@aceshooting/lyra-ui 9.1.1 → 10.0.1

package/llms/components/lr-map.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** `maplibre-gl` — see `llms/peers.md`
-- **Themeable via** 12 parts, 5 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 15 parts, 5 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`
 
 ---
@@ -31,6 +31,22 @@ operations. Its runtime value is the underlying MapLibre map.
   style-required failure and makes no tile/style request. Assign a hosted vector/raster style from
   a provider whose terms fit your application, or an explicitly network-silent style for local
   geometry.
+- `legendGradient: readonly (readonly [number, string])[] = []` (attribute: false, type
+  `LyraMapLegendGradientStop[]`) — renders the legend as a **continuous** gradient bar with endpoint
+  captions instead of (or alongside) the discrete `legend` swatches, which is the standard key for a
+  choropleth whose `interpolate` fill is itself a continuous ramp. Takes the same `[value, color]`
+  stop shape as `choropleth.stops`, so the usual assignment is `map.legendGradient =
+  myChoropleth.stops` and the key cannot drift from the layer it describes. Stops are sorted
+  ascending, bounded to 64, and filtered to finite values carrying a CSS-parsable color; fewer than
+  two usable stops render no bar at all, since a one-stop "gradient" is a flat block that describes
+  nothing. Each stop sits at its true proportion of the value range, so the bar shows the ramp the
+  expression actually produces rather than evenly spacing unevenly-spaced values. Part names
+  (`legend-gradient`, `legend-lo`, `legend-hi`) mirror `lr-heatmap`'s gradient legend, and the bar
+  is `aria-hidden`/`inert` with the captions carrying the meaning. Mirrors under RTL
+- `legendGradientLoLabel: string | null = null` (attribute `legend-gradient-lo-label`),
+  `legendGradientHiLabel: string | null = null` (attribute `legend-gradient-hi-label`) — override
+  the endpoint captions, which otherwise default to the lowest/highest stop value in the component's
+  own locale-aware numeric formatting
 - `legend: readonly LyraMapLegendEntry[] = []` (attribute: false) — immutable defensive snapshots
   of `LyraMapLegendEntry { readonly color: string; readonly label: string; readonly pattern:
 LyraMapLegendPattern }`, where `LyraMapLegendPattern` is `'solid' | 'diagonal' | 'dots' |
@@ -42,10 +58,20 @@ omittedCount, truncatedLabelCount, truncated }` result for the latest assignment
   projection renders a localized visible `1–N of M items` summary rather than silently claiming
   the bounded rows are complete.
 - `choropleth?: LyraMapChoroplethLayer` (attribute: false) — `LyraMapChoroplethLayer { sourceId:
-string; geojson: GeoJSON.FeatureCollection; field: string; stops: [number, string][] }` (interpolated
+string; geojson: GeoJSON.FeatureCollection; field: string; stops: [number, string][]; interpolation?:
+'linear' | 'logarithmic' }` (interpolated
   fill-color expression from `field`'s value against `stops`; `stops` must contain at least one
   `[value, color]` pair — an empty array is ignored, leaving whatever fill layer already exists, if
-  any, untouched, rather than being applied)
+  any, untouched, rather than being applied).
+  `interpolation` (type `LyraMapChoroplethInterpolation`, default `'linear'`) chooses how the colour
+  is interpolated between stops. `'logarithmic'` compresses the ramp, which is what a heavy-tailed
+  quantity — price, population, income — needs: on a linear ramp every value below the maximum falls
+  into the first colour band, so the map reads as one flat colour plus a couple of outliers. It
+  emits maplibre's own `['interpolate', ['exponential', 0.25], …]`, exposing an existing capability
+  rather than adding one (maplibre has no `['log']` interpolation type; a sub-1 exponential base is
+  the documented way to weight a ramp toward the low end). **`stops` stay in the data's own units
+  under either mode**, so the legend keeps reading in real values instead of log units — no
+  pre-transforming to log10 and hand-relabelling the legend back
 - `markers: LyraMapMarker[] = []` (attribute: false) — `LyraMapMarker { id?: string; lngLat:
 [number, number]; color?: string; label?: string; unsafeHtml?: string }`; an explicit `id` is
   trimmed and must be nonempty, and the first marker for an explicit ID wins. Markers are reconciled
@@ -80,6 +106,37 @@ GeoJSON.FeatureCollection; tone?: 'accent' | 'success' | 'warning' |
   persists across a `dataLayers` reassignment gets its GeoJSON updated in place (`setData()`), one
   that's dropped has its private source/layers removed, and a genuinely new `sourceId` gets new
   resources — nothing leaks on removal, style change, or disconnect.
