@aceshooting/lyra-ui 24.1.0 → 25.0.0

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

@@ -9,13 +9,17 @@
 - **Release history** [CHANGELOG.md](../../CHANGELOG.md); family-wide breaking-change summaries: [forms](https://github.com/aceshooting/lyra-ui/blob/main/packages/lyra-ui/llms/forms.md)
 - **Deprecations** none
 - **Optional peers** none
-- **Themeable via** 4 parts, 9 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 4 parts, 10 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`
 
 ---
 
 ## `lr-swatch-picker`
 
+Keyboard navigation and item-update focus restoration reveal the complete focused swatch
+inside scrolling containers, including single-row `nowrap` palettes. Public
+`focus({ preventScroll: true })` continues to suppress scrolling.
+
 A single-select picker over a small, fixed set of color swatches with the WAI-ARIA APG
 `radiogroup` contract built in: `role="radiogroup"`/`role="radio"`, roving tabindex, automatic
 activation (click or arrow-key move both select immediately, like a native radio group), cyclic
@@ -120,7 +124,8 @@ gemstone mode, same aliasing and scope as `--lr-swatch-picker-gemstone-selected-
 plus shared tokens — `--lr-color-border`/`-brand`, `--lr-space-xs`,
 `--lr-border-width-thin`/`-thick`, `--lr-radius`, `--lr-transition-fast`, `--lr-focus-ring-*`,
 and the per-tier `--lr-size-*` tokens. The automatic gemstone glyph's own checked-state halo/shine
-is themed independently, through `--lr-gemstone-selected-color`/`-blur`/`-shine-duration` — see
+is themed independently, through `--lr-gemstone-selected-color`/`-blur`/`-shine-duration` and
+`--lr-gemstone-selected-animation` — see
 `theme/gemstones.js`'s `gemstoneSelectedGlyphStyles` below, the exact stylesheet this picker
 includes in its own `static styles` for that glyph.
 
@@ -200,7 +205,7 @@ class AccentTrigger extends LitElement {
 - the semantic `radiogroup` lives inside shadow DOM. Set `accessibleLabel` or a host `aria-label`;
   the component deliberately forwards the resulting name to that internal role.
 - the automatic gemstone glyph's checked-state halo/shine is themed through
-  `--lr-gemstone-selected-color`/`-blur`/`-shine-duration`, not through
+  `--lr-gemstone-selected-color`/`-blur`/`-shine-duration`/`-animation`, not through
   `--lr-swatch-picker-selected-*`/`-gemstone-*` — those style a plain color-fill swatch or a
   consumer-supplied `icon` override instead, even while `mode="gemstone"`.
 
@@ -246,7 +251,12 @@ import {
 `--lr-overlay-max-inline-size` lifts the popup's default 20rem cap so the 20rem palette plus the
 popover's own padding fits. Both `--lr-gemstone-selected-*` values reach the trigger glyph and the
 picker's checked glyph alike: a 0.42rem halo at 92% of the accent. Leave
-`--lr-gemstone-selected-shine-duration` unset to keep the default 1.8s shine. The
+`--lr-gemstone-selected-shine-duration` unset to keep the default 1.8s shine. For an independent
+**Shine OFF** choice, set `--lr-gemstone-selected-animation: none` on the common popover scope or
+another ancestor of both glyphs. This stops the animation while preserving the static halo,
+selected accent, and checked semantics. Remove the property to restore the default shine;
+do not use a zero duration or pause an infinite animation as an OFF setting. Persistence of
+this choice stays with the application, separately from its motion preference. The
 `--lr-icon-button-*` values keep the trigger free of a rectangular fill at rest, on hover, and
 while pressed:
 
@@ -337,7 +347,9 @@ The parts already supply the behavior, so do not re-implement it. The picker is
 `radiogroup` with `aria-checked` and a `:focus-visible` ring per swatch, and its Arrow keys swap
 under RTL. The popover keeps `bottom-end` on the logical end under RTL and returns focus to the
 trigger on Escape. `gemstoneSelectedGlyphStyles` stops the shine under
-`prefers-reduced-motion: reduce`. Verify 320px and desktop layouts, enlarged text, and both color
+`prefers-reduced-motion: reduce` and under application `motion: 'reduce'` with `preferences.css`
+loaded, even when the public animation hook explicitly requests a loop. Verify 320px and desktop
+layouts, enlarged text, and both color
 modes. In a sidebar or settings panel, the caption and row may appear inline with the same glow
 and spacing; use the compact tier when the container is narrow and allow wrapping if even that
 tier cannot fit. Never shrink targets below 24px. Application theme application, default accent,

package/llms/components/lr-table.md

@@ -338,6 +338,19 @@ cell: (row) => unknown }` — `cell` is required for every `editTrigger` except
   exists again (the same convention `selectedRowKeys` follows for server pagination). Reads return
   immutable detached `ReadonlySet` facades; reassign a new set to update
 - `hasMore: boolean = false` (attribute `has-more`, reflected)
+- `loadingMore: boolean = false` (attribute `loading-more`, reflected) — controlled busy state
+  for the built-in incremental action. With `hasMore`, keeps existing rows and the same focusable
+  `more-button` mounted, exposes `aria-busy="true"` and `aria-disabled="true"`, and suppresses
+  pointer and keyboard `lr-load-more` requests while pending. Set it synchronously in the event
+  handler before awaiting the next page, then clear it when the request settles. It does not fetch
+  or append data itself; reassign `rows` when results arrive. `hasMore` still controls the button's
+  presence, and `loading` retains its separate full-table loading behavior. Left unset, the
+  continuation markup and activation behavior are unchanged.
+- `loadingMoreLabel?: string` (attribute `loading-more-label`) — omission renders localized
+  `tableLoadingMore` (`'Loading more rows'` in the built-in English catalog); supplied strings,
+  including `''`, render verbatim. Post-mount transitions into incremental loading append this
+  copy to the shared light-DOM polite sink only when the continuation is rendered and initial
+  `loading` is false. Declarative initial busy state remains silent.
 - `moreLabel?: string` (attribute `more-label`) — omission renders localized `loadMore` (`'Load more'` in the built-in English catalog); a supplied string, including `''`, renders verbatim
 - `error: boolean = false` (attribute `error`, reflected) — replaces `<tbody>`'s row content with
   a built-in failed-load state while keeping the surrounding `<thead>`, filter field, and
@@ -449,7 +462,7 @@ any of the attributes — a consumer-supplied key is not safe to interpolate int
 `detail: { phase: 'request', sortKey, sortDir }`) precedes `lr-sort` (frozen readonly
 `detail: { phase: 'commit', sortKey, sortDir }`) only when accepted. Client mode also updates its
 sort properties; server mode leaves them controlled. Other events are `lr-row-activate`
-(a row was activated by pointer or Enter/Space, `detail: { row }`), `lr-load-more` (fired on the "load more" button),
+(a row was activated by pointer or Enter/Space, `detail: { row }`), `lr-load-more` (fired on the "load more" button only while `loadingMore` is false),
 `lr-priority-columns-visibility-change` (frozen readonly `detail: { visible }`), and the expansion
 pair `lr-row-expand-request` (**cancelable**, frozen readonly `detail: { row, rowKey, expanded }`,
 emitted only while `expansionMode` is `'single'` or `'multiple'`; `preventDefault()` skips the

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

@@ -16,6 +16,9 @@
 
 ## `lr-voice-picker`
 
+The voice list follows the [shared surface treatment](shared/styles-and-tokens.md);
+its editing field retains an opaque fill.
+
 A TTS voice selector over a host-supplied `catalog`, mirroring `lr-model-select`'s
 closed-dropdown/free-text-combobox dual mode, stale-value handling, and form-association verbatim
 (see that section for the full mode-switching contract this one shares), extended with a

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

@@ -261,3 +261,43 @@ and opacity tokens first. These additional hooks customize only the light-DOM bu
 | `--lr-native-legend-padding`              | `--lr-space-xs`; legend inline padding                                       |
 | `--lr-native-table-cell-padding`          | `--lr-space-s`; caption and table-cell padding                               |
 | `--lr-native-rule-space`                  | `--lr-space-l`; horizontal-rule block margin                                 |
+
+
+### Native navigation and floating chrome
+
+The opt-in `.lr-surface-chrome` class uses the same protected Glass material as Lyra navigation,
+menus and modal panels. It is shipped by `theme.css` for the built-in profile and by the separate
+`surfaces/glass.css` asset for applications composing their own stylesheet set:
+
+```css
+@import "@aceshooting/lyra-ui/theme.css";
+@import "@aceshooting/lyra-ui/tokens-root.css";
+```
+
+```html
+<nav class="lr-surface-chrome" aria-label="Primary navigation">…</nav>
+<section class="lr-surface-chrome" aria-labelledby="settings-title">
+  <h2 id="settings-title">Settings</h2>
+  <div class="settings-scrollport">…</div>
+</section>
+```
+
+Localize the example's names. Keep the material wrapper non-scrolling and put overflow on an inner
+scrollport. The decorative pseudo-element filters the backdrop without changing fixed descendant
+coordinates. The wrapper reserves `::before` and supplies a low-specificity `position: relative`;
+application fixed, sticky or absolute positioning still wins. Avoid an extra opaque wrapper inside
+an already treated Lyra popup.
+
+`--lr-surface-background` optionally supplies this native wrapper's base fill. It falls back to the
+local high container surface, then the overlay surface, and resolves on the painted wrapper, so nearer
+theme inputs work.
+The existing `--lr-theme-surface-opacity`, `--lr-theme-surface-blur`,
+`--lr-theme-surface-saturation` and `--lr-theme-surface-highlight` controls apply. Glass uses 70%
+opacity by default, 12px blur with a 16px ceiling, and qualified text, edges and focus.
+The public opacity input accepts 0–1; lower custom opacity may expose backdrops that need
+stronger foreground contrast. Solid and accessibility preferences still force opaque fills.
+Explicit `data-lr-surface="solid"`, unsupported backdrop filtering, reduced transparency, increased
+contrast and forced colors retain opaque fills. Load `preferences.css` for explicit inherited
+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.

package/llms/shared/styles-and-tokens.md

@@ -73,6 +73,193 @@ See [Where an override actually reaches](#where-an-override-actually-reaches) be
 inheritance rules, including the one documented exception (per-component `--lr-<component>-*`
 hooks, layer 3, which do inherit through wrappers).
 
+### Lyra signature starter
+
+Lyra's built-in profile is Shadcn, Glass, Emerald, System mode and comfortable density. Plain
+component imports receive these defaults and a host-level Solid opt-out; `theme.css` provides the
+full look/accent/mode resolver and the same profile for document scopes, including native chrome.
+Explicit saved choices remain independent and win over missing or invalid fields. Use the existing style API to opt into Solid, the Lyra look, another accent or
+mode; `accent: null` explicitly clears the accent, while `resetLyraStyle()` restores Emerald.
+
+```css
+@layer lr-base, lr-theme, lr-theme-preset, lr-utilities, lr-overrides;
+@layer lr-theme-preset.look, lr-theme-preset.density, lr-theme-preset.surface, lr-theme-preset.accent, lr-theme-preset.mode;
+@import "@aceshooting/lyra-ui/theme.css";
+@import "@aceshooting/lyra-ui/tokens-root.css";
+```
+
+Keep both layer-order statements before these imports. Bundlers can hoist statements from imported
+stylesheets; the declarations preserve the order when imports are flattened. See
+[Cascade layers](#cascade-layers). Separate Shadcn, Glass and Emerald imports remain compatible,
+but are unnecessary for this profile. Import other optional looks, accents and densities when
+exposing those choices.
+
+For first paint, run the synchronous `lyraThemeBootstrap` before blocking stylesheets, using the
+[CSP-safe embedding or classic-script asset](#style-runtime--aceshootinglyra-uithemejs). It restores
+valid saved axes and fills missing or invalid choices with the built-in profile. Keep the
+application's legacy-key precedence in an application adapter, and retain saved Solid, Lyra,
+custom accents, runtime looks, overrides and historical records. Do not reconstruct a saved record
+from the normalized `parseLyraStyleRecord()` snapshot: it is not a lossless persistence format.
+`getLyraStyle()` reads the same choices at runtime; user changes use `setLyraStyle()`. An application
+Reset can call `resetLyraStyle()` and restore any separate application preferences. Selectable
+alternate looks and an explicitly cleared accent require `theme.css`; the intrinsic component
+profile does not replace that scope resolver.
+
+Keep spotlights in application CSS, independent of the chosen control look. The public root-token
+stylesheet makes this static recipe follow both light/dark mode and the current accent:
+
+```css
+body { isolation: isolate; min-block-size: 100svh; background: var(--lr-color-surface); }
+body::before {
+  content: '';
+  position: fixed;
+  inset: 0;
+  z-index: -1;
+  pointer-events: none;
+  background:
+    radial-gradient(ellipse 46rem 30rem at 8% 4%, color-mix(in srgb, var(--lr-color-brand) 16%, transparent), transparent 60%),
+    radial-gradient(ellipse 40rem 30rem at 96% 22%, color-mix(in srgb, var(--lr-color-brand) 12%, transparent), transparent 58%),
+    radial-gradient(ellipse 44rem 32rem at 78% 96%, color-mix(in srgb, var(--lr-color-brand) 9%, transparent), transparent 60%),
+    var(--lr-color-surface);
+}
+html[data-lr-contrast='more'] body::before { background: var(--lr-color-surface); }
+@media (forced-colors: active) { body::before { background: Canvas; } }
+```
+
+Keep an existing application's multicolor spotlight palette when adopting a control look. For
+example, an accent/violet/pink canvas should retain all three gradient colors across Lyra, Shadcn,
+and Material; changing `look` must not replace those colors with the same-accent starter above.
+Keep application background rules outside look selectors, while letting mode and accent update
+their own inputs.
+
+These are decorative application backgrounds, not an `accentBackground` value: that style field
+accepts absolute colors used as contrast reference surfaces, not gradients or image URLs. Use
+semantic surface/text pairings for content and keep the decorative layer behind it.
+
+Use the existing [gemstoneAccentPicker composition](../components/lr-swatch-picker.md#gemstoneaccentpicker--the-signature-accent-selector),
+with its localized caption, nine canonical gemstones, and shared selected-glyph treatment. Keep
+`--lr-swatch-picker-wrap: nowrap`: desktop hit size `1.75rem` and gap `.25rem`; at widths up to
+`30rem`, hit size `1.5rem` and gap `.125rem` (28/4px and 24/2px at a 16px root). Leave its fill size
+unset. Bound the palette to the viewport and provide horizontal overflow for unusually narrow
+allocations or enlarged text; keyboard focus must bring every swatch into view. Do not shrink
+below the component's 24px floor or replace its Arrow/Home/End and RTL behavior. For an independent
+Shine preference, set `--lr-gemstone-selected-animation: none` on the scope shared by the trigger
+and picker; remove that declaration for Shine ON. OFF preserves the halo and selected accent.
+Application and OS reduced motion still take precedence; persist Shine independently from motion.
+See the composition guide for the controlled picker and preference wiring.
+
+The four separate topbar controls—gemstone, mode, design, language—stay square `2.75rem` targets
+(44px at a 16px root), with localized names and tooltips. Use gemstone, sun/moon and horizontal-slider
+icons, and a country flag for language. Dense gemstone options do not reduce
+those launcher targets. Size icon launchers directly and keep their slotted glyphs bounded:
+
+```css
+.appearance-launcher { --lr-icon-button-size: 2.75rem; }
+.appearance-launcher::part(button) { inline-size: 2.75rem; block-size: 2.75rem; }
+.appearance-launcher > svg,
+.appearance-launcher > lr-icon { inline-size: 1.125rem; block-size: 1.125rem; }
+```
+
+Apply `appearance-launcher` to each `lr-icon-button`, including buttons slotted through a popover.
+Keep the mode action separate from the design fields. Set the locale picker's
+`--lr-locale-picker-trigger-height: 2.75rem` and
+use its public flag-only trigger with readable menu entries:
+
+```ts
+import '@aceshooting/lyra-ui/components/lr-locale-picker.js';
+import '@aceshooting/lyra-ui/components/media/flag/flag-peer.js';
+```
+
+```html
+<lr-locale-picker top-layer trigger-display="flag" option-display="label"
+  aria-label="Localized language action"></lr-locale-picker>
+```
+
+Install the optional `@aceshooting/lyra-flags` peer; the granular resolver import loads requested
+flags without a bulk flag import. Leave `withoutFlags` false. Assign `locales` as a property with
+`{ tag, label, country? }` entries: provide readable localized language names and an explicit ISO
+country for regional entries when known, such as `en-US` → `US`. Keep flags as supplementary cues,
+never the only accessible names, and preserve a valid saved locale in the controlled `value`.
+Use the component's flag resolver rather than emoji, invented flag SVGs, or guessed display APIs.
+Verify 320px and desktop, light/dark, RTL, enlarged text, keyboard focus, and saved preferences.
+
+#### Two-column design panel
+
+Compose a settings form inside `lr-popover`; use its dialog behavior rather than assigning menu or
+ARIA grid roles to form fields. Import the existing native utility stylesheet and granular controls:
+
+```css
+@import "@aceshooting/lyra-ui/utilities.css";
+
+.design-popover { --lr-overlay-max-inline-size: min(29rem, calc(100dvw - 1rem)); }
+.design-popover::part(content) { padding: 0; }
+.design-panel {
+  box-sizing: border-box;
+  inline-size: 29rem;
+  max-inline-size: calc(100dvw - 1rem);
+  padding: var(--lr-space-l);
+  max-block-size: min(75dvh, 40rem);
+  overflow: auto;
+  overflow-wrap: anywhere;
+}
+.design-fields { --lr-grid-min-inline-size: 12rem; }
+.design-fields > * { min-inline-size: 0; max-inline-size: 100%; }
+.design-reset { inline-size: 100%; margin-block-start: var(--lr-space-l); }
+```
+
+```ts
+import '@aceshooting/lyra-ui/components/lr-popover.js';
+import '@aceshooting/lyra-ui/components/lr-icon-button.js';
+import '@aceshooting/lyra-ui/components/lr-select.js';
+import '@aceshooting/lyra-ui/components/lr-option.js';
+import '@aceshooting/lyra-ui/components/lr-button.js';
+```
+
+```html
+<lr-popover class="design-popover" top-layer placement="bottom-end" aria-label="Design settings">
+  <lr-icon-button slot="trigger" class="appearance-launcher" label="Design settings">
+    <!-- Application's decorative horizontal-slider glyph -->
+  </lr-icon-button>
+  <section class="design-panel">
+    <div class="design-fields lr-grid-auto lr-gap-s">
+      <lr-select label="Look" value="shadcn">
+        <lr-option value="shadcn">Shadcn</lr-option>
+        <lr-option value="lyra">Lyra</lr-option>
+        <lr-option value="material">Material</lr-option>
+      </lr-select>
+      <lr-select label="Surface" value="glass">
+        <lr-option value="glass">Glass</lr-option>
+        <lr-option value="solid">Solid</lr-option>
+      </lr-select>
+      <lr-select label="Density" value="comfortable">
+        <lr-option value="compact">Compact</lr-option>
+        <lr-option value="comfortable">Comfortable</lr-option>
+        <lr-option value="touch">Touch</lr-option>
+      </lr-select>
+      <!-- Further independent settings in their reading order -->
+    </div>
+    <lr-button class="design-reset" type="button">Reset appearance</lr-button>
+  </section>
+</lr-popover>
+```
+
+Localize the example's labels and options, bind values to the current application state, and handle
+each select's `lr-change` through the relevant public style or preference API. Reset restores the
+application profile and any separate application preferences.
+
+`lr-grid-auto` already uses `auto-fit` with a `min(100%, minimum)` track floor. A bounded `29rem`
+panel and `12rem` minimum give two columns when both fit, then one in narrow allocations; a third
+column would need at least `36rem` before gaps. Keep those bounds together when customizing the
+recipe. The existing `lr-gap-s` supplies the gap; no extra grid component or layout controller is
+needed. The minimum is measured in rem, so enlarged text can also reduce the column count.
+
+Keep every field in one row-major source list. Default grid placement and native Tab order then
+agree: first row, second row, and so on; inherited RTL starts each row on the right. Do not split
+fields into separate column wrappers, reorder with CSS, or add positive tabindex values. Leave the
+full-width Reset action outside the field grid. Verify two columns at desktop allocation, one at
+320px and enlarged text, long translated labels, RTL reading order, and Escape/focus return to the
+design launcher. Keep these layout rules shared across application headers and administrative views.
+
 ### Reading the resolved tokens from your own components — `tokens-root.css`
 
 The paragraph above is a real problem for any application that has custom elements of its own: they
@@ -628,7 +815,7 @@ resetLyraStyle(["look"]); // reset only the look axis
 setLyraStyle({ mode: "unset", accent: null, accentBackground: null, overrides: null });
 ~~~
 
-setLyraStyle() accepts independent choices for look, surface, density, mode, accent, accentBackground, and overrides. Omitted axes keep their current selection; null resets an axis. The returned LyraStyle snapshot includes the selected values, a resolved mode when the choice is system, and lookForm to distinguish a stylesheet look from a runtime look.
+setLyraStyle() accepts independent choices for look, surface, density, mode, accent, accentBackground, and overrides. Omitted axes keep their current selection. Null restores the built-in value for look, surface, density and mode; `accent: null` explicitly clears the accent, and null clears accentBackground or overrides. `resetLyraStyle()` restores Shadcn/Glass/Emerald/System/comfortable; a field list resets only those fields. The returned LyraStyle snapshot includes the selected values, a resolved mode when the choice is system, and lookForm to distinguish a stylesheet look from a runtime look.
 
 mode is light, dark, system, or unset. Explicit modes set both data-lr-theme and data-theme; system follows the operating system and updates both attributes when it changes; unset removes Lyra's mode attributes. The lr-style-change event carries { style, changed }, where changed lists the affected fields. Applications can listen to this one event for document style changes.
 
@@ -702,10 +889,8 @@ The complete native CSS and utility contract is in the [native styles guide](./n
 
 ### Composing looks, surfaces and density
 
-The independent style API is exported from `@aceshooting/lyra-ui/theme.js`.
-A scope selects one look, one surface, one density, one mode and one accent. These choices compose:
-shadcn with glass and compact density is valid. Selecting another look replaces that scope's look;
-it does not stack two competing look definitions.
+`@aceshooting/lyra-ui/theme.js` exports the API. Each scope selects one look, surface, density,
+mode and accent; the axes compose independently.
 
 ```js
 import '@aceshooting/lyra-ui/theme.css';
@@ -717,60 +902,48 @@ import '@aceshooting/lyra-ui/accents.css';
 import { setLyraStyle, resetLyraStyle, applyLyraStyleScope } from '@aceshooting/lyra-ui/theme.js';
 
 setLyraStyle({ look: 'shadcn', mode: 'system', accent: 'sapphire' });
-setLyraStyle({ surface: 'glass' }); // keeps the other choices
-applyLyraStyleScope(tableRegion, { density: 'compact' }); // other axes inherit
+setLyraStyle({ surface: 'glass' }); // keeps others
+applyLyraStyleScope(tableRegion, { density: 'compact' }); // others inherit
 applyLyraStyleScope(previewRegion, { look: 'material', mode: 'dark' });
-resetLyraStyle(['look']); // restores the Lyra look, retaining the other fields
-applyLyraStyleScope(tableRegion, null); // restores the element's previous authored values
+resetLyraStyle(['look']); // resets look only
+applyLyraStyleScope(tableRegion, null); // restores authored values
 ```
 
-`setLyraStyle()` merges omitted fields and persists the whole-page selection. `null` resets a field.
-`applyLyraStyleScope()` replaces the element's complete selection: omitted fields inherit. It neither
-persists nor dispatches global events. Author changes made after the helper's last write are preserved
-when the scope is cleared. `getLyraStyle()` reports requested axes and the resolved mode.
-
-Each attribute can also be authored directly: `data-lr-look`, `data-lr-surface`, `data-lr-density`,
-`data-lr-mode` and `data-lr-accent`. A stylesheet look id requires its stylesheet; setting an arbitrary
-id does not load or register a look. Use `defineLyraLook({ id, tokens })` for a validated, immutable
-runtime definition, then pass it as `look`. `lyraLookCss()` from `theme/look-css.js` produces the
-stylesheet form without accessing the DOM. Install `theme.css` and the selected optional sheets in
-an application-owned shadow root that contains its own style boundaries; document selectors do not
-cross shadow roots. Inherited values do cross them.
-
-For design-tool interchange, `@aceshooting/lyra-ui/design-tokens.json` includes
-`$extensions['com.aceshooting.lyra.looks']` with `schemaVersion: 1`, `base: 'lyra'`, and a
-`definitions` map for the shipped looks, including `lyra`, `material`, `shadcn`, `data`, `terminal`
-and `high-contrast`. Each entry is a portable `{ id, tokens }`
-definition accepted by `defineLyraLook()`. Sparse and null branches remain sparse; omitted values
-come from the canonical base token tree, and the empty Lyra definition restores that base. Load the
-artifact explicitly only in tooling or flows that need it; ordinary components do not import it.
-
-### Documentation theme builder
-
-The optional [theme builder](https://www.lyra-ui.com/docs/?path=/story/theming-theme-builder--editor)
-composes existing style APIs and portable token maps. It previews both modes, supports individual
-and complete resets, and edits contrast/motion preferences, local-font pairing, shape, elevation
-and categorical/sequential/diverging palettes. The editor is documentation code, not a package
-entry point or a new custom element; importing components never imports the builder.
-
-Import/export uses the existing `LyraLook`, `LyraThemeTokens`, version-2 saved style record and
-`LyraPreferences` formats. Preferences remain separate from the saved style record. Runtime look
-tokens are retained explicitly; `getLyraStyle()` snapshots alone do not contain those tokens.
-Imports validate atomically, are bounded to 256 KiB, and reject network-bearing or executable CSS.
-Errors leave the last valid preview intact. A group reset removes that group's writes; resetting
-one token to its look value removes it from every override group.
-
-Exported look CSS comes from `lyraLookCss()` and requires `theme.css`, the selected optional sheets
-and axis attributes. It is not an export of every axis or preference. Use the complete runtime
-recipe for custom accent derivation, or the separate style/preference files to retain those choices.
-Server-rendered attributes use `lyraStyleAttributes()` and `lyraPreferenceAttributes()`; system mode
-is not falsely resolved on the server. Install the required CSS in each application-owned shadow
-root that contains a local style boundary.
-
-Diagnostics describe measured specimen colors and states, not universal accessibility
-certification. Unknown/dynamic backgrounds remain unmeasured. Chart series keep text and non-color
-cues; color-vision simulation does not replace them. Font availability, physical blur and native
-platform accessibility settings still require evidence on the relevant platform.
+`setLyraStyle()` persists supplied fields and retains omitted ones; null resets profile axes, while
+`accent: null` clears it. `applyLyraStyleScope()` replaces an element's selection (omitted fields
+inherit), without persistence or global events; clearing preserves later author changes. `getLyraStyle()`
+reports requested axes and resolved mode.
+
+Set `data-lr-look`, `data-lr-surface`, `data-lr-density`, `data-lr-mode` and `data-lr-accent`
+directly if needed. Stylesheet look ids need their sheet; arbitrary ids neither load nor register.
+`defineLyraLook({ id, tokens })` defines a validated immutable runtime look;
+`lyraLookCss()` from `theme/look-css.js` creates CSS without DOM access. In app-owned shadow roots
+with local boundaries, install `theme.css` and selected sheets; selectors stop at roots, inheritance
+crosses.
+
+`@aceshooting/lyra-ui/design-tokens.json` exports `$extensions['com.aceshooting.lyra.looks']`
+(schemaVersion 1, base `lyra`), definitions `lyra`, `material`, `shadcn`, `data`, `terminal`,
+`high-contrast`, and `defaultStyle`: Shadcn/Glass/Emerald/System/comfortable. The original token tree remains
+authoritative; empty `lyra` restores it. Runtime CSS/editor/preview project the default separately.
+Portable `{ id, tokens }` works with `defineLyraLook()`; sparse/null branches stay sparse. Load its
+resolver to apply a look.
+
+The [theme builder](https://www.lyra-ui.com/docs/?path=/story/theming-theme-builder--editor) previews
+modes and edits contrast/motion, fonts, shape, elevation and chart palettes. It is documentation only,
+not an entry point or element; component imports do not load it.
+
+Import/export uses `LyraLook`, `LyraThemeTokens`, version-2 saved-style records and separate
+`LyraPreferences`. Preserve runtime look tokens; `getLyraStyle()` snapshots omit them. Imports are
+atomic (256 KiB max), reject network-bearing/executable CSS and preserve the last preview on error.
+Group reset removes its writes; resetting a token to its look value removes it from every group.
+
+`lyraLookCss()` exports only look CSS (requires `theme.css`, selected sheets and axis attributes).
+Use the runtime recipe for custom accent derivation or separate style/preference files. SSR helpers
+`lyraStyleAttributes()` and `lyraPreferenceAttributes()` leave system mode unresolved. Install CSS
+in every app-owned shadow root with a local boundary.
+
+Diagnostics measure specimens, not certify accessibility; dynamic backgrounds are unmeasured. Keep
+chart text/non-color cues. See [contrast guidance](#scoped-contrast-and-motion-preferences).
 
 ### Optional shape, typography and elevation presets
 
@@ -937,18 +1110,42 @@ lyraStyleAttributes() provide DOM-free server-rendering helpers; render the retu
 through the framework's normal HTML escaping.
 
 Glass is a treatment for eligible navigation and floating chrome. It does not make content panels,
-forms, charts or dialogs translucent. Unsupported blur, reduced transparency, increased contrast and
+editing controls, charts or base map layers translucent. Dialog and drawer panels, menus and
+control-owned listboxes share the chrome treatment; their input interiors stay opaque. Unsupported blur, reduced transparency, increased contrast and
 forced colors retain solid fills. Solid surfaces use `backdrop-filter: none`; forced colours paint
 `Canvas`. Offer a solid choice wherever the application offers glass, since reduced-transparency
 media-query support varies between browsers.
 
-Regular glass defaults to 90% opacity, with a 90% minimum and a 12px blur clamped to 16px.
+Regular glass defaults to 70% opacity with a 12px blur clamped to 16px.
+The public `--lr-theme-surface-opacity` input accepts 0 through 1. Lower opacity exposes more
+of the backdrop; the default foreground qualification covers 70%, while a custom lower setting
+cannot guarantee contrast against every backdrop. Solid and accessibility preferences retain
+opaque fills regardless of this input.
 Quiet text, necessary control edges, focus indicators and transparent actions gain a local
 contrast-qualified foreground; opaque accent fills retain their own on-colours. Supported chrome
 includes app rails, navigation menus, menubars, menus and their context-menu composition, popovers,
 selection toolbars, toast items and the owned playback-rate toolbar of `lr-av-player`. Nested glass
-chrome is opaque, preventing repeated blur. Content cards and modal dialogs remain solid.
-Scrolling rail, popover and selection-toolbar surfaces keep a stationary decorative blur layer;
+chrome is opaque, preventing repeated blur. Independently promoted menus and modal panels start a
+new material root. Content cards and editing fields remain opaque.
+A design panel can offer a Glass opacity range from 0–100%, shown when the selected surface is
+Glass. Start and reset it at 70%; convert the displayed percentage to the public token's 0–1 range.
+Apply this CSS input independently of look overrides: `setLyraStyle()` does not accept surface
+inputs in its `overrides` allowlist. Persist the percentage in the application's own settings and
+apply it before first paint, including after restoring those settings. Reset the app setting to 70
+and reapply it. Native `.lr-surface-chrome` wrappers and eligible component chrome consume the
+same input:
+
+```js
+function applyGlassOpacity(percent) {
+  if (!Number.isFinite(percent)) return;
+  const opacity = Math.min(100, Math.max(0, percent)) / 100;
+  document.documentElement.style.setProperty('--lr-theme-surface-opacity', String(opacity));
+}
+
+applyGlassOpacity(70); // Default and reset value; apply saved app settings before first paint.
+```
+
+Scrolling rail, popup, modal-panel and selection-toolbar surfaces keep a stationary decorative blur layer;
 the public surface continues to own scrolling, focus and author overflow hooks.
 
 `lr-av-player` additionally offers `controls-surface="clear"`, restricted to its owned toolbar and

package/llms/shared/testing-and-utilities.md

@@ -320,7 +320,10 @@ void`, and `virtualAnchorFromRect()`** — thin wrapper over `@floating-ui/dom`'
   `computePosition` + `autoUpdate`. Forces `strategy: 'fixed'` (matching the
   popup's own `position: fixed` CSS — otherwise it lands offset by the page scroll), middleware
   `offset(opts.offset ?? 4)`, `flip()`, `shift({ padding: 8 })`, default `placement: 'bottom-start'`.
-  Returns a cleanup function that stops the `autoUpdate` loop — call it in `disconnectedCallback()`.
+  Returns a cleanup function that stops observation and queued updates — call it in `disconnectedCallback()`.
+  For `place()`, element-resize notifications coalesce into the next animation frame; initial
+  computation, scrolling and layout-shift updates begin immediately. Cleanup cancels a pending
+  resize frame.
   `trackRect()` reports the target's initial viewport rect exactly once before returning, follows
   later layout/viewport changes, and returns the same cleanup shape.
   `virtualAnchorFromRect()` adapts a live rectangle provider to the exported `VirtualAnchor`