@aceshooting/lyra-ui 9.1.0 → 10.0.1

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

@@ -23,9 +23,11 @@ columns. Consumes the same `LyraSpan[]` as `<lr-span-waterfall>`.
 under `lr-span-waterfall` above (exported from `trace-tree/span.ts`); hierarchy comes from
 `parentId`, and a span whose `parentId` is missing or doesn't resolve within the same array renders
 as a root rather than being dropped. `activeSpanId: string | null = null`
-(attribute `active-span-id`), `label: string = ''`, `showTokens: boolean = false` (attribute
+(attribute `active-span-id`), `label?: string`, `showTokens: boolean = false` (attribute
 `show-tokens`) — surfaces `tokensIn`/`tokensOut`, `showCost: boolean = false` (attribute
 `show-cost`) — surfaces `costText`, and `hideBars: boolean = false` (attribute `hide-bars`).
+`label` is an optional accessible-name override for the `role="tree"` element: omission localizes
+the default, and any supplied string — including `''` — is rendered verbatim.
 Token counts render only when finite and non-negative; invalid metrics are omitted rather than
 reaching `Intl.NumberFormat`. A row's accessible name includes its optional `detail` text as well
 as its name/status/metrics, and updates when the supplied span data changes. Every trace view uses

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

@@ -53,6 +53,9 @@ describable), `summary`, `tokens-in`, `tokens-out`, `cost`, `latency`, `tooltip`
     cost-text="$0.012"
     latency-ms="2350"
   ></lr-usage-badge>
-  <lr-markdown .content="${answer}"></lr-markdown>
+  <lr-markdown></lr-markdown>
 </lr-chat-message>
+<script type="module">
+  document.querySelector("lr-chat-message lr-markdown").content = answer;
+</script>
 ```

package/llms/components/lr-video-playlist.md

@@ -6,7 +6,7 @@
 - **Class** `LyraVideoPlaylist`, also available unregistered from `@aceshooting/lyra-ui/components/media/video-playlist/video-playlist.class.js`
 - **Family** `components/media/` — see `llms/index.md` for its siblings
 - **Status** `experimental` since `8.0.0` — see the maturity and deprecation policy in `llms/shared.md`
-- **Deprecated part** `base` since `8.0.0`; use part `::part(video-playlist)`; removal not before `10.0.0` — The video-playlist part identifies the root component explicitly; base remains on the same root node for migration compatibility.
+- **Deprecated part** `base` since `8.0.0`; use part `::part(video-playlist)`; removal not before `10.0.0` — The video-playlist part identifies the root component explicitly; base remains on the same root node for migration compatibility. That version is a policy floor, not a plan: `wa-video-playlist` still publishes its own deprecated `base` part, so this alias is removed only when upstream's is.
 - **Optional peers** `dompurify` — see `llms/peers.md`
 - **Themeable via** 7 parts, 2 custom properties — see this component's own `@csspart`/`@cssprop` list below
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`

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

@@ -123,7 +123,7 @@ progress` style, and gates `lr-load-more` while a consumer's fetch is in flight.
 **Exported types:** `VirtualListRowHeight = number | 'auto'`;
 `VirtualListSource<T> = readonly T[] | VirtualListIndexedSource<T>` and
 `VirtualListIndexedSource<T> { readonly count: number; itemAt(index): T; keyAt?(index): string |
-number; indexOfKey?(key: string | number): number }`; `VirtualListRange { start: number; end: number }` (the `lr-visible-range-changed`
+number; indexOfKey?(key: string | number): number }`; `VirtualListRange { start: number; end: number }` (the `lr-visible-range-change`
 detail shape); `VirtualListGroup { key: string | number; label?: string; startIndex: number }` — the
 shape consumed by `groups` above; `VirtualListScroll { scrollTop: number; viewportHeight: number }` —
 the `lr-virtual-scroll` detail shape.
