@aceshooting/lyra-ui 27.0.0 → 28.0.0

package/llms/components/lr-app-rail.md

@@ -9,7 +9,7 @@
 - **Release history** [CHANGELOG.md](../../CHANGELOG.md)
 - **Deprecations** none
 - **Optional peers** none
-- **Themeable via** 11 parts, 33 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 13 parts, 37 custom properties — see this component's own `@csspart`/`@cssprop` list below
 - **Documented with** `lr-app-rail-item`, `lr-app-rail-group` (same section below)
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
 
@@ -113,6 +113,31 @@ letting a consumer that syncs app chrome to the rail's mode pick up the restored
   a reload only when `storage-key` is set AND `persist` includes `preferred-mode` — the default
   `persist` is `open width`, which does not. Pair them: `persist="width preferred-mode"`. Either
   route announces itself through the existing `lr-mode-change` event; there is no new event.
+- `autoHide: boolean = false` (reflected, attribute `auto-hide`) — opts the desktop rail into an
+  auto-hide ("peek") mode. The rail rests as the `'icon-only'` strip (an unset `preferredMode` reads
+  as `'icon-only'` instead of following `icon-only-breakpoint`; `preferredMode` and `forceMode` keep
+  their meaning). While a non-touch pointer moves inside the strip, or keyboard focus enters it, the
+  rail expands to full width as an overlay: the strip's inline footprint stays in the layout, so the
+  content beside it never reflows, and the expansion grows toward the inline end and mirrors under
+  RTL. It collapses back once the pointer has left and keyboard focus is no longer inside, after
+  `peekCloseDelay`; Escape closes it at once and it stays closed until the pointer and focus have
+  both left. Touch pointers and boundary events fired with no movement (a cursor resting where the
+  page loaded) never open it, and pointer-originated focus (a click) does not hold it open. The rail
+  docks at full width only while pinned: the built-in `[part="pin-button"]` writes
+  `preferredMode`, so it persists through `storage-key` with `persist` including `preferred-mode`
+  (the default `persist` does not, so set `persist="preferred-mode"`). The mobile presentation is
+  unchanged, `[part="collapse-toggle"]` is not rendered while this is set (the pin replaces it),
+  `mode` stays `'icon-only'` while peeking, and the resizer is hidden until pinned. Unset reproduces
+  today's exact behavior.
+- `peekOpenDelay: number = 150` (attribute `peek-open-delay`) — milliseconds a moving pointer must
+  stay inside the strip before it peeks open; keyboard focus opens it at once. Non-finite values use
+  the default and negative values clamp to `0`.
+- `peekCloseDelay: number = 300` (attribute `peek-close-delay`) — milliseconds the peek stays open
+  after the pointer left and keyboard focus is no longer inside. Non-finite values use the default
+  and negative values clamp to `0`.
+- `peeking: boolean` (read-only getter, reflected `peeking` attribute) — whether the `auto-hide`
+  rail is currently expanded as a temporary overlay. Always `false` while `auto-hide` is unset or the
+  rail is pinned (`'full'`) or `'mobile'`. Disconnecting resets it silently.
 - `withoutToggle: boolean = false` (reflected, attribute `without-toggle`) — suppresses the built-in mobile
   `[part='toggle']` hamburger/OPEN button, for a consumer that already owns an external mobile-menu
   trigger wired to this rail's own `open` property (pair it with `trigger`/`for` below so focus
@@ -229,7 +254,9 @@ built-in control does, for a consumer rendering its own control (app chrome, a c
 keyboard shortcut). A no-op while `mode` is `'mobile'`. While `forceMode` pins the mode the
 preference alternates relative to `preferredMode ?? mode` on every call and takes effect once the pin is released.
 
-**Events:** `lr-mode-change` (`detail: LyraAppRailModeChangeDetail` = `{ mode: LyraAppRailMode }`; the
+**Events:** `lr-peek-change` (`detail: LyraAppRailPeekChangeDetail` = `{ peeking: boolean }`; the
+`auto-hide` rail started or stopped peeking; non-cancelable, and not fired for the silent reset a
+disconnect performs), `lr-mode-change` (`detail: LyraAppRailModeChangeDetail` = `{ mode: LyraAppRailMode }`; the
 effective mode changed, whether from a breakpoint crossing, a `forceMode` assignment, or a
 persisted `preferred-mode` restored on mount (`storage-key` + `persist="preferred-mode"`) — the
 restored-on-mount case fires once, from the first `updated()` after that mount's render and
@@ -272,7 +299,10 @@ underlying element — see above), `resizer` (the `resizable` opt-in's drag hand
 `aria-controls` at `[part="nav"]` — the item list whose presentation actually changes, never the
 containing `[part="base"]`/`[part="panel"]` — and takes a localized name from the
 `appRailCollapse`/`appRailExpand` keys) and `collapse-icon` (the chevron wrapper, mirrored by its own
-`transform` under RTL). Collapsing to `'icon-only'` keeps each item's own accessible name and
+`transform` under RTL), `pin-button` (the `auto-hide` pin control, rendered inside `[part="header"]`
+while the rail is peeking or pinned, never in the resting strip; `aria-pressed` renders `"true"`
+while pinned and `"false"` otherwise, the name comes from the `appRailPin`/`appRailUnpin` keys, and it
+takes the `--lr-icon-button-size` hit area) and `pin-icon` (its glyph wrapper). Collapsing to `'icon-only'` keeps each item's own accessible name and
 clips its `label`/`meta` visually, while hiding nested disclosure controls and child lists — so `aria-expanded` reports which of the two
 presentations is on screen, for magnifier and braille users, rather than announcing hidden content.
 