+- `maxBounds: LyraMapBounds | null = null` (attribute: false) — box the map may not pan outside,
+  `[[west, south], [east, north]]`. Prefer it over calling `map.setMaxBounds()` through the `.map`
+  escape hatch: constraining the camera can wedge maplibre-gl at a sub-1 fractional zoom in a wide
+  container, leaving `getZoom()` returning `null` permanently, every frame throwing from inside the
+  peer's own matrix math, and the canvas never painting again — a blank map, with nothing thrown at
+  the call site to attribute it to. This property applies the same call, then reads the camera back
+  and reverts (restoring zoom and centre) if it did not survive, so the worst case is an
+  unconstrained map plus a dev-mode warning. A malformed box is rejected rather than clamped
+
+**Choropleth and `dataLayers` updates are diffed before they reach the peer.** `setData()`
+unconditionally re-tiles and repaints an entire source, which is invisible on a static map and
+expensive on an animated one. When an update changes only feature *properties* — the values driving
+the colour ramp — the component emits maplibre-gl's incremental `updateData()` instead. The fast
+path is deliberately strict, and needs all of: the same feature count, a `string`/`number` `id` on
+every feature in the same order, and geometry that is the **same object** as last time (not merely
+deep-equal). Structurally comparing polygon rings would cost about what the re-tile costs, and a
+false positive would paint stale geometry. Reuse your geometry objects across frames — the
+efficient way to build an animation anyway — and the fast path applies; otherwise it falls back to
+`setData()` with no change in behaviour. Peers predating `updateData()` always take the old path.
+
+**Feature properties are tiled, and therefore bounded in numeric magnitude.** MapLibre GL tiles
+every GeoJSON source through a worker into a protobuf vector tile, so a property carrying a huge
+integer throws *inside that worker* — "Given varint doesn't fit into 10 bytes". That throw is not
+catchable by your app and not a rejected promise; it reaches you only as an opaque message on
+`lr-map`'s own error handler, while the rest of the layer still paints, so one bad feature in a
+large collection is invisible until someone walks the data by hand. Both `choropleth.geojson` and
+`dataLayers[].geojson` are now pre-scanned (first 10,000 features) and any numeric property beyond
+`Number.MAX_SAFE_INTEGER` draws a dev-mode warning naming the feature and the property. Carry a
+reduced figure in the feature — a log, a bucket, an index — and keep the exact value in your own
+payload beside the map.
+
 - `label: string = ''` — purpose-specific accessible name for MapLibre's actual focusable canvas.
   A nonempty host `aria-label` remains on the host and is not duplicated onto the canvas; the canvas
   uses `label` or the localized map name. An explicitly empty host `aria-label` is preserved as an