@@ -168,12 +168,14 @@ math, and any row element can be recycled or removed on the next update.
 **Events:** `lr-load-more` (no detail — fired once per approach to the bottom of the list while
 `has-more` is true and `loading` is false; does not refire on every scroll tick while still near the
 bottom — scrolling back away from the bottom and returning, or `items` growing enough to move the
-window away from the end, re-arms it), `lr-visible-range-changed` (`detail: VirtualListRange`, the
-current visible, non-overscanned item index range — fired only when it actually changes),
+window away from the end, re-arms it), `lr-visible-range-change` (`detail: VirtualListRange`, the
+current visible, non-overscanned item index range — fired only when it actually changes; it was
+spelled `lr-visible-range-changed` before 10.0.0, the only past-tense `-changed` spelling among 58
+`-change`-family events, so a convention-driven `lr-${x}-change` listener silently missed it),
 `lr-virtual-scroll`
 (`detail: VirtualListScroll` — the scroll container moved; emitted from the same animation frame that
 already coalesces native `scroll` events, so a fling produces at most one per frame and none at all
-when the position did not change. Unlike `lr-visible-range-changed`, which only fires on index-range
+when the position did not change. Unlike `lr-visible-range-change`, which only fires on index-range
 changes, this reports _sub-row_ movement, which is what scroll-linked layout needs)
 
 **Slots:** none — all content comes from `renderItem`.
@@ -204,8 +206,10 @@ activation target.
 
 **Optional peer deps:** none.
 
-```html
-<lr-virtual-list
+```ts
+import { html } from "lit";
+
+const view = html`<lr-virtual-list
   .items=${sessions}
   .renderItem=${(item, index) => html`
     <lr-conversation-item
@@ -220,12 +224,14 @@ activation target.
   ?has-more=${hasMorePages}
   ?loading=${isLoadingMore}
   @lr-load-more=${() => loadNextPage()}
-  @lr-visible-range-changed=${(e) => console.log('visible', e.detail.start, e.detail.end)}
-  @lr-virtual-scroll=${(e) => console.log('scroll top', e.detail.scrollTop)}
-></lr-virtual-list>
+  @lr-visible-range-change=${(e) => console.log("visible", e.detail.start, e.detail.end)}
+  @lr-virtual-scroll=${(e) => console.log("scroll top", e.detail.scrollTop)}
+></lr-virtual-list>`;
 ```
 
 ```ts
+import { html } from "lit";
+
 // No count-sized array: only the current window is read.
 const syntheticRows = {
   count: 100_000,
@@ -242,15 +248,17 @@ html`<lr-virtual-list
 ></lr-virtual-list>`;
 ```
 
-```html
-<!-- Sticky group headers: the header is a real row, so the `groups` entries are position anchors
-     only (`label: ''`); the pinned copy remains strictly presentational. -->
-<lr-virtual-list
+```ts
+import { html } from "lit";
+
+// Sticky group headers: the header is a real row, so the `groups` entries are position anchors
+// only (`label: ''`); the pinned copy remains strictly presentational.
+const view = html`<lr-virtual-list
   .items=${rows}
   .groups=${groupStarts /* [{ key: 'Today', label: '', startIndex: 0 }, …] */}
   .renderItem=${(item, index) => (item.isHeader ? headerTemplate(item) : rowTemplate(item))}
   .renderStickyGroup=${(group) => headerTemplate(group)}
-></lr-virtual-list>
+></lr-virtual-list>`;
 ```
 
 Every row is positioned by a `transform: translateY(offset)`, rather than page flow, so only a small

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

@@ -123,15 +123,18 @@ stale-value row), `option-preview` (a pointer-only per-row preview icon, `tabind
 trigger), `expand-icon`, `empty`, `hint`, `error`.
 
 ```html
-<lr-voice-picker provider="elevenlabs" .catalog=${voices} allow-custom
-  @lr-change=${(e) => setVoice(e.detail.value)}
-  @lr-preview-request=${(e) => {
+<lr-voice-picker provider="elevenlabs" allow-custom></lr-voice-picker>
+<script type="module">
+  const picker = document.querySelector("lr-voice-picker");
+  picker.catalog = voices;
+  picker.addEventListener("lr-change", (e) => setVoice(e.detail.value));
+  picker.addEventListener("lr-preview-request", (e) => {
     if (!e.detail.previewUrl) {
       e.preventDefault();
       playSample(e.detail.voiceId);
     }
-  }}
-></lr-voice-picker>
+  });
+</script>
 ```
 
 **Known gotchas:**

package/llms/components/lr-widget-renderer.md

