@aceshooting/lyra-ui 29.0.2 → 29.1.0

package/llms/components/lr-retrieval-results.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)
 - **Deprecated event** `lr-select` since `26.0.0`; use event `@lr-selection-change`; removal not before `28.0.0` — lr-selection-change is the library's one name for a changed selection (detail chunkIds is selectedChunkIds); the alias fires right after it for one major.
 - **Optional peers** none
-- **Themeable via** 29 parts, 1 custom property — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 35 parts, 1 custom property — see this component's own `@csspart`/`@cssprop` list below
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
 
 ---
@@ -22,6 +22,98 @@ compact/expanded switch. Each row wraps exactly one chunk in an internal `lr-chu
 a single-element array), reusing its score bar, tier coloring, title+page rendering, and expandable
 text verbatim. Large sets window through an internal `lr-virtual-list`.
 
+With `dataSource` unset, assignment retains the first 10,000 chunks in a bounded readonly outer snapshot. Admitted record
+identities feed a descriptor-safe copy of the closed display schema, including source fields and
+score breakdowns; `metadata` remains opaque and a locator receives its own bounded snapshot. This
+avoids applying the shared 50,000-value deep-copy budget to arbitrary nested provider data. Replace
+the collection to publish record changes. Canonical records, id/order indexes, and the sorted/grouped
+projection are reused across selection and presentation changes. Replace a custom grouping callback
+when its behavior changes, or issue a keyless `requestUpdate()` to refresh its projection.
+
+A localized `[part="limit"]` note reports retained and assigned-source counts above the input
+ceiling, using the effective locale. Initial truncation is silent; a later transition into input
+truncation is announced politely. Virtualization continues to window the admitted result set.
+
+**Full-source paging:** `dataSource: RetrievalResultsSource | undefined`
+(attribute: false) supplies the complete logical collection while retaining only bounded pages.
+A defined source takes display precedence over `chunks`; an invalid defined source fails visibly.
+Setting `undefined` restores the current legacy chunks. `sourcePage: number = 0` (`source-page`)
+is zero-based; `sourcePageSize: number = 100` (`source-page-size`) normalizes to 1–500.
+Readonly `sourceTotal: number | null` reports the exact current-query total after success, or
+`null` before success and without a source. Query/page-size changes reset page zero. A total shrink
+receives at most one corrective request for the last valid page.
+
+```ts
+import type { RetrievalResultsSource, RetrievalResultsSourceQuery } from
+  "@aceshooting/lyra-ui/components/retrieval/retrieval-results/retrieval-results.class.js";
+import type { LyraPageSource, LyraPageResult, LyraSourceRecord } from
+  "@aceshooting/lyra-ui/data-sources.js";
+```
+
+`RetrievalResultsSource` is `LyraPageSource<RetrievalChunk, RetrievalResultsSourceQuery>`.
+The immutable provider `revision` is a nonempty string or finite number. `query({ revision,
+locale, signal, page, pageSize, query })` returns `{ rows, total, groups? }`, where each row is
+`{ key, order, value }`, `value` is a complete `RetrievalChunk`, and `order` is its stable canonical
+source order. Counts/orders are safe nonnegative integers; page keys/orders are unique and the
+returned row count must exactly fill the requested in-bounds page. `lookup(keys, context)` returns
+canonical records for globally present requested IDs, omitting absent ones;
+`locate(key, query, context)` returns an absolute current-query index or `null`.
+
+The forwarded query is `{ sort, withoutDedupe, grouping, groupBy, groupLabel, groupOrder }`.
+The provider applies sorting, deduplication and grouping to the complete collection before paging;
+local callbacks never compute a global group from a partial page. Grouped responses require
+`groups: [{ key, label, startIndex, itemCount }]` with globally positioned, nonoverlapping intervals
+covering the page. At most 500 records and 500 intersecting groups are admitted. Each record's
+required rendered strings share a 65,536 UTF-16-unit limit; locator paths have at most 500 segments.
+Malformed or oversized pages fail without silently clipping full chunk text. Keys/group text are
+bounded to 65,536 units each and share a 2,000,000-unit admission budget.
+
+With `withoutDedupe: false`, page `key` must equal canonical `value.id`. With `withoutDedupe: true`,
+distinct occurrence keys may show repeated canonical IDs, while selection still uses `value.id`.
+Canonical `lookup` must always return `key === value.id`; page occurrence keys never become selected
+IDs. Provider order is preserved in the visible page.
+
+Up to 10,000 explicit `selectedChunkIds` resolve globally in sequential batches of at most 500;
+blanks/duplicates normalize before lookup. Off-page IDs remain selected while unresolved, and only
+a successful global absence proof removes an ID. Complete canonical records are ordered by
+provider `order`, independently of page/query order. The selected-record cache and pending user
+transaction survive paging, query changes and page retry. Selection failure exposes a separate
+retry without emitting a partial selection. External assignment and reconnect/adoption
+reconciliation are silent. A user toggle emits `lr-selection-change` and its guarded deprecated
+`lr-select` alias only after the current complete selection resolves.
+
+Source selection event arrays and closed projected record fields are frozen; each record's
+`metadata` remains an opaque reference to the provider-owned value. The component neither deeply
+clones nor freezes that metadata graph. Legacy selection events retain their whole-detail detached,
+deeply frozen snapshot and its existing bounded failure behavior, including `null` on exhaustion.
+This source identity policy applies to both selection event names. `lr-chunk-open` retains its
+existing detail. Source mode suppresses `lr-load-more` and ignores legacy `hasMore`.
+
+The source remains host-owned by identity. Reassign even the same provider, or call a keyless
+`requestUpdate()`, to refresh its revision/cache. Named presentation changes reuse accepted data.
+Source replacement, refresh, disconnect and adoption revoke obsolete effects. Each page, selection
+and locate lane allows one physically unsettled provider call and only the latest queued intent;
+ignored aborts retain their permit until settlement. Only the current page/groups, explicit
+selected-record cache and bounded in-progress results are retained, with no full-source corpus.
+`activeChunkId` uses global `locate` once per active/query binding; subsequent manual paging wins
+until that binding changes. Expansion is bounded to the current page. Source-only parts are
+`source-status`, `source-retry`, `source-pagination`, `source-selection-status` and
+`source-selection-retry`, alongside existing row/chunk/metadata parts.
+
+The following array processing and sort/group fallback rules describe the legacy route;
+presentation properties also apply to provider rows.
+
+**Exported source query declaration:**
+
+`RetrievalResultsSourceQuery {
+  readonly sort: 'score' | 'none';
+  readonly withoutDedupe: boolean;
+  readonly grouping: RetrievalResultsGrouping;
+  readonly groupBy: LyraRetrievalResults['groupBy'];
+  readonly groupLabel: LyraRetrievalResults['groupLabel'];
+  readonly groupOrder: LyraRetrievalResults['groupOrder'];
+}`
+
 **Properties:**
 
 - `chunks: RetrievalChunk[] = []` (attribute: false) — **`RetrievalChunk`, imported from
@@ -35,13 +127,14 @@ queryId?: string; stage?: string; traceId?: string; scores?: RetrievalScoreBreak
   Nothing is ever guessed from `metadata` — a chunk with no `locator` simply leaves `anchor`/`page`
   unset
 - `selectedChunkIds: string[] = []` (attribute: false) — controlled selection by chunk `id`. Blank
-  ids, duplicates, and ids absent from the canonical chunk model are pruned. The component updates
+  ids, duplicates, and ids absent from the canonical chunk model are pruned in the legacy route;
+  source mode resolves presence globally as described above. The component updates
   its own copy on toggle _then_ emits `lr-selection-change`; reassign to control
 - `withoutSelection: boolean = false` (attribute `without-selection`, reflected) — omits the per-row
   `lr-checkbox`.
 - `withoutDedupe: boolean = false` (attribute `without-dedupe`, reflected) — retained for
-  compatibility and has no effect; malformed, blank, and later duplicate chunk ids are always omitted
-  first-wins so identity never becomes ambiguous.
+  compatibility in the legacy route, where malformed, blank, and later duplicate chunk ids are
+  always omitted first-wins. Source mode supports distinct occurrence keys as described above.
 - `sort: 'score' | 'none' = 'score'` — `'score'` sorts descending; `'none'` preserves given order
 - `grouping: 'source' | 'custom' | 'none' = 'none'` — `'source'` buckets rows under a header per
   `source.id` (the header text is that source's `name`, or a localized "untitled source" when it has
@@ -71,7 +164,8 @@ queryId?: string; stage?: string; traceId?: string; scores?: RetrievalScoreBreak
   to each row and to the virtual list (which scrolls the matching row into view)
 - `loading: boolean = false` (reflected)
 - `hasMore: boolean = false` (attribute `has-more`, reflected) — while virtualized, forwarded to the
-  virtual list so scroll-near-bottom fires `lr-load-more`; otherwise shows the built-in footer button
+  virtual list so scroll-near-bottom fires `lr-load-more`; otherwise shows the built-in footer button.
+  Inactive with `dataSource` set
 - `errorText: string = ''` (attribute `error-text`; spelled plain `error` before 9.0.0) — non-empty
   replaces the whole result view with a neutral visible message. Caller-supplied text is not
   localized (app/network data, not library copy). A new non-empty value is announced through a
@@ -131,7 +225,11 @@ virtualized — `::part(row)` reaches it either way), `group-header` (exported f
 on a selected `row-body`), `metadata` (a `<dl>`; omitted when the chunk has none or while
 `presentation="compact"`; at most 32 entries, each value formatted within the same bounds as a
 `lr-retrieval-search` filter value), `metadata-entry`, `metadata-term` (the `<dt>` carrying a metadata key),
-`metadata-value` (the `<dd>` carrying its value), `load-more-row`, `load-more`.
+`metadata-value` (the `<dd>` carrying its value), `load-more-row`, `load-more`, `limit` (the
+input-retention notice).
+Source-mode parts: `source-status` (page loading or failure text), `source-retry` (page retry),
+`source-pagination` (provider page navigation), `source-selection-status` (canonical selected-record
+lookup loading or failure), and `source-selection-retry` (retrying that lookup).
 
 The per-row `lr-chunk-inspector`'s own parts are forwarded onward under a `chunk-` prefix —
 `chunk`, `chunk-current`, `chunk-score`, `chunk-score-current`, `chunk-score-bar`,

package/llms/components/lr-scatter-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-select.md

@@ -9,14 +9,14 @@
 - **Release history** [CHANGELOG.md](../../CHANGELOG.md)
 - **Deprecations** none
 - **Optional peers** none
-- **Themeable via** 34 parts, 36 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 35 parts, 36 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`
 
 ---
 
 ## `lr-select`
 