@@ -102,13 +159,20 @@ shared `maplibre-gl` import without constructing a map or allocating a WebGL con
 an element.
 
 **Events:** `lr-map-load` (fired once, after the underlying map's own `'load'`), `lr-map-click`
-(frozen `detail: { readonly lngLat: readonly [lng, lat], readonly feature? }`; the tuple and any
-hit GeoJSON feature are detached and recursively frozen — feature is only populated if a
-choropleth fill layer exists and was hit)
+(frozen `detail: { readonly lngLat: readonly [lng, lat], readonly feature?, readonly origin?,
+readonly sourceId? }`; the tuple and any hit GeoJSON feature are detached and recursively frozen).
+`feature` resolves against the choropleth fill layer **and** every applied `dataLayers`
+fill/line/circle layer, topmost first — so a shape painted through `dataLayers` is identifiable
+instead of being indistinguishable from empty space. `origin` is `'choropleth'` or `'data-layer'`,
+and `sourceId` carries the authored `dataLayers[].sourceId` for a data-layer hit; both are
+`undefined` whenever `feature` is
 
-**Slots:** none.
+**Slots:** `legend` — custom legend content, rendered inside the legend panel's own layout so it
+stays positioned with the map instead of floating beside it. Supplying it opens the panel even
+when `legend` and `legendGradient` are both empty.
 
-**CSS parts:** `base`, `container`, `legend`, `legend-swatch`, `legend-limit`, `marker`, `popup`,
+**CSS parts:** `base`, `container`, `legend`, `legend-swatch`, `legend-gradient`, `legend-lo`,
+`legend-hi`, `legend-limit`, `marker`, `popup`,
 `popup-content`, `popup-close-button`, `attribution`, `attribution-toggle`, `error`.
 `legend` is a localized `role="group"` containing a real list associated to the map canvas with
 `aria-describedby`; each entry is a `listitem`, decorative swatches are inert/accessibility-hidden,

package/llms/components/lr-markdown-core.md

@@ -36,8 +36,9 @@ support (`highlights`, `activeHighlightId`, `scrollToAnchor()`, the `lr-highligh
 section above for the full write-up of shared behavior.
 
 **Properties:** `content: string = ''`, `tabSize: number = 4` (attribute `tab-size`) — the same
-finite-integer-guarded leading-indentation expansion used by `<lr-markdown>`; values outside 1–32
-or non-finite values fall back to `4`, independently of rendered code's
+finite-integer-guarded leading-indentation expansion used by `<lr-markdown>`; finite values are
+clamped to `[1, 32]` (`0` becomes `1`, `33` becomes `32`), and only non-finite values (`NaN`,
+`Infinity`) fall back to `4`, independently of rendered code's
 `--lr-code-block-tab-size`; `marked: LyraMarkedParser | undefined` (readonly, no attribute) — this
 instance's isolated peer-neutral configurable parser; `htmlMode: 'sanitize' | 'escape' | 'trusted' =
 'sanitize'` (attribute `html-mode`), `gfm: boolean = true`, `linkTarget: string | null = '_blank'` (attribute

package/llms/components/lr-media-card.md

@@ -30,13 +30,18 @@ final.
 - `mimeType: string = ''` (attribute `mime-type`) — drives auto-detection when `kind` is unset.
 - `filename: string = ''` — shown in the file-chip fallback, used as the download link's suggested
   filename, and folded into the accessible name.
-- `alt: string = ''` — alt text for the image case (and reused as a video label fallback). Falls
-  back to `filename`, then a generic per-kind description.
-- `accessibleLabel: string = ''` (attribute `aria-label`) — a declarative attribute names the host
-  as a whole while its nested button/link keeps a purpose-specific localized action name. A
-  property-only assignment can override the nested action when no host label is present. Image alt
-  text and the native video's own purpose label remain independent; an explicitly empty host still
-  leaves every interactive descendant named.
+- `alt?: string` — alt text for the image case (and reused as a video label fallback). Unset falls
+  back to `filename`, then a generic per-kind description. An explicit `alt=""` survives to the
+  rendered `<img alt="">`, which is the HTML idiom for a decorative image — same contract as
+  `<lr-image-viewer>` and `<lr-document-preview>`. The `<video>` case is deliberately outside that
+  carve-out: an empty `alt` there still falls through to `filename`/the generic description, because
+  an empty accessible name would leave an interactive player unnamed rather than mark it decorative.
+- `accessibleLabel: string | null = null` (attribute `aria-label`) — a declarative attribute names
+  the host as a whole while its nested button/link keeps a purpose-specific localized action name. A
+  property-only assignment can override the nested action when no host label is present. An explicit
+  empty string behaves like the unset `null` default — both fall through to the generated
+  purpose-specific name. Image alt text and the native video's own purpose label remain independent;
+  an explicitly empty host still leaves every interactive descendant named.
 - `maxHeight: string = ''` (attribute `max-height`) — a CSS length (e.g. `"16rem"`); once set,
   overrides the `--lr-media-card-max-height` custom property for this instance only (applied
   inline on `[part="base"]`, so it reliably wins over a `:host{}`-declared default from outside the
@@ -102,12 +107,23 @@ sizing), `--lr-focus-ring-*`, `--lr-transition-fast`.
 **Optional peer deps:** none.
 
 ```html
-<lr-media-card kind="image" src="https://example.com/photo.jpg" alt="Screenshot" filename="photo.jpg"
-  @lr-media-open=${(e) => openLightbox(e.detail.src)}
-></lr-media-card>
-<lr-media-card kind="file" src="https://example.com/report.pdf" filename="report.pdf"
-  @lr-before-media-download=${(e) => shouldUseNativeDownload || e.preventDefault()}
+<lr-media-card
+  id="image-card"
+  kind="image"
+  src="https://example.com/photo.jpg"
+  alt="Screenshot"
+  filename="photo.jpg"
 ></lr-media-card>
+<lr-media-card id="file-card" kind="file" src="https://example.com/report.pdf" filename="report.pdf">
+</lr-media-card>
+<script type="module">
+  document
+    .getElementById("image-card")
+    .addEventListener("lr-media-open", (e) => openLightbox(e.detail.src));
+  document
+    .getElementById("file-card")
+    .addEventListener("lr-before-media-download", (e) => shouldUseNativeDownload || e.preventDefault());
+</script>
 ```
 
 **Safe-URL checking.** `src` is validated by internal sink-specific helpers before it's

package/llms/components/lr-message-parts.md

@@ -74,7 +74,8 @@ import "@aceshooting/lyra-ui/components/conversation/message-parts/message-parts
 - `lr-copy` event — Passthrough from rendered JSON content.
 - `lr-highlight-activate` event — Passthrough from rendered Markdown.
 - `lr-link-click` event — Passthrough from rendered Markdown.
-- `lr-preview-request` event — Cancelable passthrough from a rendered attachment.
+- `lr-preview-request` event — Passthrough from a rendered attachment. Not cancelable as of 10.0.0:
+  `<lr-attachment-chip>` dropped the flag, since it owns no preview default action to veto.
 - `lr-remove` event — Passthrough from a rendered attachment.
 - `lr-render-error` event — Passthrough from rendered Markdown, tool-result, or widget content.
 - `lr-retry` event — Passthrough from a rendered attachment.

package/llms/components/lr-model-select.md

@@ -225,19 +225,18 @@ shared tokens — `--lr-space-xs/-s`, `--lr-color-border/-surface/-brand/-brand-
 **Optional peer deps:** none.
 
 ```html
-<lr-model-select
-  provider="openai"
-  .catalog=${[
-    { id: 'gpt-4o', label: 'GPT-4o', icon: '✦' },
-    { id: 'gpt-4o-mini', label: 'GPT-4o mini' },
-  ]}
-  value="gpt-4o"
-  placeholder="Choose a model…"
-  @lr-change=${(e) => setModel(e.detail.value, e.detail.inCatalog)}
-></lr-model-select>
+<lr-model-select provider="openai" value="gpt-4o" placeholder="Choose a model…"></lr-model-select>
 
 <!-- No fixed catalog yet: falls back to free-text entry -->
 <lr-model-select provider="ollama" placeholder="Type a model id…" allow-custom></lr-model-select>
+<script type="module">
+  const select = document.querySelector("lr-model-select");
+  select.catalog = [
+    { id: "gpt-4o", label: "GPT-4o", icon: "✦" },
+    { id: "gpt-4o-mini", label: "GPT-4o mini" },
+  ];
+  select.addEventListener("lr-change", (e) => setModel(e.detail.value, e.detail.inCatalog));
+</script>
 ```
 
 **Known gotchas:**

package/llms/components/lr-model-settings-panel.md

@@ -72,15 +72,15 @@ selector label), `temperature-row`, `temperature-label`, `temperature-value`
 internally (both imported unconditionally as side effects, not optional).
 
 ```html
-<lr-model-settings-panel
-  provider="OpenAI"
-  .catalog=${['gpt-4o', 'gpt-4o-mini', 'gpt-4.1']}
-  model="gpt-4o"
-  temperature="0.7"
-  @lr-change=${(e) => console.log(e.detail)}
-></lr-model-settings-panel>
-
-<lr-model-settings-panel layout="compact" .catalog=${catalog}></lr-model-settings-panel>
+<lr-model-settings-panel provider="OpenAI" model="gpt-4o" temperature="0.7"></lr-model-settings-panel>
+
+<lr-model-settings-panel layout="compact"></lr-model-settings-panel>
+<script type="module">
+  const [panel, compactPanel] = document.querySelectorAll("lr-model-settings-panel");
+  panel.catalog = ["gpt-4o", "gpt-4o-mini", "gpt-4.1"];
+  panel.addEventListener("lr-change", (e) => console.log(e.detail));
+  compactPanel.catalog = catalog;
+</script>
 ```
 
 The internal `lr-slider` renders with its own value readout suppressed (`.showValue=${false}`);

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

@@ -30,7 +30,7 @@ graph data) and never mutates a graph.
 - `label: string = ''` — fallback name for the stable group. A non-empty host `aria-label` makes
   the host the sole overall owner; an explicitly empty host label stays empty on the group
 