@@ -44,9 +44,9 @@ readonly slot?: string; readonly actionId?: string; readonly payload?: unknown }
 - `LyraWidgetDocument { readonly version: '2'; readonly root: LyraWidgetNode }` — the sole versioned tree source.
 - `createWidgetDocument(root: LyraWidgetNode): LyraWidgetDocument` — creates an immediate frozen
   version-two snapshot for former unversioned tree assignments. Traversal uses the renderer's depth,
-  node, and per-node prop ceilings; malformed, cyclic, duplicate-id, or hostile structure throws
-  `TypeError`. Node records, child arrays, and prop records are copied and frozen, while opaque prop
-  values and action payloads intentionally retain caller identity.
+  node, per-node prop, and per-string length ceilings; malformed, cyclic, duplicate-id, or hostile
+  structure throws `TypeError`. Node records, child arrays, and prop records are copied and frozen,
+  while opaque prop values and action payloads intentionally retain caller identity.
 
 The package root and the normal `widget-renderer.js` registration entry expose the renderer
 `LyraWidgetRenderer`/`LyraWidgetRendererEventMap` together with the complete stable authoring

package/llms/components/lr-widget.md

@@ -8,7 +8,7 @@
 - **Status** `stable` since `4.0.0` — see the maturity and deprecation policy in `llms/shared.md`
 - **Deprecations** none
 - **Optional peers** none
-- **Themeable via** 16 parts, 8 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 16 parts, 9 custom properties — see this component's own `@csspart`/`@cssprop` list below
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
 
 ---

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

@@ -46,9 +46,13 @@ number, color?: string, group?: string }` snapshots; malformed/hostile records a
   marking shortened strings with an ellipsis and disclosing omitted input through `[part="limit"]`.
   The returned sequence and records are frozen; reassign `words` after changes.
 - `minFontSize: number = 12` (attribute `min-font-size`) — px, applied to the lowest-weight word;
-  layout clamps positive finite values to at most 512px and uses 1px for invalid/non-positive values
+  a finite value is clamped to `[1, 512]` (so `0`/a negative value floors at `1px`, and an oversized
+  value caps at `512px`); a non-finite value (`NaN`/`Infinity`) falls back to the default `12px`
+  rather than to the `1px` floor
 - `maxFontSize: number = 48` (attribute `max-font-size`) — px, applied to the highest-weight word;
-  normalized by the same 1–512px layout bound (reversed min/max bounds are swapped)
+  clamped/defaulted the same way (a non-finite value falls back to `48px`, not to `1px`); a
+  resulting reversed pair (`minFontSize` greater than `maxFontSize`) is swapped rather than
+  inverting the weight-to-size mapping
 - `scale: 'linear'|'sqrt' = 'linear'` — `sqrt` compresses the weight→font-size mapping so one heavy
   word doesn't dwarf the rest, matching `lr-heatmap`'s `scale` property
 - `wordRotation: 'none'|'mixed' = 'none'` (attribute `word-rotation`, reflected) — `mixed` lets

package/llms/index.md

@@ -175,7 +175,7 @@ Optional peers: `llms/peers.md`. Safe `wa-*`/`sl-*` migration: `llms/migration.m
 - `lr-attachment-chip` · lr-attachment-chip.js · `stable` since `4.0.0` — a compact chip representing one file queued for (or already part of) a chat message: a composer's pre-send attachment tray, or a sent mes...
 - `lr-file-icon` · lr-file-icon.js · `stable` since `4.0.0` — Displays a localized, tokenized file-type badge from a MIME type.
 - `lr-media-card` · lr-media-card.js · `stable` since `4.0.0` — a lightweight inline preview for one already-sent, already-available attachment inside a rendered chat message body (e.g.
-- `lr-attachment-trigger` · lr-attachment-trigger.js · `stable` since `4.0.0` — a compact attach affordance designed for a chat composer's leading slot (see `<lr-chat-composer>`'s own `leading` slot, which this drops...
+- `lr-attachment-trigger` · lr-attachment-trigger.js · `stable` since `4.0.0` — a compact attach affordance designed for a chat composer's start slot (see `<lr-chat-composer>`'s own `start` slot, which this drops stra...
 - `lr-avatar` · lr-avatar.js · `stable` since `4.0.0` — a small, fixed-size identity marker: an image, an `icon`-slotted fallback glyph, or an initials fallback, in that priority order.
 - `lr-animated-image` · lr-animated-image.js · `stable` since `4.0.0` — - displays an animated GIF/APNG/WebP with a play/pause control, defaulting to a frozen first frame both at rest and automatically under `...
 - `lr-animation` · lr-animation.js · `stable` since `4.0.0` — `<lr-animation>` declaratively animates its single slotted child through the native Web Animations API: a small curated preset catalog (`...

package/llms/peers.md

@@ -2,14 +2,14 @@
 
 # Optional peer dependencies
 
-All 28 peers are **optional**: nothing here is needed to install or use the library,
+All 29 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 (25).** No component imports one eagerly. Install a
+**Component-loaded peers (26).** No component imports one eagerly. Install a
 peer only when you use a component that needs it.
 
 **How they load.** A component that needs a peer resolves it through a dynamic `import()` on first
@@ -26,12 +26,22 @@ command), matching the range below. The npm-published 0.18.5 release has unresol
 do not run `npm audit fix --force` to address them when it proposes downgrading lyra-ui. That
 changes the component library version without installing a supported SheetJS release.
 
