@aceshooting/lyra-ui 2.12.0 → 3.0.0

package/llms-full.txt

@@ -1,18 +1,14 @@
 # @aceshooting/lyra-ui — LLM API Reference
 
-`@aceshooting/lyra-ui` is a library of free, clean-room [Lit](https://lit.dev) web components — a
-companion to [Web Awesome](https://webawesome.com) that reimplements selected Web Awesome **Pro**
-components as open-source equivalents (documented compatible tag shape, attributes, slots, events,
-and CSS parts under a `lyra-` prefix instead of `wa-`), plus a number of extras that have no Web Awesome
-counterpart at all (dashboard atoms, temporal/graph widgets, chart wrappers, a map component, a
-file dropzone). It is **token-compatible with Web Awesome**: every component's stylesheet resolves
-through Web Awesome's `--wa-*` design tokens first, falling back to its own `--lyra-*` tokens, so
-components read as native inside a Web Awesome-themed app and are equally usable standalone with no
-theme at all. This document is the complete, component-by-component API reference intended for
-coding assistants integrating the library; for install instructions, the full component catalog, and
-the `<wa-*>` → `<lyra-*>` migration notes, see the package [README](./README.md) — or the shorter
-curated index at [`llms.txt`](./llms.txt) if you just need the shape of the library before diving in
-here.
+`@aceshooting/lyra-ui` is a free, independent, MIT-licensed [Lit](https://lit.dev) web-component
+library and an open-source alternative to Shoelace and Web Awesome. It combines accessible form
+controls, layout and overlay primitives, dashboards, charts, data visualization, and Conversation &
+Agent UI. Selected components retain documented Web Awesome-compatible public names under a `lyra-`
+prefix to make migration easier, but Lyra has its own implementation, design tokens, localization
+runtime, RTL behavior, and release surface. It has no runtime dependency on either project. This is
+the complete component-by-component API reference for coding assistants integrating the library; for
+installation, the full catalog, and Web Awesome/Shoelace migration notes, see the package
+[README](./README.md) — or the shorter curated index at [`llms.txt`](./llms.txt).
 
 Component entry points such as `components/empty/empty.js` register their custom-element tag.
 Every component also exposes a matching `.class.js` entry for subclassing or type-directed
@@ -105,21 +101,22 @@ Not a custom element itself — infrastructure every `lyra-*` component in the l
   `lyra-citation-badge`, and `lyra-menu` (which resolves its `placement` through
   `rtlAwarePlacement()` first — see `rtl.ts` below — before handing it to `place()`).
 - **`tokens.styles.ts` → `tokens`** (a `css` template prepended to every component's stylesheet) —
-  the whole design-token layer. Every value chains through a `--wa-*` Web Awesome token first, with
-  a hard-coded fallback, e.g. `--lyra-color-brand: var(--wa-color-brand-fill-loud, #0969da)`. Full
+  the whole design-token layer. Every value chains through an independent `--lyra-theme-*` custom
+  property and finally a hard-coded fallback, e.g. `--lyra-color-brand: var(--lyra-theme-color-brand-fill-loud, #0969da)`.
+  Full
   set: `--lyra-color-surface / -text / -text-quiet / -border / -brand / -brand-quiet / -success /
   -success-quiet / -warning / -warning-quiet / -danger / -danger-quiet`,
   `--lyra-color-on-brand / -on-success / -on-warning / -on-danger` (paired
   text/icon colors for content painted on the corresponding solid semantic fill; standalone light
-  and dark fallbacks choose a contrasting foreground for each fill, while a Web Awesome theme can
-  provide its own `*-on-loud` values), `--lyra-space-xs / -s / -m / -l`, `--lyra-radius`, `--lyra-shadow`,
+  and dark fallbacks choose a contrasting foreground for each fill, while a consumer's own theme
+  can provide its own `*-on-loud` values), `--lyra-space-xs / -s / -m / -l`, `--lyra-radius`, `--lyra-shadow`,
   `--lyra-font`, `--lyra-transition-fast` / `-base` (motion timing every animating component should
   share), `--lyra-opacity-disabled` (one shared disabled-state opacity), `--lyra-focus-ring-width` /
   `-color` / `-offset` (every `:focus-visible` rule should reference these), `--lyra-icon-button-size`
   (minimum tappable box for icon-only buttons; the glyph itself doesn't grow). Also sets
   `:host([hidden]) { display: none !important; }`, an inherited `box-sizing: border-box` reset, and
   a `prefers-color-scheme: dark` fallback that re-points the color tokens' hard-coded defaults at a
-  dark palette (only takes effect when no real `--wa-*` theme value is present).
+  dark palette (only takes effect when no real `--lyra-theme-*` value is set).
 - **`prefix.ts`** — `LYRA_PREFIX = 'lyra'`; `tag(name)` → `` `lyra-${name}` ``; `defineElement(name,
   ctor)` — idempotent `customElements.define`, safe if a module is evaluated twice.
 - **`a11y.ts`** — `nextId(scope)`: monotonic id generator (e.g. `nextId('combobox-list')` →
@@ -544,6 +541,10 @@ Text field + calendar popover, **form-associated** via the shared `FormAssociate
   internal `<input>`; empty omits the attribute. Named `autoCorrect` in JS/TS (not `autocorrect`)
   to dodge a `lib.dom.d.ts` collision with `HTMLElement`'s own boolean `autocorrect` IDL member;
   the wire attribute is still the plain `autocorrect` name
+- `autocomplete: string = ''`, `inputMode: string = ''` (attribute `inputmode`), and
+  `enterKeyHint: string = ''` (attribute `enterkeyhint`) — forwarded to the internal date input
+- `autocomplete: string = ''`, `inputMode: string = ''` (`inputmode`), and `enterKeyHint: string = ''`
+  (`enterkeyhint`) — forwarded to the internal `<input>`.
 
 **Methods:** `show()`, `hide()`, `clear()`
 
@@ -720,15 +721,14 @@ original declarative `value`, matching native `defaultValue` behavior.
 
 ## `lyra-button`
 
-A generic action-button primitive, the `lyra-*` equivalent of a plain `wa-button`. Renders an
-internal native `<button>` (this library has no runtime dependency on Web Awesome); `type="submit"`/
+A generic action-button primitive. Renders an internal native `<button>`; `type="submit"`/
 `type="reset"` are handled by the component itself via the host's own `closest('form')`, since a
 shadow-internal native button doesn't participate in an ancestor form's submission on its own.
 
 **Properties:**
 - `variant: 'neutral' | 'brand' | 'success' | 'warning' | 'danger' = 'neutral'` (reflected)
 - `appearance: 'accent' | 'filled' | 'outlined' | 'plain' = 'filled'` (reflected) — `'accent'` is a
-  loud, high-contrast filled tier (equivalent to `wa-button`'s own runtime-default appearance),
+  loud, high-contrast filled tier,
   distinct from `'filled'` for `variant="neutral"` specifically (`'filled'` reads the ambient
   surface color there; `'accent'` reads a solid neutral fill)
 - `size: 'xs' | 's' | 'm' | 'l' | 'xl' = 'm'` (reflected)
@@ -737,7 +737,11 @@ shadow-internal native button doesn't participate in an ancestor form's submissi
   clearing `disabled`
 - `disabled: boolean = false` (reflected)
 
-**Getters/methods:** `focus(options?)`/`blur()` — forwarded to the internal native `<button>`.
+The shared `m` size uses `--lyra-font-size-m`. The internal button follows the host's inline size through `--lyra-button-width` (default
+`100%`), and the size scale is exposed through `--lyra-button-size-xs/-s/-m/-l/-xl`.
+
+**Getters/methods:** `click()`, `focus(options?)`, and `blur()` — forwarded to the internal native
+`<button>`; `click()` also runs the component's submit/reset behavior.
 
 **Events:** none (a plain native `click` bubbles and composes through the shadow boundary
 unmodified; disabled while `disabled` or `loading`).
@@ -746,11 +750,12 @@ unmodified; disabled while `disabled` or `loading`).
 
 **CSS parts:** `base`, `label`, `start`, `end`, `spinner` (present only while `loading`).
 
-**Themeable custom properties:** `--lyra-button-accent`, `--lyra-button-fill`,
+**Themeable custom properties:** `--lyra-button-width`, `--lyra-button-size-xs/-s/-m/-l/-xl`,
+`--lyra-button-accent`, `--lyra-button-fill`,
 `--lyra-button-on-fill`, `--lyra-button-border` (each swapped by the active `variant`, default
 `neutral` falls back to plain text/surface/border tokens), `--lyra-button-accent-fill`,
 `--lyra-button-accent-on-fill` (the `appearance="accent"` fill/foreground pair; `neutral` falls
-back to `--wa-color-neutral-fill-loud`/`-on-loud`, every other variant reuses that variant's own
+back to `--lyra-color-neutral`/`--lyra-color-on-neutral`, every other variant reuses that variant's own
 loud fill token), `--lyra-button-hover-brightness` (default `1.08`, the `:hover` filter intensity),
 `--lyra-button-active-scale` (default `0.9875`, the `:active` press-scale, disabled under
 `prefers-reduced-motion`).
@@ -790,13 +795,17 @@ form-associated via the same `FormAssociated` mixin as `lyra-textarea`. Ships th
 - `errorText: string = ''` (attribute `error-text`)
 - `accessibleLabel: string | null = null` (attribute `aria-label`)
 - `autocomplete: string = ''`
+- `spellcheck: boolean = true` — forwarded to the native input, including `spellcheck="false"`
+- `autocapitalize: string = ''` / `autoCorrect: string = ''`
+- `inputMode: string = ''` / `enterKeyHint: string = ''`
 - `min?: number` / `max?: number` / `step?: number` (attribute: false — `type="number"` only)
 - `passwordVisible: boolean = false` (attribute `password-visible` — `type="password"` only)
 - `name`/`disabled`/`required` (from `FormAssociated`)
 
-**Events:** `lyra-input` (`detail: { value }`, fired on every user-driven edit), `lyra-change`
-(`detail: { value }`, fired on the native `change` timing), `blur`/`focus` (re-dispatched bubbling +
-composed from the internal native input's own `blur`/`focus`).
+**Events:** native-style composed `input` and `change`, plus `lyra-input` (`detail: { value }`,
+fired on every user-driven edit) and `lyra-change` (`detail: { value }`, fired on the native
+`change` timing), `blur`/`focus` (re-dispatched bubbling + composed from the internal native input's
+own `blur`/`focus`).
 
 **Slots:** `label`, `hint`, `error`.
 
@@ -821,6 +830,18 @@ composed from the internal native input's own `blur`/`focus`).
   `ElementInternals` — not a second hand-rolled regex check.
 - `type="password"` always renders the `password-toggle` button; there is no separate opt-out.
 
+## `lyra-number-input`
+
+A migration-friendly numeric alias of `lyra-input`. It forces `type="number"` while retaining the
+same form association, label/hint/error chrome, native editing passthrough, input/change events,
+and `min`/`max`/`step` validation. It exposes the same properties, slots, events, and CSS parts as
+`lyra-input`.
+
+## `lyra-time-input`
+
+A migration-friendly time alias of `lyra-input`. It forces the native `type="time"` while retaining
+the same form association, chrome, native editing passthrough, events, slots, and CSS parts.
+
 ---
 
 ## `lyra-phone-input`
@@ -1400,8 +1421,8 @@ accent edge and value tint).
 
 ## `lyra-table`
 
-Presentational, sort/select-aware data table. **The host owns actual sorting/filtering/pagination**
-of `rows` — this component only renders and emits intents.
+Sort/select-aware data table. Sorting remains consumer-controlled; optional filtering, pagination,
+and loading chrome are built in while remaining controlled at the public API boundary.
 
 **Properties:**
 - `columns: TableColumn<T>[] = []` (attribute: false) — `{ key, label, headerCell?, width?,
@@ -1419,7 +1440,8 @@ of `rows` — this component only renders and emits intents.
   `[part='foot']` (`<tfoot>`) only renders at all when at least one column defines `footer`;
   `cellStyle` is applied directly to the generated `<td>` via `styleMap` — e.g. a computed heat-tint
   background a `cell()`-returned inner element can't paint into the cell's own padding — omit it for
-  no per-cell style override (the default, unchanged output)
+  no per-cell style override (the default, unchanged output); `editable` enables double-click
+  editing, `editValue` supplies the editor value, and `editType` selects `text` or `number`
 - `columnsHidden: boolean = false` (attribute `columns-hidden`, reflected) — computed/read-only: true
   when a `priority` column is *actually* hidden right now by the `@container` breakpoints above, or
   `showAllColumns` force-visible mode is currently active. Measured via a `ResizeObserver` on
@@ -1437,6 +1459,31 @@ of `rows` — this component only renders and emits intents.
   when omitted, which is only safe while `rows` never reorders — set it whenever `rows` can be
   sorted/filtered/re-ordered across renders, or selection/click can silently attach to the wrong row
 - `selectedKey: string | number | null = null` (attribute: false) — **single**-selection only
+- `selectionMode: 'none'|'single'|'multiple' = 'none'` (attribute `selection-mode`, reflected) —
+  opt-in self-managed row selection; the default remains presentational
+- `selectedKeys: Set<string | number> = new Set()` (attribute: false) — the selected raw row keys
+  used by multiple selection
+- `filterable: boolean = false` (attribute `filterable`, reflected) — renders a localized search
+  field above the grid
+- `filterText: string = ''` (attribute `filter-text`) — controlled filter text
+- `filter?: (row: T, text: string) => boolean` (attribute: false) — typed predicate used by the
+  filter field; when omitted, rows are matched against their JSON representation
+- `filterLabel: string = ''` (attribute `filter-label`) and `filterPlaceholder: string = ''`
+  (attribute `filter-placeholder`) — optional localized-label overrides
+- `loading: boolean = false` (attribute `loading`, reflected) and `loadingLabel: string = ''`
+  (attribute `loading-label`) — renders a busy spinner and suppresses the grid while loading
+- `pageSize: number = 0` (attribute `page-size`) — positive values enable controlled pagination;
+  zero disables the pagination footer
+- `page: number = 1` (attribute `page`, reflected) — controlled current page
+- `totalItems: number = -1` (attribute `total-items`) — server-side total item count; `-1` derives
+  the total from filtered rows
+- `paginationMode: 'client'|'server' = 'client'` (attribute `pagination-mode`, reflected) — client
+  mode slices rows; server mode renders the supplied page unchanged
+- Editable columns emit `lyra-cell-edit` on commit and never mutate the supplied row object.
+- `groupBy?: (row: T) => string | number` (attribute: false) — inserts a non-focusable full-width
+  group row before each group
+- `groupLabel?: (key: string | number, rows: 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
 - `canExpand?: (row: T) => boolean` (attribute: false) — optional per-row gate for expansion
@@ -1459,7 +1506,11 @@ of `rows` — this component only renders and emits intents.
 (`detail: { row }`), `lyra-load-more` (fired on the "load more" button), `lyra-columns-hidden-change`
 (`detail: { hidden: boolean }`, fired only on a real `columnsHidden` transition),
 `lyra-columns-revealed` (`detail: { revealed: boolean }`), and `lyra-row-expand-toggle`
-(`detail: { row, key }`; the table does not mutate `expandedKeys`)
+(`detail: { row, key }`; the table does not mutate `expandedKeys`), and
+`lyra-selection-change` (`detail: { keys }`) when selection is enabled, `lyra-filter-change`
+(`detail: { text }`), and `lyra-page-change` (`detail: { page }`) from the controlled
+filter/pagination surfaces, and `lyra-cell-edit` (`detail: { row, key, value }`) for editable
+columns
 
 **Slots:** none — content comes entirely from `columns`/`rows`.
 
@@ -1467,7 +1518,8 @@ of `rows` — this component only renders and emits intents.
 chevron indicator shown on the active sortable header, rotated per `sortDir`), `reveal-columns-button`
 (shown only when `columnsHidden` is true), `foot` (the `<tfoot>`, only rendered when at least one
 column defines `footer`), `footer-row`, `footer-cell`, `expand-toggle-cell`, `row-expand-toggle`,
-`row-expand-icon`, `expanded-row`, `expanded-cell`
+`row-expand-icon`, `expanded-row`, `expanded-cell`, `filter-label`, `filter`, `loading`, and
+`pagination`, `cell-editor`, `group-row`, and `group-cell`
 
 **Themeable custom properties:** `--lyra-table-max-height` (default `none`; controls the scrollable
 body's `max-block-size`).
@@ -1833,6 +1885,9 @@ itself (absent for `'wide'`/`collapse="none"`); and the `lyra-split-collapse-cha
 divider adjacent to the collapsed panel is drag/keyboard-disabled (`aria-disabled="true"`) while
 collapsed. `collapse="none"` (the default) is byte-for-byte identical to pre-collapse-feature behavior.
 
+`dividerLabel?: (index: number, panelCount: number) => string` (attribute: false) customizes the
+localized accessible label generated for each auto-inserted divider.
+
 **Events:** `lyra-resize` (`detail: { sizes }`, fired on every drag step/release **and** every
 keyboard step), `lyra-split-collapse-change` (`detail: { state: 'wide'|'rail'|'floating' }`, fired only
 on a real `collapse`-state transition, never on every resize/render),
@@ -1912,6 +1967,8 @@ position) survives the transition.
   sidebar/toolbar visible during fullscreen
 - `compact: boolean = false` (reflected) — tighter header/body padding, same convention as
   `lyra-empty`'s `compact`
+- `backdropInset: string = ''` (attribute `backdrop-inset`) — overrides the fullscreen backdrop's
+  CSS `inset` independently from `fullscreenInset`; when empty, it follows `fullscreenInset`
 - `views: WidgetView[] = []` (attribute: false) — named alternate views for the panel body, e.g. a
   chart/table toggle inside the same card chrome; `WidgetView { id: string; label: string; icon?:
   TemplateResult }`. Each entry gets a header toggle button (`[part='view-toggle']`) and a
@@ -1940,7 +1997,7 @@ empty), `label-group` (wrapper around the label and sublabel), `label`, `sublabe
 `backdrop`
 
 **Themeable custom properties:** `--lyra-widget-overlay-color` (default `rgb(0 0 0 / 0.5)` — the
-fullscreen backdrop scrim color; component-specific since no shared `--wa-*`/`--lyra-*` overlay token
+fullscreen backdrop scrim color; component-specific since no shared `--lyra-*` overlay token
 exists), plus shared tokens (`--lyra-space-*`, `--lyra-color-border/-surface/-text-quiet`,
 `--lyra-radius`, `--lyra-shadow`, `--lyra-icon-button-size`, `--lyra-focus-ring-*`).
 
@@ -2222,10 +2279,15 @@ A Canvas-rendered heatmap with a DPR-aware, resize-aware redraw loop, in one of
 `"matrix"` (default — a `rowLabels` × `colLabels` grid of `values`) or `"calendar"` (a
 GitHub-style Sunday–Saturday × week grid built from `days`, colored by quartile bucket rather than
 the matrix mode's continuous ramp). Every cell is independently addressable despite being
-canvas-drawn (no per-cell DOM node): a `pointermove` hit-test over the canvas shows `[part="tooltip"]`
+canvas-drawn (no per-cell DOM node by default): a `pointermove` hit-test over the canvas shows `[part="tooltip"]`
 with that cell's label + value; the canvas is `tabindex="0"` with arrow-key roving focus (a stroked
 ring redrawn over the focused cell on every draw, plus `[part="live-region"]` announcing it); and a
-click, or Enter/Space on the focused cell, fires `lyra-cell-click`.
+  click, or Enter/Space on the focused cell, fires `lyra-cell-click`.
+
+Set `accessibleCells: true` (`accessible-cells`) to opt into a native-button overlay for each
+interactive matrix/calendar cell. The overlay uses localized `aria-label`s, explicit
+`aria-pressed="true"|"false"` from the controlled `selectedCell`, and roving tabindex/arrow-key
+focus; it continues to emit `lyra-cell-click` and leaves selection state consumer-controlled.
 
 **Properties:**
 - `rowLabels: string[] = []` (attribute: false — matrix mode only)
@@ -2265,6 +2327,11 @@ click, or Enter/Space on the focused cell, fires `lyra-cell-click`.
   announcement when the focused cell is the selection. Purely a controlled property — mirrors
   `<lyra-lite-chart>`'s `selectedIndex`, this component never mutates it itself. Unset (the default,
   `null`) reproduces today's exact output.
+- `accessibleCells: boolean = false` (attribute `accessible-cells`) — renders `[part="cells"]` with
+  one `[part="cell"]` native button per interactive cell. Buttons expose localized `aria-label`s,
+  explicit `aria-pressed` state from `selectedCell`, and a roving tabindex; the canvas becomes
+  `aria-hidden` while this mode is enabled. The property is opt-in so the default canvas mode keeps
+  its low DOM footprint.
 - `cellText?: (pos: MatrixCellPos | CalendarCellPos, value: number) => string` (attribute: false) —
   formats the per-cell hover tooltip and keyboard live-region announcement text; receives the cell
   position (`{ row, col }` in matrix mode, `{ week, weekday }` in calendar mode) and its value.
@@ -2323,7 +2390,8 @@ force a redraw manually.
 
 **Slots:** none.
 
-**CSS parts:** `base`, `canvas`, `tooltip` (hover tooltip, positioned over the hovered cell),
+**CSS parts:** `base`, `canvas`, `cells` (opt-in per-cell overlay), `cell` (one opt-in native cell
+button), `tooltip` (hover tooltip, positioned over the hovered cell),
 `live-region` (visually-hidden `role="status" aria-live="polite"` element announcing the
 keyboard-focused cell), `legend`, `legend-lo`, `legend-hi`, `legend-annotation` (one per labeled
 `annotations` entry)
@@ -2576,6 +2644,8 @@ descendants of the treeitem, matching the WAI-ARIA treeitem pattern's containmen
 - `setSize: number = 1`, `posInSet: number = 1` (attribute: false) — this node's `aria-setsize`/
   `aria-posinset` values among its siblings, pushed down from `<lyra-tree>`; normally set internally,
   not by consumers
+- `hasChildren: boolean` (read-only getter) — reports whether `item.children` contains at least one
+  child; leaf nodes never expose `aria-expanded` and cannot expand or collapse
 
 **Methods:** `expand()`, `collapse()` (each a no-op if already in that state, or a leaf), `select()`
 (fires `lyra-node-select`).
@@ -3122,6 +3192,10 @@ parsing (that's left entirely to the host).
 - `label: string = 'Drop files here or click to browse'`
 - `accessibleLabel: string = ''` (attribute `aria-label`) — overrides `label` as the internal
   dropzone/button accessible name without changing visible copy
+- `acceptedMessage: string = '{count} file(s) added.'` (attribute `accepted-message`) — live-region
+  message after an accepted selection; `{count}` is replaced with the accepted count
+- `rejectedMessage: string = '{count} file(s) rejected.'` (attribute `rejected-message`) — live-region
+  message after rejected files; `{count}` is replaced with the rejected count
 
 **Methods:** `openPicker()` programmatically opens the native file dialog; `focus(options?)`
 forwards to the interactive dropzone.
@@ -3181,6 +3255,219 @@ an extension-only `accept` list.
 
 ---
 
+## `lyra-drawer`
+
+A modal panel anchored to one edge of the viewport. It inherits the dialog overlay contract:
+focus trapping, Escape and optional backdrop dismissal, document scroll locking, overlay stacking,
+accessible naming, and the cancelable `lyra-dialog-close` event.
+
+**Properties:**
+- `open: boolean = false` (attribute `open`, reflected) — controls visibility
+- `placement: 'start'|'end'|'top'|'bottom' = 'start'` (attribute `placement`, reflected)
+- `heading?: string`, `label: string`, `closable: boolean`, and `noLightDismiss: boolean` — inherited
+  dialog naming and dismissal options
+
+**CSS parts:** `backdrop`, `panel`, `header`, `heading`, `close-button`, `label`, `body`, `footer`.
+
+**Themeable custom properties:** `--lyra-drawer-width`, `--lyra-drawer-height`, and inherited
+dialog surface/overlay tokens.
+
+```html
+<lyra-drawer open placement="end" heading="Filters" closable>
+  <lyra-checkbox label="Only active"></lyra-checkbox>
+</lyra-drawer>
+```
+
+---
+
+## `lyra-carousel`
+
+Accessible carousel for arbitrary slotted slide elements. It shows one assigned element at a time,
+adds slide semantics and localized position labels, and provides keyboard, button, and indicator
+navigation.
+
+**Properties:**
+- `index: number = 0` (attribute `index`, reflected) — active slide index
+- `loop: boolean = false` (attribute `loop`, reflected) — wraps navigation at either end
+- `autoplay: boolean = false` (attribute `autoplay`, reflected) and `autoplayInterval: number = 5000`
+  (attribute `autoplay-interval`) — optional timed advance; autoplay is disabled under reduced motion
+- `showIndicators: boolean = true` (attribute `show-indicators`) — renders slide indicator buttons
+- `accessibleLabel: string = ''` (attribute `accessible-label`) — fallback landmark name; a host
+  `aria-label` takes precedence
+
+**Methods:** `next()`, `previous()`, and `goTo(index)` update the active index and emit
+`lyra-slide-change` (`detail: { index }`).
+
+**CSS parts:** `base`, `viewport`, `track`, `controls`, `previous-button`, `next-button`,
+`indicators`, and `indicator`.
+
+```html
+<lyra-carousel aria-label="Screenshots">
+  <img alt="Dashboard overview" src="overview.png">
+  <img alt="Dashboard details" src="details.png">
+</lyra-carousel>
+```
+
+---
+
+## `lyra-carousel-item`
+
+Optional semantic wrapper for one slide in `<lyra-carousel>`. The carousel also accepts arbitrary
+slotted elements, so this element is useful when a migration needs the explicit item tag.
+
+**Slots:** default slide content.
+
+**CSS parts:** `base`.
+
+```html
+<lyra-carousel>
+  <lyra-carousel-item>Dashboard overview</lyra-carousel-item>
+  <lyra-carousel-item>Dashboard details</lyra-carousel-item>
+</lyra-carousel>
+```
+
+---
+
+## `lyra-button-group`
+
+Responsive semantic grouping primitive for related action controls. It preserves the slotted
+controls and exposes `role="group"` on its internal wrapper.
+
+**Properties:**
+- `orientation: 'horizontal' | 'vertical' = 'horizontal'` (reflected)
+- `label: string = ''` — accessible group name; a host `aria-label` is used when `label` is empty
+
+**Slots:** default action controls.
+
+**CSS parts:** `base`.
+
+---
+
+## `lyra-image-comparer`
+
+Before/after comparison surface with two named slots and a keyboard-accessible native range handle.
+
+**Properties:**
+- `position: number = 50` (attribute `position`, reflected) — divider position from 0 to 100
+- `orientation: 'horizontal'|'vertical' = 'horizontal'` (attribute `orientation`, reflected)
+- `accessibleLabel: string | null` (attribute `aria-label`) — accessible name for the comparison
+  and its range handle
+- `beforeLabel`/`afterLabel` — fallback text for empty named slots
+
+**Events:** `lyra-position-change` (`detail: { position }`), plus composed `focus` and `blur` events
+from the internal range handle.
+
+**Slots:** `before`, `after`.
+
+**CSS parts:** `base`, `before`, `after`, `divider`, and `handle`.
+
+```html
+<lyra-image-comparer aria-label="Before and after">
+  <img slot="before" alt="Before" src="before.png">
+  <img slot="after" alt="After" src="after.png">
+</lyra-image-comparer>
+```
+
+---
+
+## `lyra-zoomable-frame`
+
+Scrollable inspection frame with bounded zoom controls and keyboard shortcuts. Scrolling provides
+panning when zoomed content exceeds the viewport.
+
+**Properties:**
+- `zoom: number = 1` (attribute `zoom`, reflected), `minZoom: number = 0.5`, `maxZoom: number = 4`,
+  and `zoomStep: number = 0.25` — bounded zoom configuration
+- `src: string = ''` and `alt: string = ''` — optional image source; otherwise the default slot is
+  rendered
+- `accessibleLabel: string | null` (attribute `aria-label`) — host-level accessible name
+
+**Methods:** `zoomIn()`, `zoomOut()`, and `resetZoom()` update the zoom and emit
+`lyra-zoom-change` (`detail: { zoom }`). The viewport also accepts `+`, `-`, and `0` keyboard
+shortcuts.
+
+**CSS parts:** `base`, `viewport`, `content`, `controls`, `zoom-out`, `zoom-in`, and `reset`.
+
+```html
+<lyra-zoomable-frame src="map-preview.png" alt="Map preview" aria-label="Map preview"></lyra-zoomable-frame>
+```
+
+---
+
+## `lyra-scroller`
+
+Responsive overflow surface with optional previous/next controls. The default slot remains the
+consumer's content, and the viewport is a native scroll container that works in narrow panels as
+well as full-width layouts.
+
+**Properties:**
+- `orientation: 'horizontal' | 'vertical' = 'horizontal'` (reflected)
+- `controls: boolean = false` (reflected) — show previous/next controls
+- `hideScrollbar: boolean = false` (attribute `hide-scrollbar`, reflected)
+- `scrollStep: number = 0` (attribute `scroll-step`) — custom step; zero uses 80% of the viewport
+- `label: string = ''` — accessible region name; a host `aria-label` is used when set
+
+**Events:** `lyra-scroll` with `scrollStart`, `scrollEnd`, `scrollLeft`, and `scrollTop` in the
+detail object.
+
+**Slots:** default scrollable content.
+
+**CSS parts:** `base`, `viewport`, `content`, `previous`, and `next`.
+
+```html
+<lyra-scroller controls label="Project cards">
+  <lyra-card>Solar</lyra-card>
+  <lyra-card>Wind</lyra-card>
+  <lyra-card>Battery</lyra-card>
+</lyra-scroller>
+```
+
+---
+
+## `lyra-resize-observer`
+
+Lifecycle-managed wrapper around the native `ResizeObserver`. It observes all element children in
+the default slot and emits a composed event, while adding no layout of its own.
+
+**Properties:** `disabled: boolean = false` (reflected) and `box: 'content-box' | 'border-box' |
+'device-pixel-content-box' = 'content-box'` (reflected).
+
+**Events:** `lyra-resize` with `{ entries: ResizeObserverEntry[] }` in `detail`.
+
+**Slots:** default observed elements. **CSS parts:** `base`.
+
+---
+
+## `lyra-intersection-observer`
+
+Lifecycle-managed wrapper around the native `IntersectionObserver`. It observes all element children
+in the default slot and emits a composed event, while adding no layout of its own.
+
+**Properties:** `disabled: boolean = false` (reflected), `rootMargin: string = '0px'` (attribute
+`root-margin`), `threshold: number | number[] = 0`, and `root: Element | null = null`.
+
+**Events:** `lyra-intersection` with `{ entries: IntersectionObserverEntry[] }` in `detail`.
+
+**Slots:** default observed elements. **CSS parts:** `base`.
+
+---
+
+## `lyra-mutation-observer`
+
+Lifecycle-managed wrapper around the native `MutationObserver`. All element children in the default
+slot are observed and their mutation records are emitted as a composed event; the wrapper itself
+adds no layout.
+
+**Properties:** `disabled: boolean = false` (reflected), `childList: boolean = true` (attribute
+`child-list`), `observeAttributes: boolean = false` (attribute `attributes`), `characterData: boolean = false` (attribute
+`character-data`), `subtree: boolean = true`, and `attributeFilter: string[] = []`.
+
+**Events:** `lyra-mutation` with `{ records: MutationRecord[] }` in `detail`.
+
+**Slots:** default observed elements. **CSS parts:** `base`.
+
+---
+
 ## `lyra-dialog` / `confirm()`
 
 General-purpose modal/overlay plus a promise-based confirmation helper built on top of it.
@@ -3204,6 +3491,8 @@ hand-building that chrome isn't worth it.
 - `closable: boolean = false` (attribute `closable`) — renders a built-in close (X) button in the
   header row (creating one, with no heading text, if `heading` is unset), wired to the same
   `close()` path Escape/backdrop-dismiss already use, with reason `'close-button'`
+- `noLightDismiss: boolean = false` (attribute `no-light-dismiss`) — prevents a backdrop click from
+  closing the dialog; Escape and explicit `close()` calls remain available
 
 Also settable as a plain `aria-label` attribute (not a public JS property): overrides the panel's
 computed accessible name outright, winning over every other source below (a slotted heading,
@@ -3241,7 +3530,7 @@ when no heading is slotted and `heading` is unset), `body` (wrapper around the d
 `footer` (wrapper around the `footer` slot)
 
 **Themeable custom properties:** `--lyra-dialog-overlay-color` (default `rgb(0 0 0 / 0.5)` — the
-backdrop scrim color; component-specific since no shared `--wa-*`/`--lyra-*` overlay token exists),
+backdrop scrim color; component-specific since no shared `--lyra-*` overlay token exists),
 `--lyra-dialog-width` (default unset/`auto` — the panel shrink-wraps to content, unchanged; set it
 for an assertive width instead), `--lyra-dialog-max-width` (default `32rem` — the panel's
 max-inline-size cap, via `min(var(--lyra-dialog-max-width, var(--lyra-dialog-width, 32rem)), 100%)`;
@@ -3901,7 +4190,7 @@ fenced/indented `<pre>`), `link` (every rendered `<a>`), `table` (every rendered
 
 **Themeable custom properties:** `--lyra-markdown-font-mono` (default `ui-monospace, SFMono-Regular,
 Menlo, Consolas, monospace` — the code/code-block font; component-specific since no shared
-`--wa-*`/`--lyra-*` monospace token exists), plus shared tokens `--lyra-space-xs/-s/-m/-l`,
+`--lyra-*` monospace token exists), plus shared tokens `--lyra-space-xs/-s/-m/-l`,
 `--lyra-color-brand-quiet`, `--lyra-color-brand`, `--lyra-color-border`, `--lyra-color-text-quiet`,
 `--lyra-radius`.
 
@@ -3983,6 +4272,8 @@ conversation-surface level).
 - `collapsed: boolean = false` (reflected) — whether the message body is hidden; effective whenever
   set, independent of `collapsible` (which only controls whether the toggle button itself is
   rendered) — mirrors `lyra-widget`'s identical `collapsible`/`collapsed` pair
+- `attachmentsPosition: 'before'|'after' = 'after'` (attribute `attachments-position`) — places the
+  `attachments` slot before or after the message body; both the visual and reading order follow it
 
 **Events:** `lyra-retry` (no detail payload; fired by the built-in retry button, only rendered when
 `status="failed"`), `lyra-collapse-toggle` (`detail: boolean`, the new `collapsed` state — fired when
@@ -4615,6 +4906,8 @@ wins when both are present.
   indeterminate state, and filename context so translators can reorder every value
 - `uploadFailedLabel: string = 'Upload failed'` (attribute `upload-failed-label`) — visible status
   text shown for `status="error"`; override for i18n/locale
+- `untitledLabel: string = 'Untitled file'` (attribute `untitled-label`) — fallback filename and
+  tooltip when neither `file` nor `name` supplies a name
 
 The component identifies *which* attachment a `lyra-remove`/`lyra-retry` event is about via the
 platform's own `id` attribute/property rather than a second, differently-named prop. Set `id="..."`
@@ -5109,6 +5402,11 @@ emitting `lyra-change`.
   `<input>`'s own `autocorrect` (Safari/WebKit-specific); empty omits the attribute. Named
   `autoCorrect` in JS purely to dodge a `lib.dom.d.ts` typing collision — the wire attribute is
   still plain `autocorrect`.
+- `autocomplete: string = 'off'`, `inputMode: string = ''` (attribute `inputmode`), and
+  `enterKeyHint: string = ''` (attribute `enterkeyhint`) — forwarded to the free-text input;
+  they have no effect in closed-dropdown mode
+- `autocomplete: string = 'off'`, `inputMode: string = ''` (`inputmode`), and `enterKeyHint: string = ''`
+  (`enterkeyhint`) — forwarded to the free-text mode's native `<input>`.
 - `name: string = ''` (reflected)
 - `disabled: boolean = false` (reflected)
 - `required: boolean = false` (reflected — enforced via `internals.setValidity()`)
@@ -5313,6 +5611,9 @@ shared overlay stack. First-party invention (no Web Awesome equivalent).
 - `searchPlaceholder: string = 'Search tools…'` (attribute `search-placeholder`)
 - `filter: ToolSelectFilter | null = null` (attribute: false) — overrides the built-in
   case-insensitive name/description substring match.
+- `autocomplete: string = ''`, `spellcheck: boolean = true`, `autocapitalize: string = ''`,
+  `autoCorrect: string = ''` (`autocorrect`), `inputMode: string = ''` (`inputmode`), and
+  `enterKeyHint: string = ''` (`enterkeyhint`) — forwarded to the search `<input>`.
 
 **Methods:** `close(reason: ToolSelectDialogCloseReason = 'api'): void` — closes the dialog, emits
 `lyra-close` with `reason`, and returns focus to whatever had it before the dialog opened.
@@ -6326,6 +6627,8 @@ and it's what every instance renders at zero extra bytes until shiki resolves.
   for that language — an additive, opt-in escape hatch for a build scoped to just the languages a
   consumer actually needs. A `language` absent from this map (or `languages` left unset) falls back
   to the default dynamic-import path unchanged.
+- `languagesOnly: boolean = false` (attribute `languages-only`) — skips the default shiki loader;
+  use when every requested language is supplied through `languages`
 
 **Events:** `lyra-copy` (`detail: { text: string }` — always the raw `code` value, never the
 highlighted HTML, and always fires regardless of whether the actual OS clipboard write succeeded),
@@ -6339,7 +6642,7 @@ button is activated, same event name/shape convention as `<lyra-thinking-panel>`
 
 **Themeable custom properties:** `--lyra-code-block-max-height` (default `none` — the consumer-tunable
 scroll cap; only takes effect once `max-height` is set), `--lyra-code-block-font` (default
-`ui-monospace, SFMono-Regular, Menlo, Consolas, monospace` — no shared `--wa-*`/`--lyra-*` monospace
+`ui-monospace, SFMono-Regular, Menlo, Consolas, monospace` — no shared `--lyra-*` monospace
 token exists to resolve through), plus shared tokens `--lyra-color-border`, `--lyra-radius`,
 `--lyra-color-surface`, `--lyra-space-xs/-s/-m`, `--lyra-font`, `--lyra-color-text-quiet`,
 `--lyra-color-text`, `--lyra-color-brand`/`-brand-quiet`, `--lyra-transition-fast`,
@@ -6559,6 +6862,15 @@ renders at the start of the action row, before Deny/Edit/Approve.
   `false` via a PROPERTY binding, e.g. `.editable=${false}` — a `?editable=${false}`
   boolean-attribute binding cannot override a true default). When `false`, `args` is always shown
   read-only and can never be changed before approval.
+- `spellcheck: boolean = false`, `autocapitalize: string = 'off'`,
+  `autoCorrect: string = 'off'` (attribute `autocorrect`), `autocomplete: string = 'off'`,
+  `wrap: 'hard'|'soft'|'off' = 'soft'`, `inputMode: string = ''` (attribute `inputmode`),
+  and `enterKeyHint: string = ''` (attribute `enterkeyhint`) — forwarded to the raw-JSON
+  textarea; the defaults keep browser editing assistance from changing JSON text
+- `spellcheck: boolean = false`, `autocapitalize: string = 'off'`, `autoCorrect: string = 'off'`
+  (`autocorrect`), `autocomplete: string = 'off'`, `wrap: 'hard'|'soft'|'off' = 'soft'`,
+  `inputMode: string = ''` (`inputmode`), and `enterKeyHint: string = ''` (`enterkeyhint`) —
+  forwarded to the raw-JSON `<textarea>` while editing.
 
 **Methods:** `close(reason: ToolApprovalDialogCloseReason = 'api'): void` — closes the dialog, emits
 `lyra-close` with `reason`, and returns focus to whatever had it before the dialog opened; a no-op if
@@ -6802,6 +7114,10 @@ menu, an avatar menu, or a history row's overflow menu. Uses the WAI-ARIA "menu
   a no-op for existing consumers), matching `lyra-select`/`lyra-model-select`'s
   `this.getAttribute('aria-label') || <computed default>` precedence
 
+- `closeOnEscapeAnywhere: boolean = false` (attribute `close-on-escape-anywhere`) — lets Escape
+  close the menu when focus is on slotted non-menu-item content inside the popup; item activation
+  remains scoped to actual menu items
+
 **Events:** `lyra-show` (no detail — fires only when `open` transitions to `true`, not for markup
 that renders `open` true from the start), `lyra-hide` (same first-render guard, opposite
 transition), `lyra-menu-select` (`detail: { value }` — a consolidated re-fire of the activated
@@ -6869,6 +7185,21 @@ not rendered at all for `type="normal"`)
 
 **Optional peer deps:** none.
 
+### `lyra-dropdown-item`
+
+Compatibility naming alias for `<lyra-menu-item>`. It is a subclass of the same implementation,
+so `value`, `disabled`, `destructive`, `type`, `checked`, `select()`, checkbox events, and menu
+roving focus behave identically.
+
+**Slots:** default label content and optional `icon`.
+
+```html
+<lyra-menu>
+  <button slot="trigger">Actions</button>
+  <lyra-dropdown-item value="archive">Archive</lyra-dropdown-item>
+</lyra-menu>
+```
+
 ```html
 <lyra-menu label="Row actions">
   <button slot="trigger" aria-label="More actions">⋮</button>
@@ -7568,6 +7899,8 @@ capability as a row.
   `'Attach files'`); only affects the single-capability button (`[part='trigger']`) — the
   multi-capability menu's own trigger keeps its fixed `'Add attachment'` label regardless. Unset
   (the default) keeps the built-in English default.
+- `triggerTitle?: string` (attribute `trigger-title`) — forwards a sighted-user hover tooltip to
+  both the single-capability and multi-capability trigger buttons
 
 **Events:** `lyra-pick` (`detail: { capability: 'files' | 'image'; files: FileList }`) — fired once a
 file-backed capability's hidden input produces a real selection. The `FileList` is an independent
@@ -7860,10 +8193,194 @@ the `footer` slot, hidden entirely when empty).
 
 ---
 
+## `lyra-radio`
+
+A form-associated single-choice control. Use it alone or inside `lyra-radio-group`.
+
+**Properties:** `checked`, `disabled`, `required`, `name`, and `value` (all reflected where
+applicable). A selected radio submits its value through `ElementInternals`.
+
+**Events:** native-style composed `input` and `change`, plus `lyra-change` with
+`{ checked, value }`.
+
+**Slots:** default label content.
+
+**CSS parts:** `base`, `circle`, `dot`, `label`.
+
+```html
+<lyra-radio name="format" value="json">JSON</lyra-radio>
+```
+
+## `lyra-popover`
+
+A click-triggered, light-dismiss floating surface positioned with the shared Floating UI positioner.
+
+**Properties:** `open`, `placement`, `distance`, `accessibleLabel` (`aria-label`), and `popupRole` (`popup-role`).
+**Events:** `lyra-show`, `lyra-hide`. **Slots:** `trigger`, default content. **CSS parts:** `trigger`,
+`popup`, `content`.
+
+## `lyra-tooltip`
+
+A hover/focus tooltip positioned with the shared Floating UI positioner.
+
+**Properties:** `open`, `manual`, `delay`, `placement`, `distance`, `content`, and
+`accessibleLabel` (`aria-label`). **Slots:** `trigger`, default content. **CSS parts:**
+`trigger`, `popup`.
+
+## `lyra-dropdown`
+
+A menu-role popover for consumer-supplied action content. Compose `lyra-menu` when full roving
+menu-item behavior is needed.
+
+**Properties:** `open`, `placement`, `distance`, `accessibleLabel` (`aria-label`), and `popupRole` (`popup-role`).
+**Slots:** `trigger`, default menu content. **CSS parts:** `trigger`, `popup`, `content`.
+
+## `lyra-radio-group`
+
+A labeled, keyboard-navigable group of `lyra-radio` controls. Arrow keys, Home, and End move
+focus; arrow navigation selects the next enabled radio.
+
+**Properties:** `label`, `hint`, `errorText` (`error-text`), `name`, `required`, `disabled`, and
+`aria-label` (through `accessibleLabel`).
+
+**Events:** `lyra-change` with `{ value, radio }`.
+
+**Slots:** default radios, `label`, `hint`, `error`.
+
+**CSS parts:** `base`, `label`, `hint`, `error`.
+
+## `lyra-spinner`
+
+An indeterminate busy indicator with a localized `role="status"` name.
+
+**Properties:** `labelPlacement` (`label-placement`): `'none' | 'after'` and `accessibleLabel`
+(`accessible-label`).
+
+**Slots:** default optional visible label. **CSS parts:** `base`, `spinner`, `label`.
+
+## `lyra-progress-bar`
+
+A determinate or indeterminate progress bar.
+
+**Properties:** `value`, `max`, `indeterminate`, `variant`, `showValue` (`show-value`), and
+`accessibleLabel` (`accessible-label`).
+The rendered progressbar exposes `aria-valuemin`, `aria-valuemax`, and `aria-valuenow` when
+determinate.
+
+**Slots:** `label`. **CSS parts:** `base`, `track`, `indicator`, `label`.
+
+## `lyra-progress-ring`
+
+A circular progress indicator with the same value contract as `lyra-progress-bar`.
+
+**Properties:** `value`, `max`, `indeterminate`, and `accessibleLabel` (`accessible-label`).
+**Slots:** default center label. **CSS parts:** `base`, `track`, `indicator`, `label`.
+
+## `lyra-badge` and `lyra-tag`
+
+Compact status labels. Both expose `variant: 'neutral' | 'brand' | 'success' | 'warning' | 'danger'`.
+The two tags share the same visual contract; `lyra-tag` is a semantic alias for migration-friendly
+markup.
+
+**Slots:** default content. **CSS parts:** `base`.
+
+## `lyra-callout`
+
+An inline status, warning, or error surface. Set `inline` for lightweight reactive form or mutation
+errors without panel chrome.
+
+**Properties:** `variant`, `heading`, `closable`, `inline`, `open`, and `accessibleLabel`
+(`accessible-label`).
+
+**Events:** cancelable `lyra-close`; the callout hides after the event unless a listener calls
+`preventDefault()`.
+
+**Slots:** default message, `heading`, `icon`. **CSS parts:** `base`, `icon`, `content`, `heading`,
+`close-button`.
+
+## `lyra-details`, `lyra-accordion`, and `lyra-accordion-item`
+
+`lyra-details` is a native-semantics disclosure panel. `lyra-accordion` coordinates slotted
+details panels and closes siblings unless `multiple` is true. `lyra-accordion-item` is an
+accordion-compatible alias.
+
+**Properties:** `open`, `disabled`, and `summary` on details/items; `multiple` on accordion.
+**Events:** `lyra-toggle` with `{ open }` from details/items. **Slots:** `summary` and default
+content on details/items; default panels on accordion. **CSS parts:** `base`, `summary`, `content`
+on details/items; `base` on accordion.
+
+## `lyra-divider`
+
+A semantic separator with `orientation: 'horizontal' | 'vertical'`. **CSS part:** `base`.
+
+## `lyra-breadcrumb` and `lyra-breadcrumb-item`
+
+Responsive navigation trail primitives. Breadcrumb has `accessibleLabel` (`accessible-label`);
+items have `href` and `current`. Breadcrumb slots default items; item slots default label content.
+Breadcrumb exposes `base`; item exposes `base`.
+
+## `lyra-format-number`
+
+Locale-aware `Intl.NumberFormat` output. **Properties:** `value`, `locale`, `currency`, `notation`,
+`minimumFractionDigits`, and `maximumFractionDigits`. Default slot is fallback content for a
+non-finite value.
+
+## `lyra-format-date`
+
+Locale-aware `Intl.DateTimeFormat` output. **Properties:** `date`, `locale`, `year`, `month`, `day`,
+`dateStyle`, and `timeStyle`. Default slot is fallback content for an invalid date.
+
+## `lyra-format-bytes`
+
+Locale-aware byte-size output. **Properties:** `value`, `locale`, `unitStep` (`unit-step`), and
+`decimals`.
+
+## `lyra-relative-time`
+
+Locale-aware relative time output. **Properties:** `date`, `locale`, `unit`, `numeric`, and `sync`.
+When `sync` is true the displayed value refreshes periodically.
+
+## `lyra-rating`
+
+A keyboard-accessible star rating control with slider semantics. **Properties:** `value`, `max`,
+`precision`, `readonly`, `disabled`, and `accessibleLabel` (`aria-label`). **Events:**
+`lyra-change` with `{ value }`. **CSS parts:** `base`, `star`.
+
+## `lyra-color-picker`
+
+A form-associated native color picker with label and hint chrome. **Properties:** the shared form
+properties `name`, `value`, `disabled`, and `required`, plus `label`, `hint`, and `accessibleLabel`
+(`aria-label`). **Slots:** `label`, `hint`. **Events:** composed `input` and `change`, plus
+`lyra-change` with `{ value }`. **CSS parts:** `form-control`, `label`, `input`, `hint`.
+
 ## Cross-cutting notes
 
 These apply across the whole library rather than to any one component:
 
+- **Independence and migration.** Lyra has no runtime, theme, or design-token dependency on
+  Shoelace or Web Awesome. The documented `wa-*` comparisons are migration references only; Lyra's
+  own `lyra-*` tokens, events, localization runtime, and implementation are the source of truth.
+  For a staged Web Awesome migration, map existing `--wa-*` values to `--lyra-theme-*` explicitly
+  in application CSS instead of relying on an implicit compatibility layer.
+
+- **Internationalization.** Built-in UI copy, accessible names, descriptions, validation messages,
+  status announcements, and empty/loading states resolve through `localize()` and the locale runtime.
+  Register an application catalog with `registerLyraLocale()` or override one instance with
+  `.strings`; locale fallback is exact locale, base language, then English. Date, number, byte,
+  relative-time, and calendar output uses `Intl`. Consumer data and slotted content are never
+  translated automatically.
+
+- **RTL and direction.** Direction is inherited from `dir`/`lang`; components do not force their own
+  direction. CSS logical properties mirror layout, while directional keyboard and pointer math
+  consults the effective direction. Test both LTR and RTL for any component with horizontal order,
+  start/end placement, drag deltas, or previous/next navigation.
+
+- **Accessibility and responsive behavior.** Semantic roles live on the shadow-DOM element that owns
+  them, with explicit false states for toggle/selection/expansion ARIA attributes and deliberate
+  host-name forwarding. Form-associated controls preserve `ElementInternals`, reset, validity,
+  focus, and native editing behavior. Reusable layouts respond to their allocated container, and
+  decorative/infinite motion simplifies under `prefers-reduced-motion: reduce`.
+
 - **Packaging.** `custom-elements.json` is now in `package.json`'s `files` allowlist and
   regenerated by a `prepack` script (`pnpm run manifest`) before publish, so a manifest-driven IDE/
   tooling integration (e.g. custom-elements-manifest-based autocomplete) does see an up-to-date copy