-Floating form-control panels follow the [shared surface treatment](shared/styles-and-tokens.md).
+Floating form-control panels follow the [shared surface treatment](../shared/styles-and-tokens.md).
 Editing fields and inline color editors retain opaque interiors.
 
 A plain closed-list dropdown — a direct `<lr-*>` counterpart to `<wa-select>`/`<wa-option>`.
@@ -33,7 +33,8 @@ value/form/validity path as a programmatic value write and does not emit `input`
 **Selecting options in browser tests.** The light-DOM `<lr-option>` children supply option data;
 the clickable rows are rendered inside `<lr-select>`'s shadow-root listbox as
 `[part="option"][role="option"]`, each with a `data-value` matching its represented value. Rows
-mount the first time the listbox opens, so a closed select has none. Opening makes the committed
+mount when the listbox opens and are removed after it closes, so a settled closed select has none.
+Opening makes the committed
 option (the first committed one in `multiple`) the active row and scrolls it into view; with
 nothing committed no row is active until an arrow key.
 Click the trigger to open the listbox, then target a rendered row. For example, in Playwright:
@@ -50,23 +51,25 @@ await select.locator('[part="option"][data-value="fr"]').click();
 For an in-page component test with a `LyraSelect` element, the public
 `@aceshooting/lyra-ui/testing` `chooseOption(selectElement, 'fr')` driver opens the listbox,
 clicks its first rendered row with that value, and awaits the component update. It also works in
