@aceshooting/lyra-ui 26.0.0 → 28.0.0

package/llms/components/lr-tool-call-block.md

@@ -38,7 +38,7 @@ progress, and `No data` only for a terminal status.
   `label` override replaces the whole header, this included
 - `callId: string = ''` (attribute `call-id`) — invocation id echoed in `lr-toggle` and
   `lr-render-error` details
-- `status: ToolCallStatus = 'pending'` (reflected, including the default) —
+- `status: ToolStatus = 'pending'` (reflected, including the default) —
   `'pending'|'running'|'success'|'error'|'denied'|'incomplete'`; selects the header verb, glyph
   and accent. `incomplete` (21.1.0) is a call that ended without a result (an interrupted stream, a
   cancelled run): it reads `Did not finish using {name}` (`toolCallBlockHeaderIncomplete`), or

package/llms/components/lr-tool-call-chip.md

@@ -49,9 +49,7 @@ its content.
   in `lr-tool-call-chip-select`'s detail so a listener can correlate the click with the call it fired for
 
 **Events:** `lr-tool-call-chip-select` (`detail: { name: string; callId: string }`) — fired on
-click or Enter/Space activation of the pill, exactly once per activation. The `lr-tool-chip-select`
-alias (deprecated since 4.0.0) was removed in 9.0.0; listen for `lr-tool-call-chip-select` instead —
-the detail is identical.
+click or Enter/Space activation of the pill, exactly once per activation.
 
 **Methods:** `focus(options?)`, `blur()`, and `click()` delegate to the internal native chip
 button, so programmatic focus/activation reaches the same semantic owner as pointer and keyboard

package/llms/components/lr-tool-result-view.md

@@ -130,8 +130,8 @@ DirectToolRendererDefinition }>` and `render?: never` — lazy loader
 
 **`ToolRenderContext`** — the shape of `render()`'s 3rd argument:
 
-- `reportStatus: (status: ToolResultStatus) => void` — reports this render's outcome without
-  throwing. `ToolResultStatus` is `'pending' | 'running' | 'success' | 'error' | 'denied' |
+- `reportStatus: (status: ToolStatus) => void` — reports this render's outcome without
+  throwing. `ToolStatus` is `'pending' | 'running' | 'success' | 'error' | 'denied' |
   'incomplete'`, the same union `<lr-tool-result-dialog>`/`<lr-tool-call-chip>` use, re-exported
   from this module. Calling
   it is entirely optional: a renderer that never calls it leaves `<lr-tool-result-view>`'s `status`
@@ -230,7 +230,7 @@ registerToolRenderer("web_search", {
   `ToolRendererDefinition`) — write the registration as a plain object literal (as in every example
   above) or annotate it as `ToolRendererDefinition` directly, so TypeScript checks the actual
   current `render`/`matches`/`load` shape, including the `context: ToolRenderContext` 3rd
-  parameter and the exact `ToolResultStatus` string union `reportStatus` accepts. A loosened/`any`
+  parameter and the exact `ToolStatus` string union `reportStatus` accepts. A loosened/`any`
   signature type-checks either way but silently gives up the compiler's ability to catch a typo'd
   status string or a dropped `context` parameter
 - `fallback` implements exactly two kinds, `"json"` and `"text"`; any _other_ runtime value

package/llms/components/lr-tool-timeline.md

@@ -23,8 +23,8 @@ primitives, with retry counts and sensitive-field redaction.
 
 - `entries: readonly ToolTimelineEntry[] = []` (attribute: false) — `ToolTimelineEntry` **extends
   `ToolInvocation` from `@aceshooting/lyra-ui/ai`** (`{ id: string; name: string; displayName?:
-string; args: Record<string, unknown>; status: ToolCallStatus; result?: unknown; error?: string }`, where
-  `ToolCallStatus = 'pending' | 'running' | 'success' | 'error' | 'denied' | 'incomplete'`) with `{ startedAt?:
+string; args: Record<string, unknown>; status: ToolStatus; result?: unknown; error?: string }`, where
+  `ToolStatus = 'pending' | 'running' | 'success' | 'error' | 'denied' | 'incomplete'`) with `{ startedAt?:
 number; endedAt?: number; retryCount?: number; redactedFields?: readonly string[]; needsApproval?: boolean;
 approved?: boolean; sourceKey?: string; icon?: string }`. `sourceKey` identifies the owning run or
   source generation when invocation ids can be reused; every expansion, activation, renderer error,

package/llms/components/lr-tooltip.md

@@ -17,7 +17,7 @@
 ## `lr-tooltip`
 
 A tooltip for a consumer-owned trigger, positioned with the shared Floating UI positioner. Which
-interactions open it is configurable as of 8.0.0; by default it is still hover and focus. Focus
+interactions open it is configurable; by default it is hover and focus. Focus
 means keyboard focus; see `trigger`.
 
 An open lr-tooltip repositions when its effective host or inherited text direction changes,
@@ -31,7 +31,7 @@ later text renders normally.
 - `open: boolean = false` (reflected) — assigning it runs the same lifecycle as `show()`/`hide()`.
   Assigning `false` also cancels a delayed open that has not fired yet, even when the tooltip is
   already closed, so a pending timer can't reopen it behind the caller's back.
-- `trigger: string = 'hover focus'` — **new in 8.0.0.** A _space-separated_ list of `hover`,
+- `trigger: string = 'hover focus'` — A _space-separated_ list of `hover`,
   `focus`, `click` and `manual`. `focus` means keyboard focus: the focused element must match
   `:focus-visible` and the last input must not have been a pointer press. Pointer, touch and
   scripted focus that follows them do not open it, but any focus inside the trigger still wires its
@@ -47,17 +47,14 @@ later text renders normally.
 - `manual: boolean = false` — equivalent to including `manual` in `trigger`; kept because it reads
   better on a tooltip that is only ever driven from script
 - `showDelay: number = 150` (attribute `show-delay`) and `hideDelay: number = 0` (attribute
-  `hide-delay`) — **breaking in 8.0.0:** the single `delay` property is gone, split into these two
-  independent milliseconds values, so a tooltip can linger after the pointer leaves without also
-  being slow to appear. `showDelay` keeps the old `delay` default of 150ms; `hideDelay` defaults to
-  `0`, so leaving the trigger now closes the tooltip at once, where 7.x's single `delay` also held
-  it open for 150ms first. A non-finite value falls back to the default; a negative one clamps to
+  `hide-delay`) — independent milliseconds values, so a tooltip can linger after the pointer leaves without also
+  being slow to appear; `hideDelay` `0` closes the tooltip at once. A non-finite value falls back to the default; a negative one clamps to
   `0` (immediate) and an oversized one to the largest delay `setTimeout` can represent, so neither
   can hang the tooltip open.
 - `placement: Placement = 'top'` (reflected) — the full Floating UI vocabulary, mirrored under RTL
 - `distance: number = 8` — anchor-offset distance in px; identical semantics to
   `<lr-popover>.distance` (both wrap the same `place()`/`offset()` middleware)