@@ -287,6 +317,13 @@ panel; no value can paint elevation while closed. Prefer that token over an unqu
 `::part(panel)` shadow rule, which would also paint while closed; state-scope a part override with
 `lr-app-rail[mode="mobile"][open]::part(panel)`.
 
+`--lr-app-rail-peek-shadow` (default `var(--lr-shadow-l)`) and `--lr-app-rail-peek-bg` (default
+`var(--lr-color-surface-overlay)`) restyle the `auto-hide` rail while it overlays the content; the
+overlay sits on the `--lr-layer-dropdown` layer token, below modals and popovers.
+`--lr-app-rail-pin-hover-bg` (default `var(--lr-color-brand-quiet)`) and
+`--lr-app-rail-pin-hover-color` (default `var(--lr-color-brand)`) tint the pin control on hover.
+Motion uses the shared transition tokens and stops under `prefers-reduced-motion`.
+
 Other hooks: `--lr-app-rail-width` (default `15rem` — the inline rail width in
 `'full'` mode), `--lr-app-rail-icon-width` (default `4rem` — the inline rail width in `'icon-only'`
 mode), `--lr-app-rail-mobile-width` (default `18rem`, capped at `85vw` — the mobile overlay panel
@@ -373,6 +410,16 @@ fallback at its exact state rule and preserves the previous brand or active-mix
 </script>
 ```
 
+An auto-hide sidebar that peeks open over the content and docks only when pinned, remembering the pin:
+
+```html
+<lr-app-rail auto-hide label="Workspace" storage-key="app" persist="preferred-mode">
+  <lr-app-rail-item href="/inbox" current>
+    <svg slot="icon" aria-hidden="true">...</svg>Inbox
+  </lr-app-rail-item>
+</lr-app-rail>
+```
+
 ```ts
 rail.forceMode = "icon-only"; // force a presentation regardless of viewport width
 rail.forceMode = "auto"; // release the force, resume live breakpoint tracking
@@ -381,7 +428,7 @@ rail.forceMode = "auto"; // release the force, resume live breakpoint tracking
 The package root also exports a pure `computeAppRailMode(iconOnlyMatches: boolean, mobileMatches:
 boolean, preferredMode?: 'full' | 'icon-only' | null): LyraAppRailMode` resolver (plus the
 `LyraAppRailMode`/`LyraAppRailModeInput`/`LyraAppRailPreferredMode`/`LyraAppRailPersistField`/
-`LyraAppRailModeChangeDetail`/`LyraAppRailToggleDetail`/`LyraAppRailResizeDetail` types) — the same
+`LyraAppRailModeChangeDetail`/`LyraAppRailToggleDetail`/`LyraAppRailResizeDetail`/`LyraAppRailPeekChangeDetail` types) — the same
 logic the element's internal `matchMedia` listeners call, exposed standalone so a
 consumer can compute or unit-test the same resolution without a real browser window. `mobileMatches`
 wins over everything else when true (the viewport is narrower than both breakpoints at once);

package/llms/components/lr-emoji-picker.md

@@ -178,15 +178,20 @@ one declaration to retheme every internal scroll container in the library.
 
 **Optional peer dependency:** install `emoji-picker-element-data` with
 `pnpm add emoji-picker-element-data` for the built-in auto-loaded default emoji set — omit it and
-supply `groups` directly instead. The loader never throws; a missing or failed peer logs one
-`console.warn` and leaves `groups` empty, and the picker then **fails closed and visibly**: the
-grid renders a distinct localized `[part="load-error"]` surface instead of the ordinary
-`[part="empty"]` message, so a skipped install is distinguishable at a glance from a genuine
-zero-match search or a deliberate `groups = []` opt-out, announces the same message once
+supply `groups` directly instead. The loader never throws; it leaves `groups` empty and logs one
+`console.warn` that names the cause: the peer **is not installed** (its module cannot be resolved)
+or it **was found but could not be loaded or validated** (a network or JSON/import-attribute error,
+an incompatible version, or a module without the expected data array). The picker then **fails
+closed and visibly**: the grid renders a distinct localized `[part="load-error"]` surface instead
+of the ordinary `[part="empty"]` message — `emojiPickerPeerMissing` ("Emoji are not available.")
+for a missing peer, `emojiPickerLoadError` ("Could not load emoji.") with the `load-retry` button
+for a failed one — so a skipped install is distinguishable at a glance from a broken one, a
+genuine zero-match search or a deliberate `groups = []` opt-out. It announces the same message once
 through the document's shared assertive live region (not a shadow-root `role="alert"`, which
