@aceshooting/lyra-ui 16.0.0 → 18.0.0

package/CHANGELOG.md

@@ -1,5 +1,754 @@
 # Changelog
 
+## 18.0.0
+
+### Major Changes
+
+- 555b974: **Major only because several exported TypeScript unions and maps gained members. No runtime
+  behaviour changes, no attribute or event was removed or renamed, and no default moved.** If you do
+  not perform exhaustive type-level matching over the members listed below, this release is a
+  drop-in upgrade and you can stop reading here.
+  
+  The public-API gate classifies widening an exported union as breaking, and it is right to: a
+  consumer with an exhaustive `switch` over one of these, or a mapped type keyed by one, stops
+  compiling until the new member is handled. Nothing else about them changed.
+  
+  **`lr-filter-bar`**
+  - `LyraFilterBarControlType` gains `'chip'`.
+  - `LyraFilterBarFilterDefinition` gains `LyraFilterBarChipDefinition`.
+  - `LyraFilterBarDefinitionValue<D>` gains an arm resolving a chip filter to the full
+    `LyraFilterBarFieldValue`, exactly as `'custom'` already does. Every other `D` resolves as before.
+  
+  An exhaustive `switch (definition.type)` over a filter schema now needs a `'chip'` case, and a
+  `Record<LyraFilterBarControlType, T>` needs a `chip` key.
+  
+  **`lr-map`**
+  - `LyraMapLegendEntry` gains an optional `value` category key.
+  - `LyraMapEventMap` gains `'lr-map-legend-toggle'`.
+  - New exported `LyraMapLegendToggleDetail`.
+  
+  A `Record<keyof LyraMapEventMap, T>` needs the new key. `LyraMapLegendEntry` is only widened by an
+  optional property, so constructing one is unaffected; only code that enumerates its keys is.
+  
+  **`lr-virtual-list`**
+  - New `rowProjection` property and `row-projection` attribute, new `projectedRows` getter, new
+    exported `LyraVirtualListRowProjection`, and two exported constants,
+    `VIRTUAL_LIST_ROW_ATTRIBUTE` and `VIRTUAL_LIST_STICKY_ATTRIBUTE`.
+  
+  **Generated framework declarations.** `./custom-elements-jsx`, `./vue` and `./svelte` are
+  regenerated from the manifest, so the prop types for the components above widen accordingly. This
+  is the bulk of the gate's reported diff and needs no action.
+  
+  **Migration:** add the new members to any exhaustive union handling; otherwise upgrade directly.
+
+### Minor Changes
+
+- 49eb3ef: `<lr-combobox>` gains `sync` (unset by default), spelled and shaped identically to
+  `<lr-dropdown>`/`<lr-popup>`/`<lr-popover>`'s property of the same name. Setting `sync="width"`
+  copies the trigger's rendered width onto the listbox and drops the previously fixed 12rem-28rem
+  content-based clamp (keeping only the outer viewport/available-space ceiling), so a full-width
+  trigger with short option labels gets a listbox that aligns to its own edges instead of floating
+  narrower in the middle. Left unset, the listbox continues to size to its own content exactly as
+  before.
+- 204aeb4: **`<lr-filter-bar>`: a control-less `type: 'chip'` filter, for a value owned by a widget elsewhere
+  on the page.**
+  
+  A calendar heatmap cell, a map selection, a chart brush — the filter is real, but the control that
+  sets it is not in the toolbar. Until now the only way to surface such a filter in the bar was a
+  `type: 'custom'` definition whose renderer drew something inert just to occupy the cell it was
+  forced to claim.
+  
+  `type: 'chip'` renders **no control and no toolbar cell**: no `field` wrapper is emitted for it, so
+  `lr-filter-bar::part(field)` and `::part(field-<filterId>)` never match one, and a bar whose filters
+  are *all* chip-only paints no empty column — its `controls` row still renders the reset button (the
+  "clear all" action such a bar needs), the `end` slot and the loading spinner, exactly like a bar
+  declaring no filters at all.
+  
+  Everything else is unchanged from any other filter type. The value lives in `value` under its own
+  filter ID, rides every `lr-input`/`lr-reset` detail, counts toward `hasActiveFilters` (so it enables
+  the reset button) and toward `invalidFilterIds` when `required`, renders a removable active-filter
+  chip subject to `activeFiltersDisplay`, and is cleared both by removing that chip and by `reset()`.
+  A `required` chip-only filter is honoured in bookkeeping only — it joins `invalidFilterIds`, fails
+  `checkValidity()` and moves `lr-validity-change` — but renders no inline error, because the bar
+  renders no element of its own for it; the owning widget keeps its own error affordance. The
+  inherited `placeholder` is inert here for the same reason it already is for `type: 'custom'`.
+  
+  **Chip text.** An optional `formatValue(value, locale)` produces it, and `locale` is the bar's
+  `effectiveLocale` — the same locale every built-in type's own chip formatting and a custom adapter's
+  `formatValue` already receive, so the caller localizes its own data. Omitted, the fallback ladder is
+  the one a custom adapter's omitted `formatValue` uses: a string array renders as a localized
+  conjunction list, anything else renders verbatim through `String(value)`, and an unset value renders
+  empty. Verbatim is exact — a chip-only value never passes through the date branch that localizes a
+  `'date'`/`'date-range'` chip, so an ISO day is not silently reformatted and a value containing a
+  slash is not mangled.
+  
+  **Clearing.** An optional `clearValue` (default `''`, what every non-multi built-in type writes) is
+  what a chip removal writes; declare `[]` for an array-valued chip-only filter. An optional `isEmpty`
+  overrides the built-in emptiness rule. A domain sentinel must pair the two: a sentinel clear value
+  with no matching `isEmpty` leaves the bar reading the "cleared" value as still set and still
+  rendering a chip for it — the identical pairing a custom adapter's own `clearValue`/`isEmpty`
+  already documents. With the pair declared, the sentinel is never stored in `value` and an absent key
+  reads back as the sentinel for the owning widget.
+  
+  **Additive only.** A schema declaring no `'chip'` filter renders byte-identical shadow DOM: the
+  render path keys on `type === 'chip'` exactly, never on "not a known control type", so an
+  unrecognized `type` still falls back to `<lr-select>` as before. At the type level, a `'chip'` filter
+  keeps the full unconstrained field value in `LyraFilterBarValueFor<Defs>`, like `'custom'`. New
+  exported type: `LyraFilterBarChipDefinition`.
+- af5a12e: `<lr-map>` gains an opt-in interactive legend, so a categorical point layer's key can double as its
+  layer switch instead of needing a hand-built checkbox group positioned over the canvas.
+  
+  `legendInteractive` (attribute `legend-interactive`, default `false`) turns every legend row that
+  carries the new `LyraMapLegendEntry.value` category key into a keyboard-operable toggle button.
+  `value` is the same string a `point.colors` / `point.icons` record matches against
+  `point.field` / `point.iconField`, so one set of category records can feed both the paint and the
+  key and the two cannot drift. It is distinct from — and does not derive from — the `value` on a
+  row's `icon` record, which is still dropped from the canonical readback as before. Rows without a
+  `value` stay inert even when `legendInteractive` is set.
+  
+  `hiddenCategories: readonly string[]` is the controlled state, mirroring `<lr-chart>`'s
+  `hiddenDatasets`, and is honoured on first render rather than only after a user toggle. Activating a
+  toggle emits a cancelable `lr-map-legend-toggle` carrying the activated key, its proposed
+  visibility, and the complete proposed hidden set; `preventDefault()` is a real veto — nothing is
+  written, the row's `aria-pressed` does not change, the map is not repainted, and no announcement is
+  made — so a host can own the state itself. A programmatic `hiddenCategories` assignment reconciles
+  silently and emits nothing.
+  
+  A hidden category's points, point icons and stroke are muted in the rendered MapLibre layers
+  through the new `--lr-map-hidden-category-opacity` (default `0.15`), resolved live from the cascade
+  because MapLibre paints to a WebGL canvas that never sees `var()`. The legend row itself dims only
+  its decorative swatch (`--lr-map-legend-hidden-swatch-opacity`, default `0.5`) and re-colors its
+  label through the quiet-text token, so the label keeps WCAG AA contrast rather than fading with the
+  swatch. New parts: `legend-toggle` and `legend-toggle-hidden`.
+  
+  Each toggle is an ordinary tabbable `<button>` with `aria-pressed` rendering both `"true"` and
+  `"false"`, matching `<lr-chart>` and `<lr-graph-legend>` rather than introducing a third legend
+  vocabulary; a long interactive legend therefore contributes one tab stop per keyed row. Show/hide
+  state changes are announced through the shared light-DOM live region.
+  
+  With `legendInteractive` left unset, the legend DOM and every MapLibre paint property are
+  byte-identical to before: no button is rendered and `circle-opacity` is never written at all.
+- 3024e74: Added a complete Romanian (`ro`) translation catalog, the twelfth full locale to ship with the
+  package. Like every other locale, it is split into twelve side-effect-only per-family slices
+  (`@aceshooting/lyra-ui/translations/ro/<family>.js`) plus the back-compat aggregate
+  `@aceshooting/lyra-ui/translations/ro.js`, covering all 1,291 keys in `LYRA_DEFAULT_STRINGS`
+  (including the 14 pluralized entries). Romanian's CLDR plural category set is `one`/`few`/`other`
+  rather than English's `one`/`other` — `few` covers `0` and `2`-`19` (and the `101`-`119`-per-hundred
+  band), while `other` is the `de`-requiring form from `20` upward (`"20 de rezultate"` vs.
+  `"2 rezultate"`) — so every pluralized message was authored with all three categories rather than
+  widening `few` to `other`.
+- 9db9165: `<lr-select>` gains `loading` (default `false`, reflected). A committed value whose catalog hasn't
+  arrived yet -- `<lr-option>`s still being fetched/mounted asynchronously -- previously had no way to
+  distinguish itself from a genuinely stale value: both rendered the raw value string badged
+  dashed/italic `notInCatalog`. Setting `loading` while the matching option is still pending instead
+  renders the localized `loading` placeholder, with no `unknown-value` badge and no synthetic
+  `showUnknownOption` listbox row, in the trigger label or the relevant `multiple`-mode tag. Once the
+  matching `<lr-option>` mounts, the real label renders automatically on the next render, with or
+  without also flipping `loading` back to `false`. A value that already matches a live option, and
+  every existing `loading`-unset unknown-value/`getUnknownLabel` behavior, is unchanged.
+- 1942512: `<lr-streaming-text>`/`<lr-streaming-text-core>` now forward their composed
+  `<lr-markdown>`/`<lr-markdown-core>`'s documented CSS parts (`content`, `heading`, `paragraph`,
+  `list`, `code-block`, `inline-code`, `link`, `table`, `blockquote`, `img`, `math`) through
+  `exportparts`, reusing each name verbatim since none collides with either wrapper's own `base`/
+  `cursor` parts. A host-level `lr-streaming-text::part(link)`/`::part(img)` (or the `-core` variant's
+  equivalent) rule now reaches the rendered `<a>`/`<img>` the same way it already does applied
+  directly to `<lr-markdown>`/`<lr-markdown-core>` -- previously that styling surface was unreachable
+  from outside either wrapper's own shadow boundary.
+- c78f78c: `<lr-virtual-list>` gains `row-projection`, an opt-in light-DOM row projection mode, so an
+  application whose list rows are already styled by its own global stylesheet can adopt virtualization
+  without rehoming every row rule.
+  
+  Until now `renderItem`'s output was stamped inside the component's shadow root, so document CSS
+  could not reach row content: adopting virtualization meant moving a dozen descendant rules per row
+  into a new custom element or a growing set of custom properties — a stylesheet refactor, paid
+  exactly by the lists long enough to need virtualizing. With `row-projection="light"` the windowed
+  rows are rendered into the host's own light DOM and assigned into the shadow viewport through
+  internal named slots. The component keeps owning windowing, measurement, spacer sizing,
+  `scrollToIndex()`, the external-scroller mode and the ARIA contract; the consumer keeps owning the
+  row markup and its cascade, and ordinary document CSS styles a virtualized row exactly as it styles
+  the same row unvirtualized.
+  
+  Positioning stays on the shadow-side `[part="row"]` wrapper, which the document cannot select, so
+  windowing is not overridable by consumer CSS and the whole existing part vocabulary — `base`,
+  `spacer`, `row`, `group`, `sticky-group` — keeps matching in both modes.
+  
+  Costs, stated plainly rather than hidden:
+  
+  - Each projected row sits inside one component-owned wrapper element carrying the reserved
+    `data-lr-virtual-list-row` attribute (exported as `VIRTUAL_LIST_ROW_ATTRIBUTE`; the sticky band's
+    counterpart is `VIRTUAL_LIST_STICKY_ATTRIBUTE`). Descendant selectors port unchanged; child
+    combinators, `:nth-child`, `:first-child` and sibling combinators written against unvirtualized
+    markup do not, and `:nth-child` reflects the current window rather than the item index.
+  - A delegated listener on the host now sees an un-retargeted `event.target`, so
+    `closest('[part="row"]')` no longer resolves — use `closest('[data-lr-virtual-list-row]')`.
+  - The document cascade now reaches row content, including resets that previously could not.
+  - Per-row light-DOM state does not survive a disconnect/reconnect, because disconnect removes the
+    projected rows completely.
+  - On a hydrated page the first window is shadow-rendered for one task before it swaps into the
+    light DOM, so server markup and the first client render agree.
+  
+  `rowProjection` is `'shadow'` by default. Left unset, every existing list renders byte-identically
+  and the host's light DOM stays empty.
+
+### Patch Changes
+
+- ce460db: **Documentation: `aria-pressed` stopped reaching a link button (`href` set) in 16.0.0 — recorded
+  here because 16.0.0 filed it where nobody would find it.**
+  
+  No behaviour changes in this release. This entry exists because the change itself shipped without a
+  discoverable release note, and a consumer pinning the old contract met it as an unexplained test
+  failure after a dependency bump.
+  
+  **What changed, and when.** Through 15.0.0, `<lr-button>`, `<lr-icon-button>` and `<lr-card>`
+  forwarded a host `aria-pressed` onto the `<a>` they render when `href` is set. Since **16.0.0** they
+  do not: `aria-pressed` reaches the `<button>` rendering only. `role="link"` has no pressed state, so
+  forwarding it there asserted an ARIA state that does not exist on that role — an ARIA conformance
+  failure, not a feature. The behaviour is correct and is not being reverted.
+  
+  This narrowed a documented forwarding contract, so it was a **breaking change** for anyone relying
+  on the old behaviour, and it should have been filed as one. 16.0.0 did describe it, but as the third
+  sub-heading of a long `<lr-card>` disabled-state entry whose opening sentence never mentions
+  `<lr-button>` — so neither scanning the release notes for button changes nor reading a per-component
+  digest surfaced it.
+  
+  **Migration.** If the control is a real toggle, drop `href` — the same host `aria-pressed` then
+  reaches the `<button>` that replaces the anchor, and the pressed state is exposed again. If it is a
+  navigation target, use the global `aria-current` (`page`, `step`, `location`, `date`, `time`,
+  `true`, `false`) instead: that one is valid on `role="link"` and does still reach the anchor.
+  
+  The `lr-button`, `lr-icon-button` and `lr-card` reference sections now name 16.0.0 as the version
+  the carve-out landed in, so the rule can be dated from the reference alone.
+- 87d02cb: Fixed `<lr-reorder-list>`'s documented Ctrl/Cmd+ArrowUp/ArrowDown shortcut so it fires from real
+  keyboard focus on a row's own move button, not only when a `keydown` happens to be dispatched
+  synthetically on the button's host element. The move buttons are composed `<lr-icon-button>`s, so
+  real DOM focus during ordinary keyboard use lands on that button's own native `<button>` — one
+  shadow boundary deeper than `<lr-reorder-item>`'s own shadow root. The exclusion predicate that
+  tells the row's own chrome apart from a consumer's nested control only recognized an element whose
+  root node was exactly the item's shadow root, so the nested native button fell through to the
+  generic `name === 'button'` exclusion and every Ctrl/Cmd+Arrow press starting from real focus on a
+  move button was discarded as though it had come from a consumer's own control.
+- 87d02cb: Fixed `<lr-reorder-list>` in `controlled` mode so it no longer steals focus back to the moved row
+  when the consumer has deliberately moved focus elsewhere while an async `finalizePendingMove()` /
+  host reconciliation is still in flight. Previously the post-move focus restore unconditionally
+  focused the moved row's move button once the host's re-render settled, even when the consumer had
+  already moved focus to an unrelated control on the page in the meantime — overriding that
+  deliberate choice. The restore now only runs when the pre-restore focus was still somewhere inside
+  this list, or there was nothing meaningful to preserve (nothing focused, or the previously-focused
+  node was disconnected by the host's own reconciliation); a still-connected external focus target
+  is left alone.
+- cada7da: `<lr-table>`'s `editType: 'select'` cell editor now shows a themed disclosure chevron instead of
+  looking like a plain text field. `appearance: none` on `select[part='cell-editor']` removed the
+  native arrow with no replacement; the glyph is repainted on the enclosing `[part='cell']` (a bare
+  `<select>` cannot host a decorative child, and a `mask` can't apply to the select itself without
+  clipping its own text), using the same mask + `background: currentColor` technique already shipped
+  for the map attribution-toggle glyph, positioned at the logical inline-end edge so it mirrors
+  correctly under `dir="rtl"` and survives `forced-colors: active`. The `text`/`number` cell editors
+  are unaffected.
+- e4402ef: Fixed `<lr-thread-list>` data-mode rows so choosing a `renderActions`-rendered menu action (for
+  example a consumer's `<lr-dropdown>` containing an `<lr-menu>`) no longer also fires the row's own
+  `lr-select` and selects/opens the conversation. The row's `lr-select` listener previously reacted to
+  any `lr-select`-named event that bubbled through the `<lr-conversation-item>`, including one
+  coincidentally emitted by a `renderActions`-rendered descendant (`<lr-menu>` fires its own
+  `lr-select` on item choice). It now only treats the event as row activation when it was dispatched
+  directly on the `<lr-conversation-item>` itself (`e.target === e.currentTarget`), which is how a
+  real row click/keyboard activation always dispatches it; a descendant's bubbled event is still
+  absorbed at the row boundary (as before) but no longer re-emitted as the row's own selection.
+
+## 17.0.0
+
+### Major Changes
+
+- a0507c3: Release the accumulated Lyra UI API, metadata, compatibility, and accessibility corrections as
+  `17.0.0`. This release includes the common-issue cleanup pass across form controls, overlays, data
+  and retrieval components, viewers, shared tokens, localization, RTL behavior, generated contracts,
+  and package-size tooling.
+
+### Minor Changes
+
+- e7d8187: `<lr-app-rail>`'s `[part="panel"]` gains four direction-aware per-corner radius tokens
+  (`--lr-app-rail-panel-radius-start-start`/`-start-end`/`-end-start`/`-end-end`), each defaulting to
+  the existing uniform `--lr-app-rail-panel-radius` so an unset override still rounds all four
+  corners exactly as before. Because the mobile drawer is always flush against its own logical
+  inline-start edge, the two `-end` corner tokens are the ones a flush-against-one-edge drawer
+  typically rounds, and both mirror to the opposite physical side under `dir="rtl"` with no second
+  consumer rule. `[part="nav"]` gains `--lr-app-rail-nav-padding` and `--lr-app-rail-nav-gap`,
+  defaulting to the values that rule previously hard-coded. `<lr-app-rail-item>`'s icon-only square
+  gains `--lr-app-rail-item-icon-only-size`, which — when set — sizes `[part="base"]`'s icon-only
+  square (and its `min-block-size` floor) directly, independent of
+  `--lr-app-rail-item-min-block-size`, so a taller expanded row and an icon-only square pinned to
+  `--lr-icon-button-size` can coexist. Unset, all three continue to reproduce their prior rendering
+  exactly.
+- e7d8187: `<lr-app-rail-item>`'s `[part="current-indicator"]` full-height edge bar now suppresses itself by
+  default in the `icon-only` presentation, where it previously painted a broken-looking bar across a
+  square icon tile. `--lr-app-rail-item-current-indicator-display` restores it per instance. A new
+  `--lr-app-rail-item-current-ring` token adds an inset ring on the icon-only current tile by
+  default — a non-color-only signal (WCAG 1.4.1) that replaces the suppressed bar there — while
+  leaving the full presentation, which already conveys current state through the bar and
+  `--lr-app-rail-item-current-font-weight`, ring-free by default. Setting the ring token explicitly
+  applies the same value in both presentations. Full presentation is otherwise byte-identical to
+  before.
+- fa5c976: `<lr-app-rail-item>` gains its own expandable child list — the treeitem-with-link pattern used by
+  repository trees, Notion-style page trees and IDE explorers, where the row itself navigates and a
+  separate disclosure expands that item's own nested rows. Nested `<lr-app-rail-item>`s slotted into
+  `children` grow a built-in disclosure (`[part="toggle"]`) as a SIBLING of the item's own
+  link/button, never nested inside it, so the link keeps navigating on its own and the disclosure
+  keeps toggling on its own. The new `expanded` property (reflected, `false` by default) is driven
+  through a cancelable `lr-toggle-request`/settled `lr-toggle` pair, mirroring
+  `<lr-app-rail-group>`'s collapsible contract exactly (same event names, same `{ open }` detail
+  shape, same request/commit veto semantics). The disclosure carries `aria-expanded` and
+  `aria-controls`, and a localized accessible name interpolating the item's own label. `icon-only`
+  forwards from an item onto every `<lr-app-rail-item>` it owns through `children`, exactly how
+  `<lr-app-rail-group>` forwards onto the items and groups it owns; a new
+  `--lr-app-rail-item-indent` token (default `var(--lr-space-l)`) indents `[part="children"]` once
+  per nesting level. An item with nothing slotted into `children` renders no disclosure and no
+  `[part="children"]` at all — byte-identical to an item authored before this feature existed.
+- 351a078: Added `lr-chart` (and every chart tag built on it -- `lr-bar-chart`, `lr-line-chart`,
+  `lr-scatter-chart`, `lr-bubble-chart`, `lr-pie-chart`, `lr-doughnut-chart`, `lr-radar-chart`,
+  `lr-polar-area-chart`, `lr-histogram`) three additive surfaces so a mixed dashboard chart no longer
+  needs to drop to raw Chart.js: `LyraChartSeries.stack` (a per-series Chart.js dataset `stack` group
+  id -- two groups on the same stacked axis are summed independently and drawn side by side);
+  `stackedAxes` (a per-value-axis override of `stacked`, so a stacked bar series on the primary axis
+  can sit next to an unstacked overlay series on `y2`); and `tooltipTitleFormatter`/
+  `tooltipFooterFormatter` (tooltip title/footer hooks receiving every hovered item's context at
+  once, in the same `LyraChartFormatterContext` shape `formatter`'s `'tooltip'` surface already
+  produces). `computeStackTotals()` is now computed per stack group as well as per axis, and the
+  canvas `stack-totals` data-label draws once per (axis, group) rather than once per axis. All three
+  additions are opt-in and unset by default: a chart that only sets the legacy `stacked` boolean
+  renders byte-identically to before. `lr-lite-chart` has no counterpart for any of the three --
+  documented as a deliberate omission (its single-value-scale, single-stack SVG bar-geometry model
+  and native per-mark `<title>` tooltip have no equivalent shape for a second value axis, a
+  per-series stack group, or a multi-item tooltip title/footer) rather than implemented.
+- 7ef4f5e: `<lr-combobox>` now takes part in the library's positioning-strategy contract. It exposes
+  `positioningStrategy` (attribute `positioning-strategy`), spelled the same as on `<lr-select>`,
+  `<lr-popover>`, `<lr-dropdown>`, `<lr-tooltip>` and `<lr-color-picker>`, and when the instance sets
+  nothing it honours the cascading `--lr-positioning-strategy` custom property ahead of its own
+  default.
+
+  Previously the listbox was always `fixed` through an undocumented internal default: an app that set
+  `--lr-positioning-strategy` once on `:root` to retune every floating surface silently left comboboxes
+  behind, and no instance could opt out. The default stays `fixed` — what the listbox has always
+  rendered, and the right choice for a typeahead list that usually sits inside a scrollable region — so
+  existing layouts do not move.
+
+  There is deliberately no `hoist` alias on this control. On `<lr-select>` it is Shoelace's established
+  spelling; here it would be a boolean defaulting to `true`, whose attribute could only ever express
+  the value the control already has. Use `positioning-strategy="absolute"` to opt out.
+- 4fc2bc1: `<lr-context-meter>`'s interactive mode can now express a non-actionable band. A `segments` entry
+  accepts `disabled`, which renders that band and its legend row as genuinely disabled controls — no
+  tab stop, no hover or press affordance, and no `lr-segment-activate` on activation. Previously a
+  band that filtered to nothing was still a fully enabled, tabbable button, so a keyboard user tabbed
+  through dead controls with no indication, and nothing distinguished the row visually.
+
+  Two derived state tokens join `segment-selected`/`legend-item-selected`, and all of them compose:
+  `segment-empty`/`legend-item-empty` for a band whose `value` is 0, and
+  `segment-disabled`/`legend-item-disabled` for a declared-disabled entry. `--lr-context-meter-disabled-opacity`
+  (default `0.5`) themes the disabled treatment.
+
+  Inertness is deliberately never inferred from `value === 0`: a zero band is legitimately clickable
+  in a token-budget meter, so the empty pair is a presentational hook with no built-in treatment while
+  `disabled` is declared by the consumer. A meter whose entries set neither renders exactly as before.
+
+  Internally this adds a shared `statePart()` helper, so a part name carrying several states is built
+  one way across the library instead of being hand-rolled per component.
+- 6c826ec: `<lr-file-input>` and `<lr-drop-zone>` can now enforce a cumulative `maxFiles`/`maxTotalSize` cap
+  across separate picker or drop sessions. Both limits previously counted only the files the control
+  itself held, so with `nonRetaining` (or after a reload in retaining mode) a user already holding 99
+  server-persisted files could add 50 more without the control ever rejecting, and the consumer had to
+  re-implement the aggregate check and render its own error.
+
+  Two optional numeric properties, `heldFileCount` (`held-file-count`) and `heldTotalSize`
+  (`held-total-size`), are the numeric counterpart of `valuePresent`: they are added to the running
+  totals before a batch is evaluated, in both retaining and non-retaining modes, so an over-cap batch is
+  rejected through the control's own rejection UI with the existing `maxFiles`/`maxTotalSize` reasons.
+  Both default to `0`, which reproduces today's behavior exactly, and a negative, `NaN` or infinite
+  value is treated as `0`. The `lr-files` detail also gains `remainingFiles` and `remainingTotalSize`
+  (`null` while that limit is unset), so a consumer can say how many more files may be added. The
+  aggregate arithmetic is now shared by both components, so the contract cannot drift between them.
+- 771d6fc: Five `<lr-filter-bar>` fixes.
+
+  An unset `'select'` or single `'combobox'` filter bound `''`, which those controls treat as a
+  committed unmatched value, so every page load showed their "not in catalog" treatment instead of the
+  declared placeholder. Unset now binds absent. The date branch deliberately keeps `''`, having no
+  catalog to mismatch against.
+
+  `activeFiltersDisplay` (`all` | `changed` | `hidden`, default `all`) controls the active-filter chip
+  row. It was unconditional, and a filter resting at its `defaultValue` counted as active — so a bar
+  whose default narrows the view claimed the user had narrowed it. `changed` lists only what the user
+  actually changed. The default reproduces today exactly.
+
+  The `'checkbox-menu'` trigger gains the disclosure caret its neighbours have, which also start-aligns
+  its content instead of centring a bold sentence in a stretched field, and its label and caret parts
+  are forwarded under the `filter-control-*` scheme.
+
+  A lean registration entry lets a bar pay only for the filter types it declares. The real cost was
+  that `filter-bar.class.ts` bare-imported eleven composed control modules it never referenced; those
+  are gone, so the class module is genuinely side-effect-free and the default entry still registers
+  everything for existing consumers.
+
+  The composed combobox tag's remove button is now forwarded, so a consumer re-skinning filter tags as
+  pills can style the control inside them instead of leaving library defaults in a custom pill.
+- 71e9296: `<lr-gauge>`'s value/label captions are now sized in `em` (`--lr-size-1em` for the value, and
+  `calc(var(--lr-size-1em) * 0.625)` for the label — the same 0.625 multiplier `--lr-font-size-2xs`
+  carries, kept as `em` math because the value-named token catalog's growth is frozen) instead of the
+  previous `rem`-anchored tokens (`--lr-font-size-m`, `--lr-font-size-2xs`, and, for the `linear`
+  shape specifically, a flat `--lr-size-0-5rem`). Every box in this component was already `em`-based
+  (`--lr-size-8em` for `radial`/`ring`, `--lr-size-12em` by `--lr-size-1-5em` for `linear`), so a
+  smaller `size` tier or a caller's own `font-size` on the host previously shrank the frame while the
+  caption stayed pinned to the document root — at the smallest tiers, or below them, the fixed
+  caption nearly filled or overflowed the box. The caption now scales with the same font-size that
+  sets the frame, so `<lr-gauge shape="linear" size="xs">` (or smaller) is usable as a compact
+  dashboard meter. At the default (unset `size`, unmodified ambient font) tier the resolved caption
+  size is unchanged.
+
+  New `showValue` property (default `true`, matching today's rendering) lets the decorative
+  `part="value"` caption be omitted — `<lr-gauge show-value="false">` — the same way an empty
+  `label` already omits the `part="label"` caption. Mirrors `<lr-progress-bar>`'s and
+  `<lr-progress-ring>`'s own `showValue` name and meaning; the default differs because a gauge's
+  purpose is showing the reading it announces, so hiding it is the opt-out. The accessible value
+  (`aria-valuenow`/`aria-valuetext`, the host's computed accessible name) is unaffected either way,
+  since the caption was always `aria-hidden`.
+- 2435dad: A blocked native form submission — clicking a `type="submit"` control, calling
+  `form.requestSubmit()`, or implicit Enter submission — now marks every invalid participant as
+  user-interacted, so `:state(user-invalid)` (and `:state(user-valid)` once corrected) matches
+  exactly like native `:user-invalid`/`:user-valid` do. Previously only an explicit
+  `control.reportValidity()`/`form.reportValidity()` call counted: a submission attempt drives
+  `ElementInternals` directly and never calls a control's own `reportValidity()` method, so
+  `aria-invalid` correctly went `true` on a blocked submit while the `user-invalid` custom state
+  silently stayed unset.
+
+  A control's own silent `checkValidity()` query continues to never count as interaction, however
+  invalid the control already is — this is unchanged and is the one path interactive validation is
+  deliberately distinguished from.
+
+  Affects every form control that manages `ElementInternals` directly rather than through the
+  `FormAssociated` mixin (the mixin itself already got this fix): `<lr-radio>`, `<lr-radio-button>`,
+  `<lr-radio-group>`, `<lr-checkbox>`, `<lr-checkbox-group>`, `<lr-switch>`, `<lr-slider>`,
+  `<lr-select>`, `<lr-combobox>`, `<lr-token-input>`, `<lr-time-range>`, `<lr-file-input>`,
+  `<lr-rating>`, `<lr-model-select>`, `<lr-voice-picker>`, `<lr-locale-picker>`,
+  `<lr-graph-query-builder>`, `<lr-tool-param-form>`, and `<lr-rubric-form>`. Every affected
+  component's `@cssstate user-valid`/`user-invalid` JSDoc is corrected to document the rule above
+  instead of the looser "or a native validity check"/"or an explicit validity report" wording some
+  of them previously carried.
+- 96c30ac: `<lr-model-select>` and `<lr-voice-picker>` catalog entries accept `disabled`. A disabled row renders
+  as a genuinely non-actionable control — no tab stop, no hover or press affordance — and keyboard
+  navigation steps over it without stranding focus. Both components share one catalog entry type, so
+  the contract cannot drift between them. An entry that does not set it renders exactly as before.
+- a80606f: `<lr-color-picker>` palette swatches accept `disabled`, so a swatch can be shown as unavailable
+  rather than silently doing nothing when chosen. The swatch renders genuinely disabled, selection
+  emits nothing, and keyboard navigation steps past it. A swatch that does not set it renders exactly
+  as before.
+- d6eb9b1: `<lr-flow-canvas>` nodes accept `disabled`, so a locked, read-only or in-progress node can be shown
+  without being activatable. The node's control renders genuinely disabled, activation emits nothing,
+  and roving focus steps past it. A node that does not set it renders exactly as before.
+- 62db946: `<lr-mention-popover>` items accept `disabled`, so an ineligible mention or command can stay visible
+  without being selectable. The row carries `aria-disabled`, activation emits nothing, and
+  active-descendant navigation steps over it without leaving focus stranded. An item that does not set
+  it renders exactly as before.
+- 5f4e877: `<lr-sequence-strip>` items accept `disabled`, so a step that cannot currently be opened stops being
+  a reachable control that does nothing. Activation emits nothing and roving focus steps past it. An
+  item that does not set it renders exactly as before.
+- 694032e: `<lr-suggestion-chips>` suggestions accept `disabled`, so a suggestion that is visible but not
+  currently offerable stops being a live, focusable control that does nothing. Activation emits
+  nothing and keyboard navigation steps past it. A suggestion that does not set it renders exactly as
+  before.
+- 3e5b916: Every `registrations.json` row now carries `localeKeys`: the `LyraMessageKey`s reachable by every tag
+  that importing it registers. It reuses the reachability walk that already derives the tree-shakeable
+  default-string slices — including keys a component reaches only through an indirect lookup table,
+  such as `lr-attachment-trigger`'s per-kind trigger and menu keys — rather than scanning for literal
+  `localize()` calls. Paired with `getRegisteredLyraLocaleKeys()`, a consumer can now verify that its
+  locale catalogue covers everything its rendered components can reach entirely from public, generated
+  metadata, with no parsing of `dist/`. The field is additive, so `schemaVersion` stays `1`.
+- 3e5b916: `registrations.json` now covers every published registration specifier, not just per-tag aliases.
+  The three published integration-bridge specifiers — `components/media/flag/flag-peer.js`,
+  `components/viewers/archive-viewer/archive-viewer-register.js` and
+  `components/viewers/ebook-viewer/ebook-viewer-register.js` — had no row at all, so a consumer asking
+  which tags importing one of them defines still had to walk `dist/`. They now appear in a new
+  top-level `integrations` array, each with a `registers` list derived from the module's real
+  transitive import closure (including the lazy `import()` a document-format registrar uses once a
+  matching file appears), never inferred from the file name.
+
+  Every row, in `entries` and `integrations`, also gains `distModule`: the registration module's own
+  published deep specifier. `registrationModule` is a `src/` path that cannot be resolved against the
+  tarball; `distModule` can.
+
+  The bridges live in their own array rather than as tag-less rows inside `entries`, because every
+  `entries` row has always carried `tag` and a reader keying by it would otherwise receive `undefined`.
+  All additions are additive, so `schemaVersion` stays `1`.
+- 83cde91: `<lr-streaming-text>`/`<lr-streaming-text-core>` forward the rest of the composed `<lr-markdown>`/
+  `<lr-markdown-core>` configuration surface verbatim: `tabSize`, `htmlMode`, `gfm`, `linkTarget`,
+  `internalLinkPrefix`, `headingOffset`, `highlightCode`, `headingAnchors`, `math`, and `maxHeight`,
+  alongside the already-forwarded `content`, `streaming`, and `languages`. Previously every one of
+  these was pinned at the composed element's default and unreachable through the wrapper, so a
+  consumer who had deliberately set, for example, `link-target=""` for same-tab links silently got
+  `target="_blank"` back after adopting `<lr-streaming-text>`. Each new property defaults to exactly
+  the composed element's own default, so leaving all of them unset renders identically to before.
+  The composed element still applies its own `rel="noopener noreferrer"` guard whenever a forwarded
+  `linkTarget` emits a `target`, and never a bare `opener`.
+- 3b1e717: `<lr-table>`'s `editTrigger: 'double-click'` inline cell editor is now reachable by keyboard, closing
+  a WCAG 2.1.1 gap: a `'double-click'` column's resting cell is its own `tabindex="-1"` roving-focus
+  stop, reachable with ArrowRight/ArrowLeft once the row itself has focus, and `F2` or `Enter` on that
+  focused cell opens its editor exactly as a double-click would. `Enter` on the row itself still only
+  activates the row. Closing the editor, by commit or by cancel, returns focus to the cell that opened
+  it. A new public `editCell(rowKey, columnKey)` method opens the same editor programmatically, for a
+  consumer's own key binding or menu action. A table with no `editTrigger: 'double-click'` column
+  renders byte-identical markup. `TableColumn.cell` is now optional for an `editTrigger: 'always'`
+  column, whose persistent editor renders unconditionally and never falls back to it; every other
+  column still requires `cell`.
+- f1612c9: `<lr-table>` columns gain `editLabel?: (row: T) => string`, mirroring the existing `editValue`/
+  `cellTitle` row callbacks: when defined, it becomes the inline cell editor's accessible name for
+  that row instead of the interpolated `tableEditCell` default (`Edit {column}`). The default is
+  identical for every row in a column, which is adequate for `editTrigger: 'double-click'` (only one
+  editor is ever open at a time) but not for `editTrigger: 'always'`, where every row's editor is a
+  permanent, individually focusable Tab stop -- a 50-row column with no `editLabel` exposed 50
+  identically named controls to keyboard and screen-reader users (WCAG 2.4.6, 1.3.1). A column that
+  omits `editLabel` renders byte-identical output to before.
+- 0baf79e: `<lr-table>` gains `rowExpandLabel?: (row, expanded) => string`, the accessible name for one row's
+  expand/collapse chevron. Every chevron was named from the same localized `expand`/`collapse` string,
+  so a long table exposed dozens of identically named Tab stops with no way to tell the rows apart —
+  the same shape as the inline editor's naming gap, on a different surface.
+
+  The default is unchanged, because this component has no row-header notion to derive row context from
+  (`rowKey` is an opaque identity, not a label), so a table that does not set the callback renders
+  byte-identically.
+- acb4266: Added `waitForLyraElement()` and `waitForToast()` to `@aceshooting/lyra-ui/testing`. `toast()`
+  registers `<lr-toast>`/`<lr-toast-item>` through a dynamic `import()` on first call, so a
+  fire-and-forget `toast(...)` -- the normal application pattern -- leaves the document empty for at
+  least one microtask, forcing a downstream test to hand-write a polling loop before it can assert on
+  the toast's rendered text. `waitForLyraElement(selector, options?)` is a generic, bounded,
+  event-driven awaitable (`MutationObserver` plus `customElements.whenDefined()`, no busy polling) for
+  "a matching library element is connected and upgraded," reachable from an optional `root` and
+  filterable by an optional `match` predicate; it rejects with a descriptive error after a bounded
+  timeout (2000ms default). `waitForToast(match?, options?)` is the named convenience for `<lr-toast-item>`,
+  matching by trimmed text or a predicate. Both run in a real browser and in the documented happy-dom
+  test environment. `confirm()` was swept too: it registers `<lr-dialog>` synchronously and has no
+  equivalent gap, so it gets no new helper.
+- 857f2ef: `@aceshooting/lyra-ui/theme-bootstrap.js` -- the static, external no-flash theme script for a
+  strict Content-Security-Policy -- now reads `data-lr-theme-storage-key` and
+  `data-lr-theme-attributes` (space-separated) from its own `<script>` tag via
+  `document.currentScript` at parse time, so an application with its own pre-existing `localStorage`
+  key can use the shared static asset instead of inlining a per-app copy generated from
+  `createLyraThemeBootstrap({ storageKey })`. Both attributes are optional and validated, failing
+  closed to today's baked-in defaults (`'lyra-theme'` and `data-lr-theme`/`data-theme`) on an absent,
+  empty, oversized, or malformed value -- including an attribute-name list entry that is not a safe
+  `data-*`-shaped token (rejecting `on*` handler names, `style`/`class`/`id`, and anything containing
+  whitespace, a quote, `=`, or a control character), a list longer than eight entries or with a
+  duplicated entry, an oversized storage key, or a `null` `document.currentScript` (module/async
+  misuse). A `<script>` tag carrying neither attribute -- every existing deployment, and every inline
+  use of `lyraThemeBootstrap`/`createLyraThemeBootstrap()` -- behaves exactly as before.
+
+### Patch Changes
+
+- 2787a1d: `<lr-button>` now re-evaluates its icon-only geometry when the slotted label's visibility changes
+  through CSS alone. Detection ran on `slotchange` and once on the first update, so the most natural
+  responsive idiom — a container or media query hiding the label at a narrow width — changed computed
+  style with no DOM mutation and nothing re-ran: the button kept full text geometry, padding and
+  min-width around an invisible label. It happened to look right only when the element was created
+  after the breakpoint was already crossed, which made it read as an intermittent bug.
+
+  A `ResizeObserver` now watches the label wrapper's own box. It deliberately does not watch the host
+  or the base part: once icon-only, those take a fixed size, so widening the container would not resize
+  them and the button could never flip back — the same one-way trap the fix exists to remove. The
+  recompute is deferred to an animation frame, matching `<lr-textarea>`'s auto-grow observer, because a
+  microtask-deferred write lands inside the same delivery pass and trips a ResizeObserver loop warning.
+- 1059b56: Fixed `custom-elements.json` silently omitting `value`, `name`, `required`, and `disabled` (as both
+  members and attributes) for a `FormAssociated` component that inherits the mixin through a
+  superclass in a different module rather than declaring it directly -- `lr-number-input` and
+  `lr-native-time-input` (both extend `LyraInput`, which owns the mixin). The
+  `lr-form-associated-mixin-members` custom-elements-manifest plugin's superclass-chain walk already
+  found and back-filled these declarations correctly; the gap was that `scripts/manifest-compact.mjs`
+  runs as a separate pass after `cem analyze` and prunes any member/attribute whose `inheritedFrom`
+  resolves to an identical entry on the named superclass, which is exactly what the back-filled (and,
+  for `value`, CEM's own natively-inherited) entries looked like. Both tags now carry the same
+  member/attribute shapes, types, and defaults as every other `FormAssociated` consumer. Manifest
+  accuracy only -- runtime behavior was already correct.
+- 0b207cb: Docs: every component whose icon-only action became a composed `<lr-icon-button>` in 16.0.0 now
+  carries the migration note that only `lr-copy-button` had. A `::part()` rule that used to paint that
+  button now names the composed child's host, which paints nothing — and because `color` still
+  inherits, such a rule looks half-alive rather than broken, which is how it escapes review. The note
+  says what to do instead: set the `--lr-icon-button-*` paint tokens on the component or an ancestor,
+  and use `--lr-theme-icon-button-size` for size, since `--lr-icon-button-size` is re-declared on every
+  host and never reaches a composed child.
+
+  Also pins the border half of that contract with a test: an ancestor `--lr-icon-button-border` does
+  reach a composed control, so border is not the one paint property that silently dies.
+- ef05323: Fixed `<lr-confirm-bar>`'s `returnFocusTo` thunk resolving before a reactive host could re-create
+  the control it names. The documented motivating case -- a host that conditionally swaps a focused
+  trigger out for this bar, then swaps a brand-new trigger back in once a decision lands -- could
+  never work: every supported host framework re-renders asynchronously relative to the bar's own
+  synchronous focus handoff, so the thunk's first (and, previously, only) call always found the
+  replacement control missing and fell back past `[part="status"]` to `<body>` once the host's own
+  re-render removed the bar.
+
+  When the thunk's immediate resolution fails, the handoff now retries once more after the host has
+  had a real chance to react, and moves focus there only if it has since appeared, is connected and
+  focusable, and nothing else has claimed focus in the meantime. An immediately-resolving thunk or a
+  plain element value is unaffected -- resolved once, synchronously, exactly as before.
+
+  The retry is a new shared primitive, `deferComposedFocusRepair()` (plus its `nextHostUpdateOpportunity()`
+  timing helper), in `src/internal/focus-navigation.ts`, built on the existing
+  `captureComposedFocusRepair()`/`applyComposedFocusRepair()` pair so any other component with the same
+  shape -- a return-focus thunk naming a control its host re-creates asynchronously -- can adopt it
+  directly.
+- 71e9296: Fixed: `<lr-context-meter shape="ring">`'s centered caption (`.ring-label`, inside `part="label"`)
+  now sizes itself in `em` (`calc(var(--lr-size-1em) * 0.625)`) instead of the previous
+  `rem`-anchored `--lr-font-size-2xs`. The ring itself is already `--lr-size-8em`, so a caller's own
+  `font-size` on the host shrinks the ring but previously left the caption pinned to the document
+  root — the same defect shape `<lr-gauge>`'s linear caption had. At the default (unmodified ambient
+  font) size the resolved caption size is unchanged.
+- 63ee11b: `<lr-data-grid>` no longer treats an unchanged re-bind of `filters` or `sort` as a change. Both
+  setters rebuilt a fresh frozen array on every write, so the new reference was never `===` the old one
+  and Lit's dirty check always reported a change. Because a `filters`/`sort` change schedules a server
+  request — and a `filters` change schedules the *debounced* one — a host that re-binds these
+  properties on every render (the ordinary controlled pattern, often driven by the grid's own events)
+  could push the server request further away indefinitely, and re-rendered for nothing in the meantime.
+
+  The setters now compare the normalized content and keep the held value, including its reference, when
+  nothing actually changed. A genuinely different value still schedules exactly as before.
+- 36f83ca: `<lr-input>`'s and `<lr-textarea>`'s `debounce` no longer silently stops working under the
+  controlled-input pattern. A pending `lr-input-settled` was cancelled by any programmatic `value`
+  write, including the one every framework binding makes on each render when it writes the just-typed
+  value straight back, so the event simply never fired and nothing warned. Only a write that actually
+  changes the value now cancels the pending settle; a write of the value already held leaves it
+  pending. A genuinely different value still supersedes the in-flight edit, exactly as before.
+
+  The fix lives in the shared `DebounceController` (a new `cancelIfChanged()`), so every debounced
+  control that routes external writes through it gets the same contract.
+- 622e12c: `formatNumber`, `formatDate`, `formatRelativeTime`, `formatBytes` and the exported `binValues()` now
+  treat an omitted `locale` as the app's active locale instead of hardcoding English. They passed the
+  argument straight to the Intl cache, whose resolver starts at `'en'`, so an app that called
+  `setLyraLocale('fr')` saw every component render French while these standalone helpers silently stayed
+  English — and it looked correct in any English-locale test run.
+
+  An explicit `locale` argument still wins, and an app that never calls `setLyraLocale()` gets
+  byte-identical output: the resolution consults only the pinned active locale and deliberately does
+  not fall through to `<html lang>` or `navigator.language`, since a bare function call has no host
+  element to resolve against.
+- 6130112: Fix: the seven built-in controls that compose `<lr-icon-button>` for an icon-only action
+  (`<lr-callout>`, `<lr-dialog>` — inherited by `<lr-drawer>` — `<lr-code-block>`, shared by
+  `<lr-code-block-core>`, `<lr-message-actions>`, `<lr-reorder-item>`, `<lr-attachment-trigger>`, and
+  `<lr-copy-button>`) no longer capture a public `--lr-icon-button-*` token on their own `:host` and
+  re-declare that same public name on the composed part. `<lr-icon-button>` now carries a private
+  `--_lr-icon-button-<token>-default` fallback tier for every paint token (background/color/border and
+  their hover/active variants), generalizing the existing `--_lr-icon-button-radius-default` shape;
+  each composing component sets its own default directly on that private tier instead of the public
+  one. An ancestor `--lr-icon-button-*` override still wins exactly as before — `<lr-icon-button>`'s
+  own stylesheet checks the public token first, ahead of any default a composing parent supplies — but
+  no descendant declares the public name from a private token derived from that same public token
+  anymore, so a scope-flattening custom-property resolver with no notion of which element declared
+  what (happy-dom, at least through 20.14.5) no longer sees a cycle: rendering any of the seven
+  controls under such an environment no longer throws `RangeError: Maximum call stack size exceeded`.
+  Revises the `llms/shared.md` testing note added in 16.0.0 to match — current versions are
+  unaffected. No public API changed.
+- 2435dad: Verified and documented that `--lr-icon-button-border` reaches every 16.0.0 composed icon action
+  (`<lr-dialog>`'s close control, `<lr-reorder-item>`'s move controls, `<lr-code-block>`'s copy
+  control, `<lr-attachment-trigger>`'s trigger) the same way `--lr-icon-button-background`/`-color`/
+  `-radius` do. A report read the absence of a relayed `--_lr-icon-button-border-default` on
+  `<lr-dialog>`/`<lr-reorder-item>`/`<lr-code-block>` (none of which paint a resting border) as
+  border theming being broken for those components. Rendered `getComputedStyle` assertions now cover
+  all four components, including `<lr-attachment-trigger>`'s `outlined`/`filled-outlined`
+  appearances, which DO relay a non-zero border default and must still let an ancestor's public
+  token override it. No source change was needed — the public token was already the first, winning
+  arm of the fallback chain in every case; only test coverage and the authored `llms/` reference
+  pages were missing an explicit statement of the rule.
+- af075a9: Docs: corrected the token-scope contract for `--lr-icon-button-size`, `--lr-otp-input-segment-size`,
+  and `--lr-popover-viewport-clamp`. All three read like ordinary per-component
+  `--lr-<component>-*` tokens, but the shared base token layer (`internal/tokens.styles.ts`) declares
+  each of them on its own `:host` block, which every `lr-*` component includes -- so, like
+  `--lr-focus-ring-width`/`-color`/`-offset`, a rule that sets one of them on an ancestor is reset at
+  the first intervening `lr-*` component and never reaches a nested target. This was always the
+  behavior (and is already asserted by `internal/tokens.test.ts`); the docs previously implied all
+  `--lr-icon-button-*`/`--lr-otp-input-*` tokens inherit uniformly from an ancestor, which is true for
+  every other one of them (e.g. `--lr-icon-button-radius`/`-background`) but not these. Updated
+  `lr-icon-button`'s and `lr-otp-input`'s own `@cssprop` JSDoc, the icon-button and otp-input entries
+  in `llms/forms.md`, and the design-token overview built by `scripts/build-llms.mjs`
+  (`llms/tokens.md`) to state the general rule once and name the affected tokens; added test coverage
+  proving the asymmetry against a nested shadow root. No runtime behavior changed and no token was
+  renamed.
+- 616e6d6: Twenty components derived state from their slotted children only through a `slotchange` listener, so
+  they depended on the environment firing that event for a slot's INITIAL assignment. A DOM
+  implementation that does not — happy-dom, through 20.14.5 — leaves that state empty forever when the
+  children already exist at connect, which is what the ordinary conditional-render pattern produces.
+  Most visibly, an `<lr-select>`/`<lr-combobox>` whose `<lr-option>` children are rendered in the same
+  commit had zero options there, so the shipped `chooseOption()` testing driver threw, contradicting
+  the testing entry's own cross-environment promise.
+
+  Each affected component now also collects once on first update, from the slot's assigned elements,
+  through a shared helper. The collection is idempotent, so a real browser firing the initial event as
+  well changes nothing. Also fixed along the way: `lr-menu`'s collection was not idempotent (a second
+  pass misread the settled active item as having moved and stole focus), and `lr-chart` could have an
+  already-collected slotted config clobbered back to undefined by a phantom `slotchange` fired at the
+  slot element discarded during its loading-to-loaded render swap.
+
+  About eighty other components were checked and already seed their slot-derived state eagerly; they
+  are unchanged.
+- 9c19aed: The cascading `--lr-positioning-strategy` custom property (`src/internal/positioning-strategy.ts`)
+  was documented as read by "every anchored/positioned overlay in this library", but until now only
+  `<lr-select>`, `<lr-popover>` (and `<lr-dropdown>` through it), `<lr-tooltip>`, `<lr-color-picker>`
+  and `<lr-combobox>` actually routed their placement through the shared resolver. An app that set the
+  property once on `:root` to retune every floating surface silently left every other anchored surface
+  behind.
+
+  `<lr-menu>` (the private submenu surface), `<lr-mention-popover>`, `<lr-export-button>`,
+  `<lr-usage-badge>`, `<lr-tool-call-chip>`, `<lr-tour>`, `<lr-locale-picker>`, `<lr-date-input>`,
+  `<lr-time-input>`, `<lr-citation-badge>`, `<lr-entity-chip>`, and `<lr-app-rail-item>` now honour the
+  same cascading property. None of them exposes a per-instance `positioning-strategy` property — that
+  remains a separate, deliberate decision — so an ancestor override is the only way to change them, and
+  their own default stays exactly what it always rendered (`fixed` in every case), so nothing moves for
+  anyone who sets nothing.
+
+  `<lr-popup>`, the low-level positioning primitive, is deliberately excluded: its own `strategy`
+  property is a plain, always-defined value (default `'absolute'`, never `undefined`), so there is no
+  way to distinguish "left unset" from "authored the default" without adding the same
+  explicit-vs-default tracking machinery the higher-level components' `positioning-strategy` property
+  uses — which this sweep does not add anywhere. It is also meant to be composed directly by a consumer
+  who already controls `strategy` explicitly.
+- 2435dad: Added `pnpm run regen`, a single command that runs every source-artifact generator (manifest,
+  component inventory, framework types, events, the testing event registry, component metadata,
+  registrations/tag-aliases, the autoloader manifest, the registration graph, default-string and
+  translation slices, the three palette generators, design tokens, reservation styles, editor data,
+  and llms) in real dependency order, so a batch of source changes no longer needs a human to
+  remember and re-run each generator individually before `pnpm lint`. Added `scripts/check-regen-
+  coverage.mjs` (wired into `contract-policy` as `check:regen-coverage`/`test:regen-coverage`), a
+  gate that derives which generators `regen` must reach directly from the freshness gates themselves
+  — a same-file `--check`/write argument pair, a gate's own `pnpm run <name>` remedy text, or a gate
+  that imports/references a generator file directly — rather than a hand-kept list, so a newly added
+  or renamed generator cannot silently fall out of `regen` again. No runtime behavior changed;
+  `pnpm run regen` on an already-fresh tree is a no-op.
+- 74a887b: `<lr-table>` no longer gets stuck with `priority`-hidden columns after the table widens back out.
+  Narrowing correctly hid `low`/`medium` columns once their content actually overflowed, but widening
+  never restored them: `recomputeHiddenPriorityColumns()` reconstructed "how wide would everything be"
+  by adding a hidden tier's cached natural width to `[part='base']`'s CURRENT `scrollWidth` — and once a
+  tier was hidden, `[part='table']`'s own `inline-size: 100%` stretched the remaining columns to fill
+  any leftover room, so that `scrollWidth` tracked `clientWidth` instead of the remaining content's real
+  width. The reconstructed total then chased whatever the container currently measured rather than the
+  actual content, so `overflowAtFull` never dropped enough to re-admit a hidden tier — `reload` or
+  `priorityColumnsVisible = true` were the only ways back, because both bypass the measurement entirely.
+
+  The fully-visible width is now reconstructed from three independently cached natural widths (the
+  always-visible columns, plus each hidden tier) instead of from the currently-rendered, potentially
+  stretched `scrollWidth`. Every cache is refreshed only on a pass where the table is genuinely too wide
+  for its container — the one condition under which nothing rendered has spare room to stretch into, and
+  necessarily true on the pass that first decides to hide anything — so a widening container now
+  correctly restores every tier that fits, without the restored tier immediately re-hiding on the very
+  next measurement pass its own restoration triggers.
+- 2435dad: Fixed `<lr-input>`'s required-field description, `<lr-task-list>`'s per-item status label,
+  `<lr-transcript-feed>`'s interim "Transcribing…" marker, and `<lr-filter-bar>`'s touched-required
+  inline error and hidden filter-control label: all four rendered `class="sr-only"` without
+  composing the shared `srOnly` style block from `internal/a11y.ts` into their own
+  `static override styles`, so the class name did nothing and the assistive-only text rendered as
+  ordinary visible content instead of being clipped to a 1px box. Each component now composes the
+  shared `srOnly` export, matching the reference shape in `time-input.class.ts`.
+
+  Added `scripts/check-visually-hidden.mjs` (with its own `scripts/check-visually-hidden.test.mjs`
+  unit tests), a new static gate wired into `contract-policy`/`pnpm lint` as
+  `check:visually-hidden`/`test:visually-hidden`. It flags any `*.class.ts` file whose render
+  template applies the `sr-only` class without either composing the shared `srOnly` export or
+  declaring a matching scoped `.sr-only { ... }` rule in its own sibling `*.styles.ts`, so this
+  class of defect fails CI instead of shipping silently. Added browser regression tests for all four
+  components asserting the rendered `getComputedStyle()` result (clipped, absolute-positioned, with
+  the accessible text still present in the DOM), plus explicit `<lr-input>` coverage of the pristine
+  (no visible required text, error part hidden) and failed-submission (error becomes visible) states.
+
 ## 16.0.0
 
 ### Major Changes
@@ -65,6 +814,15 @@
   reading a painted value off it (`getComputedStyle(node).backgroundColor`) needs
   `node.shadowRoot.querySelector('[part~="button"]')`.
   
+  **Size is the one token that does NOT follow that rule.** `--lr-icon-button-background`/`-color`/
+  `-radius`/`-border` inherit down to a composed action, but `--lr-icon-button-size` set on the
+  wrapping component does not reach it, and `min-inline-size`/`min-block-size` written on the old
+  part cannot push the nested control past its own floor — so a pre-16 rule that sized one of these
+  controls, including a coarse-pointer touch-target pair, is inert with no visible symptom. Use
+  `--lr-theme-icon-button-size` instead; it is the hook that crosses into the composed child. This
+  applies to every component in the table above, not only `<lr-copy-button>`, whose reference page
+  was previously the only place it was written down.
+  
   **Not affected by this change.** Other icon-sized built-in buttons deliberately stay native
   `<button>`s in 16.0.0, so every rule you already wrote against them still applies: `<lr-alert>`,
   `<lr-toast-item>`, `<lr-lightbox>` and `<lr-tool-result-dialog>` close buttons; `<lr-chip>`,