-- `skidding: number = 0` — offset along the anchor's edge, in px. New in 8.0.0.
+- `skidding: number = 0` — offset along the anchor's edge, in px.
 - `for: string = ''` (reflected) — id of an element in this tooltip's own root. It positions behind
   a direct `.anchor`; when it resolves to a live HTML element and no trigger is slotted, it also owns
   the configured interaction listeners and `aria-describedby`. A slotted trigger wins interaction
@@ -84,7 +81,7 @@ later text renders normally.
 - `withoutArrow: boolean = false` (attribute `without-arrow`, reflected),
   `arrowPlacement: 'anchor'|'start'|'end'|'center' = 'anchor'` (attribute `arrow-placement`) and
   `arrowPadding: number = 0` (attribute `arrow-padding`) — the same arrow trio `<lr-popover>`
-  documents (`llms/components/lr-popover.md`), new in 8.0.0.
+  documents (`llms/components/lr-popover.md`).
 - `content: string = ''` — plain-text tooltip content, used when nothing is slotted
 - `accessibleLabel: string = ''` (attribute **`aria-label`**) — a host `aria-label` wins by
   attribute presence, including an explicitly empty value. When the attribute is absent, an
@@ -111,8 +108,8 @@ origin-aware migration emits those tokens.
 
 **Events:** `lr-show` (cancelable), `lr-after-show`, `lr-hide` (cancelable), `lr-after-hide` — the
 same four-event contract, timing and veto semantics `<lr-popover>` documents
-(`llms/components/lr-popover.md`), and all four are
-new to this component in 8.0.0. A vetoed `lr-show` leaves the tooltip closed whether the delay
+(`llms/components/lr-popover.md`).
+A vetoed `lr-show` leaves the tooltip closed whether the delay
 elapsed, `show()` was called, or `open` was assigned.
 
 Tooltip motion resolves `tooltip.show` / `tooltip.hide` through the public animation registry.

package/llms/components/lr-tour.md

@@ -6,7 +6,7 @@
 - **Class** `LyraTour`, also available unregistered from `@aceshooting/lyra-ui/components/utility/tour/tour.class.js`
 - **Family** `components/utility/` — see `llms/index.md` for its siblings
 - **Status** `stable` since `4.0.0` — see the maturity and deprecation policy in `llms/shared.md`