-announces unreliably) and emits `lr-load-error` (no detail). The failed load is not cached: the
-`load-retry` button (or a later locale change) loads again, and a successful retry clears the
-failure. Assigning `groups` also clears it. The adapter buckets the peer's flat
+announces unreliably) and emits `lr-load-error` (no detail) in both cases. A failed load is not
+cached: the `load-retry` button (or a later locale change) loads again, and a successful retry
+clears the failure. No Retry button is offered for a missing peer, since retrying cannot install
+it. Assigning `groups` also clears it. The adapter buckets the peer's flat
 entry list by numeric group id and returns only the public `{ key, label, emojis }` shape. The picker
 privately maps auto-loaded group ids 0–9 to the existing `emojiPickerGroup*` locale strings; override
 those through `registerLyraLocale()` or `.strings`. An unknown future group id uses `Group {id}`.

package/llms/components/lr-icon-button.md

@@ -9,7 +9,7 @@
 - **Release history** [CHANGELOG.md](../../CHANGELOG.md)
 - **Deprecations** none
 - **Optional peers** `dompurify` — see `llms/peers.md`
-- **Themeable via** 3 parts, 11 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 3 parts, 12 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`
 
 ---
@@ -166,6 +166,18 @@ it inherits normally from an ancestor even through an intervening component; it
 counterpart to it. The internal control sets `font: inherit`, so an `em`-sized slotted glyph takes
 the surrounding text's font-size rather than the native button's UA default.
 
+`--lr-icon-button-padding-inline` (default `0`) is the logical inline padding of the
+`[part='button']` control, for a compact trigger that shows a short text value (a currency, unit or
+locale code) instead of a square glyph. It inherits from an ancestor like the radius. The default
+keeps an icon-only button at exactly its `--lr-icon-button-size` floor; padding adds to the
+content, so a label grows the button and the hit-area floor still applies. Block padding stays 0.
+
+```html
+<lr-icon-button aria-label="Currency: euro" style="--lr-icon-button-padding-inline: var(--lr-space-s)">
+  <span>€ EUR</span>
+</lr-icon-button>
+```
+
 The rest come in resting/hover/pressed triples, each falling through to the next-quieter state so
 setting only one still behaves:
 

package/llms/components/lr-image-viewer.md

@@ -30,6 +30,14 @@ apply when that wrapper itself owns keyboard input. Enter on a highlight button
 highlight without starting or committing an annotation, whether or not a draft exists; wrapper arrow
 commands retain physical image-coordinate semantics in both directions.
 
+A region highlight paints exactly the percentage rectangle it names, at every fit, zoom and
+rotation: its box never takes the shared `--lr-icon-button-size` minimum, so a small region cannot
+grow past its data or overlap a neighbour. The accessible pointer target is a separate transparent
+`::after` of the `[part="highlight"]` button, centred on the box and grown to
+`--lr-icon-button-size` on any axis where the box is smaller. Overlap rule: a region's own painted
+box always wins over another region's enlarged area, and where only enlarged areas overlap the
+later highlight in document order wins. Keyboard navigation between highlights is unaffected.
+
 **Properties:** `src: string = ''`, `name: string = ''`, `alt?: string`,
 `fit: LyraImageFit = 'contain' | 'width' | 'actual'` (reflected; invalid writes normalize to
 `contain`), `zoom: number = 1` (reflected), `minZoom: number = 0.5` (attribute

package/llms/components/lr-pagination.md

@@ -9,7 +9,7 @@
 - **Release history** [CHANGELOG.md](../../CHANGELOG.md)
 - **Deprecations** none
 - **Optional peers** none
-- **Themeable via** 22 parts, 22 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 22 parts, 23 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`
 
 ---
@@ -203,7 +203,9 @@ buttons, the numbered pages and the page input — `--lr-pagination-control-padd
 `--lr-pagination-control-size`, so this only adjusts the icon/digit inset. Layout spacing is split
 across `--lr-pagination-base-gap` (default `var(--lr-space-m)`) between summary and controls,
 `--lr-pagination-controls-gap` (default `var(--lr-space-xs)`) inside the navigation group, and
-`--lr-pagination-pages-gap` (default `var(--lr-space-xs)`) between numbered pages; each remains
+`--lr-pagination-pages-gap` (default `var(--lr-space-xs)`) between numbered pages, and
+`--lr-pagination-page-field-gap` (default `var(--lr-space-2xs)`) between the compact
+`[part="page-input"]` and its `[part="page-count"]`; each remains
 active in standard, compact, and 320px container layouts —
 `--lr-pagination-invalid-border` (default `var(--lr-color-danger)`) — border color of
 `[part="page-input"]` while the typed page is out of range (`aria-invalid="true"`); a state hook

package/llms/components/lr-segmented.md

@@ -101,11 +101,15 @@ The floor at the two compact tiers is the ladder's own (20px at `2xs`, 24px at `
 `2xs`/`xs` _segment_ separately carries a 24×24px minimum box, so the tappable target holds even
 when a label is a single character and the track ends up taller than its nominal floor.
 
