@aceshooting/lyra-ui 11.2.0 → 12.1.0

package/llms-full.txt

@@ -34,7 +34,7 @@ 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** — 25 tags in `components/data/`
+- **Data display, dashboards & flow canvas** — 26 tags in `components/data/`
 - **Layout, navigation & structure** — 35 tags in `components/layout/`
 - **Overlays, status & feedback** — 21 tags in `components/overlays/`
 - **Utilities, formatting & observers** — 20 tags in `components/utility/`
@@ -202,6 +202,8 @@ The entry points, then:
   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),
@@ -696,10 +698,110 @@ reaches plain application CSS, and it never reaches your own custom elements, si
 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` |
+
+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.
@@ -1246,7 +1348,10 @@ stay in light DOM: they do not pierce a component's shadow root.
 `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.
+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
 
@@ -2757,6 +2862,7 @@ These named interfaces and helper signatures are available to typed integrations
   "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;
@@ -3142,6 +3248,7 @@ These named interfaces and helper signatures are available to typed integrations
   "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;
@@ -3428,6 +3535,7 @@ These named interfaces and helper signatures are available to typed integrations
   "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;
@@ -3754,6 +3862,7 @@ These named interfaces and helper signatures are available to typed integrations
   "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;
@@ -4056,6 +4165,48 @@ Filterable single/multi-select combining a text input with a listbox. Mirrors th
 `<wa-combobox>` API under the `lr-` prefix. **Form-associated** (hand-rolled internals, not the
 shared `FormAssociated` mixin — see gotchas).
 
+**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.
@@ -4960,9 +5111,21 @@ default). An inherited or direct public value remains authoritative in every tie
 Text field + calendar popover, **form-associated** via the shared `FormAssociated` mixin (`name`,
 `value`, `disabled`, `required` all inherited).
 
-**Properties (42):**
+**Properties (44):**
 
 - `appearance: 'filled'|'outlined'|'filled-outlined' = 'outlined'` (reflected)
+- `appliedPreset: LyraDateRangePreset | undefined` (read-only, new in 11.3.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)
@@ -4987,6 +5150,12 @@ Text field + calendar popover, **form-associated** via the shared `FormAssociate
 - `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)
@@ -10182,7 +10351,7 @@ no-rows states return the empty element as the shadow root's own root, with no `
 wrapper around it — `::part(base)` does not apply in those two states, only in the filtered-to-zero
 one — and that `empty` disappears entirely once the `empty` slot is filled.
 
-- `scrollMode: 'self' | 'page' = 'self'` (attribute `scroll-mode`, reflected) — which element
+- `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
@@ -10190,8 +10359,12 @@ one — and that `empty` disappears entirely once the `empty` slot is filled.
   still `overflow: auto` becomes a sticky containing block that never scrolls, and its header
   scrolls away with the page. With `'page'` the header's nearest scrollport is the page, so it pins
   there; the cost is that a table wider than its host overflows the page instead of scrolling
-  inside itself. Named `scrollMode` rather than `scroll` because a `scroll` property would shadow
-  `Element.prototype.scroll()`
+  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
@@ -10675,6 +10848,114 @@ Dependency-free SVG radial, full-circle ring, or linear meter (no charting libra
 
 ---
 
+## `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.
+
+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.
+- **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
@@ -10890,6 +11171,38 @@ weekdayLabelText?: (jsWeekday:number)=>string|undefined; monthLabelText?:
   `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
@@ -11019,7 +11332,10 @@ color?: string; label?: string; partOfRamp?: boolean }`: a discrete legend key r
   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. A dev-mode-only warning fires when a stop's
+  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
@@ -11029,9 +11345,12 @@ color?: string; label?: string; partOfRamp?: boolean }`: a discrete legend key r
 color-scheme change; called automatically on theme changes, exposed for a consumer that needs to
 force a redraw manually. `matrixGeometry: Readonly<{ padLeft: number; padTop: number; cellSize:
 number }> | 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 (e.g. a sticky header mirror
-for a tall matrix) line up with the canvas without hardcoding the same numbers `row-label-width`/
-`col-label-height`'s `"auto"` resolution would otherwise keep private.
+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.
 
 **Events:** `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),
@@ -11042,8 +11361,12 @@ in calendar mode)
 
 **Slots:** none.
 
-**CSS parts:** `base`, `canvas`, `cells` (opt-in per-cell overlay), `cell` (one opt-in native cell
-button), `tooltip` (hover tooltip, positioned over the hovered cell),
+**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
@@ -11079,7 +11402,12 @@ dedicated token distinct from both the focus ring and the annotation ring so a h
 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. Also consumes `--lr-color-text-quiet` (axis label
+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`).
@@ -12318,20 +12646,21 @@ renders each event as a `<button part="agenda-event">`.
 
 ## `lr-timeline` and `lr-timeline-item`
 
