# @aceshooting/lyra-ui — LLM API Reference

`@aceshooting/lyra-ui` is a free, independent, MIT-licensed [Lit](https://lit.dev) web-component
library and an open-source alternative to Shoelace and Web Awesome. It combines accessible form
controls, layout and overlay primitives, dashboards, charts, data visualization, and Conversation &
Agent UI. Selected components retain documented Web Awesome-compatible public names under a `lr-`
prefix to make migration easier, but Lyra has its own implementation, design tokens, localization
runtime, RTL behavior, and release surface. It has no runtime dependency on either project.

**This file is the whole catalog concatenated — several hundred thousand tokens.**
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) |
| 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` |
| know what to `npm install` | `llms/peers.md` |
| port `wa-*`/`sl-*` markup | `llms/migration.md` (per-tag classification, safe rewrites, and warnings) |

Prefer stable tag-shaped registration imports such as
`@aceshooting/lyra-ui/components/lr-input.js`; each registers its tag as a side effect without
coupling application code to Lyra's source-family layout. Existing family-shaped registration
paths remain supported. Class-only and helper modules continue to use their owning family paths;
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.

- **Foundation** — base class, form association, events, i18n, theming, TypeScript, frameworks, SSR, packaging (`llms/shared.md`)
- **Form controls & inputs** — 29 tags in `components/forms/`
- **Data display, dashboards & flow canvas** — 26 tags in `components/data/`
- **Layout, navigation & structure** — 36 tags in `components/layout/`
- **Overlays, status & feedback** — 21 tags in `components/overlays/`
- **Utilities, formatting & observers** — 20 tags in `components/utility/`
- **Media, files & maps** — 22 tags in `components/media/`
- **Charts** — 12 tags in `components/charts/`
- **Document & file viewers** — 23 tags in `components/viewers/`
- **Conversation & chat UI** — 34 tags in `components/conversation/`
- **Agent tooling, tool calls & evaluation** — 35 tags in `components/agent-tools/`
- **Retrieval, knowledge graph & grounding** — 30 tags in `components/retrieval/`
- **Reference tables** — design tokens (`llms/tokens.md`), optional peers (`llms/peers.md`), `wa-*`/`sl-*` migration (`llms/migration.md`)

---

# Foundation

## Component status, versioning, and deprecation

Every public `lr-*` component has an explicit status and `since` version in the package metadata.
`since` is the earliest published Lyra UI release manifest that contained the tag; for a component
introduced by the current release, it is the current package version.

- **Stable** components are supported for production use. An incompatible public API or behavior
  change requires a semver-major release.
- **Experimental** components are still open to design review, but they are not exempt from
  compatibility promises: once published, their public APIs receive the same full-semver protection
  as stable components until they are formally deprecated and removed.

Deprecation is explicit metadata, not an implication from status. Each deprecated component or
member names a replacement, a deprecation version, a rationale, and the earliest permitted removal
version. If an API is deprecated in major version M, it remains available for the complete M+1
release line and cannot be removed before M+2. This policy applies equally to stable and
experimental public APIs.

**9.0.0 took a one-time exception to that policy, and says so rather than quietly breaking it.**
Three members whose recorded removal window had genuinely opened were removed normally
(`lr-tool-call-chip`/`lr-message-parts`' `lr-tool-chip-select`, and `lr-flow-canvas`'
`--lr-flow-canvas-node-current-outline-color`). Alongside them, a small set of members that had
_never_ been deprecated were renamed and their old spellings removed in the same release, without the
customary M+1 warning period — `lr-usage-badge`'s `compact`, `lr-chart`'s `horizontal`,
`lr-rag-answer`/`lr-retrieval-results`' `error`, `lr-ingestion-queue`'s
`virtualizeThreshold` → `virtualizeAt`,
`lr-knowledge-base`'s `lr-kb-*` events, `lr-data-grid`'s `columns`/`filename` option fields, and
`lr-test-results`' two legacy detail-slot spellings, plus the component-specific
`LyraModelCatalog`/`LyraVoiceCatalog` aliases in favor of the shared `LyraCatalog<T>`. Every one has
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.

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

The major-version landmarks after 9.0.0 are:

- **10.0.0:** removed eligible members deprecated during 9.x and made the public-contract
  corrections listed in its changelog entry; follow that entry's per-member migration guidance.
- **11.0.0:** carried no known consumer-breaking change; consumers upgrading from 10.x were not
  expected to change code.
- **12.0.0:** removed the inherited static `LyraElement.getPropertyDescriptor()` surface after Lit
  deprecated that finalization hook. Ordinary component consumers need no migration; only subclasses
  that themselves overrode the hook are affected. Collection snapshot enforcement moved to a
  decorator-agnostic accessor seam instead.

### The support window

Compatibility promises are bounded by a published support window, not by "evergreen browsers":
Chromium 120+, Gecko 121+, WebKit 16.4+, and Node 20+ (ESM only; there is no CommonJS entry point).
Those floors are derived from platform features the source actually uses — `:dir()`, `:has()`,
`@container`, `color-mix()`, `ElementInternals` form association — because the package ships
untranspiled ES2022 modules with no polyfills and no build-time downleveling. There is deliberately
no `browserslist` field: it would describe a build step this package does not have. The version
floors are derived from those platform features rather than individually verified version-by-version.
Raising any floor is a semver-major change. Full policy, including the known WebKit
cross-shadow-selection gap and the
rule for when a `@supports` fallback may be dropped:
<https://github.com/aceshooting/lyra-ui/blob/main/docs/support-policy.md>.

## Importing and registering components

Every component has a stable, tag-shaped side-effect entry point that registers its own tag. Use
`components/<tag>.js`; this public boundary stays unchanged if the internal family folders move:

```js
import "@aceshooting/lyra-ui/components/lr-combobox.js"; // registers <lr-combobox>
import "@aceshooting/lyra-ui/components/lr-table.js"; // registers <lr-table>
```

The older family-shaped registration paths remain supported for compatibility. Class-only
`.class.js` entries still use their owning family path because they intentionally expose source
organization and do not register a tag.

Principal v8 and compatibility registrations use the same exact shape:

```js
import "@aceshooting/lyra-ui/components/lr-page.js";
import "@aceshooting/lyra-ui/components/lr-video.js";
import "@aceshooting/lyra-ui/components/lr-video-playlist.js";
import "@aceshooting/lyra-ui/components/lr-native-time-input.js";
import "@aceshooting/lyra-ui/components/lr-pan-zoom.js";
import "@aceshooting/lyra-ui/components/lr-split-panel.js";
import "@aceshooting/lyra-ui/components/lr-alert.js";
```

`llms/index.md` lists every tag and its owning implementation module. The stable tag-shaped alias
and the family-shaped compatibility path both resolve through the package's `./components/*`
export.

**Breaking in 8.0.0 — the package root no longer registers anything.** Through 7.x, importing the
bare `@aceshooting/lyra-ui` root had the side effect of defining every non-optional-peer tag, so a
project that only wanted a type or a helper from it silently pulled the then-current 268 component
definitions into its eager bundle. The root is now a pure, side-effect-free export surface, and the
registrations moved to an explicit entry:

```js
import "@aceshooting/lyra-ui/all.js"; // exactly the pre-8 root behaviour, opted into by name
```

_Nothing was removed from the root's named surface._ Every class, helper, and type it exported in
7.x is still exported, from the same specifier; `all.js` re-exports that identical surface, so
`import { LyraTable } from '@aceshooting/lyra-ui';` and the `@aceshooting/lyra-ui/all.js` form of it
both keep working. Only the registration side effect changed.

_Migrating._ If a bare `import '@aceshooting/lyra-ui';` (or a bundler entry that relied on it) was
how your tags got defined, add the `/all.js` specifier — a one-line change with identical behaviour.
If instead the root was only ever imported for values or types, delete nothing: those imports now
cost what they should. The symptom of a missed migration is an unupgraded element — the tag renders
as an empty inert box with its light DOM visible — not a module error, because the specifier still
resolves and still hands back everything it used to.

_Granular imports remain the recommendation._ `all.js` is a compatibility and prototyping
convenience, not the intended production shape: it is side-effectful by definition and cannot be
tree-shaken down to the handful of elements a page actually renders.

The entry points, then:

- **Class without registration.** Each entry has a `.class.js` sibling exporting the class (and the
  `HTMLElementTagNameMap` augmentation) without touching `customElements`:
  `import { LyraTable } from '@aceshooting/lyra-ui/components/data/table/table.class.js';`. Use it
  for subclassing, `instanceof` checks, or type-only imports.
- **Duplicate package copies.** Re-registering the same constructor is silent and idempotent. If a
  different Lyra constructor already owns a tag, the first definition remains active and Lyra emits
  one warning for that exact conflict with the existing/incoming package versions, constructor
  names, and both constructor references. An existing non-Lyra definition is reported with an
  `unknown` existing version rather than guessed provenance.
- **Root barrel.** `import '@aceshooting/lyra-ui';` registers **nothing** (see the 8.0.0 note
  above). It re-exports a broad compatibility surface of commonly used classes, helpers, and types,
  but it is not an exhaustive promise that every component-owned type or future export is present.
  Prefer the owning component entry in application code, both for the smallest bundle and the
  complete contract of that component.
- **`all.js` compatibility entry.** `import '@aceshooting/lyra-ui/all.js';` registers the 272
  root-included tags — everything **except** the 16 inventory-designated optional-peer-family tags:
  `lr-chart` and its 8 typed subclasses (`lr-line-chart`, `lr-bar-chart`, `lr-pie-chart`,
  `lr-doughnut-chart`, `lr-radar-chart`, `lr-polar-area-chart`, `lr-bubble-chart`,
  `lr-scatter-chart`), `lr-box-plot`, `lr-histogram`, `lr-map`, `lr-graph`,
  `lr-knowledge-graph-explorer`, `lr-geojson-view`, and `lr-geojson-viewer`. Those always need their own subpath import,
  from `all.js` exactly as from the root — the entry deliberately preserves the optional-peer
  isolation contract rather than putting `chart.js`, `maplibre-gl`, or the `d3-*` set on the
  critical path of every install. It is the one import that defeats tree-shaking.
  (Server-side, `@aceshooting/lyra-ui/ssr/all.js` is the counterpart that _does_ register the
  complete inventory, optional-peer families included; see "SSR and declarative shadow DOM".)
- **Document anchor/highlight types.** The granular document-viewer entry owns and exports
  `LyraAnchor`, `LyraAnchorKind`, `LyraHighlight`, `LyraHighlightTone`,
  `AnchorTargetCapabilities`, `HighlightActivateDetail`, `TextSelectDetail`, and
  `AnchorResultDetail`. The registration-free root now intentionally re-exports these contracts,
  together with `LyraAnchorTarget` and `LyraAnchorTargetEventMap`, and all are semver-covered:
  ```ts
  import type {
    LyraAnchor,
    LyraHighlight,
    AnchorTargetCapabilities,
  } from "@aceshooting/lyra-ui/components/viewers/document-viewer/document-viewer.js";
  ```
  Prefer the granular entry for component-local imports; use the root export when an application
  deliberately shares the contracts across several viewer integrations.
- **`lr-flag`** registers from the barrel, but resolving a flag by `country`/`language` (rather than
  a pre-resolved `src`) additionally needs
  `import '@aceshooting/lyra-ui/components/media/flag/flag-peer.js';` once.
- **Other subpaths.** `@aceshooting/lyra-ui/theme.css` (ready-made light/dark theme),
  `@aceshooting/lyra-ui/tokens-root.css` (opt-in: the curated resolved `--lr-*` tokens at `:root`,
  so your own components can read them),
  `@aceshooting/lyra-ui/native.css` (opt-in native-element styles inside `.lr-native`),
  `@aceshooting/lyra-ui/utilities.css` (opt-in light-DOM layout/text utilities),
  `@aceshooting/lyra-ui/theme.js` (the zero-dependency mode/accent runtime),
  `@aceshooting/lyra-ui/localization.js` (side-effect-free locale runtime),
  `@aceshooting/lyra-ui/autoloader.js` (side-effect-free on-demand tag loading),
  `@aceshooting/lyra-ui/autoloader-cdn.js` (browser-guarded auto-start side effect),
  `@aceshooting/lyra-ui/translations/<locale>.js` (the eleven shipped message catalogs),
  `@aceshooting/lyra-ui/events` (the global typed-event map — types only, no runtime),
  `@aceshooting/lyra-ui/ai` (provider-neutral data types), `@aceshooting/lyra-ui/testing`
  (happy-dom shims, `createLyraEvent()` for building a validated test event, a small set of
  interaction drivers that go through a component's own real activation path, and
  `waitForLyraElement()`/`waitForToast()` for awaiting a lazily registered mount),
  `@aceshooting/lyra-ui/utilities/*` (the curated shared helpers, all documented below).

### Registration-free component helpers

The following focused helpers are public, side-effect-free modules. They do not define a custom
element, so they are suitable for server code, workers, or applications that need the same data
normalization as a component without registering it:

```ts
import {
  DEFAULT_INTERNAL_PATTERNS,
  parseStackTrace,
  STACK_TRACE_LIMITS,
} from '@aceshooting/lyra-ui/components/agent-tools/stack-trace/stack-trace-parse.js';
import {
  MAX_RENDERED_LYRA_SPANS,
  normalizeLyraSpans,
} from '@aceshooting/lyra-ui/components/agent-tools/trace-tree/span.js';
import {
  agentStatusMessage,
  agentStatusVariant,
} from '@aceshooting/lyra-ui/components/agent-tools/agent-status-presentation.js';
import {
  approvalAction,
  approvalDecision,
} from '@aceshooting/lyra-ui/components/agent-tools/approval-state.js';
import { DEFAULT_WIDGET_TYPE_REGISTRY } from '@aceshooting/lyra-ui/components/conversation/widget-renderer/default-registry.js';
```

Their companion type exports remain on those same paths: stack parsing exposes `StackFrame`,
`StackGroup`, `StackTraceParseOptions`, and `StackTraceParseResult`; span projection exposes
`LyraSpan`, `LyraSpanKind`, `LyraSpanStatus`, and `LyraSpanProjection`; status and approval helpers
expose their respective presentation and decision types. The status helpers are `agentStatusKind`,
`agentStatusLabel`, `agentStatusMessage`, `agentStatusVariant`, `isAgentStatusTerminal`, and
`isAgentStatusActive`; approval also exports `ApprovalAction` and `ApprovalDecision`; span also
exports `normalizeLyraSpanKind` and `normalizeLyraSpanStatus`; the widget registry module exports
only `DEFAULT_WIDGET_TYPE_REGISTRY`. Import a component registration entry separately when the page
also renders that component.

### Optional autoloader

`@aceshooting/lyra-ui/autoloader.js` exports `discover(root?, options?)`, `start(root?, options?)`,
and `stop()`. It can load each known Lyra tag independently, allowing bundlers to split components
while granular imports remain independent. Importing this entry alone has no side effect and
registers nothing.

- `discover()` scans once. `start()` performs the same initial scan, then observes dynamic and
  Turbo-style replacement subtrees; a later `start()` stops the previous watcher. `stop()` is
  idempotent, disconnects it, invalidates pending definitions, and removes loader-owned markers.
- The optional root is a `Document`, `DocumentFragment`/open `ShadowRoot`, or `Element`; the default
  is `document`. Caller-owned open shadow roots are traversed iteratively. Each element resolves
  against its owning/scoped custom-element registry rather than an unrelated global registry.
- `maxElements` (default `10_000`), `maxRoots` (`2_000`), `maxDepth` (`256`), and `maxWork`
  (`100_000`) bound one complete discovery operation. `maxConcurrency` (`16`) bounds concurrent
  definition and first-update tasks. Invalid limits throw `RangeError`; an initial `discover()` or
  `start()` preflights its currently rendered tree and rejects a traversal-limit failure before
  loading it. Newly rendered shadow content remains under the same cumulative ceilings, but a
  failure found there necessarily follows the parent definition that rendered it.
- A discovered element carries `data-lr-autoload-pending` until its class is defined and its first
  `updateComplete` settles. The exported `AUTOLOADER_PENDING_ATTRIBUTE` is that exact string. A
  pre-existing consumer-owned marker is never removed by the loader.
- `{ events: true }` emits bubbling/composed `lr-autoload-preload`, `lr-autoload-loaded`,
  `lr-autoload-error`, and `lr-autoload-traversal-error` events on the supplied root. Detail is
  `{ tag, optionalPeers }`, plus the caught `error` for the error event. `loaded` means the registry
  definition exists; the pending marker remains authoritative until first render finishes. A
  watched insertion that exceeds a traversal ceiling emits the traversal event with
  `{ limit, maximum, error }`. A statically over-limit insertion launches no definitions from that
  insertion; a later failure in its first-update shadow content leaves the already loaded parent
  intact. Later work can still retry.
- Optional-peer tags are skipped by default. `optionalPeers: ['dompurify', 'postal-mime']` enables
  a tag only when the allowlist contains **all** packages recorded for it; `optionalPeers: 'all'`
  is for an installation that deliberately provides the entire peer set. A failed import clears
  its marker and in-flight cache, so a later scan or insertion can retry it.

```ts
import { start, stop } from "@aceshooting/lyra-ui/autoloader.js";

await start(document, {
  optionalPeers: ["dompurify", "postal-mime"],
  events: true,
});
// Later, when this application no longer owns the rendered subtree:
stop();
```

`@aceshooting/lyra-ui/autoloader-cdn.js` is the separate side-effect entry. It auto-starts only
when `document` exists and reads `data-lyra-optional-peers="peer-a,peer-b"` plus the boolean
`data-lyra-autoload-events` from its own `<script>`. Add `data-lyra-autoloader` to that script when
an ESM CDN executes the package entry behind a wrapper URL. Neither entry imports the root barrel,
and both are safe to import in plain Node.

## Collection identity

Every host-supplied collection has one explicit identity policy. An actionable or keyed collection
uses a stable, nonempty business identity and ignores malformed identities plus later duplicates
before rendering, counting, focus reconciliation, selection lookup, persistence, or event dispatch.
The first valid occurrence wins and reordering the input does not turn its array position into its
identity. When repeated values are intentionally meaningful, the component keeps them and exposes
an occurrence index in every state or event that must address one occurrence; the relevant
component section says so.

Lyra-owned controlled properties and action details name the domain instead of overloading the
platform's `HTMLElement.id`: for example `panelId`, `commandId`, `cellId`, `stepId`, `viewId`,
`attachmentId`, `cueId`, `highlightId`, and `spanId`. Controlled active/persisted fields and event
details use the same domain name. Compound identities retain every required scope field (for
example `{ invocationId, sourceKey }`). Published input-record schemas may retain an established
generic `id`/`key`/`path` spelling; the component still applies its documented uniqueness or
occurrence policy and exposes domain-named controlled state and action details.

Treat an empty or whitespace-only required identity as missing. Unless a component's contract
explicitly documents and tests an input normalization such as trimming surrounding whitespace,
Lyra does not rewrite a valid retained identity merely to validate it. When normalization is part
of that contract, the normalized value is the identity used consistently for duplicate detection,
selection, persistence, keyed DOM ownership, and event details. Assign a new collection when the
data changes, and keep the business identity stable across object replacement so those consumers
continue to follow the same logical record.

## Events

Lyra-specific events are `lr-`-prefixed `CustomEvent`s (`lr-change`, `lr-input`, `lr-select`, …),
dispatched through `LyraElement`'s `protected emit<T>(name, detail?, options?)`: **bubbling,
composed, and non-cancelable by default**, with the payload on `event.detail`. A component that
offers a genuine veto point opts into `{ cancelable: true }` and checks `defaultPrevented` before
acting (as `lr-export` does) — that is called out per component. Native wrappers may additionally
relay unprefixed `Event`, `InputEvent`, or `FocusEvent` instances; each component section documents
the exact native names, constructors, bubbling, and cancelability it supports.

Never assume a native DOM event name works: a component mirrors a native contract only where its own
section says so. `preventDefault()` on a non-cancelable event does nothing.

Every one of those names is also typed — per component through its own event map, and globally
through `@aceshooting/lyra-ui/events` for listeners on an ancestor, `document` or `window`. See
"TypeScript" below.

## TypeScript

- **Per-component event maps.** Every component with events exports a `Lyra<Name>EventMap` type, and
  `LyraElement<Events>` declares a typed `addEventListener` overload — so `event.detail` is inferred
  with no cast:
  ```ts
  import { LyraTable } from "@aceshooting/lyra-ui/components/data/table/table.class.js";
  const table = document.querySelector("lr-table") as LyraTable;
  table.addEventListener("lr-sort", (event) => event.detail.key); // typed
  ```
- **`HTMLElementTagNameMap`** is augmented in the `.class.d.ts` files. `document.querySelector('lr-table')`
  is only typed as `LyraTable` when that class module is in the type graph — importing just the
  registration entry (`table.js`) also pulls it in, since the entry re-exports the class module.
- **Generics.** Row/item-carrying components are generic over their data type
  (`LyraTable<T>`, `LyraTableEventMap<T>`, …); annotate the element to keep `detail` payloads typed.
- **Setting object properties from templates** requires a property binding, never an attribute —
  see "Framework integration".
- **Framework template declarations are opt-in.** Import exactly the declaration entry your
  compiler uses once in its type graph:
  ```ts
  import type {} from "@aceshooting/lyra-ui/custom-elements-jsx"; // React 19 / JSX
  import type {} from "@aceshooting/lyra-ui/vue";
  import type {} from "@aceshooting/lyra-ui/svelte";
  ```
  All three are generated from `custom-elements.json` and type the documented properties,
  attribute aliases, events, element refs, and CSS custom properties. Their emitted JavaScript is
  empty: they are declaration merging, not runtime wrappers, and they do not register any tag.
- **Delegated, `document` and `window` listeners: `@aceshooting/lyra-ui/events`.** Component events
  bubble and are composed, so they reach ancestors, `document`, and `window` — but a listener
  attached _there_ has no element type to key off and would otherwise receive a bare `Event`. This
  subpath declares `LyraGlobalEventMap` (all generated Lyra event names) and mixes it into
  `GlobalEventHandlersEventMap`, which types `element`, `document` and `window`
  `addEventListener` calls alike:

  ```ts
  import "@aceshooting/lyra-ui/events";

  document.addEventListener("lr-sort", (event) => event.detail); // typed on document
  ```

  It is **opt-in**: the augmentation only applies once that import is somewhere in the project's
  type graph, so add it once (a root `main.ts`, or a `.d.ts` in the project's `include`). A direct
  element reference never needs it — `LyraElement` overrides `addEventListener`, so
  `table.addEventListener('lr-sort', …)` resolves through `LyraTableEventMap` first either way.
  `LyraGlobalEventMap` is exported as well, for writing your own typed helper over it.

- **The surface is per-event type aliases, not runtime event classes.** `LyraSortEvent` and its
  generated siblings are `type` aliases over the owning component's own map entry
  (`LyraTableEventMap['lr-sort']`) — there is nothing to `new`, and `instanceof LyraSortEvent` is
  not a thing. The module compiles to `export {};`: shipping runtime event subclasses to type a
  listener would cost every consumer runtime bytes for a compile-time concern, so it deliberately
  costs zero.
- **A shared event name narrows to the union of its dispatchers.** One name can come from several
  components with different details — `lr-select` from five, `lr-selection-change` from five — so
  its global entry is the _union_ of their entries, and `event.detail` there exposes only what all
  of them share. Index the owning component's own map when you need one component's exact detail:

  ```ts
  import type { LyraCommandPaletteEventMap } from "@aceshooting/lyra-ui/components/layout/command-palette/command-palette.class.js";

  type PaletteSelect = LyraCommandPaletteEventMap["lr-select"]; // the precise detail
  ```

  Native-named events some form controls re-emit (`blur`, `change`, `focus`, `input`) are
  deliberately **absent** from the global map — they already exist in the DOM's own event maps with
  their standard types, and redeclaring them globally would widen a built-in. Those stay typed
  through the component's own event map.

## Form association

`FormAssociated(Base)` (`@aceshooting/lyra-ui/utilities/form-associated.js`) makes a `LitElement`
form-associated: `static formAssociated = true` plus a descriptor-safe `attachInternals` lookup in
the constructor, which eagerly calls
`internals.setFormValue('')` so an untouched control is present in `FormData` as `""` from
construction — matching native `<input>` — instead of being absent.

It adds `name: string`, a non-reflecting live `value: string`, reflected
`defaultValue: string` (attribute `value`), `customError: string | null` (attribute
`custom-error`), `disabled: boolean` (reflected), and `required: boolean` (reflected). These use
hand-written accessors declared with Lit's `noAccessor`, so attribute writes and `internals` calls
happen synchronously rather than waiting for Lit's update cycle.

Mapped controls accept `null` as a setter-only clearing input without changing their getter types:
`.name = null` removes the name and reads back as `''`. The controls that publish a mapped nullable
`value` setter are listed in each control's component reference; ordinary string values clear to `''`, while checkbox
and switch values restore the native `'on'` default and remove their `value` attribute. An explicit
non-null `'on'` reflects `value="on"`. This is a property-assignment spelling only — never write
`name="null"` or `value="null"` in markup.

Every form-associated control exposes element-valued reads from `form` and `getForm()`, plus
`labels`, `validity`, `validationMessage`, `willValidate`, and `effectiveDisabled`. The `form`
setter accepts an owner id, an identified `HTMLFormElement`, or `null`; it reflects/removes the
host's `form` attribute while subsequent reads still return the browser-resolved form element.
Methods include `checkValidity()`, `reportValidity()`, and `setCustomValidity()`.

Native external labels work across the shadow boundary for every form-associated Lyra control:

```html
<label for="display-name">Display name</label>
<lr-input id="display-name" name="displayName"></lr-input>
```

The label text names the internal role owner, and clicking the label focuses text/select-like
controls or activates toggle/button-like controls exactly once. The relationship stays live when
labels are inserted, removed, retargeted, or edited. A host `aria-label` always wins. Compound
controls such as `lr-tool-param-form`, `lr-rubric-form`, and `lr-time-range` put that aggregate name
on an internal `role="group"` while retaining the more specific names of their fields/handles.
Disabled controls, including controls disabled by an ancestor `<fieldset disabled>`, ignore label
activation.

- **Read `effectiveDisabled`, not `disabled`, for the merged state.** `effectiveDisabled` is own
  `disabled` OR an ancestor `<fieldset disabled>`'s cascaded state.
  `formDisabledCallback(fieldsetDisabled)` stores the ancestor state privately, so `disabled` always
  reflects only the consumer's own attribute/property, as native `<input>` does.
- **Validity is real.** `updateValidity()` calls `internals.setValidity({ valueMissing: true }, …)`
  whenever `required` is set and `value === ''`, re-run on every `value`/`required` change and once
  from `connectedCallback()` — so `checkValidity()`/`reportValidity()`/`:invalid`/`:user-invalid`
  reflect actual constraint state.
- **`setCustomValidity(message: string): void`** — the consumer channel for an error no client-side
  constraint can express: a server-side rejection ("that email is already registered"), a
  cross-field rule, a business constraint. A non-empty `message` raises `customError` and becomes
  `validationMessage`, so the control fails `checkValidity()`, blocks submission, and matches
  `:invalid`; `''` clears it. Every value-carrying form-associated control in the library exposes
  it, mixin-based or not.
  ```ts
  const email = document.querySelector("lr-input")!;
  email.setCustomValidity("That address is already registered.");
  form.requestSubmit(); // blocked; the browser reveals this message
  email.setCustomValidity(""); // cleared
  ```
  The method, reflected `customError` property, and `custom-error` attribute are one atomic state:
  a non-empty method/property write reflects the same message, while `setCustomValidity('')`,
  `resetValidity()`, `customError = ''`, or `customError = null` clears validity and removes the
  attribute. Serialized or cloned markup therefore cannot resurrect a message already cleared at
  runtime.
  Two behaviors are inherited verbatim from native controls and are the ones worth knowing.
  **Clearing restores computed validity rather than forcing the control valid** — a
  required-and-empty field whose custom error is cleared is still `valueMissing`. And **the custom
  error outlives everything except another `setCustomValidity('')`**: it survives each intrinsic
  recomputation (every `value`/`required` change re-runs one) and survives `form.reset()`. Clear it
  yourself when the condition that raised it goes away. The message is your content, so it is
  emitted verbatim and never localized — pass a string already in the user's language.
- **`customError` and `lr-invalid`.** Assigning `customError` is the reflected property form of
  `setCustomValidity()`; assign `null` to clear it and remove `custom-error`. Whenever the native
  non-bubbling `invalid` event fires, the host also emits exactly one bubbling, composed
  `lr-invalid` alias with no detail.

  **`lr-invalid` is cancelable, and cancelling it cancels the native event too.** It is one of the
  library's few real veto points: `event.preventDefault()` on `lr-invalid` forwards the cancellation
  to the platform `invalid` event that triggered it, which suppresses that event's default —
  the browser's own validation bubble, and the focus/scroll `reportValidity()` performs on the first
  invalid control. That is what lets an app render its own error banner from `lr-invalid` without the
  native UI appearing alongside it. Nothing else changes: the control is still invalid, still fails
  `checkValidity()`, and still blocks submission.

  ```ts
  form.addEventListener("lr-invalid", (event) => {
    event.preventDefault(); // no native bubble, no auto-scroll
    showMyOwnErrorSummary(event.target as HTMLElement);
  });
  ```

  Leave it uncancelled to keep the platform behavior. The listener has to be attached before the
  validity check runs (`lr-invalid` bubbles and composes, so the form or `document` is a fine place);
  a `preventDefault()` after the fact does nothing.

- **Validation anchoring.** An internal controller passes
  `internals.setValidity(flags, message, anchor)` with `anchor` = the first focusable descendant in
  the shadow root (`input:not([type='hidden']), textarea, select, button, [tabindex]:not([tabindex='-1'])`),
  re-resolved after each render — the browser cannot focus the non-focusable custom-element host when
  native validation UI tries to reveal the invalid control.
- **Live/default dirty semantics.** A `.value` write changes only the live value and marks it dirty;
  it never reflects the `value` attribute. Declarative markup, `defaultValue`, or a later
  `setAttribute('value', …)` updates the current reset default and updates the live value only while
  it is still pristine. `form.reset()` restores that current default and clears the dirty flag.
  `formStateRestoreCallback()` restores string state synchronously without emitting a user event.
- **Who uses the mixin.** Ten classes take it directly — `lr-input` (and its `lr-number-input` /
  `lr-time-input` subclasses), `lr-textarea`, `lr-code-editor`, `lr-otp-input`, `lr-color-picker`,
  `lr-emoji-picker`, `lr-date-input`, `lr-phone-input`, `lr-chat-composer`, and
  `lr-known-date`. Controls with non-string values or markup-derived defaults hand-roll an
  equivalent with the same `setValidity`/default-capture behavior — `lr-slider` because its value
  is numeric (and its range submission has two entries), `lr-combobox` because its value
  can be an array in `multiple` mode, `lr-select` because its default comes from a `selected`
  `<lr-option>` rather than a `value` attribute. Divergences are documented per component.
  `lr-button` is form-associated only to act as a submit/reset control: it carries no value and no
  validity. `lr-icon-button` is deliberately an action/link primitive rather than a form-associated
  submitter; use an icon-only `lr-button` when the action must submit or reset a form.
  `lr-time-range` is form-associated only for fieldset-cascaded disablement: no submission value,
  no state restoration.

### Enter submits the form

A native `<input>` submits its form owner when the user presses Enter. The `<input>` these controls
render has no form owner at all — it lives in a shadow tree, and only the _host_ element
participates in the light-DOM `<form>` — so the platform can never run implicit submission for it,
and Enter in a text field would silently do nothing, which reads as a broken form. Text-entry
controls implement it themselves, to the platform's rules rather than an approximation of them:

- **Modifiers disqualify the keystroke.** `Ctrl`/`Cmd`/`Alt`/`Shift`+Enter is an application
  shortcut (send-and-keep-open, insert-newline, open-in-new-tab), never implicit submission.
- **An IME composition Enter is not a submit.** Enter commits the highlighted candidate in
  Japanese/Chinese/Korean input; submitting there throws away the word being typed.
- **A `keydown` a listener above already `preventDefault()`ed stays vetoed** — an open suggestion
  panel committing a selection, or your own shortcut, keeps the keystroke.
- **The submitter is resolved, not skipped.** The form's default button — the first enabled submit
  control in `form.elements` — is used as the submitter, so `SubmitEvent.submitter`, that button's
  own `name`/`value` entry, and its `formaction`/`formmethod`/`formnovalidate` overrides all
  survive. An `<lr-button type="submit">` is activated through its own `click()`, since a
  form-associated custom element is never a legal `requestSubmit()` submitter.
- **A submit-button-less form submits only from a single field**, matching the platform's rule that
  a form with no default button refuses implicit submission when more than one text-entry field
  blocks it.
- **Validation still runs.** Submission goes through `requestSubmit()`, never `submit()`, so an
  invalid field blocks it exactly as a real submit button would.

**Deliberately not wired everywhere**, because Enter already means something else: `lr-textarea` and
`lr-code-editor` insert a newline (the whole point of a multi-line surface); `lr-select`'s trigger is
a `role="combobox"` where Enter opens the listbox and then commits the active option, per the ARIA
combobox pattern; `lr-date-picker` selects the focused day. A `disabled` or `readonly` control stays
inert either way.

## CSS custom states

Every value-carrying form-associated control publishes its validation state as CSS custom states, so
a light-DOM stylesheet can react to validity without reaching into a shadow root or mirroring the
state onto an attribute of your own:

```css
lr-input:state(user-invalid)::part(input-wrapper) {
  border-color: var(--lr-color-danger-border-loud);
}
```

Six states, in three pairs:

| State                         | Matches when                                           |
| ----------------------------- | ------------------------------------------------------ |
| `required` / `optional`       | the control's `required` is set / is not set           |
| `valid` / `invalid`           | `validity.valid` is `true` / `false`                   |
| `user-valid` / `user-invalid` | the same, **and** the control has been interacted with |

Exactly one of the first two pairs matches at any moment. The third is the one that differs:
**before the control has been interacted with, neither `user-valid` nor `user-invalid` matches** —
and that is precisely what makes the pair worth having. A pristine required field is genuinely
`invalid` from the moment it connects, so a rule on `:state(invalid)` paints an untouched form red
before the user has typed anything; the same rule on `:state(user-invalid)` waits.

"Interacted with" means an `input`, `change` or blur on that control, or a `reportValidity()`
call — which is what a submit attempt runs, so a failed submit switches the `user-*` states on for
every field that failed. `form.reset()` makes the control pristine again and they stop matching.
`setCustomValidity()` participates like any other constraint: raising a custom error flips `invalid`
immediately, and `user-invalid` too if the control has already been touched.

**A control barred from constraint validation publishes neither `valid` nor `invalid`** — and
therefore neither `user-valid` nor `user-invalid`. "Barred" is the platform's own term and the
platform's own list: the control's own `disabled`, an ancestor `<fieldset disabled>`, `readonly`
where the control has it, or anything else that makes `willValidate` false. A native
`<input required disabled>` matches neither `:valid` nor `:invalid`, and these states match native.
This matters because the idiomatic rule is written against the _tag_:

```css
lr-input:state(user-invalid)::part(input-wrapper) {
  border-color: var(--lr-color-danger-border-loud);
}
```

A disabled required field that still published `invalid` painted every greyed-out control in the
form red. `required`/`optional` are unaffected — they describe the attribute, not the validation
outcome, so they keep publishing exactly like native `:required`/`:optional`, and a disabled
required field still matches `:state(required)`. Style the barred case through
`:state(disabled)`/`:disabled` and `:state(readonly)`, not through the validity pair.

The states are published the same way whether a control uses the `FormAssociated` mixin or drives
`ElementInternals` directly, so a rule written against `lr-input` behaves identically on
`lr-checkbox`. `lr-button` is the form-associated exception noted above: it has no value and
therefore no validity to publish. `lr-icon-button` is not form-associated at all. Where an engine
cannot register a custom state, the styling hook is simply absent — validity, submission blocking
and `checkValidity()`/`reportValidity()` are unaffected, so never make a `:state()` rule the only
signal that a field is wrong.

## The required-field marker

A labelled control with `required` set paints a marker after its label text — by default ` *` in
`--lr-color-danger`. It is one shared contract and, with one fieldset-specific exception, one shared
rule rendered as an `::after` on the `form-control-label` part: the labelled form controls, plus
`lr-file-input`, `lr-model-select`, `lr-voice-picker`, and `lr-tool-param-form`, which marks its
_per-field_ labels the same way. `lr-known-date` reads the same three properties but paints the
marker on its `legend` box, after the complete label; its `form-control-label` part owns only the
label content and cannot retheme that marker. A control with no
`form-control-label` part — `lr-checkbox`, `lr-switch`, `lr-radio`, whose default slot _is_ the
visible label — has no label box to hang a marker on and paints none; a control that renders the
part with no label text set paints none either, so no stray glyph is ever orphaned.

Three custom properties control it. Each is read as an inline `var()` fallback at the point of use,
never declared on `:host`, so setting one on **any ancestor** of the control reaches it — and one
declaration on `:root` retunes every marker in the application at once:

| Property                             | Default                  | What it does                                                                                                 |
| ------------------------------------ | ------------------------ | ------------------------------------------------------------------------------------------------------------ |
| `--lr-form-control-required-content` | `' *'`                   | The marker itself, as a CSS `content` string. Must be _quoted_.                                              |
| `--lr-form-control-required-color`   | `var(--lr-color-danger)` | The marker's colour, independent of every other danger surface.                                              |
| `--lr-form-control-required-offset`  | `0`                      | Inline space between the label text and the marker (a logical `margin-inline-start`, so it flips under RTL). |

```css
/* mark the requirement in words, in the page's language */
:root {
  --lr-form-control-required-content: " (required)";
  --lr-form-control-required-color: var(--lr-color-text-quiet);
  --lr-form-control-required-offset: var(--lr-space-2xs);
}

/* or suppress the marker entirely and rely on your own label copy */
lr-input.no-marker {
  --lr-form-control-required-content: "";
}
```

Three things follow from `content` being a consumer-supplied string:

- **It is never localized by the library.** `localize()` covers strings the library authors; this
  one is yours, so a translated marker (` (obligatoire)`, ` (必須)`) is set per locale by the
  application — one declaration on the root element beside whatever else the locale switch changes.
- **The default's leading space is part of the glyph**, which is why
  `--lr-form-control-required-offset` defaults to `0`. A replacement string that omits the space
  should set an offset rather than baking one in, so the spacing stays a length.
- **Suppressing the marker is a styling change, not a semantic one.** `required` still reflects,
  still reaches the accessibility tree through the control's own `aria-required`, still publishes
  `:state(required)`, and still fails `valueMissing`. If the marker is the only way a form
  communicates requiredness, replace it with visible copy rather than removing it.

## Presenting hint text as a compact disclosure

Every form control's `hint` chrome (props + matching named slot + `hint` CSS part, the same shape
`<lr-select>` documents) renders as permanent text under the control. **There is no
`hint-display`/`hint-placement` attribute anywhere in the library, on any control, and none is
planned** — a compact icon-triggered presentation is a composition you build from existing pieces,
not a built-in render mode. Permanent text is also the reason a hint reads reliably across a form in
the first place: a control that silently switched between "text under the control" and "icon that
opens a popup" from one attribute would desync sibling field heights at exactly the moment it
removed the visual cue that anything had changed.

The recipe: compose an icon-only `<lr-icon-button>` inside an `<lr-tooltip>` — or `<lr-details>` for
an inline expand/collapse instead of a hover/focus popup — and slot the pair into the control's
`label` slot, beside its regular label text. This works on every control shipping that label/hint
slot pair (`lr-input`, `lr-textarea`, `lr-select`, `lr-combobox`, `lr-number-input`, `lr-date-input`,
and siblings). Keep the same copy in the control's own `hint` slot as well, wrapped in the
`lr-visually-hidden` utility class (opt into it with `@import "@aceshooting/lyra-ui/utilities.css";`
— see "Optional native styles and CSS utilities" below): that keeps the text wired into the
control's `aria-describedby`, which is the entire reason the built-in `hint` chrome exists, while
removing its visible, height-affecting rendering. The compact trigger is additive to that
description, not a replacement for it — `<lr-tooltip>` separately gives its own trigger (the icon
button) an accessible description built from the tooltip's content while open, which is a second,
narrower win: it reaches only the icon button's own focus, not the field's `aria-describedby` chain,
which is exactly why the visually-hidden copy in `hint` still matters.

```html
<lr-input label="API key" name="apiKey">
  <lr-tooltip
    slot="label"
    content="Used to authenticate requests server-side. Rotate it if it leaks."
  >
    <lr-icon-button
      icon="info-circle"
      label="More info about API key"
    ></lr-icon-button>
  </lr-tooltip>
  <span slot="hint" class="lr-visually-hidden"
    >Used to authenticate requests server-side. Rotate it if it leaks.</span
  >
</lr-input>
```

```js
import '@aceshooting/lyra-ui/components/lr-input.js';
import '@aceshooting/lyra-ui/components/lr-tooltip.js';
import '@aceshooting/lyra-ui/components/lr-icon-button.js';
```

`icon="info-circle"` above illustrates the pattern; `<lr-icon>`'s own built-in glyph set has no info
symbol (see `llms/components/lr-icon.md` for the exact list), so register a real icon library with
`registerIconLibrary()`, set `library` alongside `icon`, or slot custom SVG geometry into the icon
button's own default slot instead.

`lr-checkbox` and `lr-switch` have no separate `label` slot — their default slot _is_ the clickable
label — so there is nowhere inside either control to slot the trigger into. Render it as a DOM
sibling instead, still paired with a visually-hidden copy inside the control's own `hint` slot:

```html
<span class="lr-cluster lr-items-center lr-gap-xs">
  <lr-checkbox name="marketingOptIn">
    Send me product updates
    <span slot="hint" class="lr-visually-hidden">We email at most once a month.</span>
  </lr-checkbox>
  <lr-tooltip content="We email at most once a month.">
    <lr-icon-button icon="info-circle" label="More info about product updates"></lr-icon-button>
  </lr-tooltip>
</span>
```

## The shared styling vocabulary

Four property names carry one meaning library-wide, so a value learned on one component transfers to
every other component that takes it. Each component's own section lists which it accepts and what it
defaults to; the meanings are fixed here.

- **`variant` — semantic tone, and only tone.** `neutral | brand | success | warning | danger`.
  It selects one row of the semantic colour grid below and changes nothing else: not shape, not
  density, not how much of the control is filled in. Nothing in the library spells this concept
  `tone` or `kind`.
- **`appearance` — how a control fills itself, and only that.**
  - `accent` — the loud semantic fill, for the one primary action in a view
  - `filled` — a quiet tint of the same tone, for secondary actions
  - `outlined` — a border with no fill
  - `filled-outlined` — both, for a control that must read as bounded on a busy surface
  - `plain` — neither; text and icon only
- **`frame` — how a container draws its own bounds.** `card | plain`: a bounded, elevated card, or
  dissolved into the surrounding layout. This is a _separate_ property from `appearance` on
  purpose — the two used to share one name for two unrelated jobs, so `appearance="plain"` meant
  "no fill" on a control and "no card chrome" on a panel.
- **`size` — one ladder: `2xs | xs | s | m | l | xl`, defaulting to `m`.** `small`/`medium`/`large`
  are accepted **everywhere** `s`/`m`/`l` are — the Web Awesome and Shoelace spellings, so migrating
  from either is a tag rename with no attribute rewrite. Neither spelling is normalised away in JS;
  the CSS matches both, so `size="medium"` and `size="m"` are the same control and `el.size` reads
  back whatever you assigned.

Every tier resolves through one set of `--lr-form-control-*` knobs — `height`, `font-size`,
`padding-inline`, `padding-block`, `gap`, `radius`. Only `height` and `radius` chain to a matching
`--lr-theme-form-control-*` input (`--lr-theme-form-control-height-2xs`…`-xl` and
`--lr-theme-form-control-radius`); `font-size`, `padding-inline`, `padding-block` and `gap` read the
shared `--lr-font-size-*`/`--lr-space-*` scale directly and have no per-control theme input of their
own. So a button, an input, a select and a combobox at the same tier line up in a toolbar row, and
an application can retune the whole control scale's height and corner radius from one place without
touching a component; retuning font size or padding means changing the shared type/space tokens
instead.

These are exported TypeScript **type aliases**, never `enum`s: an `enum` is nominal, so
`el.variant = 'brand'` would stop type-checking, and it emits a runtime object that costs bytes in a
library whose delivery promise is tree-shaking. Each component's class module re-exports the exact
vocabulary it accepts (for example, `ButtonVariant` or the shared `LyraFrame`), so a consumer never
needs a separate types import.

A small number of components use `variant` for a rendering _mode_ rather than a tone — the shape a
visualizer draws, the skeleton a placeholder mimics. Those unions are component-specific and are
spelled out in that component's own section; the tone vocabulary above is what `variant` means
everywhere a tone is what the property is for.

## Theming and design tokens

Three layers, and **which one you set decides how far the override reaches**:

1. **`--lr-theme-*`** — the application input layer. `theme.css` supplies values on its root and
   light/dark mode selectors; component shadow styles never redeclare them. Set these to retheme.
2. **`--lr-*`** — internal tokens. Themeable base tokens read a `--lr-theme-*` input and use a
   built-in fallback when it is unset. Aliases, computed tokens, and the colour ramp may instead
   resolve through another internal token or a fixed contract value. See
   [the colour ramp and the semantic grid](#the-colour-ramp-and-the-semantic-grid) for how a colour
   resolves through this layer.
3. **`--lr-<component>-*`** — per-component properties, for one element at a time. Listed in each
   component's own section.

**Layer 2 (`--lr-*`) is declared only on each `lr-*` element's own shadow `:host`.** It never
reaches plain application CSS, and it never reaches your own custom elements, since neither is a
descendant of an `lr-*` shadow root — `body { color: var(--lr-color-text) }` in application CSS
resolves to nothing, silently, not an error. Retheme through layer 1 (`--lr-theme-*`), which
`theme.css` supplies at document scope and which inherits normally into every nested shadow root.
To _read_ (not retheme) the resolved values from your own components, import the opt-in
[`tokens-root.css`](#reading-the-resolved-tokens-from-your-own-components--tokens-rootcss), which
declares a curated subset of layer 2 at `:root`.
See [Where an override actually reaches](#where-an-override-actually-reaches) below for the full
inheritance rules, including the one documented exception (per-component `--lr-<component>-*`
hooks, layer 3, which do inherit through wrappers).

### Reading the resolved tokens from your own components — `tokens-root.css`

The paragraph above is a real problem for any application that has custom elements of its own: they
are not descendants of an `lr-*` shadow root either, so `var(--lr-color-border)` inside **your**
component resolves to nothing, and `var(--lr-space-m, 0.5rem)` quietly runs on its literal fallback
forever. Both failures are invisible without reading computed styles in a browser.

Import one optional stylesheet and the curated part of layer 2 exists at document scope:

```css
@import "@aceshooting/lyra-ui/theme.css"; /* the --lr-theme-* input layer */
@import "@aceshooting/lyra-ui/tokens-root.css"; /* the resolved --lr-* layer, at :root */
```

```css
/* Now valid in your own component's stylesheet, in plain application CSS, anywhere. */
.app-panel {
  padding: var(--lr-space-m);
  border: var(--lr-border-width-thin) solid var(--lr-color-border);
  border-radius: var(--lr-radius);
  background: var(--lr-color-surface-raised);
  color: var(--lr-color-text);
  font-family: var(--lr-font);
}
.app-panel:focus-visible {
  outline: var(--lr-focus-ring);
  outline-offset: var(--lr-focus-ring-offset);
}
```

**It is opt-in, and it is a curated subset — not all of layer 2.** `--lr-*` is internal precisely so
it can change without a major version; publishing all of it at `:root` would freeze several hundred
internal decisions as permanent API. What ships is what an application's own component needs to sit
inside a Lyra UI without looking foreign:

| Family                | Names                                                                                                                                                                                                                     |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Ambient colour        | `--lr-color-surface`, `--lr-color-surface-raised`, `--lr-color-surface-overlay`, `--lr-color-overlay`, `--lr-color-text`, `--lr-color-text-quiet`, `--lr-color-border`, `--lr-color-border-strong`                         |
| The semantic grid     | all 45 `--lr-color-{brand,success,warning,danger,neutral}-{fill,border,on}-{quiet,normal,loud}` slots                                                                                                                       |
| Flat colour aliases   | `--lr-color-{brand,success,warning,danger,neutral}`, `--lr-color-{brand,success,warning,danger}-quiet`, `--lr-color-on-{brand,success,warning,danger,neutral}`                                                              |
| Spacing               | `--lr-space-2xs`, `--lr-space-xs`, `--lr-space-s`, `--lr-space-m`, `--lr-space-l`, `--lr-space-2xl`                                                                                                                        |
| Geometry              | `--lr-radius-xs`, `--lr-radius`, `--lr-radius-pill`, `--lr-border-width-thin`, `--lr-border-width-medium`, `--lr-border-width-thick`                                                                                       |
| Elevation             | `--lr-shadow-color`, `--lr-shadow-xs`, `--lr-shadow-s`, `--lr-shadow-m`, `--lr-shadow-l`, `--lr-shadow-xl`, `--lr-shadow`                                                                                                  |
| Typography            | `--lr-font`, `--lr-font-mono`, the ten `--lr-font-size-*` steps, the four `--lr-font-weight-*` steps                                                                                                                        |
| State and motion      | `--lr-focus-ring`, `--lr-focus-ring-color`, `--lr-focus-ring-width`, `--lr-focus-ring-offset`, `--lr-opacity-disabled`, `--lr-opacity-muted`, `--lr-duration-fast`, `--lr-duration-base`, `--lr-easing-standard`, `--lr-easing-emphasized`, `--lr-transition-fast`, `--lr-transition-base`, `--lr-transition-interactive` |

The grid ships whole because its contrast guarantee is **per tier** — a `fill-quiet` background is
only guaranteed legible under the matching `on-quiet` foreground — so shipping the flat aliases
alone would hand you a pairing with nothing behind it.

**Deliberately not published**, and each for a reason that makes reading it a bug rather than a
convenience: `--lr-ramp-*` (a step encodes a light-mode choice and has no theme hook),
`--lr-size-*` (value-named geometry constants, frozen internals), the chart, graph and terminal
palettes (generated ramps that move with the palette tooling), `--lr-layer-*` (stacking order is
your decision), `--lr-color-mix-*` and `--lr-hover-brightness` (inputs to the library's own
interaction recipe), `--lr-line-height-*`, the per-control internals (`--lr-icon-button-size`,
`--lr-otp-input-segment-size`, `--lr-scroll-fade-size`, `--lr-popover-viewport-clamp`,
`--lr-safe-area-*`, `--lr-mask-opaque`, `--lr-color-no-data`), and the nine variant-following slots
(`--lr-color-fill-loud` and friends), which mean "the variant _this_ element is set to" and are
meaningless on `:root`. If you need one of these, ask for it to be added rather than reading it out
of a component's shadow root.

**Stability promise.** Every name in the table is public API from the release that introduced it: it
will not be renamed or removed outside a major version, and its meaning will not change. Its _value_
may change in a minor exactly as it may inside a component — a palette retune moves your elements
and the kit's together, which is the point. Names absent from the file stay internal and may change
in any release.

**Modes work the way the components' do.** Light on `:root` and on `.lr-light` /
`[data-lr-theme="light"]`, dark under `prefers-color-scheme: dark` (unless an explicit light scope
opts out) and on `.lr-dark` / `[data-lr-theme="dark"]`, plus the same `forced-colors` and
`prefers-reduced-motion` overrides the components apply — and those two reach you on **every** one
of those routes, including a dark OS with no explicit scope, because they repeat the compound
`:root:not(.lr-light):not([data-lr-theme="light"])` selector the dark route uses rather than a bare
`:root` that the dark route would out-specify. Every declaration keeps its `--lr-theme-*`
input in front of a resolved fallback, so `theme.css` and your own overrides still win here exactly
as they do inside a component.

**One caveat, and it is the same shape as layer 2's rule everywhere else.** A `--lr-theme-*` input
set on a mid-tree element retunes every `lr-*` component below it, because each component re-derives
the resolved layer on its own `:host`. The document-scope copy cannot: it is substituted where it is
declared, and what inherits past that point is the finished value. So if an application element
carries a subtree override and expects its **own** descendants to follow, give that element a mode
scope too — `class="lr-light"`, `class="lr-dark"`, or `data-lr-theme` — which is what the file's
mode rules key on, and the whole subset resolves again there:

```html
<!-- Both the lr-* components and the app's own elements below follow the override. -->
<section class="lr-light" style="--lr-theme-color-brand-fill-loud: #7c3aed">…</section>
```

Everything sits in the `lr-theme` cascade layer, like `theme.css`, so any unlayered application rule
beats it regardless of load order, and the file declares custom properties only — notably not
`color-scheme` — so importing it paints nothing by itself. `--lr-focus-ring` and its three parts are
also declared at document scope by `theme.css`; both spell the same chain, so importing both is a
no-op either way round.

### The colour ramp and the semantic grid

Colour has two layers beneath the `--lr-*` tokens you normally read.

**The ramp — `--lr-ramp-<variant>-<step>`.** Five variants (`brand`, `success`, `warning`,
`danger`, `neutral`) × eleven steps (`05 10 20 30 40 50 60 70 80 90 95`). The step number is
approximate perceptual lightness: `-05` is nearly black, `-95` nearly white, `-50` the mid tone. The
ramp is generated in OKLCH, so the same step number reads as the same _apparent_ lightness across
every variant — which is what makes the grid above it predictable rather than 45 separate
decisions.

**Never reference a ramp step directly — from application CSS or from a component's own styles.**
Two reasons, and both fail silently. A step encodes a light-mode choice: `-50` is a comfortable fill
on white and unreadable on a dark surface, so a rule written against it looks correct until someone
switches modes. And the ramp carries no `--lr-theme-*` hook and is re-declared on every `lr-*`
element's own `:host`, so a `:root { --lr-ramp-brand-50: … }` in an application stylesheet is
shadowed at the first component it reaches and changes nothing at all. Read the grid instead; it
picks the right step per mode for you, and it is the layer that _is_ overridable.

**The grid — `--lr-color-<variant>-<role>-<emphasis>`.** `{brand|success|warning|danger|neutral}` ×
`{fill|border|on}` × `{quiet|normal|loud}` = 45 slots. This is the layer components consume and the
layer to build on. Its _shape_ is identical in light and dark; only which ramp step each slot
resolves to changes, so a rule written against it is mode-independent for free.

- `fill` — a background. `on` — text and icons that sit **on** the matching `fill`. `border` — an
  outline.
- `emphasis` runs `quiet → normal → loud`. Louder means more prominent, not lighter or darker: in
  light mode it descends the ramp and in dark mode it climbs it.

**The contrast guarantee is what makes the grid usable without thinking.** For every variant, in
both modes: `on-<e>` clears WCAG 1.4.3's 4.5:1 against `fill-<e>` at the _same_ emphasis — so
`background: var(--lr-color-danger-fill-loud); color: var(--lr-color-danger-on-loud)` is legible by
construction, and no other pairing is promised. `border-normal` and `border-loud` clear 1.4.11's
3:1 against the page surface, so a control's visible bounds are always discernible. `border-quiet`
is deliberately exempt: it exists for decoration that is not load-bearing — a rule between table
rows, a hairline inside an already-bounded card — so never use it as a control's only boundary.
These guarantees apply in both modes.

**Every slot has its own `--lr-theme-*` override**, named after the slot, so one decision can be
rethemed without forking anything beneath it:

```css
/* Both the grid slot and the flat alias below now resolve to this. */
.invoice-panel {
  --lr-theme-color-brand-fill-loud: #7c3aed;
}
```

The full chain for one colour is therefore: your `--lr-theme-*` input, else the grid slot's default,
else the ramp step it points at. To move a whole tone, set its nine `--lr-theme-color-<variant>-*`
inputs — that is the wholesale route, since the ramp itself is not a consumer override point.

The flat names are aliases into the grid, kept because they read well at the call site:

```css
--lr-color-brand      /* == --lr-color-brand-fill-loud  */
--lr-color-brand-quiet/* == --lr-color-brand-fill-quiet */
--lr-color-on-brand   /* == --lr-color-brand-on-loud    */
```

**Nine generic slots follow the active `variant`.** On a component that takes `variant`,
`--lr-color-{fill,border,on}-{quiet,normal,loud}` — the same shape as the grid, with the variant
segment dropped — resolve to that element's current variant row. `variant="danger"` re-points
`--lr-color-fill-loud` at `--lr-color-danger-fill-loud`, and so on for all nine. The names keep the
grid's tiers so its contrast promise stays readable at the call site: `on-loud` is legible on
`fill-loud` whatever the variant happens to be. Use them in a `::part()` rule that should track the
element's variant instead of pinning one tone:

```css
/* Follows whatever variant the element is set to. */
lr-callout::part(base) {
  background: var(--lr-color-fill-quiet);
  color: var(--lr-color-on-quiet);
}
```

They are declared only on components that actually take a `variant` — six blocks of nine
declarations per shadow root is real weight for an element that would never read them — so treat
them as part of that component's surface, not as an ambient global. On a component with no
`variant`, reach for the fully-qualified grid slot instead.

### Interaction states: hover and press

Two knobs plus a partner colour describe every hover and press in the library:

```css
--lr-color-mix-hover    /* 12% — how far a hovered surface moves */
--lr-color-mix-active   /* 22% — how far a pressed one moves */
--lr-color-mix-partner  /* what it moves toward; defaults to var(--lr-color-text) */
```

**Hover and press are a colour mix, not a brightness filter.** The distinction is the whole design:
`filter: brightness()` multiplies every channel, so it lightens a dark control and darkens a light
one only by coincidence, does nothing whatsoever to a pure white or pure black fill, and — because a
filter applies to the element _and its descendants_ — drags the control's text and icons along with
its background. Mixing toward a partner colour has none of those properties: it is defined on the
fill alone, it always moves, and it moves in the direction the surface actually needs.

Making the partner follow the text colour is what makes the direction automatic. On a light surface
the text is dark, so a hover darkens; on a dark surface it is light, so the identical declaration
lightens. Components write it as:

```css
background: color-mix(
  in oklab,
  var(--lr-button-hover-base),
  var(--lr-color-mix-partner) var(--lr-color-mix-hover)
);
```

where the first argument is the colour the surface moves _away from_ — the fill that tier actually
paints. A chrome-less tier (outlined, plain, link) paints no fill of its own and mixes from the page
surface it sits on instead, which is why hovering one still moves.

Because the two knobs are percentages, a theme can flatten or exaggerate **every** interaction in
the library at once — `--lr-theme-color-mix-hover: 4%` for a restrained UI, `20%` for a punchy one —
without touching a single component. Point `--lr-theme-color-mix-partner` at a concrete colour to
override the follow-the-text behaviour where a surface needs a fixed direction.

### Elevation

Five shadow steps, so elevation carries information instead of one shadow serving every surface:

| Token            | For                                                                              |
| ---------------- | -------------------------------------------------------------------------------- |
| `--lr-shadow-xs` | a raised affordance inside a control — a segmented control's selected thumb      |
| `--lr-shadow-s`  | a small floating handle or a card lifted off the page — slider thumb, stat card  |
| `--lr-shadow-m`  | an anchored, transient surface — menus, dropdowns, popovers, tooltips            |
| `--lr-shadow-l`  | a persistent panel that owns its own region — dialog, drawer, toast, app rail    |
| `--lr-shadow-xl` | the topmost surface on screen — command palette, fullscreen widget, tool dialogs |

`--lr-shadow` is an alias for `--lr-shadow-m`.

**The steps are mode-aware, and that is not cosmetic.** Elevation is a luminance difference, and a
12%-alpha black shadow against a near-black surface is not one — so in dark mode the alphas roughly
triple and the geometry of the two largest steps grows, because a wider, softer shadow is what still
reads as depth when the surface underneath is already dark. The shadow _colour_ is its own token,
`--lr-shadow-color` (a bare `R G B` triple, not a full colour, so each step can apply its own
alpha), which lets a theme tint every shadow in the library from one place:

```css
:root {
  --lr-theme-shadow-color: 30 27 75;
} /* every step now casts an indigo shadow */
```

Reach for the tier that matches what the surface _is_, not the one that happens to look right on the
page you are on — that is what keeps two overlapping surfaces reading in the correct order.

### Cascade layers

`theme.css` declares its layer order up front, then puts all of its own tokens in `lr-theme`:

```css
@layer lr-base, lr-theme, lr-utilities, lr-overrides;
```

- **`lr-base`** — contains the explicitly scoped native-element rules only when the optional
  `native.css` asset is imported.
- **`lr-theme`** — where every `--lr-theme-*` token `theme.css` ships is declared.
- **`lr-utilities`** — contains exact `lr-*` classes only when the optional `utilities.css` asset is
  imported.
- **`lr-overrides`** — named so an application can opt its own rules into a defined position
  relative to Lyra's rather than inventing one.

**The consequence, stated plainly: any _unlayered_ declaration you write beats _every_ layered one,
whatever its specificity and whatever the load order.** So a plain
`:root { --lr-theme-color-brand-fill-loud: … }` in your own stylesheet wins even when your file is
loaded _before_ `theme.css`, and it needs no `!important` and no extra specificity. That is the
point of layering the theme at all: before this, `theme.css` declared its tokens unlayered at
`:root` — specificity (0,1,0), identical to a consumer's own `:root` rule — so whether your
override won came down to which stylesheet the bundler, the `<link>` and the `@import` happened to
emit first. Declaring the order up front also fixes it regardless of the order the stylesheets
themselves load in.

To place your overrides deliberately rather than relying on being unlayered:

```css
@layer lr-overrides {
  :root {
    --lr-theme-color-brand-fill-loud: #7c3aed;
  }
}
```

**Breaking in 8.0.0 — if you wrapped your Lyra overrides in a layer of your own, re-check them.**
That rule used to be compared against an _unlayered_ `theme.css`, which meant it lost
unconditionally, whatever its specificity. Now both sides are layered, so the winner is decided by
**layer order** — and layer order is fixed by whichever name the browser saw first. Import
`theme.css` before your own `@layer` statement and your layer sorts after Lyra's and wins; declare
your layers first and `lr-theme` is appended after them and wins instead. The outcome can therefore
flip in either direction on a change that only moves an `@import`, with nothing in the stylesheet
looking wrong. Two fixes, either is fine:

```css
/* 1. Unlayer them — an unlayered rule outranks all four Lyra layers unconditionally,
      whatever the load order. This is the one that cannot be broken by an import move. */
:root {
  --lr-theme-color-brand-fill-loud: #7c3aed;
}

/* 2. Or keep your layer and pin it after Lyra's, once, before anything else loads. */
@layer lr-base, lr-theme, lr-utilities, lr-overrides, app-theme;
@layer app-theme {
  :root {
    --lr-theme-color-brand-fill-loud: #7c3aed;
  }
}
```

The second form is the one to reach for when the application already has a layer architecture:
re-declaring the order is additive, and the first occurrence of each name is what fixes its
position — so stating all five names yourself pins `app-theme` last no matter when `theme.css`
loads.

### Where an override actually reaches

**Shared computed `--lr-*` design-token outputs are declared on every `lr-*` element's `:host`.**
That includes palette, spacing, radius, typography, and motion outputs such as
`--lr-color-brand`, `--lr-space-m`, and `--lr-radius`. A value for one of those shared outputs set
on an ancestor is re-declared — and lost — at the first `lr-*` element between that ancestor and
the component you meant to style. It never reaches anything nested inside another component.

**`--lr-theme-*` inputs are never redeclared inside a component's shadow styles.** `theme.css`
supplies them on its root and light/dark mode selectors, so an application override inherits normally
through every nested shadow root. **Setting a `--lr-theme-*` input on a wrapper element is the
supported way to retheme one subtree.** Setting a `--lr-*` token there only works for that wrapper's
direct children.

```css
/* Reaches everything in the subtree, however deeply nested. */
.invoice-panel {
  --lr-theme-color-brand-fill-loud: #7c3aed;
}

/* A shared computed output reaches direct lr-* children only — shadowed at the first nested host. */
.invoice-panel {
  --lr-color-brand: #7c3aed;
}
```

Documented component hooks are different: `--lr-<component>-*` properties (plus an upstream
mirror's documented unprefixed spellings) are public inputs. Components consume each public input
through a use-site fallback backed by a private default; they do not redeclare the public name on
`:host`. A component hook therefore inherits through wrappers and nested shadow hosts, while a
value set directly on the component remains authoritative. This makes one wrapper declaration a
reliable way to theme a group of matching components:

```css
.invoice-actions {
  --lr-button-radius: var(--lr-radius-pill);
  --lr-button-fill: var(--lr-color-brand-quiet);
}
```

State and size selectors change only the private fallback. An inherited or direct public value
continues to win in every state and size tier.

**Diagnostic:** if a shared design-token output has no effect on a nested component, check which
layer you set before assuming the component is at fault. If a documented component-specific hook
fails when inherited from a wrapper, that is a component bug; setting the same hook directly on
every host should not be necessary.

**There is no way to tell a live `--lr-*` declaration from a dead one without rendering.** A dead
declaration is byte-identical to a working one in the stylesheet; a stylesheet-text check cannot
distinguish it. Verify with `getComputedStyle` on the real element in the real state, and perturb
the value deliberately to confirm the assertion actually bites.

The same trap has a second form inside a component's own styles: a _declared_ value always wins
over a `var()` fallback arm, and `auto` is a declared value. That is why the exact-height escape
hatches (`--lr-input-control-height`, `--lr-select-trigger-height`, `--lr-chip-height`, …) are
undeclared by default rather than set to `auto`. Setting one _to_ `auto` is therefore not the same
as leaving it alone: it wins over the fallback arm and makes the per-size minimum-height floor dead
code. See each control's own reference page for its exact pair.

### Tokens with a contract attached

- **`--lr-theme-icon-button-size`** (default `2.5rem`) backs `--lr-icon-button-size`, the tappable
  box of **every** icon-only control in the library — `lr-icon-button` itself, and the
  expand/clear/toggle affordances inside `lr-date-input`, `lr-combobox`, `lr-input`, and
  `lr-select`. It is a _floor_, not a fixed size. Keep the resolved value **at or above 24px**
  (WCAG 2.2 SC 2.5.8 target size); the default leaves headroom. Lowering it below that shrinks
  every affordance in the library at once.
- **`--lr-icon-button-size-scope`** resizes icon buttons for **one subtree** instead of the whole
  application. Set it on any wrapper; it inherits past intervening components and reaches every
  icon-only control below it. Three names, three scopes — pick by how far you want the change to
  reach:

  | Property | Scope | Set it on |
  | --- | --- | --- |
  | `--lr-theme-icon-button-size` | application-wide | `:root`, or any ancestor |
  | `--lr-icon-button-size-scope` | one subtree | the wrapper you want affected |
  | `--lr-icon-button-size` | one element | the icon-only control itself |

  `--lr-icon-button-size-scope` wins wherever both ancestor inputs are set — the narrower scope
  takes precedence, and it has to: the shipped `design-tokens.css` declares
  `--lr-theme-icon-button-size` on `:root`, and a `var()` chain only falls through for a property
  that is unset *everywhere*, not merely shadowed nearer the element. Reading the theme tier first
  therefore made this knob inert for anyone loading that stylesheet (a real 18.1.0 defect, fixed in
  18.2.0). `--lr-icon-button-size`
  is **element-scoped on purpose** and is not a wrapper knob: every component re-declares it on its
  own host so the touch-target floor can apply per element, so a value set on a wrapper is replaced
  at the first component in between and never reaches anything nested inside one. That behaviour is
  unchanged — use `--lr-icon-button-size-scope` for the wrapper case.

  ```css
  /* A dense toolbar, without touching the rest of the app. */
  .message-toolbar {
    --lr-icon-button-size-scope: 1.75rem;
  }
  ```

  The coarse-pointer floor still applies to both ancestor inputs: on a touch device (`hover: none`
  or `pointer: coarse`) a resolved value below `2.75rem` is raised back to it, so the new subtree
  knob is not a way around WCAG 2.2 SC 2.5.8 — a deliberately dense desktop toolbar still becomes
  tappable on a phone.
- **`--lr-color-surface-overlay` follows `--lr-theme-color-surface-default` in both modes.** It is
  the panel colour behind every floating surface — dropdowns, listboxes, menus, toasts, popovers,
  dialogs, and the `lr-app-rail` mobile drawer. In light mode it resolves straight to
  `--lr-color-surface`, so a re-skinned page surface carries them all with it. Dark mode cannot
  resolve to the page surface — panel and page would be the same near-black, and an open dialog
  would read as a scrim with text floating on it and no panel at all — so it is **derived** from
  the page surface instead: `color-mix(in srgb, var(--lr-color-surface) 85%, #8bade2)`, which lifts
  the panel a fixed amount above whatever the base happens to be. One
  `--lr-theme-color-surface-default` override therefore re-skins every floating surface in dark
  mode too, and the elevation delta survives the re-skin. At the built-in dark base the pair still
  resolves to the same panel colour it always has, so no existing dark theme moves.
  `--lr-theme-color-surface-overlay` still wins outright when you set it — reach for it only when
  you want a panel colour unrelated to the page surface.
- **Aligning your own content next to a checkbox or radio.** `--lr-checkbox-label-indent` /
  `--lr-radio-label-indent` publish the label offset, but custom properties inherit _down_, not
  sideways, so a sibling node in your tree cannot read them off the control. Compute the same
  formula from the `--lr-theme-*` inputs you control:
  ```css
  padding-inline-start: calc(
    min(var(--lr-theme-icon-button-size, 2.5rem), 1.75rem) + var(--lr-theme-space-s, 0.5rem)
  );
  ```

**`llms/tokens.md` is the full generated catalog** of every token. It records the theme input and
fallback for themeable tokens, and the resolved alias, ramp, or fixed value for derived tokens —
consult it rather than guessing a token name.

```css
@import "@aceshooting/lyra-ui/theme.css"; /* optional ready-made light + dark base */
:root {
  --lr-theme-color-brand-fill-loud: #7c3aed;
}
```

With `theme.css` imported, switch modes by putting `class="lr-light"`/`class="lr-dark"` (or
`data-lr-theme="light"`/`"dark"`) on any ancestor; it also sets `color-scheme`. Without it, the token
layer still ships a `prefers-color-scheme: dark` fallback that re-points the hardcoded defaults at a
dark palette. Two things switch that fallback off:

- **A real `--lr-theme-*` value**, which the fallback only substitutes for.
- **`data-lr-theme="light"` on the component itself**, which pins light mode regardless of the OS.
  Both layers honour it now: the palette layer always did, and the token layer — the hardcoded
  surface/text/border defaults — does too, so `<lr-card data-lr-theme="light">` on a dark machine is
  light throughout rather than light chrome over a dark colour grid. The mirror-image
  `data-lr-theme="dark"` pins dark on a light machine the same way, and a `.lr-dark` /
  `data-lr-theme="dark"` _ancestor_ is followed as well (through `:host-context()` where the engine
  has it, and through `theme.css`'s inheriting custom properties everywhere else).

Note the asymmetry: the _light_ pin is read on the component itself (`:host([data-lr-theme='light'])`),
while a _dark_ ancestor is followed through `:host-context()`. Putting `data-lr-theme="light"` on
`<html>` — what `theme.js`'s `setLyraTheme({ mode: 'light' })` does — pins the page through
`theme.css`'s real `--lr-theme-*` values, which inherit into every shadow root. Without `theme.css`
there are no such values to inherit, so put the attribute on the components you actually need
pinned.

The token layer also sets `:host([hidden]) { display: none !important; }` and an inherited
`box-sizing: border-box` reset.

### Theme mode/accent/surface runtime (`@aceshooting/lyra-ui/theme.js`)

Flipping the mode class/attribute above is something every app ends up hand-rolling — persist a
choice, apply it on load, avoid the flash of wrong theme before the app boots. `theme.js` is that
runtime, published as its own subpath: **zero dependencies, no Lit, no component imports, and no
side effects on import**, so an app can persist and apply a theme without pulling the component
graph into its first-paint bundle.

```ts
import { setLyraTheme, getLyraTheme } from "@aceshooting/lyra-ui/theme.js";

setLyraTheme({ mode: "dark" }); // unspecified fields keep their current value
setLyraTheme({ accent: "#7c3aed" }); // mode stays 'dark'; brand-only shorthand
getLyraTheme(); // → { mode: 'dark', accent: '#7c3aed', surface: null }
setLyraTheme({ accent: { danger: "#dc2626", success: "#16a34a" } }); // per-role, brand untouched
setLyraTheme({ accent: { brand: { light: "#2563eb", dark: "#f59e0b" } } }); // per-mode base color
setLyraTheme({ surface: "#0b0f1a" }); // mixes every ramp against this instead of the mode default
setLyraTheme({ mode: "auto" }); // follows the OS, including later changes
setLyraTheme({ mode: "unset", accent: null, surface: null }); // removes Lyra's overrides
```

- **`setLyraTheme({ mode?, accent?, surface? })`** persists to `localStorage['lyra-theme']`,
  applies to `document.documentElement`, and dispatches `lr-theme-change` on `window` with
  `detail: { mode, accent, surface }`. Fields you omit keep their current value; pass `null` to
  clear a field. It **never throws** — when `localStorage` is unavailable (private browsing,
  quota, a sandboxed iframe) it degrades to apply-without-persist, and the "fields you omit keep
  their current value" rule still holds across calls in that state: the merge falls back to the
  last theme applied in this session rather than to the default.
- **`getLyraTheme()`** returns `{ mode, accent, surface }`, defaulting to
  `{ mode: 'auto', accent: null, surface: null }` when nothing is stored or the stored value is
  malformed. Storage is re-read on every call — no in-memory cache — so a value written by another
  tab or a previous session is picked up cold. Where storage is unreadable or unwritable it
  reports the theme last applied, so the return value always describes what the document is
  actually showing and a toggle UI bound to it stays in sync.
- **`mode`** is `'light' | 'dark' | 'auto' | 'unset'`. `'light'`/`'dark'` set **both
  `data-lr-theme`** (the
  attribute `theme.css` actually keys its palette blocks on) **and `data-theme`** (the generic
  attribute canvas-rendered components watch, so `lr-chart`/`lr-heatmap`/`lr-qr-code` repaint on
  the switch rather than keeping stale colors — see `llms/components/lr-chart.md`). `'auto'`
  resolves `prefers-color-scheme` immediately and keeps following changes. `'unset'` removes both
  attributes; use it when the application owns mode selection through another cascade.
- **`accent`** is either an absolute CSS color — shorthand for `{ brand: <that color> }`, and the
  only shape prior to 16.0.0 — or a per-role record
  `{ brand?, success?, warning?, danger?, neutral? }`. Only the roles you supply are (re)derived;
  an omitted role keeps whatever the static palette (`llms/tokens.md`) already provides. For each
  supplied role, Lyra derives the complete quiet/normal/loud fill, border, and paired on-color
  ramp as inline `--lr-theme-color-<role>-*` inputs; `brand` additionally keeps `--lr-theme-accent`
  (a compatibility value holding the raw brand color, resolved for the active mode when the role
  is per-mode) and `--lr-theme-color-focus`, which no other role drives. Each paired foreground is
  selected for at least 4.5:1 contrast against its fill; normal/loud borders and the brand focus
  color are adjusted to at least 3:1 against the resolved surface (see `surface` below). Malformed
  values, CSS-wide keywords, `currentColor`, system colors, relative-color syntax, and unresolved
  `var()` expressions fail closed to `null` — at the whole `accent` field for a bare-string call,
  or at just that one role (or role/mode branch) for a per-role record, so one bad role does not
  take the others down with it. Pass `accent: null` to restore the palette supplied by
  `theme.css` entirely.
- **Per-mode accent.** Each role's value can itself be a bare color/`null` (applied to both
  resolved modes, as above) or a `{ light?, dark? }` map deriving that role's ramp from a
  genuinely *different base color* per resolved mode — not merely a different tint weight of the
  same hue — for example `{ brand: { light: "#2563eb", dark: "#f59e0b" } }`. An omitted branch
  (or a role/branch that fails validation) keeps that mode's inherited/palette default; the branch
  actually painted follows the *resolved* mode, so it updates automatically when `mode: 'auto'`
  follows a `prefers-color-scheme` change. The stored/returned/event-detail shape always mirrors
  what you supplied (bare color or `{ light, dark }`), never collapsed to a single resolved color.
- **`surface`** is an absolute CSS color used as every role's ramp mix base, instead of the
  shipped light/dark defaults (`#1a1a1a` dark / `#ffffff` light). It follows the same absolute
  CSS color and fail-closed-to-`null` rules as `accent`; an alpha channel is composited against
  the mode's own default surface before use. `null` (the default) keeps those shipped defaults.
  Supplying `surface` changes the quiet/normal/loud mix ratios and every border/focus contrast
  check for **every** currently-supplied role at once — it is one mix base per apply, not
  per-role.

  These are `--lr-theme-*` inputs, so they reach every nested shadow root — see "Where an override
  actually reaches" above for why setting a `--lr-*` token instead would not.

**Theme presets.** `@aceshooting/lyra-ui/theme/presets.js` exports
`LYRA_THEME_PRESETS`, `defineLyraThemePreset()` and `applyLyraThemePreset()`. Built-in keys are
`system`, `light`, `dark`, `unset`, `emerald`, `ruby`, `amethyst`, and `sapphire`; the gemstone
presets use system-following mode plus the named brand accent. Application presets use a stable
lowercase kebab-case `id` and a `theme: { mode?, accent?, surface? }` record — the same shapes
`setLyraTheme()` accepts, including a per-role `accent` record. `defineLyraThemePreset()`
validates the id and field shapes, freezes both records, and leaves CSS color-syntax validation to
the production runtime when the preset is applied:

```ts
import {
  applyLyraThemePreset,
  defineLyraThemePreset,
} from "@aceshooting/lyra-ui/theme/presets.js";

applyLyraThemePreset("sapphire");
applyLyraThemePreset(
  defineLyraThemePreset({
    id: "application-ocean",
    theme: {
      mode: "dark",
      accent: { brand: "#22d3ee", danger: "#dc2626" },
      surface: "#0b0f1a",
    },
  })
);
```

Applying a preset uses the production runtime. When every explicitly requested field survives its
runtime validation, Lyra reflects the id to `data-lr-theme-preset` and emits
`lr-theme-preset-change` on `window` with `{ id, theme }`, where `theme` is the complete applied
snapshot. If runtime validation changes a field (for example, an invalid accent fails closed to
`null`), only the ordinary `lr-theme-change` event is emitted and no preset marker is written,
because the resulting state is not exactly that named preset. A direct `setLyraTheme()` call also
removes the preset marker.

**No-flash bootstrap.** `lyraThemeBootstrap` is a self-contained IIFE **string** (not a function),
meant to be inlined into a `<script>` in `<head>` **before any stylesheet**, so the persisted theme
is on the root element before first paint. It reads `localStorage['lyra-theme']`.
`createLyraThemeBootstrap({ storageKey })` returns the same kind of string for an application-owned
key, so an existing persistence layer can reuse the pre-paint half independently of
`setLyraTheme()`/`getLyraTheme()`. Calling the factory with no options returns the same string as
`lyraThemeBootstrap`. The result is a string precisely so this can happen in an unbundled
`<script>` context without shipping or parsing the module. Custom keys are escaped against HTML
script termination and JavaScript line separators. Under a Content Security Policy, give the
inline script the nonce or hash required by the application:

```html
<head>
  <script>
    /* server-inlines lyraThemeBootstrap here */
  </script>
  <link rel="stylesheet" href="/theme.css" />
</head>
```

Both variants read a stored `{ mode, accent, surface }` record, resolve `auto`, and derive the same
per-role ramp(s) from the same math — the bootstrap re-implements it inline (self-contained, so it
can run before any module loads) rather than importing the runtime, but the two are tested to never
drift. A missing or malformed record receives the runtime's
`{ mode: 'auto', accent: null, surface: null }` default; blocked `localStorage` leaves the document
untouched rather than throwing before your app loads.

**External-file delivery for a strict CSP.** `@aceshooting/lyra-ui/theme-bootstrap.js` is a
third, non-module way to ship the same bootstrap: a static script asset published alongside the
package, containing exactly `lyraThemeBootstrap`'s bytes (both are produced from the same build
step, so they can never drift apart). Reference it with a plain `<script src>` in `<head>`,
still before any stylesheet:

```html
<head>
  <script src="/vendor/theme-bootstrap.js"></script>
  <link rel="stylesheet" href="/theme.css" />
</head>
```

This exists for a Content-Security-Policy that forbids `unsafe-inline` and cannot mint a
per-response nonce — a static HTML entry, for example — where the documented inline-script
nonce/hash guidance above does not apply. Serving it same-origin (copy it into your build output,
or configure your bundler/static host to do so) needs no hash at all; hashing it for an even
stricter policy uses the same CSP `script-src` hash mechanism browsers already apply to any
external script resource.

**Configuring the static asset from its own `<script>` tag.** `theme-bootstrap.js` must be loaded
as a plain classic script — never `type="module"` and never `async` — because it reads its own
configuration synchronously through `document.currentScript` while it runs, and that property is
`null` for both of those loading modes (as well as for anything scheduled after the script has
already finished executing). Two optional attributes on that same `<script>` tag override the
defaults without regenerating the file:

```html
<head>
  <script
    src="/vendor/theme-bootstrap.js"
    data-lr-theme-storage-key="my-app-theme"
    data-lr-theme-attributes="data-lr-theme data-theme"
  ></script>
  <link rel="stylesheet" href="/theme.css" />
</head>
```

- `data-lr-theme-storage-key` — the `localStorage` key to read, in place of the default
  `'lyra-theme'`. Equivalent to `createLyraThemeBootstrap({ storageKey })`'s argument, but
  resolved by the static file itself at parse time rather than baked in ahead of time. This is
  what lets an application with its own pre-existing storage key use the static asset instead of
  inlining a per-app copy.
- `data-lr-theme-attributes` — a space-separated list of attribute names to set on
  `<html>` in place of the default `data-lr-theme data-theme` pair, replacing that list entirely
  rather than adding to it.

Both attributes are optional and independently validated; an absent, empty, oversized, or
malformed value falls back to the built-in default rather than throwing, so a `<script>` tag with
neither attribute — every existing deployment — behaves exactly as before. `data-lr-theme-storage-key`
must be a non-empty string of at most 200 characters (its content is otherwise unrestricted — it is
only ever used as an opaque `localStorage` key, never written to the DOM). `data-lr-theme-attributes`
must parse to one to eight tokens, each unique and each matching `data-[a-z0-9]+(-[a-z0-9]+)*` —
which rejects an event-handler name (`onload`), a native attribute (`style`, `class`, `id`), any
token containing whitespace, a quote, `=`, or a control character, an empty list, and a duplicated
token — because these attribute names reach `setAttribute()`/`removeAttribute()` on the document
root. A `document.currentScript` of `null` (module/async misuse, or a script tag re-read after it
finished running) is treated the same as no configuration at all.

An application-owned key from `createLyraThemeBootstrap({ storageKey })` can still be inlined as
documented above; the static file's own script-tag attributes are the alternative for a strict-CSP
deployment that cannot inline that call.

**Migrating from 15.x.** `accent` used to be exactly an absolute CSS color or `null`; that shape
still works unchanged (`setLyraTheme({ accent: '#7c3aed' })` keeps deriving only the brand ramp).
What changed is `LyraTheme` gaining a `surface` field alongside it — a strict superset for every
caller that only ever read/wrote `mode`/`accent`, since `getLyraTheme()` now also returns
`surface: null` by default. Only code that structurally compares the whole returned record (for
example `assert.deepEqual(getLyraTheme(), { mode, accent })`) needs the extra field added.

### Invalidating canvas theme values

Canvas pixels do not participate in the CSS cascade after they are drawn. Lyra automatically
redraws its canvas renderers when theme attributes, style/link nodes, CSSOM rules, adopted style
sheets, or relevant media-query results change. If an application theme engine changes computed
tokens through another mechanism, call the explicit realm-level invalidation hook afterwards:

```ts
import { invalidateLyraTheme } from "@aceshooting/lyra-ui/utilities/theme.js";

invalidateLyraTheme(); // the global document realm
invalidateLyraTheme(shadowRoot); // the realm owning this root/element/document
```

`invalidateLyraTheme(root?: Document | ShadowRoot | Element): void` coalesces each connected
canvas consumer's redraw to its normal microtask/render schedule. The optional root selects a
browser realm; it does not limit invalidation to a subtree. The function is a no-op during server
rendering and retains no document or stylesheet after the last canvas consumer disconnects.

## Preventing layout shift from lazy-upgrading elements (CLS)

An undefined custom element is an inline box with no intrinsic size, so every `lr-*` in the initial
viewport contributes a reflow as its definition loads. Components that additionally defer on an
optional peer (`lr-chart`, `lr-map`, `lr-flag`, `lr-flow-canvas`, `lr-graph`,
`lr-knowledge-graph-explorer`)
render a skeleton while that peer resolves, which can cost a second shift when the real content
replaces it. Each component is individually well-behaved; the aggregate on a first paint is what
costs a Lighthouse Cumulative Layout Shift score.

Lyra ships an optional, opt-in stylesheet that reserves each component's intrinsic footprint before
upgrade:

```css
@import "@aceshooting/lyra-ui/reservations.css";
```

It styles **only** `:not(:defined)` elements, inside an `@layer lr-reservations`, so it becomes inert
the moment a definition upgrades and can never fight a component's own layout. It sets no colors and
no `:root` rules.

**Every reservation is expressed with the same custom property and fallback token the component's
own stylesheet uses** — `--lr-chart-height` / `--lr-size-280px` for the chart family,
`--lr-map-height` for `lr-map`, `--lr-canvas-reserved-height` for graph/canvas surfaces,
`--lr-flag-aspect-ratio` for `lr-flag`, `--lr-form-control-height` for the field controls, and so
on. That is the point of shipping it rather than documenting measured pixel values: a hand-written
reservation rots silently the moment a component's default changes, whereas these track it, and
theming a component through its documented custom property re-themes its reservation with it.

Hand-rolling equivalent rules is still fine — the pattern is just:

```css
lr-chart:not(:defined) {
  display: block;
  min-block-size: var(--lr-chart-height, var(--lr-size-280px));
}
```

Three things worth knowing:

- **It reserves layout only for `lr-*` usages in the exact tree it is loaded into.** A `<link>`/
  `@import` reaching the document reserves the document's own light-DOM `lr-*` usages; it does not
  reach one that a *different* component renders inside *that component's own* shadow root, because
  a document stylesheet never crosses a shadow boundary. If your own component's template composes
  `lr-*` elements, load the reservations there too, in whichever form matches how your component is
  built: adopt `@aceshooting/lyra-ui/reservations.styles.js`'s `reservationStyles` export (a Lit
  `CSSResult` generated from the same `reservations.css`, so the two can never drift) —
  `static styles = [reservationStyles, css\`…\`]`, or
  `shadowRoot.adoptedStyleSheets = [reservationStyles.styleSheet!]` outside Lit — or `<link>`/
  `@import` `reservations.css` again inside that shadow root if you are not using constructed
  stylesheets at all.
- A per-instance override needs the matching custom property to be set as well, not only the
  attribute, or the pre-upgrade frame and the upgraded frame will disagree. `<lr-chart height="500px">`
  should carry `style="--lr-chart-height: 500px"` too if it sits above the fold.
- The reservation covers the definition-upgrade shift. A component that then swaps a skeleton for
  peer-resolved content stays stable as long as the reserved box matches the final footprint, which
  is why the reservations target each component's *final* default size rather than its skeleton's.

## Scope: what this library does not provide

Lyra is a component library, not an application framework. The following are deliberately out of
scope, so they are worth not searching the catalog for:

- **Client-side routing.** There is no router and no route-outlet component. URL ownership belongs to
  the application (or its router of choice), because a component library that took it over would
  conflict with every framework router a consumer might already run. The navigation components are
  designed to be *driven* by whatever router you use rather than to own the URL themselves:
  `lr-app-rail-item`, `lr-breadcrumb-item` and `lr-tab-group` all expose their active/selected state
  as ordinary reflected properties, so binding is a one-way write from your route state plus a click
  handler that calls your router. Wire it once in your shell component; there is no Lyra-specific
  pattern to learn.
- **Data fetching, caching, and state management.** Components take data as properties and emit
  events; they never fetch on your behalf, except the documented viewers/`src`-taking components,
  which are explicit about it.
- **Form submission and validation orchestration.** Form-associated controls integrate with the
  native `<form>`/`ElementInternals` contract; the submission lifecycle stays the application's.

## Optional native styles and CSS utilities

Lyra ships two independent light-DOM stylesheets. Neither is imported by the root barrel, a family
barrel, a component entry, or `theme.css`, so applications that do not opt in keep their existing
native-element and utility conventions unchanged.

```css
@import "@aceshooting/lyra-ui/native.css";
@import "@aceshooting/lyra-ui/utilities.css";
```

`native.css` places its rules in `lr-base` and styles native elements only when they are
**descendants** of an explicit `.lr-native` scope. It has no `:root`, `html`, `body`, or unscoped
reset, and the element carrying `.lr-native` is not styled by the native bundle itself. The rules
stay in light DOM: they do not pierce a component's shadow root.

```html
<section class="lr-native">
  <h2>Profile</h2>
  <label for="profile-name">Display name</label>
  <input id="profile-name" />
  <button type="button">Save</button>
</section>
```

`utilities.css` places exact, zero-specificity `:where(.lr-*)` classes in `lr-utilities`. It never
uses a substring class selector, so a class such as `app-lr-flex-preview` does not opt in. Both
assets repeat `@layer lr-base, lr-theme, lr-utilities, lr-overrides`; an ordinary unlayered
application rule therefore beats them regardless of load order. A third opt-in asset,
[`tokens-root.css`](#reading-the-resolved-tokens-from-your-own-components--tokens-rootcss), is not a
style sheet in the same sense — it declares custom properties only, and exists so your own
components can read the resolved `--lr-*` tokens these two are written against.

### Utility class inventory

| Group                       | Exact classes                                                                                                                                                     |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Display and composition     | `lr-block`, `lr-inline-block`, `lr-flex`, `lr-inline-flex`, `lr-grid`, `lr-flow-root`, `lr-stack`, `lr-cluster`, `lr-grid-auto`                                   |
| Flex direction and wrapping | `lr-row`, `lr-column`, `lr-wrap`, `lr-nowrap`, `lr-grow`, `lr-grow-0`, `lr-shrink`, `lr-shrink-0`                                                                 |
| Item alignment              | `lr-items-start`, `lr-items-center`, `lr-items-end`, `lr-items-stretch`, `lr-items-baseline`, `lr-self-start`, `lr-self-center`, `lr-self-end`, `lr-self-stretch` |
| Distribution                | `lr-justify-start`, `lr-justify-center`, `lr-justify-end`, `lr-justify-between`, `lr-justify-around`                                                              |
| Gaps                        | `lr-gap-0`, `lr-gap-xs`, `lr-gap-s`, `lr-gap-m`, `lr-gap-l`, `lr-gap-2xl`                                                                                         |
| Logical sizing              | `lr-inline-full`, `lr-block-full`, `lr-size-full`, `lr-min-inline-0`, `lr-min-block-0`, `lr-max-inline-full`, `lr-max-inline-prose`, `lr-center`                  |
| Overflow                    | `lr-overflow-auto`, `lr-overflow-hidden`                                                                                                                          |
| Text alignment and size     | `lr-text-start`, `lr-text-center`, `lr-text-end`, `lr-text-xs`, `lr-text-sm`, `lr-text-base`, `lr-text-lg`, `lr-text-xl`, `lr-text-quiet`                         |
| Font                        | `lr-font-normal`, `lr-font-medium`, `lr-font-semibold`, `lr-font-bold`, `lr-font-mono`                                                                            |
| Text flow                   | `lr-text-break`, `lr-text-nowrap`, `lr-truncate`, `lr-text-balance`, `lr-text-pretty`, `lr-prose`                                                                 |
| Visibility and focus        | `lr-visually-hidden`, `lr-visually-hidden-focusable`, `lr-fouce-hidden`, `lr-hidden`                                                                              |
| Page allocation             | `lr-page-mobile-only`, `lr-page-desktop-only`                                                                                                                     |

`lr-fouce-hidden` hides only an opted-in custom element while it matches `:not(:defined)`, then
reveals it automatically after registration. `lr-visually-hidden-focusable` becomes visible on
focus or when a descendant receives focus, making it suitable for skip links.

The Page helpers key off the reflected `view` state of their containing `<lr-page>`:
`lr-page-mobile-only` is hidden for `view="desktop"`, and `lr-page-desktop-only` is hidden for
`view="mobile"`. Page derives that state from its own allocated inline size, not the viewport.

### Bundle-specific override hooks

The bundles consume the ordinary shared color, typography, spacing, border, radius, focus, size,
and opacity tokens first. These additional hooks customize only the light-DOM bundle behavior:

| Hook                                      | Default/fallback and use                                                     |
| ----------------------------------------- | ---------------------------------------------------------------------------- |
| `--lr-layout-gap`                         | `--lr-space-m`; default gap for `lr-stack`, `lr-cluster`, and `lr-grid-auto` |
| `--lr-grid-min-inline-size`               | `--lr-size-14rem`; minimum auto-grid item inline size                        |
| `--lr-content-max-inline-size`            | `--lr-size-48rem`; `lr-center` content measure                               |
| `--lr-prose-max-inline-size`              | `65ch`; `lr-prose` and `lr-max-inline-prose` measure                         |
| `--lr-prose-flow-space`                   | `--lr-space-l`; flow spacing between direct prose blocks                     |
| `--lr-prose-quote-padding`                | `--lr-space-l`; logical quote inset                                          |
| `--lr-prose-quote-border-width`           | `--lr-border-width-thick`; logical quote edge                                |
| `--lr-visually-hidden-size`               | `--lr-border-width-thin`; retained hidden box size                           |
| `--lr-native-link-decoration-width`       | `--lr-border-width-thin`; resting underline thickness                        |
| `--lr-native-link-underline-offset`       | `--lr-space-2xs`; underline offset                                           |
| `--lr-native-link-hover-decoration-width` | `--lr-border-width-medium`; hovered underline thickness                      |
| `--lr-native-pre-padding`                 | `--lr-space-m`; preformatted block padding                                   |
| `--lr-native-tab-size`                    | `2`; preformatted tab width                                                  |
| `--lr-native-quote-padding`               | `--lr-space-l`; native blockquote logical inset                              |
| `--lr-native-quote-border-width`          | `--lr-border-width-thick`; native blockquote logical edge                    |
| `--lr-native-control-min-block-size`      | `--lr-icon-button-size`; native control hit-area floor                       |
| `--lr-native-control-padding-block`       | `--lr-space-s`; native control block padding                                 |
| `--lr-native-control-padding-inline`      | `--lr-space-m`; native control inline padding                                |
| `--lr-native-placeholder-opacity`         | `1`; native input/textarea placeholder opacity                               |
| `--lr-native-summary-min-block-size`      | `--lr-icon-button-size`; native summary hit-area floor                       |
| `--lr-native-fieldset-padding`            | `--lr-space-l`; fieldset padding                                             |
| `--lr-native-legend-padding`              | `--lr-space-xs`; legend inline padding                                       |
| `--lr-native-table-cell-padding`          | `--lr-space-s`; caption and table-cell padding                               |
| `--lr-native-rule-space`                  | `--lr-space-l`; horizontal-rule block margin                                 |

## Localization: `locale`, `strings`, and the locale runtime

Every built-in string — button labels, accessible names, descriptions, validation messages, status
announcements, empty/loading states — resolves through the locale runtime. Consumer data and slotted
content are never translated.

Two knobs exist on **every** `lr-*` element, inherited from `LyraElement` and therefore not repeated
in the per-component sections:

- **`locale: string = ''`** (reflected attribute) — per-instance locale override. Empty means "use
  the nearest `locale`/`lang` ancestor".
- **`strings: LyraLocaleStrings = {}`** (property only, no attribute) — per-instance message
  overrides, merged over the registered catalog. Assignment takes an immutable snapshot of up to
  4,096 own enumerable data properties. Mutating the assigned object later has no effect; assign a
  new object to update it. Accessors and malformed entries are ignored per key without being run.

```ts
import {
  registerLyraLocale,
  setLyraLocale,
} from "@aceshooting/lyra-ui/localization.js";

registerLyraLocale("fr", { close: "Fermer", retry: "Réessayer" }); // app-wide, partial catalogs fine
setLyraLocale("fr"); // page-level selection; see the precedence order below
```

```html
<lr-toast></lr-toast>
<script type="module">
  document.querySelector("lr-toast").strings = { close: "Fermer" };
</script>
```

**Which locale a component ends up using.** Four sources, first answer wins:

1. **The component's own `locale`, then its own `lang`.**
2. **The nearest ancestor declaring `locale` or `lang`** (crossing shadow boundaries), except that
   `lang` on `<html>` is not read here — see 4. A `locale` attribute on `<html>` _is_, since that
   attribute is this library's own and can only be a deliberate opt-in.
3. **`setLyraLocale(tag)`**, the page-level selection.
4. **`<html lang>`**, the document default.
5. **`'en'`.**

**Breaking in 9.0.0:** steps 3 and 4 were the other way round, which made `setLyraLocale()` inert on
any page that declares `<html lang>` — i.e. essentially every well-formed page. `setLyraLocale('fr')`
under `<html lang="en">` silently kept rendering English. It now wins. Two consequences: an
application that switched locale by _rewriting_ `<html lang>` still works only if it never also
called `setLyraLocale()` (the explicit call now pins the locale until changed or cleared with
`setLyraLocale('')`), and a per-subtree `lang`/`locale` override is unaffected — it still beats both.

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
[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
`LyraLocaleStrings`, `LyraLocaleMeta`, `LyraLocaleDirection`, `LyraMessageKey`, `LyraMessage`,
`LyraPluralMessage` and `LyraPluralCategory`. The package root continues to re-export the same
surface for compatibility and remains registration-free in v8; use the dedicated entry when the
application only needs locale setup and the narrower import graph.
**`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`.

**Locale-tag identity.** Registration, active selection, `getLyraLocale()`, registry enumeration,
component resolution and `bridgeLyraLocale()` all use the same public spelling. `_` remains an input
alias, and structurally valid BCP-47 tags go through the platform canonicalizer, so `PT_BR` becomes
`pt-BR` and deprecated aliases collapse onto their current tag. Private-use-only and short legacy
application tags that the platform canonicalizer rejects remain supported as bounded lowercase
identities. `registerLyraLocale()` and `setLyraLocale()` reject values that are neither valid BCP-47
nor bounded alphanumeric custom tags; an inherited invalid over-complex `locale`/`lang` safely
resolves to English. Structurally valid long BCP-47 tags remain accepted.

**Lookup order for a tag.** Every message resolves through one chain, and `Intl.PluralRules`
category selection walks the same chain, so the two can never disagree:

1. **The BCP-47 truncation walk, most specific first** — `zh-Hans-CN` → `zh-Hans` → `zh`.
   Casing and `_` separators are normalized, so `pt_BR` and `pt-br` are the same key. Lookup chains
   are memoized and capped at 64 candidates. A structurally valid tag beyond the normal complexity
   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, and `lang="pt"`/`lang="pt-PT"` both find `pt-BR`. 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.
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`.

```ts
import { getLyraLocaleDirection } from "@aceshooting/lyra-ui/localization.js";

getLyraLocaleDirection("ar-EG"); // 'rtl' — declared by the shipped `ar` catalog, inherited by the region
getLyraLocaleDirection("de"); // 'ltr'
```

`getLyraLocaleDirection(tag): 'ltr' | 'rtl'` answers "does this locale need `dir="rtl"`?" without
an application keeping its own tag table. It reads a `dir` declared by `registerLyraLocale()`'s
optional third argument first (walked through the same chain above, so a region inherits its base
language's declaration), then `Intl.Locale`'s text-info surface where the engine has it, and
finally `'ltr'`. It only _reports_ a direction — nothing in the library applies one; see
[RTL and direction](#rtl-and-direction).

```ts
registerLyraLocale("ar", { close: "إغلاق" }, { dir: "rtl", name: "العربية" });
```

`registerLyraLocale(tag, strings, meta?)`'s third argument is optional catalog metadata —
`{ dir?: 'ltr' | 'rtl'; name?: string }` (`LyraLocaleMeta`). Nothing in it is ever rendered: `dir`
feeds `getLyraLocaleDirection()`, `name` is the locale's endonym for an application's own locale
list. It merges the same way `strings` does, so a later two-argument call adding messages never
drops metadata, and the two-argument call remains the normal way to register a catalog.

Registration snapshots at most 4,096 own enumerable catalog properties before publishing them.
Each accepted value is either a string or a plain/null-prototype CLDR plural record whose own data
properties are string categories and which includes `other`. Nested plural records are cloned and
frozen. Arrays, `null`, inherited properties, accessors and malformed records are ignored per key:
they never execute and never replace that key's last valid translation, while valid sibling keys
still merge. Empty strings remain intentional translations. Per-instance `.strings` overrides use
the same validation, so `resolveLyraString()` always returns a string and malformed overrides fall
through to the next valid tier.

`getRegisteredLyraLocales(): readonly string[]` returns a fresh frozen list of every locale with strings registered via
`registerLyraLocale()`, plus `'en'` (always available through the built-in English fallback),
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
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
registry listeners from running. State commits first, then the mutator throws one `AggregateError`
containing all callback failures after delivery completes. `<lr-locale-picker>` is the built-in
consumer of the registry subscription; see `llms/components/lr-locale-picker.md`.

`getRegisteredLyraLocaleKeys(locale: string): readonly string[]` returns a frozen snapshot of
exactly the keys `locale`'s own catalog carries — no BCP-47 fallback-chain widening and no merge
with the built-in English defaults. This answers "what has this locale actually been given",
distinct from `getRegisteredLyraLocales()`, which reports registry *membership* (which tags exist)
rather than catalog *content*. Diff the result's length against
`Object.keys(LYRA_DEFAULT_STRINGS).length` to measure a locale's own translation coverage without a
silent English-fallback merge making a partial catalog look complete. A locale nothing ever
registered — including `'en'` itself, unless it was explicitly passed to `registerLyraLocale()` —
returns an empty snapshot.

In development (Lit's own dev-mode signal; silent in production), resolving a message for a
resolved locale other than English that has no override, no fallback, and no registered catalog
entry for that key warns once per (locale, key) to `console.warn` before falling through to the
English default — the same silent-fallback `resolveLyraString()`, `localize()`, and
`resolveLyraScopedString()` all shared with no way to detect it before. It never fires for an
English-resolved locale, since falling through to `defaults` is simply how English itself resolves.

Gotcha: `localize()`'s optional second argument is a fallback string. Passing a defined literal there
silently defeats a registered catalog — omit it, or pass `undefined`.

### Ready-made catalogs: `@aceshooting/lyra-ui/translations/<locale>.js`

Twelve full catalogs ship with the package — **`ar`, `de`, `es`, `fa`, `fr`, `he`, `it`, `ja`,
`pt-BR`, `ro`, `ru`, `zh-CN`** — each covering every key in `LYRA_DEFAULT_STRINGS`. They are
**side-effect-only modules**: import one bare, read nothing from it, and it calls
`registerLyraLocale()` for you.

```ts
import "@aceshooting/lyra-ui/translations/de.js";
import "@aceshooting/lyra-ui/translations/ar.js"; // declares dir: 'rtl'; direction still comes from dir
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"; // also serves pt and pt-PT
import "@aceshooting/lyra-ui/translations/ro.js"; // Romanian
import "@aceshooting/lyra-ui/translations/zh-CN.js"; // also serves zh, zh-Hans and zh-Hans-CN
```

Persian and Hebrew use CLDR plural categories (`fa`: `one`/`other`; `he`:
`one`/`two`/`other`); Italian uses a non-default set too (`it`: `one`/`many`/`other`), and so does
Romanian (`ro`: `one`/`few`/`other`, where `few` covers `0` and `2`-`19` and `other` is the
`de`-requiring form from `20` upward). `ar`, `fa`
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.

`pt-BR` and `zh-CN` are the only Portuguese and Chinese catalogs, and they are regional tags. Step 2
of the lookup order above is what makes them reachable from `lang="pt"`, `lang="pt-PT"`,
`lang="zh"`, `lang="zh-Hans"` and `lang="zh-Hans-CN"` — no separate `pt`/`zh` alias registration is
needed. They are still 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
`registerLyraLocale('de', { close: '…' })` still overrides individual keys, and a per-instance
`.strings` still wins over both. Importing a catalog registers it; it does not _select_ it —
`setLyraLocale()` or `<html lang>` still chooses. What the import does do is make the locale show up
in `getRegisteredLyraLocales()`, and therefore in `<lr-locale-picker>`, so the set you import is the
set a user can switch between.

### Smaller catalogs: `@aceshooting/lyra-ui/translations/<locale>/<family>.js`

Each locale above is also published as twelve smaller, side-effect-only **family slices** — one per
component family (`agent-tools`, `charts`, `conversation`, `data`, `forms`, `layout`, `media`,
`overlays`, `retrieval`, `utility`, `viewers`), plus `shared` for the handful of messages more than
one family reaches (roving-focus/overlay/a11y strings like `collapse`, `open`, `search`). Import only
the families the application actually renders instead of the whole-locale aggregate above:

```ts
import "@aceshooting/lyra-ui/translations/fr/forms.js"; // lr-input, lr-select, lr-combobox, ...
import "@aceshooting/lyra-ui/translations/fr/data.js"; // lr-table, lr-tree, lr-data-grid, ...
import "@aceshooting/lyra-ui/translations/fr/shared.js"; // cross-cutting strings both families reach
```

`@aceshooting/lyra-ui/translations/fr.js` is unchanged: it is now a thin aggregate that imports every
slice above, so the plain whole-locale import from the previous section keeps working exactly as
before — this is a purely additive, opt-in way to shrink a non-English bundle, mirroring the
per-component tree-shaking English defaults already get for free. A component's family is the
directory it ships under (`src/components/<family>/<name>/`); when in doubt, import the aggregate and
measure, or import `shared` alongside whichever family slices you do import so a cross-cutting string
is never silently missing.

### Pluralized messages

A message may be a plain string or a **`LyraPluralMessage`** — an object keyed by CLDR plural
category, one string per category the language needs:

```ts
import { registerLyraLocale } from "@aceshooting/lyra-ui/localization.js";

registerLyraLocale("en", {
  viewerSearchMatchCount: { one: "{count} match", other: "{count} matches" },
});
registerLyraLocale("ru", {
  viewerSearchMatchCount: {
    one: "{count} совпадение",
    few: "{count} совпадения",
    many: "{count} совпадений",
    other: "{count} совпадения",
  },
});
```

- **The categories are `zero | one | two | few | many | other`** — the values
  `Intl.PluralRules.prototype.select()` can return. A language uses only the subset its grammar
  needs: English and German `one`/`other`, Russian `one`/`few`/`many`/`other`, Arabic all six,
  Japanese and Chinese only `other`.
- **`other` is required.** It is the terminal step of the category fallback chain, so every
  selection is guaranteed to land on a real string. TypeScript enforces it; the remaining five keys
  are optional. A missing intermediate category widens to a grammatical neighbour before falling
  back to `other`.
- **Selection is driven by `values.count`**, run through `Intl.PluralRules` at the component's
  effective locale — never at the locale the catalog was authored in, so an unregistered locale
  still pluralizes correctly against whatever strings it does have.
- **`pluralCount` is the escape hatch for a pre-formatted count.** When `{count}` must render as
  locale-grouped text (`Intl.NumberFormat` output is a string, and `'1,024'` cannot select a
  category), pass the display string as `count` and the raw number as `pluralCount`. A non-finite
  or absent value selects `other`.

**Breaking in 8.0.0:** a catalog that paired a singular key with a separate `<key>Plural` key must be
rewritten as one object-valued entry. The old spelling is not read, and nothing warns — the plural
key becomes an unused entry and the singular renders for every count. Fold the pair into
`{ one: …, other: … }` under the singular key's name.

## RTL and direction

Direction is inherited from the platform `dir` cascade; locale/`lang` selection does not change it,
and no component forces its own. Pair an RTL locale with `dir="rtl"` — ask
`getLyraLocaleDirection(tag)` rather than hard-coding a list of RTL tags, and note that
`<lr-locale-picker>`'s `lr-change` detail already carries the picked locale's `direction`, so
applying it is `document.documentElement.dir = event.detail.direction`. Layout mirrors through CSS
logical properties. Where physical math is unavoidable — drag ratios, arrow-key direction, anchored
placement — components share one internal direction helper: `isRtl(el)` (used by `lr-multi-split`,
`lr-time-range`, `lr-dock-panel`), plus `rtlAwareSide(side, el)` and `rtlAwarePlacement(placement,
el)`, which swap the `left`/`right` component of a value under RTL and pass it through unchanged
under LTR (`lr-menu` resolves its `placement` this way). These are implementation detail, not a
published subpath — resolve direction in your own code with `getComputedStyle(el).direction`, which
is the same answer through the same inheritance. Test both directions for anything with horizontal
order, start/end
placement, drag deltas, or previous/next navigation.

## Provider-neutral AI types: `@aceshooting/lyra-ui/ai`

The agentic components share one vocabulary, exported as types from a dedicated subpath. Use these
instead of hand-rolling state shapes — they bind field-for-field onto the components, with no
adapter layer:

```ts
import {
  createAgentStreamState,
  reduceAgentStream,
  adaptAiSdkMessage,
  AgUiStreamAdapter,
  adaptA2UiSurface,
  type AgentRun,
  type ChatMessage,
  type MessagePart,
  type RetrievalChunk,
} from "@aceshooting/lyra-ui/ai";
```

- **Run/step state** — `AgentStatusKind`, `AgentStatus`, `AgentStep`, `AgentRun`
- **Conversation** — `ChatMessage`, ordered `MessagePart` variants, `ToolInvocation`
- **Documents & grounding** — `DocumentRef`, `Citation`, `RetrievalQuery`, `RetrievalChunk`,
  `RetrievalScoreBreakdown`, `GroundedClaim`, `GroundingAssessment`, `DocumentLocator`
- **Streaming runtime** — `AgentStreamEvent`, `AgentStreamState`, `createAgentStreamState()`,
  `reduceAgentStream()`, `reduceAgentStreamEvents()`; every event carries a monotonic `generation`
  and strictly increasing `sequence`. A newer generation atomically retires the previous run, while
  an older or replayed cursor is ignored. JSON Patch input is structurally validated and rejects
  prototype-mutating paths.
- **Protocol adapters** — `adaptAiSdkMessage()`, `AgUiStreamAdapter`, and `adaptA2UiSurface()` map
  structural provider messages, events, and documents onto the neutral runtime without pulling
  vendor SDKs into the package. Feed AG-UI events through `new AgUiStreamAdapter().push(event)`.
  Adapter inputs are treated as untrusted data, recursively snapshotted, and rejected without
  throwing when malformed, non-serializable, or over their configured budgets.
- **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
  `DEFAULT_A2UI_ADAPTER_LIMITS` constants document the defaults; invalid limit values fall back to
  them. Runtime breaches become an explicit error state/event, while snapshot/A2UI rejection
  returns `null` or an empty adapter result as documented by that boundary.
- **Message-part invariants** — `MessagePartState` is transport-only (`'streaming' | 'complete'`):
  failures use an `ErrorMessagePart` or the owning domain error. Tool results are a success/error
  union, and a `type: 'data'` part contains exactly one of `data` or `widget`.
- **Event payloads** — `RunLifecycleEventDetail`, `RetrievalProgressEventDetail`,
  `CitationSelectEventDetail`, `ToolApprovalEventDetail`, `CancelEventDetail`, `RetryEventDetail`,
  `ExportEventDetail`

These structural, provider-agnostic types correspond to the component inputs above; map a vendor
payload onto them at the edge.

### Task-first AI composition guide

- **Render one model response:** `lr-message-parts`; use `lr-chat-message` only when the message
  shell (avatar, author, actions) is also needed.
- **Build the main prompt affordance:** `lr-prompt-input`; it already composes attachments,
  model/voice/source controls, mentions/commands, and `lr-prompt-queue`.
- **Run an agent workspace:** `lr-agent-workspace` + `reduceAgentStream()`; add
  `lr-subagent-panel` for nested runs and `lr-mcp-app` only for executable MCP App resources.
- **Show grounded output:** `lr-rag-answer`; pass claim records for `lr-claim-evidence`, use
  `lr-retrieval-compare` for retrieval tuning and `lr-rag-eval-dashboard` for run metrics.
- **Develop prompts/tools:** `lr-prompt-studio` and `lr-json-schema-viewer`.
- **Build voice sessions:** `lr-realtime-session`; it composes the existing audio visualizer,
  push-to-talk control, and transcript feed while leaving transport ownership with the host.

Family registration entry points are additive: importing
`@aceshooting/lyra-ui/components/conversation`, `/agent-tools`, or `/retrieval` registers and
exports that complete family. Granular component entry points remain the smallest bundles and are
preferred in production.

## Optional peer dependencies

All 29 peers are optional, in two groups. The 26 component-facing peers remain outside the default
install; components load them on demand where applicable. React, Svelte, and Vue are
compile-time-only peers for their matching
opt-in declaration entries (`custom-elements-jsx`, `svelte`, and `vue`): those entries emit empty
JavaScript, no component loads a framework, and Lyra ships no runtime wrapper. `llms/peers.md` is the
generated peer-role/component table. Loading and failure UI for component peers is
component-specific: viewer sections document their localized loading/error/notice states, while
`lr-include` preserves its light-DOM fallback/live region and emits `lr-include-error` when its
sanitizer is unavailable. Some components additionally issue a deduped warning. Consult the owning
component section instead of assuming every peer user renders an `<lr-skeleton>` or the same
degraded state. `lr-phone-input` is the exception to dynamic peer import: it takes a consumer-built
adapter (`loadLibphonenumberAdapter()`) rather than importing `libphonenumber-js` itself.

## Framework integration

Plain custom elements, so they work anywhere — with the usual two caveats. React 19/JSX, Vue 3,
and Svelte 5 projects can opt into the generated declarations shown under "TypeScript" without
installing or shipping a wrapper; import the normal granular registration entry separately.

- **Complex values must be property-bound, not attribute-bound.** An attribute stringifies:
  `rows="[object Object]"`. Use the framework's property syntax for anything that isn't a string,
  number, or boolean: Lit `.rows=${rows}`, Vue `:rows.prop="rows"` (or `.rows="rows"`), Angular
  `[rows]="rows"`, Svelte `bind:this` + assignment, React 19+ passes objects to custom-element
  properties natively (earlier React needs a ref).
- **Events are dashed custom events.** Lit `@lr-change=${…}`, React 19
  `onlr-change={…}`, Vue `@lr-change="…"`, Angular `(lr-change)="…"`, and Svelte 5
  `onlr-change={…}` (or the legacy `on:lr-change={…}`). Earlier React versions use
  `ref.addEventListener('lr-change', …)`.
- **Angular** additionally needs `CUSTOM_ELEMENTS_SCHEMA` in the module/component that uses the tags.
- In-DOM templates lower-case attribute names; camelCase property names only survive in framework
  templates and JS, never in hand-written HTML attributes.
- **Dev-mode unknown-attribute diagnostics ignore framework-owned scoping/debug attributes.**
  Angular's default emulated view encapsulation writes `_ngcontent-*`/`_nghost-*` scoping markers
  onto every element it manages, its dev builds add `ng-reflect-*` input reflections and
  `ng-version`, and Vue's scoped styles add `data-v-*` — none of these trigger the unknown-attribute
  warning. A genuinely misspelled or unsupported attribute still warns.

## SSR and declarative shadow DOM

Root, `all.js`, and granular component imports are server-safe under Node 20+.
`@aceshooting/lyra-ui/ssr/all.js` is the **server-only** convenience entry: unlike the browser
`all.js`, it registers the complete inventory including the optional-peer families — defining those
tags never imports their peers (each component loads its own lazily, client-side), and the
browser-bundle argument for excluding them does not apply to a server render. Use the public
`@aceshooting/lyra-ui/ssr-loader.js` entry for the tested Lit SSR contract. Its exported
`LYRA_SSR_SUPPORT_MATRIX`, `LYRA_SSR_RENDER_AND_HYDRATE_TAGS`, and
`LYRA_SSR_CLIENT_RENDER_TAGS` classify every inventory tag exactly once:

- `render-and-hydrate`: `@lit-labs/ssr` emits Declarative Shadow DOM, and the client reuses the
  existing shadow root and nodes.
- `client-render`: the server emits the host's serializable attributes and light DOM with no shadow
  template; the component renders when its definition upgrades in the browser. Use this for initial
  renders that require light-DOM traversal, layout, canvas, observers, media, or other browser APIs.

Server setup (the fallback must precede Lit's renderer):

```ts
import { lyraSsrElementRenderers } from "@aceshooting/lyra-ui/ssr-loader.js";
import { render, LitElementRenderer } from "@lit-labs/ssr";
import { html } from "lit";

const result = render(html`<lr-page><main>Dashboard</main></lr-page>`, {
  elementRenderers: lyraSsrElementRenderers(LitElementRenderer),
});
```

In the browser, import `@aceshooting/lyra-ui/ssr-loader.js` before any other module that can import
Lit. This installs `@lit-labs/ssr-client/lit-element-hydrate-support.js` before component
registration. `getLyraSsrMode(tagName)` reads one tag's tier, and
`diagnoseLyraHydration(document)` inspects current Lyra hosts in the supplied tree and every
reachable open shadow root, awaits registered hosts' current updates, and reports `ready`,
`unregistered`, `missing-shadow-root`, or `update-failed`. `ready` means the current update finished
and a shadow root exists; it does not claim that server markup was observed or hydrated. Read each
diagnostic's separate `mode` to distinguish the declared `render-and-hydrate` and `client-render`
tiers.

The loader preserves optional-peer isolation: import a root-excluded component's granular
registration after the loader. A fallback cannot serialize JS property bindings, so put initial
server state in attributes/light DOM or assign it client-side. A `render-and-hydrate` component
whose rendering depends on something only a browser can answer — its own light-DOM children, or a
browser global such as `EyeDropper` — reproduces the server's answer on the hydrating render and
corrects itself on the next update, so a slotted override lands one frame after hydration; a
browser-only mount is unaffected and renders the final result the first time. Layout/observer/canvas/media work
begins after hydration, and remote content is client-only.

**If hydration never runs at all** — a page that intentionally ships no script bundle, a reader
that fetches the raw HTML, or a crawler — a `render-and-hydrate` tag's declarative-shadow-DOM
output is either permanently complete and correct on its own, or only ever promised once hydration
executes; nothing in between is supported. `getLyraSsrStaticSafety(tagName)` (also
`LYRA_SSR_SUPPORT_MATRIX.declarativeShadowDom.staticSafety[tagName]`) returns which:
`'static-safe'` is the first guarantee, `'hydration-required'` is the second. Every
`render-and-hydrate` tag has one of the two; `pnpm test:ssr` fails closed on any tag that does
not, so there is no silent third case. Do not infer `'static-safe'` from a component "looking
static" — check the classification, because two components that look equally static can differ:

- `lr-details` is `'static-safe'`. Its native `<details>`/`<summary>` toggle is bound with a Lit
  *property* binding (`.open=${this.open}`), which the SSR renderer reflects to a real `open`
  attribute in the server markup, and the click listener that vetoes a user toggle is registered
  only by the component's own (unexecuted, without hydration) lifecycle code. With hydration JS
  never running, both facts together mean the browser's native disclosure behavior is what
  answers a click — so `lr-details` renders in the correct open/closed state and keeps expanding
  and collapsing indefinitely, with zero JavaScript.
- A canvas-painted component such as `lr-chart` is `'hydration-required'`: a `<canvas>`
  element has no pixels until script draws to it, so without hydration the server markup is
  present but visibly empty forever, not merely stale for one frame. `lr-lite-chart` is also
  `'hydration-required'`, but for a different reason: it renders real SVG (not canvas), and its
  default `layout="fit"` mode needs a ResizeObserver-measured host size before it can draw
  coordinate-based geometry, so without hydration it stays on its structurally-identical
  pre-measurement fallback rather than ever reaching final content.

## Testing form-associated components: `@aceshooting/lyra-ui/testing`

`@aceshooting/lyra-ui/testing` exports `installHappyDomFormAssociatedShims(): void` for test
environments without usable `ElementInternals`. In that environment, form participation is inert
while components retain local validity and state behavior. Install the helper once before assertions
that need form-value or validity behavior: it supplies
`setFormValue()`, `setValidity()`, `checkValidity()`, `reportValidity()`, and readonly
`form`/`labels`/`validity`/`validationMessage`/`willValidate`. The shim is a no-op where the
platform already provides internals, so it is safe in a shared setup file.

## Constructing a validated test event: `createLyraEvent()`

`@aceshooting/lyra-ui/testing` also exports
`createLyraEvent(tag, name, detail?): CustomEvent`, for a downstream suite that wants to dispatch
one specific `lr-*` component's documented event — at a listener under test, without rendering the
real component — instead of hand-rolling a `CustomEvent` and guessing its shape and flags:

```ts
import { createLyraEvent } from '@aceshooting/lyra-ui/testing';

const event = createLyraEvent('lr-confirm-bar', 'lr-approve', { args: null, waitUntil: () => {} });
event.cancelable; // true — lr-confirm-bar's own lr-approve call site is cancelable
target.dispatchEvent(event);
```

`tag` and `name` are checked against that component's own generated event map: an event name the
tag does not document, an unregistered tag, or a `detail` of the wrong shape are all compile
errors. `bubbles` and `composed` are always `true` (every `lr-*` event is), and `cancelable` is
looked up per tag and event from the component's own documented contract, so a listener that calls
`preventDefault()` on a genuinely cancelable event is actually exercised — the exact case a
hand-built event with a guessed `cancelable` value silently skips. `detail` is always optional,
even where the real component's own type makes it required, so a test that only cares about the
dispatched event's flags does not have to fabricate a realistic one; an omitted or `undefined`
detail becomes `null`, matching `LyraElement.emit()`'s own normalization. `createLyraEvent()`
builds the event only — dispatch it yourself with `target.dispatchEvent(event)`.

Scope: covers every `lr-*`-named event a component documents. A component's native-named
re-emits (`input`, `change`, `blur`, `focus`, ...) already have real DOM event types and dispatch
semantics of their own that this factory does not model.

## Driving a component's real activation path: interaction drivers

For the exact gap `createLyraEvent()` leaves open — choosing an option, submitting a confirm
decision, toggling a switch, activating a step — `@aceshooting/lyra-ui/testing` exports a small
set of typed interaction drivers, one per interaction, that go through the real component's own
activation path (its own shadow-part lookup and `.click()`, the same as its own tests) instead of
a downstream suite reverse-engineering internal detail shapes or shadow-part selectors itself:

```ts
import {
  chooseOption,
  submitConfirmDecision,
  toggleSwitch,
  activateStep,
} from '@aceshooting/lyra-ui/testing';

await chooseOption(combobox, 'banana'); // opens the listbox, clicks the matching [part="option"] row
await submitConfirmDecision(confirmBar, 'approved'); // clicks [part="approve-button"]
await toggleSwitch(switchEl); // calls switchEl.click(), lr-switch's own activation path
await activateStep(stepper, 'review'); // clicks the [part="step"] button for that stepId (or pass an index)
```

`chooseOption()` accepts any of `<lr-combobox>`, `<lr-select>`, `<lr-model-select>`,
`<lr-locale-picker>` and `<lr-voice-picker>` — every component that independently implements the
same `[part="option"]` row plus `data-value` delegated-click pattern for its own listbox/popup.
`submitConfirmDecision()`
accepts either `<lr-confirm-bar>` or `<lr-tool-approval-dialog>`, which render the identical
`[part="approve-button"]`/`[part="deny-button"]` pair for the same `lr-approve`/`lr-deny`
contract.

Each driver is `async` and awaits `updateComplete` before returning, so assertions written
immediately after it see fully-settled DOM/state. Each one also throws a plain `Error` — never a
silent no-op — when the requested interaction cannot actually happen: the target is disabled, the
option owner/stepper is read-only or has no matching row/step currently rendered, or the confirm
bar is already decided. That is the exact failure mode a hand-rolled event misses (for example
dispatching a confirm event without `cancelable`, which makes a `preventDefault()`-based
pending-state handler a silent no-op that still looks tested) — these drivers exercise the
component for real, so a precondition that blocks the interaction is surfaced as a thrown error
instead of quietly doing nothing.

Pure DOM operations only (`Element.click()`, shadow-part queries, public properties) — no
`@web/test-runner`/CDP-only helper, so they also run under a downstream suite's own
happy-dom/jsdom environment, not only a real browser.

Scope: one driver per interaction named above. Not a general "drive any component" toolkit —
render the real component and interact with it directly for anything else.

## Awaiting a lazily registered mount: `waitForLyraElement()` and `waitForToast()`

An imperative API can register its elements lazily -- `toast()` dynamically `import()`s
`<lr-toast>`/`<lr-toast-item>` on first call (a deliberate bundle-size trade: importing the package
root, or even `toast()` itself, never pulls the element classes into an eagerly loaded bundle). A
fire-and-forget `toast(...)` call -- the normal application pattern, since a component should not
block its own flow on a toast -- therefore leaves the document empty for at least one microtask
after the call returns. `@aceshooting/lyra-ui/testing` exports `waitForLyraElement()` for this shape
in general, plus `waitForToast()` as the named convenience for `toast()` specifically:

```ts
import { waitForToast } from '@aceshooting/lyra-ui/testing';

toast('Saved'); // fire-and-forget; toast.class.js/toast-item.class.js may still be importing
const item = await waitForToast('Saved'); // resolves once a matching <lr-toast-item> mounts
expect(item.textContent?.trim()).to.equal('Saved');
```

`waitForToast(match?, options?)` resolves once a `<lr-toast-item>` is connected and upgraded. A
string `match` compares against the item's trimmed `textContent` (what `toast('Saved')` sets
verbatim); pass a predicate — `(item: LyraToastItem) => boolean` — for anything else (a substring,
an icon/action check, a specific variant); omitting `match` resolves the first toast item to mount.

The underlying `waitForLyraElement<T>(selector, options?)` is generic over any element reachable
from `options.root` (`document` by default): it resolves once an element matching `selector` is
both connected and upgraded — registered with a constructor the element is actually an instance of
— filtered further by an optional `options.match: (element: T) => boolean`. An element already
present in markup before its class registers (the SSR/hydration case) is not a match until it
upgrades. Both resolve via `MutationObserver` (new elements arriving) and
`customElements.whenDefined()` (an already-connected-but-undefined element finishing registration)
rather than polling on a timer, and both reject with an Error describing the selector, the timeout,
and how many non-matching candidates were found — after a bounded `options.timeoutMs` (2000ms
default). Every underlying API is standard DOM/HTML with no `@web/test-runner`/CDP dependency, so
both also run under a downstream suite's own happy-dom environment, not only a real browser.

Scope: awaiting a lazy mount reachable from a root you already have a handle to. Not a replacement
for `updateComplete` (a mounted element may still have a pending render) or for the interaction
drivers above (already-mounted components' own activation paths). `toast()` is currently the only
imperative `lyra-ui` API that registers its elements through a dynamic `import()`; `confirm()`
registers `<lr-dialog>` synchronously (a static import plus an idempotent `defineElement()` call) and
mounts its transient dialog before returning, so it has no equivalent gap.

## happy-dom's custom-property resolver and host-to-part token forwarding

In 16.0.0, seven built-in controls that each compose a real
`<lr-icon-button>` for their icon-only action — `<lr-copy-button>`, `<lr-dialog>` (whose close
button is inherited by `<lr-drawer>`), `<lr-reorder-item>`, `<lr-message-actions>`,
`<lr-attachment-trigger>`, `<lr-code-block>` (shared by `<lr-code-block-core>`), and `<lr-callout>`
— captured the composed control's public `--lr-icon-button-*` tokens on their own `:host` and
forwarded that private token back onto the SAME public token name on the `[part]` rendering the
composed control, so that an ancestor theme override still reached the composed child instead of
being shadowed by the component's own default. That was legal under the CSS Custom Properties spec
— `:host` and `[part]` resolve on different elements, so a real browser resolves the host
declaration to a concrete value first and the part substitutes that, and per-element cycle detection
never fired — but **happy-dom does not model that element boundary**. Its `CSSComputedStyle` merges
ancestor and own-element custom properties into a single flat map with no notion of which element
declared what, and (at least through 20.14.5, the newest release at time of writing)
`CSSVariableFormatter.resolveVariables` substitutes into that map recursively with no visited set
and no depth cap — so the capture-and-forward pair resolved into each other forever, throwing an
unhandled `RangeError: Maximum call stack size exceeded` from `CSSVariableFormatter.resolveVariables`
on every render of any of the seven components. Every test still reported as passing — there was no
failing assertion to point at — but the runner counted the unhandled errors and exited non-zero
anyway, which read as unrelated flakiness rather than a CSS issue.

**Current versions are unaffected.** `<lr-icon-button>` now carries a private
`--_lr-icon-button-<token>-default` fallback tier for every paint token (background, color, border,
and their hover/active variants — the same shape its corner radius already used via
`--_lr-icon-button-radius-default`), and each composing component sets its own default directly on
that private tier rather than re-declaring the public token name. `<lr-icon-button>`'s own
stylesheet still checks the public token first, so an ancestor override reaches a composed control
exactly as before, but no descendant declares a public `--lr-icon-button-*` token from a private
token that was itself derived from that same public token — so no resolver, scoped or flattened,
ever sees a cycle. A project still hitting the `RangeError` above should upgrade
`@aceshooting/lyra-ui`; the workarounds that version range needed (patching or upgrading the DOM
implementation to cycle-aware/depth-limited custom-property resolution, or running the affected
suites against a real browser engine) are no longer necessary once it does.

## Accessibility contract

Semantic roles live on the shadow-DOM element that owns them, with explicit false states for
toggle/selection/expansion ARIA attributes and deliberate host-name forwarding. Form-associated
controls preserve `ElementInternals`, reset, validity, focus, and native editing behavior. Reusable
layouts respond to their allocated container rather than the viewport, and decorative or infinite
motion simplifies under `prefers-reduced-motion: reduce`.

Keyboard model: a composite widget (menu, tab group, tree, table, calendar, carousel, segmented
control) is a single tab stop using a roving `tabindex`; arrow keys move within it and skip disabled, hidden,
`aria-hidden` and `inert` items; `Home`/`End` jump to the ends; `Enter` and `Space` both activate;
`Escape` dismisses the topmost dismissible overlay and returns focus to whatever opened it.
`ArrowLeft`/`ArrowRight` mean previous/next and swap under `dir="rtl"`.

**`accessibleLabel` binds to one of two different attributes depending on the component, and the
two are not interchangeable.** Most components (e.g. `lr-card`, `lr-stat`) expose it as a direct
alias of the native `aria-label` attribute — `accessible-label="…"` does nothing on those; write
`aria-label="…"` instead. A minority (e.g. `lr-callout`, `lr-table`) separately compute an internal
accessible name and expose `accessibleLabel` through the bespoke `accessible-label` attribute
instead, specifically so the host's own native `aria-label` can still independently override that
computed name. Check the component's own reference section (or its class JSDoc) for which
convention it uses before writing markup — an `accessible-label` attribute on an `aria-label`-only
component is a silent no-op, not an error.

Lyra UI does not make a formal assistive-technology conformance claim or provide a VPAT. For the
documented accessibility scope and how to report an accessibility issue, see
<https://github.com/aceshooting/lyra-ui/blob/main/docs/accessibility.md>.

## Editor and tooling integration

The published package ships machine-readable metadata for editors:
`custom-elements.json` (Custom Elements Manifest), `web-types.json` (JetBrains, zero-config), and
`vscode-html-data.json` / `vscode-css-data.json` (point `html.customData` / `css.customData` at them
in `.vscode/settings.json`). For an agent, `llms/components/<tag>.md` is the cheaper source; these
files matter when scaffolding a project's editor configuration. Build tools can import the manifest
through the explicit `@aceshooting/lyra-ui/custom-elements.json` package export; native Node ESM
uses `with { type: 'json' }` on that import.

**Inherited members in `custom-elements.json`.** A subclass declaration's `cssParts` array is
always the complete flattened set, including everything inherited from a superclass — `::part()`
has no type-level inheritance chain a consumer could otherwise walk. `attributes`, `members`,
`events`, `slots`, and `cssProperties` are the opposite: a subclass declaration lists only its own
entries plus any inherited entry it explicitly overrides, pruning an inherited-and-unmodified entry
of those four kinds. This is intentional, not a gap — a TypeScript/JS consumer already gets the
full set for free from the generated `.d.ts` `extends` chain, the same resolution `web-types.json`
and `vscode-html-data.json` perform ahead of time. A consumer reading `custom-elements.json`
directly and needing the complete `attributes`/`members`/`events`/`slots`/`cssProperties` set for
those four kinds must walk the declaration's own `superclass.name`/`superclass.module` across
`modules[].declarations[]` itself, or read `web-types.json`/`vscode-html-data.json` instead, which
are already fully resolved.

**Which tags an entry registers, and which message keys it can reach (`registrations.json`).** A
stable per-tag entry (`@aceshooting/lyra-ui/components/lr-<name>.js`) can, at import time, define
more than one custom element: importing `lr-table.js` also registers `<lr-empty>`,
`<lr-pagination>`, `<lr-skeleton>` and `<lr-spinner>`, because `lr-table`'s registration entry
imports those composed children's own registration entries before defining `<lr-table>` itself.
`custom-elements.json` declares one custom element per family source module, with no field for a
stable per-tag entry specifier and none for the extra tags importing it registers as a side effect.
For that, read the generated `@aceshooting/lyra-ui/registrations.json` instead (`schemaVersion: 1`):
`{ entries: [{ tag, entry, registrationModule, distModule, registers, localeKeys }],
integrations: [{ entry, registrationModule, distModule, registers, localeKeys }] }`. Every
`entries` row describes the stable per-tag alias above and always carries `tag`. `integrations`
lists the published integration-bridge specifiers, which install an integration — an optional-peer
resolver, a lazy document-format registrar — without being any single component's own alias, so
they carry no `tag`: `components/media/flag/flag-peer.js`,
`components/viewers/archive-viewer/archive-viewer-register.js` and
`components/viewers/ebook-viewer/ebook-viewer-register.js`, the three imports a per-tag alias cannot
stand in for. They are a separate array rather than tag-less rows mixed into `entries`, so a reader
that keys `entries` by `tag` keeps working; `integrations`, `distModule` and `localeKeys` are all
additive, which is why the schema version is unchanged. `registrationModule` is the `src/` path used
internally; `distModule` is that same module's own published deep specifier (e.g.
`./components/data/table/table.js`) so a caller holding either a per-tag alias or a deep import can
resolve the other without reading `src/` or walking `dist/` — for an integration bridge,
`distModule` equals `entry`, since there is no separate alias. `registers` is every `lr-*` tag
importing `entry` defines, direct or transitive, derived from the same transitive-import analysis
`scripts/check-component-dependencies.mjs` already performs against the real registration graph
(not a second hand-maintained list). `localeKeys` is every `LyraMessageKey` the registered tags can
reach — including a key reached only through an indirect lookup table (e.g. `lr-attachment-trigger`'s
`{ triggerKey: 'attachmentTriggerFiles' }`-shaped map), because it reuses
`generate-default-string-slices.mjs`'s own reachability walk rather than a literal-`localize()`-only
scan. All of it is regenerated by `pnpm run registration-graph`.

## Independence and migration

Lyra has no runtime, theme, or design-token dependency on Shoelace or Web Awesome. Documented `wa-*`
comparisons are migration references only; Lyra's own tokens, events, localization runtime, and
implementation are the source of truth. `llms/migration.md` holds the generated per-tag
`exact`/`rewritten`/`warning-required`/`conceptual-only`/`unsupported` decision and every declared
member/default/import rewrite. Only the first two classifications are automatic; use the codemod's
location-aware report rather than treating a README relationship as a rename allowlist.

Security-motivated differences remain explicit. `lr-include` sanitizes every fragment, omits a
script-executing mode, and defaults to same-origin fetches. Its post-sanitization transclusion is
network-silent and non-interactive: anchors remain only for resolvable same-document `#fragment`
links (rebased per include instance); every other navigation or resource attribute, including
`href`, `src`, `srcset`, `action`, `ping`, and `poster`, is stripped, so images do not load.
Form-control and custom-element wrappers are unwrapped to safe ordinary text or children, while
controls with no passive content are removed. Link-like controls strip `opener` and force-add
`noopener noreferrer` whenever `target` is set while preserving other settable author tokens where
the component exposes `rel`; iframe/media/viewer inputs keep their URL validation, sandbox, size
caps, and generation guards. A use that depends on weaker behavior is left unchanged with a warning.
For a staged theme migration, map existing values onto `--lr-theme-*` explicitly in application CSS
rather than expecting an implicit compatibility layer.

## Family barrels

Each of the eleven component families has an entry point that registers every element in it:
`@aceshooting/lyra-ui/components/forms`, `.../components/overlays`, and so on for `agent-tools`,
`charts`, `conversation`, `data`, `layout`, `media`, `retrieval`, `utility` and `viewers`.

They existed for three families before 8.0.0, were in the exports map, and were documented nowhere —
so they were effectively unreachable. All eleven now exist and are listed here.

A family barrel is **side-effectful by design**: importing it registers every tag in that family, the
same way `all.js` registers all of them (the package root itself registers nothing as of 8.0.0 — see
"Importing and registering components"). Reach for one when you genuinely use most of a family
and want a single import; reach for the granular
`@aceshooting/lyra-ui/components/<tag>.js` path when you do not, because a barrel cannot be
tree-shaken down to the two elements you actually render. The tag-shaped path remains stable if a
component moves between Lyra's internal family folders; existing family-shaped registration paths
remain supported.

```js
import "@aceshooting/lyra-ui/components/forms"; // every form control
import "@aceshooting/lyra-ui/components/lr-input.js"; // just <lr-input>
```

---

## Shared helpers: `utilities/`

Not custom elements — infrastructure the components compose, curated into a supported public
surface. Importable one module per helper, e.g.
`@aceshooting/lyra-ui/utilities/positioner.js` — the `.js` is required — or as a whole from the extensionless
`@aceshooting/lyra-ui/utilities`.

**This replaced `@aceshooting/lyra-ui/internal/*` in 8.0.0. `@aceshooting/lyra-ui/internal/*` is no
longer a published subpath** — the import fails to resolve rather than degrading. The whole
`internal/` tree used to be exported with no stability statement, which made every internal
refactor potentially breaking for someone. The helpers below are the supported surface and are
covered by semver. Each subpath and the extensionless barrel use explicit named exports, so an
implementation helper added to `internal/` does not silently become public. Rewriting an existing
supported import is a path swap and nothing more:

```ts
// before 8.0.0
import { place } from "@aceshooting/lyra-ui/internal/positioner.js";
// 8.0.0
import { place } from "@aceshooting/lyra-ui/utilities/positioner.js";
```

If you were importing something from `internal/` that is not listed below, it was never a supported
entry point. After getting the user's explicit agreement, submit a capability request through the
feature-request API described in "When no component fits" so it can be promoted deliberately.

- **`LyraElement`** — the base class. `static styles = [tokens]`;
  subclasses prepend `LyraElement.styles` to their own `static styles`. Supplies `emit()` (see
  "Events"), the typed `addEventListener` overload (see "TypeScript"), `locale`/`strings` (see
  "Localization"), and protected `localize()` / `effectiveLocale` / `effectiveDirection`, all
  memoized once per update cycle. `LyraEmitOptions { cancelable?: boolean }` is the public options
  object accepted by `emit()`; set `cancelable` only for a real, branch-on-veto operation.
- **`catalog` → `LyraCatalogEntry` and `LyraCatalog<T>`** — type-only shared vocabulary for model,
  voice, and future catalog-backed controls. Import it from
  `@aceshooting/lyra-ui/utilities/catalog.js`; both types are also available from the package root
  and the model-select/voice-picker granular entries. The exact contracts are `LyraCatalogEntry {
id: string; label: string }` and `LyraCatalog<T extends LyraCatalogEntry = LyraCatalogEntry> =
readonly string[] | readonly T[]`. A catalog is homogeneous: use string shorthand (the same
  string becomes both id and label) or typed object rows, never a mixed array. Readonly tuples and
  arrays are accepted, and object catalogs retain an extended row type such as
  `LyraModelCatalogEntry` or `LyraVoiceCatalogEntry`.
- **`anchor-target` → `LyraAnchorTarget` and `LyraAnchorTargetEventMap`** — type-only structural
  contracts for viewers that expose Lyra's shared document-anchor surface. Import them from
  `@aceshooting/lyra-ui/utilities/anchor-target.js` when a host, adapter, or external viewer needs
  to accept or implement `highlights`, `activeHighlightId`, `anchor`, `anchorKinds`, and
  `scrollToAnchor(target)` without importing the internal mixin. The event map types the shared
  `lr-highlight-activate`, `lr-text-select`, and `lr-anchor-result` listener vocabulary; a concrete
  viewer can support only the events it actually emits, as documented on that component.
  The exact structural contract is `LyraAnchorTarget { highlights: readonly LyraHighlight[];
activeHighlightId: string | null; anchor: LyraAnchor | string | null; readonly anchorKinds:
readonly LyraAnchorKind[]; scrollToAnchor(target: LyraAnchor | string): Promise<boolean> }`.
  Assigning `highlights` synchronously creates a frozen array of copied, frozen highlight records;
  malformed records without a non-empty string `anchor.kind` are omitted, while each accepted
  record's otherwise-opaque `anchor` retains caller identity so reference-based anchor jumps still
  work.
- **`positioner` → `place(anchor, popup, opts?): () => void`, `trackRect(target, onUpdate(rect)): () =>
void`, and `virtualAnchorFromRect()`** — thin wrapper over `@floating-ui/dom`'s
  `computePosition` + `autoUpdate`. Forces `strategy: 'fixed'` (matching the
  popup's own `position: fixed` CSS — otherwise it lands offset by the page scroll), middleware
  `offset(opts.offset ?? 4)`, `flip()`, `shift({ padding: 8 })`, default `placement: 'bottom-start'`.
  Returns a cleanup function that stops the `autoUpdate` loop — call it in `disconnectedCallback()`.
  `trackRect()` reports the target's initial viewport rect exactly once before returning, follows
  later layout/viewport changes, and returns the same cleanup shape.
  `virtualAnchorFromRect()` adapts a live rectangle provider to the exported `VirtualAnchor`
  contract; `PlaceOptions` and its closed-set placement/sizing types are exported for typed wrappers.
  The structural result is `PlacementResult { placement: Placement; arrow?: { x?: number;
y?: number } }`, where `arrow`
  contains its resolved coordinates when supplied. `VirtualAnchor` exposes
  `getBoundingClientRect()` and optional `contextElement`; `virtualAnchorFromRect({ x, y, width?,
height?, contextElement? })` builds one. `PlaceOptions` exposes `placement`, `strategy`, `offset`,
  `skidding`, `boundary`, `flip`, `flipFallbackPlacements`, `flipFallbackStrategy`, `flipBoundary`,
  `flipPadding`, `shift`, `shiftBoundary`, `shiftPadding`, `padding`, `autoSize`,
  `autoSizeBoundary`, `autoSizePadding`, `sync`, `arrow`, `arrowPadding`, `hoverBridge`, and
  `onPlaced(result)`.
  Exact authoring contracts are `VirtualAnchor { getBoundingClientRect(): DOMRect;
contextElement?: Element }`, `virtualAnchorFromRect(rect: { x: number; y: number; width?: number;
height?: number; contextElement?: Element }): VirtualAnchor`, and `PlaceOptions { placement?:
Placement; strategy?: PlaceStrategy; offset?: number; skidding?: number; boundary?:
PlaceBoundary; flip?: boolean; flipFallbackPlacements?: Placement[]; flipFallbackStrategy?:
PlaceFlipFallbackStrategy; flipBoundary?: PlaceBoundary; flipPadding?: number; shift?: boolean;
shiftBoundary?: PlaceBoundary; shiftPadding?: number; padding?: number; autoSize?: PlaceAutoSize;
autoSizeBoundary?: PlaceBoundary; autoSizePadding?: number; sync?: PlaceSync; arrow?: HTMLElement;
arrowPadding?: number; hoverBridge?: HTMLElement; onPlaced?: (result: PlacementResult) => void }`.
  `place()` and `virtualAnchorFromRect()` throw `RangeError` before registering observers, invoking
  callbacks, or writing styles when coordinates/options are non-finite, dimensions or padding are
  negative; finite signed `offset`/`skidding` stay valid. If a previously valid live anchor later
  returns invalid geometry, positioning stops and rolls back without publishing partial state or a
  placement callback.
  Used by `lr-combobox`, `lr-select`, `lr-date-input`, `lr-export-button`, `lr-model-select`,
  `lr-mention-popover`, `lr-tool-call-chip`, `lr-citation-badge`, and `lr-menu`.
- **`prefix`** — `LYRA_PREFIX = 'lr'`; `tag(name)` → `` `lr-${name}` ``; `defineElement(name, ctor)`,
  an idempotent `customElements.define` that is safe if a module is evaluated twice.
  Exact callable contracts are `tag(name: string): string` and
  `defineElement(name: string, ctor: CustomElementConstructor): void`.
- **`a11y`** — `nextId(scope)`, a monotonic id generator (`nextId('combobox-list')` →
  `"lr-combobox-list-3"`); `srOnly`, a visually-hidden-but-AT-visible class. The callable contract
  is `nextId(scope: string): string`.
- **`icons`** — the shared inline-SVG set (`calendarIcon`, `chevronIcon`, `closeIcon`, `expandIcon`,
  `eyeIcon`, `eyeOffIcon`, `fileIcon`, `folderIcon`, `pauseIcon`, `playIcon`, and `spinnerIcon`).
  One 24×24 viewBox per icon, rendered at `1em` so each inherits the
  caller's font size; none bakes in a direction — callers rotate the wrapping `part` via CSS.
  Each is a zero-argument template factory: `calendarIcon(): SVGTemplateResult`,
  `chevronIcon(): SVGTemplateResult`, `closeIcon(): SVGTemplateResult`,
  `expandIcon(): SVGTemplateResult`, `eyeIcon(): SVGTemplateResult`,
  `eyeOffIcon(): SVGTemplateResult`, `fileIcon(): SVGTemplateResult`,
  `folderIcon(): SVGTemplateResult`, `pauseIcon(): SVGTemplateResult`,
  `playIcon(): SVGTemplateResult`, and `spinnerIcon(): SVGTemplateResult`.
- **`scroll-lock` → `lockScroll(doc = document): () => void`** — ref-counted
  `doc.documentElement` scroll lock (used by `lr-widget`'s fullscreen mode); safe to acquire/release
  concurrently, restores the original `overflow` only when the last lock releases.
- **`form-associated` → `FormAssociated(Base)`**, plus `attachInternalsSafely()` and
  `createFallbackInternals()` — the mixin documented under "Form association" above, exposed so an
  application can build its **own** form-associated control alongside Lyra's and have it
  participate in a form, restore on reset, and report validity the same way every `lr-` control
  does. Reach for it instead of hand-rolling `attachInternals()` when a bespoke control has to sit
  in the same `<form>` as these. `attachInternalsSafely()` inspects own and inherited data
  descriptors without reading accessors, calls an eligible implementation once, and returns the
  fallback internals for a missing, accessor-backed, non-callable, or throwing capability.
  The free-function signatures are `attachInternalsSafely(host)`,
  `createStringArrayFormDataState(name, values)`, `readStringArrayFormDataState(state)`, and
  `FormAssociated(Base, valueAdapter?)`. For a non-string value, pass a typed
  `FormValueAdapter<T>` as that `valueAdapter`;
  `FormSubmissionValue`, `createStringArrayFormDataState()`,
  `readStringArrayFormDataState()`, `isEmptyFormValue()`, and `stringFormValueAdapter` are the
  retained adapter-building seams. Form-owner mutation, validity barring, anchor installation, and
  other mixin implementation helpers are deliberately not exported.
  `FormValueAdapter<T>` has readonly `empty`, required `toFormValue(value)`, and optional
  `toFormState(value)`, `isEmpty(value)`, `fromAttribute(attribute)`, `toAttribute(value)`, and
  `fromFormState(state)`. `FormAssociatedInterface<T>` exposes `internals`; the `name` getter/setter
  (`next`); `value`; `defaultValue`; `customError`; `disabled`; `required`; readonly
  `effectiveDisabled`; the `form` getter/setter (`owner`); readonly `labels`, `validity`,
  `validationMessage`, and `willValidate`; `setFormValue(next)`; `getForm()`; `checkValidity()`;
  `reportValidity()`; `setCustomValidity(message)`; `resetValidity()`; `formResetCallback()`; and
  `formStateRestoreCallback(state, reason)`.
  The exact callable signatures are `attachInternalsSafely(host: HTMLElement): ElementInternals`,
  `createFallbackInternals(): ElementInternals`, `createStringArrayFormDataState(name: string,
values: readonly string[]): FormData`, `readStringArrayFormDataState(state: string | File |
FormData | null): string[]`, `isEmptyFormValue(value: unknown): boolean`, and
  `FormAssociated<T, TValue = string>(Base: T, valueAdapter?:
FormValueAdapter<TValue>): T & Constructor<FormAssociatedInterface<TValue> &
FormAssociatedSubclassInterface<TValue>>`.
  The exact adapter records are `FormValueAdapter<TValue> { readonly empty: TValue;
toFormValue(value: TValue): FormSubmissionValue; toFormState?(value: TValue):
FormSubmissionValue; isEmpty?(value: TValue): boolean; fromAttribute?(attribute: string): TValue;
toAttribute?(value: TValue): string | null; fromFormState?(state: FormSubmissionValue): TValue }`
  and `FormAssociatedInterface<TValue> { internals: ElementInternals; get name(): string; set
name(next: string | null); value: TValue; defaultValue: TValue; customError: string | null;
disabled: boolean; required: boolean; readonly effectiveDisabled: boolean; get form():
HTMLFormElement | null; set form(owner: FormOwnerValue); readonly labels: NodeList; readonly
validity: ValidityState; readonly validationMessage: string; readonly willValidate: boolean;
setFormValue(next: TValue): void; getForm(): HTMLFormElement | null; checkValidity(): boolean;
reportValidity(): boolean; setCustomValidity(message: string): void; resetValidity(): void;
formResetCallback(): void; formStateRestoreCallback(state: FormSubmissionValue, reason:
'autocomplete' | 'restore'): void }`. The exported subclass seam is
  `FormAssociatedSubclassInterface<TValue> { protected captureLiveValueCheckpoint(): { readonly
value: TValue; readonly dirty: boolean }; protected restoreLiveValueCheckpoint(checkpoint: {
readonly value: TValue; readonly dirty: boolean }): void }`.
- **`group-by-recency` → `groupByRecency(items, options?)`** — buckets dated items into
  Today / Yesterday / Previous 7 Days / Older, on **local calendar-day boundaries** ("yesterday" is
  the previous calendar date, not 24–48 hours ago). Plain data in, plain data out — no DOM.
  `getTimestamp` extracts the date (default: the item _is_ a `Date`; a returned number is epoch
  **milliseconds**), `now` fixes the reference instant for deterministic tests or an "as of" report,
  and `labels` overrides any of the four English defaults — the strings are yours, so localize them
  through your own catalog. Empty buckets are omitted, order within a bucket is the input's, a
  future timestamp lands in Today and an unparseable one in Older. Exposed because an application
  rendering its own list beside `lr-thread-list` needs bucketing that agrees with the component's;
  reimplementing "this week" is how two lists on one page start disagreeing about what day it is.
  The typed records are `RecencyLabels { today?; yesterday?; previousWeek?; older? }`,
  `GroupByRecencyOptions<T> { getTimestamp?(item); now?; labels? }`, and
  `RecencyBucket<T> { label; items }`.
  The callable signature is `groupByRecency<T>(items: T[], options?:
GroupByRecencyOptions<T>): RecencyBucket<T>[]`.
- **`defined` → `allDefined(root?, options?): Promise<void>`** — iteratively waits for every
  currently rendered, inventory-known Lyra tag below a `Document`, `DocumentFragment`/open
  `ShadowRoot`, or `Element` to be defined in its owning/scoped registry. It also waits for each
  available `updateComplete`, then repeats so tags created by that first render are included. Open
  shadow roots are traversed without recursive calls; unknown `lr-*` names are ignored instead of
  hanging. `AllDefinedOptions` bounds the complete operation with `maxElements` (default `10_000`),
  `maxRoots` (`2_000`), `maxDepth` (`256`), `maxWork` (`100_000`), and `maxPasses` (`100`). Invalid
  limits throw `RangeError`; exceeding a limit rejects instead of resolving with a partial
  readiness result. Consumer-owned elements with throwing registry or update-completion accessors
  are treated as unavailable while valid siblings continue. With no browser document or registry
  it resolves immediately. It **does not import or define components**: pair it with explicit
  registration imports, `discover()`, or
  `start()` when bootstrap/tests need a readiness barrier.
  The exact options record is `AllDefinedOptions { readonly maxPasses?: number; readonly
maxElements?: number; readonly maxRoots?: number; readonly maxDepth?: number; readonly maxWork?:
number }`.
- **`css-length` → `resolveCssLength(value, options?)`** — resolves finite numbers and CSS
  `px`/`rem`/`em`/`%`/`vw`/`vh` lengths to pixels without allocating DOM. Supply `host` for live
  font and owner-realm context, `percentBase` for percentages, and an optional `viewportBasis` for
  deterministic viewport-unit resolution: either a `Window` or `{ inlineSize, blockSize }`.
  Unsupported expressions and unavailable context return `undefined`; range policy remains the
  caller's responsibility.
  Its exact signatures are `resolveCssLength(value: number | string | undefined, options?:
ResolveCssLengthOptions): number | undefined` and `ResolveCssLengthOptions { readonly host?:
Element; readonly percentBase?: number; readonly viewportBasis?: Window | Readonly<{
inlineSize: number; blockSize: number }> }`.
- **`format` → `formatNumber(value, locale?, options?)`, `formatDate(value, locale?, options?)`,
  `formatRelativeTime(value, locale?, options?)`, and `formatBytes(value, locale?, options?)`** —
  pure, string-returning wrappers over the same memoized `Intl` formatter cache and locale
  resolution `<lr-format-number>`, `<lr-format-date>`, `<lr-relative-time>`, and `<lr-format-bytes>`
  render through. Reach for these when you need a formatted **string** rather than a rendered
  element: interpolating into a message template, populating a text-only property on another
  component (a stat tile's value, a chart tick label, a badge's cost text), building a search
  predicate, or composing an accessibility announcement.
  An omitted `locale` (or the explicit `'auto'` sentinel) on any of the four resolves to the page's
  active `setLyraLocale()` locale, exactly like a rendered `<lr-*>` component with no closer
  `locale`/`lang` override — not a hardcoded `'en'`. It falls back to `'en'` only once no active
  locale has ever been set, so an app that never calls `setLyraLocale()` sees no change. An
  explicit BCP-47 tag always stays authoritative over the active locale.
  `formatNumber()` and `formatBytes()` accept a `bigint` or a decimal/integer string, not just a
  `number`, for exact-precision input (large ids, monetary amounts, exact byte counts) — a plain
  `number` is a float64 and cannot exactly represent an integer beyond `Number.MAX_SAFE_INTEGER` or
  most decimal fractions. `formatBytes()` still selects its unit (`byte`..`petabyte`/`bit`..
  `petabit`) from an approximate magnitude, since which unit is only ever a display choice, but
  computes the displayed amount itself with exact `bigint` division, so the digits a `bigint`/string
  input carries are never rounded away. `formatDate()` and `formatRelativeTime()` accept the same
  date sources as `<lr-format-date>`/`<lr-relative-time>`'s `date` property (an ISO/date string,
  epoch milliseconds, or a `Date`) and return `undefined` for an unresolvable source instead of
  throwing; `formatBytes()` likewise returns `undefined` for a non-finite or unparseable `value`.
  `formatNumber()` and invalid `options` on any of the four throw the same error
  `Intl.NumberFormat`/`Intl.DateTimeFormat`/`Intl.RelativeTimeFormat`'s own constructor would.
  `formatRelativeTime()`'s `options.unit` accepts an explicit unit or `'auto'` (default) to pick
  the largest unit the magnitude clears, matching `<lr-relative-time unit="auto">`'s heuristic;
  `options.now` fixes the reference instant for a deterministic test or an "as of" report. It is a
  one-shot computation — pair it with your own timer, or use `<lr-relative-time sync>`, for text
  that must stay current while displayed.
  The exact signatures are `formatNumber(value: number | bigint | string, locale?: string,
options?: Intl.NumberFormatOptions): string`, `formatDate(value: string | number | Date, locale?:
string, options?: Intl.DateTimeFormatOptions): string | undefined`,
  `formatRelativeTime(value: string | number | Date, locale?: string,
options?: LyraFormatRelativeTimeOptions): string | undefined`, and `formatBytes(value: number |
bigint | string, locale?: string, options?: LyraFormatBytesOptions): string | undefined`.
  `LyraFormatRelativeTimeOptions { readonly unit?: LyraRelativeTimeUnit | 'auto'; readonly format?:
LyraFormatDisplay; readonly numeric?: LyraRelativeTimeNumeric; readonly now?: number }` and
  `LyraFormatBytesOptions { readonly unit?: LyraFormatBytesUnit; readonly display?:
LyraFormatDisplay; readonly unitStep?: number; readonly decimals?: number }`.

  ```ts
  import { formatBytes, formatRelativeTime } from "@aceshooting/lyra-ui/utilities/format.js";

  const size = formatBytes(12_345_678_901_234_567_890n, "en-US"); // exact, no float rounding
  const updated = formatRelativeTime(item.updatedAt, "en-US"); // "3 days ago"
  ```
- **`layered-layout` → `layeredLayout()`** — the deterministic, dependency-free layered-DAG
  ("Sugiyama-lite") layout `lr-flow-canvas` draws with: cycle handling, longest-path layering,
  barycenter crossing reduction, and coordinates assigned along the block axis so the result is
  RTL-neutral. `fixedPositions` entries keep their given coordinates: their combined inline extent
  is reserved before computed boxes, and a fixed layer's block extent advances every later layer,
  so fixed and computed boxes retain `gapX`/`gapY` separation without moving the anchors. Two
  conflicting caller-fixed boxes are deliberately kept verbatim. Node dimensions, gaps, and fixed
  coordinates must be finite, non-negative values no greater than `Number.MAX_SAFE_INTEGER`; bad
  geometry throws `RangeError` before graph traversal. Traversal is iterative, and
  `maxVirtualWaypoints` sets the nonnegative integer routing budget (default 10,000; invalid values
  use the default, negative values clamp to zero, and fractions truncate). The returned
  `LayeredLayoutResult` contains readonly `positions`, `virtualWaypointCount`, and `truncated`;
  when truncated, long edges influence ordering through their real endpoints instead of allocating
  every intermediate layer. Positions are raw box centers; the first computed layer starts at
  `y = 0`, so its centers are offset by half that layer's height. Centering the drawing in your own
  canvas is yours.
  Its exact data contracts are `LayeredLayoutNode { id; width; height }`,
  `LayeredLayoutEdge { source; target }`, `LayeredLayoutOptions { fixedPositions?:
ReadonlyMap<string, Readonly<{ x: number; y: number }>>; gapX?: number; gapY?: number;
maxVirtualWaypoints?: number }`, and `LayeredLayoutResult { readonly positions:
ReadonlyMap<string, Readonly<{ x: number; y: number }>>; readonly truncated: boolean; readonly
virtualWaypointCount: number }`. The callable contract is `layeredLayout(input: { nodes: readonly
LayeredLayoutNode[]; edges: readonly LayeredLayoutEdge[]; options?: LayeredLayoutOptions }):
LayeredLayoutResult`. Call `layeredLayout(input)` with `input.nodes`, `input.edges`, and
  optional `input.options`; the result's `positions` map contains readonly `{ x, y }` coordinates.
- **`animation-registry` → `setDefaultAnimation(animationName, animation)`,
  `setAnimation(element, animationName, animation)`, and
  `getAnimation(element, animationName, options?)`** — public
  motion overrides in native Web Animations API vocabulary. Resolution is per-element first,
  page-wide default second, then the component's token-derived fallback. `rtlKeyframes` supplies a
  logical-direction alternative; `getAnimation()` infers computed direction unless `options.dir`
  is explicit. Passing `null` disables visible motion without skipping the owning component's
  events or promise lifecycle. Each setter returns an idempotent cleanup that restores the previous
  stacked registration; element registrations live in a `WeakMap`, so neither the registry nor a
  retained cleanup keeps a detached element alive. Each registration takes a bounded shallow
  frozen snapshot of its readonly keyframe arrays, keyframe records, and options, so later caller
  mutation cannot alter another component's motion; `getAnimation()` returns a fresh readonly
  frozen snapshot. Each logical direction retains at most 512 keyframes, a keyframe may carry at
  most 256 enumerable own fields, and the options record may carry at most 64. An oversized or
  getter-throwing JavaScript record is retained as an inert override: resolution uses the caller's
  valid bounded fallback, or the zero-duration disabled result when no valid fallback exists.
  Reduced motion is respected by default by
  flattening delay/duration/end-delay to zero and iterations to one while preserving the resolved
  end frame; only a caller with a stronger policy should pass `respectReducedMotion: false`.
  The exact records are `LyraElementAnimation { readonly keyframes: readonly Readonly<Keyframe>[];
readonly rtlKeyframes?: readonly Readonly<Keyframe>[]; readonly options?:
Readonly<KeyframeAnimationOptions> }`, `LyraResolvedElementAnimation { readonly keyframes:
readonly Readonly<Keyframe>[]; readonly options: Readonly<KeyframeAnimationOptions> }`, and
  `LyraGetAnimationOptions { readonly dir?: 'ltr' | 'rtl'; readonly fallback?:
LyraElementAnimation | null; readonly respectReducedMotion?: boolean }`. The callable contracts are
  `setDefaultAnimation(animationName: string, animation: LyraElementAnimation | null):
LyraAnimationCleanup`, `setAnimation(element: Element, animationName: string, animation:
LyraElementAnimation | null): LyraAnimationCleanup`, and `getAnimation(element: Element,
animationName: string, options?: LyraGetAnimationOptions): LyraResolvedElementAnimation`.

  ```ts
  import {
    setAnimation,
    type LyraElementAnimation,
  } from "@aceshooting/lyra-ui/utilities/animation-registry.js";

  const dialog = document.querySelector("lr-dialog");
  const enter: LyraElementAnimation = {
    keyframes: [{ opacity: 0 }, { opacity: 1 }],
    options: { duration: 180 },
  };
  const release = setAnimation(dialog, "dialog.show", enter);
  // release() restores the previous registration.
  ```

- **`overlay-manager` → `activateOverlay(options): OverlayHandle` and
  `suspendLyraModalsFor(externalModal): () => void`** — per-`Document` coordination used by Lyra's
  modal and focus-returning overlay surfaces, including dialogs/drawers, Page/app navigation,
  command/tool surfaces, lightbox/tour, and responsive/floating/fullscreen panels. All entries share
  one topmost stack: only the top entry handles Escape, Tab
  trapping, and backdrop dismissal. Content outside the active modal's composed path is inert,
  including lower overlays and page content added while it is open. Focus traversal crosses slots
  and open shadow roots; activation preserves focus already inside but pulls outside focus in, and
  closing restores the still-connected opener. Nested closes restore into the surviving overlay
  before returning to the original trigger. `OverlayActivationOptions.lockScroll` gives the manager
  document-scoped, ref-counted ownership of scroll locking for the entry's registered lifetime; it
  releases that ownership during disconnect or rendered suspension. `suspendWhenUnrendered` defaults
  to `false`. When enabled, an active entry whose resolved panel generates no CSS layout box —
  including because `display: none` is set on the host or an ancestor — releases inerting,
  focus-trap/stack ownership, and manager-owned scroll lock without changing the component's logical
  open state. It resumes in its original stack order when rendered again.
  `deactivate`'s `deferScrollLockRelease` option (default `false`) skips releasing the entry's
  scroll lock as part of deactivation and instead returns the release function, so a component with
  a visible exit animation can hold the lock until that animation actually finishes rather than the
  instant it starts closing; it is ignored (returns `undefined`) when the entry never requested
  `lockScroll`.
  `OverlayActivationOptions` exposes `host`, `panel`, optional `modalRoot`, `modal`, `lockScroll`,
  `suspendWhenUnrendered`, `onEscape`, `onBackdrop`, `preferredInitialFocus`,
  `beforeInitialFocus`, `restoreFocusTo`, `trapFocus`, and `onTab`. `OverlayHandle` exposes
  `focusInitial()`, `focusAutofocus()`, `updateRestoreFocusTo(target)`,
  `deactivate({ restoreFocus?, deferScrollLockRelease? }?)`, `suspend()`, `resume()`, `isTopmost()`,
  `isActive()`, and `dismissBackdrop()`; the deactivate argument is the exported
  `OverlayDeactivateOptions` record, and its return value is the deferred scroll-lock release
  function (or `undefined`).
  Exact records are `OverlayActivationOptions { host: HTMLElement; panel: () => HTMLElement |
null; modalRoot?: () => HTMLElement | null; onEscape: () => void; onBackdrop?: () => void;
preferredInitialFocus?: () => HTMLElement | null; beforeInitialFocus?: () => boolean;
restoreFocusTo?: OverlayRestoreFocusTarget; modal?: boolean; trapFocus?: boolean; onTab?: () =>
void; suspendWhenUnrendered?: boolean; lockScroll?: boolean }`, `OverlayDeactivateOptions {
restoreFocus?: boolean; deferScrollLockRelease?: boolean }`, and `OverlayHandle { focusInitial():
void; focusAutofocus(): boolean; updateRestoreFocusTo(target: OverlayRestoreFocusTarget): void;
deactivate(options?: OverlayDeactivateOptions): (() => void) | undefined; suspend(): void;
resume(): void; isTopmost(): boolean; isActive(): boolean; dismissBackdrop(): boolean }`.
  When a third-party modal must open above a Lyra modal, call the public helper after its root is
  connected, then release it when that modal closes:

  ```ts
  import { suspendLyraModalsFor } from "@aceshooting/lyra-ui/utilities/overlay-manager.js";

  const externalModal = document.querySelector<HTMLElement>("#vendor-modal")!;
  const release = suspendLyraModalsFor(externalModal);
  release(); // idempotent
  ```

  The handle is document-scoped and nestable. While any
  such handle is active, Lyra yields Escape/Tab ownership and keeps only the external modal paths
  non-inert; disconnecting or adopting the external root releases its handle automatically.

- **`announcer` → `Announcer` and `acquireAnnouncementSink()`** — throttled live-region
  announcements, paired with `lr-live-region`. `Announcer` is the DOM-free coalescing engine;
  `acquireAnnouncementSink(politeness, options?)` hands back the ref-counted, visually hidden region
  in the **host document's light DOM** that every Lyra announcement lands in (a live region inside a
  shadow root is not reliably announced). The module also exports `ANNOUNCEMENT_SINK_ATTRIBUTE` —
  the `data-lr-live-region` marker those regions carry — so a consumer's DOM diffing, snapshot
  testing, or `MutationObserver` can recognize and ignore them. Both are documented in full in
  `llms/components/lr-live-region.md`.
  The constructor accepts `AnnouncerOptions { throttleMs?; onFlush(text); timerHost? }`; each call
  accepts `AnnounceOptions { force? }`; and `AnnouncerTimerHost` provides `setTimeout(handler,
timeout)` plus `clearTimeout(handle)`. `AnnouncementSinkOptions` exposes `document`, `source`, and
  `messageTtlMs`; its `AnnouncementSink` handle exposes readonly `element` and `politeness`, mutable
  `messageTtlMs`, `announce(text)`, and `release()`.
  Exact sink contracts are `acquireAnnouncementSink(politeness: AnnouncementPoliteness, options?:
AnnouncementSinkOptions): AnnouncementSink`, `AnnouncementSinkOptions { document?: Document;
source?: Element; messageTtlMs?: number }`, `AnnouncementSink { readonly element: HTMLElement;
readonly politeness: AnnouncementPoliteness; messageTtlMs: number; announce(text: string): void;
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").
  `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**
  locale-dependent output in step with the components without reacting to every lazy catalog.

  `bridgeLyraLocale()` mirrors the active locale's canonical public tag onto an element's `lang`
  and — unless `direction: false` — its `dir`, resolved through `getLyraLocaleDirection()`.
  `setLyraLocale()`
  only tells _this library_ which locale is in force; `:lang()` selectors, hyphenation and quote
  marks, spelling dictionaries, a screen reader's pronunciation of untranslated prose and every
  third-party widget all read the platform `lang`/`dir` cascade instead, so an application that
  switches locale at runtime has to write those attributes itself. This is that glue, in one
  supported place. `target` defaults to `document.documentElement`; pass an application root to
  scope it to a subtree. It is strictly opt-in — importing the module does nothing, and the library
  never calls it for you. While no locale is active it leaves the target's authored `lang`/`dir`
  alone rather than blanking them. Multiple bridges on the same target share one subscription and
  authored-state snapshot; cleanup handles can release in any order, and the last release restores
  exactly what the target carried before the first bridge, including an attribute that was absent.
  Direction remains mirrored while any active handle leaves `direction` enabled.
  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 "@aceshooting/lyra-ui/translations/ar.js";

  const stop = bridgeLyraLocale(); // mirrors onto <html>
  setLyraLocale("ar"); // <html lang="ar" dir="rtl">
  stop(); // restores whatever <html> carried before
  ```

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

  ```ts
  import { resolveLyraScopedString } from "@aceshooting/lyra-ui/utilities/localization.js";

  const label = resolveLyraScopedString(host, "save", { save: "Save" });
  ```

**Known gotchas:**

- `formResetCallback()` restores the _content attribute_ default, so `el.value = 'x'` never redefines
  what `form.reset()` restores to (native `defaultValue`/`defaultSelected` semantics).

## Reference artifacts

The package includes authored family and shared references plus derived index, component, token,
peer, migration, and concatenated references.

## When no component fits, file it

First rule out a naming mismatch: check `llms/index.md` for a component covering the same job
under a different name. Most apparent gaps are discovery failures, not missing components.

Then check the live catalog — one read-only request, no side effects, nothing filed:

```bash
curl -sS 'https://www.lyra-ui.com/api/v1/components/search?q=kanban+board+swimlane'
```

It returns the closest components with doc links. Search as many phrasings as you like; this
endpoint is meant to be used freely, and it is the cheapest way to discover that a "missing"
component already exists under a name you did not guess.

If nothing fits, report the gap so it can be built — but **ask the user and get their explicit
agreement first.** Filing sends the user's description to an external service; show them what you
intend to submit, and never file as a silent side effect of noticing a gap. If the user has not
said yes, do not send it.

```bash
curl -sS -X POST https://www.lyra-ui.com/api/v1/feature-requests \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "Kanban board",
    "description": "Needed a drag-and-drop board with swimlanes for a task view; nothing in the catalog covers it.",
    "searched_for": ["kanban", "board", "swimlane", "drag drop"],
    "settled_for": "a hand-rolled div grid with HTML5 drag events",
    "agent": "claude-code"
  }'
```

Accepted fields: `title` (required, ≤120 chars), `description` (required, ≤4000 chars), `use_case`,
`searched_for` (array of terms tried — the most valuable field, since it records which name was
expected and that's exactly what makes a component undiscoverable), `settled_for` (what was used
instead), `agent`, and the optional contact fields `name` (≤120) and `email` (≤200). Anonymous
submission is the default and is fine — `name`/`email` only add value if the maintainer might
follow up. Ask the user whether they want to be reachable before adding either one; never invent,
guess, or reuse an address from context you happen to have (git config, an earlier message, the
environment). All submissions, including any name/email, are stored privately and shown only to
the maintainer — never published.

The response includes `matches` (the closest existing components, with doc links — read it, since
it often answers the gap outright) and an `id`; status is readable later at
`https://www.lyra-ui.com/api/v1/feature-requests/{id}`. The full schema is at
`https://www.lyra-ui.com/api/v1/openapi.json`.

**Never include private material.** Submissions leave the user's machine. Describe the component
generically — no source code, no client or product names, no file paths, no credentials. If the
need cannot be described without such details, do not file it.

Use the API even when you are working inside the lyra-ui repo itself. It is the only supported
automated intake path for an assistant acting on a user's behalf — do not write the request into a
local file instead, where nothing will pick it up, and do not silently open a GitHub issue. A person
filing their own report can use the human-facing routes in `SUPPORT.md`.

Keep the report short and concrete:

- **Name the component you wanted**, in library style (`lr-kanban-board`), so the gap is searchable.
- **Say what it had to do** in a sentence or two — the behaviour, not your implementation.
- **List the `lr-*` components you actually checked** and why each fell short. This is what separates
  a real gap from a naming mismatch, and it is the part only you can supply.

## Exported TypeScript contracts

These named interfaces and helper signatures are available to typed integrations. They are grouped by capability so the component sections above can stay focused.

- **`ai-adapters-a2ui-contracts`** — AI adapter and runtime contracts.
  `A2UiAdapterLimits {
  maxComponents: unknown;
  maxDepth: unknown;
  maxOutputNodes: unknown;
  maxChildrenPerComponent: unknown;
  maxNodes: unknown;
  maxBytes: unknown;
  maxStringCharacters: unknown;
}`
  `A2UiLikeAction {
  id: unknown;
  payload: unknown;
}`
  `A2UiLikeComponent {
  id: unknown;
  type: unknown;
  props: unknown;
  text: unknown;
  children: unknown;
  action: unknown;
}`
  `A2UiLikeSurface {
  surfaceId: unknown;
  rootId: unknown;
  components: unknown;
  data: unknown;
}`
  `adaptA2UiSurface(/* public names: surface, typeMap, limits */): unknown`

- **`ai-adapters-ag-ui-contracts`** — AI adapter and runtime contracts.
  `AgUiAdapterLimits {
  maxBufferedTools: unknown;
  maxToolArgumentBytes: unknown;
  maxTextDeltaCharacters: unknown;
  maxDepth: unknown;
  maxNodes: unknown;
  maxBytes: unknown;
  maxStringCharacters: unknown;
}`
  `AgUiLikeEvent {
  type: unknown;
  eventId: unknown;
  runId: unknown;
  messageId: unknown;
  role: unknown;
  delta: unknown;
  toolCallId: unknown;
  toolCallName: unknown;
  result: unknown;
  message: unknown;
  code: unknown;
  snapshot: unknown;
  messages: unknown;
}`

- **`ai-adapters-ai-sdk-contracts`** — AI adapter and runtime contracts.
  `adaptAiSdkMessage(/* public names: message, limits */): unknown`
  `AiSdkAdapterLimits {
  maxParts: unknown;
  maxDepth: unknown;
  maxNodes: unknown;
  maxBytes: unknown;
  maxStringCharacters: unknown;
}`
  `AiSdkLikeMessage {
  id: unknown;
  role: unknown;
  parts: unknown;
  metadata: unknown;
}`

- **`ai-runtime-contracts`** — AI adapter and runtime contracts.
  `AgentStreamLimits {
  maxMessages: unknown;
  maxPartsPerMessage: unknown;
  maxTools: unknown;
  maxDeltaCharacters: unknown;
  maxTextCharactersPerPart: unknown;
  maxIdentifierCharacters: unknown;
  maxStatusMessageCharacters: unknown;
  maxPatchOperations: unknown;
  maxSnapshotDepth: unknown;
  maxSnapshotNodes: unknown;
  maxSnapshotBytes: unknown;
  maxRetainedBytes: unknown;
}`
  `AgentStreamState {
  generation: unknown;
  cursor: unknown;
  limits: unknown;
  runId: unknown;
  status: unknown;
  messages: unknown;
  tools: unknown;
  sharedState: unknown;
  error: unknown;
  message: unknown;
  code: unknown;
}`
  `applySharedStatePatch(/* public names: value, patch */): unknown`
  `createAgentStreamState(/* public names: limits */): unknown`
  `parseJsonPatch(/* public names: value, limits */): unknown`
  `reduceAgentStreamEvents(/* public names: state, events */): unknown`
  `reduceAgentStream(/* public names: state, event */): unknown`

- **`ai-snapshot-contracts`** — AI adapter and runtime contracts.
  `createProviderSnapshotBudget(/* public names: limits */): unknown`
  `ProviderSnapshotBudget {
  limits: unknown;
  bytes: unknown;
  nodes: unknown;
}`
  `ProviderSnapshotLimits {
  maxDepth: unknown;
  maxNodes: unknown;
  maxBytes: unknown;
  maxStringCharacters: unknown;
}`
  `resolveProviderSnapshotLimits(/* public names: limits */): unknown`
  `snapshotProviderValue(/* public names: value, budget */): unknown`

- **`ai-types-contracts`** — AI adapter and runtime contracts.
  `AgentRun {
  id: unknown;
  status: unknown;
  startedAt: unknown;
  endedAt: unknown;
  model: unknown;
  costEstimate: unknown;
  steps: unknown;
}`
  `AgentStatus {
  kind: unknown;
  message: unknown;
}`
  `AgentStep {
  id: unknown;
  kind: unknown;
  label: unknown;
  status: unknown;
  startedAt: unknown;
  endedAt: unknown;
}`
  `AttachmentMessagePart {
  type: unknown;
  document: unknown;
  id: unknown;
  state: unknown;
  metadata: unknown;
}`
  `AudioMessagePart {
  type: unknown;
  src: unknown;
  transcript: unknown;
  mimeType: unknown;
  id: unknown;
  state: unknown;
  metadata: unknown;
}`
  `CancelEventDetail {
  reason: unknown;
}`
  `ChatMessage {
  id: unknown;
  role: unknown;
  status: unknown;
  timestamp: unknown;
  text: unknown;
  attachments: unknown;
  parts: unknown;
  metadata: unknown;
}`
  `Citation {
  id: unknown;
  chunkId: unknown;
  sourceId: unknown;
  span: unknown;
  start: unknown;
  end: unknown;
  label: unknown;
  locator: unknown;
  answerRange: unknown;
  quote: unknown;
  metadata: unknown;
}`
  `CitationMessagePart {
  type: unknown;
  citation: unknown;
  id: unknown;
  state: unknown;
  metadata: unknown;
}`
  `CitationSelectEventDetail {
  citation: unknown;
}`
  `DataMessagePart {
  type: unknown;
  name: unknown;
  data: unknown;
  widget: unknown;
  id: unknown;
  state: unknown;
  metadata: unknown;
}`
  `DocumentRef {
  id: unknown;
  name: unknown;
  mimeType: unknown;
  uri: unknown;
  version: unknown;
}`
  `ErrorMessagePart {
  type: unknown;
  message: unknown;
  code: unknown;
  retryable: unknown;
  id: unknown;
  state: unknown;
  metadata: unknown;
}`
  `ExportEventDetail {
  format: unknown;
}`
  `GroundedClaim {
  id: unknown;
  text: unknown;
  status: unknown;
  citationIds: unknown;
  answerRange: unknown;
  start: unknown;
  end: unknown;
  confidence: unknown;
  explanation: unknown;
}`
  `GroundingAssessment {
  supportedClaims: unknown;
  unsupportedClaims: unknown;
  coverage: unknown;
  confidence: unknown;
  warnings: unknown;
  claims: unknown;
}`
  `MessagePartBase {
  id: unknown;
  state: unknown;
  metadata: unknown;
}`
  `ReasoningMessagePart {
  type: unknown;
  text: unknown;
  collapsed: unknown;
  id: unknown;
  state: unknown;
  metadata: unknown;
}`
  `RetrievalChunk {
  id: unknown;
  text: unknown;
  score: unknown;
  source: unknown;
  metadata: unknown;
  rank: unknown;
  locator: unknown;
  queryId: unknown;
  stage: unknown;
  traceId: unknown;
  scores: unknown;
}`
  `RetrievalProgressEventDetail {
  queryId: unknown;
  stage: unknown;
  progress: unknown;
}`
  `RetrievalQuery {
  text: unknown;
  filters: unknown;
  mode: unknown;
  scope: unknown;
}`
  `RetrievalScoreBreakdown {
  dense: unknown;
  sparse: unknown;
  rerank: unknown;
  final: unknown;
}`
  `RetryEventDetail {
  attempt: unknown;
  messageId: unknown;
}`
  `RunLifecycleEventDetail {
  runId: unknown;
  status: unknown;
}`
  `TextMessagePart {
  type: unknown;
  text: unknown;
  id: unknown;
  state: unknown;
  metadata: unknown;
}`
  `ToolApprovalEventDetail {
  invocationId: unknown;
  approved: unknown;
}`
  `ToolCallMessagePart {
  type: unknown;
  invocation: unknown;
  id: unknown;
  state: unknown;
  metadata: unknown;
}`
  `ToolInvocation {
  id: unknown;
  name: unknown;
  args: unknown;
  status: unknown;
  result: unknown;
  error: unknown;
}`
  `ToolResultErrorMessagePart {
  error: unknown;
  result: unknown;
  type: unknown;
  invocationId: unknown;
  name: unknown;
  id: unknown;
  state: unknown;
  metadata: unknown;
}`
  `ToolResultSuccessMessagePart {
  result: unknown;
  error: unknown;
  type: unknown;
  invocationId: unknown;
  name: unknown;
  id: unknown;
  state: unknown;
  metadata: unknown;
}`
  `WidgetMessagePart {
  type: unknown;
  name: unknown;
  data: unknown;
  widget: unknown;
  id: unknown;
  state: unknown;
  metadata: unknown;
}`

- **`autoloader-contracts`** — Shared utility contracts.
  `AutoloaderErrorEventDetail {
  error: unknown;
  tag: unknown;
  optionalPeers: unknown;
}`
  `AutoloaderEventDetail {
  tag: unknown;
  optionalPeers: unknown;
}`
  `AutoloaderOptions {
  optionalPeers: unknown;
  events: unknown;
  maxConcurrency: unknown;
  maxElements: unknown;
  maxRoots: unknown;
  maxDepth: unknown;
  maxWork: unknown;
}`
  `AutoloaderTraversalErrorEventDetail {
  limit: unknown;
  maximum: unknown;
  error: unknown;
}`
  `discover(root?: LyraDefinitionRoot, options?: AutoloaderOptions): Promise<readonly AutoloadableTagName[]>`
  `start(root?: LyraDefinitionRoot, options?: AutoloaderOptions): Promise<readonly AutoloadableTagName[]>`
  `stop(): unknown`

- **`custom-elements-jsx-contracts`** — Framework integration type contracts.
  `LyraReactIntrinsicElements {
  "lr-accordion": unknown;
  "lr-accordion-item": unknown;
  "lr-activity-feed": unknown;
  "lr-agent-eval-dashboard": unknown;
  "lr-agent-run": unknown;
  "lr-agent-trace": unknown;
  "lr-agent-workspace": unknown;
  "lr-alert": unknown;
  "lr-animated-image": unknown;
  "lr-animation": unknown;
  "lr-app-rail": unknown;
  "lr-app-rail-group": unknown;
  "lr-app-rail-item": unknown;
  "lr-approval-queue": unknown;
  "lr-archive-viewer": unknown;
  "lr-artifact-panel": unknown;
  "lr-attachment-chip": unknown;
  "lr-attachment-trigger": unknown;
  "lr-audio-visualizer": unknown;
  "lr-av-player": unknown;
  "lr-avatar": unknown;
  "lr-avatar-group": unknown;
  "lr-badge": unknown;
  "lr-bar-chart": unknown;
  "lr-box-plot": unknown;
  "lr-branch-picker": unknown;
  "lr-breadcrumb": unknown;
  "lr-breadcrumb-item": unknown;
  "lr-browser-frame": unknown;
  "lr-bubble-chart": unknown;
  "lr-button": unknown;
  "lr-button-group": unknown;
  "lr-calendar": unknown;
  "lr-calendar-viewer": unknown;
  "lr-callout": unknown;
  "lr-card": unknown;
  "lr-carousel": unknown;
  "lr-carousel-item": unknown;
  "lr-chart": unknown;
  "lr-chat-composer": unknown;
  "lr-chat-message": unknown;
  "lr-chat-viewport": unknown;
  "lr-checkbox": unknown;
  "lr-checkbox-group": unknown;
  "lr-checkpoint": unknown;
  "lr-chip": unknown;
  "lr-chip-group": unknown;
  "lr-chunk-inspector": unknown;
  "lr-citation-badge": unknown;
  "lr-claim-evidence": unknown;
  "lr-code-block": unknown;
  "lr-code-block-core": unknown;
  "lr-code-editor": unknown;
  "lr-color-picker": unknown;
  "lr-combobox": unknown;
  "lr-command-palette": unknown;
  "lr-commit-card": unknown;
  "lr-community-card": unknown;
  "lr-compare-panel": unknown;
  "lr-condition-builder": unknown;
  "lr-confirm-bar": unknown;
  "lr-contact-viewer": unknown;
  "lr-context-inspector": unknown;
  "lr-context-meter": unknown;
  "lr-control-group": unknown;
  "lr-conversation-item": unknown;
  "lr-copy-button": unknown;
  "lr-csv-viewer": unknown;
  "lr-dashboard-grid": unknown;
  "lr-data-grid": unknown;
  "lr-dataset-viewer": unknown;
  "lr-date-input": unknown;
  "lr-date-picker": unknown;
  "lr-details": unknown;
  "lr-dialog": unknown;
  "lr-diff-view": unknown;
  "lr-divider": unknown;
  "lr-dock-panel": unknown;
  "lr-document-compare": unknown;
  "lr-document-library": unknown;
  "lr-document-preview": unknown;
  "lr-document-viewer": unknown;
  "lr-docx-viewer": unknown;
  "lr-doughnut-chart": unknown;
  "lr-drawer": unknown;
  "lr-drilldown-panel": unknown;
  "lr-drop-zone": unknown;
  "lr-dropdown": unknown;
  "lr-dropdown-item": unknown;
  "lr-ebook-viewer": unknown;
  "lr-email-viewer": unknown;
  "lr-embedding-explorer": unknown;
  "lr-emoji-picker": unknown;
  "lr-empty": unknown;
  "lr-entity-card": unknown;
  "lr-entity-chip": unknown;
  "lr-entity-dossier": unknown;
  "lr-env-list": unknown;
  "lr-eval-dataset": unknown;
  "lr-eval-result": unknown;
  "lr-eval-run": unknown;
  "lr-export-button": unknown;
  "lr-file-icon": unknown;
  "lr-file-input": unknown;
  "lr-file-tree": unknown;
  "lr-filter-bar": unknown;
  "lr-flag": unknown;
  "lr-flow-canvas": unknown;
  "lr-flow-controls": unknown;
  "lr-flow-minimap": unknown;
  "lr-flow-node": unknown;
  "lr-flow-run-status": unknown;
  "lr-format-bytes": unknown;
  "lr-format-date": unknown;
  "lr-format-number": unknown;
  "lr-funnel": unknown;
  "lr-gauge": unknown;
  "lr-generation-metrics": unknown;
  "lr-geojson-view": unknown;
  "lr-geojson-viewer": unknown;
  "lr-graph": unknown;
  "lr-graph-legend": unknown;
  "lr-graph-query-builder": unknown;
  "lr-grounding-summary": unknown;
  "lr-handoff-divider": unknown;
  "lr-heatmap": unknown;
  "lr-highlight-layer": unknown;
  "lr-histogram": unknown;
  "lr-html-viewer": unknown;
  "lr-icon": unknown;
  "lr-icon-button": unknown;
  "lr-image-comparer": unknown;
  "lr-image-viewer": unknown;
  "lr-include": unknown;
  "lr-ingestion-queue": unknown;
  "lr-input": unknown;
  "lr-intersection-observer": unknown;
  "lr-json-viewer": unknown;
  "lr-kbd": unknown;
  "lr-knowledge-base": unknown;
  "lr-knowledge-base-admin": unknown;
  "lr-knowledge-graph-explorer": unknown;
  "lr-known-date": unknown;
  "lr-lightbox": unknown;
  "lr-line-chart": unknown;
  "lr-lite-chart": unknown;
  "lr-live-region": unknown;
  "lr-locale-picker": unknown;
  "lr-map": unknown;
  "lr-markdown": unknown;
  "lr-markdown-core": unknown;
  "lr-mcp-app": unknown;
  "lr-media-card": unknown;
  "lr-memory-panel": unknown;
  "lr-mention-popover": unknown;
  "lr-menu": unknown;
  "lr-menu-item": unknown;
  "lr-menu-label": unknown;
  "lr-message-actions": unknown;
  "lr-message-feedback": unknown;
  "lr-message-parts": unknown;
  "lr-mind-map": unknown;
  "lr-model-select": unknown;
  "lr-model-settings-panel": unknown;
  "lr-multi-split": unknown;
  "lr-mutation-observer": unknown;
  "lr-native-time-input": unknown;
  "lr-neighbor-list": unknown;
  "lr-node-palette": unknown;
  "lr-notebook-viewer": unknown;
  "lr-number-input": unknown;
  "lr-option": unknown;
  "lr-otp-input": unknown;
  "lr-page": unknown;
  "lr-page-rail": unknown;
  "lr-pagination": unknown;
  "lr-pan-zoom": unknown;
  "lr-path-strip": unknown;
  "lr-pdf-viewer": unknown;
  "lr-phone-input": unknown;
  "lr-pie-chart": unknown;
  "lr-polar-area-chart": unknown;
  "lr-policy-summary": unknown;
  "lr-poll-status": unknown;
  "lr-popover": unknown;
  "lr-popup": unknown;
  "lr-pptx-viewer": unknown;
  "lr-progress-bar": unknown;
  "lr-progress-ring": unknown;
  "lr-prompt-input": unknown;
  "lr-prompt-queue": unknown;
  "lr-prompt-studio": unknown;
  "lr-provenance-panel": unknown;
  "lr-push-to-talk": unknown;
  "lr-qr-code": unknown;
  "lr-radar-chart": unknown;
  "lr-radio": unknown;
  "lr-radio-button": unknown;
  "lr-radio-group": unknown;
  "lr-rag-answer": unknown;
  "lr-rag-eval-dashboard": unknown;
  "lr-random-content": unknown;
  "lr-rating": unknown;
  "lr-realtime-session": unknown;
  "lr-relative-time": unknown;
  "lr-reorder-item": unknown;
  "lr-reorder-list": unknown;
  "lr-resize-observer": unknown;
  "lr-responsive-panel": unknown;
  "lr-result-card": unknown;
  "lr-result-field": unknown;
  "lr-retrieval-compare": unknown;
  "lr-retrieval-results": unknown;
  "lr-retrieval-search": unknown;
  "lr-retrieval-trace": unknown;
  "lr-rubric-form": unknown;
  "lr-scatter-chart": unknown;
  "lr-json-schema-viewer": unknown;
  "lr-scroller": unknown;
  "lr-segmented": unknown;
  "lr-select": unknown;
  "lr-selection-toolbar": unknown;
  "lr-sequence-playback": unknown;
  "lr-sequence-strip": unknown;
  "lr-skeleton": unknown;
  "lr-slider": unknown;
  "lr-source-card": unknown;
  "lr-source-list": unknown;
  "lr-source-picker": unknown;
  "lr-span-waterfall": unknown;
  "lr-sparkline": unknown;
  "lr-spinner": unknown;
  "lr-split-panel": unknown;
  "lr-spreadsheet-viewer": unknown;
  "lr-stack-trace": unknown;
  "lr-stat": unknown;
  "lr-stepper": unknown;
  "lr-stream-status": unknown;
  "lr-streaming-text": unknown;
  "lr-streaming-text-core": unknown;
  "lr-subagent-panel": unknown;
  "lr-suggestion-chips": unknown;
  "lr-svg-viewer": unknown;
  "lr-swatch-picker": unknown;
  "lr-switch": unknown;
  "lr-tab": unknown;
  "lr-tab-group": unknown;
  "lr-tab-panel": unknown;
  "lr-table": unknown;
  "lr-tag": unknown;
  "lr-task-list": unknown;
  "lr-terminal": unknown;
  "lr-test-results": unknown;
  "lr-textarea": unknown;
  "lr-thinking-panel": unknown;
  "lr-thread-list": unknown;
  "lr-time-input": unknown;
  "lr-time-range": unknown;
  "lr-timeline": unknown;
  "lr-timeline-item": unknown;
  "lr-toast": unknown;
  "lr-toast-item": unknown;
  "lr-token-input": unknown;
  "lr-tool-approval-dialog": unknown;
  "lr-tool-call-chip": unknown;
  "lr-tool-param-form": unknown;
  "lr-tool-result-dialog": unknown;
  "lr-tool-result-view": unknown;
  "lr-tool-select-dialog": unknown;
  "lr-tool-timeline": unknown;
  "lr-tooltip": unknown;
  "lr-tour": unknown;
  "lr-trace-tree": unknown;
  "lr-transcript-feed": unknown;
  "lr-tree": unknown;
  "lr-tree-item": unknown;
  "lr-typing-indicator": unknown;
  "lr-usage-badge": unknown;
  "lr-video": unknown;
  "lr-video-playlist": unknown;
  "lr-virtual-list": unknown;
  "lr-visually-hidden": unknown;
  "lr-voice-picker": unknown;
  "lr-widget": unknown;
  "lr-widget-renderer": unknown;
  "lr-word-cloud": unknown;
  "lr-xml-viewer": unknown;
  "lr-zoomable-frame": unknown;
}`

- **`internal-ansi-contracts`** — Shared utility contracts.
  `AnsiStyles {
  bold: unknown;
  dim: unknown;
  italic: unknown;
  underline: unknown;
  inverse: unknown;
  fg: unknown;
  bg: unknown;
}`

- **`internal-canvas-color-contracts`** — Shared utility contracts.
  `resolveCanvasColor(/* public names: scope, color, fallback */): unknown`
  `resolveCanvasColors(/* public names: scope, colors, fallback */): unknown`

- **`internal-localization-runtime-contracts`** — Shared utility contracts.
  `getLyraLocaleDirection(/* public names: locale */): unknown`
  `getLyraLocale(): unknown`
  `getRegisteredLyraLocaleKeys(/* public names: locale */): unknown`
  `getRegisteredLyraLocales(): unknown`
  `registerLyraLocale(/* public names: locale, strings, meta */): unknown`
  `resolveLyraDirection(/* public names: host */): unknown`
  `resolveLyraLocale(/* public names: host */): unknown`
  `setLyraLocale(/* public names: locale */): unknown`
  `subscribeLyraLocaleRegistry(/* public names: listener */): unknown`

- **`internal-localization-types-contracts`** — Shared utility contracts.
  `LyraLocaleMeta {
  dir: unknown;
  name: unknown;
}`

- **`internal-localization-contracts`** — Shared utility contracts.
  `resolveLyraString(/* public names: host, key, overrides, fallback, values */): unknown`

- **`internal-node-type-style-contracts`** — Shared utility contracts.
  `LyraNodeTypeStyle {
  id: unknown;
  label: unknown;
  color: unknown;
  shape: unknown;
}`

- **`internal-registered-animation-contracts`** — Shared utility contracts.
  `RegisteredAnimationSpec {
  keyframes: unknown;
  rtlKeyframes: unknown;
  durationProperties: unknown;
  easingProperties: unknown;
  fallbackDuration: unknown;
  fallbackEasing: unknown;
  options: unknown;
}`

- **`internal-text-viewer-target-contracts`** — Shared utility contracts.
  `LyraSearchChangeDetail {
  query: unknown;
  matchCount: unknown;
  matchCountExact: unknown;
  activeIndex: unknown;
}`
  `LyraTextViewerTarget {
  search: unknown;
  query: unknown;
  searchNext: unknown;
  searchPrevious: unknown;
  clearSearch: unknown;
  highlights: unknown;
  activeHighlightId: unknown;
  anchor: unknown;
  anchorKinds: unknown;
  scrollToAnchor: unknown;
  target: unknown;
}`

- **`ssr-contracts`** — Shared utility contracts.
  `buildLyraSsrStaticSafety(/* public names: tags, tagCapabilities, auditedStaticSafeTags */): unknown`
  Fail-closed classifier behind `LYRA_SSR_STATIC_SAFETY`/`getLyraSsrStaticSafety`: a tag present in
  neither a non-empty `tagCapabilities` entry nor `auditedStaticSafeTags` is reported in the result's
  `unaudited` list instead of silently defaulting to `'static-safe'`. Pure and fixture-friendly --
  `scripts/check-ssr.mjs` calls it with the real inventory, tests call it with small fixture lists.
  `deriveLyraSsrStaticSafety(/* public names: capabilities */): unknown`
  Derives static safety from one tag's capability record: any `'after-hydration'`/`'client-only'`
  entry makes it `'hydration-required'`; an empty record defaults to `'static-safe'`. That empty-
  record default is only valid for a record already known to reflect a completed review (as
  `LYRA_SSR_TAG_CAPABILITIES` entries do) -- `buildLyraSsrStaticSafety()` does not rely on it for a
  tag missing from that record entirely, which it instead routes through `auditedStaticSafeTags`.
  `diagnoseLyraHydration(/* public names: root */): unknown`
  `getLyraSsrMode(/* public names: tagName */): unknown`
  `getLyraSsrStaticSafety(/* public names: tagName */): unknown`
  Returns the static-safety classification for a `render-and-hydrate` Lyra tag, or `undefined` for a
  tag outside that tier. See "SSR and declarative shadow DOM" above for the full write-up.
  `LyraHydrationDiagnostic {
  element: unknown;
  tag: unknown;
  mode: unknown;
  status: unknown;
  error: unknown;
}`
  `LyraLitElementRendererConstructor {
  prototype: unknown;
  matchesClass: unknown;
  constructor: unknown;
  tagName: unknown;
  attributes: unknown;
}`
  `LyraSsrClientRenderReason {
  code: unknown;
  detail: unknown;
}`
  `LyraSsrStaticSafetyResult {
  classification: unknown;
  unaudited: unknown;
}`
  Return shape of `buildLyraSsrStaticSafety()`: `classification` holds one entry per classified tag
  (a tag absent from it was neither capability-bearing nor audited), and a non-empty `unaudited`
  means the check must fail closed.
  `lyraSsrElementRenderers(/* public names: litElementRenderer */): unknown`

- **`svelte-contracts`** — Framework integration type contracts.
  `LyraElementTagNameMap {
  "lr-accordion": unknown;
  "lr-accordion-item": unknown;
  "lr-activity-feed": unknown;
  "lr-agent-eval-dashboard": unknown;
  "lr-agent-run": unknown;
  "lr-agent-trace": unknown;
  "lr-agent-workspace": unknown;
  "lr-alert": unknown;
  "lr-animated-image": unknown;
  "lr-animation": unknown;
  "lr-app-rail": unknown;
  "lr-app-rail-group": unknown;
  "lr-app-rail-item": unknown;
  "lr-approval-queue": unknown;
  "lr-archive-viewer": unknown;
  "lr-artifact-panel": unknown;
  "lr-attachment-chip": unknown;
  "lr-attachment-trigger": unknown;
  "lr-audio-visualizer": unknown;
  "lr-av-player": unknown;
  "lr-avatar": unknown;
  "lr-avatar-group": unknown;
  "lr-badge": unknown;
  "lr-bar-chart": unknown;
  "lr-box-plot": unknown;
  "lr-branch-picker": unknown;
  "lr-breadcrumb": unknown;
  "lr-breadcrumb-item": unknown;
  "lr-browser-frame": unknown;
  "lr-bubble-chart": unknown;
  "lr-button": unknown;
  "lr-button-group": unknown;
  "lr-calendar": unknown;
  "lr-calendar-viewer": unknown;
  "lr-callout": unknown;
  "lr-card": unknown;
  "lr-carousel": unknown;
  "lr-carousel-item": unknown;
  "lr-chart": unknown;
  "lr-chat-composer": unknown;
  "lr-chat-message": unknown;
  "lr-chat-viewport": unknown;
  "lr-checkbox": unknown;
  "lr-checkbox-group": unknown;
  "lr-checkpoint": unknown;
  "lr-chip": unknown;
  "lr-chip-group": unknown;
  "lr-chunk-inspector": unknown;
  "lr-citation-badge": unknown;
  "lr-claim-evidence": unknown;
  "lr-code-block": unknown;
  "lr-code-block-core": unknown;
  "lr-code-editor": unknown;
  "lr-color-picker": unknown;
  "lr-combobox": unknown;
  "lr-command-palette": unknown;
  "lr-commit-card": unknown;
  "lr-community-card": unknown;
  "lr-compare-panel": unknown;
  "lr-condition-builder": unknown;
  "lr-confirm-bar": unknown;
  "lr-contact-viewer": unknown;
  "lr-context-inspector": unknown;
  "lr-context-meter": unknown;
  "lr-control-group": unknown;
  "lr-conversation-item": unknown;
  "lr-copy-button": unknown;
  "lr-csv-viewer": unknown;
  "lr-dashboard-grid": unknown;
  "lr-data-grid": unknown;
  "lr-dataset-viewer": unknown;
  "lr-date-input": unknown;
  "lr-date-picker": unknown;
  "lr-details": unknown;
  "lr-dialog": unknown;
  "lr-diff-view": unknown;
  "lr-divider": unknown;
  "lr-dock-panel": unknown;
  "lr-document-compare": unknown;
  "lr-document-library": unknown;
  "lr-document-preview": unknown;
  "lr-document-viewer": unknown;
  "lr-docx-viewer": unknown;
  "lr-doughnut-chart": unknown;
  "lr-drawer": unknown;
  "lr-drilldown-panel": unknown;
  "lr-drop-zone": unknown;
  "lr-dropdown": unknown;
  "lr-dropdown-item": unknown;
  "lr-ebook-viewer": unknown;
  "lr-email-viewer": unknown;
  "lr-embedding-explorer": unknown;
  "lr-emoji-picker": unknown;
  "lr-empty": unknown;
  "lr-entity-card": unknown;
  "lr-entity-chip": unknown;
  "lr-entity-dossier": unknown;
  "lr-env-list": unknown;
  "lr-eval-dataset": unknown;
  "lr-eval-result": unknown;
  "lr-eval-run": unknown;
  "lr-export-button": unknown;
  "lr-file-icon": unknown;
  "lr-file-input": unknown;
  "lr-file-tree": unknown;
  "lr-filter-bar": unknown;
  "lr-flag": unknown;
  "lr-flow-canvas": unknown;
  "lr-flow-controls": unknown;
  "lr-flow-minimap": unknown;
  "lr-flow-node": unknown;
  "lr-flow-run-status": unknown;
  "lr-format-bytes": unknown;
  "lr-format-date": unknown;
  "lr-format-number": unknown;
  "lr-funnel": unknown;
  "lr-gauge": unknown;
  "lr-generation-metrics": unknown;
  "lr-geojson-view": unknown;
  "lr-geojson-viewer": unknown;
  "lr-graph": unknown;
  "lr-graph-legend": unknown;
  "lr-graph-query-builder": unknown;
  "lr-grounding-summary": unknown;
  "lr-handoff-divider": unknown;
  "lr-heatmap": unknown;
  "lr-highlight-layer": unknown;
  "lr-histogram": unknown;
  "lr-html-viewer": unknown;
  "lr-icon": unknown;
  "lr-icon-button": unknown;
  "lr-image-comparer": unknown;
  "lr-image-viewer": unknown;
  "lr-include": unknown;
  "lr-ingestion-queue": unknown;
  "lr-input": unknown;
  "lr-intersection-observer": unknown;
  "lr-json-viewer": unknown;
  "lr-kbd": unknown;
  "lr-knowledge-base": unknown;
  "lr-knowledge-base-admin": unknown;
  "lr-knowledge-graph-explorer": unknown;
  "lr-known-date": unknown;
  "lr-lightbox": unknown;
  "lr-line-chart": unknown;
  "lr-lite-chart": unknown;
  "lr-live-region": unknown;
  "lr-locale-picker": unknown;
  "lr-map": unknown;
  "lr-markdown": unknown;
  "lr-markdown-core": unknown;
  "lr-mcp-app": unknown;
  "lr-media-card": unknown;
  "lr-memory-panel": unknown;
  "lr-mention-popover": unknown;
  "lr-menu": unknown;
  "lr-menu-item": unknown;
  "lr-menu-label": unknown;
  "lr-message-actions": unknown;
  "lr-message-feedback": unknown;
  "lr-message-parts": unknown;
  "lr-mind-map": unknown;
  "lr-model-select": unknown;
  "lr-model-settings-panel": unknown;
  "lr-multi-split": unknown;
  "lr-mutation-observer": unknown;
  "lr-native-time-input": unknown;
  "lr-neighbor-list": unknown;
  "lr-node-palette": unknown;
  "lr-notebook-viewer": unknown;
  "lr-number-input": unknown;
  "lr-option": unknown;
  "lr-otp-input": unknown;
  "lr-page": unknown;
  "lr-page-rail": unknown;
  "lr-pagination": unknown;
  "lr-pan-zoom": unknown;
  "lr-path-strip": unknown;
  "lr-pdf-viewer": unknown;
  "lr-phone-input": unknown;
  "lr-pie-chart": unknown;
  "lr-polar-area-chart": unknown;
  "lr-policy-summary": unknown;
  "lr-poll-status": unknown;
  "lr-popover": unknown;
  "lr-popup": unknown;
  "lr-pptx-viewer": unknown;
  "lr-progress-bar": unknown;
  "lr-progress-ring": unknown;
  "lr-prompt-input": unknown;
  "lr-prompt-queue": unknown;
  "lr-prompt-studio": unknown;
  "lr-provenance-panel": unknown;
  "lr-push-to-talk": unknown;
  "lr-qr-code": unknown;
  "lr-radar-chart": unknown;
  "lr-radio": unknown;
  "lr-radio-button": unknown;
  "lr-radio-group": unknown;
  "lr-rag-answer": unknown;
  "lr-rag-eval-dashboard": unknown;
  "lr-random-content": unknown;
  "lr-rating": unknown;
  "lr-realtime-session": unknown;
  "lr-relative-time": unknown;
  "lr-reorder-item": unknown;
  "lr-reorder-list": unknown;
  "lr-resize-observer": unknown;
  "lr-responsive-panel": unknown;
  "lr-result-card": unknown;
  "lr-result-field": unknown;
  "lr-retrieval-compare": unknown;
  "lr-retrieval-results": unknown;
  "lr-retrieval-search": unknown;
  "lr-retrieval-trace": unknown;
  "lr-rubric-form": unknown;
  "lr-scatter-chart": unknown;
  "lr-json-schema-viewer": unknown;
  "lr-scroller": unknown;
  "lr-segmented": unknown;
  "lr-select": unknown;
  "lr-selection-toolbar": unknown;
  "lr-sequence-playback": unknown;
  "lr-sequence-strip": unknown;
  "lr-skeleton": unknown;
  "lr-slider": unknown;
  "lr-source-card": unknown;
  "lr-source-list": unknown;
  "lr-source-picker": unknown;
  "lr-span-waterfall": unknown;
  "lr-sparkline": unknown;
  "lr-spinner": unknown;
  "lr-split-panel": unknown;
  "lr-spreadsheet-viewer": unknown;
  "lr-stack-trace": unknown;
  "lr-stat": unknown;
  "lr-stepper": unknown;
  "lr-stream-status": unknown;
  "lr-streaming-text": unknown;
  "lr-streaming-text-core": unknown;
  "lr-subagent-panel": unknown;
  "lr-suggestion-chips": unknown;
  "lr-svg-viewer": unknown;
  "lr-swatch-picker": unknown;
  "lr-switch": unknown;
  "lr-tab": unknown;
  "lr-tab-group": unknown;
  "lr-tab-panel": unknown;
  "lr-table": unknown;
  "lr-tag": unknown;
  "lr-task-list": unknown;
  "lr-terminal": unknown;
  "lr-test-results": unknown;
  "lr-textarea": unknown;
  "lr-thinking-panel": unknown;
  "lr-thread-list": unknown;
  "lr-time-input": unknown;
  "lr-time-range": unknown;
  "lr-timeline": unknown;
  "lr-timeline-item": unknown;
  "lr-toast": unknown;
  "lr-toast-item": unknown;
  "lr-token-input": unknown;
  "lr-tool-approval-dialog": unknown;
  "lr-tool-call-chip": unknown;
  "lr-tool-param-form": unknown;
  "lr-tool-result-dialog": unknown;
  "lr-tool-result-view": unknown;
  "lr-tool-select-dialog": unknown;
  "lr-tool-timeline": unknown;
  "lr-tooltip": unknown;
  "lr-tour": unknown;
  "lr-trace-tree": unknown;
  "lr-transcript-feed": unknown;
  "lr-tree": unknown;
  "lr-tree-item": unknown;
  "lr-typing-indicator": unknown;
  "lr-usage-badge": unknown;
  "lr-video": unknown;
  "lr-video-playlist": unknown;
  "lr-virtual-list": unknown;
  "lr-visually-hidden": unknown;
  "lr-voice-picker": unknown;
  "lr-widget": unknown;
  "lr-widget-renderer": unknown;
  "lr-word-cloud": unknown;
  "lr-xml-viewer": unknown;
  "lr-zoomable-frame": unknown;
}`
  `LyraSvelteElements {
  "lr-accordion": unknown;
  "lr-accordion-item": unknown;
  "lr-activity-feed": unknown;
  "lr-agent-eval-dashboard": unknown;
  "lr-agent-run": unknown;
  "lr-agent-trace": unknown;
  "lr-agent-workspace": unknown;
  "lr-alert": unknown;
  "lr-animated-image": unknown;
  "lr-animation": unknown;
  "lr-app-rail": unknown;
  "lr-app-rail-group": unknown;
  "lr-app-rail-item": unknown;
  "lr-approval-queue": unknown;
  "lr-archive-viewer": unknown;
  "lr-artifact-panel": unknown;
  "lr-attachment-chip": unknown;
  "lr-attachment-trigger": unknown;
  "lr-audio-visualizer": unknown;
  "lr-av-player": unknown;
  "lr-avatar": unknown;
  "lr-avatar-group": unknown;
  "lr-badge": unknown;
  "lr-bar-chart": unknown;
  "lr-box-plot": unknown;
  "lr-branch-picker": unknown;
  "lr-breadcrumb": unknown;
  "lr-breadcrumb-item": unknown;
  "lr-browser-frame": unknown;
  "lr-bubble-chart": unknown;
  "lr-button": unknown;
  "lr-button-group": unknown;
  "lr-calendar": unknown;
  "lr-calendar-viewer": unknown;
  "lr-callout": unknown;
  "lr-card": unknown;
  "lr-carousel": unknown;
  "lr-carousel-item": unknown;
  "lr-chart": unknown;
  "lr-chat-composer": unknown;
  "lr-chat-message": unknown;
  "lr-chat-viewport": unknown;
  "lr-checkbox": unknown;
  "lr-checkbox-group": unknown;
  "lr-checkpoint": unknown;
  "lr-chip": unknown;
  "lr-chip-group": unknown;
  "lr-chunk-inspector": unknown;
  "lr-citation-badge": unknown;
  "lr-claim-evidence": unknown;
  "lr-code-block": unknown;
  "lr-code-block-core": unknown;
  "lr-code-editor": unknown;
  "lr-color-picker": unknown;
  "lr-combobox": unknown;
  "lr-command-palette": unknown;
  "lr-commit-card": unknown;
  "lr-community-card": unknown;
  "lr-compare-panel": unknown;
  "lr-condition-builder": unknown;
  "lr-confirm-bar": unknown;
  "lr-contact-viewer": unknown;
  "lr-context-inspector": unknown;
  "lr-context-meter": unknown;
  "lr-control-group": unknown;
  "lr-conversation-item": unknown;
  "lr-copy-button": unknown;
  "lr-csv-viewer": unknown;
  "lr-dashboard-grid": unknown;
  "lr-data-grid": unknown;
  "lr-dataset-viewer": unknown;
  "lr-date-input": unknown;
  "lr-date-picker": unknown;
  "lr-details": unknown;
  "lr-dialog": unknown;
  "lr-diff-view": unknown;
  "lr-divider": unknown;
  "lr-dock-panel": unknown;
  "lr-document-compare": unknown;
  "lr-document-library": unknown;
  "lr-document-preview": unknown;
  "lr-document-viewer": unknown;
  "lr-docx-viewer": unknown;
  "lr-doughnut-chart": unknown;
  "lr-drawer": unknown;
  "lr-drilldown-panel": unknown;
  "lr-drop-zone": unknown;
  "lr-dropdown": unknown;
  "lr-dropdown-item": unknown;
  "lr-ebook-viewer": unknown;
  "lr-email-viewer": unknown;
  "lr-embedding-explorer": unknown;
  "lr-emoji-picker": unknown;
  "lr-empty": unknown;
  "lr-entity-card": unknown;
  "lr-entity-chip": unknown;
  "lr-entity-dossier": unknown;
  "lr-env-list": unknown;
  "lr-eval-dataset": unknown;
  "lr-eval-result": unknown;
  "lr-eval-run": unknown;
  "lr-export-button": unknown;
  "lr-file-icon": unknown;
  "lr-file-input": unknown;
  "lr-file-tree": unknown;
  "lr-filter-bar": unknown;
  "lr-flag": unknown;
  "lr-flow-canvas": unknown;
  "lr-flow-controls": unknown;
  "lr-flow-minimap": unknown;
  "lr-flow-node": unknown;
  "lr-flow-run-status": unknown;
  "lr-format-bytes": unknown;
  "lr-format-date": unknown;
  "lr-format-number": unknown;
  "lr-funnel": unknown;
  "lr-gauge": unknown;
  "lr-generation-metrics": unknown;
  "lr-geojson-view": unknown;
  "lr-geojson-viewer": unknown;
  "lr-graph": unknown;
  "lr-graph-legend": unknown;
  "lr-graph-query-builder": unknown;
  "lr-grounding-summary": unknown;
  "lr-handoff-divider": unknown;
  "lr-heatmap": unknown;
  "lr-highlight-layer": unknown;
  "lr-histogram": unknown;
  "lr-html-viewer": unknown;
  "lr-icon": unknown;
  "lr-icon-button": unknown;
  "lr-image-comparer": unknown;
  "lr-image-viewer": unknown;
  "lr-include": unknown;
  "lr-ingestion-queue": unknown;
  "lr-input": unknown;
  "lr-intersection-observer": unknown;
  "lr-json-viewer": unknown;
  "lr-kbd": unknown;
  "lr-knowledge-base": unknown;
  "lr-knowledge-base-admin": unknown;
  "lr-knowledge-graph-explorer": unknown;
  "lr-known-date": unknown;
  "lr-lightbox": unknown;
  "lr-line-chart": unknown;
  "lr-lite-chart": unknown;
  "lr-live-region": unknown;
  "lr-locale-picker": unknown;
  "lr-map": unknown;
  "lr-markdown": unknown;
  "lr-markdown-core": unknown;
  "lr-mcp-app": unknown;
  "lr-media-card": unknown;
  "lr-memory-panel": unknown;
  "lr-mention-popover": unknown;
  "lr-menu": unknown;
  "lr-menu-item": unknown;
  "lr-menu-label": unknown;
  "lr-message-actions": unknown;
  "lr-message-feedback": unknown;
  "lr-message-parts": unknown;
  "lr-mind-map": unknown;
  "lr-model-select": unknown;
  "lr-model-settings-panel": unknown;
  "lr-multi-split": unknown;
  "lr-mutation-observer": unknown;
  "lr-native-time-input": unknown;
  "lr-neighbor-list": unknown;
  "lr-node-palette": unknown;
  "lr-notebook-viewer": unknown;
  "lr-number-input": unknown;
  "lr-option": unknown;
  "lr-otp-input": unknown;
  "lr-page": unknown;
  "lr-page-rail": unknown;
  "lr-pagination": unknown;
  "lr-pan-zoom": unknown;
  "lr-path-strip": unknown;
  "lr-pdf-viewer": unknown;
  "lr-phone-input": unknown;
  "lr-pie-chart": unknown;
  "lr-polar-area-chart": unknown;
  "lr-policy-summary": unknown;
  "lr-poll-status": unknown;
  "lr-popover": unknown;
  "lr-popup": unknown;
  "lr-pptx-viewer": unknown;
  "lr-progress-bar": unknown;
  "lr-progress-ring": unknown;
  "lr-prompt-input": unknown;
  "lr-prompt-queue": unknown;
  "lr-prompt-studio": unknown;
  "lr-provenance-panel": unknown;
  "lr-push-to-talk": unknown;
  "lr-qr-code": unknown;
  "lr-radar-chart": unknown;
  "lr-radio": unknown;
  "lr-radio-button": unknown;
  "lr-radio-group": unknown;
  "lr-rag-answer": unknown;
  "lr-rag-eval-dashboard": unknown;
  "lr-random-content": unknown;
  "lr-rating": unknown;
  "lr-realtime-session": unknown;
  "lr-relative-time": unknown;
  "lr-reorder-item": unknown;
  "lr-reorder-list": unknown;
  "lr-resize-observer": unknown;
  "lr-responsive-panel": unknown;
  "lr-result-card": unknown;
  "lr-result-field": unknown;
  "lr-retrieval-compare": unknown;
  "lr-retrieval-results": unknown;
  "lr-retrieval-search": unknown;
  "lr-retrieval-trace": unknown;
  "lr-rubric-form": unknown;
  "lr-scatter-chart": unknown;
  "lr-json-schema-viewer": unknown;
  "lr-scroller": unknown;
  "lr-segmented": unknown;
  "lr-select": unknown;
  "lr-selection-toolbar": unknown;
  "lr-sequence-playback": unknown;
  "lr-sequence-strip": unknown;
  "lr-skeleton": unknown;
  "lr-slider": unknown;
  "lr-source-card": unknown;
  "lr-source-list": unknown;
  "lr-source-picker": unknown;
  "lr-span-waterfall": unknown;
  "lr-sparkline": unknown;
  "lr-spinner": unknown;
  "lr-split-panel": unknown;
  "lr-spreadsheet-viewer": unknown;
  "lr-stack-trace": unknown;
  "lr-stat": unknown;
  "lr-stepper": unknown;
  "lr-stream-status": unknown;
  "lr-streaming-text": unknown;
  "lr-streaming-text-core": unknown;
  "lr-subagent-panel": unknown;
  "lr-suggestion-chips": unknown;
  "lr-svg-viewer": unknown;
  "lr-swatch-picker": unknown;
  "lr-switch": unknown;
  "lr-tab": unknown;
  "lr-tab-group": unknown;
  "lr-tab-panel": unknown;
  "lr-table": unknown;
  "lr-tag": unknown;
  "lr-task-list": unknown;
  "lr-terminal": unknown;
  "lr-test-results": unknown;
  "lr-textarea": unknown;
  "lr-thinking-panel": unknown;
  "lr-thread-list": unknown;
  "lr-time-input": unknown;
  "lr-time-range": unknown;
  "lr-timeline": unknown;
  "lr-timeline-item": unknown;
  "lr-toast": unknown;
  "lr-toast-item": unknown;
  "lr-token-input": unknown;
  "lr-tool-approval-dialog": unknown;
  "lr-tool-call-chip": unknown;
  "lr-tool-param-form": unknown;
  "lr-tool-result-dialog": unknown;
  "lr-tool-result-view": unknown;
  "lr-tool-select-dialog": unknown;
  "lr-tool-timeline": unknown;
  "lr-tooltip": unknown;
  "lr-tour": unknown;
  "lr-trace-tree": unknown;
  "lr-transcript-feed": unknown;
  "lr-tree": unknown;
  "lr-tree-item": unknown;
  "lr-typing-indicator": unknown;
  "lr-usage-badge": unknown;
  "lr-video": unknown;
  "lr-video-playlist": unknown;
  "lr-virtual-list": unknown;
  "lr-visually-hidden": unknown;
  "lr-voice-picker": unknown;
  "lr-widget": unknown;
  "lr-widget-renderer": unknown;
  "lr-word-cloud": unknown;
  "lr-xml-viewer": unknown;
  "lr-zoomable-frame": unknown;
}`

- **`testing-event-factory-contracts`** — Shared utility contracts.
  `createLyraEvent(/* public names: tag, name, detail */): unknown`
  See "Constructing a validated test event: `createLyraEvent()`" above for the full contract.

- **`testing-happy-dom-shims-contracts`** — Shared utility contracts.
  `installHappyDomFormAssociatedShims(): unknown`
  `installStubInternalsForTest(/* public names: host */): unknown`

- **`testing-interaction-drivers-contracts`** — Shared utility contracts.
  `chooseOption(/* public names: owner, value */): unknown`
  `submitConfirmDecision(/* public names: owner, decision */): unknown`
  `toggleSwitch(/* public names: switchEl */): unknown`
  `activateStep(/* public names: stepper, target */): unknown`
  See "Driving a component's real activation path: interaction drivers" above for the full contract.

- **`testing-wait-for-mount-contracts`** — Shared utility contracts.
  `waitForLyraElement(/* public names: selector, options */): unknown`
  `WaitForLyraElementOptions {
  root: unknown;
  match: (element: unknown) => unknown;
  timeoutMs: unknown;
}`
  `waitForToast(/* public names: match, options */): unknown`
  See "Awaiting a lazily registered mount: `waitForLyraElement()` and `waitForToast()`" above for the
  full contract.

- **`theme-gemstones-data-contracts`** — Shared utility contracts.
  `GemstoneAccent {
  key: unknown;
  fill: unknown;
  deep: unknown;
}`

- **`theme-gemstones-contracts`** — Shared utility contracts.
  `gemstoneGlyph(/* public names: color */): unknown`
  `gemstoneSelectedGlyphStyles: CSSResult` — the shared "selected" halo/shine presentation for a
  rendered `gemstoneGlyph()`, applied via the `data-lr-gemstone-selected` boolean attribute on the
  element wrapping the glyph. `lr-swatch-picker mode="gemstone"` includes this exact stylesheet in
  its own `static styles` for its checked swatch's automatic glyph rather than keeping a private
  copy, so a glyph rendered anywhere else on the page can match it exactly by consuming the same
  export and attribute.

- **`theme-presets-contracts`** — Shared utility contracts.
  `applyLyraThemePreset(/* public names: presetOrName */): unknown`
  `defineLyraThemePreset(/* public names: preset */): unknown`
  `LyraThemePresetChangeDetail {
  id: unknown;
  theme: unknown;
}`
  `LyraThemePreset {
  id: unknown;
  theme: unknown;
}`

- **`theme-theme-contracts`** — Shared utility contracts.
  `createLyraThemeBootstrap(/* public names: options */): unknown`
  `getLyraTheme(): unknown`
  `LyraThemeBootstrapOptions {
  storageKey: unknown;
}`
  `LyraTheme {
  mode: unknown;
  accent: unknown;
  surface: unknown;
}`
  `setLyraTheme(/* public names: theme */): unknown`

- **`vue-contracts`** — Framework integration type contracts.
  `LyraVueGlobalComponents {
  "lr-accordion": unknown;
  "lr-accordion-item": unknown;
  "lr-activity-feed": unknown;
  "lr-agent-eval-dashboard": unknown;
  "lr-agent-run": unknown;
  "lr-agent-trace": unknown;
  "lr-agent-workspace": unknown;
  "lr-alert": unknown;
  "lr-animated-image": unknown;
  "lr-animation": unknown;
  "lr-app-rail": unknown;
  "lr-app-rail-group": unknown;
  "lr-app-rail-item": unknown;
  "lr-approval-queue": unknown;
  "lr-archive-viewer": unknown;
  "lr-artifact-panel": unknown;
  "lr-attachment-chip": unknown;
  "lr-attachment-trigger": unknown;
  "lr-audio-visualizer": unknown;
  "lr-av-player": unknown;
  "lr-avatar": unknown;
  "lr-avatar-group": unknown;
  "lr-badge": unknown;
  "lr-bar-chart": unknown;
  "lr-box-plot": unknown;
  "lr-branch-picker": unknown;
  "lr-breadcrumb": unknown;
  "lr-breadcrumb-item": unknown;
  "lr-browser-frame": unknown;
  "lr-bubble-chart": unknown;
  "lr-button": unknown;
  "lr-button-group": unknown;
  "lr-calendar": unknown;
  "lr-calendar-viewer": unknown;
  "lr-callout": unknown;
  "lr-card": unknown;
  "lr-carousel": unknown;
  "lr-carousel-item": unknown;
  "lr-chart": unknown;
  "lr-chat-composer": unknown;
  "lr-chat-message": unknown;
  "lr-chat-viewport": unknown;
  "lr-checkbox": unknown;
  "lr-checkbox-group": unknown;
  "lr-checkpoint": unknown;
  "lr-chip": unknown;
  "lr-chip-group": unknown;
  "lr-chunk-inspector": unknown;
  "lr-citation-badge": unknown;
  "lr-claim-evidence": unknown;
  "lr-code-block": unknown;
  "lr-code-block-core": unknown;
  "lr-code-editor": unknown;
  "lr-color-picker": unknown;
  "lr-combobox": unknown;
  "lr-command-palette": unknown;
  "lr-commit-card": unknown;
  "lr-community-card": unknown;
  "lr-compare-panel": unknown;
  "lr-condition-builder": unknown;
  "lr-confirm-bar": unknown;
  "lr-contact-viewer": unknown;
  "lr-context-inspector": unknown;
  "lr-context-meter": unknown;
  "lr-control-group": unknown;
  "lr-conversation-item": unknown;
  "lr-copy-button": unknown;
  "lr-csv-viewer": unknown;
  "lr-dashboard-grid": unknown;
  "lr-data-grid": unknown;
  "lr-dataset-viewer": unknown;
  "lr-date-input": unknown;
  "lr-date-picker": unknown;
  "lr-details": unknown;
  "lr-dialog": unknown;
  "lr-diff-view": unknown;
  "lr-divider": unknown;
  "lr-dock-panel": unknown;
  "lr-document-compare": unknown;
  "lr-document-library": unknown;
  "lr-document-preview": unknown;
  "lr-document-viewer": unknown;
  "lr-docx-viewer": unknown;
  "lr-doughnut-chart": unknown;
  "lr-drawer": unknown;
  "lr-drilldown-panel": unknown;
  "lr-drop-zone": unknown;
  "lr-dropdown": unknown;
  "lr-dropdown-item": unknown;
  "lr-ebook-viewer": unknown;
  "lr-email-viewer": unknown;
  "lr-embedding-explorer": unknown;
  "lr-emoji-picker": unknown;
  "lr-empty": unknown;
  "lr-entity-card": unknown;
  "lr-entity-chip": unknown;
  "lr-entity-dossier": unknown;
  "lr-env-list": unknown;
  "lr-eval-dataset": unknown;
  "lr-eval-result": unknown;
  "lr-eval-run": unknown;
  "lr-export-button": unknown;
  "lr-file-icon": unknown;
  "lr-file-input": unknown;
  "lr-file-tree": unknown;
  "lr-filter-bar": unknown;
  "lr-flag": unknown;
  "lr-flow-canvas": unknown;
  "lr-flow-controls": unknown;
  "lr-flow-minimap": unknown;
  "lr-flow-node": unknown;
  "lr-flow-run-status": unknown;
  "lr-format-bytes": unknown;
  "lr-format-date": unknown;
  "lr-format-number": unknown;
  "lr-funnel": unknown;
  "lr-gauge": unknown;
  "lr-generation-metrics": unknown;
  "lr-geojson-view": unknown;
  "lr-geojson-viewer": unknown;
  "lr-graph": unknown;
  "lr-graph-legend": unknown;
  "lr-graph-query-builder": unknown;
  "lr-grounding-summary": unknown;
  "lr-handoff-divider": unknown;
  "lr-heatmap": unknown;
  "lr-highlight-layer": unknown;
  "lr-histogram": unknown;
  "lr-html-viewer": unknown;
  "lr-icon": unknown;
  "lr-icon-button": unknown;
  "lr-image-comparer": unknown;
  "lr-image-viewer": unknown;
  "lr-include": unknown;
  "lr-ingestion-queue": unknown;
  "lr-input": unknown;
  "lr-intersection-observer": unknown;
  "lr-json-viewer": unknown;
  "lr-kbd": unknown;
  "lr-knowledge-base": unknown;
  "lr-knowledge-base-admin": unknown;
  "lr-knowledge-graph-explorer": unknown;
  "lr-known-date": unknown;
  "lr-lightbox": unknown;
  "lr-line-chart": unknown;
  "lr-lite-chart": unknown;
  "lr-live-region": unknown;
  "lr-locale-picker": unknown;
  "lr-map": unknown;
  "lr-markdown": unknown;
  "lr-markdown-core": unknown;
  "lr-mcp-app": unknown;
  "lr-media-card": unknown;
  "lr-memory-panel": unknown;
  "lr-mention-popover": unknown;
  "lr-menu": unknown;
  "lr-menu-item": unknown;
  "lr-menu-label": unknown;
  "lr-message-actions": unknown;
  "lr-message-feedback": unknown;
  "lr-message-parts": unknown;
  "lr-mind-map": unknown;
  "lr-model-select": unknown;
  "lr-model-settings-panel": unknown;
  "lr-multi-split": unknown;
  "lr-mutation-observer": unknown;
  "lr-native-time-input": unknown;
  "lr-neighbor-list": unknown;
  "lr-node-palette": unknown;
  "lr-notebook-viewer": unknown;
  "lr-number-input": unknown;
  "lr-option": unknown;
  "lr-otp-input": unknown;
  "lr-page": unknown;
  "lr-page-rail": unknown;
  "lr-pagination": unknown;
  "lr-pan-zoom": unknown;
  "lr-path-strip": unknown;
  "lr-pdf-viewer": unknown;
  "lr-phone-input": unknown;
  "lr-pie-chart": unknown;
  "lr-polar-area-chart": unknown;
  "lr-policy-summary": unknown;
  "lr-poll-status": unknown;
  "lr-popover": unknown;
  "lr-popup": unknown;
  "lr-pptx-viewer": unknown;
  "lr-progress-bar": unknown;
  "lr-progress-ring": unknown;
  "lr-prompt-input": unknown;
  "lr-prompt-queue": unknown;
  "lr-prompt-studio": unknown;
  "lr-provenance-panel": unknown;
  "lr-push-to-talk": unknown;
  "lr-qr-code": unknown;
  "lr-radar-chart": unknown;
  "lr-radio": unknown;
  "lr-radio-button": unknown;
  "lr-radio-group": unknown;
  "lr-rag-answer": unknown;
  "lr-rag-eval-dashboard": unknown;
  "lr-random-content": unknown;
  "lr-rating": unknown;
  "lr-realtime-session": unknown;
  "lr-relative-time": unknown;
  "lr-reorder-item": unknown;
  "lr-reorder-list": unknown;
  "lr-resize-observer": unknown;
  "lr-responsive-panel": unknown;
  "lr-result-card": unknown;
  "lr-result-field": unknown;
  "lr-retrieval-compare": unknown;
  "lr-retrieval-results": unknown;
  "lr-retrieval-search": unknown;
  "lr-retrieval-trace": unknown;
  "lr-rubric-form": unknown;
  "lr-scatter-chart": unknown;
  "lr-json-schema-viewer": unknown;
  "lr-scroller": unknown;
  "lr-segmented": unknown;
  "lr-select": unknown;
  "lr-selection-toolbar": unknown;
  "lr-sequence-playback": unknown;
  "lr-sequence-strip": unknown;
  "lr-skeleton": unknown;
  "lr-slider": unknown;
  "lr-source-card": unknown;
  "lr-source-list": unknown;
  "lr-source-picker": unknown;
  "lr-span-waterfall": unknown;
  "lr-sparkline": unknown;
  "lr-spinner": unknown;
  "lr-split-panel": unknown;
  "lr-spreadsheet-viewer": unknown;
  "lr-stack-trace": unknown;
  "lr-stat": unknown;
  "lr-stepper": unknown;
  "lr-stream-status": unknown;
  "lr-streaming-text": unknown;
  "lr-streaming-text-core": unknown;
  "lr-subagent-panel": unknown;
  "lr-suggestion-chips": unknown;
  "lr-svg-viewer": unknown;
  "lr-swatch-picker": unknown;
  "lr-switch": unknown;
  "lr-tab": unknown;
  "lr-tab-group": unknown;
  "lr-tab-panel": unknown;
  "lr-table": unknown;
  "lr-tag": unknown;
  "lr-task-list": unknown;
  "lr-terminal": unknown;
  "lr-test-results": unknown;
  "lr-textarea": unknown;
  "lr-thinking-panel": unknown;
  "lr-thread-list": unknown;
  "lr-time-input": unknown;
  "lr-time-range": unknown;
  "lr-timeline": unknown;
  "lr-timeline-item": unknown;
  "lr-toast": unknown;
  "lr-toast-item": unknown;
  "lr-token-input": unknown;
  "lr-tool-approval-dialog": unknown;
  "lr-tool-call-chip": unknown;
  "lr-tool-param-form": unknown;
  "lr-tool-result-dialog": unknown;
  "lr-tool-result-view": unknown;
  "lr-tool-select-dialog": unknown;
  "lr-tool-timeline": unknown;
  "lr-tooltip": unknown;
  "lr-tour": unknown;
  "lr-trace-tree": unknown;
  "lr-transcript-feed": unknown;
  "lr-tree": unknown;
  "lr-tree-item": unknown;
  "lr-typing-indicator": unknown;
  "lr-usage-badge": unknown;
  "lr-video": unknown;
  "lr-video-playlist": unknown;
  "lr-virtual-list": unknown;
  "lr-visually-hidden": unknown;
  "lr-voice-picker": unknown;
  "lr-widget": unknown;
  "lr-widget-renderer": unknown;
  "lr-word-cloud": unknown;
  "lr-xml-viewer": unknown;
  "lr-zoomable-frame": unknown;
}`

# Form controls & inputs (`components/forms/`)

## Breaking changes in 10.0.0

`<lr-swatch-picker>` drops the three members it carried through 9.x as documented one-major
back-compat aliases, each with a like-for-like replacement that has shipped since. The `options`
property is now `items` — same frozen owned-snapshot contract, still `attribute: false`, so no
markup changes. The `label` property/attribute is now `accessibleLabel` (attribute `aria-label`), or
the host `aria-label` directly; this is the one worth grepping for, because an un-updated
`<lr-swatch-picker label="Brand colours">` leaves the internal `role="radiogroup"` with no accessible
name at all rather than failing loudly. And the exported `SwatchOption` type is now
`SwatchPickerItem`. The item shape itself is unchanged, including its own per-item `label` field,
which is a different member and stays.

Also corrected in 10.0.0 — not breaking, but visible. A specificity sweep found rules that were
meant to win yet were losing to another rule in the same shadow stylesheet, so their declarations
never applied at all. In this family: arrow-keying onto the already-selected option in
`<lr-select>` or `<lr-combobox>` produces a visible keyboard highlight again — `[aria-selected="true"]`
was written after the active-descendant rule at equal specificity and swallowed it, so the highlight
was absent exactly on the row a user is most likely to arrow onto first. `appearance="filled"` has a
focus indicator again on `<lr-combobox>` and `<lr-date-input>`, both of which previously had none:
the appearance rule out-ranked `:focus-within`, and the only `outline` in the focus rule was
`solid transparent`. Both now express appearance as private custom properties, so no `[part]` rule
can out-rank another. `<lr-option>` and `<lr-time-range>`'s active preset regain their pointer
feedback, and `<lr-token-input>` can now veto all three of its mutations (`lr-add` and
`lr-token-edit` became cancelable alongside `lr-remove`, which already was — additive; see that
section).

## Setter-only `null` clearing in 8.0.0

Several mapped string IDLs accept `null` on assignment without widening their read type. This is a
JavaScript/TypeScript compatibility surface: after the write, every getter below still returns its
canonical string. Name attributes are removed; live-value writes follow each control's existing
live/default-value reflection contract. HTML authors remove an attribute instead of writing the
literal text `"null"`.

- `.name = null` clears to `''` on `lr-button`, `lr-checkbox`, `lr-color-picker`, `lr-combobox`,
  `lr-date-input`, `lr-input`, `lr-number-input`, `lr-otp-input`, `lr-radio`, `lr-radio-group`,
  `lr-select`, `lr-switch`, `lr-textarea`, and `lr-time-input`.
- `.value = null` clears to `''` on `lr-color-picker`, `lr-input`, `lr-number-input`, `lr-otp-input`,
  and `lr-radio-group`.
- `.value = null` restores the native checkbox default `'on'` on `lr-checkbox` and `lr-switch`
  while removing the `value` attribute. An explicit non-null `.value = 'on'` instead reflects
  `value="on"`, preserving the distinction between an absent native default and an authored value.

These are setter-only input types, not nullable states: code that reads any member above continues
to receive a `string`.

## The validity alias is cancelable in 8.0.0

Every form-associated control emits `lr-invalid` (no detail, bubbling, composed) as the alias of the
native, non-bubbling `invalid` event. In 8.0.0 that alias is **cancelable**, and its cancellation is
forwarded to the native event that produced it:

```ts
form.addEventListener("lr-invalid", (event) => {
  event.preventDefault(); // suppresses the browser's own validation bubble,
  showMyOwnErrorSummary(event.target); // and reportValidity()'s focus/scroll of this control
});
```

`preventDefault()` suppresses only the platform's _default UI_ — the validation bubble, and the
focus/scroll `reportValidity()` performs on the first invalid control. The control stays invalid,
still fails `checkValidity()`, and still blocks submission. Cancelling a copy of a platform event
could only ever mean cancelling the original, which is why the forwarding exists at all: before it,
an app wiring `lr-invalid` to its own error banner had no way to stop the native UI appearing
alongside it.

Nothing changes for code that ignores the event, and the listener has to be attached before the
validity check runs. Every per-control mention of `lr-invalid` below inherits this contract; the
per-control sections repeat only what is specific to that control.

## Mirrored static validator catalogs

The mirrored form-control constructors expose a public `static validators` catalog with the same
callable shape as Web Awesome's `Validator[]`: `observedAttributes`, `checkValidity(element)`, and
an optional message. The catalog is available on `LyraButton`, `LyraCheckbox`, `LyraColorPicker`,
`LyraInput`, `LyraNumberInput`, `LyraOtpInput`, `LyraRadio`, `LyraRadioGroup`, `LyraSelect`,
`LyraSlider`, `LyraSwitch`, `LyraTextarea`, and `LyraTimeInput`. Each call returns a fresh array;
calling an entry projects the control's current `ValidityState` into `{ isValid, message,
invalidKeys }` without mutating the control.

```ts
import { LyraInput } from "@aceshooting/lyra-ui/components/forms/input/input.js";

const input = document.querySelector("lr-input")!;
const result = LyraInput.validators[0].checkValidity(input);
```

## The required-field marker

A labelled control with `required` set paints ` *` after its label text. It is one shared rule on
the `form-control-label` part, so it looks and sits identically on every control that renders that
part — here, and on `lr-file-input`, `lr-model-select`, `lr-voice-picker` and `lr-tool-param-form`
in the other families. `lr-checkbox`, `lr-switch` and `lr-radio` have no label box of their own and
paint none; a control with the part but no label text set paints none either, so no stray glyph is
orphaned.

Three consumer-settable properties replace it, retune its colour, or suppress it entirely —
`--lr-form-control-required-content` (a quoted CSS `content` string; `''` suppresses the marker),
`--lr-form-control-required-color` (default `var(--lr-color-danger)`), and
`--lr-form-control-required-offset` (default `0`). Each is an inline `var()` fallback rather than a
`:host` declaration, so setting one on any ancestor — `:root` included — reaches every marker at
once. Full description, worked examples, and why the content string is never localized by the
library: `llms/shared.md` → "The required-field marker".

## Disabled and readonly controls publish no invalid state

A control **barred from constraint validation** — its own `disabled`, an ancestor
`<fieldset disabled>`, `readonly` on the controls that have it, or anything else that makes
`willValidate` false — matches neither `:state(invalid)` nor `:state(user-invalid)`, and reports no
violation from `checkValidity()`. That is the native rule: `<input required disabled>` and
`<input required readonly>` both match neither `:valid` nor `:invalid`.

It matters because the idiomatic stylesheet rule keys off the tag —
`lr-input:state(user-invalid) { border-color: … }` — so a disabled required field that still
published `invalid` painted every greyed-out control in the form red.

`required`/`optional` are unaffected: they describe the attribute, not the outcome, so a disabled
required field still matches `:state(required)`, exactly like native `:required`. Style the barred
case through `:state(disabled)`/`:disabled` and `:state(readonly)` instead. Full description in
`llms/shared.md` → "CSS custom states".

## `lr-combobox` / `lr-option`

Filterable single/multi-select combining a text input with a listbox. Mirrors the core
`<wa-combobox>` API under the `lr-` prefix. **Form-associated** (hand-rolled internals, not the
shared `FormAssociated` mixin — see gotchas).

Consumer writes on mounted options immediately update the owning picker and its submission,
without changing the reset default or emitting picker input/change events. Owner synchronization
does not echo as a consumer selected write.

A mounted `option.selected` assignment updates the live picker value and form submission
immediately, including deselection and equal-value writes; it emits no user input/change event.

When `multiple` becomes false, the public value, live option flags, and popup `aria-selected` expose
one selected occurrence. The retained multiple-selection history returns if multiple is enabled
again without another selection write.

Composing keyboard events (`isComposing` or legacy key code 229) remain with filter editing; they do
not navigate, select/create a value, or dismiss the popup.

Source options with `inert`, including inherited inertness, are unavailable through the popup. Live
inert changes refresh row availability. Text, insertion, replacement, removal, slot
reassignment/removal, and relevant attributes of `start`/`end`/`prefix`/`suffix` adornments refresh
the corresponding cloned presentation; unchanged presentation retains its clone identity while
filtering.

Host `aria-describedby` resolves external descriptions onto the native combobox filter before local
error/hint guidance. References track missing targets, replacement, removal/reinsertion, reconnect,
and adoption. Removing `label`, `hint`, or `error-text` safely omits the content while leaving
removed string properties at their native `null` readback; explicit empty strings remain supplied
empty strings.

**First-interaction registration.** Where initial-route weight is stricter than a static combobox
registration allows, keep a labelled native `<input list>` as the working pre-JavaScript control
and import only the granular combobox registration on its first focus. Copy the native value after
the import resolves so typing that happens while the chunk is in flight is not lost, then transfer
focus explicitly — the browser does not replay the focus event after custom-element upgrade:

```html
<div id="country-fallback">
  <label for="country-native">Country</label>
  <input id="country-native" name="country" list="country-options">
  <datalist id="country-options"><option value="France"></option></datalist>
</div>
<lr-combobox id="country-enhanced" name="country" label="Country" hidden>
  <lr-option value="France">France</lr-option>
</lr-combobox>
<script type="module">
  const fallback = document.querySelector("#country-fallback");
  const input = document.querySelector("#country-native");
  const combobox = document.querySelector("#country-enhanced");
  let registration;
  input.addEventListener("focus", async () => {
    if (!combobox.hidden) return;
    registration ??= import(
      "@aceshooting/lyra-ui/components/forms/combobox/combobox.js"
    ).catch((error) => {
      registration = undefined; // let a later interaction retry
      throw error;
    });
    await registration;
    await customElements.whenDefined("lr-combobox");
    combobox.value = input.value;
    fallback.hidden = true;
    combobox.hidden = false;
    combobox.focus();
  });
</script>
```

Leave the native control in place if registration fails. This pattern preserves the initial shell;
the full form-label, option, overlay, and first-open positioning contracts arrive in deferred
chunks instead of being weakened in a separate partial combobox implementation.

An `lr-option` row remains bounded by its owning listbox: the default label ellipsizes and each
`start`/`end` (or `prefix`/`suffix`) adornment is capped at 40% of the row. Unbroken metadata
therefore cannot widen a 320px LTR or RTL picker.

**Adornments in the popup (fixed in 11.0.0).** Before 11.0.0 this paragraph described behavior the
code did not have: `lr-combobox` builds its popup from normalized row *data* rather than from the
light-DOM nodes, so a slotted `start`/`end`/`prefix`/`suffix` adornment had nowhere to land and
simply never rendered — the documented slots and their documented parts were both dead inside the
one component `lr-option` exists to feed. They now render. The nodes are **cloned** into the row
(`option-start` / `option-end` parts, inert and `aria-hidden`, so they never join the option's
accessible name), which means the author's own `<lr-option>` subtree is left exactly where they put
it rather than being moved into a shadow root as a side effect of opening a dropdown:

```html
<lr-combobox label="Country">
  <lr-option value="fr"><lr-flag slot="start" country="fr"></lr-flag>France</lr-option>
  <lr-option value="mt"><lr-flag slot="start" country="mt"></lr-flag>Malta</lr-option>
</lr-combobox>
```

An async `source` row can carry the same two fields (`start`, `end`) alongside its existing `icon`.

### `lr-combobox`

**Properties:**

- `multiple: boolean = false` (reflected)
- `size: LyraSize = 'm'` (reflected — the shared control ladder, so both `2xs`/`xs`/`s`/`m`/`l`/`xl`
  and the `small`/`medium`/`large` spellings are accepted; also scales the "+N" overflow tag and
  decorative expand icon; `size="s"` shares its outer control height with `lr-input`, `lr-select`,
  and `lr-segmented` without part overrides)
- `pill: boolean = false` (reflected) — rounds the trigger row's corners to a full pill, mirroring
  `lr-input`'s own `pill`. It changes the private radius default to `--lr-radius-pill`, so an
  inherited or direct `--lr-combobox-radius` remains authoritative
- `placeholder: string = ''`
- `disabled: boolean = false` (reflected)
- `required: boolean = false` (reflected — enforced via `internals.setValidity()`; also reflected as
  `aria-required` on `<input part="combobox-input">` immediately. That semantic input exposes
  `aria-invalid="true"` whenever visible error chrome is present, or after interaction while
  intrinsic/custom validity fails; it explicitly returns to `"false"` when neither applies)
- `name: string = ''`
- `label: string = ''`
- `hint: string = ''`
- `errorText: string = ''` (attribute `error-text` — static error copy shown below the hint;
  overridden by slotted `error` content when provided)
- `open: boolean = false` (reflected)
- `allowCreate: boolean = false` (attribute `allow-create`) — a nonmatching query renders a
  localized create row. Activating it emits cancelable `lr-create`; unless vetoed, the component
  appends a real `<lr-option>` and selects it (also supported in `multiple` mode)
- `allowCustomValue: boolean = false` (attribute `allow-custom-value`) — single-select only;
  commits arbitrary text on Enter without creating an option
- `showUnknownOption: boolean = false` (attribute `show-unknown-option`, reflected) — appends every
  committed value that no option or async row claims to the end of the listbox as a synthetic,
  badged, keyboard-reachable, re-selectable row. Off by default. The synthetic row is filtered by
  the active query exactly like the `allow-create` row is, so a query it does not match neither
  shows it nor suppresses the "no matches" copy; re-picking it re-commits the same value and
  deliberately does **not** reclassify it as known — the badge and the row both survive, and the row
  never appears in `selectedRows`
- `getUnknownLabel?: (value: string) => string` (attribute: false) — renders the label for a
  committed value that matches no option or async row, everywhere it appears (trigger, `multiple`
  tag, synthetic row). `getTag` cannot serve this case: it is handed a matched option and there is
  none. A blank return falls back to the raw value. Not consulted while an async `source` fetch has
  never yet resolved for this element — see "Unknown committed values" below; `loadingText` covers
  that window instead, since the value is not yet known to be unmatched at all
- `appearance: 'filled' | 'outlined' | 'filled-outlined' = 'outlined'` (reflected)
- `placement: 'top' | 'bottom' = 'bottom'` (reflected; flip/shift can still keep the listbox in view)
- `positioningStrategy: PlaceStrategy = 'fixed'` (attribute `positioning-strategy`, reflected) —
  the CSS positioning scheme the listbox is laid out with, spelled the same as on `lr-select`,
  `lr-popover`, `lr-dropdown`, `lr-tooltip` and `lr-color-picker`. `fixed` is this control's
  default and what it has always rendered: it positions against the viewport and escapes most
  clipping ancestors, which suits a typeahead list that usually sits inside a scrollable region.
  `absolute` positions against the nearest containing block and scrolls with it. An unsupported
  value resolves to the default. Like `placement`, a change takes effect the next time the listbox
  opens. When the instance sets nothing, the cascading `--lr-positioning-strategy` custom property
  (`absolute`/`fixed`, set on `:root`, a theme, or one clipping ancestor) is honoured ahead of the
  default; an explicit instance value always wins. There is deliberately no `hoist` alias here:
  unlike on `lr-select`, where it is Shoelace's established spelling, it would be a boolean
  defaulting to `true`, so its attribute could only ever express the value the control already has
- `sync?: PlaceSync` (reflected) — copies the trigger's width, height, or both onto the listbox,
  spelled the same as on `lr-dropdown`/`lr-popup`/`lr-popover`. Unset (the default), the listbox
  sizes to its own content, clamped between `--lr-size-12rem` and `--lr-size-28rem`, exactly as
  before. `sync="width"` drops that content-based clamp so a full-width trigger with short option
  labels gets a listbox that aligns to its own edges instead of floating narrower in the middle.
  A synced listbox is capped on `--lr-positioner-available-inline-size` **alone** — the space the
  positioner actually measured beside the anchor, which still keeps an over-wide trigger from
  pushing it off-screen. `--lr-popover-viewport-clamp` does **not** apply to a synced listbox — its
  92vw default used to shorten the listbox against its own trigger in exactly the full-width case
  `sync` exists for, and `lr-popup` never applied it either. It still applies with `sync` unset.
  Like `placement`, a change takes effect the next time the listbox opens
- `clearable: boolean = false` (reflected) — displays the clear button while there is something to
  clear on **either** axis this control owns: a committed selection, or _visible_ filter text. See
  "the clear button covers two axes" below
- `withClear: boolean = false` (attribute `with-clear`) — Web Awesome's spelling of `clearable`;
  either one enables the same clear button. Not deprecated: Web Awesome names this attribute
  `with-clear` and Shoelace names it `clearable`, so honouring both is what keeps a mechanical tag
  rename from silently dropping the control
- `withLabel: boolean = false` and `withHint: boolean = false` (attributes `with-label` and
  `with-hint`) — SSR slot-presence hints
- `getTag: ((option: LyraOption, index: number) => unknown) | undefined` (attribute: false) —
  replaces a built-in multiple-selection tag with consumer Lit/DOM/text output; strings render as
  text, never as HTML
- `validators: LyraComboboxValidator[] = []` (attribute: false) — extra JavaScript validators run
  after the intrinsic `required` constraint, the same contract `lr-date-input` implements. Each
  entry may be a `(value, input) => void | boolean | string | ValidityStateFlags` function (`value`
  is the live `string | string[]`), an object with `validate(value, input)` returning that same
  vocabulary, or a Web Awesome-compatible object with `checkValidity(input)` returning
  `{ isValid, message, invalidKeys }`, where `invalidKeys` names `ValidityState` flags; that object
  may also expose `observedAttributes` and a string or callback `message`. Changing any listed host
  attribute revalidates automatically. `isValid: true` (or `true`/`undefined` from a function)
  passes; otherwise the listed flags are set (`customError` when the list maps to nothing) and the
  returned message wins over the validator-level fallback. A throwing validator fails closed with
  the localized generic message. `disabled` bars them exactly as it bars `required`
- `validationTarget: HTMLElement | undefined` — writable native-validity focus anchor. After the
  first render it defaults to the internal filter input; assign another element to override it, or
  assign `undefined` to restore that input. It is `undefined` before the input exists
- `autocomplete: string = 'off'`, `inputMode: string = ''` (attribute `inputmode`),
  `enterKeyHint: string = ''` (attribute `enterkeyhint`), `spellcheck: boolean = false`,
  `autocapitalize: string = ''`, and `autocorrect: boolean = true` (attribute values `on`/`off`) —
  native editing-assistance properties forwarded to the internal filter input. Removing a
  `spellcheck` attribute after an override restores this component's declared `false` default.
  The lowercase
  mapped IDLs `inputmode` and `enterkeyhint` delegate to the corresponding camel-case native
  properties
- `inputValue: string` — the live filter input text; programmatic writes are event-silent
- `maxOptionsVisible: number = 3` (attribute `max-options-visible` — caps how many selected **tags**
  show before collapsing to `+N`; nothing to do with the suggestion list, see the three-caps note
  below)
- `visibleOptions?: number` (attribute `visible-options`, new in 11.0.0) — bounds the popup to about
  this many suggestion rows, leaving the rest reachable by scrolling. Purely presentational: every
  row is still rendered. Measured from where row N actually starts rather than computed from a
  token, because a row's height varies with `sub` lines, adornments and group labels. Unset imposes
  no bound of its own and the listbox keeps exactly its previous max-height behavior; zero,
  negative, and non-finite values normalize to unset rather than collapsing the popup

**The three caps, which are easy to confuse.** `visibleOptions` caps how many suggestion rows are
*visible* (presentation; the rest scroll). `maxRender` caps how many suggestion rows are *rendered
at all* (performance; the rest do not exist and are summarized by `option-overflow`).
`maxOptionsVisible` caps how many *selected tags* show in multi-select and never touches the
suggestion list.
- `emptyText?: string` (attribute `empty-text`) — omission displays localized `noMatches` (`"No
matches"` in the built-in English locale); any supplied string, including `''`, renders verbatim
- `loadingText?: string` (attribute `loading-text`) — shown while a `source` fetch is in flight,
  and in place of the raw value on the trigger/tag for a committed value the fetch has never yet
  resolved (see "Unknown committed values" below); omission displays localized `loading`
  (`"Loading…"` in English), while any supplied string, including `''`, renders verbatim
- `overflowText?: string` (attribute `overflow-text`) — shown when `maxRender` caps the rows;
  omission displays localized `comboboxOverflow` (`"+{n} more — refine your search"` in English).
  A supplied template wins verbatim over `.strings`, including when it equals that English
  template or is empty; `{n}` is still replaced with the locale-formatted hidden count
- `filter: OptionFilter | null = null` (attribute: false — `(option, query) => boolean`; default
  matches `label`/`searchText` case-insensitively; ignored while `source` is set)
- `source: ComboboxSource | null = null` (attribute: false — `(query: string, options: { signal:
AbortSignal; limit: number }) => Promise<readonly ComboboxSourceRow[] | { rows, total? }>`; when set, replaces the light-DOM `<lr-option>`
  list with an async lookup, debounced by `sourceDelay` ms after each keystroke and re-run on
  clear/pick. Forward `options.signal` to `fetch(url, { signal })` to cancel the request when a
  newer query supersedes it or the element disconnects. `loadingText` is shown while a call is in
  flight; a stale in-flight call that resolves after a newer one (or after disconnect) is dropped
  via a monotonic token. The exported type requires the `options` parameter; an existing
  one-parameter `(query) => …` function remains assignable under TypeScript's ordinary function
  parameter compatibility, but consumers that need cancellation should accept and forward
  `options.signal`; honor `options.limit` when practical and return `{ rows, total }` to report the
  provider-side match count. The component independently clone-normalizes the result, retains at
  most 2,000 rows/250,000 aggregate text units, skips malformed or hostile rows, and never trusts a
  provider to enforce the ceiling. A current rejection clears stale rows and renders a localized disabled
  listbox row; that visible row is not a shadow live region. The same localized message is appended
  to `[data-lr-live-region="assertive"]` in the document for each fresh post-mount rejection,
  including an identical retry, while raw caught error text stays out of the UI.)
- `sourceDelay: number = 200` (attribute `source-delay` — debounce in ms between the last keystroke
  and the `source` call; `0` fires on every keystroke. Sanitized to a finite non-negative duration,
  falling back to `200` for a non-finite value)
- `maxRender: number = 200` (attribute `max-render` — caps how many rows render at once, always
  keeping the current selection visible even if it's outside the cap; the excess renders as one
  `overflowText` row instead of being dropped silently. See "Large option lists" below for how to
  size it, and when `source` is the better answer. Runtime writes are capped at 1,000)
- `sourceTotal: number` (read-only) — provider-side total for the latest accepted response
- `sourceTruncated: boolean` (read-only) — whether the response reported or contained more rows
  than the bounded retained snapshot; the overflow row includes that hidden count
- `value: string | string[]` — a getter/setter: plain `string` in single mode, `string[]` in
  `multiple` mode. Assigning `undefined`/`null` clears the selection; every string, including `''`,
  is instead a candidate value resolved against the current local options/async rows — an
  `<lr-option value="">` (or a matching async row) is legitimate and round-trips like any other
  value. A value matching no current option/row still commits rather than being dropped or treated
  as a clear — see "Unknown committed values" below
- `customError: string | null` (attribute `custom-error`) — reflected consumer validation message
- `selectedRows` (read: `ComboboxSourceRow[]`; write: `readonly ComboboxSourceRow[]`) — structured
  rows for the current selection, including any opaque `data` payload supplied by an async source
  row or a light-DOM `<lr-option data>`, reached by reference and never deep-cloned.
  Reads return detached row snapshots. Writes select stable row values resolved against the
  current or deferred source, dropping duplicate and detached values without emitting selection
  events. Selected async rows remain available after the query changes or a later source result
  no longer contains them
- `selectionStart`, `selectionEnd`, and `selectionDirection` — selection getters/setters forwarded
  to the internal input

**Unknown committed values.** A committed value matching no current option/row (a stale value from
a removed option, or a programmatic assignment with a typo) still commits — the raw string stays
fully reachable through `value`/`selectedRows` — but renders a dashed/italic
`[part='unknown-value']` badge next to the closed single-select input, or on the relevant
`multiple`-mode tag, instead of an unexplained bare label, mirroring `<lr-model-select>`'s synthetic
"not in catalog" stale-value row — see `--lr-combobox-unknown-value-border-style`/`-color` below.
The badge is suppressed while an async `source` fetch has never yet resolved for this element —
from mount through the debounce delay and the in-flight call itself — and never shown for an
`allowCustomValue` commit, which is a sanctioned unmatched value, not a stale one. Over that same
unresolved window the raw value itself is also withheld: the trigger (and any `multiple`-mode tag
for the same value) shows the `loadingText` placeholder instead, so a value seeded before its async
catalogue has ever answered never flashes an unexplained, unbadged machine key. Once the fetch
settles — success or failure — the raw value returns, badged if it still matches nothing.

**Methods:** `focus(options?)`, `blur()`, `select()`, `setSelectionRange()`, and `setRangeText()`
forward to the internal input. `setRangeText()` synchronizes the filter query and visible options.
`show(): Promise<void>` and `hide(): Promise<void>` settle after `lr-after-show` and
`lr-after-hide`, respectively. `refresh(): void` re-runs the current `source` query without changing
the source's identity, its debounce controller, or its delay. Reassigning `source` is a provider
change and clears the fetched rows and pending-selection cache; `refresh()` does not. It queues for
the next open while the listbox is closed, and is a no-op without a `source`. `resetValidity()`
clears consumer custom validity and restores the current intrinsic constraints. `getForm()` returns the owning form, including an external owner
selected by the `form` attribute.
`setCustomValidity(message)` carries a rejection no client-side constraint can express ("that option
is no longer available"): a non-empty message raises `customError`, becomes `validationMessage`, and
blocks submission; `''` clears it and restores the control's own computed validity, so a `required`
combobox with nothing chosen goes back to `valueMissing` rather than to valid. The message survives
every selection change and a `form.reset()` — like a native control, only another
`setCustomValidity('')` or `resetValidity()` clears it — and is used verbatim, never localized.

**8.0 migration:** the former camel-case string property `autoCorrect` is not retained as a public
alias. Set the boolean `autocorrect` IDL, or use `autocorrect="on"` / `autocorrect="off"` in markup.

`ComboboxSourceRow = { readonly value: string; readonly label: string; readonly sub?: string; readonly icon?: unknown; readonly start?: unknown;
readonly end?: unknown; readonly badge?: string |
number; accessibleLabel?: string; data?: unknown; dotColor?: string; group?: string; disabled?:
boolean }` — the row shape used by the async `source` path. `start` and `end` (new in 11.0.0) are
the async counterparts of `<lr-option>`'s `start`/`end` adornment slots and render as the
`option-start` / `option-end` parts, inert and aria-hidden exactly like `icon`. `icon` renders as a decorative leading
visual whose rendered subtree stays visible but is inert and hidden from assistive technology;
put independent actions outside it. `badge` renders as trailing metadata, `accessibleLabel` can
provide richer spoken text than the visible label, and `data` is retained without being rendered
for retrieval through `selectedRows`.
`dotColor` accepts a valid CSS `color`; invalid values, declaration-breaking input, and `url()`
render a transparent dot.
The light-DOM `<lr-option>` path normalizes its supported label/sub/dot/group/data fields to the
same internal row model — `<lr-option data>` is the light-DOM counterpart of an async row's own
`data` field, reached by reference through `selectedRows` exactly the same way.

When a local option is removed or becomes disabled, or an async response shrinks, an existing
keyboard-active row clamps to the nearest enabled survivor. If every row is disabled or removed,
`aria-activedescendant` clears; an untouched list with no active row remains untouched.

**Events:** typing in the filter exposes the original bubbling/composed, non-cancelable `InputEvent`
as exactly one host `input` event (no `value` detail) and does not fire `change`. An actual user
selection mutation — pointer or keyboard selection, multiple-value toggle, tag/Backspace removal, or
clear — emits exactly one bubbling/composed, non-cancelable `input` `CustomEvent`, immediately
followed by the same shape of `change`, then a prefixed `lr-change` alias. All three carry
`detail: { value; data: readonly unknown[] }` — `value` is the new committed selection (a string in
single mode, a `string[]` in `multiple` mode); `data` is index-aligned with `value`: `data[i]`
describes `value[i]` — the opaque `data` payload of a light-DOM `<lr-option data>` or an async
source row's own `data`, reached by reference and never deep-cloned — or `undefined` in that
value's own slot when it currently matches no live row/option (see "Unknown committed values"
above; unlike `selectedRows`, which drops that entry instead). `lr-change` mirrors `<lr-checkbox>`'s namespaced alias; subscribe to it when you
want a `lr-`-prefixed event, or to the native-style `input`/`change` for parity with a native
control. Re-picking the current single value and programmatic/default/reset/restore writes are
silent (including on `lr-change`). The clear button emits one `lr-clear` after its
`input`/`change`/`lr-change` triple.
`lr-activate` (`detail: { value: string }`, bubbling/composed, non-cancelable) fires on **every**
activation of an available listbox row — a click, or Enter on the active row — whether or not the
selection actually moved. Its `value` is the activated option's own value, **always a single
string**, even in `multiple` mode, where the `input`/`change`/`lr-change` triple carries the whole
`string[]` instead. It reports that the user picked a row and gates nothing. Use it for the
single-select repeat pick that `change`/`lr-change` deliberately stay silent for — "re-run that
filter" is a real intent — which is otherwise unobservable, because the rows live in this shadow
root, so a retargeted `click` names no option and a keyboard commit produces no click at all. When
an activation _does_ move the selection, `input`/`change`/`lr-change` are emitted first, so either
listener reads the settled selection. Not fired for typing, for a committed custom value matching no
row, for the clear button, or for a programmatic `value` assignment.
`lr-filter` (`detail: { value: string }`) reports the in-progress filter text on every user-driven
keystroke — the live as-you-typed search string, deliberately _not_ `value`, which is the committed
selection. It is the supported way to read that text; reaching into the shadow root for
`[part="combobox-input"]`'s value is not. Named `lr-filter` rather than `lr-input` precisely because
`lr-input`'s detail on `<lr-input>` is the committed value, and the two must not share a name while
carrying different strings. It fires for user edits only. Picking a row, `form.reset()`, dismissing
the listbox, and a programmatic `value` write blank the filter silently. `setRangeText()` silently
replaces the requested or selected native text range, synchronizes the resulting query and visible
options, and refreshes an async source when present; it preserves the committed selection.
Activating the clear button is a user edit: when a query existed it emits `lr-filter` with
`value: ''` before the clear transaction finishes.
`lr-show` and `lr-hide` report the start of listbox visibility transitions. `lr-show` is a
cancelable veto point; `lr-hide` is cancelable while connected, but the disconnect-driven close is
non-cancelable because an already-removed control cannot honour a veto. Vetoing a connected close
is atomic: the filter query, active option, async result rows, reflected `open` state, and overlay
ownership remain unchanged, so the host can defer dismissal without reconstructing the search.
`lr-after-show` and
`lr-after-hide` fire when the corresponding transition settles. `lr-create` carries
`detail: { inputValue }` and is also cancelable: preventing it suppresses the default append/select
action so the host can normalize and commit its own option.
The internal input's `focus` and `blur` are relayed exactly once from the host as owner-realm
native `FocusEvent`s. Both bubble, cross the shadow boundary, and preserve `relatedTarget`.
`lr-invalid` (no detail) is emitted once as a bubbling/composed, **cancelable** alias when native
validity fails — see "The validity alias is cancelable in 8.0.0" above.
`lr-source-error` is non-cancelable, `detail: { error, query }` carrying the raw rejection from an
async `source` call plus the exact query string that call was made with (the rejected call's own
query, not necessarily the live `query`/`inputValue`, which may have moved on — or been cleared by
closing the listbox — by the time the rejection settles). The rendered copy stays localized and
never shows the raw error.
`lr-retry` is cancelable; the built-in failed-load action calls `refresh()`, and `preventDefault()`
leaves the failure on screen. While the failure state is the only popup content, the popup swaps
`role="listbox"` for `role="dialog"` (the input gains the matching `aria-haspopup="dialog"` and
drops `aria-activedescendant`, and the popup carries the localized failure heading as its accessible
name). `dialog` is one of the four popup roles WAI-ARIA lets a `role="combobox"` own, so the still
expanded `aria-controls` target keeps a valid owner while holding a retry `button` that is not a
legal listbox child. A successful retry restores `role="listbox"`.

**The clear button covers two axes, and announces only the one that moved.** A combobox owns both a
committed selection and an in-progress filter query, so the button renders whenever either has
something to clear, and one press clears both:

- Clearing a selection emits `input`, then `change`, then `lr-change`, then `lr-clear` — and, if the
  query was also non-empty, `lr-filter` with an empty `value`.
- A **query-only** clear (nothing selected, just typed text) emits `lr-filter` with an empty
  `value` and deliberately **no** `change` and **no** `lr-clear`. There was no selection
  transition to report, so announcing one would be a lie. Don't listen for `lr-clear` to detect
  "the user emptied the field" — listen for `lr-filter` when you care about the query.
- The query half of the render gate is scoped to states where the query is actually _visible_: an
  open listbox in single-select, or any time in `multiple` mode. A closed single-select shows the
  selected label rather than the query, so a stale query alone never surfaces a button offering to
  clear text the user cannot see.

**Large option lists: sizing `maxRender`, and why the listbox is not windowed.** Every row that
survives the filter and fits under `maxRender` is a real DOM element — the listbox renders its rows
in full rather than recycling a small window of them across a scroll. That is a deliberate
accessibility constraint, not an omission: the filter input carries `aria-activedescendant`, which
is an **IDREF**, and an IDREF only resolves within its own tree scope. Moving the rows into the
library's windowing primitive (`<lr-virtual-list>`) would place them one shadow root deeper than the
input that has to point at them, where neither the attribute nor its `ariaActiveDescendantElement`
element-reflection replacement can reach — element reflection resolves same-root or upward only. So
`<lr-virtual-list>` stays `role="list"`/`role="listitem"` and is the right tool for feeds and
viewers, not for a listbox whose active row must stay addressable.

What that means in practice:

- **Up to a few hundred rows, raise `maxRender` and move on.** A few hundred flex rows is an
  unremarkable amount of DOM; a country, currency, or time-zone list (typically 200–450 entries)
  renders comfortably with `max-render` set to cover it. The cap exists to bound pathological
  cases, not to make lists of that size expensive.
- **Past roughly a thousand rows, reach for `source` instead of a larger cap.** An async source
  narrows the candidate set before it ever becomes DOM, which is a categorically better trade than
  rendering everything and asking the browser to lay it out. Pair it with `sourceDelay` to debounce.
- **Leave the overflow row doing its job.** When the cap does bite, the excess collapses into one
  `overflowText` row (default `"+{n} more — refine your search"`) rather than disappearing
  silently, and the current selection is always kept visible even when it falls outside the cap.
  Suppressing that row by setting `maxRender` far above the real list size trades a useful "keep
  typing" affordance for layout work no user asked for.

**Slots:** default (`<lr-option>` children), `label`, `hint`, `error` (overrides the `errorText`
attribute when provided), plus two adornment slots:

- `start` — content at the inline-start of the trigger row, before the selected-value tags and the
  filter input. It is decorative chrome, **not** an option: only `<lr-option>` elements in the
  default slot are ever collected into the option list.
- `end` — content after the filter input and the built-in clear action, and before the expand icon,
  so consumer content never sits outboard of the dropdown chevron.
- `clear-icon` and `expand-icon` replace the corresponding built-in glyphs.
- `source-error` — replaces the built-in failed-`source` state, retry control included. Deliberately
  named apart from the form-control `error` slot: they are different failures and a field has to be
  able to show both.

**CSS parts:** `form-control`, `form-control-label`, `label`, `form-control-input`, `combobox`,
`start` and `end` (the two
adornment-slot wrappers, each `hidden` while nothing is slotted into it), `tags`, `tag`,
`tag-label`, `tag__content`, `tag__remove-button`, `tag__remove-button__base`, `combobox-input`,
`clear-button`, `unknown-value` (the dashed/italic badge shown next to the closed single-select
input, or on a `multiple`-mode tag, when the committed value matches no current option/row),
`expand-icon`, `listbox`,
`group-label` (the heading of an option group — rows sharing a `group` — named as on `lr-select` and
`lr-emoji-picker` so one rule styles every grouped list; it labels the `role="group"` wrapper here),
`option`,
`option-dot` (the leading status dot, when a row's `dotColor` is set), `option-icon` (the inert,
aria-hidden decorative leading visual for an async row), `option-start` and `option-end` (the inert,
aria-hidden adornments cloned from the source option's `start`/`prefix` and `end`/`suffix` slots, or
from an async row's `start`/`end`), `option-label`, `option-sub` (a row's
secondary line, when `sub` is set), `option-badge` (an async row's trailing metadata),
`option-overflow` (the "+N more" indicator from `maxRender`),
`source-error-row` (the listbox row holding the failed-`source` state), `source-error` (the shared
failed-load state itself, with `source-error-base`, `source-error-icon`, `source-error-heading`,
`source-error-description` and `source-error-actions` forwarded from the composed `<lr-empty>`),
`retry-button`, `error`, `hint`

**TypeScript:** `LyraCombobox<Multiple extends boolean = boolean>` — `value`/`defaultValue` and the
`lr-change`/`lr-input` detail `value` narrow to `string` when `Multiple` is `false` and `string[]`
(`readonly string[]` in a detail) when `true`. Types only; the runtime and the mirrored surface are
unchanged, and an untyped `<lr-combobox>` keeps `string | string[]`.

**The required marker.** `required` with a non-empty `label` paints the library's shared marker on
`[part="form-control-label"]` — the one `::after` rule described above, not a copy of it, so
`--lr-form-control-required-content`, `--lr-form-control-required-color` and
`--lr-form-control-required-offset` retune or suppress it here exactly as they do on `lr-input`.
With no label text the part is hidden and no glyph is painted.

**Themeable custom properties:** `--lr-combobox-trigger-padding`,
`--lr-combobox-trigger-min-height`, `--lr-combobox-font-size`, `--lr-combobox-tag-padding`,
`--lr-combobox-tag-font-size`, `--tag-max-size` (default `var(--lr-size-5rem)`), `--show-duration`,
`--hide-duration`, and `--lr-combobox-expand-size` (the decorative icon box; each
standard size supplies an aligned default), plus shared tokens. `--lr-combobox-gap` (default
`--lr-space-xs`, the gap inside `[part='combobox']`) and `--lr-combobox-radius` (default
`--lr-radius`, its corner radius) are both retunable without a `::part(combobox)` rule but, unlike
the properties above, do not vary by `size` — the same `--lr-button-gap`/`-radius` pattern.

The trigger row's own surface became public in 16.0.0, having been a private pair until then:
`--lr-combobox-fill` (default `var(--lr-color-surface)`) and `--lr-combobox-border-color` (default
`var(--lr-color-border)`). The `filled`/`filled-outlined` treatments default the fill to
`var(--lr-color-surface-raised)` and `filled` defaults the border to `transparent`; a value set
here wins over every treatment. `--lr-combobox-open-border-color` (default
`var(--lr-color-brand)`) recolors the row's edge while it holds focus, which was a hardcoded brand
border before. Read the name as the state the listbox opens in rather than as a synonym for `open`:
it is bound to `:focus-within`, so it also paints on a focused row whose listbox is closed — after
an Escape dismissal, say. It is named for symmetry with `lr-select`'s
`--lr-select-open-border-color`, which really is gated on `open`.

The shared field halo `--lr-form-control-focus-shadow` (default `none`) paints a `box-shadow`
while this control is focused — one name for every field-shaped control in the library, so a
halo is configured once instead of per component. It is additive: the focus outline and
border cue are the accessibility answer to focus and are never replaced by it.

`--lr-combobox-option-active-bg` (default `var(--lr-color-brand-quiet)`) recolors the background of
a hovered or keyboard-active `[part='option']` row — the same per-component indirection
`lr-select`'s identical `--lr-select-option-active-bg` uses, so a consumer can retheme just this
row state without hijacking the shared `--lr-color-brand-quiet` token library-wide.

The currently-**selected** row (`[part='option'][aria-selected='true']`) has its own matching set:
`--lr-combobox-option-selected-bg` (default `transparent`), `--lr-combobox-option-selected-border`
and `--lr-combobox-option-selected-color` (both default `var(--lr-color-brand)`), and
`--lr-combobox-option-selected-font-weight` (default `var(--lr-font-weight-semibold)`) — the same
four-token indirection `lr-select`/`lr-model-select` already provide for their own selected row.
Like the active-bg knob these are inline `var()` fallbacks, not declared on `:host`, so a consumer
can retheme the selected row without hijacking `--lr-color-brand` library-wide.

The listbox popup itself is a floating surface and paints from the **shared overlay-surface family**
(16.0.0), not from the page surface every card and input reads: `--lr-overlay-surface` (default
`var(--lr-color-surface-overlay)`), `--lr-overlay-border` (default `var(--lr-color-border)`),
`--lr-overlay-radius` (default `var(--lr-radius)`) and `--lr-overlay-shadow-anchored` (default
`var(--lr-shadow-m)`). None is declared on `:host`, so one declaration on `:root` — or on any
ancestor, to scope it — retints this popup together with every other floating surface, and none of
it touches the trigger row the popup drops from.

`--lr-combobox-unknown-value-border-style` (default `dashed`) and
`--lr-combobox-unknown-value-border-color` (default `var(--lr-color-border)`) retheme the
`[part='unknown-value']` badge described above under "Unknown committed values".
`--lr-combobox-option-badge-bg` (default `var(--lr-color-brand-quiet)`) retints the
`[part='option-badge']` trailing metadata badge on an async row, and the "not in catalog" badge
`show-unknown-option` renders on the synthetic unmatched-value listbox row — the same
per-component indirection `lr-select`'s `--lr-select-option-badge-bg` uses.

`--lr-combobox-trigger-height` pins an **exact** input-container height (both floors and caps it),
for pixel-matching an `<lr-input>` or `<lr-select>` in the same toolbar row. It is **undeclared by
default**, leaving `--lr-combobox-trigger-min-height` as a floor only and the row free to grow —
see "exact-height hatches" under `lr-input` for why `auto` is not a way to opt back out. Intended
for a single-row combobox: in `multiple` mode, a tag row long enough to wrap overflows the pinned
box visibly (nothing is clipped or made unreachable), so leave it unset there.

**CSS custom states:** `blank`, `disabled`, `required`, `optional`, `valid`, `invalid`,
`user-valid`, and `user-invalid`.

**Optional peer deps:** none.

### `lr-option`

**Properties:**

- `value: string = ''`
- `disabled: boolean = false`
- `defaultSelected: boolean = false` (attribute `selected`; property writes do not reflect) — the
  declarative and `form.reset()` default. Changing it after mount updates the parent's reset
  baseline without overwriting a dirty live selection
- `selected: boolean = false` (property only) — live selectedness. The parent combobox/select
  updates it as the current value changes; those live writes never rewrite the `selected`
  attribute or `defaultSelected`
- `group: string = ''` (section header)
- `searchText: string = ''` (attribute `search-text` — extra text the filter matches beyond the
  visible label)
- `sub: string = ''` (optional secondary line rendered under the label, e.g. a status/date summary)
- `dotColor: string = ''` (attribute `dot-color` — optional CSS color for a small leading status
  dot; invalid values, declaration-breaking input, and `url()` render the dot transparently)
- `data?: unknown` (attribute: false) — opaque application payload, e.g. the backend record this
  option represents. Never read or rendered by this component; retained by reference, never
  deep-cloned, through the owning `lr-combobox`'s `selectedRows` and the owning `lr-select`'s
  `selectedData`, and in both controls' `lr-input`/`lr-change`/`input`/`change` event details.
  Assigning it notifies the owning picker with `lr-option-change`, like `sub`/`dotColor`/`group`
- `label: string` — settable WA-compatible plain-text label. A non-empty property/attribute wins;
  otherwise it resolves to `defaultLabel`. Property writes stay property-only (no reflection)
- `defaultLabel: string` (read-only) — normalized accessibility-visible text generated from the
  flattened default slot. Hidden subtrees are excluded, visible nested `aria-label` values replace
  their descendants, and `start`/`end`/`prefix`/`suffix` adornments are excluded. Direct and
  forwarding-slot mutations update the value and notify the owning picker

**Method:** `getTextLabel(): string` returns `defaultLabel`, preserving Shoelace's content-derived
plain-text contract even when a separate WA `label` override is present.

**Events:** `lr-option-change` — bubbles when the option's label or selectable data changes so
its parent `lr-combobox` or `lr-select` can refresh its normalized option rows. It is a private
child-to-parent refresh signal, not a picker event: the owning `lr-combobox`/`lr-select` consumes
it and stops it, so it never reaches a listener on the picker host (whose own contract is
`lr-change`/`lr-input`/`change`/`input`). Listen on the `<lr-option>` itself to observe it.

**Slots:** default (visible label), `start`/`end` (WA adornments), and `prefix`/`suffix` (Shoelace
aliases). `start` and `prefix` project into one leading wrapper; `end` and `suffix` project into one
trailing wrapper.

**CSS parts:** `base`, `checked-icon`, `label`, `start`/`prefix` (same node), and `end`/`suffix`
(same node). **CSS custom property:** `--current-text-color` (default `var(--lr-color-text)`) colors
the keyboard-current row. **CSS custom states:** `current` (the host is the roving-focus target),
`selected`, `disabled`, and `hover` (pointer presence, including drag sessions).

Own-anatomy state hooks are `--lr-option-hover-bg`, `--lr-option-active-bg`,
`--lr-option-current-bg`, `--lr-option-current-color`, `--lr-option-selected-font-weight`, and
`--lr-option-checked-icon-color`. Their defaults preserve brand-quiet hover/current paint, the
shared active mix, semibold selected text, and the brand checkmark. The current-color hook falls
back through upstream `--current-text-color`, so existing themes keep working.

The stock `lr-combobox` and `lr-select` intentionally treat each option as light-DOM data and
render normalized rows in their own shadow roots. Style those rows through the parent's `option`,
`option-label`, and related parts; the parts above style an option's own anatomy when it is rendered
by a custom owner.

```html
<lr-combobox id="cb" label="Country" placeholder="Search…" with-clear>
  <lr-option value="fr">France</lr-option>
  <lr-option value="de" search-text="deutschland">Germany</lr-option>
</lr-combobox>
<script type="module">
  document
    .getElementById("cb")
    .addEventListener("change", (e) => console.log(e.target.value));
</script>
```

```html
<!-- Async data source instead of light-DOM <lr-option> children: -->
<lr-combobox id="cb2" label="Fruit (async)" with-clear></lr-combobox>
<script type="module">
  document.getElementById("cb2").source = async (query) => {
    const rows = await fetchFruit(query); // your own lookup
    return rows.map((r) => ({
      value: r.id,
      label: r.name,
      icon: renderFruitIcon(r), // decorative; hidden from assistive technology
      badge: r.category,
      accessibleLabel: `${r.name}, ${r.category}`,
      data: r, // retained in cb2.selectedRows after selection
    }));
  };
</script>
```

Multi-select submits as **repeated `FormData` entries** (not a joined string) —
`new FormData(form).getAll(name)` behaves like a native multi-value control. An unnamed multi-select
(`multiple` with no `name`) contributes nothing to the form at all, matching a nameless native
`<select multiple>`, rather than falling back to a shared literal key that could collide with
another unnamed combobox in the same form.
Session-history/autofill state is stored as a name-independent JSON string array. A valid string
array restores the selection (single mode keeps its first entry); malformed or wrong-shape state
restores an empty selection. Restored state wins even when it arrives before the first option
collection, while `form.reset()` still returns to the declarative selected default. Restoration is
synchronous and fires no `input`/`change`/`lr-change` event.

**Known gotchas:**

- `with-clear` and `clearable` are equivalent and both are supported indefinitely; prefer
  `clearable` in new code. `lr-input` and `lr-select` accept both spellings too.
- a host-level `aria-label` attribute on `<lr-combobox>` now takes priority over `label`/
  `placeholder`/`"Combobox"` when resolving the accessible name on `[part="combobox-input"]` —
  previously it was silently ignored. Matches the same fallback on `<lr-select>`.
- `aria-required` reflects `required` immediately; `aria-invalid`, by contrast, only reflects
  **after the field has been touched** (first `blur`) — a `required` field with a validity error
  doesn't look invalid to assistive tech before that, by design (avoids flashing invalid styling on
  first render). Blurring the input (Tab away) now also closes an open listbox, the same as a
  native `<select>`'s popup, not just a click outside or Escape.
- `dotColor`/`sub`/`group` are read from light-DOM `<lr-option>` children as before, but are also
  first-class fields on `ComboboxSourceRow` for the async `source` path — an async lookup can drive
  the same grouped/dot/sub-text rendering a static option list can.
- `icon`, `badge`, and `accessibleLabel` are async-source row features rather than `<lr-option>`
  properties. Icons are decorative (`aria-hidden`); use `accessibleLabel` when the visible
  label/sub/badge combination needs a fuller spoken name. `data`, by contrast, is a first-class
  `<lr-option>` property too (the light-DOM counterpart of the async row's own `data`): it is
  deliberately opaque, never rendered, and reachable through the read-only `selectedRows` getter
  (combobox), the read-only `selectedData` getter (select), and both controls' `lr-input`/
  `lr-change`/`input`/`change` event details.
- Full ARIA 1.2 combobox pattern (`role=combobox`, roving `aria-activedescendant`, real DOM focus
  kept on the input) is implemented correctly — a genuine strength, safe to build on.
  `<lr-option value="b" selected>` sets that option's `defaultSelected`, seeds the live selection,
  and supplies the `form.reset()` baseline, mirroring native `<select><option selected>`. A
  later-slotted option or post-mount `defaultSelected` change updates that baseline and updates the
  live selection only while it is pristine. A user pick or direct `option.selected` write makes the
  live selection dirty and never rewrites the declarative `selected` attribute/reset default.
- The floating listbox participates in Lyra's shared nonmodal overlay stack. Its computed
  `--lr-overlay-stack-index`, Escape owner, outside-pointer dismissal, and focus handoff follow the
  newest open Lyra overlay. Opening it above a color picker (or vice versa) therefore closes only
  the visual top layer per Escape/pointer action rather than both popups.

**Additional API surface:**

- `part="tag-label"` — The selected-tag label. Kept on one line and truncated with an ellipsis at `--tag-max-size` (default `var(--lr-size-5rem)`), rather than wrapped. Note that `lr-select`'s tag of the same name defaults to `var(--lr-size-12rem)`, so the same `--tag-max-size` value yields a wider tag there.

---

## `lr-select`

A plain closed-list dropdown — a direct `<lr-*>` counterpart to `<wa-select>`/`<wa-option>`.
**Form-associated** (hand-rolled internals, not the shared `FormAssociated` mixin — same reasoning
as `lr-combobox`: `multiple` re-shapes the committed `value` into a `string[]`, which the shared
mixin — built for a single string value — can't model, so both controls attach their own
`ElementInternals` and drive `setValidity()` directly instead). The trigger is a `<button>`, not a text
input: click/Enter/Space/ArrowDown opens it, and there's no typing-to-filter. Options are
`<lr-option value>` children — the same element `<lr-combobox>` uses — reconciled the same way
combobox does. The popup reuses `internal/positioner.ts` for placement and participates in Lyra's
shared nonmodal overlay stack.
Session-history/autofill restoration assigns the stored string through the same synchronous
value/form/validity path as a programmatic value write and does not emit `input`, `change`, or
`lr-change`.

Mounted `option.selected` assignments update the picker value and form submission immediately,
including deselection and equal-value writes. Duplicate-valued options retain their individual
occurrence identities. These programmatic writes emit no user input/change event.

Host `aria-describedby` resolves external guidance onto the trigger before internal value, error,
and hint guidance. References track missing targets, replacement, removal/reinsertion, reconnect,
and adoption. Removing `label`, `hint`, `help-text`, or `error-text` safely omits the content
without changing native `null` property readback; explicit empty strings remain empty.

There is no typing-to-filter and no `filter`/`source`/`empty-text`/`max-render` surface — reach for
`<lr-combobox>` instead whenever any of those apply. Everything else a closed list needs is here:
`multiple`, `max-options-visible`, `with-clear`, `getTag`, `placement`, `appearance`, and `pill`.

The trigger and its overlaid multi-select tag row accept constrained allocation. Long selected
labels ellipsize; long built-in tags wrap and cap their labels, so single and multiple selections
stay inside exact-320px LTR and RTL containers alongside start/end adornments.

**Multi-select (`multiple`, new in 8.0.0, default `false`).** Setting it re-shapes `value` from a
`string` into a `string[]` and renders one chip per selection. The `[part="tags"]` row is a sibling
overlaid on the real trigger, so every built-in tag remove button is valid independently-focusable
interactive content rather than a button nested inside another button. Picking a selected row,
Backspace/Delete on the focused trigger, and the `with-clear` action remain equivalent removal
paths. Selection identity is the option occurrence, not just its string: two same-valued rows may
both remain selected, render their own labels, submit duplicate entries, and be removed separately.
The trigger retains one genuinely visually-hidden current-value node containing **every**
selected label, even past `max-options-visible`; painted built-in chip labels and the overflow chip
are hidden from the accessibility tree so that value is announced once rather than truncated or
duplicated. Turning `multiple` back off collapses
the selection to its first entry, so the single-mode string and the submitted entry can never
disagree with what the trigger shows.

A `multiple` select submits **one form entry per selected value** under its `name`, so
`new FormData(form).getAll(name)` behaves like a native multi-value control rather than returning a
joined string. An unnamed multi-select contributes nothing to the form at all, matching a nameless
native `<select multiple>`. Session-history/autofill state is a JSON string array in `multiple` mode
and the plain submitted string in single mode; malformed state restores an empty selection. The
listbox renders `aria-multiselectable` in **both** states (`"true"` and `"false"`), never omitting it.

**Breaking in 8.0.0:** `value` is now typed `string | string[]` even in single mode. A TypeScript
consumer that read it as a plain string needs a narrowing step —
`const v = el.value; const single = typeof v === 'string' ? v : (v[0] ?? '');`

**Single-option auto-commit.** Opt-in via `autoCommitSingleOption` (default `false` — a select always
renders the normal combobox/listbox/chevron trigger unless enabled, matching pre-1.3.0 behavior).
When set and exactly one option is available (neither disabled nor inert, including through an
inert ancestor), the popup never opens at all: a click, Enter, Space, ArrowDown, or ArrowUp on the
trigger
commits that sole option directly, and the trigger renders as a plain `role="button"` with no
chevron/`aria-haspopup`/`aria-expanded`/`aria-controls`/`aria-activedescendant` rather than a
combobox with a permanently inert popup state — opening a one-row list to pick the only available
choice is pure friction with no real decision behind it. It never changes `value`/validity defaults
on its own: an unselected single-option select stays unselected (and a `required` one stays invalid)
exactly like the multi-option case, until the trigger is actually activated.

**Properties:**

- `placeholder: string = ''` — text shown on the trigger while nothing is selected, and the
  trigger's accessible name when neither a host `aria-label` nor a `label` supplies one. One
  exception to "an empty selection always shows this": while `loading` is `true` the trigger shows
  the localized `loading` text instead — see `loading` below. The accessible name is unaffected
  either way
- `disabled: boolean = false` (reflected)
- `required: boolean = false` (reflected — enforced via `internals.setValidity()`)
- `name: string = ''`
- `label: string = ''`
- `hint: string = ''`
- `errorText: string = ''` (attribute `error-text` — static error copy shown below the hint;
  overridden by slotted `error` content when provided)
- `open: boolean = false` (reflected). Direct or fieldset-cascaded disablement synchronously forces
  it closed; every later property or attribute attempt to open remains normalized to `false` until
  the control is enabled again
- `size: LyraSize = 'm'` (reflected — the shared control ladder, same scale as
  `lr-input`/`lr-combobox`/`lr-button`, for compact toolbar placements that don't fit the default
  trigger height. Both spellings of every tier are accepted: `2xs`/`xs`/`s`/`m`/`l`/`xl` and
  `small`/`medium`/`large`)
- `appearance: 'accent' | 'filled' | 'outlined' | 'filled-outlined' | 'plain' = 'outlined'`
  (reflected) — the library's shared field-surface vocabulary. `outlined` (the default) is a
  bordered surface; `filled` swaps the border for a raised fill; `filled-outlined` keeps both;
  `plain` drops both; `accent` paints the loud brand fill with on-brand text (the placeholder,
  expand icon, adornments and chips all ride that on-brand color rather than the quiet-text
  tokens). Every value keeps the same box, border width and radius, and each restates its own
  `:hover` feedback. `lr-input` and `lr-textarea` use the same mapped `outlined` default.
- `pill: boolean = false` (reflected) — fully-rounded trigger corners. It changes the private
  radius default to `--lr-radius-pill`, so an inherited or direct `--lr-select-radius` remains
  authoritative
- `placement: Placement = 'bottom'` (reflected) — preferred listbox placement, from the
  Floating UI vocabulary (`'top'`, `'bottom-end'`, …). `flip`/`shift` may still move the popup to
  keep it in view, and the `left`/`right` component is swapped under RTL. Assignment while open
  refreshes positioning in place without closing, firing lifecycle events, or changing stack order
- `hoist: boolean = false` (reflected) — switches Floating UI from its mapped absolute strategy to
  fixed positioning, escaping clipping containers. It also switches live while open; an effective
  direction change refreshes logical left/right placement by the same path
- `positioningStrategy: PlaceStrategy = 'absolute'` (attribute `positioning-strategy`, reflected) —
  see `<lr-popover>` (`llms/components/lr-popover.md`). `hoist: boolean = false` is its retained
  exact alias; writing either spelling updates the other. This property always reports the
  instance's own authored value (or the mirrored `absolute` default); when neither spelling is
  authored, the listbox is actually placed with the cascading `--lr-positioning-strategy` custom
  property honored ahead of that default — see the listbox's own **Themeable custom properties**
  below
- `sync?: PlaceSync` (reflected) — copies the trigger's width, height, or both onto the listbox,
  spelled and typed the same as on `lr-popup`/`lr-popover`/`lr-dropdown`/`lr-combobox`
  (`'width' | 'height' | 'both'`). Unset (the default), the listbox sizes to its own content,
  clamped between `--lr-size-12rem` and `min(--lr-popover-viewport-clamp, --lr-size-28rem)`,
  exactly as before. `sync="width"` drops that content-based clamp so a full-width trigger with
  short option labels gets a listbox that aligns to its own edges instead of floating narrower in
  the middle. A synced listbox is capped on `--lr-positioner-available-inline-size` **alone** — the
  space the positioner actually measured beside the trigger, which still keeps an over-wide trigger
  from pushing it off-screen; `--lr-popover-viewport-clamp` does **not** apply to a synced listbox,
  and still does with `sync` unset. Assignment while open repositions in place without closing;
  unsetting it releases the inline width the positioner wrote
- `showUnknownOption: boolean = false` (attribute `show-unknown-option`, reflected) — appends every
  committed value that no `<lr-option>` claims to the end of the listbox as a synthetic, badged,
  keyboard-reachable, re-selectable row. Off by default
- `getUnknownLabel?: (value: string) => string` (attribute: false) — renders the label for a
  committed value that matches no option, everywhere it appears (trigger, `multiple` tag, synthetic
  row). `getTag` cannot serve this case: it is handed a matched option and there is none. A blank
  return falls back to the raw value. Not consulted while `loading` suppresses that same value —
  see below
- `loading: boolean = false` (reflected) — whether a committed value's real label may still be
  pending because its `<lr-option>` catalog hasn't arrived yet (e.g. an async fetch still in
  flight). While `true`, a committed value that currently matches no option renders the localized
  `loading` placeholder in the trigger label or the relevant `multiple` tag instead of the raw
  value, with no `notInCatalog`/`[part='unknown-value']` badge and no synthetic
  `showUnknownOption` listbox row — "not yet resolved" is a different state from "known to be
  missing". It covers an **empty** selection too: with nothing selected — a create form whose
  catalogue is still being fetched, or an edit form whose saved selection is legitimately empty —
  the trigger renders that same localized text in place of `placeholder`, from the same `loading`
  message key, so both halves of a pending state read the same words and one
  `registerLyraLocale()` translation reaches both. Nothing to re-localize in the consuming app.
  With `loading` false an empty selection renders `placeholder` exactly as before. The trigger's
  accessible name never changes for this: a host `aria-label` wins, then `label`, then
  `placeholder`, then the localized `select` fallback. A value already matching a live option is
  unaffected. Never mutates `value`/`selectedOptions` itself, and does not itself disable the
  trigger — pair it with `disabled` when the control should also be non-interactive while pending
- `filled: boolean = false` (reflected) — Shoelace alias for the filled trigger treatment
- `autofocus: boolean = false` / `title: string = ''` — forwarded to the internal trigger
- `multiple: boolean = false` (reflected) — several options selectable at once; see "Multi-select"
  above. Flipping it re-shapes `value` and the submitted form entry, so it is normally set once
  declaratively
- `maxOptionsVisible: number = 3` (attribute `max-options-visible`) — how many chips render in
  `multiple` mode before the rest collapse behind a localized "+N" chip. `0` removes the cap
  entirely. Sanitized to a finite, non-negative integer: a fractional value truncates, a negative
  one clamps to `0` (i.e. uncapped), and a non-finite one falls back to `3`
- `withClear: boolean = false` (attribute `with-clear`, reflected) — renders a clear button while
  anything is selected (and nothing at all while the selection is empty). It sits in the trigger's
  inline-end band as a **sibling** of the trigger rather than a child of it — same nesting reason as
  the chips — so pressing it clears the selection without opening the listbox
- `clearable: boolean = false` — Shoelace's spelling of `withClear`; either one renders the same
  button. Present so a mechanical `sl-select` → `lr-select` rename keeps the clear control
- `helpText: string = ''` (attribute `help-text`) — Shoelace alias for `hint`; `hint` wins if both
  are present. `withLabel`/`withHint` (`with-label`/`with-hint`) are SSR slot-presence hints
- `getTag?: LyraSelectTagRenderer` (attribute: false) — `(option: LyraOption, index: number) =>
unknown`, exported under that name from the component's own module, renders one
  selected option's chip in `multiple` mode. Whatever it returns replaces the whole built-in
  `[part="tag"]` element, so re-declare `part="tag"` on your own root node to keep the default
  styling hooks. A returned **string renders as text, never as markup** (it lands in an ordinary
  Lit child position). A custom tag replaces the built-in remove control too, so it owns any custom
  removal affordance. Overflow past `max-options-visible` still collapses into the built-in "+N" chip
- `autoCommitSingleOption: boolean = false` (attribute `auto-commit-single-option`) — opts in to the
  single-option auto-commit behavior described above
- `value: string | string[]` — a getter/setter: a plain `string` in single mode (empty when nothing
  is selected), a `string[]` in `multiple` mode
- `defaultValue: string | string[]` (attribute `default-value` accepts the single string form) —
  reset selection; changing it updates the live value only while the control is pristine. Assigning
  `undefined`/`null` to either clears the selection; every string, including `''`, is a candidate
  value resolved against the current `<lr-option>`s instead — an `<lr-option value="">` is a
  legitimate row and round-trips like any other value. A value matching no current option still
  commits — see "Unknown committed values" below
- `selectedOptions: LyraOption[]` — a writable, fresh snapshot of the live selected occurrences.
  Assigning live child options commits their exact occurrences through the same event-silent path
  as `value`; foreign/detached options are ignored, and single mode keeps only the first. Mutating
  an array returned by the getter never mutates the control
- `selectedData: readonly unknown[]` (read-only) — the opaque `data` payload of each committed
  value, index-aligned with `value`: `selectedData[i]` describes `value[i]` (or `value` itself in
  single mode), and stays that value's own slot — `undefined`, never shifted or dropped — when
  that value currently matches no live option (see "Unknown committed values" below). Always an
  array the same length as `value`, in both single and `multiple` mode. Reached by reference,
  never deep-cloned
- `customError: string | null` (attribute `custom-error`) — reflected consumer validation message

**Unknown committed values.** A committed value matching no current `<lr-option>` (a stale value
from a removed option, or a programmatic assignment with a typo) still commits — the raw string
stays fully reachable through `value`/`selectedOptions` — but renders a dashed/italic
`[part='unknown-value']` badge next to the trigger label, or on the relevant `multiple`-mode tag,
instead of an unexplained bare label, mirroring `<lr-model-select>`'s synthetic "not in catalog"
stale-value row — see `--lr-select-unknown-value-border-style`/`-color` below. Set `loading` while
that same value's own `<lr-option>` catalog simply hasn't arrived yet (unlike `<lr-combobox>`,
`<lr-select>` has no async `source` of its own, so this is consumer-driven rather than automatic):
a still-unmatched value then renders the localized `loading` placeholder instead of the raw value,
with no `unknown-value` badge and no synthetic `showUnknownOption` row, since it is not yet known
to be missing. Once the matching option mounts, the real label renders on the next render with no
`value`/`selectedOptions` re-assignment needed, whether or not `loading` is also flipped back to
`false`. The same flag covers the other half of that state: with **nothing** selected the trigger
renders the same localized `loading` text in place of `placeholder`, so a consumer never has to
hand-write a conditional placeholder bound to the same flag and re-localize, in its own catalogue,
the string this control already owns.

**Methods:** `focus(options?)`, `blur()`, and `click()` forward to the internal trigger button.
`show()` and `hide()` return `Promise<void>` and resolve after `lr-after-show`/`lr-after-hide` once
the matching transition settles. `getForm()` returns the browser-resolved form owner, including an
external owner selected by `form`.
`setCustomValidity(message)` carries a rejection no client-side constraint can express ("that option
is no longer available"): a non-empty message raises `customError`, becomes `validationMessage`, and
blocks submission; `''` clears it and restores the control's own computed validity, so a `required`
select with nothing chosen goes back to `valueMissing` rather than to valid. The message survives
every selection change and a `form.reset()` — like a native control, only another
`setCustomValidity('')` or `resetValidity()` clears it — and is used verbatim, never localized.
`resetValidity()` changes only that consumer error layer: it restores the current intrinsic
required/selection validity without changing the selection/default or clearing prior interaction
state.

**Events:** each real selection change emits, in order, a native `InputEvent` named `input`,
`lr-input`, a native `Event` named `change`, then `lr-change`. The native events carry no detail;
read `event.target.value`. Both
prefixed aliases carry `detail: { value: string | string[]; data: readonly unknown[] }` — `value`
is the new committed selection, a string in single mode and a `string[]` in `multiple` mode; `data`
is index-aligned with `value` exactly like `selectedData` above (the same reference, `undefined`
for a value matching no live option), reached by reference and never deep-cloned. The complete sequence is silent for a
programmatic `value` write, `form.reset()`, or session-state restoration. Plus
`lr-clear` (no detail; emitted by the `with-clear` button _after_ its
`input`/`lr-input`/`change`/`lr-change` run, and never when there was nothing to clear, so it never
announces a no-op),
`lr-show`, `lr-hide`, and bubbling, composed `focus`/`blur` events re-dispatched from the internal
trigger. `lr-show` is cancelable; `lr-hide` is cancelable while connected and
non-cancelable only for the disconnect-driven close, where a veto cannot be honoured. A direct or
fieldset-cascaded disablement is a policy closure rather than a user-requested transition: it
synchronously closes without the vetoable `lr-hide` or settled `lr-after-hide` lifecycle, and a
listener cannot hold a disabled popup open.
`lr-after-show` and `lr-after-hide` fire after the corresponding listbox transition has settled; an
interrupted transition drops its stale after-event.
`lr-invalid` (no detail, cancelable) fires when a validity check finds the control invalid.
`lr-activate` (`detail: { value: string }`, bubbling, composed, non-cancelable) fires on **every**
activation of an available listbox row — a click, or Enter/Space on the active row — whether or not
the selection actually moved. Its `value` is the activated option's own value, **always a single
string**, even in `multiple` mode, where `lr-input`/`lr-change` carry the whole `string[]` instead.
It reports that the user picked a row and gates nothing. Use it for the single-select repeat pick
that `change`/`lr-change` deliberately stay silent for (matching a native `<select>`) — "re-run that
filter" is a real intent — which is otherwise unobservable, because the rows live in this shadow
root, so a retargeted `click` names no option and a keyboard commit produces no click at all. When
an activation _does_ move the selection, `input`/`lr-input`/`change`/`lr-change` are emitted first,
so either listener reads the settled selection. It is not fired by a programmatic `value`
assignment, nor by the `with-clear` button.

**Slots:** default (`<lr-option>` children), `label`, `hint`, `help-text` (alias), `error` (overrides
the `errorText` attribute when provided), `start`/`prefix` (aliases before the selected-value label),
`end`/`suffix` (aliases after the label), plus `clear-icon` and `expand-icon`. Because the adornments
live inside the native trigger `<button>`, both wrappers are unconditionally inert,
`aria-hidden="true"`, and non-hit-testable. The names remain mirrored for decorative glyphs and
text, but links, buttons, inputs, and other supplied controls cannot become nested interaction or
accessibility stops.

In populated multiple mode, the trigger's `aria-describedby` first references the complete
visually-hidden selected-value node. When hint/error content is present it then references stable
shadow-local IDs for both messages (error before hint), so the current value and visible supporting
text are part of the focused control's accessible description.

**CSS parts:** `form-control`, `form-control-label`, `label`, `form-control-input`, `combobox`,
`trigger`, `display-input`, `start`, `prefix`, `end`, `suffix`, `tags` (the legal sibling
`multiple`-mode chip row), `tag`/`tag__base` (one selected-value chip), `tag-label`/`tag__content`,
`tag__remove-button`/`tag__remove-button__base`, and `tag-overflow` (the "+N" chip standing in for the selections past
`max-options-visible` — it carries **both** `tag` and `tag-overflow`, so `::part(tag)` styles every
chip while `::part(tag-overflow)` reaches only that one; state after `::part()` never matches, so it
is encoded in the part name instead), `unknown-value` (the dashed/italic badge shown next to the
trigger label, or on a `multiple`-mode tag, when the committed value matches no current
`<lr-option>`), `clear-button` (the `with-clear` button, present only while
there is a selection to clear), `listbox` (the managed nonmodal popup, layered by
`--lr-overlay-stack-index` with `--lr-layer-dropdown` as its standalone fallback),
`group-label` (a heading row emitted inside the listbox whenever an option's `group` differs from
the previous one's — its stable ID labels a `role="group"` wrapper that semantically owns the
following option rows; options with an empty `group` get no heading or group wrapper),
`option`, `option-dot` (the leading status dot, when a row's `dotColor` is set),
`option-start`/`option-end` (an option row's leading/trailing adornment, cloned from the source
`<lr-option>`'s `start`/`prefix`/`end`/`suffix` slot — inert and `aria-hidden`, exactly like
`lr-combobox`'s identical parts), `option-label`,
`option-sub` (a row's secondary line, when `sub` is set),
`option-badge` (the localized "not in catalog" badge on a synthetic unmatched-value row, rendered
only while `show-unknown-option` is set), `expand-icon`, `error`, and
`hint`/`form-control-help-text` (compatibility names on the same supporting-text node).

**TypeScript:** `LyraSelect<Multiple extends boolean = boolean>` — `value`/`defaultValue` and the
`lr-change`/`lr-input` detail `value` narrow to `string` when `Multiple` is `false` and `string[]`
(`readonly string[]` in a detail) when `true`. Types only; the runtime and the mirrored surface are
unchanged, and an untyped `<lr-select>` keeps `string | string[]`.

**The required marker.** `required` with a non-empty `label` paints the library's shared marker on
`[part="form-control-label"]` — the one `::after` rule described above, not a copy of it, so
`--lr-form-control-required-content`, `--lr-form-control-required-color` and
`--lr-form-control-required-offset` retune or suppress it here exactly as they do on `lr-input`.
With no label text the part is hidden and no glyph is painted.

**Themeable custom properties:** `--lr-select-trigger-padding`, `--lr-select-trigger-min-height`,
`--lr-select-font-size`, `--lr-select-expand-size` — all four have private defaults that follow
`size` (`xs`…`xl`), while inherited or direct public values remain authoritative; the same pattern
`lr-toast-item`'s `--lr-toast-padding`/`--lr-toast-font-size` use. `--lr-select-gap` (default
`--lr-space-xs`, the gap inside `[part='trigger']`) is retunable without a `::part(trigger)` rule
and does not vary by `size` — the adornment gap a field wants is looser than the icon-beside-label
gap the ladder is tuned for. `--lr-select-radius` (default `--lr-form-control-radius`, the corner
radius) is retunable the same way but _does_ follow the tier: the two tightest tiers take a smaller
radius, since a 6px corner on a 20px-tall control reads as a lozenge. `pill` changes its private
default to `--lr-radius-pill`. `--lr-select-tag-padding`
(default `var(--lr-space-2xs) var(--lr-space-xs)`) and `--lr-select-tag-font-size` (default
`var(--lr-font-size-sm)`) size a `multiple`-mode chip; like gap and radius their private defaults do
**not** vary by `size` tier, and inherited or direct public values win.
Mapped hooks `--tag-max-size` (default `var(--lr-size-12rem)`), `--show-duration`, and
`--hide-duration` cap one tag and independently retime the two popup directions.

The listbox is a floating surface and paints from the **shared overlay-surface family** (16.0.0):
`--lr-overlay-surface` (default `var(--lr-color-surface-overlay)`), `--lr-overlay-border` (default
`var(--lr-color-border)`), `--lr-overlay-radius` (default `var(--lr-radius)`) and
`--lr-overlay-shadow-anchored` (default `var(--lr-shadow-m)`). None is declared on `:host`, so one
declaration on `:root` — or on any ancestor, to scope it — retints this listbox together with every
other floating surface; the trigger it drops from is untouched and keeps the hooks below.

`--lr-positioning-strategy` (16.0.0) is the same cascading `absolute`/`fixed` override
`<lr-popover>` (`llms/components/lr-popover.md`) documents, read from computed style each time the
listbox is (re)positioned. An explicit `positioning-strategy`/`hoist` on the instance always wins
over it; otherwise it wins over this control's own mirrored `absolute` default. One declaration on
`:root`, a theme, or a single clipping ancestor (an `overflow: hidden` card or scroller) changes
every unset select beneath it instead of authoring `positioning-strategy`/`hoist` on each instance.

The trigger's own resting surface has hooks as of 16.0.0: `--lr-select-trigger-fill` (default
`var(--lr-color-surface)`) and `--lr-select-trigger-border-color` (default
`var(--lr-color-border)`). Both are read by **every** appearance, each falling back to that
appearance's own default (`var(--lr-color-surface-raised)` for `filled`/`filled-outlined`,
`transparent` for `plain`, `var(--lr-color-brand)` for `accent`), so one value retints the trigger
whichever treatment it is wearing. `--lr-select-trigger-hover-border-color` (default: the resting
`--lr-select-trigger-border-color`) moves the edge under the pointer; unset, the hovered border
stays exactly where the resting state left it, as it always has.

The shared field halo `--lr-form-control-focus-shadow` (default `none`) paints a `box-shadow`
while this control is focused — one name for every field-shaped control in the library, so a
halo is configured once instead of per component. It is additive: the focus outline and
border cue are the accessibility answer to focus and are never replaced by it.

The trigger's pointer/open states have component-scoped hooks too:
`--lr-select-trigger-hover-bg` (default `var(--lr-color-brand-quiet)` for the quiet appearances),
`--lr-select-trigger-active-bg` (default a deeper mix from the hover background), and
`--lr-select-open-border-color` (default `var(--lr-color-brand)`). Accent keeps its louder mixed
hover fallback when the hook is unset. These inline fallbacks let one select be rethemed without
changing the shared brand tokens used by other controls.

`--lr-select-trigger-min-height` is live at **every** tier, the default `m` included, where it is
`2.5rem` — byte-identical to `lr-input`'s and `lr-combobox`'s own `m` floor, so the three controls
agree at that tier. It used to be dead code: the component declared `--lr-select-trigger-height:
auto` on `:host`, and a _declared_ value (`auto` is one) wins over the `var()` fallback arm that
the floor lives in, so the floor never applied and four extra specificity rules existed only to
patch it back for four of the tiers. Those rules are gone.

`--lr-select-trigger-height` pins an **exact** trigger height — both a floor and a cap — e.g. to
pixel-match a sibling text field in the same toolbar row. It is **undeclared by default**, which is
exactly what keeps the per-tier floor alive; see "exact-height hatches" under `lr-input`. Because
the component never declares it, it can be set inline, from an ancestor, or from an outer-tree
rule. One consequence worth knowing when testing:
`getComputedStyle(el).getPropertyValue('--lr-select-trigger-height')` now reads `''` rather than
`'auto'` — assert the rendered `min-block-size`/`block-size` instead of the property string.

`--lr-select-option-active-bg` (default `var(--lr-color-brand-quiet)`) recolors the background of a
hovered or keyboard-active `[part='option']` row. Not declared on `:host`, so a value set on any
ancestor is never shadowed — retheme just this row state without hijacking the shared
`--lr-color-brand-quiet` token every other component's own hover/active state also reads. Same
knob `lr-combobox`'s own `--lr-combobox-option-active-bg` provides.

The currently-**selected** row (`[part='option'][aria-selected='true']`) has its own matching set:
`--lr-select-option-selected-bg` (default `transparent`), `--lr-select-option-selected-border` and
`--lr-select-option-selected-color` (both default `var(--lr-color-brand)`), and
`--lr-select-option-selected-font-weight` (default `var(--lr-font-weight-semibold)`). Like the
active-bg knob these are inline `var()` fallbacks, not declared on `:host`, so a consumer can
retheme the selected row without hijacking `--lr-color-brand` library-wide. Note the shadow-parts
spec forbids an attribute selector after `::part()` — `::part(option)[aria-selected='true']` is
invalid CSS and never matches — which is exactly why these tokens exist.

`--lr-select-unknown-value-border-style` (default `dashed`) and
`--lr-select-unknown-value-border-color` (default `var(--lr-color-border)`) retheme the
`[part='unknown-value']` badge described above under "Unknown committed values".
`--lr-select-option-badge-bg` (default `var(--lr-color-brand-quiet)`) retints the
`[part='option-badge']` "not in catalog" badge `show-unknown-option` renders on the synthetic
listbox row, independent of the unknown-value chip's border above.

**Optional peer deps:** none.

```html
<lr-select id="sel" label="Fruit" placeholder="Pick one…">
  <lr-option value="a">Apple</lr-option>
  <lr-option value="b" selected>Banana</lr-option>
</lr-select>
<script type="module">
  document
    .getElementById("sel")
    .addEventListener("change", (e) => console.log(e.target.value));
</script>
```

```html
<!-- Multi-select with chips, a cap, and a clear button: -->
<lr-select
  id="tags"
  label="Labels"
  multiple
  with-clear
  max-options-visible="2"
  appearance="filled"
  pill
>
  <lr-option value="bug">Bug</lr-option>
  <lr-option value="docs">Docs</lr-option>
  <lr-option value="perf">Performance</lr-option>
</lr-select>
<script type="module">
  import "@aceshooting/lyra-ui/components/forms/select/select.js";
  const sel = document.getElementById("tags");
  // A custom chip: return a node, and re-declare part="tag" to keep the built-in styling hooks.
  sel.getTag = (option, index) => `${index + 1}. ${option.label}`; // a string renders as text
  sel.addEventListener("change", (e) => console.log(e.currentTarget.value)); // string[] in multiple mode
  sel.addEventListener("lr-clear", () => console.log("selection emptied"));
</script>
```

**Known gotchas:**

- The trigger keeps real DOM focus throughout — the listbox's "active" row is conveyed via
  `aria-activedescendant`, never actual focus, matching the WAI-ARIA "select-only combobox" pattern
  (as opposed to `lr-combobox`'s editable-input pattern).
- While open, live option reorders preserve the active row by option identity. Removing or
  disabling/inerting that option rehomes activity to the nearest available survivor (preferring the
  following row on a tie); removing every available option clears `aria-activedescendant`.
- One availability rule governs keyboard navigation, type-ahead, single-option auto-commit,
  pointer selection, and each proxy row's `aria-disabled`: an option is unavailable when it is
  disabled, inert itself, or inside an inert ancestor. Pointer activation of such a row is a no-op.
- The floating listbox participates in Lyra's shared nonmodal overlay stack. Its computed
  `--lr-overlay-stack-index`, Escape owner, capture-phase outside-pointer dismissal, and focus
  handoff follow the newest open overlay rather than DOM order. A single dismissal therefore closes
  only the visual top layer, even when target code stops pointer bubbling.
- No typing-to-filter, but a printable keypress still jumps to (while open) or directly selects
  (while closed) the next available option whose label starts with what's been typed, matching a
  native `<select>`'s own type-ahead; the buffer resets ~500ms after the last keystroke. In closed
  `multiple` mode the bounded search skips already-selected option occurrences and continues to a
  later unselected match, including a distinct row that carries the same public string value.
- `<lr-option value="b" selected>` sets that option's `defaultSelected`, seeds the live selection,
  and supplies the `form.reset()` baseline, mirroring native `<select><option selected>`. Later
  `defaultSelected`/attribute changes update that reset baseline without clobbering a dirty live
  selection; user picks and direct `option.selected` writes remain live-only and never rewrite the
  attribute/default.
- `aria-required` on the trigger reflects `required` immediately; `aria-invalid` only reflects once
  the trigger has been blurred (touched) at least once, mirroring `lr-combobox`'s own input.
  Blurring the trigger (Tab away) closes an open listbox, the same as a native `<select>`'s popup,
  without restoring focus and undoing the browser's native Tab/Shift+Tab destination.
- The trigger's accessible name now checks a host-level `aria-label` attribute first, before falling
  back to `label`/`placeholder`/`"Select"` — a plain `aria-label` on `<lr-select>` is no longer
  silently ignored. Precedence is presence-based: `aria-label=""` remains an explicit empty
  override rather than restoring any fallback.
- With `autoCommitSingleOption` set, a select with exactly one available option never exposes
  `role="combobox"`/opens a listbox at all — see "Single-option auto-commit" above.
  Testing/automation code that always expects a `role="combobox"` trigger, or that opens the
  listbox before asserting on a row, either needs at least two available options or should leave
  `autoCommitSingleOption` unset to observe the normal dropdown chrome.

---

## `lr-date-picker` / `lr-date-input` (+ `calendar-core.ts`)

Mirrors the `<wa-date-picker>`/`<wa-date-input>` 3.11 public API under `lr-`. Both
components are **experimental since 3.8**. Values use ISO 8601: `YYYY-MM-DD` (single) or
`YYYY-MM-DD/YYYY-MM-DD` (range).

For `lr-date-input`, host `aria-describedby` targets resolve in the host's root and describe the
native combobox input through element references, before its existing error and hint descriptions.
Replacement, removal, reinsertion, newly resolved IDs, reconnect, and adoption update those
relationships. Removing `label`, `hint`, or `error-text` safely omits that copy while preserving
`null` property readback; later supplied values render normally.

`lr-date-input`'s `clearLabel`, `openLabel`, and `dialogLabel` retain their initial defaults (`''`,
`''`, and `'Choose date'`). Omitted labels localize; explicitly supplied text, built-in English
labels, and empty strings win over `.strings`. Attribute removal restores localization while
preserving `null` readback. The composed calendar applies the same range endpoint and
inclusive-length admission rules as the standalone picker.

An authored host `aria-label` names an enclosing calendar group. Individual month and selection
grids retain their distinct generated period names; changing or removing the purpose label updates
the group without changing a caller-authored host role. Removing the `value` attribute renders an
empty selection safely while preserving `null` readback; a subsequent valid value works normally.

Live constraints repair roving state without moving focus from an unrelated control. If a focused
cell becomes unavailable, focus recovers onto an enabled cell. Explicit distant bounds seed the
bounded automatic search within the permitted domain; a genuinely empty domain has no enabled roving
stop. Selected day and range-endpoint buttons retain their foreground/background pairing during
hover and press; author state-token overrides remain available. Month/year/decade state buttons
retain the common typography, padding, border reset, and minimum action size.

The `calendar-core.ts` helper `formatISO()` returns an empty string for invalid dates or years
outside `0000`–`9999`, so generated ISO anchors never advertise an unsupported signed or five-digit
year.

The ISO model is proleptic Gregorian in every locale and supports years `0000`–`9999`, including
`0000`–`0099` without JavaScript's `Date` 1900 remap. Navigation anchors remain within that domain;
moving past either boundary leaves a valid roving stop and does not change the selected value. Month/day names and visible day/week digits follow the effective locale while
formatters explicitly select the Gregorian calendar. `lr-date-input` uses locale `formatRange()`
for range presentation and normalizes locale digits plus bidi marks before parsing, so its own
Arabic/Persian display round-trips to the same ISO value.

### `lr-date-picker`

Inline month-grid calendar, not form-associated (used standalone or embedded inside
`lr-date-input`'s popover).

**Properties (28):**

- `dayContent` (JS only): `LyraDatePickerDayContent | undefined`
- `presets: LyraDateRangePreset[] = []` (JS only, new in 11.0.0) —
  `LyraDateRangePreset { label: string; start?: string; end?: string; id?: string }`, where
  `start`/`end` are ISO `YYYY-MM-DD` and `id` is an optional caller-owned
  correlation key, echoed verbatim on `appliedPreset` and never read by the picker itself.
  **Either bound may be omitted (new in 11.1.0)** to mean an OPEN bound, resolving to
  the picker's `min` / `max` respectively — that is how an "All time" preset is expressed. When the
  corresponding `min`/`max` is unset there is nothing to resolve to (a `value` of
  `YYYY-MM-DD/YYYY-MM-DD` has no unbounded spelling), so that preset's button renders **disabled**
  rather than looking live and doing nothing when pressed. Renders a `[part="presets"]` quick-range button row above the calendar, for the
  dashboard time-filter shape (Today / Last 7 days / Last 30 days / This month / All time).
  **Range mode only** — a preset names two dates, so it is ignored for a single-date picker rather
  than rendering a row that cannot do anything; unset renders nothing at all. Applying one commits
  through the same path a two-click selection uses, so the ISO serialization, the `min`/`max`
  clamping and the `input`-then-`change` pair are identical and a consumer's change handler cannot
  tell them apart. A reversed preset normalizes; a malformed one is ignored rather than clearing the
  current value, so a bad entry in a config-driven list never reads as "the user picked nothing".
  Non-array runtime assignments normalize to the empty collection, and null/non-object entries in
  an otherwise valid array are omitted from the rendered row rather than aborting the calendar. Empty and
  whitespace-only labels are also omitted, preserving named siblings. Explicit endpoints clamp to
  `min`/`max` before admission. Both endpoints must be selectable, and the inclusive length must
  satisfy `minRange`/`maxRange`; invalid outcomes render disabled and do not emit value events.
  Interior dates need not all be enabled. A same-day manual completion obeys those same inclusive
  length limits. Long preset labels wrap in narrow allocations, including unbroken text and RTL.
  The active button carries `aria-pressed="true"` and `data-active`. Deliberately the same
  `label`/`start`/`end`/`id` shape as `<lr-time-range>`'s `TimeRangePreset`, so the library has one
  preset vocabulary rather than two — the only difference is the unit (ISO dates, not numbers)
- `appliedPreset: LyraDateRangePreset | undefined` (read-only, new in 11.1.0) — the preset whose
  button produced the current `value`, or `undefined` when the range was picked by hand, cleared, or changed externally.
  `clear()` removes identity before synchronous `input`/`change` listeners run; an external value
  change removes identity silently. An accepted preset retains its exact caller-owned source
  identity through its own update. Read it
  inside your own `change`/`input` handler. It exists because a dashboard filter has to persist
  *which* preset is active rather than the pair it froze to: "Last 7 days" must still mean the last
  7 days after tomorrow's reload. That fact is not recoverable from `value` — re-deriving it by
  string-matching is the mapping table `presets` exists to delete, and it is ambiguous anyway
  (Today and This month coincide on the 1st of a month, and a hand-picked range can equal a
  preset's pair by construction). A property rather than an event detail because `input`/`change`
  here are **native** events, deliberately indistinguishable from a manual selection so existing
  handlers need no special case, and a native `Event` cannot carry a detail without changing type
- `disabled: boolean = false` (reflected)
- `disabledDates: string | string[] | Date[] = ''` (attribute `disabled-dates`)
- `disabledDaysOfWeek: string = ''` (attribute `disabled-days-of-week`)
- `disableFuture: boolean = false` and `disablePast: boolean = false` (reflected)
- `firstDayOfWeek: LyraDatePickerFirstDayOfWeek = 'auto'` (`'auto'|'sun'|'mon'|'tue'|'wed'|
'thu'|'fri'|'sat'`; attribute
  `first-day-of-week`, reflected)
- `focusedDate: string = ''` (attribute `focused-date`, reflected)
- `isDateDisabled?: (date: Date) => boolean` (JS only)
- `locale: string = ''` (reflected; malformed tags fall back to the platform locale)
- `max: string = ''` and `min: string = ''` (reflected ISO bounds)
- `maxRange: number = 0` and `minRange: number = 0` (attributes `max-range`/`min-range`, reflected;
  positive values count both range endpoints)
- `mode: 'single'|'range' = 'single'` (reflected; unknown values normalize to `single`)
- `months: 1|2 = 1` (reflected; finite values are truncated and clamped to `1..2`)
- `pageBy: 'months'|'single' = 'months'` (attribute `page-by`, reflected)
- `readonly: boolean = false` (reflected)
- `size: LyraSize = 'm'` (reflected; the shared `2xs`–`xl` ladder plus
  `small`/`medium`/`large` aliases)
- `today: string = ''` (reflected ISO override for deterministic today styling/constraints)
- `value: string = ''` (reflected)
- `valueAsDate: Date | null` and `valueAsRange: { from: Date|null; to: Date|null }` (JS-only
  accessors; setters are silent and normalize reversed ranges)
- `view: 'days'|'months'|'years'|'decades' = 'days'` (reflected)
- `weekdayFormat: 'narrow'|'short'|'long' = 'short'` (attribute `weekday-format`, reflected)
- `withOutsideDays: boolean = false` and `withWeekNumbers: boolean = false` (reflected)

Lyra retains the additive `previousLabel`/`nextLabel` accessible-label overrides and the `selection`
range getter. Their initial readback remains `'Previous month'` and `'Next month'`; omitted labels
localize, while explicit text, the built-in English labels, and empty strings win over locale and
`.strings` copy. Removing either label attribute restores localized omission while preserving
`null` property readback.

**Methods:** `clear()`, `focus(options?)`, `goToToday()`, and
`goToDate(date: string | Date)`. Valid navigation dates are clamped to `min`/`max`; invalid values
are ignored.

**Keyboard:** The day grid uses one roving Tab stop. Month, year, and decade selection views do the
same: Arrow keys move through their four-column visual grid (with horizontal movement mirrored in
RTL), Home/End move to the first/last enabled period in the current page, and Enter/Space drills
into the focused period. Moving beyond a selection-grid edge opens the adjacent period page;
disabled periods never receive the roving focus. A period is enabled only when it contains at least
one date selectable under the active bounds, past/future limits, disabled dates/weekdays, predicate,
and pending-range limits; activating an unavailable period is a no-op.

**Events:** all are non-cancelable. `input` is a bubbling/composed native `InputEvent` (including
the first endpoint of a range); `change` is a bubbling/composed native `Event` for committed
values. `lr-focus-day` carries `{ date: Date }`, and `lr-view-change` carries `{ view, date }`.

**Slots:** `header`, `previous-icon`, `next-icon`, and `footer`. A dynamic
`day-YYYY-MM-DD` slot is also accepted as a Lyra extension and takes precedence over `dayContent`.

**Custom states:** `disabled`, `range`, and `readonly`.

**CSS parts (37):** `date-picker` / permanent compatibility name `base` (tokens on the same
visible shell; both names remain supported), `day`, `day-disabled`, `day-label`, `day-outside`,
`day-placeholder`, `day-range-end`, `day-range-inner`, `day-range-preview`, `day-range-start`,
`day-selected`, `day-today`, `day-weekend`, `footer`, `grid`, `header`, `month`, `month-label`,
`months`, `nav`, `next`, `previous`, `title`, `view-cell`, `view-grid`, `view-item`,
`presets` (the quick-range row), `preset-button` (one quick-range button; carries `data-active`
while its range is the current value),
`view-item-disabled`, `view-item-selected`, `view-item-today`, `view-row`, `weekday`, `weekdays`,
`weeknumber`, and `weeknumbers`. Lyra additionally retains the existing `week` part.

**Themeable custom properties:** `--lr-cell-size` (default `2.25rem`, controls day-cell/grid-column
size; its private default follows the `size` tier — `2xs`/`xs`/`s`/`l`/`xl`; `m` keeps the
default). An inherited or direct public value remains authoritative in every tier.

**Optional peer deps:** none.

### `lr-date-input`

Text field + calendar popover, **form-associated** via the shared `FormAssociated` mixin (`name`,
`value`, `disabled`, `required` all inherited).

**Properties (44):**

- `appearance: 'filled'|'outlined'|'filled-outlined' = 'outlined'` (reflected)
- `appliedPreset: LyraDateRangePreset | undefined` (read-only, new in 12.0.0) — the `presets` entry
  whose button produced the current `value`, or `undefined` when the value was picked on the
  calendar, typed into the field, cleared, or reset. Read it inside your own `change`/`input`
  handler; it is updated before those events are relayed, so a handler observes the preset that
  caused the very commit it is handling, and it is `undefined` while the popover has never been
  opened. Mirrors the nested `lr-date-picker`'s identically-named property across this component's
  shadow boundary, which is where the readback is actually needed: the compact
  text-field-plus-popover shape is the one a dashboard filter uses, the nested picker instance is
  unreachable from outside (a CSS part cannot yield it), and the fact is not recoverable from
  `value` — re-deriving it by string-matching is the mapping table `presets` exists to delete and is
  ambiguous anyway. A property rather than an event detail because `input`/`change` here are
  **native** events that cannot carry one
- `assumeInteractionOn: string[] = ['input']` (JS only)
- `autocomplete: string = ''`
- `dayContent?: LyraDatePickerDayContent` (JS only)
- `defaultValue: string = ''` (reset value; reflected through the `value` content attribute)
- `disabled: boolean = false`
- `disabledDates: string | string[] | Date[] = ''` and `disabledDaysOfWeek: string = ''`
- `disableFuture: boolean = false` and `disablePast: boolean = false` (reflected)
- `distance: number = 0` (reflected; finite offset from the anchor)
- `firstDayOfWeek: LyraDateInputFirstDayOfWeek = 'auto'` (reflected)
- `form: HTMLFormElement | null` (JS-only FACE owner)
- `hint: string = ''`
- `isDateDisabled?: (date: Date) => boolean` (JS only)
- `label: string = ''`
- `max: string = ''` and `min: string = ''` (reflected ISO bounds)
- `maxRange: number = 0` and `minRange: number = 0` (reflected; positive values include both
  endpoints)
- `mode: 'single'|'range' = 'single'` (reflected)
- `months: 1|2 = 1` (reflected; finite values are truncated and clamped)
- `name: string = ''` (reflected)
- `open: boolean = false` (reflected)
- `pageBy: 'months'|'single' = 'months'` (reflected)
- `pill: boolean = false` (reflected)
- `placement: LyraDateInputPlacement = 'bottom-start'` (reflected; all 12 side/alignment
  placements are accepted)
- `presets: LyraDateRangePreset[] = []` (JS only, new in 11.1.0) — forwarded verbatim to the nested
  `lr-date-picker`, whose own `presets` documents the semantics (range mode only, open bounds
  resolving to `min`/`max`, unset renders nothing). Forwarded rather than reimplemented because the
  picker lives in this component's shadow root, so a consumer has no route to it. The row's parts
  are re-exported as `presets`/`preset-button`, and `appliedPreset` above reports which entry
  produced the current value
- `readonly: boolean = false` and `required: boolean = false` (reflected)
- `size: LyraSize = 'm'` (reflected; `2xs`–`xl` and aliases)
- `today: string = ''` (reflected ISO override)
- `validationTarget: HTMLElement | undefined` (JS only) — writable native-validity focus anchor.
  It defaults to the internal input after first render; assign another element to override it, or
  assign `undefined` to restore the internal input
- `validators: LyraDateInputValidator[] = []` (JS only) — each entry may be a
  `(value, input) => void | boolean | string | ValidityStateFlags` function, an object with
  `validate(value, input)` returning that same result vocabulary, or a Web Awesome-compatible
  object with `checkValidity(input)`. The mapped object returns
  `{ isValid, message, invalidKeys }`, where `invalidKeys` names `ValidityState` flags; it may also
  expose `observedAttributes` and a string or callback `message`. Changing any listed host
  attribute automatically runs validity again. `isValid: true` passes. Otherwise the listed flags
  are set (`customError` is used when the list is empty) and the returned message wins over the
  validator-level fallback.
- `value: string = ''` (JS property)
- `valueAsDate: Date | null` and `valueAsRange: { from: Date|null; to: Date|null }` (JS-only
  accessors; setters are silent and normalize reversed ranges)
- `weekdayFormat: 'narrow'|'short'|'long' = 'short'` (reflected)
- `withClear: boolean = false`, `withHint: boolean = false`, and `withLabel: boolean = false`
- `withOutsideDays: boolean = false` and `withWeekNumbers: boolean = false` (reflected)

Lyra retains additive native-wrapper and form-chrome properties: `placeholder`, `locale`,
`errorText`, `accessibleLabel` (attribute `aria-label`), `clearLabel`, `openLabel`, `dialogLabel`,
`spellcheck`, `autocapitalize`, `autoCorrect` (attribute `autocorrect`), `inputMode: string = ''`
(attribute `inputmode`), `enterKeyHint: string = ''` (attribute `enterkeyhint`), and the reflected
`customError: string | null` (attribute `custom-error`). `withLabel` and `withHint` are SSR hints:
they force those slot wrappers into the first render so server output and hydration have the same
structure even before assigned-slot state is observable. The shared Lyra FACE contract also
reflects `disabled` and accepts a `form` content-attribute owner ID in addition to the
element-valued `form` IDL.

**Methods:** `blur()`, `clear()`, `focus(options?)`,
`formStateRestoreCallback(state)`, `hide()`, `resetValidity()`, `setCustomValidity(message)`, and
`show()`. The shared form contract additionally exposes `getForm()`, `checkValidity()`, and
`reportValidity()`; Lyra's native wrapper also exposes `click()`. `show()` and `hide()` return promises that settle after their corresponding transition;
they do nothing when already settled, and respect cancellation of their request event. `clear()`
is a no-op while blank, disabled, or readonly; otherwise it emits `lr-clear`, then `input`, then
`change`. Lyra also retains native-wrapper `select()`, `setSelectionRange()`, and `setRangeText()`.
The text input is itself the popup-opening combobox owner: it exposes `role="combobox"`,
`aria-haspopup="dialog"`, and explicit `aria-controls`/`aria-expanded` alongside the expand button.
Host focus/click/show/clear calls are synchronous no-ops as soon as direct or fieldset disablement
starts, including before Lit has updated the inner native controls.

**Getters:** `input: HTMLInputElement | undefined` — the internal native `<input>`, for direct DOM
access.

**Selection properties:** `selectionStart`, `selectionEnd`, and `selectionDirection` mirror the
internal native date input.

**Events:** `input` is an `InputEvent`, `change` is an `Event`, and `focus`/`blur` are
`FocusEvent`s preserving `relatedTarget`; each is dispatched exactly once from the host and is
bubbling, composed, and non-cancelable. `lr-show`/`lr-hide` are cancelable requests emitted before state changes;
`lr-after-show`/`lr-after-hide` are non-cancelable and fire after rendering and popup animations
settle. `lr-clear` is non-cancelable. `lr-invalid` **is** cancelable: `preventDefault()` on it
suppresses the browser's native validation bubble and `reportValidity()`'s focus/scroll of this
control, without making the control valid — see "The validity alias is cancelable in 8.0.0" above.

**Slots (10):** `clear-icon`, dynamic `day-YYYY-MM-DD`, `end`, `expand-icon`, `footer`, `hint`,
`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.

**Custom states:** `blank`, `disabled`, `open`, and `range`; the shared form-associated mixin also
exposes its validity states.

**CSS parts (21):** `clear-button`, `date-input`, `date-picker`, `presets` and `preset-button`
(forwarded from the nested `lr-date-picker` via `exportparts`, so the quick-range row is styleable
from outside — new in 11.1.0), `end`, `expand-button`,
`expand-icon`, `form-control`, `form-control-input`, `form-control-label`, `hint`, `input`,
`input-wrapper`, `popup`, `range-separator`, `segment`, `segment-literal`, `start`, permanent
compatibility name `base` (a nested wrapper inside `date-input`), and permanent compatibility name
`label` (the inner label-content wrapper inside `form-control-label`). Lyra additionally retains
`error`.

**Form value and validation:** a complete range submits `YYYY-MM-DD/YYYY-MM-DD`. A first range
endpoint remains visible in `value` but contributes the empty string to `FormData` until the second
endpoint is selected. `min`/`max`, past/future limits, disabled dates/weekdays, the predicate,
range length, `required`, and configured validators all feed FACE validity. Reset and state restore
use the same normalization path as direct property writes.

**The required marker.** `required` with a non-empty `label` paints the library's shared marker on
`[part="form-control-label"]` — the one `::after` rule described above, not a copy of it, so
`--lr-form-control-required-content`, `--lr-form-control-required-color` and
`--lr-form-control-required-offset` retune or suppress it here exactly as they do on `lr-input`.
With no label text the part is hidden and no glyph is painted.

**Themeable custom properties:** `--lr-date-input-padding-block` (default
`--lr-form-control-padding-block`) pads the native text input; `--lr-date-input-padding-inline`
(default `--lr-form-control-padding-inline`) pads the row. `--lr-date-input-font-size` defaults to
`--lr-form-control-font-size`. The row floor `--lr-date-input-control-min-height` defaults to
`--lr-form-control-height`. All four defaults follow the shared size ladder, including
`small`/`medium`/`large` aliases and inherited `--lr-theme-form-control-height-*` overrides.
Inherited or direct public values win. `pill` changes the private radius default to
`--lr-radius-pill`; a public `--lr-date-input-radius` still wins.

Calendar and clear actions fit inside the selected row height while retaining at least 24×24
CSS-pixel targets. At the default root size, rows measure 30/40/48/56px for s/m/l/xl; 2xs and xs
grow to 26px to accommodate the 24px action plus the row borders. Custom content or font metrics
can grow an unconstrained row. A theme setting the small tier to 36px produces a 36px date row.
`--lr-date-input-control-height` remains undeclared by default and pins an exact row height when
set. If it forces a row below its target size, the action overflows instead of shrinking.

The mapped `--show-duration` and `--hide-duration` hooks independently retime the popup's enter
and exit transitions; both default to `var(--lr-transition-fast)`. Clear and calendar action
state hooks are `--lr-date-input-action-hover-color`, `--lr-date-input-action-hover-bg`, and
`--lr-date-input-action-hover-radius` (defaults: text, transparent, and the input radius), plus
`--lr-date-input-action-active-color`, `--lr-date-input-action-active-bg`, and
`--lr-date-input-action-active-radius` for the pressed state. They inherit from theme ancestors;
direct values on `lr-date-input` win without retuning library-wide tokens.

`--lr-positioning-strategy` (16.0.0) — the calendar popup reads this same cascading
`absolute`/`fixed` override documented on `<lr-popover>` when it is (re)positioned, falling back to
its own `fixed` default when nothing is set. There is no per-instance `positioning-strategy`
property on `<lr-date-input>`; set the custom property on `:root`, a theme, or one clipping
ancestor to change every unset date input beneath it.

**Optional peer deps:** none.

```html
<lr-date-input
  id="di"
  label="Start date"
  with-clear
  name="start"
></lr-date-input>
<script type="module">
  const di = document.getElementById("di");
  di.value = "2026-07-10";
  di.addEventListener("change", () => console.log(di.value)); // ISO string
</script>
```

`calendar-core.ts` exports the pure date math both components share (**internal — not re-exported
from the package root**, but worth knowing when reasoning about behavior): `parseISO`, `formatISO`,
`isSameDay`, `addMonths`, `addMonthsClampingDay(date, n)` (like `addMonths` but clamps the result to
the target month's last day instead of overflowing into the month after — e.g. Jan 31 + 1 month
lands on Feb 28/29, not Mar 3; backs `lr-date-picker`'s PageUp/PageDown), `clampDate`,
`monthMatrix(year, month, firstDayOfWeek)`, `weekdayLabels(firstDayOfWeek, format, locale)`,
`monthTitle(year, month, locale)`, `resolveFirstDayOfWeek(value, locale?)`,
`normalizeCalendarMode(value)`, `normalizeCalendarMonths(value)`, `normalizeWeekdayFormat(value)`,
and `dateTimeFormat(locale, options)`.

**Known gotchas:**

- `first-day-of-week="auto"` now derives from `locale` when the runtime's `Intl.Locale` exposes
  week-info (`weekInfo`/`getWeekInfo()`, still shifting between engines) — `resolveFirstDayOfWeek()`
  only hardcodes Sunday as the fallback when that isn't available or `locale` is unset. A
  French/German-locale user with a supporting runtime now gets the Monday-first grid their OS would
  show; on an older runtime it still falls back to Sunday-first silently. **If you need a guaranteed
  locale-correct week start regardless of runtime**, pass an explicit
  `first-day-of-week="mon"` (accepted values: `sun`/`mon`/`tue`/`wed`/`thu`/`fri`/`sat`).
- Runtime attribute/property inputs are normalized before calendar math or `Intl` formatting:
  unsupported modes and weekday formats use their documented defaults, month counts cannot exceed
  the two-grid API, malformed locale tags use the platform locale, and invalid `Date` objects do
  not replace the current view.
- (date-input only) — opening the calendar does not move focus into it: `Alt+ArrowDown` leaves focus
  on the text input, and the expand button keeps focus when clicked. The focused opener is
  remembered. Escape and a finalized calendar selection close the popup and return focus to that
  same connected element; a direct `.open = false` also restores it when focus would otherwise
  remain inside the now-hidden popup. Outside-pointer dismissal deliberately leaves focus at the
  clicked target.
- (date-input only) — typing an unparseable string and blurring/committing sets `badInput` via
  `internals.setValidity()` and reverts the displayed text to the last valid commit. The visible
  `<input part="input">` mirrors `required` through native `required`/`aria-required` and exposes
  touched outer validity through `aria-invalid`; this includes required, bad-input, and range
  failures owned by the form-associated host. A host `aria-label` is reactively forwarded to the
  input, including later changes/removal, and takes precedence over the component's
  label/placeholder fallback. Native validation attempts reveal `aria-invalid`; `form.reset()`
  clears that touched presentation. A parseable typed date outside an active bound is committed
  instead and reports the precise `rangeUnderflow`/`rangeOverflow` state.
- (date-input only) — declarative, IDL, reset, and restored values are sanitized to exact ISO dates:
  calendar-invalid or malformed strings become `''` (and therefore `valueMissing` when required),
  while valid dates outside `min`/`max` or `disable-past`/`disable-future` remain submitted and expose
  `rangeUnderflow`/`rangeOverflow`. Changes to these constraints, `mode`, and `readonly` recompute
  validity synchronously; range mode validates both endpoints.
- The grid keyboard pattern (Arrow/PageUp/PageDown/Home/End navigation with correct focus
  sequencing) is implemented correctly and safe to rely on, as is the selected/range-day text color
  (`--lr-date-picker-selected-color`, defaulting to `--lr-color-on-brand`, not a hardcoded literal).
  Override selected background and foreground together to preserve contrast.

**Additional API surface:**

- `--lr-date-picker-month-gap` — Gap between visible months. Default: `var(--lr-space-l)`.
- `--lr-date-picker-header-gap` — Month-header child gap. Default: `var(--lr-space-s)`.
- `--lr-date-picker-radius` — Calendar and control corner radius. Default: `var(--lr-radius)`.
- `--lr-date-picker-nav-hover-bg` — Hover background of the previous/next month-navigation buttons.
  Default: `var(--lr-color-brand-quiet)`. An inline `var()` fallback rather than a `:host`
  declaration, and the rule wraps its selector in `:where()` so a consumer's own
  `::part(previous):hover` still wins without `!important`.
- `--lr-date-picker-nav-active-bg` — Pressed navigation background; defaults to the hover color
  mixed by `--lr-color-mix-active`.
- `--lr-date-picker-preset-hover-bg`, `--lr-date-picker-preset-active-bg`, and
  `--lr-date-picker-preset-selected-bg` (new in 11.0.0) — hover, pressed, and
  currently-selected paint for a `presets` quick-range button. Defaults are
  `var(--lr-color-brand-quiet)`, that hover colour mixed by `--lr-color-mix-active`, and
  `var(--lr-color-brand)` respectively.
- `--lr-date-picker-preset-selected-border` (default `var(--lr-color-brand)`) and
  `--lr-date-picker-preset-selected-color` (default `var(--lr-color-on-brand)`) independently
  theme a selected preset's border and foreground; the selected background token controls only its
  background.
- `--lr-date-picker-title-hover-color`, `--lr-date-picker-title-active-color`,
  `--lr-date-picker-title-active-bg`, and `--lr-date-picker-title-active-radius` — Month-title
  hover/press paint and pressed shape; defaults to brand, brand, brand-quiet, and
  `var(--lr-date-picker-radius)` respectively.
- `--lr-date-picker-day-hover-bg` and `--lr-date-picker-day-active-bg` — Day hover/press
  backgrounds; the pressed default mixes the hover hook by `--lr-color-mix-active`.
- `--lr-date-picker-day-outside-color`, `--lr-date-picker-today-outline`,
  `--lr-date-picker-disabled-color`, and `--lr-date-picker-disabled-opacity` — adjacent-month,
  today, and disabled-day paint; defaults preserve the quiet-text, brand, and shared disabled
  tokens.
- `--lr-date-picker-range-bg`, `--lr-date-picker-range-preview-bg`, and
  `--lr-date-picker-range-color` — range-interior, pending-preview, and adjacent-month range text
  paint. The preview defaults to the range background hook.
- `--lr-date-picker-selected-bg` and `--lr-date-picker-selected-color` — selected day and range
  endpoint paint; defaults to brand/on-brand.
- `--lr-date-picker-view-hover-bg`, `--lr-date-picker-view-active-bg`,
  `--lr-date-picker-view-selected-bg`, `--lr-date-picker-view-selected-color`,
  `--lr-date-picker-view-today-outline`, and `--lr-date-picker-view-disabled-opacity` — the
  corresponding month/year/decade selection-view states, independently themeable from day cells.
- `--lr-date-input-placeholder-color` — Placeholder text color. Default: `var(--lr-color-text-quiet)`.
- `--lr-date-input-gap` — Gap between input-row children. Default: `var(--lr-space-xs)`.
- `--lr-date-input-radius` — Input-row corner radius. Default: `var(--lr-radius)`.
- `--lr-date-input-focus-border-color` — Focused row border color. Default: `var(--lr-color-brand)`.
- `--lr-date-input-fill` — Resting input-row background, public since 16.0.0 (the radius beside it
  always was). Default: `var(--lr-color-surface)`, or `var(--lr-color-surface-raised)` under the
  `filled`/`filled-outlined` treatments; a value set here wins over every treatment.
- `--lr-date-input-border-color` — Resting input-row border color. Default:
  `var(--lr-color-border)`, or `transparent` under `filled`.
- `--lr-form-control-focus-shadow` — The shared field halo, painted as a `box-shadow` while the row
  holds focus. Default: `none`. Additive — the focused brand border is never replaced by it.

---

## `lr-textarea`

A multiline plain-text input primitive, form-associated (participates in native `<form>`
submission/validation/reset via `name`/`value`/`disabled`/`required`/`checkValidity()`/
`reportValidity()`). Ships an opt-in `label`/`hint`/`errorText` form-control chrome mirroring
`lr-select` -- left unset, none of it renders.

Removing `label`, `hint`, `help-text`, or `error-text` safely omits the corresponding content while
preserving native `null` property readback. Explicit empty strings stay empty; later supplied text
renders normally.

Changing own `disabled` from true to false in the same task that disables an ancestor fieldset keeps
the native editing control effectively disabled. The enabled first-legend exception and explicit
own-disabled state retain their native meaning; validity and form submission follow the effective
disabled state.

```html
<lr-textarea placeholder="Notes" rows="4"></lr-textarea>
<lr-textarea
  label="Bio"
  maxlength="280"
  with-count
  appearance="outlined"
  size="s"
  resize="auto"
></lr-textarea>
<script type="module">
  import "@aceshooting/lyra-ui/components/forms/textarea/textarea.js";
  const bio = document.querySelector('lr-textarea[label="Bio"]');
  await bio.updateComplete; // both calls are no-ops before the first render
  bio.scrollPosition({ top: 0 }); // pin a restored draft back to the top
  console.log(bio.scrollPosition()); // -> { top: 0, left: 0 }
</script>
```

### Properties

| Property                 | Attribute                  | Type                                                                 | Default      | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| ------------------------ | -------------------------- | -------------------------------------------------------------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `value`                  | `value`                    | `string`                                                             | `''`         | The current text value.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `defaultValue`           | `value` / `default-value`  | `string`                                                             | `''`         | Reset value. The Shoelace attribute alias and the native-style `value` content attribute share the same reset engine.                                                                                                                                                                                                                                                                                                                                                                                             |
| `rows`                   | `rows`                     | `number`                                                             | `4`          | Visible text rows (mapped default).                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `resize`                 | `resize`                   | `'none' \| 'vertical' \| 'horizontal' \| 'both' \| 'auto'`           | `'vertical'` | Native CSS `resize` behavior, plus `'auto'` (`ResizeObserver`-driven grow-to-content, no manual handle). An invalid runtime value falls back to `'vertical'`; `'auto'` maps native CSS resize to `none`.                                                                                                                                                                                                                                                                                                          |
| `size`                   | `size`                     | `LyraSize`                                                           | `'m'`        | Visual size on the shared control ladder — the same scale as `lr-input`/`lr-select`/`lr-button`, and both spellings of every tier are accepted (`2xs`/`xs`/`s`/`m`/`l`/`xl` and `small`/`medium`/`large`). Governs the field's padding, font size and corner radius. Reflected.                                                                                                                                                                                                                                   |
| `appearance`             | `appearance`               | `'accent' \| 'filled' \| 'outlined' \| 'filled-outlined' \| 'plain'` | `'outlined'` | Visual treatment of the field. The mapped default draws a border without a fill; the other values share `lr-input`'s vocabulary. Reflected.                                                                                                                                                                                                                                                                                                                                                                       |
| `filled`                 | `filled`                   | `boolean`                                                            | `false`      | Shoelace alias for the filled treatment.                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `pill`                   | `pill`                     | `boolean`                                                            | `false`      | Fully rounded field corners, matching `lr-input`'s/`lr-select`'s own `pill` — both upstreams ship it on their textarea, so a mechanical tag rename must not drop it. It changes the private radius default to `--lr-radius-pill`, so an inherited or direct `--lr-textarea-radius` stays authoritative. Most useful on a one- or two-row field: a tall multi-line surface with fully rounded ends wastes its first and last line's inline space, which is why it is opt-in rather than tied to `size`. Reflected. |
| `withCount`              | `with-count`               | `boolean`                                                            | `false`      | Renders a character count below the field, inside `[part="footer"]`. With `maxlength` set it counts _down_ the remaining characters instead of up from zero. Reflected.                                                                                                                                                                                                                                                                                                                                           |
| `placeholder`            | `placeholder`              | `string`                                                             | `''`         | Placeholder text.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `readonly`               | `readonly`                 | `boolean`                                                            | `false`      | Native read-only behavior: prevents user edits while preserving focus, selection/copy, form submission, and silent programmatic editing methods. Reflected.                                                                                                                                                                                                                                                                                                                                                       |
| `label`                  | `label`                    | `string`                                                             | `''`         | Visible label text. Unset: no label chrome renders.                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `hint`                   | `hint`                     | `string`                                                             | `''`         | Hint text below the field.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `helpText`               | `help-text`                | `string`                                                             | `''`         | Shoelace alias for `hint`; `hint` wins when both are set.                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `withLabel` / `withHint` | `with-label` / `with-hint` | `boolean`                                                            | `false`      | SSR slot-presence hints; neither is required for hydrated client-side slot detection.                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `errorText`              | `error-text`               | `string`                                                             | `''`         | Error text below the field (overridden by slotted `error` content).                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `customError`            | `custom-error`             | `string \| null`                                                     | `null`       | Reflected consumer-supplied validation message. A non-empty value blocks submission until `setCustomValidity('')` clears it.                                                                                                                                                                                                                                                                                                                                                                                      |
| `accessibleLabel`        | `aria-label`               | `string \| null`                                                     | `null`       | Accessible-name override forwarded to the internal `<textarea>`; every non-`null` value wins by presence—including an explicit empty string—over `label`, `placeholder`, and the localized default.                                                                                                                                                                                                                                                                                                               |
| `spellcheck`             | `spellcheck`               | `boolean`                                                            | `true`       | Forwarded to the native `<textarea>`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `autofocus`              | `autofocus`                | `boolean`                                                            | `false`      | Forwarded to the native `<textarea>`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `title`                  | `title`                    | `string`                                                             | `''`         | Forwarded to the native `<textarea>`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `autocapitalize`         | `autocapitalize`           | `string`                                                             | `''`         | Forwarded to the native `<textarea>`; empty omits the attribute.                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `autocorrect`            | `autocorrect`              | read: `boolean`; write: `boolean \| string`                          | `true`       | Forwarded to the native `<textarea>` (Safari/WebKit-specific). Reads are always boolean. Boolean writes preserve Web Awesome's IDL; Shoelace-compatible string writes normalize `off`/`false` to `false` and every other string to `true`. The HTML attribute uses canonical `on`/`off`. When the host attribute is absent and the state remains at its `true` default, the internal attribute is omitted so the browser keeps its default behavior.                                                              |
| `wrap`                   | `wrap`                     | `'hard' \| 'soft' \| 'off'`                                          | `'soft'`     | Native line-wrapping/submission behavior.                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `autocomplete`           | `autocomplete`             | `string`                                                             | `''`         | Forwarded to the native `<textarea>`; empty omits the attribute.                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `inputMode`              | `inputmode`                | `string`                                                             | `''`         | Virtual-keyboard input hint forwarded to the native `<textarea>`.                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `enterKeyHint`           | `enterkeyhint`             | `string`                                                             | `''`         | Virtual-keyboard Enter-key hint forwarded to the native `<textarea>`.                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `minlength`              | `minlength`                | `number \| undefined`                                                | `undefined`  | Minimum text length; forwarded to the native `<textarea>` and reported as `validity.tooShort`.                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `maxlength`              | `maxlength`                | `number \| undefined`                                                | `undefined`  | Maximum text length; forwarded to the native `<textarea>` (which also stops typing past it) and reported as `validity.tooLong`.                                                                                                                                                                                                                                                                                                                                                                                   |
| `debounce`               | `debounce`                 | `number \| undefined`                                                | `undefined`  | How long (ms) to wait after the last keystroke before emitting one `lr-input-settled`, while `input`/`lr-input` keep firing per keystroke as before. Omitted, `0`, or non-finite means no debounce: `lr-input-settled` never fires. A pending debounce is flushed immediately by `change`/Enter/blur and cancelled with no stray settle by disconnection and by a programmatic `value` write that changes the value. A write of the value already held leaves it pending, so a framework binding that writes the just-typed value back on each render (the controlled-input pattern) still settles. Shares its `DebounceController` primitive with `lr-filter-bar`'s own per-filter `debounce` and with `lr-input`'s identical property. |
| `name`                   | `name`                     | `string`                                                             | `''`         | Form field name.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `disabled`               | `disabled`                 | `boolean`                                                            | `false`      | Disables the control.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `required`               | `required`                 | `boolean`                                                            | `false`      | Participates in native constraint validation.                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |

The lowercase native IDLs `inputmode: string` and `enterkeyhint: string` delegate to
`inputMode`/`enterKeyHint`; `autocorrect` is one public state with a boolean read type and a wider
cross-upstream write vocabulary.

**8.0 migration:** the former camel-case string property `autoCorrect` is not retained as a public
alias. Prefer boolean `autocorrect` writes in new code. A migrated Shoelace string write remains
valid (`'off'` and `'false'` read back as `false`; other strings read back as `true`), while markup
uses `autocorrect="on"` / `autocorrect="off"`.

### Constraint validation

`validity` reports `valueMissing` (from `required`), `tooShort` (from `minlength`), and `tooLong`
(from `maxlength`) — the complete set a native `<textarea>` can produce. Leaving `minlength` and
`maxlength` unset constrains nothing, exactly as before they existed.

While `readonly`, all three constraint flags are suspended and `checkValidity()` succeeds, matching
native textarea behavior. The value remains a successful form value and is restored by form reset;
unsetting `readonly` restores the applicable required and length constraints.

Two behaviors are worth knowing, both inherited from the platform and both shared with `lr-input`:

- **An empty value is never `tooShort`.** Native `minlength` only applies to a non-empty value, so
  an optional field left blank stays valid; `required` is what rejects empty.
- **A script-assigned value is validated too.** The native `tooShort`/`tooLong` flags are raised
  only for a value the _user_ edited, so the component recomputes both from its own `value` and
  ORs them in — `el.value = <over-length>` reports `tooLong` rather than silently submitting.
  Lengths count UTF-16 code units, matching the native control (one emoji counts as two).
  `validationMessage` is the browser's own localized message when the native control flagged the
  value, and the localized `valueInvalid` string when only the script-value check did.

The visible label, hint, and error live in the same shadow tree as the native control, so their
generated ids safely drive the native `<label>`/`aria-describedby` relationships. Name precedence
is `accessibleLabel`/host `aria-label`, visible `label`, `placeholder`, then the localized
`textareaLabel` message. External `aria-labelledby`/`aria-describedby` idrefs are not copied across
the shadow boundary.

### Getters and selection properties

- `input: HTMLTextAreaElement | null` — the internal native control.
- `selectionStart: number | null`, `selectionEnd: number | null`, and
  `selectionDirection: 'forward'|'backward'|'none'|null` — readable and writable passthroughs to
  the native selection state.
- The shared form-associated getters `form`, `getForm()`, `labels`, `validity`, `validationMessage`,
  `willValidate`, and `effectiveDisabled` are also available.

### Methods

| Method                                                 | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `focus(options?)` / `blur()`                           | Focus or blur the internal native control.                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `select()`                                             | Select all text.                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `setSelectionRange(start, end, direction?)`            | Set the native selection range and optional direction.                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `setRangeText(replacement, start?, end?, selectMode?)` | Apply a native range edit, then synchronize the component `value`, form value, validity, and auto-grown size without emitting a user event.                                                                                                                                                                                                                                                                                                                                           |
| `scrollPosition(position?)`                            | Read or write the internal textarea's scroll offsets. Called with no argument it returns the current `{ top, left }`; called with a partial `{ top?, left? }` it writes only the axes present and returns `undefined`. Returns `undefined` either way before the internal textarea has rendered, and a non-finite offset leaves that axis alone. This is the one piece of scroll state no other public member reaches — use it to restore a draft, or to pin a long value to its end. |
| `setFormValue(value)`                                  | Set the reactive and submitted value synchronously.                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `setCustomValidity(message)`                           | Set a consumer-supplied validation message. A non-empty message raises `customError`, becomes `validationMessage`, and blocks submission; `''` clears it and restores intrinsic required/length validity.                                                                                                                                                                                                                                                                             |
| `resetValidity()`                                      | Clear only consumer-supplied custom validity and recompute current intrinsic constraints. It does not change `value`/`defaultValue`, clear prior interaction state, or force an intrinsically invalid field valid.                                                                                                                                                                                                                                                                    |
| `checkValidity()` / `reportValidity()`                 | Run native constraint validation through `ElementInternals`.                                                                                                                                                                                                                                                                                                                                                                                                                          |

### Events

| Event        | Detail              | Description                                                                                                                                                               |
| ------------ | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `input`      | none                | Native-style composed event fired on every user-driven edit.                                                                                                              |
| `change`     | none                | Native-style composed event fired at native `change` timing.                                                                                                              |
| `lr-input`   | `{ value: string }` | Compatibility alias fired on every user-driven edit.                                                                                                                      |
| `lr-change`  | `{ value: string }` | Compatibility alias fired on native `change` timing (blur after a committed edit).                                                                                        |
| `lr-input-settled` | `{ value: string }` | Fires once, `debounce` ms after the last keystroke, alongside the per-keystroke `input`/`lr-input` pair. **Non-cancelable.** See `debounce` above for the flush and cancellation rules. Never fires while `debounce` is unset, `0`, or non-finite. |
| `blur`       | none                | Re-dispatched from the internal native `<textarea>`'s own `blur` -- bubbling and composed, unlike the native event.                                                       |
| `focus`      | none                | Re-dispatched from the internal native `<textarea>`'s own `focus`, for the same reason as `blur`.                                                                         |
| `lr-invalid` | none                | Fired when a validity check finds the control invalid. **Cancelable** — `preventDefault()` suppresses the native validation bubble and `reportValidity()`'s focus/scroll. |

Programmatic property assignments, selection changes, `setRangeText()`, form reset, and form-state
restoration are silent. User edits update `value`, submitted form data, and required validity before
the corresponding `lr-input`/`lr-change` event is dispatched. `form.reset()` restores the
original declarative `value`, matching native `defaultValue` behavior.

### Slots

| Slot        | Description                |
| ----------- | -------------------------- |
| `label`     | Custom label content.      |
| `hint`      | Custom hint content.       |
| `help-text` | Shoelace alias for `hint`. |
| `error`     | Custom error content.      |

### CSS Parts

| Part                                                                     | Description                                                                                                                                                                                                                                  |
| ------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `form-control`                                                           | The outer wrapper around label, textarea, error and hint.                                                                                                                                                                                    |
| `form-control-label`                                                     | The `<label>` element.                                                                                                                                                                                                                       |
| `label`                                                                  | The visible label-content wrapper.                                                                                                                                                                                                           |
| `base` / `form-control-input` / `textarea-adjuster` / `textarea-wrapper` | Compatibility names on the plain block wrapper around the native `<textarea>`. It deliberately imposes no size of its own — the native resize grip writes inline `width`/`height` onto the `<textarea>` itself, so the field drives the box. |
| `textarea`                                                               | The native `<textarea>` element.                                                                                                                                                                                                             |
| `footer`                                                                 | The row below the field carrying the character count. Always in the DOM but `hidden` without `with-count`.                                                                                                                                   |
| `count`                                                                  | The character count text, rendered only with `with-count`.                                                                                                                                                                                   |
| `hint` / `form-control-help-text`                                        | Compatibility names on the hint message.                                                                                                                                                                                                     |
| `error`                                                                  | The error message.                                                                                                                                                                                                                           |

The visible `[part="count"]` is `aria-hidden`; the internal shadow `.count-announcement` node is
also an `aria-hidden` mirror (it is not a public CSS part), while the debounced spoken update is
appended to the shared light-DOM
`[data-lr-live-region="polite"]` sink about a second after the user stops typing. A screen reader is
therefore not told the count on every keystroke, and the announcement remains reliable across the
shadow boundary. The sink stays silent while the textarea or a composed ancestor is hidden, inert,
`aria-hidden`, or hidden by rendered CSS. Lengths count UTF-16 code units (one emoji counts as two),
matching the native `maxlength` the count reports against, and the remaining count floors at zero — only a
script-assigned value can exceed `maxlength`, and the `tooLong` validity flag already reports that
state better than a negative number would. An unparseable `maxlength` (`maxlength="oops"`) is
dropped rather than rendered as `NaN`, and the count counts up from zero instead.

`required` with a non-empty `label` paints the library's shared marker on `form-control-label` —
the one `::after` rule described under "The required-field marker" above, not a copy of it, so
`--lr-form-control-required-content`, `--lr-form-control-required-color` and
`--lr-form-control-required-offset` retune or suppress it here exactly as they do on `lr-input`.
With no label text the part is hidden and no glyph is painted.

### Themeable custom properties

- `--lr-textarea-max-block-size` (default `none`) — bounds `resize="auto"`; content beyond the
  bound scrolls inside the native textarea. Auto-resize remeasures after user edits, programmatic
  `value`/`rows` changes, range edits, and container-width changes.
- `--lr-textarea-padding` (default `var(--lr-form-control-padding-inline)`),
  `--lr-textarea-font-size` (default `var(--lr-form-control-font-size)`) and
  `--lr-textarea-radius` (default `var(--lr-form-control-radius)`) — the native textarea's padding,
  font size and corner radius. All three read the active `size` tier of the shared control ladder,
  so their private defaults follow the tier; the two tightest tiers take a smaller radius. Public
  values inherited from an ancestor or set directly on the host win in every tier. `pill` changes
  the private `--lr-textarea-radius` default to `--lr-radius-pill`.
- `--lr-textarea-fill` (default `transparent`) and `--lr-textarea-border-color` (default
  `var(--lr-color-border)`) — the field's background and border color, whose private defaults
  change per `appearance` rather than per `size`. The documented defaults are
  `appearance="outlined"`'s private values. Set either on an ancestor or directly on the host to
  retune the surface without a `::part(textarea)` rule; the public value remains authoritative
  across appearances.
- `--lr-textarea-hover-border-color` (default `var(--lr-color-brand)`) — the field border while the
  native textarea is hovered, independent of its resting border and every other brand-colored
  component state.
- `--lr-textarea-focus-border-color` (default `var(--lr-textarea-border-color)`) — the field
  border while the native textarea is focused. Unset, it resolves to this field's own resting
  border color, so a textarea with no override renders exactly as before this hook existed; set it
  to give focus its own border color independent of the hover color above and the halo below.
- `--lr-form-control-focus-shadow` (default `none`) — the shared field halo, painted as a
  `box-shadow` while the field holds focus. One name for every field-shaped control in the library,
  so a halo is configured once instead of per component; additive, so the `:focus-visible` outline
  is untouched.

`<lr-textarea>` now fills a definite-height host: place it inside a container with a resolved
block size (a flex/grid item stretched to a track, or an ancestor with an explicit height) and
the field's `form-control` → `textarea-wrapper` → the native `<textarea>` chain fills it instead
of staying at its `rows`-derived intrinsic height. This has no effect and needs no opt-in for the
ordinary case (an unsized host) — `resize="auto"`'s own growth and its
`--lr-textarea-max-block-size` cap are unaffected either way.

**Additional API surface:**

- `click()` — Activates the internal textarea.

---

## `lr-button`

A generic action-button primitive. Renders an internal native `<button>`; `type="submit"`/
`type="reset"` are handled by the component itself via its browser-resolved form owner (including
an external owner named by `form`), since a shadow-internal native button doesn't participate in a
light-DOM form's submission on its own. They remain default actions of the composed native
`click`: `preventDefault()` from any listener on that click path vetoes submit/reset before it
runs, while `stopPropagation()` alone does not. Canceling the form's later `submit` or `reset`
event remains an independent veto point.

External descriptions follow the current source element identity when an element with the same ID
replaces it, when a source is removed or reinserted, and when the control reconnects or moves to
another document. Host-root lookup and ordering follow the current `aria-describedby` list,
including unresolved IDs and duplicates. Switching between native button and anchor modes keeps the
relationship on the current action. Existing accessible names and `aria-controls` relationships
retain their separate contracts.

Set `href` to a safe link URL and the root renders as a real `<a part="base" href=…>` instead — a
link styled as a button (e.g. a CTA). Native navigation is then the activation, so the submit/reset
handling and `type` have no effect in that mode. A disabled link button (its own `disabled` or an
ancestor `<fieldset disabled>`) renders the anchor with `aria-disabled="true"` and **no `href`**, so
it is neither focusable nor navigable; it also dims to `--lr-opacity-disabled` with a `not-allowed`
cursor and no hover/press feedback, exactly like the disabled `<button>` path (an `<a>` can never
match `:disabled`, so that arm of the styling keys off `aria-disabled` instead). An
unsafe/unparseable `href` falls back to the native `<button>`.

The label does **not** grow to fill a stretched button. `[part="label"]` shrink-wraps its text and
the whole icon+label pair centres under `--lr-button-justify`, so the icon-to-text distance is
exactly `--lr-button-gap`. Before 16.0.0 the label was `flex: 1 1 auto`, which parked every spare
pixel inside the label box and — because the native `<button>` UA stylesheet centres text, which the
label wrapper inherited — floated the text in the middle of a wide empty row. A `with-caret` button,
and one with an `end`/`suffix` adornment, keep the growing label so that trailing affordance stays
pinned to the trailing content edge. `--lr-button-label-grow: 1` restores the old stretch and `0`
opts a caret/end-adornment row out of pinning. The label is also `text-align: start` now, which
fixes two side effects of the inherited centring: a label narrower than its own text centred the
overflow so the ellipsis appeared at the end while the start of the word was clipped, and the `<a>`
root (which never inherited the centring) disagreed with the `<button>` root across a mode switch.

**Properties:**

- `href?: string` — when set to a safe link URL (`http:`/`https:`/`blob:`/`mailto:`/relative; see
  `safeLinkHref`), the root renders as an `<a href=…>` instead of a `<button>`. Setting `download`
  narrows the allowlist to `http:`/`https:`/`blob:`/relative — `mailto:` names no retrievable bytes,
  so a `mailto:` href paired with `download` falls back to the native `<button>`. Unset (the default)
  renders a plain `<button>`, unchanged. `type` (submit/reset) has no effect while the anchor
  renders. While the button is disabled the anchor is rendered **without** `href` (keeping
  `aria-disabled="true"`), so a disabled link button cannot navigate. An unsafe/unparseable value
  falls back to the native `<button>`
- `target?: string` — native anchor `target`, used only while `href` resolves to a link. Setting it
  (e.g. `'_blank'`) automatically force-adds `noopener noreferrer` to the rendered anchor's
  relationship tokens. Ignored in `<button>` mode
- `rel?: string` — independently settable native relationship tokens with no default. Author tokens
  such as `nofollow`, `me`, `license`, `external`, and `tag` are preserved on same-tab and targeted
  links. `opener` is always stripped, and whenever `target` is set the non-removable
  `noopener noreferrer` floor is merged in. When neither `target` nor author tokens are present the
  anchor omits `rel`
- `download?: string` — native anchor `download` attribute, used only while `href` resolves to a
  link. Presence remains meaningful when the value is empty: `download=""` derives a filename and
  still selects the stricter downloadable-URL policy. Ignored in `<button>` mode
- `variant: 'neutral' | 'brand' | 'success' | 'warning' | 'danger' = 'neutral'` (reflected). Reads
  stay in Lyra's shared vocabulary; migrated Shoelace inputs normalize `default` → `neutral`,
  `primary` → `brand`, and `text` → neutral `appearance="plain"`. The Lyra/Web Awesome default is
  intentionally still `neutral`
- `appearance: 'accent' | 'filled' | 'outlined' | 'filled-outlined' | 'plain' | 'quiet' | 'link' =
'accent'` (reflected) — the library's shared fill vocabulary plus this component's own two extra
  tiers. **Breaking in 8.0.0: the default moved from `'filled'` to `'accent'`**, so a bare
  `<lr-button>` now paints the loud fill it used to need `appearance="accent"` for. The two are no
  longer near-duplicates: `'accent'` takes the active `variant`'s **loud** fill
  (`--lr-button-accent-fill`) with the foreground guaranteed legible on it, while `'filled'` takes
  that variant's **quiet** tint (`--lr-button-fill`) — a secondary-action fill that still reads as a
  fill rather than as the page surface. Before 8.0.0 every chromatic variant's `'filled'` and
  `'accent'` resolved to the same loud token and rendered identically, while `variant="neutral"`'s
  `'filled'` was the page surface, i.e. no fill at all. `'filled-outlined'` is `'filled'`'s fill and
  foreground carrying the outlined tier's border colour, for a filled button that must still read as
  bounded on a same-toned surface. `'quiet'` is a de-emphasized tier:
  transparent background with a bordered, muted-text chrome; its text/border tokens are **not**
  variant-swapped, so `variant` has no effect on it.
  `'link'` is a true inline-link tier:
  zero chrome (no padding, border, border-radius, or `min-block-size` floor), underlined
  (`text-underline-offset: var(--lr-size-0-15rem)`), colored from `--lr-button-accent` (the same token `'plain'`
  uses, so `variant` still selects the link color) and inheriting the surrounding font-size/weight
  — for a text link that flows within a sentence rather than a button-shaped control. Declared
  after the per-`size` rules, so it overrides them whatever `size` is set
- `size: LyraSize = 'm'` (reflected) — the shared control ladder. `'2xs'` is the tightest tier,
  below `'xs'`, for dense chrome; `'m'` is the standard one. Both spellings of every tier are
  accepted — `2xs`/`xs`/`s`/`m`/`l`/`xl` and `small`/`medium`/`large` — and the same ladder drives
  `lr-input`/`lr-select`/`lr-combobox`/`lr-date-input`, so same-`size` controls share density and
  minimum-height tokens rather than separate scales. That is not a blanket pixel-height promise:
  content and nested action hit-target floors can make a composed control such as `lr-date-input`
  taller
- `pill: boolean = false` (reflected) — fully rounded ends. It changes the private radius default
  to `--lr-radius-pill` rather than declaring a radius on `[part="base"]`, so an inherited or
  direct `--lr-button-radius` remains authoritative. `appearance="link"` renders with zero chrome,
  pill or not
- `circle: boolean = false` (reflected) — Shoelace-compatible circular icon-button treatment: a
  square control with the pill radius and compact inline padding. It is additive to, not a rename
  of, `pill`. Circle and automatically detected icon-only buttons retain the shared
  `--lr-icon-button-size` minimum clickable box at every `size`; the tier still scales their glyph
  and chrome. A visually hidden label does not count as content, so an icon plus an `.sr-only` name
  still gets the square, `--lr-icon-button-size`-floored treatment. `<lr-visually-hidden>`,
  `hidden`/`display: none`/`visibility: hidden`, and the standard absolutely-positioned
  `clip-path: inset(50%)` algorithm are all recognised from computed style, so a consumer's own
  utility class works whatever it is called
- `wrap: boolean = false` (reflected) — wraps a long label onto multiple lines instead of
  ellipsis-truncating it to one, the same opt-in `<lr-chip>` ships. Unset, `[part="label"]` keeps
  its single-line, ellipsis-truncated rule exactly
- `outline: boolean = false` (reflected) — Shoelace-compatible outlined treatment. It does not
  overwrite `appearance`, so removing `outline` restores the canonical Lyra appearance
- `withCaret: boolean = false` (attribute `with-caret`, reflected) — renders a decorative trailing
  chevron (`[part="caret"]`, `aria-hidden`) marking the button as a dropdown/menu trigger. It
  carries no accessible name of its own: the button's label already names the action, and the popup
  relationship is expressed by a host `aria-haspopup`/`aria-expanded`, which are forwarded to the
  internal control. Like the label and the two adornment slots it fades to `opacity: 0` while
  `loading`, so the spinner has the button to itself
- `caret: boolean = false` (attribute `caret`, reflected) — Shoelace alias for `withCaret`; either spelling renders the same part
- `withStart: boolean = false` / `withEnd: boolean = false` (attributes `with-start`/`with-end`) —
  Web Awesome SSR presence hints that keep the matching adornment wrapper mounted before slot
  assignment is observable
- `type: 'button' | 'submit' | 'reset' = 'button'`
- `loading: boolean = false` (reflected) — shows an internal spinner and disables the button without
  clearing `disabled`
- `disabled: boolean = false` (reflected)
- `accessibleLabel: string | null = null` (attribute `aria-label`) — accessible name forwarded
  reactively to the internal native button or anchor; changing or removing the attribute after
  mount updates the actual focused control
- `required: boolean = false` (reflected), `validity`, `validationMessage`, and `willValidate` —
  Web Awesome's form-validity surface. A required button needs a non-empty submitter `value`; this
  validation never makes the button a persistent form-data entry. Disabled, loading, and actual
  anchor modes clear effective validity while retaining intrinsic/custom state for restoration
- `customError: string | null` (attribute `custom-error`, reflected) — consumer validation message

**Submitter overrides (`type="submit"` in `<button>` mode).** `name`/`value` plus the five native
`form*` overrides describe the submission this button triggers, not the button itself:

- `formAction?: string` (attribute `formaction`) — overrides the form owner's `action`. Unset leaves
  the form's own action in place; an explicitly present empty string is forwarded and follows
  native resolution against the current document
- `formEnctype?: 'application/x-www-form-urlencoded' | 'multipart/form-data' | 'text/plain'`
  (attribute `formenctype`) — overrides the form owner's `enctype`
- `formMethod?: 'get' | 'post' | 'dialog'` (attribute `formmethod`) — overrides the form owner's
  `method`; `'dialog'` closes an ancestor `<dialog>` instead of submitting
- `formNoValidate: boolean = false` (attribute `formnovalidate`) — skips the form owner's
  constraint validation. Without it an invalid form is reported and not submitted, exactly as with
  a native submit button
- `formTarget?: string` (attribute `formtarget`) — overrides the form owner's `target`. Distinct
  from `target`, which is the anchor target used in link mode

All five are `undefined`/`false` by default. When any of them — or `name`/`value` — is set, the
submission runs through a **transient native `<button type="submit">`** inserted directly after the
host, used as `requestSubmit()`'s submitter and removed again in the same synchronous step (in a
`finally`, so a throwing or validation-blocked submission can't leave it behind). That is what makes
the name/value pair reach the submitted `FormData` and the overrides reach the real submission:
`requestSubmit()` only accepts a submitter the form actually owns, and a custom element is never
one. While that stand-in exists it _is_ the form's submitter, so **`SubmitEvent.submitter` is the
transient native button, not this host**. With none of those properties set, submission stays a
plain `requestSubmit()` with a `null` submitter, and all of it is inert in link mode.
For each string override, presence rather than truthiness chooses the transient path and its raw
attribute is copied, so explicit empty values remain distinguishable from absence. Only the
canonical native/upstream spellings are supported; the former hyphenated Lyra aliases were
removed.

Each size tier's `min-block-size` floor is exposed as its own token (see below).

**Getters/methods:** `click()`, `focus(options?)`, and `blur()` — forwarded to the internal base
element (the `<button>`, or the `<a>` in anchor mode); `click()` also runs the component's
submit/reset behavior in `<button>` mode. `getForm()` returns the browser-resolved form owner,
including an external owner selected by the `form` attribute. `checkValidity()`, `reportValidity()`,
and `setCustomValidity(message)` delegate to `ElementInternals`; `resetValidity()` clears only the
consumer error and restores the current `required`/`value` constraint. `formStateRestoreCallback()`
restores `value` for session history/autofill without changing submitter-only form-data semantics.

**Events:** a plain native `click` bubbles and composes through the shadow boundary unmodified
(disabled while `disabled` or `loading`). In button mode, submit/reset runs only after that click's
listener path has accepted the default action; calling `preventDefault()` on the host or an
ancestor therefore vetoes it, while propagation control by itself does not. The internal button's
`focus` and `blur` — which do not
cross the shadow boundary on their own — are re-dispatched from the host as bubbling, composed
events. `lr-invalid` (no
detail, cancelable) fires when a validity check finds the button invalid; `preventDefault()` on it
suppresses the native validation bubble and `reportValidity()`'s focus/scroll.

**Slots:** default (label content), `start` (leading icon/content), `end` (trailing icon/content),
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.

**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
wrapper), `caret` (the decorative dropdown chevron, present only while either caret spelling is
set), `spinner` (present only while `loading`).

**CSS custom states:** `disabled` (including fieldset-disablement and loading), `icon-button`
(one text-free default-slot element), `link` (safe anchor mode), and `loading`.

**Themeable custom properties.** The colour slots below are re-pointed at the active `variant`'s row
of the library's shared semantic colour grid, so the component carries no `:host([variant='…'])`
block of its own — the ones marked variant-independent are the exceptions:

- `--lr-button-accent` (default `--lr-color-fill-loud`) — text/glyph colour for the chrome-less
  tiers (`outlined`, `plain`, `link`), i.e. the variant's loud fill borrowed as a foreground.
  `variant="neutral"` is the one exception: its loud fill is a mid grey picked to carry _light_
  text, so reusing it as dark-on-surface text would wash out every plain and link button — neutral
  keeps `--lr-color-text` instead.
- `--lr-button-fill` (default `--lr-color-fill-quiet`) and `--lr-button-on-fill` (default
  `--lr-color-on-quiet`) — the `appearance="filled"`/`"filled-outlined"` fill and its
  guaranteed-legible foreground.
- `--lr-button-accent-fill` (default `--lr-color-fill-loud`) and `--lr-button-accent-on-fill`
  (default `--lr-color-on-loud`) — the same pair for `appearance="accent"`, the default tier. The
  accent fill is also that tier's border colour.
- `--lr-button-border` (default `--lr-color-border-normal`) — the border colour, from the active
  variant's row.
- `--lr-button-outlined-border` (default `--lr-color-border-strong`) — the border colour of
  `appearance="outlined"` _and_ `"filled-outlined"`, overriding `--lr-button-border`. Deliberately
  variant-independent.
- `--lr-button-outlined-fill` (default `transparent`) — the `appearance="outlined"` background, also
  variant-independent. Set it to tint an outlined button (a faint surface wash behind the outline)
  without a `::part(base)` rule, and point `--lr-button-hover-base` at the same colour so the hover
  and press states keep moving away from what is actually painted.
- `--lr-button-quiet-text` (default `--lr-color-text-quiet`) and `--lr-button-quiet-border` (default
  `--lr-color-border`) — the `appearance="quiet"` foreground/border pair, variant-independent too.

Hover and press are **colour mixes, not a filter** — `--lr-button-hover-base` (default
`--lr-color-surface`) is the colour both move away from, and each painted tier re-points it at the
fill it actually paints (`--lr-button-fill` for `filled`/`filled-outlined`, `--lr-button-accent-fill`
for `accent`); the chrome-less tiers paint nothing, so they mix from the page surface.
`--lr-button-hover-background` (default `color-mix(in oklab, var(--lr-button-hover-base),
var(--lr-color-mix-partner) var(--lr-color-mix-hover))`) is the hovered background and
`--lr-button-active-background` the same mix at the stronger `--lr-color-mix-active` share, so a
press reads as more than a hover. `appearance="link"` moves its text colour by those two shares
instead of taking a background. `--lr-button-hover-color` and `--lr-button-hover-border` are the
text/border counterparts, letting e.g. `appearance="quiet"` (which has its own resting
`--lr-button-quiet-text`/`-border`) theme its hover state independently. Both are **undeclared by
default**, falling back to whatever colour/border the active `appearance` already paints at rest —
every appearance's current hover paint is unchanged until one is set.
`appearance="link"` ignores `--lr-button-hover-color` (its own hover rule sets a higher-specificity
colour mix) and renders with no border at any state, so `--lr-button-hover-border` has no visible
effect there. **Breaking in 8.0.0:** this replaced `--lr-button-hover-brightness`,
which no longer exists — a `filter: brightness()` multiplies every channel, so it moved a mid-toned
fill but did nothing at all to a pure white or pure black one, and it dimmed the label and icons
along with the box. Retuning `--lr-button-fill` or `--lr-button-accent-fill` now retunes that tier's
hover and press with it.

`--lr-button-width` (default `100%`) is the internal control's inline size, so it follows the host's
own width; override it to `auto` for a compact inline composition. `--lr-button-active-scale`
(default `0.9875`) is the `:active` press-scale, dropped under `prefers-reduced-motion`.
`--lr-button-spinner-duration` (default `var(--lr-transition-ambient)`, i.e. `1.8s ease-in-out`) is
the `loading` spinner's rotation period; that token itself collapses to `0.001ms linear` under
`prefers-reduced-motion`, so the spinner effectively stops.

The per-`size` `min-block-size` floors are `--lr-button-size-2xs`, `--lr-button-size-xs`,
`--lr-button-size-s`, `--lr-button-size-m`, `--lr-button-size-l` and
`--lr-button-size-xl`. Each defaults to the matching tier of the shared form-control ladder
(`--lr-form-control-height-2xs` … `-xl`, i.e. 1.25rem, 1.5rem, 1.875rem, 2.5rem, 3rem, 3.5rem), so a
button shares the same minimum-height ladder as sibling form controls rather than relying on a
second hand-maintained list — which is exactly how the scales drifted apart before 8.0.0. This is
density/floor parity, not guaranteed pixel-height parity: content and nested actions can make a
composed control such as `lr-date-input` taller. Each token is read only by its own tier
(`--lr-button-size-s` also serves `size="small"`, and so on for the other two aliases), and all are
ignored by `appearance="link"`.
Retheming `--lr-theme-form-control-height-*` moves every control on the ladder together.
Circle and automatically detected icon-only buttons add the shared `--lr-icon-button-size` floor
on both axes, so the compact `2xs`/`xs` tiers cannot collapse those standalone targets below 40px.
Ordinary single-line labelled buttons keep the exact ladder heights above unless their content
requires more room.

`--lr-button-gap` (default `--lr-form-control-gap`, the gap between the icon/label and any slotted
content) does not vary by tier. `--lr-button-radius` (default `--lr-form-control-radius`, the corner
radius) _does_ follow the tier — the two tightest tiers take a smaller radius, since a 6px corner on
a 20px-tall control reads as a lozenge. Both are inheritable and retunable without a
`::part(base)` rule; `appearance="link"` ignores the radius (it renders with zero), and `pill`
changes its private default to `--lr-radius-pill`. `--lr-button-caret-size` (default
`var(--lr-size-0-75em)`) is the `with-caret`
chevron's font size — declared in `em`, so it tracks every `size` tier through the button's own font
size instead of needing a per-tier value.
`--lr-button-shadow` is **undeclared by default**, so `box-shadow` falls back to `none` —
byte-identical to before this property existed — set it to add a drop shadow (e.g. an
elevated/floating action button) without a `::part(base)` rule. `appearance="link"` always renders
with no shadow regardless of this token — a zero-chrome inline link has no box to elevate.
`--lr-button-justify` (default `center`) is the `justify-content` of the internal button's row. With
the label no longer growing, this is what positions the icon+label pair inside a stretched control:
`flex-start` packs it against the leading edge, `space-between` pushes the adornments apart.
`--lr-button-label-grow` (default `0`) is the `flex-grow` of `[part="label"]`; `1` restores the
pre-16.0.0 behaviour where the label absorbed every spare pixel of a stretched button, and it also
overrides the automatic grow a `with-caret`/`end`-adornment button applies.

**Retuning one `size` tier's geometry, without a `::part(base)` rule.** Four more properties carry
the active tier's geometry. Every `:host([size='…'])` rule changes only private defaults — no
per-tier rule redeclares a public hook or styles `[part='base']` directly. An inherited or direct
public value therefore retunes whatever tier is active (e.g. pinning a `size="s"` button into a compact toolbar row), the same
pattern `lr-input`/`lr-select`/`lr-combobox`/`lr-segmented`/`lr-date-input` follow. Each defaults to
the shared ladder's value for the active tier, which at the default `m` tier resolves to the values
in brackets:

- `--lr-button-padding-block` (default `--lr-form-control-padding-block`; `--lr-space-xs` at `m`)
- `--lr-button-padding-inline` (default `--lr-form-control-padding-inline`; `--lr-space-m` at `m`)
- `--lr-button-font-size` (default `--lr-form-control-font-size`; `--lr-font-size-m` at `m`)
- `--lr-button-min-height` (default `--lr-form-control-height`) — the active tier's `min-block-size`
  floor. Its private default follows that tier's own `--lr-button-size-*` token, and it is used as the
  fallback when `--lr-button-height` is unset.
- `--lr-button-height` — an **exact** height (both floor and cap), for pinning the button to a
  fixed toolbar row. **Undeclared by default**, so the button keeps the active tier's floor and an
  `auto` height; see "exact-height hatches" under `lr-input`.

`appearance="link"` ignores all five: it is declared after the `size` rules and resets padding,
font, and both height properties with literals, so an inline link can never take a button-shaped
box no matter what tier or override is in play.

**Optional peer deps:** none.

```html
<!-- appearance defaults to "accent": the loud fill, for the one primary action in a view. -->
<lr-button variant="brand">Save</lr-button>
<!-- "filled" is the quiet tint of the same tone, for a secondary action beside it. -->
<lr-button variant="brand" appearance="filled">Save a copy</lr-button>
<lr-button appearance="plain" aria-label="Close dialog"
  ><svg slot="start">...</svg></lr-button
>
<p>
  The message failed.
  <lr-button appearance="link" variant="brand">Retry</lr-button>
</p>

<lr-button pill with-caret aria-haspopup="menu" aria-expanded="false"
  >Actions</lr-button
>
<lr-button variant="primary" outline caret
  ><span slot="prefix">★</span>Migrated</lr-button
>
<lr-button circle aria-label="Settings"
  ><svg aria-hidden="true">...</svg></lr-button
>

<form action="/save" method="post">
  <lr-input name="title" label="Title" required></lr-input>
  <lr-button
    type="submit"
    name="intent"
    value="draft"
    formnovalidate
    formaction="/save-draft"
  >
    Save draft
  </lr-button>
  <lr-button type="submit" name="intent" value="publish">Publish</lr-button>
</form>
```

**Known gotchas:**

- `accessibleLabel`/a host `aria-label` is forwarded reactively to the internal button or anchor as
  a literal string (for an icon-only button). Host `aria-describedby` targets in the host's root
  are resolved onto the focused internal control through `ariaDescribedByElements`; external
  `aria-labelledby` is not copied across the shadow boundary.
- Host `aria-haspopup` and `aria-expanded` values are forwarded to the internal semantic control.
  For toggle buttons, host `aria-pressed="true|false|mixed"` reaches the focused native button —
  BUTTONS only. A link button (`href` set) never receives it, because `role="link"` does not support
  `aria-pressed`; remove `href` and the same host attribute starts reaching the `<button>` that
  replaces the anchor. That link carve-out arrived in **16.0.0** — before it, `aria-pressed` was
  forwarded onto the anchor as well, asserting a state `role="link"` does not have. Navigation can
  use the global `aria-current="page|step|location|date|time|true|false"`, which does reach the
  anchor. Both states update reactively, including native `ariaPressed`/`ariaCurrent` property
  assignments, attribute removal and `href` changes. Empty or unsupported tokens are omitted. The native button/link role
  remains unchanged for an enabled control: use pressed state for button toggles and current state
  for navigation links. A DISABLED link button drops `href` (so it genuinely cannot navigate) and
  therefore also drops the anchor's implicit role, so it renders an explicit `role="link"` — without
  it, the forwarded `aria-label`/`aria-haspopup`/`aria-expanded`/`aria-current` would sit on a
  role-less generic element, which is prohibited.
  For host `aria-controls`, targets in the host's own root are resolved through the reflected
  element-reference API so a popup relationship survives the component's shadow boundary; browsers
  with that API expose the relationship through `ariaControlsElements` and intentionally serialize
  the `aria-controls` content attribute as an empty string. Browsers without the API retain the
  forwarded string attribute as a best-effort fallback. A reflected element list and a non-empty
  serialized string cannot coexist; this is what lets either button serve as an `lr-menu` trigger.
- Is form-associated (`static formAssociated = true` + `attachInternals()`), so it participates in
  an ancestor `<form>.elements` the same way `wa-button` does — a sibling text field's own
  Enter-to-submit lookup (which scans `form.elements` for a `type === 'submit'` control) finds it.
- **`SubmitEvent.submitter` is not this element** whenever `name`/`value` or any `form*` override is
  set: it is the transient native `<button>` described above. That native submitter remains
  connected throughout synchronous `requestSubmit()` handling, so a `submit` listener can read
  its `name`, `value` and `form*` fields and construct `FormData` with it. It is removed after
  submission handling returns; its identity is distinct from the `lr-button` host.
- The `form*` overrides and `type` are all inert while `href` renders the anchor — native navigation
  is the activation there, and an anchor has no submit/reset concept.

---

## `lr-icon-button`

An accessible icon-only action/link with a native `<button>` inside. It is deliberately not a
form-associated submitter; use `<lr-button circle type="submit|reset">` with an icon-only default
slot when a form action is required. Because it is not form-associated, an ancestor
`<fieldset disabled>` does not disable it and it is absent from `form.elements`; set `disabled`
directly on each icon button.

External descriptions follow the current source element identity when an element with the same ID
replaces it, when a source is removed or reinserted, and when the control reconnects or moves to
another document. Host-root lookup and ordering follow the current `aria-describedby` list,
including unresolved IDs and duplicates. Switching between native button and anchor modes keeps the
relationship on the current action. Existing accessible names and `aria-controls` relationships
retain their separate contracts.

Its public `--lr-icon-button-*` theme inputs stay undeclared on the host, so an ancestor theme
wrapper can override the built-in fallbacks; a value set directly on the element still wins.

Host `aria-labelledby` IDREFs are resolved onto the internal control through
`ariaLabelledByElements`, so a composing component can name the button from elements in its own
shadow root — an idref cannot cross that boundary, the reflected element reference can. Per ARIA it
wins over `aria-label`/`label` and the localized fallback name.

**Lean registration entry.** `components/forms/icon-button/icon-button.js` eagerly imports
`<lr-icon>` so an `icon`/`src` attribute paints synchronously. A consumer who only ever slots their
own SVG can import `components/forms/icon-button/icon-button-register.js` instead, which registers
`<lr-icon-button>` and nothing else — no `<lr-icon>` implementation in the entry chunk and no
unreachable sanitizer chunk. Setting `icon`/`src` on a button registered that way renders no glyph
until `<lr-icon>` is registered by something else.

**Properties:**

- `icon: string = ''` — an `lr-icon` glyph name (see `llms/components/lr-icon.md`)
- `name: string = ''` — Shoelace alias for `icon`; reads and writes stay synchronized. Assigning
  the upstream `undefined` spelling clears both names to the canonical `''` read value
- `library?: string` / `src?: string` — forwarded to the nested `lr-icon`, preserving Shoelace
  icon-library and remote-SVG markup. Remote SVG loading inherits `lr-icon`'s URL, byte-ceiling,
  sanitization, and stale-generation guards
- `accessibleLabel: string = ''` (attribute: `aria-label`) — the typed override for the button's
  accessible name; wins over `label`
- `label: string = ''` — accessible name when `accessibleLabel` is unset
- `disabled: boolean = false` (reflected)
- `href?: string`, `target?: string`, `download?: string` — a safe `href` renders a native anchor;
  `target` derives `rel="noopener noreferrer"`, and download presence (including `download=""`)
  selects the stricter downloadable-URL allowlist. A disabled link keeps the anchor but removes
  `href`

With neither `accessibleLabel` nor `label` set, the name falls back to the localized
`iconButtonLabel` string rather than being empty — override it per instance with `.strings` or
app-wide with `registerLyraLocale()` (see `llms/shared.md`); don't rely on the fallback for a
button whose purpose isn't generic.

Host `aria-haspopup` and `aria-expanded` values are forwarded reactively to the shadow-internal
native button. `aria-pressed` (`true`, `false`, `mixed`) supports icon-only toggle actions such as
mute, favorite, or pin, and reaches the `<button>` rendering only — a link icon-button (`href` set)
never receives it, since `role="link"` has no pressed state (that carve-out arrived in **16.0.0**;
earlier versions forwarded it onto the anchor too); `aria-current` (`page`, `step`,
`location`, `date`, `time`, `true`, `false`) is global and supports current-item icon buttons such
as an active nav/pagination target in both renderings. Both follow attribute
changes, removal, and button/link replacement without changing the native role of an enabled
control; an empty or unsupported token is omitted — mirroring `lr-button`'s own
`aria-pressed`/`aria-current` forwarding. A disabled link icon-button drops `href` and renders an
explicit `role="link"` in place of the implicit role that goes with it, keeping its forwarded
accessible name legal. Host `aria-describedby` targets in the host's own root are resolved through
`ariaDescribedByElements`. Host `aria-controls` targets use the corresponding
`ariaControlsElements` API, so using `<lr-icon-button slot="trigger">` inside `<lr-menu>` exposes
the menu relationship and expanded state on the element that actually receives focus. Supporting
browsers intentionally clear each serialized internal IDREF attribute after its explicit element
list is assigned. Browsers without those APIs retain the forwarded string attributes as
best-effort fallbacks.

**Methods:** `focus(options?)`, `blur()`, and `click()` forward to the native interactive root,
activating the action button or a safe anchor through the same path as pointer/keyboard input.
`getToolbarActions(): readonly LyraToolbarAction[]` contributes this control as one logical action
to `<lr-message-actions>` and any other `LyraToolbarAction` toolbar. A roving-tabindex owner needs
it: writing `tabindex` on a custom-element host neither adds nor removes its shadow-internal
button's tab stop, so without it a slotted icon button either stays permanently tabbable or drops
out of the toolbar's stop list. `control: HTMLButtonElement | HTMLAnchorElement | null` (read-only)
is the internal native control that owns the role, for projecting a host IDREF relationship onto it;
it is `null` before the first render, mirroring `<lr-virtual-list>`'s `scrollContainer`.

**Events:** a plain native `click` crosses the shadow boundary unmodified. The internal button's
`focus` and `blur` are re-dispatched from the host as bubbling, composed events.

**Slots:** (default) — custom icon content. It is rendered **beside** the `icon` glyph, as a
sibling of it, not piped through `<lr-icon>`: the internal `<lr-icon>` mounts only when `icon` is
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.

**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
own has no real SVG parent as parsed, and is detected and cloned into an internal
`[part="fallback"]` SVG-namespaced element so it still paints — the same fallback `<lr-icon>`'s own
custom-content slot uses. The `[part="fallback"]` svg carries the same `fill="none"
stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round"` defaults
`<lr-icon>`'s own wrapper svg does, so bare stroke-style geometry (the common lucide/feather/tabler
path-data shape, which carries no fill/stroke of its own) renders outlined instead of as a solid
shape; an explicit `fill`/`stroke`/etc. already present on the slotted node still wins for that
node. This is narrowly scoped to that whitelist: a complete `<svg>`, `<img>`, or custom element
(e.g. `<lr-flag>`) is never touched by it and keeps rendering as an untouched sibling at its own
natural aspect ratio.

**CSS parts:** `base`/`button` (the same native button or anchor), `fallback` (only present in the
DOM while at least one top-level slotted element needs the bare-geometry fallback above)

**Themeable custom properties:** `--lr-icon-button-size` (default `2.5rem`) is the **minimum**
tappable inline and block size of the native button — a floor, not a fixed size. Content larger
than it grows the button and keeps its own aspect ratio; a small glyph pads out to it. It is a
library-wide token (declared on every `lr-*` host by the shared token layer, and the shared minimum tappable size
that several other components size their icon-only controls against), so overriding
`--lr-theme-icon-button-size` globally resizes all of them together. Keep the resolved value at or
above 24px — see `llms/shared.md`. **`--lr-icon-button-size` is element-scoped, unlike every other
token in this section:** the shared token layer re-declares it on every `lr-*` host's own `:host`,
so a rule that sets `--lr-icon-button-size` on an ancestor wrapper is reset the moment it crosses
into any intervening `lr-*` component and never reaches a `<lr-icon-button>` composed inside it
(e.g. one slotted through `<lr-popover>`). The three levers that actually reach it are: setting
`--lr-icon-button-size` directly on the icon button element itself, where no intervening component
sits between the rule and the property; setting `--lr-icon-button-size-scope` on any ancestor to
resize one subtree; or setting `--lr-theme-icon-button-size` on an ancestor to resize the whole
application. The shared layer reads the latter two through `var()` at every level, so both reach a
`<lr-icon-button>` composed inside another component, e.g. `<lr-copy-button>`/
`<lr-message-actions>` -- see `llms/shared.md` for the full scope table.

Lowering the floor for a dense action row below 24px is safe **only through the two ancestor
levers**. The coarse-pointer/no-hover media rule reads those, and floors the RENDERED hit area back
at 2.75rem/44px however far the override lowered it, so the control stays comfortably tappable the
moment the pointer reaching it is a finger rather than a mouse. It does **not** rescue
`--lr-icon-button-size` set directly on the element: that declaration comes from the outer tree and
outranks the shadow tree's own `:host` rule, so the media rule never wins and the rendered hit area
is exactly the value set -- `--lr-icon-button-size: 1rem` really does render a 16px target under a
coarse pointer, which fails WCAG 2.2 SC 2.5.8. Prefer `--lr-icon-button-size-scope` when the intent
is a denser row; reach for the element-scoped name only as a deliberate, localized trade-off. `--lr-icon-button-radius` (default
`--lr-radius`) is not re-declared anywhere in the shared layer, so — like every other token below —
it inherits normally from an ancestor even through an intervening component; it is the
`[part='button']` corner radius, retunable without a `::part(button)` rule — the same
`--lr-button-radius` pattern; `lr-icon-button` has no `size` tiers, so there is no per-tier gap
counterpart to it. The internal control sets `font: inherit`, so an `em`-sized slotted glyph takes
the surrounding text's font-size rather than the native button's UA default.

The rest come in resting/hover/pressed triples, each falling through to the next-quieter state so
setting only one still behaves:

- `--lr-icon-button-background` (default `transparent`),
  `--lr-icon-button-background-hover` (default `color-mix(in oklab, var(--lr-color-surface),
var(--lr-color-mix-partner) var(--lr-color-mix-hover))`) and
  `--lr-icon-button-background-active` (the same mix at the stronger `--lr-color-mix-active` share,
  so a press reads as more than a hover) — the `[part='button']` background in each state. The
  hover fallback used to be `--lr-color-surface` itself, i.e. the page background, so hovering an
  icon button on a default page changed nothing at all.
- `--lr-icon-button-color` (default `inherit`), `--lr-icon-button-color-hover` (default
  `var(--lr-icon-button-color, inherit)`) and `--lr-icon-button-color-active` (default
  `var(--lr-icon-button-color-hover, var(--lr-icon-button-color, inherit))`) — the icon/text colour.
- `--lr-icon-button-border` (default `0`), `--lr-icon-button-border-hover` (default
  `var(--lr-icon-button-border, 0)`) and `--lr-icon-button-border-active` (default
  `var(--lr-icon-button-border-hover, var(--lr-icon-button-border, 0))`) — the _complete_ native
  border shorthand, replaced wholesale in each state rather than merged.

These are the same per-component indirection `lr-button`'s
`--lr-button-fill`/`--lr-button-on-fill` provide, letting a single button be bordered and tinted
without a `::part(button)` rule. All nine are undeclared by default and read as inline `var()`
fallbacks, so setting only the resting value carries through hover and press, and setting none of
them leaves rendering unchanged.

```html
<lr-icon-button name="search" library="default" label="Search"></lr-icon-button>
<lr-icon-button
  name="chevron-right"
  label="Open documentation"
  href="https://example.com/docs"
  target="_blank"
></lr-icon-button>
```

## `lr-input`

A single-line plain-text input primitive, the `lr-*` equivalent of a plain `wa-input`,
form-associated via the same `FormAssociated` mixin as `lr-textarea`. Ships the same opt-in
`label`/`hint`/`errorText` form-control chrome as `lr-textarea`/`lr-select`, and the same
`size` scale as `lr-select`/`lr-combobox`.

`stepUp()` and `stepDown()` use the current `value`, `step`, `min`, and `max` properties in the same
synchronous call, including changes made immediately beforehand. They preserve native step alignment
and bounds, update form submission silently, and remain no-ops before the native input has rendered
or while disabled/readonly. Native `step="any"` remains a non-steppable no-op.

Removing `label`, `hint`, `help-text`, or `error-text` safely omits that content while retaining
native `null` property readback. Explicit empty strings remain empty and later supplied text renders
normally. The same inherited behavior applies to `lr-number-input` and `lr-native-time-input`.

Changing own `disabled` from true to false in the same task that disables an ancestor fieldset keeps
the native editing control effectively disabled. The enabled first-legend exception and explicit
own-disabled state retain their native meaning; validity and form submission follow the effective
disabled state.

Pressing Enter submits the ancestor `<form>` — the implicit submission a native `<input>` performs;
see "Enter-to-submit" below for the exact rules and for which controls deliberately opt out.

Public `--lr-input-*` theme inputs stay undeclared on the host, so an ancestor theme wrapper can
override size, appearance, and pill fallbacks; a value set directly on the element still wins.
When a clear or password action is present, `2xs` through `m` grow only enough to contain its
shared hit target (42px including the row border at the default theme); `l` and `xl` retain their
48px and 56px shared control heights.

**Properties:**

- `type: LyraInputType = 'text'` — `'text' | 'password' | 'email' | 'number' | 'time' | 'search' |
'date' | 'datetime-local' | 'tel' | 'url'`. Unsupported attribute or direct-property strings
  normalize to reflected `text` before native validity and type-dependent chrome are projected
- `size: LyraSize = 'm'` (reflected — see "Shared form vocabulary" below)
- `appearance: 'accent' | 'filled' | 'outlined' | 'filled-outlined' | 'plain' = 'outlined'`
  (reflected) — the shared field-surface vocabulary. `outlined` (the mapped default) draws a border
  without a fill; `filled-outlined` draws both, `filled` drops the border, `plain` drops
  both, and `accent` tints both with the brand color. Each value does nothing but swap
  `--lr-input-fill`/`--lr-input-border-color`, so either can be retuned without a
  `::part(input-wrapper)` rule
- `filled: boolean = false` (reflected) — Shoelace alias for the filled treatment
- `pill: boolean = false` (reflected) — rounds the control row to a full pill by swapping
  `--lr-input-radius` to `--lr-radius-pill`
- `autofocus: boolean = false` — forwarded to the internal native `<input>` rather than left on the
  host, so the browser's own autofocus algorithm targets the real text control (the custom-element
  host is not focusable). Left unset, the native attribute is omitted entirely
- `value: string = ''` (from `FormAssociated`)
- `defaultValue: string = ''` — reset value, backed by the standard `value` content attribute;
  `default-value` is accepted as a Shoelace attribute alias
- `name: string` (from `FormAssociated`) and the plain inherited `id` are both forwarded to the
  internal native `<input>` (previously the internal input carried neither, only a fixed
  `id="input"`), so shadow-DOM-aware password managers that key field detection off the actual
  control's own `name`/`id` — not `autocomplete` alone — recognize `<lr-input>` fields. The
  internal `<label for>` tracks whichever id is in use. Leaving `id` unset on the host keeps the
  internal input at `id="input"`, identical to before
- `placeholder: string = ''`
- `clearable: boolean = false` (reflected) — shows a localized clear action while a `text` or
  `search` input has a value; clearing preserves input focus
- `withClear: boolean = false` (attribute `with-clear`) — Web Awesome's spelling of `clearable`;
  either one shows the same action. Inherited by `lr-number-input` and `lr-native-time-input`,
  where it is inert because their native types render no clear action. The separate segmented
  `lr-time-input` implements its own `with-clear` action
- `readonly: boolean = false` (reflected) — forwarded to the native input and disables clearing
- `label: string = ''`
- `hint: string = ''`
- `helpText: string = ''` (attribute `help-text`) — Shoelace alias for `hint`; `hint` wins when both
  are set. `withLabel`/`withHint` (`with-label`/`with-hint`) provide optional SSR slot-presence hints
- `errorText: string = ''` (attribute `error-text`)
- `accessibleLabel: string | null = null` (attribute `aria-label`)
- `autocomplete: string = ''`
- `title: string = ''` — forwarded to the native input
- `spellcheck: boolean = true` — forwarded to the native input, including `spellcheck="false"`
- `autocapitalize: string = ''` / `autocorrect` (read: `boolean = true`; write:
  `boolean | 'off' | 'on'`; attribute values `on`/`off`)
- `inputMode: string = ''` (attribute `inputmode`) / `enterKeyHint: string = ''` (attribute
  `enterkeyhint`) — `autocapitalize`, `inputMode`, and `enterKeyHint` are forwarded verbatim to the
  native input and an empty string omits them; `autocorrect` is normalized to canonical `on`/`off`
- Lowercase native IDLs `inputmode: string` and `enterkeyhint: string` delegate to the camel-case
  native properties; `autocorrect` reads as boolean while accepting both Web Awesome's boolean
  writes and Shoelace's `'off'`/`'on'` writes

**8.0 migration:** the former camel-case string property `autoCorrect` is not retained as a public
alias. Prefer boolean `autocorrect` writes in new code; migrated Shoelace `'off'`/`'on'` property
writes remain valid and read back as booleans. Markup uses `autocorrect="on"` /
`autocorrect="off"`.

- `min?: number | string` / `max?: number | string` (attributes `min`/`max`) /
  `step?: number | 'any'` (attribute `step`, accepts the native `'any'` value alongside a number)
  — forwarded verbatim to the native
  input and validated by it. Intended for `type="number"`; `step` is equally meaningful on
  `type="time"`. On `lr-input` itself the `min`/`max` _attributes_ are number-converted, so a
  non-numeric bound only survives a direct property assignment; the declared type also admits a
  string so a subclass can narrow the attribute parsing to its own native type's literal form —
  `lr-native-time-input` does exactly that. Inert for the other types
- `minlength?: number` / `maxlength?: number` (attributes `minlength`/`maxlength`) — text-length
  bounds forwarded to the native input and reported as `validity.tooShort`/`validity.tooLong`.
  Apply to the text-bearing types (`text`, `search`, `email`, `password`); the platform ignores
  both on `type="number"`/`type="time"`, and so does this component
- `pattern?: string` (attribute `pattern`) — a regular expression the value must match in full,
  forwarded to the native input and reported as `validity.patternMismatch`. Anchored to the whole
  value by the platform, so no `^`/`$` is needed; an empty value never violates it
- `passwordToggle: boolean = false` (attribute `password-toggle`, reflected — `type="password"`
  only) — renders the built-in show/hide-password button. **Breaking in 8.0.0: this is now opt-in.**
  Before, `type="password"` always rendered the toggle and there was no way to remove it; a consumer
  whose threat model or visual design excludes one had to hide it with CSS. Add `password-toggle`
  to keep the old rendering
- `passwordVisible: boolean = false` (attribute `password-visible` — `type="password"` only) —
  whether the field currently reveals its raw text. Toggled by the built-in button, and also
  settable up front with or without that button being rendered
- `match: string | HTMLElement | null = null` (attribute `match`) — declarative cross-field
  confirmation constraint: a sibling field to compare this one's `value` against, referenced either
  by id (resolved in this element's own root — an idref never crosses a shadow boundary, matching
  every other idref this library resolves) or by a direct element reference (works across shadow
  trees, since no lookup is needed). While set and resolvable, this field additionally fails
  validity — `customError`, with a localized mismatch message — whenever its value differs from the
  referenced element's own `.value`, but only once every other constraint above (`required`,
  `pattern`, length, type-specific format) already reports valid, so an empty required confirm
  field reports `valueMissing`, not a mismatch. Re-validates automatically on either field's own
  edits: this one's through the usual `value` write, and the referenced one's through a listener on
  its `input`/`change` events, so retyping the password half of a confirm pair revalidates the
  confirm field immediately, not only on its own next edit. A `match` that does not resolve to a
  live element (most commonly a dangling id) is inert rather than a permanent block on submission,
  exactly like the platform's own tolerance of an unresolvable `aria-describedby` idref. The
  referenced element only needs a string `.value`, so a native `<input>`/`<textarea>` works the
  same as another `lr-input`; see "A new-password field" below for the password-confirmation shape
- `withoutSpinButtons: boolean = false` (attribute `without-spin-buttons`, reflected —
  `type="number"` only) — suppresses the browser's own increment/decrement spin buttons.
  **Breaking in 8.0.0:** `type="number"` used to hide them unconditionally; left unset, the
  platform's spinners now render exactly as they do on a bare `<input type="number">`.
  `<lr-number-input>` defaults this the other way (`true`), so its rendering is unchanged
- `noSpinButtons: boolean = false` (attribute `no-spin-buttons`) — Shoelace alias for
  `withoutSpinButtons`; either suppresses native number spinners
- `debounce?: number` (attribute `debounce`, ms) — how long to wait after the last keystroke
  before emitting one `lr-input-settled`, while `input`/`lr-input` keep firing per keystroke as
  before. Omitted, `0`, or a non-finite value means no debounce at all: `lr-input-settled` never
  fires. A pending debounce is flushed immediately by `change`/Enter/blur (so a blur never drops
  the last keystroke) and cancelled with no stray settle by disconnection, the built-in clear
  button, and a programmatic `value` write that changes the value. A write of the value already
  held leaves it pending, so a framework binding that writes the just-typed value back on each
  render (the controlled-input pattern) still settles. Shares its `DebounceController` primitive with
  `lr-filter-bar`'s own per-filter `debounce` and with `lr-textarea`'s identical property
- `name`/`disabled`/`required` (from `FormAssociated`)

**Getters/methods:** `input: HTMLInputElement | null` (the internal native `<input>`, for direct DOM
access), `focus(options?: FocusOptions)`, `blur()`, `select()`. Also forwards the full native
selection/editing surface, mirroring `lr-textarea`'s identical passthrough: `selectionStart: number
| null` and `selectionEnd: number | null` (readable/writable; `null` both before the internal input
has rendered and whenever `type` doesn't support selection — only `text`/`search`/`password` do,
matching the native `<input>`'s own contract), `setSelectionRange(start, end, direction?)`
(no-op before render, otherwise throws the same native `InvalidStateError` a native `<input>` would
for an unsupported `type`), and `setRangeText(replacement, start?, end?, selectMode?)` (no-op
before render; syncs `value` afterward without emitting a user event).
The shared form surface also exposes `getForm()`, which returns the browser-resolved owner including
an external form selected by the `form` attribute. `resetValidity()` clears only consumer-supplied
custom validity and recomputes the current native/required constraints; it leaves
`value`/`defaultValue` and prior interaction state unchanged, so an intrinsically invalid input
stays invalid.

Three more native passthroughs:

- `valueAsDate: Date | null` / `valueAsNumber: number` — native getters/setters for date/time and
  numeric input types. Assignment synchronizes `value`, form value, and validity without emitting a
  user edit event; unsupported types retain the native `null`/`NaN` behavior.

- `showPicker(): void` — opens the browser's own picker for the current `type` (the time picker, and
  whatever chooser the platform offers for the other types), delegating to the internal native
  `<input>`. Deliberately failure-tolerant: the platform method throws for environmental reasons a
  component can neither detect up front nor usefully report (no user activation →
  `NotAllowedError`, a cross-origin document → `SecurityError`, a non-mutable control →
  `InvalidStateError`), and engines that predate it don't define it at all. A picker that cannot
  open is a **no-op here rather than an exception** you must wrap every call in. Also a no-op while
  `disabled` or `readonly`.
- `stepUp(steps = 1): void` / `stepDown(steps = 1): void` — increment/decrement by `steps` × the
  effective `step`, through the native `<input>`'s own `stepUp()`/`stepDown()`, so `min`/`max`
  clamping and decimal handling stay the platform's. **Silent, like the native methods**: they
  update `value`, the submitted form value and validity, but emit no `input`/`change`. A
  non-finite `steps` falls back to `1`; `0` is a no-op, as is `step="any"`, as is any `type` the
  platform gives no allowed value step (it throws `InvalidStateError` for those, which is swallowed
  here), and as is `disabled` or `readonly`. `type="number"` and `type="time"` are the two that step
  — on a time field the unit is seconds, matching its `step`.
  `<lr-number-input>`'s stepper buttons build on these and _do_ emit, because a button press is a
  user edit.

**Events:** native-style composed `input` and `change`, plus `lr-input` (`detail: { value }`,
fired on every user-driven edit) and `lr-change` (`detail: { value }`, fired on the native
`change` timing), `blur`/`focus` (re-dispatched bubbling + composed from the internal native input's
own `blur`/`focus`), and
`lr-clear` (no detail, fired after the clear action's `input`/`lr-input`/`change`/`lr-change`
sequence). `lr-invalid` (no detail) fires when a validity check finds the input invalid.
`lr-input-settled` (`detail: { value }`, non-cancelable) fires once, `debounce` ms after the last
keystroke, alongside the per-keystroke `input`/`lr-input` pair; see `debounce` above for the flush
and cancellation rules. Never fires while `debounce` is unset, `0`, or non-finite.

**Slots:** `label`, `hint`/`help-text`, `error`, `start`/`prefix` (aliases before the input),
`end`/`suffix` (aliases after the input and built-in actions), `clear-icon`,
`show-password-icon`, and `hide-password-icon`.

**CSS parts:** `form-control`, `form-control-label`, `label`, `base`/`form-control-input`/
`input-wrapper` (compatibility names on the row wrapping the native input and actions), `input`,
`password-toggle`, `password-toggle-button`
(present only when `type="password"` **and** `password-toggle` is set), `start`, `end`,
`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
`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
`[part="form-control-label"]` — the one `::after` rule described under "The required-field marker"
above, and the reference implementation every other labelled control in the library shares, so
`--lr-form-control-required-content`, `--lr-form-control-required-color` and
`--lr-form-control-required-offset` retune or suppress it. With no label text the part is hidden and
no glyph is painted.

**Themeable custom properties:** `--lr-input-padding-block`, `--lr-input-padding-inline`,
`--lr-input-font-size`, `--lr-input-control-min-height` — all four have private defaults that follow
`size` (`2xs`…`xl`), while inherited or direct public values remain authoritative; the same pattern
`lr-select`'s `--lr-select-trigger-padding`/`--lr-select-font-size` use.
`--lr-input-control-height` pins an **exact** outer control-row height (both floors and caps it) —
for example to pixel-match an `<lr-select>` or `<lr-combobox>` in the same toolbar row. It is
undeclared by default, leaving `--lr-input-control-min-height` as a floor only and the row free to
grow. `--lr-input-gap` (default `--lr-space-xs`, the gap inside `[part='input-wrapper']`) is
retunable without a `::part(input-wrapper)` rule and, unlike the four properties above, does not
vary by `size` — the adornment gap a text field wants between an adornment and the caret is looser
than the icon-beside-label gap the ladder is tuned for. `--lr-input-radius` (default
`--lr-form-control-radius`, its corner radius) is retunable the same way but _does_ follow the tier:
the two tightest tiers take a smaller radius, since a 6px corner on a 20px-tall control reads as a
lozenge. `pill` changes its private default to `--lr-radius-pill`; an inherited or direct public
value still wins. `lr-number-input`/`lr-native-time-input` inherit both
unchanged. The separate segmented `lr-time-input` also consumes the documented input theme tokens.

`--lr-input-fill` (default `transparent`) is the control row's background and
`--lr-input-border-color` (default `var(--lr-color-border)`) its border color. `appearance` changes
their private fallback roles rather than the public hooks, and the documented defaults are
`appearance="outlined"`'s values. Ancestor theme wrappers therefore still win. Setting either
directly retunes the surface
without a `::part(input-wrapper)` rule and without leaving the `appearance` vocabulary behind.
`--lr-input-focus-border-color` independently retunes the focused row, and the shared field halo
`--lr-form-control-focus-shadow` (default `none`) adds a `box-shadow` layer while the row holds
focus — one name for every field-shaped control in the library, additive rather than a replacement
for the focused border. Built-in clear/password
actions and `lr-number-input` steppers share `--lr-input-action-color`,
`--lr-input-action-hover-color`, `--lr-input-action-active-color`, and
`--lr-input-action-active-bg`; all fall back to the previous text/surface semantic tokens.
For `type="time"`, the browser-native picker indicator gains disabled-gated hover and focus-visible
affordances through `--lr-input-time-picker-hover-bg`, `--lr-input-time-picker-active-bg`,
`--lr-input-time-picker-focus-bg`, and `--lr-input-time-picker-focus-ring` (falling back to
brand-quiet/brand and the canonical focus-ring token).

### Shared form vocabulary — `size`, `appearance`, `pill`, and custom validity

Four things every form control in this family now spells the same way. They are documented here
because `lr-input` is where a reader meets all four at once; each component's own list restates only
what is specific to it.

- **`size` accepts both spellings of every tier.** The canonical ladder is
  `2xs`/`xs`/`s`/`m`/`l`/`xl`, and `small`/`medium`/`large` — Web Awesome's and Shoelace's names —
  are accepted as exact synonyms for `s`/`m`/`l`. Nothing is normalized away in JS: the shared
  stylesheet matches both spellings in the same selector list, so `size="small"` costs nothing and
  `el.size` reads back whatever you wrote. A migration off either upstream is a tag rename with no
  attribute rewrite. One ladder now drives `lr-button`, `lr-input`, `lr-select`, `lr-combobox`,
  `lr-date-input`, `lr-textarea`, `lr-checkbox`, `lr-radio`, `lr-switch` and `lr-slider`, so
  same-`size` controls line up in a toolbar row by construction. Retune a whole tier from one place
  with `--lr-theme-form-control-height-*` rather than per component. Set
  `--lr-theme-form-control-radius` on the same ancestor to give these controls one shared corner
  radius across every tier; without it, the compact `2xs`/`xs` tiers retain their smaller default
  radius.
- **`appearance` is the fill vocabulary and nothing else.** `accent` (the loud semantic fill),
  `filled` (a quiet tint of the same tone), `outlined` (a border, no fill), `filled-outlined`
  (both) and `plain` (neither). It used to double as a _container_ treatment on other components;
  that meaning moved to `frame` (`card`/`plain`) in 8.0.0, so `appearance` means one thing
  library-wide. `lr-button` adds two tiers of its own on top (`quiet` and `link`). Text fields
  (`lr-input`, `lr-textarea`, and `lr-select`) default to `outlined`; `lr-button` defaults to `accent`.
- **`pill` rounds the control's ends.** Available on `lr-input`, `lr-number-input`, `lr-time-input`,
  `lr-textarea`, `lr-select`, `lr-combobox`, `lr-date-input`, `lr-phone-input`, `lr-token-input`,
  `lr-button` and `lr-radio-button`. In every case it does exactly one thing — re-assign that
  component's own `--lr-*-radius` knob to `--lr-radius-pill` — rather than declaring a radius on a
  part, so the knob stays the single corner-radius override point and a consumer's own value still
  wins over it.
- **`setCustomValidity(message)` and `resetValidity()` are on every form-associated _value_ control
  here** — every one
  that submits something, whether it drives `ElementInternals` through the shared mixin or by hand.
  (`lr-button` is a form-associated submitter, so an ancestor `<fieldset disabled>` and
  `form.elements` reach it, but it carries no value or validity and therefore has no such method;
  `lr-icon-button` is deliberately not form-associated.) It is the standard channel for a rejection
  no client-side constraint can express — a server-side
  "that email is already registered". A non-empty message raises `customError` and becomes
  `validationMessage`, so the control fails `checkValidity()`, blocks submission, and matches
  `:invalid`/`:state(invalid)`.
  `''` clears it and republishes the control's _own_ computed validity rather than forcing it valid:
  a required-and-empty field goes back to `valueMissing`. The message survives every intrinsic
  recomputation and a `form.reset()`, exactly like a native control; `setCustomValidity('')` or
  `resetValidity()` clears it. `resetValidity()` affects only that consumer layer and recomputes the
  current intrinsic constraints: it does not change `value`/`defaultValue`, make the control
  pristine again, or force an intrinsically invalid value valid. The message is used verbatim,
  never localized, because it is caller-supplied content.

### Enter-to-submit

Pressing Enter in a single-line text control submits the ancestor `<form>`, the implicit submission
a native `<input>` performs. The internal input lives in a shadow root and has no form owner of its
own, so the platform can never run it here; the component does, following the platform's own rules
rather than an approximation of them:

- The keystroke must be a **bare** Enter — any of Ctrl/Cmd/Alt/Shift held makes it an application
  shortcut (send-and-keep-open, insert-newline, open-in-new-tab), never a submission.
- An Enter **during IME composition** commits the highlighted candidate; submitting there would
  throw away the word being typed, so it is skipped.
- A keydown already `defaultPrevented` by a listener above stays vetoed.
- The **submitter is resolved, not skipped**: the form's default button is the first enabled submit
  control in `form.elements`, so its `name`/`value` entry and its
  `formaction`/`formmethod`/`formnovalidate` overrides all reach the submission. A native button
  goes through `form.requestSubmit(submitter)`; an `<lr-button type="submit">` is a form-associated
  custom element, which `requestSubmit()` rejects with a `TypeError`, so it is activated through its
  own `click()` — the same path a real click takes.
- A form with **no** submit button submits implicitly only when it holds at most one field that
  blocks implicit submission, matching the platform.
- It runs through `requestSubmit()`, never `submit()`, so the `submit` event fires and interactive
  constraint validation blocks an invalid form exactly as a real submit button would. Each control
  also gates on its own `disabled`/`readonly` first.

**Deliberately not wired everywhere.** Enter means something else in several controls, and implicit
submission must never shadow it: `lr-textarea` and `lr-code-editor` insert a newline, which is the
whole point of a multi-line surface; `lr-select`'s `role="combobox"` trigger opens the listbox (and
then commits the active option), per the ARIA pattern; and `lr-date-picker` selects the focused day
in the calendar grid. The controls that _do_ wire it are `lr-input` (and its `lr-number-input`/
`lr-native-time-input` subclasses), the separate segmented `lr-time-input`, `lr-combobox`,
`lr-date-input`, `lr-phone-input`, `lr-token-input` and `lr-otp-input`.

### Exact-height hatches — the one rule that applies to all of them

Several controls expose the same pair: a per-`size` `*-min-height` **floor**, and an exact
`*-height` **cap**. The family is `--lr-input-control-height`, `--lr-select-trigger-height`,
`--lr-combobox-trigger-height`, `--lr-date-input-control-height`, `--lr-button-height`,
`--lr-known-date-field-height`, and `--lr-chip-height`. Every one of them behaves identically:

- **Each is undeclared by default.** The component reads it only through two `var()` fallbacks —
  `min-block-size: var(--lr-x-height, var(--lr-x-min-height))` and
  `block-size: var(--lr-x-height, auto)` — so leaving it unset is what makes the per-tier floor
  and the content-driven height work at all.
- **Setting one to `auto` is not the same as leaving it unset.** `auto` is a perfectly valid
  _declared_ value, and a declared value wins over the `var()` fallback arm — so `auto` silently
  turns the per-tier `*-min-height` floor into dead code, and nothing anywhere reports it. To
  return a control to default behavior, **remove** the declaration; never neutralize it with
  `auto`.
- Because the component itself never declares them, each can be set inline on the element, from an
  ancestor, or from an outer-tree rule (`lr-input { --lr-input-control-height: 44px }`) — no
  `::part()` rule needed.
- **A dead declaration is invisible in source.** There is no way to tell a live `--lr-*`
  declaration from a shadowed or defeated one without rendering: a test asserting on stylesheet
  text passes either way. Assert the rendered `min-block-size`/`block-size` via
  `getComputedStyle` on the real element instead of reading the custom property back.

**Optional peer deps:** none.

```html
<lr-input type="password" label="Password" password-toggle></lr-input>
<lr-input type="email" label="Email" required></lr-input>
<lr-input size="s" placeholder="Compact"></lr-input>
<lr-input appearance="plain" pill placeholder="Pill, no chrome"></lr-input>
<lr-input
  type="number"
  min="0"
  max="10"
  step="0.5"
  without-spin-buttons
  label="Weight"
></lr-input>
<lr-input type="search" clearable value="workflow" aria-label="Search"
  ><span slot="start">⌕</span></lr-input
>
<lr-input type="time" label="Reminder" id="reminder"></lr-input>
<button type="button" id="open-picker">Pick a time</button>
<script type="module">
  import "@aceshooting/lyra-ui/components/forms/input/input.js";
  const time = document.getElementById("reminder");
  // showPicker() needs user activation, so drive it from a real click.
  document
    .getElementById("open-picker")
    .addEventListener("click", () => time.showPicker());
</script>
```

`password-toggle`, `pill` and `without-spin-buttons` all default to `false`, so the plain
attribute form is enough to turn each on. `autofocus` is likewise `false`-defaulting — none of
these four needs the property form to be reset.

**A new-password field.** There is no dedicated password-purpose preset — a deliberate decision,
not an omission: the only thing such a preset would actually save is `autocomplete`, and that value
has no single correct default for "a password field" (`new-password` on a set/change/reset flow,
`current-password` on a login one, and one is never derivable from the other), so a `purpose`
property would still need a second parameter carrying that same distinction, in exchange for a
non-standard vocabulary a migrating `wa-`/`sl-`/native `<input type="password">` author would have
to learn instead of carrying over unchanged. Compose the existing primitives directly, the same way
a plain native `<input type="password">` does:

```html
<lr-input
  type="password"
  id="new-password"
  label="New password"
  password-toggle
  autocomplete="new-password"
  minlength="12"
  required
></lr-input>
<lr-input
  type="password"
  label="Confirm password"
  password-toggle
  autocomplete="new-password"
  match="new-password"
  required
></lr-input>
```

`autocomplete="new-password"` (rather than the bare `password` token, and never `current-password`
on a set/change/reset flow) is the platform contract that keeps a browser's or password manager's
own generator and save prompt from cross-contaminating a change/reset flow with the account's
existing credential; set it explicitly on every field in the pair, since `autocomplete` has no
purpose-derived default here. `match` (above) is what makes the second field fail validity —
`customError`, with a localized mismatch message — for as long as its value disagrees with the
first field's, referenced here by id.

**Known gotchas:**

- `type="email"`/`type="number"` delegate constraint validation to the internal native `<input>`'s
  own browser-computed `validity` (format/range/step), bridged into this element's own
  `ElementInternals` — not a second hand-rolled regex check. The same bridge carries
  `minlength`/`maxlength`/`pattern`, so `validity` reports the full native set: `valueMissing`,
  `typeMismatch`, `rangeUnderflow`, `rangeOverflow`, `stepMismatch`, `tooShort`, `tooLong`,
  `patternMismatch`, and `badInput`.
- **`tooShort`/`tooLong` also fire for a value assigned from script.** The native flags are raised
  only for a value the _user_ edited, so the component recomputes both from its own `value` and ORs
  them in; `el.value = <over-length>` reports `tooLong` rather than silently submitting. Lengths
  count UTF-16 code units, matching the native control (one emoji counts as two). `patternMismatch`
  needs no such handling — the platform applies `pattern` to script-assigned values already.
  `validationMessage` is the browser's own localized message when the native input flagged the
  value, and the localized `valueInvalid` string when only the script-value check did.
- An empty value is never `tooShort` and never a `patternMismatch` — both native constraints skip
  the empty string, and `required` is what rejects it.
- **The `password-toggle` button is opt-in as of 8.0.0.** A bare `type="password"` now ships no
  toggle at all, and the `password-toggle` part is absent from the shadow tree with it — a
  `::part(password-toggle)` rule, or a test that queries for it, silently matches nothing until the
  attribute is set. The toggle never renders for a non-password `type`, opted in or not.
- **`type="number"` no longer hides the native spin buttons on its own.** Set
  `without-spin-buttons` (or use `<lr-number-input>`, which defaults it to `true` and draws its own
  stepper pair) to get the previous rendering back.
- `showPicker()` swallows every platform failure by design, so it returns without telling you the
  picker didn't open. Don't build a flow that assumes a picker is now on screen.
- `stepUp()`/`stepDown()` are silent — they emit no `input`/`change`. Emit your own, or drive the
  value through a real user affordance, if downstream state depends on those events.
- **A `match` id reference resolves in this element's own root, not the whole document.** Two
  fields inside two different shadow roots (a confirm field composed by one component, the field it
  should match composed by an unrelated one) must pair through a direct element reference
  (`confirm.match = passwordEl`) instead of an id string — exactly like every other idref this
  library resolves, `aria-describedby` included. An id that does not resolve at all (a typo, or an
  element removed later) is inert rather than a permanent block on submission: `match` stops
  applying, it does not fail closed.

**Additional API surface:**

- `click()` — Activates the internal input.

## `lr-number-input`

A numeric field with the complete `lr-input` form, validation and native-editing contract, plus its
own increment/decrement stepper pair. Its constructor and `connectedCallback()` both force
`type = 'number'`; all inherited `lr-input` form and editing APIs remain available.

`stepUp()` and `stepDown()` use the current `value`, `step`, `min`, and `max` properties in the same
synchronous call, including changes made immediately beforehand. They preserve native step alignment
and bounds, update form submission silently, and remain no-ops before the native input has rendered
or while disabled/readonly. Native `step="any"` remains a non-steppable no-op.

Changing own `disabled` from true to false in the same task that disables an ancestor fieldset keeps
the native editing control effectively disabled. The enabled first-legend exception and explicit
own-disabled state retain their native meaning; validity and form submission follow the effective
disabled state.

**Inherits:** all public surface from `lr-input`.

The inherited `--lr-input-*` theme inputs keep `lr-input`'s ancestor-theme precedence; the number
subclass does not redeclare them on its host.
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`.

**Properties:** `size` (`2xs`…`xl`), `appearance`, `pill`, `autofocus`, `placeholder`, `readonly`,
`label`, `hint`, `errorText`
(`error-text`), `accessibleLabel` (`aria-label`), `autocomplete`, `spellcheck`, `autocapitalize`,
`autocorrect` (boolean readback; accepts `boolean | 'off' | 'on'` writes), `inputMode`
(`inputmode`), `enterKeyHint` (`enterkeyhint`), and
`min`/`max`/`step` (the native numeric constraint validation), all inherited from `lr-input` with
identical meaning. This component changes the mapped defaults to `appearance='outlined'`,
`inputMode='numeric'`, and `step=1`. `clearable` (and its `with-clear` spelling),
`passwordVisible` (`password-visible`), and `minlength`/`maxlength`/`pattern` are inherited but
inert — see gotchas. Also inherited from `lr-input`, with identical meaning:
`defaultValue: string = ''` (attribute `value`, reflected) — the reset value; and
`customError: string | null = null` (attribute `custom-error`, reflected) — a consumer-supplied
validation message. `getForm()` returns the browser-resolved form owner, including an external
owner selected by `form`; `setCustomValidity(message)` sets or clears `customError` without
discarding intrinsic validity; `resetValidity()` clears only that consumer layer and recomputes
the current intrinsic constraints, leaving `value`/`defaultValue` and prior interaction state
unchanged.

Stepper switches:

- `steppers: boolean = true` (attribute `steppers`, reflected) — renders the increment/decrement
  pair inside the control row. It **defaults to `true`**, so it needs a custom converter to switch
  off: write `steppers="false"` as an attribute, or `.steppers=${false}` as a property binding.
  A bare `?steppers=${false}` (or removing the attribute in a framework that models booleans by
  presence) cannot reset a `true`-defaulting property.
- `withoutSpinButtons: boolean = true` (attribute `without-spin-buttons`, reflected) — the same
  knob `lr-input` exposes, but **defaulted the other way here** (`lr-input`'s default is `false`),
  so the component's own steppers are never shown alongside the browser's built-in spin buttons.
  It is `true`-defaulting too, so `without-spin-buttons="false"` / `.withoutSpinButtons=${false}`
  brings the native pair back. The two properties are independent: `steppers="false"
without-spin-buttons="false"` returns the field to a plain native `<input type="number">`.
- `withoutSteppers: boolean = false` (attribute `without-steppers`, not reflected) — the positive
  upstream spelling for hiding the custom pair. It does not invert `steppers`: either
  `without-steppers` or `steppers="false"` hides the same controls, and both unset leaves them on.

Each stepper drives the inherited `stepUp()`/`stepDown()`, so `min`/`max` clamping and decimal
handling stay the platform's. Unlike those silent methods, a stepper **click** is a user edit and
emits the same `input`/`lr-input`/`change`/`lr-change` sequence typing would — but only when the
value actually moved, so clicking at a bound is inert rather than emitting a no-op edit. Clicking
also returns focus to the field.

The steppers are deliberately outside the tab order (`tabindex="-1"`), like the native spin buttons
they stand in for: a keyboard user steps the value with ArrowUp/ArrowDown on the field itself, which
the native `<input type="number">` already handles, so making them tab stops would add two stops per
field for no new capability. Each carries a localized accessible name and the shared
`--lr-icon-button-size` hit-area floor in both axes, and both are disabled while the field is
`disabled` or `readonly`.

**Events:** `input`/`change` (native-style, composed), `lr-input`/`lr-change`
(`detail: { value }`), `focus`/`blur` (re-dispatched bubbling + composed from the internal native
input), and `lr-clear`
(inherited, never fired here). The inherited `lr-invalid` (no detail) fires when a validity check
finds the input invalid. The internal native `beforeinput` is cancelable, bubbles, and composes;
calling `preventDefault()` on the host vetoes the edit before `value` changes. It also inherits `lr-input-settled` (`detail: { value }`, non-cancelable), which fires once
`debounce` ms after the last keystroke when `debounce` is set; see `lr-input`'s own `debounce`
entry for the flush and cancellation rules.

**Slots:** `label`, `hint`, `error`, `start`, `end`, `decrement-icon`, and `increment-icon`.

**CSS parts:** `form-control`, `form-control-label`, `base` (compatibility name for the
control row; use `number-input`), `number-input` (the numeric control row; it is the same node as
`base` and the inherited `input-wrapper` part), `input-wrapper`, `input`, shared `stepper`, mapped
`stepper-decrement` / `stepper-increment`, and compatibility `stepper-down` / `stepper-up` (the two
stepper buttons, rendered only while both switches permit them; they sit side by side
between the built-in clear/password actions and the `end` adornment, and each one rotates the shared
chevron glyph — `[part="stepper-up"] > svg` a quarter turn one way, `[part="stepper-down"] > svg` the
other — so a consumer replacing the button chrome keeps the same up/down orientation), `start`, `end`,
`hint`, `error`, plus the inherited `clear-button` and `password-toggle`, neither of which this
component ever renders.

**Themeable custom properties:** inherited from `lr-input`, identical in meaning —
`--lr-input-control-min-height`, `--lr-input-control-height`, `--lr-input-padding-block`,
`--lr-input-padding-inline`, `--lr-input-font-size`, `--lr-input-gap`, `--lr-input-radius`,
`--lr-input-fill`, and `--lr-input-border-color` (all
but `--lr-input-control-height` and `--lr-input-gap` follow the active `size` tier;
`--lr-input-control-height` stays undeclared until you pin an exact
row height, `--lr-input-fill`/`--lr-input-border-color` swap per `appearance` instead of per tier,
and `--lr-input-gap` — like `--lr-button-gap` — is constant across the ladder). The steppers take their font size from `--lr-input-font-size` and their
minimum box from `--lr-icon-button-size`.
The inherited `--lr-input-focus-border-color` and four `--lr-input-action-*` hooks also apply to
the numeric row and its steppers, so their state paint can be isolated from other form controls.
The exact-320px RTL story keeps long label/hint copy and both fixed-size steppers within the host.

```html
<lr-number-input
  label="Quantity"
  min="0"
  max="99"
  step="1"
  value="1"
></lr-number-input>
<!-- A bare numeric field: no steppers, and the browser's own spinners back: -->
<lr-number-input
  label="Quantity"
  steppers="false"
  without-spin-buttons="false"
></lr-number-input>
<script type="module">
  import "@aceshooting/lyra-ui/components/forms/input/number-input.js";
</script>
```

**Known gotchas:**

- **`steppers` and `without-spin-buttons` both default to `true` here.** Only the literal string
  `"false"` parses as `false`; every other attribute value — including an empty one, and including
  _removing_ the attribute — parses as `true`. So `?attr=${false}` and a removed attribute cannot
  reset either; use the `="false"` attribute value or the `.prop=${false}` property binding. The
  two also serialize differently when reflected: `steppers` is absent while `true` and appears as
  `steppers="false"` while `false`, whereas `without-spin-buttons` appears empty while `true` and is
  absent while `false`. Assert the rendered result, not the attribute's presence.
- `clearable`/`clear-button`/`lr-clear` are inert: the clear action only renders for
  `type="text"`/`"search"`. `password-visible`/`password-toggle` are likewise inert, since the
  toggle only renders for `type="password"`. `minlength`/`maxlength`/`pattern` are inert too — the
  platform ignores all three on `type="number"`; use `min`/`max`/`step` instead.
- `type` is re-forced to `number` on every connect, but a later `el.type = 'text'` on a connected
  element is not reverted — use `lr-input` when the type has to change.

## `lr-time-input`

A locale-aware segmented field and column picker mirroring `wa-time-input`. Its wire and submitted
value is always timezone-free, 24-hour ASCII: `HH:mm`, or `HH:mm:ss` when seconds are visible.
Locale changes segment order, separators, digits, and day-period labels — never the wire value.
Typing accepts both ASCII digits and the active locale's digit glyphs, and validation-message
bounds use the same localized time presentation rather than exposing the ASCII wire form.
An incomplete draft remains visible for editing but submits `''` and raises `badInput`.
The clear/expand actions sit directly in the shared outer height ladder: compact tiers grow only
enough for their hit targets, while `l` and `xl` retain the shared 48px and 56px heights rather
than adding outer padding around the buttons.

Removing `label` or `hint` safely omits that content while retaining native `null` property
readback. Explicit empty strings remain empty; later supplied text renders normally.

**Properties:**

- `value: string` (also accepts a `Date` or `null` when assigned) — strict `HH:mm`, optional
  `:ss`/`.sss`; `Date` reads local clock fields without timezone conversion. Invalid strings and
  `null` normalize to `''`. `valueAsNumber` is milliseconds since midnight (`NaN` while blank),
  and `valueAsDate` applies the clock fields to today's local date (`null` while blank). Both are
  settable, like the native `<input type="time">` properties they mirror: assigning `valueAsNumber`
  sets `value` from the same scale, and out-of-range or non-finite figures clear the field rather
  than wrapping into a different time; assigning `valueAsDate` reads the same local clock fields
  back off the Date, so it round-trips with the getter, and `null`/an invalid Date clears. Both
  assignments are silent, again like the native properties.
- `defaultValue`, `name`, `form`, `disabled`, `required`, `customError`, `getForm()`,
  `checkValidity()`, `reportValidity()`, `setCustomValidity()`, and `resetValidity()` use the shared form-control
  contract. Reset restores the current declarative `value` default; `readonly` remains focusable
  and submits but cannot be edited. `resetValidity()` clears only consumer custom validity and
  restores the current intrinsic time constraints; it leaves the value/default and interaction
  state unchanged.
- `min = ''`, `max = ''` accept the same canonical time syntax. `min <= max` is an ordinary
  closed range; `min > max` is an overnight range (for example `22:00` through `06:00`).
- `step: number | 'any' = 60` is seconds. A numeric value below 60 reveals seconds. Numeric
  validation follows native time step-base precedence: valid `min`, otherwise the current reset
  default (`defaultValue`/the `value` content attribute), otherwise midnight. Picker options are
  projected from the complete valid-time grid, so offset, hourly, multi-hour, bounded and overnight
  grids expose only reachable values and retain a selected valid value. `'any'` disables step
  mismatch and exposes the unrestricted segment vocabulary.
- `hourFormat: 'auto' | '12' | '24' = 'auto'` (`hour-format`) overrides the locale's hour cycle.
- `appearance: 'accent' | 'filled' | 'outlined' | 'filled-outlined' | 'plain' = 'outlined'`,
  `size` (shared `2xs`…`xl` ladder and `small`/`medium`/`large` aliases), and `pill = false`.
- `label = ''`, `hint = ''`, `errorText = ''` (`error-text`), `withLabel = false`
  (`with-label`), and `withHint = false` (`with-hint`) provide complete form chrome. A host
  `aria-label` wins for the internal editing surface's accessible name.
- `open = false`, `placement = 'bottom-start'`, and `distance = 0` control the picker.
  `show()` / `hide()` return `Promise<void>` and settle after the matching `lr-after-*` event.
- `withClear = false` (`with-clear`) adds a localized clear action. `withNow = false`
  (`with-now`) adds a localized Now footer unless the `footer` slot replaces it.
- `autocomplete = ''` is forwarded to a visually hidden, nameless native time input used only as
  the browser autofill seam; the FACE host remains the sole submitted control.

**Methods:** `focus(options?)`, `blur()`, and `click()` delegate to the active segment; `focus()` and
`click()` are synchronous no-ops while directly or fieldset disabled, so they cannot create focus
events from a removed tab stop. If a controlled locale, `hourFormat`, or `step` change removes the
segment that currently owns focus, the first surviving segment receives focus after the new pattern
renders. A format change never reclaims focus from another control. `show()` and `hide()` control the
picker, while its form methods are described above. Disconnecting force-closes without a veto and
reconnects with `open`, its attribute, ARIA, popup visibility, and `:state(open)` all closed. A
visible incomplete draft retains its segments, digit buffer, empty submitted value, and `badInput`
state across detach/adoption/reconnect.

**Keyboard:** only one segment is in the tab order. Digits fill the active segment and advance when
no further digit can be accepted; Left/Right moves in locale order and reverses under RTL;
Up/Down steps, Home/End selects the segment edge, and Backspace/Delete clears the segment.
Pasting a canonical time replaces the full value as one edit. Alt+ArrowDown opens the picker.
Inside a picker column, one enabled option is tabbable; ArrowUp/ArrowDown rove, Home/End jump to
the bounds, and Enter/Space activate the focused native option button. Disabled controls project
`disabled` and `tabindex=-1` to every picker option.
`readonly` keeps navigation and popup browsing but blocks commits; `disabled` removes the tab stop,
popup, validation, and form submission.

**Events:** native `input` on user edits and native `change` on a complete commit; compatibility
aliases `lr-input` / `lr-change` carry `{ value }`. `focus` / `blur` cross the shadow boundary once.
`lr-clear` follows a clear. Cancelable `lr-show` / `lr-hide`
precede popup state changes; `lr-after-show` / `lr-after-hide` follow motion settlement.
`lr-invalid` follows a failed validity check.
The hidden native autofill seam treats an intentional empty `input` followed by `change` as a
single clear transaction, emitting `input`, `lr-input`, `change`, then `lr-change` exactly once.

**Slots:** `label`, `hint`, `error`, `start`, `end`, `clear-icon`, `expand-icon`, and `footer`.

**CSS parts:** `form-control`, `form-control-input`, `form-control-label label` (same node),
`base time-input input-wrapper` (same node), `input`, `segment`, `segment-literal`, `start`, `end`,
`clear-button`, `expand-button`, `expand-icon`, `popup`, `columns`, `column`, `column-item`,
`column-item-selected`, `now-button`, `hint`, and `error`.
Each `column` is a block-axis scroll container and explicitly clips inline overflow, so an
undersized `--column-width` cannot introduce a second scrollbar.
The label/hint/error chrome wraps unbroken localized content within the host, while `start`/`end`
adornments shrink and ellipsize. The exact-320px RTL story keeps that copy, the seconds segments,
fixed-size actions, and the open picker contained.

`error` is ordinary visible validation text referenced by the segmented input through
`aria-describedby`, not a shadow `role="alert"`. Native `reportValidity()`/focus feedback therefore
has one description path instead of being duplicated by a second live-region announcement.
The group and every spinbutton expose explicit stateful `aria-invalid`: visible property/slotted
error chrome makes it `"true"` immediately, as does intrinsic/custom invalidity after interaction;
otherwise each owner explicitly exposes `"false"`.
Every spinbutton renders explicit `aria-required="true"` or `"false"`. While required, the
segmented `role="group"` also acquires a localized visually-hidden requiredness description without
overwriting its existing hint/error relationship; removing `required` releases only that text.

**Custom states:** `blank`, `disabled`, and `open`, plus the shared validity states.

**The required marker.** `required` with a non-empty `label` paints the library's shared marker on
the `form-control-label` node — the one `::after` rule described under "The required-field marker"
above, not a copy of it, so `--lr-form-control-required-content`,
`--lr-form-control-required-color` and `--lr-form-control-required-offset` retune or suppress it
here exactly as they do on `lr-input`. With no label text the part is hidden and no glyph is
painted.

**Themeable custom properties:** `--lr-time-input-gap` (outer segment/adornment/action gap,
default `--lr-form-control-gap`) and `--lr-time-input-radius` (outer row radius, default
`--lr-form-control-radius`, or `--lr-radius-pill` with `pill`) remain undeclared on the host, so an
ancestor theme wrapper or direct-host value overrides those fallbacks. Also available are
`--lr-time-input-border-color`, `--lr-time-input-fill`, and `--lr-time-input-color` for the
appearance surface; `--lr-time-input-focus-border-color`;
`--lr-time-input-segment-hover-bg`, `--lr-time-input-segment-active-bg`, and
`--lr-time-input-segment-focus-bg`; `--lr-time-input-action-color`,
`--lr-time-input-action-hover-color`, `--lr-time-input-action-hover-bg`, and
`--lr-time-input-action-active-bg`; and `--lr-time-input-column-hover-bg`,
`--lr-time-input-column-active-bg`, `--lr-time-input-column-selected-bg`,
`--lr-time-input-column-selected-color`, `--lr-time-input-column-selected-font-weight`,
`--lr-time-input-column-selected-hover-bg`, and `--lr-time-input-column-selected-active-bg`.
Outer row height is a pair, not one knob: `--lr-time-input-control-min-height` (default
`var(--lr-form-control-height)`) is the row's height **floor**, taken from the active `size` tier of
the shared form-control ladder, so a time field is exactly as tall as an `lr-input` or `lr-select`
at the same tier; `--lr-time-input-control-height` is **unset by default** and, given a length,
pins the row to exactly that height — flooring and capping it at once, which is what pixel-matches
an `lr-date-input` sharing the same toolbar. Leaving `--lr-time-input-control-height` unset keeps
`--lr-time-input-control-min-height` working as a floor only, and because the component never
declares `--lr-time-input-control-height` on its own host it can be set from an ancestor or an
outer-tree rule just as well as inline on the element.
Every state hook falls back to the exact semantic token or color mix used previously, and remains
undeclared on the host so ancestor themes work. The upstream-compatible `--column-item-height`
(default `calc(var(--lr-size-1em) * 2.25)`) and `--column-width`
(default `calc(var(--lr-size-1em) * 3)`) retain their component-font-relative sizing through the
Lyra `--lr-size-1em` token. `--show-duration` and `--hide-duration` similarly use Lyra
duration-token fallbacks. Each `column` also honors the opt-in theme-level
`--lr-theme-scrollbar-width`/`--lr-theme-scrollbar-gutter` hooks (defaults `thin`/`auto`, matching
its previous unconditional `scrollbar-width: thin`) — set either on `:root` or any ancestor for one
declaration to retheme every internal scroll container in the library.

The shared field halo `--lr-form-control-focus-shadow` (default `none`) paints a `box-shadow` while
this control is focused or open — one name for every field-shaped control in the library, so a halo
is configured once instead of per component. It is additive: the focus outline and the
`--lr-time-input-focus-border-color` edge are the accessibility answer to focus and are never
replaced by it.

The `popup` panel is a floating surface and paints from the **shared overlay-surface family**
(16.0.0): `--lr-overlay-surface`, `--lr-overlay-border` (default `var(--lr-color-border)`),
`--lr-overlay-radius` (default `var(--lr-radius)`) and `--lr-overlay-shadow-anchored` (default
`var(--lr-shadow-m)`). None is declared on `:host`, so one declaration on `:root` — or on any
ancestor, to scope it — retints this panel together with every other floating surface in the
library. One deliberate difference from the rest of the family: `--lr-overlay-surface` defaults here
to `var(--lr-color-surface-raised)` rather than the family's own
`var(--lr-color-surface-overlay)`. The picker is a dense grid of time cells dropped from a field,
and the raised tone is what separates it from the field's fill — `--lr-color-surface-overlay`
resolves to the plain page surface in light mode and would erase that separation, while in dark
mode the raised tone is already distinct from the page, so this panel never had the
reads-as-a-hole problem the family exists to fix. Setting `--lr-overlay-surface` still repaints it
along with every other popup.

`--lr-positioning-strategy` (16.0.0) — the `popup` panel reads this same cascading
`absolute`/`fixed` override documented on `<lr-popover>` when it is (re)positioned, falling back to
its own `fixed` default when nothing is set. There is no per-instance `positioning-strategy`
property on `<lr-time-input>`; set the custom property on `:root`, a theme, or one clipping
ancestor to change every unset time input beneath it.

```html
<lr-time-input
  label="Start time"
  value="09:30"
  with-clear
  with-now
></lr-time-input>
<lr-time-input label="Precise time" step="15" value="09:30:15"></lr-time-input>
<script type="module">
  import "@aceshooting/lyra-ui/components/forms/input/time-input.js";
</script>
```

## `lr-native-time-input`

The Lyra 7 browser-native time field preserved under an explicit tag. It extends `lr-input`,
forces its internal native input to `type="time"` on construction and reconnect, and retypes
`min`/`max` so time-shaped attributes such as `09:00:30` are forwarded verbatim instead of parsed
as numbers. Use it when the browser/OS picker is preferred; new `wa-time-input` migrations should
use the segmented `lr-time-input` above.

`stepUp()` and `stepDown()` use the current `value`, `step`, `min`, and `max` properties in the same
synchronous call, including changes made immediately beforehand. They preserve native step alignment
and bounds, update form submission silently, and remain no-ops before the native input has rendered
or while disabled/readonly. Native `step="any"` remains a non-steppable no-op.

Changing own `disabled` from true to false in the same task that disables an ancestor fieldset keeps
the native editing control effectively disabled. The enabled first-legend exception and explicit
own-disabled state retain their native meaning; validity and form submission follow the effective
disabled state.

**Inherits:** all public surface from `lr-input`.

All `lr-input` properties, form methods, events, label/hint/error/start/end slots, parts, and theme
properties apply. `step` is native seconds; `showPicker()`, `stepUp()`, and `stepDown()` keep their
native-wrapper behavior. The control row carries `base input-wrapper time-input` part tokens on one
node. Its native picker UI and AM/PM presentation are browser-owned and intentionally unstyled.
The inherited `--lr-input-*` theme inputs therefore remain configurable from an ancestor theme
wrapper without being shadowed by the subclass. Among those inherited properties and methods:
`defaultValue: string = ''` (attribute `value`, reflected) is the reset value, and
`customError: string | null = null` (attribute `custom-error`, reflected) is a consumer-supplied
validation message. `getForm()` returns the browser-resolved form owner, including an external
owner selected by `form`; `setCustomValidity(message)` sets or clears `customError` without
discarding intrinsic validity; `resetValidity()` clears only that consumer layer and recomputes
the current intrinsic constraints, leaving `value`/`defaultValue` and prior interaction state
unchanged.

**Events:** native-style `input` and `change`; bubbling, composed `focus` and `blur` bridges; the
`lr-input` / `lr-change` aliases with `{ value }`;
`lr-clear` after the inherited clear action; and `lr-invalid` when a validity check fails. It also inherits `lr-input-settled` (`detail: { value }`, non-cancelable), which fires once
`debounce` ms after the last keystroke when `debounce` is set; see `lr-input`'s own `debounce`
entry for the flush and cancellation rules.

**CSS parts:** all inherited `lr-input` parts, plus `time-input` on the same control-row node as
`base` and `input-wrapper`.

```html
<lr-native-time-input
  label="Start time"
  min="09:00"
  max="17:00"
  value="09:30"
></lr-native-time-input>
<script type="module">
  import "@aceshooting/lyra-ui/components/forms/input/native-time-input.js";
</script>
```

---

## `lr-phone-input`

A form-associated, country-aware telephone field. The submitted `value` is either canonical E.164
(for example `+352621123456`) or `''` while the editable input is empty, incomplete, or invalid.
Numbering-plan metadata and national formatting stay outside Lyra's base bundle: supply a
synchronous `LyraPhoneNumberAdapter`, or lazily create one from a `libphonenumber-js`-compatible module
with `loadLibphonenumberAdapter()`. Without an adapter, already-international E.164 input still
normalizes and validates; national input remains editable with `incomplete` validity. The loader
returns its discovered country catalog as a frozen array of frozen records.

For `default-country`, removing the attribute safely uses the existing country fallback while
leaving property   readback at native `null`; an existing selected country remains selected.
Explicit empty   strings remain empty, and later valid default-country values work normally.

Host `aria-describedby` references resolve onto the telephone input before its local hint/error
guidance. References track missing IDs, target replacement, removal/reinsertion, reconnect, and
adoption. The country selector keeps its separate existing accessible-name contract.

The country selector keeps the real native `<select>` (localized full country names in its popup,
native mobile pickers, keyboard type-ahead) but stretches it invisibly over a compact decorative
trigger showing the selected alpha-2 code plus a design-system chevron — long country names never
clip the closed control and the adjacent calling code isn't repeated. With `flags`, the trigger
also shows the selected country's `<lr-flag>`.

Public `--lr-phone-input-*` theme inputs stay undeclared on the host, so an ancestor theme wrapper
can override size and pill fallbacks; a value set directly on the element still wins.
The native country-selector target retains the shared icon-button hit floor, and the wrapper uses
the same rendered action-height ladder as input, number-input, and segmented time-input.

**Types:**

```ts
type LyraPhoneNumberStatus = "empty" | "incomplete" | "invalid" | "valid";

interface LyraPhoneCountry {
  readonly code: string; // ISO 3166-1 alpha-2
  readonly callingCode: string; // no leading "+"
  readonly label?: string; // overrides Intl.DisplayNames
}

type LyraPhoneNumberParseResult =
  | {
      status: "empty" | "incomplete" | "invalid";
      formatted?: string; // best-effort editable display text
      country?: string; // detected ISO alpha-2 code
    }
  | {
      status: "valid";
      e164: string; // required and E.164-shaped on the only successful branch
      formatted?: string;
      country?: string;
    };

interface LyraPhoneNumberAdapter {
  readonly countries?: readonly LyraPhoneCountry[];
  parse(input: string, country?: string): LyraPhoneNumberParseResult;
}
```

**Properties:**

- `value: string = ''` — canonical E.164 form/submission value. A programmatic assignment is parsed
  and normalized synchronously but emits no user event.
- `name: string = ''`, `disabled: boolean = false`, `required: boolean = false` — native-like
  form-control properties supplied by `FormAssociated`; inherited disabled fieldsets are included
  through `effectiveDisabled`.
- `defaultValue: string = ''` (attribute `value`) is the reset target, and `customError: string |
null` (attribute `custom-error`) carries a consumer-supplied validation message.
- `adapter?: LyraPhoneNumberAdapter` (attribute: false) — synchronous numbering-plan
  parser/formatter. No metadata implementation is imported by the component itself. Runtime
  results are validated exhaustively: unknown statuses, hostile getters, wrong optional-field
  types, and a `valid` result without E.164 all fail closed to `invalid`.
- `countries?: readonly LyraPhoneCountry[]` (attribute: false) — `undefined` discovers
  `adapter.countries`; every supplied array, including `[]`, is authoritative. Rows are copied and
  validated at the boundary; a row without a two-letter code or 1–3 digit calling code, a duplicate,
  or a throwing getter is skipped without hiding later valid rows. Explicit and adapter-provided
  catalogs are bounded to 512 rows and captured as frozen owned snapshots when assigned.
- `defaultCountry: string = ''` (attribute `default-country`) — selected when `country` has not been
  set explicitly.
- `flags: boolean = false` (reflected) — show the selected country's flag in the country trigger as
  `<lr-flag variant="compact" aria-label="">` (decorative; the native select already announces the
  country name). The `<lr-flag>` element definition is registered lazily the first time any
  `lr-phone-input` enables this, so nothing flag-related is bundled while it stays off. Flag
  _artwork_ still follows the standalone `<lr-flag>` contract: install the optional
  `@aceshooting/lyra-flags` peer and import
  `@aceshooting/lyra-ui/components/media/flag/flag-peer.js` once; without that registration the
  trigger simply omits the image. The open popup list stays text-only — a native `<option>` cannot
  contain elements.
- `size: LyraSize = 'm'` (reflected — the shared control ladder, so both `2xs`/`xs`/`s`/`m`/`l`/`xl`
  and `small`/`medium`/`large` are accepted; scales input padding, font size, and wrapper
  min-height; `size="s"` shares its outer control height with `lr-input`, `lr-select`, and
  `lr-combobox` without part overrides)
- `pill: boolean = false` (reflected) — rounds the field's corners to a full pill, mirroring
  `lr-input`'s own `pill`. It changes the private radius default to `--lr-radius-pill`, and the
  country trigger's leading corners follow; an inherited or direct `--lr-phone-input-radius`
  remains authoritative
- `country: string` — current uppercase ISO alpha-2 selection; falls back to `defaultCountry`, then
  the first explicit/adapter country. A requested or adapter-detected country absent from the
  effective catalog resolves to that same valid fallback before property, trigger, native select,
  calling-code, and parser projection. An empty effective catalog resolves to `''`. Changing the
  country reparses the editable number.
- `label: string = ''`, `hint: string = ''`, `errorText: string = ''` (attribute `error-text`) —
  visible form-field chrome; each has a matching named slot.
- `placeholder: string = ''` — forwarded to the native telephone input.
- `spellcheck: boolean = true`, `autocapitalize: string = ''`, `autoCorrect: string = ''`
  (attribute `autocorrect`) — forwarded to the internal telephone input's own `spellcheck`/
  `autocapitalize`/`autocorrect`; `spellcheck="false"` is parsed as `false` via a string-aware
  converter (Lit's default presence-based boolean converter would otherwise treat any attribute
  value, including the literal string `"false"`, as `true`).
- `accessibleLabel: string | null = null` (attribute `aria-label`) — forwarded to the internal
  telephone input. Name precedence is host `aria-label`, `phoneLabel`, visible `label`, then
  `placeholder`, and finally a localized generic "Phone" name, so a bare `<lr-phone-input>` with
  none of them set never reaches the accessibility tree unnamed. (The visible label part cannot
  stand in for it: it carries the native `hidden` attribute while there is no label text, which
  removes it from the accessibility tree entirely.)
- `phoneLabel: string = ''` (attribute `phone-label`) — explicit accessible-name override for the
  native telephone input.
- `countryLabel: string = 'Select'` (attribute `country-label`) — country-selector accessible name.
  Omitted copy uses the localized `select` message. Explicit text, including `'Select'` and `''`,
  wins over locale strings. Removing the attribute restores the declared `'Select'` property
  readback and resumes localization.
- `incompleteText: string = 'This phone number is incomplete.'` (attribute `incomplete-text`) —
  validation message for dial-like input that can still become valid with more digits. Omitted
  copy uses the localized `phoneInputIncomplete` message. Explicit nonempty text, including the
  English default, wins verbatim; an empty override retains the localized native error reason.
  Removing the attribute restores its declared English property default and resumes localization.
- `invalidText: string = 'The value is invalid.'` (attribute `invalid-text`) — completed-invalid
  validation message. Omitted copy uses localized `valueInvalid`; explicit nonempty text,
  including the English default, wins verbatim. An empty override retains the localized native
  error reason. Removing the attribute restores its declared English property default and resumes
  localization.
- `autocomplete: string = 'tel'`, `inputmode: 'tel'|'numeric'|'text' = 'tel'`,
  `enterkeyhint: string = ''` — forwarded to the internal `<input type="tel">`.
- `readonly: boolean = false` (reflected) — forwards to the native telephone input, locks the
  country selector and all user edit handlers, and bars validation while retaining focus,
  selection/copying, canonical form value, and submission.
- `autofocus: boolean = false` (reflected) — forwarded to the actual native telephone input; it is
  never stranded on the non-focusable host.
- readonly `input: HTMLInputElement | undefined` — the internal native telephone input.
- readonly `inputValue: string` — editable formatted/partial text, which remains available even when
  canonical `value` is `''`.
- `selectionStart`, `selectionEnd`, and `selectionDirection` — native selection getters/setters
  forwarded to the telephone input
- readonly `phoneStatus: LyraPhoneNumberStatus` — current parse state. The host also reflects it through
  `data-phone-status`.
- readonly `form`, `labels`, `validity`, `validationMessage`, `willValidate`, and
  `effectiveDisabled` — the shared form-associated native-like getters.

**Events:** each text edit emits native `InputEvent` `input` then `lr-input`; telephone-input commit
emits native `Event` `change` then `lr-change`; and a country pick emits both pairs in order:
`input`, `lr-input`, `change`, `lr-change`. Native events carry no custom detail; the aliases carry
`{ value, inputValue, country, valid, status }`.
Internal `focus`/`blur` are relayed once as realm-correct native `FocusEvent`s preserving `relatedTarget`.
`lr-invalid` has no detail and is the one bubbling/composed alias
when native validity fails. Programmatic value writes remain silent.

**Validity:** empty + `required` sets `valueMissing`; incomplete dial-like input sets `badInput`;
completed-invalid input sets `typeMismatch`; valid E.164 input clears all three. Partial or invalid
text remains in `inputValue`/the native input so validation never makes a number impossible to edit,
but its canonical submitted `value` is blank. Native validation feedback is anchored to the
telephone input, not the adjacent country selector.

**Methods:** `focus(options?)`, `blur()`, `select()`, `setSelectionRange()`, and `setRangeText()`
forward to the native telephone input. Range-text edits reparse the number and synchronize the
canonical value, form value, and validity.
`getForm()`, `setFormValue(value)`, `checkValidity()`, and `reportValidity()` come from
`FormAssociated`. `setCustomValidity(message)` sets or clears `customError` without discarding the
control's intrinsic phone-number validity. `resetValidity()` clears only that consumer error and
recomputes the current phone-number constraints; it does not change the editable/canonical value,
the reset default, or prior interaction state.
`form.reset()` restores the original declarative `value` and the default country.

**Slots:** `label`, `hint`, `error`, `country-prefix` (optional visual before the country selector,
such as a consumer-owned `<lr-flag>`; no flag package is imported automatically).

**CSS parts:** `form-control`, `form-control-label`, `input-wrapper`, `country-prefix`, `country`
(the selector region: invisible native select layered over the visual trigger), `country-select`,
`country-trigger` (visible, `aria-hidden` closed-state box), `flag` (the `<lr-flag>`, only with
`flags`), `country-code` (selected alpha-2 code, `data-placeholder` when no country exists),
`expand-icon`, `calling-code`, `input`, `hint`, `error`.

`error` is ordinary visible validation text referenced by the native telephone input through
`aria-describedby`, not a shadow `role="alert"`. Native invalid/focus feedback therefore has one
description path instead of being duplicated by a second live-region announcement.

**The required marker.** `required` with a non-empty `label` paints the library's shared marker on
`[part="form-control-label"]` — the one `::after` rule described above, not a copy of it, so
`--lr-form-control-required-content`, `--lr-form-control-required-color` and
`--lr-form-control-required-offset` retune or suppress it here exactly as they do on `lr-input`.
With no label text the part is hidden and no glyph is painted.

**Themeable custom properties:** `--lr-phone-input-padding-block` (scaled through the shared
form-control padding ladder), `--lr-phone-input-font-size`, and
`--lr-phone-input-control-min-height` (each scaled by `size`), plus `--lr-phone-input-control-height`
to pin an exact input-wrapper height (both floors and caps it — use it for pixel-matching an
`<lr-input>` or `<lr-select>` in the same toolbar row; undeclared by default, leaving the min height
as a floor only). The phone-number input and calling code are deliberately `dir="ltr"`/isolated
because telephone numbers are algorithmic content; surrounding form chrome and the country selector
inherit LTR/RTL and use logical spacing/borders.
The native country selector's hover and press backgrounds are supplemented in forced-colors mode
with dashed/solid `Highlight` outlines, so those states do not collapse when the UA flattens the
background tint to `Canvas`.

**Optional peer deps:** `libphonenumber-js` is declared optional but never imported by Lyra itself.
For full national parsing/formatting, install it in the consuming app and pass it through the
consumer-supplied lazy loader below. Because the import expression lives in consumer code, no
numbering metadata enters a bundle that does not opt in.

```ts
import "@aceshooting/lyra-ui/components/forms/phone-input/phone-input.js";
import { loadLibphonenumberAdapter } from "@aceshooting/lyra-ui/components/forms/phone-input/phone-input.class.js";

const phone = document.querySelector("lr-phone-input");
phone.adapter = await loadLibphonenumberAdapter(
  () => import("libphonenumber-js/min")
);
```

```html
<lr-phone-input
  name="mobile"
  label="Mobile number"
  hint="Used only for account security"
  default-country="LU"
  required
></lr-phone-input>
```

```ts
// Country flags in the trigger (optional): same peer contract as a standalone <lr-flag>.
import "@aceshooting/lyra-ui/components/media/flag/flag-peer.js";
```

```html
<lr-phone-input
  label="Mobile number"
  flags
  default-country="LU"
></lr-phone-input>
```

**Known gotchas:**

- An adapter's `parse()` method is synchronous because it runs on every keystroke. Load any optional
  module first, then assign the resolved adapter. Once an adapter is assigned, exceptions and
  malformed results fail closed to `invalid`; only the no-adapter mode uses the E.164-only fallback.
- A valid adapter result must include an E.164-shaped `e164`; the discriminated result type makes
  that requirement statically visible and runtime normalization prevents malformed success from
  entering form submission.
- Country names use `Intl.DisplayNames` and fall back to the ISO code; set `LyraPhoneCountry.label` for
  a product-specific name. Calling codes are data, not derived by the component.
- The component never imports `@aceshooting/lyra-flags` itself, with `flags` or without. `flags`
  lazily registers only the `<lr-flag>` element; the artwork resolver comes from the consumer's own
  `flag-peer.js` import (plus the installed peer package), so forgetting either shows a flagless
  trigger rather than erroring. `country-prefix` remains available for a fully consumer-owned
  adornment instead.
- The visible trigger (`country-trigger` and everything inside it) is `aria-hidden` by design; the
  layered native select is the accessible control. Don't move interactive content into those parts
  via `::part` styling tricks, and don't expect the flag inside the open popup list — a native
  `<option>` is text-only.

**Additional API surface:**

- `click()` — Activate the internal telephone input unless the form control is effectively disabled.
- `--lr-phone-input-flag-size` — Selected flag size, scaled by `size`.
- `--lr-phone-input-glyph-size` — Country selector glyph size, scaled by `size`.
- `--lr-phone-input-gap` — Country-trigger child gap. Default: `var(--lr-space-xs)`.
- `--lr-phone-input-radius` — Input-wrapper corner radius. Default: `var(--lr-radius)`.
- `--lr-phone-input-focus-border-color` — Focused row border color. Default: `var(--lr-color-brand)`.
- `--lr-phone-input-fill` — Resting input-row background, public since 16.0.0. Default:
  `var(--lr-color-surface)`.
- `--lr-phone-input-border-color` — Resting input-row border color. Default:
  `var(--lr-color-border)`. The invalid and focused states keep their own hooks and still win
  over it.
- `--lr-form-control-focus-shadow` — The shared field halo, painted as a `box-shadow` while the
  row holds focus. Default: `none`. Additive — the focus outline and the focused border are
  never replaced by it.
- `--lr-phone-input-invalid-border-color` — Invalid row border color. Default: `var(--lr-color-danger)`.
- `--lr-phone-input-country-hover-bg` — Country trigger hover background. Default: `var(--lr-color-brand-quiet)`.

---

## `lr-time-range`

A two-handle brush/scrubber over a numeric domain (no date logic — callers map their own time axis
onto `[min, max]`). Form-associated (`static formAssociated = true`, via `ElementInternals`): an
ancestor `<fieldset disabled>` disables both handles and every preset button through an internal
`effectiveDisabled` getter, the same way it would a native `<input>`, without ever mutating the
consumer-facing `disabled` property/attribute itself.
The `base` part is an accessible `role="group"`: a non-empty host `aria-label` names the two-handle
aggregate. A native external `<label for>` remains available through `labels`, but it does not cross
into the shadow-root group. `startLabel` and `endLabel` continue to name the individual sliders.

Only the primary mouse button starts seeking or dragging. Right and middle presses leave the range
and input/change events untouched. Touch and pen gestures keep their existing behavior, including
concurrent pointer support; pointer cancellation and capture cleanup retain their existing
semantics.

**Properties:**

- `min: number = 0`
- `max: number = 100`
- `start: number = 0`
- `end: number = 100`
- `step: number = 1`
- `size: '2xs' | 'xs' | 's' | 'm' | 'l' | 'xl' | 'small' | 'medium' | 'large' = 'm'` (reflected) — visual size; proportionally
  scales the handle, track, and preset buttons via a single `--lr-time-range-size-scale` multiplier
  (not pixel-matched to `lr-input`'s row-height scale — this component's own dimensions aren't on
  that ladder); `small`/`medium`/`large` are exact aliases for `s`/`m`/`l`, and the drag hit-area
  never shrinks below 24px (WCAG 2.5.8)
- `disabled: boolean = false` (reflected)
- `startLabel?: string` (attribute `start-label`) — caller-owned `aria-label` override for the start
  handle; absence resolves localized `rangeStart` (`"Range start"` in English), while every
  supplied string — including `"Range start"` and `""` — remains literal
- `endLabel?: string` (attribute `end-label`) — equivalent override for the end handle; absence
  resolves localized `rangeEnd` (`"Range end"` in English)
- `valueFormatter?: TimeRangeValueFormatter` (attribute: false) — maps each finite, clamped
  `aria-valuenow` to optional human-readable `aria-valuetext`; called as
  `(value, handle: TimeRangeHandle)`, where `TimeRangeHandle = 'start' | 'end'`. The formatter may
  return `string | null | undefined`; a nullish result omits `aria-valuetext` for that handle.
  Leaving the property unset preserves the numeric-only contract
- `presets: readonly TimeRangePreset[] = []` (attribute: false) — readonly `TimeRangePreset {
label: string; start: number; end: number; id?: string }`; a bounded frozen snapshot of optional
  discrete presets (e.g. "Last 7 days") rendered as a
  `[part="presets"]` button row above the track — purely additive, the continuous brush is
  unaffected and both interaction modes coexist; picking one sets both handles and emits the same
  native/prefixed input and change sequences a committed drag or keyboard step would. Preset
  endpoints are clamped and ordered once, and that same normalized pair drives both application
  and `aria-pressed`/`data-active` projection. The optional `id` is a caller-owned
  correlation key copied into the snapshot verbatim and never read by the control itself; an
  untagged preset is unaffected
- `appliedPreset: TimeRangePreset | undefined` (read-only, attribute: false) — the frozen
  `presets` snapshot whose button produced the current range. Preset application updates this
  identity before its synchronous event sequence, so it can be read inside `input`/`change` or
  `lr-input`/`lr-change` handlers. It remains `undefined` before a preset is selected and is
  cleared by a real manual handle move, a controlled endpoint change away from that preset, a
  preset-collection replacement, or a form reset. Numeric equality never infers identity; no-op
  endpoint writes and reassigning the same preset snapshot preserve it
- `customError: string | null` (attribute `custom-error`, reflected) — consumer validation message

**Events:** a native-style composed `input` (no detail) then `lr-input` (`detail: { start, end }`),
both fired continuously while dragging or on each arrow/Home/End/PageUp/PageDown key press; and a
native-style composed `change` (no detail) then `lr-change` (`detail: { start, end }`), both fired
on pointer release, keyboard keyup, handle blur while a changed keyboard gesture is still pending,
or when a preset button is clicked. A blur commit retires the gesture before the later physical
keyup, so it cannot emit a duplicate change. The focused handle's native `focus` and `blur` are
re-dispatched from the host as bubbling, composed events. A failed native validity check emits one bubbling/composed,
cancelable `lr-invalid` alias; cancelling it cancels the native `invalid` event and suppresses the
browser's default validation UI.

**Methods:** `focus(options?)` and `click()` forward to `[part="handle-start"]`. `blur()` releases
whichever handle actually owns focus, falling back to the start handle when neither does. Without
these overrides the host's own `focus()`/`blur()`/`click()` are no-ops, because the real controls
live in the shadow root. `getForm()` returns the browser-resolved owning form.

`setCustomValidity(message)` is this control's **only** validation channel: every reachable range is
intrinsically legal, so there is no constraint for it to compute. A non-empty message raises
`customError`, becomes `validationMessage`, and blocks submission of the form it sits in; `''`
clears it. The error survives handle moves, preset picks and a form reset, exactly like a native
control — so a consumer re-validating a range on every `lr-input` calls this with the new message
(or `''`) each time rather than expecting the movement itself to clear it. The message is
caller-supplied and is used verbatim, never localized.

Programmatic writes to `start` and `end` are event-silent. When a controlled caller writes both in
one update, the pair is clamped and ordered atomically (for example `90/10` becomes `10/90` without
losing either endpoint). A one-sided write retains moved-handle semantics: a start above the current
end is pulled back to that end, while an end below the current start is pulled up to that start.

**`form.reset()` — `formResetCallback()`.** The control has no submitted value, but it does take
part in its owning form's reset, and a reset undoes everything the _user_ did to it:

- **The range** goes back to the declared `start`/`end` **content attributes** — the markup default,
  the way a native `<input>` resets to its `value` attribute rather than to its current IDL value. A
  handle with no attribute falls back to the domain bound it started at. The restored pair is
  normalized the same way a preset pick is (clamped into `[min, max]`, then ordered so
  `start <= end`), so an inverted or out-of-range declared range still restores to a legal one.
- **The interaction flag** is cleared, which makes the control pristine again: `:state(user-valid)`
  and `:state(user-invalid)` stop matching until the user touches it again. Without this, a range a
  consumer had rejected kept rendering as the user's mistake on a form they had just reset.
- **An in-flight keyboard gesture** is dropped, so the next key-up cannot commit an `lr-change` for
  a step the reset already discarded. Every in-flight pointer drag is also retired synchronously,
  including its window listeners, so a later pointer release cannot commit the restored range as a
  stale user change. Direct and fieldset disablement use the same gesture invalidation path.

Two things deliberately **survive** the reset, matching native semantics:

- **A `setCustomValidity()` message**, and with it `customError`, `validationMessage`,
  `:state(invalid)` and blocked submission. Only another `setCustomValidity('')` clears it. The
  reset stops it looking like the user's error; it does not decide the consumer's constraint is
  satisfied. If a reset should also clear your rejection, call `setCustomValidity('')` from your own
  `reset` listener.
- **`disabled`, `min`/`max`, `step`, `presets`, and every other author-set property** — a reset
  restores the user's edits, not the component's configuration.

The reset **emits nothing**: like a native control, it is the form's edit rather than the user's, so
no `input`/`change`/`lr-input`/`lr-change` fires. Read `start`/`end` in a `reset` listener on the
form if you need to react. There is deliberately no `formStateRestoreCallback()` beside it — this
control never calls `setFormValue()`, so the browser has no serialized state to hand back for
autofill or back/forward restore.

**Slots:** none.

**CSS parts:** `base` (the aggregate `role="group"`), `track`, `range`, `handle-start`, `handle-end`,
`presets`, `preset-button`

**Themeable custom properties:** mostly shared tokens — `--lr-color-border`, `--lr-color-brand`,
`--lr-color-surface`, `--lr-shadow-s` (handles), `--lr-opacity-disabled` (`:host(:disabled)`
dimming, including ancestor-fieldset disablement), plus (for `presets`) `--lr-color-text`,
`--lr-color-on-brand` (the active preset
button's text), `--lr-radius`, `--lr-space-xs/-s`, `--lr-transition-fast`,
`--lr-focus-ring-*`.

Three component-local properties recolor the **active** preset button independently of the shared
palette: `--lr-time-range-preset-active-bg` (falls back to `--lr-color-brand`),
`--lr-time-range-preset-active-border-color` (falls back to `--lr-color-brand`), and
`--lr-time-range-preset-active-color` (falls back to `--lr-color-on-brand`). Unset, each resolves
to exactly the token the rule used before they existed, so the default rendering is unchanged.

Pointer states and handle chrome are independently themeable too:

- `--lr-time-range-preset-hover-border-color`,
  `--lr-time-range-preset-pressed-border-color`, and `--lr-time-range-preset-pressed-bg` control
  preset hover/press paint.
- `--lr-time-range-handle-bg`, `--lr-time-range-handle-border-color`,
  `--lr-time-range-handle-hover-bg`, and `--lr-time-range-handle-pressed-bg` control the handle's
  resting, hovered, and pressed paint.

Every hook falls through to the prior shared brand/surface token or color-mix expression, so old
themes retain their rendering and can opt into only the state they need.

One additional component-local property, `--lr-time-range-size-scale` (unitless multiplier,
default 1, automatically set based on the `size` property), scales the handle, track, and preset
button dimensions proportionally — unset, it defaults to 1 (size='m', no scaling).

They exist because the active preset is marked with an attribute on a part, and
`::part(preset-button)[data-active]` is **invalid CSS** — an attribute selector cannot follow
`::part()`. Without these, recoloring just the active preset meant hijacking the shared
`--lr-color-brand`/`--lr-color-on-brand` tokens and repainting everything else that reads them.

They are written as **inline `var()` fallbacks at the point of use, never declared on `:host`** —
deliberately, because a `:host` declaration would shadow any value an ancestor set. Setting one on
any ancestor of the `<lr-time-range>` therefore reaches it. (The same technique is used for
`lr-emoji-picker`'s `--lr-emoji-picker-active-bg`.)

**Optional peer deps:** none.

```html
<lr-time-range id="months" min="0" max="2" start="0" end="2"></lr-time-range>
<script>
  const months = ["April 2023", "May 2023", "June 2023"];
  const range = document.getElementById("months");
  range.valueFormatter = (value, handle) =>
    `${handle === "start" ? "From" : "Through"} ${months[value]}`;
  range.addEventListener("lr-change", (e) =>
    console.log(e.detail.start, e.detail.end)
  );
</script>
```

**Known gotchas:**

- Keyboard support now matches the full WAI-ARIA APG slider pattern: ArrowUp/Right and ArrowDown/Left
  move by `step` (RTL-aware — under `direction: rtl` the forward/backward keys swap so they still
  track the visually-adjacent direction), PageUp/PageDown move by `step * 10`, and Home/End jump to
  that handle's actual _reachable_ bound — clamped by the sibling handle's current value, not the
  component's full `[min, max]` domain, so Home/End on the `end` handle can't jump past `start` (and
  vice versa). Pointer-drag is RTL-aware the same way (mirrors the drag ratio under `direction:
rtl`).
- **Click-to-seek on the track.** A pointerdown anywhere on `[part="base"]` other than a handle
  itself jumps whichever handle is nearer the clicked position to that point and continues as the
  same drag gesture, then focuses that handle so arrow keys carry on from there. It emits `lr-input`
  on the jump and a single `lr-change` on release, mirrors the ratio under RTL exactly as dragging
  does, breaks a tie toward the handle that can actually travel toward the click, and does nothing
  while the control is disabled. This matches `lr-slider[range]`'s identical behavior; a pointerdown
  that starts on a handle is still a plain handle drag.
- A disabled handle now gets `aria-disabled="true"` in addition to losing `tabindex` — a
  screen-reader user exploring by virtual cursor no longer hears it announced as a live, adjustable
  slider.
- `aria-valuemin`/`aria-valuemax` on each handle report that handle's reachable sub-range (bounded by
  its sibling), not the full domain — matching what Home/End actually jump to.
- `valueFormatter` is presentation-only: `aria-valuenow`, geometry, emitted values, and preset
  matching stay numeric. Non-finite handles omit both `aria-valuenow` and `aria-valuetext` and are
  never passed to the formatter.
- Handles a `min > max` domain, a non-positive/non-finite `step`, and disabled-mid-drag/
  disconnect-mid-drag correctly (tested) — safe to rely on those edge cases. Concurrent drags are
  tracked per `pointerId` (not a single scalar), so a two-finger touch — one finger per handle —
  moves both independently instead of the second pointer hijacking which handle the first pointer's
  moves apply to; `pointercancel`/`lostpointercapture` (not just `pointerup`) both end a drag, same
  fix as `lr-multi-split`.
- Non-finite domain/handle values use finite fallback geometry, and non-finite or negative steps are
  treated as unstepped; invalid values never become `NaN`/`Infinity` CSS or ARIA strings.
- `startLabel`/`endLabel` only override each handle's `aria-label`; they don't affect
  `aria-valuenow`/`aria-valuemin`/`aria-valuemax`, `valueFormatter`, or any visible text.
- An ancestor `<fieldset disabled>` toggling is reflected via `formDisabledCallback` into
  `effectiveDisabled` (tracked separately from the consumer's own `disabled`), so re-enabling the
  fieldset correctly restores a handle that had `disabled` set explicitly by the consumer, and vice
  versa — mirrors `lr-combobox`'s identical pattern.

**Additional API surface:**

- `--lr-time-range-handle-size` — Visible handle diameter. Default: `14px*scale`.
- `--lr-time-range-hit-size` — Actual drag hit-area diameter; endpoint handles are inset by half this distance so the hit geometry stays inside the host. Default: `max(24px,28px*scale)`.
- `--lr-time-range-track-size` — Track and selected-range thickness. Default: `4px*scale`.
- `--lr-time-range-base-size` — Brush baseline block size. Default: `1.5rem*scale`.
- `--lr-time-range-preset-gap` — Gap between preset buttons. Default: `var(--lr-space-xs)`.
- `--lr-time-range-preset-radius` — Preset button corner radius. Default: `var(--lr-radius)`.
- `--lr-time-range-preset-padding` — Preset button padding, scaled by `size`.
- `--lr-time-range-preset-font-size` — Preset button font size, scaled by `size`.

---

## `lr-swatch-picker`

A single-select picker over a small, fixed set of color swatches with the WAI-ARIA APG
`radiogroup` contract built in: `role="radiogroup"`/`role="radio"`, roving tabindex, automatic
activation (click or arrow-key move both select immediately, like a native radio group), cyclic
Arrow/Home/End navigation. First-party invention (no Web Awesome equivalent). Distinct from
`lr-color-picker`, which is a freeform picker over the whole colour space — this picks exactly one
of N designer-chosen named colors, the shape apps otherwise hand-roll as a row of round
accent-color buttons. Its `items` are the _only_ choices; a `lr-color-picker`'s `swatches` are a
shortcut list alongside a grid, a hue ramp and a text field that can still express any colour.
Arrow/Home/End navigation starts from the swatch that actually received the keyboard event, even
when a controlled `value` write changed the selected or remembered roving item first.

Own `disabled` changes take effect immediately for host `click()` and `focus()`, including calls in
the same task as the property assignment. Blocked activation leaves value and `lr-change` untouched;
blocked focus preserves outside focus and emits no native focus inside the picker.

**Properties:**

- `items: readonly SwatchPickerItem[] = []` (attribute: false) — `SwatchPickerItem { readonly value:
string; readonly color: string; readonly label: string; readonly icon?: unknown; readonly
gemstone?: GemstoneKey }`; a valid CSS `color` is used as the
  swatch fill, while invalid values, declaration-breaking input, and `url()` are ignored (and are
  never interpolated into a gemstone SVG). `label` is each swatch's accessible name and `title`.
  `icon` is an optional custom shape rendered _instead of_ the plain filled circle. Its rendered
  subtree stays visible but is inert and hidden from assistive technology, so the swatch button
  remains the sole action. `gemstone` selects the canonical faceted glyph when
  `mode="gemstone"`. An explicit `icon` wins over `gemstone`. Assignments are bounded and copied
  into a frozen owned snapshot; mutate a new array/item and reassign it to update the palette.
- `value: string | null = null` — the currently selected option's `value` (controlled); `null`
  leaves nothing selected while keeping the first swatch tabbable.
- `size: '2xs' | 'xs' | 's' | 'm' | 'l' | 'xl' = 'm'` (reflected — scales the swatch hit-area and
  fill diameter proportionally, hit-area floored at 24px; not pixel-matched to `lr-input`'s
  row-height scale)
- `mode: 'swatch' | 'gemstone' = 'swatch'` (reflected) — `swatch` preserves the plain-circle
  default. `gemstone` renders the shared glyph for options carrying a `gemstone` key and enables
  the selected glow/shine defaults. That automatic glyph's checked-state halo/shine is the exact
  `gemstoneSelectedGlyphStyles` stylesheet the theme module also exports standalone (see
  `theme/gemstones.js` below), so a glyph rendered elsewhere on the page — e.g. a header trigger
  showing the current selection — can match this picker exactly by consuming the same export. An
  explicit `icon` on a `gemstone`-mode item is a consumer shape, not that shared glyph, and keeps
  this picker's own generic selected-icon glow instead (see `--lr-swatch-picker-gemstone-*` below).
- `accessibleLabel: string = ''` (attribute `aria-label`) — accessible name copied to the internal
  `role="radiogroup"`; attribute presence wins, including an explicitly empty name.
- The 9.x compatibility aliases were removed in 10.0.0: `options` is `items`, the exported
  `SwatchOption` type is `SwatchPickerItem`, and the former invisible `label` IDL is
  `accessibleLabel`/`aria-label`. The canonical sibling radiogroup vocabulary is now the only
  spelling.
- `disabled: boolean = false` (reflected) — locks the whole picker. Every swatch renders as a real
  `disabled` `<button>`, so it leaves the tab sequence and cannot be activated; arrow/Home/End
  navigation and host `click()` become no-ops; and the swatches dim to `--lr-opacity-disabled` with
  a `not-allowed` cursor and no hover lift. This is the picker's own attribute only: the control is
  deliberately **not** form-associated (it submits nothing and carries no `name`, validity or reset
  semantics), so an ancestor `<fieldset disabled>` does not cascade into it — disable the picker
  itself alongside the fieldset when a form needs both.

**Events:** `lr-change` (`detail: { value }`) — fired only when the selected value actually
changes via click or keyboard (re-selecting the current swatch is a no-op).
`lr-activate` (`detail: { value }`) — fired on **every** activation of a swatch (a click, or an
Arrow/Home/End key that lands on one), whether or not the selection actually moved. Bubbling,
composed, not cancelable — it reports that the user picked a swatch and gates nothing. `value` is
the activated swatch's own value. Use it for the repeat pick `lr-change` deliberately stays silent
for, which is otherwise unobservable: the swatches live in this shadow root, so a retargeted `click`
names no swatch, and keyboard activation produces no click at all — Home on an already-first
selection, End on an already-last one, or an arrow key in a one-item row activates a swatch and
fires nothing else. When an activation _does_ move the selection, `lr-change` is emitted first and
`lr-activate` second, so either listener reads the settled `value`.

**Slots:** none.

**CSS parts:** `base` (the `role="radiogroup"` root), `swatch` (a single `role="radio"` color
swatch's interactive hit target, sized via `--lr-swatch-picker-hit-size` — its private default
follows `size` and is floored at 24px; the selected one is
`[part='swatch'][aria-checked='true']`), `swatch-fill` (the filled circle inside it, sized via
`--lr-swatch-picker-fill-size` — defaults to `--lr-size-1-5rem`, with a private default that also
follows `size` —
rendered when the option has no `icon`), `swatch-icon` (the option's `icon` shape, rendered in its
place when it has one, with its inherited `font-size` set to the same fill-size token so a `1em`
glyph fills the wrapper; the wrapper is inert and aria-hidden across the flattened subtree).
Exactly one of `swatch-fill`/`swatch-icon` is mounted per swatch, so the two never coexist.

**Themeable custom properties:** `--lr-swatch-picker-selected-color` (ring color around the
selected swatch, defaults to `--lr-color-brand`, themeable independently of the focus ring),
`--lr-swatch-picker-selected-blur` (default `0` — a crisp ring; set a real length such as `0.4rem`
for a soft glow. It is the blur radius of `swatch-fill`'s `box-shadow` ring, and of the equivalent
`drop-shadow()` used for a `swatch-icon` rendering a consumer-supplied `icon`, since `box-shadow`
can't follow a slotted icon's real shape), `--lr-swatch-picker-shine-duration` (default `0s`, a
no-op; set a duration such as `1.6s` for a looping brighten-and-settle pulse on the selected
swatch. It drives a separate `filter: brightness()` keyframe rather than `box-shadow`, so it
composes with the blur token and works identically for a fill and a consumer-supplied icon;
disabled outright under `prefers-reduced-motion: reduce`, which also drops the hover/selection
scale transition), `--lr-swatch-picker-hit-size` (hit-area
size; its private default follows `size`), `--lr-swatch-picker-fill-size` (visible fill/icon
diameter; its private default follows `size`; set this hook on an ancestor/direct host to override
every tier, or `--lr-theme-swatch-picker-fill-size` on an ancestor for a shared default),
`--lr-swatch-picker-gemstone-selected-blur` (default `--lr-size-0-5rem` in gemstone mode, aliased
onto the shared `--lr-gemstone-selected-blur` so the two cannot drift apart — applies to a plain
color-fill swatch and to a consumer-supplied `icon` override in gemstone mode, NOT to the
automatic gemstone glyph itself), `--lr-swatch-picker-gemstone-shine-duration` (default `1.8s` in
gemstone mode, same aliasing and scope as `--lr-swatch-picker-gemstone-selected-blur`);
plus shared tokens — `--lr-color-border`/`-brand`, `--lr-space-xs`,
`--lr-border-width-thin`/`-thick`, `--lr-radius`, `--lr-transition-fast`, `--lr-focus-ring-*`,
and the per-tier `--lr-size-*` tokens. The automatic gemstone glyph's own checked-state halo/shine
is themed independently, through `--lr-gemstone-selected-color`/`-blur`/`-shine-duration` — see
`theme/gemstones.js`'s `gemstoneSelectedGlyphStyles` below, the exact stylesheet this picker
includes in its own `static styles` for that glyph.

**Optional peer deps:** none.

```html
<lr-swatch-picker aria-label="Accent color"></lr-swatch-picker>
<script type="module">
  const picker = document.querySelector("lr-swatch-picker");
  picker.items = [
    { value: "blue", color: "#0969da", label: "Blue" },
    { value: "green", color: "#1a7f37", label: "Green" },
    { value: "purple", color: "#8250df", label: "Purple" },
  ];
  picker.value = "green";
  picker.addEventListener("lr-change", (e) => console.log(e.detail.value));
</script>
```

For the shared gemstone accent mode, import the Lit-free palette data entry. The glyph renderer
remains available separately from `theme/gemstones.js` for Lit templates; palette-only consumers
do not need to load Lit. The consumer still owns localized labels, display order, and the initial
value:

```ts
import "@aceshooting/lyra-ui/components/forms/swatch-picker/swatch-picker.js";
import { GEMSTONES } from "@aceshooting/lyra-ui/theme/gemstones-data.js";

const order = ["emerald", "ruby", "sapphire", "hematite"] as const;
picker.mode = "gemstone";
picker.items = order.map((key) => ({
  value: key,
  color: GEMSTONES[key].fill,
  label: translateGemstone(key),
  gemstone: key,
}));
picker.value = "ruby";
```

To match this picker's checked-glyph halo/shine on a `gemstoneGlyph()` rendered anywhere else
(e.g. a header trigger button showing the current selection before it opens the picker in a
popover), import both Lit-based exports and reuse them directly instead of re-authoring the
treatment: `gemstoneGlyph()` for the markup and `gemstoneSelectedGlyphStyles` — a `CSSResult` — in
the consuming component's own `static styles`, then toggle the `data-lr-gemstone-selected` boolean
attribute on the element wrapping the rendered glyph to switch the halo/shine on:

```ts
import { gemstoneGlyph, gemstoneSelectedGlyphStyles } from "@aceshooting/lyra-ui/theme/gemstones.js";

class AccentTrigger extends LitElement {
  static styles = [gemstoneSelectedGlyphStyles];
  render() {
    return html`<button ?data-lr-gemstone-selected=${this.hasSelection}>
      ${gemstoneGlyph()}
    </button>`;
  }
}
```

**Known gotchas:**

- arrow-key navigation cycles (past the last swatch wraps to the first, and vice versa) rather than
  clamping, and self-selects on move — arrow-navigating to a swatch immediately updates `value` and
  fires `lr-change`, there's no separate commit step.
- live `items` changes preserve a focused swatch by item-object identity across reorders.
  Removing the focused option moves focus and the roving tab stop to the nearest surviving swatch
  (the next item at that position, or the previous item when the final option was removed) without
  changing the controlled `value` or emitting `lr-change`.
- under RTL (nearest `dir="rtl"` ancestor) `ArrowLeft`/`ArrowRight` swap which direction they move.
- each swatch's fill comes from its option's `color`, applied through a per-swatch custom property
  set inline on `[part='swatch']` and read by `[part='swatch-fill']`, so a consumer's
  `::part(swatch-fill)` `background-color` rule can still override it.
- style the selected state through `--lr-swatch-picker-selected-color`/`-selected-blur`/
  `-shine-duration`, not through `::part(swatch)[aria-checked='true']` from outside: the CSS Shadow
  Parts spec only allows a fixed set of pseudo-classes after `::part()`, not arbitrary attribute
  selectors, so that combinator can silently fail to match depending on the engine.
- the semantic `radiogroup` lives inside shadow DOM. Set `accessibleLabel` or a host `aria-label`;
  the component deliberately forwards the resulting name to that internal role.
- the automatic gemstone glyph's checked-state halo/shine is themed through
  `--lr-gemstone-selected-color`/`-blur`/`-shine-duration`, not through
  `--lr-swatch-picker-selected-*`/`-gemstone-*` — those style a plain color-fill swatch or a
  consumer-supplied `icon` override instead, even while `mode="gemstone"`.

**Additional API surface:**

- `--lr-swatch-picker-gap` — Gap between swatches. Default: `var(--lr-space-xs)`.
- `--lr-swatch-picker-wrap` — `flex-wrap` on the swatch row. Default: `wrap`, reproducing the
  previously hardcoded wrapping row exactly. Set `nowrap` to confine every swatch to a single
  row — the case this exists for is a picker inside a fixed-width popover, where a second row
  changes the panel's height and moves the popover under its trigger. A custom property rather
  than an attribute, so it inherits through wrappers like the gap and hit-size hooks beside it;
  tuning the gap and hit size small enough to avoid wrapping is a guess that breaks at the next
  swatch added.

---

## `lr-checkbox`

A boolean form control. `role="checkbox"` with an `aria-checked` that can also be `"mixed"`, and a
visual box/checkmark. Structurally the same idea as `<lr-switch>` (form-associated via
`ElementInternals`, click and Space toggle) but with checkbox semantics.

Removing `error-text` safely omits the message while preserving native `null` property readback.
Explicit empty text stays empty; later supplied text renders normally.

**Properties:**

- `checked: boolean = false` — the live, non-reflecting state
- `defaultChecked: boolean = false` (canonical attribute `checked`, reflected) — the current reset
  default; changing it updates `checked` only while the live state is pristine
- `indeterminate: boolean = false` (reflected) — visual-only mixed state; does not affect `checked`,
  and is cleared back to `false` by any user interaction (click or keyboard), matching native
  `<input type="checkbox">`
- `disabled: boolean = false` (reflected)
- `required: boolean = false` (reflected — enforced via `internals.setValidity()`)
- `name: string = ''`
- `value: string = 'on'` — only contributed to form submission while `checked` (a native checkbox
  submits nothing at all, not even an empty string, while unchecked)
- `customError: string | null` (attribute `custom-error`) — reflected consumer validation message
- `hint: string = ''` — WA supporting text below the control
- `helpText: string = ''` (attribute `help-text`) — Shoelace alias for the same supporting-text
  surface; `hint` wins when both properties are set
- `errorText: string = ''` (attribute `error-text`) — owned error text associated with the inner
  checkbox; custom markup can use the `error` slot
- `size: LyraSize = 'm'` (reflected) — control size on the shared ladder, accepting both
  `2xs`/`xs`/`s`/`m`/`l`/`xl` and `small`/`medium`/`large`. It scales the box and its checkmark off
  the same values `lr-input`/`lr-select`/`lr-button` read, so controls of one `size` line up in a
  row. The slotted label keeps the library's standard control-label type size at every tier —
  restyle it through `::part(label)` if you want it to track the control.

**Events:** user toggles emit, in order, bubbling/composed `input`, the compatibility `lr-input`
alias, bubbling/composed `change`, then the compatibility `lr-change` alias (both aliases carry
`detail: { checked: boolean }`). Programmatic `.checked` assignments are
silent. Internal `focus`/`blur` are re-dispatched as bubbling, composed host events. `lr-invalid` (no detail) fires when a
validity check finds the checkbox invalid.
**Refusing a toggle.** `lr-checkbox-toggle-request` is cancelable and fires *before* `checked`
moves, on every user path (click, Space, and the host `click()` activation it forwards).
`detail: { checked: boolean }` is the state the control **would** take; `checked` itself still holds
the old value while the event dispatches. `preventDefault()` keeps the current state, so the box
never flips at all rather than flipping and snapping back, and none of
`input`/`lr-input`/`change`/`lr-change` follow. A listener can instead answer by assigning `checked`
itself during the dispatch, which suppresses the built-in write the same way — including when it
assigns the value the control already held, which a before/after comparison cannot detect. It does
not fire for a programmatic `.checked` assignment, a form reset, a session-state restore, or while
the control is disabled. Inside an `<lr-checkbox-group>` this event is consumed at the group
boundary and republished as `lr-checkbox-group-toggle-request`, exactly as the group already
translates the child's `input`/`change`/`lr-change`. A refused toggle also leaves the control
pristine: it does not count as the interaction that reveals `:state(user-valid)`/`:state(user-invalid)`,
so refusing a required checkbox's first toggle cannot flash a validation error for a change that
never happened. Blurring the control, or a `reportValidity()` call, still marks it interacted, which
is the native `:user-invalid` timing.

**Methods:** `focus(options?)`, `blur()`, and `click()` forward to the internal checkbox control;
`getForm()` returns its owning form (including an external owner selected by `form`).
`setCustomValidity(message)` sets or clears a consumer-supplied error ("those terms have been
superseded"): a non-empty message raises `customError` and blocks submission, `''` restores the
control's own computed validity so a required-and-unchecked box goes back to `valueMissing`. It
survives every toggle and a form reset; `setCustomValidity('')` or `resetValidity()` clears it.

**Slots:** default — rich label content rendered beside the semantic checkbox owner. Clicking
plain label content toggles like a native associated label; activating a nested link or button does
not toggle. If left empty, set `aria-label` on the host so the control still has an accessible
name. `hint` is the WA supporting-text slot;
`help-text` is the Shoelace spelling for the same described-by surface.
`error` supplies custom error markup on the same owned error surface as `errorText`.

The label, hint, and error wrappers can shrink and wrap at arbitrary boundaries inside a 320px LTR
or RTL allocation. The checkbox square and its shared interactive target remain fixed-size.

The default slot deliberately remains the checkbox's one visible, clickable label; there is no
separate top-of-field label property or slot. `form-control` wraps that checkbox plus its error and
hint, matching `lr-switch` without duplicating the label idiom.

The `checkbox`/`base` semantic role owner retains `--lr-icon-button-size` as its minimum inline and
block size at every tier. The visible `box` remains tied to `size`, so a label-less `2xs` checkbox
centres a compact square inside a 40px clickable target instead of inflating the glyph itself.

The label wrapper tracks flattened forwarding-slot assignment and later mutations. Its presence is
visual: an element-only icon or intentionally visible `aria-hidden` decoration keeps the wrapper,
independently of whether that node contributes to the accessible name. A host `aria-label` wins by
presence and is forwarded verbatim, including `aria-label=""`.

The internal `role="checkbox"` exposes explicit stateful `aria-invalid`. Visible property/slotted
error chrome makes it `"true"` immediately; otherwise it becomes true only after interaction while
intrinsic/custom validity fails, and explicitly returns to `"false"` when neither condition holds.

Host `aria-describedby` targets in the host's own root are resolved onto the internal
`role="checkbox"` through `ariaDescribedByElements`, so an externally-owned description remains
valid across the shadow boundary. In supporting browsers the explicit element list intentionally
leaves the internal role's serialized attribute empty; browsers without the reflected-reference
API keep the string fallback. The relationship tracks host attribute changes and clears when
unset.

**CSS parts:** `form-control` (outer checkbox/error/hint frame), `row` (the row wrapping the
checkbox owner and the label as siblings — the node to size or align when laying out a column of
checkboxes, since `base`/`checkbox` below is only the control box and its inline size tracks the box
rather than the row), `base` (compatibility name for the
semantic owner; use `checkbox`), `checkbox` (the interactive `role="checkbox"` owner; it is the
same node as `base`, while the rich default label is its sibling),
`box` / `control` (the small square showing the checkmark/indeterminate dash; while active it also
carries Shoelace's `control--checked` or `control--indeterminate` state token), `checkmark` plus
`checked-icon` or `indeterminate-icon` on the visible glyph, `label` (wrapper around the default
slot), `error`, and `hint` / `form-control-help-text` on the supporting-text wrapper.

**Themeable custom properties:** `--lr-checkbox-box-size` and `--lr-checkbox-label-indent` (both
below), plus shared tokens — `--lr-space-s`, `--lr-icon-button-size`,
`--lr-color-border/-surface/-on-brand/-brand/-text/-danger`, `--lr-radius`,
`--lr-transition-fast`, `--lr-focus-ring-width/-color/-offset`, `--lr-opacity-disabled`.
State paint is independently themeable through `--lr-checkbox-hover-border`,
`--lr-checkbox-active-border`, `--lr-checkbox-active-ring`, `--lr-checkbox-invalid-border`,
`--lr-checkbox-checked-bg`, and `--lr-checkbox-checked-border`; every default preserves the
corresponding brand/brand-quiet/danger token.

**`--lr-checkbox-box-size`** — the edge length of `[part='box']`, defaulting to
`min(var(--lr-icon-button-size), calc(var(--lr-form-control-height) * 0.7))`. Derived from the
active `size` tier's shared control height, so the box lines up with an
`lr-input`/`lr-select`/`lr-button` of the same `size` instead of carrying a scale of its own; at the
default `m` tier it resolves to `1.75rem`, exactly what the control shipped with before it had a
`size` at all. The `--lr-icon-button-size` cap is kept, so a consumer compacting that theme token
compacts this control with it. Set it to pin the box independently of the tier.

**`--lr-checkbox-label-indent`** — the inline distance from the control's start edge to the start of
the label text: the box plus the gap beside it. It defaults to
`calc(var(--lr-checkbox-box-size) + var(--lr-space-s))`, and the rendered gap is
_derived_ from it, so the advertised value and the real label offset cannot drift. Setting it on
the element (or on `lr-checkbox` in your own stylesheet) moves the label. The visible box
aligns with the inline start of its transparent hit target, so a compact box plus gap remains
clear of the label in both directions even when the hit target is wider than the box.

It is published so you can align your own per-option hint text under the label without re-deriving
that formula by reading the shadow styles. **But custom properties inherit down, not sideways**, so
a _sibling_ node in your tree cannot read it off the checkbox. Align a sibling by computing the
same formula from the `--lr-theme-*` inputs you control — the tier below is the default `m`;
substitute the one you actually use:

```css
.checkbox-hint {
  padding-inline-start: calc(
    min(
        var(--lr-theme-icon-button-size, 2.5rem),
        calc(var(--lr-theme-form-control-height-m, 2.5rem) * 0.7)
      ) + var(--lr-theme-space-s, 0.5rem)
  );
}
```

`--lr-checkbox-checked-bg` (default `var(--lr-color-brand)`) and `--lr-checkbox-checked-border`
(default `var(--lr-color-brand)`) recolor `[part='box']`'s background/border while `checked` or
`indeterminate` — a component-scoped indirection (the same pattern `lr-source-picker`'s own
`--lr-source-picker-checked-bg`/`-border` pair uses) so a consumer can retint just this control's
checked/indeterminate fill without hijacking the shared `--lr-color-brand` token everything else
reads.

WA's `--checked-icon-color` and `--checked-icon-scale` aliases directly control the visible
checkmark/dash color and scale.

**Optional peer deps:** none.

```html
<lr-checkbox name="terms" required>Accept the terms and conditions</lr-checkbox>
<script type="module">
  document
    .querySelector("lr-checkbox")
    .addEventListener("lr-change", (e) => console.log(e.detail.checked));
</script>
```

Form-associated via a directly-attached `ElementInternals` (not the shared `FormAssociated` mixin,
whose `value` accessor assumes a plain string default flow) with its own hand-rolled
`updateValidity()` — same shape as `<lr-combobox>`'s and `<lr-switch>`'s direct-`ElementInternals`
handling.
Session-history/autofill restoration uses four explicit state tokens: `checked`, `unchecked`,
`checked/indeterminate`, and `unchecked/indeterminate`. This preserves both public booleans while
keeping an unchecked control distinguishable from a checked control whose submitted value is an
empty string. Restoration updates state, form data, and validity synchronously without firing
`lr-change`.

**Known gotchas:**

- `checked` follows native dirty-state rules. A later `el.checked = true` assignment changes only
  the live state and never rewrites the attribute. Changing `defaultChecked` or the `checked`
  attribute updates the reset target but cannot overwrite a dirty live state; `form.reset()` uses
  that current default and makes the control pristine again.
- `indeterminate` is visual-only and silently clears on any user click/keypress — a consumer relying
  on it staying `true` after a user interacts with the box will be surprised.
- The rendered `aria-label` is copied from the host's own `aria-label` attribute at render time; if
  neither that nor slotted label text is present, the control has no accessible name.

---

## `lr-switch`

A boolean toggle-switch form control. `role="switch"` with `aria-checked` read as an on/off state
rather than checked/unchecked, and no indeterminate state. Structurally the same idea as
`<lr-checkbox>` (form-associated via `ElementInternals`; click and Space toggle). Enter is not a
special switch key. Logical ArrowLeft/ArrowRight set the switch off/on, mirrored under RTL.
Ships an opt-in `hint`/`errorText` form-control chrome (props + matching named slots + `hint`/`error`
CSS parts), mirroring `<lr-select>`'s pattern for those two pieces — left unset, neither renders.
Deliberately no separate top-of-field `label` prop/slot/part: the default slot already is this
control's visible, clickable label (same as `<lr-checkbox>`).

Host `aria-describedby` references resolve onto the internal `role="switch"` before its local
error/hint guidance. The relationship tracks missing IDs, target replacement/removal/reinsertion,
reconnect, and document adoption. Removing `hint`, `help-text`, or `error-text` safely omits that
content while preserving native `null` property readback; explicit empty and later text work
normally.

**Properties:**

- `checked: boolean = false` — the live, non-reflecting state
- `defaultChecked: boolean = false` (canonical attribute `checked`, reflected) — the current reset
  default; changing it updates `checked` only while the live state is pristine
- `disabled: boolean = false` (reflected)
- `required: boolean = false` (reflected — enforced via `internals.setValidity()`)
- `name: string = ''`
- `value: string = 'on'` — only contributed to form submission while `checked`
- `customError: string | null` (attribute `custom-error`) — reflected consumer validation message
- `hint: string = ''` — hint text below the switch. Unset: no hint chrome renders.
- `helpText: string = ''` (attribute `help-text`) — Shoelace alias for `hint`; `hint` wins when both
  are supplied
- `withHint: boolean = false` (attribute `with-hint`) — WA SSR presence hint for slotted supporting
  text that cannot be inspected until hydration
- `errorText: string = ''` (attribute `error-text`) — error text below the switch (overridden by
  slotted `error` content). Unset: no error chrome renders.
- `size: LyraSize = 'm'` (reflected) — control size on the shared ladder, accepting both
  `2xs`/`xs`/`s`/`m`/`l`/`xl` and `small`/`medium`/`large`. It scales the track and thumb off the
  same values `lr-input`/`lr-select`/`lr-button` read, so controls of one `size` line up in a row.
  The slotted label keeps the library's standard control-label type size at every tier — restyle it
  through `::part(label)` if you want it to track the control.

**Events:** a user state change (click, Space, a logical ArrowLeft/ArrowRight change, or the
programmatic `click()` activation path) emits
`input`, then `lr-input`, then `change`, then `lr-change` (both aliases carry
`detail: { checked: boolean }`) — in that order, matching
the native checkbox/radio contract. The two native-style events are **new in 8.0.0**: a boolean
control that emitted only the `lr-`-prefixed alias was invisible to every form library, validation
helper, and `<form>`-level `change` listener that binds the native names, which is the ordinary way
a consumer observes a control they didn't write. `input` is an `InputEvent`; `change` is an
`Event`. Both bubble and compose, and neither carries a detail — read `event.target.checked`.
None of the four fires for a programmatic `.checked`
assignment, `form.reset()`, or session-state restoration. The internal control's native
`focus` and `blur` are re-dispatched as bubbling, composed host events. `lr-invalid` (no detail) fires when a validity
check finds the switch invalid.
**Refusing a toggle.** `lr-switch-toggle-request` is cancelable and fires *before* `checked` moves,
on every user path (click, Space, a logical ArrowLeft/ArrowRight change, and the host `click()`
activation it forwards). `detail: { checked: boolean }` is the state the switch **would** take;
`checked` itself still holds the old value while the event dispatches. `preventDefault()` keeps the
current state, so the switch never slides at all rather than sliding and snapping back, and none of
`input`/`lr-input`/`change`/`lr-change` follow. A listener can instead answer by assigning `checked`
itself during the dispatch, which suppresses the built-in write the same way. It does not fire for a
programmatic `.checked` assignment, `form.reset()`, session-state restoration, while the control is
disabled, or for an arrow key naming the state the switch already holds. A refused toggle also
leaves the control pristine: it does not count as the interaction that reveals
`:state(user-valid)`/`:state(user-invalid)`, so refusing a required switch's first toggle cannot
flash a validation error for a change that never happened. Blurring the control, or a
`reportValidity()` call, still marks it interacted, which is the native `:user-invalid` timing.

**Methods:** `focus(options?)`, `blur()`, and `click()` forward to the internal switch control;
focus/click and stale keyboard/pointer activation are synchronous no-ops as soon as direct or
fieldset disablement starts, even before the next render;
`getForm()` returns its owning form (including an external owner selected by `form`).
`setCustomValidity(message)` sets or clears a consumer-supplied error ("notifications are disabled
for your plan"): a non-empty message raises `customError` and blocks submission, `''` restores the
control's own computed validity so a required-and-unchecked switch goes back to `valueMissing`. It
survives every toggle and a form reset; `setCustomValidity('')` or `resetValidity()` clears it.

`checked`/`defaultChecked` use the same native dirty-state contract as `lr-checkbox`: live writes
never reflect, default/attribute changes cannot overwrite a dirty live state, and `form.reset()`
restores the current default before making the control pristine again.

**Slots:**

- default — rich label content rendered beside the semantic switch owner. Clicking plain label
  content toggles like an associated label; activating a nested link or button does not toggle. If
  left empty, set `aria-label` on the host so the control still has an accessible name. Flattened
  forwarding-slot assignment and later mutations
  keep the visual wrapper synchronized; element-only and visible `aria-hidden` decorations retain
  it. A host `aria-label` wins by presence, including an explicitly empty value.
- `hint` — custom hint content.
- `help-text` — Shoelace alias for the same hint surface.
- `error` — custom error content.

**CSS parts:** `form-control` (the outer wrapper around the switch, error and hint), `row` (the row
wrapping the switch owner and the label as siblings — the node to size or align when laying out a
column of switches, since `base`/`switch` below is only the track box and its inline size tracks the
track rather than the row), `base` /
`switch` / `wrapper` (the semantic interactive `role="switch"` owner; the rich label is its
sibling), `track` / `control` (the
pill-shaped background), `thumb` (the circular knob), `label` (wrapper around the default slot),
`hint` / `form-control-help-text` (the hint message), and `error`.

**Themeable custom properties:** `--lr-switch-track-block-size` (default
`calc(var(--lr-form-control-height) * 0.5)`), `--lr-switch-track-inline-size` (default
`calc(var(--lr-switch-track-block-size) * 1.8)`, the 1.8:1 aspect ratio the control has always had)
and `--lr-switch-thumb-offset` (default `var(--lr-size-2px)`) — component-local geometry knobs set
on `:host`, since a fully-rounded pill/thumb needs a radius well past the shared `--lr-radius`
default. Both track dimensions ride the shared `size` ladder, so at the default `m` tier they
resolve to exactly the `1.25rem` × `2.25rem` the switch shipped with before it had a `size` at all.
WA/Shoelace's `--width`, `--height`, and `--thumb-size` aliases feed those same rendered dimensions.
`--lr-switch-gap` (default `var(--lr-space-s)`) independently controls the track-to-label gap.

`--lr-switch-track-fill` (default `--lr-color-border`) is `[part='track']`'s unchecked resting
fill. `--lr-switch-checked-track-fill` (default `--lr-color-brand`) independently retints its
checked fill, and `--lr-switch-track-hover-fill` / `--lr-switch-track-active-fill` independently
retint the pointer states (their defaults remain mixes from the current resting fill).
`--lr-switch-track-border` is `[part='track']`'s border; **undeclared by default**, so no border
renders at all, matching today's chrome — set it to add a rim (e.g. for a themed high-contrast
look) without affecting any other switch. `--lr-switch-checked-track-border` (default
`var(--lr-switch-track-border)`) varies that border only while checked, so a bordered track can
differ by state without falling back to `lr-switch:state(checked)::part(track)`. It takes a whole
`border` shorthand value, like its resting sibling, and falls back through it to no border at all —
setting only the resting hook keeps one border in both states. Keep both widths equal unless a size
change between states is what you want: the track is `box-sizing: content-box`, so a border grows
its outer footprint.
`--lr-switch-thumb-fill` (default `--lr-color-surface`) controls the thumb while unchecked, and is
also the checked-state fallback. `--lr-switch-checked-thumb-fill` (default
`var(--lr-switch-thumb-fill)`) independently retints the thumb only while checked, leaving the
unchecked thumb untouched.
`--lr-switch-label-color` (default `var(--lr-color-text)`) controls `[part='label']`'s text color,
and is also the checked-state fallback. `--lr-switch-checked-label-color` (default
`var(--lr-switch-label-color)`) independently retints the label only while checked. Both label hooks
read the switch's **live** checked state (the same `:state(checked)` custom state the class doc's
`@cssstate checked` documents), not the `checked` *attribute* — which instead reflects
`defaultChecked`, the form-reset value — so the checked-state hook tracks user interaction correctly
even though the attribute does not.
Plus shared tokens
`--lr-space-s`, `--lr-color-border/-brand/-surface/-text`,
`--lr-transition-fast`, `--lr-focus-ring-width/-color/-offset`, `--lr-opacity-disabled`.

**Optional peer deps:** none.

```html
<lr-switch name="notifications" checked>Enable notifications</lr-switch>
<script type="module">
  import "@aceshooting/lyra-ui/components/forms/switch/switch.js";
  const sw = document.querySelector("lr-switch");
  sw.addEventListener("lr-change", (e) => console.log(e.detail.checked)); // prefixed alias
  sw.addEventListener("change", (e) => console.log(e.target.checked)); // native-style, no detail
</script>
```

Form-associated the same way as `<lr-checkbox>`: a directly-attached `ElementInternals` with a
hand-rolled `updateValidity()`, not the shared `FormAssociated` mixin. The thumb animates the
logical `inset-inline-start` property (not a physical `transform: translateX()`), so the slide
direction mirrors correctly under `dir="rtl"`.
Session-history/autofill restoration uses the same explicit `checked`/`unchecked` state tokens as
checkbox and does not emit `lr-change`.

**Known gotchas:**

- `checked` is live and dirty; `defaultChecked`/the `checked` attribute is the current reset default.
  A later `.checked = true` never redefines what `form.reset()` restores to. Shoelace's
  Only the canonical `checked` attribute and property-only `defaultChecked` IDL define that reset
  default.
- The rendered `aria-label` is copied from the host's own `aria-label` attribute at render time; with
  neither that nor slotted label text, the control has no accessible name.

---

## `lr-slider`

A numeric range control (e.g. an LLM "temperature" setting). **Form-associated** directly through
`ElementInternals`, because its public `value` is a number rather than the string assumed by the
shared form mixin. `value`, `defaultValue`, and `valueAsNumber` are numeric; `valueAsString` is the
explicit compatibility round-trip for code that still wants a serialized value. A primary-button press anywhere
on `[part~="base"]` (not just the thumb) jumps the
thumb to that point and continues the same gesture as a drag, matching native `<input type=range>`
click-to-seek — the thumb is also `.focus()`ed on that click, so keyboard interaction can continue
seamlessly right after. Mirrors the core `<wa-slider>` API under the `lr-` prefix.

Secondary mouse buttons leave the value and input/change events untouched. Primary mouse, touch and
pen gestures remain supported, including concurrent pointers.

Removing `label`, `hint`, `help-text` or `error-text` safely removes the corresponding copy; native
attribute-removal property readback remains unchanged, including `null`. Supplying an empty string
or later replacement remains supported. In single mode, host `aria-describedby` references resolve
in the host's root and precede local error/hint descriptions on the slider handle. Target
replacement, removal, reinsertion, host reconnection and document adoption update the relationship
without losing local guidance.

**Two-handle `range` mode.** `range` turns the control into a selection between `minValue` and
`maxValue`, defaulting to `0`/`50`. Each handle is a separately focusable `role="slider"` with its
own localized accessible name and the full domain as its reachable range. When the active handle
crosses its sibling, it pushes that sibling to the same value instead of stopping, so the active
thumb remains under the pointer/key. A track click moves whichever handle is nearer the clicked
position. `[part~="base"]` then carries `role="group"`, named from
`label`/`aria-label`, so the pair is announced as one control.

Switching `range` while the outgoing handle owns focus transfers focus to the equivalent replacement
(single value to lower handle; either range handle to single value) without reclaiming newer
external focus. A mode switch during a pointer drag releases capture and cancels that gesture
without an extra commit.

A named range slider submits **two same-name entries**, lower then upper. For example,
`<lr-slider range name="window">` contributes `window=0&window=50` by default. Read both with
`formData.getAll('window')`; `get()` returns only the first entry. Turning `range` off restores the
single numeric string entry.

**Properties:**

- `min: number = 0`
- `max: number = 100`
- `step: number = 1` — a zero or negative value is kept as an explicit "unstepped" mode
- `range: boolean = false` (reflected) — two-handle mode; see above
- `minValue: number = 0` (attribute `min-value`) — the lower handle's value in `range` mode.
  Assigning past `maxValue` pushes `maxValue` to the same number
- `maxValue: number = 50` (attribute `max-value`) — the upper handle's value. Assigning below
  `minValue` pushes `minValue` to the same number. Only the `min-value`/`max-value`
  _attributes_ are captured as the `form.reset()` defaults, so a later property assignment never
  redefines what a reset restores to
- `orientation: 'horizontal' | 'vertical' = 'horizontal'` (reflected) — which axis carries the
  value. `'horizontal'` maps values to the inline axis (mirroring under RTL); `'vertical'` maps them
  to the block axis with the domain minimum at the block **end** (so "up" always means "more"),
  switches the primary keys to ArrowUp/ArrowDown, and exposes `aria-orientation="vertical"` on every
  handle
- `readonly: boolean = false` (reflected) — the value is displayed but not changeable. Unlike
  `disabled`, a read-only slider stays focusable, fully legible, and **still submits its value**; it
  renders `aria-readonly` in both states and withdraws the grab cursor
- `size: LyraSize = 'm'` (reflected) — control size on the shared ladder, accepting both
  `2xs`/`xs`/`s`/`m`/`l`/`xl` and `small`/`medium`/`large`. It scales the track, the filled
  indicator, the tick marks and the handles off the same values `lr-input`/`lr-select`/`lr-button`
  read, so controls of one `size` line up in a row. The handle's transparent drag area keeps its own
  1.75rem/28px floor at every tier, so a small slider is still a conformant pointer target
- `withMarkers: boolean = false` (attribute `with-markers`) — draws a tick mark at every
  `step` position along the track. Purely decorative (`aria-hidden`). Nothing is drawn for an
  unstepped grid (`step` ≤ 0) or for one implying more than 100 intervals — ten million ticks would
  be visually indistinguishable and would hang the page, so the grid is dropped rather than
  half-drawn
- `withTooltip: boolean = false` (attribute `with-tooltip`) — shows a live value bubble
  above each handle while that handle is focused or being dragged. Its text is `valueFormatter`'s
  result when one is supplied, otherwise the locale-formatted number
- `label: string = ''`, `hint: string = ''`, and `errorText: string = ''` (attribute `error-text`) —
  visible form context around the track, with matching rich `label`/`hint`/`error` slots. A host
  `aria-label` wins for the interactive accessible name by attribute presence, including an
  explicitly empty value; range mode then suppresses `aria-labelledby` on its group owner as well.
  When error and hint content are both present, every handle's `aria-describedby` references the
  error first and the hint second. Rich slotted error content replaces the plain `errorText` copy.
- `helpText: string = ''` (`help-text`) and the `help-text` slot are Shoelace aliases for `hint`.
- `withLabel: boolean = false` / `withHint: boolean = false` (`with-label`/`with-hint`) are SSR
  presence hints; hydrated instances also discover populated slots automatically.
- `indicatorOffset?: number` (`indicator-offset`) — single-slider fill origin. The indicator spans
  between this number and `value`, whichever is lower.
- `autofocus: boolean = false` — focuses the first/lower thumb after the first client render.
- `tooltipPlacement: 'top' | 'right' | 'bottom' | 'left' = 'top'` and
  `tooltipDistance: number = 8` control physical tooltip layout in either orientation and RTL.
- `tooltip: 'top' | 'bottom' | 'none' = 'none'` and `tooltipFormatter?: (value) => string` are
  Shoelace-compatible aliases layered over the richer Lyra/Web Awesome tooltip surface. Lyra's
  default is `none`, while `<sl-range>` defaults to `top`; the bundled migration codemod inserts
  `tooltip="top"`, and a manual tag rename must set it explicitly to retain Shoelace's behavior.
- `valueFormatter?: SliderValueFormatter` (attribute: false) —
  `(value: number, handle: 'value' | 'min' | 'max') => string | null | undefined`. Maps the finite,
  clamped `aria-valuenow` number to optional human-readable `aria-valuetext`, and supplies the
  `with-tooltip` bubble's text. The second argument identifies which handle is being formatted
  (`'value'` on a single-handle slider). A nullish result omits `aria-valuetext`. Leaving the
  property unset preserves the numeric `aria-valuetext`.
- `showValue: boolean = false` (attribute `show-value`) — opt-in numeric readout next to the track;
  a range readout joins both values with an en dash. The explicit HTML spelling
  `show-value="false"` stays false.
- `valueDisplay: SliderValueDisplay = 'numeric'` (attribute `value-display`) — `'numeric' |
  'formatted'`. Opt into `formatted` to reuse `valueFormatter` (or `tooltipFormatter` when no
  value formatter is supplied) for the visible readout too. Each range handle is formatted
  separately; nullish results fall back to localized numbers. Existing ARIA and tooltip behavior
  is unchanged. The callback owns its unit labels and locale formatting.
- `valuePlacement: SliderValuePlacement = 'inline'` (attribute `value-placement`) — `'inline' |
  'label'`. With `showValue`, `label` places the readout opposite the label in a wrapping row that
  follows RTL. The readout stays outside the accessible label. These presentation options update
  on live `lr-input` changes without changing the commit-only `lr-change` contract.
- `value: number = 0`, `defaultValue: number = 0` (attribute `value`), `valueAsNumber: number`, and
  `valueAsString: string` are synchronized and finite. Values normalize the low/high domain, snap
  to the grid anchored at the low endpoint, then clamp so a non-grid endpoint remains reachable;
  invalid, nonpositive, or below-resolution steps are unstepped.
- `isRange: boolean` is the read-only normalized range-mode state.
- `name: string | null = null`, `disabled = false`, `required = false`, reflected `customError`,
  plus read-only `form`, `labels`, `validity`, `validationMessage`, and `willValidate` make up the
  native form surface.

**Events:** native-style `input` (no detail), then `lr-input`, fire continuously during an active
drag or keyboard step, including OS key-repeat while a key is held. Native-style `change` (no
detail), then `lr-change`, fire once an interaction commits: on pointerup for an enabled drag,
or on keyup or ordinary blur for a changed keyboard sequence. A later keyup cannot duplicate a
blur commit. Own or fieldset disablement, and readonly, cancel unfinished gestures without
reverting their live values or emitting a later change pair. Pointer cancellation, lost capture
and disconnection also remain noncommitting.
The focused handle's native `focus` and `blur` are re-dispatched from the host as bubbling,
composed events.
`lr-invalid` (no detail) fires when a validity check finds the slider invalid.
**Breaking in 8.0.0:** both details widened from `{ value: number }` to
`{ value: number; minValue: number; maxValue: number; handle: 'value' | 'min' | 'max' }`. `value` is
the value of the handle that moved and `handle` says which one that was (`'value'` on a
single-handle slider); `minValue`/`maxValue` always carry both range-handle positions. Existing
`e.detail.value` readers keep working unchanged.

**Methods:** `focus(options?)` and `click()` forward to the first/lower thumb; `blur()` releases the
thumb that actually owns focus. `stepUp(steps = 1)` / `stepDown(steps = 1)` silently move the
focused handle (first/lower when none is focused). `getForm()`, `checkValidity()`,
`reportValidity()`, `setCustomValidity(message)`, and `resetValidity()` mirror native form-control
methods.

**Slots:** `label`, `hint`, Shoelace alias `help-text`, `error`, and `reference`. Empty chrome stays
hidden and contributes no accessible relationship.

The standalone slider has a zero intrinsic flex minimum and a 100% allocation ceiling. Its label,
reference, error, and hint regions wrap even unbroken content in LTR and RTL; the fixed numeric
readout and track remain contained. An exact-320px story covers this composition.

**CSS parts:** `base slider form-control form-control-input input control` are tokens on the
interactive row (`role="group"` in range mode). `label form-control-label` share the visible label
node; `references` wraps the endpoint/unit slot; `error` is the error node; and
`hint form-control-help-text` share the hint node.
`track` is the full-length line; `indicator` is the filled portion from `min` up to the current
value, or between the two handles in `range` mode.
`markers` (the tick container, present only with `with-markers`) and `marker` (one `step`-grid
tick), `thumb` (a draggable handle, `role="slider"` — present on every handle including both range
ones), `thumb-min` and `thumb-max` (the lower and upper range handles; each carries `thumb` as
well, so `::part(thumb)` styles both while `::part(thumb-min)` reaches only one), `tooltip` (the
live value bubble per handle, present only with `with-tooltip`), `tooltip-visible` (added _to the
`tooltip` element's part list_ while that handle is focused or dragged — visibility is encoded in
the part name because `::part(tooltip)[data-visible]` is invalid CSS and never matches; write
`::part(tooltip-visible)`). The tooltip also exposes `tooltip__tooltip`, `tooltip__content`, and
`tooltip__arrow`. `value` is the opt-in readout; `label-row` contains the separate label and value
nodes when `showValue` and `valuePlacement="label"` are enabled.

**CSS custom states:** `disabled`, `dragging`, `focused`, `required`, `optional`, `valid`,
`invalid`, `user-valid`, and `user-invalid`. A slider always has a finite numeric value, so
`required` is still useful as a styling hook but does not by itself make the control invalid;
`setCustomValidity()` controls the invalid states.

**Breaking in 8.0.0:** the `fill` part was **renamed to `indicator`**, matching `wa-slider`. A
`::part(fill)` rule silently matches nothing now — rename it.

**The required marker.** `required` with a non-empty `label` paints the library's shared marker on
the `form-control-label` node — the one `::after` rule described under "The required-field marker"
above, not a copy of it, so `--lr-form-control-required-content`,
`--lr-form-control-required-color` and `--lr-form-control-required-offset` retune or suppress it
here exactly as they do on `lr-input`. With no label text the node is hidden and no glyph is
painted. It is purely a visual convention here, for the reason the custom states note above gives:
a slider always has a value, so the marker never accompanies a `valueMissing` violation.

**Themeable custom properties:** three geometry knobs ride the shared `size` ladder, so a tier moves
them all without a per-tier rule, and the values in brackets are what they resolve to at the default
`m`:

`--lr-slider-gap` (default `var(--lr-space-s)`) controls the row/column gap between the track,
value readout, label, references, error, and hint as those flex items wrap.

- `--lr-slider-thumb-size` (default `calc(var(--lr-form-control-height) * 0.4)`; `1rem`) — the
  diameter of each draggable handle. The transparent drag area around it never drops below
  1.75rem/28px whatever this is set to, so shrinking the visible dot cannot cost you the pointer
  target.
- `--lr-slider-track-thickness` (default `calc(var(--lr-slider-thumb-size) * 0.25)`; `0.25rem`) —
  the thickness of the track, the filled `indicator`, and (scaled from it) the `with-markers` ticks.
- `--lr-slider-row-size` (default `calc(var(--lr-form-control-height) * 0.6)`; `1.5rem`) — the
  cross-axis extent of `[part="base"]`: its block size when horizontal, its inline size when
  vertical.

`--lr-slider-track-length` (default `var(--lr-size-10rem)`) is the
track's length in `orientation="vertical"`; a horizontal track fills its container instead, so the
token is inert there. It is declared as an inline `var()` fallback and never on `:host`, so a
consumer value set on any ancestor is never shadowed. `--lr-slider-tooltip-distance` carries the
finite, unit-resolved tooltip offset computed from `tooltipDistance`; set `tooltipDistance` rather
than overriding this runtime value. The thumb has independent paint hooks:
`--lr-slider-thumb-bg` (default `var(--lr-color-brand)`), `--lr-slider-thumb-border-color`
(default `var(--lr-color-surface)`), `--lr-slider-thumb-hover-ring-color` (default
`var(--lr-color-brand-quiet)`), and `--lr-slider-thumb-active-ring-color` (defaulting through the
hover ring). Everything else is shared tokens —
`--lr-space-s`, `--lr-color-border/-brand/-surface/-text-quiet`, `--lr-shadow`,
`--lr-focus-ring-width/-color/-offset`, `--lr-opacity-disabled`.

Mapped aliases are also live: `--thumb-size`, `--thumb-width`, `--thumb-height`, `--track-height`,
`--track-size`, `--track-color-active`, `--track-color-inactive`, `--track-active-offset`,
`--tooltip-offset`, `--marker-width`, and `--marker-height`.

**Optional peer deps:** none.

```html
<lr-slider
  id="temperature-slider"
  name="temperature"
  min="0"
  max="2"
  step="0.1"
  label="Temperature"
  hint="Higher values make replies more varied."
  with-markers
  with-tooltip
></lr-slider>

<!-- Two handles, vertical. A name submits two `price` entries. -->
<lr-slider
  id="price-slider"
  range
  name="price"
  orientation="vertical"
  min="0"
  max="1000"
  step="50"
  min-value="200"
  max-value="800"
  label="Price"
></lr-slider>
<script type="module">
  const temperature = document.getElementById("temperature-slider");
  temperature.valueAsNumber = 0.7;
  temperature.valueFormatter = (value, handle) => `${value * 100}%`;
  temperature.addEventListener("lr-input", (e) => setDraftTemperature(e.detail.value));
  temperature.addEventListener("lr-change", (e) => commitTemperature(e.detail.value));

  const price = document.getElementById("price-slider");
  price.addEventListener("lr-change", (e) => applyPriceFilter(e.detail.minValue, e.detail.maxValue));
</script>
```

An unset `value` starts at numeric `0`, clamped into the configured domain and step grid. A reset
restores the numeric `defaultValue` sourced from the `value` content attribute, or the same zero
default when the attribute was absent. A slider therefore always represents a number; `required`
is present for upstream form-surface parity but adds no missing-value constraint.

**Known gotchas:**

- `valueAsNumber` always returns a real, clamped number — never `NaN` or `""` — even reading it in the
  brief window right after a `form.reset()`.
- Under `direction: rtl`, physical ArrowRight/ArrowLeft swap which one counts as "forward" (increasing
  value); ArrowUp/ArrowDown are never swapped, since direction only affects the horizontal inline axis.
- Changing `min`/`max`/`step` after mount automatically re-clamps/re-snaps the current `value` in the
  next update — narrowing the domain can silently move the slider's value.
- `valueFormatter` is presentation-only: `aria-valuenow`, geometry, form value, and emitted values
  stay numeric. The visible readout stays numeric unless `valueDisplay="formatted"` is set.
- Numeric value/domain assignments in the same Lit update batch are normalized against the final
  `min`, `max`, and `step`, regardless of binding order. Await `updateComplete` to read the settled
  scalar or range endpoints. Immediate imperative readback remains clamped to the current domain;
  separate update batches intentionally normalize independently. Programmatic normalization emits
  no user input/change event.
  With no formatter, `aria-valuetext` remains the
  numeric string rendered by earlier versions; a nullish formatter result omits it.
- A pointer drag fires `lr-input` continuously and a single `lr-change` on release; a keyboard step
  fires exactly one of each per press, but OS key-repeat while a key is held re-fires `lr-input` on
  every repeat while still only committing `lr-change` once, on the eventual keyup. A gesture that
  ends without a pointerup (`pointercancel`, lost pointer capture, the element being removed
  mid-drag) tears down cleanly and commits nothing.
- **`::part(fill)` no longer matches** — the part is `indicator` as of 8.0.0.
- A named `range` slider contributes two same-name entries. Use `FormData#getAll()`, not `get()`,
  when both values are required.
- `min-value`/`max-value` are clamped against the domain, snapped to `step`, and re-sanitized once
  every declarative attribute has landed, so narrowing `min`/`max` after mount can silently move
  both handles. Only the attributes seed the `form.reset()` defaults.
- Vertical sliders put the domain minimum at the block **end**: ArrowUp increases. ArrowUp/ArrowDown
  are never mirrored under RTL, which is exactly what makes them the stable primary keys there.
- `with-markers` silently draws nothing when `step` is 0/negative or when the domain implies more
  than 100 intervals. That is a deliberate ceiling, not a bug — check the rendered `[part="marker"]`
  count rather than assuming the ticks are there.
- The visible thumb is deliberately below the library's usual 40px icon-button floor — 16px at the
  default `m` tier, and smaller at the tighter ones. A transparent `::before` carries the hit/drag
  area at `max(28px, calc(var(--lr-slider-thumb-size) * 1.75))`, which clears WCAG 2.5.8's 24px
  minimum at **every** tier, while a 40px _visible_ thumb would make two range handles overlap
  across 40px of track and hijack track clicks. The pseudo-element has no DOM node of its own, so a
  pointerdown inside it still reports the thumb as `e.target`.

---

## `lr-radio`

A form-associated single-choice control. Use it alone or inside `lr-radio-group`.

An explicit live `checked` assignment marks the state dirty even if its boolean value is unchanged.
For example, assigning `checked = false` to an already-unchecked radio prevents a later
`defaultChecked = true` from selecting it until form reset. Pristine default propagation and
owning-group normalization retain their existing behavior.

Host `aria-describedby` references resolve onto the internal `role="radio"`, tracking unresolved
IDs, target replacement/removal/reinsertion, reconnect, and document adoption. The same behavior
applies to the button appearance of `lr-radio`.

**Properties:** live, non-reflecting `checked`; reflected `defaultChecked` (attribute `checked`);
reflected `customError: string | null` (attribute `custom-error`); `disabled`, `required`, `name`,
and `value`. A selected standalone radio submits its value through `ElementInternals`.
An empty `name` is canonicalized to an omitted attribute rather than reappearing as `name=""`.
`effectiveRequired` exposes the required state inherited from a containing radio group.
`effectiveName` and `effectiveSize` expose the owning group's aggregate projections while `name`
and `size` remain the option's authored state; late writes survive removal, reparenting, and group
disconnect/reconnect. `focus()`,
`blur()`, and `click()` forward to the internal radio control; `getForm()` returns the standalone
radio's owning form and the aggregate group's owning form while the radio is group-owned.

- `size: LyraSize = 'm'` (reflected) — control size on the shared ladder, accepting both
  `2xs`/`xs`/`s`/`m`/`l`/`xl` and `small`/`medium`/`large`. It scales the indicator off the same
  values `lr-input`/`lr-select`/`lr-button` read, so controls of one `size` line up in a row. The
  slotted label keeps the standard control-label type size at every tier — restyle it through
  `::part(label)` to make it track the control.
- `appearance: 'default' | 'button' = 'default'` (reflected) — WA's button presentation on the
  same `<lr-radio>` tag; it retains radio semantics, group ownership, value, and events
- `pill: boolean = false` (reflected) — rounds the control's own chrome into a pill instead of the
  shared control radius. A plain `<lr-radio>`'s indicator is a circle at every setting, so this is
  visible on `<lr-radio-button>`, which inherits this class and renders rectangular chrome; it is
  declared here so both tags carry one property with one meaning.

`setCustomValidity(message)` sets or clears a consumer-supplied error ("that plan is no longer
available"): a non-empty message raises `customError` and blocks submission, `''` restores the
control's own computed validity so a required-and-unselected radio goes back to `valueMissing`. It
survives every selection, every group-driven `required` change, and a form reset. A standalone
radio owns the error itself; an owned radio delegates it to the form-associated aggregate group.
`resetValidity()` clears the error through that same standalone-or-group owner.

`checked` follows native dirty-state semantics: changing `defaultChecked`/the `checked` attribute
updates the current reset default without overwriting a dirty live selection, and `form.reset()`
restores the current default.

**Events:** a standalone selection emits, in order, native-style composed `input`, `lr-input`,
native-style composed `change`, then `lr-change`; both aliases carry `{ checked, value }`. An owned
radio emits none of those child value events; its group emits the sole aggregate sequence described
below, so capture and bubble listeners cannot observe two differently shaped event sets. The
internal control's native `focus` and `blur` are re-dispatched as bubbling, composed host events.
`lr-invalid` (no detail) belongs to the standalone radio; an aggregate group emits its own alias.

**Slots:** default label content. In `appearance="button"`, `start`/`prefix` share the leading
wrapper and `end`/`suffix` share the trailing wrapper, matching `lr-radio-button`; changing away
from button appearance does not remove or rewrite the authored light-DOM content. Flattened
forwarding-slot assignment and later mutations keep the visual label wrapper synchronized;
element-only and visible `aria-hidden` decorations retain it. A host `aria-label` wins on the
internal radio by presence, including `aria-label=""`.

A standalone radio stays within its allocated inline size. Long or unbroken default labels wrap in
LTR and RTL while the indicator retains its fixed geometry; an exact-320px story covers both.

**CSS parts:** default appearance: `base`, `circle` / `control` (with Shoelace's
`control--checked` state token), `dot` / `checked-icon`, and `label`. Button appearance: `base`,
`button`, `control`, `button--checked` while selected, `start` / `prefix`, `label`, and `end` /
`suffix`. Empty leading, label, and trailing wrappers are hidden independently, so only present
content contributes `--lr-radio-button-gap` spacing.
Every `<lr-radio-button>` size tier keeps its interactive base at least 24px in both axes, including
an empty-label control; the visible density can still grow with the shared size ladder.

**Themeable custom properties:**

- `--lr-radio-circle-size` (default `min(var(--lr-icon-button-size), calc(var(--lr-form-control-height)
  - 0.7))`; `1.75rem`at the default`m`tier) — the edge length of`[part='circle']`, derived from
the active `size`tier's shared control height so a radio lines up with an`lr-input`/`lr-select`/`lr-button`of the same`size`.
- `--lr-radio-dot-size` (default `min(calc(var(--lr-radio-circle-size) * 0.5),
calc(var(--lr-form-control-height) * 0.3))`; `0.75rem` at `m`) — the edge length of `[part='dot']`,
  capped at half the circle so it can never outgrow its ring, whatever is done to either the ladder
  or the `--lr-icon-button-size` cap.
- `--lr-radio-radius` (default `--lr-radius-pill`) — the corner radius of the control's own chrome.
  A circular indicator is fully round at every setting; `<lr-radio-button>` changes the private
  default to the shared control radius and `pill` changes it back to a pill. An inherited or direct
  public value wins throughout.
- `--lr-radio-label-indent` (default `calc(var(--lr-radio-circle-size) + var(--lr-space-s))`) — the
  inline distance from the control's start edge to the start of the label text, i.e. the circle plus
  the gap beside it. The rendered gap is derived from it, so the advertised value and the real offset
  cannot drift; setting it on the element (or on `lr-radio` in your own stylesheet) moves the label.
  Exactly the same knob, purpose, and sideways-inheritance caveat as `--lr-checkbox-label-indent` —
  see `llms/components/lr-checkbox.md` for the formula to align a sibling hint element.

`--lr-radio-checked-border-color` (default `var(--lr-color-brand)`) and `--lr-radio-checked-dot-color`
(default `var(--lr-color-brand)`) recolor `[part='circle']`'s border and `[part='dot']`'s background
while `checked` — a component-scoped indirection (the same pattern `lr-checkbox`'s own
`--lr-checkbox-checked-bg`/`-border` pair uses) so a consumer can retint just this control's checked
ring/dot without hijacking the shared `--lr-color-brand` token everything else reads.
The pointer states are independently themeable with `--lr-radio-hover-border-color` (default
`var(--lr-color-brand)`), `--lr-radio-active-border-color` (defaulting through the hover border),
and `--lr-radio-active-ring-color` (default `var(--lr-color-brand-quiet)`).
WA's `--checked-icon-color` and `--checked-icon-scale` aliases feed the selected indicator's color
and scale.

```html
<lr-radio name="format" value="json">JSON</lr-radio>
```

## `lr-radio-button`

The same single-choice control as `lr-radio`, rendered as a button instead of a circle. Mirrors
`sl-radio-button`.

An explicit live `checked` assignment marks the state dirty even if its boolean value is unchanged.
For example, assigning `checked = false` to an already-unchecked radio prevents a later
`defaultChecked = true` from selecting it until form reset. Pristine default propagation and
owning-group normalization retain their existing behavior.

Host `aria-describedby` references resolve onto the internal `role="radio"`, tracking unresolved
IDs, target replacement/removal/reinsertion, reconnect, and document adoption. The same behavior
applies to the button appearance of `lr-radio`.

Deliberately a **subclass of `LyraRadio`**: form association, validity, `form.reset()` restoration
and the whole `lr-radio-group` ownership/roving-focus contract are inherited rather than
reimplemented, so the two can never drift apart. Only the chrome differs. A `lr-radio-group` accepts
either tag and the two can be mixed in one group.

Inside a horizontal `lr-radio-group`, measured adjacent runs of `lr-radio-button` controls merge
their touching borders and retain rounded outer corners. Separated or mixed controls, vertical
layouts, wrapped rows and standalone buttons keep the corners appropriate to their actual layout;
label and hint slots do not determine the segment endpoints.

Standalone button chrome is allocation-safe too: unbroken labels wrap, and start/end (or retained
prefix/suffix) adornments are each capped and truncate rather than widening the containing panel.
The exact-320px story shows that behavior in LTR and RTL.

**Properties and methods:** exactly the same functional surface as `lr-radio`. Its writable fields
are `appearance`, `checked`, `defaultChecked`, `customError`, `disabled`, `name`, `required`, `value`,
`size`, and `pill`. Its effective form/validity state is also inherited: read-only
`effectiveDisabled`, `effectiveRequired`, `form`, `labels`, `validity`, `validationMessage`, and
`willValidate`. The delegated methods are `click()`, `focus()`, `blur()`, `getForm()`,
`checkValidity()`, `reportValidity()`, `setCustomValidity()`, and `resetValidity()`; form reset,
disabled-fieldset, and state-restoration callbacks remain the browser-owned FACE integration behind
those public operations. Its inherited strongly typed `addEventListener()` and
`removeEventListener()` overloads cover the radio event map listed below while retaining the
standard DOM string overloads. The inherited `appearance` remains `'default' | 'button'`; this tag already
renders button chrome in either state, so the property adds no second visual mode. `size` is where this
chrome differs most visibly: the shared ladder drives the button's height (floored at `1.5rem`),
inline padding and font size, so a `size="small"` radio button sits at the same height as a
`size="small"` `lr-button` beside it. `pill` is the one inherited property that does _more_ here
than on a plain `lr-radio` — see the radius note below.

The inherited derived reads `effectiveName` and `effectiveSize` expose the resolved group name and
size used by the button's form and chrome logic.

**Events:** identical to `lr-radio` — a standalone selection emits `input`, `lr-input`, `change`,
then `lr-change` (both aliases carry `{ checked, value }`); an owning `lr-radio-group` emits the
aggregate sequence instead. The internal control's `focus` / `blur` are re-emitted because they do
not cross the shadow boundary. `lr-invalid` (no detail) belongs to a standalone radio button; an aggregate group emits
its own alias.

**Slots:** default (label text), `start` (leading content, typically an icon), and `end` (trailing
content). Shoelace's `prefix` and `suffix` are retained as aliases for `start` and `end`,
respectively; either spelling can be used, and both spellings share one wrapper at each edge.
The leading, label, and trailing wrappers are hidden independently while empty, so missing regions
do not contribute dead flex gaps.
Host `aria-label` is forwarded to the internal radio by attribute presence, including
`aria-label=""`; it is not replaced by the visible default-slot text.

**CSS parts:** `base` / `button` / `control`, `start` / `prefix` (the same leading wrapper),
`label`, and `end` / `suffix` (the same trailing wrapper). The interactive node carries `checked`
and `button--checked` when selected, plus `disabled` under own, group, or fieldset disablement,
because an attribute selector
after `::part()` never matches.

**Themeable custom properties:** `--lr-radio-radius` is the one inherited knob this element really
uses. `lr-radio` gives it a private `--lr-radius-pill` default for its circular indicator; this
subclass changes that private default to `--lr-form-control-radius` — the active `size` tier's
shared corner radius — and `pill` changes it back to `--lr-radius-pill`. An inherited or direct
public value wins. Only the _outer_ corners of an actually contiguous run take it: an
owning horizontal group measures same-line adjacency after layout, then collapses shared borders.
The ordinary group gap, a plain-radio interruption, vertical layout, or a flex wrap starts a new
fully rounded run, and live add/remove/reorder plus LTR/RTL changes are reconciled. Standalone
siblings are never guessed into a run. `--lr-radio-button-gap` (default `var(--lr-space-xs)`) controls the
spacing between the start/prefix wrapper, label, and end/suffix wrapper in both `<lr-radio-button>`
and `<lr-radio appearance="button">` without changing the shared spacing token used elsewhere.
Button paint states can be rethemed without changing shared tokens:
`--lr-radio-button-hover-bg` / `--lr-radio-button-hover-border-color` and
`--lr-radio-button-active-bg` / `--lr-radio-button-active-border-color` control the unchecked
pointer states; `--lr-radio-button-checked-bg`, `--lr-radio-button-checked-border-color`, and
`--lr-radio-button-checked-color` control checked rest; and the corresponding
`--lr-radio-button-checked-hover-bg`, `--lr-radio-button-checked-hover-border-color`,
`--lr-radio-button-checked-active-bg`, and `--lr-radio-button-checked-active-border-color` hooks
control checked pointer states. The inherited `--lr-radio-hover-border-color`,
`--lr-radio-active-border-color`, and `--lr-radio-active-ring-color` remain visible in generated
metadata but apply only to the base radio's circular chrome. All fallbacks preserve the existing
brand, on-brand, quiet, and color-mix treatments.

Because this is a subclass, the manifest also lists `lr-radio`'s own `circle` and `dot` parts and
its `--lr-radio-circle-size`, `--lr-radio-dot-size`, `--lr-radio-label-indent`,
`--lr-radio-checked-border-color` and `--lr-radio-checked-dot-color` custom properties. **This
element renders none of those** — it draws a button, not a circle and dot — so styling them here has
no effect. The same is true of the inherited `checked-icon` and `control--checked` parts and the
`--checked-icon-color` / `--checked-icon-scale` aliases. They are inherited declarations, not
rendered button surface. `--lr-radio-radius` is the exception, and
the only one of the set worth setting on this tag.

```html
<lr-radio-group name="view" label="View" orientation="horizontal">
  <lr-radio-button value="day" checked>Day</lr-radio-button>
  <lr-radio-button value="week">Week</lr-radio-button>
</lr-radio-group>
```

---

## `lr-otp-input`

A form-associated one-time-code field: several character segments that together hold one value.
Mirrors `wa-otp-input`.

Host `aria-describedby` references resolve onto the native control input before its local error and
hint guidance. The relationship tracks missing IDs, target replacement, removal/reinsertion,
reconnect, and document adoption. The decorative code segments do not receive a second copy of the
descriptions.

Changing own `disabled` from true to false in the same task that disables an ancestor fieldset keeps
the native editing control effectively disabled. The enabled first-legend exception and explicit
own-disabled state retain their native meaning; validity and form submission follow the effective
disabled state.

The segments are **presentational**. A single real `<input>` sits transparently across them and owns
focus, selection and the value. It remains the native integration point for SMS autofill
(`autocomplete` defaults to `one-time-code`), IME composition and mobile keyboards, and keeps the
control to one tab stop rather than one per character. Fixed-cell keyboard and paste handlers map
those native editing intents into the visual cells without exposing one input per character.

Every live-value path — typing, paste, autofill, a `value` assignment, pristine default propagation,
form reset, browser state restoration, or a narrowing `type` change — funnels through one sanitizer,
so none of them can produce a value another could not. Characters the current `type` rejects are
dropped silently: pasting or assigning `"ABC-123"` to a numeric field yields `123`. Programmatic,
reset, and restoration paths remain event-silent and preserve native dirty/default-value semantics.

Public `--lr-otp-input-*` theme inputs stay undeclared on the host, so an ancestor theme wrapper
can override appearance fallbacks; a value set directly on the element still wins.

**Properties:** `label`, `hint`, `errorText` (`error-text`);
`appearance: 'outlined' | 'filled' | 'filled-outlined' | 'contained' = 'outlined'` (reflected);
`autofocus: boolean = false`; `autosubmit: boolean = false` (reflected);
`size: LyraSize = 'm'` (reflected after an explicit property/attribute write, accepting
`2xs`/`xs`/`s`/`m`/`l`/`xl` and the shared aliases). While unset, its generic font/radius/height
slots inherit a containing control's size context; standalone font and radius rendering falls back
to `m`. Explicitly writing even the same-default `m` pins the `m` mapping, and removing the
attribute restores contextual inheritance;
`length: number = 6` (reflected); `format: string = ''` — `#` marks a segment and any
other character becomes a literal separator (`format="###-###"`), overriding `length`. Only the
first 4,096 UTF-16 code units are parsed;
`type: 'numeric' | 'alpha' | 'alphanumeric' = 'numeric'` (reflected, also drives `inputmode`);
`case: 'preserve' | 'upper' | 'lower' = 'preserve'` (reflected); `mask: boolean = false` masks entered
characters, while `withMask: boolean = false` (`with-mask`) independently paints the mask glyph in
empty segments. With only `with-mask`, entered characters remain visible; with both properties,
filled and empty segments paint the glyph. Both are display-only, so `value` and screen-reader text
are unaffected. `readonly: boolean = false`; `autocomplete: string = 'one-time-code'`; plus the shared
form-associated surface (`name`, `value`, `defaultValue`, `customError` (`custom-error`), `disabled`,
`required`, `form`, `validity`, `validationMessage`, `willValidate`, `getForm()`, `checkValidity()`,
`reportValidity()`, and `setCustomValidity()`).

**Methods:** `focus()`, `blur()`, `click()`, `select()`,
`setSelectionRange(start, end, direction?)`, `setRangeText(replacement, start?, end?, selectMode?)`,
`clear()`, `resetValidity()`, and `formStateRestoreCallback(state, reason)`. `clear()` empties a
nonempty code, emits `lr-clear`, and returns focus to the real input. `resetValidity()` clears only
a consumer-supplied custom error and recomputes the intrinsic required/completeness constraints.
The browser restoration callback sanitizes string state and restores unsupported state shapes as
the empty value. `select()` selects the real compact-string value; typing replaces its selected
occupied cells at the first selected cell, while Backspace/Delete clears them in one edit.
`setRangeText()` bounds both the current native value and replacement before applying a
programmatic compact-string edit through the same character, case, and length sanitizer as every
other value path, synchronizes the visual cells, submitted value, and validity, and emits no
user-input event. When sanitizing removes a replacement character, the
returned selection offsets are remapped onto the accepted compact string.

**Read-only:** `input: HTMLInputElement | null` exposes the real native input and
`validationTarget: HTMLInputElement | null` exposes the same element as the native validation-UI
anchor. Both are `null` before the component connects and renders. `effectiveLength: number`
reports how many segments are actually rendered: a valid
`format`'s `#` count, else `length`, clamped to 1–32. A nonempty format whose bounded
4,096-code-unit prefix contains no `#` is treated as unset, so `length` supplies the segments and
no literal-only row renders. Literal runs are
coalesced into one separator cell; output is still bounded to 32 segments. Value sanitization
likewise inspects at most the first 4,096 UTF-16 code units and stops earlier as soon as the
effective length is filled. This is the number `value` is truncated to and the field is validated
against, so read it instead of re-deriving it from `length`.

**Selection facade:** `selectionStart`, `selectionEnd`, and `selectionDirection` forward native
compact-string getters and setters; each reads `null` before the input renders, and pre-render
writes and range-method calls are safe no-ops. Native selection, Home/End, click/pointer caret, and
host facade changes all move the fixed-cell keyboard target, so printable, Delete, and Backspace
edit the cell at the live compact caret rather than a stale internal index.

**Events:** native `InputEvent` `input` (including editing payload), native `Event` `change`, and
`lr-clear` (no detail) when a nonempty field is cleared by the user or `clear()`. Fixed-cell edits
emit `input` immediately and one `change` when the field settles on blur or Enter. Intermediate IME
composition events stay on the real input without sanitizing or committing; the final
non-composing input commits and relays once. `lr-complete` (`detail: { value }`) fires only on an
incomplete-to-complete transition, so replacing a filled cell does not complete again. It always
bubbles, composes, and is cancelable. With `autosubmit`, the component submits its owning form
after the event unless a listener calls `preventDefault()`. That submission is deferred one task,
so a listener that decides asynchronously (`await`-ing a check before letting the form go) can
still veto it; it then goes through the same resolved default button as Enter-to-submit, so
`SubmitEvent.submitter` and the button's own `name`/`value` reach the submission. The real input's native
`focus` and `blur` are re-dispatched from the host as bubbling, composed events since the originals
do not cross the shadow boundary. Replacing the live or default code, resetting/restoring the form state, or disconnecting
the component before the deferred task runs retires that completion's submission; a task for code
A can never submit a later full code B.
`lr-invalid` (no detail) fires when a validity check finds the one-time-code input invalid.
Programmatic value/default/reset/state-restoration writes do not emit `input`, `change`, or
`lr-complete`.

**Keyboard and paste:** Left/Right move through visually adjacent fixed cells, with the index delta
mirrored in RTL. Backspace clears the current cell and moves back; Delete clears it in place.
Neither operation shifts later characters. Typing replaces the active cell and advances. A
nonempty native selection maps its compact-string offsets back to occupied visual cells: typing
replaces the selection at its first cell, while either deletion key clears every selected cell.
A bare Enter flushes a pending `change` and requests exactly one submission from the owning form,
through the shared Enter-to-submit gate above — so a modifier-held Enter, an Enter that commits an
IME candidate, an already-vetoed keydown, and a `readonly` field all leave the form alone, and the
keystroke itself is never cancelled. Pasting
fills accepted characters from the first cell in one input operation. The public and submitted
`value` concatenates occupied cells; a middle hole is a visual editing state and is not encoded in
that string.

**Slots:** `label` and `hint` provide rich content when their matching attributes are empty; a
nonempty `label`/`hint` attribute wins when both sources are supplied. The `error` slot replaces
`errorText` when both are supplied. Sources are never concatenated.

**CSS parts:** `base` / `form-control` (aliases on the outer wrapper), `label` /
`form-control-label` (aliases on the label), `field` / `segments` (aliases on the segment wrapper),
`control` (the real, transparent input), `segment`, `separator` / `segment-literal` (aliases on
separators), `hint`, and `error`. A populated required label paints the shared required marker —
the same `::after` rule and the same three properties every other labelled control uses (see "The
required-field marker" above), not a copy of it, so `--lr-form-control-required-content`,
`--lr-form-control-required-color` and `--lr-form-control-required-offset` retune or suppress it
here too.
`segment` carries `active`, `masked`, `placeholder-mask`, and `invalid` as additional part tokens.

**Themeable custom properties:** `--mask-char` (mapped mask-glyph alias, defaulting to the retained
`--lr-otp-input-mask-char`; the value must be a _quoted_ CSS string), `--segment-border-radius`
(default `var(--lr-form-control-radius, var(--lr-radius))`), `--segment-gap` (default
`var(--lr-space-xs)`, ignored by `contained`), and `--segment-size` (default `2.5em` at standalone
`size="m"`), which is the exact inline and block size of each non-shrinking cell. The segment row,
rather than each cell, carries the shared minimum target floor and becomes horizontally scrollable
when the allocated inline size is too small; label, hint, and error copy wrap within that allocation.
The exact-320px RTL story covers an eight-cell row and an unbroken localized label while retaining
horizontal reachability for every cell.
The internal role token `--lr-otp-input-segment-size` supplies that `2.5em` default and can be
retuned through `--lr-theme-otp-input-segment-size` when the `--segment-size` override is absent.
Like `--lr-icon-button-size`, `--lr-otp-input-segment-size` is element-scoped: the shared token
layer re-declares it on every `lr-*` host, so a rule that sets it on an ancestor wrapper is reset at
the first intervening `lr-*` component and never reaches a nested `<lr-otp-input>`. Set it directly
on the element, or set `--lr-theme-otp-input-segment-size` on an ancestor to resize every OTP input
in the subtree at once — the retained per-cell hooks below are not re-declared anywhere in the
shared layer and inherit normally.

The retained per-cell hooks are `--lr-otp-input-segment-fill` (default `transparent`),
`--lr-otp-input-segment-border-color` (default `var(--lr-color-border)`), and
`--lr-otp-input-segment-radius` (defaulting through `--segment-border-radius` to the shared
form-control radius). `filled` uses the raised-surface fill with a transparent cell border;
`filled-outlined` adds the shared border; `outlined` keeps the transparent fill and shared border.
`contained` makes individual cells transparent, borderless, square segments inside the single
raised, bordered row whose radius remains controlled by `--segment-border-radius`.
Active and invalid states are independently themeable through
`--lr-otp-input-active-border-color`, `--lr-otp-input-active-ring-color`, and
`--lr-otp-input-invalid-border-color`, with the shared focus and danger colors retained as
fallbacks.

**CSS custom states:** `--blank`, `--filled`, `disabled`, and `readonly`, plus the shared
form-associated validity states.

**Validation:** a partially-entered code reports `tooShort` with the localized `otpInputIncomplete`
message; `required` and empty reports `valueMissing`. Intrinsic invalid segment styling and the
internal input's intrinsic `aria-invalid` state wait until the user types, blurs, or reports
validity. Explicit `errorText` or `error`-slot chrome renders immediately, is referenced by
`aria-describedby`, and makes the internal input `aria-invalid="true"` immediately, matching the
other Lyra form controls. `readonly` suspends intrinsic required/completeness validity while the
control cannot be edited and restores the current intrinsic result when editing is enabled again.

```html
<lr-otp-input
  label="Verification code"
  required
  error-text="Enter the code we sent you."
></lr-otp-input>
<lr-otp-input
  label="License key"
  type="alphanumeric"
  case="upper"
  format="####-####-####"
></lr-otp-input>
<form>
  <lr-otp-input
    name="code"
    label="PIN"
    length="4"
    appearance="contained"
    autosubmit
  ></lr-otp-input>
</form>
```

---

## `lr-radio-group`

A labeled, keyboard-navigable group of `lr-radio` controls. Home/End and the orientation's arrow
axis move focus and select the next enabled radio: Up/Down when vertical, Left/Right when
horizontal. Horizontal direction mirrors under RTL, and disabled options are skipped.

Host `aria-describedby` references resolve onto the internal `role="radiogroup"` before its local
hint/error guidance. References track unresolved IDs, target replacement/removal/reinsertion,
reconnect, and document adoption. Group descriptions remain on the group; child radios can carry
their own separately authored descriptions.

**Properties:** `label`, `hint`, `helpText` (`help-text`, Shoelace alias), `errorText`
(`error-text`), `name` (empty by default, with the empty attribute omitted), live `value`, reflected
`defaultValue` (attribute `value`; Shoelace's `default-value` is also accepted), `customError`
(`custom-error`), `required`, `disabled`, `orientation: 'vertical' | 'horizontal' = 'vertical'`,
`withLabel`/`withHint` (`with-label`/`with-hint` SSR presence hints), `aria-label` (through
`accessibleLabel`; attribute presence wins, including `aria-label=""`, and suppresses the
visible-label `aria-labelledby` fallback), and `size: LyraSize = 'm'` (reflected) — the size of the
group's **own** chrome, on the shared ladder and accepting both `2xs`/`xs`/`s`/`m`/`l`/`xl` and
`small`/`medium`/`large`. It scales the group's label type size and the gaps around and between its
options off the same values the controls themselves use, and projects that tier to every owned
`<lr-radio>`/`<lr-radio-button>` child (including children added later). Group size and name are
authoritative through each option's `effectiveSize`/`effectiveName`, but never rewrite the child's
authored public properties or attributes; late child writes are restored immediately on removal or
reparenting.

When renaming `<sl-radio-group>` manually, set `name="option"` if the old markup relied on
Shoelace's implicit form-data key. Lyra deliberately defaults `name` to empty; the bundled migration
codemod inserts the compatibility value automatically.

The group is the sole aggregate form-associated owner. A non-empty selected value contributes one
`name=value` entry; owned radios suppress their own entries and validity while a standalone radio
continues to participate independently. `form`, `getForm()`, `labels`, native validity, external
form ownership, fieldset disablement, reset, and session restoration all live on the group.
`value` is non-reflecting live state; `defaultValue`/the `value` attribute is the current reset
default and cannot overwrite a dirty selection. Reset restores that current default, and session
restore selects the stored value silently even when it arrives before the radio children.
A required but pristine group keeps `aria-invalid="false"` on its internal radiogroup; the value
error is projected only after interaction or a native validity check (`checkValidity()`,
`reportValidity()`, or form-level validation), while explicit error chrome is immediate.

**Events:** per owned selection — including keyboard activation — the group emits, in order,
a bubbling/composed `InputEvent` named `input`, `lr-input`, a bubbling/composed `Event` named
`change`, then exactly one group-owned `lr-change`. The two native events carry no detail (read
`event.target.value`);
both prefixed aliases carry `{ value, radio }`. The selected child does not emit its standalone
value events. Ownership is resolved synchronously, so immediate removal restores standalone
behavior and immediate reparenting routes the event to the new group without waiting for a
mutation-observer turn. `lr-invalid` (no detail) is group-owned and fires when the group's validity
check fails; a consumer listening above the group does not receive a second prefixed alias from the
child validity owner.

**Slots:** default radios, `label`, `hint`, `help-text` (Shoelace hint alias), `error`.

**CSS parts:** `base`, `form-control`, `label` / `form-control-label`, `radios` /
`form-control-input` / `button-group` / `button-group__base`, `hint` /
`form-control-help-text`, and `error`.

**The required marker.** `required` with a non-empty group `label` paints the library's shared
marker on the `form-control-label` node — the one `::after` rule described under "The
required-field marker" above, not a copy of it, so `--lr-form-control-required-content`,
`--lr-form-control-required-color` and `--lr-form-control-required-offset` retune or suppress it
here exactly as they do on `lr-input`. It marks the **group**, not the individual radios: an owned
`<lr-radio>` has no label box of its own and paints nothing. With no group label text the node is
hidden and no glyph is painted.

**Themeable custom properties:** `--lr-radio-group-row-gap` (default
`calc(var(--lr-form-control-height) * 0.2)`) — the vertical gap between the group's label, its
options and its messages, scaled by `size` through the shared control ladder.

**Methods:** `setCustomValidity(message = '')` sets or clears a group-level consumer error. A
non-empty message raises `customError` and blocks submission; `setCustomValidity('')` and
`resetValidity()` restore the group's computed validity, including `valueMissing` when a required
group has no selected radio. `focus()` moves focus to the selected (or first enabled) radio;
`blur()` releases whichever owned radio currently contains deep focus, and `click()` mirrors
`focus()` by activating the selected/first enabled radio. All three are inert under direct or
fieldset disablement, so the group behaves like one native control.

## `lr-checkbox-group`

Long group labels, hints, errors, and horizontal option labels wrap within the host in both logical
directions. The `Narrow RTL long options (320px)` story is the adversarial baseline; checkbox
targets keep their own fixed hit-area floor while the surrounding text wraps.

A form-associated collection of `<lr-checkbox>` children. Its readonly `value` is a defensive
`string[]` snapshot; each
selected value is submitted under `name` and `required` requires at least one selection.

**Properties:** `label`, `hint`, `errorText`, `value`, `customError` (`custom-error`), `name`,
`required`, `disabled`, `orientation: 'vertical' | 'horizontal' = 'vertical'`,
`withLabel`/`withHint` (`with-label`/`with-hint` SSR presence hints),
`accessibleLabel` (`aria-label`), and `size?: LyraSize` (reflected) — the optional size of the group's
**own** chrome, on the shared ladder and accepting both `2xs`/`xs`/`s`/`m`/`l`/`xl` and
`small`/`medium`/`large`. It scales the group's label type size and the gaps around and between its
options. When set, it temporarily projects the tier to every owned `<lr-checkbox>`, including
children added later. When omitted, each child retains its own authored tier.

An explicit group `size` is owner state, not a destructive rewrite: late child-size writes are
remembered while the group remains authoritative, and removing the group size, moving an option
out, or disconnecting the group restores the latest authored child value. This matches Web
Awesome's unset-default behavior.

**Slots:** default checkboxes, `label`, `hint`, `error`.
**Events:** a user toggle emits exactly one group-owned `input`, then `change`, then `lr-change`;
all three carry `{ value: string[] }`. The owned child's corresponding events are consumed at the
group boundary, so an ancestor does not receive a second, differently shaped sequence.
Programmatic child `checked`/`value` synchronization is silent and completes synchronously, so a
same-task `new FormData(form)` or validity query observes the same state as the child.
`lr-invalid` (no detail) is the group's one bubbling/composed native-validity alias.
**Refusing a toggle.** `lr-checkbox-group-toggle-request` is cancelable and fires *before* the owned
option flips. `detail: { value: string[], previousValue: string[], option: LyraCheckbox }` carries
the group value that **would** result, the value as it stands, and the checkbox the user acted on.
`preventDefault()` keeps the current state, so the option never flips at all rather than flipping
and snapping back — which is what lets a host refuse "uncheck the last remaining option"
(`detail.value.length === 0`) with no flicker — and no `input`/`change`/`lr-change` follows.
Assigning the group's `value` from a listener resolves the request the same way. The owned
checkbox's own `lr-checkbox-toggle-request` is consumed at the group boundary and republished under
this name, so an ancestor never receives two veto points for one interaction. The detail is a
detached, frozen snapshot; `option` is kept by identity. `LyraCheckboxGroupToggleRequestDetail` is
its exported interface — see **Exported TypeScript contracts** below for the full signature.
**Methods:** `getForm()` returns the group's owning form, including an external owner selected by
`form`. `setCustomValidity(message)` sets or clears a consumer-supplied error ("that
combination of topics is not available"): a non-empty message raises `customError` and blocks
submission, `''` restores the group's own computed validity so a required group with nothing checked
goes back to `valueMissing`. It survives every child toggle, slot change and form reset.
Session restore uses a `FormData` state containing the repeated selected strings; it is independent
of the control's current `name`, preserves duplicate-value cardinality, waits for early-arriving
option children, and falls back to an empty selection for malformed state. Restoration is silent.
`focus()` targets the first enabled checkbox, `blur()` releases whichever owned checkbox contains
focus, and `click()` activates (toggles) the first enabled checkbox. Native validity UI anchors to
that checkbox's focusable semantic owner. A required group also leases a localized visually-hidden
aggregate requiredness description onto its fieldset without replacing hint/error IDs; it does not
incorrectly mark every child checkbox required.
The fieldset exposes explicit stateful `aria-invalid`: visible property/slotted error chrome makes
it `"true"` immediately; otherwise only interacted intrinsic/custom invalidity does so, and the
valid/pristine state is explicitly `"false"`.
**CSS parts:** `form-control`, `form-control-label`, `options` / `form-control-input`, `hint`,
`error`.
**Disabled chrome.** A disabled group — its own `disabled` or an ancestor `<fieldset disabled>` —
dims `form-control-label`, `hint` and `error` to `--lr-opacity-disabled`. The dimming is keyed off
the UA-computed `:disabled` state (so the fieldset cascade reaches it) and is deliberately applied
to those three parts rather than the host: each owned `<lr-checkbox>` already dims itself, and a
host-level opacity would compound with it.
**The required marker.** `required` with a non-empty group `label` paints the library's shared
marker on `[part="form-control-label"]` — here the `<legend>` of the group's fieldset. It is the
one `::after` rule described under "The required-field marker" above, not a copy of it, so
`--lr-form-control-required-content`, `--lr-form-control-required-color` and
`--lr-form-control-required-offset` retune or suppress it here exactly as they do on `lr-input`. It
marks the **group**, not the individual checkboxes: an owned `<lr-checkbox>` has no label box of
its own and paints nothing. With no group label text the legend is hidden and no glyph is painted.

**Themeable custom properties:** `--lr-checkbox-group-row-gap` (default
`calc(var(--lr-form-control-height) * 0.1)`), the vertical gap between the group's label, options
and messages, and `--lr-checkbox-group-option-gap` (default
`calc(var(--lr-form-control-height) * 0.2)`), the gap between adjacent options — both scaled by
`size` through the shared control ladder. WA's `--gap` alias is the value used by the rendered
option layout and defaults to `--lr-checkbox-group-option-gap`.
`--lr-checkbox-group-invalid-border` (default `var(--lr-color-danger)`) independently retints the
invalid option-collection border without changing other danger-colored surfaces.

**`value` reads as a frozen defensive snapshot of child state, and assigning it mirrors back onto
the children.** The children remain the single source of truth. An internal sync recomputes `value`
on every child toggle, programmatic child `checked`/`value`/`disabled` update, `slotchange`,
`name`/`required` change, blur, and `form.reset()`. Mutating an obtained array cannot mutate the
group — assign a new array instead.
Only a checkbox whose nearest `lr-checkbox-group` ancestor is this group contributes; a nested
group owns its own descendants and form entries. `connectedCallback()` runs that sync before the
first render.

Assigning checks every child whose `value` (defaulting to `'on'`) appears in the array and unchecks
every other one; duplicate entries check that many same-valued children, and values naming no child
are ignored. `null`/`undefined` clear the selection. It is controlled input, so it emits no
`lr-change` — only user interaction does. An assignment made before the children exist (the shape of
a `.value=${...}` binding on first render) is applied once they arrive.

- **To preselect**, either set `checked` on the children (`<lr-checkbox value="a" checked>`) or
  assign the group's `value`.
- **To read the selection**, use this property or the `lr-change` event detail.
- **Give every child a distinct `value`.** `<lr-checkbox>`'s `value` defaults to `'on'`, so a group
  of undifferentiated children submits several identical `FormData` entries and the submitted data
  cannot say which one was checked. The group warns once per duplicated value when it sees this.
- Assignments migrate to writes on the intended children's `checked` state; a host value such as
  `['on']` cannot identify which default-valued occurrence was intended.

## `lr-token-input`

An editable form-associated token list. Enter, comma, Tab, or blur commits a token; Tab is not
prevented, so focus still advances normally. Backspace removes the last token. `value` is a
readonly owned `readonly string[]` snapshot and repeated values are submitted under `name`; mutate
a new array and reassign it to change the list.

Composing keyboard events (`isComposing` or legacy key code 229) remain with the native draft or
inline editor without adding/removing tokens, committing an edit or closing the editor. Normal
Enter, delimiter, Tab, Backspace and Escape behavior is unchanged after composition.

Host `aria-describedby` references resolve in the host's root and precede local hint/error guidance
on the native draft input. Live source replacement, removal, reinsertion, host reconnection and
document adoption update the relationship. Removing `label`, `hint` or `error-text` safely removes
that copy while preserving native attribute-removal property readback, including `null`; explicit
empty and later replacement strings remain supported.

Editable token labels vertically center their text within the existing pointer target while
retaining narrow-content ellipsis, wrapping and alignment with the remove action. The ordinary
noneditable token layout remains the default.

**Properties:** live, non-reflecting `value`, reflected `defaultValue` (attribute `value`, encoded
as a JSON string array), `customError` (`custom-error`), `label`, `hint`, `errorText`
(`error-text`), `placeholder`, `name`,
`required`, `disabled`, `accessibleLabel` (attribute `aria-label` — forwarded to the input wrapper
and draft text input; precedence is presence-based, so `aria-label=""` remains an explicit empty
override and suppresses visible-label linkage), `spellcheck: boolean = true`, `autocapitalize: string = ''`, and `autocorrect` (read: `boolean = true`; write: `boolean | string`, attribute values
`on`/`off`) — all three native text-entry hints are forwarded to both the draft input and the inline
token editor. The former camel-case `autoCorrect` property is removed; use the native-shaped
lowercase IDL. `size: '2xs' | 'xs' | 's' | 'm' | 'l' | 'xl' = 'm'` (reflected —
same scale as `lr-input`'s `size`, scaling the input-wrapper's row height and text size across six
tiers, and both `2xs`/`xs`/`s`/`m`/`l`/`xl` and `small`/`medium`/`large` are accepted; the remove
button's hit area stays fixed at `40px` across all sizes), `pill` (reflected, default `false` —
rounds the token row's corners by changing the private radius default to `--lr-radius-pill`; the
chips share the public `--lr-token-input-radius` hook with the row, and an inherited or direct
value remains authoritative),
`allowDuplicates`
(`allow-duplicates`, default `false`), `editable` (reflected, default `false` — see below), and
`delimiter: string | null` (default `','` — see below).
**Slots:** `label`, `hint`, `error`, `start` (adornment before the tokens), `end` (adornment after
the draft input) — both wrapped in a `hidden`-toggling span, mirroring `lr-combobox`'s identical
`start`/`end`.
**Events:** native `InputEvent` `input`, `lr-input`, native `Event` `change`, then `lr-change` for
each list mutation; native events have no detail and both aliases carry a frozen
`{ value: readonly string[] }` snapshot.
Native `FocusEvent` `focus`/`blur` are relayed once from the draft and inline editor, preserving
`relatedTarget`. `lr-add`
(`detail: { value, values }`, where `value` is the final added token and `values` is the frozen,
readonly, complete ordered and deduplicated set of tokens added by that commit — cancelable as of
10.0.0; `preventDefault()` keeps the tokens out of `value` and leaves the typed draft text in the
input unchanged so the user can correct it, rather than clearing it),
`lr-remove`
(`detail: { value, index }` — cancelable; `preventDefault()` keeps the token in `value`
unchanged), and `lr-token-edit`
(`detail: { value, previousValue, index }` — an existing token is about to be edited in place —
cancelable as of 10.0.0; `preventDefault()` keeps the token in `value` unchanged and leaves the
inline editor open with the user's edited text intact, rather than closing and discarding it).
All three mutators now share one veto contract; previously only `lr-remove` could be vetoed.
`lr-invalid` (no detail) is emitted once as a bubbling/composed alias when native validity fails.
**CSS parts:** `form-control`, `form-control-label`, `input-wrapper`, `token`, `token-label` (the
token's text, doubling as the roving-focus edit trigger — rendered only while `editable`),
`token-editor` (the inline text field that replaces a token's text while it is open for editing —
rendered only while `editable` and only for the token being edited), `remove` (the
per-token remove button, floored at the shared `--lr-icon-button-size` tap size around a compact
glyph), `input`, `start`, `end`, `hint`, `error`. `focus()`, `blur()`, `click()`, and `select()` forward to the
internal draft text input. `selectionStart`, `selectionEnd`, and `selectionDirection` are readable/
writable native-selection passthroughs; `setSelectionRange(start, end, direction?)` and
`setRangeText(replacement, start?, end?, selectMode?)` expose the matching native methods.
`setRangeText()` synchronizes the pending draft without emitting `input`/`change`, so the next
delimiter, Enter, or blur commit consumes the edited text. `getForm()` returns the browser-resolved
owning form. `setCustomValidity(message)` carries a
rejection no client-side constraint can express
("that tag is reserved"): a non-empty message raises `customError` and blocks submission, `''`
restores the control's own computed validity so a `required` control with no tokens goes back to
`valueMissing`. It survives every token add, removal and edit, and a `form.reset()`.

`defaultValue` is the current reset target. A live `value` write marks the token list dirty, so a
later default/attribute mutation does not overwrite it; `form.reset()` restores the latest default
and makes the value pristine again. Session restoration uses repeated entries in a `FormData`
state, is independent of the current `name`, accepts early delivery, rejects malformed/file state
to an empty list, and emits no user events.

**`editable` — editing a token in place.** Off by default, in which case the token row renders
exactly as it does without the feature and stays non-focusable. Turn it on and each token becomes a
roving tab stop (one Tab stop for the whole row): click, Enter, Space, or F2 opens an inline
editor on that token; ArrowLeft/ArrowRight move between tokens (swapped under RTL, since they mean
previous/next _visually_), Home/End jump to the first/last. Inside the editor, Enter commits and
returns focus to the token, Escape cancels (and is consumed rather than left to bubble, so an
enclosing dialog or popover does not also close), and blurring commits _without_ pulling focus
back — a blur means the user already aimed focus elsewhere. A changed inline edit commits and emits
its native/alias input-change sequence before the public native/alias blur sequence. Both the draft
and inline editor relay one native bubbling/composed host `focus` or `blur` event while their source
event stays internal.
`lr-token-edit` fires only for an edit
that actually changed something: a reverted, unchanged, emptied, or (under the default
`allowDuplicates = false`) duplicate-colliding edit is discarded silently, mirroring how a
duplicate draft is skipped rather than rejecting the whole entry. Own or fieldset-cascaded
disablement removes every token label's tabindex, renders `aria-disabled="true"`, retires any
internal focus/editor state, and suppresses enabled hover/active paint. Re-enabling renders
`aria-disabled="false"` and restores exactly one roving token stop.
Host `focus()` and `click()` are also synchronous no-ops under own or fieldset-cascaded disablement,
including the same task that sets `disabled` before Lit has updated the still-rendered native draft.
`blur()` remains available to release existing focus.
When a focused token label, editor, or remove action disappears through its own removal or a
controlled `value`/pristine `defaultValue` shrink, DOM focus moves to the nearest surviving
equivalent surface at the clamped index. If no token remains it moves to the draft input; a newer
explicit focus destination outside the component is never reclaimed.

**`delimiter` is nullable, and only a single character acts as a commit key.** It does two separate
jobs: it splits a committed draft into several tokens, and — _only when it is exactly one
character_ — it is the keystroke that commits the draft. A multi-character delimiter still splits a
pasted or committed draft, but no keystroke can ever match it, so nothing commits on typing.
Setting it to `null` disables both, so a token may contain the delimiter verbatim. **`delimiter="null"`
does not work** — that is the four-character string `null`. Use `delimiter="none"`, `delimiter=""`
(both of which the attribute converter maps to `null`), or a property binding
(`.delimiter=${null}`). Removing the attribute restores the `,` default.

**The required marker.** `required` with a non-empty `label` paints the library's shared marker on
`[part="form-control-label"]` — the one `::after` rule described under "The required-field marker"
above, not a copy of it, so `--lr-form-control-required-content`,
`--lr-form-control-required-color` and `--lr-form-control-required-offset` retune or suppress it
here exactly as they do on `lr-input`. It marks the control, not an individual token. With no label
text the part is hidden and no glyph is painted.

**Themeable custom properties:** `--lr-token-input-padding` (the input-wrapper padding, scaled by
`size`), `--lr-token-input-font-size` (the input-wrapper and token font size, scaled by `size`),
`--lr-token-input-control-min-height` (the input-wrapper's block-size floor, scaled by `size`),
`--lr-token-input-control-height` (exact input-wrapper height — undeclared by default, leaving the
`--lr-token-input-control-min-height` floor only; set it to a length to both floor and cap the row,
e.g. to pixel-match a sibling field in the same toolbar row). An uncapped row grows as tokens wrap.
A capped row explicitly clips inline overflow and becomes a block-axis scrollport, preserving every
wrapped token and 40px-floored remove/edit action instead of clipping them; keyboard focus scrolls
the destination token into view. `--lr-token-input-input-inline-size`
(the editable input's `flex-basis` inside the wrapped token row; undeclared by default, falling back
inline to `--lr-size-8rem`), `--lr-token-input-min-input-inline-size` (default `--lr-size-4rem`, the
floor that input keeps once tokens have consumed the row), and `--lr-token-input-editor-inline-size`
(default `--lr-size-6rem`, the inline size of the inline token editor opened by `editable`).

**Additional API surface:**

- `--lr-token-input-token-padding` — Per-token chip padding, scaled by `size`.
- `--lr-token-input-gap` — Gap between form/row children. Default: `var(--lr-space-xs)`.
- `--lr-token-input-token-gap` — Gap inside token chips. Default: `var(--lr-space-2xs)`.
- `--lr-token-input-radius` — Row/token corner radius. Default: `var(--lr-radius)`.
- `--lr-token-input-token-bg` — Token chip background. Default: `var(--lr-color-brand-quiet)`.
- `--lr-token-input-action-hover-bg` — Backwards-compatible aggregate edit/remove hover
  background. Default: `var(--lr-color-brand-quiet)`.
- `--lr-token-input-edit-hover-bg` / `--lr-token-input-edit-pressed-bg` — Editable token-label
  hover and pressed backgrounds. The hover hook falls back to
  `--lr-token-input-action-hover-bg`; the pressed hook defaults to its active-state mix.
- `--lr-token-input-remove-hover-bg` / `--lr-token-input-remove-pressed-bg` — Remove-action hover
  and pressed backgrounds, with the same aggregate-hover and active-state fallbacks.
- `--lr-token-input-focus-border-color` — Focused row border color. Default: `var(--lr-color-brand)`.
- `--lr-token-input-fill` — Resting input-row background, public since 16.0.0. Default:
  `var(--lr-color-surface)`.
- `--lr-token-input-border-color` — Resting input-row border color. Default:
  `var(--lr-color-border)`. The invalid and focused states keep their own hooks and still win
  over it.
- `--lr-form-control-focus-shadow` — The shared field halo, painted as a `box-shadow` while the
  row holds focus. Default: `none`. Additive — the focus outline and the focused border are
  never replaced by it.
- `--lr-token-input-invalid-border-color` — Invalid row border color. Default: `var(--lr-color-danger)`.

## `lr-code-editor`

Long translated form chrome wraps within the host, while long source stays reachable through the
editor's internal scroll extent instead of widening the page. The `Narrow RTL long content
(320px)` story covers both boundaries together.

`form.reset()` restores the default value and pristine interaction feedback. Required and custom
validity constraints remain; a required-empty editor is still invalid. Removing `label`, `hint`, or
`error-text` treats the removed value as absent for rendering while retaining native
attribute-removal property readback.

Host `aria-describedby` references resolve in the host root onto the native textarea before its
local error/hint guidance. Target replacement, removal, reinsertion, unresolved IDs, reconnect, and
adoption keep that relationship current.

Dependency-free, form-associated multiline code editor built around a native textarea, with an
optional line-number gutter. No syntax highlighting: `language` is metadata only.

**Properties:**

- `language: string = ''` — reflected on the host and projected onto the `editor` part as
  `data-language`; purely a consumer-reachable styling/metadata hook, nothing tokenizes the text
- `lineNumbers: boolean = true` (attribute `line-numbers`, reflected) — renders the `gutter` part,
  one row per `\n`-separated line
- `tabSize: number = 2` (attribute `tab-size`) — spaces inserted per Tab press and the tab width
  shared by the native textarea and text measurement. Explicit property/attribute assignment wins
  over `--lr-code-editor-tab-size`; otherwise the token controls the rendered tab width. Sanitized
  on assignment to a finite integer clamped to `1..16`, so a `NaN`/`Infinity` value can neither
  empty the insert nor throw out of `String.repeat()`.
- `label: string = ''`, `hint: string = ''`, `errorText: string = ''` (attribute `error-text`),
  `placeholder: string = ''`
- `readonly: boolean = false` (reflected) — also disables Tab indentation
- `rows: number = 4`, `cols: number = 20`, `minlength?: number`, `maxlength?: number` — native
  textarea geometry and code-unit length constraints. Programmatic/restored values receive the
  same supplemental length validity as user edits.
- `resize: 'none' | 'both' | 'horizontal' | 'vertical' | 'auto' = 'both'` — written as the
  textarea's inline `resize`; `auto` grows the owned surface to its content without a manual drag
  handle. A consumer `max-block-size` on the `textarea` part caps that growth and restores vertical
  scrolling; changing away from `auto` clears its inline block-size and overflow state. An invalid
  runtime value falls back to `'both'`
- `size: LyraSize = 'm'` (reflected) — visual size on the shared control ladder, the same scale as
  `lr-textarea`/`lr-input`/`lr-select`, accepting both spellings of every tier (`2xs`/`xs`/`s`/`m`/
  `l`/`xl` and `small`/`medium`/`large`). Governs the gutter's and textarea's padding and font size,
  plus the editor frame's minimum block size.
- `wrap: 'off' | 'soft' | 'hard' = 'off'` — native textarea wrapping. `'off'` (the default) makes
  the `editor` part the single horizontal scroll viewport. Soft/hard text wraps within the editor
  allocation, with the caret and logical line-number gutter following the wrapped lines as the
  allocation changes; the editor frame owns scrolling. `hard` uses the owner realm's native
  textarea serializer, so FormData receives platform-equivalent `cols` wrapping while the live
  `value` remains unwrapped.
- `spellcheck: boolean = false` — off by default for code, and parsed with a string-aware converter
  so `spellcheck="false"` really is `false`
- `autofocus: boolean = false`, `title: string = ''`, `autocomplete: string = ''`,
  `inputMode`/`inputmode: string = ''`, `enterKeyHint`/`enterkeyhint: string = ''`,
  `autocapitalize: string = 'off'`, and `autocorrect: boolean = false` (attribute vocabulary
  `on`/`off`; boolean and string writes normalize through the shared native converter)
- `accessibleLabel: string = ''` (attribute `aria-label`) — wins over `label`/the localized
  `codeEditorLabel` fallback on the internal textarea
- The shared form surface adds `value`, `defaultValue`, `customError` (`custom-error`), `name`,
  `disabled`, `required`, `form`, `getForm()`, `checkValidity()`, `reportValidity()`, and
  `setCustomValidity()` / `resetValidity()`. The latter clears only consumer custom validity and
  restores current intrinsic constraints; it does not change the value/default or prior
  interaction state.

**Methods:** `focus(options?)`, `blur()`, `select()`, `setSelectionRange(start, end, direction?)`,
`setRangeText(replacement, start?, end?, selectMode?)` (writes the result back into `value` without
emitting an event), and `scrollPosition()` / `scrollPosition({top?,left?})`. The `input` getter
returns the owned native textarea after render. `selectionStart`, `selectionEnd`, and
`selectionDirection` use native nullable sentinels before that surface exists.
`scrollPosition()` reads or writes `[part="editor"]`'s top/left offsets: the gutter and caret share
that single scroll owner rather than a private textarea scroll position.
The native textarea receives the actual `required` state. Its `aria-invalid` is true whenever
visible property/slotted error chrome exists, or after interaction while native validity fails;
showing error chrome alone does not mutate `ElementInternals` validity.

**Events:** exactly one realm-correct native `input`, `change`, `focus`, and `blur` is relayed from
the internal textarea; native payload such as `InputEvent.inputType` and
`FocusEvent.relatedTarget` is preserved. Typed `lr-input`/`lr-change` aliases carry
`detail: { value }`. `lr-invalid`
(no detail) fires once when validity fails.

**Slots:** `label`, `hint`, `error`.

**CSS parts:** `form-control`, `label` / `form-control-label` (both tokens sit on the same `<label>`
element — `label` is the historical name, `form-control-label` the one every other form component
in this family uses), `editor` (the bordered frame and the single scroll viewport), `gutter` (line
numbers, `aria-hidden`, only when `lineNumbers`), `textarea`, `hint`, `error`.

**The required marker.** `required` with a non-empty `label` paints the library's shared marker on
that label element — the one `::after` rule described under "The required-field marker" above, not
a copy of it, so `--lr-form-control-required-content`, `--lr-form-control-required-color` and
`--lr-form-control-required-offset` retune or suppress it here exactly as they do on `lr-input`.
With no label text the element is hidden and no glyph is painted.

**Themeable custom properties:** `--lr-code-editor-min-block-size` (default `--lr-size-8rem`, the
frame's and textarea's height floor), `--lr-code-editor-padding` (default `--lr-space-s`, the
gutter's block-side padding and the textarea's all-side padding), and `--lr-code-editor-font-size`
(default `--lr-font-size-m`, the gutter's and textarea's font size) — all three come from the active
`size` tier by default, and assigning one directly overrides that tier's value. Also
`--lr-code-editor-line-height` (default `1.5`, applied to both gutter and textarea so line numbers
stay aligned with their lines).
`--lr-code-editor-tab-size` (default `2`) is read by the `textarea` part's rule and drives both the
rendered tab stops and the number of spaces Tab inserts. Precedence, highest first: an explicitly
assigned `tabSize` (property or `tab-size` attribute) > a host-level `--lr-code-editor-tab-size` >
the `:host` default of `2`. The component writes the token inline on the `textarea` part only while
`tabSize` has been assigned, so an untouched `tabSize` leaves your override in charge; removing the
`tab-size` attribute hands control back to the token. A length-valued override (`40px`, `2ch`, …)
still sets the visual tab stops for literal tab characters, but is not reinterpreted as a count of
spaces — the Tab key keeps inserting `tabSize` spaces in that case.
`--lr-code-editor-border` (default `var(--lr-color-border)`) and `--lr-code-editor-fill` (default
`var(--lr-color-surface)`) retint the frame's resting border and background, independent of the
hover and invalid states below.
`--lr-code-editor-hover-border` (default `var(--lr-color-brand)`) and
`--lr-code-editor-invalid-border` (default `var(--lr-color-danger)`) retint those frame states
without changing brand/danger paint in sibling components.
The `editor` scroll frame also honors the opt-in theme-level
`--lr-theme-scrollbar-width`/`--lr-theme-scrollbar-gutter` hooks (defaults `auto`/`auto`, matching
its previous unconditional `scrollbar-width: auto`) — set either on `:root` or any ancestor for one
declaration to retheme every internal scroll container in the library, including `lr-table`,
`lr-virtual-list`, `lr-scroller`, `lr-carousel`, and `lr-code-block`.

**Known gotchas:**

- Keyboard contract (no keyboard trap, WCAG 2.1.2): Tab inserts one indent unit of spaces at the
  caret (see the tab-width precedence above);
  Shift+Tab is never captured, so reverse focus traversal always works; pressing Escape releases
  the _next_ Tab for forward traversal instead, and any other keypress (or focus leaving the
  editor) re-arms Tab indentation.
- The host gets a `data-invalid` attribute once the field has been blurred at least once and
  validity fails; the styles hang the danger border off it.
- Public/default/restored CR and CRLF sequences normalize once to LF, matching the native
  textarea's value, gutter line count, selection offsets and ordinary FormData state.

**Additional API surface:** `click()` activates the internal editing surface.

## `lr-color-picker`

A form-associated colour picker with label, hint and error chrome: a compact swatch trigger that
opens a popover holding a saturation/brightness grid, a hue slider, an optional alpha slider, a text
field accepting any parseable CSS colour, an optional predefined palette, and — where the browser
supports it — a screen eyedropper.

Host `aria-describedby` references resolve in the host's root and precede the trigger's local error,
hint and current-value guidance. Same-ID target replacement, removal, reinsertion, reconnection and
document adoption keep those relationships current. Inline mode has no trigger.

Own or fieldset disablement discards an unfinished native text draft without committing it and
blocks palette/format actions immediately, including before disabled rendering settles. A valid
enabled draft still commits on normal blur or Enter. Format changes retain their existing
programmatic event silence. Pointer and eyedropper cancellation behavior remains unchanged.

**Rewritten in 8.0.0.** It used to wrap a bare native `<input type="color">`; it is now a real
picker built from the pieces above. Two consequences for existing code:

- **`::part(input)` now names the panel's text field, not the swatch.** The swatch is
  `::part(trigger)`. A stylesheet that targeted `input` to size or tint the visible control has to
  move to `trigger`.
- In popup mode the visible control is a `<button>` (`[part="trigger"]`): `focus()` targets it and
  `click()` activates it, toggling the popup. There is no native colour input in the shadow tree to
  reach for. Inline mode has no trigger; `focus()` targets the grid handle and `click()` activates
  the editable value field. In either mode `blur()` blurs whichever internal control is active.

`value` is always serialized in the active `format` (`hex` by default), so reading it back after any
interaction gives a canonical string in exactly one syntax; switching `format`, `opacity` or
`uppercase` **re-serializes the same colour** rather than reinterpreting it. Input is far more
permissive than output: hex (3/4/6/8 digit), `rgb()`/`rgba()`, `hsl()`/`hsla()`, `hsv()`/`hsva()`,
CSS colour names, and any other colour syntax the browser itself parses are all accepted. A value
that is not a colour at all is **kept verbatim** rather than silently replaced, so a consumer's own
sentinel survives a round trip. The public `value` and `defaultValue` both default to the empty
string, matching the mirrored form contract; the uncommitted preview and editable field still begin
at black (`#000000`). A bare `required` picker is therefore value-missing, and `form.reset()` returns
to the declarative value or to empty when none was supplied.

Colour is never the only channel carrying state: the trigger's `aria-describedby` points at a
visually-hidden span spelling the current value out in text, the panel shows it in an editable
field, and the selected palette swatch is marked with `aria-pressed` plus a check mark rather than
a tint alone.

Validation is projected onto both editing owners with an explicit stateful `aria-invalid`. A
required empty picker starts pristine, so the popup trigger and panel value input both expose
`aria-invalid="false"` even though `checkValidity()` is false. Once focus leaves the control, the
resulting `user-invalid` state changes both to `"true"`; `reportValidity()` reveals the same state
without requiring a blur. A valid value or `form.reset()` clears the projection back to `"false"`,
while visible error content makes it `"true"`. Inline mode omits the trigger, but its value input
follows the same pristine/user-invalid contract.

**Not the same control as `lr-swatch-picker`.** This one is freeform: `swatches` is a shortcut row
_beside_ a saturation grid, a hue ramp and a text field, and the committed value can be any colour
the browser parses. `<lr-swatch-picker>` offers exactly its `options` and nothing else, with
`radiogroup` semantics rather than a popover. Reach for it when the answer must be one of N
designer-chosen colours; reach for this when it must not.

**Properties:** the shared
form properties `name`, `value`, `defaultValue` (canonical content attribute `value`),
`customError` (`custom-error`), `disabled`, and
`required`, plus `label`, `hint`, `errorText`
(`error-text`), `accessibleLabel` (`aria-label`), and `size: LyraSize = 'm'`
(reflected — the same visual-density scale as `lr-input`, applied to the centered visible swatch;
accepts `2xs`/`xs`/`s`/`m`/`l`/`xl` and `small`/`medium`/`large`; the interactive target
independently retains the `--lr-icon-button-size` floor),
and:

- `format: 'hex' | 'rgb' | 'hsl' | 'hsv' = 'hex'` — the syntax `value` is **written** in. Parsing is
  always permissive regardless of it. The format button cycles through the four in that order
- `opacity: boolean = false` — enables the alpha channel: an opacity slider appears in the panel and
  the serialized value gains its alpha-carrying twin (`hexa`/`rgba`/`hsla`/`hsva`). With it unset,
  picking a palette entry forces alpha back to 1
- `uppercase: boolean = false` — serializes `value` in upper case (`#FF0000` rather than `#ff0000`);
  applies to the whole string, function names included (`RGB(255, 0, 0)`)
- `swatches: string | string[] | LyraColorPickerSwatch[] = ''` — a predefined palette, given as a
  `;`-separated string, an array of colour strings, or an array of
  `{ color: string; label?: string; disabled?: boolean }` objects. Any colour the picker can parse
  is accepted; blank entries are dropped. An entry that is _not_ parseable is kept in the list and
  still renders a swatch — it just paints no colour (the bare checkerboard) and clicking it does
  nothing, so filter the palette yourself if that matters. `label` becomes the swatch's accessible
  name; a missing, empty, or whitespace-only label falls back to announcing the raw colour string.
  `disabled` marks that one swatch non-actionable, independent of the whole control's own
  `disabled`: it renders a genuinely disabled `<button>` (no tab stop, no hover/press affordance)
  and clicking it commits nothing; omitted or `false` renders the swatch exactly as before this
  field existed. The palette container renders only while the normalized list is non-empty
- `withoutFormatToggle: boolean = false` (attribute `without-format-toggle`) — removes the button
  that cycles between formats. `noFormatToggle` (`no-format-toggle`) is the Shoelace spelling and
  reaches the same behavior; either one wins
- `inline: boolean = false` (reflected) — renders the full panel in normal flow and omits the popup
  trigger. In this mode `focus()` targets the grid handle and `click()` targets the value field.
  The panel stays visible regardless of `open`; `show()`/`hide()` still update that lifecycle state
  and its events so switching back to popup mode has a deterministic result
- `hoist: boolean = false` (reflected) — uses fixed popup positioning to escape clipping
  ancestors; the default absolute strategy stays in the component's local scrolling context
- `positioningStrategy: PlaceStrategy = 'absolute'` (attribute `positioning-strategy`, reflected) —
  see `<lr-popover>` (`llms/components/lr-popover.md`): the one property `<lr-popover>`,
  `<lr-dropdown>`, `<lr-select>`, `<lr-tooltip>` and `<lr-color-picker>` all spell the same way,
  `'absolute' | 'fixed'`. `absolute` is this control's mirrored default and keeps the panel in the
  component's local scrolling context; `fixed` escapes most clipping ancestors. An unsupported value
  resolves back to the default, and a change applies live while the panel is open.
  `hoist: boolean = false` is its retained exact alias (`hoist` ⇔ `positioning-strategy="fixed"`);
  writing either spelling updates the other, so the two attributes can never disagree. Prefer
  `positioning-strategy` in new code. This property always reports the instance's own authored
  value (or the mirrored default); when neither spelling is authored, the panel is actually placed
  with the cascading `--lr-positioning-strategy` custom property honored ahead of that default —
  see **Themeable custom properties** below
- `withLabel: boolean = false` (`with-label`, reflected) and `withHint: boolean = false`
  (`with-hint`, reflected) — SSR hints that the corresponding slots are populated, so their chrome
  is present before client-side slot observation
- `placement: Placement = 'bottom-start'` (reflected) — preferred panel placement, from the Floating
  UI vocabulary. The resolved side still flips/shifts to stay in the viewport, and the
  `left`/`right` component is swapped under RTL
- `open: boolean = false` (reflected) — whether the popup panel is open. Assigning `true` while the
  control is effectively disabled is ignored, and a `disabled` that flips on while the popup is
  already open closes it. Inline rendering remains visible at either value

**Methods:** `show()` opens the popup (a no-op while effectively disabled), and `hide()` closes it
and returns focus to the trigger. In popup mode `click()` activates the trigger and therefore
toggles the popup, while `focus(options?)` targets that trigger. Inline mode has no trigger:
`click()` activates the editable value field and `focus(options?)` targets the grid handle.
`blur()` blurs the active internal control in either mode; `click()` and `focus()` are inert while
effectively disabled. In inline mode `show()`/`hide()` update `open` and lifecycle events without
hiding the in-flow panel.
`getFormattedValue(format?)` returns the current colour in any of the eight output formats —
`'hex' | 'hexa' | 'rgb' | 'rgba' | 'hsl' | 'hsla' | 'hsv' | 'hsva'`, defaulting to `'hex'` —
independently of `format`/`opacity`, honouring `uppercase`. Use it to read, say, an `rgba()` string
out of a picker configured to store hex, without touching `value`.
`getHexString(hue, saturation, brightness, alpha = 100)` converts percent-scaled HSV(A) channels
to six-digit hex, or eight-digit hex when alpha is below 100, honoring `uppercase`.
The shared form methods are
`getForm()`, `checkValidity()`, `reportValidity()`, `setCustomValidity(message)`, and
`resetValidity()`. `resetValidity()` clears only consumer-supplied custom validity and recomputes
the current intrinsic constraints; it leaves `value`/`defaultValue` and prior interaction state
unchanged.

**Slots:** `label`, `hint`, `error`. Slotted label text replaces the `label` property's visible text
and names both the trigger and dialog; a host `aria-label` remains the strongest naming override.

**Events:** each serialized value-changing edit emits a bubbling/composed native `InputEvent` named
`input`, followed by the no-detail `lr-input` compatibility alias. A completed interaction emits
one bubbling/composed native `Event` named `change`, followed by `lr-change` with
`detail: { value }`. The commit pair occurs on pointer release, key release, swatch click, an
accepted text-field change/Enter, or an eyedropper result. A drag or repeated key can therefore
emit several `input`/`lr-input` edit pairs but only one `change`/`lr-change` commit pair.
Pointer drags are reversible previews: `pointercancel`, lost pointer capture, mid-gesture
disablement, disconnection, or document adoption restores the pre-gesture colour and submitted
form value without emitting another `input` or a commit pair. A direct consumer `value` assignment
during a drag is authoritative instead: it retires the gesture and remains current.
Also emitted are `lr-show` / `lr-after-show` and `lr-hide` / `lr-after-hide` (the panel opened
or closed — never emitted for a declaratively-open picker's first render, nor for a close caused by
disconnection; because this panel has no opening animation, each `lr-after-*` immediately follows
its matching lifecycle event in the completed update), and `focus`/`blur`
(exactly one bubbling/composed native `FocusEvent` relay when focus
enters or leaves the internal controls in either popup or inline mode), and `lr-invalid`
(no detail) once when native validity fails. A change that
doesn't move the serialized value emits nothing, so dragging within a single rounded colour is
silent.

**Keyboard.** The grid handle, hue handle and opacity handle are each a real `role="slider"` with a
localized name and `aria-valuetext`. Arrow keys step by 1 (percent or degree), Shift+Arrow by 10,
and Home/End jump to that axis' extremes; ArrowLeft/ArrowRight swap meaning under RTL, ArrowUp/Down
never do. One discrete press pairs a keydown (`input`/`lr-input`) with a keyup
(`change`/`lr-change`); OS key repeat re-fires the edit pair but still commits once. The panel is
Escape-dismissible and returns focus to the trigger; a pointerdown outside the element closes it
too. Both routes are topmost-aware through the shared nonmodal overlay stack, so an older color
picker remains open under a newer Lyra popup and receives the manager's focus handoff when that top
layer closes.

**CSS parts:** `base` (permanent compatibility name on the same field wrapper as `color-picker`),
`color-picker` (the field wrapper; it is the same node as `base` and `form-control`),
`form-control` (the field wrapper; it is the same node as `base` and `color-picker`),
`form-control-label` (the label; `label` is its permanent compatibility name), `trigger-container`
(the row wrapping the trigger), `trigger` (the swatch button that
opens the panel), `panel` (the positioned `role="dialog"` surface), `grid` (the
saturation/brightness square) and `grid-handle` (its draggable, keyboard-operable handle),
`slider` and `slider-handle` (carried by **both** ramps), `hue-slider` / `hue-slider-handle` and
`opacity-slider` / `opacity-slider-handle` (each also carrying the shared `slider`/`slider-handle`
token, so `::part(slider)` styles both ramps while `::part(hue-slider)` reaches only one; the
opacity pair renders only with `opacity` set), `preview` (the current-colour dot beside the ramps),
`input` (the text field holding the serialized value), `format-button` (the format-cycling button,
absent with either format-toggle suppression property), plus `format-button__base`,
`format-button__start`/`format-button__prefix`, `format-button__label`,
`format-button__end`/`format-button__suffix`, and `format-button__caret`;
`eyedropper-button` / `eye-dropper-button` (rendered only where the browser exposes the EyeDropper
API), with the corresponding `eyedropper-button__base|start|label|end|caret` and Shoelace
`eye-dropper-button__base|prefix|label|suffix|caret` aliases; `swatches` (the palette container, rendered only when the normalized `swatches`
list is non-empty), `swatch` (one palette entry), `swatch-selected` (a token **added to** the
swatch matching the current value — state after `::part()` never matches, so write
`::part(swatch-selected)`), `hint`, `error`.

The eyedropper aliases are also addressable individually as `eyedropper-button__base`,
`eyedropper-button__start`, `eyedropper-button__label`, `eyedropper-button__end`,
`eyedropper-button__caret`, `eye-dropper-button__base`, `eye-dropper-button__prefix`,
`eye-dropper-button__label`, `eye-dropper-button__suffix`, and `eye-dropper-button__caret`.

**The required marker.** `required` with a non-empty `label` paints the library's shared marker on
`[part="form-control-label"]` — the one `::after` rule described under "The required-field marker"
above, not a copy of it, so `--lr-form-control-required-content`,
`--lr-form-control-required-color` and `--lr-form-control-required-offset` retune or suppress it
here exactly as they do on `lr-input`. With no label text the part is hidden and no glyph is
painted.

**Themeable custom properties:** `--lr-color-picker-swatch-size` sizes the centered visible swatch,
not the button's minimum target. Its private default follows `size` (default `'m'` reads `2.5rem`,
`'2xs'` reads `1.25rem`, etc.), matching the visual-density ladder `lr-input` uses. The trigger's
inline and block sizes are each
`max(var(--lr-color-picker-swatch-size), var(--lr-icon-button-size))`: compact tiers center a smaller
swatch inside the shared hit-area floor, while a larger swatch expands the target with it. The
panel's geometry has its own public hook set; each hook inherits from an ancestor, and a direct host
value wins:

- `--lr-color-picker-grid-inline-size` (default `var(--lr-size-15rem)`) and
  `--lr-color-picker-grid-block-size` (default `var(--lr-size-8rem)`) — the saturation/brightness
  square's width and height. The first also caps the palette row's width.
- `--lr-color-picker-grid-handle-size` (default `var(--lr-size-1rem)`) — diameter of the grid handle.
- `--lr-color-picker-slider-block-size` (default `var(--lr-size-0-75rem)`) — thickness of the
  **visible** hue/opacity ramp. The slider's own pointer target stays floored at 24px regardless, so
  thinning the ramp never shrinks the touch target.
- `--lr-color-picker-slider-handle-size` (default `var(--lr-size-1-25rem)`) — diameter of a slider
  handle.
- `--lr-color-picker-palette-swatch-size` (default `var(--lr-size-1-5rem)`) — size of a palette
  swatch, and of the `preview` dot.
- `--lr-color-picker-checker-color` (default `var(--lr-color-border)`) and
  `--lr-color-picker-checker-size` (default `var(--lr-size-0-5rem)`) — tint and cell size of the
  alpha checkerboard drawn behind the trigger, preview, swatches and opacity ramp.
- `--lr-color-picker-hue-stops` — the hue ramp's own gradient stops, defaulting to the six-stop sRGB
  hue wheel. Both text directions read the same list; only the gradient's direction differs.
  Override it to theme a wide-gamut or perceptually-uniform ramp.

The upstream aliases `--grid-width`, `--grid-height`, `--grid-handle-size`, `--slider-height`, and
`--slider-handle-size` feed the corresponding Lyra geometry properties above; Shoelace's
`--swatch-size` feeds `--lr-color-picker-palette-swatch-size`. An explicit `--lr-*` value takes
precedence over its alias.

Three more are **state, not configuration** — the component rewrites each inline on every render, so
setting them from a stylesheet has no lasting effect: `--lr-color-picker-swatch-color` (the live
colour painted on the trigger, preview, slider handles and palette swatches),
`--lr-color-picker-grid-hue` (the grid's fully-saturated base hue), and
`--lr-color-picker-opacity-gradient` (the opacity ramp's transparent-to-opaque gradient, built from
the current colour and text direction). Read them if you need the resolved colour; don't assign them.

The popup panel is a floating surface and paints from the **shared overlay-surface family** (16.0.0):
`--lr-overlay-surface` (default `var(--lr-color-surface-overlay)`), `--lr-overlay-border` (default
`var(--lr-color-border)`) and `--lr-overlay-shadow-anchored` (default `var(--lr-shadow-m)`). None is
declared on `:host`, so one declaration on `:root` — or on any ancestor, to scope it — retints this
surface together with every other floating surface in the library. `--lr-overlay-radius` (default `var(--lr-radius)`) reaches it only as the middle arm of
`--lr-color-picker-radius`, which still wins when set.

`--lr-positioning-strategy` (16.0.0) is the same cascading `absolute`/`fixed` override
`<lr-popover>` (`llms/components/lr-popover.md`) documents, read from computed style each time the
panel is (re)positioned. An explicit `positioning-strategy`/`hoist` on the instance always wins
over it; otherwise it wins over this control's own mirrored `absolute` default. One declaration on
`:root`, a theme, or a single clipping ancestor changes every unset color picker beneath it instead
of authoring `positioning-strategy`/`hoist` on each instance.

**Additional API surface:**

- `click()` — In popup mode activates the trigger, opening or closing the panel; in inline mode
  activates the editable value field instead. It is a no-op while effectively disabled.
- `--lr-color-picker-gap` — Gap between field chrome and panel rows. Default: `var(--lr-space-xs)`.
- `--lr-color-picker-radius` — Trigger, grid, field and panel corner radius. Default: `var(--lr-radius)`.
- `--lr-color-picker-border-color` — Resting trigger border color. Default: `var(--lr-color-border)`.
- `--lr-color-picker-hover-border-color` — Hover border color, shared by the trigger, handles, text
  field, format/eyedropper buttons and palette swatches. Default: `var(--lr-color-brand)`.
- `--lr-color-picker-selected-border` — Selected palette-swatch border. Default:
  `var(--lr-color-brand)`.
- `--lr-color-picker-selected-check-color` — Checkmark on the selected palette swatch. Default:
  `var(--lr-color-surface)`.
- `--lr-color-picker-swatch-disabled-opacity` — Opacity of a palette swatch whose own entry sets
  `disabled`. Default: `0.5`.

```html
<lr-color-picker
  name="accent"
  label="Accent colour"
  hint="Used for links and primary buttons."
  format="rgb"
  opacity
  uppercase
  placement="bottom-end"
  swatches="#e11d48;#2563eb;#16a34a"
></lr-color-picker>
<script type="module">
  import "@aceshooting/lyra-ui/components/forms/color-picker/color-picker.js";
  const picker = document.querySelector("lr-color-picker");
  // Objects give each entry a real accessible name:
  picker.swatches = [
    { color: "#e11d48", label: "Rose" },
    { color: "#2563eb", label: "Blue" },
  ];
  picker.addEventListener("change", () => {
    console.log(picker.value); // e.g. "RGBA(225, 29, 72, 1.00)"
    console.log(picker.getFormattedValue("hexa")); // e.g. "#E11D48FF"
  });
  picker.show();
</script>
```

**Known gotchas:**

- **The `input` CSS part moved.** It is the panel's text field as of 8.0.0; the swatch is `trigger`.
- The eyedropper button is only in the DOM where `window.EyeDropper` exists (feature-detected once,
  at connect). Dismissing the eyedropper rejects the platform promise, which is treated as a
  cancellation, not an error — nothing is surfaced and nothing changes.
- A non-colour `value` is preserved verbatim, so `value` is not guaranteed to be parseable as a
  colour just because the element accepted it. `getFormattedValue()` always reports the picker's
  own working colour, which in that case is whatever was last understood.
- A disconnect/reconnect cycle (a drag-and-drop reparent, a virtualized list reordering) closes the
  panel rather than leaving it rendered at a stale, frozen position, and an abandoned half-typed
  entry in the text field is discarded rather than reappearing on the next open.

## `lr-emoji-picker`

A searchable, keyboard-navigable, form-associated emoji picker. `groups` is fully consumer-suppliable
— the component ships no emoji data of its own — in the same "zero/optional-peer dependency" spirit
as `<lr-lite-chart>`/`<lr-heatmap>`; an optional convenience auto-loader fetches a default set on
connect from the `emoji-picker-element-data` peer, but only when `groups` hasn't already been
supplied (an explicit empty array still counts as supplied and skips the auto-load).
When the filtered set reaches 200 items, the grid automatically windows its visible rows while
preserving the full option count through `aria-setsize`/`aria-posinset`.

Removing `label`, `hint`, or `error-text` treats the removed value as absent for rendering while
preserving native attribute-removal property readback. Host `aria-describedby` references resolve in
the host root onto the value-owning listbox before its local error/hint guidance. Target
replacement, removal, reinsertion, reconnect, and adoption keep that relationship current. The
search input keeps its separate description ownership.

`form.reset()` restores the default value and pristine interaction feedback. Required constraints
and persistent custom validity remain in force; a required-empty value remains invalid. Composing
key events (`isComposing` or legacy key code 229) remain with text editing and do not navigate or
pick an emoji.

Ships the same opt-in `label`/`hint`/`errorText` form-control chrome as `lr-select`/
`lr-color-picker` (props + matching named slots + `form-control`/`form-control-label`/`hint`/
`error` CSS parts) — left unset, none of that chrome renders.

Public `--lr-emoji-picker-*` theme inputs stay undeclared on the host, so an ancestor theme wrapper
can override size-tier fallbacks; a value set directly on the element still wins.

**Properties:** the shared form properties `name`, `value`, `defaultValue`, `customError`
(`custom-error`), `disabled`, and `required`, plus
`groups: readonly EmojiPickerGroup[] = []` (attribute: false) — readonly `EmojiPickerGroup { key,
label, emojis: readonly EmojiPickerItem[] }`, readonly `EmojiPickerItem { emoji, name,
shortcodes? }`; assignment captures a bounded frozen owned snapshot, including the current contents
of reused source item objects. Earlier snapshots remain frozen and unchanged; in-place source edits
become visible only after an explicit `groups` assignment. The search field matches
`name` and every `shortcodes` entry, case-insensitively. Consumer group labels render verbatim.
Groups returned by the built-in loader carry private provenance, letting their fixed emojibase
headings follow `registerLyraLocale()`/`.strings` through filtering and windowed rendering, including
same-locale `.strings` changes, without exposing localization keys as consumer data. Caller-authored
headings remain literal even when their keys match built-in groups. Empty (the default, before the auto-loader
resolves) renders just the search input and the empty state. `accessibleLabel` (`aria-label`)
forwards a host-supplied accessible name to the internal `role="listbox"` grid. Only omission falls
back to the visible label or localized default; an explicit `aria-label=""` remains empty.
`label: string = ''` — visible label rendered above the
search/grid; unset renders no label chrome. When `label` (or the `label` slot) is set and
`accessibleLabel`/a host `aria-label` is not, the grid's accessible name switches from the
localized default to `aria-labelledby` pointing at the visible label. `hint: string = ''` —
supporting text rendered below the search/grid; unset renders no hint chrome. `errorText: string =
''` (attribute `error-text`) — validation-error text rendered below the hint (overridden by slotted
`error` content when provided); unset renders no error chrome. `size: '2xs' | 'xs' | 's' | 'm' | 'l' | 'xl' = 'm'` —
visual size; scales the glyph and preferred emoji box while every interactive option remains
floored at the shared `--lr-icon-button-size`.

**Methods:** `focus(options?)`, `blur()`, and `click()` delegate to the search input/current owned
focus target, plus `getForm()`, `checkValidity()`, `reportValidity()`, `setCustomValidity(message)`, and
`resetValidity()` provide the shared form-validation surface. `resetValidity()` clears only
consumer-supplied custom validity and recomputes current intrinsic constraints; it does not change
`value`/`defaultValue`, clear prior interaction state, or force a required-empty picker valid.

**Events:** a pick emits native `InputEvent` `input`, `lr-input`, native `Event` `change`, then
`lr-change`; both aliases carry `detail: { value }`. The internal search input's `focus` and `blur`
are relayed once as native `FocusEvent`s preserving `relatedTarget`.
All four native events use the picker's current owner-document realm, including
after adoption. `lr-invalid` (no detail) is emitted once as a cancelable alias when native validity
fails; preventing it also prevents the native `invalid` event that produced it. Programmatic `value`
changes are silent.

**Keyboard:** the grid is a roving-tabindex listbox (a single Tab stop — only the active emoji is
tabbable). ArrowLeft/ArrowRight step the active item backward/forward following reading direction
(swapped under RTL), ArrowUp/ArrowDown move by one visual row (measured from the live wrap layout),
Home/End jump to the first/last item, and Enter/Space picks the active item. The search input is a
`role="combobox"` over the same listbox: the arrow keys and Enter also work while focus stays in
the input, with `aria-activedescendant` tracking the active option. Hovering an emoji with the
pointer also moves the active item to it. When a controlled `groups` replacement removes the
focused option, focus moves to the nearest surviving option; when the same item object remains,
its identity wins even if it moved. A replacement never pulls focus away from the search field or
an external control. In a windowed grid, roving navigation materializes an off-window target before
transferring focus, so End and long row jumps never strand focus on a removed virtual row.

**Slots:** `label` (custom label content), `hint` (custom hint content), `error` (custom error
content, overrides the `errorText` attribute when provided).

**CSS parts:** `form-control` (the outer wrapper around label, `base`, error and hint),
`form-control-label` (the visible label), `base`, `search-wrapper` (the row wrapper around
`search` and `search-clear`), `search` (`role="combobox"`), `search-clear` (clears the search
field, replacing the native search-cancel glyph the component resets; rendered only while it has a
value), `grid`
(`role="listbox"`, the scroll viewport), `group-label`, `emoji` (each emoji's own `role="option"`
button), `empty` (shown when the search matches nothing, or when a consumer deliberately opted out
with `groups = []`), `load-error` (the failure surface shown in `empty`'s place when the optional
peer failed to load), `hint` (the hint message), `error` (the
error message). The grid scrolls in the block axis and explicitly clips inline overflow, so an
allocation narrower than one option does not introduce a second scrollbar. While windowing is
active the rows are wrapped in `virtual-spacer`
(full-height scroll spacer), `virtual-row` (one absolutely-positioned row), `virtual-label` (an
`aria-hidden` spacer standing in for a row's missing `group-label`), and `virtual-items` (the row's
emoji flex line).

**The required marker.** `required` with a non-empty `label` paints the library's shared marker on
`[part="form-control-label"]` — the one `::after` rule described under "The required-field marker"
above, not a copy of it, so `--lr-form-control-required-content`,
`--lr-form-control-required-color` and `--lr-form-control-required-offset` retune or suppress it
here exactly as they do on `lr-input`. With no label text the part is hidden and no glyph is
painted.

**Themeable custom properties:** `--lr-emoji-picker-item-size` (default `--lr-icon-button-size`,
each emoji button's box; scaled by the `size` property), `--lr-emoji-picker-glyph-size` (default
`--lr-font-size-lg`, the font size of the emoji glyph; scaled by the `size` property to keep the glyph
proportional to the item box), `--lr-emoji-picker-gap` (default `--lr-space-2xs`, the gap between
emoji within a windowed row), and `--lr-emoji-picker-row-height` (default
`calc(var(--lr-emoji-picker-item-size) + var(--lr-space-l))`, one windowed row's height).
`--lr-emoji-picker-item-size`, `--lr-emoji-picker-gap`, and `--lr-emoji-picker-row-height` are also
read back in JS to derive columns-per-row and row offsets for the windowed layout,
resolved to real pixels by measuring hidden probe boxes the component's own stylesheet sizes from
those same tokens — so any CSS length unit works, `rem`/`em` and `calc()` included, and the windowed
geometry matches what is painted without expressing the tokens in `px`. The measurement is cached
and re-derived only when the resolved pixels can actually change (a token override applied after the
first render, a theme swap, a root or host font-size change feeding a `rem`/`em` value), never per
frame. `--lr-emoji-picker-search-min-height` (default `auto`),
`--lr-emoji-picker-search-font-size` (default `inherit`),
`--lr-emoji-picker-search-padding-inline` (default `var(--lr-space-s)`) and
`--lr-emoji-picker-search-padding-block` (default `var(--lr-space-xs)`) size the built-in filter
field. `size` does NOT drive them — on this component `size` scales the emoji glyph and item box,
never the form-control ladder — so point the height at `--lr-form-control-height-s` (or any tier of
that ladder) when the filter field has to match a themed search field beside it.

Emoji interaction states are separate: `--lr-emoji-picker-hover-bg`,
`--lr-emoji-picker-keyboard-active-bg`, `--lr-emoji-picker-selected-bg`/
`--lr-emoji-picker-selected-color`, and `--lr-emoji-picker-pressed-bg`, with matching
`--lr-emoji-picker-keyboard-active-outline-color`,
`--lr-emoji-picker-selected-outline-color`, and
`--lr-emoji-picker-pressed-outline-color` hooks for active, selected, and pressed. The legacy
`--lr-emoji-picker-active-bg` remains the fallback for hover and keyboard-active. These are inline
`var()` fallbacks rather than host declarations, so values set on any ancestor remain effective.
The committed form `value` alone drives `aria-selected`; roving focus and pointer navigation use
`data-active`, so moving through the grid never falsely changes selection. Forced-colors mode also
distinguishes hover (dashed), active (dotted), selected (solid), and pressed (double) outlines.

Two constraints remain. `--lr-emoji-picker-item-size` is held at the shared
`--lr-icon-button-size` minimum: smaller `size` tier values can still shrink the glyph, but never
the interactive option, and the windowed geometry follows the clamped, painted size. And windowed
rows are absolutely positioned at the row-height
pitch, so `--lr-emoji-picker-row-height` must stay at or above the item size plus the group-label
band (`--lr-space-l`) — the default's own formula — or consecutive rows overlap. Columns per
windowed row are additionally capped at 20 regardless of available width.
The `grid` scroll container also honors the opt-in theme-level
`--lr-theme-scrollbar-width`/`--lr-theme-scrollbar-gutter` hooks (defaults `auto`/`stable`, matching
its previous unconditional `scrollbar-gutter: stable`) — set either on `:root` or any ancestor for
one declaration to retheme every internal scroll container in the library.

**Optional peer dependency:** install `emoji-picker-element-data` with
`pnpm add emoji-picker-element-data` for the built-in auto-loaded default emoji set — omit it and
supply `groups` directly instead. The loader never throws; a missing or failed peer logs one
`console.warn` and leaves `groups` empty, and the picker then **fails closed and visibly**: the
grid renders a distinct localized `[part="load-error"]` surface instead of the ordinary
`[part="empty"]` message, so a skipped install is distinguishable at a glance from a genuine
zero-match search or a deliberate `groups = []` opt-out, and announces the same message once
through the document's shared assertive live region (not a shadow-root `role="alert"`, which
announces unreliably). Assigning `groups` afterwards clears it. The adapter buckets the peer's flat
entry list by numeric group id and returns only the public `{ key, label, emojis }` shape. The picker
privately maps auto-loaded group ids 0–9 to the existing `emojiPickerGroup*` locale strings; override
those through `registerLyraLocale()` or `.strings`. An unknown future group id uses `Group {id}`.

**Additional API surface:**

- `--lr-emoji-picker-control-gap` — Gap between field sections. Default: `var(--lr-space-xs)`.
- `--lr-emoji-picker-search-clear-gap` — Gap between the search field and the clear button inside
  `search-wrapper`. Default: `var(--lr-space-xs)`.
- `--lr-emoji-picker-radius` — Outer picker corner radius. Default: `var(--lr-radius)`.
- `--lr-emoji-picker-item-radius` — Search and emoji corner radius. Default: `var(--lr-radius-xs)`.
- `--lr-emoji-picker-search-border-color` — Resting search border color, independent of the hover
  color below. Default: `var(--lr-color-border)`.
- `--lr-emoji-picker-search-fill` — Resting search background. Default: `var(--lr-color-surface)`.
- `--lr-emoji-picker-search-hover-border-color` — Search hover border. Default: `var(--lr-color-brand)`.

## `lr-rubric-form`

A configurable annotation rubric (LangSmith annotation-queue style): score, category, and
freeform-comment keys with a submit-and-next flow for working through an eval queue. Each
`RubricKey.type` routes to an existing sibling control: `score` renders `<lr-segmented>` or
`<lr-slider>`; `category` renders `<lr-select>` or `<lr-checkbox-group>` (`multiple`); `comment`
renders `<lr-textarea>`. The `base` part is an accessible `role="group"`: aggregate label, hint,
and error chrome is linked to that same-shadow role. A host `aria-label` wins by attribute presence
(including an explicitly empty value), while each key retains its field-level name.
Both score branches format visible numeric labels with the effective locale (including non-Latin
digits); segmented item values and submitted rubric values remain stable raw numbers/strings.

Host `aria-describedby` references resolve in the host's root and precede local hint/error guidance
on that aggregate group. Target replacement, removal, reinsertion, reconnection and document
adoption keep the relationship current. Aggregate guidance is not copied to every child field; each
retains its own description/error ownership. Removing `label` or `hint` safely removes the copy
while retaining native attribute-removal property readback, including `null`; explicit empty and
later replacement strings remain supported.

Replacing `value` after a multiple-category user edit reconciles the actual checkbox checked states,
group value and submitted JSON, including when replacement happens in the same task. These parent
writes use live child state, leave child reset-default/dirty semantics intact, and emit no user-edit
events.

**Properties:** `keys: readonly RubricKey[] = []` (attribute: false), where the exported immutable
discriminated union is `ScoreRubricKey | CategoryRubricKey | CommentRubricKey`. Keys use nonblank
first-wins identity and retained valid spelling is not rewritten. Shared fields are
`key`, `label?`, `description?`, and `required?`; only scores expose `min?`/`max?`/`step?`, only
categories expose readonly `RubricKeyOption[]` plus `multiple?`, and only comments expose
`placeholder?`. Runtime schema normalization retains the first occurrence of each nonempty key and
rejects malformed rows. `value: RubricValue = {}` is a defensive readonly snapshot and
`defaultValue: RubricValue = {}` is its explicit form-reset baseline (both attribute: false).
`itemId: string = ''`
(attribute `item-id`, reflected), `hasNext: boolean = false` (attribute `has-next`), `skippable:
boolean = false`, aggregate `label: string = ''`, `hint: string = ''`, `errorText: string = ''` (attribute
`error-text`), SSR presence hints `withLabel: boolean = false` / `withHint: boolean = false`
(attributes `with-label` / `with-hint`), and the shared form properties `name` and `disabled`.
`errors: Readonly<Record<string, string>>` is a frozen effective validation-message snapshot:
intrinsic messages use their rubric key and a consumer-owned whole-form rejection uses `base`.
`customError: string | null` reflects through `custom-error` for that rejection.

Every value path — direct writes, child edits, schema changes, state restoration, reset, events,
rendering, validity, and FormData — uses one canonical object. Finite scores clamp and snap to the
current range/step; a wide slider score without an explicit default records its rendered, snapped
midpoint in both `defaultValue` and the pristine live value, while segmented scores remain
unselected. Nonfinite scores are absent; categories retain only current option values (and their
available occurrence counts); comments must be strings; undeclared keys are dropped. This prevents
a rendered value, public readout, validity result, and submitted JSON from disagreeing.
`form.reset()` restores a fresh clone of `defaultValue`, clears touched/error-reveal state, and
preserves any consumer `setCustomValidity()` message. Changing `defaultValue` updates a pristine
live value but never overwrites a dirty edit.

**Slots:** `label` — aggregate rubric label before the fields; `hint` — aggregate supporting text;
`error` — aggregate validation content; `actions` —
extra host controls rendered in the footer beside Submit/Skip.

**Events:** `lr-input` (`detail: { value }`), `lr-validity-change` (frozen
`detail: { valid, errors }`, deduplicated on effective native validity including consumer custom
errors and own/fieldset validation barring), `lr-submit` (`detail: { value, itemId }`), and `lr-skip`
(`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.

**Methods:** `getForm()` returns the owning form. `setCustomValidity(message)` sets or clears a
form-level error no per-key rule can
express ("this item was already annotated by someone else"): a non-empty message raises
`customError` and blocks submission, `''` restores the rubric's own computed validity — unanswered
required keys, and any key with an unsupported `type`, still hold it invalid. It is whole-control
state exposed as `errors.base`, rather than being attributed to one rubric key. It survives every
`value`/`keys` write and a form reset. When
`errorText` is empty, the current custom-validity message is rendered in the aggregate error region;
clearing it hides that region unless the `error` slot supplies other content.
`click()` forwards to the active field (the same one a submit-and-next transition auto-focuses),
so the host behaves like a single control under both a `<label>`-driven and a programmatic click.

**CSS parts:** `base` (the outer `role="group"` wrapper), `form-control` (aggregate chrome wrapper),
`aggregate-label` / `form-control-label`, `fields` / `form-control-input`, `aggregate-hint` /
`form-control-help-text`, `aggregate-error` / `form-control-error`, `field` (one key's wrapper),
`label`, `description`, `scale` (the
rendered score/category/comment control's wrapper), `error` (a field-level validation message),
`footer`, `submit`, `skip` (only rendered when `skippable`), `empty` (shown when `keys` has no
entries), and `unsupported` (the fallback note for a key whose `type` is outside the three supported
ones).

Field-level `error` content is ordinary visible validation text, not a shadow live region. Score
controls compose the current message into the semantic control's accessible name; category/comment
controls use their own same-shadow label/error plumbing. `reportValidity()` therefore reveals and
focuses the error once without an additional `role="alert"` announcement.

**The required marker.** Required score and unsupported fields own their visible label, so the
shared marker is rendered there. Required category and comment fields retain the marker from their
own `lr-select`/`lr-checkbox-group` or `lr-textarea` label instead; the rubric never adds a second
glyph. `--lr-form-control-required-content` (a quoted CSS `content` string; `''` suppresses it),
`--lr-form-control-required-color` (default `var(--lr-color-danger)`), and
`--lr-form-control-required-offset` (default `0`) retune the same marker across every required
field.

**Themeable custom properties:** Submit rest uses `--lr-rubric-form-submit-bg`,
`--lr-rubric-form-submit-border-color`, and `--lr-rubric-form-submit-color`; its hover and pressed
paint use `--lr-rubric-form-submit-hover-bg`, `--lr-rubric-form-submit-hover-border-color`,
`--lr-rubric-form-submit-active-bg`, and `--lr-rubric-form-submit-active-border-color`. Skip rest uses
`--lr-rubric-form-skip-bg`, `--lr-rubric-form-skip-border-color`, and
`--lr-rubric-form-skip-color`, with `--lr-rubric-form-skip-hover-bg` and
`--lr-rubric-form-skip-active-bg` for its pointer states. All preserve the existing shared-token
and color-mix treatments as fallbacks. Disabled actions still dim through `--lr-opacity-disabled`,
the same library-wide token every other disabled control reads.

## `lr-locale-picker`

A closed-list locale switcher over the library's own locale registry. First-party invention (no
Web Awesome equivalent). With `locales` unset (the default), the offered rows are exactly
`getRegisteredLyraLocales()` — every locale with strings registered via `registerLyraLocale()`,
plus `en` — kept live via `subscribeLyraLocaleRegistry()`. Built directly on `lr-select`'s
trigger-button/`aria-activedescendant` listbox technique, not composed from it — a plain closed
list, no filter/free-text mode.

Host `aria-describedby` references resolve onto the role=combobox trigger before its local error and
hint guidance. The relationship tracks missing IDs, target replacement, removal/reinsertion,
reconnect, and document adoption. Removing `label`, `hint`, or `error-text` safely omits that
content while leaving native `null` property readback unchanged; explicit empty strings remain empty
and later supplied text renders normally.

Public `--lr-locale-picker-*` theme inputs stay undeclared on the host, so an ancestor theme
wrapper can override size-tier fallbacks; a value set directly on the element still wins.

**Properties:**

- `locales?: LyraLocaleCatalog` (attribute: false) — `LyraLocaleCatalog = readonly string[] |
readonly LyraLocaleEntry[]`, `LyraLocaleEntry { tag: string; label?: string; country?: string }`.
  `undefined` (the default) auto-discovers the registry; every supplied array (either form),
  including an authoritative `[]`, overrides it entirely — a curated subset, custom order,
  custom labels, or a locale offered before its strings are registered. Explicit catalogs are
  capped, cloned and frozen at assignment; mutate a new array/entry and reassign it to update the
  list. `country` (ISO 3166-1 alpha-2 or alpha-3) overrides a row's derived flag — e.g.
  showing Lebanon's flag for an `'ar'` row instead of the library's default Saudi Arabia mapping;
  only available on the `{tag,label,country}` object form, not the bare `string[]` form. Replacing
  the catalog while the listbox is open keeps keyboard navigation valid: an active row beyond the
  new end is rehomed to the last remaining row. Arrow/Home/End/typeahead changes scroll the active
  owned option into nearest view after render; replacement and disconnect cancel stale scrolls.
- `showFlags: boolean = true` — each row's leading `<lr-flag language={tag} variant="compact">`
  (or `<lr-flag country={country} variant="compact">` when the entry sets `country`); `false`
  omits the flag element entirely (not just visually).
- `triggerDisplay: LyraLocaleTriggerDisplay = 'flag-label'` (attribute `trigger-display`) —
  `'flag' | 'label' | 'flag-label'`. The default keeps the flag, label and chevron. `label`
  omits only the trigger flag; the menu keeps its flags and endonyms. `flag` centers the flag in
  a square and hides the visible label and chevron. The `trigger-label` remains available to
  assistive technology and describes the trigger's current language; its accessible name still
  follows `label`/the host `aria-label`. The square uses the shared/scoped trigger height with a
  24px floor. `showFlags=false` retains visible text in every mode. Selection, keyboard navigation,
  form values and the uncommitted effective-locale preview keep their usual behavior.
- `optionDisplay: LyraLocaleOptionDisplay = 'label-tag'` (attribute `option-display`) —
  `'label' | 'label-tag'`. The default renders each option row as the locale's label above its raw
  BCP-47 tag. `'label'` renders the label alone and **omits the `option-tag` element from the DOM**
  rather than hiding it with CSS — a visually hidden tag would still join the row's accessible name
  and would still be matched by `::part(option-tag)`, so under `'label'` that part matches nothing
  at all. The trigger, the row flags, `showFlags`, selection, keyboard navigation and form values
  are identical in both modes; only the option rows change.
- `value: string = ''` — the **committed** selection (form value, drives `lr-change`). While `''`
  and untouched, the trigger _displays_ `effectiveLocale` as a preview label, but
  `checkValidity()`/`required` are governed by the real `value`, which stays `''` until a real
  commit — mirrors a native `<select>` showing its first option's text without that being a
  committed selection.
- `defaultValue: string = ''` (attribute `value`, reflected) — the current reset default. Live
  `value` writes are non-reflecting and dirty; later default/attribute changes cannot overwrite
  them until `form.reset()` restores the current default.
- `customError: string | null` (attribute `custom-error`) — reflected consumer validation message.
- `required: boolean = false`, `disabled: boolean = false`, `name: string = ''` — standard
  form-associated properties.
- `label: string = ''`, `hint: string = ''`, `errorText: string = ''` (attribute `error-text`) —
  same opt-in form-control chrome as `lr-select` (props + matching named slots + parts); unset
  renders none of it.
- `open: boolean = false` (reflected).
- `size: LyraSize = 'm'` (reflected) — the same full scale as `lr-select`, accepting
  `2xs`/`xs`/`s`/`m`/`l`/`xl` and `small`/`medium`/`large`.

**Events:** `lr-change` (`detail: { value, previousValue, direction }`, **cancelable**) — fired on
every explicit pick; if not `defaultPrevented`, the component applies the pick itself via
`setLyraLocale(value)`. A listener calling `event.preventDefault()` leaves `value` updated but the
active locale untouched, so a host can persist the choice first and apply it later. `focus`/`blur`
are relayed once from the trigger as native `FocusEvent`s preserving `relatedTarget`.
`lr-invalid` is the single
bubbling/composed, cancelable alias of a failed native validity check.

`direction` (`'ltr' | 'rtl'`, typed as `LyraLocaleDirection`) is the picked locale's writing
direction, resolved through `getLyraLocaleDirection(value)` — a catalog's declared
`registerLyraLocale(tag, strings, { dir })` first, then `Intl.Locale`'s text-info surface where the
engine has it, then `'ltr'`. It is present on every `lr-change`, cancelled or not, and it is carried
precisely so applying the direction is a one-liner instead of an application-maintained table of RTL
tags:

```js
picker.addEventListener("lr-change", (e) => {
  document.documentElement.lang = e.detail.value;
  document.documentElement.dir = e.detail.direction;
});
```

The component still never writes `lang`/`dir` itself — a picker does not own the page — but it no
longer leaves the host to work the direction out. `getLyraLocaleDirection()` is exported from
`@aceshooting/lyra-ui/localization.js` for the same lookup outside an event handler (a persisted
choice applied on boot).

**Methods:** `focus(options?)`, `blur()`, and `click()` — all forward to the internal trigger
button and synchronously no-op under direct or fieldset disablement, same convention as
`lr-select`'s identical trio. `setCustomValidity(message)` sets or clears
a consumer-supplied error ("that locale is not enabled for your account"): a non-empty message
raises `customError` and blocks submission, `''` restores the picker's own computed validity so a
required picker with nothing committed goes back to `valueMissing`. It survives every
`value`/`required` change and a form reset. `getForm()` returns the browser-resolved owning form.

The open list is a nonmodal overlay: only its topmost owner handles Escape and outside pointer
dismissal; Escape restores the trigger, while Tab keeps ordinary document navigation. Disconnect or
cross-document adoption closes it. A required, uncommitted value recomputes its intrinsic localized
message when `.strings` or the effective locale changes; an author custom-validity message retains
priority until cleared.

**Slots:** `label`, `hint`, `error`.

**CSS parts:** `form-control`, `form-control-label`, `trigger`,
`trigger-flag` (the trigger's leading `<lr-flag>` for the current value, present only while
`showFlags` is on and `triggerDisplay` is not `label`), `trigger-label` (the current language,
visually hidden in flag-only mode), `listbox`, `option`, `option-flag` (present only while `showFlags` is on),
`option-label`, `option-tag` (the row's secondary line — the raw BCP-47 tag; rendered only while
`optionDisplay` is `label-tag`, and absent from the DOM entirely under `optionDisplay="label"`),
`expand-icon`,
`hint`, `error`.

**The required marker.** `required` with a non-empty `label` paints the library's shared marker on
`[part="form-control-label"]` — the one `::after` rule described under "The required-field marker"
above, not a copy of it, so `--lr-form-control-required-content`,
`--lr-form-control-required-color` and `--lr-form-control-required-offset` retune or suppress it
here exactly as they do on `lr-input`. The part is rendered only when there is label text, so an
unlabelled picker paints no stray glyph.

**Themeable custom properties:** `--lr-locale-picker-trigger-padding`,
`--lr-locale-picker-trigger-min-height`, `--lr-locale-picker-trigger-height` (unset by default, a
floor-only escape hatch — set a length to both floor and cap the trigger),
`--lr-locale-picker-font-size`, `--lr-locale-picker-expand-size` (all scaled by `size`), and
`--lr-locale-picker-trigger-hover-bg`, `--lr-locale-picker-open-border-color`,
`--lr-locale-picker-option-active-bg`, `--lr-locale-picker-option-selected-border-color`,
`--lr-locale-picker-option-selected-color`, and
`--lr-locale-picker-option-selected-font-weight`. The state hooks fall back to the previous brand,
quiet-brand, and semibold semantic tokens.

The listbox is a floating surface and paints from the **shared overlay-surface family** (16.0.0):
`--lr-overlay-surface` (default `var(--lr-color-surface-overlay)`), `--lr-overlay-border` (default
`var(--lr-color-border)`) and `--lr-overlay-shadow-anchored` (default `var(--lr-shadow-m)`), none of
them declared on `:host`, so one declaration on `:root` — or on any ancestor, to scope it — retints
this listbox together with every other floating surface. `--lr-overlay-radius` reaches the listbox
only as the middle arm of this component's own `--lr-locale-picker-radius`, which still wins when
set: a component-scoped override outranks the shared family, never the other way round.

`--lr-positioning-strategy` (16.0.0) — the listbox reads this same cascading `absolute`/`fixed`
override documented on `<lr-popover>` when it is (re)positioned, falling back to its own `fixed`
default when nothing is set. There is no per-instance `positioning-strategy` property on
`<lr-locale-picker>`; set the custom property on `:root`, a theme, or one clipping ancestor to
change every unset locale picker beneath it.

**Optional peer deps:** none directly — each row's `<lr-flag>` degrades to an empty render (no
peer warning duplication; `lr-flag` itself already logs one) when the optional
`@aceshooting/lyra-flags` package isn't installed and `showFlags` is left on.

A compact header can set `trigger-display="flag"` and
`--lr-locale-picker-trigger-height: 2.25rem` for a 36px square at the usual 16px root size.
Import `@aceshooting/lyra-ui/components/media/flag/flag-peer.js` to register the optional flag
resolver. Menu labels stay visible; a per-entry `country` override also reaches the compact trigger.

```html
<lr-locale-picker label="Language"></lr-locale-picker>
<script type="module">
  import { registerLyraLocale } from "@aceshooting/lyra-ui/localization.js";
  registerLyraLocale("fr", { close: "Fermer" });
  document
    .querySelector("lr-locale-picker")
    .addEventListener("lr-change", (e) => console.log(e.detail.value));
</script>
```

**Known gotchas:**

- selecting a row applies `setLyraLocale()` itself unless the listener calls
  `event.preventDefault()` on `lr-change` — it does not touch
  `document.documentElement.lang`/`dir`. Applying those is still the host's job, but the direction
  is no longer the host's to _derive_: read `event.detail.direction` (or call
  `getLyraLocaleDirection(tag)`), rather than keeping a hand-maintained list of RTL tags.
- no filter/free-text mode — for a catalog with hundreds+ of rows, roll your own with `lr-select`
  or `lr-combobox` instead.
- arrow-key navigation is vertical-only (Home/End/ArrowUp/ArrowDown); there is no
  ArrowLeft/ArrowRight remap under RTL, since there is no horizontal axis to remap.

**Additional API surface:**

- `--lr-locale-picker-gap` — Trigger and option child gap. Default: `var(--lr-space-xs)`.
- `--lr-locale-picker-radius` — Trigger/listbox/option corner radius. Default: `var(--lr-radius)`.
- `--lr-locale-picker-trigger-hover-bg` — Trigger hover background. Default: `var(--lr-color-brand-quiet)`.
- `--lr-locale-picker-open-border-color` — Open trigger border color. Default: `var(--lr-color-brand)`.
- `--lr-locale-picker-trigger-fill` — Resting trigger background. Default: `var(--lr-color-surface)`.
- `--lr-locale-picker-trigger-border-color` — Resting trigger border color. Default:
  `var(--lr-color-border)`.
- `--lr-locale-picker-trigger-hover-border-color` — Trigger border color under the pointer. Default:
  the resting `--lr-locale-picker-trigger-border-color`, so an unset hook leaves the hovered border
  exactly where it has always been.
- `--lr-form-control-focus-shadow` — The shared field halo, painted as a `box-shadow` while the
  trigger is focused or open. Default: `none`. Additive — the focus outline and the open border are
  never replaced by it.
- `--lr-locale-picker-option-selected-border-color` — Selected option border. Default: `var(--lr-color-brand)`.
- `--lr-locale-picker-option-selected-color` — Selected option text. Default: `var(--lr-color-brand)`.

## Consumer integration notes

For `lr-input`, `lr-time-input`, and `lr-checkbox-group`, host `aria-describedby` is projected to
the semantic native control before built-in hint, error, and required-description ids. Host
`aria-labelledby` deliberately does not project: the native label or fieldset legend remains the
single name owner. This lets an application add external descriptions without replacing the
component's visible form label.

## Exported TypeScript contracts

These named interfaces and helper signatures are available to typed integrations. They are grouped by capability so the component sections above can stay focused.

- **`components-forms-checkbox-group-checkbox-group-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/forms/checkbox-group/checkbox-group.class.js`.
  `LyraCheckboxGroupToggleRequestDetail {
    readonly value: readonly string[];
    readonly previousValue: readonly string[];
    readonly option: LyraCheckbox;
  }`

- **`components-forms-color-picker-color-core-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/forms/color-picker/color-picker.class.js`.
  `LyraColorHsva {
    h: number;
    s: number;
    v: number;
    a: number;
  }`

- **`components-forms-color-picker-color-picker-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/forms/color-picker/color-picker.class.js`.
  `LyraColorPickerSwatch {
    color: string;
    label?: string;
    disabled?: boolean;
  }`

- **`components-forms-combobox-combobox-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/forms/combobox/combobox.class.js`.
  `ComboboxFilterDetail {
    value: string;
  }`
  Import: `@aceshooting/lyra-ui/components/forms/combobox/combobox.class.js`.
  `ComboboxSourceResult {
    readonly rows: readonly ComboboxSourceRow[];
    readonly total?: number;
  }`
  Import: `@aceshooting/lyra-ui/components/forms/combobox/combobox.class.js`.
  `ComboboxSourceRow {
    readonly value: string;
    readonly label: string;
    readonly sub?: string;
    readonly icon?: unknown;
    readonly start?: unknown;
    readonly end?: unknown;
    readonly badge?: string | number;
    readonly accessibleLabel?: string;
    readonly data?: unknown;
    readonly dotColor?: string;
    readonly group?: string;
    readonly disabled?: boolean;
  }`
  Import: `@aceshooting/lyra-ui/components/forms/combobox/combobox.class.js`.
  `LyraComboboxObjectValidator {
    observedAttributes?: string[];
    checkValidity: (input: never) => LyraComboboxObjectValidatorResult;
    message?: string | ((input: never) => string);
  }`
  Import: `@aceshooting/lyra-ui/components/forms/combobox/combobox.class.js`.
  `LyraComboboxObjectValidatorResult {
    message: string;
    isValid: boolean;
    invalidKeys: Exclude<keyof ValidityState, 'valid'>[];
  }`

- **`components-forms-date-picker-date-input-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/forms/date-picker/date-input.class.js`.
  `LyraDateInputObjectValidator {
    observedAttributes?: string[];
    checkValidity: (input: never) => LyraDateInputObjectValidatorResult;
    message?: string | ((input: never) => string);
  }`
  Import: `@aceshooting/lyra-ui/components/forms/date-picker/date-input.class.js`.
  `LyraDateInputObjectValidatorResult {
    message: string;
    isValid: boolean;
    invalidKeys: Exclude<keyof ValidityState, 'valid'>[];
  }`

- **`components-forms-date-picker-date-picker-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/forms/date-picker/date-picker.class.js`.
  `DateRange {
    from: Date | null;
    to: Date | null;
  }`
  Import: `@aceshooting/lyra-ui/components/forms/date-picker/date-picker.class.js`.
  `LyraDateRangePreset {
    readonly label: string;
    readonly start?: string;
    readonly end?: string;
    readonly id?: string;
  }`

- **`components-forms-emoji-picker-emoji-types-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/forms/emoji-picker/emoji-picker.class.js`.
  `EmojiPickerGroup {
    readonly key: string;
    readonly label: string;
    readonly emojis: readonly EmojiPickerItem[];
  }`
  Import: `@aceshooting/lyra-ui/components/forms/emoji-picker/emoji-picker.class.js`.
  `EmojiPickerItem {
    readonly emoji: string;
    readonly name: string;
    readonly shortcodes?: readonly string[];
  }`

- **`components-forms-form-validator-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/forms`.
  `LyraFormValidator<T extends {
    readonly validity: ValidityState;
    readonly validationMessage: string;
  }> {
    observedAttributes?: string[];
    checkValidity(element: T): LyraFormValidatorResult;
    message?: string | ((element: T) => string);
  }`
  Import: `@aceshooting/lyra-ui/components/forms`.
  `LyraFormValidatorResult {
    isValid: boolean;
    message: string;
    invalidKeys: Exclude<keyof ValidityState, 'valid'>[];
  }`

- **`components-forms-locale-picker-locale-picker-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/forms/locale-picker/locale-picker.class.js`.
  `LyraLocaleChangeDetail {
    value: string;
    previousValue: string;
    direction: LyraLocaleDirection;
  }`
  Import: `@aceshooting/lyra-ui/components/forms/locale-picker/locale-picker.class.js`.
  `LyraLocaleEntry {
    readonly tag: string;
    readonly label?: string;
    readonly country?: string;
  }`

- **`components-forms-phone-input-phone-input-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/forms/phone-input/phone-input.class.js`.
  `LibphonenumberModuleLike<CountryCode extends string = string> {
    getCountries(): CountryCode[];
    getCountryCallingCode(country: CountryCode): string;
    parsePhoneNumberFromString(input: string, defaultCountry?: CountryCode): LibphonenumberPhoneLike | undefined;
    validatePhoneNumberLength?(input: string, defaultCountry?: CountryCode): string | undefined;
  }`
  Import: `@aceshooting/lyra-ui/components/forms/phone-input/phone-input.class.js`.
  `loadLibphonenumberAdapter<CountryCode extends string = string>(loader: () => Promise<unknown>): Promise<LyraPhoneNumberAdapter>`
  Import: `@aceshooting/lyra-ui/components/forms/phone-input/phone-input.class.js`.
  `LyraPhoneCountry {
    readonly code: string;
    readonly callingCode: string;
    readonly label?: string;
  }`
  Import: `@aceshooting/lyra-ui/components/forms/phone-input/phone-input.class.js`.
  `LyraPhoneInputEventDetail {
    value: string;
    inputValue: string;
    country: string;
    valid: boolean;
    status: LyraPhoneNumberStatus;
  }`
  Import: `@aceshooting/lyra-ui/components/forms/phone-input/phone-input.class.js`.
  `LyraPhoneNumberAdapter {
    readonly countries?: readonly LyraPhoneCountry[];
    parse(input: string, country?: string): LyraPhoneNumberParseResult;
  }`

- **`components-forms-rubric-form-rubric-form-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/forms/rubric-form/rubric-form.class.js`.
  `CategoryRubricKey extends RubricKeyBase {
    readonly type: 'category';
    readonly options?: readonly RubricKeyOption[];
    readonly multiple?: boolean;
    // Inherited from RubricKeyBase.
    readonly key: string;
    readonly label?: string;
    readonly description?: string;
    readonly required?: boolean;
  }`
  Import: `@aceshooting/lyra-ui/components/forms/rubric-form/rubric-form.class.js`.
  `CommentRubricKey extends RubricKeyBase {
    readonly type: 'comment';
    readonly placeholder?: string;
    // Inherited from RubricKeyBase.
    readonly key: string;
    readonly label?: string;
    readonly description?: string;
    readonly required?: boolean;
  }`
  Import: `@aceshooting/lyra-ui/components/forms/rubric-form/rubric-form.class.js`.
  `RubricKeyOption {
    readonly value: string;
    readonly label?: string;
    readonly description?: string;
  }`
  Import: `@aceshooting/lyra-ui/components/forms/rubric-form/rubric-form.class.js`.
  `ScoreRubricKey extends RubricKeyBase {
    readonly type: 'score';
    readonly min?: number;
    readonly max?: number;
    readonly step?: number;
    // Inherited from RubricKeyBase.
    readonly key: string;
    readonly label?: string;
    readonly description?: string;
    readonly required?: boolean;
  }`

- **`components-forms-slider-slider-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/forms/slider/slider.class.js`.
  `LyraSliderChangeDetail {
    value: number;
    minValue: number;
    maxValue: number;
    handle: SliderHandle;
  }`

- **`components-forms-swatch-picker-swatch-picker-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/forms/swatch-picker/swatch-picker.class.js`.
  `SwatchPickerItem {
    readonly value: string;
    readonly color: string;
    readonly label: string;
    readonly icon?: unknown;
    readonly gemstone?: GemstoneKey;
  }`

- **`components-forms-textarea-textarea-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/forms/textarea/textarea.class.js`.
  `TextareaScrollPosition {
    top: number;
    left: number;
  }`

- **`components-forms-time-range-time-range-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/forms/time-range/time-range.class.js`.
  `TimeRangePreset {
    readonly label: string;
    readonly start: number;
    readonly end: number;
    readonly id?: string;
  }`

# Data display, dashboards & flow canvas (`components/data/`)

## Breaking changes in 10.0.0

`<lr-calendar>`'s `firstDayOfWeek`/`first-day-of-week` drops the bare `0`–`6` integer form and stops
defaulting to a hardcoded Monday. The type is now exactly `LyraCalendarFirstDayOfWeek`
(`'auto'|'sun'|'mon'|'tue'|'wed'|'thu'|'fri'|'sat'`, default `'auto'`), so there is one way to
express a week start instead of two that had to be sanitized and wrapped against each other, and
`'auto'` resolves through the same `resolveFirstDayOfWeek()` contract `<lr-date-picker>`/
`<lr-date-input>` already use. An unset `<lr-calendar>` and an unset `<lr-date-picker>` on the same
page therefore agree at last — Sunday-first under `en-US`, Monday-first under `fr-FR` — where the
calendar previously rendered Monday-first everywhere while already formatting its weekday *labels*
from the locale. Replace `first-day-of-week="1"` with `first-day-of-week="mon"`: a leftover numeric
value is not mapped or clamped, it is simply an unrecognized token and falls through to Sunday. If
the locale-independent Monday start was deliberate, keep it by writing `"mon"` explicitly instead of
relying on the default. There is no `wa-calendar`, so no upstream mirror is affected.

Also corrected in 10.0.0 — not breaking, but visible. A specificity sweep found rules that were
meant to win yet were losing to another rule in the same shadow stylesheet, so their declarations
never applied at all. In this family: `<lr-calendar>`'s today cell has a focus ring again (its
`[data-today]` outline was swallowing it, leaving today's cell pixel-identical focused and at rest)
and its adjacent-month cells take selection and pointer feedback again; `<lr-table>`'s header cell
that is both sticky and sortable, `<lr-pagination>`'s page input, `<lr-sequence-strip>`'s selected
cell and `<lr-flow-canvas>`'s selected edge regain hover/press/focus feedback; and
`<lr-flow-controls>` honors a `hidden` slotted action button instead of painting it.

## `lr-sparkline`

Zero-dependency inline SVG trend chart (mirrors `<wa-sparkline>`). Its default allocation is one
`em` tall at a `4 / 1` aspect ratio, so it can sit directly in text; authored block size changes
both dimensions through the aspect ratio.

An empty or removed `data` attribute uses the `values` collection. With no usable fallback samples,
no trend path is rendered. Attribute removal preserves `null` property readback, and supplying later
space-separated samples restores the attribute-driven path.

**Properties:**

- `appearance: 'gradient'|'line'|'solid' = 'solid'` (reflected) — `solid` fills the area below the
  stroke, `gradient` fades that fill toward the baseline, and `line` renders only the stroke
- `curve: 'linear'|'natural'|'step' = 'linear'` (reflected) — straight segments, smooth cubic
  interpolation, or horizontal/vertical steps
- `data: string = ''` — space-separated finite numbers such as `"5 4 4 3 4 2 3"`; at least two
  finite values are required. Invalid/non-finite tokens are dropped, and a remaining series shorter
  than two values renders the named empty wrapper without an invalid SVG path
- `label: string = ''` — accessible name applied verbatim to the SVG
- `trend?: 'positive'|'negative'|'neutral'` (reflected) — selects semantic Lyra-token defaults for
  the line and fill. The public color custom properties below always override it

**Additive Lyra extensions:**

- `values: readonly number[] = []` (attribute: false) — property-only programmatic data source used
  while `data` is empty; foreign/non-array assignments render the empty state rather than throwing
- `mark: LyraSparklineMark = 'line'`, where `LyraSparklineMark = 'line'|'bar'` (reflected) —
  chooses line/path versus bounded rectangle geometry. Fill treatment remains solely on the
  mirrored `appearance` axis
- `min?: number` (defaults to data minimum)
- `max?: number` (defaults to data maximum)
- `accessibleLabel: string | null = null` (attribute `aria-label`) — programmatic compatibility
  name for the additive `values` path. Naming precedence is an authored host `aria-label`
  (including an intentional empty value), then nonempty `label`, then a nonempty programmatic
  `accessibleLabel`, then the localized generated summary

**Events:** none.

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

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

**Optional peer deps:** none.

```html
<lr-sparkline
  appearance="gradient"
  curve="natural"
  trend="positive"
  data="3 5 4 8 6 9 7"
  label="Revenue over the last seven days"
></lr-sparkline>
```

**Known gotchas:**

- The semantic `role="img"` and accessible name live on the SVG that owns the graphic. `label` is
  applied exactly. The additive `values` path retains its localized, effective-locale summary when
  neither naming property is present; a `data` chart without a label is left presentational rather
  than inventing spoken application data.
- flat data (every value equal, so the auto-computed range spans zero) now renders a centered
  midline/mid-height bars instead of collapsing every point to the bottom edge, and a single-value
  additive `values` series renders a visible flat line. Mirrored `data` deliberately requires two
  values. **Every** rendering mode
  (`mark="line"` with any appearance, or `mark="bar"`) decimates a `values` array past 500 points
  down to at most 500 plotted
  samples — evenly sampled by index, always keeping the first and last value exactly, not
  aggregated/averaged. `mark="bar"` caps at 500 rendered `<rect>`s directly; line marks cap the
  point count baked into the single `<path>`'s `d` string instead (an uncapped path string also
  grows unbounded, even though the element count stays at one `<path>`). Auto `min`/`max` is still
  scanned from the _full_ pre-decimation `values` array, so a real extreme value that decimation
  happens to drop can't silently narrow the rendered scale.
- Point order mirrors under RTL while the numeric sample order remains unchanged. There are no
  animations, so reduced-motion mode needs no alternate timing branch.
- **9.0 migration:** rename additive `type="bar"`/`"line"` to `mark="bar"`/`"line"`. Replace
  `type="area"` with `mark="line" appearance="solid"`. `values` is now property-only, matching its
  array type; use mirrored `data` for declarative space-separated samples.

---

## `lr-stat`

KPI/stat card — value + unit + label + optional icon/trend/caption.

Passive slotted content preserves normal pointer activation and Control/Meta/Shift intent. The
platform primary modifier and Shift activate a new browsing context through the real anchor;
listeners may cancel that activation. Nested interactive controls retain their own actions.
Temporary target and relation values are restored after activation unless the listener changed those
attributes itself.

Removing `caption` or `sub` omits the attribute fallback without hiding assigned slot content.
Removal retains `null` property readback; explicit empty strings remain empty and later supplied
values render normally.

**Renamed in 8.0.0 — breaking:** `appearance` is now `frame`. Library-wide, `appearance` means only
"how a control fills itself" and `frame` means "whether a container draws itself as a bounded card";
this property was always the second. There is no alias — `appearance` on `<lr-stat>` is an unknown
attribute now, so a stat left on `appearance="plain"` silently renders full card chrome again.

**Properties:**

- `label: string = ''`
- `accessibleLabel: string | null = null` (attribute `aria-label`) — when `href` is safe, this
  host-level override names the real whole-card anchor; removing it restores the natural
  label/value/unit name
- `value: string = ''`
- `unit: string = ''`
- `href?: string` — when it resolves to a safe URL, the root is a real whole-stat `<a>`; unsafe
  URL schemes keep the stat non-interactive. The anchor is stretched behind the visible content,
  so public slots remain semantic siblings rather than interactive descendants of the link
- `target?: string` — forwarded to the anchor while `href` is active; a nonempty target derives
  `rel="noopener noreferrer"` rather than exposing a separately settable `rel`
- `variant: LyraVariant = 'neutral'` (reflected) — the library's shared
  one semantic-tone vocabulary, tinting `[part="value"]`. **`brand` is new in 8.0.0**, so a stat
  whose headline is the primary metric no longer has to borrow `emphasis` (which is a card-chrome
  accent) to read as branded
- `deltaPercent: number | null = null` (attribute `delta-percent`) — a finite percentage delta;
  `null` hides the trend pill and any non-finite assignment normalizes to `null`
- `caption: string = ''`
- `goodDirection: 'up'|'down' = 'up'` (attribute `good-direction`) — which trend direction counts
  as "good"; inverts arrow/color polarity for cost/latency/error-rate-style metrics where a
  _decrease_ is the win.
- `rows: readonly StatRow[] = []` (attribute: false) — `StatRow { readonly label: string; readonly
value: string; readonly exactValue?: string }`; at most the first 10,000 rows are snapshotted and
  frozen at assignment. Reassign `rows` after changing it. The snapshot renders as a simple
  label/value breakdown list (`[part="rows"]`/`[part="row"]`/
  `[part="row-label"]`/`[part="row-value"]`) beneath the caption, hidden entirely when empty. A row's
  optional `exactValue` mirrors the headline `exactValue`/`exact-value` pattern: rendered as a `title`
  tooltip on that row's `[part="row-value"]` and gives it `tabindex="0"`, independently per row —
  unset rows are unaffected.
- `emphasis: boolean = false` (reflected) — visual emphasis (e.g. for a "headline" stat in a group):
  a brand-colored accent edge, orthogonal to the status `variant`; status semantics still win over
  it — `emphasis` only additionally tints `[part="value"]` brand-colored when `variant` is still
  `'neutral'`, never overriding an actual `success`/`warning`/`danger` value color
- `exactValue: string = ''` (attribute `exact-value`) — rendered as a `title` attribute on
  `[part="value"]` for a hover tooltip (e.g. `value="$1.2K" exact-value="$1,204.37"`); also gives
  `[part="value"]` `tabindex="0"` (only when set) so the tooltip is reachable by keyboard focus, not
  just hover
- `sub: string = ''` — a secondary line distinct from `caption`, e.g. a comparison-period label,
  rendered as `[part="sub"]` between the trend pill and the caption; hidden entirely when unset
- `prose: boolean = false` (reflected) — CSS-only variant that shrinks/lightens `[part="value"]` and
  hides `[part="unit"]`, for rendering a loading/status message in place of a numeric value
- `compact: boolean = false` (reflected) — tighter card padding; same convention as `lr-empty`'s and
  `lr-widget`'s `compact`
- `frame: 'card'|'plain' = 'card'` (reflected) — container treatment, on the library-wide `frame`
  vocabulary. `'card'` keeps the bordered, filled, padded box that stretches to fill its
  parent; `'plain'` removes the border, background, padding, corner radius **and** the
  `block-size: 100%` stretch, so the stat can sit inline in prose, a toolbar, or a table cell.
  `plain` wins over `compact` when both are set (there is no padding left to tighten), and it drops
  `emphasis`'s accent edge — that edge is card chrome — while `emphasis`'s brand value tint still
  applies. A `plain` stat with a safe `href` swaps the card's border-color/lift hover affordance
  (invisible with no border) for an underline on `[part="value"]`; the `:focus-visible` ring is
  unchanged
- `orientation: 'vertical'|'horizontal' = 'vertical'` (reflected) — layout axis. `'vertical'` stacks
  label, value, trend, sub and caption. `'horizontal'` lays label, value+unit, trend, sub and caption
  out on a single wrapping baseline row; `[part="spark"]` and `[part="rows"]` have no sensible place
  on a text baseline and stay stacked on their own full-width line beneath that row

**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 —
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
is provided). In a linked stat, an interactive slotted descendant keeps its own focus and action;
clicking non-interactive slotted content still follows the whole-card link.

**CSS parts:** `base` (a `<div>`, or an `<a>` for a safe `href`), `icon`, `label` (carries `hidden`,
and is collapsed, whenever `label` is empty — a label-less stat leaves no blank line above the
value), `value-row`, `value`, `unit`, `trend`, `sub`, `spark`,
`caption`, `rows`, `row`, `row-label`, `row-value` — `[part="value"]` gets `aria-labelledby` pairing
it with `[part="label"]`'s generated id whenever `label` is non-empty (so tabbing straight to the
`exactValue`-focusable value still announces e.g. "Revenue $1.2K USD", including the visible unit,
not just the bare value); each
`[part="row-value"]` is paired the same way with its own row's `[part="row-label"]`.

**Themeable custom properties:** `--lr-stat-bg` (default `var(--lr-color-surface)`) is
`[part="base"]`'s RESTING background — the tier a dashboard sits at all day, and the companion to
the linked card's existing pressed `--lr-stat-link-active-bg` (whose own default now mixes from
`--lr-stat-bg`, so one override retints both); `frame="plain"` still drops the fill entirely.
`--lr-stat-padding` (default `var(--lr-space-m)`) and
`--lr-stat-gap` (default `var(--lr-space-xs)`) control `[part="base"]`'s padding and gap in every
rendering path — the default card, `compact` (own defaults `var(--lr-space-s)` /
`var(--lr-size-0-125rem)`), `frame="plain"` (own default `0` for padding), and the internal
`.linked-content` wrapper used when `href` is set, so one override reaches a linked and an
unlinked stat identically. `--lr-stat-trend-good-color` (default `var(--lr-color-success)`)
and `--lr-stat-trend-good-bg` (default `color-mix(in srgb, var(--lr-color-success) 8%,
transparent)`) — text/background of `[part="trend"]` when its polarity (per `goodDirection`) is
"good"; `--lr-stat-trend-bad-color` (default `var(--lr-color-danger)`) and `--lr-stat-trend-bad-bg`
(default `color-mix(in srgb, var(--lr-color-danger) 8%, transparent)`) — the "bad"-polarity
counterparts. All four are independent of the headline value's `variant="success"`/`"danger"` tint,
so retinting the trend pill doesn't also recolor the value, and vice versa.
`--lr-stat-value-brand-color` (default `var(--lr-color-brand)`),
`--lr-stat-value-success-color` (default `var(--lr-color-success)`),
`--lr-stat-value-warning-color` (default `var(--lr-color-warning)`), and
`--lr-stat-value-danger-color` (default `var(--lr-color-danger)`) independently color the headline
value for each non-neutral `variant`. `--lr-stat-emphasis-border-color` and
`--lr-stat-emphasis-value-color` (both default `var(--lr-color-brand)`) independently color the
emphasis accent edge and a neutral emphasized headline without retinting `variant="brand"`.
Linked-card interaction paint is independently themeable through
`--lr-stat-link-hover-border-color` (default `var(--lr-color-brand)`),
`--lr-stat-link-hover-shadow` (default `var(--lr-shadow-s)`),
`--lr-stat-link-active-border-color`/`--lr-stat-link-active-shadow` (defaulting to their hover
counterparts), and `--lr-stat-link-active-bg` (defaulting to the existing active color mix). These
are point-of-use fallbacks, so values inherit from a theme ancestor and a value on `lr-stat` wins.

**Optional peer deps:** none.

```html
<lr-stat
  label="Active users"
  value="1,204"
  delta-percent="4.2"
  variant="success"
>
  <svg slot="start">...</svg>
</lr-stat>
<lr-stat label="Memories" value="128" href="/memories"></lr-stat>
```

**Known gotchas:**

- When `href` makes the whole stat a link, exact-value spans keep their hover tooltips but omit
  their own `tabindex` to avoid nesting focus targets inside the anchor.
- Slotted buttons, links, and other controls are outside the stretched whole-card anchor. Their
  actions never also navigate the stat; use a host `aria-label` when the link destination needs a
  more specific name than the visible label/value/unit.
- no `aria-live` region wraps `value`/`deltaPercent` — an in-place update after first render still isn't
  proactively announced to screen readers. The trend pill's direction/polarity is no longer
  conveyed by icon rotation/color alone, though: a visually-hidden span now spells it out in plain
  language (e.g. "increased 4.2%, good" / "decreased 2%, bad" / "unchanged"), so a screen reader
  landing on the pill (rather than being live-notified of a change) gets the full meaning, not just
  an `aria-hidden` arrow glyph.
- **9.0 migration:** rename `trend`/`trend=` to `deltaPercent`/`delta-percent`; replace the `NaN`
  absence sentinel with `null`. Import shared `LyraVariant` and `LyraFrame` directly; the redundant
  `StatVariant` and stale `StatAppearance` aliases were removed. Calling `click()` on a linked stat
  now activates its whole-card anchor exactly once.

---

## `lr-data-grid`

Virtualized client/server data grid with multi-sort, column filters, global search, grouping,
trees, row details, paging, pinning, resizing, reordering, selection, copy, and CSV export. Import
the granular registration module when the root bundle is not already loaded:

Repeated references to an admitted root row appear once in processed rows, pagination, facets, and
CSV, matching rendered canonical identity. The retained occurrence remains the original caller-owned
record. Clicking a supported interactive descendant, including a native control inside its open
shadow root, runs that control without also emitting `lr-cell-click`. Passive cell content continues
to activate the cell.

```js
import "@aceshooting/lyra-ui/components/data/data-grid/data-grid.js";
```

Give the grid an accessible name with `label` or a host `aria-label`; the host attribute wins.
Collection inputs are clone-owned readonly snapshots, so reassign `data`, `columns`, `groupBy`, and controlled
state arrays to update them; mutating the array originally assigned has no effect.
Column records are also copied and frozen synchronously. Row object
identities are preserved so formatter callbacks and `selectedRows` still refer to caller records.
Column identity uses a nonblank `id`, then a nonblank `field`, then stable definition-object
occurrence; malformed, blank, and later-duplicate identities are omitted first-wins. When `rowKey`
is set, malformed, blank, and later-duplicate row identities are omitted first-wins before
rendering, focus, selection, expansion, or events. Without `rowKey`, stable row-object occurrence
replaces positional identity, so reordering the same records does not transfer DOM or controlled
state to another row.

Pagination exposes the same page-local ARIA row model in client and server modes. The header is row
one; current-page display rows and expanded detail rows begin at two; and `aria-rowcount` covers
only that page plus the header. In server mode, `total` still drives `pageCount` and the pager, but
does not inflate `aria-rowcount` while `aria-rowindex` restarts for each loaded page. Treat these
ARIA values as page-local positions rather than as the dataset-wide total.

**Properties:**

- `appearance: 'outlined' | 'plain' = 'outlined'` (`appearance`, reflected).
- `childRows: string | ((row) => readonly Row[] | undefined) | null = null` (`child-rows`) — dot path or
  callback for nested rows. Tree sorting stays within each parent and paging keeps a subtree with
  its top-level parent. Projection is iterative, cycle-safe, and bounded to 10,000 total rows and
  64 descendant levels; exceeding a budget renders the localized `tree-limit` notice.
- `columnOrder: readonly string[] = []` (JS-only) — empty preserves declaration order.
- `columns: readonly DataGridColumn<Row>[] = []` (JS-only).
- `data: readonly Row[] = []` (JS-only) — client rows, or the currently loaded server page.
- `dataSource: ((request) => Promise<{ rows, total }>) | null = null` (JS-only) — providing it
  enables server behavior.
- `error: boolean = false` (`error`, reflected) — reports a failed load. The body's single row
  becomes the built-in failed-load `<lr-empty>` (matching `<lr-table>`'s own `error` contract),
  keeping the header/toolbar/pager mounted around it; `loading` beats `error` beats every
  empty/no-columns/no-results branch. Host-controlled, like `<lr-table>`'s: the internal
  `dataSource` request cycle's own `lr-data-error` does NOT set it (that event's contract keeps
  prior rows rendered on a rejection), so a consumer that wants a specific rejection to replace the
  row content sets `error = true` from its own `lr-data-error` listener.
- `errorHeading?: string` (`error-heading`) — failed-load heading override. Omitted localizes
  `<lr-table>`'s own `tableLoadFailed` default.
- `errorDescription: string = ''` (`error-description`) — failed-load supporting copy.
- `expandedRowKeys: readonly Array<string | number> = []` (JS-only).
  The mirrored `expandedKeys` spelling remains a compatibility alias for this same state.
- `filterDebounce: number = 250` (`filter-debounce`) — finite server search/filter delay.
- `filteredCount: number` (read-only, JS-only) — matching client rows before paging.
- `filterFromLeafRows: boolean = false` (`filter-from-leaf-rows`) — retains ancestors of matching
  tree descendants.
- `filters: readonly Array<{ readonly id: string; readonly value: unknown }> = []` (JS-only).
- `groupBy: string | readonly string[] | null = null` (`group-by`) — a string accepts comma- or
  whitespace-separated column ids/fields.
- `label: string | null = null` (`label`).
- `loading: boolean = false` (`loading`, reflected).
- `maxMultiSort: number = 0` (`max-multi-sort`) — zero means unlimited; the oldest sort is dropped
  when a positive limit is reached.
- `page: number = 0` (`page`, reflected) — zero-based.
- `pageCount: number` (read-only, JS-only).
- `pageSize: number = 20` (`page-size`).
- `pageSizeOptions: readonly number[] = [10, 20, 50, 100]` (JS-only). A finite current `pageSize`
  absent from this list is still inserted into the selector, keeping visible and IDL state aligned.
- `paginate: boolean = false` (`paginate`, reflected).
- `pinnable: boolean = false` (`pinnable`, reflected).
- `reorderable: boolean = false` (`reorderable`, reflected).
- `resizable: boolean = false` (`resizable`, reflected).
- `rowClass: ((row) => string | null | undefined) | null = null` (JS-only).
- `rowDetail: ((row) => string | TemplateResult | Node) | null = null` (JS-only).
- `rowKey: string | null = null` (`row-key`) — dot path for stable selection/expansion identity.
- `searchFn: ((value, term, row) => boolean) | null = null` (JS-only).
- `searchTerm: string = ''` (JS-only).
- `selectable: '' | 'single' | 'multiple' | 'none' = 'none'` (`selectable`, reflected) — a bare
  `selectable` attribute means `multiple`.
- `selectableRows: ((row) => boolean) | null = null` (JS-only).
- `selectedRowKeys: readonly Array<string | number> = []` (JS-only).
  The mirrored `selectedKeys` spelling remains a compatibility alias for this same state.
- `selectedRows: readonly Row[]` (writable, JS-only) — assigning rows that belong to the current source
  maps them to `selectedRowKeys`; detached rows are ignored and single-selection mode keeps the first.
- `selectionMode: 'none' | 'single' | 'multiple'` (`selection-mode`) — alias of `selectable` using
  `<lr-table>`'s `selectionMode`/`selection-mode` spelling for the same row-selection concept, so a
  consumer migrating between the two grid components doesn't need to remember two names.
  `selectable` remains canonical (mirrored from `wa-data-grid`); this alias reads and writes
  `selectable` directly, so there is no separate value to fall out of sync, and the bare `''`
  shorthand for `selectable`'s own `multiple` normalizes to `'multiple'` when read back through it.
- `server: boolean = false` (`server`, reflected).
- `size: 'xs' | 's' | 'm' | 'l' | 'xl' | 'small' | 'medium' | 'large' = 'm'` (`size`, reflected).
- `sort: readonly Array<{ readonly id: string; readonly desc: boolean }> = []` (JS-only).
- `sortDescFirst: boolean = false` (`sort-desc-first`).
- `striped: boolean = false` (`striped`, reflected).
- `total: number = -1` (`total`) — server total; `-1` derives from loaded/matching rows.
- `withColumnMenu: boolean = false` (`with-column-menu`, reflected).
- `withColumnsMenu: boolean = false` (`with-columns-menu`, reflected).
- `withoutSortRemoval: boolean = false` (`without-sort-removal`, reflected).
- `withSearch: boolean = false` (`with-search`, reflected).

`DataGridColumn<Row>` accepts `id`, dot-path `field`, `label`, `align`, numeric `width` /
`minWidth` / `maxWidth`, `flex`, `formatter(value, row)`, `cellTitle(row)`, computed `value(row)`,
`sortable`, `sortFn`, `comparator`, `sortDescFirst`, `sortUndefined`, `searchable`, `filterable`,
`filterType`, `filterFn`, `hidden`, `hideable`, `resizable`, `movable`, `pinnable`, `pinned`,
`footer`, `aggregation`, and `aggregatedFormatter`. A column with neither `field` nor `value` is an
action column: its formatter receives `undefined`, and it is not sorted or searched by default.
`cellTitle(row) => string | undefined` renders as the generated cell's native `title`, symmetrical
with `<lr-table>`'s `columns[].cellTitle` — e.g. the untruncated text behind an ellipsized cell, or
a formatted timestamp behind a relative one. Returning `undefined` or `''` omits the `title`
attribute entirely rather than rendering `title=""`, which would suppress an ancestor's own tooltip.

Built-in sort algorithms are `alphanumeric`, `alphanumericCaseSensitive`, `text`,
`textCaseSensitive`, `datetime`, and `basic`; `comparator` takes precedence. Built-in filter types
are `text`, `equals`, `number-range`, `date-range`, `set`, `includes-any`, and `includes-all`;
`filterFn` takes precedence in client mode. Group aggregations are `sum`, `min`, `max`, `mean`,
`median`, `count`, `unique`, `uniqueCount`, `extent`, or a callback.

**Methods:**

- `autoSizeColumn(columnId)` and `autoSizeColumns()` manage measured widths. `sizeColumnsToFit()`
  reserves visible effective zero-flex column widths and selection-control allocation before
  dividing the remaining width proportionally among flexible columns. Fixed widths are preserved;
  min/max clamps still apply, and an all-fixed grid is unchanged. Maximum clamps can leave unused
  space, while incompatible minimum widths can still overflow.
- `collapseAllRows()`, `collapseRow(key)`, `expandAllRows()`, and `expandRow(key)` update expansion
  without emitting the user-only row events.
- `copySelectedRows(options?: DataGridCopyOptions)` copies selected rows (or all processed rows
  when selection is empty) as TSV by default and returns the copied row count. Its options include
  `columnIds`, `includeHeaders`, `format: 'tsv' | 'csv'`, `escapeFormulas`, and `delimiter`; an
  explicit delimiter overrides the one normally selected by `format`. Clipboard settlement is
  asynchronous: `lr-copy` fires only after the owning context's write fulfills (including a
  successful legacy textarea fallback), while rejection emits `lr-error` plus `lr-copy-error` and
  announces the localized `copyFailed` string. Copy intent alone is never reported as success.
- `exportDataAsCsv(options?: DataGridExportOptions)` downloads formula-safe delimited data (CSV by
  default); `getDataAsCsv(options?: DataGridCsvOptions)` returns it without downloading. Options include `delimiter`,
  `includeHeaders`, `columnIds`, `escapeFormulas`, and `fileName`. The Lyra-only `columns` and
  `filename` aliases were **removed in 9.0.0** — rename them to `columnIds` and `fileName` (the
  spellings `wa-data-grid` uses); an unrenamed call silently falls back to every visible column and
  `data.csv`. Formula escaping is on by default for string cells beginning with `=`, `+`,
  `-`, or `@`; numeric values remain numeric.
- `focus(options?)` focuses the current roving header/cell stop.
- `getColumnFacets(columnId)` returns `{ uniqueValues: Map, minMax? }`, computed after every other
  filter but before the named column's own filter. Server mode returns an empty map.
- `getColumnPin(columnId)`, `pinColumn(columnId, side: 'left' | 'right' | 'start' | 'end' | false)`, and
  `toggleColumn(columnId, visible)` read or change column state without emitting the corresponding
  user-only events. `left`/`start` mean logical inline-start and `right`/`end` mean logical
  inline-end, so both pairs mirror under RTL; pass `false` to unpin.
- `getProcessedRows()` returns a frozen readonly snapshot of matching sorted rows before paging;
  `getVisibleRows()` returns a frozen readonly snapshot of the current effective page.
- `getState()`, `setState(state)`, `resetState()`, and `resetColumns()` serialize or restore view
  state. `getState()` is detached, frozen, and JSON-safe (Set filter values become arrays). Unknown
  column ids are ignored. `resetState()` intentionally preserves selection, page, and page size.
- `handleColumnsChange()`, `handlePageChange()`, and `handleSearchTermChange()` are public handler
  seams used by the built-in controls.
- `reload()` forces the current server request.
- `scrollToIndex(index, options?: DataGridScrollOptions)` addresses a processed row, maps it through
  group/tree/detail display rows, and scrolls with `align: 'start' | 'center' | 'end'`. A row hidden
  in a collapsed branch is a no-op.

**Server mode:** `dataSource` receives `{ sort, filters, search, page, pageSize, signal }`. A newer
request aborts and supersedes the previous one; rejected requests keep prior rows and emit
`lr-data-error`. Filter/search requests use `filterDebounce`; sorting and paging load immediately.
For event-driven loading, set `server`, listen to the mirrored `request` event, and assign `data`,
`total`, and `loading` yourself. The redundant Lyra-only `lr-data-request` event was removed in
9.0.0; rename that listener to `request`. Each dispatch carries a fresh frozen detail that cannot
mutate the component or loader request.

**Keyboard:** headers and cells share one roving grid stop; the scrollable `body` is separately
focusable so keyboard users can pan overflowing content. Arrow keys traverse cells, Home/End
traverse a row, Ctrl+Home / Ctrl+End reach grid ends, PageUp/PageDown move a page, Enter
sorts/activates, Space selects, Shift+Arrow reorders a header, Alt+Arrow resizes from the header,
unmodified Left/Right adjusts a focused separator, Ctrl+A selects
the current page, Ctrl+C copies, and Shift+F10 requests a cell context menu. Inline-direction
movement swaps under RTL. Keyboard events from an interactive formatter descendant remain owned by
that descendant.

**Events:** `request`; `lr-cell-click` and cancelable `lr-cell-contextmenu` carry canonical
`rowKey`/`columnId` alongside the row, column, value, and display index (canceling the latter suppresses the
native menu); `lr-column-move`; `lr-column-pin`; `lr-column-resize` (`detail.finished` distinguishes
live and committed resize). `pointerup` commits a pointer drag. `pointercancel` or lost capture
restores the exact pre-gesture width state; after a live move it emits the restored width with
`finished: false`, and it never emits a canceled `finished: true` commit. `lr-column-visibility-change`;
`lr-data-error`;
`lr-filter-change`; `lr-page-change`; `lr-row-collapse`; `lr-row-expand`; `lr-group-collapse` and
`lr-group-expand` (frozen `{ key, columnId, value, rows }` snapshots); `lr-row-select` with
canonical `{ selectedRowKeys, selectedRows }` plus mirrored `selectedKeys`; row expand/collapse
details use canonical `rowKey` plus mirrored `key`; cancelable `lr-sort-request` (frozen readonly
`detail: { sort }`) precedes `lr-sort-change`; vetoing it leaves `sort` unchanged and suppresses
`lr-sort-change`, mirroring `<lr-table>`'s identical `lr-sort-request`/`lr-sort` veto-then-commit
contract;
`lr-copy` (frozen `{ ok: true, text }` after fulfillment); `lr-copy-error`
(frozen `{ ok: false, text, reason, error }` after failure); `lr-error` (compatibility failure
notification with no raw platform error text); `lr-data-error` does NOT itself set the built-in
`error` state (see `error` above); `lr-retry` (`detail: null`, cancelable) — the built-in
`[part='retry-button']` was activated, only rendered while `error` is set; the default action
clears `error`, `preventDefault()` leaves it set instead. Every library event bubbles and is
composed; only `lr-cell-contextmenu`, `lr-sort-request`, and `lr-retry` are cancelable. Structured
details and their owned collections are frozen. The toolbar search and active column-filter inputs
re-dispatch `focus` and `blur` once from the grid host as bubbling, composed native `FocusEvent`s,
preserving `relatedTarget` so delegated ancestors can observe editor entry and exit without
crossing the shadow boundary.

**Slots:** `empty`, `loading`, `no-results`, `error` (replaces the built-in failed-load state,
including its retry button, while `error` is set).

**CSS parts:** `body`, `cell`, `column-menu`, `column-menu-button`, `columns-menu`, `data-grid`,
`drag-ghost`, `ellipsis`, `empty`, `error-row` (the single full-width row that replaces the body
content while `error` is set), `error-cell`, `error` (the built-in `<lr-empty>` host), `error-base`,
`error-icon`, `error-heading`, `error-description`, `error-actions` (all four exported from the
built-in error `<lr-empty>`'s own parts), `retry-button` (the built-in retry control), `expand-button`,
`filter-button`, `filter-panel`,
`filter-panel-clear` (clears the active column filter editor, replacing the native search-cancel
glyph the component resets; rendered only while it has a value), `first-button`,
`first-icon`, `footer`, `footer-cell`, `footer-row`, `group-count`, `group-row`, `group-value`,
`header`, `header-cell`, `last-button`, `last-icon`, `live-region`, `loading-overlay`,
`next-button`, `next-icon`, `no-results`, `page`, `page-current`, `page-size`, `pager`,
`pager-button`, `pin-indicator`, `previous-button`, `previous-icon`,
`resize-handle`, `row`, `row-detail`, `search`, `search-wrapper` (the row wrapper around `search`
and `search-clear`), `search-clear` (clears the global row-search input, replacing the native
search-cancel glyph the component resets; rendered only while it has a value),
`select-all-checkbox`, `sort-indicator`,
`sort-number`, `table`, `toolbar`, `tree-limit`.

Each per-column disclosure opens an honestly named native-control `group`, not a false ARIA menu:
its buttons have localized pin-to-start, pin-to-end, and unpin names; its visibility toggle has one
native checkbox semantic owner; and `aria-controls` links trigger and group. The per-column group,
column-filter panel, and all-columns visibility group are mutually exclusive and use the shared
topmost overlay router, so Escape closes only the active disclosure and returns focus to its own
trigger. Resize separators are focusable and expose finite `aria-valuemin`, `aria-valuemax`, and
`aria-valuenow`; inverted bounds collapse to the minimum. Revoking resize/reorder capability during
a gesture rolls it back, and column drops require the current grid's owned drag token plus current
source/target capability.

The four pager navigation controls each wrap their glyph in an icon part — `first-icon`,
`previous-icon`, `next-icon`, `last-icon` — rendered as real chevron SVGs rather than literal
`«`/`‹`/`›`/`»` text, so they mirror under `dir="rtl"` instead of pointing the wrong way. `first-icon`
and `last-icon` hold two overlapping chevrons so the pair reads as one doubled glyph. This matches
`<lr-pagination>`'s identical treatment; style the glyph through the icon part and the control
through `first-button`/`previous-button`/`next-button`/`last-button` (or the shared `pager-button`).

`[part="live-region"]` is a visually-hidden, `aria-hidden` **mirror** of the last polite
announcement — a styling and inspection surface, with no live-region role of its own. The
announcement itself goes to the library's shared **light-DOM** polite region, appended to the
consumer's `<body>` and marked `data-lr-live-region="polite"`, because a live region inside a
shadow root is not reliably announced (JAWS with Firefox ignores one outright). Assert against that
document-level region rather than `::part(live-region)`; the part still tells you what the grid
last announced.

Declarative `loading` is silent on mount. Each later `false` → `true` transition appends the
localized loading text to that shared polite sink, including repeated loading cycles. The visible
`loading-overlay` is ordinary non-live content, and the grid exposes the state with `aria-busy`.

**Themeable custom properties:** `--accent-color`, `--background-color`, `--border-color`,
`--border-radius`, `--border-width`, `--cell-padding`, `--focus-ring`, `--header-background`,
`--header-row-height`, `--header-text-color`, `--indent-size`, `--max-height`, `--row-height`,
`--row-hover-background`, `--selected-background`, `--stripe-background`, `--text-color`, and
`--transition-duration`. Defaults resolve through Lyra design tokens. Set `--max-height: none` to
render every row instead of a virtual window. Three grid-specific hooks reach formatter and row
detail content inside the shadow root: `--lr-data-grid-cell-color` (default `inherit`) controls
body-cell text, `--lr-data-grid-cell-link-color` (default `var(--lr-color-brand)`) controls nested
anchors, and `--lr-data-grid-cell-link-hover-color` (default
`var(--lr-data-grid-cell-link-color, var(--lr-color-brand))`) controls those anchors on hover,
focus-visible, and active interaction. Set the link color to `revert` to restore the user-agent
default. Six independent interaction-background hooks preserve those state boundaries:
`--lr-data-grid-control-hover-background` and `--lr-data-grid-control-active-background` theme
search, toolbar, pager, and resize controls; `--lr-data-grid-page-size-active-background` themes
the page-size selector when pressed; `--lr-data-grid-row-active-background` themes pressed data
rows; and `--lr-data-grid-sortable-header-hover-background` and
`--lr-data-grid-sortable-header-active-background` theme sortable header states. They default to
live `color-mix()` values of the effective grid accent and transparent, using the corresponding
`--lr-color-mix-hover` or `--lr-color-mix-active` token (the page-size pressed state intentionally
uses the hover mix), so an accent override remains coherent while each surface can still be
overridden independently.

```html
<lr-data-grid
  label="Engineering roster"
  row-key="id"
  selectable
  with-search
  paginate
  page-size="20"
></lr-data-grid>
<script type="module">
  const grid = document.querySelector("lr-data-grid");
  grid.columns = [
    { field: "name", label: "Name", filterable: true },
    { field: "score", label: "Score", align: "end" },
  ];
  grid.data = [{ id: 1, name: "Ada", score: 97 }];
</script>
```

**Known gotchas:** selection and expansion are only stable across sort/filter/server page changes
when `rowKey` names a unique string/number field. CSV/copy uses a formatter only when it returns a
string; templates and Nodes fall back to the raw value. Server export/copy includes currently loaded
rows because the browser does not possess unloaded pages.

---

## `lr-table`

Sort/select-aware data table with a bounded 100-row default projection. A sortable header first
emits cancelable `lr-sort-request`; accepted transactions emit `lr-sort` with the same canonical
`sortKey`/`sortDir`. Client mode updates sort state and orders rows; server mode leaves sort state
controlled. Optional filtering, bounded pagination, and loading chrome are built in. A
`columns[].heatValue`-opted-in heat-tint mode paints a shared, normalized color-mix background across
every tinted cell (auto-derived domain, or overridden via `heatTintScale`); `rowTotal`/`grandTotal`
add a trailing totals column mirroring `expandedContent`'s leading one — `rowTotal(row)` renders
per-row, `grandTotal(rows)` renders at its intersection with the footer row — both sharing `footer`'s
own "consumer computes/renders" contract rather than assuming addition.

Effective locale changes recollate and filter the current view while keeping activation and edit
lookups aligned with the rendered page. Direct row focus uses the same stable-key restoration rules;
programmatic locale changes do not emit a row action.

Header cells and body rows use separate roving tab stops. When a controlled `columns` or rendered
row collection changes while one of those stops owns focus, the table keeps the same stable key if
it survives and otherwise clamps focus to the nearest surviving index. Moving focus outside the
table before the update is applied always wins; nested editors and controls keep their independent
focus contracts.

**9.0 migration:** replace `selectedKey = key` with `selectedRowKeys = new Set([key])`; both single
and multiple modes now use that one store. Replace `columnsHidden` with read-only
`hasHiddenPriorityColumns`, `showAllColumns` with `priorityColumnsVisible`, and the two former
column-visibility events with `lr-priority-columns-visibility-change { visible }`. Column
`sticky: true` becomes `sticky: 'start'`; `editable: true` becomes
`editTrigger: 'double-click'`, and `editable: 'always'` becomes `editTrigger: 'always'`. Sort
listeners now receive phased readonly `{ phase, sortKey, sortDir }` details from
`lr-sort-request`/`lr-sort`. A bare table now projects 100 rows per page (with inputs bounded to
1..500); set an explicit finite `page-size` when a different window is required.

**TypeScript:** `LyraTable<T, K extends string | number = string | number>` takes a second type
parameter for the row-key type. `K` types `rowKey`'s return value,
`selectedRowKeys`/`expandedRowKeys`, and every event detail's `rowKey`/`rowKeys`, so
`LyraTable<Row, number>` reads `event.detail.rowKey` as `number` with no cast. It defaults to the
`string | number` union, so an untyped element and an existing `LyraTable<Row>` annotation compile
unchanged.

**Properties:**

- `columns: readonly TableColumn<T>[] = []` (attribute: false; clone-owned frozen collection,
  bounded to the first 10,000 source positions; blank keys and later duplicates are omitted first-wins
  before header, cell, sort, focus, and event paths; reassign to update) — `{ key, label,
headerCell?, width?, minWidth?, maxWidth?,
resizable?, sortable?, sortValue?, defaultSortDir?: 'asc'|'desc', align?: 'start'|'end',
priority?: 'medium'|'low',
sticky?: 'start'|'end', editTrigger?: 'double-click'|'always', editValue?, editLabel?: (row) => string,
editType?: 'text'|'number'|'select',
editOptions?: { value: string; label: string }[], footer?, cellStyle?, heatValue?,
cell: (row) => unknown }` — `cell` is required for every `editTrigger` except `'always'`, whose
  persistent editor renders unconditionally so the table's render path never falls back to it —
  `sortValue(row) => string | number | null | undefined` supplies the comparable value backing
  client-mode sorting for that column: a finite number sorts numerically, a string sorts through an
  `Intl.Collator` built from the component's effective locale with `numeric: true` (so `item2`
  precedes `item10`), and `null`/`undefined`/non-finite sorts **last in both directions** so
  flipping `sortDir` never floats a block of blanks to the top. Omit it and the column sorts by its
  stringified `cell()` output instead — meaningful only when `cell()` returns a string or number, so
  define `sortValue` whenever `cell()` returns a template or element. Ignored under
  `sortMode="server"` and on a column that is not `sortable`;
  `defaultSortDir` sets this column's own initial sort direction the first time header activation
  makes it the active `sortKey`, taking precedence over the element-level `defaultSortDir` (see
  below), which remains the fallback when this is omitted — useful for giving one column in an
  otherwise-ascending table (e.g. a "last updated" column) the opposite starting direction.
  Re-activating a column that is already `sortKey` still only toggles between `'asc'` and `'desc'`,
  exactly as the element-level `defaultSortDir` already does;
  `priority` progressively hides that column once `[part='base']`'s content actually overflows it —
  `'low'` hides first, and `'medium'` hides too if the table would still overflow with just `'low'`
  gone — measured via the same `ResizeObserver`-driven overflow check `scroll-mode="auto"` uses, never
  at a fixed container width (there is deliberately no themeable-token form of this: a `@container`
  query, which is what a token-driven threshold would need, can only ever read ancestor inline-size,
  never a measured overflow amount), reversible via
  `[part='reveal-columns-button']`; `sticky` pins that column's header/cells to the logical start or
  end edge while the table scrolls horizontally — multiple sticky columns stack
  in logical order (each measures every earlier sticky column's rendered width via
  `--lr-table-sticky-offset`) instead of overlapping at the same edge. A sticky body cell's
  background always matches its own row's effective fill — striped, selected, hovered, or pressed —
  rather than painting a flat opaque surface over that state; a sticky header cell is unaffected
  (headers are never striped/selected) and keeps its plain surface fill, see
  `--lr-table-row-selected-bg`/`--lr-table-row-stripe-bg` below; `footer` renders a
  sticky-bottom footer cell for that column, computed from every currently-rendered row (post-sort,
  pre-pagination) — e.g. a column total — omit it for a column with no footer value, and a
  `[part='foot']` (`<tfoot>`) only renders at all when at least one column defines `footer`;
  `heatValue(row) => number | null | undefined` opts a column into heat-tint mode: its presence on
  any column is the opt-in signal (no separate boolean), a `null`/`undefined` return excludes that
  cell from both the domain and the tint ("no data", not "zero"), and every `heatValue`-defining
  column shares one normalized `color-mix()` background scale (see `heatTintScale` below) painted
  via the retheme-able `--lr-table-heat-tint-lo`/`-hi` custom properties, matching `lr-heatmap`'s
  own ramp-token convention; `cellStyle` is applied directly to the generated `<td>` via `styleMap` — e.g. a computed heat-tint
  background a `cell()`-returned inner element can't paint into the cell's own padding — omit it for
  no per-cell style override (the default, unchanged output);
  `editTrigger: 'double-click'` opens a native editor on that cell's double-click, `F2`, or `Enter`
  (one cell at a time), while `'always'` renders a persistent editor in every body cell from first paint, for a
  settings/rate-style column meant to be typed straight into — while `editValue` supplies the editor
  value and `editType` selects `'text'`, `'number'`, or `'select'` (a native `<select>` populated
  from `editOptions: { value: string; label: string }[]`, one `<option>` per entry in order; a
  `'select'` column with no `editOptions` renders an empty, valueless `<select>` instead of
  throwing); `editLabel(row) => string`, read once per row exactly like `editValue`/`cellTitle`,
  overrides that editor's accessible name — omit it and every editor in the column shares the same
  interpolated `tableEditCell` name instead (see the accessibility note under `editTrigger` below)
  `cellTitle(row) => string | undefined` is the `title` analogue of `cellStyle`, applied directly to
  the generated `<td>` — e.g. the untruncated text behind an ellipsized cell, or a formatted
  timestamp behind a relative one;
  `resizable` adds a focusable separator `[part='resize-handle']` and emits `lr-column-resize` with
  the live width in CSS pixels. Drag it, or use logical ArrowLeft/ArrowRight for 10px steps (mirrored
  under RTL), Shift+Arrow for 50px steps, Home for the minimum, and End for an explicit pixel
  `maxWidth`; explicit pixel `minWidth`/`maxWidth` values bound both input paths. The separator
  exposes its current/minimum/bounded-maximum pixel width through ARIA value attributes. Only the
  _commit_ is vetoable — see `lr-column-resize` under Events.
- **`cellStyle` beats `heatValue`, always.** `styleMap` writes an inline `style=` attribute, and an
  inline style outranks any stylesheet rule in the cascade regardless of specificity, while the heat
  tint is painted by a shadow-stylesheet rule. So a `cellStyle` returning
  `background`/`backgroundColor` on a column that also defines `heatValue` silently and completely
  erases that column's tint — no warning, and the cell still contributes to the shared domain, so the
  _other_ tinted columns' scale shifts around a cell that shows no tint at all. Define both on one
  column only when that override is the intent; to tint _and_ style, return only non-background
  declarations (`color`, `fontWeight`, `textAlign`, …) from `cellStyle`.
- `columns[].editTrigger: 'double-click' | 'always'` — `'double-click'` opens one transient editor;
  Enter commits and closes, Escape cancels and closes, and blur-after-change commits. `'always'`
  renders an editor in
  every body cell of that column, permanently:
  - **Keyboard entry (`'double-click'` columns).** The resting (not-currently-editing) cell of a
    `'double-click'` column is its own roving-focus stop — `tabindex="-1"`, carrying `[data-editable]`
    — reachable once the row itself has focus: ArrowRight (ArrowLeft under RTL) enters at the first
    editable cell in the row and steps forward through any further ones; ArrowLeft (ArrowRight under
    RTL) steps back and, from the first editable cell, returns focus to the row. None of this is a Tab
    stop — a table with a `'double-click'` column gains no new entry in the page's Tab order, only a
    new arrow-reachable one — and a table with no `editTrigger` column at all renders no `tabindex`/
    `[data-editable]` anywhere. `F2` or `Enter` on the focused cell opens its editor; `Enter` on the
    row itself (no cell focused) still only activates the row. `editCell(rowKey, columnKey)` (see
    Methods above) is the same open action as a public method. Closing the editor, by commit or by
    cancel, returns focus to the cell that opened it.
  - **Focus model (`'always'` columns).** Each editor is a plain tab stop — no `tabindex` of its own
    — exactly like the
    existing row-expand toggle, and stays _outside_ the header/row/cell roving-tabindex model. Tab
    walks
    down the column; arrow keys still navigate the grid from a row's own roving stop, and act as
    ordinary caret movement once focus is inside a field. Non-editable columns are unaffected.
  - **Value binding.** A persistent `'text'`/`'number'` editor binds its `value` as a **content
    attribute**, not as the `.value` property, so native dirty-value-flag semantics apply.
    Trade-off: once the user has typed into a cell, an out-of-band `rows` update to that same cell
    will **not** visibly replace their draft. An editor the user has not touched still picks up a
    new `rows` value normally. A persistent `'select'` editor has no equivalent protection —
    `<select>`/`<option>` carry no native dirty-value flag, so an out-of-band `rows` update to that
    cell re-applies the selection even after the user has picked a different, uncommitted option.
    `lr-cell-edit` remains the only mutation channel — the table never mutates `row`.
  - **Keys.** Enter commits (emits `lr-cell-edit`) and _keeps focus_ in the field, since there is no
    closed state to fall back to. `change` (blur after a modification) commits in both modes.
    Escape is **not** cancelled and does nothing to the editor — there is nothing to cancel back to
    — so an ancestor dialog/popover still acts on it.
  - **Focus across re-sorts and pagination.** Rows are keyed, so a re-sort _moves_ the editor's
    `<input>` (the typed value rides along) and the table restores focus to the same logical cell
    afterwards. If the focused row leaves the rendered page entirely (pagination, filtering), focus
    is simply lost rather than yanked to whichever unrelated row now sits in that position.
  - **Accessible name.** Each editor's name is `columns[].editLabel(row)` when the column defines
    it, or otherwise the interpolated `tableEditCell` string (`Edit {column}`) — identical for every
    row in that column, since the default has no row context. That default is adequate for
    `'double-click'`, where at most one editor is ever open, but not for `'always'`: every row's
    editor there is a permanent, individually focusable Tab stop, so leaving `editLabel` unset on an
    `'always'` column exposes as many identically named controls as there are rows (e.g. fifty "Edit
    Status" comboboxes), failing WCAG 2.4.6 and 1.3.1. Define `editLabel` for any `'always'` column
    to give each row's editor its own name.
- `hasHiddenPriorityColumns: boolean = false` (attribute `has-hidden-priority-columns`, reflected) —
  computed/read-only and true only while a priority column is actually hidden. It becomes false
  when `priorityColumnsVisible` reveals the columns. Measured via a `ResizeObserver` on
  `[part='base']` plus a post-render DOM check, so it settles one render cycle after a `columns`/
  `rows`/width change lands — poll for the settled value (e.g. `await el.updateComplete;` twice, or
  `waitUntil()`) rather than assuming a single `updateComplete` covers it. Setting it directly has no
  lasting effect; it is recomputed on the next render or resize. The toggle remains available while
  a narrow table is revealed, even though this property truthfully reports false
- `rows: readonly T[] = []` (attribute: false; clone-owned frozen collection bounded to the first
  10,000 rows; reassign to update). Records are retained
  here; one canonical `rowKey` projection omits blank and later-duplicate identities first-wins
  before filtering, counts, pagination, focus, actions, and events
- `layout: 'auto'|'fixed' = 'auto'` (reflected) — a **floor** on the `<table>`'s `table-layout`, not
  an override. `'fixed'` forces the fixed algorithm even when no column declares a `width`, so every
  column shares the available width evenly and long cell content is clipped/wrapped instead of
  stretching its column. The default `'auto'` still _resolves_ to `fixed` whenever a column declares
  a `width`, a column has been drag-resized, or a resize gesture is in flight — column resizing does
  not work under `table-layout: auto`, so `'auto'` can never mean "never fixed". See the gotchas for
  the two consequences of the fixed algorithm worth knowing before opting in
- `sortKey: string = ''` (attribute `sort-key`)
- `sortDir: 'asc'|'desc' = 'asc'` (attribute `sort-dir`)
- `sortIndicators: TableSortIndicators = 'active'` (attribute `sort-indicators`) — `'all'` adds a
  muted bidirectional indicator to each inactive sortable header, reserving the same space as the
  active chevron. The default retains only the active column's indicator. This presentation does
  not change keyboard interaction, client/server sorting, or `aria-sort="none"` on inactive columns.
- `sortMode: 'client'|'server' = 'client'` (attribute `sort-mode`, reflected) — mirrors
  `paginationMode`'s identical split. `'client'` (the default) orders `rows` in the browser from
  `sortKey`/`sortDir` and the active column's `sortValue`; `'server'` renders `rows` exactly as
  given, for a table whose ordering already happened server-side. Accepted header activation emits
  `lr-sort` under both modes, but only client mode mutates `sortKey`/`sortDir`. With no `sortKey` set
  (the default) `'client'` is a **no-op** — the
  input order is preserved verbatim — so a table that never sorts renders identically either way.
  Sorting applies to the whole filtered set _before_ client pagination slices the page, so page 1
  holds the globally-smallest rows rather than a re-sorted slice
- `defaultSortDir: 'asc'|'desc' = 'asc'` (attribute `default-sort-dir`) — the direction applied
  whenever header activation switches sorting to a **different** column, including the first column
  ever sorted, for any column that does not declare its own `columns[].defaultSortDir` (that
  column-level value wins first when set — see `columns` above). Re-activating the column that is
  already `sortKey` toggles between `'asc'` and `'desc'` instead, so `defaultSortDir` never
  overrides a direction the user just chose for the column they are still on. Set `'desc'` for a
  most-recent-first or highest-first table
- `viewRows: readonly T[]` (readonly; computed, no attribute) — `rows` after filtering and
  (client-mode) sorting, ignoring pagination — the same set `columns[].footer(rows)`/
  `grandTotal(rows)`/the heat-tint domain already compute over. Read this instead of
  re-implementing filtering/sorting in a consumer that needs "what the grid currently shows" (e.g.
  to export it). A fresh, frozen array on every read: mutating the result cannot reach or corrupt
  the table's own internal state
- `pageRows: readonly T[]` (readonly; computed, no attribute) — `viewRows` sliced to the page
  currently rendered in `<tbody>`. Same defensive-copy guarantee as `viewRows`
- `rowKey?: (row: T) => K` (attribute: false) — derives each row's stable identity for
  DOM-reconciliation and the delegated row click/keydown lookup; falls back to the row's array index
  when omitted, which is only safe while `rows` never reorders — set it whenever `rows` can be
  sorted/filtered/re-ordered across renders, or selection/click can silently attach to the wrong
  row. Empty string identities and later duplicates are omitted; the first valid occurrence wins.
  The element's second type parameter (`K`, default `string | number`) is this callback's return
  type
- `selectionMode: 'none'|'single'|'multiple' = 'none'` (attribute `selection-mode`, reflected) —
  opt-in self-managed row selection; the default remains presentational
- `selectedRowKeys: ReadonlySet<string | number> = new Set()` (attribute: false) — the single selection
  store in every mode, bounded to 10,000 keys. Single mode enforces at most one key; multiple mode
  toggles membership. Malformed and whitespace-only string keys are omitted, while valid
  unmatched/off-page keys remain controlled state for server pagination. Reads return immutable detached `ReadonlySet`
  facades; reassign a new set to update
- `filterable: boolean = false` (attribute `filterable`, reflected) — renders a localized search
  field above the grid
- `filterText: string = ''` (attribute `filter-text`) — controlled filter text. Removing the
  attribute clears the effective filter safely while retaining native removal readback; a later
  supplied value filters normally.
- `filter?: (row: T, text: string) => boolean` (attribute: false) — typed predicate used by the
  filter field; when omitted, rows are matched against their JSON representation
- `filterLabel?: string` (attribute `filter-label`) and `filterPlaceholder?: string`
  (attribute `filter-placeholder`) — omission localizes `tableFilterLabel`/
  `tableFilterPlaceholder`; any supplied string, including the built-in English text or `''`, is
  an explicit verbatim override
- `spellcheck: boolean = true`, `autocapitalize: string = ''`, `autoCorrect: string = ''`
  (attribute `autocorrect`) — forwarded to the filter input and, for a `'text'` (the default)
  `editType`, the inline cell editor; no effect on a `'number'` or `'select'` cell editor. `spellcheck="false"`
  is parsed as `false` via a string-aware converter (Lit's default presence-based boolean
  converter would otherwise treat any attribute value, including the literal string `"false"`, as
  `true`).
- `loading: boolean = false` (attribute `loading`, reflected) and `loadingLabel?: string`
  (attribute `loading-label`) — renders busy chrome and suppresses the real rows while loading;
  omission localizes `tableLoading`, while a supplied string (including `''`) renders verbatim
- `loadingAppearance: 'spinner'|'skeleton' = 'spinner'` (attribute `loading-appearance`, reflected) —
  how `loading` renders. `'spinner'` replaces the whole grid with an indeterminate spinner.
  `'skeleton'` instead renders the real table — the same `<colgroup>` (declared _and_ drag-resized
  widths included), the same `<thead>`, the filter field and the pagination footer — and fills
  `<tbody>` with placeholder rows, so a cold load sketches the grid's shape rather than collapsing to
  a spinner and reflowing when the rows land. Kept as a separate property rather than widening
  `loading` to a string union, so `?loading=${…}` bindings and `el.loading === true` checks keep
  working. Loading takes precedence over both empty branches. When `columns` is empty, a skeleton
  request temporarily falls back to the spinner because there is no schema to sketch; the table
  does not flash its no-columns empty state while `loading` remains true
- `skeletonRows: number = 0` (attribute `skeleton-rows`) — placeholder row count under
  `loadingAppearance="skeleton"`. `0` renders 3 placeholders for the ordinary bounded default, or
  derives a non-default explicit `pageSize` (capped at 20). Positive explicit values are also capped
  at 20. Ignored entirely under the default spinner appearance
- `pageSize: number = 100` (attribute `page-size`) — normalized to `1..500`; a bare table therefore
  never mounts an unbounded row-by-column projection
- `page: number = 1` (attribute `page`, reflected) — self-managed after accepted client pagination;
  controlled in server mode
- `totalItems: number = -1` (attribute `total-items`) — server-side total item count; `-1` derives
  the total from filtered rows
- `paginationMode: 'client'|'server' = 'client'` (attribute `pagination-mode`, reflected) — client
  mode slices rows and updates `page`; server mode leaves `page` controlled and bounds the supplied
  page to `pageSize`
- `unknownTotal: boolean = false` (attribute `unknown-total`, reflected) — server pagination for a
  caller with no total item count, only whether one more page exists (`hasNext`). Forwarded to the
  nested `<lr-pagination>` as its own indeterminate mode (`total="-1"`): previous/next only, no
  numbered page list, no item-range summary. Ignored outside `paginationMode: 'server'` — client
  mode always knows the exact row count it slices. A dedicated boolean rather than reusing
  `totalItems`'s own `-1` sentinel, which already means "derive from the currently matching rows"
- `hasNext: boolean = true` (attribute `has-next`, reflected) — whether at least one more page
  exists past the current one; consulted only alongside `unknownTotal` and forwarded verbatim to
  the nested `<lr-pagination>`'s own `hasNext`
- Editable columns emit `lr-cell-edit` on commit and never mutate the supplied row object.
- `groupBy?: (row: T) => string | number` (attribute: false) — inserts a non-focusable full-width
  group row wherever this key changes between consecutive rendered rows. Supply `rows` with each
  group already contiguous; the table renders the groups in their first-appearance order in `rows`
  and never reorders them. A client-mode sort is applied **within** each group, so sorting a
  grouped table on a column unrelated to the group key reorders rows inside their groups and
  leaves the grouping intact. The one exception: when the sorted column's value is constant inside
  every group — the group column itself, most obviously — there is nothing to reorder within a
  group, so the **groups** are ordered by that value instead.
- `groupLabel?: (key: string | number, rows: readonly T[]) => unknown` (attribute: false) — custom group
  header content; without it, the group key is rendered as text
- `expandedContent?: (row: T) => unknown` (attribute: false) — enables a leading expand toggle and
  renders a full-width detail row beneath expanded records. The returned content renders inside
  the component's shadow root, behind the `expanded-cell` part — page CSS cannot reach it, and
  `::part(expanded-cell)` only reaches the wrapping `<td>` itself, not the descendants this
  callback returns (the same `::part()` limitation a column's `cell(row)` anchors run into, see
  `--lr-table-cell-link-color` below). Style such content by returning already-styled elements —
  inline `style`, or elements that reference this table's own `--lr-*` design tokens, which
  inherit across the shadow boundary like any custom property. When script has to reach the
  rendered panel anyway, `expandedContentElement(rowKey)` (below) resolves that `<td>`;
  `rowElement(rowKey)` does not, because the panel is a sibling `<tr>` rather than part of the row
- `canExpand?: (row: T) => boolean` (attribute: false) — optional per-row gate for expansion
- `rowExpandLabel?: (row: T, expanded: boolean) => string | undefined` (attribute: false) —
  accessible name for one row's expand/collapse chevron, read once per render for that row,
  exactly like a column's `editLabel`/`cellTitle`; consumer-owned text used verbatim, never
  passed through localization. Omit it and every chevron shares the same localized
  `expand`/`collapse` name, which carries no row context — fine for a handful of rows, but each
  chevron is its own Tab stop, so a long table otherwise announces the same two names over and
  over with no way to tell the rows apart. There is no default row context to derive one from
  here: this component has no row-header notion (`rowKey` is an opaque identity, not a label)
- `expansionMode: 'none'|'single'|'multiple' = 'none'` (attribute `expansion-mode`, reflected) —
  mirrors `selectionMode` member for member, for expansion. The default `'none'` keeps
  `expandedRowKeys` fully consumer-controlled: an activation only reports `lr-row-expand-toggle`.
  `'single'` and `'multiple'` self-manage the set behind the cancelable `lr-row-expand-request`, so
  an expandable table needs no host handler at all; `'single'` keeps at most one row open and
  coerces an already-larger `expandedRowKeys` down to its first key when this property becomes
  `'single'` (no event for that fix-up — read `expandedRowKeys` back). Closing a row to make room
  for another is an ordinary expansion change, so `'single'` reports the displaced row with its own
  `lr-row-expand-toggle` (`expanded: false`) immediately **before** the accepted one — the one
  exception being a displaced row that is filtered or paged out of view, which has no `row` object
  for the detail to carry and is reported through `expandedRowKeys` alone. An unrecognized attribute
  value falls back to the controlled behaviour rather than self-managing
- `expandedRowKeys: ReadonlySet<string | number> = new Set()` (attribute: false; `ReadonlySet<K>` on a
  parameterized element) — expanded state bounded to 10,000 keys. Who writes it depends on
  `expansionMode`: under the default `'none'` the table never mutates it and consumers reassign it
  after `lr-row-expand-toggle`; under `'single'`/`'multiple'` the table writes it on each accepted
  activation, and a `preventDefault()` on `lr-row-expand-request` hands that one change back.
  Malformed and whitespace-only string keys are omitted while valid off-view keys remain controlled
  in every mode — filtering, sorting and pagination never clear them, so a row paged or filtered out
  of view comes back expanded and a key matching no current row simply renders nothing until one
  exists again (the same convention `selectedRowKeys` follows for server pagination). Reads return
  immutable detached `ReadonlySet` facades; reassign a new set to update
- `hasMore: boolean = false` (attribute `has-more`, reflected)
- `moreLabel?: string` (attribute `more-label`) — omission renders localized `loadMore` (`'Load more'` in the built-in English catalog); a supplied string, including `''`, renders verbatim
- `error: boolean = false` (attribute `error`, reflected) — replaces `<tbody>`'s row content with
  a built-in failed-load state while keeping the surrounding `<thead>`, filter field, and
  pagination mounted — unlike either data-empty branch below, which this state overrides and which
  replace that chrome too. Precedence when more than one state could apply at once: `loading` beats
  `error` beats every empty branch, so a `loading` table never shows a stale `error`, and an
  `error` table never falls through to "no rows"/"no columns" copy underneath it.
- `errorHeading?: string` (attribute `error-heading`) — omission renders localized
  `tableLoadFailed` (`'Could not load data'` in the built-in English catalog); a supplied string,
  including `''`, renders verbatim. Has no effect once the `error` slot is filled.
- `errorDescription: string = ''` (attribute `error-description`) — never localized, the same
  contract as `emptyDescription`. Has no effect once the `error` slot is filled.
- `announce: boolean = false` (reflected) — opts the table into announcing a failed-load state it
  already carries when it first mounts, through the same shared assertive region and the same
  heading text the later `error` transition announces, so the two paths cannot drift. Leave unset
  for a table that is part of the page a user is arriving on: the built-in error state renders in
  document order and repeating it is noise. Set it when the table is created in response to a user
  action — a reload that rejects mounts a fresh `error` table whose failure would otherwise never
  be spoken. Read once, on the first update: a later reconnection or adoption stages the same
  state again rather than replaying the announcement, and later `error` transitions announce
  either way. Deliberately not forwarded to the composed `[part='error']` `<lr-empty>`, whose own
  `announce` stays unset so the failure is spoken once, not twice. Remove any host
  `role="status"`/`role="alert"` hand-added before this property existed once it is set —
  otherwise the failure is announced a third time, through the native role as well.
- `emptyHeading?: string` (attribute `empty-heading`) — omission renders localized `noData` (`'No data'` in the built-in English catalog); a supplied string, including `''`, renders verbatim
- `emptyDescription: string = ''` (attribute `empty-description`)
- `noColumnsHeading?: string` (attribute `no-columns-heading`) — omission renders localized `noColumns` (`'No columns configured'` in the built-in English catalog); a supplied string,
  including `''`, renders verbatim
- `noColumnsDescription: string = ''` (attribute `no-columns-description`)
- `emptyCompact?: boolean` (attribute `empty-compact`) — overrides the built-in `[part='empty']`
  state's `compact` rendering. Tri-state: leave it `undefined` (the default) to keep each empty
  branch's own built-in default — the two shadow-root-level branches (no columns, no rows) render
  spacious, while the filtered-to-zero branch, which sits inside `[part='base']` alongside the filter
  field, renders compact. `empty-compact="false"` forces the spacious rendering everywhere, and is
  parsed as `false` rather than as mere attribute presence. Has no effect once the `empty` slot is
  filled
- `revealColumnsLabel?: string` (attribute `reveal-columns-label`) — the reveal button's label
  while `priority`-hidden columns are hidden; omission renders localized
  `showAllColumns` (`'Show all columns'` in the built-in English catalog), while a supplied string (including `''`) is verbatim
- `hideColumnsLabel?: string` (attribute `hide-columns-label`) — the same button's label once
  the columns have been revealed; omission renders localized `showFewerColumns` (`'Show fewer columns'` in the built-in English catalog), while a supplied string (including `''`) is verbatim
- `priorityColumnsVisible: boolean = false` (attribute `priority-columns-visible`, reflected) —
  forces responsive priority columns visible and is updated by the built-in reveal button.
  Priority-hidden columns hide their header, body, and footer cells together at the same measured
  overflow point in either direction; revealing columns restores all three bands.
- `storageKey?: string` (attribute `storage-key`) — when set, persists `priorityColumnsVisible` to
  `localStorage` (namespaced as `lr-table:${storageKey}`) and restores it on the next mount, without
  overwriting a `priorityColumnsVisible` the consumer declared on that same mount
  (`priority-columns-visible` present, or a `.priorityColumnsVisible=${…}` binding) — including a
  binding that pins it to `false`, its own default. Unset (the default) touches storage not at all.
  The same "explicit beats persisted" guarantee `lr-app-rail` gives each of its `persist`-selected
  fields and `lr-widget` gives `collapsed`; all three share one mechanism
- `priorityColumnsToggleAvailable: boolean` (readonly; computed, no attribute) — whether the
  reveal/hide control is currently offered at all, the public counterpart of the measurement
  `[part='reveal-columns-button']` itself renders from. True while at least one `priority` column is
  actually hidden at the current allocation, and it stays true once `priorityColumnsVisible` has
  revealed them (otherwise the control would remove itself the moment it was used). Always `false`
  with no `priority` column declared — the state the development-mode inert-configuration warning
  describes. Remeasured after every render and container resize, so read it after
  `await table.updateComplete`
- `heatTintScale?: { min?: number; max?: number }` (attribute: false) — overrides the auto-derived
  heat-tint domain (min/max of every `heatValue` result across every currently-rendered row —
  post-sort, pre-pagination, the same rows `footer(rows)` already sees). Unset (the default) computes
  the domain automatically from the data, spanning every `heatValue`-defining column together — a
  single shared scale across the whole grid, not one scale per column
- `rowTotal?: (row: T) => unknown` (attribute: false) — renders a trailing `<td>`
  (`[part='row-total-cell']`) on every body row holding this row's total. Same "consumer
  computes/renders, table only positions" contract as the existing per-column `footer(rows)` — does
  not assume addition, so a non-sum aggregate works identically. Omit for no trailing column at all
  (unchanged output)
- `grandTotal?: (rows: readonly T[]) => unknown` (attribute: false) — renders the bottom-right cell (row-total
  column × footer row). Only rendered when both `rowTotal` is set **and** at least one column defines
  `footer` — otherwise there is no footer row for it to occupy, and this renders nothing

**Methods:**

- `rowElement(rowKey)` — the rendered `<tr>` for one row key, or `null` when that row is not in the
  current render output (filtered out, paged away, never present)
- `cellElement(rowKey, columnKey)` — the rendered `<td>` at a row/column pair, on the same terms;
  `columnKey` is the column's own `key`
- `expandedContentElement(rowKey)` — the rendered `[part='expanded-cell']` holding that row's
  `expandedContent(row)` output, or `null` when the row is not currently rendered, is not expanded,
  or the table sets no `expandedContent`
- `editCell(rowKey, columnKey)` — opens the inline editor at that row/column pair, exactly as a
  double-click, `F2`, or `Enter` on the cell's own focus stop would (see `columns[].editTrigger`
  below) — the entry point for a consumer's own key binding or menu action. A no-op for an unknown
  row key, an unknown column key, or a column with no `editTrigger`. For an `editTrigger: 'always'`
  column (already open from first paint) it moves focus into that editor instead of opening
  anything.

The first three exist for code that has to reach content a `cell(row)`/`expandedContent(row)` callback
rendered into this component's shadow root — measuring it, scrolling it into view, or applying a
style `::part()` cannot express, since only pseudo-classes may follow a part selector. One method per
callback, and the split is not cosmetic: the expansion panel is a **sibling** `<tr part='expanded-row'>`
of the data row rather than a descendant of it, so `rowElement(rowKey)` cannot reach
`expandedContent` output at all — use `expandedContentElement(rowKey)` for that half. All three read
the DOM as it stands, so `await table.updateComplete` first and treat `null` as "not rendered right
now". The `data-row-key`, `data-col-key` and `data-expanded-row-key` attributes they resolve are
documented stable API: `data-col-key` is the column's own `key`, while `data-row-key` (on the data
row) and `data-expanded-row-key` (on the panel row) are a type-tagged encoding of the row key
(`string:a` vs `number:1`) that keeps a numeric key distinct from the string that stringifies the
same way. The panel deliberately does **not** repeat `data-row-key`, so a `[data-row-key]` query
still resolves exactly one element per row. Prefer these three methods over building a selector from
any of the attributes — a consumer-supplied key is not safe to interpolate into CSS unescaped.

**Events:** `lr-sort-request` (cancelable frozen readonly
`detail: { phase: 'request', sortKey, sortDir }`) precedes `lr-sort` (frozen readonly
`detail: { phase: 'commit', sortKey, sortDir }`) only when accepted. Client mode also updates its
sort properties; server mode leaves them controlled. Other events are `lr-row-click`
(`detail: { row }`), `lr-load-more` (fired on the "load more" button),
`lr-priority-columns-visibility-change` (frozen readonly `detail: { visible }`), and the expansion
pair `lr-row-expand-request` (**cancelable**, frozen readonly `detail: { row, rowKey, expanded }`,
emitted only while `expansionMode` is `'single'` or `'multiple'`; `preventDefault()` skips the
built-in `expandedRowKeys` write and suppresses the following toggle) and `lr-row-expand-toggle`
(frozen readonly `detail: { row, rowKey, expanded }`, where `expanded` is the state the activation
resolves to; under the default `expansionMode: 'none'` the table does not mutate `expandedRowKeys`,
while under a self-managed mode the write has already landed when it fires, and `'single'` fires it
once more — with `expanded: false`, immediately ahead of the accepted one — for the row it closed to
make room, unless that row is out of view), and
`lr-selection-change` (frozen readonly `detail: { rowKeys }`, not cancelable) when selection is
enabled — fired both from a row activation and from a `selectionMode` flip to `'single'` that coerces
an existing multi-row selection down to one key (skipped on the very first render, since an
already-inconsistent initial `selectionMode`/`selectedRowKeys` pairing is a starting state, not a
live transition), `lr-filter-change`
(frozen readonly `detail: { text }`), and `lr-page-change` (frozen readonly `detail: { page }`) from the
filter/pagination surfaces, and `lr-cell-edit` (`detail: { row, columnKey, value }`) for editable
columns, and `lr-column-resize` (`detail: { columnKey, width }`, `width` in CSS pixels) on every pointer or
keyboard resize step. **Only the commit is cancelable.** A pointer drag fires the event once per
pixel of movement as non-cancelable live feedback, then exactly once more — `cancelable: true` — for
the width committed at drag-end (and only when that width actually differs from the pre-drag one).
A keyboard step (Arrow/Shift+Arrow/Home/End) is already one discrete action, so it fires that single
cancelable commit directly, with no live-feedback stream. Calling `preventDefault()` on a cancelable
emission reverts the column to its pre-gesture width (or removes the override entirely if the column
had never been resized) — unless the listener also applied a width of its own during that same
synchronous dispatch, which stands rather than being rolled back over, so a listener may refuse the
proposed width and resolve the resize its own way in one step. Calling `preventDefault()` on a
mid-drag step does nothing, by design — a veto is a decision
about the final width, not about every pixel the pointer passes through.
The internal filter input's composed native `input`/`change` events are contained; only
`lr-filter-change` crosses the host boundary. Cell-editor `input`/`change` events are likewise
contained while an accepted edit publishes `lr-cell-edit`. Internal filter/cell-editor native
`focus` and `blur` are re-dispatched from the host as bubbling, composed events (the native ones
are neither). `lr-retry` — the built-in `[part='retry-button']` was activated, only rendered while
`error` is set. **Cancelable**: the default action clears `error`; calling `preventDefault()` leaves
it set, for a consumer that owns its own retry timing (e.g. it wants to keep the banner up until a
fresh load has actually started, or failed again immediately).

**Slots:** `empty` — replaces the built-in empty state on the two _data_-empty branches (no rows at
all, and filtered/paginated down to zero). Left unfilled, the built-in `[part='empty']` `<lr-empty>`
renders as this slot's fallback content. The no-columns branch is deliberately **not**
slot-replaceable: it reports a configuration problem (`noColumnsHeading`), not "this query returned
nothing", and one slot covering all three would collapse that distinction. Everything else comes
from `columns`/`rows`. `error` — replaces the built-in failed-load state, including its retry
button, while `error` is set. Left unfilled, the built-in `[part='error']` `<lr-empty>` renders as
this slot's fallback content.

**CSS parts:** `base`, `table`, `caption`, `head`, `header-cell`, `row`, `cell`, `more-button`, `sort-icon`
(each sort indicator), `sort-icon-active` (the active chevron, rotated per `sortDir`),
`sort-icon-inactive` (the muted bidirectional indicator under `sort-indicators="all"`), `reveal-columns-button`
(shown when priority columns are hidden or when a narrow allocation is currently force-visible),
`foot` (the `<tfoot>`, only rendered when at least one
column defines `footer`), `footer-row`, `footer-cell`, `row-total-cell` (each body row's trailing
`<td>` holding `rowTotal(row)`, rendered only when `rowTotal` is set — the corresponding footer-row
cell, holding `grandTotal`, is a `footer-cell` instead, matching every other footer cell),
`expand-toggle-cell`, `row-expand-toggle`,
`row-expand-icon`, `expanded-row`, `expanded-cell`, `filter-label`, `filter`, `filter-clear`
(clears the filter field, replacing the native search-cancel glyph the component resets; rendered
only while it has a value), `loading` (under
`loadingAppearance="spinner"` the visible block holding the spinner; under `"skeleton"` the
visually-hidden, `aria-hidden` announcement mirror, since the placeholder rows are the visible
affordance; the part has no live-region role in either appearance),
`skeleton` (each canonical `shape="rect"` `<lr-skeleton>` placeholder inside a skeleton-mode body cell — the placeholder rows
and cells reuse the ordinary `row`/`cell`/`row-total-cell` parts, which is exactly what keeps them
geometrically identical to real rows, so `skeleton` is the part to target for the placeholder's own
look: `::part(skeleton) { --lr-skeleton-h: 2em; }`), and
`pagination`, `cell-editor`, `group-row`, `group-cell`, and `resize-handle` (the focusable column
separator, with a finite explicit ARIA maximum even when no CSS `maxWidth` was supplied). The built-in empty state is addressable rather than fixed: `empty` is the `<lr-empty>`
host in all three empty states, and it re-exports that element's own inner parts as `empty-base`,
`empty-icon`, `empty-heading`, `empty-description` and `empty-actions`. Note that the no-columns and
no-rows states return the empty element as the shadow root's own root, with no `[part='base']`
wrapper around it — `::part(base)` does not apply in those two states, only in the filtered-to-zero
one — and that `empty` disappears entirely once the `empty` slot is filled. `error` — the built-in
`<lr-empty>` host rendered in the row body while `error` is set. Unlike `[part='empty']`'s no-rows
branches, its surrounding `<thead>`, filter, and pagination stay mounted rather than being replaced
along with it. It re-exports that element's own inner parts as `error-base`, `error-icon`,
`error-heading`, `error-description`, and `error-actions` (which wraps `retry-button`, the built-in
retry control). `error-row` — the single full-width `<tr>` replacing the row content while `error`
is set; `error-cell` — the `<td>` inside it, spanning every column, that holds the failed-load
content. Both exist only in the in-grid branch: when `columns` is empty there is no grid to keep
mounted, so the failed-load content renders standalone and neither part is present (`error` and its
re-exported inner parts still are).

- `scrollMode: 'self' | 'page' | 'auto' = 'self'` (attribute `scroll-mode`, reflected) — which element
  scrolls when the table overflows. `'self'` makes `[part="base"]` the scroll container, which is
  what pairs with `--lr-table-max-height` and makes the sticky header pin inside the table's own
  viewport. `'page'` hands scrolling back to the document. Needed because a scroll container clips
  **both** axes — CSS offers no way to scroll one and not the other — so an *uncapped* table that is
  still `overflow: auto` becomes a sticky containing block that never scrolls, and its header
  scrolls away with the page. With `'page'` the header's nearest scrollport is the page, so it pins
  there; the cost is that a table wider than its host overflows the page instead of scrolling
  inside itself. The opt-in `'auto'` mode resolves between those two behaviors from the rendered
  allocation: while content fits it uses page flow, and only while content actually overflows
  horizontally does `[part="base"]` become the contained scrollport. It re-evaluates when either
  the allocated width or the rendered table's intrinsic width changes, so the same table can flow
  with a desktop page and contain itself in a 320px panel. The default remains `'self'`. Named
  `scrollMode` rather than `scroll` because a `scroll` property would shadow `Element.prototype.scroll()`

**Themeable custom properties:** `--lr-table-cell-color` (default `inherit`),
`--lr-table-cell-link-color` (default `var(--lr-color-brand)`) and
`--lr-table-cell-link-hover-color` — an anchor returned from a column's `cell(row)` renders inside
the component's shadow root, where page CSS cannot reach it and `::part()` cannot select past the
first compound selector to reach it either, so without these it computes to the UA default link
blue; set `revert` for the UA default. `--lr-table-cell-padding` (default `var(--lr-space-s)`) sets
the padding of a header cell, a body cell, and the row-total cell; `--lr-table-cell-padding-compact`
(default `var(--lr-space-xs) var(--lr-space-s)`) is the same hook for the group-header cell and the
footer cell, which default to a tighter block/inline shorthand rather than sharing the first token
outright — two hooks instead of one preserve that distinction. `--lr-table-font-size` (default
`inherit`) sets the `<table>` element's font size; the rest of the font shorthand (family,
weight, etc.) keeps inheriting from the host regardless of this override. `--lr-table-max-height` (default `none`; controls the scrollable
body's `max-block-size`). `--lr-table-heat-tint-lo` (default `var(--lr-color-brand-quiet)`) and
`--lr-table-heat-tint-hi` (default `var(--lr-color-brand)`) — the `color-mix()` ramp endpoints
for heat-tint mode's per-cell background, consulted only on columns/rows that define `heatValue`;
`--lr-table-resize-min-width` (default `var(--lr-size-3rem)`) and
`--lr-table-resize-handle-opacity` (default `0.12`) control resizable-column behavior. The latter
remains the legacy shared opacity fallback; `--lr-table-resize-handle-hover-bg` (default
`var(--lr-color-brand)`), `--lr-table-resize-handle-hover-opacity` (defaulting to the legacy
opacity), `--lr-table-resize-handle-active-bg` (defaulting to the hover background), and
`--lr-table-resize-handle-active-opacity` (defaulting to twice the hover opacity) independently
retune the rendered interaction states. These heat-tint/resize hooks are not redeclared on the component host: set them on
`lr-table` or on a theme ancestor, and a table-level value wins through the normal cascade.
`--lr-table-row-selected-bg` (default `var(--lr-color-brand-quiet)`) — the background of a row whose
`aria-selected` is `true`, including that row's own `sticky` column cell. Like every state-scoped
custom property in this library it is an inline
`var()` fallback at its point of use and is **not** declared on `:host`, so it can be set on the
element _or on any ancestor_ and still reach the rule that reads it. It exists because Shadow Parts
forbids an attribute selector after `::part()` — `::part(row)[aria-selected='true']` is invalid CSS —
so the only prior lever for restyling the selected row was overriding the library-wide
`--lr-color-brand-quiet` token, which repaints everything else reading it.
`--lr-table-row-stripe-bg` (default `transparent`) — the background of alternating body rows,
including each row's own `sticky` column cell. The
component marks the alternating rows itself, so this works without an invalid `::part(row)` attribute
or structural-pseudo-class selector and does not affect group, expanded, hover, or selected rows. A
row's hover and pressed fills reach its `sticky` column cell the same way, through an internal
custom property rather than a themeable token, since neither state has a public hook today.
`--lr-table-header-sorted-bg` (default `var(--lr-color-surface)`) and `--lr-table-header-sorted-color` (default
`inherit`) restyle the **currently-sorted** column's header cell (`[aria-sort]` other than `none`),
including a `sticky` column's own header cell. The opaque surface default prevents body rows from
showing through the sticky header while it scrolls.
Same shape and rationale as `--lr-table-row-selected-bg`: inline `var()` fallbacks, not on `:host`,
because `::part(header-cell)[aria-sort]` is invalid CSS. The `sort-icon` part styles only the
indicator; these tokens style the header cell itself. Use `::part(sort-icon-inactive)` and
`::part(sort-icon-active)` to style the two indicator states without private selectors.
`--lr-table-sticky-offset` (default `0`) is measured and written inline per column by the component
so multiple `sticky` columns stack instead of overlapping; it is a read-out, not a knob you set.
`--lr-table-heat-t` is likewise component-written (each `[data-heat]` cell's position on the ramp).
`[part="base"]`, the table's own scroll container, also honors the opt-in theme-level
`--lr-theme-scrollbar-width`/`--lr-theme-scrollbar-gutter` hooks (defaults `auto`/`auto`, matching
its previous unconditional `scrollbar-width: auto`) — set either on `:root` or any ancestor for one
declaration to retheme every internal scroll container in the library, including
`lr-virtual-list`, `lr-scroller`, `lr-carousel`, `lr-code-block`, and `lr-code-editor`.

**Optional peer deps:** none.

```html
<lr-table
  id="t"
  sort-key="name"
  sort-dir="asc"
  accessible-label="Items"
></lr-table>
<script type="module">
  const t = document.getElementById("t");
  t.columns = [
    { key: "name", label: "Name", sortable: true, cell: (r) => r.name },
    // sortValue keeps the numeric column comparing as numbers, not as strings.
    {
      key: "value",
      label: "Value",
      align: "end",
      sortable: true,
      sortValue: (r) => r.value,
      cell: (r) => r.value,
    },
  ];
  t.rows = [
    { name: "Alpha", value: 1 },
    { name: "Beta", value: 2 },
  ];
  t.rowKey = (r) => r.name;
  t.addEventListener("lr-sort-request", (e) => {
    console.log("sort proposed", e.detail.sortKey, e.detail.sortDir);
    // Call e.preventDefault() here to veto the transaction.
  });
  t.addEventListener("lr-sort", (e) =>
    console.log("sort committed", e.detail.sortKey, e.detail.sortDir)
  );
  t.addEventListener("lr-row-click", (e) =>
    console.log("clicked", e.detail.row)
  );
</script>
```

**Known gotchas:**

- accepted sortable-header activation writes `sortKey`/`sortDir` only in client mode. Server mode
  keeps those properties controlled and reports the accepted proposal in `lr-sort`; veto
  `lr-sort-request` to suppress both state change and commit. The built-in transaction toggles only
  between two directions, so a tri-state header (asc → desc → unsorted) remains consumer-owned.
- `sortValue`/`cell` are read off the column object by identity. Mutating a column **in place**
  (`t.columns[0].sortValue = …`) neither re-renders nor re-sorts; assign a new `columns` array.
- `groupBy` + client sorting are **not** in conflict: the sort runs per group, not across the whole
  set, so group rows stay contiguous. The consequence is that the group order is normally yours to
  control — it follows first appearance in `rows`. The single exception is a sort on a column whose
  value is constant inside every group (the group column itself, a column functionally determined
  by the group key, or any column at all when every group holds one row): the within-group sort
  would be a provable no-op, so the groups are ordered by that constant value instead. That is what
  keeps `aria-sort` and the header chevron honest — otherwise clicking the group column would flip
  both while changing nothing. To force a group order in any other case, sort `rows` into it before
  assigning them (or set `sort-mode="server"` and own the whole ordering).
- both single and multiple row selection use `selectedRowKeys`; the component does not synthesize a
  checkbox column, so a bulk-select UI still belongs in `headerCell()`/`cell()` callbacks.
- `accessibleLabel?: string` (attribute `accessible-label`) — a typed accessible name for the
  `<table role="grid">`. Omitting it reads back `undefined`; a plain `aria-label` HTML attribute on
  the host is then forwarded instead (read via `this.getAttribute('aria-label')` at render time). An
  explicitly empty string is a real override — it renders `aria-label=""` rather than falling back to
  the host attribute. Consumer-supplied text, so neither is run through `this.localize()`.
- `caption: string = ''` — an optional visible `<caption>` (exposed as the `caption` CSS part). When
  no `accessibleLabel`/host `aria-label` is present the caption also names the grid via
  `aria-labelledby`.
- A grid with **none** of `accessibleLabel`, host `aria-label`, or `caption` logs a one-time
  `console.warn` on first render in development builds only — an unnamed grid is an accessibility
  defect that otherwise renders silently. Production and unknown/unbundled runtimes do not log it.
- `revealColumnsLabel`/`hideColumnsLabel` only ever reach the DOM on
  `[part='reveal-columns-button']`, which itself only renders while at least one column declares
  `priority`. Setting either label with no `priority` column is therefore always inert — it logs
  the same shape of one-time, development-only, production-silent `console.warn` as the missing
  accessible-name check above, rather than failing silently.
- Full roving-tabindex grid keyboard pattern (one `tabindex="0"` stop among header cells, one among
  body rows) — Left/Right/Home/End move within the header row, Up/Down/Home/End move within the
  body, Down from the header enters the body's roving stop and Up from the body's first row returns
  to the header, Enter/Space still only sort/activate — a genuine strength versus most siblings in
  this family. A `priority`-hidden header/cell is skipped when computing the visible header stops,
  so arrow-key navigation never strands the roving stop on a hidden column.
- a `cell()` template can render its own interactive content without it being swallowed by
  row/column activation. Delegated clicks and Enter/Space inspect the event's composed path for
  native buttons, links, inputs, selects, textareas, summaries, and media with controls;
  editable content; a non-negative `tabindex`; or role semantics (`button`, `checkbox`, `combobox`,
  `listbox`, `menu`, `menuitem`, `option`, `radio`, `separator`, `slider`, `spinbutton`, `switch`,
  `tab`, or `textbox`). Open-shadow custom controls expose those semantics through the composed path
  and therefore keep their own action. A passive custom element — including a formatter or
  display-only badge — remains part of the row activation surface instead of creating a dead zone
  merely because its tag contains a hyphen. An opaque closed-shadow control can explicitly opt out
  of row activation by adding `data-table-interactive` to its visible host.
- `layout="fixed"` (and any `'auto'` that resolves to fixed) carries two consequences of the CSS
  fixed algorithm. With no declared widths the **first** row — the header row included — determines
  every column's width, so revealing a `priority`-hidden column via
  `[part='reveal-columns-button']` re-measures and changes _all_ of them, not just the revealed one.
  And `columns[].minWidth`/`maxWidth` are silently ignored by `table-layout: fixed`; declare `width`
  instead when a specific column needs a specific size.
- skeleton mode keeps geometry stable only when the browser isn't sizing columns from cell content.
  Under the default `table-layout: auto`, placeholder cells have no intrinsic width, so the columns
  re-measure when real content arrives — exactly as they do between any two different data sets. For
  pixel-identical widths across the load, declare `columns[].width` or set `layout="fixed"`.
  Initial declarative loading stays silent; every later transition into either loading appearance
  appends the localized loading text to the document's shared light-DOM polite sink, including
  repeated cycles. `[part="base"]` exposes `aria-busy`, `[part="loading"]` is an `aria-hidden`
  mirror rather than a live region, and every placeholder opts out of `<lr-skeleton>`'s own
  announcement, so a skeleton table never announces once per placeholder row.
- `columns[].cellTitle` returning an empty string **or** `undefined` omits the `title` attribute
  entirely rather than rendering `title=""` — an empty `title` would suppress an ancestor element's
  own tooltip. The attribute is also suppressed while that cell is in inline-edit mode, so the
  tooltip can't shadow the editor. Accessibility caveat: some screen readers announce a `<td title>`
  as the cell's accessible _name_, replacing the cell's content rather than supplementing it (the
  same caveat `lr-stat`'s `exactValue` carries). Use it for a longer form of what the cell already
  shows, never for information that exists nowhere else.
- `editTrigger: 'always'` deliberately does not re-assert a `'text'`/`'number'` cell's source value
  once the user has typed into it. That is the native dirty-value-flag behavior the attribute
  binding buys, and it is the point: a background `rows` refresh cannot silently overwrite an
  in-progress edit. If you need the
  opposite — an authoritative external value that always wins — do not use `'always'`; re-key the
  row (`rowKey`) so the editor is recreated rather than updated, or use `editTrigger: 'double-click'` and let
  the short-lived double-click editor's property binding re-assert. Also note the two things
  `'always'` intentionally does _not_ do: it never sets the roving `tabindex` (its editors are
  ordinary tab stops, so Tab order in that column interleaves with the grid's two roving stops,
  the same way the row-expand toggle's already does), and it never cancels Escape.
- `editType: 'select'` renders a native `<select>`, populated from `columns[].editOptions`
  (`{ value: string; label: string }[]`, one `<option>` per entry in order); a `'select'` column
  with no `editOptions` renders an empty, valueless `<select>` rather than throwing. Unlike the
  `'text'`/`'number'` editors, `<select>`/`<option>` carry no native dirty-value flag, so the
  protection described above for a persistent `'always'` editor does not extend to a `'select'`
  one — a background `rows` refresh re-applies the selection to a persistent select editor even
  after the user has picked a different, uncommitted option. The double-click flavor is unaffected
  by this distinction either way, since it is always short-lived.

---

## `lr-pagination`

Controlled page navigation for server-side or client-side data sets: a numbered page list with
elided runs, previous/next and optional first/last buttons, an opt-in localized item-range summary,
a compact layout that swaps the list for a validated numeric page jump, and a polite announcement
after the host applies a requested page. The component owns no data fetching and never mutates
`page`.

**Indeterminate mode (`total="-1"`):** for a server API that never returns a total — limit/offset and
cursor/keyset APIs typically don't — set `total="-1"` and use `hasNext` to report whether one more
page exists. The component then renders previous/next plus a page-number field only: no numbered
page list, no item-range summary, and no `/ totalPages` readout, regardless of `format`,
`withSummary`, or `withEdges`. Previous is disabled at page 1 exactly as in the known-total path;
next is disabled once `hasNext` is `false`. Events, focus management, and the applied-page
announcement all use the same contract as known-total pagination — `lr-before-page-change`/
`lr-page-change`/`lr-activate` fire the same way, and focus still follows the applied page — except
the announcement text has no total-pages figure (`"Page {page}"` instead of `"Page {page} of
{totalPages}"`). Any negative `total` other than exactly `-1` still renders the ordinary empty
state.

**9.0.0 migration:** remove reads of `pageCount` and use the required mirrored `totalPages` getter.
There is no alias or compatibility shim; keeping both names made one derived total look like two
independent concepts.

**8.0.0 migration — these changes are breaking:**

- `total-items` is now `total` (property `totalItems` → `total`). The old attribute no longer binds
  to anything: a pager left on `total-items` keeps `total` at its `0` default and silently renders
  the empty state with every control disabled.
- `hide-summary` is now `with-summary`, which **inverts the default**. The summary used to render
  unless you opted out; it is now hidden unless you opt in. Drop `hide-summary` wherever it appears,
  and add `with-summary` to every pager that was relying on the old show-by-default behavior.
- `pageSize` now defaults to `10` instead of `20`, matching the mirrored pagination contract. Keep
  `page-size="20"` explicitly wherever the old twenty-item window is part of the data request.
- `lr-page-change.detail` now includes `pageSize` as well as `page`, and the new cancelable
  `lr-before-page-change` fires first. Existing readers of `detail.page` keep working; code that
  asserted the exact one-key detail object must accept `{ page, pageSize }`.

**Properties and getters:**

- `page: number = 1` (reflected) — the currently applied page. Runtime values are presented within
  the valid `1..totalPages` range, but the public property itself remains controlled and is not
  rewritten by the component
- `pageSize: number = 10` (attribute `page-size`) — items per page; finite values are truncated to
  a non-negative integer for the derived calculations, and zero produces no pages
- `total: number = 0` (attribute `total`) — total item count; finite values are truncated
  to a non-negative integer for display and page-count calculations, except for the exact sentinel
  `-1`, which enters indeterminate mode (see below) instead of clamping to the ordinary empty state.
  Any other negative value — including one arrived at by a miscalculation — still clamps to `0` and
  renders the empty state, unchanged
- `totalPages: number` (readonly getter) — `ceil(total / pageSize)` after the normalization above,
  or `0` when either normalized input is zero (always `0` in indeterminate mode too, since there is
  no total to derive a page count from)
- `hasNext: boolean = true` (attribute `has-next`, reflected) — whether at least one more page
  exists past the current one. Consulted only in indeterminate mode; previous availability is always
  derivable from `page` alone
- `disabled: boolean = false` (reflected)
- `loading: boolean = false` (reflected) — disables all controls and sets `aria-busy="true"` on the
  internal navigation landmark
- `withSummary: boolean = false` (attribute `with-summary`, reflected) — renders the built-in range
  summary while retaining the controls. Opt-in since 8.0.0, when the old `hide-summary` attribute
  (shown-by-default) was renamed to `with-summary` (hidden-by-default) — the **8.0.0 migration**
  bullet above has the full inverted-default detail
- `size: '2xs'|'xs'|'s'|'m'|'l'|'xl' = 'm'` (reflected) — control footprint, on the library's shared
  six-step ladder: `--lr-pagination-control-size` and `--lr-pagination-font-size` read the same
  `--lr-form-control-height`/`--lr-form-control-font-size` knobs `lr-button`/`lr-input`/`lr-select`
  sit on, so a pager in a toolbar row lines up with its neighbours at every tier.
  `'small'`/`'medium'`/`'large'` are accepted as exact synonyms of `'s'`/`'m'`/`'l'` — no attribute
  rewrite when migrating from an upstream that spells them that way
- `format: 'standard'|'compact' = 'standard'` (reflected) — `standard` renders the numbered page
  list; `compact` replaces it with the single page-jump input and a `/ totalPages` readout, for a
  toolbar or card footer. Previous/next and the `with-edges` buttons render in both. Foreign
  runtime values normalize to `standard`
- `siblingCount: number = 2` (attribute `sibling-count`) — pages shown either side of the current
  page in the numbered list. Read as a non-negative integer clamped to `0..25`; non-finite input
  falls back to `2`
- `boundaryCount: number = 1` (attribute `boundary-count`) — pages always pinned at the start and
  the end of the numbered list. Same normalization, fallback `1`
- `withEdges: boolean = false` (attribute `with-edges`, reflected) — adds first-page and last-page
  buttons outside previous/next, each drawn with a doubled chevron
- `withoutNav: boolean = false` (attribute `without-nav`, reflected) — omits previous/next while
  retaining numbered pages and any `with-edges` first/last controls
- `hideSinglePage: boolean = false` (attribute `hide-single-page`, reflected) — renders nothing when
  the normalized data set has zero or one page
- `hrefTemplate: string | ((page: number) => string) = ''` (attribute `href-template`) — renders
  every navigation target outside the compact field as an `<a>` instead of a `<button>`, so the
  pager works before hydration and for crawlers. Standard layout includes numbered pages and
  interactive ellipses; compact layout retains link-mode previous/next and optional first/last
  controls around its controlled page field. A string uses `{page}` as the placeholder
  (`/products?page={page}`); a function receives the page number and returns the URL and can only be
  assigned from JavaScript
- `appearance: 'accent'|'filled'|'outlined'|'filled-outlined'|'plain' = 'outlined'` (reflected) —
  the resting fill and border of the first/previous/next/last buttons and the numbered pages (not the
  compact page-jump input), applied through the two custom properties below. The applied page stays a
  solid brand chip in all five, so the appearance never decides whether the current page is
  identifiable
- `itemLabel: string = ''` (attribute `item-label`) — custom item noun used in the summary; empty
  selects the localized singular `item` or plural `items` key
- `accessibleLabel: string | null = null` (attribute `aria-label`) — host accessible-name override
  forwarded to the internal `<nav>` landmark; takes precedence over `label`
- `label?: string` — explicit fallback accessible name for the internal `<nav>` landmark, applied
  when no host `aria-label` is set; omitting it reads back `undefined` and localizes the
  `paginationLabel` message, while an explicit empty string renders no visible/accessible label
- `pageLabel?: string` (attribute `page-label`) — optional accessible-name override for the page-jump input
- `previousLabel?: string` (attribute `previous-label`), `nextLabel?: string`
  (attribute `next-label`) — optional accessible-name overrides for the icon-only directional buttons
- `firstLabel?: string` (attribute `first-label`), `lastLabel?: string`
  (attribute `last-label`) —
  optional accessible-name overrides for the icon-only edge buttons rendered by
  `with-edges`

Omitting any of those five control-label properties resolves the matching locale message. Any
supplied string is an explicit per-instance override and renders verbatim, including the built-in
English wording under a non-English `.strings` catalog and an empty string.

**Events:** `lr-before-page-change` (frozen readonly `detail: { page: number, pageSize: number }`, bubbles and
composes, cancelable) fires first for any valid, different requested page. Preventing it suppresses
the request and restores the compact field to the controlled page. If accepted,
`lr-page-change` follows with the same frozen detail (bubbles and composes, non-cancelable), from a numbered
page, interactive ellipsis, previous/next, first/last, or the compact page-jump input. The host
applies `event.detail.page` back to `page` after routing, fetching, or any other policy decision.
When that requested value is applied, focus follows the new `[part="page-current"]` control; the
compact layout returns focus to its page field instead. This keeps keyboard orientation intact even
when a next/previous, edge, or ellipsis control is replaced by the newly rendered page window. If
the application applies the controlled page asynchronously and the user has moved focus outside
the pagination component in the meantime, it leaves that newer focus destination alone.
`lr-activate` (`detail: { value: number }`, bubbles and composes, non-cancelable) fires on **every**
accepted page request, whether or not the page actually moved; `value` is the requested page number.
`lr-before-page-change` remains the veto point, and a vetoed request emits no activation at all, so
`lr-activate` only ever reports a request the component accepted. Use it for the re-request of the
current page that `lr-page-change` deliberately stays silent for — "load that page again" is a real
intent, and it is otherwise unobservable, because the page buttons and the jump input live in this
shadow root, so a retargeted `click` names no page and pressing Enter on the jump field produces no
click at all. When a request _does_ move the page, `lr-before-page-change` and `lr-page-change` are
emitted first. Link-mode anchors navigate without emitting it.
`focus` and `blur` are re-dispatched as exactly one bubbling, composed native `FocusEvent` from
whichever internal control the user reached — a page button or link, previous/next, first/last, or
the page input. The shadow-origin event is stopped, and the host event preserves its native focus
payload, including `relatedTarget`.

**Methods:** `focus(options?)`, `blur()` and `click()` resolve the primary control for the active
format at call time: the applied `[part="page-current"]` button/link in `standard`, or the
`[part="page-input"]` page-jump input in `compact`. `click()` additionally does nothing while the
controls are disabled.

**Slots:** `first-icon`, `previous-icon`, `next-icon`, and `last-icon` replace the corresponding
directional glyph while leaving its localized accessible name on the owning control.

**CSS parts:** `base` and `pagination` are aliases on the same navigation wrapper; `summary`,
`controls`, `pages`, `button`, `page`, `page-current`, `ellipsis`,
`first-button`, `first-icon`, `previous-button`, `previous-icon`, `page-field`, `label`, `page-input`,
`page-count`, `next-button`, `next-icon`, `last-button`, `last-icon`, `live-region`.

`pages` is the `role="list"` wrapper, `page` one numbered control inside it (a `<button>`, or an
`<a>` under `href-template`), and `ellipsis` an accessible interactive control that jumps several
pages into its skipped run. `button` is shared by every page, ellipsis, and navigation control;
`label` aliases the compact `page-field` wrapper. The applied page's control carries a second part token, so
`::part(page-current)` selects it and `::part(page)` still selects every page including the current
one — the state lives in the part name because `::part(page)[aria-current='page']` is invalid CSS
and would silently never match. `first-button`/`first-icon` and `last-button`/`last-icon` exist only
while `with-edges` is set — and never in indeterminate mode, along with `pages`, `summary`, and
`page-count`, none of which have a total to render against (see indeterminate mode above).

`live-region` is a visually hidden, `aria-hidden` **mirror** of the applied-page announcement — a
styling and inspection surface, with no live-region role of its own. The announcement itself goes
to the library's shared **light-DOM** polite region, appended to the consumer's `<body>` and marked
`data-lr-live-region="polite"`, because a live region inside a shadow root is not reliably
announced (JAWS with Firefox ignores one outright). Assert against that document-level region
rather than `::part(live-region)`.

**CSS custom states:** `disabled` matches when the public `disabled` property is true. The state
does not match for the separate `loading` or empty-data conditions, even though those conditions
also make the rendered controls inert.

**Themeable custom properties:** `--lr-pagination-control-size` and
`--lr-pagination-font-size` (both default from `size`), `--lr-pagination-control-bg` (default
`var(--lr-color-surface)`) and `--lr-pagination-control-border-color` (default
`var(--lr-color-border)`) — the resting fill and border shared by the first/previous/next/last
buttons, interactive ellipses, and numbered pages, which is what `appearance` re-points: `filled` → `var(--lr-color-surface-raised)` + `transparent`,
`filled-outlined` → `var(--lr-color-surface-raised)` + `var(--lr-color-border)`, `plain` →
`transparent` + `transparent`, `accent` → `var(--lr-color-brand-quiet)` +
`var(--lr-color-brand)`; set either property yourself to theme past the five presets —
`--lr-pagination-control-radius` (default `var(--lr-radius)`) — border radius of the navigation
buttons, the numbered pages and the page input — `--lr-pagination-control-padding` (default
`var(--lr-space-xs)`) — inner padding of those same controls, deliberately uniform across every
`size` tier because the control's outer footprint is already fixed by
`--lr-pagination-control-size`, so this only adjusts the icon/digit inset. Layout spacing is split
across `--lr-pagination-base-gap` (default `var(--lr-space-m)`) between summary and controls,
`--lr-pagination-controls-gap` (default `var(--lr-space-xs)`) inside the navigation group, and
`--lr-pagination-pages-gap` (default `var(--lr-space-xs)`) between numbered pages; each remains
active in standard, compact, and 320px container layouts —
`--lr-pagination-invalid-border` (default `var(--lr-color-danger)`) — border color of
`[part="page-input"]` while the typed page is out of range (`aria-invalid="true"`); a state hook
declared as an inline `var()` fallback, since `::part(page-input)[aria-invalid='true']` is invalid
CSS. `--lr-pagination-control-color` independently controls the resting foreground. The applied
page has `--lr-pagination-current-bg`, `--lr-pagination-current-border-color`, and
`--lr-pagination-current-color`. Ordinary controls use `--lr-pagination-hover-bg`,
`--lr-pagination-hover-border-color`, `--lr-pagination-active-bg`, and
`--lr-pagination-active-border-color`; the applied page has independent
`--lr-pagination-current-hover-bg`, `--lr-pagination-current-hover-border-color`,
`--lr-pagination-current-active-bg`, and `--lr-pagination-current-active-border-color` hooks. Each
defaults to the exact shared brand/quiet-brand/active-mix treatment used previously. These state
hooks and the resting background/border hooks are consumed through inline fallbacks, so they work
when inherited from an ancestor as well as when set directly on one pager. Shared spacing,
disabled-opacity, and focus-ring tokens remain available as usual.

**Optional peer deps:** none.

```html
<lr-pagination
  total="237"
  page-size="20"
  with-summary
  with-edges
></lr-pagination>
<script>
  const pagination = document.querySelector("lr-pagination");
  pagination.addEventListener("lr-page-change", async (event) => {
    await loadPage(event.detail.page, event.detail.pageSize);
    pagination.page = event.detail.page;
  });
</script>

<!-- Link mode: real anchors, so the pager is crawlable and works before hydration. -->
<lr-pagination
  total="237"
  page-size="20"
  page="3"
  with-edges
  href-template="/products?page={page}"
></lr-pagination>
```

A function template builds the URL itself, which is where any dynamic segment gets encoded:

```js
const pagination = document.querySelector("lr-pagination");
const query = new URLSearchParams(location.search).get("q") ?? "";
pagination.hrefTemplate = (page) =>
  `/products?${new URLSearchParams({ q: query, page: String(page) })}`;
```

**Known gotchas:**

- user activation only emits an intent. Until the host applies a new `page`, the numeric input
  returns to the currently controlled value; assigning the page triggers the localized
  announcement in the shared light-DOM polite sink
- cancel `lr-before-page-change` for a policy veto; preventing `lr-page-change` has no effect because
  that second event is the accepted, non-cancelable controlled intent
- the jump input accepts only whole pages in `1..totalPages`; empty, fractional, and out-of-range
  drafts expose `aria-invalid="true"` and emit nothing
- zero items, zero page size, `disabled`, and `loading` all disable the navigation controls. The
  empty summary is still rendered via the localized `paginationEmptySummary` message
  (`'{total} {itemLabel}'`, producing `0 items` in the default locale) only when `with-summary` is set
- below a 20rem container allocation the summary and controls stack; the breakpoint responds to the
  component's own inline size, not the viewport. The control group and the page list wrap onto
  further rows at any width rather than overflowing. Previous/next and first/last icons all mirror
  under RTL
- link mode moves navigation outside the compact page field out of your handler. Numbered pages and
  ellipses exist only in standard layout; previous/next and first/last exist in both layouts. Each
  is a plain anchor with no click handler: activating it navigates and emits neither pagination
  event. The compact field continues to emit the controlled request events
- `href-template` is interpolated, not encoded. `{page}` is replaced with `String(page)` — always a
  plain integer, never the localized digits shown in the label — and the rest of the template is
  placed in the `href` verbatim: it is neither URL-encoded nor otherwise escaped. The only check
  applied is a scheme allowlist on the resolved URL (`http:`, `https:`, `blob:`, `mailto:`, and
  relative URLs); a `javascript:`, `data:` or unparseable result fails closed to a `<button>` for
  that page instead of being rendered. Treat the template as trusted application input and encode
  any dynamic segment yourself before it reaches the template — a function template is the
  straightforward place to do that
- the current page never gets an `href`, but while enabled it carries `tabindex="0"` so the applied
  location remains a keyboard stop. While `disabled` or `loading`, every anchor loses both `href`
  and the current page's explicit tabindex and carries `aria-disabled="true"`, leaving the inert
  pager with no tab stops
- an `hrefTemplate` function runs only for active targets inside `1..totalPages`. Current, spent,
  disabled, loading, and empty-state controls stay rendered as configured anchors without `href`,
  but do not call the function with a destination the user cannot activate
- `format="compact"` removes only the numbered list. `href-template` still applies to active
  previous/next and optional first/last targets around the page-jump input; spent boundary controls
  remain anchors without `href` and expose `aria-disabled="true"`
- the numbered list keeps a constant slot count as the reader pages through, so the control does not
  jitter: `siblingCount`/`boundaryCount` fix the budget, every page renders when the page count fits
  inside it, and otherwise a side that turns out to need no gap hands its slot back as one more page
  number. A gap is a named jump control, not decorative text; repeated activation advances through
  a large skipped run. Both counts are clamped to `25` and the render-every-page budget is capped at 101 slots, so
  however large you set them the list never renders more than 103 slots
- `appearance` does not reach the compact page-jump input — `[part="page-input"]` always draws with
  the shared surface and border tokens. Style `::part(page-input)` directly when a non-default
  appearance needs it to match

---

## `lr-gauge`

Dependency-free SVG radial, full-circle ring, or linear meter (no charting library).

Removing `label` omits the visible SVG label in radial, linear, and ring shapes and restores the
localized gauge name unless `aria-label` is authored. The property retains removal `null`;
explicitly empty labels remain empty and later labels render normally.

**Properties:**

- `value: number = 0`
- `min: number = 0`
- `max: number = 100`
- `shape: GaugeShape = 'radial'`, where `GaugeShape = 'radial'|'ring'|'linear'` (reflected —
  `radial` is a 270° sweep; `ring` is a
  full circle that begins at 12 o'clock)
- `size?: LyraSize` (reflected, unset by default) — density tier on the library's one size ladder:
  `'2xs'|'xs'|'s'|'m'|'l'|'xl'`, or the Web Awesome / Shoelace spellings `'small'|'medium'|'large'`,
  which are accepted as authored rather than rewritten to the short form. A tier pins the host font
  size, and because the whole gauge box is expressed in `em` the frame, the stroke geometry and both
  SVG captions scale together — `8em` square for `radial`/`ring`, `12em` by `1.5em` for `linear`,
  each multiplied by that tier's font size. Leaving it unset keeps the inherited ambient text size
  and the exact geometry the gauge rendered before the ladder reached it, so existing markup is
  untouched. An unsupported value normalizes to the omitted state and removes the attribute.
- `label: string = ''`
- `valueText?: string` (attribute `value-text` — overrides both the visible text and the host's
  `aria-valuetext`; an empty string is treated the same as unset and falls back to the numeric
  `value` while removing `aria-valuetext`)
- `showValue: boolean = true` (attribute `show-value`, not reflected) — whether the decorative
  `part="value"` caption renders at all; `show-value="false"` omits it the same way an empty
  `label` already omits `part="label"`. `aria-valuenow`/`aria-valuetext` and the host's accessible
  name are unaffected either way, since the caption itself is always `aria-hidden`. Mirrors
  `<lr-progress-bar>`'s/`<lr-progress-ring>`'s own `showValue` name and meaning; the default here
  is `true` (a gauge's whole purpose is showing the reading it announces) where theirs is `false`.
- `variant: LyraProgressVariant = 'brand'` (reflected) — the same shared semantic-tone vocabulary
  `<lr-progress-bar>` uses (`'neutral'|'brand'|'success'|'warning'|'danger'`). The fallback color
  whenever `thresholds` is empty or matches nothing.
- `thresholds: readonly LyraGaugeThreshold[] = []` (attribute: false) — `LyraGaugeThreshold {
  readonly at: number; readonly variant: LyraProgressVariant }`. Value-to-variant color mapping:
  the LAST entry, after sorting by `at` regardless of authored order, whose `at` is `<=` the
  current `value` wins; an entry whose `at` is not a finite number never matches. The same rule
  serves a higher-is-worse domain like CPU load (`[{at: 0, variant: 'success'}, {at: 70, variant:
  'warning'}, {at: 90, variant: 'danger'}]`) and a higher-is-better one like battery charge
  (`[{at: 0, variant: 'danger'}, {at: 20, variant: 'warning'}, {at: 50, variant: 'success'}]`) —
  only the authored pairs differ.

**Events:** none.

**Slots:** none.

**CSS parts:** `base` (the `<svg>`), `track`, `fill`, `value` (rendered only while `showValue` is
true), `label` (rendered only while `label` is non-empty)

**Themeable custom properties:** `--lr-gauge-fill` (fill stroke; overrides `variant`/`thresholds`
entirely and falls back to the effective variant's shared semantic token —
`--lr-color-brand` by default).

**Optional peer deps:** none.

```html
<lr-gauge value="72" min="0" max="100" label="CPU"></lr-gauge>
<lr-gauge
  shape="ring"
  value="84"
  label="Coverage"
  style="--lr-gauge-fill: var(--lr-color-success)"
></lr-gauge>
<lr-gauge shape="linear" value="0.4" max="1" value-text="72°F"></lr-gauge>
<!-- compact dashboard meter: a slim, captionless, thresholded row -->
<lr-gauge
  shape="linear"
  size="xs"
  show-value="false"
  aria-label="Spend"
  value="84"
  max="100"
></lr-gauge>
<!-- automatic threshold coloring: same rule, opposite direction -->
<lr-gauge id="cpu" value="82" label="CPU"></lr-gauge>
<script>
  cpu.thresholds = [
    { at: 0, variant: 'success' },
    { at: 70, variant: 'warning' },
    { at: 90, variant: 'danger' },
  ];
</script>
<lr-gauge id="battery" value="15" label="Battery"></lr-gauge>
<script>
  battery.thresholds = [
    { at: 0, variant: 'danger' },
    { at: 20, variant: 'warning' },
    { at: 50, variant: 'success' },
  ];
</script>
```

**9.0 migration:** rename geometry `type`/`GaugeType` to `shape`/`GaugeShape`, and formatted-value
`valueLabel` to the declarative `valueText`/`value-text`. There are no legacy aliases.

**Known gotchas:**

- SVG text cannot wrap. Long caller-supplied `label`/`valueText` strings are visibly abbreviated
  with an ellipsis instead of being compressed into unreadable hairline glyphs; a nested SVG
  `<title>` supplies the full hover tooltip, while the host accessible label and `aria-valuetext`
  retain the complete text.
- The host defaults to `role="meter"` for a finite, non-degenerate range and `role="img"`
  otherwise. An authored host role remains authoritative across value updates; removing it restores
  the generated default.
- setting `valueText` (e.g. `"72°F"`) also sets `aria-valuetext` on the host (in addition to
  changing the visible SVG text), so a screen reader announces your formatted string instead of the
  raw `aria-valuenow` number; the SVG `<text part="value">`/`<text part="label">` elements are
  `aria-hidden="true"` so they're no longer separately exposed inside the same `role="meter"` host.
- `thresholds` recolors the fill from `value` alone — no reactive application-state wiring needed
  for the common success/warning/danger case. It never rewrites the `variant` property or its
  reflected attribute; the resolved color is tracked separately so a component reading back
  `variant` always sees the value it set. `--lr-gauge-fill` still overrides both `variant` and
  `thresholds` unconditionally, for a color outside the shared semantic-tone vocabulary.
- no documented component-specific sizing custom property. The host box is fixed em values
  (`8em` radial/ring, `12em`/`1.5em` linear) against the host font size, so `size` is the supported
  way to step it; for a dimension off the ladder, set plain CSS `width`/`height` (or `font-size`)
  on the element instead. The value/label captions are `em`-sized against that same host font-size,
  so they shrink right along with the frame at a smaller tier or a smaller host `font-size` —
  combine a small tier (or a small host `font-size`) with `show-value="false"` for a slim,
  thresholded dashboard meter, matching `<lr-progress-bar size="xs">`'s footprint but with
  `role="meter"` and one `thresholds` array instead of a hand-written ratio-to-variant mapping.
- Divide-by-zero guarded, and radial/linear share one component via the `shape`
  attribute.
- non-finite `value` text remains blank unless `valueText` supplies a truthful fallback; that
  fallback is included in the generated `role="img"` accessible name. Non-finite `min`/`max` use finite default domain
  bounds; no `NaN`/`Infinity` value leaks into the SVG geometry or ARIA attributes, and a finite
  value is clamped into the resolved domain before being announced.

---

## `lr-funnel`

Dependency-free conversion funnel (no charting library): an ordered set of stages, each drawn as a
bar whose length is that stage's share of the **first** stage, read top-to-bottom as progressive
drop-off. It sits beside `lr-gauge` and `lr-heatmap` as an analytics primitive rather than a general
chart type.

When a positive finite stage value divided by a positive finite baseline overflows to `Infinity`,
the main or comparison data fill clamps to 100%. Nonfinite input normalization, nonpositive-baseline
behavior, percentage and drop-off text, and overflow border styling keep their existing rules.

It is deliberately not a sorted bar chart: it normalizes to the first stage rather than to the data
maximum, draws no value axis, and reads as stage-to-stage retention rather than category comparison.
Reach for `lr-bar-chart`/`lr-lite-chart` when you actually want a value axis and category comparison.

The whole chart is plain HTML — stage names, absolute values, shares and drop-off percentages are
real text inside an `<ol>`, so there is no sighted-only drawing needing a separate transcript. The
list carries the accessible name; a host `aria-label` overrides `label`.

**Properties:**

- `stages: readonly LyraFunnelStage[] = []` (property only; every share is measured against
  `stages[0]`)
- `comparison: readonly LyraFunnelStage[] = []` (property only — an optional baseline/peer cohort
  drawn behind each bar as a dashed outline, normalized to **its own** first stage so a cohort's
  funnel *shape* stays comparable against a baseline whose absolute volumes are not)
- `comparisonLabel: string = ''` (attribute `comparison-label`; falls back to a localized generic
  label)
- `label: string = ''` (accessible name for the stage list)
- `dropoff: boolean = true` (reflected; `dropoff="false"` in markup really does turn it off —
  the property uses the explicit `false`-parsing converter, not attribute presence)
- `sharePrecision: number = 0` (attribute `share-precision`; fraction digits for every share and
  drop-off percentage, clamped to `0`–`20`)

```ts
interface LyraFunnelStage {
  readonly label: string;
  readonly value: number;
  readonly color?: string; // CSS color; unparseable values fall back to --lr-funnel-bar-color
}
```

**Events:** none.

**Slots:** none.

**CSS parts:** `base`, `stages` (the `<ol>`), `stage`, `dropoff`, `stage-header`, `stage-label`,
`stage-value`, `stage-share`, `comparison-value`, `track`, `bar`, `bar-overflow` (a second token on
`bar` when the stage exceeds the first stage), `comparison-bar`, `empty`

**Themeable custom properties:** `--lr-funnel-bar-color` (default `var(--lr-color-brand)`),
`--lr-funnel-comparison-color` (default `var(--lr-color-border-strong)`), `--lr-funnel-track-color`
(default `var(--lr-color-surface-raised)`), `--lr-funnel-bar-size` (track thickness, default
`var(--lr-size-1-5rem)`).

**Optional peer deps:** none.

```html
<script type="module">
  import '@aceshooting/lyra-ui/components/data/funnel/funnel.js';
</script>

<lr-funnel id="signup" label="Self-serve signup" share-precision="1"></lr-funnel>

<script type="module">
  const funnel = document.querySelector('#signup');
  funnel.stages = [
    { label: 'Visited pricing', value: 12480 },
    { label: 'Started trial', value: 4310 },
    { label: 'Converted to paid', value: 512 },
  ];
  // Normalized to ITS OWN first stage, so a 380-visitor account still compares against a
  // 12,480-visitor peer group.
  funnel.comparison = [
    { label: 'Visited pricing', value: 380 },
    { label: 'Started trial', value: 141 },
    { label: 'Converted to paid', value: 12 },
  ];
  funnel.comparisonLabel = 'Acme Corp';
</script>
```

**Known gotchas:**

- **Shares are of the first stage, not of the previous one.** `stage-share` answers "how much of the
  top of the funnel is left here?"; the separate `dropoff` row answers "what changed since the
  previous stage?". Both are rendered because the percentage is usually the interesting number and
  the absolute count is the credibility check.
- **A zero or negative first stage cannot define a share.** Every `stage-share` is omitted, every bar
  is zero-length, and only the absolute values render. Nothing is silently divided by zero and no
  `NaN` reaches the geometry.
- **A stage larger than its predecessor is legal** (funnel re-entry). Its share is reported
  truthfully above 100% in text, while the bar clamps to the track and gains the `bar-overflow` part
  token so you can style it. Drop-off for that stage reads as an increase.
- **Drop-off is omitted, not zeroed, when the previous stage is non-positive** — a change relative to
  zero is undefined.
- **A comparison series of a different length pairs by index.** Extra comparison entries are ignored;
  stages past its end simply get no comparison bar. A comparison series whose own first value is
  zero or negative draws nothing.
- **Malformed stage entries are omitted independently.** Non-record entries and records without a
  string `label` cannot suppress valid neighbors in either series. This is a render-only boundary:
  the public `stages` and `comparison` arrays retain caller identity and are never rewritten.
- **Non-finite `value`s are treated as `0`** rather than blanking the stage, so one bad row cannot
  take the chart with it.
- Values, shares and drop-off percentages all format through the component's effective locale
  (`locale` attribute, or an inherited one) — never a hardcoded `en`.
- Bars grow from the inline-start edge and every dimension is a logical property, so `dir="rtl"`
  needs no extra work. The component never sets its own `dir`.
- Layout responds to the **container** (`container-type: inline-size` on `base`), not the viewport:
  below roughly `18rem` of allocated width the stage name moves to its own line so the value and
  share stay together. Bar motion is a token-driven transition that stops under
  `prefers-reduced-motion`.
- No events, no interaction model, no zoom/pan. If you need a clickable funnel, wrap the element and
  handle clicks yourself.

## `lr-word-cloud`

Dependency-free SVG word/tag cloud. First-party invention (no Web Awesome equivalent). Lays words
out via an outward Archimedean-spiral search — heaviest word placed first, each word spiraling from
the center until it clears every word already placed. Unlike sibling `lr-sparkline`/`lr-heatmap`
(one `role="img"` glyph standing in for an aggregate value), the individual words here _are_ the
meaningful interactive content — but with up to `MAX_WORDS` (150) of them, making every single one
its own tab stop would be a poor keyboard experience. Instead, like `lr-heatmap`'s cells, the whole
`[part="svg"]` is **one tab stop with roving arrow-key focus**: `ArrowRight`/`ArrowDown` move the
focus cursor to the next word in **declaration order** (not weight/placement order),
`ArrowLeft`/`ArrowUp` to the previous, `Home`/`End` to the first/last, and `Enter`/`Space` fires
`lr-word-activate` for the currently-focused word. Tab focus silently establishes the first word,
so immediate Enter/Space always works without requiring a preparatory arrow key. A
`[part="focus-ring"]` `<rect>` is drawn around the focused word, and a
shared light-DOM polite sink announces `"${text}, ${weight}"` on every focus move. Mount is silent,
and repeated edge movements append repeated announcements even when their text is identical.
`[part="live-region"]` mirrors the latest text for styling/inspection but is `aria-hidden` and has
no live-region role of its own. Pointer input resolves the nearest word from the adequately-sized
SVG surface; the potentially tiny text glyphs are not independent hit targets.

Pinned opposite-sign finite endpoints such as `[-1e308, 1e308]` produce bounded finite scale
fractions and SVG geometry, including with reversed endpoints or square-root scaling. Word weights
remain nonnegative; placement budgets, font-size limits, and the omitted-word policy are unchanged.

**Properties:**

- `words: readonly WordCloudWord[] = []` (attribute: false) — readonly `{ text: string, weight:
number, color?: string, group?: string }` snapshots; malformed/hostile records are skipped while
  later valid records survive. `weight` is normalized once to a finite nonnegative value used by
  font sizing, announcements, and `lr-word-activate` detail. A valid CSS `color` overrides the
  palette for that word (invalid values,
  declaration-breaking input, and `url()` fall back to the palette), and `group` shares one palette
  color across every word with the same `group` value. The component scans at most 10,000 input
  records, bounds each string to 256 characters and all retained word strings to 16,384 characters,
  marking shortened strings with an ellipsis and disclosing omitted input through `[part="limit"]`.
  The returned sequence and records are frozen; reassign `words` after changes.
- `minFontSize: number = 12` (attribute `min-font-size`) — px, applied to the lowest-weight word;
  a finite value is clamped to `[1, 512]` (so `0`/a negative value floors at `1px`, and an oversized
  value caps at `512px`); a non-finite value (`NaN`/`Infinity`) falls back to the default `12px`
  rather than to the `1px` floor
- `maxFontSize: number = 48` (attribute `max-font-size`) — px, applied to the highest-weight word;
  clamped/defaulted the same way (a non-finite value falls back to `48px`, not to `1px`); a
  resulting reversed pair (`minFontSize` greater than `maxFontSize`) is swapped rather than
  inverting the weight-to-size mapping
- `domain?: [number, number]` (attribute: false) — pins the weight-to-font-size input domain so
  separate clouds can share one scale instead of each deriving it from its own lightest and
  heaviest words. Reversed endpoints are normalized; a degenerate or non-finite pair falls back to
  the data-derived range
- `scale: 'linear'|'sqrt' = 'linear'` — `sqrt` compresses the weight→font-size mapping so one heavy
  word doesn't dwarf the rest, matching `lr-heatmap`'s `scale` property
- `wordRotation: 'none'|'mixed' = 'none'` (attribute `word-rotation`, reflected) — `mixed` lets
  ~25% of words render rotated 90° for denser packing
- `palette?: readonly string[]` (attribute: false) — clone-owned custom categorical colors (at
  most 64), cycled by word index (or by
  `group`); invalid CSS colors, declaration-breaking input, and `url()` entries are skipped, and an
  all-invalid palette defaults to the `--lr-word-cloud-color-1..8` tokens. The returned sequence is
  frozen; reassign `palette` after changes
- `legend: readonly WordCloudLegendItem[] = []` (attribute: false) — clone-owned, frozen named
  readonly `{ label, color }` entries for explaining explicit `words[].color`/group color
  overrides; when omitted, the component derives entries from grouped and explicitly colored
  words. Explicit legends retain at most 100 entries and 8,192 aggregate characters; malformed
  records are skipped, overlong strings end in an ellipsis, invalid colors render transparent, and
  `[part="legend-limit"]` truthfully exposes the localized rendered/received count. The returned
  sequence and records are frozen; reassign `legend` after changes.
- `showLegend: boolean = false` (attribute `show-legend`, reflected) — renders the supplied or
  derived legend below the cloud; the color key is an accessible list and does not change word
  activation or palette selection

**Methods:** `refreshTheme(): void` — forces a relayout so the `--lr-font` custom property is
re-read from computed style (font-family affects the canvas text measurement layout depends on).
The component's theme watcher calls it automatically when inherited theme typography changes; the
method remains available for a host theme system that needs an explicit synchronous refresh.

**Events:** `lr-word-activate` (frozen readonly `detail: { text, weight, group }`; fires from the
single SVG pointer surface, or Enter/Space on the current word)

**Slots:** none.

**CSS parts:** `base`, `svg`, `word` (each `<text>`), `focus-ring` (the rect around the roving-focus
cursor's word), `live-region` (visually-hidden, `aria-hidden` mirror of the latest announcement;
the actual announcement uses the shared light-DOM polite sink),
`legend`/`legend-item`/`legend-swatch`/`legend-label` (the optional static color key), and `empty`
(the no-data placeholder), `limit` (localized rendered/received word count), and `legend-limit`
(localized rendered/received explicit-legend count)

**Themeable custom properties:** `--lr-word-cloud-color-1`, `--lr-word-cloud-color-2`,
`--lr-word-cloud-color-3`, `--lr-word-cloud-color-4`, `--lr-word-cloud-color-5`,
`--lr-word-cloud-color-6`, `--lr-word-cloud-color-7`, `--lr-word-cloud-color-8` (the default
categorical palette, cycled by word index or `group`; a data-driven literal exception like
`lr-heatmap`'s scale-ramp endpoints — exposed as retheme-able custom properties instead of
hardcoded). They inherit from theme ancestors, while a value set directly on the word cloud wins
through the normal cascade), plus shared tokens (`--lr-font`,
`--lr-focus-ring-*`, `--lr-transition-fast`, `--lr-color-text-quiet`).

**Optional peer deps:** none.

```html
<lr-word-cloud id="cloud" style="height: 20rem"></lr-word-cloud>
<script type="module">
  document.getElementById("cloud").words = [
    { text: "JavaScript", weight: 90 },
    { text: "TypeScript", weight: 75 },
    { text: "Lit", weight: 60, group: "framework" },
  ];
  document
    .getElementById("cloud")
    .addEventListener("lr-word-activate", (e) => console.log(e.detail));
</script>
```

The focusable SVG is the single semantic owner: `role="application"` plus an accessible name. An
authored host `aria-label` is forwarded to that SVG and wins by attribute presence; when it is
absent, the SVG uses an auto-computed localized name such as `"Word cloud of 12 words"` / `"Word
cloud of 1 word"`, counting only words actually rendered. An authored host `role` remains on the
host and does not replace the SVG's application role. When records are omitted, the SVG references
the visible localized `[part="limit"]` rendered/received summary.

**Known gotchas:**

- capped at 150 words (`MAX_WORDS` in `word-cloud-layout.ts`, mirroring `lr-sparkline`'s
  `MAX_POINTS` input-sample guard) — a one-pass bounded top-K scan retains the **heaviest** 150 and
  counts the rest without cloning/sorting/spreading the full input. A pathological input can exhaust the
  spiral search's radius bound and get dropped the same way; blank/whitespace-only `text` is dropped
  during boundary normalization. Omitted diagnostics retain at most 32 records, while a separate
  complete count drives one deduplicated `console.warn` and the rendered disclosure — nothing throws.
- each word's spiral search tests at most 4,096 candidate positions. Together with the 150-word and
  512px font-size caps, this bounds placement work even for dense or adversarial layouts; a word
  that exhausts the search budget is reported through the same skipped-word path.
- text width is measured via a detached `<canvas>` 2D context (`ctx.measureText`) using the live
  `--lr-font-weight-semibold` and `--lr-font` token values. A consumer-only `::part(word)` font
  override can still desynchronize measurement from the painted glyph.
- rotation (`word-rotation="mixed"`) is genuinely random per layout (`Math.random()`, not seeded), so
  which words render rotated changes on every re-layout (any `words`/`minFontSize`/`maxFontSize`/
  `scale`/`wordRotation` change) — don't rely on rotation being stable across renders.
- only one word is ever in the page's tab sequence at a time (the roving cursor on `[part="svg"]`) —
  there's no way to Tab directly to the Nth word; arrow-key/Home/End your way there, or click it.

---

## `lr-heatmap`

A Canvas-rendered heatmap with a DPR-aware, resize-aware redraw loop. One discriminated `data`
property selects `{ kind: "matrix", rowLabels, colLabels, values }` (the default) or
`{ kind: "calendar", days, ...calendarOptions }` (a GitHub-style weekday × week grid). Every cell
is independently addressable despite being
canvas-drawn (no per-cell DOM node by default): a `pointermove` hit-test over the canvas shows `[part="tooltip"]`
with that cell's label + value; the canvas is a named `role="application"`, `tabindex="0"` control
with arrow-key roving focus (a stroked ring is redrawn over the focused cell on every draw, and the
cell text is appended to the document's shared light-DOM polite sink); and a click, or Enter/Space
on the focused cell, fires `lr-cell-click`. The first render is silent, repeated identical focus
movements remain separate announcements, and `[part="live-region"]` is only an `aria-hidden` mirror.
Both modes deliberately retain physical LTR grid geometry under `dir="rtl"`: matrix column 0 and
calendar week 0 remain at the physical left, so ArrowLeft and ArrowRight retain their physical
previous/next movement instead of swapping for RTL.
Full canvas redraws pause while the host is outside the viewport. Data, locale, theme, resize, and
DPR invalidations remain pending and coalesce into one redraw when the heatmap intersects again;
environments without `IntersectionObserver` retain eager drawing.

Focus-only updates repaint a bounded neighborhood around the old and new cells, restoring all
intersected neighboring fills and overlays while preserving the focus-ring geometry. Calendar axis
pixels intersected by the repaint are restored too.

Changing `domain` or `midpoint` without replacing matrix data preserves absent and nullish cells as
no data in paint, accessible text, callbacks, and cell events. Missing values still use `-1` in
default unsigned mode and `NaN` in signed mode; supplied negative signed values remain data.

Invalid authored ramp colors retain the default endpoint fallback. The public `resolveRgb()` helper
likewise preserves its supplied fallback bytes. These authoring diagnostics are once-per-color
development warnings and remain silent in production; the separate missing-canvas runtime warning is
unchanged.

Set `accessibleCells: true` (`accessible-cells`) to opt into a semantic grid backed by a bounded
window of native buttons. It retains the complete `aria-rowcount`/`aria-colcount` and arrow-key
navigation model without mounting one node per cell. Buttons use localized `aria-label`s, explicit
`aria-selected="true"|"false"` from the controlled `selectedCell`, and roving tabindex; the grid
continues to emit `lr-cell-click` and leaves selection state consumer-controlled.
When matrix/calendar data refreshes while one of those buttons owns focus, the semantic matrix
coordinate or calendar date remains the sole roving stop. If it disappears, focus clamps to the
nearest surviving interactive cell, or to the stable heatmap base when none remain; an unfocused
refresh never steals external focus.

Changing `accessibleCells` also preserves owned focus across the rendering-mode replacement:
turning the overlay off moves a focused cell button to the canvas application control; turning it on
moves a focused canvas to the matching remembered cell, the first interactive cell, or the stable
base when no cell exists. A newer external focus destination is never reclaimed.

**Properties:**

- `data: HeatmapData = { kind: 'matrix', rowLabels: [], colLabels: [], values: [] }` (attribute:
  false), where `HeatmapData` is the readonly discriminated union:
  - `HeatmapMatrixData { kind: 'matrix'; rowLabels: readonly string[]; colLabels: readonly
string[]; values: readonly (readonly number[])[] }`
  - `HeatmapCalendarData { kind: 'calendar'; days: readonly CalendarDay[]; firstDayOfWeek?:
number; columnX?: (index:number)=>number; rowY?: (weekday:number)=>number;
weekdayLabelWidth?: number|'auto'; weekdayLabelText?: (jsWeekday:number)=>string|undefined; monthLabelText?:
(jsMonth:number,year:number)=>string|undefined }`
    Matrix `-1` or non-finite values are no-data. Calendar identity is ISO date; invalid dates are
    omitted and duplicates use one deterministic **first-valid-wins** entry before count, scale,
    paint, selection, focus and event paths.
    Collections are snapshotted into a bounded canonical projection; reassign `data` after changing
    caller-owned input.
    `weekdayLabelWidth` controls the calendar weekday-label gutter: a nonnegative CSS-pixel number
    pins its width, while `'auto'` measures the widest rendered weekday label without shrinking
    below the built-in `28px` gutter or growing beyond 40% of the host. Unset preserves the original
    `28px` geometry; malformed values are ignored.
- `cellSize: number = 22` (attribute `cell-size` — default `22` in matrix mode, `11` in calendar
  mode when left unset; explicitly setting it now governs both modes' per-cell size alike, and it's
  ignored in either mode when `fitToWidth` is set)
- `cellGapX: number = 1` / `cellGapY: number = 1` (attributes `cell-gap-x` / `cell-gap-y`) —
  matrix-only trailing horizontal/vertical gaps in CSS pixels, subtracted from the square
  `cellSize` pitch. Negative values clamp to zero, non-finite values use `1`, and oversized gaps
  leave at least one painted pixel. Custom geometry with `accessibleCells` grows the minimum pitch
  and caps gaps to preserve the `--lr-icon-button-size` target floor. Calendar spacing is unchanged.
- `cellRadius: number = 0` (attribute `cell-radius`) — matrix-only painted corner radius in CSS
  pixels, clamped from zero to half the smaller painted side; non-finite values use zero. Custom
  cell fills, focus/selection/annotation rings, semantic overlays, and PNG canvas output share the
  same bounds. Custom gaps are excluded from canvas pointer hits; rounded cells retain rectangular
  interaction bounds. The default one-pixel separator retains its existing hit area.
- `colLabelInterval: number = 1` (attribute `col-label-interval`) — paint every Nth matrix column
  label starting at column zero, including frozen labels and rotated label measurement. Truncated
  to an integer of at least one; non-finite values use `1`. Every original `data.colLabels` value
  remains available to tooltips, keyboard announcements, semantic cells, and `cellText`.
- `fitToWidth: boolean = false` (attribute `fit-to-width` — derives `cellSize` from the host's
  measured `clientWidth` on every draw/resize instead of the fixed `cell-size`, so the grid actually
  fills the available width; now applies to calendar mode as well as matrix mode — see gotchas for
  the default, non-`fit-to-width` behavior)
- `rowLabelWidth?: number | 'auto'` (attribute `row-label-width`, reflected) — width, in CSS px, of
  the **matrix** row-label gutter, or `'auto'` to measure the widest label and size the gutter to
  fit (never below the built-in `60`, never above 40% of the host width, so one long label cannot
  squeeze out the cells it describes). Unset keeps the built-in `60`, so no existing chart reflows.
  Independently of this, a label too wide for the resolved gutter is truncated with an ellipsis
  rather than clipped mid-glyph — clipping read as a rendering fault, truncation reads as "there is
  more here". `cellText` still carries the full label to the tooltip and the keyboard announcement.
  A malformed value is ignored rather than collapsing the gutter. Calendar mode is unaffected; it
  has its own fixed weekday gutter
- `colLabelHeight?: number | 'auto'` (attribute `col-label-height`, not reflected, `'auto'` new in
  11.0.0) — height, in CSS px, of the matrix column-label band, or `'auto'` to measure the labels
  and size the band to fit them. Under a non-zero `colLabelRotation` the measurement projects each
  label's width through the rotation, which is what makes a rotated axis usable without hand-tuning
  a magic number. Never below the built-in `20`, and bounded above by a sanity ceiling so a
  pathological label cannot produce an absurd canvas. Note this deliberately does **not** use
  `rowLabelWidth`'s "40% of the host" rule: the row gutter steals width from the cells and so must
  be bounded relative to them, whereas the canvas simply grows taller for this band and the cells
  keep their size. Unset keeps the built-in `20`, so no existing chart reflows. A malformed value is
  ignored
- `colLabelRotation?: number` (attribute `col-label-rotation`, new in 11.0.0) — rotation, in
  degrees, applied to matrix column labels. Unset or `0` paints them horizontally exactly as before.
  In a dense matrix the per-column width is far narrower than a typical label, so horizontal labels
  collide with their neighbours; `45` or `90` is the standard remedy. Each label rotates about an
  anchor at its own column's centre with the label's *end* at that anchor, so it leans back over the
  columns to its left and the last column's label cannot overflow the canvas. Values outside
  `[0, 90]` clamp into that range and non-finite values normalize to `0`. Pair with
  `colLabelHeight="auto"` to have the band size itself to the rotated extent. **Not mirrored under
  `dir="rtl"`** — both grid modes deliberately retain physical LTR geometry, so leaning one axis'
  labels the other way would be incoherent
- `stickyLabels: 'none' | 'rows' | 'cols' | 'both' = 'none'` (attribute `sticky-labels`, reflected)
  — freezes a **matrix** label band against the grid's own scrolling. `'rows'` pins the row-label
  gutter so it survives horizontal scrolling, `'cols'` pins the column-label band so it survives
  vertical scrolling, `'both'` pins both. Labels and cells otherwise share one bitmap, so neither
  band can be `position: sticky` on its own and a tall matrix scrolls its column header out of
  view; the only workaround was a light-DOM mirror row that had to hardcode the gutter width and
  cell size, which made it mutually exclusive with `row-label-width="auto"`. A frozen band is
  repainted into its own layer in the same draw pass, from the same resolved `matrixGeometry` the
  cells were painted with, so it tracks a `row-label-width`/`col-label-height` `"auto"`
  re-resolution, a resize, and a DPR change without drifting a pixel. Freezing needs something to
  scroll, so the frozen modes wrap the grid in a `[part="grid"]` scrollport: it is bounded inline by
  the host's own allocation — a matrix wider than a 320px host scrolls inside the component instead
  of overflowing it — and unbounded in block until you set `--lr-heatmap-grid-max-block-size`, which
  a frozen column band needs in order to have vertical scrolling to stay behind. The bands are
  `aria-hidden` duplicates of pixels the canvas already painted, so the accessible representation is
  unchanged, and the `accessibleCells` overlay moves inside the scrollport so the cell buttons
  scroll with the canvas they cover. The grid keeps this component's physical LTR geometry under
  `dir="rtl"`, so the frozen gutter stays on the same physical side as the labels the canvas paints.
  Matrix mode only, like `matrixGeometry`: the property is read in calendar mode but has no effect
  there, since a calendar's axes are a different geometry (fixed weekday gutter, month band, and the
  optional `columnX`/`rowY` overrides). Unset (`'none'`, the default) renders exactly what it always
  did — one canvas, no scrollport, no extra elements — and an unsupported value normalizes to it.
  The union is re-exported from the package root as `LyraHeatmapStickyLabels`, so a typed consumer
  can annotate a variable or a framework prop with it. Everything positioned in canvas coordinates
  moves into the scrollport with the cells: `[part="tooltip"]` renders inside it, so it stays on
  the cell it describes through a scroll instead of drifting by the scroll offset, and because
  `overflow: auto` clips whatever leaves the scrollport, the tooltip is kept inside the visible
  window too — clamped along the inline axis and flipped to below its cell when a frozen band
  leaves no room above it. Arrow-key navigation scrolls the focused cell into that window, clear of
  the frozen bands, which the frozen modes need in their own right: the canvas is the roving tab
  stop, its focus ring is painted into the bitmap rather than carried by a focusable element the
  browser would scroll to, and it calls `preventDefault()` on the arrows
- `maxCellSize?: number` (attribute `max-cell-size`) — ceiling, in CSS px, on the cell size
  `fitToWidth` derives from the host width, in **both** modes. Exists because `fitToWidth` divides
  the _whole_ host width across the grid, so a 5-week calendar or a 3-column matrix in a wide pane
  produces enormous blocks; capping them keeps a cell a cell
- `minCellSize?: number` (attribute `min-cell-size`) — the mirror floor, in CSS px, so a year-long
  calendar in a narrow pane keeps legible, hit-testable cells and overflows its host instead of
  collapsing to hairlines. It can only _raise_ the built-in `4`px floor, never lower it: a value
  below `4` normalizes to `4`. When both clamps are set and `maxCellSize < minCellSize`, the ceiling
  wins. For both: a non-finite value, or an empty attribute, means unset rather than `0`, and unset
  (the default) reproduces the unclamped fit-to-width behavior exactly
- `valueLabel?: string` (attribute `value-label`) — absence uses the localized default. Every
  supplied string is literal, including `"value"` and `""`; unset the property/attribute to resume
  localization.
- `withoutLegend: boolean = false` (attribute `without-legend`, reflected) — hides the colour
  legend, under the same name and the same polarity `lr-chart` has always used rather than a third
  spelling for one idea. The whole row leaves the DOM — the gradient bar or `legendStops` swatches,
  the `legend-lo`/`legend-hi` endpoint labels, the `valueLabel` caption, the labelled `annotations`
  entries and the `legend` slot go with it — so it contributes no layout box and assigns no slotted
  content, rather than being painted and then hidden. The legend's own preparation stops with it:
  `--lr-heatmap-color-steps-gradient`, which this component writes onto the host for the legend bar
  and for nothing else, is not written while the legend is hidden, and is removed again if it had
  been. Cells, tooltips, keyboard interaction, selection and the generated accessible summary are
  unaffected — the summary already names the value label independently of the legend.
- `scale: 'linear' | 'sqrt' = 'linear'` — governs both modes: in matrix mode, `'sqrt'` compresses the
  color ramp via `sqrtStep()` instead of mapping linearly; in calendar mode, the default `'linear'`
  still buckets by quartile (`quartileBucket()`, unchanged), while `'sqrt'` instead compresses via the
  same `sqrtStep()` magnitude compression as matrix mode, so one heavy day doesn't wash out the rest
- `domain?: [number, number]` (attribute: false) — pins the color ramp's input domain instead of
  deriving it from the data's own extremes, so two heatmaps of comparable data can share a scale
  rather than each normalizing to its own min/max. A reversed pair is normalized; a degenerate or
  non-finite one falls back to the derived range
- `midpoint?: number` — anchors a diverging ramp's neutral color on this value rather than at the
  middle of the domain, scaling the two halves independently (`lo`→0, `midpoint`→0.5, `hi`→1). A
  midpoint outside the resolved domain degrades to plain normalization rather than distorting the
  ramp
- **Signed data.** Setting either `domain` or `midpoint` opts the component into signed data, where
  only a **non-finite** value is no-data. With neither set (the default), a negative value is
  no-data — matching the long-documented `-1` sentinel, since a matrix of counts has no meaningful
  negative. Declaring a domain or midpoint is what disambiguates "a real negative" from "the
  sentinel", so signed datasets render their negative half instead of dropping it. In signed mode a
  structurally absent matrix cell reads as `NaN` so it stays no-data while a real `-1` beside it
  renders on the ramp; in default mode an absent cell still resolves to `-1`, keeping `valueAt()`
  and the `lr-cell-click` payload unchanged. `scale="sqrt"` rejects negatives in both modes — a
  square root of a negative has no meaning
- `bucketCount: number = 5` (attribute `bucket-count` — calendar mode only; non-finite values fall
  back to 5, while finite values are floored and clamped to 2–256 before the color-ramp allocation)
- `annotations: readonly HeatmapAnnotation[] = []` (attribute: false) — `HeatmapAnnotation { row?: number;
col?: number; date?: string; label?: string }`: matrix mode matches by `row`/`col`, calendar mode
  by `date` (whichever pair matches the active `mode`; the other fields are ignored). Draws a
  stroked ring over the matching cell; an annotation with a `label` also gets its own
  `[part="legend-annotation"]` entry in the legend. The collection is clone-owned, bounded, and
  frozen; reassign a new array after changes.
- `selectedCell: HeatmapSelectedCell | null = null` (attribute: false) — `HeatmapSelectedCell {
row?: number; col?: number; date?: string }`, matched the same way as `annotations`. Draws a
  persistent ring (independent of keyboard focus) over the matching cell, appends a "Selected: ..."
  description to the host's own `aria-label`, and adds localized selected wording to the keyboard
  announcement when the focused cell is the selection. Purely a controlled property — mirrors
  `<lr-lite-chart>`'s `selectedIndices`, this component never mutates it itself. Unset (the default,
  `null`) reproduces today's exact output.
- `multiple: boolean = false` — opts into controlled multi-cell selection through `selectedCells`.
  The existing `selectedCell` is ignored while enabled and resumes when disabled. Single-cell
  behavior is unchanged when omitted.
- `selectedCells: readonly HeatmapSelectedCell[] = []` (attribute: false) — clone-owned selection
  input, inspected up to `MAX_HEATMAP_CELLS` (10,000) entries. Duplicates, non-integer/out-of-grid
  coordinates and non-interactive cells are ignored. Matrix records use `{ row, col }`; calendar
  records use `{ date }`, including interactive calendar gaps. The component never assigns this
  property in response to user input. It draws selected rings and, with `accessibleCells`, exposes
  per-cell `aria-selected` plus grid `aria-multiselectable="true"`. The localized accessible summary
  reports the selected count through `heatmapSelectedCount`.

  `lr-selection-change` is a non-cancelable proposal: frozen `HeatmapSelectionChangeDetail {
  selectedCells: readonly Readonly<HeatmapSelectedCell>[]; source: HeatmapSelectionSource }`, with
  source `'pointer' | 'keyboard' | 'row' | 'column'`. Assign the event's array back to `selectedCells`
  to accept it; property assignments are silent. Output is deduplicated in row/column order. Click
  or Enter/Space toggles one cell and retains `lr-cell-click`. Pointer dragging paints or erases
  according to the starting cell, previews transient selection, and proposes once on release;
  pointer cancellation, Escape, disconnect, data/mode changes discard the gesture. A drag does
  not emit a cell click. Shift+arrows extends/contracts a rectangle from the anchor while retaining
  unrelated pre-range selection. Directions remain physical under RTL, matching the canvas.

  `toggleRowSelection(row: number): void` and `toggleColumnSelection(col: number): void` propose
  whole-axis toggles for application-owned controls: remove an entirely selected axis, otherwise
  add its interactive cells. Shift+Space and Ctrl/Meta+Space invoke those actions for the focused
  row/column. Calendar rows are weekday rows 0–6 and columns are zero-based weeks. Invalid indices
  and calls outside `multiple` mode are no-ops. For a narrow day/hour matrix, use `accessibleCells`
  and `stickyLabels="both"` to retain usable targets within the component's own scrollport.

  ```js
  import '@aceshooting/lyra-ui/components/lr-heatmap.js';
  const heatmap = document.querySelector('lr-heatmap');
  heatmap.multiple = true;
  heatmap.accessibleCells = true;
  heatmap.addEventListener('lr-selection-change', event => {
    heatmap.selectedCells = event.detail.selectedCells;
    // Derive filter state from the accepted row/column coordinates.
  });
  ```
- `accessibleCells: boolean = false` (attribute `accessible-cells`) — renders `[part="cells"]` with
  at most 400 `[part="cell"]` native buttons around the active cell. The semantic grid exposes the
  full row/column counts, buttons expose localized `aria-label`s and explicit `aria-selected`, and
  roving arrow navigation still reaches every canonical cell. The canvas remains the visual and
  pointer surface but is hidden from the accessibility tree. Controlled refresh focus follows the
  preservation/clamping behavior above.
- `cellText?: (pos: MatrixCellPos | CalendarCellPos, value: number) => string` (attribute: false) —
  formats the per-cell hover tooltip and keyboard announcement text; receives the cell
  position (`MatrixCellPos { row, col }` in matrix mode, `CalendarCellPos { week, weekday, date }` in
  calendar mode) and its value. `CalendarCellPos.date` is a **required** ISO `yyyy-mm-dd` string,
  present for every grid position — including a sparse gap position with no matching entry in `days`
  at all, which still sits on a real calendar day (that case simply reports the `-1` "no data" value
  alongside it). It lets a callback key off the date without re-deriving the grid's own
  anchor-week arithmetic; `MatrixCellPos` is unchanged, and so is `lr-cell-click`'s detail.
  Unset (the default) falls back to localized matrix row/column/value or calendar date/value
  templates. The default English catalog renders "Row X, Col Y: value" (matrix) / "Jan 15: value"
  — short month + day, **not** a weekday abbreviation (calendar). Matrix row/column placeholders,
  no-data wording, template order, calendar wording/date formatting, and numeric values all follow
  `locale` plus `registerLyraLocale()`/`.strings`; use `cellText` for application-specific wording.
- `cellInteractive?: (pos: MatrixCellPos | CalendarCellPos, value: number) => boolean` (attribute:
  false) — opts individual cells out of the interaction model; receives the cell position and its
  value, return `false` to make that cell present-but-non-interactive (no hover tooltip, click, or
  keyboard roving-focus stop) without losing the layout/color-ramp machinery. Unset (the default)
  keeps every cell interactive, unchanged.
- `data.columnX?: (index: number) => number` (calendar branch only) — overrides the
  internal week-column x-coordinate formula (`CAL_PAD_LEFT + week * (CAL_CELL + CAL_GAP)`) used
  consistently across drawing, hit-testing, the focus ring, and month-label positioning, so a
  consumer can pixel-align this calendar's week columns with a sibling `<lr-lite-chart>`'s bars
  (see that component's own `barX`) by supplying the same coordinate function to both. Unset (the
  default) is the original formula, unchanged.
- `data.rowY?: (weekday: number) => number` (calendar branch only) — the vertical
  analogue of `columnX`: overrides the internal weekday-row y-coordinate formula (`CAL_LABEL_H +
weekday * (cellSize + CAL_GAP)`), consulted consistently by drawing, hit-testing, and the focus
  ring (also consulted at `weekday = 7` to size the canvas height, mirroring `columnX` at
  `week = weekCount`). Unset (the default) is the original formula, unchanged. Ignored in matrix
  mode.
- `cellColor?: (pos: MatrixCellPos | CalendarCellPos, value: number) => string | undefined`
  (attribute: false) — overrides a cell's computed ramp/no-data color entirely for an exact value;
  return a CSS color string to force that cell to it, or `undefined` to fall back to the normal ramp
  math unchanged. Lets a consumer designate a value as categorically outside the ramp (e.g. a real
  zero-count day rendered as a neutral hairline, distinct from both "no data" and the ramp's own
  lightest step) without a synthetic ramp color, which can't safely reserve an exact value on a
  skewed dataset. Unset (the default) reproduces the exact ramp/no-data behavior for every cell.
- `data.weekdayLabelText?: (jsWeekday: number) => string | undefined` (calendar branch only) —
  overrides the weekday-axis label text; receives the real JS weekday index (`0` Sunday ..
  `6` Saturday) for a row that would otherwise render a label and, when it returns a string, uses it
  instead of the built-in `Intl.DateTimeFormat`-derived short weekday name. Unset (the default)
  reproduces today's exact locale-derived output.
- `data.monthLabelText?: (jsMonth: number, year: number) => string | undefined` (calendar branch
  only) — the month-axis analogue of `weekdayLabelText`: receives the real JS month
  index (`0` January .. `11` December) and full year for a month boundary that would otherwise
  render a label, and, when it returns a string, uses it instead of the built-in
  `Intl.DateTimeFormat`-derived short month name. Unset (the default) reproduces today's exact
  locale-derived output. Lets month labels track the same locale signal (e.g. an app's own i18n
  store) as `weekdayLabelText` and the component's other localizable strings, instead of always
  following the browser/OS-language default.
- `colorSteps?: readonly string[]` (attribute: false) — a clone-owned, bounded, frozen discrete array (≥2 entries) of CSS colors used as
  exact ramp steps instead of linearly interpolating between `--lr-heatmap-scale-lo`/`-hi`;
  governs both `mode`s and both `scale` values, discretizing whichever scale would otherwise
  interpolate continuously into `colorSteps.length` buckets instead. Unset (the default, or fewer
  than 2 entries) keeps today's 2-endpoint interpolation exactly. Invalid colors use the canvas
  fallback color and prevent the custom legend gradient from being assigned.
- `legendStops?: readonly HeatmapLegendStop[]` (attribute: false) — clone-owned, bounded, frozen `HeatmapLegendStop { value: number;
color?: string; label?: string; partOfRamp?: boolean }`: a discrete legend key rendered **instead of** the
  `--lr-heatmap-scale-lo`/`-hi` gradient bar and its `[part="legend-lo"]`/`[part="legend-hi"]`
  endpoint labels — one `[part="legend-stop"]` per entry, in array order, each a
  `[part="legend-swatch"]` filled with that entry's `color` plus a `[part="legend-stop-label"]`.
  `color` is optional: omit it, pass an empty string, or pass an invalid CSS color for a
  **caption-only** stop, which renders its `[part="legend-stop-label"]` alone with no
  `[part="legend-swatch"]` element in the DOM at all — so a leading "0" or trailing "more" caption
  around a run of colored stops doesn't leave an empty swatch box in the row.
  A stop's label defaults to the component's own locale-aware numeric formatting of `value`, so an
  explicit `label` is only needed when the number isn't the right caption ("none", "≥ 90%"). Exists
  for the consumer who supplies `cellColor`: because that callback overrides a cell's color
  entirely, the built-in two-endpoint bar can end up describing a ramp the grid no longer uses —
  supplying the same colors here keeps the legend honest instead of hiding `::part(legend)` and
  re-implementing swatches, labels and annotation entries by hand. Strictly presentation: the stops
  are never consulted by the color ramp, the bucket math, the tooltip, or the generated accessible
  name, so adding them changes nothing a cell renders. Labeled `annotations` still render their
  `[part="legend-annotation"]` entries after the stops. Unset (the default) or an empty array
  reproduces the exact gradient legend, unchanged. Reassigning stops whose `value`/`color`/`label`/
  `partOfRamp` fields are unchanged does not schedule a canvas redraw. The assignment still takes
  a fresh frozen ownership snapshot, so mutating and reassigning the same caller array is detected
  while mutation without reassignment remains isolated. A dev-mode-only warning fires when a stop's
  `color` doesn't match the corresponding `colorSteps` entry — set `partOfRamp: false` on a stop
  that is a real, distinctly-colored swatch deliberately outside the sequential ramp (e.g. a fixed
  "no data" color next to an N-step ramp) to exclude just that stop from the comparison; defaults to
  `true`. A caption-only stop (no `color`) is already excluded regardless of this flag.

**Getters/methods:** `exportData('png')` returns a PNG data URL for the most recently completed
canvas paint. It includes the painted axes, cells, focus/selection/annotation overlays, and frozen
label bands while `stickyLabels` is enabled; the DOM legend, tooltip, and accessible-cell buttons
are deliberately excluded. It returns `''` before a completed paint, while rendering is deferred or
zero-sized, after disconnect, or when the browser cannot encode the snapshot. `refreshTheme()` —
redraws canvas content after an upstream design-token or color-scheme change; called automatically
on theme changes, exposed for a consumer that needs to force a redraw manually. `matrixGeometry: Readonly<LyraHeatmapMatrixGeometryChangeDetail> | undefined` — the gutter/cell geometry the last matrix-mode draw actually painted with,
in CSS pixels; `undefined` in calendar mode. Lets a light-DOM consumer line up with the canvas
without hardcoding the same numbers `row-label-width`/`col-label-height`'s `"auto"` resolution would
otherwise keep private. For the case that motivated it — a frozen header or gutter on a tall or wide
matrix — prefer `stickyLabels`, which freezes the band inside the component and needs no mirror at
all; the getter remains the way to align a *separate* element (a sibling chart, a custom overlay)
with the grid. `LyraHeatmapMatrixGeometryChangeDetail` contains `padLeft`, `padTop`, and `cellSize`
(the square pitch), plus optional `cellWidth`, `cellHeight`, and `cellRadius` for custom matrix
presentation. When those optional fields are absent, painted width/height are `cellSize - 1` and
radius is zero. The getter and geometry-change event always share one frozen snapshot, including
changes to the resolved gaps/radius.

For a fluid day/hour matrix, keep all 24 hour strings in `data.colLabels` and use
`fit-to-width cell-gap-x="1" cell-gap-y="2" cell-radius="2" col-label-interval="3"`.
For a single fluid square cell, use `fit-to-width` with equal horizontal and vertical gaps.

**Events:** `lr-selection-change` (not cancelable; frozen readonly `HeatmapSelectionChangeDetail { selectedCells, source }` proposal in multiple mode, with `source: 'pointer' | 'keyboard' | 'row' | 'column'`; accept it by assigning `selectedCells`). `lr-cell-click` (fired on click, or Enter/Space on the keyboard-focused cell —
`detail: { row, col, value }` in matrix mode, `detail: { date, value }` in calendar mode),
`lr-matrix-geometry-change` (fired after a matrix-mode draw whose resolved `matrixGeometry` differs
from the previous draw — e.g. after `row-label-width="auto"`/`col-label-height="auto"` resolves
against new content or a resize; `detail` is the same object `matrixGeometry` returns; never fired
in calendar mode)

**Slots:** `legend` — custom content rendered inside the built-in `[part="legend"]` row, after the
gradient/`legendStops` swatches, the trailing `valueLabel` caption, and any labeled `annotations`
entries. Presentation-only, like `legendStops`: slotted content is never consulted by the color
ramp, the bucket math, the tooltip, or the generated accessible name. Nothing is rendered, and the
slot itself is absent from the shadow root, while `withoutLegend` is set. Available since 13.0.0;
this doc previously said "Slots: none" for several releases after that, which was a documentation
gap rather than a behavior change — the slot has worked, unannounced, the whole time.

**CSS parts:** `base`, `canvas`, `grid` (the scrollport wrapping the canvas while `stickyLabels`
freezes an axis — absent entirely otherwise), `row-labels`/`col-labels` (the frozen label bands,
rendered only for the axis `stickyLabels` names), `cells` (opt-in per-cell overlay), `cell` (one opt-in native cell
button), `tooltip` (hover tooltip, positioned over the hovered cell — inside `[part="grid"]` while
`stickyLabels` freezes an axis, so it scrolls with the cells, and a `[part="base"]` child
otherwise),
`live-region` (visually-hidden, `aria-hidden` mirror of the keyboard-focused cell; the actual
announcement uses the shared light-DOM polite sink), `projection-limit` (localized assistive
disclosure when bounded canonicalization truncates input), `legend`, `legend-lo`, `legend-hi` (both omitted, along with the gradient
bar between them, while `legendStops` is supplied), `legend-stop` (one per `legendStops` entry),
`legend-swatch` (that stop's color chip, not rendered at all for a caption-only stop),
`legend-stop-label` (that stop's text), `legend-value-label` (the trailing `valueLabel` caption that
closes the legend row, present in both the gradient and the `legendStops` branch),
`legend-annotation` (one per labeled `annotations` entry)

**Themeable custom properties:** `--lr-heatmap-scale-lo` (default `var(--lr-color-brand-quiet)`),
`--lr-heatmap-scale-hi` (default `var(--lr-color-brand)`) — the sequential color-ramp endpoints
(matrix mode) or quartile-bucket ramp endpoints (calendar mode), resolved via `getComputedStyle` each
draw (any valid CSS color syntax — hex/rgb/hsl/oklch/named — works, resolved through a scratch
canvas). Private defaults follow the theme (including dark mode), while inherited or direct public
values remain authoritative; the hard-coded `#cde2fb`/`#0969da` pair in the source is
only a last-resort constant for the case where the custom property resolves to an empty string (no
stylesheet applied at all), not the shipped default.
`--lr-heatmap-no-data-fill` (default `var(--lr-color-no-data)` — the no-data cell fill, same
resolve-via-`getComputedStyle` pattern), `--lr-heatmap-label-font` (default
`var(--lr-size-10px) var(--lr-font)` — the canvas-drawn axis/month/weekday label font),
`--lr-heatmap-focus-ring-color` (default
`var(--lr-focus-ring-color)` — the canvas-drawn ring stroked around the keyboard-focused cell;
also reused by `[part="canvas"]`'s own `:focus-visible` outline so the two stay visually in sync),
`--lr-heatmap-color-steps-gradient` (default
`linear-gradient(to right, var(--lr-heatmap-scale-lo), var(--lr-heatmap-scale-hi))` — the gradient
painted on the continuous legend bar; the component writes it onto the host itself while
`colorSteps` is supplied and the legend is rendered, and removes it again when either stops being
true — `withoutLegend` takes the legend row, this property's only reader, out of the DOM — so it is
a read-out rather than a knob you set). `--lr-heatmap-annotation-color` (default `var(--lr-color-danger)` — the canvas-drawn ring
stroked around an annotated cell, deliberately not one of the sequential ramp colors so it stays
visible regardless of what it's drawn over). `--lr-heatmap-selected-color` (default
`var(--lr-color-success)` — the canvas-drawn ring stroked around the persistent `selectedCell`, a
dedicated token distinct from both the focus ring and the annotation ring so a host can retheme it
independently). `--lr-heatmap-tooltip-bg` (default
`var(--lr-color-surface)`) and `--lr-heatmap-tooltip-text` (default `var(--lr-color-text)`) —
unlike the canvas-drawn tokens above, `[part="tooltip"]` is a real DOM element and consumes these
directly, no `getComputedStyle` bridging needed. `--lr-heatmap-sticky-label-bg` (default
`var(--lr-color-surface)` — the backdrop painted under a frozen `stickyLabels` band, resolved via
`getComputedStyle` like the other canvas-drawn tokens; it must stay **opaque**, since it covers the
same labels the scrolling canvas painted underneath it) and `--lr-heatmap-grid-max-block-size`
(default `none` — the block-size ceiling of the `[part="grid"]` scrollport, consumed directly by
that real DOM element; set it to give a frozen column band vertical scrolling to stay behind). Also consumes `--lr-color-text-quiet` (axis label
color), `--lr-space-xs`, `--lr-radius`/`--lr-shadow` (tooltip box), and `--lr-focus-ring-width`/
`--lr-focus-ring-offset` (the real `[part="canvas"]:focus-visible` DOM outline, stroked in the
same color as `--lr-heatmap-focus-ring-color`).

**Optional peer deps:** none.

```html
<lr-heatmap value-label="requests"></lr-heatmap>
<script>
  const hm = document.querySelector("lr-heatmap");
  hm.data = {
    kind: "matrix",
    rowLabels: ["Mon", "Tue", "Wed"],
    colLabels: ["00h", "06h", "12h", "18h"],
    values: [
      [3, 8, 12, 4],
      [1, 2, 9, 5],
      [0, 4, 6, 2],
    ],
  };
</script>
```

```html
<!-- Calendar mode: a GitHub-contributions-style day grid -->
<lr-heatmap value-label="commits"></lr-heatmap>
<script>
  document.querySelector("lr-heatmap").data = {
    kind: "calendar",
    days: [
      { date: "2026-01-01", value: 3 },
      { date: "2026-01-02", value: 0 },
    ],
    firstDayOfWeek: 1,
  };
</script>
```

**9.0 migration:** replace the independent `mode`, `rowLabels`, `colLabels`, `values`, `days`,
`firstDayOfWeek`, `columnX`, `rowY`, `weekdayLabelText`, and `monthLabelText` members with one
`data` assignment as shown above. There are no runtime aliases: this removes stale cross-mode state
and gives every scale/count/paint/selection/event path the same bounded projection. Replace the old
magic `value-label="value"` localization sentinel by removing the attribute; a supplied `"value"`
is now literal.

**Known gotchas:**

- Matrix projection is capped at 10,000 renderable cells. Calendar input is capped at 10,000
  records and 530 weeks, and the color-step/legend-stop/annotation projections are each capped at
  256 entries. `[part="projection-limit"]` and the generated accessible summary disclose every
  truncation. The semantic grid mounts at most 400 cell buttons while preserving full navigation.
- Calendar duplicates use a first-valid-wins ISO-date identity. Invalid dates are dropped. `data.columnX`
  and `data.rowY` results must be finite, nonnegative, monotonic and non-overlapping; an invalid,
  throwing or hostile result safely falls back to the normal coordinate for that position.
- Annotation, controlled selection and keyboard focus use independent concentric canvas rings;
  selection/focus also use distinct dash patterns so forced-color rendering does not collapse the
  three public states into one overwritten outline.
- The legend is a wrapping flex row. Long unbroken stop labels, the trailing `valueLabel`, and
  annotation labels wrap within the host instead of forcing the heatmap wider than its allocation.
- `legendStops` _replaces_ the lo/hi gradient bar rather than adding to it: supplying it removes
  `[part="legend-lo"]`, `[part="legend-hi"]` and the bar from the DOM, so a stylesheet targeting
  those parts silently stops applying. It is also presentation-only — it never feeds back into the
  cell colors, so the stops and a `cellColor` callback have to be kept in agreement by the consumer
  (the point of the property is that they _can_ be, from one shared function).
- the `ResizeObserver` only actually resizes the drawn grid **when `fit-to-width` is set**, in either
  mode. Without it (the default), `draw()` sizes the canvas as `PAD_LEFT + cols * cellSize` (matrix
  mode) or `CAL_PAD_LEFT + weekCount * cellSize` (calendar mode), never from the host's measured
  width, so a container-resize redraw is a geometric no-op; the stylesheet's
  `canvas { inline-size: 100% }` is also dead code in that case, since `draw()` unconditionally sets
  an inline `canvas.style.width/height` that wins over it.
- `maxCellSize`/`minCellSize` are no-ops without `fit-to-width` — an explicit `cellSize` is an exact
  request and is never clamped. And the canvas is sized _from the clamped_ cell size, so a capped
  grid deliberately leaves the host's remaining width unfilled: the canvas simply ends early rather
  than stretching to fill. `fit-to-width` derives that cell size from the host's own measured
  `clientWidth`, so do **not** make the host itself shrink-to-fit (`display: inline-block`,
  `inline-size: fit-content`, floating it, ...) to chase the capped canvas — that makes the host's
  width a function of its own rendered content while the content's width is derived from the host's
  width, a circular sizing dependency the browser cannot resolve stably. Keep the host at its normal
  block-level, fully-sized width and position the canvas within it instead:
  `::part(canvas) { margin-inline: auto }` centers it, `::part(canvas) { margin-inline-start: auto }`
  end-aligns it. Reach for `::part(canvas)`, not `::part(base)`: `[part="base"]` is a flex column, so
  `::part(base) { align-items: center }` also centers the canvas, but shrink-wraps every other base
  child along with it — the legend row included, which loses its full-width wrap layout and
  collapses to the canvas's own (possibly capped) inline size.
- the host is `role="group"` (not `role="img"`) with a dimensions+range summary `aria-label`
  (calendar mode: a day-count + range summary instead). In default canvas mode,
  `[part="canvas"]` is itself a named `role="application"`, focusable, keyboard-operable,
  per-cell-interactive control (roving arrow-key focus, shared light-DOM announcements,
  `lr-cell-click`). `role="img"` would flatten that interactive subtree for some assistive tech.
  With `accessibleCells`, the canvas becomes `aria-hidden` and the native cell-button overlay owns
  the interactive semantics instead.
- `NaN`/non-finite cell values in matrix mode are correctly treated as no-data now (alongside `-1`),
  and repeated DPR crossings (moving the window across displays with different pixel ratios) no
  longer leak a `MediaQueryList` listener per crossing — both previously-known issues are fixed.
- calendar mode's date labels (used by the default `cellText` template and the tooltip/announcement
  text) now format via `effectiveLocale` (`toLocaleString(effectiveLocale, ...)`) instead of a hardcoded
  `'en'` — fixed. The canvas-drawn axis chrome is now locale-aware too: month labels use
  `toLocaleString(effectiveLocale, ...)` (previously hardcoded `'en'`) and weekday labels are derived via
  `Intl.DateTimeFormat(effectiveLocale, { weekday: 'short' })` (previously a literal English `['', 'Mon',
'', 'Wed', '', 'Fri', '']` array) — same sparse every-other-day spacing, just locale-correct text.
- this component's legend can show more than a label (a value caption, `legendStops` swatches,
  annotation entries, a custom slot) and can now be turned off outright with `withoutLegend`.
  `lr-sequence-strip`'s `showLegend` key is swatch+label only, the same "legend needs more than a
  label" shape `lr-context-meter`'s `legendDisplay` addresses for that component; unaddressed here,
  since fixing it belongs with whichever component actually has the gap.

---

## `lr-sequence-strip`

A compact, one-thin-cell-per-item (or per item range) strip visualizing a sequence of categorical
states, with an
optional secondary per-cell marker. Pure CSS/flex — no chart.js, no SVG, no canvas — sized/named
consistently with the sparkline/heatmap family, and read as a glanceable aggregate. `[part="base"]`
is a labeled `role="list"` and each cell a named `role="listitem"` (`aria-label`, `aria-posinset`,
`aria-setsize`), so the sequence is walkable item by item rather than collapsed into one summary
string. Exactly one cell is tabbable at a time (roving `tabindex`); ArrowLeft/ArrowRight and
Home/End move the stop — direction-aware, so the arrows swap under RTL — and focusing a cell shows
the same `[part="tooltip"]` detail that pointer hover does. That tooltip is positioned from the
active cell, not from the center of the whole strip. The tooltip is visual only and is not
wired through `aria-describedby`, because the cell's own `aria-label` already exposes the identical
text and describing it again would duplicate the announcement. Cells are actionable: clicking a
cell, or pressing Enter/Space on the roving cell, emits `lr-item-activate`. Selection is controlled,
so the consumer updates `selectedIndex` when it accepts that activation. Setting `showLegend`
additionally renders a static `[part="legend"]` key below the strip, so the color-to-category
mapping is readable without visiting each cell.

A standard host `aria-label` names the host itself and is not copied verbatim to the internal
list; `accessible-label` remains the list-specific override and otherwise the generated
category-count summary names it. When an
`items` refresh occurs while a cell owns focus, its `id` remains the sole roving stop; removal
clamps focus to the nearest survivor, or to the stable list base when no cells remain. Unfocused
refreshes do not move focus. A queued Arrow/Home/End focus is bound to the current item-array
identity and connection generation, so a same-turn replacement or disconnect/reconnect cannot
focus an unrelated cell that merely inherited the old numeric index.

High-cardinality strips retain at most the first 10,000 assigned items and categories as detached,
frozen canonical snapshots; reassign either collection after changing it. At most 200 cells are
rendered. **At or below that cap each cell is one item. Past it the strip becomes a span-preserving
overview rather than a window:** the retained items are distributed over exactly 200 contiguous
ranges, each cell painted by its range's dominant category (a tie goes to the category appearing
earliest in the range) and carrying `[part="marker"]` when any item inside it sets `marker`. The 200
cells tile the sequence exactly once, so the strip always covers the full span at full width and
never needs horizontal scrolling. Roving focus, `aria-posinset`/`aria-setsize`, `aria-current` and
activation all address cells rather than items: ArrowLeft/ArrowRight and Home/End step one range at
a time, and each cell exposes `data-range-start` / `data-range-end` (zero-based, inclusive item
indices) alongside its `data-index` range position. `[part="bucket-summary"]` visibly discloses the
item total and range count, and the same localized text is appended as a trailing clause to the
generated `aria-label` so assistive technology learns the cells are ranges. The optional legend
likewise mounts at most 200 categories and exposes `[part="legend-limit"]` as a rendered/total
numeric disclosure.

**Properties:**

- `items: readonly SequenceStripItem[] = []` (attribute: false) — `{ readonly id, readonly
categoryId, readonly marker?, readonly label?, readonly disabled? }`;
  `marker` renders a small bottom marker on that cell independent of the category color (e.g. a
  subagent-dispatched turn); `label` is per-item hover/focus tooltip text _and_ that cell's own
  `role="listitem"` accessible name, falling back to the matching category's own nonblank `label`,
  then localized `sequenceStripUnnamedCategory` (`"Unnamed category"` in the built-in English
  catalog) when unset — it is not read by `[part="base"]`'s auto-generated `aria-label`, which
  summarizes by category/count only. `disabled` marks the item non-actionable:
  `aria-disabled="true"` replaces the selected/active affordances of the cell that represents it,
  activating it (click or Enter/Space) emits nothing, and roving Left/Right/Home/End navigation —
  including the default resting tab stop — steps past it. Above the 200-cell cap, a range cell's
  disabled state follows its own activated item, the range's first. Omitted or `false` renders the
  item exactly as before this field existed
- `categories: readonly SequenceStripCategory[] = []` (attribute: false) — `{ readonly id,
readonly color, readonly label? }`; `color`
  is the cell background for every item whose `categoryId` matches `id`; invalid CSS colors,
  declaration-breaking input, `url()`, and unmatched categories render `transparent`. `label` is
  used in the auto-generated `aria-label` summary and as the hover-tooltip fallback text, falling
  back to localized `sequenceStripUnnamedCategory` when omitted or blank rather than exposing the
  internal `id`. Both collection properties are cloned and frozen at assignment,
  bounded to the first 10,000 source entries, and require reassignment after changes; empty/blank
  ids are omitted and duplicates use the first valid entry, so identity is deterministic
- `accessibleLabel?: string` (attribute `accessible-label`) — overrides the auto-generated
  `aria-label` (a per-category "label: count" summary, e.g. `"Text: 2, Tool: 1"`). Unset computes the
  summary from `items`/`categories`; a standard host `aria-label` remains a distinct host name
- `showLegend: boolean = false` (attribute `show-legend`, reflected) — renders a static
  `[part="legend"]` key below the strip, one swatch + label row per `categories` entry, in array
  order. The key describes the _scheme_, not the current data: a category with no matching item
  still gets a row, and an item whose `categoryId` matches no entry adds none. Deliberately
  non-interactive — it toggles nothing and emits nothing (`lr-graph-legend` is the interactive,
  filtering legend). Because it only repeats the category names `[part="base"]`'s own `aria-label`
  summary already announces, the legend is `aria-hidden` — visible on screen, announced exactly
  once — and it wraps onto further rows in a narrow allocation rather than overflowing
- `markerLabel?: string` (attribute `marker-label`) — names what an item's `marker` _means_ (e.g.
  `"Subagent"`). Setting it does two things: with `showLegend` on it adds one trailing
  `[part="legend-item"]`, whose `[part="legend-marker-swatch"]` reproduces the cell's own marker
  treatment, and it adds the marker to the auto-generated `aria-label` summary, which is otherwise
  per-category only. The marker count is reported as its own clause rather than folded into any
  category's count. Unset (the default) changes nothing: no extra legend row, no extra summary clause

- `selectedIndex: number = -1` (attribute `selected-index`) — the currently selected item, or `-1`
  for none. **Controlled:** activating a cell emits `lr-item-activate` and does *not* move the
  selection itself, so the consumer stays the single source of truth and the strip cannot drift from
  a playback index it does not own (its natural companion is `lr-sequence-playback`). Mirrors the
  shape `lr-lite-chart`'s `selectedIndices` and `lr-heatmap`'s `selectedCell` already establish. An
  out-of-range or non-integer value selects nothing. The selected cell carries `aria-current="true"`
  and `data-selected`; the selection is drawn as a ring rather than a background change, because a
  cell's background is data (its category colour) and tinting it would misreport the category. Past
  the 200-cell cap the whole range that contains `selectedIndex` reads as selected, since that range
  is the only thing the strip draws for it

The single-member `orientation: 'horizontal'` property was **removed in 9.0.0**: nothing read it and
the stylesheet never mentioned it, so the reflected attribute styled nothing. Delete the attribute;
the strip has always laid out horizontally.

**Events:** `lr-item-activate` — `detail: { index: number; id: string; item: SequenceStripItem }`,
fired when a cell is clicked or activated with Enter/Space on the roving-tabindex focus. Past the
200-cell cap a cell stands for a range, and the event reports that range's **first** item — a real
sequence index a playback consumer can scrub from, not a synthesized midpoint. The `detail` shape is
unchanged. Not
cancelable: nothing in the component branches on `defaultPrevented`. Bubbles and composed, like every
library event.

**Slots:** none.

**CSS parts:** `base` (the root strip, `role="list"`), `cell` (each item's `role="listitem"` cell,
background-colored by its category, carrying the roving `tabindex`, and activatable by click or
Enter/Space — it has a pointer cursor plus paired hover/press treatments, and `[data-selected]` when
it is `selectedIndex`), `marker` (the small bottom
marker on a cell whose item sets `marker: true`), `tooltip` (the detail tooltip showing the active
item's label, hidden until a cell is hovered or focused),
`legend` (the static category key rendered below the strip when `showLegend` is set — `aria-hidden`,
as it repeats the strip's own `aria-label`), `legend-item` (one swatch + label pair, one per
`categories` entry, plus one trailing marker row when `markerLabel` is set), `legend-swatch` (the
color chip, matching that category's cell color), `legend-marker-swatch` (the marker row's chip
instead: a neutral chip carrying the same bottom bar a `marker: true` cell paints, in the same
`--lr-sequence-strip-marker-color`), `legend-label` (the category's nonblank `label`, or localized
`sequenceStripUnnamedCategory`), `bucket-summary` (the item-total/range-count disclosure, rendered
only while the strip is past its 200-cell cap; it replaced 15.x's `window-range`, which disclosed a
projection window this component no longer has), and `legend-limit`
(bounded legend/total).

**Themeable custom properties:** `--lr-sequence-strip-height` (default `1.5rem` — the strip's
block-size), `--lr-sequence-strip-marker-color` (default `var(--lr-color-text)` — the
`[part="marker"]` fill, and of the marker legend row's bar), `--lr-sequence-strip-legend-swatch-size`
(default `0.625rem` — a legend swatch's inline- and block-size, category and marker rows alike), and
`--lr-sequence-strip-legend-marker-bg` (default `var(--lr-color-surface-raised)` — the neutral chip
background behind the marker legend row's bar; it stands in for "any cell", so it deliberately
matches no category color), and `--lr-sequence-strip-disabled-opacity` (default `var(--lr-opacity-disabled)` — opacity of
a cell whose activated item sets `disabled`); the tooltip also consumes shared tokens
`--lr-color-surface`, `--lr-color-text`, `--lr-font-size-xs`, `--lr-radius`, and `--lr-shadow`, and
the legend consumes `--lr-space-2xs`, `--lr-space-xs`, `--lr-space-s`, `--lr-font-size-xs`,
`--lr-color-text-quiet`, and `--lr-radius-xs`.

**Optional peer deps:** none.

```html
<lr-sequence-strip></lr-sequence-strip>
<script>
  const strip = document.querySelector("lr-sequence-strip");
  strip.categories = [
    { id: "text", color: "#4f46e5", label: "Text" },
    { id: "tool", color: "#16a34a", label: "Tool" },
  ];
  strip.items = [
    { id: "1", categoryId: "text", label: "Turn 1: text" },
    { id: "2", categoryId: "tool", marker: true, label: "Turn 2: tool call" },
    { id: "3", categoryId: "text", label: "Turn 3: text" },
  ];
</script>
```

**Known gotchas:**

- the activation event is `lr-item-activate`, not `lr-cell-click`. Click and Enter/Space emit the
  activated item's `index`/`id`, but do not mutate the controlled `selectedIndex`; listen for the
  event and update that property when the application accepts the activation.
- an `items` entry whose `categoryId` has no matching `categories` entry still contributes to the
  strip (its cell's background is `transparent`) rather than being dropped, so a strip renders one
  cell per item — or, above the 200-cell cap, one cell per range — regardless of `categories`
  coverage.
- **16.0 migration:** above 200 items the strip renders item RANGES, not a 200-item window. Rename
  any `::part(window-range)` selector to `::part(bucket-summary)`. Code that read a cell's
  `data-index` as an item index must read `data-range-start` / `data-range-end` instead — above the
  cap `data-index` is the range's position in the strip, not an item's position in the sequence. Two
  localization keys are new: `sequenceStripBucketLabel` (`"{label}, items {start} to {end}"`) and
  `sequenceStripBucketSummary` (`"{items} items in {ranges} ranges"`).
- **9.0 migration:** rename category `{ key }` to `{ id }` and item `{ category }` to
  `{ categoryId }`. Reassign after changes; caller mutation no longer changes the installed
  snapshot. Category clauses use effective-locale `Intl.ListFormat` punctuation.

---

## `lr-tree` / `lr-tree-item`

An expand/collapse hierarchy (document/graph navigation tree). Mirrors `wa-tree`/`wa-tree-item` and
`sl-tree`/`sl-tree-item`.

An otherwise unnamed data row receives its stable `id` as a semantic name. Usable `accessibleLabel`,
visible label, description, badge content and explicit host naming retain precedence; the fallback
changes neither visible content nor installed data. Blank visible labels remain supported.
Declarative items receive no automatic ID fallback.

**Renamed in 8.0.0 — breaking:** the child element is `<lr-tree-item>` (class `LyraTreeItem`), not
`<lr-tree-node>`/`LyraTreeNode`. It was the only child element in the library whose tag diverged
from both upstreams, so `wa-tree-item`/`sl-tree-item` markup had nothing to rename to. The shared
data types moved to `tree-types.ts` to free the name and are still re-exported from `tree.js`. A
leftover `<lr-tree-node>` is an unregistered tag: it never
upgrades, `<lr-tree>` does not count it as an item at all, and the tree renders its empty state
with the stale markup sitting inert in the light DOM — no error anywhere.

**9.0 type/API cleanup:** rename the structured-data type `TreeItem` to `LyraTreeNodeData`, use
`LyraVariant` for `TreeBadge.tone` instead of `TreeBadgeTone`, and replace a singular `badge` value
with `badges: [{ text: String(value) }]`. The former item-controller fields (`activeId`, `ancestry`,
`depth`, `setSize`, `posInSet`) and context setters were never consumer state; they are now private
owner context maintained by `<lr-tree>`.

**Two child models are accepted, and they never interleave.**

- **Declarative** (mirrors the upstream markup, so a tag rename is the whole migration): write
  nested `<lr-tree-item>` elements as light-DOM children, each carrying its own
  `label`/`expanded`/`disabled`/`selected` attributes. `<lr-tree-item>` moves its nested children
  onto an internal `children` slot itself, so you never write `slot=`.
- **Data**: leave `<lr-tree>` empty and assign `data`, a `LyraTreeNodeData[]` of plain objects. This is this
  library's own original shape and is where per-row icons, secondary descriptions and badges live —
  the declarative model has none of those. `<lr-tree>` creates and reconciles the
  `<lr-tree-item>` children by `id`, and each item renders its own subtree into its own shadow root.
  Every reachable `LyraTreeNodeData.id` must be nonblank and globally unique. Malformed rows and
  later duplicates are omitted before rendering; the first valid depth-first occurrence wins
  and cannot receive focus, selection, expansion, or reorder requests. Supplying unique refreshed
  data releases that fail-closed state.

A tree containing any author-written `<lr-tree-item>` child is read purely as the declarative model
and `data` is ignored. The empty state renders only when neither model has any items.

Both child models use the same selection, roving-focus, checkbox-cascade, icon, and lazy-loading
engine. The upstream lifecycle names are normalized to the library-wide `lr-` prefix;
`lr-node-toggle` and `lr-node-select` remain as additive Lyra notifications. In multiple modes the
tree role explicitly exposes `aria-multiselectable="true"` (and explicit `"false"` otherwise),
while each treeitem host is the sole selected/checked/mixed semantic owner; checkbox-shaped chrome
is decorative and cannot duplicate the row's accessible name.

### `lr-tree`

Implements the full WAI-ARIA treeitem keyboard pattern: a single owner-controlled roving `tabindex`
across every reachable `<lr-tree-item>` and
ArrowUp/Down/Right/Left/Home/End/Enter/Space handled by one delegated `keydown` listener (native
`KeyboardEvent`s are `composed: true` and bubble across shadow-DOM boundaries, so a press inside a
deeply-nested node's own shadow root still reaches it).

**Properties:**

- `data: readonly LyraTreeNodeData[] = []` (attribute: false) — the object child model; ignored
  while any author-written `<lr-tree-item>` child is present. Assignment installs a detached,
  recursively frozen snapshot: mutate caller data only before assignment, then reassign after
  changes. Normalization accepts at most 1,000 valid nodes and 64 descendant levels, and lazily
  inspects at most 10,000 root/child array positions globally in depth-first order. It never
  invokes caller accessors and exposes `dataTruncated = true` when malformed or over-budget input
  was omitted or the inspected-position ceiling was reached. Collapsed branches do not instantiate descendants; disclosure projects only normalized
  children while `aria-setsize` preserves the declared sibling count. `LyraTreeNodeData` is
  `{ readonly id: string; readonly label: string; readonly children?: readonly LyraTreeNodeData[];
readonly selected?: boolean; readonly disabled?: boolean; readonly lazy?: boolean; readonly
badges?: readonly TreeBadge[]; readonly icon?: unknown; readonly description?: string; readonly
accessibleLabel?: string }`. `TreeBadge` is `{ readonly text: string; readonly tone?:
LyraVariant; readonly label?: string }`. `badges` renders tone-mapped chips in order. A nonempty
  `label` makes that chip a named `img`; when the override is omitted or empty, no generic role or
  redundant `aria-label` is added and the visible `text` contributes to the treeitem name naturally.
  `icon` renders as a decorative leading visual, `description` as secondary visible row text, and
  `accessibleLabel` names the `role="treeitem"` host without changing its visible label. An
  author-supplied host `aria-label` takes precedence by presence and is never overwritten or
  removed by later object refreshes; removing the author attribute restores the current data name.
  `id` is the event, roving-focus, reconciliation, and reorder identity and must be unique across
  the complete reachable hierarchy; malformed rows, blank IDs and later duplicates are omitted as described above
- `selection: 'single'|'multiple'|'leaf'|'leaf-multiple' = 'single'` — self-managed selection for
  both child models. `single` selects one item; `leaf` selects one loaded leaf; `multiple` displays
  checkboxes and cascades through enabled descendants; `leaf-multiple` applies that cascade only
  to leaves. Partially-selected branches expose `indeterminate`
- `label: string = ''` — accessible-name fallback for the tree; `role="tree"` lives on an internal
  `[part="base"]` element. A host `aria-label` takes precedence by attribute presence, including an
  explicit empty string; removing it restores the `label` fallback. External `aria-labelledby`
  idrefs are not forwarded across the shadow boundary.
- `reorderable: boolean = false` (reflected) — opts into keyboard reordering. Unset, no `lr-reorder`
  is ever emitted, Ctrl/Cmd+Arrow behaves exactly like a plain Arrow press, and the internal live
  region is not rendered at all.

**Read-only getters:** `selectedItems: readonly LyraTreeItem[]` returns a new frozen snapshot of
selected item elements in document order, including derived fully-selected parents in either
multiple mode. `dataTruncated: boolean` reports bounded/malformed normalization as described above.

**Keyboard:** ArrowDown/ArrowUp move the roving focus to the next/previous _visible_ node.
ArrowRight expands a collapsed node (focus stays put; a second ArrowRight then steps into the first
child) or moves into an already-expanded node's first child. ArrowLeft collapses an expanded node, or
moves focus to its parent. Home/End jump to the first/last visible node. Enter/Space activate
`select()` on the focused node. While `reorderable`, **Ctrl/Cmd**+ArrowUp/ArrowDown moves the focused
node within its own parent's child list instead of navigating. Ctrl/Cmd rather than Alt: Alt+Arrow is
browser back/forward on Windows and Linux. ArrowUp/ArrowDown are not direction-sensitive, so this
binding is deliberately **not** RTL-swapped — "down" always means later in the sibling list.
If a same-id data refresh disables an expanded branch, that reused branch collapses immediately;
enabled descendants are never left visibly stranded outside this navigation walk.

**`inert` excludes an item and its whole subtree from that walk, exactly as `disabled` does.**
`role="treeitem"` and the roving `tabindex` both live on the `<lr-tree-item>` host itself, so an
inert item literally refuses `focus()` — stepping the roving index onto one would leave focus behind
on `<body>` and kill every later arrow press. Marking the focused item inert therefore moves the
roving stop to the next reachable row instead of stranding it, and the state is observed live
(`attributeFilter: ['selected', 'disabled', 'inert', 'lazy']`). Two deliberate limits:

- **Only inertness _inside_ the tree counts** — the item's own `inert`, or that of an ancestor item
  between it and the `<lr-tree>`. An inert ancestor _outside_ the tree (the page behind an open
  modal) inerts every item uniformly, and excluding them all would empty the walk, null out
  `activeId`, and leave the tree with no `tabindex="0"` stop for anything to restore once the dialog
  closes. That case needs no handling: focus cannot be inside the tree at all.
- **Selection ignores it.** An inert subtree is temporarily non-interactive, not deselected, so
  `selectedItems` and the multiple-mode cascade are unchanged and a modal that inerts the page can
  never silently wipe a tree's selection.

**Methods:** `expandAll(): Promise<void>`, `collapseAll(): Promise<void>` (both iterative, bounded,
and resolved only after the affected rendered item cascade settles).

**Events:** `lr-selection-change` (`detail: { selection }`, where both the detail and selection
snapshot are frozen) and `lr-reorder` (`detail: { nodeId, parentNodeId, fromIndex, toIndex }`, only while `reorderable`).
Like every other event here it is a **request**: `data` is host-owned and is never mutated by this
component, so nothing moves until the host reassigns a reordered `data` — focus then follows the
moved node. The live region likewise announces a completed move only after the rendered sibling
order confirms the exact requested swap. Ignored or rejected requests stay silent, and unrelated
updates do not prematurely discard an asynchronously persisted request. `parentNodeId` is `null` for a
top-level item, and `fromIndex`/`toIndex` are **sibling-scoped
indices**, not positions in the flattened visible list. The move is constrained to one sibling list
and never fires at a subtree boundary, so a reorder can never become a reparent: Ctrl+ArrowDown on
the last child of a subtree is ambiguous (the visually next row is a top-level uncle, so "move down"
could mean either "swap with the next sibling" — there is none — or "reparent up a level"), and
reparenting is a structural edit with no keyboard affordance distinguishing the two. Such a request
is simply not made: no event, no announcement, focus stays put. Item events listed below bubble
through the tree as well.

**Slots:** default — top-level `<lr-tree-item>` elements, each nesting its own children (the
declarative model). Leave it empty and assign `data` for the object model; the same slot then holds
the items `<lr-tree>` generates. `expand-icon` and `collapse-icon` provide tree-wide disclosure
icons; an item-level slot with the same name takes precedence.

**CSS parts:** `base` and `tree` are aliases on the same `role="tree"` root; `empty` is the
empty-state message shown when neither child model has any items.

**Themeable custom properties:** shared tokens `--lr-space-xs`/`-s`, `--lr-color-brand-quiet`,
`--lr-color-text-quiet`, `--lr-color-border`, `--lr-color-text`, `--lr-radius`,
`--lr-focus-ring-*` (row `:focus-visible` ring, driven by `:host(:focus-visible)` since the host
itself is the focusable `role="treeitem"`), plus `--indent-size`, `--indent-guide-color`,
`--indent-guide-offset`, `--indent-guide-style`, and `--indent-guide-width`.

**Optional peer deps:** none.

### `lr-tree-item`

One row of the tree, in either child model. `role="treeitem"` (plus
`aria-expanded`/`aria-level`/`aria-setsize`/`aria-posinset`/`aria-selected` and the roving
`tabindex`, driven by `<lr-tree>`) live on the _host_ element itself, not an internal row `<div>` —
so this node's own nested children (whether rendered in its own shadow root or projected from the
light DOM, as further `role="group"` content) are genuine DOM descendants of the treeitem, matching
the WAI-ARIA treeitem pattern's containment expectation.

**Properties — declarative model** (write these as attributes; `item` data seeds the matching state
when assigned):

- `label: string = ''` — the row's label, used only when nothing is slotted into the default slot
- `disabled: boolean = false` (reflected) — removes the item from roving focus and blocks
  select/toggle activation
- `selected: boolean = false` (reflected) — renders the selected state and is exposed as
  `aria-selected`
- `lazy: boolean = false` (reflected) — defers expansion, renders the spinner, and emits
  `lr-lazy-load` until children arrive or `lazy` is cleared

**Properties — data model:**

- `item?: LyraTreeNodeData` (attribute: false) — the whole subtree as one object, normally assigned by
  `<lr-tree>` from its `data`. An assigned `item` **wins** for label/disabled/children and seeds
  `selected`/`lazy`; a refreshed object identity re-seeds those values. Light-DOM children are
  ignored while `item` is assigned. Outside an owning tree, an omitted `item.selected` leaves
  `aria-selected` off the host; an owning tree always publishes explicit true/false state. Assign
  `undefined` to return safely to the declarative model and reset data-seeded selected/lazy state

**Properties — shared:**

- `expanded: boolean = false` (reflected)
- `loading: boolean` (read-only) — a lazy expansion is waiting for children
- `indeterminate: boolean` (read-only) — an enabled branch has some but not all selectable
  descendants selected

**Read-only getters** — each answers for whichever child model is in use, which is what lets
`<lr-tree>` drive both with one implementation:

- `nodeId: string` — this item's identity: `item.id` in the data model, or a generated per-element
  id in the declarative one (where the markup carries no id of its own). It is the `nodeId` every
  `lr-node-toggle` / `lr-node-select` / `lr-reorder` detail carries, and what the tree tracks its
  roving tabindex by
- `isDisabled: boolean` — `item.disabled` in the data model, the `disabled` property in the
  declarative one
- `nodeLabel: string` — this item's spoken name, used for the tree's reorder announcements: a host
  `aria-label` is authoritative in both models
  (including the component-owned stable-ID fallback for otherwise unnamed data rows); otherwise `item.accessibleLabel || item.label` in
  the data model, or flattened accessibility-visible slotted label text (nested items excluded)
  followed by the `label` fallback in the declarative one. Direct and forwarding-slot
  text/ARIA/visibility mutations update the name
- `hasChildren: boolean` — whether this node has at least one child in whichever model is in use.
  Leaf nodes never expose `aria-expanded` and cannot expand or collapse. It also reports `false`
  past the owner controller's 64-level bound, which stops runaway recursion; cyclic object graphs
  are detected by private ancestry identity

**Methods:** `expand()`, `collapse()` (each a no-op if already in that state, disabled, loading, or a leaf),
`select()` (fires `lr-node-select`; a no-op while disabled), and host `click()` (forwards exactly
once to the same selection path and is likewise disabled-gated). `childItems(): LyraTreeItem[]` returns
this node's **direct** child `<lr-tree-item>` elements — from its own shadow root in the data model,
from its own light-DOM children in the declarative one. A grandchild is not included; it lives under
its own parent. `getChildrenItems({ includeDisabled = true } = {})` is the upstream-compatible
public spelling over the same direct-child list.

**Events:** `lr-node-toggle` (`detail: { nodeId, expanded }`, fired by `expand()`/`collapse()` — via
the toggle button or ArrowRight/ArrowLeft), `lr-node-select` (`detail: { nodeId }`, fired by `select()`
— via clicking anywhere in the row or Enter/Space) — dispatched from `lr-tree-item`,
bubble/compose up through `lr-tree`'s light DOM. `lr-expand`/`lr-collapse` fire when a transition
begins; `lr-after-expand`/`lr-after-collapse` fire after the matching themeable duration. Rapid
opposite transitions and disconnects invalidate stale after-events. Collapse keeps the subtree
mounted through its real opacity animation and removes it only when the animation completes;
reduced motion settles immediately, and duration parsing is finite/nonnegative/timer-capped.
`lr-lazy-load` requests data
with `detail: { item, generation }`; `lr-lazy-change` reports `detail: { item, loading }` when the
pending state starts or ends. Disabling or disconnecting an item invalidates the pending generation.

**Slots:** default — the row's label content in the declarative model. `children` — where nested
`<lr-tree-item>` children are projected; **assigned by the component**, so write the nested items in
the default slot and never set `slot="children"` yourself. `expand-icon` and `collapse-icon`
override the owning tree's corresponding icon for one item. The label/children slots are unused in
the data model.

Visual slot selection is separate from `nodeLabel` extraction: flattened element-only and visible
`aria-hidden` content still chooses the authored slot instead of the `label` fallback, while hidden
content is omitted from the spoken name. Host `aria-label` remains authoritative by presence.

**CSS parts:** `base` and `tree-item` are aliases on the same outer wrapper around the row and child
group; `row`, `toggle`, `icon`, `content`, `label`, `description`, `badge`, `group`, `item`,
`item--disabled`, `item--expanded`, `item--indeterminate`, `item--selected`, `indentation`,
`expand-button`, `spinner`, `spinner__base`, `children`, `checkbox`, `checkbox__base`,
`checkbox__control`, `checkbox__control--checked`, `checkbox__control--indeterminate`,
`checkbox__checked-icon`, `checkbox__indeterminate-icon`, and `checkbox__label`. `badge`
is applied to every `item.badges` chip; chips carry
`data-tone="neutral|brand|success|warning|danger"`. `icon` is `aria-hidden="true"`; `content`
groups the primary label and optional wrapping secondary description while preserving one
interactive treeitem per row. `icon`, `description` and `badge` render only in the data model —
the declarative model has no icon/description/badge inputs, so a row written as markup renders
`row`/`toggle`/`content`/`label` (and `group` while expanded) and nothing else.
`item` and its four state aliases are real painted row containers: consumer background, border,
padding, and opacity rules reach the visible row rather than a boxless wrapper.
The enabled disclosure `toggle` has its own pointer-hover feedback in addition to the row's hover
treatment; disabled toggles remain visually inert.
In the data model, every recursively rendered child forwards this complete part list under the
same names, so one selector on the outer item, such as `lr-tree-item::part(row)`, reaches matching
parts at every rendered depth. Declarative children remain light-DOM hosts and can be matched
directly as `<lr-tree-item>` elements.

**Themeable custom properties:** `--indent-size` (default `var(--lr-space-l)`, applied once per
nesting depth), `--indent-guide-color` (default `var(--lr-color-border)`),
`--indent-guide-offset` (default `0`, the guide's block-axis inset at both ends),
`--indent-guide-style` (default `solid`), and `--indent-guide-width` (default `0`); these mirrored
properties are consumed directly by every `<lr-tree-item>` and may be set on an item or inherited
from `<lr-tree>`. `--lr-tree-depth` is internal and set inline per row for indentation;
`--show-duration`/`--hide-duration` both default through `--lr-duration-base`;
`--lr-tree-selected-color` and `--lr-tree-selected-bg` for the selected row; and paired
`--lr-tree-checkbox-checked-border-color`, `--lr-tree-checkbox-checked-bg`,
`--lr-tree-checkbox-checked-color`, `--lr-tree-checkbox-indeterminate-border-color`,
`--lr-tree-checkbox-indeterminate-bg`, and `--lr-tree-checkbox-indeterminate-color` independently
theme the two multiple-selection checkbox states (brand border/background and on-brand glyph
fallbacks); and paired
`--lr-tree-badge-{neutral|brand|success|warning|danger}-color` /
`--lr-tree-badge-{neutral|brand|success|warning|danger}-bg` properties for each badge tone. Each
badge property falls back to its corresponding shared semantic token. The expanded names are
`--lr-tree-badge-neutral-color`, `--lr-tree-badge-neutral-bg`, `--lr-tree-badge-brand-color`,
`--lr-tree-badge-brand-bg`, `--lr-tree-badge-success-color`, `--lr-tree-badge-success-bg`,
`--lr-tree-badge-warning-color`, `--lr-tree-badge-warning-bg`, `--lr-tree-badge-danger-color`,
and `--lr-tree-badge-danger-bg`.

**Optional peer deps:** none.

The data model — icons, descriptions and badges live here:

```html
<lr-tree></lr-tree>
<script>
  document.querySelector("lr-tree").data = [
    {
      id: "1",
      label: "Root",
      description: "Two child documents",
      accessibleLabel: "Root, two child documents",
      icon: document.createTextNode("◇"),
      children: [
        { id: "1a", label: "Child A" },
        { id: "1b", label: "Child B", badges: [{ text: "3" }] },
      ],
    },
  ];
</script>
```

The declarative model — the same shape a renamed `wa-tree`/`sl-tree` subtree lands in, with no
`slot=` anywhere and no `data` assignment:

```html
<lr-tree label="Documents">
  <lr-tree-item label="Root" expanded>
    <lr-tree-item label="Child A"></lr-tree-item>
    <lr-tree-item label="Child B" disabled></lr-tree-item>
  </lr-tree-item>
</lr-tree>
```

**Known gotchas:**

- all four previously-known ARIA gaps in this pair are fixed: the treeitem row is now genuinely
  keyboard-operable with a roving tabindex and full arrow-key navigation (not just the expand/collapse
  button); the expanded-children `role="group"` is now a real DOM descendant of its `role="treeitem"`
  host rather than a shadow-DOM sibling; by-id reconciliation (preserving `expanded` state across
  data reassignment) now applies at every depth via a keyed `repeat()`, not just depth 0; and
  `role="tree"` now has an accessible name via the new `label` property.
- `lr-tree`'s `getUpdateComplete()` cascades through owner-controlled descendants
  `<lr-tree-item>`'s own `updateComplete` (see `update-cascade.ts`) so that code awaiting the
  tree's `updateComplete` does not run before a reachable nested node has finished rendering its
  roving `tabIndex`. The same 64-level/1,000-node work bounds apply to context, focus, selection,
  and disclosure walks.
- row enrichment is intentionally structured rather than an unrestricted renderer: use `icon`,
  `label`, `description`, `badges`, and `accessibleLabel`. This keeps the host as the single
  `role="treeitem"` interaction target and preserves the APG keyboard model.
- `lr-file-tree` does **not** forward `reorderable`, and deliberately so: its `LyraTreeNodeData[]` is derived
  from `nodes` on every render and keyed by filesystem path, an order it does not own.
- in the declarative model, appending a child while the parent is collapsed still registers: a
  `childList` MutationObserver assigns the `children` slot and requests an update, because
  `slotchange` alone cannot see a child added to a slot that is not currently rendered. Editing a
  label in place is picked up the same way.
- a declarative row whose default slot holds only whitespace around its nested items still shows the
  `label` attribute — indentation does not count as slotted label content, which is what makes the
  common `<lr-tree-item label="…">` + nested-children shape render its label.

---

## `lr-flow-canvas`

A pannable/zoomable DAG workflow canvas: positions HTML node cards, draws SVG edges between their
handles, runs a shared layered auto-layout for unpositioned nodes, and owns all selection/drag/
connect interaction. It is readonly by default; opt into editor gestures with `nodes-draggable`,
`connectable`, and `droppable`. The component snapshots model inputs instead of retaining mutable
caller aliases, and reports edit intent for the host to apply.

Input/output handle IDs are reserved only after their complete handle record is admitted; unreadable
optional labels cannot suppress a later valid handle with the same ID.

Horizontal RTL reflects the coordinate plane while authored cards, generated `lr-flow-node` cards,
native portable fallback cards and SVG edge labels retain readable content. Explicit physical model
coordinates remain unchanged.

Flow records and companion payloads are readonly public contracts. Consumers that need the types
without registering a component can import them from the side-effect-free module:

```ts
import type {
  FlowEdge,
  FlowHandle,
  FlowLayoutChangeDetail,
  FlowNode,
  FlowRunDecoration,
  FlowRunDecorations,
  FlowStructureSnapshot,
} from "@aceshooting/lyra-ui/components/data/flow-canvas/flow-types.js";
```

**Properties:**

- `nodes: readonly FlowNode[] = []` (attribute: false) — each record has readonly `id`, optional
  `type`, `position`, `data`, `accessibleLabel`, `inputs`, `outputs`, and `disabled`. A missing
  `position` opts into layered layout. String `data.label` and `data.description` feed the
  declarative fallback card. Assignment takes a detached, deeply frozen snapshot of plain
  arrays/records, omitting blank ids and later duplicates first-wins before layout, focus,
  selection, gestures, companion snapshots, and events. At most the first 10,000 source nodes are
  retained, with finite nested depth/entry budgets; reassign `nodes` after changes. Replacing the
  model cancels node-drag and connect gestures whose ids belonged to the old model and silently
  prunes selected ids that no longer exist. `disabled` marks a node non-actionable: it keeps its
  position and card content but cannot be selected/activated by click or keyboard, roving-tabindex
  navigation (arrow keys, Home/End) steps past it, it cannot be dragged even while
  `nodes-draggable`, and it is excluded from starting or receiving a new connection while
  `connectable` (an edge already touching it is left alone). Omitted or `false` renders the node
  exactly as before this field existed.
- `edges: readonly FlowEdge[] = []` (attribute: false) — readonly `id`, `source`, `target`, optional
  handle ids, optional drawn `label`, and optional `tone: LyraVariant`. The canonical brand value is
  `brand`; the former `accent` value and `FlowEdgeTone` alias are not part of this contract. Blank
  ids and later duplicates are omitted first-wins before render, focus, selection, gestures,
  companion snapshots, and events. At most the first 10,000 source edges are retained, with finite
  nested depth/entry budgets; reassign `edges` after changes. Dangling endpoint references remain
  visible through the component's documented fail-closed edge-list/stub paths.
- `orientation: 'horizontal' | 'vertical' = 'horizontal'` (reflected) — downstream layout/handle axis
- `nodesDraggable: boolean = false` (attribute `nodes-draggable`)
- `connectable: boolean = false`
- `droppable: boolean = false` — accepts drops carrying the `FLOW_PALETTE_MIME_TYPE` payload a
  `lr-node-palette` drag sets, emitting `lr-node-add`. The decoded payload must be a plain record
  with a non-empty string `type`; text fields and total payload size are bounded.
- `locked: boolean = false` (reflected) — freezes pan/zoom/drag/connect without touching the other
  gesture flags. Enabling it during a pan, node drag, pointer/keyboard connection, or palette drop
  cancels the active preview, rolls pan/node geometry back, clears transient state, and retires the
  window pointer listeners so a later release cannot commit.
- `selectedNodeIds: readonly string[] = []`, `selectedEdgeIds: readonly string[] = []` (attribute:
  false) — seed or replace selection. Each assignment snapshots at most the first 10,000 ids,
  omits blank/later duplicates first-wins, and prunes identities absent from the current canonical
  node/edge model. Reassign after changes. Activation and clear-selection gestures update frozen
  arrays before emitting `lr-selection-change`; model shrinkage prunes stale ids without claiming
  a user selection gesture occurred.
- `minZoom: number = 0.25` (attribute `min-zoom`), `maxZoom: number = 2` (attribute `max-zoom`)
- `grid: number = 8` — snap step in content px for drags/nudges/drop positions (`0` disables
  snapping); also the dotted background's base spacing
- `layerGap: number = 64` (attribute `layer-gap`), `nodeGap: number = 24` (attribute `node-gap`) —
  auto-layout layer/sibling spacing. The canvas measures rendered cards in layout space before its
  first pass; live changes to orientation, gaps, or card size trigger a new pass.
- `decorations: FlowRunDecorations | null = null` (attribute: false) —
  `Record<nodeOrEdgeId, FlowRunDecoration>`, where `FlowRunDecoration` has `status` plus optional
  `progress`, `durationMs`, and `detail`; assignment is detached, deeply frozen, bounded to 10,000
  keys plus finite nested depth/entry budgets, and invalid statuses and records with unreadable `status`, `progress`, `durationMs` or `detail` fields are omitted independently, retaining valid neighbors. Reassign the
  record after changes. Usually supplied by `lr-flow-run-status`.
- `accessibleLabel: string | null = null` (attribute `aria-label`)
- `viewport` (readonly getter) — a frozen `{ x, y, zoom }` snapshot

**Methods:** `setViewport({ x, y, zoom })`, `zoomIn()`, `zoomOut()`, `resetZoom()`,
`fit(options?: { padding?: number })` (frames every node), `focusNode(id, options?: { zoom? })`
(pans/zooms to one node and moves roving focus onto it), `toContentPoint(clientX, clientY)` (maps a
pointer position to content coordinates, RTL-aware), `registerCompanion(cb: (snapshot:
FlowStructureSnapshot) => void): () => void` — the subscription `lr-flow-minimap` uses to read
live node/edge/viewport geometry without this canvas ever importing the minimap.
All viewport-mutating methods, including `focusNode()`, are inert while `locked`; coordinate mapping
and companion subscription remain available because neither mutates viewport or edit state.
Each companion observer receives its own deeply frozen `FlowStructureSnapshot`: readonly node and
edge geometry/status arrays, viewport `{ x, y, zoom, width, height, minZoom, maxZoom }`, and the
effective `locked`, `orientation`, `layerGap`, and `nodeGap`. Zoom bounds are finite, positive, and
sorted even when public inputs are invalid or reversed.

**Events:** `lr-node-activate` (`detail: { nodeId }`), `lr-edge-activate` (`detail: { edgeId, source, target
}`), `lr-selection-change` (`detail: { nodeIds, edgeIds }`), `lr-node-move` (`detail: { nodeId,
position, previous }`), `lr-connect` (`detail: { source, target, sourceHandle, targetHandle }`),
`lr-node-add` (`detail: { type, position }`, from a palette drop), `lr-selection-delete`
(`detail: { nodeIds, edgeIds }`), `lr-viewport-change` (`detail: { x, y, zoom }`),
`lr-layout-change` (`detail: { positions, truncated }`, fired after an auto-layout pass places
previously unpositioned nodes). Every detail and nested coordinate/array is readonly and frozen.

**Slots:** default (consumer-authored cards matched by `node-id` and assigned to generated
`node-{id}` slots), `top-start`, `top-end`, `bottom-start`, `bottom-end`. Each node always has a
declarative shadow-DOM fallback card, so SSR and hydration do not depend on imperative light-DOM
card creation. An authored card replaces only its matching fallback; unmatched cards are unslotted
with a warning. Opposite-side companion slots share wrapping rails in narrow allocations.

**CSS parts:** `base`, `viewport`, `background`, `edges`, `edge`, `edge-label`, `edge-hit-area`,
`arrowhead`, `stub`
(a dangling-edge stub line), `connection-line` (in-progress connect gesture), `node`, `empty`,
`node-control` (the native per-node roving/activation control), `live-region`, `edge-list` (a
visually hidden list only for dangling/unrenderable edges), `layout-limit` (a visible notice whose
announcement uses the shared light-DOM polite sink), `overlay-rail`, and the
fallback-card parts `node-card`, `node-card-base`, `node-card-surface`, `node-card-header`,
`node-card-heading`, `node-card-status`, `node-card-progress`, `node-card-body`, `node-card-toolbar`,
`node-card-handle`, `node-card-handle-input`, and `node-card-handle-output`. A node whose `type`
normalizes to a safe part token also exposes `node-type-{value}`. A selected node wrapper carries
`data-selected`; its hidden `node-control` exposes the state as `aria-pressed`.

`live-region` is a visually hidden, `aria-hidden` mirror of the latest item/gesture message. The
actual messages are flushed to the document's shared light-DOM polite sink; mount is silent, and
identical repeated messages are appended as separate announcements.

**Themeable custom properties:** `--lr-canvas-reserved-height` (default
`var(--lr-size-24rem)`) controls the host's default block size and matches the pre-upgrade
reservation stylesheet; an explicit outer `block-size` still wins. `--lr-flow-canvas-grid-size`
(default: the finite `grid` property, or `8px`; dotted background spacing) can be set on the canvas
or a theme ancestor to override that property-derived fallback. Each edge tone colors its stroke
and the arrowhead marker it references:
`--lr-flow-canvas-edge-neutral-color` (default `var(--lr-color-border)`),
`--lr-flow-canvas-edge-brand-color` (default `var(--lr-color-brand)`),
`--lr-flow-canvas-edge-success-color` (default `var(--lr-color-success)`),
`--lr-flow-canvas-edge-warning-color` (default `var(--lr-color-warning)`), and
`--lr-flow-canvas-edge-danger-color` (default `var(--lr-color-danger)`).
`--lr-flow-canvas-connection-line-color` (default `var(--lr-color-brand)`) colors
`[part="connection-line"]`, the in-progress ghost path drawn while dragging a new connection from a
node's output handle, independent of a finished edge's own `-edge-*-color` tone above.
`--lr-flow-canvas-march-duration` (default
`var(--lr-duration-ambient)`, running-edge march animation duration; this is a time-only value, not
the `--lr-transition-ambient` duration/easing shorthand, because the animation supplies its own
`linear` timing function), and
`--lr-flow-canvas-node-selected-outline-color` (default `var(--lr-color-brand)`) controls the
selected-node outline. It is an inherited inline fallback, so it can be set on the canvas or a theme
ancestor without retinting the library-wide brand token. The same pattern applies to:
`--lr-flow-canvas-node-connect-invalid-outline-color` (default `var(--lr-color-danger)`) — outline of
a node that is an invalid connect-gesture drop target; `--lr-flow-canvas-node-connect-target-outline-color`
(default `var(--lr-color-brand)`) — outline of a node that is a valid connect-gesture drop target; and
`--lr-flow-canvas-drop-active-outline-color` (default `var(--lr-color-brand)`) — outline of the
viewport itself while a palette item is dragged over it (`droppable`). A fifth,
`--lr-flow-canvas-node-hover-outline-color` (default `var(--lr-color-border-strong)`) — the
mouse-hover preview of a node's own `:focus-visible` ring — exists for a different reason than the
four above. Set it to `transparent` to opt out of the hover treatment.

**Optional peer deps:** none.

```html
<lr-flow-canvas
  id="canvas"
  nodes-draggable
  connectable
  droppable
  style="height:480px"
>
  <lr-flow-controls slot="bottom-start" for="canvas"></lr-flow-controls>
  <lr-flow-minimap slot="bottom-end" for="canvas"></lr-flow-minimap>
  <lr-flow-run-status slot="top-start" for="canvas"></lr-flow-run-status>
</lr-flow-canvas>
<script>
  const canvas = document.getElementById("canvas");
  canvas.nodes = [
    { id: "a", data: { label: "Fetch" } },
    { id: "b", data: { label: "Transform" } },
  ];
  canvas.edges = [{ id: "a-b", source: "a", target: "b" }];
  canvas.addEventListener("lr-node-move", (e) => {
    canvas.nodes = canvas.nodes.map((n) =>
      n.id === e.detail.nodeId ? { ...n, position: e.detail.position } : n
    );
  });
</script>
```

**Known gotchas:**

- `nodes` and `edges` are controlled inputs: move, connect, add, and delete events are requests the
  host applies back. Selection is hybrid state: `selectedNodeIds`/`selectedEdgeIds` accept external
  replacement, while node/edge activation and clear-selection gestures update them internally and
  emit `lr-selection-change`.
- Auto-layout (via the dependency-free `layeredLayout()` util) only ever positions nodes that are
  missing an explicit `position`; a node the host has already positioned is left exactly where it is
  and, when its resolved center is nonnegative and within the safe-integer range, is used as a fixed
  anchor for the rest of the layout pass. Negative and larger finite coordinates remain rendered
  and caller-controlled but are omitted from the bounded utility's fixed-anchor input. The utility
  bounds virtual ordering work. If that ceiling is reached, the canvas renders a localized `layout-limit` status and sets
  `lr-layout-change.detail.truncated` to `true`; positions remain usable. Call the public utility
  directly with `maxVirtualWaypoints` when an application needs a different work ceiling.
- `droppable` only accepts drags carrying the exact `FLOW_PALETTE_MIME_TYPE` MIME type a
  `lr-node-palette` drag sets — the two components can never disagree on the payload shape because
  they share one exported constant.
- Pan/drag/zoom track the pointer's physical direction; under an RTL ancestor the pan and node-drag
  deltas are mirrored so content still visually follows the cursor, matching every other
  RTL-mirrored surface in this library.

**Additional API surface:**

- `part="edge-hit-area"` — The transparent wide pointer target behind an edge.
- `part="node-control"` — The visually hidden, roving selection button for a node.
- `--lr-flow-canvas-node-selected-outline-color` — Outline color of a selected node. Default: `var(--lr-color-brand)`.
- `--lr-flow-canvas-node-disabled-opacity` — Opacity of a node whose `FlowNode` entry sets
  `disabled`. Default: `var(--lr-opacity-disabled)`.

---

## `lr-flow-node`

The card a workflow node renders as: header/body/toolbar chrome, tool-lifecycle status tones, and
the named connection-handle elements edges anchor to. Used as `lr-flow-canvas`'s default card and
as a slotted override; also renders standalone (palette previews, docs). Purely presentational —
activation, selection, movement, and connection are all `lr-flow-canvas` events; this component
owns none of that.

**Properties:**

- `nodeId: string = ''` (attribute `node-id`, reflected) — identity used to match an authored card
  to a canvas node; the empty default leaves the attribute absent
- `flowType: string = ''` (attribute `data-node-type`, reflected) — consumer taxonomy forwarded by
  the canvas; use this stable hook or the canvas's normalized `node-type-*` part for type-specific
  presentation
- `heading: string = ''`
- `status: 'pending' | 'running' | 'success' | 'error' | 'denied' | null = null` (reflected)
- `progress: number | null = null` — renders a determinate `[part="progress"]` bar when set
- `statusDetail: string = ''` (attribute `status-detail`) — appended to the status line
- `durationMs: number | null = null` (attribute `duration-ms`) — formatted into the status line
- `selected: boolean = false` (reflected)
- `compact: boolean = false` (reflected) — tighter card padding for dense canvases and palette
  previews; the border, background, shadow and the `selected`/`status="running"` treatments all stay
- `inputs: readonly FlowHandle[] = [{ id: 'in' }]`, `outputs: readonly FlowHandle[] = [{ id: 'out'
}]` (attribute: false) — detached, frozen snapshots of at most the first 10,000 readonly
  `{ id, label? }` handles; blank ids and later duplicates are omitted first-valid/first-wins
  (a record rejected for an unreadable optional label does not reserve its ID);
  reassign a collection after changes
- `orientation: 'horizontal' | 'vertical' = 'horizontal'` (reflected) — which physical edge handles
  render on; mirrors the adopting canvas's own `orientation`

**Events:** none — purely presentational, activation/drag/connect all live on `lr-flow-canvas`.

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

**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`,
`heading`, `status` (never color-only — always paired with text), `progress`, `body`, `toolbar`,
`handle` (every handle dot), `handle-input`, `handle-output`.

**Themeable custom properties:** `--lr-flow-node-min-inline-size` (default `11rem`),
`--lr-flow-node-compact-padding` (default `var(--lr-space-xs)`) and `--lr-flow-node-compact-gap`
(default `var(--lr-space-2xs)`) — `[part="card"]`'s padding and row gap while `compact` — and
`--lr-flow-node-selected-outline-color` (default `var(--lr-color-brand)`) — the card's outline color
while `selected`. Like the other state-scoped custom properties here, it is an inline `var()`
fallback at its point of use rather than a `:host` declaration, so it can be set on the element _or any
ancestor_ (a canvas retunes every card at once); overriding the selection color otherwise means
hijacking the library-wide `--lr-color-brand` token and repainting everything else that reads it.
`--lr-flow-node-running-border` (default `var(--lr-color-brand)`) — the card's border color while
`status="running"`, independent of `--lr-flow-node-selected-outline-color` so a consumer can retint
just one of the two states without the other following along — and `--lr-flow-node-running-glow` (default
`var(--lr-color-brand-quiet)`) — the box-shadow color of the running-state ring around the card, and
the pulse keyframes' peak color. The status dot uses the shared
`--lr-flow-status-{pending|running|success|error|denied}-color` hooks, defaulting respectively
to border-strong, brand, success, danger, and warning; `--lr-flow-status-color` is the no-status
fallback. The explicit status hooks are `--lr-flow-status-pending-color`,
`--lr-flow-status-running-color`, `--lr-flow-status-success-color`,
`--lr-flow-status-error-color`, and `--lr-flow-status-denied-color`.
`--lr-flow-node-progress-track-color` (default
`var(--lr-color-border)`) and `--lr-flow-node-progress-fill-color` (default
`var(--lr-color-brand)`) independently retint the determinate progress track and fill. All of
these hooks inherit, so one canvas-level override can retint every descendant node without
changing a library-wide semantic token.

**Optional peer deps:** none.

```html
<lr-flow-node
  node-id="a"
  heading="Fetch"
  status="running"
  progress="40"
></lr-flow-node>
```

**Known gotchas:**

- A running node's card pulses (`?data-pulse`) unless `prefers-reduced-motion` is set — the same
  reduced-motion exception every animated surface in this library follows.
- `status` drives a status chip with a localized label plus `statusDetail`/`durationMs`, never a
  color-only indicator.
- All card chrome lives on `[part="card"]`, not `[part="base"]` — `base` is only the flex row that
  holds the input handles, the card and the output handles. Style the box through `::part(card)`.
- Empty `header`, body, and toolbar rows are removed from layout and update when slot contents are
  added or removed. A populated toolbar remains visible on coarse-pointer/no-hover devices rather
  than depending on an unavailable hover gesture. Invalid status/orientation inputs normalize to
  the documented canonical values.
- Selection uses an outline, while the running lifecycle uses its own border and glow; the two
  remain simultaneously visible.
- `--lr-flow-node-min-inline-size` was previously overridden by a duplicate declaration and had no
  effect. It now sets the card's minimum inline size again, so a node that was relying on the card
  collapsing below `11rem` will render wider than it used to.

---

## `lr-flow-minimap`

A corner overview map of a `lr-flow-canvas`: scaled node rectangles plus a draggable viewport
rectangle, for orientation and fast navigation on canvases larger than the screen. Draws no edges
(nodes only, matching the React Flow/n8n minimap convention) and never reads `nodes` itself —
geometry always comes from the canvas's `registerCompanion()` snapshots, so the two can never
disagree.

**Properties:**

- `for: string = ''` — id of the target `lr-flow-canvas`; when empty, the nearest ancestor canvas
  is used (the slotted-into-a-corner-slot case, the primary wiring)
- `label: string = ''` — accessible name for the map region. A host `aria-label` takes precedence,
  followed by `label`, then the localized default
- `frame: 'card' | 'plain' = 'card'` (reflected) — container treatment, on the library-wide `frame`
  vocabulary. `'plain'` removes `[part="base"]`'s border, background and corner radius, for a
  minimap placed in a host panel or toolbar that already draws its own surface, so the frame isn't
  doubled. The map's own hover/click affordances and the viewport rect stay either way — only the
  outer `base` decoration goes. Mirrors `lr-flow-controls`'/`lr-flow-run-status`'s identical `frame`.

**Events:** none.

**Slots:** none.

**CSS parts:** `base` (the root wrapper; drops its border, background and corner radius under
`frame="plain"`), `map` (the scaled SVG), `node` (one rect per node), `viewport` (the
exact visible view rectangle), `viewport-hit-area` (the transparent draggable/focusable target),
`instructions` (visually hidden keyboard help), and `live-region` (the `aria-hidden` mirror of the
latest viewport-change text).

**Themeable custom properties:** `--lr-flow-minimap-inline-size` (default `12rem`),
`--lr-flow-minimap-block-size` (default `8rem`), plus the shared
`--lr-flow-status-color` and the explicit palette hooks
`--lr-flow-status-pending-color`, `--lr-flow-status-running-color`,
`--lr-flow-status-success-color`, `--lr-flow-status-error-color`, and
`--lr-flow-status-denied-color`.
`--lr-flow-minimap-viewport-color` (default `var(--lr-color-brand)`) colors `[part="viewport"]`'s
fill (mixed 15% into transparent) and stroke, independent of every per-status node fill above.
`--lr-flow-minimap-viewport-min-size` (default `var(--lr-icon-button-size)`, normally 40px) floors
only the transparent `viewport-hit-area` along each axis. The visible `viewport` remains the exact
viewport-to-content ratio. The token inherits from ancestors; set it to `0` to opt out.

**Optional peer deps:** none.

```html
<lr-flow-canvas id="canvas" style="height:480px">
  <lr-flow-minimap slot="bottom-end" for="canvas"></lr-flow-minimap>
</lr-flow-canvas>
```

**Known gotchas:**

- Never resolves `nodes`/`edges` on its own — it subscribes to `registerCompanion()` and repaints
  from whatever snapshot the canvas last pushed, so it can only ever show what the canvas itself
  currently renders.
- A locked snapshot makes the hit area unfocusable and inert: no pointer, click, wheel, or keyboard
  shortcut can mutate the canvas.
- Dragging the viewport rectangle calls the canvas's `setViewport()` directly; there's no separate
  event to wire up. A completed drag consumes only the browser-synthesized click following its
  `pointerup`; a canceled or lost-capture drag leaves the next genuine map click available for
  click-to-center navigation.
- On a canvas whose node bounds dwarf the visible viewport — the case the minimap exists for — the
  raw viewport rectangle can collapse to a couple of pixels. The separate transparent hit area is
  floored and grown symmetrically around the exact visible rectangle; keyboard and drag math still
  read the canvas viewport directly.

**Additional API surface:**

- `part="instructions"` — Visually hidden keyboard instructions for the viewport.
- `part="live-region"` — Visually hidden, `aria-hidden` mirror of the latest viewport-change text.
  The initial companion snapshot is silent. Keyboard, map-click, and wheel viewport changes append
  their next rAF-coalesced snapshot to the document's shared light-DOM polite sink; a completed
  viewport drag appends its final position once, while canceled/lost-capture drags remain silent.
  Repeated identical snapshots are still separate additions.

---

## `lr-flow-controls`

The canvas's button cluster: zoom in/out, fit, and interaction lock, so every flow surface ships the
same affordances without hosts rebuilding them. Manipulates only view state, never `nodes`/`edges` —
no editing commands live here. Zoom-in/out disabled state reads the canvas snapshot's effective
finite, sorted bounds, so invalid or reversed raw `minZoom`/`maxZoom` values cannot disable an
otherwise available direction.

**Properties:**

- `for: string = ''` — id of the target `lr-flow-canvas`; empty resolves to the nearest ancestor
- `orientation: 'vertical' | 'horizontal' = 'vertical'` (reflected) — button-cluster layout axis
- `hideLock: boolean = false` (attribute `hide-lock`) — omits the lock/unlock toggle button
- `frame: 'card' | 'plain' = 'card'` (reflected) — container treatment, on the library-wide `frame`
  vocabulary. `'plain'` drops `[part="base"]`'s border, background, padding, corner radius and its
  floating-surface `box-shadow`, for a cluster placed in a host toolbar or panel that already draws
  its own surface. There is deliberately no `compact`: the padding is already the smallest spacing
  step and the only remaining room is the buttons' `--lr-icon-button-size` hit-area floor. The
  canonical type is `LyraFrame`; the former component-local appearance alias is removed.

**Events:** none dispatched directly — each button calls the resolved canvas's own `zoomIn()`/
`zoomOut()`/`fit()`, or toggles its `locked` property.

**Slots:** default — extra host buttons appended to the cluster, styled by the same group. A slotted
`<button>` is matched by a `::slotted(button)` rule that gives it the built-in controls' treatment:
the shared `--lr-icon-button-size` hit-area floor, the chrome-less transparent box, and the same
hover/press/disabled/focus-visible affordances. Only the slotted element itself is styled — markup
the consumer nests inside it is left alone — so an icon or label child keeps whatever the host
page gives it.

**CSS parts:** `base` (the `role="group"` wrapper; drops its floating-surface chrome under
`frame="plain"`), `zoom-in`, `zoom-out`, `fit`, `lock` (omitted when `hideLock`).

**Themeable custom properties:** `--lr-flow-controls-lock-active-color` (default
`var(--lr-color-brand)`, pressed lock-button foreground), plus shared tokens —
`--lr-icon-button-size` (each button's minimum hit area, unchanged by `frame`), `--lr-shadow-m`,
`--lr-color-surface`, `--lr-color-border`, `--lr-radius`, `--lr-space-2xs`,
`--lr-focus-ring-width`/`-color`/`-offset`.

**Optional peer deps:** none.

```html
<lr-flow-canvas id="canvas" style="height:480px">
  <lr-flow-controls slot="bottom-start" for="canvas"></lr-flow-controls>
</lr-flow-canvas>
```

**Known gotchas:**

- `for` resolution is identical across all three companions: a non-empty `for` is strict and never
  falls back; only an empty `for` chooses the nearest ancestor. Id changes, target replacement, and
  a canvas that upgrades after the companion are observed in the companion's own document/root.
  Wrong-tag or wrong-capability targets fail closed.
- `frame="plain"` drops the `box-shadow` along with the border and background — unlike most
  `plain` escapes in this library, which only reset the border/background/padding/radius. A lift
  shadow with no surface under it reads as a stray smudge, so the whole floating-surface treatment
  goes together (same as `lr-flow-run-status`'s `plain`).
- Under a narrow allocation the group wraps without overflowing, while each button retains the
  shared hit-area floor.

---

## `lr-flow-run-status`

Execution-state presentation for a `lr-flow-canvas`: pushes a `FlowRunDecorations` map into the
resolved canvas (the canvas itself renders the node/edge paint) and renders a compact run-summary
strip. Summary/count text and slotted host chrome wrap within narrow allocations. Does not execute,
poll, or time anything — pure pushed state; `durationMs` is host-computed.

**Properties:**

- `for: string = ''` — id of the target `lr-flow-canvas`; empty resolves to the nearest ancestor
- `decorations: FlowRunDecorations = {}` (attribute: false) — a detached, deeply frozen readonly
  record bounded to 10,000 keys plus finite nested depth/entry budgets and pushed onto the resolved
  canvas; invalid statuses and records with unreadable `status`, `progress`, `durationMs` or `detail` fields are omitted independently, retaining valid neighbors, and consumers reassign the record after changes
- `hideSummary: boolean = false` (attribute `hide-summary`) — omits the "{done} of {total} steps
  complete" strip, keeping only the decoration push
- `label: string = ''` — accessible name for the summary strip
- `frame: 'card'|'plain' = 'card'` (reflected) — container treatment, on the library-wide `frame`
  vocabulary. `'plain'` removes the border, background, shadow, padding and radius, so a summary
  strip dropped straight into a host toolbar that already draws its own frame does not double it.
  `'card'` is the standalone floating-strip presentation. The canonical type is `LyraFrame`; there
  is no component-local appearance alias.

**Events:** none dispatched directly.

**Slots:** default — extra host chrome appended to the strip (e.g. a cancel button or a usage
badge).

**CSS parts:** `base`, `summary` (the "{done} of {total} steps complete" line), `count` (one per
status present, text + tone dot, never color-only), `live-region` (a visually-hidden, `aria-hidden`
mirror of the last step-transition announcement).

`live-region` carries no live-region role of its own — it is a styling and inspection surface. The
announcement itself goes to the library's shared **light-DOM** polite region, appended to the
consumer's `<body>` and marked `data-lr-live-region="polite"`, because a live region inside a
shadow root is not reliably announced (JAWS with Firefox ignores one outright). Assert against that
document-level region rather than `::part(live-region)`.

**Themeable custom properties:** shared `--lr-flow-status-color` and the explicit
`--lr-flow-status-pending-color`, `--lr-flow-status-running-color`,
`--lr-flow-status-success-color`, `--lr-flow-status-error-color`, and
`--lr-flow-status-denied-color` hooks, also consumed by `lr-flow-node` and `lr-flow-minimap`.
Set the palette on a canvas/theme ancestor to keep all three presentations in sync.

**Optional peer deps:** none.

```html
<lr-flow-canvas id="canvas" style="height:480px">
  <lr-flow-run-status slot="top-start" for="canvas"></lr-flow-run-status>
</lr-flow-canvas>
<script>
  document.querySelector("lr-flow-run-status").decorations = {
    a: { status: "success", durationMs: 820 },
    b: { status: "running", progress: 40 },
  };
</script>
```

**Known gotchas:**

- Purely a pushed-state conduit: it never starts, stops, or times a run itself — the host recomputes
  `decorations` (including `durationMs`) on whatever cadence its own execution engine ticks at.
- `for` resolution matches `lr-flow-minimap`/`lr-flow-controls`.
- The public identity is `lr-flow-run-status` / `LyraFlowRunStatus`. The former overlay name is
  removed rather than retained as a second runtime tag or public type.

---

## `lr-context-meter`

A segmented occupancy meter (bar or ring) for showing how a fixed capacity — a model's context
window, a token budget, any consumable quota — is divided across labeled categories. First-party
invention (no Web Awesome equivalent). Pure data visualization: it renders `segments`/`total` exactly
as given and never computes token counts, costs, or any other domain-specific estimate itself — the
one exception is the plain arithmetic sum of segment values used to build the accessible "X of Y
used" summary.

**Properties:**

- `segments: ContextMeterSegment[] = []` (attribute: false, JS-only) — `{ label: string; value:
number; tone?: 'brand' | 'success' | 'warning' | 'danger' | 'neutral'; color?: string; disabled?:
boolean }[]`. `value` is an _absolute_
  quantity measured against `total`, never a pre-computed percentage.
  `color`, when supplied, is a sanitized arbitrary CSS color that takes precedence over `tone`.
  `disabled`, when set, marks that band non-actionable while `interactive` is set: its control
  renders genuinely disabled (no tab stop, no hover/press affordance) and activating it emits no
  `lr-segment-activate`.
- `total: number = 0` — the full capacity segments are measured against (e.g. a model's context
  window size).
- `shape: ContextMeterShape = 'bar'` (`'bar' | 'ring'`, reflected) — the v9 geometry name;
  `variant` remains reserved for semantic tone across Lyra.
- `label: string = ''` — overall accessible caption, e.g. `"128K context window"`. Also rendered
  visually (`[part="label"]`) when set.
- `showLegend: boolean = false` (attribute `show-legend`, reflected) — renders a static
  `[part="legend"]` key below the meter, one swatch/label pair per `segments` entry, each swatch
  painted from that segment's resolved `color`/`tone`. Without it a segment's own label is exposed
  only through a hover `title` (desktop-only, undiscoverable) and the visually-hidden breakdown
  list, so a meter split across more than two or three categories reads as unlabeled colour to a
  sighted user. Non-interactive: it toggles nothing and emits nothing, mirroring
  `lr-sequence-strip`'s `showLegend` rather than the interactive `lr-graph-legend`. The whole
  subtree is `aria-hidden`, since `segment-list` already exposes the same names. Under
  `shape="ring"` the host stops being a fixed square so the key flows below the ring instead of
  being clipped.
- `legendDisplay: ContextMeterLegendDisplay = 'label'` (attribute `legend-display`) — what each
  legend row shows beside its swatch: `'label'` (the default, byte-identical to before this
  property existed), `'label-value'`, `'label-percent'` or `'label-value-percent'`, adding
  `[part="legend-value"]` and `[part="legend-percent"]` spans. The share is the same clamped ratio
  the bar or ring paints, so the key can never disagree with the band it stands for, and both
  numbers are formatted through `effectiveLocale`. Combinable rather than mutually exclusive,
  unlike `lr-chart`'s `label | value | percentage` legend vocabulary, because a part-to-whole key is
  ordinarily read as "count AND share". A foreign attribute value normalizes to `'label'`. No
  effect while `showLegend` is unset.
- `interactive: boolean = false` (reflected) — opt-in filter mode. Every band, and every legend row,
  becomes a real `<button>` emitting the cancelable `lr-segment-activate`; the ring's arcs carry
  `role="button"` with their own tab stop and Enter/Space handling, since an SVG shape cannot be a
  native button. In this mode, and only in this mode, `[part="legend"]` drops `aria-hidden` so the
  rows are reachable, and the visually-hidden `[part="segment-list"]` steps aside because the
  buttons already expose the same label/count pairs with their pressed state attached. A band's
  inline size IS its share, so a small band is a small pointer target: pair `interactive` with
  `showLegend` where that matters, since the legend row is the same action at full row height. The
  ring's arcs share one bounding box, so a focused arc reports itself by dimming as well as by the
  shared focus outline — an outline alone cannot say *which* arc.
- `selectedIndices: readonly number[] = []` (attribute: false) — indexes rendered as
  `aria-pressed="true"` plus a `segment-selected`/`legend-item-selected` part token on both the band
  and its legend row; every other control renders `aria-pressed="false"`. Meaningful only while
  `interactive` is set. Uncontrolled by default: an activation nobody vetoes toggles the index here
  itself. `preventDefault()` on `lr-segment-activate` suppresses that write, which is how a consumer
  that owns the selection takes control; assigning the property directly always wins either way. A
  non-integer or out-of-range entry selects nothing rather than throwing.

Accessible summaries, segment tooltips, and ring titles format normalized nonnegative quantities
using `effectiveLocale`. A host `aria-label` names the host without being duplicated on the nested
meter owner, which retains its generated aggregate summary.

**Events:** `lr-segment-activate` — a band or its legend row was activated while `interactive` is
set. `detail: { index: number; label: string; value: number }`, bubbling and composed like every
library event. **Cancelable, and a real veto point**: the default action is this component toggling
`index` in its own `selectedIndices`, so `preventDefault()` keeps the current selection and hands
that state entirely to the consumer. Never emitted in the default presentational mode. Because the
event dispatches synchronously *before* the write, a listener reading `selectedIndices` inside its
own handler sees the pre-activation value.

**Slots:** none.

**CSS parts:** `base` (a `<div>` for `bar`, an `<svg>` for `ring`), `semantic` (the visually hidden
meter semantics), `track` (the unfilled/empty capacity), `segment` (one occupied segment — carries
`data-tone` and, for custom colors, `--lr-context-meter-segment-color`), `segment-list` (the hidden
category list), `segment-item` (one hidden category/value entry), `label`, and — only under
`showLegend` — `legend`, `legend-item`, `legend-swatch` (carrying the same `data-tone` and custom
color hook as `segment`) and `legend-label`, plus `legend-value` and `legend-percent` under the
matching `legendDisplay` settings. While `interactive` is set, `segment` and `legend-item` are
`<button>`s (a `role="button"` arc under `shape="ring"`) and a selected one carries a second part
token — `segment-selected` / `legend-item-selected` — because nothing but a pseudo-class may follow
`::part()`, so the state has to live in the part name. Two further state tokens join them, and they
compose: `segment-empty` / `legend-item-empty` on a band whose `value` is 0, and
`segment-disabled` / `legend-item-disabled` on a band whose `segments` entry sets `disabled`. The
empty pair is DERIVED and carries no built-in treatment — it is the hook for your own "nothing in
this bucket" styling, and a zero band stays actionable. The disabled pair is DECLARED: that control
renders genuinely disabled (no tab stop, no hover or press affordance) and activating it emits no
`lr-segment-activate`. Inertness is never inferred from a zero value, because a zero band is
legitimately clickable in a budget meter

**Themeable custom properties:** `--lr-context-meter-segment-color` is set per segment when its
`color` field is supplied, and is read by both `segment` and its matching `legend-swatch` so the
two can never disagree. `--lr-context-meter-legend-swatch-size` (default `var(--lr-size-0-625rem)`)
sizes a legend chip on both axes. The `bar`-shape track is independently retunable:
`--lr-context-meter-track-size` (default `var(--lr-size-0-5rem)`) is its block size (and so the
block size of its filled segments), `--lr-context-meter-track-radius` (default
`calc(var(--lr-radius) * 0.5)`) its corner radius, `--lr-context-meter-track-bg` (default
`color-mix(in srgb, var(--lr-color-border) 30%, transparent)`) the background of its unfilled
remainder, and `--lr-context-meter-segment-seam-color` (default `var(--lr-color-surface)`) the
hairline seam painted between adjacent segments.
`--lr-context-meter-selected-ring-color` (default `var(--lr-color-text)`) and
`--lr-context-meter-selected-ring-width` (default `var(--lr-border-width-thick)`) paint the inset
ring marking a selected `bar`-shape band or legend row. It is drawn inward, because the track clips
its own overflow and an outward ring would be invisible, and it is a ring rather than an outline so
that it composes with the hover, press and focus outlines instead of being replaced by them — a
selected band stays visibly selected exactly while it is being pointed at or focused, and its focus
ring stays intact. `--lr-context-meter-selected-arc-stroke` (default `16`, in this component's
`0 0 100 100` viewBox units) is the stroke width of a selected `ring`-shape arc: every arc shares
one bounding box, so a selected arc reports itself by thickening in place rather than by an outline
that would trace the whole ring identically for every selection.
`--lr-context-meter-disabled-opacity` (default `var(--lr-opacity-disabled)`) dims a band or legend row whose entry sets
`disabled`; the band keeps its own colour, since that colour is the datum. Otherwise the component consumes shared tokens
`--lr-space-xs`, `--lr-color-text-quiet`, `--lr-font`, `--lr-radius`, `--lr-color-border`,
`--lr-color-brand`, `--lr-color-success`, `--lr-color-warning`, `--lr-color-danger`,
`--lr-transition-base`.

**Optional peer deps:** none.

```html
<lr-context-meter label="128K context window" total="128000"></lr-context-meter>

<lr-context-meter shape="ring" total="128000"></lr-context-meter>
<script type="module">
  const [meter, ringMeter] = document.querySelectorAll("lr-context-meter");
  meter.segments = [
    { label: "System prompt", value: 2200, tone: "neutral" },
    { label: "Conversation history", value: 61000, tone: "brand" },
    { label: "Retrieved context", value: 30800, tone: "warning" },
  ];
  ringMeter.segments = segments;
</script>
```

An internal visually-hidden semantic node carries `role="meter"` plus `aria-valuenow`,
`aria-valuemin`, and `aria-valuemax` whenever `total > 0`; without a valid positive total it uses
`role="group"` and omits numeric meter attributes. Its accessible name is the generated summary;
an authored host `aria-label` remains on the host as a distinct overall name. A separate
visually-hidden segment list exposes
each labeled quantity, while the visible track, segments, ring SVG, and visible label remain
`aria-hidden`. The summary's "used" figure is the sum of
`segments[].value`, clamped to `total` whenever `total > 0` so the announced text can never claim
more than 100% used (e.g. `segments` summing to `150000` against `total="128000"` still announces
`"128,000 of 128,000 used"`) — matching what the _visual_ meter shows, since each segment's ratio is
independently clamped so the running cumulative fill across all segments can never exceed 100% of the
bar/ring either: an over-`total` `segments` array renders as a fully (not over-) filled meter, with
later segments truncated or squeezed to zero width/arc-length as the budget runs out. `total <= 0`
(or non-finite) renders zero segments — an empty track/ring — and the announced summary falls back to
just `"{used} used"` with no `"of {total}"` clause, regardless of what's in `segments`. Ring geometry
(a 40-radius circle, 12px stroke, centered at 50,50) intentionally matches `lr-gauge`'s own radial
numbers, so the two circular-meter components in the library share one visual scale.

**Known gotchas:**

- The ring variant's per-segment `<title>` and the bar variant's per-segment `title=` attribute are
  native mouse-hover tooltips only — they sit inside `aria-hidden` markup. Screen readers use the
  hidden meter/group summary and segment list instead.
- `shape="ring"` fixes the host at `8em × 8em` (`:host([shape='ring'])`) — the bar shape's
  `inline-size: 100%` does not apply in ring mode; resize it via `font-size` or an explicit
  width/height override on the host instead.
- Segment order is significant for the ring's cumulative `stroke-dashoffset` — later entries in
  `segments` render further around the circle (starting at 12 o'clock, going clockwise); there's no
  independent sort/z-order control.

**Additional API surface:**

- `part="segment-item"` — One visually-hidden segment label/count pair.
- `part="segment-list"` — The visually-hidden list exposing the segment breakdown.
- `part="semantic"` — The visually-hidden meter/group carrying aggregate range semantics.

---

## `lr-calendar`

Responsive month calendar with event markers and an agenda view.

Early ISO dates such as `0001`, `0099`, and `0100` retain their authored local year in the month
grid and month navigation. Valid colored agenda actions preserve their foreground/background pairing
through hover and press, with the existing state tokens remaining overridable. Arbitrary caller
colors still require the caller to choose an accessible contrast pair.

**Properties:**

- `events: CalendarEvent[] = []` (attribute: false) — `{ readonly id?, readonly date, readonly
title, readonly color?, readonly data? }`; `date` accepts an ISO `YYYY-MM-DD` string, finite epoch
  milliseconds, or a valid `Date`, then normalizes to the displayed ISO day. Invalid date/title rows
  are omitted; `lr-event-select.detail.event` remains the original admitted object. `color` is
  sanitized before use as the marker background. The former ignored `start`/`end` fields are not
  part of the contract; use one event per displayed date
- `value: string = ''` — the selected ISO date
- `viewDate: string` (attribute `view-date`, defaults to the 1st of the current month) — the visible
  month; an unparseable value falls back to the current month
- `view: CalendarView = 'month'`, where `CalendarView = 'month' | 'agenda'` (reflected) — agenda
  lists the effective visible month's events, date-sorted. Foreign tokens normalize and reflect to
  `month`
- `firstDayOfWeek: LyraCalendarFirstDayOfWeek = 'auto'` (attribute `first-day-of-week`) — which
  weekday the grid starts on. **Breaking in 10.0.0:** the default was a hardcoded `1` (Monday)
  regardless of locale; it now derives from the effective locale through the same
  `resolveFirstDayOfWeek()` contract `<lr-date-picker>`/`<lr-date-input>` already use, so an unset
  `<lr-calendar>` renders Sunday-first under `en-US` and Monday-first under `fr-FR` instead of
  disagreeing with a date picker on the same page. **Also breaking in 10.0.0:** the bare `0`–`6`
  integer form is gone; the value is now one of the shared weekday-name tokens (`'auto'`, then
  `'sun'` through `'sat'`), which pins the week start independent of locale. Pass `'mon'` to keep
  the pre-10.0.0 rendering.
- `accessibleLabel: string = ''` (attribute `aria-label`) — names the host. The nested calendar
  section retains the localized purpose name rather than duplicating an authored host name; when
  set programmatically without a host attribute, this value names the section

**Keyboard:** the month grid is a fixed 6×7 matrix (leading/trailing days of adjacent months fill it
out) with one roving tab stop — `focusedDate`, else `value`, else today, else the first rendered day.
Arrows move by 1 day (Left/Right swapped under RTL) or 7; stepping past the rendered grid rolls
`viewDate` to the target's month and emits `lr-view-change`. Enter/Space select.

**Events:** `lr-date-select` (`detail: { date }`), `lr-event-select` (`detail: { event }`),
`lr-view-change` (`detail: { viewDate }`, from the prev/next buttons and out-of-grid arrow moves).

**Slots:** none.

**CSS parts:** `header` and `navigation` are aliases on the header wrapper; `nav` is shared by both
month-navigation buttons; `previous-button` and `next-button` identify each direct button;
`nav-glyph` is the chevron (`scaleX(-1)`-mirrored under RTL); `title`, `weekdays`, `weekday`,
`grid`, `week` (`display: contents`), `day`, `date`, `event` (a month-view marker), `agenda`, and
`agenda-event`.

**Themeable custom properties:** `--lr-calendar-day-min-block-size` (default `var(--lr-size-6rem)`)
and `--lr-calendar-day-min-block-size-narrow` (default `var(--lr-size-4rem)`, applied at container inline-size
≤ 28rem); `--lr-calendar-day-selected-bg` (default `var(--lr-color-brand-quiet)`) for a selected
day's background; `--lr-calendar-day-outside-color` (default `var(--lr-color-text-quiet)`) and
`--lr-calendar-day-outside-bg` (default `var(--lr-color-surface)`) for adjacent-month days; and
`--lr-calendar-day-today-outline-color` (default `var(--lr-color-brand)`) for today's outline.
`--lr-calendar-nav-hover-bg`, `--lr-calendar-nav-active-bg`, `--lr-calendar-day-hover-bg`,
`--lr-calendar-day-active-bg`, `--lr-calendar-agenda-event-hover-bg`, and
`--lr-calendar-agenda-event-active-bg` independently theme navigation, day, and agenda-event
hover/pressed states through inheritable inline fallbacks.
These state hooks use inline fallbacks at their paint rules, so an application theme can set them
on an ancestor. They keep persistent selection, outside-month chrome, and today's outline
independent from shared tokens that also drive unrelated component states.

Month-view `[part='event']` markers are real keyboard-focusable buttons inside a non-interactive
`role="gridcell"` day container; Enter/Space activates the same `lr-event-select` path as a pointer.
Their target stays at least 24×24 CSS px even in the narrow month layout. Agenda view likewise
renders each event as a `<button part="agenda-event">`.

## `lr-timeline` and `lr-timeline-item`

Read-only chronological sequence by default. `lr-timeline` is a `role="list"` flex container; each
`lr-timeline-item` is a light-DOM child that sets `role="listitem"` on itself and renders its own
marker plus the trailing rail segment reaching toward the next item's marker. The last item's rail is
suppressed purely in CSS (`::slotted([role='listitem']:last-child)`) — no JS coordination anywhere.
Items have no keyboard navigation or selection model: a passive record display, by design (an
item's `title`/`description` routinely hold focusable content, so wrapping the row in `role="button"`
would trip `nested-interactive`). The opt-in clustered time scale adds only native count-marker
buttons; it does not make the individual rows interactive.

Horizontal time layouts using `collision="overlap"` or `collision="stack"` allocate their block size
from the actual item content and lane offsets. The height follows content growth, shrinkage, and
changes in lane count. `--lr-timeline-time-extent` still controls only the main-axis distance, and
horizontal scrolling retains clipping on the cross axis. Cluster mode keeps its existing sizing
behavior.

**`lr-timeline` properties:** `orientation: 'vertical' | 'horizontal' = 'vertical'` — note the
opposite default from `lr-stepper`; `horizontal` makes `[part='base']` a horizontally scrollable row.
`accessibleLabel?: string` (attribute `aria-label`) overrides the localized `"Timeline"` name —
omitting it reads back `undefined` and falls back to that default, while an explicitly empty
`aria-label` stays empty
(the `role="list"` element is in the shadow root and never inherits a host attribute). Read-only
`itemCount: number` is the live count of default-slot `<lr-timeline-item>` assignments (including
flattened forwarding slots); unrelated slotted elements and text nodes are ignored.
`scale: 'flow' | 'time' = 'flow'` (attribute `scale`, type `LyraTimelineScale`) chooses how items
are distributed along the main axis. `'flow'` is the default even sequence, where `timestamp` is
rendered as text but carries no positional meaning. `'time'` positions each item at its true
proportion of the range, so a gap of weeks and a gap of decades stop looking identical. `'time'`
needs a definite extent to distribute along — `--lr-timeline-time-extent` (default
`var(--lr-size-20rem)`), applied as `block-size` when vertical and `inline-size` when horizontal —
because items are absolutely positioned and a percentage against an auto-sized track resolves to
zero. `collision: 'overlap' | 'stack' | 'cluster' = 'overlap'` (attribute `collision`, type
`LyraTimelineCollision`) chooses what `scale="time"` does with items landing on nearly the same
position: `'overlap'` leaves them stacked on one another, `'stack'` steps each colliding item one
lane along the **cross** axis (indent per lane: `--lr-timeline-collision-offset`, default
`var(--lr-space-l)`), and `'cluster'` replaces every group of at least two colliding items with one
count marker. The group's first member in author order becomes its representative and renders the
button in that item's existing list/Tab position; the remaining members are hidden, so visual,
semantic, and keyboard order do not diverge merely because clustering is enabled. Stack mode and
the cluster floor treat items within 1.5% of the axis as colliding.
Cluster mode widens that floor to the rendered count action's footprint on the currently allocated
axis, then reclusters when the allocation or rendered action size changes, so interactive marker
hit areas do not overlap.
Cluster windows are bounded from their first sorted position rather than transitively chaining every
dense neighbour, so a large history becomes a useful sequence of markers rather than one axis-wide
cluster. An isolated item remains an ordinary timeline item. Activating a count marker is a
notification only; it never expands or selects items internally.
`rangeStart` / `rangeEnd` (`Date | string | number`, attribute: false) pin the axis instead of
deriving it from the earliest/latest item; a reversed or non-finite pair falls back to the derived
range. An item with no parseable `timestamp` (including one supplied only through the `timestamp`
slot, which carries no machine-readable instant) keeps document order and is spread evenly, so a
partially-timestamped list degrades rather than stacking at the origin. Reassigning an item's
`timestamp` reclusters without requiring a slot mutation. Positions are written to
each child as a private `--_lr-timeline-item-offset` custom property and removed again on a switch
back to `'flow'`. Cluster mode adds and removes a private visibility marker on non-representative
members and temporarily changes only the representative item's shadow presentation; switching
mode, shrinking the data, or disconnecting restores every ordinary row. If regrouping would remove
the focused row content or count action, focus moves to the replacement cluster action, the first
surviving item action, or the timeline list as a programmatic fallback.

**`lr-timeline-item` properties:** `timestamp?: Date | string | number` (attribute: false — `Date`
isn't attribute-serializable; invalid input normalizes to unset and renders no timestamp UI),
`sync: boolean = false` (forwarded to the internal `<lr-relative-time>`; no effect when the
`timestamp` slot is filled), `variant: 'neutral' | 'brand' | 'success' | 'warning' | 'danger' =
'neutral'` (marker tone), `active: boolean = false` (reflected — a static marker ring plus an
optional pulse disabled under `prefers-reduced-motion: reduce`, with explicit `aria-current="true"`
or `"false"` on the host).

**Events:** `lr-timeline` emits `lr-cluster-activate` when a `collision="cluster"` marker is
activated by pointer, Enter, or Space. Its non-cancelable, bubbling, composed
`detail: LyraTimelineClusterActivateDetail` is `{ items: readonly LyraTimelineItem[] }`: a fresh
frozen snapshot of the cluster members in document order, preserving each element's identity.
`LyraTimelineClusterActivateDetail {
  items: readonly LyraTimelineItem[];
}`
Use it to open a consumer-owned popover, dialog, or detail view. `lr-timeline-item` emits no events.
Read the reactive `itemCount` property after changing assigned items; the internal slot's
non-composed `slotchange` event is not a host-level public signal.

**Slots:** `lr-timeline`'s default slot holds the items, in display order. On an item the **default
slot is the title** (there is no `title` slot), plus `marker-icon` (marker glyph override; an empty
slot falls back to a color-coded dot), `timestamp` (wins outright over the
`timestamp` property whenever it has assigned content), and `description` (its part is hidden
entirely when empty).

**CSS parts:** timeline `base` — the `role="list"` flex container (no separate `list` part). Item:
`cluster` — the native count button rendered while that item represents a cluster, with a 40px
minimum action surface; `cluster-count` — its painted count pill; `base`, `track`
(marker + rail spine, always the opposite axis from `base`), `marker`
(`aria-hidden="true"`, decorative), `rail` (the connecting segment; `visibility: hidden` rather than
removed on the last item, so marker alignment stays consistent), `content`, `header` (flex row
wrapping `title` and `timestamp`; wraps at narrow widths rather than truncating), `title`,
`timestamp` (hidden when there's nothing to show), `description`.

**Themeable custom properties:** `--lr-timeline-gap` (default `var(--lr-space-l)`) — declared on
`lr-timeline` but consumed inside each item via inheritance across the slot boundary; it is both the
inter-item spacing and the length each rail bridges. `--lr-timeline-cluster-size` (default
`var(--lr-size-2rem)`) sizes the painted count pill, `--lr-timeline-cluster-bg` (default
`var(--lr-color-brand)`) sets its background, and `--lr-timeline-cluster-color` (default
`var(--lr-color-on-brand)`) sets its foreground. `--lr-scroll-fade-size` (default `2rem`) controls
each horizontal-overflow edge fade; forced-colors mode removes the masks while retaining native
scrolling. On the item: `--lr-timeline-marker-size`
(default `var(--lr-size-1-25rem)`, both dimensions so the dot stays circular),
`--lr-timeline-rail-width` (default `var(--lr-border-width-medium)`), `--lr-timeline-rail-color`
(default `var(--lr-color-border)`), `--lr-timeline-marker-color` (default
`var(--lr-color-text-quiet)`, with a private default that changes per `variant`), and
`--lr-timeline-active-ring-color`
(defaults to the effective marker color). All five item hooks inherit from theme
ancestors; setting one directly on an item wins over both the inherited value and variant default.

Version 9 removes the legacy item `icon` slot; migrate marker glyphs to `slot="marker-icon"`.
Timeline orientation/rail coordination now uses private implementation-prefixed cross-shadow
properties. The only supported spacing input remains `--lr-timeline-gap`; stop overriding the five
former `--lr-timeline-item-*` plumbing names.

## `lr-file-tree`

A file-explorer preset over `<lr-tree>` + `<lr-file-icon>`: path-keyed nodes with
git-status/diff-count badges, lazy directory loading, and select/open events.

An unreadable optional field rejects only that file record; it cannot reserve the path against a
later valid occurrence. Valid siblings retain their source order within the existing depth and
inspected-position budgets.

**Properties:** `nodes: readonly FileTreeNode[] = []` (attribute: false; clone-owned/frozen,
cycle-safe snapshot omitting empty/blank paths and retaining the first successfully admitted occurrence of each path, bounded to
the first 10,000 inspected source positions across 64 descendant levels; reassign after changes),
`selectedPath: string | null = null` (attribute `selected-path`), and `label?: string` — an
accessible-name override for the internal `<lr-tree>`, where omission reads back `undefined` and falls
back to the localized default while an explicitly empty string renders as an empty label.
`additions`/`deletions` are normalized once to finite nonnegative integers before localized visible
and accessible diff summaries. A host `aria-label` wins by presence when naming the internal tree,
including an explicit empty string; removing it restores `label` or the localized fallback.

**Methods:** `setChildren(path, children)` supplies a lazily-loaded directory's children.
`revealPath(path)` expands every ancestor directory and scrolls the target row into view, resolving
`true` once found. `expandAll()` and `collapseAll()` forward to the underlying `<lr-tree>`.

**Events:** `lr-file-select` (frozen readonly `detail: { filePath, node }`, a row was activated),
`lr-file-open` (frozen readonly `detail: { filePath, node }`, Enter/click on an already-selected file
row), and `lr-load-children` (frozen readonly `detail: { filePath }`, a lazy unloaded directory
expanded).

**CSS parts:** `base` — the root wrapper.

## `lr-env-list`

A masked key/value list for environment variables and secrets, with per-row reveal and copy.
Masking is presentational, not a security boundary: the real value sits in a DOM property
regardless of mask state. Names, revealed values, and localized action text wrap within narrow
allocations; the name track uses at most 40% of the available inline size.

**Properties:** `entries: readonly EnvEntry[] = []` (attribute: false; clone-owned/frozen snapshots
of at most the first 10,000 source entries; malformed records, blank names, and later duplicate
names are skipped first-wins before render, reveal state, copy actions, and events; reassign after
changes), `revealable: boolean = true` (reflected), `copyable: boolean = true`
(reflected), and `label?: string`. An omitted label uses localized `envListLabel`; an explicit empty
string remains empty. A host `aria-label` wins by attribute presence, including when empty.

**Events:** `lr-reveal-change` (frozen readonly `detail: { envName, revealed }`); `lr-copy` (frozen
readonly `detail: { ok: true, text }`, emitted only after clipboard fulfillment, with `text` equal
to the real unmasked value); `lr-copy-error` (frozen readonly
`detail: { ok: false, text, reason, error }`); and `lr-error` (compatibility failure notification
without raw platform error text). Failure is announced through the localized `copyFailed` string
in the owning document's shared polite live region; copy intent is never announced as success.

**CSS parts:** `base` (the `<dl>` root), `name` (the `<dt>` text), `value-cell` (the `<dd>` wrapping
an entry's value text and buttons), `value` (carries `data-masked`), `reveal-button`, and
`copy-button`.

**Themeable custom properties:** `--lr-env-list-reveal-active-bg` (default
`var(--lr-color-brand-quiet)`) and `--lr-env-list-reveal-active-border` (default
`var(--lr-color-brand)`) — the background and border color of a pressed (revealed) reveal toggle.
Both are inline `var()` fallbacks at their point of use rather than `:host` declarations, so either
can be set on the element _or any ancestor_. They exist because
`::part(reveal-button)[aria-pressed='true']` is invalid CSS — Shadow Parts forbids an attribute
selector after `::part()` — so restyling the pressed state otherwise required overriding the
library-wide brand tokens.

## `lr-document-library`

Controlled searchable and filterable document inventory with versions, tags, owners, freshness,
sorting, and bulk selection. It composes the table's bounded 100-row default, so a large document
collection stays reachable through pagination without mounting an unbounded grid.

Own `tags: undefined` is treated like omitted tags; malformed tag arrays and entries remain invalid.
Removing `search-term` clears search filtering without rewriting its `null` property readback; an
explicitly empty query also clears filtering and a later query applies normally.

**9.0 migration:** `lr-filter-change.detail.text` is now `searchTerm`, backed by the public
`searchTerm`/`search-term` axis. Replace `sortDirection: 'ascending'|'descending'` with
`sortDir: 'asc'|'desc'`; document sorting now uses the same cancelable `lr-sort-request` followed
by accepted `lr-sort` transaction and `{ phase, sortKey, sortDir }` vocabulary as `lr-table`.

**Properties:** clone-owned frozen `documents: readonly LibraryDocument[] = []` (at most the first
10,000 source documents and 10,000 tags per document are retained; document records, nested tags,
and dates are snapshotted on assignment; malformed records (including missing/non-string names or
non-string tag entries), blank ids, and later duplicate ids are omitted first-wins before filters,
counts, selection, rows, and events; reads are detached so `Date`
mutators cannot reach retained state; reassign after changes), `filter`, `label`, `loading`,
clone-owned frozen `selectedDocumentIds: readonly string[] = []` (at most 10,000 unique ids; reassign after
changes), public controlled `searchTerm: string = ''`
(`search-term`), `sortKey: LibraryDocumentSortKey = 'name'` (`sort-key`), canonical
`sortDir: 'asc'|'desc' = 'asc'` (`sort-dir`), and clone-owned frozen
`tagFilter: readonly string[] = []` (at most 10,000 unique tags; reassign after changes).
`size?: LyraSize` (reflected) — opt-in density tier forwarded to BOTH composed toolbar controls, the
search `lr-input` and the tag-filter `lr-combobox`, on the library's one six-step ladder
(`2xs`/`xs`/`s`/`m`/`l`/`xl`, or `small`/`medium`/`large`). Forwarding is the only way to reach them:
each resolves its tier inside its own shadow root, so no custom property on this component would get
there. The two always stay on the same tier as each other, so the toolbar row never goes ragged.
With no `size` both keep their own `m` default; an unsupported value normalizes to the omitted state
and removes the attribute.
`error: boolean = false` (reflected) — reports a failed document-list load. Forwarded to the nested
`lr-table`, whose own built-in failed-load state (with retry button) replaces the document rows
while it's set; `error` beats the empty state, matching `lr-table`'s own precedence.
`errorHeading?: string` (`error-heading`) — failed-load heading override, forwarded to the nested
table. Omitted localizes the table's own `tableLoadFailed` default.
`errorDescription: string = ''` (`error-description`) — failed-load supporting copy, forwarded to
the nested table.

**Events:** `lr-filter-change` emits a fresh frozen readonly
`{ searchTerm, tags, matchCount }`; cancelable `lr-sort-request` proposes frozen readonly
`{ phase: 'request', sortKey, sortDir }`; accepted `lr-sort` commits the same canonical vocabulary
with `phase: 'commit'`; `lr-selection-change` emits a fresh frozen readonly `{ documentIds }`;
`lr-open` emits frozen readonly `{ documentId }`; and `lr-retry` (`detail: null`, cancelable) — the
nested table's built-in retry button was activated, only rendered while `error` is set; the default
action clears `error`, `preventDefault()` leaves it set. This component intercepts the nested
table's own `lr-retry` and re-proposes its own, so the outer `error` property never drifts out of
sync with the table's internal state.

**Slots:** `error` — replaces the nested table's built-in failed-load state, including its retry
button, while `error` is set.

**CSS parts:** `base`, `toolbar`, `search`, `tag-filter`, `selection-bar`, `selection-count`,
`clear-selection`, `table`, `row`, `cell`, `header-cell`, `document-name`, `error-row`, `error-cell`,
`error` (the nested table's built-in `lr-empty` host), `error-base`, `error-icon`, `error-heading`,
`error-description`, `error-actions`, `retry-button`.

`selection-bar` is visible ordinary content, not a shadow live region. Initial declarative
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
`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.

## `lr-graph-query-builder`

Form-associated editor for a typed graph relationship/path query, including entity anchors,
relationship and node-type filters, hop limits, validation, and saved queries.

When the DOM cannot provide `activeElement`, the builder skips focus restoration while chip removal
and saved-query updates continue normally. Each minimum/maximum-hop select choice updates the query
once and emits one `lr-input` with the complete `{ value: GraphQuery }` snapshot. Native value
events, prefixed value aliases and listbox show/hide lifecycle events from those child selects are
contained. Programmatic query assignments remain silent.

The normalized `value` present at the first update is the form reset default. Later property writes
and user edits change only the live query; `form.reset()` restores that initial model, clears
interaction/touched state and the save-name draft, and retains a caller-set custom validity message
like a native control.

Removing a focused relationship/node filter chip moves focus to the adjacent chip, or to that
filter's add picker when no chips remain. `savedQueries` is controlled: when the host applies a
focused accepted `lr-query-delete` notification, focus follows the adjacent saved-query delete
action, or the stable save-name input when the list becomes empty. Updates that did not remove the
focused control never move external focus.

**Properties and getters:** clone-owned frozen `value: GraphQuery`; `customError` (`custom-error`),
`label`, `labels`, `name`, `disabled`, `effectiveDisabled`; clone-owned frozen
`nodeTypeOptions: readonly GraphQueryTypeOption[]`, `relationshipTypeOptions: readonly
GraphQueryTypeOption[]`, and `savedQueries: readonly GraphQuerySavedItem[]`; `hopLimit`, frozen
`errors`, `form`, `validity`, `validationMessage`, and `willValidate`. Type-option values and saved
query ids are nonblank unique first-wins identities; malformed/hostile records are skipped, nested queries
are normalized snapshots, collections are capped at 500 options / 200 saved queries, and strings
at 256 characters. `value.relationshipTypes` and `value.nodeTypes` are each capped at 500 entries.
Create and reassign a new value, options array, or saved-query array after changes; mutating a
previous caller-owned object cannot change the builder's assigned snapshots.

**Methods and form callbacks:** `getForm()`, `focus(options?)`, `blur()`, `click()`,
`checkValidity()`, `reportValidity()`, `setCustomValidity(message)`, `formDisabledCallback(disabled)`,
`formResetCallback()`, and `formStateRestoreCallback(state, mode?)`.

`setCustomValidity(message)` (new in 8.0.0) is the standard channel for a server-side rejection
("no graph is loaded for that tenant") that neither of the control's own constraints can express. A
non-empty `message` raises `customError` and becomes `validationMessage`, so the builder fails
`checkValidity()`, blocks submission and matches `:state(invalid)`; `''` clears it. Clearing
restores the control's own computed validity rather than forcing it valid — a query with no
`startId` stays `valueMissing` — and the custom error survives both intrinsic recomputation (every
field edit) and `form.reset()`, exactly like a native control, where only another
`setCustomValidity('')` clears it. The message is caller-supplied and is used verbatim, never
localized, and it is whole-control state exposed as `errors.base`; intrinsic errors remain keyed
by their field csspart. The start-ID `lr-input` is natively required, matching
the aggregate `valueMissing` constraint. `focus(options?)` and `click()` target the first rendered
field (start/end/hop-limit/direction/save-name, in that order), `blur()` releases whichever nested
owner contains deep focus, and all entry actions are inert while directly or fieldset disabled.

The group is named by a host `aria-label` when present; otherwise `aria-labelledby` points to the
visible label element, so slotted/property/localized label text is also the announced name.

**Events:** all query/model details are readonly frozen snapshots. `lr-validity-change` publishes
effective native validity, including custom errors and own/fieldset validation barring.
`lr-invalid` is a cancelable bubbling/composed alias; vetoing it suppresses the native invalid
default. Run, save, load, and delete share one two-phase contract: cancelable
`lr-before-query-run`, `lr-before-query-save`, `lr-before-query-load`, and
`lr-before-query-delete` requests precede any local effect; non-cancelable `lr-query-run`,
`lr-query-save`, `lr-query-load`, and `lr-query-delete` notifications follow only when accepted.
The matching before/accepted pair reuses one frozen payload: `{ query }` for run,
`{ name, query }` for save, `{ queryId, query }` for load, and `{ queryId }` for delete.
Run validates before its request. Save veto preserves the draft name. Load requests frozen
`{ queryId, query }` before changing `value`, so veto preserves the current query; its accepted event
fires after the new value is applied. Delete remains controlled, so the host removes the accepted
id from `savedQueries`. The full set is `lr-input`, `lr-validity-change`, `lr-invalid`, and those
eight phased action events.

Migration note: veto save in `lr-before-query-save`, not `lr-query-save`; the existing
`lr-query-*` action events are accepted, non-cancelable notifications. **Slots:** `actions`,
`label`, `hint`, `error`. **CSS
parts:** `base`, `label`, `hint`, `error` (the three form-control chrome parts every
form-associated control in this library exposes — see `lr-select`), `path-fields`, `start-input`,
`end-input`, `relationship-picker`, `relationship-chips`, `node-type-picker`, `node-type-chips`,
`direction`, `filter-group`, `min-hops`, `max-hops`, `footer`, `run-button`, `save-button`,
`save-row`, `save-name-input`, `saved-queries`, `saved-queries-label`, `saved-list`, `saved-item`,
`saved-load-button`, `saved-delete-button`, `saved-empty`.

**Themeable custom properties:** the Run button exposes `--lr-graph-query-builder-run-bg`,
`--lr-graph-query-builder-run-border-color`, and `--lr-graph-query-builder-run-color` for its
resting longhands plus `--lr-graph-query-builder-run-hover-bg` and
`--lr-graph-query-builder-run-active-bg`; the Save button exposes
`--lr-graph-query-builder-save-bg`, `--lr-graph-query-builder-save-border-color`,
`--lr-graph-query-builder-save-color`, `--lr-graph-query-builder-save-hover-bg`, and
`--lr-graph-query-builder-save-active-bg`. Saved-query actions use
`--lr-graph-query-builder-saved-load-color`, `--lr-graph-query-builder-saved-load-active-bg`,
`--lr-graph-query-builder-saved-delete-color`,
`--lr-graph-query-builder-saved-delete-hover-color`,
`--lr-graph-query-builder-saved-delete-active-color`, and
`--lr-graph-query-builder-saved-delete-active-bg`. Unset hooks preserve the current shared
surface/text/brand/danger colors and hover/active mixes. They are inline `var()` fallbacks at the
longhand that consumes them, so an override on a parent themes every descendant builder without
being shadowed by a declaration on the component host.

**Additional API surface:**

- `errorText` — Caller-supplied outer error text. Field-level validation remains on the affected controls. Type: `string`.
- `hint` — Supporting text rendered below the outer label. Type: `string`.
- `error-text` attribute — Caller-supplied outer error text. Field-level validation remains on the affected controls.
- `hint` attribute — Supporting text rendered below the outer label.
- `hint` slot — Supporting text for the complete form control.
- `part="hint"` — Supporting text for the complete form control.

## `lr-condition-builder`

Composable flat condition builder for tabular or dashboard data: condition rows combined with an
AND/OR combinator, distinct by name and model from `lr-graph-query-builder`.

A field or operator select choice updates the builder once and emits one `lr-input` carrying the
complete `{ value: ConditionBuilderValue }` snapshot. Child native `input`/`change`, prefixed value
aliases and listbox show/hide lifecycle events remain inside those pickers. Programmatic `value`
assignments remain silent.

**9.0 migration:** `lr-query-builder` / `LyraQueryBuilder` / `QueryBuilder*` were renamed without
aliases to `lr-condition-builder` / `LyraConditionBuilder` / `ConditionBuilder*`. Update the tag,
granular import path, class/type imports, selectors, and framework bindings together.

**Properties:** clone-owned readonly `fields`, clone-owned readonly `value`, and `disabled`.
Structured inputs are bounded (200 fields and conditions, 500 options per field, 256 characters
per string), malformed records and blank field names/option values/condition ids are skipped,
duplicates use the first valid record, and unknown closed-vocabulary values normalize to their
documented fallback. A retained, known operator and its value payload are not rewritten merely
because they disagree with the current field metadata. That preservation also applies when fields
arrive after `value` or their operator/type definition later changes.
Returned arrays and records are frozen snapshots, so mutate-and-reuse does not bypass Lit's
assignment boundary. Create and reassign a new `fields` array or `value` record after changes.

`validationIssues` is a live frozen list of `{ conditionId, code }` rows, where `code` is
`field-unavailable`, `operator-not-allowed`, `operator-arity`, or `value-type`.
`invalidConditionIds` projects their ids in model order, `checkValidity()` tests the current model,
and `reportValidity()` additionally focuses the first affected field/operator/value control. The
root group and every condition render explicit `aria-invalid="true"|"false"`. A non-finite
controlled number is therefore preserved and reported as `value-type`; numeric text entered through
the UI still becomes unset when parsing overflows. Check validity before sending restored data to a
backend, particularly because JSON serializes non-finite numbers as `null`.

`ConditionBuilderField.min`/`max` accept finite numbers for `type: 'number'` and bounded strings for
`type: 'date'`; `step` accepts a positive finite number for numeric fields. These constraints are
forwarded to the composed `lr-input`/`lr-date-input`. They are omitted for other field types, and
leaving all three unset preserves the previous unconstrained controls.

**Methods:** `addCondition()` appends a condition using the first available field and emits a frozen
`lr-add-condition`; it is a no-op while disabled or when there are no fields. `checkValidity()` and
`reportValidity()` validate without changing `value`.
`removeCondition(id)` removes the matching condition and emits `lr-remove-condition`
(`detail: { conditionId }`); it is a
no-op while disabled or when the id is absent.

**Events:** `lr-input`, `lr-add-condition`, `lr-remove-condition`; all details and nested model
snapshots are readonly and frozen. **CSS parts:** `base`, `conditions`,
`condition`, `field-select`, `operator-select`, `value`, `combinator`, `add-button`,
`remove-button`, `empty`.

`conditions` is a semantic list and every `condition` is a list item, so repeated Field/Operator/
Value labels retain a row relationship in the accessibility tree. The localized, indexed remove
name continues to identify each row's destructive action.

At allocations of 320px or less, each condition stacks its composed field/operator/value controls
into one column. Long field labels and localized operator text remain contained and ellipsize inside
the nested `lr-select` triggers in both LTR and RTL; they do not widen the host or document.

## Consumer integration notes

- **Data grid:** variable-height rows use `[part="body"]` as the only vertical and horizontal scroll
  viewport; header and footer mirror its logical inline position. Resize `aria-valuenow` stays in
  CSS pixels while `aria-valuetext` is localized with the effective locale. Row/group measurement is
  cached by stable identity: after width, columns, locale, or display structure changes, a pending
  `scrollToIndex()` target realigns after measurement unless a user scroll supersedes the correction.
  `--lr-data-grid-control-hover-background`, `--lr-data-grid-control-active-background`,
  `--lr-data-grid-page-size-active-background`, `--lr-data-grid-row-active-background`,
  `--lr-data-grid-sortable-header-hover-background`, and
  `--lr-data-grid-sortable-header-active-background` theme those independent state surfaces.
- **Table:** resize-handle numeric ARIA ranges remain CSS pixels, with localized current-pixel
  `aria-valuetext`. Adjacent row-expand controls inherit table typography and use a `1em` glyph.
- **Flow canvas:** only direct child cards participate. A matching `node-id` receives the managed
  `node-{id}` slot. When the canvas stops managing a card, it restores that card's original `slot`
  only if it has not changed in the meantime; a later author-set `slot` is left intact. Unmatched
  direct cards do not render because there is no catch-all slot. The first completed connected
  layout is silent even if truncated; it still shows the limit and emits `lr-layout-change`, while
  only a later false-to-true truncation transition announces.

## Exported TypeScript contracts

These named interfaces and helper signatures are available to typed integrations. They are grouped by capability so the component sections above can stay focused.

- **`components-data-calendar-calendar-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/data/calendar/calendar.class.js`.
  `CalendarEvent {
    readonly id?: string;
    readonly date: string | number | Date;
    readonly title: string;
    readonly color?: string;
    readonly data?: unknown;
  }`

- **`components-data-condition-builder-condition-builder-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/data/condition-builder/condition-builder.class.js`.
  `ConditionBuilderCondition {
    readonly id: string;
    readonly field: string;
    readonly operator: ConditionBuilderOperator | '';
    readonly value?: string | number | boolean | readonly string[];
  }`
  Import: `@aceshooting/lyra-ui/components/data/condition-builder/condition-builder.class.js`.
  `ConditionBuilderField {
    readonly name: string;
    readonly label?: string;
    readonly type: ConditionBuilderFieldType;
    readonly options?: readonly ConditionBuilderFieldOption[];
    readonly operators?: readonly ConditionBuilderOperator[];
    readonly placeholder?: string;
    readonly min?: number | string;
    readonly max?: number | string;
    readonly step?: number;
  }`
  Import: `@aceshooting/lyra-ui/components/data/condition-builder/condition-builder.class.js`.
  `ConditionBuilderFieldOption {
    readonly value: string;
    readonly label?: string;
  }`
  Import: `@aceshooting/lyra-ui/components/data/condition-builder/condition-builder.class.js`.
  `ConditionBuilderValidationIssue {
    readonly conditionId: string;
    readonly code: ConditionBuilderValidationIssueCode;
  }`
  Import: `@aceshooting/lyra-ui/components/data/condition-builder/condition-builder.class.js`.
  `ConditionBuilderValue {
    readonly combinator: ConditionBuilderCombinator;
    readonly conditions: readonly ConditionBuilderCondition[];
  }`

- **`components-data-context-meter-context-meter-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/data/context-meter/context-meter.class.js`.
  `ContextMeterSegment {
    label: string;
    value: number;
    tone?: ContextMeterTone;
    color?: string;
    disabled?: boolean;
  }`
  Import: `@aceshooting/lyra-ui/components/data/context-meter/context-meter.class.js`.
  `LyraContextMeterSegmentActivateDetail {
    readonly index: number;
    readonly label: string;
    readonly value: number;
  }`

- **`components-data-data-grid-data-grid-types-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/data/data-grid/data-grid.class.js`.
  `DataGridCellContextMenuDetail<Row = Record<string, unknown>> extends DataGridCellDetail<Row> {
    readonly originalEvent: MouseEvent | KeyboardEvent;
    // Inherited from DataGridCellDetail<Row>.
    readonly rowKey: DataGridKey;
    readonly columnId: string;
    readonly column: DataGridColumn<Row>;
    readonly value: unknown;
    readonly row: Row;
    readonly index: number;
  }`
  Import: `@aceshooting/lyra-ui/components/data/data-grid/data-grid.class.js`.
  `DataGridCellDetail<Row = Record<string, unknown>> {
    readonly rowKey: DataGridKey;
    readonly columnId: string;
    readonly column: DataGridColumn<Row>;
    readonly value: unknown;
    readonly row: Row;
    readonly index: number;
  }`
  Import: `@aceshooting/lyra-ui/components/data/data-grid/data-grid.class.js`.
  `DataGridColumn<Row = Record<string, unknown>> {
    readonly id?: string;
    readonly field?: string;
    readonly label?: string;
    readonly align?: 'left' | 'center' | 'right' | 'start' | 'end';
    readonly width?: number;
    readonly minWidth?: number;
    readonly maxWidth?: number;
    readonly flex?: number;
    readonly formatter?: (value: unknown, row: Row) => string | TemplateResult | Node | unknown;
    readonly cellTitle?: (row: Row) => string | undefined;
    readonly value?: (row: Row) => unknown;
    readonly sortable?: boolean;
    readonly sortFn?: DataGridSortAlgorithm;
    readonly comparator?: (left: unknown, right: unknown, leftRow: Row, rightRow: Row) => number;
    readonly sortDescFirst?: boolean;
    readonly sortUndefined?: 'first' | 'last' | 1 | -1;
    readonly searchable?: boolean;
    readonly filterable?: boolean;
    readonly filterType?: DataGridFilterType;
    readonly filterFn?: (value: unknown, filter: unknown, row: Row) => boolean;
    readonly hidden?: boolean;
    readonly hideable?: boolean;
    readonly resizable?: boolean;
    readonly movable?: boolean;
    readonly pinnable?: boolean;
    readonly pinned?: DataGridPinSide;
    readonly footer?: string | ((rows: readonly Row[]) => unknown);
    readonly aggregation?: DataGridAggregation<Row>;
    readonly aggregatedFormatter?: (value: unknown, rows: readonly Row[]) => string | TemplateResult | Node | unknown;
  }`
  Import: `@aceshooting/lyra-ui/components/data/data-grid/data-grid.class.js`.
  `DataGridColumnMoveDetail {
    readonly columnOrder: readonly string[];
    readonly columnId: string;
    readonly finished: boolean;
  }`
  Import: `@aceshooting/lyra-ui/components/data/data-grid/data-grid.class.js`.
  `DataGridColumnPinDetail {
    readonly columnId: string;
    readonly side: DataGridPinSide;
  }`
  Import: `@aceshooting/lyra-ui/components/data/data-grid/data-grid.class.js`.
  `DataGridColumnResizeDetail {
    readonly columnId: string;
    readonly width: number;
    readonly finished: boolean;
  }`
  Import: `@aceshooting/lyra-ui/components/data/data-grid/data-grid.class.js`.
  `DataGridColumnState {
    readonly order?: readonly string[];
    readonly widths?: Readonly<Record<string, number>>;
    readonly visibility?: Readonly<Record<string, boolean>>;
    readonly pinning?: Readonly<Record<string, DataGridPinSide>>;
  }`
  Import: `@aceshooting/lyra-ui/components/data/data-grid/data-grid.class.js`.
  `DataGridColumnVisibilityDetail {
    readonly columnId: string;
    readonly visible: boolean;
  }`
  Import: `@aceshooting/lyra-ui/components/data/data-grid/data-grid.class.js`.
  `DataGridCopyOptions {
    readonly columnIds?: readonly string[];
    readonly includeHeaders?: boolean;
    readonly format?: 'tsv' | 'csv';
    readonly escapeFormulas?: boolean;
    readonly delimiter?: string;
  }`
  Import: `@aceshooting/lyra-ui/components/data/data-grid/data-grid.class.js`.
  `DataGridCsvOptions {
    readonly delimiter?: string;
    readonly includeHeaders?: boolean;
    readonly columnIds?: readonly string[];
    readonly escapeFormulas?: boolean;
  }`
  Import: `@aceshooting/lyra-ui/components/data/data-grid/data-grid.class.js`.
  `DataGridDataErrorDetail {
    readonly error: unknown;
    readonly request: DataGridRequest;
  }`
  Import: `@aceshooting/lyra-ui/components/data/data-grid/data-grid.class.js`.
  `DataGridExportOptions extends DataGridCsvOptions {
    readonly fileName?: string;
    // Inherited from DataGridCsvOptions.
    readonly delimiter?: string;
    readonly includeHeaders?: boolean;
    readonly columnIds?: readonly string[];
    readonly escapeFormulas?: boolean;
  }`
  Import: `@aceshooting/lyra-ui/components/data/data-grid/data-grid.class.js`.
  `DataGridFacets {
    readonly uniqueValues: ReadonlyMap<unknown, number>;
    readonly minMax?: readonly [number, number];
  }`
  Import: `@aceshooting/lyra-ui/components/data/data-grid/data-grid.class.js`.
  `DataGridFilter {
    readonly id: string;
    readonly value: unknown;
  }`
  Import: `@aceshooting/lyra-ui/components/data/data-grid/data-grid.class.js`.
  `DataGridGroupDetail<Row = Record<string, unknown>> {
    readonly key: string;
    readonly columnId: string;
    readonly value: unknown;
    readonly rows: readonly Row[];
  }`
  Import: `@aceshooting/lyra-ui/components/data/data-grid/data-grid.class.js`.
  `DataGridPageDetail {
    readonly page: number;
    readonly pageSize: number;
  }`
  Import: `@aceshooting/lyra-ui/components/data/data-grid/data-grid.class.js`.
  `DataGridRequest {
    readonly sort: DataGridSortingState;
    readonly filters: readonly DataGridFilter[];
    readonly search: string;
    readonly page: number;
    readonly pageSize: number;
    readonly signal: AbortSignal | undefined;
  }`
  Import: `@aceshooting/lyra-ui/components/data/data-grid/data-grid.class.js`.
  `DataGridResponse<Row = Record<string, unknown>> {
    readonly rows: readonly Row[];
    readonly total: number;
  }`
  Import: `@aceshooting/lyra-ui/components/data/data-grid/data-grid.class.js`.
  `DataGridRowDetail<Row = Record<string, unknown>> {
    readonly rowKey: DataGridKey;
    readonly key: DataGridKey;
    readonly row: Row;
  }`
  Import: `@aceshooting/lyra-ui/components/data/data-grid/data-grid.class.js`.
  `DataGridScrollOptions {
    readonly align?: 'start' | 'center' | 'end';
  }`
  Import: `@aceshooting/lyra-ui/components/data/data-grid/data-grid.class.js`.
  `DataGridSelectionDetail<Row = Record<string, unknown>> {
    readonly selectedRowKeys: readonly DataGridKey[];
    readonly selectedKeys: readonly DataGridKey[];
    readonly selectedRows: readonly Row[];
  }`
  Import: `@aceshooting/lyra-ui/components/data/data-grid/data-grid.class.js`.
  `DataGridSort {
    readonly id: string;
    readonly desc: boolean;
  }`
  Import: `@aceshooting/lyra-ui/components/data/data-grid/data-grid.class.js`.
  `DataGridStateFilter {
    readonly id: string;
    readonly value: DataGridJsonValue;
  }`
  Import: `@aceshooting/lyra-ui/components/data/data-grid/data-grid.class.js`.
  `DataGridState extends DataGridColumnState {
    readonly sort?: DataGridSortingState;
    readonly filters?: readonly DataGridStateFilter[];
    readonly search?: string;
    readonly selectedRowKeys?: readonly DataGridKey[];
    readonly expandedRowKeys?: readonly DataGridKey[];
    readonly selectedKeys?: readonly DataGridKey[];
    readonly expandedKeys?: readonly DataGridKey[];
    readonly page?: number;
    readonly pageSize?: number;
    // Inherited from DataGridColumnState.
    readonly order?: readonly string[];
    readonly widths?: Readonly<Record<string, number>>;
    readonly visibility?: Readonly<Record<string, boolean>>;
    readonly pinning?: Readonly<Record<string, DataGridPinSide>>;
  }`

- **`components-data-document-library-document-library-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/data/document-library/document-library.class.js`.
  `DocumentLibraryFilterChangeDetail {
    readonly searchTerm: string;
    readonly tags: readonly string[];
    readonly matchCount: number;
  }`
  Import: `@aceshooting/lyra-ui/components/data/document-library/document-library.class.js`.
  `DocumentLibraryOpenDetail {
    readonly documentId: string;
  }`
  Import: `@aceshooting/lyra-ui/components/data/document-library/document-library.class.js`.
  `DocumentLibrarySelectionChangeDetail {
    readonly documentIds: readonly string[];
  }`
  Import: `@aceshooting/lyra-ui/components/data/document-library/document-library.class.js`.
  `DocumentLibrarySortCommitDetail {
    readonly phase: 'commit';
    readonly sortKey: LibraryDocumentSortKey;
    readonly sortDir: TableSortDirection;
  }`
  Import: `@aceshooting/lyra-ui/components/data/document-library/document-library.class.js`.
  `DocumentLibrarySortRequestDetail {
    readonly phase: 'request';
    readonly sortKey: LibraryDocumentSortKey;
    readonly sortDir: TableSortDirection;
  }`
  Import: `@aceshooting/lyra-ui/components/data/document-library/document-library.class.js`.
  `LibraryDocument extends DocumentRef {
    tags?: readonly string[];
    owner?: string;
    updatedAt?: Date | string;
    freshness?: LibraryDocumentFreshness;
    // Inherited from DocumentRef.
    id: string;
    name: string;
    mimeType?: string;
    uri?: string;
    version?: string;
  }`

- **`components-data-env-list-env-list-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/data/env-list/env-list.class.js`.
  `EnvEntry {
    readonly name: string;
    readonly value: string;
    readonly secret?: boolean;
  }`

- **`components-data-file-tree-file-tree-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/data/file-tree/file-tree.class.js`.
  `FileTreeNode {
    readonly path: string;
    readonly name?: string;
    readonly kind?: 'file' | 'directory';
    readonly mimeType?: string;
    readonly gitStatus?: GitStatus;
    readonly additions?: number;
    readonly deletions?: number;
    readonly children?: readonly FileTreeNode[];
    readonly hasChildren?: boolean;
  }`

- **`components-data-flow-canvas-flow-types-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/data/flow-canvas/flow-types.js`.
  `FlowEdge {
    readonly id: string;
    readonly source: string;
    readonly target: string;
    readonly sourceHandle?: string;
    readonly targetHandle?: string;
    readonly label?: string;
    readonly tone?: LyraVariant;
  }`
  Import: `@aceshooting/lyra-ui/components/data/flow-canvas/flow-types.js`.
  `FlowHandle {
    readonly id: string;
    readonly label?: string;
  }`
  Import: `@aceshooting/lyra-ui/components/data/flow-canvas/flow-types.js`.
  `FlowLayoutChangeDetail {
    readonly positions: Readonly<Record<string, Readonly<{
      x: number;
      y: number;
    }>>>;
    readonly truncated: boolean;
  }`
  Import: `@aceshooting/lyra-ui/components/data/flow-canvas/flow-types.js`.
  `FlowNode {
    readonly id: string;
    readonly type?: string;
    readonly position?: Readonly<{
      x: number;
      y: number;
    }>;
    readonly data?: Readonly<Record<string, unknown>>;
    readonly accessibleLabel?: string;
    readonly inputs?: readonly FlowHandle[];
    readonly outputs?: readonly FlowHandle[];
    readonly disabled?: boolean;
  }`
  Import: `@aceshooting/lyra-ui/components/data/flow-canvas/flow-types.js`.
  `FlowRunDecoration {
    readonly status: LyraToolStatus;
    readonly progress?: number;
    readonly durationMs?: number;
    readonly detail?: string;
  }`
  Import: `@aceshooting/lyra-ui/components/data/flow-canvas/flow-types.js`.
  `FlowStructureEdgeSnapshot {
    readonly id: string;
    readonly source: string;
    readonly target: string;
    readonly status?: LyraToolStatus;
  }`
  Import: `@aceshooting/lyra-ui/components/data/flow-canvas/flow-types.js`.
  `FlowStructureNodeSnapshot {
    readonly id: string;
    readonly x: number;
    readonly y: number;
    readonly width: number;
    readonly height: number;
    readonly status?: LyraToolStatus;
  }`
  Import: `@aceshooting/lyra-ui/components/data/flow-canvas/flow-types.js`.
  `FlowStructureSnapshot {
    readonly nodes: readonly FlowStructureNodeSnapshot[];
    readonly edges: readonly FlowStructureEdgeSnapshot[];
    readonly viewport: FlowViewportSnapshot;
    readonly locked: boolean;
    readonly orientation: LyraOrientation;
    readonly layerGap: number;
    readonly nodeGap: number;
  }`
  Import: `@aceshooting/lyra-ui/components/data/flow-canvas/flow-types.js`.
  `FlowViewportSnapshot {
    readonly x: number;
    readonly y: number;
    readonly zoom: number;
    readonly width: number;
    readonly height: number;
    readonly minZoom: number;
    readonly maxZoom: number;
  }`

- **`components-data-funnel-funnel-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/data/funnel/funnel.class.js`.
  `LyraFunnelStage {
    readonly label: string;
    readonly value: number;
    readonly color?: string;
  }`

- **`components-data-graph-query-builder-graph-query-builder-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/data/graph-query-builder/graph-query-builder.class.js`.
  `GraphQueryDeleteDetail {
    readonly queryId: string;
  }`
  Import: `@aceshooting/lyra-ui/components/data/graph-query-builder/graph-query-builder.class.js`.
  `GraphQuery {
    readonly startId: string;
    readonly endId: string;
    readonly relationshipTypes: readonly string[];
    readonly nodeTypes: readonly string[];
    readonly direction: GraphQueryDirection;
    readonly minHops: number;
    readonly maxHops: number;
  }`
  Import: `@aceshooting/lyra-ui/components/data/graph-query-builder/graph-query-builder.class.js`.
  `GraphQueryLoadDetail {
    readonly queryId: string;
    readonly query: GraphQuery;
  }`
  Import: `@aceshooting/lyra-ui/components/data/graph-query-builder/graph-query-builder.class.js`.
  `GraphQueryRunDetail {
    readonly query: GraphQuery;
  }`
  Import: `@aceshooting/lyra-ui/components/data/graph-query-builder/graph-query-builder.class.js`.
  `GraphQuerySaveDetail {
    readonly name: string;
    readonly query: GraphQuery;
  }`
  Import: `@aceshooting/lyra-ui/components/data/graph-query-builder/graph-query-builder.class.js`.
  `GraphQuerySavedItem {
    readonly id: string;
    readonly name: string;
    readonly query: GraphQuery;
  }`
  Import: `@aceshooting/lyra-ui/components/data/graph-query-builder/graph-query-builder.class.js`.
  `GraphQueryTypeOption {
    readonly value: string;
    readonly label?: string;
  }`

- **`components-data-heatmap-calendar-grid-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui`.
  `CalendarDay {
    date: string;
    value: number;
  }`

- **`components-data-heatmap-heatmap-scale-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui`.
  `linearAlpha(value: number, lo: number, hi: number): number`
  Import: `@aceshooting/lyra-ui`.
  `sqrtStep(count: number, max: number, steps: number): number`

- **`components-data-heatmap-heatmap-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/data/heatmap/heatmap.class.js`.
  `CalendarCellPos {
    week: number;
    weekday: number;
    date: string;
  }`
  Import: `@aceshooting/lyra-ui/components/data/heatmap/heatmap.class.js`.
  `HeatmapAnnotation {
    row?: number;
    col?: number;
    date?: string;
    label?: string;
  }`
  Import: `@aceshooting/lyra-ui/components/data/heatmap/heatmap.class.js`.
  `HeatmapCalendarData {
    readonly kind: 'calendar';
    readonly days: readonly CalendarDay[];
    readonly firstDayOfWeek?: number;
    readonly columnX?: (index: number) => number;
    readonly rowY?: (weekday: number) => number;
    readonly weekdayLabelWidth?: number | 'auto';
    readonly weekdayLabelText?: (jsWeekday: number) => string | undefined;
    readonly monthLabelText?: (jsMonth: number, year: number) => string | undefined;
  }`
  Import: `@aceshooting/lyra-ui/components/data/heatmap/heatmap.class.js`.
  `HeatmapLegendStop {
    value: number;
    color?: string;
    label?: string;
    partOfRamp?: boolean;
  }`
  Import: `@aceshooting/lyra-ui/components/data/heatmap/heatmap.class.js`.
  `HeatmapMatrixData {
    readonly kind: 'matrix';
    readonly rowLabels: readonly string[];
    readonly colLabels: readonly string[];
    readonly values: readonly (readonly number[])[];
  }`
  Import: `@aceshooting/lyra-ui/components/data/heatmap/heatmap.class.js`.
  `HeatmapSelectedCell {
    row?: number;
    col?: number;
    date?: string;
  }`
  Import: `@aceshooting/lyra-ui/components/data/heatmap/heatmap.class.js`.
  `HeatmapSelectionChangeDetail {
    readonly selectedCells: readonly Readonly<HeatmapSelectedCell>[];
    readonly source: HeatmapSelectionSource;
  }`
  Import: `@aceshooting/lyra-ui/components/data/heatmap/heatmap.class.js`.
  `hexToRgb(hex: string): [number, number, number, number] | null`
  Import: `@aceshooting/lyra-ui/components/data/heatmap/heatmap.class.js`.
  `MatrixCellPos {
    row: number;
    col: number;
  }`
  Import: `@aceshooting/lyra-ui/components/data/heatmap/heatmap.class.js`.
  `normalizeBucketCount(bucketCount: number): number`
  Import: `@aceshooting/lyra-ui/components/data/heatmap/heatmap.class.js`.
  `resolveRgb(color: string, fallbackHex: string, ownerDocument?: Document): [number, number, number, number]`

- **`components-data-pagination-pagination-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/data/pagination/pagination.class.js`.
  `LyraPaginationChangeDetail {
    readonly page: number;
    readonly pageSize: number;
  }`

- **`components-data-sequence-strip-sequence-strip-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/data/sequence-strip/sequence-strip.class.js`.
  `LyraSequenceStripActivateDetail {
    readonly index: number;
    readonly id: string;
    readonly item: SequenceStripItem;
  }`
  Import: `@aceshooting/lyra-ui/components/data/sequence-strip/sequence-strip.class.js`.
  `SequenceStripCategory {
    readonly id: string;
    readonly color: string;
    readonly label?: string;
  }`
  Import: `@aceshooting/lyra-ui/components/data/sequence-strip/sequence-strip.class.js`.
  `SequenceStripItem {
    readonly id: string;
    readonly categoryId: string;
    readonly marker?: boolean;
    readonly label?: string;
    readonly disabled?: boolean;
  }`

- **`components-data-stat-stat-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/data/stat/stat.class.js`.
  `StatRow {
    readonly label: string;
    readonly value: string;
    readonly exactValue?: string;
  }`

- **`components-data-table-table-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/data/table/table.class.js`.
  `TableColumn<T> {
    key: string;
    label: string;
    headerCell?: (column: TableColumn<T>) => unknown;
    width?: string;
    minWidth?: string;
    maxWidth?: string;
    resizable?: boolean;
    sortable?: boolean;
    sortValue?: (row: T) => string | number | null | undefined;
    defaultSortDir?: TableSortDirection;
    align?: TableEdgeAlign;
    priority?: 'medium' | 'low';
    sticky?: TableEdgeAlign;
    footer?(rows: readonly T[]): unknown;
    cellStyle?(row: T): Record<string, string> | undefined;
    cellTitle?(row: T): string | undefined;
    heatValue?(row: T): number | null | undefined;
    editTrigger?: TableColumnEditTrigger;
    editValue?: (row: T) => string | number;
    editLabel?: (row: T) => string;
    editType?: 'text' | 'number' | 'select';
    editOptions?: TableColumnEditOption[];
    cell: (row: T) => unknown;
  }`
  Import: `@aceshooting/lyra-ui/components/data/table/table.class.js`.
  `TableColumnEditOption {
    value: string;
    label: string;
  }`
  Import: `@aceshooting/lyra-ui/components/data/table/table.class.js`.
  `TableSortCommitDetail {
    readonly phase: 'commit';
    readonly sortKey: string;
    readonly sortDir: TableSortDirection;
  }`
  Import: `@aceshooting/lyra-ui/components/data/table/table.class.js`.
  `TableSortRequestDetail {
    readonly phase: 'request';
    readonly sortKey: string;
    readonly sortDir: TableSortDirection;
  }`

- **`components-data-tree-tree-types-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/data/tree/tree.class.js`.
  `LyraTreeNodeData {
    readonly id: string;
    readonly label: string;
    readonly selected?: boolean;
    readonly disabled?: boolean;
    readonly lazy?: boolean;
    readonly children?: readonly LyraTreeNodeData[];
    readonly badges?: readonly TreeBadge[];
    readonly icon?: unknown;
    readonly description?: string;
    readonly accessibleLabel?: string;
  }`
  Import: `@aceshooting/lyra-ui/components/data/tree/tree.class.js`.
  `TreeBadge {
    readonly text: string;
    readonly tone?: LyraVariant;
    readonly label?: string;
  }`

- **`components-data-word-cloud-word-cloud-layout-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/data/word-cloud/word-cloud.class.js`.
  `WordCloudWord {
    readonly text: string;
    readonly weight: number;
    readonly color?: string;
    readonly group?: string;
  }`

- **`components-data-word-cloud-word-cloud-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/data/word-cloud/word-cloud.class.js`.
  `WordCloudLegendItem {
    readonly label: string;
    readonly color: string;
  }`

# Layout, navigation & structure (`components/layout/`)

## Breaking changes in 10.0.0

**`lr-virtual-list`:** the `lr-visible-range-changed` event is removed — listen for
`lr-visible-range-change` instead. The detail (`LyraVirtualListRange`), the firing conditions and the
gesture are all unchanged; only the name moved. The old spelling was the library's only past-tense
`-changed` event among 58 members of the `-change` family, so a convention-driven `lr-${x}-change`
listener silently missed it on a component embedded in ten viewers. It is removed outright rather
than kept as a dual-emitting alias, because the library has no released consumers and an alias is a
permanent tax paid to protect users who do not exist. Rename the listener; nothing else changes.

Also corrected in 10.0.0 — not breaking, but visible. `<lr-dashboard-grid>`'s cell keeps a focus
indicator while it is in a collision or drop state: the collision rule owns the outline channel by
design, but the side effect was that the focus ring vanished entirely during exactly the drag or
resize a keyboard user most needs it, so the ring is now re-expressed on a second channel. And
`<lr-card>` honors a `hidden` slotted media child instead of painting it — the component's own
`display` declaration is author-origin and was beating the UA stylesheet's `[hidden] { display: none }`.

## Breaking changes in 9.0.0

**`lr-app-rail`:** `mode`'s write side is removed: the accessor is now strictly read-only (always resolves to
'full'/'icon-only'/'mobile', never 'auto'). A new `forceMode` property/attribute (`force-mode`, type
`'full' | 'icon-only' | 'auto'`, unset by default) replaces it: assign 'full'/'icon-only' to pin that
mode, 'auto' (or unset) to release the pin and resume automatic breakpoint tracking. Unlike the
removed mode setter, 'mobile' can no longer be force-pinned — the mobile breakpoint is always tracked
automatically regardless, mirroring `preferredMode`'s existing scope; if a consumer needs a
guaranteed-mobile demo/test state, widen `mobile-breakpoint` instead. Whether the rail is currently
pinned is now itself observable (`forceMode === 'auto'` or unset means auto-tracking). `dragging`
loses its public setter — it's read-only; assigning it now throws (`el.dragging = true` ->
TypeError), matching that this component has always owned every drag transition itself. Exported
types renamed (TypeScript-only, no markup/runtime change): `AppRailMode` -> `LyraAppRailMode`,
`AppRailModeInput` -> `LyraAppRailModeInput`, `AppRailPreferredMode` -> `LyraAppRailPreferredMode`,
`AppRailPersistField` -> `LyraAppRailPersistField`, `AppRailModeChangeDetail` ->
`LyraAppRailModeChangeDetail`, `AppRailToggleDetail` -> `LyraAppRailToggleDetail`,
`AppRailResizeDetail` -> `LyraAppRailResizeDetail`.

**`lr-tab-group`:** Exported types renamed, TypeScript-only: `TabGroupPlacement` ->
`LyraTabGroupPlacement`, `TabGroupActivation` -> `LyraTabGroupActivation`.

**`lr-virtual-list`:** Exported types renamed, TypeScript-only: `VirtualListRange` ->
`LyraVirtualListRange`, `VirtualListGroup` -> `LyraVirtualListGroup`, `VirtualListItemRole` ->
`LyraVirtualListItemRole`, `VirtualListRowHeight` -> `LyraVirtualListRowHeight`,
`VirtualListIndexedSource` -> `LyraVirtualListIndexedSource`, `VirtualListSource` ->
`LyraVirtualListSource`, `VirtualListScroll` -> `LyraVirtualListScroll`.

**`lr-split-panel`:** Exported types renamed, TypeScript-only: `SplitPanelOrientation` ->
`LyraSplitPanelOrientation`, `SplitPanelPrimary` -> `LyraSplitPanelPrimary`, `SnapFunctionParams` ->
`LyraSplitPanelSnapFunctionParams`, `SnapFunction` -> `LyraSplitPanelSnapFunction`,
`SplitPanelRepositionDetail` -> `LyraSplitPanelRepositionDetail`. The unused, undocumented
`SplitPanelSnapFunction` compatibility alias (of what is now `LyraSplitPanelSnapFunction`) is deleted
outright — import `LyraSplitPanelSnapFunction` directly. `SNAP_NONE` and the `<lr-split-panel>`
tag/runtime API are unchanged.

**`lr-widget`:** `LyraWidgetView.icon` widens from `TemplateResult` to `unknown`, matching
`LyraSegmentedItem.icon`/`LyraStepItem.icon`. Purely additive: an existing `TemplateResult` icon
value keeps working unchanged; a plain string, DOM node, or any other Lit-renderable value is now
also accepted.

## `lr-multi-split`

Resizable panels for dashboard layouts. Direct **light-DOM children are the panels**; a divider is
auto-inserted between each adjacent pair. Panels participating in persistence carry a unique,
nonempty, whitespace-stable `panel-id`; this business identity stays independent from the platform
`id` attribute and is never rewritten.

Feasible `minPx` floors also constrain flex shrinking after the divider target gutters take their
allocation: a 600px split with a 40px divider can render panels of 300px and 260px. If the floors
cannot fit, the remaining panel space is shared proportionally instead of overflowing. The budget
follows allocation and the actual divider geometry, including font-relative tokens resolved in the
divider's own font context. Panel font sizes do not change that gutter budget; stored percentages,
initialization precedence, and resize event values retain their existing meaning.

Granular import: `@aceshooting/lyra-ui/components/layout/multi-split/multi-split.js`.
The Lyra-original v9 identity migration is mechanical: `lr-split` → `lr-multi-split`,
`LyraSplit` → `LyraMultiSplit`, generic container authoring types → the corresponding
`LyraMultiSplit*` names, identity-specific `lr-split-*` events → `lr-multi-split-*`, and
`--lr-split-*` hooks/storage keys → `--lr-multi-split-*`/`lr-multi-split:*`. The separate mirrored
`lr-split-panel`, its `LyraSplitPanel` class, `SnapFunction`, and `SNAP_NONE` are unchanged.

With a definite block size, each direct panel owns a native `overflow: auto` scroll surface.
Unconstrained panels have a zero block minimum, so long content stays inside the split rather than
escaping into following content. Set `overflow` directly on an individual panel when its content
needs a different scrolling surface.

**Properties:**

- `sizes: number[] = []` (attribute: false — percentages per panel, auto-computed equally if
  omitted/mismatched)
- `defaultSizes: (number | string)[] = []` (attribute: false) — initialization-only fallback: a
  valid restored `storageKey` layout wins first; otherwise a valid `defaultSizes` wins over equal
  distribution. Initialization occurs on the first update so framework property bindings committed
  after connection in the same turn — including `defaultSizes` and `storageKey` — are honored
  before the layout becomes live. Later reassignment never overwrites live drag/persisted state —
  set it once, at mount. Each entry is either a plain **number** (percent-of-container, validated unchanged: a
  pure-number array that does not sum to ~100, e.g. `[30, 60]`, is still rejected and falls through
  to the equal split) or a CSS **length string** (`'200px'`, `'20%'`, `'3rem'`). When at least one
  entry is a length string, every entry is resolved through the public contextual
  `resolveCssLength()` utility (`%` against the measured container, `rem`/`em` against the
  owner-document/host, and `vw`/`vh` against the owner window), then normalized to percentages
  before the same validation applies — so `['200px', '300px']` on a 500px container initializes to
  `[40, 60]`.
- `min: number = 10` (min % per panel)
- `orientation: 'horizontal'|'vertical' = 'horizontal'` (reflected) — the axis used at/above
  `orientationBreakpoint` (or always, when that's unset).
- `orientationBreakpoint?: number | string` (attribute `orientation-breakpoint`) — opt-in inline-size
  breakpoint measured on `[part='base']`; unset (the default) means no behavior change at all, and
  no `ResizeObserver` is armed. Below it, `narrowOrientation` becomes the effective axis instead of
  `orientation`. Accepts a bare pixel number (`900`, `orientation-breakpoint="900"`) or a CSS length
  string: `'900px'`, `'56.25rem'`, `'3em'`. Under the default `orientationBreakpointBasis='container'`,
  `rem` resolves against the document root's **computed** font size (the rule a `@container` query
  follows) and `em` against this element's own computed font size. The length is **re-resolved on
  every measurement**, never cached at first render, so a root font-size change moves the crossing
  width with no invalidation step on the consumer's side. Anything that isn't a resolvable length
  behaves exactly as unset (no observation, no `data-effective-orientation`): `''`, `'auto'`,
  garbage, a non-finite number, and deliberately `%`, `vw`/`vh` and `calc()` — a viewport-relative
  threshold would mix reference boxes against a measurement of the element's own allocation. For a
  genuinely viewport-relative breakpoint set `orientationBreakpointBasis='viewport'` instead.
- `orientationBreakpointBasis: 'container'|'viewport' = 'container'` (reflected, attribute
  `orientation-breakpoint-basis`) — which box `orientationBreakpoint` is compared against. Unset,
  behavior is identical to before this property existed. `'container'` measures this component's own
  `[part='base']` via `ResizeObserver` and compares strictly `<`. `'viewport'` evaluates
  `matchMedia('(max-width: <breakpoint>)')` and arms no `ResizeObserver` for the orientation feature
  at all, so the shared observer stays armed only for `collapse`; its comparison is inclusive (`<=`),
  because that is what native `max-width` means — deliberate, so the crossing point matches a CSS
  `@media` rule authored with the same length exactly.
  **`rem`/`em` mean different things under the two bases, and this is the reason `'viewport'` exists.**
  Inside a media query, relative units resolve against the browser's _initial_ font size and ignore
  any `html { font-size }` override; under `'container'` they resolve against live computed font
  sizes. The two agree unless an app re-points the root font size. So when the breakpoint must stay
  in lockstep with a CSS `@media` rule, `'viewport'` is the exact match — the browser evaluates the
  same query, live, across browser zoom and user font-size preferences, with no px re-derivation.
- `narrowOrientation: 'horizontal'|'vertical' = 'vertical'` (reflected, attribute `narrow-orientation`)
- `effectiveOrientation: 'horizontal'|'vertical'` (readonly getter) — the live resize/layout axis
  actually in effect; identical to `orientation` whenever `orientationBreakpoint` is unset or
  doesn't resolve to a length. Also reflected as `data-effective-orientation` (only present while
  `orientationBreakpoint` resolves to a usable length).
- `storageKey?: string` (attribute `storage-key`) — persists a versioned list of `{ panelId, size }`
  records to `localStorage` under `` `lr-multi-split:${key}:panels` ``. Every direct panel must have
  a unique, nonempty, whitespace-stable `panel-id`; a missing, surrounding-whitespace, or duplicate identity fails persistence closed without
  disabling the live split. Restores and same-instance membership reconciliation follow `panelId`,
  so a reorder/replacement never transfers a saved size to a different business panel.
- `panelConstraints: (LyraMultiSplitPanelConstraint | null)[] = []` (attribute: false) — `LyraMultiSplitPanelConstraint { minPx?:
number; maxPx?: number; minPercent?: number; maxPercent?: number }`, index-aligned with `sizes`; a
  `null`/missing entry (or an omitted bound within an entry) leaves that side of that panel purely
  percent-based (the existing `min`-only behavior). Combining a px and a percent bound on the same
  side resolves to the stricter one (larger for min, smaller for max) via a native CSS `max()`/`min()`
  in the rendered `clamp()` flex-basis. `sizes`, the `lr-resize` payload, and localStorage persistence
  stay percent-based regardless — only the effective drag/keyboard clamp bounds (and the rendered
  `flex-basis`, via a native CSS `clamp()` across container resizes) change for a constrained panel.
  Pixel minimums also account for live divider dimensions. Bounds on neighboring panels remain
  active during collapse transitions, including when constraints are updated from an
  `lr-multi-split-collapse-change` handler.
- `collapse: 'start'|'end'|'none' = 'none'` (reflected) — opt-in responsive collapse for one panel:
  `'start'`/`'end'` is a _logical_ position (RTL-aware, matching CSS logical properties — the panel at
  the document's visual leading/trailing edge, not a raw array index). `lr-multi-split` only owns the
  width-collapse mechanics/state signaling below; it renders no icon-only UI itself — the collapsing
  panel's own slotted content is expected to adapt itself (e.g. via its own `@container` query reading
  the panel's clamped width or `data-collapse-state`, see below).
- `railWidth: string = '3.5rem'` (attribute `rail-width`) — the fixed CSS length the collapsing panel
  clamps to in `'rail'` state.
- `railBreakpoint: number | string = 640` (attribute `rail-breakpoint`) — below this width, the
  collapsing panel switches from its normal drag-resizable percent width to the fixed `railWidth`.
  Accepts a bare pixel number (`640`, `rail-breakpoint="640"` — the original form) or a CSS length
  string: `'640px'`, `'68.75rem'`, `'3em'`. Under the default `collapseBreakpointBasis='container'`
  it is compared against this component's own measured `[part='base']` inline size (a
  `ResizeObserver`, active only while `collapse !== 'none'`), and `rem` resolves against the
  document root's **computed** font size while `em` resolves against this element's own; the length
  is re-resolved on every measurement, never cached. Anything the grammar rejects — `''`, `'auto'`,
  garbage, a non-finite number, and deliberately `%`, `vw`/`vh`, `calc()` and `var()` — falls back
  to the `640` default rather than switching the feature off (unlike `orientationBreakpoint`, this
  breakpoint has a documented default to fall back to). A negative length is floored at `0`, i.e.
  never crossed. Must stay above `floatBreakpoint` — an inverted pair is sanitized by raising this
  one to match, collapsing the `'rail'` band away rather than reporting a wide container as
  collapsed.
- `floatBreakpoint: number | string = 400` (attribute `float-breakpoint`) — below this narrower
  width, the collapsing panel instead becomes an absolutely-positioned overlay ("floating card") on
  top of the other pane(s), removed from the normal flex flow; the sibling(s) take the full width.
  Same accepted forms, basis, and sanitization as `railBreakpoint`; an unparseable value falls back
  to the `400` default.
- `collapseBreakpointBasis: 'container'|'viewport' = 'container'` (reflected, attribute
  `collapse-breakpoint-basis`) — which box `railBreakpoint`/`floatBreakpoint` are measured against.
  Unset, behavior is identical to before this property existed. `'container'` observes this
  component's own `[part='base']` inline size via `ResizeObserver` and compares strictly `<`;
  `'viewport'` evaluates `matchMedia('(max-width: <breakpoint>)')` for each of the two thresholds,
  which is inclusive (`<=`) — native `max-width` semantics, deliberately, so the crossing point
  matches a CSS `@media` rule authored with the same length exactly. Use `'viewport'` to collapse in
  step with a page-level responsive layout (a shell whose own `@media` rules restack at the same
  width) rather than with this split's own allocation; it is also what lets the browser resolve a
  `rem` breakpoint with real `@media` semantics (against the _initial_ font size, ignoring an
  `html { font-size }` override). Both bands are classified from both queries together on every
  change, so a fast resize crossing both thresholds at once still lands on one correct state and
  fires `lr-multi-split-collapse-change` once; under `'viewport'` the first paint is already correct — no
  `ResizeObserver` round-trip — and that initial state is not announced as a transition.
- `collapseState: 'wide'|'rail'|'floating'` (reflected, attribute `collapse-state`) — a public
  accessor with force/auto semantics mirroring `<lr-app-rail>`'s `mode`: normally derived
  automatically from the measured container width, but assigning it a concrete value pins it there
  (stopping automatic breakpoint tracking) — useful for a consumer-driven toggle (e.g. a button that
  forces `'floating'` regardless of width). Assigning the write-only `'auto'` sentinel releases the
  pin and immediately re-derives the state from the current measured width; the getter never returns
  `'auto'`. This is an **effective** state: while `collapse='none'` or fewer than two panels exist,
  the getter/reflected attribute stays `'wide'` and forced rail/floating intent produces no event,
  marker, backdrop, focus trap, or scroll lock. Enabling an eligible pane can make retained forced
  intent effective; disabling/removing it transitions back to `'wide'`, closes `open`, releases
  overlay ownership, and restores focus.
- `open: boolean = false` (reflected) — whether the `'floating'` collapse state's drawer is shown.
  While `collapseState` is `'floating'` and `open` is `false` (the default), the collapsing panel
  renders nothing (`hidden`, out of the accessibility tree) instead of the always-visible overlay
  card this state rendered before `open` existed — not just visually hidden; this holds even
  against an author `display` rule targeting the panel directly. Setting `open = true` reveals it as a
  focus-trapped floating panel with a `[part="backdrop"]` scrim; Escape or a backdrop click set
  proposes a cancelable close before changing `open`. While open, the floating panel is the modal root and every sibling pane
  behind it is inert. Leaving `'floating'` while `open` is still `true` also closes it, the same
  way `<lr-app-rail>` closes its mobile overlay when leaving `'mobile'` while open.
- `releasePinOnBreakpoint: boolean = false` (attribute `release-pin-on-breakpoint`, reflected) — opts a
  pinned `collapseState` in to releasing itself when the layout it was made for is gone: either the
  measured collapse band changes to a different one than the pin was made in, or
  `effectiveOrientation` crosses `orientationBreakpoint`. The pin is dropped exactly as if `'auto'`
  had been assigned and the state re-derives from the current measurement, firing
  `lr-multi-split-collapse-change` when that is a real transition. Re-measuring the same band never
  releases a pin, so ordinary resizing inside one band leaves it alone. Left unset (the default), a
  pin survives every band and orientation change until a consumer writes `'auto'` — the pre-existing
  behavior.

**Methods:** `expandPane()`, `collapsePane()` and `togglePane()` drive the collapse feature
semantically, each picking the mechanism the pane's *current band* provides rather than its pinned
state: inside the `floatBreakpoint` band that is the overlay drawer (`open`), above it it is the
`collapseState` pin (`'wide'` expanded, `'rail'` collapsed). `togglePane()` reads the pane's current
presentation — `'wide'` counts as expanded, `'rail'` as collapsed, `'floating'` as expanded exactly
while `open` — so toggling a pane pinned to `'rail'` after the container narrowed into the floating
band opens the drawer instead of doing nothing visible. All three are no-ops while `collapse='none'`
or fewer than two panels exist, none creates a pin the band already produces, and a pin one of them
cancels is released rather than replaced, so an expand/collapse cycle leaves automatic breakpoint
tracking as it found it. They emit no `lr-toggle`, matching the existing rule that a direct `open`
write does not. They are named `…Pane()` rather than `expand()`/`collapse()`/`toggle()` because
`collapse` is already the pane-selection property, following `<lr-page>`'s `showNavigation()` trio.
The component still renders no trigger of its own — wire these to your own control.

`collapse`'s three resulting states — `'wide'` (default, today's plain layout) / `'rail'` / `'floating'`
— are exposed as: a `data-collapse-state` attribute on both the host and the collapsing panel element
itself (absent for `'wide'`/`collapse="none"`); and the `lr-multi-split-collapse-change` event below. The
divider adjacent to the collapsed panel is drag/keyboard-disabled (`aria-disabled="true"`) while
collapsed. `collapse="none"` (the default) is byte-for-byte identical to pre-collapse-feature behavior.

`dividerLabel?: (index: number, panelCount: number) => string` (attribute: false) customizes the
localized accessible label generated for each auto-inserted divider.

**Events:** `lr-resize-request` (cancelable; `detail: { sizes }` is the proposed constrained size
array from a divider drag or keyboard step. Call `preventDefault()` to leave `sizes` and its
persisted layout unchanged. It is not emitted when a consumer assigns `sizes` directly or a
keyboard/pointer proposal clamps to the already-current sizes),
`lr-resize` (non-cancelable; the same `detail: { sizes }`, emitted after an accepted drag movement
or keyboard step commits. A genuine pointer gesture has one terminal persistence write on
`pointerup`; no-move, fully clamped, vetoed, canceled, and lost-capture gestures have none. Pointer
release emits no additional event; direct `sizes` assignments stay silent),
`lr-multi-split-collapse-change` (`detail: { state: 'wide'|'rail'|'floating' }`, fired only
on a real `collapse`-state transition, never on every resize/render. It fires *after* the collapsing
panel is decorated for the new state — its `data-collapse-state` marker, the closed drawer's `hidden`
flag and its owned inline sizing are all applied first — so a listener can read the panel
synchronously inside its own handler instead of deferring past `updateComplete`. Focus is also moved
out of a pane the new state hides (`'floating'` while closed) or clamps (`'rail'`) before the event
fires, landing on the first surviving pane that can take it, otherwise on the split's own divider;
focus anywhere other than the collapsing pane is untouched),
`lr-toggle` (`detail: LyraMultiSplitToggleDetail = { open: boolean }`) — Escape/backdrop close
proposals are cancelable and fire before `open` changes; preventing the event or making a synchronous
reentrant mutation aborts the proposal. A forced close when a responsive collapse transition leaves
`floating` fires noncancelably after `open` is false. Direct `open` writes and no-op dismissals are silent,
`lr-multi-split-constraints-invalid` (`detail: LyraMultiSplitConstraintIssueDetail`, fired once when the configured
panel minimums/maximums cannot fit the track; the infeasible set is rejected for interaction and a
normalized percent minimum is used instead), `lr-multi-split-orientation-change` (`detail: { orientation }`,
fired only when an enabled `orientationBreakpoint` actually changes `effectiveOrientation`)

**Slots:** default (each direct child element is one panel; set a unique `panel-id` on every child
when `storage-key` is used).

**CSS parts:** `base` (`position: relative`, so the `'floating'` state can anchor to it), `divider`
(carries `aria-disabled="true"` and is drag/keyboard-inert while its adjacent panel is collapsed),
`backdrop` (the `'floating'` drawer's scrim — only rendered while `collapseState === 'floating'` and
`open`)

**Themeable custom properties:** `--lr-multi-split-overlay-color` (default `var(--lr-color-overlay)`) —
the `'floating'` drawer's `[part='backdrop']` scrim; scoped to `[part='base']`, not the viewport.
`--lr-multi-split-divider-target-size` (default
`max(var(--lr-icon-button-size), var(--lr-size-3px))`) — the real flex track/gutter reserved for the
divider along the resize axis. The visual rule is painted in its center; no pseudo-element
extends into either adjacent panel, so slotted controls retain pointer ownership up to their edge.
Set it on an ancestor to retune a split subtree or directly on one component; either public value
remains authoritative.
`--lr-multi-split-divider-thickness` (default `var(--lr-size-3px)`) sets the painted hairline's own
width, independent of `--lr-multi-split-divider-target-size` above — retuning one never changes the
other, so the WCAG 2.5.8 pointer target can never be shrunk by a thinner or thicker visual line.
`--lr-multi-split-divider-color` (default `var(--lr-color-border)`),
`--lr-multi-split-divider-hover-color` (default `var(--lr-color-brand)`), and
`--lr-multi-split-divider-active-color` (default
`color-mix(in oklab, var(--lr-color-brand), var(--lr-color-mix-partner) var(--lr-color-mix-active))`)
theme the divider hairline's resting/hover/pressed color; the active color is only reachable while a
resize gesture is pressed (pointer capture holds `:active` for the whole gesture).
`--lr-multi-split-floating-panel-inline-size` overrides the `'floating'` collapse state's overlay
card `inline-size`, which otherwise mirrors its own live `sizes[i]` percent (i.e. what it renders
at in the `'wide'` state, so un-floating never jumps). Unset, the rendered geometry is unchanged;
set (e.g. on an ancestor), it wins over that percent at ordinary specificity, with no `!important`
needed against the inline style the component rewrites on every render.
`--lr-multi-split-floating-panel-inset` (default `0`) sets the `'floating'` drawer's distance from
`[part="base"]`'s edges, applied to both block insets and to whichever logical inline edge
`collapse` anchors the drawer to, so one declaration insets all three anchored edges; the free inline
edge stays governed by the panel's own width. Unset, the drawer is flush with its container exactly
as before.
Otherwise shared tokens only.

**Optional peer deps:** none.

```html
<lr-multi-split storage-key="dashboard-main" min="15">
  <div panel-id="navigation">Panel A</div>
  <div panel-id="content">Panel B</div>
  <div panel-id="inspector">Panel C</div>
</lr-multi-split>
```

Keyboard: focus a divider (`Tab`), then `ArrowRight`/`ArrowLeft` (horizontal) or
`ArrowDown`/`ArrowUp` (vertical) to resize by a fixed 2% step — RTL-aware for horizontal layouts
(under `direction: rtl`, the forward/backward keys and drag-delta sign both swap so they still track
the visually-adjacent panel). Home and End jump directly to that divider's current achievable
minimum and maximum, including per-panel px/percent constraints.

**Known gotchas:**

- Panel membership tracks the complete ordered direct-child identity sequence, not just its count.
  Same-count `replaceWith()` and DOM reorder immediately reconcile visual order with DOM/AX order
  while preserving sizes by `panel-id`; count changes retain existing panels' relative proportions
  and allocate an equal share to each new identity. Without a complete unique `panel-id` set, the
  live layout retains the positional fallback but persistence is deliberately disabled. Every temporary
  inline layout/collapse declaration, `hidden`, and `data-collapse-state` value is
  snapshot/adopt/restore-owned, so late author writes survive removal, disconnect/adoption, reuse,
  and reconnect without stale multi-split state.
- divider `aria-valuemin`/`aria-valuemax` are computed per adjacent pair from the same resolved
  `panelConstraints` bounds used by pointer and keyboard resizing, rather than a blanket
  `100 - min`. They therefore remain accurate for 3+-panel layouts and for px/percent constraints.
  Each divider also has its own `aria-label` ("Resize divider between panel N and panel N+1")
  distinguishing it from any other divider in a multi-divider layout.
- infeasible aggregate constraints (for example, three panels with `min=40`) are reported through
  `lr-multi-split-constraints-invalid`; interaction rejects that set and uses a normalized percent minimum
  with aggregate slack, so the divider remains operable instead of silently freezing.
- concurrent drags are tracked per `pointerId` (not a single scalar), so a multi-touch drag on two
  different dividers moves both independently instead of the second pointer clobbering the first's
  drag state; `pointercancel`/`lostpointercapture` (not just `pointerup`) both end a drag.
- `localStorage.getItem`/`setItem` calls are now both wrapped in their own `try`/`catch` (in addition
  to the `JSON.parse` result already being caught), so a blocked or quota-exceeded store fails
  silently instead of throwing from inside a `pointerup`/`keydown` handler. A malformed/duplicate
  identity record or layout whose sizes are already below the current `min` floor is rejected rather
  than restored.
- Pointer-drag lifecycle (pointer capture, window-listener cleanup on both drag-end and
  `disconnectedCallback`) is solid and safe to rely on.
- `orientationBreakpoint` shares its `[part='base']` `ResizeObserver` with `collapse` (one observer,
  not two) — arming logic covers either feature being opted into independently.
- **Switching a basis moves the crossing point by exactly 1px.** Container basis compares strictly
  `<` against a measured width; viewport basis asks `matchMedia('(max-width: …)')`, which is
  inclusive (`<=`). So at a breakpoint of `640`, a container-basis split is still `'wide'` at 640px
  while a viewport-basis one has already collapsed. This is deliberate on both sides: `<` is the
  right comparison for "how much room do I actually have", and `<=` is what a CSS `@media` rule with
  the same length does, which is the whole point of the viewport basis.
- `collapseBreakpointBasis='viewport'` does **not** drop the `ResizeObserver` the way the
  orientation feature's viewport basis does. The measured width it feeds is still read by a
  container-basis `orientationBreakpoint` and by the `collapseState = 'auto'` release path, which
  re-derives from the current measured width. Collapse's basis changes only _which values_ the
  classification consults, never whether the split measures itself.
- `railBreakpoint`/`floatBreakpoint` are typed `number | string`. Authored as attributes they read
  back as **strings** (`el.railBreakpoint === '640'`, not `640`) — the same value, a different type.
  Compare with `Number(el.railBreakpoint)` rather than `===`, or assign the property directly when a
  numeric identity matters.
- **Picking a basis.** `orientationBreakpointBasis='container'` (the default) observes the
  component's own allocated inline size, so it fits a component that is the sole flex/grid item in
  the container being measured. It does **not** fit a component sitting beside a fixed-width sibling
  in a row that stacks via a CSS `@media` rule: while the row is a row, this element's width shrinks
  with the viewport; the instant the row stacks (a pure-CSS event no component can observe) it jumps
  to the _full_ row width — wider than it was just before the transition. Because the measured width
  is not monotonic across that transition, no single container threshold both stays wide while the
  row is a row and goes narrow exactly when it stacks. A fixed-width sibling is worse still: its own
  width never changes with the viewport at all, so no container breakpoint on it can react to the
  stacking.
  That layout is what `orientationBreakpointBasis='viewport'` is for. Give every sibling the same
  `orientation-breakpoint` and `orientation-breakpoint-basis='viewport'` and they flip together, in
  lockstep with the CSS rule that stacks the row:
  ```html
  <lr-stepper
    orientation-breakpoint="56.25rem"
    orientation-breakpoint-basis="viewport"
  ></lr-stepper>
  <lr-multi-split
    orientation-breakpoint="56.25rem"
    orientation-breakpoint-basis="viewport"
  ></lr-multi-split>
  <style>
    @media (max-width: 56.25rem) {
      .shell {
        flex-direction: column;
      }
    }
  </style>
  ```
  A consumer-side `matchMedia()` controller driving the `orientation` attribute directly is still
  supported and still correct — it is simply no longer required for this case.

---

## `lr-split-panel`

Accessible two-pane resizing with the public `wa-split-panel` / `sl-split-panel` contract. Use this
component when migrated markup has named `start` and `end` panes. The separate `<lr-multi-split>` is
Lyra's multi-panel layout: its direct default-slot children, responsive collapse modes, and
multi-divider events are intentionally a different API.

Both `lr-reposition-request` detail fields `position` and `positionInPixels` measure from the
selected primary edge and agree with accepted public property readback, including `primary="end"`.
Canceling preserves both prior values; direct property writes remain silent.

**Properties:**

- `position: number = 50` (reflected) — divider position from the selected `primary` pane's edge,
  as a percentage from 0–100. With no `primary`, the logical `start` pane is the reference.
- `positionInPixels: number` (attribute `position-in-pixels`) — the same position in pixels.
  Assigning either position updates the other after the component has a layout box; both remain
  synchronized after pointer/keyboard changes and host resizes.
- `orientation: 'horizontal'|'vertical' = 'horizontal'` (reflected) — side-by-side panes or stacked
  panes. `vertical: boolean = false` (reflected) is the synchronized Shoelace spelling: setting
  either API updates the other. If both attributes occur in initial markup, the canonical
  `orientation` attribute wins.
- `disabled: boolean = false` (reflected) — makes the divider pointer/keyboard-inert and removes it
  from the tab order. Host resizing can still update synchronized position values.
- `primary?: 'start'|'end'` — when unset, the panes resize proportionally and `position` stays fixed
  as the host changes size. When set, that pane keeps its pixel size and the other pane absorbs the
  resize. Position values are always measured from the selected primary edge.
- `snap: string | SnapFunction = ''` — pointer-drag snap behavior. A string accepts space-separated
  pixels, percentages, and repeat expressions (`'160px 50% repeat(100px)'`) and reflects to the
  `snap` attribute. It parses and caches the numeric value/unit projection from at most the first
  16,384 UTF-16 code units and 256 finite valid tokens; later source text cannot affect snapping. A property-bound
  `SnapFunction` receives `{ pos, size, snapThreshold }` in pixels and returns the desired pixel
  position; callback code decides how to use the supplied threshold. The setter also accepts
  `undefined` for mapped source compatibility, clearing the configuration to the canonical `''`
  read value. Function and empty values remove the serializable attribute.
- `snapThreshold: number = 12` (attribute `snap-threshold`) — maximum pixel distance at which a
  string snap point takes effect. Non-finite values fall back safely and negative values clamp to
  zero.

**Events:** `lr-reposition-request` (cancelable; `detail: SplitPanelRepositionDetail`, where
`{ position, positionInPixels }` is the final snapped and constrained proposed position measured
from the selected `primary` pane's edge. Call `preventDefault()` to leave both position properties
unchanged. It is not emitted when a consumer assigns `position` or `positionInPixels` directly),
`lr-reposition` (non-cancelable, no detail) — bubbling and composed, emitted after an accepted
pointer or keyboard interaction commits the divider position; direct property assignments stay
silent.

**Slots:** `start` (logical start pane), `end` (logical end pane), `divider` (optional decorative
custom-handle content inside the separator; its assigned subtree is inert, so the separator remains
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
`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).

**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`
(default `0`) and `--max` (default `100%`) for the primary pane, or the start pane when no primary is
selected. Lyra-prefixed aliases are `--lr-split-panel-divider-width`,
`--lr-split-panel-divider-hit-area`, `--lr-split-panel-min`, and `--lr-split-panel-max`; when both
spellings are set, the Lyra-prefixed value wins. Constraint values may be lengths, percentages, or
`calc()` expressions and are re-applied when their computed sizes change.

`--lr-split-panel-divider-hover-color` (default `var(--lr-color-brand)`) is the divider's background
on hover/keyboard focus. `--lr-split-panel-divider-active-color` (default
`var(--lr-color-border-strong)`) is its background while being dragged, or focused and pressed via
the keyboard. Both are independent, component-scoped hooks rather than the bare shared token, so
retinting this divider does not also retint any other component that happens to default to the same
color.

Keyboard: focus the divider, then use Left/Right for a horizontal split or Up/Down for a vertical
split. Each arrow moves one percent of the current allocation; horizontal arrows mirror under RTL.
`Home` and `End` move to the current `--min` and `--max` bounds. Pointer dragging uses capture and
cleans up on pointer up, cancellation, capture loss, disconnect, and orientation changes.

**Optional peer deps:** none.

```js
import "@aceshooting/lyra-ui/components/layout/split-panel/split-panel.js";
```

```html
<lr-split-panel
  primary="start"
  position-in-pixels="240"
  snap="25% 50% 75%"
  aria-label="Resize editor panes"
  style="block-size: 20rem; --min: 10rem; --max: 30rem"
>
  <nav slot="start" aria-label="Files">…</nav>
  <main slot="end">…</main>
  <span slot="divider" aria-hidden="true">⋮</span>
</lr-split-panel>
```

**Known gotchas:** a vertical split needs a definite block size so percentages have an axis to
resolve against. `snap` callbacks are JavaScript functions and must be assigned as properties, not
serialized into an HTML attribute. The visible divider can remain narrow because its transparent
hit region expands independently; use `--divider-width` for the painted line and
`--divider-hit-area` for the requested interaction region.

---

## `lr-widget`

A titled panel shell with an optional collapse toggle and an optional fullscreen-expand toggle.
First-party invention (no `wa-*`/`sl-*` counterpart). Fullscreen promotes the same host element in
place (a CSS state, not a clone/portal), so slotted content (a chart, a running simulation, scroll
position) survives the transition.

**Properties:**

- `label: string = ''` — header title; a removed attribute renders as absent while preserving
  `null` readback. Supplied empty strings remain empty and later values recover normally.
- `sublabel: string = ''` — secondary header copy with the same removal, empty-string and recovery
  behavior.
- `collapsible: boolean = false` (reflected — shows the collapse/expand chevron button)
- `collapsed: boolean = false` (reflected)
- `expandable: boolean = false` (reflected — shows the fullscreen toggle button)
- `fullscreen: boolean = false` (reflected)
- `fullscreenInset: string = ''` (attribute `fullscreen-inset`) — CSS `inset` shorthand applied to
  `[part="base"]` while fullscreen instead of the default per-side
  `max(var(--lr-space-l), <safe-area inset>)`, e.g. `"0 0 0 240px"` to leave a 240px persistent
  sidebar/toolbar visible during fullscreen. Invalid values, declaration-breaking input, and
  `url()` are ignored.
- `compact: boolean = false` (reflected) — tighter header/body padding, same convention as
  `lr-empty`'s `compact`
- `backdropInset: string = ''` (attribute `backdrop-inset`) — overrides the fullscreen backdrop's
  CSS `inset`; when empty or invalid, the backdrop remains viewport-filling (`0`) independently of
  `fullscreenInset`
- `views: readonly LyraWidgetView[] = []` (attribute: false) — named alternate views for the panel body, e.g. a
  chart/table toggle inside the same card chrome; `LyraWidgetView { viewId: string; label?: string; icon?:
TemplateResult; ariaLabel?: string }`. Each entry gets a header toggle button
  (`[part='view-toggle']`) and a `<slot name="view-${viewId}">`. An icon-only view should set
  `ariaLabel`; if both labels are omitted, the button uses `viewId` as a last-resort accessible name.
  Empty (the default) renders today's single unnamed default slot as the sole view, unchanged.
  Up to 256 valid records are snapshotted; IDs must be unique, nonempty, and whitespace-stable.
  Malformed/hostile entries are ignored without rejecting the component update.
- `activeViewId: string = ''` (attribute: false) — the currently active view's `viewId`; defaults to the
  first entry of `views` (or `''` when `views` is empty). Settable directly to control the active
  view externally; also updated internally when a view toggle is clicked. `activeView`, a
  deprecated alias that seeded this property, was removed in 16.0.0 (available since 11.2.0;
  eligible for removal from 13.0.0) — use `activeViewId`.
- `accessibleLabel: string | null = null` (attribute `aria-label`) — overrides the label-derived
  fullscreen dialog name. An explicitly empty value is retained; property, slotted-label, and
  localized fallbacks apply only when it is absent.
- `storageKey?: string` (attribute `storage-key`) — when set, persists `collapsed` to `localStorage`
  under `lr-widget:${storageKey}` and restores it on the next mount, without overwriting a
  `collapsed`/`.collapsed=${…}` binding already assigned on that same mount — including one that
  assigns `false`, the default. The restore runs once, before the first paint, and is skipped for
  any property the consumer assigned; `lr-app-rail` and `lr-table` share the same mechanism. Without
  a `storageKey` there is no persistence and storage is never touched — listen for
  `lr-collapse-change` and persist the state yourself.

**Events:** `lr-collapse-request` (cancelable; `detail: { collapsed }` is the state proposed by the
built-in collapse toggle. Call `preventDefault()` to leave `collapsed` and any persisted state
unchanged. It is not emitted when a consumer assigns `collapsed` directly), `lr-collapse-change`
(non-cancelable; `detail: { collapsed }` is the accepted built-in-toggle state. It is not emitted
when a consumer assigns `collapsed` directly), `lr-fullscreen-request` (cancelable; `detail: {
fullscreen }` is the state proposed by the fullscreen toggle, Escape, or a backdrop click. Call
`preventDefault()` to leave `fullscreen` unchanged. Not emitted when a consumer assigns
`fullscreen` directly), `lr-fullscreen-change` (non-cancelable; `detail: { fullscreen }` is the
accepted state — also fired when fullscreen is exited via Escape or a backdrop click, not just the
toggle button. Not emitted when a consumer assigns `fullscreen` directly), `lr-view-request`
(cancelable; `detail: { viewId }` is the view proposed by a header view-toggle click. Call
`preventDefault()` to leave `activeViewId` unchanged. Not emitted when a consumer assigns
`activeViewId` directly), `lr-view-change` (non-cancelable; `detail: { viewId }`, the accepted
active view's `viewId`. Not emitted when a consumer sets `activeViewId` directly), and
`lr-activate` (non-cancelable; `detail: { value }` — note the key is `value`, not `viewId` — is the
activated view's `viewId`, fired on **every** accepted header view-toggle activation whether or not
`activeViewId` actually moved. `lr-view-request` stays the veto point, and a vetoed activation emits
no activation at all. Use it for the repeat pick `lr-view-change` deliberately stays silent for —
"rebuild that view" is a real intent — which is otherwise unobservable, because the toggles live in
this shadow root, so a retargeted `click` names no view. When an activation _does_ move the view,
`lr-view-request` and `lr-view-change` are emitted first. Not emitted when a consumer sets
`activeViewId` directly)

**Slots:** default (the panel body, rendered only while `views` is empty), `icon` (optional leading
icon in the title row; its flattened subtree is inert and aria-hidden), `label` (rich label content,
overrides the `label` attribute), `sublabel` (rich sublabel content, overrides the `sublabel`
attribute), `actions` (header action controls,
rendered before the collapse/expand buttons), `collapse-icon` (replaces the built-in chevron in the
collapse toggle via native slot fallback; its assigned content is decorative, inert, and aria-hidden
so the outer toggle remains the only action. The whole button rotates while expanded, so use a
collapsed/right-facing baseline for a directional override; only meaningful while `collapsible`),
`fullscreen-icon` (replaces the built-in glyph in the fullscreen toggle — the override replaces
_both_ the "expand" and "exit fullscreen" defaults, so the consumer owns that distinction, e.g. by
reading the `fullscreen` attribute; its assigned content is decorative, inert, and aria-hidden so
the outer toggle remains the only action; only meaningful while `expandable`), and one `view-{viewId}`
slot per `views` entry, used instead of the default slot

**CSS parts:** `base`, `header`, `title`, `icon` (wrapper around the `icon` slot, hidden entirely when
empty), `label-group` (wrapper around the label and sublabel), `label`, `sublabel`, `actions`,
`view-toggles` (the header toggle-button group, only rendered when `views` is non-empty),
`view-toggle` (a single view toggle button), `view-icon` (a decorative view glyph whose rendered
subtree is inert and aria-hidden, leaving the toggle as the sole action), `view-label`
(a view's visible label), `collapse-button`, `fullscreen-button`, `body`, `backdrop`

Both header rows (`actions` and `view-toggles`) scroll horizontally on their own when the header is
too narrow for them, and each independently paints a `--lr-scroll-fade-size` edge fade while — and
only while — it actually overflows, so a clipped row reads as scrollable rather than truncated. The
overflow is measured, not assumed: a row that fits is left unmasked.
Forced-colors mode disables those decorative masks while retaining the native scroll owners. The
body is the block-axis scroll owner whenever the widget receives a constrained height, so the
header remains fixed while deep body content scrolls.

**Themeable custom properties:** `--lr-widget-overlay-color` (default `var(--lr-color-overlay)` —
the fullscreen backdrop scrim color), `--lr-widget-fullscreen-inset` (default per side
`max(var(--lr-space-l), <safe-area inset>)` — the fullscreen `[part="base"]` inset; the
`fullscreen-inset` attribute overrides it), and `--lr-widget-backdrop-inset` (defaults to `0` so
the modal backdrop covers the viewport; the `backdrop-inset` attribute overrides it), plus shared
tokens (`--lr-space-*`, `--lr-color-border/-surface/-text-quiet`,
`--lr-radius`, `--lr-shadow`, `--lr-icon-button-size`, `--lr-focus-ring-*`).

Three properties style the pressed view toggle: `--lr-widget-view-toggle-active-bg` (default
`var(--lr-color-brand-quiet)`) and `--lr-widget-view-toggle-active-color` (default
`var(--lr-color-brand)`), plus `--lr-widget-view-toggle-active-border-color` (default
`transparent`) — the background, text, and border color of the `aria-pressed="true"` toggle. All three
are **state hooks**: declared as inline `var()` fallbacks at the point of use and never on `:host`,
so setting any of them on the element _or on any ancestor_ reaches the toggle. That shape exists because
`::part(view-toggle)[aria-pressed='true']` is not valid CSS — Shadow Parts forbids an attribute
selector after `::part()` — so before these hooks the only way to recolor an active toggle was to
override the library-wide `--lr-color-brand-quiet`/`--lr-color-brand` tokens, repainting every other
element that reads them. Left unset, each falls back to exactly the token the rule used before, so
rendering is unchanged.

`--lr-widget-view-toggle-hover-bg` (default `var(--lr-color-brand-quiet)`) and
`--lr-widget-view-toggle-hover-color` (default `var(--lr-color-text)`) are the same shape for the
_hover_ state, and the `:hover` rule wraps its selector in `:where()` so a consumer's own
`::part(view-toggle):hover` override wins without `!important`.

**Optional peer deps:** none.

```html
<lr-widget label="Load profile" sublabel="Last 7 days" collapsible expandable>
  <span slot="actions"><button>Refresh</button></span>
  <div>Panel body content — a chart, a table, anything.</div>
</lr-widget>
```

While `fullscreen`, `[part="base"]` (not the host itself) takes `role="dialog"` + `aria-modal="true"`
(with `aria-label`, including an explicitly empty value, taking precedence; otherwise the `label`
property, slotted label, then `"Fullscreen panel"` supply the name), document scroll is locked
(ref-counted, safe with multiple simultaneously-fullscreen widgets), and Tab/Shift+Tab are bounded
to the panel's own focusable content (`actions` slot → collapse/fullscreen buttons → body slot,
matching visual tab order — resolved shadow-piercingly, so a slotted custom element's real
focusable target inside its own shadow root is found too) so keyboard focus can't escape to page
content hidden behind the backdrop. Escape or clicking the backdrop exits fullscreen and returns
focus to whichever button triggered it. Set `fullscreen-inset` (e.g. `"0 0 0 240px"`) to reserve
panel space for a persistent sidebar/toolbar while the default backdrop still covers the complete
viewport. Set `backdrop-inset` explicitly only when the scrim should leave the same frame open. Set
`compact` for tighter header/body padding.

The collapse-button `aria-label` is localized via its own `widgetCollapse` (default `'Collapse
panel'`) and `widgetExpand` (default `'Expand panel'`) keys.

**Known gotchas:**

- a reconnect that preserves the same element instance (e.g. a drag-and-drop reparent) resumes its
  shared overlay registration and re-acquires the scroll lock if `fullscreen` was still `true`
  across the move — `disconnectedCallback`/`connectedCallback` fire back-to-back with no update in
  between, so `willUpdate()` alone wouldn't otherwise notice.
- `collapsed` hides the body via `hidden` rather than an animated height transition — collapsing is
  instant, not a slide.
- an explicit `collapsed` assignment before the first update — an attribute, a property, or a
  framework binding, including one that pins the property to its own default `false` — always wins
  over a `storageKey`-restored value for that mount, and skips the restore entirely. For
  uncontrolled persistence, don't bind `collapsed`: read the restored value back after
  `updateComplete` and track further changes from `lr-collapse-change`, pushing the property down
  imperatively only for later external changes.
- prior to this release the collapse-button `aria-label` was localized through `lr-dock-panel`'s
  own `dockPanelCollapse`/`dockPanelExpand` keys (a borrowed, differently-named pair). A locale
  registered against those keys specifically to target `lr-widget`'s collapse button should move
  to `widgetCollapse`/`widgetExpand`; the default English strings are unchanged, and `lr-dock-panel`
  itself is unaffected.

**Additional API surface:**

- `part="view-icon"` — Decorative icon content inside a view toggle.
- `part="view-label"` — Visible label text inside a view toggle.

---

## `lr-carousel`

Accessible scroll-snap carousel for arbitrary slotted slide elements. Mirrors `wa-carousel` /
`sl-carousel`, including their opt-in navigation and pagination, multi-slide pages, logical
orientation, autoplay, loop, mouse dragging, slots, methods, parts, and custom properties. Slide
semantics (`role="group"`, a localized "slide" role description, and a localized "Slide N of M"
label) are added only to `<lr-carousel-item>` children. An arbitrary slotted element keeps its own
native or authored semantics, and an explicit `role`, `aria-roledescription`, or `aria-label` on an
`<lr-carousel-item>` wins over generated metadata. Later author changes to those attributes and to
`hidden`, `inert`, or `aria-hidden` remain in effect across carousel updates. The carousel
temporarily makes off-page slides inert and aria-hidden, then restores their retained author state
when they become visible, are removed, or the carousel disconnects.

**Keyboard:** focus the `scroll-container` viewport to navigate with Arrow keys (horizontal LTR/RTL
or vertical), Home, and End. Keys originating in a native input, textarea, contenteditable surface,
or supported custom control remain owned by that editor, including when the editor is the assigned
slide itself; they do not change the active slide or move focus away from it.

**Properties:**

- `currentSlide: number = 0` (attribute `current-slide`, reflected) — zero-based index of the first
  slide in the active page. The pinned Web Awesome markup spelling `currentSlide` is also accepted
  through HTML's normalized
  `currentslide` attribute as a permanent compatibility alias. When both spellings are present on
  initial markup, canonical `current-slide` wins.
- `loop: boolean = false` (attribute `loop`, reflected) — wraps navigation at either end
- `autoplay: boolean = false` (attribute `autoplay`, reflected) and
  `autoplayInterval: number = 3000` (attribute `autoplay-interval`) — optional timed advance.
  Autoplay pauses while the page is hidden or the user is hovering, focusing, or dragging the
  carousel, and remains off under `prefers-reduced-motion: reduce`.
- `navigation: boolean = false` (attribute `navigation`, reflected) — renders previous and next
  buttons
- `pagination: boolean = false` (attribute `pagination`, reflected) — renders page indicators.
- `slidesPerPage: number = 1` (attribute `slides-per-page`) — number of simultaneously operable
  slides. Values used for layout are finite integers clamped to at least one and at most the live
  slide count.
- `slidesPerMove: number = 1` (attribute `slides-per-move`) — number advanced by `next()` and
  `previous()`, clamped to `slidesPerPage`. A final partial movement lands on the last full page.
- `orientation: 'horizontal'|'vertical' = 'horizontal'` — inline-axis or block-axis layout and
  scrolling. Give a vertical carousel a definite block size.
- `mouseDragging: boolean = false` (attribute `mouse-dragging`, reflected) — adds desktop
  click-and-drag scrolling without replacing native touch and trackpad scrolling. Pointer
  cancellation releases capture, removes drag state, and returns to the active snap position.
  Gestures begin only for a primary left-mouse pointer on noninteractive slide content; native,
  custom, shadow-wrapped, labelled, disabled, and editable controls retain their own pointer input.
- `slides: number` (read-only) — live assigned-slide count, updated after dynamic child changes.
- `accessibleLabel?: string` (attribute `accessible-label`) — fallback landmark name. Omitting it
  reads back `undefined` and uses the localized `carouselLabel` default; an explicitly empty value
  is used as-is. A host `aria-label` takes precedence by presence, including an explicitly empty
  value

**9.0 cleanup:** the redundant Lyra-only `index`, `showIndicators`, and `goTo()` aliases were
removed. Use mapped `currentSlide`, `pagination`, and `goToSlide()`. The writable/reflected
`slides` readout also became a readonly composition-derived property. Navigation and pagination
retain their mapped opt-in defaults, and the autoplay interval remains 3000ms.

**Methods:**

- `next(behavior: ScrollBehavior = 'smooth')` and
  `previous(behavior: ScrollBehavior = 'smooth')` move by `slidesPerMove`
- `goToSlide(index, behavior: ScrollBehavior = 'smooth')` moves to a specific slide
- `addSlide(slide: LyraCarouselItem)` appends a slide and `removeSlide(index)` removes one; page
  count, active range, inertness, eligible loop snapshots, and pagination reconcile
  automatically

**Events:** `lr-slide-change` (`detail: { index, slide }`) — emitted after the active slide changes
from a method, button, key, pagination item, autoplay tick, or settled user scroll. `slide` is the
original assigned element at `index`, never a loop endcap.

**Paging and scrolling.** In non-loop mode the page count is the set of reachable starts from zero
to `slideCount - slidesPerPage`, stepping by `slidesPerMove` and always including the final start.
Loop pagination exposes every slide as an exact valid start, so the current loop start always has
one and only one current indicator. Multi-slide basis conserves the allocation as
`(100% - (slidesPerPage - 1) * gap) / slidesPerPage`, including final partial pages. All
slides in the active page are restored to their authored `inert`/`aria-hidden` state; every other
slide keeps its layout box but becomes `inert` and `aria-hidden="true"`, so visible multi-slide
pages remain fully operable while off-page links are unreachable. Native mandatory scroll snap
owns touch, trackpad, momentum, and rubber-band behavior. Settling adopts the nearest page once and
emits one event for the whole gesture. Programmatic movement scrolls the same track; first mount
and reduced-motion alignment are instant. Loop mode adds inert, accessibility-hidden snapshots only
for side-effect-free plain HTML, so forward/backward wrapping can continue in the requested
direction before silently resetting to the matching original slide. Those snapshots refresh after
light-DOM content or attribute changes, and their idrefs/form-identifying attributes are removed. A
slide containing a custom element, media/resource owner, form state, script/style, or non-HTML
descendant is never cloned; wrapping falls back to the original slide instead, avoiding duplicate
lifecycle, network/playback, and state owners even when the physical wrap cannot use an endcap in
the requested direction.

Manual active-page changes after mount are appended to Lyra's shared light-DOM polite
announcement sink. The focusable `scroll-container` is not itself a shadow-root live
region. Initial connection and reconnection stay silent. Timer-driven autoplay advances also stay
silent, while click, keyboard, method, scroll-gesture, and property changes are announced even
when `autoplay` remains enabled. A change made while the carousel or a composed ancestor is
`hidden`, `inert`, `aria-hidden`, or CSS-hidden stays silent. Slide announcement text likewise
omits accessibility-hidden descendants. A subtree-pruned active slide root suppresses the entire
page announcement rather than synthesizing a position for content outside the tree; a
`visibility:hidden|collapse` root can still contribute a descendant that explicitly restores
`visibility:visible`, in which case the position and that exposed descendant are announced.
Nested forwarding slots contribute their flattened assigned content. Slot fallback text contributes
only when there is no direct assignment; an accessibility-hidden assignment remains authoritative
and does not expose the fallback. The `carouselSlideAnnouncement` message (English default:
`{position}: {content}`) controls the order and punctuation of each position/content pair, and
`carouselSlideAnnouncementSeparator` (English default: `. `) separates multiple visible-slide
summaries. A registered locale or the instance's `strings` override can customize both.

Horizontal Left/Right keys follow logical direction and swap under RTL; vertical carousels use
Up/Down without an RTL inversion. Home and End move to the first and final reachable start. The
populated multi-slide state remains accessible at a 320px allocation.
If a controlled page/page-size change or slide removal would make the currently focused slide
inert or disconnected, focus moves to the stable `scroll-container` before exclusion. A
newer external focus destination is never reclaimed.

**Slots:** default slides, `previous-icon`, and `next-icon`. Named icon slots replace only the
decorative glyph content; their flattened subtrees remain visible but are inert and aria-hidden.
Lyra retains the localized native-button names, actions, and minimum hit areas.

**CSS parts:** `base carousel` (same region node), `scroll-container` (focusable scroll port),
`navigation`, `navigation-button`, `navigation-button-previous` /
`navigation-button-next`, Shoelace aliases `navigation-button--previous` /
`navigation-button--next`, plus `previous-glyph` / `next-glyph`; `pagination`, `pagination-item`,
active aliases `pagination-item-active` / `pagination-item--active`, and `indicator-dot`. `track` and
`controls` are Lyra extensions.

**Themeable custom properties:** mapped `--aspect-ratio` (default `16/9`), `--scroll-hint`
(logical scroll-area padding), and `--slide-gap` (default `var(--lr-space-m)`). Lyra extensions
`--lr-carousel-indicator-current-bg` (default `var(--lr-color-brand-quiet)`) and
`--lr-carousel-indicator-current-border-color` (default `var(--lr-color-brand)`) color only the
active `indicator-dot`. `--lr-carousel-slide-basis` remains a compatibility escape hatch that
overrides the basis computed from `slidesPerPage`; prefer the property for normal multi-slide
layouts because it also updates paging and accessibility state.
Navigation buttons use independent `--lr-carousel-navigation-hover-bg`,
`--lr-carousel-navigation-hover-border-color`, `--lr-carousel-navigation-active-bg`, and
`--lr-carousel-navigation-active-border-color` hooks. Pagination dots use the corresponding
`--lr-carousel-pagination-hover-bg`, `--lr-carousel-pagination-hover-border-color`,
`--lr-carousel-pagination-active-bg`, and `--lr-carousel-pagination-active-border-color` hooks.
All are inline fallbacks at their state rules, inherit from ancestors, and retain the previous
brand/active-mix rendering when unset. The scroll-snap viewport's mouse-hover preview has its own
four-longhand outline shape, matching `lr-scroller`'s viewport:
`--lr-carousel-scroll-container-hover-outline-width` (default `var(--lr-border-width-thin)`),
`--lr-carousel-scroll-container-hover-outline-style` (default `solid`),
`--lr-carousel-scroll-container-hover-outline-color` (default `var(--lr-color-border-strong)`, set
to `transparent` to opt out entirely), and `--lr-carousel-scroll-container-hover-outline-offset`
(default `var(--lr-focus-ring-offset)`). Unset, all four resolve to the rule's previous literal
paint. The `scroll-container` part also honors the opt-in theme-level
`--lr-theme-scrollbar-width`/`--lr-theme-scrollbar-gutter` hooks (defaults `none`/`auto`, matching
its previous unconditional `scrollbar-width: none`) — set either on `:root` or any ancestor for one
declaration to retheme every internal scroll container in the library. Chromium and Safari ignore
the standard `scrollbar-width` property for any element a page also styles through the legacy
`::-webkit-scrollbar` pseudo-element, which this part's own stylesheet still does to hide its
scrollbar there, so on those two engines the hook only visibly retunes this part in Firefox.

```html
<lr-carousel navigation pagination aria-label="Screenshots">
  <lr-carousel-item
    ><img alt="Dashboard overview" src="overview.png"
  /></lr-carousel-item>
  <lr-carousel-item
    ><img alt="Dashboard details" src="details.png"
  /></lr-carousel-item>
</lr-carousel>
```

```html
<lr-carousel
  navigation
  pagination
  mouse-dragging
  slides-per-page="3"
  slides-per-move="2"
  aria-label="Projects"
>
  <lr-card>Solar</lr-card>
  <lr-card>Wind</lr-card>
  <lr-card>Battery</lr-card>
  <lr-card>Hydro</lr-card>
</lr-carousel>
```

---

## `lr-carousel-item`

Optional semantic wrapper for one slide in `<lr-carousel>`. Mirrors `wa-carousel-item` /
`sl-carousel-item`. The carousel also accepts arbitrary slotted elements, so this element is useful
when a migration needs the explicit item tag — and it is the one slide shape whose contract lets the
carousel generate group semantics and a localized "Slide N of M" name for it (see `<lr-carousel>`
above). An explicit `role`, `aria-roledescription` or `aria-label` you set yourself always wins,
including a value added, changed, or removed after connection. The carousel temporarily controls
`inert` and `aria-hidden` while an item is off page, then restores your retained values when it is
visible, removed, or disconnected.

**Slots:** default slide content.

**CSS parts:** `base`.

**Themeable custom properties:** `--aspect-ratio` — inherited from the owning carousel unless set
on the item itself.

```html
<lr-carousel>
  <lr-carousel-item>Dashboard overview</lr-carousel-item>
  <lr-carousel-item>Dashboard details</lr-carousel-item>
</lr-carousel>
```

---

## `lr-button-group`

Responsive semantic grouping primitive for related action controls. It preserves the slotted
controls and exposes `role="group"` on its internal wrapper.

**Properties:**

- `orientation: LyraOrientation = 'horizontal'` (reflected; the shared
  `'horizontal' | 'vertical'` layout axis, with no component-local alias)
- `label: string = ''` — accessible group-name fallback; a host `aria-label`, when present, wins
  including an explicitly empty value

**Slots:** default action controls.

**CSS parts:** `base` (the `role="group"` flex wrapper; wraps, and goes full-width below a 20rem
container inline-size).

**Themeable custom properties:** `--lr-button-group-gap` (default `var(--lr-space-2xs)`) — gap
between slotted controls on both axes.

**Sizing gotcha — give it an explicit width.** `:host` is `display: inline-flex` _and_ declares
`container-type: inline-size` unconditionally (that is what makes the 20rem `@container` rule above
fire at all). Inline-size containment means the box's own content can no longer contribute to its
width, so in any context where the host would otherwise be shrink-to-fit — plain block flow, an
`inline-flex`/`flex` parent, anywhere with no definite width — the group uses its
`contain-intrinsic-inline-size` fallback of `var(--lr-size-12rem)` instead of growing to fit the
slotted buttons. Give `<lr-button-group>` a definite width (`inline-size`, `width: 100%`, `flex: 1`,
or a grid track) whenever it isn't already in a layout that supplies one. Under tighter allocation,
`min-inline-size: var(--lr-icon-button-size)` remains the hard 2.5rem lower bound rather than the
unallocated fallback.

---

## `lr-scroller`

Responsive overflow surface with optional previous/next controls. The default slot remains the
consumer's content, and the viewport is a native scroll container that works in narrow panels as
well as full-width layouts.

**Properties:**

- `orientation: 'horizontal' | 'vertical' = 'horizontal'` (reflected)
- `controls: boolean = false` (reflected) — show previous/next controls
- `withoutScrollbar: boolean = false` (attribute `without-scrollbar`, reflected) — hides the
  native scrollbar while preserving scrolling
- `withoutShadow: boolean = false` (attribute `without-shadow`, reflected) — suppresses both
  logical edge cues without changing native scrolling or the optional controls
- `scrollStep: number = 0` (attribute `scroll-step`) — custom step; zero uses 80% of the viewport
- `label: string = ''` — accessible region name; a host `aria-label` is used when set

**Events:** `lr-scroll` has detail `{ scrollStart, scrollEnd, scrollLeft, scrollTop }`.
Scroll-driven emissions are coalesced through one `requestAnimationFrame` tick, so a fling that
fires dozens of native `scroll` events produces at most one `lr-scroll` per frame. This is the
scroller's own event shape, not `lr-virtual-list`'s `lr-virtual-scroll` event
(`{ scrollTop, viewportHeight }`).

**Slots:** default scrollable content.

**CSS parts:** `base`, `viewport`, `content`, `start-shadow`, `end-shadow`, `previous`, `next`,
`control` (shared by `previous` and `next`), and `previous-glyph`/`next-glyph` (the chevron inside
each, mirrored under RTL). Each shadow is hidden at its corresponding measured edge and uses
logical positioning, so both cues and gradients mirror under RTL and rotate to the block axis in a
vertical scroller. Before the first client measurement, both cues are hidden and both optional
controls are disabled, so server-rendered markup never advertises a false scroll direction.

**Themeable custom properties:** `--lr-scroller-control-size` (default `var(--lr-size-2rem)`) — the
previous/next control's box size; the interactive target never shrinks below `--lr-icon-button-size`
regardless. `--lr-scroller-min-block-size` (default `var(--lr-size-10rem)`) — the vertical
orientation's minimum block size, ignored while horizontal. `--shadow-color` (default
`var(--lr-color-surface)`) and `--shadow-size` (default `var(--lr-size-2rem)`) theme each edge cue's
base color and logical extent; `--lr-scroller-shadow-color` and `--lr-scroller-shadow-size` are
Lyra-prefixed aliases for the same two (mirroring `lr-split-panel`'s alias pattern for its own
upstream-named props), and win when both spellings are set. The viewport's mouse-hover preview has
its own four-longhand outline shape, matching `lr-virtual-list`'s: `--lr-scroller-hover-outline-width`
(default `var(--lr-border-width-thin)`), `--lr-scroller-hover-outline-style` (default `solid`),
`--lr-scroller-hover-outline-color` (default `var(--lr-color-border)`, set to `transparent` to opt
out entirely), and `--lr-scroller-hover-outline-offset` (default `var(--lr-focus-ring-offset)`).
Unset, all four resolve to the rule's previous literal paint. The `viewport` part also honors the
opt-in theme-level `--lr-theme-scrollbar-width`/`--lr-theme-scrollbar-gutter` hooks (defaults
`auto`/`auto`, matching its previous unconditional `scrollbar-width: auto`) — set either on `:root`
or any ancestor for one declaration to retheme every internal scroll container in the library,
including `lr-table`, `lr-virtual-list`, `lr-code-block`, and `lr-code-editor`.

```html
<lr-scroller controls label="Project cards">
  <lr-card>Solar</lr-card>
  <lr-card>Wind</lr-card>
  <lr-card>Battery</lr-card>
</lr-scroller>
```

---

## `lr-tab-group`

A tab strip. Mirrors `wa-tab-group` / `sl-tab-group`.

With manual activation, removing the focused unselected tab rehomes actual focus to a valid survivor
while retaining a valid selected tab and panel. This repair emits no show/hide events and preserves
focus already held by an outside control.

**Renamed in 8.0.0.** This element used to be `<lr-tabs>`. The tag is now `<lr-tab-group>`, its
single `lr-tabs-change` event is now the `lr-tab-hide` → `lr-tab-show` pair below, and every
`--lr-tabs-*` custom property is now spelled `--lr-tab-group-*` (`--lr-tabs-selected-color` →
`--lr-tab-group-selected-color`, and so on). Neither old spelling survives as an alias, and all
three fail silently: `<lr-tabs>` is an unknown element that renders its children unstyled,
`lr-tabs-change` never fires, and a `--lr-tabs-*` declaration is inert. Rename all three in the same
change. The rename is what lets `<lr-tab>` and `<lr-tab-panel>` (below) exist as a family, which is
what makes migrating from either upstream a pure tag rename.

**Canonical child model:** direct `<lr-tab panel="x">` + `<lr-tab-panel name="x">` pairs. This is
the single shape shared with both upstreams, so markup renames mechanically. The pre-9.0
`<div slot="x" label="…">` data/attribute model is removed; migrate each former child into one
descriptor and one matching panel. An unpaired panel never creates a tab.

The group assigns private projection `slot` values itself; consumers do not need to write them.
Those writes are temporary ownership, not destructive normalization: when a descriptor or panel is
removed, moved to another group, disconnected/reconnected, or adopted into another document, the
group restores that element's latest author-owned `slot` value. An author write made while the group
owns the projection is remembered and then reprojected until release.

Each `<lr-tab>`'s content is projected into the real `role="tab"` button, so a tab can carry an icon
or badge while the button's accessible name stays exactly its accessibility-exposed flattened text.
Direct default-slot element roots in that visual label become inert while projected and regain
their latest author-owned inert state when released; use text/glyph markup, not an independent
action. Author `aria-hidden`, hidden, inert, and CSS-hidden branches are excluded from the name, and
direct-label text or visibility changes refresh it. `active` on a paired or labeled unpaneled tab is
an SSR hint: the group reads an initially active tab and then keeps the source tab and any matching
panel attributes synchronized with its own selection after hydration.

Implements the WAI-ARIA APG tabs pattern. With the default `activation="auto"`, Left/Right (swapped
under RTL, or Up/Down when `placement` is `start`/`end`) move focus _and_ selection together; with
`activation="manual"` they move focus only and Enter/Space commits. Home/End jump to the first/last
enabled tab, and a roving `tabindex` follows the focused tab.
Keyboard handling starts from the real event-target tab (then actual shadow focus), so a controlled
`active` write cannot make Arrow/Delete/Enter operate on a different remembered tab.
An enabled `closable` `<lr-tab>` also puts `aria-keyshortcuts="Delete"` on its real tab button.
Delete emits that descriptor's `lr-close` request without creating a second tab stop or changing
selection.

**Properties:**

- `active: string = ''` (reflected) — the active tab's panel name; falls back to the first enabled
  tab whenever the current value doesn't resolve to one (including on every children/attribute
  change, tracked via a `MutationObserver`)
- `accessibleLabel: string | null = null` (attribute `aria-label`) — accessible name applied to the
  `role="tablist"` strip; attribute-reflects from a host-level `aria-label`. `null` omits the
  attribute; an explicitly empty value is preserved (there is no localized default name).
- `placement: 'top' | 'bottom' | 'start' | 'end' = 'top'` (attribute `placement`, reflected) — which
  edge the strip sits on. `start`/`end` are _logical_, so they mirror under RTL with no `:dir()`
  rule of your own; either turns the tablist vertical, which sets `aria-orientation="vertical"` and
  switches the navigation keys to Up/Down per the APG.
- `activation: 'auto' | 'manual' = 'auto'` (reflected) — `auto` moves selection with focus; `manual`
  moves focus only and waits for Enter or Space. Use `manual` whenever revealing a panel is
  expensive: automatic activation would reveal every panel the user arrows past. Under `manual` the
  roving `tabindex="0"` sits on the _focused_ tab, which may differ from the selected one.
- `withoutScrollControls: boolean = false` (reflected, attribute `without-scroll-controls`) and
  `noScrollControls: boolean = false` (reflected, attribute `no-scroll-controls`) — the same opt-out
  under Web Awesome's spelling and Shoelace's. Both are read, either one suppresses the overflow
  scroll controls described below, and neither is deprecated: a consumer arriving from either
  upstream finds their own attribute working. Left unset, an overflowing horizontal strip gets the
  controls.
- `fixedScrollControls: boolean = false` (reflected, attribute `fixed-scroll-controls`) —
  keeps both controls laid out across an overflowing range. Without it, the start control is hidden
  at the logical start and the end control is hidden at the logical end; an exhausted control is a
  no-op in either mode. The flag never makes controls appear on a row that fits, which remains gated
  on real overflow.
- `defaultSlot: HTMLSlotElement` (property only) — the real unnamed shadow slot expected by mapped
  integrations. Lyra exposes it for slot observation but keeps it hidden because every accepted
  tab and panel is projected through a deterministic named slot.

**Methods:** `show(name: string): void` activates the matching enabled tab through the same
`lr-tab-hide` then `lr-tab-show` sequence as pointer/keyboard selection. Unknown, disabled, and
already-active names are no-ops.

**Overflow and scrolling.** The tablist is a native scroll container (`overflow-x: auto`). A
horizontal row that does not fit additionally gets two pointer scroll controls flanking it inside
`[part="nav"]`. Logical edge state drives both controls and the mask: at the initial edge only the
inline-end fade/control appears, in the middle both appear, and at the final edge only inline-start
appears. Native scroll plus a `ResizeObserver` on the strip and its rendered tabs refresh that state,
so intrinsic label/font geometry changes cannot leave stale controls. The same contract works under
RTL, and forced-colors mode removes the alpha mask entirely instead of obscuring text. A row that
fits gets neither affordance.

Controls are rendered only for horizontal placement. A `start`/`end` strip scrolls natively in the
block direction, and in a fixed block allocation the vertical nav, tablist, and panel body stay
within the group: the tablist and body become their own scroll containers rather than expanding the
host. One horizontal control press travels 80% of the visible row smoothly, or instantly under
`prefers-reduced-motion`; under RTL the physical delta mirrors.

The controls are `aria-hidden="true"` and `tabindex="-1"`: a pointer affordance only, matching
upstream. The strip is already fully keyboard-scrollable without them — the roving `tabindex` puts
every tab one arrow key away and focusing a tab scrolls it into view — so two extra tab stops in the
middle of the strip would buy no capability. They still carry a localized `aria-label`, so the name
is there for automation and for a consumer that chooses to expose them. Pressing one does not move
focus off the tab the user was on.

**Events:**

- `lr-tab-show` (`detail: { name: string }`) — a tab became active via click, keyboard, or `show()`.
  Not fired
  when `active` self-corrects to a valid tab (initial default, or a tab disappearing/becoming
  disabled underneath the current selection).
- `lr-tab-hide` (`detail: { name: string }`) — the outgoing tab, emitted immediately _before_ the
  matching `lr-tab-show`, so a listener that tears down the old panel always runs before the one
  that builds the new one. Not fired when there was no previous selection.
- `lr-activate` (`detail: { value: string }`) — fired on **every** user activation of a navigable
  tab (a click, an Arrow/Home/End key under `activation="auto"`, or Enter/Space under
  `activation="manual"`), whether or not the active tab actually moved. Bubbling, composed, not
  cancelable — it reports that the user picked a tab and gates nothing. `value` is the activated
  tab's panel name, the same identity `lr-tab-show` reports under the key `name`. Use it for the
  repeat pick `lr-tab-show` deliberately stays silent for: "reload that panel". From the keyboard
  that case is otherwise unobservable, because Home on an already-first active tab (or End on an
  already-last one) activates a tab and produces no click at all. When an activation _does_ move the
  tab, `lr-tab-hide` and `lr-tab-show` are emitted first. The programmatic `show()` method is not a
  user activation and never fires it.

**Slots:** default — canonical `<lr-tab>`/`<lr-tab-panel>` pairs. `nav` is the upstream-compatible
projection slot a standalone `<lr-tab>` uses before a hydrated group assigns its private slot.

```html
<!-- element model: renames straight across from wa-/sl- -->
<lr-tab-group placement="start" activation="manual">
  <lr-tab panel="general">General</lr-tab>
  <lr-tab panel="danger" disabled>Danger zone</lr-tab>
  <lr-tab-panel name="general">General settings</lr-tab-panel>
  <lr-tab-panel name="danger">Danger zone</lr-tab-panel>
</lr-tab-group>
```

**CSS parts:** `base` and `tab-group` are aliases on the same root wrapper around the tablist and
panels; `nav` (the row wrapping the
tablist together with the two overflow scroll controls; mirrors the upstream part of the same name),
`tablist` and `tabs` (aliases on the `role="tablist"` row of tab buttons and scroll container),
`body` (wrapper around all panels), `scroll-button` and `scroll-button__base` (aliases shared by
both overflow controls), `scroll-button-start`/`scroll-button--start` and
`scroll-button-end`/`scroll-button--end` (aliases on the individual
controls that scroll the tabs toward their inline start and end — under RTL "start" is the
right-hand one), `scroll-button-glyph` (the chevron wrapper inside a control; this wrapper is what
mirrors under RTL, never the icon), `tab` (a single tab button), `active-tab-indicator` (the selected
tab's directional indicator), and `panel`
(a single `role="tabpanel"` wrapper, one per tab, hidden unless active).
The two controls exist in the DOM whenever the group can have them at all (horizontal `placement`,
no opt-out). Non-overflow and inactive-edge qualifiers are wrapped in `:where()`, so a consumer's
own `::part(scroll-button)` rule can override presentation without `!important`.

**Themeable custom properties:** `--lr-scroll-fade-size` (default `2rem`) — width of the mask fade
at each inline scroll edge of the tablist, painted only while the tablist actually overflows and
only for a horizontal `placement`. `--lr-tab-group-selected-color` (default
`var(--lr-color-brand)`) — text color of the selected tab, scoped to `[aria-selected='true']` only,
so it never repaints a hovered unselected tab. `--lr-tab-group-indicator-color` (default
`var(--lr-color-brand)`) — the selected tab's indicator rule, themeable independently of its text
color (an underline on a `top`/`bottom` strip, an inline edge on a vertical one).
`--lr-tab-group-hover-color` (default `var(--lr-color-text)`) — text color of a hovered, non-disabled
tab, independent of the two selected-state hooks. All three are declared as inline `var()` fallbacks
at the point of use rather than on `:host`, so each can be set on the element _or on any ancestor_ —
the pattern exists because `::part(tab)[aria-selected='true']` is invalid CSS (Shadow Parts forbids
an attribute selector after `::part()`), which previously left overriding the library-wide
`--lr-color-brand`/`--lr-color-text` tokens as the only way to restyle a selected or hovered tab,
repainting everything else that reads them. Unset, each falls back to the token its rule used
before, so rendering is unchanged. The upstream hooks `--indicator-color` (selected indicator),
`--track-color` (resting strip rule), and `--track-width` (resting strip-rule thickness) are read
first, with the Lyra/token values as fallbacks. `--lr-tab-group-vertical-nav-max-inline-size`
(default `var(--lr-size-12rem)`) caps a `start`/`end` nav's logical inline size while still allowing
it to shrink in a constrained allocation. Its inline fallback means it can be set on the group or
an ancestor; long single-line tab labels ellipsize within the cap rather than expanding the group or
starving the panel.

`--lr-tab-group-active-bg` (default `color-mix(in oklab, transparent,
var(--lr-color-mix-partner) var(--lr-color-mix-active))`) and
`--lr-tab-group-active-color` (default
`var(--lr-tab-group-hover-color, var(--lr-color-text))`) style a pressed, non-disabled tab.
The overflowing row's controls have their own hooks:
`--lr-tab-group-scroll-button-hover-color` (default `var(--lr-color-text)`),
`--lr-tab-group-scroll-button-active-bg` (default `color-mix(in oklab, transparent,
var(--lr-color-mix-partner) var(--lr-color-mix-active))`), and
`--lr-tab-group-scroll-button-active-color` (default `var(--lr-color-text)`). Each is an
inline fallback, so a wrapper can retheme the interaction state without affecting ordinary tabs,
selection, or the other control state.

The active panel's mouse-hover preview — a subtler cue than `:focus-visible` for a panel that is
also keyboard-focusable, matching `lr-scroller`'s viewport and `lr-carousel`'s scroll container —
has its own four-longhand outline shape: `--lr-tab-group-panel-hover-outline-width` (default
`var(--lr-border-width-thin)`), `--lr-tab-group-panel-hover-outline-style` (default `solid`),
`--lr-tab-group-panel-hover-outline-color` (default `var(--lr-color-border)`, set to `transparent`
to opt out entirely), and `--lr-tab-group-panel-hover-outline-offset` (default
`var(--lr-focus-ring-offset)`). Unset, all four resolve to the rule's previous literal paint.

Otherwise shared tokens — `--lr-space-xs/-s/-m`,
`--lr-color-border/-text-quiet/-text/-brand`, `--lr-transition-fast`, `--lr-radius`,
`--lr-focus-ring-width/-color/-offset`, `--lr-opacity-disabled`.

**Optional peer deps:** none.

```html
<lr-tab-group active="general">
  <lr-tab panel="general">General</lr-tab>
  <lr-tab panel="advanced" disabled>Advanced</lr-tab>
  <lr-tab-panel name="general">General settings…</lr-tab-panel>
  <lr-tab-panel name="advanced">Advanced settings…</lr-tab-panel>
</lr-tab-group>
<script type="module">
  const group = document.querySelector("lr-tab-group");
  group.addEventListener("lr-tab-show", (e) => console.log(e.detail.name));
  group.show("general");
</script>
```

**Known gotchas:**

- **`inert` on a child excludes its tab from arrow-key navigation, exactly as `disabled` does.** An
  inert element refuses focus outright, so a roving `tabindex` that stepped onto one would leave
  `focus()` a silent no-op and strand the arrow key with focus back on `<body>`. The tab button
  rendered for an inert source child is itself marked `inert`, so the two can never disagree,
  Home/End skip it, and `active` is never resolved to it. Only the child's **own** `inert` counts,
  never an ancestor's: a tab group inside a subtree an open modal has inerted is inert as a whole,
  and treating every tab as unreachable there would reset `active` to `''` and blank every panel for
  as long as the dialog is open.
- Tabs are rebuilt from direct children via a `MutationObserver` — not `slotchange` — because a
  brand-new tab's `slot` name has no matching `<slot>` to fire `slotchange` on until this component
  has already rendered one for it, and neither `slotchange` nor any Lit lifecycle hook observes a
  plain attribute edit on a light-DOM child at all. Text/content and relevant
  accessibility/visibility mutations below a direct `<lr-tab>` refresh that button's flattened
  name; arbitrary nested mutations inside panels remain ignored.
- If two `<lr-tab>` descriptors share the same panel name, the first wins. A second matching panel
  is likewise ignored for projection, keeping selection, focus, events, and ARIA idrefs unambiguous.
- The navigation keys follow `placement`, not the writing mode: a `top`/`bottom` strip uses
  Left/Right (swapped under RTL via `internal/rtl.ts`'s `isRtl()`), and a `start`/`end` strip uses
  Up/Down with no RTL swap, because block flow does not reverse. Only one pair is live at a time —
  there is no set of keys that works for both placements.
- The two overflow controls are `aria-hidden`, so an automated check that looks for a _focusable_
  "scroll tabs" button will not find one. Assert on `[part~="scroll-button"]` (and on the tablist's
  `scrollLeft` moving) instead.

---

## `lr-stepper`

Ordered multi-step wizard/form navigation: an index/label per step, independent
`pending`/`current`/`completed`/`error` progress plus disabled availability, and click-to-jump.
First-party invention (no `wa-*`/`sl-*` counterpart). Fully
data-driven and controlled, like `lr-table`'s `columns`/`rows` — it never mutates `steps` itself; a
click, or Enter/Space on a non-disabled step, fires a non-cancelable `lr-step-select`, and the host
decides whether/how `steps` changes in response.

**Properties:**

- `steps: readonly LyraStepItem[] = []` (attribute: false) — `LyraStepItem { stepId: string; label:
string; state: LyraStepState; disabled?: boolean; title?: string; icon?: unknown }`, where
  `LyraStepState` is `'pending' | 'current' | 'completed' | 'error'`. `disabled` independently gates
  activation and roving focus, so locking a current/completed/error step does not erase its progress.
  `title` is an optional native tooltip for the step's button (e.g. explaining why a `disabled` step
  is locked) — omit it for no `title` attribute at all, not an empty string. `icon` is an optional
  leading topic glyph (a `TemplateResult`, an emoji string, etc. — not restricted to a square icon)
  rendered as inert, `aria-hidden` decoration in the `step-icon` part, additionally to — never
  instead of — the state-driven `step-index`/`step-check` glyph. It provides no independent action
  or accessible name. Input is read through a realm-neutral bounded schema snapshot (at most 256
  positions); malformed/hostile entries are skipped while valid neighbors survive, and the frozen
  returned array/records never alias caller-owned objects. Duplicate step IDs are supported as
  ordered occurrences because selection detail always includes `index`; keyed rendering and focus
  restoration correlate `{ stepId, index }` so a refresh retains the focused duplicate occurrence.
  Empty (the default) renders nothing.
- `orientation: 'horizontal' | 'vertical' = 'horizontal'` (reflected) — `'horizontal'` (the default)
  lays steps out in a row (Left/Right, RTL-aware, navigate); `'vertical'` stacks them (Up/Down
  navigate instead, no RTL swap needed). The axis used at/above `orientationBreakpoint` (or always,
  when that's unset).
- `orientationBreakpoint?: number | string` (attribute `orientation-breakpoint`) — opt-in inline-size
  breakpoint measured on `[part='base']`; unset (the default) means no behavior change at all, and
  no `ResizeObserver` is armed. Below it, `narrowOrientation` becomes the effective axis instead of
  `orientation`. Accepts a bare pixel number (`900`, `orientation-breakpoint="900"`) or a CSS length
  string: `'900px'`, `'56.25rem'`, `'3em'`. Under the default `orientationBreakpointBasis='container'`,
  `rem` resolves against the document root's **computed** font size (the rule a `@container` query
  follows) and `em` against this element's own computed font size. The length is **re-resolved on
  every measurement**, never cached at first render, so a root font-size change moves the crossing
  width with no invalidation step on the consumer's side. Anything that isn't a resolvable length
  behaves exactly as unset (no observation, no `data-effective-orientation`): `''`, `'auto'`,
  garbage, a non-finite number, and deliberately `%`, `vw`/`vh` and `calc()` — a viewport-relative
  threshold would mix reference boxes against a measurement of the element's own allocation. Mirrors
  `<lr-multi-split>`'s identically-named contract, unit handling included.
- `orientationBreakpointBasis: 'container'|'viewport' = 'container'` (reflected, attribute
  `orientation-breakpoint-basis`) — which box `orientationBreakpoint` is compared against. Unset,
  behavior is identical to before this property existed. `'container'` measures the stepper's own
  `[part='base']` via `ResizeObserver`, comparing strictly `<`; `'viewport'` evaluates
  `matchMedia('(max-width: <breakpoint>)')`, arms no `ResizeObserver`, and compares inclusively
  (`<=`) per native `max-width` semantics. **A stepper given a fixed width in a row layout cannot
  react to that row stacking by measuring itself — its own width never changes — so that case
  requires `'viewport'`.** Relative units also differ by basis: inside a media query they resolve
  against the browser's _initial_ font size, ignoring `html { font-size }`, which is precisely why
  `'viewport'` matches a CSS `@media` rule authored with the same length. Mirrors `<lr-multi-split>`'s
  identically-named contract.
- `narrowOrientation: 'horizontal' | 'vertical' = 'vertical'` (reflected, attribute
  `narrow-orientation`)
- `wrapLabels: boolean = false` (reflected, attribute `wrap-labels`) — when true, allows long
  labels to wrap when the effective orientation is vertical. The default preserves single-line
  labels, and horizontal labels remain single-line even when this is enabled. Set this when a
  narrow or localized vertical stepper would otherwise clip labels or overflow its allocation.
- `readonly: boolean = false` (reflected) — renders the same `steps` data as a passive progress
  display instead of a navigable control. Each step becomes a non-interactive item inside its
  existing `role="listitem"` wrapper rather than a `<button>`: no `tabindex` (the stepper takes no
  tab stop at all), no `aria-disabled`, no click or Enter/Space activation, and therefore no
  `lr-step-select` — including from a synthetic click dispatched at `::part(step)`.
  Arrow/Home/End become a no-op and no longer call `preventDefault()`, so Space keeps scrolling
  the page the way it does anywhere else in static content. Everything that describes _progress_
  is untouched: the `step-index` chip, the `step-check` glyph, the optional `step-icon`, the
  per-step `title`, `aria-current="step"` on the current step, and every `--lr-stepper-*` custom
  property. It is deliberately **not** a disabled treatment — `disabled` means "you may not do
  this", read-only means "there is nothing to do here" — so a read-only step keeps normal opacity
  and only loses its pointer cursor, matching `<lr-slider>`'s and `<lr-rating>`'s own `readonly`.
  A per-step `disabled` flag is inert while read-only for the same reason: there is no activation
  left for it to gate, so it adds no dimming, and the step still shows its progress state. A
  focused step loses focus when `readonly` is turned on mid-session, because the control holding
  it stops existing; nothing is left stranded in the tab order. Unset (the default) is
  byte-for-byte the previous behavior.
- `effectiveOrientation: 'horizontal' | 'vertical'` (readonly getter) — the live layout/navigation
  axis actually in effect; identical to `orientation` whenever `orientationBreakpoint` is unset or
  doesn't resolve to a length. Also reflected as `data-effective-orientation` (only present while
  `orientationBreakpoint` resolves to a usable length).
- `accessibleLabel: string | null = null` (attribute `aria-label`) — accessible name applied to the
  `role="list"` step strip; attribute-reflects from a host-level `aria-label`. Unset, the list
  renders without an `aria-label` (there is no localized default name); an explicitly empty
  attribute remains empty rather than being treated as absent.

**Events:** `lr-step-select` (`detail: { stepId, index }`) — fired on click, or Enter/Space while
focused, on a non-`disabled` step. Never fired while `readonly`. It is non-cancelable because the
component takes no default action to veto: it never mutates `steps`. `lr-stepper-orientation-change`
(`detail: { orientation }`) — fired only when an enabled `orientationBreakpoint` actually changes
`effectiveOrientation`.

**Slots:** none.

**CSS parts:** `base` (root wrapper, `role="list"`), `step-item` (the `role="listitem"` wrapper for
one step), `step` (a single native button — or a non-interactive `<div>` carrying the same part
while `readonly`; the current step carries `aria-current="step"` and every
other step carries `aria-current="false"`),
`step-icon` (optional inert, `aria-hidden` leading topic glyph from the step's `icon` field; only
rendered when the step has one, additionally to — never instead of — `step-index`/`step-check`),
`step-index` (the numbered index chip, shown for `pending`/`current`/`error` steps), `step-check`
(the completed-checkmark glyph, shown for `completed` steps instead of `step-index`), `step-label`
(the step's label text).

**Themeable custom properties:** `--lr-stepper-hover-bg` (default
`var(--lr-color-brand-quiet)`) and `--lr-stepper-hover-color` (default
`var(--lr-color-text)`) style a hovered non-disabled step. `--lr-stepper-active-bg` (default
`color-mix(in oklab, var(--lr-color-brand-quiet), var(--lr-color-mix-partner)
var(--lr-color-mix-active))`) and `--lr-stepper-active-color` (default `var(--lr-color-text)`)
style a pressed non-disabled step. `--lr-stepper-current-color` (default `var(--lr-color-text)`) —
text color of the `current` step. `--lr-stepper-current-font-weight` (default
`var(--lr-font-weight-semibold)`) — font weight of the `current` step's label.
`--lr-stepper-error-color` (default `var(--lr-color-danger)`) —
text color of an `error` step. `--lr-stepper-current-index-bg` (default `var(--lr-color-brand)`) and
`--lr-stepper-current-index-color` (default `var(--lr-color-on-brand)`) — background and text color
of the `current` step's numbered `step-index` chip. The text color reads the dedicated on-brand
foreground token, not `--lr-color-surface`, so the chip stays legible in dark mode and under forced
colors, where surface and on-brand diverge. Each is an inline `var()` fallback at the point
of use, never declared on `:host`, so it can be set on the element or on any ancestor; and each is
scoped to its own `data-state`, so recoloring the current step leaves `pending`/`completed`/`error`
steps alone. The hooks exist because `::part(step)[data-state='current']` is invalid CSS — Shadow
Parts forbids an attribute selector after `::part()` — so state-specific theming previously meant
overriding a library-wide `--lr-color-*` token and repainting everything else that read it. Unset,
each falls back to the token its rule used before.
`--lr-scroll-fade-size` (default `2rem`) controls the decorative horizontal overflow fade, which is
disabled under forced-colors while the native scroll owner remains available. Otherwise shared tokens —
`--lr-space-m`/`-xs`/`-2xs`,
`--lr-color-text-quiet`/`-text`/`-danger`/`-brand`/`-on-brand`, `--lr-radius`/`-pill`,
`--lr-font-size-xs`, `--lr-font-weight-semibold`, `--lr-opacity-disabled`,
`--lr-focus-ring-*`.

**Optional peer deps:** none.

```html
<lr-stepper></lr-stepper>
<script type="module">
  const stepper = document.querySelector("lr-stepper");
  stepper.steps = [
    { stepId: "account", label: "Account", state: "completed" },
    { stepId: "billing", label: "Billing", state: "current" },
    { stepId: "review", label: "Review", state: "pending" },
  ];
  stepper.addEventListener("lr-step-select", (e) =>
    console.log(e.detail.stepId, e.detail.index)
  );
</script>
```

**Known gotchas:**

- `orientationBreakpointBasis='container'` (the default) observes **the stepper's own allocated
  inline size**, so it fits a stepper that is the sole flex/grid item in its measured container. It
  does **not** fit a stepper sitting beside a fixed-width sibling in a row that stacks via a CSS
  `@media` rule: while the row is a row, the stepper's width shrinks with the viewport; the instant
  the row stacks (a pure-CSS event no component can observe) it jumps to the _full_ row width —
  wider than it was just before the transition. Because the measured width is not monotonic across
  that transition, no single container threshold both stays wide while the row is a row and goes
  narrow exactly when it stacks — and a fixed-width sibling is worse still, since its own width
  never changes with the viewport at all, so no container breakpoint on it can ever react to the
  stacking. Use `orientationBreakpointBasis='viewport'` for that layout — give the stepper and its
  sibling the same `orientation-breakpoint` and `orientation-breakpoint-basis='viewport'` and they
  flip together, in lockstep with the CSS rule that stacks the row:
  ```html
  <lr-stepper
    orientation-breakpoint="56.25rem"
    orientation-breakpoint-basis="viewport"
  ></lr-stepper>
  <lr-multi-split
    orientation-breakpoint="56.25rem"
    orientation-breakpoint-basis="viewport"
  ></lr-multi-split>
  <style>
    @media (max-width: 56.25rem) {
      .shell {
        flex-direction: column;
      }
    }
  </style>
  ```
  A consumer-side `matchMedia()` controller driving the `orientation` attribute directly is still
  supported and still correct — it is simply no longer required for this case.
- there's no built-in "step forward/back" method — advancing the wizard is entirely the host's job:
  react to `lr-step-select` (or its own Next/Back buttons) and reassign `steps` with updated
  `state` values.
- The stepper exposes ordered progress/navigation semantics (`list`/`listitem` plus native step
  buttons), not tabs: it owns no tab panels. Roving tabindex and orientation-aware arrow-key
  navigation remain available independently of those semantics.
- Left/Right (horizontal) and Up/Down (vertical) are mutually exclusive per `orientation` — there's
  no single set of keys that works in both.

---

## `lr-tab`

One tab in a `<lr-tab-group>`'s strip. Mirrors `wa-tab` / `sl-tab`.

A **declarative descriptor, not the interactive control**: the group renders the real `role="tab"`
button and projects this element's content into it, so the whole ARIA and roving-tabindex contract
stays in one place. The host is `display: contents`, contributing no box of its own inside that
button. Direct default-slot element roots in the visual label are inert while projected, while their flattened
accessibility-exposed text explicitly names the real tab button; author-hidden, inert, and CSS-hidden
branches do not contribute. Use text/glyph markup rather than a second action.

**Properties:** `panel: string = ''` (reflected) — the `name` of the `<lr-tab-panel>` this tab
reveals; `disabled: boolean = false` (reflected) — removes the tab from keyboard navigation and
prevents activation; `active: boolean = false` (reflected) — SSR selection hint, synchronized by
the owning group after hydration; `closable: boolean = false` (reflected) — shows the mapped close
affordance.

**Events:** `lr-close` (no detail) — the Lyra-convention mapping of Shoelace's `sl-close`, emitted
when the close affordance is clicked or Delete is pressed on the focused owning tab. It bubbles, is
composed and noncancelable. A disabled tab never emits it. The tab never removes itself or its
panel; the consumer handles the request. The owning group separately emits
`lr-tab-show`/`lr-tab-hide`. **Slots:** default (the tab's visual label content; direct default-slot element roots
are inert while projected, and its accessibility-exposed flattened text names the real tab button).
**CSS parts:** `base`
and `tab` are aliases on the same projected-content slot; `close-button` and
`close-button__base` are aliases on the same non-focusable visual close affordance. Style the
group's `tab` part for the real interactive tab button.

**Themeable custom properties:** none of its own, and the group's are not settable here. The button
this tab is projected into lives in `<lr-tab-group>`'s shadow root, so it inherits
`--lr-tab-group-selected-color`, `--lr-tab-group-indicator-color` and `--lr-tab-group-hover-color`
from the group host or an ancestor of it. Declaring one on the `<lr-tab>` itself does nothing: this
element is _inside_ that button in the flattened tree, and inheritance only runs the other way.
`<lr-tab>`'s own host is `color: inherit; font: inherit;` for exactly this reason — it makes the
projected element (and therefore its visible label) pick up the real tab button's own computed
color and font, so `--lr-tab-group-selected-color`/`--lr-tab-group-hover-color` reach the rendered
tab text rather than being shadowed by the library's own default text color.

Before group hydration, an unassigned tab places itself in the public `nav` slot. The group then
writes its internal per-tab `slot` attribute itself. A labeled tab with no `panel` gets a stable
synthetic name from its position; the allocator avoids every authored tab and panel name, so mixed
paired/unpaired markup cannot collapse two tabs into one key. An unpaneled descriptor with no
accessibility-exposed label is omitted instead of exposing the synthetic key as its spoken name.

The visual close affordance is non-focusable because `<lr-tab-group>` projects this descriptor
inside the real `role="tab"` button. Rendering another focusable button there would create a
nested-interactive accessibility violation and break the APG's one-stop roving-tabindex model. The
glyph carries a localized `title`, stays out of the accessible name, and stops propagation so
closing an inactive tab never selects it first. Keyboard users focus the same real tab button and
press Delete, advertised through `aria-keyshortcuts`. Remove the corresponding `<lr-tab>` and
`<lr-tab-panel>` in an `lr-close` listener; the group then reconciles selection automatically.

```html
<lr-tab-group id="documents" aria-label="Open documents">
  <lr-tab panel="overview" active>Overview</lr-tab>
  <lr-tab panel="notes" closable>Notes</lr-tab>
  <lr-tab-panel name="overview" active>Overview content</lr-tab-panel>
  <lr-tab-panel name="notes">Notes content</lr-tab-panel>
</lr-tab-group>
```

```js
const group = document.querySelector("#documents");
group.addEventListener("lr-close", (event) => {
  const tab = event.target;
  const name = tab.panel;
  tab.remove();
  group.querySelector(`lr-tab-panel[name="${CSS.escape(name)}"]`)?.remove();
});
```

---

## `lr-tab-panel`

The content revealed by the `<lr-tab>` whose `panel` matches this element's `name`. Mirrors
`wa-tab-panel` / `sl-tab-panel`.

Deliberately carries **no `role="tabpanel"` of its own**: the group renders the `role="tabpanel"`
wrapper this element is projected into, and a second nested tabpanel role would leave the panel
announced twice. Show/hide is the group's job too — this element is always present in the DOM.

**Properties:** `name: string = ''` (reflected) — matches the `panel` of the `<lr-tab>` that reveals
it; `active: boolean = false` (reflected) — SSR visibility hint, synchronized by the owning group
after hydration. **Events:** none. **Slots:** default (the panel's content). **CSS parts:** `base`
(the content wrapper); the owning group also exposes its outer `panel` wrapper. **Themeable custom
properties:** `--padding` (default `0`) — inner padding on the panel's own `base` wrapper.

---

---

## `lr-control-group`

Semantic grouping for mixed controls and actions. It keeps slotted children in a wrapping
inline-flex row and centers children with different intrinsic heights. Use it for dashboard
toolbars that combine segmented controls, selects, buttons, and other interactive elements.

**Properties:**

- `label: string = ''` — accessible-name fallback for the internal `role="group"`; a host
  `aria-label`, when present, wins including an explicitly empty value.
- `responsive: boolean = false` (reflected) — makes the host a CSS size-query container
  (`container-type: inline-size`) so a future `@container` rule can react to this group's own
  allocated width. Left unset, the host is `container-type: normal`, since `container-type:
  inline-size` unconditionally would collapse the group to 0 inline size whenever it sits as an
  ordinary (`flex-basis: auto`) child of a shrink-to-fit flex row — this component's own primary
  use case. `[part="base"]` itself now fills the host's inline size unconditionally (not gated by
  `responsive`): a percentage inline-size against an indefinite/shrink-to-fit containing block
  resolves as `auto`, so this is a no-op unless the host is given a definite inline size, directly
  or via an ancestor.

**Events:** none.

**Slots:** default — controls, buttons, or other action content.

**CSS parts:** `base` — the internal `role="group"` wrapper.

**Themeable custom properties:** `--lr-control-group-gap` (default `var(--lr-space-xs)`) — gap
between grouped controls; shared spacing and layout tokens apply as well.

```html
<lr-control-group label="Chart controls">
  <lr-segmented></lr-segmented>
  <lr-select></lr-select>
  <lr-button>Export</lr-button>
</lr-control-group>
```

**Known gotchas:**

- This is a layout and semantics primitive; it does not coordinate child values or emit a group
  change event.
- Children wrap according to the group's own allocated inline size, not the viewport width.
- `[part="base"]` fills the host's inline size unconditionally, but the host itself never gets a
  size from `responsive`/`container-type` alone — give the host a definite inline size directly
  (a percentage width, a grid track, a block-level parent) for the fill to have any visible effect.
- Setting `responsive` while this group also sits as a shrink-to-fit flex child re-introduces the
  0-width collapse the unset default is designed to avoid — only opt in when the group's own size
  comes from somewhere else.

---

## `lr-reorder-list` / `lr-reorder-item`

A generic flat-list reorder primitive: per-row move-up/move-down buttons (always available), plus
Ctrl/Cmd+ArrowUp/ArrowDown from focus anywhere inside a row — the same modifier convention
`<lr-tree>`'s `reorderable` and `<lr-dashboard-grid>`'s `cells-draggable` already establish. By
default this list physically moves its own slotted `<lr-reorder-item>` light-DOM nodes itself
(there is no `data` array prop to reconcile against), and emits `lr-reorder` with the full new
order so the host can persist it without hand-rolling its own splice/resort logic. Setting
`controlled` opts into `<lr-tree>`'s controlled `reorderable` contract instead: the list stops
moving anything itself, and waits for the host to reorder its own backing data and re-render the
slotted items to match — reconciled by each item's `value` rather than by element reference, so a
non-keyed host re-render that recreates the moved row (or merely rewrites `value` on the elements
already at each position) still completes the move once the resulting order matches. `lr-reorder`
is cancelable — a listener calling `preventDefault()` holds the move open (mirroring
`lr-confirm-bar`'s cancelable approve/deny pattern) until the host calls
`finalizePendingMove()`/`revertPendingMove()`; `controlled` changes what "applying" the move
means (host re-render instead of a physical DOM move) but not this cancelable contract.

Direct item `value` property or attribute edits refresh the owning list's valid identities and
movement boundaries. Correcting a missing or duplicate identity re-enables the corresponding
controls; making it invalid disables them. Identity edits do not emit a reorder event. Removing the
value attribute from a standalone item renders it as absent while preserving `null` readback; an
explicit empty string remains supplied and later valid values recover.

### `lr-reorder-list`

**Properties:**

- `label: string = ''` — accessible-name fallback for the internal `role="list"`. A present host
  `aria-label` always wins over `label`, including when the host value is explicitly empty.
- `disabled: boolean = false` (reflected) — disables every item's move buttons and the Ctrl/Cmd+
  Arrow shortcut, without mutating any item's own `disabled` attribute.
- `controlled: boolean = false` (reflected) — opts into the controlled mode described above:
  an accepted move waits for a matching host re-render (reconciled by `value`) instead of moving
  the DOM itself. Every move action stays disabled and `aria-busy="true"`/`:state(busy)` apply
  list-wide for the whole wait, the same as a `preventDefault()`-held move. A host re-render that
  never reaches the exact emitted `order` leaves the move pending indefinitely; one that drops the
  moved `value` entirely (removes or renames that row) cancels it silently, with no announcement.
  Toggling this off while a reconciliation is pending drops it rather than leaving the list stuck
  busy.

**Events:** `lr-reorder`
(`detail: LyraReorderDetail { readonly order: readonly string[], readonly fromIndex: number,
readonly toIndex: number }`, cancelable) — fired before a move is applied; `order` is an immutable
snapshot of every valid item's stable `value` in the order the move WOULD produce. Uncanceled, the
move applies synchronously only if the exact mover, target, membership, order, identities, and
availability remain valid after dispatch — or, while `controlled`, starts waiting for the host's
own re-render to reach that `order` instead. `preventDefault()` holds the move instead: the
internal list exposes `aria-busy="true"`, every move action is disabled, the affected item exposes
`:state(pending)`, and no other move can start until the host resolves it — see **Methods** below.
Synchronous finalize/revert calls from the canceling listener are supported.

**Methods:** `finalizePendingMove()` — applies a move held via `preventDefault()` (or, while
`controlled`, starts waiting for the host's own re-render instead of moving the DOM itself).
`revertPendingMove(options?: { silent?: boolean })` — discards a held move, restoring the prior
order; pass `{ silent: true }` to suppress the built-in `reorderMoveCancelled` announcement, e.g.
when a host is deferring the decision to a flow of its own (a confirmation dialog, say) that will
communicate the outcome itself. Both methods no-op when nothing is pending.

**Slots:** default — `<lr-reorder-item>` elements.

**CSS parts:** `base` — the internal `role="list"` wrapper.

**Themeable custom properties:** `--lr-reorder-list-gap` (default `var(--lr-space-2xs)`) — gap
between rows.

```html
<lr-reorder-list label="Form fields">
  <lr-reorder-item value="name">Name</lr-reorder-item>
  <lr-reorder-item value="email">Email</lr-reorder-item>
  <lr-reorder-item value="phone">Phone</lr-reorder-item>
</lr-reorder-list>
<script type="module">
  document
    .querySelector("lr-reorder-list")
    .addEventListener("lr-reorder", (e) => console.log(e.detail.order));
</script>
```

**Known gotchas:**

- Boundary-disabled state (`atStart`/`atEnd`), `listDisabled`, and `pending` are readonly effective
  state computed by the owning list and exposed through item custom states.
- Every item requires a unique, nonempty stable `value`. Missing, whitespace-only, and later
  duplicate identities remain visible but their move actions are unavailable until corrected.
- Ctrl/Cmd+Arrow is consumed only for a valid owned move. A boundary/no-op gesture or one from a
  nested input, select, link, button, editable region, or custom control retains its native action.
- No pointer drag-and-drop; move-up/move-down buttons and the keyboard shortcut only.
- `controlled` reconciliation is keyed by `value`, never by element reference: a host re-render
  that recreates the moved row as a brand-new element, or one that leaves every node in place and
  just rewrites `value` at each position (the common outcome of a non-keyed `Array.map()` into the
  default slot), both complete the move once the resulting order matches.

---

### `lr-reorder-item`

**Properties:**

- `value: string = ''` — required unique, nonempty stable identifier included in the parent's
  `lr-reorder` order array.
- `accessibleLabel?: string` (attribute `accessible-label`) — explicit row identity appended to
  each repeated move action's accessible name; otherwise the item derives a bounded accessible
  text projection from its row content.
- `disabled: boolean = false` (reflected) — disables this row's own move buttons only; does not
  hide its slotted content.
- `atStart: boolean`, `atEnd: boolean`, `listDisabled: boolean`, `pending: boolean` (readonly) —
  effective owner state. Corresponding custom states include `:state(at-start)`, `:state(at-end)`,
  `:state(list-disabled)`, `:state(pending)`, and `:state(busy)`.

**Events:** `lr-move-request` (`detail: { direction: 'up' | 'down' }` — a move button was activated
while not disabled; handled by the parent `<lr-reorder-list>`, which performs the actual move)

**Methods:** `focusMoveButton(direction: 'up' | 'down'): boolean` — moves focus to the requested
move control and returns whether it did; a no-op returning `false` when that control is disabled
for any reason (this item's own `disabled`, the owning list's `listDisabled`, a move held or a
controlled reconciliation pending anywhere in the list, an invalid identity, or that direction
already being this item's boundary). The owning `<lr-reorder-list>` uses it for its own post-move
focus restore, including onto a freshly recreated element instance while `controlled`; a host can
call it the same way.

**Slots:** default — arbitrary row content.

**CSS parts:** `base` (row wrapper), `move-up-button`, `move-down-button`,
`move-up-button__control` / `move-down-button__control` (each move control's own native `<button>` —
as of 16.0.0 the move controls are composed `<lr-icon-button>`s: the old part names keep placement,
rotation and activation, while background, radius, hover/press mixes, focus ring and hit-area floor
come from `--lr-icon-button-*`, and the component's own `--lr-reorder-item-move-button-*` hooks still
win over those defaults), `content` (default-slot wrapper).

**Border reaches the composed move controls the same way background/color/radius do.** This
component paints no resting border on either move control, so it relays no
`--_lr-icon-button-border-default` into their private fallback tier — but that absence is not a
gap. The public `--lr-icon-button-border` (and its `-hover`/`-active` variants) is the FIRST arm
of the token chain, resolved by ordinary custom-property inheritance regardless of whether this
component relays a default for that same property, so setting it on either move control or an
ancestor reaches it exactly as the background/color/radius tokens do. A component with no resting
border simply has no default to relay, which is different from border theming being broken. Size
remains the one exception that does not cross this way: use `--lr-theme-icon-button-size`, never
`--lr-icon-button-size` — every `LyraElement` re-declares the latter on its own `:host`, so it
never reaches a composed child (see `llms/tokens.md`).

**Themeable custom properties:** `--lr-reorder-item-gap` (default `var(--lr-space-xs)`) — gap
between the move buttons and the row content. The move-button interaction paints are independent,
inherited inline fallbacks: `--lr-reorder-item-move-button-hover-bg` (default
`var(--lr-color-brand-quiet)`), `--lr-reorder-item-move-button-hover-color` (default
`var(--lr-color-brand)`), `--lr-reorder-item-move-button-active-bg` (default `color-mix(in oklab,
var(--lr-color-brand-quiet), var(--lr-color-mix-partner) var(--lr-color-mix-active))`), and
`--lr-reorder-item-move-button-active-color` (default `var(--lr-color-brand)`). Set them on an item
or any ancestor to retheme only the hover or pressed move affordance.

---

## `lr-segmented`

A single-select button row with the WAI-ARIA APG `radiogroup` contract built in:
`role="radiogroup"`/`role="radio"`, roving tabindex, automatic activation (click or arrow-key move
both select immediately, like a native radio group), cyclic Arrow/Home/End navigation among
non-disabled items. First-party invention (no `wa-*`/`sl-*` counterpart) — "choose exactly one of N
labeled options, rendered as a button row" is ubiquitous settings/filter-panel UI.
Navigation starts from the segment that actually received the keyboard event, even when a
controlled `value` write changed the selected or remembered roving item first.

**Properties:**

- `items: readonly LyraSegmentedItem[] = []` (attribute: false) — `LyraSegmentedItem { value:
string; label: string; icon?: unknown; disabled?: boolean }`; `icon` renders as an inert,
  `aria-hidden` decorative leading
  visual inside `segment-icon`. It does not replace the required text label or provide an independent
  action or accessible name. Input is read through a realm-neutral bounded schema snapshot (at most
  256 positions); malformed/hostile entries are skipped, later duplicate values use
  first-valid-value-wins, and the frozen returned array/records never alias caller-owned objects.
- `value: string = ''` — the currently selected item's `value`.
- `label: string = ''` — accessible-name fallback copied to the internal `role="radiogroup"`. A
  host-level `aria-label` wins by attribute presence, including an explicitly empty value.
- `size: '2xs' | 'xs' | 's' | 'm' | 'l' | 'xl' | 'small' | 'medium' | 'large' = 'm'` (reflected) —
  visual size on the library's **shared** ladder, the same `--lr-form-control-*` scale
  `lr-input`/`lr-select`/`lr-combobox`/`lr-button` resolve, so a row of mixed controls set to one
  `size` lines up at a matching height. Both spellings of every tier are accepted (`s`/`small`,
  `m`/`medium`, `l`/`large`), so migrating from either upstream is a tag rename with no attribute
  rewrite. Before 8.0.0 this component carried its own six-tier scale that had drifted from that
  one; `m` is still the default, but the tiers now resolve to the shared control heights, paddings
  and font sizes rather than to this component's former private values.

**Events:**

- `lr-change` (`detail: { value }`) — fired when the selected value changes via click or keyboard.
- `lr-activate` (`detail: { value }`) — fired on **every** activation of a non-disabled
  segment (a click, or an Arrow/Home/End key that lands on one), whether or not the selection
  actually moved. Bubbling, composed, not cancelable — it reports that the user picked a segment
  and gates nothing. Use it for the repeat pick `lr-change` deliberately stays silent for: "run
  that report again", reopening a panel, re-fetching the same range. A `click` listener only
  half-covers that case, because keyboard activation produces no click — pressing Home on an
  already-first selection, End on an already-last one, or an arrow key in a one-item row activates
  a segment and fires no click at all. When an activation _does_ move the selection, `lr-change` is
  emitted first and `lr-activate` second, so either listener reads the settled `value`. A
  disabled segment fires neither event.

**Methods:**

- `scrollToValue(value: string): void` — scroll the segment with the given `value` into view within
  the (possibly overflowing) track, without changing the selection. Honors
  `prefers-reduced-motion` (falls back to `behavior: 'auto'`). This runs automatically when `value`
  is changed programmatically (keyboard navigation already reveals the focused segment on its own),
  so you only need to call it for the "reveal without selecting" case.

**Slots:** none.

**CSS parts:** `base` (the `role="radiogroup"` root), `segment` (a single `role="radio"` button),
`segment-icon` (an optional inert, `aria-hidden` decorative leading icon), `segment-label` (the
segment's label text).

**Themeable custom properties:** `--lr-scroll-fade-size` (default `2rem`) — width of the mask fade
at each horizontal scroll edge of the track, painted only while the track actually overflows (a row
that fits is never dimmed). Forced-colors mode removes the decorative mask while preserving the
native horizontal scroll owner. `--lr-segmented-track-min-height` (default
`var(--lr-form-control-height)`), `--lr-segmented-segment-padding` (default
`var(--lr-form-control-padding-block) var(--lr-form-control-padding-inline)`), and
`--lr-segmented-font-size` (default `var(--lr-form-control-font-size)`) are the three knobs the
`size` tier moves — each points at the shared ladder rather than carrying a per-tier value of its
own, so retuning one tier for this component alone is a one-line override instead of a fork. Their
private defaults follow the tier; a public value inherited from an ancestor or set directly on the
element remains authoritative in every tier.

`--lr-segmented-track-height` pins the `base` track's exact height at every `size` tier (it sets
both `block-size` and `min-block-size`), for a row that has to sit flush beside a hard-sized toolbar
control. It is **genuinely undeclared by default** — not `auto` — and that is load-bearing: an
exact-height hatch only works as an undeclared sentinel, because `auto` is itself a valid value that
would always win and would silently turn every tier's `--lr-segmented-track-min-height` floor into
dead code. While it is unset, each tier keeps its own floor and the track grows with its content.
The floor at the two compact tiers is the ladder's own (20px at `2xs`, 24px at `xs`), but every
`2xs`/`xs` _segment_ separately carries a 24×24px minimum box, so the tappable target holds even
when a label is a single character and the track ends up taller than its nominal floor.

`--lr-segmented-selected-bg` (default `var(--lr-color-surface)`), `--lr-segmented-selected-color`
(default `var(--lr-color-text)`), `--lr-segmented-selected-font-weight` (default
`var(--lr-font-weight-semibold)`) and `--lr-segmented-selected-shadow` (default
`var(--lr-shadow-xs)` — the shallowest step in the elevation scale, since the checked segment is a
thumb lifted a hair off its own track) style the checked segment's pill;
`--lr-segmented-hover-color` (default `var(--lr-color-text)`) styles a hovered segment that is
neither checked nor disabled, independently of the four above — so recoloring the checked pill never
bleeds onto hover. `--lr-segmented-hover-bg` (default `transparent`) and `--lr-segmented-hover-shadow`
(default `none`) style that same hovered segment's background and box shadow; both are undeclared by
default, so they fall back to the segment's own resting values and change nothing about today's
hover paint until set. These seven state hooks are inline `var()` fallbacks at the
point of use rather than `:host` declarations, so each can be set on the element _or on any
ancestor_; unset, each falls back to the token its rule used before. They exist because
`::part(segment)[aria-checked='true']` is invalid CSS — Shadow Parts forbids an attribute selector
after `::part()` — which previously left hijacking the library-wide
`--lr-color-surface`/`--lr-color-text` tokens as the only way to restyle a selected segment,
repainting every other element that read them.

`--lr-segmented-active-bg` (default `color-mix(in oklab, transparent,
var(--lr-color-mix-partner) var(--lr-color-mix-active))`) and
`--lr-segmented-active-color` (default
`var(--lr-segmented-hover-color, var(--lr-color-text))`) style a pressed segment that is neither
checked nor disabled. They use the same inline-fallback inheritance, leaving checked and merely
hovered siblings independent.

Otherwise shared tokens — `--lr-color-border`/`-surface`/`-text`/
`-text-quiet`, `--lr-radius`, `--lr-font-weight-semibold`, `--lr-shadow-xs`,
`--lr-opacity-disabled`, `--lr-focus-ring-*`, and the `--lr-form-control-*` knobs the `size` tier
resolves.

**Optional peer deps:** none.

```html
<lr-segmented></lr-segmented>
<script type="module">
  const seg = document.querySelector("lr-segmented");
  seg.items = [
    { value: "day", label: "Day", icon: "☀" },
    { value: "week", label: "Week", icon: "▦" },
    { value: "month", label: "Month" },
  ];
  seg.value = "week";
  seg.addEventListener("lr-change", (e) => console.log(e.detail.value));
  seg.addEventListener("lr-activate", (e) => console.log("activated", e.detail.value));
</script>
```

**Known gotchas:**

- arrow-key navigation cycles (past the last non-disabled item wraps to the first, and vice versa)
  rather than clamping at the first/last item, unlike `lr-stepper`'s clamped Left/Right.
- this component self-selects on navigation: clicking or arrow-navigating to an item immediately
  updates `value` and fires `lr-change` — there's no separate "commit" step the way, e.g.,
  `lr-select`'s popup has. `lr-change` is change-only, so re-picking the segment that is already
  selected fires nothing on it; listen for `lr-activate` if a repeat pick is meaningful to
  your application.
- the semantic `radiogroup` lives inside shadow DOM. Set `label` (preferred for reactive code) or a
  host `aria-label`; a present host attribute wins, including an explicit empty value, and the
  component deliberately forwards the resulting name to that internal role.

**Additional API surface:**

- `--lr-segmented-track-gap` — Gap between segments. Default: `var(--lr-size-0-125rem)`.
- `--lr-segmented-track-radius` — Track corner radius. Default: `var(--lr-radius)`.
- `--lr-segmented-track-padding` — Track inset padding. Default: `var(--lr-size-0-125rem)`.
- `--lr-segmented-track-bg` — Background of the `base` track. Undeclared by default (transparent),
  matching its own current absence of a background.
- `--lr-segmented-track-border-color` — Border color of the `base` track, which previously read
  `--lr-color-border` as a literal with no override hook. Default: `var(--lr-color-border)`.

---

## `lr-virtual-list`

A generic windowed/virtualized list host. Renders only the items within the current viewport (plus
`overscan` padding rows on each side) as real DOM, regardless of how large its source is, so a
multi-thousand-row chat-history sidebar (or a long message thread) stays cheap to scroll. Content is
entirely caller-supplied: `renderItem(item, index)` returns whatever `lit-html` value should represent
that row, and `keyFunction(item, index)` gives it a stable identity for DOM reconciliation. First-party
invention (no `wa-*`/`sl-*` counterpart).

Before a viewport can be measured, including during server rendering, the component emits a bounded
deterministic first window (the first visible row plus `overscan`) rather than a false empty list.
Hydration preserves that window on its first pass and then reconciles it with the measured browser
viewport; an ordinary browser-only mount retains the established empty-until-measured range-event
contract.

**Properties:**

- `items: readonly unknown[] = []` (attribute: false) — the full, non-windowed item collection. JS-only; set via
  a property/lit-html binding (`.items=`), not an HTML attribute. This remains the compatibility
  source whenever `source` is unset. Its sequence is copied, bounded, and frozen while generic row
  identities are retained; reassign a new array after sequence changes.
- `source?: LyraVirtualListSource` (attribute: false) — a readonly array or a count/index-backed
  `{ readonly count: number; itemAt(index): unknown; keyAt?(index): string | number;
indexOfKey?(key): number }`. When set it takes precedence over `items`. The indexed form performs
  bounded random access for only the rendered window instead of allocating `0…count`; invalid counts
  normalize to zero. Prefer a stable object identity and stable `keyAt`/`indexOfKey` implementations
  for synthetic, paged, or remote collections. `indexOfKey` is required when `active-item-id` should
  target an indexed source: the list never performs a count-sized fallback scan; invalid or
  out-of-range results mean no match. An array source receives the same clone-owned frozen sequence
  and row-identity contract as `items`; an indexed-source object passes through by identity.
- `renderItem: (item: unknown, index: number) => unknown = () => nothing` (attribute: false) — renders
  one row's content, typically returning a `lit-html` `TemplateResult`. JS-only. The returned value
  is stamped inside `<lr-virtual-list>`'s own shadow root, not the caller's light DOM, so
  document-level selectors cannot style arbitrary returned descendants. Use inherited custom
  properties, the public row parts, or a self-styled custom element in the returned template.

**Narrow rows:** ordinary `renderItem` content can shrink and wraps even at a 320px allocation,
including an otherwise-unbroken value; in `row-height="auto"` mode the measured row height follows
those extra lines. This is direction-neutral: LTR and RTL use the same inline-size containment. To
intentionally preserve an unbroken row, set `white-space: nowrap` on the caller-rendered content; the
list's `base` scroll container exposes horizontal scrolling for that explicit opt-out.

- `keyFunction?: (item: unknown, index: number) => string | number` (attribute: false) — derives a
  row's stable reconciliation key. JS-only. Falls back to the effective source index when omitted,
  which is only a safe identity while a collection never reorders/inserts/removes — provide this
  whenever possible, or scroll position and per-row DOM state (e.g. an `<audio>` element's playback
  position) can attach to the wrong row across a mutation.
- `groups?: LyraVirtualListGroup[]` (attribute: false) — renders a labeled marker at each group's
  `startIndex` as a measured virtual entry immediately before that row. Its live block size
  contributes to every following offset, so a variable-height or late-resizing marker never covers
  the group's first row. Markers remain windowed with their rows. Groups are sorted by `startIndex`;
  a non-object entry or a `startIndex` that's non-integer, out of range, or a duplicate of an earlier
  group's is silently dropped rather than rendered wrong. An entry whose
  `label` is the **empty string** renders no marker at all — it is a pure position anchor, for a host
  that renders its own group header as an ordinary row (and would otherwise end up with two stacked
  headers) but still needs this component to know where each group starts, e.g. to drive
  `renderStickyGroup` below. Omitting `label` entirely still falls back to rendering `key`.
- `renderStickyGroup?: (group: LyraVirtualListGroup) => unknown` (attribute: false) — renders a pinned
  copy of whichever `groups` entry the viewport is currently inside, into a `[part="sticky-group"]`
  overlay that stays at the top of the scroll viewport and is pushed out by the overlap as the next
  group's header arrives (rather than swapped abruptly at the boundary). Native `position: sticky` on
  the rows or markers themselves cannot do this: every row is absolutely positioned and
  transform-offset by the windowing math, which makes sticky structurally inert. Unset (the default)
  renders no overlay element whatsoever and changes nothing about the list's output. The overlay is a
  _visual copy_ of content that already exists in the list, which fixes its contract:

  - it is `aria-hidden` and `inert`, so the real row keeps sole ownership of heading semantics,
    focus and activation. The component never traverses or rewrites callback-owned descendants,
    including open custom-element shadow roots;
  - it is pointer-transparent and deliberately cannot become a mouse-only action. Put interactive
    group actions in the real row;
  - it is never measured as a row, so a group header that is also a real row is not double-counted in
    `row-height="auto"` mode;
  - its measured height is applied as `scroll-padding-block-start` on the scroll container and
    subtracted from top-aligned scroll targets, so `active-item-id`, `scrollToIndex({ align: 'start' })`
    and native keyboard scrolling all stop _below_ the band instead of parking the row behind it.

  The callback runs on every scroll-driven update, so keep it cheap and side-effect free. While the
  viewport is above the first group there is nothing to pin: the band shows nothing, but it stays
  mounted (called with the first group, rendered hidden) so its height is known before the first
  programmatic jump rather than only after it.

- `rowHeight: number | 'auto' = 'auto'` (attribute `row-height`) — `'auto'` measures each row's real
  height via `ResizeObserver`; a numeric markup value (for example `row-height="56"`) parses to the
  number `56` and fixes every row to that many pixels. Property callers assign a number, not a
  numeric string. Anything else (non-numeric, zero, negative, non-finite) safely canonicalizes to
  `'auto'` rather than throwing.
- `rowProjection: 'shadow' | 'light' = 'shadow'` (attribute `row-projection`) — where
  `renderItem`'s output is instantiated. `'shadow'` (default) stamps it inside this component's own
  shadow root, so only inherited custom properties and the public row parts reach it. `'light'`
  renders the windowed rows into the host's own light DOM instead, assigned into the shadow viewport
  through internal named slots, so ordinary document CSS styles a virtualized row exactly as it
  styles the same row unvirtualized. The component keeps owning windowing, measurement, spacer
  sizing, `scrollToIndex()`, the external-scroller mode and the ARIA contract either way, and
  positioning stays on the shadow-side `[part="row"]` wrapper that document CSS cannot select — so
  consumer styles can never break windowing. Any other value canonicalizes to `'shadow'`. Left
  unset, the rendered output is byte-identical to before and the host's light DOM stays empty.
  See **Light-DOM row projection** below for the trade-offs it carries.
- `itemRole: 'listitem' | 'row' = 'listitem'` (attribute `item-role`) — `'listitem'` (default)
  preserves the plain `role="list"`/`role="listitem"` mapping with `aria-setsize`/`aria-posinset`.
  `'row'` additionally maps `[part="base"]` to `role="rowgroup"`, `[part="spacer"]` to
  `role="presentation"`, and each row to `role="row"` with `aria-rowindex` instead — for a consumer
  composing its own `role="table"` wrapper and header row around this component (see
  `lr-dataset-viewer`).
- `rowIndexOffset: number = 0` (attribute `row-index-offset`) — added to a row's 1-based index to
  compute `aria-rowindex` in `item-role="row"` mode (e.g. `1` when a consumer renders its own header
  row occupying `aria-rowindex="1"` outside this component). Negative and non-finite values become
  zero, fractions are truncated, and the final positive ARIA integer saturates safely. No effect in
  `'listitem'` mode.
- `overscan: number = 6` — extra rows rendered beyond the visible viewport on each side; finite
  values are floored and clamped to 0–100, while non-finite values use the default 6, so an invalid
  runtime value cannot disable windowing and render the entire collection.
- `activeItemId: string | number | '' = ''` (attribute `active-item-id`) — when set and it matches a row's `keyFunction`
  result (compared with `Object.is` against the typed value — attribute values arrive as strings, so
  assign the property directly for a numeric key), that row is smoothly scrolled into view whenever
  this changes, and rendered with `aria-current="true"`.
- `loading: boolean = false` (reflected) — sets `aria-busy` on the scroll container and a `cursor:
progress` style, and gates `lr-load-more` while a consumer's fetch is in flight.
- `hasMore: boolean = false` (attribute `has-more`, reflected) — when true, scrolling near the bottom
  fires `lr-load-more` (gated by `loading`).
- `scrollElement?: Element | Window` (attribute: false) — an ancestor that already owns a scrollbar,
  or the window itself, for a list embedded in a longer scrolling page rather than sized as its own
  panel. JS-only; set via a property/lit-html binding. While set, `[part="base"]` stops scrolling and
  grows to the list's full virtual extent, so the page's single scrollbar spans the whole list and
  `[part="sticky-group"]` sticks to that outer scrollport instead of this component's. Everything
  expressed in list coordinates keeps answering in list coordinates — `offsetForIndex()`,
  `indexAtOffset()`, `scrollToIndex()`, `active-item-id` scroll-into-view, and `lr-virtual-scroll`'s
  `scrollTop` are all still measured from the top of the list, with the component converting to and
  from the external scroller's position; auto-height scroll anchoring moves the external scroller
  too, so measuring a row above the viewport does not make the page jump. There is deliberately no
  ancestor auto-detection: the scroller is the element you name and nothing else, so adding an
  unrelated `overflow` rule to some wrapper can never silently take the job over. Two consequences:
  `[part="base"]` drops its `tabindex` and its hover outline, because it is no longer a scrollable
  region and a focus stop that scrolls nothing is worse than none — keyboard scrolling belongs to the
  external scroller; and horizontal scrolling of row content that opted out of wrapping becomes the
  external scroller's responsibility, since CSS cannot leave one axis visible while the other
  scrolls. The list's position inside the scroller is re-read on scroll, on the scroller's own
  resize, and whenever the list re-renders; a layout change _above_ the list that shifts it without
  any of those happening is not observable, so re-assign the property to force a re-read. Listeners
  follow the property — re-pointing it, disconnecting, and reconnecting all rebind against the
  current target and leave nothing behind on the previous one. A value that is neither an `Element`
  nor a `Window` is ignored and the list keeps scrolling its own viewport, so wiring this from a ref
  that is still empty on a first render is safe.

**Exported types:** `LyraVirtualListRowHeight = number | 'auto'`;
`LyraVirtualListSource<T> = readonly T[] | LyraVirtualListIndexedSource<T>` and
`LyraVirtualListIndexedSource<T> { readonly count: number; itemAt(index): T; keyAt?(index): string |
number; indexOfKey?(key: string | number): number }`; `LyraVirtualListRange { start: number; end: number }` (the `lr-visible-range-change`
detail shape); `LyraVirtualListGroup { key: string | number; label?: string; startIndex: number }` — the
shape consumed by `groups` above; `LyraVirtualListScroll { scrollTop: number; viewportHeight: number }` —
the `lr-virtual-scroll` detail shape.
`groupByRecency(items, options?)` is a DOM-free helper that returns non-empty
Today/Yesterday/Previous 7 Days/Older buckets, preserves input order within each bucket, and accepts
a timestamp extractor, reference date, and label overrides. Import it from its granular subpath —
the package root also re-exports it without registering custom elements, while the granular
route limits the named-export module graph. `@aceshooting/lyra-ui/all.js` is the separate eager
registration entry:

```ts
import { groupByRecency } from "@aceshooting/lyra-ui/utilities/group-by-recency.js";
```

**Methods:** `scrollToIndex(index, options?)` — the programmatic counterpart to `active-item-id`'s
automatic scroll-into-view, for a host that needs to scroll to a specific row without changing which
row is "active." `options.align` is `'start'`, `'end'`, or `'auto'` (default — no scroll at all when
already fully visible); `options.behavior` (default `'smooth'`) is forced to `'auto'` under
`prefers-reduced-motion: reduce`. `index` is clamped to the effective source's `0…count-1` range.
In auto-height mode, estimate-based jumps are corrected as row and group-marker measurements arrive.
That correction is bound to the source, key function, and target identity and is canceled on a new
target, data replacement, manual scroll intent, or disconnect, so late observations cannot pull a
newer view back to stale content.
`offsetForIndex(index)` returns the pixel top row `index` renders at, in the same coordinate space as
the scroll container's `scrollTop`; under an external `scrollElement` that space is unchanged — it
measures from the top of the list itself, not from the top of the external scroller's content, and
the component converts between the two. It is clamped to `0…count`, so `offsetForIndex(count)`
is the total content height and an empty list is always `0`. `indexAtOffset(px)` is its inverse — the
row whose box contains that offset, clamped at both ends, `-1` for an empty list — so
`indexAtOffset(offsetForIndex(i)) === i` and `indexAtOffset(scrollContainer.scrollTop)` is the row at
the top of the viewport. In `row-height="auto"` mode both are estimate-based for any row that (or
above which) has not been measured yet, and converge as those `ResizeObserver` measurements land;
fixed numeric `row-height` offsets are exact from the first render. Both read the most recent render,
so `await el.updateComplete` after assigning `items` or `source` before querying.

**Getters:** `scrollContainer: HTMLElement | undefined` — the real scroll container (`[part="base"]`),
`undefined` before the first render; for a host that needs the live scroll position or wants to scroll
the list itself without reaching into the shadow root. While `scrollElement` is set this element
still exists and still hosts every row, but it no longer scrolls — read and write the position on the
external scroller, or keep using `scrollToIndex()`, which targets whichever of the two is currently
in charge. `renderedRows: HTMLElement[]` — the row
wrappers (`[part="row"]`) that currently exist as real DOM, in item order (the current window, not the
whole collection; empty before the first render). It exists for hosts that must _reach_ a rendered row
rather than style it — keyboard focus management across a windowed list, where the row to focus may
not have existed a frame earlier, and which `exportparts` cannot serve since it forwards styling, not
element references. Treat both as read-only: positioning, keys, and lifetime belong to the windowing
math, and any row element can be recycled or removed on the next update.

**Events:** `lr-load-more` (no detail — fired once per approach to the bottom of the list while
`has-more` is true and `loading` is false; does not refire on every scroll tick while still near the
bottom — scrolling back away from the bottom and returning, or `items` growing enough to move the
window away from the end, re-arms it), `lr-visible-range-change` (`detail: LyraVirtualListRange`, the
current visible, non-overscanned item index range — fired only when it actually changes; it was
spelled `lr-visible-range-changed` before 10.0.0, the only past-tense `-changed` spelling among 58
`-change`-family events, so a convention-driven `lr-${x}-change` listener silently missed it),
`lr-virtual-scroll`
(`detail: LyraVirtualListScroll` — the scroll container moved. `scrollTop` is always in the list's own
offset space (`offsetForIndex()`'s space), including under an external `scrollElement`, where it is how
far the list has scrolled past the top of that scroller rather than the scroller's own position;
emitted from the same animation frame that
already coalesces native `scroll` events, so a fling produces at most one per frame and none at all
when the position did not change. Unlike `lr-visible-range-change`, which only fires on index-range
changes, this reports _sub-row_ movement, which is what scroll-linked layout needs)

**Slots:** none — all content comes from `renderItem`.

**CSS parts:** `base` (the scrollable container, `role="list"` — or `role="rowgroup"` in
`item-role="row"` mode — `tabindex="0"`; under an external `scrollElement` it stops scrolling, drops
that `tabindex` and its hover outline, and sizes itself to the list's full virtual extent instead of
`--lr-virtual-list-height`), `spacer` (the full-content-height inner element
establishing true scroll extent; `role="presentation"` in `item-role="row"` mode), `row` (one
rendered row's absolutely-positioned wrapper, `role="listitem"` — or `role="row"` with
`aria-rowindex` in `item-role="row"` mode), `group` (a `groups` entry's positioned marker; not
rendered for an entry whose `label` is the empty string), `sticky-group` (the pinned copy of the
current group, present only while `renderStickyGroup` is set — `aria-hidden`, `inert`, and
pointer-transparent, and it shows nothing while the viewport is above the first group)

**Themeable custom properties:** `--lr-virtual-list-height` (default `24rem` — the host's bounded
scroll extent; component-specific since a virtualized list is meaningless without a sized viewport,
and ignored while `scrollElement` names an external scroller, whose own height is the visible band),
plus shared `--lr-focus-ring-width/-color/-offset` (inward-offset ring on `[part="base"]`, negative
so it isn't clipped by the container's own `overflow: auto`). `[part="base"]` also carries a
mouse-hover outline — a subtler preview of that same `:focus-visible` ring, shown because the part
carries `tabindex="0"` and is a real keyboard-navigable target whenever it owns the scrollport (both
the tab stop and this outline are dropped under an external `scrollElement`) — tinted via
`--lr-virtual-list-hover-outline-color` (default `var(--lr-color-border-strong)`); set it to
`transparent` to opt out of the hover treatment entirely. Its remaining longhands are independently
themeable with `--lr-virtual-list-hover-outline-width` (default
`var(--lr-border-width-thin)`), `--lr-virtual-list-hover-outline-style` (default `solid`), and
`--lr-virtual-list-hover-outline-offset` (default
`calc(-1 * var(--lr-border-width-thin))`). All four hover-outline hooks are inline fallbacks and
there is intentionally no pressed state: the list viewport is a scroll surface rather than an
activation target. `[part="base"]` also honors the opt-in theme-level
`--lr-theme-scrollbar-width`/`--lr-theme-scrollbar-gutter` hooks (defaults `auto`/`auto`, matching
its previous unconditional `scrollbar-width: auto`) — set either on `:root` or any ancestor for one
declaration to retheme every internal scroll container in the library, including `lr-table`,
`lr-scroller`, `lr-carousel`, `lr-code-block`, and `lr-code-editor`.

**Optional peer deps:** none.

```ts
import { html } from "lit";

const view = html`<lr-virtual-list
  .items=${sessions}
  .renderItem=${(item, index) => html`
    <lr-conversation-item
      id=${item.id}
      title=${item.title}
      .timestamp=${item.updatedAt}
      ?active=${item.id === currentId}
    ></lr-conversation-item>
  `}
  .keyFunction=${(item) => item.id}
  active-item-id=${currentId}
  ?has-more=${hasMorePages}
  ?loading=${isLoadingMore}
  @lr-load-more=${() => loadNextPage()}
  @lr-visible-range-change=${(e) => console.log("visible", e.detail.start, e.detail.end)}
  @lr-virtual-scroll=${(e) => console.log("scroll top", e.detail.scrollTop)}
></lr-virtual-list>`;
```

```ts
import { html } from "lit";

// No count-sized array: only the current window is read.
const syntheticRows = {
  count: 100_000,
  itemAt: (index: number) => ({ page: index + 1 }),
  keyAt: (index: number) => index + 1,
  indexOfKey: (key: string | number) =>
    typeof key === "number" ? key - 1 : -1,
};

html`<lr-virtual-list
  row-height="72"
  .source=${syntheticRows}
  .renderItem=${(row) => html`Page ${row.page}`}
></lr-virtual-list>`;
```

```ts
import { html } from "lit";

// Sticky group headers: the header is a real row, so the `groups` entries are position anchors
// only (`label: ''`); the pinned copy remains strictly presentational.
const view = html`<lr-virtual-list
  .items=${rows}
  .groups=${groupStarts /* [{ key: 'Today', label: '', startIndex: 0 }, …] */}
  .renderItem=${(item, index) => (item.isHeader ? headerTemplate(item) : rowTemplate(item))}
  .renderStickyGroup=${(group) => headerTemplate(group)}
></lr-virtual-list>`;
```

Every row is positioned by a `transform: translateY(offset)`, rather than page flow, so only a small
DOM window exists while the scrollbar still reflects the full collection. Array sources retain their
cumulative-offset cache, rebuilt only when the collection/height/key inputs or a measurement change —
never on a pure scroll tick. Indexed sources never synthesize count-sized item, key, identity, or
offset arrays: fixed-height offsets are direct count arithmetic, while auto-height offsets combine the
default estimate with sparse `ResizeObserver` measurements for rows that have actually mounted.

**Known gotchas:**

- `items`, `source`, `renderItem`, `keyFunction`, and `groups` are all `attribute: false` — they must
  be set as JS properties (`.source=`, `.items=`, `.renderItem=`, …), never as HTML attribute strings.
- The container is `role="list"` with rows `role="listitem"`, deliberately not `listbox`/`option` —
  this component only provides windowing, not the roving-tabindex/`aria-activedescendant`
  keyboard-interaction contract a real `listbox` requires. `active-item-id` only scrolls a row into view and
  marks it `aria-current`; it is not a selection widget. Compose your own selection behavior on top if
  needed.
- `[part="base"]` carries `tabindex="0"` unconditionally, since `renderItem`'s caller-supplied content
  isn't guaranteed to contain a focusable element and an otherwise-unreachable-by-keyboard scroll
  region would result.
- Ordinary row content wraps by default, including long unbroken values. Set `white-space: nowrap`
  only for content that intentionally needs an unbroken horizontal scrollport; it overrides that
  default without clipping the row.
- `aria-setsize`/`aria-posinset` are computed from a row's real index in the full `items` array, not its
  position among the currently-rendered DOM window, so assistive tech still announces e.g. "item 12 of
  340" correctly even though only a handful of rows exist in the DOM at a time.
- `groups`, `renderStickyGroup`, `offsetForIndex()`/`indexAtOffset()` and the `lr-virtual-scroll`
  event are
  all expressed against the _same_ windowing math, so they agree with each other — but that math is
  estimate-based in `row-height="auto"` mode until the rows involved have been measured. Read a
  position after `await el.updateComplete`, and expect the value to converge rather than be final on
  the first frame.
- A sticky band only appears when `renderStickyGroup` _and_ at least one valid `groups` entry are
  both present; `groups` alone renders positioned markers with nothing pinned, and
  `renderStickyGroup` alone renders no overlay element at all.
- **A row that renders a popup needs the active-row lift, and this is why `[part='row']` has one.**
  Each row carries `will-change: transform` (a compositor hint for the per-frame translate), which
  makes every row its own stacking context. Rows otherwise carry no `z-index`, so they paint in DOM
  order and each one paints over the previous. Anything a row renders that overflows its own box —
  an `<lr-dropdown>` popup containing a row-action menu, a tooltip, an outward focus ring — is therefore painted
  _underneath_ every following row, no matter how high its own `z-index` is: that `z-index` only
  orders siblings inside the row's own context. The last row always looks correct, which is exactly
  why the failure tends to hide in short lists. A row lifts to `--lr-layer-content` while something
  inside it holds focus or while it contains an open `lr-dropdown`. The explicit dropdown-open branch covers
  imperative opening and virtual measurement/render cycles, where focus can temporarily return to
  the document while the popup remains visible. The value deliberately _matches_
  `[part='group']`'s rather than exceeding it, so the two land on the same layer and DOM order
  decides: groups render before the rows, so an active row wins while (and only while) it needs to,
  which is right — a group header is a non-interactive `pointer-events: none` label.

### Light-DOM row projection

`rowProjection="light"` exists for one shape: an application whose list rows are already styled by
its own global stylesheet, and which therefore could not adopt virtualization without rehoming a
dozen descendant rules per row into a new custom element or a growing set of custom properties. In
projection mode the windowed rows render into the host's own light DOM, so ordinary document CSS
reaches row content directly.

Positioning, measurement and semantics stay where they were. The `[part="row"]` wrapper remains in
the shadow root and keeps `position: absolute`, the per-frame `transform`, `role`, `aria-setsize`/
`aria-posinset` (or `aria-rowindex`) and the `ResizeObserver` box — document CSS cannot select it,
so consumer styles can never break windowing. The whole part vocabulary (`base`, `spacer`, `row`,
`group`, `sticky-group`) keeps matching in both modes, and `row-height="auto"` still measures
projected content because the light row is an ordinary in-flow child of that wrapper.

`projectedRows: HTMLElement[]` returns the projected light-DOM row wrappers in item order, and is
empty outside projection mode. The exported type is `LyraVirtualListRowProjection`; the reserved
attributes marking library-owned light-DOM nodes are exported as `VIRTUAL_LIST_ROW_ATTRIBUTE`
(`data-lr-virtual-list-row`) and `VIRTUAL_LIST_STICKY_ATTRIBUTE` (`data-lr-virtual-list-sticky`).

**Known gotchas, all inherent to handing the cascade back to the consumer:**

- **One component-owned wrapper sits between the host and your markup.** A slot cannot assign a text
  node or a multi-root fragment by attribute, so each row's content lives inside a wrapper carrying
  `data-lr-virtual-list-row`. Descendant selectors (`lr-virtual-list .row-title`) port unchanged;
  child combinators (`lr-virtual-list > .row`), `:nth-child`, `:first-child` and sibling combinators
  written against the unvirtualized markup do not. `:nth-child` on the wrappers reflects the current
  *window*, not the item index.
- **`closest('[part="row"]')` stops resolving.** A delegated listener on the host now sees an
  un-retargeted `event.target` inside the light DOM. Use `closest('[data-lr-virtual-list-row]')`.
- **The document cascade now reaches row content**, including resets and element-level rules that
  previously could not, so a projected row can look different from the same row in shadow mode.
- **Per-row light-DOM state does not survive a disconnect/reconnect.** Disconnect removes the
  projected rows completely (no rows, no markers, no anchor left behind), so a reparenting move
  rebuilds them. Scroll position, measurements and the window are unaffected — they live in
  component state, not in the rows.
- **Projection activates one task after hydration.** A server render has no DOM to project into, so
  the first window is shadow-rendered, hydration matches the server markup, and the rows then swap
  into the light DOM on the next task.
- **A row taken out of flow collapses its wrapper.** `position: fixed`/`absolute` or
  `display: none` on your own row leaves nothing for the wrapper to measure.

---

## `lr-app-rail`

A responsive navigation rail that adapts across three presentations as the _viewport_ narrows (not
this element's own inline size): `'full'` (nav items show icon + label, inline), `'icon-only'` (a
narrower inline rail, icons only), and `'mobile'` (hidden behind a toggle button; opening it shows a
focus-trapped floating overlay over the page). First-party invention (no `wa-*`/`sl-*` counterpart).
Breakpoints are viewport-width `matchMedia()` queries against `icon-only-breakpoint`/
`mobile-breakpoint`, not a `ResizeObserver` on this element — presentation tracks the actual device/
window width the way a native OS shell's navigation does, not however much horizontal space a
particular layout happens to give it. `[part="base"]` (the inline `'full'`/`'icon-only'`
presentation) and `[part="panel"]` (the mobile overlay) are the _same_ element promoted in place
across modes (mirrors `<lr-widget>`'s fullscreen mode) — never both at once, and slotted nav
content is never duplicated.

Opting in to `resizable` adds a continuously draggable width for the `'full'` state: a
`[part="resizer"]` handle (pointer-drag and Left/Right-arrow keyboard stepping, RTL-aware) clamped to
`[minRailWidthPx, maxRailWidthPx]`. Set `storageKey` (attribute `storage-key`) to persist the fields
selected by `persist` to `localStorage` under `lr-app-rail:${storageKey}` and restore them on the
next mount (mirrors `lr-multi-split`'s `storage-key`; effective `mode` is breakpoint-derived and never
persisted). The backward-compatible allowlist is `open width`; use
`persist="width preferred-mode"` for durable layout preference without restoring the transient
mobile overlay. Without a `storageKey` there is no persistence — listen for `lr-rail-resize` and
persist its committed `widthPx` yourself. Listen for the preceding cancelable
`lr-rail-resize-request` event when a host needs to veto a proposed width.
`preferredMode` separately lets a host manually prefer `'full'`/`'icon-only'` for the non-mobile
breakpoint axis (e.g. a user's own collapse toggle) while `mobile-breakpoint` continues to be tracked
automatically regardless — it's only consulted while `forceMode` is `'auto'` or unset; an explicit
`forceMode` value takes full priority. A `preferredMode` restored from `localStorage` on mount is
observable the same way a live change is: it fires `lr-mode-change` too (see **Events** below),
letting a consumer that syncs app chrome to the rail's mode pick up the restored value on load.

**Properties:**

- `mode: LyraAppRailMode` (custom accessor, reflected, read-only as of 9.0.0) — always resolves to
  one of the three real modes (`'full'|'icon-only'|'mobile'`), never `'auto'`; assigning it now
  throws (`el.mode = 'icon-only'` -> TypeError).
- `forceMode?: 'full' | 'icon-only' | 'auto'` (attribute `force-mode`, reflected) — replaces `mode`'s
  former write side as of 9.0.0. Assigning `'full'`/`'icon-only'` pins that mode and stops the
  element responding to breakpoint changes; assigning `'auto'` (or leaving it unset) releases the
  pin and resumes automatic viewport tracking. `'mobile'` can never be force-pinned here — the
  mobile breakpoint is always tracked automatically regardless, mirroring `preferredMode`'s scope
  below; widen `mobile-breakpoint` for a guaranteed-mobile state instead. Settable via the
  `force-mode` attribute too (`force-mode="icon-only"`, `force-mode="auto"`).
- `iconOnlyBreakpoint: string = '960px'` (attribute `icon-only-breakpoint`) — any valid CSS length,
  used directly in a `(max-width: ...)` media query; below it the rail switches from `'full'` to
  `'icon-only'`.
- `mobileBreakpoint: string = '600px'` (attribute `mobile-breakpoint`) — same mechanism; below it the
  rail switches from `'icon-only'` to `'mobile'`. Should be smaller than `iconOnlyBreakpoint` to
  produce all three states as the viewport narrows.
- `open: boolean = false` (reflected) — whether the mobile floating overlay is shown. Only meaningful
  while `mode` is `'mobile'`; leaving mobile mode closes it so a later mobile transition cannot
  restore a stale modal. Set this directly, or use the built-in toggle button — there is no separate
  `show()`/`hide()` pair.
- `label?: string` — optional accessible name for the rail's navigation landmark and mobile dialog.
  Every nonempty supplied string is honored literally; only absence/empty uses the localized
  navigation fallback. A host-level `aria-label` attribute (including an explicit empty value)
  takes precedence.
- `preferredMode?: 'full' | 'icon-only' | null` (attribute `preferred-mode`) — manually prefers
  `'full'` or `'icon-only'` for the non-mobile breakpoint axis, while `mobile-breakpoint` continues to
  be tracked automatically regardless — e.g. a user's manual collapse toggle that should still yield
  to a genuinely too-narrow-for-any-inline-rail viewport. Only consulted while `forceMode` is
  `'auto'` or unset (see above); an explicit `forceMode` value takes full priority.
  Unset (the default, `null`) reproduces the original breakpoint-only behavior exactly.
- `collapsible: boolean = false` (reflected) — opts in a desktop collapse control rendered inside
  `[part="header"]`. It flips the rail between its `'full'` and `'icon-only'` presentations by
  writing `preferredMode`, so the `mobile-breakpoint` keeps being tracked automatically and a
  genuinely too-narrow viewport still wins. The control is not rendered at all while `mode` is
  `'mobile'`, and `[part="header"]`'s layout is unchanged when this is unset. The collapse survives
  a reload only when `storage-key` is set AND `persist` includes `preferred-mode` — the default
  `persist` is `open width`, which does not. Pair them: `persist="width preferred-mode"`. Either
  route announces itself through the existing `lr-mode-change` event; there is no new event.
- `hideToggle: boolean = false` (reflected, attribute `hide-toggle`) — suppresses the built-in mobile
  `[part='toggle']` hamburger/OPEN button, for a consumer that already owns an external mobile-menu
  trigger wired to this rail's own `open` property (pair it with `trigger`/`for` below so focus
  still returns to that external trigger on close). `false` (the default) reproduces the exact
  existing output. This does not remove the button once the overlay is open: at that point it has
  been reparented inside the trapped `[part="panel"]` (see the CSS parts entry below) as the
  panel's only in-panel dismiss control, and hiding it there too would leave the open panel with no
  in-panel way to close it at all besides Escape/backdrop.
- `trigger: HTMLElement | null = null` (attribute: false) — direct reference to an external element
  that opens this rail's mobile overlay (e.g. an application-chrome hamburger button used together
  with `hideToggle`). When set (or resolved through `for`), closing the overlay by any path —
  Escape, backdrop click, a nav-item click, or the built-in toggle itself — returns focus to it, the
  same guarantee the built-in toggle's own click already gets. Needed because a consumer's own
  JS-driven `open = true` never focuses anything, and even a real click does not reliably focus its
  target in every browser. Resolved once when the overlay opens; reassigning afterward changes the
  return target for the remainder of that overlay's open lifetime. Read alongside `for`; this direct
  reference wins when both resolve to different elements. Unset (the default, `null`) reproduces the
  exact existing behavior: only the built-in toggle's own click supplies a return target, for that
  interaction alone. 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, engines resolve `aria-controls` to the
  `<lr-app-rail>` host itself; either resolution is correct. The association applies while `mode` is
  `'mobile'` and is released when the rail leaves that mode or disconnects, and it tracks live —
  reassigning `trigger` moves the state to the new element.
- `for: string = ''` — id of an external element that opens this rail's mobile overlay, the
  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.
  Ignored once `trigger` is itself set.
- `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
  exactly as before this property existed.
- `railWidthPx?: number` (attribute `rail-width-px`) — the rail's current width in px while
  `resizable`; settable/gettable directly. Unset defers to `--lr-app-rail-width`'s own resolved
  width.
- `storageKey?: string` (attribute `storage-key`) — when set, persists the fields selected by
  `persist` to `localStorage` under `lr-app-rail:${storageKey}` and restores them on the next
  mount. Each field is restored only when the consumer has not assigned it on that same mount: an
  `open`/`rail-width-px`/`preferred-mode` attribute, or a `.open=${false}`-style binding, wins over
  stored state, and a restored `open` fires no `lr-toggle`. Effective `mode` is breakpoint-derived
  and never persisted. Unset means no persistence.
- `persist: string = 'open width'` — whitespace-separated field allowlist used with `storageKey`.
  Valid `LyraAppRailPersistField` tokens are `open`, `width` (`railWidthPx`), and `preferred-mode`
  (`preferredMode`). The default preserves the existing open+width behavior. Use
  `persist="width preferred-mode"` when overlay-open state is controlled or should stay
  session-only.
- `minRailWidthPx: number = 190` (attribute `min-rail-width-px`) — minimum `railWidthPx` a
  drag/keyboard resize can reach.
- `maxRailWidthPx: number = 440` (attribute `max-rail-width-px`) — maximum `railWidthPx` a
  drag/keyboard resize can reach.
- `dragging: boolean = false` (reflected, read-only as of 9.0.0) — `true` for the duration of an
  active pointer-driven resize drag (not a keyboard step); reflected so a consumer (or this
  component's own styles) can suppress `[part='base']`'s `transition: inline-size` during the drag,
  which otherwise visibly "chases" the pointer instead of tracking it 1:1. This component always
  owned every drag transition itself; assigning it now throws (`el.dragging = true` -> TypeError).

Also settable as a plain `aria-label` attribute (not a reactive property): overrides the computed
`label`/localized-default accessible name on both the navigation landmark and the mobile dialog
role, matching `<lr-date-input>`'s `accessibleLabel`.

**Methods:** `toggleCollapse(): void` performs the same `'full'`/`'icon-only'` flip `collapsible`'s
built-in control does, for a consumer rendering its own control (app chrome, a command palette, a
keyboard shortcut). A no-op while `mode` is `'mobile'`. While `forceMode` pins the mode the
preference is still recorded and takes effect once the pin is released.

**Events:** `lr-mode-change` (`detail: LyraAppRailModeChangeDetail` = `{ mode: LyraAppRailMode }`; the
effective mode changed, whether from a breakpoint crossing, a `forceMode` assignment, or a
persisted `preferred-mode` restored on mount (`storage-key` + `persist="preferred-mode"`) — the
restored-on-mount case fires once, from the first `updated()` after that mount's render and
attribute reflection have both landed, rather than synchronously during the mount itself; it is
not fired for a redundant reassignment to the mode already in effect, nor when no preferred mode
was persisted), `lr-toggle`
(`detail: LyraAppRailToggleDetail` = `{ open: boolean }`; the mobile overlay is opening or closing — via
the built-in toggle button, Escape, a backdrop click, a nav-item click while open, or a
breakpoint/forced mode change leaving `'mobile'` while open — not fired when a consumer sets `open`
directly. Cancelable for every trigger except the forced mode-change close, which always applies —
vetoing that one would leave `open` stuck `true` in a mode where it's meaningless; call
`preventDefault()` to keep the overlay as it is for the other triggers),
`lr-rail-resize-request` (`detail: LyraAppRailResizeDetail` = `{ widthPx: number }`; a cancelable
proposed width from drag or keyboard stepping, emitted before the component assigns
`railWidthPx` — call `preventDefault()` to keep the current width. A synchronous request listener
that disables resizing, leaves full mode, or disconnects the rail also cancels the proposal,
preserving any width the listener assigned and publishing no accepted resize. Assigning only
`railWidthPx` does not veto the proposal. It is not fired when a consumer sets `railWidthPx` directly), and `lr-rail-resize` (`detail: LyraAppRailResizeDetail` =
`{ widthPx: number }`; non-cancelable committed width, emitted immediately for a genuine keyboard
step and once at pointerup for a genuine drag. Clamped/no-op steps, canceled/lost gestures, and
consumer property writes emit no committed event).

**Slots:** default (nav items — generic slotted content, e.g. `<a>`/`<button>` elements the consumer
builds with its own icon+label structure; clicking anywhere in this slot closes the mobile overlay if
open), `header` (logo/brand content, shown above the nav items in every mode), `footer` (a trailing
user/settings trigger, shown below the nav items).

**CSS parts:** `base`, `header`, `nav`, `footer`, `toggle` (hidden via CSS outside `'mobile'` mode, or
-- while it is not also serving as the panel's only in-panel dismiss control -- via `hideToggle`;
reparented to be the first child of `[part="panel"]` for exactly as long as the mobile overlay is
open, so the shared focus trap, scoped to the panel alone, can reach it and Tab cycles through it
like `<lr-dialog>`'s in-panel close button, then moved back to its resting position, a sibling
immediately ahead of `[part="panel"]`, once closed; the same button element is reused throughout,
never destroyed/recreated, so a reference captured before opening remains valid after closing, and
it renders as its own reserved row ahead of the `header` slot rather than an absolute overlay on
top of it, so a wide/slotted header is never obscured), `backdrop`, `panel` (`base`/`panel` are mutually exclusive on the same
underlying element — see above), `resizer` (the `resizable` opt-in's drag handle, only rendered while
`resizable` and `mode` is `'full'`; its hit target is `--lr-icon-button-size`-wide), `resizer-track`
(the slim 3px visible drag line centered inside that hit target, tinted `--lr-color-brand` on hover),
`collapse-toggle` (the opt-in desktop collapse control, rendered inside `[part="header"]` only while
`collapsible` is set and `mode` is not `'mobile'`; it renders `aria-expanded` in both states, points
`aria-controls` at `[part="nav"]` — the item list whose presentation actually changes, never the
containing `[part="base"]`/`[part="panel"]` — and takes a localized name from the
`appRailCollapse`/`appRailExpand` keys) and `collapse-icon` (the chevron wrapper, mirrored by its own
`transform` under RTL). Collapsing to `'icon-only'` removes nothing from the accessibility tree — it
clips each item's `label`/`meta` visually — so `aria-expanded` reports which of the two
presentations is on screen, for magnifier and braille users, rather than announcing hidden content.

**Themeable custom properties:** `--lr-app-rail-width` (default `15rem` — the inline rail width in
`'full'` mode), `--lr-app-rail-icon-width` (default `4rem` — the inline rail width in `'icon-only'`
mode), `--lr-app-rail-mobile-width` (default `18rem`, capped at `85vw` — the mobile overlay panel
width), `--lr-app-rail-overlay-color` (default `var(--lr-color-overlay)` — the mobile backdrop scrim
color; component-specific since no shared token exists), `--lr-app-rail-panel-inset-block-start`
(default `0`, applied to both `[part="panel"]` and `[part="backdrop"]` — raise it to leave room for
a fixed app bar/status area above the drawer instead of the panel/scrim starting flush with the
viewport top), `--lr-app-rail-panel-radius` (default `0` — uniform corner radius of `[part="panel"]`;
pairs naturally with a nonzero `--lr-app-rail-panel-inset-block-start`, which exposes the panel's top
corners). Four direction-aware per-corner tokens each default to `--lr-app-rail-panel-radius`, so
setting only the uniform token still rounds all four corners exactly as before:
`--lr-app-rail-panel-radius-start-start` and `--lr-app-rail-panel-radius-end-start` (logical
`border-start-start-radius`/`border-end-start-radius` — the two corners at the panel's own flush
inline-start edge, since the drawer always sits flush against `inset-inline-start: 0`) and
`--lr-app-rail-panel-radius-start-end`/`--lr-app-rail-panel-radius-end-end` (logical
`border-start-end-radius`/`border-end-end-radius` — the two corners away from that flush edge, the
pair a flush-against-one-edge drawer typically rounds). All four are logical, so which physical
corner each one paints swaps under `dir="rtl"` with no second consumer rule.
`--lr-app-rail-panel-overflow-block` (default `auto`) and
`--lr-app-rail-panel-overflow-inline` (default `clip`) — `[part="panel"]`'s logical overflow axes;
either non-`visible` value clips a `position: fixed` popup opened by a slotted/nav-item control
(e.g. a slotted `<lr-select>`/`<lr-menu>`) whenever its rendered box extends past the panel,
regardless of that popup's own containing block. Per the CSS overflow spec, a lone `visible` axis
paired with a non-`visible` other axis computes as `auto` instead (still clipping) — set **both**
tokens to `visible` together to actually stop the clipping, accepting that wide header/footer
content can then scroll/bleed both ways. `--lr-app-rail-background` (default
`var(--lr-color-surface)` — `[part="base"]`'s background, the docked non-overlay presentation) and
`--lr-app-rail-panel-background` (default `var(--lr-color-surface-overlay)` — `[part="panel"]`'s
background, the mobile overlay presentation; kept separate from `--lr-app-rail-background`/
`--lr-app-rail-overlay-color` since the panel is deliberately themed as a modal surface, not the
docked rail chrome). `--lr-app-rail-header-padding` and `--lr-app-rail-footer-padding` (both default
`var(--lr-space-m)`) retune `[part="header"]`/`[part="footer"]`'s padding independently.
`--lr-app-rail-header-min-block-size` (default `auto`, the property's own initial value, so unset
reproduces today's exact height) reserves a minimum height for `[part="header"]`, for content that
mounts or resizes asynchronously. `--lr-app-rail-nav-padding` and `--lr-app-rail-nav-gap` (default
`var(--lr-space-s)`/`var(--lr-space-xs)`, the values this rule hard-coded before either token
existed) retune `[part="nav"]`'s own padding and inter-item gap — the rail's vertical rhythm,
previously reachable only through `::part(nav)`. Plus shared
tokens (`--lr-color-border`,
`--lr-color-surface`, `--lr-color-text`, `--lr-color-brand`, `--lr-color-brand-quiet`,
`--lr-space-*`, `--lr-radius`, `--lr-shadow`, `--lr-icon-button-size`,
`--lr-focus-ring-*`, `--lr-transition-base`). `resizable`'s width is driven entirely by
`railWidthPx`'s inline `inline-size` style rather than a new custom property.
The mobile toggle's hover/pressed background and foreground are independently inheritable through
`--lr-app-rail-toggle-hover-bg`, `--lr-app-rail-toggle-hover-color`,
`--lr-app-rail-toggle-active-bg`, and `--lr-app-rail-toggle-active-color`. `[part="collapse-toggle"]`
has the matching set: `--lr-app-rail-collapse-toggle-hover-bg` (default
`var(--lr-color-brand-quiet)`), `--lr-app-rail-collapse-toggle-hover-color` (default
`var(--lr-color-brand)`), `--lr-app-rail-collapse-toggle-active-bg` (no default) and
`--lr-app-rail-collapse-toggle-active-color` (default `var(--lr-color-brand)`). The resizer track uses
`--lr-app-rail-resizer-hover-bg` and `--lr-app-rail-resizer-active-bg`. Each hook is an inline
fallback at its exact state rule and preserves the previous brand or active-mix value when unset.

**Optional peer deps:** none.

```html
<lr-app-rail
  label="Main navigation"
  icon-only-breakpoint="960px"
  mobile-breakpoint="600px"
  resizable
>
  <span slot="header"><img src="/logo.svg" alt="Acme" /></span>
  <a href="/inbox" aria-label="Inbox"
    ><svg aria-hidden="true">...</svg><span>Inbox</span></a
  >
  <a href="/settings" aria-label="Settings"
    ><svg aria-hidden="true">...</svg><span>Settings</span></a
  >
  <span slot="footer"><button>Profile</button></span>
</lr-app-rail>
<script type="module">
  const rail = document.querySelector("lr-app-rail");
  rail.addEventListener("lr-rail-resize-request", (e) => {
    if (e.detail.widthPx > 360) e.preventDefault();
  });
  rail.addEventListener("lr-rail-resize", (e) =>
    localStorage.setItem("railWidthPx", String(e.detail.widthPx))
  );
</script>
```

```ts
rail.forceMode = "icon-only"; // force a presentation regardless of viewport width
rail.forceMode = "auto"; // release the force, resume live breakpoint tracking
```

The package root also exports a pure `computeAppRailMode(iconOnlyMatches: boolean, mobileMatches:
boolean, preferredMode?: 'full' | 'icon-only' | null): LyraAppRailMode` resolver (plus the
`LyraAppRailMode`/`LyraAppRailModeInput`/`LyraAppRailPreferredMode`/`LyraAppRailPersistField`/
`LyraAppRailModeChangeDetail`/`LyraAppRailToggleDetail`/`LyraAppRailResizeDetail` types) — the same
logic the element's internal `matchMedia` listeners call, exposed standalone so a
consumer can compute or unit-test the same resolution without a real browser window. `mobileMatches`
wins over everything else when true (the viewport is narrower than both breakpoints at once);
otherwise `preferredMode` (when set) wins over `iconOnlyMatches`.

The mobile state keeps its own panel template rather than nesting `<lr-dialog>`, while its modal
behavior participates in the shared overlay stack. It is a plain `<div>` with an explicit
`role="navigation"` (swapping to `role="dialog"` while the overlay is open) rather than a literal
`<nav>` tag, since a
`<nav>`'s implicit role can't be overridden to `role="dialog"` without an `aria-allowed-role`
violation. In `'icon-only'` mode, slotted nav items lose their visible text label — give each one a
real accessible name (`aria-label`, visually hidden text, or `title`) regardless, since this
component only lays out whatever is slotted and can't inspect or fix up a consumer's own markup.

**Known gotchas:**

- `mode` is the readonly `LyraAppRailMode` result. `forceMode` accepts the non-mobile
  `LyraAppRailPreferredMode` values plus the `'auto'` release sentinel, so whether the rail is
  pinned or tracking the viewport remains directly observable.
- reassigning `icon-only-breakpoint`/`mobile-breakpoint` after first render tears down and rebuilds
  the `matchMedia` listeners, but does not itself clear `forceMode` — if a consumer set
  `forceMode = 'icon-only'`, changing the breakpoints won't resume auto-tracking until
  `forceMode = 'auto'` is set explicitly.
- leaving `'mobile'` mode while `open` (via a breakpoint crossing or a `forceMode` reassignment)
  auto-closes the overlay through the same path as the toggle button, so `lr-toggle` still fires
  and the scroll lock/focus trap still release normally — a consumer listening only for explicit
  toggle-button clicks would miss this closure.
- the mobile panel is also given `inert` whenever `mode === 'mobile'` and `open` is `false` — it's
  removed from the accessibility tree and tab order via `inert` at the same time it's hidden visually
  via `transform: translateX(-100%)`, both applied simultaneously rather than one implying the other.
- the offscreen slide direction for the mobile panel is flipped for RTL via a `:dir(rtl)` CSS
  selector (`translateX(100%)`), not through the shared `internal/rtl.ts` JS helper used for pointer/
  keyboard math elsewhere in this library — a physical `transform` isn't expressible with logical
  properties, so this one case is handled purely in CSS.
- a reconnect that preserves the same element instance (e.g. a drag-and-drop reparent) resumes its
  shared overlay registration and re-acquires the scroll lock if the overlay was still active
  across the move — `disconnectedCallback`/`connectedCallback` fire back-to-back with no update in
  between, so `willUpdate()` alone wouldn't otherwise notice.
- `resizable`'s drag handle is pointer-only (`pointerdown`/`pointermove`/`pointerup`/
  `pointercancel`/`lostpointercapture`) plus discrete Left/Right-arrow keyboard stepping (8px per
  press, RTL-aware) — there's no dedicated touch gesture beyond what Pointer Events already unify.
- reassigning `railWidthPx` while `resizable` is unset has no visible effect on the rendered width —
  the fixed-width `--lr-app-rail-width` token still governs `'full'`-mode width until `resizable`
  is also set.
- reassigning `icon-only-breakpoint`/`mobile-breakpoint`/`preferredMode` does not itself un-force a
  previously-forced `mode` — same caveat as above, `preferredMode` is only consulted while `mode`
  isn't force-pinned.
- the built-in toggle physically moves in the DOM: it is a sibling immediately ahead of
  `[part="base"]`/`[part="panel"]` while closed (or outside mobile mode), and the first child of
  `[part="panel"]` while the mobile overlay is open. This is a real reparent via `insertBefore`
  (not a template-conditional recreate), so an event listener or a captured element reference
  stays valid across the transition — a MutationObserver watching a specific fixed container would
  still need to account for the move.
- opening the mobile overlay moves initial focus to the first focusable nav item (or the panel
  itself when nothing in the slotted content is focusable), never to the toggle — even now that
  the toggle lives inside the panel as its structurally-first child. Tab still reaches it as part
  of the trap's normal cycle.

### `lr-app-rail-item`

An explicit navigation item for `<lr-app-rail>`. It renders an accessible link when `href` is
set and enabled, otherwise a button; the rail can add its `icon-only` presentation state without
removing the label from the accessibility tree.

**Properties:**

- `href: string = ''` — optional destination. Without it, the item renders as a button.
- `target: string = ''` — optional link target.
- `disabled: boolean = false` (reflected) — prevents activation while retaining the item in the rail.
- `current: boolean = false` (reflected) — marks this as the destination for the current page/view;
  reflects `aria-current="page"` on `[part='base']` and drives the current visual treatment. The rail
  has no built-in routing, so the consumer sets this per item (e.g. by comparing `href` against the
  current location). `active`, a deprecated alias in both property and attribute form, was removed
  in 16.0.0 (available since 11.2.0; eligible for removal from 13.0.0) — use `current`.
- `tooltip: boolean = false` (reflected) — opt-in hover/focus flyout (`[part='tooltip']`) showing
  this item's label text while the rail's `icon-only` mode (set externally by the parent
  `<lr-app-rail>` as the viewport narrows) hides it from view. No effect outside icon-only mode,
  since the label is already visible there. `false` (the default) reproduces the exact existing
  output.
- `expanded: boolean = false` (reflected) — whether this item's own `children` are shown. `false`
  reproduces exactly what an item without this property rendered before this feature existed.
  Driven through the same request/commit pair as `<lr-app-rail-group>`'s `open`, see Events below.

A host `aria-label` is copied to the rendered native link or button by attribute presence,
including an explicitly empty value; without it, the default slot supplies the native name. The
same precedence supplies the tooltip text when that opt-in flyout is visible, and the disclosure's
interpolated `{label}` (see Events below).

**Events:** `lr-toggle-request` — cancelable, emitted before `expanded` changes from the built-in
disclosure (`detail: { open }` — the field is named `open`, matching `<lr-app-rail-group>`'s
identical event name and detail shape exactly). Call `preventDefault()` to keep the current state,
or assign `expanded` from the listener to resolve it yourself; a write during the dispatch
suppresses the default commit even when it assigns the value the property already held. Not
emitted for a direct `expanded` write. `lr-toggle` — non-cancelable, emitted after `expanded` is
written, never for a vetoed or listener-resolved request (`detail: { open }`).

**Methods:** `click(): void` activates the internal native link or button; it is a no-op while
`disabled`.

If an `href`/`disabled` update replaces a focused link or button, focus follows an available native
replacement. When that replacement is disabled or inert, focus returns to the available element
that led into the item, or to the stable owning rail surface when no return target exists. A newer
external focus move is always preserved, and this repair dispatches no activation event.

**Slots:** default (the visible label), `icon` (the leading decorative icon, always hidden from
assistive technology and inert across its flattened subtree; the default slot or host `aria-label`
names the native control, which remains the sole action).

- `meta` slot — secondary trailing text (an unread count, a keyboard shortcut). Rendered as a
  SIBLING of the item's own link/button, so its text is not part of the item's accessible name and a
  pointer landing on it does not activate the item. Visually clipped in `icon-only` mode exactly as
  the label is, staying available to assistive technology.
- `end` slot — trailing controls or adornments (an overflow-menu trigger, a status badge). Also a
  sibling of the link/button — the shape `<lr-details>` uses for `header-actions` — so a slotted
  control keeps its own click, keyboard activation and focus order instead of being swallowed.
  Unlike `meta` it stays visible in `icon-only` mode, where it shares the narrow rail's width with
  the icon.
- `children` slot — nested `<lr-app-rail-item>`s disclosed beneath this item (the
  treeitem-with-link pattern: the row itself navigates, a separate disclosure expands its own
  child rows). Slotting anything into it grows a built-in `[part="toggle"]` disclosure button as a
  SIBLING of the item's own link/button, never nested inside it, so the link keeps navigating on
  its own and the disclosure keeps toggling on its own — clicking one never triggers the other.
  Leaving `children` empty renders neither the disclosure nor `[part="children"]` at all: an item
  authored without any `children` content renders byte-identically to one authored before this
  slot existed. The disclosure carries `aria-expanded` (both states) and `aria-controls` pointing
  at `[part="children"]`'s id, and a localized accessible name interpolating this item's own label
  (`Expand {label}`/`Collapse {label}` in the default locale — no literal fallback, so a
  `registerLyraLocale()` translation or a `.strings` override always reaches it). `<lr-app-rail-group>`
  cannot express this pattern: its collapsible heading *is* the toggle, so a navigable link cannot
  live inside it without nesting an interactive element inside a button.

  `icon-only` forwards from this item onto every `<lr-app-rail-item>` it directly owns through
  `children` — including ones appended later — exactly how `<lr-app-rail-group>` forwards onto the
  items and nested groups it owns. The disclosure itself never changes shape between
  presentations: it is always a fixed icon-button-sized square beside `[part="base"]`, reusing the
  same hover/active/focus tokens as the link/button (`--lr-app-rail-item-hover-bg` etc.) rather than
  a second disclosure-only set. There is no ancestor-current treatment — `<lr-app-rail-group>` has
  no equivalent concept for a group containing the current item, so none is invented here either; a
  current descendant stays perceivable only through its own `current` property.

Both wrappers (`[part="meta"]`, `[part="end"]`) are hidden while empty, so an item using neither
renders exactly as before. Note that while the mobile overlay is open, a click anywhere in the
rail's default slot closes it — including a click on an `end` control; that is the rail's documented
nav-slot behaviour, not new to these slots.

**CSS parts:** `base`, `icon`, `label`, `current-indicator` (a decorative inline indicator rendered
only while the item is `current`/`aria-current="page"`, mirroring `<lr-conversation-item>`'s
shipped `active-indicator` part — suppressed by default while `icon-only`, see the current-ring
tokens below), `tooltip` (the hover/focus label flyout, only rendered while `tooltip` is set, the
item is `icon-only`, and it is hovered or focused), `meta` (the wrapper around the `meta` slot,
hidden while empty), `end` (the wrapper around the `end` slot, hidden while empty), `toggle` (the
`children` disclosure, rendered only while something is slotted into `children`; a sibling of
`base`, never nested inside it), `toggle-icon` (the wrapper around the disclosure chevron,
direction-aware through this wrapper's own `transform` — mirrors `<lr-app-rail-group>`'s own
`[part="toggle-icon"]`) and `children` (the wrapper around the `children` slot, rendered only
alongside `toggle`; hidden — but present, so `aria-controls` keeps resolving — while `expanded` is
`false`).

**Themeable custom properties:** `--lr-app-rail-item-current-bg` (default
`var(--lr-color-brand-quiet)`), `--lr-app-rail-item-current-color` (default
`var(--lr-color-brand)`), and `--lr-app-rail-item-current-font-weight` (default
`var(--lr-font-weight-semibold)`) — background, text/icon color, and font weight of the `current`
(`aria-current="page"`) item. All three are scoped to `[aria-current='page']` only and declared as
inline `var()` fallbacks at the point of use, never on `:host`, so any can be set on the item itself
_or on any ancestor_ — including on `<lr-app-rail>` or a wrapper above it, to retheme every item's
current state at once. `::part(base)[aria-current='page']` is invalid CSS (Shadow Parts forbids an
attribute selector after `::part()`), so before these hooks the only lever was overriding the
library-wide `--lr-color-brand-quiet`/`--lr-color-brand`/`--lr-font-weight-semibold` tokens, which
repainted every other element reading them. Unset, each falls back to the token its rule used
before. `--lr-app-rail-item-current-font-weight` mirrors `<lr-stepper>`'s
`--lr-stepper-current-font-weight` and `<lr-segmented>`'s `--lr-segmented-selected-font-weight`.
`--lr-app-rail-item-current-indicator-color` (default `var(--lr-color-brand)`),
`--lr-app-rail-item-current-indicator-width` (default `var(--lr-size-2px)`), and
`--lr-app-rail-item-current-indicator-inset-inline` (default `0 auto`; set `auto 0` to place the
indicator at the inline-end edge instead) theme `[part="current-indicator"]`.
`--lr-app-rail-item-current-indicator-display` (no default; unset resolves to `none` while
`icon-only`) restores the indicator bar in icon-only presentation — a full-height edge bar reads
as a rendering glitch on the square icon-only tile, so it is suppressed there by default; full
presentation is unaffected either way, since its own `[part="current-indicator"]` rule declares no
`display` at all. `--lr-app-rail-item-current-ring` (no default; unset resolves to `none` in full
presentation and an inset ring in icon-only presentation) sets `box-shadow` on `[part="base"]`
while current: unset, icon-only gets an inset ring automatically — the non-color-only signal
(WCAG 1.4.1) that replaces the bar suppressed there, since full presentation already conveys
current state through the indicator bar and `--lr-app-rail-item-current-font-weight`. Setting this
token explicitly applies the same value in both presentations.
Ordinary interaction states are independently inheritable through
`--lr-app-rail-item-hover-bg`, `--lr-app-rail-item-hover-color`,
`--lr-app-rail-item-active-bg`, and `--lr-app-rail-item-active-color`, again retaining the former
brand/active-mix values as fallbacks.
`--lr-app-rail-item-min-block-size` (default `var(--lr-icon-button-size)`, floor-clamped to that
same token regardless of the override so the row's own hit target can never shrink below the WCAG
2.5.8 minimum), `--lr-app-rail-item-padding` (default `var(--lr-space-s)`),
`--lr-app-rail-item-gap` (default `var(--lr-space-s)`, the gap between `[part="icon"]` and
`[part="label"]`, and now also between the item's control and the `meta`/`end` adornments),
`--lr-app-rail-item-meta-color` (default `var(--lr-color-text-quiet)`),
`--lr-app-rail-item-meta-font-size` (default `var(--lr-font-size-sm)`),
`--lr-app-rail-item-icon-size` (default `var(--lr-icon-button-size)`, not
floor-clamped since the icon is decorative, not itself a pointer target), and
`--lr-app-rail-item-font-size` (default `inherit`, set after the `font` shorthand so only the size
is retuned while family/weight/line-height stay inherited) retune the row's geometry.
While `icon-only`, `[part="base"]` resolves to a square hit target matching the icon-button
footprint used elsewhere in this library (`aspect-ratio: 1` against its already floor-clamped
block size) instead of stretching across the rail's icon column. `--lr-app-rail-item-icon-only-size`
(no default) sizes that square directly — both `inline-size` and `block-size`, and the row's own
`min-block-size` floor — independent of `--lr-app-rail-item-min-block-size`, so a taller expanded
row and an icon-only square pinned to `--lr-icon-button-size` can coexist. Unset, the square is
still derived via `aspect-ratio: 1` against the row's block size exactly as before.

**`--lr-positioning-strategy`** (16.0.0) — the icon-only flyout tooltip reads this same cascading
`absolute`/`fixed` override documented on `<lr-popover>` when it is (re)positioned, falling back to
its own `fixed` default when nothing is set. There is no per-instance `positioning-strategy`
property on `<lr-app-rail-item>`; set the custom property on `:root`, a theme, or one clipping
ancestor to change every unset rail item's flyout beneath it.

`--lr-app-rail-item-indent` (default `var(--lr-space-l)`) sets `[part="children"]`'s
`padding-inline-start`. Applied once per nesting level — a doubly-nested `children` list compounds
two insets automatically, since each level's own `[part="children"]` applies the token again.
Logical, so it mirrors under `dir="rtl"` with no separate rule.

**Optional peer deps:** none.

---

### `lr-app-rail-group`

Titles, and optionally collapses, a section of `<lr-app-rail-item>`s. Grouping is by composition —
the group holds whatever it is given; there is no items array and no renderer callback, so it can
never disagree with what is rendered inside it.

```html
<script type="module">
  import '@aceshooting/lyra-ui/components/layout/app-rail-group/app-rail-group.js';
</script>

<lr-app-rail>
  <lr-app-rail-group heading="Workspaces" collapsible>
    <button slot="header-actions" aria-label="Add workspace">+</button>
    <lr-app-rail-item href="/atlas" current>Atlas</lr-app-rail-item>
    <lr-app-rail-item href="/beacon">Beacon</lr-app-rail-item>
  </lr-app-rail-group>
</lr-app-rail>
```

**Properties:**

- `heading: string = ''` — the section title. The `heading` slot replaces it when populated.
- `headingLevel: number = 3` (attribute `heading-level`) — the `aria-level` the heading landmark
  reports. Clamped to 1-6 and rounded; a non-finite value falls back to `3`. Settable because a rail
  sits at a different depth in every page that embeds it.
- `collapsible: boolean = false` (reflected) — opts in the built-in collapse control. The heading's
  own text becomes the button carrying `aria-expanded` and `aria-controls`, which is the accordion
  pattern; an unnamed group falls back to a localized `Collapse`/`Expand` name.
- `open: boolean = true` (reflected) — whether the content is shown. Carries a true-default
  converter, so `open="false"` parses from markup (a plain presence-based boolean cannot). `open`
  governs visibility whether or not `collapsible` is set, so a consumer can drive collapse entirely
  from its own chrome.

**Events:** `lr-toggle-request` — cancelable, emitted before `open` changes from the built-in
control (`detail: { open }`). Call `preventDefault()` to keep the current state, or assign `open`
from the listener to resolve it yourself; a write during the dispatch suppresses the default commit
even when it assigns the value the property already held. Not emitted for a direct `open` write.
`lr-toggle` — non-cancelable, emitted after `open` is written, never for a vetoed or
listener-resolved request (`detail: { open }`).

**Slots:** default — the group's items, and any nested `<lr-app-rail-group>`s; `heading` — rich
heading content; `header-actions` — controls beside the heading, rendered as a sibling of the
collapse control so activating one never toggles the group.

**CSS parts:** `base`, `header`, `heading`, `heading-text`, `toggle`, `toggle-icon`,
`header-actions`, `content`.

**Themeable custom properties:** `--lr-app-rail-group-gap` (default `var(--lr-space-xs)`),
`--lr-app-rail-group-padding-block` (default `var(--lr-space-xs)`),
`--lr-app-rail-group-heading-color` (default `var(--lr-color-text-quiet)`),
`--lr-app-rail-group-heading-font-size` (default `var(--lr-font-size-sm)`),
`--lr-app-rail-group-hover-bg` (default `var(--lr-color-brand-quiet)`),
`--lr-app-rail-group-hover-color` (default `var(--lr-color-brand)`),
`--lr-app-rail-group-active-bg` (no default), `--lr-app-rail-group-active-color` (default
`var(--lr-color-brand)`).

The owning rail marks a slotted group `icon-only` exactly as it marks a slotted item, and the group
forwards that to the items and nested groups it *directly* owns — including ones appended later —
so grouping survives the rail's icon-only presentation. A nested group re-forwards in turn, so
exactly one element ever writes `icon-only` onto any given node and a nested group clips its own
heading too. In that mode the heading text is clipped out of layout — whether or not the group is
collapsible — but stays in the accessibility tree. While `collapsible` too, `[part="toggle"]`
resolves to a square hit target matching the icon-button footprint used elsewhere in this library,
instead of stretching across the header row (mirroring `<lr-app-rail-item>`'s own `[part="base"]`).

**Optional peer deps:** none.

---

## `lr-responsive-panel`

The same slotted content either docked inline in its containing layout or presented as a
full-screen/bottom-sheet/side-anchored overlay, depending on the panel's allocated inline size.
First-party invention (no `wa-*`/`sl-*` counterpart).

**Properties:**

- `open: boolean = false` (reflected) — in the inline presentation this just means visible/mounted;
  in the overlay presentation this is the actual modal open/closed state.
- `mode: LyraResponsivePanelMode = 'auto'` (reflected) — `'auto'` tracks `overlay-breakpoint`
  against the component's allocation; `'inline'`/`'overlay'` force that presentation.
- `effectiveMode: LyraResponsivePanelEffectiveMode` (readonly) — the currently resolved
  `'inline'|'overlay'` presentation.
- `shape: LyraResponsivePanelShape = 'fullscreen'` (reflected) — only affects the overlay
  presentation's visual treatment: `'fullscreen'` covers the whole viewport; `'bottom-sheet'`
  anchors to its block-end edge and does not cover the full height; `'start'`/`'end'` anchor to the
  matching *logical* inline edge instead, like a docked sidebar's slide-in-from-the-edge overlay
  counterpart — the anchored edge and the panel's rounded free edge both flip automatically under
  `dir="rtl"` (logical `inset-inline-*`/border-radius properties, no `:dir()` selector involved).
  Has no visual effect while the effective presentation resolves to `'inline'`.
- `label: string = ''` — accessible name for the overlay presentation's `role="dialog"`, used
  verbatim when set — but a plain `aria-label` attribute on the host wins outright over `label`
  when both are present, the standard ARIA convention for a consumer that wants full control over
  the announced name (matching `lr-dialog`'s `accessibleLabel` pattern). When both the host
  `aria-label` and `label` are empty, this falls back to the `header` slot's content: a heading
  element (`h1`–`h6` or `[role="heading"]`) among the slotted header content wins if present,
  otherwise the header slot's combined text content is used (mirrors `lr-dialog`'s
  `detectHeading()` fallback, via `aria-label` rather than `aria-labelledby` since the header
  content is light DOM while `[part="panel"]` is in shadow DOM). A panel opened with none of a host
  `aria-label`, `label`, or header content uses the localized `responsivePanel` fallback (`"Panel"`
  in the default locale), so its dialog is never unnamed. Unused in the inline presentation, which
  has no dialog semantics to name.
- `overlayBreakpoint: string = '768px'` (attribute `overlay-breakpoint`) — CSS length compared with
  the component's allocated inline size in `mode="auto"`; at or below it, the effective presentation
  is `'overlay'`.

**Methods:** `close(reason: LyraResponsivePanelCloseReason = 'api'): void` — requests a close by
emitting `lr-close` with `reason` before changing `open`. A listener can call `preventDefault()` to
keep the panel open; otherwise it sets `open = false` and — only in the overlay presentation —
returns focus to whichever element triggered the open. No-op if already closed. Built-in overlay
triggers call this with `'escape'`/`'backdrop'`; a consumer's own close affordance (a footer button,
a docked panel's own toggle) should call it directly with its own reason string.

**Events:** `lr-close` (`detail: LyraResponsivePanelCloseReason` = `'escape'|'backdrop'|'api'|string`;
cancelable pre-close veto, fired by the overlay presentation's built-in dismiss triggers — Escape,
backdrop click — and by any `close()` call, in either presentation; calling `preventDefault()` keeps
the panel open and leaves active overlay chrome/focus trapping intact. A plain `open = false`
property write does **not** fire it, only going through `close()` counts as a dismissal),
`lr-mode-change`
(`detail: LyraResponsivePanelModeChangeDetail` = `{ mode: LyraResponsivePanelEffectiveMode }`; fired whenever
the _effective_ mode — not the `mode` prop's possibly-`'auto'` literal value — changes between
`'inline'` and `'overlay'`; never fired on the initial render, only for a live change thereafter).

**Slots:** default (the panel body), `header` (optional header content, rendered above the body),
`footer` (optional footer content, e.g. action buttons, rendered below the body).

**CSS parts:** `base`, `backdrop`, `panel`, `header`, `body`, `footer` (`backdrop` is only rendered
in the overlay presentation).

**Themeable custom properties:** `--lr-responsive-panel-overlay-color` (default
`var(--lr-color-overlay)` — the overlay presentation's backdrop scrim color),
`--lr-responsive-panel-sheet-max-block-size` (default `85dvh`, falling back to `85vh` where `dvh`
isn't supported — the maximum height of a `shape="bottom-sheet"` overlay panel, so a long sheet
stops short of the top of the viewport instead of covering it; it has no effect on
`shape="fullscreen"` or on the inline presentation),
`--lr-responsive-panel-side-inline-size` (default `var(--lr-size-20rem)` — the width of a
`shape="start"`/`shape="end"` overlay panel along the inline axis; no effect on any other shape or
on the inline presentation),
`--lr-responsive-panel-overlay-panel-bg` (default `var(--lr-color-surface-overlay)`), and
`--lr-responsive-panel-overlay-panel-shadow` (default `var(--lr-shadow-l)`). The latter two are
inherited inline fallbacks for `[part="panel"]` only while the effective presentation is overlay;
they do not affect inline panels. Plus shared tokens (`--lr-color-border`, `--lr-color-surface`,
`--lr-space-*`, `--lr-radius`, `--lr-shadow`).

**Optional peer deps:** none.

```html
<lr-responsive-panel
  id="settings-panel"
  label="Settings"
  shape="bottom-sheet"
  overlay-breakpoint="48rem"
>
  <span slot="header"><h2>Settings</h2></span>
  <div>Panel body content — a form, a list, anything.</div>
  <span slot="footer"
    ><button onclick="document.getElementById('settings-panel').close()">
      Done
    </button></span
  >
</lr-responsive-panel>
```

Breakpoint detection uses `ResizeObserver` on the component allocation. Resizing a parent layout
across `overlayBreakpoint` while `mode="auto"` updates the effective presentation without
unmounting or re-creating the slotted content.
Inline and overlay presentations share the same shadow DOM, so slotted content and scroll position
survive the transition. Focus already inside the panel is preserved. If focus is outside when an
open inline panel becomes an overlay, focus moves to the first composed focus target (falling back
to the panel), so it cannot remain behind `aria-modal="true"`. An allowed close restores the element
captured when the panel originally opened, even when that original open happened inline. The overlay
presentation participates in the shared modal stack rather than nesting a `<lr-dialog>`.

The granular route exports the pure
`resolveResponsivePanelEffectiveMode(mode: LyraResponsivePanelMode,
belowBreakpoint: boolean): LyraResponsivePanelEffectiveMode` resolver alongside the
`LyraResponsivePanelMode`/`LyraResponsivePanelEffectiveMode`/`LyraResponsivePanelShape`/
`LyraResponsivePanelCloseReason`/`LyraResponsivePanelModeChangeDetail` types. It's the same logic
the element's allocation observer calls: `'inline'`/`'overlay'` pass straight through
unchanged; `'auto'` resolves to `'overlay'` when `belowBreakpoint` is true, `'inline'` otherwise —
exposed standalone so a consumer can compute or unit-test the same resolution without a real browser
window.

**Known gotchas:**

- assigning `open` directly still does not emit `lr-close` and therefore cannot be vetoed; use
  `close()` when the dismissal event/reason or a close guard is required. While overlay chrome is
  active, however, the `true` → `false` state transition restores opener focus regardless of
  whether it came from an allowed `close()` call, a property write, or attribute removal.
- crossing inline → overlay while already open preserves focus that is already inside and moves
  outside focus into the panel; do not expect focus to remain on page content behind the modal.
- `shape="bottom-sheet"`/`shape="start"`/`shape="end"` have no visible effect at all while the
  effective presentation is `'inline'` — they only change the overlay presentation's
  anchoring/height/width.
- `shape="start"`/`shape="end"` are logical, not physical: `'start'` anchors to the inline-start
  edge (left in `dir="ltr"`, right in `dir="rtl"`) and `'end'` to the inline-end edge, so neither
  value alone tells you which physical side a given instance renders on without also knowing its
  resolved direction.
- a reconnect that preserves the same element instance (e.g. a drag-and-drop reparent) resumes its
  shared overlay registration and re-acquires the scroll lock if overlay chrome was still active
  across the move — `disconnectedCallback`/`connectedCallback` fire back-to-back with no update in
  between, so `willUpdate()` alone wouldn't otherwise notice.
- `overlay-breakpoint` follows allocation, not the viewport. Use `mode="overlay"` for a deliberate
  viewport-modal policy independent of the component's containing layout.

---

## `lr-menu-label`

A non-interactive section heading inside `<lr-menu>`'s default slot. Mirrors `sl-menu-label`.

The host takes `role="presentation"` on connect (a `role="menu"` may only contain menu-item roles,
so a heading with a generic role would make the menu's own children invalid) — unless the consumer
already set a `role`, which is left alone. `<lr-menu>` enumerates its interactive items by local tag
name (`lr-menu-item` or `lr-dropdown-item`), not `instanceof`, so an adopted same-origin
foreign-realm item remains enrollable. A label matches neither tag, is never enrolled in the roving
tabindex, and can never become a focus stop; nothing on `<lr-menu>` has to know this element exists.

Keep selectable items directly assigned to the menu's default slot, or forward them through a
slot, with `lr-menu-label` as a sibling visual caption. Arbitrary `role="group"` wrappers do not
provide a supported menu-group API. `aria-labelledby` cannot reference this element's shadow
internals because idrefs do not cross a shadow boundary.

**Properties:** none. **Events:** none. **Slots:** default (the heading text).
**CSS parts:** `base` (the heading row).

**Themeable custom properties:** shared tokens only — `--lr-color-text-quiet`, `--lr-font-size-sm`,
`--lr-font-weight-semibold`, `--lr-space-xs`/`--lr-space-s`.

```html
<lr-menu>
  <lr-menu-label>Recently used</lr-menu-label>
  <lr-menu-item value="open">Open…</lr-menu-item>
</lr-menu>
```

---

## `lr-menu` / `lr-menu-item`

The inline semantic menu mapped from Shoelace's `sl-menu`, plus its action-row element. A root
`<lr-menu>` is always visible and owns the named `role="menu"` list, real roving DOM focus,
wrapping keyboard navigation, type-ahead, and one canonical selection event. It deliberately has no
trigger, positioned popup, root open state, placement API, or overlay lifecycle.

Removing or disabling the remembered active item repairs the roving stop without taking focus from
outside controls or the menu's header/footer. If the changed item held actual focus, focus moves to
a valid survivor or through the existing owner dismissal path when none remain.

For a menu button or other anchored overlay, compose the semantic controller inside
`<lr-dropdown>`:

```html
<lr-dropdown label="Row actions">
  <button slot="trigger" aria-label="Row actions">⋮</button>
  <lr-menu>
    <lr-menu-item value="edit">Edit</lr-menu-item>
    <lr-menu-item value="delete" variant="danger">Delete</lr-menu-item>
  </lr-menu>
</lr-dropdown>
```

The dropdown shell owns trigger relationships, positioning, opening/closing, outside dismissal,
focus return, and lifecycle events. The contained menu remains the sole semantic owner: its
`header`/default/`footer` regions and named `role="menu"` list are preserved, while the outer popup
is neutral. This is also the composition used for direct `<lr-dropdown-item>` children.

### `lr-menu`

**Properties:**

- `label?: string` — accessible name for the `role="menu"` list. A host `aria-label`
  attribute is authoritative, including `aria-label=""`; any supplied `label` follows (including `"Menu"` or
  `""`),
  then a containing dropdown's supplied fallback, then the localized menu label. Omission,
  not comparison with an English sentinel, is what selects localization.
- `dropdownOpen: boolean = false` (attribute: false) — the containing dropdown's controlled open
  state, used to synchronize the menu interaction engine while it is rendered inside a popup.

**Events:**

- `lr-select` — cancelable, with `detail: { item }`. It originates exactly once at the menu that
  owns the activated item, then bubbles unchanged through ancestor menus and a containing dropdown.
  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.

**CSS parts:** `header`, `list`, and `footer`. Root `trigger` and `popup` parts do not exist;
style those on `<lr-dropdown>` when using the overlay composition.

**Themeable custom properties:** the standalone menu surface and a submenu's own surface paint from
the **shared overlay-surface family** (16.0.0) — `--lr-overlay-surface` (default
`var(--lr-color-surface-overlay)`), `--lr-overlay-border` (default `var(--lr-color-border)`),
`--lr-overlay-radius` (default `var(--lr-radius)`) and, on the submenu only,
`--lr-overlay-shadow-anchored` (default `var(--lr-shadow-m)`). None is declared on `:host`, so one
declaration on `:root` (or on any ancestor, to scope it) retints this menu together with every other
floating surface. A menu contained by `<lr-dropdown>` paints no surface of its own, so the family has
no effect there — the dropdown's popup carries it. The header/footer dividing rules and a slotted
`<hr>` deliberately stay on `--lr-color-border`: they separate content rather than draw the
surface's edge. Otherwise shared spacing and motion tokens. Row chrome is controlled through the
menu-item properties listed below.

Width is a pair, applied to the standalone surface and to a submenu's own surface alike:
`--lr-menu-max-inline-size` (default `var(--lr-size-20rem)`) and `--lr-menu-min-inline-size`
(default `var(--lr-size-10rem)`). They move together — the floor wins over the ceiling, so capping
alone cannot take a menu below 10rem. Neither is declared on `:host`, so an ancestor theme wrapper's
value reaches the menu. The ceiling takes a length or a percentage; `100%` and `none` both uncap it
to the container, and any other value outside `<length-percentage>` is treated as `none` rather than
dropping the cap's safety terms. Those terms — the shared `--lr-popover-viewport-clamp` and the
container allocation — are applied outside the name, so no value of the hook can make a menu wider
than its container or the viewport. (That guarantee is enforced by a registered custom property, so
an out-of-syntax value falls back cleanly instead of invalidating the whole declaration; an engine
without `CSS.registerProperty` degrades to "use `100%`, not `none`".) A menu contained by
`<lr-dropdown>` sizes from its dropdown and is unaffected by both names.

**`--lr-positioning-strategy`** (16.0.0) — the private submenu surface reads this same cascading
`absolute`/`fixed` override documented on `<lr-popover>` when it is (re)positioned, falling back to
its own `fixed` default when nothing is set. There is no per-instance `positioning-strategy`
property on `<lr-menu>`; set the custom property on `:root`, a theme, or one clipping ancestor to
change every unset submenu beneath it. A menu contained by `<lr-dropdown>` is positioned by the
dropdown instead and is unaffected.

**Methods:** no menu-specific public overlay methods. Use `<lr-dropdown>`'s `show()`/`hide()` and
`open` state for an overlay. Menu-item submenu methods remain public because they drive a row's
nested disclosure.

**Keyboard and focus:** exactly one navigable row has `tabindex="0"`. ArrowDown/ArrowUp wrap;
Home/End move to the first/last navigable row; Enter/Space activate; printable input performs
locale-aware type-ahead. Rows that are disabled, loading, hidden, `aria-hidden`, inert, or inside an
inert subtree are skipped. Navigation is repaired live when those states or light-DOM membership
change. A root inline menu does not consume Escape or turn Tab into overlay dismissal; a containing
dropdown owns those root-level behaviors.

### `lr-menu-item`

A focusable action row owned by `<lr-menu>`. The host itself carries `role="menuitem"` (or
`menuitemcheckbox`/`menuitemradio`) and roving `tabindex`; `[part="base"]` is only the visual row.

**Properties:**

- `value: string = ''` — identifier available as `event.detail.item.value` on `lr-select`
- `size: '2xs' | 'xs' | 's' | 'm' | 'l' | 'xl' | 'small' | 'medium' | 'large' = 'm'`
- `disabled: boolean = false`
- `variant: 'default' | 'danger' = 'default'`
- `type: 'normal' | 'checkbox' | 'radio' = 'normal'`
- `checked: boolean = false` — meaningful only for `type="checkbox"`/`type="radio"`
- `group?: string` — narrows a `type="radio"` item's exclusive-choice scope to only the other
  radio items sharing this same string. Unset, the scope is every `type="radio"` item the same
  owning `<lr-menu>` owns directly — a nested submenu's radio items belong to that submenu's own
  `<lr-menu>` instead, so they're never in scope regardless of `group`. Meaningless for
  `type="normal"`/`"checkbox"`
- `loading: boolean = false`
- `href?: string` — when set to a safe link URL (`http:`/`https:`/`blob:`/`mailto:`/relative; see
  `safeLinkHref`, or `safeDownloadHref` when `download` is set, which drops `mailto:`),
  `[part="base"]` renders as a real `<a href=…>` instead of a `<span>`, and activation (click, or
  the owning menu's Enter/Space handling, which forwards through `click()` for a link item so the
  anchor's own native default action runs) navigates there in addition to firing the usual
  `select()`/`lr-select` contract. An unsafe/unparseable value falls back to the plain `<span>`,
  matching `lr-button`'s identical fallback
- `target?: string` — native anchor `target`, used only while `href` resolves to a link. Setting it
  (e.g. `'_blank'`) always force-adds `noopener noreferrer` to the rendered anchor's `rel`,
  matching `lr-button`'s identical pattern
- `rel?: string` — independently settable author relationship tokens, no default. Author tokens are
  merged rather than replaced: `opener` is always stripped, and whenever `target` is set the
  non-removable `noopener noreferrer` floor is added, so a same-tab link (no `target`) keeps
  exactly the author's tokens while a link opening a new context can never lose the guard
- `download?: string` — native anchor `download` attribute, used only while `href` resolves to a
  link. Presence narrows the safe-URL allowlist to `safeDownloadHref`'s, which drops `mailto:` — a
  mail handoff names no retrievable bytes, so it cannot be a download target
- `hasSubmenu: boolean` (read-only)
- `submenuOpen: boolean = false` — transient live state; assigning it drives an existing submenu
  without moving focus and disconnect resets it

**Methods:**

- `click(): void` forwards programmatic activation through the visual-row path
- `select(): void` activates through the current owning menu; it is inert while disabled/loading
- `openSubmenu(focus: 'first' | 'last' | 'none' = 'first'): Promise<void>`
- `closeSubmenu(): Promise<void>`
- `getTextLabel(): string` returns the accessibility-visible label used by type-ahead

The computed name is derived from the row's own visible label and does not depend on whether the
menu is currently displayed, so a row inside a closed dropdown — whose popup is `visibility:
hidden` — is named the same as an open one, and `getTextLabel()` drives type-ahead either way.
A row with no label text carries **no** `aria-label` attribute rather than an empty one, so the
browser falls back to the row's own content; an `aria-label` or `aria-labelledby` you set yourself,
including an explicitly empty value, still wins.

A checkbox activation first emits cancelable `lr-menu-item-change` with the proposed
`detail: { value, checked }`. Preventing that event retains the current checked state; the owning
menu's canonical `lr-select` still follows. A submenu parent is a disclosure instead of an action:
activation opens its submenu and emits neither checkbox-change nor selection.

A `type="radio"` item works the same way, with exclusive-choice semantics layered on top:
activating an already-checked radio is a no-op on `checked` — no `lr-menu-item-change`, no state
change, matching native `<input type="radio">` — but still falls through to the owning menu's
usual selection. Activating an unchecked radio fires `lr-menu-item-change` with
`checked: true`; once not prevented, this item becomes `checked` and every other `type="radio"`
item the same owning `<lr-menu>` owns directly whose `group` matches is unchecked directly
(without an `lr-menu-item-change` of its own).

**Events:**

- `lr-menu-item-change` — cancelable checkbox/radio-state proposal; never fired when activating an
  already-checked radio
- `lr-menu-item-state-change` — internal navigation repair signal with
  `detail: { disabled, hidden, inert }`; the owning menu consumes and contains it, so it does not
  escape a menu or a composite wrapper as an apparent public event

Item activation itself is private owner plumbing, not a public child event. Listen for `lr-select`
on the owning menu.

**Slots:** default label, `icon`, `prefix`, `details`, `suffix`, and `submenu`. Display slots are
inert visual content; their accessibility-visible default-slot text names the focusable host. The
submenu slot accepts either one nested `<lr-menu>` or direct mapped items. Long `details` and
`suffix` content shrinks and ellipsizes within the allocated row in both directions rather than
expanding the popup.

**CSS parts:** `base`, `icon`, `prefix`, `label`, `details`, `suffix`, `checkmark`,
`checked-icon`, `spinner`, `spinner__base`, `submenu-icon`, and `submenu`.

**Themeable custom properties:** `--lr-menu-item-gap`, `--lr-menu-item-radius`,
`--lr-menu-item-danger-color`, `--lr-menu-item-danger-hover-bg`,
`--lr-menu-item-danger-active-bg`, `--lr-menu-item-checked-bg` (default `transparent`),
`--lr-menu-item-checked-color` (default `inherit`), `--lr-menu-item-checked-font-weight` (default
`inherit`), and `--submenu-offset`, plus shared size/focus/color/spacing tokens. The checked hooks
apply to a `type="checkbox" checked` or `type="radio" checked` row's `[part="base"]`, matching the
checked/selected-state hooks `<lr-option>`, `<lr-select>`, `<lr-combobox>`, and `<lr-tree-item>`
already expose; unset, a checked row paints identically to an unchecked one.

Four more row-chrome hooks land in 16.0.0, each an inline fallback so unset rendering is
byte-identical: `--lr-menu-item-hover-bg` (default `var(--lr-color-brand-quiet)`) is the enabled
row's fill under the pointer, and the pressed state mixes from that same value, so a retuned hover
fill keeps its pressed step instead of snapping back to the brand default; `--lr-menu-item-active-bg`
(default `color-mix(in oklab, var(--lr-menu-item-hover-bg, var(--lr-color-brand-quiet)),
var(--lr-color-mix-partner) var(--lr-color-mix-active))`) overrides that pressed fill directly,
matching `--lr-option-active-bg`'s equivalent hook — unset, the pressed row keeps mixing from
`--lr-menu-item-hover-bg` exactly as before this hook existed; `--lr-menu-item-icon-color` (default
`inherit`) recolours `[part="icon"]` without touching the label beside it, so it still follows the
row while the row is disabled or `variant="danger"` unless you say otherwise; and
`--lr-menu-item-min-height` (default `max(var(--lr-form-control-height), var(--lr-size-24px))`)
sets the row's minimum block size for a denser or roomier menu, replacing a `::part(base)` rule per
item. A value below the 24px floor is your call, exactly as it is when overriding the shared ladder
itself.

### Nested submenus

Both supported authoring shapes use the `submenu` slot:

```html
<lr-menu label="Share actions">
  <lr-menu-item value="share">
    Share
    <lr-menu slot="submenu" label="Share options">
      <lr-menu-item value="email">Email</lr-menu-item>
      <lr-menu-item value="link">Copy link</lr-menu-item>
    </lr-menu>
  </lr-menu-item>
</lr-menu>
```

```html
<lr-dropdown-item>
  Share
  <lr-dropdown-item slot="submenu" value="email">Email</lr-dropdown-item>
  <lr-dropdown-item slot="submenu" value="link">Copy link</lr-dropdown-item>
</lr-dropdown-item>
```

The submenu presentation is private to the parent row, not a second root-menu API. A submenu parent
has `aria-haspopup="menu"`, explicit `aria-expanded="true|false"`, the transient
`submenu-open` state, and a logical-direction chevron. Its submenu is named from the parent's
accessible label unless the submenu supplies its own `aria-label` or non-default `label`.

The into-branch and back-out arrow keys swap under RTL. Enter/Space and the into key open and focus
the first child; the back-out key and Escape close only the innermost branch and return focus to its
parent row. Pointer hover uses an intent delay, outside pointer dismissal closes the branch, and at
most one branch per level is open. Selection bubbles as the same single `lr-select`; a non-vetoed
selection closes the full nested chain.

### `lr-dropdown-item`

The Web Awesome-compatible name for the same item implementation. It shares all menu-item
properties, slots, parts, methods, checkbox/radio/state events, roving focus, and canonical parent
`lr-select` behavior. Its host also exposes native, non-bubbling, composed `focus` and `blur`
events.

**Attributes:** `href`, `target`, `rel`, and `download` — the same link-rendering properties
documented above for `<lr-menu-item>`, settable directly in markup
(`<lr-dropdown-item href="/settings" target="_blank">`). The `rel` guard is identical: author
tokens merge rather than get replaced, `opener` is always stripped, and setting `target` force-adds
the non-removable `noopener noreferrer` floor, so a same-tab link keeps exactly the author's tokens
while a link opening a new context can never lose the guard.

**Events:** native, non-bubbling, composed, non-cancelable `focus` and `blur` (`FocusEvent`) when
the focusable host gains or loses focus, plus the shared menu-item events above.

**Themeable custom properties:** every `<lr-menu-item>` hook above, including 16.0.0's
`--lr-menu-item-hover-bg`, `--lr-menu-item-active-bg`, `--lr-menu-item-icon-color` and
`--lr-menu-item-min-height`.
`--lr-overlay-surface`, `--lr-overlay-border` and `--lr-overlay-radius` are listed on this tag
because it shares a stylesheet directory with `<lr-menu>`, whose surface reads them; a dropdown item
is a row **inside** that surface and paints no surface of its own, so setting them here is a no-op —
set them on the menu or on any ancestor instead. The row's own corner stays `--lr-menu-item-radius`.

`submenuOpen` reflects to canonical `submenu-open`. HTML normalizes Web Awesome's documented
mixed-case spelling to `submenuopen`, so that lowercase token is a permanent compatibility alias.
Adding either spelling opens the submenu and synchronizes the other; removing either closes it and
removes both. Internal close paths — `closeSubmenu()`, Escape, outside dismissal, selection,
replacement, and disconnect — clear both spellings, preventing a persistent alias from reopening a
dismissed branch. An authored initial open request remains pending until submenu content connects.

### 9.0 migration

Root overlay behavior moved from `<lr-menu>` to `<lr-dropdown>`. Migrate mechanically:

- Move a former menu `trigger` slot and menu `open`, `placement`, `anchor`, or
  `close-on-escape-anywhere` policy to an enclosing `<lr-dropdown>`.
- Replace `menu.show()`/`menu.hide()` and menu `lr-show`/`lr-hide` listeners with the equivalent
  dropdown APIs/events.
- Replace `lr-menu-select` (`detail.value`) and `lr-menu-item-select` listeners with one
  `lr-select` listener on the menu or dropdown and read `event.detail.item`.
- Replace menu `::part(trigger)`/`::part(popup)` rules with dropdown part styling. Menu
  `header`/`list`/`footer` parts remain on the semantic controller.

Standalone mapped `<sl-menu>` markup needs no wrapper: the mechanical `sl-` → `lr-` tag rename
continues to produce an inline menu.

---

## `lr-dock-panel`

A single panel docked to one edge of whatever contains it, resizable by dragging its inner edge.
First-party invention (no `wa-*`/`sl-*` counterpart). Unlike `lr-multi-split` (which owns and lays out N
sibling panels, and requires restructuring a layout so every panel becomes its direct child), this is
one self-contained element you drop next to your existing content — typically as an absolutely-
positioned child of a `position: relative` parent, or as a flex item alongside a main-content sibling.
It deliberately imposes no `position`/`inset` of its own: it only manages its own size along the
resize axis (`inline-size` for `start`/`end`, `block-size` for `top`/`bottom`) and fills 100% of the
cross axis, leaving where it sits in the page entirely up to the consumer's own layout. `lr-multi-split`
stays the right primitive for the multi-sibling-panel case; this is the primitive for the single-edge-
docked case.

**Properties:**

- `edge: 'start' | 'end' | 'top' | 'bottom' = 'end'` (reflected) — which edge of the panel's own
  container it's docked to. `start`/`end` are logical-inline (mirror left/right depending on writing
  direction); `top`/`bottom` are block-direction and unaffected by RTL.
- `extent: string = '280px'` — the current docked size along the resize axis, as a CSS length.
- `minExtent: string = '160px'` (attribute `min-extent`) — minimum resize bound, as a CSS length.
- `maxExtent: string = ''` (attribute `max-extent`) — maximum resize bound. Empty means "no explicit
  cap": the live extent of the containing element is used instead (falling back to the viewport if
  there's no parent, e.g. not yet connected). An explicit maximum is still capped to that live
  containing extent, and an effective minimum above the maximum is reduced to the maximum, so the
  separator always exposes `min <= now <= max`.
- `collapsible: boolean = false` (reflected)
- `collapsed: boolean = false` (reflected)
- `resizable: boolean = true` (reflected) — when `false`, no drag handle renders at all and the panel
  is a fixed size. Its string-aware converter accepts `resizable="false"` as false despite the
  true default. A Lit property binding (`.resizable=${false}`) also disables it; a false
  boolean-attribute binding (`?resizable=${false}`) only removes the attribute and cannot override
  a true-defaulting property.

**Renamed in 8.0.0: `size`/`min-size`/`max-size` are now `extent`/`min-extent`/`max-extent`**, and
the then-current resize detail key moved with them (`{ size }` → `{ extent }`). Everywhere else in the library
`size` names a tier on the shared six-step ladder; here it was an arbitrary CSS length, which is the
collision the rename resolves. It is a clean rename with no alias, and it fails quietly in both
directions: `size="320px"` is now an unknown attribute the browser ignores, so the panel silently
renders at the `280px` default, and `event.detail.size` reads `undefined`.

**Exported types:** `LyraDockPanelEdge = 'start' | 'end' | 'top' | 'bottom'`, readonly
`LyraDockPanelResizeDetail = { extent: string }`, readonly
`LyraDockPanelCollapseChangeDetail = { collapsed: boolean }`, and `LyraDockPanelEventMap`.
The former dock-specific `parseLengthPx()` export is removed; dock length resolution is now a
private adapter over the library's canonical CSS-length resolver, with container/viewport units
resolved in the host's owner realm.

**Events:**

- `lr-resize-request` (cancelable; `detail: { extent }` is the proposed `px` CSS length string),
  fired before a discrete keyboard step commits and before a pointer drag's final settle commits.
  Call `preventDefault()` to reject it: a keyboard step simply does not apply, and a drag's final
  settle snaps the panel back to the size it had before that drag gesture began. Not fired for a
  continuous pointer drag's own intermediate ticks — checking a cancelable event on every
  `pointermove` would make a live drag visibly stutter — only its final settle on release.
- `lr-resize-input` — frozen `detail: { extent }` (a `px` CSS length string), fired for each genuine
  pointer or keyboard value transition. Fully clamped/no-op attempts emit nothing.
- `lr-resize-change` — a fresh frozen detail snapshot, fired exactly once on genuine `pointerup`
  after at least one value transition and the drag's `lr-resize-request` was not prevented, and
  after each genuine keyboard step whose own `lr-resize-request` was not prevented. `pointercancel`,
  lost capture, disconnect/adoption, live policy/geometry mutation, no-op attempts, and a prevented
  `lr-resize-request` all emit nothing.
- `lr-collapse-request` (cancelable; `detail: { collapsed }` is the state proposed by the built-in
  collapse toggle. Call `preventDefault()` to leave `collapsed` unchanged. Not fired when a
  consumer assigns `collapsed` directly), `lr-collapse-change` (non-cancelable; `detail: {
collapsed }` is the accepted built-in-toggle state. Not fired when a consumer assigns `collapsed`
  directly). Both details are fresh readonly/frozen snapshots.

The Lyra-original v9 event migration is mechanical: listen for `lr-resize-input` for live layout
feedback and `lr-resize-change` for persistence/telemetry instead of the removed `lr-resize` name.
Type imports likewise move from `DockPanel*` to `LyraDockPanel*`.

**Slots:** default — the panel's own content.

**CSS parts:** `base` (the panel root), `content` (wraps the default slot; hidden while `collapsed`),
`handle` (the draggable resize edge; only rendered when `resizable` and not `collapsed`),
`collapse-toggle` (only rendered when `collapsible`)

**Themeable custom properties:** `--lr-dock-panel-collapsed-size` (default
`var(--lr-icon-button-size)`) — the persistent "rail" width/height the panel holds at while
`collapsed`, rather than collapsing to zero (a zero-size collapsed panel would have nowhere to host
the re-expand toggle); component-specific since collapse never zeroes the box. The `collapse-toggle`
button and the resize `handle` used to share the bare `--lr-color-brand`/`--lr-color-brand-quiet`
tokens for their hover/pressed feedback even though they're unrelated visual purposes (button
affordance vs. drag affordance); each now has its own scoped override, all still defaulting to the
exact same colors as before: `--lr-dock-panel-collapse-toggle-hover-bg` (default
`var(--lr-color-brand-quiet)`) and `--lr-dock-panel-collapse-toggle-hover-color` (default
`var(--lr-color-brand)`) theme the toggle's hover state and are reused verbatim (color) or through
`color-mix()` (background) for its pressed state; `--lr-dock-panel-handle-hover-color` (default
`var(--lr-color-brand)`) themes the handle's hover/keyboard-focus state, and
`--lr-dock-panel-handle-active-color` (default a `color-mix()` of the hover color) themes it while
being dragged. Plus shared tokens `--lr-color-surface`, `--lr-color-border`, `--lr-color-brand`,
`--lr-color-brand-quiet`, `--lr-color-text`, `--lr-radius`, `--lr-space-xs`,
`--lr-focus-ring-width/-color/-offset`, `--lr-transition-fast`, `--lr-icon-button-size`.

**Optional peer deps:** none.

```html
<div style="position: relative; block-size: 100vh;">
  <lr-dock-panel edge="end" extent="320px" min-extent="200px" max-extent="480px" collapsible>
    <div>Sidebar content — a chat thread list, an inspector, anything.</div>
  </lr-dock-panel>
</div>
<script type="module">
  const panel = document.querySelector("lr-dock-panel");
  panel.addEventListener("lr-resize-input", (e) => updateLayoutPreview(e.detail.extent));
  panel.addEventListener("lr-resize-change", (e) => persistExtent(e.detail.extent));
  panel.addEventListener("lr-collapse-change", (e) => console.log(e.detail.collapsed));
</script>
```

Pointer-drag-resize admits only a primary pointer using its primary button, then mirrors
`lr-multi-split`'s pointer-capture technique (`pointerdown` captures the pointer on the handle;
`pointermove` computes a new size; `pointerup`/`pointercancel`/`lostpointercapture` all release it,
since a drag can end without a clean `pointerup`) but reasons in raw pixels throughout rather than
percent. A genuine interaction — pointer movement or a keyboard step
(<kbd>ArrowLeft</kbd>/<kbd>ArrowRight</kbd> for the inline axis, <kbd>ArrowUp</kbd>/<kbd>ArrowDown</kbd>
for the block axis, 16px per step) — commits `extent` as a rounded `px` string regardless of what
unit `extent`/`min-extent`/`max-extent` were originally expressed in. Passive container/bounds
reconciliation emits neither resize event and preserves an in-range authored relative unit.

**Known gotchas:**

- `collapsed` doesn't zero the panel's box — it shrinks to the persistent rail size
  (`--lr-dock-panel-collapsed-size`). `extent` itself is left untouched while collapsed, so
  re-expanding restores what it was unless the current bounds require a valid clamp.
- Parent or flex allocation shrink, direct out-of-range property writes, and live min/max changes
  reconcile atomically. A later container grow does not silently restore an extent that was clamped
  during shrink.
- `handle` only renders while `resizable && !collapsed`; `collapse-toggle` only renders while
  `collapsible` — a panel with both `false` renders neither control, just fixed-size slotted content.
  `resizable` and `collapsed` interact: dragging is disabled whenever `collapsed` is `true`, even if
  `resizable` is also `true`.
- The collapse-toggle's chevron rotates to point toward the panel's pinned edge when expanded (the
  direction clicking it will shrink toward) and away from it when collapsed — this is folded through
  both `edge` and, for `start`/`end`, current RTL-ness, so the same markup visually flips correctly
  under `dir="rtl"` with no extra author work.

---

## `lr-card`

A generic, styled bordered content container — the "small bordered surface with padding" idiom common
to hero highlights, clickable grid tiles, and management-list items. A direct `<lr-*>` counterpart
to `<wa-card>`'s contract, staying slot-compatible with `lr-result-card` where they overlap.

**Properties:**

- `appearance: 'accent' | 'filled' | 'outlined' | 'filled-outlined' | 'plain' = 'outlined'`
  (reflected) — `'outlined'` (the default) is a plain bordered surface; `'filled'` swaps the border
  for a quiet brand-tinted background; `'filled-outlined'` keeps the border and adds that same tinted
  background; `'accent'` drops the border for a single colored accent stripe on the leading edge;
  `'plain'` has no border or background at all.
- `orientation: LyraOrientation = 'vertical'` (reflected; the shared
  `'horizontal' | 'vertical'` layout axis) — vertical renders media,
  header/actions, body, and footer/footer-actions as sections. Horizontal arranges media/image,
  body, and `actions` in logical order and stacks them when the card's own container drops below
  30rem.
- `withHeader`, `withHeaderActions`, `withMedia`, `withFooter`, and `withFooterActions` (boolean,
  reflected as `with-header`, `with-header-actions`, `with-media`, `with-footer`, and
  `with-footer-actions`) — SSR presence hints. They expose an otherwise-empty section wrapper before
  slot assignment can be measured; populated slots are still detected automatically after hydration.
- `actionable: boolean = false` (reflected) — opt-in no-link whole-card action behavior: the hover/focus-visible
  treatment (border-color shift, `cursor: pointer`) plus, when `href` is **not** also set, real
  activation semantics. Those come from a real native `<button part="activation-button">` stretched
  across the card, not from making `[part='base']` itself focusable: it is the keyboard tab stop,
  it answers Enter and Space natively, and activating it emits `lr-card-activate`. With `href` set,
  a stretched sibling native `<a>` owns navigation, no activation button renders, and
  `lr-card-activate` never fires. Consumer slots stay outside that link, so their controls remain
  independent. A valid `href` is inherently actionable and receives the same interaction paint
  without this flag. `false` (the default) leaves a no-link card static: no button, listeners, or
  events.
- `disabled: boolean = false` (reflected) — turns the card's OWN activation off. The native
  `activation-button` renders `disabled`; a linked card's stretched `<a>` loses its `href`, so it
  genuinely cannot navigate rather than merely claiming to be disabled while still clickable, 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-card-activate` stops firing from every path,
  `click()` included, the control leaves the tab order, and the card paints at
  `--lr-opacity-disabled` with a `not-allowed` cursor. Scoped to the card's own action: a passive
  card (no `actionable`, no `href`) has nothing to turn off, so `disabled` leaves it untouched,
  and slotted controls stay yours to disable. `<lr-card>` is deliberately not form-associated (it
  is a layout container, not a form control), so an ancestor `<fieldset disabled>` does not
  cascade into it — disable each card explicitly.
- `accessibleLabel: string | null = null` (attribute `aria-label`) — the accessible name of the
  native whole-card owner: the activation button without `href`, or the stretched link with it.
  An explicitly empty value is retained; only an absent value falls back to card or linked content,
  so set it explicitly for a card whose content is an image or a chart.
- `href?: string` — when set, a real stretched `<a href=...>` renders behind the consumer slots for
  a whole-card link (e.g. a wide CTA tile). A click on noninteractive card content follows that
  link, while slotted controls keep their own native or Lyra behavior. Unset (the default) renders
  a plain `<div>`.
- `target?: string` — native anchor target, applied only while `href` resolves to a link. Setting it
  to `'_blank'` (or any other target) forces `noopener noreferrer` on the rendered anchor.
- `rel?: string` — author relationship tokens such as `nofollow`, `sponsored`, `me`, or `license`.
  `opener` is always stripped, other tokens are preserved, and any set `target` force-adds the
  non-negotiable `noopener noreferrer` floor. With no target, safe author tokens render unchanged.
- `aria-pressed` and `aria-current` (attributes only) — forwarded reactively onto the native
  control the card actually renders, the same mechanism `<lr-button>` and `<lr-icon-button>` use.
  `aria-pressed` accepts `'true' | 'false' | 'mixed'` and reaches the `activation-button` only —
  `link` has no pressed state, so a linked card never receives it — the same **16.0.0** carve-out
  `<lr-button>` and `<lr-icon-button>` took. The global `aria-current`
  accepts `'page' | 'step' | 'location' | 'date' | 'time' | 'true' | 'false'` and reaches both the
  activation button and the stretched link. Anything outside those sets is dropped rather than
  passed through, so a typo never reaches the accessibility tree. This is what lets a single-select
  list of card-shaped tiles announce which one is the active selection.

**Events:** `lr-card-activate` (no detail) — the whole card was activated, by a click anywhere on it
or by Enter/Space on `[part='activation-button']`. Only fired while `actionable` is set **without**
`href`. Never fired for an interaction that originated in a slotted control, so a card can keep its
own action buttons (see the gotchas below).

**Methods:** `click(): void` activates the native whole-card owner: the linked anchor when `href` is
safe, or the activation button while `actionable` is set without a link. Passive cards remain
inert.

Changing `href` or `actionable` while the whole-card owner has focus transfers focus across the
link, activation button, and a programmatically focusable passive base. It never overrides a newer
external focus destination.

**Slots:** default (the card body), `header` (vertical header content), `media` and `image` (aliases
for media above the header vertically or at logical start horizontally), `footer` (vertical footer
content), `header-actions` and `footer-actions` (controls aligned with those vertical sections), and
`actions` (horizontal-card actions; retained as the legacy header-actions spelling vertically).

**CSS parts:** `base` (the outer container — a `<div>`, or a stretched `<a>` behind consumer slots
when `href` is set),
`activation-button` (the native whole-card action, rendered only while `actionable` without `href`;
it is absolutely positioned across the card, `pointer-events: none` so it never intercepts a click
meant for slotted content, and it owns the card's `:focus-visible` ring), `media` and `image`
(aliases on the wrapper around both media slots, hidden entirely when empty), `header` (wrapper around the `header` slot and
`actions`, hidden entirely when both are empty), `actions` (wrapper around the `actions` slot,
hidden entirely when empty), `body` (wrapper around the default slot), `footer` (wrapper around the
`footer` and `footer-actions` slots, hidden entirely when both are empty).

**Themeable custom properties:** `--spacing` (default `var(--lr-space-m)`) controls the padding and
gap around card sections. Shoelace-compatible `--padding` is its fallback; `--border-color`,
`--border-radius`, and `--border-width` control the outer and section borders. Otherwise shared
tokens — `--lr-color-border`/`-surface`/`-brand`/
`-brand-quiet`, `--lr-radius`, `--lr-space-s`/`-m`, `--lr-transition-fast`,
`--lr-focus-ring-*`.
Appearance and interaction paint can be rethemed independently through `--lr-card-outlined-bg`
(the DEFAULT `outlined` appearance's background, and `accent`'s, which adds a stripe without
restating a surface — defaults to `var(--lr-color-surface)`, mirroring `<lr-details>`'s
`--lr-details-outlined-bg`), `--lr-card-filled-bg`,
`--lr-card-filled-outlined-bg`, `--lr-card-accent-border-color`,
`--lr-card-interactive-hover-border-color`, `--lr-card-interactive-active-border-color`, and
`--lr-card-interactive-active-overlay`. They inherit from ancestors and fall back to the exact
former brand and active-mix values when unset.
`--lr-card-shadow` is **undeclared by default**, so `box-shadow` falls back to `none` —
byte-identical to before this property existed — mirroring `--lr-button-shadow`'s pattern; set it
for a raised card without a `::part(base)` rule. `--lr-card-interactive-hover-shadow` styles an
`actionable`/linked card's shadow while hovered, falling back to `--lr-card-shadow` itself so a
card given only a resting shadow keeps that exact shadow on hover.

**Optional peer deps:** none.

```html
<lr-card appearance="outlined" href="/reports/42" with-media with-header>
  <img slot="image" src="/thumb.png" alt="" />
  <span slot="header">Q3 Report</span>
  <span slot="header-actions"><lr-chip tone="success">Ready</lr-chip></span>
  Revenue up 12% quarter-over-quarter.
  <span slot="footer">Updated 2 days ago</span>
  <button slot="footer-actions" type="button">Download</button>
</lr-card>
```

**Known gotchas:**

- every `appearance` renders on the _same_ `[part="base"]` element — there's no separate element per
  variant, so a `::part(base)` override applies uniformly regardless of `appearance`.
- **a card clips, it does not scroll — and it never picks a scroll owner for you.** `[part='base']`
  stretches to the host's allocated block-size and clips its overflow, which is what keeps a
  full-bleed `media`/`image` child inside the rounded border. In an auto-sized row the card simply
  grows and nothing is clipped; give it a _definite_ allocation (a fixed grid row, an explicit
  `block-size`) and body content taller than that allocation is clipped silently, with no
  scrollbar. Neither upstream card exposes an overflow, block-size, or scroll hook and neither does
  this one: the public `body` part already carries the whole decision, and a `::part()` rule from
  your tree wins over the shadow stylesheet regardless of specificity. A fixed-height tile that
  must hold more content says so itself:

  ```css
  .tile-grid {
    display: grid;
    grid-template-rows: 12rem;
  }
  .tile-grid lr-card::part(body) {
    overflow: auto;
    overscroll-behavior: contain;
  }
  ```

  `overflow` other than `visible` also zeroes the body's automatic minimum size, so that one
  declaration is enough — the body shrinks into the tile and scrolls, and `max-block-size` /
  `scrollbar-gutter` stay available on the same rule. The linked (`href`) card behaves identically.
- slot-presence (`header`/`media`/`image`/`footer`/`actions`/`header-actions`/`footer-actions`) is
  tracked in JS, not via CSS `:empty` (a
  `[part]` wrapper always contains a literal `<slot>` child, so `:empty` never matches) — the same
  pattern `lr-empty`/`lr-widget` use.
- The `with-*` hints force section presence; do not set one for a section that should stay absent.
  They are safe to leave in server-rendered markup once hydrated, because actual slot detection is
  combined with—not substituted for—the hints.
- Horizontal orientation intentionally omits the vertical header/footer presentation and uses the
  `actions` slot beside the body. Its 30rem breakpoint is a container query on the card allocation,
  not a viewport media query, so the same card can be horizontal in a wide region and stacked in a
  narrow sidebar on one page.
- **`[part='base']` itself deliberately carries no `role="button"` and is not focusable.** A card is
  a _container_ — it routinely holds slotted buttons and links — and `role="button"` around
  focusable descendants is the `nested-interactive` accessibility violation this library's own a11y
  gate enforces. (`lr-chip`'s `toggleable` mode _can_ carry `role="button"` because it forbids
  focusable children outright.) The whole-card action is therefore a _sibling_ of the slotted
  content — `[part='activation-button']` — so the actionable roles are never nested inside one
  another, and the card still announces as a real button rather than as an unnamed focusable region.
- because the base element carries no `role="button"` to disambiguate, "did the user aim at the card
  or at a control inside it?" is answered at event time: the composed path from the original target
  up to `[part='base']` is walked, and `lr-card-activate` is suppressed if anything along the way is
  itself a control (a link, `button`, `input`, `select`, `textarea`, `label`, `summary`,
  `contenteditable`, anything carrying a `tabindex` other than `-1`, or an ARIA widget role such as
  `button`/`link`/`checkbox`/`switch`/`radio`/`menuitem`/`option`/`tab`/`textbox`/`slider`/
  `spinbutton`). Using the _composed_
  path is what makes this work through a slotted component's own shadow root — a click on
  `<lr-button>` retargets to the host, but its composed path still contains the internal native
  `<button>`.
- a click whose composed path starts on `[part='activation-button']` skips that walk entirely and
  always activates — it _is_ the whole-card action, so there is nothing to disambiguate.
- with `href`, `[part='base']` is a stretched real anchor sibling behind the visible content rather
  than an ancestor of it. Clicks from noninteractive slotted content are delegated to that anchor;
  composed-path arbitration leaves native and Lyra buttons, links, and fields independent. The
  linked example's `Download` button therefore does not navigate the card.

---

## `lr-command-palette`

Searchable application command menu. Renders nothing at all while closed. Uses the same shared
overlay infrastructure as `lr-dialog` (focus-trapping Tab, Escape dismissal, backdrop-click
dismissal, ref-counted document scroll lock).

Valid string keywords still participate in search alongside the command's label, description, and
group. Unsafe keyword entries are skipped without invoking accessors, and selection returns the
original command object.

**Properties:**

- `open: boolean = false` (reflected) — after the initial silent render, property and attribute
  writes use the same synchronous cancelable transaction as `openPalette()`/`close()`; a veto
  restores reflection and prevents query/active-row opening side effects
- `commands: readonly LyraCommand[] = []` (attribute: false) — `{ commandId, label, description?, group?,
shortcut?, keywords?: readonly string[], disabled?, icon?, onSelect? }`. The sequence is copied,
  bounded, and frozen while each command object's identity is retained for `onSelect`; create and
  reassign a new command array after sequence or row changes. `commandId` is a stable business identity and
  must be nonempty and unique; invalid rows are omitted and the first duplicate wins. Replacing or
  reordering the array preserves the active command by `commandId`. `icon` is an optional leading glyph (a `TemplateResult`,
  an emoji string, etc. — not restricted to a square icon) rendered in the `icon` part before the
  label; a command with no `icon` renders no `icon` part at all. A runtime `keywords` value that is
  not an array is ignored, as are non-string members, without dropping otherwise-valid commands.
  Filtering is case-insensitive
  substring matching over `label` + `description` + `group` + `keywords` joined together (not
  fuzzy/subsequence), memoized per `commands` array identity — reassign the array, never mutate it
  in place. Consecutive commands sharing a `group` render one `[part='group']` heading, so pre-sort
  by group yourself.
- `hotkey: string = 'mod+k'` — exact global activation chord parsed as `+`-separated parts; `mod`
  resolves to Cmd on Mac and Ctrl elsewhere. Detection prefers Client Hints, then falls back to
  the legacy platform string and reduced user-agent string rather than trusting
  `navigator.platform` alone. Repeats, composition keys, and extra modifiers do not match. If
  several connected palettes use the same chord, the last connected palette owns it;
  activation is idempotently open rather than a toggle.
- `accessibleLabel?: string` (attribute `aria-label`) — overrides the localized dialog name.
  Omitting it reads back `undefined` and uses the localized `commandPaletteLabel` default; an
  explicitly empty value is used as-is

**Methods:** `openPalette()` (after an accepted open, clears the query and resets the active row;
no-op if already open),
`close()`, `registerCommand(command)` — appends to `commands` and returns an unregister function.

**Keyboard:** ArrowUp/ArrowDown move the active option, skipping `disabled` rows and clamping (not
cycling) at the ends; the active row is scrolled into view. Enter selects. Hovering a non-disabled
row also makes it active.

**Events:** `lr-open`, `lr-close` (both `detail: null`, cancelable — fired before the
mutation, `preventDefault()` keeps the palette in its current open state), `lr-select`
(`detail: { command }`, fired before the command's own `onSelect` runs and before the palette
closes), and no-detail `focus`/`blur` events re-dispatched from the host whenever the search input
gains or loses focus. The `focus`/`blur` bridge is new in 10.0.0: native `focus`/`blur` neither
bubble nor cross the shadow boundary, so a host-level `el.addEventListener('focus', …)` previously
never fired at all.

**Slots:** none.

**CSS parts:** `backdrop`, `dialog` (the `role="dialog" aria-modal="true"` panel), `search` (the
input row), `input` (the `type="search"` field), `clear-button` (clears the search field,
replacing the native search-cancel glyph the component resets; rendered only while it has a
value), `list` (the `role="listbox"`), `group` (a group
heading), `command-group` (a labeled ARIA group of commands), `command` (a `role="option"` button),
`icon` (a command's leading icon glyph; only rendered when the command has one), `label`,
`description`, `shortcut`, `list-spacer` (the virtual result extent), `empty`.

**Themeable custom properties:** `--lr-command-palette-z-index` (default
`var(--lr-overlay-stack-index, var(--lr-layer-modal))`), `--lr-command-palette-offset-block-start`
(default `12vh` — how far down the viewport the dialog sits), `--lr-command-palette-max-inline-size`
(default `var(--lr-size-48rem)`), `--lr-command-palette-max-block-size` (default `70vh`),
`--lr-command-palette-list-max-block-size` (default `50vh` — the scrolling result list), and
`--lr-command-palette-active-bg` (default `var(--lr-color-brand-quiet)` — the background of the
active, keyboard-highlighted command row). That last one is an inline `var()` fallback at the point
of use rather than a `:host` declaration, so it can be set on the element _or on any ancestor_:
`::part(command)[data-active='true']` is invalid CSS (Shadow Parts forbids an attribute selector
after `::part()`), so highlighting the active row previously required hijacking the library-wide
`--lr-color-brand-quiet` token and repainting everything else that read it. Unset, it falls back to
that token, so rendering is unchanged. `--lr-command-palette-search-padding` (default
`var(--lr-space-m)`) and `--lr-command-palette-search-gap` (default `var(--lr-space-s)`) size the
query row; `--lr-command-palette-search-min-height` (default `auto`) and
`--lr-command-palette-search-font-size` (default `inherit`) size the field itself. Point the height
at `--lr-form-control-height-s` (or any tier of that ladder) to match the palette's query field to a
themed search field elsewhere in the application. Unset, all four leave the row exactly as it
shipped.

**Additional API surface:**

- `part="command-group"` — A labeled ARIA group containing visible command options.
- `part="list-spacer"` — Virtual result extent inside the scrolling list.
- `--lr-command-palette-row-height` — Virtual command-row height. Default: `var(--lr-size-3rem)`.
  Its live resolved value drives the painted height, row transforms, keyboard-scroll coordinates,
  and result extent together.
- `--lr-command-palette-group-height` — Virtual group-heading height. Default:
  `var(--lr-size-2rem)`. Its live resolved value drives heading/row transforms and the result extent
  together.

## `lr-details`, `lr-accordion`, and `lr-accordion-item`

`lr-details` is a native-semantics disclosure panel; it mirrors `wa-details` / `sl-details`.
`lr-accordion` and `lr-accordion-item` mirror `wa-accordion` / `wa-accordion-item`: the group owns
mode, presentation, lifecycle events, and roving focus, while each item renders a heading button
and animated panel. The two components intentionally keep distinct vocabularies: accordion items
use `expanded`, `label`, and `expand()`/`collapse()`/`toggle()`, while `open`, `summary`, and
`show()`/`hide()` belong only to Details.

`lr-toggle` reports the direction and source of an accepted Details transition. Accordion
coordinates only its direct `lr-accordion-item` children; Details retains independent state and
optional grouping through a shared non-empty `name`.

**Breaking in 9.0.0:** an accordion coordinates direct `lr-accordion-item` children only. Direct
`lr-details` panels used to be accepted as well; they are not any more. A `lr-details` slotted into
an accordion today is ordinary content owning its own disclosure lifecycle — the group applies
neither its presentation, nor its single-panel invariant, nor its roving keyboard model, nor its
`lr-expand`/`lr-collapse` lifecycle to it, and `expandAll()`/`collapseAll()` skip it. Migrate both
the tag and its member vocabulary: `<lr-details summary="..." open>` becomes
`<lr-accordion-item label="..." expanded>`, and `show()`/`hide()` become
`expand()`/`collapse()`. `lr-details` on its own, outside an accordion, is unchanged.

**Accordion properties:**

- `mode: 'single' | 'single-collapsible' | 'multiple' = 'multiple'` (reflected). `multiple` allows
  any number of expanded items. `single` permits at most one and activating the expanded item is a
  no-op. `single-collapsible` permits at most one but allows zero.
- `iconPlacement: 'start' | 'end' = 'end'` (attribute `icon-placement`, reflected),
  `headingLevel: string = '3'` (attribute `heading-level`, reflected; `1`–`6` select that heading,
  `none` omits it, and every other value renders the documented h3 fallback), and
  `appearance: 'filled' | 'outlined' | 'filled-outlined' | 'plain' = 'outlined'` (reflected). The
  group applies all three to each direct `lr-accordion-item` whenever children or properties
  change.

**Accordion-item properties:** `label: string = ''`, `expanded: boolean = false` (reflected),
`disabled: boolean = false` (reflected), plus the same `iconPlacement`, `headingLevel`, and
`appearance` properties listed above. **Removed in 9.0.0:** inherited Details members `open`,
`summary`, `name`, `size`, `show()`, and `hide()`; use the canonical accordion-item members or use
`lr-details` when the Details contract is required. Accordion expansion policy likewise has one
authority: migrate `multiple` to `mode="multiple"`, and `multiple="false"` to the intended
`mode="single"` or `mode="single-collapsible"` behavior.

**Details properties:** `open: boolean = false` (reflected), `disabled: boolean = false`
(reflected — blocks activation and sets `aria-disabled="true"`; its native summary uses
`tabindex="-1"` while disabled so sequential navigation matches a disabled accordion-item
trigger), `summary: string = ''`, `name: string = ''` (reflected — disclosures with the same
non-empty name in one document or shadow root are mutually exclusive),
`appearance: 'filled' | 'outlined' | 'filled-outlined' | 'plain' = 'outlined'` (reflected),
`iconPlacement: 'start' | 'end' = 'end'` (attribute `icon-placement`, reflected and logical), and
`size`.

A host `aria-label`, when present, names the actual Details summary or accordion-item trigger;
it wins over summary/label content even when explicitly empty. When the host attribute is absent,
Details and accordion-item property/localized fallbacks keep their native name-from-content
behavior. An active accordion-item `label` slot contributes its normalized
accessibility-visible text as the trigger's explicit name; its rendered subtree is inert and hidden
from assistive technology so the trigger remains the sole action.

`size: '2xs' | 'xs' | 's' | 'm' | 'l' | 'xl' | 'small' | 'medium' | 'large' = 'm'` (reflected, new
in 8.0.0) is the library's shared size ladder, so a disclosure scales with the controls around it
instead of being the one fixed-density element in a compact panel. Both spellings of every tier are
accepted — `s`/`small`, `m`/`medium`, `l`/`large` — so markup migrated from either upstream needs no
attribute rewrite. `m` is the default and reproduces the disclosure this component had before `size`
existed. The tier drives two custom properties (below) rather than any `::part()` rule, so a tier
the ladder doesn't cover is a two-line override rather than a fork.

**Methods:**

- Accordion: `expandAll()` expands every direct enabled item only in `multiple` mode;
  `collapseAll()` collapses every direct expanded item. Nested accordion items are never included.
- Accordion item: `expand(): Promise<void>`, `collapse(): Promise<void>`, and
  `toggle(): Promise<void>` initiate the corresponding transition and settle after its rendered
  motion. Disabled items are unchanged. `focus()` and the host's `click()` target the trigger.
- Details: `show(): Promise<void>` expands and `hide(): Promise<void>` collapses. Each promise
  settles after its matching `lr-after-show` or `lr-after-hide`; a vetoed, disabled, or
  already-satisfied request resolves without changing state. Assigning `open` runs the same
  Details lifecycle. `show()` is a no-op while disabled; `hide()` can still close a disabled
  Details panel.

**Events:**

- `lr-expand`, `lr-collapse`, `lr-toggle-request`, `lr-after-expand`, `lr-after-collapse` —
  accordion group lifecycle.
- `lr-show`, `lr-hide`, `lr-toggle`, `lr-after-show`, `lr-after-hide` — Details lifecycle only.

On the accordion, `lr-expand` and `lr-collapse` fire before a direct item changes, are cancelable,
and carry `detail: { item }`. **New in 10.0.0:** a cancelable `lr-toggle-request`
(`detail: { collapsed, item }`) fires alongside the matching directional event for every transition,
including sibling auto-collapses in `single`/`single-collapsible` mode and `collapseAll()`. It carries
the direction in the detail rather than the event name, matching `<lr-code-block>`/`<lr-chat-message>`'s
`lr-toggle-request` convention, plus an `item` reference the single-panel siblings do not need (an
accordion's toggling entity is one of several children, so the event target alone cannot identify it).
`preventDefault()` on **either** event vetoes the transition — the two are a symmetric veto pair, not
a primary and a notification. Note `<lr-thinking-panel>`'s own `lr-toggle-request` spells its detail
`{ expanded }` rather than `{ collapsed }`; the two conventions are not fully unified. **Changed in 9.0.0:** `item` is now always a `LyraAccordionItem` —
it could previously also be a `LyraDetails`. The exported `LyraAccordionPanel` union that spelled
that has been removed; use `LyraAccordionItem`. An accepted transition finishes with the
non-cancelable
`lr-after-expand` or `lr-after-collapse`, carrying the same item. In `single` mode, activating the
already-expanded item is a no-op and emits no collapse lifecycle. Nested accordions own their own
triggers; an outer group does not close siblings or emit its own lifecycle for an inner item. Item
methods and group methods use this lifecycle too. When opening an item in a single mode, the previously expanded
sibling's cancelable collapse is consulted before the new panel changes state; vetoing it keeps the
old item open and cancels the new expansion, so the group never silently violates its one-item
invariant.

> **A nested `lr-accordion`'s events are not scoped to it — filter by target.** Every accordion
> event goes through the shared `emit()` helper with `bubbles: true, composed: true`, so an inner
> `<lr-accordion>` slotted inside an outer item sends its own `lr-expand`, `lr-collapse`,
> `lr-toggle-request`, `lr-after-expand` and `lr-after-collapse` straight through the outer group.
> A listener bound directly on the outer `<lr-accordion>` therefore also receives the inner
> group's — and their `detail.item` is an item of the inner group, so an outer handler that looks
> that item up among its own children finds nothing, or acts on a panel it does not own.
> Coordination itself is already scoped: an outer group never applies its single-panel invariant,
> roving keyboard model, or lifecycle to an inner group's items. It is only the listener that
> needs the guard, the same one `<lr-details>` and `<lr-dialog>` document for their own events:
>
> ```html
> <lr-accordion id="outer">
>   <lr-accordion-item label="Outer">
>     <lr-accordion>
>       <lr-accordion-item label="Inner">Inner content.</lr-accordion-item>
>     </lr-accordion>
>   </lr-accordion-item>
> </lr-accordion>
> <script type="module">
>   const outer = document.querySelector('#outer');
>   outer.addEventListener('lr-expand', (event) => {
>     if (event.target !== event.currentTarget) return; // a nested group expanded, not this one
>     // ...
>   });
> </script>
> ```

The Details events `lr-show` and `lr-hide` have no detail payload and are cancelable; preventing
either leaves the panel in its previous state. Accepted changes emit `lr-toggle` with
`detail: { open, source }`, then the non-cancelable `lr-after-show` or `lr-after-hide` once
rendering and motion settle. `source` is `user` for a summary click or keyboard activation,
`programmatic` for `show()`, `hide()`, or assigning `open`, and `peer` when another Details with
the same non-empty `name` closes this one. The full orders are `lr-show` → `lr-toggle` →
`lr-after-show` and `lr-hide` → `lr-toggle` → `lr-after-hide`. Initially open markup emits
nothing, and an interrupted transition drops its stale after-event. The `animating` CSS custom
state is present only between an accepted state change and that settled boundary, and is cleared
when the element disconnects.

> **A nested `lr-details`' events are not scoped to it — filter by target.** Every Details event
> goes through the shared `emit()` helper with `bubbles: true, composed: true` hardcoded, with no
> exception for this component. A `<lr-details>` nested inside another `<lr-details>` (as ordinary
> slotted content, e.g. inside `header-actions` or the default panel) has its own
> `lr-show`/`lr-hide`/`lr-toggle`/`lr-after-show`/`lr-after-hide` bubble straight through the outer
> panel, so a listener bound directly on the outer `<lr-details>` also receives the inner one's
> events — an inner disclosure opening or closing looks identical to the outer one doing the same,
> the same failure mode `lr-dialog`'s `lr-close` carries and documents in its own section. Guard on
> the target:
>
> ```html
> <lr-details id="outer" summary="Outer">
>   Some outer content.
>   <lr-details id="inner" summary="Inner">Inner content.</lr-details>
> </lr-details>
> <script type="module">
>   const outer = document.querySelector('#outer');
>   outer.addEventListener('lr-toggle', (event) => {
>     if (event.target !== outer) return; // the inner details toggled, not this one
>     // ...
>   });
> </script>
> ```
>
> This is deliberate, not a bug to fix: non-bubbling Details events would be a breaking change, and
> `event.target`/`event.currentTarget` already give every listener exactly what it needs to tell the
> two apart.

**Keyboard:** each direct enabled accordion item contributes one heading button. Exactly one is in
the tab order; ArrowDown/ArrowUp move cyclically, horizontal arrows provide the same next/previous
movement and swap under RTL, and Home/End jump to the first/last enabled item. Disabled items are
skipped. Enter and Space use the native button activation contract. Focus and key handling stay
inside the nearest nested accordion.

**Slots:** accordion has a default slot for direct items. Accordion item has default panel content,
`label`, and `icon`; `label` slot → `label` property → localized `"Details"` is the precedence
order. The label slot accepts rich visible markup, but its flattened subtree is inert and hidden
from assistive technology: do not place independent links, buttons, inputs, form state, or focus
targets there. The accordion-item `icon` slot follows the same flattened-tree inert and aria-hidden
visual contract, while the trigger button remains the sole action. Details has `summary`,
`header-actions`, `expand-icon`, `collapse-icon`, plus default content. `header-actions` renders
extra controls (e.g. a trailing "add" button) as a sibling of the private native `<details>` in the
complete header row, so they stay rendered, visible, and hit-testable while the panel is collapsed
or disabled. Activating one never toggles the panel: a click whose
composed path crosses `[part~="header-actions"]` is exempted from disclosure activation. Its wrapper
is hidden and reclaims layout space whenever the slot is empty.

**CSS parts:** accordion exposes `base`. Accordion item exposes `base` and `accordion-item` on the
same outer wrapper, plus `heading`, `button`, `label`, `icon`, `panel`, and `content`. Details
exposes `base` and `details` on the same outer container, plus `header`, `summary`, `icon`,
`header-actions`, and `content`. The native `<details>` is private; `content` is inside its
findable `hidden="until-found"` closed-state gate.
The Details icon wrapper also carries Shoelace's `summary-icon` alias, so either part name styles
the same node. `header-actions` is the wrapper around the `header-actions` slot.

Open panel content now fills and scrolls inside a bounded host: place `<lr-details>` (or an
ancestor of it) in a container with a resolved block size and, once open, `[part="content"]`
fills the remaining space below the summary row and scrolls its own overflow internally instead
of the panel growing past the host. This has no effect on an ordinary unsized disclosure — the
chain resolves to `auto` and the panel stays exactly as content-sized as before. It has no effect
on the closed state either: the private closed-state findability gate (`hidden="until-found"`)
is untouched, and the open/close lifecycle (`show()`/`hide()`, `lr-show`/`lr-toggle`/
`lr-after-show`/`lr-hide`/`lr-after-hide`) is unaffected.

For rich independent actions, reserve a useful basis on `header-actions` so the complete action
group wraps onto another row before its checkbox label becomes too narrow. The header already
wraps; its summary belongs to a private native-details flex item, so setting `flex` on
`::part(summary)` does not control that item's allocation. This recipe uses public parts and
ordinary light-DOM layout:

```html
<style>
  lr-details.responsive-actions::part(header-actions) {
    flex: 1 1 12rem;
    min-inline-size: min(100%, 12rem);
    padding: var(--lr-space-xs);
    box-sizing: border-box;
  }
  .details-action-group {
    display: flex;
    flex-wrap: wrap;
    align-items: center;
    gap: var(--lr-space-s);
    min-inline-size: 0;
  }
  .details-action-group lr-checkbox { flex: 1 1 auto; min-inline-size: 0; }
</style>
<lr-details class="responsive-actions" summary="Settings">
  <span slot="header-actions" class="details-action-group">
    <lr-checkbox size="s">Show distribution details</lr-checkbox>
    <lr-badge>Live</lr-badge>
  </span>
  Distribution settings.
</lr-details>
```

Import the granular details, checkbox and badge registration entries. Adjust the `12rem` basis
for the actual labels. Logical sizing supports RTL and narrower allocations; the checkbox remains
independently focusable and operable when the summary is disabled.

**Themeable custom properties:** accordion item exposes `--lr-accordion-item-spacing` (default
`var(--lr-form-control-padding-inline)`), `--lr-accordion-item-show-duration` and
`--lr-accordion-item-hide-duration` (both default `var(--lr-duration-base)`), and
`--lr-accordion-item-easing` (default `var(--lr-easing-standard)`). The mapped unprefixed names
`--spacing`, `--show-duration`, `--hide-duration`, and `--easing` remain accepted aliases and win
when set. Panel and icon transitions stop under `prefers-reduced-motion: reduce`.

Accordion appearance paint is independently inheritable: `--lr-accordion-outlined-bg` (default
`var(--lr-color-surface)`) and `--lr-accordion-outlined-border-color` (default
`var(--lr-color-border)`); `--lr-accordion-filled-bg` (default
`var(--lr-color-surface-raised)`) and `--lr-accordion-filled-border-color` (default `transparent`);
and `--lr-accordion-filled-outlined-bg` (default `var(--lr-color-surface-raised)`) plus
`--lr-accordion-filled-outlined-border-color` (default `var(--lr-color-border)`). Direct item
surfaces have matching `--lr-accordion-item-outlined-bg`, `--lr-accordion-item-filled-bg`, and
`--lr-accordion-item-filled-outlined-bg` hooks with the same surface fallbacks. Item trigger paint
uses `--lr-accordion-item-button-hover-bg` (default `var(--lr-color-brand-quiet)`) and
`--lr-accordion-item-button-active-bg` (default the existing active `color-mix(...)`). These hooks
are read as inline fallbacks rather than declared on the host, so an ancestor theme can set them.

Details exposes `--lr-details-font-size` (default
`var(--lr-form-control-font-size)`) — the text size of both the summary and the panel.
`--lr-details-spacing` (default `var(--lr-form-control-padding-inline)`) — the block rhythm: the
summary's block padding and the panel's trailing padding, kept equal so a stack of disclosures reads
evenly. Each `size` tier changes both private defaults from the shared ladder; a public value on an
ancestor or the element remains authoritative. Note that the spacing knob
deliberately reads the ladder's _inline_-padding value: a stacked panel wants generous block rhythm,
whereas the ladder's own block padding exists to fit text inside a fixed control height and would
collapse the summary row. The summary's and the panel content's padding can also be tuned
independently of each other and of `--lr-details-spacing`: `--lr-details-summary-padding-block` and
`--lr-details-summary-padding-inline` control the summary alone, and
`--lr-details-content-padding-block-end` and `--lr-details-content-padding-inline` control the
panel content alone. All four default to the same `--lr-details-spacing` resolution described
above, mirroring how `--lr-details-gap`/`--lr-details-radius` (below) are already independent of
the spacing knob. `--spacing` aliases the Details rhythm and remains the highest-precedence
override, ahead of these four as well. `--show-duration` and
`--hide-duration` (both default `var(--lr-duration-base)`) tune its icon transitions. Motion stops
under `prefers-reduced-motion`, so the `lr-after-*` events still settle promptly in that branch.
`--lr-details-gap` (default `var(--lr-space-s)`) independently controls the summary content/icon
gap, and `--lr-details-radius` (default `var(--lr-radius)`) controls the surface corners. Both use
inline fallbacks, inherit from ancestors, and remain independent of the `size` density ladder.
Details surface paint uses `--lr-details-outlined-bg` / `--lr-details-outlined-border-color`,
`--lr-details-filled-bg` / `--lr-details-filled-border-color`, and
`--lr-details-filled-outlined-bg` / `--lr-details-filled-outlined-border-color`; their defaults are
respectively the existing surface/border, brand-quiet/transparent, and brand-quiet/border values.
Summary interaction paint uses `--lr-details-summary-hover-bg` (default
`var(--lr-color-brand-quiet)`) and `--lr-details-summary-active-bg` (default the existing active
`color-mix(...)`). All eight are inheritable inline-fallback hooks, so they isolate one disclosure
theme without requiring shared-token changes or shadow-part selectors.

```html
<lr-details summary="Advanced options">Panel content</lr-details>
<script type="module">
  const panel = document.querySelector("lr-details");
  let ready = false;
  // Cancelable: veto the open until some precondition is met.
  panel.addEventListener("lr-show", (e) => {
    if (!ready) e.preventDefault();
  });
  panel.addEventListener("lr-after-show", () =>
    panel.querySelector("input")?.focus()
  );
  ready = true;
  await panel.show();
</script>
```

```html
<lr-accordion
  mode="single-collapsible"
  icon-placement="start"
  heading-level="2"
>
  <lr-accordion-item label="Account" expanded
    >Profile settings</lr-accordion-item
  >
  <lr-accordion-item>
    <strong slot="label">Notifications</strong>
    Notification settings
  </lr-accordion-item>
</lr-accordion>
<script type="module">
  const accordion = document.querySelector("lr-accordion");
  accordion.addEventListener("lr-expand", (event) => {
    if (event.detail.item.disabled) event.preventDefault();
  });
</script>
```

## `lr-breadcrumb` and `lr-breadcrumb-item`

Responsive navigation trail primitives.

**`lr-breadcrumb` properties:** `label?: string` names the trail; omitting it reads back `undefined`
and falls back to the localized `"Breadcrumb"`, while an explicitly empty string stays empty.
`accessibleLabel?: string` (attribute **`aria-label`**) overrides both, with the same
omitted-versus-explicitly-empty distinction. The
shadow-root `<nav>` landmark never inherits a host attribute on its own, so the value is copied onto
it. **Fixed in 9.0.0:** the property used to be declared but never read — only the literal host
`aria-label` attribute reached the landmark, so `el.accessibleLabel = 'Docs trail'` type-checked and
did nothing. Both spellings now work, with an authored host attribute still winning (including an
explicitly empty `aria-label=""`, which stays empty rather than falling back).

**`lr-breadcrumb-item` properties:** `href: string = ''` (URL-sanitized; an unsafe scheme renders the
non-link form; assigning `undefined` clears it and reads back as the canonical `''`),
`target?: LyraBreadcrumbItemTarget`, and `current: boolean = false` (reflected — renders a
`<span aria-current="page">` instead of an `<a>`, even when `href` is set). A target derives
the mandatory `noopener noreferrer` floor. `rel: string = 'noreferrer noopener'` is independently
settable: author tokens are preserved, `opener` is stripped, and any target force-adds the floor. Each item
sets `role="listitem"` on itself. A non-current item without `href` renders a native button. A host
`aria-label` is forwarded to either non-current native owner by attribute presence, including an
explicitly empty value; when absent, the default slot supplies its name.

**`lr-breadcrumb-item` methods:** `click(): void` activates the internal native link or button. It
is a no-op for the current-page label.

Changing `href` or `current` while that native owner has focus transfers focus across the link,
button, and programmatically focusable current-page label. External focus is preserved.

**Slots:** breadcrumb's default slot takes `lr-breadcrumb-item` children and its `separator` slot is
copied to every item without an item-level override. Both breadcrumb and item `separator` slots are
decorative-only: their rendered content is inert and hidden from assistive technology, so it must not
provide interactive behavior, a focus target, or form state. Generated shared copies omit identifiers,
ID-reference relationships, form associations, and submission attributes. Source text, attributes,
and compatible subtrees update live; identity-compatible clone nodes are patched in place instead of
being disconnected and recreated. The first owned breadcrumb item is determined independently of
separator sources or other auxiliary siblings, so it never renders a leading separator. An item's default slot is
its label; `start`/`prefix` and `end`/`suffix` are the two upstream adornment vocabularies, and
`separator` overrides the `/` fallback.

**CSS parts:** breadcrumb `base` and `breadcrumb` are aliases on the same `<nav>`; `list` is the
`role="list"` flex row wrapping the slotted items; item `base` (the `<a>`, `<button>`, or current
`<span>`), `label`,
`separator`, and the alias pairs `start`/`prefix` and `end`/`suffix`.
Interactive link/button bases retain a 24px minimum target in both axes even with empty content;
the inert current-page label remains content-sized.

**Themeable custom properties:** `--lr-breadcrumb-current-color` (default
`var(--lr-color-text-quiet)`) — text color of the current-page item (`current`/`aria-current="page"`).
It is an inline `var()` fallback at the point of use rather than a `:host` declaration, so it can be
set on the item, on `<lr-breadcrumb>`, or on any ancestor above the trail:
`::part(base)[aria-current='page']` is invalid CSS (Shadow Parts forbids an attribute selector after
`::part()`), so tinting the current item previously meant overriding the library-wide
`--lr-color-text-quiet` token and repainting everything else that read it. Unset, it falls back to
that token.
`--lr-breadcrumb-item-active-bg` independently themes a non-current link/button's pressed fill;
unset, it retains the former transparent active mix.

**Additional API surface:**

- `part="separator"` — Decorative separator shown before non-first items.

## `lr-dashboard-grid`

Responsive, keyboard-accessible controlled widget grid. It positions layout entries and emits
move, resize, collision, and layout-change requests; the host owns persistence and applies updates.

Pointer move and resize gestures measure the rendered column/row pitch, including the gutter, so
movement by four painted tracks proposes four logical columns in either LTR or RTL. Row-height and
gap overrides also govern vertical pointer snapping. The component continues to emit controlled
layout proposals; the caller accepts them by assigning `layout`.

**Properties:** `layout: readonly LyraDashboardCell[] = []` (attribute: false, never mutated by the component),
`columns: number = 12`, `rowHeight: number = 80` (px, also the row snap pitch), `gap: number = 8`
(px, both axes), `collision: 'reject' | 'push' | 'overlap' = 'reject'`, `cellsDraggable: boolean = false`
(attribute `cells-draggable` — pointer drag plus Ctrl/Cmd+Arrow), `cellsResizable: boolean = false`
(attribute `cells-resizable` — the resize handle plus Ctrl/Cmd+Shift+Arrow), `locked: boolean =
false` (reflected — disables every gesture grid-wide), `accessibleLabel: string | null = null`
(attribute `aria-label`, falls back to a localized grid name).

**Events:** `lr-cell-move` (`detail: { cellId, position, previous }`), `lr-cell-resize`
(`detail: { cellId, size, previous }`), `lr-collision`
(`detail: { cellId, collidedCellIds, policy, accepted }`),
`lr-layout-change` (`detail: { layout }`, the full proposed layout after an accepted change).
The collection-bearing collision and layout-change details are detached and recursively frozen;
listeners apply changes by creating and assigning a new layout.
Rejected-collision feedback is appended immediately to the shared light-DOM polite announcement
sink. Accepted move/resize success is appended only after a later controlled `layout` assignment
contains the requested target geometry; ignoring a request never announces a change that did not
happen. All feedback remains silent while the grid or a composed ancestor is excluded from the
accessibility tree.
**Slots:** `cell-{cellId}`. **CSS parts:** `base`, `cell`, `empty`, `resize-handle`, `live-region` (an
`aria-hidden` shadow mirror of the latest spoken message).

`layout` is normalized into an immutable snapshot before rendering. Reads are bounded to the first
1,000 positions; foreign-realm arrays are accepted; malformed records, hostile accessors, and later
duplicate cell IDs are skipped without discarding valid neighbors. Geometry and min/max constraints
are finite and consistent, and neither the returned array nor its cells alias caller-owned objects.
Each admitted `cell.widget` is also copied immediately through the canonical bounded widget-document
factory: its node records, child arrays, and prop records are frozen without cloning opaque prop or
payload leaves. A hostile or malformed widget is omitted while its otherwise-valid cell remains.
Direct light-DOM children with `cell-id` remain the authored source of truth across insertion,
removal, cell-ID retargeting, reconnect, and document adoption. The first authored child for a cell
ID wins; when it disappears, the default cell is restored without mistaking a forged marker
attribute for a library-owned node.

The default content assigns a version-two document created from `cell.widget` to
`<lr-widget-renderer>.document`; it never uses the legacy `tree` input. Pointer gestures admit only
the primary button/pointer and ignore controls, links, labels, editable content, and interactive
roles in the composed path. Keyboard resizing uses physical directions in both LTR and RTL:
Right/Down grow and Left/Up shrink, while pointer resizing retains the logical inline-end handle.

In the narrow stacked layout, a cell that currently owns a resize handle keeps at least the shared
interactive-action block-size (`--lr-icon-button-size`). The handle is absolutely positioned and
cannot contribute intrinsic size itself; the state-aware floor prevents it from overlapping the
preceding cell or gap while readonly and locked short cells retain content-derived sizing.
Host, grid, cell, and direct slotted-content boundaries also permit intrinsic inline shrinkage and
inherit `overflow-wrap: anywhere`, so an unbroken consumer-authored text run cannot widen a 320px
stack. This does not seize overflow from child-owned widgets: custom content can still declare
`overflow: auto` and `white-space: nowrap` to retain a contained internal scrollport.

**Themeable custom properties:** `--lr-dashboard-grid-columns`, `--lr-dashboard-grid-row-height`,
and `--lr-dashboard-grid-gap` back the CSS Grid's `grid-template-columns`/`grid-auto-rows`/`gap`.
They are real cascade-authoritative public hooks: the `columns`/`rowHeight`/`gap` properties supply
private computed fallbacks rather than overwriting these public variables inline.
`--lr-dashboard-grid-cell-hover-outline-color`
(default `var(--lr-color-border-strong)`) retints the mouse-hover outline on `[part='cell']` — a
preview of its own `:focus-visible` ring, shown because every cell is a real focusable,
draggable/resizable target; set it to `transparent` to opt out of the hover treatment entirely.

**Additional API surface:**

- `LyraDashboardCell`, `LyraDashboardCollisionPolicy`, and
  `LyraDashboardPlacementResult` — readonly public authoring/result types.
- `resolveLyraDashboardPlacement(layout, candidateCellId, requested, columns, policy)` — the only public
  runtime layout utility. It returns an immutable normalized result; collision indexing,
  clamping, sorting, and push-cascade helpers are intentionally implementation-private.
- `LyraDashboardCellMoveDetail`, `LyraDashboardCellResizeDetail`,
  `LyraDashboardCollisionDetail`, and `LyraDashboardLayoutChangeDetail` — readonly event-detail
  interfaces used by `LyraDashboardGridEventMap`.
- `--lr-dashboard-grid-collision-outline-color` — Outline color of a cell whose current drag/resize preview collides with another cell. Default: `var(--lr-color-danger)`.
- `--lr-dashboard-grid-interaction-shadow` — Box shadow applied during a cell drag or resize. Default: `var(--lr-shadow-m)`.

## `lr-drilldown-panel`

Controlled navigation shell from a chart or table datum to related evidence, documents, entities,
or agent runs. It renders a breadcrumb path and delegates the effective category to existing
source-card, document-preview, and entity-card primitives.

**Properties:**

- `path: readonly LyraDrilldownNode[] = []` (attribute: false) — host-owned breadcrumb trail. Each
  node uses `nodeId` and may carry readonly `evidence`, `documents`, and `entities` collections.
  Evidence records use `evidenceId`, documents use `documentId`, and entities use `entityId`.
- `activeCategory: LyraDrilldownCategory | '' = ''` (attribute `active-category`, reflected) —
  controlled category authority. Empty or unavailable values resolve to the first populated
  category without mutating the property. A tab interaction emits a change request; the host
  accepts it by assigning `event.detail.category`.
- `types: readonly LyraNodeTypeStyle[] = []` (attribute: false) — shared node-type badge styles
  forwarded to composed entity cards. The shape is structurally identical to the graph/entity
  node-style vocabulary.
- `accessibleLabel: string | null = null` (attribute `aria-label`) — names the nested tab group or
  sole category region. `null` leaves a tab strip unnamed and falls back to the sole category
  label; an explicit empty string is preserved.
- `communityLabel: string = ''` (attribute `community-label`) and
  `showFocusButton: boolean = true` (attribute `show-focus-button`) — forwarded to active entity
  cards.

Structured inputs cross a realm-neutral schema boundary. The component clones and freezes all
accepted records, nested arrays, and entity property maps; ignores accessors, malformed records,
whitespace-unstable identities, and later duplicate IDs; and bounds the retained model to 256 path
nodes, 1,000 records per category, 256 type styles, and 128 entity properties. A localized range
under `limit` truthfully reports source input omitted by a ceiling.

Only the effective category's child components are mounted. Each category is paged eight records
at a time, with a localized `start–end of total` summary and Previous/Next controls. Consequently an
active document category owns at most eight simultaneous `lr-document-preview` lifecycles (and at
most eight of that viewer's individually byte-capped text resources); hidden categories own no
preview fetches. Paging, path replacement, category changes, and disconnect remove obsolete
previews, which abort their owner-realm requests. The embedded tab group uses manual activation so
arrowing across tabs does not request expensive categories until Enter/Space commits.

**Events:**

- `lr-drilldown-navigate` — frozen `{ nodeId, index }`; a request only, never a `path` mutation.
- `lr-drilldown-category-change` — frozen `{ nodeId, category, previousCategory }`; a controlled
  request only.
- `lr-drilldown-evidence-expand`, `lr-drilldown-evidence-open`,
  `lr-drilldown-document-download`, `lr-drilldown-document-render-error`,
  `lr-drilldown-document-highlight-activate`, and `lr-drilldown-entity-activate` — correlated
  wrapper events carrying the current `nodeId` and the relevant `evidenceId`, `documentId`, or
  `entityId`. The document-highlight wrapper carries `{ nodeId, documentId, highlightId }`,
  preserving the preview event's domain-specific highlight identity. Raw events from owned source
  cards, previews, entity cards, and tabs are contained;
  events from consumer-owned `runs` slot content continue bubbling normally.

**Slots:** `runs`. **CSS parts:** `base`, `breadcrumb`, `breadcrumb-item`, `breadcrumb-button`,
`tabs`, `category`, `content`, `evidence-item`, `document-item`, `entity-item`, `pagination`,
`pagination-summary`, `previous-button`, `next-button`, `limit`, `empty`.

**9.0 migration:** the generic `Drilldown*` authoring types are now `LyraDrilldown*`. Replace node
`id` with `nodeId`, evidence `id` with `evidenceId`, document `id` with `documentId`, entity `id`
with `entityId`, and read `lr-drilldown-navigate.detail.nodeId`. Hidden category DOM is no longer
eagerly present; query the source data or accept `lr-drilldown-category-change` before accessing
that category's composed children.

## `lr-filter-bar`

Dashboard filter row that composes Lyra inputs and removable chips, with reset and loading states.

Choice option entries must expose string `value` and `label` data fields; malformed entries are
omitted independently, while supplied empty strings remain valid. A custom definition requires its
adapter and a callable `render`; a rejected definition does not reserve its filter ID. Valid
siblings remain available. Exceptions thrown by an admitted trusted renderer still propagate. A
chip-only definition requires neither options nor an adapter — a stable filter ID and a label are
the whole schema, since a malformed `formatValue`/`isEmpty` still has a correct fallback and so is
guarded where it is used rather than rejected outright.

**Lean registration entry.** `components/layout/filter-bar/filter-bar.js` (the default entry)
eagerly imports every composed control this bar could possibly render — `<lr-select>`,
`<lr-combobox>`, `<lr-dropdown>` + `<lr-dropdown-item>` (the `'checkbox-menu'` branch),
`<lr-date-input>`, `<lr-input>`, `<lr-chip>`/`<lr-chip-group>` (the active-filter row), and
`<lr-button>`/`<lr-spinner>` (the reset action and the loading status) — because `filters` is a
runtime value it cannot inspect ahead of time. A bar that only ever declares `'select'`/`'text'`
filters still pays for `<lr-combobox>` and `<lr-date-input>` through that entry: a measured ~69.5 kB
gzip more than importing only what it uses. A consumer who knows their own filter `type`s ahead of
time can import `components/layout/filter-bar/filter-bar-register.js` instead, which registers
`<lr-filter-bar>` and nothing else, then import each composed control's own registration entry for
the filter `type`s actually declared:

| Filter `type` | Registration entry |
| --- | --- |
| `'select'` | `components/forms/select/select.js` |
| `'combobox'` | `components/forms/combobox/combobox.js` |
| `'checkbox-menu'` | `components/overlays/overlay/dropdown.js` **and** `components/layout/menu/dropdown-item.js` |
| `'date'` / `'date-range'` | `components/forms/date-picker/date-input.js` |
| `'text'` | `components/forms/input/input.js` |
| `'chip'` | none — renders no control |

Two more are unconditional regardless of which filter `type`s are declared: `<lr-button>` renders
the reset action on every bar, and `<lr-chip>`/`<lr-chip-group>` render the active-filter row
whenever any filter has a value (further gated by `activeFiltersDisplay`, but never provably absent
for a generic bar) — `components/forms/button/button.js` and `components/overlays/chip/chip.js` +
`components/overlays/chip/chip-group.js`. `<lr-spinner>`
(`components/overlays/spinner/spinner.js`) is the one built-in dependency the lean entry omits even
though every bar could use it: `loading` is a plain boolean any consumer can leave unset entirely,
unlike a filter `type`, which `filters` always names outright — import it too if the bar ever sets
`loading`. A filter definition whose `type` has no matching import above renders no usable control
until something else registers it, the same trade `icon-button-register.js` documents for
`<lr-icon-button>`'s own `icon`/`src` attribute.

**Properties:**

- `filters: readonly LyraFilterBarFilterDefinition[] = []` (attribute: false) — filter schema in
  render order. Every definition carries a nonempty, whitespace-stable, unique `filterId` and a
  `label` that is a non-blank string; invalid definitions (including a missing, non-string, or
  blank `label`) and later duplicate filter IDs are ignored deterministically. The first 10,000
  definitions and nested collection entries are detached and deeply frozen at assignment; the
  optional Lit `icon` payload retains its rendering identity. Create and reassign a new array after
  changes. Writing `null` or `undefined` clears the schema; reads remain the canonical non-null
  empty array.
- `value: LyraFilterBarValue = {}` (attribute: false) — sparse current values keyed by `filterId`.
  Cleared fields are omitted. Reads, writes, event details, and string-array fields are immutable
  snapshots rather than references to caller-owned data, capped at 10,000 record keys and 10,000
  entries per string-array field. Create and reassign a new record after changes. Writing `null` or
  `undefined` clears the value; reads remain the canonical non-null empty record. Built-in controls
  use strings/string arrays; if an untyped boundary supplies a boolean, `false` is canonical empty
  and omitted while `true` remains set. Custom controls instead use their adapter's `isEmpty` or
  `clearValue` contract, so either boolean can be meaningful in a custom domain.
- `label: string = ''` — accessible-name fallback for the internal `role="group"`. A host
  `aria-label` wins by attribute presence, including an explicitly empty value.
- `disabled: boolean = false` (reflected) — disables every filter control and reset action.
- `loading: boolean = false` (reflected) — shows the status spinner and disables reset while leaving
  filters editable.
- `hasActiveFilters: boolean` (read-only) — whether any configured filter currently has a value,
  including one sitting at its own declared `defaultValue`. Drives the reset button's own disabled
  state in every `activeFiltersDisplay` mode except `'changed'`; the getter itself is unaffected by
  `activeFiltersDisplay`.
- `hasChangedFilters: boolean` (read-only) — whether any filter's value differs from its own
  declared `defaultValue`, using the same equality `activeFiltersDisplay: 'changed'` filters its
  chip row on: a `readonly string[]` default compares positionally, everything else compares with
  `Object.is`. This is the counterpart to `hasActiveFilters`, not a synonym — a bar whose filters
  were all declared with non-empty defaults and never touched reads `hasActiveFilters === true` and
  `hasChangedFilters === false`, because a bar whose defaults narrow the view on load has not been
  narrowed by the user. A filter with no declared `defaultValue` counts as changed the moment it
  holds any value at all (there is nothing for it to still equal), and clearing a filter that *does*
  declare one counts as changed too, since `reset()` would restore it — which is the one case where
  this getter and the `'changed'` chip row differ, the row's entries being non-empty by
  construction. Always live, never cached.
- `invalidFilterIds: readonly string[]` (read-only) — immutable ids of required filters whose
  values are unset.
- `activeFiltersDisplay: 'all' | 'changed' | 'hidden' = 'all'` (reflected, attribute
  `active-filters-display`) — which currently-active filters render as removable chips in the row
  below the fields. `'all'` (the default, and this component's only behavior before this property
  existed) shows one chip per non-empty filter, including one sitting at its own `defaultValue`.
  `'changed'` shows a chip only for a filter whose value differs from its own `defaultValue` — so a
  bar whose defaults narrow the view on load does not claim the user narrowed it — and a filter with
  no declared `defaultValue` counts as changed as soon as it has any value at all. `'hidden'` never
  renders the row. Array values compare against `defaultValue` positionally (same length, same entry
  at each index), matching this component's only other array-equality precedent (a custom adapter's
  own `clearValue` comparison); a `'date-range'` value is a single composed string, so it compares
  like any other string. Removing a chip always clears that filter, unaffected by this property.
  `'changed'` additionally gates the reset button on `hasChangedFilters` instead of
  `hasActiveFilters`, so an untouched defaults-only bar — which renders no chip in this mode — no
  longer offers an enabled reset that would change nothing. Enablement under `'all'` and `'hidden'`
  is unchanged, `disabled`/`loading` still win in every mode, and `reset()` itself is untouched.

The composed reset action uses `lr-button`'s default `m` size tier, matching the default rendered
height of adjacent select, combobox, input, and date fields instead of introducing a shorter action
inside the same controls row.
The host, root, controls, active-filter row, composed chip group, and chips all zero nested flex
auto minima and cap themselves to the allocated inline size. A single unbroken localized active
value therefore stays inside a 320px LTR or RTL bar, with the chip's own label ellipsis retaining
overflow ownership rather than widening the page.

Each edit exposes one filter-bar `lr-input` carrying a detached, deeply frozen snapshot of the
complete value object, plus the `filterId` that changed and (new in 12.0.0) `appliedPreset` — see
"Date-range quick ranges" below. A built-in or
custom control's own `lr-input`/`lr-change` aliases stay inside the wrapper so their incompatible
detail shapes cannot escape as duplicate bar events; native-style `input`/`change` events from the
composed controls continue bubbling normally.

**Methods:** `checkValidity(): boolean` returns whether every required filter is set without
revealing errors; `reportValidity(): boolean` returns the same state and reveals every current
required-field error; `reset(): void` restores each definition's `defaultValue` (or unsets it),
unless the bar is disabled.

**Events:** `lr-input`, `lr-reset`, `lr-validity-change`.

**Slots:** `end` — extra host-supplied controls (for example, a "Save search" or "Export"
action) rendered inside `controls`, next to the reset button. Hidden and claiming no layout
space while nothing is slotted.

**CSS parts:** `base`, `controls`, `field`, `field-<filterId>`, `end`, `filter-control`,
`filter-control-label`, `filter-control-label-group`, `filter-control-field`,
`filter-control-input`, `filter-control-start`, `filter-control-end`, `filter-control-listbox`,
`filter-control-option`, `filter-control-tags`, `filter-control-tag`, `filter-control-tag-label`,
`filter-control-tag-remove-button`, `filter-control-tag-remove-button-base`,
`filter-control-clear-button`, `filter-control-expand-button`, `filter-control-expand-icon`,
`filter-control-popup`, `filter-control-error`, `filter-control-hint`, `active-filters`, `chips`,
`chip`, `reset-button`, `status`.

The `filter-control-*` parts are semantic aliases forwarded from each built-in control's shadow
surface. `filter-control-field` consistently reaches the select trigger, combobox container, or
text/date input wrapper; `filter-control-input` reaches the corresponding display or editable input.
Listbox/option aliases apply to select and combobox filters, `filter-control-tags`/
`filter-control-tag`/`filter-control-tag-label` apply to a `multiple` combobox filter's selected-tag
chips (`filter-control-tag-label` is capped by that control's own `--tag-max-size`), and
expand-button/popup apply to date filters. `filter-control-tag-remove-button`/
`filter-control-tag-remove-button-base` reach a selected tag's own remove button and its inner icon
wrapper — the same reach a standalone `lr-combobox`/`lr-select` consumer already has, now available
from `lr-filter-bar` too, for a consumer re-skinning filter tags as pills who needs the remove
target inside one to be stylable. This lets a consumer theme the composed tier from
`lr-filter-bar::part(...)` without depending on the built-in control type selected by a filter
definition. Custom renderers retain ownership of their own part forwarding.

A `multiple` `'combobox'` filter collapses past its own `max-options-visible` (3 by default, an
`<lr-combobox>` property this component does not forward) into a localized "+N" overflow indicator,
the same substance as `lr-select`'s own `multiple`-mode overflow chip. The one remaining difference:
`lr-select`'s overflow chip carries a second, distinguishing `tag-overflow` part
(`part="tag tag-overflow tag__base"`) so a consumer can style just that chip; `lr-combobox`'s
overflow chip carries only the plain `tag` part, with no equivalent token to forward as
`filter-control-tag-overflow`. Adding one is `<lr-combobox>`'s own surface to grow, not something
`lr-filter-bar`'s `exportparts` can manufacture for a part its composed child never renders — noted
here as a known, deliberate gap rather than silently undocumented.
On a `'checkbox-menu'` filter, `filter-control-field` is the trigger button's own frame — the
element inside `<lr-button>` that draws the border, background and radius, not the chrome-less
button host, so a `::part(filter-control-field) { border-color: … }` rule works there exactly as it
does for every other filter type. `filter-control-start` is that trigger's adornment wrapper (where
a definition `icon` lands), `filter-control-input` is its selection summary, `filter-control-label`
is the trigger's own label text (not a stacked label above the control), `filter-control-listbox` is
the dropdown's popup surface, `filter-control-option` is one `role="menuitemcheckbox"` row, and
`filter-control-error` is the revealed required message — rendered by the bar itself, because the
composed dropdown has no error chrome of its own. The trigger also renders a `with-caret` disclosure
chevron, matching `lr-select`'s own — forwarded as `filter-control-expand-icon`, the same name a
select/combobox/date-input filter's own chevron already uses, so one consumer rule styles every
filter type's expand icon. `filter-control-label-group` reaches the trigger's own label wrapper —
the flex row this component lays `filter-control-label` and `filter-control-input` out in, which
also grows to fill the stretched trigger (via `with-caret`) so its content starts at the leading
edge instead of centring; no other filter type renders this part, since every other type's label and
input are two independent elements with no shared wrapper of their own. This component does not
render a stacked label above a `'checkbox-menu'` field the way every other built-in type does:
every other type's stacked label is rendered by the composed control itself, and there is no
equivalent shared "stacked label" template inside `<lr-filter-bar>` for this branch to reuse without
inventing a new one, so `labelVisibility` keeps its narrower meaning here (whether the trigger's own
baked-in label text is visible or screen-reader-only).

`field` wraps one filter's composed control and its validation spacer inside `controls`; its
flex-basis is themeable via `--lr-filter-bar-field-basis` (default `var(--lr-size-12rem)`).
`--lr-filter-bar-gap` (default `var(--lr-space-s)`) themes the gap between filter fields, the
`end` slot, the reset button, and the loading status in the `controls` row. Both are byte-identical
to the previous hardcoded values when unset.

Each field wrapper also carries a second, per-filter part token, `field-<filterId>` (for example
`part="field field-status"`), so a single field can be targeted directly --
`lr-filter-bar::part(field-status) { flex: 2 1 20rem; }` -- setting any layout property, not just a
width, while `::part(field)` rules continue to match every field unchanged. The `field-<filterId>`
token is present only when `filterId` reads as a plain CSS ident (ASCII letters/digits/`-`/`_`,
starting with a letter); an id that doesn't (for example one containing whitespace) renders `field`
alone, exactly as before this part existed, rather than risking a `part` attribute whose
space-separated token list fabricates an unrelated second token.

A `'select'`, `'combobox'` or `'checkbox-menu'` filter's required `options` entries are
`LyraFilterBarOption { value, label, icon?, searchText?, disabled? }`. `searchText` is extra text
the option also matches on, forwarded verbatim to `<lr-option>`'s own `search-text`, so a row can
keep a short visible `label` ("Urgent") while still matching a long canonical key ("SEV-1
production outage"). It affects a `'combobox'` filter only: the attribute is written on every
choice type's `<lr-option>`, but `<lr-select>`'s listbox type-ahead matches the option's `label`
alone and never reads it, and a `'checkbox-menu'` has no text entry to match against. `disabled`
marks the option non-actionable: forwarded to `<lr-option disabled>` for `'select'`/`'combobox'`
and to the composed `<lr-dropdown-item disabled>` for `'checkbox-menu'`, so the row renders
genuinely disabled (no tab/roving stop, no hover/press affordance) and arrow-key navigation already
steps past it, since that is the composed control's own existing `disabled` behavior. Omitted or
`false` renders the option exactly as before this field existed.
`icon` is optional Lit content — a status dot, a type glyph, a flag — rendered into the composed
`<lr-option>`'s own `start` slot as inert, `aria-hidden` chrome, so it never joins the option's
accessible name:

```ts
options: [
  {
    value: "open",
    label: "Open",
    icon: html`<lr-icon name="circle"></lr-icon>`,
  },
  { value: "closed", label: "Closed" },
];
```

Each filter definition's `type` selects which existing Lyra input renders it — this component
composes them and never invents a control of its own. `'select'`/`'combobox'` map to their
same-named counterparts (with `combobox`'s `multiple` opting into a multi-value filter),
`'date'`/`'date-range'` both map to `<lr-date-input>` (single vs. `mode="range"`), and `'text'` maps
to `<lr-input>` for an open-ended free-text query rather than a closed choice set. A `'text'`
filter's value is the raw query string, verbatim, and its chip shows exactly that string — the same
text the user typed, not a truncated or normalized form. `'chip'` is the one type that renders no
control at all (see **Chip-only filters** below): its value belongs to a widget elsewhere on the
page, so the bar renders only its active-filter chip and gives it no toolbar cell.

Every built-in (non-`'custom'`) filter definition additionally accepts optional `size: LyraSize`,
`icon: unknown` and `labelVisibility: 'visible' | 'hidden' | 'auto'` fields, and every one whose
composed control ships a clear action also accepts `clearable: boolean`. They are forwarded verbatim to that
control's own same-named property — `icon` into its `start` slot exactly like a choice option's own
`icon`, rendered inert and `aria-hidden`; `clearable` reaching `<lr-date-input>` under its own
`with-clear` spelling, since that control has no `clearable`. `'text'` also accepts
`inputType: LyraInputType` (forwarded to the composed `<lr-input>`'s own `type`, e.g.
`'search'`/`'email'`/`'tel'`/`'url'`), and `'combobox'` also accepts `emptyText: string` (forwarded
to its `empty-text`, the row its listbox shows when a query matches none of the declared options). A
`'custom'` definition deliberately accepts none of them: its renderer owns the control's markup
outright, so a field the bar could not forward anywhere would be inert API. Every one of these is
optional and defaults to that composed control's own default, so an existing filter definition
renders unchanged.

`labelVisibility: 'hidden'` routes the filter's `label` to the composed control's own `aria-label`
instead of rendering it as a stacked visible label, and — when the definition declares no
`placeholder` of its own — also uses it as the placeholder. The label is re-routed, never dropped,
so a compact toolbar row still names every field for assistive technology; visually hiding
`::part(filter-control-label)` in CSS, the only previous option, removed the accessible name along
with the text.

`labelVisibility: 'auto'` is the width-dependent middle between the two. It renders exactly what
`'visible'` renders — the same stacked label element, the same accessible name computed from it, no
`aria-label` and no placeholder fallback — and the bar's own stylesheet visually clips that label
once the bar's allocation drops below `30rem`. The threshold is a container query on the host, so it
reads the bar's own allocated width, not the viewport's: the same definitions render labelled across
a dashboard and unlabelled in a 320px side panel, dialog or split pane, with no host-side breakpoint
logic. The label element is never removed at any width, so the field's accessible name is identical
in both states, and `'auto'` deliberately does not route the name onto the control the way
`'hidden'` does — doing so would name a wide-allocation field twice. A `'checkbox-menu'` filter
participates through its own trigger label run, the same one `'hidden'` already clips there. The
threshold is fixed rather than themeable: a CSS container query's prelude cannot read a custom
property (`var()` is not substituted in an at-rule prelude), so a `--lr-*` hook for it would parse
and silently never apply.

`'combobox'` also accepts the same `debounce?: number` (ms) `'text'` already had: it coalesces a
burst of rapid selection changes (picks, a multi-select toggle, an
`allowCustomValue`/`allowCreate` commit, or the clear action) into one delayed commit. Unlike
`'text'`'s uncontrolled-with-sync field, the composed `<lr-combobox>`'s `.value=` binding stays
fully controlled: while a commit is pending it renders that pending selection rather than the
last-committed `value`, so the control's own display never reverts mid-delay. A pending debounce
is flushed by the control's own blur and cancelled by `reset()`, a chip removal, and
disconnection — identical to `'text'`.

### `'checkbox-menu'` filters

A `'checkbox-menu'` filter composes `<lr-dropdown>` plus one `<lr-dropdown-item type="checkbox">`
(`role="menuitemcheckbox"`) per option, behind a single toolbar trigger button. The menu stays open
across toggles, so several categories can be switched in one visit. Its value is a `string[]`,
identical to a `'combobox'` with `multiple`, so the two are interchangeable everywhere the bar's own
bookkeeping is concerned — the same `value` record, active-filter chips, `reset()` path, `required`
validation and single full-value `lr-input`. Choose between them on interaction, not on data shape:
reach for `'checkbox-menu'` when the set is small and fixed and typing to filter would only be in
the way.

Rows are controlled by `value` rather than self-toggling, so a toggle the bar refuses (a `disabled`
bar, a filter removed mid-interaction) can never leave a checkmark the bar disagrees with.

It is the one built-in type that renders no stacked label above its control: the trigger button
carries the `label` as its own text next to the selection summary, and `labelVisibility: 'hidden'`
makes that text visually hidden — never removed — so the button keeps its accessible name. In the
one case where the hidden label would be the *only* thing the button says (hidden routing, no
declared `placeholder`, nothing selected) the label routes to the visible summary instead of being
emitted twice, so the trigger's accessible name stays "Teams", never "Teams Teams".
`labelVisibility: 'auto'` clips that same trigger label run, and only below the `30rem` threshold —
the label run is always emitted under `'auto'`, since nothing is routed to the summary there.

Because its trigger is a button rather than a field, a `required` `'checkbox-menu'` deliberately
renders **no** required asterisk and sets **no** `aria-invalid`: the shared required marker has no
selector that matches a button trigger's label, and `<lr-button>` does not forward a host
`aria-invalid` onto the element that owns the button role, so writing one would be silently inert. A
revealed required error still reaches assistive technology — it joins the trigger's accessible name
as a screen-reader-only run, alongside the visible `filter-control-error` line under the field.

```ts
const filters: LyraFilterBarFilterDefinition[] = [
  {
    filterId: "teams",
    label: "Teams",
    type: "checkbox-menu",
    placeholder: "Any team",
    options: [
      { value: "core", label: "Core" },
      { value: "infra", label: "Infrastructure" },
      { value: "design", label: "Design" },
    ],
  },
];
// bar.value -> { teams: ["core", "design"] }
```

A filter bar detached and reattached while a checkbox menu is open comes back closed, like every
other transient state the bar owns.

### Date-range quick ranges

A `'date-range'` definition also accepts `presets?: readonly LyraDateRangePreset[]` (new in 12.0.0),
forwarded to its composed `<lr-date-input>` exactly like `min`/`max`, so the quick-range row
("Today", "Last 7 days", "All time") renders inside that filter's own calendar popover. Entries are
`LyraDateRangePreset { label, start?, end?, id? }` with ISO `YYYY-MM-DD` bounds; an omitted bound is
open and resolves to the filter's `min`/`max`, and an open bound with no corresponding limit renders
that button disabled. The optional `id` is a caller-owned correlation key, never read by the bar
itself -- it exists purely so `appliedPreset.id` (below) is typed without a cast. `presets` is
deliberately **not** accepted on a single `'date'` filter: a preset names two dates, so
`lr-date-picker` ignores the list outside range mode, and a list passed there is dropped rather
than rendering a row that cannot do anything.

The `lr-input` emitted by such a commit carries `appliedPreset`, the definition entry whose button
produced it — the bar's own frozen snapshot, so it compares identical to `filters[i].presets[j]`. It
is `undefined` for every other filter type and for a range picked or typed by hand. A filter bar
whose values round-trip through a query string needs it because `value` holds only the frozen ISO
range: persisting "Last 7 days" as a preset id keeps it meaning the last 7 days after the next
reload, and re-deriving it by string-matching `value` is both the mapping table `presets` exists to
delete and ambiguous (Today and This month coincide on the 1st). It rides the event rather than
`value` because it is metadata about one edit, not a filter value — `value` stays the plain,
JSON-serializable record it has always been.

```ts
const filters: LyraFilterBarFilterDefinition[] = [
  {
    filterId: "period",
    label: "Reporting period",
    type: "date-range",
    min: "2020-01-01",
    max: "2030-12-31",
    presets: [
      { label: "Last 7 days", start: "2026-08-13", end: "2026-08-19" },
      { label: "This month", start: "2026-08-01", end: "2026-08-31" },
      { label: "All time" },
    ],
  },
];

bar.addEventListener("lr-input", (event) => {
  const { value, filterId, appliedPreset } = event.detail;
  persist({ ...value, periodPreset: appliedPreset?.label });
});
```

Before this, the only way to give a filter-bar date range a quick-range row was `type: 'custom'`,
which means hand-rendering an `lr-date-input` plus a full adapter (`clearValue`, `isEmpty`,
`formatValue`) to set one property, and forfeits the built-in date-range chip localization described
next.

Date chips localize exactly one round-trip-valid ISO `YYYY-MM-DD` segment; date-range chips require
exactly two slash-separated segments. Four-digit
years `0000`–`0099` retain those literal years rather than inheriting JavaScript's 1900 offset;
impossible days/months, extra/missing segments, inverted ranges, and a range with either invalid
endpoint stay verbatim instead of silently rolling into another date or discarding data.

A `'text'` filter is the one control that is **not** a fully controlled `.value=` binding.
Re-rendering a text field from `value` mid-typing would push a stale value back in and drop the
caret to the end, so the field owns its own value while the user types, and an external `value`
write is synced back into it only once no edit is in flight (a host write, a chip removal, and
`reset()` all take that path).

`'text'` filters also accept an optional per-filter `debounce` (ms) — how long to wait after the
last keystroke before committing the typed value to `value` and emitting a single `lr-input`, so a
server-side query runs once per pause instead of once per character. Omitted, `0`, or a non-finite
value means no debounce at all: every keystroke commits immediately. A pending debounce is always
**flushed** by the field's own `change`/blur, so a blur never loses the last keystroke, and
**cancelled outright** by `reset()`, by removing that filter's chip, and on disconnect — a stale
keystroke can never overwrite a reset or fire after teardown. `'combobox'` accepts the same
`debounce`, and so does `'custom'` (see below); `debounce` is ignored for every other `type`, whose
commits are discrete choices with nothing to debounce.

### Custom controls

Use `type: 'custom'` when an existing Lyra control does not fit the built-in filter types. Provide a
`custom` object with a `render(context)` function and an `adapter`. The renderer owns the control's
markup and should bind the context's `value`, `disabled`, `required`, and `errorText` as appropriate;
`context.onValueChange` (or its `onInput`/`onChange` aliases) reads the event through
`adapter.valueFromEvent` and commits it to the filter bar. `context.setValue(value)` is available for
controls that expose a value without an event payload, and `context.onFocusout` marks the filter
touched for required validation. Every context also carries its `filterId`, a monotonic
`generation`, and an `AbortSignal`; replacement/removal of the schema, disconnection, and reconnect
abort stale contexts, whose callbacks become inert.

A `'custom'` definition also accepts the same optional `debounce?: number` (ms) `'text'`/
`'combobox'` already have: it delays committing whatever `context.onValueChange`/`onInput`/
`onChange` reads through `adapter.valueFromEvent`, coalescing a burst of rapid commits into one.
Omitted, `0`, or a non-finite value means no debounce, exactly as before this field existed. While
one is pending, `context.value` carries that pending value rather than the last-committed one, so a
renderer binding it as a fully controlled value never reverts mid-delay; a pending commit is
**flushed** by `context.onFocusout` and **cancelled outright** by `reset()`, removing that filter's
chip, and disconnect — identical to `'text'`/`'combobox'`. This is what closes the gap those two
types' own debounce left: before this field existed, a custom free-text filter had to hand-roll the
same timer, flush, and cancellation lifecycle itself just to match `'text'`.

The adapter's required `clearValue` is used when the active chip is removed. Its optional
`isEmpty(value)` defines domain emptiness; without one, the bar compares against `clearValue`
(including shallow string-array equality). Its optional `formatValue(value, locale)` controls chip
display; `locale` is the filter bar's `effectiveLocale`, the same value every built-in filter
type's own chip formatting already receives, so an existing single-argument `formatValue`
implementation keeps working unchanged — JS simply ignores a second parameter it never declared.
Consequently `false` remains a meaningful active value unless the adapter explicitly declares it
empty. Custom values may be strings, string arrays, booleans, or `undefined`, so controls such as
`lr-time-range`, `lr-checkbox`, and an async-backed `lr-combobox` can participate in the same
controlled value, active-chip, reset, disabled, and validation contract:

```ts
const filters: LyraFilterBarFilterDefinition[] = [
  {
    filterId: "archived",
    label: "Include archived",
    type: "custom",
    custom: {
      adapter: {
        valueFromEvent: (event) =>
          (event as CustomEvent<{ checked: boolean }>).detail.checked,
        clearValue: false,
        formatValue: (value) => (value === true ? "Enabled" : "Disabled"),
      },
      render: (context) => html`
        <lr-checkbox
          .checked=${context.value === true}
          ?disabled=${context.disabled}
          @lr-change=${context.onValueChange}
          @focusout=${context.onFocusout}
          >${context.label}</lr-checkbox
        >
      `,
    },
  },
];
```

The custom renderer returns a Lit `TemplateResult`; the filter bar places it in its
`filter-control` part and re-renders it whenever the controlled value or validation state changes.

### Chip-only filters

Use `type: 'chip'` when the value is already owned by a widget elsewhere on the page — a calendar
heatmap cell, a map selection, a chart brush — and the bar's job is only to *show* that the filter
is applied and to let the user take it off. Unlike `type: 'custom'`, which still renders a control
inside the toolbar, a chip-only filter renders **no control and no toolbar cell at all**: no `field`
wrapper is emitted for it, so `lr-filter-bar::part(field)` and `::part(field-<filterId>)` never
match one and a bar whose filters are *all* chip-only shows no empty column — its `controls` row
still holds the reset button (the "clear all" action such a bar needs), the `end` slot, and the
loading spinner, exactly like a bar with no filters at all.

Everything else is unchanged from any other filter type. The value lives in `value` under its own
filter ID, rides every `lr-input`/`lr-reset` detail, counts toward `hasActiveFilters` (so it enables
the reset button) and toward `invalidFilterIds` when the definition is `required`, renders a
removable active-filter chip subject to `activeFiltersDisplay`, and is cleared both by removing that
chip and by `reset()`. A `required` chip-only filter is honoured in **bookkeeping only**: it joins
`invalidFilterIds`, fails `checkValidity()` and moves `lr-validity-change`, but renders no inline
error, because the bar renders no element of its own for it — the owning widget is responsible for
its own error affordance. The inherited `placeholder` is inert here for the same reason it is for
`type: 'custom'`: there is no field to place it in.

A chip-only definition adds three optional fields of its own:

```ts
type: 'chip';
formatValue?: (value: LyraFilterBarFieldValue, locale: string) => string;
clearValue?: LyraFilterBarFieldValue;
isEmpty?: (value: LyraFilterBarFieldValue) => boolean;
```

`formatValue` produces the chip's text, and its `locale` argument is the bar's `effectiveLocale` —
the same locale every built-in type's own chip formatting and a custom adapter's `formatValue`
already receive, and the reason a chip-only value (normally an already-formatted string such as a
localized date) can be localized by the caller. That output is caller data, so — like a filter's
own label — the bar never routes it through its own localization. Omitted, the fallback ladder is
the one a custom adapter's omitted `formatValue` uses: a string array renders as a localized
conjunction list, anything else renders verbatim through `String(value)`, and an unset value renders
as the empty string. Verbatim is exact: a chip-only value is never run through the date branch that
localizes a `'date'`/`'date-range'` chip, so an ISO day is not silently reformatted and a value
containing a slash is not mangled.

`clearValue` is what a chip removal (and `clearFilter()`) writes, defaulting to the empty string —
what every non-multi built-in type writes. Declare an empty array for an array-valued chip-only
filter. `isEmpty` overrides the built-in emptiness rule (absent, `false`, the empty string and the
empty array are empty; everything else is set). **A domain sentinel must pair the two**: declaring
a sentinel clear value without a matching `isEmpty` leaves the bar reading the "cleared" value as
still set, so it keeps rendering a chip for it — the identical pairing a custom adapter's own
`clearValue`/`isEmpty` documents. With the pair declared, the sentinel is never stored in `value`
(cleared keys are omitted) and an absent key reads back as the sentinel for the owning widget.

```ts
const filters: LyraFilterBarFilterDefinition[] = [
  { filterId: "query", label: "Query", type: "text" },
  {
    filterId: "day",
    label: "Day",
    type: "chip",
    formatValue: (value, locale) =>
      new Intl.DateTimeFormat(locale, {
        dateStyle: "medium",
        timeZone: "UTC",
      }).format(new Date(`${String(value)}T00:00:00Z`)),
  },
];

// The calendar heatmap beside the bar owns the value; the bar only shows and removes it.
heatmap.addEventListener("app-select-day", (event) => {
  const { isoDate } = (event as CustomEvent<{ isoDate: string }>).detail;
  bar.value = { ...bar.value, day: isoDate };
});
bar.addEventListener("lr-input", (event) => {
  const { value } = (event as LyraFilterBarInputEvent).detail;
  heatmap.selectedDay = (value["day"] as string | undefined) ?? "";
});
```

**TypeScript:** `LyraFilterBar<Defs extends readonly LyraFilterBarFilterDefinition[] =
readonly LyraFilterBarFilterDefinition[]>` — `value` and the `lr-input`/`lr-reset` detail `value`
narrow to a record keyed per `filterId`, whose value type follows that filter's own definition (a
`'select'`, a non-`multiple` `'combobox'`, `'text'`, `'date'`, and `'date-range'` narrow to
`string`; a `'checkbox-menu'` and a `multiple: true` `'combobox'` narrow to `readonly string[]`; a
`'custom'` filter keeps the full unconstrained field value, and so does a `'chip'` filter, whose
value is owned by a widget this component never renders). Declare the schema with `as const
satisfies readonly LyraFilterBarFilterDefinition[]` and type the element as
`LyraFilterBar<typeof FILTERS>` to pick it up. Types only; the runtime is unchanged, and an untyped
`<lr-filter-bar>` keeps today's `LyraFilterBarValue` (`Readonly<Record<string, string | readonly
string[] | boolean | undefined>>`). `LyraFilterBarValueFor<Defs>` is the standalone alias for the
narrowed record, and `LyraFilterBarInputEvent<Defs>`/`LyraFilterBarResetEvent<Defs>` are stable
per-event aliases so a handler can name one event's type without restating the detail shape.

## `lr-page`

Semantic application/page shell with page-wide banner/header/subheader/footer regions, a compact
menu, primary navigation, main header/content/footer, and an aside. It derives mobile versus
desktop presentation from **its own allocated inline size**, not the viewport: a Page inside a
narrow split pane becomes mobile even on a wide monitor. The first/server-safe state is desktop;
the first live measurement corrects it before normal interaction.

Navigation has one static shadow subtree and one `navigation` slot in both presentations. Desktop
places it in the grid; mobile promotes that exact subtree into a logical-edge modal drawer. Assigned
nodes are never cloned or recreated, so focus, custom-element instances, form state, scroll state,
and event listeners survive every breakpoint crossing.

**Properties:**

- `view: 'mobile' | 'desktop' = 'desktop'` (reflected) — current allocation-derived presentation.
- `navOpen: boolean = false` (attribute `nav-open`, reflected) — mobile drawer state. Navigation is
  visible on desktop independently. The state is retained through a desktop crossing, so returning
  to mobile restores the same open drawer rather than replacing its content.
- `mobileBreakpoint: string = '768px'` (attribute `mobile-breakpoint`, not reflected) — accepts a
  bare number/px length, `rem` resolved against the live root font size, or `em` resolved against
  the Page's live font size. It is re-resolved on every allocation measurement. Invalid values,
  including `%`, viewport units, `calc()`, and `var()`, fall back to `768px`.
- `navigationPlacement: 'start' | 'end' = 'start'` (attribute `navigation-placement`, reflected) —
  a logical placement: `start` is left in LTR and right in RTL; `end` is the reverse.
- `tabindex: string = '-1'` (reflected) — the host fragment target's native focusability. The Page
  preserves an authored value and otherwise keeps the host target focusable programmatically so a
  skip link or URL fragment can transfer focus into the main content.
- `disableNavigationToggle: boolean = false` (attribute `disable-navigation-toggle`, reflected) —
  hides the built-in mobile toggle. One or more custom controls assigned to `navigation-toggle`, or
  a slotted control carrying `data-toggle-nav`, can still own the action.
- `strings`/`locale` and host `aria-label` follow the shared localization contract. `aria-label`
  overrides the localized name of the internal navigation landmark.

**Methods:** `showNavigation(): void`, `hideNavigation(): void`, and
`toggleNavigation(): void` update `navOpen`. `visiblePixelsInViewport(element: HTMLElement | null):
number` returns the element's finite, viewport-clamped vertical intersection in CSS pixels (`0` for
`null`, invalid geometry, no intersection, or an element in a detached document with no viewport).
This is a deliberate owner-realm safety divergence from Web Awesome 3.11, whose method returns
`null` for a null input and measures detached-document geometry against the ambient page viewport;
code migrating from `wa-page` should treat Lyra's always-finite `number` result as canonical.

**Events:** `lr-nav-toggle` (cancelable; `detail: { open }` is the `navOpen` state proposed by
`showNavigation()`/`hideNavigation()`/`toggleNavigation()` or a built-in dismissal — backdrop
click, Escape, or the default/custom navigation-toggle control, all of which route through those
same methods. Call `preventDefault()` to leave `navOpen` unchanged.)

The default mobile toggle is a native button with localized open/close names and explicit
`aria-haspopup="dialog"`, `aria-expanded="true|false"`, plus `aria-controls` pointing to this
Page's unique drawer. Opening
uses Lyra's shared modal overlay stack for inerting, scroll lock, Escape/backdrop dismissal, focus
trapping, stacking, reconnect suspension, and focus return. Modal inerting is scoped to the live
drawer root, so header/main/footer siblings inside the Page become inert without inerting the
drawer itself. Every custom `navigation-toggle` and the composed descendant that actually receives
focus are wired to the same state with `aria-haspopup="dialog"`, synchronized `aria-expanded`, and
a localized label when unnamed; any available assigned control opens the same Page-owned drawer,
while disabled, `aria-disabled`, hidden, and inert controls remain non-actions. The component
supplies the real drawer to the shared controls owner; current browsers normalize that inward
private relationship to the public Page host. Generated whole-value state remains authoritative
while assigned, authored relationship tokens compose, and exact initial or late-authored baselines
return when a toggle is replaced, removed, or the Page disconnects. If the opening toggle is
replaced while the drawer is open, both the ARIA owner and eventual focus-return target retarget to
the next available assigned toggle's real composed control.

`navigation-toggle-icon` is decorative visual content: its assigned subtree is inert and hidden
from assistive technology, while the native toggle retains the sole action and localized name.
Likewise, `skip-to-content` replaces only visible skip-link text; its assigned subtree is inert and
hidden from assistive technology, but its text names the Page's sole skip link. Supply text or a
glyph as appropriate to the slot, not a separate interactive control: `skip-to-content` needs
descriptive text, while `navigation-toggle-icon` needs a glyph.

The focus-visible skip link has a localized `Skip to content` fallback and focuses the unique
internal `<main>`. Native URL fragments cannot address an id inside a shadow root, so the Page host
is the unique, programmatically focusable fragment target; activation then focuses and scrolls its
own main landmark. Multiple Page instances therefore never share a global `#main-content` target.

**Slots (15):** default (main content), `aside`, `banner`, `footer`, `header`, `main-footer`,
`main-header`, `menu`, `navigation`, `navigation-footer`, `navigation-header`,
`navigation-toggle`, `navigation-toggle-icon`, `skip-to-content`, and `subheader`.

**CSS parts (22):** `aside`, `banner`, `base` and `page` (same root node), `body`,
`dialog-wrapper`, `drawer`, `footer`, `header`, `main`, `main-content`, `main-footer`,
`main-header`, `menu`, `navigation` and `navigation-desktop` (same navigation landmark),
`navigation-footer`, `navigation-header`, `navigation-toggle`, `navigation-toggle-icon`,
`skip-to-content`, and `subheader`.

**Themeable custom properties:** `--lr-page-aside-width` (default `auto`),
`--lr-page-banner-height` (`0px`), `--lr-page-header-height` (`0px`),
`--lr-page-main-width` (`1fr`), `--lr-page-menu-width` (`auto`), and
`--lr-page-subheader-height` (`0px`). The six Web Awesome spellings remain accepted as aliases:
`--aside-width`, `--banner-height`, `--header-height`, `--main-width`, `--menu-width`, and
`--subheader-height`. Set either spelling on the Page itself; the prefixed name is Lyra's canonical
form. The following interaction and overlay paints are inherited inline fallbacks, so an element or
ancestor may retheme only the named state: `--lr-page-skip-to-content-hover-bg` (default
`var(--lr-color-brand-quiet)`), `--lr-page-skip-to-content-hover-color` (default
`var(--lr-color-brand)`), `--lr-page-skip-to-content-active-bg` (default `color-mix(in oklab,
var(--lr-color-brand-quiet), var(--lr-color-mix-partner) var(--lr-color-mix-active))`),
`--lr-page-skip-to-content-active-color` (default `var(--lr-color-brand)`),
`--lr-page-navigation-toggle-hover-bg` (default `var(--lr-color-brand-quiet)`),
`--lr-page-navigation-toggle-hover-color` (default `var(--lr-color-brand)`),
`--lr-page-navigation-toggle-active-bg` (default `color-mix(in oklab, var(--lr-color-brand-quiet),
var(--lr-color-mix-partner) var(--lr-color-mix-active))`),
`--lr-page-navigation-toggle-active-color` (default `var(--lr-color-brand)`),
`--lr-page-navigation-backdrop-bg` (default `var(--lr-color-overlay)`),
`--lr-page-navigation-drawer-bg` (default `var(--lr-color-surface-overlay)`), and
`--lr-page-navigation-drawer-shadow` (default `var(--lr-shadow-l)`).

`disable-sticky` is a whitespace-token attribute, not a comma-separated value. Accepted tokens are
`banner`, `header`, `subheader`, `menu`, and `aside`; each only disables that region. Sticky offsets
use the three configured height properties, so set them to the real minimum heights when those rows
carry content. Motion uses Lyra transition tokens and is removed under `prefers-reduced-motion`.
Every region has a zero-minimum inline size and anywhere wrapping; the drawer clamps inside a 320px
allocation, and long localized or consumer-provided text cannot widen the Page.

Import only the Page registration when it is the only layout component this bundle needs:

```js
import "@aceshooting/lyra-ui/components/layout/page/page.js";
```

```html
<lr-page
  mobile-breakpoint="48rem"
  navigation-placement="start"
  disable-sticky="aside"
  style="--lr-page-main-width: 1fr; --lr-page-aside-width: 14rem"
>
  <strong slot="header">Workspace</strong>
  <button slot="header" data-toggle-nav>Sections</button>
  <h2 slot="navigation-header">Sections</h2>
  <a slot="navigation" href="/overview">Overview</a>
  <a slot="navigation" href="/reports">Reports</a>
  <h1 slot="main-header">Overview</h1>
  <p>Main content</p>
  <aside slot="aside">Related reports</aside>
  <small slot="footer">Workspace footer</small>
</lr-page>
```

## Consumer integration notes

- **Multi-split:** `LyraMultiSplitToggleDetail` is `{ open: boolean }`. Escape or a backdrop click
  proposes a floating-panel state cancelably before `open` changes; `preventDefault()` or a
  synchronous reentrant write aborts the proposal. Leaving floating mode closes the panel, emits
  the collapse change, and then emits noncancelable `lr-toggle`; direct writes and no-ops stay
  silent. Divider numeric ARIA values remain percentages and their `aria-valuetext` is localized.
- **Resizers:** `lr-split-panel` retains numeric percent ranges with localized current-percent
  `aria-valuetext`; `lr-app-rail` and `lr-dock-panel` expose CSS-pixel ranges with localized current
  width/extent text. The app-rail toggle inherits rail typography and its glyph is `1em`.
- **Details structure:** `base` is the outer details container and `header` is its complete row.
  A private native `<details>` owns the summary; `header-actions` is its sibling after that native
  element, stays enabled and non-toggling even while the disclosure is disabled, and `content` is
  behind a private `hidden="until-found"` gate. `beforematch` or a fragment reveal follows the
  normal programmatic lifecycle, or re-arms the gate after a veto or disabled state.

## Exported TypeScript contracts

These named interfaces and helper signatures are available to typed integrations. They are grouped by capability so the component sections above can stay focused.

- **`components-layout-app-rail-app-rail-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/layout/app-rail/app-rail.class.js`.
  `LyraAppRailModeChangeDetail {
    mode: LyraAppRailMode;
  }`
  Import: `@aceshooting/lyra-ui/components/layout/app-rail/app-rail.class.js`.
  `LyraAppRailResizeDetail {
    widthPx: number;
  }`
  Import: `@aceshooting/lyra-ui/components/layout/app-rail/app-rail.class.js`.
  `LyraAppRailToggleDetail {
    open: boolean;
  }`
  Import: `@aceshooting/lyra-ui/components/layout/app-rail/app-rail.class.js`.
  `computeAppRailMode(iconOnlyMatches: boolean, mobileMatches: boolean, preferredMode?: LyraAppRailPreferredMode | null): LyraAppRailMode`

- **`components-layout-app-rail-group-app-rail-group-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/layout/app-rail-group/app-rail-group.class.js`.
  `LyraAppRailGroupToggleDetail {
    open: boolean;
  }`

- **`components-layout-app-rail-item-app-rail-item-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/layout/app-rail/app-rail-item.class.js`.
  `LyraAppRailItemToggleDetail {
    open: boolean;
  }`

- **`components-layout-command-palette-command-palette-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/layout/command-palette/command-palette.class.js`.
  `LyraCommand {
    commandId: string;
    label: string;
    description?: string;
    group?: string;
    shortcut?: string;
    keywords?: readonly string[];
    disabled?: boolean;
    icon?: unknown;
    onSelect?: () => void;
  }`

- **`components-layout-dashboard-grid-dashboard-grid-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/layout/dashboard-grid/dashboard-grid.class.js`.
  `LyraDashboardCellMoveDetail {
    readonly cellId: string;
    readonly position: Readonly<{
      x: number;
      y: number;
    }>;
    readonly previous: Readonly<{
      x: number;
      y: number;
    }>;
  }`
  Import: `@aceshooting/lyra-ui/components/layout/dashboard-grid/dashboard-grid.class.js`.
  `LyraDashboardCellResizeDetail {
    readonly cellId: string;
    readonly size: Readonly<{
      w: number;
      h: number;
    }>;
    readonly previous: Readonly<{
      w: number;
      h: number;
    }>;
  }`
  Import: `@aceshooting/lyra-ui/components/layout/dashboard-grid/dashboard-grid.class.js`.
  `LyraDashboardCollisionDetail {
    readonly cellId: string;
    readonly collidedCellIds: readonly string[];
    readonly policy: LyraDashboardCollisionPolicy;
    readonly accepted: boolean;
  }`
  Import: `@aceshooting/lyra-ui/components/layout/dashboard-grid/dashboard-grid.class.js`.
  `LyraDashboardLayoutChangeDetail {
    readonly layout: readonly LyraDashboardCell[];
  }`

- **`components-layout-dashboard-grid-layout-types-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/layout/dashboard-grid/dashboard-grid.js`.
  `LyraDashboardCell {
    readonly cellId: string;
    readonly x: number;
    readonly y: number;
    readonly w: number;
    readonly h: number;
    readonly minW?: number;
    readonly minH?: number;
    readonly maxW?: number;
    readonly maxH?: number;
    readonly locked?: boolean;
    readonly widget?: LyraWidgetNode | null;
    readonly label?: string;
  }`
  Import: `@aceshooting/lyra-ui/components/layout/dashboard-grid/dashboard-grid.js`.
  `LyraDashboardPlacementResult {
    readonly accepted: boolean;
    readonly layout: readonly LyraDashboardCell[];
    readonly collidedCellIds: readonly string[];
  }`

- **`components-layout-dashboard-grid-layout-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/layout/dashboard-grid/dashboard-grid.js`.
  `resolveLyraDashboardPlacement(layout: readonly LyraDashboardCell[], candidateCellId: string, requested: Readonly<{
    x: number;
    y: number;
    w: number;
    h: number;
  }>, columns: number, policy: LyraDashboardCollisionPolicy): LyraDashboardPlacementResult`

- **`components-layout-details-accordion-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/layout/details/accordion.class.js`.
  `LyraAccordionEventDetail {
    readonly item: LyraAccordionItem;
  }`

- **`components-layout-details-details-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/layout/details/details.class.js`.
  `LyraDetailsToggleDetail {
    open: boolean;
    source: LyraDetailsToggleSource;
  }`

- **`components-layout-dock-panel-dock-panel-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/layout/dock-panel/dock-panel.class.js`.
  `LyraDockPanelCollapseChangeDetail {
    readonly collapsed: boolean;
  }`
  Import: `@aceshooting/lyra-ui/components/layout/dock-panel/dock-panel.class.js`.
  `LyraDockPanelResizeDetail {
    readonly extent: string;
  }`

- **`components-layout-drilldown-panel-drilldown-panel-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/layout/drilldown-panel/drilldown-panel.class.js`.
  `LyraDrilldownCategoryChangeDetail {
    readonly nodeId: string;
    readonly category: LyraDrilldownCategory;
    readonly previousCategory: LyraDrilldownCategory;
  }`
  Import: `@aceshooting/lyra-ui/components/layout/drilldown-panel/drilldown-panel.class.js`.
  `LyraDrilldownDocumentDownloadDetail {
    readonly nodeId: string;
    readonly documentId: string;
    readonly src: string;
    readonly filename: string;
  }`
  Import: `@aceshooting/lyra-ui/components/layout/drilldown-panel/drilldown-panel.class.js`.
  `LyraDrilldownDocumentHighlightActivateDetail {
    readonly nodeId: string;
    readonly documentId: string;
    readonly highlightId: string;
  }`
  Import: `@aceshooting/lyra-ui/components/layout/drilldown-panel/drilldown-panel.class.js`.
  `LyraDrilldownDocument {
    readonly documentId: string;
    readonly name: string;
    readonly mimeType?: string;
    readonly uri?: string;
    readonly version?: string;
  }`
  Import: `@aceshooting/lyra-ui/components/layout/drilldown-panel/drilldown-panel.class.js`.
  `LyraDrilldownDocumentRenderErrorDetail {
    readonly nodeId: string;
    readonly documentId: string;
    readonly error: unknown;
  }`
  Import: `@aceshooting/lyra-ui/components/layout/drilldown-panel/drilldown-panel.class.js`.
  `LyraDrilldownEntityActivateDetail {
    readonly nodeId: string;
    readonly entityId: string;
  }`
  Import: `@aceshooting/lyra-ui/components/layout/drilldown-panel/drilldown-panel.class.js`.
  `LyraDrilldownEntity {
    readonly entityId: string;
    readonly label: string;
    readonly type?: string;
    readonly description?: string;
    readonly properties?: Readonly<Record<string, string | number>>;
    readonly degree?: number;
    readonly communityId?: string;
  }`
  Import: `@aceshooting/lyra-ui/components/layout/drilldown-panel/drilldown-panel.class.js`.
  `LyraDrilldownEvidenceExpandDetail {
    readonly nodeId: string;
    readonly evidenceId: string;
    readonly expanded: boolean;
  }`
  Import: `@aceshooting/lyra-ui/components/layout/drilldown-panel/drilldown-panel.class.js`.
  `LyraDrilldownEvidenceItem {
    readonly evidenceId: string;
    readonly title: string;
    readonly page?: string | number;
    readonly href?: string;
    readonly excerpt?: string;
    readonly full?: string;
  }`
  Import: `@aceshooting/lyra-ui/components/layout/drilldown-panel/drilldown-panel.class.js`.
  `LyraDrilldownEvidenceOpenDetail {
    readonly nodeId: string;
    readonly evidenceId: string;
    readonly href?: string;
  }`
  Import: `@aceshooting/lyra-ui/components/layout/drilldown-panel/drilldown-panel.class.js`.
  `LyraDrilldownNavigateDetail {
    readonly nodeId: string;
    readonly index: number;
  }`
  Import: `@aceshooting/lyra-ui/components/layout/drilldown-panel/drilldown-panel.class.js`.
  `LyraDrilldownNode {
    readonly nodeId: string;
    readonly label: string;
    readonly evidence?: readonly LyraDrilldownEvidenceItem[];
    readonly documents?: readonly LyraDrilldownDocument[];
    readonly entities?: readonly LyraDrilldownEntity[];
  }`

- **`components-layout-filter-bar-filter-bar-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/layout/filter-bar/filter-bar.class.js`.
  `LyraFilterBarComboboxDefinition extends LyraFilterBarClearableDefinitionBase {
    readonly type: 'combobox';
    readonly options: readonly LyraFilterBarOption[];
    readonly multiple?: boolean;
    readonly debounce?: number;
    readonly emptyText?: string;
    // Inherited from LyraFilterBarClearableDefinitionBase.
    readonly clearable?: boolean;
    // Inherited from LyraFilterBarComposedDefinitionBase.
    readonly size?: LyraSize;
    readonly icon?: unknown;
    readonly labelVisibility?: LyraFilterBarLabelVisibility;
    // Inherited from LyraFilterBarDefinitionBase.
    readonly filterId: string;
    readonly label: string;
    readonly placeholder?: string;
    readonly required?: boolean;
    readonly defaultValue?: string | readonly string[] | boolean;
  }`
  Import: `@aceshooting/lyra-ui/components/layout/filter-bar/filter-bar.class.js`.
  `LyraFilterBarCheckboxMenuDefinition extends LyraFilterBarComposedDefinitionBase {
    readonly type: 'checkbox-menu';
    readonly options: readonly LyraFilterBarOption[];
    // Inherited from LyraFilterBarComposedDefinitionBase.
    readonly size?: LyraSize;
    readonly icon?: unknown;
    readonly labelVisibility?: LyraFilterBarLabelVisibility;
    // Inherited from LyraFilterBarDefinitionBase.
    readonly filterId: string;
    readonly label: string;
    readonly placeholder?: string;
    readonly required?: boolean;
    readonly defaultValue?: string | readonly string[] | boolean;
  }`
  Import: `@aceshooting/lyra-ui/components/layout/filter-bar/filter-bar.class.js`.
  `LyraFilterBarChipDefinition extends LyraFilterBarDefinitionBase {
    readonly type: 'chip';
    readonly formatValue?: (value: LyraFilterBarFieldValue, locale: string) => string;
    readonly clearValue?: LyraFilterBarFieldValue;
    readonly isEmpty?: (value: LyraFilterBarFieldValue) => boolean;
    // Inherited from LyraFilterBarDefinitionBase.
    readonly filterId: string;
    readonly label: string;
    readonly placeholder?: string;
    readonly required?: boolean;
    readonly defaultValue?: string | readonly string[] | boolean;
  }`
  Import: `@aceshooting/lyra-ui/components/layout/filter-bar/filter-bar.class.js`.
  `LyraFilterBarCustomControlAdapter {
    readonly valueFromEvent: (event: Event) => LyraFilterBarFieldValue;
    readonly clearValue: LyraFilterBarFieldValue;
    readonly isEmpty?: (value: LyraFilterBarFieldValue) => boolean;
    readonly formatValue?: (value: LyraFilterBarFieldValue, locale: string) => string;
  }`
  Import: `@aceshooting/lyra-ui/components/layout/filter-bar/filter-bar.class.js`.
  `LyraFilterBarCustomControlContext {
    readonly filterId: string;
    readonly label: string;
    readonly definition: LyraFilterBarCustomDefinition;
    readonly value: LyraFilterBarFieldValue;
    readonly disabled: boolean;
    readonly required: boolean;
    readonly errorText: string;
    readonly signal: AbortSignal;
    readonly generation: number;
    readonly setValue: (value: LyraFilterBarFieldValue) => void;
    readonly onValueChange: (event: Event) => void;
    readonly onInput: (event: Event) => void;
    readonly onChange: (event: Event) => void;
    readonly onFocusout: () => void;
  }`
  Import: `@aceshooting/lyra-ui/components/layout/filter-bar/filter-bar.class.js`.
  `LyraFilterBarCustomControl {
    readonly render: (context: LyraFilterBarCustomControlContext) => TemplateResult;
    readonly adapter: LyraFilterBarCustomControlAdapter;
  }`
  Import: `@aceshooting/lyra-ui/components/layout/filter-bar/filter-bar.class.js`.
  `LyraFilterBarCustomDefinition extends LyraFilterBarDefinitionBase {
    readonly type: 'custom';
    readonly custom: LyraFilterBarCustomControl;
    readonly debounce?: number;
    // Inherited from LyraFilterBarDefinitionBase.
    readonly filterId: string;
    readonly label: string;
    readonly placeholder?: string;
    readonly required?: boolean;
    readonly defaultValue?: string | readonly string[] | boolean;
  }`
  Import: `@aceshooting/lyra-ui/components/layout/filter-bar/filter-bar.class.js`.
  `LyraFilterBarDateDefinition extends LyraFilterBarDateDefinitionBase {
    readonly type: 'date';
    // Inherited from LyraFilterBarDateDefinitionBase.
    readonly min?: string;
    readonly max?: string;
    readonly clearable?: boolean;
    readonly size?: LyraSize;
    readonly icon?: unknown;
    readonly labelVisibility?: LyraFilterBarLabelVisibility;
    readonly filterId: string;
    readonly label: string;
    readonly placeholder?: string;
    readonly required?: boolean;
    readonly defaultValue?: string | readonly string[] | boolean;
  }`
  Import: `@aceshooting/lyra-ui/components/layout/filter-bar/filter-bar.class.js`.
  `LyraFilterBarDateRangeDefinition extends LyraFilterBarDateDefinitionBase {
    readonly type: 'date-range';
    readonly presets?: readonly LyraDateRangePreset[];
    // Inherited from LyraFilterBarDateDefinitionBase.
    readonly min?: string;
    readonly max?: string;
    readonly clearable?: boolean;
    readonly size?: LyraSize;
    readonly icon?: unknown;
    readonly labelVisibility?: LyraFilterBarLabelVisibility;
    readonly filterId: string;
    readonly label: string;
    readonly placeholder?: string;
    readonly required?: boolean;
    readonly defaultValue?: string | readonly string[] | boolean;
  }`
  Import: `@aceshooting/lyra-ui/components/layout/filter-bar/filter-bar.class.js`.
  `LyraFilterBarInputDetail {
    readonly value: LyraFilterBarValue;
    readonly filterId?: string;
    readonly appliedPreset?: LyraDateRangePreset;
  }`
  Import: `@aceshooting/lyra-ui/components/layout/filter-bar/filter-bar.class.js`.
  `LyraFilterBarOption {
    readonly value: string;
    readonly label: string;
    readonly icon?: unknown;
    readonly searchText?: string;
    readonly disabled?: boolean;
  }`
  Import: `@aceshooting/lyra-ui/components/layout/filter-bar/filter-bar.class.js`.
  `LyraFilterBarResetDetail {
    readonly value: LyraFilterBarValue;
  }`
  Import: `@aceshooting/lyra-ui/components/layout/filter-bar/filter-bar.class.js`.
  `LyraFilterBarSelectDefinition extends LyraFilterBarClearableDefinitionBase {
    readonly type: 'select';
    readonly options: readonly LyraFilterBarOption[];
    // Inherited from LyraFilterBarClearableDefinitionBase.
    readonly clearable?: boolean;
    // Inherited from LyraFilterBarComposedDefinitionBase.
    readonly size?: LyraSize;
    readonly icon?: unknown;
    readonly labelVisibility?: LyraFilterBarLabelVisibility;
    // Inherited from LyraFilterBarDefinitionBase.
    readonly filterId: string;
    readonly label: string;
    readonly placeholder?: string;
    readonly required?: boolean;
    readonly defaultValue?: string | readonly string[] | boolean;
  }`
  Import: `@aceshooting/lyra-ui/components/layout/filter-bar/filter-bar.class.js`.
  `LyraFilterBarTextDefinition extends LyraFilterBarClearableDefinitionBase {
    readonly type: 'text';
    readonly debounce?: number;
    readonly inputType?: LyraInputType;
    // Inherited from LyraFilterBarClearableDefinitionBase.
    readonly clearable?: boolean;
    // Inherited from LyraFilterBarComposedDefinitionBase.
    readonly size?: LyraSize;
    readonly icon?: unknown;
    readonly labelVisibility?: LyraFilterBarLabelVisibility;
    // Inherited from LyraFilterBarDefinitionBase.
    readonly filterId: string;
    readonly label: string;
    readonly placeholder?: string;
    readonly required?: boolean;
    readonly defaultValue?: string | readonly string[] | boolean;
  }`
  Import: `@aceshooting/lyra-ui/components/layout/filter-bar/filter-bar.class.js`.
  `LyraFilterBarValidityDetail {
    readonly valid: boolean;
    readonly invalidFilterIds: readonly string[];
  }`

- **`components-layout-menu-menu-item-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/layout/menu/menu-item.class.js`.
  `MenuItemChangeDetail {
    value: string;
    checked: boolean;
  }`
  Import: `@aceshooting/lyra-ui/components/layout/menu/menu-item.class.js`.
  `MenuItemStateChangeDetail {
    disabled: boolean;
    hidden: boolean;
    inert: boolean;
  }`

- **`components-layout-menu-menu-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/layout/menu/menu.class.js`.
  `MenuItemSelectDetail {
    readonly item: LyraMenuItem;
  }`

- **`components-layout-multi-split-multi-split-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/layout/multi-split/multi-split.class.js`.
  `LyraMultiSplitCollapseChangeDetail {
    readonly state: LyraMultiSplitCollapseState;
  }`
  Import: `@aceshooting/lyra-ui/components/layout/multi-split/multi-split.class.js`.
  `LyraMultiSplitToggleDetail {
    readonly open: boolean;
  }`
  Import: `@aceshooting/lyra-ui/components/layout/multi-split/multi-split.class.js`.
  `LyraMultiSplitConstraintIssueDetail {
    readonly reason: LyraMultiSplitConstraintIssueReason;
    readonly panelCount: number;
    readonly minimumTotal: number;
    readonly maximumTotal: number | null;
    readonly containerSize: number;
  }`
  Import: `@aceshooting/lyra-ui/components/layout/multi-split/multi-split.class.js`.
  `LyraMultiSplitOrientationChangeDetail {
    readonly orientation: LyraOrientation;
  }`
  Import: `@aceshooting/lyra-ui/components/layout/multi-split/multi-split.class.js`.
  `LyraMultiSplitPanelConstraint {
    readonly minPx?: number;
    readonly maxPx?: number;
    readonly minPercent?: number;
    readonly maxPercent?: number;
  }`
  Import: `@aceshooting/lyra-ui/components/layout/multi-split/multi-split.class.js`.
  `LyraMultiSplitResizeDetail {
    readonly sizes: readonly number[];
  }`

- **`components-layout-reorder-list-reorder-list-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/layout/reorder-list/reorder-list.class.js`.
  `LyraReorderDetail {
    readonly order: readonly string[];
    readonly fromIndex: number;
    readonly toIndex: number;
  }`

- **`components-layout-responsive-panel-responsive-panel-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/layout/responsive-panel/responsive-panel.class.js`.
  `LyraResponsivePanelModeChangeDetail {
    mode: LyraResponsivePanelEffectiveMode;
  }`
  Import: `@aceshooting/lyra-ui/components/layout/responsive-panel/responsive-panel.class.js`.
  `resolveResponsivePanelEffectiveMode(mode: LyraResponsivePanelMode, belowBreakpoint: boolean): LyraResponsivePanelEffectiveMode`

- **`components-layout-segmented-segmented-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/layout/segmented/segmented.class.js`.
  `LyraSegmentedItem {
    value: string;
    label: string;
    icon?: unknown;
    disabled?: boolean;
  }`

- **`components-layout-split-panel-split-panel-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/layout/split-panel/split-panel.class.js`.
  `SNAP_NONE(options: { pos: number; size: number; snapThreshold: number; }): number`
  Import: `@aceshooting/lyra-ui/components/layout/split-panel/split-panel.class.js`.
  `LyraSplitPanelSnapFunctionParams {
    pos: number;
    size: number;
    snapThreshold: number;
  }`
  Import: `@aceshooting/lyra-ui/components/layout/split-panel/split-panel.class.js`.
  `LyraSplitPanelRepositionDetail {
    position: number;
    positionInPixels: number;
  }`

- **`components-layout-stepper-stepper-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/layout/stepper/stepper.class.js`.
  `LyraStepItem {
    stepId: string;
    label: string;
    state: LyraStepState;
    disabled?: boolean;
    title?: string;
    icon?: unknown;
  }`
  Import: `@aceshooting/lyra-ui/components/layout/stepper/stepper.class.js`.
  `LyraStepperOrientationChangeDetail {
    orientation: LyraOrientation;
  }`

- **`components-layout-virtual-list-virtual-list-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/layout/virtual-list/virtual-list.class.js`.
  `LyraVirtualListGroup {
    key: string | number;
    label?: string;
    startIndex: number;
  }`
  Import: `@aceshooting/lyra-ui/components/layout/virtual-list/virtual-list.class.js`.
  `LyraVirtualListIndexedSource<T = unknown> {
    readonly count: number;
    itemAt(index: number): T;
    keyAt?(index: number): string | number;
    indexOfKey?(key: string | number): number;
  }`
  Import: `@aceshooting/lyra-ui/components/layout/virtual-list/virtual-list.class.js`.
  `LyraVirtualListRange {
    start: number;
    end: number;
  }`
  Import: `@aceshooting/lyra-ui/components/layout/virtual-list/virtual-list.class.js`.
  `LyraVirtualListScroll {
    scrollTop: number;
    viewportHeight: number;
  }`

- **`components-layout-widget-widget-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/layout/widget/widget.class.js`.
  `LyraWidgetView {
    viewId: string;
    label?: string;
    icon?: unknown;
    ariaLabel?: string;
  }`

# Overlays, status & feedback (`components/overlays/`)

## Breaking changes in 10.0.0

**Breaking (event rename, v10):** `lr-dialog`'s close event is now spelled `lr-close`, and
`lr-dialog-close` is removed; `lr-drawer`, which inherits the whole dialog lifecycle, loses it too.
The detail (`DialogCloseReason`), the cancelability, and the position in the `lr-hide` → close →
`lr-after-hide` sequence are all unchanged — only the name moved, onto the plain spelling
`lr-tool-select-dialog` and the rest of the library already use. The old name is removed outright
rather than dual-emitted, because the library has no released consumers and an alias is a permanent
tax paid to protect users who do not exist. Rename the listener. **Breaking (default change, v10):**
`lr-progress-ring` gains `showValue`/`show-value`, defaulting to `false`, so a determinate ring no
longer renders its percentage unless asked. It used to render it unconditionally with no way to
suppress it short of slotting replacement content, while sibling `lr-progress-bar` has had an opt-in
`show-value` all along and this reference has always claimed the two share the same value contract;
they now actually do. Add `show-value` to keep the percentage. The accessible value is unchanged
either way — `aria-valuetext` still carries the locale-formatted percentage — and slotted replacement
content still projects with or without the attribute. **Breaking (removal, v10):** `confirm()`'s
deprecated `tone` option is removed from `ConfirmOptions`; use `variant` (same `'neutral' | 'danger'`
values, same `'neutral'` default). It was documented as a one-major back-compat alias and `variant`
already won whenever both were set, so only a caller passing `tone` alone is affected. **New,
additive, non-breaking:** `lr-popover` gains `disabled` — both `lr-tooltip` and `lr-popover`'s own
subclass `lr-dropdown` had it and the base did not; `lr-dropdown` now inherits it with byte-identical
behavior.

Also corrected in 10.0.0 — not breaking, but visible. `lr-alert` really hides a base that is queued
behind the visible toast window (it renders that base `hidden` and `inert`; `inert` is
platform-enforced, but `hidden` was doing nothing), and `lr-badge` and `lr-chip` honor a consumer's
`hidden` slotted adornment. In each case the component's own author-origin `display` declaration was
beating the UA stylesheet's `[hidden] { display: none }` regardless of specificity.

## Breaking changes in 9.0.0

**Breaking (type-only, v9):** `lr-toast`'s exported `ToastPlacement`, `ToastCreateOptions`, and
`ToastOverflowDetail` are renamed to `LyraToastPlacement`, `LyraToastCreateOptions`, and
`LyraToastOverflowDetail`; `lr-toast-item`'s exported `ToastVariant` and `ToastSize` are renamed to
`LyraToastVariant` and `LyraToastSize`. Update any `import type { ToastPlacement, ... }` to the
`Lyra*`-prefixed names — no runtime/markup change, TypeScript imports only. **Breaking (type-only,
v9):** `lr-progress-bar`'s exported `ProgressVariant` is renamed to `LyraProgressVariant`. **Breaking
(removal, v9):** the deprecated `ToastOptions` alias of `LyraToastOptions`, exported from the
`toast()` helper module, is removed — it was Lyra's own convenience-API type, not a `wa-toast` DOM
member, so no upstream mirror is affected; use `LyraToastOptions` (unchanged, was already the
canonical name). **Breaking (type-only, v9):** `lr-skeleton`'s exported `SkeletonEffect` is renamed to
`LyraSkeletonEffect`. **Breaking (type-only, v9):** `lr-spinner`'s exported `SpinnerLabelPlacement` is
renamed to `LyraSpinnerLabelPlacement`. **New, additive, non-breaking:** `lr-progress-ring` gains a
`variant` property/attribute (`LyraProgressVariant`, default `'brand'`, reflected), matching sibling
`lr-progress-bar`'s semantic-palette vocabulary (`neutral`/`brand`/`success`/`warning`/`danger`), plus
a new `--lr-progress-ring-indicator-variant-color` CSS custom property (palette slot, same override
precedence as `lr-progress-bar`'s `--lr-progress-indicator-variant-color`).

## The shared overlay lifecycle

`lr-dialog`, `lr-drawer`, `lr-popover`, `lr-dropdown` and `lr-tooltip` all open and close over the
page, and as of 8.0.0 they do it through one contract. Each component's own section below documents
what it _adds_ to that contract, not a private variant of it.

**One way to open, one way to close.** All five expose `show()`, `hide()` and a reflected `open`
boolean, and all three drive the same code path: `el.show()` is indistinguishable from
`el.open = true`, and `el.hide()` from `el.open = false`. The property, the reflected attribute and
the two methods can therefore never disagree, and each method is a no-op when the overlay is already
in the requested state. `lr-dialog` and `lr-drawer` keep `close(reason)` alongside — `hide()` plus
the reason string that `lr-close` carries.

**Four events, and where the veto sits.**

| Event           | Cancelable | Fires                                              |
| --------------- | ---------- | -------------------------------------------------- |
| `lr-show`       | yes        | before the overlay opens                           |
| `lr-after-show` | no         | once the enter animation has finished              |
| `lr-hide`       | yes        | before the overlay closes, on every dismissal path |
| `lr-after-hide` | no         | once the exit animation has finished               |

> **These four names are not overlay-instance-scoped — filter by target.** Overlay-family
> descendants emit the same bubbling, composed lifecycle events, so a listener on an
> `<lr-dialog>` also receives (for example) a nested popover's or tooltip's event. This applies to
> both pre-events and both `lr-after-*` events. When the handler is intended only for the element
> it is attached to, start with `if (event.target !== event.currentTarget) return;`.

Both pre-events fire **before** the state changes, so `el.open` read inside an `lr-show`/`lr-hide`
handler is still the _old_ value, and `preventDefault()` cancels the transition rather than undoing
it: a vetoed `lr-show` leaves the overlay closed for the trigger interaction, `show()` and
`open = true` alike; a vetoed `lr-hide` leaves it open for Escape, light dismiss, the close button,
`hide()` and `open = false` alike. The two `lr-after-*` events are never cancelable, and none of the
four fires for markup that renders open from the start. The generic popover/dropdown/tooltip events
carry no detail; dialog/drawer `lr-hide` carries `{ source: Element }`. That is the
timing `wa-show`/`wa-hide` always had, so a mechanical `wa-*` → `lr-*` rename now maps all four names
with matching timing _and_ matching cancelability — which also means Lyra 7.x code that read
`el.open` inside an `lr-show`/`lr-hide` handler, or treated the pair as purely informational, was
relying on the opposite polarity and has to be re-read.

`lr-dialog` and `lr-drawer` also expose cancelable `lr-initial-focus` and `lr-request-close` veto
points, documented in their sections. Their cancelable `lr-close` fires **after** `lr-hide` and
before `lr-after-hide`; it carries the close reason as `detail: DialogCloseReason`. Vetoing
`lr-hide` stops it from firing at all, and `preventDefault()` on `lr-close` itself also vetoes the
close. The same name is already used by the `lr-tool-select-dialog`/`lr-tool-result-dialog`/
`lr-tool-approval-dialog` trio, which mirrors this identical detail shape, so one listener covers
all of them. `lr-drawer` inherits `lr-close` unchanged.

> **`lr-close` is not a dialog-scoped name — filter by target.** Nine components in this library
> emit `lr-close`, several of them commonly nested *inside* a dialog: `<lr-callout>` (an inline
> notice above a form), `<lr-tab>`/`<lr-tab-group>`, `<lr-command-palette>`,
> `<lr-document-viewer>`, `<lr-responsive-panel>`, and the three tool dialogs. Library events bubble
> and are composed, so a listener bound directly on `<lr-dialog>` **also receives a descendant's
> close** — a closable callout inside a dialog would otherwise dismiss the whole dialog. The details
> differ too (`<lr-callout>` and `<lr-tab>` carry none, where the dialog carries a
> `DialogCloseReason`), so a handler reading `event.detail.reason` throws on a foreign one. It is
> latent rather than broken-on-arrival, because a callout or tab only emits once it is given a close
> affordance — which is what makes it a bad failure mode: it shows up later and presents as the
> dialog dismissing itself. Guard on the target, the way `<lr-document-viewer>` already does
> internally:
>
> ```js
> dialog.addEventListener('lr-close', (event) => {
>   if (event.target !== event.currentTarget) return; // a descendant's close, not this dialog's
>   // ...
> });
> ```

**The top layer.** An open `lr-dialog` or modal `lr-drawer` is promoted into the browser **top layer**
(through `popover="manual"`) rather than stacked with `z-index`. It therefore escapes every ancestor
stacking context and every ancestor `overflow` clip: a `transform`ed parent, an `isolation: isolate`
wrapper or a `z-index: 2147483647` sticky header can no longer paint over it or crop it, which no
`z-index` value alone can guarantee. If you raised `--lr-layer-modal` to win one of those fights,
that override no longer decides anything for their modal instances and can be dropped — the token
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, and go on stacking at `--lr-overlay-stack-index`, falling back to `--lr-layer-popover`.

**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`,
modal `lr-drawer`) prefers the first focusable body control and otherwise focuses the panel itself,
so the default close button never wins merely because it appears first in shadow DOM. A non-modal
`lr-popover` or `lr-dropdown` deliberately leaves focus on the trigger.

**Arrows and external anchors.** `lr-popover`, `lr-dropdown`, `lr-tooltip` and the low-level
`lr-popup` share one anchoring vocabulary, all of it new in 8.0.0 (`lr-popup` itself is new in
8.0.0).

- `arrow` (boolean, reflected) renders an arrow pointing at the anchor, exposed as the `arrow` CSS
  part. It defaults to `true` on popover/tooltip and `false` on dropdown/popup; `without-arrow`
  suppresses the true-default surfaces. The part's attribute also carries the **resolved side** as
  a second token — `arrow-top`, `arrow-bottom`, `arrow-left`, `arrow-right` — so
  `::part(arrow arrow-top)` styles one side. `::part(arrow)[data-side]` and
  `::part(arrow) .inner` are invalid selectors that silently never match; the state is in the part
  name.
- `arrow-placement` (`anchor` | `start` | `end` | `center`, default `anchor`) — `anchor` tracks the
  anchor's centre, `center` pins the arrow to the middle of the popup's edge wherever the anchor is,
  and `start`/`end` pin it `arrow-padding` from one _logical_ end of that edge. On a top/bottom
  placement those two ends are the inline ones, so they swap under RTL; on a left/right placement
  they are the block ends, which do not.
- `arrow-padding` (number of px) keeps the arrow that far from the popup's corners. It defaults to
  `10` on the low-level popup and `0` on the three policy overlays.
- `--arrow-size` is the mapped size custom property and its value is **half** the square's width —
  the rendered arrow is twice it in both axes. Retained fallbacks are `--lr-overlay-arrow-size` on
  `lr-popover`/`lr-dropdown`, `--lr-tooltip-arrow-size` on `lr-tooltip`, and
  `--lr-popup-arrow-size` on `lr-popup`; they default to `var(--lr-size-0-375rem)`.
- `skidding` (number of px, default `0`) offsets the popup _along_ the anchor's edge — the
  cross-axis counterpart to `distance`.
- `for` (string, reflected) anchors the popup to an element it does not contain, by id. The id is
  resolved in the overlay's **own root**, so it works inside a shadow tree where a plain idref could
  not cross the boundary. On popover/tooltip, a slotted trigger wins interaction and ARIA ownership;
  only when no trigger is slotted does a live HTML `for` target own both. Direct `.anchor` is always
  positioning-only. A `showAt()` virtual anchor wins positioning and has no DOM interaction/ARIA
  owner while active.

---

## `lr-toast` / `lr-toast-item` / `toast()`

Stacking toast/notification region. Mirrors `<wa-toast>`/`<wa-toast-item>` under `lr-`.

### `lr-toast`

A placement-specific region. The imperative helper maintains one region for each
`ownerDocument` + `placement` pair; manually authored regions remain independent.

**Properties:**

- `placement: LyraToastPlacement = 'top-end'` (reflected) — one of `'top-start'|'top-center'|'top-end'|
'bottom-start'|'bottom-center'|'bottom-end'`. Every placement resolves inside one logical usable
  rectangle whose four edges are the greater of `--lr-space-l` and the matching safe-area token.
  Start/end follow direction, center placements use that rectangle's midpoint even when the inline
  safe-area insets are asymmetric, and an oversized stack is capped to its usable inline size.

**Methods:** `create(options: LyraToastOptions): Promise<LyraToastItem>` is the canonical form;
`create(message: string, options?: LyraToastCreateOptions)` remains as a compatibility overload.
`LyraToastOptions` contains `message`, optional `placement`, `ownerDocument`, `variant`, `duration`,
`size`, `withIcon`, `icon`, and `action`; `LyraToastCreateOptions` omits `message` and `placement`.
`icon` accepts text, a DOM node, a Lit template, or a target-document factory returning one of
those. Strings are always text, never HTML; cross-document nodes are imported into the region's
document. `action` creates a native button from `{ label, onClick }`. The options' `ownerDocument`,
and `placement`, when supplied directly to a region, must match that region. Calling `create()`
while the region is detached rejects immediately instead of leaving a render-dependent promise pending. `size` accepts
the canonical `2xs`/`xs`/`s`/`m`/`l`/`xl` values plus `small`/`medium`/`large`; either spelling is
preserved by the created item's getter and reflected attribute.

**Live members:** `stack: HTMLElement | null` returns the rendered `[part="stack"]` element, or
`null` before the render root is populated. Its identity remains stable across ordinary updates and
reconnection.

The region keeps exactly three items active. Later items enter a hidden, inert FIFO queue capped at
twenty; their show lifecycle and auto-dismiss timer do not start until promotion. Removing an active
item promotes the oldest queued item. A visible standalone item moved into a full region is
deactivated and timer-paused without replaying `lr-show`, then resumes from its remaining duration
when promoted; its progress ring resumes at the same elapsed fraction as that JavaScript countdown.
The visible stack is safe-area bounded and vertically scrollable, so all three active items and their
controls remain keyboard-reachable even with long localized content.

**Events:** `lr-toast-overflow` (noncancelable, `detail: { count: number }`) reports how many oldest
queued items were discarded when admission exceeded the twenty-item queue. Losses in one synchronous
burst coalesce into one event and one localized polite announcement; `create()` retains its existing
promise/result contract.

**Slots:** default (`<lr-toast-item>` children)

**CSS parts:** `stack`

**CSS custom states:** `visible` while at least one `lr-toast-item` is present in the region.

**Themeable custom properties:** `--lr-toast-gap` (default `var(--lr-space-s)`),
`--lr-toast-width` (default `var(--lr-size-28rem)`) — set directly on the `<lr-toast>` element.
The mapped `--gap` and `--width` names are compatibility aliases for those two Lyra-prefixed
properties; an explicitly set Lyra-prefixed property continues to take precedence.
Every `<lr-toast-item>` property below is also documented on the region, because custom properties
inherit into the items slotted inside it: one declaration on `<lr-toast>` retunes the whole stack.

**Optional peer deps:** none.

### `lr-toast-item`

A single notification.

**Properties:**

- `duration: number = 5000` (ms; `Infinity` or `<= 0` disables auto-dismiss)
- `size: '2xs'|'xs'|'s'|'m'|'l'|'xl'|'small'|'medium'|'large' = 'm'` (reflected — drives both `--lr-toast-padding` and the
  toast's own font-size through a private effective-size mapping, from a compact `2xs` up to a roomier `xl`;
  valid property and attribute writes round-trip without changing spelling)
- `variant: 'brand'|'success'|'warning'|'danger'|'neutral' = 'neutral'` (reflected)
- `withIcon: boolean = false` (attribute `with-icon`)

**Methods:** `async hide(): Promise<void>` — plays the hide animation, then removes itself from the
DOM. `toastItemElement: HTMLElement | null` exposes the live `[part="toast-item"]` surface (or
`null` before rendering) and remains the same node across ordinary updates/reconnection.

**Events:** `lr-show`, `lr-after-show`, `lr-hide`, `lr-after-hide`. `lr-show` and `lr-hide` are the
cancelable before-transition veto points. The item stays hidden and inert throughout `lr-show`;
vetoing its initial request releases it from the region without an after-event or timer. Re-entering
the same show/hide request from its own before-event coalesces onto that request, so the outer veto
remains authoritative and the lifecycle event fires once. Vetoing an auto-dismiss expiry leaves the
item visible and restarts the full current normalized `duration`; repeated vetoes retry at that same
interval. Vetoing a manual `hide()` leaves any active countdown at its current elapsed position. An
accepted show or hide interrupted by disconnection resumes after reconnection and emits its matching
`lr-after-*` event exactly once; no terminal event fires while the item is detached.

**Slots:** default (message), `icon`

**CSS parts:** `toast-item`, `accent`, `icon`, `content`, `close-button`, `close-icon`,
`close-icon__svg`, `progress-ring`, `progress-ring__base`, `progress-ring__indicator`,
`progress-ring__label`, `progress-ring__track`. The progress-ring tree is rendered for a finite,
positive auto-dismiss duration and surrounds the close glyph; its indicator pauses alongside the
auto-dismiss timer on hover or focus.

**Themeable custom properties:** `--lr-toast-accent-width` (default `var(--lr-size-4px)`),
`--lr-toast-show-duration`/`--lr-toast-hide-duration`
(`var(--lr-transition-base, 180ms ease-out)` — the show/hide lifecycle reads the resolved computed
transition duration and uses it for its completion fallback), `--lr-toast-padding`
(`var(--lr-space-m)`) and `--lr-toast-font-size` (`var(--lr-font-size-m)`) — their private defaults
follow `size`, from a compact `2xs` up to a roomier `xl` — and `--lr-toast-accent-color` (default
`var(--lr-color-border)`, with a private default that follows `variant` to that variant's loud
fill). Inherited or direct public values remain authoritative across every size and variant.

`--lr-toast-item-gap` (default `var(--lr-space-s)`) controls the gap between the item's icon,
message, and close action; `--lr-toast-item-radius` (default `var(--lr-radius)`) controls the item
surface and accent-bar start corners. They are deliberately separate from `--lr-toast-gap`, which
continues to control only the region's stack spacing.

The close button's four inherited state hooks are `--lr-toast-close-button-hover-bg` (default
`transparent`), `--lr-toast-close-button-hover-color` (default `var(--lr-color-text)`),
`--lr-toast-close-button-active-bg` (default `color-mix(in oklab, transparent,
var(--lr-color-mix-partner) var(--lr-color-mix-active))`), and
`--lr-toast-close-button-active-color` (default `var(--lr-color-text)`). Each is an inline fallback
at the relevant state, so setting one on the item or an ancestor rethemes only that close-button
state rather than the item surface, other close states, or the region stack.

The mapped names `--accent-width`, `--show-duration`, `--hide-duration`, and `--padding` alias their
respective Lyra-prefixed properties. Setting the Lyra-prefixed form explicitly wins over its alias.

**Optional peer deps:** none.

Once a non-vetoed toast starts showing, its normalized message is appended to Lyra's pre-mounted,
shared light-DOM announcement sink: assertive for `danger`/`warning`, polite otherwise. Changing a
visible toast between those urgency levels announces that message at the new urgency. The visible
item and stack themselves remain ordinary content, so an icon, action, and close button never become
part of an atomic live announcement. Auto-dismiss timer **pauses** on `pointerenter`/`focusin`, **resumes**
on `pointerleave`/`focusout`, with real elapsed-time bookkeeping (WCAG 2.2.1 timing-adjustable) —
hover and focus are tracked as independent pause reasons, so releasing only one (e.g. the pointer
leaves while focus remains, or vice versa) keeps the timer paused until _neither_ holds it anymore.
A `duration` change while the timer is actively counting down reschedules it immediately against
the new value instead of waiting for the next pause/resume cycle. A vetoed timer expiry restarts
that full normalized value; if hover/focus or a disconnect begins during the veto event, the retry
stays paused and starts from the full value only after the item resumes/reconnects.
Accessible message extraction follows same-root `aria-labelledby` references and observes their
targets, lookup roots, and every open shadow root actually traversed for text, including targets
outside the toast subtree. Traversal is bounded; when a ceiling is reached, the announcement carries
an explicit ellipsis and the close action uses the localized truncated-context template instead of
silently treating the bounded prefix as whole. If no prefix fits before a ceiling, both surfaces use
the localized `toastContentIncomplete` fallback so the missing content remains explicit.

### `toast()`

From the `toaster` controller — the ergonomic entry point, no manual `<lr-toast>` mounting
needed:

```ts
import { toast } from "@aceshooting/lyra-ui/components/overlays/toast/toaster.js";

toast("Saved");
toast({
  message: "Deleted",
  variant: "danger",
  icon: (ownerDocument) => ownerDocument.createTextNode("!"),
  action: {
    label: "Undo",
    onClick: (item) => {
      /*...*/
    },
  },
});
```

`toast(input: LyraToastOptions | string): ToastHandle`, where
`ToastHandle = { item: Promise<LyraToastItem>; dismiss: () => void }`. The canonical options are
shared byte-for-byte with the region's object-form `create()`, including `ownerDocument`, safe icon
payloads/factories, actions, and the long `small`/`medium`/`large` size aliases. It lazily mounts
(and re-mounts if removed) **one singleton `<lr-toast>` region per distinct `ownerDocument` and
`placement`** on that document's body — a call targeting one placement/document never relocates
toasts already showing in another. A foreign document must have the toast elements registered in
its own custom-element registry; otherwise the returned `item` promise rejects explicitly.

```html
<script type="module">
  import { toast } from "@aceshooting/lyra-ui/components/overlays/toast/toaster.js";
  document
    .getElementById("save-btn")
    .addEventListener("click", () => toast("Saved!"));
</script>
```

**Known gotchas:**

- the stack and each visible item have no live-region role. Their normalized message is appended as
  one child of a shared non-atomic light-DOM sink at the variant's urgency; icon, action, and close
  controls remain outside that sink. Later meaningful message changes add only the changed normalized
  message, and appending an action does not re-announce it.
- the close button's accessible name is derived from the toast's own message text (the first 40
  grapheme clusters when it must be shortened, falling back to bare `"Close"` only when the toast
  has no text content and extraction completed) rather than a bare `"Close"` on every instance — useful when several toasts
  are stacked and a screen-reader or switch-access user needs to tell their close buttons apart
  without activating one first. On a legacy engine without `Intl.Segmenter`, it retains the whole
  label rather than splitting a grapheme. The localized `closeWithTruncatedContext` template owns
  truncation punctuation and word order. Rich non-interactive message markup contributes its text,
  named-slot/icon and actionable content do not, and live message text mutations or reassignment
  update the name through nested forwarding slots. Hidden, inert, CSS-hidden and `aria-hidden`
  message branches are excluded. Same-root external `aria-labelledby` targets and the open shadow
  roots traversed for their text remain synchronized across reconnect, replacement, and adoption.
  A bounded traversal prefix is explicitly marked as incomplete; if no prefix is available, the
  localized `toastContentIncomplete` fallback keeps both the announcement and close name truthful.
  Observation, animation frames, elapsed-time clocks and completion/auto-dismiss timers follow the
  item's owner window after iframe adoption and cancel through the same window that scheduled them.
- pause/resume-on-hover/focus (the component's main accessibility differentiator), including the
  independent-hover-vs-focus pause reasons above, now has regression test coverage.
- `hide()` is idempotent (a second call while already hiding is a no-op) and `[part="close-button"]`
  gets `aria-disabled="true"` once hiding starts, so a stray extra click/Enter during the hide
  animation can't re-enter it. A disconnect during that animation pauses completion; reconnecting
  the same item resumes it and emits/removes exactly once.
- When the focused close/action control's toast finishes hiding, focus moves to an adjacent toast's
  close control, or back to the connected element that held focus before the toast when no adjacent
  item remains.
- Prefer the `toast()` helper over manually creating `<lr-toast>`/`<lr-toast-item>` — it already
  handles the singleton-region and remount-if-removed logic. The helper and `lr-alert.toast()` never
  fall back to an unbounded unknown region in an owner document where the controller is unregistered;
  unavailable alert requests are removed and their existing `Promise<void>` settles.

---

## `lr-empty`

First-party "no data" state (no Web Awesome equivalent).

Removing `heading` or `description` safely omits that text; explicit empty values remain empty and
later values restore the corresponding content.

**Properties:**

- `heading: string = ''`
- `headingLevel: LyraHeadingLevel = '3'` (attribute `heading-level`, reflected) — `1`–`6` expose
  either the string heading or rich `heading` slot at that semantic level; invalid untyped values
  retain level 3, while `none` keeps the visible text without heading semantics
- `description: string = ''`
- `compact: boolean = false` (reflected) — tighter, left-aligned rendering (less padding, a lighter
  heading weight) for use inside a constrained space like a widget body or table cell, instead of
  the centered/spacious full-page default
- `announce: boolean = false` (reflected) — announces the heading and description this empty state
  already carries when it first mounts, through the same shared light-DOM polite sink later changes
  use. Set it where the empty state replaces a result set the user just asked for; leave it unset
  for an empty state that is part of the page being loaded. See the first "Known gotchas" bullet

**Events:** none.

**Slots:** default (icon/illustration), `heading` (rich heading content, overrides the `heading`
attribute), `description` (rich description content, overrides the `description` attribute),
`actions` (buttons/links below the description)

**CSS parts:** `base`, `icon`, `heading`, `description`, `actions`

**Themeable custom properties:** `--lr-empty-compact-align` (compact mode only; defaults preserve
the existing `flex-start` cross-axis and `start` text alignment, and `center` centers both),
`--lr-empty-compact-padding` (default `--lr-space-xs` — padding used in compact mode),
`--lr-empty-compact-gap` (default `--lr-space-2xs` — gap between the icon, heading, and description
in compact mode; the non-compact layout's gap stays the plain shared `--lr-space-s` token, not
independently themeable), `--lr-empty-compact-font-size` (compact mode only; unset by default with
**no fallback value** — the compact heading keeps its ordinary inherited font size until a
consumer explicitly sets this token), plus shared tokens (`--lr-space-xs/-s/-l`,
`--lr-color-text-quiet/-border/-text`).

**Optional peer deps:** none.

```html
<lr-empty
  heading="No results"
  heading-level="2"
  description="Try a different search."
>
  <svg slot="" ...></svg>
  <!-- default slot: any icon/illustration -->
  <div slot="actions"><button>Clear filters</button></div>
</lr-empty>
<lr-empty
  compact
  heading="No results"
  description="Try a different search."
  style="--lr-empty-compact-align: center"
></lr-empty>
```

**Known gotchas:**

- Initial content and reconnect state—including property changes made while detached—stay silent
  unless `announce` is set, which announces the heading/description present at first mount once,
  through the same sink and the same exclusions as a later change. `announce` is read once, so a
  later reconnection or adoption stages the existing content again rather than replaying it.
  Later meaningful heading and description changes are appended to Lyra's shared light-DOM polite
  announcement sink. Default-slot illustrations, action-slot controls, nested hidden/inert/
  `aria-hidden="true"` content, updates under a hidden/CSS-hidden composed ancestor, and mutations
  that leave the accessible text unchanged are excluded;
  a `visibility:hidden|collapse` wrapper suppresses its own text but not a descendant that restores
  `visibility:visible`;
  nested forwarding slots contribute their flattened assigned heading/description text instead of
  fallback content, and later assignment plus assigned-node text/style/visibility changes are
  observed without turning initial distribution into a live update;
  a host `aria-label` names the host but does not replace that visible update text;
  the shadow `[part="base"]` remains ordinary visible content rather than a shadow-root live region.
  Remove any host `role="status"`/`role="alert"` hand-added before `announce` existed once it is
  set — otherwise the initial text is announced twice, through the native role and again through
  the shared sink.
- Note: correctly works around the classic `:empty`-pseudo-class trap (a wrapper with a `<slot>`
  inside can never match `:empty`) by tracking real flattened slot content in JS, including a bare
  non-whitespace text node such as an emoji as default icon content —
  `lr-table` reuses this component for its own empty-rows state, and `lr-stat` (below) now uses
  the same JS-tracked-slot-state pattern for its own icon/caption wrappers.

---

## `lr-skeleton`

Loading placeholder mirroring the Web Awesome/Shoelace skeleton surface under the `lr-` prefix,
with `text`/`circle`/`rect` geometry and opt-in `pulse`/`sheen` effects.

**Properties:**

- `shape: 'text'|'circle'|'rect' = 'text'` (reflected) — the canonical geometry vocabulary;
  exported as `LyraSkeletonShape`. The former `variant` property/attribute and `SkeletonVariant`
  type are removed in v9; use `shape` and `LyraSkeletonShape`.
- `effect: 'pulse'|'sheen'|'none' = 'none'` (not reflected; the live value is exposed as
  `data-effect` on `[part="base"]`) — animation is opt-in. **Changed in
  8.0.0:** the Lyra default was `pulse`; set `effect="pulse"` to preserve that motion explicitly.
- `width?: string`
- `height?: string`
- `label?: string` — accessible name used when `announce` is set (rendered as visually-hidden text
  inside `[part="base"]`). Only absence uses the localized loading default; every explicit caller
  value—including `label="Loading…"` and `label=""`—is preserved literally. Prefer a description
  of what's actually loading, e.g. `label="Loading chart"`.
- `announce: boolean = false` (reflected) — opt one meaningful placeholder into `role="status"`
  and localized hidden text. The false default preserves the decorative bare Web Awesome/Shoelace
  skeleton contract and prevents repeated placeholders from producing duplicate announcements.
  An author-supplied host role remains authoritative; the component adds and removes the status
  role only when it owns that opt-in role.

**Events:** none.

**Slots:** none.

**CSS parts:** `base` and `indicator` are aliases on the same placeholder/animation surface.

**Themeable custom properties:** `--lr-skeleton-w`, `--lr-skeleton-h` (set/cleared by the
`width`/`height` properties; defaults `100%` / `var(--lr-size-1em)`),
`--lr-skeleton-color` (default `var(--lr-color-border)`), `--lr-skeleton-sheen-color` (default
`var(--lr-color-surface)`), `--lr-skeleton-border-radius` (default `var(--lr-radius)` for text and
rectangle shapes); upstream `--color`, `--sheen-color`, and `--border-radius` feed those same
values. The shared `--lr-transition-ambient` (default `1.8s ease-in-out`) controls the pulse/sheen
timing.

**Optional peer deps:** none.

```html
<lr-skeleton
  shape="circle"
  effect="pulse"
  width="3rem"
  height="3rem"
></lr-skeleton>
<lr-skeleton
  announce
  shape="text"
  effect="sheen"
  label="Loading name"
></lr-skeleton>
```

**Known gotchas:**

- Bare skeletons are decorative. In a repeated layout, set `announce` only on one meaningful
  placeholder or provide one parent status; leave every other child unannounced.
- no `lines`/`count` shorthand for "N lines of skeleton text" — stamp out N elements
  yourself.
- Respects `prefers-reduced-motion` (both effects) — safe to leave as-is for that concern.

---

## `lr-drawer`

A modal panel anchored to one logical edge of the viewport. `LyraDrawer` extends `LyraDialog`, so it
inherits the entire dialog contract unchanged: focus trapping, Escape and opt-in backdrop dismissal,
document scroll locking, browser **top-layer** promotion, overlay stacking, accessible naming, the
`show()`/`hide()`/`close()` methods and the whole
`lr-show`/`lr-after-show`/`lr-hide`/`lr-after-hide`/`lr-close` lifecycle. `contained` switches
to an absolute, nonmodal panel inside the nearest containing block; only that mode, `placement`, and
the slide animation are its own.

**Properties:**

- `open: boolean = false` (attribute `open`, reflected) — assigning it runs the same lifecycle as
  `show()`/`hide()`, so the property, the reflected attribute and the two methods can never disagree
- `placement: 'start'|'end'|'top'|'bottom' = 'end'` (attribute `placement`, reflected). **Changed in
  8.0.0:** the default used to be `start`. `end` is what `wa-drawer` does, so a mechanical
  `wa-drawer` → `lr-drawer` rename no longer silently slides the panel in from the other edge.
- `contained: boolean = false` (attribute `contained`, reflected) — position within the nearest
  containing block without a backdrop, page inerting, focus trap, scroll lock, top-layer
  promotion, or global Escape ownership
- `heading?: string`, `label: string`, `accessibleLabel: string = ''` (attribute
  `accessible-label`), `closable: boolean = true`, `noHeader: boolean = false` (attribute
  `no-header`, Shoelace's spelling, reflected), `withoutHeader: boolean = false` (attribute
  `without-header`, Web Awesome's spelling, reflected; neither is deprecated),
  `withFooter: boolean = false` (attribute `with-footer`, reflected; SSR hint), and
  `lightDismiss: boolean = false` (attribute `light-dismiss`) — inherited dialog naming, chrome and
  dismissal options. A plain `aria-label` attribute on the host is honored too, inherited unchanged
  from `lr-dialog`: it is the strongest naming override, by attribute presence including an
  explicitly empty value, ahead of `accessible-label` and any slotted heading.
- `headingLevel: LyraHeadingLevel = '3'` (attribute `heading-level`, reflected) — semantic level of
  the generated title, from `1` through `6`, or `none` for visual-only title text. A direct slotted
  heading retains its own native level.
- `size: LyraSize = 'm'` (reflected) — inherited unchanged from `lr-dialog`; caps the panel's
  `max-inline-size` on the same six-step ladder for `start`/`end` placements (`top`/`bottom` are
  unaffected, since those axes are already unconditionally `100%`). At the `m` default the 32rem
  cap exceeds the panel's own 24rem default inline size, so it stays a no-op unless set. Distinct
  from the drawer-specific `--size` CSS custom property below, which maps to this same panel's own
  `inline-size`/`block-size` for the active axis.

**Methods:** `show(): Promise<void>`, `hide(): Promise<void>`,
`close(reason?: DialogCloseReason): Promise<void>` — inherited unchanged from `lr-dialog`; each
promise settles after the matching `lr-after-*` event.

**Events:** `lr-show` (cancelable), `lr-after-show`, `lr-hide` (cancelable), `lr-after-hide`, and
`lr-initial-focus` (cancelable), `lr-request-close` (cancelable, detail source), and `lr-close`
(`detail: DialogCloseReason`, cancelable) — all inherited unchanged from
`lr-dialog`; see that section for details and veto rules. `lr-after-show` /
`lr-after-hide` fire once the slide animation has finished, so they are deferred by roughly one
animation compared with the state flip. **`lr-close` is not drawer-scoped, same as on `lr-dialog`:**
several components nested inside a drawer (`lr-callout`, `lr-tab`/`lr-tab-group`, the tool dialogs,
and so on) emit the same bubbling, composed `lr-close` name, so a listener bound on `<lr-drawer>`
also receives a descendant's close. Guard with
`if (event.target !== event.currentTarget) return;` before reading `event.detail`, which those
descendants either omit or shape differently from `DialogCloseReason`.

**Animation registry:** the panel uses placement-specific names:
`drawer.showStart`/`drawer.hideStart`, `drawer.showEnd`/`drawer.hideEnd`,
`drawer.showTop`/`drawer.hideTop`, and `drawer.showBottom`/`drawer.hideBottom`. The backdrop uses
`drawer.overlay.show`/`drawer.overlay.hide`. Per-element overrides are RTL-aware through
`rtlKeyframes`; passing `null` disables interpolation while retaining the inherited event/promise
lifecycle.

**Slots:** default (drawer body), `label` (rich header content), `header-actions` (extra header
controls, rendered before the built-in close button), `footer` — all inherited from `lr-dialog`.

**CSS parts:** `base`; `backdrop overlay`; `panel dialog`; `header`; `heading title label`;
`header-actions`; `close-button close-button__base`; `close-button__control`; `body`; `footer`.
Names grouped together are aliases on the same functional node; `close-button__control` is the
composed `<lr-icon-button>`'s own native `<button>`, inherited from `lr-dialog` as of 16.0.0.

**Migrating a pre-16.0.0 `::part()` rule.** This component's icon-only action is a composed
`<lr-icon-button>`, so the part naming that action now names the composed child's HOST, which
paints nothing. A `border`, `background` or `border-radius` set on it is silently dead — only
`color` still appears to work, because it inherits, which makes such a rule look half-alive rather
than broken. Set `--lr-icon-button-background`/`-color`/`-border`/`-radius` (and their
`-hover`/`-active` variants) on this element or an ancestor instead: the composed control reads
those public tokens ahead of any default this component supplies. For SIZE use
`--lr-theme-icon-button-size`, not `--lr-icon-button-size` — every `LyraElement` re-declares the
latter on its own `:host`, so it never reaches a composed child (see `llms/tokens.md`).

**Themeable custom properties:** mapped `--size` controls the active axis. For start/end drawers,
the inherited `--width` and `--lr-dialog-width` remain compatibility fallbacks when neither
`--size` nor `--lr-drawer-width` is set, and `--lr-dialog-max-width` remains an effective cap,
falling back to the `size` property's own tier value (see Properties above) when unset.
The other mapped/inherited aliases are `--backdrop-filter`, `--spacing`, `--header-spacing`, `--body-spacing`,
`--footer-spacing`, `--show-duration`, and `--hide-duration`. Lyra compatibility tokens remain:
`--lr-drawer-width` (default `--lr-size-24rem`; used by
`placement="start"|"end"`, capped at `100%`), `--lr-drawer-height` (default `--lr-size-24rem`;
used by `placement="top"|"bottom"`), `--lr-drawer-enter-x` / `--lr-drawer-enter-y` (the panel's
slide translate offset, used for both the enter and the exit keyframes — `-x` for start/end, `-y`
for top/bottom; both default to `±var(--lr-size-1rem)` and are set per `placement`, with `-x`
explicitly flipped under `:dir(rtl)` since `translateX` is physical. Override to lengthen/shorten
the slide). It also inherits every `<lr-dialog>` token — `--lr-dialog-overlay-color`,
`--lr-dialog-backdrop-filter`, `--lr-dialog-width`, `--lr-dialog-max-width`, `--lr-dialog-spacing`,
`--lr-dialog-spacing-block`, `--lr-dialog-panel-duration` and `--lr-dialog-backdrop-duration` —
since `LyraDrawer` extends `LyraDialog`, including the shared overlay-surface family the panel
paints from: `--lr-overlay-surface`, `--lr-overlay-border`, `--lr-overlay-radius` and
`--lr-overlay-shadow-modal`. The drawer's own `[part~="panel"]` rule squares the corners and steps
the elevation down to `var(--lr-shadow-l)` — three of its edges are flush with the viewport — so on
this tag `--lr-overlay-radius` and `--lr-overlay-shadow-modal` are overridden and only the fill and
edge colour take effect. `--lr-dialog-height` is deliberately **not** among the
inherited tokens above: `<lr-drawer>`'s own `[part~="panel"]` rule unconditionally sets its own
`block-size` for every placement (`100%` for `start`/`end`, a `--lr-drawer-height`-driven `min()`
for `top`/`bottom`), which always wins the cascade over `<lr-dialog>`'s `--lr-dialog-height`-driven
rule regardless of value, so the property has no effect on `<lr-drawer>`. `<lr-drawer>` also opts
out of `<lr-dialog>`'s inherited `[part="body"]` growth: on `<lr-dialog>` that rule only fills the
panel once `--lr-dialog-height` is set (otherwise the panel is content-sized, so the rule is a
no-op); a drawer's panel is unconditionally a definite size for every placement, so without this
override `body` would always stretch and push `footer` to the panel's far edge. `<lr-drawer>`'s own
`[part="body"]` rule restores the natural content size instead, so `footer` follows immediately
after a short body exactly as it did before `--lr-dialog-height` existed. The drawer's own
size/width/height tokens take precedence
for its panel, and only the animation _name_ is overridden, so `--lr-dialog-panel-duration` retunes the
slide too and the reduced-motion flattening of the shared `--lr-duration-*` tokens still reaches it.

```html
<lr-drawer open placement="end" heading="Filters" closable>
  <button slot="header-actions" type="button">Reset</button>
  <lr-checkbox label="Only active"></lr-checkbox>
  <div slot="footer"><button type="button">Apply</button></div>
</lr-drawer>
```

---

## `lr-dialog` / `confirm()`

General-purpose modal/overlay plus a promise-based confirmation helper built on top of it.

Removing `label` safely omits its fallback title. Open dialog and drawer names follow supported name
and exclusion attribute changes on direct unslotted headings, while host naming retains precedence;
nested and `slot=""` headings remain outside automatic discovery.

### `lr-dialog`

A modal/overlay: `role="dialog"`, focus-trapped while open, dismissible via Escape or (opt-in) a
backdrop click, and scroll-locks the document for as long as it's open. Mapped chrome is present by
default: `label` renders as a visible title and `closable` renders a localized close button.
`closable="false"` plus either header-suppression spelling support custom chrome: `no-header` is
Shoelace's name and `without-header` is Web Awesome's. Both are current upstream spellings, both are
read, and neither is deprecated.

**Properties:**

- `open: boolean = false` (reflected) — **changed in 8.0.0:** `lr-dialog` now also has a
  `show()`/`hide()` pair, and assigning `open` runs exactly the same lifecycle as calling them, so
  the property, the reflected attribute and the two methods can never disagree. `el.open = false`
  therefore emits the full close lifecycle and can be vetoed, where it used to be a silent state
  flip. Markup that renders open from the start (`<lr-dialog open>`) emits nothing.
- `label: string = ''` — mapped visible title. The richer `label` slot wins over it.
- `headingLevel: LyraHeadingLevel = '3'` (attribute `heading-level`, reflected) — `1`–`6` expose
  the generated visible title (string property or rich `label` slot) at that semantic level;
  invalid untyped values retain level 3, while `none` keeps visual title text without heading
  semantics. A direct light-DOM heading retains its own native/ARIA level.
- `accessibleLabel: string = ''` (attribute `accessible-label`) — explicit accessible-only name;
  unlike `label`, it never renders visible text
- `heading?: string` — legacy visible-title fallback, after the `label` slot and `label` property;
  it has no effect when a direct light-DOM heading already supplies custom chrome
- `closable: boolean = true` (attribute `closable`, reflected) — renders the localized close (X)
  button. This true-default boolean parses `closable="false"`; removing the attribute also restores
  the default.
- `noHeader: boolean = false` (attribute `no-header`, reflected) — Shoelace's spelling
  (`sl-dialog`'s `no-header`), which suppresses the entire header row
- `withoutHeader: boolean = false` (attribute `without-header`, reflected) — **new in 8.0.0.**
  Web Awesome's spelling (`wa-dialog`'s `without-header`) for the same header suppression. Both
  names are current upstream spellings, both are read, and neither is deprecated or removable
- `withFooter: boolean = false` (attribute `with-footer`, reflected) — keeps the footer wrapper
  rendered as an SSR/hydration presence hint even before assigned slot content is observable
- `size: LyraSize = 'm'` (reflected) — `'2xs' | 'xs' | 's' | 'm' | 'l' | 'xl' | 'small' | 'medium' |
  'large'`. Panel-width tier, on the shared six-step ladder: `20rem` (`2xs`), `24rem` (`xs`), `28rem`
  (`s`/`small`), `32rem` (`m`/`medium`, unchanged from before this property existed), `38rem`
  (`l`/`large`), `48rem` (`xl`) — each value feeds `--lr-dialog-max-width`'s private default. An
  explicit `--lr-dialog-width`/`--lr-dialog-max-width` still wins over every tier.
- `lightDismiss: boolean = false` (attribute `light-dismiss`) — opt in to a backdrop click closing
  the dialog; Escape and explicit `close()`/`hide()` calls remain available. **Changed in 8.0.0:**
  this was previously spelled `no-light-dismiss`, an opt-_out_ whose default left backdrop dismissal
  on. The polarity now matches `wa-dialog` exactly, so a mechanical rename no longer flips what the
  markup does.
- `modal: LyraDialogModalController` (writable, property only) — `activateExternal()` temporarily
  yields focus/Escape ownership to a third-party modal; balanced `deactivateExternal()` resumes it
  without changing `open`

A plain host `aria-label` is the strongest naming override. It changes naming only: mapped title
chrome remains visible. The fallback order appears below.

**Methods:**

- `show(): Promise<void>` — opens the dialog and resolves after `lr-after-show`; no-op/veto returns
  an already-resolved promise
- `hide(): Promise<void>` — identical to `close('api')`, resolving after `lr-after-hide`
- `close(reason: DialogCloseReason = 'api'): Promise<void>` — closes the dialog, returns focus to
  whatever had it right before opening, and resolves after `lr-after-hide`.
  `DialogCloseReason = 'escape' | 'backdrop' | 'close-button' | 'api' | 'unmount' | string` —
  `'escape'`/`'backdrop'` are emitted by the dialog's own built-in dismiss triggers;
  `'close-button'` by the built-in header close button (rendered when `closable` is set); `'api'`
  covers `close()` with no argument, `hide()`, and `open = false`; `'unmount'` is emitted
  automatically if the dialog is removed from the DOM while still `open` by anything other than its
  own `close()` (a consumer's own cleanup code, a parent re-render that drops it); any other string
  is whatever a caller passes (e.g. a footer Cancel button calling `dlg.close('cancel')`, or
  `confirm()`'s own `'confirm'`/`'cancel'`).

**Events:**

- `lr-show` — cancelable pre-open veto
- `lr-after-show` — opening animation finished
- `lr-hide` — cancelable pre-close veto; detail is `{ source: Element }`, the host or built-in
  affordance that requested the transition
- `lr-after-hide` — closing animation finished
- `lr-initial-focus` — cancelable immediately before the first automatic focus movement. A
  CSS-hidden dialog defers it until rendered; reconnecting the same open activation does not repeat
  it.
- `lr-request-close` — cancelable request from a built-in affordance; detail source is
  `'close-button' | 'keyboard' | 'overlay'`. Veto stops the close lifecycle. Direct `close()` and
  `hide()` calls do not emit this request event.
- `lr-close` — cancelable, with `detail: DialogCloseReason`; emitted after `lr-hide`. The same name
  is already used by `<lr-tool-select-dialog>`, `<lr-tool-result-dialog>`, and
  `<lr-tool-approval-dialog>`, whose own docs describe an identical detail shape, so one listener
  covers all of them. A listener calling `preventDefault()` vetoes the close. Also fired (with
  reason `'unmount'`, non-cancelable there) when the dialog is removed from the DOM while still
  open. **But the name is not dialog-scoped.** Nine components in this library emit `lr-close`,
  several of them commonly nested *inside* a dialog: `<lr-callout>`, `<lr-tab>`/`<lr-tab-group>`,
  `<lr-command-palette>`, `<lr-document-viewer>`, `<lr-responsive-panel>`, and the three tool
  dialogs (`<lr-tool-select-dialog>`, `<lr-tool-result-dialog>`, `<lr-tool-approval-dialog>`).
  Library events bubble and are composed, so a listener bound directly on
  `<lr-dialog>` also receives a descendant's close — a closable callout or tab inside a dialog would
  otherwise dismiss the whole dialog. Guard on the target, the way `<lr-document-viewer>` already
  does internally:

  ```js
  dialog.addEventListener('lr-close', (event) => {
    if (event.target !== event.currentTarget) return; // a descendant's close, not this dialog's
    // ...
  });
  ```

The two `lr-after-*` events are never cancelable.

The open sequence is `lr-show` → `lr-initial-focus` (when focus would move) → `lr-after-show`; the
direct close sequence is `lr-hide` → `lr-close` → `lr-after-hide`.
A built-in dismissal prepends `lr-request-close`. **Both state pre-events fire _before_ the state changes**, so reading
`el.open` inside an `lr-show`/`lr-hide` handler returns the _old_ value — this is the polarity
`wa-show`/`wa-hide` already had, and the opposite of what Lyra 7.x's own `lr-show`/`lr-hide` did on
`lr-popover`/`lr-dropdown`. The `wa-*` → `lr-*` migration table treats the rename as mechanical, and
as of 8.0.0 that is finally true for these four names: `wa-show`/`wa-after-show`/`wa-hide`/
`wa-after-hide` map to `lr-show`/`lr-after-show`/`lr-hide`/`lr-after-hide` with matching timing and
matching cancelability. Code written against Lyra 7.x that read `el.open` in a handler, or assumed
the events were informational rather than vetoable, has to be re-read.

`lr-after-show`/`lr-after-hide` settle after the public registry animations `dialog.show` /
`dialog.hide` (panel) and `dialog.overlay.show` / `dialog.overlay.hide` (backdrop). Per-element
registrations win over page defaults; keyframes-only overrides retain the token-derived duration
and easing. Under `prefers-reduced-motion: reduce`, registry timing flattens to zero while the end
frame and lifecycle remain intact. Passing `null` skips native interpolation but still emits the
matching after-event before the method promise resolves. Because dialogs now animate on close too,
`lr-after-hide` is normally deferred by roughly one animation. A removal while open emits
`lr-hide`, `lr-close` (reason `'unmount'`) and `lr-after-hide` in that
order, none of them cancelable, since the element is already gone.

**Stacking and the top layer:** an open dialog is promoted into the browser **top layer** (via
`popover="manual"`), new in 8.0.0. That means it escapes every ancestor stacking context and every
ancestor `overflow` clip: a `transform`ed parent, an `isolation: isolate` wrapper or a
`z-index: 2147483647` sticky header can no longer render on top of it or crop it, which no `z-index`
value alone can guarantee. The `z-index` in the stylesheet remains only as the fallback for a user
agent without popover support, and `popover="manual"` is deliberate — light dismiss and Escape stay
this component's own contract rather than the user agent's, where an `auto` popover would close on
the user agent's terms instead. What a consumer sees: the host gains a `popover="manual"` attribute
while open (component-owned bookkeeping — don't set or remove it), any `z-index` you were fighting
with becomes irrelevant, and the panel is no longer clipped by an ancestor's `overflow: hidden`.
Beyond that, the dialog participates in the shared per-document overlay stack: only the topmost
overlay receives Escape, Tab trapping, or backdrop dismissal, while overlays beneath stay open until
the top one closes.

**Slots:** default (the dialog body), `label` (rich header content — an element, markup, anything;
rendered inside `[part="heading"]` and used as the panel's accessible name, winning over the
plain-string `label` and legacy `heading` properties), `header-actions` (extra header controls,
rendered in the header row _before_
the built-in close button), `footer` (action buttons, rendered in a bottom row, hidden entirely when
empty). The `label` and `header-actions` slots are new in 8.0.0.

**CSS parts:** `base`; `backdrop overlay`; `panel dialog`; `header`; `heading title label`;
`header-actions`; `close-button close-button__base`; `close-button__control`; `body`; `footer`.
Names grouped together are additive aliases on the same functional node, so a mapped
`::part(title)` rule styles the same visible title as Lyra's `::part(heading)`.
`close-button__control` is the composed `<lr-icon-button>`'s own native `<button>`: as of 16.0.0 the
close button IS an `<lr-icon-button>`, so `close-button`/`close-button__base` name that host and the
painted surface sits one boundary deeper. `<lr-drawer>` inherits this control and now registers
`<lr-icon-button>` itself.

**The body is keyboard-reachable while it overflows.** `[part="body"]` is the element that scrolls,
so it carries `tabindex="-1"` and joins the focus order **only while its content actually
overflows** — a dialog whose content is nothing but prose, a table, or a rendered document used to
be scrollable with a mouse and completely unreachable from the keyboard, because a scroll container
with no focusable child is not a stop of its own. A short body never becomes a gratuitous stop.

It takes focus like any other stop, so it styles like one: `::part(body):focus-visible` draws the
standard `--lr-focus-ring-*` ring, inset (`outline-offset` is negative) because the body is flush
with the panel edges, where an outset ring would be clipped or would collide with the header rule.
Restyle it through `::part(body)` as usual; do not remove the outline without replacing it.

It never steals initial focus from real content: an `[autofocus]` element wins, then the first
focusable control _inside_ the body, and the body itself is used only when there is nothing else to
focus. So a dialog full of form controls behaves exactly as before, and a dialog full of text is now
scrollable with the arrow keys, Page Up/Down and Home/End once Tab reaches it.

**Migrating a pre-16.0.0 `::part()` rule.** This component's icon-only action is a composed
`<lr-icon-button>`, so the part naming that action now names the composed child's HOST, which
paints nothing. A `border`, `background` or `border-radius` set on it is silently dead — only
`color` still appears to work, because it inherits, which makes such a rule look half-alive rather
than broken. Set `--lr-icon-button-background`/`-color`/`-border`/`-radius` (and their
`-hover`/`-active` variants) on this element or an ancestor instead: the composed control reads
those public tokens ahead of any default this component supplies. For SIZE use
`--lr-theme-icon-button-size`, not `--lr-icon-button-size` — every `LyraElement` re-declares the
latter on its own `:host`, so it never reaches a composed child (see `llms/tokens.md`).

**Border reaches the composed close control the same way background/color/radius do.** This
component paints no resting border of its own, so it relays no `--_lr-icon-button-border-default`
into the close control's private fallback tier — but that absence is not a gap. The public
`--lr-icon-button-border` (and its `-hover`/`-active` variants) is the FIRST arm of the token
chain, resolved by ordinary custom-property inheritance regardless of whether this component
relays a default for that same property, so setting it on this element or an ancestor reaches the
close control exactly as the background/color/radius tokens do. A component with no resting
border simply has no default to relay, which is different from border theming being broken. Size
remains the one exception that does not cross this way: use `--lr-theme-icon-button-size`, never
`--lr-icon-button-size`, as noted above.

**Themeable custom properties:** mapped aliases are `--backdrop-filter`, `--width`, `--spacing`,
`--header-spacing`, `--body-spacing`, `--footer-spacing`, `--show-duration`, and
`--hide-duration`. The individual region properties override `--spacing`; mapped properties in
turn fall back to the retained Lyra tokens: `--lr-dialog-overlay-color` (default
`var(--lr-color-overlay)` —
the backdrop scrim color), `--lr-dialog-backdrop-filter` (default `none` — a `backdrop-filter` on
the scrim, e.g. `blur(3px)`, for a frosted-glass treatment over the page behind it),
`--lr-dialog-width` (default `auto` — the panel shrink-wraps to content; set it for an assertive
width instead), `--lr-dialog-max-width` (default `var(--lr-dialog-width, var(--_lr-dialog-max-width))`
— the panel's max-inline-size cap, applied as
`min(var(--lr-dialog-max-width, var(--lr-dialog-width, var(--_lr-dialog-max-width))), 100%)`, where
the private `--_lr-dialog-max-width` is the `size` property's own tier value (`32rem` at the `m`
default, unchanged); when
`--lr-dialog-width` is set but `--lr-dialog-max-width` is left at its default, the cap falls back to
the requested width itself — not the tier default — so an assertive width isn't silently clipped;
the viewport is still a hard limit either way), `--lr-dialog-height` (default `auto` — the panel
shrink-wraps to content on the block axis, same as before this property existed; always capped at
`100%`, i.e. the viewport, like every other panel dimension). With it set, `[part="body"]`'s own
`flex: 1 1 auto` is what actually gives slotted content a definite, fillable block size:
`[part="header"]` and `[part="footer"]` keep their natural size and only `[part="body"]` grows or
shrinks into the remaining space, matching `--lr-dialog-width`'s pairing with `--lr-dialog-max-width`
on the other axis. `--lr-dialog-spacing` (default `var(--lr-space-l)` —
the padding inside `[part="body"]` and the _inline_ padding of the header and footer rows),
`--lr-dialog-spacing-block` (default `var(--lr-space-m)` — the _block_ padding of the header and
footer rows, which are tighter than the body by default), `--lr-dialog-panel-duration` (default
`var(--lr-duration-base)` — the panel's enter/exit animation duration) and
`--lr-dialog-backdrop-duration` (default `var(--lr-duration-fast)` — the backdrop's fade duration).
The panel paints from the **shared overlay-surface family** (16.0.0), not from the page-surface
tokens this entry previously named: `--lr-overlay-surface` (default `var(--lr-color-surface-overlay)`
— the panel fill), `--lr-overlay-border` (default `var(--lr-color-border)` — the panel edge and the
header's and footer's dividing rules), `--lr-overlay-radius` (default `var(--lr-radius)` — the panel
corner and the close button's) and `--lr-overlay-shadow-modal` (default `var(--lr-shadow-xl)` — the
panel's elevation). None is declared on `:host`, so one declaration on `:root` (or on any ancestor,
to scope it) retints the dialog together with every popup opened from it. The modal tier is a
separate name from `--lr-overlay-shadow-anchored`, which anchored popups read, so raising popups
never raises dialogs.

Otherwise the shared tokens the panel and its chrome read include the `--lr-size-20rem` /
`-24rem` / `-28rem` / `-32rem` / `-38rem` / `-48rem` width ladder behind `size`, `--lr-space-l`,
`--lr-space-m`, `--lr-space-s` and `--lr-space-xs` (spacing defaults), the `--lr-safe-area-*` insets
on the fixed frame, `--lr-color-overlay` (the scrim default), `--lr-color-text-quiet`,
`--lr-color-brand` and `--lr-color-brand-quiet` with `--lr-color-mix-partner`/`--lr-color-mix-active`
(the close button's foreground and its hover/pressed fills), `--lr-border-width-thin`,
`--lr-icon-button-size` (the close button's hit-area floor), `--lr-focus-ring-width`,
`--lr-focus-ring-color`, `--lr-focus-ring-offset`, `--lr-font-weight-semibold`,
`--lr-transition-fast`, and `--lr-layer-modal` behind `--lr-overlay-stack-index`. Earlier revisions
of this entry instead named `--lr-color-surface`, a bare `--lr-shadow` and `--lr-easing-standard`:
none of the three has ever been part of a declaration in `dialog.styles.ts`, and the panel's real
fill and elevation are the overlay-family tokens above, eased through `--lr-transition-fast` (itself
derived from `--lr-duration-fast` and `--lr-easing-standard`, which is where that last name came
from).

**Optional peer deps:** none.

```html
<lr-dialog id="dlg" heading-level="2" closable>
  <span slot="label">Delete item?</span>
  <button slot="header-actions" type="button">Help</button>
  <p>This cannot be undone.</p>
  <div slot="footer">
    <button id="cancel" type="button">Cancel</button>
    <button id="confirm" type="button">Delete</button>
  </div>
</lr-dialog>
<script type="module">
  import "@aceshooting/lyra-ui/components/overlays/dialog/dialog.js";

  const dlg = document.getElementById("dlg");
  // Listeners first: `lr-show` is emitted synchronously inside show().
  dlg.addEventListener("lr-show", () =>
    console.log("opening; el.open is still", dlg.open)
  );
  dlg.addEventListener("lr-after-show", () =>
    console.log("enter animation done")
  );
  dlg.addEventListener("lr-close", (e) =>
    console.log("closed:", e.detail)
  );
  dlg.addEventListener("lr-after-hide", () =>
    console.log("exit animation done")
  );
  document
    .getElementById("cancel")
    .addEventListener("click", () => dlg.close("cancel"));
  await dlg.show(); // identical state change to dlg.open = true; settles after lr-after-show
</script>
```

A dialog with no chrome of Lyra's own, animating faster and blurring the page behind it:

```html
<lr-dialog
  without-header
  accessible-label="Preview"
  light-dismiss
  style="--lr-dialog-backdrop-filter: blur(4px); --lr-dialog-panel-duration: 120ms;
         --lr-dialog-backdrop-duration: 80ms; --lr-dialog-spacing: 0"
>
  <img src="/poster.jpg" alt="Poster" />
</lr-dialog>
```

Accessible naming and visible title are separate. Naming precedence is: (1) host `aria-label`, by
attribute presence including an explicitly empty value, (2) `accessible-label`, (3) the copied text
of an unslotted direct light-DOM heading, then (4) the shadow-owned visible title wrapper.
Visible-title precedence is the rich `label` slot, then the mapped `label` property, then legacy
`heading`. The direct-heading case copies text because an IDREF cannot cross from the panel's shadow
tree to a light-DOM heading; the mapped title wrapper can use `aria-labelledby` because it lives in
the same shadow root. `no-header`/`without-header` removes the mapped title, so custom-chrome dialogs
should provide a direct heading, `accessible-label`, or host `aria-label`.

**Known gotchas:**

- `role="dialog"`/`aria-modal="true"` are only present on `[part="panel"]` while `open` is `true` —
  inspecting closed markup won't show them.
- An `[autofocus]` element anywhere in the slotted content takes initial focus instead of the first
  focusable element, including one inside a slotted custom element's own open shadow root — so
  `<lr-input autofocus>` behaves like `<input autofocus>`. With nothing marked, the first focusable
  element still wins, unchanged.
- `lr-initial-focus` is the veto point for Lyra's automatic focus move. It fires once per logical
  open, only when the rendered panel is ready to receive focus; canceling it does not disable the
  trap or later focus return.
- The host gains a `popover="manual"` attribute the first time it opens and keeps it from then on —
  only top-layer membership (`:popover-open`) tracks `open`, not the attribute — and carries
  `data-closing` for exactly as long as the exit animation runs (pointer events are dead for that
  window, so a dismissing dialog can't swallow a click meant for the page underneath). Both are
  component-owned bookkeeping — don't set or remove them.
- Heading detection observes child, subtree, and character-data changes, so mutating an
  already-slotted direct heading's text updates the copied panel `aria-label` live.
- Only _unslotted direct_ children are scanned for a heading — one nested several layers deep,
  inside a slotted custom element's own shadow root, or carrying a `slot` attribute, is left to the
  consumer to label explicitly via `label` or the `label` slot.
- A reconnect that preserves the same element instance (e.g. a drag-and-drop reparent) resumes its
  shared overlay registration and re-acquires the scroll lock if `open` was still `true` across the
  move — `disconnectedCallback`/`connectedCallback` fire back-to-back with no update in between, so
  `willUpdate()` alone wouldn't otherwise notice.
- Tab-trap focus order follows the default (body) slot, then the `footer` slot — the same order the
  flattened tree already tabs through — and is resolved shadow-piercingly, so a slotted custom
  element's real focusable target inside its own shadow root is found even though the host tag
  itself isn't a native focusable element.

### `confirm()`

A drop-in async replacement for `window.confirm()`, built on `<lr-dialog>`.

```ts
import { confirm } from "@aceshooting/lyra-ui/components/overlays/dialog/confirm.js";

const ok = await confirm({
  title: "Delete conversation?",
  description: "This cannot be undone.",
  confirmLabel: "Delete",
  variant: "danger",
});
if (ok) deleteConversation();
```

`confirm(options: ConfirmOptions): Promise<boolean>` where
`ConfirmOptions = { title: string; description?: string; confirmLabel?: string /* = 'Confirm' */; cancelLabel?: string /* = 'Cancel' */; variant?: 'neutral' | 'danger' /* = 'neutral' */ }`.

Resolves `true` only when the confirm button is pressed — Escape, a backdrop click, and the cancel
button all resolve `false`. It sets `lightDismiss = true` on its transient dialog explicitly, so the
backdrop-click branch survives 8.0.0's flip of that property's own default to `false`. Mounts a
transient `<lr-dialog>` on `document.body` for the duration
of the call and removes it once settled, rather than reusing a persistent page-level region
(contrast `lr-toast`'s `toaster.ts`). Concurrent calls are distinct dialogs in the shared overlay
stack, each tied to its own returned promise. `title` becomes a direct light-DOM `<h2>`, which per `<lr-dialog>`'s
own heading-detection also drives the dialog's accessible name; `description`, if provided, becomes
a direct light-DOM `<p>`. `variant: 'danger'` fills the confirm button with `--lr-color-danger`
instead of `--lr-color-brand`, for destructive actions. The deprecated `tone` option that preceded
`variant` was removed in 10.0.0. Confirm/cancel actions deliberately use native
inline-styled `<button>` elements so this helper does not register or import the broader button
component; every color value is still a `--lr-*` token reference, never a raw literal. They carry the same interaction
states as every other control in the library: a hover/pressed fill mixed toward
`--lr-color-mix-partner` by `--lr-color-mix-hover`/`--lr-color-mix-active`, and a
`--lr-focus-ring-width`/`--lr-focus-ring-color`/`--lr-focus-ring-offset` `:focus-visible` ring. An
inline `style` attribute cannot express a pseudo-class, so those rules ship in a small `<style>`
element mounted inside the transient dialog (and removed with it), targeting the buttons through
their `data-lr-confirm-action` attribute.

**Known gotchas:**

- Every dismissal path (confirm button, cancel button, Escape, backdrop click) funnels through
  `<lr-dialog>`'s own `close()`/`lr-close` event, so there is exactly one place that
  resolves the promise and tears the dialog down — a consumer never needs to (and shouldn't) call
  `.remove()` itself. Because the close event is cancelable, `confirm()` waits through the full
  dispatch and remains pending/mounted when a listener calls `preventDefault()`.
- The neutral confirm button pairs `--lr-color-on-brand` with `--lr-color-brand`; the danger
  variant pairs `--lr-color-on-danger` with `--lr-color-danger`. Each of those resolves through its
  variant's row of the semantic grid (`--lr-color-<variant>-fill-loud` /
  `--lr-color-<variant>-on-loud`), which in turn reads the matching `--lr-theme-color-*` hook and
  falls back to the shared neutral ramp — so retheming the grid retints the confirm button with no
  `::part()` rule, in light and dark alike.
- Importing `confirm` is side-effect free and does not register `<lr-dialog>`. Invoking the helper
  synchronously registers exactly the dialog class it creates before mounting the transient
  element; consumers do not need a separate registration import for helper-created dialogs.

---

## `lr-chip` / `lr-chip-group`

A small, content-agnostic surface for a short label: a tag, an active-filter/scope indicator, etc.
Distinct from `<lr-attachment-chip>` (specifically file-shaped, with a thumbnail/size/upload-
progress) — this pair carries no domain assumptions at all. `<lr-chip>` is a controlled component:
clicking its remove (×) button only fires `lr-remove` — the chip never removes itself from the DOM
on its own interaction, the same contract `<lr-attachment-chip>`/`<lr-conversation-item>`
already follow.

Collapsed groups reapply `max-visible` when assigned children are replaced or reordered at the same
count, preserving authored hidden/inert state and releasing departed visibility leases.

**Two breaks in 8.0.0.** `tone` is now `variant`, with no alias — one concept, one spelling,
library-wide. And a chip is **no longer a pill by default**: `--lr-chip-radius` used to be
`var(--lr-radius-pill)` unconditionally, is now `var(--lr-radius)` (a rounded rectangle), and the
fully-rounded treatment moved behind the new opt-in `pill` boolean. Existing markup keeps its corner
radius only if you add `pill`, or set `--lr-chip-radius: var(--lr-radius-pill)` once at the app
level. `<lr-badge>`/`<lr-tag>` made the identical shape change, with the identical `pill` opt-in.

**Two breaks in 9.0.0.** The chip's leading adornment slot and CSS part are now `start`, matching
the library-wide adornment vocabulary; migrate `slot="icon"` to `slot="start"` and
`::part(icon)` to `::part(start)`. Also, `toggleable` is now the sole toggle-mode opt-in:
`selected` represents only current pressed state, so add `toggleable` anywhere that previously
relied on `<lr-chip selected>` to create an action.

### `lr-chip`

**Properties:**

- `size: '3xs' | '2xs' | 'xs' | 's' | 'm' | 'l' | 'xl' | 'small' | 'medium' | 'large' = 'm'`
  (reflected) — standard visual-density scale for typography, padding, gap, and icon size; `m`
  preserves the original chip dimensions. The `small`/`medium`/`large` spellings are exact aliases
  of `s`/`m`/`l` and round-trip unchanged. Unsupported attributes and untyped property writes
  normalize to reflected `m`.
- `variant: 'neutral' | 'brand' | 'success' | 'warning' | 'danger' = 'neutral'` (reflected) —
  **renamed from `tone` in 8.0.0, with no alias** (see above). `<lr-badge>`, `<lr-callout>` and
  `<lr-toast-item>` all already spelled it `variant`. It tints the whole surface using the
  loud-color-on-quiet-tint convention: background is the
  variant's quiet fill, text/icon its loud fill, both read from the shared semantic grid. `neutral`
  deliberately opts out of that grid and falls back to a plain bordered-surface look. Unsupported
  attributes and untyped property writes normalize to reflected `neutral`.
- `removable: boolean = false` (reflected — shows the remove (×) button)
- `disabled: boolean = false` (reflected) — disables the active native toggle/remove control,
  blocks focus and activation, and suppresses selection/removal requests without mutating state
- `pill: boolean = false` (reflected) — **new in 8.0.0.** Fully-rounded ends instead of the default
  rounded rectangle; the same property `<lr-badge>`/`<lr-tag>` carry. Since it defaults to `false`,
  `pill="false"` is not a way to switch it off — remove the attribute, or assign `.pill = false`.
- `selected: boolean = false` (reflected) — current pressed value. It does not opt into interaction
  or selected styling by itself; set `toggleable` independently. Once toggle mode is active, a
  separate native `[part='toggle-button']` owns focus, Enter/Space/click
  activation, and explicit `"true"`/`"false"` `aria-pressed`; `[part='base']` remains a container
  and the visible default-slot label is inert and aria-hidden. Activation proposes the opposite
  value through the cancelable `lr-chip-select` event and mutates `selected` only when that event is
  not prevented.
  Has no toggle effect when combined with `removable`, where the remove button is the sole control.
- `toggleable: boolean = false` (reflected) — sole opt-in into the toggle/pressed interactive mode,
  independent of `selected`'s current value. Pair it with `selected` for an initially pressed chip;
  leave `selected` unset for an initially unpressed chip.
- `value?: string` — opaque consumer bookkeeping value, never read, validated, or rendered by this
  component itself, only ever echoed back verbatim (including `undefined` if never set) in
  `lr-remove`'s detail
- `wrap: boolean = false` (reflected) — wraps `[part='label']` onto multiple lines instead of
  ellipsis-truncating it to one line. `false` (the default) reproduces the chip's original
  single-line, ellipsis-truncated label exactly. Matches `<lr-suggestion-chips>`'s identical `wrap`
  opt-in.

**Events:** `lr-remove` (`detail: { value }` — the remove (×) button was activated via click or
Enter/Space while focused; only rendered/reachable while `removable`), `lr-chip-select`
(`detail: { value, selected }` — cancelable; fired from the native toggle button on click or
Enter/Space with the proposed next state when toggle mode is active and `removable` is not set.
Calling `preventDefault()` keeps the current `selected` state unchanged)

**Methods:** `focus(options?)`, `blur()`, and `click()` forward to the active internal control
(toggle or remove button); a disabled control refuses focus/click, and a passive chip's `click()`
retains ordinary host behavior.

When `removable`, `toggleable`, or `disabled` replaces a focused control, focus follows to the
equivalent new chip control when one exists, otherwise to the nearest available composed action.
Synchronous controlled removal receives the same repair, and a newer external focus destination is
never overridden.

**Slots:** default (the chip's label content; its flattened subtree is inert and aria-hidden in
toggle mode, so move links/buttons outside a toggleable chip), `start` (optional decorative leading
adornment such as an icon or status dot; its flattened subtree stays visible but is always inert
and aria-hidden, and nothing is reserved for it — no extra gap — when left empty), `end` (optional trailing content,
typically an icon, placed after the label and before the toggle/remove button; nothing is reserved
for it — no extra gap — when left empty, mirroring `<lr-badge>`'s identical `end` slot). `end`
remains ordinary consumer content in passive/removable mode, but its flattened subtree becomes
inert and aria-hidden beneath the full-surface toggle.

Toggle/remove action names follow the default slot's live visible accessible text through nested
forwarding slots and assigned-node replacement; decorative `start` content never leaks into them.
Hidden, inert, CSS-hidden and `aria-hidden` label branches are excluded. When a host `aria-label`
is present—including `aria-label=""`—the host becomes the one aggregate `role="group"` owner;
that label is not copied onto the nested action. The toggle/remove button instead keeps its
purpose-specific name from visible label text or the localized `select`/`remove` fallback, so the
host and action never expose duplicate names.

**CSS parts:** `base` (the pill's root container), `start` (inert, aria-hidden wrapper around the
decorative `start` slot; hidden entirely while empty), `label` (wrapper around the default slot,
inert and aria-hidden in toggle mode), `end` (wrapper around the `end` slot; hidden entirely while
empty and inert plus aria-hidden in toggle mode, the same `end` csspart name `<lr-badge>` uses),
`toggle-button` (the real native toggle control, rendered over the label in toggle mode),
`remove-button` (the remove (×) affordance, only rendered while `removable`)

The toggle control's accessible name comes from the chip's default-slot text. A start-only
toggleable chip (a colour swatch standing in for a chart series, a bare status dot) falls back to
the localized `select` message rather than shipping an unnamed focusable button—the same generic
fallback the remove button makes to `remove`. A host name, when supplied, remains on the aggregate
group as described above.

**Themeable custom properties:** `--lr-chip-accent`, `--lr-chip-bg`, `--lr-chip-border`
(component-local trio whose private defaults change per `variant` rather than repeating
background/color/border per part per variant; default `var(--lr-color-text)` /
`var(--lr-color-surface)` / `var(--lr-color-border)` —
mirrors the same accent/bg/border vocabulary `<lr-tool-call-chip>`/`<lr-attachment-chip>` use. One
rule covers all four non-neutral variants, because the shared variants sheet has already re-pointed
`--lr-color-fill-loud`/`--lr-color-fill-quiet` at the active variant's row of the semantic grid —
the chip reads those generic slots and never names a variant, and sets its border `transparent`),
`--lr-chip-pressed-border` (border color while pressed/selected — falls back to
`--lr-chip-accent`), `--lr-chip-pressed-bg` (background color while pressed/selected — falls
back to `--lr-chip-bg`), the density quintet `--lr-chip-font-size`, `--lr-chip-padding-block`,
`--lr-chip-padding-inline`, `--lr-chip-gap`, `--lr-chip-icon-size` (all five have private defaults
that follow each `size`, so setting one on the element or a theme ancestor remains authoritative; the
`m` defaults are `--lr-font-size-sm` / `--lr-size-0-25rem` / `--lr-space-s` / `--lr-space-xs` /
`--lr-font-size-sm`), the height pair `--lr-chip-min-height` / `--lr-chip-height` (below),
`--lr-chip-radius` (default `var(--lr-radius)`; `pill` changes its private default to
`var(--lr-radius-pill)`) — the
corner radius of both `[part='base']` and `[part='remove-button']`, kept in sync so retuning one
retunes both, retunable without a `::part()` rule, and unlike the density quintet above it does not
vary by `size`; the same `--lr-button-radius` pattern —
plus shared tokens (`--lr-space-xs`, `--lr-space-s`,
`--lr-color-fill-loud`/`-fill-quiet`, `--lr-color-surface`, `--lr-color-border`, `--lr-color-text`,
`--lr-color-mix-active`,
`--lr-icon-button-size`, `--lr-focus-ring-width`, `--lr-focus-ring-color`,
`--lr-focus-ring-offset`, `--lr-transition-fast`).

**Chip height — a floor and an exact cap:**

- `--lr-chip-min-height` (default `--lr-size-1-5rem`) controls the component-density floor for
  **every interactive chip**—toggleable and removable alike. The final used block size is also
  floored by the shared `--lr-icon-button-size` target in both modes, while `l`/`xl` raise the
  density default. A passive display chip takes no floor from this at all. The interactive base is
  likewise allocated at least the shared target width, so its absolute toggle action cannot escape
  into an adjacent control.
- `--lr-chip-height` pins an **exact** height on `[part='base']` — interactive and passive chips
  alike — so a row of chips can line up with a sibling control of a known height. It is
  **undeclared by default**, which is what keeps the per-tier floor alive: `auto` is a valid
  declared value that would win over the `var()` fallback arm and make `--lr-chip-min-height` dead
  code, so never set it to `auto` — remove the declaration instead. Because the component never
  declares it, it can be set inline, from an ancestor, or from an outer-tree rule.
  On an interactive chip, a value below the shared target size controls only the painted density;
  the owned action allocation still expands to the target floor and cannot overlap adjacent
  controls.

**Optional peer deps:** none.

```html
<lr-chip
  toggleable
  selected
  style="--lr-chip-bg: var(--lr-color-surface); --lr-chip-pressed-bg: var(--lr-color-warning-quiet)"
>
  Priority filter
</lr-chip>
```

### `lr-chip-group`

A flex-wrap container for a set of `<lr-chip>` children — plain light-DOM composition, direct
children are the chips (the same shape `<lr-multi-split>`'s panels / `<lr-source-list>`'s cards take,
no `.items` array prop).

**Properties:**

- `accessibleLabel: string = ''` (attribute `aria-label`) — accessible name for the group,
  forwarded to `[part='base']`, which carries `role='group'` whenever a name is supplied. Supply
  one for any chip row that means something as a set (a filter row, a tag list); without it the
  container stays roleless, because an unnamed group role adds verbosity without information.
  A host `aria-label` does **not** reach a shadow root on its own — this property is what makes it
  reach `[part='base']`, the element that owns the role. Mirrors how `lr-radio-group` and
  `lr-segmented` name their own `radiogroup`.
- `maxVisible?: number` (attribute `max-visible`) — maximum number of assigned children shown before
  the rest collapse behind a "+N" indicator; flattened slot-forwarded children count the same as
  direct children. Author-hidden or inert children do not consume capacity or inflate the hidden
  count. Unset means no limit.

**Events:** `lr-overflow-toggle` (`detail: { expanded }` — the overflow indicator was activated,
revealing or re-collapsing the excess children; fires only from that click, i.e. only when
`max-visible` is actually causing an overflow state — never as a side effect of `max-visible`/
children changing on their own)

When collapse, `max-visible`, or controlled child removal hides the focused chip action, focus moves
to the nearest enabled visible chip control, then the overflow disclosure, then the stable group
base. Focus already moved outside the group is preserved.

**Slots:** default (`<lr-chip>` elements, or any content, though the chip pairing is the intended
usage)

**CSS parts:** `base` (the flex-wrap container, holds both the slot and the overflow indicator),
`overflow-indicator` (the "+N" / "Show less" toggle button; only rendered while `max-visible` is
actively causing an overflow—a locally-styled pill, not an instantiated real `<lr-chip>`, with the
shared minimum hit area in both axes)

**Themeable custom properties:** `--lr-chip-group-gap` (default `var(--lr-space-xs)`) — the gap
between `[part='base']`'s wrapped children (chips and the overflow indicator alike); previously
hardcoded. `--lr-chip-group-overflow-expanded-color` (default
`var(--lr-color-text)`) — text color of `[part="overflow-indicator"]` while expanded
(`aria-expanded="true"`). `--lr-chip-group-overflow-expanded-border-style` (default `solid`) —
that same expanded indicator's border style; its resting border deliberately remains dashed, so a
theme can retune the open affordance without losing the collapsed treatment. Both are state hooks:
inline `var()` fallbacks at the point of use, never `:host` declarations, so they can be set on the
element _or on any ancestor_. They exist because
`::part(overflow-indicator)[aria-expanded='true']` is invalid CSS — Shadow Parts forbids an attribute
selector after `::part()` — so retinting or reshaping only the expanded state otherwise meant
re-pointing shared tokens. Left unset, rendering is unchanged. Otherwise shared tokens
(`--lr-space-xs`, `--lr-space-s`,
`--lr-color-border`, `--lr-color-surface`, `--lr-color-text-quiet`, `--lr-color-text`,
`--lr-color-brand`, `--lr-focus-ring-width`, `--lr-focus-ring-color`,
`--lr-focus-ring-offset`, `--lr-transition-fast`).

**Optional peer deps:** none.

```html
<lr-chip-group max-visible="3">
  <lr-chip removable value="draft">Draft</lr-chip>
  <lr-chip variant="success" removable value="reviewed">Reviewed</lr-chip>
  <lr-chip variant="warning">Needs input</lr-chip>
  <lr-chip variant="danger" pill>Blocked</lr-chip>
</lr-chip-group>
<script type="module">
  const group = document.querySelector("lr-chip-group");
  group.addEventListener("lr-overflow-toggle", (e) =>
    console.log(e.detail.expanded)
  );
  group
    .querySelectorAll("lr-chip")
    .forEach((chip) =>
      chip.addEventListener("lr-remove", (e) => console.log(e.detail.value))
    );
</script>
```

Since CSS alone can't parameterize `:nth-child` on a runtime prop, `<lr-chip-group>` reaches
directly into the light DOM and sets each excess child's own `hidden` property once `max-visible` is
exceeded — the same approach `<lr-multi-split>` uses to set each panel's inline `flex`/`order`, rather
than a stylesheet-only solution. It observes live author changes to each managed child's `hidden`
and `inert` state, uses real `hidden` attributes for arbitrary HTML/SVG elements, and restores the
latest author-owned value when ownership ends or the group disconnects; reconnecting reapplies the
current collapsed state. Forwarded-slot reconciliation is deferred without scheduling a reactive
write from `firstUpdated()`.

**Known gotchas:**

- `<lr-chip>`'s accessible remove-button label ("Remove {text}") is computed only from the default
  slot's own text content — text living inside the (decorative) `start` slot doesn't leak into it.
- `<lr-chip-group>` silently un-expands (`expanded` resets to `false`, with no event firing) if a
  consumer raises `max-visible` past the current child count while already expanded — only an actual
  click on the overflow indicator fires `lr-overflow-toggle`.
- `<lr-chip-group>`'s overflow indicator is its own locally-styled pill, not an instantiated
  `<lr-chip>` in its shadow DOM — don't expect `<lr-chip>`'s CSS parts or custom properties to
  reach it.

---

## `lr-kbd`

A small chip representing a keyboard shortcut, rendering the platform-appropriate glyph for
cross-platform modifier keys (⌘ on macOS, "Ctrl" elsewhere) from a single platform-neutral `keys`
string. First-party invention (no Web Awesome equivalent).

Removing `keys` safely clears the shortcut. Unknown tokens, including `constructor` and `__proto__`,
render and name themselves verbatim; recognized modifiers keep their localized labels.

**Properties:**

- `keys: string = ''` — a `+`-separated sequence of tokens, e.g. `"mod+k"` or `"mod+shift+p"`.
  Recognized modifier tokens: `mod` (platform-neutral primary modifier — ⌘/"Command" on macOS,
  "Ctrl"/"Control" elsewhere), `alt` (⌥/"Option" on macOS, "Alt" elsewhere), `shift` (⇧/"Shift"
  always), `ctrl`/`control` (always the literal Control key, distinct from `mod`, for a shortcut
  that's specifically Ctrl even on macOS). Anything else falls through to a small built-in map of
  friendly labels (`enter` → `↵`/"Enter", `esc`/`escape` → "Esc"/"Escape", `tab`, `space`,
  `backspace` → `⌫`/"Backspace", `delete` → "Del"/"Delete", `home`, `end`, `pageup` → "PgUp"/"Page
  Up", `pagedown` → "PgDn"/"Page Down", the four `arrowup`/`arrowdown`/`arrowleft`/`arrowright` →
  arrow glyphs, `plus`/`minus` → literal "+"/"−" as an escape hatch since `+` is the token
  delimiter and can't appear as a literal token itself), or, failing that, renders as typed
  (single letters/digits upper-cased).
- `platform: 'auto'|'mac'|'windows'|'linux' = 'auto'` (reflected) — `auto` detects the current
  runtime once; an explicit value makes SSR, screenshots, documentation, and tests deterministic.
- `effectivePlatform: 'mac'|'windows'|'linux'` (read-only) — the concrete platform currently used.
  It is serialized as `data-effective-platform` on `[part="base"]`; hydration adopts a server's
  serialized auto choice instead of re-sniffing and replacing its key caps in another realm.

**Exported types/functions (also directly usable standalone):** `KbdKeyLabel { visual: string;
word: string }` — one resolved token's rendered glyph and spelled-out word; `KbdLocalize = (key:
string, fallback: string) => string`.
`shortcutTokenLabel(rawToken: string, isMac: boolean, localize?: KbdLocalize): KbdKeyLabel`
resolves a single token, parameterized on `isMac` so both platform branches are unit-testable
without spoofing `navigator`; the optional callback localizes spoken key names.
`parseShortcut(keys: string, isMac: boolean, localize?: KbdLocalize): KbdKeyLabel[]` splits and
resolves a full `keys` string with the same optional localization callback.

**Events:** none — purely presentational.

**Slots:** default — an escape hatch for fully custom key-cap content (e.g. an icon instead of a
text glyph). When it has any real (non-whitespace) content, it replaces the `keys`-driven rendering
entirely and this component stops _computing_ its own `aria-label` from `keys`, leaving the slotted
content to carry its own accessible name. A host-supplied `aria-label` in custom mode is forwarded
to `[part="base"]` together with `role="img"`; without one, the wrapper adds no image role and
leaves the slotted content's own semantics exposed. A host `aria-label` wins by attribute presence,
including an explicitly empty value; the computed shortcut name applies only when that attribute is
absent.

**CSS parts:** `base` (the chip root), `key` (one per rendered token).

**Themeable custom properties:** shared tokens only — `--lr-space-xs`, `--lr-color-surface`/
`-border`/`-text`/`-text-quiet`, `--lr-radius`, `--lr-font`.

**Optional peer deps:** none.

```html
<lr-kbd keys="mod+k"></lr-kbd>
<lr-kbd keys="mod+shift+p"></lr-kbd>
<lr-kbd keys="esc"></lr-kbd>
```

Automatic platform detection (computed once at module scope, not per-instance/per-render, since a
page's platform never changes mid-session) prefers `navigator.userAgentData` (Client Hints, so far
Chromium-only) when available, falling back through `navigator.platform` (long-deprecated) and
finally a `navigator.userAgent` substring check. A server without `navigator` uses `linux`; its
serialized effective value is retained by hydration. Set `platform` explicitly whenever the
rendered documentation should target a different platform.
The rendered chip carries `role="img"` with a single spelled-out `aria-label` (e.g. "Command+K")
rather than exposing each glyph/`+`-separator as separate accessible-tree text, since the individual
pieces aren't real words and would read worse piecemeal than as one label — glyphs like ⌘/⇧/⌥ are
not reliably announced by every screen reader/platform combination, which is exactly why the
spelled-out word form exists at all. An empty `keys` with no explicit `aria-label` override and no
slotted content renders nothing visible and is marked `aria-hidden="true"` (no `role="img"`) instead
of exposing a nameless image element — `role`/`aria-hidden` are both derived from the same
computed-label value so the two can never disagree.

---

## `lr-popup`

The low-level anchored-positioning primitive `lr-popover`, `lr-dropdown` and `lr-tooltip` are built
on. Mirrors `wa-popup` / `sl-popup`. **New in 8.0.0** — the positioning logic already existed as an
internal module, but a migrating consumer had no public element to rename `wa-popup`/`sl-popup` to
and had to reimplement it by hand.

It positions its default slot against an anchor and keeps the two aligned through scroll, resize and
layout change — and does nothing else. **No dismiss behaviour, no focus management, no ARIA
relationship, no trigger semantics.** Those are policy, and each of the three overlays above layers
its own. Reach for `lr-popup` when you need a floating surface the library does not already ship (an
anchored inline editor, a custom autocomplete list); if you find yourself adding light dismiss and
focus return on top of it, use `lr-popover` instead.

**Anchoring**, in precedence order: legacy `virtualAnchor` (an arbitrary rect — a canvas hit, chart
datum, or selection range), mapped `anchor` (an `Element`, same-root id string, or Floating UI
virtual element), `for` (a same-root id), then the first element assigned to the `anchor` slot. A
disconnected element or dangling id falls through to the next source. Id insertion, removal,
replacement and transfer, plus direct and forwarded slot changes, are tracked live.

**Properties:**

- `active: boolean = false` (reflected) — requests positioning and paint. It remains the caller's
  intent when an anchor is temporarily unavailable; the popup and optional hover bridge stay
  hidden and non-interactive until the currently resolved anchor has completed placement.
- `anchor: Element | string | VirtualAnchor | null = null`, `for: string = ''` (reflected), and
  `virtualAnchor` (property only) — the non-slot anchors, in the precedence order above. For a
  plain virtual rect, omitted `width`/`height` default to zero, negative dimensions clamp to zero,
  and any non-finite coordinate or dimension makes that highest-priority rect inert so it cannot
  corrupt layout or paint stale popup chrome.
- `placement: Placement = 'top'` (reflected) — the full Floating UI vocabulary, mirrored
  under RTL. The shared positioner's physical coordinates remain authoritative in either
  direction, so RTL never stretches a fixed-width popup against an opposite logical inset.
- `strategy: 'absolute' | 'fixed' = 'absolute'` (reflected) — the CSS positioning scheme. `fixed`
  normally positions relative to the viewport, but ancestors using transforms, filters or
  containment can establish a different containing block, and ancestor clipping may still apply.
  `absolute` positions relative to its containing block and scrolls with its containing content.
- `distance: number = 0` — offset from the anchor along the placement axis, in px
- `skidding: number = 0` — offset along the anchor's edge, in px
- `flip: boolean = false` (not reflected), with `flipFallbackPlacements: string = ''` (attribute
  `flip-fallback-placements` — a
  space-delimited placement list `flip` tries in order instead of just the opposite side;
  unrecognized entries are dropped rather than forwarded), `flipFallbackStrategy: 'best-fit' |
'initial' | 'initial-placement' = 'best-fit'` (attribute `flip-fallback-strategy` — what `flip` settles on
  when no candidate fits: the least-overflowing one, or `placement` as written),
  `flipBoundary: PlaceBoundary | null = null` (property only — element(s) to measure overflow
  against instead of the popup's clipping ancestors) and `flipPadding: number = 0` (attribute
  `flip-padding`)
- `boundary: 'viewport' | 'scroll' = 'viewport'` (not reflected) — shared overflow boundary for flip,
  shift, and auto-size; each middleware-specific boundary below overrides it independently
- `shift: boolean = false` (not reflected), with
  `shiftBoundary: PlaceBoundary | null = null` (property only) and
  `shiftPadding: number = 0` (attribute `shift-padding`)
- `padding: number = 0` — boundary padding kept clear by `shift` and by the available-size
  measurement
- `autoSize: 'horizontal' | 'vertical' | 'both' | null = null` (attribute `auto-size`), with
  `autoSizeBoundary: PlaceBoundary | null = null` (property only) and
  `autoSizePadding: number = 0` (attribute `auto-size-padding`). The popup is _always_ capped by the
  available space it publishes as `--lr-positioner-available-inline-size` /
  `--lr-positioner-available-block-size`; `auto-size` re-measures the named axes against
  `auto-size-boundary`/`auto-size-padding` instead of the shared `padding`, so it narrows or widens
  that cap rather than introducing one. An unrecognized value is inert rather than half-applied.
- `sync: 'width' | 'height' | 'both' | null = null` — copies the anchor's inline size, block size,
  or both onto the popup. An unrecognized value is inert, for the same reason.
- `hoverBridge: boolean = false` (attribute `hover-bridge`, not reflected) — renders an invisible quad
  across the `distance` gap, so a pointer travelling between anchor and popup never leaves both at
  once. Purely geometric: this element owns no hover policy of its own, the component built on top
  reads the hover.
- `arrow: boolean = false` (not reflected), `arrowPlacement: 'anchor'|'start'|'end'|'center' = 'anchor'`
  (attribute `arrow-placement`) and `arrowPadding: number = 10` (attribute `arrow-padding`) — the
  shared arrow trio described at the top of this family

The aligned v8 defaults above are source-contract exact. To preserve the previous Lyra-shaped
geometry explicitly, use `placement="bottom-start" strategy="fixed" distance="4" flip shift`;
origin-aware migration rewrites emit those tokens instead of relying on changed defaults.

`popup: HTMLElement` is the positioned, shadow-owned popup node. Its setter exists for the writable
WA/SL public TypeScript contract, but assignments are intentionally ignored: replacing that node
would disconnect positioning, animation, and the documented CSS parts. Read it to animate or style
the live internal node.

**Methods:** `reposition()` — recompute now. Rarely needed, since the popup already tracks scroll,
resize, layout and live DOM-anchor identity changes; useful after moving a virtual anchor
imperatively.

**Events:** `lr-reposition` — `detail: { placement }`, the placement actually used after `flip`.

**Slots:** `anchor` (the element to position against), default (the floating content).

**CSS parts:** `anchor`, `popup`, `arrow`, and `hover-bridge` (the invisible quad, rendered only
while `hover-bridge` is set). `popup` carries the **resolved side** as a second part token
(`top`/`bottom`/`left`/`right`), so `::part(popup bottom)` styles one side —
`::part(popup)[data-side]` would silently never match. `arrow` carries its own resolved side the
same way (`arrow-top`, `arrow-bottom`, `arrow-left`, `arrow-right`).

**Themeable custom properties:** mapped `--arrow-size`, `--arrow-color`, `--popup-border-width`,
`--show-duration`, and `--hide-duration`; retained `--lr-popup-arrow-size` is the arrow-size
fallback. Read-only `--auto-size-available-width` / `--auto-size-available-height` mirror the
positioner's available dimensions. Shared tokens cover stacking, raised surface, and border.

The popup also receives `--lr-positioner-available-inline-size` / `--lr-positioner-available-block-size`
from the shared positioner and caps its dimensions to the measured available space.

```html
<lr-popup active arrow placement="top" distance="8">
  <button slot="anchor">Anchor</button>
  <div class="panel">Positioned content</div>
</lr-popup>
```

---

## `lr-popover`

A click-triggered, light-dismiss floating surface positioned with the shared Floating UI positioner.

An open lr-popover repositions when its effective host or inherited text direction changes,
preserving open state without emitting lifecycle events.

**First-interaction registration.** A performance-sensitive navigation shell can keep a native
`<details>` disclosure working before JavaScript, then load only the granular popover registration
when that fallback first opens. The interaction that starts an async import is not replayed after
the custom element upgrades, so finish the handoff explicitly with `show()`:

```html
<details id="account-fallback">
  <summary>Account</summary>
  <nav aria-label="Account"><a href="/profile">Profile</a></nav>
</details>
<lr-popover id="account-popover" popup-role="none" hidden>
  <button slot="trigger">Account</button>
  <nav aria-label="Account"><a href="/profile">Profile</a></nav>
</lr-popover>
<script type="module">
  const fallback = document.querySelector("#account-fallback");
  const popover = document.querySelector("#account-popover");
  let registration;
  fallback.addEventListener("toggle", async () => {
    if (!fallback.open || !popover.hidden) return;
    registration ??= import(
      "@aceshooting/lyra-ui/components/overlays/overlay/popover.js"
    ).catch((error) => {
      registration = undefined; // let a later interaction retry
      throw error;
    });
    await registration;
    await customElements.whenDefined("lr-popover");
    fallback.hidden = true;
    popover.hidden = false;
    await popover.show();
  });
</script>
```

This keeps the fallback's markup and semantics in the initial document. The registration, Lyra
base, nonmodal stack, and first-open positioning runtime remain outside that initial module graph.
If the import fails, leave the native disclosure visible and usable.

**Properties:**

- `open: boolean = false` (reflected) — assigning it runs the same `lr-show`/`lr-hide` lifecycle as
  `show()`/`hide()`, so the property, the reflected attribute and the two methods can never disagree
- `placement: Placement = 'top'` (reflected) — the full Floating UI vocabulary, mirrored
  under RTL
- `positioningStrategy: PlaceStrategy = 'fixed'` (attribute `positioning-strategy`, reflected) — CSS
  positioning scheme the popup is laid out with, `'absolute' | 'fixed'`. The one property
  `<lr-popover>`, `<lr-dropdown>`, `<lr-select>`, `<lr-tooltip>` and `<lr-color-picker>` all spell
  the same way; each keeps its own default, so setting nothing changes nothing. An unsupported value
  resolves back to that default. This property always reports the instance's own authored value (or
  its mirrored default) — see the cascading `--lr-positioning-strategy` custom property below for a
  theme-level way to change the *rendered* strategy of every instance that sets neither.
- `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
  keyword. The two transient modes open after `showDelay`, close after `hideDelay` once the
  interaction ends, never move focus into the surface, and stay open while focus rests anywhere
  inside it. A click on the trigger pins a transient surface open; the next click releases the pin
  and closes it. `manual` refuses every interaction, leaves the surface to `show()`/`hide()`/`open`,
  and wins over any keyword beside it. Unrecognized tokens are dropped and the property reads back
  as the canonical list; unlike `<lr-tooltip>`, a list left with no recognized keyword resolves to
  `'click'` rather than to manual, so a typo can never strand a popover's content behind `show()`.
  Both the slotted trigger and a `for=`-resolved external trigger honour every keyword.
- `showDelay: number = 0` (attribute `show-delay`) — ms before a `hover`/`focus` interaction opens
  the popover.
- `hideDelay: number = 0` (attribute `hide-delay`) — ms before the interaction ending closes it; the
  grace period that lets a pointer cross the gap to the popup.
- `hoverBridge: boolean = false` (attribute `hover-bridge`, reflected) — clips an invisible
  `[part='hover-bridge']` quad across the `distance` gap while a `hover` popover is open, so a
  pointer travelling between trigger and popup never leaves both at once.
- `distance: number = 8` — anchor-offset distance in px (Floating UI's main-axis `offset()`). May
  legitimately be negative to overlap the trigger; a non-finite value falls back to the default.
- `skidding: number = 0` — offset _along_ the anchor's edge, in px (Floating UI's cross-axis
  offset). New in 8.0.0.
- `for: string = ''` (reflected) — id of an element resolved in this element's own root. It is the
  positioning source behind a direct `.anchor`; when it resolves to a live HTML element and no
  trigger is slotted, it also owns click and generated ARIA. A slotted trigger wins interaction/ARIA
  ownership even when positioning uses `for`, and a `showAt()` virtual anchor wins positioning while
  suppressing every DOM interaction owner.
  Assigning `null` is the mapped setter-only clearing spelling: it removes the attribute and the
  getter continues to return `''`
- `anchor: Element | null = null` (property only) — positioning-only direct anchor, taking priority
  over `for` and the interaction owner but never receiving click listeners or generated ARIA; a
  `showAt()` virtual anchor still wins
- `arrow: boolean = true` (reflected) — render an arrow pointing at the anchor; the true-default
  converter accepts `arrow="false"`
- `withoutArrow: boolean = false` (attribute `without-arrow`, reflected) — positive mapped spelling
  for suppressing the default arrow
- `arrowPlacement: 'anchor'|'start'|'end'|'center' = 'anchor'` (attribute `arrow-placement`) —
  `anchor` tracks the anchor's centre; `start`/`end` pin the arrow `arrow-padding` from one logical
  end of the edge (the two ends are the inline ones on a top/bottom placement, so they swap under
  RTL; on a left/right placement they are the block ends, which do not); `center` pins it to the
  middle of the edge regardless of where the anchor is
- `arrowPadding: number = 0` (attribute `arrow-padding`) — keeps the arrow this many px from the
  popup's corners
- `accessibleLabel: string = ''` (attribute **`aria-label`**) — names the popup. An authored host
  attribute wins by presence, including `aria-label=""`; only when it is absent does the property
  or localized "Popover" ("Menu" when `popupRole` is `menu`) fallback apply
- `popupRole: 'dialog'|'menu'|'none' = 'dialog'` (attribute `popup-role`). `none` (new in 11.0.0)
  renders **no** `role` and no generated `aria-label` on the popup surface, and leaves
  `aria-haspopup` off the trigger, so slotted content owns its own semantics and accessible name.
  Unsupported attribute values and untyped property writes normalize to `dialog` before any role
  or trigger ARIA is rendered.
  It exists for the WAI-ARIA **disclosure navigation** pattern: a flyout of links is not an
  application action menu (`menu` announces "menu, menu item" and expects `menuitem` children) and
  is not an interruptive surface (`dialog`). The `aria-expanded`/`aria-controls` wiring that pattern
  requires is unchanged, as are light dismiss, Escape, focus return, and positioning:

  ```html
  <lr-popover popup-role="none">
    <button slot="trigger">Products</button>
    <nav aria-label="Products">
      <ul><li><a href="/overview">Overview</a></li><li><a href="/pricing">Pricing</a></li></ul>
    </nav>
  </lr-popover>
  ```

  Note there is deliberately no `aria-haspopup="none"` — that is an invalid attribute value, not a
  neutral one, and axe reports it as a critical violation. `lr-dropdown` still pins `popupRole` to
  `menu`; the escape hatch lives on the general-purpose primitive.
- `disabled: boolean = false` (reflected, new in 10.0.0) — prevents opening the popover; pointer,
  keyboard, and programmatic `show()`/`open = true` are all refused while set. Becoming disabled also
  closes an already-open popover, and initial `disabled` plus `open` normalizes closed in either
  attribute order. `lr-dropdown` now inherits this from `lr-popover` rather than declaring its own;
  its consumer-facing behavior is unchanged

To preserve the previous Lyra-shaped defaults explicitly, use
`placement="bottom-start" distance="4" without-arrow`; origin-aware migration emits those tokens.

The slotted trigger receives `aria-haspopup`, `aria-expanded`, and `aria-controls`. With no slotted
trigger, a live HTML `for` target receives the identical ownership contract. A wrapper/custom
trigger's composed descendant that actually receives focus receives the same semantics and becomes
the focus-return target. The component supplies the real popup to the shared relationship owner;
because current browsers reject a light-DOM reference into a private shadow tree, that inward edge
is exposed as the public `lr-popover` host. Target insertion, removal, replacement, `id` changes,
and late custom-element upgrade are tracked live. Authored relationship tokens compose, generated
whole-value attributes stay authoritative while owned, and exact late-authored baselines return
when ownership moves or disconnects.
An enabled, non-inert light-DOM descendant with `data-popover="close"` requests its closest owning
popover to close when activated. Disabled/`aria-disabled` actions are inert, and a nested popover
consumes its own action so the same click never closes an ancestor.
**Methods:** `show(): Promise<void>` opens the popover programmatically — identical to
`el.open = true`, including the veto point — and resolves after `lr-after-show`. A no-op or vetoed
transition returns an already-resolved promise.
`showAt(rect: { x, y, width?, height?, contextElement? }, options?: { returnFocusTo?:
HTMLElement })` opens the popover anchored to an arbitrary rectangle instead of any DOM anchor —
for a graph node, a canvas pixel, a chart datum, or any other non-DOM location
(`width`/`height` default to `0`, a point). Escape and light-dismiss return focus to
`options.returnFocusTo` when supplied, or skip focus-return entirely otherwise, since a virtual
anchor has no `.focus()`. The virtual anchor has no DOM node of its own for `autoUpdate()` to
track ancestor scroll/resize against — pass `rect.contextElement` (a real, still-connected element
near the virtual point) when one is available to give it something to observe; otherwise, or when
the anchor point moves on its own (e.g. a graph pan/zoom tick), re-call `showAt()` with fresh
coordinates to re-anchor — the popover stays open across such a call. A popover that never calls
`showAt()` behaves exactly as before. Non-finite coordinates or dimensions are a no-op and leave
the current open/anchor state unchanged. While virtual anchoring is active, no slotted/`for` DOM
element owns click or generated ARIA.
`hide(options?: { focusTrigger?: boolean }): Promise<void>` programmatically closes the popover and
resolves after `lr-after-hide`; pass
`{ focusTrigger: false }` to opt out of focus restoration. By default, `hide()`, Escape, light
dismiss, and a bare `el.open = false` all return focus to the slotted/`for` owner's real composed
focus target, or to a virtual anchor's explicit `returnFocusTo`; a virtual anchor with no return
target closes without moving focus. No-op when already closed.
**Events:** `lr-show` (cancelable), `lr-after-show`, `lr-hide` (cancelable), `lr-after-hide` — none
carries a detail, and the two `lr-after-*` events are never cancelable. Neither pair fires for
markup that renders open from the start, nor when only `placement`/`distance` change on an
already-open popover.

Removing the sole connected direct anchor or sole interaction anchor from an open popover is
structural teardown: it force-closes even if an `lr-hide` listener would veto an ordinary close. If
a live slotted/`for` positioning fallback remains, the popover rebinds to it and stays open instead.

Public DOM-anchored `lr-popover` instances form a same-root singleton. A later ordinary `show()`
first requests the existing peer's cancelable close and remains closed if that peer vetoes. Initial
open markup stays lifecycle-silent: after the hydration-safe first-render boundary, the
later-connected instance wins and the earlier peer closes structurally without a veto or lifecycle
event. `lr-dropdown`, `showAt()` virtual surfaces, and popovers in separate document/shadow roots
remain independent. Re-entering the same `show()` or `hide()` request from its own before-event
coalesces onto one transition promise and emits the lifecycle once.

**Breaking in 8.0.0:** `lr-show`/`lr-hide` now fire _before_ the state changes and are cancelable —
`preventDefault()` on `lr-show` leaves the popover closed for the trigger click, `show()` and
`open = true` alike, and on `lr-hide` keeps it open for every dismissal path (Escape, light dismiss,
`hide()`, `open = false`). Reading `el.open` inside such a handler therefore returns the _old_
value; in 7.x these events fired after the fact and were purely informational. That is exactly the
timing `wa-show`/`wa-hide` always had, so the `wa-*` → `lr-*` migration table's "mechanical rename"
promise now holds for these names too — which also means 7.x Lyra code that read `el.open` in the
handler was relying on the _opposite_ polarity and must be re-read. `lr-after-show`/`lr-after-hide`
are new in 8.0.0 and settle after the public `popover.show` / `popover.hide` registry animation.
Per-element overrides win over page defaults; keyframes-only overrides retain the popup's
`--show-duration` / `--hide-duration` and shared easing. Reduced motion flattens timing to zero, and
a `null` registration skips interpolation, but neither path skips the after-event or its
method-promise settlement.

**Slots:** `trigger` (the interactive element that toggles the popover), default (popover content;
an enabled, non-inert descendant with `data-popover="close"` closes its nearest owning popover).

**CSS parts:** `trigger`; `popup dialog popup__popup`; `content body`;
`arrow popup__arrow` (rendered unless suppressed); and `hover-bridge` (the invisible quad, rendered
only while a `hover` popover with `hover-bridge` set is open). Names grouped together are aliases on
the same node. The arrow's part attribute also carries the **resolved side** as a second token — `arrow-top`,
`arrow-bottom`, `arrow-left`, `arrow-right` — so `::part(arrow arrow-top)` styles one side.
`::part(arrow)[data-side]` and `::part(arrow) .inner` are invalid selectors that silently never
match; the state is in the part name.

**Themeable custom properties:** mapped `--max-width`, `--arrow-size`, `--show-duration`, and
`--hide-duration`, with retained `--lr-overlay-max-inline-size` and `--lr-overlay-arrow-size`
fallbacks. Arrow size is half the square's width. Rendering the arrow switches `[part~="popup"]` to
`overflow: visible` so it is not clipped, moving the scroll container onto `[part~="content"]`.

The popup and its arrow paint from the **shared overlay-surface family** (16.0.0):
`--lr-overlay-surface` (default `var(--lr-color-surface-overlay)`), `--lr-overlay-border` (default
`var(--lr-color-border)`), `--lr-overlay-radius` (default `var(--lr-radius)`) and
`--lr-overlay-shadow-anchored` (default `var(--lr-shadow-m)`). The arrow takes the fill and the
edge but never the radius — its corners are already cut by its clip path. None of the four is
declared on `:host`, so a single declaration on `:root` retints every floating surface in the
application, and the same declaration on one component's own ancestor scopes the retint to that
subtree. `--lr-overlay-shadow-anchored` is deliberately a different name from the modal tier
`--lr-overlay-shadow-modal` that `lr-dialog`/`lr-drawer` read, so raising popups never raises
dialogs.

**`--lr-positioning-strategy` (16.0.0)** — a cascading `absolute`/`fixed` override for
`positioningStrategy`, read from computed style each time the popup is (re)positioned (open, or a
placement/anchor change while open — never per animation frame). Setting nothing anywhere leaves
every default exactly as before. Precedence: an explicit `positioning-strategy`/`hoist` on the
instance always wins; otherwise this inherited custom property; otherwise the component's own
mirrored default. Because it is a plain cascading custom property, one declaration on `:root`, a
theme, or a single clipping ancestor (an `overflow: hidden` card or a scroller) changes every unset
overlay beneath it — no need to author `positioning-strategy`/`hoist` on each instance individually,
or to remember it on every new one:

```html
<lr-card style="--lr-positioning-strategy: fixed; overflow: hidden">
  <lr-dropdown>
    <button slot="trigger">Actions</button>
    <lr-dropdown-item>Rename</lr-dropdown-item>
  </lr-dropdown>
</lr-card>
```

`<lr-popover>`, `<lr-dropdown>`, `<lr-select>`, `<lr-tooltip>` and `<lr-color-picker>` all honor it.

```html
<lr-popover
  arrow
  arrow-placement="center"
  placement="bottom"
  distance="8"
  skidding="12"
>
  <button slot="trigger" type="button">Details</button>
  <p>Anchored content.</p>
</lr-popover>
<script type="module">
  import "@aceshooting/lyra-ui/components/overlays/overlay/popover.js";

  const popover = document.querySelector("lr-popover");
  let ready = false;
  popover.addEventListener("lr-show", (event) => {
    // vetoes the open; popover.open is still false inside this handler
    if (!ready) event.preventDefault();
  });
  popover.addEventListener("lr-after-show", () => console.log("fully open"));
</script>
```

## `lr-tooltip`

A tooltip for a consumer-owned trigger, positioned with the shared Floating UI positioner. Which
interactions open it is configurable as of 8.0.0; by default it is still hover and focus.

An open lr-tooltip repositions when its effective host or inherited text direction changes,
preserving open state without emitting lifecycle events.

Removing `content` safely omits tooltip fallback text while preserving `null` property readback;
later text renders normally.

**Properties:**

- `open: boolean = false` (reflected) — assigning it runs the same lifecycle as `show()`/`hide()`.
  Assigning `false` also cancels a delayed open that has not fired yet, even when the tooltip is
  already closed, so a pending timer can't reopen it behind the caller's back.
- `trigger: string = 'hover focus'` — **new in 8.0.0.** A _space-separated_ list of `hover`,
  `focus`, `click` and `manual`. `manual` (or an empty list) leaves the tooltip entirely under
  programmatic control. Note the name collision: this string property and the `trigger` _slot_ are
  different things — the slot holds the element, this property says which of its interactions count.
- `manual: boolean = false` — equivalent to including `manual` in `trigger`; kept because it reads
  better on a tooltip that is only ever driven from script
- `showDelay: number = 150` (attribute `show-delay`) and `hideDelay: number = 0` (attribute
  `hide-delay`) — **breaking in 8.0.0:** the single `delay` property is gone, split into these two
  independent milliseconds values, so a tooltip can linger after the pointer leaves without also
  being slow to appear. `showDelay` keeps the old `delay` default of 150ms; `hideDelay` defaults to
  `0`, so leaving the trigger now closes the tooltip at once, where 7.x's single `delay` also held
  it open for 150ms first. A non-finite value falls back to the default; a negative one clamps to
  `0` (immediate) and an oversized one to the largest delay `setTimeout` can represent, so neither
  can hang the tooltip open.
- `placement: Placement = 'top'` (reflected) — the full Floating UI vocabulary, mirrored under RTL
- `distance: number = 8` — anchor-offset distance in px; identical semantics to
  `<lr-popover>.distance` (both wrap the same `place()`/`offset()` middleware)
- `skidding: number = 0` — offset along the anchor's edge, in px. New in 8.0.0.
- `for: string = ''` (reflected) — id of an element in this tooltip's own root. It positions behind
  a direct `.anchor`; when it resolves to a live HTML element and no trigger is slotted, it also owns
  the configured interaction listeners and `aria-describedby`. A slotted trigger wins interaction
  and ARIA ownership. Assigning `null` clears the attribute to the canonical `''` read value; the
  getter itself remains non-nullable
- `anchor: Element | null = null` (property only) — positioning-only direct anchor, taking priority
  over `for` and the active interaction owner without receiving listeners or generated ARIA
- `disabled: boolean = false` (reflected) — prevents both interaction and programmatic opening;
  setting it while open closes the tooltip
- `hoist: boolean = false` (reflected) — switches the mapped absolute positioning default to fixed
- `positioningStrategy: PlaceStrategy = 'absolute'` (attribute `positioning-strategy`, reflected) —
  see `<lr-popover>`. `hoist: boolean = false` is its retained exact alias
  (`hoist` ⇔ `positioning-strategy="fixed"`); writing either spelling updates the other, so the two
  attributes can never disagree. Prefer `positioning-strategy` in new code. It also honors the
  cascading `--lr-positioning-strategy` custom property `<lr-popover>` documents, ahead of this
  mirrored `absolute` default, when neither spelling is authored on the instance.
- `arrow: boolean = true` (reflected), `withoutArrow: boolean = false` (attribute `without-arrow`,
  reflected), `arrowPlacement: 'anchor'|'start'|'end'|'center' = 'anchor'`
  (attribute `arrow-placement`) and `arrowPadding: number = 0` (attribute `arrow-padding`) — the
  same arrow trio `<lr-popover>` documents (`llms/components/lr-popover.md`), new in 8.0.0
- `content: string = ''` — plain-text tooltip content, used when nothing is slotted
- `accessibleLabel: string = ''` (attribute **`aria-label`**) — a host `aria-label` wins by
  attribute presence, including an explicitly empty value. When the attribute is absent, an
  actionable popup with no property label uses the localized `popover` string.

To preserve the previous Lyra-shaped visual defaults explicitly, use `distance="6" without-arrow`;
origin-aware migration emits those tokens.

**Methods:**

- `show(): Promise<void>` — open immediately, bypassing `show-delay` and interaction policy, then
  resolve after `lr-after-show`
- `hide(): Promise<void>` — close immediately, bypassing `hide-delay`, then resolve after
  `lr-after-hide`
- `showAt(rect: { x, y, width?, height?, contextElement? }, options?: { returnFocusTo?: HTMLElement })`
  — same virtual-anchor contract as `lr-popover.showAt()` (`llms/components/lr-popover.md`)
  (anchors to an arbitrary rectangle
  instead of any DOM anchor, `width`/`height` default to `0`, `contextElement` gives
  `autoUpdate()` something to observe, Escape returns focus to `options.returnFocusTo` or skips
  focus-return, re-call with fresh coordinates to re-anchor a moving point). Opens immediately,
  bypassing `show-delay`/`trigger`/`manual` (all are interaction-debounce concerns for a slotted
  trigger, not a deliberate programmatic call); while active it removes every DOM interaction/ARIA
  owner. Close it with `hide()` or `open = false`. Non-finite coordinates or dimensions are a no-op.

**Events:** `lr-show` (cancelable), `lr-after-show`, `lr-hide` (cancelable), `lr-after-hide` — the
same four-event contract, timing and veto semantics `<lr-popover>` documents
(`llms/components/lr-popover.md`), and all four are
new to this component in 8.0.0. A vetoed `lr-show` leaves the tooltip closed whether the delay
elapsed, `show()` was called, or `open` was assigned.

Tooltip motion resolves `tooltip.show` / `tooltip.hide` through the public animation registry.
The same per-element/global precedence, RTL keyframe selection, token-timing fallback,
reduced-motion flattening, and null-disable lifecycle rules documented for `lr-popover` apply.

**Slots:** both mapped shapes are supported. Web Awesome uses named `trigger` plus default tooltip
content. Shoelace uses the default slot for the trigger and `slot="content"` (or the `content`
property) for tooltip content. A named trigger always selects the first shape; without one, an
explicit content source makes the default slot unambiguously the trigger.

**CSS parts:** `popup base tooltip base__popup` are aliases on the same wrapper; `trigger`; `body`;
and `arrow base__arrow` (rendered unless suppressed). The arrow also carries the resolved side —
`arrow-top`, `arrow-bottom`, `arrow-left`, or `arrow-right`.

**Themeable custom properties:** mapped `--max-width`, `--show-delay`, `--hide-delay`, and
`--arrow-size`; retained `--lr-tooltip-max-inline-size`, `--lr-tooltip-background`,
`--lr-tooltip-color`, and `--lr-tooltip-arrow-size` remain fallbacks. A tooltip popup has no inner
scroll wrapper to move overflow onto, so its default arrow trades internal scrolling for a visible
arrow — use `<lr-popover>` when a floating surface needs both.

`--lr-overlay-surface`, `--lr-overlay-border` and `--lr-overlay-radius` are listed on this tag
because its rules live in the stylesheet module `lr-popover` also composes, but a tooltip bubble is
a **deliberate exclusion** from the overlay-surface family: it is a high-contrast label, not a
panel, so it keeps painting from `--lr-tooltip-background`/`--lr-tooltip-color`, draws no border,
and keeps the tighter `var(--lr-radius-xs)` corner. Setting any of the three changes nothing here.

`--lr-positioning-strategy` (16.0.0) is not excluded: the tooltip honors the same cascading
`absolute`/`fixed` override `<lr-popover>` documents (`llms/components/lr-popover.md`), ahead of
its own mirrored `absolute`
default, when neither `positioning-strategy` nor `hoist` is authored on the instance.

```html
<lr-tooltip
  trigger="hover focus click"
  show-delay="0"
  hide-delay="400"
  arrow
  placement="right"
>
  Copied to clipboard
  <button slot="trigger" type="button">Copy</button>
</lr-tooltip>

<!-- Shoelace-compatible shape: default trigger, named content. -->
<lr-tooltip content="Save your changes">
  <button type="button">Save</button>
</lr-tooltip>
```

While open, trigger `aria-describedby` points to a hidden text proxy in the tooltip's light DOM,
not the shadow-private popup. Native triggers resolve that ID directly. A description is only
announced on the node that actually holds focus, so when the trigger is a custom element the same
proxy is applied to the first focusable descendant as well — across slots and nested open shadow
roots — which covers `lr-select`, `lr-switch`, `lr-chip` and any consumer-authored wrapper, not
just the components that forward their own host `aria-describedby`. A descendant in the same tree
receives the serialized ID; one inside a shadow root is linked through `ariaDescribedByElements`,
whose explicit element-reference assignment intentionally leaves that control's serialized
`aria-describedby` value empty in supporting browsers. Existing author-provided descriptions —
including a control's own internal hint/error text — are merged while open and restored when the
tooltip closes, the trigger is replaced, or the tooltip disconnects. Late author writes remain the
release baseline while Lyra's active description stays composed into the owned value.

With no slotted trigger, a live HTML `for` target receives those same interactions and description;
target insertion, removal, replacement and `id` changes are tracked without requiring reinsertion.
Removing the sole connected direct or interaction anchor force-closes despite an `lr-hide` veto,
while a live slotted/`for` positioning fallback is rebound and keeps the tooltip open.

Plain content keeps `role="tooltip"`. If actionable content appears anywhere in the assigned
default-slot subtree — including native links/form/media controls, authored sequential focus stops,
explicit ARIA widget roles, or content inside a nested custom element's open shadow root — the popup
promotes to a named `role="dialog"` and remains open while pointer or focus is within it. Escape
from either the trigger or popup closes it; Escape from popup content returns focus to the trigger's
real composed focus target. Bubbling `focusin`/`focusout` keeps the tooltip open when focus moves
within a wrapper trigger or between interactive popup controls.
The content scan follows the live composed assignment through forwarding slots. Reassignment,
external descendant text/actionability changes, and relevant composed-ancestor visibility changes
update both the hidden description proxy and popup role; when a forwarding slot becomes genuinely
unassigned, its own fallback content is restored. This classification also runs while the popup is
closed, without treating the popup's internal closed-state visibility as consumer-hidden content.
Image alternatives and `aria-labelledby` references contribute their accessible text; referenced
targets outside the tooltip subtree are observed too, so a sibling label's live text mutation
updates the proxy. Text, actionability, and observer enrollment share bounded, cycle-safe composed
traversal; content beyond the traversal ceiling fails closed instead of recursing without bound.
While open, rootless custom-element content receives a bounded initialization grace period for an
upgrade or newly attached open shadow root; later observable content mutations start a fresh
grace period. This catches normal lazy initialization without scheduling perpetual animation-frame
work for a legitimate custom element that intentionally has no shadow root. Content and trigger
observers plus delayed show/hide timers are bound to the tooltip's current owner window; disconnect
or cross-document adoption cancels the old realm, and reconnect creates fresh observers. Use
`lr-popover` when click-to-open ownership is desired.

**`showAt()` composed with `lr-graph`** — anchoring a popover to a clicked graph node. Note:
`lr-graph.getNodePosition()` and the `lr-node-click` event's `{ x, y }` are in the graph's own
_local drawing space_ (pre pan/zoom), not viewport pixels, so they can't be passed to `showAt()`
directly. For `renderer="svg"` (the default), read the clicked node's own rendered element instead,
whose `getBoundingClientRect()` is already viewport-relative; for `renderer="canvas"` (no per-node
DOM element), use the click event's own `clientX`/`clientY`.

```js
const graph = document.querySelector("lr-graph");
const detail = document.querySelector("lr-popover"); // no slotted trigger needed for showAt()

graph.addEventListener("click", (event) => {
  const nodeEl = event
    .composedPath()
    .find((el) => el instanceof Element && el.matches('[part="node"]'));
  if (!nodeEl) return; // clicked empty canvas/background, not a node
  const rect = nodeEl.getBoundingClientRect();
  detail.showAt({
    x: rect.left + rect.width / 2,
    y: rect.top,
    width: rect.width,
    height: rect.height,
  });
});
```

## `lr-dropdown`

The complete mapped action-menu component. The public element remains a Popover-style trigger plus
positioned popup shell; the shell is presentation-only, and its contained `lr-menu` is the sole
menu role/name owner. That menu provides the same interaction engine as standalone `lr-menu`, so
direct `lr-dropdown-item`/`lr-menu-item` children get roving focus, disabled skipping, type-ahead,
nested submenu keyboard/pointer intent, and focus return without a second public popup. A
consumer-supplied `lr-menu` in the default slot becomes that contained engine instead of being
wrapped in another menu. This supports both Web Awesome's direct-item shape and Shoelace's
consumer-menu shape.

The inner menu list owns scrolling within the popup's height limit, keeping a consumer menu's
header and footer visible. The outer `popup` and `content` parts allow overflow so nested submenus
remain clickable outside the parent menu in every supported browser. This works with either
submenu authoring shape, with or without `hoist` or an arrow; no overflow override is required.

An open lr-dropdown repositions when its effective host or inherited text direction changes,
preserving open state without emitting lifecycle events.

**Direct mapped items.** `<lr-dropdown-item>` is the Web Awesome-compatible name for the same row
implementation as `<lr-menu-item>`. Direct mapped items receive this dropdown's `size` and use its
contained roving-focus, type-ahead, disabled-skipping, selection, and submenu controller; a
consumer-supplied `<lr-menu>` uses that controller directly. This preserves both Web Awesome's
direct-item composition and Shoelace's consumer-menu composition. The canonical item properties,
methods, events, slots, parts, and theme variables are documented in the layout-family
`lr-menu` / `lr-menu-item` section.
The trigger always receives `aria-haspopup="menu"`. `popupRole` is narrowed to the invariant
`'menu'`; assigning another runtime value or authoring another `popup-role` value normalizes it
back to `menu` and never puts a dialog/menu role on the outer positioning shell. This matches Web
Awesome's fixed inner menu role and Shoelace's consumer-menu ownership rather than exposing a
Lyra-only role switch.

ArrowDown opens and focuses the first enabled item; ArrowUp opens and focuses the last enabled
item, whether the interaction owner is slotted or resolved through `for`.
The inherited `data-popover="close"` descendant action is also supported and follows the same
disabled/inert and nearest-owner rules described for `lr-popover`.

The generated menu uses the dropdown's presence-sensitive host `aria-label`, `accessibleLabel`, or
localized "Menu" fallback. A consumer-supplied menu keeps its own naming precedence: its host
`aria-label` (including an explicit empty value), then an explicit nondefault `label`, then the
dropdown fallback. Its `header` and `footer` slots remain rendered outside the inner
`role="menu"` list while contained, including after live slot changes; Tab can therefore reach
their controls without putting arbitrary content inside the menu role.

**Properties:**

- `open: boolean = false` (reflected), `placement: Placement = 'bottom-start'`,
  `distance: number = 0`, `skidding: number = 0`, and `for: string = ''` — the same positioning
  vocabulary as `lr-popover`, except the mapped dropdown sits flush against its trigger by default.
  An explicit distance still wins, and generic `lr-popover` keeps its own default of `8`.
- `size: LyraSize = 'm'` (reflected) — propagated to directly owned mapped items. Accepts the
  six-step Lyra ladder and `small`/`medium`/`large` aliases.
- `disabled: boolean = false` (reflected) — prevents pointer/keyboard/programmatic opening and
  dismisses an already-open dropdown when enabled. Initial `disabled` plus `open` markup or
  pre-upgrade property writes normalize closed regardless of assignment/attribute order.
- `stayOpenOnSelect: boolean = false` (attribute `stay-open-on-select`, reflected) — suppresses the
  default selection close for direct and nested selections.
- `hoist: boolean = false` (reflected) — uses viewport-fixed positioning; otherwise the popup uses
  the containing-block (`absolute`) strategy.
- `sync?: 'width'|'height'|'both'` (reflected) — copies the trigger dimension(s) onto the popup.
- `positioningStrategy: PlaceStrategy = 'absolute'` (attribute `positioning-strategy`, reflected) —
  see `<lr-popover>`. `hoist: boolean = false` is its retained exact alias
  (`hoist` ⇔ `positioning-strategy="fixed"`); writing either spelling updates the other, so the two
  attributes can never disagree. Prefer `positioning-strategy` in new code. `<lr-dropdown>` also
  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.
- `containingElement?: HTMLElement` (property only) — an external element that counts as inside for
  light-dismiss handling.
- `arrow`, `withoutArrow` (`without-arrow`), `arrowPlacement`, `arrowPadding`, and `accessibleLabel`
  (`aria-label`) are retained from `lr-popover` for existing Lyra consumers.
- `popupRole: 'menu'` (attribute `popup-role`) is the narrowed inherited surface. Dropdowns cannot
  be changed into dialogs; use `lr-popover popup-role="dialog"` for arbitrary dialog-like content.

**Methods:** `show(): Promise<void>` and
`hide(options?: { focusTrigger?: boolean }): Promise<void>` use the same cancelable before-events,
after-events, focus return, and settlement rules as `lr-popover`. `reposition(): void` immediately
recomputes placement after an imperative anchor/layout change. `focusOnTrigger(options?): void`
focuses the first assigned trigger, and `getMenu(): LyraMenu | null` returns the live generated or
consumer-supplied contained menu engine. `showAt()` remains available for Lyra's virtual-anchor
compatibility surface.

While a consumer-supplied menu is contained, the dropdown snapshots every integration field it owns
(`dropdownOpen`, owner/contained/role flags, stay-open policy, and size). Removing/swapping that menu or
disconnecting the dropdown restores the exact author values, so reuse outside this dropdown does
not retain hidden parent policy.

**Events:** `lr-select` is the single mapped selection path: cancelable, bubbling/composed, with
`detail: { item }` carrying the activated element. Preventing it keeps the complete submenu chain
open; `stay-open-on-select` applies the same default suppression declaratively. Nested selection is
not translated or re-emitted at each level, so a listener on `lr-dropdown` receives exactly one
event. `lr-show` (cancelable), `lr-after-show`, `lr-hide` (cancelable), and `lr-after-hide` retain
the Popover lifecycle; none fires for initial open markup.

Dropdown motion resolves `dropdown.show` / `dropdown.hide` through the public animation registry;
it retains the dropdown's `--show-duration` / `--hide-duration` defaults when an override supplies
only keyframes. Passing `null` disables motion without skipping the after-event or promise.

**Slots:** `trigger`; default (`lr-dropdown-item`/`lr-menu-item` rows, or one consumer-supplied
`lr-menu`; that menu may use its own `header`/`footer` regions). **CSS parts:** `trigger`;
`popup dialog popup__popup base base__popup panel` (all six tokens on the neutral positioned
popup, preserving the popover, Web Awesome and Shoelace wrapper names on the same node); `menu`
(the contained semantic/controller owner); `content body`; the retained optional
`arrow popup__arrow` token set; and the inherited `hover-bridge` — the invisible quad the positioner
clips across the `distance` gap between trigger and popup, rendered only while a `hover`-triggered
dropdown with `hover-bridge` set is open, so a pointer travelling from the trigger to the popup
never leaves both at once and the surface does not close underneath it. It paints nothing by
default; style it only to debug the travel region.

**Themeable custom properties:** `--show-duration` and `--hide-duration` (both default
`var(--lr-transition-fast)`), mapped `--max-width` and `--arrow-size`, plus retained
`--lr-overlay-max-inline-size` and `--lr-overlay-arrow-size` fallbacks. The popup surface is
`lr-popover`'s, so the whole overlay-surface family reaches it unchanged: `--lr-overlay-surface`,
`--lr-overlay-border`, `--lr-overlay-radius`, `--lr-overlay-shadow-anchored`, and the cascading
`--lr-positioning-strategy` override documented on `<lr-popover>`
(`llms/components/lr-popover.md`).

```html
<lr-dropdown aria-label="File actions" size="small">
  <button slot="trigger">Actions</button>
  <lr-dropdown-item value="rename"
    ><span slot="details">⌘R</span>Rename</lr-dropdown-item
  >
  <lr-dropdown-item>
    Share
    <lr-dropdown-item slot="submenu" value="email">Email</lr-dropdown-item>
    <lr-dropdown-item slot="submenu" value="link">Copy link</lr-dropdown-item>
  </lr-dropdown-item>
  <lr-dropdown-item value="delete" variant="danger">Delete</lr-dropdown-item>
</lr-dropdown>
<script type="module">
  document
    .querySelector("lr-dropdown")
    .addEventListener("lr-select", (event) => {
      console.log(event.detail.item.value);
    });
</script>
```

## `lr-spinner`

An indeterminate busy indicator with a localized, deliberately non-live `role="progressbar"`
name. Mounting ordinary loading UI therefore does not create a false status announcement.

**Properties:** `labelPlacement: 'none' | 'after' = 'none'` (attribute `label-placement`, reflected)
and `accessibleLabel: string | null = null` (attribute **`aria-label`**, not `accessible-label`) —
names `[part="base"]`'s `role="progressbar"`; unset falls back to the localized "Loading…".

**Events:** none.

**Slots:** default — optional label text. `label-placement="after"` renders it inline next to the
indicator and its visible accessible text becomes the progressbar name unless `aria-label`
overrides it. Hidden, inert, `display:none`, `content-visibility:hidden`, and `aria-hidden`
descendants are excluded from that name. A `visibility:hidden|collapse` wrapper suppresses its own
text while a descendant that restores `visibility:visible` remains part of the name.
These rules and live mutation tracking cross nested forwarding slots, including assigned-node
replacement; no wrapper re-render is required.
`'none'` (the default) applies the native `hidden` state to the label wrapper, removing it from both
rendering and the accessibility tree; the progressbar then uses `aria-label` or the localized
"Loading…" fallback.

**CSS parts:** `base` and `spinner` are aliases on the same indeterminate `role="progressbar"`
outer wrapper (no `aria-valuenow` and no live-region semantics);
`spinner-indicator` is the animated `aria-hidden` ring, and `label` is the default-slot wrapper.

**Themeable custom properties:** `--lr-spinner-size` (default `var(--lr-size-1-25rem)` — both
dimensions), `--lr-spinner-track-width` (default `var(--lr-border-width-medium)` — ring thickness),
`--lr-spinner-duration` (default `var(--lr-transition-ambient)` — the duration _and_ easing of one
full rotation; the animation is dropped entirely under `prefers-reduced-motion: reduce`). The ring
colors come from `--lr-color-brand`/`-brand-quiet`. Upstream aliases are `--track-width`,
`--track-color`, `--indicator-color`, and `--speed`.

## `lr-progress-bar`

A determinate or indeterminate progress bar with an independently visible label and optional
formatted percentage.

**Properties:** `value` (reflected), `max`, `indeterminate`, `variant`, `showValue` (`show-value`), and
`label` (mapped accessible-name property), plus `accessibleLabel` (`accessible-label`) — the
retained Lyra compatibility spelling for this component. It is not a library-wide attribute:
spinner, rating, and tooltip expose their explicit host name through `aria-label`. Host
`aria-label` has highest precedence here too. Also
`size: LyraSize = 'm'` (reflected) — `'2xs' | 'xs' | 's' | 'm' | 'l' | 'xl' | 'small' | 'medium' |
'large'`. Track/indicator thickness tier, on the shared six-step ladder: `0.25rem` (`2xs`),
`0.375rem` (`xs`), `0.625rem` (`s`/`small`), `1rem` (`m`/`medium`, unchanged from before this
property existed), `1.25rem` (`l`/`large`), `1.5rem` (`xl`) — each value feeds
`--lr-progress-track-height`'s private default. An explicit `--lr-progress-track-height` (or the
upstream `--track-height`/`--height` aliases) still wins over every tier.

The rendered progressbar exposes `aria-valuemin`, `aria-valuemax`, and `aria-valuenow` when
determinate. Slotted label content is always visible and names the progressbar unless an explicit
label overrides it; `show-value` controls only whether the locale-formatted percentage is appended.
Live label mutations and reassignment stay synchronized through nested forwarding slots. Hidden,
inert, CSS-hidden and `aria-hidden` branches do not name the role; a visible descendant can restore
text suppressed only by an ancestor's `visibility:hidden|collapse`. Host `aria-label` precedence is
presence-based, so an explicitly empty value remains empty rather than invoking a fallback.

**Slots:** default — label content; `label` — compatibility alias for the default slot.
**CSS parts:** `base` and `progress-bar` are aliases on the same progressbar; `track`, `indicator`,
`label`.
**Themeable custom properties:** `--lr-progress-track-height` (default
`var(--lr-progress-height, var(--_lr-progress-track-height))`; `--lr-progress-height` is the legacy
fallback, and the private `--_lr-progress-track-height` is the `size` property's own tier value,
`1rem` at the `m` default, unchanged),
`--lr-progress-track-color` (default `var(--lr-color-brand-quiet)`),
`--lr-progress-indicator-color` (default `var(--lr-progress-indicator-variant-color)`), and
`--lr-progress-label-color` (default `var(--lr-color-text)`). Upstream aliases are `--height` and
`--track-height`, plus `--track-color`, `--indicator-color`, and `--label-color`.

`--lr-progress-indicator-variant-color` is the palette slot the active `variant` feeds: it resolves
to that variant's loud fill from the shared semantic grid (`var(--lr-color-fill-loud)`), falling back
to `var(--lr-color-brand)` on an element that has not updated yet. It sits _inside_
`--lr-progress-indicator-color` and the upstream `--indicator-color` alias in the fallback chain, so
setting either of those still wins outright and the indicator renders exactly as it did before
`variant` support existed. Set the variant-color slot instead when you want to retheme one semantic
tone while leaving the rest of the grid alone.

**Additional API surface:**

- `--lr-progress-duration` — Indeterminate sweep timing. Default: `var(--lr-transition-ambient)`.

## `lr-progress-ring`

A circular progress indicator with the same value contract as `lr-progress-bar`.

**Properties:** `value: number = 0` (reflected), `max: number = 100`, `indeterminate: boolean = false`
(reflected), `variant: LyraProgressVariant = 'brand'` (reflected, added in 9.0.0 — matches sibling
`lr-progress-bar`'s semantic-palette vocabulary: `neutral`/`brand`/`success`/`warning`/`danger`),
`showValue: boolean = false` (attribute `show-value`),
`label: string = ''` (the mapped accessible-name property), and
`accessibleLabel: string = ''` (attribute `accessible-label`; a Lyra compatibility
accessible-name spelling retained by this progress component, while several sibling components use
`aria-label` directly). Also
`size: LyraSize = 'm'` (reflected) — `'2xs' | 'xs' | 's' | 'm' | 'l' | 'xl' | 'small' | 'medium' |
'large'`. Outer diameter tier, on the shared six-step ladder: `1.25rem` (`2xs`), `1.75rem` (`xs`),
`2.25rem` (`s`/`small`), `2.5rem` (`m`/`medium`, unchanged from before this property existed),
`3rem` (`l`/`large`), `3.5rem` (`xl`) — each value feeds `--lr-progress-ring-size`'s private
default. An explicit `--lr-progress-ring-size` (or the upstream `--size` alias) still wins over
every tier. Matching sibling `lr-progress-bar`'s own `size`, this ladder scales exactly one
dimension — `--lr-progress-ring-track-width`/`--lr-progress-ring-indicator-width` and the center
label's font size are untouched by it. Host
`aria-label` takes precedence; otherwise the name falls back to `label`, `accessibleLabel`, the
visible default- or `label`-slot text when supplied, then the localized "Progress".
Non-finite/out-of-range `value`/`max` are normalized (`max <= 0` falls
back to `100`, `value` clamps to `[0, max]`) rather than producing NaN geometry.
**Slots:** default — replaces the built-in center label, which otherwise renders the rounded
percentage **only when `show-value` is set** (and nothing at all while `indeterminate`); `label` —
named alias for center content, matching `lr-progress-bar`.
**Breaking in 10.0.0:** a determinate ring used to render its percentage unconditionally, with no way
to suppress it short of slotting replacement content. It now gains `showValue`/`show-value` defaulting
to `false`, exactly matching `lr-progress-bar` — which is what "the same value contract as
`lr-progress-bar`" above has always claimed but did not deliver. Add `show-value` to keep the
percentage. `aria-valuetext` still carries it regardless, mirroring `lr-progress-bar`'s own
independence there, so the accessible value is unaffected.
Its accessible text uses the same visibility filtering, forwarding-slot mutation/reassignment
tracking, and explicit-empty host-label precedence as `lr-progress-bar`.
**Live members:** `indicator: SVGCircleElement | null` returns the rendered indicator circle (or
`null` before rendering). `indicatorOffset: number` returns the normalized stroke offset used for
that circle, including the indeterminate value. The indicator node remains stable across ordinary
value updates and reconnection while the offset updates live.
**CSS parts:** `base` and `progress-ring` are aliases on the same progressbar; `track`, `indicator`,
`label`.
**Themeable custom properties:** `--lr-progress-ring-size` (default
`var(--size, var(--_lr-progress-ring-size))`; `--size` is the upstream alias, and the private
`--_lr-progress-ring-size` is the `size` property's own tier value, `2.5rem` at the `m` default,
unchanged — the ring's inline and block size), `--lr-progress-ring-track-width` (default
`var(--lr-theme-progress-ring-track-width, var(--lr-size-4px))` — a dedicated, opt-in theme hook, set
on `:root` or any ancestor to retune this ring specifically; it stays unset, and `4px` applies, whether
or not `theme.css` is imported, unlike the widely-shared `--lr-theme-border-width-thick` this used to
bridge directly, which `theme.css` declares at `3px`),
`--lr-progress-ring-track-color` (default `var(--lr-color-brand-quiet)`),
`--lr-progress-ring-indicator-width` (defaulting to the track width),
`--lr-progress-ring-indicator-color` (default
`var(--lr-progress-ring-indicator-variant-color)`, so the active `variant` supplies the color),
`--lr-progress-ring-indicator-variant-color` (added in 9.0.0, same override precedence as
`lr-progress-bar`'s `--lr-progress-indicator-variant-color` — the palette slot `variant` resolves
into),
`--lr-progress-ring-indicator-transition-duration` (default `var(--lr-transition-base)`), and
`--lr-progress-duration` (default
`var(--lr-transition-ambient)` — the indeterminate spin period, the same token and the same default
as `lr-progress-bar`'s sweep, so it flattens under `prefers-reduced-motion: reduce` with the rest of
the ambient motion).
Upstream aliases are `--size`, `--track-width`, `--track-color`, `--indicator-width`,
`--indicator-color`, and `--indicator-transition-duration`.

## `lr-badge` and `lr-tag`

Compact status labels. `LyraTag` extends `LyraBadge`, so the two share one visual contract; `lr-tag`
adds tag semantics and an optional remove affordance. Both are static text by default, matching the
mirrored upstreams and avoiding repeated announcements when a category badge is re-rendered.
Authors can opt a genuinely changing badge into live semantics with `role="status"`; that and every
other author-supplied role remain authoritative across updates, hydration, and reconnect.

**Visual break in 8.0.0 — a badge is no longer a pill by default.** Both components used to render
fully-rounded ends unconditionally. `--lr-badge-radius` now defaults to `var(--lr-radius)` (a rounded
rectangle) and the pill treatment moved behind the new opt-in `pill` boolean. Existing markup keeps
its corner radius only if you add `pill`, or set `--lr-badge-radius: var(--lr-radius-pill)` once at
the app level.

**Properties** (all are declared by `lr-badge` and inherited by `lr-tag`; `lr-tag` adds the
`variant="text"` spelling plus `withRemove` / `removable`):

- `variant: 'neutral' | 'brand' | 'primary' | 'success' | 'warning' | 'danger' = 'neutral'`
  (reflected) — the semantic palette. `primary` renders through the same brand palette while
  remaining `primary` on property reads, selectors, serialization and reflection. `lr-tag`
  additionally accepts and preserves `text`, rendering the neutral plain treatment.
- `size: '2xs' | 'xs' | 's' | 'm' | 'l' | 'xl' | 'small' | 'medium' | 'large' = 'm'` (reflected) — the same visual-density scale
  `<lr-chip>` uses, for typography/padding/minimum block size; `m` preserves the original badge
  dimensions. Both short and long upstream spellings round-trip verbatim while resolving to the
  same private effective size for rendering.
- `appearance: 'accent' | 'filled' | 'outlined' | 'filled-outlined' | 'plain' = 'filled-outlined'`
  (reflected) — **new in 8.0.0.** The second visual axis: `variant` picks the palette, `appearance`
  decides how much of it lands on the fill, the border and the text. `filled-outlined` (the default)
  is quiet tint + loud border + loud text, i.e. exactly the pre-8.0.0 treatment; `filled` drops the
  border, `outlined` drops the fill, `accent` fills solidly with on-loud text, and `plain` drops both
  fill and border while keeping the label color. The border-less appearances use a `transparent`
  border rather than `none`, so switching appearance never changes the badge's layout box.
- `pill: boolean = false` (reflected) — **new in 8.0.0.** Fully-rounded ends instead of the default
  rounded rectangle; see the visual break above. Since it defaults to `false`, `pill="false"` is not
  a way to switch it off — remove the attribute, or assign `.pill = false`.
- `attention: 'none' | 'pulse' | 'bounce' = 'none'` (reflected) — **new in 8.0.0.** An opt-in,
  infinitely-looping attention animation for a badge that has to be noticed: `pulse` draws an
  expanding ring, `bounce` hops the surface vertically (block-direction, so it needs no RTL
  mirroring). Both stop outright — not merely shorten — under `prefers-reduced-motion: reduce`.
  The default does not materialize an attribute; an explicit `attention="none"` is authoritative
  and suppresses the `pulse` shorthand.
- `pulse: boolean = false` (reflected) — upstream-compatible shorthand for the pulse attention
  treatment while the `attention` attribute is omitted. Any explicit attention value wins. Lyra's
  intentional `variant="neutral"` and `appearance="filled-outlined"` defaults remain unchanged
  because the two pinned upstreams disagree on both defaults.
- `withRemove: boolean = false` (attribute `with-remove`, reflected) — **`lr-tag` only, new in
  8.0.0.** Renders the remove affordance. `lr-badge` never renders one, even if the attribute is
  present on the markup.
- `removable: boolean = false` (attribute `removable`) — **`lr-tag` only.** Shoelace-compatible
  alias for `withRemove`; reading either property reports the shared state. Either authored
  attribute keeps removal enabled until both are absent. Assigning `false` through either property
  clears both attributes, while assigning `true` reflects that property's own spelling.

**Events:** `lr-remove` — noncancelable, no detail, bubbles and composes. Emitted by `lr-tag` only (a
badge emits nothing at all) when the remove button is activated by click or by Enter/Space while
focused; it is a real native `<button>`, so both come for free. Only rendered, and therefore only
fired, while `withRemove` / `removable` is set, and the event's `target` is the tag itself.

Like `<lr-chip>`, a removable `lr-tag` is controlled: activation only announces the request. The
tag remains connected even if a listener calls `preventDefault()` (the event is not cancelable),
and the consumer removes it by updating the collection that rendered it.

If that controlled listener synchronously removes the focused tag, or a direct property write
removes its action, focus moves to the nearest available composed action. Focus explicitly moved by
the listener is preserved.

For a removable tag, `focus(options?)`, `blur()`, and `click()` delegate to its native remove
button. A plain tag's `click()` retains native `HTMLElement.click()` behavior and dispatches one
host `click`; its `focus()` has no delegated target. Setting `withRemove` / `removable` false
revokes remove-button focus and activation synchronously before the outgoing button is rerendered,
so same-task `click()` uses the plain host behavior instead of firing `lr-remove`. `blur()` remains
available during that same-task window so it can release the stale focused button; after render
there is no owner to blur.

**Slots:** default (the label), `start` (content before the label, typically an icon) and `end`
(content after it) — both new in 8.0.0. Each wrapper collapses entirely (`display: none`, so no
stray gap) while its slot is empty, and is seeded from the light-DOM children before the first
render so declarative content never flashes hidden for a frame. Mark purely decorative slotted
content `aria-hidden`.

**CSS parts:** `base` and `badge` are aliases on the same badge/tag surface; `start` and `end` (the slot wrappers, hidden entirely
while empty), `content` (the wrapper around the default slot — this is the part that truncates with
an ellipsis, deliberately not `base`, so the tag's oversized remove hit target can overhang the
compact surface without being clipped), and `remove-button` (`lr-tag` only, rendered only while
`withRemove` / `removable`). The button also carries Shoelace's `remove-button__base` alias, so
either part name styles the same native button.

**Themeable custom properties.** Three layers, so a consumer can retune one without restating the
others. Public hooks are consumed through private use-site defaults instead of being redeclared on
the host, so values set directly or inherited from a theme ancestor both win. The same contract
reaches `lr-tag` unchanged.

_Overrides_ — undeclared by default, so they still inherit from a consumer's own ancestor rule, and
win over whatever `variant`/`appearance` resolved: `--lr-badge-background` (falls back to
`--lr-badge-fill`), `--lr-badge-border` (falls back to `--lr-badge-stroke`), `--lr-badge-color`
(falls back to `--lr-badge-text`).

_Palette — what `variant` chooses_ (new in 8.0.0): `--lr-badge-tint` (private default
`var(--lr-color-surface)`, the quiet fill; each non-neutral variant changes that private default to
`var(--lr-color-fill-quiet)`, which the shared variants sheet has already re-pointed at that
variant's row of the semantic grid), `--lr-badge-solid` (private default
`var(--lr-color-fill-loud)`, the loud fill used by `appearance="accent"`), `--lr-badge-edge`
(private default `var(--lr-color-border)`, the border color), `--lr-badge-ink` (private default
`var(--lr-color-text)`, the text color) and
`--lr-badge-on-solid` (default `var(--lr-color-on-loud)`, the text color that stays legible on
`--lr-badge-solid`). An inherited or direct public palette value remains authoritative. Neutral is
the only variant whose border and text colors differ, which is why `-edge` and `-ink` are separate
slots rather than one loud color.

_Surface — what `appearance` routes onto the box_ (new in 8.0.0): `--lr-badge-fill` (default
`var(--lr-badge-tint)`), `--lr-badge-stroke` (default `var(--lr-badge-edge)`) and `--lr-badge-text`
(default `var(--lr-badge-ink)`). Set one of these to retune a single appearance without touching the
palette.

_Density and shape:_ `--lr-badge-font-size` (default `var(--lr-font-size-sm)`),
`--lr-badge-padding-inline` (default `var(--lr-space-s)`) and `--lr-badge-min-height` (default
`var(--lr-size-1-25rem)`) — the trio each private effective-size rule rewrites to that step's font size,
inline padding and minimum block size; the `m` defaults above exactly reproduce the pre-`size` fixed
badge treatment. `--lr-badge-gap` (default `var(--lr-space-2xs)`, new in 8.0.0) is the space between
the `start` slot, the label and the `end` slot — it collapses on its own when a wrapper is empty,
because the empty wrapper is `display: none` rather than zero-width. `--lr-badge-radius` (default
`var(--lr-radius)`; `pill` raises it to `var(--lr-radius-pill)`) is `[part='base']`'s corner radius,
retunable without a `::part(base)` rule and, unlike the density trio, does not vary by `size` — the
same `--lr-button-radius` pattern.

_Attention_ (all new in 8.0.0): `--lr-badge-attention-duration` (default
`var(--lr-duration-ambient)` — one cycle of the animation), `--lr-badge-attention-easing` (default
`var(--lr-easing-emphasized)` — kept a separate token from the duration so the `animation` shorthand
expands to exactly one timing function), `--lr-badge-pulse-color` (default
`color-mix(in srgb, currentColor 40%, transparent)` — the expanding ring's color; upstream alias
`--pulse-color`),
`--lr-badge-pulse-spread` (default `var(--lr-size-0-25rem)` — how far the ring expands) and
`--lr-badge-bounce-distance` (default `var(--lr-size-0-1875rem)` — the hop's peak travel).

_`lr-tag`'s own two_ (new in 8.0.0): `--lr-tag-remove-radius` (default `var(--lr-badge-radius)`, so
retuning the tag's corner retunes the remove button's with it) and
`--lr-tag-remove-hover-background` (default `color-mix(in srgb, currentColor 16%, transparent)` —
the remove button's `:hover` fill).

**Known gotchas:**

- The remove button's hit target meets the shared `--lr-icon-button-size` minimum in both axes while
  the visible glyph stays compact. Its full allocation participates in layout with no negative
  margins, so adjacent compact tags retain disjoint targets.
- Its accessible name is computed from the default slot's own text ("Remove {label}", localized;
  bare "Remove" for a label-less tag) and re-derived live when that text changes. Text inside the
  decorative `start`/`end` slots never leaks into it. Visible accessible text, forwarding-slot
  reassignment and external assigned-node mutations stay synchronized; hidden/inert/CSS-hidden/
  `aria-hidden` branches are excluded. A host `aria-label`, including an explicit empty value,
  names a single aggregate `role="group"`; it is not copied to the nested action. The remove button
  retains its purpose-specific visible-label/localized-fallback name.
- `appearance` and `variant` are orthogonal: `appearance="plain"` on `variant="danger"` still reads
  as danger, because the palette is chosen before the surface routing.

```html
<lr-badge variant="success" appearance="accent" pill size="s">
  <svg slot="start" aria-hidden="true" width="12" height="12">
    <!-- icon -->
  </svg>
  Live
</lr-badge>

<lr-tag variant="brand" appearance="outlined" with-remove>Design</lr-tag>
<script type="module">
  import "@aceshooting/lyra-ui/components/overlays/badge/badge.js";
  import "@aceshooting/lyra-ui/components/overlays/badge/tag.js";

  document.querySelector("lr-tag").addEventListener("lr-remove", (e) => {
    e.target.remove(); // in an app, update the backing collection instead
  });
</script>
```

## `lr-alert`

A closed-by-default alert that carries the pinned Shoelace alert surface under the `lr-` prefix,
plus one additive Lyra property (`size`) that is inert until you set it.
Use `lr-callout` for Lyra/Web Awesome's always-open inline callout contract; use `lr-alert`
when migrated markup relies on `open`, timed dismissal, countdown, or identity-preserving
`toast()` behavior.

**Properties:**

- `open: boolean = false` (reflected) — controls visibility. Initial `open` markup establishes
  state without a transition event; later property or attribute changes run the full lifecycle
  below.
- `closable: boolean = false` (reflected) — renders a localized close action.
- `size?: LyraSize` (reflected, unset by default) — density tier on the library's one size ladder:
  `'2xs'|'xs'|'s'|'m'|'l'|'xl'`, or the Web Awesome / Shoelace spellings `'small'|'medium'|'large'`,
  which are accepted as authored rather than rewritten to the short form. This is the one Lyra
  addition on top of the pinned Shoelace surface, and it is opt-in for that reason: unset, the panel
  keeps the padding it always had and the text size it inherits, so migrated markup renders
  unchanged. A tier scales the panel padding and text together and takes `lr-callout`'s values for
  both, so a tiered alert and a tiered callout of the same size line up in one column. Their
  **untiered** states are not interchangeable, deliberately: with no `size` this panel keeps a fixed
  gutter and inherits the ambient text size (its exact pre-ladder rendering), while an untiered
  `lr-callout` reads the ambient form-control slots and falls back to the shared `m` padding and
  `--lr-font-size-m`. Pinning a default tier here would resize every alert that shipped before this
  property existed. Two things deliberately do not vary by tier, also matching `lr-callout`: the gap
  separating icon, message and close action (it separates three boxes rather than setting density)
  and the leading icon glyph size (a status affordance bounded by the shared tappable-target token).
  The close action also keeps the shared tappable-target floor at every tier — a WCAG 2.5.8 minimum
  rather than a density knob — and its optical pull-out toward the panel edge is clamped to the
  tier's own gutter, so the two smallest tiers cannot push it through the panel's clipped border. An
  unsupported value normalizes to the omitted state and removes the attribute.
- `variant: 'primary' | 'success' | 'neutral' | 'warning' | 'danger' = 'primary'` (reflected) —
  `primary` resolves through Lyra's shared brand semantic tokens. Unsupported attributes and
  untyped property writes normalize to reflected `primary`.
- `duration: number = Infinity` — milliseconds before automatic dismissal. `Infinity` stays open;
  hover or focus pauses the timer, and leaving interaction restarts the full duration.
- `countdown: 'rtl' | 'ltr' | undefined` (reflected, unset by default) — adds a decorative visual
  bar that empties in the requested physical direction. Its motion is removed under
  `prefers-reduced-motion: reduce`. Unsupported attributes and untyped property writes normalize
  to the omitted state and remove the attribute.
- `role: string | null = 'alert'` (reflected) — the light-DOM semantic owner. The default is a
  reactive initial value, so SSR/no-JS output serializes it before `connectedCallback`; an authored
  alternate role such as `status` remains authoritative.

**Methods:** `show(): Promise<void>` and `hide(): Promise<void>` resolve after their respective
after-event. `toast(): Promise<void>` moves the same alert instance into Lyra's singleton logical
top-end toast region, shows it, and resolves after it hides and is removed. Keep the reference to
reuse the same identity with another `toast()` call. An alert adopted into another same-origin
document uses that document's toast region, timers, motion preference, and focus realm. If external
DOM reconciliation removes a toast without hiding it, the pending promise settles after that
disconnect proves lasting (a synchronous move into the toast region does not count), stale
listeners are released, and a later `toast()` starts a fresh lifecycle.
The region admits three active alerts and twenty hidden/inert queued alerts in FIFO order. An
already-open alert also becomes explicitly hidden and inert while queued; promotion preserves that
accepted state without replaying `lr-show`. If focus was inside that surface, queue admission repairs
it to an available adjacent control without overriding a newer external focus destination. An initial
`lr-show` veto removes and settles that toast attempt; a later `toast()` uses a fresh promise and can
retry. Re-entering `show()` or the same `open` request during the before-event coalesces, so an outer
veto cannot be bypassed by a nested request.
In an adopted document without an upgraded bounded toast controller, `toast()` fails closed by
removing the unavailable request and settling its unchanged `Promise<void>` rather than appending to
an unbounded fallback element. Region ownership is reasserted when an alert moves between stacks;
stale observations from its previous stack cannot change its active/queued state. A lasting region
disconnect discards managed work, so reconnecting that old region cannot resurrect an already-settled
alert toast.

**Events:** `lr-show`, `lr-after-show`, `lr-hide`, and `lr-after-hide` all bubble, compose, carry no
detail. `lr-show` and `lr-hide` are cancelable veto points; their `lr-after-*` counterparts are
noncancelable. A transition interrupted by the opposite state does not emit the stale after-event.
When an accepted hide removes the focused close action, focus moves to the nearest available
composed action. A veto keeps focus in place, and a listener-selected external destination wins.
An accepted show/hide interrupted by a same-task move resumes and emits exactly one matching
after-event before its method resolves. A lasting disconnect settles the method without emitting on
the detached node; reconnecting the same inline alert later resumes the pending terminal lifecycle
once. Toast-owned work instead settles and is discarded when its region disconnect proves lasting.

**Slots:** default message content; `icon` for an optional decorative leading icon whose flattened
subtree remains visible but is inert and aria-hidden.

**CSS parts:** `base`, `icon`, `message`, and `close-button` / `close-button__base` on the same
native close button. The pinned surface exposes no custom states, form association, native-event
relays, or delegated native methods.

**Themeable custom properties:** the close button's two state hooks are
`--lr-alert-close-hover-bg` (its `:hover` surface; default `color-mix(in oklab, transparent,
var(--lr-color-mix-partner) var(--lr-color-mix-hover))`) and `--lr-alert-close-active-bg` (its
`:active` surface, scoped independently from the hover property; default `color-mix(in oklab,
transparent, var(--lr-color-mix-partner) var(--lr-color-mix-active))`). Each is an inline fallback
at the relevant state, so setting one on the alert or an ancestor rethemes only that close-button
state.

By default the light-DOM `<lr-alert>` host owns `role="alert"`, so initially-open/static alerts and
alerts shown later expose one assertive, content-derived semantic surface without duplicating it in
a shadow or shared live region. The role is present in server output; an explicit authored role is
preserved. The optional icon wrapper remains visible, but its flattened subtree is inert
and `aria-hidden`; the close action remains independently accessible through Lyra's localized
`close` string. Layout uses logical properties, wraps unbroken content at 320px, and the toast path
reuses the existing Lyra toast layer instead of creating a second placement system.

```html
<lr-alert
  id="session-alert"
  closable
  duration="10000"
  countdown="rtl"
  variant="warning"
>
  <svg slot="icon" aria-hidden="true"><!-- warning icon --></svg>
  Your session will expire soon.
</lr-alert>
<button type="button" onclick="document.querySelector('#session-alert').show()">
  Show alert
</button>

<script type="module">
  import "@aceshooting/lyra-ui/components/overlays/alert/alert.js";

  const alert = document.querySelector("#session-alert");
  alert.addEventListener("lr-after-hide", () => console.log("Alert is hidden"));
</script>
```

## `lr-callout`

An inline status, warning, or error surface. Set `inline` for lightweight reactive form or mutation
errors without panel chrome.

**Properties:** `variant: 'neutral'|'brand'|'success'|'warning'|'danger' = 'brand'` (reflected when
explicit — an unset nested callout inherits its ancestor's semantic colour context without
materializing a `variant` attribute. Explicitly writing even the same-default `brand` materializes
the attribute and pins the local brand palette; removing the attribute restores contextual
inheritance),
`appearance: 'accent'|'filled'|'outlined'|'plain'|'filled-outlined'` (reflected, with no explicit
default — when set, controls how much of the active variant palette is spent on fill, border, and
text; leaving it unset preserves the established quiet-fill/loud-edge treatment),
`size: LyraSize = 'm'` (reflected when explicit — **new in 8.0.0**; visual density on the library's shared ladder,
accepting both spellings of the aliased tiers (`s`/`small`, `m`/`medium`, `l`/`large`) so markup migrated
from `wa-callout` needs no attribute rewrite. An unset nested callout inherits its ancestor's size
context; standalone fallback is `m`. Explicitly writing even the same-default `m` pins the local
medium mapping, and removing the attribute restores contextual inheritance), `heading: string = ''`,
`headingLevel: LyraHeadingLevel = '3'` (attribute `heading-level`, reflected; `1`–`6` expose the
property and rich-slot heading wrapper at that semantic level, invalid untyped values retain level
3, and `none` is the visual-only opt-out),
`closable: boolean = false` (reflected), `inline: boolean = false` (reflected),
`announce: boolean = false` (reflected — opts the callout into announcing the content it already
carries when it first mounts; see the announcement paragraph that closes this section),
`open: boolean = true`
(reflected as a presence attribute — `open="false"` is accepted in plain markup; `false` removes the
semantic content and hides the host surface), and `accessibleLabel: string = ''`
(`accessible-label`; used only when the host has no `aria-label` attribute). A host `aria-label`
has highest precedence by presence, including an explicitly empty value.

Every reflected closed set normalizes identically from markup and untyped JavaScript writes:
unsupported `variant`, `size`, and `heading-level` values become reflected `brand`, `m`, and `3`,
while an unsupported `appearance` becomes the omitted state.

**Events:** cancelable `lr-close` (no detail); the callout sets `open = false` after the event
unless a listener calls `preventDefault()`.
When accepted close or a direct `open = false` write removes the focused close action, focus moves
to the nearest available composed action. Vetoed close and newer external focus are preserved.

**Slots:** default message, `heading` (rendered alongside the `heading` property inside the
configured semantic heading wrapper), `icon`.

**CSS parts:** `base` (the transparent grid wrapper inside the host-owned surface), `icon`
(hidden while the `icon` slot is empty), `content`, `heading`,
`message` (wrapper around the default slot), `close-button` (the close control, always
at least `--lr-icon-button-size` in both the panel and `inline` treatments), `close-button__control`,
`close-icon` (the visible "×" glyph inside it — this is what shrinks under `inline`, so the hit
target never does).

As of 16.0.0 the close control is a composed `<lr-icon-button>`: `close-button` names that host —
it still owns the grid placement, the accessible name and the click/focus API — while
`close-button__control` is its own native `<button>`, where the background, radius, hover/press
fill, focus ring and hit-area floor are painted. A rule that sets `background`, `border`,
`padding` or `outline` through `::part(close-button)` must move to `::part(close-button__control)`
or, better, to the `--lr-icon-button-*` tokens, which reach it the same way they reach a standalone
icon button. Layout-only rules (`margin`, `grid-column`, `order`, `display`) keep working on
`close-button` untouched.

The surface chrome lives on the custom-element host, not inside `base`. Ordinary host
`background`, `border`, `border-radius`, `color`, `padding`, and `margin` declarations therefore
work directly and take normal author precedence. `inline` removes the host's border, background,
and padding.

**Migrating a pre-16.0.0 `::part()` rule.** This component's icon-only action is a composed
`<lr-icon-button>`, so the part naming that action now names the composed child's HOST, which
paints nothing. A `border`, `background` or `border-radius` set on it is silently dead — only
`color` still appears to work, because it inherits, which makes such a rule look half-alive rather
than broken. Set `--lr-icon-button-background`/`-color`/`-border`/`-radius` (and their
`-hover`/`-active` variants) on this element or an ancestor instead: the composed control reads
those public tokens ahead of any default this component supplies. For SIZE use
`--lr-theme-icon-button-size`, not `--lr-icon-button-size` — every `LyraElement` re-declares the
latter on its own `:host`, so it never reaches a composed child (see `llms/tokens.md`).

**Themeable custom properties:** `--lr-callout-background`, `--lr-callout-color`, and
`--lr-callout-border` read the inherited generic semantic quiet/loud slots, with brand quiet/loud
as their standalone fallback. An explicit `variant` maps all generic slots locally; leaving it
unset preserves an ancestor's mapping. Explicit `appearance` works with either source and uses the
same brand fallback when there is no surrounding context. Public callout hooks are consumed at use
sites through private defaults, so a value inherited from a theme ancestor has the same authority
as one set directly on the callout. `--lr-callout-close-hover-bg`
(default `var(--lr-color-brand-quiet)`) — the close button's `:hover` background, deliberately
decoupled from `--lr-callout-background` (which every explicit `variant`, including `neutral`,
retargets for the panel itself) so a consumer can retint the hover fill — e.g. to keep it visibly distinct from a
`variant="brand"` panel, which shares the same default token — without a collateral effect on the
panel background, and vice versa.

Three more, all new in 8.0.0: `--lr-callout-font-size` (private default
`var(--lr-form-control-font-size, var(--lr-font-size-m))` — the callout's text size; each explicit
`size` tier maps that private default from the shared ladder), `--lr-callout-padding` (private
default `var(--lr-form-control-padding-inline, var(--lr-space-m))` — the panel's padding on _both_
axes; each `size` tier changes that private default from the ladder's inline-padding knob, because
a panel's block rhythm is generous like a control's inline padding rather than tight like its block
padding, which only exists to fit text inside a fixed control height). The padding hook applies to
the panel treatment; `inline` intentionally forces host padding to zero. Inherited or direct public
font-size values remain authoritative in either treatment, while inherited/direct padding is
authoritative only for the panel.
`--lr-callout-gap` (default `var(--lr-space-s)` — the space between the icon, the
content and the close action. It deliberately does _not_ vary by `size`: it separates three adjacent
boxes rather than setting the panel's density, and shrinking it at the small tiers only crowds
them).

Initial content and initially distributed slots are silent. After that first render/slot
distribution settles, heading-property changes and direct or nested default/heading-slot additions,
removals, and text changes are appended to Lyra's shared light-DOM polite sink (`assertive` for
`danger`). An unset callout resolves that urgency from the nearest composed ancestor carrying an
explicit semantic `variant`, matching the palette it inherits without inspecting computed RGB.
Ancestor changes, removal, reconnect, and adoption are resolved live; an explicit local variant
pins both presentation and urgency. Announcement text is whitespace-normalized, honors meaningful `aria-label` values, and
excludes the icon/close chrome plus content hidden by `hidden`, `inert`, or `aria-hidden="true"` at
any nested level. `display:none`/`content-visibility:hidden` prune a branch; a
`visibility:hidden|collapse` wrapper suppresses its own text while a descendant that restores
`visibility:visible` remains exposed. Updates while the host or a composed ancestor is hidden also
stay silent. Nested forwarding slots expose their flattened assigned text instead of fallback
content, and later assignment plus assigned-node text/style/visibility mutations are observed.
Mutations that leave that accessible text unchanged are deduplicated. A nonempty host
`aria-label` (or `accessible-label` fallback) prefixes visible update text as context, with an
equality check preventing duplicate copy. The complete localized
`calloutAnnouncementWithContext: '{context}: {content}'` message owns both fields, their order, and
punctuation; override that key through `strings` rather than prejoining either field. An explicitly
empty host label still leaves visible heading/message text live.
`[part="base"]` is an ordinary wrapper, upgraded to a non-live `role="group"` only when it has an
accessible label. Initial connection, reconnection, adoption, and detached changes that settle
during staging stay silent; each connection acquires its owning document's shared sink.

Set `announce` when the callout is created in response to something the user just did — a save
failure, a validation result — and nothing else would read the message aloud. It announces the
content the callout already carries the first time it mounts, through the same path a later update
takes: assertive for `danger` (including a `danger` inherited from a composed ancestor) and polite
otherwise, the same `hidden`/`inert`/`aria-hidden`/CSS-hidden and hidden-ancestor exclusions, the
same flattened text through nested forwarding slots, and the same complete localized
`calloutAnnouncementWithContext` composition when the host carries a nonempty label. A closed
callout (`open="false"`) announces nothing. `announce` is read once, when the callout first mounts:
a later reconnection or adoption stages the existing content again rather than replaying the
announcement, and later content updates are announced whether or not it is set. Leave it unset for
a callout that is simply part of the page a user is arriving on — that text is already read in
document order, and announcing it again is noise. If a consumer previously hand-added a host
`role="status"`/`role="alert"` to work around the missing initial announcement, remove it once
`announce` is set: leaving both in place announces the same initial text twice, once through the
native role and once through the shared sink.

## `lr-rating`

A keyboard-accessible star rating control with slider semantics. It is a **form-associated control**
that lives in this family rather than in `components/forms/` — if you came looking for it among the
form controls, this is its section. Everything the "Form association" section says about `name`,
submission, validity and the `user-*` custom states applies to it.

Readonly transitions synchronize validity and `aria-invalid` in the same completed update. Form
reset restores the independent `default-value` rather than the live `value` attribute.

It is form-associated through `ElementInternals` directly rather than through the shared
`FormAssociated` mixin, because its `value` is a number and the mixin's contract assumes a plain
string — routing through it would force every consumer into string round-tripping for what is
natively a numeric score. The submitted entry is the clamped value stringified (`"0"` while
unrated), and `required` reports `valueMissing` until a rating above zero is set. The `value`
content attribute and IDL property both control the live score. `defaultValue` and its
`default-value` attribute independently own the reset target that `form.reset()` restores.

**Properties:** live `value: number = 0` (attribute `value`);
`defaultValue: number = 0` (attribute `default-value`, the current reset target); `customError: string |
null` (attribute `custom-error`); `max: number = 5`; `precision: number = 1`;
`readonly: boolean = false` (reflected), `disabled`, `required`, `name`,
`size: '2xs'|'xs'|'s'|'m'|'l'|'xl'|'small'|'medium'|'large' = 'm'` (reflected — changes the private
fallback behind `--lr-rating-size` from a type ramp rather than the shared control ladder, since a
rating has no control frame to size; an inherited or direct public size wins; the `m` default
reproduces the treatment this component had before `size` existed; valid long-form spellings
round-trip unchanged), plus two separate naming knobs:
`accessibleLabel: string = ''` (property) and `label: string = ''` (attribute
`label`). An authored host `aria-label` wins by attribute presence, including an explicitly empty
value. Without one, a non-empty external `<label for>` names the host; `accessibleLabel`, `label`,
then the localized name are the fallback order when no external label supplies text. Clicking an
associated external label focuses the host-owned slider without changing its value. Neither
property is visible label text, since a rating is a bare row of symbols with no field frame of its
own; wrap the element in your own layout for a labelled field, exactly as `<lr-slider>` does.

For the managed slider name only, an empty or whitespace-only `label` counts as absent and falls
through to localized `rating`; the raw `label` property still reads exactly as assigned. An
associated external label and an authored `aria-label`, including `aria-label=""`, keep their
existing precedence and are never replaced by that fallback.

**Static constructor API:** `LyraRating.validators` is the mirrored callable validator catalog.
Each access returns a fresh `LyraFormValidator<LyraRating>[]`; its entry observes
`required`/`disabled`/`readonly`/`value`/`max`, and `checkValidity(element)` projects the element's
current `ValidityState` into `{ isValid, message, invalidKeys }` without changing it.

```ts
import { LyraRating } from "@aceshooting/lyra-ui/components/overlays/rating/rating.js";

const rating = document.querySelector("lr-rating")!;
const result = LyraRating.validators[0].checkValidity(rating);
```

The host is the one focusable `role="slider"` owner and carries `tabindex`, its accessible name,
`aria-valuemin`/`aria-valuemax`/`aria-valuenow`/`aria-valuetext`, and explicit true/false disabled,
readonly and required states. The shadow star row is `aria-hidden` presentation only, so custom
host ARIA never creates a competing second slider.

Assigning `null` to `name` is accepted for mapped source compatibility; it removes the attribute and
clears to the canonical `''` read value rather than creating a nullable state.

`getSymbol?: (value: number, selected: boolean) => unknown` (property only, no attribute) — **new in
8.0.0.** Renders a consumer-supplied symbol per position instead of the built-in star. It is called
_twice per position_: once for the empty backdrop (`selected` false) and once for the overlay
clipped to that position's filled fraction (`selected` true), which is what keeps a fractional
`precision` rendering a partial fill. Return any Lit-renderable value; a plain string renders as
text, never as markup. Renderer output is decorative, inert, and pointer-transparent, so it cannot
become a second focus or action target; pointer and keyboard selection stay on the rating control.
Left unset, the built-in star outline/solid pair is unchanged.

**Events:**

- `change` — a native `Event` (bubbling, composed, non-cancelable, and carrying no `detail`) emitted
  when a user commits a genuinely new value. It fires immediately before `lr-change`; read the
  numeric score from `event.target.value`. Programmatic `value`/`defaultValue` writes, reset/state
  restore, and gestures that clamp to the current value are silent.
- `lr-change` — `detail: { value }`. The rating was committed to a new value. Not emitted when the
  clamped value is unchanged, nor on a programmatic `value` write. It fires immediately after the
  native `change` event for the same user commit.
- `lr-activate` — `detail: { value }`, the committed rating. Fired on **every** interactive commit
  (a click on a symbol, or an Arrow/Home/End key), whether or not the value actually moved.
  Bubbling, composed, not cancelable — it reports that the user committed a rating and gates
  nothing. Use it for the re-commit of the current rating that `lr-change` deliberately stays silent
  for; from the keyboard that case is otherwise unobservable, because End on an already-maximum
  rating, Home on an already-zero one, or an arrow key at either bound commits a rating and produces
  no click at all. When the commit _does_ move the value, `change` and `lr-change` are emitted
  first, so a listener reading `value` from any of the three sees the settled rating. A
  non-interactive (`readonly`/`disabled`) rating fires none of them.
- `lr-hover` — **new in 8.0.0.** `detail: { phase: 'start' | 'move' | 'end', value }`, where `value`
  is the rating that committing the current pointer position _would_ produce — enough to render a
  live description of what is being hovered without waiting for a click. Fires only while the rating
  is settable (neither `disabled`, fieldset-disabled, nor `readonly`). `start` also covers a pointer
  that reaches the symbols without a `pointerenter` the component saw; `end` fires on
  `pointerleave` **and** on `pointercancel` (a touch drag taken over by scrolling, palm rejection),
  so an interrupted gesture never leaves the preview frozen. A disconnect or a disablement drops the
  preview silently, with no `end` phase — that teardown wasn't user-driven.
- `focus` / `blur` — the host-owned slider's ordinary native focus transitions. Like native focus
  events, they do not bubble; listen on the rating itself (or use capture on an ancestor).
- `lr-invalid` — no detail; fired when a validity check finds the rating invalid.

**Methods:** `focus()`, `blur()` and `click()` operate on the host-owned slider and are gated while
disabled. `rating: HTMLElement | null` is the live presentational symbol row (the element carrying
the `rating`/`base` parts), or `null` before rendering; its identity remains stable across ordinary
updates and reconnection.
`getForm()` returns the browser-resolved owning form. `checkValidity()` and `reportValidity()`
behave as on a native form control — `reportValidity()`
additionally shows the browser's validation UI, and counts as interaction, so a failed submit is
what starts `user-invalid` matching. `setCustomValidity(message: string)` sets a consumer-supplied
rejection no client-side constraint can express ("you have already rated this item"): a non-empty
message raises `customError` and becomes `validationMessage`, so the control fails
`checkValidity()`, blocks submission and matches `:state(invalid)`. It is caller-supplied content,
so it is used verbatim and never localized. `setCustomValidity('')` clears it and restores the
control's _computed_ validity rather than forcing it valid — a `required` control that is still
unrated stays `valueMissing`. Like a native control, the custom error survives every intrinsic
recomputation in between (each `value`/`max`/`required` change re-runs validation) and a
`form.reset()`; `setCustomValidity('')` or `resetValidity()` clears it.

**Reset and state restore.** A live `value` or `value`-attribute write updates the current score;
later `defaultValue`/`default-value` mutations update the reset target without overwriting that
live score. `form.reset()` restores the current default, drops any
in-flight hover preview, and returns the control to pristine, so the `user-valid`/`user-invalid`
states stop matching even though a required-and-unrated control is still `invalid`. Browser session
restore (`formStateRestoreCallback`) reinstates the previously submitted numeric value; a
non-string restored state falls back to `0` rather than producing NaN geometry.

**Custom states:** `required`, `optional`, `valid`, `invalid`, `user-valid`, `user-invalid` —
`lr-rating:state(user-invalid)` is the one to paint red. Plain `invalid` matches a pristine
`required` rating that has never been set.

**CSS parts:** `base` (compatibility name for the presentational symbol row; use `rating`),
`rating` (the presentational symbol row; it is the same node as `base`), `star` (each rendered symbol), `star-fill` (the
filled overlay inside each symbol, clipped to that symbol's filled fraction — 0%, a partial
percentage under a fractional `precision`, or 100%).

**Themeable custom properties:** `--lr-rating-fill` (default `--lr-color-warning` — filled-symbol
color), `--lr-rating-empty-color` (default `--lr-color-border` — unfilled-symbol color, also
retained during hover preview), `--lr-rating-active-color` (default: the existing active mix of the
empty-symbol color — pressed-symbol color only), `--lr-rating-size` (default `--lr-font-size-xl` —
symbol size; its private default follows each `size` step while a public value wins), and
`--lr-rating-gap` (default
`--symbol-spacing`, then `--lr-space-xs` — gap between symbols). The mapped compatibility hooks
are `--symbol-color` (inactive symbols), `--symbol-color-active` (filled symbols), `--symbol-size`
(symbol size), and `--symbol-spacing` (the gap around symbols). The Lyra-prefixed color, size, and
gap names win if both a Lyra property and its compatibility alias are set. `--symbol-size` otherwise
feeds the active `size` step, while `--symbol-spacing` remains the fallback for
`--lr-rating-gap` before the shared `--lr-space-xs` default.

Pointer selection resolves the position within the clicked star and snaps upward to `precision`
(with the physical fraction mirrored under RTL), so half/quarter-star precision applies to pointer
input as well as keyboard/value updates. The host-owned slider's presentational symbol row keeps a
40×40px minimum activation area even for the degenerate `max=0`/`max=1` cases; larger ratings
naturally grow wider, while symbols may shrink within a narrow allocation instead of forcing the
host beyond its container.

```html
<lr-rating
  name="score"
  label="Overall rating"
  default-value="2"
  max="5"
  precision="0.5"
  size="l"
  style="--lr-rating-active-color: var(--lr-color-success); --lr-rating-gap: var(--lr-space-s); --symbol-color-active: var(--lr-color-success); --symbol-size: var(--lr-font-size-2xl)"
></lr-rating>
<p id="preview"></p>
<script type="module">
  import "@aceshooting/lyra-ui/components/overlays/rating/rating.js";

  const rating = document.querySelector("lr-rating");
  const preview = document.getElementById("preview");
  rating.getSymbol = (value, selected) => (selected ? "♥" : "♡");
  rating.addEventListener("lr-hover", (event) => {
    const { phase, value } = event.detail;
    preview.textContent = phase === "end" ? "" : `Rate ${value}`;
  });
  rating.addEventListener("change", (event) =>
    console.log("native commit", event.target.value)
  );
  rating.addEventListener("lr-change", (event) =>
    console.log("committed", event.detail.value)
  );
</script>
```

## Exported TypeScript contracts

These named interfaces and helper signatures are available to typed integrations. They are grouped by capability so the component sections above can stay focused.

- **`components-overlays-chip-chip-group-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/overlays/chip/chip-group.class.js`.
  `ChipGroupOverflowToggleDetail {
    expanded: boolean;
  }`

- **`components-overlays-chip-chip-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/overlays/chip/chip.class.js`.
  `ChipRemoveDetail {
    value?: string;
  }`
  Import: `@aceshooting/lyra-ui/components/overlays/chip/chip.class.js`.
  `ChipSelectDetail {
    value?: string;
    selected: boolean;
  }`

- **`components-overlays-dialog-confirm-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/overlays/dialog/confirm.js`.
  `confirm(options: ConfirmOptions): Promise<boolean>`
  Import: `@aceshooting/lyra-ui/components/overlays/dialog/confirm.js`.
  `ConfirmOptions {
    title: string;
    description?: string;
    confirmLabel?: string;
    cancelLabel?: string;
    variant?: 'neutral' | 'danger';
  }`

- **`components-overlays-dialog-dialog-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/overlays/dialog/dialog.class.js`.
  `LyraDialogHideDetail {
    source: Element;
  }`
  Import: `@aceshooting/lyra-ui/components/overlays/dialog/dialog.class.js`.
  `LyraDialogModalController {
    activateExternal(): void;
    deactivateExternal(): void;
  }`
  Import: `@aceshooting/lyra-ui/components/overlays/dialog/dialog.class.js`.
  `LyraDialogRequestCloseDetail {
    source: LyraDialogRequestCloseSource;
  }`

- **`components-overlays-kbd-kbd-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/overlays/kbd/kbd.class.js`.
  `KbdKeyLabel {
    visual: string;
    word: string;
  }`
  Import: `@aceshooting/lyra-ui/components/overlays/kbd/kbd.class.js`.
  `parseShortcut(keys: string, isMac: boolean, localize?: KbdLocalize): KbdKeyLabel[]`
  Import: `@aceshooting/lyra-ui/components/overlays/kbd/kbd.class.js`.
  `shortcutTokenLabel(rawToken: string, isMac: boolean, localize?: KbdLocalize): KbdKeyLabel`

- **`components-overlays-toast-toast-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/overlays/toast/toast.class.js`.
  `LyraToastOptions {
    message: string;
    placement?: LyraToastPlacement;
    ownerDocument?: Document;
    variant?: LyraToastVariant;
    duration?: number;
    size?: LyraSize;
    withIcon?: boolean;
    icon?: LyraToastIcon;
    action?: {
      label: string;
      onClick: (item: LyraToastItem) => void;
    };
  }`
  Import: `@aceshooting/lyra-ui/components/overlays/toast/toast.class.js`.
  `LyraToastOverflowDetail {
    count: number;
  }`

- **`components-overlays-toast-toaster-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/overlays/toast/toaster.js`.
  `toast(input: LyraToastOptions | string): ToastHandle`
  Import: `@aceshooting/lyra-ui/components/overlays/toast/toaster.js`.
  `ToastHandle {
    item: Promise<LyraToastItem>;
    dismiss: () => void;
  }`

# Utilities, formatting & observers (`components/utility/`)

## Breaking changes in 9.0.0

TypeScript-only rename (no attribute/property/default change): `lr-divider`'s exported
`DividerOrientation` type is now `LyraDividerOrientation`.

TypeScript-only renames (no attribute/property/default change) across the `lr-format-number`/
`lr-format-date`/`lr-format-bytes`/`lr-relative-time` family: `FormatNumberType`,
`FormatNumberNotation`, `FormatCurrencyDisplay`, `FormatBytesUnit`, `FormatDisplay`, `FormatDateHour`,
`FormatDateStyle`, `FormatDateText`, `FormatDateNumeric`, `FormatDateMonth`, `FormatDateTimeZoneName`,
`RelativeTimeNumeric`, and `RelativeTimeUnit` are now `Lyra*`-prefixed equivalents.

## `lr-export-button`

CSV/JSON download button with extensible event-driven formats — either single-format (click exports
immediately) or multi-format (click opens a small menu).

**Properties:**

- `rows: readonly Readonly<Record<string, unknown>>[] = []` (attribute: false) — assignment takes
  shallow frozen snapshots of the collection and row records; nested cell values remain opaque; the
  built-in download reads this **after** the cancelable `lr-export` event, so a listener that lets
  the download proceed may assign `.rows` from inside its own handler and that data is what gets
  downloaded
- `columns: readonly Readonly<LyraCsvColumn>[] = []` (attribute: false) — assignment takes a
  shallow frozen snapshot. `{ key, label }` acts as a field allow-list **and**
  CSV header-label source for **both** export formats when non-empty. Left empty, **both** CSV and
  JSON fall back to the union of the rows' own keys (`key`/`label` both set to the key name) instead
  of CSV degrading to a header-less/blank file while only JSON had a fallback — so an unconfigured
  export still produces a proper header + data file in either format
- `filename: string = 'export'`
- `getRows?: () => readonly Record<string, unknown>[]` (attribute: false) — lazy row source,
  consulted only when a built-in CSV/JSON download is actually about to be built: after a
  non-prevented `lr-export`, and never for a custom format this component does not serialize itself.
  When set it replaces `rows` for that download, so a consumer can export a collection it already
  holds — an `<lr-table>`'s `viewRows`, say — without copying it into this element and keeping a
  second live copy. The `columns` fallback derives its header row from the lazily supplied rows. A
  non-array return is treated as no rows, matching how `rows` normalizes one; a callback that throws
  is reported through `lr-export-error` and the shared failure announcement, since an export whose
  data could not be collected has failed
- `bom: boolean = false` (reflected) — prepends a UTF-8 byte-order mark (U+FEFF) to the built-in
  CSV download only. Excel on Windows ignores a downloaded file's MIME charset and decodes a
  BOM-less CSV with the system ANSI code page, so accented, Arabic, CJK, and typographic characters
  render as mojibake; the BOM makes Excel detect UTF-8 and decode correctly. Google Sheets,
  LibreOffice, and Numbers already sniff UTF-8 correctly with or without it, so leaving this `false`
  changes nothing for them. Never applies to the built-in JSON download — RFC 8259 forbids a BOM
  there
- `formats: readonly LyraExportFormatOption[] = ['csv']` (attribute: false; shallow frozen
  snapshot), where
  `LyraExportFormatOption` is the built-in `LyraExportFormat = 'csv' | 'json'` or a
  `LyraExportFormatDescriptor = { formatId: string; label: string; description?: string;
extension?: string }`. Descriptor labels/descriptions are consumer-supplied, already-localized
  copy. `formatId` must be nonempty and unique; malformed options and later duplicates are omitted
  first-wins before menu state, focus reconciliation, or export events. Custom format ids are
  event-only; no custom encoder is bundled
- `size?: LyraSize` — optional density on the shared `2xs` through `xl` ladder, including the
  `small`/`medium`/`large` aliases. It changes trigger and menu-row typography and padding while
  retaining the shared 40px minimum hit-area floor. Unset preserves the established geometry
- `appearance?: LyraExportButtonAppearance` — `outlined` or `quiet` trigger treatment. Unset
  preserves the established surface, border, and text colors
- `disabled: boolean = false` (reflected) — also disables every `[part="menu-item"]` button, not just
  the trigger
- `loading: boolean = false` (reflected) — controlled busy state for an async or server-generated
  export; sets host/trigger `aria-busy` and disables the trigger and menu items. The component does
  not toggle it automatically
- `label?: string` — trigger button text; omission uses the localized `exportButtonLabel` default.
  Every supplied string, including `''` and `'Export'`, remains caller-owned visible copy. An empty
  or whitespace-only visible label keeps the localized default as the trigger's accessible name;
  the effective accessible name also feeds the format-choice menu's localized name
- `accessibleLabel: string | null = null` (attribute `aria-label`) — overrides the trigger's
  accessible name and feeds the localized format-menu name without changing the visible label.
  Presence is authoritative, so an explicit empty string is preserved; `null` restores naming from
  a nonempty visible label or the localized fallback
- `open: boolean = false` (reflected)

**Methods:** `focus(options?)`, `blur()`, and `click()` forward to the native trigger button.

**Events:** `lr-export` (`detail: { format: string }`, **cancelable** — call `preventDefault()` to
substitute your own server-generated download instead of the built-in client-side one; the rows a
non-prevented built-in download serializes are read **after** this dispatch, so `.rows` assigned from
inside the listener still reaches it, and `getRows` is consulted at the same point),
`lr-export-complete` (`detail: { format: 'csv' | 'json' }`, fires only after a non-cancelled
built-in download completes), `lr-export-error` (`detail: { format: 'csv' | 'json', error:
unknown }`, fires when a built-in export cannot be serialized or downloaded; the same failure is
also shown via the trigger's `trigger-error` part and announced through the shared light-DOM live
region, so a listener is needed only for additional handling; activation does not throw into
consumer code), `lr-show`, `lr-hide` (cancelable format-menu visibility transitions; self-imposed
closes caused by disablement, loading, or an unusable format list emit neither event)

**Slots:** none.

**CSS parts:** `trigger`, `trigger-error` (present alongside `trigger` on the same button —
`part="trigger trigger-error"` — after a built-in CSV/JSON export fails; cleared on the next export
attempt regardless of outcome — style with `::part(trigger-error)`), `menu`, `menu-item`,
`format-label`, `format-description`

**Themeable custom properties:** the trigger's paint is settable per state. At rest,
`--lr-export-button-background`, `--lr-export-button-color` and `--lr-export-button-border`; on
hover, `--lr-export-button-hover-background`, `--lr-export-button-hover-color` and
`--lr-export-button-hover-border`; while pressed, `--lr-export-button-active-background`,
`--lr-export-button-active-color` and `--lr-export-button-active-border`. Each layers over whatever
the current `appearance` resolves to and leaves the other paints alone, so they are also the way to
keep `appearance="outlined"` chrome while returning its label to neutral text — `outlined` paints
the label `--lr-color-brand` and, unlike `lr-button`, this component has no `variant` of its own to
opt out. Before 18.4.0 none of these existed and the only lever was `::part(trigger)`. Plus shared
tokens, including `--lr-popover-viewport-clamp` (default `92vw`) — the shared narrow-viewport ceiling the `menu`'s max-inline-size is `min()`ed
against, alongside its own `20rem` cap and the positioner's available space. See `lr-tour` for the
shared-clamp note.

The menu popup is a floating surface and paints from the **shared overlay-surface family** (16.0.0):
`--lr-overlay-surface` (default `var(--lr-color-surface-overlay)`), `--lr-overlay-border` (default
`var(--lr-color-border)`) and `--lr-overlay-shadow-anchored` (default `var(--lr-shadow-m)`). None is
declared on `:host`, so one declaration on `:root` — or on any ancestor, to scope it — retints this
surface together with every other floating surface in the library. `--lr-overlay-radius` (default `var(--lr-radius)`) is the matching corner radius.

`--lr-positioning-strategy` (16.0.0) — the format menu reads this same cascading `absolute`/`fixed`
override documented on `<lr-popover>` when it is (re)positioned, falling back to its own `fixed`
default when nothing is set. There is no per-instance `positioning-strategy` property on
`<lr-export-button>`; set the custom property on `:root`, a theme, or one clipping ancestor to
change every unset export button beneath it.

**Optional peer deps:** none.

```html
<lr-export-button id="exp" filename="report" label="Export"></lr-export-button>
<script type="module">
  const exp = document.getElementById("exp");
  exp.rows = [{ name: "Alpha", value: 1 }];
  exp.columns = [
    { key: "name", label: "Name" },
    { key: "value", label: "Value" },
  ];
  exp.formats = ["csv", "json"]; // shows a format-choice menu instead of exporting immediately
  exp.addEventListener("lr-export", (e) =>
    console.log("exporting", e.detail.format)
  );

  // Custom formats supply menu copy but remain application-handled.
  exp.formats = [
    "csv",
    {
      formatId: "xlsx",
      label: "Excel workbook",
      description: "Preserves spreadsheet data types",
      extension: "xlsx",
    },
  ];
  exp.addEventListener("lr-export", async (e) => {
    if (e.detail.format !== "xlsx") return;
    e.preventDefault();
    exp.loading = true;
    try {
      await exportWorkbook(exp.rows);
    } finally {
      exp.loading = false;
    }
  });
</script>
```

Package-level CSV utilities (used internally, also exported for standalone use — `import {
escapeCsvField, buildCsv, downloadBlob } from
'@aceshooting/lyra-ui/components/utility/export-button/csv.js'`):

```ts
escapeCsvField(value: unknown): string   // quotes/escapes; neutralizes leading whitespace and ASCII/fullwidth =,+,-,@ formula prefixes with an apostrophe
buildCsv(rows: readonly Readonly<Record<string, unknown>>[], columns: readonly LyraCsvColumn[], options?: LyraBuildCsvOptions): string  // CRLF-joined, header row included; options.bom prepends a UTF-8 byte-order mark
downloadBlob(content: string, filename: string, mime: string, ownerDocument?: Document): void // triggers a browser download in the supplied document realm
```

**Known gotchas:**

- Format options are read from their direct data fields into a frozen list. Accessor-backed, missing,
  malformed, or throwing descriptor fields are ignored rather than evaluated; later menu rendering
  and `lr-export` events use that snapshot. The snapshot includes only direct `formatId`, `label`,
  `description`, and `extension` fields; accepted records are frozen and never reread from the
  caller. An open multi-format menu is a non-modal overlay owned by the element's
  current document: only its topmost menu handles that document's Escape, outside pointer, or Tab.
  It rebinds after document adoption; Escape or a selected export returns focus to its own trigger,
  while a Tab close permits normal document navigation. Placement uses the current trigger and panel
  geometry and remains clamped to the current document's viewport.
- CSV and JSON are the only built-in encoders. To offer XLSX/PDF/etc., pass an
  `LyraExportFormatDescriptor` and handle its `formatId` from `lr-export`; custom formats never trigger a
  download or `lr-export-complete` on their own. A descriptor's optional `extension` is metadata
  for that handler, not automatic filename handling.
- CSV formula-injection guarding and the deferred (5s) `URL.revokeObjectURL` (works around Safari
  cancelling in-flight downloads on immediate revoke) are genuine, safe-to-rely-on strengths.
  Finite JavaScript numbers remain numeric CSV cells (including negative and decimal values);
  caller-supplied strings such as `"-12"` still take the formula-safe text path. `NaN` and
  infinities are non-numeric values and are escaped as text.
- `bom` addresses an Excel-on-Windows-specific defect: Excel ignores a downloaded file's MIME
  charset and falls back to decoding a BOM-less CSV with the system ANSI code page, garbling
  accented, Arabic, CJK, and typographic characters. Setting `bom` prepends U+FEFF ahead of the
  CSV header row so Excel detects UTF-8. It changes nothing for Google Sheets, LibreOffice, or
  Numbers, which already sniff UTF-8 correctly either way, and it never reaches the JSON download
  under any setting — RFC 8259 forbids a BOM in JSON.
- `open` is valid only when `formats` contains more than one choice. An invalid open request is
  normalized closed without a false `lr-show`/`lr-hide` pair; shrinking an open menu to one format,
  or becoming `disabled`/`loading`, closes it and repairs focus. JSON projection safely preserves
  an own enumerable column literally named `__proto__`.
- an empty format list, including one whose descriptors are all rejected during validation,
  disables the trigger because no export action exists.
- the multi-format menu (`role="menu"`) supports full arrow-key navigation — ArrowUp/ArrowDown move
  between items (opening the menu and seeding the right one focused, if it was closed), Home/End
  jump to the first/last item once open, Escape closes it and returns focus to the trigger button,
  and a completed export also returns focus to the trigger — not just Escape/click-outside as
  before.
- the positioned menu is constrained to the inline/block space reported by the positioner, wraps
  long localized format labels/descriptions, scrolls when necessary, and disables its transition
  under reduced motion.

---

## `lr-copy-button`

A standalone copy-to-clipboard affordance for a plain text `value` or a source element selected by
`from`. Its built-in icon button swaps to a confirmation or failure glyph once the Clipboard API
settles; a consumer-provided default-slot trigger can replace that button. The component takes no
positioning opinion of its own.

The CopyFailure example temporarily supplies a denied clipboard operation during click capture,
including after a held pointer press, then restores the original own property descriptor or removes
its temporary override when the clipboard was inherited. Pointer gestures that end without a click
do not install an override. This example does not change the clipboard contract of ordinary copy
buttons.

**Properties:**

- `value: string = ''` — the plain text to copy.
- `from: string = ''` — source expression that takes precedence over `value`. `id` copies the
  element's `textContent`, `id[attribute]` copies an attribute, and `id.property` copies a property.
  Resolution prefers an element in the button's own root, then falls back to the owner document;
  a duplicate same-root id therefore wins without preventing a shadow-contained button from
  targeting an otherwise valid document-owned source.
- `copyLabel: string = ''` (attribute `copy-label`) — built-in button accessible name and resting
  tooltip text; empty uses localized `copy`.
- `successLabel: string = ''` (attribute `success-label`) — confirmation name/tooltip text; empty
  uses localized `copied`.
- `errorLabel: string = ''` (attribute `error-label`) — failure name/tooltip text; empty uses
  localized `copyFailed`.
- `tooltip: 'full' | 'copy' | 'none' = 'full'` (reflected) — `full` shows the resting tooltip on
  hover/focus and feedback after activation, `copy` shows feedback only, and `none` disables it.
- `tooltipPlacement: 'top' | 'right' | 'bottom' | 'left' = 'top'` (attribute
  `tooltip-placement`, reflected).
- `hoist: boolean = false` (reflected) — uses fixed tooltip positioning to escape clipped
  containers.
- `accessibleLabel: string | null = null` (attribute `aria-label`) — overrides the localized
  built-in button name while leaving tooltip/feedback labels unchanged; retained Lyra alias.
  An empty or whitespace-only value falls back to the localized state label so the built-in
  icon-only trigger always remains named; remove the attribute or assign `null` for the same
  fallback.
- `disabled: boolean = false` (reflected)
- `feedbackDuration: number = 1000` (attribute `feedback-duration`) — milliseconds before the
  confirmation **or** the failure state returns to the copy icon. A non-finite value falls back to
  `1000` rather than leaving the state stuck; a negative one clamps to `0`.

**Methods:** `focus(options?)`, `blur()` and `click()` forward to the active built-in or custom
trigger. `getToolbarActions(): readonly LyraToolbarAction[]` implements the public logical-toolbar
provider protocol with one stable action whose id is `copy`; its focus, roving tab index, disabled
state, and composed-event matching follow the active trigger without exposing that node. Its
`releaseTabIndex()` action method lets a parent stop managing its tab index on disconnect, adoption,
trigger replacement, and parent departure: an untouched author-supplied `tabindex` is restored,
while a newer author change is never overwritten.

**Events:**

- `lr-copy` (`detail: LyraClipboardWriteSuccess`, `{ ok: true; text: string }`) — fires only after
  the owning browsing context's clipboard write fulfills. The detail is a frozen shared outcome.
- `lr-error` (no detail) — bubbling, composed, non-cancelable notification that source resolution
  or clipboard writing failed.
- `lr-copy-error` (`detail: LyraClipboardWriteFailure`,
  `{ ok: false; text: string; reason: LyraCopyErrorReason; error: unknown }`) — the frozen detailed
  failure outcome. `reason` is `'unsupported'` (no Clipboard API), `'denied'`
  (`NotAllowedError`/`SecurityError`) or `'failed'` (including a missing/empty source and other
  platform failures); the error field contains the original platform or component-created error.
- `lr-toolbar-actions-change` (no detail) — bubbling/composed coordination event emitted when the
  logical action's disabled state or backing trigger changes, so an enclosing
  `<lr-message-actions>` can repair its roving tab stop.

The nested tooltip's `lr-show`/`lr-after-show`/`lr-hide`/`lr-after-hide` lifecycle is internal
implementation detail and is contained at the copy-button boundary; it is not part of this event
surface and cannot be canceled through an ancestor of `<lr-copy-button>`.

**Slots:** default custom trigger, plus `copy-icon`, `success-icon`, and `error-icon` overrides for
the built-in button. Exactly one named icon is rendered at a time.

**CSS parts:**

- `base` / `button` — the built-in trigger, a composed `<lr-icon-button>` as of 16.0.0. It owns the
  accessible name, the activation and every state part below; its background, radius, hover/press
  mixes, focus ring and hit-area floor come from `--lr-icon-button-*`.
- `base__control` — the composed `<lr-icon-button>`'s own native `<button>`. A rule that set
  `background`/`border`/`padding` through `::part(base)` moves here, or onto the token.
- `base-success` — added to the button's part list while the confirmation shows
  (`part="base button base-success"`).
- `base-error` — the same while the failure state shows (`part="base button base-error"`).
- `copy-icon`, `success-icon`, `error-icon` — the resting, confirmation and failure glyphs. Exactly
  one is rendered at a time; all three are `aria-hidden`.
- `feedback` — the visually hidden, `aria-hidden` mirror of the outcome text. Empty at rest, so
  nothing is announced before a real outcome. It carries no live-region role of its own: the
  announcement goes to the library's shared **light-DOM** polite region, appended to the consumer's
  `<body>` and marked `data-lr-live-region="polite"`, because a live region inside a shadow root is
  not reliably announced (JAWS with Firefox ignores one outright). Assert against that
  document-level region rather than `::part(feedback)`; the part is a styling and inspection
  surface, and still tells you what the button last announced.
- `tooltip__base`, `tooltip__base__popup`, `tooltip__base__arrow`, `tooltip__body` — exported nested
  tooltip parts.

**CSS custom states:** `success` and `error`. The retained `base-success`/`base-error` part names
remain available for shadow-part styling.

**Themeable custom properties:** `--success-color` (default `var(--lr-color-success)`) and
`--error-color` (default `var(--lr-color-danger)`), plus shared hit-area, text, focus, transition,
and disabled-opacity tokens.

**Optional peer deps:** none.

```html
<code id="install-command">npm install @aceshooting/lyra-ui</code>
<lr-copy-button
  from="install-command"
  copy-label="Copy install command"
  success-label="Install command copied"
  tooltip-placement="right"
  hoist
></lr-copy-button>
```

Handling the failure path — the button already shows and announces it, so a listener is only needed
for an application-level fallback:

```html
<lr-copy-button
  id="copy"
  value="npm install @aceshooting/lyra-ui"
></lr-copy-button>
<script type="module">
  import "@aceshooting/lyra-ui/components/utility/copy-button/copy-button.js";

  const button = document.getElementById("copy");
  button.addEventListener("lr-copy", (event) =>
    trackCopySuccess(event.detail.text)
  );
  button.addEventListener("lr-error", () => showCopyFallback());
  button.addEventListener("lr-copy-error", (event) => {
    // event.detail.reason is 'unsupported' | 'denied' | 'failed'
    if (event.detail.reason === "unsupported")
      selectTextForManualCopy(event.detail.text);
  });
</script>
```

The closed-set and error-reason types are exported alongside the class:

```ts
import type {
  LyraClipboardWriteFailure,
  LyraClipboardWriteOutcome,
  LyraClipboardWriteSuccess,
  LyraCopyButtonTooltip,
  LyraCopyButtonTooltipPlacement,
  LyraCopyErrorReason,
} from "@aceshooting/lyra-ui/components/utility/copy-button/copy-button.class.js";
```

**Known gotchas:**

- **Changed in 8.0.0:** the button used to enter the "Copied" confirmation on activation whether or
  not the clipboard write succeeded. It now waits for `navigator.clipboard.writeText()` to settle: a
  rejection renders the failure glyph instead, announces the localized failure text through the
  shared polite region mirrored by `[part="feedback"]`, and emits `lr-error` plus `lr-copy-error`.
  `lr-copy` is now the success-only fulfilled outcome; code that tracked activation attempts from
  that event should instead track the initiating click separately.
- An empty `value`, missing `from` target/member, or empty resolved source is an error; no clipboard
  write is attempted. `from` always wins over `value`, including when it is invalid.
- `navigator.clipboard` is absent in insecure contexts/older browsers, and some engines throw
  synchronously rather than rejecting. Both arrive at the same failure path (`unsupported` for the
  missing API, `denied`/`failed` for a real rejection) — there is no silent success left.
- Changing `value`/`from`, or disconnecting, clears any in-progress confirmation/failure
  immediately. A write that settles after that change is discarded.
- A custom default-slot trigger supplies its own semantics and accessible name; built-in icon
  slots, `button`/`base` parts, and `aria-label` forwarding apply only to the built-in button.
- The failure is signalled on four channels — a different glyph, a different accessible name, the
  live-region announcement, and only then colour — so it survives a monochrome or high-contrast
  rendering.
- Copy affordance strings are localizable: `copy` (`'Copy'`), `copied` (`'Copied!'`) and
  `copyFailed` (`'Copy failed'`), overridable per instance through `.strings` or app-wide through
  `registerLyraLocale()` (see `llms/shared.md`). Explicit `*-label` properties take precedence.
- Native `dir`/`lang` remain inherited global attributes. The component is not form-associated.
- No `size`/`compact` property: the built-in trigger's hit area is `<lr-icon-button>`'s shared
  `--lr-icon-button-size` floor (2.5rem/40px). For a dense action row, lower
  `--lr-theme-icon-button-size` (not `--lr-icon-button-size`, which every `LyraElement` re-declares
  on its own `:host` and so never reaches a composed child) on this element or an ancestor, or reach
  the composed native control directly through `::part(base__control)`. A coarse-pointer/no-hover
  media rule then floors the rendered hit area at 2.75rem/44px regardless of how far a dense-row
  override lowered it, so the shrink is safe on a touch device.

---

## `lr-resize-observer`

Lifecycle-managed wrapper around the native `ResizeObserver`. It observes all element children in
the default slot and emits a composed event, while adding no layout of its own.

**Properties:** `disabled: boolean = false` (reflected) and `box: 'content-box' | 'border-box' |
'device-pixel-content-box' = 'content-box'` (reflected).

**Events:** `lr-resize` with a frozen `Readonly<{ entries: readonly ResizeObserverEntry[] }>`
detail. The sequence is detached and bounded while each native observer entry retains identity.

**Slots:** default observed elements. **CSS parts:** `base`.

---

## `lr-intersection-observer`

Lifecycle-managed wrapper around the native `IntersectionObserver`. It observes all element children
in the default slot and emits a composed event, while adding no layout of its own.

**Properties:** `disabled: boolean = false` (reflected), `rootMargin: string = '0px'` (attribute
`root-margin`), `threshold: number | number[] | string = '0'` (the mapped attribute form accepts
space-separated values), `root: Element | string | null = null` (an element or mapped element ID),
`intersectClass: string = ''` (attribute `intersect-class`, toggled on each target), and `once:
boolean = false` (reflected; unobserves a target after its first intersection). A once-consumed
target stays consumed across option-driven observer rebuilds and disconnect/reconnect cycles;
setting `once` to false is the explicit reset boundary.

The browser capability is optional. A missing or throwing owner-window lookup or unavailable
constructor leaves that rebuild inert rather than leaking an exception; an initial construction
failure retries once with safe default options. Individual `observe`, `unobserve`, and `disconnect`
failures are contained, so later valid targets and later rebuilds can still observe. Callbacks are
tied to the current owner document, so a detached or adopted wrapper cannot emit a stale batch.
Threshold collections inspect at most their first 10,000 direct data entries. Malformed or
accessor-backed entries are skipped; a valid prefix remains active, while an entirely unusable value
falls back to threshold `0`.

**Events:** mapped `lr-intersect` once per entry with `{ entry }`, plus the existing batch alias
`lr-intersection` with a frozen
`Readonly<{ entries: readonly IntersectionObserverEntry[] }>` detail. The batch sequence is
detached and bounded while each native observer entry retains identity.

**Slots:** default observed elements. **CSS parts:** `base`.

---

## `lr-mutation-observer`

Lifecycle-managed wrapper around the native `MutationObserver`. All element children in the default
slot are observed and their mutation records are emitted as a composed event; the wrapper itself
adds no layout.

**Properties:** `disabled: boolean = false` (reflected), `childList: boolean = false` (attribute
`child-list`; **changed in 8.0.0** from Lyra's former `true` default, so opt in explicitly when
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).

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
`observe` and `disconnect` failures are contained, so later valid targets and later rebuilds can still observe.
Callbacks from a retired document are ignored after disconnect or adoption. `attributeFilter` is
likewise a bounded own-data snapshot (examining at most its first 10,000 direct data entries);
malformed or accessor-backed entries are skipped, a valid prefix remains active, and an entirely
unusable value falls back to an empty filter.

**Events:** `lr-mutation`; its detail and bounded readonly record sequence are frozen.
`detail.records` and mapped `detail.mutationList` reference the same sequence, while each native
`MutationRecord` retains identity.

**Slots:** default observed elements. **CSS parts:** `base`.

---

## `lr-json-viewer`

A collapsible, copyable tree view for an arbitrary JSON-serializable value (object, array, string,
number, boolean, null, or `undefined`). Serves as a fallback renderer wherever a raw payload needs
inspecting without a bespoke view. Assignment creates one bounded, frozen graph from own enumerable
data descriptors. It never invokes getters or object-conversion hooks; accessor/reflection-failed
branches and function or symbol leaves are omitted, while bigint is retained as decimal text.
Rendering, searching, toolbar copy, and per-node copy all use that same owned graph, so later
mutation or revocation of the supplied object cannot change a displayed or copied value. Ordinary
aliases, cycles, and sparse-array holes are retained. Expand/collapse state is keyed by structural path (not object
identity), so it survives a `data` reassignment that keeps the same shape — e.g. a streaming result
being patched in place. A container value that self-references (directly or through a longer cycle)
renders as a leaf `Circular reference` marker (`data-type="circular"`) instead of recursing — no
stack overflow on cyclic `data`.

Removing `search` clears matches while retaining null property readback. Before any match is active,
`searchPrevious()` selects the final match; later next/previous navigation wraps. Navigation may
reopen the selected match’s ancestors while unrelated manual collapse remains intact.

**Properties:**

- `data: unknown` (attribute `false` — property-only, not settable via an HTML attribute)
- `collapsedDepth?: number` (attribute `collapsed-depth`) — nodes at or beyond this nesting depth
  (root = `0`) start collapsed; omitted/`undefined` means nothing auto-collapses
- `maxHeight: string = ''` (attribute `max-height`) — a CSS length (e.g. `"20rem"`); once set, the
  viewer scrolls internally past this height instead of growing the page. Values that do not parse
  as CSS `max-height`, contain declaration breaks, or contain `url()` are ignored, leaving
  `--lr-json-viewer-max-height` in control
- `copyable: boolean = false` (reflected) — shows copy-to-clipboard affordances: one for the whole
  value, plus one per node
- `search: string = ''` — case-insensitive substring match against keys/values; matches are
  highlighted and their ancestors auto-expanded

**Methods:** `runSearch(query)` sets the declarative `search` property and awaits the recompute,
resolving the match count — named distinctly from `search` because a class member can't share a name
with a reactive property. `searchNext()`/`searchPrevious()` advance/step back a match cursor
(wrapping), reveal that selected match even when one of its ancestors was explicitly collapsed,
mark it as the active `aria-current` result, announce its position, and scroll it into view;
they resolve `false` when there are no matches. `clearSearch()` resets `search` to `''`, clearing all
matches and the cursor.

**Events:** `lr-copy` (`detail: LyraClipboardWriteSuccess`, `{ ok: true; text: string }`) — fired by
the top-level copy button or a per-node one only after the owning browsing context's clipboard write
fulfills. `lr-error` (no detail) and `lr-copy-error` (`detail: LyraClipboardWriteFailure`) fire when
serialization or clipboard writing fails; the detailed frozen outcome carries `ok: false`, the
attempted text, a reason of `'unsupported' | 'denied' | 'failed'`, and the original error. Failures
announce localized `copyFailed`; the raw platform error is never rendered. Copying a circular
`data` value serializes safely, substituting the same `Circular reference` marker the tree view
renders, instead of throwing. `lr-search-change`
(`detail: { query, matchCount, matchCountExact, activeIndex }`) —
fired whenever the search query, match count, or active-match cursor changes, from
`runSearch()`/`searchNext()`/`searchPrevious()`/`clearSearch()`, or a direct `search`/`data`
property write. `matchCountExact` is `false` when the bounded traversal only proves a lower bound;
the rendered count uses an “at least” prefix in the same case.

**Slots:** none — the tree is rendered entirely from `data`.

**CSS parts:** `base` (root scroll container, respects `max-height`), `toolbar` (wrapper around the
top-level copy button, only rendered when `copyable`), `tree` (wrapper around the rendered node
tree; a host `aria-label` is forwarded here), `row` (every structural opening/value and
closing-delimiter row), `key` (an object property key or array index label, `data-match` while it matches `search`,
`data-active` while it is the current `searchNext()`/`searchPrevious()` cursor position),
`value` (a primitive value's text — carries `data-type` of
`string`/`number`/`boolean`/`null`/`undefined`/`circular` for per-type coloring, `data-match`
while it matches `search`, and `data-active` while it is the current cursor position), `bracket` (a
`{`, `}`, `[`, or `]` delimiter), `toggle` (a container node's expand/collapse button; hidden but
present for row alignment on leaf/empty nodes),
`copy-button` (a copy-to-clipboard button — the top-level one in `toolbar` (aria-label "Copy JSON to
clipboard") or a per-node one (aria-label `Copy ${key/type}`, e.g. "Copy age"); only rendered when
`copyable`), `limit` (the localized notice rendered below the tree when the depth/node traversal
budget truncates rendering or search — absent entirely for any document within budget)

Collapsed arrays retain their exact safe `.length`. A broad object whose key count itself exceeds
the traversal budget uses an “at least” preview rather than presenting the retained prefix as a
false total. Per-row copy actions remain visible by default on coarse-pointer/no-hover devices;
fine-pointer users retain the hover/focus reveal.

Active-match position changes are appended to Lyra's shared light-DOM polite announcement sink.
The shadow tree keeps only an `aria-hidden` text mirror, so the same result is not announced twice;
initial connection and reconnection—including a detached cursor update whose render settles during
reattachment—do not replay the current cursor. Search navigation while the viewer or a composed
ancestor is accessibility-hidden also stays silent. After cross-document adoption, smooth-scroll
motion preferences and best-effort clipboard writes use the viewer's current owner window.

**Themeable custom properties:** `--lr-json-viewer-max-height` (default `none` — grows with content
until `max-height` is set), `--lr-json-viewer-font` (default `var(--lr-font-mono)`),
`--lr-json-viewer-match-bg` (default `var(--lr-color-warning-quiet)`) — background, and surrounding
box-shadow, of a key/value that currently matches `search`. Component-scoped indirection over the
shared `--lr-color-warning-quiet` token, so a consumer can retheme just this search-match highlight
without repainting every other warning-toned surface that reads the same shared token;
`--lr-json-viewer-row-hover-bg` (default `var(--lr-color-brand-quiet)`) — structural-row hover
background;
`--lr-json-viewer-active-outline` (default `var(--lr-focus-ring-color)`) — outline color for the
current imperative search match; `--lr-json-viewer-string-color` (default
`var(--lr-color-success)`), `--lr-json-viewer-number-color` (default `var(--lr-color-brand)`),
`--lr-json-viewer-boolean-color` (default `var(--lr-color-warning)`), and
`--lr-json-viewer-null-color` (default `var(--lr-color-text-quiet)`) — per-value-type color hooks.
Plus shared
tokens `--lr-color-border/-surface/-text/-text-quiet/-brand/-brand-quiet/-success/-warning/-warning-quiet`,
`--lr-radius`, `--lr-space-xs/-s/-l`, `--lr-focus-ring-width/-color/-offset`,
`--lr-transition-fast`.

**Optional peer deps:** none.

```ts
import { html } from "lit";
import "@aceshooting/lyra-ui/components/utility/json-viewer/json-viewer.js";

html`<lr-json-viewer
  .data=${apiResponse}
  copyable
  max-height="24rem"
  search=${query}
></lr-json-viewer>`;
```

```html
<lr-json-viewer copyable max-height="24rem"></lr-json-viewer>
<script type="module">
  document.querySelector("lr-json-viewer").data = {
    hello: "world",
    items: [1, 2, 3],
  };
</script>
```

**Known gotchas:**

- `data` is property-only (`attribute: false`) — it must be set via `.data = ...` or a lit-html `.data=${...}`
  binding, never as a plain HTML attribute.
- Search highlighting auto-expands only the _ancestors_ of a match, not the whole tree — a
  non-matching sibling subtree elsewhere stays collapsed (or expanded) exactly as it already was.
- An explicit per-node expand/collapse (from clicking a node's `toggle` button) overrides
  `collapsedDepth` and declarative search-driven auto-expansion for that path. Imperative
  `searchNext()`/`searchPrevious()` navigation may reopen the ancestors of the selected result so
  the active match is never hidden; otherwise the override persists until `data` is reassigned with
  a different shape.
- Per-node copy buttons call `stopPropagation()` on click so clicking one doesn't also toggle the
  row's expand/collapse state.
- Whole-value copy always produces text, including for a root `undefined`, `Symbol`, or function
  that native `JSON.stringify()` would otherwise return as no value.

---

## `lr-live-region` (+ the `Announcer` helper)

A throttled screen-reader announcement helper, split into a DOM-free coalescing engine (the
`Announcer` class), the shared light-DOM region a flush writes into (`acquireAnnouncementSink()`),
and a real custom element that composes both. The two helpers are public — part of the curated,
semver-covered `utilities/` surface documented in `llms/shared.md`, not internals:

The Basic example’s controls announce through its sibling live region; both first and repeated
messages appear in the visible log and the light-DOM announcement sink.

```ts
import {
  Announcer,
  acquireAnnouncementSink,
} from "@aceshooting/lyra-ui/utilities/announcer.js";
```

The `.js` is required (`./utilities/*` maps straight onto `./dist/utilities/*`). Both symbols are
also re-exported from the extensionless `@aceshooting/lyra-ui/utilities` barrel and from the package
root, but the single-helper subpath above is the form to copy — it reaches nothing else.

### `Announcer` — `@aceshooting/lyra-ui/utilities/announcer.js`

Not a custom element — the `Announcer` class itself is pure timing/coalescing logic with no DOM
dependency, composed by `<lr-live-region>` (below) and intended for reuse by any other component
that needs throttled announcements (a stream-status indicator, a tool-call chip's status
transitions, a chat message's streaming state). The same module also exports the DOM half a flush
writes into — `acquireAnnouncementSink()`, documented after `Announcer` below.

Streaming UIs (token-by-token chat responses, progress ticks, etc.) naturally produce far more
candidate announcements than a screen-reader user can usefully absorb — reading every incremental
chunk aloud is spam, not information. `Announcer` collapses a burst of `announce()` calls arriving
within `throttleMs` of the _first_ call in that burst down to a single trailing-edge flush of the
latest text: superseded intermediate text is dropped outright, never queued or concatenated.

- `new Announcer(options: AnnouncerOptions)` where
  `AnnouncerOptions = { throttleMs?: number /* = 500 */; onFlush: (text: string) => void;
timerHost?: AnnouncerTimerHost }`. `AnnouncerTimerHost` is the minimal numeric-handle
  `setTimeout`/`clearTimeout` surface implemented by a browser `Window`; omit it to use ambient
  timers.
- `announce(text: string, options?: AnnounceOptions)` where `AnnounceOptions = { force?: boolean }` —
  queues `text`, overwriting whatever an earlier call in the same burst queued. Only the _first_
  call of a burst schedules the flush timer, so the deadline stays anchored to that first call
  rather than being pushed back by every subsequent call. `{ force: true }` bypasses any
  in-progress window and flushes immediately, so a terminal message (e.g. "response complete") is
  never swallowed mid-burst.
- `cancel()` — drops any pending (not yet flushed) text without invoking `onFlush`.
- `setTimerHost(timerHost: AnnouncerTimerHost)` — rebinds scheduling and cancellation, for example
  after a component is adopted into another document. A pending burst is canceled on the previous
  host and rescheduled on the new one without losing its latest text.
- `pendingText: string | undefined` — the latest text awaiting flush, if a burst is in progress.
- `isPending: boolean` — whether a flush is currently scheduled.
- `throttleMs` — a plain public field, safe to change between bursts; a flush already scheduled
  keeps the deadline it was scheduled with.

### `acquireAnnouncementSink()` — `@aceshooting/lyra-ui/utilities/announcer.js`

The shared live region announcements actually land in. A live region rendered **inside a shadow
root is not reliably announced** — JAWS with Firefox ignores one entirely — so every announcement
this library makes goes into a visually hidden element in the _host document's_ light DOM instead.

- `acquireAnnouncementSink(politeness: AnnouncementPoliteness, options?: AnnouncementSinkOptions)`
  where `AnnouncementPoliteness = 'polite' | 'assertive'` and
  `AnnouncementSinkOptions = { document?: Document /* = the ambient document */; source?: Element;
messageTtlMs?: number /* = 5000 */ }`. Library components pass their host as `source`, which
  prevents a document-level region from speaking while that source or a composed ancestor is
  `hidden`, `inert`, `aria-hidden`, CSS-hidden, or in a closed `<details>` content branch;
  standalone consumers can do the same. A box-generating source also stays silent while skipped by
  `content-visibility:auto`. Browsers report every `display:contents` source as false from
  `checkVisibility()` whether its semantics are exposed or not, so the helper uses the explicit
  authored/CSS/closed-details gates for that boxless case and cannot distinguish an auto-skipped
  subtree; bind `source` to a semantic box when that exact distinction matters. A source adopted
  away from the acquired `document` also fails closed until its owner reacquires a sink.
  Returns an `AnnouncementSink` handle: `element`, `politeness`, a writable `messageTtlMs`,
  `announce(text: string): void` and `release(): void`.
- One region per `(document, politeness)` pair, shared by every consumer and **ref-counted**: it is
  mounted on the first `acquire()` and removed from the DOM when the last handle `release()`s.
  Mounting happens at acquire time, ahead of any text, because assistive tech has to have been
  observing a region _before_ content arrives for the change to be announced at all.
- `announce()` **appends a child node** (`aria-relevant="additions"`, `aria-atomic="false"`) rather
  than rewriting one text node. That is what makes an identical repeat announce a second time — no
  clear-then-restore-across-a-frame dance is needed — and each appended node is swept after
  `messageTtlMs`, so returning focus to the page never finds stale text to re-read. Empty text is
  ignored. Sweep and release cancellation use the selected document's `defaultView` timer realm,
  so an iframe-owned sink does not leave parent-window timers retaining its messages. `announce()`
  after `release()` is a no-op; `release()` is idempotent and removes that
  handle's own not-yet-swept nodes.
- The region carries `data-lr-live-region="<politeness>"` (exported as
  `ANNOUNCEMENT_SINK_ATTRIBUTE`) so a consumer's DOM diffing, snapshot testing or `MutationObserver`
  can recognize and ignore library-owned nodes appearing at the end of `<body>`.
- Under SSR (no `document`) the call returns an inert handle instead of throwing, so callers need
  no environment check.

### `lr-live-region`

A visually-hidden ARIA live region that throttles and coalesces announcements instead of relaying
every call verbatim, by composing an internal `Announcer` with the shared light-DOM sink above. A
consumer typically mounts one `<lr-live-region>` per page/surface (much like `<lr-toast>` is one
region per placement) and keeps a reference to call `announce()` from application code or a parent
component. The announced copy does **not** live in this element's shadow root: it is appended to
the shared, ref-counted region in the host document, while the shadow `part="region"` element stays
behind as an `aria-hidden` mirror of the latest text.

**Properties:**

- `mode: 'polite' | 'assertive' = 'polite'` (reflected) — selects which shared region announcements
  land in: `'polite'` uses the `role="status"` + `aria-live="polite"` one (waits for the user to be
  idle), `'assertive'` the `role="alert"` + `aria-live="assertive"` one (interrupts). Unsupported
  attributes and untyped property writes normalize to reflected `polite`
- `throttleMs: number = 500` (attribute `throttle-ms`) — the coalescing window; see `Announcer`
  above

**Methods:** `announce(text: string, options?: AnnounceOptions): void` — queues `text` for
announcement through the internal `Announcer`; `{ force: true }` bypasses the current throttle
window and flushes immediately.

**Events:** none.

**Slots:** none.

**CSS parts:** `region` — the visually-hidden, `aria-hidden` mirror of the latest announced text.
It carries no `role`/`aria-live` of its own: a second live region holding the same text would make
browsers that _do_ announce shadow live regions read every message twice.

**Themeable custom properties:** none component-specific — the shadow mirror is hidden via the
shared `.sr-only` helper class (`internal/a11y.ts`) and the light-DOM region via the same
visually-hidden algorithm inline (no stylesheet of this package reaches the consumer's light DOM),
neither of them tokenized CSS.

**Optional peer deps:** none.

```html
<!-- once, near the root of a page/surface -->
<lr-live-region id="live" mode="polite"></lr-live-region>
<script type="module">
  const live = document.getElementById("live");
  // streaming tokens: fine to call on every chunk, only the trailing state lands
  live.announce(`${partialText} …`);
  // stream finished: always announced, even mid-throttle-window
  live.announce("Response complete", { force: true });
</script>
```

A parent Lit component would instead hold the reference via `@query('lr-live-region')`.

**Known gotchas:**

- The element mounts (and shares) a region in `document.body` for as long as it is connected — an
  expected side effect, not a leak: it is ref-counted and removed once the last `<lr-live-region>`
  of that politeness disconnects. Announcements are appended nodes, so re-announcing identical text
  is read again with no special-casing, and each node is swept a few seconds later.
- The announcement never waits on a render: it is appended as soon as the flush happens, including
  when a consumer creates, appends and `announce()`s synchronously. Only the shadow mirror waits —
  a write landing before `firstUpdated()` is buffered and applied on the next `firstUpdated()`.
- Changing `mode` re-targets the shared region synchronously at announce time, so setting `mode`
  and force-announcing in the same turn lands with the new urgency instead of racing Lit's
  re-render. Adopting the element into an iframe likewise re-targets to that document's own region.
- `disconnectedCallback()` cancels any pending (unflushed) announcement and any before-first-render
  buffered write, and releases the shared region — an element removed before a deferred write lands
  silently drops it, including across a later reconnect.
- Changing `throttle-ms` updates the live `Announcer`'s window immediately, but a flush already
  scheduled under the old window keeps the deadline it was scheduled with.

---

## `lr-poll-status`

A "next scheduled refresh" countdown with a built-in pause control: a ticking `M:SS` display counting
down to the next scheduled action, a "Refreshing…" state at zero, and a pause/resume toggle.
First-party invention (no Web Awesome equivalent); the closest existing component,
`<lr-stream-status>`, is scoped to transport/connection-health phases, a different concern from a
scheduled-interval countdown — this mirrors its internal `<lr-live-region>` composition for
accessible phase-transition announcements.

Long localized status labels, including unbroken words, wrap within the component’s allocated inline
size in LTR and RTL. The indicator and pause/resume action retain their size; the 320px example
shows both inactive and refreshing states.

**Properties:**

- `nextInMs?: number` (attribute `next-in-ms`) — milliseconds until the next scheduled action, as of
  whenever this was last set; setting it (re)starts the countdown from "now." Unset (the default)
  shows no countdown.
- `active: boolean = true` (reflected) — whether the poll cycle is running at all.
- `paused: boolean = false` (reflected) — user-toggled pause; while `true`, the countdown display
  freezes and `lr-poll-due` never fires.

**Events:** `lr-poll-due` (no detail — fired once when the countdown reaches zero, not fired while
`paused`), `lr-pause-change` (`detail: { paused: boolean }` — fired when `paused` changes via the
built-in button).

**Methods:** `restart(): void` — restarts the currently configured `nextInMs` delay from now,
including after its previous deadline fired. With `nextInMs` unset it simply clears the due state.

**Slots:** none.

**CSS parts:** `base`, `indicator` (the pulsing status dot), `countdown` (the `M:SS`, or
"Refreshing…", text), `pause-button` (the built-in pause/resume toggle).

**Themeable custom properties:** `--lr-poll-status-due-bg` (default `var(--lr-color-success)`) —
background of `indicator` while `data-due` is set. Component-scoped indirection over the shared
`--lr-color-success` token, so a consumer can retheme just this due-state indicator without
repainting every other component that reuses the same shared success token. `--lr-poll-status-pause-hover-bg`/`--lr-poll-status-pause-hover-color` (defaults
`var(--lr-color-brand-quiet)`/`var(--lr-color-brand)`) and
`--lr-poll-status-pause-active-bg`/`--lr-poll-status-pause-active-color` (defaults the former
brand-quiet active `color-mix()`/`var(--lr-color-brand)`) retheme the built-in `pause-button`'s
hover/pressed paint independently of those same shared brand tokens. Plus shared tokens —
`--lr-space-xs`, `--lr-font-size-sm`,
`--lr-color-text-quiet`, `--lr-color-brand`, `--lr-color-success`, `--lr-radius`/`-pill`,
`--lr-focus-ring-*`.

**Optional peer deps:** none.

```html
<lr-poll-status next-in-ms="30000"></lr-poll-status>
<script type="module">
  const status = document.querySelector("lr-poll-status");
  status.addEventListener("lr-poll-due", () => refreshData());
  status.addEventListener("lr-pause-change", (e) =>
    console.log("paused:", e.detail.paused)
  );
</script>
```

Internally, owner-window timeouts schedule both the exact deadline and the next displayed-second
boundary from a captured target timestamp, so a zero/short delay does not wait for a one-second
poll and the countdown stays accurate after background throttling. Assigning a _changed_
`nextInMs` value starts a fresh deadline; assigning the same value is a normal Lit no-op, so use
`restart()` for a new cycle with the same delay. Entering `paused` captures the bounded remaining
duration; every resume establishes a new deadline from that frozen value. Changing `nextInMs` or
calling `restart()` while paused replaces the frozen duration without starting time. Toggling
`active`, disconnecting/reconnecting, or toggling either after the due event stops/starts only an
unconsumed ticker: a consumed deadline never replays until `nextInMs` changes or `restart()` is
called. Phase transitions ("Paused.", "Resumed.", "Refreshing now.") are announced via an internal
`<lr-live-region>` in polite mode.

**Known gotchas:**

- `restart()` is the explicit reset/extend path when the configured delay value itself has not
  changed.
- `active="false"` and `paused` both stop the ticker independently, but only `paused` fires
  `lr-pause-change` — that event is scoped to the built-in pause button's own toggle, not to
  `active`.
- the countdown rounds up while time remains. If a deadline is already elapsed when the ticker is
  armed — including a due-immediately or sufficiently short cycle — it can render "0:00" for one
  update before the scheduled due tick advances it to "Refreshing…".

---

## `lr-mention-popover`

A caret-anchored, keyboard-navigable popover for `@`-mention and `/`-slash-command autocomplete
inside a plain-text `<textarea>`/`<input>` the host owns. First-party invention (no Web Awesome
equivalent). A textarea keeps its native textbox semantics while open and, after a consumed
navigation key, `focusActiveOption()` moves real focus to the active option in the shadow listbox.
A single-line text input retains its active-descendant element-reference route; only that route
uses `syncActiveDescendant()`, which returns `false` for a textarea.
Textarea ARIA/AOM values are restored on close, anchor replacement, disconnect, or adoption; a
cross-root string IDREF is never left behind. Later localized result-count and active-position
changes are announced once through the shared polite region; opening markup and unchanged state are
silent.

Forward native input keydown events to `handleKeyDown()` as usual. Events with `isComposing` or
legacy `keyCode === 229` return false without preventing default, moving the active suggestion,
selecting, or closing the popover. Removing `query` uses the unfiltered empty-query behavior while
preserving null readback; an explicitly empty query remains empty.

**Properties:**

- `anchor?: HTMLElement` (attribute: false) — the element to position the popup relative to. A
  plain `<textarea>` or single-line text `<input type="text"|"search">` gets caret-precise
  positioning; any other element anchors the whole popup under that element's own box.
- `items: readonly Readonly<LyraMentionItem>[] = []` (attribute: false) — the full candidate set,
  pre-`query`-filtering. Assignment takes a shallow frozen snapshot. Runtime rows without a string
  `label` remain in that diagnostic snapshot but are omitted from filtering/rendering before the
  built-in or custom predicate runs, so one malformed provider row cannot take down valid siblings.
  An entry's `disabled` marks that row non-actionable: `aria-disabled="true"` replaces its
  selected/active affordances, activating it (click, or Enter/Tab while highlighted) commits
  nothing and emits no `lr-mention-select`, and ArrowDown/ArrowUp highlighting -- including the
  default pre-highlighted first row -- steps past it instead of landing on it. Omitted or `false`
  renders the row exactly as before this field existed.
- `query: string = ''` — the text typed since the trigger character; drives the built-in filtering
  (see `filter`).
- `open: boolean = false` (reflected)
- `filter: LyraMentionFilter | null = null` (attribute: false) — overrides the built-in
  case-insensitive `label`/`description` substring match entirely.
- `emptyText?: string` (attribute `empty-text`) — `undefined` uses localized `noMatches`; every
  supplied string, including `''` and `'No matches'`, is caller-owned
- `label?: string` — accessible name for the `role="listbox"` popup. `undefined` uses localized
  `mentionSuggestions`; every supplied string, including `''` and `'Suggestions'`, is
  caller-owned. A host-level plain `aria-label` attribute on `<lr-mention-popover>` itself takes
  priority over this property when present (checked via a plain `getAttribute()` read, not a
  reactive property) — matches the same fallback on `<lr-combobox>`/`<lr-table>`.
- `filteredItems: readonly Readonly<LyraMentionItem>[]` — read-only getter; label-valid `items`
  filtered by `query` via `filter` (or the built-in default). An empty `query` skips the query
  predicate but still omits malformed-label rows.
- `activeDescendantId: string | null` — read-only getter; the `id` of the currently-highlighted
  internal row, or `null` while closed or when `filteredItems` is empty. Useful for diagnostics and
  same-tree consumers; do not copy it to an external control as a string IDREF.
- `activeDescendantElement: HTMLElement | null` — read-only getter; the highlighted shadow option
  for the platform's element-reference ARIA API.
- `listboxId: string` — read-only getter; the internal `id` of the `role="listbox"` element. Like
  `activeDescendantId`, it cannot form a cross-shadow string IDREF from a host input.

**Methods:**

- `handleKeyDown(e: KeyboardEvent): boolean` — the host's own text-control `keydown` handler calls
  this while the popover is open. Handles `ArrowDown`/`ArrowUp` (moves the highlight) and
  `Enter`/`Tab` (commits the highlighted row) — both pairs return `false` with no
  `preventDefault()` when `filteredItems` is empty, letting the keystroke fall through to the
  host's own control unchanged. `Escape` closes with no selection. Returns `true` whenever the key
  was intercepted and `false` for keys the method does not recognize.
- `syncActiveDescendant(control: HTMLElement): boolean` — applies
  `ariaActiveDescendantElement` only for a retained single-line input route. For a textarea it
  returns `false` without mutating `aria-activedescendant`; the managed textarea session clears that
  value separately.
- `focusActiveOption(options?: LyraMentionFocusOptions): Promise<boolean>` — same-tree fallback
  after a consumed navigation key when `syncActiveDescendant()` returns `false`. Focuses the active
  option, lets the popover handle subsequent navigation, and restores focus to `anchor` when the
  popover closes. Pass `ownsFocus: () => boolean` when the caller has its own suggestion-session
  generation/disabled/focus-exit state; the predicate is rechecked immediately before transfer and
  during later fallback navigation. Close, candidate/query/filter/anchor replacement,
  disconnect/adoption, a newer transfer, or failed ownership resolves `false` without moving focus.

**Exported types:** `LyraMentionItem { suggestionId: string; label: string; description?: string;
icon?: string; disabled?: boolean }`; `LyraMentionFilter = (item: LyraMentionItem, query: string) => boolean`;
`LyraMentionFocusOptions { ownsFocus?: () => boolean }`;
`LyraMentionSelectDetail { suggestionId: string; index: number; label: string }`.

**Events:** `lr-mention-select` (`detail: LyraMentionSelectDetail`; `index` is the occurrence in
the assigned `items` collection before filtering and disambiguates repeated `suggestionId` values),
`lr-mention-close` (no detail payload —
`this.emit('lr-mention-close')` is called with no second argument, so `event.detail` is `null`,
not `undefined`; fires on Escape or any other `open: true -> false` transition, but never for the
close that immediately follows a `lr-mention-select` commit, and never for markup that simply
renders `open="false"` on first paint)

**Slots:** none.

**CSS parts:** `listbox`, `option`, `option-icon` (when `icon` is set), `option-label`,
`option-description` (when `description` is set), `empty`

**Themeable custom properties:** `--lr-mention-popover-option-active-bg` (default
`var(--lr-color-brand-quiet)`) — background of the hovered or `[data-active]`
(keyboard-highlighted) suggestion row. Component-scoped indirection over the shared
`--lr-color-brand-quiet` token, so a consumer can retheme just this highlighted/active row without
repainting every other component that reuses the same shared token.
`--lr-mention-popover-option-disabled-opacity` (default `0.5`) — opacity of a row whose `items`
entry sets `disabled`. Plus shared tokens —
`--lr-space-xs`/`-s`/`-m` (popup padding,
row padding/gap), `--lr-radius`
(row corners — the popup's own corner is the overlay family's, below),
`--lr-transition-fast` (open/close
transition), `--lr-color-brand` (selected-row
text), `--lr-color-text-quiet`/`--lr-color-text` (description text, full-contrast on the active
row), and `--lr-popover-viewport-clamp` (default `92vw`) — the shared narrow-viewport ceiling the
popup's max-inline-size is `min()`ed against, alongside its own `24rem` cap and the positioner's
available space. See `lr-tour` for the shared-clamp note.

The popup is a floating surface and paints from the **shared overlay-surface family** (16.0.0):
`--lr-overlay-surface` (default `var(--lr-color-surface-overlay)`), `--lr-overlay-border` (default
`var(--lr-color-border)`) and `--lr-overlay-shadow-anchored` (default `var(--lr-shadow-m)`). None is
declared on `:host`, so one declaration on `:root` — or on any ancestor, to scope it — retints this
surface together with every other floating surface in the library. `--lr-overlay-radius` (default `var(--lr-radius)`) is the matching corner radius.

`--lr-positioning-strategy` (16.0.0) — the popup reads this same cascading `absolute`/`fixed`
override documented on `<lr-popover>` when it is (re)positioned, falling back to its own `fixed`
default when nothing is set. There is no per-instance `positioning-strategy` property on
`<lr-mention-popover>`; set the custom property on `:root`, a theme, or one clipping ancestor to
change every unset mention popover beneath it.

**Optional peer deps:** none.

```html
<textarea id="composer"></textarea>
<lr-mention-popover
  id="mentions"
  label="People"
  empty-text="No matches"
></lr-mention-popover>
<script type="module">
  const textarea = document.getElementById("composer");
  const popover = document.getElementById("mentions");
  let suggestionGeneration = 0;

  textarea.addEventListener("keydown", (e) => {
    if (popover.open && popover.handleKeyDown(e)) {
      if (
        !popover.syncActiveDescendant(textarea) &&
        (e.key === "ArrowDown" || e.key === "ArrowUp")
      ) {
        const generation = suggestionGeneration;
        void popover.focusActiveOption({
          ownsFocus: () =>
            generation === suggestionGeneration &&
            (document.activeElement === textarea ||
              document.activeElement === popover),
        });
      }
      return;
    }
  });
  textarea.addEventListener("input", () => {
    suggestionGeneration += 1;
    popover.anchor = textarea;
    popover.items = [
      {
        suggestionId: "ada",
        label: "Ada Lovelace",
        description: "Engineering",
        icon: "👩‍💻",
      },
      {
        suggestionId: "grace",
        label: "Grace Hopper",
        description: "Engineering",
      },
    ];
    popover.query = "a"; // detected since the trigger character
    popover.open = true;
    popover.updateComplete.then(() => popover.syncActiveDescendant(textarea));
  });
  textarea.addEventListener("blur", (event) => {
    if (event.relatedTarget !== popover) {
      suggestionGeneration += 1;
      popover.open = false;
    }
  });

  popover.addEventListener("lr-mention-select", (e) => {
    // splice `${e.detail.label}` into the textarea at the trigger offset
  });
</script>
```

Integration is entirely the host's responsibility: detect a mention/command trigger in the host's
own `input` handling, set `anchor`/`items`/`query` and flip `open = true`, and forward every
`keydown` through `handleKeyDown()` while open. Anchor relationship and active-descendant syncing
are automatic; if an explicit `syncActiveDescendant()` check returns `false`, call
`focusActiveOption()` after the first consumed ArrowUp/ArrowDown so the fallback owns navigation
from then on. Setting `open = false` whenever the
query stops looking like an active mention context (a space typed, the trigger deleted, the input
blurred, …) is also the host's job — `lr-mention-close` fires automatically from that.

Positioning measures exactly where the caret currently paints via a hidden-mirror-element technique
(`caretClientRect()`) and positions against that single point with `internal/positioner.js`'s
`place()`, so the popup tracks the caret rather than sitting under the whole textarea. Re-measures
automatically only on an `anchor` or `query` change while open (a keystroke moves the caret, so a
fresh `query` is the proxy for "the caret may have moved").

**Known gotchas:**

- a host-level `aria-label` attribute on `<lr-mention-popover>` now takes priority over `label`
  (and its localized default) when resolving `[part="listbox"]`'s accessible name — previously it
  was silently ignored. Matches the same fallback on `<lr-combobox>`/`<lr-table>`.
- Never copy `activeDescendantId` or `listboxId` onto a document-owned control as a string ARIA
  IDREF; shadow-root IDs are outside that control's tree scope. Use `syncActiveDescendant()` and its
  `focusActiveOption()` fallback.
- The popover opens pre-highlighted on the top match (index 0), unlike `<lr-combobox>`'s own
  listbox which opens with nothing highlighted (`-1`) — a bare Enter right after opening commits
  immediately.
- Caret-precise positioning only applies to a plain `<textarea>` or single-line text
  `<input type="text"|"search">`; any other `anchor` element, or a text control whose caret rect
  can't be measured (e.g. `display: none`), silently falls back to whole-element anchoring against
  `anchor` itself.
- A caret that moves for a reason other than typing (e.g. a mouse click elsewhere in the text while
  the popover happens to still be open) is not separately tracked — force a re-measure by toggling
  `open` or reassigning `anchor`.
- `activeIndex` resets to `0` whenever `query`, `items`, or `filter` changes, but not when only
  `anchor` changes — reassigning `anchor` alone preserves whatever row was last highlighted. If
  fallback focus currently lives in the listbox and filtering removes every option, closing,
  emptying, or disconnecting the popover returns focus to the connected anchor before removing the
  active option.
- There's no persisted "selection" the way `<lr-combobox>`'s own listbox has one — a mention is
  either committed (closing the popover) or dismissed with nothing chosen. `aria-selected="true"`
  here marks whichever row is currently _active_ (what Enter/Tab would commit right now, per the
  WAI-ARIA combobox-with-list-autocomplete pattern), not a separate persisted value.

---

## `lr-diff-view`

A real two-string line diff (a classic longest-common-subsequence dynamic program, not a Myers
implementation), rendered as interleaved unified-diff output — not diff-flavored syntax highlighting
over an already-formatted string (`<lr-code-block>`'s `language="diff"` only lexically colors a
string the consumer already unified-diffed; it has no two-string-compare entry point of its own).
First-party invention (no Web Awesome equivalent).

**Properties:**

- `oldText: string = ''` (attribute: false) — the "before" text. Default `''` renders an
  all-additions diff of `newText`.
- `newText: string = ''` (attribute: false) — the "after" text. Default `''` renders an
  all-removals diff of `oldText`.
- `copyable: boolean = false` — shows a copy-to-clipboard button for the full unified-diff text.
  `false` (the default) renders no button.
- `maxHeight: string = ''` (attribute `max-height`) — a CSS length (e.g. `"20rem"`); once set, the
  view scrolls internally past this height instead of growing the page. Invalid values are ignored.
- `layout: 'unified' | 'split' = 'unified'` (reflected) — `'unified'` (the default) renders today's
  single interleaved `<pre>`; `'split'` renders two side-by-side `[part="side"]` columns derived from
  the same diff alignment. Unsupported attributes and untyped property writes normalize to
  reflected `unified`.
- `language: string = ''` — a shiki-recognized language id. Highlighting activates only when this
  has a matching entry in `languages` — there is deliberately no default full-table
  `lr-code-block`-style fallback, so this component never reaches shiki's ~200-language
  dynamic-import table.
- `languages?: Record<string, ShikiLanguageInput>` (attribute: false) — grammar definitions this
  instance can highlight, same shape as `lr-code-block-core`'s own `languages`.
- `contextLines: number | undefined` (attribute: `context-lines`) — keeps this many unchanged
  lines around each change and collapses longer unchanged runs into a localized fold marker. The
  default `undefined` shows every line; negative and non-finite values also disable folding.
- `maxLines: number = 5000` (attribute `max-lines`) — maximum logical lines accepted on either
  side. Larger input renders the localized `diffViewTooLarge` fallback without computing or
  highlighting the diff. `Infinity` relaxes this line-count ceiling, but the fixed aggregate
  character and comparison-work ceilings remain in force.

Grammar entries are read from own enumerable data fields into a bounded frozen map. A getter,
unreadable field, non-enumerable field, or malformed proxy branch is skipped without preventing a
later valid grammar from being used; grammar values themselves remain opaque to the component.
Non-enumerable names do not consume language slots, but every inspected name counts toward the
20,000 structural ceiling.

**Events:**

- `lr-copy` (`detail: LyraClipboardWriteSuccess`, `{ ok: true; text: string }`) — the frozen full
  unified-diff outcome, fired only after the owning browsing context's clipboard write fulfills.
- `lr-error` (no detail) — the Clipboard API was unavailable or the write failed.
- `lr-copy-error` (`detail: LyraClipboardWriteFailure`) — the frozen failure outcome contains
  `ok: false`, the text, a `LyraCopyErrorReason`, and the original error. The reason is
  `'unsupported' | 'denied' | 'failed'`.

The copy button stays in its resting state until `writeText()` resolves. Success renders and
announces localized `copied`; failure renders and announces localized `copyFailed`. A newer
activation, source-text change, `copyable`/`maxLines` transition, disconnect, or document adoption
retires an older pending outcome, so stale writes cannot confirm or fail a hidden or replaced diff.

**Slots:** none.

**CSS parts:** `base` (the root wrapper), `line` (a single line; carries
`data-type="equal"|"add"|"remove"|"empty"|"fold"` — `"empty"` is an unbalanced-replace placeholder cell in
`layout="split"` and never carries a `+`/`-` prefix; `"fold"` is the localized unchanged-lines
marker), `copy-button` (the copy affordance, only
rendered while `copyable`), `limit` (the localized over-`maxLines` fallback), `side` (one column in
`layout="split"`, `data-side="old"|"new"`).

**Themeable custom properties:** `--lr-diff-view-max-height` (default `none` — an independently
settable scroll cap on `[part="base"]`; the `maxHeight` property writes the same custom property
inline on `[part="base"]`), `--lr-diff-view-font` (default `var(--lr-font-mono)`), plus
shared tokens `--lr-color-border`/`-surface`/`-success`/`-success-quiet`/`-danger`/
`-danger-quiet`/`-text`, `--lr-radius`, `--lr-space-xs`/`-s`, `--lr-font-size-sm`,
`--lr-line-height-snug`, `--lr-focus-ring-*`.

**Optional peer deps:** `shiki` (the same fine-grained `shiki/core`/`shiki/engine/oniguruma`/binary
`shiki/onig.wasm` subset `lr-code-block-core` uses by default, never `shiki`'s full ~200-language
main entry point) — only loaded once both `language` and a matching `languages` entry are set;
unset/unmatched leaves the plain unhighlighted diff text untouched.

```html
<lr-diff-view copyable></lr-diff-view>
<script type="module">
  const diff = document.querySelector("lr-diff-view");
  diff.oldText = "line one\nline two\nline three";
  diff.newText = "line one\nline TWO\nline three\nline four";
  diff.addEventListener("lr-copy", (e) => console.log(e.detail.text));
  diff.addEventListener("lr-copy-error", (e) => {
    console.error(`Copy ${e.detail.reason}`, e.detail.error);
  });
</script>
```

The package root also exports the pure `computeLineDiff(oldLines: string[], newLines: string[]):
LyraDiffOp[]` helper (plus the `LyraDiffOp` type, `{ type: 'equal' | 'add' | 'remove'; text: string }`) — the
same line-diff function this component's own `render()`/copy handler call, exposed standalone so a
consumer can compute or unit-test the same alignment without instantiating the element at all.

**Known gotchas:**

- line splitting normalizes LF, CRLF, and lone CR endings before alignment and syntax-token indexing,
  so files that differ only by line-ending convention do not appear wholly changed.
- An empty document contains zero logical lines. A genuine trailing newline is still represented,
  so empty/one-sided diffs and copied unified text do not gain a phantom blank operation.
- alignment uses Hirschberg longest-common-subsequence matching: O(n·m) time with linear working
  memory. The 5,000-line per-side default, aggregate character ceiling, and comparison-work ceiling
  bound pathological inputs; `Infinity` opts out of only the first of those limits.
- the computed `diffOps` state is cached and recomputed only when `oldText`, `newText`, or
  `maxLines` changes. Copy-confirmation and other unrelated renders reuse the cached alignment.
- Changing either `oldText` or `newText` clears any in-progress "Copied" feedback immediately.

**Additional API surface:**

- `--lr-diff-view-add-background` — Added-line background.
- `--lr-diff-view-add-color` — Added-line text color.
- `--lr-diff-view-remove-background` — Removed-line background.
- `--lr-diff-view-remove-color` — Removed-line text color.
- `--lr-diff-view-fold-color` — Fold-marker text color.
- `--lr-diff-view-fold-background` — Fold-marker background.

---

## `lr-icon`

SVG icon primitive. Left alone it is dependency-free and offline: a built-in path, no icon font, no
sprite sheet, no network access at all. **New in 8.0.0**, it can also resolve a name through a
registered icon library, or fetch a single SVG document from `src` — those paths do hit the network,
and every byte they return is capped, sanitized, and rendered only if the whole pipeline succeeds.
Pairs with `lr-icon-button` (see `llms/components/lr-icon-button.md`).

**Properties:**

- `name: string = ''` (reflected once set) — a built-in glyph: `add`, `check`, `close`, `search`, `menu`,
  `chevron-left`, `chevron-right`, `chevron-down`, `calendar`, `command`, `trash`. An unknown name
  renders nothing (no error, no fallback glyph). With a registered `library`, this is instead the
  name handed to that library's resolver. The setter accepts `undefined` to clear the name; reads
  remain the canonical non-nullable `''`.
- `path: string = ''` — raw SVG path data for a glyph the built-in set doesn't cover. Takes
  precedence over `name`.
- `label: string = ''` — accessible name. Left empty (the default) the stable semantic owner is
  `aria-hidden="true"`, which is what you want whenever adjacent text already names the control. A
  host `aria-label` wins over it. For a labeled remote icon the same semantic owner and name remain
  present through idle, loading, loaded, empty, and error states without double-naming the SVG.
- `library: string = 'default'` (reflected) — name of a library registered with `registerIconLibrary()`.
  `default` means the built-in glyph set. An **unregistered** name also falls back to the
  built-in set instead of erroring, which is what lets registration happen after first render.
- `family: string = ''` and `variant: string = ''` (reflected once set) — forwarded with `name` to
  a registered library resolver. Their vocabulary belongs to that library; for example, an icon
  host might distinguish `classic`/`sharp` families and `regular`/`solid` variants.
- `src: string = ''` — URL of a single SVG document to fetch. It applies only when no registered
  library owns the icon: no `library` set, an unregistered one, or an empty `name`. Once a
  registered library does own the name it decides alone — a resolver that returns `''` or throws
  does **not** fall back to `src`. Assigning `undefined` aborts and clears any pending remote load,
  removes the source, and reads back as `''`.
- `rotate: number = 0` (reflected once changed) — clockwise rotation in degrees, applied to the icon box. At zero
  there is no `transform` at all, so an ordinary icon never becomes a containing block; a
  non-finite value leaves the icon unrotated.
- `flip?: 'x' | 'y' | 'both' | 'horizontal' | 'vertical'` (reflected, type `LyraIconFlip`) — mirrors
  the icon about the vertical, horizontal, or both axes. `horizontal`/`vertical` are retained Lyra
  aliases for the mirrored `x`/`y` vocabulary. Unset by default.
- `canvas?: 'fixed' | 'auto' | 'square' | 'roomy'` (reflected, type `LyraIconCanvas`) — sizes the
  layout box. Unset behaves as `fixed` (1.25em × 1em); `auto` follows the SVG's intrinsic width at
  1em high; `square` is 1.25em × 1.25em; `roomy` is 1.5em × 1.5em. All scale with `font-size`.
- `autoWidth: boolean = false` (attribute `auto-width`, reflected, deprecated) — compatibility
  alias for `canvas="auto"`; an explicit `canvas` wins.
- `swapOpacity: boolean = false` (attribute `swap-opacity`, reflected) — swaps the primary and
  secondary opacity hooks on SVGs that carry `.fa-primary`/`.fa-secondary` duotone layers.
- `animation?: LyraIconAnimation` (reflected) — one of `beat`, `fade`, `beat-fade`, `bounce`,
  `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.

**Events:**

- `lr-load` (`detail: { src: string }`) — a remote icon finished loading and is in the DOM. Also
  fires for a valid-but-empty document, which is not a failure. Never fires for a built-in glyph.
- `lr-error` (`detail: { src: string; error: unknown }`) — a remote icon could not be resolved,
  fetched, size-capped, sanitized, or parsed as an SVG document. `src` is the URL that was attempted
  (or the icon name, when a library resolver itself threw).

**Slots:** (default) — custom SVG geometry, rendered only when neither `path` nor a known `name`
resolves **and** no remote source is configured; a fetched document is never merged with slotted
nodes. Slotted nodes are cloned into the component-owned `<svg>` (Chromium does not paint SVG
geometry distributed through a slot that sits inside an SVG), so pass plain `<path>`/`<circle>`/
`<g>` elements, not a whole `<svg>`. Attribute and descendant mutations to assigned geometry are
mirrored live while connected; observation stops on detach and a reconnect synchronizes the latest
source tree.

**CSS parts:**

- `svg` — the rendered SVG, whether built-in or fetched.
- `use` — every `<use>` in the rendered SVG.
- `error` — the visually hidden, `aria-hidden` shadow mirror shown when a remote icon fails. The
  localized message (`iconLoadError`, `iconTooLarge`, or `iconSanitizerMissing`), never the raw
  platform error, is appended to Lyra's shared assertive light-DOM announcement sink. The sink
  stays silent while the icon or a composed ancestor is hidden, inert, `aria-hidden`, or hidden by
  rendered CSS.
- `empty` — the `aria-hidden` marker rendered when a remote icon resolved to an empty but valid
  document.

**Themeable custom properties:**

- `--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-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.
- Shared animation controls: `--animation-delay` (default `0s`), `--animation-direction` (default
  `normal`), `--animation-duration` (default `--lr-duration-icon`, 1s),
  `--animation-iteration-count` (default `infinite`), and `--animation-timing` (default
  `--lr-easing-emphasized`).
- Animation-specific controls: `--beat-scale` (default `1.25`, used exactly once as the beat peak);
  `--fade-opacity`; `--beat-fade-opacity` and
  `--beat-fade-scale`; `--bounce-height`, `--bounce-jump-scale-x`, `--bounce-jump-scale-y`,
  `--bounce-land-scale-x`, `--bounce-land-scale-y`, `--bounce-rebound`,
  `--bounce-start-scale-x`, `--bounce-start-scale-y`, and `--bounce-anticipation`; `--flip-angle`,
  `--flip-x`, `--flip-y`, `--flip-z`, `--flip-anticipation-scale`, and `--flip-overshoot`;
  `--buzz-distance`; `--wag-angle`; `--swing-angle`; `--jello-scale-x` and `--jello-scale-y`; and
  `--float-height`, `--float-drift`, `--float-tilt`, `--float-squash-x`, `--float-squash-y`,
  `--float-stretch-x`, and `--float-stretch-y`.
- Duotone controls: `--primary-color`/`--secondary-color` (default `currentColor`) and
  `--primary-opacity`/`--secondary-opacity` (defaults `1`/`0.4`). `swap-opacity` exchanges which
  opacity each layer receives without exchanging its color.

**Optional peer deps:** `dompurify` — needed **only** for `library`/`src` fetching, never for the
built-in glyphs. It is imported lazily on the first remote load; if it can't be loaded the icon
fails closed (nothing rendered, localized alert, `lr-error`) rather than injecting unsanitized
markup.

### Registering an icon library

A library is a pure name-to-URL function plus an optional mutator, registered once at application
start. The component keeps every security-relevant step: the resolved URL still goes through the
fetch allowlist, the response is still byte-capped, and the markup is still sanitized — a resolver
cannot widen what an icon is allowed to render.

```ts
import "@aceshooting/lyra-ui/components/utility/icon/icon.js"; // registers <lr-icon>
import {
  registerIconLibrary,
  unregisterIconLibrary,
  getIconLibrary,
} from "@aceshooting/lyra-ui/components/utility/icon/icon-library.js";

registerIconLibrary("material", {
  // May return a URL directly or resolve one asynchronously. All three reflected lookup fields
  // are provided, so a library decides their vocabulary and URL layout.
  resolver: async (name, family, variant) =>
    `https://cdn.example.com/material/${family}/${variant}/${name}.svg`,
  // Optional. Runs on the already-sanitized, component-owned <svg> before it is rendered —
  // recolouring, adding a viewBox, stripping a hardcoded width/height. It must not reintroduce
  // markup from an untrusted source, and a throwing mutator fails the load.
  mutator: (svg) => {
    svg.setAttribute("fill", "currentColor");
    svg.removeAttribute("width");
    svg.removeAttribute("height");
  },
});

await getIconLibrary("material")?.resolver("star", "classic", "solid");
unregisterIconLibrary("material"); // icons using it revert to the built-in glyph set
```

```html
<lr-icon
  library="material"
  family="classic"
  variant="solid"
  name="star"
  label="Favourite"
></lr-icon>
<lr-icon library="material" name="delete" fixed-width></lr-icon>
<lr-icon name="search" canvas="square" animation="beat"></lr-icon>
```

Types: `LyraIconLibraryResolver = (name: string, family: string, variant: string) => string |
Promise<string>`, `LyraIconLibraryMutator = (svg: SVGElement) => void`, and
`LyraIconLibraryOptions = { resolver; mutator? }` are exported from the same module.

**Known gotchas:**

- Registration order doesn't matter. `registerIconLibrary()` re-resolves every currently rendered
  `<lr-icon>` using that name, so icons can be on the page first; re-registering the same name with
  a different resolver re-resolves them again, and `unregisterIconLibrary()` reverts them to the
  built-in glyph. While a remote icon resolves, nothing is drawn — the box already holds its size,
  and a placeholder glyph would be a flash of the wrong icon.
- A resolver returning an empty string (an unknown name) restores the built-in render and fetches
  nothing. A resolver that throws or rejects is a failure: localized alert plus `lr-error`.
  Resolver promises are generation-guarded: if `name`, `family`, `variant`, or `library` changes
  while one is pending, its stale URL is never fetched.
- Remote loading is fail-closed by construction: the URL must pass the shared fetch allowlist
  (`http:`, `https:`, `blob:`, `data:`, and relative URLs — a `javascript:` URL is never fetched),
  the response is capped at 1 MiB before any parser sees it, and DOMPurify's SVG profile runs
  unconditionally, sanitizing straight to DOM nodes rather than to a re-parsed string. A strict
  post-sanitization SVG pass then removes style/foreign-document content and every external
  `href`, image, CSS `url()`, paint, filter, mask, marker, and related resource sink; only safe
  same-document fragments survive. A response that isn't an SVG document is rejected, and its
  text never reaches the DOM.
- Matching requests share a bounded cache of canonical sanitized SVG nodes. Concurrent icons issue
  one fetch, a disconnected subscriber does not abort work another icon still needs, and retryable
  failures are evicted. The canonical node is never rendered or mutated: each icon deep-clones it,
  then invokes that library's trusted mutator on the private clone. This keeps one library's
  recoloring from poisoning another library, a direct `src`, or a later cache hit.
- A superseded load can never paint over a newer one, and a detached icon holds no half-finished
  remote state. Reconnecting re-resolves the library and can reuse a retained sanitized resource.
- `rotate`/`flip` are physical, not direction-relative: `flip="x"` produces the same
  mirrored artwork in LTR and RTL. A glyph that must follow reading direction is mirrored by the
  wrapping part of the component that owns it; a second, direction-driven flip here would silently
  cancel that one out.

## `lr-visually-hidden`

Hides its slotted content from sight while leaving it in the accessibility tree, so a screen reader
still announces it. Uses the clip-rect technique (`position: absolute` in a 1px box with
`clip-path: inset(50%)`), never `display: none` or `visibility: hidden` — either of those would
remove the content from the accessibility tree along with the viewport, which is the whole failure
mode this element exists to avoid.

`:host(:focus-within)` restores the element to normal flow, so anything focusable inside becomes
visible the moment a keyboard user reaches it. That is what makes it usable for a skip link.

**Properties:** none. **Events:** none. **Slots:** default (the content to hide).
**CSS parts:** none — the host itself is the box. **Themeable custom properties:** none.

```html
<lr-visually-hidden
  ><a href="#main">Skip to main content</a></lr-visually-hidden
>
```

Every declaration is `!important`, deliberately: the element's contract is that the content is
hidden, and a consumer stylesheet that accidentally set `position: static` on it would silently
expose the text. Use the `:focus-within` escape hatch rather than overriding the base rules.

---

## `lr-divider`

A semantic separator: renders `<hr part="base" role="separator" aria-orientation="…">`. A host
`aria-label` is forwarded to that inner semantic owner.

**Properties:** `orientation: 'horizontal' | 'vertical' = 'horizontal'` (reflected) and
`vertical: boolean = false` (reflected Shoelace-compatible shorthand).

**Events:** none. **Slots:** none. **CSS parts:** `base`.

**Themeable custom properties:** `--color` (falls back to `--lr-color-border`), `--width` (falls
back to `--lr-border-width-thin`), and `--spacing` (default `0`, applied on the cross axis).

The host is `display: block` when horizontal and `display: inline-block; block-size: 100%` when
vertical, so a vertical divider fills its flex/grid row's height with no extra CSS — but it needs a
parent that actually has a resolved height.

---

## `lr-format-number`

`Intl.NumberFormat` output.

Removing `currency` preserves the removal readback while formatting with the declared USD fallback.
An explicitly blank currency also keeps its existing USD formatting fallback, and a later valid
currency takes effect normally.

Shared by all four formatters (`lr-format-number`, `lr-format-date`, `lr-format-bytes`,
`lr-relative-time`): each is text-only — a `display: inline` host with **no CSS parts, no events, and
no themeable custom properties of its own** — rendering one formatted string into its shadow root.
Locale comes from the shared `effectiveLocale` (this element's own `locale`, else the nearest
inherited `lang`; see `llms/shared.md`) and is passed to `Intl` as `undefined` when it resolves
empty, which means "the runtime's default locale". Every `Intl` instance is pulled from the shared
memoized `internal/intl-cache.ts` (one instance per locale + options pair, LRU-capped), so these are
cheap to use per row in a large table or feed.

Malformed runtime options fall back to a safe option set without discarding an otherwise-valid
effective locale. Only a malformed locale itself falls back to the runtime default.

**Properties:**

- `value: number = 0`
- `type: 'currency' | 'decimal' | 'percent' = 'decimal'`
- `currency: string = 'USD'` and `currencyDisplay: 'symbol' | 'narrowSymbol' | 'code' | 'name' =
'symbol'` (`currency-display`); used only by currency formatting
- `withoutGrouping: boolean = false` (`without-grouping`) and `noGrouping: boolean = false`
  (`no-grouping`) — Web Awesome/Shoelace aliases; either disables grouping separators. With both
  false, the `Intl.NumberFormat` option is omitted so each locale and notation keeps its own default
  grouping policy
- `notation: 'standard' | 'compact' | 'scientific' | 'engineering' = 'standard'`
- `minimumIntegerDigits?: number` (attribute `minimum-integer-digits`)
- `minimumFractionDigits?: number` (attribute `minimum-fraction-digits`)
- `maximumFractionDigits?: number` (attribute `maximum-fraction-digits`)
- `minimumSignificantDigits?: number` / `maximumSignificantDigits?: number` (matching kebab-case
  attributes)

**Slots:** default — fallback content, rendered only when `value` is not finite (`NaN`/`Infinity`,
e.g. a malformed attribute) or the formatted string is empty.

All digit properties are finite-integer guarded before `Intl` construction: integer/significant
digits clamp to `[1, 21]`, fractions to `[0, 100]`, and crossed minimum/maximum pairs are ordered.
Leaving one `undefined` preserves `Intl`'s own defaults. Closed-set values assigned through untyped
JavaScript fall back to their documented defaults.

## `lr-format-date`

`Intl.DateTimeFormat` output. Text-only host — no CSS parts, events, or own tokens; locale
resolution and `Intl`-instance caching are as described in
`llms/components/lr-format-number.md`.

**Properties:**

- `date: string | number | Date = new Date()` — unset means the construction-time current instant.
  Numeric HTML attributes are epoch milliseconds, matching numeric property assignment (including
  zero and negative epochs); nonnumeric strings retain ordinary date/ISO parsing. **Changed in
  8.0.0:** the former empty-string default rendered fallback content
- optional granular fields: `weekday`, `era`, `year`, `month`, `day`, `hour`, `minute`, `second`,
  and `timeZoneName` (attribute `time-zone-name`), each restricted to its corresponding published
  `Intl.DateTimeFormat` literal set
- `dateStyle?: 'full'|'long'|'medium'|'short'` (attribute `date-style`), `timeStyle?: …`
  (attribute `time-style`) — the preset-style set
- `timeZone?: string` (attribute `time-zone`) — an IANA zone name, forwarded through **both** option
  sets
- `hourFormat: 'auto' | '12' | '24' = 'auto'` (`hour-format`) — maps to `hour12` when explicit

Setting either `dateStyle` or `timeStyle` switches the component to the preset-style set and the
granular fields are then ignored entirely (`Intl` throws when the two are mixed); leave both unset
to use the granular set. An unparseable `date` renders the default slot. An invalid
`timeZone` throws a `RangeError` inside `Intl`, which is caught and retried once without the zone —
so the output falls back to the browser's local zone instead of failing to render. Valid output is
wrapped in semantic `<time datetime="…">`. Date input accepts primitive strings/numbers or a
genuine `Date`; arbitrary objects are rejected without calling their `valueOf()`, `toString()`, or
other conversion hooks.

**Slots:** default — fallback content for an invalid/unparseable `date`.

## `lr-format-bytes`

Byte/bit output via `Intl.NumberFormat`'s `style: 'unit'`, so the unit name is localized too.
Text-only host — no CSS parts, events, or own tokens; locale resolution and
`Intl`-instance caching are as described under `lr-format-number` above.

**Properties:**

- `value: number = 0`
- `unit: 'byte' | 'bit' = 'byte'`
- `display: 'long' | 'short' | 'narrow' = 'short'` — forwarded as `unitDisplay`
- `unitStep: number = 1000` (attribute `unit-step`) — mapped decimal scaling. **Changed in 8.0.0:**
  the former Lyra default was `1024`; it remains an opt-in extension
- `decimals: number = 1` — maximum fraction digits on the scaled amount

**Slots:** default — fallback content, rendered only when `value` is not finite.

The selected ladder is `byte`/`kilobyte`… or `bit`/`kilobit`… through peta and saturates at the
top; the index is `floor(log|value| / log(unitStep))`, and zero stays in the base unit. Magnitudes
below one remain at index zero. `unitStep` is normalized to a finite number `> 1`, falling back to
`1000`; `decimals` clamps to `[0, 10]`. Setting `unitStep="1024"` still prints SI-named `kB`/`MB`
units, not `KiB`/`MiB`, because `Intl` exposes no binary unit names.

## `lr-relative-time`

`Intl.RelativeTimeFormat` output ("3 hours ago", "in 2 days"), relative to `Date.now()` at render.
Text-only host — no CSS parts, events, or own tokens; locale resolution and `Intl`-instance caching
are as described under `lr-format-number` above.

**Properties:**

- `date: string | number | Date = new Date()` — the target instant; unset means now. Numeric HTML
  attributes are epoch milliseconds, matching numeric property assignment (including zero and
  negative epochs); nonnumeric strings retain ordinary date/ISO parsing. **Changed in 8.0.0:** the
  former empty-string default rendered no content
- `unit: 'second'|'minute'|'hour'|'day'|'week'|'month'|'quarter'|'year'|'auto' = 'auto'` — `'auto'`
  picks the largest unit whose own length fits inside the elapsed time, then rounds; naming a unit
  forces it (so a 90-minute delta with `unit="day"` rounds to "today"/0 days)
- `numeric: 'always' | 'auto' = 'auto'` — `Intl`'s own option: `'auto'` allows "yesterday"/"tomorrow"
  in place of "1 day ago"/"in 1 day"; `'always'` keeps the numeric phrasing
- `format: 'long' | 'short' | 'narrow' = 'long'` — forwarded as relative-time `style`
- `sync: boolean = false` — schedules one timeout at the next rounded-value or auto-unit boundary,
  rather than fixed polling; it is cleared on disconnect and recalculated when inputs change

Valid output is semantic `<time datetime="…">`. **Slots:** none — an unparseable `date` renders the
empty string, with no fallback-content hook (unlike the three `lr-format-*` components above).
Date input accepts primitive strings/numbers or a genuine `Date`; arbitrary objects are rejected
without calling their conversion hooks.

## `lr-known-date`

A form-associated control for a date the user already knows (a birthdate, a passport expiry),
collected as three plain day/month/year number fields in the locale's natural order rather than a
calendar popup. Uses the shared `FormAssociated` mixin; the submitted value is always canonical ISO
8601 (`YYYY-MM-DD`), or `''` while any field is blank or the combination isn't a real calendar date.

Host `aria-describedby` resolves external guidance onto the aggregate date fieldset and follows live
target replacement/removal/reinsertion and document adoption. Each native field retains the
component’s local hint and error guidance. Removed `label` and `hint` render as absent. Removing
`day-label`, `month-label`, or `year-label` restores that field’s localized omitted default; an
explicitly empty label remains empty. Own or fieldset disablement preserves each field’s resting
paint on hover and press.

**Properties:**

- `value: string` — canonical `YYYY-MM-DD` or `''`. Assignment goes through a strict-ISO gate:
  a non-zero-padded (`"2007-3-27"`) or calendar-invalid (`"2007-02-30"`) literal sanitizes to `''`
  and clears all three fields. Programmatic assignment never emits `input`/`change`
- `valueAsDate: Date | null` — the same value as a local-midnight `Date`; settable (assigning
  `null` clears)
- `parts: LyraKnownDateParts` — the live raw `{ day, month, year }` strings. Assigning a complete valid set
  synchronizes the canonical `value`; assigning an incomplete or impossible set clears `value`
- `valueInput: HTMLInputElement` — hidden native `type="date"` mirror kept synchronized with
  `value`, `min`, `max`, `required`, `disabled`, and `readonly` for integrations that inspect native
  date constraints
- `validationTarget: HTMLElement | undefined` (attribute: false) — the browser validation bubble's
  focus anchor; defaults to the first visible day/month/year field in locale order, never the
  hidden `valueInput` mirror. Settable to override which element the popup anchors to
- `min: string = ''`, `max: string = ''` — inclusive `YYYY-MM-DD` bounds, surfaced as
  `rangeUnderflow`/`rangeOverflow`
- `readonly: boolean = false` (reflected) — also suspends all validity flags
- `appearance: 'filled' | 'outlined' | 'filled-outlined' = 'outlined'` (reflected) — field fill and
  border treatment; `pill: boolean = false` (reflected) rounds every field fully
- `size: '2xs' | 'xs' | 's' | 'm' | 'l' | 'xl' = 'm'` (reflected) — control density on the library's
  shared six-step ladder, scaling each field's height floor, padding, font size and corner radius
  together so a birthdate field lines up with the `lr-input`/`lr-date-input` beside it at the same
  declared size. `'small'`/`'medium'`/`'large'` are accepted as exact synonyms of `'s'`/`'m'`/`'l'`,
  so migrating from an upstream that spells them that way needs no attribute rewrite. Every tier
  resolves to at least the 24px pointer-target floor, so even `'2xs'` stays usable
- `label: string = ''`, `hint: string = ''`, `errorText: string = ''` (attribute `error-text`)
- `locale: string = ''` — BCP-47 override for field order and per-field label sampling only
  (redeclared non-reflecting over the base `locale`, like `lr-date-input`)
- `autocomplete: string = ''` — the special value `'bday'` expands to
  `bday-day`/`bday-month`/`bday-year` across the three fields; `'on'` and `'off'` apply to all three,
  while any other non-empty field-specific token is forwarded only to the year field
- `withLabel: boolean = false` (`with-label`) and `withHint: boolean = false` (`with-hint`) — SSR
  slot-presence hints. Normal client rendering detects slotted label/hint content automatically
- `dayLabel?: string` (`day-label`), `monthLabel?: string` (`month-label`), `yearLabel?: string`
  (`year-label`) — visible **and** accessible per-field labels. `undefined` uses the corresponding
  localized default; every supplied string, including `''` and the old English copy, is
  caller-owned
- `accessibleLabel: string | null = null` (attribute `aria-label`) — applied to `[part="fieldset"]`,
  which owns the group role, overriding the `<legend>`-derived name
- The shared form surface adds `defaultValue`, `customError` (`custom-error`), `getForm()`,
  `checkValidity()`, `reportValidity()`, and `setCustomValidity(message)`.

**Static constructor API:** `LyraKnownDate.validators` is the mirrored callable validator catalog.
Each access returns a fresh `LyraFormValidator<LyraKnownDate>[]`; its entry observes
`required`/`disabled`/`readonly`/`value`/`min`/`max`, and `checkValidity(element)` projects the
element's current `ValidityState` into `{ isValid, message, invalidKeys }` without changing it.

```ts
import { LyraKnownDate } from "@aceshooting/lyra-ui/components/utility/known-date/known-date.js";

const knownDate = document.querySelector("lr-known-date")!;
const result = LyraKnownDate.validators[0].checkValidity(knownDate);
```

For mapped JavaScript/TypeScript compatibility, assigning `null` to `name` clears it to the
canonical `''` read value and removes the `name` attribute. The getter remains non-nullable.

**Methods:** `focus(options?)` focuses the first empty field in locale order (or the first field when
all are filled); `blur()` blurs whichever field currently has focus; `resetValidity()` clears a
consumer-supplied custom error and republishes intrinsic constraints;
`formStateRestoreCallback(state)` restores a string state and clears for other shapes.

**Events:** native bubbling/composed `InputEvent` `input` (every keystroke, preserving the private
field edit's `inputType`) and native
bubbling/composed `Event` `change` (a field blur where the composite value newly transitioned),
plus re-dispatched bubbling/composed `focus` and `blur` (`blur` fires once when focus
leaves all three fields, not per field-to-field Tab; each entry into the control likewise produces
exactly one public `focus`, with the private trusted focus suppressed). `input`/`change` detail is
`{ value, day, month, year, field }` — `value` is the canonical ISO date or `''`, `day`/`month`/`year`
are the live raw typed text, and `field` is `'day' | 'month' | 'year'`, whichever was last edited.
`lr-invalid` (no detail) is emitted once as a bubbling/composed alias when native validity fails.

**Slots:** `label`, `hint`, `error` (each rendered alongside its matching property).

**CSS parts:** `base`, `known-date`, and `form-control` are aliases on the same outer wrapper;
`fieldset` (the `<fieldset>` grouping the fields —
carries `aria-label` when `accessibleLabel` is set), `legend` (the `<legend>`; hidden when there is
no label, and grows a `*` suffix while `required`), `form-control-label` (`label` is its deprecated
compatibility alias), `fields` / `form-control-input` (aliases on the flex row), `field` (one field
block, repeated three times, `data-field="day"|"month"|"year"`) plus its matching `field-day`,
`field-month`, or `field-year` token, `field-input` (the native
`<input type="text" inputmode="numeric">` inside it, same `data-field` marker), `field-label` (the
small per-field text label), `hint`, `error` (visible non-live validation text and the fields'
`aria-describedby` target).

Once initial rendering and slot distribution settle, a newly visible or changed validation error
is appended exactly once to Lyra's shared assertive light-DOM announcement sink. Identical renders
are deduplicated, while clearing and later re-showing the same error announces it again. Initial
connection and reconnection do not replay an existing error. Hidden, inert, CSS-hidden, and
`aria-hidden` slotted error content is excluded; revealing meaningful error text is the change that
announces it. Within that error content, `display:none` and `content-visibility:hidden` prune a
branch; a `visibility:hidden|collapse` wrapper suppresses its own text while a descendant that
restores `visibility:visible` remains exposed. Updates also stay silent while the control or a
composed ancestor is hidden, then the current error announces if it becomes newly visible. This
tracking follows nested forwarding slots as well: mutations and reassignment of their flattened
assigned nodes update the announcement without requiring the wrapper component to re-render.

The `label` part alias was deprecated in 8.0.0 in favor of the shared form vocabulary
`form-control-label`. Both names remain on the same node during the compatibility window; use
`::part(form-control-label)` in new CSS. Removal is not scheduled: Web Awesome still publishes its
own deprecated `label` part on `<wa-known-date>`, and a mirrored tag owes its whole upstream
surface, so the alias goes only when upstream's does.

**The required marker.** The `*` the legend grows while `required` is the library's shared
required-field marker, and it takes the same three consumer-settable properties every other
labelled control in the library does: `--lr-form-control-required-content` (the glyph, as a quoted
CSS `content` string; `''` suppresses it), `--lr-form-control-required-color` (default
`var(--lr-color-danger)`) and `--lr-form-control-required-offset` (default `0`). One declaration on
an ancestor — `:root` included — retunes this marker along with every other one in the page. The
one detail specific to this component: `[part="legend"]` owns the marker, while
`[part="form-control-label"]` owns only the label content inside that legend. A
`::part(form-control-label)` rule therefore cannot retheme the marker; use the three public marker
properties above. With no label the legend is hidden and nothing is painted. Full description in
`llms/shared.md` → "The required-field marker".

**CSS states:** `:state(blank)` while the composite value is empty/incomplete;
`:state(disabled)` for direct or fieldset-cascaded disablement.

**Themeable custom properties:** `--lr-known-date-field-padding-block`,
`--lr-known-date-field-padding-inline`, `--lr-known-date-field-font-size` and
`--lr-known-date-field-min-height` all read the shared control ladder rather than a hand-kept copy
of the scale — respectively `--lr-form-control-padding-block`, `--lr-form-control-padding-inline`,
`--lr-form-control-font-size`, and `max(var(--lr-form-control-height), var(--lr-size-24px))`, each
of which the ladder re-points per `size` tier. That is what keeps the three fields the same height
as an `<lr-input>`/`<lr-date-input>` in the same form row at every tier; the
`--lr-known-date-field-*` names are unchanged and are still the documented override point. The
min-height resolves to 24px at `2xs`/`xs` (WCAG 2.2 SC 2.5.8's pointer-target floor, above the
ladder's own 1.25rem/1.5rem there), 1.875rem at `s`, 2.5rem at `m`, 3rem at `l`, 3.5rem at `xl`.
Also `--lr-known-date-field-height`,
`--lr-known-date-field-gap` (default `--lr-space-s` — gap between the three field blocks),
`--lr-known-date-day-field-width` / `--lr-known-date-month-field-width` (default `--lr-size-3-5em`)
and `--lr-known-date-year-field-width` (default `--lr-size-5em`) — the per-field input widths, not
size-scaled. `--lr-known-date-invalid-border-color` (default `var(--lr-color-danger)`) — border
color of each `field-input` while `:host([data-invalid])` is set. Component-scoped indirection over
the shared `--lr-color-danger` token, so a consumer can retheme just this invalid-field border
without repainting every other component that reads the same shared danger token.

The two height knobs work as a pair on `[part='field-input']`, the same way
`lr-input`/`lr-select`/`lr-combobox`/`lr-date-input` expose theirs:

- `--lr-known-date-field-min-height` is a **floor** whose private default follows each `size` tier
  through the shared ladder; an inherited or direct public value remains authoritative. At the
  small tiers the default exceeds the field's own padding/font-driven height and is what
  actually pins the rendered box — that is how `2xs`/`xs` keep a 24px pointer target; at `l`/`xl`
  the content height already clears it, so it is inert there and only raising it changes anything.
- `--lr-known-date-field-height` pins an **exact** height (both floors and caps), so the three
  inputs can line up with a neighbouring control of a known height. It is **undeclared by
  default** — the field grows to fit its content. Never set it to `auto`: `auto` is a valid
  declared value that wins over the `var()` fallback arm, which would make the per-tier floor
  dead code. To go back to the default behavior, remove the declaration rather than neutralizing
  it. Because the component never declares it, it can be set inline, from an ancestor, or from an
  outer-tree rule.

**Known gotchas:**

- Field _order_ is derived from the locale by formatting a probe date (Jan 2 2026) with
  `Intl.DateTimeFormat` and reading back the part order — not from `Date.parse()`'s mm/dd/yyyy bias.
  It falls back to `month, day, year` only when that sampling fails.
- Auto-advance (typing a field's last digit moves to the next) and backspace-into-the-previous-field
  are this library's own additions, not Web Awesome parity. Auto-advance is purely digit-count
  based, never value based.
- Each `<input>` keeps exactly the digits that were typed — never zero-padded, range-clamped, or
  reverted to a previous value; only the composite `value` is normalized to zero-padded ISO.
- Non-digit characters are stripped in the `input` handler before they reach field state (the
  native `<input>`'s own value is rewritten in the same tick). Locale-specific numerals _are_
  accepted and transliterated to ASCII, not rejected: Arabic-Indic (`٠`–`٩`) and Extended
  Arabic-Indic/Persian (`۰`–`۹`) digits are mapped unconditionally, and the digits of
  `effectiveLocale`'s own numbering system are added on top via `Intl.NumberFormat`, so typing
  `٢٠٢٦` into the year field commits `2026`.
- ArrowLeft/ArrowRight cross fields at a field's text boundary, and the _physical_ key meaning
  "next field" flips under an inherited `dir="rtl"`; the locale-derived field order itself does not.
- A blank composite is `valueMissing` only when **all three** fields are blank; a partially typed
  required date reports `badInput` instead.
- The host carries a `:state(blank)` custom state whenever `value === ''`, and `data-invalid` only
  once touched (first blur out of the whole control) and actually invalid.

**Additional API surface:**

- `click()` — Activates the first native field in locale order.

## `lr-random-content`

Shows a chosen subset of its slotted children and hides the rest — A/B copy testing, testimonial
rotation, varying marketing copy per render or interval — with no custom JS beyond slotting the
candidates. Selection is applied by setting `hidden` + `aria-hidden` directly on the light-DOM
children; nothing is moved or cloned.

**Properties:**

- `items: number = 1` — how many children are shown **simultaneously**; a count, not the pool.
  Normalized to a finite integer clamped to `[1, poolSize]`
- `mode: 'unique' | 'random' | 'sequence' = 'unique'` — `'random'` re-rolls freely (repeats
  possible); `'unique'` retries up to 10 times to avoid re-picking the previous selection (only
  when the pool is larger than `items`); `'sequence'` walks the pool in order with a wrapping cursor
- `animation: 'none' | 'fade' | 'fade-up' | 'fade-down' | 'fade-left' | 'fade-right' = 'none'`
  (reflected) — entrance effect applied to a child the instant it becomes shown
- `autoplay: boolean = false` (reflected)
- `paused: boolean = false` (reflected) — suppresses autoplay. The built-in pause/resume action
  toggles this state; a programmatic assignment remains silent.
- `autoplayInterval: number = 3000` (attribute `autoplay-interval`) — clamped to a 1000 ms floor

**Methods:** `randomize(): readonly Element[]` — re-selects using the current `mode`, applies
`hidden`/`aria-hidden`, emits `lr-content-change`, appends the exposed selection text to the shared
polite announcement sink (even when `autoplay` is enabled), and returns the elements now shown.
Does **not** reset or restart the autoplay timer.

**Events:** `lr-content-change` (`detail: { readonly items: readonly Element[] }` — a frozen
snapshot of the exact elements now shown, in display order). Fires on first render, on
`randomize()`, on a real slot-content change, and on
each autoplay tick; never when the eligible pool is empty. `lr-pause-change`
(`detail: { paused: boolean }`) fires only when the built-in pause/resume button toggles `paused`, so a
host mirroring or persisting that state stays in sync; a programmatic `paused` write stays silent,
so a controlled binding can't echo itself. Same event name and payload shape as `<lr-poll-status>`'s
identical affordance, so one handler serves both.

**Slots:** default — the candidate pool. Direct **element** children, including SVG elements, are
eligible. When a wrapper
places a forwarding `<slot>` directly in the pool, its flattened projected elements become the
candidates; an arbitrary nested custom-element subtree remains one opaque direct candidate.

**CSS parts:** `base` — the ordinary wrapper around the default slot; a host `aria-label` gives it
a non-live `role="group"` and is included as announcement context. Selection changes after mount
are appended to Lyra's shared light-DOM polite announcement sink; nested `hidden`, `inert`,
`aria-hidden="true"`, `display:none`, and `content-visibility:hidden` branches are omitted. A
`visibility:hidden|collapse` wrapper suppresses its own text but not a descendant that restores
`visibility:visible`. Timer-driven autoplay ticks stay silent to avoid spam,
but a direct `randomize()` call still announces while `autoplay` is enabled. Initial connection and
reconnection are also silent, including a detached reactive selection change whose update settles
during reattachment; changes while the component or a composed ancestor is accessibility-hidden
stay silent too. A nested forwarding slot contributes flattened assigned content rather than its
fallback; later assignment and assigned-node text/style/visibility changes announce only when they
change the currently exposed selection, while initial distribution remains silent. `pause-button`
— the localized autoplay pause/resume action, rendered
only while `autoplay` is enabled and exposed as a toggle with `aria-pressed`.

**Themeable custom properties:** Web Awesome aliases `--animation-duration` (default `300ms`),
`--animation-easing` (default `ease`), and `--animation-translate` (default
`--lr-size-0-5em` — travel distance for the four directional `fade-*` effects) feed the mapped
`--lr-animation-duration`, `--lr-animation-easing`, and `--lr-animation-translate` names. Existing
`--lr-random-content-animation-duration`, `--lr-random-content-animation-easing`, and
`--lr-random-content-animation-translate` names remain fallbacks. The base owns a wrapping flex
layout for simultaneous selections; `--lr-random-content-item-gap` (default `--lr-space-s`) sets
the row/column gap and `--lr-random-content-item-alignment` (default `flex-start`) sets cross-axis
alignment. Slotted candidates establish transformable inline-block boxes, so directional entrance
animations retain their travel for ordinary inline elements.

**Web Awesome migration note:** `migrate-wa` performs the tag rename and reports only the behavior
groups exercised by each use: host layout (`display: contents` versus Lyra's block host),
multi-item layout ownership, the bounded retry used by `mode="unique"`, direct forwarding-slot
candidates, and autoplay semantics (reduced-motion suppression, silent timer ticks, focus-only
pause, and Lyra's visible localized pause/resume control). An empty element is rewritten without a
behavior warning; direct SVG candidates and the documented animation vocabulary are parity cases.

**Known gotchas:**

- There is no next/previous/shuffle action; the only built-in control is the autoplay pause/resume
  button. Selection changes via autoplay or `randomize()`.
- Autoplay is suppressed entirely under `prefers-reduced-motion: reduce`, and whenever the eligible
  pool has fewer than 2 children. The preference is re-observed live, not just read once.
- `fade-left`/`fade-right` are physical-direction transforms (upstream naming), deliberately **not**
  mirrored under `:dir(rtl)` — they are not previous/next navigational semantics.
- The entrance animation targets `::slotted(*)`, which the library-wide reduced-motion rule cannot
  reach (it only covers the shadow tree), so this component guards it with its own media query.
- The host is `display: block`. For an inline text-fragment swap inside a sentence, override
  `lr-random-content { display: inline; }` from outside; `display: contents` is deliberately not
  used (a11y-tree inconsistencies across engines).
- Slot/focus microtasks and autoplay never queue new selection work while detached; reconnecting
  starts again from current state rather than replaying stale work.
- Non-selected candidates are hidden by the component's own `::slotted([hidden])` rule, not by the
  UA's. `::slotted(*)` sets `display: inline-block` on every candidate, and an author-origin
  declaration always beats the user-agent `[hidden] { display: none }` — so the rule that restores
  the native meaning of `hidden` is load-bearing, and an author overriding `display` on
  `::slotted` content from outside must keep the hidden case at `display: none`.
  `hidden="until-found"` is exempted, exactly as the UA rule exempts it.
- **Before script runs, the first candidate is the one that shows.** Selection happens after the
  first client render and works by setting `hidden`/`aria-hidden` on light-DOM siblings, which Lit
  hydration never compares, so a server renderer can never produce it. Every candidate after the
  first is therefore hidden by CSS until a selection has been applied: a server-rendered page — or
  one whose script never runs — paints one candidate rather than the whole pool. Randomness itself
  cannot survive SSR (there is no shared seed), so order the pool if a specific candidate should be
  the pre-hydration one. With `items > 1` the pre-hydration paint is still a single candidate.

## `lr-tour`

A spotlight-and-step guided walkthrough for first-run onboarding: each step anchors a popover to a
target element elsewhere in the page via the shared Floating UI positioner, over a dimmed
full-viewport backdrop with a cutout/ring around the current target, with Next/Previous/Skip
controls and a step-progress indicator. Controlled component — `steps` is never mutated; only
`activeIndex` and `open` are self-managed.

**Properties:**

- `open: boolean = false` (reflected) — no separate `show()`/`hide()`; set this or call
  `start()`/`end()`
- `steps: readonly Readonly<LyraTourStep>[] = []` (attribute: false) — assignment takes a shallow
  frozen snapshot; empty renders nothing
- `activeIndex: number = 0` (attribute `active-index`, reflected) — clamped to
  `[0, steps.length - 1]` as a finite integer, including for a direct property/attribute write that
  bypasses `goToStep()`; fractions floor and non-finite values fall back to `0`
- `placement: Placement = 'bottom'` (reflected) — tour-level Floating UI default, overridable per
  step; resolved through `rtlAwarePlacement()`
- `distance: number = 12` — px offset between target and popover. Tour-level only (no per-step
  override); may be negative for overlap
- `spotlightPadding: number = 4` (attribute `spotlight-padding`) — extra px between the target's box
  and the cutout/ring; overridable per step
- `lightDismiss: boolean = false` (attribute `light-dismiss`) — a deliberate inversion of
  `lr-dialog`'s `lightDismiss`: a backdrop click does **nothing** by default so a stray click
  can't discard onboarding progress. Set it to make a backdrop click `end('skip')`
- `showProgress: boolean = true` (attribute `show-progress`) — renders the "Step X of Y" text + dots
- `aria-label` (a plain host attribute, not a public JS property) — names **every** step's popover,
  overriding each step's own `heading` as the `aria-labelledby` source

**Exported types:** `LyraTourStep { stepId: string; target: LyraTourTarget; heading: string; content?: string;
placement?: Placement; spotlightPadding?: number; interactiveTarget?: boolean; hidePrevious?: boolean }`;
`LyraTourTarget = string | HTMLElement | (() => HTMLElement | null)` — a string resolves via
`ownerDocument.querySelector` (top-level light DOM only). Every form resolves exactly once when the
step becomes active and is kept as one connected snapshot for that activation, then resolves again
on a later activation/reconnect. Invalid selectors, throwing resolvers, non-`HTMLElement` results,
and detached elements use the normal missing-target path instead of throwing. `heading` normally
becomes the panel's accessible name; a defensive blank/whitespace heading uses the localized
"Step X of Y" string instead, including when progress is visually hidden or the target is missing.
`content` renders as plain text (no HTML/markdown parsing).
Assigning `steps` clone-normalizes at most 256 own-data plain records into an immutable snapshot;
accessor/inherited/malformed rows and invalid optional fields are omitted while later valid siblings
remain usable. Step ids and headings are bounded to 256 and 4,096 characters, target selector
strings to 8,192, and body content to 65,536. Per-step spotlight padding is finite, non-negative,
and capped at 10,000px. Provider mutation after assignment cannot change rendering or event detail.
`LyraTourEndReason = 'completed' | 'skip' | 'escape' | 'api' | 'unmount' | (string & {})`.

**Methods:** `start(index = 0)` (clamps, opens, emits `lr-tour-start`), `next()` (on the last step
ends with `'completed'` instead), `back()` (no-op on the first step), `goToStep(index)` (clamped),
`skip()` (sugar for `end('skip')`), `end(reason: LyraTourEndReason = 'api')`.

**Events:** `lr-tour-start` (`detail: { index }`, not cancelable); `lr-tour-step-change`
(`detail: { index, previousIndex, step, via: 'next'|'back'|'goto' }`, **cancelable** — fires before
`activeIndex` changes, so `preventDefault()` gates advancement on a real action; a deliberate
departure from `lr-carousel`'s non-cancelable `lr-slide-change`); `lr-tour-end`
(`detail: LyraTourEndReason`, cancelable except in practice for `'unmount'`, which is emitted when the
element is removed while still open by something other than its own `end()`);
`lr-tour-target-missing` (`detail: { index, step }`, informational — the tour does **not** auto-end,
it renders that step viewport-centered with no spotlight).

**Slots:** default — rich content replacing the active step's plain-text `content`. Not scoped per
step: a consumer needing different rich content per step swaps the slotted children itself (e.g. on
`lr-tour-step-change`).

**CSS parts:** `backdrop` (the full-viewport `<svg>` scrim with the cutout, `aria-hidden`),
`spotlight` (the decorative ring around the padded target rect, `pointer-events: none`),
`popover` (the step panel, `role="dialog"`, `aria-modal="true"` for default steps and `"false"` for
an `interactiveTarget` step, `data-unanchored` when the target didn't resolve), `heading` (the
`aria-labelledby` target), `body` (slot or `step.content`),
`progress` (wrapper), `progress-text` (the "Step X of Y" text — an `aria-describedby` target),
`progress-dot` (one decorative dot per step, `data-current` on the active one, `aria-hidden`),
`footer` (the control row), `previous-button`, `skip-button`, `next-button` (the Next control's
label switches to Done on the last step).

**Themeable custom properties:** `--lr-tour-backdrop-color` (default `--lr-color-overlay`),
`--lr-tour-spotlight-radius` (default `--lr-radius` — shared by the cutout and the ring),
`--lr-tour-spotlight-ring-color` (default `--lr-color-brand`), `--lr-tour-spotlight-ring-width`
(default `--lr-border-width-medium`), `--lr-tour-popover-max-width` (default `--lr-size-22rem`,
further capped by `--lr-popover-viewport-clamp` and the positioner's available space),
`--lr-tour-progress-dot-current-bg` (default `var(--lr-color-brand)`) — background of
`progress-dot` for the current step. Component-scoped indirection over the shared `--lr-color-brand`
token, so a consumer can retheme just the current-step dot without repainting every other component
that reuses the same shared brand token.

`--lr-popover-viewport-clamp` (default `92vw`, from `--lr-theme-popover-viewport-clamp`) is the
shared ceiling that keeps any floating surface inside a narrow viewport. `lr-tour`,
`lr-mention-popover`, and `lr-export-button` all `min()` their own max-inline-size against it, so
retuning `--lr-theme-popover-viewport-clamp` once at `:root` narrows or widens all three together
rather than per component.

`--lr-positioning-strategy` (16.0.0) — the step popover reads this same cascading `absolute`/`fixed`
override documented on `<lr-popover>` when a step is (re)positioned, falling back to its own `fixed`
default when nothing is set. There is no per-instance `positioning-strategy` property on `<lr-tour>`;
set the custom property on `:root`, a theme, or one clipping ancestor to change every unset tour
beneath it.

**Known gotchas:**

- By default the spotlighted target is **non-interactive**: it stays visible and announceable (not
  `inert`, not `aria-hidden`) but every pointer event over the viewport is captured by the backdrop.
  A default step uses a modal overlay and traps focus in the panel. Set `step.interactiveTarget` to
  clip the backdrop around the target, switch the panel to nonmodal semantics, and install an
  explicit bounded Tab scope over the panel and the live composed target descendants, so nested,
  forwarded, dynamically disabled, and inert controls cannot leak focus to unrelated page content.
- A live transition between modal and interactive-target steps preserves the trigger captured when
  the tour opened. Intermediate overlay ownership changes never restore focus; a genuine end returns
  to that original trigger when it is still connected.
- Each step transition mounts a genuinely new popover node keyed on occurrence index plus
  `step.stepId`, so repeated business ids cannot collapse distinct occurrences. Every step-related
  event exposes the occurrence index, which is the authoritative collection identity; focus
  reliably re-enters the panel — don't cache a reference to `[part="popover"]` across steps.
- No `Home`/`End` shortcut and no click-to-jump progress dots (unlike `lr-stepper`): later steps may
  depend on an earlier step's side effect having run. `goToStep()` is available for a caller that
  knows better. ArrowRight/ArrowLeft do move between steps (swapped under RTL), except while focus
  is in an `input`/`textarea`/`contenteditable` inside slotted content.
- A direct `HTMLElement` target must be connected at activation and is treated as missing after a
  remount; prefer a selector string or resolver function for targets that can be replaced between
  activations.
- The active step's target is `scrollIntoView({ block: 'center' })`'d on activation, smoothly unless
  `prefers-reduced-motion: reduce`.
- Changing `placement`, `distance`, or tour-level `spotlightPadding` while open repositions/repaints
  the current step live without scrolling again or emitting a duplicate `lr-tour-target-missing`.

## Exported TypeScript contracts

These named interfaces and helper signatures are available to typed integrations. They are grouped by capability so the component sections above can stay focused.

- **`components-utility-diff-view-diff-line-diff-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui`.
  `computeLineDiff(oldLines: string[], newLines: string[]): LyraDiffOp[]`
  Import: `@aceshooting/lyra-ui`.
  `LyraDiffOp {
    type: 'equal' | 'add' | 'remove';
    text: string;
  }`

- **`components-utility-export-button-csv-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/utility/export-button/csv.js`.
  `buildCsv(rows: readonly Readonly<Record<string, unknown>>[], columns: readonly LyraCsvColumn[], options?: LyraBuildCsvOptions): string`
  Import: `@aceshooting/lyra-ui/components/utility/export-button/csv.js`.
  `downloadBlob(content: string, filename: string, mime: string, ownerDocument?: Document): void`
  Import: `@aceshooting/lyra-ui/components/utility/export-button/csv.js`.
  `escapeCsvField(value: unknown): string`
  Import: `@aceshooting/lyra-ui/components/utility/export-button/csv.js`.
  `LyraBuildCsvOptions {
    readonly bom?: boolean;
  }`
  Import: `@aceshooting/lyra-ui/components/utility/export-button/csv.js`.
  `LyraCsvColumn {
    readonly key: string;
    readonly label: string;
  }`

- **`components-utility-export-button-export-button-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/utility/export-button/export-button.class.js`.
  `LyraExportFormatDescriptor {
    readonly formatId: string;
    readonly label: string;
    readonly description?: string;
    readonly extension?: string;
  }`

- **`components-utility-icon-icon-library-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/utility/icon/icon-library.js`.
  `getIconLibrary(name: string): LyraIconLibrary | undefined`
  Import: `@aceshooting/lyra-ui/components/utility/icon/icon-library.js`.
  `LyraIconLibrary extends LyraIconLibraryOptions {
    readonly name: string;
    // Inherited from LyraIconLibraryOptions.
    resolver: LyraIconLibraryResolver;
    mutator?: LyraIconLibraryMutator;
  }`
  Import: `@aceshooting/lyra-ui/components/utility/icon/icon-library.js`.
  `LyraIconLibraryOptions {
    resolver: LyraIconLibraryResolver;
    mutator?: LyraIconLibraryMutator;
  }`
  Import: `@aceshooting/lyra-ui/components/utility/icon/icon-library.js`.
  `registerIconLibrary(name: string, options: LyraIconLibraryOptions): void`
  Import: `@aceshooting/lyra-ui/components/utility/icon/icon-library.js`.
  `unregisterIconLibrary(name: string): void`

- **`components-utility-known-date-known-date-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/utility/known-date/known-date.class.js`.
  `LyraKnownDateEventDetail {
    value: string;
    day: string;
    month: string;
    year: string;
    field: LyraKnownDateField;
  }`
  Import: `@aceshooting/lyra-ui/components/utility/known-date/known-date.class.js`.
  `LyraKnownDateParts {
    day: string;
    month: string;
    year: string;
  }`

- **`components-utility-mention-popover-mention-popover-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/utility/mention-popover/mention-popover.class.js`.
  `LyraMentionFocusOptions {
    readonly ownsFocus?: () => boolean;
  }`
  Import: `@aceshooting/lyra-ui/components/utility/mention-popover/mention-popover.class.js`.
  `LyraMentionItem {
    readonly suggestionId: string;
    readonly label: string;
    readonly description?: string;
    readonly icon?: string;
    readonly disabled?: boolean;
  }`
  Import: `@aceshooting/lyra-ui/components/utility/mention-popover/mention-popover.class.js`.
  `LyraMentionSelectDetail {
    readonly suggestionId: string;
    readonly index: number;
    readonly label: string;
  }`

- **`components-utility-tour-tour-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/utility/tour/tour.class.js`.
  `LyraTourStep {
    readonly stepId: string;
    readonly target: LyraTourTarget;
    readonly heading: string;
    readonly content?: string;
    readonly placement?: Placement;
    readonly spotlightPadding?: number;
    readonly interactiveTarget?: boolean;
    readonly hidePrevious?: boolean;
  }`

- **`internal-clipboard-contracts`** — Shared utility contracts.
  Import: `@aceshooting/lyra-ui/components/utility/copy-button/copy-button.class.js`.
  `LyraClipboardWriteFailure {
    readonly ok: false;
    readonly text: string;
    readonly reason: LyraCopyErrorReason;
    readonly error: unknown;
  }`
  Import: `@aceshooting/lyra-ui/components/utility/copy-button/copy-button.class.js`.
  `LyraClipboardWriteSuccess {
    readonly ok: true;
    readonly text: string;
  }`

# Media, files & maps (`components/media/`)

## Breaking changes in 10.0.0

`<lr-media-card>`'s `alt` becomes optional (`alt?: string`, was `alt: string = ''`), so a decorative
image is expressible at last. The image render used to fall through `alt`, then `filename`, then a
localized generic description with `||`, which made an explicit `alt=""` indistinguishable from an
absent one and published it as `alt="Image attachment"` — there was no way to mark the image
decorative, which is the one thing
`alt=""` means in HTML. It now reads `??`, matching `<lr-image-viewer>` and `<lr-document-preview>`,
which already documented that contract. Omitting `alt` is unchanged; only the value read back from
an unset property differs (`''` becomes `undefined`), so a consumer comparing `el.alt === ''` should
read `el.alt ?? ''`. The nested `<video controls>` label deliberately does **not** follow: an empty
`alt` there would leave an interactive player with no accessible name, and "decorative" is not a
state a media control can be in, so the video path still falls through to `filename` and the generic
description.

`<lr-attachment-chip>`'s `lr-preview-request` is no longer cancelable. It was advertised as a veto
point, but the chip never read `defaultPrevented` and owns no preview default action to cancel — it
never registers or owns a viewer or overlay, by its own documented contract — so `preventDefault()`
was a no-op. The flag is removed rather than left as a promise the component cannot keep: a host that
was calling `preventDefault()` can drop the call, and one that believed the call was suppressing
something was never being served. `<lr-voice-picker>`'s same-named event belongs to a different
component, owns a real internal default action, and stays cancelable.

Also corrected in 10.0.0 — not breaking, but visible. `<lr-flag>` no longer paints a full-size
undecoded image beside its own skeleton while loading; `<lr-video>` no longer keeps a second,
duplicate controls play button both painted and focusable behind a poster, and it now keeps captions
for a `<track>` with no `kind` attribute, whose HTML missing-value default is `subtitles`; and
`<lr-avatar>` and `<lr-image-comparer>` honor a consumer's `hidden` slotted child. In each case the
component's own author-origin declaration was beating the UA stylesheet's `[hidden] { display: none }`
regardless of specificity.

## Breaking changes in 9.0.0

`<lr-media-card>`'s `accessibleLabel` property now defaults to `null` instead of `''`
(`string | null`, matching `<lr-pan-zoom>`/`<lr-zoomable-frame>`). Behavior is unchanged: an explicit
empty string and the unset default both still fall through to the generated purpose-specific action
name — only the value read back from an unset property differs. A consumer comparing against `''`
should switch to `== null` / `?? ''`.

## `lr-flag`

Country/language flag image. Flag artwork ships in a **separate, optional peer package**
(`@aceshooting/lyra-flags`) — importing `lyra-ui` core never pulls in flag image weight.

**Properties:**

- `country?: string` (ISO 3166-1 **alpha-2 or alpha-3**, e.g. `"fr"` or `"FRA"` — takes
  precedence over `language`). Length alone disambiguates the two code spaces, so no format hint
  is needed: a 2-letter value is alpha-2, a 3-letter value is alpha-3. Alpha-3 support exists
  because public statistical sources (World Bank, UN, IMF, most open-data portals) key country
  records on alpha-3; the 249 officially-assigned mappings are packed as a ~1.2 KB fixed-width
  string and expanded lazily on the first alpha-3 lookup, so an alpha-2-only app never pays for
  them. Withdrawn and user-assigned codes deliberately do not map to a successor state — they
  take the unresolved path below
- `fallback?: string` — placeholder image URL rendered when the code cannot resolve to a current
  flag. The `fallback` slot wins over it
- `language?: string` (BCP-47-ish tag, e.g. `"en"`/`"en-US"`, resolved to a representative country
  via `languageToCountry()`)
- `src?: string` (a pre-resolved flag image URL — takes precedence over `country`/`language` and
  skips the peer-package lookup; mainly useful to avoid even
  the small per-flag async hop when you already have the URL at build time, e.g. from
  `import frUrl from '@aceshooting/lyra-flags/flags/fr.svg?url'`. `label` is effectively required
  alongside `src` since there's no `country`/`language` to derive a fallback `alt` from.)
- `label?: string` (accessible name / `alt` text — **defaults to a localized, human-readable region
  name derived from the _resolved country_ code via `Intl.DisplayNames` if omitted**, see gotchas)
- host `aria-label` takes precedence over `label` and the derived region name; an explicit empty
  value marks the image decorative
- `shape: LyraFlagShape = 'rect'` (reflected, `'rect' | 'circle'`)
- `fidelity: LyraFlagFidelity = 'standard'` (reflected — picks a
  fidelity tier for the ~65 codes whose source art embeds a coat of arms/seal/emblem; every other
  code resolves to the same file regardless of `fidelity`. `'compact'` = a tiny WebP raster for
  icon-scale use (menus, language pickers, ~12–28px); `'standard'` = the icon-optimized vector for
  card/row sizes (~28–96px); `'detailed'` = the
  pristine full-fidelity vector for hero-scale display. No effect when `src` is set.)

The v9 vocabulary replaces `round` with `shape="circle"` and `variant` with `fidelity`; exported
authoring types are `LyraFlagShape`, `LyraFlagFidelity`, and `LyraFlagUrlResolver`.

**Events:** none.

**Slots:** `fallback` — rendered in place of the flag when `country`/`language` cannot resolve to a
current flag (an unassigned, historical, or malformed code). Wins over the `fallback` property.

**CSS parts:** `image` (the underlying `<img>`, exposed once native loading succeeds),
`fallback-image` (the `fallback` property's placeholder, when no slot content is supplied), `error`
(contained localized visible text rendered when URL validation, peer resolution, or native image
loading fails). The host reflects the terminal error state with `data-error`, and an unresolvable
code with `data-unresolved`. **The two are deliberately distinct:** a dissolved federation or
unrecognized territory in a longitudinal dataset is *data*, not a defect, so it renders the neutral
fallback (occupying its normal footprint in a table or card grid) rather than localized error
wording that reads to a user as a bug. Style the two states apart with those attributes.
The built-in `fallback-image` uses the same full-frame sizing, `object-fit`, circle clipping, and
forced-colors inset boundary as the resolved `image`; replacing it with slotted fallback content
leaves that content's presentation under the caller's control.

**Themeable custom properties:** `--lr-flag-radius` (default `calc(var(--lr-radius) * 0.33)` —
rectangular corner radius), `--lr-flag-aspect-ratio` (default `4 / 3`), and
`--lr-flag-object-fit` (default `cover`); also consumes `--lr-color-border` for the inset ring.

**Sizing.** The host has no intrinsic `width` — it sizes from `font-size` (`block-size: 1em`,
`inline-size` derived from `--lr-flag-aspect-ratio` via CSS `aspect-ratio`), so it scales naturally
with surrounding text (`<lr-flag style="font-size: 2rem">`). Setting `width`/`inline-size` directly
instead makes both axes definite, which defeats `aspect-ratio` (only applies when at most one axis
is definite) and squashes the image rather than scaling it.

**Optional peer deps:** `@aceshooting/lyra-flags` — required for the component to actually render an
image when `country` or `language` is used. Import
`@aceshooting/lyra-ui/components/media/flag/flag-peer.js` once to opt into
that resolver; a pre-resolved `src` works without the peer registration entry. If the peer is not
installed — or if `flag-peer.js` was simply never imported, which looks identical from the page —
the component fails closed with localized visible `[part="error"]` text, a shared light-DOM
assertive announcement, and a one-time `console.warn` naming the unresolved code and this import
(see gotchas).

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:
`localeNativeName(tag: string): string`.

`localeNativeName()` returns a BCP-47 tag's **endonym** — the locale's name written in that locale
itself (`'fr'` → `français`, `'pt-BR'` → `português (Brasil)`). That is what a language switcher
should list, so a reader who understands none of the current UI language can still find their own.
It derives from `Intl.DisplayNames`, so no name table ships with the library and results follow the
browser's own ICU data; the underlying instance comes from a shared memoized cache, since a picker
does one lookup per offered locale on every render pass. A tag with no display name resolves to the
tag itself, and so does a structurally invalid one — `Intl.DisplayNames` throws a `RangeError` on
those rather than falling back, and a language picker should degrade to showing the raw tag rather
than tearing down the render. Pair it with `languageToCountry()` for the flag half of the same row.

**Locale picker recipe.** `<lr-locale-picker>`
(`@aceshooting/lyra-ui/components/lr-locale-picker.js`) is the built-in
locale switcher — a closed-list dropdown over the locale registry or an explicit catalog, with
`lr-flag`/`localeNativeName()` rows and full form association out of the box. The manual
composition below remains available for an app that wants different chrome (its own dismiss
surface, a different active-state marker, or a layout `<lr-locale-picker>` doesn't offer):
`<lr-popover>` supplies the light-dismiss surface, `<lr-flag>` the country mark,
`localeNativeName()` the endonym, and `aria-current="true"` marks the active choice. Which locales
exist is the app's decision, so the app owns the list. Set `lang` on each row so assistive tech
pronounces the endonym in its own language, and use `fidelity="compact"` at icon scale.

```html
<lr-popover placement="bottom-start">
  <button slot="trigger">
    <lr-flag language="fr" label="" style="height: 1rem"></lr-flag>
    <span>français</span>
  </button>
  <ul role="list">
    <!-- one <li><button lang="pt-BR" aria-current="false"> … </button></li> per offered locale -->
  </ul>
</lr-popover>
```

```js
import {
  localeNativeName,
  languageToCountry,
} from "@aceshooting/lyra-ui/components/media/flag/language-map.js";

const rows = ["en", "fr", "de", "pt-BR", "ja", "ar"].map((tag) => ({
  tag,
  name: localeNativeName(tag), // endonym, e.g. "português (Brasil)"
  country: languageToCountry(tag), // flag code for the same row
}));
```

```html
<lr-flag country="fr" label="France"></lr-flag>
<lr-flag language="en-US" shape="circle"></lr-flag>
<lr-flag country="es" fidelity="compact"></lr-flag>
<!-- tiny WebP raster, icon-scale -->
<lr-flag country="es" fidelity="detailed"></lr-flag>
<!-- pristine full-fidelity vector -->
```

```bash
pnpm add @aceshooting/lyra-flags   # required for country/language lookup; failures render error text
```

```js
import "@aceshooting/lyra-ui/components/media/flag/flag-peer.js";
```

**Known gotchas:**

- `country`/`language` resolution is opt-in through
  `@aceshooting/lyra-ui/components/media/flag/flag-peer.js`; `all.js`
  registers the component without importing the optional flag asset graph. Requires the optional
  peer `@aceshooting/lyra-flags` to actually render an image; without it the component still shows a
  decorative `<lr-skeleton shape="rect" announce="false">` placeholder while resolving. The
  host exposes `aria-busy="true"`, and ordinary sr-only text preserves the localized `loading`
  label without creating a shadow live region. Resolution failure then **fails closed** into ordinary localized
  `<span part="error">` text (the `flagLoadError` message key, `"Flag unavailable"` by default).
  Each fresh failure appends that same localized message to the document's pre-mounted
  `[data-lr-live-region="assertive"]` sink, so the shadow chrome itself is not live and identical
  retries remain separate additions. The failure also produces a one-time `console.warn`
  once the resolver rejects (lazy `import()`, cached module-wide so the warning fires only once per
  page even with many `<lr-flag>` instances). A **separate** one-time `console.warn` covers the
  commonest setup mistake — `country`/`language` set while no resolver was ever registered, i.e.
  `flag-peer.js` was not imported. It names the offending code and that import path, because the
  visible `[part="error"]` state alone is indistinguishable from missing flag data. It is armed
  once per resolver-registration generation, so a table of many flags warns once.
  An _empty_ template is a different, non-error outcome:
  the peer resolved fine but returned no URL for that code (e.g. `country="zz"`) — no `[part="error"]`,
  no `<img>`, no warning.
- Rendering is async even when the peer _is_ installed: `src` resolves after an `import()` +
  resolver call, so there's a brief loading-skeleton window on first paint/attribute change — don't
  assume the `<img>` exists synchronously right after setting `country`/`language`.
- if both `aria-label` and `label` are omitted, the accessible name (`alt`) falls back to a localized
  region name via `Intl.DisplayNames([effectiveLocale], { type: 'region' })` (e.g. `"United Kingdom"`) instead of
  a bare code — for `language="en"` that's derived from `"GB"` (the mapped country), not `"EN"` (the
  language tag itself). Falls back further to the bare uppercase code if `Intl.DisplayNames` throws
  for an unrecognized region or isn't available. You can still pass an explicit `label` (e.g.
  `"France"`) to override the derived name.
- an invalid `country` (anything not matching the ISO 3166-1 alpha-2 shape, e.g. containing `../`)
  is rejected before it ever reaches the peer's `flagUrl()` resolver — treated the same as an
  unknown/missing flag rather than being passed through. `languageToCountry()`'s region-subtag path
  is validated against that same alpha-2 shape too (not just a bare length-2 check), so a malformed
  region such as `"en-01"` correctly falls through to the `LANGUAGE_TO_COUNTRY[base]` lookup instead
  of being accepted verbatim as a country code.
- rapidly reassigning `country`/`language`/`src` no longer risks a stale resolution overwriting a
  newer one: each resolver call is tagged with a token captured at the time it was kicked off, and a
  `.then()` that fires after a later change (or after the field was cleared) is discarded instead of
  clobbering the rendered image/`loading`.
- `country`/`language` resolve through `@aceshooting/lyra-flags`'s `flagUrl(code)`, which lazily
  fetches one requested flag at runtime. A bundler may still emit the complete reachable lazy-chunk
  graph because every supported code has a literal loader import; use a literal asset subpath
  import when the deployment artifact must be pruned. If every `<lr-flag>` in the app is pinned to
  one `fidelity` (no per-instance switching), register
  `@aceshooting/lyra-flags/standard`/`/compact`/`/detailed` via `setFlagUrlResolver()` instead of
  importing `flag-peer.js` (which always registers the full three-tier resolver) — the tier-specific
  entry excludes the other two tiers' generated loader maps from the reachable graph; see that
  package's README. If you already have a flag's URL at build
  time, `src` skips the peer-package round trip; native image loading still uses the same bounded
  loading/error transaction.
- Rendering many flags at once (a country table, a picker listing every locale): resolve every code
  up front with `@aceshooting/lyra-flags`'s `flagUrls()` (one call, returns `{code: url}` for all
  249 flags) and pass results through `src`, instead of letting each `<lr-flag>` instance
  independently call `flagUrl()` — skips one peer-resolution round trip per instance. Image fetches
  themselves are unaffected either way (each flag is a distinct asset; there is no sprite).
  Alternatively, import `@aceshooting/lyra-ui/components/media/flag/flag-peer-bulk.js` instead of
  the default `flag-peer.js` (never both) to get this automatically: it registers a resolver backed
  by one shared `flagUrls()` call, so every `<lr-flag>` on the page benefits without threading `src`
  by hand. Only worth it when the page renders most/all flags — a page with a handful pays an
  unneeded 249-entry fetch. Only the standard tier is bulk-fetched this way;
  `fidelity="compact"/"detailed"` on individual elements still resolves through its own lazy
  per-code loader.
- Rendering many flags at once **and** leaving every `<lr-flag>` on the default
  `fidelity="standard"`: import
  `@aceshooting/lyra-ui/components/media/flag/flag-peer-bulk-standard.js` instead of
  `flag-peer-bulk.js` (never more than one of the three peer entries — each
  `setFlagUrlResolver()` call replaces the previous resolver). It registers
  `@aceshooting/lyra-flags/standard`'s `createFlagUrlResolver()`, which is backed by the same
  standard-tier-only eager map as the root's, without statically importing the detailed and
  compact loader maps the root entry needs for its per-call `variant`. Those maps are what
  `flag-peer-bulk.js` pays for its batching: on a real production build with a 156-country flag
  column, routing bulk resolution through the package root emitted +65 detailed SVGs and +31
  compact WebPs — +15.8MB of assets no route rendered — swamping the chunk-count win the bulk path
  exists for. The tradeoff is the tier commitment: `fidelity="compact"/"detailed"` on an individual
  element resolves to that code's standard asset instead (a silent no-op, not an error), so use
  `flag-peer-bulk.js` when per-instance fidelity must actually be honoured.
- 65 of `@aceshooting/lyra-flags`' 249 flags (any whose design includes a detailed coat of
  arms/seal/emblem, e.g. `es`, `pt`, `sv`) ship **three** fidelity tiers, selected via the
  `fidelity` property (`flagUrl(code, { variant: fidelity })` under the hood): `"compact"` — a tiny WebP raster for
  icon-scale use (menus, language pickers, dense lists); `"standard"` — the default, the
  icon-optimized vector for card/row sizes, ~84% smaller on average than the pristine source for the
  65 affected codes with no visible fidelity loss at that scale; `"detailed"` — the pristine
  full-fidelity vector, for hero-scale display where the extra illustrative detail is actually
  visible. The other 184 codes resolve to the same file regardless of `fidelity` — a safe no-op.

**Additional API surface:**

- `part="error"` — Ordinary localized visible text rendered when the optional peer resolver is
  unavailable or fails; the fresh transition is announced by the shared light-DOM assertive sink.

---

## `lr-sequence-playback`

Steps a current index through `[0, itemCount)` on a fixed interval — explicit discrete-sequence
playback for time-series scrubbing, without implying native audio/video playback.

When fewer than two items are available, the disabled play button retains its resting border and
background under hover and press. Enabled playback controls retain their token-driven pointer
feedback.

**Properties:**

- `itemCount: number = 0` (attribute `item-count`)
- `currentIndex: number = 0` (attribute `current-index`)
- `intervalMs: number = 900` (attribute `interval-ms`)
- `playing: boolean = false` (reflected)
- `loop: boolean = true`
- `hidden: boolean = false` (reflected; re-declared over the native IDL property so Lit's
  change-tracking sees it and auto-pauses on `hidden = true`)

**Methods:** `play()`, `pause()`, `toggle()`, `next()`, `previous()`,
`goTo(currentIndex: number)` — all idempotent/clamped; `itemCount <= 1` is a no-op degenerate case.
`focus(options?)`, `blur()`, and
`click()` forward to the play button.

**Events:** `lr-play`, `lr-pause` (no detail), `lr-sequence-step`
(`detail: LyraSequencePlaybackStepDetail { currentIndex }`, fired on every tick and manual step);
internal `focus`/`blur` are relayed exactly once as owner-realm native `FocusEvent`s (bubbling and
composed, preserving `relatedTarget`).

**Class and event types:** `LyraSequencePlayback`, `LyraSequencePlaybackEventMap`, and
`LyraSequencePlaybackStepDetail`. The former generic `LyraPlayback`, `<lr-playback>`, `length`,
`index`, and `lr-step` names are removed in v9 rather than retained as ambiguous aliases.

**Slots:** none.

**CSS parts:** `base`, `play-button`, `slider`

The `slider` carries supplemental localized `aria-valuetext` — `Step {index} of {total}` (key
`playbackStepPosition`, both numbers formatted with the component's effective locale). Browsers may
ignore that override on a native range, so the interoperable semantic contract is itself one-based
(`min=1`, `max=itemCount`, `value=currentIndex+1`): assistive technologies receive the correct
ordinal even when they expose the native numeric value.

**Themeable custom properties:** `--lr-sequence-playback-icon-size` (default
`calc(var(--lr-icon-button-size) * 0.35)` — the play/pause glyph's size; applied as the button's
`font-size`, and the inline SVG renders at `1em`).
`--lr-sequence-playback-play-button-active-bg` (default
`color-mix(in oklab, var(--lr-color-surface), var(--lr-color-mix-partner) var(--lr-color-mix-active))`) —
the pressed play/pause background; and `--lr-sequence-playback-play-button-active-border-color` (default
`var(--lr-color-brand)`) — its pressed border. Both are inline `var()` fallbacks, so a value set on
the element or an ancestor inherits without being shadowed by a host default. Plus shared tokens `--lr-space-s`,
`--lr-color-border`, `--lr-color-surface`, `--lr-color-text`, `--lr-color-brand`,
`--lr-icon-button-size` (the play button's box), `--lr-opacity-disabled` (play button/slider
dimming at `itemCount <= 1`), `--lr-focus-ring-*`.

**Optional peer deps:** none.

```html
<lr-sequence-playback item-count="24" interval-ms="500"></lr-sequence-playback>
<script>
  const playback = document.querySelector("lr-sequence-playback");
  playback.addEventListener("lr-sequence-step", (event) => {
    renderFrame(event.detail.currentIndex);
  });
</script>
```

**Known gotchas:**

- `currentIndex` is re-clamped into `[0, itemCount)` as soon as `itemCount` shrinks (in
  `willUpdate()`, not waiting for the next `tick()`/`goTo()`/`next()`/`previous()` call) — setting
  `el.itemCount = 2` while `el.currentIndex = 7` immediately pulls `currentIndex` back to `1`, and
  playback auto-pauses if `itemCount` drops
  to `<= 1` while playing (the play button and slider would otherwise both become disabled with no
  way to stop it — both are `?disabled` whenever `itemCount <= 1`, not just the button).
- `intervalMs` is live-reactive mid-playback: ticking is a self-rescheduling `setTimeout` (not one
  long-lived `setInterval`), so `intervalMs` is re-read fresh before every tick — changing
  `interval-ms` while `playing` takes effect on the very next step instead of only after a
  pause/play cycle.
- `itemCount` and `currentIndex` are normalized to finite non-negative integer counts, with
  `currentIndex` clamped into `[0, itemCount)`; fractional, negative, `NaN`, infinite, and oversized
  values cannot poison end conditions or the slider.
- `interval-ms` is clamped to the 16ms floor and the browser's finite timer ceiling: a non-finite or
  lower value ticks at 16ms, while an oversized value uses the timer ceiling.
- Initial `playing` and `item-count` attributes are resolved together on the first update, so
  playback starts consistently regardless of their source order; an invalid final `itemCount <= 1`
  clears the reflected `playing` state.
- No _visible_ "N of M" position label beside the range input; the native one-based range still
  exposes the current ordinal and total bounds, with localized `aria-valuetext` as a supplemental
  enhancement where the platform honors it.
- Calling `play()`/`pause()` programmatically (not via the button) gives no `aria-live`
  announcement of the Play/Pause state change.

---

## `lr-map`

A `maplibre-gl` wrapper with a declarative legend, a single choropleth GeoJSON fill layer, markers,
and additive `dataLayers` — plain GeoJSON, natively clustered points, or a heatmap density surface —
plus a peer-neutral `map` getter for common imperative operations. Its runtime value is the
underlying MapLibre map. The component observes its own map-container allocation and calls the
peer's `resize()` when that allocation changes.

Markers and popups use the physical top-left origin required by MapLibre's projected transforms in
both LTR and RTL. Their text and surrounding controls retain logical direction-aware layout.

Live ancestor theme or token changes resolve the choropleth's stop colors and explicit or implicit
step base color again, as well as its opacity. These are paint-only updates on the existing fill
layer: the map instance, source, layer and viewport are preserved. Linear, logarithmic and step
modes use the same expression semantics at initial render and after a theme change.

**Properties:**

- `center: [number, number] = [0, 0]`
- `zoom: number = 2`
- `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
  later change takes effect after the component is disconnected and reconnected.
- `mapStyle?: LyraMapStyleSpecification | string` (attribute: false) — required before a map is
  constructed. Object assignments are detached and recursively frozen; create and reassign a new
  style to update it. `LyraMapStyleSpecification` is the peer-neutral structural subset accepted from
  MapLibre's `StyleSpecification`, including its string or multi-sprite form. No provider or style
  is selected implicitly: an unset, empty, or whitespace-only value renders the localized
  style-required failure and makes no tile/style request. Assign a hosted vector/raster style from
  a provider whose terms fit your application, or an explicitly network-silent style for local
  geometry.
- `legendGradient: readonly (readonly [number, string])[] = []` (attribute: false, type
  `LyraMapLegendGradientStop[]`) — renders the legend as a **continuous** gradient bar with endpoint
  captions instead of (or alongside) the discrete `legend` swatches, which is the standard key for a
  choropleth whose `interpolate` fill is itself a continuous ramp. Takes the same `[value, color]`
  stop shape as `choropleth.stops`, so the usual assignment is `map.legendGradient =
  myChoropleth.stops` and the key cannot drift from the layer it describes. Stops are sorted
  ascending, bounded to 64, and filtered to finite values carrying a CSS-parsable color; fewer than
  two usable stops render no bar at all, since a one-stop "gradient" is a flat block that describes
  nothing. Each stop sits at its true proportion of the value range, so the bar shows the ramp the
  expression actually produces rather than evenly spacing unevenly-spaced values. A logarithmic
  choropleth renders bounded samples of the same exponential interpolation in the gradient rather
  than showing a misleading CSS-linear ramp. In development, independently authored
  `legendGradient` and `choropleth.stops` arrays that disagree produce a once-per-page warning;
  assigning the same stops (or deriving both from one source) avoids drift. Part names
  (`legend-gradient`, `legend-lo`, `legend-hi`) mirror `lr-heatmap`'s gradient legend, and the bar
  is `aria-hidden`/`inert` with the captions carrying the meaning. Mirrors under RTL
- `legendGradientLoLabel: string | null = null` (attribute `legend-gradient-lo-label`),
  `legendGradientHiLabel: string | null = null` (attribute `legend-gradient-hi-label`) — override
  the endpoint captions, which otherwise default to the lowest/highest stop value in the component's
  own locale-aware numeric formatting
- `legend: readonly LyraMapLegendEntry[] = []` (attribute: false) — immutable defensive snapshots
  of `LyraMapLegendEntry { readonly color: string; readonly label: string; readonly pattern:
LyraMapLegendPattern }`, where `LyraMapLegendPattern` is `'solid' | 'diagonal' | 'dots' |
'crosshatch'`. Pattern is required so color is never the sole category cue. At most 100 valid
  rows, 256 characters per label, and 8,192 aggregate label characters are retained; colors are
  bounded before validation. The overlay scrolls within the map allocation.
  A row may also carry its own `value`: the category key that row stands for — the same string a
  `point.colors`/`point.icons` entry matches against `point.field`/`point.iconField`. It is
  trimmed, bounded to 256 characters (sliced, never ellipsized, so a bounded key still matches) and
  **retained** in the canonical readback; a non-string, empty or whitespace-only key leaves no
  `value` property on the frozen row at all. It is what makes a row operable under
  `legendInteractive`, and it does not count toward the label budget.
  A row may also carry `icon`, deliberately the same record a `point.icons` entry uses — hand the
  legend the very icon object its point layer renders and the key shows the symbol drawn on the
  map instead of describing it in colour alone. The **icon record's own** `value` is a separate
  field from the row-level one above: it is accepted so a pass-through needs no reshaping, and it
  is still left out of the canonical readback. A row's key is never derived from its glyph's, which
  would silently make a row interactive that the author never marked;
  `path`, `viewBox`, `mode`, `strokeWidth`, `lineCap` and `lineJoin` keep their point-icon meaning
  and their point-icon defaults, and the same validation applies (path data only, at most 8,192
  characters, positive `viewBox` dimensions). An unusable record is dropped and that row keeps
  rendering its colour swatch, exactly as a row that supplies no `icon` does.
  A row may finally carry a `group`: the section it belongs to, for a key that describes two
  layers at once and otherwise could not say which rows belong to which. The rule is pinned
  rather than inferred: **consecutive** entries sharing an identical `group` render as one section
  — a visible heading plus a `role="group"` that heading names — an entry with **no** `group`
  keeps its **declared** position rather than being hoisted above or sunk below a section, and a
  `group` that reappears after an interruption opens a *second* section rather than reordering
  rows to merge them. Declaration order is the one thing the legend never rewrites, because the
  order is itself information about the map. `group` is caller-supplied **data**: it renders
  verbatim and is never resolved through the locale catalogue. It is trimmed and bounded to 256
  characters (ellipsized, since it is rendered prose rather than a key matched against
  `point.field`); a non-string, empty or whitespace-only value leaves no `group` property on the
  frozen row at all, so an empty string means "ungrouped" instead of an empty heading. Like the
  row-level `value`, it does not count toward the aggregate label budget — the rendered total is
  already finite and stated: at most one heading per rendered row, so at most 100 of them. A
  section is not a row: the 100-row cap and the `legend-limit` summary count rows, never sections.
- readonly `legendProjection: LyraMapLegendProjection` — frozen `{ inputCount, renderedCount,
omittedCount, truncatedLabelCount, truncated }` result for the latest assignment. A truncated
  projection renders a localized visible `1–N of M items` summary rather than silently claiming
  the bounded rows are complete.
- `legendInteractive: boolean = false` (attribute `legend-interactive`, reflected) — opt-in: turns
  every legend row that carries a `value` into a keyboard-operable visibility toggle, and leaves a
  row without one inert. Unset, the legend renders exactly the read-only key it rendered before —
  no `button`, no extra attribute, and no extra MapLibre paint key. Each toggle is an independently
  tabbable native `button`, so Enter and Space are the platform's own activation and there is no
  roving tabindex: a 100-row interactive legend contributes 100 tab stops, exactly as a 100-series
  `lr-chart` legend does. Each interactive row also grows to the shared `--lr-icon-button-size`
  hit-area floor (WCAG 2.5.8), which the panel's existing `max-block-size` and scrolling contain.
- `legendControlRole: 'button' | 'checkbox' = 'button'` (attribute `legend-control-role`,
  reflected) — how each `legendInteractive` row's toggle presents itself to assistive tech; inert
  while `legendInteractive` is unset, exactly like the toggle itself. `'button'` is byte-identical
  to every legend rendered before this property existed: `<button aria-pressed>`. `'checkbox'`
  renders the SAME `<button>` element with its implicit role overridden to `role="checkbox"` and
  `aria-checked` in place of `aria-pressed` — the swatch, the label, the click handler and the
  platform's own Enter/Space activation are unchanged, so `hiddenCategories`, the cancelable
  `lr-map-legend-toggle` veto, `group` sections and `legendCollapsible` all compose with either
  role. `aria-checked` tracks the same visibility flag `aria-pressed` does, inverted from
  `hiddenCategories`: a hidden category renders `aria-checked="false"`. Prefer `'checkbox'` when the
  legend reads as a checklist of independent show/hide toggles; prefer the `'button'` default when
  it reads as a set of filtering actions. An unsupported value normalizes back to `'button'`.
- `legendCollapsible: boolean = false` (attribute `legend-collapsible`, reflected) — opt-in: renders
  a `legend-disclosure` `button` inside the panel that collapses the key down to its header, so a
  large legend stops permanently covering part of the map. Unset, the panel renders exactly what it
  rendered before — no button, no `id` minted on the row list, and no `hidden` attribute anywhere.
  Collapsing hides the gradient bar, the rows, the `legend-limit` summary and the trailing `legend`
  slot; the `legend-start` slot and the disclosure itself stay visible, so a slotted header survives
  the collapse and the control that restores the key is never what the collapse hides.
- `legendOpen: boolean = true` (attribute `legend-open`, reflected) — whether a `legendCollapsible`
  panel is expanded. It defaults **open**, so adding only `legendCollapsible` never hides an existing
  key, and it does nothing at all while `legendCollapsible` is unset. Because it is a
  `true`-defaulting boolean it uses a custom attribute converter, so `legend-open="false"` parses —
  the bare presence-based boolean form cannot express `false` at all — and the reflection follows the
  same converter: open (the default) reflects as an **absent** attribute and collapsed reflects as
  `legend-open="false"`. It is controlled public state and survives a disconnect/reconnect. Assigning
  it programmatically reconciles the rendered panel and emits nothing.
- `hiddenCategories: readonly string[] = []` (attribute: false) — the complete controlled set of
  muted category keys, mirroring `lr-chart`'s `hiddenDatasets`. Clone-owned and frozen; non-string,
  empty, whitespace-only and duplicate entries are dropped (first occurrence wins, matching
  `point.colors`), and at most 100 keys are retained. Honoured on the **first** render and the
  first MapLibre paint, not only after a user toggle, so a host can restore a saved selection. An
  empty array deliberately means every category is visible. It is controlled public state and
  survives a disconnect/reconnect. A hidden key that matches no category is harmless. Assigning it
  programmatically emits nothing.
- `choropleth?: LyraMapChoroplethLayer` (attribute: false) — `LyraMapChoroplethLayer { sourceId:
string; geojson: GeoJSON.FeatureCollection; field: string; stops: [number, string][]; interpolation?:
'linear' | 'logarithmic' | 'step'; stepBaseColor?: string }` (interpolated
  fill-color expression from `field`'s value against `stops`; `stops` must contain at least one
  `[value, color]` pair — an empty array is ignored, leaving whatever fill layer already exists, if
  any, untouched, rather than being applied).
  `interpolation` (type `LyraMapChoroplethInterpolation`, default `'linear'`) chooses how the colour
  is interpolated between stops. `'logarithmic'` compresses the ramp, which is what a heavy-tailed
  quantity — price, population, income — needs: on a linear ramp every value below the maximum falls
  into the first colour band, so the map reads as one flat colour plus a couple of outliers. It
  emits maplibre's own `['interpolate', ['exponential', 0.25], …]`, exposing an existing capability
  rather than adding one (maplibre has no `['log']` interpolation type; a sub-1 exponential base is
  the documented way to weight a ramp toward the low end). **`stops` stay in the data's own units
  under either mode**, so the legend keeps reading in real values instead of log units — no
  pre-transforming to log10 and hand-relabelling the legend back.
  `'step'` (new in 11.0.0) emits maplibre's `['step', …]` instead of `['interpolate', …]`, giving
  **discrete bands rather than a continuous ramp**. Use it whenever the legend advertises a fixed
  set of ranges with one swatch each: a ramp would put colours on the map that appear nowhere in the
  legend, and would render two regions in the same advertised band as visibly different colours
  (`legendGradient` covers the opposite case, a gradient legend). `stepBaseColor` is the colour for
  values below the first threshold, which `['step', …]` requires; it defaults to the first stop's own
  colour, so a legend whose first band starts at the data minimum needs no extra configuration.
  Stop colors and `stepBaseColor` accept CSS custom-property references; Lyra resolves them from
  the live host cascade before passing the expression to MapLibre's WebGL renderer.
- `markers: LyraMapMarker[] = []` (attribute: false) — `LyraMapMarker { id?: string; lngLat:
[number, number]; color?: string; label?: string; unsafeHtml?: string }`; an explicit `id` is
  trimmed and must be nonempty, and the first successfully admitted marker for an explicit ID wins.
  A malformed earlier row does not reserve that ID. Markers are reconciled
  by that explicit ID (falling back
  to a `lng,lat` key, disambiguated by occurrence order for duplicate-coordinate id-less markers,
  when `id` is omitted) so an unchanged marker isn't torn down and recreated on every `markers`
  reassignment — its `lngLat` **and** its popup content (`unsafeHtml`/`label`, in that precedence)
  are both updated in place, and the popup is removed if a later update sets neither. `unsafeHtml` is
  rendered via `Popup.setHTML()` — **raw markup, inline event handlers included** — only pass trusted
  content, sanitize anything derived from user input first; prefer `label` (`Popup.setText()`,
  escaped) when the content is plain text. For marker/popup naming, visible text is extracted from
  trusted markup while `script`, `style`, `template`, `[hidden]`, and `aria-hidden="true"` subtrees
  are excluded; an explicitly supplied `label` remains the more predictable accessible name. A
  marker whose `color` changes for a persisting `id`
  can't be recolored in place (no `Marker.setColor()`) and is torn down/reconstructed instead — see
  gotchas. Entries with non-finite coordinates, latitude outside `[-90, 90]`, or a runtime
  non-string `label` are skipped without aborting valid siblings. `color` is used only when the
  browser accepts it as CSS `color`;
  declaration breaks and `url()` paint servers fall back to MapLibre's default marker color.
  Every retained marker is a named `role="button"` tab stop, including one without a popup. Click,
  Enter, and Space emit `lr-map-marker-activate`; Space suppresses its page-scroll default while
  preserving MapLibre's popup toggle. A popup-bearing marker additionally exposes
  `aria-haspopup="dialog"`, `aria-controls`, and explicit `aria-expanded`.
- `dataLayers: LyraMapGeoJsonDataLayer[] = []` (attribute: false) —
  `LyraMapGeoJsonDataLayer { sourceId: string; geojson: GeoJSON.Feature |
GeoJSON.FeatureCollection; tone?: 'accent' | 'success' | 'warning' |
'danger' | 'neutral'; color?: string; strokeColor?: string; line?: LyraMapLineOptions;
point?: LyraMapPointOptions; kind?: LyraMapDataLayerKind;
heatmap?: LyraMapHeatmapOptions; cluster?: LyraMapClusterOptions }`. `sourceId` is trimmed and must be nonempty; the first layer for a
  `sourceId` that is successfully admitted wins; blank, malformed, and later duplicate records are
  ignored without reserving an identity for a valid later sibling. Each retained entry adds one
  GeoJSON source plus three geometry-filtered layers
  (fill, line, and circle, so a mixed `FeatureCollection` renders correctly), colored from the
  matching `--lr-color-*` token (`tone` defaults to `'accent'` → `--lr-color-brand`).
  `color` and `strokeColor` (both new in 11.0.0) override that per surface — `color` paints the
  polygon fill, `strokeColor` the line and circle layers, falling back to `color` and then to `tone`.
  They are separable because a fill and its outline want opposite things on a
  choropleth-plus-overlay map, and the difference is measurable rather than aesthetic: the fill
  competes for area with the choropleth beside it and has to sit quiet, while the 1px outline
  competes with nothing and is the only thing keeping a no-data region's shape readable once the
  fill is that faint. Deriving one from the other measured 1.41:1 against a light basemap — under
  WCAG 1.4.11's 3:1 floor for graphical objects. A `var(--lr-…)` reference is resolved against the
  host before it reaches MapLibre, which paints to a WebGL canvas and never sees the CSS cascade.
  The component
  assigns collision-free private MapLibre ids for those resources: `sourceId` is the stable
  declarative reconciliation key, **not** an id to retrieve from `map`. This prevents a data layer
  from overwriting or removing a same-named source supplied by `mapStyle`. Independent of
  `choropleth` — no `field`/`stops` color-interpolation, just the geometry rendered in a flat tone;
  use `choropleth` instead when you need a data-driven color ramp. An entry whose `sourceId`
  persists across a `dataLayers` reassignment gets its GeoJSON updated in place (`updateData()`
  when stable feature IDs make a safe diff possible, otherwise `setData()`), one that's dropped has
  its private source/layers removed, and a genuinely new `sourceId` gets new resources — nothing
  leaks on removal, style change, or disconnect.

  The component snapshots the configuration it reads. It passes `choropleth.geojson` and
  `dataLayers[].geojson` through to MapLibre; assign a new `choropleth`, `dataLayers`, or `markers`
  value after changing configuration, because mutating an assigned value is not observed.

  `cluster` and `kind` (both new in 12.0.0) opt one entry out of that three-layer geometry split.
  **Both are strictly additive: an entry that sets neither renders exactly what it rendered before,
  down to the layer ids and the point layer's filter.**

  `cluster?: LyraMapClusterOptions { radius?: number; maxZoom?: number; radiusSteps?: [number,
number][]; colorSteps?: [number, string][]; countFont?: string[] }` turns the entry's source into a
  natively clustered one — `cluster`/`clusterRadius` (default 50)/`clusterMaxZoom` (default 14) on
  the source, plus a `${sourceId}-cluster` circle filtered on `has('point_count')`, a
  `${sourceId}-cluster-count` label, and a `${sourceId}-circle` layer for the points that stayed
  unclustered. `cluster: {}` opts in at every default. This is what a thousands-of-points map needs
  and what `markers` cannot be: `markers` mints one real, individually focusable DOM element per
  entry, which is right for tens of pins and both unreadable and expensive for thousands.
  `radiusSteps` and `colorSteps` are `['step', …]` breaks keyed on `point_count`, in the same
  ascending `[value, output]` vocabulary as `choropleth.stops` — including the same base rule, where
  the first entry's own output covers everything below the first threshold, and the same colour
  resolution, where a `var(--lr-…)` reference in a `colorSteps` entry is resolved against the host
  before it reaches MapLibre (which paints to a WebGL canvas and never sees the CSS cascade), so a
  retheme moves the cluster breaks with everything else. No fill or line layer is created for a
  clustered entry, because MapLibre's clustering keeps point features only. The count
  label needs glyphs: a style that declares none gets the graduated circles without the numbers
  (adding a text layer against a glyph-less style paints nothing and only emits peer errors), and
  `countFont` names the font stack when your style's glyph source lacks MapLibre's spec default.
  Cluster options are baked into the source at creation time by MapLibre and have no setter, so
  changing them (or `kind`) rebuilds that one entry's source and layers; every other update still
  reconciles in place.

  `kind?: 'auto' | 'heatmap'` (`LyraMapDataLayerKind`, default `'auto'` — today's geometry split)
  renders the source as MapLibre's own first-class `heatmap` layer instead, which the geometry split
  cannot express at all: thousands of overlapping circles read as one opaque blob rather than as
  where the data is concentrated. `heatmap?: LyraMapHeatmapOptions { weightField?: string;
weightRange?: [number, number]; stops?: [number, string][]; radius?: LyraMapHeatmapZoomValue;
intensity?: LyraMapHeatmapZoomValue; opacity?: number }`, where `LyraMapHeatmapZoomValue` is a
  scalar number or bounded `[zoom, value][]` stops,
  configures it. `weightField` weights each point by a feature property, and `weightRange` maps that
  property's own units onto the 0–1 weight MapLibre expects — without it the raw value is passed
  through, which saturates the surface for any quantity above ~1; with neither, every point weighs 1.
  `stops` are `[density, color]` pairs with density in `[0, 1]`, **the same `[value, color]`
  vocabulary `choropleth.stops` and `legendGradient` already share**, so a `legendGradient` bar can
  describe the ramp without a second copy of it, and `var(--lr-…)` stops resolve against the host the
  same way `color`/`strokeColor` do. A ramp that doesn't start at density 0 gets a fully transparent
  stop prepended, because a coloured zero tints the entire map — so **a single stop is already a
  complete ramp**, as long as it sits above density 0: `stops: [[1, '#ff0000']]` is exactly
  transparent → red. The one authored ramp that can't be honoured is a lone stop AT density 0, which
  describes a flat colour rather than a gradient; that one — like an unset or wholly unusable
  `stops` — falls back to the built-in ramp, which runs transparent → `--lr-color-brand` →
  `--lr-color-success` → `--lr-color-warning` → `--lr-color-danger`, so a retheme moves the density
  surface with everything else. Scalar `radius` (default 30) and `intensity` (default 1) preserve
  their established behavior. Two or more usable `[zoom, value]` stops emit linear zoom
  interpolation; stops are sorted, duplicate zooms removed, zoom clamped into `[0, 24]`, radius
  into `[1, 200]`, and intensity into `[0, 100]`. One usable stop becomes a scalar and an unusable
  array falls back to the existing default. `opacity` is clamped into `[0, 1]`; omission leaves the
  peer's default untouched on construction, and dropping a previously-authored value restores 1.
  `cluster` is ignored on a heatmap entry: a heatmap already aggregates density, and clustering its
  input would feed it one point per cluster instead of the real distribution.
  `line?: LyraMapLineOptions { field?: string; stops?: readonly (readonly [number, string])[];
  width?: number; opacity?: number }` configures line/outline paint for an ordinary `dataLayers`
  entry. `field` names a numeric feature property; two usable `[value, color]` stops produce a
  continuous linear ramp. Missing, null, and non-numeric feature values use `strokeColor`, then
  `color`, then `tone`. Stops inspect the first 64 entries, discard non-finite values and invalid
  CSS colors, sort ascending, and retain the first duplicate threshold. Fewer than two stops or
  an absent field preserves flat color. Values beyond the endpoints clamp to their endpoint color.
  CSS variables resolve on the host during reconciliation and retheming. `width` defaults to 2 CSS
  pixels and clamps to `[0, 200]`; `opacity` defaults to 1 and clamps to `[0, 1]`. Non-finite values
  restore those defaults, as does dropping a previously-authored option. Point colors and polygon
  fills are unaffected; cluster and heatmap entries ignore `line`.

  `point?: LyraMapPointOptions` styles individual points on ordinary and clustered auto entries.
  It is ignored for heatmaps. `field` names a **string** feature property; `colors` maps exact
  `[category, CSS color]` pairs. Missing, unknown and non-string categories use the existing
  `strokeColor`/`color`/`tone` fallback. The first 32 pairs are inspected and valid duplicates are
  first-wins. CSS variables resolve on the host and follow ancestor theme changes. `radius`
  defaults to 5 CSS pixels and `strokeWidth` to 0; both clamp to `[0, 200]`. `strokeColor` overrides
  the outline only, with the layer's flat color as fallback. Dropping options restores defaults.

  `radius` also accepts `LyraMapPointRadiusOptions { field, stops, interpolation?, fallback? }`
  for **numeric** feature-driven sizes. `field` is independent of the category field. The first 32
  pairs are inspected and finite `[value, radius]` pairs are sorted ascending; duplicate thresholds are first-wins and
  radii clamp to `[0, 200]`. `interpolation` defaults to `'step'`: below the first threshold use
  its radius, and each threshold is inclusive. `'linear'` interpolates between adjacent stops and
  clamps outside the domain. One usable stop is a constant for numeric features. Missing, null,
  non-numeric and non-finite feature values use `fallback` (default 5, clamped to `[0, 200]`), as
  do an empty field, unusable stops or a linear domain that cannot retain distinct finite intervals.
  Invalid interpolation values use step. These options style individual/unclustered points;
  cluster-count radii remain independent. Switching back to a number or removing the radius
  scale restores the fixed radius without recreating the source.

  `point.icons` maps exact category values to `LyraMapPointIcon { value: string; path: string;
  viewBox?: readonly [number, number, number, number]; mode?: LyraMapPointIconMode;
  strokeWidth?: number; lineCap?: LyraMapPointIconLineCap; lineJoin?: LyraMapPointIconLineJoin }`.
  `iconField` defaults to `field`. Each icon is **SVG path data**, not SVG markup or a URL. Copy an icon's path data,
  combine filled subpaths in that string, and supply its `[minX, minY, width, height]` viewBox
  (default `[0, 0, 24, 24]`). `mode` defaults to `'fill'`; `'stroke'` draws open outline paths,
  and `'fill-stroke'` paints both. `strokeWidth` uses **viewBox units** (default 2, clamped to
  `[0, 200]`; zero omits the stroke), so it scales with the icon. `lineCap` accepts `'butt'`,
  `'round'`, or `'square'`; `lineJoin` accepts `'miter'`, `'round'`, or `'bevel'`. Both default
  to round; miter joins retain a limit of 10. Invalid modes/caps/joins restore their defaults,
  and a non-finite stroke width restores 2. Keep padding inside the viewBox for strokes at its
  edges, which are clipped to the fixed atlas square. These are icon-path options;
  `point.strokeWidth` and `point.strokeColor` continue to style the surrounding circle only.
  The first 32 entries are inspected, valid duplicates are first-wins, path data is capped at
  8192 characters, and viewBox coordinates must be finite within ±10000 with dimensions at least
  0.001. Invalid paths are ignored; markup, external references and event handlers cannot execute.
  Rasterization is synchronous and local, with no fetch or HTML/SVG document insertion.
  `iconColor` supplies both fill and stroke ink, accepts CSS variables and defaults to the tone's contrasting foreground; `iconSize`
  is the displayed bounding square in CSS pixels (default 16, clamped to `[1, 200]`). The fixed
  64px raster preserves the viewBox aspect ratio. Unknown categories, invalid icons and partial
  peers lacking image-atlas methods retain their colored circles. No sprite or glyph URL is needed.

  All categories use the **same GeoJSON source** and cluster across categories. Cluster circles
  keep the existing count-based styling; only unclustered points get category colors/icons.
  An optional symbol layer and at most 32 images are allocated per configured source, with no
  per-feature DOM markers. Data changes reuse the source, retheming updates paint/icon pixels,
  and style reloads restore the owned resources. Removing the entry or icons releases its images.
  `lr-map-click` on either a point's circle or icon returns `origin: 'data-layer'`, the public
  `sourceId`, and the rendered feature. For clustered GeoJSON, use numeric feature IDs and keep
  string business IDs in feature properties, as MapLibre's cluster tiling uses numeric IDs. Canvas export includes both; supply an accessible textual
  legend/list for category interpretation and individual keyboard actions.

  ```js
  import '@aceshooting/lyra-ui/components/lr-map.js';
  map.dataLayers = [{
    sourceId: 'places', geojson: locations, cluster: {},
    point: {
      field: 'category',
      radius: { field: 'visits', stops: [[0, 10], [10, 12], [50, 14], [100, 16]], fallback: 10 },
      strokeWidth: 1,
      colors: [['home', 'var(--lr-color-brand)'], ['work', 'var(--lr-color-success)']],
      icons: [
        { value: 'home', path: 'M2 12L12 2L22 12V22H2Z' },
        { value: 'work', path: 'M8 6V3H16V6M3 6H21V21H3ZM3 11H21',
          mode: 'stroke', strokeWidth: 1.75, lineCap: 'round', lineJoin: 'round' },
      ],
      iconSize: 14,
    },
  }];
  ```

  Share the same stops with `legendGradient` and set its endpoint labels for units. A gradient
  matching a line ramp remains linear even alongside a logarithmic choropleth. Changing metric,
  filtered GeoJSON, width or opacity reconciles existing resources; style reloads restore the layer.
  Lines remain in MapLibre's canvas and can be captured with the map's normal render-event PNG
  export flow.

  ```js
  mapElement.dataLayers = [{
    sourceId: 'routes', geojson: routes,
    line: { field: 'kmh', stops: speedStops, width: 4, opacity: 0.9 }
  }];
  mapElement.legendGradient = speedStops;
  mapElement.legendGradientLoLabel = '0 km/h';
  mapElement.legendGradientHiLabel = '100 km/h';
  ```
- `maxBounds: LyraMapBounds | null = null` (attribute: false) — box the map may not pan outside,
  `[[west, south], [east, north]]`. Prefer it over calling `map.setMaxBounds()` through the `.map`
  escape hatch: constraining the camera can wedge maplibre-gl at a sub-1 fractional zoom in a wide
  container, leaving `getZoom()` returning `null` permanently, every frame throwing from inside the
  peer's own matrix math, and the canvas never painting again — a blank map, with nothing thrown at
  the call site to attribute it to. This property applies the same call, then reads the camera back
  and reverts (restoring zoom and centre) if it did not survive, so the worst case is an
  unconstrained map plus a dev-mode warning. The defensive camera snapshots are inside the same
  failure boundary, so a peer whose damaged transform already throws from `getZoom()` or
  `getCenter()` is also reduced to an unconstrained map instead of leaking through Lit's update.
  A malformed box is rejected rather than clamped

**Choropleth and `dataLayers` updates are diffed before they reach the peer.** `setData()`
unconditionally re-tiles and repaints an entire source, which is invisible on a static map and
expensive on an animated one. When every feature has a unique `string`/`number` `id` and retained
features keep semantically unchanged geometry/bbox values, the component emits MapLibre's
incremental `updateData()` for property changes, additions, removals, and order changes. The exact
next order is preserved: an unchanged prefix stays in place and only the invalidated suffix is
removed and re-added. Lyra snapshots control and projection data while retaining opaque GeoJSON
identity at the MapLibre boundary; a bounded, accessor-free comparison verifies the JSON geometry
graph instead. A missing/duplicate ID, changed geometry, exceeded bound, or uncertain
comparison falls back to `setData()` with no change in rendered behaviour. Peers without
`updateData()` always take the old path.

**Feature properties are tiled, and therefore bounded in numeric magnitude.** MapLibre GL tiles
every GeoJSON source through a worker into a protobuf vector tile, so a property carrying a huge
integer throws *inside that worker* — "Given varint doesn't fit into 10 bytes". That throw is not
catchable by your app and not a rejected promise; it reaches you only as an opaque message on
`lr-map`'s own error handler, while the rest of the layer still paints, so one bad feature in a
large collection is invisible until someone walks the data by hand. Both `choropleth.geojson` and
`dataLayers[].geojson` are now pre-scanned (first 10,000 features) and any numeric property beyond
`Number.MAX_SAFE_INTEGER` draws a dev-mode warning naming the feature and the property. Carry a
reduced figure in the feature — a log, a bucket, an index — and keep the exact value in your own
payload beside the map.

- `label: string = ''` — purpose-specific accessible name for MapLibre's actual focusable canvas.
  A nonempty host `aria-label` remains on the host and is not duplicated onto the canvas; the canvas
  uses `label` or the localized map name. An explicitly empty host `aria-label` is preserved as an
  empty canvas name. The non-semantic `[part="base"]` wrapper is not named instead.

**Authoring types:** `LyraMapLegendEntry`, `LyraMapLegendPattern`, `LyraMapLegendProjection`, `LyraMapChoroplethLayer`,
`LyraMapGeoJsonDataLayer`, `LyraMapDataLayerKind`, `LyraMapClusterOptions`, `LyraMapHeatmapOptions`,
`LyraMapHeatmapZoomValue`, `LyraMapLineOptions`, `LyraMapPointOptions`, `LyraMapPointRadiusOptions`,
`LyraMapPointRadiusInterpolation`, `LyraMapPointIcon`, `LyraMapPointIconMode`,
`LyraMapPointIconLineCap`, `LyraMapPointIconLineJoin`, `LyraMapMarker`, `LyraMapMarkerActivationDetail`,
`LyraMapMarkerActivationSource`, `LyraMapLegendToggleDetail`, `LyraMapLegendPanelToggleDetail`,
`LyraMapStyleSpecification`, and `LyraMapInstance`.
The former `LegendEntry`, `ChoroplethLayer`, `GeoJsonDataLayer`, and `MapMarker` names are removed
in v9 rather than retained as aliases.

**Getters:** `map: LyraMapInstance | undefined` → the underlying runtime `maplibregl.Map`, exposed
through the peer-neutral `getCanvas()`, `getCenter()`, `getZoom()`, `setCenter()`, `setZoom()`, and
`resize()` subset so merely importing Lyra does not require `maplibre-gl` declarations. A consumer
that installed the optional peer and needs its full imperative API can explicitly narrow the runtime
value to `maplibregl.Map`.

**Methods:** `LyraMap.preload(): Promise<boolean>` is a static optional-peer warm-up that starts the
shared `maplibre-gl` import without constructing a map or allocating a WebGL context. It resolves to
`false` when the peer is unavailable, allowing an application to choose a fallback before connecting
an element.

**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
proposed hidden set in the order it would be committed, with the array detached and frozen so a
listener cannot mutate the component's state through it). `preventDefault()` is a genuine veto, not
a notification: `hiddenCategories` is not written, the row's `aria-pressed` does not change, the
MapLibre paint is untouched, and nothing is announced — which is exactly what a host needs to own
the set and assign its own value instead. There is deliberately no second, confirmation event: the
committed state is `hiddenCategories`, which the host already observes, so a paired before/after
vocabulary would be permanent public surface nobody asked for. The event is a DOM-interaction
proposal only, so a programmatic `hiddenCategories` assignment reconciles without emitting it.
Also `lr-map-legend-panel-toggle` (**cancelable**; frozen `LyraMapLegendPanelToggleDetail { open }` —
the proposed `legendOpen` value), fired once when the `legendCollapsible` disclosure is activated by
pointer or by Enter/Space. It is the *panel's* disclosure, not a *category's* visibility, so it
deliberately does not reuse `lr-map-legend-toggle`. `preventDefault()` is the same genuine veto:
`legendOpen` is not written, the rendered rows and the disclosure's `aria-expanded` do not change,
so a host can own the open state and assign its own value from `event.detail.open`. A programmatic
`legendOpen` assignment reconciles without emitting it, so a controlled host cannot loop.
Also `lr-map-marker-activate` (non-cancelable; frozen `LyraMapMarkerActivationDetail { id, lngLat,
marker, source }`; `id` is the trimmed explicit identity or `undefined`, `marker` is the accepted
declarative snapshot, and `source` is `'pointer' | 'keyboard'`), and `lr-map-click`
(frozen `detail: { readonly lngLat: readonly [lng, lat], readonly feature?, readonly origin?,
readonly sourceId? }`; the tuple and any hit GeoJSON feature are detached and recursively frozen).
`feature` resolves against the choropleth fill layer **and** every applied `dataLayers`
fill/line/circle/cluster layer, topmost first — so a shape painted through `dataLayers` is
identifiable instead of being indistinguishable from empty space. `origin` is `'choropleth'`,
`'data-layer'` or `'cluster'`, and `sourceId` carries the authored `dataLayers[].sourceId` for a
data-layer or cluster hit; both are `undefined` whenever `feature` is. A cluster hit is reported
separately because it is a synthetic aggregate rather than one of your features: its useful payload
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

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
markup as described above.

**Slots:** `legend` — custom legend content, rendered inside the legend panel's own layout so it
stays positioned with the map instead of floating beside it. Supplying it opens the panel even
when `legend` and `legendGradient` are both empty. `legend-start` — the same extension point at the
**top** of the panel: it renders ahead of the gradient bar and every projected row, where `legend`
renders after them, so a host-authored panel header is no longer forced to be a footer. Content in
it alone opens the panel too, and neither slot is ever made interactive by `legendInteractive`,
which only reaches rows projected from `legend`.

**CSS parts:** `base`, `container`, `legend`, `legend-disclosure`, `legend-disclosure-icon`,
`legend-group`, `legend-group-heading`, `legend-swatch`, `legend-toggle`,
`legend-toggle-hidden`, `legend-gradient`, `legend-lo`,
`legend-hi`, `legend-limit`, `marker`, `popup`,
`popup-content`, `popup-close-button`, `attribution`, `attribution-toggle`, `navigation`,
`zoom-in`, `zoom-out`, `compass`, `scale`, `error`.
The compact attribution summary has a decorative, current-color information glyph and retains
MapLibre's accessible name, keyboard/touch disclosure behavior and attribution links. To make
only this control compact, scope the shared target-size token to its public wrapper:

```css
lr-map::part(attribution) { --lr-icon-button-size: var(--lr-size-24px); }
```

Keep that target at least 24px in both axes. This leaves navigation controls at their existing size.

`legend` is a localized `role="group"` containing a real list associated to the map canvas with
`aria-describedby`; each entry is a `listitem`, decorative swatches are inert/accessibility-hidden,
and the overlay is bounded to the map allocation with scrolling and long-label wrapping.
A swatch rendering an entry's `icon` carries `data-icon="true"`, paints the glyph in that entry's
own colour through `currentColor`, and drops the colour block, its border and the `pattern`
overlay — all three would sit on top of the shape they identify, and the shape is itself the
non-colour cue the pattern supplies for a colour-only row. The glyph stays decorative: the row's
visible label carries its meaning. That association is advertised only while it is true — while
the optional `maplibre-gl` peer is still loading, and after any failure, there is no map
container in the tree, so `legend` withholds `aria-controls` rather than leaving a dangling
idref.
Under `legendInteractive`, a row carrying a `value` wraps its swatch and label in a
`legend-toggle` `button` with `aria-pressed` rendered as the literal `"true"`/`"false"` — never
omitted, because a missing attribute reports "not a toggle button" rather than "unpressed". Setting
`legendControlRole="checkbox"` renders the SAME `button` with `role="checkbox"` and `aria-checked`
(also always the literal `"true"`/`"false"`) in place of `aria-pressed`, and nothing else about the
row changes. The button's accessible name is its own visible label (caller-supplied data, so
deliberately not localized), scoped by the legend's own localized group name; no `aria-label`
restates the state, which would make assistive tech announce it twice. A hidden row's button
additionally carries the
`legend-toggle-hidden` token — state lives in the part name, so `::part(legend-toggle-hidden)` is a
reachable hook — and dims only its `aria-hidden` swatch while re-colouring the label through the
quiet text token, so the label keeps AA contrast rather than fading with the whole button. In
forced colors the hidden row falls back to `line-through`, which survives a system-color collapse.
Each activation is announced through the shared light-DOM polite live region, using the same
`legendTypeShown`/`legendTypeHidden` strings `lr-graph-legend` announces with.
Under `legendCollapsible`, `legend-disclosure` is a native `button` whose **visible localized text
is its accessible name** and whose `aria-expanded` renders the literal `"true"`/`"false"` — never
omitted — with `aria-controls` naming the row list in the same shadow root (idrefs do not cross
shadow boundaries, so this is deliberately not an idref into the light DOM). It carries the shared
`--lr-icon-button-size` hit-area floor, and `legend-disclosure-icon` is the decorative chevron it
rotates: the shared icon set ships one right-pointing glyph and asks callers to rotate the wrapping
part, so collapsed points along the reading direction and expanded points down in both directions.
The rotation runs on `--lr-transition-fast`, which the token layer already flattens under
`prefers-reduced-motion`. A collapsed panel hides its gradient, rows, `legend-limit` summary and
trailing `legend` slot with the plain `hidden` attribute, so they leave layout, the accessibility
tree and the tab order together.
When at least one entry carries a `group`, each consecutive run renders inside `legend-group`
(`role="group"`, named by its own `legend-group-heading` through `aria-labelledby`) and **each run
gets its own `role="list"`**, because a `list` may only own `listitem`s — a `group` sitting directly
inside the outer list is an `aria-required-children`/`aria-required-parent` violation. The outer
container therefore drops its own `role` in that case; a legend with no groups keeps the single
`role="list"` it has always had. Row `aria-posinset`/`aria-setsize` stay whole-key values inside a
section: `aria-setsize` already reports the *input* count so a bounded key stays honest, and a
dropped row carries no attributable group, so a section adds a labelled sub-region without
renumbering the key.
`legend-limit` is the localized bounded-projection summary. The five peer-chrome parts project
stable Lyra names onto MapLibre-generated DOM without erasing peer-supplied part tokens;
`marker` retains a 24px minimum target in both axes even when a peer/custom marker has no intrinsic
content size. `popup-close-button` is the generated close control on an open marker popup. `error` is ordinary localized visible
text rendered in place of `container` for four distinct states: explicit style required, optional
peer unavailable, owner-realm WebGL2 unavailable, or initialization failed. A post-mount failure is
appended to the document's pre-mounted `[data-lr-live-region="assertive"]` sink rather than making
shadow chrome live; raw caught errors are never exposed.

**Standard peer controls:** after `lr-map-load`, narrow `.map` to the installed MapLibre peer
and use `addControl(new NavigationControl(), 'bottom-right')` and
`addControl(new ScaleControl({ unit: 'metric' }), 'bottom-left')`. No document-level peer CSS or
shadow-root modification is needed: navigation buttons, compass glyph, scale bar and control
corners are styled with Lyra tokens. The corners follow inline start/end under RTL. The legend
reserves vertical room for these controls and attribution, including after resize or removal.
Attribution also reserves legend space when it is the only control. Opposing occupied corners
share the available width, so expanded attribution wraps without covering a scale or navigation
control on the other side; controls stay aligned to their logical edge in both text directions.
Navigation exposes `navigation`, `zoom-in`, `zoom-out`, and `compass` parts; the scale exposes `scale`.
Button names update through `zoomIn`, `zoomOut`, and `mapResetNorth` locale strings. MapLibre retains
keyboard activation, compass rotation, zoom limits, scale units and viewport updates. No controls
are created until the application explicitly adds them. This is a supported imperative peer-control
integration; there is no declarative controls property.

**Themeable custom properties:**

- `--lr-map-height` (default `var(--lr-size-24rem)`) — host block size, shared with the optional
  pre-upgrade reservation stylesheet. An explicit outer `block-size` still wins.
- `--lr-map-choropleth-fill-opacity` (default `0.75`) — fill opacity for the declarative
  `choropleth` layer and polygon fills in every `dataLayers` entry. It intentionally inherits from
  an ancestor, so one scoped declaration rethemes every nested map without setting each host.
- `--lr-map-hidden-category-opacity` (default `0.15`) — opacity a category listed in
  `hiddenCategories` is muted to in the rendered MapLibre paint: `circle-opacity` and
  `circle-stroke-opacity` on the points layer and `icon-opacity` on the point-icon symbol layer.
  Like the fill-opacity token it is read from the resolved cascade on every paint, because MapLibre
  draws to a WebGL canvas the CSS cascade never reaches, and it inherits from an ancestor. A
  `kind: 'heatmap'` entry is out of scope: a density surface has no per-category field to mute.
- `--lr-map-legend-hidden-swatch-opacity` (default `0.5`) — opacity of a hidden interactive legend
  row's decorative swatch. Only the `aria-hidden` swatch dims; the label re-colours through
  `--lr-color-text-quiet` instead, so it never drops below 4.5:1.
- `--lr-map-popup-close-button-hover-bg` (default `var(--lr-color-brand-quiet)`) and
  `--lr-map-popup-close-button-hover-color` (default `var(--lr-color-brand)`) — hover background
  and foreground of `popup-close-button`.
- `--lr-map-popup-close-button-active-bg` (default `color-mix(in oklab,
var(--lr-color-brand-quiet), var(--lr-color-mix-partner) var(--lr-color-mix-active))`) and
  `--lr-map-popup-close-button-active-color` (default `var(--lr-color-brand)`) — pressed
  background and foreground of `popup-close-button`.
- Shared tokens — `--lr-space-xs/-s`, `--lr-color-surface`, `--lr-color-border`, `--lr-shadow`,
  `--lr-radius`.

**Optional peer deps:** `maplibre-gl` `>=5 <7` (lazy-loaded). `<lr-map>` styles MapLibre's
generated canvas, marker, popup, and control DOM inside its shadow root; a page-level MapLibre
stylesheet is neither required nor able to reach those nodes. MapLibre v5's standard build includes
its worker. MapLibre v6 is ESM-only, requires WebGL2, and additionally needs its module-worker URL
configured for the bundler once — the component cannot choose a bundler-specific worker URL. For
Vite with v6:

```html
<lr-map center="[2.35, 48.85]" zoom="10"></lr-map>
<script type="module">
  import { setWorkerUrl } from "maplibre-gl";
  import workerUrl from "maplibre-gl/dist/maplibre-gl-worker.mjs?worker&url";
  setWorkerUrl(workerUrl);

  const m = document.querySelector("lr-map");
  m.mapStyle = { version: 8, sources: {}, layers: [] }; // explicit, network-silent baseline
  m.choropleth = {
    sourceId: "regions",
    geojson: myGeoJson,
    field: "value",
    stops: [
      [0, "#cde2fb"],
      [100, "#0969da"],
    ],
  };
  m.legend = [
    { color: "#cde2fb", label: "Low", pattern: "solid" },
    { color: "#0969da", label: "High", pattern: "diagonal" },
  ];
  m.markers = [{ lngLat: [2.29, 48.86], label: "Eiffel Tower" }];
  m.renderWorldCopies = false;
  m.addEventListener("lr-map-marker-activate", (e) =>
    console.log(e.detail.id, e.detail.lngLat)
  );
  m.addEventListener("lr-map-click", (e) =>
    console.log(e.detail.feature?.properties)
  );
</script>
```

Webpack, esbuild, Rollup, and direct-browser ESM use different worker URL forms; use MapLibre's ESM
installation guide for the matching setup:
https://maplibre.org/maplibre-gl-js/docs/#esm.

**Known gotchas:**

- Construction is transactional. A constructor/setup/get-canvas failure removes any partially
  created peer instance, renders only the localized initialization failure, and can retry after a
  new style or reconnect without an unhandled promise rejection. Capability probes and error
  constructors come from the current owner document, including after same-origin adoption.
- Every marker handles Enter and Space as button activation. Space suppresses the page-scroll
  default whether or not a popup exists; when one does, MapLibre still receives its own popup
  toggle and the component emits exactly one `lr-map-marker-activate` notification.
- clearing or swapping the choropleth no longer leaks the old layer: setting `choropleth =
undefined`, or changing `choropleth.sourceId` to a different value, now calls `removeLayer`/
  `removeSource` on whatever was previously applied before adding the new one (or nothing, if
  cleared).
- `mapStyle` changes after construction now call `setStyle()` (in addition to `center`/`zoom`
  already calling `setCenter`/`setZoom`) — the choropleth and `dataLayers` are both automatically
  re-applied once the new style's own `'style.load'` fires, since a style change wipes every
  layer/source maplibre-gl knows about.
- Point markers now have a declarative API (`markers`, above) with popup support — narrowing the
  runtime `.map` value and manually constructing `new maplibregl.Marker()` are no longer the only
  way to place pins.
- A marker uses `label` as its accessible name, then visible text extracted from trusted
  `unsafeHtml`, and only then the localized map label. Popup ownership is exposed through
  `aria-controls`/`aria-expanded`; an open popup is a named
  `role="dialog"` and its localized close button exposes `part="popup-close-button"`. The map
  canvas, markers, popups, and MapLibre's own control strings all follow the component's effective
  locale.
- Ancestor theme-attribute and custom-property changes repaint the already-applied choropleth and
  data-layer colors/opacities in place. This does not recreate MapLibre sources/layers, replace the
  style, or reset the current viewport.
- a marker whose `color` changes for a persisting `id` is torn down and reconstructed (maplibre-gl's
  `Marker` has no `setColor()`) rather than mutated in place — this also closes any popup the user
  currently has open on that marker (a fresh, closed `Popup` is built for the new instance); an
  accepted side effect of the reconstruction fallback, not a bug.
- No click-select visual highlight on choropleth features (no `setFeatureState` call) — clicking
  only fires the event, no built-in visual feedback. Popups are still only reachable declaratively
  through `markers`' `unsafeHtml`/`label` — a choropleth-feature click still has no built-in popup,
  only the raw `lr-map-click` event.
- `LyraMapLegendEntry.color` is validated against a strict CSS-color-syntax allowlist before being applied
  to the legend swatch's `background-color`, rejecting anything that isn't recognizable color syntax
  (notably `url(...)`, which `background` also accepts and would otherwise fetch as soon as the
  swatch renders). The required `pattern` remains distinct in forced colors through solid, dashed,
  dotted, and double border/shape encodings.
- while the `maplibre-gl` peer is resolving, the host/base expose `aria-busy="true"` and show a
  decorative `<lr-skeleton shape="rect" announce="false">` in place of the map container.
  Ordinary sr-only text preserves the localized `loading` label without creating a shadow live
  region.
- construction of the real `maplibregl.Map` (and its WebGL context) is additionally gated on this
  element being observed intersecting the viewport (`IntersectionObserver`), independent of whether
  the `maplibre-gl` peer has already loaded — an off-screen `<lr-map>` swaps its skeleton for the
  empty `[part="container"]` div as soon as the peer resolves, but `map` stays `undefined` and
  `lr-map-load` never fires until the element is actually scrolled into view. Deliberate: caps
  concurrent WebGL contexts when many `<lr-map>`s sit in one dashboard/grid. Skipped entirely
  (constructs immediately once the peer loads) when `IntersectionObserver` itself is unavailable.
- Once constructed, the owner realm's `ResizeObserver` watches the rendered map container and calls
  the current peer's `resize()` on allocation changes. It is replaced on reconnect/adoption and
  disconnected before peer teardown, so a stale delivery cannot resize a removed map. Browsers
  without `ResizeObserver` retain MapLibre's own window-resize behavior.

---

## `lr-drop-zone`

A drag-and-drop region wrapper with no file input of its own. Wrap it around an arbitrary region —
a chat composer, a whole conversation viewport, a panel far larger than any single control — to
make that entire region a file-drop target: it owns the drag-session state, renders a themeable
drag-over overlay, applies `accept`/size/count limits, and emits the same `lr-files` event shape
`lr-file-input` does. It never renders a native file picker, a selected-file list, or any focusable
control of its own; wrap `lr-file-input` itself (or any other focusable content) inside it when the
region also needs a click-to-browse affordance. The drag-session mechanics are the exact ones
`lr-file-input` uses, shared through `internal/drop-session-controller.ts` rather than
reimplemented.

**Properties:**

- `disabled: boolean = false` (reflected) — disables drag/drop handling entirely; the wrapped
  content keeps its own interactivity
- `multiple: boolean = true` (reflected) — accepts more than one file per drop and enables
  recursive folder-drop traversal, same contract as `lr-file-input`'s `multiple`. Defaults to `true`
  (unlike `lr-file-input`'s `false`): a region wrapper's typical use expects more than one file, and
  there is no native single-file picker here to keep in sync.
- `accept: string = ''` — identical native-`accept`-style parsing to `lr-file-input`'s `accept`, via
  the same shared `matchesAccept()`
- `maxFileSize: number = 0` (attribute `max-file-size` — bytes; `0` disables the check), `maxFiles:
  number = 0` (attribute `max-files`), `maxTotalSize: number = 0` (attribute `max-total-size`) —
  identical contract and invalid-override fail-safe fallback to `lr-file-input`'s own three limits.
  Since this component retains nothing of its own between drops, `maxFiles`/`maxTotalSize` would
  otherwise always cover only the current drop — `heldFileCount`/`heldTotalSize` below are what let
  a cumulative cap span separate drops.
- `heldFileCount: number = 0` (attribute `held-file-count`) and `heldTotalSize: number = 0`
  (attribute `held-total-size`) — externally held baseline added to the running count/byte-total
  `maxFiles`/`maxTotalSize` evaluate against, identical contract to `lr-file-input`'s own
  `heldFileCount`/`heldTotalSize`: `0` (the default) means "nothing held" and reproduces prior
  behavior exactly, and a negative, `NaN`, or `Infinity` override is normalized to `0` via
  `finiteCount` rather than corrupting every later comparison.
- `readonly dragging: boolean` — `true` during an active drag session

**Events:** `lr-files` (`detail: LyraDropZoneFilesDetail`, with fresh frozen readonly `files` and
`rejected` arrays and frozen rejected-file records, plus `remainingFiles`/`remainingTotalSize`
reporting the allowance still left under `maxFiles`/`maxTotalSize` after this drop (`null` while
that limit is unset), fired on drop; immutable `File` objects retain identity) — typed as
`LyraDropZoneFilesEvent`, so `event.target`/`event.currentTarget` are `LyraDropZone` without a
cast. `LyraDropZoneRejectedFile = { readonly file: File; readonly reason: 'type' | 'count' | 'size'
| 'directory' | 'read' | 'limit' | 'maxFiles' | 'maxTotalSize' }`, the same reason vocabulary as
`lr-file-input`'s `LyraFileInputRejectedFile`.

**Slots:** the default slot is the wrapped region, rendered as ordinary light DOM; `overlay`
overrides the localized accept/reject overlay text.

**CSS parts:** `base` (wraps the default slot and the overlay), `overlay` (the drag-over overlay,
layered above the slotted content via `position: absolute; inset: 0`, hidden outside an active drag
session), `overlay-icon`, `overlay-text`, `status` (a visually-hidden, `aria-hidden` mirror of the
drag state and counts — announcements go through the shared light-DOM regions, same as
`lr-file-input`), `rejection` (a visible region listing each currently-rejected file, rendered only
while one exists).

**CSS custom states:** `dragging`, matching `lr-file-input`'s.

**Themeable custom properties:** `--lr-drop-zone-radius` (default `var(--lr-radius)`),
`--lr-drop-zone-overlay-border-color` (default `var(--lr-color-brand)`, the dashed overlay border in
its neutral drag state, before an accept/reject verdict) and `--lr-drop-zone-overlay-bg` (default
`color-mix(in srgb, var(--lr-color-brand) 8%, transparent)`, that same neutral state's fill),
`--lr-drop-zone-overlay-font-size` (default `var(--lr-font-size-md-sm)`),
`--lr-drop-zone-overlay-icon-size` (default `var(--lr-font-size-xl)`),
`--lr-drop-zone-overlay-gap` (default `var(--lr-space-xs)`), and the drag accept/reject highlight —
`--lr-drop-zone-accept-border-color`/`--lr-drop-zone-accept-bg` (defaults `var(--lr-color-success)`/
`color-mix(in srgb, var(--lr-color-success) 12%, transparent)`) and
`--lr-drop-zone-reject-border-color`/`--lr-drop-zone-reject-bg` (defaults `var(--lr-color-danger)`/
`color-mix(in srgb, var(--lr-color-danger) 12%, transparent)`) — independently overridable on the
element or any ancestor, mirroring `lr-file-input`'s equivalent hooks.

**Optional peer deps:** none.

```html
<lr-drop-zone id="chat-surface" accept="image/*,.pdf" max-files="5">
  <div class="chat-panel">
    <!-- an existing chat composer / viewport, unrelated to this component -->
  </div>
</lr-drop-zone>
<script>
  document.querySelector("#chat-surface").addEventListener("lr-files", (e) => {
    console.log("accepted:", e.detail.files, "rejected:", e.detail.rejected);
  });
</script>
```

Composing `lr-file-input` inside the wrapped region gives that region both a click-to-browse picker
and a drop target covering the whole surrounding panel:

```html
<lr-drop-zone>
  <div class="chat-panel">
    <lr-file-input></lr-file-input>
  </div>
</lr-drop-zone>
```

**Known gotchas:**

- No paste-from-clipboard handling (unlike `lr-file-input`'s `paste`) — this component is drag/drop
  only.
- Dragged folders are traversed recursively while `multiple` (the default), with the same
  10,000-entry budget and `'read'`/`'limit'` failure reasons as `lr-file-input`. While not
  `multiple`, a dropped folder is rejected outright with reason `'directory'`.

---

## `lr-file-input`

A form-associated drag-drop + click-to-browse file dropzone. It stores and renders raw `File[]`;
no client-side CSV/XLSX/etc. parsing is performed (that's left entirely to the host).

Removing `label` or `hint` consumes it as absent without changing the property's `null` readback. An
explicit empty string remains empty. Text chrome and label/description associations disappear when
no corresponding slot or explicit presence hint remains, and a later value restores them. Removing
the label leaves the localized dropzone instruction available. Disabled file removal buttons,
including fieldset disablement, retain resting foreground and background under hover and press;
enabled buttons retain pointer feedback.

**Properties:**

- `multiple: boolean = false` (reflected)
- `disabled: boolean = false` (reflected)
- `files: File[] = []` — selected files; programmatic writes are event-silent and immediately
  synchronize rendering, validity, and form submission
- `readonly fileCount: number` and `readonly dragging: boolean` — derived state. Assigning `files`
  updates the selected-file count; real drag events alone own the drag session and its
  accept/reject state.
- `name: string | null = null`, `required: boolean = false`, `form`, `labels`, `validity`,
  `validationMessage`, and `willValidate` — standard form-associated surface. One file submits as a
  `File`; `multiple` submits repeated entries under `name`
- `customError: string | null` (attribute `custom-error`) — reflected consumer validation message;
  a non-empty value blocks submission until cleared with `setCustomValidity('')` or
  `resetValidity()`
- `accept: string = ''` — a native-`accept`-style string (`.csv,.xlsx`, `text/csv`, `image/*`, or any
  comma-separated mix); now enforced on **both** the native picker dialog and the drag-drop path, see
  gotchas
- `capture: '' | 'user' | 'environment' = ''` — forwarded to the native file picker
- `allowedMimeTypes: readonly string[] = []` (attribute: false) — exact MIME-string allowlist
- `forbiddenMimeTypes: readonly string[] = []` (attribute: false) — exact MIME-string denylist,
  checked **before** (and taking precedence over) `allowedMimeTypes`. Both properties take frozen
  snapshots, retain valid string entries, and inspect at most 10,000 candidates per assignment;
  update them by assigning a new collection.
- `maxFileSize: number = 0` (attribute `max-file-size` — bytes; `0` disables the check)
- `maxFiles: number = 0` (attribute `max-files`) — largest total file count accepted, counting
  retained files (unless `nonRetaining`) plus `heldFileCount` plus the current batch; `0` disables
  the check. An excess file in the batch is rejected with reason `'maxFiles'`, in the same
  `[part="rejection"]` shape as `maxFileSize`.
- `maxTotalSize: number = 0` (attribute `max-total-size`) — largest combined byte size accepted,
  summing retained files (unless `nonRetaining`) plus `heldTotalSize` plus the current batch; `0`
  disables the check. Same rejection-UI shape and fail-safe invalid-override behavior as
  `maxFileSize` (see gotchas).
- `heldFileCount: number = 0` (attribute `held-file-count`) — externally held file count added to
  the running count `maxFiles` evaluates against, in both retaining and `nonRetaining` modes — the
  numeric counterpart of `valuePresent`, for a cumulative cap (e.g. a server-backed upload limit)
  that spans separate picker sessions rather than resetting to what this control alone can see. `0`
  (the default) means "nothing held" and reproduces prior behavior exactly. A negative, `NaN`, or
  `Infinity` override is normalized to `0` via `finiteCount` rather than corrupting every later
  comparison or permanently blocking every future file.
- `heldTotalSize: number = 0` (attribute `held-total-size`) — externally held byte total added to
  the running size `maxTotalSize` evaluates against, in both retaining and `nonRetaining` modes.
  Same contract, default, and invalid-input normalization as `heldFileCount`.
- `nonRetaining: boolean = false` (reflected, attribute `non-retaining`) — opt-in mode where an
  accepted selection still fires `lr-files`/`input`/`change` but is never written to `files` or
  rendered as a built-in `[part="file"]` row. For a host that persists files elsewhere and renders
  its own list, so assigning `files` (even to reset it) never fights that host-owned rendering.
  `required` validity and the `blank` custom state then read `valuePresent` instead of
  `files.length`. Does not affect `formStateRestoreCallback()` or a direct `files` assignment, both
  of which still retain.
- `valuePresent: boolean = false` (reflected, attribute `value-present`) — external "a value is
  present" signal a `nonRetaining` host sets once it has taken ownership of the selected files, so
  `required` validity and the `blank` state reflect externally-held files. Ignored while
  `nonRetaining` is `false`.
- `directory: boolean = false` (reflected) — enables native directory selection where supported
- `paste: boolean = true` (reflected) — accepts files pasted into the dropzone
- `compact: boolean = false` (reflected) — tighter dropzone padding, gap and label font for
  constrained spaces (a toolbar, a table cell) — the same convention as `lr-empty`'s `compact`. The
  dashed border stays; only the internal spacing shrinks. `false` (the default) keeps the full
  `--lr-space-l` dropzone.
- `label: string = ''` and `hint: string = ''`; an empty `label` leaves the localized dropzone
  instruction (`fileInputDefaultLabel`) as the visible fallback
- `errorText: string = ''` (attribute `error-text`) — plain-text owned validation feedback. When
  it is empty, a `customError` message is rendered when present; otherwise an intrinsic validation
  message appears after the control has been interacted with. Rich `error` slot content replaces
  that text.
- `withLabel: boolean = false`, `withHint: boolean = false`, and `withError: boolean = false`
  (attributes `with-label`, `with-hint`, and `with-error`) — SSR slot-presence hints. Use
  `with-error` when the rich `error` slot is populated in initial declarative-shadow-DOM output,
  before hydration can observe the assigned light-DOM content.
- `size: LyraSize = 'm'` (reflected)
- `validators: LyraFileInputValidator[] = []` (attribute: false) — additional JavaScript
  constraints, run after the intrinsic `required` check. **Fixed in 9.0.0:** the property was
  previously declared (typed `unknown[]`) and read by nothing, so an assigned validator silently
  never ran. It now implements the same contract as `lr-date-input`/`lr-combobox`:
  - a function `(files: File[], input: LyraFileInput) => void | boolean | string | ValidityStateFlags`
    — `undefined`/`true` passes, a string is the validation message (raising `customError`), `false`
    is a generic failure using the localized `valueInvalid` string, and a `ValidityStateFlags` object
    names the flags to raise;
  - an object with `validate(files, input)` returning the same shapes;
  - the mapped object-validator shape `{ observedAttributes?, checkValidity(input), message? }`,
    whose `checkValidity()` returns `{ isValid, invalidKeys, message }`. Unrecognized `invalidKeys`
    are dropped, and an empty mapped set synthesizes `customError`. The message falls back from the
    result's own `message` to the validator's static or function `message`, then to the localized
    default. Attributes listed in `observedAttributes` are watched on the host and revalidate live.
    Validators run in order and the first failure wins. A validator that throws fails closed with the
    localized generic message rather than escaping into the caller. Unreadable proxy-backed
    validator collections/results are contained too: a collection or result trap fails closed,
    returned validity flags are copied through the native flag vocabulary, and an unreadable
    `observedAttributes` list is skipped without rejecting the component's update. The public array
    remains the live mutable mirrored contract; each validation/observer pass takes only a transient
    iteration snapshot. `checkValidity()` and `reportValidity()` recompute at call time, so a
    validator that starts failing without any host property changing is still seen. Own or
    fieldset-cascaded `disabled` bars configured validators exactly as it bars the intrinsic
    constraint. Exported types:
    `LyraFileInputValidator`, `LyraFileInputValidatorResult`, `LyraFileInputObjectValidator`,
    `LyraFileInputObjectValidatorResult`.
- `validationTarget: HTMLElement | undefined` — the focusable base of the dropzone control after
  first render. Assign another shadow descendant to override where native constraint-validation UI
  is anchored; assign `undefined` to restore the default focusable base
- `accessibleLabel: string = ''` (attribute `aria-label`) — overrides `label` as the internal
  dropzone/button accessible name without changing visible copy
- `acceptedMessage?: string` (attribute `accepted-message`) — live-region message after an
  accepted selection; `{count}` is replaced with the accepted count. Absence uses the localized
  singular/plural `fileInputAcceptedOne`/`fileInputAcceptedMany` default. Every explicit string,
  including empty and the former `'{count} file(s) added.'` English default, wins verbatim.
- `rejectedMessage?: string` (attribute `rejected-message`) — live-region message after rejected
  files; `{count}` is replaced with the rejected count. Absence uses the localized singular/plural
  `fileInputRejectedOne`/`fileInputRejectedMany` default. Every explicit string, including empty
  and the former `'{count} file(s) rejected.'` English default, wins verbatim.

**Methods:** `openPicker()` programmatically opens the native file dialog; `focus(options?)`,
`blur()`, and `click()` forward to the interactive dropzone. Standard FACE methods are
`getForm()`, `checkValidity()`, `reportValidity()`, `setCustomValidity(message)`, and
`resetValidity()`; reset clears only consumer custom validity and restores current intrinsic
`required` validity.

**Events:** a user selection or removal emits native bubbling/composed `input`, then exactly one
host `change`; programmatic `files` writes are silent (both still fire while `nonRetaining` is set,
even though `files` itself is not written in that mode). `lr-files` (`detail:
LyraFileInputFilesDetail`, with fresh frozen readonly `files` and `rejected` arrays and frozen
rejected-file records, plus `remainingFiles`/`remainingTotalSize` reporting the allowance still left
under `maxFiles`/`maxTotalSize` after this batch (`null` while that limit is unset), fired on both
drop and manual file-picker selection; immutable `File` objects retain identity) — typed as
`LyraFileInputFilesEvent`, so `event.target`/`event.currentTarget` are `LyraFileInput` without a
cast. `LyraFileInputRejectedFile = { readonly file: File; readonly reason:
'type' | 'count' | 'size' | 'directory' | 'read' | 'limit' | 'maxFiles' | 'maxTotalSize' }`: `'type'`
from `accept`/`allowedMimeTypes`/`forbiddenMimeTypes`, `'count'` when a single-file input
(`multiple` unset) receives more than one file (in which case _all_ files are rejected, none
accepted), `'size'` from `maxFileSize`, `'maxFiles'`/`'maxTotalSize'` from the two aggregate limits,
`'directory'` for a dropped folder in single-file mode, `'read'` when a file/directory reader fails,
or `'limit'` when folder traversal exceeds its bounded entry budget. Read/limit failures reject the
complete selection atomically; lifecycle cancellation and supersession stay silent. `focus`/`blur`
fire when the semantic dropzone (the actual keyboard-focusable element, not the hidden native
`<input>`) gains/loses focus. `lr-invalid` is the bubbling/composed alias of native invalidity.

Each rejected file also renders as its own line in the visible `[part="rejection"]` region, naming
the file and the reason via one of eight locale keys: `fileInputRejectedType` (default
`'{filename}: this file type is not accepted.'`), `fileInputRejectedSize` (default
`'{filename}: this file is too large.'`), `fileInputRejectedCount` (default `'{filename}: only one
file can be selected at a time.'`), `fileInputRejectedMaxFiles` (default `'{filename}: the maximum
number of files has been reached.'`), `fileInputRejectedMaxTotalSize` (default `'{filename}: adding
this file would exceed the total size limit.'`), and — for `'directory'` — the pre-existing
`fileInputFolderRejected` (default `'Folders are not accepted here.'`, reused verbatim, so it has no
`{filename}` placeholder). Terminal traversal failures use `fileInputRejectedRead` (default
`'{filename}: the file could not be read.'`) and `fileInputRejectedLimit` (default
`'{filename}: the folder contains too many entries.'`). The filename is interpolated as
caller-supplied data, never localized itself. The same per-reason text is announced assertively;
the region is cleared (and unrendered) as soon as a subsequent selection rejects nothing.

**Slots:** `dropzone` (with the default slot retained as its fallback) supplies custom dropzone
content; `label`, `hint`, and `error` supply form chrome. The semantic button's accessible name comes from
`accessibleLabel`/host `aria-label`,
then `label`, so icon-only slot content still announces correctly. Slotted content is a sibling of
the button rather than nested inside it: links, buttons, inputs, and other interactive slotted
controls keep their own activation and do not also open the picker; clicking non-interactive custom
content still activates the dropzone.

The semantic button describes its rendered owned error and hint in that order. A supplied
`errorText` or `error` slot marks it `aria-invalid="true"`; a required intrinsic message appears
after interaction, while a custom validity message is immediately visible and survives native form
reset until `resetValidity()` or `setCustomValidity('')` clears it.

**CSS parts:** `file-input` (compatibility alias) and `form-control` (the complete form-control
frame), `form-control-label`, `label`, `hint`, `error`, `dropzone`, `dropzone-icon`, `dropzone-text`,
`base` (the native dropzone button, visually behind but semantically beside the
slotted content), `input`, `file-list`, `file`, `file-thumbnail`, `file-image`, `file-icon`,
`file-details`, `file-name`, `file-size`, `remove-button`, `status` (a visually-hidden,
`aria-hidden` mirror of the drag accept/reject state and the aggregate accepted/rejected count),
`rejection` (a **visible** region, rendered only while a rejection exists, listing each
currently-rejected file next to a per-reason message — in addition to, never in place of, the
sr-only `status` mirror above)

**Both live regions moved out of the shadow root (public surface change).** Neither `status` nor
`rejection` carries a live-region role any more: `status` is an `aria-hidden` mirror, and
`rejection` is plain visible text. A live region inside a shadow root is not reliably announced
(JAWS with Firefox ignores one outright), so the announcements now go to the library's shared
**light-DOM** regions appended to the consumer's `<body>` and marked
`data-lr-live-region="polite"` / `data-lr-live-region="assertive"` — the drag/selection summary
politely, and a rejection assertively, so it still interrupts.

What this changes for you:

- **Nothing about what the visible text says or where it renders.** `[part="rejection"]`'s text is
  ordinary visible content and stays in the accessibility tree, so a user who reaches it reads it
  normally. Both parts remain the right styling hooks.
- **Read announcements from the shared light-DOM region** — query
  `[data-lr-live-region="assertive"]` or `[data-lr-live-region="polite"]` in the document rather
  than the styling parts.
- **A `::part(rejection)[role]`-style selector never matched anyway** — an attribute selector
  cannot follow `::part()`. Nothing that worked before stopped working.

**CSS custom states:** `blank` and `dragging`, plus the shared validity states `required`,
`optional`, `valid`, `invalid`, `user-valid`, and `user-invalid`. As on every other form-associated
control, `valid`/`invalid` and `user-valid`/`user-invalid` stop matching entirely while the control
is barred from constraint validation (its own `disabled`, or an ancestor `<fieldset disabled>`),
matching native `:invalid`; `required`/`optional` keep publishing.

**The required marker.** With `required` set and a populated `label`, `[part="form-control-label"]`
paints the library's shared required marker — the same `::after` rule every labelled control in
the library uses, not a copy of it, so `--lr-form-control-required-content`,
`--lr-form-control-required-color` and `--lr-form-control-required-offset` retune or suppress it
here exactly as they do on `lr-input`. See `llms/shared.md` → "The required-field marker".

**Themeable custom properties:** `--lr-file-input-gap` (default `var(--lr-space-xs)`) — gap between
the dropzone's slotted children; `--lr-file-input-radius` (default `var(--lr-radius)`) — corner
radius of `[part='base']`; `--lr-file-input-compact-padding` (default `var(--lr-space-s)`) —
`[part='base']`'s padding while `compact`; `--lr-file-input-compact-gap` (default
`var(--lr-space-2xs)`) — the gap between the dropzone's slotted children while `compact`; and
`--lr-file-input-compact-font-size` (default `var(--lr-font-size-sm)`) — the label's font size while
`compact`. `--lr-file-input-font-size` (default `var(--lr-form-control-font-size)`) controls the
label and selected-filename text size.

`size` retunes the whole dropzone, not just its label: `--lr-file-input-dropzone-font-size`
(default `var(--lr-font-size-md-sm)`) for the instructional text,
`--lr-file-input-dropzone-icon-size` (default `var(--lr-font-size-xl)`) for `[part='dropzone-icon']`,
`--lr-file-input-dropzone-padding` (default `var(--lr-space-l)`) for the dropzone's own padding, and
`--lr-file-input-detail-font-size` (default `var(--lr-font-size-sm)`) for the secondary text (hint,
validation error, each file's formatted size). Each documented default is the `m`/`medium` tier, and
each is re-declared per `size` tier — so an unset or default-size control renders exactly as before,
while `size="xl"` scales the dropzone coherently instead of enlarging the label alone. `compact`
still overrides the dropzone padding and font size independently of the tier. The compact gap falls back to `--lr-file-input-gap` when its compact-specific
property is unset. The compact properties apply only while `compact` is set, so they are the way to tune a dense dropzone
without re-pointing shared spacing tokens for everything else on the page. The drag accept/reject
highlight on `[part='base'][data-drag-state='accept'|'reject']` is independently overridable too:
`--lr-file-input-accept-border-color` (default `var(--lr-color-success)`) and
`--lr-file-input-accept-bg` (default `color-mix(in srgb, var(--lr-color-success) 8%, transparent)`)
for the drag-accept state; `--lr-file-input-reject-border-color` (default `var(--lr-color-danger)`)
and `--lr-file-input-reject-bg` (default `color-mix(in srgb, var(--lr-color-danger) 8%,
transparent)`) for drag-reject. All four are inline `var()` fallbacks at the point of use, settable
on the element or any ancestor, so a consumer can retint just this dropzone's drag highlight without
hijacking the shared `--lr-color-success`/`--lr-color-danger` tokens used elsewhere.

The **resting** dropzone — the state it spends most of its life in — has the same three hooks as of
16.0.0: `--lr-file-input-dropzone-fill` (default `var(--lr-color-surface)`),
`--lr-file-input-dropzone-border-color` (default `var(--lr-color-border)`; the dashed border style
itself is unchanged), and `--lr-file-input-dropzone-hover-border-color` (default
`var(--lr-color-brand)`), which recolours the edge whether the pointer is over the button or over
the content stacked on it. The shared field halo `--lr-form-control-focus-shadow` (default `none`)
paints a `box-shadow` while the dropzone holds focus; it is additive, so the
`[part='base']:focus-visible` outline is untouched. Plus shared
tokens — `--lr-space-xs`, `--lr-space-l`,
`--lr-color-border`, `--lr-radius`, `--lr-color-surface`, `--lr-color-text-quiet`,
`--lr-focus-ring-width/-color/-offset` (`[part="base"]:focus-visible` outline),
`--lr-opacity-disabled` (`:host([disabled])` dimming).

**Optional peer deps:** none.

```html
<lr-file-input id="dataset-files" multiple accept=".csv,.xlsx"></lr-file-input>
<script>
  const input = document.querySelector("#dataset-files");
  input.allowedMimeTypes = ["text/csv"];
  input.addEventListener("lr-files", (e) => {
    console.log("accepted:", e.detail.files, "rejected:", e.detail.rejected); // rejected[i].reason
  });
</script>
```

Note: `allowedMimeTypes`/`forbiddenMimeTypes` are complex properties (`attribute: false`) — set
them via JS (`el.allowedMimeTypes = [...]`), not as a JSON string attribute.

`accept.ts` exports `matchesAccept(file, accept, assumeExtensionMatch?)` (internal — not
re-exported from the package root) — parses the same three `accept` forms the browser's native
picker accepts (extension, exact MIME, `type/*` wildcard) and reports whether a `File` matches. Used
both for the drop path's real rejection and for the dragenter preview, where a `DataTransferItem` (no
`.name`, only `.type`) can't evaluate an extension pattern yet — `assumeExtensionMatch: true` treats
that as a possible match during preview so the drag-over UI doesn't flash a false "reject" state for
an extension-only `accept` list.

**Known gotchas:**

- Paste-from-clipboard **is** supported and on by default: a `paste` event on the dropzone reads
  `e.clipboardData.files` and routes it through the same accept/reject classification as a drop.
  Set `paste="false"` (or `.paste = false`) to opt out.
- Dragged folders are traversed recursively in `multiple` mode with a 10,000-entry budget. A read
  failure or over-budget traversal rejects the complete drop atomically and emits one `lr-files`
  result with `rejected[].reason === 'read'` or `'limit'`, plus dedicated visible and assertive
  localized feedback. Lifecycle cancellation and supersession remain silent and emit no partial
  result. In single-file mode a folder is reported as `rejected[].reason === 'directory'` (paired
  with a synthetic zero-byte `File` carrying the folder name).
- `maxFileSize` fails safe rather than open: `0` (the default) or `Infinity` mean "no limit", but a
  `NaN`/negative value — an unparsable `max-file-size` attribute, or a config that hasn't loaded
  yet — falls back to a 25 MB cap (exported as `DEFAULT_MAX_FILE_SIZE_BYTES`) instead of disabling
  the check. `maxFiles` and `maxTotalSize` fail safe the identical way, falling back to
  `DEFAULT_MAX_FILES` (100) and `DEFAULT_MAX_TOTAL_SIZE_BYTES` (250 MB) respectively.
- The drag-session mechanics (nested-depth tracking, accept/reject preview, folder traversal) live
  in `internal/drop-session-controller.ts`, shared verbatim with `lr-drop-zone` below rather than
  reimplemented per component.
- `maxFileSize`/`accept` extension patterns can't be evaluated during the dragenter preview (no real
  `File.size`/`.name` available yet from a `DataTransferItem`) — the live preview state (border/
  background color, `status` announcement) is therefore only a best-effort hint; the authoritative
  accept/reject decision (and `rejected[].reason`) is always the one made at actual drop time.
- the click/keyboard-to-browse path is correctly operable (`role="button"`, `tabindex` 0/-1 by
  disabled, `aria-disabled`, Enter/Space handling).

---

## `lr-image-comparer`

Before/after comparison surface with two named slots and a keyboard-accessible native range handle.

**Properties:**

- `position: number = 50` (attribute `position`, reflected) — divider position from 0 to 100
- `orientation: 'horizontal'|'vertical' = 'horizontal'` (attribute `orientation`, reflected)
- `accessibleLabel: string | null` (attribute `aria-label`) — accessible name for the comparison
  and its range handle
- `beforeLabel`/`afterLabel` — fallback text for empty named slots

**Events:** exactly one owner-realm, bubbling/composed native `input` (`Event`) after every live
range update, and exactly one owner-realm native `change` (`Event`) after a gesture commits.
`focus`/`blur` are relayed exactly once as owner-realm native `FocusEvent`s preserving
`relatedTarget`; a dirty keyboard edit commits its `change` before `blur`.

Arrow handling is explicit so browser engines cannot disagree: in horizontal orientation,
Left/Right follows the mirrored inline axis (and Up/Down increases/decreases); in vertical
orientation, Up/Left decreases toward the physical top and Down/Right increases toward the
physical bottom, independent of document direction. Home/End select 0/100 and PageUp/PageDown
move by 10. Only a primary left-button pointer may begin a drag.

**Methods:** `focus(options?)`, `blur()`, and `click()` forward to the internal range handle.

**Slots:** `before`, `after`, and `handle` (decorative content inside the visible drag handle). The
flattened `handle` subtree is always inert and hidden from assistive technology, so even an
accidentally interactive slotted descendant cannot become a second focus target; the native range
remains the sole interaction surface.

**CSS parts:** `base` and `comparison` are aliases on the same comparison viewport; `before`,
`after`, `divider`, `handle` (the full interaction wrapper), and `input` (the transparent native
range input).

**CSS custom properties:** `--lr-image-comparer-divider-width` (default
`var(--divider-width, var(--lr-size-1px))`) controls the dividing line's thickness, and
`--lr-image-comparer-handle-size` (default `var(--handle-size, var(--lr-icon-button-size))`) sizes
the visible handle in both axes. Those namespaced names are the ones to override: the bare
Shoelace-compat `--divider-width`/`--handle-size` are retained as their fallback source, but an
unprefixed custom property inherits, so setting one high up the tree silently retunes every other
element below that reads a property of the same generic name. The `dragging` CSS custom state is present only while a pointer gesture is active and is
cleared on pointer cancellation, blur, or disconnect.

```html
<lr-image-comparer aria-label="Before and after">
  <img slot="before" alt="Before" src="before.png" />
  <img slot="after" alt="After" src="after.png" />
  <span slot="handle" aria-hidden="true">↔</span>
</lr-image-comparer>
```

---

## `lr-zoomable-frame`

Sandboxed iframe preview that mirrors Web Awesome's zoomable-frame contract. It scales a real
`<iframe>` through discrete controls without changing the document's own viewport, and fills its
allocated inline size with a 16:9 aspect ratio by default (override `aspect-ratio` on the host).

Focus on either zoom control does not enter the iframe browsing context, and `blur()` does not blur
a focused zoom control.

**Properties:**

- `src: string = ''` — iframe URL. Relative, `http:`, `https:`, `blob:`, and exact `about:blank`
  values are accepted; active `data:`/`javascript:` and non-embeddable schemes are omitted.
- `srcdoc: string = ''` — inline iframe document. A present `srcdoc` wins over `src`, including an
  explicitly empty `srcdoc` attribute.
- `allowfullscreen: boolean = false`, `loading: LyraZoomableFrameLoading = 'eager'`
  (`'eager' | 'lazy'`),
  `referrerpolicy: string = ''`, and `sandbox: string = 'allow-same-origin'` forward the native
  iframe controls after validation. Invalid loading becomes `eager`; an invalid non-empty referrer
  policy becomes `no-referrer`.
- `zoom: number = 1` (reflected) — current scale. Finite programmatic values do not have to occur
  in `zoomLevels`; unsafe/non-finite layout values render as a finite positive fallback.
- `zoomLevels: string = '25% 50% 75% 100% 125% 150% 175% 200%'` (attribute `zoom-levels`) —
  decimal/percentage stops used by the controls. The cached projection reads at most the first
  16,384 UTF-16 code units and 256 whitespace-delimited tokens before deduplicating and sorting;
  a token cut by the source ceiling is ignored, and later source text cannot affect the controls.
- `withoutControls: boolean = false`, `withoutInteraction: boolean = false`, and
  `withThemeSync: boolean = false` (reflected attributes `without-controls`,
  `without-interaction`, `with-theme-sync`) — respectively remove the zoom controls, remove pointer and
  sequential-keyboard iframe interaction by making the browsing context native `inert`, and opt
  into best-effort same-origin theme sync. The inert frame also refuses programmatic focus/click
  and carries no unsupported `aria-disabled` claim.
- `accessibleLabel: string | null` (attribute `aria-label`) — a declarative attribute remains on
  the host while the iframe gets its localized purpose title, avoiding a duplicate name on two
  semantic owners. A property-only value names the iframe and updates reactively without creating a host attribute. Explicit empty host naming is preserved
  as an empty iframe title rather than replaced through truthiness.
- readonly `iframe?: HTMLIFrameElement`, `contentWindow: Window | null`, and
  `contentDocument: Document | null`. Both content accessors return `null` while detached;
  `contentDocument` also returns `null` across an origin boundary.

**Authoring type:** `LyraZoomableFrameLoading`. The former unprefixed
`ZoomableFrameLoading` name is removed in v9 rather than retained as an alias.
The former deep-class-module implementation exports `DEFAULT_ZOOM_LEVELS`,
`DEFAULT_IFRAME_SANDBOX`, `safeZoomableFrameSrc()`, and `safeZoomableFrameSandbox()` are also
removed in v9. They were never part of the registration, root, or documented component surface;
configure the corresponding public properties instead of depending on sink-policy internals.

**Methods:** `zoomIn()` selects the nearest configured level above the current value;
`zoomOut()` selects the nearest below it. The control group also accepts `+`/`=` and `-`/`_` while one
of its controls has focus. `focus(options?)`, `blur()`, and `click()` forward to the internal
iframe — the component's primary interactive surface — only while the component is connected and
interaction is enabled. Under `without-interaction` they are deliberate no-ops rather than an
escape around native `inert`; the two-button zoom-control group has no single primary action. Both
buttons are ordinary independent Tab stops inside a labelled `role="group"`; the container does not
claim the roving-arrow-key contract of an ARIA toolbar.

**Slots:** `zoom-in-icon` and `zoom-out-icon` replace the decorative control glyphs. Their
flattened subtrees are always inert and hidden from assistive technology, so use an SVG or glyph
rather than a second interactive control; the native zoom buttons remain the sole focus and pointer
actions.

**Events:** internal `focus`/`blur` from the iframe are relayed exactly once as owner-realm native
`FocusEvent`s (bubbling and composed, preserving external `relatedTarget`; a transition to or from an internal zoom control uses `null` because retargeting that control to the host would suppress the relay);
native `load` and `error` are relayed exactly once from the current iframe
generation as non-bubbling, non-composed `Event` instances. Navigation/source-policy changes
replace the iframe, so a late event from an earlier document is ignored; detached frames do not
notify.

**CSS parts:** `iframe`, `controls`, `zoom-in-button`, and `zoom-out-button`. Real focus entry into
the browsing context (Tab, pointer, or `focus()`) exposes `data-frame-focused` on the host and paints
the shared focus ring around the iframe boundary; blur, navigation rekey, disablement, and removal
clear it. Moving between the iframe and a zoom control clears or restores the marker and emits one matching native blur or focus relay; focusing a zoom control alone leaves the marker absent.

**CSS custom properties:** read-only `--lr-zoomable-frame-zoom`, resolved from the `zoom`
property and applied to the internal iframe scale; and `--lr-zoomable-frame-control-hover-background`
(default `var(--lr-color-brand-quiet)`), which colors a zoom control on hover and supplies the base
for its active color.

**RTL behavior:** the scaled iframe is a physical canvas and remains pinned to physical top-left in
both directions. Its zoom controls remain logical interface chrome, so RTL places the control group at
inline-end (the physical left edge).

**Security and theme sync:** the iframe always keeps a `sandbox` attribute. The secure Lyra default
allows same-origin access but not scripts, forms, popups, downloads, or top navigation. Supplied
sandbox tokens are allowlisted; if both `allow-scripts` and `allow-same-origin` are requested, the
latter is dropped so framed script cannot escape a same-origin sandbox. `with-theme-sync` never
widens those permissions: when the document is accessible it copies only Lyra theme-selector
classes, theme attributes, computed `--lr-theme-*` inputs, and `color-scheme`; cross-origin
documents remain untouched. Turning `with-theme-sync` off restores only the iframe classes,
attributes, and inline properties Lyra changed, preserving any later iframe-owned edits. Changing
a watched host-page theme attribute syncs again.

```js
import "@aceshooting/lyra-ui/components/media/zoomable-frame/zoomable-frame.js";
```

```html
<lr-zoomable-frame
  aria-label="Component preview"
  srcdoc="<!doctype html><html><body><h1>Preview</h1></body></html>"
  zoom="0.75"
  with-theme-sync
></lr-zoomable-frame>
```

---

## `lr-pan-zoom`

Scrollable inspection surface for slotted DOM or one image, with bounded zoom and native-scroll
panning. This is the compatibility destination for Lyra's former `lr-zoomable-frame` behavior:
existing consumers that inspect DOM/images should rename the tag to `lr-pan-zoom` (and the class
import to `LyraPanZoom`); `lr-zoomable-frame` now means the mapped iframe component above.

**Properties:**

- `zoom: number = 1` (reflected), `minZoom: number = 0.5`, `maxZoom: number = 4`, and
  `zoomStep: number = 0.25` — bounded, finite zoom configuration
- `src: string = ''` and `alt: string = ''` — optional safe image source. A rejected URL is treated
  as absent and the default slot renders; no empty or unsafe `<img>` replaces that fallback.
- `fit: LyraImageFit = 'actual'` (reflected) — base sizing policy for an image supplied through
  `src`, using the same `contain`/`width`/`actual` vocabulary as `<lr-image-viewer>`. `actual`
  preserves the historical natural-size layout; the other modes resolve against the viewport and
  update with its allocation, including when an image loads after the frame first renders.
- `accessibleLabel: string | null` (attribute `aria-label`) — a declarative host label remains on
  the host while the focusable viewport receives the localized inspection-surface purpose name.
  A property-only value names the viewport and updates reactively without creating a host attribute. This avoids cloning one author label onto both the outer component and nested `role="group"`. An explicitly empty direct property remains empty; a present host attribute, including an empty one, leaves the viewport's localized purpose name intact.

**Methods:** `zoomIn()`, `zoomOut()`, and `resetZoom()` update zoom and emit `lr-zoom-change`
(`detail: { zoom }`). `resetZoom()` preserves pan; `resetView()` also scrolls the viewport to the
origin. Reset reaches 100% exactly whenever it is within `minZoom`/`maxZoom`; it is not quantized to
the nearest `zoomStep`. The viewport accepts `+`/`=`, `-`/`_`, and `0`, without consuming keys from
a slotted editor. The three zoom buttons are independently tabbable inside a labelled `group`; the
container does not claim toolbar arrow-key navigation.

**Slots:** default — inspected content, ignored while `src` renders an image.

`focus(options?)`, `blur()`, and `click()` forward to the scrollable `viewport`, which is the
component's own keyboard target — a bare host `.focus()` would otherwise be a silent no-op.

**Events:** `lr-zoom-change` (`detail: { zoom }`); internal `focus`/`blur` from the viewport are
relayed exactly once as owner-realm native `FocusEvent`s (bubbling and composed, preserving
`relatedTarget`).

**CSS parts:** `base`, `viewport`, `content`, `controls`, `zoom-out`, `zoom-in`, and `reset`. The
`reset` button's visible text is the live zoom percentage, locale-formatted and recomputed from
`zoom` on every render (not a fixed "100%"). Its accessible name includes both the localized reset
action and that visible percentage, so the visible label is contained in the computed name.

**Themeable custom properties:** `--lr-pan-zoom-min-block-size` (default `var(--lr-size-10rem)`)
and the read-only `--lr-pan-zoom-zoom`. The former `--lr-zoomable-frame-min-block-size` and
`--lr-zoomable-frame-zoom` compatibility names were removed in v9; migrate them to the two
`--lr-pan-zoom-*` names. Scaling
uses layout-participating CSS `zoom`, not a paint-only transform, so the viewport's native scroll
range reaches the entire painted footprint at both logical edges in LTR and RTL.

```js
import "@aceshooting/lyra-ui/components/media/pan-zoom/pan-zoom.js";
```

```html
<lr-pan-zoom
  src="map-preview.png"
  alt="Map preview"
  aria-label="Map preview"
></lr-pan-zoom>
```

---

## `lr-attachment-chip`

A compact chip representing one file queued for (or already part of) a chat message — used in a
composer's pre-send attachment tray or a sent message's attachments display. Two independent ways
to populate it: set `file` to a real `File` (fresh from a picker/drop), from which `name`/`bytes`/
`mime-type` and the image thumbnail are all auto-derived; or set the plain `name`/`bytes`/
`mime-type`/`thumbnail-src` props instead, for reconstructing a chip from server-persisted
attachment metadata after a page reload, when no real `File` object exists any more. `file` always
wins when both are present. When a real `File` or `preview-src` is available, the chip offers a
localized action that emits a plain, non-cancelable `lr-preview-request`; it never registers or owns a viewer
or overlay, so the host composes the desired preview surface.

An error already present at first mount or reconnection renders as existing state without an
announcement, including a failure assigned while detached and reconnected before the next render. A
new connected transition to error still appends one localized failure announcement; repeated
connected failures remain separately announced, including a retry whose uploading and error writes
coalesce into one update.

**Properties:**

- `file?: File` (attribute `false`, i.e. property-only) — when set, `name`/`bytes`/`mimeType`/the
  image thumbnail are all derived from it, taking precedence over the independent props below
- `name: string = ''` — filename, used only while `file` is unset
- `bytes?: number` — file size in bytes, used only while `file` is unset. `0` is a known empty file
  and renders `0 B`; omission means unknown. Negative/non-finite writes normalize to omission.
- `attachmentId: string = ''` (attribute `attachment-id`) — stable domain identity carried by
  attachment action events. Empty or whitespace-only values use the fallback identity below. The
  platform `id` remains available for DOM identity/idrefs only.
- `mimeType: string = ''` (attribute `mime-type`) — used only while `file` is unset
- `thumbnailSrc: string = ''` (attribute `thumbnail-src`) — thumbnail image URL, used only while
  `file` is unset; rendered whenever present regardless of `mimeType` (no `file`-derived equivalent
  exists for a non-image file)
- `previewSrc: string = ''` (attribute `preview-src`) — source URL used for preview and download when
  `file` is unset; a real `File` takes precedence and uses a temporary blob URL
- `previewable: boolean = true` (reflected) — shows the preview action whenever a `file` or
  `preview-src` is available
- `status: LyraAttachmentUploadStatus = 'pending'` (reflected) — `'pending' | 'uploading' |
'error' | 'success'`; invalid values normalize to `pending`. Drives the accent tint and which of
  `progress`/`spinner`/`retry-button` renders.
- `progress: number = 0` — upload completion, 0-100; only meaningful while `status="uploading"`, a
  value of `0` or `NaN` falls back to the indeterminate spinner
- `removable: boolean = true` (reflected) — shows the remove (×) button
- `compact: boolean = false` (reflected) — renders a smaller, borderless pill presentation instead of
  the default bordered/chrome-heavy chip, e.g. for a composer's pending-attachment tray. `false` (the
  default) is visually identical to the standard chip.
- `thumbnailOnly: boolean = false` (reflected, attribute `thumbnail-only`) — when both this and
  `compact` are set, hides `[part='meta']` (the filename/size text) entirely for an image-mime
  attachment, leaving only the thumbnail. Has no effect for a non-image chip, or when `compact` is
  unset. `false` (the default) reproduces the chip's exact existing output. While it actually hides
  `[part='meta']`, `[part='base']` also switches to a reduced, symmetric padding sized for a lone
  thumbnail instead of the compact text row's padding — see
  `--lr-attachment-chip-compact-thumbnail-only-padding` below.
- `removeLabel?: string` (attribute `remove-label`) — verb used in the remove button's accessible
  name; omitting it reads back `undefined` and routes through the complete localized
  `removeWithContext` template
- `retryLabel?: string` (attribute `retry-label`) — verb used in the retry button's accessible
  name; omitting it reads back `undefined` and routes through the complete localized
  `attachmentRetryWithContext` template
- `uploadingLabel?: string` (attribute `uploading-label`) — verb used in the visible uploading
  status; omitting it reads back `undefined` and uses complete localized messages for progress,
  indeterminate state, and filename context so translators can reorder every value
- `uploadFailedLabel?: string` (attribute `upload-failed-label`) — visible status text shown for
  `status="error"`; override for i18n/locale. Omitting it reads back `undefined` and uses the
  localized default (`'Upload failed'` in English)
- `untitledLabel?: string` (attribute `untitled-label`) — fallback filename and tooltip when
  neither `file` nor `name` supplies a name. Omitting it reads back `undefined` and uses the
  localized default (`'Untitled file'` in English)

**Renamed in 8.0.0 — breaking:** the byte count is `bytes`, not `size` (same rename as
`lr-file-icon`'s). Everywhere else in this library `size` names a tier on the shared size ladder,
and a numeric byte count answering to the same property name is a collision a consumer only
discovers at runtime. A leftover `size="245000"` is an unknown attribute now: `bytes` stays omitted
and the `size` part renders nothing.

The component identifies _which_ attachment an action event is about through `attachmentId`. Set
`attachment-id="..."` when you have a stable server-side identity; when unset or whitespace-only
and `file` is set, a stable attachment id is
derived from `` `${file.name}:${file.size}:${file.lastModified}` ``; when neither is available, a
generated internal id is used as a last resort.

**Events:** `lr-remove` (`detail: { attachmentId }`, only rendered while `removable`), `lr-retry`
(`detail: { attachmentId }`, only rendered while `status="error"`), and
`lr-preview-request` (`detail: { attachmentId, name, mimeType, src }`) — a plain, non-cancelable
notification that the preview action was activated. **Breaking in 10.0.0:** this event was
advertised as cancelable, but the chip never read `defaultPrevented` and owns no preview default
action to veto (it never registers or owns a viewer/overlay), so `preventDefault()` was a no-op.
The flag is gone rather than left as a promise the component cannot keep.

**Slots:** none.

**CSS parts:** `base`, `thumbnail`, `meta`, `name`, `size` (the formatted `bytes` count; the part
keeps its pre-rename name — it is the rendered size _text_, and renaming a part would break shipped
`::part()` rules for no gain), `status-text` (the visible text twin of
the status accent color, so the state is carried in words and not only in color; empty and hidden
for `pending`/`success`), `progress`, `progress-fill`, `spinner` (decorative/`aria-hidden` while the
adjacent `status-text` supplies the wording), `retry-button`, `preview-button`,
`remove-button`

**`status-text` carries no live-region role (public surface change).** It is plain visible text
that stays in the accessibility tree and reads normally once a user reaches the chip. The
interrupting announcement a transition _into_ `status="error"` makes — so a screen-reader user not
already focused on the chip still hears an upload failure — goes to the library's shared
**light-DOM** assertive region instead, appended to the consumer's `<body>` and marked
`data-lr-live-region="assertive"`: a live region inside a shadow root is not reliably announced
(JAWS with Firefox ignores one outright). Two consequences worth knowing:

- Only a _transition_ into `error` announces. A chip that mounts already failed is history the user
  can read at their own pace, and a retry that fails the same way twice is announced twice rather
  than being a silent no-op. The ticking `uploading` readout announces nothing at all — a live
  region re-announcing every progress tick is noise, not information.
- Read the announcement from `[data-lr-live-region="assertive"]` in the document;
  `::part(status-text)` remains the styling hook and visible-status text.

**Themeable custom properties:** `--lr-attachment-chip-accent` (default
`var(--lr-color-text-quiet)`), `--lr-attachment-chip-bg` (default `var(--lr-color-surface)`),
`--lr-attachment-chip-border` (default `var(--lr-color-border)`) — the trio's private defaults
change per `status` (`uploading` → brand/brand-quiet/transparent, `error` →
danger/danger-quiet/transparent, `success` → success/success-quiet/transparent), while an inherited
or direct public value remains authoritative; `--lr-attachment-chip-compact-thumbnail-size` (default
`1.75rem`), `--lr-attachment-chip-compact-font-size` (default `var(--lr-font-size-xs)`),
`--lr-attachment-chip-compact-gap` (default `0.25rem`) — govern the chip's thumbnail size, text
size, and internal gap while `compact` is set; `--lr-attachment-chip-spinner-duration` (default
`var(--lr-transition-ambient)`) controls the indeterminate rotation's duration and easing and stops
under reduced motion.
`--lr-attachment-chip-padding` (default `var(--lr-space-xs) var(--lr-space-s)`) and
`--lr-attachment-chip-compact-padding` (default `var(--lr-size-0-125rem) var(--lr-space-xs)`) make
`[part='base']`'s padding themeable in the resting and `compact` states respectively — both were
previously hardcoded. `--lr-attachment-chip-compact-thumbnail-only-padding` (default
`var(--lr-size-0-125rem)`, applied symmetrically to every side) governs `[part='base']`'s padding
specifically while `compact` and `thumbnail-only` together actually hide `[part='meta']` for an
image-mime attachment — reduced from the compact padding above, since the lone thumbnail no longer
needs inline padding sized for a text row that isn't rendering. It has no effect for a non-image
chip, where `[part='meta']` stays visible and the ordinary compact padding still applies.
Plus shared tokens `--lr-space-xs`, `--lr-space-s`,
`--lr-radius`, `--lr-color-text`, `--lr-color-danger`, `--lr-icon-button-size`,
`--lr-transition-fast`, `--lr-transition-base`, `--lr-focus-ring-width`,
`--lr-focus-ring-color`, `--lr-focus-ring-offset`.

**Optional peer deps:** none.

Also exported from the package root:
`formatFileSize(bytes: number, unitLabel?: (unit: 'B' | 'KB' | 'MB' | 'GB' | 'TB') => string,
numberLabel?: (value: number, fractionDigits: number) => string): string`. `unitLabel` localizes each
selected unit abbreviation; `numberLabel` formats the scaled value and receives `fractionDigits`
as `0` for bytes or `1` for larger units. Their defaults preserve the built-in output: `512` →
`"512 B"` (whole bytes never get a decimal), `2415919` → `"2.3 MB"` (every unit past bytes gets
exactly one decimal place), and a negative or non-finite input (`NaN`, `Infinity`) returns `""` so
an unknown size renders nothing instead of `"NaN B"`.

```html
<lr-attachment-chip
  name="report.pdf"
  bytes="245000"
  mime-type="application/pdf"
  status="success"
></lr-attachment-chip>
<lr-attachment-chip
  attachment-id="att-2"
  status="uploading"
  progress="42"
></lr-attachment-chip>
<script type="module">
  import { formatFileSize } from "@aceshooting/lyra-ui/components/media/attachment-chip/file-size.js";

  const chip = document.createElement("lr-attachment-chip");
  chip.file = pickedFile; // name/bytes/mime-type/thumbnail all derived from the File
  chip.addEventListener("lr-remove", (e) =>
    removeAttachment(e.detail.attachmentId)
  );
  chip.addEventListener("lr-retry", (e) => retryUpload(e.detail.attachmentId));
  chip.addEventListener("lr-preview-request", (e) => openPreview(e.detail));
  console.log(formatFileSize(pickedFile.size));
</script>
```

The image thumbnail for a real `File` is a cached `URL.createObjectURL()` blob URL, allocated in
`willUpdate()` — the update lifecycle, deliberately **never** from `render()`, so rendering stays a
pure projection of already-prepared state and URL allocation never happens as a render side effect.
It is created only when `file` is an image (or `previewable` is set), reused for as long as the same
`File` object stays assigned, and revoked when `file` changes to a different `File`, to a non-image,
or to `undefined`, and again on disconnect. Because the same pass that allocates also revokes the
previous entry, reassigning `file` several times before the next paint leaks nothing.

**Known gotchas:**

- `file` always wins over `name`/`bytes`/`mimeType` when both are set — assigning those props while
  `file` is also set has no visible effect on the rendered chip.
- A `0` `bytes` value is a known empty file and renders `"0 B"`; only omission means unknown and
  hides the `size` part. Negative and non-finite writes normalize to omission.
- `progress` only renders as a numeric bar when `status="uploading"` **and** `progress` is finite
  and `> 0`; otherwise it's either nothing (non-`uploading` status) or the indeterminate spinner
  (`uploading` with no known progress).
- `thumbnailSrc` is used whenever present regardless of `mimeType` — pass a URL that's already known
  to be an image; there's no non-image fallback check for it the way there is for `file`.
- `previewSrc` is used only when `file` is unset. A preview action is omitted when neither a real
  `File` nor `preview-src` supplies a source. The viewer's footer omits its download link for unsafe
  source schemes.

---

## `lr-file-icon`

Localized, tokenized file-format badge for surrounding upload rows, cards, selectors, and viewer
headers. The companion `getFileTypeMetadata(mimeType, fileName?)` utility covers common document,
spreadsheet, presentation, code, archive, image, audio, and video formats. An explicit known MIME
type wins; filename extension fallback is used only for an empty or `application/octet-stream`
MIME type. Unknown values return a generic file result.

**Properties:** `mimeType` (attribute `mime-type`), `name`, `bytes` (file size **in bytes**, shown
next to the label in `mode="label"`; `0`, the default, renders no size), `label`, `decorative`,
`mode: LyraFileIconMode = 'icon' | 'label'` (invalid values normalize to `icon`), and
`registry: LyraFileTypeMetadataRegistry` (property-only, defaulting to the immutable built-in
registry). A host `aria-label` wins over the computed localized file-type/size name. `decorative`
changes the semantic owner to presentation and renders `aria-hidden="true"` explicitly.

**Renamed in 8.0.0 — breaking:** the byte count is `bytes`, not `size`. Everywhere else in this
library `size` names a tier on the shared size ladder, and a numeric byte count answering to the
same property name is a collision a consumer only discovers at runtime. A leftover `size="245000"`
is an unknown attribute now: `bytes` stays `0` and the badge silently renders without a size.

**CSS parts:** `base`, `icon`, `label`, `description` (consumer-authored registry metadata in label
mode), and `size` (the part keeps its name — it is the rendered size _text_, and renaming a part
would break shipped `::part()` rules for no gain).

**Themeable custom properties:** `--lr-file-icon-size` (default `var(--lr-size-2rem)` — the
format badge's inline and block size). `--lr-file-icon-bg` (default `var(--lr-color-brand-quiet)`)
and `--lr-file-icon-color` (default `var(--lr-color-brand)`) retint the `icon` badge — every file
category renders the same fill today, so either can be set without hijacking the shared
`--lr-color-brand-quiet`/`--lr-color-brand` tokens used elsewhere in the theme.

**Exports:** `LyraFileTypeMetadata`, `LyraFileTypeMetadataEntry`, `LyraResolvedFileTypeMetadata`,
`LyraFileTypeMetadataRegistry`, `LyraFileTypeIcon`, `LyraFileTypeCategory`,
`createFileTypeMetadataRegistry(entries)`, `defaultFileTypeMetadataRegistry`, and the compatibility
lookup `getFileTypeMetadata()`. Registries validate and deeply snapshot records, use deterministic
longest registered-suffix matching (including multi-dot/punctuation suffixes), and isolate custom
mappings per instance instead of mutating module-global state. Consumer labels/descriptions remain
verbatim; built-in labels route through localization.

```html
<lr-file-icon
  mime-type="application/pdf"
  mode="label"
  bytes="245000"
></lr-file-icon>
```

## `lr-media-card`

A lightweight inline preview for one already-sent, already-available attachment inside a rendered
chat message body — distinct from `lr-document-preview` (a fuller viewer with an async
server-side-conversion state machine) and `lr-attachment-chip` (a pre-send queued-file chip with
upload progress). This component has neither concern; it only ever shows a `src` that's already
final.

Removing `mime-type` consumes the hint as absent and restores generic file detection unless `kind`
explicitly selects a format. Property readback stays `null`; an explicit empty hint remains empty
and later MIME values restore detection.

**Properties:**

- `src: string = ''` — the media URL. Always re-validated against a safe-scheme allowlist before
  use (see below) — never trust it unsanitized even though it's typed as a plain string.
- `kind?: LyraMediaCardKind` (`'image' | 'video' | 'file'`, reflected) — explicit format dispatch. Leave unset to
  auto-detect from `mimeType`.
- `mimeType: string = ''` (attribute `mime-type`) — drives auto-detection when `kind` is unset.
- `filename: string = ''` — shown in the file-chip fallback, used as the download link's suggested
  filename, and folded into the accessible name.
- `alt?: string` — alt text for the image case (and reused as a video label fallback). Unset falls
  back to `filename`, then a generic per-kind description. An explicit `alt=""` survives to the
  rendered `<img alt="">`, which is the HTML idiom for a decorative image — same contract as
  `<lr-image-viewer>` and `<lr-document-preview>`. The `<video>` case is deliberately outside that
  carve-out: an empty `alt` there still falls through to `filename`/the generic description, because
  an empty accessible name would leave an interactive player unnamed rather than mark it decorative.
- `accessibleLabel: string | null = null` (attribute `aria-label`) — a declarative attribute names
  the host as a whole while its nested button/link keeps a purpose-specific localized action name. A property-only assignment names the nested action and updates reactively when no host label is present, without creating a host attribute. An explicit
  empty string behaves like the unset `null` default — both fall through to the generated
  purpose-specific name. Image alt text and the native video's own purpose label remain independent;
  an explicitly empty host still leaves every interactive descendant named.
- `maxHeight: string = ''` (attribute `max-height`) — a CSS length (e.g. `"16rem"`); once set,
  overrides the `--lr-media-card-max-height` custom property for this instance only (applied
  inline on `[part="base"]`, so it reliably wins over a `:host{}`-declared default from outside the
  shadow root) — same contract as `<lr-document-preview>`'s identically-named prop. Values that do
  not parse as CSS `max-height`, contain declaration breaks, or contain `url()` are ignored, leaving
  the stylesheet token in control.
- `frame: LyraFrame = 'card'` (reflected) — container treatment, on the library-wide `frame`
  vocabulary. `'card'` (the default) keeps the bordered, filled box. `'plain'` removes
  `[part="base"]`'s border, background, padding, and corner radius, so a card inside a dense chat
  transcript (or any container already drawing its own separation between attachments) doesn't
  double the frame.
- `disabled: boolean = false` (reflected) — turns off this card's OWN action. The `kind="image"`
  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()`
  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
  unsafe-`src` file chip has no action at all, so `disabled` leaves it unchanged. Not
  form-associated, so an ancestor `<fieldset disabled>` does not cascade here. The disabled paint
  keys off the state each element already carries — `::part(base):disabled` and
  `::part(open-button):disabled` restyle the two buttons from outside; the file chip's anchor has no
  such pseudo-class, so target it through the reflected host attribute
  (`lr-media-card[disabled]::part(base)`).
- `aria-pressed` and `aria-current` (attributes only) — forwarded reactively onto whichever native
  control carries this card's action, the same mechanism `<lr-button>`/`<lr-icon-button>` use.
  `aria-pressed` accepts `'true' | 'false' | 'mixed'` and reaches BUTTONS only (`kind="image"`'s
  `base` and `kind="video"`'s `open-button`) — the file chip's anchor never receives it, because
  `link` has no pressed state. The global `aria-current` accepts `'page' | 'step' | 'location' |
  'date' | 'time' | 'true' | 'false'` and reaches every kind, anchor included. Anything outside
  those sets is dropped rather than passed through.

**Renamed in 8.0.0 — breaking:** this was `appearance`. Library-wide, `appearance` now means only
"how a control fills itself" and `frame` means "whether a container draws itself as a bounded card";
this property was always the second. There is no alias — `appearance` on `<lr-media-card>` is simply
an unknown attribute now, so a card left on `appearance="plain"` silently renders the full card
chrome again.

**Authoring types:** `LyraMediaCardKind` and `LyraMediaCardOpenDetail`; `frame` uses the shared
`LyraFrame` directly. The former `MediaCardKind`, `MediaCardOpenDetail`, and `MediaCardFrame`
names are removed in v9 rather than retained as aliases. URL validators are implementation details,
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
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
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,
truthful names.
Native `focus` and `blur` are each relayed once from the current primary action as bubbling,
composed `FocusEvent`s whose target is the `lr-media-card` host.

**Methods:** `focus(options?)`, `blur()`, and `click()` forward to the primary action for the
current media kind. The forwarded focus/blur transition produces the relayed host event described
above.

**Slots:** none.

**CSS parts:** `base` (a `<button>` for `kind="image"`, a plain wrapper `<div>` for `kind="video"`,
an `<a>` or `<span>` for the file-chip fallback depending on href safety), `media` (the `<img>`/
`<video>`), `file-icon`, `filename` (file-chip fallback only), `open-button` (video only — see
below).

**Themeable custom properties:** `--lr-media-card-max-height` (default `var(--lr-size-20rem)` — caps `[part="media"]`'s
block-size so one oversized image/video can't blow out a chat bubble; same naming/contract as
`<lr-document-preview>`'s identical `--lr-document-preview-max-height`; override per-instance via
the `max-height` attribute instead of this property directly).
`--lr-media-card-bg` (default `var(--lr-color-surface)`) retints the RESTING `frame="card"`
chrome — the companion to the pressed state's `--lr-media-card-active-bg` below, and the tier a
card sits at all day; `frame="plain"` still drops the fill entirely.
`--lr-media-card-active-border-color` (default
`color-mix(in oklab, var(--lr-color-brand), var(--lr-color-mix-partner) var(--lr-color-mix-active))`)
and `--lr-media-card-active-bg` (default
`color-mix(in oklab, var(--lr-media-card-bg, var(--lr-color-surface)), var(--lr-color-mix-partner) var(--lr-color-mix-active))`)
independently retint only a pressed image/file action; the pressed default mixes from
`--lr-media-card-bg`, so retinting the resting card carries the pressed state with it. Both are inline `var()` fallbacks in the
pressed state, so values on a chat or attachment-list ancestor inherit into every card rather than
being shadowed by host defaults. Plus shared tokens
`--lr-space-xs`/`-s`, `--lr-color-border`, `--lr-color-surface`, `--lr-color-text`/`-text-quiet`,
`--lr-color-brand` (hover border), `--lr-radius`, `--lr-icon-button-size` (video's `open-button`
sizing), `--lr-focus-ring-*`, `--lr-transition-fast`.

**Optional peer deps:** none.

```html
<lr-media-card
  id="image-card"
  kind="image"
  src="https://example.com/photo.jpg"
  alt="Screenshot"
  filename="photo.jpg"
></lr-media-card>
<lr-media-card id="file-card" kind="file" src="https://example.com/report.pdf" filename="report.pdf">
</lr-media-card>
<script type="module">
  document
    .getElementById("image-card")
    .addEventListener("lr-media-open", (e) => openLightbox(e.detail.src));
  document
    .getElementById("file-card")
    .addEventListener("lr-before-media-download", (e) => shouldUseNativeDownload || e.preventDefault());
</script>
```

**Safe-URL checking.** `src` is validated by internal sink-specific helpers before it's
ever assigned to an `<img>`/`<video>` `src` or an `<a href>` — only `http:`/`https:`/`blob:` (plus
`data:` for a _media_ `src` only) or a scheme-relative/relative URL with no scheme at all pass;
anything else (`javascript:`, `vbscript:`, and similarly suspicious schemes) is rejected. `data:` is
allowed for a media source (a browser never executes script from a media element's `src`) but
rejected by the stricter link validator (a `data:text/html` URI navigated to via a clicked `<a
href>` runs as a full document and can execute script) — the same scheme gets a different verdict
depending on which DOM sink it's headed for. Both validators delegate to the platform's own `new
URL()` parser rather than a hand-rolled scheme regex, specifically because `new URL()` already
implements the WHATWG URL Standard's input normalization (stripping tab/newline/leading-trailing
space before looking for a scheme) — a naive regex is vulnerable to exactly the kind of
tab-injected-into-a-scheme bypass a browser attribute sink still normalizes and executes. An
`image`/`video` `kind` whose `src` fails the media-src check falls back to the generic file-chip
rendering, which then separately re-validates `src` against the stricter href allowlist for its own
download affordance.

`kind="video"` renders its open affordance as a separate `[part="open-button"]` next to
`[part="media"]` rather than wrapping the whole card in one `<button>`/`<a>` (the pattern
`image`/`file` use) — a `<video controls>` element is itself interactive content, and HTML forbids
nesting interactive content inside a `<button>`/`<a>`; doing so anyway would also make every click on
the video's own native controls bubble up and spuriously fire `lr-media-open`.

**Known gotchas:**

- `kind` only reflects to the host attribute when explicitly set — CSS keying off the
  auto-detected resolved kind should target the rendered `[part]`/element (e.g. `video[part="media"]`),
  not `:host([kind=...])`, since the latter won't see an auto-detected kind.

---

## `lr-attachment-trigger`

A compact attach affordance designed for a chat composer's start slot (see `lr-chat-composer`'s
own `start` slot, which this drops straight into, though it has no code dependency on it). First-
party invention (no Web Awesome equivalent). Its shape adapts to how many attachment `capabilities`
are configured: exactly one renders a single plain icon button; more than one renders a small
anchored menu (composed from `lr-dropdown`/`lr-menu`/`lr-menu-item`) listing each
capability as a row.

**Properties:**

- `capabilities: readonly LyraAttachmentCapability[] = ['files']` (property only, no attribute) —
  which capabilities to offer, in display order. `LyraAttachmentCapability = 'files' | 'image' |
'camera' | 'audio'`; `LyraFileBackedCapability = 'files' | 'image'` (the two that actually open
  the file picker). Writes inspect at most the first 64 candidates and normalize to a frozen,
  deduplicated, at-most-four entry snapshot. Unknown values and duplicates do not consume that
  four-entry output budget; hostile/invalid collections fail closed to the default.
- `accept: string = ''` — a native-file-input-style accept string (e.g. `'image/*'` or
  `'.pdf,.docx'`), forwarded to the hidden file input for the `files`/`image` capabilities. `image`
  defaults it to `'image/*'` unless this prop overrides it; `files` always uses it as-is (empty
  means "any file type").
- `multiple: boolean = true` (reflected) — forwarded to the hidden file input's own `multiple`
  attribute.
- `disabled: boolean = false` (reflected)
- `accessibleLabel?: string` (attribute `accessible-label`) — overrides either trigger shape's
  localized accessible-name fallback. A host `aria-label`, including explicit empty, wins.
- `triggerTitle?: string` (attribute `trigger-title`) — forwards a sighted-user hover tooltip to
  both the single-capability and multi-capability trigger buttons
- `appearance: LyraAppearance = 'plain'` (reflected) — how the trigger fills itself, from the
  library's shared `accent`/`filled`/`outlined`/`filled-outlined`/`plain` vocabulary. `'plain'` is
  exactly the treatment this component shipped before it had the property
- `size: LyraSize = 'm'` (reflected) — size on the shared six-step ladder, accepting the
  `small`/`medium`/`large` spellings too. The tier scales the **glyph**, never the tappable box:
  `--lr-icon-button-size` is an accessibility floor and the ladder's tightest steps resolve below
  WCAG 2.5.8's minimum. Override `--lr-icon-button-size` to make that trade-off explicitly

**Events:** `lr-files` (`detail: { capability: 'files' | 'image'; files: readonly File[] }`) — fired
once a file-backed capability's hidden input produces a real selection. `files` is a fresh frozen
owner-realm array snapshot, not a live reference to the input's own `.files`. `lr-camera-request`
and `lr-audio-request`
(both no detail — `detail` is `null`, not `undefined`, per the DOM spec's `CustomEventInit`
default) — fired when the `camera` / `audio` capability is activated; this component implements no
capture UI of its own, the host owns everything from here (there's no single right answer for
`getUserMedia` vs. `<input capture>` vs. a native wrapper's own camera API; for `audio` the
typical host response is opening `<lr-push-to-talk>` in an overlay, then handing the resulting
blob to `<lr-attachment-chip>`). `focus`/`blur` from the active single- or multi-capability trigger
are relayed exactly once as owner-realm native `FocusEvent`s (bubbling and composed, preserving
`relatedTarget`); the hidden file input is not the focus owner.
The composed dropdown/menu implementation lifecycle, item-state, and selection events are
contained inside the trigger. Only the attachment events listed above cross the host boundary.

**Slots:** none — capabilities are configured entirely via the `capabilities` prop.

**CSS parts:** `trigger` (the single-capability button, only rendered when
`capabilities.length === 1`), `menu` (the `lr-dropdown` shell, only rendered when
`capabilities.length > 1`), `menu-trigger` (the multi-capability button slotted into `lr-dropdown`'s
`trigger` slot, only rendered when `capabilities.length > 1`), `expand-icon` (the disclosure chevron
inside the multi-capability trigger button, only rendered when `capabilities.length > 1`),
`trigger__control` / `menu-trigger__control` (each trigger's own native `<button>` — as of 16.0.0
both triggers are composed `<lr-icon-button>`s, so `trigger`/`menu-trigger` name those hosts and the
painted surface sits one boundary deeper),
`hidden-input` (the internal native `<input type="file">` that actually opens the OS file picker;
hidden via CSS by default, exposed as a part only so a consumer can override that with
`::part(hidden-input)` in the unlikely case their integration needs to).

**Migrating a pre-16.0.0 `::part()` rule.** This component's icon-only action is a composed
`<lr-icon-button>`, so the part naming that action now names the composed child's HOST, which
paints nothing. A `border`, `background` or `border-radius` set on it is silently dead — only
`color` still appears to work, because it inherits, which makes such a rule look half-alive rather
than broken. Set `--lr-icon-button-background`/`-color`/`-border`/`-radius` (and their
`-hover`/`-active` variants) on this element or an ancestor instead: the composed control reads
those public tokens ahead of any default this component supplies. For SIZE use
`--lr-theme-icon-button-size`, not `--lr-icon-button-size` — every `LyraElement` re-declares the
latter on its own `:host`, so it never reaches a composed child (see `llms/tokens.md`).

**An ancestor's public border wins over this component's own relayed default, not just its
absence.** Unlike most composing components, the `outlined`/`filled-outlined` appearances here DO
relay a non-zero `--_lr-icon-button-border-default` (a themed edge) into the trigger's private
fallback tier. That does not change the resolution order: `--lr-icon-button-border` (and its
`-hover`/`-active` variants) is still the FIRST arm of the token chain, read by the composed
trigger ahead of whatever this component relays, so setting it on this element or an ancestor
overrides the outlined edge exactly as it overrides the `plain`/`filled`/`accent` appearances'
zero default. The private relay is only this component's own default opinion, never a gate the
public token must pass through. Size remains the one exception that does not cross this way: use
`--lr-theme-icon-button-size`, never `--lr-icon-button-size`, as noted above.

**Themeable custom properties:** shared tokens only — `--lr-space-xs`, `--lr-color-text`/
`-text-quiet`, `--lr-icon-button-size`, `--lr-focus-ring-*`, `--lr-opacity-disabled`,
`--lr-radius`, `--lr-transition-fast`.

**Optional peer deps:** none.

```html
<lr-attachment-trigger accept=".pdf,.docx"></lr-attachment-trigger>
<script type="module">
  const trigger = document.querySelector("lr-attachment-trigger");
  trigger.capabilities = ["files", "image", "camera"];
  trigger.addEventListener("lr-files", (e) => queueFiles(e.detail.capability, e.detail.files));
  trigger.addEventListener("lr-camera-request", openCameraFlow);
</script>
```

**Known gotchas:**

- `HTMLInputElement.files` is a _live_ view in most browsers — clearing `input.value` after reading
  `.files` (needed so re-picking the exact same file still fires another `change` event next time)
  mutates that exact `FileList` object back to empty in place, not just detaches a stale reference.
  A consumer reading `lr-files` later would otherwise observe an empty list — this component
  copies into a fresh frozen `File[]` before clearing the native input.
- The `camera`/`audio` capabilities never touch the hidden `<input type="file">` at all — both are
  scope-limited by design to firing `lr-camera-request`/`lr-audio-request` and nothing else. The
  hidden input is only rendered when `capabilities` contains `files` or `image`.
- Setting `disabled` closes an open capability menu, disables its items as well as the trigger, and
  discards a native file selection that arrives after the component became disabled.

**Additional API surface:**

- `click()` — Activates the internal attachment trigger.

---

## `lr-avatar`

A small, fixed-size identity marker: an image, an `icon`-slotted fallback glyph, or initials — in
that priority order. Mirrors `wa-avatar` / `sl-avatar` (`image`, `initials`, `loading`, `shape`, the
named `icon` slot, label and image-load error event) and adds this library's shared `size` and
`variant` vocabulary. Purely presentational, with no built-in interactivity; wrap it in a
`<button>`/`<lr-menu>` trigger for a user-menu affordance.

Removing the attribute consumes the label as absent while preserving its `null` property readback.
Explicit empty labels remain empty, host `aria-label` precedence remains intact, and later label
values restore the image or fallback name.

**Properties:**

- `initials: string = ''` — fallback text (typically 1-2 characters), shown whenever no glyph and no
  image is set, or the image fails to load and no `icon` slot content is provided.
- `image: string = ''` — image URL; takes priority over the `icon` slot and `initials` when set and
  loads successfully, falling back to them on a load
  error. **Renamed from `src` in 8.0.0** to match `wa-avatar`: a mechanical `wa-` → `lr-` rename
  used to leave the property unset, so a migrated avatar silently dropped its photo and rendered
  initials instead.
- `label: string = ''` — upstream-compatible accessible description. A host `aria-label` wins.
  The same resolved name reaches the image `alt` and every fallback tier.
- host `aria-label` — overrides `label` as the image/fallback accessible name without changing the
  visible initials or image
- `loading: 'eager' | 'lazy' = 'eager'` (new in 8.0.0) — passthrough to the rendered `<img>`'s
  native `loading` attribute. `'lazy'` defers the request until the avatar approaches the viewport,
  which is worth setting for avatars far down a long list and never for one above the fold. It only
  reaches the DOM while the image tier is the one rendering; the default matches the native default,
  so an avatar that never sets it behaves exactly as it did before the property existed.
- `size: LyraSize = 'medium'` (reflected) — `'2xs' | 'xs' | 's' | 'm' | 'l' | 'xl' |
'small' | 'medium' | 'large'`. Every tier renders a distinct diameter: 1.5rem (`2xs`), 2rem
  (`xs`), 2.5rem (`s`/`small`), 3rem (`m`/`medium`, the mirrored default), 4rem (`l`/`large`,
  matching `--lr-icon-button-size`), and 5rem (`xl`). Invalid and removed `sm`/`md`/`lg` writes
  normalize to `medium`.
- `shape: 'circle' | 'rounded' | 'square' = 'circle'` (reflected) — three distinct corner radii:
  `circle` (the pill radius), `rounded` (the shared `--lr-radius`), `square` (no radius at all).
  **`rounded` is new in 8.0.0.**
- `variant: 'neutral' | 'brand' | 'success' | 'warning' | 'danger' = 'neutral'` (reflected) —
  recolors the initials-fallback background/text on the library's one semantic-tone vocabulary;
  `neutral` (the default) reads as a plain, unaccented circle. **Renamed from `tone` in 8.0.0**,
  with no alias: `tone="brand"` is an unknown attribute now and renders the neutral circle.

**Events:** `lr-error` (`detail: { image: string }`, new in 8.0.0) — the image failed to load;
`detail.image` carries the URL that failed, so a consumer can retry or report it. Bubbling,
composed, non-cancelable, and purely informational: by the time it fires the avatar has already
fallen back to the `icon` slot or the initials on its own. It never fires for an avatar with no
`image` set, and fires once more for each replacement `image` that also fails.

**Slots:** `icon` — a
fallback glyph shown only when there is no loadable `image`; that is
the role `wa-avatar`'s `icon` slot fills, a stand-in for the `initials` text rather than an override
of the photo. Its content is decorative (`aria-hidden`) — set `label` alongside it for an
accessible name. There is no default slot.

**CSS parts:** `base` (the outer circle/rounded/square container), `icon` (wrapper around the named
fallback slot while it is the winning tier), `image` (the `<img>`, only while a safe, non-failed
`image` is usable), and `initials` (only once the image and icon tiers are unavailable).

**Themeable custom properties:** `--size` is the upstream-compatible diameter and falls back to
`--lr-avatar-size` (default `var(--lr-size-3rem)`, with a private default stepped across the ladder
from `var(--lr-size-1-5rem)` at `2xs` to `var(--lr-size-5rem)` at `xl`), `--lr-avatar-bg` (default
`var(--lr-color-border)`, whose private default changes for a non-neutral `variant` to that
variant's `-quiet` fill; there is no `--lr-color-surface-alt` token in this library, despite what
older copies of this page claimed), `--lr-avatar-color` (default `var(--lr-color-text)`, whose
private default changes for a non-neutral `variant` to that variant's loud color),
`--lr-avatar-font-size` (default `var(--lr-font-size-m)`) — the font size of the initials fallback,
and of any `em`-sized slotted glyph. Its private default follows `size` alongside the diameter
(`--lr-font-size-xs` at `2xs`, `--lr-font-size-sm` at `xs`, `--lr-font-size-md-sm` at `s`,
`--lr-font-size-m` at `m`, `--lr-font-size-lg` at `l`, and `--lr-font-size-xl` at `xl`), so the
initials track the circle instead of staying one fixed size across every tier. Every public value
above can be inherited from an ancestor or set directly on the avatar and remains authoritative
across size/variant states. Plus shared tokens
`--lr-radius`/`-pill`, `--lr-font-weight-semibold`.

The variant colors are deliberately **not** the library's generic quiet-fill/on-quiet-text pairing:
an avatar's initials _are_ the accent, so they read in the variant's own loud color on that
variant's quiet tint.

**Optional peer deps:** none.

```html
<lr-avatar initials="JS" variant="brand"></lr-avatar>
<lr-avatar image="/users/42/photo.jpg" label="Jane Smith" size="large" shape="rounded"></lr-avatar>
<lr-avatar label="Assistant"><svg slot="icon" viewBox="0 0 24 24"><!-- role glyph --></svg></lr-avatar>

<!-- Far down a long list: defer the request, fall back to a glyph, and report a broken URL. -->
<lr-avatar id="lazy-avatar" image="/users/7/photo.jpg" label="Ada Lovelace" loading="lazy">
  <svg slot="icon" viewBox="0 0 24 24"><!-- fallback glyph --></svg>
</lr-avatar>
<script type="module">
  document
    .getElementById("lazy-avatar")
    .addEventListener("lr-error", (e) => reportBrokenAvatar(e.detail.image));
</script>
```

**Known gotchas:**

- additive `alt`, default glyph content and `sm`/`md`/`lg` aliases were removed for exact mirrored
  vocabulary: migrate `alt→label`, default glyph content to `slot="icon"`, and size aliases to
  `small`/`medium`/`large`. The older `src→image` and `tone→variant` migrations still apply.
- an image load failure falls back to the `icon` slot when it has content, otherwise to `initials`.
  Changing `image` clears the failure state so the replacement URL gets its own load attempt,
  including when a later transition returns to a URL that failed previously.
- when `label` or host `aria-label` supplies a name, the base preserves that name through the glyph
  and initials fallbacks while hiding duplicate initials text from assistive technology.
- the `icon` slot yields to a loadable `image` and becomes the fallback if the image fails.

---

## `lr-animated-image`

An animated GIF/APNG/WebP with a play/pause control, frozen to a captured still frame at rest and
automatically under `prefers-reduced-motion: reduce`.

**Properties:**

- `src: string = ''` — re-validated through `safeMediaSrc()` (same allowlist as `lr-media-card`)
  before reaching the real `<img src>`.
- `alt?: string` — forwarded to the live image and frozen canvas. An absent or explicitly empty
  value keeps both visual owners decorative; a nonempty value names whichever one is exposed. The
  independent play/pause action still uses localized context when no nonempty `alt` is available.
- `play: boolean = false` — the caller's _intent_ (reflected).
- `playing: boolean` (readonly getter, reflected as a `playing` host attribute) — the _effective_
  state after reduced-motion arbitration: `play && !(respectReducedMotion && <OS prefers reduce>)`.
  It is a genuine getter-only property, so assigning to it from a strict JavaScript module throws a
  `TypeError`; drive playback via `play`.
- `respectReducedMotion: boolean = true` (reflected, attribute `respect-reduced-motion`) — while
  `true` and the OS reports `prefers-reduced-motion: reduce`, playback stays frozen and
  `[part="play-button"]` is `disabled` regardless of `play`.
- `accessibleLabel: string = ''` (attribute `aria-label`) — when the host attribute is present,
  including explicitly empty, it overrides `[part="play-button"]`'s computed Play/Pause label
  verbatim in _both_ states (it does not itself vary by state). Never
  touches the image's `alt`/the canvas's `aria-label`. For state-sensitive custom wording, override
  the `playWithContext`/`pauseWithContext`/`animatedImageDefaultAlt` strings instead.

**Methods:** `focus(options?)` and `blur()` forward to the play/pause button.

**Events:** `lr-load` (the live `<img>` loaded; fires again on every successful `src` change),
`lr-error` (native decode failure, or a non-empty `src` that failed the safe-URL check — never for
an empty `src`), `lr-play`/`lr-pause` (real transitions of the effective `playing` value only, so a
`play = true` that reduced motion blocks emits nothing, while a live reduced-motion change that
forces a freeze does emit `lr-pause`). Internal `focus`/`blur` are relayed exactly once as
owner-realm native `FocusEvent`s (bubbling and composed, preserving `relatedTarget`).

**Slots:** `play-icon`, `pause-icon` — decorative custom glyphs for the frozen/paused and playing
states. Both stay mounted and are toggled via the native `hidden` attribute. Their assigned content
renders in an inert, `aria-hidden`, pointer-transparent sibling layer over the named play/pause
button, so do not use either slot for a second interactive control.

**CSS parts:** `base` (positioning context), `image` (the live `<img>`), `canvas` (the
frozen-frame `<canvas>`, shown in place of `image` while not playing), `control-box` (the
backgrounded circle around the button; only rendered once loaded and error-free), `play-button`.

**Themeable custom properties:** upstream `--control-box-size` and `--icon-size` feed
`--lr-animated-image-control-box-size` (default
`var(--lr-icon-button-size)`), `--lr-animated-image-icon-size` (default
`calc(var(--lr-icon-button-size) * 0.35)`), `--lr-animated-image-max-height` (default
`var(--lr-size-20rem)` — caps the rendered media's block-size, same contract as
`--lr-media-card-max-height`).

**Optional peer deps:** none.

**Known gotchas:**

- the freeze frame is captured once per successful `src` load, in the `<img>`'s own `load` handler
  (a DPR-aware `drawImage()`), not re-captured on each pause — pausing always reverts to that first
  frame, never to the frame that was on screen.
- both `image` and `canvas` stay mounted at all times (never `display: none`/removed) so the
  browser's native decode loop keeps running while visually covered; only opacity and `aria-hidden`
  swap.
- reduced-motion arbitration is re-evaluated on every reconnect, so a preference change made while
  the element was detached cannot leave `playing` stale.

**Additional API surface:**

- `click()` — Activate the play/pause control.

## `lr-animation`

Declaratively animates one slotted element through the native Web Animations API.

An initial playing mount creates one native animation and emits one `lr-start`. A real target or
timing change still rebuilds the animation, while replay and reconnect retain their normal
start/finish lifecycle, including reduced motion.

**Properties:**

- `name: string = 'none'` — accepts any animation registry name. The built-in names are `'none' |
'fade-in' | 'fade-out' | 'zoom-in' | 'zoom-out' | 'slide-in-start' | 'slide-in-end' |
'slide-out-start' | 'slide-out-end' | 'slide-in-up' | 'slide-in-down' | 'bounce' | 'pulse' |
'spin' | 'shake'`; `LyraAnimationPreset` remains the exported convenience type for that built-in
  subset. Other strings resolve through the registry key `animation.<name>`. The four built-in
  `-start`/`-end` slide presets are logical: "start" is physically left under `ltr`, right under
  `rtl`.
- `keyframes?: Keyframe[]` (attribute: false) — raw WAAPI keyframes; always wins over `name`.
- `play: boolean = false` (reflected) — playback intent.
- `delay: number = 0`, `duration: number = 1000`, `endDelay: number = 0` (attribute `end-delay`),
  `easing: string = 'linear'`, `fill: FillMode = 'auto'`, `direction: PlaybackDirection = 'normal'`,
  `iterations: number = Infinity`, `iterationStart: number = 0` (attribute `iteration-start`),
  `playbackRate: number = 1` (attribute `playback-rate`) — straight WAAPI timing. `direction` is
  the WAAPI `PlaybackDirection`, unrelated to text direction; `iterations` is always numeric.
- `timingPreset: LyraAnimationTimingPreset = 'custom'` (attribute `timing-preset`, reflected) —
  `'custom' | 'fast' | 'base' | 'ambient'`. Anything other than `'custom'` derives `duration` and
  `easing` from the matching `--lr-transition-*` token (read off computed style and decomposed into
  the numeric ms + easing string WAAPI needs), ignoring the `duration`/`easing` properties.
- `respectReducedMotion: boolean = true` (attribute `respect-reduced-motion`, reflected) — under
  `prefers-reduced-motion: reduce`, caps playback at one iteration and calls `finish()` immediately
  instead of playing, so the target snaps to its resolved end state; `lr-start`/`lr-finish` still
  fire in order.
- `playOnVisible: boolean = false` (attribute `play-on-visible`, reflected) — starts playback via
  `IntersectionObserver` once the target intersects. `playOnVisibleRepeat: boolean = false`
  (attribute `play-on-visible-repeat`, reflected) — re-plays on each re-entry and pauses on exit;
  when unset the observer disconnects after the first trigger. `root: Element | null = null` and
  `threshold: number | readonly number[] = 0` (both attribute: false) plus
  `rootMargin: string = '0px'` (attribute `root-margin`) configure that observer. Threshold arrays
  are frozen snapshots, retain only finite values from 0 through 1, and inspect at most 1,000
  candidates per assignment; invalid scalar thresholds normalize to `0`.
- `currentTime: CSSNumberish` — the underlying `Animation.currentTime` (`0` when no animation
  exists); writable and forwarded when one exists. Non-finite numeric assignments are ignored.

**Methods:** `start()` (sugar for `play = true` — named `start` because `play` is already a
property), `pause()` (`play = false`), `finish()`, `cancel()`. `cancel()` leaves the target reverted
to its own CSS: the `play = false` that the resulting `lr-cancel` sets never re-pauses the now-idle
`Animation`, which per the Web Animations API would un-cancel it back to keyframe zero and freeze the
target there.

**Events:** `lr-start` (a new animation was created and playback began/restarted), `lr-finish`
(natural end, including the reduced-motion instant-finish path), `lr-cancel` (the public `cancel()`
method or external cancellation). `lr-finish`/`lr-cancel` both reset `play` to `false`.

**Slots:** default slot — the element to animate. A second slotted element is accepted without
error but ignored.

**CSS parts:** none (`:host { display: contents }`; the animated element is light-DOM content).

**Themeable custom properties:** `--lr-animation-slide-distance` (default `100%` — travel distance
for the slide presets), `--lr-animation-zoom-scale` (default `0.5` — start/end scale for
`zoom-in`/`zoom-out`), `--lr-animation-bounce-height` (default `25%` — peak lift of `bounce`),
`--lr-animation-shake-distance` (default `4%` — horizontal travel of `shake`).

**Animation registry:** every named preset resolves the public registry key
`animation.<name>` before using its built-in keyframes. A per-element `setAnimation()` registration
wins over `setDefaultAnimation()`; a keyframes-only registration retains this component's
property- or token-derived timing, and `rtlKeyframes` is selected from the live inherited text
direction. Both setters return an idempotent cleanup. Passing `null` disables interpolation but
still emits `lr-start` then `lr-finish`, so code sequencing work from the lifecycle does not stall.
Direct `keyframes` property input remains the strongest, instance-local override and does not use a
registry name. Register an override before the first render when creating an animation
programmatically. For an already-rendered `<lr-animation>`, the override is selected on its next
normal rebuild (a keyframe/timing/direction change or reconnect); the registry never mutates a
native timeline that is already running.

```js
import "@aceshooting/lyra-ui/components/media/animation/animation.js";
import { setAnimation } from "@aceshooting/lyra-ui/utilities/animation-registry.js";

const animation = document.createElement("lr-animation");
animation.name = "slide-in-start";
animation.iterations = 1;
animation.innerHTML = "<span>Registry-controlled content</span>";
const release = setAnimation(animation, "animation.slide-in-start", {
  keyframes: [
    { transform: "translateX(calc(-1 * var(--lr-size-2rem)))" },
    { transform: "translateX(0)" },
  ],
  rtlKeyframes: [
    { transform: "translateX(var(--lr-size-2rem))" },
    { transform: "translateX(0)" },
  ],
});
document.body.append(animation);
animation.start();
// release() restores the previous registration.
```

**Optional peer deps:** none.

**Known gotchas:**

- `iterations` defaults to `Infinity` (mirrors the upstream Web Awesome/Shoelace contract) — a named
  preset plays forever unless you set `iterations="1"`.
- changing any timing/keyframe property rebuilds the animation from scratch; the rebuild's internal
  `cancel()` is deliberately silent (no `lr-cancel`), only the public `cancel()` emits.
- the slide presets re-resolve when an inherited text-direction change is observed. The old native
  animation is replaced rather than mirrored in place, so its timeline restarts from the new edge.
- reduced-motion handling is entirely in JS; the shared shadow-DOM reduced-motion CSS block can't
  reach light-DOM slotted content driven by `Element.animate()`.

## `lr-avatar-group`

Stacks slotted `<lr-avatar>` children into one overlapping row and, past `max`, collapses the
excess into a localized "+N" badge. Composed over `<lr-avatar>` via plain light-DOM slotted content
(no `.items` array); it does **not** import/register `<lr-avatar>` — the consumer does that.

**Properties:**

- `max?: number` — how many assigned children stay visible before the rest collapse behind the
  badge. Unset (the default) means no limit. Any assigned value is sanitized to a finite,
  non-negative integer. Flattened slot-forwarded children count the same as direct children.
- `size: LyraSize = 'medium'` (reflected) — reused from `<lr-avatar>`'s canonical six-step ladder.
- `shape: LyraAvatarShape = 'circle'` (reflected) — `'circle' | 'rounded' | 'square'`.
- `variant: LyraVariant = 'neutral'` (reflected) — `'neutral' | 'brand' | 'success' | 'warning' |
'danger'`.

`size`/`shape`/`variant` style the overflow badge and provide defaults only to assigned avatars
that omit the corresponding attribute. Explicit child attributes remain authoritative; owned
defaults are restored without overwriting later author writes across removal, reparenting,
disconnect and reconnect.

- `label: string = ''` — the group's `role="group"` accessible name. A host-level `aria-label` wins
  if both are set; with neither, no `aria-label` is rendered.

**Events:** `lr-overflow-click` (frozen
`detail: { readonly hiddenCount: number; readonly hiddenAvatars: readonly LyraAvatar[] }`) —
the badge was activated by click or Enter/Space. Non-cancelable, purely informational: the
component keeps rendering the same collapsed stack, and a host typically wires this to its own
popover/dialog listing the hidden members. There is no `expanded` state and no `aria-expanded`.

**Slots:** default slot — direct or forwarded `<lr-avatar>` elements. Other elements are ignored
and remain untouched. Author-hidden/inert avatars do not consume visible capacity. Excess eligible
avatars are hidden through reversible component-owned state.

**CSS parts:** `base` (the outer inline-flex container holding the slot and the badge),
`overflow-badge` (the 40px-minimum action surface; only rendered while `max` is actively
overflowing), and `overflow-badge-visual` (the avatar-tier-sized painted disc inside it).

**Themeable custom properties:** `--lr-avatar-group-avatar-size` (default `var(--lr-size-3rem)`,
with a private default stepped across the same six tiers as `<lr-avatar>`'s `--lr-avatar-size`,
from `var(--lr-size-1-5rem)` at `2xs`, through `var(--lr-size-2rem)`/
`var(--lr-size-2-5rem)`/`var(--lr-size-3rem)`/`var(--lr-size-4rem)`, to
`var(--lr-size-5rem)` at `xl`),
`--lr-avatar-group-overlap` (default `var(--lr-size-neg-6px)`, whose private default follows `size`;
a logical `margin-inline-start`, so it auto-mirrors
under `dir="rtl"` — setting `0` or a positive length turns the stack into normal spacing),
`--lr-avatar-group-ring-color` (default `var(--lr-color-surface)`),
`--lr-avatar-group-ring-width` (default `var(--lr-border-width-medium)`),
`--lr-avatar-group-badge-bg` (default `var(--lr-color-border)`, with a private default that follows
`variant`), `--lr-avatar-group-badge-color` (default `var(--lr-color-text)`, with a private default
that follows `variant`),
`--lr-avatar-group-badge-font-size` (default `var(--lr-font-size-m)`) — the font size of the "+N"
badge label. Its private default follows `size` alongside the badge diameter, matching
`<lr-avatar>`'s own `--lr-avatar-font-size` scale (`xs`/`sm`/`md-sm`/`m`/`lg`/`xl` font tokens from
the `2xs` through `xl` size tiers), so the badge and the avatars it caps read at the same optical
weight. An inherited or direct public value remains authoritative for every hook.

The overflow badge keeps a `--lr-icon-button-size` minimum activation target at every tier while
the nested visual disc stays exactly avatar-sized, so small tiers do not paint as oversized 40px
circles.

**Optional peer deps:** none.

```html
<lr-avatar-group max="3" label="Project members">
  <lr-avatar initials="JS"></lr-avatar>
  <lr-avatar initials="AM"></lr-avatar>
  <lr-avatar initials="RT"></lr-avatar>
  <lr-avatar initials="KL"></lr-avatar>
</lr-avatar-group>
```

**Known gotchas:**

- group defaults only fill omitted child attributes; they deliberately do not overwrite explicit
  heterogeneous child presentation.
- the row never wraps (`flex-wrap` stays `nowrap`) — wrapping an overlapping stack breaks the
  visual.
- avatars are non-interactive, so there is no roving tabindex / arrow-key handling; the badge is the
  only tab stop.

## `lr-lightbox`

A modal, full-screen image viewer with prev/next navigation, captions, and pan/zoom delegated to one
stable embedded `<lr-pan-zoom>`. It renders its own dialog panel (not a nested `<lr-dialog>`)
but shares the same overlay infrastructure as `<lr-dialog>`/`<lr-command-palette>` — stacking, focus
trap, Escape/backdrop dismissal, scroll lock, and focus return.

**Properties:**

- `open: boolean = false` (reflected) — post-render writes run the same cancelable lifecycle as
  `show()`/`hide()`/`close()`. Initial `open` markup is state and emits no lifecycle events.
- `images: readonly LyraLightboxImage[] = []` (attribute: false) —
  `LyraLightboxImage { readonly src: string; readonly alt?: string; readonly caption?: string }`.
  Assignment clones/freezes the records and inspects at most 10,000 candidates; malformed records
  are omitted and updates require a new collection assignment. `src` is passed to the embedded
  frame, which runs it through `safeMediaSrc()`. `alt`/`caption` are caller data, never localized.
- `index: number = 0` (reflected) — clamped defensively for rendering and silently re-synced (no
  event) when `images` shrinks.
- `loop: boolean = false` (reflected) — wraps prev/next past the ends.
- `lightDismiss: boolean = false` (attribute `light-dismiss`) — opt in to backdrop dismissal. Off by default, matching `lr-dialog`.
- `showCounter: boolean = true` (attribute `show-counter`, **not reflected**) — shows the visible
  `[part="counter"]`. `show-counter="false"` clears it from plain HTML (the attribute is parsed by
  literal string, not by presence, so a true-defaulting boolean can actually be turned off), and a
  `.showCounter=${false}` property binding does the same. Nothing is ever written back to the
  attribute — no stylesheet or selector keys off `[show-counter]`.
  Spoken position updates remain active when the counter is hidden: the shadow
  `[part="live-region"]` is only an `aria-hidden` text mirror, while announcements append to the
  shared light-DOM polite sink. Announcements stay silent when the lightbox or a composed ancestor
  is excluded from the accessibility tree.
- `minZoom: number = 0.5`, `maxZoom: number = 4`, `zoomStep: number = 0.25` (attributes `min-zoom`/
  `max-zoom`/`zoom-step`) — pure pass-throughs to the embedded `<lr-pan-zoom>`, which does the
  normalizing.
- `fit: LyraImageFit = 'actual'` (reflected) — opt-in base sizing policy for the current image,
  reusing `<lr-image-viewer>`'s `contain`/`width`/`actual` vocabulary. The default preserves the
  existing natural-size behavior. `contain` fits both landscape and tall images inside the stage;
  `width` fills its inline size. CSS recalculates either policy when the stage is resized or a
  delayed image source finishes loading, so navigation and opening do not require consumer timers.
  Fit is the base zoom policy: an explicit user zoom remains until navigation or a reset, and
  changing the theme does not mutate the lightbox's zoom property.
- `accessibleLabel: string | null = null` (attribute `aria-label`) — the panel's accessible name,
  overriding the localized `lightboxLabel`.

**Methods:** promise-based `show()`, `hide()`, and `close(reason?)`, plus `next()`, `previous()`, and
`goTo(index)`. `show()`/`hide()` resolve after the successful rendered transition; a veto resolves
without changing state. `goTo()` ignores a non-finite
index without changing state or emitting `lr-index-change`. A finite fractional index is truncated
toward zero before clamping or loop wrapping, so `lr-index-change.detail.index` is always the
actual rendered integer index; `reason` defaults to `'api'` and is forwarded as the close event's
detail.

**Events:** cancelable `lr-show`, followed after a successful open render by `lr-after-show`;
cancelable `lr-hide` (`detail: LyraLightboxHideDetail = { source: Element }`), then
`lr-lightbox-close` (`detail: LyraLightboxCloseReason = 'escape' | 'backdrop' |
'close-button' | 'api' | 'unmount' | (string & {})`; **cancelable** — `preventDefault()` blocks
closing on every path, including a consumer's own `close()` call), followed after a successful
closed render by `lr-after-hide`. Removal while open emits the settled non-vetoable
hide/close/after-hide order with reason `'unmount'`. `lr-index-change` (`detail: { index }`, fired
only for internally-driven navigation — a button, a keyboard shortcut, or `next()`/`previous()`/
`goTo()`; **not** when a consumer sets `index`/`images` directly); `lr-zoom-change` (`detail: {
zoom }`) is not emitted by the lightbox itself — it bubbles up composed from the embedded frame.

**Slots:** `actions` — extra toolbar buttons (download/share/delete), rendered in `[part="toolbar"]`
between the counter and the close button.

**CSS parts:** `backdrop`, `panel` (`role="dialog"` + `aria-modal="true"` while open; fills the
padded safe area rather than shrink-wrapping), `toolbar`, `counter` (visible localized "Image N of
Total"), `live-region` (an `aria-hidden` shadow text mirror; each post-mount `index` change,
including a consumer-driven one, appends the localized position to the document's shared
`[data-lr-live-region="polite"]` sink; initial mount and reconnect are silent), `actions` (wrapper,
`hidden` when nothing is slotted),
`close-button` (always rendered — unlike `<lr-dialog>`'s opt-in `closable`), `stage`, `frame` (the
embedded `<lr-pan-zoom>`), forwarded aliases `frame-viewport`, `frame-content`, `frame-controls`,
`previous-button`,
`previous-glyph`, `next-button`, `next-glyph`, `caption` (only when the current image has one; its
`id` is the panel's `aria-describedby` target).

**Themeable custom properties:** `--lr-lightbox-overlay-color` (default
`var(--lr-color-overlay-strong)` — the backdrop scrim), `--lr-lightbox-control-bg` (default
`var(--lr-color-neutral)`) and `--lr-lightbox-control-color` (default `var(--lr-color-on-neutral)`)
— background/foreground for the counter, caption, and every floating/toolbar icon button; these use
the solid neutral token rather than `--lr-color-surface` because the controls float over arbitrary
photo content.

**Optional peer deps:** none.

**Known gotchas:**

- keyboard navigation is RTL-aware on panel/chrome: Arrow forward/back (mirrored under `rtl`),
  `Home`, `End`. When the embedded pan/zoom viewport owns focus, those keys remain with its native
  scroll surface and never change gallery item; `+`/`-`/`0` remain its zoom shortcuts.
- initial focus deliberately goes to `close-button`, not the first tabbable element — a slotted
  `actions` button placed before it does not steal focus.
- zoom/pan reset on navigation is imperative (`resetView()` from `updated()`), not a binding; the
  frame element is reused across navigations rather than recreated, so a keyboard user who tabbed
  into the viewport keeps focus.
- fit sizing is CSS-driven inside the stable frame. The rendered DOM image is not copied or
  measured by the lightbox, so stale load events cannot apply a previous image's size. The fit
  policy covers the painted image only; the lightbox's DOM caption, toolbar, legend-like actions,
  and tooltip content remain outside that image surface.
- scope for v1: no per-image slotted content (data-driven via `images` only), no dot indicators, no
  visual open/close animation, no click-image-to-navigate, no touch-swipe. Lifecycle phases are
  still observable through the before/after events and methods above.

## `lr-qr-code`

Renders `value` as a QR code using the optional `qrcode` peer dependency. **Properties:** `value`,
`label`, `size` (clamped to `1`–`2048` CSS px), `radius` (clamped to `0`–`0.5`), and
`errorCorrection` (`error-correction`, `L`/`M`/`Q`/`H`, default `H`). Standard host `color` and
`background-color` control paint; optional `--lr-qr-code-fill` and
`--lr-qr-code-background` aliases override those host styles, while the permanent upstream parity
properties `fill` and `background` remain the highest-precedence paint inputs. `image` accepts
a safe media URL for a centered overlay, `imageBackground` (`image-background`) paints its coverage
box, `imageCoverage` (`image-coverage`, default `0.5`) controls that box as a fraction of the canvas
side, and `imagePadding` (`image-padding`, default `0`) pads the image within it. Image geometry is
finite-number guarded and clamped; supplying a valid image forces error correction to `H` so the
covered modules remain recoverable. Unsafe image URLs are ignored and a failed image load leaves the
base QR symbol intact. Peer output is validated and cloned into an owned finite QR matrix before
paint; malformed or hostile module shapes fail closed to the localized error state.

The host is the single image-semantic owner; its accessible name uses host `aria-label`, then
`label`, then `value`, and it publishes `aria-busy="true"`/`"false"`. The stable public
`canvas: HTMLCanvasElement` is presentational and remains the same live node through
empty/loading/ready/error, reconnect, and adoption (hidden outside ready). Empty values render an
empty state. `generate(): void` synchronously starts re-encoding the current value.
`refreshTheme(): void` redraws cached modules for consumer-owned token changes; ordinary ancestor
theme and color-scheme changes redraw automatically. Async peer and image results are
generation-guarded, including across disconnect/reconnect.
`LyraQrCode.preload(): Promise<boolean>` is a static optional-peer warm-up that starts the shared
`qrcode` import without encoding a value; it resolves to `false` when the peer is unavailable.

When `IntersectionObserver` is available, painting waits for a valid intersecting entry and resumes
whenever the code re-enters view. If the API is unavailable, its constructor fails, or `observe()`
throws, rendering proceeds immediately. Invalid resolved paint colors fall back to the documented
safe fill/background without changing the QR's loading or error state: foreground becomes black,
background becomes transparent, and `imageBackground` becomes the resolved QR background.

At ordinary sizes the backing store is a fixed `2×` the CSS size, independent of device pixel
ratio. It degrades uniformly only to stay within 4,096 pixels per dimension and 8,388,608 total
pixels. Modules span the full canvas with no injected quiet zone; add host padding when a scanner
or physical output needs one.

**CSS parts:** `base` and `qr-code` are aliases on the same outer wrapper; `canvas`, `empty`,
`loading`, and `error`. **CSS custom properties:**
`--lr-qr-code-fill` and `--lr-qr-code-background`.

`error` is ordinary localized visible text, not a shadow live region. A missing peer or encode
failure appends the localized message to the document's pre-mounted
`[data-lr-live-region="assertive"]` sink; identical retries append distinct children, and sink
ownership is released/reacquired across disconnect or document adoption. Meaningful post-mount
loading transitions use the corresponding polite light-DOM sink; initial mount remains silent.

## `lr-image-viewer`

A full pan/zoom raster-image viewer with labeled region highlights and opt-in region annotation, the
landing surface for `region`-anchored citations. Distinct from `<lr-svg-viewer>` (rendered SVG
documents) and `<lr-image-comparer>` (before/after slotted surfaces). Adopts `DocumentAnchorTarget`
with `anchorKinds: ['region']` only — no text selection is bound.

Disabled fit, rotate and annotate controls retain their resting paint on hover and press. Enabled
controls keep their token-driven feedback.

The annotation wrapper displays the shared token-driven focus ring in keyboard modality. The ring
sits inside the wrapper so an image filling the scroll viewport cannot clip it. Annotation commands
apply when that wrapper itself owns keyboard input. Enter on a highlight button activates that
highlight without starting or committing an annotation, whether or not a draft exists; wrapper arrow
commands retain physical image-coordinate semantics in both directions.

**Properties:** `src: string = ''`, `name: string = ''`, `alt?: string`,
`fit: LyraImageFit = 'contain' | 'width' | 'actual'` (reflected; invalid writes normalize to
`contain`), `zoom: number = 1` (reflected), `minZoom: number = 0.5` (attribute
`min-zoom`), `maxZoom: number = 4` (attribute `max-zoom`), `zoomStep: number = 0.25` (attribute
`zoom-step`) — `minZoom`/`maxZoom`/`zoomStep` are pure pass-throughs to the embedded
`<lr-pan-zoom>` as its own `.minZoom`/`.maxZoom`/`.zoomStep`, which does the actual
clamping/normalizing; same names/defaults as `<lr-lightbox>`'s identical trio, both wrapping the
same pan/zoom surface — `rotation: LyraImageRotation = 0 | 90 | 180 | 270` (reflected; finite
writes round to the nearest right angle and wrap), and `annotatable: boolean = false` (reflected).
`LyraImageRegionRect` is the public `{ x, y, width, height }` percentage-coordinate shape. The
inherited anchor-target surface is
`highlights: readonly LyraHighlight[] = []` (property only; assign a new collection to update),
`activeHighlightId: string | null = null` (attribute `active-highlight-id`),
`anchor: LyraAnchor | string | null = null` (property only), and readonly
`anchorKinds: readonly LyraAnchorKind[] = ['region']`.

**Methods:** `rotate()` advances `rotation` by 90°. `zoomIn()`, `zoomOut()`, and `resetZoom()` adjust
the embedded pan-zoom surface's zoom. `scrollToAnchor(target: LyraAnchor | string):
Promise<boolean>` resolves a canonical finite, positive, in-bounds `region` anchor (or unique
highlight id) after the image loads, scrolls its rendered target into the pan/zoom viewport, and
reports true only when the target visibly intersects that viewport. Malformed/out-of-range regions
report false.

**Events:** `lr-load` (`detail: { naturalWidth, naturalHeight }`), `lr-zoom-change` (`detail: {
zoom }`), `lr-rotation-change` (`detail: { rotation }`), `lr-fit-change` (`detail: { fit }`),
`lr-highlight-activate` (`detail: { highlightId }`), `lr-annotation-create` (`detail: { anchor }`, kind
`'region'`), `lr-anchor-result` (`detail: { found }`), and `lr-render-error` (`detail: { error
}`).

`lr-text-select` is not part of this raster viewer's event contract because it binds no selectable
text.

**CSS parts:** `base`, `toolbar`, `fit-control`, `rotate-button`, `annotate-toggle`, `frame` (the
embedded `lr-pan-zoom`), forwarded aliases `frame-viewport`, `frame-content`, `frame-controls`,
`rotation-frame` (the axis-swapped 90°/270° layout footprint), `image-wrapper`, `image`,
`highlight-layer`, `highlight` (carries `data-tone`/`data-active`), `highlight-label`,
`annotation-box`, `error`, and `anchor-live-region` (an aria-hidden, non-live shadow mirror of the
latest anchor-jump message; the spoken copy is appended to the shared document-level polite sink
only while the viewer and its composed ancestors are exposed to the accessibility tree).

`error` is ordinary localized visible text, not a shadow live region. A fresh post-mount image
failure or transition to an unsafe source appends the localized message to the document's
pre-mounted `[data-lr-live-region="assertive"]` sink. An already-unsafe initial `src` remains
visible but does not interrupt on mount; identical later failures append distinct children.

Fit, rotate and annotate controls remain disabled until the current source reaches its own loaded
terminal. Requested annotation mode resumes after a successful replacement load, but is not
exposed as pressed/operable during idle, loading, or error state.

While effectively annotatable, `image-wrapper` is a named `role="group"` with the localized
annotation hint. Only `region` highlights whose rectangle is finite, positive and wholly within
the 0–100 image coordinate space are rendered. Malformed, empty, and blank IDs are omitted; later
duplicates use first-wins uniqueness. At most
`IMAGE_VIEWER_HIGHLIGHT_LIMIT` (200) region buttons are projected at once; one roving `tabindex=0`
is maintained, Arrow keys/Home/End move within the projection, and an active item beyond the
leading window replaces its final entry so identity stays reachable. `data-truncated` and
`data-total` on `highlight-layer` expose the bounded state. Highlight tones retain distinct border
styles as well as colors, including forced-colors mode.

At 90°/270°, `rotation-frame` swaps the untransformed wrapper's layout axes and centers the painted
transform inside that footprint, keeping every fit mode reachable in the scroll geometry in LTR
and RTL.

**RTL behavior:** the raster and annotation geometry use physical image coordinates. In annotation
mode, ArrowLeft/ArrowRight decrease/increase a draft's `x` coordinate and their Shift variants
decrease/increase its width in both text directions; the surrounding toolbar remains logical.

**Themeable custom properties:** `--lr-image-viewer-annotate-active-bg` (default
`var(--lr-color-brand-quiet)`) and `--lr-image-viewer-annotate-active-border` (default
`var(--lr-color-brand)`) — the background and border of `[part='annotate-toggle']` while annotation
mode is on. The toggle carries its own glyph in `--lr-color-text`, so keep a 4.5:1 ratio against it
when overriding the background. `--lr-image-viewer-highlight-active-color` (default
`var(--lr-color-brand)`) — the outline of the `[part='highlight']` matching `activeHighlightId`,
independent of the per-tone border colors, so the active box stays distinguishable whatever tone it
carries. `--lr-image-viewer-highlight-active-border-width` (default
`var(--lr-border-width-thick)`) controls the active highlight border width;
`--lr-image-viewer-highlight-active-outline-width` (default `var(--lr-focus-ring-width)`) and
`--lr-image-viewer-highlight-active-outline-offset` (default `var(--lr-focus-ring-offset)`) control
its outline geometry. Like the existing active color hook, each is an inline `var()` fallback and
can be set on the viewer or any ancestor. Highlight tone styling is exposed through
`--lr-image-viewer-highlight-border`,
`--lr-image-viewer-highlight-bg`, and the tone-specific
`--lr-image-viewer-highlight-success-border`, `--lr-image-viewer-highlight-success-bg`,
`--lr-image-viewer-highlight-warning-border`, `--lr-image-viewer-highlight-warning-bg`,
`--lr-image-viewer-highlight-danger-border`, `--lr-image-viewer-highlight-danger-bg`,
`--lr-image-viewer-highlight-neutral-border`, and `--lr-image-viewer-highlight-neutral-bg`
properties. `--lr-image-viewer-highlight-fill` is the resting fill a `[part='highlight']` actually
renders, resolved per tone from the `-bg` knobs above; its hover and pressed states are color mixes
taken from that value, so setting it directly retints all three states of one highlight at once —
retint a whole tone through the matching `-bg` knob instead. `--lr-image-viewer-annotation-box-border`
(default `var(--lr-color-brand)`) and `--lr-image-viewer-annotation-box-bg` (default
`color-mix(in srgb, var(--lr-color-brand) 15%, transparent)`) retint `[part='annotation-box']`, the
in-progress draft rectangle drawn while actively annotating, independent of the saved highlights'
own tone colors. These properties are declared as inline
`var()` fallbacks at the point of use rather than on `:host`, so each can be set on the element _or
on any ancestor_:
`::part(highlight)[data-active]` is invalid CSS — Shadow Parts forbids an attribute selector after
`::part()` — which previously left overriding the library-wide
`--lr-color-brand`/`--lr-color-brand-quiet` tokens as the only lever, repainting every other
element that read them. Unset, each falls back to the token its rule used before.

## `lr-av-player`

An audio/video player built on a native `<audio>`/`<video>` element, plus a cue transcript synced to
`currentTime`, `time-range` anchor/highlight support, an optional dependency-free waveform (peaks
in, no in-component decoding), and playback-rate control. Owns recorded-media transcript sync —
distinct from `<lr-transcript-feed>` (live captions for an in-progress voice session) and
`<lr-sequence-playback>` (a discrete sequence stepper, no native media). Adopts
`DocumentAnchorTarget` with
`anchorKinds: ['time-range']` only — no text selection is bound. The transcript virtualizes through
`<lr-virtual-list>` the same way `lr-pdf-viewer` virtualizes pages.

Removing `mime-type` consumes the absent hint safely and restores automatic video fallback unless
`kind` explicitly selects audio. Attribute removal keeps its `null` property readback; an explicit
empty hint remains empty, and a later audio MIME value restores audio detection.

A cue with no `end` extends to the next strictly chronological applicable start, or remains
open-ended when none exists. Equal starts do not end each other. The player indexes starts on cue
assignment in at most O(n log n) work and reconciles each seek/time update in O(n) work. Caller
order, first ID admission, explicit ends and overlap arbitration are retained; a paused seek uses
replacement cues immediately, even before rendering. Duration changes preserve the same
effective-start rules.

An unavailable timeline keeps its resting border and background under hover and press. Enabled
seeking retains token-driven pointer feedback.

The default document-viewer renderer advertises `time-range` anchors but not search: the generic
document payload has no cue/transcript field, so advertising search there would expose a control
whose result is always empty. Standalone `<lr-av-player>` search remains available whenever the
consumer supplies `cues` directly.

**Properties:** `src: string = ''`, `name: string = ''`, `kind?: 'audio' | 'video'`
(attribute-backed auto-detection override), `mimeType: string = ''` (attribute `mime-type`), `poster: string =
''`, `loop: boolean = false`, `muted: boolean = false`, `preload: 'none' | 'metadata' | 'auto' =
'metadata'`, `playbackRate: number = 1` (attribute `playback-rate`, reflected),
`volume: number = 1` (attribute `volume`, reflected; normalized to `0..1`),
`rates: readonly number[] = [0.75, 1, 1.25, 1.5, 2]` (attribute: false),
`cues: readonly LyraAvCue[] = []` (attribute: false), `peaks: readonly number[] = []`
(attribute: false), and `tracks: readonly LyraAvTrack[] = []` (attribute: false). Each collection is
normalized synchronously on assignment into a bounded, cloned, frozen snapshot; mutate by assigning a
new collection. The inherited
anchor-target surface is `highlights: readonly LyraHighlight[] = []` (property only; assign a new
collection to update), `activeHighlightId: string | null = null` (attribute `active-highlight-id`),
`anchor: LyraAnchor | string | null = null` (property only), and readonly
`anchorKinds: readonly LyraAnchorKind[] = ['time-range']`.
`LyraAvCue = { readonly cueId, readonly start, readonly end?, readonly text, readonly speaker? }`;
`LyraAvTrack = { readonly src, readonly kind: 'subtitles' | 'captions' | 'descriptions', readonly
srclang, readonly label, readonly default? }`. Their retained records are frozen as well as the
outer arrays. Cue IDs are trimmed and must be nonempty; the first cue for a `cueId` is retained and
blank or later duplicate records are ignored.

Only exact `kind="audio"` and `kind="video"` values override MIME auto-detection. An unrecognized
runtime or attribute value falls back to `mimeType` (`audio/*` renders audio; every other value
renders video) and never appears in `lr-load`'s `detail.kind`.

`poster` is ignored for audio and is validated with the same safe media-source allowlist as `src`
before reaching the native video element; an unsafe poster URL is omitted.

Runtime numeric input is normalized before it reaches media, canvas, or `Intl`: cue/highlight times
and waveform peaks are clamped to their valid ranges; non-finite native duration/current time
cannot leak into state or events. `rates` keeps only unique finite values in the supported
`0.0625..16` range, while always including the normalized current `playbackRate`.

**Waveform lifecycle:** with `peaks`, waveform canvas painting is gated by player visibility when
`IntersectionObserver` is available. Peak, theme, and resize changes while the player is
off-screen coalesce into one paint on re-entry; environments without that API retain eager
painting.

**Methods:** `play(): Promise<void>` proxies the native media element and preserves its native
promise/rejection (before the media mounts it returns an already-resolved promise). `pause()` and
`toggle()` proxy the native element; an internal toggle that cannot start playback renders the
error state and emits `lr-render-error`. `seek(seconds)` sets `currentTime` and forces an immediate
`lr-time-change`. `search(query)` resolves the match count; `searchNext()`/`searchPrevious()` wrap
and reveal the active match in the virtualized transcript without seeking playback; `clearSearch()`
resets the query and match state. `focus(options?)`, `blur()`, and `click()` forward to the native
`[part='media']` element, which carries `controls` and is therefore the player's primary focusable
affordance. `scrollToAnchor(target: LyraAnchor | string): Promise<boolean>` seeks to a resolved
`time-range` anchor's `start` after media metadata loads and makes an id-addressed highlight active;
unsupported or unresolved targets report `false` through the return value and `lr-anchor-result`.

**Events:** `lr-play`, `lr-pause`, `lr-load` (`detail: { duration, kind }`), `lr-time-change`
(`detail: { currentTime }`, throttled to at most 4/s while playing plus one extra per `seek()`),
`lr-rate-change` (`detail: { rate }`), `lr-cue-change`
(`detail: { readonly cueId, readonly index }`; `cueId` is `null` and `index` is `-1` when no cue is active),
`lr-highlight-activate` (`detail: { highlightId }`), `lr-anchor-result` (`detail: {
found }`), `lr-search-change` (`detail: { query, matchCount, matchCountExact, activeIndex }`;
`matchCountExact` is always `true` — `search()` matches over the already-loaded `cues` array with no
additional ceiling), and
`lr-render-error` (`detail: { error }`). The native `ended`, `error`, `loadedmetadata`, `pause`,
`play`, `timeupdate`, and `volumechange`
events are also relayed exactly once from the host as native `Event` instances. Like the original
media notifications, these relays are non-bubbling, non-composed, and non-cancelable. The richer
`lr-*` notifications above remain unchanged. The native media element's `focus`/`blur` are relayed
exactly once as owner-realm native `FocusEvent`s (bubbling and composed, preserving
`relatedTarget`). `lr-text-select` is not part of this
player's event contract: transcript rows live inside the embedded virtual list's nested shadow
root, so no selection binding is installed.

**CSS parts:** `base`, `media` (the native `<audio>`/`<video>` element), `toolbar`, `rate-select`,
`timeline` (click-to-seek and arrow-key seeking), `timeline-marker` (one per `time-range` highlight;
`data-tone`, `data-active`), `transcript` (the `<lr-virtual-list>` itself), `cue` (`aria-current`,
`data-match`, `data-active-match`), `cue-current` (added alongside `cue` on the row the playhead is
inside), `cue-match` (added alongside `cue` on a row matching the current search query),
`cue-active-match` (added alongside `cue`/`cue-match` on the row holding the current match),
`cue-time`, `cue-speaker`, `cue-text`, `error`, and `anchor-live-region` (an aria-hidden, non-live
shadow mirror of the latest anchor-jump message; the spoken copy is appended to the shared
document-level polite sink only while the viewer and its composed ancestors are exposed to the
accessibility tree).

`error` is ordinary localized visible text, not a shadow live region. A fresh post-mount native,
playback, or unsafe-source failure appends the localized message to the document's pre-mounted
`[data-lr-live-region="assertive"]` sink. An already-unsafe initial `src` remains visible but does
not interrupt on mount; identical later failures append distinct children. `[part="base"]` remains
a named `role="region"` in the unsafe-source branch and across a safe-to-unsafe transition, so the
player does not lose its landmark or accessible name when its media is replaced by the error.

Every cue-level part above is rendered into the embedded `<lr-virtual-list>`'s own shadow root and
forwarded back out through `exportparts`, so `lr-av-player::part(cue)` and friends work from a
consumer stylesheet. The three cue states are separate part _names_ rather than attribute selectors,
because Shadow Parts forbids an attribute selector after `::part()` —
`::part(cue)[aria-current='true']` is invalid CSS, so use `::part(cue-current)`. The `aria-current`
and `data-*` attributes remain on each row for semantics and scripting.

**Themeable custom properties:** `--lr-av-player-transcript-height` (default
`var(--lr-size-16rem)` — block size of the transcript pane; forwarded to the embedded
`<lr-virtual-list>`'s own `--lr-virtual-list-height`). `--lr-av-player-marker-active-color` (default
`var(--lr-color-brand)`) — the outline of the `[part='timeline-marker']` matching
`activeHighlightId`, leaving the per-tone marker fills alone. It is an inline `var()` fallback at
the point of use rather than a `:host` declaration, so it can be set on the element or on any
ancestor — `::part(timeline-marker)[data-active]` is invalid CSS (Shadow Parts forbids an attribute
selector after `::part()`), so re-pointing the shared `--lr-color-brand` token was the only previous
lever.

Each `[part='timeline-marker']`'s own background is independently overridable per tone, the same
inline-`var()`-fallback pattern as `--lr-av-player-marker-active-color` above:
`--lr-av-player-marker-bg` (default `color-mix(in srgb, var(--lr-color-brand) 35%, transparent)`) —
no (or an unrecognized) `data-tone`; `--lr-av-player-marker-success-bg` (default `color-mix(in srgb,
var(--lr-color-success) 35%, transparent)`) — `data-tone="success"`;
`--lr-av-player-marker-warning-bg` (default `color-mix(in srgb, var(--lr-color-warning) 35%,
transparent)`) — `data-tone="warning"`; `--lr-av-player-marker-danger-bg` (default `color-mix(in
srgb, var(--lr-color-danger) 35%, transparent)`) — `data-tone="danger"`; and
`--lr-av-player-marker-neutral-bg` (default `color-mix(in srgb, var(--lr-color-text) 25%,
transparent)`) — `data-tone="neutral"`. Each can be set on the element or on any ancestor without
hijacking the shared `--lr-color-success`/`-warning`/`-danger`/`-brand`/`-text` tokens used
elsewhere in the theme. `--lr-av-player-marker-fill` is the resting fill a marker actually renders,
resolved per tone from those `-bg` knobs; its hover and pressed states are color mixes taken from
that value, so setting it directly retints all three states of one marker at once — retint a whole
tone through the matching `-bg` knob instead.

Three further cue-state properties tint the transcript: `--lr-av-player-cue-hover-bg` (default
`var(--lr-color-brand-quiet)`) is the background of a hovered `cue` row, and its pressed state is a
color mix taken from that same value rather than a separate knob, so retuning it keeps its pressed
step too. `--lr-av-player-cue-current-bg` (default `var(--lr-color-brand-quiet)`) is the background
of the `cue-current` row the playhead is inside, and `--lr-av-player-cue-active-match-color`
(default `var(--lr-color-warning)`) is the outline of the `cue-active-match` row, leaving the other
matches' dashed outline on the shared warning token. All three are inline `var()` fallbacks at the
point of use rather than `:host` declarations, so any of them can be set on the element or on any
ancestor.

**RTL behavior:** surrounding controls follow the inherited direction, but the elapsed-media axis
on `[part='timeline']` stays physical left-to-right. ArrowLeft rewinds and ArrowRight advances in
both LTR and RTL.

## `lr-video`

Experimental inline native video player with custom controls, safe declarative sources/tracks,
selectable captions, and bounded WebVTT thumbnail previews. It mirrors the public Web Awesome Video
API under the `lr-` prefix. Import the granular registration entry with
`import '@aceshooting/lyra-ui/components/media/video/video.js'`.

When progress is unavailable, the disabled native range input and its visible timeline track retain
resting paint under hover and press. Once media duration makes progress available, the track retains
its token-driven hover and press feedback.

**Properties:** `autoplay: boolean = false`, `autoplayMuted: boolean = false` (attribute
`autoplay-muted`), `autoplayOnVisible: boolean = false` (attribute `autoplay-on-visible`),
`controls: 'none' | 'standard' | 'full' = 'standard'`, `currentTime: number = 0` (attribute
`currentTime`; HTML exposes it as lowercase `currenttime`, with legacy `current-time` also
accepted), `duration: number = 0` (live/read-only in normal use), `iconLibrary: string =
'system'` (attribute `icon-library`), `loop: boolean = false`, `muted: boolean = false`, `playing:
boolean = false` (live/read-only in normal use), `poster: string = ''`, `preload: 'auto' |
'metadata' | 'none' = 'metadata'`, `src: string = ''`, `thumbnails: string = ''`, `title: string =
''`, and `volume: number = 1`. The private native `<video>` always carries `playsinline`; native
browser controls stay disabled because the selected Lyra preset owns the control surface.
`autoplayOnVisible` does not start a video merely because it is visible: it pauses a currently
playing video when it leaves view and resumes only that visibility-owned pause when it returns.
Turning the property off while such a pause is pending resumes immediately; observer rebuilds,
temporary disconnects, reconnects, and same-origin adoption preserve the pending ownership. An
explicit user/API pause or source reload/change revokes it so later visibility changes cannot
restart user-stopped media.

`controls="standard"` renders play/pause, timeline and elapsed/duration labels, volume/mute,
available captions, and capability-gated fullscreen. `controls="full"` adds playback rate and
capability-gated picture in picture. `controls="none"` removes the control bar but leaves the
poster and active caption overlays available. Fullscreen/PiP/caption affordances are feature-gated
instead of browser-name-gated and are probed through the concrete native element's current owner
realm. While the poster is visible, its button is the only exposed play action; the ordinary
control-bar play toggle is hidden until the poster is dismissed.

**Methods:** `getState(): VideoState` returns a fresh synchronous
`{ playing, currentTime, duration, volume, muted, playbackRate }` snapshot. `VideoState` is the
canonical upstream-compatible authoring type; the redundant `LyraVideoState` alias is removed in
v9;
`getVideoElement(): HTMLVideoElement | undefined` returns the private native element after mount;
`play(): Promise<void>` returns the exact native promise and preserves its rejection; `pause()`,
`togglePlay()`, `toggleMute()`, `seek(time)`, `setPlaybackRate(rate)`, and `setVolume(volume)` proxy
finite, clamped media state; `requestFullscreen()` and `exitFullscreen()` preserve the platform
promise/rejection and reject with an owner-realm `DOMException` named `NotSupportedError` when the
capability is absent. `load()` is a
Lyra extension that re-clones current light-DOM sources/tracks and restarts native resource
selection under a fresh event generation. `focus(options?)`, `blur()`, and `click()` forward to the
play/pause control (absent, and therefore a no-op, under `controls="none"`).

**Events:** native `ended`, `error`, `loadedmetadata`, `pause`, `play`, `timeupdate`, and
`volumechange`, relayed exactly once from the host as native `Event` instances. They remain
non-bubbling, non-composed, and non-cancelable. Scrubbing the custom timeline also dispatches an
immediate host `timeupdate`, before a browser's eventual native seek notification. The internal
play/pause control's `focus`/`blur` are relayed exactly once as owner-realm native `FocusEvent`s
(bubbling and composed, preserving `relatedTarget`).

**Slots:** the default slot accepts direct `<source>` and `<track>` children;
`controls-after-play`, `controls-start`, `exit-fullscreen-icon`, `fullscreen-icon`, `mute-icon`,
`pause-icon`, `play-icon`, `poster-icon`, and `volume-icon` customize the control surface. Consumer
source/track nodes remain in light DOM: the component inserts fresh private clones containing only
safe URL, source (`type`, `media`), and track (`kind`, `srclang`, `label`, `default`) attributes.
The seven `*-icon` slots are decorative glyph overrides: assigned content renders in an inert,
`aria-hidden`, pointer-transparent visual layer beside the named native button, never inside its
flat-tree descendants. An accidentally supplied link, button, or input therefore cannot create a
nested action or second keyboard stop. `controls-start` and `controls-after-play` remain ordinary
composition slots and may intentionally contain interactive controls.

A declarative host `aria-label` or `title` remains the component's overall name and is not copied to
the private native video; that element receives the localized player-purpose name. An explicitly
empty host `aria-label` is preserved exactly as an empty native-video name. Caption/subtitle tracks
selected for Lyra's custom overlay use native `mode="hidden"`, keeping cue activity available
without asking the browser to paint a duplicate native caption layer.

**CSS parts:** `base` and `video-wrapper` (aliases on the same root node), `caption`,
`caption-overlay`, `controls`, `controls-overlay`, `poster-overlay`, `poster-play-button`,
`progress`, `thumbnail`, `timeline`, `timeline-indicator`, `timeline-thumb`, `timeline-track`,
`video`, and `video-title-overlay`.

The `progress` range carries `aria-label` and points through `aria-describedby` to a localized
`{current} of {duration}` description (key `avPlayerPosition`, shared with `lr-av-player`) built
from the same locale-formatted clock times as the visible labels. This deliberately avoids relying
on `aria-valuetext`, which browsers ignore on native range semantics. Before duration is available,
the same range remains in the DOM as a disabled `0..0` control with its description intact,
avoiding a disappearing/reappearing semantic target.

**Themeable custom properties:** `--controls-background` (default
`var(--lr-color-overlay-strong)`), `--controls-color` (default
`var(--lr-color-on-strong-overlay)`), and
`--poster-play-button-background` (default `var(--lr-color-surface-overlay)`). These exact names are
kept for mechanical Web Awesome migration. Lyra also supplies
`--lr-video-poster-play-button-hover-background` (default is the existing hover color mix) and
`--lr-video-poster-play-button-hover-border-color` (default `var(--lr-color-brand)`).

Caption and playback-rate selectors remain native `<select>` controls with decorative, pointer-inert
chevrons; their option foreground and background inherit `--controls-color` and
`--controls-background`. Controls, elapsed/title text, caption text, and selectors consistently use
the semantic strong-overlay foreground. The fallback remains legible in light and dark themes.
The poster play button and its glyph instead default to `--lr-color-text` against their
`--lr-color-surface-overlay` surface. An explicit `--controls-color` retains final precedence on
both poster and overlay controls, and forced-colors mode remains UA-owned.

**RTL behavior:** surrounding controls follow the inherited direction, while the elapsed-media axis
stays physical left-to-right. Native ArrowRight advances and ArrowLeft rewinds the timeline in both
LTR and RTL.

**Thumbnail security and lifecycle:** `thumbnails` is validated before `fetch()`, read through a
256 KiB byte ceiling, and parsed up to 2,000 cues. Cue image URLs are resolved relative to the VTT
file and validated again before reaching `<img>`; `#xywh=x,y,width,height` sprite fragments are
supported. A generation token is checked after every await, and changing `thumbnails` or
disconnecting prevents an older response from painting over newer state. Invalid, oversized,
failed, or empty thumbnail files fail closed to no preview; no caught remote error text is shown.

```html
<lr-video controls="full" poster="/posters/demo.jpg" title="Product demo">
  <source src="/video/demo.webm" type="video/webm" />
  <source src="/video/demo.mp4" type="video/mp4" />
  <track
    src="/captions/demo-en.vtt"
    kind="captions"
    srclang="en"
    label="English"
    default
  />
</lr-video>
```

## `lr-video-playlist`

Experimental direct-child `<lr-video>` playlist with a visible current-video stage and
keyboard-navigable item list. It mirrors the public Web Awesome Video Playlist API under the `lr-`
prefix. Import the granular registration entry with
`import '@aceshooting/lyra-ui/components/media/video-playlist/video-playlist.js'`.

**Properties:** `controls: 'none' | 'standard' | 'full' = 'full'` (reflected and forwarded to every
direct child), and `iconLibrary: string = 'system'` (attribute `icon-library`, non-reflected and
forwarded). Lyra additionally provides `autoAdvance: boolean = true` (attribute `auto-advance`;
`auto-advance="false"` disables completion-driven navigation) and `repeat: 'none' | 'one' | 'all' =
'none'`. Keeping `autoAdvance` true preserves the mirrored behavior in which an ended video starts
the next one. `repeat="one"` restarts the current video; `repeat="all"` wraps the final video to the
first. `items: readonly LyraVideoPlaylistItem[] = []` (attribute: false) is deterministic
first-render row metadata with `{ title, poster?, duration?, unavailable? }`, indexed to the direct
video children. Assign the same value before the server and browser first render. Seeded rows stay
visible but disabled while live children are unavailable; after hydration, each child's live
title/poster/duration and native `inert` state become authoritative in a corrective update that
reuses the server-rendered row nodes. Once live children have been observed, later removal does not
make stale seed rows reappear.

**Methods:** `goTo(index)` selects a finite integer direct-child index; invalid, fractional, and
inert-child indexes are no-ops. Calling it for the current index still emits `lr-video-change`, matching
the mirrored contract. `next()` and `previous()` select the next or previous enabled child when one
exists. `focus(options?)`, `blur()`, and `click()` forward to the playlist row that currently owns
the optional-arrow navigation cursor (falling back to the first enabled row). This forwarding is a
convenience; every enabled row is independently reachable through ordinary sequential Tab order.

**Events:** internal `focus`/`blur` from a playlist row are relayed exactly once as owner-realm
native `FocusEvent`s (bubbling and composed, preserving `relatedTarget`).
`lr-video-change` is bubbling and composed but non-cancelable, with exact
detail `{ previousIndex, currentIndex, video }`. `video` is a fresh detached, recursively frozen plain-data snapshot with
exact shape `{ title, poster, sources, tracks }`, not the live child element. `sources` contains
fresh `{ src, type, media }` records for the child's direct `src` and `<source>` declarations;
`tracks` contains fresh `{ src, kind, srclang, label, default }` records. A listener that needs to
annotate or reshape the payload must create its own mutable copy; the dispatched detail and every
nested record/array reject mutation.

**Slot:** the default slot accepts direct `<lr-video>` children. Nested videos and other elements
are not playlist items.

**CSS parts:** `base` and `video-playlist` (aliases on the same root node), `playlist`,
`playlist-duration`, `playlist-item`, `playlist-thumbnail`, and `playlist-title`.

**Themeable custom properties:** `--lr-video-playlist-item-current-border-color` (default
`var(--lr-color-brand)`) and `--lr-video-playlist-item-current-background` (default
`var(--lr-color-brand-fill-quiet)`) style the active playlist row.

Only the active child is visible and loaded. Before another child is activated, the outgoing native
player is synchronously paused, stripped of its private source/track clones, and reloaded into an
empty selection state. The incoming child then safely re-clones its own light-DOM declarations.
Valid user volume, mute, playback-rate, and selected-caption preferences carry across that boundary;
selected caption tracks use `hidden`, not `showing`, so the active child's custom overlay is the only
caption paint. Current time does not carry. Events and rejected play promises from a superseded
activation cannot affect the current child. The playlist snapshots each child's authored
`controls`, `iconLibrary`, and `hidden` values before projecting effective state, and restores those
values plus resource selection when that exact child is removed or reparented. Removing or
reordering duplicate-metadata children is identity-safe; disconnecting pauses/unloads every child
while preserving ownership for a later reconnect in a new realm.

Every enabled playlist button has `tabindex="0"`; disabled rows for inert children use `-1`.
Up/Down, Home/End, and mirrored Left/Right remain optional shortcuts, and the selected item exposes
`aria-current`. Each visible known duration is associated with its row using `aria-describedby`;
missing duration creates no empty description, and metadata updates replace the localized value.
At narrow
allocations the sidebar moves below the video through a container query; long titles ellipsize
without widening the host.

**A child marked `inert` is unavailable:** it never becomes the active video,
`next()`/`previous()`/`goTo()` and auto-advance step past it, and its playlist row renders `disabled`
and `tabindex="-1"` so neither sequential nor optional-arrow focus can land on it — an inert element
refuses focus, which would leave `focus()` a silent no-op and kill the next arrow press. `<lr-video>`
has no `disabled`
property; use the platform `inert` state exclusively. Only the child's **own** `inert` counts: a
playlist inerted wholesale by an open modal keeps playing. The attribute is watched live, so
marking the _current_ video inert moves the selection to the nearest enabled child (emitting
`lr-video-change`) and hands optional-arrow focus to the row that replaced it, instead of leaving a
stale arrow-navigation cursor on a row that can no longer take focus.

Only the native `ended` notification drives `autoAdvance`/repeat completion. A native `error`
records the stopped state but never changes selection; recovery and retry remain consumer-owned.

```html
<lr-video-playlist controls="full" repeat="all">
  <lr-video title="Introduction" poster="/posters/introduction.jpg">
    <source src="/video/introduction.mp4" type="video/mp4" />
  </lr-video>
  <lr-video title="Advanced workflow" poster="/posters/advanced.jpg">
    <source src="/video/advanced.mp4" type="video/mp4" />
    <track
      src="/captions/advanced-en.vtt"
      kind="captions"
      srclang="en"
      label="English"
      default
    />
  </lr-video>
</lr-video-playlist>
```

## Exported TypeScript contracts

These named interfaces and helper signatures are available to typed integrations. They are grouped by capability so the component sections above can stay focused.

- **`components-media-animation-animation-catalog-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/media/animation/animation.class.js`.
  `getAnimationNames(): LyraMirrorAnimationName[]`
  Import: `@aceshooting/lyra-ui/components/media/animation/animation.class.js`.
  `getEasingNames(): LyraAnimationEasingName[]`

- **`components-media-attachment-chip-attachment-chip-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/media/attachment-chip/attachment-chip.class.js`.
  `LyraAttachmentIdDetail {
    attachmentId: string;
  }`
  Import: `@aceshooting/lyra-ui/components/media/attachment-chip/attachment-chip.class.js`.
  `LyraAttachmentPreviewRequestDetail extends LyraAttachmentIdDetail {
    name: string;
    mimeType: string;
    src: string;
    // Inherited from LyraAttachmentIdDetail.
    attachmentId: string;
  }`

- **`components-media-attachment-trigger-attachment-trigger-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/media/attachment-trigger/attachment-trigger.class.js`.
  `LyraAttachmentFilesDetail {
    capability: LyraFileBackedCapability;
    files: readonly File[];
  }`

- **`components-media-av-player-av-metadata-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/media/av-player/av-player.class.js`.
  `LyraAvCue {
    readonly cueId: string;
    readonly start: number;
    readonly end?: number;
    readonly text: string;
    readonly speaker?: string;
  }`
  Import: `@aceshooting/lyra-ui/components/media/av-player/av-player.class.js`.
  `LyraAvTrack {
    readonly src: string;
    readonly kind: 'subtitles' | 'captions' | 'descriptions';
    readonly srclang: string;
    readonly label: string;
    readonly default?: boolean;
  }`

- **`components-media-av-player-av-player-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/media/av-player/av-player.class.js`.
  `LyraAvCueChangeDetail {
    readonly cueId: string | null;
    readonly index: number;
  }`

- **`components-media-avatar-group-avatar-group-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/media/avatar-group/avatar-group.class.js`.
  `LyraAvatarGroupOverflowDetail {
    readonly hiddenCount: number;
    readonly hiddenAvatars: readonly LyraAvatar[];
  }`

- **`components-media-avatar-avatar-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/media/avatar/avatar.class.js`.
  `LyraAvatarErrorDetail {
    image: string;
  }`

- **`components-media-drop-zone-drop-zone-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/media/drop-zone/drop-zone.class.js`.
  `LyraDropZoneRejectedFile {
    readonly file: File;
    readonly reason: 'type' | 'count' | 'size' | 'directory' | 'read' | 'limit' | 'maxFiles' | 'maxTotalSize';
  }`
  Import: `@aceshooting/lyra-ui/components/media/drop-zone/drop-zone.class.js`.
  `LyraDropZoneFilesDetail {
    readonly files: readonly File[];
    readonly rejected: readonly LyraDropZoneRejectedFile[];
    readonly remainingFiles: number | null;
    readonly remainingTotalSize: number | null;
  }`
  Import: `@aceshooting/lyra-ui/components/media/drop-zone/drop-zone.class.js`.
  `LyraDropZoneFilesEvent extends CustomEvent<LyraDropZoneFilesDetail> {
    readonly target: LyraDropZone;
    readonly currentTarget: LyraDropZone;
  }`
  `lr-files`'s event type on `<lr-drop-zone>`, narrowing `target`/`currentTarget` to `LyraDropZone`
  so a listener reads them without casting — same convention as `lr-file-input`'s own
  `LyraFileInputFilesEvent` below.

- **`components-media-file-icon-file-type-metadata-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/media/file-icon/file-icon.js`.
  `createFileTypeMetadataRegistry(entries?: readonly LyraFileTypeMetadataEntry[]): LyraFileTypeMetadataRegistry`
  Import: `@aceshooting/lyra-ui/components/media/file-icon/file-icon.js`.
  `getFileTypeMetadata(mimeType: string, fileName?: string): LyraResolvedFileTypeMetadata`
  Import: `@aceshooting/lyra-ui/components/media/file-icon/file-icon.js`.
  `LyraFileTypeMetadataEntry {
    readonly mimeTypes: string | readonly string[];
    readonly metadata: LyraFileTypeMetadata;
  }`
  Import: `@aceshooting/lyra-ui/components/media/file-icon/file-icon.js`.
  `LyraFileTypeMetadata {
    readonly label: string;
    readonly description?: string;
    readonly icon: LyraFileTypeIcon;
    readonly category: LyraFileTypeCategory;
    readonly extensions?: readonly string[];
  }`
  Import: `@aceshooting/lyra-ui/components/media/file-icon/file-icon.js`.
  `LyraFileTypeMetadataRegistry {
    resolve(mimeType: string, fileName?: string): LyraResolvedFileTypeMetadata;
  }`
  Import: `@aceshooting/lyra-ui/components/media/file-icon/file-icon.js`.
  `LyraResolvedFileTypeMetadata extends LyraFileTypeMetadata {
    readonly provenance: 'builtin' | 'consumer';
    // Inherited from LyraFileTypeMetadata.
    readonly label: string;
    readonly description?: string;
    readonly icon: LyraFileTypeIcon;
    readonly category: LyraFileTypeCategory;
    readonly extensions?: readonly string[];
  }`

- **`components-media-file-input-file-input-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/media/file-input/file-input.class.js`.
  `LyraFileInputFilesDetail {
    readonly files: readonly File[];
    readonly rejected: readonly LyraFileInputRejectedFile[];
    readonly remainingFiles: number | null;
    readonly remainingTotalSize: number | null;
  }`
  Import: `@aceshooting/lyra-ui/components/media/file-input/file-input.class.js`.
  `LyraFileInputObjectValidator {
    observedAttributes?: string[];
    checkValidity: (input: never) => LyraFileInputObjectValidatorResult;
    message?: string | ((input: never) => string);
  }`
  Import: `@aceshooting/lyra-ui/components/media/file-input/file-input.class.js`.
  `LyraFileInputObjectValidatorResult {
    message: string;
    isValid: boolean;
    invalidKeys: Exclude<keyof ValidityState, 'valid'>[];
  }`
  Import: `@aceshooting/lyra-ui/components/media/file-input/file-input.class.js`.
  `LyraFileInputRejectedFile {
    readonly file: File;
    readonly reason: 'type' | 'count' | 'size' | 'directory' | 'read' | 'limit' | 'maxFiles' | 'maxTotalSize';
  }`
  Import: `@aceshooting/lyra-ui/components/media/file-input/file-input.class.js`.
  `LyraFileInputFilesEvent extends CustomEvent<LyraFileInputFilesDetail> {
    readonly target: LyraFileInput;
    readonly currentTarget: LyraFileInput;
  }`
  `lr-files`'s event type, narrowing `target`/`currentTarget` to `LyraFileInput` so a listener reads
  them without casting.

- **`components-media-flag-flag-peer-bulk-standard-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/media/flag/flag-peer-bulk-standard.js`.
  `registerLyraFlagStandardBulkPeer(): Promise<LyraFlagUrlResolver | null>`

- **`components-media-flag-flag-peer-bulk-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/media/flag/flag-peer-bulk.js`.
  `registerLyraFlagBulkPeer(): Promise<LyraFlagUrlResolver | null>`

- **`components-media-flag-flag-peer-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/media/flag/flag-peer.js`.
  `registerLyraFlagPeer(): Promise<LyraFlagUrlResolver | null>`

- **`components-media-flag-flag-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/media/flag/flag.class.js`.
  `loadFlagUrl(importFlags: () => Promise<unknown>): Promise<LyraFlagUrlResolver | null>`
  Import: `@aceshooting/lyra-ui/components/media/flag/flag.class.js`.
  `loadBulkFlagUrl(importFlags: () => Promise<unknown>): Promise<LyraFlagUrlResolver | null>`
  Import: `@aceshooting/lyra-ui/components/media/flag/flag.class.js`.
  `setFlagUrlResolver(value: LyraFlagUrlResolver | Promise<LyraFlagUrlResolver | null> | null): void`

- **`components-media-flag-language-map-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/media/flag/language-map.js`.
  `alpha3ToAlpha2(code: string): string | undefined`
  Import: `@aceshooting/lyra-ui/components/media/flag/language-map.js`.
  `languageToCountry(language: string): string | undefined`
  Import: `@aceshooting/lyra-ui/components/media/flag/language-map.js`.
  `localeNativeName(tag: string): string`

- **`components-media-image-viewer-image-viewer-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/media/image-viewer/image-viewer.class.js`.
  `LyraImageRegionRect {
    x: number;
    y: number;
    width: number;
    height: number;
  }`

- **`components-media-lightbox-lightbox-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/media/lightbox/lightbox.class.js`.
  `LyraLightboxHideDetail {
    source: Element;
  }`
  Import: `@aceshooting/lyra-ui/components/media/lightbox/lightbox.class.js`.
  `LyraLightboxImage {
    readonly src: string;
    readonly alt?: string;
    readonly caption?: string;
  }`

- **`components-media-map-map-loader-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/media/map/map-loader.js`.
  `loadMaplibre(): Promise<MaplibreModule | null>`
  Import: `@aceshooting/lyra-ui/components/media/map/map-loader.js`.
  `MapLibreGeoJsonDiff {
    readonly remove?: readonly (string | number)[];
    readonly add?: readonly Feature[];
    readonly update: readonly {
      readonly id: string | number;
      readonly addOrUpdateProperties: readonly {
        readonly key: string;
        readonly value: unknown;
      }[];
      readonly removeProperties: readonly string[];
    }[];
  }`
  Import: `@aceshooting/lyra-ui/components/media/map/map-loader.js`.
  `MapLibreGeoJsonSource {
    setData(data: unknown): void;
    updateData?(diff: MapLibreGeoJsonDiff): void;
  }`
  Import: `@aceshooting/lyra-ui/components/media/map/map-loader.js`.
  `MapLibreMapCapability {
    getCanvas(): HTMLCanvasElement;
    getCenter(): {
      lng: number;
      lat: number;
    };
    getZoom(): number;
    setCenter(center: [number, number]): unknown;
    setZoom(zoom: number): unknown;
    resize(): unknown;
    setMaxBounds?(bounds: readonly [readonly [number, number], readonly [number, number]] | null): unknown;
    remove(): void;
    on(type: 'error', listener: (event: {
      error?: unknown;
    }) => void): this;
    on(type: 'load', listener: () => void): this;
    on(type: 'click', listener: (event: {
      point: unknown;
      lngLat: {
        lng: number;
        lat: number;
      };
    }) => void): this;
    once(type: 'style.load', listener: () => void): this;
    setStyle(style: unknown): this;
    getSource(id: string): MapLibreGeoJsonSource | undefined;
    addSource(id: string, source: unknown): this;
    removeSource(id: string): this;
    getLayer(id: string): unknown;
    addLayer(layer: unknown): this;
    removeLayer(id: string): this;
    setPaintProperty(layerId: string, name: string, value: unknown): this;
    hasImage?(id: string): boolean;
    addImage?(id: string, image: ImageData, options: { pixelRatio: number }): unknown;
    updateImage?(id: string, image: ImageData): unknown;
    removeImage?(id: string): unknown;
    queryRenderedFeatures(point: unknown, options?: {
      layers?: string[];
    }): unknown[];
  }`
  Import: `@aceshooting/lyra-ui/components/media/map/map-loader.js`.
  `MapLibreMarkerCapability {
    setLngLat(lngLat: [number, number]): this;
    setPopup(popup?: MapLibrePopupCapability): this;
    getPopup(): MapLibrePopupCapability | undefined;
    addTo(map: MapLibreMapCapability): this;
    remove(): void;
    getElement?(): HTMLElement;
  }`
  Import: `@aceshooting/lyra-ui/components/media/map/map-loader.js`.
  `MaplibreModule {
    Map: new (options: Record<string, unknown>) => MapLibreMapCapability;
    Marker: new (options?: {
      color?: string;
    }) => MapLibreMarkerCapability;
    Popup: new (options?: {
      offset?: number;
    }) => MapLibrePopupCapability;
  }`
  Import: `@aceshooting/lyra-ui/components/media/map/map-loader.js`.
  `MapLibrePopupCapability {
    setHTML(html: string): this;
    setText(text: string): this;
    on?(type: 'open' | 'close', listener: () => void): this;
    isOpen?(): boolean;
    getElement?(): HTMLElement | undefined;
  }`

- **`components-media-map-map-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/media/map/map.class.js`.
  `buildGeoJsonPropertyDiff(previous: unknown, next: unknown): MapLibreGeoJsonDiff | null`
  Import: `@aceshooting/lyra-ui/components/media/map/map.class.js`.
  `LyraMapChoroplethLayer {
    readonly sourceId: string;
    readonly geojson: FeatureCollection;
    readonly field: string;
    readonly stops: readonly (readonly [number, string])[];
    readonly interpolation?: LyraMapChoroplethInterpolation;
    readonly stepBaseColor?: string;
  }`
  Import: `@aceshooting/lyra-ui/components/media/map/map.class.js`.
  `LyraMapClusterOptions {
    readonly radius?: number;
    readonly maxZoom?: number;
    readonly radiusSteps?: readonly (readonly [number, number])[];
    readonly colorSteps?: readonly (readonly [number, string])[];
    readonly countFont?: readonly string[];
  }`
  Import: `@aceshooting/lyra-ui/components/media/map/map.class.js`.
  `LyraMapGeoJsonDataLayer {
    readonly sourceId: string;
    readonly geojson: Feature | FeatureCollection;
    readonly tone?: 'accent' | 'success' | 'warning' | 'danger' | 'neutral';
    readonly color?: string;
    readonly strokeColor?: string;
    readonly line?: LyraMapLineOptions;
    readonly point?: LyraMapPointOptions;
    readonly kind?: LyraMapDataLayerKind;
    readonly heatmap?: LyraMapHeatmapOptions;
    readonly cluster?: LyraMapClusterOptions;
  }`
  Import: `@aceshooting/lyra-ui/components/media/map/map.class.js`.
  `LyraMapHeatmapOptions {
    readonly weightField?: string;
    readonly weightRange?: readonly [number, number];
    readonly stops?: readonly (readonly [number, string])[];
    readonly radius?: LyraMapHeatmapZoomValue;
    readonly intensity?: LyraMapHeatmapZoomValue;
    readonly opacity?: number;
  }`
  Import: `@aceshooting/lyra-ui/components/media/map/map.class.js`.
  `LyraMapLineOptions {
    readonly field?: string;
    readonly stops?: readonly (readonly [number, string])[];
    readonly width?: number;
    readonly opacity?: number;
  }`
  Import: `@aceshooting/lyra-ui/components/media/map/map.class.js`.
  `LyraMapPointIcon {
    readonly value: string;
    readonly path: string;
    readonly viewBox?: readonly [number, number, number, number];
    readonly mode?: LyraMapPointIconMode;
    readonly strokeWidth?: number;
    readonly lineCap?: LyraMapPointIconLineCap;
    readonly lineJoin?: LyraMapPointIconLineJoin;
  }`
  Import: `@aceshooting/lyra-ui/components/media/map/map.class.js`.
  `LyraMapPointOptions {
    readonly field?: string;
    readonly colors?: readonly (readonly [string, string])[];
    readonly radius?: number | LyraMapPointRadiusOptions;
    readonly strokeWidth?: number;
    readonly strokeColor?: string;
    readonly iconField?: string;
    readonly icons?: readonly LyraMapPointIcon[];
    readonly iconColor?: string;
    readonly iconSize?: number;
  }`
  Import: `@aceshooting/lyra-ui/components/media/map/map.class.js`.
  `LyraMapPointRadiusOptions {
    readonly field: string;
    readonly stops: readonly (readonly [number, number])[];
    readonly interpolation?: LyraMapPointRadiusInterpolation;
    readonly fallback?: number;
  }`
  `LyraMapPointRadiusInterpolation = 'step' | 'linear'`;
  `LyraMapPointIconMode = 'fill' | 'stroke' | 'fill-stroke'`;
  `LyraMapPointIconLineCap = 'butt' | 'round' | 'square'`;
  `LyraMapPointIconLineJoin = 'miter' | 'round' | 'bevel'`.
  Import: `@aceshooting/lyra-ui/components/media/map/map.class.js`.
  `LyraMapInstance {
    getCanvas(): HTMLCanvasElement;
    getCenter(): {
      lng: number;
      lat: number;
    };
    getZoom(): number;
    setCenter(center: [number, number]): unknown;
    setZoom(zoom: number): unknown;
    resize(): unknown;
    setMaxBounds?(bounds?: unknown): unknown;
  }`
  Import: `@aceshooting/lyra-ui/components/media/map/map.class.js`.
  `LyraMapLegendEntry {
    readonly color: string;
    readonly label: string;
    readonly pattern: LyraMapLegendPattern;
    readonly icon?: LyraMapPointIcon | Omit<LyraMapPointIcon, 'value'>;
    readonly group?: string;
  }`
  Import: `@aceshooting/lyra-ui/components/media/map/map.class.js`.
  `LyraMapLegendProjection {
    readonly inputCount: number;
    readonly renderedCount: number;
    readonly omittedCount: number;
    readonly truncatedLabelCount: number;
    readonly truncated: boolean;
  }`
  Import: `@aceshooting/lyra-ui/components/media/map/map.class.js`.
  `LyraMapMarker {
    readonly id?: string;
    readonly lngLat: readonly [number, number];
    readonly color?: string;
    readonly label?: string;
    readonly unsafeHtml?: string;
  }`
  Import: `@aceshooting/lyra-ui/components/media/map/map.class.js`.
  `LyraMapMarkerActivationDetail {
    readonly id: string | undefined;
    readonly lngLat: readonly [number, number];
    readonly marker: LyraMapMarker;
    readonly source: LyraMapMarkerActivationSource;
  }`
  Import: `@aceshooting/lyra-ui/components/media/map/map.class.js`.
  `LyraMapLegendToggleDetail {
    readonly value: string;
    readonly visible: boolean;
    readonly hiddenCategories: readonly string[];
  }`
  Import: `@aceshooting/lyra-ui/components/media/map/map.class.js`.
  `LyraMapLegendPanelToggleDetail {
    readonly open: boolean;
  }`
  Import: `@aceshooting/lyra-ui/components/media/map/map.class.js`.
  `LyraMapStyleSpecification {
    readonly version: 8;
    readonly sources: Readonly<Record<string, unknown>>;
    readonly layers: readonly unknown[];
    readonly name?: string;
    readonly sprite?: string | readonly Readonly<{
      id: string;
      url: string;
    }>[];
    readonly glyphs?: string;
  }`

- **`components-media-media-card-media-card-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/media/media-card/media-card.class.js`.
  `LyraMediaCardOpenDetail {
    src: string;
    filename: string;
  }`

- **`components-media-sequence-playback-sequence-playback-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/media/sequence-playback/sequence-playback.class.js`.
  `LyraSequencePlaybackStepDetail {
    currentIndex: number;
  }`

- **`components-media-video-playlist-video-playlist-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/media/video-playlist/video-playlist.class.js`.
  `LyraVideoPlaylistChangeDetail {
    readonly previousIndex: number;
    readonly currentIndex: number;
    readonly video: LyraVideoPlaylistVideo;
  }`
  Import: `@aceshooting/lyra-ui/components/media/video-playlist/video-playlist.class.js`.
  `LyraVideoPlaylistItem {
    readonly title: string;
    readonly poster?: string;
    readonly duration?: number;
    readonly unavailable?: boolean;
  }`
  Import: `@aceshooting/lyra-ui/components/media/video-playlist/video-playlist.class.js`.
  `LyraVideoPlaylistSource {
    readonly src: string;
    readonly type: string;
    readonly media: string;
  }`
  Import: `@aceshooting/lyra-ui/components/media/video-playlist/video-playlist.class.js`.
  `LyraVideoPlaylistTrack {
    readonly src: string;
    readonly kind: string;
    readonly srclang: string;
    readonly label: string;
    readonly default: boolean;
  }`
  Import: `@aceshooting/lyra-ui/components/media/video-playlist/video-playlist.class.js`.
  `LyraVideoPlaylistVideo {
    readonly title: string;
    readonly poster: string;
    readonly sources: readonly LyraVideoPlaylistSource[];
    readonly tracks: readonly LyraVideoPlaylistTrack[];
  }`

- **`components-media-video-video-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/media/video/video.class.js`.
  `VideoState {
    playing: boolean;
    currentTime: number;
    duration: number;
    volume: number;
    muted: boolean;
    playbackRate: number;
  }`

# Charts (`components/charts/`)

## Breaking changes in 9.0.0

Breaking changes in this release (v9): `<lr-chart>` and `<lr-box-plot>` drop the deprecated
`accessible-label`/`accessible-description` attributes and `accessibleLabel`/`accessibleDescription`
properties — use the mirrored `label`/`description` instead (identical semantics, just renamed).
`<lr-box-plot>` drops the deprecated `boxes` property — use `datasets`. `<lr-lite-chart>` drops three
deprecated aliases: `pad-left`/`padLeft` (use `value-axis-gutter`/`valueAxisGutter`), `hide-axis`/
`hideAxis` (use `without-value-axis`/`withoutValueAxis`), and `selectedIndex` (use the grammatically
plural `selectedIndices`, which was already the canonical property). `<lr-chart>` drops its redundant
positive-polarity `legend` property/attribute, which duplicated `withoutLegend`/`without-legend` — the
legend now shows by default and is hidden only with `without-legend`; remove any `legend` attribute
from markup (it is now a no-op host attribute) and any `el.legend = true` from code (`<lr-box-plot>`
and `<lr-lite-chart>` are unaffected — their own `legend` property is each component's only visibility
toggle, not a duplicate). The deprecated type aliases `ChartPoint`, `Series` (superseded by
`LyraChartPoint`/`LyraChartSeries`), `BoxPlotPoint`, `BoxPlotSeries` (superseded by
`LyraBoxPlotSummary`/`LyraBoxPlotSeries`), and `LiteSeries` (superseded by `LyraLiteChartSeries`) are
removed — update TypeScript imports to the canonical `Lyra*`-prefixed names. The internal
`lockChartType` helper is no longer exported from the public `chart.ts` entry point; it is now used
solely by `<lr-histogram>` to keep its `type` fixed to `'bar'` — every other `lr-*-chart` subclass
keeps its `type` writable, matching its mirrored WA counterpart. `chart-core-loader.ts`'s v8 compatibility
facade is removed; `./components/charts/chart/chart-core-loader.js` and
`./components/charts/chart/chart-feature-loader.js` are now the real public entry points.

Non-breaking: `<lr-histogram>`'s `appendData()` is no longer marked deprecated; prefer the
histogram-specific `appendSamples(values, maxSamples?)` for new code. `<lr-lite-chart>`'s legend is
documented as a static color key with no interactive dataset-visibility toggle, matching its scope as
the lightweight chart variant; its own `accessibleLabel`/`accessible-label` property is unaffected by
the `lr-chart`/`lr-box-plot` removal above.

## `lr-chart` (core)

Chart.js wrapper used directly and by the eight typed Chart.js tags plus `lr-histogram`;
`lr-lite-chart` and `lr-box-plot` are independent implementations. It supports both a simplified
series surface and a raw Chart.js `config` passthrough (mirrors Web Awesome's `wa-chart` `config`
property).

For horizontal scalar bars, tooltip values come from parsed x rather than the category y, including
an effective raw `config.options.indexAxis` override. Both formatter APIs follow this rule;
structured points retain their y-value formatting.

**Properties:**
- `axes: LyraChartAxes = 'both'` — `'x' | 'y' | 'both' | 'none'`, controlling complete cartesian
  axes: labels, ticks, borders and grid lines. The `y` setting includes `y2`; invalid values use
  `both`. Radial charts ignore this setting. Use `grid` when only grid lines should disappear.
- `compact: boolean = false` — hides cartesian axes and removes automatic plot padding. Combine
  with `withoutLegend` and a short `height` (for example `64px`) for an inline histogram or
  sparkline. Tooltips, accessible data, formatting and keyboard activation remain available.
  `config` still wins over generated options, so explicit scale visibility or layout padding
  can override the preset. Leaving compact mode restores `axes`. Radial charts are unaffected.

  For a monthly histogram above `lr-slider`, give both controls the same inline allocation and
  use `lr-bar-chart compact without-legend height="64px"`. Map range values to bin edges: with
  twelve months, set the slider's `min=0`, `max=12`, `step=1` and treat its values as the half-open
  interval `[minValue, maxValue)`. Equal edges select no months. Use `show-value`,
  `value-display="formatted"` and `value-placement="label"` to display application-formatted month
  names without a separate readout listener. Commit filtering on `lr-change`; `lr-input` remains
  available for live previews. Chart categories retain their authored physical order: for an RTL
  slider that starts at the right edge, reverse both histogram labels and counts. The Monthly
  Range bar-chart story demonstrates both directions without scale configuration.
- `type: LyraChartType = 'bar'` — `LyraChartType = 'line' | 'bar' | 'scatter' | 'pie' | 'doughnut' |
  'radar' | 'polarArea' | 'bubble'` — every named default used by a typed `lr-*-chart` is
  already a first-class member, so `<lr-chart type="pie">` needs no subclass or cast to work;
  unknown runtime attribute/property values fall back to `bar` before reaching Chart.js
- `description: string | null = null` — accessible chart description
- `grid: 'x'|'y'|'both'|'none' = 'both'` — controls cartesian grid lines. On a radial chart, `x`
  controls angle lines and `y` controls concentric grid lines
- `indexAxis: 'x'|'y' = 'x'` (attribute `index-axis`) — Chart.js index axis. `'y'` is Chart.js's own
  mechanism for horizontal bars (it also flips `line`/`area` types onto a horizontal category axis).
  The `horizontal` boolean that used to alias `'y'` was removed in 9.0.0 — use `index-axis="y"`
- `label: string | null = null` — accessible chart label. Host `aria-label` has highest precedence
  by presence, including an explicit empty string
- `max: number | null = null`, `min: number | null = null` — finite value-axis bounds. They apply to
  the cartesian value axis selected by `indexAxis`, or the radial `r` scale; non-finite writes are
  omitted before Chart.js sees them
- `annotations: readonly LyraChartAnnotation[] = []` (attribute: false) — declarative reference
  lines and shaded bands: a threshold, an event year, a regime change, a highlighted period.
  `LyraChartAnnotation { axis?: 'x' | 'y'; value?: number; from?: number; to?: number; label?:
  string; tone?: LyraVariant }` — `tone` is the shared `LyraVariant` vocabulary
  (`'neutral' | 'brand' | 'success' | 'warning' | 'danger'`), not a chart-local copy. A finite `value` renders
  a reference line on that axis; a finite `from`/`to` pair renders a band bounded on that axis and
  spanning the other. `axis` defaults to `'y'`. An entry with neither (or non-finite numbers) is
  dropped rather than handed to Chart.js; a reversed range is normalized. Labelled entries are
  included in the generated accessible description, mirroring `lr-heatmap` — the label is
  consumer-supplied text and so is not localized, and an unlabelled line has no nameable meaning to
  announce. Needs the optional `chartjs-plugin-annotation` peer, loaded on first actual demand, so a
  page with no annotated charts never downloads it; without it the chart still renders, and a
  console warning plus a localized visible warning and light-DOM announcement explain the no-op.
  The plugin is registered globally, like `chartjs-plugin-zoom` and unlike
  `chartjs-plugin-datalabels`: it draws nothing unless a chart supplies annotation options, so the
  registration is unobservable to charts that set none, and registration is also what installs the
  plugin's own element defaults
- `scaleType: 'linear' | 'logarithmic' = 'linear'` (attribute `scale-type`, type
  `LyraChartScaleType`) — scale type for the **value** axis; the categorical axis is never
  affected. `'logarithmic'` plots data spanning several orders of magnitude (prices, latency
  percentiles, file sizes) honestly, where a linear axis collapses everything below the maximum
  into the baseline. Inherited by `lr-line-chart`, `lr-scatter-chart` and `lr-bar-chart`, and
  applied to the secondary `y2` axis too when one is present. A logarithmic axis cannot represent
  zero (`log(0)` is `-Infinity`), so `beginAtZero` is not forwarded in that mode and non-positive
  points are dropped by Chart.js's own log scale. Chart.js rejects an unregistered scale type at
  construction, so `LogarithmicScale` is registered with the core — it ships inside the `chart.js`
  module already loaded, adding no download weight
- `plugins: LyraChartPlugin[] = []` — peer-neutral per-instance Chart.js plugin structures,
  combined without duplicates with Lyra's
  on-demand data-label plugin and any `config.plugins` entries
- `labels: readonly string[] = []` (attribute: false)
- `datasets: readonly LyraChartSeries[] = []` (attribute: false) — `LyraChartSeries { readonly
  label: string; readonly data?: readonly (number|null)[]; readonly points?: readonly
  LyraChartPoint[]; readonly color?: string|readonly string[]; readonly stack?: string; ... }`. The
  deprecated `Series` and `ChartPoint` names were removed in 9.0.0 — import
  `LyraChartSeries`/`LyraChartPoint` instead.
  - `stack` is a Chart.js dataset `stack` group id: series sharing one `stack` value on the same
    (stacked) axis accumulate into one stack; a different id starts an independent stack Chart.js
    draws side by side with the first on that axis. Omitted series share one implicit group, so
    every chart written before `stack` existed sums exactly as it always did. Only meaningful on an
    axis that is actually stacked — see `stacked`/`stackedAxes` below.
  `LyraChartPoint { readonly x: number; readonly
  y: number; readonly r?: number; readonly label?: string }`: `r` is the bubble
  radius, and the optional per-point `label` is retained by events, CSV export, keyboard
  announcements, generated summaries, and the accessible table. Point wording is localized as
  whole messages: `chartPointCoordinates`, `chartBubblePointCoordinates`, and
  `chartLabeledPoint` own coordinate names, order, separators, and the label wrapper. A caller's
  point label is interpolated verbatim rather than translated or parsed. At runtime, non-record
  dataset entries are dropped while valid sibling series remain usable; an omitted `data`/`points`
  payload is still a valid empty series.
  - `pointRadius` takes a single number (applied to every point) **or** an array matching `data`'s
    length that sizes each point independently — passed straight through to Chart.js, which
    supports both natively. Useful for emphasizing a single outlier or the latest reading without
    splitting the series in two.
  - `segmentColors` colors each *segment* (the line drawn between two consecutive points) by the
    segment's **starting** point index, so `['red', 'green']` over 3 points paints the first
    segment red and the second green; a shorter array cycles. When rows are sampled, each
    represented segment retains the original source starting-point index modulo the palette length.
    Wired to Chart.js's
    `segment.borderColor` scriptable option, so it is only meaningful for line-type series.
    Typical use is threshold/anomaly banding along one line. A series that omits it (or passes an
    empty array) emits no `segment` key at all, leaving line rendering exactly as before.
- `hiddenDatasets?: readonly number[]` (attribute: false) — complete controlled DOM-legend
  visibility state. Leave it `undefined` (the default) to honor each effective dataset's declarative
  `hidden` value; pass `[]` to deliberately show every dataset, or a canonical list of zero-based
  indexes to hide those datasets. A defined value wins over the declarative defaults. Duplicate,
  non-integer, negative, and out-of-range indexes are discarded. The component writes the accepted
  legend-toggle snapshot back to this property so a host can persist it, and a programmatic write
  reconciles Chart.js and the DOM legend silently without emitting either legend-visibility event.
- `withoutLegend: boolean = false` (attribute `without-legend`, reflected) — the legend shows by
  default; set this to hide it. Renders a wrapping DOM legend (when shown) whose keyboard-operable
  buttons toggle dataset visibility. The DOM surface preserves long public labels that a canvas legend
  would clip. Its pressed state follows `hiddenDatasets` whenever that controlled snapshot is
  defined, otherwise the effective dataset's declarative `hidden` value before Chart.js is ready
  and across chart type/plugin rebuilds.
- `legendMode: LyraChartLegendMode = 'auto'` (attribute `legend-mode`) — `auto` resolves to `datum`
  on pie, doughnut and polar-area charts and to `dataset` everywhere else, so a single-dataset slice
  chart labels every slice rather than emitting one aggregate row that identifies only the first
  colour. `dataset` forces dataset toggles even on a slice chart. `datum` shows one category toggle
  per slice in pie, doughnut and polar-area charts; other types retain dataset legends. Category names use source labels with localized
  numbered fallbacks. Colors and values come from the first dataset. With multiple datasets/rings,
  a category toggle hides that source index in every ring, matching Chart.js category visibility.
- `hiddenDatums: readonly number[] = []` (attribute: false) — clone-owned hidden source category
  indexes for radial charts. `[]` restores all categories. Invalid, duplicate and out-of-range
  indexes are ignored when applied or emitted. Programmatic changes are silent; accepted datum
  legend toggles write the complete next snapshot. Data and type replacements, reconnection and
  sampling retain source-index meaning. This state is independent of `hiddenDatasets`; hiding a
  whole dataset continues to hide its ring. Accessible data and CSV export retain hidden values.
- `legendDisplay: LyraChartLegendDisplay = 'auto'` (attribute `legend-display`) — `auto` preserves
  the existing label with optional legend formatting. `label` always shows labels alone, even when
  `formatter`/`valueFormatter` supplies values for tooltips or axes. `value` appends the formatted
  numeric value. `percentage` appends a locale-formatted share independently of these callbacks:
  the denominator is the sum of absolute represented legend values, including hidden entries.
  `value-percentage` appends both, as `label: value (percentage)`. Dataset entries use sampled
  sums; category entries use the first dataset's represented values. Zero totals give 0%. The
  `formatter`/`valueFormatter` callback backing `value` and `value-percentage` also receives that
  same share as `percentage` in its `surface: 'legend'` context (`LyraChartFormatterContext`), so a
  custom formatter can render its own combined text without recomputing it from raw data. These
  options affect the DOM legend; tooltip/axis/table formatting is unchanged.
  Simplified pie/doughnut datasets with magnitudes above `Number.MAX_SAFE_INTEGER` are uniformly
  rescaled for finite canvas geometry. Lyra tooltips, data labels, legends, events and CSV retain
  original values; direct Chart.js callbacks see the rescaled peer data. Explicit `config.data`
  remains the unmodified full-fidelity escape hatch.
- `legendPosition: LyraChartLegendPosition = 'top'` (attribute `legend-position`) — accepts the
  Chart.js `left|top|right|bottom|center|chartArea|{ [scaleId]: number }` positions plus logical
  `start`/`end`; the additive `auto` chooses right above 480px and bottom below that allocation
  width. Logical positions swap under RTL, and a literal `left`/`right` stays on the physical edge
  it names in both directions — the rendered DOM legend honors both, so `legend-position="start"`
  really does paint at the reading-start edge under `dir="rtl"`
- `valueFormatter?: LyraChartValueFormatter` (attribute: false) — formats numeric (value-axis)
  tick, tooltip, legend, and generated accessible-table values; the callback receives the value
  and `'tick'`, `'tooltip'`, `'legend'`, or `'table'` context. Never runs against the categorical
  x-axis's own labels (line/bar's `labels` strings) — Chart.js's category scale passes the tick
  index to `ticks.callback`, not the label text
- `formatter?: LyraChartFormatter` (attribute: false) — the family-wide context-object formatter:
  `({ value, surface, datasetIndex?, index?, label?, seriesLabel?, statistic?, axis? }) => string`.
  `surface` identifies `visual`, `spoken`, `export`, `tick`, `tooltip`, `legend`, or `table`.
  `statistic`, when present for a structured datum or stack total, is one of `x`, `y`, `r`,
  `min`, `q1`, `median`, `q3`, `max`, or `total`. It takes precedence over the legacy positional
  `valueFormatter` where both are supplied. The legacy callback remains a visual/table compatibility
  hook; use `formatter` when a generated spoken value or CSV cell must use the same unit text.
  `axis` names the scale the number is plotted on — `'x'` wherever it carries numbers rather than
  categories (scatter/bubble, and a horizontal bar/line), `'y'`/`'y2'` for the two cartesian value
  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
  *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
  number. `lr-lite-chart`'s total cells drop the same two fields.
- `tooltipTitleFormatter?: LyraChartTooltipGroupFormatter` (attribute: false) — tooltip title
  formatter (e.g. a scatter point's own name). `LyraChartTooltipGroupFormatter = (items:
  readonly LyraChartFormatterContext[]) => string`: unlike `formatter`, which runs once per item,
  this runs once per tooltip render and receives every hovered item's context at once (one entry
  per dataset the tooltip covers, each in the same shape `formatter`'s `'tooltip'` surface already
  produces). Unset (the default) leaves Chart.js's own default title — the shared category label.
- `tooltipFooterFormatter?: LyraChartTooltipGroupFormatter` (attribute: false) — tooltip footer
  formatter (e.g. a category's stack total under the items), in the same shape and calling
  convention as `tooltipTitleFormatter`. Unset (the default) leaves Chart.js's own default: no
  footer.
- `area: boolean = false` — chart-wide default for whether line-type series fill the region under
  their line; a series's own `fill` overrides it, rendered with a translucent version of its color
- `zoom: boolean = false` — wheel/drag/pinch zoom on the `x` axis only (pan disabled, and the zoom
  range is limited to the original data extent); shows the `reset-zoom-button` while zoomed
- `height: string = '280px'` — a valid CSS length used only as the component's private fallback.
  A consumer-set `--lr-chart-height` always takes precedence; invalid values remove that fallback
  and likewise leave the public token/default in control.
- `xLabel: string | null = null` (attribute `x-label`)
- `yLabel: string | null = null` (attribute `y-label`)
- `y2Label: string = ''` (attribute `y2-label`)
- `beginAtZero: boolean = true` (attribute `begin-at-zero`)
- `stacked: boolean = false` — stacks the `x`/`y`(/`y2`) scale entries `buildScales()` returns; only
  meaningful for `bar`/`line` types (scatter/bubble's linear `x` scale and the radial `r` scale used
  by radar/polar-area are out of scope)
- `stackedAxes?: Partial<Record<'y' | 'y2', boolean>>` (attribute: false) — per-value-axis override
  of `stacked`, keyed by `'y'`/`'y2'`. An axis absent from this record — including every axis when
  the whole property is unset — falls back to `stacked`, so a chart that never sets this renders
  byte-identically to before. Lets a `stacked` bar series on the primary axis sit next to an
  unstacked overlay series on `y2` (via `LyraChartSeries.axis: 'y2'`): e.g. `stacked` plus
  `stackedAxes: { y2: false }`. The shared categorical axis (`x` for a vertical bar/line, or `y`
  under a horizontal `indexAxis`) has no entry of its own — it always mirrors the resolved `'y'`
  value, matching Chart.js's own paired index/value-scale stacking contract.
- `withoutAnimation: boolean = false` (attribute `without-animation`, reflected) — disables Chart.js
  construction animation; reduced-motion preference also disables it regardless of this value
- `withoutTooltip: boolean = false` (attribute `without-tooltip`, reflected) — disables the
  Chart.js tooltip plugin for this instance
- `dataLabels: boolean = false` (attribute `data-labels`) — draws each point's value on the chart via
  the optional `chartjs-plugin-datalabels` peer (see `peers.md`). Unset (the default) leaves labels
  off; because the plugin is registered **per chart instance** (not globally), a `<lr-chart
  data-labels>` never affects any other chart on the page. If the peer is unavailable or cannot
  register, the core chart remains usable, labels stay disabled, and a localized visible
  `feature-warning` plus assertive announcement explains the nonfatal limitation. The screen-reader
  equivalent is the always-present accessible data table (`show-data-table` makes it visible) —
  labels are a purely visual, canvas-only addition and add no new a11y surface.
- `stackTotals: boolean = false` (attribute `stack-totals`) — on an actually-stacked axis (`stacked`
  or `stackedAxes`, bar/line only), draws the per-category stack total above each stack, via the
  same `chartjs-plugin-datalabels` peer. Computed per `LyraChartSeries.stack` group as well as per
  axis: two stack groups sharing one axis each get their own total, drawn above their own topmost
  dataset, and a dataset on an axis that isn't stacked (e.g. an unstacked `stackedAxes` overlay)
  never gets one. Null/undefined points are skipped; a category whose every value is null shows no
  total (not `0`). The generated accessible table receives one formatted total column per stacked
  axis (a dual-axis stack gets separately labelled primary- and secondary-axis columns); with
  multiple stack groups on one axis, that column still totals only the implicit group of series
  that never set their own `stack` id — a per-group breakdown is available programmatically but not
  yet surfaced as extra table columns. The table totals do not depend on the optional visual-label
  peer being installed. If that peer is unavailable, the chart retains its core rendering and
  generated table totals while a localized nonfatal warning explains that the canvas labels cannot
  be drawn.
- `config?: LyraChartConfiguration` (attribute: false) — peer-neutral configuration structurally
  compatible with Chart.js's `ChartConfiguration`, deep-merged over the generated
  config; any nested key wins without clobbering sibling generated keys. This is the raw Chart.js
  escape hatch, so a caller-supplied `config.type` is passed through rather than normalized.
  Explicit `config.data.labels` and `config.data.datasets` arrays are authoritative independently:
  an omitted member still comes from the simplified `labels`/`datasets` properties, while an
  explicit array replaces that generated member rather than concatenating with it. This effective
  model drives canvas rendering, `appendData()`, export, the accessible name/summary, keyboard
  navigation and activation events, the DOM legend, and the generated fallback table.
  For generated **bar** series, an explicit series `width` wins. Otherwise authored bar
  `borderWidth`/`borderRadius` defaults in `options.datasets.bar`, its nested `elements.bar`,
  `options.elements.bar`, or root `options` are left for Chart.js to resolve, including scriptable,
  indexable and `barBorderWidth`/`barBorderRadius` forms. Unset values retain Lyra's `--border-width`
  and `--border-radius` defaults; removing config restores those defaults. Raw `config.data.datasets`
  remain authoritative. Dense charts with transparent borders should set
  `config.options.datasets.bar.borderWidth = 0` (or the public `--border-width: 0` CSS hook):
  a one-pixel transparent stroke can consume the fill of a bar narrower than two pixels.
  As a declarative alternative, place one `<script type="application/json">` in the default slot;
  an explicitly assigned `config` property wins over the slotted object. Invalid/non-object JSON is
  ignored without evaluating script or exposing prototype-pollution keys to the merge.
- `showDataTable: boolean = false` (attribute `show-data-table`) — makes the always-available
  accessible data table visible rather than screen-reader-only
- `dataTableToggle: boolean = false` (attribute `data-table-toggle`, new in 11.0.0) — renders a
  localized disclosure button (`part="data-table-toggle"`) above the data table so a *sighted*
  reader can reveal the numbers on demand. `showDataTable` alone is all-or-nothing, which left
  consumers wrapping a duplicated table in their own `<details>`. With the toggle on,
  `showDataTable` becomes the disclosure's **initial** state rather than its whole behavior; the
  table stays in the DOM in both states, so assistive technology never loses it, and the button
  carries `aria-expanded` plus `aria-controls` pointing at the `data-table` wrapper. Until the
  reader activates it, the disclosure follows `showDataTable`; afterwards the reader's selected
  state remains authoritative for that mounted chart. A supplied `slot="data-table"` follows this
  same disclosure state. Unset, nothing renders and behavior is identical to before.
- `chartArea: LyraChartArea | undefined` (readonly) — current Chart.js chart-area geometry in
  canvas-local coordinates (`top`, `left`, `right`, `bottom`, `width`, `height`), when a chart is
  drawn
- `chart: LyraChartInstance | undefined` (readonly-by-convention) — peer-neutral structural view of
  the live Chart.js instance; absent before load and after disconnect
- `appendData(label, values, maxPoints?)` — appends one aligned numeric category and optionally
  keeps only the newest `maxPoints`. Each labels/datasets member is written back to the surface
  that owns it: an explicitly overridden `config.data` member stays in `config`, while an omitted
  member continues through the simplified property and retains its generated Chart.js styling.
  Point-based scatter/bubble series are left unchanged because appending their x/y/r coordinates
  needs a richer caller-defined contract.

**Methods:** `renderChart()` requests a connected/visibility-gated render or incremental update.
`resetZoom()` resets any active zoom/pan to the original view. `refreshTheme()` forces
a redraw so the `--lr-chart-*` tokens below are re-read from the current computed style. A
built-in `ThemeWatcher` now calls this automatically when `prefers-color-scheme` flips or an
ancestor's `class`/`style`/`data-theme`/`data-color-scheme` attribute mutates — the most common
theme-toggle mechanisms — so a consumer rarely needs to call it by hand; it remains public as the
escape hatch for theme changes those signals can't observe. Canvas redraw remains visibility-gated;
when a DOM legend is present its computed swatch colors are refreshed too.
`exportData('csv' | 'png')` returns a spreadsheet-safe CSV snapshot or the current PNG data URL
when Chart.js is loaded. Numeric datasets retain the compact one-column-per-series CSV shape.
Point datasets expand into `<series> x`, `<series> y`, and, when present, `<series> r` and
`<series> label` columns so radius and per-point labels are not flattened away.

**The categorical series ramp.** Eight tokens, `--lr-color-chart-1` … `--lr-color-chart-8`, with a
separate set of values for light and dark mode. A series that sets no `color` of its own is assigned
one of them by index.

The ramp is **generated, not hand-picked**, by a search that maximises worst-case separation between
every pair of series under all three dichromacies, over a candidate pool that already clears 3:1
against the surface (WCAG 1.4.11 — a chart series is a non-text graphical object conveying data).
The consequence worth designing around: the ramp separates on **lightness** as well as hue. Hue is
exactly the channel colour-vision deficiency collapses, so two series that differ only in hue become
the same series under red-green colour blindness; lightness is the channel every form of colour
blindness preserves. That is also why the eight colours are not evenly lit — an evenly-lit
categorical ramp cannot satisfy the constraint at all.

The separation guarantee is *pairwise across all eight*, so any subset of the ramp — and any
ordering of it — inherits it; you can pick entries 1 and 5 as freely as 1 and 2. What forfeits the
guarantee is supplying your own colours through `Series.color` or replacing the ramp with a set
chosen by hue alone. An eight-hue set at one lightness looks tidier on screen and is unreadable to
the ~8% of men with red-green colour-vision deficiency.

**`--lr-theme-color-chart-1` … `-8` is the retheme hook.** Each internal `--lr-color-chart-N` reads
the matching `--lr-theme-color-chart-N` application input and falls back to the generated value, so
setting the theme inputs once at `:root` recolours every chart in the app with no per-component
override and no `::part()` rule. Charts are canvas-rendered, so a live theme change is picked up by
the built-in `ThemeWatcher` (or `refreshTheme()`) rather than by CSS alone.

Under `forced-colors: active` the ramp deliberately collapses onto the three system colors the mode
actually guarantees (`Highlight`/`LinkText`/`CanvasText`, cycling), so colour alone stops separating
more than three series there. The chart therefore adds a **non-colour encoding automatically** in
that mode, cycling eight variants by series index: a canvas fill pattern (stripes, crosshatch, dots,
checker), a `borderDash` stroke pattern, a `pointStyle` shape, and the matching texture on the DOM
legend's `legend-swatch`, which carries a `data-encoding` attribute naming the variant (`solid`,
`horizontal`, `vertical`, `diagonal`, `reverse-diagonal`, `crosshatch`, `dots`, `checker`). Nothing
is opt-in and no author colour is substituted. Direct labels via `dataLabels` are still worth adding
when a chart must stay readable with no legend at all.

The instance method `seriesPalette(): string[]` resolves that ramp through `getComputedStyle` and
returns the concrete, theme-aware colors — the exact same values the chart hands an uncolored
series, with any `--lr-theme-color-chart-*` override already applied.

The module also exports `seriesPalette(scope?: Element | null): string[]`, which can run before a
chart exists. Omit `scope` to read `document.documentElement`, pass an element to resolve its theme
scope, or pass `null` to request the light-mode fallback directly. When a scope has no component
token layer yet, the helper reads the `--lr-theme-color-chart-N` inputs directly. Both forms return
a fresh eight-color array each call (safe to mutate) and let chart-adjacent UI, KPI tiles, or the
`Series` array itself come from one source of truth.

The same module also exports `ChartThemeColors`, the resolved chrome colours a chart paints around
its series. Every field is an already-resolved CSS colour string, because canvas silently ignores a
raw `var(--lr-…)` string and would paint nothing; `<lr-box-plot>` consumes the same shape, so a
consumer drawing its own canvas overlay beside a chart can match the grid, tick, legend and tooltip
chrome exactly rather than re-deriving it.

Import the standalone form from `.../chart/chart-colors.js`, not from `.../chart/chart.js`: the
latter is `<lr-chart>`'s registration entry, so it defines the element (and pulls in `<lr-skeleton>`)
as a side effect. `chart-colors.js` is side-effect-free and carries nothing but the palette helpers,
so a KPI tile that only needs eight color strings stays a ~1KB import.

```ts
import { seriesPalette } from '@aceshooting/lyra-ui/components/charts/chart/chart-colors.js';

const colors = seriesPalette();
const series = [
  { label: 'Revenue', data: [12, 19], color: colors[0] },
  { label: 'Costs', data: [7, 11], color: colors[1] },
];
```

**Events:** `lr-zoom` (`detail: { zoomed: boolean }`, fired on zoom-complete and on
`resetZoom()`), `lr-point-click` (fired when pointer input lands on an intersecting data
point/segment, when a generated-table value is activated, or when Enter/Space activates the
keyboard-current canvas datum; `detail: { datasetIndex: number, index: number, label: string |
undefined, value: unknown }`). For scatter/bubble points, `label` prefers the per-point label and
`value` is the complete `LyraChartPoint`, including optional `r` and `label`.
`lr-datum-activate` emits the same activation with `kind: 'bar'|'point'|'segment'|'slice'` for
family-wide handling; `lr-point-click` remains as a compatibility event. Also
`lr-before-legend-visibility-change` (cancelable proposal), and
`lr-legend-visibility-change` (accepted commit). Both legend events carry
`{ datasetIndex: number, visible: boolean, hiddenDatasets: readonly number[] }`; the latter is the
complete, sorted, valid next snapshot. Call `preventDefault()` on the proposal to veto the toggle;
then no property change or commit event occurs.
Category toggles use a separate pair, `lr-before-datum-visibility-change` (cancelable proposal) and
`lr-datum-visibility-change` (accepted commit), carrying
`{ index: number, visible: boolean, hiddenDatums: readonly number[] }`. Both details and their
complete, sorted index snapshots are frozen. `index` is the source category index, including when
the displayed data is sampled; it applies across all rings. Programmatic assignments emit neither
pair. `preventDefault()` leaves both controlled state and the chart unchanged.

```html
<lr-doughnut-chart
  legend-mode="datum"
  legend-display="label"
  .labels=${['A', 'B', 'C']}
  .datasets=${[{ label: 'Distribution', data: [5, 3, 2] }]}
  .hiddenDatums=${[]}
></lr-doughnut-chart>
```

**Slots:** default — one optional `<script type="application/json">` Chart.js configuration;
`data-table` — an optional consumer-provided complete, paginated, or virtualized accessible table
alternative; `center` —
optional overlay content positioned at the chart area's center, useful for doughnut and pie totals.

**Bounded rendering and data alternative:** simplified `labels`/`datasets` canvas rendering, the
DOM legend, generated table, keyboard-operable datum model, generated point-details in the summary,
and automatic canvas name process at most 1,000 category×series records. When sampling is necessary,
the selected category and series indexes are distributed
deterministically and retain their first and last endpoints; a localized `data-truncation` notice
is shown and announced. Supplying `slot="data-table"` suppresses the generated detailed sample and
notice, so use that escape hatch when the complete data set needs pagination, virtualization, or
another application-owned presentation. Explicit `config.data` is the deliberate full-fidelity
Chart.js escape hatch and is not rewritten by the simplified-surface sampler.

**CSS parts:** `base`, `plot` (the fixed-height canvas/overlay region), `canvas`, `legend` (the
wrapping DOM legend), `legend-item` (a dataset/category visibility button), `legend-item-hidden`
(added while the dataset/category is hidden), `legend-swatch`,
`reset-zoom-button`, `description`, `notices` (wrapper for nonfatal feature warnings and
bounded-alternative truncation notices), `data-table`, `data-table-toggle` (the `dataTableToggle` disclosure button), `data-truncation` (the bounded-alternative
notice), `feature-warning` (a nonfatal missing optional-feature warning), `center` (the
chart-area-centered wrapper for the `center` slot), `error` (neutral visible message rendered in
place of `canvas` when the optional `chart.js` peer dependency fails to load; the failure transition
is announced through the shared document-level light-DOM assertive sink)

**Themeable custom properties:** `--lr-chart-height` (the public, consumer-owned plot-height hook;
it sizes the `plot` region and the host's minimum block size, while a visible table or wrapping
legend grows the host in normal flow. The `height` property writes only a private fallback, so this
public token wins across valid, invalid, and unset `height` updates. Set it on the host or an
ancestor, not a shadow-tree descendant, since custom properties only cascade downward);
`--lr-chart-grid-color` (default `var(--lr-color-border)`),
`--lr-chart-tick-color` (default `var(--lr-color-text-quiet)`), `--lr-chart-legend-color`
(default `var(--lr-color-text)`), `--lr-chart-tooltip-bg` (default `var(--lr-color-surface)`),
`--lr-chart-tooltip-text` (default `var(--lr-color-text)`) — each resolved fresh via
`getComputedStyle` on every draw (Chart.js renders to canvas, not the DOM, so it can't consume CSS
`var()` directly), driving the grid lines, tick labels **and axis titles** (`xLabel`/`yLabel`/
`y2Label` title text reuses `--lr-chart-tick-color` too — there's no separate title-color token),
legend text, and tooltip background/text respectively; `--lr-chart-tick-font-size` (default
`var(--lr-font-size-xs)`, any CSS length unit) — the axis tick-label font size, same
`getComputedStyle` resolution and same token *name* as `lr-lite-chart`'s SVG equivalent, though not
the same default: `--lr-font-size-xs` is 12px at the standard root, matching Chart.js's own
built-in tick font size that every canvas chart rendered before this token existed, while
`lr-lite-chart`'s SVG axis labels default to the smaller `--lr-font-size-2xs` (10px), unchanged
from before this token existed. Also sizes the radar/polarArea `r`-scale `pointLabels` (the spoke
labels) once set, but NOT by default: Chart.js's `RadialLinearScale` gives `pointLabels` its own
distinct built-in default (10px, not this token's 12px tick default), so leaving the token unset
keeps that separate default rather than adopting the tick size; setting the token brings both the
ticks and the point labels to the same size; plus
`--lr-chart-legend-item-hover-bg` / `--lr-chart-legend-item-active-bg`,
`--lr-chart-data-table-button-hover-bg` / `--lr-chart-data-table-button-active-bg`,
`--lr-chart-data-table-toggle-hover-bg` / `--lr-chart-data-table-toggle-active-bg` (the
`dataTableToggle` disclosure button), and
`--lr-chart-reset-zoom-button-hover-bg` / `--lr-chart-reset-zoom-button-active-bg` — independent
background hooks for each DOM control's hover and pressed states. Hover defaults to
`--lr-color-brand-quiet`; pressed defaults to its standard active color mix. Override one pair
without repainting the other controls;
`--lr-chart-legend-side-max` (default `var(--lr-size-15rem)`) caps the side-positioned legend track;
the responsive grid also limits it to one third of the chart allocation and stacks it below the
plot in narrow containers;
`--lr-chart-canvas-hover-outline-width` (default `var(--lr-border-width-thin)`) — the width of
`[part="canvas"]`'s own `:hover` outline. Unlike the tokens above, this one is a real CSS
declaration on a DOM element (the outline is painted by the stylesheet, not by Chart.js), so it is
consumed directly with no `getComputedStyle` bridging; it is an inline `var()` fallback at the point
of use, so it can be set on the element or any ancestor, and left unset the outline is exactly the
`--lr-border-width-thin` it always was. `--lr-chart-canvas-hover-outline-color` (default
`var(--lr-chart-grid-color)`) independently controls that outline's color.

`--lr-chart-pattern-step` (default `var(--lr-space-2xs)`) is the tile size of the texture painted on
`[part="legend-swatch"]` while `forced-colors: active` matches — the legend half of the non-colour
encoding described under "The categorical series ramp" above, and the reason repeated system colours
stay tellable apart in the DOM legend. It has no effect outside forced colors, where the swatch is a
plain colour chip. It scales the tile, not the mark inside it: the stripe/crosshatch line width
stays `--lr-border-width-thin` and the `dots` radius stays absolute, so a larger step spaces those
marks further apart rather than thickening them (the percentage-based `checker` variant is the one
that scales with the step). It does not touch the **canvas** pattern, whose 8×8 bitmap geometry is
part of the encoding algorithm and is not themeable. Unlike
the properties above it is declared by the shadow stylesheet on the swatch itself, not inherited
from the host, so setting it on `lr-chart` does nothing — override it through the part:

```css
lr-chart::part(legend-swatch) {
  --lr-chart-pattern-step: 0.5rem;
}
```

Plus shared `--lr-space-xs`.

The mirrored Chart styling hooks are also available on all nine tags. All canvas-bound values are
resolved to concrete colors/CSS-pixel numbers on every draw; `rem` uses the live root font size and
`em` uses the chart's own font size rather than a hard-coded conversion.

- `--border-color-1`, `--border-color-2`, `--border-color-3`, `--border-color-4`,
  `--border-color-5`, `--border-color-6` — first six dataset/slice stroke colors, each falling back
  to matching `--lr-color-chart-N`
- `--fill-color-1`, `--fill-color-2`, `--fill-color-3`, `--fill-color-4`, `--fill-color-5`,
  `--fill-color-6` — first six dataset/slice fill colors, with the same Lyra
  palette fallbacks. A directly authored fill is used as-is; an unoverridden line-area fallback
  retains Lyra's translucent area treatment
- `--border-radius` → `--lr-radius`; `--border-width` → `--lr-border-width-thin`
- `--grid-border-width` → `--lr-border-width-thin`; `--grid-color` →
  `--lr-chart-grid-color`
- `--line-border-width` → `--lr-border-width-medium`; `--point-radius` → `--lr-space-2xs`

**Optional peer deps:** `chart.js` (mandatory peer, lazy-imported on every `connectedCallback()`
regardless of options), `chartjs-plugin-zoom` (lazy-imported *additionally* only when `zoom` is — or
later becomes — `true`; never fetched for a chart that keeps `zoom` unset/false, since the plugin
has a hard dependency on `hammerjs`), `chartjs-plugin-datalabels` only when `data-labels` or
`stack-totals` is enabled, and `chartjs-plugin-annotation` only when `annotations` contains a usable
entry. Each capability load is memoized once per page, registering only the tree-shaken
controller/element/scale subset actually used. A failed zoom, data-label, or annotation peer is not
a failed chart: the canvas, legend, and accessible alternative remain usable; the requested
enhancement is disabled and a localized static `feature-warning` is visibly rendered and
announced. In particular, unavailable data labels do not remove generated table totals.

```html
<lr-chart type="line" x-label="Day" y-label="kWh"></lr-chart>
<script>
  const c = document.querySelector('lr-chart');
  c.labels = ['Mon', 'Tue', 'Wed'];
  c.datasets = [{ label: 'Production', data: [12, 19, 7], color: '#2563eb' }];
</script>
```

**Known gotchas:**
- supported `type` values are normalized before reaching Chart.js; unknown runtime attribute or
  property values fall back to `bar`. Each typed `lr-*-chart` tag supplies its named chart type as
  a default while retaining the mirrored writable `type` surface.
- a built-in `ThemeWatcher` automatically rethemes an already-drawn chart when
  `prefers-color-scheme` flips or an ancestor's `class`/`style`/`data-theme`/`data-color-scheme`
  attribute mutates (coalesced to one redraw). `refreshTheme()` stays public for out-of-band theme
  changes those signals can't observe.
- the focusable canvas is an interactive `application`, not a static image: Arrow keys move through
  finite data, Home/End jump to the endpoints, and Enter/Space activates the current datum. Its
  localized `aria-roledescription` identifies the application as a chart; the generated table is
  the non-canvas alternative.
- generated `scales` are keyed off the *effective* type (`config.type` ?? `type`, see
  `effectiveType()`) and are type-appropriate: no scale at all for `type="pie"`/`"doughnut"` (true of
  `<lr-chart type="pie">` directly, not just the `lr-pie-chart`/`lr-doughnut-chart` subclasses),
  and a single radial `r` scale (respecting `beginAtZero`) for `type="radar"`/`"polarArea"`
  (`lr-radar-chart`/`lr-polar-area-chart`), instead of always generating the cartesian `x`/`y`/
  `y2` block. `xLabel`/`yLabel`/`y2Label` are still silently inert for all four of those types (a
  radial scale and "no scale" both have nowhere to put an axis title) — reach a titled radial scale
  only via raw `config`.
- `annotations` loads and registers `chartjs-plugin-annotation` on first actual demand; consumers
  do not hand-register it or route ordinary reference lines/bands through raw `config`. A chart
  with no usable annotations never requests the peer. Raw `config` remains the escape hatch for
  plugin-specific annotation options outside the declarative surface.
- while the `chart.js` peer is resolving, `render()` swaps in a `<lr-skeleton shape="rect">` for
  the canvas, and the **host element itself** (not the skeleton) carries `aria-busy="true"` — set/
  cleared in `updated()` off the private `loading` state (same lazy-load pattern as
  `lr-graph`/`lr-map`/`lr-flag`). Chart.js's own ~1000ms draw-in animation only ever fires on
  initial construction or a type change that rebuilds the `Chart` instance (every in-place data
  update already passes `'none'` to `Chart#update()` and never animates regardless); that
  construction-time animation is additionally skipped when `without-animation` is set or under
  `prefers-reduced-motion: reduce`.
  The raw `config` passthrough is deep-merged with `__proto__`/`constructor`/`prototype` keys skipped
  unconditionally, so a JSON-sourced `config` (e.g. parsed from an API response) can't reach up and
  pollute `Object.prototype` through the merge.
- lazy-redraw + change gating: with `IntersectionObserver` available, canvas construction waits
  for its first delivered visibility decision. Off-screen charts remain unconstructed until
  visible, and later off-screen property changes skip redraws until visibility returns. Without
  the observer, drawing starts when the peer and canvas are ready. An empty delivered callback
  retains the visible fallback. Peer loading and accessible DOM may settle while visibility is
  pending. Independently, `updated()` only reaches
  Chart.js when at least one of `type`, `labels`, `datasets`, `description`, `grid`, `axes`, `compact`, `indexAxis`,
  `label`, `hiddenDatasets`, `legendPosition`, `min`, `max`, `plugins`, the internal resolved auto legend
  position, `valueFormatter`, `formatter`, `tooltipTitleFormatter`, `tooltipFooterFormatter`, `area`,
  `height`, `xLabel`, `yLabel`, `y2Label`, `beginAtZero`,
  `stacked`, `stackedAxes`, any `without*` control, `dataLabels`, `stackTotals`, `config`, the parsed
  slotted config, `zoom`, `locale`, `strings`, or the internal loading state actually changed in
  that update (so an
  unrelated property/state update, or a bare `requestUpdate()`, draws nothing). Resize callbacks
  ignore unchanged inline sizes and coalesce into one animation-frame task; a responsive legend
  position change and its reactive update share that same single redraw. `refreshTheme()`, resize,
  optional-plugin completion, and histogram data changes all use the same connected/visible gate.
  A theme refresh may still rerender the cheap DOM legend while off-screen so its computed swatches
  do not go stale, but it does not repaint the canvas there.
- Chart.js receives `effectiveLocale`; generated summary values use the same locale. Cartesian y/y2
  axes swap logical sides under RTL, and host `aria-label` is forwarded to the canvas and data-table
  caption.

---

## `lr-lite-chart`

A dependency-free bar/line chart — plain SVG/DOM rendering, zero peer dependencies (unlike
`lr-chart`, which wraps `chart.js`). For a project whose architecture forbids a charting
dependency outright: covers grouped/stacked bars, multi-series lines, per-point click, and hover
tooltips (native SVG `<title>`, no positioning JS) — not a full `lr-chart` replacement (no
zoom/pan, no pie/doughnut/radar/scatter/bubble types, no horizontal/dual-y-axis, no raw-config
passthrough). Not a subclass of `LyraChart`.

Deliberate omissions, assessed and not implemented: `lr-chart`'s per-series `LyraChartSeries.stack`
group and per-axis `stackedAxes` have no `lr-lite-chart` counterpart. `stacked` here is already
chart-wide only (see below) and this component has exactly one value scale — no `y2` — so "an
unstacked overlay on a second axis," the motivating case for `stackedAxes`, has no equivalent
shape to express. A per-series stack-group id would also need the hand-rolled SVG bar-geometry
pass (linear/sqrt/log stack compression, `minBarHeight`) to track independent running offsets per
group instead of one per category, which is a materially larger, higher-risk change than this
component's existing single-stack model. `tooltipTitleFormatter`/`tooltipFooterFormatter` are
similarly absent: this component's hover tooltip is a native SVG `<title>` on each mark — one
self-contained string per mark, generated by `pointText` — not a Chart.js-style multi-item tooltip
with separate title/body/footer regions for several datasets sharing a hovered category, so there
is no "every item in the tooltip" surface to hook a title or footer formatter onto.

**Properties:**
- `type: LyraLiteChartType = 'bar'` — `'bar' | 'line'`
- `labels: readonly string[] = []` (attribute: false)
- `datasets: readonly LyraLiteChartSeries[] = []` (attribute: false) —
  `LyraLiteChartSeries { readonly label: string; readonly data: readonly (number|null)[];
  readonly color?: string }`. The legacy `LiteSeries` name was removed in 9.0.0 — import
  `LyraLiteChartSeries` instead.
  `color` accepts a valid CSS `color`, while invalid values,
  declaration-breaking input, and `url()` paint servers fall back to the built-in palette. A
  runtime entry whose required `data` member is not an array is dropped while valid siblings
  continue to render.
- `legend: boolean = false`
- `legendPosition: 'top'|'bottom'|'start'|'end' = 'bottom'` (attribute `legend-position`) — logical
  placement for the DOM legend; side positions are bounded and stack responsively in narrow hosts
- `label: string | null = null`, `description: string | null = null` — canonical accessible name
  and description; host `aria-label` wins by presence, including an explicit empty string
- `accessibleLabel?: string` (attribute `accessible-label`) — overrides the `<svg>`'s auto-derived
  `aria-label` (`datasets.map(d => d.label).join(', ') || 'Chart'`); a host `aria-label` still wins.
  Unset keeps the auto-derived (English-fallback) label. `lr-lite-chart` keeps this property under
  its original `accessible-label` name, unrelated to the deprecated `accessible-label` alias that
  `lr-chart`/`lr-box-plot` dropped in favor of their mirrored `label` property.
- `height: string = '280px'` — accepts a valid CSS `height` as a private fallback. A consumer-set
  `--lr-chart-height` always wins; invalid values, declaration-breaking input, and `url()` remove
  the fallback and leave the public token/default in control.
- `xLabel: string = ''` (attribute `x-label`)
- `yLabel: string = ''` (attribute `y-label`)
- `beginAtZero: boolean = true` (attribute `begin-at-zero`)
- `stacked: boolean = false` — sums each category's bars into one segmented bar instead of grouping
  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.
- `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.
  Every surface names this chart's single value scale as `axis: 'y'`, and the `visual` surface now
  carries the category `index` as well as the series, so one formatter written against
  `lr-chart`'s dual-axis context serves both components unchanged.
- `tableCellFormatter?: LyraLiteChartTableCellFormatter` (attribute: false) — formats each finite
  numeric cell in the built-in multi-series accessible table. The callback receives `(value,
  context)`, where `context` is `{ kind: 'value' | 'total'; datasetIndex: number | null; index:
  number; label: string; seriesLabel: string | null }`; total cells have `datasetIndex` and
  `seriesLabel` set to `null`. Unset cells retain locale-aware `Intl.NumberFormat` output.
- `tableTotals: boolean = false` (attribute `table-totals`) — adds a localized total column to the
  multi-series accessible table when `type="bar"` and `stacked` are both active. Ignored for
  grouped bars, line charts, and the single-series `data-list`.
- `showDataTable: boolean = false` (attribute `show-data-table`, new in 11.1.0) — makes the
  generated accessible table visible rather than screen-reader-only. Same meaning as `lr-chart`'s
  property of the same name.
- `dataTableToggle: boolean = false` (attribute `data-table-toggle`, new in 11.1.0) — renders a
  localized disclosure button (`part="data-table-toggle"`, with `aria-expanded` and
  `aria-controls`) above the table, so a *sighted* reader can reveal the numbers on demand;
  `showDataTable` then becomes the disclosure's **initial** state rather than its whole behavior.
  The table stays in the DOM in both states, so assistive technology never loses it. This matters
  more here than on `lr-chart`: this component exists to avoid the Chart.js peers, so without it an
  app that chose it for exactly that reason had to either hand-roll a `<details>` around a
  duplicated table or adopt `lr-chart` and pull in Chart.js for a button — the cheap component
  stuck with the expensive workaround. A supplied `slot="data-table"` follows the same disclosure
  state. Unset, nothing renders and behavior is unchanged.
  Themeable via `--lr-lite-chart-data-table-toggle-hover-bg` (default
  `var(--lr-color-brand-quiet)`) and `--lr-lite-chart-data-table-toggle-active-bg` (default: that
  hover colour mixed by `--lr-color-mix-active`).
- `layout: 'fit' | 'scroll' = 'fit'` (reflected) — `'fit'` (default) is the original squeeze-the-
  whole-plot-to-host-width behavior, unchanged. `'scroll'` gives bars a fixed `barWidth` instead: plot
  content width becomes `categoryCount * barWidth` (can exceed the host's measured width), and
  `[part='base']` becomes horizontally `overflow-x: auto` so the user scrolls to see every bar at a
  legible fixed width instead of them compressing as category count grows. The plot content width
  is capped at 1,000,000px, so hostile category counts or widths cannot produce
  unbounded geometry. Bar type only.
- `barWidth: number = 32` (attribute `bar-width`, px) — each bar's fixed width in `layout="scroll"`
  mode; ignored in the default `'fit'` mode. An excessive value is reduced as needed by the
  1,000,000px scroll-content ceiling.
- `maxLabels?: number | 'auto'` (attribute `max-labels`) — decimates which category axis labels
  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.
- `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
  (see that component's own `columnX`) by supplying the same coordinate function to both. Unset (the
  default) is the original formula, unchanged. The callback runs once per rendered category per
  render and its finite result is shared by that category's bars and label; a non-finite result
  falls back to the normal slot position.
- `pointText?: (label: string, value: number, datasetIndex: number) => string` (attribute: false) —
  overrides the per-bar/per-point native SVG `<title>` text (mirrors `lr-heatmap`'s `cellText`).
  The same text is written to `aria-label`, because WebKit accessibility APIs do not consistently
  derive an ARIA command name from an SVG `<title>`; the title remains the native browser tooltip.
  Falls back to the built-in raw-value template when unset.
- `legendText?: (label: string, datasetIndex: number) => string` (attribute: false) — appends
  formatter-supplied text (e.g. a value or percentage share) after each series' label in the
  built-in legend row, mirroring `pointText`/`tickFormat`'s opt-in-hook convention. Falls back to
  the label alone when unset; no-op while `legend` is `false`.
- `axisLabelText?: (label: string, index: number) => string | null` (attribute: false) — a
  display-only override for one category-axis tick's text; returning `null` renders no tick there at
  all. `labels` stays the single authoritative source for the generated accessible table's row
  headers, the per-mark `<title>`/accessible name, the live announcement and CSV export, so blanking
  a tick never blanks the same category where a reader or a spreadsheet needs it. Complements
  `maxLabels` rather than replacing it: that even decimation is applied FIRST, so a category it
  already dropped never reaches this callback — use this one for ticks that must line up with an
  external grouping boundary (a month, a release, a shift change) and leave `maxLabels` unset there.
  The returned string is ellipsized to the tick's own slot exactly like a source label, with the
  full text kept as the tick's accessible name; a return value that is neither a string nor `null`
  falls back to the source label rather than reaching the DOM.
- `roundedBars: boolean = false` (attribute `rounded-bars`, bar type only) — draws each bar as a
  rounded-top-corner shape instead of a square-cornered `<rect>`.
- `skipZero: boolean = false` (attribute `skip-zero`, bar type only) — omits a bar entirely (no
  mark/tabindex/tooltip) for a value that is exactly `0`; `null`/non-finite values are always
  skipped regardless.
- `valueAxisGutter?: number | 'auto'` (attribute `value-axis-gutter`) — value-axis gutter width in
  CSS px. A finite number is authoritative (clamped to 0…1,000,000px as before). `'auto'` sizes the
  gutter from the exact value-tick strings rendered in that pass — `formatter` output first, then
  `tickFormat`, then the component's `effectiveLocale` number formatting — using the deterministic
  7px-per-character estimate plus 14px for the tick offset and font-width variance. Automatic
  sizing never shrinks below the legacy 36px default. In `layout="fit"` it is bounded to the smaller
  of 240px or 40% of the measured SVG width, so a pathological formatter result cannot consume the
  plot. In `layout="scroll"` the cap is 240px: that SVG has an explicit content width, so deriving a
  percentage cap from its own ResizeObserver result would create a shrinking feedback loop. The
  gutter remains at logical start under RTL. Unset keeps exactly 36px.
- `barGapRatio?: number` (attribute `bar-gap-ratio`) — overrides the internal 0.2 `BAR_GROUP_GAP`
  fraction of a category slot left as a gap between categories. Unset keeps the fixed 0.2. Internal
  grouped-bar gaps are bounded within the remaining category width so supported multi-series groups
  retain positive, nonoverlapping bars for ratios below 1. A ratio of 1 reserves the whole slot as
  gap and leaves zero-width bars.
- `scale: 'linear' | 'sqrt' | 'logarithmic' = 'linear'` — `'sqrt'` (**bar type only**) maps a bar's
  value to height via `Math.sqrt(value / domainMax)` instead of the standard linear `niceDomain`
  fraction (mirroring `lr-heatmap`'s matrix-mode `sqrt` scale), so a skewed dataset's smaller bars
  aren't washed out by one dominant value; under `'sqrt'` gridlines/tick labels stay on the linear
  domain and `type="line"` ignores it entirely.
  `'logarithmic'` is the base-10 value axis for data spanning several orders of magnitude, where a
  linear axis collapses everything below the maximum into the baseline. Unlike `'sqrt'` it applies
  to **bars, line points and gridlines alike**, since a log axis whose gridlines stayed linear
  would misrepresent the plot. Value ticks use positive, bounded steps within that same domain:
  powers of ten across whole decades, with positive numeric steps for spans smaller than a decade.
  Both domain bounds remain represented, with space reserved between interior ticks and the bounds.
  Linear and square-root tick selection is unchanged. Its lower bound is the smallest *positive* datum rather than the
  linear `lo`: `beginAtZero` defaults to true, so `lo` is normally `0`, which has no logarithm —
  deriving the floor from the data is what makes a 1…1000 series span three even decades instead of
  collapsing onto one. Values at or below that floor (including zero and negatives, which have no
  real logarithm) pin to the axis floor rather than producing `-Infinity` geometry, and a degenerate
  domain falls back to the linear fraction. `lr-chart`'s own `scaleType` is the Chart.js-backed
  equivalent for the full charts. With `stacked` and `'logarithmic'`, the finite sum of positive
  raw values determines the log-mapped total extent; positive raw fractions partition that extent.
  Nonpositive segments have zero natural log height. With `minBarHeight` unset, the stack stays
  within the plot and its top agrees with the log axis. The square-root mode retains its separate
  signed-total compression and proportional allocation, with linear gridlines.
- `withoutValueAxis: boolean = false` (attribute `without-value-axis`) — suppresses gridlines and
  value-axis tick labels; x-axis category labels remain.
- `selectedIndices: readonly number[] = []` (attribute: false) — names **source category indices**,
  not positions in the sampled SVG output. Finite integer entries whose source rows are represented
  in the bounded rendered sample select matching bars and line points, which receive
  `data-selected` and explicit `aria-pressed="true"`; all other marks render `aria-pressed="false"`.
  For a multi-series chart, a selected source category selects the matching rendered mark in every
  dataset. Empty is the default.
  Style the built-in highlight through `--lr-lite-chart-selected-outline-color` and
  `--lr-lite-chart-selected-outline-width`. Note
  `::part(bar)[data-selected]` and `::part(point)[data-selected]` are **invalid CSS** — Shadow Parts
  forbids an attribute selector after `::part()` — so they silently never match; the outline is
  painted inside the shadow root and exposed through that token instead.
- `labels`, `datasets`, and `selectedIndices` are clone-owned, bounded, frozen snapshots. Mutating
  a previously assigned array or nested series data has no effect; create and reassign a new
  collection.
- `minBarHeight?: number` (attribute `min-bar-height`) — optional minimum visible bar height for
  small non-zero values; finite input is capped at 1,000,000px before derived SVG geometry is
  calculated. Authored floors can exceed the available plot height. Linear and logarithmic stacks
  push subsequent segments along their signed pixel cursor; zero values remain unfloored.
- `appendData(label, values, maxPoints?)` — appends one aligned category and optionally trims the
  oldest categories

**Events:** `lr-datum-activate` — canonical family activation with `kind: 'bar'|'point'`,
`datasetIndex`, `index`, `label`, and `value`. The compatibility `lr-point-click` event is emitted
for the same pointer or Enter/Space activation. When different series' expanded
line-point targets overlap, pointer activation selects the closest rendered point in two-dimensional
screen space; an exact distance tie retains the point whose target received the click.

**Methods:** `exportData('csv' | 'svg')` returns a spreadsheet-safe CSV snapshot or the current SVG
markup. CSV rows cover the canonical record count — the maximum of `labels.length` and every
`dataset.data.length` — and use empty cells for missing labels/values, so a longer or ragged series
is never truncated or shifted. The method does not download a file; pair it with
`lr-export-button` for download UX.

Axis titles retain their complete `xLabel`/`yLabel` values and accessible names. In the browser,
visible titles fit their plot allocation using the rendered SVG font; long titles end with an
ellipsis. If even the ellipsis cannot fit, the title remains accessible without painting text.
Fitting refreshes after rendering, allocation changes, inherited or host font changes, font loading,
and reconnection. Server rendering retains the original title until browser layout is available.

The axis gutter/title and y-axis labels mirror to logical start under RTL. The first and last
rendered category-axis tick labels anchor toward the plot's interior (`text-anchor="start"`/`"end"`)
instead of centering, so a long boundary label (e.g. a wide date string) never overhangs past the
plot's own clipped edge; every other tick still centers. Because SVG's `start`/`end` anchors already
mirror with the inherited `direction: rtl`, and the plot's own boundary swaps sides with it too, this
anchoring keeps working correctly under RTL without inverting which rendered category gets which
keyword. Built-in mark summaries are complete localized templates and format values with
`effectiveLocale`.

**Performance:** `render()` recomputes the grid/marks on every update rather than memoizing against a
content signature — `datasets`/`labels` can hold callbacks (`tickFormat`, `barX`) or arbitrary,
possibly circular or BigInt-bearing application data that a fingerprint can't serialize safely, so a
fresh, small SVG render is cheaper and more correct than a lossy cache. The shared sampling path
keeps that render bounded to 1,000 category×series marks/keyboard records, retaining endpoints
instead of materializing an unbounded hidden DOM or SVG tree.

**Slots:** `data-table` — optional consumer-provided complete, paginated, or virtualized accessible
data alternative.

**CSS parts:** `base`, `description`, `grid-line`, `axis-label`, `axis-title`, `bar` and `point` (each carries
`data-selected` when its category index is in `selectedIndices`, with explicit pressed state on every
mark), `line`, `legend`, `legend-item`, `legend-swatch`, `legend-text` (extra per-item text after
the series label, rendered only when `legendText` is set), `live-region` (the current mark
announcement for keyboard users), `data-list` (a visually hidden sampled list of plotted data
points — single-series only), `data-table` (the generated/slotted alternative container),
`data-table-toggle` (the `dataTableToggle` disclosure button — new in 11.1.0), `table`
(the generated semantic category×series table rendered when there is more than one dataset), and
`data-truncation` (the
visible/announced sampling notice).

**Screen-reader data alternative:** a single dataset renders the flat `data-list` (one `<li>` per
plotted point, matching the roving-tabindex mark order). More than one dataset instead renders a
`data-table` — a category-labelled `<caption>` (the shared localized `chartData` string), one
`<th scope="col">` per series (plus a leading `chartCategory` corner header), and one
`<th scope="row">` per category label with its per-series values in the body — so a screen-reader
user hears the values grouped by series rather than one flattened N×M sequence.
Finite table cells use `tableCellFormatter` when supplied and otherwise use the component's
effective locale. A stacked multi-series bar chart with `tableTotals` adds a localized total
column; null/non-finite inputs are skipped, while an all-missing category leaves the total cell
blank instead of reporting a misleading zero. Built-in SVG marks, keyboard targets, and this data
alternative share one endpoint-preserving sample of at most 1,000 category×series records. When
sampling occurs, a localized `data-truncation` notice is shown and announced; provide
`slot="data-table"` for a complete paginated, virtualized, or application-owned alternative, which
suppresses the generated sample and notice.

**Themeable custom properties:** `--lr-chart-height` (same public host-level property and precedence
as `lr-chart`; it always wins over the `height` property's private fallback);
`--lr-chart-grid-color`, `--lr-chart-tick-color`, `--lr-chart-tick-font-size` (default
`var(--lr-font-size-2xs)`), `--lr-chart-legend-color` — same token
*names* as `lr-chart`, so a host already theming `lr-chart` themes this for free;
`--lr-chart-color-1`, `--lr-chart-color-2`, `--lr-chart-color-3`, `--lr-chart-color-4`,
`--lr-chart-color-5`, `--lr-chart-color-6`, `--lr-chart-color-7`, and `--lr-chart-color-8` (each
defaulting to the matching `var(--lr-color-chart-N)` ramp entry) — the per-series colors, so one element can be recolored
without moving the library-wide ramp; `--lr-chart-legend-side-max` (default
`var(--lr-size-15rem)`) caps side legend allocation; `--lr-lite-chart-selected-outline-color` (default
`var(--lr-color-brand)`) — the stroke drawn on
selected `[part='bar']` and `[part='point']` marks whose category index is in `selectedIndices`;
`--lr-lite-chart-selected-outline-width` (default `var(--lr-size-2px)`) — that stroke's width.
Unlike `lr-chart` (canvas-rendered, needs `getComputedStyle`-based re-theming on every draw), this
is plain SVG/DOM and reads these via native CSS `var()` — no JS-side resolution step, and no
`refreshTheme()` method needed (there's nothing to go stale). `--lr-chart-pattern-step`
(default `var(--lr-space-2xs)`) sizes the forced-colors legend texture, exactly as on `lr-chart`.

**Forced colors:** under `forced-colors: active` the `--lr-color-chart-*` ramp behind
`--lr-chart-color-1..8` is remapped onto the small repeating system-color cycle the platform
exposes, so series 1/4/7 (and 2/5/8, 3/6) would otherwise paint identically. `lr-lite-chart` then
encodes each series a second way, using the same eight-way vocabulary as `lr-chart`: `[part='bar']`
takes a per-series SVG texture fill, `[part='line']` takes a per-series `stroke-dasharray`, and
`[part='legend-swatch']` carries a `data-encoding` attribute selecting the matching CSS texture.
Nothing is opt-in, the encodings exist only while the media query matches, and no author color is
substituted.

**Optional peer deps:** none. This is the point of the component.

```html
<lr-lite-chart type="bar" stacked legend x-label="Week" y-label="Commits"></lr-lite-chart>
<script>
  const c = document.querySelector('lr-lite-chart');
  c.labels = ['W1', 'W2', 'W3', 'W4'];
  c.datasets = [
    { label: 'Docs', data: [4, 6, 3, 8] },
    { label: 'Bugs', data: [3, 2, 5, 4] },
  ];
</script>
```

**Known gotchas:**
- No horizontal-bar mode (unlike `lr-chart`'s `index-axis="y"`) — deliberately cut from scope, not a
  stub: bars are always vertical.
- No dual y-axis (`Series.axis: 'y2'`) — every series shares one y-axis/domain.
- Series colors default to the shared categorical ramp (round-robin by dataset index) when `color`
  is unset or invalid — the same eight `--lr-color-chart-1..8` tokens `lr-chart` uses, so both
  chart implementations agree on the palette and both follow a `--lr-theme-color-chart-*` retheme.
  Being plain SVG, they resolve through native `var()` at paint time, so a theme or color-scheme
  change needs no JS-side redraw pass here.
- Bar/point elements are real focusable DOM nodes (`role="button"` with one roving `tabindex="0"`);
  each carries the same localized text as an explicit `aria-label` and native SVG `<title>`, giving
  every engine a command name while retaining the tooltip. The `<svg>` itself uses
  `role="group"`, not `role="img"` — an image role would conflict with genuinely interactive
  descendants (axe's `nested-interactive` rule).
- Dense transparent hit regions expand toward 24px only while remaining inside the neighboring
  mark's midpoint lane; stacked segments keep their own vertical region. This prevents a
  later-painted mark from stealing pointer input from an adjacent datum. Cross-series line targets
  are additionally arbitrated by two-dimensional screen distance.
- In narrow allocations, category labels are ellipsized to their available lane and retain the
  complete label through `aria-label`; SVG overflow is contained within the host.
- Tick values use a standard "nice numbers" (1/2/5 × 10ⁿ) rounding step, not exact data min/max —
  intentional (readable axis labels), matches how most charting libraries pick tick steps.

---

## Typed subclasses: `lr-line-chart`, `lr-bar-chart`, `lr-pie-chart`, `lr-doughnut-chart`, `lr-radar-chart`, `lr-polar-area-chart`, `lr-bubble-chart`, `lr-scatter-chart`

Each is `LyraChart` with a named default `type` — respectively `line`, `bar`, `pie`, `doughnut`,
`radar`, `polarArea`, `bubble`, `scatter`. In parity with the mirrored tags, `type` remains writable
and accepts the full `LyraChartType` vocabulary; the tag name is a convenient default, not a lock.

Everything else is inherited verbatim from `lr-chart`; each name below has the same type, default,
and behavior there. **See `llms/components/lr-chart.md` for the details, code example, and gotchas
of every entry in these lists.**

**Properties:** `description`, `grid`, `axes`, `compact`, `indexAxis` (`index-axis`), `label`, `hiddenDatasets`, `legendPosition`
(`legend-position`), `hiddenDatums`, `legendMode` (`legend-mode`), `legendDisplay` (`legend-display`),
`max`, `min`, `plugins`, `scaleType` (`scale-type`), `annotations`,
`stacked`, `stackedAxes`, `withoutAnimation` (`without-animation`),
`withoutLegend` (`without-legend`), `withoutTooltip` (`without-tooltip`), `xLabel` (`x-label`),
`yLabel` (`y-label`), plus additive `labels`, `datasets`, `valueFormatter`, `formatter`,
`tooltipTitleFormatter`, `tooltipFooterFormatter`, `area`, `zoom`,
`height`, `y2Label` (`y2-label`), `beginAtZero` (`begin-at-zero`), `dataLabels`
(`data-labels`), `stackTotals` (`stack-totals`), `config`, `showDataTable`
(`show-data-table`), `dataTableToggle` (`data-table-toggle`), `chartArea` (readonly), and `chart`.
`type` differs only in its initial value.

**Methods:** `appendData(label, values, maxPoints?)`, `exportData('csv' | 'png')`, `renderChart()`, `resetZoom()`,
`refreshTheme()`.

**Events:** `lr-zoom` (`detail: { zoomed: boolean }`), `lr-datum-activate`, `lr-point-click` (`detail: { datasetIndex,
index, label, value }`), `lr-before-legend-visibility-change` (cancelable), and
`lr-legend-visibility-change` (commit; both legend events carry `datasetIndex`, `visible`, and the
complete `hiddenDatasets` snapshot).
Radial category legends additionally emit `lr-before-datum-visibility-change` (cancelable) and
`lr-datum-visibility-change`, carrying `index`, `visible` and the frozen `hiddenDatums` snapshot.

**Slots:** default JSON configuration script, `data-table`, `center`.

**CSS parts:** `base`, `plot`, `canvas`, `legend`, `legend-item`, `legend-item-hidden`, `legend-swatch`,
`reset-zoom-button`, `description`, `notices`, `data-table`, `data-table-toggle`, `data-truncation`, `feature-warning`, `center`, `error` (neutral visible message
rendered in place of `canvas` when the optional `chart.js` peer dependency fails to load; the
failure transition is announced through the shared document-level light-DOM assertive sink — see
`llms/components/lr-chart.md`).

**Themeable custom properties:** `--lr-chart-height`, `--lr-chart-grid-color`,
`--lr-chart-tick-color`, `--lr-chart-tick-font-size`, `--lr-chart-legend-color`, `--lr-chart-tooltip-bg`,
`--lr-chart-tooltip-text`, `--lr-chart-legend-item-hover-bg`,
`--lr-chart-legend-item-active-bg`, `--lr-chart-data-table-button-hover-bg`,
`--lr-chart-data-table-button-active-bg`, `--lr-chart-data-table-toggle-hover-bg`,
`--lr-chart-data-table-toggle-active-bg`, `--lr-chart-reset-zoom-button-hover-bg`,
`--lr-chart-reset-zoom-button-active-bg`, `--lr-chart-canvas-hover-outline-width`, and
`--lr-chart-canvas-hover-outline-color`, `--lr-chart-pattern-step`, plus `--lr-chart-legend-side-max` — all inherited from `LyraChart`, identical in meaning and default (see
`lr-chart` above); each of the eight variants below reads the same set, so one rule retunes them
together. The mirrored hooks are `--border-color-1`,
`--border-color-2`, `--border-color-3`, `--border-color-4`, `--border-color-5`,
`--border-color-6`, `--fill-color-1`, `--fill-color-2`, `--fill-color-3`, `--fill-color-4`,
`--fill-color-5`, `--fill-color-6`, `--border-radius`, `--border-width`, `--grid-border-width`,
`--grid-color`, `--line-border-width`, and `--point-radius`, also identical to the core chart.

**Optional peer deps:** same as `lr-chart` — `chart.js`, plus `chartjs-plugin-zoom` only once
`zoom` is set, `chartjs-plugin-datalabels` only once `data-labels`/`stack-totals` is set, and
`chartjs-plugin-annotation` only once `annotations` contains a usable entry.

```html
<lr-bar-chart></lr-bar-chart>
<lr-pie-chart></lr-pie-chart>
<script>
  document.querySelector('lr-bar-chart').labels = ['A', 'B'];
  document.querySelector('lr-bar-chart').datasets = [{ label: 'Count', data: [4, 9] }];

  document.querySelector('lr-pie-chart').labels = ['A', 'B', 'C'];
  document.querySelector('lr-pie-chart').datasets = [{ label: 'Share', data: [30, 45, 25], color: ['#2563eb', '#16a34a', '#dc2626'] }];
</script>
```

**Known gotchas (in addition to the core `lr-chart` list in `llms/components/lr-chart.md`):**
- Changing `type` after construction may rebuild the underlying Chart.js instance; any active zoom
  state is reset and announced before the new type renders.
- `lr-bubble-chart` consumes the exported `LyraChartPoint` shape directly. Set `x`/`y`, optional `r`
  for bubble radius, and optional `label` for the point-level accessible/event/export label; no
  runtime cast is needed.

---

## `lr-histogram`

Bins `values` into `bins` equal-width buckets and renders as a bar chart (extends `LyraChart`,
`type` fixed to `'bar'`).

**Properties:**
- `bins: number = 10` — finite values are floored and clamped to 0–1,000 before allocation;
  non-finite values produce no buckets
- `values: number[] = []` (attribute: false)
- `seriesLabel: string = ''` (attribute `series-label`) — dataset label used for the
  legend/tooltip/table; empty falls back to localized "Frequency". Inherited `label` keeps its
  chart-wide accessible-name meaning.
- inherits `lr-chart`'s full surface, including `scaleType` (`scale-type`) and `annotations` —
  a logarithmic frequency axis and threshold/band markers both apply to a histogram
- `labels`/`datasets`/`type` are **derived, read-only** (installed as getter/setter pairs on the
  prototype; direct writes are silently ignored) — `labels`/`datasets` are computed from
  `values`/`bins` (memoized per instance, keyed by reference equality on `values` plus the
  normalized `bins`), and `type` always reads back `'bar'` regardless of any assignment. This
  specialist owns its controller because a non-bar type would contradict the derived distribution.
- All other `LyraChart` properties are inherited and usable: `description`, `grid`, `axes`, `compact`, `indexAxis`
  (`index-axis`), `hiddenDatasets`, `hiddenDatums`, `legendPosition` (`legend-position`),
  `legendMode` (`legend-mode`), `legendDisplay` (`legend-display`), `max`, `min`, `plugins`,
  `withoutAnimation` (`without-animation`), `withoutLegend` (`without-legend`), `withoutTooltip`
  (`without-tooltip`), `valueFormatter`, `formatter`, `tooltipTitleFormatter`,
  `tooltipFooterFormatter`, `area`, `zoom`, `config`, `height`, `xLabel` (`x-label`),
  `yLabel` (`y-label`), `y2Label` (`y2-label`), `beginAtZero` (`begin-at-zero`),
  `stacked`, `stackedAxes`, `dataLabels` (`data-labels`), `stackTotals` (`stack-totals`), `showDataTable`
  (`show-data-table`), `dataTableToggle` (`data-table-toggle`), `chartArea` (readonly).

**Methods:** `resetZoom()`, `refreshTheme()`, and `renderChart()` are inherited; `appendSamples(values,
maxSamples?)` appends finite raw samples and optionally retains only the newest samples.
`appendData()` remains a working compatibility adapter (no longer deprecated); prefer
`appendSamples()` for new code.

**Events:** `lr-zoom`, `lr-datum-activate`, `lr-point-click`, `lr-before-datum-visibility-change`
(cancelable), `lr-datum-visibility-change`, `lr-before-legend-visibility-change` (cancelable), and
`lr-legend-visibility-change` — inherited; `lr-point-click`'s `index` is the bucket index and
`label` the generated bucket range string (`"lo–hi"`, both bounds at one decimal place).
The inherited datum-visibility events apply only to radial controllers; the histogram keeps its
bar controller and dataset legend even with `legend-mode="datum"`.

**Slots:** default JSON configuration script, `data-table`, `center`.

**CSS parts:** `base`, `plot`, `canvas`, `legend`, `legend-item`, `legend-item-hidden`, `legend-swatch`,
`reset-zoom-button`, `description`, `notices`, `data-table`, `data-table-toggle`, `data-truncation`, `feature-warning`, `center`, `error` (neutral visible message
rendered in place of `canvas` when the optional `chart.js` peer dependency fails to load; the
failure transition is announced through the shared document-level light-DOM assertive sink —
inherited from `LyraChart`, unaffected by the binning logic).

**Themeable custom properties:** `--lr-chart-height`, `--lr-chart-grid-color`,
`--lr-chart-tick-color`, `--lr-chart-tick-font-size`, `--lr-chart-legend-color`, `--lr-chart-tooltip-bg`,
`--lr-chart-tooltip-text`, `--lr-chart-legend-item-hover-bg`,
`--lr-chart-legend-item-active-bg`, `--lr-chart-data-table-button-hover-bg`,
`--lr-chart-data-table-button-active-bg`, `--lr-chart-data-table-toggle-hover-bg`,
`--lr-chart-data-table-toggle-active-bg`, `--lr-chart-reset-zoom-button-hover-bg`,
`--lr-chart-reset-zoom-button-active-bg`, `--lr-chart-canvas-hover-outline-width`, and
`--lr-chart-canvas-hover-outline-color`, `--lr-chart-pattern-step`, plus `--lr-chart-legend-side-max` — inherited from `LyraChart`, identical in meaning, together with the
mirrored `--border-color-1`,
`--border-color-2`,
`--border-color-3`, `--border-color-4`, `--border-color-5`, `--border-color-6`, `--fill-color-1`,
`--fill-color-2`, `--fill-color-3`, `--fill-color-4`, `--fill-color-5`, `--fill-color-6`,
`--border-radius`, `--border-width`, `--grid-border-width`, `--grid-color`,
`--line-border-width`, and `--point-radius` hooks listed on the core chart.

**Optional peer deps:** the same `chart.js` peer, plus `chartjs-plugin-zoom` when `zoom` is set,
`chartjs-plugin-datalabels` when `data-labels` or `stack-totals` is set, and
`chartjs-plugin-annotation` when `annotations` contains a usable entry.

All of the above behave exactly as documented in `llms/components/lr-chart.md` — read that file for
their semantics, defaults, and gotchas.

```html
<lr-histogram bins="12"></lr-histogram>
<script>
  document.querySelector('lr-histogram').values = [1, 2, 2, 3, 5, 5, 5, 8, 13, 13];
</script>
```

**Known gotchas:**
- `bins <= 0` no longer crashes: `binValues()` now returns an empty bucket array for `binCount <= 0`
  (or empty `values`), so the histogram just renders with no bars instead of throwing.
- excessively large finite bin counts are capped at 1,000, preventing an attribute or direct
  property write from requesting an unbounded bucket array.
- non-finite samples in `values` are dropped before bucketing rather than corrupting bucket-index
  math; a constant domain produces one truthful single-value bucket, including at numeric extremes.
- raw `config.options` and plugins remain available, but `config.type` and `config.data` are ignored:
  the histogram owns its bar controller and derives all categories from `values`/`bins`.
- `values`/`bins`/`seriesLabel` changes join the inherited connected-and-visible redraw path. There is no
  second post-update refresh, so a same-tick disconnect cannot recreate Chart.js on a detached
  canvas and off-screen sample updates do not repaint it.
- calling `binValues()` directly (not through `<lr-histogram>`, which always passes its own
  resolved `effectiveLocale`) with an omitted `locale` (or `'auto'`) now resolves to the page's
  active `setLyraLocale()` locale instead of a hardcoded `'en'`, matching `utilities/format.ts`'s
  helpers; an app that never calls `setLyraLocale()` sees no change, and an explicit tag still wins.

---

## `lr-box-plot`

Box-and-whisker chart from a precomputed five-number summary (no raw sample data sent to the
browser). Does **not** extend `LyraChart` — a deliberately bespoke API.

With `IntersectionObserver` available, canvas construction waits for its first delivered visibility
decision. An off-screen box plot stays unconstructed until visible. Without the observer, drawing
starts when the peers and canvas are ready; an empty delivered callback retains the visible
fallback. Peer loading and accessible DOM can settle while visibility is pending. These rules also
apply when the component reconnects.

**Properties:**
- `labels: readonly string[] = []` (attribute: false)
- `datasets: readonly LyraBoxPlotSeries[] = []` (attribute: false) — each series contains readonly
  `LyraBoxPlotSummary { min, q1, median, q3, max }` values. Summaries must be finite and ordered
  `min <= q1 <= median <= q3 <= max`; invalid entries are omitted and caller objects are never
  passed to the mutating peer. A runtime series whose required `data` member is not an array is
  dropped while valid siblings continue to render.
- `hiddenDatasets?: readonly number[]` (attribute: false) — complete controlled visibility snapshot
  for the DOM legend. `undefined` leaves every box series visible; `[]` likewise explicitly makes
  every series visible, while a defined canonical list of zero-based indexes hides those series.
  Duplicate, non-integer, negative, and out-of-range indexes are discarded. Accepted user toggles
  write their complete next snapshot back to this property; programmatic writes reconcile silently.
- `labels`, `datasets`, and `hiddenDatasets` are clone-owned, bounded, frozen snapshots. Mutating a
  previously assigned array or nested series data has no effect; create and reassign a new
  collection.
- `legend: boolean = false` — renders a wrapping DOM legend whose buttons toggle box-series
  visibility without clipping long labels.
- `legendPosition: 'top'|'bottom'|'start'|'end' = 'bottom'` (attribute `legend-position`) — logical,
  responsive DOM legend placement
- `height: string = '280px'` — valid CSS height used as a private fallback only. A consumer-set
  `--lr-chart-height` always wins; invalid values remove the fallback and leave the public
  token/default in control.
- `yLabel: string = ''` (attribute `y-label`)
- `beginAtZero: boolean = true` (attribute `begin-at-zero`)
- `label: string | null = null`, `description: string | null = null` — canonical accessible name
  and description; host `aria-label` wins by presence, including an explicit empty string
- `formatter?: LyraChartFormatter`, `valueFormatter?: LyraChartValueFormatter` — numeric axis,
  tooltip, table, summary, and export formatting. The context-object formatter receives the
  family-wide `spoken` surface for the generated summary and `export` for CSV cells; the legacy
  positional formatter receives `table` for the spoken/export compatibility paths, its normal
  surface name for axis, tooltip, and table work, and no fallback for a `visual` context. The
  context-object formatter takes precedence. Tick calls name `axis: 'y'`, and a tooltip value now
  carries the hovered datum's `datasetIndex`, `index`, `label`, `seriesLabel` and
  `statistic: 'median'` instead of discarding what the callback was handed.
- `showDataTable: boolean = false` (attribute `show-data-table`) — reveals the accessible data table
- `dataTableToggle: boolean = false` (attribute `data-table-toggle`, new in 11.0.0) — renders a
  localized disclosure button (`part="data-table-toggle"`) above the data table so a *sighted*
  reader can reveal the numbers on demand. `showDataTable` alone is all-or-nothing, which left
  consumers wrapping a duplicated table in their own `<details>`. With the toggle on,
  `showDataTable` becomes the disclosure's **initial** state rather than its whole behavior; the
  table stays in the DOM in both states, so assistive technology never loses it, and the button
  carries `aria-expanded` plus `aria-controls` pointing at the `data-table` wrapper. A supplied
  `slot="data-table"` follows this same disclosure state. Unset, nothing renders and behavior is
  identical to before.

**Methods:** `exportData('csv'|'png')` returns spreadsheet-safe summary rows or the current canvas
PNG data URL. `refreshTheme()` re-reads canvas theme custom properties after an ancestor theme
change. Canvas work remains connected/visible-gated, while a rendered DOM legend also refreshes
its computed color swatches.

**Events:** `lr-datum-activate` (canonical detail with `kind: 'box'`), `lr-point-click`
(compatibility), `lr-before-legend-visibility-change` (cancelable proposed legend
toggle) and `lr-legend-visibility-change` (accepted commit). The two legend events carry
`{ datasetIndex: number, visible: boolean, hiddenDatasets: readonly number[] }`, where
`hiddenDatasets` is the complete sorted, valid next snapshot. Calling `preventDefault()` on the
proposal leaves state untouched and suppresses the commit event.

`lr-point-click` fires when pointer input lands on a box, or when Enter/Space activates the
keyboard-current box — the same event name and role `lr-chart` and `lr-lite-chart` expose. Its
`detail` is `{ datasetIndex: number, index: number, label: string | undefined, value: LyraBoxPlotSummary |
null }`, where `value` is a fresh copy of that box's five-number summary (never the object you
passed in `datasets`, which the underlying peer may annotate in place). A pointer click that misses every
box emits nothing rather than reporting the nearest one.

**Per-box keyboard access:** the `canvas` part is a focusable `role="application"` surface.
Arrow keys walk the boxes one at a time (Left/Right swap under RTL; Up/Down always mean
previous/next), Home/End jump to the first/last, and Enter or Space activates the current box. Each
move announces that box's series, category, and complete five-number summary through the shared
document-level light-DOM polite sink. The walk visits the same bounded, deterministic sample the
generated data table uses, so a very wide data set stays navigable.

**Slots:** `data-table` — an optional consumer-provided complete, paginated, or virtualized
accessible table alternative.

**Bounded data alternative:** the generated table, automatic canvas name, and generated per-series
description use at most 1,000 category×series records. When sampling is needed, its category and
series indexes are deterministic and retain the first and last endpoint; a localized
`data-truncation` notice is shown and announced. A slotted `data-table` replaces the generated
detailed sample and notice, making it the escape hatch for complete data.

**CSS parts:** `base`, `plot` (the fixed-height canvas region), `canvas`, `legend`,
`legend-item`, `legend-item-hidden` (added to a legend item while its box series is hidden),
`legend-swatch`, `description`, `data-table`, `data-table-toggle` (the `dataTableToggle` disclosure button), `error` (neutral visible message shown
instead of `canvas` when the optional box-plot peer fails to load; the failure transition is
announced through the shared document-level light-DOM assertive sink), `data-truncation` (the
bounded-alternative sampling notice)

**Themeable custom properties:** `--lr-chart-height`, `--lr-chart-grid-color`,
`--lr-chart-tick-color`, `--lr-chart-tick-font-size`, `--lr-chart-legend-color`, `--lr-chart-tooltip-bg`,
`--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`
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
ramp and mirroring `lr-chart`'s own `--border-color-N`/`--fill-color-N` palette-override mechanism
under a box-plot-namespaced name, since box-plot has no raw `config` passthrough to piggyback on:
`--lr-box-plot-border-color-1` through `--lr-box-plot-border-color-8` (defaulting respectively to
`--lr-color-chart-1` through `--lr-color-chart-8`) set the box-outline stroke color, and
`--lr-box-plot-fill-color-1` through `--lr-box-plot-fill-color-8` (the same eight defaults) set the
box fill and its legend swatch. In full, the stroke tokens are `--lr-box-plot-border-color-1`,
`--lr-box-plot-border-color-2`, `--lr-box-plot-border-color-3`, `--lr-box-plot-border-color-4`,
`--lr-box-plot-border-color-5`, `--lr-box-plot-border-color-6`, `--lr-box-plot-border-color-7` and
`--lr-box-plot-border-color-8`; the fill tokens are `--lr-box-plot-fill-color-1`,
`--lr-box-plot-fill-color-2`, `--lr-box-plot-fill-color-3`, `--lr-box-plot-fill-color-4`,
`--lr-box-plot-fill-color-5`, `--lr-box-plot-fill-color-6`, `--lr-box-plot-fill-color-7` and
`--lr-box-plot-fill-color-8`. `--lr-box-plot-border-width` (default `var(--lr-border-width-thin)`)
sets the canvas box-outline stroke width in pixels — the same override mechanism as `lr-chart`'s
`--border-width`. `--lr-box-plot-item-radius` (default `0`) sets the radius, in pixels, of the
individual raw-sample dots drawn alongside each box; `0` disables them. `--lr-chart-pattern-step`
(default `var(--lr-space-2xs)`) sizes the forced-colors legend texture and
`--lr-chart-canvas-hover-outline-width` (default `var(--lr-border-width-thin)`) sizes the `canvas`
hover outline; `--lr-chart-canvas-hover-outline-color` (default `var(--lr-chart-grid-color)`) sets
its color. `--lr-chart-legend-item-active-bg` and `--lr-chart-legend-item-hover-bg` retune the
pressed and hovered legend rows, and `--lr-chart-legend-side-max` caps a side legend — the same tokens and defaults as
`lr-chart`. Its own `dataTableToggle` disclosure button carries box-plot-namespaced hooks rather
than inheriting the chart pair, since its stylesheet is not a re-export:
`--lr-box-plot-data-table-toggle-hover-bg` (defaults to `--lr-color-brand-quiet`) and
`--lr-box-plot-data-table-toggle-active-bg` (defaults to its standard active color mix).

**Forced colors:** under `forced-colors: active` the eight-color ramp is remapped onto the small
repeating system-color cycle the platform exposes, so series 1/4/7 (and 2/5/8, 3/6) would otherwise
paint identically. Each box's fill is therefore textured with a per-series pattern, and its legend
swatch carries the matching CSS texture — the same eight-way encoding `lr-chart` applies to its own
repeated colors. Box-and-whisker elements expose no border-dash or point-style option, so texture is
the only channel here; nothing is opt-in and no author color is substituted.

**Optional peer deps:** `@sgratzl/chartjs-chart-boxplot` plus `chart.js`; both validated capability
loads are memoized per page.

```html
<lr-box-plot y-label="Latency (ms)"></lr-box-plot>
<script>
  const bp = document.querySelector('lr-box-plot');
  bp.labels = ['Run A', 'Run B'];
  bp.datasets = [{ label: 'p50–p99', data: [{ min: 10, q1: 20, median: 30, q3: 45, max: 90 }, { min: 12, q1: 18, median: 25, q3: 35, max: 60 }] }];
</script>
```

**Known gotchas:**
- no raw `config` passthrough — limited to the properties above, plus the `--lr-box-plot-border-width`
  and `--lr-box-plot-item-radius` CSS hooks; the underlying controller's other options
  (`outlierRadius`, `coef`) remain unreachable.
- Chart.js receives `effectiveLocale`; generated numeric summaries use it, the y axis moves to
  logical start in RTL, and live ancestor `lang`/`dir` changes redraw the already-mounted canvas
  without requiring another box property write. Canvas tooltip/axis colors are token-driven, and
  animation is disabled under reduced motion.
- `--lr-chart-height` fixes the `plot` height and the host's minimum height, not the complete host.
  It is consumer-owned and wins over the `height` property's private fallback. A visible or slotted
  table and the wrapping legend remain in normal document flow, grow the
  component, and cannot overlap following content; oversized tables scroll inside the host.
- If `@sgratzl/chartjs-chart-boxplot` fails to load, the component warns to the console and
  fails closed with a localized, neutral visible error part rather than leaving a blank canvas.
  The transition into that state is announced through the shared document-level light-DOM
  assertive sink.

---

## Chart streaming and export

`lr-lite-chart` and `lr-chart` expose imperative helpers for live dashboards:
`appendData(label, values, maxPoints?)` appends one aligned category and optionally trims the oldest
points; when existing series lengths differ, missing cells are padded before the new category so
labels and values remain aligned. `lr-histogram.appendSamples(values, maxSamples?)` appends finite
raw samples and rebins the retained window. `lr-lite-chart.exportData('csv' | 'svg')` returns a spreadsheet-safe CSV snapshot
or the current SVG markup. `lr-chart.exportData('csv' | 'png')` returns a CSV snapshot or Chart.js's
current PNG data URL when the optional peer is loaded; point datasets expand x/y and optional
radius/point-label columns. `lr-box-plot.exportData('csv'|'png')` exports all five summary values.
These helpers do not download files; compose them with
`lr-export-button` so the host owns filenames and download policy.

For route-level warming, the side-effect-free chart preload entry exports
`preloadCharts({ zoom?, dataLabels?, annotations?, boxPlot? })`. Core Chart.js is always requested
and optional capabilities only when flagged; the result reports which requested capabilities are
available. `annotations` appears in the result only when requested, and is `true` only after the
optional annotation peer loads.

## Exported TypeScript contracts

These named interfaces and helper signatures are available to typed integrations. They are grouped by capability so the component sections above can stay focused.

- **`components-charts-chart-box-plot-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/charts/chart/box-plot.class.js`.
  `LyraBoxPlotPointDetail {
    datasetIndex: number;
    index: number;
    label: string | undefined;
    value: LyraBoxPlotSummary | null;
  }`
  Import: `@aceshooting/lyra-ui/components/charts/chart/box-plot.class.js`.
  `LyraBoxPlotSeries {
    readonly label: string;
    readonly data: readonly LyraBoxPlotSummary[];
    readonly color?: string;
  }`
  Import: `@aceshooting/lyra-ui/components/charts/chart/box-plot.class.js`.
  `LyraBoxPlotSummary {
    readonly min: number;
    readonly q1: number;
    readonly median: number;
    readonly q3: number;
    readonly max: number;
  }`

- **`components-charts-chart-chart-colors-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/charts/chart/chart-colors.js`.
  `ChartThemeColors {
    grid: string;
    tick: string;
    legend: string;
    tooltipBg: string;
    tooltipText: string;
    tickFontSize: number;
  }`
  Axis tick-label font size in pixels, resolved from `--lr-chart-tick-font-size` (see that
  `@cssprop` on `<lr-chart>`/`<lr-box-plot>`/`<lr-lite-chart>`).
  Import: `@aceshooting/lyra-ui/components/charts/chart/chart-colors.js`.
  `seriesPalette(element?: Element | null): string[]`
  Import: `@aceshooting/lyra-ui/components/charts/chart/chart-colors.js`.
  `translucentAreaColor(scope: Element, color: string): string`

- **`components-charts-chart-chart-core-loader-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/charts/chart/chart-core-loader.js`.
  `ChartJsModule {
    Chart: ChartConstructorCapability;
    defaults: {
      plugins?: {
        legend?: {
          labels?: {
            generateLabels?: (chart: object) => unknown[];
          };
        };
      };
    };
    LineController: unknown;
    BarController: unknown;
    ScatterController: unknown;
    DoughnutController: unknown;
    PieController: unknown;
    RadarController: unknown;
    PolarAreaController: unknown;
    BubbleController: unknown;
    LineElement: unknown;
    PointElement: unknown;
    BarElement: unknown;
    ArcElement: unknown;
    LinearScale: unknown;
    CategoryScale: unknown;
    RadialLinearScale: unknown;
    LogarithmicScale: unknown;
    Filler: unknown;
    Tooltip: unknown;
    Legend: unknown;
  }`
  Import: `@aceshooting/lyra-ui/components/charts/chart/chart-core-loader.js`.
  `loadAndRegisterChartModule(importChart?: () => Promise<unknown>, register?: (mod: ChartJsModule) => void): Promise<ChartJsModule | null>`
  Import: `@aceshooting/lyra-ui/components/charts/chart/chart-core-loader.js`.
  `loadChartJs(): Promise<ChartJsModule | null>`
  Import: `@aceshooting/lyra-ui/components/charts/chart/chart-core-loader.js`.
  `loadChartModule(importChart?: () => Promise<unknown>): Promise<ChartJsModule | null>`

- **`components-charts-chart-chart-feature-loader-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/charts/chart/chart-feature-loader.js`.
  `ChartPluginCapability {
    id: string;
    [key: string]: unknown;
  }`
  Import: `@aceshooting/lyra-ui/components/charts/chart/chart-feature-loader.js`.
  `loadAnnotationPlugin(importAnnotation?: () => Promise<unknown>): Promise<AnnotationPlugin | undefined>`
  Import: `@aceshooting/lyra-ui/components/charts/chart/chart-feature-loader.js`.
  `loadChartAndAnnotation(loadChart: () => Promise<ChartJsModule | null>, importAnnotation?: () => Promise<unknown>): Promise<ChartFeatureLoadResult<AnnotationPlugin>>`
  Import: `@aceshooting/lyra-ui/components/charts/chart/chart-feature-loader.js`.
  `loadChartJsWithAnnotationResult(importAnnotation?: () => Promise<unknown>): Promise<ChartFeatureLoadResult<AnnotationPlugin>>`

- **`components-charts-chart-chart-legend-visibility-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/charts/chart/chart.class.js`.
  `LyraChartLegendVisibilityChangeDetail {
    readonly datasetIndex: number;
    readonly visible: boolean;
    readonly hiddenDatasets: readonly number[];
  }`
  Import: `@aceshooting/lyra-ui/components/charts/chart/chart.class.js`.
  `LyraChartDatumVisibilityChangeDetail {
    readonly index: number;
    readonly visible: boolean;
    readonly hiddenDatums: readonly number[];
  }`
  `LyraChartLegendMode = 'dataset' | 'datum'`
  `LyraChartLegendDisplay = 'auto' | 'label' | 'value' | 'percentage' | 'value-percentage'`

- **`components-charts-chart-chart-loader-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/charts/chart/chart-feature-loader.js`.
  `loadChartAndZoom(importChart?: () => Promise<unknown>, importZoom?: () => Promise<unknown>, needsZoom?: boolean): Promise<{
    mod: ChartJsModule;
    zoomPlugin: ZoomPlugin | undefined;
  } | null>`
  Import: `@aceshooting/lyra-ui/components/charts/chart/chart-feature-loader.js`.
  `loadChartAndDataLabels(loadChart: () => Promise<ChartJsModule | null>, importDataLabels?: () => Promise<unknown>): Promise<ChartFeatureLoadResult<DataLabelsPlugin>>`
  Import: `@aceshooting/lyra-ui/components/charts/chart/chart-feature-loader.js`.
  `loadChartAndRegisterZoom(loadChart: () => Promise<ChartJsModule | null>, importZoom?: () => Promise<unknown>): Promise<ChartFeatureLoadResult<ZoomPlugin>>`
  Import: `@aceshooting/lyra-ui/components/charts/chart/chart-feature-loader.js`.
  `loadChartJsWithDataLabels(importDataLabels?: () => Promise<unknown>): Promise<{
    mod: ChartJsModule;
    plugin: DataLabelsPlugin | undefined;
  } | null>`
  Import: `@aceshooting/lyra-ui/components/charts/chart/chart-feature-loader.js`.
  `loadChartJsWithDataLabelsResult(importDataLabels?: () => Promise<unknown>): Promise<ChartFeatureLoadResult<DataLabelsPlugin>>`
  Import: `@aceshooting/lyra-ui/components/charts/chart/chart-feature-loader.js`.
  `loadChartJsWithZoom(importZoom?: () => Promise<unknown>): Promise<ChartJsModule | null>`
  Import: `@aceshooting/lyra-ui/components/charts/chart/chart-feature-loader.js`.
  `loadChartJsWithZoomResult(importZoom?: () => Promise<unknown>): Promise<ChartFeatureLoadResult<ZoomPlugin>>`
  Import: `@aceshooting/lyra-ui/components/charts/chart/chart-feature-loader.js`.
  `loadDataLabelsPlugin(importDataLabels?: () => Promise<unknown>): Promise<DataLabelsPlugin | undefined>`

- **`components-charts-chart-chart-preload-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/charts/chart/chart-preload.js`.
  `LyraChartPreloadOptions {
    readonly zoom?: boolean;
    readonly dataLabels?: boolean;
    readonly annotations?: boolean;
    readonly boxPlot?: boolean;
  }`
  Import: `@aceshooting/lyra-ui/components/charts/chart/chart-preload.js`.
  `LyraChartPreloadResult {
    readonly core: boolean;
    readonly zoom?: boolean;
    readonly dataLabels?: boolean;
    readonly annotations?: boolean;
    readonly boxPlot?: boolean;
  }`
  Import: `@aceshooting/lyra-ui/components/charts/chart/chart-preload.js`.
  `preloadCharts(options?: LyraChartPreloadOptions): Promise<LyraChartPreloadResult>`

- **`components-charts-chart-chart-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/charts/chart/chart.class.js`.
  `LyraChartAnnotation {
    readonly axis?: LyraChartIndexAxis;
    readonly value?: number;
    readonly from?: number;
    readonly to?: number;
    readonly label?: string;
    readonly tone?: LyraVariant;
  }`
  Import: `@aceshooting/lyra-ui/components/charts/chart/chart.class.js`.
  `LyraChartArea {
    readonly top: number;
    readonly left: number;
    readonly right: number;
    readonly bottom: number;
    readonly width: number;
    readonly height: number;
  }`
  Import: `@aceshooting/lyra-ui/components/charts/chart/chart.class.js`.
  `LyraChartConfiguration {
    type?: string;
    data?: LyraChartDataConfiguration;
    options?: object;
    plugins?: LyraChartPlugin[];
  }`
  Import: `@aceshooting/lyra-ui/components/charts/chart/chart.class.js`.
  `LyraChartDataConfiguration {
    labels?: unknown[];
    datasets?: LyraChartDatasetConfiguration[];
  }`
  Import: `@aceshooting/lyra-ui/components/charts/chart/chart.class.js`.
  `LyraChartDatasetConfiguration {
    type?: string;
    label?: unknown;
    data?: unknown[];
    hidden?: boolean;
    axis?: string;
    yAxisID?: string;
    stack?: string;
    noTooltip?: boolean;
    fill?: unknown;
    backgroundColor?: unknown;
    borderColor?: unknown;
    borderRadius?: unknown;
    borderWidth?: unknown;
    borderDash?: unknown;
    color?: unknown;
    pointStyle?: unknown;
    pointBackgroundColor?: unknown;
    pointRadius?: unknown;
    segment?: unknown;
  }`
  Import: `@aceshooting/lyra-ui/components/charts/chart/chart.class.js`.
  `LyraChartDatumActivateDetail<TKind extends LyraChartDatumKind = LyraChartDatumKind, TValue = unknown> {
    readonly kind: TKind;
    readonly datasetIndex: number;
    readonly index: number;
    readonly label: string | undefined;
    readonly value: TValue;
  }`
  Import: `@aceshooting/lyra-ui/components/charts/chart/chart.class.js`.
  `LyraChartFormatterContext {
    readonly value: number;
    readonly surface: LyraChartFormatSurface;
    readonly datasetIndex?: number;
    readonly index?: number;
    readonly label?: string;
    readonly seriesLabel?: string;
    readonly statistic?: LyraChartStatistic;
    readonly axis?: LyraChartFormatterAxis;
    readonly percentage?: number;
  }`
  Import: `@aceshooting/lyra-ui/components/charts/chart/chart.class.js`.
  `LyraChartFormatterAxis = 'x' | 'y' | 'y2' | 'r'`
  Import: `@aceshooting/lyra-ui/components/charts/chart/chart.class.js`.
  `LyraChartInstance extends RuntimeChart {
    // Inherited from RuntimeChart.
    data: {
      labels?: unknown[];
      datasets: LyraChartDatasetConfiguration[];
    };
    options: Record<string, unknown>;
    config: {
      type?: unknown;
    };
    legend?: unknown;
    chartArea?: LyraChartArea;
    destroy(): void;
    update(mode?: string): void;
    toBase64Image?(): string;
    getElementsAtEventForMode(event: Event, mode: string, options: Record<string, unknown>, useFinalPosition: boolean): ChartHit[];
    getDatasetMeta?(index: number): {
      hidden: boolean | null;
    };
    isDatasetVisible(index: number): boolean;
    setDatasetVisibility(index: number, visible: boolean): void;
    getDataVisibility?(index: number): boolean;
    toggleDataVisibility?(index: number): void;
  }`
  Import: `@aceshooting/lyra-ui/components/charts/chart/chart.class.js`.
  `LyraChartPlugin {
    readonly id: string;
  }`
  Import: `@aceshooting/lyra-ui/components/charts/chart/chart.class.js`.
  `LyraChartPoint {
    readonly x: number;
    readonly y: number;
    readonly r?: number;
    readonly label?: string;
  }`
  Import: `@aceshooting/lyra-ui/components/charts/chart/chart.class.js`.
  `LyraChartSeries {
    readonly label: string;
    readonly data?: readonly (number | null)[];
    readonly points?: readonly LyraChartPoint[];
    readonly color?: string | readonly string[];
    readonly fill?: boolean;
    readonly width?: number;
    readonly dash?: boolean;
    readonly noTooltip?: boolean;
    readonly axis?: 'y' | 'y2';
    readonly stack?: string;
    readonly pointColors?: readonly string[];
    readonly pointRadius?: number | readonly number[];
    readonly segmentColors?: readonly string[];
    readonly type?: 'line' | 'bar';
  }`

- **`components-charts-chart-histogram-bin-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui`.
  `binValues(values: readonly number[], binCount: number, locale?: string): HistogramBucket[]`
  Import: `@aceshooting/lyra-ui`.
  `HistogramBucket {
    label: string;
    count: number;
  }`

- **`components-charts-chart-histogram-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/charts/chart/histogram.class.js`.
  `binnedBuckets(el: LyraHistogram): HistogramBucket[]`

- **`components-charts-chart-lite-chart-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/charts/chart/lite-chart.class.js`.
  `LyraLiteChartSeries {
    readonly label: string;
    readonly data: readonly (number | null)[];
    readonly color?: string;
  }`
  Import: `@aceshooting/lyra-ui/components/charts/chart/lite-chart.class.js`.
  `LyraLiteChartTableCellContext {
    kind: LyraLiteChartTableCellKind;
    datasetIndex: number | null;
    index: number;
    label: string;
    seriesLabel: string | null;
  }`

# Document & file viewers (`components/viewers/`)

## `lr-document-preview`

A format-dispatching viewer for one document/attachment, plus the visual state machine for an async
server-side conversion a host app runs in front of it. First-party invention (no Web Awesome
equivalent).

Fitting images remain centered; overflowing nonzoomable images begin inside the reachable body
scroll range, so their top and bottom are available.

Format dispatch is intentionally minimal: only `text/*`/`application/json` (a plain, scrollable
`<pre>` — no syntax highlighting; compose `<lr-code-block>` yourself via the `unsupported` slot for
that) and `image/*` (a contained `<img>`) render inline. Everything else — PDF, office documents,
video, audio, or any unrecognized MIME type — falls back to a generic "can't preview this" state: a
file glyph, a short message, and (when `src` is set) a native `<a download>` link. This is a
deliberate ceiling, not a gap: the component ships a dispatch _shell_, not a format registry. The
`unsupported` slot is the escape hatch for every format left out of the built-in three.

`status="converting"` is a second, independent axis from format dispatch. This component doesn't know
your backend's conversion API shape and owns none of the actual polling/fetch — a host converting a
non-natively-previewable format server-side (e.g. `.docx` → `.pdf`) polls its own backend and updates
`status`/`progress`/`src` here as that proceeds; this component only _visualizes_ that state (an
indeterminate spinner, or a determinate one once `progress` is supplied). The one piece of async work
this component _does_ own is fetching a `text/*`/`application/json` `src` itself — there's no other
way to get a `<pre>`'s text content from a URL — gated behind a generation-counter guard
(`lr-tool-result-view`'s `resolve()` uses the identical pattern) so a `src` reassigned mid-fetch
can't have a stale response clobber a newer one.

Every `src` is validated (via `internal/safe-url.ts`) against a scheme allowlist specific to the DOM/
API sink it's about to reach: `fetch(src)` (text preview) and an `<img src>` (image preview) both
allow relative URLs plus `http:`, `https:`, `blob:`, and `data:`; the download `<a href>` deliberately
excludes `data:` (following a `data:text/html` URL can create an active document, unlike using it as
inert media/fetch data). A `src` that fails its sink's check never reaches `fetch()`/`<img>`/the
anchor: the text preview renders `[part="error"]` with `"Document URL is not allowed."`, the image
preview silently falls back to the download fallback **directly** — not the generic
download-or-`unsupported`-slot one, so `<slot name="unsupported">` content is _not_ consulted on the
image path — and the generic fallback simply omits `[part="download-link"]` entirely.

**Properties:**

- `src: string = ''` — URL to fetch (for `text`/`application/json`) or display (`image`, or as the
  generic fallback's download `href`). Optional — gracefully absent while, e.g., a conversion is
  still in progress. Validated per-sink before use — see the URL-safety note above; an unsafe/
  malformed value is treated as if `src` were unusable for that sink, never passed to `fetch()`/
  `<img>`/the anchor.
- `mimeType: string = ''` (attribute `mime-type`) — drives format dispatch using the case-insensitive
  MIME essence before parameters. For example, `application/json; charset=utf-8` renders as text.
  Attribute removal retains `null` readback and is interpreted as an absent format by the renderer;
  an explicitly empty attribute remains empty, and later valid values restore dispatch.
- `filename: string = ''` — shown in the header and used as the download link's suggested filename.
- `alt?: string` — image description. When omitted, the filename/localized image-preview fallback
  is used; an explicit empty string keeps a decorative preview's `alt=""` intact.
- `status: 'idle' | 'converting' | 'ready' | 'error' = 'idle'` (reflected) — host-owned lifecycle
  state. `"converting"` shows the spinner regardless of `mimeType`/`src`; `"error"` shows
  `errorText` regardless of either. `"idle"`/`"ready"` both resume normal format dispatch — a host
  with no conversion step never has to explicitly set `"ready"`.
- `progress?: number` (type `Number`) — 0-100. Only consulted while `status="converting"`. Unset (the
  default) renders an indeterminate spinner instead of a determinate progress bar.
- `errorText: string = ''` (attribute `error-text`; spelled `errorMessage`/`error-message` before
  9.0.0) — shown via `[part="error"]` while `status="error"`. Caller-supplied text, not localized;
  left empty, the localized `documentPreviewGenericError` fallback shows instead.
- `maxHeight: string = ''` (attribute `max-height`) — a CSS length (e.g. `"24rem"`); once set,
  `[part="body"]` scrolls internally past this height instead of growing the page — same contract as
  `lr-json-viewer`'s identically-named prop. Invalid CSS `max-height` values, declaration breaks,
  and `url()` are ignored, leaving the stylesheet token in control.
- `zoomable: boolean = false` (reflected) — wraps the rendered image (image format only) in an
  internal `<lr-pan-zoom>`. `false` (the default) preserves the exact pre-`zoomable` DOM — an
  inline thumbnail (e.g. in a chat stream) must not unexpectedly grow a focusable zoom-chrome
  viewport; an inspection surface opts in.
- `suppressDownload: boolean = false` (attribute: false) — omits the generic fallback's download
  action when a composing shell already owns that action. This is property-only composition state;
  it does not suppress inline preview rendering.
- `highlights: readonly LyraHighlight[] = []` (attribute: false) — display-only `region` highlights painted
  over the image-format preview; ignored for the `text`/`generic` formats. IDs are trimmed and
  required to be nonempty, with the first record retained when IDs repeat. A rectangle renders only
  when `x`/`y`/`width`/`height` are finite numbers and both dimensions are nonnegative. Image-region
  geometry is captured when `highlights` is assigned: an invalid or accessor-backed `region` anchor
  is ignored, and mutating an accepted anchor later does not move its painted region. Reassign
  `highlights` to update it; the original public anchor identity remains available for
  reference-based `scrollToAnchor()`.
- `activeHighlightId: string | null = null` (attribute `active-highlight-id`) — the `highlights`
  entry, if any, currently treated as active (`data-active` on its `region-highlight`).
- `anchorKinds: readonly LyraAnchor['kind'][] = ['region']` (this viewer's supported
  `LyraAnchor.kind` values for the
  shared anchor-target contract).

**Methods:** `scrollToAnchor(target)` — scrolls a `region` highlight (by id, or a `LyraAnchor`
matched back to its owning `LyraHighlight` by reference) into view; resolves `false` when nothing
matches, the anchor isn't `region`, or the format isn't currently `image`.

**Events:**

- `lr-download` — `detail: { src, filename }` — fired when the generic-download fallback's link is
  activated. The browser download itself needs no JS (a plain `<a download>` handles it); this is
  purely for a host that wants to observe/log the download.
- `lr-render-error` — `detail: { error }` — fired when this component rejects an unsafe text/JSON
  URL or when its own `text/*`/`application/json` `fetch(src)` fails (network error or non-2xx
  response). Distinct from `status="error"`, which is entirely host-driven.
- `lr-highlight-activate` — `detail: { highlightId }` — a region highlight was clicked or activated via
  Enter/Space (image format only).

**Slots:** `unsupported` — escape hatch: when populated, its content renders _instead of_ the generic
download fallback for any `mime-type` this component doesn't natively support. Ignored while
`mime-type` resolves to `text`/`image` dispatch, or while `status` is `"converting"`/`"error"`.

**CSS parts:** `base`, `header` (hidden entirely when `filename` is unset), `filename`, `body`,
`spinner` (ordinary non-live shadow content while indeterminate, or `role="progressbar"` once
numeric progress is known — used both for `status="converting"` and this component's own in-flight
text fetch), `error` (ordinary visible shadow text used both for `status="error"` and a failed text
fetch; error transitions use the shared document-level assertive sink), `download-link` (only
rendered when `src` is set _and_ passes the link-safe scheme allowlist — see the URL-safety note
above; excludes `data:` even though the other two sinks allow it), `highlight-layer` (wrapper around
every rendered region highlight, image format only), `region-highlight` (one region highlight,
`data-tone`, `data-active`; image format only), `region-highlight-target` (transparent activation
geometry with a minimum hit area independent of the visual rectangle), `highlight-actions`
(non-overlapping actions used when multiple minimum hit areas would overlap),
`region-highlight-action` (one action in that list), `frame-viewport`/`frame-content`/`frame-controls`/
`frame-zoom-in`/`frame-zoom-out`/`frame-reset` (forwarded from the internal `<lr-pan-zoom>`
while `zoomable`; image format only)

**Themeable custom properties:** `--lr-document-preview-max-height` (default `none`) — the
consumer-tunable scroll cap on `[part="body"]`, set from `max-height`; `none` means the preview grows
with its content until a caller opts in. `--lr-document-preview-font` (default
`var(--lr-font-mono)`, so a themed monospace stack reaches plain-text previews with no
per-component override) and `--lr-document-preview-spin-duration` (default
`var(--lr-transition-ambient)`, stopped under reduced motion). `--lr-document-preview-progress`
(default `0`) — a unitless
0–100 number the determinate spinner's `conic-gradient` fill reads; written inline on the ring by
the component itself from the clamped `progress` property, so overriding it only makes sense to
repaint the fraction. `--lr-document-preview-active-border` (default
`var(--lr-color-warning, var(--lr-color-brand))`) — the border color of the `[part='region-highlight']`
matching `activeHighlightId` (image format only), deliberately distinct from the resting highlight
border so the active region can be recolored without touching the rest. Like the library's other
state hooks it is an inline `var()` fallback at the point of use rather than a `:host` declaration,
so it can be set on the element or on any ancestor — `::part(region-highlight)[data-active]` is
invalid CSS (Shadow Parts forbids an attribute selector after `::part()`), which previously left
re-pointing the shared `--lr-color-warning`/`--lr-color-brand` tokens as the only lever, repainting
every other element that read them. The tone-specific resting border and hover tint use
`--lr-document-preview-highlight-accent-color`, `--lr-document-preview-highlight-success-color`,
`--lr-document-preview-highlight-warning-color`, `--lr-document-preview-highlight-danger-color`,
and `--lr-document-preview-highlight-neutral-color` (defaulting respectively to the matching
brand/success/warning/danger/neutral color tokens). `--lr-document-preview-download-link-hover-bg`
defaults to `color-mix(in oklab, var(--lr-color-brand), var(--lr-color-mix-partner)
var(--lr-color-mix-hover))`; `--lr-document-preview-download-link-active-bg` uses the same mix with
`var(--lr-color-mix-active)`, styling the native download action's hover and pressed backgrounds.
Plus shared tokens
`--lr-color-border`, `--lr-radius`, `--lr-color-surface`, `--lr-space-s/-m/-l/-xs`,
`--lr-color-text`, `--lr-color-text-quiet`, `--lr-color-danger`, `--lr-color-brand`,
`--lr-color-on-brand`, `--lr-focus-ring-width/-color/-offset`, `--lr-transition-fast`.

**Optional peer deps:** none directly — the `unsupported` slot is commonly used to compose
`<lr-code-block>` (which has its own optional `shiki` peer dependency; see that component's own
entry) or a third-party PDF/office-doc viewer, but neither is a dependency of this component itself.

```html
<lr-document-preview
  id="text-preview"
  filename="board-notes.txt"
  mime-type="text/plain"
  src="/files/board-notes.txt"
  max-height="24rem"
></lr-document-preview>

<!-- A host driving its own server-side conversion -->
<lr-document-preview filename="deck.pptx" status="converting" progress="42"></lr-document-preview>

<!-- Escape hatch for an unsupported format -->
<lr-document-preview filename="deck.pptx" mime-type="application/vnd.ms-powerpoint" src="/files/deck.pptx">
  <lr-code-block slot="unsupported" language="text">Open in PowerPoint to preview.</lr-code-block>
</lr-document-preview>
<script type="module">
  document
    .getElementById("text-preview")
    .addEventListener("lr-render-error", (e) => console.error(e.detail.error));
</script>
```

Accessibility: after the initial silent baseline, entering `"converting"` without numeric
`progress` appends the localized "Converting document…" transition to the pre-mounted shared
document-level polite sink; the visible spinner and its visually-hidden label remain ordinary,
non-live shadow content. Once finite `progress` is available, the spinner becomes a standard
`role="progressbar"`, self-describing via `aria-valuenow`, and does not duplicate that information
through the live sink. A later finite-to-indeterminate transition is announced. `status="error"`
keeps `[part="error"]` as ordinary visible text and appends later error transitions to the shared
document-level assertive sink.

**Known gotchas:**

- `status="converting"`/`status="error"` always win over format dispatch, regardless of
  `mimeType`/`src` — a `text`/`image` source is not shown until `status` returns to `"idle"`/`"ready"`.
- The component's own text/JSON `fetch(src)` is a _different_ async operation from the host-driven
  `status="converting"` conversion. A failed fetch fires `lr-render-error` and renders
  `[part="error"]` on its own; it never sets `status="error"` itself.
- changing `src` aborts the superseded text fetch as well as ignoring any stale completion; removing
  the component aborts its active request.
- `progress` is only ever consulted for the host-driven `"converting"` state — this component's own
  in-flight text fetch always renders the indeterminate spinner, with no numeric-progress path.
- the text/JSON fetch is capped at 25 MB, enforced while streaming so it holds even when the server
  omits `Content-Length`; going over renders `[part="error"]` with the localized
  `documentPreviewResourceTooLarge` message. The cap is not overridable per component. The `image`
  preview is unaffected — it hands `src` to an `<img>` rather than reading it.
- The `unsupported` slot's initial presence is detected once, before the first render, by scanning
  light-DOM children directly (not the slot's `assignedElements()`); every later slot-content change
  is instead picked up via the slot's own `slotchange` listener. Both paths keep detection correct,
  just via two different mechanisms depending on timing.
- `download-link` (and thus `lr-download`) only renders/fires when `src` is set — a generic-fallback
  state with no `src` shows only the file glyph and message, with no download affordance at all.
- `download-link` also never renders for a `data:` or `mailto:` URL, even though `data:` is accepted
  for text/image sinks and `mailto:` is accepted for navigation anchors elsewhere in the library — a
  `src="data:..."` document renders/fetches fine but falls back to no download affordance in the
  generic state, and a `mailto:` names no retrievable bytes so it cannot be a download target at all.
- A `src` that fails its sink's URL-safety check raises `lr-render-error` for the text/JSON path,
  with the localized URL-rejection error; the event is also raised when an allowed `fetch()` fails
  at the network layer. An unsafe/malformed image or download `src` is instead treated as unusable
  without an event (a silent image fallback or omitted download link — and on the image path that
  fallback is the download fallback directly, so an `unsupported` slot the host supplied is
  bypassed).

---

## `lr-document-viewer`

A dialog-hosted, format-dispatching full viewer for one document or attachment. It uses a pluggable
renderer registry and falls back to `<lr-document-preview>` when no renderer matches the file's MIME
type. First-party invention.

MIME matching uses the case-insensitive essence before parameters and ignores outer whitespace. An
extensionless `application/*+xml` file selects the XML renderer when it is registered, including a
value such as ` APPLICATION/ATOM+XML ; charset=utf-8 `. Exact registry keys retain precedence,
filename extensions remain a fallback, and the renderer receives the original MIME value.

A host `aria-label` names the nested dialog by attribute presence, including an explicitly empty
value, without suppressing the visible `name` heading.

**Properties:**

- `open: boolean = false` (reflected) — opens or closes the viewer dialog.
- `name: string = ''` — display name passed to the renderer and used as the dialog heading.
- `mimeType: string = ''` (attribute `mime-type`) — MIME type used for exact renderer dispatch.
- `src: string = ''` — source URL passed to the selected renderer or the fallback preview.
- `payload?: LyraDocumentRendererPayload` (attribute: false) — opt-in renderer-specific input.
  Assignment immediately clones, validates, bounds, and freezes the payload. While set,
  `payload.file` is authoritative for MIME dispatch, the dialog heading, renderer/fallback input,
  anchors/highlights, and download; the scalar `name`, `mimeType`, `src`, `anchor`, `highlights`,
  and `alt` properties resume their legacy behavior when `payload` is reset to `undefined`.
- `registry?: DocumentRendererRegistry` (attribute: false) — optional per-instance registry
  override. Assign either a native map or the result of `createDocumentRendererRegistry()`; both
  use the same bounded snapshot behind a frozen readonly facade. Definition records are cloned and
  frozen while callback identities are retained. Later source-map or definition mutation is not
  observed. Reassigning the same source or retained snapshot leaves the snapshot unchanged. When unset, the
  instance owns an immutable snapshot of the built-ins registered when it was constructed. A later
  module import/registration cannot mutate an existing viewer. A throwing consumer matcher or
  renderer is contained as the localized error state rather than escaping the update.
- `alt?: string` — media alt text forwarded to the resolved renderer, for image-like renderers.
  Unset lets the renderer derive its fallback; an explicit `''` preserves decorative media.
- `anchor: LyraAnchor | string | null = null` (attribute: false) — declarative scroll-to-anchor
  target forwarded to the resolved renderer; a string is a highlight id in `highlights`.
  `hasChanged: () => true`, so re-assigning the same value (e.g. re-clicking the same citation
  badge) still re-fires.
- `highlights: readonly LyraHighlight[] = []` (attribute: false) — highlights forwarded to the resolved
  renderer after the shared trimmed, nonempty, first-wins identity normalization.

**Events:**

- `lr-close` — `detail: DocumentViewerCloseReason`, the viewer shell dialog's dismissal reason.
  The event is emitted after the viewer sets `open` to `false`. A registered renderer may compose
  its own descendant dialog; closing that inner dialog keeps its own `lr-close` path — the shell
  guards on `event.target !== event.currentTarget` — and does not close the document viewer.
  (`<lr-dialog>`'s close event was spelled `lr-dialog-close` before 10.0.0.)
- `lr-download` — `detail: { src, filename }`, emitted when the native safe download action is
  activated. The browser download itself is handled by the link.
- `lr-anchor-result` — `detail: { found }`. Emitted by this shell as `{ found: false }` once per
  applied `anchor` when a resolved renderer can't honor it (it declares no `capabilities.anchors`,
  or none matching the anchor's `kind`). When the file uses `<lr-document-preview>`—including after
  a lazy renderer fails to load—the shell delegates to that preview's `scrollToAnchor()` and emits
  its actual `found` result. A capable renderer instead emits its own `lr-anchor-result` from its
  embedded `DocumentAnchorTarget` mixin, which composes up through this element unchanged — the
  shell stays silent in that case, so the event fires exactly once either way. A string `anchor`
  (a highlight id) counts as supported by any renderer declaring at least one anchor kind.
- `lr-render-error` — `detail: { error }`. The fallback preview or an embedded renderer emits this
  when fetching, parsing, sanitizing, or rendering fails; the composed event reaches the document
  viewer unchanged.

**CSS parts:** `body` — wrapper around the active renderer, loading/error state, or fallback preview;
it renders explicit `aria-busy="true"|"false"`. Visible loading/error text is ordinary non-live
shadow content; later loading and error transitions use the pre-mounted shared document-level
polite and assertive sinks, respectively;
`download-link` — the native download action, rendered when `src` passes Lyra's safe-link policy.

**Themeable custom properties:** `--lr-document-viewer-max-height` (default `70vh`) — maximum block
size of `[part="body"]` before the dialog body scrolls internally.
`--lr-document-viewer-min-height` (default `var(--lr-size-12rem)`) — minimum block size of
`[part="body"]` before it grows to fit content.
`--lr-document-viewer-width` (default `auto`) — assertive inline size for the nested dialog panel,
forwarded straight to `<lr-dialog>`'s own `--lr-dialog-width`; set this on `<lr-document-viewer>`
itself rather than reaching through to `--lr-dialog-width` directly, which stays an internal detail
of the nested dialog. Left at `auto` the panel keeps shrink-wrapping to content, capped by the
dialog's own `--lr-dialog-max-width` tier.
`--lr-document-viewer-download-link-hover-bg` defaults to `color-mix(in oklab,
var(--lr-color-brand), var(--lr-color-mix-partner) var(--lr-color-mix-hover))`, and
`--lr-document-viewer-download-link-active-bg` uses `var(--lr-color-mix-active)` in that same mix
for the native download action's hover and pressed backgrounds.

**Renderer registry exports:**

- `DocumentFile` — 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.
- `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.
- `LyraGenericDocumentRendererPayload` / `LyraAvDocumentRendererPayload` — the concrete
  `kind: 'document'` and `kind: 'av'` branches. `LyraDocumentRendererPayloadKind` names their kind
  union, and `LyraDocumentRendererPayloadFor<K>` extracts one branch for adapter authoring.
- `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
  `{ 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
  single source of truth. Adapted definitions register eagerly; a lazy definition resolves a
  legacy direct renderer, keeping the static and payload-derived capability branches distinct.
- `LyraAdaptedDocumentRendererDefinition` / `LyraResolvedDocumentRendererDefinition` — the adapted
  registry branch and the union of both immediately renderable branches. `LyraAdaptedDocumentRenderer`
  is the frozen payload/capabilities/render invocation returned by `adaptDocumentRenderer()`.
- `DocumentRendererRegistry` — `ReadonlyMap<string, DocumentRendererDefinition>`.
- `createDocumentRendererAdapter(definition)` — preserves discriminator-specific callback types
  while producing the validated adapter accepted by a registry definition.
- `adaptDocumentRenderer(definition, file, payload?)` — binds one resolved definition to an
  immutable payload and derives its frozen capabilities. It snapshots the file once and passes
  that canonical object to either the adapter or legacy renderer; caller object identity is not
  retained across this boundary.
- `snapshotLyraDocumentRendererPayload(payload)` — returns the same validated, bounded, frozen
  assignment snapshot used by `<lr-document-viewer>`.
- `createDocumentRendererRegistry(overrides?)` — returns a truly immutable built-in snapshot plus
  optional per-instance overrides. MIME keys are trimmed, lowercased, and reduced to their essence.
- `registerDocumentRenderer(key, definition)` — adds or replaces a built-in-builder entry for
  registry snapshots created later; it never mutates existing instances.
- `findDocumentRenderer(file, registry?)` — checks normalized MIME essence (case-insensitive and
  parameter-independent), then the first matching `matches()` entry in registration order.
- `loadDocumentRenderer(definition)` — resolves and identity-caches a lazy direct definition;
  rejected loads are retried on the next call.

Every built-in kind ships a lazy, register-only entry named `<kind>-viewer-register.js`
(`archive-viewer-register.js`, `ebook-viewer-register.js`, `pdf-viewer-register.js`,
`docx-viewer-register.js`, `pptx-viewer-register.js`, `spreadsheet-viewer-register.js`,
`csv-viewer-register.js`, `xml-viewer-register.js`), which installs that kind's registration
without pulling its element class module into the importing graph until a matching file is
actually opened, and exports a `<KIND>_VIEWER_TAG` string constant naming the tag it eventually
registers. `document-viewer/document-viewer-kinds.js` imports and re-exports all eight at once, for
a consumer who wants every built-in kind available lazily without importing each entry
individually. `<lr-document-viewer>` itself (`document-viewer.js`) is always a separate import.

```html
<lr-document-viewer
  open
  name="report.pdf"
  mime-type="application/pdf"
  src="/files/report.pdf"
></lr-document-viewer>
```

Construct and inject a renderer registry per application/viewer. The definition may load a heavy
optional viewer only when a matching document is opened:

```ts
import { createDocumentRendererRegistry } from "@aceshooting/lyra-ui/components/viewers/document-viewer/registry.js";

const registry = createDocumentRendererRegistry([
  ["application/x-example", { render: (file) => `Preview: ${file.name}` }],
]);

html`<lr-document-viewer .registry=${registry}></lr-document-viewer>`;
```

Supply AV metadata without widening every legacy renderer callback. The built-in AV adapter always
declares `time-range` anchors and declares search only when the retained cue snapshot contains
non-whitespace transcript or speaker text:

```ts
import type { LyraDocumentRendererPayload } from "@aceshooting/lyra-ui/components/viewers/document-viewer/registry.js";

const payload = {
  kind: "av",
  file: { name: "episode.mp4", mimeType: "video/mp4", src: "/episode.mp4" },
  cues: [{ cueId: "intro", start: 0, text: "Welcome", speaker: "Host" }],
  tracks: [
    {
      src: "/episode-en.vtt",
      kind: "captions",
      srclang: "en",
      label: "English",
    },
  ],
} satisfies LyraDocumentRendererPayload;

html`<lr-document-viewer open .payload=${payload}></lr-document-viewer>`;
```

When no renderer matches, the viewer renders `<lr-document-preview>`, which handles text and images
inline and provides a safe generic fallback for other formats.

If a consumer matcher/renderer throws while an anchor is pending, the viewer renders localized
ordinary error text, appends the transition to the shared document-level assertive sink, and emits
exactly one `lr-anchor-result` with `{ found: false }`.

## `lr-docx-viewer`

Fetches a `.docx` Word document as an `ArrayBuffer`, converts it to semantic HTML with the optional
`mammoth` peer, sanitizes that HTML through the optional `dompurify` peer, and renders the result.
Mammoth preserves document structure such as headings, paragraphs, lists, tables, and validated
inline raster images; it is not intended to reproduce pixel-exact Word page layout. There is no
unsanitized rendering escape
hatch: if `dompurify` is unavailable, rendering is blocked even when Mammoth converted successfully.
Converted markup then passes through the passive-document profile: anchors, form controls, and
custom elements are unwrapped to ordinary text/children where safe, remote navigation/resource
attributes are removed, and an `<a>` itself never remains. Images render only inline base64 GIF,
JPEG, PNG, or WebP data; same-document SVG fragment references may remain.

Every rendered heading's slug (the same GitHub-slugger-style algorithm `<lr-markdown>` uses) is
stamped as its `id` and cached into `getHeadingTree()`'s document-ordered outline. Duplicate
headings receive monotonic `-1`, `-2`, … suffixes; used suffixes are never re-probed for the same
base, so one bounded heading pass performs linear aggregate dedupe work. Adopts
`DocumentAnchorTarget`: `fragment` anchors resolve against that outline, `text-quote` anchors via
the shared quote-scoping helpers; `highlights` re-resolve by quote after every render. Native
keyboard actions are exposed only for highlights whose quote resolves in the currently loaded
document; unresolved highlights and idle/loading/error states never expose an enabled no-op.

**Properties:** `src: string = ''`, `name: string = ''`, and `maxHeight: string = ''` (attribute
`max-height`). A nonempty host `aria-label` makes the host the sole named semantic owner. With an
explicitly empty host label, the shadow document keeps `role="document"` and an empty accessible
name; when the attribute is absent, `name` and the localized label are fallbacks. `maxHeight` caps the
scrollable document body; invalid CSS `max-height` values, declaration breaks, and `url()` are
ignored. The inherited anchor-target properties are `highlights: readonly LyraHighlight[] = []` (property
only; reassign after mutation), `activeHighlightId: string | null = null` (attribute
`active-highlight-id`), `anchor: LyraAnchor | string | null = null` (property only), and
`anchorKinds: readonly LyraAnchorKind[] = ['fragment', 'text-quote']` (this viewer's supported
`LyraAnchor.kind` values).

**Methods:** `getHeadingTree()` returns the document-ordered outline as `DocxHeadingItem[]` (`{ id,
label, level }`), cached on every successful load. `search(query)` resolves the match count via a
case-insensitive substring search over the rendered content's text (empty/whitespace query behaves
like `clearSearch()`); `searchNext()`/`searchPrevious()` advance/step back through matches
(wrapping, resolving `false` when there are none); `clearSearch()` clears the query, matches, and
painted marks. It indexes at most 1,000,000 code units/20,000 text nodes per content generation,
accepts at most 4,096 query code units, scans at most 4,000,000 code units, retains 1,000 matches,
and paints a 200-range search window.

**Events:** `lr-render-error` with `detail.error` only when fetching, conversion, or sanitization
fails terminally. Non-fatal Mammoth conversion messages emit `lr-viewer-diagnostic` instead;
`detail.diagnostic` is readonly `{ code: 'docx-conversion-message', severity: 'warning', fatal:
false, source: 'mammoth', cause }`. `lr-search-change` (`detail: { query, matchCount,
matchCountExact, activeIndex }`) — from search/navigation/clear, canonical source reset, and
effective-locale re-evaluation.
`lr-highlight-activate` (`detail: { highlightId }`) — a painted `text-quote` highlight was clicked or its
resolved keyboard action was activated.
`lr-text-select` (`detail: { text, anchor, rects }`) — fired on selection end inside the rendered
content. `lr-anchor-result` (`detail: { found }`) — fired after an `anchor` assignment or a
`scrollToAnchor()` call.

Mammoth's conversion result is usable only when it has own-data `value: string` and an own-data
`messages` array; an unusable primary result is terminal. From a usable result, the first 100
message positions are considered, malformed entries are omitted, and valid opaque causes are
retained in their diagnostics. Sanitized document content remains visible while those non-fatal
diagnostics are emitted.

**CSS parts:** `base`, `body`, `content`, `spinner`, `error`, `highlight` (a painted `text-quote`
highlight), `highlight-actions` (keyboard-accessible actions for resolved highlights),
`highlight-action` (one native highlight activation button), `search-match` (a painted in-document
search match), and `search-match-active` (the currently active search match, also carries
`search-match`), plus `anchor-live-region` (an aria-hidden, non-live shadow mirror of the latest
anchor-jump message; the spoken copy is appended to the shared document-level polite sink only
while the viewer and its composed ancestors are exposed to the accessibility tree).

**Themeable custom properties:** `--lr-docx-viewer-max-height` (default `none`) — maximum block size
of `[part="body"]`; also settable via the `max-height` property, which writes this token inline.
`--lr-docx-viewer-table-header-background` (default `var(--lr-color-brand-quiet)`) retints a
rendered document table's header row (`th`), independent of the highlight backgrounds below.
Highlight backgrounds are independently themeable with
`--lr-docx-viewer-highlight-accent-background`,
`--lr-docx-viewer-highlight-success-background`,
`--lr-docx-viewer-highlight-warning-background`,
`--lr-docx-viewer-highlight-danger-background`, and
`--lr-docx-viewer-highlight-neutral-background`, defaulting to the matching quiet color tokens --
except neutral, which defaults to `var(--lr-color-surface-raised)`: `[part='content']` paints no
background of its own and therefore shows `[part='base']`'s `--lr-color-surface`, so a neutral
highlight falling back to that same token would render as unhighlighted.
`--lr-docx-viewer-highlight-active-background` and
`--lr-docx-viewer-highlight-active-outline` style the active host highlight.
`--lr-docx-viewer-search-match-background`,
`--lr-docx-viewer-search-match-active-background`, and
`--lr-docx-viewer-search-match-active-foreground` style resting and active search matches.

**Optional peer dependencies:** install `mammoth` and `dompurify` with `pnpm add mammoth dompurify`.
The component registers an eager `application/vnd.openxmlformats-officedocument.wordprocessingml.document`
renderer with `<lr-document-viewer>` (a plain `render`, no `load()` hook — importing this module
defines `<lr-docx-viewer>` immediately; only `mammoth`/`dompurify` themselves are loaded on demand)
and matches `.docx` filenames when the MIME type is generic.

A granular consumer (not importing the `all.js` compatibility bundle) who wants `<lr-docx-viewer>`'s
own class module deferred too can instead import
`@aceshooting/lyra-ui/components/viewers/docx-viewer/docx-viewer-register.js`, which installs the
same registration lazily and exports `DOCX_VIEWER_TAG` (`'lr-docx-viewer'`) as a stable reference to
the tag it eventually registers.

Remote resources are capped at 25 MB; exceeding it surfaces the localized
`documentPreviewResourceTooLarge` message instead of the document.

```html
<lr-docx-viewer
  src="/files/report.docx"
  name="report.docx"
  max-height="32rem"
></lr-docx-viewer>
```

## `lr-email-viewer`

Fetches and parses `.eml` messages with the optional `postal-mime` peer. HTML message bodies are
sanitized through the existing optional `dompurify` peer before rendering; plain-text messages
remain available without DOMPurify. Attachments are listed as filename and size only (the parsed
`mimeType` never reaches the DOM) and their content is never rendered by this component. Each
attachment row is a real `<button>` that emits `lr-attachment-open` with an immutable Blob snapshot
of the decoded bytes; opening, downloading, or object-URL'ing them is the host's job (e.g.
`URL.createObjectURL(content)` → `<lr-document-viewer>` → revoke on
`lr-close`).
An attachment with no filename uses the localized `emailViewerUnnamedAttachment` fallback
(`"Unnamed attachment"` in English) for its visible name, open-button accessible name, and
`lr-attachment-open` detail. The fallback resolves while rendering, so changing the locale or
per-instance `strings` after the message loads updates it without reparsing the message.

When `foldQuotes` is enabled, `search(query)` reveals matching supported plain-text and HTML quoted
replies before navigating. Reveal uses the shared text index's Unicode normalization, whitespace
collapse, soft-hyphen removal, locale matching, and query/work bounds, so padded or normalized
queries reveal the same quote as ordinary matching text. Folding remains opt-in.

Parser output is admitted through a bounded direct-data projection: malformed optional fields,
recipients, and attachment entries are omitted without discarding later valid siblings. Accepted
string, `Uint8Array`, and `ArrayBuffer` attachment bytes are copied before use, and every
`lr-attachment-open` creates a fresh Blob, so later source mutation cannot change event bytes.

Sanitized HTML uses the passive-document profile: anchors, form controls, and custom elements are
unwrapped to ordinary text/children where safe, remote navigation/resource attributes are removed,
and an `<a>` itself never remains. Images render only inline base64 GIF, JPEG, PNG, or WebP data;
same-document SVG fragment references may remain.

Remote resources are capped at 25 MB; exceeding it surfaces the localized
`documentPreviewResourceTooLarge` message instead of the message.

**Properties:** `src: string = ''`, `name: string = ''`, and `maxHeight: string = ''` (attribute
`max-height`); invalid CSS
`max-height` values, declaration breaks, and `url()` are ignored. `foldQuotes: boolean = false`
(attribute `fold-quotes`) — collapses trailing quoted-reply text/HTML behind a
localized show/hide toggle. `false` (the default) preserves the full body rendering. A nonempty
host `aria-label` makes the host the sole named semantic owner; an explicitly empty host label
keeps the shadow `region` with an empty name, and an absent host label falls back to `name` or the
localized label. `highlights`, `activeHighlightId`, `anchor`, and
`anchorKinds` (`['text-quote', 'fragment']`) provide the shared text-viewer contract. A fragment is
an exact DOM `id` lookup: Lyra generates no ids for message headers or a plain-text body, while an
HTML message can resolve only an id retained from its sanitized body. Without such an id the jump
reports `found: false`; text-quote anchors work across all rendered message text.

**Methods:** `search(query)`, `searchNext()`, `searchPrevious()`, `clearSearch()`, and
`scrollToAnchor()` operate on rendered message text and emit the shared search/anchor events.

**Events:**

- `lr-render-error` with `detail.error` when fetching or parsing fails.
- `lr-attachment-open` — recursively frozen `detail: { attachment: { filename, mimeType,
  content?: Blob } }`; call `content.arrayBuffer()` to read the immutable copied bytes. This
  replaces the mutable `Uint8Array` event field.
- `lr-search-change` — `detail: { query: string; matchCount: number; matchCountExact: boolean; activeIndex: number }` — fired
  whenever rendered-message search state changes.
- `lr-anchor-result` — `detail: { found: boolean }` — fired after an `anchor` assignment or
  `scrollToAnchor()` call is applied.
- `lr-text-select` — `detail: TextSelectDetail` (`{ text: string; anchor: LyraAnchor | null; rects:
DOMRect[] }`) — fired after a selection ends inside the rendered message.

`lr-highlight-activate` is not part of this viewer's event contract: painted text highlights are
passive and cannot be activated.

The three shared text-viewer events bubble and compose and are non-cancelable.

**CSS parts:** `base`, `headers`, `from-label`, `from`, `to-label`, `to`, `subject-label`, `subject`,
`date-label`, `date`, `body`, `body-html`, `body-text`, `attachments`, `attachments-label`,
`attachment-list`, `attachment-item`, `attachment-button` (an attachment's open button, inside its
`attachment-item`), `attachment-name` (an attachment's filename, inside `attachment-button`),
`attachment-size` (an attachment's formatted file size, inside `attachment-button`), `quoted` (a
folded quoted-text block, hidden until expanded, only while `foldQuotes`), `quote-toggle` (the
show/hide-quoted-text toggle button, only while `foldQuotes`), `spinner`, `error`, and
`anchor-live-region` (an aria-hidden, non-live shadow mirror of the latest anchor-jump message; the
spoken copy is appended to the shared document-level polite sink only while the viewer and its
composed ancestors are exposed to the accessibility tree).

**Themeable custom properties:** `--lr-email-viewer-max-height` (default `none`) — maximum block size
of `[part="body"]`; also settable via the `max-height` property, which writes this token inline.

**Optional peer dependencies:** install `postal-mime` and `dompurify` with
`pnpm add postal-mime dompurify`. The component registers `message/rfc822` and falls back to
matching `.eml` filenames in `<lr-document-viewer>`. Fail-closed behavior is explicit: an absent
`postal-mime` renders `[part="error"]` with the localized
`emailViewerMissingParser` message (nothing is parseable without it), and an HTML-only message
(no `text/plain` alternative) with `dompurify` absent renders the localized
`documentViewerMissingSanitizer` message rather than silently showing an empty body.

## `lr-calendar-viewer`

Fetches and parses `.ics` calendars with the optional `ical.js` peer and renders each VEVENT as
plain text, including its title, start/end time, location, and description. RFC 5545 `DATE` values
remain all-day dates rather than fabricated midnight times, and an all-day `DTEND` is displayed as
the exclusive boundary it represents (14–17 renders as 14–16). No HTML is injected.

Valid early all-day dates, including years `0001`, `0099`, and `0100`, retain their UTC calendar
year when parsed through `ical.js`; the exclusive `DTEND` display rule remains unchanged. The peer
may normalize malformed raw date fields before Lyra receives them.

**Properties:** `src: string = ''`, `name: string = ''`, and `maxHeight: string = ''` (attribute
`max-height`); invalid CSS
`max-height` values, declaration breaks, and `url()` are ignored. A host `aria-label` takes
precedence over `name` by attribute presence, including an explicitly empty value. `highlights`,
`activeHighlightId`, `anchor`, and
`anchorKinds` (`['text-quote', 'fragment']`) provide the shared text-viewer contract. Fragment
resolution is an exact DOM `id` lookup, but generated event markup defines no fragment ids, so a
fragment jump reports `found: false`. Use a text-quote anchor for event content.

**Methods:** `search(query)`, `searchNext()`, `searchPrevious()`, `clearSearch()`, and
`scrollToAnchor()` operate on rendered event text and emit `lr-search-change`/`lr-anchor-result`.

**Events:**

- `lr-render-error` with `detail.error` when fetching or parsing fails.
- `lr-search-change` — `detail: { query: string; matchCount: number; matchCountExact: boolean; activeIndex: number }` — fired
  whenever rendered-calendar search state changes.
- `lr-anchor-result` — `detail: { found: boolean }` — fired after an `anchor` assignment or
  `scrollToAnchor()` call is applied.
- `lr-text-select` — `detail: TextSelectDetail` (`{ text: string; anchor: LyraAnchor | null; rects:
DOMRect[] }`) — fired after a selection ends inside the rendered calendar.

`lr-highlight-activate` is not part of this viewer's event contract: painted text highlights are
passive and cannot be activated.

The three shared text-viewer events bubble and compose and are non-cancelable.

**CSS parts:** `base`, `body`, `event-list`, `event`, `event-summary`, `event-time`, `event-location`,
`event-description`, `spinner`, `error`, and `anchor-live-region` (an aria-hidden, non-live shadow
mirror of the latest anchor-jump message; the spoken copy is appended to the shared document-level
polite sink only while the viewer and its composed ancestors are exposed to the accessibility tree).

**Themeable custom properties:** `--lr-calendar-viewer-max-height` (default `none`) — maximum block
size of `[part="body"]`; also settable via the `max-height` property, which writes this token inline.

**Optional peer dependency:** install `ical.js` with `pnpm add ical.js`. The component registers
`text/calendar` and falls back to matching `.ics` filenames in `<lr-document-viewer>`.

Remote resources are capped at 25 MB; exceeding it surfaces the localized
`documentPreviewResourceTooLarge` message instead of the calendar. The accepted model is further
capped at 250 events and 2 MiB of rendered event text; this keeps the complete accepted document in
the DOM so search, selection and text-quote anchors remain truthful without the former 10,000-event
eager tree.

## `lr-archive-viewer`

Lists entry names and human-readable declared uncompressed sizes inside a `.zip` archive. It is
listing-only: entry content is never inflated, rendered, or previewed, and the component has no
runtime archive-parser dependency. One owned central-directory parser validates local-header
bounds, supported compression methods, entry names, and the 10,000-entry/100 MB declared-expansion
ceilings, then returns the immutable metadata used directly by the listing. The list composes
`<lr-virtual-list>` for large archives.

**Properties:** `src: string = ''`, `name: string = ''`, and `maxHeight: string = ''` (attribute
`max-height`) — a host-level `aria-label` takes precedence over `name` by attribute presence,
including an explicitly empty value, when naming the `role="region"` listing. `maxHeight` caps the
scrollable archive body; invalid CSS `max-height` values, declaration breaks, and `url()` are
ignored. The viewer also exposes the shared text-viewer
contract: `highlights`, `activeHighlightId`, `anchor`, and `anchorKinds` (`['text-quote', 'fragment']`).

**Methods:** `search(query)`, `searchNext()`, `searchPrevious()`, and `clearSearch()` provide
case-insensitive text search over every loaded entry path; next/previous wrap and scroll the active
virtualized row into view. Queries are capped at 4,096 code units and each pass at 4,000,000 path
code units; `matchCountExact: false` reports a ceiling-truncated lower bound. `scrollToAnchor()` resolves text-quote and fragment anchors and emits
`lr-anchor-result`. A fragment id is the exact ZIP entry path. A text quote resolves within one
complete entry path; both forms first mount the absolute virtualized row and only then perform the
shared DOM-level anchor resolution. Rendered rows intentionally do not expose entry paths as DOM
ids; the fragment mapping is resolved against archive metadata. A jump whose archive is replaced
by a concurrent `src` reassignment mid-flight, or whose row cannot be located after the wait,
reports `found: false` rather than a phantom success.

**Events:** `lr-render-error` with `detail.error` when fetching or parsing fails;
`lr-search-change` (`detail: { query, matchCount, matchCountExact, activeIndex }`) from search,
navigation, clear, canonical source reset, and effective-locale re-evaluation; `lr-text-select`
(`detail: { text, anchor, rects }`) for a selection contained within one
entry path; and `lr-anchor-result` (`detail: { found }`) after anchor resolution.
`lr-highlight-activate` is not part of this viewer's event contract: archive entry-path highlights
are passive and cannot be activated.

**CSS parts:** `base`, `body`, `entry`, `entry-icon`, `entry-name`, `entry-name-dir`, `entry-size`,
`highlight` (the `<mark>` fallback for a painted entry-path quote), `spinner`, `error`, and
`anchor-live-region` (an aria-hidden, non-live shadow mirror of the latest anchor-jump message; the
spoken copy is appended to the shared document-level polite sink only while the viewer and its
composed ancestors are exposed to the accessibility tree). A directory row's name element carries
both `entry-name` and
`entry-name-dir` (a part list), so `::part(entry-name-dir)` selects only directory names while
`::part(entry-name)` still selects every name. Entry rows are rendered into the embedded
`<lr-virtual-list>`'s own shadow root and forwarded with `exportparts`, so
`lr-archive-viewer::part(entry)` (and every other row part above) reaches them from a consuming
stylesheet.

**Themeable custom properties:** `--lr-archive-viewer-max-height` (default `none`) caps the
scrollable `[part="body"]` and is also settable through `maxHeight`/`max-height`.
`--lr-archive-viewer-highlight-accent-background`,
`--lr-archive-viewer-highlight-success-background`,
`--lr-archive-viewer-highlight-warning-background`,
`--lr-archive-viewer-highlight-danger-background`, and
`--lr-archive-viewer-highlight-neutral-background` control tone backgrounds. The neutral default is
`var(--lr-color-surface-raised)`, deliberately not `--lr-color-surface`: entry rows paint no
background of their own and therefore show the viewer's `--lr-color-surface`, so a neutral highlight
falling back to that same token would render as unhighlighted.
`--lr-archive-viewer-highlight-active-background` and
`--lr-archive-viewer-highlight-active-outline` control the active quote.

**Exports:** `ArchiveEntry` — `{ name: string; dir: boolean; size: number }`.

The lazy registry registers `application/zip` and `application/x-zip-compressed`, with a `.zip`
filename fallback, and imports the viewer only when a matching archive is opened. Both registrations declare
`capabilities: { anchors: ['text-quote', 'fragment'], search: true, textSelect: true }` — sibling to
`load`, not inside it, so feature detection can read the capabilities without paying for the lazy
import. Opening a `.zip` through `<lr-document-viewer>` forwards `anchor`/`highlights` to the mounted
viewer, so a deep link into an entry name survives the registry hop. `.tar`, `.rar`, and other
archive formats fall through to `<lr-document-preview>`'s generic download fallback.

A granular consumer (not importing the `all.js` compatibility bundle) must import
`@aceshooting/lyra-ui/components/viewers/archive-viewer/archive-viewer-register.js` once to install
this registration; without it `<lr-document-viewer>` never recognizes `.zip` files and falls
through to the generic download fallback described above. That entry also exports
`ARCHIVE_VIEWER_TAG` (`'lr-archive-viewer'`) as a stable reference to the tag it eventually
registers.

Remote resources are capped at 25 MB; exceeding it surfaces the localized
`documentPreviewResourceTooLarge` message instead of the entry listing.

## `lr-ebook-viewer`

Renders EPUB ebooks through the optional `epubjs` peer. `src` is fetched as an `ArrayBuffer`, and
epub.js renders the reading area into its stable `mount` element, using an internal iframe for
chapter content. A usable book exposes `ready`, `renderTo()`, and `destroy()`, and its rendition
exposes `display()`, `prev()`, `next()`, `on()`, and `annotations.highlight()`/`remove()`; an absent
required capability is terminal. Navigation and spine data are optional.

Genuine native `Selection`/`Range` objects from the current chapter iframe are accepted through
platform accessors, including across document realms. Arbitrary peer-owned accessors remain
uninvoked, and callbacks from replaced or disconnected books cannot emit stale selections.

**Properties:** `src: string = ''` and `name: string = ''`. A plain `aria-label` attribute on the
host overrides the reading region's accessible name — by attribute presence, so an explicitly empty
`aria-label=""` still wins over `name`. (There is no matching JS property: the `accessibleLabel`
property was removed in 9.0.0, where it had never been readable or writable to any effect — set the
attribute.) `maxHeight: string = ''`
(attribute `max-height`) caps the `mount` area epub.js renders into; invalid CSS `max-height`
values, declaration breaks, and `url()` are ignored. `location: string = ''`
(not reflected — CFIs are long) is
a CFI or spine href identifying the current reading position: set before the book finishes
loading it's recorded and applied once ready, set after it applies immediately, and epub.js's own
`relocated` event keeps it in sync with user navigation without re-triggering its own `display()`
call. A controlled `location` assignment made synchronously inside `lr-location-change` wins over
the peer-reported CFI and is displayed. `anchorKinds: readonly LyraAnchorKind[] = ['cfi',
'text-quote']` (this
viewer's supported `LyraAnchor.kind` values for the shared anchor-target contract).

**Methods:** `getToc()` resolves the EPUB's own navigation document (`book.navigation.toc`,
populated once `book.ready` resolves) flattened into document-ordered `EbookTocItem[]` (`{ id,
label, href, level }`, `level` starting at 1 for a top-level entry, `id` falling back to `href`
when a navigation entry has none), `[]` before a book has loaded or when navigation is absent. TOC
projection examines at most 10,000 positions, nodes, and depth 100; malformed entries are skipped
without preventing later valid entries. `search(query)` resolves the
match count across every spine section, in document order, via epub.js's own `item.load()`/
`item.find()`/`item.unload()` (empty/whitespace query behaves like `clearSearch()`; a newer
`search()` call or a `src` change aborts an in-flight scan; peer output is capped at 10,000
matches after at most 1,000 spine items and 4,000,000 result code units; queries are capped at 4,096
code units); `searchNext()`/`searchPrevious()`
advance/step back through matches (wrapping, resolving `false` when there are none); `clearSearch()`
clears the query, matches, and painted search annotation. `matchCountExact: false` also reports
malformed or holey spine/find data and failed section load/unload work, not only a search ceiling.

**Events:** `lr-render-error` with `detail.error` when fetching, opening, or rendering fails;
`lr-location-change` (`detail: { cfi, href }`) fired from epub.js's own `relocated` event;
`lr-search-change` (`detail: { query, matchCount, matchCountExact, activeIndex }`) from search,
navigation, clear, canonical source reset, and effective-locale re-evaluation; `lr-anchor-result`
(`detail: { found }`) after an anchor is
applied; `lr-highlight-activate` (`detail: { highlightId }`) when a painted CFI highlight is clicked; and
`lr-text-select` (`detail: { text, anchor, rects }`) after selection inside a chapter iframe.
Selection text is capped at 4,096 code units and selection rectangles at 1,000.

**CSS parts:** `base` (explicit `aria-busy="true"|"false"`; visible loading text is ordinary
non-live shadow content and later loading transitions use the shared document-level polite sink),
`toolbar`, `previous-button`, `next-button`, `previous-icon`, `next-icon`,
`mount`, and `error` (ordinary visible text; later error transitions use the shared document-level
assertive sink), plus `anchor-live-region` (an aria-hidden, non-live shadow mirror of the latest
anchor-jump message; the spoken copy is appended to the shared document-level polite sink only
while the viewer and its composed ancestors are exposed to the accessibility tree). Search results
are appended to the shared document-level polite sink, which lives in the host's light DOM; the
empty `announcer` shadow mirror that used to carry a part of that name was removed in 9.0.0 (it had
no styling of its own and never held any text).

**Themeable custom properties:** `--lr-ebook-viewer-max-height` (default `none`) — maximum block
size of `[part="mount"]` before it scrolls internally; also settable via the `max-height` property,
which writes this token inline.

The toolbar buttons use the component-specific localized labels `ebookViewerPreviousChapter` and
`ebookViewerNextChapter` (English: “Previous chapter” / “Next chapter”), so they remain
unambiguous beside other previous/next controls and are overridable through `.strings`.

**Optional peer dependency:** install `epubjs` with `pnpm add epubjs`. The document-viewer registry
matches `application/epub+zip` and `.epub` filenames, declaring `{ anchors: ['cfi', 'text-quote'],
search: true, textSelect: true }` capabilities and forwarding `anchor`/`highlights` to the mounted
viewer. The peer loader requires the callable EPUB factory; malformed module shapes fail closed.
A granular consumer (not importing the `all.js` compatibility bundle) must also import
`@aceshooting/lyra-ui/components/viewers/ebook-viewer/ebook-viewer-register.js` once to install
this registration; without it `<lr-document-viewer>` never recognizes `.epub` files. That entry also
exports `EBOOK_VIEWER_TAG` (`'lr-ebook-viewer'`) as a stable reference to the tag it eventually
registers.

Remote resources are capped at 25 MB; exceeding it surfaces the localized
`documentPreviewResourceTooLarge` message instead of the ebook.

Adopts the shared anchor-target contract (`highlights`, `activeHighlightId`, `scrollToAnchor()`,
events `lr-highlight-activate`/`lr-text-select`/`lr-anchor-result`): a `cfi` anchor displays
directly via `rendition.display()`; a `text-quote` anchor resolves by scanning the spine with
epub.js's own `item.find()`, since chapter content lives inside epub.js-owned iframes rather than
this component's own shadow DOM — `lr-text-select` mirrors epub.js's own `selected` event for the
same reason. `highlights` (kind `cfi`) paint via `rendition.annotations.highlight()` and are
re-applied whenever the rendition is recreated (a `src` change, or a reconnect remount), since
epub.js doesn't persist annotations across a fresh `renderTo()`.

Rejected or synchronous failures from display, previous/next navigation, search annotation, or
anchor application enter the localized error state and emit `lr-render-error`. Anchor failures
emit one `{ found: false }`, and superseded async anchor/search work cannot mutate the current book.

## `lr-pptx-viewer`

Best-effort client-side PPTX viewer backed by the optional `@aiden0z/pptx-renderer` peer. A
localized fidelity notice is always visible because animations, equations, embedded objects,
speaker notes, and several advanced effects are not rendered.

**Properties:** `src: string = ''`, `name: string = ''`, `label?: string`, `page: number = 1`
(reflected, one-based current slide), and `maxHeight: string = ''` (attribute `max-height`). Assigning
`page` while ready navigates to that slide. Omitting `label` reads back `undefined` and falls back to
`name`, then a localized default; an explicit empty string clears it. A host
`aria-label` takes precedence over
`label` and `name`. `maxHeight` caps the scrollable `[part="container"]`; invalid CSS `max-height`
values, declaration breaks, and `url()` are ignored. `highlights`, `activeHighlightId`, `anchor`,
and `anchorKinds`
(`['text-quote', 'fragment']`) provide the shared text-viewer contract when the renderer exposes
DOM text. Lyra defines no fragment ids for slides. A fragment can resolve only an exact DOM `id`
exposed by the optional renderer in its currently mounted output; renderer-owned ids are not a
stable Lyra navigation contract. Use `page`/`goToSlide()` or a text-quote anchor instead.

**Methods:** `goToSlide(index)` returns a promise and navigates the mounted presentation using the
renderer's zero-based index. A current renderer rejection is contained, enters the localized error
state, emits `lr-render-error`, and does not escape as an unhandled promise rejection.
`renderPageThumbnailToContainer(page, container, options?)` renders a
one-based, width-bounded DOM/SVG slide preview and resolves to a caller-owned disposable handle (or
`false` when unavailable/invalid); it generation-checks asynchronous preview resources after they
settle.
`search(query)` searches the renderer's complete presentation model, not its windowed DOM, retains
at most 10,000 validated results, navigates the matching slide, and paints a renderer-owned node
overlay. Queries are capped at 4,096 code units and one result-validation pass at 4,000,000 code
units; a truncated pass reports `matchCountExact: false`. `searchNext()`, `searchPrevious()`, and `clearSearch()` navigate/dispose those model
results. `scrollToAnchor()` remains available for renderer output that exposes DOM text.

**Events:**

- `lr-load` — `detail: { slideCount }` — fired after a presentation opens.
- `lr-slide-change` — `detail: { index, count }` — fired when the active slide changes.
- `lr-page-viewer-state-change` — `detail.snapshot` is the same atomic readonly value exposed by
  `pageViewerSnapshot`: `{ identity, status, page, pageCount }`. `identity` changes at the start of
  every load so a rail can discard same-count replacement thumbnails without inferring identity
  from `src`.
- `lr-render-error` with `detail.error` when fetching/opening fails, public slide navigation rejects,
  or a post-load peer event is explicitly classified fatal.
- `lr-viewer-diagnostic` — `detail.diagnostic` is a readonly structured slide/node/search
  diagnostic with stable `code`, `severity`, `fatal`, `source`, `cause`, and correlated `page` or
  `nodeId` when valid. Recoverable events keep the mounted deck usable and do not also emit
  `lr-render-error`; fatal events enter the localized error state, destroy the adapter, and emit the
  terminal event once.
- `lr-search-change` — `detail: { query: string; matchCount: number; matchCountExact: boolean; activeIndex: number }` — fired
  whenever rendered-presentation search state changes, including canonical source reset and
  effective-locale re-evaluation.
- `lr-anchor-result` — `detail: { found: boolean }` — fired after an `anchor` assignment or
  `scrollToAnchor()` call is applied.
- `lr-text-select` — `detail: TextSelectDetail` (`{ text: string; anchor: LyraAnchor | null; rects:
DOMRect[] }`) — fired after a selection ends inside the rendered presentation.

`lr-highlight-activate` is not part of this viewer's event contract: painted renderer-text
highlights are passive and cannot be activated.

The three shared text-viewer events bubble and compose and are non-cancelable.

**CSS parts:** `base` (the named region with explicit `aria-busy="true"|"false"`), `header`, `name`,
`notice`, `error`, `nav`, `previous-button`, `previous-icon`, `slide-count`, `next-button`,
`next-icon`, `container`, and `anchor-live-region` (an aria-hidden, non-live shadow mirror of the
latest anchor-jump message; the spoken copy is appended to the shared document-level polite sink
only while the viewer and its composed ancestors are exposed to the accessibility tree). While
loading, the decorative skeleton is paired with an ordinary visually-hidden localized label; later
loading and error transitions use the shared document-level polite and assertive sinks,
respectively, without adding live semantics inside the viewer shadow. The previous/next chevrons
mirror under effective RTL direction, including inherited `dir` changes.

**Themeable custom properties:** `--lr-pptx-viewer-max-height` (default `none`) — maximum block
size of `[part="container"]` before it scrolls internally; also settable via the `max-height`
property, which writes this token inline.

**Optional peer dependency:** install `@aiden0z/pptx-renderer` with
`pnpm add @aiden0z/pptx-renderer`. The registry matches the official PPTX MIME type and `.pptx`
filenames, declaring `{ anchors: ['text-quote', 'fragment'], search: true, textSelect: true }`
capabilities and forwarding `anchor`/`highlights` to the mounted viewer. That forwarding preserves
the request across the registry hop; it does not create stable fragment ids in renderer output.

Importing `pptx-viewer.js` (this component's own registration entry) loads `<lr-pptx-viewer>`'s
class module immediately. A granular consumer (not importing the `all.js` compatibility bundle) who
wants that deferred too can instead import
`@aceshooting/lyra-ui/components/viewers/pptx-viewer/pptx-viewer-register.js`, which installs the
same registration lazily and exports `PPTX_VIEWER_TAG` (`'lr-pptx-viewer'`) as a stable reference to
the tag it eventually registers.

Remote resources are capped at 25 MB and measured ZIP expansion is capped at 256 MB before the
renderer opens the archive; exceeding either ceiling surfaces the localized
`documentPreviewResourceTooLarge` message instead of the presentation. The optional peer must also
expose its complete recommended ZIP-limits capability within Lyra's safety ceilings. Missing,
malformed, or more-permissive limits make the peer unavailable and the viewer fails closed.

The peer instance is immediately wrapped in a validated `PptxViewerAdapter`; the component observes
only readonly slide metadata, complete-model search/navigation/highlight/thumbnail capabilities and
normalized correlated events. Raw renderer DOM windowing and event payloads do not become component
state.
`PptxViewerAdapter`, `PptxViewerAdapterEvent`, `PptxTextSearchResult`, and
`PptxSearchHighlightHandle`/`PptxThumbnailHandle` are exported from the granular PPTX loader module.
The shared diagnostic
types are `LyraViewerDiagnostic`, `LyraViewerDiagnosticCode`, `LyraViewerDiagnosticSeverity`, and
`LyraViewerDiagnosticEventDetail`.

## `lr-svg-viewer`

Fetches an SVG document, sanitizes it with the optional `dompurify` peer, and renders it inline.
The shared `passive-svg` profile (the same post-sanitization engine used for embedded viewer markup)
removes author `<style>`/`style`, SVG animation elements, and external
resource or paint-server references before insertion, preventing fetched SVG content from escaping
the viewer's paint box or starting secondary requests. Local `url(#id)` paint servers and embedded
raster data remain available.

Fitting SVG content stays centered. In a capped nonzoomable viewer, overflowing content begins
inside the body's reachable scroll range, keeping both its top and bottom available.

Adopts `DocumentAnchorTarget` (the same shared mixin `lr-pdf-viewer`/`lr-csv-viewer` use): a `region`
anchor addresses one `highlights` entry, matched by reference or by structural equality of its `rect`
(and optional `page`). Assigning `anchor` or calling `scrollToAnchor()` scrolls the matching
`[part="region-highlight"]` into view and fires `lr-anchor-result`. No other anchor kind resolves
here — a sanitized SVG document has neither pages nor extractable text to quote, which is also why
its registry entry declares `capabilities: { anchors: ['region'], search: false, textSelect: false }`.

**Properties:** `src: string = ''`, `name: string = ''`, and `maxHeight: string = ''` (attribute
`max-height`). `maxHeight` caps the scrollable body; invalid CSS `max-height` values, declaration
breaks, and `url()` are ignored.
`zoomable: boolean = false` (reflected) — wraps the rendered content in an
internal `<lr-pan-zoom>`. `false` (the default) preserves the exact pre-`zoomable` DOM — an
inline thumbnail (e.g. in a chat stream) must not unexpectedly grow a focusable zoom-chrome viewport;
an inspection surface opts in. `anchor: LyraAnchor | string | null = null` (attribute: false) —
declaratively jump to an anchor (a `LyraAnchor` object, or a `highlights` entry's `id`). Assigning it
calls `scrollToAnchor()` and fires `lr-anchor-result`; re-assigning the same value re-triggers the
scroll, it is not reference-gated. `highlights: readonly LyraHighlight[] = []` (attribute: false) —
display-only `region` highlights painted over the rendered SVG; unchanged behavior, now inherited
from `DocumentAnchorTarget` rather than declared locally. A region rectangle renders/resolves only
when `x`/`y`/`width`/`height` are finite numbers and both dimensions are nonnegative.
`activeHighlightId: string | null = null`
(attribute `active-highlight-id`) — the `highlights` entry, if any, currently treated as active
(`data-active` on its `region-highlight`). `anchorKinds: readonly LyraAnchorKind[] = ['region']`
(this viewer's supported `LyraAnchor.kind` values for the shared anchor-target contract).

**Methods:** `scrollToAnchor(target): Promise<boolean>` — scrolls the `highlights` entry matching
`target` (a `region`-kind `LyraAnchor`, matched by reference or by structural equality of
`rect`/`page`; or a `highlights[].id` string) into view, honoring `prefers-reduced-motion`. Resolves
`true` when a match was found and scrolled, `false` otherwise, and always fires `lr-anchor-result`
carrying the same boolean. Called before the SVG has finished loading it retries for up to 5s (real
timers) rather than failing immediately.

**Events:** `lr-render-error` with `detail.error` when fetching or sanitizing fails.
`lr-highlight-activate` (`detail: { highlightId }`) — a region highlight was clicked or activated via
Enter/Space. `lr-anchor-result` (`detail: { found: boolean }`) — fired after an `anchor` assignment
or a `scrollToAnchor()` call is applied, whether or not a match was found. `lr-text-select` is not
part of this viewer's event contract because sanitized SVG has no extractable text-selection
contract (`textSelect: false` in its registry capabilities).

**CSS parts:** `base`, `body`, `svg`, `spinner` (ordinary loading content; later transitions use the
shared document-level polite sink), `error` (ordinary visible text; later transitions use the shared
document-level assertive sink), `anchor-live-region` (an aria-hidden, non-live shadow mirror of the
latest anchor-jump message; the spoken copy is appended to the shared document-level polite sink
only while the viewer and its composed ancestors are exposed to the accessibility tree),
`highlight-layer` (wrapper around every
rendered region highlight), `region-highlight` (one region highlight, `data-tone`, `data-active`),
`region-highlight-target` (transparent activation geometry with an independent minimum hit area),
`highlight-actions` (non-overlapping actions for multiple highlights), `region-highlight-action`
(one action in that list),
`frame-viewport`/`frame-content`/`frame-controls`/`frame-zoom-in`/`frame-zoom-out`/`frame-reset`
(forwarded from the internal `<lr-pan-zoom>` while `zoomable`).
Passive loaded SVG content owns `role="img"`. Idle, loading, and error states instead use a named
`region`, keeping their descendant state text in the accessibility tree; zoom controls or
interactive region highlights likewise use a region. The spinner always includes visible
localized loading text alongside its decorative ring, and the ring stops under reduced motion.

**Themeable custom properties:** `--lr-svg-viewer-max-height` (default `none`) — maximum block size
of `[part="body"]`; also settable via the `max-height` property, which writes this token inline.
`--lr-svg-viewer-active-border` (default `var(--lr-color-warning, var(--lr-color-brand))`) — the
border color of the `[part='region-highlight']` matching `activeHighlightId`, distinct from the
resting highlight border so the active region can be recolored without touching the rest. It is an
inline `var()` fallback at the point of use rather than a `:host` declaration, so it can be set on
the element _or on any ancestor_: `::part(region-highlight)[data-active]` is invalid CSS — Shadow
Parts forbids an attribute selector after `::part()` — so re-pointing a shared `--lr-color-*` token,
and repainting everything else reading it, was previously the only way. Unset, it falls back to
exactly the tokens the rule used before. The tone-specific resting border and hover tint use
`--lr-svg-viewer-highlight-accent-color`, `--lr-svg-viewer-highlight-success-color`,
`--lr-svg-viewer-highlight-warning-color`, `--lr-svg-viewer-highlight-danger-color`, and
`--lr-svg-viewer-highlight-neutral-color` (defaulting respectively to the matching
brand/success/warning/danger/neutral color tokens).

**Optional peer dependency:** `dompurify`.

Remote resources are capped at 25 MB; exceeding it surfaces the localized
`documentPreviewResourceTooLarge` message instead of the graphic.

## `lr-html-viewer`

Fetches an HTML document, sanitizes it with the optional `dompurify` peer, and renders the safe markup
inside a bounded, scrollable body.
Its passive-document profile is network-silent and non-interactive: links, form controls, and custom
elements are unwrapped to their ordinary text/children where safe; remote navigation and resource
attributes are removed. Images load only inline base64 GIF, JPEG, PNG, or WebP data, while
same-document SVG fragment references may remain; an `<a>` itself never remains in the rendered
preview.

**Properties:** `src: string = ''`, `name: string = ''`, and `maxHeight: string = ''` (attribute
`max-height`); invalid CSS
`max-height` values, declaration breaks, and `url()` are ignored. A nonempty host `aria-label`
makes the host the sole named semantic owner; an explicitly empty host label keeps the shadow
`document` role with an empty name, and an absent host label falls back to `name` or the localized
label. `highlights`, `activeHighlightId`, `anchor`, and
`anchorKinds` (`['text-quote', 'fragment']`) provide the shared text-viewer contract.

**Methods:** `search(query)`, `searchNext()`, `searchPrevious()`, `clearSearch()`, and
`scrollToAnchor()` operate on sanitized HTML text and emit the shared search/anchor events.

**Events:**

- `lr-render-error` with `detail.error` when fetching or sanitizing fails.
- `lr-search-change` — `detail: { query: string; matchCount: number; matchCountExact: boolean; activeIndex: number }` — fired
  whenever rendered-document search state changes.
- `lr-anchor-result` — `detail: { found: boolean }` — fired after an `anchor` assignment or
  `scrollToAnchor()` call is applied.
- `lr-text-select` — `detail: TextSelectDetail` (`{ text: string; anchor: LyraAnchor | null; rects:
DOMRect[] }`) — fired after a selection ends inside the rendered document.

`lr-highlight-activate` is not part of this viewer's event contract: painted sanitized-text
highlights are passive and cannot be activated.

The three shared text-viewer events bubble and compose and are non-cancelable.

**CSS parts:** `base`, `body`, `html`, `spinner`, `error`, and `anchor-live-region` (an aria-hidden,
non-live shadow mirror of the latest anchor-jump message; the spoken copy is appended to the shared
document-level polite sink only while the viewer and its composed ancestors are exposed to the
accessibility tree).

**Themeable custom properties:** `--lr-html-viewer-max-height` (default `none`) — maximum block size
of `[part="body"]`; also settable via the `max-height` property, which writes this token inline.

**Optional peer dependency:** `dompurify`. The registry matches `text/html` and `.htm`/`.html`
filenames, declaring `{ anchors: ['text-quote', 'fragment'], search: true, textSelect: true }`
capabilities and forwarding `anchor`/`highlights` onto the created element, so a deep link opened
through `<lr-document-viewer>` survives the registry hop.

Remote resources are capped at 25 MB; exceeding it surfaces the localized
`documentPreviewResourceTooLarge` message instead of the document.

## `lr-dataset-viewer`

Fetches tab-, pipe-, or delimiter-separated text and renders a virtualized, accessible table (a
`role="table"` container with a sticky `role="row"` header, composed with `<lr-virtual-list
item-role="row">` for the body) using the optional `papaparse` peer. The document registry matches
`.tsv`, `.psv`, and `.dat` filenames.

Adopts `DocumentAnchorTarget`: a `cell-range` anchor addresses the raw file grid, 1-based, with the
header row always occupying row 1 (this component always parses with a header row, so the first row
is never part of the virtualized body); `scrollToAnchor()` scrolls the addressed row into view via
the virtualized list's `active-item-id`. `highlights` paint as a `part="cell-highlight"` cell wrapping a
focusable `part="cell-highlight-action"` native button, keeping the ARIA table tree intact. A jump
whose document is replaced by a concurrent `src` reassignment mid-flight reports `found: false`
rather than a phantom success, and a header-row target scrolls with the same
`prefers-reduced-motion`-gated smooth behavior every other row uses.

**Properties:** `src: string = ''`, `name: string = ''`, `maxHeight: string = ''` (attribute
`max-height`), and `scrollMode: DatasetViewerScrollMode = 'self'` (attribute `scroll-mode`,
reflected). Invalid CSS `max-height` values, declaration breaks, and `url()` are ignored.
`scrollMode='self'` preserves contained horizontal scrolling and applies `maxHeight`.
`scrollMode='page'` removes intervening scroll containers and the height cap, so a populated table's
sticky header follows the page scrollport while rows continue below it. The border and rounded
header corners remain; a wide dataset can overflow its host in page mode.
Unsupported attribute and untyped property values normalize to `'self'`.
Host `aria-label` names the table by attribute presence, including an explicitly empty value;
`name` and the localized row-count caption are fallbacks. The same computed name (host `aria-label`,
else `name`) also names a persistent `role="region"` landmark on `[part='base']` in _every_ fetch
state — idle, loading, empty, error, loaded — so a landmark-navigating screen-reader user reaches the
viewer before it has any rows, not only after a successful non-empty load. With neither set,
`[part='base']` stays a plain wrapper rather than an unnamed region. The outer region carries the
plain display name while the inner `[part='table']` keeps the richer row-count caption; the two are
complementary, matching `lr-csv-viewer`/`lr-archive-viewer`'s base-vs-content split.
`anchorKinds: readonly LyraAnchorKind[] = ['cell-range']` (this viewer's supported `LyraAnchor.kind`
values for the shared anchor-target contract).

**Methods:** `search(query)` resolves the match count via a case-insensitive substring search over
every body cell's raw string value, ordered row then column (empty/whitespace query behaves like
`clearSearch()`); `searchNext()`/`searchPrevious()` advance/step back through matches (wrapping,
resolving `false` when there are none); `clearSearch()` clears the query, matches, and cursor.

**Events:** `lr-render-error` with `detail.error` when fetching or parsing fails. Up to 100
PapaParse diagnostics also emit this event when the recoverable partial table remains rendered, so
malformed or extra cells are never silently presented as a clean parse; exceeding that diagnostic
budget is a resource-limit error instead.
`lr-highlight-activate` (`detail: { highlightId }`) — a `highlights` cell was clicked or activated via
Enter/Space. `lr-anchor-result` (`detail: { found }`) — fired after an `anchor` assignment or a
`scrollToAnchor()` call. `lr-search-change` (`detail: { query, matchCount, matchCountExact, activeIndex }`) — from
search/navigation/clear, canonical source reset, and effective-locale re-evaluation. `lr-text-select` is not part of this
grid viewer's event contract; its registry capabilities advertise `textSelect: false`.

**CSS parts:** `base` (a persistent `role="region"` named by the host `aria-label` or `name`, in
every fetch state), `body`, `table`, `header-row`, `header-cell`, `data-row`, `cell`,
`cell-highlight` (a `role="cell"` covered by a `highlights` entry; wraps the action button),
`cell-highlight-action` (the native button filling a highlighted cell — focusable, emits
`lr-highlight-activate` on click or Enter/Space; its complete accessible name uses the localized
`cellHighlightWithLabel` message with independent `{value}` and `{label}` placeholders), `spinner`,
`error`, and `anchor-live-region` (an aria-hidden, non-live shadow mirror of the latest anchor-jump
message; the spoken copy is appended to the shared document-level polite sink only while the viewer
and its composed ancestors are exposed to the accessibility tree). `data-row`, `cell`,
`cell-highlight` and `cell-highlight-action` render inside the internal `<lr-virtual-list>` and are
forwarded via `exportparts`, so `lr-dataset-viewer::part(cell)` reaches them from a consumer
stylesheet.

**Exports:** `DatasetTable` is `{ fields: string[]; rows: Record<string, string>[] }`;
`DatasetViewerScrollMode` is `'self' | 'page'`.

**Themeable custom properties:** `--lr-dataset-viewer-max-height` (default `none`) — maximum block
size of `[part="body"]`; also settable via the `max-height` property, which writes this token inline.
Page scroll mode deliberately ignores this cap.
`--lr-dataset-viewer-highlight-color` (default `var(--lr-color-brand)`) — the outline color of a
`cell-highlight` cell. The cell matching `activeHighlightId` receives a private warning-color
default because a `[data-active]` selector can't be chained onto the `::part(cell-highlight)` the
cell reaches this component's stylesheet through. An inherited or direct public value remains
authoritative across that boundary.
`--lr-dataset-viewer-header-row-bg` (default `var(--lr-color-brand-quiet)`) — background of the
sticky header row, independent of the highlight outline above.

**Optional peer dependency:** `papaparse`.

Remote resources are capped at 25 MB. A quote-aware scan stops before PapaParse at 10,000 data rows,
1,000 fields in any row, 1,000,000 aggregate cells (including the header), or more than 100 parser
diagnostics; streaming record callbacks enforce the same ceilings again. Exceeding any ceiling
surfaces the localized `documentPreviewResourceTooLarge` message instead of a partial table.

## `lr-contact-viewer`

Fetches a vCard document and renders one accessible card per contact. The document registry matches
`.vcf` filenames and the `FN`, `ORG`, `TEL`, `EMAIL`, and `ADR` fields are displayed. `N` is parsed
but never rendered — the card's heading uses `FN` (falling back to a localized "unnamed contact"
label when `FN` is absent).

Remote resources are capped at 25 MB; exceeding it surfaces the localized
`documentPreviewResourceTooLarge` message instead of the contacts. Parsing retains at most 250
contacts and 2 MiB of rendered contact text, keeping the complete accepted model searchable and
text-quote anchorable without a 10,000-card eager DOM tree.

**Properties:** `src: string = ''`, `name: string = ''`,
`headingLevel: LyraHeadingLevel = '3'` (attribute `heading-level`, reflected) — `1`–`6` expose every
rendered contact name at that semantic level, invalid untyped values retain level 3, and `none`
keeps the names visual-only — and `maxHeight: string = ''` (attribute `max-height`); invalid CSS
`max-height` values, declaration breaks, and `url()` are ignored. A host `aria-label` takes
precedence over `name` by attribute presence, including an explicitly empty value. `highlights`,
`activeHighlightId`, `anchor`, and
`anchorKinds` (`['text-quote', 'fragment']`) provide the shared text-viewer contract. Fragment
resolution is an exact DOM `id` lookup, but generated contact cards define no fragment ids, so a
fragment jump reports `found: false`. Use a text-quote anchor for contact content.

**Methods:** `search(query)`, `searchNext()`, `searchPrevious()`, `clearSearch()`, and
`scrollToAnchor()` operate on rendered contact text and emit the shared search/anchor events.

**Events:**

- `lr-render-error` with `detail.error` when fetching or parsing fails.
- `lr-search-change` — `detail: { query: string; matchCount: number; matchCountExact: boolean; activeIndex: number }` — fired
  whenever rendered-contact search state changes.
- `lr-anchor-result` — `detail: { found: boolean }` — fired after an `anchor` assignment or
  `scrollToAnchor()` call is applied.
- `lr-text-select` — `detail: TextSelectDetail` (`{ text: string; anchor: LyraAnchor | null; rects:
DOMRect[] }`) — fired after a selection ends inside the rendered contacts.

`lr-highlight-activate` is not part of this viewer's event contract: painted contact-text
highlights are passive and cannot be activated.

The three shared text-viewer events bubble and compose and are non-cancelable.

**CSS parts:** `base`, `body`, `contact`, `contact-name`, `contact-org`, `contact-tel`,
`contact-email`, `contact-adr`, `spinner`, `error`, and `anchor-live-region` (an aria-hidden,
non-live shadow mirror of the latest anchor-jump message; the spoken copy is appended to the shared
document-level polite sink only while the viewer and its composed ancestors are exposed to the
accessibility tree).

**Themeable custom properties:** `--lr-contact-viewer-max-height` (default `none`) — maximum block
size of `[part="body"]`; also settable via the `max-height` property, which writes this token inline.

**Exports:** `parseVCards(text, maxContactsOrOptions?)` and the `ParseVCardsOptions`, `VCardName`,
`VCardTypedValue`, `VCardAddress`, and `VCardContact` types. The parser accepts vCard 2.1/3.0/4.0,
line folding, 2.1 bare types, quoted parameters and quoted-printable charset values. Its numeric
limit is floored and clamped to `0…250`; malformed framing/profiles/parameters fail closed, while an
actually empty document returns no contacts.

## `lr-pdf-viewer`

Fetches a PDF and renders its pages with the optional `pdfjs-dist` peer. Pages are virtualized through
`lr-virtual-list`, and PDF.js's selectable text layer is positioned over each rendered canvas.
The virtual list's raw `lr-visible-range-change` and `lr-virtual-scroll` events are internal and do
not escape the viewer; visible-range changes surface through the documented `lr-page-change` state.

Adopts `DocumentAnchorTarget`: `page`, `text-quote`, and `region` anchors resolve, and `highlights`
paint through one `<lr-highlight-layer>` per page, stacked between the canvas and the text layer
(canvas → highlights → text layer) so starting a text selection over a cited passage keeps working.
Pointer activation is hit-tested at the page-wrapper level (the text layer on top intercepts most
direct pointer events); keyboard activation reaches the highlight layer's own roving-tabindex rects
directly, since z-stacking doesn't affect tab order. Residual: a click that _ends a text-selection
drag_ over a highlighted passage never activates it — the selection-in-progress check exists exactly
to tell that apart from a genuine activation click.

**Properties:** `src: string = ''` and `name: string = ''`. `page: number = 1` is the one-based
current page and
`zoom: number = 1` is clamped to `0.25`–`4`. `maxHeight: string = ''` (attribute `max-height`) is a
CSS length that, once set, overrides `--lr-pdf-viewer-height` — the block size of the virtualized
page list — declaratively, writing it inline on `[part="base"]`; invalid CSS `max-height` values,
declaration breaks, and `url()` are ignored. `workerSrc: string = ''` (attribute `worker-src`) is the
URL of the PDF.js web worker chunk — see **Configuring the PDF.js worker** below.
`anchorKinds: readonly LyraAnchorKind[] = ['page',
'text-quote', 'region']` (this viewer's supported `LyraAnchor.kind` values for the shared
anchor-target contract). The other inherited anchor-target properties are `highlights:
LyraHighlight[] = []` (property only; reassign after mutation), `activeHighlightId: string | null =
null` (attribute `active-highlight-id`), and `anchor: LyraAnchor | string | null = null` (property
only). Page and page-addressed region anchors require an in-range integer page
and are rejected rather than clamped; region rectangles also require finite coordinates and
nonnegative dimensions.

**Events:**

- `lr-render-error` — `detail: { error }` — fetching, parsing, or rendering (page canvas or text
  layer) failed. Both synchronous and rejected text-layer failures are contained and reported
  without an unhandled promise rejection.
- `lr-load` — `detail: { pageCount }` — the document reached `ready`. `page` is reset to `1` first.
- `lr-page-change` — `detail: { page, pageCount }` — fired for scroll-driven page crossings as well
  as `page` assignments and `nextPage()`/`previousPage()`/`goToPage()`.
- `lr-zoom-change` — `detail: { zoom }` — fired for `zoom` assignments as well as
  `zoomIn()`/`zoomOut()`. Never fired for the initial `1`, only for a transition away from it.
- `lr-search-change` — `detail: { query, matchCount, matchCountExact, activeIndex }` — from `search()`/`searchNext()`/
  `searchPrevious()`/`clearSearch()` and effective-locale re-evaluation. A `src` change invalidates document-relative matches and emits
  the canonical reset `{ query: '', matchCount: 0, matchCountExact: true, activeIndex: -1 }`.
- `lr-highlight-activate` — `detail: { highlightId }` — a painted highlight was clicked or activated via
  Enter/Space. On a pointer hit-test, the last entry of `highlights` covering the point wins.
- `lr-text-select` — `detail: { text, anchor, rects }` — a selection ended inside a page's text
  layer. `anchor` is the computed anchor (`null` when none resolves), carrying the resolved `page`
  when it is a `text-quote`.
- `lr-anchor-result` — `detail: { found }` — fired after an `anchor` assignment or a
  `scrollToAnchor()` call.
- `lr-page-viewer-state-change` — `detail.snapshot` is the same immutable atomic state exposed by
  `pageViewerSnapshot` (`identity`, `status`, `page`, `pageCount`). `identity` changes for every load,
  including same-count replacements.

**`lr-page-change`/`lr-zoom-change` are state broadcasts, not user-intent signals.** This differs
deliberately from the same-named `<lr-pagination>` event and from `<lr-pan-zoom>`'s `lr-zoom-change`,
and the distinction is worth internalizing before wiring a handler. Pagination and pan-zoom are
*controlled*: pagination never mutates its own `page`, so its event is a request the host applies,
and pan-zoom's `zoom` is bound by a parent, so echoing a programmatic write back would feed a loop.
This viewer instead *owns* `page` and `zoom` — scrolling the page list changes `page` with no
consumer action at all — so there is no useful "the user did this" subset to isolate, and every
accepted transition is announced identically: scrolling, `nextPage()`/`previousPage()`/`goToPage()`,
`zoomIn()`/`zoomOut()`, anchor resolution, the reset to page 1 when a new `src` finishes loading,
and a plain `viewer.page = 3` / `viewer.zoom = 2` assignment. A handler that mirrors the event back
into the property it came from is therefore idempotent rather than looping, but it is also
redundant — read the property, or `pageViewerSnapshot`, instead.

A write that clamps or rounds back onto the value already in effect is not a transition and stays
silent: on a 3-page document already showing page 1, `viewer.page = -7` and `viewer.page = 1.4` both
settle on page 1 and emit nothing, and `viewer.zoom = 999` at 4× emits nothing.

For page-addressed integrations prefer the atomic `pageViewerSnapshot` /
`lr-page-viewer-state-change` channel over this pair: it carries page, count, load status and
document `identity` together, and a late subscriber can read the current value synchronously instead
of having missed the announcement. `<lr-page-rail>` binds that channel for any viewer exposing
`pageViewerSnapshot` — including this one — and falls back to `lr-load`/`lr-page-change` only for
older structural sources that do not.

**Methods:** `nextPage()`, `previousPage()`, `zoomIn()`, and `zoomOut()` update the corresponding
controlled state within its supported range. `getPageText(page)` resolves the raw reading-order text
of one page (per-page LRU-cached, 64 pages), rejecting on no loaded document or an out-of-range page.
`pageViewerSnapshot` is a synchronously readable readonly lifecycle/page/count snapshot for page
rails and other late subscribers. `renderPageThumbnail(page, canvas, options?)` renders `page` into a caller-owned `canvas` at
`options.width` CSS px (default 96), devicePixelRatio-aware, resolving `false` when not ready or out
of range. `goToPage(page)` scrolls the virtualized list to `page`, resolving `true` once mounted (or
`false` for an out-of-range value, without changing `page`). `getOutline()` resolves the document's
table of contents as `PdfOutlineItem[]` (`{ title, page?, children? }`), `[]` when there is none;
peer output is capped at 10,000 unique items and 100 levels, with cycles ignored.
`search(query)` resolves the match count across all pages (empty/whitespace query behaves like
`clearSearch()`), accepting at most 4,096 query code units and scanning at most 1,000 pages,
1,000,000 corpus code units, and 4,000,000 search code units while retaining 10,000 matches;
`searchNext()` and `searchPrevious()` advance/step back through matches (wrapping,
resolving `false` when there are none); `clearSearch()` clears the query, matches, and painted marks.

**CSS parts:** `base` (the named region with explicit `aria-busy="true"|"false"`), `toolbar`,
`previous-button`, `next-button`, `zoom-out-button`,
`zoom-in-button` (the four toolbar controls — previously reachable only through `::part(toolbar)
button`, which is invalid: a descendant combinator after `::part()` never matches, so each button now
carries its own part name), `page-indicator`, `zoom-indicator`, `pages`, `page`, `page-canvas`
(the canvas one page's content is painted onto), `text-layer`, `text-span` (one generated text run
inside a page's text layer — PDF.js creates these imperatively, and they carry the part so a rule can
reach them without a descendant combinator), `search-match` (a `<mark>` painted into a mounted page's
text layer around one search match), `search-match-active` (the currently active match, also carries
`search-match`), `page-error`, `page-error-visible`, `spinner`, `error`, and `anchor-live-region` (an
aria-hidden, non-live shadow mirror of the latest anchor-jump message; the spoken copy is appended
to the shared document-level polite sink only while the viewer and its composed ancestors are
exposed to the accessibility tree). Search painting is best-effort: a page outside the virtualized
render window is skipped and repainted once its text layer mounts, and a match spanning a text-layer
span boundary that `Range.surroundContents()` can't wrap stays unpainted (still reachable via
`searchNext()`). The loading skeleton is decorative and paired with an ordinary visually-hidden
localized label; later loading and error transitions use the shared document-level polite and
assertive sinks, respectively, without adding live semantics inside the viewer shadow.

**Known capability boundaries** — deliberate, not defects, and stated here so they need not be
rediscovered: text search and `LyraAnchor` text-quote resolution match **exact** text only, after
whitespace and soft-hyphen normalization, with no fuzzy or approximate mode. Non-Latin
cMap-encoded fonts get no special handling beyond whatever the `pdfjs-dist` peer resolves on its
own — no `cMapUrl`/`cMapPacked` is configured. A scanned or image-only PDF has no text layer at
all, so it has nothing to select, search or anchor into; it still renders and paginates normally.

`page`, `page-canvas`, `text-layer`, `text-span`, `search-match` and `search-match-active` are
rendered inside the virtualizing `lr-virtual-list`'s own shadow root and forwarded out through
`exportparts`, so `lr-pdf-viewer::part(page)` (and each of the others) works from a consumer
stylesheet exactly like the parts in this viewer's own shadow root. The selection tint over a page's
text is styled on `text-span` rather than on `text-layer`, because a highlight pseudo-element is
matched against the element the selected text originates in:
`lr-pdf-viewer::part(text-span)::selection { background: … }`.

**Themeable custom properties:** `--lr-pdf-viewer-height` (default `var(--lr-size-24rem)`) — block
size of the virtualized page list (`[part="pages"]`); also settable via the `maxHeight` property,
which writes this token inline on `[part="base"]`. `--lr-pdf-viewer-toolbar-bg` (default
`var(--lr-color-brand-quiet)`) — background of the `toolbar` part, independent of the shared
`--lr-color-brand-quiet` token. `--lr-pdf-viewer-toolbar-button-hover-bg`
(default `var(--lr-color-surface)`) — hover fill of the toolbar buttons; it defaults to the surface
fill rather than the toolbar's own `--lr-color-brand-quiet` tint precisely so the hover state is
visible against the toolbar behind it. `--lr-pdf-viewer-text-selection-bg` (default
`var(--lr-color-brand-quiet)`) — background of a native text selection over a `text-span`,
independent of the shared `--lr-color-brand-quiet` token. `--lr-pdf-viewer-search-match-bg` (default
`var(--lr-color-warning-quiet)`) and `--lr-pdf-viewer-search-match-active-bg` (default
`var(--lr-color-warning)`) retint the painted `search-match`/`search-match-active` marks without
overriding the shared warning tokens directly. Everything else below the page list is retuned
through the exported parts above rather than through dedicated custom properties.

**Optional peer dependency:** install `pdfjs-dist` with `pnpm add pdfjs-dist`. The component registers
a lazy `application/pdf` renderer with `<lr-document-viewer>` so the PDF library is loaded only when
a PDF is opened. An absent `pdfjs-dist` fails closed and renders
`[part="error"]` with the localized `pdfViewerMissingLibrary` message — there is no partial PDF
rendering without it.

Importing `pdf-viewer.js` (this component's own registration entry) loads `<lr-pdf-viewer>`'s class
module immediately, before any PDF is ever opened — `pdfjs-dist` itself is the only thing that
entry actually defers. A granular consumer (not importing the `all.js` compatibility bundle) who
wants the class module deferred too can instead import
`@aceshooting/lyra-ui/components/viewers/pdf-viewer/pdf-viewer-register.js`, which installs the same
`application/pdf` registration without pulling in `<lr-pdf-viewer>`'s class module until a matching
file is actually opened, and exports `PDF_VIEWER_TAG` (`'lr-pdf-viewer'`) as a stable reference to
the tag it eventually registers.

**Configuring the PDF.js worker.** PDF.js renders in a web worker and rejects every document with
`No "GlobalWorkerOptions.workerSrc" specified.` until it has been told where that worker lives. The
worker is a separate file inside the peer (`pdfjs-dist/build/pdf.worker.min.mjs`) that only the
application's own bundler can turn into a real URL — a bare package specifier does not resolve in a
browser without an import map, and resolving it against this library's own module URL would point
into `@aceshooting/lyra-ui`'s files, where no worker exists. So a bundled application supplies it,
either way round:

```ts
// 1. Per element, through the public property/attribute.
import workerUrl from 'pdfjs-dist/build/pdf.worker.min.mjs?worker&url'; // Vite; see your bundler
const viewer = document.querySelector('lr-pdf-viewer');
viewer.workerSrc = workerUrl;
// or, declaratively: <lr-pdf-viewer worker-src="/assets/pdf.worker.min.mjs"></lr-pdf-viewer>

// 2. Once for the whole application, on PDF.js's own singleton, before any viewer loads a document.
import { GlobalWorkerOptions } from 'pdfjs-dist';
GlobalWorkerOptions.workerSrc = workerUrl;
```

`workerSrc` accepts a document-relative URL (resolved against the document base) as well as an
absolute one; only `http:`, `https:`, `blob:` and `file:` URLs are accepted, and anything else — a
`javascript:` or `data:` URL in particular — is ignored rather than handed to `new Worker()`.

`GlobalWorkerOptions` is PDF.js's process-wide singleton and the PDF.js module itself is loaded once
per page, so `workerSrc` is applied only while that singleton is still unset. Two consequences worth
knowing before reaching for the per-element form: a worker the application configured itself is never
overwritten, and when several viewers carry different `workerSrc` values only the first one to load
PDF.js takes effect for the whole page. Assigning `workerSrc` after PDF.js has already loaded is not
silently dropped — it is re-applied on the next load — but it still cannot displace an
already-configured worker. Option 2 above is the right choice for an application that wants one
explicit worker everywhere.

Remote resources are capped at 25 MB; exceeding it surfaces the localized
`documentPreviewResourceTooLarge` message instead of the PDF.

Anchor navigation is generation-guarded: a newer anchor, document replacement, or disconnect
prevents stale page/text/region work from scrolling or reporting success.

## `lr-spreadsheet-viewer`

Fetches and renders `.xlsx` and `.xls` workbooks with the optional `xlsx` (SheetJS) peer. Multiple
worksheets render through a `<lr-tab-group>` switcher, and body rows use `<lr-virtual-list>`.

Adopts `DocumentAnchorTarget`: a `cell-range` anchor addresses one sheet's raw grid, 1-based, with
its header row included, resolving the target sheet from the anchor's own `sheet` field (falling
back to a `Sheet!`-prefixed `range`, then the active sheet); `scrollToAnchor()` switches
`<lr-tab-group>`'s active tab first when needed, then scrolls the addressed row/column into view.
`highlights` paint as a focusable `part="cell-highlight"`. A jump whose workbook is replaced by a
concurrent `src` reassignment mid-flight reports `found: false` rather than a phantom success —
matching `lr-csv-viewer`/`lr-dataset-viewer` (it wrongly reported `found: true` before 9.0.0).

**Properties:** `src: string = ''` and `name: string = ''`. `maxHeight: string = ''` (attribute
`max-height`) is a CSS length that caps the scrollable body — setting it writes
`--lr-spreadsheet-viewer-max-height` inline on `[part="base"]`; invalid CSS `max-height` values are
ignored. `anchorKinds: readonly LyraAnchorKind[] = ['cell-range']` (this viewer's supported
`LyraAnchor.kind` values for the shared anchor-target contract).

**Methods:** `search(query)` resolves the match count across every sheet's stringified cell values,
ordered sheet then row then column, switching tabs as navigation crosses sheets (empty/whitespace
query behaves like `clearSearch()`); `searchNext()`/`searchPrevious()` advance/step back through
matches (wrapping, resolving `false` when there are none); `clearSearch()` clears the query,
matches, and painted marks.

**Events:** `lr-render-error` with `detail.error` when fetching or parsing fails.
`lr-highlight-activate` (`detail: { highlightId }`) — a `highlights` cell was clicked or activated via
Enter/Space. `lr-anchor-result` (`detail: { found }`) — fired after an `anchor` assignment or a
`scrollToAnchor()` call. `lr-search-change` (`detail: { query, matchCount, matchCountExact, activeIndex }`) — from
search/navigation/clear, canonical source reset, and effective-locale re-evaluation. `lr-text-select` is not part of this
grid viewer's event contract; its registry capabilities advertise `textSelect: false`.

**CSS parts:** `base`, `body` (the scrollable wrapper around the fetched-state content, capped by
`max-height`), `tabs`, `sheet`, `header-row`, `data-row`, `cell`, `cell-highlight` (a
structural cell covered by a `highlights` entry), `cell-highlight-action` (the native button
filling a highlighted cell; focusable and emits `lr-highlight-activate`; its complete accessible
name uses the localized `cellHighlightWithLabel` message with independent `{value}` and `{label}`
placeholders), `rows`, `spinner`, `error`, and `anchor-live-region` (an aria-hidden, non-live shadow
mirror of the latest anchor-jump message; the spoken copy is appended to the shared document-level
polite sink only while the viewer and its composed ancestors are exposed to the accessibility tree).
`data-row`, `cell`, `cell-highlight`, and `cell-highlight-action` are rendered inside the internal
`<lr-virtual-list>` and forwarded via
`exportparts`, so `lr-spreadsheet-viewer::part(cell)` reaches them from a consumer stylesheet.
The spinner always includes visible localized loading text alongside its decorative ring; the text
remains understandable without CSS or animation and the ring stops under reduced motion.

**Themeable custom properties:** `--lr-spreadsheet-viewer-highlight-color` (default
`var(--lr-color-brand)`) — the outline color of a `cell-highlight` cell. The cell matching
`activeHighlightId` receives a private warning-color default because a `[data-active]` selector
can't be chained onto the `::part(cell-highlight)` the cell reaches this component's stylesheet
through. An inherited or direct public value remains authoritative across that boundary.
`--lr-spreadsheet-viewer-highlight-outline-offset` (default
`calc(-1 * var(--lr-border-width-medium))`) — the outline offset of a highlighted cell.
`--lr-spreadsheet-viewer-max-height` (default `none`) — maximum block size of `[part="body"]`
before it scrolls internally; also settable via the `maxHeight` property, which writes this token
inline on `[part="base"]`.

**Optional peer dependency:** install `xlsx` with `pnpm add https://cdn.sheetjs.com/xlsx-0.20.3/xlsx-0.20.3.tgz`. The official CDN matches the
`.xlsx` and `.xls` MIME types and filename extensions.

Importing `spreadsheet-viewer.js` (this component's own registration entry) loads
`<lr-spreadsheet-viewer>`'s class module immediately. A granular consumer (not importing the
`all.js` compatibility bundle) who wants that deferred too can instead import
`@aceshooting/lyra-ui/components/viewers/spreadsheet-viewer/spreadsheet-viewer-register.js`, which
installs the same registration lazily and exports `SPREADSHEET_VIEWER_TAG`
(`'lr-spreadsheet-viewer'`) as a stable reference to the tag it eventually registers.

Remote resources are capped at 25 MB, each parsed sheet at 10,000 rows and 1,000 columns, and each
workbook at 256 sheets and 1,000,000 aggregate expanded cells. Row limits are per sheet, not
cumulative across a workbook. Exceeding any ceiling surfaces the localized
`documentPreviewResourceTooLarge` message instead of the workbook.

## `lr-csv-viewer`

Fetches CSV text, parses quoted fields with the optional `papaparse` peer, and virtualizes body rows.

Adopts `DocumentAnchorTarget`: a `cell-range` anchor addresses the raw file grid, 1-based, with the
header row included whenever `has-header-row` is set; `scrollToAnchor()` scrolls the addressed
row/column into view via the virtualized list's `active-item-id`. `highlights` paint as a focusable
`part="cell-highlight"`. A jump whose document is replaced by a concurrent `src` reassignment
mid-flight reports `found: false` rather than a phantom success.

**Properties:** `src: string = ''` and `name: string = ''`. `hasHeaderRow: boolean = true` (attribute
`has-header-row`) controls whether the first parsed row is rendered as a persistent header above
the virtualized row scrollport.
Host `aria-label` names both the viewer region and loaded table by attribute presence, including an
explicitly empty value; `name` and the localized label are fallbacks.
`maxHeight: string = ''` (attribute `max-height`) is a CSS length that caps the body allocation —
setting it writes `--lr-csv-viewer-max-height` inline on `[part="base"]`; invalid CSS `max-height`
values, declaration breaks, and `url()` are ignored. `anchorKinds: readonly LyraAnchorKind[] =
['cell-range']` (this viewer's supported `LyraAnchor.kind` values for the shared anchor-target
contract).

**Methods:** `search(query)` resolves the match count via a case-insensitive substring match over
the same stringified cell values `cell()` renders, ordered row then column (empty/whitespace query
behaves like `clearSearch()`); `searchNext()`/`searchPrevious()` advance/step back through matches
(wrapping, resolving `false` when there are none); `clearSearch()` clears the query, matches, and
painted marks.

**Events:** `lr-render-error` with `detail.error` when fetching or parsing reports an error. Up to
100 recoverable PapaParse diagnostics may accompany the rendered grid; exceeding that budget is a
resource-limit error instead.
`lr-highlight-activate` (`detail: { highlightId }`) — a `highlights` cell was clicked or activated via
Enter/Space. `lr-anchor-result` (`detail: { found }`) — fired after an `anchor` assignment or a
`scrollToAnchor()` call. `lr-search-change` (`detail: { query, matchCount, matchCountExact, activeIndex }`) — from
search/navigation/clear, canonical source reset, and effective-locale re-evaluation. `lr-text-select` is not part of this
grid viewer's event contract; its registry capabilities advertise `textSelect: false`.

**CSS parts:** `base`, `body` (the capped content allocation), `sheet` (the named `role="table"`),
`header-row` (persistent above the nested virtual-list row scrollport), `data-row`, `cell`, `cell-highlight` (a structural
cell covered by a `highlights` entry), `cell-highlight-action` (the native button filling a
highlighted cell; emits `lr-highlight-activate`; its complete accessible name uses the localized
`cellHighlightWithLabel` message with independent `{value}` and `{label}` placeholders; this action,
not the structural `cell-highlight`, owns keyboard focus and its focus ring), `rows`,
`spinner`, `error`, and `anchor-live-region` (an aria-hidden, non-live shadow mirror of the latest
anchor-jump message; the spoken copy is appended to the shared document-level polite sink only while
the viewer and its composed ancestors are exposed to the accessibility tree). `data-row`,
`cell`, `cell-highlight`, and `cell-highlight-action` are rendered inside the internal
`<lr-virtual-list>` and forwarded via `exportparts`, so
`lr-csv-viewer::part(cell)` reaches them from a consumer stylesheet.

**Themeable custom properties:** `--lr-csv-viewer-max-height` (default `none`) — maximum block size
allocated to `[part="body"]`; the nested virtual-list scrolls data rows in the remainder below the
header. It is also settable via the `maxHeight` property, which writes this token inline on
`[part="base"]`. `--lr-csv-viewer-highlight-color` (default
`var(--lr-color-brand)`) — the outline color of a `cell-highlight` cell. The cell matching
`activeHighlightId` receives a private warning-color default because a `[data-active]` selector
can't be chained onto the `::part(cell-highlight)` the cell reaches this component's stylesheet
through. An inherited or direct public value remains authoritative across that boundary.

**Optional peer dependency:** install `papaparse` with `pnpm add papaparse`. The registry matches
`text/csv` and `.csv` filenames.

Importing `csv-viewer.js` (this component's own registration entry) loads `<lr-csv-viewer>`'s class
module immediately. A granular consumer (not importing the `all.js` compatibility bundle) who wants
that deferred too can instead import
`@aceshooting/lyra-ui/components/viewers/csv-viewer/csv-viewer-register.js`, which installs the
same registration lazily and exports `CSV_VIEWER_TAG` (`'lr-csv-viewer'`) as a stable reference to
the tag it eventually registers.

Remote resources are capped at 25 MB. A quote-aware scan stops before PapaParse at 10,000 raw rows
(the first row consumes the same budget whether or not `has-header-row` displays it as a header),
1,000 columns in any row, 1,000,000 aggregate cells, or more than 100 parser diagnostics; streaming
row callbacks enforce the same ceilings again. Exceeding any ceiling surfaces the localized
`documentPreviewResourceTooLarge` message instead of a partial grid.

---

## `lr-include`

Loads an HTML fragment from `src` and transcludes it as sanitized **light-DOM** content, so the
fragment participates in the surrounding page's CSS cascade like a native server-side include —
unlike `<lr-html-viewer>`, which renders a foreign document inside an isolated preview card. The
markup always passes through the shared DOMPurify-backed sanitizer before it reaches `innerHTML`;
there is deliberately no `allow-scripts`-style escape hatch (the Web Awesome/Shoelace equivalents'
raw injection option is omitted, not shipped as a no-op).
The post-sanitization transclusion profile is network-silent and non-interactive: anchors are
retained, but only resolvable same-document `#fragment` links survive and those ids are rebased per
include instance. Other navigation and resource attributes such as `href`, `src`, `srcset`,
`action`, `ping`, and `poster` are removed, so images never load. Form controls and custom elements
cannot remain interactive; their wrappers are unwrapped when their ordinary children are safe,
while elements such as inputs that have no passive content are removed.

The same passive restrictions apply through nested template contents before a remote document is
retained in the cache or a selected fragment becomes live. Template text and fragment selection
remain supported at nested depths, including ordinary elements inside templates; permitted local
anchors still resolve against per-instance rebased IDs.

A bare primitive: no label/hint/error chrome, no implicit role, no computed accessible name, and no
`aria-live` wrapper (the fragment can carry its own landmarks; wrapping the host would re-announce
all of it on every load). The host always carries explicit `aria-busy="true"|"false"`: true while
the source is loading and being sanitized. Build error UI from `lr-include-error`.

**Properties:**

- `src: string = ''` (reflected) — source of the fragment. `#id` clones the matching same-page
  template content or element children without fetching or moving the source nodes.
  `/partial.html#id` fetches `/partial.html` without its hash, sanitizes the complete response, then
  clones the target's children; a URL without a hash transcludes the complete sanitized document.
  Remote URLs pass the shared `safeFetchUrl()` allowlist (`http:`, `https:`, `blob:`, `data:`).
  Empty/falsy is a no-op: no fetch, no events, existing content untouched.
- `mode: 'cors' | 'no-cors' | 'same-origin' = 'same-origin'` (reflected) — forwarded to
  `fetch(url, { mode })`. Defaults to `same-origin` (not the upstream components' `cors`) so
  cross-origin fetching is opt-in; an invalid value is normalized back to `same-origin` rather than
  letting `fetch()` throw. `no-cors` is accepted for enum completeness but always yields an opaque
  response (`status` `0`, unreadable body) — a Fetch API limitation, not a bug here.
- `cache: boolean = true` (attribute is not reflected) — shares matching in-flight work and retains
  successful sanitized remote documents in a bounded cache. `cache="false"` (including that exact
  HTML attribute syntax) opts this instance out of both deduplication and retention. Fragment ids
  are deliberately not part of the key: `/partial.html#one` and `/partial.html#two` share only the
  fragmentless fetch/sanitize work, then select and clone independently. Request mode, byte cap,
  and sanitizer profile are part of the key.

**Methods:** `reload(): Promise<void>` invalidates the retained remote document for this URL and
mode, then loads it again. A same-page source is simply re-cloned from its current DOM.

The shared text-viewer contract is also available for the sanitized light-DOM fragment:
`highlights`, `activeHighlightId`, `anchor`, and `anchorKinds` (`['text-quote', 'fragment']`).
`search(query)`, `searchNext()`, `searchPrevious()`, `clearSearch()`, and `scrollToAnchor()`
operate on the included text. A successful replacement explicitly recomputes any active search
against the new fragment rather than leaving results from the previous content.

**Events:**

- `lr-load` — `detail: { src }` — the fragment was sanitized and written into the light DOM.
- `lr-include-error` — `detail: { status, reason, error? }`. `reason` is a `LyraIncludeErrorReason`:
  `'blocked-url'` (`src` failed the allowlist; `fetch()` never ran), `'network'` (`fetch()` rejected),
  `'http'` (response not `ok`; `status` carries the code), `'missing-sanitizer'` (the optional
  `dompurify` peer failed to load), `'resource-too-large'` (the body exceeded the 2 MiB Include
  cap), or `'missing-fragment'` (the requested id was absent after sanitization). Non-HTTP reasons
  use status `0`; `'http'` normally carries the response code, but an opaque `mode="no-cors"`
  response is also classified as `'http'` with status `0`.
- `lr-error` — the same failure under a second name, carrying the **identical detail object** and
  always fired alongside `lr-include-error`, never instead of it. The two upstreams disagree on the
  spelling — Web Awesome's is `wa-include-error`, Shoelace's is `sl-error` — so both are supported
  and **neither is deprecated**; listen to whichever one your migration produced. `lr-error` is
  also the name every other Lyra component uses for a load failure, so a generic page-level
  listener catches this one too. Listening to both names on the same element runs your handler
  twice for one failure.
- `lr-search-change` — `detail: { query: string; matchCount: number; matchCountExact: boolean; activeIndex: number }` — fired
  whenever included-content search state changes.
- `lr-anchor-result` — `detail: { found: boolean }` — fired after an `anchor` assignment or
  `scrollToAnchor()` call is applied.
- `lr-text-select` — `detail: TextSelectDetail` (`{ text: string; anchor: LyraAnchor | null; rects:
DOMRect[] }`) — fired after a selection ends inside the included content.

`lr-highlight-activate` is not part of this component's event contract: included-text highlights
are passive and cannot be activated.

The three shared text-viewer events bubble and compose and are non-cancelable.

**Slots:** default — fallback content shown until (or unless) a fetch succeeds. It is overwritten by
the sanitized fragment on success, and left untouched on failure (as is any previously successful
include).

**CSS parts:** `base` (the `display: contents` wrapper around the default slot), and
`anchor-live-region` (an aria-hidden, non-live shadow mirror of the latest anchor-jump message; the
spoken copy is appended to the shared document-level polite sink only while the viewer and its
composed ancestors are exposed to the accessibility tree).

An absent `dompurify` fails closed: it fires `lr-include-error` with
`reason: 'missing-sanitizer'` and leaves the existing content in place — unsanitized markup is
never transcluded.

Every inserted subtree is a clone. Its ids are rebased per Include instance, including references
from labels, ARIA idrefs, fragment links, and `url(#id)` attributes, so repeating one source does
not add duplicate document ids. Concurrent consumers lease shared work: disconnecting one aborts
the request only when no other subscriber still needs it. Rejected work is evicted and can be
retried; a stale response never paints over a newer `src`.

```html
<lr-include id="navigation" src="/partials/navigation.html#primary">
  Loading navigation…
</lr-include>
<script type="module">
  import "@aceshooting/lyra-ui/components/viewers/include/include.js";

  const include = document.querySelector("#navigation");
  include.addEventListener("lr-include-error", (event) => {
    console.error(event.detail.reason, event.detail.status);
  });
  await include.reload();
</script>
```

## `lr-highlight-layer`

A presentational overlay that paints highlight rectangles (percent-of-box coordinates) over
positioned content and owns their activation, active/flash styling, and keyboard access. `items`
order is the caller's own reading order; the layer does not re-sort geometrically. Fills its nearest
positioned ancestor.

**Properties:** `items: HighlightLayerItem[] = []` (attribute: false), with IDs trimmed and required
to be nonempty and the first item retained when IDs repeat; `activeHighlightId: string | null = null`
(attribute `active-highlight-id`), and `interactive: boolean = true` (reflected) — gates click/keyboard
activation. A rectangle is eligible only when `x`/`y`/`width`/`height` are finite numbers and both
dimensions are nonnegative; an item with a missing/non-array `rects` collection and each invalid
rectangle are omitted from paint, focus, and activation. When
`interactive=false`, the base is `aria-hidden` pure paint with no group role, accessible name, or
controls. If every rectangle is invalid, no shadow subtree is rendered.

**Methods:** `flash(id)` briefly re-triggers the flash styling for an already-rendered rect (e.g. a
re-click of the same source citation).

**Events:** `lr-highlight-activate` — a rect was activated (click, or Enter/Space while focused).
`detail: { highlightId }`.

**CSS parts:** `base` (the absolutely-positioned overlay, inset 0), `rect` (one visual highlight
rectangle; carries `data-tone`/`data-active`/`data-flash` state attributes), and `rect-target`
(transparent activation geometry with a minimum pointer/focus area independent of the visual
rectangle). When more than one logical highlight would create overlapping minimum hit areas, the
individual targets are replaced by `highlight-actions` (a non-overlapping action list) containing
one `highlight-action` button per rendered highlight.

**Themeable custom properties:**
`--lr-highlight-layer-accent-background`, `--lr-highlight-layer-accent-outline`,
`--lr-highlight-layer-success-background`, `--lr-highlight-layer-success-outline`,
`--lr-highlight-layer-warning-background`, `--lr-highlight-layer-warning-outline`,
`--lr-highlight-layer-danger-background`, `--lr-highlight-layer-danger-outline`,
`--lr-highlight-layer-neutral-background`, and `--lr-highlight-layer-neutral-outline` control each
tone independently, defaulting to the corresponding Lyra quiet background and foreground tokens.
`--lr-highlight-layer-flash-background` controls the temporary flash state (default
`--lr-color-brand`).

## `lr-page-rail`

A virtualized vertical thumbnail rail for page-addressed documents, with per-page highlight heat
markers. Two modes: **wired** (`viewer`/`for` supply a live page source, e.g. `<lr-pdf-viewer>` or
`<lr-pptx-viewer>` —
thumbnails render lazily as rows materialize, and the rail tracks page/count from the viewer's own
events) and **mediated** (`page-count`/`page` are host-bound directly, rows render a placeholder
glyph — still a fully functional pager). In wired mode the viewer's `page` is the single source of
truth.

**Properties:** `viewer: PageThumbnailSource | null = null` (attribute: false) — the wired viewer.
`for: string = ''` — an id selector alternative to setting `viewer` directly. `pageCount: number = 0`
(attribute `page-count`) and `page: number = 1` (reflected) — mediated-mode page state.
`highlights: readonly LyraHighlight[] = []` (attribute: false) — drives the per-page heat markers;
IDs are trimmed and required to be nonempty, with the first record retained when IDs repeat.
`thumbWidth: number = 96` (attribute `thumb-width`) and `label: string = ''`. A wired
`PageThumbnailSource` provides its one-based `page`, optionally exposes the atomic
`pageViewerSnapshot`/`lr-page-viewer-state-change` protocol, and supplies at least one lazy preview
method: the original `renderPageThumbnail(page, canvas, options?)` for bitmap/canvas sources, or
`renderPageThumbnailToContainer(page, container, options?)` for renderer-owned DOM/SVG previews.
The latter resolves to a `PageThumbnailRenderHandle`; the rail disposes it whenever its row,
viewer, allocation width, status, or document identity changes.

**Events:** `lr-page-select` — a page row was activated (click, or Enter/Space on a focused row).
`detail: { page }`. In wired mode the rail also sets `viewer.page` itself.

If `pageCount` shrinks past the currently focused row, focus moves to the absolute last remaining
page instead of using the rendered window's local index or being lost with the virtualized row.
Rapid consecutive shrinks supersede an in-flight repair, so focus lands on the latest count. The
numeric type-ahead buffer is cleared on detach. Alt/Ctrl/Meta-modified digits are left to browser or
application shortcuts and never enter the buffer.

**CSS parts:** `base` (the rail), `pages` (the embedded `<lr-virtual-list>`), `page` (one page
button), `page-current` (the button for the current `page`), `thumbnail` (the thumbnail canvas/DOM
preview wrapper), `thumbnail-target` (the canvas or renderer-owned DOM preview target), `page-number`
(the visible page number), `heat` (the heat-marker cluster), `heat-dot` (one
heat marker), `heat-dot-accent`, `heat-dot-success`, `heat-dot-warning`, `heat-dot-danger` and
`heat-dot-neutral` (the tone-specific name on each marker), and `heat-dot-overflow` (the `+n`
marker).

Page rows are rendered into the embedded `<lr-virtual-list>`'s own shadow root and forwarded with
`exportparts`, so `lr-page-rail::part(page)` and the rest reach them from a consuming stylesheet.
State variants each carry a second name in the element's part list rather than a state attribute,
because `::part()` cannot be followed by an attribute selector: the current row is
`part="page page-current"` and a danger marker is `part="heat-dot heat-dot-danger"`, and `::part()`
matches with `part~=` semantics, so both names select the same element.

Loading thumbnail skeletons are aria-hidden and non-announcing. Each page button already carries
the localized page name, so thumbnail work does not create one live region per virtualized row.

**Themeable custom properties:** `--lr-page-rail-height` (default `var(--lr-size-24rem)`) — block
size of the virtualized rail. `--lr-page-rail-current-bg` (default `var(--lr-color-brand-quiet)`) —
background of the `page-current` button, kept while the row is hovered so the current page stays
identifiable under the pointer. Each heat-dot tone has its own matching cssprop, all defaulting to
the same shared tone token the marker used before: `--lr-page-rail-heat-accent-color` (default
`var(--lr-color-brand)`, the base `heat-dot` rule shared by the default "accent" tone),
`--lr-page-rail-heat-success-color` (default `var(--lr-color-success)`),
`--lr-page-rail-heat-warning-color` (default `var(--lr-color-warning)`),
`--lr-page-rail-heat-danger-color` (default `var(--lr-color-danger)`), and
`--lr-page-rail-heat-neutral-color` (default `var(--lr-color-text-quiet)`).

## `lr-notebook-viewer`

Read-only Jupyter notebook (nbformat 4.x) renderer, composing existing components per cell.
Execution is a hard non-goal. Markdown cells render through `lr-markdown`, code cells through
`lr-code-block` (using the notebook's kernel language for syntax highlighting), and raw cells as
plain preformatted text. A code cell's `execute_result`/`display_data` outputs prefer, in order,
`image/png`, `image/jpeg`, `image/svg+xml` (sanitized), `text/html` (sanitized), `application/json`
(via `lr-json-viewer`), then `text/plain`. Stream/error outputs render as preformatted text (tinted
`danger` for stderr/tracebacks) with embedded ANSI SGR color/style escapes interpreted through the
same shared `internal/ansi.ts` parser `lr-terminal` uses — a traceback keeps its coloring instead of
showing raw `ESC[` sequences. Sanitizing raw HTML/SVG output markup lazy-loads the
optional peer `dompurify`; without it, the output renders a localized notice instead of raw markup.
Sanitized `text/html` output uses the passive-document profile: anchors, form controls, and custom
elements are unwrapped to ordinary text/children where safe, remote navigation/resource attributes
are removed, and only inline base64 raster image sources render. Sanitized `image/svg+xml` output
is likewise network-silent and non-interactive: animation is removed and only same-document
fragment references or inline base64 raster image references survive.
Cells are virtualized through `lr-virtual-list`. `node-path` anchors resolve `path[0]` as a cell
index; `fragment` anchors resolve a cell's own `id`. For cells with IDs, successful public anchor
navigation scrolls the matching virtual row into the notebook allocation and applies active-cell
paint using that same ID. Repeating a target scrolls back to it after manual scrolling.
`maxHeight` also bounds the child virtual viewport. No execution, no kernels, no editing, no
ipywidgets.

**Properties:** `src: string = ''` — URL to fetch and parse as a notebook; ignored while `notebook`
is present. `notebook?: Readonly<NotebookDoc> | string` (property only) — an already-parsed
notebook document, or its raw JSON text; presence wins over `src` (including an empty string) and
is parsed synchronously. Parsed document assignments are synchronously clone-owned and recursively
frozen; mutate a copy and reassign it to update the viewer, because later source-object mutation is
not observed.
Assigning `undefined` clears inline authority and immediately reloads the already configured `src`,
or exposes the idle state when no URL exists. `source: LyraNotebookViewerSource` is a readonly
discriminated snapshot (`{ kind: 'inline', value }`, `{ kind: 'url', url }`, or `null`).
`name: string = ''` —
accessible label, and matched against a `fragment` anchor's cell id. `outputCollapseLines: number =
40` (attribute `output-collapse-lines`) — a plain-text output longer than this many lines renders
collapsed behind a toggle; `0` disables collapsing. `maxHeight: string = ''` (attribute
`max-height`) — once set, the notebook scrolls internally past this height; invalid CSS
`max-height` values, declaration breaks, and `url()` are ignored. `anchorKinds: readonly
LyraAnchorKind[] = ['node-path', 'fragment']` (this viewer's supported `LyraAnchor.kind` values for
the shared anchor-target contract). The inherited carrier fields `highlights: readonly LyraHighlight[] = []`
(property only) and `activeHighlightId: string | null = null` (attribute `active-highlight-id`)
paint every highlight entry that resolves to a cell index (capped at 100 painted highlights), each
tinted by its tone and, when its `id` matches `activeHighlightId`, outlined. Use
`anchor: LyraAnchor | string | null = null` or `scrollToAnchor()` for notebook-cell navigation.

**Methods:** `search(query)` resolves the match count over cell sources and text outputs — a
matching cell counts as one match (empty/whitespace query behaves like `clearSearch()`);
queries are capped at 4,096 code units and one pass at 4,000,000 source/output code units, with
`matchCountExact: false` reporting a truncated lower bound;
`searchNext()`/`searchPrevious()` advance/step back through matches, scrolling to and marking the
target cell with the persistent active-cell paint, and each resolves `true` once the active match
moved or `false` when there are none — the same `Promise<boolean>` every other searchable viewer
resolves, so one find-in-page host can drive them all; `clearSearch()` clears the query and
matches.

**Events:** `lr-load` — `detail: { cellCount, language }`, fired once a notebook has been parsed
and validated (`language` from `metadata.language_info.name`/`kernelspec.language`, else `''`).
`lr-search-change` — `detail: { query, matchCount, matchCountExact, activeIndex }`, including
canonical source reset and effective-locale re-evaluation. `lr-render-error` —
`detail: { error }`, fetching, parsing, or validating the notebook failed. `lr-anchor-result` —
non-cancelable; `detail: { found: boolean }`, fired after an `anchor` assignment or a
`scrollToAnchor()` call is applied.

Neither `lr-highlight-activate` nor `lr-text-select` is part of `lr-notebook-viewer`'s event
contract: highlights are painted but not click-to-activate, and no selection binding is installed.
Use `anchor` plus `lr-anchor-result` for notebook cell navigation outcomes.

**CSS parts:** `base` (the root scroll container), `cell` (`data-cell-type="code|markdown|raw"`,
`data-active`), `cell-active` (added alongside `cell` on the cell currently targeted by an anchor
or the active search match),
`cell-highlighted` (added alongside `cell` on a cell matched by a `highlights` entry, always paired
with a tone-specific `cell-highlighted-<tone>` part below), `cell-highlighted-accent` (the default
tone), `cell-highlighted-success`, `cell-highlighted-warning`, `cell-highlighted-danger`,
`cell-highlighted-neutral`, `cell-highlight-active` (added alongside `cell-highlighted`/
`cell-highlighted-<tone>` when the matched highlight's `id` equals `activeHighlightId`),
`cell-gutter` (the `In [n]`/`Out [n]` label column), `cell-source`, `raw-source` (the horizontally
scrollable preformatted surface for a raw cell), `outputs`, `output`
(`data-output-type`, `data-stream`), `output-error` (added alongside `output` on a stderr stream or
an error output), `error-output-label` (the label introducing an error output's traceback),
`output-toggle`, `error`, `spinner`, and `anchor-live-region` (an aria-hidden, non-live shadow mirror
of the latest anchor-jump message; the spoken copy is appended to the shared document-level polite
sink only while the viewer and its composed ancestors are exposed to the accessibility tree). The
highlight/active state variants are separate part _names_ rather than attribute selectors, because
Shadow Parts forbids an attribute selector after `::part()`.
The document-level spinner always includes visible localized loading text alongside its decorative
ring; the text remains understandable without CSS or animation and the ring stops under reduced
motion.

Every cell-level part above is rendered into the embedded `<lr-virtual-list>`'s own shadow root and
forwarded back out through `exportparts`, so `lr-notebook-viewer::part(cell)` and friends work from
a consumer stylesheet. The three state variants are separate part _names_ rather than attribute
selectors, because Shadow Parts forbids an attribute selector after `::part()` —
`::part(cell)[data-active]` is invalid CSS, so use `::part(cell-active)`. The `data-*` attributes
remain on the elements for scripting.

**Themeable custom properties:** `--lr-notebook-viewer-max-height` (default `none`).

`--lr-notebook-viewer-active-bg` (default `var(--lr-color-brand-quiet)`) is the background of the
cell currently targeted by an anchor or the active search match — the `cell-active` part. It is an
inline `var()` fallback at the point of use rather than a `:host` declaration, so it can be set on
the element or on any ancestor.

`--lr-notebook-viewer-highlight-accent-background` (default `var(--lr-color-brand-quiet)`),
`--lr-notebook-viewer-highlight-success-background` (default `var(--lr-color-success-quiet)`),
`--lr-notebook-viewer-highlight-warning-background` (default `var(--lr-color-warning-quiet)`),
`--lr-notebook-viewer-highlight-danger-background` (default `var(--lr-color-danger-quiet)`), and
`--lr-notebook-viewer-highlight-neutral-background` (default `var(--lr-color-surface-raised)`) are
each tone's highlighted-cell background. `--lr-notebook-viewer-highlight-active-outline` (default
`var(--lr-focus-ring-color)`) outlines the highlighted cell whose highlight `id` equals
`activeHighlightId`.

**Optional peer deps:** `marked`+`dompurify` (markdown cells, falls back to plain text per cell),
`shiki` (code cells, falls back to unhighlighted), `dompurify` (HTML/SVG outputs, falls back to
`text/plain`).

```html
<lr-notebook-viewer max-height="30rem"></lr-notebook-viewer>
<script type="module">
  const viewer = document.querySelector("lr-notebook-viewer");
  viewer.notebook = result;
  viewer.addEventListener("lr-load", (e) => console.log(e.detail.cellCount, "cells"));
</script>
```

A notebook major version outside 4.0–4.5, an invalid shape, or more than 2,000 cells renders a
localized error and fires `lr-render-error` instead of the notebook.

PNG/JPEG outputs use their `text/plain` representation as alt text, falling back to a localized
code-cell name. Sanitized SVG output is wrapped in a named `role="img"` with the same fallback.

## `lr-xml-viewer`

Collapsible, copyable, `DOMParser`-based tree view for XML documents, mirroring `lr-json-viewer`'s
UX (`collapsed-depth`, `copyable`, structural-path-keyed expand state that survives a same-shape
`xml` reassignment) adapted for XML's own node kinds: elements with attributes, text, comments, CDATA
sections, and processing instructions, preserved in their original mixed-child source order.
Namespace-literal: qualified names render exactly as authored, with no namespace-URI-aware
matching. Every document type declaration is rejected before `DOMParser`, preventing external
entity access and browser-specific internal-entity expansion. Not `lr-json-viewer` (JS values); not `lr-html-viewer`
(sanitized _rendered_ HTML). No XPath/XSLT evaluation, no editing, no schema validation.

The registration entry also matches extensionless `application/*+xml` MIME essences, ignoring
parameters, case and outer whitespace. Exact registered MIME keys retain precedence over this
fallback matcher.

Importing `xml-viewer.js` (this component's own registration entry) loads `<lr-xml-viewer>`'s class
module immediately. A granular consumer (not importing the `all.js` compatibility bundle) who wants
that deferred too can instead import
`@aceshooting/lyra-ui/components/viewers/xml-viewer/xml-viewer-register.js`, which installs the
same registration lazily and exports `XML_VIEWER_TAG` (`'lr-xml-viewer'`) as a stable reference to
the tag it eventually registers.

**Properties:** `src: string = ''` — URL to fetch and parse; ignored once `xml` is set. `xml?:
string` (property only) — raw XML text to parse and render; wins over `src`, and setting it parses
synchronously. Assigning `undefined` relinquishes inline authority and immediately resumes an
already configured `src`, or exposes idle when none exists. `source: LyraXmlViewerSource` is the
readonly discriminated effective authority (`{ kind: 'inline', value }`, `{ kind: 'url', url }`, or
`null`). `name: string = ''` — accessible label. `collapsedDepth?: number` (attribute
`collapsed-depth`) — elements at or beyond this nesting depth (root = 0) start collapsed. `copyable:
boolean = false` (reflected) — shows copy-to-clipboard affordances, one for the whole document plus
one per element. `maxHeight: string = ''` (attribute `max-height`). `anchorKinds: readonly
LyraAnchorKind[] = ['node-path']` (this viewer's supported `LyraAnchor.kind` values for the shared anchor-target
contract) — each numeric path segment is the 0-based index within the parent's _element_ children,
and an optional trailing string segment `'@attrName'` addresses one existing, nonempty-named
attribute. Invalid CSS `max-height` values, declaration breaks, and `url()` are ignored.

**Methods:** `search(query)` resolves the match count via a case-insensitive substring search over
every element's tag name, attribute names/values, and own text (empty/whitespace query behaves like
`clearSearch()`), accepting at most 4,096 query code units and scanning at most 4,000,000 code
units while retaining 10,000 matches; `searchNext()`/`searchPrevious()` advance/step back through matches (wrapping);
`clearSearch()` clears the query and matches. Imperative `search()`, `searchNext()` and
`searchPrevious()` reopen the selected match and its ancestors, including manually collapsed
nodes, before scrolling. Other explicit collapse choices remain in effect, and later manual
collapse still takes precedence over default expansion. All three resolve only after the newly
active match's row has been scrolled into view (`block: 'center'`, `behavior: 'auto'` under
`prefers-reduced-motion`) — before 9.0.0 they moved `data-active-match` without ever scrolling, so
on a document taller than the viewport the reader never saw the match they had stepped to. Replacing
the XML source clears document-relative matches and emits the canonical empty `lr-search-change`;
changing the effective locale re-evaluates and emits the retained query.

**Highlights:** host-supplied `highlights` are first-class here, not carried and ignored. Every entry
whose anchor is a `node-path` this document resolves tints its element row — `[part='node']` gains
`data-highlight` carrying the entry's `tone` (`accent` when omitted) — and adds a focusable
`[part='highlight-action']` button that emits `lr-highlight-activate`. The button's accessible name
is the entry's own `label` when supplied, otherwise a localized "Highlight n of m". `activeHighlightId`
adds `data-active-highlight` to the matching row. Entries are deduplicated by `id`; an entry whose
anchor kind or path this document cannot resolve is dropped whole rather than painted at some
coarser granularity; missing and non-array `path` values are included in that invalid case. An entry
inside a collapsed subtree paints once that subtree is expanded.
Painting retains at most 100 resolved entries from a 1,000-entry candidate window; an active entry
anywhere in the bounded 10,000-record host snapshot is placed first inside both ceilings.

**Events:** `lr-copy` — emitted only after the owning realm's clipboard write fulfills, with
`detail: { ok: true, text }`. Clipboard absence, synchronous throws, and rejected writes instead
show the localized `copyFailed` label and emit generic `lr-error` plus `lr-copy-error` with
`detail: { ok: false, text, reason, error }`; `reason` is `'unsupported'`, `'denied'`, or `'failed'`.
`lr-search-change` — `detail: { query, matchCount, matchCountExact, activeIndex }`.
`lr-render-error` — `detail: { error }`, fetching or parsing failed, including a
parse error or exceeding the node cap. `lr-anchor-result` — non-cancelable; `detail: { found:
boolean }`, fired after an `anchor` assignment or a `scrollToAnchor()` call is applied.
`lr-highlight-activate` — non-cancelable; `detail: { highlightId }`, fired when a highlight's
`[part='highlight-action']` button is activated by click or Enter/Space. `lr-text-select` is not
part of this structural tree viewer's event contract because it installs no selection binding.

**CSS parts:** `base`, `toolbar` (the whole-document copy button row, only when `copyable`),
`copy-button` (the whole-document one, or a per-node one), `tree`, `node` (`data-active` while it's
the resolved anchor target, `data-match`, `data-active-match`, `data-highlight` carrying a resolved
highlight's tone, `data-active-highlight`), `tag` (`data-match`), `attribute` (`data-active` while a
`node-path` anchor's trailing `'@attrName'` segment addresses that specific attribute — so a citation
pointing at one attribute value of a multi-attribute element stays identifiable in the rendered
tree, rather than resolving indistinguishably from the bare element path),
`attribute-name`, `attribute-value` (`data-match`), `text` (`data-match`), `comment`, `cdata`, `pi`,
`toggle` (an element's expand/collapse button on nodes with renderable children; its collapsed
chevron mirrors under effective RTL direction), `highlight-action` (the focusable button a resolved
`highlights` entry adds to its element row), `toggle-placeholder` (the empty toggle-column spacer on
leaf rows), `error`, `spinner`, and `anchor-live-region` (an aria-hidden, non-live shadow mirror of
the latest anchor-jump message; the spoken copy is appended to the shared document-level polite sink
only while the viewer and its composed ancestors are exposed to the accessibility tree).
The spinner always includes visible localized loading text alongside its decorative ring; the text
remains understandable without CSS or animation and the ring stops under reduced motion.

**Themeable custom properties:** `--lr-xml-viewer-max-height` (default `none`) — maximum block size
of the scrollable body; also settable via the `max-height` property.
`--lr-xml-viewer-active-match-color` (default `var(--lr-color-warning)`) — the solid outline on the
`[part='node']` holding the _current_ search match, leaving every other match on its dashed
`--lr-xml-viewer-match-color` outline. It is an inline `var()` fallback at the point of use rather
than a `:host` declaration, so it can be set on the element _or on any ancestor_:
`::part(node)[data-active-match]` is invalid CSS — Shadow Parts forbids an attribute selector after
`::part()` — so distinguishing the active match previously meant re-pointing the shared
`--lr-color-warning` token, which recolored every other match (and every other warning surface)
along with it. Unset, it falls back to that token, so rendering is unchanged.

`--lr-xml-viewer-match-color` (default `var(--lr-color-warning)`) — outline color of a non-active
`[part='node']` search match, and (via `color-mix`) the tint source for a matching `[part='text']`'s
background — kept distinct from `--lr-xml-viewer-active-match-color` so the non-active matches can
be recolored without touching the active one. `--lr-xml-viewer-match-bg` (default
`var(--lr-color-warning-quiet)`) — background of a matching `[part='tag']`/`[part='attribute-value']`.
Both are inline `var()` fallbacks at the point of use, so either can be set on the element or any
ancestor; unset, they fall back to the same shared tokens the rules used before.

`--lr-xml-viewer-highlight-accent-background` (default `var(--lr-color-brand-quiet)`),
`--lr-xml-viewer-highlight-success-background` (default `var(--lr-color-success-quiet)`),
`--lr-xml-viewer-highlight-warning-background` (default `var(--lr-color-warning-quiet)`),
`--lr-xml-viewer-highlight-danger-background` (default `var(--lr-color-danger-quiet)`) and
`--lr-xml-viewer-highlight-neutral-background` (default `var(--lr-color-surface-raised)`) are the row
backgrounds of a resolved `highlights` entry per tone. The neutral default is deliberately
`--lr-color-surface-raised` and not `--lr-color-surface`: the viewer paints its own surface with the
latter, so a neutral highlight tinted with it would render as unhighlighted.
`--lr-xml-viewer-highlight-active-outline` (default `var(--lr-color-brand)`) outlines the entry named
by `activeHighlightId`, and `--lr-xml-viewer-active-attribute-color` (default `var(--lr-color-brand)`)
outlines the `[part='attribute']` an attribute-addressing `node-path` anchor resolved to.
`--lr-xml-viewer-tag-color` (default `var(--lr-color-brand)`) retints every rendered `[part='tag']`
element name, independent of that outline.

`[part='toggle']`'s glyph box stays compact (`1.25rem`) while its _interactive_ box takes the shared
minimum target size as a floor via `--lr-icon-button-size`. That token is a floor, not a fixed size,
so lowering it never squashes the chevron below its own box — the visible glyph keeps its size while
the hit target follows the token, and it can never fall under the accessible minimum from this
component's own rules. A collapsed chevron mirrors when effective direction is RTL (including an
inherited `dir` change); an expanded chevron points down in either direction.

```ts
const viewer = document.querySelector("lr-xml-viewer");
viewer.xml = payload;
viewer.collapsedDepth = 2;
viewer.copyable = true;
await viewer.search(query);
```

Node cap: 50,000 — exceeding it renders the localized `xmlViewerTooManyNodes` error instead of the
tree. A collapsed element's child count includes element, text, comment, CDATA, and processing-
instruction children rather than only element descendants.

## `lr-document-compare`

Comparison surface for two document versions, using `lr-diff-view` for textual diffs and
`lr-document-preview` for side-by-side rendered content.

A nonempty host `aria-label` makes the host the sole named semantic owner. With an explicitly empty
host label, the shadow comparison group keeps `role="group"` and an empty name; when the attribute
is absent, it uses the localized comparison label. Dynamic host-label changes update that ownership.

**Properties:**

- `oldVersion?: DocumentCompareVersion`, `newVersion?: DocumentCompareVersion` (attribute: false) —
  the before/after inputs. `DocumentCompareVersion` extends `DocumentRef`
  (`id`, `name`, `mimeType?`, `uri?`, `version?`) with `text?: string` for diff mode and
  `highlights?: LyraHighlight[]` for its own preview pane. Each assignment becomes a frozen
  snapshot: own string `id` and `name` are required or that pane is unset; valid string optional
  fields are retained and other values are omitted. Its highlights use the shared snapshot too, so
  mutation requires reassignment.
- `view: 'diff' | 'side-by-side' = 'diff'` (reflected) — one inline text diff or two rendered
  preview panes. Invalid property or attribute values normalize to `diff` and repair the reflected
  attribute.
- `diffLayout: 'unified' | 'split' = 'unified'` (attribute `diff-layout`, reflected) — forwarded
  to `lr-diff-view` in diff mode. Invalid property or attribute values normalize to `unified` and
  repair the reflected attribute.
- `copyable: boolean = false` — forwards the diff copy action.
- `language: string = ''`, `languages?: Record<string, ShikiLanguageInput>` (the latter
  attribute: false) — optional syntax highlighting forwarded to the diff. A runtime non-string
  `language` is treated as `''` without coercion.
- `syncScroll: boolean = true` (attribute `sync-scroll`) — proportionally mirrors either
  side-by-side pane's scroll fraction to the other. The true-default converter accepts the literal
  `sync-scroll="false"`.
- `anchor: LyraAnchor | string | null = null` (attribute: false) — sends the same target to both
  preview panes; repeated assignment of the same value still re-runs.
- `maxHeight: string = ''` (attribute `max-height`) — a CSS length (e.g. `"30rem"`) that overrides
  `--lr-document-compare-pane-max-height` declaratively, giving each `view="side-by-side"` pane its
  maximum block size before it scrolls internally. The value is sanitized as a CSS length, so an
  invalid one is ignored and the token default applies; the unset default `''` also defers to the
  token, so setting nothing preserves existing behaviour.

**Exported types:** `DocumentCompareVersion`; `LyraDocumentCompareView = 'diff' |
'side-by-side'`; `DocumentComparePaneSide = 'old' | 'new'`.

**Synchronized anchors:** activating a region highlight whose normalized id exists in the opposite
preview's trimmed, nonempty, first-wins highlight projection scrolls that pane to its corresponding
highlight, while the original `lr-highlight-activate`
continues bubbling unchanged. The shared `anchor` property drives both panes. In diff mode, split
columns already share one scroll container.

**Events:** `lr-copy` fires only after clipboard fulfillment (`detail: { ok: true, text }`). A
clipboard failure bubbles `lr-error` plus `lr-copy-error`
(`detail: { ok: false, text, reason, error }`) unchanged from `lr-diff-view`. Also emits
`lr-download` (`detail: { src, filename }`), `lr-highlight-activate` (`detail: { highlightId }`), and
`lr-render-error` (`detail: { error }`).

**Slots:** none.

**CSS parts:** `base`, `diff`, `panes`, `pane-old`, `pane-new`, `pane-header`, `pane-empty`.

**Themeable custom properties:** `--lr-document-compare-pane-max-height` (default
`var(--lr-size-24rem)`) — maximum block size of a `side-by-side` pane before it scrolls internally.

## `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.

Validates the parsed JSON is a `Feature`/`FeatureCollection`/bare geometry (one of `Point`,
`LineString`, `Polygon`, `MultiPoint`, `MultiLineString`, `MultiPolygon`, `GeometryCollection`) before
rendering; anything else renders the localized `geojsonViewInvalid` error. On success, it walks every
value and object key first, rejecting more than 50,000 graph units, nesting beyond 64 levels, more
than 2 Mi UTF-16 units of aggregate keys/string values, or more than 4 Mi UTF-16 units of formatted
metadata before serialization or peer handoff. It then walks every coordinate under a separate
10,000-position ceiling to compute a bounding box and fits a `center`/`zoom` to it (a Web-Mercator-fit
approximation weighting latitude span ~2x, with 40% padding), then hands the parsed value to
`<lr-map>` as a single `dataLayers` entry (`sourceId: 'lr-geojson'`). When the optional
`maplibre-gl` peer isn't installed, it falls back to a status line plus a `<lr-json-viewer
collapsed-depth="2">` of the raw value instead of the map.

The root owns the named `region` landmark while loading, in fallback/error/idle states, and while a
lazy map initializes. After `lr-map-load`, landmark ownership transfers to the map canvas so there
is exactly one named region. Serialized metadata is locally inline-scrollable, preventing long
unbroken values from widening a 320px allocation.

**Properties:** `src: string = ''` — URL to fetch and parse. `name: string = ''` — accessible label,
used as `<lr-map>`'s `label` and the root's `aria-label` (falling back to the localized
`geojsonViewLabel` when unset). A host `aria-label` takes precedence over `name`. The shared
text-viewer contract adds `highlights`, `activeHighlightId`, `anchor`, and
`anchorKinds` (`['text-quote', 'fragment']`), plus `search()`, `searchNext()`, `searchPrevious()`,
`clearSearch()`, and `scrollToAnchor()` for the ordinary-DOM serialized feature metadata and status
text, independent of whether the optional map peer is available. Fragment resolution is an exact
DOM `id` lookup, but the generated metadata, status, and map output define no fragment ids, so a
fragment jump reports `found: false`. Use a text-quote anchor for serialized metadata.

**Events:**

- `lr-render-error` — `detail: { error }` — fetch, parse, shape-validation, or missing-map capability
  failure. A missing optional MapLibre peer also keeps the serialized metadata fallback visible.
- `lr-search-change` — `detail: { query: string; matchCount: number; matchCountExact: boolean; activeIndex: number }` — fired
  whenever serialized-metadata search state changes.
- `lr-anchor-result` — `detail: { found: boolean }` — fired after an `anchor` assignment or
  `scrollToAnchor()` call is applied.
- `lr-text-select` — `detail: TextSelectDetail` (`{ text: string; anchor: LyraAnchor | null; rects:
DOMRect[] }`) — fired after a selection ends inside the serialized metadata.

`lr-highlight-activate` is not part of this registry bridge's event contract: serialized-metadata
highlights are passive and cannot be activated.

The three shared text-viewer events bubble and compose and are non-cancelable.

**CSS parts:** `base` (the root container with explicit `aria-busy="true"|"false"`), `status` (the
ordinary feature-count line, shown only in the `<lr-map>` path; a successful transition uses the
shared document-level polite sink), `metadata` (selectable/searchable serialized GeoJSON `<pre>`,
rendered in both map and fallback paths), `missing-library` (the missing-`maplibre-gl` callout shown
alongside the `lr-json-viewer` fallback; its transition uses the shared document-level assertive
sink), `error` (ordinary visible error text; later transitions use the same assertive sink),
`spinner` (a decorative skeleton plus an ordinary visually-hidden localized label; later loading
transitions use the shared document-level polite sink), and `anchor-live-region` (an aria-hidden,
non-live shadow mirror of the latest anchor-jump message; the spoken copy is appended to the shared
document-level polite sink only while the viewer and its composed ancestors are exposed to the
accessibility tree). No active live semantics are rendered in the viewer's shadow tree.

Those states carry the same visual tones the rest of this family uses rather than plain inherited
body text: `error` is `--lr-color-danger` (matching `lr-docx-viewer`/`lr-email-viewer`/
`lr-html-viewer`), `missing-library` is `--lr-color-warning` -- a missing optional peer is a degraded
but working state, since the `lr-json-viewer` fallback below it still renders the data, not a failure
-- and `status` is the quiet `--lr-color-text-quiet` metadata tone.

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`.
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.
MapLibre v5's standard build includes its worker, while v6 is ESM-only, requires WebGL2, and needs
its module-worker URL configured for the bundler before this viewer constructs the nested map. See
`llms/components/lr-map.md` for the Vite v6 example and the other bundler variants.

## Exported TypeScript contracts

These named interfaces and helper signatures are available to typed integrations. They are grouped by capability so the component sections above can stay focused.

- **`components-viewers-archive-viewer-archive-viewer-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/viewers/archive-viewer/archive-viewer.class.js`.
  `ArchiveEntry {
    name: string;
    dir: boolean;
    size: number;
  }`

- **`components-viewers-calendar-viewer-calendar-loader-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/viewers/calendar-viewer/calendar-viewer.js`.
  `clearIcalCache(): void`
  Import: `@aceshooting/lyra-ui/components/viewers/calendar-viewer/calendar-viewer.js`.
  `IcalApi {
    parse(source: string): unknown;
    Component: new (data: unknown) => IcalComponentApi;
    Event: new (component: unknown) => IcalEventApi;
  }`
  Import: `@aceshooting/lyra-ui/components/viewers/calendar-viewer/calendar-viewer.js`.
  `IcalComponentApi {
    getAllSubcomponents(name: string): unknown[];
  }`
  Import: `@aceshooting/lyra-ui/components/viewers/calendar-viewer/calendar-viewer.js`.
  `IcalEventApi {
    uid?: string;
    summary?: string;
    startDate?: IcalTimeApi;
    endDate?: IcalTimeApi;
    location?: string;
    description?: string;
  }`
  Import: `@aceshooting/lyra-ui/components/viewers/calendar-viewer/calendar-viewer.js`.
  `IcalTimeApi {
    toJSDate(): Date;
    isDate?: boolean;
    year?: number;
    month?: number;
    day?: number;
  }`
  Import: `@aceshooting/lyra-ui/components/viewers/calendar-viewer/calendar-viewer.js`.
  `loadIcalDeps(importIcal?: () => Promise<unknown>): Promise<IcalApi | null>`
  Import: `@aceshooting/lyra-ui/components/viewers/calendar-viewer/calendar-viewer.js`.
  `loadIcal(): Promise<IcalApi | null>`

- **`components-viewers-calendar-viewer-calendar-viewer-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/viewers/calendar-viewer/calendar-viewer.class.js`.
  `ParsedCalendarEvent {
    uid: string;
    summary: string;
    start: Date | null;
    end: Date | null;
    startKind: ParsedCalendarTimeKind | null;
    endKind: ParsedCalendarTimeKind | null;
    location: string;
    description: string;
  }`

- **`components-viewers-contact-viewer-vcard-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/viewers/contact-viewer/contact-viewer.js`.
  `parseVCards(text: string, options?: number | ParseVCardsOptions): VCardContact[]`
  Import: `@aceshooting/lyra-ui/components/viewers/contact-viewer/contact-viewer.js`.
  `ParseVCardsOptions {
    maxContacts?: number;
  }`
  Import: `@aceshooting/lyra-ui/components/viewers/contact-viewer/contact-viewer.js`.
  `VCardAddress {
    poBox: string;
    extendedAddress: string;
    streetAddress: string;
    locality: string;
    region: string;
    postalCode: string;
    country: string;
    types: string[];
  }`
  Import: `@aceshooting/lyra-ui/components/viewers/contact-viewer/contact-viewer.js`.
  `VCardContact {
    fn: string;
    n?: VCardName;
    org: string[];
    tel: VCardTypedValue[];
    email: VCardTypedValue[];
    adr: VCardAddress[];
  }`
  Import: `@aceshooting/lyra-ui/components/viewers/contact-viewer/contact-viewer.js`.
  `VCardName {
    familyNames: string;
    givenNames: string;
    additionalNames: string;
    honorificPrefixes: string;
    honorificSuffixes: string;
  }`
  Import: `@aceshooting/lyra-ui/components/viewers/contact-viewer/contact-viewer.js`.
  `VCardTypedValue {
    value: string;
    types: string[];
  }`

- **`components-viewers-dataset-viewer-dataset-viewer-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/viewers/dataset-viewer/dataset-viewer.class.js`.
  `DatasetTable {
    fields: string[];
    rows: Record<string, string>[];
  }`

- **`components-viewers-document-compare-document-compare-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/viewers/document-compare/document-compare.class.js`.
  `DocumentCompareVersion extends DocumentRef {
    readonly text?: string;
    readonly highlights?: readonly LyraHighlight[];
    // Inherited from DocumentRef.
    id: string;
    name: string;
    mimeType?: string;
    uri?: string;
    version?: string;
  }`

- **`components-viewers-document-viewer-anchors-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/viewers/document-viewer/document-viewer.js`.
  `AnchorResultDetail {
    found: boolean;
  }`
  Import: `@aceshooting/lyra-ui/components/viewers/document-viewer/document-viewer.js`.
  `AnchorTargetCapabilities {
    anchors?: LyraAnchorKind[];
    search?: boolean;
    textSelect?: boolean;
  }`
  Import: `@aceshooting/lyra-ui/components/viewers/document-viewer/document-viewer.js`.
  `HighlightActivateDetail {
    highlightId: string;
  }`
  Import: `@aceshooting/lyra-ui/components/viewers/document-viewer/document-viewer.js`.
  `LyraHighlight {
    readonly id: string;
    readonly anchor: LyraAnchor;
    readonly label?: string;
    readonly note?: string;
    readonly tone?: LyraHighlightTone;
  }`
  Import: `@aceshooting/lyra-ui/components/viewers/document-viewer/document-viewer.js`.
  `TextSelectDetail {
    readonly text: string;
    readonly anchor: LyraAnchor | null;
    readonly rects: readonly TextSelectRect[];
  }`
  Import: `@aceshooting/lyra-ui/components/viewers/document-viewer/document-viewer.js`.
  `TextSelectRect {
    readonly x: number;
    readonly y: number;
    readonly width: number;
    readonly height: number;
    readonly top: number;
    readonly right: number;
    readonly bottom: number;
    readonly left: number;
  }`

- **`components-viewers-document-viewer-registry-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/viewers/document-viewer/registry.js`.
  `adaptDocumentRenderer(candidate: LyraResolvedDocumentRendererDefinition, file: DocumentFile, supplied?: LyraDocumentRendererPayload): LyraAdaptedDocumentRenderer`
  Import: `@aceshooting/lyra-ui/components/viewers/document-viewer/registry.js`.
  `clearDocumentRenderers(): void`
  Import: `@aceshooting/lyra-ui/components/viewers/document-viewer/registry.js`.
  `createDocumentRendererAdapter<K extends LyraDocumentRendererPayloadKind>(definition: LyraDocumentRendererAdapterDefinition<K>): LyraDocumentRendererAdapter`
  Import: `@aceshooting/lyra-ui/components/viewers/document-viewer/registry.js`.
  `createDocumentRendererRegistry(overrides?: Iterable<readonly [string, DocumentRendererDefinition]>): DocumentRendererRegistry`
  Import: `@aceshooting/lyra-ui/components/viewers/document-viewer/registry.js`.
  `DirectDocumentRendererDefinition extends DocumentRendererDefinitionBase {
    readonly render: (file: DocumentFile) => unknown;
    readonly capabilities?: AnchorTargetCapabilities;
    readonly adapter?: never;
    readonly load?: never;
    // Inherited from DocumentRendererDefinitionBase.
    readonly matches?: (file: DocumentFile) => boolean;
  }`
  Import: `@aceshooting/lyra-ui/components/viewers/document-viewer/registry.js`.
  `DocumentFile {
    readonly name: string;
    readonly mimeType: string;
    readonly src: string;
    readonly anchor?: LyraAnchor | string;
    readonly highlights?: readonly LyraHighlight[];
    readonly alt?: string;
  }`
  Import: `@aceshooting/lyra-ui/components/viewers/document-viewer/registry.js`.
  `findDocumentRenderer(file: DocumentFile, registry?: DocumentRendererRegistry): DocumentRendererDefinition | undefined`
  Import: `@aceshooting/lyra-ui/components/viewers/document-viewer/registry.js`.
  `getDefaultDocumentRendererRegistry(): DocumentRendererRegistry`
  Import: `@aceshooting/lyra-ui/components/viewers/document-viewer/registry.js`.
  `LazyDocumentRendererDefinition extends DocumentRendererDefinitionBase {
    readonly render?: never;
    readonly adapter?: never;
    readonly capabilities?: AnchorTargetCapabilities;
    readonly load: () => Promise<DirectDocumentRendererDefinition | {
      default: DirectDocumentRendererDefinition;
    }>;
    // Inherited from DocumentRendererDefinitionBase.
    readonly matches?: (file: DocumentFile) => boolean;
  }`
  Import: `@aceshooting/lyra-ui/components/viewers/document-viewer/registry.js`.
  `loadDocumentRenderer(candidate: DirectDocumentRendererDefinition | LazyDocumentRendererDefinition): Promise<DirectDocumentRendererDefinition>;
  loadDocumentRenderer(candidate: LyraAdaptedDocumentRendererDefinition): Promise<LyraAdaptedDocumentRendererDefinition>;
  loadDocumentRenderer(candidate: DocumentRendererDefinition): Promise<LyraResolvedDocumentRendererDefinition>;`
  Import: `@aceshooting/lyra-ui/components/viewers/document-viewer/registry.js`.
  `LyraAdaptedDocumentRendererDefinition extends DocumentRendererDefinitionBase {
    readonly adapter: LyraDocumentRendererAdapter;
    readonly render?: never;
    readonly capabilities?: never;
    readonly load?: never;
    // Inherited from DocumentRendererDefinitionBase.
    readonly matches?: (file: DocumentFile) => boolean;
  }`
  Import: `@aceshooting/lyra-ui/components/viewers/document-viewer/registry.js`.
  `LyraAdaptedDocumentRenderer {
    readonly payload: LyraDocumentRendererPayload;
    readonly capabilities?: AnchorTargetCapabilities;
    readonly render: () => unknown;
  }`
  Import: `@aceshooting/lyra-ui/components/viewers/document-viewer/registry.js`.
  `LyraAvDocumentRendererPayload {
    readonly kind: 'av';
    readonly file: LyraDocumentFile;
    readonly cues: readonly LyraAvCue[];
    readonly tracks: readonly LyraAvTrack[];
  }`
  Import: `@aceshooting/lyra-ui/components/viewers/document-viewer/registry.js`.
  `LyraDocumentFile {
    readonly name: string;
    readonly mimeType: string;
    readonly src: string;
    readonly anchor?: LyraAnchor | string;
    readonly highlights?: readonly LyraHighlight[];
    readonly alt?: string;
  }`
  Import: `@aceshooting/lyra-ui/components/viewers/document-viewer/registry.js`.
  `LyraDocumentRendererAdapterDefinition<K extends LyraDocumentRendererPayloadKind> {
    readonly kind: K;
    readonly adapt: (file: DocumentFile, supplied?: LyraDocumentRendererPayload) => LyraDocumentRendererPayloadFor<K>;
    readonly capabilities: (payload: LyraDocumentRendererPayloadFor<K>) => AnchorTargetCapabilities | undefined;
    readonly render: (payload: LyraDocumentRendererPayloadFor<K>) => unknown;
  }`
  Import: `@aceshooting/lyra-ui/components/viewers/document-viewer/registry.js`.
  `LyraDocumentRendererAdapter {
    readonly kind: LyraDocumentRendererPayloadKind;
    readonly [DOCUMENT_RENDERER_ADAPTER]: true;
    adapt(file: DocumentFile, supplied?: LyraDocumentRendererPayload): LyraDocumentRendererPayload;
    capabilities(payload: LyraDocumentRendererPayload): AnchorTargetCapabilities | undefined;
    render(payload: LyraDocumentRendererPayload): unknown;
  }`
  Import: `@aceshooting/lyra-ui/components/viewers/document-viewer/registry.js`.
  `LyraGenericDocumentRendererPayload {
    readonly kind: 'document';
    readonly file: LyraDocumentFile;
  }`
  Import: `@aceshooting/lyra-ui/components/viewers/document-viewer/registry.js`.
  `registerDocumentRenderer(key: string, definition: DocumentRendererDefinition): void`
  Import: `@aceshooting/lyra-ui/components/viewers/document-viewer/registry.js`.
  `snapshotLyraDocumentRendererPayload(value: LyraDocumentRendererPayload): LyraDocumentRendererPayload`

- **`components-viewers-docx-viewer-docx-loader-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/viewers/docx-viewer/docx-viewer.js`.
  `clearDocxDepsCache(): void`
  Import: `@aceshooting/lyra-ui/components/viewers/docx-viewer/docx-viewer.js`.
  `DocxDeps {
    mammoth: MammothApi | undefined;
    DOMPurify: HtmlSanitizer | undefined;
  }`
  Import: `@aceshooting/lyra-ui/components/viewers/docx-viewer/docx-viewer.js`.
  `getDocxDepsIfLoaded(): DocxDeps | undefined`
  Import: `@aceshooting/lyra-ui/components/viewers/docx-viewer/docx-viewer.js`.
  `loadDocxDeps(): Promise<DocxDeps>`
  Import: `@aceshooting/lyra-ui/components/viewers/docx-viewer/docx-viewer.js`.
  `loadMammothAndSanitizer(importMammoth?: () => Promise<unknown>, importDompurify?: () => Promise<unknown>): Promise<DocxDeps>`
  Import: `@aceshooting/lyra-ui/components/viewers/docx-viewer/docx-viewer.js`.
  `MammothApi {
    convertToHtml(input: {
      arrayBuffer: ArrayBuffer;
    }): Promise<{
      value: string;
      messages: unknown[];
    }>;
  }`

- **`components-viewers-docx-viewer-docx-viewer-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/viewers/docx-viewer/docx-viewer.class.js`.
  `DocxHeadingItem {
    id: string;
    label: string;
    level: number;
  }`

- **`components-viewers-ebook-viewer-ebook-viewer-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/viewers/ebook-viewer/ebook-viewer.class.js`.
  `EbookTocItem {
    id: string;
    label: string;
    href: string;
    level: number;
  }`

- **`components-viewers-email-viewer-email-loader-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/viewers/email-viewer/email-viewer.js`.
  `clearEmailDepsCache(): void`
  Import: `@aceshooting/lyra-ui/components/viewers/email-viewer/email-viewer.js`.
  `EmailDeps {
    PostalMime: PostalMimeApi | undefined;
    DOMPurify: HtmlSanitizer | undefined;
  }`
  Import: `@aceshooting/lyra-ui/components/viewers/email-viewer/email-viewer.js`.
  `getEmailDepsIfLoaded(): EmailDeps | undefined`
  Import: `@aceshooting/lyra-ui/components/viewers/email-viewer/email-viewer.js`.
  `loadEmailAndSanitizer(importPostalMime?: () => Promise<unknown>, importDompurify?: () => Promise<unknown>): Promise<EmailDeps>`
  Import: `@aceshooting/lyra-ui/components/viewers/email-viewer/email-viewer.js`.
  `loadEmailDeps(): Promise<EmailDeps>`
  Import: `@aceshooting/lyra-ui/components/viewers/email-viewer/email-viewer.js`.
  `PostalAddressApi {
    name?: string;
    address?: string;
    group?: PostalAddressApi[];
  }`
  Import: `@aceshooting/lyra-ui/components/viewers/email-viewer/email-viewer.js`.
  `PostalAttachmentApi {
    filename?: string | null;
    mimeType?: string;
    content: ArrayBuffer | Uint8Array | string;
  }`
  Import: `@aceshooting/lyra-ui/components/viewers/email-viewer/email-viewer.js`.
  `PostalMessageApi {
    html?: string;
    text?: string;
    from?: PostalAddressApi;
    to?: PostalAddressApi[];
    subject?: string;
    date?: string;
    attachments?: PostalAttachmentApi[];
  }`
  Import: `@aceshooting/lyra-ui/components/viewers/email-viewer/email-viewer.js`.
  `PostalMimeApi {
    parse(input: ArrayBuffer): Promise<PostalMessageApi>;
  }`

- **`components-viewers-email-viewer-email-viewer-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/viewers/email-viewer/email-viewer.class.js`.
  `LyraEmailAttachmentOpenDetail {
    readonly attachment: Readonly<{
      filename: string;
      mimeType: string;
      content?: Blob;
    }>;
  }`
  Import: `@aceshooting/lyra-ui/components/viewers/email-viewer/email-viewer.class.js`.
  `ParsedEmailAttachment {
    filename: string;
    mimeType: string;
    size: number;
    content?: Uint8Array;
  }`
  Import: `@aceshooting/lyra-ui/components/viewers/email-viewer/email-viewer.class.js`.
  `ParsedEmail {
    from: string;
    to: string;
    subject: string;
    date: string;
    bodyHtml: string | null;
    bodyText: string | null;
    attachments: ParsedEmailAttachment[];
  }`

- **`components-viewers-highlight-layer-highlight-layer-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/viewers/highlight-layer/highlight-layer.class.js`.
  `HighlightLayerItem {
    readonly id: string;
    readonly rects: readonly Readonly<{
      x: number;
      y: number;
      width: number;
      height: number;
    }>[];
    readonly label?: string;
    readonly tone?: LyraHighlightTone;
  }`

- **`components-viewers-include-include-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/viewers/include/include.class.js`.
  `LyraIncludeErrorDetail {
    status: number;
    reason: LyraIncludeErrorReason;
    error?: unknown;
  }`

- **`components-viewers-page-rail-page-rail-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/viewers/page-rail/page-rail.class.js`.
  `LyraPageViewerSnapshot {
    readonly identity: number;
    readonly status: LyraPageViewerStatus;
    readonly page: number;
    readonly pageCount: number;
  }`
  Import: `@aceshooting/lyra-ui/components/viewers/page-rail/page-rail.class.js`.
  `LyraPageViewerStateChangeDetail {
    readonly snapshot: LyraPageViewerSnapshot;
  }`
  Import: `@aceshooting/lyra-ui/components/viewers/page-rail/page-rail.class.js`.
  `PageThumbnailRenderHandle {
    dispose(): void;
  }`
  Import: `@aceshooting/lyra-ui/components/viewers/page-rail/page-rail.class.js`.
  `PageThumbnailSource extends EventTarget {
    page: number;
    readonly pageViewerSnapshot?: LyraPageViewerSnapshot;
    renderPageThumbnail?(page: number, canvas: HTMLCanvasElement, options?: {
      width?: number;
    }): Promise<boolean>;
    renderPageThumbnailToContainer?(page: number, container: HTMLElement, options?: {
      width?: number;
    }): Promise<PageThumbnailRenderHandle | false>;
  }`

- **`components-viewers-pdf-viewer-pdf-viewer-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/viewers/pdf-viewer/pdf-viewer.class.js`.
  `PdfOutlineItem {
    title: string;
    page?: number;
    children?: PdfOutlineItem[];
  }`

- **`components-viewers-pptx-viewer-pptx-loader-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/viewers/pptx-viewer/pptx-loader.js`.
  `adaptPptxViewer(value: unknown): PptxViewerAdapter | null`
  Import: `@aceshooting/lyra-ui/components/viewers/pptx-viewer/pptx-loader.js`.
  `getPptxRenderer(): Promise<PptxRendererModule | null>`
  Import: `@aceshooting/lyra-ui/components/viewers/pptx-viewer/pptx-loader.js`.
  `loadPptxRenderer(importer?: () => Promise<unknown>): Promise<PptxRendererModule | null>`
  Import: `@aceshooting/lyra-ui/components/viewers/pptx-viewer/pptx-loader.js`.
  `PptxRendererModule {
    PptxViewer: {
      open(input: ArrayBuffer, container: HTMLElement, options?: Record<string, unknown>): Promise<PptxViewerApi>;
    };
    RECOMMENDED_ZIP_LIMITS: Readonly<PptxZipLimits>;
  }`
  Import: `@aceshooting/lyra-ui/components/viewers/pptx-viewer/pptx-loader.js`.
  `PptxSearchHighlightHandle {
    dispose(): void;
  }`
  Import: `@aceshooting/lyra-ui/components/viewers/pptx-viewer/pptx-loader.js`.
  `PptxTextSearchResult {
    readonly slideIndex: number;
    readonly nodeId: string;
    readonly matchStart: number;
    readonly matchEnd: number;
    readonly text: string;
  }`
  Import: `@aceshooting/lyra-ui/components/viewers/pptx-viewer/pptx-loader.js`.
  `PptxThumbnailHandle {
    readonly ready: Promise<void>;
    dispose(): void;
  }`
  Import: `@aceshooting/lyra-ui/components/viewers/pptx-viewer/pptx-loader.js`.
  `PptxViewerAdapter {
    readonly slideCount: number;
    readonly currentSlideIndex: number;
    goToSlide(index: number): Promise<void>;
    searchText(query: string, options?: {
      matchCase?: boolean;
    }): PptxTextSearchResult[];
    highlightSearchResult(result: PptxTextSearchResult, options?: {
      scrollIntoView?: boolean | ScrollIntoViewOptions;
    }): Promise<PptxSearchHighlightHandle | null>;
    renderThumbnailToContainer(index: number, container: HTMLElement, options?: {
      width?: number;
    }): PptxThumbnailHandle | null;
    clearSearchHighlights(): void;
    subscribe(listener: (event: PptxViewerAdapterEvent) => void): () => void;
    destroy(): void;
  }`
  Import: `@aceshooting/lyra-ui/components/viewers/pptx-viewer/pptx-loader.js`.
  `PptxViewerApi extends EventTarget {
    slideCount: number;
    currentSlideIndex: number;
    goToSlide(index: number): Promise<void> | void;
    searchText(query: string, options?: {
      matchCase?: boolean;
    }): PptxTextSearchResult[];
    highlightSearchResult(result: PptxTextSearchResult, options?: {
      scrollIntoView?: boolean | ScrollIntoViewOptions;
    }): Promise<PptxSearchHighlightHandle | null>;
    renderThumbnailToContainer(index: number, container: HTMLElement, options?: {
      width?: number;
    }): PptxThumbnailHandle | null;
    clearSearchHighlights(): void;
    destroy(): void;
  }`
  Import: `@aceshooting/lyra-ui/components/viewers/pptx-viewer/pptx-loader.js`.
  `PptxZipLimits {
    maxEntries: number;
    maxEntryUncompressedBytes: number;
    maxTotalUncompressedBytes: number;
    maxMediaBytes: number;
    maxConcurrency: number;
  }`

- **`components-viewers-spreadsheet-viewer-spreadsheet-loader-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/viewers/spreadsheet-viewer/spreadsheet-viewer.js`.
  `clearSheetJsCache(): void`
  Import: `@aceshooting/lyra-ui/components/viewers/spreadsheet-viewer/spreadsheet-viewer.js`.
  `loadSheetJsCached(): Promise<SheetJsApi | null>`
  Import: `@aceshooting/lyra-ui/components/viewers/spreadsheet-viewer/spreadsheet-viewer.js`.
  `loadSheetJs(importXlsx?: () => Promise<unknown>): Promise<SheetJsApi | null>`
  Import: `@aceshooting/lyra-ui/components/viewers/spreadsheet-viewer/spreadsheet-viewer.js`.
  `SheetJsApi {
    read(input: ArrayBuffer, options?: Record<string, unknown>): SheetJsWorkbook;
    utils: {
      sheet_to_json(sheet: unknown, options?: Record<string, unknown>): unknown;
    };
  }`
  Import: `@aceshooting/lyra-ui/components/viewers/spreadsheet-viewer/spreadsheet-viewer.js`.
  `SheetJsWorkbook {
    SheetNames: string[];
    Sheets: Record<string, unknown>;
  }`

- **`components-viewers-viewer-diagnostics-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/viewers/docx-viewer/docx-viewer.class.js`.
  `LyraViewerDiagnosticEventDetail {
    readonly diagnostic: LyraViewerDiagnostic;
  }`
  Import: `@aceshooting/lyra-ui/components/viewers/docx-viewer/docx-viewer.class.js`.
  `LyraViewerDiagnostic {
    readonly code: LyraViewerDiagnosticCode;
    readonly severity: LyraViewerDiagnosticSeverity;
    readonly fatal: boolean;
    readonly source: 'mammoth' | 'pptx-renderer';
    readonly cause: unknown;
    readonly page?: number;
    readonly nodeId?: string;
  }`

# Conversation & chat UI (`components/conversation/`)

## Breaking changes and fixes in 9.0.0

Fixed: `<lr-markdown>`/`<lr-markdown-core>`'s renderer overrides (heading, paragraph, code-block,
table, link, image, inline/block math) previously emitted HTML with mismatched open/close
attribute-quote characters, which could corrupt the parsed DOM for real documents containing those
constructs. Output is now well-formed HTML for every renderer override, using matched single-quote
attribute delimiters; no public API changed.

Breaking (v9): `<lr-model-select>`, `<lr-voice-picker>`, `<lr-prompt-input>`, and `<lr-chat-composer>`
no longer emit the v8 `lr-focus`/`lr-blur` compatibility-alias events. Listen for the native-named
`focus`/`blur` events instead. Also fixed as part of the same change: `<lr-prompt-input>`'s `focus`/
`blur` now relay only from its own primary textarea; a descendant control's own focus/blur no longer
leaks through as the composite element's own focus/blur.

## `lr-markdown`

Sanitized Markdown-to-HTML rendering (GFM tables, fenced code blocks, links, blockquotes) built on
two optional peer dependencies — `marked` (parsing) and `dompurify` (sanitizing) — both lazy-loaded
independently via `markdown-loader.ts`'s `loadMarkdownDeps()` on first connect, cached per page the
same way `chart-core-loader.ts`/`map-loader.ts` cache their load promise so every `<lr-markdown>`
instance on a page shares one load. `heading`/`code`/`blockquote`/`table`/`link`/`image` tokens are
rendered through a `marked` renderer override that injects `part="..."` attributes directly into the
produced HTML in a single pass (no second DOM walk after insertion).

Removing `content` clears the document and its empty-document tab stop, including while streaming.
The property keeps Lit's `null` readback after removal; an explicitly empty attribute remains an
empty string. Later source text renders normally.

If an instance disconnects and reconnects before that shared promise settles, only the current
connection applies the result and reparses; the stale connection callback is generation-guarded.

To warm that shared cache before the first Markdown instance connects, await the stable public
entry point. This keeps the default lazy behavior for apps that do not need it while letting a
route or startup boundary render from an already-settled cache. The helper is exported by both
the full and core granular entries:

```ts
import { preloadMarkdown } from "@aceshooting/lyra-ui/components/conversation/markdown/markdown.js";

await preloadMarkdown();
```

Fenced code blocks are also syntax-highlighted via the same optional `shiki` peer `<lr-code-block>`
uses, gated by `highlightCode` (default `true`). This is a pure upgrade, not a separate opt-in: it's
already transparently gated by whether `shiki` is installed at all, so an app that never installs the
peer sees byte-identical output to before this property existed. The very first render of any content
is always plain text/code (identical to today's output); highlighting arrives as an asynchronous
upgrade one render later once shiki resolves and the block's language is tokenized. No highlighting
is attempted while `streaming` is `true` — it applies once a stream settles, adding no per-chunk cost
while content is still arriving.

Highlighted blocks follow the page's resolved theme. Shiki emits both palettes at once, so
`[part="content"]` carries `data-dark-theme="true"` whenever the component's own resolved
`--lr-color-text` is lighter than its `--lr-color-surface`, and the stylesheet then paints each
token from `--shiki-dark`/`--shiki-dark-bg` rather than the light inline color. It keys off the
resolved tokens rather than `prefers-color-scheme`, so an app theming with `--lr-theme-color-*`
independently of the OS setting gets the dark palette too — the same mechanism `<lr-code-block>`
uses for its own `[part="body"]`.

**Properties:**

- `content: string = ''` — the Markdown source to render
- `tabSize: number = 4` (attribute `tab-size`) — tab-stop width used to expand tabs in leading
  indentation before parsing. Values are finite-integer guarded and clamped to `[1, 32]` at use;
  invalid values fall back to `4`. This is separate from `--lr-code-block-tab-size`, which controls
  how tabs already inside rendered code are displayed.
- `marked: LyraMarkedParser | undefined` (readonly, no attribute) — this instance's peer-neutral,
  configurable `marked.Marked` parser. It is `undefined` while the optional peer is still resolving
  or unavailable. Each element owns an isolated parser, so `marked.use(...extensions)` affects only
  that element; call `renderMarkdown()` after configuring it. The peer-neutral type deliberately
  models Lyra's stable `defaults`/`use()`/`parse()` surface; consumers using version-specific Marked
  tokenizers, constructors, or helpers should type that local reference with their installed
  `marked` version.
- `htmlMode: 'sanitize' | 'escape' | 'trusted' = 'sanitize'` (attribute `html-mode`) — controls raw
  authored HTML. `sanitize` passes the complete rendered document through DOMPurify and fails closed
  to plain text if the peer is unavailable; `escape` displays raw HTML source as text while ordinary
  Markdown still renders; `trusted` renders raw HTML without sanitization and is only for trusted
  content.
- `gfm: boolean = true` — GitHub-flavored Markdown (tables, strikethrough, autolinks, task lists).
  GFM task-list checkboxes stay disabled. A task's primary inline text supplies its accessible name;
  nested task text is excluded, and a blank task receives no generated name.
- `linkTarget: string | null = '_blank'` (attribute `link-target`) — `target` applied to every
  rendered `<a>`, with `rel="noopener noreferrer"` always added alongside it whenever a `target` is
  emitted. `'_blank'` (the default) preserves the original output; a falsy value (`null`, or the
  empty string via `link-target=""`) omits `target`/`rel` entirely instead of always defaulting to
  `_blank`, so rendered links open in the same tab
- `internalLinkPrefix: string = ''` (attribute `internal-link-prefix`) — when set, a rendered link
  whose `href` _attribute_ (not the browser-resolved `.href` property) starts with this prefix is
  intercepted on click and reported via `lr-link-click` instead of navigating; empty (the default)
  means every link is treated as external
- `headingOffset: number = 0` (attribute `heading-offset`) — added to every rendered heading's
  source `token.depth` before emitting `<h${depth}>` (e.g. `heading-offset="2"` renders a source `#`
  as `<h3>`); clamped to `[1, 6]` so a source `######` with a positive offset stays at `<h6>` rather
  than overflowing past the HTML heading levels. `0` (the default) preserves the original
  `<h${token.depth}>` output
- `streaming: boolean = false` (reflected) — marks the host `aria-busy="true"` while partial Markdown
  is still arriving and lets consumers target `lr-markdown[streaming]`. Both `lr-markdown` and
  `lr-markdown-core` display accumulated plain text without parsing or highlighting while it is
  true. Setting `streaming=false` parses and renders the latest complete content; busy state also
  remains true while parser dependencies are loading
- `highlightCode: boolean = true` (attribute `highlight-code`) — syntax-highlights fenced code
  blocks via the optional `shiki` peer. `true` (the default) upgrades every fenced block once the
  peer is available; set `false` to keep plain output even when `shiki` is installed. No effect
  while `streaming` is `true`
- `languages?: Record<string, ShikiLanguageInput>` (attribute: false) — same shape and purpose as
  `<lr-code-block>`'s own `languages`: a fine-grained, explicit language-grammar bundle scoping
  shiki's build output to just those grammars instead of its full ~200-language bundle. Forwarded
  verbatim to `loadShikiHighlighterCore()`. Unset (the default) uses the default full-bundle loader
- `headingAnchors: boolean = false` (attribute `heading-anchors`) — stamps a computed
  GitHub-slugger-style slug as `id` on every rendered heading.
- `math: boolean = false` — renders `$inline$` and `$$block$$` TeX via the optional `katex` peer,
  lazy-loaded the same way as `marked`/`dompurify`/`shiki`.
- `maxHeight: string = ''` (attribute `max-height`) — a CSS length (e.g. `"20rem"`); once set,
  `[part="content"]` scrolls internally past this height instead of growing the page. Invalid
  values are ignored.
- `highlights: readonly LyraHighlight[] = []` (attribute: false) — host-supplied `text-quote` highlights;
  reassign the array after mutation so painting is refreshed.
- `activeHighlightId: string | null = null` (attribute `active-highlight-id`) — identifies the
  currently active entry in `highlights` for active paint and outline treatment.
- `anchor: LyraAnchor | string | null = null` (attribute: false) — declaratively applies an anchor
  or a highlight id through the same path as `scrollToAnchor()`; assigning the same value again
  deliberately re-runs resolution.
- `anchorKinds: readonly ('fragment' | 'text-quote')[] = ['fragment', 'text-quote']` — the anchor kinds this
  component resolves for the shared anchor-target contract.

Text-quote resolution indexes at most 1,000,000 code units/20,000 text nodes per content
generation, accepts quote fields up to 4,096 code units, and scans at most 4,000,000 code units per
pass. It reuses that index across navigation and painting. Host-highlight admission retains at most
10,000 unique nonempty records after inspecting at most 10,001 inputs; rendering selects at most
1,000 candidates and paints at most 100, with an active entry anywhere in the admitted snapshot
placed first and preserved inside both ceilings.

**Methods:**

- `renderMarkdown(): void` — immediately reruns the current content through the parse, selected
  HTML-mode, and fallback pipeline. Use it to refresh existing content after changing `marked` configuration;
  it safely no-ops while the optional parser is unresolved.
- `getHeadingTree(): MarkdownHeadingItem[]` — returns the document-ordered heading outline
  (`{ id, label, level }[]`)
  computed on every parse, regardless of `headingAnchors`.
- `LyraMarkdown.getMarked(): Marked` — returns the variant's shared compatibility parser (`Marked`
  is the route's exported alias of `LyraMarkedParser`),
  whose configuration seeds instance parses. Await `preloadMarkdown()` first; otherwise this throws.
- `LyraMarkdown.updateAll(): void` — re-renders every connected full Markdown instance after shared
  compatibility-parser configuration changes. Prefer the instance `marked` parser for isolated
  configuration.

**Events:**

- `lr-link-click` (`detail: { href: string }`) — fired, with navigation prevented, when a rendered
  link's `href` starts with `internal-link-prefix`; ordinary external links navigate normally and
  never fire this. If an intercepted link overlaps a painted highlight,
  `lr-highlight-activate` fires first for pointer and Enter activation.
- `lr-render-error` (`detail: { error: unknown }`) — rendering fell back to plain text (see the
  fallback matrix below), or `math` is set but the `katex` peer isn't installed
- `lr-highlight-activate` (`detail: { highlightId: string }`) — a painted `text-quote` highlight was clicked
- `lr-text-select` (`detail: { text: string; anchor: LyraAnchor | null; rects: DOMRect[] }`) — a text
  selection inside the rendered content ended; `anchor` is a `text-quote` anchor scoped to the
  rendered content, or `null` when the selection couldn't be anchored
- `lr-anchor-result` (`detail: { found: boolean }`) — fired after an `anchor` property assignment or
  a `scrollToAnchor()` call is applied (the shared anchor-target contract)
- `lr-content-settled` (`detail: null`, composed, bubbling) — fired whenever newly-rendered content
  actually reaches `[part="content"]`, including a transient plain-text fallback frame and a later
  async syntax-highlight upgrade, not only a final parsed render. Being composed, it crosses this
  element's own shadow boundary — a consumer composing `<lr-markdown>` inside a free-form container
  (e.g. `<lr-thinking-panel>`'s default slot) can listen for it to drive auto-scroll, since a
  light-DOM `MutationObserver` on that container can never see a property-driven update rendered
  entirely inside this element's own shadow root. See `<lr-thinking-panel>`'s own reference at `llms/components/lr-thinking-panel.md`.

**Slots:** none — content comes from the `content` property, not light-DOM children.

**CSS parts:** `content` (the wrapper around the rendered or plain-text-fallback output; respects
`max-height`; carries `data-fallback` while showing the plain-text fallback — still-loading peers
or a failed render — so a consumer can target `lr-markdown [part='content'][data-fallback]` to
style it distinctly), `anchor-live-region` (the aria-hidden, non-live shadow mirror of the latest
anchor-jump message), `heading` (every rendered `<h1>`–`<h6>`, shifted by `heading-offset`),
`paragraph` (every rendered `<p>`), `list` (every rendered `<ul>`/`<ol>`), `code-block` (every
rendered fenced/indented `<pre>`), `inline-code` (every rendered inline `<code>` span — backtick
spans, not fenced blocks), `link` (every rendered `<a>`), `table` (every rendered `<table>`),
`blockquote` (every rendered `<blockquote>`), `img` (every rendered `<img>`), `math` (a rendered
inline or block math span, carrying `data-display="inline"|"block"`)

**Themeable custom properties:** `--lr-markdown-max-height` (default `none` — cap on
`[part="content"]`'s block size, past which the document scrolls internally; the `maxHeight`
property sets this token inline on `[part="content"]`), `--lr-markdown-font-mono` (default `var(--lr-font-mono)` — the
code/code-block font, resolving through the library's shared monospace stack so a
`--lr-theme-font-family-mono` override reaches it), `--lr-markdown-code-bg` (default
`var(--lr-color-brand-quiet)` — background shared by every inline `code` span and the fenced
`code-block` surface, so a consumer can retheme either or both together without repainting every
other surface that reads the shared brand-quiet token), `--lr-markdown-code-padding` (default
`var(--lr-size-0-125rem) var(--lr-size-0-3125rem)` — inline `code` span padding),
`--lr-markdown-code-radius` (default `calc(var(--lr-radius) * 0.5)` — inline `code` span border
radius), `--lr-markdown-code-block-padding` (default `var(--lr-space-s) var(--lr-space-m)` — the
fenced `code-block` surface's padding), `--lr-markdown-code-block-radius` (default `var(--lr-radius)`
— the fenced `code-block` surface's border radius), `--lr-markdown-table-header-bg` (default
`var(--lr-color-brand-quiet)` — background of every rendered `[part="table"]` header cell),
`--lr-code-block-tab-size` (default `2` — tab
width inside a rendered fenced or indented `code-block`), plus shared tokens
`--lr-space-xs/-s/-m/-l`, `--lr-color-brand-quiet`, `--lr-color-brand`, `--lr-color-border`,
`--lr-color-text-quiet`, `--lr-radius`.

**Optional peer deps:** `marked`, `dompurify` (both lazy-loaded via `markdown-loader.ts`'s
`loadMarkdownDeps()`, mirroring `chart-core-loader.ts`'s two-independent-optional-peers shape). Each half
is loaded and caught independently — a consumer who installs only `marked` and explicitly sets
`html-mode="trusted"` (so `dompurify` is never needed) is a valid, supported combination. Also `shiki`,
the same optional peer `<lr-code-block>` uses, for `highlightCode`'s fenced-block syntax
highlighting — independent of the `marked`/`dompurify` pair, and its absence never blocks rendering
(fenced blocks simply stay unhighlighted). The readonly `marked` property becomes available only
after that lazy load resolves; each instance owns its configuration. Call `renderMarkdown()` after
`marked.use(...)` to refresh content that is already shown.

```html
<lr-markdown
  content="# Report&#10;&#10;See the [setup guide](/docs/setup) for details."
  internal-link-prefix="/docs/"
></lr-markdown>
<script>
  document
    .querySelector("lr-markdown")
    .addEventListener("lr-link-click", (e) => {
      router.navigate(e.detail.href);
    });
</script>
```

Rendering never ships unsanitized or broken markup silently. If `marked` fails to load, or throws
while parsing malformed input, the component falls back to plain text (`white-space: pre-wrap`, no
HTML parsing at all — the raw `content` string itself) and fires `lr-render-error`. In the default
`html-mode="sanitize"`, an unavailable or failed `dompurify` peer takes that same fail-closed path:
the component never renders `marked`'s raw HTML output when sanitization was requested. Use
`html-mode="escape"` when authored raw HTML should remain visible as text, or
`html-mode="trusted"` only for content whose complete HTML output is already trusted. While the
optional peers are still resolving, the host carries `aria-busy="true"` (set/
cleared in `updated()` based on whether the deps have loaded) and shows the same plain-text fallback
rendering — there's no separate loading skeleton, since the un-rendered Markdown source is already
legible text in the meantime.

**One tab width for every code surface.** `--lr-code-block-tab-size` is deliberately the same
property name and default (`2`) that `<lr-code-block>` and `<lr-code-editor>` use, so a consumer sets
tab width once for every code surface in the app. It is declared as a `var()` fallback **at the point
of use, never on `:host`** — a `:host` declaration is re-stamped on every instance and shadows any
inherited value, so a page- or container-level declaration could never reach it. This element carries
its own copy of that fallback rather than inheriting `<lr-code-block>`'s because the two are
**sibling** custom elements, not ancestor and descendant: no single declaration inside one of them
can cover the other. The same value can still _look_ different between the two — a markdown code
block inherits `white-space: pre-wrap` while `<lr-code-block>` is `white-space: pre`, and tab stops
restart at the beginning of each visual line, so a wrapped line's tabs land differently.

**Known gotchas:**

- a malformed percent-escape or lone UTF-16 surrogate in a link's raw `href` makes the internal
  `encodeURI`-based validity guard throw, silently dropping just that anchor (the link text still
  renders, with no `href`) — mirrors `marked`'s own default `link()` renderer's defensive behavior.
- every rendered link/image `href`/`src` is additionally scheme-checked against the same allowlist
  `<lr-button>`/`<lr-card>` use for a navigation `href` (`http:`, `https:`, `blob:`, `mailto:`, and
  relative URLs — plus `data:` for images only), independently of `htmlMode` — `sanitize` and
  `escape` both reject a disallowed scheme (e.g. `javascript:`) by dropping the anchor/image and
  rendering only its text/alt content, exactly like the malformed-`href` case above; only
  `html-mode="trusted"` skips this check, consistent with its documented full bypass.
- `target` is not in DOMPurify's default attribute allowlist (unlike `part`/`rel`/`class`, which
  already are), so sanitization is called with `ADD_ATTR: ['target']` — without that, every rendered
  link's `target` would be silently stripped by sanitization even though the anchor itself survives.
- a fresh internal `marked.Marked()` instance (with a fresh renderer) is built on every parse so
  the renderer's `link()` override always closes over the _current_ `linkTarget`. The public
  `marked` parser is still shared: its current configured defaults are copied into that fresh
  instance on each pass, avoiding a stale closure while preserving `marked.use(...)` hooks and
  extensions.
- `internal-link-prefix` matching compares against the raw `href` _attribute_, not the resolved
  `.href` IDL property (always an absolute URL in the browser) — a prefix like `/docs/` matches a
  relative markdown link but would never match against the resolved property.
- rendered output goes through `unsafeHTML`; with `html-mode="trusted"` the component renders
  whatever HTML `marked` produces from `content` completely unsanitized, so untrusted `content`
  must never use trusted mode.

**Additional API surface:**

- `--lr-markdown-table-header-bg` — Background of every rendered `[part="table"]` header cell. Default: `var(--lr-color-brand-quiet)`.
- `--lr-markdown-highlight-accent-bg` — Accent highlight fill. Default: `var(--lr-color-brand-quiet)`.
- `--lr-markdown-highlight-success-bg` — Success highlight fill. Default: `var(--lr-color-success-quiet)`.
- `--lr-markdown-highlight-warning-bg` — Warning highlight fill. Default: `var(--lr-color-warning-quiet)`.
- `--lr-markdown-highlight-danger-bg` — Danger highlight fill. Default: `var(--lr-color-danger-quiet)`.
- `--lr-markdown-highlight-neutral-bg` — Neutral highlight fill. Default: `var(--lr-color-surface)`.
- `--lr-markdown-highlight-active-bg` — Active highlight fill. Default: `var(--lr-color-brand-quiet)`.
- `--lr-markdown-highlight-active-outline-color` — Active highlight outline. Default: `var(--lr-color-brand)`.

---

## `lr-markdown-core`

A build-lean sibling of `<lr-markdown>` above, for a consumer whose `languages` map already covers
every language it will ever render — mirrors `<lr-code-block-core>`'s relationship to
`<lr-code-block>`. Where `<lr-markdown>` unconditionally calls `loadShikiHighlighter()` — the
default ~200-language dynamic-import table loader, whose bundled lookup table a bundler can't
statically narrow away —
this component's own module never imports or calls that function at all; it only ever calls
`loadShikiHighlighterCore(languages)`, so a consumer importing this entry point instead of
`markdown.js` gets a build genuinely free of shiki's full language table.

Removing `content` clears the document and its empty-document tab stop, including while streaming.
The property keeps Lit's `null` readback after removal; an explicitly empty attribute remains an
empty string. Later source text renders normally.

A fenced code block whose language isn't a key in `languages` always renders the plain-text fallback
— there is no default/full-table highlighter here to fall back to, the same default (not degraded)
rendering path as `<lr-code-block-core>`'s identical contract. A block that _is_ highlighted follows the
page's resolved theme through the same `[part="content"][data-dark-theme="true"]` hook `<lr-markdown>`
documents above, painting each token from `--shiki-dark`/`--shiki-dark-bg` on a dark palette. Every other capability — GFM tables,
links, blockquotes, images, heading anchors, `getHeadingTree()`, `fragment`/`text-quote` anchor-target
support (`highlights`, `activeHighlightId`, `scrollToAnchor()`, the `lr-highlight-activate`/
`lr-text-select`/`lr-anchor-result` events), math via the optional `katex` peer, the sanitize/
`htmlMode`/streaming fallback matrix and known gotchas — is identical to `<lr-markdown>`; see that
section above for the full write-up of shared behavior.

**Properties:** `content: string = ''`, `tabSize: number = 4` (attribute `tab-size`) — the same
finite-integer-guarded leading-indentation expansion used by `<lr-markdown>`; finite values are
clamped to `[1, 32]` (`0` becomes `1`, `33` becomes `32`), and only non-finite values (`NaN`,
`Infinity`) fall back to `4`, independently of rendered code's
`--lr-code-block-tab-size`; `marked: LyraMarkedParser | undefined` (readonly, no attribute) — this
instance's isolated peer-neutral configurable parser; `htmlMode: 'sanitize' | 'escape' | 'trusted' =
'sanitize'` (attribute `html-mode`), `gfm: boolean = true`, `linkTarget: string | null = '_blank'` (attribute
`link-target`), `internalLinkPrefix: string = ''` (attribute `internal-link-prefix`),
`headingOffset: number = 0` (attribute `heading-offset`), `streaming: boolean = false` (reflected),
`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
block stays unhighlighted permanently. Each value is either an already-resolved grammar or a lazy
loader (`() => Promise<ShikiLanguageInput | { default: ShikiLanguageInput }>`, e.g.
`() => import('@shikijs/langs/bash')`) — called at most once per key, memoized, the first time a
fenced block actually requests that language, `headingAnchors: boolean = false` (attribute `heading-anchors`),
`math: boolean = false`, `maxHeight: string = ''` (attribute `max-height`) — same CSS-length scroll
cap on `[part="content"]` as `<lr-markdown>`'s own; plus the same inherited anchor-target properties as `<lr-markdown>`:
`highlights: readonly LyraHighlight[] = []` (attribute: false), `activeHighlightId: string | null = null`
(attribute `active-highlight-id`), `anchor: LyraAnchor | string | null = null` (attribute: false),
and `anchorKinds: readonly ('fragment' | 'text-quote')[] = ['fragment', 'text-quote']`.
The same 1,000,000-code-unit/20,000-node corpus ceiling, 4,096-code-unit quote-field ceiling,
4,000,000-code-unit work ceiling, 10,000-record admission ceiling, 1,000-candidate window, and
100-painted-highlight limit documented for `<lr-markdown>` apply here too, including active-first
retention from anywhere in the admitted snapshot.

**Methods:** `renderMarkdown(): void` — immediately reruns the current content through the parse,
sanitize, highlight, and fallback pipeline after changing this instance's `marked` configuration;
safely no-ops while the parser is unresolved. `refreshTheme(): void` re-reads the resolved theme
for syntax highlighting. `getHeadingTree()` — same contract as
`<lr-markdown>`'s own. `LyraMarkdownCore.getMarked(): Marked` and
`LyraMarkdownCore.updateAll(): void` provide the same variant-scoped compatibility-parser contract
as the full class; the core route exports its own `Marked` alias.

**Events:** `lr-link-click`, `lr-render-error`, `lr-highlight-activate`, `lr-text-select`,
`lr-anchor-result`, `lr-content-settled` — identical detail shapes to `<lr-markdown>`'s own.

**Slots:** none — content comes from the `content` property, not light-DOM children.

**CSS parts:** `anchor-live-region` (the aria-hidden, non-live shadow mirror of the latest
anchor-jump message), `content` (respects `max-height`), `heading`, `paragraph`, `list`,
`code-block`, `inline-code`, `link`, `table`, `blockquote`, `img`, `math` — identical to
`<lr-markdown>`'s own parts.

**Themeable custom properties:** identical to `<lr-markdown>`'s own tokens, including
`--lr-markdown-max-height` (default `none` — cap on `[part="content"]`'s block size; the
`maxHeight` property sets this token inline) and its code-surface tokens —
`--lr-markdown-code-bg` (default `var(--lr-color-brand-quiet)`, shared by inline `code` and the
fenced `code-block` surface), `--lr-markdown-code-padding`/`--lr-markdown-code-radius` (inline
`code` span padding/radius, defaulting to `var(--lr-size-0-125rem) var(--lr-size-0-3125rem)`/
`calc(var(--lr-radius) * 0.5)`), and `--lr-markdown-code-block-padding`/
`--lr-markdown-code-block-radius` (the fenced `code-block` surface's padding/radius, defaulting to
`var(--lr-space-s) var(--lr-space-m)`/`var(--lr-radius)`) — plus `--lr-code-block-tab-size` (default
`2` — tab width inside a rendered fenced or indented `code-block`), with exactly the mechanics
described under `<lr-markdown>` above: the same property name and default that
`<lr-code-block>`/`<lr-code-editor>` read, declared as a `var()` fallback at the point of use rather
than on `:host` so a page- or container-level value reaches it, and carried here in its own right
because this element is a **sibling** of `<lr-code-block>` rather than an ancestor of it. Markdown
code blocks wrap (`white-space: pre-wrap`) while `<lr-code-block>` does not, so the same tab width
can render differently on a wrapped line. `--lr-markdown-font-mono` is the monospace stack used by
rendered code and defaults to `var(--lr-font-mono)`.

**Optional peer deps:** `marked`, `dompurify` (both lazy-loaded, same as `<lr-markdown>`), `katex`
(for `math`). Does _not_ depend on the full `shiki` package's default entry point — only
`shiki/core`, `shiki/engine/oniguruma`, the binary `shiki/onig.wasm` asset (the default; select
`shiki/engine/javascript` instead via `setShikiCoreEngine('javascript')`), and
`shiki/themes/github-{light,dark}.mjs`, the same fine-grained subset `<lr-code-block-core>` depends
on.

````ts
import { html } from "lit";
import python from "shiki/langs/python.mjs";
import "@aceshooting/lyra-ui/components/conversation/markdown/markdown-core.js";

const view = html`<lr-markdown-core
  .content=${"# Report\n\n```python\nprint('hi')\n```\n\n```bash\necho hi\n```"}
  .languages=${{ python, bash: () => import("shiki/langs/bash.mjs") }}
></lr-markdown-core>`;
````

**Additional API surface:**

- `--lr-markdown-table-header-bg` — Background of every rendered `[part="table"]` header cell. Default: `var(--lr-color-brand-quiet)`.
- `--lr-markdown-highlight-accent-bg` — Accent highlight fill. Default: `var(--lr-color-brand-quiet)`.
- `--lr-markdown-highlight-success-bg` — Success highlight fill. Default: `var(--lr-color-success-quiet)`.
- `--lr-markdown-highlight-warning-bg` — Warning highlight fill. Default: `var(--lr-color-warning-quiet)`.
- `--lr-markdown-highlight-danger-bg` — Danger highlight fill. Default: `var(--lr-color-danger-quiet)`.
- `--lr-markdown-highlight-neutral-bg` — Neutral highlight fill. Default: `var(--lr-color-surface)`.
- `--lr-markdown-highlight-active-bg` — Active highlight fill. Default: `var(--lr-color-brand-quiet)`.
- `--lr-markdown-highlight-active-outline-color` — Active highlight outline. Default: `var(--lr-color-brand)`.

---

## `lr-chat-message`

A role-based message bubble _shell_ for a chat/agent conversation surface. It renders none of the
message content itself — the default slot carries whatever a consumer wants to display (plain text,
a `<lr-markdown>`, a custom template, anything) and this component only supplies the surrounding
chrome: alignment/coloring by `messageRole`, an avatar/badges header row, an optional collapse toggle, an
attachments strip, and a status-aware footer (a live-updating status dot + text, the formatted
`timestamp`, a built-in retry affordance for `status="failed"`, and an `actions` slot for everything
else). No built-in copy button is rendered — slot a copy control into `actions` and fire
`lr-copy` (fulfilled-only frozen `detail: { ok: true, text }`) from it if you want one (matching
`<lr-code-block>`'s copy-affordance contract for anything listening at the conversation-surface
level).

Compose `lr-copy-button` in `actions` with its `value` set to the intended message source. The shell
does not infer that source or write the clipboard itself; the composed control emits success only
after the write fulfills.

**Properties:**

- `messageRole: ChatMessageRole = 'assistant'` (`'user' | 'assistant' | 'system'`, attribute
  `message-role`, reflected) — identifies the author without colliding with the platform `role`
  attribute. The role-owning internal article receives the localized author name directly through
  `aria-label`; a host `aria-label` overrides it by attribute presence (including an explicitly
  empty override). Styling keys off the same reflected `message-role` host attribute; a bare `role="assistant"`
  is never an authoring API.
- `status: ChatMessageStatus = 'sent'` (`'sending' | 'sent' | 'failed' | 'streaming'`, reflected) —
  drives the footer's status dot/text, `status="failed"`'s danger treatment on the bubble, and the
  built-in retry button
- `timestamp?: LyraTimestamp` (`Date | string | number`, attribute: false) — normalizes through the
  ECMAScript TimeClip domain; invalid or throwing input is treated as unset (no timestamp rendered)
- `formatTimestamp?: (date: Date) => string` (attribute: false) — overrides the default
  `hour:minute` (`Intl.DateTimeFormat`, runtime locale) rendering of `timestamp`
- `collapsible: boolean = false` (reflected) — shows the built-in collapse/expand toggle in the header
- `collapsed: boolean = false` (reflected) — whether the message body is hidden; effective whenever
  set, independent of `collapsible` (which only controls whether the toggle button itself is
  rendered) — mirrors `lr-widget`'s identical `collapsible`/`collapsed` pair
- `attachmentsPosition: 'before'|'after' = 'after'` (attribute `attachments-position`) — places the
  `attachments` slot before or after the message body; both the visual and reading order follow it
- `actionsPosition: ChatMessageActionsPosition = 'inside'` (`'inside' | 'outside'`, attribute
  `actions-position`, reflected) — `'outside'` renders the `actions` slot's content as a sibling
  immediately after `[part="bubble"]` instead of nested inside `[part="footer"]`'s own
  padding/background box, for an action row that must sit visually outside the bubble's chrome
- `messageId: string = ''` (attribute `message-id`, reflected) — optional stable application id;
  included in `lr-message-retry` detail when the built-in retry control is activated

**Events:** `lr-message-retry` (`detail: { messageId?: string }`; fired by the built-in retry button,
only rendered when `status="failed"`). `lr-toggle-request` is cancelable and carries
`{ collapsed: boolean }`; preventing it vetoes the built-in collapse/expand transaction.
`lr-toggle` carries that same detail after the accepted state is committed.

**Slots:** default (the message body), `avatar` (an avatar/icon for the message author), `badges`
(small status/metric chips — e.g. token count, latency, model name — entirely app-supplied), `actions`
(action controls such as copy/retry, rendered at the end of the footer), `attachments` (file/image
attachment chips, rendered below the message body), `failure` (only meaningful while
`status="failed"`: host-supplied content — typically a `role="alert"` banner plus its own retry
control — that replaces the built-in status text, retry button, and live-region announcement
entirely; unset, `status="failed"` renders exactly as before)

**CSS parts:** `bubble`, `header` (hidden entirely when nothing is in it), `avatar`, `badges`,
`collapse-button` (only rendered when `collapsible`), `body` (hidden while `collapsed`),
`attachments`, `footer` (hidden entirely when nothing is in it), `status-indicator` (a small
decorative `aria-hidden` dot, absent while `status="sent"`), `status-text` (the visible text twin of
`status-indicator`), `timestamp`, `retry-button` (only rendered when `status="failed"` and the
`failure` slot is empty), `actions` (rendered inside the footer by default; a sibling immediately
after `bubble` when `actionsPosition="outside"`), `failure` (`display: contents` wrapper for the
`failure` slot; contributes no box when the slot is empty)

**Themeable custom properties:** `--lr-chat-message-max-width` (default `80%` — the bubble's max
inline size; component-specific, no shared width token exists), four role-scoped bubble color
properties:

- `--lr-chat-message-bubble-bg` (default `var(--lr-color-surface)`) — bubble fill for every role
  except `user`.
- `--lr-chat-message-bubble-color` (default `var(--lr-color-text)`) — bubble text color for those
  same roles.
- `--lr-chat-message-user-bubble-bg` (default `var(--lr-color-brand-quiet)`) — bubble fill for
  `message-role="user"`.
- `--lr-chat-message-user-bubble-color` (default `var(--lr-color-text)`) — bubble text color for
  `message-role="user"`.

Prefer these over re-pointing the shared token a default happens to reference. Overriding
`--lr-color-brand-quiet` on the host also retints `[part='collapse-button']:hover` within this same
component, and which shared token backs each role's fill is not a stable contract — it changed
between 4.x and 5.0.0, which silently turned one consumer's inner-surface scrim into the whole
bubble (near-black text on `rgba(0,0,0,0.22)`, visible only by eye). These four are that stable
contract.

Two matching geometry properties cover the bubble's box:

- `--lr-chat-message-bubble-padding` (default `var(--lr-space-m)`) — the bubble's padding.
- `--lr-chat-message-bubble-radius` (default `var(--lr-radius)`) — the bubble's corner radius.
  Bubble-only by design: `[part='collapse-button']` and `[part='retry-button']` keep reading the
  shared `--lr-radius`, so a rounder bubble never desyncs those controls from the rest of the
  library.

**Prefer these to a `::part(bubble)` padding/radius override.** A consumer `::part()` rule wins only
for the CSS properties it actually declares; changing padding or radius does not erase unrelated
role/status colors or borders. The named hooks are the stable, narrow geometry contract and can be
set once above a whole transcript. They are consumed as inline `var()` fallbacks rather than
declared on `:host`, so the host cannot shadow an inherited value.

Plus shared tokens `--lr-space-xs/-m`, `--lr-color-border`, `--lr-color-surface`,
`--lr-color-brand-quiet`, `--lr-color-brand`, `--lr-color-text-quiet`, `--lr-color-danger`,
`--lr-color-danger-quiet`, `--lr-radius`, `--lr-icon-button-size`, `--lr-focus-ring-*`,
`--lr-transition-fast`, and `--lr-transition-ambient` (default `1.8s ease-in-out`) — the
streaming-indicator pulse animation's cycle, the same shared compound token
`<lr-typing-indicator>` uses.

`[part=bubble]`'s background resolves through `--lr-color-surface`. If your own panel/container
background already maps to that same token, override `[part=bubble]`'s background explicitly (e.g.
via `::part(bubble)`) so message bubbles stay visually distinct from the surrounding panel.

> Retheming a bubble from outside `<lr-chat-message>` (e.g. per-thread or per-role colors)?
> Set `--lr-theme-*` on the ancestor wrapper, not `--lr-*` directly — see `llms/shared.md`'s
> "Theming and design tokens" section for why a `--lr-*` override on a wrapper only reaches that
> wrapper's _direct_ children, not a nested `<lr-*>` host's shadow DOM.

**Optional peer deps:** none. Internally renders a `<lr-live-region>` (a first-party sibling
component, auto-imported alongside this one, not an npm peer) for the status-transition
announcements described below.

```html
<lr-chat-message message-role="assistant" status="streaming">
  <span slot="avatar">🤖</span>
  <span slot="badges">gpt-5.4 · 1.2s</span>
  <lr-markdown content="Here's what I found…"></lr-markdown>
  <button slot="actions">Copy</button>
</lr-chat-message>
<script>
  document
    .querySelector("lr-chat-message")
    .addEventListener("lr-message-retry", () => resend());
</script>
```

Accessibility of `status`: the current status is always available as plain visible text
(`[part="status-text"]`), never color alone. A transition _to_ `"failed"`, or _from_ `"streaming"` to
`"sent"` (a stream finishing), is additionally announced through the internal `<lr-live-region>` —
`"failed"` announces assertively (`"Message failed to send."`), a streaming→sent completion announces
politely (`"Message complete."`) — so a screen-reader user not currently focused on this message
still learns about it. No other status transition is announced (e.g. `streaming`→`sending`, or
`sending`→`sent` without having passed through `streaming`, produce no announcement). This differs
from `<lr-typing-indicator>`'s deliberately simpler `role="status"` approach, appropriate there
since that component only ever announces once (its own mount); this component's `status` can flip
between several values across a single element's lifetime.

**Known gotchas:**

- mounting a message with `status="failed"` (or any other non-`"sent"` status) already set does
  **not** announce anything — only a genuine _later_ transition (`changed.get('status') !==
undefined`, i.e. not the very first update) triggers the live-region announcement.
- `lr-message-retry` carries `{ messageId?: string }`; the field is the component's `messageId` when set,
  and is omitted otherwise.
- the header/footer/avatar/badges/attachments/actions wrappers are shown/hidden via the `hidden`
  attribute, not conditional templating. Whether each slot currently has content is checked once via
  a light-DOM children scan on the very first update (`willUpdate`, gated on `!this.hasUpdated`) and
  thereafter only via each slot's own `slotchange` listener — content added directly with
  `appendChild` after first paint still triggers native `slotchange`, so this works transparently,
  but any code that manually re-parents already-slotted nodes without a real slot-assignment change
  won't refresh the corresponding wrapper's visibility.
- `messageRole` reflects as `message-role`, which is also the host selector used by component
  styling. Never use `[role="user"]` as author state.

**Additional API surface:**

- `--lr-chat-message-system-color` — System-message text color. Default: `var(--lr-color-text-quiet)`.
- `--lr-chat-message-streaming-border-color` — Streaming bubble border. Default: `var(--lr-color-brand)`.
- `--lr-chat-message-failed-border-color` — Failed bubble border. Default: `var(--lr-color-danger)`.
- `--lr-chat-message-failed-bg` — Failed bubble fill. Default: `var(--lr-color-danger-quiet)`.
- `--lr-chat-message-footer-color` — Default footer text. Default: `var(--lr-color-text-quiet)`.
- `--lr-chat-message-user-footer-color` — User-message footer text. Default: `var(--lr-color-text)`.
- `--lr-chat-message-failed-footer-color` — Failed-message footer text. Default: `var(--lr-color-danger)`.
- `--lr-chat-message-indicator-color` — Default status indicator. Default: `var(--lr-color-text-quiet)`.
- `--lr-chat-message-streaming-indicator-color` — Streaming indicator. Default: `var(--lr-color-brand)`.
- `--lr-chat-message-failed-indicator-color` — Failed indicator. Default: `var(--lr-color-danger)`.
- `--lr-chat-message-failed-status-color` — Failed status text. Default: `var(--lr-color-danger)`.

---

## `lr-typing-indicator`

A purely presentational "assistant is responding" presence cue — no events, no interactivity. A
consumer mounts it while a response is being generated and removes (or hides) it once real content
arrives. Three visual variants share one component rather than three separate tags, since callers
pick between them along a single axis (how the surrounding surface wants the cue to read) and
nothing else about the component differs: `dots` (default, three dots with a staggered bounce — the
classic "typing…" affordance for a standalone status line), `pulse` (a single breathing dot, a
quieter cue for a tight space, e.g. next to an avatar), `cursor` (a blinking vertical bar, meant to
sit inline at the tail end of streamed text still being appended to).

Removing `label` restores the localized thinking name while preserving an explicit host
`aria-label`. Later label assignments remain reactive.

`label-placement="after"` additionally renders `label` (or its localized "Thinking…" fallback)
visibly next to the animated shape, in a new `part="label"` element, mirroring `<lr-spinner>`'s own
`labelPlacement` vocabulary. The default, `"none"`, is unchanged from this component's
screen-reader-only rendering before this property existed: a single `.sr-only` text node, no
visible twin. That visible `part="label"` node is itself `aria-hidden="true"`: the host's own
`aria-label` already carries the identical string as the accessible name, so the visible copy is
never exposed as a second, redundant accessibility-tree node for the same text.

**Properties:**

- `shape: TypingIndicatorShape = 'dots'` (`'dots' | 'pulse' | 'cursor'`, reflected)
- `label: string = ''` — caller-supplied accessible name. Empty or whitespace-only values use the
  localized “Thinking…” fallback; an explicit host `aria-label`, including `aria-label=""`, wins.
  The status is not re-announced on every animation frame, only on mount and on later label changes
- `labelPlacement: TypingIndicatorLabelPlacement = 'none'` (`'none' | 'after'`, attribute
  `label-placement`, reflected) — where the accessible label renders. `'none'` (default) keeps
  `label` screen-reader-only, exactly as this component rendered before this property
  existed. `'after'` also renders it visibly next to the animated shape.
- `size: TypingIndicatorSize = 'm'` (reflected) — visual size on the library-wide ladder;
  `TypingIndicatorSize` is an alias of the shared `LyraSize`, so it accepts `2xs`/`xs`/`s`/`m`/`l`/
  `xl` plus the `small`/`medium`/`large` spellings of `s`/`m`/`l`. A presence cue has three usefully
  distinguishable sizes rather than six, so the ladder renders as three tiers: `2xs`/`xs`/`s`/
  `small` are compact (for dense layouts, e.g. inline with a message bubble), `m`/`medium` is the
  default standalone status-line size, and `l`/`large`/`xl` are roomy. Every accepted value matches a
  rule — none is silently inert

**Events:** none — purely presentational.

**Slots:** none.

**CSS parts:** `base` (the decorative, `aria-hidden`, wrapper around the animated shape), `dot`
(each of the three dots in the `dots` variant), `pulse` (the single pulsing dot in the `pulse`
variant), `cursor` (the blinking bar in the `cursor` variant), `label` (the visible, `aria-hidden`,
label, rendered only while `label-placement="after"`)

**Themeable custom properties:** `--lr-typing-dot-size` (default `var(--lr-space-s)`, i.e. `0.5rem`;
`0.375rem` on the compact tier, `var(--lr-space-m)` on the roomy one), `--lr-typing-gap` (default
`var(--lr-space-xs)`, i.e. `0.25rem`; `0.1875rem` compact, `var(--lr-space-s)` roomy),
`--lr-inline-cursor-width` (shared inline-cursor hook; default `var(--lr-size-0-125rem)`, compact
`0.09375rem`, roomy `0.1875rem`), `--lr-inline-cursor-height` (shared inline-cursor hook; default
`var(--lr-size-1em)`, unaffected by `size`),
`--lr-typing-dot-stagger-1` (default `600ms`, second dot), `--lr-typing-dot-stagger-2` (default
`1200ms`, third dot), and `--lr-typing-duration` (default `var(--lr-transition-ambient)`, i.e.
`1.8s ease-in-out`) — the compound duration/timing-function token every variant uses as its
animation cycle. `--lr-typing-duration` is a dedicated alias: it defaults to the library-wide
`--lr-transition-ambient` token (shared by every other ambient-looping component), but overriding
it retimes only this component, leaving `--lr-transition-ambient` itself — and anything else keyed
off it — untouched.

**Optional peer deps:** none.

```html
<lr-typing-indicator label="Assistant is responding…"></lr-typing-indicator>
<lr-typing-indicator
  label-placement="after"
  label="Assistant is responding…"
></lr-typing-indicator>
<lr-typing-indicator shape="pulse" size="s"></lr-typing-indicator>
<lr-typing-indicator shape="cursor"></lr-typing-indicator>
<lr-typing-indicator
  style="--lr-typing-duration: 900ms ease-in-out; --lr-typing-dot-stagger-1: 300ms; --lr-typing-dot-stagger-2: 600ms"
></lr-typing-indicator>
```

Accessibility: since this indicator typically mounts and unmounts around a real generation lifecycle
(appears when a response starts, disappears once one arrives) rather than emitting a stream of
updates of its own, it does **not** route through `<lr-live-region>`/the internal `Announcer` —
that machinery exists to coalesce many rapidly-changing announcements into one, and there is only
ever a single announcement here: the mount itself. `role="status"` plus an accessible name derived
from `label` is set both as `aria-label` on the host _and_ as a visually-hidden text node
(`.sr-only`) in the shadow tree, so the name survives even if only one of the two is picked up by a
given assistive-tech/browser pairing. The animated shape itself is `aria-hidden="true"` — it's
decorative; `label` is the entire accessible content, nothing narrates individual animation frames.

**Known gotchas:**

- under `prefers-reduced-motion: reduce`, every variant collapses to its plain, fully-visible resting
  state (`opacity: 1`, no transform, `animation: none !important`) rather than freezing on whatever
  frame the animation happened to be on — notably relevant for `cursor`, which would otherwise risk
  freezing on its invisible ("off") blink half.
- `--lr-typing-duration` (like the `--lr-transition-ambient` token it aliases by default) is a
  compound `duration timing-function` value and cannot be divided with `calc()`. When retiming it,
  override both stagger properties alongside it to preserve the default one-third/two-thirds dot
  phasing, as shown above.
- the compact tier (`2xs`/`xs`/`s`/`small`) shrinks the dot size, gap, and cursor width, but **not**
  `--lr-inline-cursor-height` (still `1em` at any size) — the cursor bar's height is meant to track
  surrounding text size via `1em`, not the component's own `size` property.
- the six-step ladder collapses onto three rendered tiers here, so `2xs` and `s` look identical, as
  do `l` and `xl`. That is deliberate: six distinguishable dot diameters do not exist inside a `1em`
  line box, and accepting a value no selector matches would leave it quietly rendering at the
  default tier.

---

## `lr-chat-composer`

The message input for a chat/agent conversation surface: an auto-resizing `<textarea>` plus a
built-in send/stop button. Deliberately no label/hint/error chrome — a composite chat-input
control, not a labeled form field; wrap it in your own layout for that context. **Form-associated**
via the shared `FormAssociated` mixin (same shape as
`<lr-date-input>`) — `name: string = ''`, `value: string = ''`, `disabled: boolean = false`
(reflected), `required: boolean = false` (reflected) are all inherited, along with
`defaultValue: string = ''`, `customError: string | null = null` (`custom-error`), readonly
`effectiveDisabled: boolean`, `form: HTMLFormElement | null = null`, readonly `labels: NodeList`,
`validity: ValidityState`, `validationMessage: string`, and `willValidate: boolean`, plus
`getForm()`, `checkValidity()`/`reportValidity()`, and `setCustomValidity()`, so it participates in
native `<form>` submission/validation/reset like any other text control.

The inner textarea mirrors `required` through native `required`/`aria-required`. Its
`aria-invalid` remains false until the textarea has been blurred, then follows the host's
`ElementInternals` validity as `value` or `required` changes. A native validation attempt also
reveals the invalid state, and `form.reset()` clears the touched presentation.

**Properties (own):**

- `placeholder: string = ''`
- `minRows: number = 1` (attribute `min-rows`) — floored to `1` at render time
- `maxRows: number = 8` (attribute `max-rows`) — floored to at least `minRows`
- `status: ChatComposerStatus = 'idle'` (reflected) — `'idle' | 'sending' | 'streaming'`; drives the
  built-in button's icon/label (send vs. stop) and whether Enter still submits. Invalid direct or
  attribute values normalize and reflect as `idle`.
- `frame: ChatComposerFrame = 'card'` (reflected) — container treatment, in the library-wide `frame`
  vocabulary (`'card' | 'plain'`; `ChatComposerFrame` is an alias of the shared `LyraFrame`).
  `'plain'` drops `[part="base"]`'s border, background, padding and corner radius so a composer
  docked inside a chat panel, dialog footer or toolbar that already draws its own border doesn't
  double it. Named `frame`, not `appearance`: `appearance` is the library's vocabulary for how a
  _control fills itself_, and one property name cannot mean both. The focus affordance is swapped,
  not dropped — see **Known gotchas**
- `actionsLayout: ChatComposerActionsLayout = 'inline'` (reflected, attribute `actions-layout`) —
  `'inline' | 'stacked'`. `'inline'` (the default) keeps today's single flex row. `'stacked'`
  arranges the `start` and `end` action slots as a compact one-column rail (`start` above `end`)
  beside a `textarea` that spans both rows — for a multi-row composer (a taller `min-rows`) where
  stretching the action buttons across the row's full height would otherwise look wrong. Layout
  only; slot content, empty-slot hiding and the built-in button are unchanged. Invalid direct or
  attribute values normalize and reflect as `'inline'`.
- `submitOnEnter: boolean = true` (reflected, attribute `submit-on-enter`) — when `false`, Enter
  always inserts a newline instead of submitting
- `submitDisabled: boolean = false` (reflected, attribute `submit-disabled`) — consumer-controlled
  validation gate; while idle, disables the built-in Send button and suppresses Enter/click
  submission without disabling the textarea or a busy-state Stop action
- `stoppable: boolean = true` (reflected) — when false, busy states keep a disabled Send button
  instead of exposing a Stop action
- `readOnly: boolean = false` (attribute `readonly`, reflected) — native read-only editing state;
  intrinsic required/length constraints are barred while set
- `minLength?: number` (attribute `minlength`) and `maxLength?: number` (attribute `maxlength`) —
  forwarded native text-length constraints; invalid/unset values impose no bound
- `accessibleLabel: string | null = null` (attribute `aria-label`) — names the internal textarea;
  wins over placeholder and the localized composer label
- `spellcheck: boolean = true` — forwarded to the internal `<textarea>`
- `autocapitalize: string = ''` — forwarded to the internal `<textarea>`; empty omits the attribute
- `autocorrect: boolean = true` — forwarded to the internal `<textarea>` and reflected canonically
  as `autocorrect="on"|"off"`; JavaScript writes also accept legacy `'off'`/`'false'` strings
- `wrap: 'hard' | 'soft' | 'off' = 'soft'`, `autocomplete: string = ''`, `inputMode: string = ''`
  (attribute `inputmode`), and `enterKeyHint: string = ''` (attribute `enterkeyhint`) — forwarded to
  the native textarea
- `input: HTMLTextAreaElement | null` — readonly reference to the rendered native textarea
- `selectionStart: number | null`, `selectionEnd: number | null`, and `selectionDirection:
'forward' | 'backward' | 'none' | null` — native selection getters/setters

**Methods (own):** `focus(options?)`, `blur()`, `select()`, `setSelectionRange()`, and
`setRangeText()` forward to the textarea; `click()` focuses it when the composer is not effectively
disabled. `setRangeText()` synchronizes reactive/form value and auto-sizing.
`checkValidity()`/`reportValidity()` remain inherited; `resetValidity()` clears consumer custom
validity and recomputes the current intrinsic constraints.

**Events:**

- `input` / `change` — one realm-correct native event relayed from the textarea per native edit or
  commit; `focus` / `blur` similarly preserve `relatedTarget`
- `lr-input` (`detail: { value }`) — fired on every user-driven edit of the textarea, not a
  programmatic `.value` assignment
- `lr-change` (`detail: { value }`) — paired with the native `change` event
- `lr-submit` (`detail: { value }`) — fired by Enter (per `submit-on-enter`) or the built-in
  button while `status="idle"` and `submitDisabled` is false. `detail.value` is always the exact, untrimmed current value;
  trimming is left to the consumer. Submitting does **not** clear `value`
- `lr-stop` (no detail) — fired by the built-in button while `status` is `"sending"` or
  `"streaming"`
- `lr-invalid` (no detail) — one bubbling/composed, cancelable alias when native validity fails;
  preventing it also prevents the native `invalid` event that produced it

**Slots:** `toolbar` (auxiliary controls, e.g. a model or provider picker, rendered inside the
frame above the chips tray and input row, sharing `[part="base"]`'s `:focus-within` affordance),
`start` (content before the textarea, e.g. an attach-file trigger button), `end` (overrides the
built-in send/stop button entirely when it has assigned content), `chips` (an attachment tray
rendered above the input row).

**CSS parts:** `base`, `toolbar`, `chips`, `row`, `start`, `textarea`, `end`, `send-glyph`,
`stop-glyph`, `action-button`

**Themeable custom properties:** `--lr-chat-composer-busy-bg` (default `var(--lr-color-text-quiet)`)
— `[part="action-button"]`'s background while `status` is `"sending"` or `"streaming"` (the busy/stop
treatment). Scoped separately from the shared `--lr-color-text-quiet` token, which
`[part="textarea"]`'s placeholder color also reads — overriding this cssprop recolors only the busy
button, not the placeholder too (the same shared-token-collision fix `<lr-chat-message>`'s own
user-bubble background pair documents). `--lr-chat-composer-background` (default
`var(--lr-color-surface)`), `--lr-chat-composer-border-color` (default `var(--lr-color-border)`) and
`--lr-chat-composer-radius` (default `var(--lr-radius)`) retune `[part="base"]`'s card chrome so a
composer docked into a themed panel can match it, with no `::part(base)` override. `--lr-chat-composer-padding`
(default `var(--lr-space-s)`) and `--lr-chat-composer-gap` (default `var(--lr-space-xs)`) retune
`[part="base"]`'s padding and the row gap between its stacked `toolbar`/`chips`/`row` sections; like
the chrome hooks above, `frame="plain"` still zeroes the padding. `--lr-chat-composer-focus-shadow`
(default `inset 0 calc(-1 * var(--lr-focus-ring-width)) 0 0 var(--lr-focus-ring-color)`) is the
`frame="plain"` focus underline painted on `[part="base"]:focus-within` — override it to reshape the
underline, or set it to `none` to cede focus chrome entirely to a wrapper you draw yourself. The
`:focus-within` border keeps its `--lr-color-brand` shift — that is state paint, not card chrome —
and `frame="plain"` still removes the border, radius and fill outright. Plus shared tokens
`--lr-space-xs`, `--lr-space-s`,
`--lr-color-border`, `--lr-color-surface`, `--lr-color-brand`, `--lr-color-on-brand`,
`--lr-color-text-quiet`, `--lr-radius`, `--lr-icon-button-size`, `--lr-transition-fast`,
`--lr-opacity-disabled`, `--lr-focus-ring-width`, `--lr-focus-ring-color`, `--lr-focus-ring-offset`.

**Optional peer deps:** none.

```html
<lr-chat-composer
  id="composer"
  name="message"
  placeholder="Message the assistant…"
  min-rows="1"
  max-rows="8"
></lr-chat-composer>
<script type="module">
  const composer = document.getElementById("composer");
  composer.addEventListener("lr-submit", (e) => {
    sendMessage(e.detail.value);
    composer.value = ""; // the composer never clears itself
    composer.status = "sending";
  });
  composer.addEventListener("lr-stop", () => stopGeneration());
</script>
```

Auto-resize (`resizeTextarea()`) reads the textarea's own _computed_ line-height/padding/border at
call time rather than assuming a fixed px-per-row constant, so it stays correct under a consumer's
own font-size/line-height overrides; it grows between `min-rows` and `max-rows`, then switches to
internal scrolling (`overflow-y: auto`) past `max-rows`. A `ResizeObserver` on the textarea itself
also re-runs this fit (one animation frame later, to avoid a `ResizeObserver`-loop console error)
whenever the textarea's own _width_ changes — a sidebar collapsing, a responsive breakpoint, a
window resize — even though `value`/`min-rows`/`max-rows` never did, since the same text now wraps
across a different number of lines. Enter-to-send only fires while
`submit-on-enter` is `true` (the default): plain Enter submits and prevents the default newline;
Shift+Enter always inserts a newline regardless of `submit-on-enter`; an IME composition step
(checked via `isComposing`, with `keyCode === 229` as a defense-in-depth fallback for browsers that
report `isComposing` inconsistently) is never treated as a submit trigger; and while `status` isn't
`"idle"`, Enter is left alone to insert a newline instead of resubmitting — the textarea itself is
**not** auto-disabled during `sending`/`streaming`, so a user can keep composing their next message
while a previous one is in flight. While idle, `submitDisabled` suppresses Enter/click submission
and disables only the built-in Send button; editing and busy-state Stop behavior remain available.

**Known gotchas:**

- `lr-submit` never clears `value` — the consumer must clear it once a submission is actually
  accepted, so a failed send can leave the text in place for retry.
- While `status !== 'idle'`, only the built-in button's behavior changes (it emits `lr-stop`
  instead of `lr-submit`); the textarea keeps accepting input and Enter keeps inserting newlines
  rather than being blocked.
- Auto-resize requires a concrete, unitless `line-height` on the textarea (the component sets
  `line-height: 1.5` in its own styles) — the UA default of `normal` has no single resolved px
  figure to measure rows against, so overriding `line-height` to a keyword breaks row sizing.
- The `end` slot fully replaces the built-in action button rather than rendering alongside it —
  once it has assigned content, the library's send/stop icon, its `aria-label`, and its
  `status`-driven busy styling all disappear, so a custom end control needs its own send/stop
  handling.
- `[part="toolbar"]`/`[part="chips"]`/`[part="start"]` are hidden via a JS-tracked `[hidden]`
  attribute rather than a CSS `:empty` selector, because each always contains a literal `<slot>`
  child regardless of assigned content.
- Under `frame="card"` the only focus affordance is a border-color shift on `[part="base"]`
  (the internal `<textarea>` sets `outline: none`). `frame="plain"` removes that border, so it
  swaps in a different affordance rather than losing focus visibility: an underline across the whole
  input row, drawn as an inset `box-shadow` from `--lr-focus-ring-width`/`--lr-focus-ring-color`,
  reachable as one unit through `--lr-chat-composer-focus-shadow`, so it costs no layout. If you
  restyle `[part="base"]` under `plain` and want to draw your own focus cue instead (e.g. on a
  wrapper you place the composer inside), set `--lr-chat-composer-focus-shadow: none` rather than
  fighting the default with a higher-specificity override.
- `actions-layout="stacked"` only changes `[part="row"]`'s layout (a CSS grid instead of a flex
  row); it does not change which slot content is hidden or when the built-in button replaces
  `end`.

---

## `lr-stream-status`

A compact status indicator for a single streaming connection (SSE, WebSocket, long-poll, …), with
built-in heartbeat-aware stall detection. First-party invention (no Web Awesome equivalent). The
host drives `connectionState` for `idle`/`connecting`/`streaming`, and calls the imperative
`recordActivity()` method on every _semantic_ frame received while streaming — a real content
chunk, never a transport-level keep-alive ping. This component has no payload-inspection logic of
its own: "ignore heartbeats" is entirely call-site discipline, which is exactly why a connection
that's only sending keep-alives (no real content) for longer than `stall-threshold-ms` correctly
reads as stalled.

**Properties:**

- `connectionState: StreamConnectionState = 'idle'` (attribute `connection-state`, reflected) —
  host-owned transport state (`'idle' | 'connecting' | 'streaming'`). Invalid attribute or property
  writes normalize to `idle`.
- `phase: LyraStreamPhase` (readonly) — effective state: `connectionState`, or component-owned
  `'stalled'` while an active stream has exceeded its inactivity threshold
- `stallThresholdMs: number = 10000` (attribute `stall-threshold-ms`) — how long `phase` may stay
  `'streaming'` with no `recordActivity()` call before the component auto-transitions to
  `'stalled'`. A non-finite or `<= 0` value disables the stall timer entirely (arming becomes a
  no-op, so the phase will never auto-stall). Changing this value while already `'streaming'`
  re-arms the timer immediately against the new value, rather than waiting for the next
  `recordActivity()` call or phase change.

**Methods:**

- `recordActivity(): void` — call on every semantic (non-heartbeat) frame received while
  streaming.
  - While `phase === 'streaming'`: (re)arms the stall timer, pushing the stall deadline
    `stallThresholdMs` further out.
  - While `phase === 'stalled'`: recovers — the effective phase becomes `'streaming'` again (firing
    `lr-recover` and arming the timer fresh, via the same transition handling a direct host
    transport transition would also go through).
  - While `phase` is `'idle'` or `'connecting'`: a no-op. Safe to call defensively before formally
    flipping to `'streaming'`; it never throws or starts a timer early.
- `markStalled(): void` — installs the component-owned stalled override for an active streaming
  connection; no-op in other transport states or when already stalled

**Events:** `lr-stall` (`detail: null`) — fires whenever the effective phase transitions into
`'stalled'`, whether timer-driven or via `markStalled()`. `lr-recover` (`detail: null`) — fires
whenever the effective phase transitions out of `'stalled'`, whether via `recordActivity()` or a
host transport transition. Neither fires for a same-value
reassignment, and neither fires for whatever phase the element happens to _mount_ with — only a
later change counts as a transition.

**Slots:** default (custom copy shown only while the readonly `phase` is `'stalled'`, e.g. "Taking longer than
usual…" — falls back to a built-in default message when nothing is slotted), `actions` (a
stop/retry button row; always present in the template regardless of `phase` — its wrapper's
visibility is driven purely by whether anything is slotted into it, not by `phase`)

**CSS parts:** `base`, `indicator`, `phase` (persistent localized effective-state text), `message`,
`actions`

**Themeable custom properties:** shared tokens only — `--lr-color-text-quiet` (idle dot color),
`--lr-color-brand` (connecting/streaming dot color), `--lr-color-warning` (stalled dot color,
message text color, stalled border), `--lr-color-warning-quiet` (stalled background tint),
`--lr-space-s` / `--lr-space-xs` (base gap, stalled padding, actions gap), `--lr-radius`
(base corner radius), `--lr-transition-base` (background/border-color transitions and the
dot's color/opacity transitions), and `--lr-transition-ambient` (the streaming pulse cycle).
The phase defaults flow through `--lr-stream-status-dot-color` and
`--lr-stream-status-dot-opacity`; setting either custom property on the element or an ancestor
wins through the shadow cascade and is the supported per-instance override. The stalled row's own
longhands are indirected the same way: `--lr-stream-status-stalled-bg` (falls back to
`--lr-color-warning-quiet`) and `--lr-stream-status-stalled-border-color` (falls back to
`--lr-color-warning`) retheme the `base` part's background/border while stalled, and
`--lr-stream-status-message-color` (also falling back to `--lr-color-warning`) rethemes both the
`phase` and `message` parts' stalled text color independently of the border — the text and border
currently share a default value but are separate hooks, so overriding one never moves the other.

**Optional peer deps:** none.

```html
<lr-stream-status connection-state="streaming" stall-threshold-ms="8000">
  <span slot="actions"><button>Stop</button></span>
</lr-stream-status>
```

```ts
const status = document.querySelector("lr-stream-status")!;
status.addEventListener("lr-stall", () => console.warn("stream stalled"));
status.addEventListener("lr-recover", () => console.info("stream recovered"));

// on every real content chunk from the transport (never on a keep-alive ping):
status.recordActivity();
```

Internally, the inactivity timer runs only while `phase === 'streaming'`. It's (re)armed whenever
`connectionState` transitions to `'streaming'` (or `recordActivity()` recovers from
`'stalled'`) and on every subsequent `recordActivity()` call while already streaming; it's disarmed
the instant the effective phase becomes anything else, including a host-driven transport transition away from
`'streaming'` — so a stale timer can never fire a stall transition after the host has already moved
on. Phase transitions into/out of `'stalled'` are announced through an internal
`<lr-live-region>` rather than a hand-rolled `aria-live` region: entering `'stalled'` announces
"Connection stalled." with `mode="assertive"` (a stall can need the user's attention before they
give up and navigate away). Leaving `'stalled'` always announces with `mode="polite"` (good news
doesn't need to interrupt), but the _wording_ depends on the destination phase: "Connection
restored." only when leaving `'stalled'` for `'streaming'` (a genuine recovery, typically via
`recordActivity()`); a neutral "No longer stalled." when the destination is `'idle'`/`'connecting'`
instead (the host gave up on the stream, which is not the same thing as it recovering — a
screen-reader user must not be told the opposite of what a sighted user sees). Calling
`recordActivity()` itself never announces anything, no
matter how often the host calls it — only the phase _transition_ announces, exactly once. The
decorative indicator dot is `aria-hidden` (a color/motion cue only) and only pulses while
`connection-state="streaming"` and not stalled; `'stalled'` is styled as a warning tone, not danger, since a stall is usually
recoverable — a host that wants to escalate after N stalls can scope its own CSS off
the `lr-stall` event, or stop rendering this component and show its own danger-styled error state
instead. The pulse animation is suppressed under `prefers-reduced-motion: reduce`.

**Known gotchas:**

- `recordActivity()` is a plain instance method, not a reactive property — there's nothing to bind
  to in a template; call it directly from streaming/application code on every real chunk received.
- Never call `recordActivity()` for a heartbeat/keep-alive ping. This component has no
  payload-inspection logic of its own, so a connection that's only sending pings (no real content)
  for longer than `stall-threshold-ms` is _supposed_ to read as stalled — that's the entire
  point of the API.
- Setting `stallThresholdMs` to `0`, a negative number, or a non-finite value disables the stall
  timer outright; the component stays `'streaming'` until the host changes `connectionState` or
  explicitly calls `markStalled()`.
- `phase` is readonly. Call `markStalled()` for a semantic stall detected outside the inactivity
  timer; writing an own `phase` property is unsupported and cannot replace component-owned state.
- reconnecting the element while still `phase === 'streaming'` (e.g. a drag-and-drop reparent that
  keeps the same instance) automatically re-arms the stall timer in `connectedCallback` —
  `disconnectedCallback` always disarms it, and disconnect/reconnect fire back-to-back with no
  `updated()` cycle in between, so nothing else would otherwise notice.
- The `actions` slot's wrapper is always present in the DOM and toggled with the `hidden` attribute
  based on slotted content, not gated by `phase` — content placed there is visible regardless of
  the current phase.

---

## `lr-conversation-item`

A selectable row representing one chat session in a history sidebar list. Usable standalone or as the
`renderItem()` payload of `<lr-virtual-list>`; has no dependency on that (or any) other component.
First-party invention (no Web Awesome equivalent).

Inline rename keeps IME composition keys in the editor; ordinary Enter commits and Escape cancels
after composition.

**Properties:**

- `conversationId: string = ''` (attribute `conversation-id`) — stable domain identity carried by
  both selection and rename details. Native `id` remains ordinary document/CSS/ARIA identity.
- `label: string = ''` — the session's visible label. Falls back to "Untitled conversation" when
  empty (display only — the property itself is never mutated by that fallback). Native `title`
  remains available for tooltip semantics.
- `excerpt: string = ''` — a short preview snippet of the last message. Omit for no excerpt line.
  Ignored entirely once the `excerpt` slot has assigned content.
- `timestamp?: LyraTimestamp` (attribute: false) — accepts a `Date`, ISO/date string, or epoch-ms
  number; invalid and TimeClip-out-of-range input is treated as unset (no `<time>` rendered).
- `formatTimestamp?: (date: Date) => string` (attribute: false) — overrides the default absolute-time
  rendering (clock time for same-day timestamps, otherwise a calendar date). Not a fuzzy "2 hours ago"
  relative string — bucketed relative grouping is a list-level concern, not this row's job.
- `active: boolean = false` (reflected) — whether this is the currently-selected/open session; drives
  the brand-quiet background treatment.
- `renamable: boolean = true` (reflected) — whether inline-rename is available at all. When `false`, the
  rename button never renders and the row can never enter its editing state; flipping it to `false`
  while a rename is already in progress cancels that edit (discards the draft, like Escape) rather
  than leaving it stranded and still committable.
- `compact: boolean = false` (reflected) — tighter row padding and gaps, for the dense history
  sidebars these rows usually render in (same convention as `lr-empty`'s `compact`). Tightens
  `[part='base']`'s padding to `var(--lr-space-xs) var(--lr-space-s)` and its gap to
  `var(--lr-space-2xs)`, and collapses `[part='content']`'s inter-line gap to `0`. Deliberately
  changes nothing else: it does **not** shrink `[part='rename-button']` below the shared
  `--lr-icon-button-size` target floor, hide the excerpt, or reduce the excerpt/timestamp font
  sizes — so a row carrying a rename button or slotted `actions` still floors at roughly that icon
  size plus the compact padding, while a row with `renamable=false` and no actions collapses much
  further.
- `spellcheck: boolean = true` — forwarded to the in-place rename `<input>`; `spellcheck="false"` is
  parsed as false (not Lit's default boolean-attribute behavior)
- `autocapitalize: string = ''` — forwarded to the in-place rename `<input>`; empty omits the attribute
- `autocorrect: boolean = true` — forwarded canonically as `autocorrect="on"|"off"`; JavaScript
  writes also accept legacy `'off'`/`'false'` strings and normalize reads to boolean.

**Methods:** `click()` activates the selectable row like its internal button; while an inline rename
is active, it forwards to the label input instead and does not re-select the conversation.

**Events:** `lr-select` (`detail: { conversationId }`; fires from the selectable region on click or
Enter/Space while not renaming), `lr-rename` (`detail: { conversationId, label }`; a controlled
rename request that never mutates `label`, and is omitted for an empty or unchanged trimmed draft),
plus bubbling/composed `blur` and `focus` with `null` detail relayed from the rename input.

**Slots:**

- `actions` — overflow/icon-button controls rendered at the trailing edge of the row (e.g. a
  pin/delete control); only visually shown once it actually has assigned elements. The only slot that
  may hold focusable content.
- `start` — non-interactive leading content (avatar, purpose icon, status dot), rendered inside the
  selectable region before the label/excerpt content.
- `content` — replaces the built-in label + excerpt + meta content area with host-supplied
  non-interactive row content.
- `excerpt` — full override of the excerpt presentation (e.g. a search-hit snippet with `<mark>`);
  wins over the `excerpt` property whenever it has assigned content.
- `meta` — small, non-focusable structured fields below the label/excerpt (a day label, cost, request
  count); entirely app-supplied, this component computes none of it.

`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`),
`select-button`, `start`, `content`, `label`, `label-input`, `rename-button`, `excerpt`, `meta`, `timestamp`,
`actions`

**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']`
while `active`. Both are declared as inline `var()` fallbacks at the point of use and never on
`:host`, so either can be set on the element _or on any ancestor_ (a thread-list wrapper, a page
theme layer); `::part(base)[active]` is not valid CSS — Shadow Parts forbids an attribute selector
after `::part()` — so the only previous lever was overriding the library-wide `--lr-color-brand-quiet`
token and repainting everything else reading it. Unset, each falls back to exactly the token its rule
used before.

**These two are a contrast-sensitive pair — override them together, never one alone.** The
`-active-color` hook exists precisely because the quiet text tone only reaches about 4.25:1 against
the default active background; keep any override at 4.5:1 or better against it. And note that
`[part='label']` is _not_ restyled by the pair — it keeps `--lr-color-text` regardless — so a dark
custom active background needs its own label color set alongside them, or the label drops below
contrast while the excerpt stays legible.

`--lr-conversation-item-active-indicator-color` (default `var(--lr-color-brand)`) controls the
decorative `active-indicator` part's color. `--lr-conversation-item-active-indicator-width`
(default `var(--lr-size-2px)`) controls its inline width. `--lr-conversation-item-active-indicator-inset-inline`
(default `0 auto`) controls its logical inline insets; set `auto 0` to move the indicator to
inline-end. The indicator is `aria-hidden`, occupies the full row block-size, and is absent while
the row is inactive.

`--lr-conversation-item-compact-padding` (default `var(--lr-space-xs) var(--lr-space-s)`) —
`[part='base']`'s padding while `compact`. `--lr-conversation-item-compact-gap` (default
`var(--lr-space-2xs)`) — `[part='base']`'s gap while `compact`. Like the active-state pair, both are
inline `var()` fallbacks at the point of use and never declared on `:host`, so a surrounding list can
retune every row at once from an ancestor. `[part='content']`'s gap collapses to a flat `0` under
`compact` with no hatch of its own — there is no smaller step left to retune to. `:host([compact])
[part='base']` is ordered _before_ `:host([active]) [part='base']` (equal specificity), so a row that
is both compact and active keeps the active background and the promoted excerpt/timestamp contrast.

`--lr-conversation-item-align` (default `flex-start`) controls the cross-axis `align-items` of both
`[part='base']` and `[part='select-button']`. `flex-start` — today's only behavior — suits the
common multi-line row (a title plus an `excerpt`): centering that layout against a single-line
trailing action would misalign the title's own baseline. Set it to `center` for a row that is
reliably single-line (no excerpt, no wrapping title) alongside a taller trailing action (e.g. an
`actions` control), where centered alignment reads better. It is not the default because switching
it would misalign every existing multi-line row.

Plus shared tokens — `--lr-space-xs/-s/-m`, `--lr-radius`,
`--lr-transition-fast`, `--lr-color-text/-text-quiet/-brand/-brand-quiet/-surface`,
`--lr-focus-ring-width/-color/-offset`, `--lr-icon-button-size`.

**Optional peer deps:** none.

```html
<lr-conversation-item
  conversation-id="sess_123"
  label="Q3 roadmap planning"
  excerpt="Let's revisit the timeline for the launch…"
>
  <button slot="actions" aria-label="Delete conversation">✕</button>
</lr-conversation-item>
<script type="module">
  const item = document.querySelector("lr-conversation-item");
  item.timestamp = session.updatedAt;
  item.active = session.id === currentSessionId;
  item.addEventListener("lr-select", (e) => openSession(e.detail.conversationId));
  item.addEventListener("lr-rename", (e) => renameSession(e.detail.conversationId, e.detail.label));
</script>
```

`role="button"` lives on `[part="select-button"]`, so the row has
valid semantics both standalone and inside a larger history-list layout: it activates one current
session rather than being a listbox option, so it requires no particular owner role. Selection is
conveyed via `aria-current="true"` while `active`, not `aria-selected`. Because `role="button"`
forbids focusable descendants (axe-core's `nested-interactive` rule), the rename button and the
`actions` slot are rendered as DOM _siblings_ of `[part="select-button"]` inside `[part="base"]`, not nested
inside it — the same constraint the in-place rename `<input>` runs into one level deeper, which is
why `[part="select-button"]` sheds its `role`/`tabindex`/`aria-current`/`aria-label` entirely for the
duration of an edit rather than just visually swapping content (a row mid-edit _is_ a text field).

**Known gotchas:**

- Both `lr-select` and `lr-rename` carry the stable `conversationId`; do not overload native `id`
  as domain identity.
- Renaming is a controlled interaction: committing `lr-rename` never updates `label` locally: the
  consumer must apply the new label once it's actually persisted.
- An empty or unchanged (post-trim) rename draft is treated as an implicit cancel — no `lr-rename`
  fires, and the row silently reverts to showing `label`.
- Rename is triggered only by the dedicated pencil-icon button, never a double-click on the label —
  double-click has no keyboard/screen-reader equivalent and would also swallow the row's own
  single-click `lr-select`.
- While renaming, `[part="select-button"]` has no `role`/`tabindex`/`aria-current`/`aria-label` at all — a
  screen reader briefly stops announcing it as a button for the duration of the edit.
- Setting `renamable = false` mid-rename silently discards the in-progress draft (no `lr-rename`
  fires) — a consumer toggling `renamable` off (e.g. in response to some other row entering rename
  mode) should not expect the previous edit to be committed first.
- `compact` is a spacing knob only — it never lowers the rename button's `--lr-icon-button-size`
  floor. A compact row that still shows a rename button (or slotted `actions` at the same floor)
  therefore bottoms out at roughly that icon size plus the compact padding, not at the text height.
  Lowering `--lr-icon-button-size` at an ancestor is the explicit, informed opt-out of the
  target-size floor; a density flag deliberately won't do it silently on your behalf.

---

## `lr-model-select`

A provider/model picker that renders as a closed dropdown when a fixed `catalog` is available, or as a
filterable free-text combobox when it isn't (or when `allow-custom` explicitly permits typing something
outside the catalog). Form-associated (hand-rolled internals via `attachInternals()` directly, not the
shared `FormAssociated` mixin — same reasoning as `lr-combobox`/`lr-select`: see the shared-foundation
notes). Built on the same trigger-button/`aria-activedescendant` listbox technique `<lr-select>` uses
and the filter-as-you-type suggestion-popup technique `<lr-combobox>` uses, without composing either
element. First-party invention (no Web Awesome equivalent).
Session-history/autofill restoration synchronously restores the model id and form entry without
emitting `lr-change`.

Removing `label`, `hint`, or `error-text` clears that optional copy in both catalog and free-text
modes. Removed string properties retain `null` readback, and later assignments restore their
content.

Composing key events (`isComposing` or legacy `keyCode === 229`) remain with the catalog query or
custom-value editor: they do not navigate options, commit a selection or custom value, or close the
popup. Ordinary keyboard behavior resumes after composition.

When `catalog`/`allowCustom` replaces a focused trigger with the free-text input or vice versa,
focus follows the available replacement. If the new owner is disabled or inert, focus returns to
the available element that led into the picker, or to the stable `form-control` owner when no
return target exists. This repair emits no action/value events and never overrides a newer external
focus move.

**Exported types:**

- `LyraCatalogEntry { id: string; label: string; disabled?: boolean }` — the shared minimum row
  vocabulary. `disabled` marks a row non-actionable: `aria-disabled="true"` replaces its
  selected/active affordances, activating it (click or keyboard) commits nothing and changes no
  state, and arrow-key/Home/End active-descendant navigation steps past it instead of landing on
  it. Omitted or `false` renders the row exactly as before this field existed.
- `LyraCatalog<T extends LyraCatalogEntry = LyraCatalogEntry> = readonly string[] | readonly T[]`
  — a homogeneous catalog shared by model-select, voice-picker, and composed controls. String
  shorthand uses the same string for both id and label; readonly tuples/arrays are accepted. Ids
  must be nonempty and unique and object rows require a nonblank string label: malformed rows and
  later duplicates are omitted first-wins before mode selection, rendering, focus reconciliation,
  selection, or preview lookup.
- `LyraModelCatalogEntry extends LyraCatalogEntry { icon?: string }` — one model row. An
  optional literal `icon` (for example, an emoji) renders decoratively before `label`; it does not
  change the option's accessible name.

**Properties:**

- `provider: string = ''` — informational only (e.g. `'ollama'`); rendered as a small leading badge.
- `catalog?: LyraCatalog<LyraModelCatalogEntry>` (attribute: false) — the full model list. Omit (or
  leave empty) to fall back to plain free-text entry. Ids use the shared unique, nonempty,
  first-wins catalog rule above. The array is clone-owned, bounded, and frozen; reassign a new
  catalog array after changing its rows.
- `allowCustom: boolean = false` (attribute `allow-custom`, reflected) — let the user type/commit a
  value that isn't in `catalog`, even when `catalog` is non-empty.
- `label: string = ''` — optional visible title above the control, rendered alongside the `label`
  slot in a `[part="form-control-label"]` `<label>` paired with the active control's id. A host
  `aria-label` remains the authoritative override by presence; otherwise either visible-label
  source names the control through the native label association. Leaving both sources empty keeps
  the original `aria-label || placeholder || 'Model'` accessible-name chain untouched.
- `hint: string = ''` — hint text below the field. Unset (the default): no hint chrome renders.
- `errorText: string = ''` (attribute `error-text`) — error text below the field (overridden by
  slotted `error` content). Unset (the default): no error chrome renders.
- `placeholder: string = ''`
- `spellcheck: boolean = true` — forwarded to the free-text mode's native `<input>`; no effect in
  closed-dropdown mode (no native text input there). `spellcheck="false"` is parsed as `false` (a
  custom converter, not Lit's presence-based `type: Boolean`, so the literal attribute string is
  honored — matches `<lr-textarea>`/`<lr-date-input>`).
- `autocapitalize: string = ''` — forwarded to the free-text mode's native `<input>`; empty omits
  the attribute.
- `autoCorrect: string = ''` (attribute `autocorrect`) — forwarded to the free-text mode's native
  `<input>`'s own `autocorrect` (Safari/WebKit-specific); empty omits the attribute. Named
  `autoCorrect` in JS purely to dodge a `lib.dom.d.ts` typing collision — the wire attribute is
  still plain `autocorrect`.
- `autocomplete: string = 'off'`, `inputMode: string = ''` (attribute `inputmode`), and
  `enterKeyHint: string = ''` (attribute `enterkeyhint`) — forwarded to the free-text input;
  they have no effect in closed-dropdown mode
- `name: string = ''` (reflected)
- `disabled: boolean = false` (reflected)
- `readonly: boolean = false` (reflected) — prevents user typing and catalog
  commits while retaining focus, popup navigation, selection/copy, submission/reset, and programmatic
  writes.
- `required: boolean = false` (reflected — enforced via `internals.setValidity()`)
- `open: boolean = false` (reflected)
- `size: LyraSize = 'm'` (reflected) — visual size on the library-wide ladder: `2xs`/`xs`/`s`/`m`/
  `l`/`xl`, plus `small`/`medium`/`large` as accepted spellings of `s`/`m`/`l`, so markup migrated
  from Web Awesome or Shoelace needs no attribute rewrite. It scales
  `[part="trigger"]`/`[part="combobox"]`'s padding/min-height/font-size through the shared
  `--lr-form-control-*` knobs, so a model select sits at the same height as the `lr-select`,
  `lr-input` or `lr-button` beside it in a toolbar row at every tier, plus `[part="expand-icon"]`'s
  box size (see the themeable custom properties below).
- `value: string` — getter/setter (hand-rolled, not the `FormAssociated` mixin); the current model id,
  `''` when nothing is selected. Writing it calls `internals.setFormValue()` synchronously. A named,
  untouched model-select contributes `''` to `FormData` instead of omitting its key.
- `defaultValue: string = ''` (attribute `value`, reflected) — the current reset default. The live
  `value` is non-reflecting and dirty, so changing the default/attribute cannot overwrite it until
  `form.reset()` restores the current default.
- `customError: string | null = null` (attribute `custom-error`) — reflected consumer validation
  message.
- `form: HTMLFormElement | null = null` — browser-resolved owner (and an assignable external owner);
  readonly `labels: NodeList`, `validity: ValidityState`, `validationMessage: string`,
  `willValidate: boolean`, and `effectiveDisabled: boolean` expose the native FACE state.
- `input: HTMLInputElement | null` — readonly native input reference in free-text mode; `null` in
  closed-dropdown mode and before render.
- `selectionStart: number | null`, `selectionEnd: number | null`, and `selectionDirection:
LyraModelSelectSelectionDirection | null` — native caret/selection state in free-text mode;
  getters return `null` and setters are inert when no text input is rendered.

**Methods:** `click()` (override) — forwards to whichever internal control the active mode renders,
since `HTMLElement.prototype.click()` is otherwise a no-op on a custom element with no native click
semantics of its own (mirrors `<lr-button>`'s identical host `click()` forwarding, so a generic
form-automation helper or another component calling `.click()` on the host actually opens the picker
instead of silently doing nothing). Closed-dropdown mode forwards a real `.click()` to the trigger
`<button>`, whose own `@click` handler opens it. Free-text mode forwards `.click()` to the combobox
`<input>`, then explicitly calls `.focus()`: unlike a genuine pointer click,
`HTMLElement.click()` never moves focus (that's a `mousedown` side effect the browser applies only
to real pointer interaction), and this mode's open behavior is wired to the input's `focus` event
(`onInputFocus`), not a `click` handler on the input itself.

`focus(options?)` and `blur()` forward to the active semantic control in either rendering mode.
If a catalog/`allowCustom` update replaces that control while it owns focus, focus follows from the
closed trigger to the free-text input (or back again). A newer external focus destination is never
overridden.

`select()` and `setSelectionRange()` forward to the native input in free-text mode.
`setRangeText()` applies the native range edit and silently synchronizes `value`, the form entry,
and validity; none of these editing methods has an effect in closed-dropdown mode or before render.

`getForm()` returns the browser-resolved owning form. `checkValidity()` / `reportValidity()` behave
as on any form-associated control.
`setCustomValidity(message: string)` is the standard channel for a server-side rejection ("that
model was retired by the provider") that no client-side constraint can express: a non-empty
`message` raises `customError` and becomes `validationMessage`, so the control fails
`checkValidity()`, blocks submission, and matches `:state(invalid)`; `''` clears it. Clearing
restores the control's own computed validity rather than forcing it valid — a `required` picker with
no value stays `valueMissing` — and the custom error survives every intrinsic recomputation in
between (each `value`/`required` change) and a `form.reset()`, matching a native control. The
message is caller-supplied content, used verbatim and never localized.

**Mode switching:** `closedMode` (private) is `true` whenever `normalizedCatalog.length > 0 &&
!allowCustom` — a non-empty `catalog` with `allowCustom` left `false` renders the closed dropdown
trigger-button UI (`[part="trigger"]`, `role="combobox"` on a `<button>`, no typing). Any other
combination (`catalog` empty/unset, or `allowCustom` true) renders the free-text `<input>` UI
(`[part="combobox"]`/`[part="combobox-input"]`) with live substring filtering against the catalog (id or
label, case-insensitive). The mode is re-evaluated on every render, so toggling `allowCustom` or clearing
`catalog` at runtime switches modes live, repositioning the shared `[part="listbox"]` popover against
whichever element is the active anchor. Replacing `catalog` while free-text mode remains open
refilters suggestions without erasing the user's current draft; controlled `value` changes and
actual mode switches still rebase the input to the committed value.

A `value` that isn't present in `catalog` (e.g. a model id saved from a provider whose live catalog has
since changed) is never silently dropped: it's appended to the rendered option list as a synthetic,
visually-distinct row (dashed border, italic label, "not in catalog" badge) computed fresh from
`catalog` + `value` on every access, without ever mutating the `catalog` property itself.

**Events:**

- `lr-change` (`detail: { value: string; inCatalog: boolean }` — fired when a value is selected
  from the listbox or committed in free-text mode; `inCatalog` reflects whether that value was
  actually present in `normalizedCatalog`, so a consumer can flag a freshly-typed custom value
  distinctly from a real catalog pick)
- `change` (`Event`, no detail) — an owner-realm native event fired on a committed value alongside
  `lr-change`, mirroring `<lr-select>`/`<lr-combobox>`'s value-change pair so native form bindings
  and framework `v-model` handlers behave consistently across the picker family.
- `input` — a payload-preserving owner-realm `InputEvent` for each free-text edit, and a plain
  owner-realm `Event` fired immediately before `change` when either mode commits a value.
- `blur` / `focus` (no detail) — one owner-realm native `FocusEvent` re-dispatched from the active
  control in either mode (the closed trigger button or free-text input), retaining `relatedTarget`
  and bubbling/composed unlike the shadow-internal original.
- `lr-invalid` (no detail) — the single bubbling/composed alias of a failed native validity check.

**Slots:** `label` (custom visible label content), `hint` (custom hint content), `error` (custom
error content).

**The required marker and barred validity.** With `required` set and either visible-label source
non-empty,
`[part="form-control-label"]` paints the library's shared required marker — the same `::after` rule
every labelled control in the library uses, so `--lr-form-control-required-content`,
`--lr-form-control-required-color` and `--lr-form-control-required-offset` retune or suppress it here
exactly as they do on `lr-input` (see `llms/shared.md` → "The required-field marker"). With no visible label there
is nothing to mark and no stray glyph is rendered. Correspondingly, while the picker is barred from
constraint validation — its own `disabled` or `readonly`, or an ancestor `<fieldset disabled>` — it
reports no violation and publishes neither `:state(invalid)` nor
`:state(user-invalid)`, matching native `:invalid`. `required`/`optional` keep publishing.

**CSS parts:** `form-control` (the complete label, control, hint, error, and listbox frame),
`form-control-label` (the `<label>` element containing the `label` property and slot), `trigger` (closed-dropdown mode's
`<button role="combobox">`, also its positioning anchor), `combobox` (free-text mode's input
container, also its positioning anchor), `combobox-input` (the free-text `<input>`),
`provider-badge` (the optional leading `provider` label), `listbox` (the options popover, shared by
both modes), `option`, `option-icon` (an object-shaped catalog row's optional decorative leading
icon), `option-label`, `option-badge` (the "not in catalog" badge on a synthetic stale-value row),
`empty` (the no-matching-models message), `expand-icon` (the dropdown chevron, present in both modes), `hint` (the hint
message), `error` (the error message)

**Themeable custom properties:** `--lr-model-select-trigger-padding` (default
`var(--lr-form-control-padding-block) var(--lr-form-control-padding-inline)`) —
`[part="trigger"]`/`[part="combobox"]`'s padding shorthand. `--lr-model-select-trigger-min-height`
(default `var(--lr-form-control-height)`) — their block-size floor, and
`--lr-model-select-trigger-height` (unset by default) — an _exact_ block size that both floors and
caps them, taking precedence over the floor, for pixel-matching a sibling field in the same toolbar
row. `--lr-model-select-font-size` (default `var(--lr-form-control-font-size)`) — their font size.
`--lr-model-select-trigger-padding`, `--lr-model-select-trigger-min-height` and
`--lr-model-select-font-size` are indirections onto the shared `--lr-form-control-*` scale rather
than literal values: the public property surface is unchanged, but the numbers come from the one
ladder every other control sizes against, so a tier is restated in exactly one place.
`--lr-model-select-expand-size` (default `var(--lr-size-1-75rem)`) — `[part="expand-icon"]`'s
decorative box size (clamped against `--lr-icon-button-size` via `min()`); this one is a glyph box
rather than a control metric, so the shared ladder has no equivalent and its per-tier values stay
local. `size` is the primary lever; override a cssprop directly only to retune a single element or
step outside the scale entirely. `--lr-model-select-gap` (default `var(--lr-space-xs)`) controls the
child gap in the trigger, combobox, and option rows; `--lr-model-select-radius` (default
`var(--lr-radius)`) controls the corner radius of the trigger, combobox, listbox, and option rows.
Both remain inheritable fallback arms, so set them on an ancestor to retheme a group without
changing unrelated controls. `--lr-model-select-trigger-border-color` (default
`var(--lr-color-border)`) and `--lr-model-select-trigger-fill` (default `var(--lr-color-surface)`)
control the trigger/combobox's resting border and background, independent of the open-state border
below. `--lr-model-select-open-border-color` (default `var(--lr-color-brand)`)
controls the trigger border while the listbox is open. A synthetic stale-value row has independent
`--lr-model-select-option-synthetic-border-style` (default `dashed`) and
`--lr-model-select-option-synthetic-border-color` (default `var(--lr-color-border)`) hooks.
`--lr-model-select-option-active-bg` (default `var(--lr-color-brand-quiet)`) — background of a
hovered or keyboard-active `[part="option"]` row; declared as a `var()` fallback at the point of
use, not on `:host`, so it isn't tied to `size`. The selected row
(`[part="option"][aria-selected="true"]`) has the matching set
`--lr-model-select-option-selected-bg` (default `transparent`),
`--lr-model-select-option-selected-border` and `--lr-model-select-option-selected-color` (both
`var(--lr-color-brand)`), and `--lr-model-select-option-selected-font-weight`
(`var(--lr-font-weight-semibold)`), all inline `var()` fallbacks so the selected row is rethemeable
without hijacking `--lr-color-brand`. `--lr-model-select-option-disabled-opacity` (default `0.5`)
— opacity of an option row whose catalog entry sets `disabled`. `--lr-model-select-max-inline-size` (default
`var(--lr-size-24rem)`) publishes the host's own width ceiling, which was previously a hard-wired
literal: set a length to retune it, or `none` to let the control fill its container the way
`lr-select` does. Like every other name here it is read as a `var()` fallback and never declared on
`:host`, so a value set on `:root` or any ancestor still reaches it. Plus shared tokens —
`--lr-space-xs/-s`, `--lr-color-border/-surface/-brand/-brand-quiet/-text-quiet`, `--lr-radius`,
`--lr-shadow`, `--lr-focus-ring-width/-color/-offset`, `--lr-icon-button-size`,
`--lr-transition-fast`, `--lr-opacity-disabled`.

The listbox is a floating surface and paints from the **shared overlay-surface family** (16.0.0):
`--lr-overlay-surface` (default `var(--lr-color-surface-overlay)`), `--lr-overlay-border` (default
`var(--lr-color-border)`) and `--lr-overlay-shadow-anchored` (default `var(--lr-shadow-m)`). None is
declared on `:host`, so one declaration on `:root` — or on any ancestor, to scope it — retints this
surface together with every other floating surface in the library. `--lr-overlay-radius` (default `var(--lr-radius)`) reaches it only as the middle arm of
`--lr-model-select-radius`, which still wins when set.

**Optional peer deps:** none.

```html
<lr-model-select provider="openai" value="gpt-4o" placeholder="Choose a model…"></lr-model-select>

<!-- No fixed catalog yet: falls back to free-text entry -->
<lr-model-select provider="ollama" placeholder="Type a model id…" allow-custom></lr-model-select>
<script type="module">
  const select = document.querySelector("lr-model-select");
  select.catalog = [
    { id: "gpt-4o", label: "GPT-4o", icon: "✦" },
    { id: "gpt-4o-mini", label: "GPT-4o mini" },
  ];
  select.addEventListener("lr-change", (e) => setModel(e.detail.value, e.detail.inCatalog));
</script>
```

**Known gotchas:**

- `catalog` must be homogeneous — an array of plain strings, or an array of `{ id, label, icon? }`
  objects, not a mix; `LyraCatalog<T>` is a union of two readonly array _types_, not an array of a
  union item type.
- The synthetic "not in catalog" row only ever appears when `catalog` is non-empty and `value` isn't one
  of its ids — with no `catalog` at all, there's no catalog list to diff `value` against, so no badge.
- `value`/form-association here is hand-rolled via `attachInternals()` directly, not the shared
  `FormAssociated` mixin — mirrors `lr-combobox`/`lr-select`'s identical divergence.
- `aria-invalid`/`data-invalid` only reflect once the control has been blurred (touched) at least once,
  matching `lr-select`'s identical pattern — validity styling never flashes on first render.
- In free-text mode, the input's displayed text is `query` only while `open`; while closed it shows the
  committed value's label — so setting `.value` programmatically doesn't require also touching the live
  typed text.
- `hint`/`errorText` mirror `<lr-select>`'s identical chrome, including the `aria-describedby` wiring
  to the rendered `hint`/`error` ids — set on whichever element (`trigger` or `combobox-input`) owns
  `role="combobox"` for the active mode.

---

## `lr-streaming-text`

A token-coalescing incremental text renderer for streaming assistant output, with an optional
blinking cursor and auto-detected Markdown rendering. First-party invention (no Web Awesome
equivalent). The host is expected to assign the _entire_ current text on every update to `content`,
not a delta — this component does no accumulation or ordering of its own.

**Properties:**

- `content: string = ''` — the full current text so far.
- `streaming: boolean = false` (reflected) — shows the blinking cursor after the rendered text;
  reflects so a host can also target `lr-streaming-text[streaming]` in CSS.
- `coalesceMs: number = 50` (attribute `coalesce-ms`) — trailing-edge coalesce window, in ms, for
  `content` updates (see prose below).
- `contentMode: StreamingTextContentMode = 'auto'` (attribute `content-mode`, reflected) — `auto`
  uses `looksLikeMarkdown`; `plain` and `markdown` force their named paths. Invalid values render as
  `auto` without installing a stale memoized decision.
- `languages?: Readonly<Record<string, ShikiLanguageInput>>` (property only) — forwarded verbatim to
  the composed `<lr-markdown>`'s own `languages`, the same fine-grained language-grammar scoping
  `<lr-code-block>`/`<lr-markdown>` support. Unset leaves the composed element's own default
  untouched.

The rest of `<lr-markdown>`'s configuration surface forwards verbatim too, each defaulting to
exactly `<lr-markdown>`'s own default so leaving it unset renders identically to before these
properties existed:

- `tabSize: number = 4` (attribute `tab-size`) — forwarded to the composed `<lr-markdown>`'s own
  `tabSize`.
- `htmlMode: 'sanitize' | 'escape' | 'trusted' = 'sanitize'` (attribute `html-mode`) — forwarded to
  the composed `<lr-markdown>`'s own `htmlMode`.
- `gfm: boolean = true` — forwarded to the composed `<lr-markdown>`'s own `gfm`.
- `linkTarget: string | null = '_blank'` (attribute `link-target`) — forwarded to the composed
  `<lr-markdown>`'s own `linkTarget`; the composed element always applies its own
  `rel="noopener noreferrer"` guard whenever a `target` is emitted, including a forwarded
  non-default value, and never a bare `opener`.
- `internalLinkPrefix: string = ''` (attribute `internal-link-prefix`) — forwarded to the composed
  `<lr-markdown>`'s own `internalLinkPrefix`.
- `headingOffset: number = 0` (attribute `heading-offset`) — forwarded to the composed
  `<lr-markdown>`'s own `headingOffset`.
- `highlightCode: boolean = true` (attribute `highlight-code`) — forwarded to the composed
  `<lr-markdown>`'s own `highlightCode`.
- `headingAnchors: boolean = false` (attribute `heading-anchors`) — forwarded to the composed
  `<lr-markdown>`'s own `headingAnchors`.
- `math: boolean = false` — forwarded to the composed `<lr-markdown>`'s own `math`; the transitive
  `katex` peer is requested only once this is set.
- `maxHeight: string = ''` (attribute `max-height`) — forwarded to the composed `<lr-markdown>`'s
  own `maxHeight`.

**Exported helper:** `looksLikeMarkdown(text: string): boolean` — runs a fixed, ordered list of
lightweight regexes (ATX heading, fenced code block, `**bold**`, `_italic_`, inline code, bullet
list item, numbered list item, `[text](url)` link, blockquote) against the whole string and returns
`true` on the first match. Used internally in `contentMode="auto"`; exported standalone
so the heuristic is directly testable without going through the component's render cycle. None of
the patterns need to be airtight — a false positive just routes ordinary prose harmlessly through
`<lr-markdown>`; a false negative just shows literal `**`/backticks/etc. as plain text until more
of the stream arrives.

**Events:** `lr-content-settled` (`detail: null`, composed, bubbling) — fired once newly-coalesced
`content` actually reaches the rendered DOM. In `markdown` mode (forced or auto-detected) this
element does not emit the event itself; the composed `<lr-markdown>` it delegates rendering to
already emits its own `lr-content-settled` at its own settle point, and — being composed — that
event bubbles out through this element unmodified, so exactly one event per settle reaches a
listener either way. A consumer composing this element inside a free-form container (e.g.
`<lr-thinking-panel>`'s default slot) can listen for it to drive auto-scroll, since this component
renders into its own shadow root and a plain light-DOM `MutationObserver` on the container can
never see that update happen. See `<lr-thinking-panel>`'s own reference at `llms/components/lr-thinking-panel.md`.

**Slots:** none — content renders from `content`, not a slot.

**CSS parts:** `base`, `cursor` (only rendered while `streaming` is `true`), plus every part
`<lr-markdown>` documents forwarded verbatim (no aliasing — none collides with `base`/`cursor`)
from the composed `<lr-markdown>` in Markdown mode via `exportparts`: `content`, `heading`,
`paragraph`, `list`, `code-block`, `inline-code`, `link`, `table`, `blockquote`, `img`, `math`. A
host-level `lr-streaming-text::part(link)`/`::part(img)` rule reaches the rendered `<a>`/`<img>`
exactly as the same rule does applied directly to `<lr-markdown>`.

**Themeable custom properties:** `--lr-inline-cursor-width` (default
`var(--lr-size-0-125rem)`, the shared inline cursor width), `--lr-inline-cursor-height` (default
`var(--lr-size-1em)`, so the bar tracks surrounding text). These are shared with
`<lr-typing-indicator>`, inherit from ancestors, and use local fallbacks only at the point of use; plus shared
`--lr-space-xs` (cursor's `margin-inline-start`) and `--lr-transition-ambient` (blink animation
cycle length).

**Optional peer deps:** the registration entry imports and auto-registers `<lr-markdown>` (the host
does not register it separately), so its optional-peer module graph includes `marked`, `dompurify`,
`shiki`, and `katex`. The runtime matrix is narrower: `content-mode="plain"` and auto-detected plain text
stay on the peer-free plain-text path; Markdown rendering lazy-loads `marked` plus the default
`dompurify` sanitizer and falls back to readable plain text if either is unavailable. Fenced code
can additionally use `shiki`, whose absence only leaves code unhighlighted. The composed Markdown
implementation contains the opt-in `katex` loader; this wrapper forwards its own `math` property
(default `false`) to the composed element verbatim, so `katex` is requested only once a consumer
sets `math` here.

```html
<lr-streaming-text id="out" coalesce-ms="80" streaming></lr-streaming-text>
<script type="module">
  const out = document.getElementById("out");
  let text = "";
  for await (const token of tokenStream) {
    text += token;
    out.content = text; // always the full string so far, never a delta
  }
  out.streaming = false; // forces the final chunk through immediately; cursor disappears
</script>
```

Token-by-token streaming can update `content` far faster than a human can usefully perceive a
re-render, so updates use a shared coalescing timer. Within any `coalesce-ms` window, only the
_last_ `content` value
assigned actually reaches the rendered DOM. Two cases always bypass the throttle and flush
immediately: the very first `content` assignment after mount, and any transition of `streaming`
between `true` and `false` in _either_ direction — so the final chunk of a finished stream can
never be left stranded mid-window, and a stream restarting on a reused element can never keep
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,
`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
renders into a `white-space: pre-wrap` span instead. The
blinking cursor degrades
to a static, always-visible bar under `prefers-reduced-motion: reduce`. In plain-text mode it sits
inline at the tail of the final character; in Markdown mode it renders as its own trailing block
below the rendered content instead of attempting to splice into whatever nested block Markdown
happens to end with.

**Known gotchas:**

- `content` must always be the complete string so far, never a delta — this component does no
  accumulation of its own.
- Only the very _first_ `content` assignment after mount bypasses `coalesceMs` unconditionally —
  every later assignment is throttled normally except when it lands in the same update as a
  `streaming` transition (either `true → false` or `false → true`), which also forces an immediate
  flush.
- `content-mode="plain"` forces plain text even if the text obviously contains Markdown syntax;
  `content-mode="markdown"` forces the Markdown path.
- Purely presentational: no events, and it does not announce anything to assistive tech itself — a
  host that needs streamed text announced needs `<lr-live-region>` for that (e.g. composed inside
  `<lr-chat-message>`).

---

## `lr-streaming-text-core`

A build-lean `<lr-streaming-text>` variant for a consumer whose fenced-code `languages` map already
covers every language it will ever stream, or who never renders fenced code at all. Every
capability — token coalescing, `contentMode` auto-detection, the blinking cursor, the
`lr-content-settled` event, the `languages` property, and the full forwarded Markdown configuration
surface (`tabSize`, `htmlMode`, `gfm`, `linkTarget`, `internalLinkPrefix`, `headingOffset`,
`highlightCode`, `headingAnchors`, `math`, `maxHeight`) — is identical to `<lr-streaming-text>`;
only which Markdown element Markdown mode composes differs: this variant renders
`<lr-markdown-core>` (`../markdown/markdown-core.js`) instead of `<lr-markdown>`, so importing this
entry point instead of `streaming-text.js` never references `<lr-markdown>`'s ~200-language
dynamic-import table at all. A fenced code block whose language isn't a key in `languages` always
renders the plain-text fallback — there is no default/full-table highlighter here to fall back to,
mirroring `<lr-markdown-core>`'s own contract.

**Properties:** `content: string = ''` — the full current text so far, identical contract to
`<lr-streaming-text>`'s own; `streaming: boolean = false` (reflected); `coalesceMs: number = 50`
(attribute `coalesce-ms`) — same trailing-edge coalesce window described in
`llms/components/lr-streaming-text.md`; `contentMode: StreamingTextContentMode = 'auto'` (attribute
`content-mode`, reflected) — `auto`
uses `looksLikeMarkdown`, `plain`/`markdown` force their named paths; `languages?:
Readonly<Record<string, ShikiLanguageInput>>` (property only) — forwarded verbatim to the composed
`<lr-markdown-core>`'s own `languages` instead of `<lr-markdown>`'s (defaulting the composed
element's own `languages` to `{}` when unset, unlike the full variant's `undefined`). The rest of
`<lr-markdown-core>`'s configuration surface forwards verbatim too, sharing the same properties,
attribute names, and defaults described under `<lr-streaming-text>`'s own **Properties** above:
`tabSize: number = 4` (attribute `tab-size`); `htmlMode: 'sanitize' | 'escape' | 'trusted' =
'sanitize'` (attribute `html-mode`); `gfm: boolean = true`; `linkTarget: string | null = '_blank'`
(attribute `link-target`, still guarded by the composed element's own
`rel="noopener noreferrer"` whenever a `target` is emitted); `internalLinkPrefix: string = ''`
(attribute `internal-link-prefix`); `headingOffset: number = 0` (attribute `heading-offset`);
`highlightCode: boolean = true` (attribute `highlight-code`); `headingAnchors: boolean = false`
(attribute `heading-anchors`); `math: boolean = false`; `maxHeight: string = ''` (attribute
`max-height`).

**Exported helper:** `looksLikeMarkdown(text: string): boolean` — the same standalone heuristic
`<lr-streaming-text>` exports and documents, in `llms/components/lr-streaming-text.md`; both tags
share one implementation.

**Events:** `lr-content-settled` (`detail: null`, composed, bubbling) — identical contract to
`<lr-streaming-text>`'s own, including the markdown-mode double-fire avoidance (here the composed
`<lr-markdown-core>` emits it instead of `<lr-markdown>`).

**Slots:** none — content renders from `content`, not a slot.

**CSS parts:** `base`, `cursor` (only rendered while `streaming` is `true`), plus every part
`<lr-markdown-core>` documents forwarded verbatim from the composed `<lr-markdown-core>` in
Markdown mode via `exportparts`: `content`, `heading`, `paragraph`, `list`, `code-block`,
`inline-code`, `link`, `table`, `blockquote`, `img`, `math` — the identical forwarded list
`<lr-streaming-text>` documents, since `<lr-markdown>` and `<lr-markdown-core>` share the same
documented part vocabulary.

**Themeable custom properties:** `--lr-inline-cursor-width` (default `var(--lr-size-0-125rem)`) and
`--lr-inline-cursor-height` (default `var(--lr-size-1em)`) — the same shared inline-cursor tokens
`<lr-streaming-text>`/`<lr-typing-indicator>` use, plus the same `--lr-space-xs`/
`--lr-transition-ambient` fallbacks described in `llms/components/lr-streaming-text.md`.

Every other capability — token coalescing mechanics, the first-assignment/`streaming`-transition
immediate-flush rules, the reduced-motion cursor degradation, and the known gotchas — is identical
to `<lr-streaming-text>`; see `llms/components/lr-streaming-text.md` for the full write-up of
shared behavior.

```html
<lr-streaming-text-core id="out" streaming></lr-streaming-text-core>
<script type="module">
  import typescript from "shiki/langs/typescript.mjs";
  const out = document.getElementById("out");
  out.languages = { typescript };
  out.content = "```typescript\nconst x = 1;\n```";
</script>
```

---

## `lr-generation-metrics`

A compact, ticking status readout shown alongside an in-progress AI response: elapsed time, token
count, and token-throughput, plus a built-in Stop button. First-party invention (no Web Awesome
equivalent). Renders as e.g. `12.3s · 340 tokens · 27 tok/s [Stop]`.

The host handles `lr-stop` by stopping its own producer and setting `status` to `complete`. A
restart supplies a fresh `startedAt`, resets its token count, and retires the previous producer
timer. The live example wires this lifecycle on mount, so its first Stop and every Restart take
effect immediately.

**9.0 identity migration:** `lr-generation-status` → `lr-generation-metrics`,
`LyraGenerationStatus` → `LyraGenerationMetrics`, and `LyraGenerationStatusEventMap` →
`LyraGenerationMetricsEventMap`. The old tag, class, event-map name, registration route, and
generated framework members are removed rather than retained as aliases.

**Properties:**

- `status: GenerationMetricsStatus = 'idle'` (`'idle' | 'running' | 'complete'`, reflected) —
  generation lifecycle. `idle` is never-started/reset; `running` ticks and is the only state that
  exposes Stop; `complete` freezes the final metrics. Invalid attribute or property writes normalize
  to `idle`.
- `startedAt?: number` (attribute `started-at`) — epoch-ms timestamp of when generation began.
  Optional — when unset, or set to a value that fails to parse as a finite number (e.g. an ISO-8601
  date string, which `type: Number` conversion turns into `NaN`), while `status` is `running`, this
  component captures `Date.now()` itself the moment `status` becomes `running` and counts from there
  instead — an invalid value is treated identically to "unset", never rendered as literal `"NaNs"`.
- `tokenCount?: number` (attribute `token-count`) — finite values are rounded to a non-negative
  integer; unset/non-finite values omit the `tokens` segment entirely.
- `tokensPerSecond?: number` (attribute `tokens-per-second`) — finite values are clamped to zero or
  above; unset/non-finite values derive from `token-count`/elapsed time once one second has elapsed.
- `showStop: boolean = true` (attribute `show-stop`, **not reflected**) — whether the built-in Stop
  button renders at all. Uses a string-value-aware `ComplexAttributeConverter` (not Lit's default
  presence-based `type: Boolean`), so a plain-HTML `show-stop="false"` content attribute correctly
  turns it off — the literal string `"false"` maps to `false`; the attribute's mere presence with any
  other value (or no value) maps to `true`. A Lit template can instead use a `.showStop=${false}`
  property binding. **Caveat:** a `?show-stop=${false}` boolean-attribute _binding_ still can't turn
  it off when the attribute was never present in markup to begin with — that binding only ever
  removes the attribute when falsy, and removing an attribute that's already absent fires no
  `attributeChangedCallback` (see AGENTS.md); use `.showStop=${false}` or the plain
  `show-stop="false"` string form instead.

**Events:** `lr-stop` (`detail: null`) — fired when the built-in Stop button is clicked while
`status="running"`.

**Slots:** none.

**CSS parts:** `base`, `elapsed` (always rendered, reads `"0.0s"` while idle), `tokens` (only
rendered for a finite `token-count`), `throughput` (only rendered when
a value is available, host-supplied or derived), `stop-button` (only rendered while `show-stop` is
`true` and `status="running"`)

**Themeable custom properties:** shared tokens only — `--lr-color-text-quiet` (base readout and
tokens/throughput text color), `--lr-color-text` (the elapsed segment's higher-contrast color,
and the stop-button's icon color), `--lr-space-s` (stop-button margin), `--lr-icon-button-size`
(stop-button minimum sizing; the full shared 40px-equivalent hit floor applies), `--lr-color-border`/`-surface`/`-brand`
(stop-button border/background/hover), `--lr-focus-ring-width`/`-color`/`-offset`,
`--lr-transition-fast`.

**Optional peer deps:** none.

```html
<lr-generation-metrics
  status="running"
  started-at="1732000000000"
  token-count="340"
  show-stop
></lr-generation-metrics>
<script type="module">
  document
    .querySelector("lr-generation-metrics")
    .addEventListener("lr-stop", () => {
      controller.abort(); // stop the host's own generation
    });
</script>
```

This is deliberately a _different_ concern than `<lr-stream-status>`: that component is about
transport/connection health (idle/connecting/streaming/stalled, heartbeat-aware stall detection),
while this one is a user-facing metrics readout for a generation both components' hosts typically
already know is healthily in progress. Neither imports or depends on the other; compose both side
by side rather than picking one. A finite `tokens-per-second`, when supplied directly, is clamped
non-negative and used;
when omitted, this component derives a live figure from `token-count` divided by elapsed seconds,
but only once at least one full second of elapsed time has accumulated (dividing by a sub-second
window can produce wildly-swinging early readings, e.g. 3 tokens in 40ms reading as "75 tok/s").
Entering `complete` freezes the elapsed clock for a completed-state summary; entering `idle` resets
it to zero. Sub-minute elapsed values use one decimal place until the rounding boundary at 59.95s;
minute values use localized whole minutes and seconds. Token counts use locale-aware plural rules.
Throughput below 10 uses up to one fractional digit and higher values round to whole tokens/sec.

This readout ticks roughly once per second while running, which is exactly the kind of
high-frequency update `<lr-live-region>`/`Announcer` exists to _prevent_ from being read aloud
verbatim — this component therefore carries no `role="status"`/`aria-live` of its own and never
announces anything. A host that wants generation-start/-end announced should pair this with
something that announces state _transitions_ instead. The Stop button gets a normal, always-present
`aria-label="Stop generating"`, no different from any other icon-only button in this library.

**Known gotchas:**

- `showStop` defaults to `true` and is not a reflected property. Its `ComplexAttributeConverter`
  makes the plain content attribute `show-stop="false"` work correctly, but a `?show-stop=${false}`
  Lit boolean-attribute _binding_ still can't turn it off starting from absent markup — see the
  property list above for the exact footgun.
- The derived `tokens-per-second` figure only appears once `elapsedMs >= 1000`; before that, the
  `throughput` part simply doesn't render — supply `tokens-per-second` yourself for a stable figure
  from the very first tick.
- Entering `complete` freezes the elapsed display; entering `idle` resets it to `"0.0s"`.
- `started-at` only re-baselines the ticker at the moment it's read: mounting the component with
  `status="running"` but no `started-at` captures `Date.now()` at that first update, not at
  whatever earlier instant generation may actually have begun.

---

## `lr-code-block`

Fenced code display with optional lazy syntax highlighting and a copy button. First-party invention
(no Web Awesome equivalent). It lazily loads the optional `shiki` peer for syntax highlighting and
includes a compact GreyCat/GCL grammar because
Shiki does not bundle one. It falls back to a plain `<pre><code>` when that peer isn't installed or
`language` is unset/unrecognized. That
fallback is the _default_ rendering path, not a degraded one: unhighlighted code is perfectly usable,
and it's what every instance renders at zero extra bytes until shiki resolves.

Removing `code`, `language`, or `highlight-lines` treats that input as absent: source becomes empty,
an absent language selects plain text, and attribute-based emphasis clears. Removal preserves Lit's
`null` property readback; an explicitly empty attribute stays an empty string, and a later value
resumes normal rendering. Highlighted gutter labels and locale-formatted line numbers follow live
`.strings` and inherited or explicit locale changes. Unrelated updates retain the existing
highlighted markup.

**Properties:**

- `code: string = ''` — the raw source text
- `language: string = ''` — a shiki-recognized language id or alias (e.g. `"javascript"`, `"python"`,
  `"json"`); when unset, or when shiki doesn't recognize it, the code renders as plain unhighlighted
  text regardless of whether shiki itself is available. Shiki's bundled catalog covers most common
  programming, markup, data, and configuration languages, including Python, C, C++, C#, Java,
  JavaScript, TypeScript, HTML, CSS, JSON, SQL, Go, Rust, YAML, Markdown, and shell scripts. Lyra
  also includes a built-in GreyCat grammar; use `"gcl"` or `"greycat"` for GreyCat source.
- `filename: string = ''` — shown in the header, when set
- `accessibleLabel: string | null = null` (attribute `aria-label`) — names the internal focusable code-body
  region; otherwise a localized filename/language description is generated
- `collapsible: boolean = false` (reflected) — shows the collapse/expand chevron button
- `collapsed: boolean = false` (reflected) — only has a visible effect while `collapsible` is also
  true
- `copyable: boolean = true` (reflected) — shows the copy-to-clipboard button. Literal HTML
  `copyable="false"` disables it; use a property binding such as `.copyable=${false}` when binding a
  value. A `?copyable=${false}` boolean-attribute binding only removes the attribute and cannot
  override the true default.
- `maxHeight: string = ''` (attribute `max-height`) — a CSS length (e.g. `"20rem"`); once set, the
  code scrolls internally past this height instead of growing the page
- `lineNumbers: boolean = false` (attribute `line-numbers`, reflected) — displays one-based line
  numbers for both highlighted output and the plain-text fallback
- `highlightLines: string = ''` (attribute `highlight-lines`) — comma-separated 1-based inclusive
  line ranges (e.g. `"3-5,7"`) to visually emphasize. Declarative sugar over `highlights` — merges
  with, and renders identically to, any `line-range` entries there. Malformed segments are ignored
  while valid segments still apply.
- `activatableLines: boolean = false` (attribute `activatable-lines`) — turns the
  (`lineNumbers`-gated) gutter into a roving-tabindex group of buttons emitting `lr-line-activate`.
  Has no effect while `lineNumbers` is unset. If controlled `code` shrinks while a line owns
  focus, focus follows the clamped surviving line; moving focus elsewhere during that update wins.
- `highlights: readonly LyraHighlight[] = []` (attribute: false) — host-supplied highlights to paint over the
  code (the shared anchor-target `LyraHighlight` contract from `document-viewer/anchors.ts`). Only
  `line-range` anchors are meaningful here — every other `LyraAnchor` kind is ignored.
- `activeHighlightId: string | null = null` (attribute `active-highlight-id`) — the `highlights`
  entry, if any, currently treated as active (`data-active` on its lines).
- `anchorKinds: LyraAnchor['kind'][] = ['line-range']` — readonly, for the shared anchor-target
  contract.
- `languages?: Record<string, ShikiLanguageInput>` (attribute: false) — a map of language id to an
  already-imported shiki grammar module (e.g. `{ bash: bashGrammar }` from a module-scope
  `import bash from 'shiki/langs/bash.mjs'`). When `language` matches a key here, highlighting is
  seeded from exactly that pre-supplied grammar via a fine-grained `createHighlighterCore()`
  highlighter, bypassing the default ~200-language dynamic-import path (`loadShikiHighlighter()`)
  for that language — an additive, opt-in escape hatch for a build scoped to just the languages a
  consumer actually needs. A `language` absent from this map (or `languages` left unset) falls back
  to the default dynamic-import path unchanged. For a TypeScript annotation, use
  `import type { ShikiLanguageInput } from '@aceshooting/lyra-ui/components/conversation/code-block/code-block.js'`;
  the type-only granular import emits no registration side effect.
  The map key need not be the grammar module's own registered name or one of its declared
  aliases — Lyra derives the Shiki `langAlias` mapping this needs automatically, so a key such as
  `tsx` reusing a differently-named grammar (e.g. TypeScript's own module, to avoid bundling a
  second near-identical grammar) still highlights under that key.

- `copyAppearance: 'text' | 'icon' = 'text'` (attribute `copy-appearance`, reflected) — how the
  header's copy control presents itself. `'text'` is the labelled button this component has always
  rendered; `'icon'` swaps the visible label for a compact glyph and promotes the same localized
  Copy/Copied/failure string to the control's accessible name

**Methods:** `scrollToAnchor(target)` — resolves a `line-range` anchor (or a `highlights` id string
resolving to one) by scrolling its start line into view within `[part="body"]`; resolves `false`
when the anchor isn't a `line-range`, the id isn't found, or the start line is out of bounds.
`refreshTheme(): void` re-reads the resolved theme for syntax highlighting.

**Events:** `lr-copy` (frozen `detail: { ok: true, text }` — fires only after the raw `code` value
was written successfully), `lr-error` (`detail: null` — generic notification when clipboard writing
fails), `lr-copy-error` (frozen `detail: { ok: false, text, reason, error }`, where `reason` is
`'unsupported' | 'denied' | 'failed'`), `lr-toggle-request` (cancelable;
`detail: { collapsed }` is the proposed next state and canceling leaves `collapsed` unchanged),
`lr-toggle` (`detail: { collapsed: boolean }` — the committed state after the request is accepted),
`lr-line-activate` (`detail: { line: number }` — a gutter line number was activated while
`activatableLines` is set),
`lr-text-select` (`detail: { text, anchor, rects }` — a text selection inside the code body ended;
`anchor` is a `line-range` anchor covering the selected lines)

**Slots:** `header-actions` — extra controls for the header row, rendered after the copy control.
Their presence alone is enough to render the header, and appending or removing such a child at any
time brings the header into existence or retires it (the host's own light DOM is observed; no
property write is needed).

**CSS parts:** `base`, `header`, `filename`, `language`,
`copy-button` (the copy control, a composed `<lr-icon-button>` as of 16.0.0; it also carries
`copy-button-text` or `copy-button-icon` for the active `copyAppearance`, so match it by token —
`[part~="copy-button"]` — not by exact value), `copy-button-text` / `copy-button-icon` (the copy
control in each appearance), `copy-button__control` (the copy control's own native `<button>`),
`header-actions` (the wrapper around the `header-actions` slot; it carries the `hidden` attribute
and computes to `display: none` whenever nothing is assigned, so an empty slot contributes no
header gap — a rule that sets `display` on it must qualify itself with `:not([hidden])`),
`toggle`, `body`, `pre`,
`code`, `line-highlight` (a line marked by `highlightLines` or a `line-range` entry in `highlights`),
`line-button` (a gutter line-number button, only rendered while `activatableLines` and `lineNumbers`
are both set)

**Migrating a pre-16.0.0 `::part()` rule.** This component's icon-only action is a composed
`<lr-icon-button>`, so the part naming that action now names the composed child's HOST, which
paints nothing. A `border`, `background` or `border-radius` set on it is silently dead — only
`color` still appears to work, because it inherits, which makes such a rule look half-alive rather
than broken. Set `--lr-icon-button-background`/`-color`/`-border`/`-radius` (and their
`-hover`/`-active` variants) on this element or an ancestor instead: the composed control reads
those public tokens ahead of any default this component supplies. For SIZE use
`--lr-theme-icon-button-size`, not `--lr-icon-button-size` — every `LyraElement` re-declares the
latter on its own `:host`, so it never reaches a composed child (see `llms/tokens.md`).

**Border reaches the composed copy control the same way background/color/radius do.** This
component paints no resting border of its own, so it relays no `--_lr-icon-button-border-default`
into the copy control's private fallback tier — but that absence is not a gap. The public
`--lr-icon-button-border` (and its `-hover`/`-active` variants) is the FIRST arm of the token
chain, resolved by ordinary custom-property inheritance regardless of whether this component
relays a default for that same property, so setting it on this element or an ancestor reaches the
copy control exactly as the background/color/radius tokens do. A component with no resting
border simply has no default to relay, which is different from border theming being broken. Size
remains the one exception that does not cross this way: use `--lr-theme-icon-button-size`, never
`--lr-icon-button-size`, as noted above.

**Themeable custom properties:** `--lr-code-block-max-height` (default `none` — an independently
settable scroll cap; a `max-height` attribute writes the same property inline on `body` and wins),
`--lr-code-block-font` (default
`var(--lr-font-mono)`, the library's shared monospace stack), `--lr-code-block-tab-size` (default `2` — tab width for the
rendered code, applied to `[part='pre']`), `--lr-code-block-active-line-outline-color` (default
`var(--lr-color-brand)` — the outline around the line marked active by `active-highlight-id`),
`--lr-code-block-highlighted-line-bg` (default `var(--lr-color-warning-quiet)` — the background of a
line marked by `highlight-lines` or a `line-range` entry in `highlights`, in both the light and
dark-theme rendering paths), `--lr-code-block-language-bg` (default `var(--lr-color-brand-quiet)`)
and `--lr-code-block-language-color` (default `var(--lr-color-brand)`) — the header `language` pill's
background and text color, independent of the active-line outline above — plus shared tokens
`--lr-color-border`, `--lr-radius`,
`--lr-color-surface`, `--lr-space-xs/-s/-m`, `--lr-font`, `--lr-color-text-quiet`,
`--lr-color-text`, `--lr-color-brand`/`-brand-quiet`, `--lr-transition-fast`,
`--lr-focus-ring-width/-color/-offset`. `body`, the scroll container, also honors the opt-in
theme-level `--lr-theme-scrollbar-width`/`--lr-theme-scrollbar-gutter` hooks (defaults `auto`/`auto`,
matching its previous unconditional `scrollbar-width: auto`) — set either on `:root` or any
ancestor for one declaration to retheme every internal scroll container in the library, including
`lr-table`, `lr-virtual-list`, `lr-scroller`, `lr-carousel`, and `lr-code-editor`.

`base` is a flex column and `body` grows to fill whatever block space a definite-height host
gives it, still capped by `--lr-code-block-max-height` and still independently scrollable. An
unsized host is unaffected — this is a fill capability, not a change to the default
content-sized rendering.

`--lr-code-block-tab-size` carries the same default as `--lr-code-editor-tab-size`, so the editable
and read-only code surfaces agree on what a literal tab looks like. It is declared as a `var()`
fallback **at the point of use, not on `:host`** — a `:host` rule is re-stamped on every instance and
shadows any inherited value, so a page- or container-level declaration could never reach it. It is
also never written as an inline `tab-size`: `shiki` puts its own `style` attribute on the highlighted
`<pre>`, and an inline declaration is the one thing a host override cannot beat. `<lr-markdown>` and
`<lr-markdown-core>` carry the same fallback for their own `code-block` part because they are
**sibling** custom elements rather than descendants of this one — no single declaration covers both.
The identical value can still look different across the two: this component is `white-space: pre`
while a markdown code block inherits `pre-wrap`, and tab stops restart at each visual line, so a
wrapped line's tabs diverge.

`--lr-code-block-active-line-outline-color` retints just the active line's outline and leaves every
other `--lr-color-brand` surface in the component — hover states, the focus
ring — alone. It too is an inline `var()` fallback rather than a `:host` declaration, deliberately,
so it inherits: set it on the element, on an ancestor, or at the theme level.
`--lr-code-block-language-bg`/`--lr-code-block-language-color` retint the header language pill on
their own, independent of both the active-line outline and the hover/focus states.

`--lr-code-block-highlighted-line-bg` follows the same pattern: an inline `var()` fallback (not a
`:host` declaration) so it inherits, retinting just the highlighted-line background and leaving every
other `--lr-color-warning-quiet` surface alone.

**Optional peer deps:** `shiki` — requested only when syntax highlighting is used and shared by
code blocks on a page. Languages load on demand. If the peer or requested language is unavailable,
every instance retains a readable plain-text fallback; install it with `pnpm add shiki` to enable
highlighting.

```ts
import { html } from "lit";
import "@aceshooting/lyra-ui/components/conversation/code-block/code-block.js";

const view = html`<lr-code-block
  language="typescript"
  filename="sum.ts"
  collapsible
  max-height="20rem"
  .code=${`export function sum(a: number, b: number) {\n  return a + b;\n}`}
  @lr-copy=${(e) => console.log("copied", e.detail.text)}
></lr-code-block>`;
```

Set `line-numbers` when source context benefits from numbered lines. The option does not change the
raw `code` value or the `lr-copy` event payload.

A decorative `<lr-skeleton shape="rect">` placeholder (with its own announcements disabled and
`aria-busy="true"` on the host) stands in only while shiki itself is loading for the very first time
on the page and `language` is set — it is
deliberately _not_ shown again for a later per-language grammar fetch (that's typically fast, and the
plain-text fallback already reads fine as a placeholder for it). Internally, a shiki `transformer`
(`partTransformer`) rewrites shiki's generated `<pre>`/`<code>` nodes in a single pass to carry this
component's own `part="pre"`/`part="code"` hooks and strips shiki's default `tabindex="0"` from
`<pre>`, since `[part="body"]` is already the single scrollable/focusable region (`role="group"`,
`tabindex="0"`) for the code area. Dark mode is handled via shiki's own "dual themes" feature: every
token carries its light color as a plain inline `color`/`background-color` and its dark color in
`--shiki-dark`/`--shiki-dark-bg` custom properties. The component watches its resolved Lyra theme
tokens and sets `data-dark-theme="true"` on the code body when the effective surface is dark; an
`!important` state rule then activates Shiki's dark values. This follows explicit Lyra theme
overrides instead of consulting `prefers-color-scheme` directly. Shiki's generated colors are the
one deliberate exception to every other color being a `--lr-*` token.

**Known gotchas:**

- `copyable` defaults to `true` and reflects — literal `copyable="false"` and a `.copyable=${false}`
  property binding both disable it; a `?copyable=${false}` boolean-attribute binding does not.
- if `code` or `language` changes while highlighting is loading, only the result matching the
  current values is rendered.
- a malformed `code`/`language` combination that makes shiki's `codeToHtml()` throw falls back to
  plain text silently, not a blank code block.
- the "Copied!" label appears only after clipboard fulfillment and reverts to "Copy" after 1500ms.
  Rejection or an unavailable clipboard instead shows the localized failure state and emits
  `lr-error` plus `lr-copy-error`; the helper resolves the clipboard from the element's current
  `ownerDocument`, including after adoption.

---

## `lr-code-block-core`

A build-lean sibling of `<lr-code-block>` above, for a consumer whose `languages` map already
covers every language it will ever render. Where `<lr-code-block>` unconditionally calls
`loadShikiHighlighter()` — the default ~200-language dynamic-import table loader, whose bundled
lookup table a bundler can't statically narrow away even when a consumer never actually uses it —
this component's own module never imports or calls that function at all. It only ever calls
`loadShikiHighlighterCore(languages)` (shiki's "fine-grained bundle" recipe: `createHighlighterCore()`
plus an explicit oniguruma engine, seeded with _only_ the grammars in `languages`), so a consumer
importing this entry point instead of `code-block.js` gets a build genuinely free of shiki's full
language table.

Removing `code`, `language`, or `highlight-lines` treats that input as absent: source becomes empty,
an absent language selects plain text, and attribute-based emphasis clears. Removal preserves Lit's
`null` property readback; an explicitly empty attribute stays an empty string, and a later value
resumes normal rendering. Highlighted gutter labels and locale-formatted line numbers follow live
`.strings` and inherited or explicit locale changes. Unrelated updates retain the existing
highlighted markup.

A `language` value absent from `languages` always renders the plain `<pre><code>` fallback — there is
no default/full-table highlighter here to fall back to, unlike `<lr-code-block>`'s dynamic-import
path for an unmapped language. That fallback is the _default_ rendering path, not a degraded one,
same as `<lr-code-block>`'s own plain-text fallback. Everything else — `code`/`language`/
`filename`/`copyable`/`collapsible`/`collapsed`/`maxHeight`, the copy button, the collapse header
toggle, the loading-skeleton behavior while the fine-grained highlighter resolves — matches
`<lr-code-block>` exactly, including its CSS parts, themeable custom properties, and stylesheet
(this component reuses `code-block.styles.ts` directly).

**Properties:**

- `code: string = ''` — the raw source text.
- `language: string = ''` — a shiki-recognized language id or alias; when unset, or when it isn't a
  key in `languages`, the code renders as plain unhighlighted text — this component has no
  default/full-table highlighter to fall back to.
- `filename: string = ''` — shown in the header, when set.
- `accessibleLabel: string | null = null` (attribute `aria-label`) — names the internal focusable code-body
  region; otherwise a localized filename/language description is generated.
- `collapsible: boolean = false` (reflected) — shows the collapse/expand chevron button.
- `collapsed: boolean = false` (reflected) — only has a visible effect while `collapsible` is also
  true.
- `copyable: boolean = true` (reflected) — shows the copy-to-clipboard button. Literal HTML
  `copyable="false"` or a `.copyable=${false}` property binding disables it; a
  `?copyable=${false}` boolean-attribute binding cannot override the true default.
- `maxHeight: string = ''` (attribute `max-height`) — a CSS length (e.g. `"20rem"`); once set, the
  code scrolls internally past this height instead of growing the page.
- `lineNumbers: boolean = false` (attribute `line-numbers`, reflected) — displays one-based line
  numbers for highlighted and plain output.
- `highlightLines: string = ''` (attribute `highlight-lines`) — comma-separated 1-based inclusive
  line ranges (e.g. `"3-5,7"`) to visually emphasize. Declarative sugar over `highlights` — merges
  with, and renders identically to, any `line-range` entries there. Malformed segments are ignored
  while valid segments still apply.
- `activatableLines: boolean = false` (attribute `activatable-lines`) — turns the
  (`lineNumbers`-gated) gutter into a roving-tabindex group of buttons emitting `lr-line-activate`.
  Has no effect while `lineNumbers` is unset. If controlled `code` shrinks while a line owns
  focus, focus follows the clamped surviving line; moving focus elsewhere during that update wins.
- `highlights: readonly LyraHighlight[] = []` (attribute: false) — host-supplied highlights to paint over the
  code. Only `line-range` anchors are meaningful here — every other `LyraAnchor` kind is ignored.
- `activeHighlightId: string | null = null` (attribute `active-highlight-id`) — the `highlights`
  entry, if any, currently treated as active (`data-active` on its lines).
- `anchorKinds: LyraAnchor['kind'][] = ['line-range']` — readonly, for the shared anchor-target
  contract, identical to `<lr-code-block>`.
- `languages: Record<string, ShikiLanguageSource> = {}` (attribute: false) — grammar definitions this
  instance can highlight, e.g. `{ json: jsonGrammar }` (import from `shiki/langs/<name>.mjs`), or a
  lazy loader per key, e.g. `{ bash: () => import('@shikijs/langs/bash') }` — called at most once
  per key, memoized, the first time a fenced block actually requests that language. Empty
  (the default) never highlights at all — every `language` renders the plain-text fallback, and so
  does a key whose lazy loader rejects.
  If `languages` changes while highlighting is loading, only results for the current map can update
  the displayed code. For a
  TypeScript annotation, use `import type { ShikiLanguageSource } from
'@aceshooting/lyra-ui/components/conversation/code-block/code-block-core.js'`; the type-only
  granular import emits no registration side effect.
- `copyAppearance: 'text' | 'icon' = 'text'` (attribute `copy-appearance`, reflected) — identical to
  `<lr-code-block>`'s own property: `'text'` is the labelled button, `'icon'` swaps the visible label
  for a compact glyph and promotes the same localized string to the control's accessible name

**Methods:** `scrollToAnchor(target)` — resolves a `line-range` anchor (or a `highlights` id string
resolving to one) by scrolling its start line into view within `[part="body"]`; resolves `false`
when the anchor isn't a `line-range`, the id isn't found, or the start line is out of bounds.
`refreshTheme(): void` re-reads the resolved theme for syntax highlighting.
Identical behavior to `<lr-code-block>`'s own method.

**Events:** the same fulfilled-only `lr-copy`, generic `lr-error`, full `lr-copy-error`, cancelable
`lr-toggle-request`, committed `lr-toggle`, and `lr-line-activate` contracts as `<lr-code-block>`;
`lr-text-select` (`detail: { text, anchor, rects }` — a text selection inside the code
body ended; `anchor` is a `line-range` anchor covering the selected lines).

**Slots:** `header-actions` — identical to `<lr-code-block>`'s own slot.

**CSS parts:** `base`, `header`, `filename`, `language`, `copy-button`, `copy-button-text`,
`copy-button-icon`, `copy-button__control`, `header-actions`, `toggle`, `body`, `pre`,
`code`, `line-highlight`, `line-button` — identical set to `<lr-code-block>`.

**Themeable custom properties:** identical to `<lr-code-block>` — `--lr-code-block-max-height`
(independently settable; an authored `max-height` attribute wins inline),
`--lr-code-block-font`, `--lr-code-block-tab-size` (default `2`, applied to `[part='pre']`),
`--lr-code-block-active-line-outline-color` (default `var(--lr-color-brand)`),
`--lr-code-block-highlighted-line-bg` (default `var(--lr-color-warning-quiet)`),
`--lr-code-block-language-bg` (default `var(--lr-color-brand-quiet)`), and
`--lr-code-block-language-color` (default `var(--lr-color-brand)`), plus the same shared
tokens, including the `--lr-theme-scrollbar-width`/`--lr-theme-scrollbar-gutter` hooks `body` honors —
this component reuses `<lr-code-block>`'s stylesheet, so both share exactly the same scroll
container. The last five are inline `var()` fallbacks at the point of use rather than `:host`
declarations, so a page-, container-, or theme-level value reaches them; see `<lr-code-block>` above
for the full rationale, including why `<lr-markdown>`/`<lr-markdown-core>` must declare the tab-size
fallback separately. `base` is a flex column and `body` grows to fill whatever block space a
definite-height host gives it too, identically to `<lr-code-block>` above.

**Optional peer deps:** `shiki` (specifically its `shiki/core`, `shiki/engine/oniguruma`, the binary
`shiki/onig.wasm` asset (the default; select `shiki/engine/javascript` instead via
`setShikiCoreEngine('javascript')`), and `shiki/themes/github-{light,dark}.mjs` subpaths — never
`shiki`'s main entry point, which is what carries the ~200-language table this component exists to
avoid). Building the
fine-grained highlighter is cached per `languages` object identity. A bounded weak cache also shares
recently used equivalent, deeply frozen plain grammar maps, including the detached snapshots owned
by separate component instances. Grammar contents and property/array order must agree completely;
mutable or unusual inputs keep identity-only caching. Highlighters returned by the public loader
can therefore be shared across equivalent frozen maps. Passing a stable module-level `languages`
constant also avoids repeated component snapshots.

```ts
import { html } from "lit";
import jsonGrammar from "shiki/langs/json.mjs";
import "@aceshooting/lyra-ui/components/conversation/code-block/code-block-core.js";

const languages = { json: jsonGrammar };
const view = html`<lr-code-block-core
  language="json"
  .languages=${languages}
  .code=${'{"ok": true}'}
></lr-code-block-core>`;
```

**Known gotchas:**

- there is no default highlighter and no dynamic-import fallback table — a `language` you haven't
  added to `languages` will never highlight, no matter how common that language is elsewhere. Reach
  for `<lr-code-block>` instead if you need to support an open-ended set of languages without
  pre-declaring each one.
- Pass a stable, module-level `languages` constant to avoid repeated snapshots on parent renders.
  Equivalent frozen maps can share a recently used highlighter, but that bounded weak reuse is an
  optimization: callers must not depend on distinct frozen map objects producing distinct cores.

---

## `lr-model-settings-panel`

A fixed composition of `<lr-model-select>` and `<lr-slider>` into one agent-configuration card:
pick a provider's model, then tune its sampling temperature. First-party invention (no Web Awesome
equivalent). Not a generic layout shell — it exists so a consumer doesn't have to re-wire the same
two child `lr-change` events into one combined settings object by hand every time this pairing
comes up.

Every prop here is a plain pass-through to (or mirror of) the matching child control's own prop of
the same/similar name — see `lr-model-select` and `lr-slider` themselves for the exact semantics
of `catalog`/`allowCustom` and `temperatureMin`/`temperatureMax`/`temperatureStep`.

**Properties:**

- `provider: string = ''` — informational provider badge, passed straight through to the internal
  `lr-model-select`.
- `catalog?: LyraCatalog<LyraModelCatalogEntry>` (attribute: false, JS-only) — a readonly string
  catalog or readonly object-row catalog (every entry must be one shape or the other, never mixed);
  passed straight through to the internal `lr-model-select`, with the shared unique, nonempty,
  first-wins catalog projection also used for this panel's `inCatalog` event field. The array is
  clone-owned, bounded, and frozen; reassign a new catalog array after changing its rows.
- `model: string = ''` — the current model id.
- `allowCustom: boolean = false` (attribute `allow-custom`) — lets the model control accept a value
  outside `catalog`; passed straight through.
- `temperature: number = 1` — the current sampling temperature. `1` is the midpoint of the default
  `[0, 2]` range and matches both OpenAI's and Anthropic's own provider default; reassign it yourself
  if your provider differs.
- `temperatureMin: number = 0` (attribute `temperature-min`)
- `temperatureMax: number = 2` (attribute `temperature-max`)
- `temperatureStep: number = 0.1` (attribute `temperature-step`)
- `layout: 'vertical' | 'compact' = 'vertical'` (reflected) — `vertical` stacks full-width rows with
  visible labels; `compact` runs the same two rows side by side with a smaller, uppercase temperature
  caption, for toolbars/sidebars where the vertical layout's height doesn't fit.
- `disabled: boolean = false` (reflected) — disables the panel as a unit by forwarding to _both_
  internal `lr-model-select` and `lr-slider`; a wrapping `<fieldset disabled>` alone would not
  reach either, since a form-associated control's own `disabled` IDL property/attribute is never
  mutated by fieldset cascading.

**Events:** `lr-change` — `detail: { model: string; inCatalog: boolean; temperature: number }`.
Fires whenever _either_ child control's own `lr-change` fires, and always carries the full current
settings snapshot, not just whichever field actually changed. `inCatalog` is recomputed fresh from
`catalog`/`model` on every emission (mirroring `lr-model-select`'s own `effectiveEntries` logic)
rather than cached from the last child event, so it's still correct even when `model` was just
assigned directly instead of via the child's own event. The nested selector's native `focus` and
`blur` events remain contained at that child boundary; the panel does not declare or relay them.

**Slots:** none — this is a fixed two-control composition, not a generic layout shell.

**CSS parts:** `base`, `model-row`, `model-select`, `model-label` (forwarded visible internal
selector label), `temperature-row`, `temperature-label`, `temperature-value`

**Themeable custom properties:** `--lr-model-settings-panel-max-inline-size` — the card's own width
ceiling (default `var(--lr-size-28rem)`). Set a length to retune it, or `none` for a full-width
card. `layout="compact"` uncaps the card by default and reads the same name, so a length narrows a
compact card too. The panel also sets `--lr-model-select-max-inline-size: none` on its own
`[part="model-row"]`, so the nested selector fills the row rather than stopping at its standalone
24rem ceiling — set that name on the row to re-cap it. Otherwise it consumes shared tokens
`--lr-space-l/-m/-s/-xs`, `--lr-color-border`, `--lr-radius`, `--lr-color-surface`,
`--lr-color-text`, `--lr-color-text-quiet`.

**Optional peer deps:** none — it composes the library's own `<lr-model-select>` and `<lr-slider>`
internally (both imported unconditionally as side effects, not optional).

```html
<lr-model-settings-panel provider="OpenAI" model="gpt-4o" temperature="0.7"></lr-model-settings-panel>

<lr-model-settings-panel layout="compact"></lr-model-settings-panel>
<script type="module">
  const [panel, compactPanel] = document.querySelectorAll("lr-model-settings-panel");
  panel.catalog = ["gpt-4o", "gpt-4o-mini", "gpt-4.1"];
  panel.addEventListener("lr-change", (e) => console.log(e.detail));
  compactPanel.catalog = catalog;
</script>
```

The internal `lr-slider` renders with its own value readout suppressed (`.showValue=${false}`);
the current temperature is instead shown via this component's own `[part="temperature-value"]` span,
which formats `temperature` through the cached `Intl.NumberFormat` for the effective locale with up
to 20 fractional digits, matching `lr-slider`'s own numeric readout. For example, `temperature="0.7"`
under `locale="de-DE"` displays `0,7`. When the full decimal expansion would exceed 24 characters —
reachable only through an extreme `temperatureMin`/`temperatureMax`/`temperatureStep` combination —
the readout switches to bounded scientific notation at up to 6 significant digits instead, so
`1e308` renders as `7E+307` rather than a 300-digit string that would overflow the label.

The panel's own `temperature` property mirrors the nested slider's _live_ value on every one of its
`lr-input` events (drag/key-repeat), not just its committed `lr-change` — so `temperature` (and
the visible readout) tick continuously during a drag, but the panel's own `lr-change` event only
fires once the slider's own `lr-change` commits (pointerup/keyup) or the model changes; reading
`.temperature` mid-drag will already reflect the live position even though no `lr-change` has fired
yet for it.

**Known gotchas:**

- `catalog` is JS-only (`attribute: false`) — set it via a property binding (`.catalog=`), never as
  an HTML attribute, same requirement as the underlying `lr-model-select`.
- `layout="compact"` removes the host's own `max-inline-size` cap (`28rem` in `vertical` layout)
  entirely, so a compact panel can grow as wide as its container/flex context allows.
- The nested `lr-model-select`'s own `max-inline-size` (sized for a standalone dropdown) is
  overridden to `100%`/`none` inside `[part="model-row"]` so it fills the card's full width — a
  detail only worth knowing if you're targeting `lr-model-select` internals with your own CSS
  through this component.

---

## `lr-audio-visualizer`

A presentational, canvas-drawn voice-activity visualization (bars or waveform) — the
LiveKit-BarVisualizer counterpart for this library. Driven by a `MediaStream` (lazily wired to a
WebAudio `AnalyserNode`), a numeric `level` for hosts that already compute levels (e.g.
`<lr-push-to-talk>`'s `lr-level`), or `state` alone for an ambient animation when no real signal
exists. A real signal (`stream` or `level`) always drives amplitude regardless of
`prefers-reduced-motion`; only the signal-less ambient animation is throttled under reduced motion.

**Properties:** `stream: MediaStream | null = null` (attribute: false) — a live capture stream, lazily
wired to a WebAudio `AnalyserNode`; `level: number | null = null` — a pre-computed 0–1 amplitude for
hosts that already have one (e.g. `lr-push-to-talk`'s `lr-level` detail); `state: 'idle' |
'listening' | 'thinking' | 'speaking' = 'idle'` (reflected) — drives the signal-less ambient
animation and per-state coloring; `mode: AudioVisualizerMode = 'bars'` (`'bars' | 'waveform'`,
reflected); `barCount: number = 5` (attribute `bar-count`, normalized to an integer in `[1, 64]`);
`gain: number = 1` — multiplier applied to the resolved amplitude, with a non-finite value treated
as `1`; `label: string = ''` — accessible-name override. `level` is clamped to `[0, 1]`; after gain,
waveform and bar values are clamped to `[-1, 1]` and `[0, 1]` respectively. Invalid `state` or
`mode` attribute/property writes normalize to `idle` and `bars` respectively.

**Methods:** `refreshTheme()` re-reads themeable custom properties after a runtime theme change (the
canvas resolves token values at paint time and cannot inherit `var()` directly). Canvas-bound
colors are materialized through a live DOM probe, so `currentColor` and inherited expressions
resolve in the component's theme scope while invalid values fall back safely. Assigning a detached
or empty `MediaStream` tears down the prior analyser transaction immediately and draws from
`level`/ambient state; late setup from an older stream cannot replace the current source.

**Events:** none — purely presentational.

**Slots:** none.

**CSS parts:** `base` (the root wrapper) and `canvas` (the drawing surface, `aria-hidden`). The host
supplies `role="img"` only while an author has not supplied a role; an authored role is preserved,
and removing it restores `img`. If observation cannot be established, it draws eagerly; otherwise
it waits for a valid observer entry and pauses offscreen.

**Themeable custom properties:** `--lr-audio-visualizer-color` (default `var(--lr-color-brand)` —
active bar/waveform color), `--lr-audio-visualizer-quiet-color` (default
`var(--lr-color-brand-border-normal)` — inactive/idle color, chosen for WCAG 1.4.11 non-text
contrast against `--lr-color-surface`), and `--lr-audio-visualizer-height` (default
`var(--lr-size-3rem)` — the host's block size). `--lr-audio-visualizer-ambient-duration` (default
`var(--lr-duration-ambient)`) is the time-only `ms`/`s` duration of one signal-less ambient pulse
or sweep. It retimes this visualizer alone; compound transition values and invalid values fall back
to the shared duration, while reduced-motion ambient output remains static.

## `lr-branch-picker`

The "‹ 2 / 5 ›" navigator across regenerated/edited variants of one message. Pure controlled: it
never mutates its own `index` — the same contract `<lr-pagination>` already establishes for
`page`. The host listens for `lr-branch-change`, swaps the displayed branch content, and applies
the new `index` back. Renders nothing at all while `count < 2`, so a host can bind it unconditionally
on every message regardless of whether that message actually has multiple branches yet.

**Properties:** `index: number = 0` (reflected) and `count: number = 1` (reflected) — the current
0-based branch and the total branch count. `label: string = ''`.

**Methods:** `focus(options?)` forwards to the currently enabled chevron (falling back to the first
rendered chevron), `blur()` blurs both chevrons, `click()` activates that same enabled target, and
`getToolbarActions()` returns the ordered logical actions used by an enclosing message toolbar.

**Events:** `lr-branch-change` — a branch navigation was requested. `detail: { index }`, always a
valid target (never past either bound); the consumer applies `index` after switching the displayed
branch content. `lr-toolbar-actions-change` is the no-detail coordination event emitted when the
provider's logical toolbar actions change availability or order.

**CSS parts:** `base` (the group wrapper, `role="group"`), `previous-button`, `next-button`,
`previous-glyph` and `next-glyph` (the chevron inside each button — target these to swap the
arrow without restyling the button), and `position` (the visible "2 / 5" text).

## `lr-message-actions`

The per-message action toolbar for `lr-chat-message`'s `actions` slot: opt-in built-ins (copy /
regenerate / edit / feedback) that emit intent events, plus a default slot for custom controls (e.g.
a slotted `lr-branch-picker`). `role="toolbar"` with WAI-ARIA APG roving-tabindex; ArrowLeft/
ArrowRight (RTL-aware) plus Home/End move focus across every stop — built-ins and slotted controls
alike. Composite controls expose ordered logical actions through the exported
`LyraToolbarActionProvider` protocol, so implementation nodes stay private while the toolbar can
focus and set each logical tab stop. Providers announce order/availability changes with
`lr-toolbar-actions-change`; plain authored controls remain observed in light DOM.
Disabled, hidden, `aria-hidden`, `aria-disabled`, inert, or no-longer-actionable controls (including
controls beneath an unavailable ancestor) are excluded before the usable roving fallback is chosen.
Those states and `tabindex` are observed live, not only at mount/slot assignment; former stops are
cleared immediately. Slotted custom elements contribute their actual composed action targets rather
than their host merely because it has a `focus()` method; multiple nested actions (for example both
feedback thumbs or branch-picker buttons) remain distinct stops. If the focused action is removed or
becomes unavailable, focus moves to the nearest survivor or the stable toolbar, without overriding a
newer external focus move. Keyboard movement starts from the action that actually received the event,
even after a controlled state write changed the remembered stop.

ArrowLeft/ArrowRight/Home/End from a slotted feedback comment editor remain native editing keys.
Roving navigation still operates on the actual toolbar and thumb actions.

**Properties:** `controls: MessageActionControl[] = []` (attribute: false) —
`MessageActionControl = 'copy' | 'regenerate' | 'edit' | 'feedback'` (exported here); which built-ins
render, in that order. Duplicate names are omitted first-wins before rendering, roving focus, or
intent events, so each built-in can occur at most once. `copyText: string = ''`
(attribute `copy-text`) — required for the `copy` built-in to render at all. `feedbackRating:
MessageFeedbackValue = null` (attribute `feedback-rating`) — forwarded to the embedded, thumbs-only
`lr-message-feedback` (its `detail`/`detailFor` are never forwarded, so its detail panel never
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.
`label: string = ''` — accessible name override for the toolbar. `accessibleLabel: string | null =
null` (attribute `aria-label`) — overrides the toolbar's computed accessible name, winning over
`label` and the localized default; attribute-reflects from a host-level `aria-label`.

**Methods:** `finalizePendingSubmit(submissionId: string): boolean` and
`revertPendingSubmit(submissionId: string): boolean` settle only the current built-in feedback
request. Both return `false` for blank, stale, mismatched, removed, or replaced requests.

**Events:** `lr-regenerate`/`lr-edit` — a built-in was activated, `detail: null`. `lr-copy` —
frozen `detail: { ok: true, text }`, emitted only after the embedded `lr-copy-button`'s clipboard
write fulfills (bubbles/composed already, not re-emitted). A failed write surfaces generic
`lr-error` (`detail: null`) plus `lr-copy-error` with frozen
`detail: { ok: false, text, reason, error }`; `reason` is `'unsupported' | 'denied' | 'failed'`.
`lr-feedback-change`/`lr-feedback-submit` — bubble unchanged from the embedded, thumbs-only
`lr-message-feedback`; the frozen submit detail includes its `submissionId`, which is the value to
pass to either settlement method. A colliding event from an
arbitrary slotted child is contained at that slot boundary rather than being mistaken for a
built-in action.

Composite toolbar providers must expose nonblank action ids that are unique within that provider;
invalid actions and later duplicates are omitted before roving focus ownership.

**Slots:** default — additional controls (e.g. `lr-copy-button`, `lr-icon-button`,
`lr-branch-picker`) appended after the built-ins; they participate in the toolbar's arrow-key
navigation.

**CSS parts:** `base` (the toolbar, `role="toolbar"`), `copy-button` (the embedded
`lr-copy-button`), `regenerate-button`, `edit-button`,
`regenerate-button__control` / `edit-button__control` (each built-in action's own native `<button>` —
as of 16.0.0 both are composed `<lr-icon-button>`s, so `--lr-icon-button-*` retunes them and the
toolbar's roving tab stop is leased on the native control rather than the host), and `feedback` (the
embedded `lr-message-feedback`).

The toolbar has no `size`/`compact` property: every built-in's hit area is `<lr-icon-button>`'s
shared `--lr-icon-button-size` floor (2.5rem/40px), same as everywhere else in the library. For a
dense action row, lower `--lr-theme-icon-button-size` (not `--lr-icon-button-size`, which every
`LyraElement` re-declares on its own `:host` and so never reaches a composed child) on this element
or an ancestor, or reach a built-in's composed native control directly through
`::part(regenerate-button__control)` / `::part(edit-button__control)`. A coarse-pointer/no-hover
media rule then floors the rendered hit area at 2.75rem/44px regardless of how far a dense-row
override lowered it, so the shrink is safe on a touch device.

**Migrating a pre-16.0.0 `::part()` rule.** This component's icon-only actions are composed
`<lr-icon-button>`s, so a part naming one of them now names the composed child's HOST, which paints
nothing. A `border`, `background` or `border-radius` set on it is silently dead — only `color` still
appears to work, because it inherits, which makes such a rule look half-alive rather than broken.
Set `--lr-icon-button-background`/`-color`/`-border`/`-radius` (and their `-hover`/`-active`
variants) on this element or an ancestor instead: the composed control reads those public tokens
ahead of any default this component supplies. For SIZE use `--lr-theme-icon-button-size`, not
`--lr-icon-button-size` — every `LyraElement` re-declares the latter on its own `:host`, so it never
reaches a composed child (see `llms/tokens.md`).

## `lr-message-feedback`

Thumbs up/down for one assistant message, with an optional inline detail step (categorical reason
chips + a free-text comment) that opens as a disclosure directly below the thumbs. Emits; never
persists — a host reflects a previously-recorded rating back via `rating` (+ `disabled` for a
read-only display). Activating the pressed thumb while its detail panel is open toggles it off to
`null`. If an applicable panel was closed without changing the rating (for example with Escape),
activating the still-pressed thumb reopens it with the surviving draft. A thumbs-only control always
uses the ordinary re-activate-to-clear toggle.

Asynchronous finalization or reversion preserves focus on an outside control. Settlement retains the
existing thumb/submit fallback when focus remains within the feedback or was lost as its pending
controls became disabled.

**Properties:** `rating: MessageFeedbackValue = null` (`'up' | 'down' | null`, reflected),
`detail?: MessageFeedbackDetailConfiguration` (attribute: false) — one configuration with optional
`reasons?: readonly { id, label }[]` and `commentable?: boolean`; omit it for thumbs-only feedback.
The record and nested reasons are a bounded clone-owned frozen snapshot; malformed, empty, blank,
and later duplicate reason ids are omitted first-wins before selection and submission. Create and
reassign a new detail record after changes.
`detailFor: 'none' | 'up' | 'down' | 'both' = 'down'` (attribute `detail-for`) selects which rating
owns that one detail panel. `disabled: boolean = false` (reflected) makes a recorded rating read-only, and
`pending: boolean = false` (reflected) — set automatically when a submit listener prevents the
submission while host persistence is unresolved; all feedback controls are disabled and the panel
reports busy until that state is resolved.

When the optional comment textarea renders, `spellcheck: boolean = true`,
`autocapitalize: string = ''`, `autocorrect: boolean = true`, and
`wrap: MessageFeedbackWrap = 'soft'` forward to it; they have no effect without that textarea.
`MessageFeedbackWrap` is `'soft' | 'hard' | 'off'`, the native textarea wrap vocabulary.

**Methods:** `focus()` focuses the thumb matching the current `rating` (the up thumb when `null`);
`blur()` blurs both thumbs; `click()` activates that same thumb when enabled.
`getToolbarActions()` returns the ordered logical thumb actions used by an enclosing toolbar.
`finalizePendingSubmit(submissionId?: string): boolean` completes a prevented submit after persistence succeeds, closing the
panel, announcing success, and returning focus to the active thumb.
`revertPendingSubmit(submissionId?: string): boolean` releases
the pending state after failure without clearing the draft or announcing success, restoring the
prior rating and panel state. A detail-panel submit remains open for retry, while a thumbs-only
submit remains panel-free; it likewise accepts an optional `submissionId` and returns `boolean`. The event
supplies a nonblank, never-reused id; a later/current settlement must use that exact id. Legacy
no-argument settlement remains available only for the first transaction that has never been
invalidated; stale or mismatched settlements return `false`.

**Events:** `lr-feedback-change` — `detail: { rating: 'up' | 'down' | null }`, fired when a thumb's
provisional rating changes or clears. `lr-feedback-submit` — cancelable
`detail: { rating: 'up' | 'down' | null; reasonIds: string[]; comment: string; submissionId: string }`, fired for every
terminal thumbs-only choice/clear and by the detail panel's submit button. The pending transaction
is installed before dispatch, so even a synchronous listener may finalize/revert it safely. The
event detail is frozen.
`preventDefault()` holds the panel/control in `pending` and delays
success announcement/focus until `finalizePendingSubmit(detail.submissionId)`; call
`revertPendingSubmit(detail.submissionId)` on failure. The no-argument form is only the documented
legacy first-transaction path.
When uncanceled it retains the synchronous close/announce/focus behavior. The optional comment
`<textarea>`'s native `focus` and `blur` are re-dispatched as bubbling, composed host events.
`lr-toolbar-actions-change` is the no-detail coordination event emitted when the provider's logical
toolbar actions change availability or order.

**CSS parts:** `base` (the root), `thumbs` (wrapper around both thumb buttons), `up-button`,
`down-button`, `panel` (the inline detail disclosure, only rendered when `reasons` is non-empty or
`commentable` is set), `reasons` (the reason-chip group), `comment` (the comment `<textarea>`), and
`submit-button`.

**Themeable custom properties:** six pressed-state hooks, three per thumb —
`--lr-message-feedback-up-active-color` (default `var(--lr-color-success)`),
`--lr-message-feedback-up-active-bg` (default `var(--lr-color-success-quiet)`),
`--lr-message-feedback-up-active-border` (default `var(--lr-color-success)`), and the thumbs-down
trio `--lr-message-feedback-down-active-color`, `--lr-message-feedback-down-active-bg`,
`--lr-message-feedback-down-active-border` (defaulting to `var(--lr-color-danger)`,
`var(--lr-color-danger-quiet)`, `var(--lr-color-danger)`). Each styles the glyph, background, and
border of its thumb only while that thumb is pressed. All six are declared as inline `var()`
fallbacks at the point of use and never on `:host`, so each can be set on the element _or on any
ancestor_ — a whole transcript's feedback controls retint from one declaration. That shape is
required because `::part(up-button)[aria-pressed='true']` is invalid CSS (Shadow Parts forbids an
attribute selector after `::part()`), which previously left overriding the library-wide
`--lr-color-success`/`--lr-color-danger` tokens as the only lever, repainting every other element
reading them. Unset, each falls back to exactly the token its rule used before.

## `lr-push-to-talk`

A mic capture button owning the full `getUserMedia` + `MediaRecorder` lifecycle: permission request,
recording, optional chunked streaming, teardown. The one place in this library that touches the
microphone — no SDK, no LiveKit/ElevenLabs import, native browser APIs only. `mode="hold"` (the
default) is a press-and-hold gesture; `mode="toggle"` is click-to-start/click-to-stop with
`aria-pressed`. Escape cancels the in-progress take in either mode.

For example, `<lr-push-to-talk><span slot="microphone-icon">MIC</span></lr-push-to-talk>` replaces
the idle microphone glyph. Use `recording-icon` separately for the recording state.

While recording, the optional elapsed timer uses the effective locale's decimal digits, suppresses
grouping, and pads its seconds field to two locale-aware digits.

**Properties:** `mode: PushToTalkMode = 'hold'` (`'hold' | 'toggle'`, reflected; invalid writes
normalize to `hold`), `timesliceMs: number = 0` (attribute
`timeslice-ms`) — `> 0` passes a timeslice to `MediaRecorder.start()` and emits `lr-record-chunk` per
slice, `mimeType: string = ''` (attribute `mime-type`) — a `MediaRecorder` MIME type, `deviceId:
string = ''` (attribute `device-id`) — a specific input device, `audioConstraints?:
PushToTalkAudioConstraints` (attribute: false) — merged into the `getUserMedia` audio constraints;
it deliberately excludes `deviceId`, whose single authority is the dedicated property,
`levelEvents: boolean = false` (attribute `level-events`) — opt in to `lr-level`, `maxDurationMs:
number = 0` (attribute `max-duration-ms`) — auto-stop cap, `0` disables it, `showTimer: boolean =
true` (attribute `show-timer`), `disabled: boolean = false` (reflected), plus two getter-only
properties: `state: PushToTalkState` (`'idle' | 'requesting' | 'denied' | 'recording' | 'error'`,
mirrored to `data-state`) and `stream: MediaStream | null` (the live capture stream, assignable straight onto
`lr-audio-visualizer.stream`).

A host `aria-label` names the internal trigger by attribute presence; an explicitly empty value is
preserved instead of being replaced by the generated Hold/Start/Stop label.

`levelEvents`, `maxDurationMs`, and `showTimer` stay reactive during an active recording: changing
them starts or stops their audio-analysis, deadline, or elapsed-time work immediately. A changed
maximum remains measured from the original recording start rather than granting a fresh duration;
setting it to `0` removes the deadline.

**Methods:** `start()`, `stop()`, and `cancel()` drive the capture lifecycle imperatively (mirroring
the pointer/keyboard gestures).

After permission is requested, only a still-active control in the same document may begin
recording; otherwise any stream returned later is immediately stopped. In hold mode, a later held
press in that document can take over one pending permission request, and a held press while
stopping begins after the prior take ends. Only one capture runs at a time.

**Slots:** `microphone-icon` replaces the default mic glyph. `recording-icon` replaces the default
recording-state pulse glyph. Both are
decorative inside the named trigger: their flattened content is inert and hidden from accessibility
APIs, so do not place a second interactive control there.

**Events:** `lr-record-start` (`detail: { stream: MediaStream }`), `lr-record-chunk` (`detail: { blob:
Blob }`, only when `timeslice-ms > 0`), `lr-record-stop` (`detail: { blob: Blob; durationMs: number
}`), `lr-record-cancel` (`detail: null`), `lr-record-error`
(`detail: { error: DOMException | Error }`, covering permission, recorder construction/start, and
recorder runtime failures), `lr-level`
(`detail: { level: number }` — 0–1 amplitude, opt-in via `level-events`), and `lr-record-state-change`
(`detail: { state: 'idle' | 'requesting' | 'denied' | 'recording' | 'error' }`).

**CSS parts:** `trigger` (the capture button), `icon`, `pulse` (rendered only while recording),
`timer` (the localized `M:SS` elapsed-time readout, only while recording and `show-timer`), and `status`
(visible status text for the `requesting`/`denied`/`error`/unsupported states).

**Themeable custom properties:** `--lr-push-to-talk-size` (default `var(--lr-size-3rem)`) — the
trigger button's preferred inline and block size; the shared `--lr-icon-button-size` remains its
minimum hit-area floor even when this value is smaller. `--lr-push-to-talk-recording-color` (default
`var(--lr-color-danger)`) remains the established aggregate fallback for the recording trigger's
border and foreground and the pulse-ring border. Retune those independently with
`--lr-push-to-talk-trigger-recording-border-color`,
`--lr-push-to-talk-trigger-recording-color`, and
`--lr-push-to-talk-pulse-recording-border-color`, each defaulting through
`var(--lr-push-to-talk-recording-color, var(--lr-color-danger))`. All four are inline `var()`
fallbacks at the point of use rather than `:host` declarations, so each can be set on the element or
on an ancestor without repainting every other danger-toned surface. `::part(trigger)[data-state='recording']`
is invalid CSS (Shadow Parts forbids an attribute selector after `::part()`), which is why these
recording-state hooks exist.

**Additional API surface:**

- `blur()` — Forwards host blur to the internal push-to-talk control.
- `focus()` — Forwards host focus to the internal push-to-talk control.
- `click()` — Programmatically starts or stops a take, mirroring a real pointer/keyboard
  activation: in `mode="toggle"` it forwards to the trigger's native `click()`; otherwise it calls
  `stop()` while `state` is `recording` or `start()` otherwise. A no-op while `disabled` or
  unsupported.

## `lr-transcript-feed`

Live captions for an in-progress voice session: speaker-grouped entries, interim-vs-final styling
with in-place upgrades keyed by `id`, and a stick-to-bottom auto-scroll with release, the same
`follow`/`lr-follow-change` contract `<lr-terminal>` uses. Live captions only — recorded-media
transcript sync is a separate concern.

Activating the focused jump action resumes follow and transfers focus to the scroll base when the
action disappears, unless a newer outside focus move takes precedence.

**Properties:** `entries: LyraTranscriptEntry[] = []` (attribute: false) — `LyraTranscriptEntry { id:
string; speaker?: string; text: string; interim?: boolean; timestamp?: LyraTimestamp }` (exported by
this module; `LyraTimestamp = Date | string | number`, normalized through Date/TimeClip). Reconciled
keyed by nonempty, nonblank, first-wins `id` via Lit's `repeat()`; rows whose required `text` is not
a string are omitted before rendering or announcement. A
same-`id` entry with new `text` replaces in place, and a same-`id` entry whose `interim` flips from
`true` to unset/`false` moves from the interim area into the `role="log"` region and announces
exactly once. A collection with no valid entry renders the empty state. Interim entries render
_after_ the log container — visible, but structurally outside
it — so per-token mutations are never spoken by assistive tech. That announcement does **not** come
from the shadow `role="log"` region, which is explicitly `aria-live="off"`: a live region inside a
component's own shadow root is not reliably announced (JAWS with Firefox ignores one outright).
Each newly final entry's `text` is announced once through the shared light-DOM polite live region
instead, the same route `<lr-chat-viewport>` and `<lr-terminal>` take. The entries a feed is
_mounted_ with are treated as existing transcript rather than newly spoken captions, so the first
render only records them. `follow: boolean = true`
(reflected), `showTimestamps: boolean = false` (attribute `show-timestamps`), `formatTimestamp?:
(date: Date) => string` (attribute: false), `maxRenderedEntries: number = 500` (attribute
`max-rendered-entries`) — `0` explicitly renders every entry; a positive value keeps only the newest N,
`sessionId: string = ''` (attribute `session-id`) — changing session identity clears finalized-ID
announcement history and treats the new session's current entries as a silent baseline,
`label?: string` — accessible name for the `role="log"` region. Omitting it uses the localized
`transcriptFeedLabel`; an explicit empty string intentionally leaves the role unnamed. `accessibleLabel: string | null = null`
(attribute `aria-label`) — overrides the log's computed accessible name, winning over `label` and
the localized default; attribute-reflects from a host-level `aria-label`.

**Methods:** `scrollToBottom()` re-engages `follow` and instantly scrolls to the current latest
entry. The built-in jump action delegates to this method.

**Slots:** `empty` — custom empty state (default: the localized "No transcript yet").

**Events:** `lr-follow-change` — `detail: { following }`, fired when a user scroll changes follow
state or the built-in jump action re-engages it. Direct `follow` assignments and
`scrollToBottom()` calls are controlled input and do not echo an event.

**CSS parts:** `base` (the scroll container), `log` (the `role="log"` region wrapping final entries
only), `entry`, `speaker` (omitted for a row repeating the previous row's speaker), `text`
(`dir="auto"`), `timestamp` (only while `show-timestamps`), `interim` (present alongside `entry` on
an interim row), `interim-area` (the wrapper holding interim rows, rendered only while at least one
interim entry exists), `jump-button` (shown only while `follow` is `false`), and `empty`.

## `lr-handoff-divider`

A labeled semantic separator marking control transfer between agents in a transcript ("Transferred
to Research Agent"), with an optional agent avatar. Purely presentational: no events, no
interactivity, no restore semantics. The computed label is announced once, on first connect,
through an internal `<lr-live-region>`.

**Properties:** `toAgent: string = ''` (attribute `to-agent`), `fromAgent: string = ''` (attribute
`from-agent`), and `label: string = ''`. With both agent names the localized text is “Transferred
from {from} to {to}”; `label` overrides it. An explicit host `aria-label`, including an empty one,
wins for the separator and mount-time announcement.

**Slots:** `avatar` — the incoming agent's `<lr-avatar>` (or icon), hidden entirely while empty.

**CSS parts:** `base` (the separator root, `role="separator"`), `line` (each of the two flanking
rules), `chip` (the visual `aria-hidden` chip wrapping the avatar and label), `avatar` (wrapper
around the `avatar` slot, only shown while the slot has content), and `label`.

## `lr-chat-viewport`

The transcript scroll container: owns stick-to-bottom behavior while an answer streams, the "jump to
latest" pill, and the unread divider. Two supported content shapes, auto-detected: ordinary element
children (typically `lr-chat-message`s — _slotted mode_), or exactly one `lr-virtual-list`
(_virtual mode_, detected via `instanceof`). In virtual mode this component defers all scrolling to
the slotted list's own `scrollToIndex()`. Follow/release state machine: while `follow` is engaged,
content growth re-scrolls to the end; release happens only on a user-intent gesture (wheel,
touchmove, scrollbar-drag, or PageUp/ArrowUp/Home while the log region has focus) that leaves the
view more than `bottomThreshold` from the end — a scroll caused by this component's own programmatic
scrolling, or by a layout shift, never releases it. Reaching the bottom again by any means re-engages
`follow`. The shadow `role="log"` always remains `aria-live="off"`, which avoids announcing every
streaming token. Consumers that append complete messages at an announcement-safe cadence can opt
into `polite` or `assertive`; each newly appended direct child's accessibility-exposed text is then
copied to the matching shared light-DOM announcement sink in the component's `ownerDocument`.
Hidden, inert, `aria-hidden`, and CSS-hidden content is omitted. Existing declarative children stay
silent on mount, and appending the same text again creates another announcement. `off` acquires no
sink and produces no announcements.

**Properties:** `follow: boolean = true` (reflected) — component-managed stick-to-bottom state,
host-writable: setting `true` scrolls to the end and re-engages following, setting `false` releases
it. `bottomThreshold: number = 24` (attribute `bottom-threshold`) — px distance from the end still
counted as "at bottom." `unreadStartIndex: number | null = null` (attribute `unread-start-index`) —
index of the first unread item (element-child index in slotted mode, `items` index in virtual mode);
`null` disables both the divider and the pill's unread count. `live: 'off' | 'polite' | 'assertive' =
'off'` (reflected) — policy for the shared light-DOM announcement sink; the internal log itself
remains non-live. Keep `off` for token-by-token streaming and opt in only when complete messages are
appended as direct children at an announcement-safe cadence.
`label: string = ''` — accessible name
for the log region, defaults to the localized `chatViewportLabel`. `accessibleLabel: string | null =
null` (attribute `aria-label`) — host `aria-label`, forwarded to the internal `role="log"` element
(an `aria-label` left on the host itself names nothing, since the log role lives inside the shadow
root); wins over `label` and the localized default.

**Methods:** `scrollToBottom(options?)` — scrolls to the end and re-engages `follow`; default
`smooth`, forced to `auto` under `prefers-reduced-motion`. `scrollToUnread(options?)` — scrolls the
unread divider to the top of the view, resolving `false` when `unreadStartIndex` is `null`/out of
range; does not re-engage `follow`.

**Events:** `lr-follow-change` — `detail: { following }`, fired whenever `follow` flips (user
scroll-up release, or reaching the bottom again). Never fired for the initial mount state.

Activating a focused jump-to-latest pill, or directly setting `follow = true`, transfers focus to
the transcript's stable scroll owner after the pill disappears: `[part="scroll"]` in slotted mode,
or the nested virtual list's real focus owner in virtual mode. Focus that moved elsewhere before the
update is preserved.

**Slots:** default — the transcript: ordinary element children, or exactly one `lr-virtual-list`.

Only a direct child `lr-virtual-list` selects virtual mode; bubbled list events from nested message
content are ignored. In slotted mode the visual unread divider remains an absolutely positioned
paint layer while a separate hidden semantic boundary is inserted immediately before the first
unread child, so DOM/accessibility order matches the visible boundary. Reordering an existing child
does not announce it again; only genuinely appended complete-message nodes do. A primary
`pointerdown` begins scrollbar-drag tracking only when the scroll container itself is the event
target, never for arbitrary descendant controls.

**CSS parts:** `base` (the positioning root), `scroll` (the scroll container, non-live `role="log"`,
`tabindex="0"`; in virtual mode it stops scrolling itself, keeps the role, and drops its tab stop), `content` (the
slotted-content wrapper the growth observers watch), `jump-pill` (the built-in jump-to-latest button,
absent while `follow` is engaged), `unread-divider` (the "New messages" separator, slotted mode
only).

Renders no messages and computes no unread state itself — the host supplies `unreadStartIndex`; no
virtualization of its own (`lr-virtual-list`); not a generic overflow surface (`lr-scroller`); no
message semantics (`lr-chat-message`).

**Sizing in virtual mode.** `[part='scroll']` steps aside and the slotted `lr-virtual-list`'s own
viewport becomes the real scroller, so it is given this component's full height — otherwise it would
scroll inside `lr-virtual-list`'s `24rem` default no matter how tall the viewport is. An explicit
`block-size` on the slotted list is what makes that resolvable: without it the list host is
auto-height, its own base percentage chains to `auto`, and the two size each other circularly.
`<lr-thread-list>` solves the same problem by turning the internal list's shipped `24rem` into a
flex-basis through `::part(base)`, which is not available here — that list lives in the _consumer's_
light DOM, and `::slotted()` cannot be followed by `::part()`. Virtual mode therefore inherits this
component's existing requirement of a height-bounded parent, exactly as slotted mode's own
`[part='scroll']` already does. A document-tree declaration on the list (a consumer's own rule or an
inline style) still wins over the built-in one.

```html
<lr-chat-viewport unread-start-index="12">
  <lr-chat-message message-role="user">…</lr-chat-message>
  <lr-chat-message message-role="assistant" status="streaming">
    <lr-streaming-text streaming></lr-streaming-text>
  </lr-chat-message>
</lr-chat-viewport>
<lr-chat-composer status="streaming"></lr-chat-composer>
<script type="module">
  const viewport = document.querySelector("lr-chat-viewport");
  viewport.querySelector("lr-streaming-text").content = partial;
  viewport.addEventListener("lr-follow-change", (e) => console.log(e.detail.following));
</script>
```

## `lr-suggestion-chips`

Starter prompts (empty thread) and follow-up suggestions (after a response) as a horizontally
scrollable chip row; activation hands the prompt to the host, which decides whether to compose it
into an input or send it directly. Never writes into a composer or sends anything itself.
Streaming-friendly: chips render through a keyed `repeat()` on `suggestionId`, so replacing
follow-ups mid-conversation preserves focus on any chip whose identifier survives; when the focused
identifier disappears, focus repairs to the nearest surviving occurrence without overriding a newer
external focus move.

**Properties:** `suggestions: readonly LyraChatSuggestion[] = []` (attribute: false) —
`LyraChatSuggestion { suggestionId: string; label: string; icon?: string; detail?: string; disabled?: boolean }`
(exported here). Identifiers must be nonempty and unique; invalid/later duplicates are omitted with
the first valid occurrence winning. The input is clone-owned, bounded, and frozen; reassign a new
array after changing the sequence or a row. `icon` is an optional
peer-neutral literal hint (for example, an emoji), rendered decoratively before the text, and
`detail` is an optional secondary line. `disabled` marks a suggestion non-actionable: its chip
renders a genuinely disabled `<button>` (no roving tab stop, no hover/press affordance), activating
it emits nothing, and arrow-key/Home/End roving navigation steps past it. Empty renders nothing at
all. `wrap: boolean = false`
(reflected) — wraps into multiple rows instead of a single horizontally scrollable line. `label?:
string` — accessible name for the group. Omitting it uses the localized `suggestionsLabel`; an
explicit empty string intentionally leaves the group unnamed.

**Events:** `lr-suggestion-select` — `detail: { suggestionId, label }`.

**CSS parts:** `base` (the labeled group), `row` (the flex container holding the chips, present in
both the wrapping and the scrolling layout), `chip` (each suggestion button), `chip-icon` (the
optional decorative literal icon), `chip-label` (the primary text), `chip-detail` (the secondary
line, only rendered when `detail` is set).

**Themeable custom properties:** `--lr-suggestion-chips-justify` (default `flex-start`) — main-axis
packing of the chip row. Use `center` to center the chips under centered empty-state text: it centers
every line, the wrapped final one included, which styling `::part(base)` as a centered flex container
cannot do (once the chips wrap, the row fills the available inline size and each line packs to the
start). `--lr-suggestion-chips-hover-bg` (default `var(--lr-color-brand-quiet)`) — a `chip`'s
background on hover. `--lr-suggestion-chips-hover-border` (default `var(--lr-color-brand)`) — a
`chip`'s border color on hover. All three are declared as `var()` fallbacks at the point of use, not
on `:host`. `--lr-suggestion-chips-disabled-opacity` (default `0.5`) — opacity of a chip whose
suggestion sets `disabled`. Plus shared tokens `--lr-space-xs/-m/-2xs`,
`--lr-color-border/-surface/-text/-text-quiet`, `--lr-radius-pill`, `--lr-font-size-xs`,
`--lr-focus-ring-width/-color/-offset`.

**Optional peer deps:** none.

Keyboard: roving tabindex across chips; ArrowLeft/ArrowRight (direction-aware) plus Home/End;
Enter/Space activate. Renders inside an internal `lr-scroller` (`orientation="horizontal"`,
`without-scrollbar`) unless `wrap` is set.

```html
<lr-suggestion-chips></lr-suggestion-chips>
<lr-chat-composer></lr-chat-composer>
<script type="module">
  const chips = document.querySelector("lr-suggestion-chips");
  const composer = document.querySelector("lr-chat-composer");
  chips.suggestions = followUps;
  chips.addEventListener("lr-suggestion-select", (e) => (composer.value = e.detail.label));
</script>
```

## `lr-thread-list`

The conversation sidebar: a grouped, searchable list of chat sessions with pin/archive/delete/rename
affordances. _Data mode_ (at least one valid `threads` record, or no valid records with nothing
slotted) renders every row as a `lr-conversation-item` inside an internal `lr-virtual-list` — virtualized by
construction, scroll position and per-row state survive a `threads` replacement; zero rows renders
the built-in empty state. _Slotted mode_ (no valid `threads` records _and_ real slotted content) renders
host-supplied `lr-conversation-item`s from the default slot as-is: no grouping, virtualization, or
row actions in that mode. No thread CRUD or persistence — every mutation
(`lr-thread-pin`/`-archive`/`-delete`/`-rename`) is a controlled event carrying the _requested_ new
state; the host mutates `threads`.

A conversation row with `slot=""` belongs to the default slot exactly like a row with no slot
attribute, including after reconnect. Named slots retain their distinct roles.

ArrowUp/ArrowDown/Home/End navigation skips rows that are disabled, hidden, `aria-hidden`, or
`inert` (including an inert ancestor introduced by `wrapRow`). Arrow navigation continues through
the complete item model at a virtual-window edge and mounts the next available row before moving
focus. Home/End always resolve the first/last thread from that complete model, even when focus
starts in a middle window; group records, collapsed-group contents, and unavailable endpoint rows
are skipped rather than becoming false boundaries.

**Exported types:** `LyraChatThread { id: string; title: string; excerpt?: string; timestamp?: Date |
string | number; pinned?: boolean; archived?: boolean }`; `ThreadRowAction = 'pin' | 'archive' |
'delete'`; `ThreadListGrouping = 'date' | 'custom' | 'none'`; `ThreadBucketKey = 'pinned' |
'today' | 'yesterday' | 'previous7' | 'previous30' | `month:${string}` | 'archived'`;
`ThreadGroupContext { id: string; threads: readonly LyraChatThread[]; bucket?: ThreadBucketKey;
date?: Date }`; and `ThreadGroupToggleDetail { groupId: string; collapsed: boolean }` (the shared
payload type for the `lr-group-toggle-request`/`lr-group-toggle` pair). `LyraThreadList` and
`LyraThreadListEventMap` are exported alongside them. The class
module, normal and stable tag-shaped registration entries, conversation family entry, and package
root all retain this complete thread-list surface; the former `ChatThread` name is not retained.
Data-mode thread ids must be nonempty, nonblank, and unique, and every row must have a string
`title`; invalid rows and later duplicates are omitted with the first valid occurrence winning
before the mode is selected, so focus, actions, slot ownership, and emitted `conversationId`
values remain unambiguous.

Display fields are captured when `threads` is assigned. After a change, create and assign a new
collection; changing an assigned record or mutating the assigned array does not update the view.
`filter`, `groupBy`, row callbacks, and group contexts receive the original source records.

**Properties:** `threads: LyraChatThread[] = []` (attribute: false). `activeConversationId: string = ''`
(attribute `active-conversation-id`) — data mode:
marks the matching row `active`/`aria-current` and scrolls it into view. `searchable: boolean =
false` (reflected) — shows the built-in search field, including a `part="clear-button"` icon button
that appears next to it once it has a value (never when empty), clears it on click, fires the same
`lr-filter-change`/`lr-query-change` event typing already fires, and returns focus to the field. Its
accessible name is the localized `clear` message (the same key `<lr-input>`'s own clear button
uses). `size?: LyraSize` (reflected) — opt-in density tier for that search field, on the library's
one six-step ladder (`2xs`/`xs`/`s`/`m`/`l`/`xl`, or the Web Awesome/Shoelace `small`/`medium`/`large`
spellings, accepted as authored). A tier gives the field the row height, text size, gutters and
corner radius an `lr-input` of that tier has, so the sidebar's own filter box lines up with an
adjacent themed search field. With no `size` the field keeps exactly the gutters, corner radius and
inherited text size it shipped with, so existing markup renders unchanged; an unsupported value
normalizes to the omitted state and removes the attribute rather than snapping to a tier. Only the
field is tiered — the gutter around it and the clear button keep their own sizes, and have their own
custom properties. `filter?: (thread, query) => boolean`
(attribute: false) — overrides the default case-insensitive `title` + `excerpt` substring match.
`grouping: ThreadListGrouping = 'date'` — data mode: bucket rows under localized date headers
(Pinned/Today/Yesterday/Previous 7 days/Previous 30 days/one bucket per month/Archived), use the
arbitrary grouping callbacks below, or render a flat list. `groupBy?: (thread: LyraChatThread) => string`
(attribute: false) derives each group id in `grouping="custom"`; rows whose callback throws or
returns a malformed or blank ID are omitted from that grouped view, and omitting the callback leaves
custom mode flat. `getGroupLabel?: (context: ThreadGroupContext) => string` (attribute: false) supplies the
plain-text accessible/visible label; `renderGroupAdornment?: (context) => TemplateResult` supplies
separate rich content beside the toggle without nesting it inside the button. `groupOrder?: string[] | ((a: string, b:
string) => number)` (attribute: false) supplies an explicit order or comparator; ids omitted from an
array follow in first-seen order. `collapsedGroupIds: string[] = []` (attribute: false) is the
collapsed state for both date and custom groups, **self-managed by default**: activating the
built-in group toggle updates this array directly. A collapsed group's header remains in the
virtual list while its conversation rows are removed from the virtual-list item/measurement set.
Prevent the default of the cancelable `lr-group-toggle-request` event (see **Events** below) to
veto that write and keep this property fully controlled instead — the only behavior it had before
self-management existed. Group headers and threads use separate
internal key namespaces, so every public `activeConversationId` remains a raw thread id — even a value such as
`group:today` cannot collide with the `today` group header. `rowActions: ThreadRowAction[] = []`
(attribute: false, each `'pin' | 'archive' | 'delete'`) —
data mode only: built-in icon buttons rendered into each row's `actions` slot. `showArchived: boolean
= false` (attribute `show-archived`, reflected) — data mode: include `archived` threads (in their own
trailing group). `renamable: boolean = true` (reflected) — forwarded to each data-mode row's inline
rename. `compact: boolean = false` (reflected) — data mode only: forwarded to each row
`lr-conversation-item`'s own `compact`, tightening every row's padding and gaps from one attribute
(the density itself lives on the row item; retune it through
`--lr-conversation-item-compact-padding`/`-gap` on this element or any ancestor). Slotted mode is a
deliberate no-op — that mode renders host-supplied items as-is, so the host sets `compact` on its own
items there, the same division of responsibility slotted mode already has for every other row
property. `stickyGroups: boolean = false` (attribute `sticky-groups`, reflected) — data mode: pins
the current date/custom group's header to the top of the scroll viewport while its rows are in view,
pushing it off as the next group's header arrives. Group headers are ordinary virtualized rows, so
this renders an `aria-hidden` copy of the header into the internal `lr-virtual-list`'s sticky layer:
the real row keeps the `role="heading"`/`aria-level` semantics and its interactive toggle. The
pinned copy is inert, pointer-transparent presentation content: its toggle and adornments do not
receive interaction, and it adds no second tab stop. Default `false` renders exactly as before; `grouping="none"` has no
headers to pin, so it is a no-op there. `label?: string` — accessible name for the list region.
Omitting it uses the localized `threadListLabel`; an explicit empty string intentionally leaves the
list unnamed. `error: boolean = false` (reflected) — data mode only: reports a failed thread-list
load. While set, the built-in `<lr-empty>` failed-load state (matching `<lr-table>`'s own `error`
contract) replaces the virtual list/empty state; `error` beats the built-in empty state.
`errorHeading?: string` (`error-heading`) — failed-load heading override; omitted localizes the
same `tableLoadFailed` default `<lr-table>` uses. `errorDescription: string = ''`
(`error-description`) — failed-load supporting copy. `wrapRow?: (thread: LyraChatThread, row: TemplateResult) =>
TemplateResult` (attribute: false) — data mode only: wraps each row's built-in
`lr-conversation-item` with host-supplied content that has no home in the item's own `label`/`excerpt`/`meta`/`actions` surface (e.g. a leading purpose
icon — the item has no default slot to receive one); unset renders the built-in row unwrapped.
`renderActions?: (thread: LyraChatThread) => TemplateResult` (attribute: false) — data mode only:
appends host-supplied content (re-invoked per row on every render, e.g. an `lr-dropdown` containing `lr-menu` with custom
actions) after the built-in `rowActions` output in each row's `actions` slot; events it fires reach
the host normally and never trigger `lr-select`. An open nested `lr-dropdown` keeps its virtual row
above later rows even if focus temporarily leaves the menu. 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`
(attribute: false) — renders rich content into the row item's own `excerpt` slot, winning over the
plain-string `excerpt` property (e.g. a server-highlighted search-match snippet), while leaving the
built-in label layout and inline-rename affordance untouched. `<mark>` descendants returned by this
hook receive the default, component-themeable highlight treatment documented below.
`renderMeta?: (thread: LyraChatThread) => TemplateResult` (attribute: false) — appends structured
metadata in the row's meta region.
`renderRowContent?: (thread: LyraChatThread) => TemplateResult` (attribute: false) — replaces the
conversation item's label/excerpt/meta content area with custom non-interactive row content.
`formatDate?: (date: Date) => string` (attribute: false) — overrides month-group date formatting.
Use `getGroupLabel` for every date/custom group label. When `wrapRow` is set, its
returned content is placed inside the library-owned `row-wrapper` part; that wrapper surrounds the
complete built-in row, including built-in `rowActions` and appended `renderActions` content inside
the conversation item's `actions` slot. Use `row-wrapper` for whole-row layout, `row-actions` for
the callback-output region, and the `row-item-*` parts for the conversation item's own internals.
With `wrapRow` unset, no wrapper element or `row-wrapper` part is rendered.

**Methods:**

- `itemElement(conversationId)` — the rendered `lr-conversation-item` for one thread's
  `conversationId` (data mode) or one slotted item's own `conversation-id` (slotted mode), or
  `null` when it is not currently rendered: filtered out by `showArchived`/search, windowed out of
  the virtualized viewport, removed from `threads`, or never present

`conversationId` is not a second identity scheme layered on top of the list — it is the same stable
id every row already carries on its own public `conversation-id` attribute/property, which every
row event (`lr-select`, `lr-thread-pin`, `lr-thread-archive`, `lr-thread-delete`,
`lr-thread-rename`) already keys off. `itemElement()` documents an accessor for it instead of a
consumer piercing this component's shadow root (and, in data mode, the nested internal
`lr-virtual-list`'s own shadow root) to walk rendered rows the way this component's own internals
do. It reads the DOM as it stands, so `await threadList.updateComplete` first and treat `null` as
"not rendered right now" — in particular, a data-mode row can exist in `threads` yet still return
`null` while it is scrolled outside the virtualized window.

**Slots:** default — slotted mode only: host-supplied `lr-conversation-item`s, rendered in order.
`empty` — replaces the built-in empty state. `error` — replaces the built-in failed-load state,
including its retry button, while `error` is set.

**Events:** data mode: `lr-select` (`detail: { conversationId }`), `lr-thread-pin`
(`detail: { conversationId, pinned }` — the requested new state), `lr-thread-archive`
(`detail: { conversationId, archived }`), `lr-thread-delete` (`detail: { conversationId }`, no
built-in confirmation), `lr-thread-rename` (`detail: { conversationId, label }`, correlated and
re-emitted from the owned row), `lr-filter-change` (`detail: { text, matchCount }`). Slotted mode
instead emits `lr-query-change` (`detail: { text }`) and never claims a match count it cannot own.
`lr-group-toggle-request` (`detail: { groupId, collapsed }`, cancelable) — proposed before a
custom/date group's collapse state changes; calling `preventDefault()` skips the built-in
`collapsedGroupIds` write and suppresses the following `lr-group-toggle`, leaving the group's
collapse state fully controlled. `lr-group-toggle` (`detail: { groupId, collapsed }`) — the
change was accepted and, unless `lr-group-toggle-request` was prevented, already applied to
`collapsedGroupIds`; native group buttons provide Enter/Space activation and explicit
`aria-expanded="true"|"false"` regardless. A consumer that already listens for `lr-group-toggle`
and reassigns `collapsedGroupIds` itself keeps working unchanged: this component's own write, when
it happens, always precedes that listener in the same synchronous dispatch, so the host's own
assignment simply wins last. `searchable` only: `blur`/`focus` (no detail) — re-dispatched from
the internal search `<input>`'s own `blur`/`focus`, bubbling and composed unlike the native events,
which are neither. `lr-retry` (`detail: null`, cancelable) — the built-in `[part='retry-button']`
was activated, only rendered while `error` is set; the default action clears `error`,
`preventDefault()` leaves it set instead.

**CSS parts:** `base`, `search`/`search-input` (the search field wrapper and `<input
type="search">`), `clear-button` (clears the search field; rendered only while it has a value,
mirroring `<lr-input>`'s own `clearable` contract's part name), `list` (the list region), `empty`,
`error` (the built-in `<lr-empty>` host rendered while `error` is set, with `error-base`/
`error-icon`/`error-heading`/`error-description`/`error-actions` exported from its own parts, plus
`retry-button` for the built-in retry control), `viewport` (the actual internal virtual-list
scroll container, suitable for scrollbar styling), `row-action` (a built-in pin/archive/delete icon
button), `pin-glyph` (the small pin indicator on a pinned row), `group-header`, `group-toggle`,
`group-label`, `group-adornment`, `group-icon`, `group-sticky` (`sticky-groups` only: the pinned copy of the current
group's header, exported from the internal `lr-virtual-list`'s sticky layer — it wraps a full copy of
the `group-header`/`group-toggle`/`group-label`/`group-adornment`/`group-icon` markup, so those parts style the real
header row and the pinned copy alike, and the band itself is where a shadow or bottom border
belongs), `row` (all exported across the internal `lr-virtual-list` shadow
boundary), `row-wrapper` (the wrapper around `wrapRow` output, only present when `wrapRow` is set;
row-only — group headers are never passed through `wrapRow`, so they never carry it), and
`row-start`/`row-excerpt`/`row-content`/`row-meta`/`row-actions` (the library-owned wrappers around
their corresponding render-hook output; inherited fonts, layout values, and theme custom properties
reach callback-rendered descendants through these parts). `row-excerpt` wraps `renderExcerpt`
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`,
`row-item-label`, `row-item-label-input`, `row-item-rename-button`, `row-item-excerpt`,
`row-item-meta`, `row-item-timestamp`, `row-item-actions`.

**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`),
`--lr-thread-list-excerpt-highlight-radius` (default `var(--lr-radius-xs)`), and
`--lr-thread-list-excerpt-highlight-padding` (default `0`). These properties inherit through the
internal virtual-list shadow tree, so set them on `lr-thread-list` or any ancestor. They do not style
marks returned by `renderRowContent` or any other hook.

**Themeable control states:** `--lr-thread-list-group-toggle-hover-bg` (default
`var(--lr-color-surface-raised)`), `--lr-thread-list-group-toggle-hover-color` (default
`var(--lr-color-text)`), `--lr-thread-list-group-toggle-active-bg` (default `color-mix(in oklab,
var(--lr-thread-list-group-toggle-hover-bg, var(--lr-color-surface-raised)),
var(--lr-color-mix-partner) var(--lr-color-mix-active))`), and
`--lr-thread-list-group-toggle-active-color` (default
`var(--lr-thread-list-group-toggle-hover-color, var(--lr-color-text))`) style group-toggle hover
and pressed states. `--lr-thread-list-row-action-hover-bg` (default
`var(--lr-color-surface-raised)`), `--lr-thread-list-row-action-hover-color` (default
`var(--lr-color-text)`), `--lr-thread-list-row-action-active-bg` (default `color-mix(in oklab,
var(--lr-thread-list-row-action-hover-bg, var(--lr-color-surface-raised)),
var(--lr-color-mix-partner) var(--lr-color-mix-active))`), and
`--lr-thread-list-row-action-active-color` (default
`var(--lr-thread-list-row-action-hover-color, var(--lr-color-text))`) do the same for row actions.

**Themeable search geometry:** `--lr-thread-list-search-padding` (default `var(--lr-space-s)`) is
the gutter around the search row and `--lr-thread-list-search-gap` (default `var(--lr-space-xs)`)
the gap between the field and its clear button; neither follows `size`.
`--lr-thread-list-search-min-height` and `--lr-thread-list-search-font-size` are unset while `size`
is — the field is then as tall as its own text and inherits the ambient text size — and a tier
resolves them to that tier's shared form-control height and font size.
`--lr-thread-list-search-padding-inline` (default `var(--lr-space-s)`),
`--lr-thread-list-search-padding-block` (default `var(--lr-space-xs)`) and
`--lr-thread-list-search-radius` (default `var(--lr-radius)`) are replaced by the tier's shared
form-control values when `size` is set. `--lr-thread-list-search-clear-size` (default
`var(--lr-size-1-5rem)`) is the clear button's box; it never follows `size`, because that button is
a tap target floored at `--lr-icon-button-size` rather than a text box. Every one of these wins over
the tier, so a consumer can take a tier and then move one value.

**Keep the two prefixes straight — they are different surfaces.** The `row-*` parts wrap _this_
component's own render-callback output (`wrapRow`, `renderStart`, `renderExcerpt`,
`renderRowContent`, `renderMeta`, `renderActions`); the `row-item-*` parts are the row item's
_internals_. Row density
in particular lives in `row-item-base`'s padding and `row-item-label`'s font size, so
`::part(row-item-base)` is the supported way to build a dense sidebar.

For plain row density, prefer the `compact` property above — it forwards straight to the row item's
own density knob. The `row-item-*` parts remain the lever for tuning beyond it (a different font
size, a different padding ratio):

```css
lr-thread-list::part(row-item-base) {
  padding-block: 0.25rem;
}
lr-thread-list::part(row-item-label) {
  font-size: 0.8125rem;
}
```

Do **not** reach for `::part(row) { --lr-theme-space-s: … }` instead. That is a whole-subtree
retheme: it shrinks everything nested inside the row, including the items of a `renderActions` menu,
which pushes their touch targets below the accessible minimum. The `row-item-*` parts exist so row
density can be tuned without that blast radius.

**Sizing:** the internal list fills whatever height this component is given, with no consumer CSS —
`[part='viewport']` is the real scroll container, and it falls back to `lr-virtual-list`'s own `24rem`
default only when the container has no resolvable height. This is deliberately _not_ implemented by
setting `--lr-virtual-list-height: 100%`: that percentage resolves against this host, which is a flex
item, so in an auto-height container it chains to `auto` and the viewport either collapses to zero
(with no rows) or grows to the full un-virtualized content height (with rows) — defeating
virtualization in both directions. Instead the list host is made a column flex container, which turns
the shipped `24rem` into a _flex-basis_: it grows to fill a bounded pane, shrinks below `24rem` in a
short one, and falls back to exactly `24rem` in an auto-height container.

`sticky-groups` keeps the current date group's header visible while scrolling through a long sidebar;
style the pinned band with `lr-thread-list::part(group-sticky)`.

```html
<lr-thread-list searchable sticky-groups></lr-thread-list>
<script type="module">
  const list = document.querySelector("lr-thread-list");
  list.threads = threads;
  list.activeConversationId = activeThreadId;
  list.rowActions = ["pin", "archive", "delete"];
  list.addEventListener("lr-select", (e) => openThread(e.detail.conversationId));
</script>
```

Composed with `lr-multi-split` (or `lr-app-rail` + `lr-responsive-panel`): thread-list in the start
pane driving `activeConversationId`, `lr-chat-viewport` + `lr-chat-composer` in the main pane.

## `lr-checkpoint`

An inline conversation restore point: a labeled marker between messages whose Restore affordance
confirms inline, then hands the host a `lr-restore` event. This component persists and restores
nothing itself — host state in, events out. Not a handoff or plain rule
(`lr-handoff-divider`/`lr-divider`); not branch navigation across regenerated variants
(`lr-branch-picker`); not recorded-run playback (`lr-sequence-playback`).

**Properties:** `checkpointId: string = ''` (attribute `checkpoint-id`) — opaque id echoed in the
`lr-restore` event detail. `label: string = ''` — checkpoint name; the localized `checkpointLabel`
fallback renders while empty. `timestamp?: LyraTimestamp` (`Date | string | number`, attribute:
false) — optional creation
time, rendered as `<time datetime>`, default `hour:minute` in `effectiveLocale`; invalid strings are
treated as unset. `formatTimestamp?: (date: Date) => string` (attribute: false) — overrides the
default rendering. `restorable: boolean = true` — when `false`, renders a plain marker with no
button. `confirmRestore: boolean = true` (attribute `confirm-restore`) — gates the event behind an
inline confirm step; a string-aware converter parses `confirm-restore="false"` correctly from plain
HTML. `restoring: boolean = false` (reflected) — host-set busy state: the Restore button becomes
`aria-disabled="true"` with a spinner beside the localized "Restoring…" text.

**Slots:** default — optional supplemental content under the marker row (e.g. what changed since
this point).

**Events:** `lr-restore` — `detail: { checkpointId, label }`; fired on Restore activation, after
the inline confirm when `confirmRestore` is on. Not cancelable.

**Methods:** `click()` forwards to the current Restore action only when restoration is available.
The confirm prompt names both Confirm and Cancel through `aria-describedby`; Escape/cancel restores
focus transactionally, and a same-turn controlled change that removes confirmation never lets a
stale focus continuation win.

**CSS parts:** `base` (`role="group"`), `line` (each of the two flanking rules), `icon` (bookmark
glyph), `label`, `timestamp`, `restore-button` (only while `restorable`), `confirm-group`,
`confirm-prompt`, `confirm-button`, `cancel-button`.

**Themeable custom properties:** `--lr-checkpoint-spin-duration` (default
`var(--lr-transition-ambient)`, the library's compound duration/timing-function token for infinite
"still alive" motion) — the restoring spinner's rotation cycle. Because that value carries a timing
function as well as a duration, it can only be spliced into the `animation` shorthand, never
assigned to `animation-duration` alone. The spinner stops outright under
`prefers-reduced-motion: reduce`.

```html
<lr-checkpoint checkpoint-id="ck_18" label="Before refactor"></lr-checkpoint>
<script type="module">
  const checkpoint = document.querySelector("lr-checkpoint");
  checkpoint.timestamp = t;
  checkpoint.addEventListener("lr-restore", (e) => restoreTo(e.detail.checkpointId));
</script>
```

## `lr-usage-badge`

Compact, static resource strip for one message or run — tokens in/out, cost, latency — with a
hover/focus tooltip breakdown. Purely formatting: computes no counts, rates, or prices; every segment
is independently optional, and with nothing set, nothing renders at all (not even a focusable shell).
The tooltip reuses `lr-tool-call-chip`'s hover/focus/Escape/`aria-describedby` contract wholesale.
Not `lr-context-meter` (occupancy of a fixed capacity); not `lr-generation-metrics` (live, with a
Stop button) — this is static after the fact.

Removing `cost-text` or `summary` safely omits that content; explicit empty values remain empty and
later values restore it. An open tooltip participates in shared Escape ordering even while only
hovered, and dismissal preserves focus elsewhere.

**Properties:** `tokensIn?: number` (attribute `tokens-in`) — input tokens, normalized to a
non-negative integer, locale-formatted; segment omitted while unset/non-finite. `tokensOut?: number`
(attribute `tokens-out`) — same rules. `costText: string = ''` (attribute `cost-text`) —
pre-formatted cost (e.g. `"$0.012"`), rendered verbatim. `latencyMs?: number` (attribute
`latency-ms`) — formatted with the shared duration algorithm (`820 -> "820ms"`, `1500 -> "1.5s"`), or
`formatLatency` when set. `formatLatency?: (ms: number) => string` — overrides the built-in duration
algorithm (which has no minutes/hours tier) in both the visible strip and the tooltip row; mirrors
`lr-activity-feed`'s `formatTimestamp` convention. `abbreviate: boolean = false` (reflected) — token
counts render via `Intl.NumberFormat` `notation: 'compact'` (`12345 -> "12K"`); the tooltip always
shows full grouped figures. This badge has no density mode: the old `compact` spelling of this
property was removed in 9.0.0 (it collided with `compact`'s density meaning everywhere else in the
library) — rename `compact` to `abbreviate`; a stale `compact` attribute is inert. `summary: string =
''` supplies visible fallback text when no built-in segment is present.

**Slots:** `summary` — visible summary when no built-in segment is set (takes precedence over the
property); `details` — extra rows appended below the built-in tooltip breakdown (e.g. cache-read
tokens). Interactive descendants are inert because this is a tooltip, while their accessible text
is mirrored into the trigger description. Details without a visible summary remain non-focusable.

**CSS parts:** `base` (a focusable non-button `role="group"` only when content is both visible and
describable), `summary`, `tokens-in`, `tokens-out`, `cost`, `latency`, `tooltip`.

The anchored breakdown tooltip is a floating surface and paints from the **shared overlay-surface
family** (16.0.0): `--lr-overlay-surface` (default `var(--lr-color-surface-overlay)`),
`--lr-overlay-border` (default `var(--lr-color-border)`) and `--lr-overlay-shadow-anchored` (default
`var(--lr-shadow-m)`). None is declared on `:host`, so one declaration on `:root` — or on any
ancestor, to scope it — retints this surface together with every other floating surface in the
library. `--lr-overlay-radius` (default `var(--lr-radius)`) is the matching corner radius.

`--lr-positioning-strategy` (16.0.0) — the breakdown tooltip reads this same cascading
`absolute`/`fixed` override documented on `<lr-popover>` when it is (re)positioned, falling back to
its own `fixed` default when nothing is set. There is no per-instance `positioning-strategy`
property on `<lr-usage-badge>`; set the custom property on `:root`, a theme, or one clipping
ancestor to change every unset usage badge beneath it.

```html
<lr-chat-message message-role="assistant" status="sent">
  <lr-usage-badge
    slot="badges"
    tokens-in="1204"
    tokens-out="386"
    cost-text="$0.012"
    latency-ms="2350"
  ></lr-usage-badge>
  <lr-markdown></lr-markdown>
</lr-chat-message>
<script type="module">
  document.querySelector("lr-chat-message lr-markdown").content = answer;
</script>
```

## `lr-widget-renderer`

Renders an agent-streamed version-two declarative JSON widget document through an immutable,
allowlisted `type -> lyra tag` registry. Mapped tags and children render declaratively, so populated
documents work during SSR without a global `document`; primitive mapped props remain property-only
and are assigned during hydration. Keyed reconciliation preserves the mapped element's focus,
scroll position, and internal state across streamed document updates. An unchanged resolved mapped
node also retains its memoized template and ref callback, so unrelated renderer updates neither
reassign its props nor detach and reattach its action/binding listeners. Built-in `row`/`col`/`text`
structural nodes render through ordinary nested templates. Not a
form runtime (no input/select/form types in the default registry), no expression language or
implicit state mutation, no remote widget/schema fetching, and it never renders arbitrary HTML or
navigates (no `href` props are allowlisted anywhere). Controlled state binding is deliberately
narrow: a versioned document may bind an allowlisted primitive prop to a JSON Pointer, and the host
must apply every requested change itself.

Default authoring diagnostics are silent outside Lit's development mode. An explicit expert
`ResolveContext.warn` callback remains active in every runtime; warning keys and the suppression cap
remain scoped to the current context generation. Runtime `lr-render-error` reporting is independent
of this development diagnostic policy.

`createWidgetDocument` validates authored trees immediately. To handle a received, untrusted
document, pass its envelope to the renderer's `document` boundary; malformed envelopes clear prior
output and emit `lr-render-error`. The malformed-stream example exercises this boundary.

**Exported types:**

- `LyraWidgetNode { readonly type: string; readonly id?: string; readonly props?:
Readonly<Record<string, unknown>>; readonly children?: readonly (LyraWidgetNode | string)[];
readonly slot?: string; readonly actionId?: string; readonly payload?: unknown }` — `id` is a stable public
  identity and reconciliation key. Bound/actionable nodes require a unique, nonempty id; other
  nodes fall back to a deterministic structural `nodePath`. `slot` is honored only when the parent
  type allowlists it, `actionId` arms the type's declared action trigger, and `payload` is echoed
  back in `lr-widget-action`.
- `LyraWidgetBinding { $bind: string; fallback?: string | number | boolean | null }` — an explicit JSON
  Pointer lookup used as an allowlisted prop value. `fallback` is used only when the pointer cannot
  resolve.
- `LyraWidgetDocument { readonly version: '2'; readonly root: LyraWidgetNode }` — the sole versioned tree source.
- `createWidgetDocument(root: LyraWidgetNode): LyraWidgetDocument` — creates an immediate frozen
  version-two snapshot for former unversioned tree assignments. Traversal uses the renderer's depth,
  node, per-node prop, and per-string length ceilings; malformed, cyclic, duplicate-id, or hostile
  structure throws `TypeError`. Node records, child arrays, and prop records are copied and frozen,
  while opaque prop values and action payloads intentionally retain caller identity.

The package root and the normal `widget-renderer.js` registration entry expose the renderer
`LyraWidgetRenderer`/`LyraWidgetRendererEventMap` together with the complete stable authoring
surface: `LyraWidgetNode`, `LyraWidgetBinding`, `LyraWidgetDocument`, `createWidgetDocument`,
`LyraWidgetPropType`, `LyraWidgetInteraction`, `LyraWidgetTypeDefinition`,
`LyraWidgetTypeRegistry`, `createWidgetTypeRegistry`, `isWidgetTypeRegistry`, and
`DEFAULT_WIDGET_TYPE_REGISTRY`. Advanced consumers that need `resolveTree`, `ResolveContext`,
`ResolvedNode`, `ResolvedText`, or `ResolvedElement` import the explicit expert route
`@aceshooting/lyra-ui/components/conversation/widget-renderer/resolve.js`. Pointer-reading helpers
and the resolver's hard safety ceilings remain internal implementation details.

The expert route's exact resolver contracts are `ResolvedText { nodeKey: string; nodePath: string;
kind: 'text'; text: string; slot?: string }`, `ResolvedElement { nodeId?: string; nodeKey: string;
nodePath: string; kind: 'builtin-row' | 'builtin-col' | 'builtin-text' | 'mapped'; tag?: string;
interactive: boolean; props: Record<string, unknown>; actionEvent?: string; actionId?: string;
payload?: unknown; bindings: Array<{ prop: string; path: string; event?: string }>; children:
ResolvedNode[]; slot?: string }`, and `ResolveContext { registry: LyraWidgetTypeRegistry;
bindingState: unknown; warned: Set<string>; warn?: (message: string) => void }`.
`resolveTree(root: LyraWidgetNode | null | undefined, ctx: ResolveContext): ResolvedNode | null`
resolves one bounded snapshot; invalid structure returns `null`.

**Properties:**

- `document: LyraWidgetDocument | null = null` (property only) — the sole tree source. `null`
  renders an empty base; a present document with an invalid/missing root fails closed, clears prior
  output, and emits exactly one `lr-render-error`.
- `bindingState?: unknown` (property only) — explicit controlled binding state. `null` is a real
  state value, not an absence sentinel.
- `registry: LyraWidgetTypeRegistry = DEFAULT_WIDGET_TYPE_REGISTRY` (property only) — immutable
  per-instance registry; mutable structural `Map` values are rejected.

**Registry module (`widget-renderer/registry.js`):**
`createWidgetTypeRegistry(entries?: Iterable<readonly [string, LyraWidgetTypeDefinition]>):
LyraWidgetTypeRegistry` validates, snapshots, and freezes a unique-key registry;
`isWidgetTypeRegistry(value: unknown): value is LyraWidgetTypeRegistry` is its untyped-boundary
guard. `LyraWidgetTypeRegistry extends ReadonlyMap<string,
Readonly<LyraWidgetTypeDefinition>> {}` is an opaque branded snapshot, so a mutable structural
`Map` is not assignable. `LyraWidgetTypeDefinition { tag: string; interaction:
'none' | 'control'; props?:
Record<string, 'string' | 'number' | 'boolean'>; forcedProps?: Record<string, unknown>; slots?:
string[]; action?: { event: string }; bindings?: Record<string, { event: string }> }` — `tag` is
resolved prefix-aware, `props` is a prop allowlist (a prop absent here, or whose runtime type doesn't
match, is silently skipped — never assigned),
`forcedProps` always apply and are never overridable by `LyraWidgetNode.props`, `slots` allowlists child
`slot` names (a disallowed one renders unslotted rather than being dropped), and `action.event` is
the native/custom DOM event that arms `lr-widget-action` when a node also sets `actionId`.
`bindings?: Record<string, { event: string }>` maps an allowlisted prop to the control event that
requests its controlled update. `interaction` is explicit: actions/bindings require `control`, and
a control descendant under another control fails closed. `DEFAULT_WIDGET_TYPE_REGISTRY` is the
frozen built-in snapshot; there are no module-global register/clear/get mutation APIs.

**Built-in schema:** `text` (plain text node) and `row`/`col` (internal flex wrappers; props `gap:
's'|'m'|'l'`, `align: 'start'|'center'|'end'|'stretch'`, `justify:
'start'|'center'|'end'|'between'`) are structural and cannot be registered. The immutable
`DEFAULT_WIDGET_TYPE_REGISTRY` maps `card` →
`lr-card` (`appearance`), `badge` → `lr-badge` (`variant`), `button` → `lr-button` (`variant`,
`appearance`, `size`, `disabled`, `loading`; action: `click`), `stat` → `lr-stat` (`label`,
`value`, `unit`, `variant`, `caption`, `sub`), `result-card` → `lr-result-card` (`title`),
`result-field` → `lr-result-field` (`label`, `value`), `markdown` → `lr-markdown` (`content`),
`image` → `lr-media-card` (`src`, `alt`, `filename`; forced `{ kind: 'image' }`). The registration
entry defines those eight mapped custom elements and `lr-widget-renderer`; it installs no mutable
module-global registry state.

**Events:** `lr-widget-action` — `detail: { actionId, payload, nodeId, nodeKey, nodePath }`, the single bubbling action
channel. `lr-render-error` — `detail: { error }`, the root or a reachable nested node was
structurally unusable (including a non-object node, invalid `props`/`children` shape, or a tree the
depth/size caps made empty). The rejected update clears prior rendered content and emits this event
once rather than throwing. `lr-widget-state-change` —
`detail: { path, value, nodeId, nodeKey, nodePath, prop }`, emitted when a bound mapped control
requests a controlled update. The renderer never mutates caller data; assign a new `bindingState`
value to complete the update.

**CSS parts:** `base` (the root wrapper, `display: contents`), `row`, `col`, `text` (built-in
structural nodes only — a mapped lyra component exposes its own parts instead).

For predictable rendering, documents are limited to depth 32, 5,000 nodes, and 100 properties per
node. Content beyond those size limits is omitted or truncated; malformed documents fail closed,
clearing prior output and emitting `lr-render-error`. `document` is captured when assigned, so
mutate a copy and assign it to update; `bindingState` updates bindings without changing that
captured document or registry. Exported deterministic `nodeKey`/`nodePath` identity drives
reconciliation.

```ts
import { html } from "lit";
import {
  createWidgetDocument,
  createWidgetTypeRegistry,
  DEFAULT_WIDGET_TYPE_REGISTRY,
} from "@aceshooting/lyra-ui/components/conversation/widget-renderer/widget-renderer.js";
import "@aceshooting/lyra-ui/components/data/sparkline/sparkline.js";
import { tag } from "@aceshooting/lyra-ui/utilities/prefix.js";

const registry = createWidgetTypeRegistry([
  ...DEFAULT_WIDGET_TYPE_REGISTRY,
  [
    "sparkline",
    { tag: tag("sparkline"), interaction: "none", props: { data: "string" } },
  ],
]);
const widgetDocument = createWidgetDocument(msg.widget);
const view = html`<lr-widget-renderer
  .document=${widgetDocument}
  .registry=${registry}
  @lr-widget-action=${(event: CustomEvent) =>
    sendToAgent(event.detail.actionId, event.detail.payload)}
></lr-widget-renderer>`;
```

For a controlled binding, use a per-instance registry and apply the event's requested value back to
`bindingState` (this one-field example binds `/name`). The direct class route supplies the
default type mappings but defines only `lr-widget-renderer`; register every mapped custom element
you use yourself. The normal `widget-renderer.js` entry also registers the eight default mapped
elements, so do not import it on this route.

```html
<lr-widget-renderer id="bound-widget"></lr-widget-renderer>
```

```js
import { LyraWidgetRenderer } from "@aceshooting/lyra-ui/components/conversation/widget-renderer/widget-renderer.class.js";
import { createWidgetDocument } from "@aceshooting/lyra-ui/components/conversation/widget-renderer/resolve.js";
import { createWidgetTypeRegistry } from "@aceshooting/lyra-ui/components/conversation/widget-renderer/registry.js";
import { defineElement, tag } from "@aceshooting/lyra-ui/utilities/prefix.js";
import "@aceshooting/lyra-ui/components/forms/input/input.js";

defineElement("widget-renderer", LyraWidgetRenderer);

const renderer = document.querySelector("#bound-widget");
renderer.registry = createWidgetTypeRegistry([
  [
    "bound-input",
    {
      tag: tag("input"),
      interaction: "control",
      props: { label: "string", value: "string" },
      bindings: { value: { event: "lr-input" } },
    },
  ],
]);
renderer.document = createWidgetDocument({
  type: "bound-input",
  id: "name",
  props: { label: "Name", value: { $bind: "/name", fallback: "" } },
});
renderer.bindingState = { name: "Ada" };
renderer.addEventListener("lr-widget-state-change", (event) => {
  renderer.bindingState = { name: event.detail.value };
});
```

**Optional peer deps:** none new — the normal registration entry directly imports the eight mapped
components (`markdown` keeps its own `marked`/`dompurify` optional-peer fallback). The manual class
route supplies the same default type mappings while leaving component registration under the
consumer's control.

## `lr-voice-picker`

A TTS voice selector over a host-supplied `catalog`, mirroring `lr-model-select`'s
closed-dropdown/free-text-combobox dual mode, stale-value handling, and form-association verbatim
(see that section for the full mode-switching contract this one shares), extended with a
TTS-agnostic preview affordance. Each new target is event-first: its cancelable
`lr-preview-request` fires before that target can start. Left un-prevented, a `previewUrl` plays
through one internal native `<audio>` (validated by `safeMediaSrc()` first); `preventDefault()` or no
URL leaves playback to the host's own TTS. Requesting the same voice while it's already playing
internally stops it instead of re-requesting; requesting a different voice retires the old resource
and publishes its terminal change before dispatching the new request. Internal playback becomes
public only after the still-current `audio.play()` promise
fulfills; a rejected pending play emits neither a false start nor a false stop. Committed-value,
active-option, and catalog changes likewise retire an internal preview before the visible preview
control changes target; closing or filtering also retires a row-owned preview once no rendered
control represents it. Does not synthesize speech, fetch catalogs, or persist selection; not a
persona picker; `lr-model-select` stays for LLMs.

Removing `label`, `hint`, or `error-text` clears that optional copy in both catalog and free-text
modes. Removed string properties retain `null` readback, and later assignments restore their
content.

Composing key events (`isComposing` or legacy `keyCode === 229`) remain with the catalog query or
custom-value editor: they do not navigate options, commit a selection or custom value, or close the
popup. Ordinary keyboard behavior resumes after composition.

**Exported types:** `LyraVoiceCatalogEntry extends LyraCatalogEntry { language?: string;
description?: string; previewUrl?: string }` — `language`/`description` render as a quiet
`[part="option-meta"]` second line. Voice catalogs use the shared
`LyraCatalog<LyraVoiceCatalogEntry>` homogeneous readonly union documented under `lr-model-select`,
including the shared `disabled` field: a disabled voice row cannot be selected by click or keyboard
and is stepped over by arrow-key/Home/End navigation, but its own `[part="option-preview"]` stays
independently clickable, since previewing a voice is a separate affordance from selecting it. The
public `size` property uses `LyraSize`, including the long-form aliases.
`LyraVoicePickerSelectionDirection = 'forward' | 'backward' | 'none'` is the native
selection direction exposed in free-text mode.

**Properties:** `provider: string = ''` — informational only (e.g. `'elevenlabs'`); rendered as a
small leading badge. `catalog?: LyraCatalog<LyraVoiceCatalogEntry>` (attribute: false) — the full
voice list; omit (or leave empty) to fall back to plain free-text entry; replacing it retires any
internal preview before the rendered candidate changes. Ids use the shared unique, nonempty,
first-wins catalog rule documented under `lr-model-select`, including preview lookup. Assignments
become bounded clone-owned frozen snapshots; create and reassign a new array after row changes.
`allowCustom: boolean = false` (attribute
`allow-custom`, reflected) — let the user type/commit a value that isn't in `catalog`. `preview:
boolean = true` (reflected) — whether to render preview affordances at all. `label: string = ''`,
`hint: string = ''`, `errorText: string = ''` (attribute `error-text`), `placeholder: string = ''`,
`spellcheck: boolean = true` (string-aware converter, same as `lr-model-select`), `autocapitalize:
string = ''`, `autoCorrect: string = ''` (attribute `autocorrect`), `autocomplete: string = 'off'`,
`inputMode: string = ''` (attribute `inputmode`), `enterKeyHint: string = ''` (attribute
`enterkeyhint`), and `open: boolean = false` (reflected) — all mirror `lr-model-select`'s
identically-named properties. `size: LyraSize = 'm'` (reflected) selects the shared
`2xs`/`xs`/`s`/`m`/`l`/`xl` control ladder; `small`/`medium`/`large` render as aliases of
`s`/`m`/`l`. It scales both closed and free-text field chrome through the shared
`--lr-form-control-*` metrics. The separate preview button retains the library-wide 40px minimum
hit area at compact tiers and grows with `l`/`xl`.

`readonly: boolean = false` (reflected) mirrors `lr-model-select`: it blocks user typing and catalog
commits while preserving focus, popup navigation, selection/copy, reset, submission, programmatic
writes, and the preview actions.

The `label` property and `label` slot share one native label in the standard `form-control` frame.
Slotted label content participates in the accessible name in both closed-dropdown and free-text
modes; an explicit host `aria-label` remains the highest-precedence name.

**Form association:** hand-rolled via `attachInternals()`, mirroring `lr-model-select`: live,
non-reflecting `value: string = ''` (the current voice id), reflected
`defaultValue: string = ''` (attribute `value`, the current reset default), reflected
`customError: string | null = null` (`custom-error`), `name`, `disabled`
(reflected), and `required` (reflected — enforced via `internals.setValidity()`). Their exact
signatures are `name: string = ''`, `disabled: boolean = false`, and `required: boolean = false`.
It also exposes `form: HTMLFormElement | null = null`, readonly `labels: NodeList`, `validity:
ValidityState`, `validationMessage: string`, `willValidate: boolean`, and `effectiveDisabled:
boolean`, plus
`checkValidity()`/`reportValidity()` and `setCustomValidity(message: string)`. The last is the
standard channel for a server-side rejection ("that voice is not enabled for your account") no
client-side constraint can express: a non-empty `message` raises `customError` and becomes
`validationMessage`, so the control fails `checkValidity()`, blocks submission, and matches
`:state(invalid)`; `''` clears only that consumer layer, leaving a `required` picker with no value
still `valueMissing`. The custom error survives every intrinsic recomputation in between and a
`form.reset()`, matching a native control, and the message is used verbatim, never localized.
`getForm()` returns the browser-resolved owning form.

**Methods:** `click()` (override) — closed-dropdown mode forwards a real `.click()` to the trigger
`<button>`, whose own `@click` handler opens it; free-text mode calls `.focus()` on the combobox
`<input>`, since a synthetic `.click()` on a text input never dispatches `focus` the way a real
click's `mousedown` default action does, and this mode's open behavior is wired to the input's
native `focus` event, not a `click` handler on the input itself. Mirrors `<lr-button>`'s host
`click()` forwarding while retaining voice-picker's focus-only free-text behavior.
`focus(options?)` and `blur()` forward to whichever internal control the active mode renders.
In free-text mode, `input: HTMLInputElement | null`, `selectionStart: number | null`,
`selectionEnd: number | null`, and `selectionDirection: LyraVoicePickerSelectionDirection | null`
mirror the native input. `select()`, `setSelectionRange(start, end, direction?)`, and overloaded
`setRangeText(replacement[, start, end, selectMode])` likewise forward native editing operations;
`setRangeText()` synchronizes the picker `value`, form entry, and validity without emitting user
`input`/`change` events. Those text APIs return `null` or are no-ops in closed-dropdown mode and
before the input renders.

**Events:** `lr-change` — `detail: { value, inCatalog }`. `lr-preview-request` — `detail: {
voiceId, previewUrl? }`, cancelable. `lr-preview-change` — `detail: { voiceId }`, internal playback
started (`voiceId`, only after `play()` fulfills) or stopped (`null`); a pending rejection emits
neither. Plus owner-realm native `input`/`change` (retaining each free-text `InputEvent` payload)
and native `FocusEvent` `focus`/`blur` (retaining `relatedTarget`). The trigger/input, listbox popup,
and sibling preview control form one focus boundary, so
moving within them does not close or touch the picker and only leaving the component emits the
outer pair. One bubbling/composed `lr-invalid` alias fires when native validity fails.

**Slots:** `label` (custom visible label content), `hint`, `error`.

**The required marker and barred validity.** Identical to `lr-model-select`'s (see that section): a
`required` picker with a non-empty `label` paints the shared required marker on
`[part="form-control-label"]`, retunable or suppressible through
`--lr-form-control-required-content`, `--lr-form-control-required-color` and
`--lr-form-control-required-offset`; and while the picker is barred from
constraint validation (own `disabled` or `readonly`, or an ancestor `<fieldset disabled>`) it
reports no violation and publishes neither `:state(invalid)` nor
`:state(user-invalid)`.

**CSS parts:** `form-control` (the complete field frame), `form-control-label`, `trigger` (closed-dropdown mode), `combobox`/`combobox-input`
(free-text mode), `provider-badge`, `listbox`, `option`, `option-label`, `option-meta` (the quiet
`language · description` second line), `option-badge` (the "not in catalog" badge on a synthetic
stale-value row), `option-preview` (a pointer-only per-row preview icon, `tabindex="-1"`,
`aria-hidden`), `preview-button` (the standalone, keyboard-reachable preview toggle beside the
trigger), `expand-icon`, `empty`, `hint`, `error`.

```html
<lr-voice-picker provider="elevenlabs" allow-custom></lr-voice-picker>
<script type="module">
  const picker = document.querySelector("lr-voice-picker");
  picker.catalog = voices;
  picker.addEventListener("lr-change", (e) => setVoice(e.detail.value));
  picker.addEventListener("lr-preview-request", (e) => {
    if (!e.detail.previewUrl) {
      e.preventDefault();
      playSample(e.detail.voiceId);
    }
  });
</script>
```

**Known gotchas:**

- Listbox options must not contain tab-focusable controls, so preview is accessible via the
  standalone `[part="preview-button"]` beside the trigger (previews the active option while open,
  else the committed value) — the per-row `[part="option-preview"]` icon is a pointer-only
  duplicate (`tabindex="-1"`, `aria-hidden="true"`).
- `catalog` must be homogeneous — the same shared `LyraCatalog<T>` constraint documented for
  `lr-model-select`.

**Additional API surface:**

- `--lr-voice-picker-max-inline-size` — The host's own width ceiling, previously a hard-wired
  literal. Set a length to retune it, or `none` to fill the container the way `lr-select` does.
  Default: `var(--lr-size-24rem)`.
- `--lr-voice-picker-trigger-min-height` — Trigger/combobox block-size floor, reading the shared
  form-control height ladder so retuning `--lr-theme-form-control-height-*` moves this control and
  every sibling field together. Default: `var(--lr-form-control-height)`.
- `--lr-voice-picker-trigger-height` — An _exact_ trigger/combobox height that both floors and caps
  the control, for pixel-matching a sibling field in the same toolbar row. Takes precedence over
  `--lr-voice-picker-trigger-min-height`. Unset by default.
- The `[part="preview-button"]` action follows whichever of those two names is in play, not just
  the exact height: `.control-row` is `align-items: stretch`, and stretch never applies to an item
  with a definite cross size, so an action that tracked only `--lr-voice-picker-trigger-height`
  would sit short and top-aligned beside a field whose floor had been raised. Its own WCAG
  hit-area floor (`--lr-icon-button-size`) still wins below that, so pinning a short field cannot
  shrink the action's hit area.
- `--lr-voice-picker-gap` — Gap between the field and preview action, and between trigger,
  combobox, and option children. Default: `var(--lr-space-xs)`.
- `--lr-voice-picker-radius` — Trigger, combobox, listbox, option, and preview-action corner radius.
  Default: `var(--lr-form-control-radius)`.
- `--lr-overlay-surface` — Shared floating-surface fill, on the listbox. Default:
  `var(--lr-color-surface-overlay)`.
- `--lr-overlay-border` — Shared floating-surface edge colour, on the listbox. Default:
  `var(--lr-color-border)`.
- `--lr-overlay-radius` — Shared floating-surface corner radius, reached only as the middle arm of
  `--lr-voice-picker-radius`, which still wins when set. Default: `var(--lr-radius)`.
- `--lr-overlay-shadow-anchored` — Elevation of the anchored listbox. Default: `var(--lr-shadow-m)`.
  None of the four is declared on `:host`, so one declaration on `:root` — or on any ancestor, to
  scope it — retints this listbox together with every other floating surface in the library.
- `--lr-voice-picker-preview-active-border` — Active preview border. Default: `var(--lr-color-brand)`.
- `--lr-voice-picker-preview-active-color` — Active preview icon. Default: `var(--lr-color-brand)`.
- `--lr-voice-picker-trigger-border-color` — Resting trigger/combobox border color, independent of
  the open-state color below. Default: `var(--lr-color-border)`.
- `--lr-voice-picker-trigger-fill` — Resting trigger/combobox background. Default:
  `var(--lr-color-surface)`.
- `--lr-voice-picker-open-border-color` — Open trigger border color. Default: `var(--lr-color-brand)`.
- `--lr-voice-picker-option-active-bg` — Active option fill. Default: `var(--lr-color-brand-quiet)`.
- `--lr-voice-picker-option-selected-border` — Selected option border. Default: `var(--lr-color-brand)`.
- `--lr-voice-picker-option-selected-color` — Selected option text. Default: `var(--lr-color-brand)`.
- `--lr-voice-picker-option-selected-bg` — Selected option fill. Default: `transparent`.
- `--lr-voice-picker-option-selected-font-weight` — Selected option label weight. Default: `var(--lr-font-weight-semibold)`.
- `--lr-voice-picker-option-synthetic-border-style` — Synthetic stale-value row border style. Default: `dashed`.
- `--lr-voice-picker-option-synthetic-border-color` — Synthetic stale-value row border color. Default: `var(--lr-color-border)`.
- `--lr-voice-picker-option-disabled-opacity` — Opacity of an option row whose catalog entry sets `disabled`. Default: `0.5`.
- `--lr-voice-picker-option-synthetic-font-style` — Synthetic stale-value option-label font style. Default: `italic`.
- `--lr-voice-picker-preview-hover-bg` — Preview hover fill. Default: `var(--lr-color-brand-quiet)`.
- `--lr-voice-picker-preview-hover-color` — Preview hover icon. Default: `var(--lr-color-brand)`.

## `lr-agent-workspace`

Responsive, fully controlled shell for an AI conversation and its supporting run, tool, retrieval,
grounding, and context state: transcript + composer in the main pane, and a details pane composing
`lr-agent-run`, `lr-tool-timeline`, `lr-retrieval-results`, `lr-grounding-summary`, and
`lr-context-inspector`. Performs no network requests, model calls, retrieval, or persistence —
assign new data to the properties as the host receives updates.

This is the single component that binds the most of the provider-neutral vocabulary exported from
`@aceshooting/lyra-ui/ai` at once; a host that already holds `ChatMessage[]`,
`AgentRun`, `RetrievalChunk[]`, `Citation[]`, and `GroundingAssessment` can wire this up with no
adapters.

**Properties (transcript):**

- `messages: ChatMessage[] = []` (attribute: false) — **`ChatMessage` from
  `@aceshooting/lyra-ui/ai`**: `{ id: string; role: ChatMessageRole; status?: ChatMessageStatus;
timestamp?: Date | string; text?: string; attachments?: DocumentRef[]; parts?: MessagePart[];
metadata?: Record<string, unknown> }`. Each entry renders as an `lr-chat-message` whose
  `role`/`status`/`timestamp` come straight across. A nonempty `parts` array renders in order through
  `lr-message-parts` and takes precedence over the legacy `text` shortcut; otherwise `text` renders
  as sanitized Markdown through `lr-markdown`. Replace the whole region with the `messages` slot for
  richer bodies. Empty ids and later duplicates are omitted first-wins before the latest 500 valid
  identities are chosen, so malformed tail rows cannot evict earlier valid messages. Host owns
  ordering, updates, and persistence
- `follow: boolean = true` (reflected) — forwarded to the internal `lr-chat-viewport`
- `unreadStartIndex: number | null = null` (attribute `unread-start-index`) — forwarded to the viewport

**Properties (details pane):**

- `run: AgentRun | null = null` (attribute: false) — **`AgentRun` from `@aceshooting/lyra-ui/ai`**:
  `{ id: string; status: AgentStatus; startedAt?: number; endedAt?: number; model?: string;
costEstimate?: number; steps: AgentStep[] }` (epoch-ms timestamps). `null` omits the run section
- `metrics: AgentRunMetric[] = []` (attribute: false) — `lr-agent-run`'s own
  `AgentRunMetric { id: string; label: string; value: string | number; variant?: BadgeVariant }`,
  e.g. token counts or latency
- `tools: ToolTimelineEntry[] = []` (attribute: false) — `lr-tool-timeline`'s
  `ToolTimelineEntry extends ToolInvocation` (i.e. `{ id, name, args, status, result?, error? }` from
  `@aceshooting/lyra-ui/ai`) plus `{ startedAt?: number; endedAt?: number; retryCount?: number;
redactedFields?: string[]; needsApproval?: boolean; approved?: boolean }`
- `retrievalChunks: RetrievalChunk[] = []` (attribute: false) — **`RetrievalChunk` from
  `@aceshooting/lyra-ui/ai`**: `{ id, text, score, source: DocumentRef, metadata? }`, forwarded to
  `lr-retrieval-results`
- `selectedRetrievalChunkIds: string[] = []` (attribute: false) — controlled selection forwarded to
  `lr-retrieval-results.selectedChunkIds`
- `retrievalLoading: boolean = false` (attribute `retrieval-loading`), `retrievalHasMore: boolean =
false` (attribute `retrieval-has-more`), `retrievalErrorText: string = ''` (attribute
  `retrieval-error-text`, caller-supplied text) — all forwarded to `lr-retrieval-results`
- `groundingAssessment: GroundingAssessment | null = null` (attribute: false) — **`GroundingAssessment`
  from `@aceshooting/lyra-ui/ai`**: `{ supportedClaims, unsupportedClaims, coverage, confidence?,
warnings? }`
- `citations: Citation[] = []` (attribute: false) — **`Citation` from `@aceshooting/lyra-ui/ai`**,
  shown alongside the grounding summary
- `contextSegments: ContextInspectorSegment[] = []` (attribute: false) — `lr-context-inspector`'s
  `{ id: string; label: string; text: string; tokens: number; tone?: ContextMeterTone; citation?:
Citation; truncated?: boolean; omittedTokens?: number; redactions?: ContextInspectorRedaction[] }`
- `contextTotal: number = 0` (attribute `context-total`) — the overall context-window token budget
- `showDetails: boolean = true` (attribute `show-details`, reflected) — whether the details pane is
  available at all when data is present

**Properties (composer / chrome):**

- `showComposer: boolean = true` (attribute `show-composer`, reflected) — whether the built-in
  plain-frame composer renders when no `composer` slot is supplied. Its workspace-owned dock supplies
  the border and padding; a supplied `composer` slot keeps its own frame.
- `composerValue: string = ''` (attribute `composer-value`) — controlled composer value
- `composerStatus: ChatComposerStatus = 'idle'` (attribute `composer-status`) — `'idle' | 'sending' |
'streaming'`, `lr-chat-composer`'s own union; invalid values read as `idle` without rewriting the
  host attribute
- `composerPlaceholder: string = ''` (attribute `composer-placeholder`)
- `composerMinRows: number = 1` (attribute `composer-min-rows`), `composerMaxRows: number = 8`
  (attribute `composer-max-rows`)
- `label: string = ''` — accessible name and visible heading
- `accessibleLabel: string | null = null` (attribute `aria-label`) — host-level accessible-name
  override for the internal `role="region"` root

**Events:**

- `lr-input` (`detail: { value: string }`) / `lr-submit` (`detail: { value: string }`) / `lr-stop`
  (`detail: null`) — forwarded from the built-in composer.
- `lr-message-retry` (`detail: { messageId: string }`) — a data-driven message's retry action.
- `lr-follow-change` (`detail: { following: boolean }`) — forwarded from the transcript viewport.
- `lr-retrieval-select` (`detail: RetrievalResultsSelectDetail` = `{ chunkIds: string[]; chunks:
RetrievalChunk[] }`) — forwarded from the built-in retrieval results.
- `lr-citation-select` (`detail: CitationSelectEventDetail` = `{ citation: Citation }`, from
  `@aceshooting/lyra-ui/ai`) — forwarded from the built-in grounding summary.
- `lr-tool-approval-decide` (`detail: ToolTimelineApprovalDetail` = `ToolApprovalEventDetail &
{ args?: unknown }` = `{ invocationId: string; approved: boolean; args?: unknown }`) — forwarded
  from the built-in tool timeline; `args` is present only on approval and may differ from what the
  entry originally proposed (the dialog's inline edit step).
- `lr-cancel` (`detail: CancelEventDetail = { reason?: string }`) / `lr-run-retry` (`detail: RetryEventDetail` =
  `{ attempt: number; messageId?: string }`, from `@aceshooting/lyra-ui/ai`) — forwarded from the
  built-in agent run. The distinct retry name prevents a rendered message or attachment retry from
  being mistaken for a whole-run retry.

**Slots:** `messages` (replaces the data-driven transcript message list; assign ordinary messages
directly, or exactly one `lr-virtual-list` when the slot itself owns virtualization), `details` (replaces the
built-in run/tool/retrieval/grounding/context details pane while keeping the responsive shell),
`composer` (replaces the built-in plain-frame `lr-chat-composer`; supplied content keeps its own
frame), `header-actions` (model selection, settings, export controls).

**CSS parts:** `base`, `header`, `heading`, `header-actions`, `body`, `conversation`, `viewport` (the
composed `lr-chat-viewport`), `messages`, `messages-empty`, `details`, `details-content`, `section`
(one run/tools/retrieval/grounding/context section), `section-heading`, `composer`, `composer-input`,
`message`
(the composed `lr-chat-composer`).

**Themeable custom properties:** shared tokens only.

**Optional peer deps:** none of its own; the composed `lr-markdown` keeps its `marked`/`dompurify`
optional-peer fallback.

Every public data/value property is controlled: forwarded child intents bubble without mutating
`messages`, `composerValue`, selections, run state, or persistence-owned data inside the shell.

**Only the transcript scrolls.** `[part='base']` is a three-row grid — header, conversation,
composer — and only the middle row can shrink, so the composed `lr-chat-viewport` owns the
scrolling and the chrome rows stay put at their content size. The trade: give the workspace less
block-size than the chrome needs and the conversation row collapses to zero first, after which the
header or composer is clipped with no scrollbar. That takes unusually large slotted chrome — a very
tall `header-actions` toolbar, or a `composer` replacement much taller than the built-in one — and
the region that supplied it caps and scrolls itself through the public parts:

```css
lr-agent-workspace::part(header) {
  max-block-size: 4rem;
  overflow: auto;
}
```

The same applies to `::part(composer)`. Both declarations are needed: the cap keeps the grid track
inside the workspace, and `overflow` makes the capped region scrollable instead of spilling. No
component-owned custom property duplicates this, because a `::part()` rule from your tree already
wins over the shadow stylesheet regardless of specificity.

## `lr-message-parts`

Ordered renderer for provider-neutral `MessagePart[]`: text, reasoning, tool call/result, citation,
attachment, data/widget, audio, and error parts can interleave without flattening stream order.
Built-in text and reasoning Markdown receives each part's `state === 'streaming'` hint and displays
accumulated plain text without parsing or highlighting. Replacing that same-id part with
`state: 'complete'` parses and renders the final content.
Citation badge ranks are precomputed in one linear pass per render, rather than rescanning and
allocating every preceding part for each citation in a citation-heavy or growing message.

**Properties:** `parts: MessagePart[] = []` (attribute: false); `contentMode: MessagePartsContentMode =
'markdown'` (attribute `content-mode`, reflected) and `showReasoning: boolean = true` (attribute
`show-reasoning`, reflected, with string-aware true-default conversion);
`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
parts without touching the host's `parts` data. Citation ranks are unaffected by the window: they
are still derived from the full sequence first, in the same linear prepass, so a badge's number
stays stable even once an earlier citation rolls out of the rendered window. Opt in for a message
that can grow an unusually large number of interleaved parts (e.g. a long agentic run with many
tool-call/tool-result pairs), where unbounded live DOM can visibly stall the main thread.
`renderPart?: MessagePartRenderer` (attribute: false), where returning `undefined` delegates that
part to the built-in renderer; `accessibleLabel: string | null = null` (attribute `aria-label`).

Unsupported direct or `content-mode` attribute values normalize and reflect as `markdown`.

`MessagePartRenderer = (part: MessagePart, index: number) => unknown`; `MessagePart` and its
discriminated part shapes come from the `@aceshooting/lyra-ui/ai` subpath. Tool results are a strict
success/error union: a success has `result` and cannot have `error`; an error has `error` and may
retain partial `result`. Audio is a single `{ type: 'audio'; src?; transcript?; mimeType? }` part,
and data parts carry exactly one of `data` or `widget`. Empty ids and later duplicate occurrences
are ignored so each rendered identity and announcement remains unambiguous.

**Events:** `lr-citation-select` (`{ citation }`), `lr-part-retry` (`{ part }`). Composed child
events pass through unchanged: `lr-anchor-result`, `lr-citation-open`, `lr-copy`,
`lr-highlight-activate`, `lr-link-click`, `lr-preview-request`, `lr-remove`, `lr-render-error`, `lr-retry`,
`lr-search-change`, `lr-text-select`, `lr-toggle`, `lr-tool-call-chip-select`, `lr-widget-action`,
and `lr-widget-state-change`. The `lr-tool-chip-select` alias passthrough was removed in 9.0.0.

**CSS parts:** `base`, `part`, `part-streaming`, `text`, `reasoning`, `tool-call`, `tool-result`,
`tool-result-error`, `citation`, `attachment`, `data`, `audio`, `audio-control`,
`audio-transcript`, `error`, `retry`.

**Themeable custom properties:** `--lr-message-parts-streaming-color` (default
`var(--lr-color-text-quiet)`) controls a streaming wrapper's inherited text color.
`--lr-message-parts-audio-transcript-color` (default `var(--lr-color-text-quiet)`) controls an
audio transcript's text color. Error parts have separate
`--lr-message-parts-error-border-color` (default `var(--lr-color-danger)`),
`--lr-message-parts-error-background` (default `var(--lr-color-danger-quiet)`), and
`--lr-message-parts-error-color` (default `var(--lr-color-danger)`) hooks. All five are inline
fallbacks, so setting one on an ancestor rethemes only that state longhand.

**Slots:** none. **Optional peer deps:** those of composed content only: Markdown can use
`marked`/`dompurify`, and code content can use `shiki`; every composed primitive retains its own
fallback.

Error parts remain ordinary visible content. After the initial baseline, each newly added error-part
`id` is also appended through the shared assertive light-DOM announcement sink, using the caller's
message or the localized fallback. Existing history and reconnect renders stay silent; removing an
error id and later adding it again creates a new announcement.

```ts
import "@aceshooting/lyra-ui/components/conversation/message-parts/message-parts.js";
```

**Additional API surface:**

- `lr-anchor-result` event — Passthrough from rendered Markdown.
- `lr-citation-open` event — Passthrough from a rendered citation's full-preview action.
- `lr-copy` event — Passthrough from rendered JSON content.
- `lr-highlight-activate` event — Passthrough from rendered Markdown.
- `lr-link-click` event — Passthrough from rendered Markdown.
- `lr-preview-request` event — Passthrough from a rendered attachment. Not cancelable as of 10.0.0:
  `<lr-attachment-chip>` dropped the flag, since it owns no preview default action to veto.
- `lr-remove` event — Passthrough from a rendered attachment.
- `lr-render-error` event — Passthrough from rendered Markdown, tool-result, or widget content.
- `lr-retry` event — Passthrough from a rendered attachment.
- `lr-search-change` event — Passthrough from rendered JSON content.
- `lr-text-select` event — Passthrough from rendered Markdown.
- `lr-toggle` event — Passthrough from a rendered reasoning panel.
- `lr-tool-call-chip-select` event — Passthrough from a rendered tool-call chip. The
  `lr-tool-chip-select` alias it replaced was removed in 9.0.0.
- `lr-widget-action` event — Passthrough from a rendered declarative widget.
- `lr-widget-state-change` event — Passthrough from a rendered controlled widget.

## `lr-prompt-input`

The composed prompt surface: chat composer, attachment controls/chips, model and voice pickers,
retrieval-source scope, mention/slash-command popup, and queued follow-up prompts. It performs no
upload, retrieval, or model call. It is deliberately not form-associated: the complete interaction
state includes attachments, source scope, model, voice, and queued turns rather than one successful
string form entry. Observe `lr-input` for controlled text and handle `lr-submit` as the submission
request. `label` names the prompt section; it is not generic field chrome.

**Properties:** `value: string = ''`; `status: 'idle' | 'sending' | 'streaming' = 'idle'`;
`placeholder: string = ''`; `disabled: boolean = false` (reflected); `readOnly: boolean = false`
(attribute `readonly`, reflected); `minLength?: number` (attribute `minlength`) and
`maxLength?: number` (attribute `maxlength`);
`submitOnEnter: boolean = true` (attribute `submit-on-enter`, string-aware true-default converter);
`spellcheck: boolean = true` (string-aware true-default converter), `autocapitalize: string = ''`,
`autocorrect: boolean = true` (legacy string writes `'off'`/`'false'` normalize to `false`),
`wrap: 'hard' | 'soft' | 'off' = 'soft'`,
`autocomplete: string = ''`, `inputMode: string = ''` (attribute `inputmode`), and
`enterKeyHint: string = ''` (attribute `enterkeyhint`) forward unchanged to the composed native
textarea; empty string hints preserve the browser default.
Invalid `status` values read as `idle` without rewriting the host attribute.
`attachments: readonly LyraPromptInputAttachment[] = []` — `attachmentId` must be nonempty and
unique; malformed rows and later duplicates are omitted first-wins before rendering and attachment
events, and surviving chips reconcile by `attachmentId`. `attachmentCapabilities: readonly
LyraAttachmentCapability[] = ['files', 'image', 'audio']`, `mentionItems: readonly LyraPromptSuggestion[] =
[]`, `commandItems: readonly LyraPromptSuggestion[] = []`,
`modelCatalog?: LyraCatalog<LyraModelCatalogEntry>`,
`voiceCatalog?: LyraCatalog<LyraVoiceCatalogEntry>`,
`sources: readonly LyraSourceEntry[] = []`, `selectedSourceIds: readonly string[] = []`, and `queue:
readonly PromptQueueItem[] = []` (all attribute: false); `model: string = ''`; `voice: string = ''`;
`label: string = ''`; `accessibleLabel: string | null = null` (attribute `aria-label`).
Source roots and queued prompts require unique nonblank `id` values; malformed rows and later
duplicates are omitted first-wins before section gating and child forwarding. Controlled selected
source ids use the same unique nonblank projection.

Every array-valued property above is a clone-owned, bounded, frozen readonly snapshot, including
nested source children and queued attachments. Mutating a previously assigned collection has no
effect; create and reassign a new array after changes.

`LyraPromptSuggestion` extends `LyraMentionItem { suggestionId, label, description?, icon?, disabled? }`
with optional `insertText` (defaults to `label`). The selected occurrence's original, pre-filter `index`
is preserved in the event detail. `LyraPromptInputAttachment` replaces `DocumentRef.id` with
`attachmentId` and adds `file?`, `bytes?`, `status?: 'pending' | 'uploading' | 'error' | 'success'`,
and numeric `progress?`.

**Methods:** `focus(options?)`, `blur()`, and `click()` forward to the composed chat input;
`select()` selects its native text surface. `click()` is inert while disabled. `input:
HTMLTextAreaElement | null`, `selectionStart: number | null`, `selectionEnd: number | null`, and
`selectionDirection: ChatComposerSelectionDirection | null` mirror the composed textarea.
`setSelectionRange(start, end, direction?)` and overloaded
`setRangeText(replacement[, start, end, selectMode])` use the same native range-editing contract;
`setRangeText()` synchronizes outer `value` without emitting `lr-input`. Selection and range calls
are no-ops before the textarea has rendered.

**Events:** native `input`, `change`, `focus`, and `blur` are each relayed once from the primary
textarea, paired with `lr-input` and `lr-change`; `lr-submit` (`{ value }`),
`lr-stop` (`null`), `lr-mention-select` (`{ suggestionId, index, label, trigger }`),
`lr-attachments-add` (`{ capability, files }`), `lr-attachment-remove` (`{ attachmentId }`),
`lr-model-change`/`lr-voice-change`
(`{ value, inCatalog }`), `lr-sources-change` (`{ selectedSourceIds }`), `lr-queue-change`
(`{ items, reason, itemId }`), `lr-send-now` (`{ item }`), `lr-camera-request`,
`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.

**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`
replaces the built-in composer action.

**CSS parts:** `base`, `controls`, `sources`, `sources-summary`, `source-picker`, `queue`,
`composer`, `start`, `chips`, `footer`.

**Themeable custom properties:** `--lr-prompt-input-control-width` (default `--lr-size-12rem`) is
the preferred width of each generated model, voice, and source control before wrapping.

An open mention or command popup remains open only while focus is in the primary textarea or that
popup; moving focus to another prompt control or outside closes it. Arrow keys move focus to the
active option. Enter or Tab accepting an option is handled before textarea submission. Escape
restores the textarea's prior ARIA and selection. If the popup closes, becomes unavailable, or its
input/items change before focus moves, no move occurs. Empty `chips` and `footer` wrappers are not rendered, so an absent optional region cannot
create phantom spacing.

**Optional peer deps:** none of its own.

```ts
import "@aceshooting/lyra-ui/components/conversation/prompt-input/prompt-input.js";
```

## `lr-prompt-queue`

Controlled editable queue of follow-up turns. Reordering, editing, and removal emit a complete
proposed queue; send-now emits the complete selected item.

When a focused row action requests removal and the host applies the proposed queue, focus moves to
the equivalent action on the nearest surviving row. If the queue becomes empty, its stable region
receives focus. Removing an unfocused row does not move focus.

**Properties:** `items: readonly PromptQueueItem[] = []` (attribute: false); `editable: boolean = true`
(reflected, string-aware true-default converter); `disabled: boolean = false` (reflected);
`label: string = ''`; `accessibleLabel: string | null = null` (attribute `aria-label`).
`PromptQueueItem = { id: string; value: string; attachments?: readonly DocumentRef[]; createdAt?: number;
metadata?: Record<string, unknown> }`.

Item ids are occurrence identities. Empty ids and later duplicates are ignored before rendering or
proposing a mutation, preserving one unambiguous `itemId`. Attachment names render visibly for both
editable and read-only rows; the host `label` is also the visible queue heading.

Supported item and attachment fields are read once when `items` is assigned; create and reassign a
new collection after changes, because changing an assigned record or reassigning the same mutated
array does not update the view. Rows or attachments without valid direct data are ignored. Duplicate IDs are resolved
after validation, so the first valid item wins. `metadata` is opaque and retains identity in
proposed queue/send-now payloads, while emitted items are new frozen snapshots.

**Events:** `lr-queue-change` (`PromptQueueChangeDetail = { items, reason, itemId }`, with
`reason: 'edit' | 'remove' | 'reorder'`), `lr-send-now` (`{ item }`). The queue is controlled:
these events propose complete next values without mutating `items`.

**CSS parts:** `base`, `heading`, `list`, `item`, `value`, `editor`, `attachments`, `attachment`,
`actions`, `action`, `empty`.

**Slots:** none. **Optional peer deps:** none.

```ts
import "@aceshooting/lyra-ui/components/conversation/prompt-queue/prompt-queue.js";
```

## `lr-selection-toolbar`

Nonmodal, Escape-dismissible text-selection toolbar carrying selected text plus a format-neutral
`DocumentLocator` into ask, quote, cite, and copy actions.

**Properties:** `open: boolean = false` (reflected); `text: string = ''`;
clone-owned `anchor: DocumentLocator | null = null`, `rect: DOMRectReadOnly | null = null`, and
clone-owned `actions: readonly SelectionAction[] = ['ask', 'quote', 'cite', 'copy']` (attribute: false);
`label: string = ''`; `accessibleLabel: string | null = null` (attribute `aria-label`).
`SelectionAction = 'ask' | 'quote' | 'cite' | 'copy'`. Duplicate built-in names are omitted
first-wins before rendering, roving focus, and action events. The anchor (including any path) and
actions are bounded frozen snapshots; reassign a new record or array after changes.

When a controlled `actions` refresh replaces the focused action, focus follows the same action id
through reordering, otherwise moves to the nearest surviving action, or to the stable toolbar when
the action set becomes empty. The same repair applies when a slotted action is removed or becomes
disabled, hidden, inert, `aria-disabled`, or no longer actionable. Availability and `tabindex`
changes are observed live, stale stops are cleared, and a newer focus destination is never
overridden. Observation is rebound to the current document realm when the toolbar is adopted.

**Events:** `lr-selection-action` (`SelectionActionDetail = { action, text, anchor }`);
`lr-dismiss` (`null`, Escape); `lr-copy` (frozen `{ ok: true, text }`, only after the clipboard
write fulfills); and, on failure, `lr-error` (`null`) plus frozen `lr-copy-error`
(`{ ok: false, text, reason, error }`). A failed copy does not emit the action event.
Detaching and later reinserting the same open instance re-establishes positioning and Escape
ownership even when the detach lasts past an event-loop turn.

**CSS parts:** `toolbar`, `action`, `action-ask`, `action-quote`, `action-cite`, `action-copy`.

The four built-in actions are the shipped set, and `actions` only reorders or subsets them. A
product-specific fifth action ("translate", "define", "search web") goes in the `actions` slot
instead: slotted elements render after the built-ins **inside** the same `role="toolbar"` element
and join the same roving-tabindex group (Home/End/Arrow, RTL-mirrored), so adding one does not mean
reimplementing the toolbar's positioning, keyboard, and dismissal behavior. A slotted action brings
its own accessible name and click handling; this component only manages its tab stop, and re-derives
the group whenever the slot's assigned elements change. The group resolves actual composed action
targets through open shadow roots and forwarding slots; decorative wrappers are not accepted as
stops, while multiple actionable descendants remain independently arrow-reachable. Keyboard
movement starts from the action that received the event rather than stale controlled state.

`rect` is the sole public positioning input. Internal computed coordinates are intentionally
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
`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):
`--lr-overlay-surface` (default `var(--lr-color-surface-overlay)`), `--lr-overlay-border` (default
`var(--lr-color-border)`) and `--lr-overlay-shadow-anchored` (default `var(--lr-shadow-m)`). None is
declared on `:host`, so one declaration on `:root` — or on any ancestor, to scope it — retints this
surface together with every other floating surface in the library. `--lr-overlay-radius` (default `var(--lr-radius)`) is the matching corner radius.

**Slots:** `actions` — extra actions rendered after the built-in ask/quote/cite/copy buttons,
inside the same `role="toolbar"` element and roving-tabindex group. **Optional peer deps:** none.

```ts
import "@aceshooting/lyra-ui/components/conversation/selection-toolbar/selection-toolbar.js";
```

## `lr-realtime-session`

Provider-neutral realtime voice shell composing connection state, `lr-audio-visualizer`,
`lr-push-to-talk`, and `lr-transcript-feed`. Transport/authentication/playback remain host-owned.

**Properties:** `state: RealtimeConnectionState = 'disconnected'` (reflected), where the closed set
is `'disconnected' | 'connecting' | 'connected' | 'reconnecting' | 'error'`; `voiceState:
AudioVisualizerState = 'idle'` (attribute `voice-state`); `level: number | null = null` (finite,
clamped by the composed visualizer); `stream: MediaStream | null = null`; `sessionId: string = ''`
(attribute `session-id`) — forwarded to the transcript feed so changing sessions resets finalized
entry announcement identity; `entries: LyraTranscriptEntry[] = []` (attribute: false);
`muted: boolean = false` (reflected);
`showCapture: boolean = true` (attribute `show-capture`, reflected, string-aware true-default
converter); `label: string = ''`. Invalid attribute or direct-property values for `state` and
`voiceState` normalize to their safe defaults (`'disconnected'` and `'idle'`) through the same
closed-set converter.

When a state transition removes a focused session action, focus moves to the replacement
connect/disconnect action. Setting `showCapture` to `false` applies that handoff only when the
capture control owned focus; a surviving built-in, slotted, or external focus destination is not
moved.

**Events:** session intents are `lr-connect`, `lr-disconnect`, `lr-mute-change` (`{ muted }`), and
`lr-interrupt`. The composed capture's complete public event surface bubbles through unchanged and
is also included in `LyraRealtimeSessionEventMap`: `lr-record-start` (`{ stream }`),
`lr-record-chunk` (`{ blob }`), `lr-record-stop` (`{ blob, durationMs }`), `lr-record-cancel` (no
detail), `lr-record-error` (`{ error }`), `lr-level` (`{ level }`), and
`lr-record-state-change` (`{ state }`). These are the child's original bubbling/composed events rather than
parent re-emissions;
normal Shadow DOM retargeting means a listener outside the session observes the session as `target`.
The composed transcript's internal `lr-follow-change` event is contained and is not part of this
session shell's public event surface.

**CSS parts:** `base`, `header`, `status`, `activity`, `controls`, `connect`, `disconnect`, `mute`,
`interrupt`, `capture`, `transcript`, `error`.

Visible status and error text remain ordinary, non-live content. After the initial baseline,
non-error `state` transitions are appended to the shared polite light-DOM announcement sink and a
transition to `error` uses the shared assertive sink instead. Initial and reconnect renders stay
silent, and sinks follow the component's `ownerDocument` when it is adopted.

**Slots:** `controls` — provider-specific actions appended to the built-in session controls.
**Optional peer deps:** none. Transport, credentials, capture permission, and media playback
remain host-owned.

```ts
import "@aceshooting/lyra-ui/components/conversation/realtime-session/realtime-session.js";
```

## Consumer integration notes

- **Markdown:** GFM task checkboxes stay disabled. When a checkbox has nonblank primary inline
  text, that primary inline text names the checkbox; nested-list text is excluded and an otherwise blank
  task receives no invented label. For an intercepted internal link that overlaps a highlight,
  `lr-highlight-activate` fires before `lr-link-click` for pointer and Enter activation;
  external links keep their native navigation.
- **Catalog controls:** `lr-model-select` and `lr-voice-picker` reflect `readonly`. It blocks user
  typing and catalog commits without disabling focus, popup navigation, selection/copy, reset,
  submission, or programmatic writes; voice previews remain available. They are barred from native
  constraint validation while disabled, readonly, or disabled by a fieldset. Voice preview actions
  expose the shared hover/pressed fill and icon hooks in both standalone and catalog-row layouts.
- **Status values:** invalid direct or attribute status writes on `lr-chat-composer` normalize and
  reflect to `idle`. `lr-prompt-input` and `lr-agent-workspace` read invalid forwarded status as the
  safe `idle` state without rewriting their host attributes.
- **Feedback toolbar:** `lr-message-actions.feedbackPending` identifies a built-in feedback request
  awaiting settlement. Pass the frozen `submissionId` from `lr-feedback-submit` to
  `finalizePendingSubmit()` or `revertPendingSubmit()`. Logical toolbar actions may implement
  `releaseTabIndex()` to restore an unchanged authored tabindex when the toolbar stops managing it;
  a later author write is never overwritten.
- **Message content:** `MessagePartsContentMode` is exported. Unsupported direct or
  `content-mode` attribute values normalize and reflect as `markdown`.
- **Prompt queues:** items and attachments are captured on assignment; create and reassign a new
  collection after changes, because changing an assigned record or reassigning the same mutated
  array does not update the view.
  Invalid rows are ignored, and the first valid duplicate id wins. A suggestion popup stays open
  only while focus remains in its textarea or popup; accepting an option handles Enter or Tab before
  textarea submission.
- **Push-to-talk:** releasing hold mode while permission is pending leaves that request eligible
  only for the next same-document held press; otherwise a later grant is discarded. A held press
  during a stopping take starts after the current take ends. Disablement, disconnection, or a
  cross-document move prevents a later permission result from starting or finishing capture.
- **Code blocks:** malformed highlight-line segments are independently ignored while valid segments
  remain. When Shiki is unavailable, readable plain text remains available.
- **Threads:** `lr-thread-list` captures display fields when `threads` is assigned; its render,
  filter, and grouping callbacks receive the original records, so create and reassign a new
  collection to update. Changing an assigned record or reassigning the same mutated array does not
  update the view.
  Group toggles and row actions have independent hover/pressed background and foreground tokens.
- **Audio visualizer:** an author-supplied `role` wins; the component supplies `role="img"` only
  when absent. With a working observer it waits for its first valid visible entry and pauses
  offscreen; unavailable/broken observation renders eagerly. Canvas input is clamped after gain to
  `-1..1` for waveforms and `0..1` for bars.

## Exported TypeScript contracts

These named interfaces and helper signatures are available to typed integrations. They are grouped by capability so the component sections above can stay focused.

- **`components-conversation-chat-message-chat-message-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/conversation/chat-message/chat-message.class.js`.
  `ChatMessageToggleDetail {
    collapsed: boolean;
  }`

- **`components-conversation-chat-composer-chat-composer-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/conversation/chat-composer/chat-composer.class.js`.
  `normalizeChatComposerStatus(value: unknown): ChatComposerStatus`

- **`components-conversation-checkpoint-checkpoint-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/conversation/checkpoint/checkpoint.class.js`.
  `CheckpointRestoreDetail {
    checkpointId: string;
    label: string;
  }`

- **`components-conversation-code-block-code-loader-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/conversation/code-block/code-loader.js`.
  `loadShikiHighlighter(): Promise<ShikiHighlighter | null>`
  Import: `@aceshooting/lyra-ui/components/conversation/code-block/code-loader.js`.
  `loadShikiLanguage(hl: ShikiHighlighter, lang: string): Promise<boolean>`
  Import: `@aceshooting/lyra-ui/components/conversation/code-block/code-loader.js`.
  `shikiHasLoadedLanguage(hl: ShikiHighlighter, lang: string): boolean`

- **`components-conversation-code-block-shiki-types-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/conversation/code-block/code-loader.js`.
  `loadShikiHighlighterCore(languages: Record<string, ShikiLanguageInput>): Promise<ShikiHighlighterCore | null>`
  Results are cached by map identity, with bounded weak reuse across equivalent deeply frozen plain
  grammar maps. Mutable maps and unusual grammar values retain identity-only caching. Every
  distinct active engine (see `setShikiCoreEngine()` below) gets its own cached core per
  `languages` object -- two engines never share one.
  Import: `@aceshooting/lyra-ui/components/conversation/code-block/code-block-core.js` (also
  re-exported from `@aceshooting/lyra-ui/components/conversation/markdown/markdown-core.js`) --
  `shiki-types.js` itself is an internal support module with no package subpath export.
  `setShikiCoreEngine(engine: ShikiEngineOption): void`
  Selects the regex-scanning engine every subsequent `loadShikiHighlighterCore()` call builds its
  `HighlighterCore` with. `'oniguruma'` (the default) fetches the binary `shiki/onig.wasm` asset;
  `'javascript'` selects shiki's pure-JS engine instead, avoiding WebAssembly entirely. A function
  value is called on first use per distinct `languages` object and may return the engine
  synchronously or via a promise.
  Import: `@aceshooting/lyra-ui/components/conversation/code-block/code-block-core.js` (also
  `.../markdown/markdown-core.js`).
  `ShikiEngineOption = 'oniguruma' | 'javascript' | ShikiRegexEngineFactory`
  Import: `@aceshooting/lyra-ui/components/conversation/code-block/code-block-core.js` (also
  `.../markdown/markdown-core.js`).
  `ShikiRegexEngineFactory = () => ShikiRegexEngine | Promise<ShikiRegexEngine>`
  A factory `setShikiCoreEngine()` accepts directly: called once per distinct `languages` object
  the first time it is used.
  Import: `@aceshooting/lyra-ui/components/conversation/code-block/code-block-core.js` (also
  `.../markdown/markdown-core.js`).
  `resolvedShikiLanguages(languages: Readonly<Record<string, ShikiLanguageSource>>): Record<string, ShikiLanguageInput>`
  The already-resolved subset of a `languages` map that may also contain lazy loaders -- the subset
  `loadShikiHighlighterCore()` seeds a `HighlighterCore` with at creation. Returns the same object
  unchanged when there is no loader, preserving identity-keyed core reuse for a caller that never
  uses one.
  Import: `@aceshooting/lyra-ui/components/conversation/code-block/code-block-core.js` (also
  `.../markdown/markdown-core.js`).
  `ensureShikiLanguageLoaded(core: ShikiHighlighterCore, key: string, source: ShikiLanguageSource): Promise<boolean>`
  Resolves one `languages` entry that may be a lazy loader, loading it into `core` via
  `HighlighterCore.loadLanguage()` the first time a given (core, key) pair is seen, memoized after
  that. Resolves to `true` immediately for an entry that is already a plain grammar. Never rejects:
  a loader that throws, or a `loadLanguage()` call that rejects, resolves to `false` instead.
  Import: `@aceshooting/lyra-ui/components/conversation/code-block/code-loader.js`.
  `normalizeShikiLanguage(lang: string): string`
  Import: `@aceshooting/lyra-ui/components/conversation/code-block/code-loader.js`.
  `ShikiHighlighter {
    codeToHtml(code: string, options: Record<string, unknown>): string;
    getLoadedLanguages(): string[];
    loadLanguage(language: string | ShikiLanguageInput): Promise<void>;
  }`
  Import: `@aceshooting/lyra-ui`.
  `ShikiLanguageRegistration {
    name: string;
    scopeName: string;
    displayName?: string;
    aliases?: string[];
    patterns?: unknown[];
    repository?: Record<string, unknown>;
  }`
  Import: `@aceshooting/lyra-ui/components/conversation/code-block/code-block.js`.
  `ShikiLanguageInput = ShikiLanguageRegistration | readonly ShikiLanguageRegistration[]`
  Import: `@aceshooting/lyra-ui/components/conversation/code-block/code-block-core.js`.
  `ShikiLanguageLoader = () => Promise<ShikiLanguageInput | { default: ShikiLanguageInput }>`
  Called at most once per key, memoized, the first time a fenced block requests that language. May
  return either a grammar directly or an ES module namespace/default-export wrapper around one,
  matching a plain `() => import('@shikijs/langs/<name>')` call site verbatim.
  Import: `@aceshooting/lyra-ui/components/conversation/code-block/code-block-core.js`.
  `ShikiLanguageSource = ShikiLanguageInput | ShikiLanguageLoader`
  One `languages` map entry on `<lr-code-block-core>`/`<lr-markdown-core>`: either an
  already-resolved grammar (seeded eagerly into the `HighlighterCore` at creation) or a lazy
  `ShikiLanguageLoader`.
  Import: `@aceshooting/lyra-ui/components/conversation/code-block/code-block-core.js` (also
  `.../markdown/markdown-core.js`).
  `ShikiRegexEngine {
    createScanner(patterns: readonly (string | RegExp)[]): unknown;
    createString(value: string): unknown;
  }`
  The peer-neutral regex-scanning capability `createHighlighterCore()`'s own `engine` option
  accepts; only ever forwarded through to shiki's own `createHighlighterCore()`, never called
  directly.

- **`components-conversation-conversation-item-conversation-item-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/conversation/conversation-item/conversation-item.class.js`.
  `ConversationItemRenameDetail {
    conversationId: string;
    label: string;
  }`
  Import: `@aceshooting/lyra-ui/components/conversation/conversation-item/conversation-item.class.js`.
  `ConversationItemSelectDetail {
    conversationId: string;
  }`

- **`components-conversation-markdown-katex-loader-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui`.
  `KatexApi {
    renderToString(tex: string, options?: Record<string, unknown>): string;
  }`

- **`components-conversation-markdown-markdown-base-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui`.
  `MarkdownVariantContext {
    readonly tag: 'lr-markdown' | 'lr-markdown-core';
    readonly connectedInstances: Set<MarkdownRuntimeBase>;
    readonly sharedParser: MarkdownParserController;
    readonly katexState: MarkdownKatexState;
  }`

- **`components-conversation-markdown-markdown-loader-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/conversation/markdown/markdown-loader.js`.
  `getMarkdownDepsIfLoaded(): MarkdownDeps | undefined`
  Import: `@aceshooting/lyra-ui/components/conversation/markdown/markdown-loader.js`.
  `loadMarkdownAndSanitizer(importMarked?: () => Promise<unknown>, importDompurify?: () => Promise<unknown>): Promise<MarkdownDeps>`
  Import: `@aceshooting/lyra-ui/components/conversation/markdown/markdown-loader.js`.
  `loadMarkdownDeps(): Promise<MarkdownDeps>`
  Import: `@aceshooting/lyra-ui/components/conversation/markdown/markdown-loader.js`.
  `LyraMarkedParser {
    readonly defaults: Record<string, unknown>;
    use(...extensions: MarkedExtension[]): LyraMarkedParser;
    parse(source: string, options: Record<string, unknown> & {
      async: false;
    }): string;
    parse(source: string, options?: Record<string, unknown>): string | Promise<string>;
  }`
  Import: `@aceshooting/lyra-ui/components/conversation/markdown/markdown-loader.js`.
  `MarkdownDeps {
    marked: MarkedModule | undefined;
    DOMPurify: HtmlSanitizer | undefined;
  }`
  Import: `@aceshooting/lyra-ui/components/conversation/markdown/markdown-loader.js`.
  `MarkedExtension {
    renderer?: Partial<MarkedRenderer>;
    extensions?: unknown[];
    [key: string]: unknown;
  }`
  Import: `@aceshooting/lyra-ui/components/conversation/markdown/markdown-loader.js`.
  `MarkedModule {
    Marked: new () => LyraMarkedParser;
  }`
  Import: `@aceshooting/lyra-ui/components/conversation/markdown/markdown-loader.js`.
  `MarkedParserContext {
    parser: {
      parse(tokens: unknown[]): string;
      parseInline(tokens: unknown[], renderer?: unknown): string;
      textRenderer: unknown;
    };
    listitem(token: unknown): string;
    tablecell(token: unknown): string;
    tablerow(token: {
      text: string;
    }): string;
  }`
  Import: `@aceshooting/lyra-ui/components/conversation/markdown/markdown-loader.js`.
  `MarkedRenderer {
    heading(this: MarkedParserContext, token: MarkedTokenBase & {
      depth: number;
    }): string;
    paragraph(this: MarkedParserContext, token: MarkedTokenBase): string;
    list(this: MarkedParserContext, token: {
      ordered: boolean;
      start: number;
      items: unknown[];
    }): string;
    code(this: MarkedParserContext, token: {
      lang?: string;
      text: string;
      escaped: boolean;
    }): string;
    codespan(this: MarkedParserContext, token: {
      text: string;
    }): string;
    blockquote(this: MarkedParserContext, token: MarkedTokenBase): string;
    table(this: MarkedParserContext, token: {
      header: Array<MarkedTokenBase & {
        align?: string | null;
      }>;
      rows: Array<Array<MarkedTokenBase & {
        align?: string | null;
      }>>;
    }): string;
    link(this: MarkedParserContext, token: MarkedTokenBase & {
      href: string;
      title?: string | null;
    }): string;
    image(this: MarkedParserContext, token: MarkedTokenBase & {
      href: string;
      title?: string | null;
    }): string;
    html(this: MarkedParserContext, token: {
      text: string;
    }): string;
  }`
  Import: `@aceshooting/lyra-ui/components/conversation/markdown/markdown.js`.
  `preloadMarkdown(): Promise<MarkdownDeps>`

- **`components-conversation-markdown-markdown-shared-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui`.
  `MarkdownKatexState {
    getIfLoaded(): KatexApi | null;
    isConfirmedMissing(): boolean;
    startLoad(onResolved: () => void): void;
  }`
  Import: `@aceshooting/lyra-ui`.
  `PendingHighlight {
    key: string;
    lang: string;
    code: string;
  }`

- **`components-conversation-message-actions-toolbar-actions-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/conversation/message-actions/toolbar-actions.js`.
  `isLyraToolbarActionProvider(value: unknown): value is LyraToolbarActionProvider`
  Import: `@aceshooting/lyra-ui/components/conversation/message-actions/toolbar-actions.js`.
  `LyraToolbarAction {
    readonly id: string;
    readonly disabled: boolean;
    focus(options?: FocusOptions): void;
    setTabIndex(tabIndex: 0 | -1): void;
    releaseTabIndex?(): void;
    matchesEventPath(path: readonly EventTarget[]): boolean;
  }`
  Import: `@aceshooting/lyra-ui/components/conversation/message-actions/toolbar-actions.js`.
  `LyraToolbarActionProvider {
    getToolbarActions(): readonly LyraToolbarAction[];
  }`

- **`components-conversation-message-feedback-message-feedback-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/conversation/message-feedback/message-feedback.class.js`.
  `MessageFeedbackDetailConfiguration {
    readonly reasons?: readonly MessageFeedbackReason[];
    readonly commentable?: boolean;
  }`
  Import: `@aceshooting/lyra-ui/components/conversation/message-feedback/message-feedback.class.js`.
  `MessageFeedbackReason {
    readonly id: string;
    readonly label: string;
  }`
  Import: `@aceshooting/lyra-ui/components/conversation/message-feedback/message-feedback.class.js`.
  `MessageFeedbackSubmitDetail {
    rating: MessageFeedbackValue;
    reasonIds: string[];
    comment: string;
    readonly submissionId: string;
  }`

- **`components-conversation-model-select-model-select-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/conversation/model-select/model-select.class.js`.
  `LyraModelCatalogEntry extends LyraCatalogEntry {
    icon?: string;
    // Inherited from LyraCatalogEntry.
    id: string;
    label: string;
    disabled?: boolean;
  }`

- **`components-conversation-model-settings-panel-model-settings-panel-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/conversation/model-settings-panel/model-settings-panel.class.js`.
  `ModelSettingsChangeDetail {
    model: string;
    inCatalog: boolean;
    temperature: number;
  }`

- **`components-conversation-prompt-input-prompt-input-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/conversation/prompt-input/prompt-input.class.js`.
  `LyraPromptInputAttachment extends Omit<DocumentRef, 'id'> {
    attachmentId: string;
    file?: File;
    bytes?: number;
    status?: LyraAttachmentUploadStatus;
    progress?: number;
    // Inherited from Omit<DocumentRef, 'id'>.
    name: string;
    mimeType?: string;
    uri?: string;
    version?: string;
  }`
  Import: `@aceshooting/lyra-ui/components/conversation/prompt-input/prompt-input.class.js`.
  `LyraPromptSuggestion extends LyraMentionItem {
    insertText?: string;
    // Inherited from LyraMentionItem.
    readonly suggestionId: string;
    readonly label: string;
    readonly description?: string;
    readonly icon?: string;
    readonly disabled?: boolean;
  }`

- **`components-conversation-prompt-queue-prompt-queue-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/conversation/prompt-queue/prompt-queue.class.js`.
  `PromptQueueChangeDetail {
    items: PromptQueueItem[];
    reason: PromptQueueChangeReason;
    itemId: string;
  }`
  Import: `@aceshooting/lyra-ui/components/conversation/prompt-queue/prompt-queue.class.js`.
  `PromptQueueItem {
    id: string;
    value: string;
    attachments?: readonly DocumentRef[];
    createdAt?: number;
    metadata?: Record<string, unknown>;
  }`

- **`components-conversation-selection-toolbar-selection-toolbar-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/conversation/selection-toolbar/selection-toolbar.class.js`.
  `SelectionActionDetail {
    readonly action: SelectionAction;
    readonly text: string;
    readonly anchor: DocumentLocator | null;
  }`

- **`components-conversation-streaming-text-streaming-text-base-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/conversation/streaming-text/streaming-text.class.js`
  (also re-exported from `@aceshooting/lyra-ui/components/conversation/streaming-text/streaming-text-core.class.js`)
  — `streaming-text-base.class.js` itself is an internal support module shared by both
  `<lr-streaming-text>` and `<lr-streaming-text-core>`, with no package subpath export of its own.
  `looksLikeMarkdown(text: string): boolean`

- **`components-conversation-suggestion-chips-suggestion-chips-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/conversation/suggestion-chips/suggestion-chips.class.js`.
  `LyraChatSuggestion {
    suggestionId: string;
    label: string;
    icon?: string;
    detail?: string;
    disabled?: boolean;
  }`

- **`components-conversation-transcript-feed-transcript-feed-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/conversation/transcript-feed/transcript-feed.class.js`.
  `LyraTranscriptEntry {
    id: string;
    speaker?: string;
    text: string;
    interim?: boolean;
    timestamp?: LyraTimestamp;
  }`

- **`components-conversation-voice-picker-voice-picker-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/conversation/voice-picker/voice-picker.class.js`.
  `LyraVoiceCatalogEntry extends LyraCatalogEntry {
    language?: string;
    description?: string;
    previewUrl?: string;
    // Inherited from LyraCatalogEntry.
    id: string;
    label: string;
    disabled?: boolean;
  }`

- **`internal-catalog-picker-contracts`** — Shared utility contracts.
  Import: `@aceshooting/lyra-ui/components/conversation/model-select/model-select.class.js`.
  `LyraCatalogEntry {
    id: string;
    label: string;
    disabled?: boolean;
  }`

# Agent tooling, tool calls & evaluation (`components/agent-tools/`)

## Breaking changes, fixes, and renames in 9.0.0

`<lr-trace-tree>` and `<lr-subagent-panel>`: `label` no longer defaults to `''`; it is
`string | undefined` and omitted means "use the localized default" — an explicit `label=""` now
renders empty instead of silently falling back.

`<lr-commit-card>`: `filesCollapsed`/`files-collapsed` renamed to `filesExpanded`/`files-expanded`,
with the default inverted (`filesExpanded = false`) so the rendered starting state is unchanged;
update `el.filesCollapsed = true` to `el.filesExpanded = false` (and vice versa).

`<lr-agent-trace>`: `hideBars`/`hide-bars` renamed to `showBars`/`show-bars` (default `true`),
matching the positive-polarity `showTokens`/`showCost` on the same element; update
`el.hideBars = true` to `el.showBars = false` (and vice versa).

`<lr-evaluation-run>` is renamed to `<lr-eval-run>` (class `LyraEvaluationRun` → `LyraEvalRun`).
Every `Evaluation*`-prefixed exported type is renamed to `Eval*` (`EvaluationContentFormat` →
`EvalContentFormat`, `EvaluationContent` → `EvalContent`, `EvaluationExampleResult` →
`EvalExampleResult`, `EvaluationExampleToggleDetail` → `EvalExampleToggleDetail`,
`EvaluationCitationSelectDetail` → `EvalCitationSelectDetail`, `EvaluationToolApprovalDetail` →
`EvalToolApprovalDetail`, `EvaluationToolActivateDetail` → `EvalToolActivateDetail`,
`EvaluationToolRenderErrorDetail` → `EvalToolRenderErrorDetail`, `EvaluationClaimSelectDetail` →
`EvalClaimSelectDetail`, `LyraEvaluationRunEventMap` → `LyraEvalRunEventMap`), matching sibling
`lr-eval-dataset`/`lr-eval-result`. The localized string keys and their English text are unchanged —
only the tag/class/type names moved.

`<lr-schema-viewer>` is renamed to `<lr-json-schema-viewer>` (class `LyraSchemaViewer` →
`LyraJsonSchemaViewer`, event map `LyraSchemaViewerEventMap` → `LyraJsonSchemaViewerEventMap`),
freeing the generic name for a future non-JSON schema viewer. `JsonSchemaNode`/`SchemaValidationIssue`
and the `--lr-schema-viewer-*` CSS custom properties are unchanged.

Security fix (non-breaking): `<lr-mcp-app>`'s `postMessage` call to its sandboxed frame now always
uses the correctly computed target origin instead of an inverted check that previously fell through
to the wildcard `'*'` origin unconditionally.

## `lr-tool-call-chip`

A compact inline pill representing one tool/function call an agent made mid-conversation, e.g.
`web_search: Searching web…` with a `running` spinner. First-party invention (no Web Awesome
equivalent). It owns no detail surface of its own — activating it (click or Enter/Space while
focused) fires `lr-tool-call-chip-select`; a consumer wires that to opening a
`<lr-tool-result-dialog>` (or anything else) at the call site, keeping the chip reusable wherever
a compact call summary is useful, with or without a detail surface behind it.

Removing `category` or `summary` hides that optional text; assigning either attribute again restores
its content.

**Properties:**

- `name: string = ''` — the tool/function name, e.g. `web_search`
- `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
- `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
- `icon: string = ''` — literal icon hint (e.g. an emoji) rendered when the `icon` slot is empty;
  ignored once anything is assigned to `slot="icon"`
- `callId: string = ''` (attribute `call-id`) — unique identifier for this invocation, echoed back
  in `lr-tool-call-chip-select`'s detail so a listener can correlate the click with the call it fired for

**Events:** `lr-tool-call-chip-select` (`detail: { name: string; callId: string }`) — fired on
click or Enter/Space activation of the pill, exactly once per activation. The `lr-tool-chip-select`
alias (deprecated since 4.0.0) was removed in 9.0.0; listen for `lr-tool-call-chip-select` instead —
the detail is identical.

**Methods:** `focus(options?)`, `blur()`, and `click()` delegate to the internal native chip
button, so programmatic focus/activation reaches the same semantic owner as pointer and keyboard
interaction.

**Slots:** default (rich tooltip/detail content — e.g. the tool's raw arguments or a short preview —
shown in a floating tooltip on hover/focus; nothing renders at all, no hover affordance, when this
slot is empty), `icon` (overrides the built-in per-status glyph entirely via native slot-fallback
content — assigned content wins; otherwise the `icon` prop is rendered as a literal hint; otherwise
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`),
`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)`,
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` →
`--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
referenced: `--lr-color-text-quiet`, `--lr-color-surface`, `--lr-color-border`,
`--lr-color-brand`/`-brand-quiet`, `--lr-color-success`/`-success-quiet`,
`--lr-color-danger`/`-danger-quiet`, `--lr-color-warning`/`-warning-quiet`, `--lr-color-text`,
`--lr-space-xs/-s/-m`, `--lr-radius`, `--lr-shadow`, `--lr-focus-ring-*`,
`--lr-transition-fast`.

> Retheming a group of chips from outside `<lr-tool-call-chip>` (e.g. per-tool or per-status
> colors)? Set the component hooks above on their ancestor wrapper. Use `--lr-theme-*` instead only
> when changing a shared semantic palette input for the entire subtree.

The anchored detail tooltip is a floating surface and paints from the **shared overlay-surface family** (16.0.0):
`--lr-overlay-surface` (default `var(--lr-color-surface-overlay)`), `--lr-overlay-border` (default
`var(--lr-color-border)`) and `--lr-overlay-shadow-anchored` (default `var(--lr-shadow-m)`). None is
declared on `:host`, so one declaration on `:root` — or on any ancestor, to scope it — retints this
surface together with every other floating surface in the library. `--lr-overlay-radius` (default `var(--lr-radius)`) is the matching corner radius.

`--lr-positioning-strategy` (16.0.0) — the detail tooltip reads this same cascading
`absolute`/`fixed` override documented on `<lr-popover>` when it is (re)positioned, falling back to
its own `fixed` default when nothing is set. There is no per-instance `positioning-strategy`
property on `<lr-tool-call-chip>`; set the custom property on `:root`, a theme, or one clipping
ancestor to change every unset chip beneath it.

**Optional peer deps:** none.

```html
<lr-tool-call-chip
  name="web_search"
  category="research"
  status="running"
  summary="Searching web…"
  duration-ms="820"
  call-id="call_123"
>
  <pre slot="icon" style="display:none"></pre>
  <code>{"query": "lyra ui components"}</code>
</lr-tool-call-chip>
<script type="module">
  document
    .querySelector("lr-tool-call-chip")
    .addEventListener("lr-tool-call-chip-select", (e) => openDetail(e.detail.callId));
</script>
```

The default slot's tooltip uses the same `'top-start'` placement as `<lr-combobox>`'s listbox, and
appears/disappears instantly
on hover/focus/blur/mouseleave with no fade transition and no "pointer moved into the tooltip"
tracking — it's documented as read-only preview content, not an interactive surface meant to retain
focus of its own. `denied` gets its own warning-toned glyph and color (a policy rejection, not a
runtime failure) distinct from `error`'s danger tone, matching `<lr-tool-result-dialog>`'s
identical status vocabulary so a call reads the same way in both places. Duration formatting is
sub-1000ms `"820ms"`, else trimmed to at most one decimal of seconds (`"1.5s"`, `"2s"`).

**Known gotchas:**

- meaningful default-slot text or element content enables the preview tooltip; whitespace-only
  text does not. A text preview needs no wrapper, and the preview remains inert and noninteractive
- the native button always keeps its purpose-specific generated name (`"name — summary — Status —
duration"`). A host `aria-label` remains on the host and is not cloned onto that button; even an
  explicit empty host label never leaves the actionable button unnamed
- the `icon` slot is decorative by contract. Its wrapper is both `aria-hidden` and `inert`, so do
  not place links, buttons, or other controls there; use the chip activation or detail slot instead
- Escape only dismisses the tooltip when it's open; it does not fire any event or otherwise affect
  `status`/`open` state, since the chip has no "open" state of its own beyond the tooltip

---

## `lr-tool-result-view`

Renders a tool call's result via whichever custom renderer a host app has registered for it,
falling back to `<lr-json-viewer>` whenever no renderer matches, a candidate renderer's
`matches()` predicate throws during dispatch, a renderer's optional `load()` rejects, or its
`render()` throws. First-party invention (no Web Awesome equivalent). This component
owns none of the actual visual weight of a populated tool result — that's entirely whatever the
registered renderer returns; `<lr-tool-result-view>` is just the dispatch + fallback + loading-state
shell around it.

**Properties:**

- `registry?: ToolRendererRegistry` (property only, no attribute) — a custom
  `ReadonlyMap<string, ToolRendererDefinition>` to dispatch against instead of the module-level
  default registry (see `registry.ts` below). Assignment synchronously copies at most 10,000
  entries behind a frozen readonly facade. Later mutation of the source map is not observed;
  create and reassign a new map to update dispatch. Definition records are cloned and frozen while
  callback identities are retained; lazy-load caching remains stable per assigned snapshot.
- `toolName: string = ''` (attribute `tool-name`) — the tool's name; the primary dispatch key
- `result: unknown` (property only, no attribute) — the tool call's result payload, handed to the
  matched renderer's `render()` (and to `matches()` for shape-based dispatch, and to the
  `<lr-json-viewer>` fallback)
- `args: unknown` (property only, no attribute) — the tool call's original arguments, if available,
  handed to the matched renderer's `render()` alongside `result`
- `fallback: ToolResultFallback = 'json'` (reflected), where exported `ToolResultFallback =
'json' | 'text'` — fallback-kind selector. `"json"` (the default) is
  an unconditional `<lr-json-viewer>`. `"text"` renders a _string_ `result` as preformatted text
  instead — falling back to the `"json"` behavior when `result` isn't a string, so setting
  `fallback="text"` defensively against an unpredictable result shape never renders broken output.
  Foreign runtime values normalize to the reflected `"json"` default.
- `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
  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
  property existed — leaves it at that default, and a later renderer that stays quiet doesn't
  inherit a stale outcome left behind by a previous one. Same status vocabulary as
  `<lr-tool-result-dialog>`/`<lr-tool-call-chip>`.

**Events:** `lr-render-error` (`detail: { toolName: string; error: unknown }`) — fired immediately
before falling back to `<lr-json-viewer>`, whether because no renderer matched, a candidate
renderer's `matches()` predicate threw during dispatch, a renderer's `load()` rejected, or its
`render()` threw.

**Slots:** none.

**CSS parts:** `base` — the root wrapper around the resolved renderer's output (or the loading/
fallback view); it keeps `aria-busy="true"` while a lazy renderer is loading and explicitly returns
to `aria-busy="false"` afterward. `fallback-text` — the `<pre>` element for the `fallback="text"` kind's preformatted
result text (only present in that mode). `fallback-copy` — the `<lr-copy-button>` shown when
`copyable` is set alongside the `fallback="text"` kind (only present when both are set).

**Themeable custom properties:** `--lr-tool-result-view-font` (default `var(--lr-font-mono)`, the
library's shared monospace stack, so a `--lr-theme-font-family-mono` override reaches it) — only used by the
`fallback="text"` kind's `[part='fallback-text']`. Otherwise none — the component's own styling is
deliberately minimal; all visible styling comes from whatever renderer/`<lr-skeleton>`/
`<lr-json-viewer>`/`<lr-copy-button>` child is currently mounted.

**Optional peer deps:** none required by the component itself — individual registered renderers may
of course pull in whatever they need (a charting library, a markdown renderer), which is exactly what
the lazy `load()` path in the registry exists for.

```html
<lr-tool-result-view tool-name="get_weather"></lr-tool-result-view>
<script type="module">
  const view = document.querySelector("lr-tool-result-view");
  view.result = { tempC: 21, condition: "cloudy" };
  view.args = { city: "Brussels" };
  view.addEventListener("lr-render-error", (e) => console.warn("renderer failed", e.detail));
</script>
```

### `registerToolRenderer()` and the tool-renderer registry (`registry.ts`)

A type-keyed dispatch registry — a tiny plugin system so a host app can teach
`<lr-tool-result-view>` how to draw the result of e.g. a `get_weather` or `run_query` tool call
without this library knowing anything about either. Every registered instance dispatches against
this same module-level registry unless a given `<lr-tool-result-view>`'s `registry` property is
set to a different readonly map snapshot.

**`ToolRendererDefinition`** — an exclusive
`DirectToolRendererDefinition | LazyToolRendererDefinition` union. Runtime registration, custom
registry lookup, and loaded-module boundaries validate the same shape, so plain JavaScript cannot
silently register `{}`, combine `render` with `load`, or cache an invalid loaded definition:

- direct: `render: (result: unknown, args: unknown, context?: ToolRenderContext) => unknown` and
  `load?: never` — renders the
  result (and the args that produced it) as UI. Typed as `unknown` rather than Lit's
  `TemplateResult` so any lit-html-renderable value works (a plain string, a DOM node, an array of
  templates) — consumers already own their own Lit import and don't need this module to add one.
  The 3rd `context` argument is additive: it's the _last_ positional parameter, so a pre-existing
  2-arg `render(result, args)` function stays assignable to this type unchanged — JS/TS function
  assignability allows an implementation with fewer parameters than its declared type. Direct
  callers may omit `context`; component invocations always provide it. Use
  `context?.reportStatus(status)` (see `ToolRenderContext` below) to signal a non-throwing outcome
  — e.g. an application-level failure the renderer still drew real UI for — instead of throwing,
  which discards that UI for the `<lr-json-viewer>` fallback instead
- either branch may include `matches?: (payload: unknown) => boolean` — facade/shape-based dispatch predicate, consulted only
  when no exact `toolName` key matches (see dispatch order below); only ever consulted _before_
  `load` resolves when supplied inline at registration time — a definition that needs shape-based
  dispatch and also wants to lazy-load its `render` should register a lightweight synchronous
  `matches` up front alongside `load`
- lazy: `load: () => Promise<DirectToolRendererDefinition | { default:
DirectToolRendererDefinition }>` and `render?: never` — lazy loader
  for a code-split renderer, so a host app can defer the cost of a rarely-used or heavy renderer
  (e.g. one pulling in a charting library) instead of paying for it on every page that merely
  registers it. Resolves to either a definition directly, or a `{ default }`-shaped module namespace
  object, so `load: () => import('./my-renderer.js')` works unmodified when that module's default
  export is itself a `ToolRendererDefinition`

**`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
  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
  registered directly.

```ts
registerToolRenderer("run_query", {
  render: (result, _args, context) => {
    if ((result as { rows?: unknown[] })?.rows === undefined) {
      context?.reportStatus("error");
      return html`<p class="query-error">The query returned no result set.</p>`;
    }
    return html`<query-result-table
      .rows=${(result as { rows: unknown[] }).rows}
    ></query-result-table>`;
  },
});
```

**Exports:**

- `registerToolRenderer(name: string, def: ToolRendererDefinition): void` — registers (or
  overwrites) the renderer for `name` in the module-level default registry
- `getDefaultToolRendererRegistry(): ToolRendererRegistry` — returns the default `Map` that
  `registerToolRenderer()` writes to and every `<lr-tool-result-view>` reads from unless its own
  `registry` prop is set
- `findToolRenderer(toolName: string, payload: unknown, registry?: ToolRendererRegistry):
ToolRendererDefinition | undefined` — the dispatch function `<lr-tool-result-view>` calls
  internally on every resolve; exposed for direct use too
- `loadToolRenderer(def: ToolRendererDefinition): Promise<DirectToolRendererDefinition>` — resolves `def`
  to a definition guaranteed to carry a real `render`, awaiting/unwrapping `def.load()` when present
  (or returning `def` unchanged otherwise)
- `clearToolRenderers(): void` — clears the default registry and its `load()` cache

**Dispatch order** (`findToolRenderer`), exactly as `<lr-tool-result-view>`'s own `resolve()` uses
it:

1. An exact `toolName` key match in the registry.
2. Failing that, the first entry — in registration order, since a `Map` already iterates that way —
   whose `matches(payload)` returns `true`. Useful when several tool names share one result shape
   (e.g. every `*_search` tool returning `{ results: [...] }`) or when the caller doesn't reliably
   know the tool name at all.
3. `undefined` if neither matches — `<lr-tool-result-view>` falls back to `<lr-json-viewer>` and
   fires `lr-render-error`.

Once a definition is found, if it carries `load`, `<lr-tool-result-view>` shows a
decorative `<lr-skeleton shape="rect" height="4rem">` while `loadToolRenderer()` resolves it.
The nested skeleton has announcements disabled; the stable `base` busy state and an ordinary,
visually hidden localized Loading label expose the in-progress state without creating a shadow-root
live region. The resolved
`load()` promise is cached keyed by _definition object identity_ (a `WeakMap`, not by tool-name
string) — two different registries that happen to reuse the same tool-name string get independently
cached loads, and any given lazy definition's `load()` runs at most once no matter how many times
it's dispatched to, across every `<lr-tool-result-view>` instance that resolves to it. A **rejected**
`load()` is _not_ cached — nor is a load that resolves to an invalid/another-lazy definition. The
definition stays registered, so a later resolution attempt (e.g. after a transient network failure)
gets a fresh `load()` call rather than being stuck replaying one failed promise forever.

```ts
import { registerToolRenderer } from "@aceshooting/lyra-ui/components/agent-tools/tool-result-view/registry.js";

registerToolRenderer("get_weather", {
  render: (result, args) =>
    html`<weather-card .data=${result} .city=${args?.city}></weather-card>`,
});

// Lazily loaded, shape-based fallback for every *_search tool:
registerToolRenderer("web_search", {
  matches: (payload) =>
    typeof payload === "object" && payload !== null && "results" in payload,
  load: () => import("./search-result-renderer.js"), // default export is a ToolRendererDefinition
});
```

**Known gotchas:**

- `<lr-tool-result-view>` re-resolves (re-runs the full dispatch → load → render pipeline)
  whenever `toolName`, `result`, `args`, or `registry` changes, or on first update — a stale
  in-flight `load()` superseded by a newer change is detected via an internal generation counter and
  its result is discarded rather than clobbering a more recent render
- registering under the same `name` twice silently overwrites the earlier definition — there is no
  warning or error
- `matches` is a linear scan over every registered definition's `matches` in registration order; it
  only runs when the exact-name lookup misses, so tool names with a direct registration never pay
  that scan cost
- `status` is reset to `'success'` immediately before every `render()` call, not merely at
  construction — a renderer that reported `'error'` on one result does not leave that status
  behind once dispatch moves on to a different (quiet) renderer; a `reportStatus()` call that
  arrives asynchronously after a _newer_ resolve has already started (a stale promise the previous
  render kicked off) is detected via the same generation counter as the `load()` staleness guard
  and discarded rather than clobbering the newer status
- **don't type a custom renderer against a hand-rolled, over-generic function signature** (e.g.
  `render: (...args: any[]) => unknown`, or a locally-declared narrower alias then cast to
  `ToolRendererDefinition`) — write the registration as a plain object literal (as in every example
  above) or annotate it as `ToolRendererDefinition` directly, so TypeScript checks the actual
  current `render`/`matches`/`load` shape, including the `context: ToolRenderContext` 3rd
  parameter and the exact `ToolResultStatus` string union `reportStatus` accepts. A loosened/`any`
  signature type-checks either way but silently gives up the compiler's ability to catch a typo'd
  status string or a dropped `context` parameter
- `fallback` implements exactly two kinds, `"json"` and `"text"`; any _other_ runtime value
  normalizes to reflected `"json"`, while `"text"` with a non-string result uses the JSON view.
  Only `"text"` renders
  `[part="fallback-text"]`/`[part="fallback-copy"]`

---

## `lr-tool-result-dialog`

A full tool-call detail overlay: a status/duration header plus a `body` slot where a consumer
typically places a `<lr-tab-group>` with Input/Preview/JSON/Raw panels. First-party invention (no Web
Awesome equivalent). This component knows nothing about what's inside that slot — it only supplies
the modal chrome around it. It keeps its own shadow template rather than nesting a `<lr-dialog>`,
so slot-forwarding does not put a forwarding `<slot>` where a slotted `<lr-tab-group>`'s own light-DOM
child scan expects real projected content, while its modal behavior participates in the shared
overlay stack.

Assigning `accessibleLabel` directly names the inner dialog when no host `aria-label` is present. A
host `aria-label` retains its separate host ownership, and an empty direct value uses the tool
title.

**Properties:**

- `open: boolean = false` (reflected) — whether the dialog is open; set it directly or use the
  lifecycle methods below
- `lightDismiss: boolean = false` (attribute `light-dismiss`) — opt in to backdrop-click
  dismissal; Escape and the built-in close button remain available without it
- `accessibleLabel: string | null = null` (attribute `aria-label`) — a host attribute names the
  host itself, while the dialog panel remains labelled by its visible tool-name title instead of
  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>`
- `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

**Methods:** `show(): void` opens the dialog; `hide(reason: ToolResultDialogCloseReason = 'api'):
void` is the reasoned API dismissal;
`close(reason: ToolResultDialogCloseReason = 'api'): void` closes the dialog (no-op if already
closed), emits `lr-close` with `reason`, and returns focus to whatever had it before
the dialog opened. Built-in triggers call this with `'escape'`, `'backdrop'` when `lightDismiss` is
enabled, or `'close-button'`; a
consumer's own close affordance (e.g. a footer action button) should call it directly with its own
reason string so every dismissal path funnels through the same event.

**Events:** `lr-close` (`detail: ToolResultDialogCloseReason` — `'escape'|'backdrop'|
'close-button'|'api'|string`) fired exactly once per dismissal (`'backdrop'` requires
`lightDismiss`); `lr-maximize-change` (`detail:
{ readonly maximized: boolean }`, the new `maximized` state) fired when the header's
maximize/restore toggle is clicked.

**Slots:** `body` (the dialog's main content — typically a `<lr-tab-group>` with Input/Preview/JSON/Raw
panels, entirely consumer-assembled), `footer` (optional action buttons, rendered in a bottom row —
the footer row itself is hidden via `[hidden]` when nothing is slotted)

**CSS parts:** `backdrop`, `panel` (`role="dialog"` while open), `header`, `title` (wrapper around
tool name/status/duration), `tool-name`, `status`, `duration`, `header-actions`, `maximize-button`,
`close-button`, `body`, `footer`

**Themeable custom properties:** `--lr-tool-result-dialog-overlay-color` (default
`var(--lr-color-overlay)` — the backdrop scrim color, the shared token `<lr-dialog>` and
`<lr-widget>` also read, so one theme override restyles every scrim in the app),
`--lr-tool-result-dialog-maximized-inset` (default `max(var(--lr-space-l),
var(--lr-safe-area-*))` on each side — the inset applied to the panel while `[maximized]`, so the
panel clears a notch or home indicator; overridable e.g. to leave a persistent app rail visible), and
`--lr-tool-result-dialog-spin` (default `var(--lr-transition-ambient)`, i.e. `1.8s ease-in-out`,
and effectively stopped under reduced motion because that token collapses to `0.001ms linear`), plus shared
tokens `--lr-color-surface/-border/-text-quiet/-brand/-brand-quiet/-success/-success-quiet/
-danger/-danger-quiet/-warning/-warning-quiet`, `--lr-space-*`, `--lr-radius`, `--lr-shadow`,
`--lr-icon-button-size`, `--lr-focus-ring-*`, `--lr-transition-base`.

**Optional peer deps:** none.

```html
<lr-tool-result-dialog tool-name="run_query" status="success" duration-ms="1240">
  <lr-tab-group slot="body">
    <div slot="preview" label="Preview">…</div>
    <div slot="json" label="JSON"><lr-json-viewer></lr-json-viewer></div>
  </lr-tab-group>
  <button slot="footer">Rerun</button>
</lr-tool-result-dialog>
<script type="module">
  const dialog = document.querySelector("lr-tool-result-dialog");
  dialog.querySelector("lr-json-viewer").data = result;
  dialog.open = true;
  dialog.addEventListener("lr-close", () => (dialog.open = false));
  dialog.addEventListener("lr-maximize-change", (e) =>
    console.log("maximized:", e.detail.maximized)
  );
</script>
```

While open, `[part="panel"]` takes `role="dialog"` + `aria-modal="true"` with `aria-labelledby`
pointing at the tool-name element, document scroll is locked, and Tab/Shift+Tab are bounded to the
panel's own focusable content in header-buttons → `body` slot → `footer` slot order (resolved
shadow-piercingly, so a slotted custom element's real focusable target inside its own shadow root is
found too). On open, focus moves to the first focusable element (falling back to the panel itself);
on close, focus returns to whatever element triggered the open (captured at open time via the active
element, since the trigger typically lives entirely outside this component). `maximized` toggles
between the constrained modal size and a near-fullscreen size within the same open dialog and
open/close lifecycle — unlike `<lr-widget>`'s fullscreen mode there's no separate non-modal resting
state, so no additional scroll-lock/focus-trap bookkeeping is needed for that transition alone.
Backdrop clicks leave the dialog open by default; add `light-dismiss` to opt in, matching
`<lr-dialog>`, `<lr-drawer>`, and `<lr-lightbox>`.

**Known gotchas:**

- a reconnect that preserves the same element instance (e.g. a drag-and-drop reparent) resumes its
  shared overlay registration and re-acquires the scroll lock if `open` was still `true` across the
  move — `disconnectedCallback`/`connectedCallback` fire back-to-back with no intervening update, so
  `willUpdate` never reruns to notice `open` did not change
- this component deliberately does **not** compose `<lr-dialog>` internally; it keeps its own
  panel template so a slotted `<lr-tab-group>` (or any other light-DOM-scanning child) sees real
  projected content rather than a forwarding `<slot>`, while still sharing the overlay stack
- `close()` is a no-op when `open` is already `false` — calling it twice in a row only fires
  `lr-close` once
- the `maximize`/`close` buttons are always the first elements in the Tab order while open,
  regardless of visual position, followed by `body` then `footer` content

**Additional API surface:**

- `--lr-tool-result-dialog-running-color` — Running status foreground. Default: `var(--lr-color-brand)`.
- `--lr-tool-result-dialog-running-bg` — Running status background. Default: `var(--lr-color-brand-quiet)`.
- `--lr-tool-result-dialog-pending-color` — Pending status foreground. Default: `var(--lr-color-text-quiet)`.
- `--lr-tool-result-dialog-pending-bg` — Pending status background. Default: `transparent`.
- `--lr-tool-result-dialog-success-color` — Success status foreground. Default: `var(--lr-color-success)`.
- `--lr-tool-result-dialog-success-bg` — Success status background. Default: `var(--lr-color-success-quiet)`.
- `--lr-tool-result-dialog-error-color` — Error status foreground. Default: `var(--lr-color-danger)`.
- `--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-select-dialog`

A category-grouped, filterable, searchable tool-enablement dialog for picking which agent tools are
available in a conversation. It keeps its own panel template rather than nesting `<lr-dialog>`, so
it has no dependency on the general-purpose dialog, while its modal behavior participates in the
shared overlay stack. First-party invention (no Web Awesome equivalent).

Programmatic `selectedToolIds` and `useDefaults` replacements synchronize the live checkbox and
switch state after user edits without emitting change events. Removing `search-placeholder` restores
localized copy, while an explicitly empty placeholder stays empty.

**Exported types:**

- `ToolSelectDialogTool { id: string; name: string; description?: string; category?: string; icon?:
string; disabled?: boolean; disabledReason?: string }` — one selectable agent tool. `category` groups
  the row into a heading; tools with no `category` (or an empty/whitespace-only one) fall into a
  trailing localized "Other" bucket. A caller category literally named `"Other"` remains its own
  ordinary, first-seen category and is not merged into or reordered with that uncategorized bucket.
  `icon` is a literal glyph (e.g. an emoji) rendered next to `name` — an opaque string, not a registry
  lookup, the same convention `<lr-tool-call-chip>`'s `icon` uses. `disabled` individually gates a
  tool regardless of `useDefaults`/`selectedToolIds` (e.g. a tool requiring admin approval);
  `description` and `disabledReason` are supporting descriptions associated with the checkbox
  through its stable `aria-describedby` owner; only `name` contributes to the checkbox's accessible
  name. `disabledReason` is ignored when `disabled` is falsy.
- `ToolSelectFilter = (tool: ToolSelectDialogTool, query: string) => boolean` — a predicate deciding
  whether `tool` matches an already-trimmed, already-lowercased `query`. Assign `filter` to replace the
  built-in case-insensitive name/description substring match entirely (mirrors `<lr-combobox>`'s
  `OptionFilter` convention).
- `ToolSelectionChangeDetail { selectedToolIds: string[]; useDefaults: boolean }` — the `lr-change` detail
  shape.
- `ToolSelectDialogCloseReason = 'escape' | 'backdrop' | 'api' | string` — the `lr-close` detail;
  `'escape'`/`'backdrop'` come from the dialog's own built-in dismiss triggers, any other string is
  whatever a caller passes to `close()` directly.

**Properties:**

- `open: boolean = false` (reflected) — set it directly or use the lifecycle methods below.
- `lightDismiss: boolean = false` (attribute `light-dismiss`) — opt in to backdrop-click
  dismissal; Escape remains available without it.
- `tools: ToolSelectDialogTool[] = []` (attribute: false) — the full set of tools a consumer offers,
  across all categories. `id` is the public identity: empty/blank ids are omitted and when provider
  data repeats one, the first occurrence wins consistently for grouping, filtering, counts,
  selection, and emitted ids.
- `selectedToolIds: string[] = []` (attribute: false) — the currently-enabled tool ids. Empty/blank ids
  are omitted and repeated ids are treated as one selection.
- `useDefaults: boolean = false` (attribute `use-defaults`, reflected) — whether the conversation is
  using the default tool set (`true`) or a custom selection (`false`).
- `label?: string` — the dialog's visible heading and accessible name. Omission uses localized
  `selectTools`; every supplied string, including `"Select tools"` and `""`, remains literal.
- `accessibleLabel: string | null = null` (attribute `aria-label`) — a host attribute names the
  host; the panel remains labelled by its visible heading instead of cloning that name. A direct
  property assignment made without the attribute can name the panel.
- `searchPlaceholder?: string` (attribute `search-placeholder`) — omission uses localized
  `searchToolsPlaceholder`; every supplied string, including `"Search tools…"` and `""`, remains
  literal as placeholder copy. Empty/whitespace-only copy leaves the field visually empty while
  its accessible name falls back to localized `searchToolsPlaceholder`.
- `filter: ToolSelectFilter | null = null` (attribute: false) — overrides the built-in
  case-insensitive name/description substring match.
- `autocomplete: string = ''`, `spellcheck: boolean = true`, `autocapitalize: string = ''`,
  `autoCorrect: string = ''` (`autocorrect`), `inputMode: string = ''` (`inputmode`), and
  `enterKeyHint: string = ''` (`enterkeyhint`) — forwarded to the search `<input>`.

**Methods:** `show(): void` opens the dialog; `hide(reason: ToolSelectDialogCloseReason = 'api'):
void` performs the reasoned API dismissal;
`close(reason: ToolSelectDialogCloseReason = 'api'): void` closes the dialog, emits `lr-close` with
`reason`, and returns focus to whatever had it before the dialog opened.

**Events:** `lr-change` (`detail: ToolSelectionChangeDetail` — the proposed enabled-tool selection and
`useDefaults` state) is cancelable and fires before either property changes. Calling
`preventDefault()` retains the current `selectedToolIds`/`useDefaults` values, and the built-in
checkbox or switch never flips at all — the proposal is raised from that control's own
`lr-checkbox-toggle-request`/`lr-switch-toggle-request`, before it writes its `checked` state, so a
refused change shows no flip-and-snap-back. A host can prevent a proposal while it validates or
persists it, then assign the desired detail values after that work succeeds. `lr-close`
(`detail: ToolSelectDialogCloseReason` — fired exactly once per dismissal, via Escape, a backdrop
click when `lightDismiss` is enabled, or a `close()` call), and no-detail `focus`/`blur` events
re-dispatched when the internal search input gains or loses focus.
Native `input`/`change` and prefixed `lr-input`/`lr-change` events from the built-in checkbox and
switch controls stop at the dialog boundary, as do their own
`lr-checkbox-toggle-request`/`lr-switch-toggle-request` proposals; listen for the single aggregate
`lr-change` proposal.

**Slots:** `footer` — optional action buttons (e.g. a "Done" button), rendered in a bottom row. Changes
already apply live via `lr-change`, so this slot is purely optional; only visually shown once it has
assigned elements.

**CSS parts:** `backdrop`, `panel`, `header`, `title`, `subtitle`, `search-row`, `search-input`,
`search-clear` (replaces the native search-cancel glyph the component resets; rendered only while
the field has text), `defaults-row`, `defaults-toggle`, `defaults-hint`, `body` (the
keyboard-focusable scroll region), `empty`, `category`, `category-heading`,
`category-count`, `category-list`, `tool-row`, `tool-checkbox`, `tool-name`, `tool-icon`,
`tool-description`, `tool-disabled-reason`, `limit`, `load-more`, `footer`

**Themeable custom properties:** `--lr-tool-select-dialog-overlay-color` (default
`var(--lr-color-overlay)` — the backdrop scrim color, the same shared token
`<lr-dialog>`/`<lr-tool-result-dialog>` read). `--lr-tool-select-dialog-search-min-height` (default
`auto`), `--lr-tool-select-dialog-search-font-size` (default `inherit`),
`--lr-tool-select-dialog-search-padding-inline` (default `var(--lr-space-m)`),
`--lr-tool-select-dialog-search-padding-block` (default `var(--lr-space-s)`) and
`--lr-tool-select-dialog-search-radius` (default `var(--lr-radius)`) size the search field; point
the height at a `--lr-form-control-height-*` tier to match it to a themed search field. The trailing
inline gutter is reserved for the overlaid `search-clear` button and is not a knob. The scrollable
tool list's mouse-hover preview on `[part="body"]` has its own four-longhand outline shape:
`--lr-tool-select-dialog-body-hover-outline-width` (default `var(--lr-border-width-thin)`),
`--lr-tool-select-dialog-body-hover-outline-style` (default `solid`),
`--lr-tool-select-dialog-body-hover-outline-color` (default `var(--lr-color-border)`, set to
`transparent` to opt out entirely), and `--lr-tool-select-dialog-body-hover-outline-offset`
(default `calc(-1 * var(--lr-border-width-thin))`, kept inward so the ring isn't clipped by the
body's own scrolling). Unset, all four resolve to the rule's previous literal paint. Plus shared
`--lr-space-*`, `--lr-color-surface/-border/-text/-text-quiet/-warning`, `--lr-radius`,
`--lr-shadow`, `--lr-focus-ring-width/-color/-offset`, `--lr-opacity-disabled`.

**Optional peer deps:** none — internally renders `<lr-checkbox>` and `<lr-switch>`, both bundled
dependencies of this package imported directly, not optional peers.

```html
<lr-tool-select-dialog label="Select tools">
  <button slot="footer" id="done-btn">Done</button>
</lr-tool-select-dialog>
<script type="module">
  const dialog = document.querySelector("lr-tool-select-dialog");
  dialog.tools = [
    { id: "search", name: "Web search", category: "Research" },
    { id: "python", name: "Python", category: "Code", description: "Run sandboxed Python" },
    { id: "admin", name: "Admin console", disabled: true, disabledReason: "Requires admin approval" },
  ];
  dialog.selectedToolIds = enabledToolIds;
  dialog.useDefaults = usingDefaults;
  dialog.open = true;
  dialog.addEventListener("lr-change", (e) =>
    updateTools(e.detail.selectedToolIds, e.detail.useDefaults)
  );
  dialog.addEventListener("lr-close", () => (dialog.open = false));
  dialog.querySelector("#done-btn").addEventListener("click", () => dialog.close("done"));
</script>
```

`useDefaults` is a single top-level switch: while `true`, every per-tool checkbox renders disabled
(still reflecting whatever `selected` holds — populate that with the actual default tool set whenever
`useDefaults` is true) alongside a hint explaining that turning the switch off is how to customize.
Turning it off is the only control that both flips `useDefaults` to `false` _and_ unlocks the per-tool
checkboxes for editing.

**Known gotchas:**

- No built-in footer/close button — dismissal happens via Escape, an opted-in (`light-dismiss`)
  backdrop click, or a consumer's own `footer`-slotted action calling `close()` directly.
- A row is effectively disabled whenever _either_ its own `tool.disabled` is true _or_ the top-level
  `useDefaults` switch is on — a tool without `disabled` set can still render as a locked checkbox while
  `useDefaults` is true.
- `disabledReason` text only renders when both `tool.disabled` and `tool.disabledReason` are set.
- Tool descriptions and disabled reasons are checkbox descriptions, not label content: the tool
  name remains the concise accessible name and the supporting text is linked through the checkbox's
  stable description bridge.
- Categories are grouped in first-seen order across `tools`; an empty/whitespace-only `category` folds
  into a trailing "Other" bucket that's always rendered last. A category left with zero matches after
  filtering is dropped entirely, not rendered as an empty heading. A caller-supplied category
  literally named `"Other"` is not the internal uncategorized sentinel: it stays in first-seen order
  and remains separate even when uncategorized tools are also present.
- Reconnecting the element while still `open` (e.g. a drag-and-drop reparent that keeps the same
  instance) resumes its shared overlay registration and re-acquires the scroll lock dropped in
  `disconnectedCallback`.
- The search input is the first focusable element in the panel and receives focus automatically on open.
- Matching rows mount in batches of 200. Selected matches reserve positions in the current batch,
  and a localized `[part="limit"]` notice plus `[part="load-more"]` button mounts the next 200;
  searching always considers the complete first-wins tool catalog.

---

## `lr-thinking-panel`

A collapsible panel for an AI agent's intermediate reasoning/"thinking" transcript, kept visually
and semantically distinct from its final response. First-party invention (no Web Awesome
equivalent). Same collapsible header-button-plus-region shape as `<lr-source-list>`; the default
slot is entirely free-form (a consumer-composed `<lr-streaming-text>`, `<lr-markdown>`, or
plain text) — this component has no dependency on either.

**Properties:**

- `label?: string` — omitted localizes `thinkingPanelLabel` (`'Thinking'` in the built-in English
  catalog). Any supplied string is an explicit override and renders verbatim, including
  `label="Thinking"` under a non-English `.strings` catalog and `label=""`.
- `compact: boolean = false` (reflected) — tightens the header/body padding and the header's
  internal gap for dense transcript rows. This is only a density control: its card border and
  surface remain, so use `frame="plain"` when surrounding message chrome already supplies them.
- `frame: LyraFrame = 'card'` (reflected) — the library-wide container-frame vocabulary
  (`'card' | 'plain'`). `'card'` keeps the bordered, filled outer container. `'plain'` removes its
  border, background, and corner radius so a nested panel does not double an existing frame;
  it retains the header/body divider and the active regular or compact padding. The exported
  `ThinkingPanelAppearance` alias names this same union.
- `expanded: boolean = false` (reflected) — starts collapsed, matching `<lr-source-list>`'s
  default.
- `mode: 'live' | 'post-hoc' = 'live'` (reflected) — `'live'` while reasoning is actively streaming
  in; `'post-hoc'` once it's complete and being reviewed after the fact. Drives two concrete
  behavior differences, see prose below.
- `durationMs?: number` (attribute `duration-ms`) — how long the reasoning took. Omitted entirely
  (nothing rendered in `'post-hoc'`, a pulsing placeholder in `'live'`) while unset.
- `follow: boolean = true` (reflected) — whether live, expanded content follows the transcript tail.
  A user scroll updates this property and emits `lr-follow-change`; a direct assignment is
  controlled input and emits nothing. Being a `true`-defaulting boolean, `follow="false"` in plain
  HTML is honoured (it uses `trueDefaultBooleanConverter`), so the attribute form is load-bearing.

**Methods:** `scrollToBottom(): void` — scrolls `[part="body"]` to its current bottom immediately
(no smooth-scroll animation). Safe to call directly, e.g. from a host that wants to force a
jump-to-latest action of its own.

**Events:** cancelable `lr-toggle-request` (`detail: { expanded: boolean }`) fires before a header
activation changes state. Prevent it to retain the current `expanded` value. An accepted request
then updates `expanded` and emits the non-cancelable committed `lr-toggle` with the same detail;
vetoed requests never emit the committed event. `lr-follow-change` (`detail: { following: boolean }`)
reports user scroll release or re-engagement; direct `follow` assignments do not echo it.

**Slots:** default (the reasoning/thinking content; entirely free-form)

**CSS parts:** `base`, `header`, `label`, `duration`, `toggle`, `body`

`[part="body"]` is unconditionally `tabindex="0"`: it is a capped-height, independently scrollable
region whose content (plain text, a non-interactive `<lr-streaming-text>`) is often not focusable
itself, so without its own tab stop a keyboard user could never scroll it — the same convention
`<lr-code-block>`'s `[part="body"]` and `<lr-virtual-list>`'s `[part="base"]` follow. It therefore
carries both affordances that go with a real tab stop: an inward `--lr-focus-ring-*` outline while
`:focus-visible` (inward so the region's own `overflow` cannot clip it), and a subtler
`--lr-color-border` outline on pointer hover, so a mouse user also sees that the transcript is a
separately scrollable region.

**Themeable custom properties:** `--lr-thinking-panel-max-block-size` (default
`var(--lr-size-16rem)`, i.e. `16rem` — consumer-overridable cap on how tall `[part="body"]` grows
before it scrolls internally; not
exposed as a component property since it's a pure layout knob, not something a template branches
on), and `--lr-thinking-panel-pending-color` (default `var(--lr-color-brand)`) — the live-mode
pending duration/toggle accent without changing the shared brand token;
`--lr-thinking-panel-compact-header-padding` (default `var(--lr-space-2xs) var(--lr-space-s)`) —
`[part="header"]` padding while `compact`; `--lr-thinking-panel-compact-header-gap` (default
`var(--lr-space-2xs)`) — gap between the toggle, label, and duration while `compact`; and
`--lr-thinking-panel-compact-header-font-size` (default `var(--lr-font-size-sm)`) — font size of
`[part="header"]` while `compact`; and
`--lr-thinking-panel-compact-body-padding` (default `var(--lr-space-s)`) — `[part="body"]`
padding while `compact`. `--lr-thinking-panel-background` (default `var(--lr-color-surface)`),
`--lr-thinking-panel-border-color` (default `var(--lr-color-border)`) and
`--lr-thinking-panel-radius` (default `var(--lr-radius)`) retune `[part="base"]`'s card chrome
without a `::part(base)` override; the border-color hook also colors the header/body divider that
`frame="plain"` keeps. The mouse-hover preview on `[part="body"]` mentioned above has its own
four-longhand outline shape: `--lr-thinking-panel-body-hover-outline-width` (default
`var(--lr-focus-ring-width)`), `--lr-thinking-panel-body-hover-outline-style` (default `solid`),
`--lr-thinking-panel-body-hover-outline-color` (default `var(--lr-color-border)`, set to
`transparent` to opt out entirely), and `--lr-thinking-panel-body-hover-outline-offset` (default
`calc(-1 * var(--lr-focus-ring-offset))`). Unset, all four resolve to the rule's previous literal
paint. Plus shared
`--lr-color-border`/`-surface`/`-text`/`-text-quiet`/`-brand`/`-brand-quiet`,
`--lr-space-xs`/`-s`/`-m`, `--lr-radius`, `--lr-focus-ring-width`/`-color`/`-offset`,
`--lr-transition-fast`/`-base`.

**Optional peer deps:** none.

```html
<lr-thinking-panel label="Reasoning" mode="live" expanded>
  <lr-streaming-text
    content="Considering the user's constraints…"
    streaming
  ></lr-streaming-text>
</lr-thinking-panel>

<lr-thinking-panel label="Reasoning" mode="post-hoc" duration-ms="4200">
  <p>Finished reasoning, collapsed by default.</p>
</lr-thinking-panel>

<div class="message-frame">
  <lr-thinking-panel compact frame="plain" expanded>
    Reasoning nested inside message chrome without a second card frame.
  </lr-thinking-panel>
</div>
```

`mode` drives two concrete behavior differences, not just a styling hook. **Header hint:** while
`duration-ms` is unset, `'live'` shows a pulsing "Thinking…" placeholder in `[part="duration"]`;
`'post-hoc'` shows nothing there. Once `duration-ms` is set, both modes show the same static
"Thought for …" text. **Auto-scroll:** only `'live'` mode auto-follows new content appended to the
default slot while `expanded`; `'post-hoc'` never scrolls on its own.

Live-mode auto-scroll ("stick to bottom") is the classic chat-transcript convention: while
`mode="live"` and `expanded`, new content keeps the panel scrolled to its latest line — unless the
user has manually scrolled up to re-read earlier content (tracked via a `scroll` listener on
`[part="body"]`: every user-driven scroll records whether the body was left within 48px of its own
max scroll position, and only a mutation that arrives while that's still true triggers a follow-up
scroll). Opening an already-`'live'` panel — or a still-`expanded` panel later becoming `'live'` —
always resets this to "anchored" and jumps to the latest content. New content is detected two
ways, both feeding the same coalesced (at most one per animation frame) scroll-to-bottom:

- A `MutationObserver` on this element's own light DOM (`childList`+`subtree`+`characterData`),
  not `slotchange`, since a plain-text producer typically appends chunks to an existing node's
  `textContent` rather than re-slotting a whole new element per token. This cannot see a mutation
  that happens entirely inside a slotted custom element's own shadow root.
- A listener for `lr-content-settled`, a composed, bubbling, signal-only event this library's own
  streaming renderers (`<lr-streaming-text>`, `<lr-markdown>`, `<lr-markdown-core>`) emit at their
  own settle points. Being composed, it crosses exactly the shadow boundary the
  `MutationObserver` cannot, covering every property- or attribute-driven producer that renders
  into its own shadow root instead of mutating visible light-DOM text — which is exactly what the
  example above's `<lr-streaming-text content="…">` does, and why composing it there auto-follows
  correctly.

**Known gotchas:**

- The `MutationObserver` half only watches this element's own light-DOM subtree — it cannot see a
  mutation that happens entirely inside a slotted custom element's own shadow root (e.g. a
  `<lr-markdown>` re-rendering its shadow tree after a `content` change). That gap is exactly what
  the `lr-content-settled` listener covers for this library's own streaming renderers (see above).
  A bespoke slotted element that is neither a plain light-DOM text producer nor one of those three
  needs to append/mutate visible light-DOM text itself, emit its own `lr-content-settled`, or have
  the host call `scrollToBottom()` directly.
- Either half of the pair can trigger the jump-to-bottom/reset-stickiness behavior, as long as the
  _other_ half already holds: an `expanded` transition to `true` while `mode` is already `'live'`,
  **or** a `mode` transition to `'live'` while the panel is already `expanded`, both jump to the
  bottom and reset stickiness. Only a change that leaves the panel in some other combination
  (collapsed, or `mode !== 'live'`) skips it.
- The sticky-bottom flag starts `true` internally, so a panel that mounts already `expanded` and
  `mode="live"` follows its very first content mutation even before any `scroll` event has fired.

---

## `lr-stack-trace`

Parses common V8/JS-TS, Firefox/Safari, and Python stack traces into a leading message plus
activatable frames, splitting chained/caused-by errors (`Caused by:`, `[cause]:`, Python's "direct
cause"/"During handling" separators) into separate groups. Frames matching `internalPatterns` fold
behind a count-labeled toggle. A malformed or non-safe-integer location remains visible as raw,
non-activatable text. Falls back to verbatim raw text when nothing parses. First-party invention
(no Web Awesome equivalent).

Removing the `trace` attribute clears parsed content and copies empty text; the property retains
`null` until assigned again.

**Properties:**

- `trace: string = ''` — the raw stack trace text to parse and render.
- `collapseInternal: boolean = true` (attribute: `collapse-internal`) — folds runs of internal
  frames behind a toggle.
- `internalPatterns: readonly (string | RegExp)[] = DEFAULT_INTERNAL_PATTERNS` (attribute: false) —
  clone-owned, bounded, frozen file-path substrings/`RegExp`s that mark a frame as internal.
  Reassign a new array after changing the matcher sequence.
- `copyable: boolean = true` — shows a copy-to-clipboard button for the raw trace text.
- `maxHeight: string = ''` (attribute: `max-height`) — caps the rendered block size and enables an
  internal scrollbar once content exceeds it (any valid CSS length). Empty string (the default)
  grows with content.
- `frame: LyraFrame = 'card'` (reflected) — container treatment, in the library-wide `frame`
  vocabulary (`'card' | 'plain'`). `'card'` keeps the bordered, filled, padded box. `'plain'` removes
  the border, background, padding and corner radius, so a trace nested inside an
  `lr-result-card`/`lr-agent-run` — which already draws a border — doesn't double the frame. The
  `max-height` scroll cap and the copy/frame affordances are unaffected either way, and `'plain'`
  wins over `compact` when both are set. The exported alias `StackTraceAppearance` is retained as a
  name for the same union.
- `compact: boolean = false` (reflected) — tighter root padding and between-group spacing for dense
  contexts (a trace as a row in an error list, a side panel), the same density convention
  `lr-agent-run`, `lr-commit-card`, `lr-result-card`, `lr-task-list`, `lr-terminal` and
  `lr-thinking-panel` already pair with `frame`. Purely density: the border, corner radius and
  background stay, so reach for `frame="plain"` to drop the chrome. Added in 9.0.0.

**Events:**

- `lr-frame-select` (`detail: { file: string; line: number; column?: number; raw: string }`) — a
  frame with a safe parsed location was activated. `column` is always undefined for Python frames,
  which carry no column information. Malformed or unsafe locations render as raw text and never
  emit this event.
- `lr-copy` (`detail: { ok: true; text: string }`) — the raw, unparsed trace text, fired only after the
  clipboard write resolves successfully.
- `lr-error` (no detail) and `lr-copy-error` (`detail: { ok: false; text: string; reason:
'unsupported'|'denied'|'failed'; error: unknown }`) — compatibility and detailed failure signals. A rejected or
  unavailable clipboard never enters the success state or emits `lr-copy`.

**Slots:** none.

**CSS parts:** `base` (the root wrapper; respects `max-height`, tightens its padding under
`compact`, and drops its card chrome under `frame="plain"`), `message` (the leading error
message text for a group), `group` (one chained-error group of frames), `frame` (a selectable
frame button, carrying `data-internal` for internal frames, or a non-activatable raw row for an
unsafe location), `frame-function` (the frame's function name), `frame-location` (the frame's
`file:line:col` text), `internal-toggle` (the collapse/expand toggle for a run of internal frames),
`limit` (the resource-ceiling status when additional frames are omitted), `raw` (the verbatim fallback when zero structured frames parsed), `copy-button` (only rendered
while `copyable`).

**Themeable custom properties:** `--lr-stack-trace-max-height` (default `none`),
`--lr-stack-trace-font` (default `var(--lr-font-mono)`),
`--lr-stack-trace-internal-frame-color` (default `var(--lr-color-text-quiet)`) — internal-frame
foreground, `--lr-stack-trace-interactive-color` (default `var(--lr-color-brand)`) — frame
hover/focus, internal-toggle, and copy-button-hover accent, plus the two density hooks
`--lr-stack-trace-compact-padding` (default `var(--lr-space-2xs)`, `[part="base"]` padding while
`compact`, overridden entirely by `frame="plain"`) and `--lr-stack-trace-compact-gap` (default
`var(--lr-space-2xs)`, the space below `[part="message"]` and between `[part="group"]`s while
`compact`). The scoped color hooks avoid changing
the shared quiet/brand tokens used by surrounding UI. `--lr-stack-trace-background` (default
`var(--lr-color-surface)`), `--lr-stack-trace-border-color` (default `var(--lr-color-border)`) and
`--lr-stack-trace-radius` (default `var(--lr-radius)`) retune `[part="base"]`'s card chrome without a
`::part(base)` override; `frame="plain"` still removes all three outright. Plus shared tokens
`--lr-color-border`/`-surface`/`-text`/`-text-quiet`/`-brand`, `--lr-radius`,
`--lr-border-width-thin`, `--lr-space-xs`/`-s`/`-2xs`, `--lr-font-size-sm`/`-xs`,
`--lr-font-weight-bold`/`-semibold`, `--lr-focus-ring-*`.

**Optional peer deps:** none.

```html
<lr-stack-trace></lr-stack-trace>
<script type="module">
  const stackTrace = document.querySelector("lr-stack-trace");
  stackTrace.trace = "TypeError: boom\n    at doThing (/app/src/util.js:10:5)";
  stackTrace.addEventListener("lr-frame-select", (e) =>
    console.log(e.detail.file, e.detail.line)
  );
</script>
```

The package root also exports the pure
`parseStackTrace(trace: string, options?: StackTraceParseOptions): StackTraceParseResult` helper
(plus `DEFAULT_INTERNAL_PATTERNS`, `STACK_TRACE_LIMITS`, and the `StackFrame`, `StackGroup`,
`StackTraceParseOptions`, and `StackTraceParseResult` types) — the same parser this component uses,
exposed standalone so a consumer can parse or unit-test traces without instantiating the element.
Pass custom classifiers as `{ internalPatterns: ['node_modules/', /vendor\//] }`. The result is
`{ groups, truncated, source }`, where `source` is the bounded raw-text fallback.

**Known gotchas:**

- an internal-frame run only collapses behind the `internal-toggle` when it is two or more
  consecutive internal frames; a single isolated internal frame renders as a normal `frame` button
  (there is nothing useful to fold).
- when `trace` doesn't match any supported format, `parseStackTrace().groups` is empty and the
  component renders the result's bounded `source` verbatim in a `raw` part instead of silently
  dropping content.
- every coordinate of an activatable frame must be a JavaScript safe integer. A malformed or
  overlarge location remains visible as a non-activatable raw row; if no safe frame is left, the
  component uses the verbatim `raw` fallback.

---

## `lr-tool-approval-dialog`

A human-in-the-loop gate: presents one proposed tool/function call (`toolName` + `args`) and blocks an
agent from executing it until a person explicitly approves or denies it, with an optional inline
"edit the arguments before approving" step. First-party invention (no Web Awesome equivalent). It
keeps its own panel template rather than nesting `<lr-dialog>`, so it has no dependency on the
general-purpose dialog component, while its modal behavior participates in the shared overlay stack.

Approve/Deny/Edit are built-in chrome, not a `footer` slot a consumer must assemble — there is exactly
one correct action set for "approve this call". The `footer` slot is offered only for _supplementary_
content alongside those buttons (e.g. a "remember this choice for this tool" checkbox); its content
renders at the start of the action row, before Deny/Edit/Approve.

**Exported types:**

- `ApprovalAction = 'approve' | 'deny'` — shared imperative vocabulary for an approval operation
  that is proposed or awaiting persistence
- `ApprovalDecision = 'approved' | 'denied'` — shared final-outcome vocabulary, deliberately
  separate from `ApprovalAction`
- `ToolApprovalDialogCloseReason = 'escape' | 'backdrop' | 'approve' | 'deny' | 'api' | string` — the
  `lr-close` detail; `'escape'`/`'approve'`/`'deny'` come from the dialog's built-in triggers,
  `'backdrop'` requires `lightDismiss`, and any other string is whatever a caller passes to
  `close()` directly.

**Properties:**

- `open: boolean = false` (reflected) — set it directly or use the lifecycle methods below
- `lightDismiss: boolean = false` (attribute `light-dismiss`) — opt in to backdrop-click
  dismissal; Escape and the built-in decision buttons remain available without it
- `accessibleLabel: string | null = null` (attribute `aria-label`) — a host attribute names the
  host; the panel remains labelled by its visible heading rather than cloning the same name. A
  direct property assignment made without the attribute can name the panel
- `proposalKey: string = ''` (attribute `proposal-key`) — immutable identity/generation for the
  open proposal. Change it whenever a source reuses the same visible tool name/arguments for a new
  proposal; draft, editing, validation-announcement, and pending-decision state reset immediately
- `toolName: string = ''` (attribute `tool-name`) — the proposed call's name, e.g. `web_search`;
  drives the heading and the dialog's accessible name
- `args: unknown = {}` (attribute: false) — the proposed call's arguments, rendered via
  `<lr-json-viewer>` read-only, or stringified into a `<textarea>` while editing
- `editable: boolean = true` (reflected) — whether an "Edit" affordance is offered at all (assign
  `false` via a PROPERTY binding, e.g. `.editable=${false}` — a `?editable=${false}`
  boolean-attribute binding cannot override a true default). When `false`, `args` is always shown
  read-only and can never be changed before approval.
- `spellcheck: boolean = false`, `autocapitalize: string = 'off'`,
  `autoCorrect: string = 'off'` (attribute `autocorrect`), `autocomplete: string = 'off'`,
  `wrap: 'hard'|'soft'|'off' = 'soft'`, `inputMode: string = ''` (attribute `inputmode`),
  and `enterKeyHint: string = ''` (attribute `enterkeyhint`) — forwarded to the raw-JSON
  `<textarea>` while editing; the defaults keep browser editing assistance from changing JSON text.
  `pending: 'approve' | 'deny' | null = null` (reflected) — which decision is awaiting host
  resolution while an `lr-approve`/`lr-deny` listener has called `preventDefault()` on the
  now-cancelable event; the pending button shows `loading`, the other is `disabled` (Approve is
  also still `disabled` while an in-progress edit is invalid JSON, independent of `pending`).
  Escape and an enabled backdrop dismissal are suppressed while `pending` is set. Finalize by calling
  `close('approve'|'deny')`, or clear `.pending` back to `null` to bounce back to the undecided
  state; `pending` also resets to `null` every time the dialog re-opens. If that same listener
  resolves the decision itself synchronously (calling `close('approve'|'deny')` or setting
  `.pending` directly before returning), that wins outright: the component's own built-in `pending`
  bookkeeping only applies when the listener left both `.pending` and `.open` untouched.

**Methods:** `show(): void` opens the dialog; `hide(reason: ToolApprovalDialogCloseReason = 'api'):
void` and `close(reason = 'api'): void` close through the same reasoned lifecycle, emit `lr-close`,
and return focus to whatever had it before opening; all are no-ops when already in the target state.

**Events:** `lr-approve` (`detail: { args: unknown }` — the current, already-parsed arguments: the
original `args` prop, or the user's edited-and-validated version if an edit was in progress.
Cancelable: a listener calling `preventDefault()` sets `pending` to `'approve'` instead of
closing; otherwise always followed by `lr-close` with reason `'approve'`), `lr-deny` (no detail —
`this.emit('lr-deny')` is called with no second argument, so per the DOM spec's `CustomEventInit`
default, `event.detail` is `null`, not `undefined`. Cancelable, same `pending` mechanism, setting
`pending` to `'deny'`; otherwise always followed by `lr-close` with reason `'deny'`), `lr-close`
(`detail: ToolApprovalDialogCloseReason` — fired exactly once per dismissal, via Escape, an opted-in
backdrop click, the Approve/Deny buttons, or a `close()` call), and no-detail `focus`/`blur` events
re-dispatched when the raw-JSON editor gains or loses focus.

`waitUntil()` is `<lr-confirm-bar>`-only and this dialog does not carry it. The two components share
the `lr-approve`/`lr-deny` event *names*, so the generated `HTMLElementEventMap['lr-approve']` is the
union of both details and only the confirm bar's arm has the field: a listener bound to the shared
name (`document.addEventListener('lr-approve', ...)`) must narrow on `event.target` before reaching
for it, while one bound through `LyraConfirmBarEventMap`/`LyraToolApprovalDialogEventMap` already
sees the right detail. Hold a decision open here with `preventDefault()` + `pending`, then finalize
with `close('approve'|'deny')` or bounce back by clearing `.pending`.

**Slots:** `footer` — optional supplementary content (e.g. a "remember this choice" checkbox),
rendered before the built-in Deny/Edit/Approve buttons.

**CSS parts:** `backdrop`, `panel`, `header`, `tool-name`, `body`, `args-view`, `args-editor`, `error`,
`footer`, `deny-button`, `edit-button`, `approve-button`,
`deny-button-base`, `deny-button-label`, `deny-button-start`, `deny-button-end`,
`deny-button-spinner`, `approve-button-base`, `approve-button-label`, `approve-button-start`,
`approve-button-end`, `approve-button-spinner` (`deny-button`/`approve-button` are each an
`<lr-button>` host; these five per-button parts are re-exported from its own `lr-button` parts via
`exportparts`. Each `*-button-base` route accepts the button's same-node `base` and `button`
wrapper aliases, so either name survives the nested shadow boundary; `edit-button` stays a plain
`<button>`, unaffected by this).

**Themeable custom properties:** `--lr-tool-approval-dialog-overlay-color` (default
`var(--lr-color-overlay)` — the backdrop scrim color, the same shared token `<lr-dialog>` and
`<lr-tool-select-dialog>` read), `--lr-tool-approval-dialog-mono-font` (default
`var(--lr-font-mono)`, the library's shared monospace stack — used by both `tool-name` and the
raw-JSON editor), `--lr-tool-approval-dialog-invalid-border-color` (default
`var(--lr-color-danger)` — border color of the invalid raw-JSON editor, independently retunable
without changing error text or other danger-coloured surfaces), and
`--lr-tool-approval-dialog-hover-border-color` (default `var(--lr-color-brand)` — border color of
the raw-JSON args editor on hover, giving mouse users the same "this is editable" affordance every
other text-entry surface in the library provides), plus shared tokens
`--lr-space-xs/-s/-m/-l`, `--lr-color-surface`, `--lr-color-border`, `--lr-radius`,
`--lr-shadow`, `--lr-color-brand`, `--lr-color-on-brand`, `--lr-color-danger`,
`--lr-color-text`, `--lr-focus-ring-width/-color/-offset`, `--lr-opacity-disabled`.

**Optional peer deps:** none — internally renders `<lr-json-viewer>`, a bundled dependency of this
package, not an optional peer.

```html
<lr-tool-approval-dialog tool-name="send_email"></lr-tool-approval-dialog>
<script type="module">
  const dialog = document.querySelector("lr-tool-approval-dialog");
  dialog.args = { to: "ops@example.com", subject: "Deploy finished" };
  dialog.addEventListener("lr-approve", (e) => runTool(e.detail.args));
  dialog.addEventListener("lr-deny", () => console.log("denied"));
  dialog.addEventListener("lr-close", (e) => console.log("closed:", e.detail));
  dialog.open = true;
</script>
```

While `editable`, an Edit button swaps the read-only `<lr-json-viewer>` for a plain `<textarea>`
pre-filled with `JSON.stringify(args, null, 2)`. Every keystroke re-validates with `JSON.parse` — the
Approve button is `disabled` for as long as the current textarea content fails to parse, so a
malformed edit can never be silently approved as either the broken text or a stale copy of the
original args. The same button relabels to "Cancel" while editing; clicking it discards the draft
entirely and returns to the read-only view of the _original_ `args` — there is no separate "save"
step independent of Approve itself. Both `editing` and any in-progress draft reset back to the
read-only view whenever the dialog opens or `proposalKey`/`toolName`/`args` identifies a replacement
proposal, so a reused instance never leaks one proposal's half-finished edit into the next.

The raw-JSON editor deliberately fixes native `resize` to `vertical`, so a user can make a long
draft taller without changing the dialog's constrained inline size. This focused approval flow has
no generic resize property or auto-grow mode; compose a dedicated editor around the approval UI
when either behavior is required.

The visible JSON error remains ordinary descriptive text. A transition from a valid draft into
invalid JSON is additionally appended once to the shared assertive light-DOM announcement sink;
further invalid keystrokes do not repeat it. An invalid draft already present at initial mount or
reconnect establishes a silent baseline rather than replaying stale context.

Initial focus deliberately does _not_ land on Approve: approving a tool call is a consequential,
potentially irreversible action, so a user who opens the dialog and reflexively presses Enter/Space
before reading anything should deny, not approve. Deny gets the initial focus instead — the same
"focus the safe action" convention a native destructive-confirmation dialog typically follows for its
own Cancel button. Tab/Shift+Tab are bounded to the panel's own focusable content, and
`<lr-json-viewer>`'s internal controls plus slotted custom-element controls are found through the
shared composed-tree focus traversal used by the other modal families.

**Known gotchas:**

- `editable` defaults to `true` and reflects — see the property note above about overriding it with a
  property binding, not a boolean-attribute binding.
- `lr-deny` has no detail payload: its `event.detail` is `null`, not `undefined`.
- a consumer flipping `editable` off while an edit is already in progress automatically exits edit mode
  and discards the draft, so an unreachable "Cancel" affordance is never left stranded on screen.
- reconnecting the element while still `open` (e.g. a drag-and-drop reparent that keeps the same
  instance) resumes its shared overlay registration and re-acquires the ref-counted scroll lock
  dropped in `disconnectedCallback` — `willUpdate()` alone wouldn't otherwise notice, since
  disconnect/reconnect fire back-to-back with no update in between.
- the Approve button's native `disabled` attribute (while the draft is invalid JSON) automatically
  excludes it from the shared Tab trap, whose focusable-set computation skips disabled controls.
- the raw-JSON `args-editor` textarea defaults to `spellcheck="false"`, `autocapitalize="off"`,
  `autocorrect="off"`, and `autocomplete="off"` because its content is JSON, never prose. These
  native editing-assistance values remain configurable through the corresponding properties for
  integrations that intentionally need different browser behavior.
- `deny-button`/`approve-button` are `<lr-button>` hosts (`variant="neutral"`/`"brand"` — the dialog
  itself has no `variant` property, unlike its in-flow sibling `<lr-confirm-bar>`, so the Approve
  button is always `brand` here) — `--lr-button-*` theming reaches them directly. A consumer
  previously styling `::part(deny-button)`/`::part(approve-button)` for
  padding/border/font/`:hover`/`:focus-visible` must move that CSS onto the re-exported
  `deny-button-base`/`approve-button-base` sub-parts instead. `edit-button` is unaffected and stays
  a raw `<button>`.
- Backdrop clicks leave the dialog open by default; add `light-dismiss` to opt in, matching
  `<lr-dialog>`, `<lr-drawer>`, `<lr-lightbox>`, and the sibling tool dialogs.
- An `lr-approve`/`lr-deny` listener can call `preventDefault()` to keep the decision open while
  its own async work is in flight — see `pending` above. While `pending` is set, Escape and an
  enabled backdrop dismissal are suppressed, so a consumer that never resolves the pending decision leaves the
  dialog open until it clears `.pending` or calls `close()` directly itself.

---

## `lr-tool-param-form`

Renders one form control per top-level property of a JSON Schema object, for ad hoc tool invocation or
approval-editing UIs (e.g. "the agent wants to call `create_event(title, attendees, allDay)` — let the
user tweak the arguments before running it"). First-party invention (no Web Awesome equivalent).
With no host name, the `base` part is the accessible `role="group"`; a native external `<label for>`
can name the form-associated host. A non-empty host `aria-label` remains on the host as the sole
aggregate semantic owner, so `base` omits its duplicate role/name. The individual generated fields
keep their own purpose-specific names in every case.

Choosing Boolean Unset keeps an explicit `undefined` value when a schema default exists; deleting
that key or replacing the value with an absent key restores default materialization. Without a
schema default, Unset removes the key.

**Supported schema subset:** a _flat_ object whose properties use one primitive `type`
(`'string'`, `'number'`, `'integer'`, or `'boolean'`), `required` property presence, string `enum`,
primitive `const`, and the `title`/`description`/`default` annotations. Nested objects, arrays, type
unions, `oneOf`/`anyOf`/`allOf`, `$ref`, string/numeric constraints, and schema-valued
`additionalProperties` are not interpreted. An unsupported property type renders a visible fallback
and makes the form invalid instead of being silently accepted. Schemas are bounded to 100 fields
and 500 enum choices per field; exceeding either ceiling leaves only the bounded prefix mounted and
fails the form closed with a localized form-wide error. A null, array, or other malformed property
definition is a schema-shape error, never misreported as a value-serialization failure.

**Exported types:**

- `ToolParamFormPropertyType = 'string' | 'number' | 'integer' | 'boolean'` — the four leaf property
  types this renderer understands
- `ToolParamFormPrimitive = string | number | boolean` — values accepted by the supported `const`
- `ToolParamFormProperty { readonly type: ToolParamFormPropertyType; readonly enum?: readonly
string[]; readonly description?: string; readonly title?: string; readonly default?: unknown;
readonly const?: ToolParamFormPrimitive; readonly autocomplete?: string; readonly spellcheck?:
boolean; readonly autocapitalize?: string; readonly autoCorrect?: string; readonly inputMode?:
string; readonly enterKeyHint?: string }` — one `schema.properties`
  entry. `enum` is only meaningful when `type` is `'string'` (rendered as a `<lr-select>`); `const`
  enforces one exact primitive value; `title` is the display label; `description` is helper text;
  `default` pre-fills a field whenever `value` doesn't already have that key. For a free-form
  string field, `autocomplete`, `spellcheck`, `autocapitalize`, `autoCorrect`, `inputMode`, and
  `enterKeyHint` forward the corresponding native editing hints to the rendered text input;
  `spellcheck` defaults to `true`, and the other hints are omitted unless supplied.
- `FlatToolParamSchema { readonly type: 'object'; readonly properties:
Readonly<Record<string, ToolParamFormProperty>>; readonly required?: readonly string[] }` — the
  (intentionally flat) schema shape this component can render.
- `ToolParamFormValue = Readonly<Record<string, unknown>>` — the clone-owned argument model.

**Properties:**

- `schema: FlatToolParamSchema = { type: 'object', properties: {} }` (attribute: false) — a
  detached, deeply frozen assignment snapshot, capped at 100 fields and required keys and 500 enum
  choices per field. Exceeding a cap keeps the bounded prefix but fails validation closed. Create
  and reassign a new schema after changes; mutating the caller's prior object has no effect.
- `value: ToolParamFormValue = {}` (attribute: false) — a detached, deeply frozen assignment
  snapshot, capped at 10,000 entries per array/plain record, 50,000 total nodes, and 16 nested
  levels. Unsafe or oversized assignments fail serialization closed. Create and reassign a new
  value after changes; mutating the caller's prior object has no effect. It represents exactly
  what the consumer last assigned.
  A field with no entry in `value` but a schema `default` _displays_ (and is _emitted_, via
  `lr-input`) as that default, but the `value` property itself is left alone until the user actually
  edits that field. JSON Schema ordinarily treats `default` as an annotation; this renderer
  deliberately materializes it before validation/submission, so a valid default can satisfy
  `required`.
- `name: string = ''` — submission key for optional native `<form>` participation
- `disabled: boolean = false` (reflected)
- `customError: string | null = null` (attribute `custom-error`) — reflected consumer validation
  message
- `form: HTMLFormElement | null = null` — browser-resolved owner (and an assignable external owner);
  readonly `labels: NodeList`, `validity: ValidityState`, `validationMessage: string`,
  `willValidate: boolean`, and `effectiveDisabled: boolean` expose the native FACE state

**Getters:**

- `effectiveValue: ToolParamFormValue` — a detached, deeply frozen `value` snapshot with every
  property missing from it filled in
  from `schema`'s own `default`; this is what actually renders and what `lr-input`'s detail carries.
  A key the user has explicitly cleared (a real own property set to `undefined`) stays cleared rather
  than snapping back to its default — only a key genuinely absent from `value` falls back.
- `errors: Readonly<Record<string, string>>` — a frozen effective validation-error snapshot.
  Intrinsic errors use their schema property key; a schema-wide/serialization error or consumer
  custom-validity message uses `base`, the whole-control part. It is independent of which fields
  have been visited.
- `formError: string` — a schema-wide/JSON-serialization error that has no honest field key; empty
  when the current effective value is safe to submit.

**Methods:**

- `getForm(): HTMLFormElement | null` — returns the browser-resolved owning form.
- `checkValidity(): boolean` — synchronously updates `ElementInternals` from the current assigned
  snapshots and returns validity without revealing inline errors.
- `reportValidity(): boolean` — performs the same synchronization, reveals all current field/root
  errors, focuses the first invalid generated field when one exists, and delegates to native
  `ElementInternals.reportValidity()`. If `required` contains an unmet key absent from
  `properties`, there is no generated control to focus, so a localized, programmatically focusable
  root error names that dangling key instead.
- `setCustomValidity(message: string): void` — the standard channel for a rejection the schema
  cannot express ("the tool rejected these arguments"). A non-empty `message` raises `customError`
  and becomes `validationMessage`, so the form fails `checkValidity()`, blocks submission, and
  matches `:state(invalid)`; `''` clears it. Two independent layers: this control already raises
  `customError` intrinsically for a malformed schema or an unsupported field type, and
  `setCustomValidity('')` clears only the consumer's layer — a still-malformed schema stays invalid
  with its own message restored, and clearing never forces a form with an unmet `required` property
  valid. The consumer's error survives every intrinsic recomputation in between (each field edit
  re-runs the validity sync) and a `form.reset()`, matching a native control. The message is
  whole-control state exposed as `errors.base`; it is caller-supplied content and is used verbatim,
  never localized.
- `click(): void` — forwards a host click to the first generated field's control, so the form
  behaves like a single control under both a `<label>`-driven and a programmatic click; a no-op
  while `disabled`.

**Events:** `lr-input` (deeply frozen `detail: { value: ToolParamFormValue }` — the full detached
current value snapshot, every property with defaults resolved, not just the field that changed),
`lr-validity-change` (deeply frozen
`detail: { valid: boolean; errors: Readonly<Record<string, string>> }` — deduplicated on
effective native validity, including consumer custom errors and own/fieldset validation barring;
fired once up front at connect time and after every effective change; serialization-only failures
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.
`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.

**Slots:** none.

**The required marker.** A field whose key is listed in `schema.required` marks its `[part="label"]`
with the library's shared required marker — the same `::after` rule and the same three properties
every labelled control in the library uses (`--lr-form-control-required-content`,
`--lr-form-control-required-color` and `--lr-form-control-required-offset`), so retuning or
suppressing the marker application-wide reaches this form's fields
too (see `llms/shared.md` → "The required-field marker"). Requiredness here is **per field**, not per host:
the host carries no `required` attribute, so the marker keys off a `data-required` attribute the
component sets on each `[part="field"]` wrapper. That attribute is component-owned bookkeeping —
never write it, and note that `::part(field)[data-required]` is invalid CSS (an attribute selector
cannot follow `::part()`), so it is not a selector hook you can use from outside. Enum and boolean
fields render as `<lr-select>` controls with their own labels. The outer schema validator owns
presence, so the nested control stays `.required=false` while its host receives
`aria-required="true"` for a required property.

**CSS parts:** `base` (the aggregate `role="group"`), `field`, `label`, `control`, `description`,
`error`, `unsupported`, `empty`.
`control` is the native `<input>` for a `'string'` (non-enum) or `'number'`/`'integer'` field — one
shared part name across both the text and number inputs, and deliberately _not_ present on the
`'boolean'`/enum (`<lr-select>`), or unsupported-type fallback branches, which are
composed components with their own part surfaces rather than raw natives. It is purely an additive
external theming hook: the internal `.control` class the stylesheet targets is unchanged.

**Themeable custom properties:** `--lr-tool-param-form-invalid-border-color` (default
`var(--lr-color-danger)`) — border color of an invalid generated native text or number input.
This component-scoped indirection retints invalid borders without changing error text, required
markers, or other danger-coloured surfaces. Shared tokens remain available for the rest of the
form: `--lr-space-l/-xs/-s`, `--lr-color-border`, `--lr-radius`, `--lr-color-surface`,
`--lr-color-danger`, `--lr-color-text-quiet`, `--lr-focus-ring-width/-color/-offset`,
`--lr-opacity-disabled`.

**Optional peer deps:** none — internally renders `<lr-select>` and `<lr-option>`, both bundled
dependencies of this package imported directly, not optional peers.

```html
<lr-tool-param-form></lr-tool-param-form>
<script type="module">
  const form = document.querySelector("lr-tool-param-form");
  form.schema = {
    type: "object",
    properties: {
      title: { type: "string", title: "Title" },
      attendees: { type: "string", enum: ["team", "everyone"], default: "team" },
      allDay: { type: "boolean", title: "All day" },
    },
    required: ["title"],
  };
  form.value = draftArgs;
  form.addEventListener("lr-input", (e) => (draftArgs = e.detail.value));
  form.addEventListener("lr-validity-change", (e) => (formIsValid = e.detail.valid));
</script>
```

This component owns no Submit/Cancel/Approve chrome — a consumer composes it inside their own dialog
(e.g. `<lr-tool-approval-dialog>`) and reads `.value`/`.errors`/`checkValidity()` (or calls
`reportValidity()` right before acting). Fields render in `Object.keys(schema.properties)` order
(insertion order). A `'string'` property with a non-empty `enum` renders as a `<lr-select>` of
`<lr-option>`s; a plain `'string'` renders a text `<input>`; `'number'`/`'integer'` render a numeric
`<input type="number">` (`step="1"` for integer, `step="any"` for number); `'boolean'` renders a
tri-state `<lr-select>` with localized Unset/True/False choices. This preserves the semantic
difference between an absent optional property and an explicit `false`. Enum and boolean
descriptions/errors flow through `<lr-select>`'s `.hint`/`.errorText` control chrome. The outer
component owns JSON Schema validity: `required` means an own property is present, so `''`, `0`, and
`false` are valid present values. Use `{ type: 'boolean', const: true }` together with `required`
for a must-confirm field; the select still does not impose its own nonempty semantics, while the
outer validator enforces both presence and the exact `true` value.

Visible field and root validation errors remain ordinary descriptive text. When user interaction or
`reportValidity()` makes one or more new errors visible, their distinct messages are coalesced into
one addition to the shared assertive light-DOM announcement sink. Initial and reconnect renders
establish a silent baseline, so pre-existing validation state is not replayed.

Optional native `<form>` participation is implemented via `ElementInternals` attached directly in the
constructor (`static formAssociated = true`) rather than a string-value mixin, since this component's
value is a whole object: the value present on first connection is cloned as the native default, and
`formResetCallback()` restores a fresh clone of that default while clearing touched/interaction state.
Consumer-set custom validity remains in force until explicitly cleared, matching native controls. The
`formDisabledCallback(disabled)` tracks inherited fieldset state separately from the author-owned
`disabled` property. JSON serialization is guarded: circular values, `BigInt`, throwing getters/`toJSON`, and
non-finite numbers cannot escape from an assignment or leave stale form data; the form entry is
temporarily removed and `formError`/custom validity are set until a serializable value replaces it.
This is layered on top of the primary `value` + `lr-input`/`lr-validity-change` contract.
The same safe serialized object is used as session-history/autofill state. Restoration accepts only
a JSON object, falls back to `{}` for malformed/non-object state, and does not emit `lr-input`.

**Known gotchas:**

- a schema property whose `type` isn't `'string'`/`'number'`/`'integer'`/`'boolean'` renders an inline
  "Unsupported field type" message exposed as `[part="unsupported"]` and fails closed with custom
  validity instead of throwing or being silently dropped.
- inline per-field errors only render once a field has been visited (`focusout`) at least once, or
  after an explicit `reportValidity()` call — `checkValidity()` alone never reveals them, matching
  every other form control in this library (`<lr-select>`/`<lr-combobox>`/`<lr-model-select>`
  all avoid flashing red before the user has touched anything).
- a key listed in `schema.required` but absent from `schema.properties` still fails closed. Because
  no field exists for that dangling reference, `reportValidity()` renders and focuses a localized
  root error naming the key rather than leaving an invisible, unreachable validity failure.
- `effectiveValue` distinguishes "key absent from `value`" (falls back to `default`) from "key present
  but `undefined`" (stays cleared and counts as absent for `required`) via `hasOwnProperty`, not an
  `=== undefined` fallback check.
- additional value keys are retained and submitted (matching JSON Schema's default open-object
  behavior), but schema-valued/false `additionalProperties` is outside this renderer's subset.
- `value` and `schema` are detached, deeply frozen assignment-time snapshots. Reassign either
  property after changing caller-owned input; direct in-place mutation cannot alter the component,
  and neither its own `checkValidity()`/`reportValidity()` nor native form validation resnapshots the
  original object.
- `lr-validity-change` fires once immediately at connect time even before any user interaction, so a
  form with an unmet required field announces `valid: false` on mount, not only after the first edit.

---

## `lr-result-card` / `lr-result-field`

A small, tightly-coupled pair giving any custom `lr-tool-result-view` renderer (registered via
`registerToolRenderer()` in `../tool-result-view/registry.js`) a consistent "small bordered card +
label/value row" visual language, without each one hand-rolling its own box. Neither component has
any code dependency on the tool-result-view registry itself — they're generically usable anywhere a
small card/field shell is useful.

Removing `heading` or a result field `label` hides that text while preserving the card actions and
field value.

### `lr-result-card`

A small bordered card shell. Purely visual, with no state of its own beyond slot-presence tracking.

**Properties:**

- `heading: string = ''` — small heading for the card. Leave unset for an untitled card (e.g. a bare
  block of `lr-result-field` rows with no natural heading).
- `compact: boolean = false` (reflected) — tighter header/body padding for dense contexts (a card
  rendered as a row in a transcript or result list), same convention as `<lr-agent-run>`'s own
  `compact`. Purely a density knob: the border and background stay, so use `frame="plain"`
  instead to drop the chrome entirely. When both are set, plain leaves compact padding and gaps
  intact.
- `frame: LyraFrame = 'card'` (reflected) — container treatment, in the library-wide `frame`
  vocabulary (`'card' | 'plain'`), the same property `<lr-agent-run>`/`<lr-card>` carry. `'card'`
  (the default) keeps the bordered, filled box. `'plain'` removes the border, background, and corner
  radius, so a card nested inside a host frame that already draws a border (e.g.
  `<lr-tool-result-view>`'s own chrome) doesn't double it. Plain controls only the chrome; compact
  padding and gaps still apply when both are set. The exported alias `ResultCardAppearance` is
  retained as a name for the same union.
- `withActions: boolean = false` (attribute `with-actions`, reflected) — explicit first-render
  presence hint for the `actions` slot. Client-only markup normally does not need it because the
  component detects assigned actions during upgrade; set it before both server and browser first
  render when an actions-only header must be present in the no-JavaScript response and reused by
  hydration.

**Events:** none.

**Slots:** default (the card body — typically one or more `lr-result-field` rows, though any
content is accepted), `actions` (small header controls, e.g. a copy button, rendered alongside the
heading).

**CSS parts:** `base` (outer bordered container), `header` (present in the DOM at all times so a
later `slotchange` on `actions` is still observed, but `hidden` whenever there's no `heading` and no
`actions` content), `heading` (truncates with an ellipsis when it overflows; carries its own native
`title` attribute — the full string — so hovering the truncated text reveals it via the browser's
default tooltip, scoped to just this element rather than the whole card), `actions` (`hidden`
whenever the slot has no assigned content), `body`.

**Themeable custom properties:** `--lr-result-card-compact-header-padding` (default
`var(--lr-space-xs)`) — `[part="header"]` block/inline padding while `compact`;
`--lr-result-card-compact-header-gap` (default `var(--lr-space-xs)`) — gap between
`[part="header"]`'s heading and actions while `compact`, one step tighter than the uncompacted
`--lr-space-s`; `--lr-result-card-compact-body-padding` (default `var(--lr-space-xs)`) —
`[part="body"]` padding while `compact`; `--lr-result-card-compact-body-gap` (default
`var(--lr-space-2xs)`) — gap between `[part="body"]`'s children while `compact`, one step tighter
than the uncompacted `--lr-space-xs`. The two gap knobs mean `compact` now tightens interior spacing,
not only the padding box — a compact card no longer keeps full-size gaps inside a shrunken frame.
`--lr-result-card-background` (default `var(--lr-color-surface)`), `--lr-result-card-border-color`
(default `var(--lr-color-border)`) and `--lr-result-card-radius` (default `var(--lr-radius)`) retune
the card chrome without a `::part(base)` override. The border-color hook also colors
`[part="header"]`'s divider, so a retuned card doesn't strand a mismatched interior rule;
`frame="plain"` still drops the outer chrome and that divider.
Plus shared tokens — `--lr-space-2xs`/`-xs`/`-s`, `--lr-color-border`/`-surface`/`-text`,
`--lr-radius`.

### `lr-result-field`

A single label/value row — e.g. "Status: 200 OK" or "Duration: 340ms" — rendered as a dense
"label: value" line by default, matching the compact, small-card presentation this pair exists for.

**Properties:**

- `label: string = ''` — the field name, e.g. "Status". Leave unset to render a value with no label.
- `value: string = ''` — plain-text value, e.g. "200 OK". Ignored once the default slot carries real
  content.

**Events:** none.

**Slots:** default — rich value content (e.g. a `lr-chip` status badge, or a plain text override),
taking precedence over `value` whenever it has any assigned content. "Real content" means any
assigned _element_ (even one with no text of its own, like an attribute-driven status badge) or any
non-whitespace text node — both a rich slotted badge and a plain-text override are caught.

**CSS parts:** `base` (row container), `label` (including its trailing colon), `value` (wrapper
around either the slotted content or the plain `value` text).

**Themeable custom properties:** shared tokens only — `--lr-space-xs`, `--lr-color-text`/
`-text-quiet`, `--lr-font`.

**Optional peer deps:** none (either component).

```html
<lr-result-card heading="Weather">
  <lr-result-field label="Status" value="200 OK"></lr-result-field>
  <lr-result-field label="Duration" value="340ms"></lr-result-field>
  <lr-result-field label="Provider">
    <lr-chip variant="success">OpenWeather</lr-chip>
  </lr-result-field>
</lr-result-card>
```

**Known gotchas:**

- `HTMLElement.textContent` read on a shadow-DOM wrapper containing a `<slot>` does NOT include the
  slot's assigned/projected light-DOM content — only literal fallback children of the `<slot>` tag
  itself (there are none here). Reading `[part="value"]`'s own `.textContent` yields an empty value
  even when slotted content is rendering correctly; use the slot's
  `assignedNodes()`/`assignedElements()` instead.

---

## `lr-compare-panel`

Side-by-side A/B output comparison with a winner vote (LMSYS-arena / LangSmith-pairwise style): two
slotted panes, a vote bar, synchronized reading.

Disabled vote buttons retain their resting colors during hover and press, including an existing
selected vote.

At narrow widths, stacked response panes size to their content up to
`--lr-compare-panel-max-height`. Short responses remain fully readable; longer responses retain the
configured height limit and scrolling.

**Properties:** `labelA: string = ''` (attribute `label-a`) and `labelB: string = ''` (attribute
`label-b`) — pane headings. `vote: 'a' | 'b' | 'tie' | 'both-bad' | null = null` (reflected) — the
recorded winner, host-writable to reflect a previously-recorded vote back. `itemId: string = ''`
(attribute `item-id`) — an opaque id round-tripped through `lr-vote`. Changing only `itemId` clears
the prior vote; assigning both `itemId` and a controlled `vote` in one update preserves the explicit
vote regardless of property assignment order. `allowedVotes: readonly CompareVote[] = ['a', 'b',
'tie', 'both-bad']` (attribute: false) is the positive list of choices to render, always projected
in that canonical order; repeated/foreign values do not create controls. The list is clone-owned,
bounded, and frozen; reassign a new array after changing the allowed choices. `syncScroll: boolean =
false` (attribute `sync-scroll`) links both panes'
scroll position. `disabled: boolean = false` (reflected) disables every vote button and suppresses
`lr-vote`.

**Slots:** `a` (the first output — any content, a chat message, markdown, a viewer), `b` (the second
output), and `prompt` (optional shared-input header above both panes).

**Events:** `lr-vote` — `detail: { choice: 'a' | 'b' | 'tie' | 'both-bad'; itemId: string }`.
This is a cancelable veto point emitted before `vote` changes; call `preventDefault()` to preserve
the prior vote.

**CSS parts:** `base` (the outer wrapper), `prompt` (the optional prompt header, hidden when the
`prompt` slot is empty), `panes` (the row, or under 640px column, wrapping both panes), `pane-a`,
`pane-b` (each pane's labeled scroll region), `pane-header` (a pane's visible heading), `vote-bar`
(the `role="group"` row of vote buttons), `vote-button` (one vote button), and `live-region` (the
internal vote-announcement live region).

**Themeable custom properties:** `--lr-compare-panel-max-height` (default `var(--lr-size-24rem)`) —
cap on each pane's scroll region before it scrolls internally;
`--lr-compare-panel-selected-background` (default `var(--lr-color-brand-quiet)`),
`--lr-compare-panel-selected-border-color` (default `var(--lr-color-brand)`), and
`--lr-compare-panel-selected-color` (default `var(--lr-color-brand)`), and
`--lr-compare-panel-selected-font-weight` (default `var(--lr-font-weight-semibold)`) style the
selected vote button without changing shared brand tokens.

## `lr-span-waterfall`

The horizontal-timeline projection of the same `LyraSpan[]` `<lr-trace-tree>` consumes: a time
axis, one row per span in start order, status-toned bars (Langfuse timeline / Temporal
event-history style).

Span views omit whitespace-only IDs and preserve every nonblank business ID exactly, including
surrounding whitespace. The first valid admitted duplicate continues to win.

**Properties:** `spans: LyraSpan[] = []` (attribute: false) — `LyraSpan { id: string; parentId?:
string; name: string; kind: 'agent' | 'llm' | 'tool' | 'retriever' | 'embedding' | 'other';
startMs: number; endMs?: number; status: 'pending' | 'running' | 'success' | 'error' | 'denied';
tokensIn?: number; tokensOut?: number; costText?: string; detail?: string }`, exported from
`trace-tree/span.ts`. `startMs`/`endMs` are milliseconds **relative to the trace start**, not
wall-clock timestamps; `endMs` is absent while the span is still running. `costText` is preformatted
by the host (e.g. `"$0.0012"`) and rendered verbatim, never parsed or summed. One flat array powers
both this component (timeline projection via `startMs`/`endMs`) and `lr-trace-tree` (hierarchy
projection via `parentId`) — never two shapes. Foreign runtime `kind` and `status` values render
as `'other'` and `'pending'` rather than throwing, although hosts should continue to use the
documented literal sets. At most 500 unique valid spans mount; when `activeSpanId` resolves beyond
the ordinary input-order budget, that span and its ancestor path reserve positions so the
controlled active state remains visible. A localized `[part="limit"]` note exposes truncation. The
time axis always scales to the whole trace, measured before that 500-span cap is applied, so a
truncated tail can never shrink the axis and stretch the surviving bars across the track.
`activeSpanId: string | null = null`
(attribute `active-span-id`), `viewStartMs: number | null = null` (attribute `view-start-ms`) and
`viewEndMs: number | null = null` (attribute `view-end-ms`) — override the auto-computed time
window, `hideAxis: boolean = false` (attribute `hide-axis`), and `label: string = ''`.

The granular `@aceshooting/lyra-ui/components/agent-tools/trace-tree/trace-tree.js` entry also
type-exports `LyraSpanKind` and `LyraSpanStatus`, and exports
`normalizeLyraSpanKind(value)` / `normalizeLyraSpanStatus(value)` for normalizing provider data
before assigning `spans`. These helpers are intentionally granular-only rather than root-barrel
exports.

**Events:** `lr-span-select` — `detail: { spanId: string }`, a bar/row was activated (click, Enter,
Space).

**CSS parts:** `base`, `axis` (the time-ruler row, hidden when `hideAxis`), `tick`, `tick-label`,
`row`, `name` (the row's name gutter), `bar-track`, `bar` (the interactive, focusable status-toned
bar), `meta` (secondary row info, shown inline under 480px), `status-text`, `duration`, `empty` (shown
when `spans` is empty), `limit` (the 500-span projection notice), and `live-region`.
The interactive `bar` keeps a 24px minimum target in both axes even when its duration-derived
paint width would otherwise be only a few pixels.

The terminal axis tick is end-aligned so its label remains inside the allocated chart width. Roving
keyboard focus is computed from the currently rendered/filtered span ids, so a hidden active span
cannot leave the component with no `tabindex="0"` stop.

**Themeable custom properties:** `--lr-span-waterfall-name-width` (default `8rem`),
`--lr-span-waterfall-stripe-speed` (a `running` span's striped-bar animation duration; defaults to
`--lr-duration-ambient` — the bare-duration token, not the `--lr-transition-ambient`
duration+easing shorthand, which is invalid in an `animation-duration` slot), and
`--lr-span-waterfall-row-active-bg` (default
`var(--lr-color-brand-quiet)`) — the background of the active (`activeSpanId`) row.
Status-scoped bar hooks are `--lr-span-waterfall-success-color` (default
`var(--lr-color-success)`), `--lr-span-waterfall-error-color` (default
`var(--lr-color-danger)`), `--lr-span-waterfall-denied-color` (default
`var(--lr-color-warning)`), `--lr-span-waterfall-running-color` (default
`var(--lr-color-brand)`) for the running stripe foreground,
`--lr-span-waterfall-running-stripe-color` (default `var(--lr-color-brand-quiet)`) for its
contrasting background, and `--lr-span-waterfall-pending-border-color` (default
`var(--lr-color-border-strong)`) for pending bars.

That last one follows the convention every **state-scoped** custom property in this family uses, and
it is worth reading once: it is an inline `var()` fallback at its point of use and is deliberately
**not** declared on `:host`, so it can be set on the element _or on any ancestor_ and still reach the
rule that consumes it. It exists because Shadow Parts forbids an attribute selector after `::part()`
— `::part(row)[data-active]` and every selector like it is invalid CSS — so before it, the only way
to restyle a state-dependent surface was to override a library-wide `--lr-color-*` token, which repaints
every other surface reading that token. Every `*-active-*`, `*-selected-*` and per-state color
property below works the same way.

## `lr-task-list`

A live, collapsible tracker for an agent's plan: ordered steps with per-step lifecycle status and one
level of nested sub-steps, embedded in the transcript. `items` is controlled and never mutated by this
component. Unlike `<lr-stepper>`'s single-`current` navigation, task-list has no selection and
several steps may be `running` at once. By default it is a status report; `reorderable` adds
controlled keyboard reorder requests without changing ownership of `items`. Status changes and
confirmed moves are announced through an internal `<lr-live-region>`.

**Properties:** `items: readonly TaskItem[] = []` (attribute: false) — `TaskItem { id: string; label: string;
status: TaskStatus; detail?: string; children?: readonly TaskItem[] }` with `TaskStatus = 'pending' |
'running' | 'success' | 'error'` (both exported here). `detail` is an optional secondary plain-text
line; `children` is exactly **one** level of sub-steps — a child's own `children` is ignored with a
`console.warn`. Runtime non-record rows and rows without a nonempty string `id` are omitted before
rendering, summaries, announcements, and reorder validation. While `reorderable`, every retained
top-level task and direct child must additionally have a globally unique `id`; duplicate data stays
visible but fails closed, with no row keyboard stops or reorder requests.
`reorderable: boolean = false` (reflected) enables Ctrl/Cmd+ArrowUp/ArrowDown on a focused task.
It emits a request only; the host must assign a new reordered `items` array before the task visibly
moves or an announcement is made. `label?: string` omits into localized `taskListLabel` (`'Tasks'`
in the built-in English catalog); any supplied value is an explicit verbatim override, including
`'Tasks'` under a non-English `.strings` catalog and `''`. `headingLevel: LyraHeadingLevel = '3'`
(attribute `heading-level`, reflected) — `1`–`6` expose the visible header as that semantic heading
level around either its disclosure button or static content, invalid untyped values retain level 3,
and `none` is the explicit visual-only opt-out — `expanded: boolean = true` (reflected), and
`collapsible: boolean = true`. `compact: boolean = false` (reflected) — tighter header/body padding
and item gap for dense contexts (a plan tracker nested in an already-padded transcript row), same
convention as `<lr-agent-run>`'s/`<lr-source-card>`'s `compact`; purely a density knob, the border
and background stay. `frame: LyraFrame = 'card'` (reflected) — container treatment, in the
library-wide `frame` vocabulary (`'card' | 'plain'`); `'plain'` removes `[part="base"]`'s border,
background, and corner radius so a list embedded in a container that already draws a border (an
agent-run panel, a message bubble) doesn't double it. The exported alias `TaskListAppearance` is
retained as a name for the same union.

**Slots:** `detail-<id>` — dynamic, one per item id (e.g. `slot="detail-step-3"`); rich detail under
that item's label, typically a `<lr-tool-call-chip>` or file `<lr-chip>`.

**Events:** `lr-toggle` — the header was activated, expanding or collapsing the panel. `detail: {
expanded }`. `lr-reorder` — Ctrl/Cmd+ArrowUp/ArrowDown requests moving the focused task within its
own sibling list. `detail: { taskId, parentTaskId, fromIndex, toIndex }`; `parentTaskId` is `null`
for a top-level task and indices are sibling-scoped. It fires only while `reorderable` with unique,
nonempty ids.
A boundary key is a silent no-op, so it never reparents a child; the component announces success only
after the host's rendered array confirms the exact requested swap.

**CSS parts:** `base`, `header` (a `<button>` when `collapsible`, plain content otherwise, within
the configured semantic heading), `label`,
`summary` (the visible "N of M completed" summary, top-level items only), `toggle` (the chevron
indicator, only rendered when `collapsible`), `body` (the list of items, `hidden` while collapsed),
`item` (`role="listitem"`; carries `data-status`/`data-id`/`data-depth` and is focusable only for
valid `reorderable` data), `status-icon`, `item-label`, `item-detail`, and `item-children` (the
nested `role="list"` wrapper around a top-level item's children).

**Themeable custom properties:** `--lr-task-list-spin` (default `var(--lr-transition-ambient)`, i.e.
`1.8s ease-in-out`, collapsing to `0.001ms linear` under `prefers-reduced-motion`) — running-status
icon spin animation duration/timing; `--lr-task-list-compact-header-padding` (default
`var(--lr-space-2xs) var(--lr-space-s)`) — `[part="header"]` padding while `compact`;
`--lr-task-list-compact-header-gap` (default `var(--lr-space-2xs)`) — gap between `[part="header"]`'s
label/summary/toggle while `compact`, one step tighter than the header's uncompacted
`--lr-space-xs`, so `compact` tightens the header's _interior_ spacing and not just its padding;
`--lr-task-list-compact-header-font-size` (default `var(--lr-font-size-sm)`) — `[part="header"]`
font size while `compact`, completing the compact header's typography alongside its padding and
gap;
`--lr-task-list-compact-gap` (default `var(--lr-space-2xs)`) — gap between `[part="body"]`'s item
rows while `compact`; `--lr-task-list-compact-body-padding` (default `var(--lr-space-2xs)
var(--lr-space-s) var(--lr-space-s)`) — `[part="body"]` padding while `compact`;
`--lr-task-list-pending-color` (default `var(--lr-color-text-quiet)`),
`--lr-task-list-running-color` (default `var(--lr-color-brand)`),
`--lr-task-list-success-color` (default `var(--lr-color-success)`), and
`--lr-task-list-error-color` (default `var(--lr-color-danger)`) independently retint the matching
status icons without changing shared status tokens. `--lr-task-list-background` (default
`var(--lr-color-surface)`), `--lr-task-list-border-color` (default `var(--lr-color-border)`) and
`--lr-task-list-radius` (default `var(--lr-radius)`) retune `[part="base"]`'s card chrome without a
`::part(base)` override; the border-color hook also colors the header/body divider that
`frame="plain"` keeps.

## `lr-terminal`

A read-only ANSI console for streamed agent/tool output. Not a PTY: no stdin/keystroke handling, no
cursor-addressed full-screen apps. An ANSI sequence split across chunks retains at most 4,096
characters; an overlong unterminated CSI/OSC sequence is dropped and the next write resumes from a
clean parser boundary.

A search with no matches clears earlier rendered match markers. Removing the `content` attribute
clears output and preserves the normal `null` property readback.

**Properties:** `content: string = ''` — initial/replaceable buffer content, parsed for ANSI/SGR
codes. `replace(content: string): void` synchronously replaces the parsed buffer and reactive
`content` source, preserving commit order with same-turn `write()`/`clear()` calls.
`maxScrollback: number = 5000` (attribute `max-scrollback`), `follow: boolean = true`
(reflected) — stick-to-bottom, `wrap: boolean = true` (reflected), `copyable: boolean = true`
(reflected) and `downloadable: boolean = false` (reflected) toggle the toolbar buttons, `filename:
string = 'terminal.log'`, `announceOutput: boolean = false` (attribute `announce-output`),
`accessibleLabel: string = ''` (attribute `aria-label`), `highlights: readonly LyraHighlight[] = []` (attribute:
false), and `activeHighlightId: string | null = null` (attribute: false). Empty/blank highlight ids
and later duplicates are omitted before painting, focus ownership, active lookup, and activation
events. A non-empty host `aria-label` is forwarded to the nested `role="log"`; an absent or explicit
empty value uses the localized terminal-purpose fallback, so the actionable log remains named.
`compact: boolean = false` (reflected) — tightens `[part="toolbar"]`'s padding and gap and each
rendered line's inline padding for a terminal embedded in an already-padded transcript row, the same
convention `<lr-task-list>` and `<lr-thinking-panel>` use; purely a density knob, the card border and
background stay. `frame: LyraFrame = 'card'` (reflected) — container treatment in the library-wide
`frame` vocabulary (`'card' | 'plain'`); `'plain'` removes `[part="base"]`'s border, corner radius,
and raised surface so a terminal nested inside a container that already draws a border (an agent-run
panel, a message bubble) doesn't double it, while keeping the toolbar/log divider and whichever
regular or compact padding applies. `anchorKinds:
LyraAnchor['kind'][] = ['line-range']` is readonly — a scrollback buffer addresses positions by line number, so `line-range` is the
only kind `scrollToAnchor()` resolves; `page`/`text-quote`/`region` belong to the paginated document
viewers, not here. `<lr-terminal>` is not registered in the document-renderer registry, so this field
is a plain readonly property rather than the `DocumentAnchorTarget` mixin's `override readonly` one.

**Methods:** `write(text)` appends ANSI-parsed text to the buffer, subject to the bounded partial
sequence behavior above. `clear()` empties the buffer.
`scrollToBottom()` and `scrollToAnchor(anchor): Promise<boolean>` control scroll position.
`search(query): Promise<number>` (resolves the match count after the resulting render),
`searchNext()`, `searchPrevious()`, and `clearSearch()` drive in-buffer text search — matching is
line-granular (a match identifies a whole line, not a character range) and capped, so `matchCount`
stops climbing on a pathologically repetitive buffer. `getPlainText()` returns the SGR-stripped
plain text of the whole buffer.

**Events:** `lr-copy` (`detail: { ok: true, text }`, emitted only after a successful clipboard write),
`lr-error` (no detail) and `lr-copy-error` (`detail: { ok: false, text, reason, error }`) on clipboard failure,
`lr-download` (`detail: { filename }`, cancelable — by
default the component creates a plain-text `Blob`/object URL and activates a synthetic
`<a download>`; `preventDefault()` suppresses that built-in download so the host can substitute
server-side or other handling),
`lr-follow-change` (`detail: { following }`), `lr-search-change` (`detail: { query, matchCount,
matchCountExact, activeIndex }`; `matchCountExact` is `false` once a search hits the 10,000-match
ceiling, marking `matchCount` as a lower bound rather than an exact total),
`lr-highlight-activate` (`detail: { highlightId }`), and `lr-text-select` (`detail: {
text, anchor, rects }`).

**CSS parts:** `base`, `toolbar` (only rendered when copy/download are enabled), `copy-button`,
`download-button`, `viewport` (the `role="log"` scrollable region), `line` (one rendered line; carries
`data-line-number`/`data-match`/`data-highlight-tone`, and is forwarded via `exportparts` so
`lr-terminal::part(line)` reaches the rendered lines from a consumer stylesheet despite them living
in the internal `<lr-virtual-list>`'s shadow root), `jump-to-latest` (shown while `follow` is
disengaged and new output has arrived), `line-interactive`, `line-highlight-accent`,
`line-highlight-success`, `line-highlight-warning`, `line-highlight-danger`, `line-highlight-neutral`,
`line-match`, `line-active-match`, and `announcer` (the visually-hidden, `aria-hidden` mirror
of the text last announced while `announce-output` is set).

`[part="announcer"]` is a styling and inspection surface only — it carries **no** live-region role
of its own. The announcement itself goes to the library's shared **light-DOM** polite region,
appended to the consumer's `<body>` and marked `data-lr-live-region="polite"`, because a live
region inside a shadow root is not reliably announced (JAWS with Firefox ignores one outright).
Inspect the shared region, not `::part(announcer)`, when reading an announcement; the part remains
the right hook for styling and for reading back what the terminal last announced.

**Themeable custom properties:** `--lr-terminal-height` (default `var(--lr-size-20rem)`) — the
viewport's block size; not declared on `:host`, so it is inherited from the host or any ancestor.
`--lr-terminal-surface-color` (default `var(--lr-color-surface-raised)`) controls the card-frame
background and the fallback foreground for inverse ANSI segments without an explicit background;
`frame="plain"` remains transparent. `--lr-terminal-border-color` (default
`var(--lr-color-border)`) and `--lr-terminal-radius` (default `var(--lr-radius)`) complete that card
chrome — the border-color hook also colors the toolbar/log divider `frame="plain"` keeps.
`--lr-terminal-surface-color` keeps its established name; nothing was renamed.
`--lr-terminal-toolbar-button-hover-bg` (default
`var(--lr-color-brand-quiet)`) and `--lr-terminal-toolbar-button-active-bg` (default
`color-mix(in oklab, var(--lr-terminal-toolbar-button-hover-bg, var(--lr-color-brand-quiet)),
var(--lr-color-mix-partner) var(--lr-color-mix-active))`) control the copy and download buttons.
`--lr-terminal-line-hover-bg` (default `var(--lr-color-brand-quiet)`) and
`--lr-terminal-line-active-bg` (default `color-mix(in oklab, var(--lr-terminal-line-hover-bg,
var(--lr-color-brand-quiet)), var(--lr-color-mix-partner) var(--lr-color-mix-active))`) control
ordinary rendered lines. `--lr-terminal-highlight-accent-bg` (default `var(--lr-color-brand-quiet)`),
`--lr-terminal-highlight-success-bg` (default `var(--lr-color-success-quiet)`),
`--lr-terminal-highlight-warning-bg` (default `var(--lr-color-warning-quiet)`),
`--lr-terminal-highlight-danger-bg` (default `var(--lr-color-danger-quiet)`), and
`--lr-terminal-highlight-neutral-bg` (default `var(--lr-color-surface)`) — the background of a
`highlights[]` entry of the matching `tone`. `--lr-terminal-compact-toolbar-padding` (default
`var(--lr-space-2xs) var(--lr-space-xs)`) and `--lr-terminal-compact-toolbar-gap` (default
`var(--lr-space-2xs)`) retune `[part="toolbar"]`'s padding and button gap while `compact`, and
`--lr-terminal-compact-line-padding-inline` (default `var(--lr-space-xs)`) retunes each rendered
line's inline padding while `compact` — all three sit behind inline `var()` fallbacks, so a
transcript can retune every nested terminal at once without restating the rules. Each highlight
background is decoupled from the identical shared token it
falls back to (e.g. `accent`'s `--lr-color-brand-quiet` is also the copy/download-button hover tint)
so retinting one tone doesn't repaint the other surface reading that token, and from any
`::part('line')` stylesheet override — the background is applied inline, so a stylesheet rule can't
beat it without `!important`.

**The ANSI/SGR palette is two token sets, not one.** SGR gives the sixteen colour names two
different jobs, and each job is themed separately:

- `--lr-terminal-color-<name>` — **foregrounds**, i.e. `CSI 30`–`37` and `CSI 90`–`97`, drawn _on_
  the terminal panel.
- `--lr-terminal-bg-<name>` — **backgrounds**, i.e. `CSI 40`–`47` and `CSI 100`–`107`, drawn _under_
  the panel's text.

`<name>` is `black`, `red`, `green`, `yellow`, `blue`, `magenta`, `cyan`, `white` and their
`bright-` counterparts — 32 tokens in all, each with its own `--lr-theme-terminal-color-*` /
`--lr-theme-terminal-bg-*` retheme hook, and each with a separate light- and dark-mode value.

The two sets exist because each is solved against a different reference, which is what makes the two
cases a program cannot avoid legible:

1. every `--lr-terminal-color-*` clears 4.5:1 against `--lr-color-surface-raised` — the panel
   `<lr-terminal>` paints for itself — so **any foreground is legible on the panel**;
2. every `--lr-terminal-bg-*` clears 4.5:1 against the panel's default text colour, which is the
   foreground actually in effect whenever a program sets a background and no explicit colour, so
   **the default foreground is legible on any background**.

A single shared set could not do both: foregrounds solved against a light panel are all dark, so
`ESC[41m` would paint a near-black red behind near-black text. An _explicit_ foreground+background
pair (`ESC[30;47m`) is the emitting program's choice and is not guaranteed here, exactly as in a
native terminal — sixteen against sixteen is 256 combinations, several degenerate by construction.

Each colour keeps its canonical ANSI hue (a terminal's red has to look like red, or escape sequences
stop meaning what every other terminal makes them mean); only lightness is solved for. The
consequence worth stating: on a light panel every background is a light tint, so `ESC[40m` ("black
background") renders as the darkest tint that still leaves the default text readable rather than as
literal black. Extended-colour sequences follow the same split: 256-colour indices 0–15 resolve to
the role-matching named token (so `ESC[48;5;1m` gets the background red, not the foreground one),
while indices 16–255 and truecolor become literal `rgb()` values — those are content-supplied rather
than token-driven, and carry no contrast guarantee.

**Additional API surface:**

- `--lr-terminal-search-outline-color` — Outline color for a line containing a non-active search match. Default: `var(--lr-color-warning)`.
- `--lr-terminal-search-active-outline-color` — Outline color for the active search match's line. Default: `var(--lr-color-brand)`.

While a search query is active, writes, scrollback trimming, `content` replacement, and `clear()`
recompute the exact match count and emit `lr-search-change` only when that public search snapshot
actually changes. Pending output announcements are canceled by clear/replacement, disabling
`announceOutput`, or disconnect, so stale text is never announced after it has been removed.
A multi-line highlight paints every retained covered line but exposes exactly one keyboard/click
owner at the anchor's start, or at the first surviving covered line after scrollback trims that
start. Its accessible name combines the caller label with visible line text (or a localized line
number for an empty line), avoiding duplicate tab stops for one logical highlight.

## `lr-trace-tree`

A collapsible span hierarchy for one agent/LLM trace (Langfuse/LangSmith run-tree style): kind icon,
name, status, an inline duration bar on the shared trace time scale, and optional tokens/cost
columns. Consumes the same `LyraSpan[]` as `<lr-span-waterfall>`.

Span views omit whitespace-only IDs and preserve every nonblank business ID exactly, including
surrounding whitespace. The first valid admitted duplicate continues to win.

**Properties:** `spans: LyraSpan[] = []` (attribute: false) — the same `LyraSpan` shape documented
under `lr-span-waterfall` above (exported from `trace-tree/span.ts`); hierarchy comes from
`parentId`, and a span whose `parentId` is missing or doesn't resolve within the same array renders
as a root rather than being dropped. Duration bars scale to the whole trace, measured before the
shared 500-span cap is applied, so a truncated tail never stretches the surviving bars across their
tracks. `activeSpanId: string | null = null`
(attribute `active-span-id`), `label?: string`, `showTokens: boolean = false` (attribute
`show-tokens`) — surfaces `tokensIn`/`tokensOut`, `showCost: boolean = false` (attribute
`show-cost`) — surfaces `costText`, and `hideBars: boolean = false` (attribute `hide-bars`).
`label` is an optional accessible-name override for the `role="tree"` element: omission localizes
the default, and any supplied string — including `''` — is rendered verbatim.
Token counts render only when finite and non-negative; invalid metrics are omitted rather than
reaching `Intl.NumberFormat`. A row's accessible name includes its optional `detail` text as well
as its name/status/metrics, and updates when the supplied span data changes. Every trace view uses
the same bounded runtime projection: provider records are normalized with deterministic first-wins
identity, then at most 500 mount. The controlled `activeSpanId` and its resolvable ancestor path
reserve positions before ordinary input-order spans. Non-object records, empty/blank ids, non-finite
starts/ends, and later duplicate ids are omitted; negative starts clamp to zero, ends clamp to at
least their start, unknown kinds become `other`, and unknown statuses become `pending`. A localized
`[part="limit"]` note exposes truncation.

**Methods:** `expandAll()` and `collapseAll()` set every row's expanded state at once.

**Events:** `lr-span-select` (`detail: { spanId: string }`, a row was activated) and `lr-span-toggle`
(`detail: { spanId: string; expanded: boolean }`, a row was expanded or collapsed).

**CSS parts:** `base` (`role="tree"`), `header` (the column-header row, only when
`showTokens`/`showCost`), `row` (`role="treeitem"`), `toggle`, `icon`, `name`, `detail`, `status-text`,
`duration`, `tokens-in`, `tokens-out` (when `showTokens`), `cost` (when `showCost`), `bar-track`,
`bar`, `empty` (shown when `spans` is empty), `limit` (the 500-span projection notice), and
`live-region`.

**Themeable custom properties:** `--lr-trace-tree-row-active-bg` (default
`var(--lr-color-brand-quiet)`) — the background of the active (`activeSpanId`) row — and
`--lr-trace-tree-row-active-color` (default `var(--lr-color-text)`) — the color of that row's
secondary text (`detail`, `duration`, `tokens-in`, `tokens-out`, `cost`, and the `pending`
`status-text` label). Same state-scoped-property convention described under `lr-span-waterfall`
above: an inline `var()` fallback rather than a `:host` declaration, so either can be set on the
element or any ancestor, and they exist because `::part(row)[data-active]` is invalid CSS.
`--lr-trace-tree-max-indent` (default `var(--lr-size-12rem)`) caps visual nesting indentation;
semantic `aria-level` remains exact at deeper levels.

**Contrast note:** the active row is more than a tint. Its secondary text would sit at ~4.25:1
against the default tint if it stayed at `--lr-color-text-quiet`, so it rises to full-strength
`--lr-color-text` while the row is active, and the semantic `status-text` labels are rendered as
`color-mix(in srgb, var(--lr-color-<tone>) 75%, var(--lr-color-text))` — keeping the status hue
(an error row stays red) while clearing the 4.5:1 floor (success 4.46 → 6.18, `denied` 4.28 →
5.96). Both adjustments are theme-symmetric, because `--lr-color-text` flips with the color
scheme. `[part='bar']` is deliberately untouched: it is a non-text graphic on a 3:1 floor, and its
saturation is the row's primary status signal.

The two properties are a **pair**. The defaults assume the active background stays on the same
side of the lightness midpoint as the ambient surface, so a consumer who sets
`--lr-trace-tree-row-active-bg` to a dark tint in light mode (or a light one in dark mode) must
set `--lr-trace-tree-row-active-color` to match, and should re-check the status-label tones
against the new tint as well.

**Additional API surface:**

- `--lr-trace-tree-toggle-hover-bg` — Toggle hover background. Default: `var(--lr-color-brand-quiet)`.
- `--lr-trace-tree-success-color` — Success status text and bar. Default: `var(--lr-color-success)`.
- `--lr-trace-tree-error-color` — Error status text and bar. Default: `var(--lr-color-danger)`.
- `--lr-trace-tree-denied-color` — Denied status text and bar. Default: `var(--lr-color-warning)`.
- `--lr-trace-tree-running-color` — Running status text and stripe. Default: `var(--lr-color-brand)`.
- `--lr-trace-tree-pending-color` — Pending status text and bar. Default: `var(--lr-color-text-quiet)`.
- `--lr-trace-tree-bar-track-bg` — Duration bar track. Default: `var(--lr-color-surface-raised)`.
- `--lr-trace-tree-running-stripe-bg` — Running stripe contrast. Default: `var(--lr-color-brand-quiet)`.

## `lr-activity-feed`

An append-only streaming log of granular agent actions ("Searching the web…", "Read the
application entry point"), collapsing to a localized "Completed N steps" summary once the run is over. Entries
never change state once added — a step whose status mutates in place belongs to `<lr-task-list>`
instead. Implements the shared follow (stick-to-bottom) contract. Focus is repaired rather than
silently dropped when the control holding it disappears: collapsing (`expanded` becoming `false`)
moves focus already inside the body to `[part="header"]` before the body is hidden, and removing
the specific `entries` row that held focus does the same once that render (and, while virtualized,
the internal `<lr-virtual-list>`'s own follow-up render) has settled. Focus that is elsewhere is
left alone — appending a live entry never steals focus from an unrelated, still-present control.
At/above `virtualizeAt`
entries, the body renders through an internal `<lr-virtual-list>` instead of a plain keyed list.

**Properties:** `entries: ActivityEntry[] = []` (attribute: false) — `ActivityEntry { id: string;
text: string; icon?: string; timestamp?: Date | string; variant?: LyraVariant; data?: unknown }`
(exported here). `icon` is a literal glyph hint (e.g. an emoji), the same convention
`lr-tool-call-chip.icon` uses; a small variant dot renders in its place when omitted. Empty/blank
ids and later duplicate ids are omitted before the summary, keyed render, or virtualization path is
chosen. `LyraVariant = 'neutral' | 'brand' | 'success'
| 'warning' | 'danger'` is the library-wide semantic vocabulary, so an entry is toned with the same
five values as every other `variant` in the library. An invalid `timestamp` string is treated as
unset. `data` is an opaque caller payload (e.g. the source record an entry summarizes) — never read
or rendered by this component. It is retained by reference, never deep-cloned, through the owned
`entries` snapshot, and handed back to `renderText` on every render, so a consumer needing richer
per-entry context does not have to re-derive it by re-scanning its own source array by id. `mode: 'live' | 'post-hoc' =
'live'` (reflected), `follow: boolean = true` (reflected), `expanded: boolean = false` (reflected),
`label?: string` — omission localizes `activityFeedLabel` (`'Activity'` in the built-in English
catalog), while any supplied string is a verbatim override, including `'Activity'` under a
non-English `.strings` catalog and `''`. A present host `aria-label` names the owned list in both
plain and virtualized rendering paths while `label` remains the visible header text. Host
`aria-labelledby` and `aria-describedby` likewise reach that semantic list in both rendering paths —
`showTimestamps: boolean = false` (attribute `show-timestamps`),
`formatTimestamp?: (date: Date) => string` (attribute: false), `renderText?: (entry: ActivityEntry)
=> TemplateResult` (attribute: false) — overrides the default plain-text `entry-text` rendering with
arbitrary rich content (e.g. rendered markdown, or markdown plus a trailing tool-call chip list),
identically whether or not the feed is currently virtualized; replaces the plain text **inside**
the persistent `[part="entry-text"]` wrapper rather than removing that part, and `virtualizeAt: number = 199` (attribute
`virtualize-at`). `compact: boolean = false` (reflected) — tighter header and entry-row padding for
dense transcript contexts, the same density-only convention `<lr-confirm-bar>`'s and
`<lr-thinking-panel>`'s own `compact` establish: the outer border and surface stay, so pair it
with `frame="plain"` to remove card chrome. Retune it through
`--lr-activity-feed-compact-header-padding`, `--lr-activity-feed-compact-header-gap`, and
`--lr-activity-feed-compact-entry-padding`. `frame: LyraFrame = 'card'` (reflected) — `'card' |
'plain'`, imported from the library's shared container-frame vocabulary and behaving exactly as
it does on `lr-confirm-bar`/`lr-thinking-panel`/`lr-agent-run`/etc.: `'plain'` removes the outer
border, background, and corner radius so a feed nested inside existing message chrome doesn't
double it. The header/body divider and entry-row padding are unaffected by `frame` — only the
outer card goes.

**Events:** `lr-toggle` (`detail: { expanded }`, the header was activated) and
`lr-follow-change` (`detail: { following }`, `follow` released or re-engaged).

**CSS parts:** `base`, `header` (a `<button>`), `status-dot` (pulses while `mode="live"`), `label`,
`summary`, `toggle`, `body` (the scrollable region, or the internal virtual-list), `entry` (carries
`data-variant`), `entry-icon`, `variant-dot` (the dot rendered inside `entry-icon` when the entry
sets no literal `icon`), `variant-dot-neutral`/`variant-dot-brand`/`variant-dot-success`/
`variant-dot-warning`/`variant-dot-danger` (each also carries `variant-dot`), `entry-text`, and
`entry-timestamp` (only while `showTimestamps` and a valid `timestamp` is set). Every entry-level
part is reachable in both rendering paths, virtualized or not.

**Themeable custom properties:** `--lr-activity-feed-max-height` (default `16rem`) — cap on how
tall the expanded body grows before it scrolls internally; and
`--lr-activity-feed-live-status-color` (default `var(--lr-color-brand)`) — background color of
`status-dot` while `mode="live"`, independently retunable without changing other brand surfaces.
The `compact` density is retunable through three properties: `--lr-activity-feed-compact-header-padding`
(default `var(--lr-space-2xs) var(--lr-space-s)`) and `--lr-activity-feed-compact-header-gap`
(default `var(--lr-space-2xs)`) both scoped to `[part="header"]` while `compact`, and
`--lr-activity-feed-compact-entry-padding` (default `var(--lr-space-2xs) var(--lr-space-s)`)
scoped to `[part="entry"]` while `compact`. All three are inline `var()` fallbacks at their point
of use, so any can be set on the element or on an ancestor, same as `lr-confirm-bar`'s and
`lr-thinking-panel`'s own compact tokens. The card chrome itself is retunable the same way:
`--lr-activity-feed-background` (default `var(--lr-color-surface)`) fills `[part="base"]`,
`--lr-activity-feed-border-color` (default `var(--lr-color-border)`) colors both its border and the
header/body divider that `frame="plain"` keeps, and `--lr-activity-feed-radius` (default
`var(--lr-radius)`) sets its corner radius — so retuning a nested feed no longer needs a
`::part(base)` override. `frame="plain"` still removes the border, radius and fill outright; the
hooks tune the card presentation rather than reinstating chrome you asked to drop.

**Known gotchas:**

- The variant dot's color is selected by its _part name_, not by `[data-variant]`: `::part()` cannot
  be followed by an attribute selector, so
  `lr-activity-feed::part(variant-dot)[data-variant='success']` never matches. Target
  `lr-activity-feed::part(variant-dot-success)` instead. `data-variant` remains on both the entry
  and the dot for DOM queries.
- `compact`/`frame` render byte-identically to the pre-existing default when unset — neither
  property changes anything about the plain-card presentation.
- Focus repair after an `entries` change is asynchronous while virtualized (it waits on the
  internal `<lr-virtual-list>`'s own follow-up render before deciding whether the previously
  focused row actually disappeared), but synchronous when collapsing (`expanded` going `false`)
  — the header renders regardless of `expanded`, so there's nothing to wait for there.

## `lr-commit-card`

A compact commit summary (subject, author/time, diffstat, per-file changes) that links file rows out
to a diff view.

Removing the `message` attribute clears the displayed subject and body; the property retains the
normal `null` readback of a removed string attribute.

**Properties:** `hash: string = ''`, `message: string = ''`, `author: string = ''`, `timestamp?:
number` (attribute: false, epoch milliseconds), `files: CommitFileChange[] = []` (attribute: false) —
`CommitFileChange { path: string; additions: number; deletions: number; status?: GitStatus }`
(exported here), where `GitStatus = 'added' | 'modified' | 'deleted' | 'renamed' | 'untracked' |
'conflicted' | 'ignored'` (shared with `lr-file-tree`); the diffstat is summed from `additions`/
`deletions` across `files`. Counts are normalized to finite non-negative integers before per-file
display, total arithmetic, localization, and accessible summaries. `path` is the file identity;
empty/blank paths and later duplicates are omitted before both diffstat arithmetic and row events. `filesExpanded:
boolean = false` (attribute `files-expanded`, reflected — renamed from `filesCollapsed` in 9.0.0,
default inverted so the rendered starting state is unchanged: `el.filesCollapsed = true` becomes
`el.filesExpanded = false`), and `copyable: boolean = true` (reflected).
`compact: boolean = false` (reflected) — tighter `[part="base"]` padding for a commit rendered as a
row in a list or PR timeline, same convention as `<lr-agent-run>`'s own `compact`; the border stays,
so pair it with `frame="plain"` to drop the chrome entirely. `frame: LyraFrame = 'card'` (reflected)
— container treatment, in the library-wide `frame` vocabulary (`'card' | 'plain'`), the same
property `<lr-agent-run>`/`<lr-card>` carry: `'card'` keeps the bordered, padded box, `'plain'`
removes the border, padding, and corner radius so a commit nested in a host list that already draws
its own row chrome doesn't double it; `plain` wins over `compact` when both are set. The exported
alias `CommitCardAppearance` is retained as a name for the same union.

**Slots:** `actions` — trailing header controls (e.g. an "open PR" button).

**Events:** `lr-file-select` (`detail: { filePath: string }`), `lr-toggle` (`detail: { collapsed: boolean
}`), and `lr-copy` (`detail: { ok: true; text: string }`, fired only after the full-hash clipboard write
resolves successfully). A failed or unavailable write emits the compatibility `lr-error` event
(no detail) and `lr-copy-error` (`detail: { ok: false; text: string; reason:
'unsupported'|'denied'|'failed'; error: unknown }`) instead; failure never emits `lr-copy`.

**CSS parts:** `base`, `subject`, `body`, `hash`, `meta`, `author`, `time`, `diffstat`, `additions`,
`deletions`, `files-toggle`, `file` (carries `data-status`), `file-path`, `file-status`,
`file-additions`, `file-deletions`, `copy-button`, and `actions`.

`file-status` is the one-letter git-status badge (`A`/`M`/`D`/`R`/`U`/`C`/`!`) rendered inside
`[part="file-path"]`, present only for a file that has a `status`. The letter alone is meaningless to
a screen reader, so the element carries the localized expansion as its `aria-label` — "Modified",
"Added", … — reusing `<lr-file-tree>`'s shared `gitStatusAdded`/`gitStatusModified`/
`gitStatusDeleted`/`gitStatusRenamed`/`gitStatusUntracked`/`gitStatusConflicted`/`gitStatusIgnored`
message keys, so one `registerLyraLocale()` registration (or one `.strings` override) translates the
badge in both components at once.

**Themeable custom properties:** `--lr-commit-card-compact-padding` (default `var(--lr-space-s)`) —
`[part="base"]` padding while `compact`. `--lr-commit-card-border-color` (default
`var(--lr-color-border)`) and `--lr-commit-card-radius` (default `var(--lr-radius)`) retune the
card's border and corner radius, and `--lr-commit-card-background` (default `transparent`) gives it
a fill of its own — this card has never painted one, so it still takes the surface it sits on unless
you opt in. `frame="plain"` still removes the border and radius.

## `lr-test-results`

A pass/fail suite summary with per-status counts, status filter toggles, and per-test rows whose
failures auto-expand by default and can host rich slotted detail (e.g. a diff or code block)
alongside the plain failure message.

**Properties:** `suites: readonly TestSuiteResult[] = []` (attribute: false) — `TestSuiteResult { id: string;
name: string; tests: readonly TestCaseResult[] }` and `TestCaseResult { id: string; name: string; status:
TestStatus; durationMs?: number; message?: string }`, with `TestStatus = 'passed' | 'failed' |
'skipped' | 'running'` (all three exported here). `statusFilter: readonly TestStatus[] =
[]` (attribute: false) — empty shows every status. `runId: string | null = null` (attribute
`run-id`) identifies the source run, and `runState: TestRunState = 'idle'` (attribute `run-state`,
reflected) exposes its lifecycle. `autoExpandFailures: boolean = true`
(attribute `auto-expand-failures`). A duration renders only when it is finite and non-negative;
invalid/negative values are omitted rather than reaching `Intl.NumberFormat`. Empty/blank suite and
test ids are omitted; retained suite ids, then test ids within each suite, use deterministic
first-wins identity. Foreign runtime statuses normalize
once to the localized neutral `skipped` state, so every accepted row contributes to one coherent
summary count and renders a label/glyph.

Summary counts cover the complete normalized input. At most 1,000 rows mount for the active filter;
manually expanded identities reserve positions first, failed rows next, then ordinary input-order
rows. A localized `[part="limit"]` note exposes truncation without losing the complete counts.

**Slots:** `detail-{encodedSuiteId}:{encodedTestId}` — collision-free suite-scoped rich detail for
a test. Derive the complete name with the exported
`testResultDetailSlotName(suiteId, testId)` helper. Well-formed ids use `encodeURIComponent`
segments; isolated UTF-16 surrogates, which that built-in rejects, use deterministic uppercase
`%uXXXX` code-unit escapes. It renders after the plain `message` once expanded (for example, suite
`unit` and test `same` use `slot="detail-unit:same"`). This is the only detail slot the component
reads, and exactly one is mounted per row. The legacy `detail-{suiteId}-{testId}` and
`detail-{testId}` spellings were removed in 9.0.0 — content assigned to either is never slotted and
never makes a row expandable; migrate by deriving the name with
`testResultDetailSlotName(suiteId, testId)`. Slot listeners remain mounted while detail is absent,
so appending matching slotted content after the component's first render immediately enables the
row's disclosure.

**Events:** `lr-test-select` (`detail: { suiteId: string; testId: string }`, a test row's name was
activated), `lr-filter-change` (`detail: { statuses: TestStatus[] }` — the complete next filter set; the
component updates its own `statusFilter` first, then emits),
and `lr-toggle` (`detail: { suiteId: string; testId: string; expanded: boolean }`, a row's failure
detail was expanded/collapsed). The suite-scoped identity shape is invariant even when `testId` is
globally unique. Manual expansion state is keyed by that same suite+test pair.
Each expand/collapse action's localized accessible name includes both suite and test names, so
repeated row controls remain distinguishable.

Passed, failed, and skipped rows use language-neutral decorative marks (`✓`, `×`, and `–`); the
adjacent localized status word carries the meaning. Running rows use the decorative spinner.

**CSS parts:** `base`, `summary` (the status-count strip), `count` (carries `data-status`), `filter`,
`filter-toggle` (carries `data-status`/`aria-pressed`), `suite`, `suite-header`, `test` (carries
`data-status`), `test-status`, `test-name`, `test-duration`, `test-expand-toggle`, `failure`
(hidden while collapsed), `failure-message`, `limit`, and `empty`.

**Themeable custom properties:** `--lr-test-results-filter-active-bg` (default
`var(--lr-color-brand-quiet)`), `--lr-test-results-filter-active-border` (default
`var(--lr-color-brand)`) and `--lr-test-results-filter-active-color` (default
`var(--lr-color-brand)`) — the background, border color and text color of a pressed (active) status
filter toggle. All three follow the state-scoped-property convention described under
`lr-span-waterfall`: inline `var()` fallbacks rather than `:host` declarations, so each can be set on
the element or on any ancestor. They exist because
`::part(filter-toggle)[aria-pressed='true']` is invalid CSS — Shadow Parts forbids an attribute
selector after `::part()` — so restyling the pressed state otherwise meant overriding the
library-wide brand tokens. Per-result status foregrounds are independently exposed through
`--lr-test-results-passed-color` (default `var(--lr-color-success)`),
`--lr-test-results-failed-color` (default `var(--lr-color-danger)`),
`--lr-test-results-skipped-color` (default `var(--lr-color-text-quiet)`), and
`--lr-test-results-running-color` (default `var(--lr-color-brand)`).
`--lr-test-results-spinner-size` (default `var(--lr-size-1em)`) controls the composed spinner's
diameter in a running test row without requiring an override of `lr-spinner`'s token.

## `lr-confirm-bar`

An inline, non-modal approve/deny block for one proposed action — the in-flow sibling of
`lr-tool-approval-dialog` for confirmations that should sit in the transcript instead of hijacking
focus. Same `lr-approve`/`lr-deny` event shapes as the dialog, and the same
`toolApprovalHeading`/`toolApprovalArgsLabel`/`deny`/`approve` localization keys, so the two always
translate in lockstep. Non-modal by contract: no focus trap, no scroll lock, no Escape/backdrop
semantics, and it never steals focus when it appears in the transcript. "Never steals focus" and
"no Escape semantics" describe the bar's behavior when `autofocus` and `escape-denies` are both
left unset (the default). A host that swaps a focused control out for this bar can opt into either
or both instead of hand-rolling them, as `<lr-memory-panel>` still does internally
(`focusPendingConfirmation`/`onConfirmKeyDown`). DOM and tab order put Deny before Approve. On
activation, focus moves synchronously to the first available of `returnFocusTo` and
`[part="status"]` (an always-rendered, `tabindex="-1"` element) before the Deny/Approve buttons
unmount, so focus never has a gap where it would fall back to `<body>`. Unset, `returnFocusTo`
leaves that handoff landing on `[part="status"]` exactly as it always has.

**Properties:** `toolName: string = ''` (attribute `tool-name`) — drives the default heading through
the existing `toolApprovalHeading`/`toolApprovalGenericTool` dialog keys. `heading: string = ''` —
free-form heading override for non-tool proposals; wins over `toolName`. `args: unknown = undefined`
(attribute: false) — shown read-only inside a collapsed `lr-details` + `lr-json-viewer` when
defined. `decision: 'approved' | 'denied' | null = null` (reflected) — decided state, set by the
component on activation and host-writable (an externally-resolved decision renders identically and
emits no `lr-approve`/`lr-deny` of its own; `lr-decision-settled` still fires, because the status
really did render). `variant: ConfirmBarVariant = 'neutral'` (reflected) — `'neutral' | 'danger'`, a
genuine two-member subset of the library-wide `LyraVariant` vocabulary (spelled as an `Extract` of
it, so the two can never drift): a confirmation is either routine or destructive, and
`brand`/`success`/`warning` have no meaning for a proposal awaiting a yes/no. `compact: boolean = false`
(reflected) — collapses the bar from a stacked `display: block` card into a single tightly-padded
inline row, for a confirmation that has to live inside an existing container: a table cell, a card's
action row, a toolbar. The host becomes `inline-flex`, and the narrow-allocation `@container`
treatment is switched off — a compact bar is _expected_ to be narrow, so stretching the buttons to
fill would be exactly wrong. It is a density knob only: the border, corner radius and background
stay. Retune it through `--lr-confirm-bar-compact-padding`/`-gap`. Everything else is unchanged: the
event shapes, the focus-to-`[part="status"]`-before-unmount contract, and `role="group"` with its
heading label. `frame: LyraFrame = 'card'` (reflected) — `'card' | 'plain'`, imported from the
library's shared container-frame vocabulary and behaving exactly as it does on `lr-agent-run`,
`lr-commit-card`, `lr-result-card`, `lr-task-list`, `lr-terminal` and `lr-thinking-panel`:
`'plain'` removes the border, background, padding and corner radius so a bar nested inside a
container that already draws a border doesn't double it, and wins over `compact` when both are set.
Before 9.0.0 `compact` alone did both jobs; a bar that relied on that now needs
`compact frame="plain"`. `ConfirmBarDecision = ApprovalDecision | null` names the final-state type.
`pending: ApprovalAction | null = null` (reflected) — which action is awaiting host
resolution while an `lr-approve`/`lr-deny` listener has called `preventDefault()` on the
now-cancelable event; the pending button shows `loading`, the other is `disabled`. Set `.decision`
to finalize, or clear `.pending` back to `null` to bounce back to the undecided state.
`waitUntil(promise)` in the event detail is the declarative form of that same state machine and
needs no `preventDefault()`: the bar sets `pending` itself, and the promise's settlement finalizes
`decision` or clears `pending` and returns focus to the control that can retry.
`disabled: boolean = false` (reflected) — disables both Deny and Approve and makes activating either
a no-op, without discarding any in-flight `decision`/`pending` state. Distinct from `pending`:
`pending` marks one specific action as awaiting the host while the other stays interactive;
`disabled` blocks both regardless of `pending`. `autofocus: boolean = false` (reflected) — opt-in
focus-on-mount: moves focus into the bar after its own first render, once this element and (when
present) the Deny `<lr-button>` have both completed it. Named after the native global attribute it
stands in for, since the platform's own `autofocus` algorithm only fires for an element already in
the document when it finishes parsing, never for one a host swaps in afterward — this bar's primary
use. Focuses the Deny control when it's present and actually focusable (not `disabled`, not
hidden), else the always-present `[part="status"]`. `escapeDenies: boolean = false` (attribute
`escape-denies`, reflected) — maps Escape on `[part="base"]` to the same outcome as clicking Deny.
A no-op while `disabled`, already decided, or `pending`, exactly like clicking Deny itself, and
never stops propagation when it was a no-op, so an unrelated enclosing dialog's own Escape handling
still sees the event. Scoped to this element's own `[part="base"]` rather than `document`: this bar
is inline and non-modal, not a member of the shared `activateOverlay()` Escape/stacking contract
real overlays use.
`returnFocusTo: ConfirmBarReturnFocusTarget = null` (attribute: false) — where focus goes once a
decision lands, instead of parking on `[part="status"]`.
`ConfirmBarReturnFocusTarget = HTMLElement | null | (() => HTMLElement | null)`; the thunk form is
called at handoff time, because a host that swaps a focused control out for this bar often
re-creates that control on the way back — and, because every supported host framework re-renders
asynchronously relative to that synchronous handoff, the control frequently does not exist yet at
that first call. When the first call does not yet name a live, focusable element, the same handoff
calls the thunk again once the host has had a real chance to react (its own re-render committed),
and moves focus there if it has since appeared and nothing else has claimed focus in the meantime —
this is what makes the swap-a-trigger-for-this-bar case actually work, rather than only working when
the host happens to re-create its control before the decision lands. A plain element value is
resolved once, synchronously, and never retried: it names something that either already exists or
never will. It applies to every path that reaches a decision, a `pending` decision finalized
externally included. A named target that is missing, detached, `inert`, or otherwise refuses focus
falls back to `[part="status"]` rather than to `<body>` — an `inert` element refuses `focus()`
silently. Left unset, the handoff is byte-identical to the shipped one. The pending state is
deliberately *not* affected: while a decision is awaiting resolution, focus still parks on
`[part="status"]`, because that is not the return journey yet.

**Slots:** default — supplementary body content between the heading and the actions (e.g. a
`lr-diff-view`). `footer` — extra content at the start of the action row.

**Events:** `lr-approve` (`detail: { args, waitUntil }` — `args` is the `args` prop as-is, matching
`lr-tool-approval-dialog`'s own `args` detail; cancelable), `lr-deny` (`detail: { waitUntil }`, the
same resolver and no denial data of its own; cancelable), `lr-decision-settled`
(`detail: { decision }`; non-cancelable).

`waitUntil(promise: Promise<unknown>) => void` is ExtendableEvent-style. Calling it from the
listener holds the bar in its `pending` presentation — `loading` on the activated control,
`disabled` on the other — until the promise settles: a resolution finalizes `decision`, a rejection
restores the undecided state and returns focus to the control that can retry. Several `waitUntil()`
calls, from one listener or from several, are awaited together. Calling it after its own dispatch
has finished does nothing (and warns in dev mode); the promise it receives may settle whenever it
likes. It needs no `preventDefault()`, and the imperative path it replaces — `preventDefault()`,
then writing `pending` and later `decision` by hand — still works unchanged. A listener that
resolves the decision itself synchronously, by writing `decision` or `pending` during the dispatch,
wins outright over both: the bar applies no bookkeeping of its own, `waitUntil()`'s included.

`waitUntil` is this component's alone: `<lr-tool-approval-dialog>` emits the same `lr-approve`/
`lr-deny` names without it, so a listener bound to the shared name rather than to one component
must narrow on `event.target` — see that component's Events section.

`lr-decision-settled` fires after the decided `[part="status"]` has rendered and its live-region
announcement has been made, on every path that reaches a decision — the bar's own, a `waitUntil()`
settlement, and a host writing `.decision` directly. It is the signal to swap the bar out on:
awaiting a single `updateComplete` after your own promise resolves is not enough, because the
promise chain and Lit's update queue interleave. A `decision` present in the initial markup
announces and settles nothing — it never transitioned.

**16.0.0 — breaking detail change.** `lr-deny`'s detail changed from `null` to `{ waitUntil }` and
`lr-approve`'s from `{ args }` to `{ args, waitUntil }`. A listener that compared the whole detail
object (`detail === null`, or a deep-equality check against `{ args }`) must read the fields it uses
instead.

**CSS parts:** `base` (`role="group"`), `heading`/`tool-name`, `body`, `args` (the
details/json-viewer wrapper, only rendered when `args` is defined), `footer`, `deny-button`,
`approve-button` (each an `<lr-button>` host, named identically to the dialog's parts),
`deny-button-base`, `deny-button-label`, `deny-button-start`, `deny-button-end`,
`deny-button-spinner`, `approve-button-base`, `approve-button-label`, `approve-button-start`,
`approve-button-end`, `approve-button-spinner` (re-exported from each button's own
`lr-button` parts via `exportparts`; each `*-button-base` route accepts the same-node `base` and
`button` wrapper aliases), `status` (the decided-state text, always present in the DOM as a focus
landing spot).

**Themeable custom properties:** `--lr-confirm-bar-bg` (default `var(--lr-color-surface)`) is
`[part="base"]`'s RESTING background — the default tier every approval prompt renders at, and the
companion to the `compact` density levers below; `frame="plain"` still drops the fill entirely.
The `compact` density is retunable through two further properties, both
scoped to `[part="base"]` while `compact`: `--lr-confirm-bar-compact-padding` (default
`var(--lr-space-s)`, any padding shorthand — overridden entirely by `frame="plain"`) and
`--lr-confirm-bar-compact-gap` (default `var(--lr-space-s)`, the gap between the row's items). They
are inline `var()` fallbacks at their point of use rather than `:host` declarations, so either can
be set on the element _or on any ancestor_, which is what makes "tighten every compact confirm bar
in this panel" a one-rule change on the panel. The chrome-removing
`--lr-confirm-bar-compact-border`, `--lr-confirm-bar-compact-background` and
`--lr-confirm-bar-compact-radius` properties were removed in 9.0.0 along with `compact`'s chrome
behavior: chrome is now `frame`'s job, so keep the default `frame="card"` (and restyle via
`::part(base)`) instead of re-chroming a chrome-less compact bar.

Two further properties recolor the decided state: `--lr-confirm-bar-approved-color` (default
`var(--lr-color-success)`) and `--lr-confirm-bar-denied-color` (default `var(--lr-color-danger)`) —
`[part="status"]`'s text/icon color under `:host([decision='approved'])` and
`:host([decision='denied'])` respectively. Same inline-`var()`-fallback shape as the compact set.
They exist because `::part(status)[decision]` is invalid CSS, so recoloring just this component's
decided state previously meant re-pointing the library-wide `--lr-color-success`/`-danger` tokens and
repainting everything else that reads them.

**Known gotchas:**

- `[part="status"]` is always rendered and must never be given `display: none`. Deciding moves focus
  to it synchronously, before the Deny/Approve buttons unmount, so hiding it would drop focus to
  `<body>`. The shipped `:empty` rule on it has never matched, and that is load-bearing.
- `[part="deny-button"]`/`[part="approve-button"]` are `<lr-button>` hosts. Deny is
  `variant="neutral" appearance="outlined"`; Approve is `variant="brand"` (`"danger"` under this
  component's own `variant="danger"`) at `lr-button`'s default `appearance="accent"`, so the
  destructive-or-primary action is the loud one and the safe action recedes. `--lr-button-*` theming
  reaches both directly. A
  consumer previously styling `::part(deny-button)`/`::part(approve-button)` for
  padding/border/font/`:hover`/`:focus-visible` must move that CSS onto the re-exported
  `deny-button-base`/`approve-button-base` sub-parts instead — the outer part now resolves to the
  `<lr-button>` host, where those declarations either do nothing or must be re-expressed through
  `lr-button`'s own parts/custom properties.
- An `lr-approve`/`lr-deny` listener can call `preventDefault()` to keep the decision open while
  its own async work is in flight — see `pending` above. If that same listener resolves the
  decision itself synchronously (setting `.decision` or `.pending` directly before returning), that
  wins outright: the component's own built-in `pending` bookkeeping only applies when the listener
  left both untouched, so a listener finalizing out of band is never silently clobbered back into
  the built-in loading/disabled presentation.
- `disabled` blocks both Deny and Approve and makes activating either a no-op — see `disabled`
  above. It is independent of, and composes with, `pending`.
- `autofocus`/`escape-denies` are both opt-in and default to `false`; neither changes any
  existing bar's behavior unless a host sets it. `escape-denies` is intentionally *not* routed
  through the shared overlay Escape manager (`src/internal/overlay-manager.ts`) — this component
  is explicitly non-modal (see the class doc), so binding Escape on its own `[part="base"]` is
  the correct scope, not a shortcut around the shared contract.

```html
<lr-tool-call-chip status="pending"></lr-tool-call-chip>
<lr-confirm-bar tool-name="run_shell"></lr-confirm-bar>
<script type="module">
  const bar = document.querySelector("lr-confirm-bar");
  bar.args = args;
  bar.addEventListener("lr-approve", (e) => run(e.detail.args));
  bar.addEventListener("lr-deny", () => cancel());
</script>
```

An `lr-approve`/`lr-deny` listener that needs to await its own async work before finalizing calls
`preventDefault()` and sets `.decision` (or clears `.pending`) once it resolves:

```ts
bar.addEventListener("lr-approve", (e) => {
  e.preventDefault();
  runApproval(e.detail.args)
    .then(() => {
      bar.decision = "approved";
    })
    .catch(() => {
      bar.pending = null;
    }); // bounce back, retry
});
```

A host that reveals this bar in place of a control it just hid — the `returnFocusTo` motivating
case — does not need to order that swap relative to the line above. A reactive host's own re-render
(replacing this bar with its trigger again) runs on its own update cycle, which lands asynchronously
either way, so `returnFocusTo`'s thunk is written to be called twice: once immediately, in case the
control already exists, and once more after the host has had a chance to react if the first call
found nothing yet:

```ts
bar.returnFocusTo = () => document.querySelector('[data-action="delete"]');
bar.addEventListener("lr-approve", (e) => {
  e.preventDefault();
  runApproval(e.detail.args)
    .then(() => {
      bar.decision = "approved"; // the host's own state clear can happen before or after this
    })
    .catch(() => {
      bar.pending = null;
    });
});
```

## `lr-browser-frame`

Presentational "agent computer" viewport: a screenshot/frame stream (or slotted live media), a
read-only URL display, action-ping overlays, and take-over/stop affordances. No automation transport
(no CDP/WebRTC/WebSocket) and no input relay — take-over is an event; the host swaps in its own
interactive element (e.g. an iframe). No replay scrubber (compose `lr-sequence-playback` with
`itemCount` set to the screenshot count, then drive `frameSrc` from `currentIndex` whenever
`lr-sequence-step` emits `detail: { currentIndex }`); no console/network drawers (compose
`lr-terminal`/`lr-json-viewer`); no
pan/zoom of the frame content (slot the image/video inside a `lr-zoomable-frame` instead, though
the pings overlay assumes the unzoomed content box in that composition).

**Properties:** `frameSrc: string = ''` (attribute `frame-src`) — image/MJPEG stream URL rendered as
an `<img>` (safe-URL-gated via `safeMediaSrc`); ignored once the default slot has content. `url:
string = ''` — address shown read-only in the toolbar (`dir="ltr"`, truncating, full value in
`title`). `phase: LyraStreamPhase = 'idle'` (reflected; `'idle' | 'connecting' | 'streaming' |
'stalled'`). `controller:
'agent' | 'user' = 'agent'` (reflected) — who is driving; switches the take-over button's label.
`pings: BrowserPing[] = []` (attribute: false, each `{ id, x, y, kind: 'click' | 'type' | 'scroll' |
'move' }` — `x`/`y` are percent (0–100) of the frame's `object-fit: contain` content box,
letterboxing-aware). Empty/blank ping ids and later duplicates are omitted before overlay rendering. `controls:
boolean = true` — render the built-in take-over/stop buttons.

**Slots:** default — host-owned live element (e.g. `<video>` or an interactive `<iframe>`), replacing
the `frame-src` image. `actions` — extra toolbar controls.

**Events:** `lr-take-over` — `detail: { controller }`, the _requested_ controller (`'user'` when
"Take over" is pressed, `'agent'` when "Hand back" is). `lr-stop` — stop the agent's browser
session, no detail.

**CSS parts:** `base` (`role="group"`), `toolbar`, `url`, `status` (visible, non-live text),
`controller-badge`, `actions`, `take-over-button`, `stop-button`, `viewport`, `frame` (the
`frame-src` `<img>`, absent once the default slot is populated), `ping` (one action-ping marker,
carries `data-kind`).

After mount, each `phase` transition is appended to the shared polite light-DOM announcement sink.
The phase already shown on initial mount or reconnect establishes a silent baseline, including a
phase write queued while detached.

**Themeable custom properties:** `--lr-browser-frame-aspect-ratio` (default `16 / 9`) — the
viewport's aspect ratio.

```html
<lr-browser-frame phase="streaming" url="https://example.com"></lr-browser-frame>
<script type="module">
  const frame = document.querySelector("lr-browser-frame");
  frame.pings = pings;
  frame.addEventListener("lr-take-over", (e) => setController(e.detail.controller));
  frame.addEventListener("lr-stop", () => stopSession());
</script>
```

**Additional API surface:**

- `--lr-browser-frame-controller-background` — Controller badge background. Default: `var(--lr-color-brand-quiet)`.
- `--lr-browser-frame-controller-color` — Controller badge text color. Default: `var(--lr-color-brand)`.
- `--lr-browser-frame-ping-click-color` — Click-ping border color. Default: `var(--lr-color-brand)`.
- `--lr-browser-frame-ping-type-color` — Type-ping border color. Default: `var(--lr-color-success)`.
- `--lr-browser-frame-ping-scroll-color` — Scroll-ping border color. Default: `var(--lr-color-warning)`.
- `--lr-browser-frame-ping-move-color` — Move-ping border color. Default: `var(--lr-color-text-quiet)`.

## `lr-artifact-panel`

Shell around one agent-generated artifact: a title/kind header, a preview↔code toggle, version
navigation with restore, a streaming indicator, and built-in copy/download actions. Renders none of
the artifact itself — content is slotted. No content rendering of its own (slots own it), no
dialog/dock chrome (compose `lr-dialog`/`lr-dock-panel`/`lr-multi-split`), no version storage or
diffing (host state; diffs via `lr-diff-view`), no code editing (`lr-code-editor`).

**Properties:** `label?: string` — the artifact's title, shown in the header; omitting it reads back
`undefined` and localizes the `artifactPanelLabel` default for the view-toggle group's accessible name
(with no visible title), while an explicit empty string renders no visible or accessible label.
`kind: string = ''`
— a short kind label (e.g. `document`, `code`), shown as a badge next to `label`. `view: 'preview' |
'code' = 'preview'` (reflected) — which slot is currently visible. `versions: ArtifactVersion[] = []`
(attribute: false, each `{ id, label? }`) — the artifact's version history, oldest first; the last
entry is the latest version. Empty/blank ids and later duplicate ids are omitted before navigation, active lookup,
position counts, and restore events. The active entry's optional `label` renders beside its localized
position. `activeVersionId: string | null = null` (attribute `active-version-id`) — the currently
viewed version's id, or `null` for "the latest version." Removing the named version reconciles the
property to `null` without a user-action event, so reinserting that id cannot unexpectedly repin it.
`streaming: boolean = false` (reflected) — whether the artifact is still being generated; sets
`aria-busy` on the body and shows a text indicator (not animated, so it stays legible under reduced
motion). `copyText: string = ''` (attribute `copy-text`) — the text copied to the clipboard by the
copy button; empty hides the button. `downloadSrc: string = ''` (attribute `download-src`) — the
download URL, sanitized through `safeDownloadHref()` (`http:`/`https:`/`blob:` only — narrower than
the media/resource allowlist, which also permits `data:`); an empty value hides the button. The
sanitizer runs at click time, not render time, so a _non-empty but rejected_ URL still renders the
button and simply emits nothing when pressed. The component never navigates on its own: it emits
`lr-download` with the sanitized `src` and leaves the actual download to the host.
`downloadName: string = ''` (attribute `download-name`) — the suggested filename reported in the
`lr-download` event detail.

**Slots:** default — preview-view content (markdown/html-viewer/browser-frame/image). `code` —
code-view content (typically a `lr-code-block`); the preview/code toggle only renders once this
slot has assigned content. Assigning `view='code'` without assigned code content normalizes back to
`preview`, including after mount. `actions` — extra header controls, rendered between the version
navigation and the built-in copy/download buttons.

**Events:** `lr-view-change` (`detail: { view }`), `lr-version-change` (`detail: { versionId }`,
fired when the previous/next navigation moves to a different version), `lr-restore` (`detail: {
versionId }`, fired by the restore-this-version button; mutates nothing itself), `lr-copy`
(`detail: { ok: true, text }`, after the clipboard write fulfills), `lr-error` plus
`lr-copy-error` (`detail: { ok: false, text, reason, error }`) on a localized failure, and
`lr-download` (`detail: { filename, src }`, with the required sanitized download URL).

**CSS parts:** `base`, `header`, `label`, `kind`, `view-toggle` (rendered only once the `code` slot
has content), `view-button` (carries `data-view="preview"` or `data-view="code"`), `version-nav`
(rendered only once `versions` is non-empty), `version-previous`, `version-previous-glyph` (the `‹`
chevron inside `version-previous`, mirrored via `scaleX(-1)` under `:dir(rtl)`), `version-next`,
`version-next-glyph` (the `›` chevron inside `version-next`, mirrored the same way), `version-position`
(the "Version N of M" text), `version-label` (the active version's optional caller-supplied label),
`restore-button` (rendered only while the active version isn't the latest), `actions`, `copy-button`
(rendered only while `copyText` is non-empty), `download-button`
(rendered only while `downloadSrc` is non-empty), `body`, `streaming-indicator` (rendered only while
`streaming`).

**Themeable custom properties:** `--lr-artifact-panel-view-active-bg` (default
`var(--lr-color-brand-quiet)`) and `--lr-artifact-panel-view-active-color` (default
`var(--lr-color-brand)`) — the background and text color of the pressed (active) preview/code toggle
button. Both follow the state-scoped-property convention described under `lr-span-waterfall`: inline
`var()` fallbacks rather than `:host` declarations, so either can be set on the element or on any
ancestor. They exist because `::part(view-button)[aria-pressed='true']` is invalid CSS, leaving the
library-wide brand tokens as the only prior lever.

```html
<lr-artifact-panel label="report.md" kind="document">
  <lr-markdown id="preview"></lr-markdown>
  <lr-code-block slot="code" id="code" language="markdown"></lr-code-block>
</lr-artifact-panel>
<script type="module">
  const panel = document.querySelector("lr-artifact-panel");
  panel.versions = versions;
  panel.querySelector("#preview").content = markdown;
  panel.querySelector("#code").code = markdown;
  panel.addEventListener("lr-restore", (e) => restoreVersion(e.detail.versionId));
</script>
```

## `lr-agent-run`

Top-level shell for one agent run: status, elapsed time, current step, model/cost summary, arbitrary
metrics, and Cancel/Retry actions. Built-in and application-defined lifecycle statuses are supported;
`statusLabels` and `statusVariants` customize unknown status kinds. Named `header` and `summary` slots
replace the corresponding built-in chrome, while `tasks`, `tools`, `reasoning`, `output`, and
`actions` support host-controlled composition.

The nine built-in status kinds are `idle`, `queued`, `collecting`, `running`, `waiting-input`,
`waiting-approval`, `done`, `error`, and `cancelled`; arbitrary application-defined string kinds are
also accepted. Live elapsed time and Cancel are available for `running`, `collecting`,
`waiting-input`, and `waiting-approval`. `queued` is pending rather than actively ticking or
cancelable. Retry is available for `error` and `cancelled`.

**Properties:**

- `run: AgentRun | null = null` (attribute: false) — **`AgentRun`, imported from
  `@aceshooting/lyra-ui/ai`**: `{ id: string; status: AgentStatus; startedAt?:
number; endedAt?: number; model?: string; costEstimate?: number; steps: readonly AgentStep[] }`, where
  `AgentStatus { kind: AgentStatusKind; message?: string }` and `AgentStep { id: string; kind:
string; label: string; status: AgentStatus; startedAt?: number; endedAt?: number }`. All timestamps
  are epoch milliseconds; `AgentStep.kind` is deliberately free-form (an agent's own step taxonomy is
  application-defined) — unlike `LyraSpan['kind']`'s closed union. The record and its nested step
  collection are clone-owned, bounded, and frozen; pass a new object to update it. `null` renders
  the shared `lr-empty` `noData` state. A runtime summary record that has not loaded `steps` yet
  renders with an empty task slot, and a step whose status has not arrived yet renders as pending
- `metrics: readonly AgentRunMetric[] = []` (attribute: false) — `AgentRunMetric { id: string; label: string;
value: string | number; variant?: BadgeVariant }` (exported here), e.g. prompt/completion token
  counts; `variant` tones `[part="metric-value"]` via `data-variant`, including the full
  `neutral`/`brand`/`success`/`warning`/`danger` badge vocabulary. Empty/blank ids and later duplicates are omitted
  before metric rendering
- `formatCost?: (cost: number) => string` (attribute: false) — overrides the default plain
  `Intl.NumberFormat` rendering of `run.costEstimate` fed to the composed `lr-usage-badge`'s
  `cost-text`; use it to add a currency symbol, which this library never assumes on a host's behalf
- `statusLabels: Readonly<Record<string, string>> = {}` (attribute: false) — clone-owned labels for
  _application-defined_ `AgentStatusKind` values; the nine built-in kinds stay localized by Lyra
- `statusVariants: Readonly<Record<string, BadgeVariant>> = {}` (attribute: false) — clone-owned
  badge variants for application-defined kinds; unknown kinds default to `neutral`

The collection and status-map properties above are bounded frozen snapshots. Mutating a previously
assigned array or record has no effect; create and reassign a new value after changes.

- `showCancel: boolean = true` (attribute `show-cancel`) / `showRetry: boolean = true` (attribute
  `show-retry`) — whether the built-in buttons may render at all, still gated by the run's own
  status. Both use a `true`-defaulting string converter, so plain-HTML `show-cancel="false"` works; a
  `?show-cancel=${false}` boolean-attribute binding starting from absent markup does not
- `compact: boolean = false` (reflected) — tighter root padding and header/body gap for dense
  contexts (a run rendered as a row in a list, or in a side panel); same convention as `lr-empty`'s
  `compact`. Purely a density knob: the border and background stay, so reach for
  `frame="plain"` instead when the goal is to drop the chrome entirely
- `frame: LyraFrame = 'card'` (reflected) — container treatment, in the library-wide `frame`
  vocabulary (`'card' | 'plain'`), the same property `<lr-card>` and every other card-shaped
  component carries. `'card'` keeps the bordered, filled, padded box; `'plain'` removes the
  border, background, padding and corner radius, so a run nested inside a host container that
  already draws a border doesn't double it. `plain` wins over `compact` when both are set — there is
  no padding left to tighten. The built-in Cancel/Retry buttons draw their own border and background
  and stay visibly interactive either way. The exported alias `AgentRunAppearance` is retained as a
  name for the same union

**Events:** `lr-cancel` (`detail: CancelEventDetail` = `{ reason?: string }`, from
`@aceshooting/lyra-ui/ai`; `reason` is `undefined` from the built-in button), `lr-run-retry`
(`detail: RetryEventDetail` = `{ attempt: number; messageId?: string }`, same module — `attempt` is
this component's own retry counter, reset when `run.id` changes).

**Slots:** `header` and `summary` replace the corresponding built-in chrome; `tasks`, `tools`,
`reasoning`, `output`, and `actions` are host-controlled composition regions.

**CSS parts:** `base`, `header`, `status`, `status-badge`, `status-message`,
`elapsed` (the live ticker), `elapsed-static` (a terminal run's frozen duration), `summary`, `model`,
`usage`, `current-step`, `current-step-icon`, `current-step-label`, `body`, `tasks`, `tools`,
`reasoning`, `output`, `actions`, `cancel-button`, `retry-button`, `metric-label`, `metric-value`
(carries `data-variant`), `metric` (one metric label/value pair), `empty`.

**Themeable custom properties:** `--lr-agent-run-spin` (default `var(--lr-transition-ambient)`, i.e.
`1.8s ease-in-out`, collapsing to `0.001ms linear` under `prefers-reduced-motion`) — the
current-step icon's rotation duration/timing. `--lr-agent-run-compact-padding` (default
`var(--lr-space-s)`) and `--lr-agent-run-compact-gap` (default `var(--lr-space-s)`) — `[part="base"]`'s
padding, and the gap between its header and body, while `compact`; both are ignored while `compact`
is unset. Like the other density/state properties in this family they are inline `var()` fallbacks at
their point of use rather than `:host` declarations, so either can be set on the element _or on any
ancestor_ — one rule on a run list retunes every compact run inside it.
`--lr-agent-run-background` (default `var(--lr-color-surface)`), `--lr-agent-run-border-color`
(default `var(--lr-color-border)`) and `--lr-agent-run-radius` (default `var(--lr-radius)`) retune
`[part="base"]`'s card chrome without a `::part(base)` override; `frame="plain"` still removes all
three outright.

**Additional API surface:**

- `--lr-agent-run-metric-brand-color` — Brand metric value. Default: `var(--lr-color-brand)`.
- `--lr-agent-run-metric-danger-color` — Danger metric value. Default: `var(--lr-color-danger)`.
- `--lr-agent-run-metric-success-color` — Success metric value. Default: `var(--lr-color-success)`.
- `--lr-agent-run-metric-warning-color` — Warning metric value. Default: `var(--lr-color-warning)`.

## `lr-agent-trace`

Provider-neutral agent/LLM trace view combining span-kind filters, handoff quick-jumps, and a
hierarchical trace tree from one shared `spans` array.

Span views omit whitespace-only IDs and preserve every nonblank business ID exactly, including
surrounding whitespace. The first valid admitted duplicate continues to win.

**Properties:**

- `spans: LyraSpan[] = []` (attribute: false) — the full, unfiltered array; identical contract to
  `lr-trace-tree.spans` (see `lr-span-waterfall` above for the `LyraSpan` shape). Controlled and
  never mutated
- `activeSpanId: string | null = null` (attribute `active-span-id`) — controlled selection forwarded
  into the composed `lr-trace-tree`; also updated locally (and re-emitted as `lr-span-select`) when a
  span is activated from either the tree or the handoff quick-jump list, so it works as a two-way
  binding
- `hiddenKinds: LyraSpan['kind'][] = []` (attribute: false) — span kinds hidden from the tree
  (`'agent' | 'llm' | 'tool' | 'retriever' | 'embedding' | 'other'`). Empty shows every kind;
  pre-settable (e.g. to hide `retriever`/`embedding` by default) and readable back after
  `lr-span-visibility-change`
- `label?: string` — forwarded to the composed `lr-trace-tree`. Omission leaves that tree's own
  `label` unset so it localizes its own default; any supplied string (including `''`) is
  forwarded verbatim
- `showTokens: boolean = false` (attribute `show-tokens`), `showCost: boolean = false` (attribute
  `show-cost`), `showBars: boolean = true` (attribute `show-bars`, renamed from `hideBars` in
  9.0.0 to match the positive polarity of its two siblings above — default inverted so the
  rendered starting state is unchanged: `el.hideBars = true` becomes `el.showBars = false`) — all
  forwarded verbatim

**Events:** `lr-span-select` (`detail: { spanId: string }`), `lr-span-toggle` (`detail: { spanId: string;
expanded: boolean }`), and `lr-span-visibility-change` (`detail: { hiddenKinds:
LyraSpan['kind'][] }`). The internal graph legend's generic `lr-visibility-change` event is
contained; consumers receive this trace-domain event instead.

`spans` is normalized through the same at-most-500-record projection as `<lr-trace-tree>` before
filtering, handoff lookup, and tree rendering. The controlled active span and its ancestor path
reserve positions, and malformed records plus later duplicate ids are omitted, so the composed
surfaces cannot disagree.

**CSS parts:** `base`, `filter` (the composed `lr-graph-legend` filter row, only rendered while
`spans` is non-empty), `handoffs` (the quick-jump list wrapper, only rendered while at least one
visible span has `kind: 'agent'`), `handoff` (one entry — a `<button>` wrapping an
`lr-handoff-divider`, carrying `data-active`), `tree` (the composed `lr-trace-tree`).

**Themeable custom properties:** `--lr-agent-trace-handoff-active-bg` (default
`var(--lr-color-brand-quiet)`) — the background of the active (`activeSpanId`) handoff quick-jump
entry. Same state-scoped-property convention described under `lr-span-waterfall`: an inline `var()`
fallback rather than a `:host` declaration, settable on the element or any ancestor, and it exists
because `::part(handoff)[data-active]` is invalid CSS. The composed tree's own
`--lr-trace-tree-row-active-bg` and `--lr-trace-tree-row-active-color` are separate knobs and
inherit straight through, so restyling both surfaces means setting both — and they carry the
pairing caveat documented under `lr-trace-tree` above: the tree's active-row defaults assume the
active background stays on the same side of the lightness midpoint as the ambient surface, so a
tint that crosses it needs the matching text color set too.

## `lr-context-inspector`

Inspection view of model-call context segments, with token estimates, source citations, redaction
markers, and copy/export controls.

**Properties:**

- `segments: readonly ContextInspectorSegment[] = []` (attribute: false) — `ContextInspectorSegment { id:
string; label: string; text: string; tokens: number; tone?: ContextMeterTone; citation?: Citation;
truncated?: boolean; omittedTokens?: number; redactions?: readonly ContextInspectorRedaction[] }` (exported
  here). One entry per piece of the assembled final prompt (system prompt, retrieved chunk, one
  history turn, …). `text` is the segment's **final** text, exactly as sent to the model
  (post-redaction/post-truncation). `tokens` is the estimated count, fed straight to
  `lr-context-meter`'s segment `value`; `label` feeds both the segment heading and the meter's
  segment label. `citation` is **`Citation` from `@aceshooting/lyra-ui/ai`** and renders an
  `lr-citation-badge` carrying its `sourceId`/`label`. `omittedTokens` is shown in the
  truncation-boundary marker when `truncated` is set. `ContextInspectorRedaction { start: number;
end: number; reason?: string }` marks character ranges within `text` that are redaction
  placeholders; `reason` becomes the marker's `title`/accessible reason, falling back to a localized
  "Redacted". Segment `id` is the stable public identity; empty/blank ids and later duplicates are omitted before
  meter values, rendering, copy/export serialization, and citation events are derived. A valid-id
  streaming segment whose `text` is not available yet remains visible with an empty body and empty
  copy/export text rather than rejecting the render.
- `total: number = 0` — the full token budget `segments` are measured against; passed straight to
  `lr-context-meter.total`
- `label: string = ''` — accessible group name, and the embedded meter's visible caption (e.g.
  "128K context window")
- `exportFormats: readonly LyraExportFormatOption[] = ['json']` (attribute: false) — forwarded to the embedded
  `lr-export-button`; one id renders a plain button, more than one a format-choice menu
- `exportFilename: string = 'context'` (attribute `export-filename`) — download filename (no
  extension) passed to `lr-export-button`

**Events:** `lr-citation-activate` (`detail: { sourceId: string; index: number }`, surfaced by a
segment's embedded `lr-citation-badge`), `lr-citation-open` (`detail: { sourceId: string; index:
number; href?: string }`, the "full preview" signal), `lr-copy` (`detail: { ok: true; text: string }`, from the
embedded `lr-copy-button`), `lr-export` (`detail: { format: string }`, from the embedded
`lr-export-button`), `lr-export-complete` (`detail: { format: string }`, after a non-cancelled export
finishes), `lr-error` (the embedded clipboard write failed), `lr-copy-error` (`detail: { ok: false;
text: string; reason: string; error: unknown }`, the detailed clipboard failure),
`lr-toolbar-actions-change` (no detail, surfaced unchanged when the embedded copy button's logical
toolbar action changes availability or backing trigger),
`lr-export-error` (`detail: { format: ExportFormat; error: unknown }`, the embedded export could not
complete), and the cancelable `lr-show` / `lr-hide` lifecycle events from the embedded export-format
menu. These composed child events surface unchanged; the inspector does not emit duplicate copies.

**CSS parts:** `base`, `toolbar`,
`segments`, `segment`, `segment-header`, `segment-label`, `segment-text`, `segment-tokens`,
`meter` (the embedded `lr-context-meter`), `citation`, `redaction` (one redaction placeholder
marker), `truncation-boundary`, `copy-button`, `export-button`, `empty`.

## `lr-eval-dataset`

Filterable and taggable evaluation-example list with add, remove, import, and export affordances.

**Properties:**

- `examples: readonly EvalExample[] = []` (attribute: false) — `EvalExample { id: string; input: string;
expectedOutput?: string; tags?: readonly string[]; metadata?: Record<string, unknown> }` (exported here).
  It is a dedicated dataset-row shape; no shared agent type models a labeled evaluation row.
  `input`/`expectedOutput` are plain
  strings (not structured payloads), rendered as plain text by every column's `cell()`. Fully
  controlled: add/remove/import/export are all _requests_; the host mutates and passes the array
  back. Empty/blank ids and later duplicate ids are omitted before selection, filtering, mutation requests, and the
  nested grid are derived. Distinct tag chips are ordered with the component's effective-locale
  collation
- `searchable: boolean = false` (reflected) — built-in free-text search over `input`,
  `expectedOutput`, and `tags` (case-insensitive substring)
- `autocomplete: string = ''`, `spellcheck: boolean = true`, `autocapitalize: string = ''`,
  `autoCorrect: string = ''` (attribute `autocorrect`), `inputMode: string = ''` (attribute
  `inputmode`), and `enterKeyHint: string = ''` (attribute `enterkeyhint`) — native
  editing-assistance and virtual-keyboard hints forwarded only to the internal search input while
  `searchable`; empty string leaves the corresponding browser default in effect
- `accept: string = ''` — forwarded to the internal `lr-file-input`'s `accept` (e.g. `'.json,.csv'`);
  empty accepts any type
- `exportFormats: readonly LyraExportFormatOption[] = ['csv', 'json']` (attribute: false) — forwarded to the
  internal `lr-export-button`
- `disabled: boolean = false` (reflected) — disables every add/remove/import/export affordance, e.g.
  while a host-side mutation is still in flight
- `label: string = ''` — purpose-specific accessible name for the nested grid; defaults to the
  localized `evalDatasetLabel`. A host `aria-label` remains on the custom-element host as its
  overall name and is not cloned onto the independently interactive grid

**Events:** `lr-example-select` (`detail: { exampleId: string | null }`),
`lr-example-add-request` (`detail: null` — no payload; `emit()`
normalizes an omitted detail to `null`, never `undefined`), `lr-example-remove-request` (`detail: { exampleId:
string }`), `lr-import-request` (`detail: { files: File[] }`), `lr-export-request` (`detail: {
format: string }`), and the deliberate nested-table pass-through `lr-sort` (`detail: { phase:
'commit'; sortKey: string; sortDir: 'asc' | 'desc' }`). `focus`/`blur` —
re-dispatched (no detail) when the internal search field (only rendered while `searchable`) gains or
loses focus, since native focus neither bubbles nor crosses the shadow boundary.
All three built-in columns are sortable; activating one of their headers produces that commit for
the host to apply to its controlled `examples` array.

**CSS parts:** `base`, `toolbar`, `search`, `search-input`, `search-clear` (replaces the native
search-cancel glyph the component resets; rendered only while the field has text), `tag-filter`,
`grid`, `add-button`, `remove-button`, `import`, `export`.

**Themeable custom properties:** `--lr-eval-dataset-search-min-height` (default `auto`),
`--lr-eval-dataset-search-font-size` (default `inherit`),
`--lr-eval-dataset-search-padding-inline` (default `var(--lr-space-s)`),
`--lr-eval-dataset-search-padding-block` (default `var(--lr-space-xs)`) and
`--lr-eval-dataset-search-radius` (default `var(--lr-radius)`) size the built-in search field; point
the height at a `--lr-form-control-height-*` tier to match it to a themed search field. The trailing
inline gutter is reserved for the overlaid `search-clear` button and is not a knob.

**Known gotchas:**

- Shrinking `examples` out from under live UI state is handled: a `selectedId` that no longer matches
  any row resets to `null`, and an active tag filter that no longer matches any row's `tags` is
  dropped rather than silently matching zero rows forever.
- A search or tag filter that hides the selected row also clears that selection and emits
  `lr-example-select` with `{ exampleId: null }`, so the Remove control never acts on an invisible
  row.

## `lr-eval-result`

Rubric scoring and human-review surface for comparing the runs of one evaluation example.

Composes `lr-table` (the comparison table), `lr-rubric-form` (the review surface), and
`lr-diff-view` (baseline↔selected output diff) rather than re-deriving any of their behavior.
The table uses `label` or the localized purpose-specific evaluation-runs name. A host `aria-label`
on `<lr-eval-result>` remains the overall host name and is not cloned onto the independently
interactive table; use `label` to distinguish several comparison grids on one page.

**Properties:**

- `runs: EvalRunResult[] = []` (attribute: false) — `EvalRunResult { id: string; label: string;
model?: string; promptVersion?: string; output: string; scores?: RubricValue; review?: RubricValue }`
  (exported here). One entry per model or prompt version being compared for a single evaluation
  example. `scores`/`review` use the same `RubricValue` shape `lr-rubric-form` itself reads and
  writes, so a `TableColumn`'s `cell()` accessor and the rubric form's own `value` binding read a
  run's fields with no conversion. Empty/blank ids and later duplicate run ids are omitted before selection, diff,
  grid, and review-event lookup. A valid-id streaming run whose `output` has not arrived yet remains
  selectable and supplies an empty output to the diff
- `columns: TableColumn<EvalRunResult>[] = []` (attribute: false) — plain pass-through to
  `lr-table.columns`, not re-derived here; malformed, empty/blank, and later duplicate column keys are omitted
- `rubricKeys: RubricKey[] = []` (attribute: false) — plain pass-through to `lr-rubric-form.keys`;
  empty/blank and later duplicate rubric keys are omitted
- `label: string = ''` — accessible name for the independently interactive comparison grid;
  falls back to the localized evaluation-runs name when unset
- `selectedRunId: string | null = null` (attribute `selected-run-id`) — the run open for review and the diff's
  **new** side; falls back to `runs[0]?.id` when empty
- `baselineRunId: string | null = null` (attribute `baseline-run-id`) — the run compared against and the
  diff's **old** side; falls back to `runs[0]?.id` when empty
- `reviewSkippable: boolean = false` (attribute `review-skippable`) — shows a Skip control on the
  review form (forwarded to `lr-rubric-form.skippable`)
- `disabled: boolean = false` (reflected) — disables the review form's controls only; the comparison
  grid stays interactive (selecting a run to inspect is not a mutation)

**Events:** `lr-run-activate` (`detail: { runId: string; run: EvalRunResult }`), `lr-review-input` (`detail: { runId:
string; value: RubricValue }`), `lr-review-validity-change` (`detail: { runId: string; valid:
boolean; errors: Record<string, string> }`), `lr-review-submit` (`detail: { runId: string; value:
RubricValue }`), `lr-review-skip` (`detail: { runId: string }`).

**CSS parts:** `base`, `empty`, `grid`, `diff`, `diff-view`,
`diff-labels`, `diff-label-old`, `diff-label-new`, `review`.

## `lr-eval-run`

Evaluation-batch progress view with overall progress and one disclosure per example. Inputs and
outputs may render as Markdown or code, with optional grounding and tool-trace sections.

**Properties:**

- `examples: readonly EvalExampleResult[] = []` (attribute: false) — `EvalExampleResult { id:
string; label?: string; status: AgentStatusPresentation; input: EvalContent; output:
EvalContent; grounding?: GroundingAssessment; citations?: readonly Citation[]; toolTrace?:
readonly ToolTimelineEntry[] }`
  (exported here). `AgentStatusPresentation` extends the shared **`AgentStatus` from
  `@aceshooting/lyra-ui/ai`** with optional caller presentation `{ label?, variant?, terminal?,
active? }`. `label` and `variant` customize application-defined lifecycle display, `message`
  renders as status detail, and `terminal` controls completion counting (falling back to the built-in
  `done`/`error`/`cancelled` map). This preserves the shared run-lifecycle vocabulary rather than
  inventing a parallel pass/fail enum; rubric scoring is `lr-eval-result`'s job, not this one's.
  `EvalContent { text: string; format?: EvalContentFormat; language?: string }` keeps
  each payload's rendering metadata together. `EvalContentFormat = 'markdown' | 'code'` —
  `'markdown'` (the default when unset) renders via `lr-markdown`; `'code'` uses `lr-code-block`
  and consults that payload's `language` for shiki.
  `grounding`/`citations` (both from `@aceshooting/lyra-ui/ai`) compose directly into
  `lr-grounding-summary`'s `assessment`/`citations`, and `toolTrace` directly into
  `lr-tool-timeline.entries` — no adapters. `citations` is consulted only while `grounding` is also
  set; an omitted `grounding` or empty `toolTrace` renders no such section for that example. `label`
  falls back to a localized "Example {index}" (1-based, array order). Controlled and never mutated;
  empty/blank ids and later duplicate example ids are omitted before progress, disclosure state, and correlated child
  events are derived. A valid-id streaming example whose `status`, `input`, or `output` has not
  arrived yet remains visible: status defaults to idle and either missing content payload renders
  as empty Markdown until the host replaces the collection
- `total: number | null = null` — the batch's expected total example count. `null` derives it from
  `examples.length`; set it explicitly while a batch is still streaming and the eventual total is
  already known. An explicit total below the current observed count is raised to `examples.length`,
  so progress never reports an impossible total
- `label: string = ''` — header label and accessible-name source; falls back to a localized
  "Evaluation run"

**Events:** `lr-example-toggle` (`detail: EvalExampleToggleDetail` = `{ exampleId: string; expanded:
boolean }`), `lr-example-citation-select` (`detail: EvalCitationSelectDetail` = `{ exampleId:
string; citation: Citation }` — the nested `lr-grounding-summary`'s own `{ citation }` correlated
with the example it came from, so a host needn't walk the DOM), `lr-example-tool-approval-decide`
(`detail: EvalToolApprovalDetail` = `ToolTimelineApprovalDetail & { exampleId: string }` =
`{ invocationId: string; approved: boolean; args?: unknown; sourceKey?: string; exampleId: string
}`). The approval
event is cancelable: calling `preventDefault()` propagates the veto to the nested
`lr-tool-approval-decide`, preserving its pending dialog and current edited arguments while the
host resolves asynchronous validation. The component also contains and correlates other composed
child events as `lr-example-claim-select` (`{ exampleId, claim }`),
`lr-example-tool-activate` (`{ exampleId, invocationId, sourceKey? }`), and
`lr-example-tool-render-error` (`{ exampleId, invocationId, sourceKey?, toolName, error }`).

**CSS parts:** `base`, `header`,
`header-label`, `progress`, `summary`, `counts`, `count`, `examples`, `example`, `example-summary`,
`example-label`, `example-status`, `example-status-message`, `input-section`, `input`, `output-section`, `output`,
`grounding-section`, `grounding-summary`, `tool-trace-section`, `tool-trace`, `section-heading`,
`live-region`, `empty`.

## `lr-policy-summary`

Read-only list of guardrail, permission, privacy, and tool-policy decisions with accessible
allow, deny, or needs-review explanations.

**Properties:** `decisions: PolicyDecision[] = []` (attribute: false) — `PolicyDecision { id: string;
category: PolicyDecisionCategory; label: string; state: PolicyDecisionState; explanation: string;
detail?: string }`, with `PolicyDecisionCategory = 'guardrail' | 'permission' | 'privacy' | 'tool'`
and `PolicyDecisionState = 'allow' | 'deny' | 'needs-review'` (all three exported here). `label` is
host-supplied data rendered as-is, never localized (a rule name, or a tool name for `category:
'tool'`). `explanation` is an **always-visible** plain-text reason — `state` is never conveyed by
color alone; it tones the badge as `allow` → success, `deny` → danger, `needs-review` → warning,
while the always-visible explanation remains plain text. `detail` is optional richer evidence
(matched rule text, policy id) revealed through
progressive disclosure. Controlled and never mutated — pass a new array to update it.
`id` is the stable decision identity; empty/blank ids and later duplicates are omitted before counts, disclosure state,
and rows are derived.

**Events:** none. Read-only and display-only: this component never mutates a decision and offers no
resolve/acknowledge action — see `lr-tool-approval-dialog`/`lr-confirm-bar` for a real approve/deny
gate.

**CSS parts:** `base`, `empty`, `summary`, `count`, `state-badge`,
`list`, `decision`, `decision-header`, `category`, `label`, `detail`, `explanation`.

**Themeable custom properties:** `--lr-policy-summary-count-allow-color` (default
`var(--lr-color-success)`), `--lr-policy-summary-count-deny-color` (default
`var(--lr-color-danger)`) and `--lr-policy-summary-count-needs-review-color` (default
`var(--lr-color-warning)`) — the text color of each state's count in the summary strip. All three
follow the state-scoped-property convention described under `lr-span-waterfall`: inline `var()`
fallbacks rather than `:host` declarations, so each can be set on the element or on any ancestor.
They exist because `::part(count)[data-state='deny']` is invalid CSS — Shadow Parts forbids an
attribute selector after `::part()` — so retoning one state's count otherwise meant overriding the
library-wide status tokens and repainting every other surface reading them.

## `lr-tool-timeline`

Chronological list of agent tool/function calls composed from tool-call, result, and approval
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?:
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,
  and approval draft is correlated by `(sourceKey, id)`. Entries with empty/blank invocation ids
  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.
  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`
  handed to the per-entry `lr-tool-call-chip`. `retryCount: 2` means the call reached its current
  state on its third try; `0`/omitted renders no retry indicator. `redactedFields` are dotted paths
  within `args`/`result`/`error` to mask in the rendered detail view (e.g.
  `['args.apiKey', 'result.rows.0.ssn']`, or a bare `'args'`/`'result'`/`'error'` to mask a whole
  branch); an unmatched path is a no-op, never an error — and redaction is **never** applied to the
  copy of `args` handed to the approval dialog. While `needsApproval` is `true` and `approved` is
  still `undefined`, activating the entry's chip opens the shared approval dialog instead of merely
  firing the chip's own selection event
- `approvalEditable: boolean = true` (attribute `approval-editable`, reflected) — forwarded to the
  shared approval dialog's `editable`: whether a reviewer may edit an entry's arguments before
  approving. Uses a `true`-defaulting string converter, so plain-HTML `approval-editable="false"`
  works
- `formatTimestamp?: (date: Date) => string` (attribute: false) — overrides the default
  `hour:minute` rendering of each entry's `startedAt`
- `pendingApproval: ToolTimelineApprovalPending = null` (read-only) — `'approve'` or `'deny'` while
  a listener has vetoed `lr-tool-approval-decide` and the timeline is holding the shared dialog for
  host persistence; otherwise `null`

**Methods:** `finalizePendingApproval(): void` closes a held dialog after the host has persisted and
applied its controlled `entries` update (it never mutates `entries` itself). `revertPendingApproval():
void` releases a held dialog after persistence fails, retaining the reviewer’s current argument edit
so they can retry. Both are no-ops when no decision is held.

At most 500 unique entries mount. Open disclosures and the entry under approval review reserve
positions before later ordinary history is omitted; a localized `[part="limit"]` note exposes the
bounded projection. Redaction is deferred until a disclosure opens and memoized while the entry's
payload and path list are unchanged. It is bounded to 100 paths, 64 levels, 10,000 visited nodes,
and 4,096 characters per path; crossing a ceiling masks the affected branch instead of exposing
data or exhausting the page.

**Events:** `lr-tool-activate` (`detail: { invocationId: string; sourceKey?: string }`) for a
non-approval entry activation and `lr-tool-render-error` (`detail: { invocationId: string;
sourceKey?: string; toolName: string; error: unknown }`) for a contained nested renderer failure.
The raw child chip-selection, renderer-error, details, and dialog events do not leak across the
timeline boundary. `lr-tool-approval-decide` (`detail: ToolTimelineApprovalDetail` =
`ToolApprovalEventDetail & { args?: unknown; sourceKey?: string }` = `{ invocationId: string;
approved: boolean; args?: unknown; sourceKey?: string }`, extending the shared detail from
`@aceshooting/lyra-ui/ai`). `args` is present only when
`approved` is `true`, and may differ from what the entry originally proposed — the dialog's inline
edit step can hand back different arguments. A listener that only needs `{ invocationId, approved }`
can ignore it; one actually executing the tool needs it. This is a cancelable veto point:
`preventDefault()` preserves the pending approval dialog and its current inline argument edits
instead of closing/resetting them, sets `pendingApproval`, and requires the host to call
`finalizePendingApproval()` after persistence succeeds or `revertPendingApproval()` after it fails.
A host may instead resolve the decision synchronously by reassigning `entries` (with the entry's
`approved` field set) from within that same listener, without ever calling
`finalizePendingApproval()`: the entry's live state is re-checked immediately after dispatch, so
`pendingApproval` — and the shared dialog's pending presentation — is never set or left set for
an entry that no longer needs a decision.

```ts
timeline.addEventListener("lr-tool-approval-decide", async (event) => {
  event.preventDefault();
  try {
    await persistDecision(event.detail);
    timeline.entries = applyDecision(timeline.entries, event.detail);
    timeline.finalizePendingApproval();
  } catch {
    timeline.revertPendingApproval();
  }
});
```

**CSS parts:** `base`,
`entry`, `entry-marker`, `entry-header`, `entry-timestamp`, `entry-body`, `entry-details`,
`entry-result`, `entry-error`, `entry-retries`, `entry-retries-count`, `entry-retries-label`,
`entry-redacted-indicator`, `entry-approval-status`, `approval-dialog`, `empty`, `limit`.
Each entry's `lr-details` disclosure has a localized contextual summary naming that tool call, not a
repeated bare "Details" label.

**Themeable custom properties:** `--lr-tool-timeline-gap` (default `var(--lr-space-l)`) — vertical
gap between entries; `--lr-tool-timeline-marker-size` (default `var(--lr-size-0-625rem)`) — the
per-entry timeline marker dot's size, which also sets the entry grid's leading column width;
`--lr-tool-timeline-denied-marker-color` (default `var(--lr-color-warning)`) — rail-dot color for a
`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-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"`.

**Additional API surface:**

- `--lr-tool-timeline-running-marker-color` — Running rail dot. Default: `var(--lr-color-brand)`.
- `--lr-tool-timeline-success-marker-color` — Success rail dot. Default: `var(--lr-color-success)`.
- `--lr-tool-timeline-error-marker-color` — Error rail dot. Default: `var(--lr-color-danger)`.
- `--lr-tool-timeline-approved-bg` — Approved badge background. Default: `var(--lr-color-success-quiet)`.
- `--lr-tool-timeline-approved-color` — Approved badge foreground. Default: `var(--lr-color-success)`.
- `--lr-tool-timeline-denied-bg` — Denied badge background. Default: `var(--lr-color-danger-quiet)`.
- `--lr-tool-timeline-denied-color` — Denied badge foreground. Default: `var(--lr-color-danger)`.
- `--lr-tool-timeline-error-color` — Expanded error text. Default: `var(--lr-color-danger)`.

## `lr-agent-eval-dashboard`

Controlled evaluation overview with metric cards, a dependency-free trend chart, and run-status
history. It never launches or scores evaluations.

**Properties:** `metrics: AgentEvaluationMetric[] = []` (attribute: false), where each metric is
`{ id, label, value, format?: 'number' | 'percent' | 'milliseconds' | 'currency' }`; `currency:
string = 'USD'` is the ISO 4217 code used by currency-formatted metrics (invalid codes safely fall
back to USD). `runs:
AgentEvaluationDashboardRun[] = []` (attribute: false), where each run is `{ id, label, status:
AgentStatusValue, metrics?: Record<string, number> }`. `AgentStatusValue` accepts either a compact
`AgentStatusKind` string or an `AgentStatusPresentation` object (`{ kind, message?, label?,
variant?, terminal?, active? }`), preserving explicit caller labels/messages and badge variants.
`metricId: string | null = null`; `label?: string` — omission localizes the heading while an
explicit empty string renders no heading/name; `showChart: boolean = true`; `chartHeight: string =
'220px'`; `maxRenderedRuns: number = 100` (attribute `max-rendered-runs`, clamped to 1–500) bounds
both the run list and the chart projection.
Empty metric/run ids are omitted and later duplicates use deterministic first-occurrence-wins
normalization before cards, selectors, chart series, row lookup, and emitted events are derived.

**Events:** `lr-metric-change` (`{ metricId }`, emitted when a metric selector is activated) and
`lr-run-activate` (`{ runId, run }`).

**CSS parts:** `base`, `heading`, `metrics`, `metric`, `chart`, `runs`, `runs-heading`, `run`,
`run-label`, `run-meta`, `run-status`, `run-status-message`, `empty`.

**Additional API surface:**

- `--lr-agent-eval-dashboard-active-border` — Active metric border. Default: `var(--lr-color-brand)`.
- `--lr-agent-eval-dashboard-active-background` — Active metric background. Default: `var(--lr-color-brand-quiet)`.

## `lr-approval-queue`

Keyboard-accessible queue of pending tool calls backed by one reusable `lr-tool-approval-dialog`.
It never executes tools or persists decisions.

**Properties:** `requests: ToolApprovalRequest[] = []` (attribute: false), where each request is
`{ id, toolName, args, status?: 'pending' | 'approved' | 'denied' }`;
`selectedInvocationId: string | null = null` (attribute `selected-invocation-id`);
`open: boolean = false`; `editable: boolean = true`; `label?: string` — omission localizes the
heading while an explicit empty string renders no heading/name. Later duplicate request
ids and empty/blank ids are omitted before count, selection, dialog lookup, or decision events are
derived.

**Events:** `lr-approval-select` (`{ invocationId }`), `lr-approval-decision` (`{ invocationId,
approved, args? }`), and `lr-approval-close` (`{ invocationId, reason }`).
`lr-approval-decision` is cancelable; calling `preventDefault()` vetoes the nested approve/deny
request and keeps the decision dialog pending.

Resolved rows (`approved`/`denied`) are never actionable. Replacing `requests` reconciles stale
selection and dialog state before another activation can use it; a request that disappears or is
resolved while open closes the dialog, and reentrant host updates during selection cannot reopen a
stale request.

**CSS parts:** `base`, `heading-row`, `heading`, `count`, `list`, `request`, `request-info`,
`tool-name`, `request-id`, `status`, `empty`. The `[part='request']` row matching
`selectedInvocationId`
carries both `data-selected="true"` (the styling hook) and `aria-current="true"` (the semantic
state), so the selection is announced, not merely painted. Other request rows explicitly render
`data-selected="false"` and `aria-current="false"`.

**Additional API surface:**

- `--lr-approval-queue-selected-border` — Selected request border. Default: `var(--lr-color-brand)`.

## `lr-mcp-app`

Sandbox host for executable MCP App-style resources. Inline documents run in a unique-origin iframe
with a trusted CSP meta placed before every caller-controlled HTML token; comment and script-text
head decoys therefore cannot bypass the policy. Remote documents accept only relative or HTTP(S)
URLs and use a fixed `no-referrer` policy; active-document `data:` and `blob:` URLs are rejected.
The frame can only request tool calls, messages, navigation, logs, and clamped resizing through
typed events. Capabilities are denied unless explicitly enabled in `resource.permissions`.

**Properties:**

- `resource: McpAppResource | null = null` (attribute: false) — a non-empty logical `uri` plus
  exactly one executable source: `{ uri, html, src?: never, ... }` for inline content or
  `{ uri, src, html?: never, ... }` for a relative/HTTP(S) document URL. Shared optional fields are
  `title`, `csp`, `permissions`, and `metadata`. Runtime validation enforces the non-empty identity,
  exact-one-source invariant, and remote URL scheme even for untyped JavaScript callers. CSP domain
  arrays accept HTTP(S) origins only. The resource and nested CSP arrays are clone-owned, bounded,
  and frozen; reassign a new resource record after changes. Permissions are optional booleans for
  camera, microphone, geolocation, clipboard read, and clipboard write.
- `height: number = 320`, `maxHeight: number = 800` (attribute `max-height`) — requested and maximum
  frame heights in pixels; runtime values and resize requests clamp to 120–10,000.
- `label: string = ''`; `accessibleLabel: string | null = null` (attribute `aria-label`). A present
  host `aria-label` stays on the custom-element host as its overall name instead of being cloned
  inward. The iframe title uses `label`, then resource title, then the localized fallback; an
  explicitly empty host label does not suppress those fallbacks, so the executable frame remains
  named. A direct non-empty `accessibleLabel` property value names the frame when no host attribute
  is present.

**Methods:** `postHostContext(context: unknown): void` posts host state into the active frame;
`postToolResult(requestId: string, options: McpAppToolResultOptions): void` resolves a prior tool
request with exactly one of `{ frameGeneration, result }` or `{ frameGeneration, error }`. Missing,
stale, or ambiguous correlation fails closed. Both methods are no-ops before a frame exists.

**Exported types:** `McpAppResource`, `McpAppCsp`, `McpAppPermissions`,
`McpAppToolCallDetail`, `McpAppToolResultOptions`, and `LyraMcpAppEventMap`.

**Events:** `lr-mcp-ready` (`{ uri }`), `lr-mcp-tool-call`
(`{ requestId?, name, args, frameGeneration }`), `lr-mcp-send-message` (`{ message }`),
`lr-mcp-open-link` (`{ href }`), `lr-mcp-log`
(`{ level, value }`), and `lr-mcp-resize` (`{ height }`). These are host-authorized requests; the
component does not execute tools, send messages, or navigate itself.

Changing `resource`, adopting the host into another document, or reconnecting it mounts a fresh
iframe/window generation; messages from the prior `contentWindow` are ignored even when two
opaque-origin inline documents otherwise look alike.

The host-to-frame direction is correlated the same way. `lr-mcp-tool-call`'s
`detail.frameGeneration` is an opaque id for the frame generation that raised the request; passing
it in `postToolResult()`'s required options makes the component drop a reply whose generation no
longer matches the mounted frame. That matters because a tool call is inherently asynchronous — the
host does real work before replying, and a conversation UI can replace or reconnect `resource` on
the same element meanwhile. An uncorrelated reply would otherwise reach a completely unrelated app.

```ts
element.addEventListener("lr-mcp-tool-call", async (event) => {
  const { requestId, name, args, frameGeneration } = event.detail;
  if (!requestId) return;
  const result = await runTool(name, args);
  element.postToolResult(requestId, { frameGeneration, result });
});
```

Changing only `height`/`maxHeight` updates frame geometry without returning an already-ready frame
to its loading state. The initial host context reports `effectiveLocale`, so inherited/document
locale and per-element locale overrides follow the same precedence as the rest of Lyra UI.

Loading and unavailable messages remain ordinary visible text. After the initial baseline, adding
or replacing a valid resource announces the localized loading state through the shared polite
light-DOM sink; changing from an available resource to no resource announces unavailability through
the shared assertive sink. Initial and reconnect renders stay silent.

**CSS parts:** `base`, `frame`, `loading`, `error`.

**Slots:** none. **Optional peer deps:** none.

```ts
import "@aceshooting/lyra-ui/components/agent-tools/mcp-app/mcp-app.js";
```

## `lr-prompt-studio`

Prompt-development workbench for ordered role messages, `{{variable}}` substitution, saved
versions, resolved preview, and save/run intents. Message and variable edits emit a cancelable
`lr-change` proposal carrying their complete next state before updating the component's current
arrays; persistence and execution remain host-owned.

Variable values resolve recursively; undefined and cyclic placeholders remain literal within preview
bounds. Each preview projection permits at most 64 nested variable resolutions, 10,000 placeholder
substitutions, and 1,048,576 UTF-16 code units each of aggregate resolved message output and
aggregate memoized intermediate text. Limits are checked before constructing oversized text.
Exceeding a limit replaces the resolved preview with a localized visible fallback; raw messages,
variables, editing and save/run payloads are unchanged.

**Properties:** `messages: readonly PromptStudioMessage[] = []` and
`variables: readonly PromptStudioVariable[] = []` are property-only editor state: user edits emit a
cancelable `lr-change` before updating the current arrays, while the host remains responsible for
persistence.
`versions: readonly PromptStudioVersion[] = []` is a property-only host-controlled input;
empty/blank message and version ids are omitted and later duplicates use deterministic first-wins
identity before rendering, editing, focus, selection, and events;
runtime `null`/non-array values for any of the three not-yet-loaded collections render as empty;
`selectedVersionId: string | null = null` (attribute `selected-version-id`); `label: string = ''`;
`heading: string = ''` — visible toolbar heading, falling back to the localized Prompt Studio
label when unset;
`running: boolean = false`, `disabled: boolean = false`, and `reorderable: boolean = false`
(all reflected). `reorderable` adds native move-up/move-down controls for each message. A move first
emits a cancelable request, so a host can veto it while persisting the proposed order and later
assign the accepted `messages` array. Native prose-editing assistance is forwarded to every message
textarea and variable input through `spellcheck: boolean = true`, `autocapitalize: string = ''`,
and `autoCorrect: string = ''` (attribute `autocorrect`); `wrap: PromptStudioWrap = 'soft'` applies
to message textareas only.

**Exported types:** `PromptStudioRole = ChatMessageRole | 'tool'`, where the shared
`ChatMessageRole` is `'system' | 'user' | 'assistant'`;
`PromptStudioMessage = { id, role, content, name? }`; `PromptStudioVariable = { name, value,
description? }`; `PromptStudioVersion = { id: string; label: string; messages:
readonly PromptStudioMessage[]; variables?: readonly PromptStudioVariable[]; createdAt?: string }`; and
`PromptStudioState = { messages, variables }`; `PromptStudioWrap = 'hard' | 'soft' | 'off'`; and
`PromptStudioMessageReorderDetail = { messages, messageId, fromIndex, toIndex }`.

**Events:** cancelable `lr-change` (`{ messages, variables }`, the complete proposed next state,
fired before it is applied — prevent it to keep the current state unchanged), `lr-run`, `lr-save`
(both carry complete messages/variables); `lr-version-select` (`{ version }`); and cancelable
`lr-message-reorder` (`{ messages, messageId, fromIndex, toIndex }`) before an accepted move
updates the component and emits `lr-change`. Prevent `lr-message-reorder` to keep the current
order; the listener may persist `detail.messages` and assign it back when ready. Plus `focus` and
`blur` (no detail), re-dispatched
from the host — bubbling and composed — whenever a message textarea or a variable input gains or
loses focus. They exist because the native `focus`/`blur` events neither bubble nor cross the shadow
boundary, so without the re-dispatch an
`editor.addEventListener('focus', …)` would never fire at all. They are re-dispatches of real
focus movement, not a synthetic host-level focus signal: moving between two fields inside the
studio emits a `blur` and then a `focus`.

**CSS parts:** `base`, `toolbar`, `editor`, `messages`, `message`, `message-role`,
`message-content`, `message-actions`, `move-message-up`, `move-message-down`, `remove-message`,
`add-message`, `variables`, `variable`, `versions`, `version`, `preview`, `save`, `run`.

Each `message-content` textarea deliberately keeps native vertical resizing. Prompt Studio exposes
neither a configurable `resize` surface nor auto-grow behavior; use a dedicated editor when either
is required.

Each message's role select and content editor has a localized contextual accessible name containing
its one-based message index and purpose (plus the current role for content), so repeated controls do
not collapse to indistinguishable generic names.

**Slots:** none. **Optional peer deps:** none.

```ts
import "@aceshooting/lyra-ui/components/agent-tools/prompt-studio/prompt-studio.js";
```

**Additional API surface:**

- `--lr-prompt-studio-field-hover-border` — Enabled field hover border. Default: `var(--lr-color-brand)`.
- `--lr-prompt-studio-version-selected-border` — Selected version border. Default: `var(--lr-color-brand)`.
- `--lr-prompt-studio-version-selected-bg` — Selected version background. Default: `var(--lr-color-brand-quiet)`.
- `--lr-prompt-studio-version-selected-color` — Selected version foreground. Default: `var(--lr-color-text)`.
- `--lr-prompt-studio-version-selected-hover-bg` — Selected version hover background. Default: `color-mix(in oklab, var(--lr-color-brand-quiet), var(--lr-color-mix-partner) var(--lr-color-mix-hover))`.

## `lr-json-schema-viewer`

Recursive JSON Schema inspector with property/branch selection, required and constraint display,
validation issues, `$ref` visibility, composition branches, cycle protection, and a depth ceiling.
It intentionally does not fetch remote references or validate values.

**Properties:** clone-owned, bounded, frozen `schema: JsonSchemaNode | null = null` and
`issues: readonly SchemaValidationIssue[] = []` (attribute: false); reassign a new schema record or
issue array after changes. `selectedPath: string | null = null` (attribute `selected-path`) —
`null` means no selection, while the empty string is the valid JSON Pointer for the schema root;
`maxDepth: number = 20` (attribute `max-depth`, clamped to 100); `label: string = ''`.

**Exported types:** `JsonSchemaNode` covers `$ref`, type/title/description, properties/items,
readonly required/enum/examples and oneOf/anyOf/allOf collections, and const/default while preserving unknown schema
keywords. `SchemaValidationIssue = { path: string; message: string; severity?: 'error' | 'warning'
| 'info' }`. At runtime, a Swagger-style boolean or string `required` keyword is treated as no
JSON-Schema required-property list instead of rejecting the entire tree.

**Events:** `lr-schema-select` (`{ schemaPath, schema }`, with an RFC 6901-style JSON Pointer).

**CSS parts:** `base`, `tree`, `node`, `node-selected`, `node-trigger`, `name`, `type`, `required`,
`description`, `constraints`, `issue`, `limit`, `issue-limit`, `empty`. `issue-limit` is the
localized resource-ceiling status shown when caller-supplied validation issues exceed the rendered
issue cap.

`[part='issue']` carries `data-severity` and each severity has its own styling: `error` reads the
danger tokens, `warning` the warning tokens, and `info` its own pair —
`--lr-schema-viewer-info-border` (default `var(--lr-color-brand)`) and `--lr-schema-viewer-info-bg`
(default `var(--lr-color-brand-quiet)`). Brand rather than a dedicated info palette because this
library has no `--lr-color-info-*` token; before these existed an `info` issue rendered identically
to an `error`, which read as a false alarm. Both are inline `var()` fallbacks at their point of use,
so either can be set on the element or on any ancestor — `::part(issue)[data-severity='info']` is
invalid CSS, so this is the only way to recolor one severity without touching the others.

**Themeable custom properties:** `--lr-schema-viewer-max-indent` (default `var(--lr-size-12rem)`)
caps visual nesting indentation while preserving complete JSON Pointer paths;
`--lr-schema-viewer-info-border`, `--lr-schema-viewer-info-bg` (see above); otherwise shared tokens
only.

Rendering is capped independently at 500 schema nodes and 500 validation issues; `limit` and
`issue-limit` show their respective truncation as ordinary, non-live status text. Newly reaching or
changing either ceiling after the initial baseline appends the localized message to the shared
polite light-DOM announcement sink; initial and reconnect renders stay silent. Issues are indexed by
path once before recursive rendering instead of rescanning the full input for every node. Cycles stop
at the repeated node rather than recursing. **Slots:** none. **Optional peer deps:** none.

```ts
import '@aceshooting/lyra-ui/components/lr-json-schema-viewer.js';
```

**Additional API surface:**

- `part="limit"` — Resource-ceiling status shown when additional nodes are omitted.
- `part="issue-limit"` — Resource-ceiling status shown when additional validation issues are omitted.
- `--lr-schema-viewer-selected-border` — Selected node branch. Default: `var(--lr-color-brand)`.
- `--lr-schema-viewer-error-border` — Error issue border. Default: `var(--lr-color-danger)`.
- `--lr-schema-viewer-error-bg` — Error issue background. Default: `var(--lr-color-danger-quiet)`.
- `--lr-schema-viewer-warning-border` — Warning issue border. Default: `var(--lr-color-warning)`.
- `--lr-schema-viewer-warning-bg` — Warning issue background. Default: `var(--lr-color-warning-quiet)`.

## `lr-subagent-panel`

Controlled nested-agent hierarchy with lifecycle badges, task/model context, guarded progress,
selection, cancel, and retry intents. `SubagentRun.parentId` creates nesting; cycles and orphan
parents remain renderable instead of recursing forever.

**Properties:** `runs: SubagentRun[] = []` (attribute: false);
`selectedRunId: string | null = null` (attribute `selected-run-id`); `label?: string` — an
accessible-name override for the `role="tree"` element, where omission reads back `undefined` and
localizes the default while any supplied string, including `''`, renders verbatim; `compact: boolean
= false` (reflected) — tighter run-row padding/gaps and smaller task/model text, the same density
convention `lr-task-list`/`lr-stack-trace`/`lr-thinking-panel`/`lr-terminal` already pair with
`frame`; purely a density knob, since each run's own border stays, so reach for `frame="plain"` to
drop the chrome entirely; `frame: LyraFrame = 'card'` (reflected) — container treatment for each run
row, in the library-wide `frame` vocabulary (`'card' | 'plain'`). `'card'` keeps each run's own
border/radius; `'plain'` drops it, for a transcript or message-bubble context that already draws its
own border around a nested `<lr-subagent-panel>` and would otherwise double it.
`SubagentRun = { id: string; parentId?: string; label: string; status: AgentStatusKind; task?:
string; model?: string; readonly progressRatio?: number; startedAt?: number; endedAt?: number;
metadata?: Record<string, unknown> }`. `progressRatio` represents completion from `0` to `1`,
inclusive.
Empty/blank run ids are omitted and later duplicate ids are ignored before hierarchy, focus,
counts, selection, and events.

**Events:** `lr-run-activate` (`{ runId, run }`), `lr-cancel` (`{ runId }`), and
`lr-run-retry` (`{ runId }`).

**CSS parts:** `base`, `list`, `run`, `run-selected`, `run-row`, `run-trigger`, `label`, `status`,
`task`, `model`, `progress`, `actions`, `cancel`, `retry`, `limit`, `empty`.

At most 500 runs render, and visual indentation is capped at 12 levels while ARIA hierarchy keeps
the logical depth. The visible `limit` text is ordinary and non-live; newly reaching or changing the
run ceiling after the initial baseline appends the localized message to the shared polite light-DOM
announcement sink, while initial and reconnect renders stay silent. The roving treeitem accepts
Enter/Space as well as pointer activation for `lr-run-activate`; cancel/retry action names include the
run label so repeated row actions remain distinguishable to assistive technology. Progress is finite
and clamped. **Slots:** none.
**Optional peer deps:** none.

```ts
import "@aceshooting/lyra-ui/components/agent-tools/subagent-panel/subagent-panel.js";
```

**Additional API surface:**

- `part="limit"` — Resource-ceiling status shown when additional runs are omitted.
- `--lr-subagent-panel-selected-border` — Selected run border. Default: `var(--lr-color-brand)`.
- `--lr-subagent-panel-progress-track` — Progress track. Default: `var(--lr-color-border)`.
- `--lr-subagent-panel-progress-fill` — Progress fill. Default: `var(--lr-color-brand)`.
- `--lr-subagent-panel-compact-trigger-padding` — `[part="run-trigger"]` padding while `compact`.
  Default: `var(--lr-space-2xs) var(--lr-space-s)`.
- `--lr-subagent-panel-compact-trigger-gap` — Gap between `[part="run-trigger"]`'s
  label/status/task/model/progress while `compact`. Default: `var(--lr-space-2xs)`.
- `--lr-subagent-panel-compact-font-size` — `[part="task"]`/`[part="model"]` font size while
  `compact`. Default: `var(--lr-font-size-2xs)`.
- `--lr-subagent-panel-compact-action-padding` — `[part="cancel"]`/`[part="retry"]` padding while
  `compact`. Default: `var(--lr-space-2xs)`.
- `--lr-subagent-panel-background` — Resting fill of each run row's trigger and action buttons.
  Hover and press follow `--lr-subagent-panel-hover-background`, so retune both together.
  Default: `var(--lr-color-surface)`.
- `--lr-subagent-panel-hover-background` — Hovered fill of each run row's trigger and action
  buttons. The pressed fill is this value mixed a further `--lr-color-mix-active` toward
  `--lr-color-mix-partner`, so retuning hover carries the press with it.
  Default: `var(--lr-color-surface-raised)`.
- `--lr-subagent-panel-border-color` — Each run row's border and its action divider. A selected row
  still uses `--lr-subagent-panel-selected-border`. Default: `var(--lr-color-border)`.
- `--lr-subagent-panel-radius` — Each run row's corner radius; `frame="plain"` still squares them.
  Default: `var(--lr-radius)`.

## Consumer integration notes

- **Tool selection:** `lr-tool-select-dialog` inspects at most 10,000 supplied positions. A usable
  row is a plain or null-prototype record with nonblank string `id` and `name`; malformed rows are
  omitted and the first usable duplicate wins. `selectedToolIds` independently retains its first
  nonblank ids, including ids that are not presently offered, and `lr-change` carries that bounded
  canonical sequence.
- **Parameter schemas:** `lr-tool-param-form` recursively admits only own-data fields from arrays,
  plain records, and null-prototype records. Unsafe branches are omitted while safe siblings remain;
  they cannot enter serialized values or `FormData`. A malformed enum omits only that field and
  leaves schema-shape validity false. Its semantic owner renders `aria-invalid="true"` only after
  interaction or `reportValidity()` when invalid and not barred from validation; otherwise it
  explicitly renders `"false"`.
- **Localized metrics:** `lr-span-waterfall` and `lr-test-results` format visual and spoken metrics
  with the effective locale, joining row and toggle labels with the localized accessible-label
  separator.
- **Terminal styling:** `--lr-terminal-surface-color` defaults to
  `var(--lr-color-surface-raised)` for the card frame and inverse ANSI fallback foreground; a plain
  frame stays transparent. `--lr-terminal-toolbar-button-hover-bg`,
  `--lr-terminal-toolbar-button-active-bg`, `--lr-terminal-line-hover-bg`, and
  `--lr-terminal-line-active-bg` independently theme toolbar-button and ordinary-line hover/pressed
  states; highlighted lines retain their tone-specific backgrounds.
- **Approval lifecycle:** when a selected pending request disappears or resolves,
  `lr-approval-close.detail.reason` can be `'request-invalidated'`; selection and open state clear
  before that noncancelable event.
- **Tool result slots:** explicitly assigning `slot=""` is default detail content and can enable the
  tool-call tooltip; named slots do not. A renderer's synchronous `reportStatus()` applies only to
  its current render attempt, so late or stale reports are ignored.
- **Trace visibility:** `lr-agent-trace` contains the nested graph legend's proposal event. Its
  public `lr-span-visibility-change` event reports the resulting `{ hiddenKinds }` state. If an
  integration exposes the nested `lr-graph-legend`, attach a veto listener to that legend rather
  than to the wrapper.
- **Schema viewer input:** `lr-json-schema-viewer` uses a bounded descriptor-safe own-data snapshot.
  It recurses through arrays, plain records, and null-prototype records only; unsupported or unsafe
  branches are omitted while valid siblings and the valid prefix remain available.

## Exported TypeScript contracts

These named interfaces and helper signatures are available to typed integrations. They are grouped by capability so the component sections above can stay focused.

- **`components-agent-tools-activity-feed-activity-feed-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/agent-tools/activity-feed/activity-feed.class.js`.
  `ActivityEntry {
    id: string;
    text: string;
    icon?: string;
    timestamp?: Date | string;
    variant?: LyraVariant;
    data?: unknown;
  }`
  `data` is an opaque caller payload, never read or rendered by `<lr-activity-feed>` itself. It is
  carried through the owned `entries` snapshot and handed back to `renderText` **by reference,
  never deep-cloned** — the whole point of the field is that a consumer can look up richer
  per-entry context without re-scanning its own source array by id on every render.
  Import: `@aceshooting/lyra-ui/components/agent-tools/activity-feed/activity-feed.class.js`.
  `ActivityFeedFollowChangeDetail {
    following: boolean;
  }`
  Import: `@aceshooting/lyra-ui/components/agent-tools/activity-feed/activity-feed.class.js`.
  `ActivityFeedToggleDetail {
    expanded: boolean;
  }`

- **`components-agent-tools-agent-eval-dashboard-agent-eval-dashboard-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/agent-tools/agent-eval-dashboard/agent-eval-dashboard.class.js`.
  `AgentEvaluationDashboardRun {
    readonly id: string;
    readonly label: string;
    readonly status: AgentStatusValue;
    readonly metrics?: Readonly<Record<string, number>>;
  }`
  Import: `@aceshooting/lyra-ui/components/agent-tools/agent-eval-dashboard/agent-eval-dashboard.class.js`.
  `AgentEvaluationMetric {
    readonly id: string;
    readonly label: string;
    readonly value: number;
    readonly format?: EvaluationMetricFormat;
  }`

- **`components-agent-tools-agent-run-agent-run-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/agent-tools/agent-run/agent-run.class.js`.
  `AgentRunMetric {
    id: string;
    label: string;
    value: string | number;
    variant?: BadgeVariant;
  }`

- **`components-agent-tools-agent-status-presentation-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/agent-tools/agent-status-presentation.js`.
  `agentStatusKind(status: AgentStatusValue): AgentStatusKind`
  Import: `@aceshooting/lyra-ui/components/agent-tools/agent-status-presentation.js`.
  `agentStatusLabel(status: AgentStatusValue): string | undefined`
  Import: `@aceshooting/lyra-ui/components/agent-tools/agent-status-presentation.js`.
  `agentStatusMessage(status: AgentStatusValue): string | undefined`
  Import: `@aceshooting/lyra-ui/components/agent-tools/agent-status-presentation.js`.
  `AgentStatusPresentation extends AgentStatus {
    label?: string;
    variant?: BadgeVariant;
    terminal?: boolean;
    active?: boolean;
    // Inherited from AgentStatus.
    kind: AgentStatusKind;
    message?: string;
  }`
  Import: `@aceshooting/lyra-ui/components/agent-tools/agent-status-presentation.js`.
  `agentStatusVariant(status: AgentStatusValue, fallback: BadgeVariant): BadgeVariant`
  Import: `@aceshooting/lyra-ui/components/agent-tools/agent-status-presentation.js`.
  `isAgentStatusActive(status: AgentStatusValue): boolean`
  Import: `@aceshooting/lyra-ui/components/agent-tools/agent-status-presentation.js`.
  `isAgentStatusTerminal(status: AgentStatusValue): boolean`

- **`components-agent-tools-approval-queue-approval-queue-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/agent-tools/approval-queue/approval-queue.class.js`.
  `ToolApprovalRequest {
    id: string;
    toolName: string;
    args: unknown;
    status?: ApprovalRequestStatus;
  }`

- **`components-agent-tools-approval-state-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/agent-tools/approval-state.js`.
  `approvalAction(decision: ApprovalDecision): ApprovalAction`
  Import: `@aceshooting/lyra-ui/components/agent-tools/approval-state.js`.
  `approvalDecision(action: ApprovalAction): ApprovalDecision`

- **`components-agent-tools-artifact-panel-artifact-panel-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/agent-tools/artifact-panel/artifact-panel.class.js`.
  `ArtifactVersion {
    id: string;
    label?: string;
  }`

- **`components-agent-tools-browser-frame-browser-frame-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/agent-tools/browser-frame/browser-frame.class.js`.
  `BrowserPing {
    id: string;
    x: number;
    y: number;
    kind: 'click' | 'type' | 'scroll' | 'move';
  }`

- **`components-agent-tools-commit-card-commit-card-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/agent-tools/commit-card/commit-card.class.js`.
  `CommitFileChange {
    path: string;
    additions: number;
    deletions: number;
    status?: GitStatus;
  }`

- **`components-agent-tools-context-inspector-context-inspector-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/agent-tools/context-inspector/context-inspector.class.js`.
  `ContextInspectorRedaction {
    start: number;
    end: number;
    reason?: string;
  }`
  Import: `@aceshooting/lyra-ui/components/agent-tools/context-inspector/context-inspector.class.js`.
  `ContextInspectorSegment {
    id: string;
    label: string;
    text: string;
    tokens: number;
    tone?: ContextMeterTone;
    citation?: Citation;
    truncated?: boolean;
    omittedTokens?: number;
    redactions?: readonly ContextInspectorRedaction[];
  }`

- **`components-agent-tools-eval-dataset-eval-dataset-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/agent-tools/eval-dataset/eval-dataset.class.js`.
  `EvalExample {
    id: string;
    input: string;
    expectedOutput?: string;
    tags?: readonly string[];
    metadata?: Record<string, unknown>;
  }`

- **`components-agent-tools-eval-result-eval-result-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/agent-tools/eval-result/eval-result.class.js`.
  `EvalRunResult {
    readonly id: string;
    readonly label: string;
    readonly model?: string;
    readonly promptVersion?: string;
    readonly output: string;
    readonly scores?: RubricValue;
    readonly review?: RubricValue;
  }`

- **`components-agent-tools-evaluation-run-evaluation-run-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/agent-tools/evaluation-run/evaluation-run.class.js`.
  `EvalCitationSelectDetail {
    exampleId: string;
    citation: Citation;
  }`
  Import: `@aceshooting/lyra-ui/components/agent-tools/evaluation-run/evaluation-run.class.js`.
  `EvalClaimSelectDetail {
    exampleId: string;
    claim: GroundedClaim;
  }`
  Import: `@aceshooting/lyra-ui/components/agent-tools/evaluation-run/evaluation-run.class.js`.
  `EvalContent {
    text: string;
    format?: EvalContentFormat;
    language?: string;
  }`
  Import: `@aceshooting/lyra-ui/components/agent-tools/evaluation-run/evaluation-run.class.js`.
  `EvalExampleResult {
    id: string;
    label?: string;
    status: AgentStatusPresentation;
    input: EvalContent;
    output: EvalContent;
    grounding?: GroundingAssessment;
    citations?: readonly Citation[];
    toolTrace?: readonly ToolTimelineEntry[];
  }`
  Import: `@aceshooting/lyra-ui/components/agent-tools/evaluation-run/evaluation-run.class.js`.
  `EvalExampleToggleDetail {
    exampleId: string;
    expanded: boolean;
  }`
  Import: `@aceshooting/lyra-ui/components/agent-tools/evaluation-run/evaluation-run.class.js`.
  `EvalToolActivateDetail extends ToolTimelineActivateDetail {
    exampleId: string;
    // Inherited from ToolTimelineActivateDetail.
    invocationId: string;
    sourceKey?: string;
  }`
  Import: `@aceshooting/lyra-ui/components/agent-tools/evaluation-run/evaluation-run.class.js`.
  `EvalToolApprovalDetail extends ToolTimelineApprovalDetail {
    exampleId: string;
    // Inherited from ToolTimelineApprovalDetail.
    args?: unknown;
    sourceKey?: string;
    invocationId: string;
    approved: boolean;
  }`
  Import: `@aceshooting/lyra-ui/components/agent-tools/evaluation-run/evaluation-run.class.js`.
  `EvalToolRenderErrorDetail extends ToolTimelineRenderErrorDetail {
    exampleId: string;
    // Inherited from ToolTimelineRenderErrorDetail.
    toolName: string;
    error: unknown;
    invocationId: string;
    sourceKey?: string;
  }`

- **`components-agent-tools-mcp-app-mcp-app-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/agent-tools/mcp-app/mcp-app.class.js`.
  `McpAppCsp {
    readonly connectDomains?: readonly string[];
    readonly resourceDomains?: readonly string[];
    readonly frameDomains?: readonly string[];
  }`
  Import: `@aceshooting/lyra-ui/components/agent-tools/mcp-app/mcp-app.class.js`.
  `McpAppPermissions {
    readonly camera?: boolean;
    readonly microphone?: boolean;
    readonly geolocation?: boolean;
    readonly clipboardRead?: boolean;
    readonly clipboardWrite?: boolean;
  }`
  Import: `@aceshooting/lyra-ui/components/agent-tools/mcp-app/mcp-app.class.js`.
  `McpAppToolCallDetail {
    requestId?: string;
    name: string;
    args: unknown;
    frameGeneration: number;
  }`

- **`components-agent-tools-policy-summary-policy-summary-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/agent-tools/policy-summary/policy-summary.class.js`.
  `PolicyDecision {
    id: string;
    category: PolicyDecisionCategory;
    label: string;
    state: PolicyDecisionState;
    explanation: string;
    detail?: string;
  }`

- **`components-agent-tools-prompt-studio-prompt-studio-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/agent-tools/prompt-studio/prompt-studio.class.js`.
  `PromptStudioMessage {
    id: string;
    role: PromptStudioRole;
    content: string;
    name?: string;
  }`
  Import: `@aceshooting/lyra-ui/components/agent-tools/prompt-studio/prompt-studio.class.js`.
  `PromptStudioMessageReorderDetail {
    readonly messages: readonly PromptStudioMessage[];
    readonly messageId: string;
    readonly fromIndex: number;
    readonly toIndex: number;
  }`
  Import: `@aceshooting/lyra-ui/components/agent-tools/prompt-studio/prompt-studio.class.js`.
  `PromptStudioState {
    messages: PromptStudioMessage[];
    variables: PromptStudioVariable[];
  }`
  Import: `@aceshooting/lyra-ui/components/agent-tools/prompt-studio/prompt-studio.class.js`.
  `PromptStudioVariable {
    name: string;
    value: string;
    description?: string;
  }`
  Import: `@aceshooting/lyra-ui/components/agent-tools/prompt-studio/prompt-studio.class.js`.
  `PromptStudioVersion {
    id: string;
    label: string;
    messages: readonly PromptStudioMessage[];
    variables?: readonly PromptStudioVariable[];
    createdAt?: string;
  }`

- **`components-agent-tools-run-events-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui`.
  `AgentRunActivateDetail<TRun = unknown> {
    readonly runId: string;
    readonly run?: TRun;
  }`

- **`components-agent-tools-schema-viewer-schema-viewer-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/agent-tools/schema-viewer/schema-viewer.class.js`.
  `JsonSchemaNode {
    readonly $ref?: string;
    readonly type?: string | readonly string[];
    readonly title?: string;
    readonly description?: string;
    readonly properties?: Readonly<Record<string, JsonSchemaNode>>;
    readonly items?: JsonSchemaNode | readonly JsonSchemaNode[];
    readonly required?: readonly string[];
    readonly enum?: readonly unknown[];
    readonly const?: unknown;
    readonly default?: unknown;
    readonly examples?: readonly unknown[];
    readonly oneOf?: readonly JsonSchemaNode[];
    readonly anyOf?: readonly JsonSchemaNode[];
    readonly allOf?: readonly JsonSchemaNode[];
    readonly [key: string]: unknown;
  }`
  Import: `@aceshooting/lyra-ui/components/agent-tools/schema-viewer/schema-viewer.class.js`.
  `SchemaValidationIssue {
    path: string;
    message: string;
    severity?: 'error' | 'warning' | 'info';
  }`

- **`components-agent-tools-stack-trace-stack-trace-parse-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/agent-tools/stack-trace/stack-trace-parse.js`.
  `parseStackTrace(trace: string, options?: StackTraceParseOptions): StackTraceParseResult`
  Import: `@aceshooting/lyra-ui/components/agent-tools/stack-trace/stack-trace-parse.js`.
  `StackFrame {
    functionName?: string;
    file?: string;
    line?: number;
    column?: number;
    internal: boolean;
    raw: string;
  }`
  Import: `@aceshooting/lyra-ui/components/agent-tools/stack-trace/stack-trace-parse.js`.
  `StackGroup {
    message: string;
    frames: StackFrame[];
  }`
  Import: `@aceshooting/lyra-ui/components/agent-tools/stack-trace/stack-trace-parse.js`.
  `StackTraceParseOptions {
    internalPatterns?: readonly (string | RegExp)[];
  }`
  Import: `@aceshooting/lyra-ui/components/agent-tools/stack-trace/stack-trace-parse.js`.
  `StackTraceParseResult {
    groups: StackGroup[];
    truncated: boolean;
    source: string;
  }`

- **`components-agent-tools-subagent-panel-subagent-panel-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/agent-tools/subagent-panel/subagent-panel.class.js`.
  `SubagentRun {
    readonly id: string;
    readonly parentId?: string;
    readonly label: string;
    readonly status: AgentStatusKind;
    readonly task?: string;
    readonly model?: string;
    readonly progressRatio?: number;
    readonly startedAt?: number;
    readonly endedAt?: number;
    readonly metadata?: Readonly<Record<string, unknown>>;
  }`

- **`components-agent-tools-task-list-task-list-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/agent-tools/task-list/task-list.class.js`.
  `TaskItem {
    id: string;
    label: string;
    status: TaskStatus;
    detail?: string;
    children?: readonly TaskItem[];
  }`
  Import: `@aceshooting/lyra-ui/components/agent-tools/task-list/task-list.class.js`.
  `TaskListToggleDetail {
    expanded: boolean;
  }`

- **`components-agent-tools-test-results-test-results-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/agent-tools/test-results/test-results.class.js`.
  `TestCaseResult {
    id: string;
    name: string;
    status: TestStatus;
    durationMs?: number;
    message?: string;
  }`
  Import: `@aceshooting/lyra-ui/components/agent-tools/test-results/test-results.class.js`.
  `testResultDetailSlotName(suiteId: string, testId: string): string`
  Import: `@aceshooting/lyra-ui/components/agent-tools/test-results/test-results.class.js`.
  `TestSuiteResult {
    id: string;
    name: string;
    tests: readonly TestCaseResult[];
  }`

- **`components-agent-tools-thinking-panel-thinking-panel-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/agent-tools/thinking-panel/thinking-panel.class.js`.
  `ThinkingPanelToggleDetail {
    expanded: boolean;
  }`

- **`components-agent-tools-tool-call-chip-tool-call-chip-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/agent-tools/tool-call-chip/tool-call-chip.class.js`.
  `ToolChipSelectDetail {
    name: string;
    callId: string;
  }`

- **`components-agent-tools-tool-result-view-registry-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/agent-tools/tool-result-view/registry.js`.
  `DirectToolRendererDefinition extends ToolRendererDefinitionBase {
    readonly render: (result: unknown, args: unknown, context?: ToolRenderContext) => unknown;
    readonly load?: never;
    // Inherited from ToolRendererDefinitionBase.
    readonly matches?: (payload: unknown) => boolean;
  }`
  Import: `@aceshooting/lyra-ui/components/agent-tools/tool-result-view/registry.js`.
  `findToolRenderer(toolName: string, payload: unknown, registry?: ToolRendererRegistry): ToolRendererDefinition | undefined`
  Import: `@aceshooting/lyra-ui/components/agent-tools/tool-result-view/registry.js`.
  `getDefaultToolRendererRegistry(): ToolRendererRegistry`
  Import: `@aceshooting/lyra-ui/components/agent-tools/tool-result-view/registry.js`.
  `LazyToolRendererDefinition extends ToolRendererDefinitionBase {
    readonly render?: never;
    readonly load: () => Promise<DirectToolRendererDefinition | {
      default: DirectToolRendererDefinition;
    }>;
    // Inherited from ToolRendererDefinitionBase.
    readonly matches?: (payload: unknown) => boolean;
  }`
  Import: `@aceshooting/lyra-ui/components/agent-tools/tool-result-view/registry.js`.
  `loadToolRenderer(def: ToolRendererDefinition): Promise<DirectToolRendererDefinition>`
  Import: `@aceshooting/lyra-ui/components/agent-tools/tool-result-view/registry.js`.
  `registerToolRenderer(name: string, def: ToolRendererDefinition): void`
  Import: `@aceshooting/lyra-ui/components/agent-tools/tool-result-view/registry.js`.
  `ToolRenderContext {
    reportStatus: (status: ToolResultStatus) => void;
  }`

- **`components-agent-tools-tool-select-dialog-tool-select-dialog-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/agent-tools/tool-select-dialog/tool-select-dialog.class.js`.
  `ToolSelectDialogTool {
    id: string;
    name: string;
    description?: string;
    category?: string;
    icon?: string;
    disabled?: boolean;
    disabledReason?: string;
  }`
  Import: `@aceshooting/lyra-ui/components/agent-tools/tool-select-dialog/tool-select-dialog.class.js`.
  `ToolSelectionChangeDetail {
    readonly selectedToolIds: readonly string[];
    readonly useDefaults: boolean;
  }`

- **`components-agent-tools-tool-timeline-tool-timeline-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/agent-tools/tool-timeline/tool-timeline.class.js`.
  `ToolTimelineActivateDetail {
    invocationId: string;
    sourceKey?: string;
  }`
  Import: `@aceshooting/lyra-ui/components/agent-tools/tool-timeline/tool-timeline.class.js`.
  `ToolTimelineApprovalDetail extends ToolApprovalEventDetail {
    args?: unknown;
    sourceKey?: string;
    // Inherited from ToolApprovalEventDetail.
    invocationId: string;
    approved: boolean;
  }`
  Import: `@aceshooting/lyra-ui/components/agent-tools/tool-timeline/tool-timeline.class.js`.
  `ToolTimelineEntry extends ToolInvocation {
    sourceKey?: string;
    icon?: string;
    startedAt?: number;
    endedAt?: number;
    retryCount?: number;
    redactedFields?: readonly string[];
    needsApproval?: boolean;
    approved?: boolean;
    // Inherited from ToolInvocation.
    id: string;
    name: string;
    args: Record<string, unknown>;
    status: ToolCallStatus;
    result?: unknown;
    error?: string;
  }`
  Import: `@aceshooting/lyra-ui/components/agent-tools/tool-timeline/tool-timeline.class.js`.
  `ToolTimelineRenderErrorDetail extends ToolTimelineActivateDetail {
    toolName: string;
    error: unknown;
    // Inherited from ToolTimelineActivateDetail.
    invocationId: string;
    sourceKey?: string;
  }`

- **`components-agent-tools-trace-tree-span-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/agent-tools/trace-tree/span.js`.
  `LyraSpan {
    id: string;
    parentId?: string;
    name: string;
    kind: LyraSpanKind;
    startMs: number;
    endMs?: number;
    status: LyraSpanStatus;
    tokensIn?: number;
    tokensOut?: number;
    costText?: string;
    detail?: string;
  }`
  Import: `@aceshooting/lyra-ui/components/agent-tools/trace-tree/span.js`.
  `LyraSpanProjection {
    spans: LyraSpan[];
    byId: Map<string, LyraSpan>;
    truncated: boolean;
    extentEndMs: number;
  }`
  Import: `@aceshooting/lyra-ui/components/agent-tools/trace-tree/span.js`.
  `normalizeLyraSpanKind(value: unknown): LyraSpanKind`
  Import: `@aceshooting/lyra-ui/components/agent-tools/trace-tree/span.js`.
  `normalizeLyraSpans(values: readonly unknown[], activeSpanId?: string | null): LyraSpanProjection`
  Import: `@aceshooting/lyra-ui/components/agent-tools/trace-tree/span.js`.
  `normalizeLyraSpanStatus(value: unknown): LyraSpanStatus`

# Retrieval, knowledge graph & grounding (`components/retrieval/`)

## Breaking changes in 10.0.0

`lr-entity-card`, `lr-entity-chip` and `lr-neighbor-list` no longer emit `lr-entity-activate`. The
canonical name for that gesture is `lr-entity-select` (`detail: { entityId }`), fired from the same
gesture with the same detail — only the second spelling is gone. It is removed outright rather than
kept as a dual-emitting alias, because the library has no released consumers and an alias is a
permanent tax paid to protect users who do not exist. Rename the listener; nothing else changes.

Two composites narrow with them. `lr-entity-dossier` surfaces its embedded entity card's and
neighbor list's gesture as `lr-entity-select` only, and `lr-provenance-panel` does the same for its
embedded entity chip. On both, `lr-entity-activate` now reaches a host only from the embedded
community card or relationship path strip, which is also the only source of the richer
`{ entityId, occurrenceIndex? }` detail — so on these two elements the names now carry different
shapes rather than being two spellings of one event.

`lr-community-card` and `lr-path-strip` keep `lr-entity-activate` unchanged. It is their only name
and never was an alias, so do **not** rename those listeners.

`lr-rag-eval-dashboard` no longer emits `lr-run-select`; listen for `lr-run-change`
(`detail: { run }`, unchanged). Same removal, same reason.

`lr-knowledge-graph-explorer`'s `lr-search-change` detail is now exactly
`{ query, matchCount, matchCountExact }`. The old `searchQuery` member is replaced by the canonical
`query` rather than carried beside it, so the event finally has the `LyraSearchChangeDetail` shape
the rest of the library's search emitters use — read `e.detail.query`. The detail deliberately has no
`activeIndex` (this is a live node filter, not a cursor-based search) and `matchCountExact` is always
`true`, since that filter has no truncating ceiling. The `searchQuery` **property** is a different
member and is unaffected: the component still applies the query to it before emitting, so reassigning
it from the handler stays a no-op.

Also corrected in 10.0.0 — not breaking, but visible. A chip with no `entity-id` renders its button
disabled, and now looks it: `lr-entity-chip` used to paint that state pixel-identical to a working
chip — full opacity, a hand cursor, complete hover and press feedback for a control that cannot emit
anything — and now dims to `--lr-opacity-disabled` with a `not-allowed` cursor and no pointer
response. `lr-embedding-explorer`'s selected point has a focus ring again. And
`lr-knowledge-graph-explorer` no longer announces on mount: a preset `search-query` used to fire its
live region before any user action.

## Breaking changes in 9.0.0

`lr-graph`'s exported types `GraphLayout`, `GraphRenderer`, `GraphSelectionMode`, `GraphPickKind`, and
`GraphCommunity` are renamed to `LyraGraphLayout`, `LyraGraphRenderer`, `LyraGraphSelectionMode`,
`LyraGraphPickKind`, and `LyraGraphCommunity` — update any TypeScript import; no markup/runtime
change.

`lr-node-palette`'s exported `PaletteItem` type is renamed to `LyraPaletteItem` — update any
TypeScript import; no markup/runtime change.

`lr-rag-answer`'s exported `RagAnswerState` type is renamed to `LyraRagAnswerState` — update any
TypeScript import; no markup/runtime change.

`lr-rag-eval-dashboard`'s exported types `RagEvaluationMetricCategory`, `RagEvaluationMetricFormat`,
`RagEvaluationMetric`, and `RagEvaluationRun` are renamed to `LyraRagEvaluationMetricCategory`,
`LyraRagEvaluationMetricFormat`, `LyraRagEvaluationMetric`, and `LyraRagEvaluationRun` — update any
TypeScript import; no markup/runtime change.

`lr-entity-chip`'s `label` property/attribute (the chip's visible text) is renamed to `text`; `label`
is now reserved, matching every other retrieval component, for the family's ARIA-fallback-name
convention. Update `<lr-entity-chip label="...">` to `text="...">` and any `el.label` read/write to
`el.text`.

`lr-grounding-summary`'s `heading-level`/`headingLevel` switches from a local numeric `1`-`6` union to
the shared string union `LyraHeadingLevel` (`'1'|'2'|'3'|'4'|'5'|'6'|'none'`), matching `lr-empty`/
`lr-dialog`/`lr-task-list`/`lr-contact-viewer`. Existing `heading-level="2"` markup keeps working
unchanged (numeric-string attribute values are unaffected), but a JS assignment of a bare number
(`el.headingLevel = 2`) must become a string (`el.headingLevel = '2'`); an out-of-range or otherwise
invalid value now falls back to level 3 (matching every sibling) instead of clamping toward the
nearest bound; and the new `heading-level="none"` value opts the warnings/evidence section headings
out of heading semantics entirely (renders plain text, no `role`/level).

## `lr-graph`

A force-directed node-link diagram with pan/zoom/drag, built on `d3-force`.

A zero-width canvas link paints neither a stroke nor an arrowhead; its relationship remains in the
nonvisual topology summary.

In both renderers, roving navigation transfers real focus through nodes, operable links, then
community hulls; zero-width, fully transparent, and dangling links remain outside that focus order.

**Properties:**

- `nodes: LyraGraphNode[] = []` (attribute: false) — readonly `LyraGraphNode { id: string; label?: string;
accessibleLabel?: string; description?: string; radius?: number; color?: string; type?: string;
expandable?: boolean; communityId?: string }`;
  `accessibleLabel` supplies richer spoken text than the visible label, while `description` renders
  as the preferred bounded tooltip/summary text in both renderers. `radius` is clamped to `[6, 24]` (an unset/non-finite value
  falls back to the midpoint, `15`) so a node can never render invisibly small or absurdly large.
  `type` is a key into `nodeTypes` (matched by `LyraNodeTypeStyle.id`); unknown/absent renders as an
  untyped default circle with the token fill, but an unmatched `type` still participates in
  `hiddenTypes` filtering by its raw string value
- `nodeTypes: LyraNodeTypeStyle[] = []` (attribute: false) — readonly `LyraNodeTypeStyle { id: string; label: string;
color?: string; shape?: 'circle' | 'square' | 'diamond' }`, one entry per `LyraGraphNode.type` value:
  `label` feeds the spoken "typed node" summary, and `shape`/`color` drive rendering per node.
  Per-node fill resolution precedence is `LyraGraphNode.color` (most specific) > the matched
  `LyraNodeTypeStyle.color` > an ordered categorical fallback palette assigned by the type's index in
  `nodeTypes` (`--lr-graph-cat-1` through `-8`, wrapping every 8 entries) > the untyped
  `--lr-node-fill` default; both data-driven color sources are sanitized the same way as
  `LyraGraphNode.color` itself. A typed node with no matching `nodeTypes` entry renders as a plain
  circle with the untyped default fill
- `hiddenTypes: string[] = []` (attribute: false) — hides nodes whose raw `type` is listed and every
  incident link from rendering, layout, keyboard navigation, the data-list alternative, and the
  accessible counts. Hidden positions are retained by id, so showing a type restores its prior
  layout even when no matching `nodeTypes` entry exists
- `links: LyraGraphLink[] = []` (attribute: false) — readonly `LyraGraphLink { id?: string; source: string; target:
string; width?: number; label?: string; accessibleLabel?: string; description?: string; directed?:
boolean; color?: string; dash?: number[] }` (source/target are node ids). `directed` adds an
  arrowhead; `color` and `dash` style the individual stroke; `label` provides a spoken-name and SVG
  tooltip fallback but is not rendered as visible edge text; `accessibleLabel` and `description`
  can override the spoken name and tooltip independently. `width` is normalized before reaching
  SVG, canvas paint, or canvas picking: negative values clamp to `0`, while a non-finite or unset
  value uses `1.5`. A zero-width or fully transparent link remains in the nonvisual topology
  summary but is excluded from pointer picking and keyboard navigation, so invisible geometry never
  becomes an operable control. A link whose `source` id doesn't resolve to a real node is still dropped entirely
  (there's no position to draw a stub from). A link whose `target` id doesn't resolve instead renders
  as a short, dashed, non-interactive stub off `source`'s own position
  (`[part='link'][data-dangling]`, `aria-hidden="true"`) rather than being silently dropped — e.g. for
  a wiki-style `[[link]]` reference to a not-yet-created node. A dangling stub is excluded from
  `d3-force`'s own simulation input and from click/keyboard interaction.
- `fitTo: 'none' | 'container' = 'none'` (attribute `fit-to`) — where the drawing space comes from.
  `'none'` uses the numeric `width`/`height` below, unchanged. `'container'` measures the host's own
  content box and feeds that to the SVG `viewBox`, the layout's centring force,
  `focusNode()`/`fit()`'s camera math and the loading skeleton, so the drawing always matches the box
  it is rendered into and no host-side `ResizeObserver` is needed. The first measurement is taken
  synchronously before the first paint, with the host's own height already applied, so the first
  painted frame is already the right size; every later one arrives on the component's own
  host-resize watcher and is rounded to whole CSS pixels, so sub-pixel jitter changes nothing. A resize re-centres the running layout in place (`forceCenter`
  plus a low-alpha restart) and never rebuilds the simulation, so settled node positions, pins and an
  in-flight drag all survive it. Works in both renderers and across a renderer switch. While
  `'container'` is in effect the measured box wins over `width`/`height`; it falls back to them when
  the box is unmeasurable (detached, `display: none`, or a realm with no `ResizeObserver`). It does
  **not** change how the host itself is sized — an outer `block-size`,
  `--lr-canvas-reserved-height` and `height` still do that, and `'container'` simply follows
  whichever of them won
- `width: number = 800` — ignored while `fitTo` is `'container'`
- `height: number = 600` — also sizes the rendered host itself (see
  `--lr-canvas-reserved-height`'s entry below) whenever neither that nor an explicit outer
  `block-size` overrides it. Only the drawing space is ignored while `fitTo` is `'container'`; the
  host sizing above still applies
- `chargeStrength: number = -300` (attribute `charge-strength` — live-reactive, see gotchas)
- `linkDistance: number = 100` (attribute `link-distance` — live-reactive, see gotchas)
- `minZoom: number = 0.1` (attribute `min-zoom`)
- `maxZoom: number = 8` (attribute `max-zoom`)
- `accessibleLabel: string | null = null` (attribute `aria-label`) — setting the JS property while
  the host attribute is absent names the SVG/canvas owner. Authored host `aria-label` presence,
  including an explicitly empty value, instead makes the host the sole named graph owner; the
  inner renderer drops its parallel role/name. Removing the attribute restores the inner owner and
  its localized node/link-count fallback
- `seed?: number` — when set, seeds each node's initial x/y deterministically
  (keyed by node **id**, not array index/order) instead of `forceSimulation()`'s own random start,
  and settles the simulation synchronously instead of animating the settle (same effect
  `prefers-reduced-motion` has, see gotchas)
- `showEdgeLabels: boolean = false` (attribute `show-edge-labels`) — draws each resolved
  (non-dangling) link's `label` as visible SVG text (`[part="link-label"]`) at the segment midpoint.
  Off by default: `LyraGraphLink.label` stays spoken/tooltip-only, matching pre-existing behavior, unless
  this is set
- `edgeLabelMinZoom: number = 0.6` (attribute `edge-label-min-zoom`) — below this zoom scale, every
  drawn edge label is hidden (toggled via a `data-edge-labels-hidden` attribute on the zoomed `<g>`,
  not a Lit re-render, so it tracks pan/zoom smoothly). Ignored entirely when `showEdgeLabels` is
  `false`
- `nodeLabels?: 'always' | 'zoom' | 'none'` (attribute `node-labels`) — node-label visibility.
  `'always'` draws every node's label unconditionally; `'zoom'` hides them below the same
  canvas-declutter zoom threshold used before this property existed (toggled via a
  `data-node-labels-hidden` attribute on the zoomed `<g>` for `renderer="svg"`, mirroring
  `showEdgeLabels`/`edgeLabelMinZoom`'s own mechanism — not a Lit re-render); `'none'` never renders
  them. Left unset (the default), each renderer keeps its own exact pre-existing behavior —
  `'always'` for `renderer="svg"`, `'zoom'` for `renderer="canvas"` — so this is purely additive
- `layout: 'force' | 'layered' = 'force'` — `'force'` runs the `d3-force` simulation described
  throughout this section, unchanged. `'layered'` swaps in a deterministic Sugiyama-lite layered
  layout instead (longest-path layering, barycenter crossing reduction, cycle-safe — back edges are
  reversed only for layering, never mutating caller data): positions are computed synchronously
  with no settle animation, sized from each node's own radius and spaced by `linkDistance` (the
  layer gap) and a fixed 12px in-layer gap. Node drag is disabled in this mode (dragging would fight
  a computed layout) and `chargeStrength` becomes a documented no-op; pan/zoom, keyboard roving,
  `focusNode()`/`fit()`, hulls, edge labels, and `hiddenTypes` filtering all work identically to
  force mode. Switching `layout` at runtime repositions every node without a tween. The layering
  algorithm itself lives in the standalone, dependency-free `layeredLayout()` export
  (`@aceshooting/lyra-ui/utilities/layered-layout`), reusable by any other layered-diagram consumer
- `renderer: 'svg' | 'canvas' = 'svg'` — `'canvas'` swaps the per-node/per-link SVG DOM for a single
  DPR-aware `<canvas>`; every event/method/property behaves identically to `'svg'`, with hit-testing
  resolved via an offscreen color-picking canvas instead of DOM event targets. Trade-offs: no
  `::part(node)`/`::part(link)` styling (pixels, not elements — theme via cssprops instead), no
  native SVG `<title>` tooltip (replaced by `part="tooltip"`), and a drawn focus ring instead of a
  CSS one. Keyboard roving/announcements are preserved through an offscreen `part="cursor-item"`
  button per visible node/link/hull; the canvas repaints a non-color dashed/ring focus cue for the
  currently focused node, link, or hull and uses a system color under forced colors. In both renderers, node, link, and community-hull picking keeps at
  least 24 CSS px of screen-space geometry as the viewport zoom changes; this enlarges interaction
  only, not the visible marks. Every data-driven and token-derived canvas color is resolved through
  the live computed CSS cascade before painting, so CSS-wide keywords such as `inherit`/`unset`,
  custom-property references, and modern color functions reach Canvas as concrete colors.

**Methods:** `focusNode(id, options?: { zoom? })` and `fit(options?: { padding?: number })` control the
camera; `getNodePosition(id)` returns the current `{ x, y }` in graph-local drawing coordinates, or
`undefined` when the id is not currently simulated.

**Events:** `lr-node-click` (`detail: { nodeId, x, y }`, where `x` and `y` are the clicked node's current
local drawing coordinates), `lr-link-click` (`detail: { sourceNodeId, targetNodeId,
linkId? }`; the optional `linkId` is the stable `LyraGraphLink.id` supplied by the caller), `lr-node-enter`/
`lr-node-leave` (`detail: { nodeId }`, hover start/end, suppressed while dragging/panning; canvas emits once per hit-identity transition or exit),
`lr-link-enter`/`lr-link-leave` (`detail: { sourceNodeId, targetNodeId, linkId? }`, same hover contract),
`lr-node-expand` (`detail: { nodeId }`, a node was double-activated — native `dblclick`, or two
Enter/Space activations within 500ms — regardless of `LyraGraphNode.expandable`), `lr-community-click`
(`detail: { communityId }`, a hull was activated), `lr-selection-change`
(`detail: { nodeIds, linkIds }`, a controlled selection intent), and `lr-viewport-change`
(`detail: { k, x, y }`, a frame-coalesced camera/layout signal)

**Slots:** none.

**CSS parts:** `base`, `svg`, `node`, `link`, `arrowhead` (the marker path shared by directed links),
`label` (`renderer="svg"` only; not rendered at all when `nodeLabels` is `'none'`), `link-label` (a
drawn edge label, only rendered when `showEdgeLabels` is set),
`expand-indicator` (the "+" badge on a node with `expandable: true`), `focus-halo` (the persistent
ring tracking `focusNodeId`'s node), `hull` (a community hull), `community-label`,
`live-region`, `data-list`, `empty`, `error` (neutral visible message shown instead of the graph when
the optional `d3-force`/`d3-drag`/`d3-zoom`/`d3-selection` peers fail to load; that transition is
announced through a shared assertive light-DOM region — distinct from the empty state, which means
the peers loaded fine but `nodes` is empty),
`canvas`/`tooltip`/`cursor-items`/`cursor-item`
(`renderer="canvas"` only — the drawing surface, its hover tooltip replacing the SVG `<title>`, and
the offscreen keyboard-roving items)

**Themeable custom properties:** `--lr-canvas-reserved-height` (default
`var(--lr-size-24rem)`) sets the host block size and is shared with the optional pre-upgrade
reservation stylesheet. Below it in the fallback chain, the normalized `height` property sizes the
host too (through a private, not-directly-settable custom property) — setting
`--lr-canvas-reserved-height` always overrides `height`, and an explicit outer `block-size` still
wins over both. `--lr-node-fill` (set inline per-node from `LyraGraphNode.color`,
falls back to `--lr-color-brand`) and `--lr-link-color` (set inline per-link from
`LyraGraphLink.color`, falling back to `--lr-color-border`); also uses `--lr-color-text` +
`--lr-font` (label text), `--lr-focus-ring-*` (node/link `:focus-visible` outline).
The ordered categorical fallback palette for a typed node with no `LyraNodeTypeStyle.color` is
`--lr-graph-cat-1` (default `var(--lr-theme-graph-cat-1,#8250df)`),
`--lr-graph-cat-2` (default `var(--lr-theme-graph-cat-2,#bf3989)`),
`--lr-graph-cat-3` (default `var(--lr-theme-graph-cat-3,#0a7d91)`),
`--lr-graph-cat-4` (default `var(--lr-theme-graph-cat-4,#57606a)`),
`--lr-graph-cat-5` (default `var(--lr-theme-graph-cat-5,#b083f5)`),
`--lr-graph-cat-6` (default `var(--lr-theme-graph-cat-6,#f470b8)`),
`--lr-graph-cat-7` (default `var(--lr-theme-graph-cat-7,#52d6e8)`), and
`--lr-graph-cat-8` (default `var(--lr-theme-graph-cat-8,#c9d1d9)`). Assignment follows the type's
index in `nodeTypes` and wraps every eight entries; the `--lr-theme-graph-cat-*` inputs are the
preferred theme-level overrides.
`--lr-graph-edge-label-halo` (default `var(--lr-color-surface)`) — the legibility halo painted
behind a drawn `[part="link-label"]` (via `paint-order: stroke`).
`--lr-graph-focus-halo-color` (default `var(--lr-color-brand)`) — `[part="focus-halo"]` and canvas keyboard-focus cue stroke.
`--lr-graph-selected-color` (default `var(--lr-color-success)`) — selected node/link stroke.
`--lr-graph-dimmed-opacity` (default `0.35`) — opacity of a node/link listed in
`dimmedNodeIds`/`dimmedLinkIds`.
`--lr-graph-hull-fill` (default `var(--lr-color-brand)`) — community hull fill/stroke color
(overridden inline per hull from `LyraGraphCommunity.color`).
`--lr-graph-hull-opacity` (default `0.12`) — hull element opacity (composites fill+stroke as one).
Under `renderer="canvas"` these five are read from computed style at paint time (there are no
per-node elements to inherit them), so they must be set on or above the `<lr-graph>` host itself.
The canvas repaints when inherited theme inputs change (including ancestor class/data attributes,
adopted stylesheets, and media-query theme transitions); a host does not need to reassign `nodes`
to make new token values visible.

**Optional peer deps:** `d3-force`, `d3-drag`, `d3-zoom`, `d3-selection` (all four required
together; lazy-`import()`ed once per page). Each loaded module is validated for the named callable
capabilities the graph uses; a missing package or malformed module fails closed through the
localized `part="error"` alert. Install with
`pnpm add d3-force d3-drag d3-zoom d3-selection`.

```html
<lr-graph style="display:block;height:500px"></lr-graph>
<script type="module">
  import "@aceshooting/lyra-ui/components/retrieval/graph/graph.js";

  const g = document.querySelector("lr-graph");
  g.nodes = [
    {
      id: "a",
      label: "A",
      accessibleLabel: "Source document A",
      description: "The source document",
    },
    { id: "b", label: "B", description: "The cited document" },
  ];
  g.links = [
    {
      id: "citation-a-b",
      source: "a",
      target: "b",
      label: "cites",
      accessibleLabel: "Document A cites document B",
      description: "Citation relationship",
      directed: true,
      color: "var(--lr-color-brand)",
      dash: [6, 3],
    },
  ];
  g.addEventListener("lr-node-click", (e) => console.log(e.detail.nodeId));
  g.addEventListener("lr-link-click", (e) =>
    console.log(e.detail.linkId, e.detail.sourceNodeId, e.detail.targetNodeId)
  );
</script>
```

**Known gotchas:**

- per-tick full re-render is expensive: every d3-force tick (up to ~300 by default,
  continuously while dragging via `alphaTarget(0.3)`) writes node/link positions straight onto the
  already-rendered DOM via `setAttribute()` rather than reassigning `simNodes`/`simLinks` (that
  reassignment — and the Lit re-render/`applyInteractions()` re-scan it used to force on every tick —
  now only happens once per structural `nodes`/`links` change). Still a noticeable cost building up
  the initial layout or while a node is actively being dragged, just no longer once per tick on an
  otherwise-settled graph.
- `chargeStrength`/`linkDistance` **are** live-reactive post-mount now (retuned on the existing
  force objects and the simulation nudged via `alpha(0.3).restart()`) — no need to also touch
  `nodes`/`links` to see the effect.
- `width`/`height` are also live-reactive post-mount: changing either re-centers the `forceCenter`
  force on the new midpoint and nudges the simulation via `alpha(0.1).restart()`, in addition to
  resizing the rendered `viewBox` — both branches apply independently, so setting `width` and
  `chargeStrength` in the same synchronous batch retunes both, not just one.
- zoom is bounded via `minZoom`/`maxZoom` (`d3-zoom`'s `.scaleExtent(...)`, live-reactive in both SVG and canvas); pan/
  zoom/drag are still pointer-only with no keyboard equivalent. Links (`<line part="link">`) are now
  keyboard-operable too (`tabindex="0"`, `role="button"`, `aria-label`, Enter/Space), matching nodes.
- while the `d3-force`/`d3-drag`/`d3-zoom`/`d3-selection` peers are resolving, the host shows an
  unannounced decorative `<lr-skeleton>` sized to `width`/`height` plus an ordinary visually hidden,
  localized loading label; the graph host itself carries `aria-busy="true"`. If the peers fail to
  load (for example, because they are not installed), the graph fails closed with a localized
  neutral `part="error"` message and announces the transition through a shared assertive light-DOM
  region instead of leaving an empty SVG.
- `LyraGraphNode.color`, node-type colors, `LyraGraphLink.color`, and community colors are accepted only
  when the browser parses them as CSS `color`; declaration breaks and `url()` paint servers are
  ignored in favor of the normal token/palette fallback. `LyraGraphLink.dash` is used only when every
  entry is finite and non-negative; an empty or invalid array falls back to a solid line rather
  than partially applying malformed SVG stroke data.
- a structural `nodes`/`links` change now carries over each already-settled node's position (and any
  in-progress drag) by id when rebuilding the simulation, instead of discarding every node's (x, y)
  and re-running the whole ~300-tick random-start settle from scratch — only genuinely new ids get a
  fresh start. Handy for a streaming/incrementally-updated graph, whose existing layout no longer
  jumps every time a node/link is appended.
- under `prefers-reduced-motion: reduce`, or whenever `seed` is set, the simulation converges
  synchronously (ticked in a loop down to `alphaMin` before first paint) instead of animating over
  ~300 rendered frames; user-initiated motion (dragging a node) is unaffected either way.
- in canvas mode, `pointercancel`, lost pointer capture, and disconnect all release a live node's
  force pin and reset the simulation target; a canceled drag never leaves the node pinned.
- With no authored host `aria-label`, the SVG/canvas carries `role="group"` and the localized
  node/link-count name (e.g. "Node-link diagram with 5 nodes and 4 links"). An authored host label
  moves that one graph role/name to the host instead of duplicating it. Node `<text part="label">`s
  stay `aria-hidden="true"` because each node control already owns its label.
- `nodeTypes` and `showEdgeLabels` are live-reactive post-mount: either changing re-scans/rebinds the
  cached per-node and per-link DOM element arrays, alongside the existing `simNodes`/`simLinks`
  structural-change trigger — no need to also touch `nodes`/`links` to see a type/shape/color or
  edge-label change take effect.
- when `showEdgeLabels` is `false` (the default), a resolved link renders as a bare `<line
part="link">` with no extra wrapping element, so existing consumers who never set it see
  byte-for-byte identical link DOM; setting it wraps each link's `<line>` and its
  `[part="link-label"]` `<text>` together. `edgeLabelMinZoom`'s hide/show gate is applied once at
  mount (against d3-zoom's known identity transform) as well as on every subsequent pan/zoom, so
  labels never wrongly start visible before the first user gesture.

**Selection & focus:** `selectionMode: 'none' | 'single' | 'multiple' = 'none'` (attribute
`selection-mode`) gates click/keyboard selection; the component never mutates
`selectedNodeIds: string[] = []` / `selectedLinkIds: string[] = []` (both attribute: false) itself,
only emits `lr-selection-change` (`detail: { nodeIds, linkIds }`) — the host assigns them back,
mirroring `lr-heatmap`'s `selectedCell` contract. `dimmedNodeIds: string[] = []` / `dimmedLinkIds:
string[] = []` (both attribute: false) are the same controlled shape for dimming instead of
selecting — the component never assigns either itself, only renders `data-dimmed` on the matching
`[part="node"]`/`[part="link"]`, themed via `--lr-graph-dimmed-opacity` (default `0.35` — visible out
of the box with no host styling required); a host typically computes the set from a
`lr-node-enter`/`lr-link-enter` hover (the complement of the hovered id's neighbor set) and assigns
it back — `lr-knowledge-graph-explorer`'s own `highlight` property is exactly this composition,
built-in. Empty (the default) renders every node/link at full opacity, unchanged from today.
`nodes`, `links`, `nodeTypes`, and `communities` use nonblank first-wins identities before lookup,
layout, rendering, selection, or events. A link uses its explicit `id`, or `source->target` when
`id` is omitted; a blank explicit `id` is invalid, while distinct explicit ids deliberately allow
parallel links between the same endpoints. Retained identity spelling is not trimmed or rewritten.
Community `memberIds` and controlled id arrays follow the same nonblank first-wins rule.
`communities: LyraGraphCommunity[] = []` (attribute: false) draws one translucent convex-hull blob per
entry behind links/nodes. Each entry is `LyraGraphCommunity { id: string; label?: string; memberIds:
string[]; color?: string }`; membership is the union of `memberIds` and nodes whose `communityId`
matches the entry id. `focusNodeId: string | null = null` (attribute `focus-node-id`) tracks a persistent
focus ring (`[part="focus-halo"]`) around one node;
`focusNode(id, options?)` and `fit(options?)` are the imperative camera-tween counterparts (pan/zoom
to a node, or to fit the whole graph), both resolving once the tween settles. `lr-viewport-change`
(`detail: { k, x, y }`, the live d3-zoom camera transform) fires at most once per animation frame,
coalescing every source that can move a rendered node's screen position — a pan/zoom gesture, a
`focusNode()`/`fit()` tween, and every simulation tick — so a consumer anchoring its own UI (e.g. a
details popover) to a node's `getBoundingClientRect()` can re-read it from this event instead of
polling its own `requestAnimationFrame` loop.

---

## `lr-node-palette`

The searchable, categorized node library for workflow editors: drag an item onto a canvas, or place
it by keyboard. Never creates nodes or touches a canvas's data itself — the drop/place handshake ends
at `lr-node-add`/`lr-palette-place`; the host mutates `nodes`. Fully decoupled from
`lr-flow-canvas` (no `for` resolution, unlike the other three companions) — it only needs to agree
with a `droppable` canvas on the `FLOW_PALETTE_MIME_TYPE` drag payload shape.

For `lr-palette-place`, create the node and assign the updated array to the target canvas's public
`nodes` property. Updating a captured local array alone does not update an already rendered canvas.

**Properties:**

- `items: LyraPaletteItem[] = []` (attribute: false) — `LyraPaletteItem { type: string; label: string;
description?: string; category?: string; keywords?: string[]; icon?: unknown; disabled?: boolean }`;
  `type` is the `FlowNode.type` a placement/drop creates, `category` groups items under
  first-appearance-ordered headings, `disabled` renders an item visible but not draggable/placeable.
  A non-array value is treated as empty. Rows require nonblank string `type` and `label` values;
  malformed optional `description`, `category`, `keywords`, or `disabled` values omit only that row,
  preserving later valid entries. At most 10,000 positions are examined through own data
  descriptors; accessor-backed rows are omitted without reserving later valid rows. The frozen
  projection drives display while `lr-select.detail.item` retains the original admitted identity
- `label?: string` — accessible name for the search field/listbox; omission uses the localized
  palette label. An omitted, empty, or whitespace-only value uses that fallback without changing
  the raw property readback
- `reorderable: boolean = false` (reflected) — opts into Ctrl/Cmd+ArrowUp/ArrowDown keyboard
  reordering of the catalog. Unset, no `lr-reorder` is ever emitted and Ctrl/Cmd+Arrow keeps
  behaving exactly like a plain Arrow press
- `accessibleLabel: string | null = null` (attribute `aria-label`) — as a JS-only property while
  the host attribute is absent, overrides the listbox name. Authored host `aria-label` instead
  names the component as a whole (including explicit-empty/dynamic values) and is not cloned onto
  the listbox, which retains the distinct `label`/localized name

**Events:** `lr-palette-place` (`detail: { type }`, a pointer click or Enter/Space — the
click/keyboard alternative to dragging), `lr-select` (`detail: { item }`, emitted alongside
`lr-palette-place` on both gestures, carrying the full item), `lr-reorder`
(`detail: { type, category, fromIndex, toIndex }`, only while `reorderable`), `focus`/`blur`
(realm-correct native `FocusEvent`s relayed exactly once from the internal search field, preserving
`relatedTarget` while bubbling and crossing the shadow boundary).

`lr-reorder` is a _request_, the same host-applies-the-mutation contract `lr-tree`'s identical
`reorderable`/`lr-reorder` pair already uses: Ctrl/Cmd+ArrowUp/ArrowDown on the focused item asks to
move it past its neighbour **inside its own category group**, so a reorder can never turn into a
recategorization, and nothing is emitted at a group boundary. `category` is `null` for the
uncategorized bucket; `fromIndex`/`toIndex` index into `items` itself, so applying the move is a
plain splice-and-reassign. The palette never reorders `items` on its own, so nothing consults
`defaultPrevented` and the event is not cancelable. The new position is announced only once the
re-rendered group order confirms the host applied it.

**Slots:** `header` (content above the search field, e.g. a heading or tabs), `footer` (content
below the list).

**CSS parts:** `base`, `search-field` (wrapper around the search input and its clear button),
`search`, `search-clear` (clears the query; rendered only while the field has text), `list` (the
listbox), `group-header`, `item`, `item-icon`, `item-label`, `item-description`, `empty`
(no-results message), `live-region` (result-count announcement).

**Themeable custom properties:** `--lr-node-palette-search-min-height` (default
`var(--lr-icon-button-size)`), `--lr-node-palette-search-font-size` (default `inherit`),
`--lr-node-palette-search-padding-inline` (default `var(--lr-space-s)`),
`--lr-node-palette-search-padding-block` (default `var(--lr-space-xs)`) and
`--lr-node-palette-search-radius` (default `var(--lr-radius)`) size the built-in search field; point
the height at a `--lr-form-control-height-*` tier to match it to a themed search field. The height
hook can only raise the field — the shared tappable-target minimum stays underneath it, so no tier
can shrink it past the WCAG floor. The trailing inline gutter is reserved for the overlaid
`search-clear` button and is not a knob. Everything else is shared tokens.

**Optional peer deps:** none.

```html
<lr-node-palette id="palette"></lr-node-palette>
<lr-flow-canvas id="canvas" droppable style="height:480px"></lr-flow-canvas>
<script>
  document.getElementById("palette").items = [
    { type: "http-request", label: "HTTP Request", category: "Actions" },
    { type: "transform", label: "Transform", category: "Actions" },
  ];
  document.getElementById("canvas").addEventListener("lr-node-add", (e) => {
    console.log("drop payload type:", e.detail.type, e.detail.position);
  });
</script>
```

**Known gotchas:**

- A drag from this palette carries `FLOW_PALETTE_MIME_TYPE` as its `DataTransfer` type — only a
  `droppable` `lr-flow-canvas` (or a host reimplementing the same MIME type) accepts it.
- Clicking or activating an item by keyboard fires `lr-palette-place`/`lr-select` immediately, no
  drag required — the host decides where the new node lands (there's no pointer position to derive
  one from on a keyboard placement).

---

## `lr-graph-legend`

A node-type legend for a paired `lr-graph`: one swatch + label + count row per node type, doubling
as visibility filters. Never reads or writes a graph directly — the host forwards `types` in from
`graph.nodeTypes` and `hiddenTypes` back out to `graph.hiddenTypes` on `lr-visibility-change`, the
same event-decoupled contract every sibling in this family follows.

**Properties:**

- `types: LyraNodeTypeStyle[] = []` (attribute: false) — `{ id: string; label: string; color?:
string; shape?: 'circle' | 'square' | 'diamond' }`, the shared `lr-graph.nodeTypes` entry shape. A color is used only
  when valid for CSS `color`; declaration breaks and `url()` fall back to the categorical palette.
  Rows require nonblank string `id` and `label` values, with later duplicate ids omitted first-wins
- `counts?: Record<string, number>` (attribute: false) — optional per-type count shown alongside the
  label; values are rendered as finite nonnegative integers (invalid or negative values become zero)
- `hiddenTypes: string[] = []` (attribute: false) — controlled; the host assigns this back from
  `lr-visibility-change`
- `interactive: boolean = true` (reflected) — renders each row as a toggle `<button>`; `false` renders
  plain, non-interactive rows
- `label: string = ''` — fallback accessible name for the `role="group"` wrapper. A non-empty host
  `aria-label` makes the host the sole overall owner (the wrapper omits its duplicate role/name);
  an explicitly empty host label stays empty on the wrapper

**Events:** cancelable `lr-before-visibility-change` (`detail: { hiddenTypes }`, a frozen complete
next array) fires before a toggle changes state or announces it. Preventing it suppresses all three.
`lr-visibility-change` (`detail: { hiddenTypes }`, the complete updated array) fires after an
accepted assignment and announcement.

**Slots:** none.

**CSS parts:** `base`, `item` (a `<button>` when `interactive`, a plain `<div>` otherwise), `swatch`,
`label`, `count`, `live-region` (the visually hidden filter-toggle announcement).

**Themeable custom properties:** `--lr-graph-legend-hidden-color` (default
`var(--lr-color-text-quiet)`) — text color of a filtered-out (hidden) row's `label`/`count`,
independent of the shared quiet-text token so a host can retint "hidden" rows without repainting
every other quiet-text surface; `--lr-graph-legend-hidden-swatch-opacity` (default `0.5`) controls
only that row's decorative swatch opacity. Also reads `--lr-graph-cat-1` through `-8`
(the same computed-style fallback palette `lr-graph`/`lr-word-cloud` use) plus shared tokens.

**Optional peer deps:** none.

```html
<lr-graph-legend id="legend"></lr-graph-legend>
<lr-graph id="graph" style="height:480px"></lr-graph>
<script>
  const graph = document.getElementById("graph");
  const legend = document.getElementById("legend");
  legend.types = [
    { id: "person", label: "Person", color: "#0969da" },
    { id: "org", label: "Organization" },
  ];
  legend.addEventListener("lr-visibility-change", (e) => {
    legend.hiddenTypes = e.detail.hiddenTypes;
    graph.hiddenTypes = e.detail.hiddenTypes;
  });
</script>
```

**Known gotchas:**

- Ships no coupling to `lr-graph`'s optional `d3-force`/`d3-drag`/`d3-zoom`/`d3-selection` peers —
  `types`/`counts`/`hiddenTypes` are plain data the host derives from a graph, never a live reference
  to one.
- Blank type ids and later duplicates are omitted first-wins. `hiddenTypes` is likewise projected
  to nonblank first occurrences before visibility checks or change events.

---

## `lr-entity-card`

A dossier card for one knowledge-graph entity: type badge, description, key/value property rows,
degree, community chip, plus a built-in "focus in graph" action. Never fetches or focuses a graph
itself — `lr-entity-select` is a request a host routes into `lr-graph`'s own
`focusNode(id, options?)`.

The host `aria-level` attribute overrides the internal title heading live. Changing or removing it
updates that heading without another property change; omission or an empty override uses level 3.

**Properties:**

- `entity: LyraEntity | null = null` (attribute: false) — `LyraEntity { id: string; label: string;
type?: string; description?: string; properties?: Record<string, string | number>; degree?:
number; communityId?: string }`; field names deliberately mirror `lr-graph`'s `LyraGraphNode`
  additions, so a graph node adapts into a `LyraEntity` with no mapping table; `null` renders the
  empty state
- `types: LyraNodeTypeStyle[] = []` (attribute: false) — the same `lr-graph.nodeTypes`/
  `lr-graph-legend.types` entry shape, resolving `entity.type` to a label/color for the badge
- `communityLabel: string = ''` (attribute `community-label`) — override text for the community chip
- `showFocusButton: boolean = true` (attribute `show-focus-button`)
- `compact: boolean = false` (reflected) — tighter root padding and row gap for dense contexts (a
  dossier rendered in a sidebar, a result list) — the same convention as `lr-empty`'s `compact` and
  as this component's sibling `lr-community-card`. Purely a density knob: the border and background
  stay. `false` (the default) keeps the full card padding.
- `frame: LyraFrame = 'card'` (reflected) — container treatment, in the library-wide `frame`
  vocabulary (`'card' | 'plain'`). `'card'` (the default) keeps the bordered, filled, padded box;
  `'plain'` removes the border, background, padding and corner radius, so a card nested inside a
  container that already draws a border doesn't double it. `plain` wins over `compact` when both are
  set — there is nothing left to tighten. The exported alias `EntityCardAppearance` is retained as a
  name for the same union.

**Events:** `lr-entity-select` (`detail: { entityId }`, the built-in focus button was activated).

**Slots:** default (extra body content below the property rows, e.g. a `lr-neighbor-list`),
`actions` (extra header actions alongside the built-in focus button).

**CSS parts:** `base`, `header`, `type-badge`, `title` (`role="heading" aria-level="3"` by default),
`description`, `properties`, `property` (one key/value row), `degree`, `community`, `actions`,
`focus-button`, `empty` (shown when `entity` is `null`).

**Themeable custom properties:** `--lr-entity-card-bg` (default `var(--lr-color-surface)`) —
`[part='base']`'s RESTING background, the companion to the `compact` tier's levers below;
`frame='plain'` still drops the fill entirely. `--lr-entity-card-compact-padding` (default
`var(--lr-space-s)`) — `[part='base']`'s padding while `compact`; `--lr-entity-card-compact-gap` (default
`var(--lr-space-xs)`) — the gap between `[part='base']`'s rows while `compact`. Both apply only in
the `compact` state, so a dense card can be tuned without re-pointing shared spacing tokens for
everything else. Otherwise shared tokens; a data-driven `entity.type` color is applied as
sanitized inline `--lr-badge-*` overrides on the type badge only (the one "type color is
data-driven by design" exception this library already grants graph nodes) — every other color comes
from tokens.

**Optional peer deps:** none.

```html
<lr-entity-card id="card"></lr-entity-card>
<script>
  document.getElementById("card").entity = {
    id: "e1",
    label: "Ada Lovelace",
    type: "person",
    description: "Mathematician",
    properties: { born: 1815 },
    degree: 4,
  };
  document
    .getElementById("card")
    .addEventListener("lr-entity-select", (e) =>
      graph.focusNode(e.detail.entityId)
    );
</script>
```

**Known gotchas:**

- The type badge's data-driven background uses a 12% quiet-tint mix against
  `--lr-color-surface`, while its text continues to use `--lr-color-text`. Treat the percentage as
  an implementation detail; override the documented nested badge properties together when a
  product palette needs a different contrast-qualified treatment.
- A blank `entity.id` renders the empty state. Blank/later duplicate `types[].id` entries cannot
  become badge lookup owners.

---

## `lr-entity-chip`

An inline `@entity` mention for agent prose: flow content, keyboard-focusable, with a hover/focus
preview popover. The knowledge-graph sibling of `lr-citation-badge`, reusing its interaction
contract wholesale. Carries ids through events only — no entity data resolution, no navigation.

Removing `text` or `type` leaves the property readback as `null` and treats it as absent when
deriving the button name. Explicit empty strings stay empty, and later valid values restore the
corresponding label/type text.

**Properties:**

- `entityId: string = ''` (attribute `entity-id`)
- `text: string = ''` — the chip's visible text
- `type: string = ''` (reflected) — lets a host theme per type from CSS, e.g.
  `lr-entity-chip[type='person'] { --lr-entity-chip-color: ... }`
- `typeLabel?: string` (attribute `type-label`) — optional spoken/visible type qualifier

The internal button always derives its own localized accessible name from `text` and optional
`typeLabel`/`type`. Blank or whitespace-only `text` uses the localized “Untitled entity” fallback
before the type template is composed, so it never produces a leading punctuation fragment such as
`, person`. An authored host `aria-label` intentionally names only the custom-element boundary;
it is not copied onto the shadow button because host naming does not cross that boundary.

**Events:** `lr-entity-select` (`detail: { entityId }`, click, or Enter while focused),
`lr-entity-open` (`detail: { entityId }`, dblclick, or Space while focused).

**Slots:** default — rich preview content (typically a compact `lr-entity-card`), shown in a
floating popover on hover/focus. No content means no popover and no hover affordance at all.

**CSS parts:** `base` (the clickable `<button>`), `label`, `popover`.

**Themeable custom properties:** `--lr-entity-chip-color` (default `var(--lr-color-brand)`,
text/accent color), `--lr-entity-chip-bg` (default `var(--lr-color-brand-quiet)`),
`--lr-entity-chip-border` (default `transparent`, the chip's `--lr-border-width-thin` outline).

The anchored detail popover is a floating surface and paints from the **shared overlay-surface family** (16.0.0):
`--lr-overlay-surface` (default `var(--lr-color-surface-overlay)`), `--lr-overlay-border` (default
`var(--lr-color-border)`) and `--lr-overlay-shadow-anchored` (default `var(--lr-shadow-m)`). None is
declared on `:host`, so one declaration on `:root` — or on any ancestor, to scope it — retints this
surface together with every other floating surface in the library. `--lr-overlay-radius` (default `var(--lr-radius)`) is the matching corner radius.

`--lr-positioning-strategy` (16.0.0) — the preview popover reads this same cascading
`absolute`/`fixed` override documented on `<lr-popover>` when it is (re)positioned, falling back to
its own `fixed` default when nothing is set. There is no per-instance `positioning-strategy`
property on `<lr-entity-chip>`; set the custom property on `:root`, a theme, or one clipping
ancestor to change every unset entity chip beneath it.

**Optional peer deps:** none.

```html
<p>
  …first described by
  <lr-entity-chip entity-id="e1" text="Ada Lovelace" type="person">
    <lr-entity-card show-focus-button="false"></lr-entity-card> </lr-entity-chip
  >.
</p>
```

**Known gotchas:**

- Reuses `lr-citation-badge`'s exact "real preview content" detection (an assigned element with no
  other `slot`, or non-whitespace text) to decide whether a popover exists at all.
- Preview content is supplementary and inert. Disable interactive actions on a slotted
  `lr-entity-card` as shown above, and handle the chip's own `lr-entity-select`/`lr-entity-open`
  events for navigation.
- A blank `entityId` disables the chip and cannot produce an activation/open event.

---

## `lr-neighbor-list`

One entity's relationship rows: relation, direction, neighbor, with per-row navigate and
expand-in-graph affordances. Never computes neighbors itself (the host derives rows from its own
graph data) and never mutates a graph.

**Properties:**

- `rows: LyraNeighborRow[] = []` (attribute: false) — `LyraNeighborRow { relation: string; direction:
'in' | 'out' | 'both'; node: LyraEntity }`
- `groupByRelation: boolean = false` (attribute `group-by-relation`) — inserts a `group-header` row per
  distinct `relation`
- `expandable: boolean = false` — renders a per-row expand-in-graph icon button
- `virtualizeAt: number = 100` (attribute `virtualize-at`) — row count above which the list virtualizes
- `label?: string` — fallback name for the stable group. Omission uses the localized neighbor-list
  label. A non-empty host `aria-label` makes
  the host the sole overall owner; an explicitly empty host label stays empty on the group

**Events:** `lr-entity-select` (`detail: { entityId }`, a row's node button was activated),
`lr-node-expand` (`detail: { nodeId }`, a row's expand button was activated — deliberately the same
name and detail shape as `lr-graph`'s own event, so one host handler serves both).

**Slots:** none.

**CSS parts:** `base` (`role="list"`), `group-header` (only when `groupByRelation`; above
`virtualizeAt` this is the internal virtual-list's own group label, re-exported under the same
name), `row` (`role="listitem"`; above `virtualizeAt` this is the internal virtual-list's own row
wrapper, re-exported under the same name), `direction` (`aria-hidden` glyph), `relation`,
`node-label`, `node-meta` (secondary type/degree text, when present), `expand-button` (only when
`expandable`), `empty` (shown when `rows` is empty). Every part presents identically either side of
`virtualizeAt`.

**Themeable custom properties:** shared tokens only.

**Optional peer deps:** none.

```html
<lr-neighbor-list expandable group-by-relation></lr-neighbor-list>
<script>
  document.querySelector("lr-neighbor-list").rows = [
    {
      relation: "works_for",
      direction: "out",
      node: { id: "e2", label: "Analytical Engine Co." },
    },
  ];
</script>
```

**Known gotchas:**

- `lr-node-expand`'s detail shape is intentionally identical to `lr-graph`'s own event of the
  same name, so a single listener wired to both handles "expand this node's neighborhood" uniformly.
- A row is exactly one `[part="row"]` element in both rendering paths. Above `virtualizeAt` that
  element is the internal virtual-list's own row wrapper (the component renders only the row's
  content into it), so a `::part(row)` rule applies once, not twice.
- Rows with blank neighbor ids and later rows repeating the same node id are omitted first-wins
  before grouping, virtualization, rendering, or events.
- A missing, blank, or nonstring `node.type` is omitted from that row's secondary metadata instead
  of being passed to locale formatting; the neighbor label and any valid degree remain visible.

---

## `lr-path-strip`

A linear node → relation → node chain rendering "why A connects to B" (GraphRAG local-search
reasoning paths) as a compact, horizontally scrollable strip. One-dimensional and presentational: no
path finding, no branching, no per-element popovers.

**Properties:**

- `path: LyraPathElement[] = []` (attribute: false) — a flat alternating sequence:
  `{ kind: 'node'; node: LyraEntity } | { kind: 'edge'; relation: string; directed?: boolean;
reverse?: boolean }`
- `label?: string` — fallback name for the stable group. Omission uses the localized path label. A
  non-empty host `aria-label` makes
  the host the sole overall owner; an explicitly empty host label stays empty on the group

**Events:** `lr-entity-activate` (`detail: { entityId, occurrenceIndex }`, a node element activated),
`lr-relation-activate` (`detail: { relation, sourceNodeId?, targetNodeId?, occurrenceIndex }`, an edge element activated —
source/target resolved from the adjacent node elements, `undefined` when the path is malformed at
that position. `occurrenceIndex` is the original supplied array position, so repeated entity ids
remain independently addressable).

**Slots:** none.

**CSS parts:** `base` (hosts the delegated roving-tabindex keydown handler), `node` (a `<button>`),
`relation` (a `<button>`), `arrow` (`aria-hidden`, logical — mirrors under RTL), `empty` (shown when
`path` is empty).

**Themeable custom properties:** shared tokens only.

**Optional peer deps:** none.

```html
<lr-path-strip></lr-path-strip>
<script>
  document.querySelector("lr-path-strip").path = [
    { kind: "node", node: { id: "a", label: "Ada Lovelace" } },
    { kind: "edge", relation: "wrote", directed: true },
    {
      kind: "node",
      node: { id: "b", label: "Notes on the Analytical Engine" },
    },
  ];
</script>
```

**Known gotchas:**

- Purely presentational rendering of a caller-supplied path — it never computes shortest paths or
  fetches relationship data itself, and never branches (one linear chain per instance).
- Blank node ids and blank relation labels are omitted. Repeated nonblank identities are deliberate
  path occurrences rather than duplicates; every event reports the supplied `occurrenceIndex`.

---

## `lr-community-card`

A cluster/community summary card (GraphRAG community report): label, LLM summary excerpt, member
count, member chips with overflow, and a drill-in action. Doesn't own community rendering on the
graph or membership fetching — `lr-drill` asks the host to load members/subgraph.

**Properties:**

- `community: LyraCommunity | null = null` (attribute: false) — `LyraCommunity { id: string; label:
string; summary?: string; memberCount?: number }`; `memberCount` is a non-negative safe-integer
  total for paged data and is authoritative only when it is at least `members.length`; a smaller or
  invalid total cannot contradict the known rendered records; `null` renders the empty state
- `members: LyraEntity[] = []` (attribute: false) — rendered as chips, up to `maxMembers`
- `maxMembers: number = 8` (attribute `max-members`) — remaining members collapse into a "+N"
  overflow chip
- `compact: boolean = false` (reflected) — omits the summary excerpt and member chips
- `frame: LyraFrame = 'card'` (reflected) — container treatment, in the library-wide `frame`
  vocabulary (`'card' | 'plain'`), the same property this component's sibling `lr-entity-card`
  carries. `'card'` (the default) keeps the bordered, filled, padded box; `'plain'` removes the
  border, background, and padding, so a card nested inside a container that already draws a border
  doesn't double it. The exported alias `CommunityCardAppearance` is retained as a name for the same
  union.

**Events:** `lr-drill` (`detail: { communityId }`, the drill button, header, or overflow chip — all three
mean "show me this whole community"), `lr-entity-activate` (`detail: { entityId }`, a member chip was
activated).

**Slots:** `actions` — extra header actions alongside the built-in drill button.

**CSS parts:** `base`, `header`, `title` (`role="heading" aria-level="3"` wrapping a `<button>`),
`member-count`, `summary` (omitted in `compact`), `members` (omitted in `compact`), `member`,
`overflow` (the "+N" chip button), `drill-button`, `actions`, `empty` (shown when `community` is
`null`).

**Themeable custom properties:** `--lr-community-card-bg` (default `var(--lr-color-surface)`) —
`[part='base']`'s RESTING background, so a panel retinting its `lr-entity-card`/`lr-source-card`
siblings can retint this card with it; `frame='plain'` still drops the fill entirely. Otherwise
shared tokens.

**Optional peer deps:** none.

```html
<lr-community-card></lr-community-card>
<script>
  document.querySelector("lr-community-card").community = {
    id: "c1",
    label: "Early computing pioneers",
    summary: "A cluster of 19th-century mathematicians and engineers.",
    memberCount: 12,
  };
</script>
```

**Known gotchas:**

- `memberCount` (not `members.length`) is the authoritative displayed count whenever it's larger —
  useful when the host sends only a preview slice of members alongside the real total.
- A blank community id renders the empty state. Members with blank ids and later duplicates are
  omitted first-wins before count fallback, overflow, rendering, or events.

---

## `lr-chunk-inspector`

A ranked retrieved-chunks list: relevance score bars with tier tones, expandable chunk text, and the
deep-link event that lands a chunk in `lr-document-viewer`. Never fetches or ranks and never opens
documents itself. Blank chunk ids and later duplicates are omitted first-wins before sorting,
rendering, state, or events.

**Properties:**

- `chunks: LyraChunk[] = []` (attribute: false) — `LyraChunk { id: string; text: string; score:
number; sourceId: string; title?: string; page?: string | number; anchor?: LyraChunkAnchor }`;
  blank ids and later duplicate ids are omitted first-wins before any derived path;
  `score` is 0–1, `title` falls back to a localized "untitled source", `anchor` (the same
  discriminated union `lr-document-viewer.anchor` accepts — page/text-quote/fragment/line-range/
  cell-range/cfi/time-range/region/node-path) is carried through `lr-chunk-open` verbatim; finite
  numeric `page` values are formatted with the effective locale in the visible title and open-button
  name, while string locators remain verbatim
- `thresholds: { high: number; medium: number } = { high: 0.75, medium: 0.5 }` (attribute: false) —
  score-bar tier cutoffs
- `sort: ChunkInspectorSort = 'score'` — `ChunkInspectorSort = 'score' | 'none'`, exported by this
  module. The sorted view is memoized on the `chunks`/`sort` pair, so an unrelated update (a new
  `activeChunkId`, toggling `compact`) hands the internal `lr-virtual-list` the same array reference it
  already holds instead of forcing a full offset/identity rebuild
- `activeChunkId: string = ''` (attribute `active-chunk-id`)
- `virtualizeAt: number = 50` (attribute `virtualize-at`)
- `compact: boolean = false` (reflected) — hides the text preview/toggle, title/score row only
- `label: string = ''` — fallback name for the populated result group. A non-empty host
  `aria-label` makes the host the sole overall owner; an explicitly empty host label stays empty

**Events:** `lr-chunk-open` (`detail: { chunkId, sourceId, anchor? }`, a chunk's title/open button was
activated — the event a host routes into `lr-document-viewer`, setting `src` from `sourceId` and
`anchor` from the chunk's own), `lr-expand` (`detail: { chunkId, expanded }`, a chunk's text toggle was
activated).

**Slots:** none.

**CSS parts:** `base` (`role="group"`), `chunk` (one chunk row; carries `role="listitem"` only
below `virtualize-at` — while virtualized the surrounding `lr-virtual-list` row supplies that role
instead), `chunk-current` (additional part on the row matching `activeChunkId`), `score` (visible
percent text), `score-current` (additional part on the current row's score line), `score-bar`
(`aria-hidden` track), `score-fill` (tone-mapped fill), `score-fill-success` /
`score-fill-warning` / `score-fill-danger` (additional part on the fill, one per scoring tier),
`open-button`, `title` (the `<span>` inside `open-button` carrying the visible title text), `text`
(omitted when `compact`), `text-clamped` (additional part on a `text` preview that is still
collapsed; dropped once expanded), `toggle` ("Show more"/"Show less", omitted when `compact`),
`empty` (shown when `chunks` is empty).

Every row-level part is reachable through `::part()` in both rendering paths: above
`virtualize-at` the row lives in the internal `lr-virtual-list`'s shadow root and its parts are
re-exported from there under the same names. Row _state_ is exposed as an additional part name
rather than as an attribute on the part, because Shadow Parts forbids an attribute selector after
`::part()` — `::part(chunk)[aria-current='true']` is invalid CSS. The equivalent attributes
(`aria-current`, `data-tone`, `data-clamped`) are still present on the elements. A state part is a
second token in the same `part` attribute, so a `[part~="…"]` (not `[part="…"]`) selector is the
one that matches inside a tree.

**Themeable custom properties:** `--lr-chunk-inspector-current-bg` (default
`var(--lr-color-brand-quiet)`) — the background of the chunk matching `activeChunkId`.
`--lr-chunk-inspector-current-color` (default `var(--lr-color-text)`) — the text color of that
chunk's `score` line (`::part(score-current)`). Both are inline `var()` fallbacks at the point of
use rather than `:host` declarations, so either can be set on the element _or on any ancestor_:
`::part(chunk)[data-active]` is invalid CSS — Shadow Parts forbids an attribute selector after
`::part()` — which is why the current-chunk state is also published as its own part name
(`chunk-current`, `score-current`); either the custom properties or `::part(chunk-current)` will
retint it.

**They are a contrast-sensitive pair — override them together, never one alone.** The `-current-color`
hook exists precisely because the quiet token it replaces only reaches about 4.24:1 against the
current background; keep any override at 4.5:1 or better against `--lr-chunk-inspector-current-bg`.

Plus shared tokens otherwise.

**Optional peer deps:** none.

```html
<lr-chunk-inspector></lr-chunk-inspector>
<lr-document-viewer id="document-viewer"></lr-document-viewer>
<script>
  const inspector = document.querySelector("lr-chunk-inspector");
  const documentViewer = document.getElementById("document-viewer");
  const sourcesById = new Map([
    [
      "doc-1",
      {
        name: "Q3 report.pdf",
        mimeType: "application/pdf",
        src: "/reports/q3-report.pdf",
      },
    ],
  ]);
  inspector.chunks = [
    {
      id: "c1",
      text: "Revenue grew 12% year over year…",
      score: 0.91,
      sourceId: "doc-1",
      title: "Q3 report",
      page: 4,
      anchor: { kind: "page", page: 4 },
    },
  ];
  inspector.addEventListener("lr-chunk-open", (e) => {
    const source = sourcesById.get(e.detail.sourceId);
    if (!source) return;
    documentViewer.name = source.name;
    documentViewer.mimeType = source.mimeType;
    documentViewer.src = source.src;
    documentViewer.anchor = e.detail.anchor ?? null;
    documentViewer.open = true;
  });
</script>
```

**Known gotchas:**

- `title` and `open-button` are split into two separate parts (rather than one dual-part-name
  element) because an exact-match `[part="..."]` CSS attribute selector cannot match a multi-token
  `part` attribute value.

---

## `lr-source-picker`

A checkbox tree/list scoping which sources ground the next answer: tri-state folders, select-all,
type icons, search. **Not `FormAssociated`, deliberately**: this is a scoping panel, not a form
control — the selection is immediate app state consumed by the next retrieval call, exactly the
stance `lr-tool-select-dialog` already takes.

Toggling search retains the query and selected source IDs. Re-enabling a retained filter repairs the
active tree row so one visible usable Tab stop remains whenever rows are visible; focus already in
the tree follows that repair, while focus outside is preserved.

**Properties:**

- `sources: LyraSourceEntry[] = []` (attribute: false) — `LyraSourceEntry { id: string; label:
string; mimeType?: string; name?: string; children?: LyraSourceEntry[] }`; flat (no `children`) or
  a tree — presence of `children` makes a row a group/folder with tri-state select. Input is
  normalized once into a deterministic nonblank first-id-wins model with identity/cycle detection,
  a depth ceiling of 64 and a 2,000-node ceiling; blank/whitespace ids, duplicate ids, and other
  rejected/truncated input fail closed with localized visible status rather than recursing or
  exposing ambiguous controls. A nonempty raw payload with no valid root entries renders a localized
  invalid-value error rather than the ordinary no-data state
- `selectedSourceIds: string[] = []` (attribute: false) — controlled; blank ids, duplicates, and ids
  that are not leaves in the current `sources` tree are pruned, and the host assigns updates back from
  `lr-sources-change`
- `showSelectAll: boolean = true` (attribute `show-select-all`)
- `searchable: boolean = true`
- `label?: string` — fallback name for the source tree; omission uses the localized picker label,
  while an explicit empty string stays empty
- `accessibleLabel: string | null = null` (attribute `aria-label`) — as a JS-only property while
  the host attribute is absent, overrides the tree name. Authored host `aria-label` instead names
  the picker as a whole (including explicit-empty/dynamic values) and is not cloned onto the tree,
  which retains the distinct `label`/localized name
- `size?: LyraSize` (reflected) — opt-in density tier forwarded to the composed filter `lr-input`,
  on the library's one six-step ladder (`2xs`/`xs`/`s`/`m`/`l`/`xl`, or `small`/`medium`/`large`).
  Forwarding is the only way to reach that field, which resolves its tier inside its own shadow
  root. With no `size` the field keeps its own `m` default; an unsupported value normalizes to the
  omitted state and removes the attribute

**Events:** `lr-sources-change` (`detail: { selectedSourceIds }`, the complete updated leaf-id array,
fired after every toggle including select-all).

**Slots:** none.

**CSS parts:** `base`, `search` (the built-in filter `lr-input`, only when `searchable`),
`select-all` (only when `showSelectAll`), `select-all-control` (the shared `lr-checkbox` semantic
owner), `summary` ("{selected} of {total} selected"), `tree`
(`role="tree"`), `item` (`role="treeitem"`; selection appears only through tri-state
`aria-checked` — `"true"`, `"false"`, or `"mixed"` — and intentionally has no duplicate
`aria-selected` state), `disclosure` (a folder row's pointer-only expand/collapse indicator; the
surrounding treeitem owns keyboard expansion),
`checkbox` (tri-state glyph), `icon` (the `lr-file-icon` type badge), `label`, `empty` (`noData`
when `sources` is empty, `noMatches` when a filter empties the tree), `error` (a nonempty raw
payload containing no valid roots), `limit` (bounded-normalizer
failure/truncation). Post-mount no-match and recovery transitions announce through the shared
light-DOM polite sink; the shadow messages are visible mirrors, never live regions.

**Themeable custom properties:** `--lr-source-picker-checked-bg` — the background of a fully-checked
selection control: the `select-all` pill (whose resting default is `var(--lr-color-brand-quiet)`) and
a fully-selected entry's `[part='checkbox']` (whose resting default is `var(--lr-color-brand)`). The
two keep their distinct defaults while it is unset; setting it unifies both.
`--lr-source-picker-checked-border` (default `var(--lr-color-brand)`) — the border color of every
checked _or_ mixed selection control. `--lr-source-picker-mixed-bg` (default
`color-mix(in srgb, var(--lr-color-brand) 50%, var(--lr-color-surface))`) — the background of a
partially-selected entry's `[part='checkbox']`, so a tri-state folder reads as distinct from a fully
selected one. All three are inline `var()` fallbacks at the point of use rather than `:host`
declarations, so each can be set on the element _or on any ancestor_:
`::part(checkbox)[aria-checked='true']` is invalid CSS — Shadow Parts forbids an attribute selector
after `::part()` — which previously left re-pointing the library-wide `--lr-color-brand` token as
the only lever, repainting every other brand surface with it. `--lr-source-picker-indent-size`
(default `var(--lr-size-1-25rem)`) — the indent step added to `[part='item']`'s
`padding-inline-start` per nesting level; the total indent is capped at `--lr-size-8rem` so a deeply
nested tree cannot push its labels out of view. The component writes each row's own depth inline as
the plain number `--lr-source-picker-depth`, which is indent plumbing rather than a retheming knob —
set the step, not the depth. Plus shared tokens otherwise.

**Optional peer deps:** none.

```html
<lr-source-picker></lr-source-picker>
<script>
  const picker = document.querySelector("lr-source-picker");
  picker.sources = [
    {
      id: "folder-1",
      label: "Reports",
      children: [{ id: "doc-1", label: "Q3.pdf", mimeType: "application/pdf" }],
    },
  ];
  picker.addEventListener(
    "lr-sources-change",
    (e) => (retrievalScope = e.detail.selectedSourceIds)
  );
</script>
```

**Known gotchas:**

- Deliberately not form-associated — `lr-sources-change` is the only wiring; there's no
  `name`/`value`/`FormData` participation the way a genuine form control would have.
- Selection, filtering and projection all consume the same bounded normalized tree. Repeated ids
  use the first depth-first occurrence; cyclic/repeated object identities are skipped.

---

## `lr-provenance-panel`

The grounding breakdown for one answer: a sectioned disclosure panel (Entities / Relationships /
Communities / Text chunks) composing this family's own pieces. The chat ↔ graph ↔ document glue
component. Pure projection + event conduit: no fetching, no graph/viewer imports, no persistence.

Malformed type rows are ignored during lookup, preserving valid later matching records and the
existing immutable collection ownership.

**Properties:**

- `provenance: LyraProvenance | null = null` (attribute: false) — `LyraProvenance { entities?:
LyraEntity[]; relationships?: { path: LyraPathElement[] }[]; communities?: LyraCommunity[]; chunks?:
LyraChunk[] }`; each present array renders through the matching sibling component (`lr-entity-
chip` row, one `lr-path-strip` per relationship, `lr-community-card`, `lr-chunk-inspector`);
  `null` or every section empty renders the overall empty state. Non-array nested collections are
  treated as empty; malformed relationship records and blank/later-duplicate entity, community, or
  chunk ids are omitted without hiding valid neighboring records
- `types: LyraNodeTypeStyle[] = []` (attribute: false) — forwarded to the Entities section's chips
- `thresholds: { high: number; medium: number } = { high: 0.75, medium: 0.5 }` (attribute: false) —
  forwarded to the Text chunks section's `lr-chunk-inspector`
- `label?: string` — fallback name for the stable overall group; omission uses the localized panel
  label. A non-empty host `aria-label`
  makes the host the sole overall owner; an explicitly empty host label stays empty

**Events:** `lr-toggle` (`detail: { section, expanded }`, a section header was toggled —
`section` is `'entities' | 'relationships' | 'communities' | 'chunks'`). Because the panel is a
conduit, every affordance it renders also reaches a listener on the panel itself, and all are
part of its typed event map: `lr-entity-select` (`detail: { entityId }`, from an entity chip),
`lr-entity-activate` (`detail: { entityId, occurrenceIndex? }`, from a community card member or
path-strip node — the only name either one emits, and the only one carrying `occurrenceIndex`),
`lr-entity-open` (`detail: { entityId }`, an entity chip double-click or
Space), `lr-drill` (`detail: { communityId }`, a community card's title, drill button, or overflow chip), and
`lr-relation-activate` (`detail: { relation, sourceNodeId?, targetNodeId?, occurrenceIndex }`, a relationship path-strip
edge), plus `lr-chunk-open` (`detail: { chunkId, sourceId, anchor? }`) and `lr-expand`
(`detail: { chunkId, expanded }`) from the chunk inspector.

**Slots:** none.

**CSS parts:** `base`, `section`, `header` (a section's disclosure `<button>`), `count` (a section's
item-count badge), `body` (`hidden` while collapsed), `entity-row` (the wrapping row of entity chips
inside the entities section), `empty` (shown when every section is empty).

**Themeable custom properties:** `--lr-provenance-panel-entity-justify` (default `flex-start`) —
main-axis packing of the entity-chip row; `center` centers every line, the wrapped final one
included. Justifying `::part(body)` cannot do this, because the row fills the body's inline size.
Plus shared tokens.

**Optional peer deps:** none.

```html
<lr-provenance-panel></lr-provenance-panel>
<script>
  document.querySelector("lr-provenance-panel").provenance = {
    entities: [{ id: "e1", label: "Ada Lovelace", type: "person" }],
    chunks: [
      { id: "c1", text: "Revenue grew 12%…", score: 0.91, sourceId: "doc-1" },
    ],
  };
</script>
```

**Known gotchas:**

- Composes `lr-entity-chip`, `lr-path-strip`, `lr-community-card`, and `lr-chunk-inspector`
  directly rather than reimplementing their rendering — events from those inner components (e.g.
  `lr-entity-activate`, `lr-chunk-open`) still bubble/compose up through this panel's light DOM
  for the host to handle in one place.

---

## `lr-mind-map`

A radial expandable topic tree (NotebookLM Mind Maps): a spatial overview of a topic hierarchy where
activating a topic drills in or hands the topic to the chat. Hierarchy, not network — no cross-links,
no force simulation, no communities, no edge labels (that's `lr-graph`). Zero-dependency SVG; the
radial layout is closed-form arithmetic, in its own `mind-map-layout.ts` module, mirroring
`lr-word-cloud`'s dependency-free precedent.

**Properties:**

- `topics: LyraTopic[] = []` (attribute: false) — `LyraTopic { id: string; label: string; children?:
LyraTopic[] }`; a single root sits at the center, multiple roots hang off an implicit center hub
- `label?: string` — accessible name for the SVG group and the implicit hub's text; omission uses
  the localized mind-map label, while an explicit empty string stays empty
- `expandDepth: number = 1` (attribute `expand-depth`) — initial expansion depth (root + first
  ring); expansion state afterward is component-managed per topic id and survives `topics`
  reassignment

**Events:** `lr-topic-select` (`detail: { topicId }`, a _leaf_ topic was activated),
`lr-topic-toggle` (`detail: { topicId, expanded }`, a parent topic was activated, or auto-expanded by
keyboard descent).

**Slots:** none.

**CSS parts:** `base`, `svg` (the single-tab-stop focus target), `node`, `node-label`, `link`
(parent-child connector), `focus-ring` (keyboard focus ring), `live-region` (visually hidden
announcement region), `empty` (shown when `topics` is empty).

**Themeable custom properties:** `--lr-mind-map-ring-gap` (default `6rem`, radius step per depth
ring). `--lr-mind-map-node-hover-halo` (default `var(--lr-color-brand-quiet)`) — stroke color of
the halo drawn around a topic node's dot on `:hover`, giving mouse users the same "this is
clickable" feedback keyboard users already get from the drawn `focus-ring` part.

**Optional peer deps:** none.

```html
<lr-mind-map style="height:480px" expand-depth="2"></lr-mind-map>
<script>
  document.querySelector("lr-mind-map").topics = [
    {
      id: "root",
      label: "Computing history",
      children: [
        {
          id: "people",
          label: "People",
          children: [{ id: "ada", label: "Ada Lovelace" }],
        },
        { id: "machines", label: "Machines" },
      ],
    },
  ];
</script>
```

**Known gotchas:**

- A user's explicit expand/collapse only ever overrides the `depth < expandDepth` default in the
  direction chosen — reassigning `topics` (even with the same ids) never silently discards that
  override.
- Node-position transitions use `--lr-transition-base`, which already collapses to near-zero under
  `prefers-reduced-motion: reduce` globally, so expansion snaps rather than tweening for a
  reduced-motion user with no extra branching in this component.
- Topic ids must be nonblank and unique across the complete hierarchy. Later depth-first duplicates
  and their subtrees are omitted before layout, navigation, expansion state, rendering, or events.

---

## `lr-citation-badge`

An inline `[n]` citation marker with a hover/focus preview popover and confidence/verification-status
coloring. First-party invention (no Web Awesome equivalent). Meant to sit inline in a chat message's
text, each badge carrying a `source-id` that matches a corresponding `<lr-source-card>` shown
elsewhere on the page (a sibling component in this family) — this component never imports or knows
anything about `<lr-source-card>`, it only carries the id through its event details.

**Properties:**

- `index: number = 1` — the citation number shown, e.g. `3` renders as `[3]`.
- `status: CitationBadgeStatus = 'default'` (reflected) — one of `'default' | 'high' | 'medium' |
'low' | 'verified' | 'unverified'`; drives the badge's color and (unless `label` is set) part of
  its accessible name.
- `sourceId: string = ''` (attribute `source-id`) — id of a corresponding `<lr-source-card>`,
  echoed back verbatim in both events; never read or validated by this component.
- `href: string = ''` — optional direct link target for the citation's source, carried into
  `lr-citation-open`'s detail as-is; this component never navigates.
- `label: string = ''` — adds caller-supplied context to the localized citation-button name while
  retaining the visible citation number (for example, `"Citation 3, Annual report"`). Authored host
  `aria-label` independently names the component and is not cloned onto that nested button. Host
  naming does not cross the shadow boundary, so the button retains its own localized
  citation/index/status name

**Events:**

- `lr-citation-activate` (`detail: { sourceId: string; index: number }`) — fires on click, or on
  Enter while focused (native `<button>` behavior, no listener needed for the Enter case). The
  lightweight "jump to this source" signal.
- `lr-citation-open` (`detail: { sourceId: string; index: number; href?: string }`) — fires on
  dblclick, or on Space while focused. A distinct "full preview" signal; `href` is `undefined` when
  the `href` prop isn't set. A double-click also fires two `lr-citation-activate` events (one per
  constituent click, standard browser `dblclick` behavior) in addition to the one `lr-citation-open`.

**Slots:** default — rich preview/tooltip content (e.g. a filename + excerpt), shown in a floating
popover on hover/focus. This is _not_ the badge's visible content (the badge always renders
`[index]`); nothing renders at all (no hover affordance) when this slot is empty.
When populated, the button carries `aria-describedby` referencing the same-shadow-tree popover,
which owns `role="tooltip"` whether currently shown or hidden.

**CSS parts:** `base` (the clickable `<button>`), `bracket` (each of the two literal `[`/`]` glyphs),
`index` (the citation number), `popover` (the floating preview panel, only meaningful while open).

**Themeable custom properties:** `--lr-citation-badge-accent` / `--lr-citation-badge-bg` /
`--lr-citation-badge-border`. Their private defaults follow `status`, but an inherited or direct
public value remains authoritative in every status. Shared tokens include
`--lr-color-text-quiet`, `--lr-color-text`, `--lr-color-success` / `-success-quiet`,
`--lr-color-warning` / `-warning-quiet`, `--lr-color-danger` / `-danger-quiet`, `--lr-radius`,
`--lr-color-surface`, `--lr-color-border`, `--lr-shadow`, `--lr-space-s`/`-m`,
`--lr-transition-fast`, `--lr-focus-ring-*`.

> Retheming a group of badges from outside `<lr-citation-badge>` (e.g. per-source or
> per-confidence colors)? Set the component hooks above on their ancestor wrapper. Use
> `--lr-theme-*` instead only when changing a shared semantic palette input for the entire subtree.

The anchored source-preview popover is a floating surface and paints from the **shared overlay-surface family** (16.0.0):
`--lr-overlay-surface` (default `var(--lr-color-surface-overlay)`), `--lr-overlay-border` (default
`var(--lr-color-border)`) and `--lr-overlay-shadow-anchored` (default `var(--lr-shadow-m)`). None is
declared on `:host`, so one declaration on `:root` — or on any ancestor, to scope it — retints this
surface together with every other floating surface in the library. `--lr-overlay-radius` (default `var(--lr-radius)`) is the matching corner radius.

`--lr-positioning-strategy` (16.0.0) — the source-preview popover reads this same cascading
`absolute`/`fixed` override documented on `<lr-popover>` when it is (re)positioned, falling back to
its own `fixed` default when nothing is set. There is no per-instance `positioning-strategy`
property on `<lr-citation-badge>`; set the custom property on `:root`, a theme, or one clipping
ancestor to change every unset citation badge beneath it.

**Optional peer deps:** none.

```html
<p>
  Revenue grew 12% year over year
  <lr-citation-badge index="1" status="verified" source-id="doc-1">
    <strong>annual_report.pdf</strong> — "Revenue grew 12% year over year,
    driven primarily by..." </lr-citation-badge
  >.
</p>
<script type="module">
  document.addEventListener("lr-citation-activate", (e) => {
    document
      .querySelector(`lr-source-card[source-id="${e.detail.sourceId}"]`)
      ?.scrollIntoView({ block: "center" });
  });
</script>
```

The popover is positioned with the same internal `place()` helper (`top-start` placement) that
`<lr-tool-call-chip>` uses for its own detail tooltip, and never traps focus — it's supplementary
preview content, not a modal, so Tab continues past the badge normally even while the popover happens
to be visible from a mouse hover. Hovering and focus are tracked as independent "keep it open"
reasons (mirroring `<lr-toast-item>`'s hovering/focused pair), so the pointer leaving while the
badge still holds keyboard focus doesn't schedule a hide the focus is still holding open. There's a
200ms grace period before a hover/focus-out actually hides the popover, so moving the pointer from
the badge into the popover itself (to select/copy its text) doesn't make it vanish mid-move; Escape
and blur (Tab away) close it immediately instead, with no delay.

Status coloring follows a semantic scheme: `verified`/`high` use the success tones (a claim that's
been checked, or the model is confident in); `medium`/`low` use warning tones; `unverified` uses the
_danger_ tone — deliberately distinct from `low`, since "hasn't been checked at all" is a different
(arguably riskier) claim than "checked but uncertain". `default` renders as plain neutral text with
no background tint, for citations that carry no confidence/verification signal at all.

**Known gotchas:**

- Enter and Space are given distinct meanings (Enter = activate via native `<button>` click, Space =
  open) — Space's native click-on-keyup is pre-empted with `preventDefault()` on keydown so it fires
  `lr-citation-open` instead of triggering a second `lr-citation-activate`.
- Escape closes the popover but calls `stopPropagation()`, so it won't also close a surrounding
  `<lr-dialog>` that has its own Escape-to-close handler.
- The preview slot's presence is tracked in JS (`hasPreviewSlot`), not via CSS `:empty` — the
  `[part="popover"]` always contains a literal `<slot>` child, so `:empty` would never match even
  with nothing assigned.

---

## `lr-source-list` / `lr-source-card`

A collapsible "Sources" panel for one chat message (`lr-source-list`) that groups a set of
`lr-source-card` entries. First-party invention (no Web Awesome equivalent). Cards are meant to be
direct light-DOM children of the list (plain composition — no `.items` array prop, the same shape
`<lr-multi-split>`'s panels take), though `lr-source-card` renders and functions fine standalone.

### `lr-source-list`

**Properties:**

- `expanded: boolean = false` (reflected) — whether the card list is currently shown. Starts
  collapsed by default so a message's sources don't eat vertical space until asked for.
- `label?: string` — header text used when `label-plural` isn't set, e.g. `"Sources"`.
- `labelPlural: string = ''` (attribute `label-plural`) — fully consumer-built, already-pluralized
  header summary, e.g. `"3 sources"` or `"1 source"`; this component never counts or pluralizes on
  its own. Takes precedence over `label` when both are set. If neither is set, the header falls back
  to the localized `sourceListDefaultLabel` string (English default: `"Sources"`).

**Getters:** `sourceCount: number` — read-only, live-updated count of the currently-slotted children,
handy for building a `label-plural` string reactively, e.g. `` list.labelPlural = `${list.sourceCount} sources` ``.

**Events:** `lr-toggle` (`detail: { expanded: boolean }`) — the header was activated, expanding or
collapsing the list.

**Slots:** default — `<lr-source-card>` elements, neutral `<div>`/`<span>` wrappers, or
author-owned `role="listitem"` entries. When every assigned child is one of those list-compatible
forms, `[part="list"]` supplies `role="list"` and neutral, unroled children temporarily receive
`role="listitem"`. Native controls and children with another explicit or native semantic role retain
their own semantics; their presence omits list/listitem roles rather than creating an invalid ARIA
list context. When every assigned child returns to this list-compatible allowlist, the
list/listitem semantics return.

**CSS parts:** `base` (outer container), `header` (the clickable `<button>` toggling `expanded`),
`toggle` (the chevron indicator inside the header), `list` (wrapper around the default slot, `hidden`
while collapsed).

**Themeable custom properties:** shared tokens only — `--lr-color-border`, `--lr-color-surface`,
`--lr-color-text`, `--lr-color-brand` / `-brand-quiet`, `--lr-radius`, `--lr-space-xs`/`-s`/
`-m`, `--lr-transition-fast`, `--lr-focus-ring-*`.

**Optional peer deps:** none.

### `lr-source-card`

**Properties:**

- `sourceId: string = ''` (attribute `source-id`) — stable identifier matching a
  `<lr-citation-badge>` elsewhere on the page.
- `title: string = ''` — the source's display title, e.g. a filename. Falls back to `"Untitled
source"` when empty.
- `page?: string | number` — optional page reference, e.g. `12` or `"iv"`, rendered as-is (never
  parsed/validated as a number), appended to the title as `" — p. {page}"`.
- `href?: string` — optional URL, echoed back (unopened) in `lr-open`'s detail.
- `compact: boolean = false` (reflected) — tighter root padding and row gap, for the dense citation
  lists these cards usually render in — the same convention as `lr-empty`'s `compact`. Purely a
  density knob: the border and background stay. `false` (the default) keeps the full card padding.
- `frame: LyraFrame = 'card'` (reflected) — container treatment, in the library-wide `frame`
  vocabulary (`'card' | 'plain'`). `'card'` (the default) keeps the bordered, filled, padded box;
  `'plain'` removes the border, background, padding and corner radius, so a card inside a
  `<lr-source-list>` (or any container already drawing its own border/dividers) doesn't double it.
  `plain` wins over `compact` when both are set — nothing left to tighten. The title and toggle keep
  their brand color and hover underline under `plain`, since neither ever depended on the card
  chrome. Use the shared `LyraFrame` type when authoring this property.
- `disabled: boolean = false` (reflected) — turns off this card's OWN controls. The `title` button
  and the "Show more"/"Show less" `toggle` both render `disabled`, so neither one can emit `lr-open`
  or `lr-expand` and neither remains in the tab order, and the card paints at
  `--lr-opacity-disabled` with a `not-allowed` cursor on both. The one `lr-expand` a disabled card
  can still emit is the automatic collapse when the `full` slot empties while expanded — that
  reports a state change the card genuinely made, exactly as it does when enabled. Both buttons
  carry the native `:disabled`, so `::part(title):disabled` / `::part(toggle):disabled` restyle the
  disabled affordance from outside. Every self-rendered sub-control is
  gated, not just the primary one: a card whose title is inert but whose disclosure toggle still
  expands reads as half-broken rather than disabled. Slotted `excerpt`/`full` content stays yours
  to disable. Not form-associated, so an ancestor `<fieldset disabled>` does not cascade here.
- `aria-pressed` and `aria-current` (attributes only) — forwarded reactively onto the `title`
  button, the control that carries this card's action, the same mechanism `<lr-button>` and
  `<lr-icon-button>` use. `aria-pressed` accepts `'true' | 'false' | 'mixed'`; `aria-current`
  accepts `'page' | 'step' | 'location' | 'date' | 'time' | 'true' | 'false'`. Anything outside
  those sets is dropped rather than passed through. The `toggle` button never receives either — it
  already owns `aria-expanded` for its own disclosure state, and two conflicting state claims on
  one control is worse than one. This is what lets a single-select citation list announce which
  source is the active one.

**Events:**

- `lr-expand` (`detail: { sourceId: string; expanded: boolean }`) — the per-card "Show
  more"/"Show less" toggle was activated. Unrelated to the parent `lr-source-list`'s own
  expand/collapse, which only ever hides/shows the _set_ of cards, never a single card's own content.
- `lr-open` (`detail: { sourceId: string; href?: string }`) — the title was activated. This
  component never navigates on its own (a controlled component, the same convention
  `<lr-tool-call-chip>`'s `lr-tool-call-chip-select` follows); a listener decides what "open"
  means.

**Slots:** `excerpt` (a short preview; when left empty, the `excerpt` part collapses away entirely —
its wrapper is `hidden`, not just visually empty), `full` (the complete source text/chunk, hidden
behind the "Show more"/"Show less" toggle — when left empty, no toggle renders at all; removing all
`full`-slotted content while expanded auto-collapses it back).

**CSS parts:** `base` (outer container), `title` (the clickable title/page heading, a `<button>`),
`excerpt` (wrapper around the `excerpt` slot, `hidden` when the slot has no assigned content), `full`
(wrapper around the `full` slot, `hidden` while collapsed), `toggle` (the "Show more"/"Show less"
button — only rendered when the `full` slot has content).

**Themeable custom properties:** `--lr-source-card-bg` (default `var(--lr-color-surface)`) —
`[part='base']`'s RESTING background, the companion to the `compact` tier's levers below;
`frame='plain'` still drops the fill entirely. `--lr-source-card-compact-padding` (default
`var(--lr-space-xs)`) —
`[part='base']`'s padding while `compact`; `--lr-source-card-compact-gap` (default
`var(--lr-space-2xs)`) — the gap between `[part='base']`'s rows while `compact`. Both apply only in
the `compact` state, so a dense citation list can be tuned without re-pointing shared spacing tokens
elsewhere. Plus shared tokens — `--lr-color-border`, `--lr-color-surface`,
`--lr-color-text` / `-text-quiet`, `--lr-color-brand`, `--lr-radius`, `--lr-space-xs`/`-s`,
`--lr-focus-ring-*`.

**Optional peer deps:** none.

```html
<lr-source-list label-plural="2 sources">
  <lr-source-card source-id="doc-1" title="annual_report.pdf" page="12">
    <span slot="excerpt">Revenue grew 12% year over year...</span>
    <span slot="full"
      >Revenue grew 12% year over year, driven primarily by...</span
    >
  </lr-source-card>
  <lr-source-card source-id="doc-2" title="q3_notes.md">
    <span slot="excerpt">No matching full-text chunk for this source.</span>
  </lr-source-card>
</lr-source-list>
<script type="module">
  // Elsewhere, a <lr-citation-badge>'s activation handler can scroll to and
  // highlight the matching card -- neither component needs extra API surface
  // for that, only source-id to be targeted by:
  document.addEventListener("lr-citation-activate", (e) => {
    const card = document.querySelector(
      `lr-source-card[source-id="${e.detail.sourceId}"]`
    );
    card?.scrollIntoView({ block: "center" });
  });
</script>
```

`lr-source-list` removes the card list from the accessibility tree (not just visually hides it)
while collapsed, via the native `hidden` attribute on `[part="list"]` — a screen reader user tabbing
past the header never lands on off-screen source cards they can't currently see. Both components
track slot presence in JS state (`slottedCount` on the list, `hasFullSlot` on the card) rather than
relying on CSS `:empty`, since a `[part]` wrapper always contains a literal `<slot>` child regardless
of assigned content; both also reconcile that state in `firstUpdated()` as a fallback for slot-
forwarding scenarios or engines that don't fire `slotchange` for content already present at parse
time.

**Known gotchas:**

- `lr-source-list` does not automatically build an “N sources” plural summary: provide
  `labelPlural` when that is wanted. Its no-label fallback is localized through
  `sourceListDefaultLabel`, and a per-instance `.strings` override reaches the rendered header.
- `lr-source-card`'s own expand/collapse (`full` slot, `lr-expand` event) is completely
  independent of the parent list's `expanded`/`lr-toggle` — collapsing the list doesn't reset an
  individual card's `fullExpanded` state, and there is no cross-talk between the two components at
  all beyond DOM nesting.
- `lr-source-card` actively strips a bare host-level `title` attribute right after Lit syncs it into
  the `title` property — otherwise the whole card would grow an unsolicited native tooltip repeating
  the title text on hover. Set `title` only as a property/attribute meant to become the rendered
  heading; don't rely on it surviving as a DOM attribute afterward.

---

## `lr-entity-dossier`

Entity detail surface: a persistent header (`lr-entity-card` + an optional confidence `lr-stat`)
above an `lr-tab-group` strip for Relationships (`lr-neighbor-list`), Supporting chunks
(`lr-chunk-inspector`), and Provenance (`lr-provenance-panel`). Pure layout — never fetches, ranks,
or mutates graph/document state.

**Properties:**

- `entity: LyraEntity | null = null` (attribute: false) — `lr-entity-card`'s own `LyraEntity`;
  `null` renders the shared `lr-empty` `noData` state in place of the whole dossier
- `confidence: LyraEntityDossierConfidence | null = null` (attribute: false) —
  readonly `LyraEntityDossierConfidence { label: string; value: string; unit?: string; variant?:
LyraVariant; exactValue?: string; caption?: string; rows?: readonly StatRow[] }` (exported by this
  module; `LyraVariant`
  is the shared semantic variant vocabulary and `StatRow` is `lr-stat`'s row type). All
  caller-supplied domain data, never routed through
  `localize()`. `null` omits the stat entirely — no placeholder
- `neighbors: LyraNeighborRow[] = []` (attribute: false) — forwarded verbatim to
  `lr-neighbor-list.rows` (`{ relation: string; direction: 'in' | 'out' | 'both'; node: LyraEntity }`)
- `chunks: LyraChunk[] = []` (attribute: false) — forwarded to `lr-chunk-inspector.chunks`; the
  evidence for _this entity's own_ summary/properties
- `provenance: LyraProvenance | null = null` (attribute: false) — forwarded to
  `lr-provenance-panel.provenance`; deliberately a separate input from `chunks` (the broader
  grounding chain, which may span other entities/relationships/communities). Pass the same array to
  both when the two genuinely coincide
- `types: LyraNodeTypeStyle[] = []` (attribute: false) — readonly `{ id: string; label: string; color?: string;
shape?: 'circle' | 'square' | 'diamond' }`, the `lr-graph.nodeTypes` entry shape; forwarded to both
  `lr-entity-card` and `lr-provenance-panel`
- `thresholds: { high: number; medium: number } = { high: 0.75, medium: 0.5 }` (attribute: false) —
  forwarded to both `lr-chunk-inspector` and `lr-provenance-panel`
- `groupByRelation: boolean = false` (attribute `group-by-relation`) — forwarded to `lr-neighbor-list`
- `expandable: boolean = false` — forwarded to `lr-neighbor-list`
- `showFocusButton: boolean = true` (attribute `show-focus-button`) — forwarded to `lr-entity-card`
- `communityLabel: string = ''` (attribute `community-label`) — forwarded to `lr-entity-card`
- `accessibleLabel: string | null = null` (attribute `aria-label`) — as a JS-only property while
  the host attribute is absent, names the internal `lr-tab-group` strip. Authored host
  `aria-label` names the dossier as a whole and is not cloned onto the strip

**Events:** declares none of its own. Every composed child's event bubbles through unmodified
(`composed: true`): `lr-entity-select` (`detail: { entityId }`, surfaced from the embedded entity
card or neighbor list), `lr-entity-activate` (`detail: { entityId, occurrenceIndex? }` — surfaced
from the embedded provenance panel's own community card or relationship path strip, the only
source carrying `occurrenceIndex`), `lr-node-expand` (`detail: { nodeId }`),
`lr-chunk-open` (`detail: { chunkId, sourceId, anchor? }`), `lr-expand` (`detail: { chunkId, expanded }`),
`lr-toggle` (`detail: { section, expanded }`), and `lr-tab-show`
(`detail: { tabId: LyraEntityDossierTab }`, where `LyraEntityDossierTab = 'relationships' | 'chunks'
| 'provenance'` — also the `lr-tab-group` slot/tab ids). The Provenance tab's own controls reach the
host the same way and are typed here too: `lr-entity-open` (`detail: { entityId }`, an entity chip
double-click or Space), `lr-drill` (`detail: { communityId }`, a community card's title, drill button, or
overflow chip), and `lr-relation-activate` (`detail: { relation, sourceNodeId?, targetNodeId?, occurrenceIndex }`, a
relationship path-strip edge).

**Slots:** none.

**CSS parts:** `base` (root, or the empty state's wrapper), `empty` (shown when `entity` is `null`),
`header`, `entity-card`, `confidence` (only when `confidence` is set), `tabs`, `neighbor-list`,
`chunk-inspector`, `provenance-panel`.

**Themeable custom properties:** shared tokens only.

**Optional peer deps:** none.

**Known gotchas:**

- The active tab is internal `@state`, not a controlled property — `lr-tab-group` already owns it, and a
  stale public property re-bound on an unrelated re-render would fight the user's own click.
- Tab labels reuse each composed child's own `localize()` key (`neighborListLabel`,
  `chunkInspectorLabel`, `provenancePanelLabel`), so a locale only translates each string once.

---

## `lr-grounding-summary`

Claim-level grounding scorecard for one generated answer: supported/unsupported claim counts,
citation coverage, optional confidence, warnings, and evidence citations linking back to their exact
spans. Consumes `GroundingAssessment` from `@aceshooting/lyra-ui/ai` directly. Pure projection +
event conduit — never fetches or computes an assessment. Composes `lr-stat` for every numeric display
and `lr-citation-badge` for each evidence entry.

**Properties:**

- `assessment: GroundingAssessment | null = null` (attribute: false) — **`GroundingAssessment`,
  imported from `@aceshooting/lyra-ui/ai`**: `{ supportedClaims: number;
unsupportedClaims: number; coverage: number; confidence?: number; warnings?: string[];
claims?: GroundedClaim[] }`, where `coverage` and `confidence` are 0–1 fractions. `null` renders
  the empty state
- `citations: Citation[] = []` (attribute: false) — **`Citation` from `@aceshooting/lyra-ui/ai`**:
  `{ id: string; chunkId?: string; sourceId?: string; span?: { start: number; end: number };
label?: string }`. Independent of `assessment`; empty omits the whole evidence section. Each entry
  renders as an `lr-citation-badge` whose `index` is its 1-based position and whose `source-id` is
  `citation.sourceId ?? ''`
- `thresholds: LyraScoreThresholds = { high: 0.8, medium: 0.5 }` (attribute: false) —
  readonly `LyraScoreThresholds { high: number; medium: number }`, with both
  0–1 fractions,
  applied to both `coverage` and `confidence`: `>= high` → `success` tone, `>= medium` → `warning`,
  below → `danger`
- `label?: string` — fallback name for the stable group, using localized
  `groundingSummaryLabel` when omitted. A non-empty host `aria-label` makes the host the sole overall
  owner (the group omits its duplicate role/name); an explicitly empty host label stays empty
- `showClaims: boolean = true` (attribute `show-claims`) — renders `assessment.claims` through
  `lr-claim-evidence`; set false to keep the aggregate scorecard only
- `headingLevel: LyraHeadingLevel = '3'` (attribute `heading-level`) — shared semantic heading
  level used by both warnings and evidence sections; `'none'` keeps the visual text without
  exposing a heading role, and invalid untyped values fall back to level 3

Direct citations and `assessment.claims` are keyed independently by nonblank `id` before counts,
rendering, or events. Usable display fields are captured once while emitted selected claim/citation
objects retain their original identity. Malformed rows and later duplicate ids are omitted; the
first valid occurrence wins.

**Events:** `lr-citation-select` (`detail: CitationSelectEventDetail` from
`@aceshooting/lyra-ui/ai` = `{ citation: Citation }`) — emitted when an evidence badge is activated.
The inner `lr-citation-badge`'s generic activation is stopped at this composition boundary; this
richer event exists because a bare `sourceId`/`index` pair cannot identify the exact evidence span.
The summary emits `lr-claim-select` (`detail: { claim }`) when a claim is activated.

**Slots:** none.

**CSS parts:** `base` (the `role="group"` root unless a non-empty host label owns the component),
`stats` (the claim-count/coverage/confidence `lr-stat`
row), `warnings` (omitted when there are none), `warnings-heading`, `warnings-count`,
`warnings-list` (a `<ul>`), `warning` (one `<li>`), `evidence` (omitted when `citations` is empty),
`evidence-heading` (a real `h1`–`h6`), `evidence-count`, `evidence-list` (a `<ul role="list">` so
its semantics survive list-style resets),
`evidence-item` (one `<li>` containing a badge + always-visible label/span text),
`evidence-label` (omitted when `Citation.label` is unset), `evidence-span` (the formatted
`Citation.span` range, omitted when unset), `claims` (the claim/evidence region), `empty`
(shown when `assessment` is `null`).

**Themeable custom properties:** shared tokens only.

**Optional peer deps:** none.

---

## `lr-ingestion-queue`

Controlled list of documents moving through an ingestion pipeline: stage badge, progress, chunk/
embedding counts, retry attempts, errors, and retry/cancel requests. Never ingests anything itself.

Nonstring failure details use the localized failed-stage label for row text and fresh failure
announcements. Omitted details stay omitted. Formatting uses the effective locale, and historical
failures remain silent on mount.

**Properties:**

- `items: IngestionQueueItem[] = []` (attribute: false) — `IngestionQueueItem { id: string;
document: DocumentRef; stage: IngestionStage; progress?: number; chunkCount?: number;
embeddedChunkCount?: number; attempts?: number; error?: string }` (exported here). `document` is
  **`DocumentRef` from `@aceshooting/lyra-ui/ai`** (`{ id, name, mimeType?, uri?, version? }`), not a
  divergent name/mimeType pair, so a caller can reuse the same list a `DocumentRef`-typed
  knowledge-base view already holds. `IngestionStage = 'queued' | 'uploading' | 'extracting' |
'chunking' | 'embedding' | 'indexing' | 'done' | 'failed' | 'cancelled'` — the first six are
  in-flight (in pipeline order), the last three terminal. `progress` is 0–100 _within the current
  stage_ (omitted/non-finite renders an indeterminate indicator, and it is only meaningful during an
  active non-`'queued'` stage). `embeddedChunkCount` renders only alongside a defined `chunkCount`.
  `error` renders only while `stage === 'failed'`. A missing or unrecognized runtime stage renders
  as a localized neutral `unknown` state with no progress, retry, or cancel affordance, allowing a
  newer backend stage to fail safely. Controlled — pass a new array to update
- `label?: string` — fallback name for the stable region; omission uses localized
  `ingestionQueueLabel`. A non-empty host `aria-label` makes the host the sole overall owner (the
  region omits its duplicate role/name); an explicitly empty host label stays empty
- `virtualizeAt: number = 100` (attribute `virtualize-at`) — item count above which the list renders
  through an internal `lr-virtual-list`. Exclusive, like every other `virtualize-at` in this family:
  exactly this many items still render as a plain list. Before 9.0.0 this was spelled
  `virtualizeThreshold`/`virtualize-threshold` _and_ compared inclusively (`>=`), so a migration
  that only renames the attribute shifts the switchover point by one item
- `announce: boolean = false` (reflected) — opt-in: announce the failures the queue **already
  carries** the first time it mounts, instead of staying silent until a row fails later. The
  mount-time pass reuses the one announcement path a later failure takes — the same shared
  assertive light-DOM region, the same locale-aware conjunction list of the caller-supplied
  `item.error` strings, and the same `[part="failure-live"]` mirror — so an opted-in mount reads
  exactly what a live failure would. Set it where the queue is created in response to something
  the user just did: a retried ingestion run that mounts a fresh queue already holding
  `stage="failed"` rows would otherwise never speak them. Leave it unset for a queue that is part
  of the page a user is arriving on — those rows render in document order and repeating them is
  noise. Read once per element lifetime: a later reconnection or adoption stages the same rows
  again rather than replaying the announcement, and failures added or changed after mount announce
  either way. A queue carrying no `stage="failed"` row with an `error` announces nothing. Remove
  any host `role="status"`/`role="alert"` hand-added before this property existed once it is set —
  otherwise the initial failures are announced twice, through the native role and again through
  the shared sink

Queue item ids must be nonblank and unique. Malformed rows and later duplicates are omitted
first-wins before empty state, counts, virtualization, failure announcements, rendering, or actions.

**Events:**

- `lr-retry` (`detail: IngestionRetryEventDetail` = `RetryEventDetail & { itemId: string }` =
  `{ attempt: number; messageId?: string; itemId: string }`) — `attempt` is the attempt about to be
  made: the displayed nonnegative finite-integer `item.attempts` value plus one (invalid, negative,
  or fractional inputs are normalized first). Only offered on `'failed'` rows.
- `lr-cancel` (`detail: IngestionCancelEventDetail` = `CancelEventDetail & { itemId: string }` =
  `{ reason?: string; itemId: string }`) — this component never supplies `reason` itself. Only
  offered on non-terminal rows (`'queued'` plus the five active stages).

Both `RetryEventDetail` and `CancelEventDetail` come from `@aceshooting/lyra-ui/ai`.

**Slots:** none.

**CSS parts:** `base`, `list`, `item`, `item-header`, `item-name`, `item-meta`, `item-stage` (the
per-item stage label), `item-progress`,
`item-chunk-count`, `item-embedding-status` (the "N of M chunks embedded" text, only once both
`chunkCount` and `embeddedChunkCount` are set), `item-attempts` (only once `attempts > 0`),
`item-error` (only for `stage="failed"` with `error` set), `failure-live` (the visually hidden,
`aria-hidden` mirror of the last announced batch of fresh failures), `item-actions`,
`retry-button`, `cancel-button`, `empty`.

`failure-live` is a styling and inspection surface and carries no live-region role of its own. The
announcement itself goes to the library's shared **light-DOM** assertive region, appended to the
consumer's `<body>` and marked `data-lr-live-region="assertive"`, because a live region inside a
shadow root is not reliably announced (JAWS with Firefox ignores one outright). What is announced
is unchanged: only failures added or transitioned _after_ mount, so historical failed rows stay
visible without being re-announced. Read that document-level region rather than
`::part(failure-live)`.

In virtualized mode (above `virtualizeAt`) the rows live in the internal
`lr-virtual-list`'s shadow root, and `item`, `item-header`, `item-name`, `item-progress`,
`item-meta`, `item-stage`, `item-chunk-count`, `item-embedding-status`, `item-attempts`, `item-error`,
`item-actions`, `retry-button` and `cancel-button` are forwarded out through `exportparts`, so every
documented row part remains reachable as `lr-ingestion-queue::part(...)` above and below the
virtualization threshold.

**Themeable custom properties:** `--lr-ingestion-queue-max-height` (default `none`) — non-virtualized
mode only: caps how tall the list grows before it scrolls internally. No effect once virtualized —
retheme the internal list via `lr-virtual-list { --lr-virtual-list-height: … }` instead.

**Optional peer deps:** none.

---

## `lr-knowledge-base`

Controlled source list for a retrieval knowledge base: sync status, indexing health, permissions, and
per-row create/sync/pause/delete requests. Composes `lr-table`, `lr-badge`, `lr-stat`, and a per-row
`lr-dropdown` containing `lr-menu`. Never syncs or indexes anything itself.

**Properties:**

- `sources: KnowledgeSource[] = []` (attribute: false) — `KnowledgeSource { id: string; name: string;
type?: string; syncStatus: KnowledgeSourceSyncStatus; indexingHealth?: KnowledgeSourceIndexingHealth;
permission?: KnowledgeSourcePermission; documentCount?: number; lastSyncedAt?: Date | string;
errorMessage?: string }` (all four types exported here), where
  `KnowledgeSourceSyncStatus = 'idle' | 'syncing' | 'paused' | 'synced' | 'error'`,
  `KnowledgeSourceIndexingHealth = 'healthy' | 'degraded' | 'failed' | 'unknown'` (absent is treated
  as `'unknown'`), and `KnowledgeSourcePermission = 'owner' | 'editor' | 'viewer' | 'restricted'`.
  `type` is a free-form connector kind (`'drive'`, `'notion'`, `'upload'`, `'url'`, …) rendered
  as-is. `lastSyncedAt` follows this library's `Date | string` timestamp convention (epoch ms Date or
  ISO-8601); absent/unparseable renders "never synced". `errorMessage` shows only while
  `syncStatus === 'error'`. `id`/`name` follow `DocumentRef`'s spirit, but a source is a _connector
  feeding_ documents, not a document, so the rest of the fields are its own
- `label?: string` — heading text and the table's accessible name; omission uses the localized
  knowledge-base label. An explicit empty string keeps the visible heading empty while the nested
  table still takes the localized default as its accessible name
- `hideSummary: boolean = false` (attribute `hide-summary`, reflected) — hides the aggregate
  total/synced/syncing/needs-attention row
- `hideCreate: boolean = false` (attribute `hide-create`, reflected) — hides the "Add source"
  affordance, e.g. for a read-only or permission-gated view
- `error: boolean = false` (reflected) — reports a failed source-list load. Forwarded to the nested
  `lr-table`, whose own built-in failed-load state (with retry button) replaces the source rows
  while it's set; `error` beats the empty state, matching `lr-table`'s own precedence
- `errorHeading?: string` (attribute `error-heading`) — failed-load heading override, forwarded to
  the nested table. Omitted localizes the table's own `tableLoadFailed` default
- `errorDescription: string = ''` (attribute `error-description`) — failed-load supporting copy,
  forwarded to the nested table

Source ids must be nonblank and unique. Malformed rows and later duplicates are omitted first-wins
before summary totals, empty state, table rows, or source actions. A retained source whose `name` is
missing, blank, or nonstring uses the localized “untitled source” label in both the row and its action
names.

**Events:** `lr-source-create` (`detail: null` — nothing exists yet to reference),
`lr-source-sync` (`detail: { sourceId: string }`), `lr-source-pause` (`detail: { sourceId: string }`),
`lr-source-delete` (`detail: { sourceId: string }`, no built-in confirmation, matching
`lr-thread-list`'s `lr-thread-delete`). These were spelled `lr-kb-create`/`-sync`/`-pause`/`-delete`
before 9.0.0 — the library's only abbreviated event prefix. `<lr-knowledge-base-admin>` already
re-emitted them under the `lr-source-*` names, so a host listening on the admin shell needs no
change; a host listening directly on `<lr-knowledge-base>` renames its four listeners.
`lr-retry` (`detail: null`, cancelable) — the nested table's built-in retry button was activated,
only rendered while `error` is set; the default action clears `error`, `preventDefault()` leaves it
set. This component intercepts the nested table's own `lr-retry` and re-proposes its own, so the
outer `error` property never drifts out of sync with the table's internal state.

**Slots:** `error` — replaces the nested table's built-in failed-load state, including its retry
button, while `error` is set.

**CSS parts:** `base`, `toolbar` (heading + "Add source" row), `heading` (the heading text),
`create-button` (omitted while `hideCreate`), `summary` (omitted while `hideSummary` or `sources` is
empty), `summary-stat`, `table`, `name-cell`, `source-name`, `source-type` (omitted when `type` is
unset), `sync-cell`, `sync-badge`, `sync-timestamp`, `sync-error`, `health-cell`, `health-badge`,
`document-count` (omitted when unset), `permission-badge` (omitted when `permission` is unset),
`actions-menu`, `actions-trigger` (the kebab `<button>`), `error-row`, `error-cell`, `error` (the
nested table's built-in `lr-empty` host), `error-base`, `error-icon`, `error-heading`,
`error-description`, `error-actions`, `retry-button`.

The row and error-state parts — `name-cell`, `source-name`, `source-type`, `sync-cell`, `sync-badge`,
`sync-timestamp`, `sync-error`, `health-cell`, `health-badge`, `document-count`,
`permission-badge`, `actions-menu`, `actions-trigger`, `error-row`, `error-cell`, `error`,
`error-base`, `error-icon`, `error-heading`, `error-description`, `error-actions`, and
`retry-button` — are forwarded from the composed table through `[part="table"]`/`exportparts`, so
they are styleable as `lr-knowledge-base::part(actions-trigger)`. `actions-trigger` is the forwarded
kebab button: it inherits the row font, has the shared `--lr-icon-button-size` minimum hit area
(40px by default), and keeps independent hover, pressed, and focus treatment.

**Themeable custom properties:** shared tokens only.

**Optional peer deps:** none.

**Known gotchas:**

- `permission` is rendered informationally only — the per-row action menu is never gated by it.
  Authorization enforcement is the host's concern.
- "Sync now" is disabled only while `syncStatus === 'syncing'` (including on `'error'` rows, so
  re-running a failed sync is one click); "Pause sync" is enabled only while `'syncing'`.
- The inner `lr-table`'s own `lr-row-click` is deliberately stopped from propagating — this component
  exposes no row-click/selection semantics, only the per-row action menu.

---

## `lr-knowledge-graph-explorer`

Orchestration-level knowledge-graph surface: the `lr-graph` canvas plus entity search, type filters,
neighborhood expansion, pinned nodes, path finding between pins, node selection, and a details
overlay. Composes `lr-graph`, `lr-graph-legend`, `lr-entity-card`, `lr-neighbor-list`,
`lr-path-strip`, and `lr-popover.showAt()`.

Removing `search-query` retains `null` property readback while clearing the search input, results
and search dimming; an explicitly empty value remains empty and later queries work normally.
Path-node `lr-entity-activate` is consumed by the explorer and enters the same selection, graph
focus and details flow as other entity activations, emitting one `lr-selection-change`.
`lr-relation-activate` continues to pass through unchanged. The canonical search event fields remain
`query`, `matchCount`, and `matchCountExact`.

**Properties:** (host-supplied data, identity-normalized before rendering)

- `nodes: LyraGraphNode[] = []`, `links: LyraGraphLink[] = []`, `nodeTypes: LyraNodeTypeStyle[] = []`,
  `communities: LyraGraphCommunity[] = []` (all attribute: false) — exactly `lr-graph`'s own types,
  projected through `lr-graph`'s shared nonblank, first-wins identity policy before derived lookups
  and forwarding: `LyraGraphNode { id: string; label?: string; accessibleLabel?: string;
  description?: string; radius?: number; color?: string; type?: string; expandable?: boolean;
  communityId?: string }`, `LyraGraphLink { id?: string; source: string; target: string; width?:
  number; label?: string; accessibleLabel?: string; description?: string; directed?: boolean;
  color?: string; dash?: number[] }` (source/target are node ids), `LyraNodeTypeStyle { id: string;
  label: string; color?: string; shape?: 'circle' | 'square' | 'diamond' }`, and
  `LyraGraphCommunity { id: string; label?: string; memberIds: string[]; color?: string }` — the full
  field-by-field semantics (color/shape resolution precedence, dangling-link handling, hull
  membership, etc.) are documented in `llms/components/lr-graph.md`'s own **Properties** list
- `entityDetails: Record<string, LyraKnowledgeGraphEntityDetails> = {}` (attribute: false) —
  `LyraKnowledgeGraphEntityDetails = Pick<LyraEntity, 'description' | 'properties' | 'degree'>`, i.e.
  `{ description?: string; properties?: Record<string, string | number>; degree?: number }`, keyed by
  node id. Merged onto the matching `LyraGraphNode` to build the entity shown in the details popover and
  neighbor rows. A node with no entry still renders: `degree` falls back to a live count derived from
  `links`, `description`/`properties` are omitted
- `path: LyraPathElement[] = []` (attribute: false) — host-supplied path-finding _result_, rendered
  via `lr-path-strip` (`{ kind: 'node'; node: LyraEntity } | { kind: 'edge'; relation: string;
directed?: boolean; reverse?: boolean }`). Empty renders no strip

(self-managed but presettable/observable — this component toggles its own copy on interaction, the
same self-toggle-then-emit contract `lr-graph-legend` uses, so every feature works with zero host wiring)

- `hiddenTypes: string[] = []` (attribute: false) — forwarded to both `lr-graph.hiddenTypes` and
  `lr-graph-legend.hiddenTypes`; hidden nodes are also excluded from explorer search results,
  neighbor rows, and activation
- `selectedNodeId: string | null = null` (attribute `selected-node-id`) — drives the details popover
  and `lr-graph.selectedNodeIds`; `null` shows no selection and keeps the popover closed
- `pinnedNodeIds: string[] = []` (attribute: false) — exactly two pinned nodes reveals the "Find
  path" action
- `searchQuery: string = ''` (attribute `search-query`) — the filter applied to the visible node
  set, driving `[part="search-results"]` and the search-match dimming forwarded to `lr-graph`. A node
  matches when the query appears in **any** name it can be known by — its `id`, its `label` or its
  `accessibleLabel` — each folded with the active locale, so a node named only through
  `accessibleLabel` is findable by the very name the search results, pinned chips and details
  popover already display for it, and a node carrying both a `label` and an `accessibleLabel` matches
  either. Presettable, so a host can deep-link straight into a filtered view; the toolbar's search
  box keeps it up to date afterwards. A missing or nonstring `label`/`accessibleLabel` is skipped
  while the node's valid string id remains searchable

(presentation)

- `renderer: 'svg' | 'canvas' = 'svg'` — forwarded to `lr-graph.renderer`
- `fitTo: 'none' | 'container' = 'none'` (attribute `fit-to`) — forwarded to `lr-graph.fitTo`.
  `'container'` makes the composed graph draw at exactly the pane this component's own layout gave
  it — the reservation minus whatever the toolbar, search results, pinned row and path strip take,
  which is not derivable from `height` — and follow it live as the explorer is resized. `'none'`
  keeps forwarding the numeric `width`/`height` below unchanged. See `fitTo`'s own entry in
  `llms/components/lr-graph.md`
- `width: number = 800`, `height: number = 600` — `height` also sizes the composed graph's own
  rendered box (`[part="graph"]`) once the explorer's own layout gives it room, the same fallback
  chain `lr-graph.height` uses on its own host
- `nodeLabels?: 'always' | 'zoom' | 'none'` (attribute `node-labels`) — forwarded to
  `lr-graph.nodeLabels`. Unset (the default) leaves the composed `lr-graph` to apply its own
  per-renderer default — see `nodeLabels`'s own entry in `llms/components/lr-graph.md`
- `highlight: 'selection' | 'hover' | 'none' = 'selection'` — what drives the dimming forwarded to
  `lr-graph`'s `dimmedNodeIds`/`dimmedLinkIds`, on top of the always-active search-match dimming:
  `'selection'` dims by the selected node's immediate neighborhood; `'hover'` additionally dims by
  the pointer-hovered node (falling back to selection while nothing is hovered); `'none'` forwards
  empty arrays regardless of search/selection state, for a host driving dimming its own way
- `label?: string` — fallback name for the root group; omission uses localized
  `graphExplorerLabel`. A non-empty host `aria-label` makes the host the sole overall owner; an
  explicitly empty host label stays empty on the group

**Events:**

- `lr-selection-change` (`detail: { selectedNodeId: string | null }`) — emitted after the explorer
  changes its own selection through search, graph, keyboard/neighborhood/path activation, or
  closing/invalidating the details selection. Clearing reports `null`. Direct host assignments to
  `selectedNodeId` remain silent, and one interaction emits at most once even when a composed
  child also reports its primitive click event.
- `lr-path-request` (`detail: { sourceNodeId: string; targetNodeId: string }`) — the "Find path" action was
  activated with exactly two nodes pinned. This component has no traversal algorithm; the host
  computes/fetches the path and assigns it back through `path`.
- `lr-pin-change` (`detail: { pinnedNodeIds: string[] }`) — the complete updated array. Already
  self-applied before emitting, so reassigning back is optional.
- `lr-hidden-types-change` (`detail: { hiddenTypes: string[] }`) — a node type's visibility changed
  via the composed legend. Follows the same self-toggle-then-emit contract as `lr-pin-change`/
  `lr-search-change`, so reassigning back is optional.
- `lr-search-change` (`detail: { query: string; matchCount: number; matchCountExact: boolean }`) —
  the user typed in the toolbar's search box. `query` is the canonical `LyraSearchChangeDetail`
  field name. `matchCount` is the same live node-filter total the result list and its live-region
  announcement already compute (`0` while the query is empty). `matchCountExact` is always `true` —
  this component's node filter has no truncating ceiling, unlike a paginated text-search viewer.
  There is no `activeIndex`: this is a live node filter, not a cursor-based search. The component
  has already applied the query to its own `searchQuery` property before emitting, so reassigning
  it back is optional and a direct host assignment stays silent.
- Bubbling straight through from composed children, unmodified: `lr-node-click`
  (`detail: { nodeId, x, y }`), `lr-link-click` (`detail: { sourceNodeId, targetNodeId, linkId? }`), `lr-community-click`
  (`detail: { communityId }`), `lr-node-expand` (`detail: { nodeId }`, from `lr-graph` and/or `lr-neighbor-list`),
  `lr-relation-activate` (`detail: { relation, sourceNodeId?, targetNodeId?, occurrenceIndex }`, from `lr-path-strip`).

**Slots:** `details` — overrides the details popover's default content (an `lr-entity-card` with a
nested `lr-neighbor-list` and a pin toggle) entirely, including the two additive slots below.
Receives no data; an overriding consumer reads the selected entity from `selectedNodeId`/`nodes`
itself. `detail-body` — additive content appended inside the default `lr-entity-card`'s body,
alongside its `lr-neighbor-list`; no effect while `details` is overridden. `detail-actions` —
additive content appended into the default `lr-entity-card`'s `actions` slot, beside its built-in
pin toggle; no effect while `details` is overridden.

**CSS parts:** `base` (`role="group"` unless a non-empty host label owns the component), `toolbar`,
`search` (the search `lr-input`), `legend` (the
composed `lr-graph-legend`), `search-results` (only while `searchQuery` is non-empty),
`search-result` (`role="listitem"` wrapping a `<button>`), `search-empty`, `pinned` (only while
`pinnedNodeIds` is non-empty), `pinned-heading`, `graph` (the composed `lr-graph`), `path` (only
while `path` is non-empty), `detail-popover`, `detail-card`.

**Themeable custom properties:** `--lr-canvas-reserved-height` (default
`var(--lr-size-24rem)`) sets the explorer's host block size and matches its pre-upgrade
reservation. The composed graph's own `[part="graph"]` box additionally falls back to the
explorer's `height` property (through a private custom property) beneath this same reservation
name, so setting `--lr-canvas-reserved-height` anywhere above the explorer overrides `height` for
the composed graph too. Retheme the composed graph through `lr-graph`'s own custom properties — `--lr-node-fill`,
`--lr-link-color`, `--lr-graph-cat-1` through `-8`, `--lr-graph-edge-label-halo`,
`--lr-graph-focus-halo-color`, `--lr-graph-selected-color`, `--lr-graph-dimmed-opacity`, and
`--lr-graph-hull-fill`/`-opacity` — documented in `llms/components/lr-graph.md`'s own
**Themeable custom properties** list.

**Optional peer deps:** `lr-graph`'s `d3-force`/`d3-drag`/`d3-zoom`/`d3-selection` set, transitively.

**Known gotchas:**

- The host defaults to `--lr-canvas-reserved-height` (`24rem`). An explicit height on the host
  bounds the whole explorer: `[part="base"]` fills it and
  `[part="graph"]` takes whatever the toolbar, search results, pinned row and path strip leave over,
  rather than the graph sizing itself from its own intrinsic aspect ratio. Within that allocation,
  the composed graph's own `height` property still contributes its configured block size (subject
  to `--lr-canvas-reserved-height` winning, and to flex-shrink if the host itself has no room to
  grow) — it is not purely cosmetic even though the host's own footprint is governed separately.
- A node's displayed name (search results, pinned chips, the details popover's accessible name)
  resolves `LyraGraphNode.label || LyraGraphNode.accessibleLabel || LyraGraphNode.id` — a node with
  only a spoken `accessibleLabel` (no visible `label`) still shows that text instead of falling
  straight through to its raw id.
- `lr-graph.getNodePosition()` and `lr-node-click`'s `{ x, y }` are graph-_local_ drawing
  coordinates, never viewport pixels. For `renderer="svg"` this component resolves the real viewport
  rect from `event.composedPath()`'s `[part="node"]` element; for `renderer="canvas"` (no per-node
  DOM) it uses the click's `clientX`/`clientY`. While an svg-click popover stays open it re-anchors
  on every `lr-viewport-change` from the graph — no `requestAnimationFrame` polling loop.
- Selecting a node any _other_ way (search result, neighbor row, path element, keyboard Enter/Space
  on a graph node — which dispatches no native `click`) has no rect to read, so it calls
  `lr-graph.focusNode(id)` and anchors at the graph element's own bounding-box center instead; no
  continuous tracking applies on that path.

---

## `lr-memory-panel`

Agent working-memory surface: short-term context and long-term memories, each with confidence and
optional grounding provenance, and add/remove/forget actions gated behind an explicit confirmation.
Composes `lr-provenance-panel` (per-item provenance, behind a disclosure toggle) and `lr-confirm-bar`
(every confirmation).

**Properties:**

- `shortTerm: LyraMemoryItem[] = []` / `longTerm: LyraMemoryItem[] = []` (both attribute: false) —
  `LyraMemoryItem { id: string; text: string; confidence?: number; provenance?: LyraProvenance }`
  (exported here). `text` renders as plain text. `confidence` is 0–1; omit it and the confidence
  indicator is omitted entirely rather than showing 0%/unknown. `provenance` reuses
  `lr-provenance-panel`'s own `LyraProvenance` shape verbatim (`{ entities?; relationships?;
communities?; chunks? }`); omit it and the disclosure toggle is omitted entirely. Both arrays are
  controlled and never mutated here — approving an action only fires the matching event
- `types: LyraNodeTypeStyle[] = []` (attribute: false) — readonly `{ id: string; label: string; color?: string;
shape?: 'circle' | 'square' | 'diamond' }`, forwarded verbatim to every expanded item's
  `lr-provenance-panel`
- `thresholds: { high: number; medium: number } = { high: 0.75, medium: 0.5 }` (attribute: false) —
  confidence-tier boundaries (reusing `lr-citation-badge`'s high/medium/low confidence vocabulary and
  success/warning/danger tones), also forwarded as the provenance relevance tiers
- `label?: string` — fallback name for the stable overall group; omission uses the localized memory
  panel label. A non-empty host `aria-label`
  makes the host the sole overall owner; an explicitly empty host label stays empty

Each memory list is canonicalized independently by nonblank `id`. Malformed rows and later
duplicates are omitted first-wins before empty state, focus/disclosure state, confirmations, counts,
rendering, or actions. Rows whose `text` is missing, nonstring, blank, or whitespace-only are also
omitted without hiding later valid memories.

**Events:**

- `lr-add` (`detail: LyraMemoryAddDetail` = `{ memory: LyraMemoryItem }`) — a pending "promote to
  long-term" was approved; the short-term item as-is. Only offered on short-term items.
- `lr-remove` (`detail: LyraMemoryRemoveDetail` = `{ memoryId: string; scope: 'short-term' | 'long-term' }`)
  — a pending per-item removal was approved. Offered on every item.
- `lr-forget` (`detail: null`) — the pending "forget all long-term memories" bulk action was
  approved. Only rendered while `longTerm` is non-empty.
- `lr-expand` (`detail: LyraMemoryExpandDetail` = `{ memoryId: string; scope: 'short-term' |
'long-term'; expanded: boolean }`) — an item's provenance disclosure was toggled.

**Slots:** none.

**CSS parts:** `base`, `empty` (the all-empty `lr-empty`, shown when both lists are empty),
`section` (one of the two, carries `data-scope`), `section-header`, `heading` (a section's visible
heading text), `section-empty`, `list` (`role="list"`, omitted while that section is empty), `item`
(`role="listitem"`, carries `data-id`/`data-scope` and a stable `tabindex="-1"` so focus has
somewhere to land after a confirmation resolves), `item-row`, `item-text`, `confidence` (carries
`data-tone`; omitted when `confidence` is unset), `expand-toggle` / `item-body` (both omitted when
`provenance` is unset; `item-body` is `hidden` while collapsed), `item-actions`, `add-button`,
`remove-button`, `forget-all-button`, `forget-all-confirm` (the `lr-confirm-bar` that replaces
`forget-all-button` while the bulk confirmation is pending).

**Keyboard/focus contract:** activating an action from the keyboard replaces that control with an
`lr-confirm-bar`, and focus moves into the bar (landing on Deny, the safe action) rather than
falling to `<body>` when the control unmounts. Cancelling — Escape or Deny — returns focus to the
control the confirmation replaced: the row's own action for a per-item confirmation, and
`forget-all-button` for the bulk one. This holds through a controlled `shortTerm`/`longTerm`
replacement that closes an open confirmation. Escape only stops propagating when it actually closed
a confirmation, so it never blocks an enclosing dialog for nothing.

**Themeable custom properties:** `--lr-memory-panel-confidence-success-color` (default
`var(--lr-color-success)`), `--lr-memory-panel-confidence-warning-color` (default
`var(--lr-color-warning)`), `--lr-memory-panel-confidence-danger-color` (default
`var(--lr-color-danger)`) — text color of an item's `confidence` indicator, one per confidence
tier (`high`/`medium`/`low` against `thresholds`, the same tiering `lr-chunk-inspector` uses for
its score bar). Plus shared tokens otherwise.

**Optional peer deps:** none.

**Known gotchas:**

- At most one confirmation is pending at a time — starting a new action (same item or not) silently
  cancels whichever confirmation was already open.
- `remove` (one item, either list) and `forget` (the whole long-term list) are deliberately distinct
  actions; there is no per-item forget and no bulk remove.

---

## `lr-retrieval-results`

Orchestration-level ranked-chunk surface: takes raw `RetrievalChunk[]` and adds identity
canonicalization, optional source grouping, multi-selection, pagination/infinite loading, and a
compact/expanded switch. Each row wraps exactly one chunk in an internal `lr-chunk-inspector` (fed
a single-element array), reusing its score bar, tier coloring, title+page rendering, and expandable
text verbatim. Large sets window through an internal `lr-virtual-list`.

**Properties:**

- `chunks: RetrievalChunk[] = []` (attribute: false) — **`RetrievalChunk`, imported from
  `@aceshooting/lyra-ui/ai`**: `{ id: string; text: string; score: number;
source: DocumentRef; metadata?: Record<string, unknown>; rank?: number; locator?: DocumentLocator;
queryId?: string; stage?: string; traceId?: string; scores?: RetrievalScoreBreakdown }`. The raw,
  unsorted/ungrouped result set; host-owned. Blank ids and later duplicate ids are omitted
  first-wins before sorting, grouping, selection, rendering, or events. Internally mapped to
  `lr-chunk-inspector`'s flatter `LyraChunk` via `source.id → sourceId`, `source.name → title`, and
  `locator → anchor`; a `page`-kind `locator` additionally supplies the inspector's visible `page`.
  Nothing is ever guessed from `metadata` — a chunk with no `locator` simply leaves `anchor`/`page`
  unset
- `selectedChunkIds: string[] = []` (attribute: false) — controlled selection by chunk `id`. Blank
  ids, duplicates, and ids absent from the canonical chunk model are pruned. The component updates
  its own copy on toggle _then_ emits `lr-select`; reassign to control
- `selectable: boolean = true` (reflected) — shows a per-row `lr-checkbox`
- `dedupe: boolean = true` (reflected) — retained for compatibility; malformed, blank, and later
  duplicate chunk ids are always omitted first-wins so identity never becomes ambiguous
- `sort: 'score' | 'none' = 'score'` — `'score'` sorts descending; `'none'` preserves given order
- `grouping: 'source' | 'custom' | 'none' = 'none'` — `'source'` buckets rows under a header per
  `source.id` (the header text is that source's `name`, or a localized "untitled source" when it has
  none); `'custom'` buckets them under whatever key `groupBy` returns; `'none'` is a flat ranked
  list. Buckets appear in order of first appearance in the already-`sort`ed list, so with the default
  `sort="score"` that is best-scoring-chunk order, and with `sort="none"` it is the order the chunks
  arrived in. Grouping **always** virtualizes, regardless of `virtualizeAt`
- `groupBy?: (chunk: RetrievalChunk) => string` (attribute: false) — `grouping="custom"` only: the
  group id for each chunk (a date bucket, a relevance tier, a domain-specific bucket). Left unset,
  `'custom'` degrades to the same flat list `'none'` renders rather than inventing a key, so the
  built-in identity/sort/virtualization pipeline stays usable either way. The same escape hatch
  `lr-thread-list` already exposes
- `groupLabel?: (id: string, chunks: RetrievalChunk[]) => string` (attribute: false) —
  `grouping="custom"` only: the group's header text. Left unset, the group id is shown verbatim
- `groupOrder?: string[] | ((a: string, b: string) => number)` (attribute: false) —
  `grouping="custom"` only: explicit group-id order, or a comparator over the first-seen ids. Ids an
  array omits follow after the listed ones in their own first-seen order, never dropped
- `presentation: 'compact' | 'expanded' = 'expanded'` — `'expanded'` shows each chunk's full row
  (score bar, text preview with its own toggle) plus any `metadata`; `'compact'` shows title + score
  bar only and omits `metadata` entirely
- `thresholds: { high: number; medium: number } = { high: 0.75, medium: 0.5 }` (attribute: false) —
  forwarded to every per-row `lr-chunk-inspector`
- `virtualizeAt: number = 50` (attribute `virtualize-at`) — row count (after identity
  canonicalization, before grouping) above which rendering switches to the internal
  `lr-virtual-list`
- `activeChunkId: string = ''` (attribute `active-chunk-id`) — the chunk currently open in a viewer; forwarded
  to each row and to the virtual list (which scrolls the matching row into view)
- `loading: boolean = false` (reflected)
- `hasMore: boolean = false` (attribute `has-more`, reflected) — while virtualized, forwarded to the
  virtual list so scroll-near-bottom fires `lr-load-more`; otherwise shows the built-in footer button
- `errorText: string = ''` (attribute `error-text`; spelled plain `error` before 9.0.0) — non-empty
  replaces the whole result view with a neutral visible message. Caller-supplied text is not
  localized (app/network data, not library copy). A new non-empty value is announced through a
  shared assertive light-DOM region; initial and reconnect content is not replayed
- `announce: boolean = false` (reflected) — opt-in: announce the state the panel is **already
  presenting** the first time it mounts, rather than only announcing later transitions into it.
  Urgency follows the state, exactly as the live path does and in the same branch order the panel
  renders: a non-empty `errorText` wins and is announced verbatim through the shared assertive
  light-DOM region, otherwise a panel that is neither `loading` nor holding any chunk announces the
  localized empty-result message through the shared polite region. A panel still `loading`, or one
  already showing chunks, announces nothing — rendered results are ordinary content read in
  document order. The announcement is deferred one frame past the first update so the shared region
  exists before its text lands, and any live transition arriving first retires the pending
  mount-time announcement so nothing is read twice. Set it where the panel is rendered in response
  to a retrieval the user just ran and nothing else reports the outcome; leave it unset for a panel
  that is part of the page a user is arriving on. Read once, when the panel first mounts: a later
  reconnection or adoption stages the existing state again rather than replaying it, and later
  transitions are announced either way. Remove any host `role="status"`/`role="alert"` hand-added
  before this property existed once it is set — otherwise the initial state is announced twice,
  through the native role and again through the shared sink
- `label?: string` — fallback name for the populated result group; omission uses localized
  `chunkInspectorLabel`. A non-empty host `aria-label` makes the host the sole overall owner; an
  explicitly empty host label stays empty

When a later update enters the settled empty state — including a completed loading cycle that
found no results — the localized empty message is announced through the shared polite light-DOM
region. Initial empty content, loading intermediates, and reconnects are not replayed.

**Events:**

- `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.
- `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.
- `lr-chunk-open` (`detail: { chunkId, sourceId, anchor? }`) — forwarded verbatim from a row's
  `lr-chunk-inspector`; the event a host routes into `lr-document-viewer`.

**Slots:** none.

**CSS parts:** `base`, `error` (neutral visible message while `errorText` is non-empty), `spinner`
(initial-load `lr-spinner`, while `loading` and `chunks` is still empty), `empty` (when `chunks` is
empty and neither `errorText` nor `loading` is set), `row` (a plain element in this shadow root below the
virtualization threshold; exported from the internal `lr-virtual-list`'s own `row` part while
virtualized — `::part(row)` reaches it either way), `group-header` (exported from the virtual list's
`group` part; grouped/virtualized mode only), `select` (per-row `lr-checkbox`, omitted when
`selectable` is false), `row-body` (carries `data-selected`), `row-body-selected` (additional part
on a selected `row-body`), `metadata` (a `<dl>`; omitted when the chunk has none or while
`presentation="compact"`), `metadata-entry`, `metadata-term` (the `<dt>` carrying a metadata key),
`metadata-value` (the `<dd>` carrying its value), `load-more-row`, `load-more`.

The per-row `lr-chunk-inspector`'s own parts are forwarded onward under a `chunk-` prefix —
`chunk`, `chunk-current`, `chunk-score`, `chunk-score-current`, `chunk-score-bar`,
`chunk-score-fill`, `chunk-score-fill-success`, `chunk-score-fill-warning`,
`chunk-score-fill-danger`, `chunk-open-button`,
`chunk-title`, `chunk-text`, `chunk-text-clamped`, `chunk-toggle`. Those elements sit two shadow
hops deep while virtualized, so this forwarding is the only way to reach them.

Selection state is exposed as the additional `row-body-selected` part name rather than through the
`data-selected` attribute, because Shadow Parts forbids an attribute selector after `::part()`:
`::part(row-body)[data-selected]` is invalid CSS, and while virtualized `::part()` is the only way
in. `data-selected` is unchanged. A state part is a second token in the same `part` attribute, so
a `[part~="…"]` (not `[part="…"]`) selector is the one that matches inside a tree. The `<dt>`/`<dd>`
carry their own part names for the same class of reason — `::part()` matches a single element and
cannot be followed by a descendant combinator, so `::part(metadata-entry) dt` reaches nothing.

**Themeable custom properties:** `--lr-retrieval-results-selected-border` (default
`var(--lr-color-brand)`) — the inline-start border color marking a selected row body
(`::part(row-body-selected)`). A
border rather than a fill by design: the row's own text (the nested chunk inspector's quiet-toned
score line in particular) is sized and colored for the page's default surface, and a tinted
background can drop it below the required contrast ratio, while a border-only indicator carries no
such risk — so recoloring this hook is contrast-safe. It is an inline `var()` fallback at the point
of use rather than a `:host` declaration, so it can be set on the element _or on any ancestor_:
`::part(row-body)[data-selected]` is invalid CSS — Shadow Parts forbids an attribute selector after
`::part()` — which previously left re-pointing the library-wide `--lr-color-brand` token as the only
lever, repainting every other brand surface with it. Plus shared tokens otherwise.

**Optional peer deps:** none.

**Known gotchas:**

- While virtualized, each row's content lives inside `lr-virtual-list`'s shadow root, not this
  component's.
- Below the virtualization threshold, scroll-near-bottom isn't a meaningful gesture, so a
  `[part="load-more"]` button takes its place (replaced by a spinner while `loading`).
- Source-group fallback labels are re-evaluated when the effective locale or a `.strings`
  override changes; a cached grouping never leaves the previous localized “untitled source” text.

---

## `lr-retrieval-search`

Query bar for a retrieval/RAG surface: query text, an active filter/scope chip row, a
vector/keyword/hybrid mode selector, and loading/error/empty feedback. Emits `RetrievalQuery` on
submit. Fully controlled; performs no retrieval itself. Composes `lr-input type="search"`,
`lr-segmented`, `lr-chip`/`lr-chip-group`, `lr-spinner`, and a compact `lr-empty`. The query field,
the mode selector and the submit button are all left on the shared `--lr-form-control-height` ladder
at the same size tier, so the toolbar row renders as one flush line.

**Properties:**

- `query: string = ''` — the query text. The internal `lr-input` updates it optimistically as the
  user types; a host reassignment always wins
- `mode: LyraRetrievalMode = 'hybrid'` — `LyraRetrievalMode = RetrievalQuery['mode'] = 'vector' |
'keyword' | 'hybrid'`, re-exported here rather than redefined
- `filters: Record<string, unknown> = {}` (attribute: false) — arbitrary metadata filters, rendered
  as removable `"{key}: {value}"` chips. A non-record runtime value normalizes to an empty record.
  Controlled
- `scope: string[] = []` (attribute: false) — source-scope ids/labels this query is restricted to,
  rendered as removable chips alongside `filters`. A non-array runtime value normalizes empty;
  blank entries and duplicates are omitted first-wins. Controlled
- `loading: boolean = false` (reflected) — host-driven busy flag; this component cannot know when a
  request resolves
- `errorText: string = ''` (attribute `error-text`) — last failed search's message, shown verbatim
  (caller-owned text, not localized) in a neutral visible region. A new non-empty value is announced
  through a shared assertive light-DOM region; initial and reconnect content is not replayed
- `empty: boolean = false` (reflected) — host-driven "the last completed search returned zero
  results"; never inferred, since this component holds no results data (see `lr-retrieval-results`).
  A later transition into the settled empty state announces the localized “No matches” heading
  through the shared polite light-DOM region; initial and reconnect content is not replayed
- `announce: boolean = false` (reflected) — opt-in: announce the state the search bar is **already
  presenting** the first time it mounts, rather than only announcing later transitions into it.
  Urgency follows the state, in the same branch order the row renders: a non-empty `errorText` wins
  and is announced verbatim through the shared assertive light-DOM region, otherwise an `empty`
  search that is not `loading` announces the localized “No matches” text through the shared polite
  region. A search that is still `loading`, or that has settled on neither state, announces
  nothing. The announcement is deferred one frame past the first update so the shared region exists
  before its text lands, and any live transition arriving first retires the pending mount-time
  announcement so nothing is read twice. Set it where the search is rendered in response to a query
  the user just ran and nothing else reports the outcome; leave it unset for a search that is part
  of the page a user is arriving on, whose visible error or empty state is already read in document
  order. Read once, when the search first mounts: a later reconnection or adoption stages the
  existing state again rather than replaying it, and later transitions are announced either way.
  Remove any host `role="status"`/`role="alert"` hand-added before this property existed once it
  is set — otherwise the initial state is announced twice, through the native role and again
  through the shared sink
- `placeholder: string = ''` — falls back to the localized generic "Search" placeholder, which also
  becomes the field's accessible name
- `label?: string` — fallback name for the `role="search"` landmark; omission uses the localized
  retrieval-search label, while an explicit empty string stays empty
- `accessibleLabel: string | null = null` (attribute `aria-label`) — as a JS-only property while
  the host attribute is absent, overrides the search-landmark name. A non-empty authored host
  `aria-label` makes the host the sole overall owner, so the inner shell omits its duplicate
  role/name; an explicitly empty host label stays empty on the search landmark
- `size?: LyraSize` (reflected) — opt-in density tier for the whole query row, on the library's one
  six-step ladder (`2xs`/`xs`/`s`/`m`/`l`/`xl`, or `small`/`medium`/`large`). It is one property for
  all three controls deliberately: the query field, the mode selector and the submit button share
  the row's baseline, and sizing one of them alone is what makes the row ragged. With no `size` each
  control keeps its own `m` default, exactly what the row rendered before; an unsupported value
  normalizes to the omitted state and removes the attribute

**Events:**

- `lr-search` (`detail: RetrievalQuery` from `@aceshooting/lyra-ui/ai` = `{ text: string;
filters?: Record<string, unknown>; mode: 'vector' | 'keyword' | 'hybrid'; scope?: string[] }`) —
  Enter in the query field, or the submit button while not `loading`.
- `lr-cancel` (`detail: CancelEventDetail` from `@aceshooting/lyra-ui/ai` = `{ reason?: string }`) —
  either the button was clicked while `loading` (`detail: {}`), or a new submission superseded an
  in-flight one (`detail: { reason: 'superseded' }`, fired immediately _before_ the new `lr-search`).
- `lr-filters-change` (`detail: RetrievalFiltersChangeDetail` = `{ filters: Record<string, unknown>;
scope: string[] }`) — a chip's remove button was activated; the complete already-updated next
  state, not a delta. The component updates its own copy first, then emits; reassign to control.

**Slots:** none.

**CSS parts:** `base` (the `role="search"` landmark unless a non-empty host label owns the
component), `row`, `query`, `mode`, `submit` (reads
"Search" while idle, "Cancel" while `loading`), `filters` (omitted entirely when both `filters` and
`scope` are empty), `spinner` (only while `loading`), `error` (neutral visible message, only when
`errorText` is non-empty and not `loading`), `empty` (only when `empty` and neither `loading` nor
`errorText`).

**Themeable custom properties:** `--lr-retrieval-search-submit-min-height` (default
`var(--lr-icon-button-size)`, raised to the tier's shared form-control height when `size` is set) is
the submit button's minimum height; the shared tappable-target minimum always stays underneath it,
so the smallest tiers cannot shrink the button below the WCAG floor. Everything else is shared
tokens.

**Optional peer deps:** none.

**Known gotchas:**

- Submitting while `loading` is already true **supersedes** the in-flight request: `lr-cancel` fires
  immediately before the new `lr-search`. Clicking the submit button (rather than pressing Enter)
  while `loading` only emits `lr-cancel` and does not resubmit.
- Long unbroken filter keys, values, and scope labels are contained within the search allocation;
  the removable chip label truncates while its remove action remains available.
- Filter values use a cycle-aware formatter bounded to 128 visited values, six nesting levels,
  32 entries per container and 256 characters per string. Cycles use the localized invalid-value
  sentinel and budget/depth truncation uses a stable ellipsis in both SSR and browser rendering.

---

## `lr-retrieval-trace`

A retrieval pipeline's stage timeline (query rewriting, embedding, retrieval, reranking, filtering)
rendered through `lr-span-waterfall`, plus a disclosure list exposing each stage's evidence. Never
fetches, ranks, or computes retrieval results itself.

**Properties:**

- `stages: RetrievalStage[] = []` (attribute: false) — `RetrievalStage { id: string; kind:
RetrievalStageKind; label?: string; startMs: number; endMs?: number; status: 'pending' | 'running'
| 'success' | 'error' | 'denied'; detail?: string; evidence?: RetrievalStageEvidence }` (exported
  here), where `RetrievalStageKind = 'query-rewrite' | 'embed' | 'retrieve' | 'rerank' | 'filter'`.
  `startMs`/`endMs` are milliseconds relative to the trace start (`endMs` absent while still
  running); `status` uses `LyraSpan.status`'s vocabulary verbatim; `label` overrides the localized
  default label for `kind`; `detail` is secondary text under the stage name. Pass in any order — the
  timeline sorts by `startMs`. Each stage projects to one `LyraSpan` with `kind` mapped
  `query-rewrite → 'llm'`, `embed → 'embedding'`, `retrieve → 'retriever'`,
  `rerank`/`filter` → `'tool'`. Without a `label` override, an unknown runtime kind keeps its literal
  string as the visible label and uses the generic `'tool'` span kind instead of aborting the trace.
  Stage ids must be nonempty, nonblank, and unique: invalid records and later duplicates are
  omitted first-wins before timeline, evidence, controlled state, counts, or event paths
- `RetrievalStageEvidence { text?: string; chunks?: RetrievalChunk[]; metadata?: Record<string,
unknown> }` — `chunks` is **`RetrievalChunk` from `@aceshooting/lyra-ui/ai`** verbatim, rendered
  through `lr-chunk-inspector` (`source.id → sourceId`, `source.name → title`, `locator → anchor`;
  page locators also supply the visible `page`); `text` is free-form (e.g. the rewritten query, an
  embedding model id); `metadata` renders as a plain key/value list. Malformed runtime chunk rows
  are omitted while valid neighboring chunks remain visible. A
  stage whose evidence has none of the three renders no disclosure row at all
- `activeStageId: string | null = null` (attribute `active-stage-id`) — controlled selection,
  forwarded verbatim to the internal `lr-span-waterfall`'s `activeSpanId`
- `label: string = ''` — accessible name for the timeline, falling back to its localized default.
  An authored host `aria-label` independently names the trace and is not cloned onto the timeline;
  explicit-empty/dynamic host changes preserve that single-owner distinction

**Events:** `lr-stage-select` (`detail: { stageId: string }`, a stage's bar was activated — click,
Enter, Space), `lr-stage-toggle` (`detail: { stageId: string; expanded: boolean }`, an evidence panel was
toggled, either by its own button or implicitly by selecting that stage in the timeline for the
first time), and `lr-stage-chunk-action` (`detail: LyraRetrievalTraceChunkActionDetail`, a
discriminated `{ stageId, action: 'open', chunkId, sourceId, anchor? } | { stageId, action: 'expand', chunkId,
expanded }`). Generic nested chunk events are stopped at the trace boundary so every action has
explicit stage identity.

**Slots:** none.

**CSS parts:** `base`, `timeline` (the internal `lr-span-waterfall`), `evidence-list` (omitted when
no stage has evidence), `evidence-row` (omitted for a stage with no evidence), `evidence-toggle`,
`evidence-toggle-icon`, `evidence-body` (hidden while collapsed), `evidence-text`,
`evidence-metadata` (a `<dl>`), `evidence-metadata-row` (one key/value pair), `evidence-metadata-key`
(`<dt>`), `evidence-metadata-value` (`<dd>`), `chunk-inspector` (the stage-owned inspector).

**Themeable custom properties:** `--lr-retrieval-trace-active-border` (default
`var(--lr-color-brand)`) — the border color of the `[part='evidence-row']` whose stage matches
`activeStageId`, leaving every other row on the resting border token. It is an inline `var()`
fallback at the point of use rather than a `:host` declaration, so it can be set on the element _or
on any ancestor_: `::part(evidence-row)[data-active]` is invalid CSS — Shadow Parts forbids an
attribute selector after `::part()` — so marking the active stage previously meant overriding the
library-wide `--lr-color-brand` token and repainting every other brand surface with it. Unset, it
falls back to that token, so rendering is unchanged. Plus shared tokens otherwise.

**Optional peer deps:** none.

**Known gotchas:**

- Every stage starts collapsed; expansion state is internal `@state` keyed by stage id, not a
  controlled property.

## `lr-rag-answer`

Controlled grounded-answer surface combining sanitized Markdown, citation badges, grounding
assessment, and expandable source previews. It performs no model call, retrieval, citation parsing,
or source fetching.

**Properties:** `answer: string = ''`; `citations: Citation[] = []` (attribute: false);
`sources: DocumentRef[] = []` (attribute: false); `assessment: GroundingAssessment | null = null`
(attribute: false); `loading: boolean = false`; `errorText: string = ''` (attribute `error-text`;
neutral visible caller text; new non-empty values announce through a shared assertive light-DOM
region, while initial and reconnect content is not replayed — spelled plain `error` before 9.0.0);
`announce: boolean = false` (reflected) — opt-in: announce the error the answer already carries
the first time it mounts, through the same shared assertive light-DOM region and the same verbatim
caller-supplied text a later `errorText` change takes. Set it where the answer is rendered in
response to a request the user just made and nothing else reports the failure; leave it unset for
an answer that is part of the page a user is arriving on, whose error text is already read in
document order. Read once, when the answer first mounts: a later reconnection or adoption stages
the existing error again rather than replaying it, and later `errorText` changes are announced
either way. An answer with no error announces nothing. Remove any host
`role="status"`/`role="alert"` hand-added before this property existed once it is set — otherwise
the initial error is announced twice, through the native role and again through the shared sink;
`showSources: boolean = true`; `showClaims: boolean = true`
(attribute `show-claims`); `label?: string` (omission uses the localized answer label; an explicit
empty string stays empty); `accessibleLabel: string | null = null` (attribute
`aria-label`). The same `<article>` remains the semantic shell in `idle`, `loading`, `answer`, and
`error` states. With no non-empty host `aria-label` it owns the article role/name; a non-empty host
label makes the host the sole overall owner, while an explicitly empty host label stays empty on
the article. The normalized state gives `errorText` precedence over a conflicting `loading`
flag; `aria-busy="true"` and the spinner appear exactly in the resulting `loading` state, including
while a partial property or slotted answer is streaming.

`citations`, `sources`, and nested `assessment.claims` are canonicalized independently by nonblank
`id`. Malformed rows and later duplicates are omitted first-wins before empty state, child
composition, counts, rendering, lookup, or actions.

**Events:** `lr-citation-select` (`{ citation, section: 'answer' | 'grounding' }`),
`lr-claim-select` (`{ claim }`), and `lr-retry`. When `assessment` is present, grounding summary is
the single citation presentation/action owner; the answer-level duplicate citation row is omitted.
Both child badge signals (`lr-citation-activate` and `lr-citation-open`) are stopped at the answer
boundary and translated into that one section-qualified `lr-citation-select` contract.

**Slots:** `answer` replaces the data-driven Markdown body; `sources` replaces the data-driven
source list. Either slot renders from its assigned content without requiring the corresponding
`answer` or `sources` data property; a slotted answer remains visible while `loading`.

**CSS parts:** `base`, `answer`, `loading`, `error` (neutral visible error message), `retry`,
`grounding`, `citations`, `citation-list`, `sources`, `source-list`, `section-heading`.

## `lr-embedding-explorer`

Dependency-free accessible 2D embedding projection viewer. Coordinates are projected by the host;
the component only normalizes them into SVG, colors optional clusters, and emits selection events.

**Properties:** `points: EmbeddingPoint[] = []` (attribute: false), where each point is `{ id, x,
y, label?, sourceId?, cluster? }`; `selectedPointId: string = ''` (attribute
`selected-point-id`); `height: string = '360px'` (any CSS length valid for `block-size`,
including `auto` for `viewBox`-derived aspect-ratio sizing; applied on the host as
`--lr-embedding-explorer-height`, and a value the browser cannot parse falls back to `auto`);
`accessibleLabel: string | null = null` (attribute `aria-label`). As a JS-only property with no host
attribute, it names the plot. An authored host `aria-label` governs the plot name too (including an
explicitly empty value), so a competing internal generic label is not exposed. Non-finite
coordinates are omitted.
Blank point ids and later duplicates are also omitted first-wins before empty state, roving focus,
selection, rendering, or events.
Pointer and programmatic focus synchronize the single roving tab stop, and every point keeps at
least a 24×24 CSS px pointer target at narrow allocations without enlarging its marker. Optional
cluster membership is exposed as each option's description and in a visible text legend, so the
grouping never depends on color alone.

**Events:** `lr-point-select` (`{ point }`), activated by click or Enter/Space.

**CSS parts:** `base`, `plot`, `point`, `legend`, `legend-item`, `legend-swatch`, `legend-label`,
`empty`.

**Themeable custom properties:** `--lr-embedding-explorer-selected-stroke` (default
`var(--lr-color-brand)`) — stroke color of the selected point; `--lr-embedding-explorer-height`
(default `360px`) — the `block-size` of `[part="plot"]`, set on the host from `height`. A consumer's
own `::part(plot) { block-size: ... }` rule still overrides it, and the narrow-allocation
`min-block-size` floor still raises it. Unspecified clusters cycle through the canonical
`--lr-color-chart-1`, `--lr-color-chart-2`, `--lr-color-chart-3`, `--lr-color-chart-4`,
`--lr-color-chart-5`, `--lr-color-chart-6`, `--lr-color-chart-7`, and `--lr-color-chart-8` palette,
including its dark and forced-color values.
Plus shared tokens.

## `lr-knowledge-base-admin`

Tabbed operations shell composing `lr-knowledge-base` and `lr-ingestion-queue`. It forwards source
and ingestion actions under namespaced events; host-owned controls such as chunking, embedding,
permissions, and connector settings go in the `settings` slot.

**Properties:** `sources: KnowledgeSource[] = []` (attribute: false); `ingestionItems:
IngestionQueueItem[] = []` (attribute: false); `activeTab: 'sources' | 'ingestion' = 'sources'`;
`label?: string` (the visible heading and the tablist's distinct accessible name; omission uses the
localized admin label, while an explicit empty string stays empty; authored host
`aria-label` independently names the admin component and is not cloned onto either);
`hideIngestion: boolean = false`. If ingestion is active when it becomes hidden, `activeTab`
normalizes to `'sources'`, emits `lr-tab-change`, and moves focus to the Sources tab when needed.
An invalid runtime or authored `activeTab` value follows the same fallback instead of leaving every
tab and panel inactive.

**Events:** `lr-tab-change` (`{ tab }`, emitted only for a distinct accepted selection),
`lr-source-create`, `lr-source-sync`, `lr-source-pause`,
`lr-source-delete`, `lr-ingestion-retry`, and `lr-ingestion-cancel` (the latter four preserve the
correlated ids/details from their composed primitives).
`lr-activate` (`detail: { value: 'sources' | 'ingestion' }`, bubbling, composed, non-cancelable)
fires on **every** user activation of an available tab — a click, or an Arrow/Home/End key —
whether or not `activeTab` actually moved. `value` is the activated tab, the same identity
`lr-tab-change` reports under the key `tab`. It reports that the user picked a tab and gates
nothing. Use it for the repeat pick `lr-tab-change` deliberately stays silent for — "refresh that
queue" is a real intent — which from the keyboard is otherwise unobservable, because Home on an
already-first active tab (or End on an already-last one) activates a tab and produces no click at
all. When an activation _does_ move the tab, `lr-tab-change` is emitted first. The normalization
that moves an invalid or newly-hidden tab back to Sources is not a user activation and fires only
`lr-tab-change`.

**Slots:** `settings` — host-owned KB configuration controls.

**CSS parts:** `base`, `heading`, `tabs`, `tab`, `panel`, `settings`.

**Themeable custom properties:** `--lr-knowledge-base-admin-tab-selected-border` (default
`var(--lr-color-brand)`) and `--lr-knowledge-base-admin-tab-selected-color` (default
`var(--lr-color-text)`) — the bottom-border and text color of the selected `[part="tab"]`. State
hooks: inline `var()` fallbacks at the point of use rather than `:host` declarations, so either can
be set on the element _or on any ancestor_, and the rule wraps its `[aria-selected='true']` qualifier
in `:where()` so a consumer's own `::part(tab)` override still wins. They exist because
`::part(tab)[aria-selected='true']` is invalid CSS — Shadow Parts forbids an attribute selector after
`::part()`. Left unset, rendering is unchanged.

**Optional peer deps:** none.

## `lr-claim-evidence`

Controlled claim-by-claim grounding audit relating `GroundedClaim[]` to complete `Citation[]`
records. Dangling citation ids are ignored rather than rendered as invented evidence.

**Properties:** `claims: GroundedClaim[] = []` and `citations: Citation[] = []` (attribute: false);
`selectedClaimId: string = ''` (attribute `selected-claim-id`); `label: string = ''` (fallback name
for the overall claim region; a non-empty host `aria-label` makes the host the sole overall owner,
while an explicitly empty host label stays empty on the region).
`GroundedClaim = { id, text, status, citationIds, answerRange?, confidence?, explanation? }`, with
`status: 'supported' | 'partially-supported' | 'unsupported' | 'contradicted'`. Claim confidence
is clamped to 0–1 for localized percent display. `Citation` is the shared AI citation record
(`id`, source/chunk ids, label, locator/ranges, quote, metadata).

Claims and citations are canonicalized independently by nonblank `id`. Malformed rows and later
duplicates are omitted first-wins before empty state, controlled selection, evidence lookup,
rendering, or events. An unrecognized runtime claim status renders as localized “Unsupported” with
the danger treatment instead of producing an empty or misleading badge.

- `compact: boolean = false` (reflected) — tighter `claim-trigger` padding and column gap, for dense
  evidence lists — the same convention as `lr-source-card`'s/`lr-entity-card`'s `compact`. Purely a
  density knob: each claim's border and background stay. `false` (the default) keeps the full
  claim-trigger padding.
- `frame: LyraFrame = 'card'` (reflected) — container treatment, in the library-wide `frame`
  vocabulary (`'card' | 'plain'`). `'card'` (the default) keeps each claim's bordered, filled box;
  `'plain'` removes the border, background, and corner radius from every `claim` row, so claims
  nested inside an already-bordered container don't double the frame. `plain` wins over `compact`
  when both are set — nothing left to tighten.

**Events:** `lr-claim-select` (`{ claim }`), `lr-citation-select` (`{ citation }`). A nested
`lr-citation-badge` activation is contained and translated to `lr-citation-select`; the distinct
composed `lr-citation-open` event intentionally crosses `lr-claim-evidence` unchanged with its
`{ sourceId, index, href }` detail.

**CSS parts:** `base`, `list`, `claim`, `claim-selected`, `claim-trigger`, `status`, `claim-text`,
`confidence`, `explanation`, `evidence`, `empty`.

**Themeable custom properties:** `--lr-claim-evidence-compact-padding` (default
`var(--lr-space-xs)`) — `[part='claim-trigger']`'s padding while `compact`;
`--lr-claim-evidence-compact-gap` (default `var(--lr-space-xs)`) — the gap between
`[part='claim-trigger']`'s columns while `compact`. Both apply only in the `compact` state.
Otherwise shared tokens only.

Selection is controlled: activation emits the complete claim but does not assign
`selectedClaimId`. Evidence preserves `citations` order and silently skips dangling ids.
**Slots:** none. **Optional peer deps:** none.

```ts
import "@aceshooting/lyra-ui/components/retrieval/claim-evidence/claim-evidence.js";
```

## `lr-retrieval-compare`

Side-by-side retrieval/reranking workbench showing effective rank, top-k Jaccard overlap, and
dense/sparse/rerank/final score breakdowns.

**Properties:** `sets: RetrievalComparisonSet[] = []` (attribute: false), where
`RetrievalComparisonSet = { id: string; label: string; chunks: RetrievalChunk[] }`;
`topK: number = 10` (attribute `top-k`, finite integer with minimum 1);
`selectedChunkId: string = ''` (attribute `selected-chunk-id`); `label?: string` (fallback name
for the overall comparison region; a non-empty host `aria-label` makes the host the sole overall
owner, while an explicitly empty host label stays empty on the region).
`RetrievalChunk` is the shared AI record carrying id/text/score/source plus optional rank, locator,
trace metadata, and `scores?: { dense?, sparse?, rerank?, final }`.

Set ids and each set's nested chunk ids are canonicalized independently. Malformed/blank rows and
later duplicates are omitted first-wins before empty state, overlap/count calculations, ranking,
controlled selection, rendering, or events.

**Events:** `lr-chunk-select` (`{ setId, chunk }`).

**CSS parts:** `base`, `overlap`, `sets`, `set`, `set-heading`, `chunks`, `chunk`,
`chunk-selected`, `chunk-rank`, `chunk-title`, `chunk-text`, `scores`, `score`, `empty`.

Chunks are ordered by effective rank, then score, then input order before the top-k slice. Overlap
is pairwise Jaccard similarity across those visible chunk ids. Selection is controlled.
**Slots:** none. **Optional peer deps:** none.

**Themeable custom properties:** `--lr-retrieval-compare-selected-border` (default
`var(--lr-color-brand)`) — the border color marking a selected `[part~="chunk-selected"]` row, the
same escape-hatch pattern as `lr-retrieval-results`'s `--lr-retrieval-results-selected-border`.

```ts
import "@aceshooting/lyra-ui/components/retrieval/retrieval-compare/retrieval-compare.js";
```

## `lr-rag-eval-dashboard`

Controlled RAG evaluation overview with latest metric cards, per-metric trends, evaluation slices,
and run history. The host computes metrics and owns evaluation execution.

**Properties:** `metrics: LyraRagEvaluationMetric[] = []` and
`runs: LyraRagEvaluationRun[] = []`
(attribute: false); `metricId: string = ''` (attribute `metric-id`, with the first metric used for
display when unset/unmatched); `slice: string = ''`; `label?: string` (visible heading and
fallback overall-region name; a non-empty host `aria-label` makes the host the sole overall owner,
while an explicitly empty host label stays empty on the region);
`showChart: boolean = true` (attribute `show-chart`, reflected, string-aware true-default
converter); `chartHeight: string = '220px'` (attribute `chart-height`).

`LyraRagEvaluationMetric = { id, label, category, format? }`, where category is
`'retrieval' | 'generation' | 'system' | custom-string` and format is `'number' | 'percent'`.
`LyraRagEvaluationRun = { id, label, metrics: Record<string, number>; slice?, timestamp?, metadata? }`.

Metrics and runs are canonicalized independently by nonblank `id`. Malformed rows and later
duplicates are omitted first-wins before metric fallback, slice derivation/filtering, cards, charts,
history, counts, rendering, or actions.

**Events:** `lr-metric-change` (`{ metricId }`), `lr-slice-change` (`{ slice }`), and
`lr-run-change` (`{ run }`). All are controlled intents; the component does not mutate the
corresponding selection properties.

**CSS parts:** `base`, `heading`, `slices`, `slice`, `slice-selected`, `metrics`, `metric`,
`metric-selected`, `metric-category` (the caller-supplied category rendered visibly on each metric),
`chart`, `runs`, `runs-heading`, `run`, `empty`.

**Themeable custom properties:** `--lr-rag-eval-dashboard-selected-border-color` (default
`var(--lr-color-brand)`) — border color shared by the controlled active slice and metric.

Percent values clamp to 0–1 and all numbers use `effectiveLocale`. The chart is built from the
filtered run order; the host computes every metric and owns evaluation execution.
**Slots:** none. **Optional peer deps:** none.

```ts
import "@aceshooting/lyra-ui/components/retrieval/rag-eval-dashboard/rag-eval-dashboard.js";
```

`lr-grounding-summary` and `lr-rag-answer` now accept `GroundingAssessment.claims` and expose
`showClaims: boolean = true`; `lr-retrieval-results` forwards `RetrievalChunk.locator` as the
document-viewer-compatible `anchor` in `lr-chunk-open`.

## Consumer integration notes

- **Explorer legend:** observe `lr-hidden-types-change` on
  `lr-knowledge-graph-explorer` for an accepted visibility change. A visibility proposal can be
  vetoed only from the legend control when an integration renders or owns one separately.
- **Projected records:** `lr-memory-panel` and `lr-claim-evidence` capture usable display/action
  fields when their collections are assigned. Unsafe or malformed branches are omitted while valid
  siblings remain; selected/action event details retain the original record where that identity is
  part of the public contract. Reassign a new collection to update the rendered projection.

## Exported TypeScript contracts

These named interfaces and helper signatures are available to typed integrations. They are grouped by capability so the component sections above can stay focused.

- **`components-retrieval-chunk-inspector-chunk-inspector-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/retrieval/chunk-inspector/chunk-inspector.class.js`.
  `LyraChunk {
    id: string;
    text: string;
    score: number;
    sourceId: string;
    title?: string;
    page?: string | number;
    anchor?: LyraChunkAnchor;
  }`

- **`components-retrieval-citation-badge-citation-badge-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/retrieval/citation-badge/citation-badge.class.js`.
  `CitationActivateDetail {
    sourceId: string;
    index: number;
  }`
  Import: `@aceshooting/lyra-ui/components/retrieval/citation-badge/citation-badge.class.js`.
  `CitationOpenDetail {
    sourceId: string;
    index: number;
    href?: string;
  }`

- **`components-retrieval-community-card-community-card-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/retrieval/community-card/community-card.class.js`.
  `LyraCommunity {
    id: string;
    label: string;
    summary?: string;
    memberCount?: number;
  }`

- **`components-retrieval-embedding-explorer-embedding-explorer-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/retrieval/embedding-explorer/embedding-explorer.class.js`.
  `EmbeddingPoint {
    id: string;
    x: number;
    y: number;
    label?: string;
    sourceId?: string;
    cluster?: string | number;
  }`

- **`components-retrieval-entity-card-entity-card-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/retrieval/entity-card/entity-card.class.js`.
  `LyraEntity {
    id: string;
    label: string;
    type?: string;
    description?: string;
    properties?: Readonly<Record<string, string | number>>;
    degree?: number;
    communityId?: string;
  }`

- **`components-retrieval-entity-dossier-entity-dossier-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/retrieval/entity-dossier/entity-dossier.class.js`.
  `LyraEntityDossierConfidence {
    readonly label: string;
    readonly value: string;
    readonly unit?: string;
    readonly variant?: LyraVariant;
    readonly exactValue?: string;
    readonly caption?: string;
    readonly rows?: readonly StatRow[];
  }`

- **`components-retrieval-graph-legend-graph-legend-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/retrieval/graph-legend/graph-legend.class.js`.
  `LyraGraphLegendVisibilityDetail {
    hiddenTypes: string[];
  }`

- **`components-retrieval-graph-graph-loader-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/retrieval/graph/graph-loader.js`.
  `D3DragBehavior<ElementType extends Element, Datum> {
    on(type: 'start' | 'drag' | 'end', listener: (event: {
      active: number;
      x: number;
      y: number;
      sourceEvent?: unknown;
      subject?: Datum;
      container?: ElementType;
    }) => void): this;
  }`
  Import: `@aceshooting/lyra-ui/components/retrieval/graph/graph-loader.js`.
  `D3ForceCenter {
    initialize?(nodes: D3SimulationNodeDatum[]): void;
  }`
  Import: `@aceshooting/lyra-ui/components/retrieval/graph/graph-loader.js`.
  `D3ForceCollide<Node extends D3SimulationNodeDatum> {
    radius(value: number | ((node: Node) => number)): this;
  }`
  Import: `@aceshooting/lyra-ui/components/retrieval/graph/graph-loader.js`.
  `D3ForceLink<Node extends D3SimulationNodeDatum, Link extends D3SimulationLinkDatum<Node>> {
    distance(value: number | ((link: Link) => number)): this;
  }`
  Import: `@aceshooting/lyra-ui/components/retrieval/graph/graph-loader.js`.
  `D3ForceManyBody<Node extends D3SimulationNodeDatum> {
    strength(value: number | ((node: Node) => number)): this;
  }`
  Import: `@aceshooting/lyra-ui/components/retrieval/graph/graph-loader.js`.
  `D3Modules {
    forceSimulation<Node extends D3SimulationNodeDatum, Link extends D3SimulationLinkDatum<Node>>(nodes: Node[]): D3Simulation<Node, Link>;
    forceLink<Node extends D3SimulationNodeDatum, Link extends D3SimulationLinkDatum<Node>>(links: Link[]): D3ForceLink<Node, Link>;
    forceManyBody<Node extends D3SimulationNodeDatum>(): D3ForceManyBody<Node>;
    forceCenter(x?: number, y?: number): D3ForceCenter;
    forceCollide<Node extends D3SimulationNodeDatum>(): D3ForceCollide<Node>;
    drag<ElementType extends Element, Datum>(): D3DragBehavior<ElementType, Datum>;
    zoom<ElementType extends Element, Datum>(): D3ZoomBehavior<ElementType, Datum>;
    zoomIdentity: D3ZoomTransform;
    zoomTransform(node: Element): D3ZoomTransform;
    select<ElementType extends Element, Datum>(node: ElementType): D3Selection<ElementType, Datum>;
  }`
  Import: `@aceshooting/lyra-ui/components/retrieval/graph/graph-loader.js`.
  `D3Selection<ElementType extends Element, Datum> {
    call(behavior: unknown): this;
    node?(): ElementType | null;
    datum?(): Datum;
  }`
  Import: `@aceshooting/lyra-ui/components/retrieval/graph/graph-loader.js`.
  `D3Simulation<Node extends D3SimulationNodeDatum, Link extends D3SimulationLinkDatum<Node>> {
    force(name: string, force: D3ForceLink<Node, Link> | D3ForceManyBody<Node> | D3ForceCollide<Node> | D3ForceCenter): this;
    on(type: 'tick', listener: () => void): this;
    alphaTarget(value: number): this;
    restart(): this;
    stop(): this;
    alpha(): number;
    alpha(value: number): this;
    alphaMin(): number;
    tick(iterations?: number): this;
  }`
  Import: `@aceshooting/lyra-ui/components/retrieval/graph/graph-loader.js`.
  `D3SimulationLinkDatum<Node extends D3SimulationNodeDatum> {
    source: Node | string | number;
    target: Node | string | number;
    index?: number;
  }`
  Import: `@aceshooting/lyra-ui/components/retrieval/graph/graph-loader.js`.
  `D3SimulationNodeDatum {
    index?: number;
    x?: number;
    y?: number;
    vx?: number;
    vy?: number;
    fx?: number | null;
    fy?: number | null;
  }`
  Import: `@aceshooting/lyra-ui/components/retrieval/graph/graph-loader.js`.
  `D3ZoomBehavior<ElementType extends Element, Datum> {
    scaleExtent(extent: [number, number]): this;
    on(type: 'start' | 'end', listener: () => void): this;
    on(type: 'zoom', listener: (event: {
      transform: D3ZoomTransform;
    }) => void): this;
    transform(selection: D3Selection<ElementType, Datum>, transform: D3ZoomTransform): void;
  }`
  Import: `@aceshooting/lyra-ui/components/retrieval/graph/graph-loader.js`.
  `D3ZoomTransform {
    readonly k: number;
    readonly x: number;
    readonly y: number;
    translate(x: number, y: number): D3ZoomTransform;
    scale(k: number): D3ZoomTransform;
    toString(): string;
  }`
  Import: `@aceshooting/lyra-ui/components/retrieval/graph/graph-loader.js`.
  `loadD3(): Promise<D3Modules | null>`
  Import: `@aceshooting/lyra-ui/components/retrieval/graph/graph-loader.js`.
  `loadD3Modules(importForce?: () => Promise<unknown>, importDrag?: () => Promise<unknown>, importZoom?: () => Promise<unknown>, importSelection?: () => Promise<unknown>): Promise<D3Modules | null>`

- **`components-retrieval-graph-graph-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/retrieval/graph/graph.class.js`.
  `LyraGraphCommunity {
    readonly id: string;
    readonly label?: string;
    readonly memberIds: readonly string[];
    readonly color?: string;
  }`
  Import: `@aceshooting/lyra-ui/components/retrieval/graph/graph.class.js`.
  `LyraGraphLink {
    readonly id?: string;
    readonly source: string;
    readonly target: string;
    readonly width?: number;
    readonly label?: string;
    readonly accessibleLabel?: string;
    readonly description?: string;
    readonly directed?: boolean;
    readonly color?: string;
    readonly dash?: readonly number[];
  }`
  Import: `@aceshooting/lyra-ui/components/retrieval/graph/graph.class.js`.
  `LyraGraphNode {
    readonly id: string;
    readonly label?: string;
    readonly accessibleLabel?: string;
    readonly description?: string;
    readonly radius?: number;
    readonly color?: string;
    readonly type?: string;
    readonly expandable?: boolean;
    readonly communityId?: string;
  }`
  Import: `@aceshooting/lyra-ui/components/retrieval/graph/graph.class.js`.
  `LyraScoreThresholds {
    readonly high: number;
    readonly medium: number;
  }`

- **`components-retrieval-ingestion-queue-ingestion-queue-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/retrieval/ingestion-queue/ingestion-queue.class.js`.
  `IngestionCancelEventDetail extends CancelEventDetail {
    itemId: string;
    // Inherited from CancelEventDetail.
    reason?: string;
  }`
  Import: `@aceshooting/lyra-ui/components/retrieval/ingestion-queue/ingestion-queue.class.js`.
  `IngestionQueueItem {
    id: string;
    document: DocumentRef;
    stage: IngestionStage;
    progress?: number;
    chunkCount?: number;
    embeddedChunkCount?: number;
    attempts?: number;
    error?: string;
  }`
  Import: `@aceshooting/lyra-ui/components/retrieval/ingestion-queue/ingestion-queue.class.js`.
  `IngestionRetryEventDetail extends RetryEventDetail {
    itemId: string;
    // Inherited from RetryEventDetail.
    attempt: number;
    messageId?: string;
  }`

- **`components-retrieval-knowledge-base-knowledge-base-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/retrieval/knowledge-base/knowledge-base.class.js`.
  `KnowledgeSource {
    id: string;
    name: string;
    type?: string;
    syncStatus: KnowledgeSourceSyncStatus;
    indexingHealth?: KnowledgeSourceIndexingHealth;
    permission?: KnowledgeSourcePermission;
    documentCount?: number;
    lastSyncedAt?: Date | string;
    errorMessage?: string;
  }`

- **`components-retrieval-memory-panel-memory-panel-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/retrieval/memory-panel/memory-panel.class.js`.
  `LyraMemoryAddDetail {
    memory: LyraMemoryItem;
  }`
  Import: `@aceshooting/lyra-ui/components/retrieval/memory-panel/memory-panel.class.js`.
  `LyraMemoryExpandDetail {
    memoryId: string;
    scope: MemoryScope;
    expanded: boolean;
  }`
  Import: `@aceshooting/lyra-ui/components/retrieval/memory-panel/memory-panel.class.js`.
  `LyraMemoryItem {
    id: string;
    text: string;
    confidence?: number;
    provenance?: LyraProvenance;
  }`
  Import: `@aceshooting/lyra-ui/components/retrieval/memory-panel/memory-panel.class.js`.
  `LyraMemoryRemoveDetail {
    memoryId: string;
    scope: MemoryScope;
  }`

- **`components-retrieval-mind-map-mind-map-layout-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/retrieval/mind-map/mind-map.class.js`.
  `LyraTopic {
    id: string;
    label: string;
    children?: readonly LyraTopic[];
  }`

- **`components-retrieval-neighbor-list-neighbor-list-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/retrieval/neighbor-list/neighbor-list.class.js`.
  `LyraNeighborRow {
    relation: string;
    direction: 'in' | 'out' | 'both';
    node: LyraEntity;
  }`

- **`components-retrieval-node-palette-node-palette-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/retrieval/node-palette/node-palette.class.js`.
  `LyraPaletteItem {
    type: string;
    label: string;
    description?: string;
    category?: string;
    keywords?: string[];
    icon?: unknown;
    disabled?: boolean;
  }`

- **`components-retrieval-provenance-panel-provenance-panel-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/retrieval/provenance-panel/provenance-panel.class.js`.
  `LyraProvenance {
    readonly entities?: readonly LyraEntity[];
    readonly relationships?: readonly Readonly<{
      path: readonly LyraPathElement[];
    }>[];
    readonly communities?: readonly LyraCommunity[];
    readonly chunks?: readonly LyraChunk[];
  }`

- **`components-retrieval-rag-answer-rag-answer-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/retrieval/rag-answer/rag-answer.class.js`.
  `LyraRagCitationSelectDetail extends CitationSelectEventDetail {
    section: 'answer' | 'grounding';
    // Inherited from CitationSelectEventDetail.
    citation: Citation;
  }`

- **`components-retrieval-rag-eval-dashboard-rag-eval-dashboard-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/retrieval/rag-eval-dashboard/rag-eval-dashboard.class.js`.
  `LyraRagEvaluationMetric {
    id: string;
    label: string;
    category: LyraRagEvaluationMetricCategory;
    format?: LyraRagEvaluationMetricFormat;
  }`
  Import: `@aceshooting/lyra-ui/components/retrieval/rag-eval-dashboard/rag-eval-dashboard.class.js`.
  `LyraRagEvaluationRun {
    id: string;
    label: string;
    metrics: Record<string, number>;
    slice?: string;
    timestamp?: string;
    metadata?: Record<string, unknown>;
  }`

- **`components-retrieval-retrieval-compare-retrieval-compare-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/retrieval/retrieval-compare/retrieval-compare.class.js`.
  `RetrievalComparisonSet {
    id: string;
    label: string;
    chunks: RetrievalChunk[];
  }`

- **`components-retrieval-retrieval-results-retrieval-results-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/retrieval/retrieval-results/retrieval-results.class.js`.
  `RetrievalResultsSelectDetail {
    chunkIds: string[];
    chunks: RetrievalChunk[];
  }`

- **`components-retrieval-retrieval-search-retrieval-search-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/retrieval/retrieval-search/retrieval-search.class.js`.
  `RetrievalFiltersChangeDetail {
    filters: Record<string, unknown>;
    scope: string[];
  }`

- **`components-retrieval-retrieval-trace-retrieval-trace-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/retrieval/retrieval-trace/retrieval-trace.class.js`.
  `RetrievalStageEvidence {
    text?: string;
    chunks?: RetrievalChunk[];
    metadata?: Record<string, unknown>;
  }`
  Import: `@aceshooting/lyra-ui/components/retrieval/retrieval-trace/retrieval-trace.class.js`.
  `RetrievalStage {
    id: string;
    kind: RetrievalStageKind;
    label?: string;
    startMs: number;
    endMs?: number;
    status: 'pending' | 'running' | 'success' | 'error' | 'denied';
    detail?: string;
    evidence?: RetrievalStageEvidence;
  }`

- **`components-retrieval-source-card-source-card-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/retrieval/source-card/source-card.class.js`.
  `SourceCardExpandDetail {
    sourceId: string;
    expanded: boolean;
  }`
  Import: `@aceshooting/lyra-ui/components/retrieval/source-card/source-card.class.js`.
  `SourceCardOpenDetail {
    sourceId: string;
    href?: string;
  }`

- **`components-retrieval-source-list-source-list-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/retrieval/source-list/source-list.class.js`.
  `SourceListToggleDetail {
    expanded: boolean;
  }`

- **`components-retrieval-source-picker-source-picker-contracts`** — Supporting data types and helpers for this component family.
  Import: `@aceshooting/lyra-ui/components/retrieval/source-picker/source-picker.class.js`.
  `LyraSourceEntry {
    id: string;
    label: string;
    mimeType?: string;
    name?: string;
    children?: readonly LyraSourceEntry[];
  }`