-**Events:** `lr-entity-activate` (`detail: { entityId }`, a row's node button was activated),
+**Events:** `lr-entity-select` (`detail: { entityId }`, a row's node button was activated),
 `lr-node-expand` (`detail: { nodeId }`, a row's expand button was activated — deliberately the same
 name and detail shape as `lr-graph`'s own event, so one host handler serves both).
 

package/llms/components/lr-notebook-viewer.md

@@ -120,9 +120,12 @@ each tone's highlighted-cell background. `--lr-notebook-viewer-highlight-active-
 `text/plain`).
 
 ```html
-<lr-notebook-viewer .notebook=${result} max-height="30rem"
-  @lr-load=${(e) => console.log(e.detail.cellCount, 'cells')}
-></lr-notebook-viewer>
+<lr-notebook-viewer max-height="30rem"></lr-notebook-viewer>
+<script type="module">
+  const viewer = document.querySelector("lr-notebook-viewer");
+  viewer.notebook = result;
+  viewer.addEventListener("lr-load", (e) => console.log(e.detail.cellCount, "cells"));
+</script>
 ```
 
 A notebook major version outside 4.0–4.5, an invalid shape, or more than 2,000 cells renders a

package/llms/components/lr-option.md

@@ -337,7 +337,10 @@ box visibly (nothing is clipped or made unreachable), so leave it unset there.
 plain-text contract even when a separate WA `label` override is present.
 
 **Events:** `lr-option-change` — bubbles when the option's label or selectable data changes so
-its parent `lr-combobox` or `lr-select` can refresh its normalized option rows.
+its parent `lr-combobox` or `lr-select` can refresh its normalized option rows. It is a private
+child-to-parent refresh signal, not a picker event: the owning `lr-combobox`/`lr-select` consumes
+it and stops it, so it never reaches a listener on the picker host (whose own contract is
+`lr-change`/`lr-input`/`change`/`input`). Listen on the `<lr-option>` itself to observe it.
 
 **Slots:** default (visible label), `start`/`end` (WA adornments), and `prefix`/`suffix` (Shoelace
 aliases). `start` and `prefix` project into one leading wrapper; `end` and `suffix` project into one
@@ -433,6 +436,6 @@ synchronous and fires no `input`/`change`/`lr-change` event.
 
 **Additional API surface:**
 
-- `part="tag-label"` — The wrapping/ellipsis-safe selected-tag label.
+- `part="tag-label"` — The selected-tag label. Kept on one line and truncated with an ellipsis at `--tag-max-size` (default `var(--lr-size-5rem)`), rather than wrapped. Note that `lr-select`'s tag of the same name defaults to `var(--lr-size-12rem)`, so the same `--tag-max-size` value yields a wider tag there.
 
 ---

package/llms/components/lr-pdf-viewer.md

@@ -32,7 +32,9 @@ current page and
 `zoom: number = 1` is clamped to `0.25`–`4`. `maxHeight: string = ''` (attribute `max-height`) is a
 CSS length that, once set, overrides `--lr-pdf-viewer-height` — the block size of the virtualized
 page list — declaratively, writing it inline on `[part="base"]`; invalid CSS `max-height` values,
-declaration breaks, and `url()` are ignored. `anchorKinds: readonly LyraAnchorKind[] = ['page',
+declaration breaks, and `url()` are ignored. `workerSrc: string = ''` (attribute `worker-src`) is the
+URL of the PDF.js web worker chunk — see **Configuring the PDF.js worker** below.
+`anchorKinds: readonly LyraAnchorKind[] = ['page',
 'text-quote', 'region']` (this viewer's supported `LyraAnchor.kind` values for the shared
 anchor-target contract). The other inherited anchor-target properties are `highlights:
 LyraHighlight[] = []` (property only; reassign after mutation), `activeHighlightId: string | null =
@@ -49,7 +51,8 @@ nonnegative dimensions.
 - `lr-load` — `detail: { pageCount }` — the document reached `ready`. `page` is reset to `1` first.
 - `lr-page-change` — `detail: { page, pageCount }` — fired for scroll-driven page crossings as well
   as `page` assignments and `nextPage()`/`previousPage()`/`goToPage()`.
-- `lr-zoom-change` — `detail: { zoom }`.
+- `lr-zoom-change` — `detail: { zoom }` — fired for `zoom` assignments as well as
+  `zoomIn()`/`zoomOut()`. Never fired for the initial `1`, only for a transition away from it.
 - `lr-search-change` — `detail: { query, matchCount, matchCountExact, activeIndex }` — from `search()`/`searchNext()`/
   `searchPrevious()`/`clearSearch()` and effective-locale re-evaluation. A `src` change invalidates document-relative matches and emits
   the canonical reset `{ query: '', matchCount: 0, matchCountExact: true, activeIndex: -1 }`.
@@ -64,6 +67,30 @@ nonnegative dimensions.
   `pageViewerSnapshot` (`identity`, `status`, `page`, `pageCount`). `identity` changes for every load,
   including same-count replacements.
 
+**`lr-page-change`/`lr-zoom-change` are state broadcasts, not user-intent signals.** This differs
+deliberately from the same-named `<lr-pagination>` event and from `<lr-pan-zoom>`'s `lr-zoom-change`,
+and the distinction is worth internalizing before wiring a handler. Pagination and pan-zoom are
+*controlled*: pagination never mutates its own `page`, so its event is a request the host applies,
+and pan-zoom's `zoom` is bound by a parent, so echoing a programmatic write back would feed a loop.
+This viewer instead *owns* `page` and `zoom` — scrolling the page list changes `page` with no
+consumer action at all — so there is no useful "the user did this" subset to isolate, and every
+accepted transition is announced identically: scrolling, `nextPage()`/`previousPage()`/`goToPage()`,
+`zoomIn()`/`zoomOut()`, anchor resolution, the reset to page 1 when a new `src` finishes loading,
+and a plain `viewer.page = 3` / `viewer.zoom = 2` assignment. A handler that mirrors the event back
+into the property it came from is therefore idempotent rather than looping, but it is also
+redundant — read the property, or `pageViewerSnapshot`, instead.
+
+A write that clamps or rounds back onto the value already in effect is not a transition and stays
+silent: on a 3-page document already showing page 1, `viewer.page = -7` and `viewer.page = 1.4` both
+settle on page 1 and emit nothing, and `viewer.zoom = 999` at 4× emits nothing.
+
+For page-addressed integrations prefer the atomic `pageViewerSnapshot` /
+`lr-page-viewer-state-change` channel over this pair: it carries page, count, load status and
+document `identity` together, and a late subscriber can read the current value synchronously instead
+of having missed the announcement. `<lr-page-rail>` binds that channel for any viewer exposing
+`pageViewerSnapshot` — including this one — and falls back to `lr-load`/`lr-page-change` only for
+older structural sources that do not.
+
 **Methods:** `nextPage()`, `previousPage()`, `zoomIn()`, and `zoomOut()` update the corresponding
 controlled state within its supported range. `getPageText(page)` resolves the raw reading-order text
 of one page (per-page LRU-cached, 64 pages), rejecting on no loaded document or an out-of-range page.
@@ -121,6 +148,39 @@ a PDF is opened. An absent `pdfjs-dist` fails closed and renders
 `[part="error"]` with the localized `pdfViewerMissingLibrary` message — there is no partial PDF
 rendering without it.
 
+**Configuring the PDF.js worker.** PDF.js renders in a web worker and rejects every document with
+`No "GlobalWorkerOptions.workerSrc" specified.` until it has been told where that worker lives. The
+worker is a separate file inside the peer (`pdfjs-dist/build/pdf.worker.min.mjs`) that only the
+application's own bundler can turn into a real URL — a bare package specifier does not resolve in a
+browser without an import map, and resolving it against this library's own module URL would point
+into `@aceshooting/lyra-ui`'s files, where no worker exists. So a bundled application supplies it,
+either way round:
+
+```ts
+// 1. Per element, through the public property/attribute.
+import workerUrl from 'pdfjs-dist/build/pdf.worker.min.mjs?worker&url'; // Vite; see your bundler
+const viewer = document.querySelector('lr-pdf-viewer');
+viewer.workerSrc = workerUrl;
+// or, declaratively: <lr-pdf-viewer worker-src="/assets/pdf.worker.min.mjs"></lr-pdf-viewer>
+
+// 2. Once for the whole application, on PDF.js's own singleton, before any viewer loads a document.
+import { GlobalWorkerOptions } from 'pdfjs-dist';
+GlobalWorkerOptions.workerSrc = workerUrl;
+```
+
+`workerSrc` accepts a document-relative URL (resolved against the document base) as well as an
+absolute one; only `http:`, `https:`, `blob:` and `file:` URLs are accepted, and anything else — a
+`javascript:` or `data:` URL in particular — is ignored rather than handed to `new Worker()`.
+
+`GlobalWorkerOptions` is PDF.js's process-wide singleton and the PDF.js module itself is loaded once
+per page, so `workerSrc` is applied only while that singleton is still unset. Two consequences worth
+knowing before reaching for the per-element form: a worker the application configured itself is never
+overwritten, and when several viewers carry different `workerSrc` values only the first one to load
+PDF.js takes effect for the whole page. Assigning `workerSrc` after PDF.js has already loaded is not
+silently dropped — it is re-applied on the next load — but it still cannot displace an
+already-configured worker. Option 2 above is the right choice for an application that wants one
+explicit worker everywhere.
+
 Remote resources are capped at 25 MB; exceeding it surfaces the localized
 `documentPreviewResourceTooLarge` message instead of the PDF.
 

package/llms/components/lr-pie-chart.md

@@ -7,7 +7,7 @@
 - **Family** `components/charts/` — see `llms/index.md` for its siblings
 - **Status** `stable` since `4.0.0` — see the maturity and deprecation policy in `llms/shared.md`
 - **Deprecations** none
-- **Optional peers** `chart.js`, `chartjs-plugin-datalabels`, `chartjs-plugin-zoom` — see `llms/peers.md`
+- **Optional peers** `chart.js`, `chartjs-plugin-annotation`, `chartjs-plugin-datalabels`, `chartjs-plugin-zoom` — see `llms/peers.md`
 - **Themeable via** 15 parts, 33 custom properties — see this component's own `@csspart`/`@cssprop` list below
 - **Documented with** `lr-line-chart`, `lr-bar-chart`, `lr-doughnut-chart`, `lr-radar-chart`, `lr-polar-area-chart`, `lr-bubble-chart`, `lr-scatter-chart` (same section below)
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
@@ -25,7 +25,8 @@ and behavior there. **See `llms/components/lr-chart.md` for the details, code ex
 of every entry in these lists.**
 
 **Properties:** `description`, `grid`, `indexAxis` (`index-axis`), `label`, `hiddenDatasets`, `legendPosition`
-(`legend-position`), `max`, `min`, `plugins`, `stacked`, `withoutAnimation` (`without-animation`),
+(`legend-position`), `max`, `min`, `plugins`, `scaleType` (`scale-type`), `annotations`,
+`stacked`, `withoutAnimation` (`without-animation`),
 `withoutLegend` (`without-legend`), `withoutTooltip` (`without-tooltip`), `xLabel` (`x-label`),
 `yLabel` (`y-label`), plus additive `labels`, `datasets`, `valueFormatter`, `formatter`, `area`, `zoom`,
 `height`, `y2Label` (`y2-label`), `beginAtZero` (`begin-at-zero`), `dataLabels`
@@ -66,7 +67,7 @@ together. The mirrored hooks are `--border-color-1`,
 `zoom` is set, and `chartjs-plugin-datalabels` only once `data-labels`/`stack-totals` is set.
 
 ```html
-<lr-bar-chart legend></lr-bar-chart>
+<lr-bar-chart></lr-bar-chart>
 <lr-pie-chart></lr-pie-chart>
 <script>
   document.querySelector('lr-bar-chart').labels = ['A', 'B'];

package/llms/components/lr-polar-area-chart.md

@@ -7,7 +7,7 @@
 - **Family** `components/charts/` — see `llms/index.md` for its siblings
 - **Status** `stable` since `4.0.0` — see the maturity and deprecation policy in `llms/shared.md`
 - **Deprecations** none
-- **Optional peers** `chart.js`, `chartjs-plugin-datalabels`, `chartjs-plugin-zoom` — see `llms/peers.md`
+- **Optional peers** `chart.js`, `chartjs-plugin-annotation`, `chartjs-plugin-datalabels`, `chartjs-plugin-zoom` — see `llms/peers.md`
 - **Themeable via** 15 parts, 33 custom properties — see this component's own `@csspart`/`@cssprop` list below
 - **Documented with** `lr-line-chart`, `lr-bar-chart`, `lr-pie-chart`, `lr-doughnut-chart`, `lr-radar-chart`, `lr-bubble-chart`, `lr-scatter-chart` (same section below)
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
@@ -25,7 +25,8 @@ and behavior there. **See `llms/components/lr-chart.md` for the details, code ex
 of every entry in these lists.**
 
 **Properties:** `description`, `grid`, `indexAxis` (`index-axis`), `label`, `hiddenDatasets`, `legendPosition`
-(`legend-position`), `max`, `min`, `plugins`, `stacked`, `withoutAnimation` (`without-animation`),
+(`legend-position`), `max`, `min`, `plugins`, `scaleType` (`scale-type`), `annotations`,
+`stacked`, `withoutAnimation` (`without-animation`),
 `withoutLegend` (`without-legend`), `withoutTooltip` (`without-tooltip`), `xLabel` (`x-label`),
 `yLabel` (`y-label`), plus additive `labels`, `datasets`, `valueFormatter`, `formatter`, `area`, `zoom`,
 `height`, `y2Label` (`y2-label`), `beginAtZero` (`begin-at-zero`), `dataLabels`
@@ -66,7 +67,7 @@ together. The mirrored hooks are `--border-color-1`,
 `zoom` is set, and `chartjs-plugin-datalabels` only once `data-labels`/`stack-totals` is set.
 
 ```html
-<lr-bar-chart legend></lr-bar-chart>
+<lr-bar-chart></lr-bar-chart>
 <lr-pie-chart></lr-pie-chart>
 <script>
   document.querySelector('lr-bar-chart').labels = ['A', 'B'];

package/llms/components/lr-popover.md

@@ -52,6 +52,11 @@ A click-triggered, light-dismiss floating surface positioned with the shared Flo
   attribute wins by presence, including `aria-label=""`; only when it is absent does the property
   or localized "Popover" ("Menu" when `popupRole` is `menu`) fallback apply
 - `popupRole: 'dialog'|'menu' = 'dialog'` (attribute `popup-role`)
+- `disabled: boolean = false` (reflected, new in 10.0.0) — prevents opening the popover; pointer,
+  keyboard, and programmatic `show()`/`open = true` are all refused while set. Becoming disabled also
+  closes an already-open popover, and initial `disabled` plus `open` normalizes closed in either
+  attribute order. `lr-dropdown` now inherits this from `lr-popover` rather than declaring its own;
+  its consumer-facing behavior is unchanged
 
 To preserve the previous Lyra-shaped defaults explicitly, use
 `placement="bottom-start" distance="4" without-arrow`; origin-aware migration emits those tokens.

package/llms/components/lr-progress-ring.md

@@ -20,6 +20,7 @@ A circular progress indicator with the same value contract as `lr-progress-bar`.
 **Properties:** `value: number = 0` (reflected), `max: number = 100`, `indeterminate: boolean = false`
 (reflected), `variant: LyraProgressVariant = 'brand'` (reflected, added in 9.0.0 — matches sibling
 `lr-progress-bar`'s semantic-palette vocabulary: `neutral`/`brand`/`success`/`warning`/`danger`),
+`showValue: boolean = false` (attribute `show-value`),
 `label: string = ''` (the mapped accessible-name property), and
 `accessibleLabel: string = ''` (attribute `accessible-label`; a Lyra compatibility
 accessible-name spelling retained by this progress component, while several sibling components use
@@ -29,7 +30,13 @@ visible default-slot text when supplied, then the localized "Progress". Non-fini
 `value`/`max` are normalized (`max <= 0` falls
 back to `100`, `value` clamps to `[0, max]`) rather than producing NaN geometry.
 **Slots:** default — replaces the built-in center label, which otherwise renders the rounded
-percentage (and nothing at all while `indeterminate`).
+percentage **only when `show-value` is set** (and nothing at all while `indeterminate`).
+**Breaking in 10.0.0:** a determinate ring used to render its percentage unconditionally, with no way
+to suppress it short of slotting replacement content. It now gains `showValue`/`show-value` defaulting
+to `false`, exactly matching `lr-progress-bar` — which is what "the same value contract as
+`lr-progress-bar`" above has always claimed but did not deliver. Add `show-value` to keep the
+percentage. `aria-valuetext` still carries it regardless, mirroring `lr-progress-bar`'s own
+independence there, so the accessible value is unaffected.
 Its accessible text uses the same visibility filtering, forwarding-slot mutation/reassignment
 tracking, and explicit-empty host-label precedence as `lr-progress-bar`.
 **Live members:** `indicator: SVGCircleElement | null` returns the rendered indicator circle (or

package/llms/components/lr-prompt-studio.md

@@ -27,7 +27,7 @@ persistence.
 `versions: readonly PromptStudioVersion[] = []` is a property-only host-controlled input;
 empty/blank message and version ids are omitted and later duplicates use deterministic first-wins
 identity before rendering, editing, focus, selection, and events;
-`selectedVersionId: string = ''` (attribute `selected-version-id`); `label: string = ''`;
+`selectedVersionId: string | null = null` (attribute `selected-version-id`); `label: string = ''`;
 `heading: string = ''` — visible toolbar heading, falling back to the localized Prompt Studio
 label when unset;
 `running: boolean = false`, `disabled: boolean = false`, and `reorderable: boolean = false`

package/llms/components/lr-provenance-panel.md

@@ -35,8 +35,10 @@ chip` row, one `lr-path-strip` per relationship, `lr-community-card`, `lr-chunk-
 **Events:** `lr-toggle` (`detail: { section, expanded }`, a section header was toggled —
 `section` is `'entities' | 'relationships' | 'communities' | 'chunks'`). Because the panel is a
 conduit, every affordance it renders also reaches a listener on the panel itself, and all are
-part of its typed event map: `lr-entity-activate` (`detail: { entityId, occurrenceIndex? }`, from an entity chip, community
-card member, or path-strip node), `lr-entity-open` (`detail: { entityId }`, an entity chip double-click or
+part of its typed event map: `lr-entity-select` (`detail: { entityId }`, from an entity chip),
+`lr-entity-activate` (`detail: { entityId, occurrenceIndex? }`, from a community card member or
+path-strip node — the only name either one emits, and the only one carrying `occurrenceIndex`),
+`lr-entity-open` (`detail: { entityId }`, an entity chip double-click or
 Space), `lr-drill` (`detail: { communityId }`, a community card's title, drill button, or overflow chip), and
 `lr-relation-activate` (`detail: { relation, sourceNodeId?, targetNodeId?, occurrenceIndex }`, a relationship path-strip
 edge), plus `lr-chunk-open` (`detail: { chunkId, sourceId, anchor? }`) and `lr-expand`

package/llms/components/lr-qr-code.md

@@ -6,7 +6,7 @@
 - **Class** `LyraQrCode`, also available unregistered from `@aceshooting/lyra-ui/components/media/qr-code/qr-code.class.js`
 - **Family** `components/media/` — see `llms/index.md` for its siblings
 - **Status** `stable` since `4.0.0` — see the maturity and deprecation policy in `llms/shared.md`
-- **Deprecated part** `base` since `8.2.3`; use part `::part(qr-code)`; removal not before `10.0.0` — The qr-code part names the rendered code wrapper explicitly; base remains on that same node during the compatibility window.
+- **Deprecated part** `base` since `8.2.3`; use part `::part(qr-code)`; removal not before `10.0.0` — The qr-code part names the rendered code wrapper explicitly; base remains on that same node during the compatibility window. That version is a policy floor, not a plan: `wa-qr-code` still publishes `base` as a deprecated part and `sl-qr-code` still publishes it as its only, undeprecated part, so this alias stays for as long as either upstream ships it.
 - **Optional peers** `qrcode` — see `llms/peers.md`
 - **Themeable via** 6 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-radar-chart.md

@@ -7,7 +7,7 @@
 - **Family** `components/charts/` — see `llms/index.md` for its siblings
 - **Status** `stable` since `4.0.0` — see the maturity and deprecation policy in `llms/shared.md`
 - **Deprecations** none
-- **Optional peers** `chart.js`, `chartjs-plugin-datalabels`, `chartjs-plugin-zoom` — see `llms/peers.md`
+- **Optional peers** `chart.js`, `chartjs-plugin-annotation`, `chartjs-plugin-datalabels`, `chartjs-plugin-zoom` — see `llms/peers.md`
 - **Themeable via** 15 parts, 33 custom properties — see this component's own `@csspart`/`@cssprop` list below
 - **Documented with** `lr-line-chart`, `lr-bar-chart`, `lr-pie-chart`, `lr-doughnut-chart`, `lr-polar-area-chart`, `lr-bubble-chart`, `lr-scatter-chart` (same section below)
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
@@ -25,7 +25,8 @@ and behavior there. **See `llms/components/lr-chart.md` for the details, code ex
 of every entry in these lists.**
 
 **Properties:** `description`, `grid`, `indexAxis` (`index-axis`), `label`, `hiddenDatasets`, `legendPosition`
-(`legend-position`), `max`, `min`, `plugins`, `stacked`, `withoutAnimation` (`without-animation`),
+(`legend-position`), `max`, `min`, `plugins`, `scaleType` (`scale-type`), `annotations`,
+`stacked`, `withoutAnimation` (`without-animation`),
 `withoutLegend` (`without-legend`), `withoutTooltip` (`without-tooltip`), `xLabel` (`x-label`),
 `yLabel` (`y-label`), plus additive `labels`, `datasets`, `valueFormatter`, `formatter`, `area`, `zoom`,
 `height`, `y2Label` (`y2-label`), `beginAtZero` (`begin-at-zero`), `dataLabels`
@@ -66,7 +67,7 @@ together. The mirrored hooks are `--border-color-1`,
 `zoom` is set, and `chartjs-plugin-datalabels` only once `data-labels`/`stack-totals` is set.
 
 ```html
-<lr-bar-chart legend></lr-bar-chart>
+<lr-bar-chart></lr-bar-chart>
 <lr-pie-chart></lr-pie-chart>
 <script>
   document.querySelector('lr-bar-chart').labels = ['A', 'B'];

package/llms/components/lr-rag-eval-dashboard.md

@@ -7,7 +7,7 @@
 - **Family** `components/retrieval/` — see `llms/index.md` for its siblings
 - **Status** `stable` since `7.0.0` — see the maturity and deprecation policy in `llms/shared.md`
 - **Deprecations** none
-- **Optional peers** `chart.js`, `chartjs-plugin-datalabels`, `chartjs-plugin-zoom` — see `llms/peers.md`
+- **Optional peers** `chart.js`, `chartjs-plugin-annotation`, `chartjs-plugin-datalabels`, `chartjs-plugin-zoom` — see `llms/peers.md`
 - **Themeable via** 13 parts, 0 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`
 
@@ -36,7 +36,7 @@ duplicates are omitted first-wins before metric fallback, slice derivation/filte
 history, counts, rendering, or actions.
 
 **Events:** `lr-metric-change` (`{ metricId }`), `lr-slice-change` (`{ slice }`), and
-`lr-run-select` (`{ run }`). All are controlled intents; the component does not mutate the
+`lr-run-change` (`{ run }`). All are controlled intents; the component does not mutate the
 corresponding selection properties.
 
 **CSS parts:** `base`, `heading`, `slices`, `slice`, `slice-selected`, `metrics`, `metric`,

package/llms/components/lr-random-content.md

@@ -101,3 +101,16 @@ behavior warning; direct SVG candidates and the documented animation vocabulary
   used (a11y-tree inconsistencies across engines).
 - Slot/focus microtasks and autoplay never queue new selection work while detached; reconnecting
   starts again from current state rather than replaying stale work.
+- Non-selected candidates are hidden by the component's own `::slotted([hidden])` rule, not by the
+  UA's. `::slotted(*)` sets `display: inline-block` on every candidate, and an author-origin
+  declaration always beats the user-agent `[hidden] { display: none }` — so the rule that restores
+  the native meaning of `hidden` is load-bearing, and an author overriding `display` on
+  `::slotted` content from outside must keep the hidden case at `display: none`.
+  `hidden="until-found"` is exempted, exactly as the UA rule exempts it.
+- **Before script runs, the first candidate is the one that shows.** Selection happens after the
+  first client render and works by setting `hidden`/`aria-hidden` on light-DOM siblings, which Lit
+  hydration never compares, so a server renderer can never produce it. Every candidate after the
+  first is therefore hidden by CSS until a selection has been applied: a server-rendered page — or
+  one whose script never runs — paints one candidate rather than the whole pool. Randomness itself
+  cannot survive SSR (there is no shared seed), so order the pool if a specific candidate should be
+  the pre-hydration one. With `items > 1` the pre-hydration paint is still a single candidate.

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

@@ -57,11 +57,16 @@ is pending.
 between rows.
 
 ```html
-<lr-reorder-list label="Form fields" @lr-reorder=${(e) => console.log(e.detail.order)}>
+<lr-reorder-list label="Form fields">
   <lr-reorder-item value="name">Name</lr-reorder-item>
   <lr-reorder-item value="email">Email</lr-reorder-item>
   <lr-reorder-item value="phone">Phone</lr-reorder-item>
 </lr-reorder-list>
+<script type="module">
+  document
+    .querySelector("lr-reorder-list")
+    .addEventListener("lr-reorder", (e) => console.log(e.detail.order));
+</script>
 ```
 
 **Known gotchas:**