@aceshooting/lyra-ui 29.0.2 → 29.1.0

package/llms/components/lr-knowledge-base.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** 29 parts, 10 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 30 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,9 +22,113 @@ Controlled source list for a retrieval knowledge base: sync status, indexing hea
 per-row create/sync/pause/delete requests. Composes `lr-table`, `lr-badge`, `lr-stat`, and a per-row
 `lr-dropdown` containing `lr-menu`. Never syncs or indexes anything itself.
 
+**Full-source inventory:** `dataSource: KnowledgeBaseSource | undefined`
+(attribute: false) takes precedence over `sources`. Only `undefined` restores the current legacy
+array; invalid defined providers, including untyped null, fail visibly. The provider stays
+caller-owned by identity, with an immutable revision and records for that revision.
+`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
+global total, or null outside source mode and while the current provider page is pending or failed.
+Page indices truncate/clamp to a safe nonnegative offset; nonfinite page/size inputs use 0/100.
+Page-size and accepted sort changes reset page zero. An out-of-range page receives at most one
+corrective last-page request; controlled page writes and correction emit no user page event.
+The table's compact server pagination navigates global pages; its internal one-based page-change
+event is consumed to update `sourcePage`.
+
+```ts
+import "@aceshooting/lyra-ui/components/lr-knowledge-base.js";
+import type { KnowledgeBaseSource, KnowledgeBaseSourceQuery, KnowledgeBaseSourceSummary,
+  KnowledgeSource } from
+  "@aceshooting/lyra-ui/components/retrieval/knowledge-base/knowledge-base.class.js";
+import type { LyraPageSource, LyraPageResult, LyraSourceRecord } from
+  "@aceshooting/lyra-ui/data-sources.js";
+
+declare const provider: KnowledgeBaseSource;
+const inventory = document.querySelector('lr-knowledge-base')!;
+inventory.dataSource = provider;
+```
+
+**Exported source declarations:**
+
+`KnowledgeBaseSource = LyraPageSource<KnowledgeSource, KnowledgeBaseSourceQuery, KnowledgeBaseSourceSummary>`.
+
+`KnowledgeBaseSourceQuery {
+  readonly sortKey: string | null;
+  readonly sortDir: 'asc' | 'desc';
+}`
+
+`KnowledgeBaseSourceSummary {
+  readonly total: number;
+  readonly synced: number;
+  readonly syncing: number;
+  readonly attention: number;
+}`
+
+`query({ revision, locale, signal, page, pageSize, query })` returns a promise for
+`{ rows, total, summary }`; each row is `{ key, order, value: KnowledgeSource }`.
+The revision is a nonempty string or finite number. Counts/orders are safe nonnegative integers,
+`key === value.id` is nonblank, and keys/orders are unique within a page. Rows must exactly fill
+the requested in-bounds page, including its short final page; rejected or duplicate records fail
+the response rather than being omitted. `order` is stable canonical source order, independent
+of query sorting. The shared page-source contract also requires `lookup(keys, context)` and
+`locate(key, query, context)`; this component uses only `query` and exposes no selection/lookup UI.
+Query ordering describes the complete inventory; the component does not sort or filter an
+accepted page locally.
+
+The required summary describes the complete inventory on every page, even with `withoutSummary`.
+`summary.total` must equal the response `total`; every count is at most total, and
+`synced + syncing <= total`. Attention counts each source with sync status `'error'` or indexing
+health `'degraded'`/`'failed'`, and may overlap synced or syncing. For example, total 10, synced 8,
+syncing 2 and attention 4 is valid. Loaded-page category counts cannot exceed the corresponding
+global counts. Empty total requires all counts zero. Missing, malformed or inconsistent summaries
+fail visibly; page rows never supply a substitute global summary. These checks detect local
+contradictions but cannot verify unseen provider records.
+
+Only the current page, at most 500 projected rows, is retained; historic pages and the complete
+inventory are not cached. There is one physical page request plus the latest queued intent;
+an aborted provider call keeps its permit until it settles, including when it ignores abort.
+Providers should settle promptly after cancellation. The fixed display fields are `id`, `name`,
+`type`, `syncStatus`, `indexingHealth`, `permission`, `documentCount`, `lastSyncedAt` and
+`errorMessage`, read as own data properties without enumerating extra fields. Accessor-backed,
+oversized or invalid required fields fail the page. Their text shares a 65,536 UTF-16-unit budget
+per row; individual page metadata strings are at most 65,536 units and share a 2,000,000-unit
+page metadata budget. Source enums must match the declared unions and optional `documentCount`
+must be a safe nonnegative integer. Blank string names retain the untitled-source presentation;
+invalid string dates retain “never synced”, while valid Date values are copied into owned dates.
+
+The source-only sortable headers are `name`, `sync`, `health` and `permission`; `actions` stays
+unsortable. Query sort state starts at `{ sortKey: null, sortDir: 'asc' }`. The table's original
+cancelable `lr-sort-request { phase: 'request', sortKey, sortDir }` and accepted
+`lr-sort { phase: 'commit', sortKey, sortDir }` bubble once with their frozen readonly detail.
+A veto prevents a query change. Only a current accepted commit updates the global server order
+and resets page zero; synchronous source/page replacement prevents an obsolete commit from
+changing the replacement view. These headers remain unsortable in the legacy route.
+
+Pending and failed pages clear accepted rows/counts and show localized `source-status`, including
+with `withoutSummary`; they do not paint invented zeros, stale stats or successful-empty copy.
+A successful empty result keeps the toolbar and existing empty state. Current page failures use
+the nested table's error/retry surface; `error`, `errorHeading`, `errorDescription` and the `error`
+slot keep their existing precedence. The canonical cancelable `lr-retry-request` is proposed once;
+a veto prevents both refresh and error clearing. An accepted current provider-failure retry clears
+the host error and retries that page; an external-error-only retry just clears the host error.
+Retained old retry controls cannot refresh a replacement source. Initial failure is quiet;
+later page failures have one localized light-DOM announcement owned by the table.
+
+Open row menus belong to the particular admitted row and current page. Page/sort/revision/source
+replacement, refresh, disconnect and adoption close/release them; retained callbacks cannot act
+on a replacement record that happens to reuse the same ID. Existing sync/pause/delete requests
+retain original source IDs and remain host-owned actions. Create remains independent of a loaded
+row and available unless `withoutCreate` is set. Reassign even the same provider,
+or call a keyless `requestUpdate()`, after revision/state changes. Ordinary named presentation
+updates reuse admitted data unless revision or effective locale has changed. Reconnect requests
+the current source anew; obsolete replies and controls cannot publish rows or actions.
+
+The following array normalization and unknown-enum fallback rules apply with `dataSource` unset;
+row presentation, action enablement and host error contracts apply to both routes.
+
 **Properties:**
 
-- `sources: KnowledgeSource[] = []` (attribute: false) — `KnowledgeSource { id: string; name: string;
+- `sources: readonly KnowledgeSource[] = []` (attribute: false) — `KnowledgeSource { id: string; name: string;
 type?: string; syncStatus: KnowledgeSourceSyncStatus; indexingHealth?: KnowledgeSourceIndexingHealth;
 permission?: KnowledgeSourcePermission; documentCount?: number; lastSyncedAt?: Date | string;
 errorMessage?: string }` (all four types exported here), where
@@ -33,7 +137,8 @@ errorMessage?: string }` (all four types exported here), where
   as `'unknown'`), and `KnowledgeSourcePermission = 'owner' | 'editor' | 'viewer' | 'restricted'`.
   `type` is a free-form connector kind (`'drive'`, `'notion'`, `'upload'`, `'url'`, …) rendered
   as-is. `lastSyncedAt` follows this library's `Date | string` timestamp convention (a `Date` or an
-  ISO-8601 string); absent/unparseable renders "never synced". A `syncStatus`, `indexingHealth` or
+  ISO-8601 string); absent/unparseable renders "never synced". With `dataSource` unset, a
+  `syncStatus`, `indexingHealth` or
   `permission` outside these unions renders a neutral localized "Unknown" badge, offers no "Sync now",
   and is left out of the synced/syncing/needs-attention counts. `errorMessage` shows only while
   `syncStatus === 'error'`. `id`/`name` follow `DocumentRef`'s spirit, but a source is a _connector
@@ -55,8 +160,8 @@ errorMessage?: string }` (all four types exported here), where
 - `errorDescription: string = ''` (attribute `error-description`) — failed-load supporting copy,
   forwarded to the nested table
 