+**PDF.js (`pdfjs-dist`).** Installing the peer is not sufficient on its own: PDF.js renders in a
+web worker, and it has no way to locate that worker inside a bundled app. If nothing configures
+it, every document load rejects with `No "GlobalWorkerOptions.workerSrc" specified.` Point
+`<lr-pdf-viewer>` at the worker chunk your own bundler emitted, either per element with
+`worker-src` (`<lr-pdf-viewer worker-src="/assets/pdf.worker.mjs">`) or once at startup by
+importing `pdfjs-dist` yourself and setting `GlobalWorkerOptions.workerSrc`. An already-configured
+global always wins, and because that global is process-wide the first viewer to load settles it
+for the page.
+
 | Peer | Range | Needed by |
 |---|---|---|
 | `@aceshooting/lyra-flags` | `workspace:^2.0.0` | `lr-flag`, `lr-locale-picker`, `lr-phone-input` |
 | `@aiden0z/pptx-renderer` | `^1.2.4` | `lr-pptx-viewer` |
 | `@sgratzl/chartjs-chart-boxplot` | `^4.4.5` | `lr-box-plot` |
 | `chart.js` | `^4.5.1` | `lr-agent-eval-dashboard`, `lr-bar-chart`, `lr-box-plot`, `lr-bubble-chart`, `lr-chart`, `lr-doughnut-chart`, `lr-histogram`, `lr-line-chart`, `lr-lite-chart`, `lr-pie-chart`, `lr-polar-area-chart`, `lr-radar-chart`, `lr-rag-eval-dashboard`, `lr-scatter-chart` |
+| `chartjs-plugin-annotation` | `^3.1.0` | `lr-agent-eval-dashboard`, `lr-bar-chart`, `lr-box-plot`, `lr-bubble-chart`, `lr-chart`, `lr-doughnut-chart`, `lr-histogram`, `lr-line-chart`, `lr-lite-chart`, `lr-pie-chart`, `lr-polar-area-chart`, `lr-radar-chart`, `lr-rag-eval-dashboard`, `lr-scatter-chart` |
 | `chartjs-plugin-datalabels` | `^2.2.0` | `lr-agent-eval-dashboard`, `lr-bar-chart`, `lr-box-plot`, `lr-bubble-chart`, `lr-chart`, `lr-doughnut-chart`, `lr-histogram`, `lr-line-chart`, `lr-lite-chart`, `lr-pie-chart`, `lr-polar-area-chart`, `lr-radar-chart`, `lr-rag-eval-dashboard`, `lr-scatter-chart` |
 | `chartjs-plugin-zoom` | `^2.2.0` | `lr-agent-eval-dashboard`, `lr-bar-chart`, `lr-box-plot`, `lr-bubble-chart`, `lr-chart`, `lr-doughnut-chart`, `lr-histogram`, `lr-line-chart`, `lr-lite-chart`, `lr-pie-chart`, `lr-polar-area-chart`, `lr-radar-chart`, `lr-rag-eval-dashboard`, `lr-scatter-chart` |
 | `d3-drag` | `^3.0.0` | `lr-agent-workspace`, `lr-chunk-inspector`, `lr-entity-dossier`, `lr-eval-run`, `lr-graph`, `lr-grounding-summary`, `lr-knowledge-graph-explorer`, `lr-memory-panel`, `lr-provenance-panel`, `lr-rag-answer`, `lr-retrieval-results`, `lr-retrieval-trace` |