-Read-only chronological sequence. `lr-timeline` is a `role="list"` flex container; each
+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.
-Neither element has events, keyboard navigation, or a 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`).
+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.
 
 **`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
 (the `role="list"` element is in the shadow root and never inherits a host attribute). Read-only
-`itemCount: number` is the live count of direct default-slot `<lr-timeline-item>` children;
-unrelated slotted elements and text nodes are ignored.
+`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
@@ -12339,23 +12668,34 @@ proportion of the range, so a gap of weeks and a gap of decades stop looking ide
 needs a definite extent to distribute along — `--lr-timeline-time-extent` (default
 `var(--lr-size-20rem)`), applied as `block-size` when vertical and `inline-size` when horizontal —
 because items are absolutely positioned and a percentage against an auto-sized track resolves to
-zero. `collision: 'overlap' | 'stack' = 'overlap'` (attribute `collision`, type `LyraTimelineCollision`)
-chooses what `scale="time"` does with items landing on nearly the same position: `'overlap'` leaves
-them stacked on one another, `'stack'` steps each colliding item one lane along the **cross** axis
-(indent per lane: `--lr-timeline-collision-offset`, default `var(--lr-space-l)`), which is what a
-dense chronology needs — items within 1.5% of the axis of each other count as colliding, and an
-isolated item returns to lane 0 rather than inheriting a preceding run's depth. There is
-deliberately no `'cluster'` mode: collapsing coincident items into one expandable marker needs a
-selection model and click events this passive component does not have.
+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. Items sharing an instant
-overlap rather than being fanned into lanes: lane assignment, brushing, zooming and per-event
-selection belong to a denser component than this deliberately passive one. Positions are written to
+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'`, so the component still never alters its children's content or structure.
+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),
@@ -12365,8 +12705,16 @@ isn't attribute-serializable; invalid input normalizes to unset and renders no t
 optional pulse disabled under `prefers-reduced-motion: reduce`, with explicit `aria-current="true"`
 or `"false"` on the host).
 
-**Events:** none on either element. Read the reactive `itemCount` property after changing direct
-children; the internal slot's non-composed `slotchange` event is not a host-level public signal.
+**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: unknown;
+}`
+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
@@ -12375,7 +12723,9 @@ slot falls back to a color-coded dot), `timestamp` (wins outright over the
 entirely when empty).
 
 **CSS parts:** timeline `base` — the `role="list"` flex container (no separate `list` part). Item:
-`base`, `track` (marker + rail spine, always the opposite axis from `base`), `marker`
+`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`,
@@ -12383,8 +12733,11 @@ wrapping `title` and `timestamp`; wraps at narrow widths rather than truncating)
 
 **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-scroll-fade-size` (default `2rem`) controls each
-horizontal-overflow edge fade; forced-colors mode removes the masks while retaining native
+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`
@@ -12975,6 +13328,13 @@ These named interfaces and helper signatures are available to typed integrations
   maxZoom: unknown;
 }`
 
+- **`components-data-funnel-funnel-contracts`** — Supporting data types and helpers for this component family.
+  `LyraFunnelStage {
+  label: unknown;
+  value: unknown;
+  color: unknown;
+}`
+
 - **`components-data-graph-query-builder-graph-query-builder-contracts`** — Supporting data types and helpers for this component family.
   `GraphQueryDeleteDetail {
   queryId: unknown;
@@ -13648,6 +14008,12 @@ TemplateResult; ariaLabel?: string }`. Each entry gets a header toggle button
 - `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: string = ''` (attribute: false) — **deprecated alias for `activeViewId`**, which it
+  seeds. `activeView` was this member's original public name and the rename was never announced, so
+  a shipped `.activeView=${…}` binding silently became inert and the widget fell back to its first
+  view. It seeds rather than being read alongside, because the component itself writes
+  `activeViewId` (a toggle click, and the fallback when `views` drops the active id) — so a stale
+  alias must not undo a later interactive change. Prefer `activeViewId` in new code.
 - `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.
@@ -15317,6 +15683,12 @@ removing the label from the accessibility tree.
   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: boolean = false` — **deprecated alias for `current`**, read alongside it: the item is