-Source ids must be nonblank and unique. Malformed rows and later duplicates are omitted first-wins
-before summary totals, empty state, table rows, or source actions. A retained source whose `name` is
+With `dataSource` unset, source ids must be nonblank and unique. Malformed rows and later duplicates
+are omitted first-wins before summary totals, empty state, table rows, or source actions. A retained source whose `name` is
 missing, blank, or nonstring uses the localized “untitled source” label in both the row and its action
 names. Row action triggers stay mounted; their three menu items mount only while the dropdown is
 open and clear after it closes.
@@ -70,15 +175,22 @@ re-emitted them under the `lr-source-*` names, so a host listening on the admin
 change; a host listening directly on `<lr-knowledge-base>` renames its four listeners.
 `lr-retry-request` (`detail: null`, cancelable) proposes a retry when the nested table's built-in
 retry button is activated. Preventing it keeps both the parent and table in the error state.
-Without a veto, the default action clears `error`. This component contains the nested table request
-and re-proposes its own canonical request, so hosts receive the parent event once.
+Without a veto, the default action clears `error` and, for a current provider failure, retries its
+page. This component contains the nested table request and re-proposes its own canonical request,
+so hosts receive the parent event once.
+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.
 
 **Slots:** `error` — replaces the nested table's built-in failed-load state, including its retry