@@ -46,7 +56,7 @@ changes the component library version without installing a supported SheetJS rel
 | `libphonenumber-js` | `>=1.11.0 <2` | `lr-phone-input` |
 | `mammoth` | `^1.12.1` | `lr-docx-viewer` |
 | `maplibre-gl` | `>=5 <7` | `lr-geojson-view`, `lr-geojson-viewer`, `lr-map` |
-| `marked` | `^18.0.9` | `lr-agent-workspace`, `lr-dashboard-grid`, `lr-eval-run`, `lr-markdown`, `lr-markdown-core`, `lr-message-parts`, `lr-notebook-viewer`, `lr-rag-answer`, `lr-streaming-text`, `lr-widget-renderer` |
+| `marked` | `^18.0.10` | `lr-agent-workspace`, `lr-dashboard-grid`, `lr-eval-run`, `lr-markdown`, `lr-markdown-core`, `lr-message-parts`, `lr-notebook-viewer`, `lr-rag-answer`, `lr-streaming-text`, `lr-widget-renderer` |
 | `papaparse` | `^5.6.0` | `lr-csv-viewer`, `lr-dataset-viewer` |
 | `pdfjs-dist` | `^6.2.108` | `lr-pdf-viewer` |
 | `postal-mime` | `^3.0.0` | `lr-email-viewer` |

package/llms/shared.md

@@ -1093,6 +1093,70 @@ canvas consumer's redraw to its normal microtask/render schedule. The optional r
 browser realm; it does not limit invalidation to a subtree. The function is a no-op during server
 rendering and retains no document or stylesheet after the last canvas consumer disconnects.
 
+## Preventing layout shift from lazy-upgrading elements (CLS)
+
+An undefined custom element is an inline box with no intrinsic size, so every `lr-*` in the initial
+viewport contributes a reflow as its definition loads. Components that additionally defer on an
+optional peer (`lr-chart`, `lr-map`, `lr-flag`, `lr-flow-canvas`, `lr-knowledge-graph-explorer`)
+render a skeleton while that peer resolves, which can cost a second shift when the real content
+replaces it. Each component is individually well-behaved; the aggregate on a first paint is what
+costs a Lighthouse Cumulative Layout Shift score.
+
+Lyra ships an optional, opt-in stylesheet that reserves each component's intrinsic footprint before
+upgrade:
+
+```css
+@import "@aceshooting/lyra-ui/reservations.css";
+```
+
+It styles **only** `:not(:defined)` elements, inside an `@layer lr-reservations`, so it becomes inert
+the moment a definition upgrades and can never fight a component's own layout. It sets no colors and
+no `:root` rules.
+
+**Every reservation is expressed with the same custom property and fallback token the component's
+own stylesheet uses** — `--lr-chart-height` / `--lr-size-280px` for the chart family,
+`--lr-flag-aspect-ratio` for `lr-flag`, `--lr-form-control-height` for the field controls, and so
+on. That is the point of shipping it rather than documenting measured pixel values: a hand-written
+reservation rots silently the moment a component's default changes, whereas these track it, and
+theming a component through its documented custom property re-themes its reservation with it.
+
+Hand-rolling equivalent rules is still fine — the pattern is just:
+
+```css
+lr-chart:not(:defined) {
+  display: block;
+  min-block-size: var(--lr-chart-height, var(--lr-size-280px));
+}
+```
+
+Two things worth knowing:
+
+- A per-instance override needs the matching custom property to be set as well, not only the
+  attribute, or the pre-upgrade frame and the upgraded frame will disagree. `<lr-chart height="500px">`
+  should carry `style="--lr-chart-height: 500px"` too if it sits above the fold.
+- The reservation covers the definition-upgrade shift. A component that then swaps a skeleton for
+  peer-resolved content stays stable as long as the reserved box matches the final footprint, which
+  is why the reservations target each component's *final* default size rather than its skeleton's.
+
+## Scope: what this library does not provide
+
+Lyra is a component library, not an application framework. The following are deliberately out of
+scope, so they are worth not searching the catalog for:
+
+- **Client-side routing.** There is no router and no route-outlet component. URL ownership belongs to
+  the application (or its router of choice), because a component library that took it over would
+  conflict with every framework router a consumer might already run. The navigation components are
+  designed to be *driven* by whatever router you use rather than to own the URL themselves:
+  `lr-app-rail-item`, `lr-breadcrumb-item` and `lr-tab-group` all expose their active/selected state
+  as ordinary reflected properties, so binding is a one-way write from your route state plus a click
+  handler that calls your router. Wire it once in your shell component; there is no Lyra-specific
+  pattern to learn.
+- **Data fetching, caching, and state management.** Components take data as properties and emit
+  events; they never fetch on your behalf, except the documented viewers/`src`-taking components,
+  which are explicit about it.
+- **Form submission and validation orchestration.** Form-associated controls integrate with the
+  native `<form>`/`ElementInternals` contract; the submission lifecycle stays the application's.
+
 ## Optional native styles and CSS utilities
 
 Lyra ships two independent light-DOM stylesheets. Neither is imported by the root barrel, a family