-`--lr-segmented-selected-bg` (default `var(--lr-color-surface)`), `--lr-segmented-selected-color`
-(default `var(--lr-color-text)`), `--lr-segmented-selected-font-weight` (default
+`--lr-segmented-selected-bg` (default `var(--lr-color-text)`), `--lr-segmented-selected-color`
+(default `var(--lr-color-surface)`), `--lr-segmented-selected-font-weight` (default
 `var(--lr-font-weight-semibold)`) and `--lr-segmented-selected-shadow` (default
 `var(--lr-shadow-xs)` — the shallowest step in the elevation scale, since the checked segment is a
-thumb lifted a hair off its own track) style the checked segment's pill;
+thumb lifted a hair off its own track) style the checked segment's pill. The default pill is the
+inverse of the surface (text-coloured fill, surface-coloured label), so the checked state stays at
+least 3:1 against a card or dialog in every look and mode; when you override
+`--lr-segmented-selected-bg`, also set `--lr-segmented-selected-color` to a label that contrasts with
+your fill;
 `--lr-segmented-hover-color` (default `var(--lr-color-text)`) styles a hovered segment that is
 neither checked nor disabled, independently of the four above — so recoloring the checked pill never
 bleeds onto hover. `--lr-segmented-hover-bg` (default `transparent`) and `--lr-segmented-hover-shadow`

package/llms/components/lr-table.md

@@ -9,7 +9,7 @@
 - **Release history** [CHANGELOG.md](../../CHANGELOG.md)
 - **Deprecations** none
 - **Optional peers** none
-- **Themeable via** 47 parts, 27 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 56 parts, 27 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`
 
 ---
@@ -78,7 +78,7 @@ cell: (row) => unknown }` — `cell` is required for every `editTrigger` except
   `scroll-mode="auto"`, adapts to actual overflow rather than a fixed token threshold, and can be
   reversed with `[part='reveal-columns-button']`; `sticky` pins headers/cells to the logical start
   or end while scrolling. Sticky columns stack in logical order using
-  `--lr-table-sticky-offset` rather than overlap. A sticky body cell's
+  `--lr-table-sticky-offset` rather than overlap. Open overlays in a sticky cell stay on top. A sticky body cell's
   background always matches its own row's effective fill — striped, selected, hovered, or pressed —
   rather than painting a flat opaque surface over that state; a sticky header cell is unaffected
   (headers are never striped/selected) and keeps its plain surface fill, see
@@ -275,15 +275,15 @@ cell: (row) => unknown }` — `cell` is required for every `editTrigger` except
 - `paginationMode: 'client'|'server' = 'client'` (attribute `pagination-mode`, reflected) — client
   mode slices rows and updates `page`; server mode leaves `page` controlled and bounds the supplied
   page to `pageSize`
-- `unknownTotal: boolean = false` (attribute `unknown-total`, reflected) — server pagination for a
-  caller with no total item count, only whether one more page exists (`hasNext`). Forwarded to the
-  nested `<lr-pagination>` as its own indeterminate mode (`total="-1"`): previous/next only, no
-  numbered page list, no item-range summary. Ignored outside `paginationMode: 'server'` — client
-  mode always knows the exact row count it slices. A dedicated boolean rather than reusing
-  `totalItems`'s own `-1` sentinel, which already means "derive from the currently matching rows"
-- `hasNext: boolean = true` (attribute `has-next`, reflected) — whether at least one more page
-  exists past the current one; consulted only alongside `unknownTotal` and forwarded verbatim to
-  the nested `<lr-pagination>`'s own `hasNext`
+- `unknownTotal: boolean = false` (attribute `unknown-total`, reflected) — server pagination with
+  no total, only `hasNext`: the pager's indeterminate mode (previous/next only). Ignored outside
+  `paginationMode: 'server'`
+- `hasNext: boolean = true` (attribute `has-next`, reflected) — whether another page exists;
+  read only with `unknownTotal`
+- `paginationWithSummary: boolean = false` (attribute `pagination-with-summary`, reflected) —
+  pager item-range summary at the inline start, controls at the inline end
+- `paginationFormat: 'standard'|'compact' = 'compact'` (attribute `pagination-format`) — pager
+  `format`; invalid values resolve to `compact`
 - Editable columns emit `lr-cell-edit` on commit and never mutate the supplied row object.
 - `groupBy?: (row: T) => string | number` (attribute: false) — inserts a non-focusable full-width
   group row wherever this key changes between consecutive rendered rows. Supply `rows` with each
@@ -519,7 +519,9 @@ affordance; the part has no live-region role in either appearance),
 and cells reuse the ordinary `row`/`cell`/`row-total-cell` parts, which is exactly what keeps them
 geometrically identical to real rows, so `skeleton` is the part to target for the placeholder's own
 look: `::part(skeleton) { --lr-skeleton-h: 2em; }`), and
-`pagination`, `cell-editor`, `group-row`, `group-cell`, and `resize-handle` (the focusable column
+`pagination` (the pager host; re-exported as `pagination-summary`,
+`pagination-controls`, `pagination-pages`, `pagination-page`, `pagination-page-current`,
+`pagination-page-field`, `pagination-page-input`, `pagination-page-count`, `pagination-button`), `cell-editor`, `group-row`, `group-cell`, and `resize-handle` (the focusable column
 separator, with a finite explicit ARIA maximum even when no CSS `maxWidth` was supplied). The built-in empty state is addressable rather than fixed: `empty` is the `<lr-empty>`
 host in all three empty states, and it re-exports that element's own inner parts as `empty-base`,
 `empty-icon`, `empty-heading`, `empty-description` and `empty-actions`. Note that the no-columns and

package/llms/components/lr-thread-list.md

@@ -290,9 +290,10 @@ lr-thread-list::part(row-item-label) {
 }
 ```
 