+  current when either is true. `active` was this member's original public name, in both property and
+  attribute form; it was renamed to `current` without an alias, so shipped consumers writing
+  `.active=${…}` or `<lr-app-rail-item active>` silently lost their current-item indicator and kept a
+  permanent `aria-current="false"`. A Lit property binding on a custom element is untyped, so nothing
+  in a consumer's type check or test suite could catch it. Prefer `current` in new code.
 - `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,
@@ -16550,7 +16922,8 @@ value therefore stays inside a 320px LTR or RTL bar, with the chip's own label e
 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. A built-in or
+complete value object, plus the `filterId` that changed and (new in 11.3.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.
@@ -16600,6 +16973,54 @@ to `<lr-input>` for an open-ended free-text query rather than a closed choice se
 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.
 
+### Date-range quick ranges
+
+A `'date-range'` definition also accepts `presets?: readonly LyraDateRangePreset[]` (new in 11.3.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? }` 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. `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;
@@ -17041,6 +17462,7 @@ These named interfaces and helper signatures are available to typed integrations
 }`
   `LyraFilterBarDateRangeDefinition {
   type: unknown;
+  presets: unknown;
   min: unknown;
   max: unknown;
   filterId: unknown;
@@ -17052,6 +17474,7 @@ These named interfaces and helper signatures are available to typed integrations
   `LyraFilterBarInputDetail {
   value: unknown;
   filterId: unknown;
+  appliedPreset: unknown;
 }`
   `LyraFilterBarOption {
   value: unknown;
@@ -18294,6 +18717,13 @@ 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
@@ -18565,6 +18995,45 @@ from the shared positioner and caps its dimensions to the measured available spa
 
 A click-triggered, light-dismiss floating surface positioned with the shared Floating UI positioner.
 
+**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
@@ -21895,6 +22364,20 @@ import "@aceshooting/lyra-ui/components/media/flag/flag-peer.js";
   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
@@ -22006,13 +22489,19 @@ dimming at `itemCount <= 1`), `--lr-focus-ring-*`.
 ## `lr-map`
 
 A `maplibre-gl` wrapper with a declarative legend, a single choropleth GeoJSON fill layer, markers,
-and additive plain-GeoJSON `dataLayers`, plus a peer-neutral `map` getter for common imperative
-operations. Its runtime value is the underlying MapLibre map.
+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.
 
 **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
@@ -22087,10 +22576,15 @@ string; geojson: GeoJSON.FeatureCollection; field: string; stops: [number, strin
   gotchas. Entries with non-finite coordinates or latitude outside `[-90, 90]` 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 }`. `sourceId` is trimmed and must be nonempty; the first layer for a
+'danger' | 'neutral'; color?: string; strokeColor?: string; kind?: LyraMapDataLayerKind;
+heatmap?: LyraMapHeatmapOptions; cluster?: LyraMapClusterOptions }`. `sourceId` is trimmed and must be nonempty; the first layer for a
   `sourceId` wins and blank or later duplicate records are ignored. 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
