@aceshooting/lyra-ui 25.2.0 → 25.3.1

package/dist/internal/package-metadata.d.ts

@@ -2,4 +2,4 @@
 * Generated from package.json by scripts/generate-package-metadata.mjs.
 * Run `pnpm package-metadata` after changing package identity or version.
 */
-export declare const LYRA_PACKAGE_NAME:'@aceshooting/lyra-ui';export declare const LYRA_PACKAGE_VERSION:'25.2.0';
+export declare const LYRA_PACKAGE_NAME:'@aceshooting/lyra-ui';export declare const LYRA_PACKAGE_VERSION:'25.3.1';

package/dist/internal/package-metadata.js

@@ -1 +1 @@
-const LYRA_PACKAGE_NAME="@aceshooting/lyra-ui",LYRA_PACKAGE_VERSION="25.2.0";export{LYRA_PACKAGE_NAME,LYRA_PACKAGE_VERSION};
+const LYRA_PACKAGE_NAME="@aceshooting/lyra-ui",LYRA_PACKAGE_VERSION="25.3.1";export{LYRA_PACKAGE_NAME,LYRA_PACKAGE_VERSION};

package/llms/components/lr-combobox.md

@@ -701,8 +701,10 @@ synchronous and fires no `input`/`change`/`lr-change` event.
 - `aria-required` reflects `required` immediately; `aria-invalid`, by contrast, only reflects
   **after the field has been touched** (first `blur`) — a `required` field with a validity error
   doesn't look invalid to assistive tech before that, by design (avoids flashing invalid styling on
-  first render). Blurring the input (Tab away) now also closes an open listbox, the same as a
-  native `<select>`'s popup, not just a click outside or Escape.
+  first render). Moving focus outside the combobox trigger (Tab away) closes an open listbox,
+  the same as a native `<select>`'s popup. Moving from the input to its clear button retains the
+  filter until the button activates; clearing returns focus to the input without changing whether
+  the listbox is open.
 - `dotColor`/`sub`/`group` are read from light-DOM `<lr-option>` children as before, but are also
   first-class fields on `ComboboxSourceRow` for the async `source` path — an async lookup can drive
   the same grouped/dot/sub-text rendering a static option list can.

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