-Do **not** reach for `::part(row) { --lr-theme-space-s: … }` instead. That is a whole-subtree
-retheme: it shrinks everything nested inside the row, including the items of a `renderActions` menu,
-which pushes their touch targets below the accessible minimum. The `row-item-*` parts exist so row
+Do **not** reach for `::part(row) { --lr-theme-space-s: … }` instead. A part is not a theme scope,
+so the input does not re-derive the spacing of the components nested in the row; and a scope there
+would be a whole-subtree retheme that shrinks everything inside the row, including the items of a
+`renderActions` menu, below the accessible touch-target minimum. The `row-item-*` parts exist so row
 density can be tuned without that blast radius.
 
 **Sizing:** the internal list fills whatever height this component is given, with no consumer CSS —

package/llms/migration.md

@@ -84,6 +84,7 @@ review removed names before running the migrated application.
 | `DEPRECATED_MEMBER_REVIEW`, `DEPRECATED_CONTENT_REVIEW` | A deprecated member, tag or kind of slotted content without a mechanical replacement. |
 | `DEPRECATED_MODULE_REVIEW` | A deprecated module, stylesheet, named export, window event or root attribute. Its replacement needs a semantic review. |
 | `GLOBAL_REVIEW` | A moved package specifier, removed root export or removed localization key that cannot be rewritten safely. |
+| `THEME_SCOPE_CSS_INPUT_REVIEW`, `THEME_SCOPE_OUTPUT_REVIEW`, `THEME_SCOPE_DYNAMIC_INPUT_REVIEW`, `THEME_SCOPE_REPEATED_REVIEW`, `THEME_SCOPE_DOUBLE_LAYER_REVIEW` | The `theme-scopes` rule found an input, shared output or marker that needs a theme scope by hand, or `tokens-root.css` imported next to `theme.css`, which already carries the layer. |
 | `MODULE_NAMESPACE_REVIEW` | A namespace, dynamic import or CommonJS module access whose exported bindings need review. |
 | `RENAME_CONFLICT_REVIEW` | The element already binds the new name, or the same receiver already listens to it with the same handler. |
 | `UNUSED_ACKNOWLEDGEMENT` | An acknowledgement comment matches no report. |
@@ -820,6 +821,7 @@ review removed names before running the migrated application.
 | `DEPRECATED_MEMBER_REVIEW`, `DEPRECATED_CONTENT_REVIEW` | A deprecated member, tag or kind of slotted content without a mechanical replacement. |
 | `DEPRECATED_MODULE_REVIEW` | A deprecated module, stylesheet, named export, window event or root attribute. Its replacement needs a semantic review. |
 | `GLOBAL_REVIEW` | A moved package specifier, removed root export or removed localization key that cannot be rewritten safely. |
+| `THEME_SCOPE_CSS_INPUT_REVIEW`, `THEME_SCOPE_OUTPUT_REVIEW`, `THEME_SCOPE_DYNAMIC_INPUT_REVIEW`, `THEME_SCOPE_REPEATED_REVIEW`, `THEME_SCOPE_DOUBLE_LAYER_REVIEW` | The `theme-scopes` rule found an input, shared output or marker that needs a theme scope by hand, or `tokens-root.css` imported next to `theme.css`, which already carries the layer. |
 | `MODULE_NAMESPACE_REVIEW` | A namespace, dynamic import or CommonJS module access whose exported bindings need review. |
 | `RENAME_CONFLICT_REVIEW` | The element already binds the new name, or the same receiver already listens to it with the same handler. |
 | `UNUSED_ACKNOWLEDGEMENT` | An acknowledgement comment matches no report. |
