@aceshooting/lyra-ui 29.0.2 → 29.1.0

package/llms/components/lr-heatmap.md

@@ -9,7 +9,7 @@
 - **Release history** [CHANGELOG.md](../../CHANGELOG.md)
 - **Deprecations** none
 - **Optional peers** none
-- **Themeable via** 18 parts, 13 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 22 parts, 13 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`
 
 ---
@@ -69,6 +69,150 @@ turning the overlay off moves a focused cell button to the canvas application co
 moves a focused canvas to the matching remembered cell, the first interactive cell, or the stable
 base when no cell exists. A newer external focus destination is never reclaimed.
 
+Calendar mode can summarize a complete large event population through host-side daily aggregation.
+Combine repeated events into one `{ date, value }` record per day before assigning
+`data = { kind: 'calendar', days }`: duplicate day records use first-valid identity rather than
+summation. A 365-day contribution view can therefore cover one million events while retaining
+365 daily totals. Keep the full event count and aggregation provenance beside the visualization;
+the heatmap's day count describes day records. A million distinct dates exceed the limits on day
+count and date span below. Query another bounded date window when needed.
+
+**Complete matrix source:** `matrixSource: LyraHeatmapMatrixSource | null = null`
+(attribute: false) opts into provider-owned indexed storage and aggregation. It takes precedence
+over legacy matrix arrays and requires `data.kind === 'matrix'`; a source with calendar data shows
+a localized error. Set `matrixSource = null` to restore the current legacy input. The provider is
+retained by identity. Reassign even the same object, or call a keyless `requestUpdate()`, after
+revision/state changes. Named presentation changes reuse accepted tiles; locale/lifecycle changes
+revoke obsolete effects. Providers should honor abort signals; ignored aborts occupy their physical
+request permits until settlement.
+
+```ts
+import type {
+  LyraHeatmapMatrixSource, LyraHeatmapMatrixViewport, LyraHeatmapMatrixReducer,
+  LyraHeatmapTile, LyraHeatmapMatrixRangeSelectDetail,
+} from "@aceshooting/lyra-ui/components/data/heatmap/heatmap.class.js";
+import type { LyraSourceRequest, LyraSourceValue, LyraNumericDomain } from
+  "@aceshooting/lyra-ui/utilities/data-preparation.js";
+```
+
+The source supplies immutable `revision` (a nonempty string or finite number), safe nonnegative integer `rowCount`/`columnCount`
+(with a safe integer product), and `domain: LyraNumericDomain | null`. This domain describes all
+finite source values; `null` means none. A valid explicit `domain` property still overrides the
+paint scale while the summary reports the provider's complete domain. Signed finite values are
+valid; only `null` represents a missing exact value. Methods may return a value or PromiseLike:
+
+- `query(request)` receives `{ signal, rowStart, rowEnd, columnStart, columnEnd, maxCells }` and
+  returns readonly `LyraHeatmapTile[]`. The host must supply an aggregation index, pyramid or server;
+  the component does not scan raw source cells to create tiles.
+- `getCell(row, column, { signal })` returns `{ value: number | null, rowLabel: string,
+  columnLabel: string }` for that exact absolute coordinate. Labels are each at most 1,024 UTF-16
+  units; malformed or oversized replies fail visibly without truncation.
+
+`matrixViewport: LyraHeatmapMatrixViewport | null = null` (attribute: false) is the zero-based,
+half-open rectangle `{ rowStart, rowEnd, columnStart, columnEnd }`; `null` covers the full matrix.
+Explicit axes must be nonempty, ordered safe integers contained in the source. Invalid new
+rectangles fail visibly without clamping or fallback. On source shrink, an unchanged previously
+accepted viewport keeps its span up to the new dimensions and clamps its origin; a newly assigned
+rectangle is validated afresh. Empty dimensions render an empty state without provider reads.
+`matrixReducer: LyraHeatmapMatrixReducer = 'mean'` (`matrix-reducer`) chooses `'mean' | 'min' | 'max'`
+for tile color; unsupported values fail visibly. Reducer changes repaint accepted tiles.
+
+Each tile supplies the viewport fields plus `{ count, validCount, min, max, sum }`. Tiles must
+partition the requested rectangle exactly once, without gaps or overlaps. `count` equals rectangle
+area, `validCount` is a safe integer from zero to `count`, and all statistics are finite and
+consistent with the complete domain. An empty-valid tile has `min: null`, `max: null`, `sum: 0`;
+otherwise extrema are ordered and `sum / validCount` lies within them, allowing a normalized
+`32 * Number.EPSILON` floating tolerance. Admission checks a bounded partition and arithmetic
+consistency; the provider owns the truth of aggregation over unseen records.
+
+The square overview allocates from available inline size, with tile budget
+`T = min(normalized maxCells, max(1, floor(plotWidth) ** 2))`; zero-width layouts defer requests.
+The existing `maxCells` default 10,000 and hard ceiling 100,000 apply to tiles here. The component
+retains bounded current/replacement tiles and O(T) partition-validation storage, without geometry
+or occupancy arrays proportional to logical cell count. One physical tile query and only the
+latest queued replacement are allowed. Exact reads share two physical permits, with current and
+pending windows of at most 400 records each plus at most one separately selected record (801 total,
+at most 1,640,448 retained exact-label units). A pending window replaces the old pane atomically;
+obsolete pending buffers are released. Canvas limits remain 16,384 per side and 16,777,216 pixels.
+
+`revealSourceCell(row: number, col: number): Promise<boolean>` resolves and focuses an exact source
+coordinate without changing controlled selection or emitting activation. Invalid/out-of-range
+coordinates make no provider call; absent, failed, noninteractive or revoked targets resolve
+`false`. Revealing outside an explicit viewport silently pans a same-size clamped rectangle by
+updating `matrixViewport`; a null/full viewport stays full. Focus restoration respects intervening
+user movement. Arrow keys move exact coordinates using physical left/right even under RTL;
+Home/End reach row endpoints, Ctrl+Home/Ctrl+End source endpoints, and PageUp/PageDown move up to
+20 rows. Each action examines at most 32 excluded candidates. With `accessibleCells: true`,
+`source-exact-window` is a separate at-most-20×20 exact grid below the overview, with full logical
+ARIA counts and absolute one-based row/column indices; the overview canvas is hidden from assistive
+technology. Without it, the named canvas owns the exact cursor.
+
+**Events:** Exact Enter/Space and singleton-tile pointer activation resolve `getCell` and emit the existing
+`lr-cell-activate` `{ row, col, value }` with absolute coordinates; missing `null` maps to `NaN`.
+`cellText`, `cellInteractive` and `cellColor` receive exact values and absolute coordinates, never
+aggregate means. Multi-cell tile pointer activation or Shift+Enter emits noncancelable
+`lr-matrix-range-select` with frozen `LyraHeatmapMatrixRangeSelectDetail`:
+`{ revision, rowStart, rowEnd, columnStart, columnEnd, count, validCount, min, max, sum }`.
+It proposes an aggregate without expanding `selectedCells` or synthesizing exact activation.
+`selectedCell`/bounded `selectedCells` stay controlled and programmatic assignments are silent;
+row/column, drag and Shift-range expansion remain legacy-only. Source geometry is proportional:
+`matrixGeometry` is `undefined` and source paints emit no `lr-matrix-geometry-change`.
+
+Source `exportData('csv')` exports the complete current accepted viewport's aggregate tile snapshot,
+with header `rowStart,rowEnd,columnStart,columnEnd,count,validCount,min,max,sum,reducer,value`.
+Coordinates are half-open and zero-based; numbers are unlocalized and missing extrema/reducer
+values are blank. It performs no provider reads and is not a raw-cell export. Loading, error or
+obsolete snapshots export `''`. PNG follows the current bounded overview and existing canvas
+readiness gates. Additional parts are `source-status`, `source-error`, `source-summary`, and
+`source-exact-window`; existing `base`, `canvas`, `cell`, `tooltip` and legend parts apply where
+rendered. The following dense matrix/calendar limits and geometry descriptions apply with
+`matrixSource` unset.
+
+**Exported matrix-source declarations:**
+
+Inherited viewport/tile fields are repeated to show the complete effective contracts. `HeatmapSourceCell { readonly value: number | null; readonly rowLabel: string; readonly columnLabel: string }` is the exact-cell reply described above.
+
+`LyraHeatmapMatrixViewport {
+  readonly rowStart: number;
+  readonly rowEnd: number;
+  readonly columnStart: number;
+  readonly columnEnd: number;
+}`
+
+`LyraHeatmapTile extends LyraHeatmapMatrixViewport {
+  readonly count: number;
+  readonly validCount: number;
+  readonly min: number | null;
+  readonly max: number | null;
+  readonly sum: number;
+  readonly rowStart: number;
+  readonly rowEnd: number;
+  readonly columnStart: number;
+  readonly columnEnd: number;
+}`
+
+`LyraHeatmapMatrixRangeSelectDetail extends LyraHeatmapTile {
+  readonly revision: LyraSourceRevision;
+  readonly count: number;
+  readonly validCount: number;
+  readonly min: number | null;
+  readonly max: number | null;
+  readonly sum: number;
+  readonly rowStart: number;
+  readonly rowEnd: number;
+  readonly columnStart: number;
+  readonly columnEnd: number;
+}`
+
+`LyraHeatmapMatrixSource {
+  readonly revision: LyraSourceRevision;
+  readonly rowCount: number;
+  readonly columnCount: number;
+  readonly domain: LyraNumericDomain | null;
+  query(request: LyraSourceRequest & LyraHeatmapMatrixViewport & { readonly maxCells: number }): LyraSourceValue<readonly LyraHeatmapTile[]>;
+  getCell(row: number, column: number, request: LyraSourceRequest): LyraSourceValue<HeatmapSourceCell>;
+}`
+
 **Properties:**
 
 - `data: HeatmapData = { kind: 'matrix', rowLabels: [], colLabels: [], values: [] }` (attribute:
@@ -88,6 +232,11 @@ weekdayLabelWidth?: number|'auto'; weekdayLabelText?: (jsWeekday:number)=>string
     pins its width, while `'auto'` measures the widest rendered weekday label without shrinking
     below the built-in `28px` gutter or growing beyond 40% of the host. Unset preserves the original
     `28px` geometry; malformed values are ignored.
+- `maxCells: number = 10000` (attribute `max-cells`) — projection budget, normalized to 1–100,000.
+  Matrix projection keeps a rectangular prefix within that budget. Calendar input retains at most
+  that many days and scales its sparse span proportionally from the default 530 weeks, up to 5,300
+  weeks, with a minimum one-week span. The accessible cell overlay remains windowed to 400 buttons,
+  and canvas backing-store limits still apply.
 - `cellSize: number = 22` (attribute `cell-size` — default `22` in matrix mode, `11` in calendar
   mode when left unset; explicitly setting it now governs both modes' per-cell size alike, and it's
   ignored in either mode when `fitToWidth` is set)
@@ -455,6 +604,10 @@ bar between them, while `legendStops` is supplied), `legend-stop` (one per `lege
 closes the legend row, present in both the gradient and the `legendStops` branch),
 `legend-annotation` (one per labeled `annotations` entry)
 