-button, while `error` is set.
+button, while the host error or a current provider failure is shown.
 
 **CSS parts:** `base`, `toolbar` (heading + "Add source" row), `heading` (the heading text),
 `create-button` (omitted while `without-create` is set), `summary` (omitted while `without-summary`
-is set or `sources` is empty), `summary-stat`, `table`, `name-cell`, `source-name`, `source-type` (omitted when `type` is
+is set or the accepted current collection is empty; provider pending/failure uses `source-status`),
+`summary-stat`, `source-status` (localized provider loading/failed-summary status), `table`, `name-cell`, `source-name`, `source-type` (omitted when `type` is
 unset), `sync-cell`, `sync-badge`, `sync-timestamp`, `sync-error`, `health-cell`, `health-badge`,
 `document-count` (omitted when unset), `permission-badge` (omitted when `permission` is unset),
 `actions-menu`, `actions-trigger` (the kebab `<button>`), `error-row`, `error-cell`, `error` (the

package/llms/components/lr-knowledge-graph-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** `d3-drag`, `d3-force`, `d3-selection`, `d3-zoom` — see `llms/peers.md`
-- **Themeable via** 15 parts, 1 custom property — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 19 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`
 
 ---
@@ -28,6 +28,10 @@ focus and details flow as other entity activations, emitting one `lr-selection-c
 `lr-relation-activate` continues to pass through unchanged. The canonical search event fields remain
 `query`, `matchCount`, `matchCountExact`, and `activeIndex: -1`.
 
+With `graphSource` unset, the `input-limit` part preserves the outer `nodes` and `edges` admission counts before the
+bounded model is passed to the graph. Counts describe retained/source root entries, independently
+of filtering, search limits and child rendering.
+
 `view: LyraGraphView = '2d'` and `camera?: LyraGraphCamera` forward the graph's spatial/list
 options. `nodes[].position` supplies real x/y/z coordinates. The default remains the existing 2D
 view; spatial/list views need no d3 peer. Search, filtering, selection, pinning and neighborhood
@@ -37,6 +41,86 @@ popovers use `getNodeScreenPosition()` so their viewport anchor follows the proj
 orbit, pan, dolly or focus. Spatial node activation includes optional world `z`; it never substitutes
 screen pixels for the existing event's coordinate domain.
 
+**Complete graph provider:** `graphSource: KnowledgeGraphExplorerSource | undefined`
+(attribute: false) takes precedence over legacy `nodes`/`edges`; invalid defined providers fail
+visibly. Setting `undefined` restores the current legacy model and local search/details behavior.
+`KnowledgeGraphExplorerSource` is exactly the public `GraphSource` alias, forwarded unchanged to
+the existing single `lr-graph` child.
+
+```ts
+import type { KnowledgeGraphExplorerSource } from
+  "@aceshooting/lyra-ui/components/retrieval/knowledge-graph-explorer/knowledge-graph-explorer.class.js";
+import type { GraphSource } from
+  "@aceshooting/lyra-ui/components/retrieval/graph/graph.class.js";
+import type { LyraGraphSourceQuery, LyraGraphSourceSummary } from
+  "@aceshooting/lyra-ui/data-sources.js";
+```
+
+The child owns global record pages, accepted bounded diagram scenes, camera/focus and bounded
+exact selection lookup; the explorer adds no second source controller or loaded graph cache.
+The source has immutable `revision`, same-revision `records` with `query`/`lookup`/`locate`, required
+`scene(request)` and optional `overview(request)`. Record/scene summaries report complete
+`{ nodes, edges }` counts. Global record keys are `'node:' + node.id` and `'edge:' + edge.id`, with
+explicit stable edge IDs; user event payloads keep original entity/edge IDs. Full-source record
+navigation is separate from the bounded accepted canvas scene: a source does not imply every
+record is drawn simultaneously or that a global minimap is available. Source editing remains
+read-only; existing editing/drag mutation controls do not become provider write operations.
+
+`sourcePage: number = 0` (`source-page`) is the child's zero-based global record page;
+`sourcePageSize: number = 100` (`source-page-size`) normalizes to 1–500, and size changes reset page
+zero. Readonly `sourceTotal: number | null` is the exact active filtered node/edge record total,
+distinct from the complete graph summary. It is null without an accepted current total, without a
+source, or for an invalid type catalog. The child retains at most 500 page records, diagram scenes
+of at most 500 nodes/1,000 edges, and at most 32 active/focused lookup reservations. Lookup for
+explorer selection shares that child lane rather than enumerating the graph. Source pagination,
+node/edge kind and incident/global navigation remain available in the child.
+
+The explorer toolbar is the sole search input in source mode; its legacy local match list is
+absent. `query` supplies global provider search, with at most 65,536 UTF-16 units forwarded.
+Toolbar query/type changes reset the child to global node scope rather than leaving an unrelated
+edge/incident filter active. `lr-search-change` waits for the latest user query's accepted exact
+source total, not a page-local count. It retains `{ query, matchCount, matchCountExact: true,
+activeIndex: -1 }`; empty query reports zero. Direct controlled query assignments remain silent.
+
+When `hiddenTypes` is nonempty, configured `nodeTypes` must describe the provider's complete type
+catalog, with at most 500 canonical nonblank IDs, each at most 65,536 UTF-16 units and together at
+most 2,000,000. The source query receives the positive complement of those IDs. With no hidden
+types, no positive filter applies and unknown provider types remain navigable. A partial catalog
+cannot represent a correct hidden-type complement. Hiding every configured type intentionally
+suppresses/revokes record, scene and neighbor requests and reports zero scoped matches; it never
+sends an empty positive array as a false claim that the entire graph is empty. The complete source
+summary stays distinct. `source-status` explains all-hidden/invalid catalog state and `source-clear`
+clears hidden types to restore the unfiltered scope. Existing `lr-hidden-types-change` reports
+user commits; controlled assignments remain silent.
+
+Controlled `selectedNodeId` resolves an off-scene original ID through exact lookup without moving
+the record page, opening details or emitting selection. Only a current authoritative global
+absence proof clears it silently. User entity activation resolves the exact original ID, updates
+selection and emits the existing `lr-selection-change` once, then requires an accepted scene and
+real mounted list-row or projected camera anchor before opening the details popover. Reentrant
+selection listeners can revoke that continuation. The details `lr-neighbor-list` binds its source
+only after actual opening and is synchronously unbound on close/source change; hidden closed
+details do not fetch neighbors. Unknown degree is omitted unless `entityDetails` supplies it,
+rather than inferred from the partial scene. Pins and `path` remain bounded host configuration;
+the explorer does not look up every configured ID or compute a full graph traversal.
+
+`revealSourceKey(key: string): Promise<boolean>` clears toolbar query/hidden types and delegates
+global node/edge reveal to the sole child, without selection or detail activation. Keys retain the
+canonical node/edge prefixes above. Missing, invalid, failed, obsolete, disconnected or unset-source
+requests resolve `false`. Off-page list entity activation likewise clears toolbar scope before
+its global focus/details flow. `fit`, `resetView` and `focusNode` retain the child's bounded current
+scene semantics; they do not promise a full-source canvas fit.
+
+Reassign even the same source, or call a keyless `requestUpdate()`, after revision/state changes.
+Named presentation changes reuse accepted data. Source replacement/removal and lifecycle
+transitions revoke obsolete controls, focus/selection continuations and popover/neighbor bindings.
+Changed scope invalidates obsolete child requests and controls. The child's fixed page/scene/lookup scheduling keeps ignored-abort
+physical calls occupied until settlement and coalesces newer intent. Existing original-ID
+activation/expansion/path/pin/camera/view events keep their payloads and ownership; there is no
+new source selection or editing event. `detail-neighbors` identifies the open-details neighborhood;
+existing graph/legend/details parts remain applicable. The following local-array lookup/search
+rules describe the legacy route unless a source qualification is stated.
+
 **Properties:** (host-supplied data, identity-normalized before rendering)
 
 - `nodes: LyraGraphNode[] = []`, `edges: LyraGraphEdge[] = []`, `nodeTypes: LyraNodeTypeStyle[] = []`,
@@ -56,10 +140,13 @@ screen pixels for the existing event's coordinate domain.
   `{ description?: string; properties?: Record<string, string | number>; degree?: number }`, keyed by
   node id. Merged onto the matching `LyraGraphNode` to build the entity shown in the details popover and
   neighbor rows. A node with no entry still renders: `degree` falls back to a live count derived from
-  `edges`, `description`/`properties` are omitted
+  `edges` in the legacy route; source mode leaves unknown degree omitted.
+  `description`/`properties` are omitted
 - `path: LyraPathElement[] = []` (attribute: false) — host-supplied path-finding _result_, rendered
   via `lr-path-strip` (`{ kind: 'node'; node: LyraEntity } | { kind: 'edge'; relation: string;
-directed?: boolean; reverse?: boolean }`). Empty renders no strip
+directed?: boolean; reverse?: boolean }`). Empty renders no strip. The child registers on the
+  first nonempty path; await `updateComplete` before accessing it. The `path` part shows localized
+  loading or error status while unavailable. Clearing and replacing the path retries a failed load.
 
 (self-managed but presettable/observable — this component toggles its own copy on interaction, the
 same self-toggle-then-emit contract `lr-graph-legend` uses, so every feature works with zero host wiring)
@@ -67,8 +154,10 @@ same self-toggle-then-emit contract `lr-graph-legend` uses, so every feature wor
 - `hiddenTypes: string[] = []` (attribute: false) — forwarded to both `lr-graph.hiddenTypes` and
   `lr-graph-legend.hiddenTypes`; hidden nodes are also excluded from explorer search results,
   neighbor rows, and activation
-- `selectedNodeId: string | null = null` (attribute `selected-node-id`) — drives the details popover
-  and `lr-graph.selectedNodeIds`; `null` shows no selection and keeps the popover closed
+- `selectedNodeId: string | null = null` (attribute `selected-node-id`) — drives
+  `lr-graph.selectedNodeIds`; legacy selection drives the details popover, while controlled source
+  selection resolves silently and user activation opens it. `null` shows no selection and keeps
+  the popover closed
 - `pinnedNodeIds: string[] = []` (attribute: false) — exactly two pinned nodes reveals the "Find
   path" action
 - `query: string = ''` — the filter applied to the visible node
@@ -107,7 +196,7 @@ same self-toggle-then-emit contract `lr-graph-legend` uses, so every feature wor
   `graphExplorerLabel`. A non-empty host `aria-label` makes the host the sole overall owner; an
   explicitly empty host label stays empty on the group
 
-**Methods:** `fit(options?: { padding?: number })` frames every visible node in the composed
+**Methods:** `fit(options?: { padding?: number })` frames every currently visible node in the composed
 graph (forwards to `lr-graph.fit()`); `resetView()` is `fit()` with the default padding, for a
 reset-view action; `focusNode(id, options?: { zoom? }): Promise<boolean>` centers a visible node
 without selecting it or opening the details popover (resolves `false` for an unknown or
@@ -136,8 +225,9 @@ filtered-out id). None change `selectedNodeId` or filters.
 - `lr-search-change` (`detail: { query: string; matchCount: number; matchCountExact: boolean }`) —
   the user typed in the toolbar's search box. `query` is the canonical `LyraSearchChangeDetail`
   field name. `matchCount` is the same live node-filter total the result list and its live-region
-  announcement already compute (`0` while the query is empty). `matchCountExact` is always `true` —
-  this component's node filter has no truncating ceiling, unlike a paginated text-search viewer.
+  announcement compute in the legacy route (`0` while the query is empty). In source mode the
+  event waits for the accepted global query total described above. `matchCountExact` is `true`
+  for emitted accepted results.
   `activeIndex` is `-1`: this is a live node filter with no search cursor. The component
   has already applied the query to its own `query` property before emitting, so reassigning
   it back is optional and a direct host assignment stays silent.
@@ -149,7 +239,7 @@ filtered-out id). None change `selectedNodeId` or filters.
 **Slots:** `details` — overrides the details popover's default content (an `lr-entity-card` with a
 nested `lr-neighbor-list` and a pin toggle) entirely, including the two additive slots below.
 Receives no data; an overriding consumer reads the selected entity from `selectedNodeId`/`nodes`
-itself. `detail-body` — additive content appended inside the default `lr-entity-card`'s body,
+in the legacy route, or resolves the controlled original ID from its own provider in source mode. `detail-body` — additive content appended inside the default `lr-entity-card`'s body,
 alongside its `lr-neighbor-list`; no effect while `details` is overridden. `detail-actions` —
 additive content appended into the default `lr-entity-card`'s `actions` slot, beside its built-in
 pin toggle; no effect while `details` is overridden.
@@ -159,9 +249,13 @@ pin toggle; no effect while `details` is overridden.
 composed `lr-graph-legend`), `search-results` (only while `query` is non-empty; at most 50 rows,
 one tab stop moved with ArrowUp/ArrowDown/Home/End, while the announced count covers every match),
 `search-result` (`role="listitem"` wrapping a `<button>`), `search-empty`, `search-limit` (a localized
-shown/total notice when more than 50 nodes match), `details-limit` (a localized shown/total notice when `entityDetails` is too large to keep), `pinned` (only while
+shown/total notice when more than 50 nodes match), `input-limit` (outer node/edge admission notice),
+`details-limit` (a localized shown/total notice when `entityDetails` is too large to keep), `pinned` (only while
 `pinnedNodeIds` is non-empty), `pinned-heading`, `graph` (the composed `lr-graph`), `path` (only
 while `path` is non-empty), `detail-popover`, `detail-card`.
+Source-mode parts: `source-status` (filter error or all-types-hidden feedback) and `source-clear`
+(the action that clears hidden types). `detail-neighbors` is the details neighborhood;
+its provider binding is active only while source-mode details are open.
 
 **Themeable custom properties:** `--lr-canvas-reserved-height` (default
 `var(--lr-size-24rem)`) sets the explorer's host block size and matches its pre-upgrade
@@ -197,6 +291,7 @@ the composed graph too. Retheme the composed graph through `lr-graph`'s own cust
 - Selecting a node any _other_ way (search result, neighbor row, path element, keyboard Enter/Space
   on a graph node — which dispatches no native `click`) has no rect to read, so it calls
   `lr-graph.focusNode(id)` and anchors at the graph element's own bounding-box center instead; no
-  continuous tracking applies on that path.
+  continuous tracking applies on that legacy path. Source activation instead waits for the
+  authoritative scene and real row/projected anchor described above.
 
 ---

package/llms/components/lr-lightbox.md

@@ -9,7 +9,7 @@
 - **Release history** [CHANGELOG.md](../../CHANGELOG.md); family-wide breaking-change summaries: [media](https://github.com/aceshooting/lyra-ui/blob/main/packages/lyra-ui/llms/media.md)
 - **Deprecations** none
 - **Optional peers** none
-- **Themeable via** 17 parts, 3 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 20 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`
 
 ---