-DOM test environments without Playwright; see [interaction drivers](shared/testing-and-utilities.md#driving-a-components-real-activation-path-interaction-drivers).
+DOM test environments without Playwright; see [interaction drivers](../shared/testing-and-utilities.md#driving-a-components-real-activation-path-interaction-drivers).
 
 Playwright's locators enter the open shadow root. A light-DOM `lr-option[value="fr"]` has no
 clickable box in this picker. If multiple options share a value, `data-value` matches every
 occurrence; narrow by accessible name or assert their order before choosing an occurrence.
 
-Mounted `option.selected` assignments update the picker value and form submission immediately,
-including deselection and equal-value writes. Duplicate-valued options retain their individual
-occurrence identities. These programmatic writes emit no user input/change event.
+Mounted `option.selected` assignments update the option immediately, including deselection and
+equal-value writes. The owning select reconciles its value and form submission once in the next
+microtask; await one microtask before reading settled parent state. Duplicate-valued options retain
+their individual occurrence identities. These writes emit no user input/change event. Assign the
+parent value array for a bulk replacement.
 
 Host `aria-describedby` resolves external guidance onto the trigger before internal value, error,
 and hint guidance. References track missing targets, replacement, removal/reinsertion, reconnect,
 and adoption. Removing `label`, `hint`, `help-text`, or `error-text` safely omits the content
 without changing native `null` property readback; explicit empty strings remain empty.
 
-There is no typing-to-filter and no `filter`/`source`/`empty-text`/`max-render` surface — reach for
-`<lr-combobox>` instead whenever any of those apply. Everything else a closed list needs is here:
+There is no typing-to-filter and no `filter`/`source`/`empty-text` surface — reach for
+`<lr-combobox>` whenever those apply. The popup has a bounded `max-render` surface. Other closed-list features include
 `multiple`, `max-options-visible`, `with-clear`, `getTag`, `placement`, `appearance`, and `pill`.
 
 The trigger and its overlaid multi-select tag row accept constrained allocation. Long selected
@@ -208,6 +211,12 @@ the normal combobox trigger continues to expose `aria-required`.
   `multiple` mode before the rest collapse behind a localized "+N" chip. `0` removes the cap
   entirely. Sanitized to a finite, non-negative integer: a fractional value truncates, a negative
   one clamps to `0` (i.e. uncapped), and a non-finite one falls back to `3`
+- `maxRender: number = 200` (attribute `max-render`) — ordinary popup prefix size, retaining
+  selected and active options within an absolute 1,000-row ceiling. The active option has priority;
+  oversized selections remain committed even when every selected row cannot mount. Zero omits
+  the ordinary prefix while retaining selected/active rows; non-finite values use 200. Rows keep
+  source order. `option-overflow` reports omitted rows, which cannot be reached by scrolling;
+  use a filterable combobox or async source for larger searchable catalogs
 - `withClear: boolean = false` (attribute `with-clear`, reflected) — renders a clear button while
   anything is selected (and nothing at all while the selection is empty). It sits in the trigger's
   inline-end band as a **sibling** of the trigger rather than a child of it — same nesting reason as
@@ -360,7 +369,8 @@ following option rows; options with an empty `group` get no heading or group wra
 `lr-combobox`'s identical parts), `option-label`,
 `option-sub` (a row's secondary line, when `sub` is set),
 `option-badge` (the localized "not in catalog" badge on a synthetic unmatched-value row, rendered
-only while `with-unknown-option` is set), `expand-icon`, `error`, and
+only while `with-unknown-option` is set), `option-overflow` (the localized count of omitted popup
+rows), `expand-icon`, `error`, and
 `hint`/`form-control-help-text` (compatibility names on the same supporting-text node).
 
 **TypeScript:** `LyraSelect<Multiple extends boolean = boolean>` — `value`/`defaultValue` and the

package/llms/components/lr-sequence-strip.md

@@ -9,7 +9,7 @@
 - **Release history** [CHANGELOG.md](../../CHANGELOG.md)
 - **Deprecations** none
 - **Optional peers** none
-- **Themeable via** 12 parts, 7 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 15 parts, 7 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`
 
 ---
@@ -42,7 +42,7 @@ refreshes do not move focus. A queued Arrow/Home/End focus is bound to the curre
 identity and connection generation, so a same-turn replacement or disconnect/reconnect cannot
 focus an unrelated cell that merely inherited the old numeric index.
 
-High-cardinality strips retain at most the first 10,000 assigned items and categories as detached,
+With `source` unset, high-cardinality strips retain at most the first 10,000 assigned items and categories as detached,
 frozen canonical snapshots; reassign either collection after changing it. At most 200 cells are
 rendered. **At or below that cap each cell is one item. Past it the strip becomes a span-preserving
 overview rather than a window:** the retained items are distributed over exactly 200 contiguous
@@ -58,6 +58,93 @@ generated `aria-label` so assistive technology learns the cells are ranges. The
 likewise mounts at most 200 categories and exposes `[part="legend-limit"]` as a rendered/total
 numeric disclosure.
 
+**Complete indexed source:** `source: LyraSequenceSource<SequenceStripItem> | null = null`
+(attribute: false) takes precedence over `items`, preserving the provider's identity. `null` or
+`undefined` restores the current legacy items; other invalid defined values fail visibly.
+Reassign even the same source, or call a keyless `requestUpdate()`, after revision/state changes.
+Named theme, strings and legend paints reuse accepted data; locale, disconnect/reconnect and
+adoption revoke obsolete requests/effects. Providers should honor abort signals; ignored aborts
+keep physical request permits occupied until settlement.
+
+```ts
+import type { LyraSequenceSource, LyraSequenceRangeSummary, SequenceStripItem } from
+  "@aceshooting/lyra-ui/components/data/sequence-strip/sequence-strip.class.js";
+import type { LyraSourceRequest, LyraSourceValue } from
+  "@aceshooting/lyra-ui/utilities/data-preparation.js";
+```
+
+`LyraSequenceSource<T>` supplies immutable `revision` (a nonempty string or finite number), safe
+nonnegative integer `length`, and
+`getItem(index, { signal }): LyraSourceValue<T | null>`,
+`findIndex(id, { signal }): LyraSourceValue<number | null>`, and
+`summarize({ signal, startIndex, endIndex, maxRanges }): LyraSourceValue<readonly
+LyraSequenceRangeSummary[]>`. The summary request spans `[0, length)` and asks for at most
+`min(length, 200)` ranges; an empty source needs no provider read. Each summary has
+`{ startIndex, endIndex, categoryCounts, markerCount, enabledCount }`: ascending, nonempty,
+half-open ranges must partition the complete logical sequence without gaps or overlap.
+`categoryCounts` is an own-data string-to-positive-safe-integer dictionary whose counts sum to
+the range length; marker/enabled counts are safe integers from zero to that length. The provider
+owns immutable snapshots, indexing and the truth of complete-source totals; admission verifies
+bounded shape and arithmetic consistency.
+
+At most 200 ranges, 200 distinct global category IDs and 40,000 category-count pairs are admitted.
+Summary category IDs are nonblank and at most 1,024 UTF-16 units. Exact `SequenceStripItem` records
+have own-data `id`, `categoryId`, optional `label`, optional boolean `marker`/`disabled`; the aggregate
+length of `id`/`categoryId`/`label` is at most 65,536 UTF-16 units. Malformed, accessor-backed or
+oversized records fail without clipped labels or compacted indices. The component retains bounded
+current/pending summaries and one exact record, with one physical summary request and one physical
+exact request; only the latest queued intent survives. String lookup and its subsequent exact read
+are sequential. There is no raw-item scan or complete source array in the component.
+
+Overview range widths are proportional to their actual lengths. Global category and marker counts
+include every range, and `selectedIndex` highlights its containing range. Source dominant-category
+ties use configured `categories` order, then lexical category ID; the legacy route retains its
+earliest-occurrence rule. A source range is disabled only when `enabledCount === 0`; mixed ranges
+report their enabled count. Overview activation still resolves the range's first exact item and
+emits the unchanged `lr-item-activate` `{ index, id, item }` with its original zero-based index and
+ID; a disabled or unavailable first item emits nothing. Hover and overview focus use the summary,
+including bounds, dominant category, marker count and enabled/total counts, without exact reads.
+`data-range-end` remains inclusive in rendered range attributes; provider bounds are half-open.
+
+`revealSourceItem(target: number | string): Promise<boolean>` resolves an original index or stable
+ID, updates the separate exact inspection cursor and focuses its control while focus ownership is
+still current. ID lookup uses `findIndex` then verifies the returned `getItem` ID. It does not
+change `selectedIndex` or emit activation. Disabled exact items remain inspectable and resolve
+`true`; absent, invalid, unavailable or revoked targets resolve `false`. The `source-exact` native
+button supports RTL-aware Left/Right and Home/End over the complete original index range, including
+missing/disabled positions; it does not scan for enabled items. Enter/Space or click activates only
+the current admitted enabled exact item. Pending/unavailable detail keeps a focusable localized
+inspector fallback. Controlled `selectedIndex` changes resolve exact detail silently. Source-only
+parts are `source-status`, `source-retry` and `source-exact`; `base`, `cell`, `marker`, `tooltip`,
+`bucket-summary`, `empty` and existing legend parts remain applicable. Initial errors are quiet;
+later status transitions use localized light-DOM announcements. No completion event is added.
+
+The following item-array limits and per-item disabled/tie rules apply with `source` unset.
+
+**Exported sequence-source declarations:**
+
+These declarations use the request/value types and granular class import shown above.
+
+`LyraSequenceSource<T> {
+  readonly revision: LyraSourceRevision;
+  readonly length: number;
+  getItem(index: number, request: LyraSourceRequest): LyraSourceValue<T | null>;
+  findIndex(id: string, request: LyraSourceRequest): LyraSourceValue<number | null>;
+  summarize(request: LyraSourceRequest & {
+    readonly startIndex: number;
+    readonly endIndex: number;
+    readonly maxRanges: number;
+  }): LyraSourceValue<readonly LyraSequenceRangeSummary[]>;
+}`
+
+`LyraSequenceRangeSummary {
+  readonly startIndex: number;
+  readonly endIndex: number;
+  readonly categoryCounts: Readonly<Record<string, number>>;
+  readonly markerCount: number;
+  readonly enabledCount: number;
+}`
+
 **Properties:**
 
 - `items: readonly SequenceStripItem[] = []` (attribute: false) — `{ readonly id, readonly
@@ -141,6 +228,9 @@ only while the strip is past its 200-cell cap; it replaced 15.x's `window-range`
 projection window this component no longer has), and `legend-limit`
 (bounded legend/total).
 
+With `source` set, additional CSS parts are `source-status` (loading or failure text), `source-retry` (retry the current
+source failure), and `source-exact` (the exact-item inspection and activation button).
+
 **Themeable custom properties:** `--lr-sequence-strip-height` (default `1.5rem` — the strip's
 block-size), `--lr-sequence-strip-marker-color` (default `var(--lr-color-text)` — the
 `[part="marker"]` fill, and of the marker legend row's bar), `--lr-sequence-strip-legend-swatch-size`

package/llms/components/lr-span-waterfall.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** none
-- **Themeable via** 13 parts, 10 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 19 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`
 
 ---
@@ -22,12 +22,70 @@ an item and reassign the same source array to publish that change. Unrelated pro
 reuse the current projection where possible.
 
 The horizontal-timeline projection of the same `LyraSpan[]` `<lr-trace-tree>` consumes: a time
-axis, one row per span in start order, status-toned bars (Langfuse timeline / Temporal
+axis, one row per legacy span in start order, status-toned bars (Langfuse timeline / Temporal
 event-history style).
 
-Span views omit whitespace-only IDs and preserve every nonblank business ID exactly, including
+With `treeSource` unset, span views omit whitespace-only IDs and preserve every nonblank business ID exactly, including
 surrounding whitespace. The first valid admitted duplicate continues to win.
 
+**Complete provider timeline:** `treeSource: TraceTreeSource | undefined`
+(attribute: false) takes precedence over `spans`; invalid defined providers show a localized failure.
+Setting `undefined` restores current legacy spans. The exact alias is shared with `lr-trace-tree`:
+`LyraHierarchySource<LyraSpan, LyraHierarchyQuery, LyraTraceSourceSummary>`.
+
+```ts
+import type { TraceTreeSource, LyraSpan } from
+  "@aceshooting/lyra-ui/components/agent-tools/span-waterfall/span-waterfall.class.js";
+import type { LyraTraceSourceSummary } from "@aceshooting/lyra-ui/data-sources.js";
+```
+
+The immutable provider revision is a nonempty string or finite number. Its `project` receives
+revision/locale/abort signal, prior opaque state, provider reset/toggle/reveal/item-select actions,
+and `{ search: '', hiddenKinds: [] }`. Return `{ state, total, rows, summary, focusIndex? }` as in
+the trace-tree contract. `total` counts all logical nodes including collapsed ones; `rows.count`
+is the complete visible preorder. Counts are safe nonnegative integers with `rows.count <= total`.
+Rows use indexed `itemAt`/`keyAt`/`indexOfKey`, or ranged `read` with required direct `indexOfKey`.
+Provider preorder is displayed as supplied, without local start-time sorting or a full topology
+scan. Each row's `key === value.id`, parent/depth/sibling/child metadata, expanded, selected and
+disabled states are authoritative; span `parentId` does not rebuild source topology.
+
+Required `summary: LyraTraceSourceSummary { startMs, endMs }` describes the complete trace,
+independently of the loaded window. Endpoints are finite nonnegative trace-relative milliseconds,
+end is at least start and their difference is finite. Missing/invalid summaries fail visibly;
+current rows and stale legacy extents never substitute. Equal global endpoints remain valid.
+Default axis/bar extent uses that global start/end, so an offscreen tail does not stretch visible
+bars. `viewStartMs`/`viewEndMs` override the display window without reloading the provider: null
+uses the corresponding global endpoint, nonfinite input falls back, finite explicit start/end
+clamp to `0..Number.MAX_SAFE_INTEGER - 1` / `0..Number.MAX_SAFE_INTEGER`, and an end at/before start
+uses `start + 1` for drawing. Source summary values remain unchanged by display overrides.
+
+Closed source display records retain id/name/kind/status/start/end; start is finite/nonnegative
+and an explicit end finite and at least start. Existing kind/status normalization applies.
+Oversized strings/rows fail without clipping: keys/state/display strings are at most 65,536 UTF-16
+units each, row text including key/parent accounting at most 65,536, and cache/staging/focused-row
+plus projection state share 2,000,000 payload units. Four 100-row pages (400 rows) plus one focused
+ready row are retained; at most 301 rows mount. Range reads request at most 100 rows with two
+physical reads pending; projection calls serialize with only the latest intent queued. Global
+uniqueness, immutable consistency and full trace summary truth remain provider obligations.
+
+`revealSourceKey(key: string): Promise<boolean>` directly resolves a full-source key, opens its
+ancestors and focuses its row. It returns false for missing, disabled, invalid, failed, revoked or
+unset-source targets. Home/End reaches full visible-preorder endpoints; branch navigation is
+RTL-aware and disabled-row traversal is bounded to 32 candidates. Controlled `activeSpanId` paints
+current state and reveals once per binding/ID without changing on activation. Accepted item
+activation emits only existing `lr-span-select { spanId }`. Expansion uses provider actions;
+there is no new public toggle event. `source-row` owns the single treeitem/focus/activation target,
+while its duration bar is decorative, unlike the legacy interactive bar below.
+
+Reassign even the same provider, or call a keyless `requestUpdate()`, after revision/state changes.
+Named display/selection/view-window paints reuse accepted data. Locale/lifecycle/source changes
+revoke obsolete requests, controls, reveal effects and announcements; ignored aborts keep physical
+permits until settlement. Localized loading/error/empty/retry and source counts do not turn newly
+loaded historical spans into status-change announcements. Source-only parts are `source-list`,
+`source-row`, `source-label`, `source-toggle`, `source-status` and `source-error`; existing axis,
+name/bar/meta/status/duration parts remain applicable. The following array admission/sorting and
+interactive-bar descriptions apply with `treeSource` unset.
+
 **Properties:** `spans: LyraSpan[] = []` (attribute: false) — `LyraSpan { id: string; parentId?:
 string; name: string; kind: 'agent' | 'llm' | 'tool' | 'retriever' | 'embedding' | 'other';
 startMs: number; endMs?: number; status: 'pending' | 'running' | 'success' | 'error' | 'denied' | 'incomplete' | 'unknown';
@@ -38,12 +96,19 @@ by the host (e.g. `"$0.0012"`) and rendered verbatim, never parsed or summed. On
 both this component (timeline projection via `startMs`/`endMs`) and `lr-trace-tree` (hierarchy
 projection via `parentId`) — never two shapes. Foreign runtime `kind` values render as `'other'`;
 explicitly unrecognized `status` values render the localized neutral `'unknown'` state, while an
-absent status renders `'pending'`. Raw provider status text is never shown. At most 500 unique valid
+absent status renders `'pending'`. Raw provider status text is never shown. Assignment retains the
+first 10,000 source entries in a bounded readonly outer snapshot; admitted row identities feed a
+descriptor-safe copy of the closed span display schema, so opaque provider fields do not consume
+the shared deep-copy budget. Reassign the collection after record changes. At most 500 unique valid
 spans mount; when `activeSpanId` resolves beyond
 the ordinary input-order budget, that span and its ancestor path reserve positions so the
-controlled active state remains visible. A localized `[part="limit"]` note exposes truncation. The
-time axis always scales to the whole trace, measured before that 500-span cap is applied, so a
-truncated tail can never shrink the axis and stretch the surviving bars across the track.
+controlled active state remains visible. A localized `[part="limit"]` note reports the actual
+number shown and the assigned source count when either ceiling omits entries. Counts use the
+effective locale; initial truncation stays silent and a later transition into truncation is
+announced politely. The time axis scales to the full admitted trace, measured before the 500-span
+cap is applied, so spans omitted only by that render cap cannot shrink the axis and stretch the
+surviving bars across the track. Active changes within the ordinary window reuse the existing
+projection and sort; reserving an outside active path can change the projection.
 `activeSpanId: string | null = null`
 (attribute `active-span-id`), `viewStartMs: number | null = null` (attribute `view-start-ms`) and
 `viewEndMs: number | null = null` (attribute `view-end-ms`) — override the auto-computed time
@@ -64,10 +129,15 @@ Space).
 **CSS parts:** `base`, `axis` (the time-ruler row, hidden when `without-axis` is set), `tick`, `tick-label`,
 `row`, `name` (the row's name gutter), `bar-track`, `bar` (the interactive, focusable status-toned
 bar), `meta` (secondary row info, shown inline under 480px), `status-text`, `duration`, `empty` (shown
-when `spans` is empty), `limit` (the 500-span projection notice), and `live-region`.
+when `spans` is empty), `limit` (the actual shown/source count for projection or input truncation).
 The interactive `bar` keeps a 24px minimum target in both axes even when its duration-derived
 paint width would otherwise be only a few pixels.
 
+With `treeSource` set, additional CSS parts are `source-list` (bounded provider virtual viewport), `source-row` (flat
+logical tree item and focus owner), `source-label` (row content), `source-toggle` (expand/collapse
+or retry button), `source-status` (loading, full-source count or empty text), and `source-error`
+(localized projection or row failure).
+
 The terminal axis tick is end-aligned so its label remains inside the allocated chart width, and an
 interior tick label that would overprint a neighbour is hidden (the terminal label is kept). Roving
 keyboard focus is computed from the currently rendered/filtered span ids, so a hidden active span

package/llms/components/lr-sparkline.md

@@ -9,7 +9,7 @@
 - **Release history** [CHANGELOG.md](../../CHANGELOG.md)
 - **Deprecated part** `base` since `8.0.0`; use part `::part(sparkline)`; removal not before `10.0.0` — The sparkline part names the rendered SVG wrapper unambiguously; base remains on that same node during the compatibility window. That version is a policy floor, not a plan: `wa-sparkline` still publishes its own deprecated `base` part, so this alias is removed only when upstream's is.
 - **Optional peers** none
-- **Themeable via** 5 parts, 3 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 6 parts, 3 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`
 
 ---
@@ -23,6 +23,13 @@ both dimensions through the aspect ratio.
 An empty or removed `data` attribute uses the `values` collection. With no usable fallback samples,
 no trend path is rendered. Attribute removal preserves `null` property readback, and supplying later
 space-separated samples restores the attribute-driven path.
+Derived values reuse the input array identity. Reassign after changes, or call `requestUpdate()`
+after mutating the current array, to refresh the projection.
+Large inputs retain at most 500 plotted samples, using the first and last finite samples plus
+bucket minima and maxima in source order. The accessible summary reports the full finite count
+and actual final value. Admission scans the current array or numeric string once without keeping
+a second full numeric array; this existing input path still performs synchronous work proportional
+to input length. Invalid samples are omitted, so plotted positions refer to finite-sample order.
 
 **Properties:**
 
@@ -51,13 +58,38 @@ space-separated samples restores the attribute-driven path.
   (including an intentional empty value), then nonempty `label`, then a nonempty programmatic
   `accessibleLabel`, then the localized generated summary
 
+**Prepared whole-source input:**
+
+- `preparedData: LyraPreparedSeriesData | null = null` (attribute: false) — accepts exactly one
+  ordered series with at most 500 semantic samples. While non-null it takes precedence over
+  `data` and `values`, without reading either legacy input. Clearing it restores the legacy route.
+  Invalid, accessor-backed, multiseries or oversized descriptors show localized unavailable text
+  through `status`; they are never resampled or replaced by the raw fallback.
+- Geometry uses original numeric x positions against the full `xDomain`, mirrored for RTL, and
+  the full `yDomain`; explicit `min`/`max` still override the y scale. Source-index order is kept
+  even when x is nonmonotonic. `breakBefore` splits every curve mode and each fill, so gaps are
+  never joined. Valid empty/all-invalid input remains an empty graphic.
+- The generated accessible summary reports full valid/invalid counts, displayed sample count,
+  full y domain and endpoint trend. The naming precedence above still applies.
+- Assignment, including the same reference, or explicit keyless `requestUpdate()` recaptures
+  mutable descriptors. Named presentation updates reuse the bounded capture. Disconnect releases
+  captured geometry; reconnect captures it again. The property still retains the caller's input
+  and its closures until replaced or cleared.
+
+Prepare data in host code with `prepareLyraSeriesData`, imported from
+`@aceshooting/lyra-ui/utilities/data-preparation.js` (the same module exports
+`LyraPreparedSeriesData`). Preparation scans all source positions in bounded yielding chunks and
+accepts an `AbortSignal`; the host owns that work, cancellation and assignment of the current
+result. Sparkline never calls `getPoint` or `queryRange` and starts no asynchronous source request.
+It adds no table, CSV or source-selection event.
+
 **Events:** none.
 
 **Slots:** none.
 
 **CSS parts:** `sparkline` and deprecated `base` are aliases on the same outer SVG, `fill` is the
 area path for solid/gradient appearance, `line` is the stroke path, and the additive `bar` is each
-extension-mode rectangle.
+extension-mode rectangle. `status` is the visible invalid-prepared-input message.
 
 **Themeable custom properties:** `--fill-color` (area/gradient stop color), `--line-color` (stroke
 color), and `--line-width` (stroke width). Each reads through the live CSS cascade; line/fill
@@ -86,15 +118,14 @@ No canvas bridge or manual refresh is needed.
 - flat data (every value equal, so the auto-computed range spans zero) now renders a centered
   midline/mid-height bars instead of collapsing every point to the bottom edge, and a single-value
   additive `values` series renders a visible flat line. Mirrored `data` deliberately requires two
-  values. **Every** rendering mode
-  (`mark="line"` with any appearance, or `mark="bar"`) decimates a `values` array past 500 points
-  down to at most 500 plotted
-  samples — evenly sampled by index, always keeping the first and last value exactly, not
-  aggregated/averaged. `mark="bar"` caps at 500 rendered `<rect>`s directly; line marks cap the
-  point count baked into the single `<path>`'s `d` string instead (an uncapped path string also
-  grows unbounded, even though the element count stays at one `<path>`). Auto `min`/`max` is still
-  scanned from the _full_ pre-decimation `values` array, so a real extreme value that decimation
-  happens to drop can't silently narrow the rendered scale.
+  values. Every legacy rendering mode (`mark="line"` with any appearance, or `mark="bar"`)
+  retains at most 500 finite samples from `values` or numeric `data`: the first and last finite
+  samples plus each source bucket's minimum and maximum, deduplicated and kept in source order.
+  Buckets follow array positions or token offsets in the source string; plotted x positions follow
+  finite-sample order. Values are never averaged, and global extrema are retained, so the automatic
+  scale covers the full finite input range. `mark="bar"` renders at most 500 `<rect>`s; line marks
+  bound the sample count in their path geometry. Prepared input is already bounded and is not
+  reduced again.
 - Point order mirrors under RTL while the numeric sample order remains unchanged. There are no
   animations, so reduced-motion mode needs no alternate timing branch.
 - **9.0 migration:** rename additive `type="bar"`/`"line"` to `mark="bar"`/`"line"`. Replace