@aceshooting/lyra-ui 26.0.0 → 27.0.0

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,7 @@ 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. |
 | `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 +819,7 @@ 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. |
 | `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 +1540,7 @@ 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. |
 | `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 +1585,97 @@ 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. |
+| `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. |
+
 ## 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 +1729,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 +1815,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` | `^27.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
@@ -1576,6 +1576,9 @@ These named interfaces and helper signatures are available to typed integrations
 
 - **`testing-happy-dom-shims-contracts`** — Shared utility contracts.
   `installHappyDomFormAssociatedShims(): unknown`
+  `installHappyDomShadowFocusShim(): unknown`
+  `installHappyDomAriaControlsShim(/* public names: proto */): unknown`
+  `installHappyDomShims(): unknown`
   `installStubInternalsForTest(/* public names: host */): unknown`
 
 - **`testing-interaction-drivers-contracts`** — Shared utility contracts.

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.
@@ -196,7 +196,7 @@ The entry points, then:
   `@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

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

@@ -200,26 +200,26 @@ English-resolved locale, since falling through to `defaults` is simply how Engli
 Gotcha: `localize()`'s optional second argument is a fallback string. Passing a defined literal there
 silently defeats a registered catalog — omit it, or pass `undefined`.
 
-### Ready-made catalogs: `@aceshooting/lyra-ui/translations/<locale>.js`
+### Ready-made catalogs: `@aceshooting/lyra-translations/<locale>.js`
 
-Sixty-six full catalogs ship with the package, each covering every key in `LYRA_DEFAULT_STRINGS`.
+Sixty-six full catalogs ship in the companion package `@aceshooting/lyra-translations` (`pnpm add @aceshooting/lyra-translations`, same version as `@aceshooting/lyra-ui`), each covering every key in `LYRA_DEFAULT_STRINGS`.
 The public `@aceshooting/lyra-ui/locales.json` manifest lists their canonical identities, authored
 source spellings, import paths, and structural coverage. It also distinguishes translation
 coverage from linguistic review tier. The catalogs are **side-effect-only modules**: import one
 bare, read nothing from it, and it calls `registerLyraLocale()` for you.
 
 ```ts