@@ -34,8 +34,15 @@ A lightbox opened outside an existing native `dialog.showModal()` stays interact
   Assignment clones/freezes the records and inspects at most 10,000 candidates; malformed records
   are omitted and updates require a new collection assignment. `src` is passed to the embedded
   frame, which runs it through `safeMediaSrc()`. `alt`/`caption` are caller data, never localized.
+- `imageSource: LyraLightboxSource | undefined` (attribute: false) — identity-owned
+  access to the complete ordered collection, taking precedence over `images` while defined.
+  Invalid defined sources show a localized error and retry action; they never fall back to the
+  legacy array. Setting `undefined` restores the current `images` input. Reassign the source,
+  including the same object, or call a keyless `requestUpdate()` after changing its revision or
+  mutable provider state. Unrelated named display updates do not refresh the source.
 - `index: number = 0` (reflected) — clamped defensively for rendering and re-synced (emitting
-  `lr-index-change`) when `images` shrinks.
+  `lr-index-change`) when the active collection shrinks. In source mode, it retains the requested
+  logical index while its descriptor and image load.
 - `loop: boolean = false` (reflected) — wraps prev/next past the ends.
 - `lightDismiss: boolean = false` (attribute `light-dismiss`) — opt in to backdrop dismissal. Off by default, matching `lr-dialog`.
 - `withoutCounter: boolean = false` (attribute `without-counter`, **not reflected**) — hides the