+With `matrixSource` set, additional CSS parts are `source-summary` (complete matrix and displayed viewport summary),
+`source-status` (loading text), `source-error` (localized failure), and `source-exact-window`
+(the bounded exact grid rendered when `accessibleCells` is true).
+
 **Themeable custom properties:** `--lr-heatmap-scale-lo` (default `var(--lr-color-brand-quiet)`),
 `--lr-heatmap-scale-hi` (default `var(--lr-color-brand)`) — the sequential color-ramp endpoints
 (matrix mode) or quartile-bucket ramp endpoints (calendar mode), resolved via `getComputedStyle` each
@@ -540,10 +693,13 @@ is now literal.
 
 **Known gotchas:**
 
-- Matrix projection is capped at 10,000 renderable cells. Calendar input is capped at 10,000
-  records and 530 weeks, and the color-step/legend-stop/annotation projections are each capped at
-  256 entries. `[part="projection-limit"]` and the generated accessible summary disclose every
-  truncation. The semantic grid mounts at most 400 cell buttons while preserving full navigation.
+- Matrix and calendar projections use `maxCells` (10,000 by default); calendar span scales from
+  the default 530 weeks with that budget. Color-step/legend-stop/annotation projections each display
+  at most 256 entries. Their owned snapshots and `selectedCells` retain at most 10,000 entries and
+  50,000 cloned values; deeply nested records can reach the value budget first.
+  `[part="projection-limit"]` and the generated accessible summary disclose visual projection and
+  input loss; changed notices are announced politely. The semantic grid mounts at most 400 cell
+  buttons while preserving full navigation.
 - Calendar duplicates use a first-valid-wins ISO-date identity. Invalid dates are dropped. `data.columnX`
   and `data.rowY` results must be finite, nonnegative, monotonic and non-overlapping; an invalid,
   throwing or hostile result safely falls back to the normal coordinate for that position.