-import "@aceshooting/lyra-ui/translations/de.js";
-import "@aceshooting/lyra-ui/translations/de-CH.js"; // Swiss Standard German
-import "@aceshooting/lyra-ui/translations/ar.js"; // declares dir: 'rtl'; direction still comes from dir
-import "@aceshooting/lyra-ui/translations/fa.js"; // fa-IR falls back to this base catalog
-import "@aceshooting/lyra-ui/translations/he.js"; // he-IL falls back to this base catalog
-import "@aceshooting/lyra-ui/translations/it.js"; // Italian
-import "@aceshooting/lyra-ui/translations/pt-BR.js"; // Brazilian: serves pt and pt-BR
-import "@aceshooting/lyra-ui/translations/pt-PT.js"; // European: serves pt-PT, pt-AO, pt-MZ
-import "@aceshooting/lyra-ui/translations/ro.js"; // Romanian
-import "@aceshooting/lyra-ui/translations/zh-CN.js"; // Simplified: serves zh, zh-Hans, zh-SG and zh-Hans-CN
-import "@aceshooting/lyra-ui/translations/zh-TW.js"; // Traditional: serves zh-Hant, zh-HK and zh-MO
+import "@aceshooting/lyra-translations/de.js";
+import "@aceshooting/lyra-translations/de-CH.js"; // Swiss Standard German
+import "@aceshooting/lyra-translations/ar.js"; // declares dir: 'rtl'; direction still comes from dir
+import "@aceshooting/lyra-translations/fa.js"; // fa-IR falls back to this base catalog
+import "@aceshooting/lyra-translations/he.js"; // he-IL falls back to this base catalog
+import "@aceshooting/lyra-translations/it.js"; // Italian
+import "@aceshooting/lyra-translations/pt-BR.js"; // Brazilian: serves pt and pt-BR
+import "@aceshooting/lyra-translations/pt-PT.js"; // European: serves pt-PT, pt-AO, pt-MZ
+import "@aceshooting/lyra-translations/ro.js"; // Romanian
+import "@aceshooting/lyra-translations/zh-CN.js"; // Simplified: serves zh, zh-Hans, zh-SG and zh-Hans-CN
+import "@aceshooting/lyra-translations/zh-TW.js"; // Traditional: serves zh-Hant, zh-HK and zh-MO
 ```
 
 Persian and Hebrew use CLDR plural categories (`fa`: `one`/`other`; `he`:
@@ -245,7 +245,7 @@ ones cost nothing. A catalog registered this way is merged like any other, so a
 in `getRegisteredLyraLocales()`, and therefore in `<lr-locale-picker>`, so the set you import is the
 set a user can switch between.
 
-### Smaller catalogs: `@aceshooting/lyra-ui/translations/<locale>/<family>.js`
+### Smaller catalogs: `@aceshooting/lyra-translations/<locale>/<family>.js`
 
 Each locale above is also published as twelve smaller, side-effect-only **family slices** — one per
 component family (`agent-tools`, `charts`, `conversation`, `data`, `forms`, `layout`, `media`,
@@ -254,12 +254,12 @@ one family reaches (roving-focus/overlay/a11y strings like `collapse`, `open`, `
 the families the application actually renders instead of the whole-locale aggregate above:
 
 ```ts
-import "@aceshooting/lyra-ui/translations/fr/forms.js"; // lr-input, lr-select, lr-combobox, ...
-import "@aceshooting/lyra-ui/translations/fr/data.js"; // lr-table, lr-tree, lr-data-grid, ...
-import "@aceshooting/lyra-ui/translations/fr/shared.js"; // cross-cutting strings both families reach
+import "@aceshooting/lyra-translations/fr/forms.js"; // lr-input, lr-select, lr-combobox, ...
+import "@aceshooting/lyra-translations/fr/data.js"; // lr-table, lr-tree, lr-data-grid, ...
+import "@aceshooting/lyra-translations/fr/shared.js"; // cross-cutting strings both families reach
 ```
 
-`@aceshooting/lyra-ui/translations/fr.js` is unchanged: it is now a thin aggregate that imports every
+`@aceshooting/lyra-translations/fr.js` is unchanged: it is now a thin aggregate that imports every
 slice above, so the plain whole-locale import from the previous section keeps working exactly as
 before — this is a purely additive, opt-in way to shrink a non-English bundle, mirroring the
 per-component tree-shaking English defaults already get for free. A component's family is the

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

@@ -755,7 +755,7 @@ code. See each control's own reference page for its exact pair.
   formula from the `--lr-theme-*` inputs you control:
   ```css
   padding-inline-start: calc(
-    min(var(--lr-theme-icon-button-size, 2.5rem), 1.75rem) + var(--lr-theme-space-s, 0.5rem)
+    min(var(--lr-theme-icon-button-size, 2.25rem), 1.75rem) + var(--lr-theme-space-s, 0.5rem)
   );
   ```
 

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

@@ -10,6 +10,16 @@ that need form-value or validity behavior: it supplies
 `form`/`labels`/`validity`/`validationMessage`/`willValidate`. The shim is a no-op where the
 platform already provides internals, so it is safe in a shared setup file.
 