@@ -1541,6 +1543,7 @@ the old name keeps working meanwhile.
 | `DEPRECATED_MEMBER_REVIEW`, `DEPRECATED_CONTENT_REVIEW` | A deprecated member, tag or kind of slotted content without a mechanical replacement. |
 | `DEPRECATED_MODULE_REVIEW` | A deprecated module, stylesheet, named export, window event or root attribute. Its replacement needs a semantic review. |
 | `GLOBAL_REVIEW` | A moved package specifier, removed root export or removed localization key that cannot be rewritten safely. |
+| `THEME_SCOPE_CSS_INPUT_REVIEW`, `THEME_SCOPE_OUTPUT_REVIEW`, `THEME_SCOPE_DYNAMIC_INPUT_REVIEW`, `THEME_SCOPE_REPEATED_REVIEW`, `THEME_SCOPE_DOUBLE_LAYER_REVIEW` | The `theme-scopes` rule found an input, shared output or marker that needs a theme scope by hand, or `tokens-root.css` imported next to `theme.css`, which already carries the layer. |
 | `MODULE_NAMESPACE_REVIEW` | A namespace, dynamic import or CommonJS module access whose exported bindings need review. |
 | `RENAME_CONFLICT_REVIEW` | The element already binds the new name, or the same receiver already listens to it with the same handler. |
 | `UNUSED_ACKNOWLEDGEMENT` | An acknowledgement comment matches no report. |
@@ -1621,6 +1624,7 @@ the old name keeps working meanwhile.
 | `DEPRECATED_MEMBER_REVIEW`, `DEPRECATED_CONTENT_REVIEW` | A deprecated member, tag or kind of slotted content without a mechanical replacement. |
 | `DEPRECATED_MODULE_REVIEW` | A deprecated module, stylesheet, named export, window event or root attribute. Its replacement needs a semantic review. |
 | `GLOBAL_REVIEW` | A moved package specifier, removed root export or removed localization key that cannot be rewritten safely. |
+| `THEME_SCOPE_CSS_INPUT_REVIEW`, `THEME_SCOPE_OUTPUT_REVIEW`, `THEME_SCOPE_DYNAMIC_INPUT_REVIEW`, `THEME_SCOPE_REPEATED_REVIEW`, `THEME_SCOPE_DOUBLE_LAYER_REVIEW` | The `theme-scopes` rule found an input, shared output or marker that needs a theme scope by hand, or `tokens-root.css` imported next to `theme.css`, which already carries the layer. |
 | `MODULE_NAMESPACE_REVIEW` | A namespace, dynamic import or CommonJS module access whose exported bindings need review. |
 | `RENAME_CONFLICT_REVIEW` | The element already binds the new name, or the same receiver already listens to it with the same handler. |
 | `UNUSED_ACKNOWLEDGEMENT` | An acknowledgement comment matches no report. |
@@ -1676,6 +1680,11 @@ working; other uses (a deep import, a namespace member) and removed localization
 | part | `<lr-eval-dataset> ::part(search-clear)` | Style the clear button through part search-clear on the field, and the native input through search-input-field. | Reported only. search-clear is now the composed lr-input clear button. |
 | part | `<lr-eval-dataset> ::part(search-input)` | Style the native input through search-input-field. | Reported only. search-input is now the lr-input host, not the native input. |
 
+This profile also runs the structural rule `theme-scopes`, the same implementation as `--rule=<name>`.
+It adds `data-lr-theme-scope` to elements whose inline style sets a token-layer input, and reports dynamic inputs,
+markers inside loops, and stylesheet rules that set an input or a shared output outside a theme scope
+(`THEME_SCOPE_*_REVIEW`, acknowledged like any other code).
+
 ## Upstream-protected compatibility spellings
 
 These 8 legacy spellings remain supported while their corresponding Web Awesome or Shoelace surface publishes them. Prefer the current Lyra spelling for new code. Their recorded `removalNotBefore` value is a minimum, not an automatic removal date or permission to remove a still-mirrored spelling.

package/llms/peers.md

@@ -38,7 +38,7 @@ for the page.
 | Peer | Range | Needed by |
 |---|---|---|
 | `@aceshooting/lyra-flags` | `^2.3.0` | _(loaded by a shared internal module)_ |
