@aceshooting/lyra-ui 29.0.2 → 29.1.0

package/llms/components/lr-diff-view.md

@@ -45,18 +45,25 @@ over each rendered line's own text, one match per line ordered by that same op i
   the same diff alignment. Unsupported attributes and untyped property writes normalize to
   reflected `unified`.
 - `language: string = ''` — a shiki-recognized language id. Highlighting activates only when this
-  has a matching entry in `languages` — there is deliberately no default full-table
+  has a matching entry in `languages` or `languageLoaders` — there is deliberately no default full-table
   `lr-code-block`-style fallback, so this component never reaches shiki's ~200-language
   dynamic-import table.
-- `languages?: Record<string, ShikiLanguageInput>` (attribute: false) — grammar definitions this
-  instance can highlight, same shape as `lr-code-block-core`'s own `languages`.
+- `languages?: Readonly<Record<string, ShikiLanguageInput>>` (attribute: false) — resolved grammar
+  definitions.
+- `languageLoaders?: Readonly<Record<string, ShikiLanguageLoader>>` (attribute: false) — lazy
+  grammar loaders. Concrete `languages` entries take priority on duplicate keys. Only the requested
+  loader runs; unused loader entries stay unresolved. Unset preserves concrete-grammar behavior.
+  Assign new map objects after editing entries.
 - `contextLines: number | undefined` (attribute: `context-lines`) — keeps this many unchanged
   lines around each change and collapses longer unchanged runs into a localized fold marker. The
   default `undefined` shows every line; negative and non-finite values also disable folding.
 - `maxLines: number = 5000` (attribute `max-lines`) — maximum logical lines accepted on either
   side. Larger input renders the localized `diffViewTooLarge` fallback without computing or
   highlighting the diff. `Infinity` relaxes this line-count ceiling, but the fixed aggregate
-  character and comparison-work ceilings remain in force.
+  character and comparison-work ceilings remain in force. Every value, including `Infinity`,
+  also enforces a hard 10,000-diff-operation render ceiling: at most 10,000 unified lines or
+  20,000 split cells, including empty cells. Larger diffs show the localized `limit` fallback.
+  Offscreen rows use `content-visibility: auto` to defer paint.
 - `anchorKinds: readonly LyraAnchorKind[] = ['line-range']` (this viewer's supported
   `LyraAnchor.kind` values for the shared anchor-target contract).
 
@@ -66,6 +73,12 @@ later valid grammar from being used; grammar values themselves remain opaque to
 Non-enumerable names do not consume language slots, but every inspected name counts toward the
 20,000 structural ceiling.
 
+Syntax highlighting accepts up to 8,192 UTF-16 code units on each input, inclusive. If either side
+exceeds that ceiling, both sides use plain text with a localized `[part="limit"]` notice when
+`language` is set. This highlighting fallback preserves admitted source text; the separate input,
+comparison, and diff-operation limits still apply. The fine-grained highlighter path does not
+import the default full-language-table loader.
+
 **Methods:** `search(query)` resolves the match count via a case-insensitive substring match over
 each rendered line's own text, ordered by `line-range` op index (empty/whitespace query behaves like
 `clearSearch()`); `searchNext()`/`searchPrevious()` advance/step back through matches (wrapping,
@@ -106,8 +119,8 @@ marker — plus `data-match`/`data-active-match` while a search result covers it
 technology exposes the change), `line-highlight-action` (the focusable button a resolved
 `highlights` entry adds to the line it first covers; emits `lr-highlight-activate`), `copy-button`
 (the copy affordance, only rendered while `copyable`; it stays pinned at the top while the view
-scrolls), `limit` (the localized over-`maxLines`
-fallback), `side` (one column in `layout="split"`, `data-side="old"|"new"`), `anchor-live-region`
+scrolls), `limit` (the localized input/render-limit fallback or syntax-highlighting ceiling
+notice), `side` (one column in `layout="split"`, `data-side="old"|"new"`), `anchor-live-region`
 (an aria-hidden, non-live shadow mirror of the latest anchor-jump message; the spoken copy is
 appended to the shared document-level polite sink only while the viewer and its composed ancestors
 are exposed to the accessibility tree).

package/llms/components/lr-document-library.md

@@ -9,7 +9,7 @@
 - **Release history** [CHANGELOG.md](../../CHANGELOG.md)
 - **Deprecations** none
 - **Optional peers** none