-- **Release history** [CHANGELOG.md](../../CHANGELOG.md); family-wide breaking-change summaries: [utility](https://github.com/aceshooting/lyra-ui/blob/main/packages/lyra-ui/llms/utility.md)
+- **Release history** [CHANGELOG.md](../../CHANGELOG.md)
 - **Deprecations** none
 - **Optional peers** none
 - **Themeable via** 12 parts, 11 custom properties — see this component's own `@csspart`/`@cssprop` list below
@@ -117,7 +117,7 @@ shared ceiling that keeps any floating surface inside a narrow viewport. `lr-tou
 retuning `--lr-theme-popover-viewport-clamp` once at `:root` narrows or widens all three together
 rather than per component.
 
-`--lr-positioning-strategy` (16.0.0) — the step popover reads this same cascading `absolute`/`fixed`
+`--lr-positioning-strategy` — the step popover reads this same cascading `absolute`/`fixed`
 override documented on `<lr-popover>` when a step is (re)positioned, falling back to its own `fixed`
 default when nothing is set. There is no per-instance `positioning-strategy` property on `<lr-tour>`;
 set the custom property on `:root`, a theme, or one clipping ancestor to change every unset tour

package/llms/components/lr-tree-item.md

@@ -6,7 +6,7 @@
 - **Class** `LyraTreeItem`, also available unregistered from `@aceshooting/lyra-ui/components/data/tree/tree-item.class.js`
 - **Family** `components/data/` — see `llms/index.md` for its siblings
 - **Status** `stable` since `8.0.0` — see the maturity and deprecation policy in `llms/shared.md`
-- **Release history** [CHANGELOG.md](../../CHANGELOG.md); family-wide breaking-change summaries: [data](https://github.com/aceshooting/lyra-ui/blob/main/packages/lyra-ui/llms/data.md)
+- **Release history** [CHANGELOG.md](../../CHANGELOG.md)
 - **Deprecations** none
 - **Optional peers** none
 - **Themeable via** 28 parts, 26 custom properties — see `lr-tree.md`

package/llms/components/lr-tree.md

@@ -6,7 +6,7 @@
 - **Class** `LyraTree`, also available unregistered from `@aceshooting/lyra-ui/components/data/tree/tree.class.js`
 - **Family** `components/data/` — see `llms/index.md` for its siblings
 - **Status** `stable` since `4.0.0` — see the maturity and deprecation policy in `llms/shared.md`
-- **Release history** [CHANGELOG.md](../../CHANGELOG.md); family-wide breaking-change summaries: [data](https://github.com/aceshooting/lyra-ui/blob/main/packages/lyra-ui/llms/data.md)
+- **Release history** [CHANGELOG.md](../../CHANGELOG.md)
 - **Deprecations** none
 - **Optional peers** none
 - **Themeable via** 4 parts, 5 custom properties — see this component's own `@csspart`/`@cssprop` list below

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

@@ -6,7 +6,7 @@
 - **Class** `LyraUnitPicker`, also available unregistered from `@aceshooting/lyra-ui/components/forms/unit-picker/unit-picker.class.js`
 - **Family** `components/forms/` — see `llms/index.md` for its siblings
 - **Status** `experimental` since `25.5.0` — see the maturity and deprecation policy in `llms/shared.md`
-- **Release history** [CHANGELOG.md](../../CHANGELOG.md); family-wide breaking-change summaries: [forms](https://github.com/aceshooting/lyra-ui/blob/main/packages/lyra-ui/llms/forms.md)
+- **Release history** [CHANGELOG.md](../../CHANGELOG.md)
 - **Deprecations** none
 - **Optional peers** none
 - **Themeable via** 11 parts, 0 custom properties — see this component's own `@csspart`/`@cssprop` list below

package/llms/components/lr-usage-badge.md

@@ -37,9 +37,7 @@ pre-formatted cost (e.g. `"$0.012"`), rendered verbatim. `latencyMs?: number` (a
 algorithm (which has no minutes/hours tier) in both the visible strip and the tooltip row; mirrors
 `lr-activity-feed`'s `formatTimestamp` convention. `abbreviate: boolean = false` (reflected) — token
 counts render via `Intl.NumberFormat` `notation: 'compact'` (`12345 -> "12K"`); the tooltip always
-shows full grouped figures. This badge has no density mode: the old `compact` spelling of this
-property was removed in 9.0.0 (it collided with `compact`'s density meaning everywhere else in the
-library) — rename `compact` to `abbreviate`; a stale `compact` attribute is inert. `summary: string =
+shows full grouped figures. This badge has no density mode: use `abbreviate` for compact counts; a `compact` attribute is inert. `summary: string =
 ''` supplies visible fallback text when no built-in segment is present.
 
 **Slots:** `summary` — visible summary when no built-in segment is set (takes precedence over the

package/llms/components/lr-video.md

@@ -53,8 +53,7 @@ control-bar play toggle is hidden until the poster is dismissed.
 
 **Methods:** `getState(): VideoState` returns a fresh synchronous
 `{ playing, currentTime, duration, volume, muted, playbackRate }` snapshot. `VideoState` is the
-canonical upstream-compatible authoring type; the redundant `LyraVideoState` alias is removed in
-v9;
+canonical upstream-compatible authoring type.
 `getVideoElement(): HTMLVideoElement | undefined` returns the private native element after mount;
 `play(): Promise<void>` returns the exact native promise and preserves its rejection; `pause()`,
 `togglePlay()`, `toggleMute()`, `seek(time)`, `setPlaybackRate(rate)`, and `setVolume(volume)` proxy

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

@@ -6,7 +6,7 @@
 - **Class** `LyraVirtualList`, also available unregistered from `@aceshooting/lyra-ui/components/layout/virtual-list/virtual-list.class.js`
 - **Family** `components/layout/` — see `llms/index.md` for its siblings
 - **Status** `stable` since `4.0.0` — see the maturity and deprecation policy in `llms/shared.md`
-- **Release history** [CHANGELOG.md](../../CHANGELOG.md); family-wide breaking-change summaries: [layout](https://github.com/aceshooting/lyra-ui/blob/main/packages/lyra-ui/llms/layout.md)
+- **Release history** [CHANGELOG.md](../../CHANGELOG.md)
 - **Deprecations** none
 - **Optional peers** none
 - **Themeable via** 5 parts, 12 custom properties — see this component's own `@csspart`/`@cssprop` list below

package/llms/components/lr-visually-hidden.md

@@ -6,7 +6,7 @@
 - **Class** `LyraVisuallyHidden`, also available unregistered from `@aceshooting/lyra-ui/components/utility/visually-hidden/visually-hidden.class.js`
 - **Family** `components/utility/` — see `llms/index.md` for its siblings
 - **Status** `stable` since `8.0.0` — see the maturity and deprecation policy in `llms/shared.md`
-- **Release history** [CHANGELOG.md](../../CHANGELOG.md); family-wide breaking-change summaries: [utility](https://github.com/aceshooting/lyra-ui/blob/main/packages/lyra-ui/llms/utility.md)
+- **Release history** [CHANGELOG.md](../../CHANGELOG.md)
 - **Deprecations** none
 - **Optional peers** none
 - **Themeable via** nothing component-specific — inherits only the shared surface

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

@@ -70,7 +70,7 @@ become bounded clone-owned frozen snapshots; create and reassign a new array aft
 affordances at all. `label: string = ''`,
 `hint: string = ''`, `errorText: string = ''` (attribute `error-text`), `placeholder: string = ''`,
 `spellcheck: boolean = true` (string-aware converter, same as `lr-model-select`), `autocapitalize:
-string = ''`, `autoCorrect: string = ''` (attribute `autocorrect`), `autocomplete: string = 'off'`,
+string = ''`, `autocorrect: boolean = true`, `autocomplete: string = 'off'`,
 `inputMode: string = ''` (attribute `inputmode`), `enterKeyHint: string = ''` (attribute
 `enterkeyhint`), and `open: boolean = false` (reflected) — all mirror `lr-model-select`'s
 identically-named properties. `size: LyraSize = 'm'` (reflected) selects the shared

package/llms/components/lr-widget.md

@@ -6,7 +6,7 @@
 - **Class** `LyraWidget`, also available unregistered from `@aceshooting/lyra-ui/components/layout/widget/widget.class.js`
 - **Family** `components/layout/` — see `llms/index.md` for its siblings
 - **Status** `stable` since `4.0.0` — see the maturity and deprecation policy in `llms/shared.md`
-- **Release history** [CHANGELOG.md](../../CHANGELOG.md); family-wide breaking-change summaries: [layout](https://github.com/aceshooting/lyra-ui/blob/main/packages/lyra-ui/llms/layout.md)
+- **Release history** [CHANGELOG.md](../../CHANGELOG.md)
 - **Deprecated event** `lr-collapse-change` since `26.0.0`; use event `@lr-toggle`; removal not before `28.0.0` — The shared toggle event uses expanded polarity while the older event retains its collapsed field; consumers must review payload handling.
 - **Deprecated event** `lr-collapse-request` since `26.0.0`; use event `@lr-toggle-request`; removal not before `28.0.0` — The shared cancelable request uses expanded polarity while the older event retains its collapsed field; consumers must review payload handling.
 - **Deprecated slot** `icon` since `26.0.0`; use slot `slot="start"`; removal not before `28.0.0` — The title glyph uses the shared start slot vocabulary; existing icon slot content remains rendered during migration.

package/llms/components/lr-word-cloud.md

@@ -6,7 +6,7 @@
 - **Class** `LyraWordCloud`, also available unregistered from `@aceshooting/lyra-ui/components/data/word-cloud/word-cloud.class.js`
 - **Family** `components/data/` — see `llms/index.md` for its siblings
 - **Status** `stable` since `4.0.0` — see the maturity and deprecation policy in `llms/shared.md`
-- **Release history** [CHANGELOG.md](../../CHANGELOG.md); family-wide breaking-change summaries: [data](https://github.com/aceshooting/lyra-ui/blob/main/packages/lyra-ui/llms/data.md)
+- **Release history** [CHANGELOG.md](../../CHANGELOG.md)
 - **Deprecations** none
 - **Optional peers** none
 - **Themeable via** 12 parts, 8 custom properties — see this component's own `@csspart`/`@cssprop` list below

package/llms/components/lr-zoomable-frame.md

@@ -53,12 +53,7 @@ a focused zoom control.
   `contentDocument: Document | null`. Both content accessors return `null` while detached;
   `contentDocument` also returns `null` across an origin boundary.
 
-**Authoring type:** `LyraZoomableFrameLoading`. The former unprefixed
-`ZoomableFrameLoading` name is removed in v9 rather than retained as an alias.
-The former deep-class-module implementation exports `DEFAULT_ZOOM_LEVELS`,
-`DEFAULT_IFRAME_SANDBOX`, `safeZoomableFrameSrc()`, and `safeZoomableFrameSandbox()` are also
-removed in v9. They were never part of the registration, root, or documented component surface;
-configure the corresponding public properties instead of depending on sink-policy internals.
+**Authoring type:** `LyraZoomableFrameLoading`.
 
 **Methods:** `zoomIn()` selects the nearest configured level above the current value;
 `zoomOut()` selects the nearest below it. The control group also accepts `+`/`=` and `-`/`_` while one

package/llms/migration.md

@@ -83,6 +83,8 @@ review removed names before running the migrated application.
 | `PROPERTY_CHANGE_REVIEW` | A property keeps its name but changes its accepted values or behavior; review the assignment without rewriting an ambiguous runtime value. |
 | `DEPRECATED_MEMBER_REVIEW`, `DEPRECATED_CONTENT_REVIEW` | A deprecated member, tag or kind of slotted content without a mechanical replacement. |
 | `DEPRECATED_MODULE_REVIEW` | A deprecated module, stylesheet, named export, window event or root attribute. Its replacement needs a semantic review. |
+| `GLOBAL_REVIEW` | A moved package specifier, removed root export or removed localization key that cannot be rewritten safely. |
+| `THEME_SCOPE_CSS_INPUT_REVIEW`, `THEME_SCOPE_OUTPUT_REVIEW`, `THEME_SCOPE_DYNAMIC_INPUT_REVIEW`, `THEME_SCOPE_REPEATED_REVIEW`, `THEME_SCOPE_DOUBLE_LAYER_REVIEW` | The `theme-scopes` rule found an input, shared output or marker that needs a theme scope by hand, or `tokens-root.css` imported next to `theme.css`, which already carries the layer. |
 | `MODULE_NAMESPACE_REVIEW` | A namespace, dynamic import or CommonJS module access whose exported bindings need review. |
 | `RENAME_CONFLICT_REVIEW` | The element already binds the new name, or the same receiver already listens to it with the same handler. |
 | `UNUSED_ACKNOWLEDGEMENT` | An acknowledgement comment matches no report. |
@@ -818,6 +820,8 @@ review removed names before running the migrated application.
 | `PROPERTY_CHANGE_REVIEW` | A property keeps its name but changes its accepted values or behavior; review the assignment without rewriting an ambiguous runtime value. |
 | `DEPRECATED_MEMBER_REVIEW`, `DEPRECATED_CONTENT_REVIEW` | A deprecated member, tag or kind of slotted content without a mechanical replacement. |
 | `DEPRECATED_MODULE_REVIEW` | A deprecated module, stylesheet, named export, window event or root attribute. Its replacement needs a semantic review. |
+| `GLOBAL_REVIEW` | A moved package specifier, removed root export or removed localization key that cannot be rewritten safely. |
+| `THEME_SCOPE_CSS_INPUT_REVIEW`, `THEME_SCOPE_OUTPUT_REVIEW`, `THEME_SCOPE_DYNAMIC_INPUT_REVIEW`, `THEME_SCOPE_REPEATED_REVIEW`, `THEME_SCOPE_DOUBLE_LAYER_REVIEW` | The `theme-scopes` rule found an input, shared output or marker that needs a theme scope by hand, or `tokens-root.css` imported next to `theme.css`, which already carries the layer. |
 | `MODULE_NAMESPACE_REVIEW` | A namespace, dynamic import or CommonJS module access whose exported bindings need review. |
 | `RENAME_CONFLICT_REVIEW` | The element already binds the new name, or the same receiver already listens to it with the same handler. |
 | `UNUSED_ACKNOWLEDGEMENT` | An acknowledgement comment matches no report. |
@@ -1538,6 +1542,8 @@ the old name keeps working meanwhile.
 | `PROPERTY_CHANGE_REVIEW` | A property keeps its name but changes its accepted values or behavior; review the assignment without rewriting an ambiguous runtime value. |
 | `DEPRECATED_MEMBER_REVIEW`, `DEPRECATED_CONTENT_REVIEW` | A deprecated member, tag or kind of slotted content without a mechanical replacement. |
 | `DEPRECATED_MODULE_REVIEW` | A deprecated module, stylesheet, named export, window event or root attribute. Its replacement needs a semantic review. |
+| `GLOBAL_REVIEW` | A moved package specifier, removed root export or removed localization key that cannot be rewritten safely. |
+| `THEME_SCOPE_CSS_INPUT_REVIEW`, `THEME_SCOPE_OUTPUT_REVIEW`, `THEME_SCOPE_DYNAMIC_INPUT_REVIEW`, `THEME_SCOPE_REPEATED_REVIEW`, `THEME_SCOPE_DOUBLE_LAYER_REVIEW` | The `theme-scopes` rule found an input, shared output or marker that needs a theme scope by hand, or `tokens-root.css` imported next to `theme.css`, which already carries the layer. |
 | `MODULE_NAMESPACE_REVIEW` | A namespace, dynamic import or CommonJS module access whose exported bindings need review. |
 | `RENAME_CONFLICT_REVIEW` | The element already binds the new name, or the same receiver already listens to it with the same handler. |
 | `UNUSED_ACKNOWLEDGEMENT` | An acknowledgement comment matches no report. |
@@ -1582,6 +1588,103 @@ hydration compares template strings.
 | `<lr-widget>` | event | `lr-collapse-request` | `@lr-toggle-request` |
 | `<lr-widget>` | slot | `icon` | `slot="start"` |
 
+## Migrating from Lyra 26 to Lyra 27 (`--origin=lyra-v26`)
+
+Lyra 26 minor releases and Lyra 27 rename some Lyra-only attributes, properties, events, CSS parts,
+custom properties and slots. Each previous name keeps working as a deprecated alias until
+Lyra 29 removes it. Names mirrored from Web Awesome or Shoelace, and their defaults, never
+change. Run the CLI of the installed package after upgrading, within Lyra 26 or to Lyra 27. It
+applies only the entries the installed release ships, so running it again after a later upgrade
+picks up the rest:
+
+```bash
+npx lyra-ui-migrate --origin=lyra-v26 --diff src > lyra-v26.patch
+npx lyra-ui-migrate --origin=lyra-v26 --check --report=lyra-v26-migration.json src
+```
+
+`--diff` prints a patch and writes nothing. The profile rewrites a name only where the rewrite
+cannot change what the site reaches: attribute, property and slot bindings on the component in
+HTML, Lit, JSX, Vue, Svelte and Angular templates; `exportparts` and `::part()` or attribute
+selectors that name the component; and calls rooted at `querySelector('lr-…')`, `closest()` or
+`createElement()`. Events bubble and custom properties inherit, so a listener moves only when no
+other component already dispatches the new name, and an unowned listener or any custom-property
+use only when, in addition, every component with the old name renamed it the same way and the
+scanned code never dispatches the old name itself. Everything else is reported with a location;
+the old name keeps working meanwhile.
+
+| Code | Reported when |
+|---|---|
+| `RENAME_REVIEW` | An old name at a site that does not prove its component, or where another component keeps the name. |
+| `RENAME_TARGET_SHARED_REVIEW` | The new name is already used by another component, so renaming would widen the site. |
+| `NAME_GAINED_OWNER_REVIEW` | A listener, `::part()` selector or declaration of a name that more components use after the upgrade. |
+| `POLARITY_REVIEW` | A boolean replaced by its inverse is bound, assigned or selected, or set statically where a framework assigns properties. |
+| `DETAIL_SHAPE_REVIEW` | A listener may receive an event whose detail changed; details cannot be aliased. |
+| `RETIRED_EVENT_REVIEW` | A listener or event-name string may use an alias already removed in the target release; review its replacement and listener reach. |
+| `PROPERTY_CHANGE_REVIEW` | A property keeps its name but changes its accepted values or behavior; review the assignment without rewriting an ambiguous runtime value. |
+| `DEPRECATED_MEMBER_REVIEW`, `DEPRECATED_CONTENT_REVIEW` | A deprecated member, tag or kind of slotted content without a mechanical replacement. |
+| `DEPRECATED_MODULE_REVIEW` | A deprecated module, stylesheet, named export, window event or root attribute. Its replacement needs a semantic review. |
+| `GLOBAL_REVIEW` | A moved package specifier, removed root export or removed localization key that cannot be rewritten safely. |
+| `THEME_SCOPE_CSS_INPUT_REVIEW`, `THEME_SCOPE_OUTPUT_REVIEW`, `THEME_SCOPE_DYNAMIC_INPUT_REVIEW`, `THEME_SCOPE_REPEATED_REVIEW`, `THEME_SCOPE_DOUBLE_LAYER_REVIEW` | The `theme-scopes` rule found an input, shared output or marker that needs a theme scope by hand, or `tokens-root.css` imported next to `theme.css`, which already carries the layer. |
+| `MODULE_NAMESPACE_REVIEW` | A namespace, dynamic import or CommonJS module access whose exported bindings need review. |
+| `RENAME_CONFLICT_REVIEW` | The element already binds the new name, or the same receiver already listens to it with the same handler. |
+| `UNUSED_ACKNOWLEDGEMENT` | An acknowledgement comment matches no report. |
+
+After reviewing a site, add a comment containing `lyra-migrate-reviewed: CODE:name` (for example
+`DETAIL_SHAPE_REVIEW:lr-close`) on the reported line, alone on the line above it, or directly before
+the element's opening tag. Acknowledged reports no longer fail `--check`. Re-running the profile
+is idempotent. Templates rendered on the server must be re-rendered after migrating, because Lit
+hydration compares template strings.
+
+| Component | Attribute | Inserted when absent to keep the Lyra 26 default |
+|---|---|---|
+| `<lr-prompt-studio>` | `heading-level` | `heading-level="2"` |
+| `<lr-task-list>` | `heading-level` | `heading-level="3"` |
+
+| Component | Event | Detail change in Lyra 27 (reported, never rewritten) |
+|---|---|---|
+| `<lr-tool-approval-dialog>` | `lr-deny-request` | The detail is now { waitUntil } instead of null. |
+
+| Component | Property | Semantic change in Lyra 27 (reported, never rewritten) |
+|---|---|---|
+| `<lr-context-inspector>` | `label` | label="" is now honored verbatim (no fallback to the heading or localized default); omit label to keep the default. |
+| `<lr-date-input>` | `autocorrect` | The string autoCorrect property is gone: autocorrect is a boolean (set .autocorrect=${false}, or autocorrect="off" in HTML), so a string assigned to it, or a framework binding of the string "off", is truthy. |
+| `<lr-model-select>` | `autocorrect` | The string autoCorrect property is gone: autocorrect is a boolean (set .autocorrect=${false}, or autocorrect="off" in HTML), so a string assigned to it, or a framework binding of the string "off", is truthy. |
+| `<lr-phone-input>` | `autocorrect` | The string autoCorrect property is gone: autocorrect is a boolean (set .autocorrect=${false}, or autocorrect="off" in HTML), so a string assigned to it, or a framework binding of the string "off", is truthy. |
+| `<lr-prompt-studio>` | `label` | label="" is now honored verbatim (no fallback to the heading or localized default); omit label to keep the default. |
+| `<lr-voice-picker>` | `autocorrect` | The string autoCorrect property is gone: autocorrect is a boolean (set .autocorrect=${false}, or autocorrect="off" in HTML), so a string assigned to it, or a framework binding of the string "off", is truthy. |
+
+Entries no component owns. A module specifier is rewritten where it is provably an import, re-export,
+dynamic import, `require()`, CSS `@import`, `<link href>`/`<script src>` or a `node_modules/` path, and in any
+string of a JSON file such as `.vscode/settings.json` (pass it as an explicit target); anywhere else it is
+reported. A removed root export is re-bound as `New as Old` in the import clause, so local references keep
+working; other uses (a deep import, a namespace member) and removed localization keys are reported as
+`GLOBAL_REVIEW`, acknowledged as `lyra-migrate-reviewed: GLOBAL_REVIEW:<name>`.
+
+| Kind | From | To | Handling |
+|---|---|---|---|
+| css-property | `--lr-eval-dataset-search-*` | the lr-input tokens (--lr-input-* and --lr-form-control-*) | Reported only. lr-eval-dataset's search field is a composed lr-input. |
+| export | `ToolCallStatus (package root)` | `ToolStatus` | Import clause re-bound; other uses reported. One ToolStatus union replaces the per-component status types; import it from the package root. |
+| export | `ToolResultStatus (package root)` | `ToolStatus` | Import clause re-bound; other uses reported. One ToolStatus union replaces the per-component status types; import it from the package root. |
+| locale-key | `evaluationRunStatusCancelled` | `agentRunStatusCancelled` | Reported only. lr-evaluation-run reads the shared agentRunStatus* keys; a string override under the old key no longer applies. |
+| locale-key | `evaluationRunStatusIdle` | `agentRunStatusIdle` | Reported only. lr-evaluation-run reads the shared agentRunStatus* keys; a string override under the old key no longer applies. |
+| locale-key | `evaluationRunStatusWaitingApproval` | `agentRunStatusWaitingApproval` | Reported only. lr-evaluation-run reads the shared agentRunStatus* keys; a string override under the old key no longer applies. |
+| locale-key | `evaluationRunStatusWaitingInput` | `agentRunStatusWaitingInput` | Reported only. lr-evaluation-run reads the shared agentRunStatus* keys; a string override under the old key no longer applies. |
+| locale-key | `videoPlaybackSpeed` | `avPlayerPlaybackRate` | Reported only. lr-video names its speed select with the key lr-av-player shares; a string override under the old key no longer applies. |
+| module | `@aceshooting/lyra-ui/custom-elements.json` | `@aceshooting/lyra-ide/custom-elements.json` | Rewritten. Install @aceshooting/lyra-ide at the same version; the editor data moved out of @aceshooting/lyra-ui. |
+| module | `@aceshooting/lyra-ui/translations/*` | `@aceshooting/lyra-translations/*` | Rewritten except `@aceshooting/lyra-ui/translations/pseudo/`. Install @aceshooting/lyra-translations at the same version; the pseudo-locales stay in @aceshooting/lyra-ui. |
+| module | `@aceshooting/lyra-ui/vscode-css-data.json` | `@aceshooting/lyra-ide/vscode-css-data.json` | Rewritten. Install @aceshooting/lyra-ide at the same version; the editor data moved out of @aceshooting/lyra-ui. |
+| module | `@aceshooting/lyra-ui/vscode-html-data.json` | `@aceshooting/lyra-ide/vscode-html-data.json` | Rewritten. Install @aceshooting/lyra-ide at the same version; the editor data moved out of @aceshooting/lyra-ui. |
+| module | `@aceshooting/lyra-ui/web-types.json` | `@aceshooting/lyra-ide/web-types.json` | Rewritten. Install @aceshooting/lyra-ide at the same version; the editor data moved out of @aceshooting/lyra-ui. |
+| part | `<lr-connector-manager> ::part(action)` | Style the label through action-label and the inner button through action-base. | Reported only. action is now the lr-button host. |
+| part | `<lr-permission-grant> ::part(decision)` | Style the label through decision-label and the inner button through decision-base. | Reported only. decision is now the lr-button host. |
+| part | `<lr-eval-dataset> ::part(search-clear)` | Style the clear button through part search-clear on the field, and the native input through search-input-field. | Reported only. search-clear is now the composed lr-input clear button. |
+| part | `<lr-eval-dataset> ::part(search-input)` | Style the native input through search-input-field. | Reported only. search-input is now the lr-input host, not the native input. |
+
+This profile also runs the structural rule `theme-scopes`, the same implementation as `--rule=<name>`.
+It adds `data-lr-theme-scope` to elements whose inline style sets a token-layer input, and reports dynamic inputs,
+markers inside loops, and stylesheet rules that set an input or a shared output outside a theme scope
+(`THEME_SCOPE_*_REVIEW`, acknowledged like any other code).
+
 ## Upstream-protected compatibility spellings
 
 These 8 legacy spellings remain supported while their corresponding Web Awesome or Shoelace surface publishes them. Prefer the current Lyra spelling for new code. Their recorded `removalNotBefore` value is a minimum, not an automatic removal date or permission to remove a still-mirrored spelling.
@@ -1635,7 +1738,7 @@ The pinned Web Awesome manifest is authoritative for this inventory; only rows m
 | `<wa-color-picker>` | `<lr-color-picker>` | `rewritten` | Automatic: tag/import plus events: wa-after-hide → lr-after-hide; events: wa-after-show → lr-after-show; events: wa-hide → lr-hide; events: wa-invalid → lr-invalid; events: wa-show → lr-show. Equivalent surface representation: name defaults null ≡ ; no source rewrite. |
 | `<wa-combobox>` | `<lr-combobox>` | `warning-required` | Manual: Native input/change notifications on lr-combobox are bubbling, composed Event instances without a detail payload. Its lr-input/lr-change aliases carry the frozen readonly value, previousValue and row data, narrowed by the picker value generic; migrated handlers reading or mutating upstream CustomEvent detail must use the prefixed aliases and review the narrower single-select type. Its appearance also accepts the full shared LyraAppearance vocabulary (accent and plain in addition to the three upstream values) since 20.0.0; every upstream value keeps its meaning, so only exhaustive TypeScript switches over the narrower upstream union need review. |
 | `<wa-comparison>` | `<lr-image-comparer>` | `exact` | Automatic: tag and supported side-effect registration import. Before/after slotted surfaces with a keyboard-accessible range divider. |
-| `<wa-copy-button>` | `<lr-copy-button>` | `rewritten` | Automatic: tag/import plus events: wa-copy → lr-copy; events: wa-error → lr-error. |
+| `<wa-copy-button>` | `<lr-copy-button>` | `rewritten` | Automatic: tag/import plus events: wa-copy → lr-copy; events: wa-error → lr-error; insert feedback-duration=1000. Equivalent surface representation: feedbackDuration defaults 1000 ≡ 1500; no source rewrite. |
 | `<wa-data-grid>` | `<lr-data-grid>` | `warning-required` | Manual: Lyra snapshots collection inputs and event details synchronously into frozen readonly values, removes the redundant wa-data-request alias, and deprecates the unprefixed request event in favor of lr-request. Migrated code that mutates arrays or event details in place, assigns derived collections, listens for the removed alias, or relies on the unprefixed request event must be reviewed. |
 | `<wa-date-input>` | `<lr-date-input>` | `warning-required` | Manual: Since 20.0.0 lr-date-input accepts the full shared LyraAppearance vocabulary (accent and plain in addition to the three upstream values). Every upstream value keeps its meaning, so migrated markup is unaffected; only exhaustive TypeScript switches over the narrower upstream union need review. Its lr-hide is cancelable except when disabling the field or making it readonly closes an open popup, which a listener cannot veto; handlers that rely on vetoing every hide need review. |
 | `<wa-date-picker>` | `<lr-date-picker>` | `rewritten` | Automatic: tag/import plus events: wa-focus-day → lr-focus-day; events: wa-view-change → lr-view-change. |
@@ -1721,7 +1824,7 @@ Shoelace relationships are classified independently; a same-suffix tag is never
 | `<sl-carousel-item>` | `<lr-carousel-item>` | `exact` | Automatic: tag and supported side-effect registration import. Optional semantic slide wrapper for carousel content. |
 | `<sl-checkbox>` | `<lr-checkbox>` | `warning-required` | Manual: Lyra uses the checked attribute as the reset default while Shoelace reflects the live checked state; migration leaves the use unchanged and reports the reflection-sensitive CSS, observer, serialization, and property-write difference. |
 | `<sl-color-picker>` | `<lr-color-picker>` | `rewritten` | Automatic: tag/import plus events: sl-blur → blur; events: sl-change → lr-change; events: sl-focus → focus; events: sl-input → lr-input; events: sl-invalid → lr-invalid. Equivalent surface representation: form defaults  ≡ null; size defaults medium ≡ m; no source rewrite. |
-| `<sl-copy-button>` | `<lr-copy-button>` | `rewritten` | Automatic: tag/import plus events: sl-copy → lr-copy; events: sl-error → lr-error. |
+| `<sl-copy-button>` | `<lr-copy-button>` | `rewritten` | Automatic: tag/import plus events: sl-copy → lr-copy; events: sl-error → lr-error; insert feedback-duration=1000. Equivalent surface representation: feedbackDuration defaults 1000 ≡ 1500; no source rewrite. |
 | `<sl-details>` | `<lr-details>` | `rewritten` | Automatic: tag/import plus events: sl-after-hide → lr-after-hide; events: sl-after-show → lr-after-show; events: sl-hide → lr-hide; events: sl-show → lr-show. |
 | `<sl-dialog>` | `<lr-dialog>` | `warning-required` | Manual: Pinned runtime evidence shows Shoelace emits non-cancelable state-change lifecycle notifications while Lyra provides synchronous pre-state veto events; automatic migration therefore requires review of listener timing and preventDefault() behavior. |
 | `<sl-divider>` | `<lr-divider>` | `exact` | Automatic: tag and supported side-effect registration import. Horizontal or vertical semantic separator. |

package/llms/peers.md

@@ -2,14 +2,14 @@
 
 # Optional peer dependencies
 
-All 29 peers are **optional**: nothing here is needed to install or use the library,
+All 30 peers are **optional**: nothing here is needed to install or use the library,
 but they have two deliberately different roles.
 
 **Framework declaration peers (3).** React, Svelte, and Vue are compile-time peers
 only when a project imports their matching opt-in declaration entry. Those entry points emit empty
 JavaScript, no component imports these frameworks, and Lyra ships no runtime wrapper.
 
-**Component-loaded peers (26).** No component imports one eagerly. Install a
+**Component-loaded peers (27).** No component imports one eagerly. Install a
 peer only when you use a component that needs it.
 
 **How they load.** Most component-loaded peers resolve through a dynamic `import()` on first use.
@@ -38,6 +38,7 @@ for the page.
 | Peer | Range | Needed by |
 |---|---|---|
 | `@aceshooting/lyra-flags` | `^2.3.0` | _(loaded by a shared internal module)_ |
+| `@aceshooting/lyra-translations` | `^28.0.0` | _(not referenced by any component)_ |
 | `@aiden0z/pptx-renderer` | `^1.3.0` | `lr-pptx-viewer` |
 | `@sgratzl/chartjs-chart-boxplot` | `^4.0.0` | `lr-box-plot` |
 | `chart.js` | `^4.0.1` | `lr-bar-chart`, `lr-box-plot`, `lr-bubble-chart`, `lr-chart`, `lr-doughnut-chart`, `lr-histogram`, `lr-line-chart`, `lr-pie-chart`, `lr-polar-area-chart`, `lr-radar-chart`, `lr-scatter-chart` |

package/llms/shared/ai-and-peers.md

@@ -46,7 +46,7 @@ import {
   validates them on `tool-upsert` events and `tool-call` parts: a non-finite or non-number time, or
   a `redactedFields` that is not an array of at most 100 strings of at most 4,096 characters, fails
   the event as `invalid_stream_event`.
-- **Tool display name and incomplete calls** (21.1.0) — `ToolInvocation.displayName` is the
+- **Tool display name and incomplete calls** — `ToolInvocation.displayName` is the
   application's own, already-translated tool label; `<lr-message-parts>` (both `tool-display`
   modes) and `<lr-tool-timeline>` show it in place of `name`, which still selects the result
   renderer. `status: 'incomplete'` marks a call that ended without a result (an interrupted stream,
@@ -118,7 +118,7 @@ preferred in production.
 
 ## Optional peer dependencies
 
-All 29 peers are optional, in two groups. The 26 component-facing peers remain outside the default
+All 30 peers are optional, in two groups. The 27 component-facing peers remain outside the default
 install; components load them on demand where applicable. React, Svelte, and Vue are
 compile-time-only peers for their matching
 opt-in declaration entries (`custom-elements-jsx`, `svelte`, and `vue`): those entries emit empty

package/llms/shared/events-and-types.md

@@ -58,7 +58,7 @@ Those nested detail fields are separate from deprecated event names and are not
   import type {} from "@aceshooting/lyra-ui/vue";
   import type {} from "@aceshooting/lyra-ui/svelte";
   ```
-  All three are generated from `custom-elements.json` and type the documented properties,
+  All three are generated from the Custom Elements Manifest and type the documented properties,
   attribute aliases, events, element refs, and CSS custom properties. Their emitted JavaScript is
   empty: they are declaration merging, not runtime wrappers, and they do not register any tag.
 - **Delegated, `document` and `window` listeners: `@aceshooting/lyra-ui/events`.** Component events
@@ -842,6 +842,16 @@ These named interfaces and helper signatures are available to typed integrations
   `resolveCanvasColor(/* public names: scope, color, fallback */): unknown`
   `resolveCanvasColors(/* public names: scope, colors, fallback */): unknown`
 
+- **`internal-document-tokens-contracts`** — Shared utility contracts.
+  `adoptLyraTokens(root: Document | ShadowRoot): void`
+  Adopts the document token layer into a document or shadow root. Idempotent; see "Application
+  shadow roots" in the styles and tokens guide for when a root needs it.
+
+- **`internal-theme-scopes-contracts`** — Shared utility contracts.
+  `findUnscopedThemeInputs(root?: Document | DocumentFragment | Element): Element[]`
+  Lists elements that set an inline `--lr-theme-*` input the layer consumes without being a theme
+  scope. Reads inline styles only and logs nothing.
+
 - **`internal-localization-runtime-contracts`** — Shared utility contracts.
   `getLyraLocaleDirection(/* public names: locale */): unknown`
   `getLyraLocale(): unknown`
@@ -1576,13 +1586,46 @@ These named interfaces and helper signatures are available to typed integrations
 
 - **`testing-happy-dom-shims-contracts`** — Shared utility contracts.
   `installHappyDomFormAssociatedShims(): unknown`
+  `installHappyDomShadowFocusShim(): unknown`
+  `flattenCascadeLayers(/* public names: css */): unknown`
+  `installHappyDomAriaControlsShim(/* public names: proto */): unknown`
+  `installHappyDomCascadeLayerShim(/* public names: proto, misbehaves */): unknown`
+  `installHappyDomShims(): unknown`
   `installStubInternalsForTest(/* public names: host */): unknown`
 
+- **`testing-jsdom-shims-contracts`** — Shared utility contracts.
+  `JsdomAdoptedStyleSheetsTargets {
+  documentPrototype?: object;
+  shadowRootPrototype?: object;
+  styleSheetPrototype?: object;
+  isJsdom?: () => boolean;
+}`
+  `installJsdomAdoptedStyleSheetsShim(targets?: JsdomAdoptedStyleSheetsTargets): () => void`
+  `JsdomFormAssociatedTargets {
+  internalsPrototype?: object;
+  elementPrototype?: object;
+  isJsdom?: () => boolean;
+}`
+  `installJsdomFormAssociatedShim(targets?: JsdomFormAssociatedTargets): () => void`
+  `installJsdomShims(): () => void`
+  See "jsdom: `installJsdomShims()`" above for the full contract.
+
 - **`testing-interaction-drivers-contracts`** — Shared utility contracts.
   `chooseOption(/* public names: owner, value */): unknown`
   `submitConfirmDecision(/* public names: owner, decision */): unknown`
   `toggleSwitch(/* public names: switchEl */): unknown`
   `activateStep(/* public names: stepper, target */): unknown`
+  `chooseSwatch(/* public names: picker, value */): unknown`
+  `chooseCurrency(/* public names: picker, code */): unknown`
+  `PopoverDriverOptions {
+  timeoutMs: unknown;
+}`
+  `ClosePopoverOptions {
+  via: unknown;
+  timeoutMs: unknown;
+}`
+  `openPopover(/* public names: popover, options */): unknown`
+  `closePopover(/* public names: popover, options */): unknown`
   See "Driving a component's real activation path: interaction drivers" above for the full contract.
 
 - **`testing-wait-for-mount-contracts`** — Shared utility contracts.
@@ -1679,6 +1722,7 @@ These named interfaces and helper signatures are available to typed integrations
   `parseLyraStyleRecord(value: unknown): Readonly<LyraStyle>`
   `resetLyraStyle(fields?: readonly LyraStyleField[]): Readonly<LyraStyle>`
   `setLyraStyle(choices: LyraStyleChoices): Readonly<LyraStyle>`
+  `startLyraStyle(): Readonly<LyraStyle>`
 
 - **`vue-contracts`** — Framework integration type contracts, including the multi-split
   `for` launcher id and `trigger` element reference.

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

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

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

@@ -39,7 +39,7 @@ Deprecated **package entry points**, **stylesheets**, **exported types/functions
 **global events/root attributes** are listed under "Deprecated package exports" at the end of
 `llms/index.md`. Deprecated named exports also carry `@deprecated` in their declarations for editor
 feedback. Each component's own deprecations
-are listed in its `llms/components/<tag>.md` header and in `custom-elements.json` (the declaration's
+are listed in its `llms/components/<tag>.md` header and in `custom-elements.json` (from `@aceshooting/lyra-ide`; the declaration's
 `deprecations`, with a member's `deprecationRef` identifying its record as `kind:name`).
 The standard `deprecated` field remains available to generic CEM readers. These records are the complete
 list of deprecated APIs; audit an upgrade against them, not against console output.
@@ -185,18 +185,19 @@ The entry points, then:
 - **`lr-flag`** registers from the barrel, but resolving a flag by `country`/`language` (rather than
   a pre-resolved `src`) additionally needs
   `import '@aceshooting/lyra-ui/components/media/flag/flag-peer.js';` once.
-- **Other subpaths.** `@aceshooting/lyra-ui/theme.css` (ready-made light/dark theme),
+- **Other subpaths.** `@aceshooting/lyra-ui/theme.css` (ready-made light/dark theme, including the
+  document token layer),
   `@aceshooting/lyra-ui/looks/shadcn.css` (opt-in shadcn/ui look, imported after `theme.css` — see
   [The shadcn look](./styles-and-tokens.md#the-shadcn-look--looksshadcncss)),
-  `@aceshooting/lyra-ui/tokens-root.css` (opt-in: the curated resolved `--lr-*` tokens at `:root`,
-  so your own components can read them),
+  `@aceshooting/lyra-ui/tokens-root.css` (the document token layer alone, for pages that do not
+  use `theme.css`; link one of the two, not both),
   `@aceshooting/lyra-ui/native.css` (opt-in native-element styles inside `.lr-native`),
   `@aceshooting/lyra-ui/utilities.css` (opt-in light-DOM layout/text/typography utilities),
   `@aceshooting/lyra-ui/theme.js` (the zero-dependency style runtime),
   `@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),
-  `@aceshooting/lyra-ui/translations/<locale>.js` (the sixty-six shipped message catalogs),
+  `@aceshooting/lyra-translations/<locale>.js` (the sixty-six message catalogs, in the companion package),
   `@aceshooting/lyra-ui/events` (the global typed-event map — types only, no runtime),
   `@aceshooting/lyra-ui/ai` (provider-neutral data types), `@aceshooting/lyra-ui/testing`
   (happy-dom shims, `createLyraEvent()` for building a validated test event, a small set of