@aceshooting/lyra-ui 23.0.0 → 24.1.0

package/llms/shared.md

@@ -59,8 +59,8 @@ way, and moving to the replacement removes the warning. A test suite that fails
 while deliberately exercising a deprecated form can pre-seed Lit's development-mode
 `globalThis.litIssuedWarnings` set, before the element renders, with the key
 `lyra-deprecated:<owner>:<kind>:<name>` — `<kind>` and `<name>` as in the deprecation record.
-`<owner>` is the element name or package-relative module specifier; for example,
-`lyra-deprecated:./theme.js:function:setLyraTheme`.
+`<owner>` is the element name or package-relative module specifier. Theme migration guidance is in
+[styles and tokens](styles-and-tokens.md).
 
 ### Release history and upgrade notes
 
@@ -81,6 +81,13 @@ The major-version landmarks after 9.0.0 are:
   that themselves overrode the hook are affected. Collection snapshot enforcement moved to a
   decorator-agnostic accessor seam instead.
 
+- **24.0.0:** removed eligible v22 compatibility routes, including package-root component
+  constructors, duplicate nested registration entries, the combined `ssr-loader.js` entry, and the
+  retired theme/preset facade. Use stable tag-shaped registration entries, a component's
+  registration-free `.class.js` subpath, the split SSR/hydration entries, and the current style API.
+  The [v23-to-v24 migration guide](v23-to-v24-migration.md) gives the removed routes, ordered
+  consumer cleanup and retained-profile instructions.
+
 ### The support window
 
 Compatibility promises are bounded by a published support window, not by "evergreen browsers":
@@ -105,9 +112,9 @@ import "@aceshooting/lyra-ui/components/lr-combobox.js"; // registers <lr-combob
 import "@aceshooting/lyra-ui/components/lr-table.js"; // registers <lr-table>
 ```
 
-The older family-shaped registration paths remain supported for compatibility. Class-only
-`.class.js` entries still use their owning family path because they intentionally expose source
-organization and do not register a tag.
+Family barrel entries remain supported and register their family. Class-only `.class.js` entries
+use their owning family/component path because they intentionally expose source organization and
+do not register a tag.
 
 New application code can import any component through its stable tag-shaped path:
 
@@ -118,8 +125,7 @@ import "@aceshooting/lyra-ui/components/lr-tool-call-block.js";
 ```
 
 `llms/index.md` lists every tag and its owning implementation module. The stable tag-shaped alias
-and the family-shaped compatibility path both resolve through the package's `./components/*`
-export.
+and the supported family barrel each resolve through the package's component exports.
 
 The package root is a pure, side-effect-free export surface. Import a component entry to register
 only that tag, or use the explicit `all.js` entry when whole-library registration is needed:
@@ -128,17 +134,11 @@ only that tag, or use the explicit `all.js` entry when whole-library registratio
 import "@aceshooting/lyra-ui/all.js"; // explicitly registers the root-included tags
 ```
 
-Import component classes from their family-shaped `.class.js` subpaths. Deprecated root
-component-class exports refer to the component constructor bindings themselves, including a
-constructor re-exported from a module that also exports helpers or types. That deprecation does not
-extend to sibling helpers, constants, or types; those remain supported unless they have their own
-deprecation record. Use the owning component's granular `.class.js` subpath for class imports.
-Family-shaped registration imports are also deprecated. Both deprecated root component-class exports
-and family-shaped registration imports keep working throughout the compatibility window, with
-removal no earlier than 24.0.0. Stable tag-shaped registration imports and class-only subpaths are
-the canonical routes. The package root's helpers and types remain available. `all.js` is
-side-effectful and registers the root-included inventory; prefer tag-shaped imports in application
-code for smaller bundles.
+The package root does not re-export component constructors. Import a class from its owning
+component's `.class.js` subpath; import the stable tag-shaped entry to register it. The root remains
+a side-effect-free home for shared utilities and types. Family registration barrels and `all.js`
+remain side-effectful convenience entries; prefer tag-shaped imports for smaller application
+bundles.
 
 The entry points, then:
 
@@ -177,7 +177,7 @@ The entry points, then:
     LyraAnchor,
     LyraHighlight,
     AnchorTargetCapabilities,
-  } from "@aceshooting/lyra-ui/components/viewers/document-viewer/document-viewer.js";
+  } from "@aceshooting/lyra-ui/components/lr-document-viewer.js";
   ```
   Prefer the granular entry for component-local imports; use the root export when an application
   deliberately shares the contracts across several viewer integrations.
@@ -185,13 +185,13 @@ The entry points, then:
   a pre-resolved `src`) additionally needs
   `import '@aceshooting/lyra-ui/components/media/flag/flag-peer.js';` once.
 - **Other subpaths.** `@aceshooting/lyra-ui/theme.css` (ready-made light/dark theme),