+`installHappyDomShims()` installs that shim plus two more Happy DOM gap fixes, each a no-op where
+the engine already behaves (feature-detected, so safe in a shared setup file and never part of a
+production bundle): `installHappyDomShadowFocusShim()` makes `ShadowRoot.activeElement` return
+`null` for a sibling or detached shadow root instead of throwing a `TypeError` (own-root and
+nested-root focus are unchanged; it returns a function that restores the original descriptor), and `installHappyDomAriaControlsShim()` adds `Element.ariaControlsElements` only
+when absent. Setting it stores the references and writes an empty `aria-controls`; reading returns
+only targets in the element's own or an ancestor shadow scope (sibling and descendant shadow
+targets are dropped); `null` clears it and removes the attribute; a changed `aria-controls`
+attribute resolves ids in the element's own root instead.
+
 ## Constructing a validated test event: `createLyraEvent()`
 
 `@aceshooting/lyra-ui/testing` also exports
@@ -136,47 +146,28 @@ a local island around the call site.
 
 ## happy-dom's custom-property resolver and host-to-part token forwarding
 
-In 16.0.0, seven built-in controls that each compose a real
-`<lr-icon-button>` for their icon-only action — `<lr-copy-button>`, `<lr-dialog>` (whose close
-button is inherited by `<lr-drawer>`), `<lr-reorder-item>`, `<lr-message-actions>`,
-`<lr-attachment-trigger>`, `<lr-code-block>` (shared by `<lr-code-block-core>`), and `<lr-callout>`
-— captured the composed control's public `--lr-icon-button-*` tokens on their own `:host` and
-forwarded that private token back onto the SAME public token name on the `[part]` rendering the
-composed control, so that an ancestor theme override still reached the composed child instead of
-being shadowed by the component's own default. That was legal under the CSS Custom Properties spec
-— `:host` and `[part]` resolve on different elements, so a real browser resolves the host
-declaration to a concrete value first and the part substitutes that, and per-element cycle detection
-never fired — but **happy-dom does not model that element boundary**. Its `CSSComputedStyle` merges
-ancestor and own-element custom properties into a single flat map with no notion of which element
-declared what, and (at least through 20.14.5, the newest release at time of writing)
-`CSSVariableFormatter.resolveVariables` substitutes into that map recursively with no visited set
-and no depth cap — so the capture-and-forward pair resolved into each other forever, throwing an
-unhandled `RangeError: Maximum call stack size exceeded` from `CSSVariableFormatter.resolveVariables`
-on every render of any of the seven components. Every test still reported as passing — there was no
-failing assertion to point at — but the runner counted the unhandled errors and exited non-zero
-anyway, which read as unrelated flakiness rather than a CSS issue.
-
-**Current versions are unaffected.** `<lr-icon-button>` now carries a private
-`--_lr-icon-button-<token>-default` fallback tier for every paint token (background, color, border,
-and their hover/active variants — the same shape its corner radius already used via
-`--_lr-icon-button-radius-default`), and each composing component sets its own default directly on
-that private tier rather than re-declaring the public token name. `<lr-icon-button>`'s own
-stylesheet still checks the public token first, so an ancestor override reaches a composed control
-exactly as before, but no descendant declares a public `--lr-icon-button-*` token from a private
-token that was itself derived from that same public token — so no resolver, scoped or flattened,
-ever sees a cycle. A project still hitting the `RangeError` above should upgrade
-`@aceshooting/lyra-ui`; the workarounds that version range needed (patching or upgrading the DOM
-implementation to cycle-aware/depth-limited custom-property resolution, or running the affected
-suites against a real browser engine) are no longer necessary once it does.
+happy-dom merges ancestor and own-element custom properties into one flat map and resolves
+`var()` recursively with no visited set or depth cap, so a `:host` token captured from a public
+token and forwarded back onto that same public name on a `[part]` recurses forever
+(`RangeError: Maximum call stack size exceeded` from `CSSVariableFormatter.resolveVariables`).
+Real browsers resolve host and part on separate elements and never cycle. Tests can pass while
+the unhandled errors still make the runner exit non-zero.
+
+Current versions are unaffected: composing components set their defaults on
+`<lr-icon-button>`'s private `--_lr-icon-button-<token>-default` tier, and `<lr-icon-button>` still
+checks the public token first, so an ancestor override reaches a composed control. A project
+still hitting the `RangeError` should upgrade `@aceshooting/lyra-ui`; no resolver patch or
+real-browser fallback is needed.
 
 ## Editor and tooling integration
 