package/llms/components/lr-histogram.md

@@ -9,7 +9,7 @@
 - **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 this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 18 parts, 39 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,7 +22,7 @@ Bins `values` into `bins` equal-width buckets and renders as a bar chart (extend
 **Properties:**
 - `bins: number = 10` — finite values are floored and clamped to 0–1,000 before allocation;
   non-finite values produce no buckets
-- `values: number[] = []` (attribute: false)
+- `values: readonly number[] = []` (attribute: false)
 - `seriesLabel: string = ''` (attribute `series-label`) — dataset label used for the
   legend/tooltip/table; empty falls back to localized "Frequency". Inherited `label` keeps its
   chart-wide accessible-name meaning.
@@ -34,9 +34,10 @@ Bins `values` into `bins` equal-width buckets and renders as a bar chart (extend
   bucket range strings, so different bin boundaries do not match unless their labels are exactly
   equal. Horizontal or continuous-x raw configurations do not participate.
 - `labels`/`datasets`/`type` are **derived, read-only** (installed as getter/setter pairs on the
-  prototype; direct writes are silently ignored) — `labels`/`datasets` are computed from
-  `values`/`bins` (memoized per instance, keyed by reference equality on `values` plus the
-  normalized `bins`), and `type` always reads back `'bar'` regardless of any assignment. This
+  prototype; direct writes are silently ignored) — on the legacy raw route, `labels`/`datasets`
+  are computed from `values`/`bins` (memoized per instance, keyed by reference equality on `values`
+  plus the normalized `bins`). A supplied `distribution` takes precedence and supplies the exact
+  bin categories/counts instead. `type` always reads back `'bar'` regardless of any assignment. This
   specialist owns its controller because a non-bar type would contradict the derived distribution.
 - All other `LyraChart` properties are inherited and usable: `description`, `grid`, `axes`, `size`, `indexAxis`
   (`index-axis`), `hiddenDatasets`, `hiddenDatums`, `legendPosition` (`legend-position`),
@@ -46,15 +47,54 @@ Bins `values` into `bins` equal-width buckets and renders as a bar chart (extend
   `tooltipFooterFormatter`, `area`, `zoomable`, `config`, `height`, `xLabel` (`x-label`),
   `yLabel` (`y-label`), `y2Label` (`y2-label`), `withoutZeroBaseline` (`without-zero-baseline`),
   `stacked`, `stackedAxes`, `dataLabels` (`data-labels`), `stackTotals` (`stack-totals`), `withDataTable`
-  (`with-data-table`), `dataTableToggle` (`data-table-toggle`), `chartArea` (readonly).
+  (`with-data-table`), `dataTableToggle` (`data-table-toggle`), `maxRecords` (`max-records`, default
+  `1000`, range 2–1,000), `chartArea` (readonly).
 
 **Methods:** `resetZoom()`, `refreshTheme()`, and `renderChart()` are inherited; `appendSamples(values,
 maxSamples?)` appends finite raw samples and keeps a rolling window of the newest `maxSamples`
 (at most 10,000, also the default; an assigned `values` array longer than that keeps its newest
-10,000 samples, with a development-mode warning).
+10,000 samples, with a localized `limit` notice). The bounded immutable window reuses existing
+canonical samples without re-admission. Use `distribution` below to represent a larger whole-source distribution.
+Appends inspect newest positions first and stop once the retained window is full. Invalid-heavy
+batches yield after 10,000 inspected positions and may finish asynchronously. Concurrent appends
+apply in call order; assigning `values` or disconnecting cancels unfinished batches. Pending input
+arrays remain caller-owned and must stay unchanged until their batch is applied or canceled.
+Unreadable positions are treated as invalid and do not block later queued appends.
 `appendData()` remains a working compatibility adapter (no longer deprecated); prefer
 `appendSamples()` for new code.
 
+**Prepared whole-source distribution:**
+
+- `distribution: LyraHistogramDistribution | null = null` (attribute: false) — exact bounded
+  bins, normally from `prepareLyraHistogram`, imported from
+  `@aceshooting/lyra-ui/utilities/data-preparation.js` with its `LyraHistogramDistribution` type.
+  A supplied distribution takes precedence over `values`, `bins` and inherited `preparedData`.
+  Inherited `preparedData` alone is incompatible with histogram bin semantics and fails visibly.
+- Own data properties supply a revision, conserving safe nonnegative source/valid/invalid counts,
+  observed `domain` (null only without valid observations), strict finite increasing `edges`,
+  exact `binCounts`, `belowCount` and `aboveCount`. There are at most 1,000 bins and 1,001 edges;
+  valid empty input may have no edges. Every occupied interval and represented extremum must
+  agree with the observed domain and counts. Accessors, sparse arrays and malformed descriptors
+  are rejected without invoking getters. All bins must fit effective `maxRecords` (2–1,000) and
+  the inherited rectangular accessible-table and metadata budgets; no bins are sampled or merged.
+- Plot, table, CSV and `binnedBuckets()` expose the exact in-range bins. Bins are half-open except
+  the final upper edge, which is inclusive. Below/above observations stay in the full summary,
+  together with whole-source valid/invalid counts and observed range; they are not invented bars.
+  Existing point/datum activation keeps the bin index and frequency.
+- Assignment or explicit keyless `requestUpdate()` recaptures mutable descriptors, including
+  same-reference assignments and coalesced updates. Locale and series-label changes rebuild
+  bounded labels. Replacing a same-locale catalog requires explicit `requestUpdate()`.
+  Distribution assignment cancels unfinished raw appends; raw append methods are inactive while
+  it is supplied. Clearing it restores the previous raw values without stale queued commits.
+  Disconnect retains the existing cancellation and peer lifecycle.
+
+The component retains bounded owned copies and the property retains the caller's descriptor until
+replaced or cleared. It never reads raw samples to render this route. `prepareLyraHistogram` scans
+all positions in bounded yielding chunks and accepts an `AbortSignal`; its source reader execution
+and cancellation remain host-owned. Invalid or overbudget distributions use the inherited visible
+localized error; valid empty/all-invalid distributions remain valid. No new events or parts are
+added; `limit` and the accessible description carry the full distribution summary.
+
 **Events:** `lr-zoom`, `lr-datum-activate`, `lr-point-activate`, `lr-datum-visibility-change-request`
 (cancelable), `lr-datum-visibility-change`, `lr-legend-visibility-change-request` (cancelable), and
 `lr-legend-visibility-change` — inherited; `lr-point-activate`'s `index` is the bucket index and
@@ -65,12 +105,17 @@ the bin width, with no fraction digits once the width reaches 10 and no forced t
 The inherited datum-visibility events apply only to radial controllers; the histogram keeps its
 bar controller and dataset legend even with `legend-mode="datum"`.
 
+**Events:** The inherited `lr-source-category-select` and `lr-source-point-select` events are not
+emitted for histogram bins. Inherited `lr-spatial-bin-select` and `lr-spatial-point-select` are
+also not emitted by this fixed-bar specialist: inherited spatial `preparedData` alone is rejected,
+and `distribution` supplies bin categories rather than a spatial route.
+
 **Slots:** default JSON configuration script, `data-table`, `center`.
 
 **CSS parts:** `base`, `plot`, `canvas`, `legend`, `legend-item`, `legend-item-hidden`, `legend-swatch`,
 `sync-crosshair` (inherited decorative category line during synchronization; the native canvas
 tooltip has no CSS part),
-`reset-zoom-button`, `description`, `notices`, `data-table`, `data-table-toggle`, `data-truncation`, `feature-warning`, `center`, `error` (neutral visible message
+`reset-zoom-button`, `description`, `notices`, `data-table`, `data-table-toggle`, `data-truncation`, `limit`, `feature-warning`, `center`, `error` (neutral visible message
 rendered in place of `canvas` when the optional `chart.js` peer dependency fails to load; the
 failure transition is announced through the shared document-level light-DOM assertive sink —
 inherited from `LyraChart`, unaffected by the binning logic).
@@ -113,7 +158,8 @@ their semantics, defaults, and gotchas.
 - non-finite samples in `values` are dropped before bucketing rather than corrupting bucket-index
   math; a constant domain produces one truthful single-value bucket, including at numeric extremes.
 - raw `config.options` and plugins remain available, but `config.type` and `config.data` are ignored:
-  the histogram owns its bar controller and derives all categories from `values`/`bins`.
+  the histogram owns its bar controller and derives categories from `values`/`bins` on the legacy
+  raw route, or from `distribution` when provided, which takes precedence.
 - `values`/`bins`/`seriesLabel` changes join the inherited connected-and-visible redraw path. There is no
   second post-update refresh, so a same-tick disconnect cannot recreate Chart.js on a detached
   canvas and off-screen sample updates do not repaint it.

package/llms/components/lr-ingestion-queue.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** 17 parts, 1 custom property — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 21 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`
 
 ---
@@ -23,6 +23,18 @@ Nonstring failure details use the localized failed-stage label for row text and
 announcements. Omitted details stay omitted. Formatting uses the effective locale, and historical
 failures remain silent on mount.
 
+Assignment retains the first 10,000 queue items in a bounded readonly outer snapshot. Admitted
+record identities feed a descriptor-safe copy of the closed row/document display fields rather
+than a deep copy of arbitrary provider data, so nested input does not consume the shared
+50,000-value deep-copy budget. Replace the collection to publish record changes. Normalized rows
+are reused until the admitted items or the resolved localized failure label changes; replacing the
+queue normalizes the new rows once and compares failures with the previous normalized rows.
+
+A localized `[part="limit"]` note reports retained and assigned-source counts when the input
+ceiling is exceeded on the legacy items route. Counts use the effective locale. Initial truncation is silent; a later
+transition into input truncation is announced through the shared polite sink, separately from
+failure announcements.
+
 **Properties:**
 
 - `items: IngestionQueueItem[] = []` (attribute: false) — `IngestionQueueItem { id: string;
@@ -47,7 +59,7 @@ embeddedChunkCount?: number; attempts?: number; error?: string }` (exported here
   exactly this many items still render as a plain list. Before 9.0.0 this was spelled
   `virtualizeThreshold`/`virtualize-threshold` _and_ compared inclusively (`>=`), so a migration
   that only renames the attribute shifts the switchover point by one item
-- `announce: boolean = false` (reflected) — opt-in: announce the failures the queue **already
+- `announce: boolean = false` (reflected) — legacy items route opt-in: announce the failures the queue **already
   carries** the first time it mounts, instead of staying silent until a row fails later. The
   mount-time pass reuses the one announcement path a later failure takes — the same shared
   assertive light-DOM region, the same locale-aware conjunction list of the caller-supplied
@@ -66,6 +78,44 @@ embeddedChunkCount?: number; attempts?: number; error?: string }` (exported here
 Queue item ids must be nonblank and unique. Malformed rows and later duplicates are omitted
 first-wins before empty state, counts, virtualization, failure announcements, rendering, or actions.
 
+**Provider pages:**
+
+- `dataSource: IngestionQueueSource | undefined` (attribute: false) —
+  `IngestionQueueSource = LyraPageSource<IngestionQueueItem, IngestionQueueSourceQuery>`, exported
+  by `@aceshooting/lyra-ui/components/retrieval/ingestion-queue/ingestion-queue.class.js`.
+  `LyraPageSource` is exported by `@aceshooting/lyra-ui/data-sources.js`. The query is one frozen
+  empty object (`readonly [key: string]: never`); the provider owns queue order and exact total.
+  A present source takes precedence over `items`, including invalid sources, which fail visibly.
+  Setting `undefined` restores the existing items route and virtualization defaults.
+- `sourcePage: number = 0` (attribute `source-page`) — zero-based provider page, normalized to a
+  finite nonnegative safe offset for the effective page size.
+- `sourcePageSize: number = 100` (attribute `source-page-size`) — normalized to 1–500; an effective
+  size change resets page zero. Pages above `virtualizeAt` use the existing virtual list.
+- `readonly sourceTotal: number | null` — null without a source, while pending or after failure;
+  otherwise the exact global queue total, including settled zero. The compact child pager uses
+  one-based pages and unknown total `-1`, disables navigation pending/error, and contains its
+  events. A valid stale page corrects once and synchronizes `sourcePage`.
+
+Only the current bounded page is retained; source mode never normalizes the legacy inventory.
+Closed row/document display fields are frozen copies with at most 65,536 aggregate UTF-16 text
+units per row. Required malformed records reject the whole page, rather than silently dropping
+rows; source getters are not invoked and arbitrary nested fields are not traversed. Existing stage,
+fallback text and action semantics apply. Historical failures stay quiet on page changes, refresh
+and reconnect even with `announce`; loading/errors use localized source status announcements.
+
+Same-source assignment or keyless `requestUpdate()` refreshes source/revision. Named paints and
+string overrides reuse the current page; reconnect replays the current bounded request. Changes to
+source, revision, refresh intent or connection revoke obsolete work. Requests receive an abort
+signal and stale results cannot publish; the provider owns callback execution cost and cooperation
+with cancellation. Rapid changes retain bounded active work and latest intent, without page history
+or a complete queue cache.
+
+Only current settled source rows can emit the existing retry/cancel details below. Pending,
+replaced, removed or disconnected source controls cannot act on stale rows. Provider-load failure
+shows `source-status` with a `source-retry` button: it reloads only the current failed page, emits
+no row `lr-retry`, and obsolete load-retry controls are inert. `source-pagination` styles navigation.
+This route adds no public event, table or CSV export.
+
 **Events:**
 
 - `lr-retry` (`detail: IngestionRetryEventDetail` = `RetryEventDetail & { itemId: string }` =
@@ -86,7 +136,8 @@ per-item stage label), `item-progress`,
 `chunkCount` and `embeddedChunkCount` are set), `item-attempts` (only once `attempts > 0`),
 `item-error` (only for `stage="failed"` with `error` set), `failure-live` (the visually hidden,
 `aria-hidden` mirror of the last announced batch of fresh failures), `item-actions`,
-`retry-button`, `cancel-button`, `empty`.
+`retry-button`, `cancel-button`, `empty`, `limit` (the input-retention notice),
+`source-status`, `source-retry`, `source-pagination`.
 
 `failure-live` is a styling and inspection surface and carries no live-region role of its own. The
 announcement itself goes to the library's shared **light-DOM** assertive region, appended to the

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

@@ -9,7 +9,7 @@
 - **Release history** [CHANGELOG.md](../../CHANGELOG.md)
 - **Deprecations** none
 - **Optional peers** none
-- **Themeable via** 10 parts, 9 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 17 parts, 9 custom properties — see this component's own `@csspart`/`@cssprop` list below
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
 
 ---
@@ -33,22 +33,96 @@ Removing `query` clears matches while retaining null property readback. Before a
 `searchPrevious()` selects the final match; later next/previous navigation wraps. Navigation may
 reopen the selected match’s ancestors while unrelated manual collapse remains intact.
 
+**Complete provider hierarchy:** `treeSource: JsonViewerTreeSource | undefined`
+(attribute: false) supplies a complete logical hierarchy without flattening it or copying it into
+`data`. A defined provider takes display precedence; invalid defined input shows a localized source
+error. Setting `undefined` restores the current `data`. `maxNodes` and `expandDepth` govern only
+the legacy `data` route; `maxHeight` also constrains the source scroller.
+
+```ts
+import type { JsonViewerTreeSource } from
+  "@aceshooting/lyra-ui/components/utility/json-viewer/json-viewer.class.js";
+import type {
+  LyraHierarchyProjection, LyraHierarchyRow, LyraInspectionNode,
+  LyraSourceSearchRequest, LyraSourceSearchResult,
+} from "@aceshooting/lyra-ui/data-sources.js";
+```
+
+`JsonViewerTreeSource` is `LyraHierarchySource<LyraInspectionNode, LyraHierarchyQuery>`.
+Its immutable `revision` is a nonempty string or finite number identifying provider state. `project(request)` receives revision, locale,
+abort signal, previous opaque `state` (initially `null`), `{ search: query, hiddenKinds: [] }`, and
+an action such as `reset`, `toggle` or `reveal`. It returns `{ state, total, rows, focusIndex? }`:
+`total` counts every logical node, including collapsed nodes; `rows.count` is the complete visible
+preorder, with `rows.count <= total`. Counts are safe nonnegative integers. The nonempty opaque
+state token is at most 65,536 UTF-16 units. `rows` supports indexed `itemAt`/`keyAt`/`indexOfKey`,
+or asynchronous `read` with required `indexOfKey`; there is no full-tree lookup scan.
+
+Each `LyraHierarchyRow<LyraInspectionNode>` supplies a globally unique nonblank `key`, `parentKey`,
+one-based logical `level`/`position`, exact sibling `setSize`, `childCount`, `expanded`, `selected`,
+and optional `disabled`/`selectionState`. Its closed own-data `value` supplies string `name`,
+string `path` equal to the row key, optional string `value`, and a `kind` from
+`'object' | 'array' | 'scalar' | 'element' | 'attribute' | 'text' | 'comment' | 'processing-instruction'`.
+Keys and each inspection string are at most 65,536 UTF-16 units. The admitted row cache, staging,
+one separately retained focused row and opaque state share a 2,000,000-unit payload budget;
+oversized rows/pages fail visibly instead of clipping a result. The source view mounts at most
+301 rows and caches four 100-row pages, plus at most one focused row. Range reads request at most
+100 rows with at most two physical reads pending; projection calls serialize with only the latest
+replacement queued. Global key uniqueness and immutable snapshot consistency remain provider-owned.
+
+`revealSourceKey(key: string): Promise<boolean>` asks the provider to open ancestors and focus its
+exact returned row. It resolves `false` for absent, failed, canceled or obsolete targets. Compact
+keys support deeply nested sources without allocating a full ancestor path; logical ARIA depth
+and sibling positions remain exact while visual indentation clamps at 32 levels. Provider
+projections own expansion. Reassign even the same source object, or call a keyless
+`requestUpdate()`, after changing its revision/state. Locale changes, reconnect and adoption refresh
+the projection; named presentation updates reuse accepted data. Replacement, refresh, query changes
+and lifecycle cancellation revoke older search, reveal and copy effects. Providers should honor
+abort signals; ignored aborts retain their physical request permits until settlement.
+
+Source `query`/`runSearch()` uses optional provider `search({ revision, locale, signal, query,
+limit })`, which returns `{ hits: [{ key }], total, exhaustive }`. Search covers the complete
+logical hierarchy, counts matching nodes rather than separate key/value occurrences, and retains
+at most 10,000 hits regardless of `maxNodes`; query length is at most 4,096 UTF-16 units. Search-hit
+keys share a separate 2,000,000-unit budget. `exhaustive` means every global hit was returned;
+`total` is the known global total or `null`. `lr-search-change` retains
+`{ query, matchCount, matchCountExact, activeIndex }`; unavailable, partial, invalid and over-budget
+results never claim exactness. The initial cursor is `-1`. `searchNext()`/`searchPrevious()` reveal
+retained hit keys without rerunning global search. `search-status` discloses unavailable/partial
+search, and clearing the query clears its hits and cursor.
+
+Source copy controls require both `copyable` and a callable provider `copy`. The request includes
+revision, locale, abort signal, `key`, `scope` and `maxBytes`: scalar rows use `'node'`, containers
+`'subtree'`, and the toolbar uses `'document'` with `key: null`. The provider must return complete
+text within 25 MiB UTF-8; the component never serializes loaded rows as a substitute. Provider or
+byte-budget failures show localized copy failure without clipboard events. A current platform
+write retains the frozen `lr-copy`/`lr-copy-error` outcome and clipboard-only `lr-error` contract.
+Source-only parts are `source-list`, `source-row`, `source-toggle`, `source-label`, `source-status`,
+`source-error`, and `search-status`; `base`, `tree`, `toolbar`, `key`, `value`, and `copy-button`
+also apply. The flat source rows own logical treeitem semantics.
+
 **Properties:**
 
 - `data: unknown` (attribute `false` — property-only, not settable via an HTML attribute)
+- `maxNodes: number = 5000` (attribute `max-nodes`) — the shared admission, search and render
+  node budget for `data`; effective range 1–50,000. Finite fractions truncate and values clamp to that range;
+  non-finite inputs use 5,000. Changing it re-admits the retained original `data`, so raising the
+  budget does not require reassigning `data`. The depth ceiling remains 100, and the existing
+  localized `limit` part discloses traversal truncation.
 - `expandDepth?: number` (attribute `expand-depth`) — nodes at or beyond this nesting depth
   (root = `0`) start collapsed, so only the levels above it start expanded; omitted/`undefined`
   means nothing auto-collapses
 - `maxHeight: string = ''` (attribute `max-height`) — a CSS length (e.g. `"20rem"`); once set, the
-  viewer scrolls internally past this height instead of growing the page. Values that do not parse
+  viewer scrolls internally past this height instead of growing the page. Source mode otherwise
+  uses a `var(--lr-size-20rem)` height ceiling. Values that do not parse
   as CSS `max-height`, contain declaration breaks, or contain `url()` are ignored, leaving
   `--lr-json-viewer-max-height` in control
 - `copyable: boolean = false` (reflected) — shows copy-to-clipboard affordances: one for the whole
   value, plus one per node
-- `query: string = ''` — case-insensitive substring match against keys/values; matches are
-  highlighted and their ancestors auto-expanded
+- `query: string = ''` — with `treeSource` unset, case-insensitive substring match against
+  keys/values; matches are highlighted and their ancestors auto-expanded. Source matching is
+  provider-owned as described above
 
-**Methods:** `runSearch(query)` sets the declarative `query` property and awaits the recompute,
+**Search methods:** `runSearch(query)` sets the declarative `query` property and awaits the recompute,
 resolving the match count. `searchNext()`/`searchPrevious()`
 advance/step back a match cursor
 (wrapping), reveal that selected match even when one of its ancestors was explicitly collapsed,
@@ -56,7 +130,7 @@ mark it as the active `aria-current` result, announce its position, and scroll i
 they resolve `false` when there are no matches. `clearSearch()` resets `query` to `''`, clearing all
 matches and the cursor.
 
-**Events:** `lr-copy` (`detail: LyraClipboardWriteSuccess`, `{ ok: true; text: string }`) — fired by
+**Events:** With `treeSource` unset, `lr-copy` (`detail: LyraClipboardWriteSuccess`, `{ ok: true; text: string }`) — fired by
 the top-level copy button or a per-node one only after the owning browsing context's clipboard write
 fulfills. `lr-error` (no detail) and `lr-copy-error` (`detail: LyraClipboardWriteFailure`) fire when
 serialization or clipboard writing fails; the detailed frozen outcome carries `ok: false`, the
@@ -71,7 +145,7 @@ fired whenever the search query, match count, or active-match cursor changes, fr
 property write. `matchCountExact` is `false` when the bounded traversal only proves a lower bound;
 the rendered count uses an “at least” prefix in the same case.
 
-**Slots:** none — the tree is rendered entirely from `data`.
+**Slots:** none — the tree is rendered from `data` or `treeSource`.
 
 **CSS parts:** `base` (root scroll container, respects `max-height`), `toolbar` (wrapper around the
 top-level copy button, only rendered when `copyable`), `tree` (wrapper around the rendered node
@@ -88,6 +162,12 @@ clipboard") or a per-node one (aria-label `Copy ${key/type}`, e.g. "Copy age");
 `copyable`), `limit` (the localized notice rendered below the tree when the depth/node traversal
 budget truncates rendering or search — absent entirely for any document within budget)
 
+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).
+`search-status` discloses unavailable or partial global provider search.
+
 Collapsed arrays retain their exact safe `.length`. A broad object whose key count itself exceeds
 the traversal budget uses an “at least” preview rather than presenting the retained prefix as a
 false total. Per-row copy actions remain visible by default on coarse-pointer/no-hover devices;

package/llms/components/lr-knowledge-base-admin.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** 6 parts, 2 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 7 parts, 2 custom properties — see this component's own `@csspart`/`@cssprop` list below
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
 
 ---
@@ -19,9 +19,65 @@
 Tabbed operations shell composing `lr-knowledge-base` and `lr-ingestion-queue`. It forwards source
 and ingestion actions under namespaced events; host-owned controls such as chunking, embedding,
 permissions, and connector settings go in the `settings` slot.
+Only the active child view is mounted. With its corresponding provider unset, if the shell's own
+admission truncates the source or ingestion array, an `input-limit` note for the active tab reports
+the original assigned count; it does not infer that count from the already-truncated child input. Initial and reconnect notes
+are quiet, and later changed omissions are politely announced.
 
-**Properties:** `sources: KnowledgeSource[] = []` (attribute: false); `ingestionItems:
-IngestionQueueItem[] = []` (attribute: false); `activeTab: 'sources' | 'ingestion' = 'sources'`;
+**Provider forwarding:** `dataSource: KnowledgeBaseSource | undefined` and
+`ingestionSource: IngestionQueueSource | undefined` are property-only inputs
+(attribute: false). `dataSource` supplies the Sources tab's `lr-knowledge-base.dataSource`;
+`ingestionSource` supplies the Ingestion tab's `lr-ingestion-queue.dataSource`. Each takes
+precedence over its matching legacy `sources`/`ingestionItems` array. Set that provider to
+`undefined` to restore the current retained legacy collection and its original admission-loss
+notice. Defined invalid providers keep the child's source-authoritative failure behavior when
+activated; the shell does not replace them with the legacy array.
+
+```ts
+import "@aceshooting/lyra-ui/components/lr-knowledge-base-admin.js";
+import type { KnowledgeBaseSource } from
+  "@aceshooting/lyra-ui/components/retrieval/knowledge-base/knowledge-base.class.js";
+import type { IngestionQueueSource } from
+  "@aceshooting/lyra-ui/components/retrieval/ingestion-queue/ingestion-queue.class.js";
+
+declare const inventoryProvider: KnowledgeBaseSource;
+declare const queueProvider: IngestionQueueSource;
+const admin = document.querySelector('lr-knowledge-base-admin')!;
+admin.dataSource = inventoryProvider;
+admin.ingestionSource = queueProvider;
+```
+
+The shell stores provider references by identity without inspecting their revision, methods,
+rows or totals, querying them or cloning them. An inactive assignment only stores the reference;
+it neither reads that provider nor refreshes the active child. Only the mounted active child
+receives its matching provider and owns validation, requests, bounded page data, loading, errors,
+retry and global totals, as described by [knowledge-base](#lr-knowledge-base) and
+[ingestion-queue](#lr-ingestion-queue). The shell adds no `sourcePage`, `sourcePageSize` or
+`sourceTotal` API and keeps no page cache or inactive child instance.
+
+An active provider assignment, including the same reference, synchronously forwards one refresh;
+the following shell render does not repeat that assignment. A keyless `admin.requestUpdate()`
+refreshes only the current child once. Named heading/label/slot paints and re-picking the active
+tab do not refresh providers. To use a repeated `lr-activate` as a refresh intent, explicitly call
+`requestUpdate()` in the host. Locale changes follow the active child's locale-dependent refresh
+contract. Reassign or explicitly refresh after changing provider revision/state.
+
+Switching tabs disconnects the old child and cancels its authority; returning mounts a new child
+at its documented default page zero. Page navigation state does not persist across tab switches.
+If a previous same-provider page call ignores abort, the remounted child's replacement page call
+waits for it to settle instead of overlapping it. Providers should settle promptly after
+cancellation. Different provider identities retain independent request capacity.
+
+A defined provider suppresses only its active collection's legacy `input-limit` notice. The
+inactive provider/collection is not inspected to compute that notice, and both parent-owned
+legacy collections remain intact. Source/ingestion actions are forwarded only from the current
+active child with their existing names, original IDs and bounded immutable detail. Provider
+replacement, refresh, tab change, disconnect and adoption revoke old action callbacks, including
+retained controls that reuse an ID. Ingestion retry/cancel keep their existing namespaced detail
+and non-cancelable notification semantics; the shell never performs the operation itself.
+
+**Properties:** `sources: readonly KnowledgeSource[] = []` (attribute: false); `ingestionItems:
+readonly IngestionQueueItem[] = []` (attribute: false); `activeTab: 'sources' | 'ingestion' = 'sources'`;
 `label?: string` (the visible heading and the tablist's distinct accessible name; omission uses the
 localized admin label, while an explicit empty string empties the heading and the tablist keeps the
 localized name; authored host `aria-label` independently names the admin component and is not
@@ -51,7 +107,7 @@ that moves an invalid or newly-hidden tab back to Sources is not a user activati
 
 **Slots:** `settings` — host-owned KB configuration controls.
 
-**CSS parts:** `base`, `heading`, `tabs`, `tab`, `panel`, `settings`.
+**CSS parts:** `base`, `heading`, `tabs`, `tab`, `panel`, `settings`, `input-limit`.
 
 **Themeable custom properties:** `--lr-knowledge-base-admin-tab-selected-border` (default
 `var(--lr-color-brand)`) and `--lr-knowledge-base-admin-tab-selected-color` (default