-  `@aceshooting/lyra-ui/themes/shadcn.css` (opt-in shadcn/ui look, imported after `theme.css` — see
-  [The shadcn look](#the-shadcn-look--themesshadcncss)),
+  `@aceshooting/lyra-ui/looks/shadcn.css` (opt-in shadcn/ui look, imported after `theme.css` — see
+  [The shadcn look](#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/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 mode/accent runtime),
+  `@aceshooting/lyra-ui/theme.js` (the zero-dependency style runtime),
   `@aceshooting/lyra-ui/localization.js` (side-effect-free locale runtime),
   `@aceshooting/lyra-ui/autoloader.js` (side-effect-free on-demand tag loading),
   `@aceshooting/lyra-ui/autoloader-cdn.js` (browser-guarded auto-start side effect),
@@ -376,7 +376,8 @@ Lyra-specific events are `lr-`-prefixed `CustomEvent`s (`lr-change`, `lr-input`,
 dispatched through `LyraElement`'s `protected emit<T>(name, detail?, options?)`: **bubbling,
 composed, and non-cancelable by default**, with the payload on `event.detail`. A component that
 offers a genuine veto point opts into `{ cancelable: true }` and checks `defaultPrevented` before
-acting (as `lr-export` does) — that is called out per component. Native wrappers may additionally
+acting (as `lr-export-request` on `<lr-export-button>` does) — that is called out per component.
+Native wrappers may additionally
 relay unprefixed `Event`, `InputEvent`, or `FocusEvent` instances; each component section documents
 the exact native names, constructors, bubbling, and cancelability it supports.
 
@@ -393,6 +394,10 @@ Every one of those names is also typed — per component through its own event m
 through `@aceshooting/lyra-ui/events` for listeners on an ancestor, `document` or `window`. See
 "TypeScript" below.
 
+For event-detail compatibility fields removed in the v23-to-v24 upgrade,
+use step 7 of the [migration checklist](v23-to-v24-migration.md#migrate-a-project-in-reviewable-steps).
+Those nested detail fields are separate from deprecated event names and are not automatic renames.
+
 ## TypeScript
 
 - **Per-component event maps.** Every component with events exports a `Lyra<Name>EventMap` type, and
@@ -401,7 +406,7 @@ through `@aceshooting/lyra-ui/events` for listeners on an ancestor, `document` o
   ```ts
   import { LyraTable } from "@aceshooting/lyra-ui/components/data/table/table.class.js";
   const table = document.querySelector("lr-table") as LyraTable;
-  table.addEventListener("lr-sort", (event) => event.detail.key); // typed
+  table.addEventListener("lr-sort", (event) => event.detail.sortKey); // typed
   ```
 - **`HTMLElementTagNameMap`** is augmented in the `.class.d.ts` files. `document.querySelector('lr-table')`
   is only typed as `LyraTable` when that class module is in the type graph — importing just the
@@ -440,13 +445,13 @@ through `@aceshooting/lyra-ui/events` for listeners on an ancestor, `document` o
   `LyraGlobalEventMap` is exported as well, for writing your own typed helper over it.
 
 - **The surface is per-event type aliases, not runtime event classes.** `LyraSortEvent` and its
-  generated siblings are `type` aliases over the owning component's own map entry
-  (`LyraTableEventMap['lr-sort']`) — there is nothing to `new`, and `instanceof LyraSortEvent` is
-  not a thing. The module compiles to `export {};`: shipping runtime event subclasses to type a
-  listener would cost every consumer runtime bytes for a compile-time concern, so it deliberately
-  costs zero.
+  generated siblings are `type` aliases over component event-map entries. `LyraSortEvent` unions
+  the `lr-sort` entries for document-library, eval-dataset and table. These aliases have no runtime
+  constructor and cannot be used with `new` or `instanceof`. The module compiles to `export {};`:
+  shipping runtime event subclasses to type a listener would cost every consumer runtime bytes for
+  a compile-time concern, so it deliberately costs zero.
 - **A shared event name narrows to the union of its dispatchers.** One name can come from several
-  components with different details — `lr-select` from five, `lr-selection-change` from five — so
+  components with different details, such as `lr-select` and `lr-selection-change`, so
   its global entry is the _union_ of their entries, and `event.detail` there exposes only what all
   of them share. Index the owning component's own map when you need one component's exact detail:
 
@@ -1130,8 +1135,8 @@ 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`** — an optional look preset layered over those tokens, such as
-  [`themes/shadcn.css`](#the-shadcn-look--themesshadcncss). Empty unless one is imported.
+- **`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-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
@@ -1186,111 +1191,39 @@ first statement the browser sees is appended at the end, so an older four-name s
 `lr-theme-preset`) would rank an imported look preset above `lr-overrides` and your own layer. Every Lyra stylesheet that declares an order repeats the same five names for exactly this
 reason.
 
-### The shadcn look — `themes/shadcn.css`
+<a id="the-shadcn-look--themesshadcncss"></a>
 
-One more import restyles every component after [shadcn/ui](https://ui.shadcn.com)'s
-"new-york" style on its Neutral base colour:
+### The shadcn look — looks/shadcn.css
 
-```ts
+Import the base resolver and the optional look stylesheet, then select the look on the scope that should receive it:
+
+~~~ts
 import "@aceshooting/lyra-ui/theme.css";
-import "@aceshooting/lyra-ui/themes/shadcn.css";
-```
+import "@aceshooting/lyra-ui/looks/shadcn.css";
+import { setLyraStyle } from "@aceshooting/lyra-ui/theme.js";
 
-The preset sets only `--lr-theme-*` inputs, so no component API changes. Every rule sits in the
-`lr-theme-preset` layer, and the file repeats `theme.css`'s layer statement, so:
-
-- **load order does not matter** — the preset beats `theme.css` whichever is emitted first;
-- **any unlayered rule of yours beats both**, exactly as it beats `theme.css` alone;
-- **`setLyraTheme({ accent })` still wins** — the runtime writes inline style on `<html>`, which beats
-  every layer.
-
-**Modes.** The light block applies to `:root, .lr-light, [data-lr-theme='light'], .light` and the
-dark block to `.lr-dark, [data-lr-theme='dark'], .dark` (declared after light, same specificity). An
-application that toggles `.dark` on `<html>` the shadcn way gets Lyra's dark mode with no extra
-wiring, and a nested `.dark` (or `.light`) region is themed on its own, native `color-scheme`
-included. Only the preset knows `.dark`/`.light`: `theme.css` never reads those class names, since an
-application may already use them for something else. That is why each preset block also repeats
-`theme.css`'s own value, for that mode, of every input the preset does not restyle — the success,
-warning and remaining danger slots, the scrims, and the chart, graph and terminal ramps — so a bare
-`.dark` switches those too instead of leaving light status tints and light chart colours on a dark
-page.
-
-| Input | Light | Dark | Notes |
-| --- | --- | --- | --- |
-| `color-surface-default` / `-raised` / `-overlay` | `#ffffff` / `#fafafa` / `#ffffff` | `#0a0a0a` / `#171717` / `#171717` | page, card/sidebar, popover |
-| `color-text-normal` / `-quiet` | `#0a0a0a` / `#737373` | `#fafafa` / `#a1a1a1` | |
-| `color-surface-border`, `color-border-strong` | `#919191` | `#646464` | control boundaries, 3:1 on page and raised surface |
-| `color-surface-border-subtle` | `#e5e5e5` | `rgb(255 255 255 / 0.1)` | decorative edges only |
-| `color-brand-*`, `color-neutral-*` | quiet `#f5f5f5`, normal `#e5e5e5`, loud `#171717` | quiet `#262626`, normal `#404040`, loud `#e5e5e5` | monochrome: primary and secondary are one family |
-| `color-danger-fill-loud` / `-on-loud` | `#d6000a` / `#ffffff` | `#ff6467` / `#0a0a0a` | other danger, success and warning slots keep Lyra's values |
-| `color-focus`, `focus-ring-width`, `focus-ring-offset` | `#8b8b8b`, `3px`, `0px` | `#787878`, `3px`, `0px` | |
-| `color-mix-partner` | `#737373` | `#737373` | hover/press mix toward a mid grey |
-| `border-radius-m` / `-xs` | `0.5rem` / `0.25rem` | same | |
-| `font-family-body` / `-mono` | `'Geist', 'Inter', ui-sans-serif, system-ui, sans-serif` / `'Geist Mono', ui-monospace, …` | same | fonts are named, not shipped |
-| `font-size-m` | `0.875rem` | same | shadcn UI text is `text-sm` |
-| `form-control-height-s` / `-m` / `-l`, `icon-button-size` | `2rem` / `2.25rem` / `2.5rem`, `2.25rem` | same | the 44px coarse-pointer floor still applies |
-| `shadow-xs` … `shadow-xl` | Tailwind geometry, alpha 0.05 / 0.1 | same geometry, alphas ×3 | `--lr-theme-shadow-color` still tints them |
-
-Every name in the first column is `--lr-theme-` plus the cell. The default `<lr-button>`
-(`variant="neutral" appearance="accent"`) is shadcn's primary; `appearance="filled"` is secondary,
-`"outlined"` outline, `"plain"` ghost, `variant="danger"` destructive, `appearance="link"` link.
-
-**Deliberate deviations from shadcn**, each keeping a contrast guarantee shadcn does not make — the
-repository's contrast gate re-measures every value in both modes:
-
-- **Control borders** use the control grey above, not shadcn's `#e5e5e5` hairline (1.26:1 on white).
-  The hairline survives as `--lr-color-border-subtle`, for decoration only.
-- **Focus** is an opaque grey, 3.41:1 / 4.48:1 against the page. shadcn's half-transparent ring
-  measures about 1.5:1 / 1.9:1.
-- **Danger.** Components set text in the loud danger colour — error messages on the page, the body of
-  a danger callout on the quiet danger tint. shadcn's `#e7000b` measures 4.10:1 on that tint, so the
-  preset uses `#d6000a`, the same red a notch darker. Dark danger is a light red under near-black
-  text, not white on a dark red, for the same reason.
-- **Charts** keep Lyra's validated series ramp: two of shadcn's chart colours fall below 3:1 on
-  white, and the ramp is also checked for colour-blind separation.
-- **Hover and press** mix toward a mid grey. The default mixes toward the text colour, and shadcn's
-  primary _is_ the text colour, so the default button would show no hover or press state at all.
-- **Code-fence syntax colouring** (`lr-code-block` / `lr-markdown`'s keyword/string/comment tokens)
-  is the one surface the preset does not repaint: it stays GitHub's light/dark Shiki theme pair in
-  both modes, with no property yet to substitute a different pair. Only which of the two fixed
-  themes paints (light or dark) tracks the preset, through the same light/dark switch every other
-  surface here reads. Unlike charts, above, this one carries no `--lr-theme-*` input at all — a
-  deliberate scope line, not an oversight.
-
-**Accents.** `lr-button`'s default renders the `neutral` role, and a bare accent only re-derives
-`brand`, so the preset aliases neutral's loud slots to brand's in both modes
-(`--lr-theme-color-neutral-fill-loud: var(--lr-theme-color-brand-fill-loud)`, and likewise
-`on-loud` and `border-loud`). With no accent that is the brand literal, so nothing changes; with
-`setLyraTheme({ accent: GEMSTONES.emerald.fill })` the default button, checked checkboxes and
-radios, and the focus ring follow the accent, while neutral's quiet and normal tiers — shadcn's
-secondary and muted — stay grey. **Switch modes through `setLyraTheme({ mode })`** (or the
-no-flash bootstrap) in an application that uses accents: the runtime derives the accent ramp for the
-mode it resolved and writes `data-lr-theme`, which the preset honours. Toggling `.dark` alone would
-leave a light-mode accent ramp on a dark page. Tailwind users can point `dark:` at
-`[data-lr-theme=dark]` to share that one switch.
-
-**Overriding the preset.** An unlayered `:root { --lr-theme-… }` wins, as always. A mode-specific
-override must name the mode selectors, because the preset re-declares every input it sets on each of
-them — so a nested `.dark` region re-applies the preset's dark value over one you set on `:root`:
+setLyraStyle({ look: "shadcn" });
+~~~
 
-```css
-:root, .lr-light, [data-lr-theme="light"], .light { --lr-theme-color-brand-fill-loud: #4f46e5; }
-.lr-dark, [data-lr-theme="dark"], .dark { --lr-theme-color-brand-fill-loud: #818cf8; }
-```
+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.
 
-Two document-scope conveniences re-derive only on Lyra's own mode selectors
-(`.lr-light`/`.lr-dark`/`data-lr-theme`), not on `.dark`/`.light`: the resolved layer published by
-[`tokens-root.css`](#reading-the-resolved-tokens-from-your-own-components--tokens-rootcss) and the
-`--lr-focus-ring` composite `theme.css` declares for your own `outline: var(--lr-focus-ring)` rules.
-A nested region whose _own_ light-DOM elements read either should carry `data-lr-theme="dark"`
-alongside `.dark`. Components are unaffected; they re-derive both on their own `:host`.
+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.
 
-**Component hooks are not part of the preset** — it sets theme inputs only. For shadcn's raised
-sidebar tone, opt `lr-app-rail` in with one line:
+The shadcn look uses Neutral for primary and secondary controls. Its default button appearance is primary; filled is secondary, outlined is outline, plain is ghost, and danger remains destructive. The measured palette keeps control borders at least 3:1, uses an opaque focus color, keeps chart series contrast-qualified, and mixes hover and press toward mid grey so the monochrome primary still has a visible interaction state. Code-fence syntax colors continue to use the built-in light/dark Shiki themes.
 
-```css
-lr-app-rail { --lr-app-rail-bg: var(--lr-color-surface-raised); }
-```
+Accents are independent from the look. A named accent such as emerald recolors the default button, checked controls, and focus ring while secondary and muted neutral tiers stay grey. Select mode with setLyraStyle({ mode: "system" }) or an explicit light/dark choice so the runtime resolves the accent ramp and updates data-lr-theme. Toggling an application class alone does not update an accent ramp managed by the runtime.
+
+Override the look through an unlayered application rule or the lr-overrides layer:
+
+~~~css
+@layer lr-overrides {
+  [data-lr-look="shadcn"] {
+    --lr-theme-color-brand-fill-loud: #4f46e5;
+  }
+}
+~~~
+
+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.
 
 ### Where an override actually reaches
 
@@ -1472,7 +1405,7 @@ dark palette. Two things switch that fallback off:
 
 Note the asymmetry: the _light_ pin is read on the component itself (`:host([data-lr-theme='light'])`),
 while a _dark_ ancestor is followed through `:host-context()`. Putting `data-lr-theme="light"` on
-`<html>` — what `theme.js`'s `setLyraTheme({ mode: 'light' })` does — pins the page through
+`<html>` — what `setLyraStyle({ mode: 'light' })` does — pins the page through
 `theme.css`'s real `--lr-theme-*` values, which inherit into every shadow root. Without `theme.css`
 there are no such values to inherit, so put the attribute on the components you actually need
 pinned.
@@ -1480,340 +1413,59 @@ pinned.
 The token layer also sets `:host([hidden]) { display: none !important; }` and an inherited
 `box-sizing: border-box` reset.
 
-### Theme mode/accent/surface runtime (`@aceshooting/lyra-ui/theme.js`)
+### Style runtime — @aceshooting/lyra-ui/theme.js
 
-Flipping the mode class/attribute above is something every app ends up hand-rolling — persist a
-choice, apply it on load, avoid the flash of wrong theme before the app boots. `theme.js` is that
-runtime, published as its own subpath: **zero dependencies, no Lit, no component imports, and no
-side effects on import**, so an app can persist and apply a theme without pulling the component
-graph into its first-paint bundle.
+The standalone style runtime has no Lit or component dependency and does not touch the document or storage when imported. It stores the selected style under localStorage['lyra-theme'], applies it to the document root, and announces changes through lr-style-change.
 
-```ts
-import { setLyraTheme, getLyraTheme } from "@aceshooting/lyra-ui/theme.js";
-
-setLyraTheme({ mode: "dark" }); // unspecified fields keep their current value
-setLyraTheme({ accent: "#7c3aed" }); // mode stays 'dark'; brand-only shorthand
-getLyraTheme(); // → { mode: 'dark', accent: '#7c3aed', surface: null }
-setLyraTheme({ accent: { danger: "#dc2626", success: "#16a34a" } }); // per-role, brand untouched
-setLyraTheme({ accent: { brand: { light: "#2563eb", dark: "#f59e0b" } } }); // per-mode base color
-setLyraTheme({ surface: "#0b0f1a" }); // mixes every ramp against this instead of the mode default
-setLyraTheme({ mode: "auto" }); // follows the OS, including later changes
-setLyraTheme({
-  tokens: {
-    "--lr-theme-border-radius-m": "0.5rem", // both modes
-    "--lr-theme-color-surface-default": { light: "#ffffff", dark: "#0a0a0a" }, // per mode
-  },
-}); // replaces any previous token map wholesale
-setLyraTheme({ tokens: null }); // back to whatever the stylesheets say
-setLyraTheme({ mode: "unset", accent: null, surface: null, tokens: null }); // removes Lyra's overrides
-```
+~~~ts
+import {
+  defineLyraLook,
+  getLyraStyle,
+  resetLyraStyle,
+  setLyraStyle,
+} from "@aceshooting/lyra-ui/theme.js";
 
-- **`setLyraTheme({ mode?, accent?, surface?, tokens? })`** persists to `localStorage['lyra-theme']`,
-  applies to `document.documentElement`, and dispatches `lr-theme-change` on `window` with
-  `detail: { mode, accent, surface, tokens? }`. Fields you omit keep their current value; pass `null` to
-  clear a field. It **never throws** — when `localStorage` is unavailable (private browsing,
-  quota, a sandboxed iframe) it degrades to apply-without-persist, and the "fields you omit keep
-  their current value" rule still holds across calls in that state: the merge falls back to the
-  last theme applied in this session rather than to the default.
-- **`getLyraTheme()`** returns `{ mode, accent, surface }`, defaulting to
-  `{ mode: 'auto', accent: null, surface: null }` when nothing is stored or the stored value is
-  malformed. Storage is re-read on every call — no in-memory cache — so a value written by another
-  tab or a previous session is picked up cold. Where storage is unreadable or unwritable it
-  reports the theme last applied, so the return value always describes what the document is
-  actually showing and a toggle UI bound to it stays in sync.
-- **`mode`** is `'light' | 'dark' | 'auto' | 'unset'`. `'light'`/`'dark'` set **both
-  `data-lr-theme`** (the
-  attribute `theme.css` actually keys its palette blocks on) **and `data-theme`** (the generic
-  attribute canvas-rendered components watch, so `lr-chart`/`lr-heatmap`/`lr-qr-code` repaint on
-  the switch rather than keeping stale colors — see `llms/components/lr-chart.md`). `'auto'`
-  resolves `prefers-color-scheme` immediately and keeps following changes. `'unset'` removes both
-  attributes; use it when the application owns mode selection through another cascade.
-- **`accent`** is either an absolute CSS color — shorthand for `{ brand: <that color> }`, and the
-  only shape prior to 16.0.0 — or a per-role record
-  `{ brand?, success?, warning?, danger?, neutral? }`. Only the roles you supply are (re)derived;
-  an omitted role keeps whatever the static palette (`llms/tokens.md`) already provides. For each
-  supplied role, Lyra derives the complete quiet/normal/loud fill, border, and paired on-color
-  ramp as inline `--lr-theme-color-<role>-*` inputs; `brand` additionally keeps `--lr-theme-accent`
-  (a compatibility value holding the raw brand color, resolved for the active mode when the role
-  is per-mode) and `--lr-theme-color-focus`, which no other role drives. Each paired foreground is
-  selected for at least 4.5:1 contrast against its fill; normal/loud borders and the brand focus
-  color are adjusted to at least 3:1 against the resolved surface (see `surface` below). Malformed
-  values, CSS-wide keywords, `currentColor`, system colors, relative-color syntax, and unresolved
-  `var()` expressions fail closed to `null` — at the whole `accent` field for a bare-string call,
-  or at just that one role (or role/mode branch) for a per-role record, so one bad role does not
-  take the others down with it. Pass `accent: null` to restore the palette supplied by
-  `theme.css` entirely.
-- **Per-mode accent.** Each role's value can itself be a bare color/`null` (applied to both
-  resolved modes, as above) or a `{ light?, dark? }` map deriving that role's ramp from a
-  genuinely *different base color* per resolved mode — not merely a different tint weight of the
-  same hue — for example `{ brand: { light: "#2563eb", dark: "#f59e0b" } }`. An omitted branch
-  (or a role/branch that fails validation) keeps that mode's inherited/palette default; the branch
-  actually painted follows the *resolved* mode, so it updates automatically when `mode: 'auto'`
-  follows a `prefers-color-scheme` change. The stored/returned/event-detail shape always mirrors
-  what you supplied (bare color or `{ light, dark }`), never collapsed to a single resolved color.
-- **`surface`** is an absolute CSS color used as every role's ramp mix base, instead of the
-  shipped light/dark defaults (`#1a1a1a` dark / `#ffffff` light). It follows the same absolute
-  CSS color and fail-closed-to-`null` rules as `accent`; an alpha channel is composited against
-  the mode's own default surface before use. `null` (the default) keeps those shipped defaults.
-  Supplying `surface` changes the quiet/normal/loud mix ratios and every border/focus contrast
-  check for **every** currently-supplied role at once — it is one mix base per apply, not
-  per-role.
-
-  These are `--lr-theme-*` inputs, so they reach every nested shadow root — see "Where an override
-  actually reaches" above for why setting a `--lr-*` token instead would not.
-- **`tokens`** is a map of `--lr-theme-*` inputs written inline on `<html>`, persisted and restored
-  before first paint like the other fields. Each value is a CSS string for both modes or a
-  `{ light?, dark? }` pair; a `null` or omitted branch leaves that mode to the stylesheets. A map
-  always **replaces** the previous one wholesale — compose with object spread
-  (`{ ...LYRA_SHADCN_THEME_PRESET.theme.tokens, "--lr-theme-border-radius-m": "0" }`) — and
-  `tokens: null`, `{}` or a map with no valid entry removes it; omitting `tokens` keeps the current
-  map. Per-mode branches apply only while Lyra resolves a mode, so `mode: "unset"` writes the bare
-  values only (use the `themes/*.css` stylesheet instead when an application-owned `.dark` class
-  decides the mode). Inline `--lr-theme-*` values your application sets itself on `<html>` and that
-  are not in a map are never touched; a name that *is* in the map is owned by the runtime while the
-  map is applied, and an earlier inline value for it is not restored on removal.
-
-  **Grammar and limits.** Invalid entries are dropped one by one (`setLyraTheme()` never throws;
-  `defineLyraThemePreset()` throws `TypeError` for the same cases). A name must match
-  `--lr-theme-[a-z0-9]+(-[a-z0-9]+)*`, be at most 80 characters, and not be `--lr-theme-accent`
-  (owned by `accent`). A value is trimmed and must be 1–256 characters; it may not contain a
-  control character or line break, a backslash, a backtick, any of
-  `; { } ! < > @ [ ] $ ^ | ~ = ? & :`, U+2028/U+2029, or a
-  comment delimiter; it may not be a CSS-wide keyword (`inherit`, `initial`, `unset`, `revert`,
-  `revert-layer`); every function must be one of `rgb rgba hsl hsla hwb lab lch oklab oklch color
-  color-mix light-dark calc min max clamp var cubic-bezier steps linear` (so `url()`, `image-set()`,
-  `attr()`, `env()` and unknown functions are rejected); and parentheses and quotes must balance. A
-  map holds at most 512 entries (more normalizes to no map at all). The check is DOM-free, so
-  `defineLyraThemePreset()`, the runtime, the bootstrap and the preset generator apply it
-  identically.
-
-  **Contrast floor.** With a resolved mode, colour families the static contrast gate checks are
-  measured before they are written; a failing value is replaced by the nearest passing mix toward
-  black or white, serialized as `rgb(r g b)`, and a passing value is written verbatim. The snapshot
-  and the stored record always keep the value you supplied. The references are the explicit
-  `surface`, else the map's `--lr-theme-color-surface-default`, else the mode default (**S**:
-  `#ffffff` / `#1a1a1a`); the map's `color-surface-raised` else `#f6f8fa` / `#22272e` (**R**); the
-  painted `color-text-normal` else `#1a1a1a` / `#f2f2f2` (**T**); and the map's
-  `color-overlay-strong` else black at 0.92 / 0.95 over S (**O**). Names below omit `--lr-theme-`:
-
-  | Tokens | Against | Floor |
-  | --- | --- | --- |
-  | `color-text-normal`, `color-text-quiet` | S and R | 4.5 |
-  | `color-<role>-on-<tier>`, when its `color-<role>-fill-<tier>` is in the map (a missing on-* is synthesized) | its fill | 4.5 |
-  | `color-on-strong-overlay` (synthesized when only `color-overlay-strong` is in the map) | O | 4.5 |
-  | `color-<role>-border-normal`/`-loud`, `color-surface-border`, `color-border-strong`, `color-focus` | S | 3 |
-  | `color-chart-<n>` | S | 3 |
-  | `terminal-color-<name>` | R | 4.5 |
-  | `terminal-bg-<name>` | T | 4.5 |
-
-  **Unchecked, written verbatim:** `*-border-quiet` and `color-surface-border-subtle` (decorative by
-  contract); `color-<role>-fill-*` (measured through their on-* partner); an on-* whose fill-* is not
-  in the same map; `color-surface-default`, `-raised` and `-overlay` (references, not foregrounds —
-  text on `color-surface-overlay` is not measured); `color-overlay`, `color-no-data` and
-  `color-mix-partner`; chart-series colour-vision separation (the static gate only); every
-  non-colour token (fonts, radii, sizes, shadows, durations — including
-  `--lr-theme-icon-button-size`, whose target-size floor is yours to keep); and any value or
-  reference that does not resolve to a colour — `var()`, `light-dark()`, relative colours,
-  `currentColor`, system colours, and **every** value when a canvas is unavailable (no 2D context,
-  or pixel reads blocked). An unresolved row is written verbatim and synthesizes nothing; the accent
-  still fails closed as it always has. The runtime never reads computed styles, so a reference an
-  application stylesheet changes without the map carrying it is not seen.
-
-  **Precedence.** accent ramp (for the roles it paints) > runtime tokens (inline on `<html>`) >
-  your unlayered CSS > `lr-theme-preset` (`themes/shadcn.css`) > `lr-theme` (`theme.css`) >
-  component fallbacks. Runtime tokens therefore beat an unlayered `:root { --lr-theme-*: … }`
-  override, like the accent does; put your override in the map instead. An element that re-declares
-  a `--lr-theme-*` input itself — a `.lr-dark`/`data-lr-theme` island, a `data-lr-theme`-pinned
-  component, app-scoped CSS — keeps its own value inside that subtree (the accent ramp has the same
-  limitation).
-
-  **Snapshots.** `getLyraTheme()`, the stored record and the `lr-theme-change` /
-  `lr-theme-preset-change` details carry `tokens` **only while a map is applied** — the key is
-  absent, not `null`, otherwise, on every path including unwritable storage and the automatic mode
-  flip. The map is normalized and deep-frozen: trimmed strings, and every per-mode entry carries
-  both `light` and `dark` (`null` for a missing branch).
-- **Unbalanced colours fail closed.** An `accent` (any role or branch) or `surface` with an
-  unclosed parenthesis or quote, such as `rgb(0 0 0`, is rejected to `null` like every other
-  malformed value. The browser's own parser closes such a construct implicitly, but written raw
-  into an inline `style` it swallows the declarations after it when that attribute is re-parsed.
-
-**Theme presets.** `@aceshooting/lyra-ui/theme/presets.js` exports
-`LYRA_THEME_PRESETS`, `defineLyraThemePreset()` and `applyLyraThemePreset()`. Built-in keys are
-`system`, `light`, `dark`, `unset`, `emerald`, `ruby`, `amethyst`, and `sapphire`; the gemstone
-presets use system-following mode plus the named brand accent. Application presets use a stable
-lowercase kebab-case `id` and a `theme: { mode?, accent?, surface? }` record — the same shapes
-`setLyraTheme()` accepts, including a per-role `accent` record. `defineLyraThemePreset()`
-validates the id and field shapes, freezes both records, and leaves CSS color-syntax validation to
-the production runtime when the preset is applied:
+setLyraStyle({ mode: "dark" }); // unspecified axes keep their current value
+setLyraStyle({ accent: "sapphire" }); // named palette accent
+setLyraStyle({ accent: "#7c3aed" }); // absolute CSS color
+setLyraStyle({ accentBackground: "#0b0f1a" }); // reference surface for accent ramps
+setLyraStyle({ mode: "system" }); // follows prefers-color-scheme
+setLyraStyle({ look: "shadcn", surface: "glass", density: "compact" });
+const style = getLyraStyle();
+resetLyraStyle(["look"]); // reset only the look axis
+setLyraStyle({ mode: "unset", accent: null, accentBackground: null, overrides: null });
+~~~
 
-```ts
-import {
-  applyLyraThemePreset,
-  defineLyraThemePreset,
-} from "@aceshooting/lyra-ui/theme/presets.js";
-
-applyLyraThemePreset("sapphire");
-applyLyraThemePreset(
-  defineLyraThemePreset({
-    id: "application-ocean",
-    theme: {
-      mode: "dark",
-      accent: { brand: "#22d3ee", danger: "#dc2626" },
-      surface: "#0b0f1a",
-    },
-  })
-);
-```
+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.
 
-Applying a preset uses the production runtime. When every explicitly requested field survives its
-runtime validation, Lyra reflects the id to `data-lr-theme-preset` and emits
-`lr-theme-preset-change` on `window` with `{ id, theme }`, where `theme` is the complete applied
-snapshot. If runtime validation changes a field (for example, an invalid accent fails closed to
-`null`), only the ordinary `lr-theme-change` event is emitted and no preset marker is written,
-because the resulting state is not exactly that named preset. A direct `setLyraTheme()` call also
-removes the preset marker.
-
-**Token presets: a look as its own axis.** A preset's `theme` may carry `tokens` (see `tokens`
-above). `defineLyraThemePreset()` validates the whole map against the same grammar the runtime
-applies and throws `TypeError` on any violation, so a map it accepts is never changed at run time and
-the preset still claims its marker — even where a canvas is unavailable. A look is independent of
-mode, accent and surface: a preset that omits those fields leaves them as they are, and the built-in
-presets never mention `tokens`, so `applyLyraThemePreset("sapphire")` or `"dark"` keeps the current
-look. Either order reaches the same state; only the marker (the last applied id) differs. The
-shadcn look ships as a generated runtime preset, built from `themes/shadcn.css` so the two can never
-drift:
+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.
 
-```ts
-import { applyLyraThemePreset, defineLyraThemePreset } from "@aceshooting/lyra-ui/theme/presets.js";
-import { LYRA_SHADCN_THEME_PRESET } from "@aceshooting/lyra-ui/theme/presets/shadcn.js";
-
-applyLyraThemePreset(LYRA_SHADCN_THEME_PRESET); // look on; mode, accent and surface kept
-applyLyraThemePreset("sapphire"); // an accent on top of the look
-
-// The exact stylesheet rendering (no accent ramp, default surface), keeping a marker:
-applyLyraThemePreset(
-  defineLyraThemePreset({
-    id: "shadcn-exact",
-    theme: { ...LYRA_SHADCN_THEME_PRESET.theme, accent: null, surface: null },
-  })
-);
-```
+accent accepts one of Lyra's named palettes or an absolute CSS color. A custom color is shorthand for a brand color; an object can set colors for brand, success, warning, danger, and neutral independently. Each role can use a { light, dark } pair. Lyra derives quiet, normal, and loud fill, border, and on-color ramps. Foregrounds meet 4.5:1 contrast against their fills; normal and loud borders and the brand focus color meet 3:1 against the selected reference surface. Invalid colors fail closed.
 
-Choose the carrier by need. The runtime preset persists, is restored by the no-flash bootstrap
-before first paint, needs no stylesheet swap, and is written inline, so it beats unlayered `:root`
-overrides. The `themes/shadcn.css` stylesheet is the one to use for light/dark **islands**, for an
-application-owned `.dark`/`.light` class, or for a page with no theme runtime. The runtime preset
-module is a separate subpath, so an application that only uses `presets.js` pays nothing for it.
-
-**No-flash bootstrap.** `lyraThemeBootstrap` is a self-contained IIFE **string** (not a function),
-meant to be inlined into a `<script>` in `<head>` **before any stylesheet**, so the persisted theme
-is on the root element before first paint. It reads `localStorage['lyra-theme']`.
-`createLyraThemeBootstrap({ storageKey })` returns the same kind of string for an application-owned
-key, so an existing persistence layer can reuse the pre-paint half independently of
-`setLyraTheme()`/`getLyraTheme()`. Calling the factory with no options returns the same string as
-`lyraThemeBootstrap`. The result is a string precisely so this can happen in an unbundled
-`<script>` context without shipping or parsing the module. Custom keys are escaped against HTML
-script termination and JavaScript line separators. Under a Content Security Policy, give the
-inline script the nonce or hash required by the application:
+accentBackground is an absolute CSS color used as the accent ramps' reference surface. surface is a separate visual treatment: solid or glass. density selects compact, comfortable, or touch. These axes remain independent, so changing the look does not reset mode, accent, surface, or density.
 
-```html
+A LyraLook is a named token definition. Define an application look with defineLyraLook({ id, tokens }), then pass it as the look choice. A look supplies --lr-theme-* inputs; overrides applies an independent map of those inputs to the document root. Both accept CSS strings or per-mode { light, dark } values. Overrides replace the previous map wholesale; compose them with object spread. Values are validated, trimmed, and deep-frozen. Invalid entries are ignored, and maps are limited to 512 entries.
+
+The token grammar rejects CSS-wide keywords, control characters, unsafe punctuation, unbalanced functions or quotes, and functions outside the documented color and layout set. Color families checked by the static contrast gate are corrected to meet their contrast floor before painting. The snapshot and stored record retain the normalized requested values. Inline style ownership records only properties Lyra wrote and restores an earlier author value when a choice is cleared.
+
+**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:
+
+~~~html
 <head>
   <script>
     /* server-inlines lyraThemeBootstrap here */
   </script>
   <link rel="stylesheet" href="/theme.css" />
 </head>
-```
-
-Both variants read a stored `{ mode, accent, surface }` record, resolve `auto`, and derive the same
-per-role ramp(s) from the same math — the bootstrap re-implements it inline (self-contained, so it
-can run before any module loads) rather than importing the runtime, but the two are tested to never
-drift. A missing or malformed record receives the runtime's
-`{ mode: 'auto', accent: null, surface: null }` default; blocked `localStorage` leaves the document
-untouched rather than throwing before your app loads.
-
-The stored record also carries `tokens` while a map is applied, and the bootstrap restores it
-before first paint: the same grammar, the same per-mode branch for the resolved mode, and the same
-contrast floor as the runtime. It records the names it wrote on `<html>`, so the runtime's first
-apply removes or rewrites exactly those. Token values are read from storage at run time and never
-serialized into the script string. **The bootstrap's bytes change with library releases** — this
-one included — so a deployment that pins a CSP hash for the inline script (or for
-`theme-bootstrap.js`) must regenerate that hash when upgrading, or the browser blocks the bootstrap
-and the first-paint flash returns.
-
-**External-file delivery for a strict CSP.** `@aceshooting/lyra-ui/theme-bootstrap.js` is a
-third, non-module way to ship the same bootstrap: a static script asset published alongside the
-package, containing exactly `lyraThemeBootstrap`'s bytes (both are produced from the same build
-step, so they can never drift apart). Reference it with a plain `<script src>` in `<head>`,
-still before any stylesheet:
+~~~
 
-```html
-<head>
-  <script src="/vendor/theme-bootstrap.js"></script>
-  <link rel="stylesheet" href="/theme.css" />
-</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.
 
-This exists for a Content-Security-Policy that forbids `unsafe-inline` and cannot mint a
-per-response nonce — a static HTML entry, for example — where the documented inline-script
-nonce/hash guidance above does not apply. Serving it same-origin (copy it into your build output,
-or configure your bundler/static host to do so) needs no hash at all; hashing it for an even
-stricter policy uses the same CSP `script-src` hash mechanism browsers already apply to any
-external script resource.
+**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).
 
-**Configuring the static asset from its own `<script>` tag.** `theme-bootstrap.js` must be loaded
-as a plain classic script — never `type="module"` and never `async` — because it reads its own
-configuration synchronously through `document.currentScript` while it runs, and that property is
-`null` for both of those loading modes (as well as for anything scheduled after the script has
-already finished executing). Two optional attributes on that same `<script>` tag override the
-defaults without regenerating the file:
-
-```html
-<head>
-  <script
-    src="/vendor/theme-bootstrap.js"
-    data-lr-theme-storage-key="my-app-theme"
-    data-lr-theme-attributes="data-lr-theme data-theme"
-  ></script>
-  <link rel="stylesheet" href="/theme.css" />
-</head>
-```
-
-- `data-lr-theme-storage-key` — the `localStorage` key to read, in place of the default
-  `'lyra-theme'`. Equivalent to `createLyraThemeBootstrap({ storageKey })`'s argument, but
-  resolved by the static file itself at parse time rather than baked in ahead of time. This is
-  what lets an application with its own pre-existing storage key use the static asset instead of
-  inlining a per-app copy.
-- `data-lr-theme-attributes` — a space-separated list of attribute names to set on
-  `<html>` in place of the default `data-lr-theme data-theme` pair, replacing that list entirely
-  rather than adding to it.
-
-Both attributes are optional and independently validated; an absent, empty, oversized, or
-malformed value falls back to the built-in default rather than throwing, so a `<script>` tag with
-neither attribute — every existing deployment — behaves exactly as before. `data-lr-theme-storage-key`
-must be a non-empty string of at most 200 characters (its content is otherwise unrestricted — it is
-only ever used as an opaque `localStorage` key, never written to the DOM). `data-lr-theme-attributes`
-must parse to one to eight tokens, each unique and each matching `data-[a-z0-9]+(-[a-z0-9]+)*` —
-which rejects an event-handler name (`onload`), a native attribute (`style`, `class`, `id`), any
-token containing whitespace, a quote, `=`, or a control character, an empty list, and a duplicated
-token — because these attribute names reach `setAttribute()`/`removeAttribute()` on the document
-root. A `document.currentScript` of `null` (module/async misuse, or a script tag re-read after it
-finished running) is treated the same as no configuration at all.
-
-An application-owned key from `createLyraThemeBootstrap({ storageKey })` can still be inlined as
-documented above; the static file's own script-tag attributes are the alternative for a strict-CSP
-deployment that cannot inline that call.
-
-**Migrating from 15.x.** `accent` used to be exactly an absolute CSS color or `null`; that shape
-still works unchanged (`setLyraTheme({ accent: '#7c3aed' })` keeps deriving only the brand ramp).
-What changed is `LyraTheme` gaining a `surface` field alongside it — a strict superset for every
-caller that only ever read/wrote `mode`/`accent`, since `getLyraTheme()` now also returns
-`surface: null` by default. Only code that structurally compares the whole returned record (for
-example `assert.deepEqual(getLyraTheme(), { mode, accent })`) needs the extra field added.
-
-**`tokens` is optional and absent unless used.** `LyraTheme` also gains an optional `tokens` field;
-`getLyraTheme()`, the stored record and both event details omit the key entirely until a token map
-is applied, so `assert.deepEqual(getLyraTheme(), { mode, accent, surface })` keeps passing.
+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.
 
 ### Invalidating canvas theme values
 
@@ -2084,7 +1736,7 @@ itself — gap and flow margins would add up (set `--lr-prose-flow-space: 0` if
 | --------------------- | ------------------------------------------------------------- | --------------------------------------- |
 | Heading sizes         | 2 / 1.75 / 1.25 / 1.125rem                                    | 2.25 / 1.875 / 1.5 / 1.25rem            |
 | h1 weight             | 700                                                           | 800                                     |
-| Tracking              | `normal` unless the hook or theme input sets it; `themes/shadcn.css` sets -0.025em | tight              |
+| Tracking              | `normal` unless the hook or theme input sets it; `looks/shadcn.css` sets -0.025em | tight              |
 | Flow spacing          | 1rem (`--lr-prose-flow-space`)                                | 1.5rem                                  |
 | Space before headings | 2 × flow = 2rem for every level                               | 2.5rem before h2, 2rem before h3        |
 | Paragraph leading     | 1.6                                                           | 1.75rem                                 |
@@ -2154,7 +1806,7 @@ and opacity tokens first. These additional hooks customize only the light-DOM bu
 | `--lr-prose-quote-padding`                | `--lr-space-l`; logical quote inset in `lr-prose` and `lr-typography`        |
 | `--lr-prose-quote-border-width`           | `--lr-border-width-thick` in `lr-prose`, `--lr-border-width-medium` in `lr-typography`; logical quote edge |
 | `--lr-heading-letter-spacing`             | `--lr-theme-heading-letter-spacing`, then `normal`; heading tracking for `lr-heading-1`–`4` and `lr-typography` headings |
-| `--lr-theme-heading-letter-spacing`       | unset; theme input for heading tracking (no resolved `--lr-*` token); `themes/shadcn.css` sets it |
+| `--lr-theme-heading-letter-spacing`       | unset; theme input for heading tracking (no resolved `--lr-*` token); `looks/shadcn.css` sets it |
 | `--lr-visually-hidden-size`               | `--lr-size-1px` (1px); retained hidden box size                              |
 | `--lr-native-link-decoration-width`       | `--lr-border-width-thin`; resting underline thickness                        |
 | `--lr-native-link-underline-offset`       | `--lr-space-2xs`; underline offset                                           |
@@ -2234,8 +1886,8 @@ The side-effect-free `@aceshooting/lyra-ui/localization.js` entry exports
 `LyraPluralMessage`, `LyraPluralCategory`, `LyraLocaleBridgeOptions` and `LyraLocaleBridgeCleanup`.
 The package root continues to re-export the runtime for compatibility and remains registration-free;
 use the dedicated entry when the application only needs locale setup and the narrower import graph.
-The former `@aceshooting/lyra-ui/utilities/localization.js` entry point was removed in 23.0.0.
-Change that import specifier to `@aceshooting/lyra-ui/localization.js`; the helper contracts are unchanged.
+The former utility-scoped entry point was removed in 23.0.0. Change that import specifier to
+`@aceshooting/lyra-ui/localization.js`; the helper contracts are unchanged.
 **`LYRA_DEFAULT_STRINGS` is the authoritative key list** (matching the `LyraMessageKey` union) —
 read it to find the key to override rather than guessing one. Date, number, byte, relative-time and
 calendar output goes through `Intl`.
@@ -2673,12 +2325,16 @@ and adapters emit empty JavaScript and do not register elements.
 
 ## SSR and declarative shadow DOM
 
+When replacing the removed combined `ssr-loader.js` route, split browser hydration from component
+registration and server rendering as shown below. The [v23-to-v24 migration guide](v23-to-v24-migration.md)
+has the ordered upgrade steps and environment-specific import mapping.
+
 Root, `all.js`, and granular component imports are server-safe under the supported Node 22+ runtime.
 `@aceshooting/lyra-ui/ssr/all.js` is the **server-only** convenience entry: unlike the browser
 `all.js`, it registers the complete inventory including the optional-peer families — defining those
 tags never imports their peers (each component loads its own lazily, client-side), and the
 browser-bundle argument for excluding them does not apply to a server render. Use the public
-`@aceshooting/lyra-ui/ssr-loader.js` entry for the tested Lit SSR contract. Its exported
+`@aceshooting/lyra-ui/ssr.js` entry for the tested Lit SSR contract. Its exported
 `LYRA_SSR_SUPPORT_MATRIX`, `LYRA_SSR_RENDER_AND_HYDRATE_TAGS`, and
 `LYRA_SSR_CLIENT_RENDER_TAGS` classify every inventory tag exactly once:
 
@@ -2691,7 +2347,7 @@ browser-bundle argument for excluding them does not apply to a server render. Us
 Server setup (the fallback must precede Lit's renderer):
 
 ```ts
-import { lyraSsrElementRenderers } from "@aceshooting/lyra-ui/ssr-loader.js";
+import { lyraSsrElementRenderers } from "@aceshooting/lyra-ui/ssr.js";
 import { render, LitElementRenderer } from "@lit-labs/ssr";
 import { html } from "lit";
 
@@ -2700,7 +2356,7 @@ const result = render(html`<lr-page><main>Dashboard</main></lr-page>`, {
 });
 ```
 
-In the browser, import `@aceshooting/lyra-ui/ssr-loader.js` before any other module that can import
+In the browser, import `@aceshooting/lyra-ui/hydration.js` before any other module that can import
 Lit. This installs `@lit-labs/ssr-client/lit-element-hydrate-support.js` before component
 registration. `getLyraSsrMode(tagName)` reads one tag's tier, and
 `diagnoseLyraHydration(document)` inspects current Lyra hosts in the supplied tree and every
@@ -2764,8 +2420,8 @@ real component — instead of hand-rolling a `CustomEvent` and guessing its shap
 ```ts
 import { createLyraEvent } from '@aceshooting/lyra-ui/testing';
 
-const event = createLyraEvent('lr-confirm-bar', 'lr-approve', { args: null, waitUntil: () => {} });
-event.cancelable; // true — lr-confirm-bar's own lr-approve call site is cancelable
+const event = createLyraEvent('lr-confirm-bar', 'lr-approve-request', { args: null, waitUntil: () => {} });
+event.cancelable; // true — lr-confirm-bar's own lr-approve-request call site is cancelable
 target.dispatchEvent(event);
 ```
 
@@ -2811,11 +2467,14 @@ await activateStep(stepper, 'review'); // clicks the [part="step"] button for th
 same `[part="option"]` row plus `data-value` delegated-click pattern for its own listbox/popup.
 `submitConfirmDecision()`
 accepts either `<lr-confirm-bar>` or `<lr-tool-approval-dialog>`, which render the identical
-`[part="approve-button"]`/`[part="deny-button"]` pair for the same `lr-approve`/`lr-deny`
-contract.
+`[part="approve-button"]`/`[part="deny-button"]` pair and emit cancelable
+`lr-approve-request`/`lr-deny-request` events. The driver awaits the component's render;
+if a listener calls `preventDefault()` on either component, or `waitUntil()` on the confirm bar,
+the action may still be pending when the driver returns.
 
 Each driver is `async` and awaits `updateComplete` before returning, so assertions written
-immediately after it see fully-settled DOM/state. Each one also throws a plain `Error` — never a
+immediately after it see the render reached by that interaction. Host-driven async decisions
+still need their own completion check. Each driver also throws a plain `Error` — never a
 silent no-op — when the requested interaction cannot actually happen: the target is disabled, the
 option owner/stepper is read-only or has no matching row/step currently rendered, or the confirm
 bar is already decided. That is the exact failure mode a hand-rolled event misses (for example
@@ -2987,10 +2646,8 @@ they carry no `tag`: `components/media/flag/flag-peer.js`,
 stand in for. They are a separate array rather than tag-less rows mixed into `entries`, so a reader
 that keys `entries` by `tag` keeps working; `integrations`, `distModule` and `localeKeys` are all
 additive, which is why the schema version is unchanged. `registrationModule` is the `src/` path used
-internally; `distModule` is that same module's own published deep specifier (e.g.
-`./components/data/table/table.js`) so a caller holding either a per-tag alias or a deep import can
-resolve the other without reading `src/` or walking `dist/` — for an integration bridge,
-`distModule` equals `entry`, since there is no separate alias. `registers` is every `lr-*` tag
+internally; `distModule` is a retained published specifier and equals the stable `entry` for v24
+per-tag registrations and integration bridges. `registers` is every `lr-*` tag
 importing `entry` defines, direct or transitive, derived from the same transitive-import analysis
 `scripts/check-component-dependencies.mjs` already performs against the real registration graph
 (not a second hand-maintained list). `localeKeys` is every `LyraMessageKey` the registered tags can
@@ -3033,8 +2690,8 @@ same way `all.js` registers its root-included tags (the package root itself regi
 and want a single import; reach for the granular
 `@aceshooting/lyra-ui/components/<tag>.js` path when you do not, because a barrel cannot be
 tree-shaken down to the two elements you actually render. The tag-shaped path remains stable if a
-component moves between Lyra's internal family folders; existing family-shaped registration paths
-remain supported.
+component moves between Lyra's internal family folders. Duplicate nested registration paths were
+removed in v24; family barrels remain supported.
 
 ```js
 import "@aceshooting/lyra-ui/components/forms"; // every form control
@@ -5037,34 +4694,30 @@ These named interfaces and helper signatures are available to typed integrations
   copy, so a glyph rendered anywhere else on the page can match it exactly by consuming the same
   export and attribute.
 
-- **`theme-presets-contracts`** — Shared utility contracts.
-  `applyLyraThemePreset(/* public names: presetOrName */): unknown`
-  `defineLyraThemePreset(/* public names: preset */): unknown`
-  `LyraThemePresetChangeDetail {
-  id: unknown;
-  theme: unknown;
-}`
-  `LyraThemePreset {
-  id: unknown;
-  theme: unknown;
-}`
-
 - **`theme-theme-contracts`** — Shared utility contracts.
-  `createLyraThemeBootstrap(/* public names: options */): unknown`
-  `getLyraTheme(): unknown`
+  `createLyraThemeBootstrap(options?: LyraThemeBootstrapOptions): string`
   `LyraThemeBootstrapOptions {
-  storageKey: unknown;
-}`
-  `LyraTheme {
-  mode: unknown;
-  accent: unknown;
-  surface: unknown;
-  tokens: unknown;
+  storageKey?: string;
 }`
-  `setLyraTheme(/* public names: theme */): unknown`
+  `LyraThemeSemanticRole = 'brand' | 'success' | 'warning' | 'danger' | 'neutral'`
+  `LyraThemeAccentValue = string | null | { light?: string | null; dark?: string | null }`
+  `LyraThemeAccent = string | null | Partial<Record<LyraThemeSemanticRole, LyraThemeAccentValue>>`
+  ``LyraThemeTokenName = `--lr-theme-${string}```
+  `LyraThemeTokenValue = string | { light?: string | null; dark?: string | null }`
+  `LyraThemeTokens = Readonly<Record<LyraThemeTokenName, LyraThemeTokenValue>>`
+  `LyraStyleAxis = 'look' | 'surface' | 'density' | 'mode' | 'accent'`
+  `LyraStyleField = LyraStyleAxis | 'accentBackground' | 'overrides'`
+  `LyraLookId = 'lyra' | 'shadcn' | 'material' | (string & {})`
+  `LyraSurface = 'solid' | 'glass'`
+  `LyraDensity = 'compact' | 'comfortable' | 'touch'`
+  `LyraMode = 'light' | 'dark' | 'system' | 'unset'`
+  `LyraAccentName = 'emerald' | 'peridot' | 'topaz' | 'ruby' | 'tourmaline' | 'amethyst' | 'aquamarine' | 'sapphire' | 'hematite'`
+  `LyraAccent = LyraAccentName | LyraThemeAccent`
+  `LyraAccentBackground = string | { light?: string | null; dark?: string | null } | null`
   `applyLyraStyleScope(element: Element, choices: LyraStyleScopeChoices | null): void`
   `defineLyraLook<const Look extends LyraLook>(look: Look): Readonly<Look>`
   `getLyraStyle(): Readonly<LyraStyle>`
+  `lyraThemeBootstrap: string`
   `LyraLook {
   readonly id: LyraLookId;
   readonly tokens: LyraThemeTokens;
@@ -5868,19 +5521,21 @@ unchanged. Step numbers and interactive context-meter legend rows use matching s
 pairs; control-border colors no longer act as their text backgrounds. Material uses 8% hover and
 12% press state layers with its `currentColor` mix partner, keeping filled-action labels at 4.5:1.
 
-Runtime custom accents, including `setLyraTheme({ accent })` and legacy gemstone presets, now
+Runtime custom accents, including `setLyraStyle({ accent })` and legacy gemstone presets, now
 floor the loud fill to 4.5:1 against its quiet fill and the built-in reference surfaces because the
 same token paints accent text. Its on-loud foreground follows the corrected fill. For example,
 light shadcn emerald changes from `#34d399` with black on-loud text to `#1a6a4d` with white text
 (6.537:1). Checked controls, brand text and streaming accents follow that loud token; secondary
 neutral controls stay unchanged. The requested and persisted accent color is retained.
 
-The compatibility `setLyraTheme()` API shares the same stored selection. Its `surface` remains an
-accent reference color (the new API calls that `accentBackground`), and its `auto` mode corresponds
-to `system`. A stored legacy CSS color such as `aquamarine` stays that color; it is not silently
-converted into the gemstone of the same name. `parseLyraStyleRecord()` and `lyraStyleAttributes()`
-provide DOM-free server-rendering helpers. Render attributes through the framework's normal HTML
-escaping; the returned object is not an HTML string.
+The runtime and no-flash bootstrap still read v1 records written by the retired theme API. On
+read, auto becomes system and the old accent reference surface becomes accentBackground. A saved
+`tokens` map remains runtime-look tokens (`lookForm: 'runtime'`), separate from public `overrides`;
+without a valid saved look id, the runtime look is named `custom`. A CSS color such as aquamarine
+remains a CSS color and is not converted into the named gemstone. New writes use the current style
+record while retaining those runtime-look tokens. parseLyraStyleRecord() and
+lyraStyleAttributes() provide DOM-free server-rendering helpers; render the returned attributes
+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