-The published package ships machine-readable metadata for editors:
-`custom-elements.json` (Custom Elements Manifest), `web-types.json` (JetBrains, zero-config), and
-`vscode-html-data.json` / `vscode-css-data.json` (point `html.customData` / `css.customData` at them
-in `.vscode/settings.json`). For an agent, `llms/components/<tag>.md` is the cheaper source; these
+The companion package `@aceshooting/lyra-ide` (not `@aceshooting/lyra-ui`) ships machine-readable
+metadata for editors: `custom-elements.json` (Custom Elements Manifest), `web-types.json`
+(JetBrains, zero-config), and `vscode-html-data.json` / `vscode-css-data.json` (point
+`html.customData` / `css.customData` at `./node_modules/@aceshooting/lyra-ide/...` in
+`.vscode/settings.json`). For an agent, `llms/components/<tag>.md` is the cheaper source; these
 files matter when scaffolding a project's editor configuration. Build tools can import the manifest
-through the explicit `@aceshooting/lyra-ui/custom-elements.json` package export; native Node ESM
+through the explicit `@aceshooting/lyra-ide/custom-elements.json` package export; native Node ESM
 uses `with { type: 'json' }` on that import.
 
 **Inherited members in `custom-elements.json`.** A subclass declaration's `cssParts` array is