@@ -99,7 +99,7 @@ readonly LyraLocaleEntry[]`, `LyraLocaleEntry { tag: string; label?: string; cou
 unset, selection commits synchronously without loading a catalog. Set it to `loadLyraLocale` from
 `@aceshooting/lyra-ui/locale-loader.js` to import the selected built-in catalog before committing.
 The loader accepts exact shipped canonical tags (equivalent casing/underscores normalize), shares
-concurrent requests, and permits retry after a failed import. `en` needs no import; an unshipped
+concurrent requests, and clears its promise cache after rejection. `en` needs no import; an unshipped
 regional tag rejects instead of claiming a translation. Importing the helper does not load a catalog
 or select the page locale. Supply an explicit `locales` list to offer catalogs before registration.
 
@@ -114,7 +114,11 @@ picker.localeLoader = loadLyraLocale;
 The unset callback preserves synchronous selection. A vetoed request never invokes the loader.
 While loading, the previous value stays committed and the trigger exposes `aria-busy`; a visible
 localized status and light-DOM announcement explain progress. Failure retains the value and offers
-Retry through a fresh request. An open listbox places above or below the full control and its
+Retry through a fresh callback invocation. Browsers may cache failed native module fetches, so
+Retry does not guarantee another network request. Retain the current locale and failure guidance;
+if a native import remains failed after connectivity returns, offer a user-initiated page reload
+after preserving unsaved work, or use an application-owned recoverable `localeLoader` transport.
+The picker never reloads automatically. An open listbox places above or below the full control and its
 failure guidance, including when `top-layer` is enabled, so it cannot cover Retry. Dismissing and
 reopening the listbox retains the failure guidance and the reachable retry action.
 New selection, host value/catalog/loader writes, reset, disablement,
@@ -218,6 +222,12 @@ A compact header can set `trigger-display="flag"` and
 Import `@aceshooting/lyra-ui/components/media/flag/flag-peer.js` to register the optional flag
 resolver. Menu labels stay visible; a per-entry `country` override also reaches the compact trigger.
 
+Option rows keep at least `--lr-size-3rem` (normally `3rem`, or 48px at a 16px root size),
+including `option-display="label"`, compact density, and a small flag trigger. Block padding is
+`--lr-space-s`; long native labels wrap and rows grow with the text. Larger medium/current control
+height tokens and the optional tag line can also grow rows beyond that floor. The listbox keeps
+its scrolling height limit; `size` controls the trigger rather than shrinking language choices.
+
 ```html
 <lr-locale-picker label="Language"></lr-locale-picker>
 <script type="module">

package/llms/components/lr-menu.md

@@ -265,6 +265,10 @@ has `aria-haspopup="menu"`, explicit `aria-expanded="true|false"`, the transient
 `submenu-open` state, and a logical-direction chevron. Its submenu is named from the parent's
 accessible label unless the submenu supplies its own `aria-label` or non-default `label`.
 
+Submenus prefer the inline end of their parent and flip to the other side when necessary. When
+neither side has enough space, they can open above or below the parent, keeping their labels
+readable within the viewport instead of shrinking to the remaining strip beside a wide menu.
+
 The into-branch and back-out arrow keys swap under RTL. Enter/Space and the into key open and focus
 the first child; the back-out key and Escape close only the innermost branch and return focus to its
 parent row. Pointer hover uses an intent delay, outside pointer dismissal closes the branch, and at

package/llms/components/lr-popover.md

@@ -127,6 +127,16 @@ If the import fails, leave the native disclosure visible and usable.
 - `anchor: Element | null = null` (property only) — positioning-only direct anchor, taking priority
   over `for` and the interaction owner but never receiving click listeners or generated ARIA; a
   `showAt()` virtual anchor still wins
+- `interactionBoundary: Element | null = null` (property only) — additional light-dismiss
+  containment for DOM anchoring. Pointer presses within this connected element and its composed
+  descendants keep the popup open, so a collection's own activation handler can change `.anchor`
+  without a hide/show cycle. Automatic DOM anchor tracking remains active. The boundary must belong
+  to the popover's document; detached or foreign-document elements are ignored. It supplies no
+  positioning, activation, generated ARIA, or focus return. Changes apply live, and configuration
+  persists across close and reconnect. Containment uses the event's composed path; when the
+  collection lives inside a closed shadow tree, supply its exposed host. Unset, existing dismissal
+  behavior is unchanged. Virtual `showAt()` anchors use only their independent per-call
+  `options.interactionBoundary`.
 - `withoutArrow: boolean = false` (attribute `without-arrow`, reflected) — suppresses the arrow
   that otherwise points at the anchor.
 - `arrowPlacement: 'anchor'|'start'|'end'|'center' = 'anchor'` (attribute `arrow-placement`) —

package/llms/components/lr-table.md

@@ -297,7 +297,8 @@ cell: (row) => unknown }` — `cell` is required for every `editTrigger` except
 - `groupLabel?: (key: string | number, rows: readonly T[]) => unknown` (attribute: false) — custom group
   header content; without it, the group key is rendered as text
 - `expandedContent?: (row: T) => unknown` (attribute: false) — enables a leading expand toggle and
-  renders a full-width detail row beneath expanded records. The returned content renders inside
+  renders a full-width detail row beneath expanded records. The visually empty toggle-column
+  header has the localized accessible name `details` (overridable through `.strings`). The returned content renders inside
   the component's shadow root, behind the `expanded-cell` part — page CSS cannot reach it, and
   `::part(expanded-cell)` only reaches the wrapping `<td>` itself, not the descendants this
   callback returns (the same `::part()` limitation a column's `cell(row)` anchors run into, see

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

@@ -274,7 +274,9 @@ registers nothing.
 - Optional-peer tags are skipped by default. `optionalPeers: ['dompurify', 'postal-mime']` enables
   a tag only when the allowlist contains **all** packages recorded for it; `optionalPeers: 'all'`
   is for an installation that deliberately provides the entire peer set. A failed import clears
-  its marker and in-flight cache, so a later scan or insertion can retry it.
+  its marker and in-flight cache, so a later scan or insertion can invoke the loader again.
+  Browser caching of failed native module fetches can still prevent a new network request;
+  clearing the loader cache does not clear the browser's module map.
 
 ```ts
 import { start, stop } from "@aceshooting/lyra-ui/autoloader.js";

package/llms/shared/localization-and-rtl.md

@@ -95,12 +95,17 @@ ships with Lyra. A delta's own registered-key list reports only its own authored
 
 **Optional lazy loading.** `loadLyraLocale(tag)` from `@aceshooting/lyra-ui/locale-loader.js`
 loads one complete built-in catalog without selecting the page locale. Tags that canonicalize to
-the same shipped catalog identity share one in-flight/completed import; failure permits retry. `en`
+the same shipped catalog identity share one in-flight/completed import. Rejection clears the
+helper's promise cache, but browsers may retain failed module fetches: another call need not make
+a new network request. `en`
 resolves without an import. A tag with no exact shipped identity, such as an unshipped regional
 variant, rejects instead of quietly loading another language. The optional loader is outside the
 default component and localization graphs. Assign it to `lr-locale-picker.localeLoader` with an
 explicit offered locale list to use the picker's loading, failure/retry and stale-selection
-protection; see the forms guide.
+protection; see the forms guide. Keep the current locale and failure guidance when loading fails.
+If a native import remains failed after connectivity returns, a user-initiated reload can recover;
+preserve unsaved work first. A custom `localeLoader` can use an application-owned recoverable
+transport. The helper neither reloads the page nor changes module URLs to bypass browser caching.
 
 **Lookup order for a tag.** Every message resolves through one chain, and `Intl.PluralRules`
 category selection walks the same chain, so the two can never disagree:

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

@@ -505,7 +505,8 @@ page you are on — that is what keeps two overlapping surfaces reading in the c
 
 ### Cascade layers
 
-`theme.css` declares its layer order up front, then puts all of its own tokens in `lr-theme`:
+`theme.css` declares its layer order up front, with base inputs in `lr-theme` and built-in profile
+rules in the `lr-theme-preset` sublayers:
 
 ```css
 @layer lr-base, lr-theme, lr-theme-preset, lr-utilities, lr-overrides;
@@ -513,9 +514,10 @@ page you are on — that is what keeps two overlapping surfaces reading in the c
 
 - **`lr-base`** — contains the explicitly scoped native-element rules only when the optional
   `native.css` asset is imported.
-- **`lr-theme`** — where every `--lr-theme-*` token `theme.css` ships is declared.
-- **`lr-theme-preset`** — the compatibility layer name that holds optional look stylesheets, such as
-  [`looks/shadcn.css`](#the-shadcn-look--looksshadcncss). Empty unless one is imported.
+- **`lr-theme`** — contains the base theme inputs and token resolvers.
+- **`lr-theme-preset`** — the compatibility layer name for look, density, surface, accent and mode
+  rules. `theme.css` already supplies the built-in Shadcn, Glass and Emerald profile here; optional
+  look stylesheets add their own rules to the same sublayers.
 - **`lr-utilities`** — contains exact `lr-*` classes only when the optional `utilities.css` asset is
   imported.
 - **`lr-overrides`** — named so an application can opt its own rules into a defined position
@@ -574,17 +576,25 @@ reason.
 
 ### The shadcn look — looks/shadcn.css
 
-Import the base resolver and the optional look stylesheet, then select the look on the scope that should receive it:
+`theme.css` already installs Shadcn as the built-in default and supports explicit
+`data-lr-look="shadcn"` scopes. Import it once; the separate Shadcn sheet is unnecessary for this
+profile:
 
 ~~~ts
 import "@aceshooting/lyra-ui/theme.css";
-import "@aceshooting/lyra-ui/looks/shadcn.css";
 import { setLyraStyle } from "@aceshooting/lyra-ui/theme.js";
 
 setLyraStyle({ look: "shadcn" });
 ~~~
 
-The stylesheet declares values only under data-lr-look="shadcn". It composes with the independent mode, surface, density, and accent axes. For a local region, set data-lr-look="shadcn" on that region or use applyLyraStyleScope(). A nested data-lr-mode="dark" still changes mode without changing the look.
+Shadcn composes with the independent mode, surface, density and accent axes. For a local region,
+set data-lr-look="shadcn" on that region or use applyLyraStyleScope(). A nested data-lr-mode="dark"
+still changes mode without changing the look.
+
+The separate `looks/shadcn.css` sheet remains compatible. Besides the same scoped look values, it
+adds legacy `.light` and `.dark` mode aliases inside a Shadcn scope. Import that sheet only when
+those aliases are needed; prefer `data-lr-mode`, `data-lr-theme` or `.lr-light`/`.lr-dark` for new
+code. Explicit Lyra mode selectors on the same element take precedence over the compatibility aliases.
 
 The look sets --lr-theme-* inputs, so no component API changes. Its rules use Lyra's named cascade layers: unlayered application rules still win, and runtime accent ramps still take precedence over look values for the roles they paint. Import order between theme.css and looks/shadcn.css does not change the layer order.
 
@@ -602,7 +612,9 @@ Override the look through an unlayered application rule or the lr-overrides laye
 }
 ~~~
 
-The former global themes/shadcn.css facade and its data-lr-theme-preset behavior have been removed. Use looks/shadcn.css and the data-lr-look axis for new styling.
+The former global themes/shadcn.css facade and its data-lr-theme-preset behavior have been removed.
+Use theme.css and the data-lr-look axis for new styling; looks/shadcn.css is needed only for the
+compatibility aliases above.
 
 ### Where an override actually reaches
 
@@ -829,10 +841,13 @@ The token grammar rejects CSS-wide keywords, control characters, unsafe punctuat
 
 **Saved styles and the no-flash bootstrap.** getLyraStyle() re-reads storage on each call, so a value written by another tab is visible. If storage is unavailable, the runtime reports its last applied style and continues applying changes without persistence. lyraThemeBootstrap is a self-contained IIFE string for a script in head before stylesheets; it restores the saved style before first paint. createLyraThemeBootstrap({ storageKey }) produces the same string for an application-owned key. Both runtime and bootstrap safely read v1 records using mode: "auto", surface, and tokens, translating them to the current style axes. Keep this reader when migrating old saved preferences; new writes use the current style record.
 
-The bootstrap string can be inlined with the application's CSP nonce or hash:
+Inline the bootstrap after an early UTF-8 declaration and before stylesheets, with the application's
+CSP nonce or hash. Keep the complete charset declaration within the HTML document's first 1024
+bytes; build plugins must not prepend the bootstrap ahead of it.
 
 ~~~html
 <head>
+  <meta charset="utf-8" />
   <script>
     /* server-inlines lyraThemeBootstrap here */
   </script>
@@ -840,9 +855,9 @@ The bootstrap string can be inlined with the application's CSP nonce or hash:
 </head>
 ~~~
 
-For a strict CSP that disallows inline scripts, the package also publishes theme-bootstrap.js, a classic script asset with identical bytes. Load it synchronously before stylesheets. Its optional data-lr-theme-storage-key and data-lr-theme-attributes attributes select an application-owned storage key or mode-attribute list; values are validated and fall back to defaults when invalid.
+For a strict CSP that disallows inline scripts, the package also publishes theme-bootstrap.js, a classic script asset with identical bytes. Load it synchronously after the charset declaration and before stylesheets. Its optional data-lr-theme-storage-key and data-lr-theme-attributes attributes select an application-owned storage key or mode-attribute list; values are validated and fall back to defaults when invalid.
 
-**Migrating the retired theme facade.** New code uses setLyraStyle() and getLyraStyle(). Map old auto mode to system, an old surface reference color to accentBackground, and an old token map to overrides; review custom CSS colors that share a gemstone name before choosing a named accent. Replace preset definitions with a LyraLook plus explicit style choices. Replace selectors for data-lr-theme-preset with the actual axis they need, such as data-lr-look="shadcn". Import looks/shadcn.css in place of the removed fixed themes/shadcn.css facade and select the look with setLyraStyle({ look: "shadcn" }) or a scoped data-lr-look attribute. Listen for lr-style-change and read event.detail.style and event.detail.changed; the old theme and preset events are no longer emitted. For the complete project-by-project sequence, see [Upgrading from v23 to v24](v23-to-v24-migration.md).
+**Migrating the retired theme facade.** New code uses setLyraStyle() and getLyraStyle(). Map old auto mode to system, an old surface reference color to accentBackground, and an old token map to overrides; review custom CSS colors that share a gemstone name before choosing a named accent. Replace preset definitions with a LyraLook plus explicit style choices. Replace selectors for data-lr-theme-preset with the actual axis they need, such as data-lr-look="shadcn". Import theme.css in place of the removed fixed themes/shadcn.css facade and select the look with setLyraStyle({ look: "shadcn" }) or a scoped data-lr-look attribute. Listen for lr-style-change and read event.detail.style and event.detail.changed; the old theme and preset events are no longer emitted. For the complete project-by-project sequence, see [Upgrading from v23 to v24](v23-to-v24-migration.md).
 
 Historical v1 stored records remain readable by the runtime and bootstrap. The removed JavaScript functions, preset subpaths, preset event, root marker, and fixed stylesheet are not available in the current API.
 
@@ -894,10 +909,8 @@ mode and accent; the axes compose independently.
 
 ```js
 import '@aceshooting/lyra-ui/theme.css';
-import '@aceshooting/lyra-ui/looks/shadcn.css';
 import '@aceshooting/lyra-ui/looks/material.css';
 import '@aceshooting/lyra-ui/density.css';
-import '@aceshooting/lyra-ui/surfaces/glass.css';
 import '@aceshooting/lyra-ui/accents.css';
 import { setLyraStyle, resetLyraStyle, applyLyraStyleScope } from '@aceshooting/lyra-ui/theme.js';
 
@@ -915,7 +928,8 @@ inherit), without persistence or global events; clearing preserves later author
 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.
+directly if needed. Shadcn and Lyra are included in `theme.css`; other stylesheet look ids need
+their optional 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

package/llms/shared.md

@@ -273,7 +273,9 @@ registers nothing.
 - Optional-peer tags are skipped by default. `optionalPeers: ['dompurify', 'postal-mime']` enables
   a tag only when the allowlist contains **all** packages recorded for it; `optionalPeers: 'all'`
   is for an installation that deliberately provides the entire peer set. A failed import clears
-  its marker and in-flight cache, so a later scan or insertion can retry it.
+  its marker and in-flight cache, so a later scan or insertion can invoke the loader again.
+  Browser caching of failed native module fetches can still prevent a new network request;
+  clearing the loader cache does not clear the browser's module map.
 
 ```ts
 import { start, stop } from "@aceshooting/lyra-ui/autoloader.js";
@@ -1313,7 +1315,8 @@ page you are on — that is what keeps two overlapping surfaces reading in the c
 
 ### Cascade layers
 
-`theme.css` declares its layer order up front, then puts all of its own tokens in `lr-theme`:
+`theme.css` declares its layer order up front, with base inputs in `lr-theme` and built-in profile
+rules in the `lr-theme-preset` sublayers:
 
 ```css
 @layer lr-base, lr-theme, lr-theme-preset, lr-utilities, lr-overrides;
@@ -1321,9 +1324,10 @@ page you are on — that is what keeps two overlapping surfaces reading in the c
 
 - **`lr-base`** — contains the explicitly scoped native-element rules only when the optional
   `native.css` asset is imported.
-- **`lr-theme`** — where every `--lr-theme-*` token `theme.css` ships is declared.
-- **`lr-theme-preset`** — the compatibility layer name that holds optional look stylesheets, such as
-  [`looks/shadcn.css`](#the-shadcn-look--looksshadcncss). Empty unless one is imported.
+- **`lr-theme`** — contains the base theme inputs and token resolvers.
+- **`lr-theme-preset`** — the compatibility layer name for look, density, surface, accent and mode
+  rules. `theme.css` already supplies the built-in Shadcn, Glass and Emerald profile here; optional
+  look stylesheets add their own rules to the same sublayers.
 - **`lr-utilities`** — contains exact `lr-*` classes only when the optional `utilities.css` asset is
   imported.
 - **`lr-overrides`** — named so an application can opt its own rules into a defined position
@@ -1382,17 +1386,25 @@ reason.
 
 ### The shadcn look — looks/shadcn.css
 
-Import the base resolver and the optional look stylesheet, then select the look on the scope that should receive it:
+`theme.css` already installs Shadcn as the built-in default and supports explicit
+`data-lr-look="shadcn"` scopes. Import it once; the separate Shadcn sheet is unnecessary for this
+profile:
 
 ~~~ts
 import "@aceshooting/lyra-ui/theme.css";
-import "@aceshooting/lyra-ui/looks/shadcn.css";
 import { setLyraStyle } from "@aceshooting/lyra-ui/theme.js";
 
 setLyraStyle({ look: "shadcn" });
 ~~~
 
-The stylesheet declares values only under data-lr-look="shadcn". It composes with the independent mode, surface, density, and accent axes. For a local region, set data-lr-look="shadcn" on that region or use applyLyraStyleScope(). A nested data-lr-mode="dark" still changes mode without changing the look.
+Shadcn composes with the independent mode, surface, density and accent axes. For a local region,
+set data-lr-look="shadcn" on that region or use applyLyraStyleScope(). A nested data-lr-mode="dark"
+still changes mode without changing the look.
+
+The separate `looks/shadcn.css` sheet remains compatible. Besides the same scoped look values, it
+adds legacy `.light` and `.dark` mode aliases inside a Shadcn scope. Import that sheet only when
+those aliases are needed; prefer `data-lr-mode`, `data-lr-theme` or `.lr-light`/`.lr-dark` for new
+code. Explicit Lyra mode selectors on the same element take precedence over the compatibility aliases.
 
 The look sets --lr-theme-* inputs, so no component API changes. Its rules use Lyra's named cascade layers: unlayered application rules still win, and runtime accent ramps still take precedence over look values for the roles they paint. Import order between theme.css and looks/shadcn.css does not change the layer order.
 
@@ -1410,7 +1422,9 @@ Override the look through an unlayered application rule or the lr-overrides laye
 }
 ~~~
 
-The former global themes/shadcn.css facade and its data-lr-theme-preset behavior have been removed. Use looks/shadcn.css and the data-lr-look axis for new styling.
+The former global themes/shadcn.css facade and its data-lr-theme-preset behavior have been removed.
+Use theme.css and the data-lr-look axis for new styling; looks/shadcn.css is needed only for the
+compatibility aliases above.
 
 ### Where an override actually reaches
 
@@ -1637,10 +1651,13 @@ The token grammar rejects CSS-wide keywords, control characters, unsafe punctuat
 
 **Saved styles and the no-flash bootstrap.** getLyraStyle() re-reads storage on each call, so a value written by another tab is visible. If storage is unavailable, the runtime reports its last applied style and continues applying changes without persistence. lyraThemeBootstrap is a self-contained IIFE string for a script in head before stylesheets; it restores the saved style before first paint. createLyraThemeBootstrap({ storageKey }) produces the same string for an application-owned key. Both runtime and bootstrap safely read v1 records using mode: "auto", surface, and tokens, translating them to the current style axes. Keep this reader when migrating old saved preferences; new writes use the current style record.
 
-The bootstrap string can be inlined with the application's CSP nonce or hash:
+Inline the bootstrap after an early UTF-8 declaration and before stylesheets, with the application's
+CSP nonce or hash. Keep the complete charset declaration within the HTML document's first 1024
+bytes; build plugins must not prepend the bootstrap ahead of it.
 
 ~~~html
 <head>
+  <meta charset="utf-8" />
   <script>
     /* server-inlines lyraThemeBootstrap here */
   </script>
@@ -1648,9 +1665,9 @@ The bootstrap string can be inlined with the application's CSP nonce or hash:
 </head>
 ~~~
 
-For a strict CSP that disallows inline scripts, the package also publishes theme-bootstrap.js, a classic script asset with identical bytes. Load it synchronously before stylesheets. Its optional data-lr-theme-storage-key and data-lr-theme-attributes attributes select an application-owned storage key or mode-attribute list; values are validated and fall back to defaults when invalid.
+For a strict CSP that disallows inline scripts, the package also publishes theme-bootstrap.js, a classic script asset with identical bytes. Load it synchronously after the charset declaration and before stylesheets. Its optional data-lr-theme-storage-key and data-lr-theme-attributes attributes select an application-owned storage key or mode-attribute list; values are validated and fall back to defaults when invalid.
 
-**Migrating the retired theme facade.** New code uses setLyraStyle() and getLyraStyle(). Map old auto mode to system, an old surface reference color to accentBackground, and an old token map to overrides; review custom CSS colors that share a gemstone name before choosing a named accent. Replace preset definitions with a LyraLook plus explicit style choices. Replace selectors for data-lr-theme-preset with the actual axis they need, such as data-lr-look="shadcn". Import looks/shadcn.css in place of the removed fixed themes/shadcn.css facade and select the look with setLyraStyle({ look: "shadcn" }) or a scoped data-lr-look attribute. Listen for lr-style-change and read event.detail.style and event.detail.changed; the old theme and preset events are no longer emitted. For the complete project-by-project sequence, see [Upgrading from v23 to v24](v23-to-v24-migration.md).
+**Migrating the retired theme facade.** New code uses setLyraStyle() and getLyraStyle(). Map old auto mode to system, an old surface reference color to accentBackground, and an old token map to overrides; review custom CSS colors that share a gemstone name before choosing a named accent. Replace preset definitions with a LyraLook plus explicit style choices. Replace selectors for data-lr-theme-preset with the actual axis they need, such as data-lr-look="shadcn". Import theme.css in place of the removed fixed themes/shadcn.css facade and select the look with setLyraStyle({ look: "shadcn" }) or a scoped data-lr-look attribute. Listen for lr-style-change and read event.detail.style and event.detail.changed; the old theme and preset events are no longer emitted. For the complete project-by-project sequence, see [Upgrading from v23 to v24](v23-to-v24-migration.md).
 
 Historical v1 stored records remain readable by the runtime and bootstrap. The removed JavaScript functions, preset subpaths, preset event, root marker, and fixed stylesheet are not available in the current API.
 
@@ -2146,12 +2163,17 @@ ships with Lyra. A delta's own registered-key list reports only its own authored
 
 **Optional lazy loading.** `loadLyraLocale(tag)` from `@aceshooting/lyra-ui/locale-loader.js`
 loads one complete built-in catalog without selecting the page locale. Tags that canonicalize to
-the same shipped catalog identity share one in-flight/completed import; failure permits retry. `en`
+the same shipped catalog identity share one in-flight/completed import. Rejection clears the
+helper's promise cache, but browsers may retain failed module fetches: another call need not make
+a new network request. `en`
 resolves without an import. A tag with no exact shipped identity, such as an unshipped regional
 variant, rejects instead of quietly loading another language. The optional loader is outside the
 default component and localization graphs. Assign it to `lr-locale-picker.localeLoader` with an
 explicit offered locale list to use the picker's loading, failure/retry and stale-selection
-protection; see the forms guide.
+protection; see the forms guide. Keep the current locale and failure guidance when loading fails.
+If a native import remains failed after connectivity returns, a user-initiated reload can recover;
+preserve unsaved work first. A custom `localeLoader` can use an application-owned recoverable
+transport. The helper neither reloads the page nor changes module URLs to bypass browser caching.
 
 **Lookup order for a tag.** Every message resolves through one chain, and `Intl.PluralRules`
 category selection walks the same chain, so the two can never disagree:
@@ -5537,10 +5559,8 @@ mode and accent; the axes compose independently.
 
 ```js
 import '@aceshooting/lyra-ui/theme.css';
-import '@aceshooting/lyra-ui/looks/shadcn.css';
 import '@aceshooting/lyra-ui/looks/material.css';
 import '@aceshooting/lyra-ui/density.css';
-import '@aceshooting/lyra-ui/surfaces/glass.css';
 import '@aceshooting/lyra-ui/accents.css';
 import { setLyraStyle, resetLyraStyle, applyLyraStyleScope } from '@aceshooting/lyra-ui/theme.js';
 
@@ -5558,7 +5578,8 @@ inherit), without persistence or global events; clearing preserves later author
 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.
+directly if needed. Shadcn and Lyra are included in `theme.css`; other stylesheet look ids need
+their optional 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

package/llms/tokens.md

@@ -12,10 +12,13 @@ Every `lr-*` component resolves its styling through this two-layer token system,
    with a built-in fallback. Other tokens are aliases, computed or environment-backed values,
    or fixed contract constants. Every component renders correctly with no theme configured.
 
-For a ready-made light/dark base, import `@aceshooting/lyra-ui/theme.css` once and put
-`class="lr-light"`/`class="lr-dark"` (or `data-lr-theme="light"`/`"dark"`) on an ancestor.
-For the shadcn/ui look, also import `@aceshooting/lyra-ui/looks/shadcn.css` and select
-`data-lr-look="shadcn"` on the root or a scoped ancestor; look and mode remain independent.
+Import `@aceshooting/lyra-ui/theme.css` once for the built-in Shadcn, Glass and Emerald profile.
+`theme.css` already includes Shadcn; no separate Shadcn look import is required.
+Select `data-lr-look="shadcn"` on a scoped ancestor when needed. Choose light/dark mode with
+`class="lr-light"`/`class="lr-dark"`, `data-lr-theme`, or the independent `data-lr-mode` axis.
+Other stylesheet looks, such as Material, require their optional `looks/<look>.css` sheet.
+The separate `looks/shadcn.css` sheet remains optional for its scoped `.light`/`.dark`
+compatibility aliases; look and mode remain independent.
 See [Styles and tokens](./shared/styles-and-tokens.md) for runtime and stylesheet options.
 Per-component `--lr-<component>-*` custom properties (listed in each component's own section)
 override a single element without touching the shared layer.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aceshooting/lyra-ui",
-  "version": "25.2.0",
+  "version": "25.3.1",
   "description": "Free, independent Lit web components: an open-source alternative to Shoelace and Web Awesome with accessible forms, dashboards, charts, and agent UI.",
   "keywords": [
     "web-components",
@@ -11832,7 +11832,7 @@
     "istanbul-lib-report": "^3.0.1",
     "istanbul-reports": "^3.2.0",
     "jszip": "^3.10.2",
-    "katex": "^0.18.9",
+    "katex": "^0.18.10",
     "libphonenumber-js": "^1.13.14",
     "mammoth": "^1.13.0",
     "maplibre-gl": "^6.11.2",
@@ -11843,10 +11843,10 @@
     "pixelmatch": "^7.2.0",
     "playwright": "^1.63.0",
     "pngjs": "^7.0.0",
-    "postal-mime": "^4.0.1",
+    "postal-mime": "^4.0.2",
     "qrcode": "^1.5.4",
     "react": "^19.3.0",
-    "shiki": "^4.4.3",
+    "shiki": "^4.5.0",
     "svelte": "^5.57.1",
     "typescript": "^7.0.2",
     "vue": "^3.5.43",