@@ -1207,7 +1271,10 @@ setLyraLocale("fr"); // page-level selection; see the precedence order below
 ```
 
 ```html
-<lr-toast .strings=${{ close: 'Fermer' }}></lr-toast>
+<lr-toast></lr-toast>
+<script type="module">
+  document.querySelector("lr-toast").strings = { close: "Fermer" };
+</script>
 ```
 
 **Which locale a component ends up using.** Four sources, first answer wins:
@@ -1599,7 +1666,7 @@ control) is a single tab stop using a roving `tabindex`; arrow keys move within
 `Escape` dismisses the topmost dismissible overlay and returns focus to whatever opened it.
 `ArrowLeft`/`ArrowRight` mean previous/next and swap under `dir="rtl"`.
 
-**What that contract is verified by, precisely.** Every one of the 283 components carries at least
+**What that contract is verified by, precisely.** Every one of the 284 public tags carries at least
 one axe-core assertion in its own directory's tests, in a test that mounts its own tag; contrast
 (4.5:1 text, 3:1 control borders, in both the light and dark palettes), a 40px minimum target size,
 pressed-state coverage for every hoverable part, and `::part()` reachability are separate blocking
@@ -1620,6 +1687,19 @@ files matter when scaffolding a project's editor configuration. Build tools can
 through the explicit `@aceshooting/lyra-ui/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
+always the complete flattened set, including everything inherited from a superclass — `::part()`
+has no type-level inheritance chain a consumer could otherwise walk. `attributes`, `members`,
+`events`, `slots`, and `cssProperties` are the opposite: a subclass declaration lists only its own
+entries plus any inherited entry it explicitly overrides, pruning an inherited-and-unmodified entry
+of those four kinds. This is intentional, not a gap — a TypeScript/JS consumer already gets the
+full set for free from the generated `.d.ts` `extends` chain, the same resolution `web-types.json`
+and `vscode-html-data.json` perform ahead of time. A consumer reading `custom-elements.json`
+directly and needing the complete `attributes`/`members`/`events`/`slots`/`cssProperties` set for
+those four kinds must walk the declaration's own `superclass.name`/`superclass.module` across
+`modules[].declarations[]` itself, or read `web-types.json`/`vscode-html-data.json` instead, which
+are already fully resolved.
+
 ## Independence and migration
 
 Lyra has no runtime, theme, or design-token dependency on Shoelace or Web Awesome. Documented `wa-*`
@@ -2792,6 +2872,7 @@ These named interfaces and helper signatures are available to typed integrations
 
 - **`internal-canvas-color-contracts`** — Shared utility contracts.
   `resolveCanvasColor(/* public names: scope, color, fallback */): unknown`
+  `resolveCanvasColors(/* public names: scope, colors, fallback */): unknown`
 
 - **`internal-localization-runtime-contracts`** — Shared utility contracts.
   `getLyraLocaleDirection(/* public names: locale */): unknown`