-| `@aceshooting/lyra-translations` | `^27.0.0` | _(not referenced by any component)_ |
+| `@aceshooting/lyra-translations` | `^28.0.0` | _(not referenced by any component)_ |
 | `@aiden0z/pptx-renderer` | `^1.3.0` | `lr-pptx-viewer` |
 | `@sgratzl/chartjs-chart-boxplot` | `^4.0.0` | `lr-box-plot` |
 | `chart.js` | `^4.0.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/events-and-types.md

@@ -842,6 +842,16 @@ These named interfaces and helper signatures are available to typed integrations
   `resolveCanvasColor(/* public names: scope, color, fallback */): unknown`
   `resolveCanvasColors(/* public names: scope, colors, fallback */): unknown`
 
+- **`internal-document-tokens-contracts`** — Shared utility contracts.
+  `adoptLyraTokens(root: Document | ShadowRoot): void`
+  Adopts the document token layer into a document or shadow root. Idempotent; see "Application
+  shadow roots" in the styles and tokens guide for when a root needs it.
+
+- **`internal-theme-scopes-contracts`** — Shared utility contracts.
+  `findUnscopedThemeInputs(root?: Document | DocumentFragment | Element): Element[]`
+  Lists elements that set an inline `--lr-theme-*` input the layer consumes without being a theme
+  scope. Reads inline styles only and logs nothing.
+
 - **`internal-localization-runtime-contracts`** — Shared utility contracts.
   `getLyraLocaleDirection(/* public names: locale */): unknown`
   `getLyraLocale(): unknown`
@@ -1577,15 +1587,45 @@ These named interfaces and helper signatures are available to typed integrations
 - **`testing-happy-dom-shims-contracts`** — Shared utility contracts.
   `installHappyDomFormAssociatedShims(): unknown`
   `installHappyDomShadowFocusShim(): unknown`
+  `flattenCascadeLayers(/* public names: css */): unknown`
   `installHappyDomAriaControlsShim(/* public names: proto */): unknown`
+  `installHappyDomCascadeLayerShim(/* public names: proto, misbehaves */): unknown`
   `installHappyDomShims(): unknown`
   `installStubInternalsForTest(/* public names: host */): unknown`
 
+- **`testing-jsdom-shims-contracts`** — Shared utility contracts.
+  `JsdomAdoptedStyleSheetsTargets {
+  documentPrototype?: object;
+  shadowRootPrototype?: object;
+  styleSheetPrototype?: object;
+  isJsdom?: () => boolean;
+}`
+  `installJsdomAdoptedStyleSheetsShim(targets?: JsdomAdoptedStyleSheetsTargets): () => void`
+  `JsdomFormAssociatedTargets {
+  internalsPrototype?: object;
+  elementPrototype?: object;
+  isJsdom?: () => boolean;
+}`
+  `installJsdomFormAssociatedShim(targets?: JsdomFormAssociatedTargets): () => void`
+  `installJsdomShims(): () => void`
+  See "jsdom: `installJsdomShims()`" above for the full contract.
+
 - **`testing-interaction-drivers-contracts`** — Shared utility contracts.
   `chooseOption(/* public names: owner, value */): unknown`
   `submitConfirmDecision(/* public names: owner, decision */): unknown`
   `toggleSwitch(/* public names: switchEl */): unknown`
   `activateStep(/* public names: stepper, target */): unknown`
+  `chooseSwatch(/* public names: picker, value */): unknown`
+  `chooseCurrency(/* public names: picker, code */): unknown`
+  `PopoverDriverOptions {
+  timeoutMs: unknown;
+}`
+  `ClosePopoverOptions {
+  via: unknown;
+  timeoutMs: unknown;
+}`
+  `openPopover(/* public names: popover, options */): unknown`
+  `closePopover(/* public names: popover, options */): unknown`
   See "Driving a component's real activation path: interaction drivers" above for the full contract.
 
 - **`testing-wait-for-mount-contracts`** — Shared utility contracts.
@@ -1682,6 +1722,7 @@ These named interfaces and helper signatures are available to typed integrations
   `parseLyraStyleRecord(value: unknown): Readonly<LyraStyle>`
   `resetLyraStyle(fields?: readonly LyraStyleField[]): Readonly<LyraStyle>`
   `setLyraStyle(choices: LyraStyleChoices): Readonly<LyraStyle>`
+  `startLyraStyle(): Readonly<LyraStyle>`
 
 - **`vue-contracts`** — Framework integration type contracts, including the multi-split
   `for` launcher id and `trigger` element reference.

package/llms/shared/frameworks-and-ssr.md

@@ -51,6 +51,22 @@ browser-bundle argument for excluding them does not apply to a server render. Us
   template; the component renders when its definition upgrades in the browser. Use this for initial
   renders that require light-DOM traversal, layout, canvas, observers, media, or other browser APIs.
 
+**Link the token layer in `<head>`.** Since 28.0.0 declarative shadow roots no longer carry the
+shared `--lr-*` layer (one server-rendered `lr-button` is about 34 KB smaller). `theme.css` carries
+it, so for a correct first paint before hydration link `theme.css` after the no-flash bootstrap (a
+page that does not use `theme.css` links `styles/tokens-root.css`, the layer alone, instead):
+
+```html
+<link rel="stylesheet" href="/node_modules/@aceshooting/lyra-ui/dist/theme.css" />
+```
+
+Hydration then skips the constructed copy. An application's **own** declarative shadow roots that
+contain theme scopes (for example a `.lr-dark` region or a `data-lr-theme-scope` wrapper) include the
+same `<link rel="stylesheet" href="…/tokens-root.css">` inside their template: document styles do not
+reach into a shadow root until hydration adopts the layer there. Without any link and without
+JavaScript, server-rendered components paint without resolved tokens, as a page without Lyra's styles
+always did.
+
 Server setup (the fallback must precede Lit's renderer):
 
 ```ts