-- **Themeable via** 21 parts, 0 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 24 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`
 
 ---
@@ -20,6 +20,13 @@ Controlled searchable and filterable document inventory with versions, tags, own
 sorting, and bulk selection. It composes the table's bounded 100-row default, so a large document
 collection stays reachable through pagination without mounting an unbounded grid.
 
+With `dataSource` unset, the tag facet displays the first 500 locale-sorted distinct tags. A localized `[part="limit"]`
+note reports the omitted count. Search and a controlled `tagFilter` continue to match all admitted
+document tags, including tags outside the facet window. Matching rows, sorting, and folded search
+fields are reused when their inputs are unchanged; loading and selection updates reuse the current
+row projection. A custom `filter` that depends on mutable closure state can be refreshed with a
+keyless `requestUpdate()`. Publish document edits with a new outer array as described below.
+
 Own `tags: undefined` is treated like omitted tags; malformed tag arrays and entries remain invalid.
 Removing `search-term` clears search filtering without rewriting its `null` property readback; an
 explicitly empty query also clears filtering and a later query applies normally.
@@ -56,6 +63,53 @@ table. Omitted localizes the table's own `tableLoadFailed` default.
 `errorDescription: string = ''` (`error-description`) — failed-load supporting copy, forwarded to
 the nested table.
 
+The provider query type is `DocumentLibrarySourceQuery { readonly searchTerm: string;
+readonly tagFilter: readonly string[]; readonly sortKey: LibraryDocumentSortKey;
+readonly sortDir: 'asc' | 'desc'; readonly filter: LyraDocumentLibrary['filter'] }`.
+
+**Full-source paging:** Set property-only `dataSource: DocumentLibrarySource | undefined`
+(default `undefined`) to browse a host-owned logical collection. `DocumentLibrarySource` is
+`LyraPageSource<LibraryDocument, DocumentLibrarySourceQuery>`; both types are exported by the
+component entry and package root. The query contains `searchTerm`, readonly `tagFilter`,
+`sortKey`, `sortDir`, and the current `filter` callback. The provider applies AND-tag filtering
+and ordering to the complete collection. A custom `filter` replaces the default text predicate;
+they are not applied cumulatively. The query forwards `searchTerm` verbatim (null becomes empty).
+The provider supplies the callback's trimmed, request-locale-folded text argument and owns any
+remote translation of that callback. It must not filter only the returned page. Source-mode
+`tagFilter` accepts at most 500 keys; its legacy 10,000-key allowance applies only without a source.
+
+`sourcePage: number = 0` (`source-page`) is zero-based; `sourcePageSize: number = 100`
+(`source-page-size`) normalizes to 1–500. Readonly `sourceTotal: number | null` is the exact
+accepted query total, or `null` before a current authoritative result. The nested table converts
+to its one-based page convention, shows unknown-total/loading/error states, and delegates sorting
+to the source. Query or page-size changes reset to source page zero. An out-of-range page receives
+one corrective last-page request. No complete array, row index or full-source search corpus is
+built by the component.
+
+The provider implements the shared `query`, global `lookup` and `locate` contract from
+`@aceshooting/lyra-ui/data-sources.js`. Each accepted page must include `tags`, even when its
+catalogue is empty: bounded `{ values, total, unavailableSelected }` facets describe the global
+catalogue and supplied labels. Missing rows on the current page never prove a filter is absent;
+only `unavailableSelected` removes a controlled tag. Facet values are bounded to 500 and source
+rows to 500 tags and 65,536 display-text UTF-16 units each. Source-row tags render as complete text
+lists rather than one chip per tag. Malformed or oversized replies show a localized error.
+
+Bulk selection still contains up to 10,000 global IDs. The provider resolves them in sequential
+batches of at most 500; only authoritative global lookup absence removes an ID. The header
+checkbox selects or clears the loaded page while preserving off-page selections. Selection
+changes wait for lookup to complete; failures expose `selection-status` and `selection-retry`.
+User `lr-selection-change` carries the complete accepted ID list, and programmatic assignments
+remain silent. Page/query changes and page retry reuse the independent selected-record cache.
+`lr-filter-change.matchCount` reports the accepted global query total.
+
+A defined source takes display precedence over `documents`; it never overwrites that legacy
+getter. Invalid defined sources fail visibly. Setting `dataSource = undefined` restores the
+current legacy documents and their existing limits. The source remains host-owned by identity;
+after changing its contents or revision, reassign it (including the same object) or call unnamed
+`requestUpdate()`. Replacement, explicit refresh, locale change, disconnect and adoption revoke
+obsolete work. Named presentation updates reuse accepted data. Both source and legacy routes
+forward instance `strings` to the composed table.
+
 **Events:**
 
 - `lr-filter-change` — non-cancelable; fresh frozen readonly `{ searchTerm, tags, matchCount }`.
@@ -64,17 +118,18 @@ the nested table.
 - `lr-selection-change` — non-cancelable; fresh frozen readonly `{ documentIds }`.
 - `lr-open` — non-cancelable; frozen readonly `{ documentId }`.
 - `lr-retry-request` — cancelable, `detail: null`; the nested table's built-in retry button was
-  activated, only rendered while `error` is set. The library contains the child's request, then
+  activated while a host or provider load error is shown. The library contains the child's request, then
   emits its own canonical request. Preventing it leaves both library and table errors set; otherwise
-  the default clears them.
+  the default clears the host error and retries the current provider page when a source is set.
 
 **Slots:** `error` — replaces the nested table's built-in failed-load state, including its retry
-button, while `error` is set.
+button, while a host or provider load error is shown.
 
 **CSS parts:** `base`, `toolbar`, `search`, `tag-filter`, `selection-bar`, `selection-count`,
 `clear-selection`, `table`, `row`, `cell`, `header-cell`, `document-name`, `error-row`, `error-cell`,
 `error` (the nested table's built-in `lr-empty` host), `error-base`, `error-icon`, `error-heading`,
-`error-description`, `error-actions`, `retry-button`.
+`error-description`, `error-actions`, `retry-button`, `limit` (the count of distinct tags omitted
+from the facet), `selection-status` (source selection loading/error), and `selection-retry`.
 
 `selection-bar` is visible ordinary content, not a shadow live region. `selectedDocumentIds`
 assignments stay silent; each selection change the user makes (row or select-all checkbox, "Clear

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

@@ -9,6 +9,6 @@
 - **Release history** [CHANGELOG.md](../../CHANGELOG.md); family-wide breaking-change summaries: [charts](https://github.com/aceshooting/lyra-ui/blob/main/packages/lyra-ui/llms/charts.md)
 - **Deprecations** none
 - **Optional peers** `chart.js`, `chartjs-plugin-annotation`, `chartjs-plugin-datalabels`, `chartjs-plugin-zoom` — see `llms/peers.md`
-- **Themeable via** 17 parts, 39 custom properties — see `lr-line-chart.md`
+- **Themeable via** 18 parts, 39 custom properties — see `lr-line-chart.md`
 - **Documented with** `lr-line-chart`: see [lr-line-chart.md](./lr-line-chart.md).
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`