@@ -413,7 +404,7 @@ arrowPadding?: number; hoverBridge?: HTMLElement; onPlaced?: (result: PlacementR
   `FormValueAdapter<T>` has readonly `empty`, required `toFormValue(value)`, and optional
   `toFormState(value)`, `isEmpty(value)`, `fromAttribute(attribute)`, `toAttribute(value)`, and
   `fromFormState(state)`. `FormAssociatedInterface<T>` exposes `internals`; the `name` getter/setter
-  (`next`); `value`; `defaultValue`; `customError`; `disabled`; `required`; readonly
+  (`next`); the `value` getter/setter (`next`); `defaultValue`; `customError`; `disabled`; `required`; readonly
   `effectiveDisabled`; the `form` getter/setter (`owner`); readonly `labels`, `validity`,
   `validationMessage`, and `willValidate`; `setFormValue(next)`; `getForm()`; `checkValidity()`;
   `reportValidity()`; `setCustomValidity(message)`; `resetValidity()`; `formResetCallback()`; and
@@ -432,7 +423,7 @@ toFormValue(value: TValue): FormSubmissionValue; toFormState?(value: TValue):
 FormSubmissionValue; isEmpty?(value: TValue): boolean; fromAttribute?(attribute: string): TValue;
 toAttribute?(value: TValue): string | null; fromFormState?(state: FormSubmissionValue): TValue }`
   and `FormAssociatedInterface<TValue> { internals: ElementInternals; get name(): string; set
-name(next: string | null); value: TValue; get defaultValue(): TValue;
+name(next: string | null); get value(): TValue; set value(next: TValue | null); get defaultValue(): TValue;
 set defaultValue(next: TValue | null); customError: string | null;
 disabled: boolean; required: boolean; readonly effectiveDisabled: boolean; get form():
 HTMLFormElement | null; set form(owner: FormOwnerValue); readonly labels: NodeList; readonly
@@ -443,7 +434,13 @@ formResetCallback(): void; formStateRestoreCallback(state: FormSubmissionValue,
 'autocomplete' | 'restore'): void }`. The exported subclass seam is
   `FormAssociatedSubclassInterface<TValue> { protected captureLiveValueCheckpoint(): { readonly
 value: TValue; readonly dirty: boolean }; protected restoreLiveValueCheckpoint(checkpoint: {
-readonly value: TValue; readonly dirty: boolean }): void }`.
+readonly value: TValue; readonly dirty: boolean }): void; protected commitFormValue(value: TValue):
+void; protected isMissingValue(): boolean }`.
+  `CheckedFormAssociated(Base)` is the checkbox-, switch- and radio-shaped variant of that mixin: the
+  string `value` (default `'on'`) is submitted only while `checked`, `checked` has native
+  dirty/default semantics, reset and state restore round-trip it, and `required` means "must be
+  checked". It adds `CheckedFormAssociatedInterface { checked: boolean; get defaultChecked():
+boolean; set defaultChecked(next: boolean) }`.
 - **`group-by-recency` → `groupByRecency(items, options?)`** — buckets dated items into
   Today / Yesterday / Previous 7 Days / Older, on **local calendar-day boundaries** ("yesterday" is
   the previous calendar date, not 24–48 hours ago). Plain data in, plain data out — no DOM.
@@ -625,7 +622,10 @@ animationName: string, options?: LyraGetAnimationOptions): LyraResolvedElementAn
   `lockScroll`.
   `OverlayActivationOptions` exposes `host`, `panel`, optional `modalRoot`, `auxiliaryRoots`, `modal`, `lockScroll`,
   `suspendWhenUnrendered`, `onEscape`, `onBackdrop`, `preferredInitialFocus`,
-  `beforeInitialFocus`, `restoreFocusTo`, `trapFocus`, and `onTab`. `OverlayHandle` exposes
+  `beforeInitialFocus`, `restoreFocusTo`, `trapFocus`, `onTab`, and `deferredReturn` (resolved after
+  the synchronous focus return of a restoring close: a deferred pass for a target the host only
+  re-shows afterward, or `undefined` to skip it; every activation and deactivation abandons a pass
+  still pending for the host). `OverlayHandle` exposes
   `focusInitial()`, `focusAutofocus()`, `updateRestoreFocusTo(target)`,
   `deactivate({ restoreFocus?, deferScrollLockRelease? }?)`, `suspend()`, `resume()`, `isTopmost()`,
   `isActive()`, and `dismissBackdrop()`; the deactivate argument is the exported
@@ -640,7 +640,8 @@ animationName: string, options?: LyraGetAnimationOptions): LyraResolvedElementAn
 null; modalRoot?: () => HTMLElement | null; auxiliaryRoots?: () => readonly HTMLElement[]; onEscape: () => void; onBackdrop?: () => void;
 preferredInitialFocus?: () => HTMLElement | null; beforeInitialFocus?: () => boolean;
 restoreFocusTo?: OverlayRestoreFocusTarget; modal?: boolean; trapFocus?: boolean; onTab?: () =>
-void; suspendWhenUnrendered?: boolean; lockScroll?: boolean }`, `OverlayDeactivateOptions {
+void; suspendWhenUnrendered?: boolean; lockScroll?: boolean; deferredReturn?: () =>
+DeferredFocusReturnPass | undefined }`, `OverlayDeactivateOptions {
 restoreFocus?: boolean; deferScrollLockRelease?: boolean }`, and `OverlayHandle { focusInitial():
 void; focusAutofocus(): boolean; updateRestoreFocusTo(target: OverlayRestoreFocusTarget): void;
 deactivate(options?: OverlayDeactivateOptions): (() => void) | undefined; suspend(): void;
@@ -708,7 +709,7 @@ number; clearTimeout(handle: number): void }`.
 
   ```ts
   import { bridgeLyraLocale, setLyraLocale } from "@aceshooting/lyra-ui/localization.js";
-  import "@aceshooting/lyra-ui/translations/ar.js";
+  import "@aceshooting/lyra-translations/ar.js";
 
   const stop = bridgeLyraLocale(); // mirrors onto <html>
   setLyraLocale("ar"); // <html lang="ar" dir="rtl">