package/llms/shared/imports-and-registration.md

@@ -185,11 +185,12 @@ The entry points, then:
 - **`lr-flag`** registers from the barrel, but resolving a flag by `country`/`language` (rather than
   a pre-resolved `src`) additionally needs
   `import '@aceshooting/lyra-ui/components/media/flag/flag-peer.js';` once.
-- **Other subpaths.** `@aceshooting/lyra-ui/theme.css` (ready-made light/dark theme),
+- **Other subpaths.** `@aceshooting/lyra-ui/theme.css` (ready-made light/dark theme, including the
+  document token layer),
   `@aceshooting/lyra-ui/looks/shadcn.css` (opt-in shadcn/ui look, imported after `theme.css` — see
   [The shadcn look](./styles-and-tokens.md#the-shadcn-look--looksshadcncss)),
-  `@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/tokens-root.css` (the document token layer alone, for pages that do not
+  use `theme.css`; link one of the two, not both),
   `@aceshooting/lyra-ui/native.css` (opt-in native-element styles inside `.lr-native`),
   `@aceshooting/lyra-ui/utilities.css` (opt-in light-DOM layout/text/typography utilities),
   `@aceshooting/lyra-ui/theme.js` (the zero-dependency style runtime),

package/llms/shared/native-styles-and-utilities.md

@@ -30,8 +30,8 @@ uses a substring class selector, so a class such as `app-lr-flex-preview` does n
 assets repeat `@layer lr-base, lr-theme, lr-theme-preset, lr-utilities, lr-overrides`; an ordinary unlayered
 application rule therefore beats them regardless of load order. A third opt-in asset,
 [`tokens-root.css`](./styles-and-tokens.md#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.
+style sheet in the same sense — it declares custom properties only: the document token layer that
+the first connected Lyra element would otherwise adopt, available before any component connects.
 
 ### Utility class inventory
 
@@ -113,7 +113,8 @@ keeps that surface's text colour. Heading tracking reads `--lr-heading-letter-sp
 | Muted | `lr-text-sm lr-text-quiet`      |
 
 For an exact 0.875rem muted/small size, use a class of your own with the token chain (resolved
-`--lr-*` tokens are undefined at document scope unless `tokens-root.css` is loaded):
+`--lr-*` tokens exist at document scope once a Lyra element has connected or `tokens-root.css` is
+loaded; the chain covers the moment before):
 
 ```css
 .app-muted {
@@ -303,3 +304,37 @@ contrast and forced colors retain opaque fills. Load `preferences.css` for expli
 contrast/motion choices. Nested chrome suppresses repeated blur; independently presented top-layer
 surfaces begin their own material root. Keep cards, data tables, charts, map layers and editing
 fields outside the automatic chrome class.
+
+#### Application fallback fills and cascade layers
+
+Lyra paints the `.lr-surface-chrome` fill from a rule inside its cascade layers
+(`lr-theme-preset.surface`). An **unlayered** application rule that sets `background` on the same
+element — a generic `dialog { background: … }`, a `.panel` class — beats every layered rule
+whatever its specificity, so the element keeps the application's opaque fill and the Glass
+treatment disappears without a warning. No `revert-layer` workaround is needed; put the
+application's fallback where it ranks below Lyra:
+
+```css
+/* 1. A low-priority application layer named before Lyra's. This order statement must be the first
+      the browser sees: put it at the top of the entry stylesheet, before the theme.css import. */
+@layer app-base, lr-base, lr-theme, lr-theme-preset, lr-utilities, lr-overrides;
+@import "@aceshooting/lyra-ui/theme.css";
+
+@layer app-base {
+  dialog,
+  .panel {
+    background: #fff; /* still paints when the Lyra stylesheets are absent */
+  }
+}
+
+/* 2. Or choose the chrome's base fill through its token; Glass mixes it at the surface opacity. */
+.panel.lr-surface-chrome {
+  --lr-surface-background: #fff;
+}
+```
+
+An application layer declared after Lyra's (or unnamed until after `theme.css` loads) ranks above
+the surface layer and disables Glass in the same way as an unlayered rule. Keep unlayered
+`background` rules off `.lr-surface-chrome` elements, or exclude them with
+`:not(.lr-surface-chrome)`. See [Cascade layers](styles-and-tokens.md#cascade-layers) for the full
+order.