package/llms/components/lr-embedding-explorer.md

@@ -9,7 +9,7 @@
 - **Release history** [CHANGELOG.md](../../CHANGELOG.md); family-wide breaking-change summaries: [retrieval](https://github.com/aceshooting/lyra-ui/blob/main/packages/lyra-ui/llms/retrieval.md)
 - **Deprecations** none
 - **Optional peers** none
-- **Themeable via** 9 parts, 10 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 11 parts, 10 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`
 
 ---
@@ -19,6 +19,76 @@
 Dependency-free accessible 2D embedding projection viewer. Coordinates are projected by the host;
 the component only normalizes them into SVG, colors optional clusters, and emits selection events.
 
+**Complete spatial source:** `source: LyraSpatialPointSource<EmbeddingPoint & LyraSpatialPoint>
+| null = null` (attribute: false) takes precedence over `points` without copying the complete
+population. Setting `null` restores the legacy point-array route. `viewport: LyraSpatialBounds
+| null = null` (attribute: false) uses `{ minX, maxX, minY, maxY }`; `null` shows the complete global
+domain. Source storage, indexing and aggregation remain host-owned.
+
+```ts
+import type { EmbeddingPoint } from
+  "@aceshooting/lyra-ui/components/retrieval/embedding-explorer/embedding-explorer.class.js";
+import type {
+  LyraSpatialBounds, LyraSpatialPoint, LyraSpatialBin, LyraSpatialQuery,
+  LyraSpatialPointSource, LyraSpatialBinSelectDetail,
+} from "@aceshooting/lyra-ui/utilities/data-spatial.js";
+```
+
+The provider has immutable `revision`, safe nonnegative integer `count`, and complete global
+`bounds: LyraSpatialBounds | null`; bounds are null exactly for an empty source. Revision is a
+nonempty string of at most 256 UTF-16 units or a finite number. `query({ signal, bounds, maxPoints,
+maxBins })` returns `{ points, bins, matchedCount }`; `getPoint(id, { signal })` returns the exact
+original point or `null`. Both methods may return values or PromiseLike results. Source metadata,
+methods and payload fields must be own data properties; accessor-backed or sparse replies reject.
+Unknown point fields are excluded from the closed projection.
+
+Each exact/representative point supplies `{ id, sourceIndex, x, y, label?, sourceId?, cluster? }`.
+`sourceIndex` is a safe original zero-based index below `count`, independent of the representative
+array position; coordinates are finite and within global bounds. IDs are globally unique,
+nonblank and at most 256 UTF-16 units; `label` is at most 1,024 units, `sourceId` and string `cluster`
+at most 256 units, and numeric clusters must be finite. Query representatives and exact lookups
+must agree within a revision. Admission detects bounded duplicate/conflicting identities; global
+uniqueness and unseen data truth remain provider obligations.
+
+Each `LyraSpatialBin` has `{ bounds, count }` with positive safe `count`. Bin counts sum exactly
+to `matchedCount <= source.count`, covering every match in the current viewport. Representative
+points overlay that population and never add to its total. Bins may leave spatial holes but cannot
+overlap in their interiors; normal-axis ownership is half-open with inclusive final viewport
+edges. Representatives must belong to a bin and cannot outnumber its population. Collapsed global
+axes stay exactly collapsed and project at the center; a noncollapsed axis requires a positive
+viewport span contained in the global domain. No fabricated domain expansion is applied.
+
+Source mode requires normalized `maxRenderedPoints >= 3`, including for an empty source;
+smaller budgets show an error. The default remains 1,000 and ceiling 10,000. Two slots within that
+budget are reserved for independent controlled-selected and imperative-revealed exact points.
+For `A = maxRenderedPoints - 2`, `maxBins = ceil(A / 2)` and `maxPoints = A - maxBins`: default
+499 bins + 499 representatives + two exact slots. Unused capacity is not borrowed. Exact overlays
+deduplicate against representatives and each other. Each query admits at most 997,000 UTF-16
+metadata units; current/pending queries, exact records and bounded intent/revision strings share
+a 2,000,000-unit envelope. No full point array or all-ID map is retained.
+
+`revealSourcePoint(id: string): Promise<boolean>` resolves an exact original ID, minimally pans an
+explicit viewport while preserving its representable span/clamping to global bounds, waits for
+current query/rendering and focuses that point. A null viewport stays global. It leaves
+`selectedPointId` unchanged and emits no selection. Missing, invalid, obsolete, disconnected or
+unrepresentable-pan requests resolve `false`. Selected and revealed records have independent slots;
+a selected record may remain retained outside the visible viewport. Accessible point ordinals use
+original `sourceIndex + 1`, not representative order.
+
+**Events:** `lr-point-select` retains `{ point }` for exact original immutable point data, including ID and
+sourceIndex. Activating a density bin emits noncancelable `lr-spatial-bin-select` with frozen
+`LyraSpatialBinSelectDetail { revision, bounds, count }`, never an exact-point event. Source mode
+adds `bin` and `error` parts; `limit` reports the complete global count/domain and current viewport
+count/domain with density and overlay counts distinguished. The cluster legend describes retained
+point overlays rather than certifying all global clusters.
+
+Reassign even the same source, or call a keyless `requestUpdate()`, after revision/state changes.
+Named style/strings updates reuse admitted data. Replacement, refresh, disconnect and adoption
+revoke older controls, reveal promises and visible effects. Query and exact lookup each allow one
+physically unsettled call plus only the latest desired intent; ignored aborts hold that lane until
+settlement. Providers should honor the abort signal. The following sampling and last-completed-view
+activation behavior describes the legacy route with `source` null.
+
 **Properties:** `points: EmbeddingPoint[] = []` (attribute: false), where each point is `{ id, x,
 y, label?, sourceId?, cluster? }`; `selectedPointId: string = ''` (attribute
 `selected-point-id`); `height: string = '360px'` (any CSS length valid for `block-size`,
@@ -29,25 +99,35 @@ including `auto` for `viewBox`-derived aspect-ratio sizing; applied on the host
 attribute or `label`, `accessibleLabel` names the plot. An authored host `aria-label` governs the plot name too (including an
 explicitly empty value), so a competing internal generic label is not exposed. Non-finite
 coordinates are omitted.
+`maxRenderedPoints: number = 1000` (attribute `max-rendered-points`) controls the evenly sampled
+point budget. Finite values clamp to 1–10,000; invalid values use 1,000. A selected point outside
+the sample is additionally retained. Replace `points` to change the owned input.
 Blank point ids and later duplicates are also omitted first-wins before empty state, roving focus,
 selection, rendering, or events.
 Pointer and programmatic focus synchronize the single roving tab stop, and every point keeps at
 least a 24×24 CSS px pointer target at narrow allocations without enlarging its marker. Optional
 cluster membership is exposed as each option's description and in a visible text legend, so the
 grouping never depends on color alone.
-Above 1,000 points, the plot renders a deterministic, evenly spaced sample of the whole array
+Above `maxRenderedPoints` (1,000 by default), the plot renders a deterministic, evenly spaced sample of the whole array
 (spanning the full input, not a leading run) instead of every point, keeping DOM node and listener
-count bounded while the sampled points stay representative of the full plotted distribution; a
-localized "showing N of M" notice appears in `[part="limit"]`. `bounds` and the cluster legend
-still derive from the complete `points` array, so a decimated view keeps the same scale and the
-same complete legend as the full plot. The selected point is always drawn, even when the sample
-skipped it. An assignment too large for one collection snapshot (10,000 entries / 50,000 values) is
-itself sampled evenly across its whole length, and the notice counts the full input.
+count bounded. This index sample does not guarantee spatial extrema or every cluster. A localized
+"showing N of M" notice appears in `[part="limit"]`. Bounds and the cluster legend derive from the
+admitted snapshot; a selected point in that snapshot is drawn even when the render sample skipped
+it. An assignment too large for one collection snapshot (10,000 entries / 50,000 values) first
+selects a bounded set of evenly spaced candidate identities across its whole length, then resolves
+each candidate's first valid occurrence in cancelable chunks. The notice counts the full input,
+but bounds, clusters, and selectable identities remain limited to that admitted snapshot.
+The last completed view stays visible with `aria-busy` until the replacement is ready; activating
+one of its points still emits that displayed point. Keep pending source arrays and records stable,
+or reassign/explicitly call `requestUpdate()` to restart inspection. Replacement and disconnect
+cancel unfinished work, and reconnect resumes from the current source.
 
 **Events:** `lr-point-select` (`{ point }`), activated by click or Enter/Space (not on key repeat).
 
 **CSS parts:** `base`, `plot`, `point`, `legend`, `legend-item`, `legend-swatch`, `legend-label`,
-`limit` (the "showing N of M" render-cap notice, present only above 1,000 points), `empty`.
+`limit` (the "showing N of M" sampling notice), `empty`.
+Spatial-source parts: `bin` (a focusable density region, separate from representative point
+overlays) and `error` (invalid or unavailable spatial-source feedback).
 
 **Themeable custom properties:** `--lr-embedding-explorer-selected-stroke` (default
 `var(--lr-color-brand)`) — stroke color of the selected point; `--lr-embedding-explorer-height`

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

@@ -9,7 +9,7 @@
 - **Release history** [CHANGELOG.md](../../CHANGELOG.md)
 - **Deprecations** none
 - **Optional peers** `emoji-picker-element-data` — see `llms/peers.md`
-- **Themeable via** 18 parts, 28 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 19 parts, 28 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`
 
 ---
@@ -28,6 +28,11 @@ reloads it. This only applies to the built-in dataset, never to a consumer-suppl
 When the filtered set reaches 200 items, the grid automatically windows its visible rows while
 preserving the full option count through `aria-setsize`/`aria-posinset`.
 
+`groups` retains at most 64 groups, 20,000 emoji items in total and 64 shortcodes per item. The
+localized `limit` part reports omitted input through `emojiPickerInputLimit`. Built-in datasets
+are admitted once per loaded dataset and shared as frozen snapshots; caller assignments retain
+their owned snapshot behavior.
+
 Removing `label`, `hint`, or `error-text` treats the removed value as absent for rendering while
 preserving native attribute-removal property readback. Host `aria-describedby` references resolve in
 the host root onto the value-owning listbox before its local error/hint guidance. Target
@@ -107,7 +112,7 @@ transferring focus, so End and long row jumps never strand focus on a removed vi
 **Slots:** `label` (custom label content), `hint` (custom hint content), `error` (custom error
 content, overrides the `errorText` attribute when provided).
 
-**CSS parts:** `form-control` (the outer wrapper around label, `base`, error and hint),
+**CSS parts:** `limit` (input-loss notice), `form-control` (the outer wrapper around label, `base`, error and hint),
 `form-control-label` (the visible label), `base`, `search-wrapper` (the row wrapper around
 `search` and `search-clear`), `search` (`role="combobox"`), `search-clear` (clears the search
 field, replacing the native search-cancel glyph the component resets; rendered only while it has a

package/llms/components/lr-eval-dataset.md

@@ -19,20 +19,37 @@
 Its native search field honors the shared `--lr-input-*` search hooks and `--lr-icon-button-*` action hooks listed in the component reference.
 
 Filterable and taggable evaluation-example list with add, remove, import, and export affordances.
-If the public collection boundary truncates an oversized dataset, `[part="limit"]` names the
+With `dataSource` unset, if the public collection boundary truncates an oversized dataset, `[part="limit"]` names the
 number of retained examples. Pagination within those examples remains available in the table.
 
 **Properties:**
 
+- `dataSource: EvalDatasetSource | undefined` (property only) — a host-owned full
+  logical source; takes display precedence over `examples`. Invalid defined sources fail visibly;
+  unsetting restores the current legacy examples without overwriting their getter.
+- `sourcePage: number = 0` (`source-page`) — zero-based source page.
+- `sourcePageSize: number = 100` (`source-page-size`) — source page size, normalized to 1–500.
+- readonly `sourceTotal: number | null` — exact accepted query total, or `null` until a current
+  authoritative result is available.
+
 - `examples: readonly EvalExample[] = []` (attribute: false) — `EvalExample { id: string; input: string;
 expectedOutput?: string; tags?: readonly string[]; metadata?: Record<string, unknown> }` (exported here).
   It is a dedicated dataset-row shape; no shared agent type models a labeled evaluation row.
   `input`/`expectedOutput` are plain
   strings (not structured payloads), rendered as plain text by every column's `cell()`. Fully
   controlled: add/remove/import/export are all _requests_; the host mutates and passes the array
-  back. Empty/blank ids and later duplicate ids are omitted before selection, filtering, mutation requests, and the
+  back. The bounded readonly outer snapshot retains at most the first 10,000 examples; records and
+  opaque `metadata` retain identity. Reassign `examples` after editing records, including when
+  reusing the same source array. A keyless `requestUpdate()` also refreshes the normalized rows and
+  search corpus. Other clone-owned collections retain the 10,000-entry/50,000-node safety budgets.
+  Empty/blank ids and later duplicate ids are omitted before selection, filtering, mutation requests, and the
   nested grid are derived. Distinct tag chips are ordered with the component's effective-locale
-  collation
+  collation; at most 500 distinct tags render. Active tags reserve places within that budget so
+  their deselection controls remain visible; the remaining places show the earliest unselected
+  tags. A localized `limit` note reports the omitted count. Search and tag filtering still use all
+  admitted examples and tags, including tags
+  outside the displayed facet window. Filtering and the tag corpus are reused across unrelated
+  disabled or selection changes
 - `searchable: boolean = false` (reflected) — built-in free-text search over `input`,
   `expectedOutput`, and `tags` (case-insensitive substring)
 - `autocomplete: string = ''`, `spellcheck: boolean = true`, `autocapitalize: string = ''`,
@@ -50,6 +67,38 @@ expectedOutput?: string; tags?: readonly string[]; metadata?: Record<string, unk
   localized `evalDatasetLabel`. A host `aria-label` remains on the custom-element host as its
   overall name and is not cloned onto the independently interactive grid
 
+The provider query type is `EvalDatasetSourceQuery { readonly search: string;
+readonly tags: readonly string[]; readonly sortKey: string | null;
+readonly sortDir: 'asc' | 'desc' }`.
+
+**Full-source paging:** `EvalDatasetSource = LyraPageSource<EvalExample, EvalDatasetSourceQuery>`;
+both types are exported from the component entry and package root. `EvalDatasetSourceQuery`
+contains `search`, readonly `tags`, `sortKey: string | null`, and `sortDir: 'asc' | 'desc'`.
+The provider owns complete-source text filtering, OR-tag filtering combined with that text query,
+and ordering. The nested table uses server sorting and one-based paging while `sourcePage` remains
+zero-based. Query and page-size changes reset source page zero; an invalid page receives at most
+one corrective last-page request. Loading, unknown totals and failures use the composed table's
+localized states; stale rows cannot be activated.
+
+The shared `LyraPageSource` contract comes from `@aceshooting/lyra-ui/data-sources.js`. Its page
+must include explicit global `tags` metadata, even for an empty catalogue. Facets have
+`{ values, total, unavailableSelected }`; at most 500 values retain global labels and counts.
+Available active tags must reserve positions in that budget so they remain removable. Only
+`unavailableSelected`, not absence from one page, removes an active filter. Source rows allow at
+most 500 tags and 65,536 display-text UTF-16 units per row; opaque `metadata` is not traversed or
+rendered. Invalid or oversized responses fail visibly rather than becoming a partial dataset.
+
+Source page/query transitions clear the private selected example once, keeping Remove restricted
+to a visible current row. Existing import/export/add events remain requests for the host; export
+does not silently serialize just the loaded page. A source-mode sort both issues the provider
+query and preserves the single existing `lr-sort` pass-through event. `disabled` also prevents
+source sorting and mutations. Instance `strings` reach the composed table.
+
+The source is retained by identity. Reassign it, including the same object, or call unnamed
+`requestUpdate()` after source/revision mutation. Replacement, explicit refresh, locale change,
+disconnect and adoption revoke obsolete responses; unrelated named presentation updates reuse
+the current data. No million-row snapshot or whole-source filter/index is created by this route.
+
 **Events:** `lr-example-select` (`detail: { exampleId: string | null }`),
 `lr-example-add-request` (`detail: null` — no payload; `emit()`
 normalizes an omitted detail to `null`, never `undefined`), `lr-example-remove-request` (`detail: { exampleId:
@@ -59,12 +108,12 @@ format: string }`), and the deliberate nested-table pass-through `lr-sort` (`det
 re-dispatched (no detail) when the internal search field (only rendered while `searchable`) gains or
 loses focus, since native focus neither bubbles nor crosses the shadow boundary.
 All three built-in columns are sortable; activating one of their headers produces that commit for
-the host to apply to its controlled `examples` array.
+the host to apply to its controlled `examples` array, or for the source to order its query result.
 
 **CSS parts:** `base`, `toolbar`, `search`, `search-input` (the composed `lr-input type="search"`),
 `search-input-field` (its native `<input>`), `search-clear` (its clear button, rendered only while the field has text), `tag-filter`,
-`grid`, `add-button`, `remove-button`, `limit` (shown when the source examples exceed the snapshot
-cap), `import` (the internal `compact` `lr-file-input`; its
+`grid`, `add-button`, `remove-button`, `limit` (shown for source examples beyond the snapshot
+cap or distinct tags beyond the 500-facet ceiling), `import` (the internal `compact` `lr-file-input`; its
 dropzone text and accessible name are the localized `evalDatasetImportLabel`), `export`.
 
 **Themeable custom properties:** the built-in search field is a composed `lr-input`, so it is themed through the shared `--lr-input-*` and `--lr-form-control-*` tokens (the former `--lr-eval-dataset-search-*` hooks are removed).
@@ -72,7 +121,7 @@ The search field remains a filter toolbar, with the native editing hints listed
 
 **Known gotchas:**
 
-- Shrinking `examples` out from under live UI state is handled: a `selectedId` that no longer matches
+- With `dataSource` unset, shrinking `examples` out from under live UI state is handled: a `selectedId` that no longer matches
   any row resets to `null`, and an active tag filter that no longer matches any row's `tags` is
   dropped rather than silently matching zero rows forever.
 - A search or tag filter that hides the selected row also clears that selection and emits

package/llms/components/lr-eval-result.md

@@ -9,7 +9,7 @@
 - **Release history** [CHANGELOG.md](../../CHANGELOG.md); family-wide breaking-change summaries: [agent-tools](https://github.com/aceshooting/lyra-ui/blob/main/packages/lyra-ui/llms/agent-tools.md)
 - **Deprecations** none
 - **Optional peers** `shiki` — see `llms/peers.md`
-- **Themeable via** 9 parts, 0 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 12 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`
 
 ---
@@ -30,6 +30,85 @@ The table uses `label` or the localized purpose-specific evaluation-runs name. A
 on `<lr-eval-result>` remains the overall host name and is not cloned onto the independently
 interactive table; use `label` to distinguish several comparison grids on one page.
 
+**Full-source comparison runs:** `dataSource: EvalResultSource | undefined`
+(attribute: false) takes precedence over `runs`; invalid defined providers fail visibly.
+Setting `undefined` restores current legacy runs. `sourcePage: number = 0` (`source-page`) is
+zero-based; `sourcePageSize: number = 100` (`source-page-size`) normalizes to 1–500. Readonly
+`sourceTotal: number | null` is the accepted current-query total, or null while unavailable/without
+a source. Page-size and accepted sort changes reset page zero. An out-of-range page receives at
+most one corrective last-page request.
+
+```ts
+import type { EvalResultSource, EvalResultSourceQuery, EvalRunResult } from
+  "@aceshooting/lyra-ui/components/agent-tools/eval-result/eval-result.class.js";
+import type { LyraPageSource, LyraPageResult, LyraSourceRecord } from
+  "@aceshooting/lyra-ui/data-sources.js";
+```
+
+`EvalResultSource` is `LyraPageSource<EvalRunResult, EvalResultSourceQuery>`. The immutable provider
+revision is a nonempty string or finite number. `query({ revision, locale, signal, page, pageSize,
+query })` returns `{ rows, total }`; query is `{ sortKey: string | null, sortDir: 'asc' | 'desc' }`,
+initially null/asc. Each record is `{ key, order, value }`, with `key === value.id`, nonblank original
+ID and safe canonical source `order`; page keys/orders are unique and rows exactly fill the
+requested in-bounds page. `lookup(keys, context)` returns complete globally present requested
+records, omitting absent IDs; `locate(key, query, context)` supplies the shared page-source
+contract but ordinary comparison paging does not use it. Provider order/sorting applies globally,
+without sorting a partial page locally.
+
+Source mode forwards the table's original cancelable `lr-sort-request`
+`{ phase: 'request', sortKey, sortDir }` and accepted `lr-sort`
+`{ phase: 'commit', sortKey, sortDir }` once. Veto prevents a source order change; only a current
+commit updates the server query and resets page zero. These sort events remain contained in the
+legacy route. Existing columns define the sorting choices rather than a new sort property API.
+
+`selectedRunId` and `baselineRunId` stay fully controlled and are never rewritten. A null ID means
+the first global row of the current query, not the first row of whichever page is displayed.
+Starting on a nonzero page can therefore request a size-one page-zero primer before the requested
+page; only its fallback key is retained and its row/total never becomes the displayed page.
+Paging preserves that fallback; sort/locale/source refresh recomputes it. Explicit selected and
+baseline IDs resolve off-page through one deduplicated lookup of at most two keys. A missing
+explicit ID does not fall back to the first row; an absent selection suppresses review/diff, while
+missing baseline retains the existing selected-output comparison behavior. Empty-source success
+and failed lookup remain distinct. Controlled ID changes and fallback resolution emit no activation.
+Same-revision paging/sorting and locale-only formatting retain explicit comparison records;
+source revision/rebind/lifecycle changes revoke old pair data before it can drive review/diff.
+
+The current page holds at most 500 rows and the selected/baseline cache at most two records;
+pending replacement work is separately bounded by those same limits. There is no full runs array
+or secondary corpus. Page, selected-pair and locate work share the source's existing fixed
+lanes: one physical call per lane plus only the latest queued intent. The primer uses the same
+page lane, and ignored aborts keep physical permits until settlement. Fixed own-data fields
+`id`, `label`, optional `model`/`promptVersion` and `output` share a 65,536 UTF-16-unit row budget;
+a missing streaming output becomes `''`. Oversized/accessor-backed rows reject without clipping.
+Keys are at most 65,536 units and share the page helper's 2,000,000-unit key admission budget.
+
+Source `scores`/`review` dictionaries remain complete opaque provider references. Custom column
+cell/style/title/value callbacks and footers receive borrowed original provider records; built-in
+identity/diff/review uses closed frozen projections. Source `lr-run-activate { runId, run }`
+freezes the event envelope/run shell while preserving the complete scores/review identities,
+without deeply cloning or freezing those maps. Legacy activation retains its whole-detail deep
+snapshot and existing exhaustion-to-null behavior. Built-in review reads only configured
+`rubricKeys`, bounded to 10,000 combined scalar/category entries and 65,536 UTF-16 text units;
+it never JSON-serializes the complete source review dictionary. Existing review events retain
+original run IDs and their current selected-pair ownership. Disabled review stays inactive while
+the comparison grid remains usable.
+
+Initial source loading uses `source-status`. Current page errors/retry use the composed table;
+selected/baseline or review-projection failure uses `selection-status`/`selection-retry` and retries
+the pair without refetching the page. Initial failure is quiet; later page failures are announced
+by the table and pair failures by the parent, without duplicated announcements. Reassign even the
+same source, or call a keyless `requestUpdate()`, after revision/state changes. Named presentation
+updates reuse accepted records. Source/lifecycle replacement and obsolete page/pair changes revoke
+old controls, callbacks and review effects. The following run-array normalization/fallback details
+apply to the legacy route; columns/rubric/presentation contracts apply to both.
+
+**Exported source query declaration:**
+
+`EvalResultSourceQuery {
+  readonly sortKey: string | null;
+  readonly sortDir: 'asc' | 'desc';
+}`
+
 **Properties:**
 
 - `runs: EvalRunResult[] = []` (attribute: false) — `EvalRunResult { id: string; label: string;
@@ -47,9 +126,10 @@ model?: string; promptVersion?: string; output: string; scores?: RubricValue; re
 - `label: string = ''` — accessible name for the independently interactive comparison grid;
   falls back to the localized evaluation-runs name when unset
 - `selectedRunId: string | null = null` (attribute `selected-run-id`) — the run open for review and the diff's
-  **new** side; falls back to `runs[0]?.id` when empty
+  **new** side; null falls back to the first legacy run, or the first global current-query run
+  in source mode
 - `baselineRunId: string | null = null` (attribute `baseline-run-id`) — the run compared against and the
-  diff's **old** side; falls back to `runs[0]?.id` when empty
+  diff's **old** side; null uses the same first-run fallback described above
 - `reviewSkippable: boolean = false` (attribute `review-skippable`) — shows a Skip control on the
   review form (forwarded to `lr-rubric-form.skippable`)
 - `disabled: boolean = false` (reflected) — disables the review form's controls only; the comparison
@@ -59,6 +139,11 @@ model?: string; promptVersion?: string; output: string; scores?: RubricValue; re
 string; value: RubricValue }`), `lr-review-validity-change` (`detail: { runId: string; valid:
 boolean; errors: Record<string, string> }`), `lr-review-submit` (`detail: { runId: string; value:
 RubricValue }`), `lr-review-skip` (`detail: { runId: string }`).
+In source mode, `lr-sort-request` is the original cancelable table proposal with frozen
+`TableSortRequestDetail { phase: 'request', sortKey, sortDir }`; `sortDir` is `'asc' | 'desc'`.
+`lr-sort` is the accepted, noncancelable table commit with frozen
+`TableSortCommitDetail { phase: 'commit', sortKey, sortDir }`. Preventing the request suppresses
+the commit and leaves the current source sort unchanged.
 
-**CSS parts:** `base`, `empty`, `grid`, `diff`, `diff-view`,
+**CSS parts:** `base`, `empty`, `grid`, `source-status`, `selection-status`, `selection-retry`, `diff`, `diff-view`,
 `diff-labels`, `diff-label-old`, `diff-label-new`, `review`.

package/llms/components/lr-export-button.md

@@ -19,7 +19,7 @@
 CSV/JSON download button with extensible event-driven formats — either single-format (click exports
 immediately) or multi-format (click opens a small menu).
 
-The format menu follows the [shared surface treatment](shared/styles-and-tokens.md).
+The format menu follows the [shared surface treatment](../shared/styles-and-tokens.md).
 
 **Properties:**