@aceshooting/lyra-ui 11.2.0 → 12.1.0

package/llms/components/lr-option.md

@@ -20,6 +20,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.

package/llms/components/lr-popover.md

@@ -17,6 +17,45 @@
 
 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

package/llms/components/lr-table.md

@@ -331,7 +331,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
@@ -339,8 +339,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

package/llms/components/lr-timeline-item.md

@@ -8,7 +8,7 @@
 - **Status** `stable` since `4.0.0` — see the maturity and deprecation policy in `llms/shared.md`
 - **Deprecations** none
 - **Optional peers** none
-- **Themeable via** 9 parts, 5 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 11 parts, 8 custom properties — see this component's own `@csspart`/`@cssprop` list below
 - **Documented with** `lr-timeline` (same section below)
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
 
@@ -16,20 +16,21 @@
 
 ## `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
@@ -37,23 +38,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),
@@ -63,8 +75,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
@@ -73,7 +93,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`,
@@ -81,8 +103,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`

package/llms/components/lr-timeline.md

@@ -8,7 +8,7 @@
 - **Status** `stable` since `4.0.0` — see the maturity and deprecation policy in `llms/shared.md`
 - **Deprecations** none
 - **Optional peers** none
-- **Themeable via** 1 part, 4 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 1 part, 7 custom properties — see this component's own `@csspart`/`@cssprop` list below
 - **Documented with** `lr-timeline-item` (same section below)
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
 
@@ -16,20 +16,21 @@
 
 ## `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
@@ -37,23 +38,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),
@@ -63,8 +75,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
@@ -73,7 +93,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`,
@@ -81,8 +103,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`

package/llms/components/lr-widget.md

@@ -6,7 +6,7 @@
 - **Class** `LyraWidget`, also available unregistered from `@aceshooting/lyra-ui/components/layout/widget/widget.class.js`
 - **Family** `components/layout/` — see `llms/index.md` for its siblings
 - **Status** `stable` since `4.0.0` — see the maturity and deprecation policy in `llms/shared.md`
-- **Deprecations** none
+- **Deprecated property** `activeView` since `11.2.0`; use property `activeViewId`; removal not before `13.0.0` — `activeView` was this property's original public name; the string does not appear anywhere in CHANGELOG.md, so the rename to `activeViewId` was never announced at all. A shipped consumer's `.activeView=` binding became a dead expando and the widget fell back to its first view with no error. The alias seeds `activeViewId` rather than being read alongside it, because the component itself writes that property (a view-toggle click, and the fallback when `views` drops the active id), and a read-alongside alias would undo a later interactive change on the next update.
 - **Optional peers** none
 - **Themeable via** 16 parts, 9 custom properties — see this component's own `@csspart`/`@cssprop` list below
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
@@ -49,6 +49,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.

package/llms/index.md

@@ -2,7 +2,7 @@
 
 # Component index
 
-284 custom elements, grouped by the source family they live in.
+285 custom elements, grouped by the source family they live in.
 
 **Reading one component.** Its reference file path is derived from the tag — no search needed:
 `llms/components/<tag>.md` (e.g. `llms/components/lr-table.md`). Each is self-contained: import
@@ -50,7 +50,7 @@ Optional peers: `llms/peers.md`. Safe `wa-*`/`sl-*` migration: `llms/migration.m
 - `lr-rubric-form` · lr-rubric-form.js · `stable` since `4.0.0` — a configurable annotation rubric (LangSmith annotation-queue style): score, category, and freeform-comment keys with a submit-and-next fl...
 - `lr-locale-picker` · lr-locale-picker.js · `stable` since `6.0.0` — a closed-list locale switcher over the library's own locale registry.
 
-## Data display, dashboards & flow canvas — `components/data/` (25)
+## Data display, dashboards & flow canvas — `components/data/` (26)
 
 - `lr-sparkline` · lr-sparkline.js · `stable` since `4.0.0` — a zero-dependency inline SVG trend chart.
 - `lr-stat` · lr-stat.js · `stable` since `4.0.0` — a KPI/stat card.
@@ -58,6 +58,7 @@ Optional peers: `llms/peers.md`. Safe `wa-*`/`sl-*` migration: `llms/migration.m
 - `lr-table` · lr-table.js · `stable` since `4.0.0` — a sort/select-aware data table.
 - `lr-pagination` · lr-pagination.js · `stable` since `4.0.0` — controlled, server-friendly page navigation: a numbered page list with elided gaps, optional first/last controls, an optional item-range...
 - `lr-gauge` · lr-gauge.js · `stable` since `4.0.0` — a radial, full-circle ring, or linear meter.
+- `lr-funnel` · lr-funnel.js · `experimental` since `12.0.0` — a dependency-free conversion funnel: an ordered set of stages, each drawn as a bar whose length is that stage's share of the FIRST stage,...
 - `lr-word-cloud` · lr-word-cloud.js · `stable` since `4.0.0` — a zero-dependency SVG word/tag cloud.
 - `lr-heatmap` · lr-heatmap.js · `stable` since `4.0.0` — a Canvas heatmap with a DPR-aware, resize-aware redraw loop.
 - `lr-sequence-strip` · lr-sequence-strip.js · `stable` since `4.0.0` — a compact, one-thin-cell-per-item strip visualizing a sequence of categorical states, with an optional secondary per-cell marker.

package/llms/peers.md

@@ -37,7 +37,7 @@ for the page.
 
 | Peer | Range | Needed by |
 |---|---|---|
-| `@aceshooting/lyra-flags` | `workspace:^2.1.0` | `lr-flag`, `lr-locale-picker`, `lr-phone-input` |
+| `@aceshooting/lyra-flags` | `workspace:^2.2.0` | `lr-flag`, `lr-locale-picker`, `lr-phone-input` |
 | `@aiden0z/pptx-renderer` | `^1.2.4` | `lr-pptx-viewer` |
 | `@sgratzl/chartjs-chart-boxplot` | `^4.4.5` | `lr-box-plot` |
 | `chart.js` | `^4.5.1` | `lr-bar-chart`, `lr-box-plot`, `lr-bubble-chart`, `lr-chart`, `lr-doughnut-chart`, `lr-histogram`, `lr-line-chart`, `lr-pie-chart`, `lr-polar-area-chart`, `lr-radar-chart`, `lr-scatter-chart` |

package/llms/shared.md

@@ -150,6 +150,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),
@@ -644,10 +646,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.
@@ -1194,7 +1296,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
 
@@ -2705,6 +2810,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;
@@ -3090,6 +3196,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;
@@ -3376,6 +3483,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;
@@ -3702,6 +3810,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;