@@ -63,9 +70,36 @@ A lightbox opened outside an existing native `dialog.showModal()` stays interact
 without changing state. `goTo()` ignores a non-finite
 index without changing state or emitting `lr-index-change`. A finite fractional index is truncated
 toward zero before clamping or loop wrapping, so `lr-index-change.detail.index` is always the
-actual rendered integer index; `reason` defaults to `'api'` and is forwarded as the close event's
+accepted logical integer index, including while a source image is loading; `reason` defaults to
+`'api'` and is forwarded as the close event's
 detail.
 
+**Full image collections:** `LyraLightboxSource` has `revision` and
+`images: LyraIndexedView<LyraSourceRecord<LyraLightboxImage>>`, using the types from
+`@aceshooting/lyra-ui/data-sources.js`. The host supplies a nonnegative safe-integer `images.count`
+and either synchronous indexed access or asynchronous bounded range reads. Each record supplies
+a stable global `key`, canonical nonnegative safe-integer `order`, and image `value`. Keep the view
+stable within a revision; publish a new revision and refresh when its contents change. Navigation,
+clamping, looping and the localized counter use the full logical count, so first, middle and final
+images remain reachable in a million-image host collection without copying it into `images`.
+Current navigation emits `lr-index-change` for the logical destination before its image finishes
+loading; direct consumer `index` writes stay event-silent. Source mode adds no new event.
+
+Only the current image loads, after resolving its descriptor. The component retains at most three
+descriptors in one-record pages, with one range read physically pending and no neighbour prefetch.
+Supplied record and image fields must be own data properties; accessors are rejected without
+invocation. Each key, `src`, `alt` and `caption` admits at most 65,536 UTF-16 units; oversized or
+malformed values fail visibly instead of being clipped. URLs pass `safeMediaSrc()` before loading.
+The host owns provider storage and response allocations; actual image decode/pixel memory belongs
+to the browser and is not bounded by the descriptor cache.
+
+Source loading clears the old image/caption, marks the stage busy and leaves logical navigation
+available. Descriptor or image-load failure shows localized retry chrome; a valid empty collection
+is a separate state. Replacing a source, navigating, refreshing, disconnecting or changing owner
+document revokes obsolete work, so a late completion cannot display an old image. The same
+pan/zoom frame stays mounted and retains focus. The provider should honor the request's abort
+signal; stale-result protection does not make an abort-ignoring provider settle promptly.
+
 **Events:** cancelable `lr-show`, followed after a successful open render by `lr-after-show`;
 conditionally cancelable `lr-hide` (`detail: LyraLightboxHideDetail = { source: Element }`):
 cancelable before a requested close, non-cancelable when an open instance unmounts. A requested