@@ -22110,9 +22604,65 @@ GeoJSON.FeatureCollection; tone?: 'accent' | 'success' | 'warning' |
   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 (`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.
+  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.
+
+  `cluster` and `kind` (both new in 11.3.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.
 - `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
@@ -22124,14 +22674,15 @@ GeoJSON.FeatureCollection; tone?: 'accent' | 'success' | 'warning' |
 
 **Choropleth and `dataLayers` updates are diffed before they reach the peer.** `setData()`
 unconditionally re-tiles and repaints an entire source, which is invisible on a static map and
-expensive on an animated one. When an update changes only feature *properties* — the values driving
-the colour ramp — the component emits maplibre-gl's incremental `updateData()` instead. The fast
-path is deliberately strict, and needs all of: the same feature count, a `string`/`number` `id` on
-every feature in the same order, and geometry that is the **same object** as last time (not merely
-deep-equal). Structurally comparing polygon rings would cost about what the re-tile costs, and a
-false positive would paint stale geometry. Reuse your geometry objects across frames — the
-efficient way to build an animation anyway — and the fast path applies; otherwise it falls back to
-`setData()` with no change in behaviour. Peers predating `updateData()` always take the old path.
+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's immutable ownership boundary detaches GeoJSON assignments, so geometry
+reference identity cannot survive between frames; 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
@@ -22150,7 +22701,9 @@ payload beside the map.
   empty canvas name. The non-semantic `[part="base"]` wrapper is not named instead.
 
 **Authoring types:** `LyraMapLegendEntry`, `LyraMapLegendPattern`, `LyraMapLegendProjection`, `LyraMapChoroplethLayer`,
-`LyraMapGeoJsonDataLayer`, `LyraMapMarker`, `LyraMapStyleSpecification`, and `LyraMapInstance`.
+`LyraMapGeoJsonDataLayer`, `LyraMapDataLayerKind`, `LyraMapClusterOptions`, `LyraMapHeatmapOptions`,
+`LyraMapHeatmapZoomValue`, `LyraMapMarker`, `LyraMapMarkerActivationDetail`,
+`LyraMapMarkerActivationSource`, `LyraMapStyleSpecification`, and `LyraMapInstance`.
 The former `LegendEntry`, `ChoroplethLayer`, `GeoJsonDataLayer`, and `MapMarker` names are removed
 in v9 rather than retained as aliases.
 
@@ -22165,14 +22718,22 @@ shared `maplibre-gl` import without constructing a map or allocating a WebGL con
 `false` when the peer is unavailable, allowing an application to choose a fallback before connecting
 an element.
 
-**Events:** `lr-map-load` (fired once, after the underlying map's own `'load'`), `lr-map-click`
+**Events:** `lr-map-load` (fired once, after the underlying map's own `'load'`),
+`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 layer, topmost first — so a shape painted through `dataLayers` is identifiable
-instead of being indistinguishable from empty space. `origin` is `'choropleth'` or `'data-layer'`,
-and `sourceId` carries the authored `dataLayers[].sourceId` for a data-layer hit; both are
-`undefined` whenever `feature` is
+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
 
 **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
@@ -22238,6 +22799,10 @@ Vite with v6:
     { 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)
   );
@@ -22254,8 +22819,9 @@ https://maplibre.org/maplibre-gl-js/docs/#esm.
   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.
-- A marker with a popup handles Space at its focus boundary: one activation toggles the peer popup
-  and suppresses the page-scroll default. Markers without a popup do not consume Space.
+- 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
@@ -22300,6 +22866,10 @@ undefined`, or changing `choropleth.sourceId` to a different value, now calls `r
   `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.
 
 ---
 
@@ -24299,6 +24869,12 @@ These named interfaces and helper signatures are available to typed integrations
   reason: unknown;
 }`
 
+- **`components-media-flag-flag-peer-bulk-standard-contracts`** — Supporting data types and helpers for this component family.
+  `registerLyraFlagStandardBulkPeer(): unknown`
+
+- **`components-media-flag-flag-peer-bulk-contracts`** — Supporting data types and helpers for this component family.
+  `registerLyraFlagBulkPeer(): unknown`
+
 - **`components-media-flag-flag-peer-contracts`** — Supporting data types and helpers for this component family.
   `registerLyraFlagPeer(): unknown`
 
@@ -24333,6 +24909,8 @@ These named interfaces and helper signatures are available to typed integrations
 - **`components-media-map-map-loader-contracts`** — Supporting data types and helpers for this component family.
   `loadMaplibre(): unknown`
   `MapLibreGeoJsonDiff {
+  remove: unknown;
+  add: unknown;
   update: unknown;
   id: unknown;
   addOrUpdateProperties: unknown;
@@ -24426,6 +25004,13 @@ These named interfaces and helper signatures are available to typed integrations
   stops: unknown;
   interpolation: unknown;
   stepBaseColor: unknown;
+}`
+  `LyraMapClusterOptions {
+  radius: unknown;
+  maxZoom: unknown;
+  radiusSteps: unknown;
+  colorSteps: unknown;
+  countFont: unknown;
 }`
   `LyraMapGeoJsonDataLayer {
   sourceId: unknown;
@@ -24433,6 +25018,17 @@ These named interfaces and helper signatures are available to typed integrations
   tone: unknown;
   color: unknown;
   strokeColor: unknown;
+  kind: unknown;
+  heatmap: unknown;
+  cluster: unknown;
+}`
+  `LyraMapHeatmapOptions {
+  weightField: unknown;
+  weightRange: unknown;
+  stops: unknown;
+  radius: unknown;
+  intensity: unknown;
+  opacity: unknown;
 }`
   `LyraMapInstance {
   getCanvas: unknown;
@@ -24466,6 +25062,12 @@ These named interfaces and helper signatures are available to typed integrations
   color: unknown;
   label: unknown;
   unsafeHtml: unknown;
+}`
+  `LyraMapMarkerActivationDetail {
+  id: unknown;
+  lngLat: unknown;
+  marker: unknown;
+  source: unknown;
 }`
   `LyraMapStyleSpecification {
   version: unknown;
@@ -25057,13 +25659,16 @@ passthrough). Not a subclass of `LyraChart`.
 - `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` (attribute `max-labels`, type Number) — decimates which category axis labels
-  actually render *text* when `labels.length > maxLabels`: always shows the first and last label,
-  and roughly evenly distributes
-  the rest between them. Works in either `layout` mode. Unset (the default) renders every label.
-  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.
+- `maxLabels?: number | 'auto'` (attribute `max-labels`) — decimates which category axis labels
+  actually render *text*: always shows the first and last label and roughly evenly distributes the
+  rest between them. A number is authoritative. `'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
@@ -25085,7 +25690,16 @@ passthrough). Not a subclass of `LyraChart`.
 - `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` (attribute `value-axis-gutter`) — value-axis gutter width.
+- `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.
 - `scale: 'linear' | 'sqrt' | 'logarithmic' = 'linear'` — `'sqrt'` (**bar type only**) maps a bar's