@@ -76,7 +110,7 @@ object. Use
 `lr-after-hide` follows the closed render. Removal while open cannot be vetoed and reports reason
 `unmount`. `lr-index-change` (`detail: { index }`, fired
 for internally-driven navigation — a button, a keyboard shortcut, or `next()`/`previous()`/
-`goTo()` — and when a shrinking `images` moves the shown image; **not** when a consumer sets
+`goTo()` — and when a shrinking active collection normalizes the index; **not** when a consumer sets
 `index` directly); `lr-zoom-change` (`detail: {
 zoom }`) is not emitted by the lightbox itself — it bubbles up composed from the embedded frame.
 
@@ -93,7 +127,9 @@ including a consumer-driven one, appends the localized position to the document'
 embedded `<lr-pan-zoom>`), forwarded aliases `frame-viewport`, `frame-content`, `frame-controls`,
 `previous-button`,
 `previous-glyph`, `next-button`, `next-glyph`, `caption` (only when the current image has one; its
-`id` is the panel's `aria-describedby` target).
+`id` is the panel's `aria-describedby` target), `source-loading`, `source-error`, and `source-retry`
+(the current source image's retry button). `stage` exposes `aria-busy="true"` while source
+descriptor or native image loading is pending.
 
 **Themeable custom properties:** `--lr-lightbox-overlay-color` (default
 `var(--lr-color-overlay-strong)` — the backdrop scrim), `--lr-lightbox-control-bg` (default
@@ -118,6 +154,6 @@ photo content.
   measured by the lightbox, so stale load events cannot apply a previous image's size. The fit
   policy covers the painted image only; the lightbox's DOM caption, toolbar, legend-like actions,
   and tooltip content remain outside that image surface.
-- scope for v1: no per-image slotted content (data-driven via `images` only), no dot indicators, no
+- scope for v1: no per-image slotted content (data-driven via `images` or `imageSource`), no dot indicators, no
   visual open/close animation, no click-image-to-navigate, no touch-swipe. Lifecycle phases are
   still observable through the before/after events and methods above.

package/llms/components/lr-line-chart.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
 - **Documented with** `lr-bar-chart`, `lr-pie-chart`, `lr-doughnut-chart`, `lr-radar-chart`, `lr-polar-area-chart`, `lr-bubble-chart`, `lr-scatter-chart` (same section below)
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
 
@@ -28,6 +28,19 @@ types leave it inert; changing `type` or raw `config` to an admitted vertical ca
 configuration enables participation regardless of the tag. Horizontal or continuous-x
 configurations remain outside synchronization.
 
+`preparedData: LyraChartPreparedData | null = null` is inherited as a property-only input. Its
+compatibility follows the effective writable type: ordered series for `line`/`bar`, categories for
+`bar`/`pie`/`doughnut`/`radar`/`polarArea`, and `LyraSpatialChartSource` (`kind: 'spatial'`)
+for `scatter`/`bubble` with linear scales. Changing `type`
+can therefore make a previously admitted descriptor incompatible; it does not convert the
+descriptor. Whole-source counts/domains, aggregate gap/overlay/table admission, explicit exact
+point reveal, bounded displayed CSV export and refresh/unset behavior follow the core contract.
+Series/category zoom stays summary-only; spatial zoom updates and queries its explicit viewport.
+The spatial contract includes complete all-series density, bounded representatives plus independent
+selected/revealed exact overlays, semantic radius/original coordinates, and the spatial event/table/CSV
+routes described above. Scatter/bubble typed class entries re-export spatial source/point/series,
+viewport and immutable spatial event-detail types; import them from their granular class routes.
+
 Everything else is inherited verbatim from `lr-chart`; each name below has the same type, default,
 and behavior there. **See `llms/components/lr-chart.md` for the details, code example, and gotchas
 of every entry in these lists.**
@@ -38,19 +51,29 @@ of every entry in these lists.**
 `stacked`, `stackedAxes`, `withoutAnimation` (`without-animation`),
 `withoutLegend` (`without-legend`), `withoutTooltip` (`without-tooltip`), `xLabel` (`x-label`),
 `yLabel` (`y-label`), plus additive `labels`, `datasets`, `valueFormatter`, `formatter`,
-`tooltipTitleFormatter`, `tooltipFooterFormatter`, `area`, `zoomable`,
+`tooltipTitleFormatter`, `tooltipFooterFormatter`, `area`, `zoomable`, `preparedData`,
+`viewport` (property only, default null), `selectedPointId` (property only, default ''),
 `height`, `y2Label` (`y2-label`), `withoutZeroBaseline` (`without-zero-baseline`), `dataLabels`
 (`data-labels`), `stackTotals` (`stack-totals`), `config`, `withDataTable`
-(`with-data-table`), `dataTableToggle` (`data-table-toggle`), `chartArea` (readonly), and `chart`.
+(`with-data-table`), `dataTableToggle` (`data-table-toggle`), `maxRecords` (`max-records`, default
+`1000`, range 2–1,000), `chartArea` (readonly), and `chart`.
 `type` differs only in its initial value.
 
 **Methods:** `appendData(label, values, maxPoints?)`, `exportData('csv' | 'png')`, `renderChart()`, `resetZoom()`,
-`refreshTheme()`.
+`refreshTheme()`, `revealSourcePoint(ref: LyraSeriesPointRef): Promise<boolean>` and
+`revealSourcePoint(id: string): Promise<boolean>` (spatial only).
 
 **Events:** `lr-zoom` (`detail: { zoomed: boolean }`), `lr-datum-activate`, `lr-point-activate` (`detail: { datasetIndex,
 index, label, value }`), `lr-legend-visibility-change-request` (cancelable), and
 `lr-legend-visibility-change` (commit; both legend events carry `datasetIndex`, `visible`, and the
 complete `hiddenDatasets` snapshot).
+Prepared activation additionally emits `lr-source-point-select` or `lr-source-category-select`
+with the core chart's immutable original-reference details. Spatial activation uses
+`lr-spatial-point-select`/`lr-spatial-bin-select` with the exact core source semantics;
+existing activation events retain
+plotted indices. The typed component entries re-export `LyraChartPreparedData`,
+`LyraChartSourcePointSelectDetail`, `LyraChartSourceCategorySelectDetail`, `LyraPreparedSeriesData`,
+`LyraPreparedCategoryData` and `LyraSeriesPointRef`.
 Radial category legends additionally emit `lr-datum-visibility-change-request` (cancelable) and
 `lr-datum-visibility-change`, carrying `index`, `visible` and the frozen `hiddenDatums` snapshot.
 
@@ -60,7 +83,7 @@ Radial category legends additionally emit `lr-datum-visibility-change-request` (
 **CSS parts:** `base`, `plot`, `canvas`, `legend`, `legend-item`, `legend-item-hidden`, `legend-swatch`,
 `sync-crosshair` (inherited decorative category line, rendered only for an admitted synchronized
 configuration; 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 — see
 `llms/components/lr-chart.md`).