@aceshooting/lyra-ui 29.0.2 → 29.1.0

package/llms/components/lr-task-list.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** 12 parts, 14 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 18 parts, 14 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,11 +19,87 @@
 A live, collapsible tracker for an agent's plan: ordered steps with per-step lifecycle status and one
 level of nested sub-steps, embedded in the transcript. `items` is controlled and never mutated by this
 component. Unlike `<lr-stepper>`'s single-`current` navigation, task-list has no selection and
-several steps may be `running` at once. By default it is a status report; `reorderable` adds
-controlled keyboard reorder requests without changing ownership of `items`. Status changes and
-confirmed moves are announced through an internal `<lr-live-region>`.
-The list renders at most 500 tasks across top-level rows and direct children; `[part="limit"]`
-explains when more were supplied. The summary still counts every top-level task.
+several steps may be `running` at once. By default it is a status report; with `treeSource` unset,
+`reorderable` adds controlled keyboard reorder requests without changing ownership of `items`.
+Legacy status changes and confirmed moves are announced through an internal `<lr-live-region>`.
+
+**Complete source tasks:** `treeSource: TaskListSource | undefined`
+(attribute: false) takes precedence over `items`; invalid defined sources fail visibly without
+falling back to the array. Only `undefined` restores current legacy items.
+
+```ts
+import "@aceshooting/lyra-ui/components/lr-task-list.js";
+import type { TaskListSource, TaskItem, TaskStatus } from
+  "@aceshooting/lyra-ui/components/agent-tools/task-list/task-list.class.js";
+import type { LyraHierarchySource, LyraHierarchyQuery, LyraTaskSourceSummary } from
+  "@aceshooting/lyra-ui/data-sources.js";
+```
+
+`TaskListSource = LyraHierarchySource<TaskItem, LyraHierarchyQuery, LyraTaskSourceSummary>`.
+The exact shared hierarchy/request/row protocols and
+`LyraTaskSourceSummary` declaration are in [shared source contracts](../shared/events-and-types.md).
+The required summary has readonly `total` and `completed` safe nonnegative integers with
+`completed <= total <= projection.total`. Its counts describe all top-level tasks, independently
+of the current visible preorder and mounted rows. `projection.total` counts all logical tasks,
+including collapsed children; `projection.rows.count` counts the complete currently visible
+preorder and cannot exceed that total. The header uses the provider's summary, never counts
+from a loaded window; unavailable summaries do not paint a fabricated 0-of-0 header.
+
+The provider implements `project({ revision, locale, signal, query, state, action })`; query stays
+`{ search: '', hiddenKinds: [] }`. Revision is a nonempty string or finite number. Each immutable
+projection supplies a nonempty `state` token of at most 65,536 UTF-16 units,
+`total`, `rows`, required `summary` and optional `focusIndex`. Rows use either indexed
+`count`/`itemAt`/`keyAt`/`indexOfKey`, or ranged `count`/`read`/`indexOfKey`; ranged reads return
+exactly the requested in-bounds range. Keys resolve directly without a full-source scan.
+Provider preorder, parent keys, one-based `level`/`position`/`setSize`, `childCount`, `expanded`,
+`selected`, optional `disabled` and `selectionState` own topology and semantic metadata.
+Task rows must be level 1 with null parent, or level 2 with a nonempty parent and no children;
+deeper source rows fail visibly. The component never traverses `value.children` or opaque task
+metadata, and `row.key` must equal the nonblank `value.id`.
+
+Source values copy only own data fields `id`, `label`, `status` and optional `detail`.
+Accessor-backed fields reject; nonstring label/detail normalize to empty text and unknown status
+to `'pending'`. A normalized row's key, parent key, id, label and detail share a 65,536 UTF-16-unit
+budget. Retained rows, focused reserve and pending admission share a 2,000,000-unit payload
+ceiling. Four 100-row pages retain at most 400 rows plus one focused row; at most 301 rows mount,
+with at most two physical range reads. Projection work permits one physical call and only the
+latest queued intent; ignored aborts keep their physical permits until settlement. Provider
+storage and indexing remain caller-owned.
+
+The virtualized tree navigates the complete visible preorder, with global Home/End, Up/Down,
+RTL-aware expansion/parent keys and disabled-row handling. `revealSourceKey(key: string):
+Promise<boolean>` requests a provider reveal and focuses its returned `focusIndex`; it resolves
+false when no source is set, the key is invalid/absent/disabled, focus cannot be transferred, or
+the operation is obsolete. Reveal, refresh and row focus emit no task action or selection event.
+Row activation does not request provider selection. Provider expansion controls remain available,
+but emit no new task toggle event; the existing `lr-toggle-request`/`lr-toggle` pair controls only
+the outer panel. `reorderable` and `maxNodes` govern legacy items; source mode disables reorder,
+clears pending moves and never replays historical per-item status changes as fresh announcements.
+
+`heading`, `headingLevel`, `frame`, `size` and panel collapse remain local presentation. The
+header's existing cancelable toggle proposal/veto behavior remains; a superseded proposal cannot
+change a replacement view. Source rows retain status icons, text/detail and `detail-<id>` slots.
+Their native treeitem accessible names derive from the rendered status, label, detail and rich
+slot content, each once; the focus owner is `source-row`, rather than a legacy reorder row.
+Source parts are `source-list`, `source-row`, `source-label`, `source-toggle`, `source-status` and
+`source-error`. Localized loading, complete visible/logical counts, empty, projection failure and
+per-row retry states stay distinct. Initial status is quiet; later current source status/failure
+changes use light-DOM announcements without historical task-status replay.
+
+Reassign even the same source or call a keyless `requestUpdate()` after revision/state changes.
+Named presentation paints reuse accepted data unless revision or effective locale changes.
+Source/revision replacement, reveal/expansion supersession, disconnect and adoption revoke old
+rows, callbacks and effects; reconnect requests the current source. Retained controls cannot act
+on a replacement row that reuses the same key. Provider results and displayed records must remain
+immutable for their captured revision.
+
+**Legacy array admission:** with `treeSource` unset, the list renders at most `maxNodes` tasks
+(default 500) across top-level rows and direct children;
+`[part="limit"]` explains when source admission or rendering omits tasks. The summary counts every
+valid admitted top-level task. Initial limit notices are silent; a later transition into truncation is announced politely.
+Assignment examines the first 10,000 outer entries; direct-child arrays share a separate 10,000-position
+budget. Display fields are copied without invoking accessors or traversing opaque metadata. Reassign
+a new array after changing task data; unrelated updates and reconnects retain the assigned snapshot.
 
 **Properties:** `items: readonly TaskItem[] = []` (attribute: false) — `TaskItem { id: string; label: string;
 status: TaskStatus; detail?: string; children?: readonly TaskItem[] }` with `TaskStatus = 'pending' |
@@ -35,6 +111,8 @@ line; `children` is exactly **one** level of sub-steps — a child's own `childr
 rendering, summaries, announcements, and reorder validation. While `reorderable`, every retained
 top-level task and direct child must additionally have a globally unique `id`; duplicate data stays
 visible but fails closed, with no row keyboard stops or reorder requests.
+`maxNodes: number = 500` (attribute `max-nodes`) sets the rendered parent-plus-child budget,
+normalized to `1..5000`; unset or non-finite values restore 500.
 `reorderable: boolean = false` (reflected) enables Ctrl/Cmd+ArrowUp/ArrowDown on a focused task.
 It emits a request only; the host must assign a new reordered `items` array before the task visibly
 moves or an announcement is made. `heading?: string` — the visible section title; omission
@@ -62,7 +140,8 @@ that item's label, typically a `<lr-tool-call-chip>` or file `<lr-chip>`.
 **Events:** cancelable `lr-toggle-request` (`detail: { expanded }`, the requested state), `lr-toggle` — the header was activated, expanding or collapsing the panel. `detail: {
 expanded }`. `lr-reorder` — Ctrl/Cmd+ArrowUp/ArrowDown requests moving the focused task within its
 own sibling list. `detail: { taskId, parentTaskId, fromIndex, toIndex }`; `parentTaskId` is `null`
-for a top-level task and indices are sibling-scoped. It fires only while `reorderable` with unique,
+for a top-level task and indices are sibling-scoped. It fires only with `treeSource` unset while
+`reorderable` with unique,
 nonempty ids.
 A boundary key is a silent no-op, so it never reparents a child; the component announces success only
 after the host's rendered array confirms the exact requested swap.
@@ -73,11 +152,16 @@ after the host's rendered array confirms the exact requested swap.
 otherwise, within the configured semantic heading), `label` (the `heading` text),
 `summary` (the visible "N of M completed" summary, top-level items only), `toggle` (the chevron
 indicator, not rendered while `without-collapse`), `body` (the list of items, `hidden` while collapsed),
-`item` (`role="listitem"`; carries `data-status`/`data-id`/`data-depth` and is focusable only for
+`item` (legacy `role="listitem"`; carries `data-status`/`data-id`/`data-depth` and is focusable only for
 valid `reorderable` data), `status-icon`, `item-label`, `item-detail`, `limit` (shown when the task
-render cap is exceeded), and `item-children` (the
+source or render cap is exceeded), and `item-children` (the
 nested `role="list"` wrapper around a top-level item's children).
 
+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).
+
 **Themeable custom properties:** `--lr-task-list-spin` (default `var(--lr-transition-ambient)`, i.e.
 `1.8s ease-in-out`, collapsing to `0.001ms linear` under `prefers-reduced-motion`) — running-status
 icon spin animation duration/timing; `--lr-task-list-compact-header-padding` (default

package/llms/components/lr-terminal.md

@@ -22,6 +22,14 @@ characters; an overlong unterminated CSI/OSC sequence is dropped and the next wr
 clean parser boundary. Carriage return and erase-in-line (`CSI K`, `0K`, `1K`, `2K`) support
 in-place progress updates; other cursor-addressing sequences remain unsupported.
 
+The buffer retains at most 2,000,000 UTF-16 text units and 10,000 lines, subject to
+`max-scrollback`. Each `write()` or content commit accepts at most 1,000,000 UTF-16 units; each
+line accepts at most 20,000 scalar columns. When a commit loses data, `lr-overflow` carries
+`LyraTerminalOverflowDetail { truncated: true; inputCharactersDropped: number;
+lineCharactersDropped: number; linesDropped: number }`. Character counts use UTF-16 units;
+`linesDropped` includes scrollback and resource-limit pruning. `write()` remains `void`. Supply
+bounded chunks and consume this event when complete capture matters.
+
 Direction: every line is left-to-right. With `without-wrap`, the scrollport is laid out left-to-right as well, so a long line scrolls from its start and, under `dir="rtl"`, the vertical scrollbar sits on the physical right; the toolbar and jump-to-latest control still follow the page direction. By default (lines soft-wrap), the scrollport follows the page direction.
 
 A search with no matches clears earlier rendered match markers. Removing the `content` attribute
@@ -70,6 +78,7 @@ plain text of the whole buffer.
 default the component creates a plain-text `Blob`/object URL and activates a synthetic
 `<a download>`; `preventDefault()` suppresses that built-in download so the host can substitute
 server-side or other handling),
+`lr-overflow` (`detail: LyraTerminalOverflowDetail`, a write or content commit lost data),
 `lr-follow-change` (`detail: { following }`), `lr-search-change` (`detail: { query, matchCount,
 matchCountExact, activeIndex }`; `matchCountExact` is `false` once a search hits the 10,000-match
 ceiling, marking `matchCount` as a lower bound rather than an exact total),

package/llms/components/lr-test-results.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** 16 parts, 8 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 20 parts, 8 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,6 +22,72 @@ alongside the plain failure message.
 
 Direction: a failure message (`::part(failure-message)`) uses `unicode-bidi: plaintext`, so each line takes the direction of its own first strong character — assertion text reads left-to-right and a translated message right-to-left. WebKit resolves this once per block from its first strong character rather than per line.
 
+**Full-source paging:** `dataSource: TestResultsSource | undefined` (attribute:
+false) takes display precedence over `suites`; invalid defined providers fail visibly.
+Setting `undefined` restores the current legacy suites. `sourcePage: number = 0` (`source-page`)
+is zero-based; `sourcePageSize: number = 100` (`source-page-size`) normalizes to 1–500.
+Readonly `sourceTotal: number | null` is the exact filtered record count after success, and `null`
+while unavailable or without a source. Filter/page-size changes reset page zero; an out-of-range
+page receives at most one corrective last-page request.
+
+```ts
+import type {
+  TestResultsSource, TestResultsSourceQuery, TestResultsSourceRow, TestResultsSourceSummary,
+} from "@aceshooting/lyra-ui/components/agent-tools/test-results/test-results.class.js";
+import type { LyraPageSource, LyraPageResult, LyraSourceRecord } from
+  "@aceshooting/lyra-ui/data-sources.js";
+```
+
+`TestResultsSource` is `LyraPageSource<TestResultsSourceRow, TestResultsSourceQuery,
+TestResultsSourceSummary>`. The provider has immutable `revision` (nonempty string or finite
+number), `query({ revision, locale, signal, page, pageSize, query })`, `lookup(keys, context)` and
+`locate(key, query, context)`. Ordinary paging uses only `query`; it does not lookup or locate
+records. Query contains `{ statuses: readonly TestStatus[] }`, empty for all statuses, and returns
+`{ rows, total, summary }`. Each row is `{ key, order, value: { suiteId, suiteName, test } }`, with
+`key === JSON.stringify([suiteId, test.id])`, nonblank original suite/test IDs and safe canonical
+`order`. Page keys/orders are unique; the response must contain exactly the requested in-bounds
+records. The provider applies filtering to the complete logical result set before paging.
+
+Required `TestResultsSourceSummary` is `{ total, passed, failed, skipped, running }` for the complete
+unfiltered run, regardless of the current page/filter. All counts are safe nonnegative integers
+and status counts sum to summary total. Page `total` equals the selected status counts' sum, or
+summary total for an empty filter. Admitted rows must match the filter and cannot exceed the full
+summary's per-status counts. Pending/error states show unknown counts, never a partial page count
+as a complete summary. Complete-source truth remains provider-owned beyond these consistency checks.
+
+At most 500 source records are admitted and mounted per page, with suite headings following
+provider order even when suites interleave. Closed own-data row fields exclude arbitrary provider
+output/attachments. `suiteId`, `suiteName`, test ID/name/message share a 65,536 UTF-16-unit bound;
+oversized or accessor-backed records reject atomically. Record keys are at most 65,536 units and
+share the page helper's 2,000,000-unit key budget. Source mode retains bounded page/in-progress
+results and current-page expansion rather than flattening the complete run. It does not run the
+legacy projection when filters change. Each page/lookup/locate lane allows one physical provider
+call plus only the latest queued intent; ignored aborts occupy their permit until settlement.
+
+Source name activation and toggle events preserve exact original `{ suiteId, testId }` values;
+the canonical JSON key is navigation identity rather than a replacement event ID. Existing
+suite-scoped detail slots and cancelable toggle-request contracts apply. Source expansion resets
+with the current page binding and remains separate from legacy manual expansion. Explicit
+`runState` completion waits for a current authoritative full summary; resuming the run, changing
+run/source or lifecycle revocation cancels obsolete deferred completion announcements.
+
+Reassign even the same source, or call a keyless `requestUpdate()`, after revision/state changes.
+Named presentation updates reuse accepted data; source/lifecycle/locale changes revoke obsolete
+requests, controls and announcements. Source-only parts are `source-status`, `source-retry` and
+`source-pagination`; existing summary/filter/test/detail parts remain applicable. A failed page
+has a localized retry and light-DOM announcement. The following `suites` behavior describes the
+legacy route.
+
+**Exported test-results source declarations:**
+
+These types use the existing `TestStatus` and `TestCaseResult` declarations.
+
+`TestResultsSourceQuery { readonly statuses: readonly TestStatus[]; }`
+
+`TestResultsSourceRow { readonly suiteId: string; readonly suiteName: string; readonly test: TestCaseResult; }`
+
+`TestResultsSourceSummary { readonly total: number; readonly passed: number; readonly failed: number; readonly skipped: number; readonly running: number; }`
+
 **Properties:** `suites: readonly TestSuiteResult[] = []` (attribute: false) — `TestSuiteResult { id: string;
 name: string; tests: readonly TestCaseResult[] }` and `TestCaseResult { id: string; name: string; status:
 TestStatus; durationMs?: number; message?: string }`, with `TestStatus = 'passed' | 'failed' |
@@ -37,7 +103,12 @@ first-wins identity. Foreign runtime statuses normalize
 once to the localized neutral `skipped` state, so every accepted row contributes to one coherent
 summary count and renders a label/glyph.
 
-Summary counts cover the complete normalized input. At most 1,000 rows mount for the active filter;
+Legacy normalization retains the complete canonical input once with O(n) rows/indexes, yielding
+after at most 500 combined suite/test positions. It normalizes status once per corpus; filtering
+may still traverse O(n) records. New input/source entry cancels older staged work, and
+`updateComplete` waits for the current normalization and render. Oversized aggregate row text or
+identity fails visibly with unknown counts in `input-error`; caller arrays and slotted DOM remain
+host-owned. Summary counts cover the complete normalized input. At most 1,000 rows mount for the active filter;
 manually expanded identities reserve positions first, failed rows next, then ordinary input-order
 rows. A localized `[part="limit"]` note exposes truncation without losing the complete counts.
 
@@ -69,7 +140,10 @@ adjacent localized status word carries the meaning. Running rows use the decorat
 **CSS parts:** `base`, `summary` (the status-count strip), `count` (carries `data-status`), `filter`,
 `filter-toggle` (carries `data-status`/`aria-pressed`), `suite`, `suite-header`, `test` (carries
 `data-status`), `test-status`, `test-name`, `test-duration`, `test-expand-toggle`, `failure`
-(hidden while collapsed), `failure-message`, `limit`, and `empty`.
+(hidden while collapsed), `failure-message`, `limit`, `input-error` (rejected legacy snapshot), and `empty`.
+
+With `dataSource` set, additional CSS parts are `source-status` (provider loading or failure text), `source-retry` (retry
+the current failed provider request), and `source-pagination` (provider page controls).
 
 **Themeable custom properties:** `--lr-test-results-filter-active-bg` (default
 `var(--lr-color-brand-quiet)`), `--lr-test-results-filter-active-border` (default

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

@@ -9,7 +9,7 @@
 - **Release history** [CHANGELOG.md](../../CHANGELOG.md); family-wide breaking-change summaries: [conversation](https://github.com/aceshooting/lyra-ui/blob/main/packages/lyra-ui/llms/conversation.md)
 - **Deprecations** none
 - **Optional peers** none
-- **Themeable via** 42 parts, 20 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 45 parts, 20 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`
 
 ---
@@ -26,6 +26,16 @@ row actions in that mode. No thread CRUD or persistence — every mutation
 (`lr-thread-pin`/`-archive`/`-delete`/`-rename`) is a controlled event carrying the _requested_ new
 state; the host mutates `threads`.
 
+With `dataSource` unset, `threads` retains the first 10,000 identities. Structural group headings do not consume that
+allowance; every admitted thread remains addressable through the internal virtual list.
+Use the full-source provider route below for larger sidebar collections.
+
+A localized `threadListInputLimit` notice in `part="limit"` discloses entries omitted from the
+original assignment. It describes input admission independently of search matches and the visible
+virtual window. Rebinding the retained snapshot preserves the notice; a fresh input below the
+limit clears it. Initial mounting and reconnecting are quiet; later changed input loss is
+politely announced.
+
 A conversation row with `slot=""` belongs to the default slot exactly like a row with no slot
 attribute, including after reconnect. Named slots retain their distinct roles.
 
@@ -36,6 +46,77 @@ focus. Home/End always resolve the first/last thread from that complete model, e
 starts in a middle window; group records, collapsed-group contents, and unavailable endpoint rows
 are skipped rather than becoming false boundaries.
 
+**Full-source paging:** `dataSource: ThreadListSource | undefined` (attribute:
+false) takes display precedence over `threads` and the default slot. An invalid defined provider
+fails visibly; setting `undefined` restores the current legacy data/slotted precedence.
+`sourcePage: number = 0` (`source-page`) is zero-based, and `sourcePageSize: number = 100`
+(`source-page-size`) normalizes to 1–500. Readonly `sourceTotal: number | null` is the exact global
+current-query record count before group collapse, or `null` before success and without a source.
+Query/page-size changes reset page zero; collapse changes preserve the current record page.
+An out-of-range page receives at most one corrective last-page request.
+
+```ts
+import type { ThreadListSource, ThreadListSourceQuery } from
+  "@aceshooting/lyra-ui/components/conversation/thread-list/thread-list.class.js";
+import type { LyraPageSource, LyraPageResult, LyraSourceRecord } from
+  "@aceshooting/lyra-ui/data-sources.js";
+```
+
+`ThreadListSource` is `LyraPageSource<LyraChatThread, ThreadListSourceQuery>`. The provider has an
+immutable `revision` (nonempty string or finite number), `query({ revision, locale, signal, page,
+pageSize, query })`, `lookup(keys, context)`, and `locate(key, query, context)`. Query returns
+`{ rows, total, groups? }`; records have `{ key, order, value }`, where `key === value.id`, `order`
+is a safe stable canonical source ordinal and `value` is a complete `LyraChatThread`. Counts are
+safe nonnegative integers; page keys/orders must be unique and the response must contain exactly
+the requested in-bounds row count. Lookup returns complete globally present requested records,
+omitting absent keys; locate returns the absolute current-query record index or `null`.
+
+The forwarded `ThreadListSourceQuery` contains `{ search, withArchived, grouping,
+collapsedGroupIds, filter, groupBy, getGroupLabel, groupOrder }`. The provider applies search,
+filtering, ordering and grouping globally before paging. Grouped responses require
+`groups: [{ key, label, startIndex, itemCount }]`: global nonoverlapping intervals covering the
+page, including the header of a group that began on an earlier page. At most 500 records plus
+500 structural headings are modeled. Collapsed rows retain their original record positions and
+actionable heading; collapse does not redefine the global total or page boundaries. Complete-group
+callbacks/adornments are not computed from partial pages. Row rendering hooks continue to receive
+the original provider record identity. Per-record display strings share a 65,536 UTF-16-unit bound;
+keys/group text are each at most 65,536 units and share a 2,000,000-unit admission budget.
+Malformed or oversized pages show a localized failure without clipping records.
+
+`activeConversationId` uses global `locate` once per active/query binding, then scrolls the bounded
+page's matching row into view. Manual paging preserves the controlled active ID without repeatedly
+jumping back; clearing/restoring that ID locates again. Arrow/Home/End navigation addresses the
+current page's virtual item model; global paging and active-ID lookup reach other logical pages.
+Source `lr-filter-change` reports the provider's full matching `total`, not the loaded row count.
+Existing controlled thread-action IDs and group-toggle/veto contracts remain unchanged.
+
+The provider remains host-owned by identity. Reassign even the same object, or call a keyless
+`requestUpdate()`, after revision/state changes. Named presentation changes reuse the accepted
+page. Replacement, refresh, disconnect and adoption revoke obsolete requests/actions/reveals.
+Each page/lookup/locate lane allows one physically unsettled provider call and only the latest
+queued intent; an ignored abort holds its physical permit until settlement. Only bounded current
+and in-progress pages are modeled, without a full-source search corpus or thread index. Provider
+storage/indexing and complete-source consistency remain host obligations.
+
+Loading uses `source-status`; `source-pagination` contains the global pager. Provider errors reuse
+the existing localized `error` surface/slot and cancelable `lr-retry-request`; its default retries
+the current provider page and clears the host error, while `preventDefault()` vetoes it. Existing
+row and group parts remain applicable. The following array admission and local grouping details
+apply with `dataSource` unset; row presentation/actions apply to provider rows as well.
+
+**Exported source query declaration:**
+
+`ThreadListSourceQuery {
+  readonly search: string;
+  readonly withArchived: boolean;
+  readonly grouping: ThreadListGrouping;
+  readonly collapsedGroupIds: readonly string[];
+  readonly filter: LyraThreadList['filter'];
+  readonly groupBy: LyraThreadList['groupBy'];
+  readonly getGroupLabel: LyraThreadList['getGroupLabel'];
+  readonly groupOrder: LyraThreadList['groupOrder'];
+}`
+
 **Exported types:** `LyraChatThread { id: string; title: string; excerpt?: string; timestamp?: Date |
 string | number; pinned?: boolean; archived?: boolean }`; `ThreadRowAction = 'pin' | 'archive' |
 'delete'`; `ThreadListGrouping = 'date' | 'custom' | 'none'`; `ThreadBucketKey = 'pinned' |
@@ -189,6 +270,7 @@ was activated, only rendered while `error` is set; the default action clears `er
 **CSS parts:** `base`, `search`/`search-input` (the search field wrapper and `<input
 type="search">`), `clear-button` (clears the search field; rendered only while it has a value,
 mirroring `<lr-input>`'s own `clearable` contract's part name), `list` (the list region), `empty`,
+`limit` (original thread input-loss notice),
 `error` (the built-in `<lr-empty>` host rendered while `error` is set, with `error-base`/
 `error-icon`/`error-heading`/`error-description`/`error-actions` exported from its own parts, plus
 `retry-button` for the built-in retry control), `viewport` (the actual internal virtual-list
@@ -206,6 +288,9 @@ their corresponding render-hook output; inherited fonts, layout values, and them
 reach callback-rendered descendants through these parts). `row-excerpt` wraps `renderExcerpt`
 output, which is slotted into the row item's own `excerpt` slot.
 
+With `dataSource` set, additional CSS parts are `source-status` (provider loading text) and `source-pagination` (the
+provider page-navigation host).
+
 Data mode additionally forwards each row `<lr-conversation-item>`'s own parts under a `row-item-`
 prefix: `row-item-base`, `row-item-base-menu-open`, `row-item-active-indicator`, `row-item-select-button`, `row-item-start`, `row-item-content`,
 `row-item-label`, `row-item-label-input`, `row-item-rename-button`, `row-item-excerpt`,

package/llms/components/lr-time-zone-picker.md

@@ -9,7 +9,7 @@
 - **Release history** [CHANGELOG.md](../../CHANGELOG.md)
 - **Deprecations** none
 - **Optional peers** none
-- **Themeable via** 11 parts, 0 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 13 parts, 0 custom properties — see this component's own `@csspart`/`@cssprop` list below
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
 
 ---
@@ -32,6 +32,11 @@ Selection does not change the application's time zone or calculate offsets, cloc
 saving transitions. Catalog types and `getTimeZoneCodes()` are documented in the
 [catalog helper reference](https://github.com/aceshooting/lyra-ui/blob/main/packages/lyra-ui/llms/forms.md#country-time-zone-and-unit-catalog-helpers).
 
+The shared `part="limit"` notice uses `catalogPickerInputLimit` for original input omitted beyond
+the 1,024-position catalog ceiling. It remains separate from popup row overflow. Snapshot rebinds,
+fresh replacement/default clearing, quiet mounting/reconnection, and later polite announcements
+follow the shared field contract.
+
 **Field API:** `label`, `hint`, `errorText` (`error-text`), `placeholder`, `accessibleLabel`
 (`aria-label`), `name`, `form`, `value`, `defaultValue`, `required`, `disabled`, `customError`
 (`custom-error`), `size`, `clearable`, `searchable`, `topLayer` (`top-layer`),
@@ -44,8 +49,8 @@ Defaults and form/editing methods follow the
 
 **Events:** `input`, `lr-input`, `change`, `lr-change`, `focus`, `blur`, `lr-invalid`.
 **Slots:** `label`, `hint`, `error`.
-**CSS parts:** `form-control`, `form-control-label`, `hint`, `error`, `select-trigger`,
-`select-display-input`, `select-listbox`, `select-option`, `select-option-sub`, `select-group-label`,
+**CSS parts:** `form-control`, `form-control-label`, `hint`, `error`, `limit`, `select-trigger`,
+`select-display-input`, `select-listbox`, `select-option`, `select-option-overflow`, `select-option-sub`, `select-group-label`,
 `select-clear-button`.
 
 ```html

package/llms/components/lr-timeline.md

@@ -26,6 +26,11 @@ item's `title`/`description` routinely hold focusable content, so wrapping the r
 would trip `nested-interactive`). The opt-in clustered time scale adds only native count-marker
 buttons; it does not make the individual rows interactive.
 
+Every assigned item remains mounted; the timeline does not window large collections. Flow mode
+leaves untouched items' positioning styles alone. Time mode reuses item geometry between targeted
+resize notifications; allocation, timestamp placement, structural and orientation changes can
+remeasure the complete mounted list.
+
 Horizontal time layouts using `collision="overlap"` or `collision="stack"` allocate their block size
 from the actual item content and lane offsets. The height follows content growth, shrinkage, and
 changes in lane count. `--lr-timeline-time-extent` still controls only the main-axis distance, and

package/llms/components/lr-token-input.md

@@ -9,7 +9,7 @@
 - **Release history** [CHANGELOG.md](../../CHANGELOG.md)
 - **Deprecations** none
 - **Optional peers** none
-- **Themeable via** 12 parts, 25 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 13 parts, 25 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`
 
 ---
@@ -58,6 +58,10 @@ value remains authoritative),
 `allowDuplicates`
 (`allow-duplicates`, default `false`), `editable` (reflected, default `false` — see below), and
 `delimiter: string | null` (default `','` — see below).
+`maxTokensVisible: number = 0` (attribute `max-tokens-visible`) — zero leaves every token mounted,
+preserving the default. Positive values bound mounted tokens while retaining the focused or editing
+token; `token-overflow` displays a localized count for the rest. Non-finite values restore the
+unlimited default. The value array and form submission still include every token.
 **Slots:** `label`, `hint`, `error`, `start` (adornment before the tokens), `end` (adornment after
 the draft input) — both wrapped in a `hidden`-toggling span, mirroring `lr-combobox`'s identical
 `start`/`end`.
@@ -85,7 +89,8 @@ token's text, doubling as the roving-focus edit trigger — rendered only while
 `token-editor` (the inline text field that replaces a token's text while it is open for editing —
 rendered only while `editable` and only for the token being edited), `remove` (the
 per-token remove button, floored at the shared `--lr-icon-button-size` tap size around a compact
-glyph), `input`, `start`, `end`, `hint`, `error`. `focus()`, `blur()`, `click()`, and `select()` forward to the
+glyph), `token-overflow` (the localized count of unmounted tokens), `input`, `start`, `end`, `hint`,
+`error`. `focus()`, `blur()`, `click()`, and `select()` forward to the
 internal draft text input. `selectionStart`, `selectionEnd`, and `selectionDirection` are readable/
 writable native-selection passthroughs; `setSelectionRange(start, end, direction?)` and
 `setRangeText(replacement, start?, end?, selectMode?)` expose the matching native methods.

package/llms/components/lr-tool-timeline.md

@@ -62,9 +62,17 @@ applied its controlled `entries` update (it never mutates `entries` itself). `re
 void` releases a held dialog after persistence fails, retaining the reviewer’s current argument edit
 so they can retry. Both are no-ops when no decision is held.
 
-At most 500 unique entries mount. Open disclosures and the entry under approval review reserve
-positions before later ordinary history is omitted; a localized `[part="limit"]` note exposes the
-bounded projection. Redaction is deferred until a disclosure opens and memoized while the entry's
+Assignment retains the newest 10,000 source entries (the array end is newest) in a bounded readonly
+outer snapshot. Source records and opaque `args`/`result` payloads retain identity, while a closed
+descriptor-safe projection copies the display fields once per admitted array. Reassign the
+collection to publish record changes; approval lookups reuse canonical identity indexes.
+
+After first-wins duplicate canonicalization, the newest 500 unique entries are selected before
+timestamp sorting. Open disclosures and the entry under approval review reserve positions within
+that same 500-row budget, displacing the oldest unreserved rows. Separate localized
+`[part="limit"]` notes disclose input retention and the rendered window; their counts use the
+effective locale. Initial truncation stays silent; a later transition into either limit is
+announced politely. Redaction is deferred until a disclosure opens and memoized while the entry's
 payload and path list are unchanged. It is bounded to 100 paths, 64 levels, 10,000 visited nodes,
 and 4,096 characters per path; crossing a ceiling masks the affected branch instead of exposing
 data or exhausting the page.
@@ -108,7 +116,8 @@ timeline.addEventListener("lr-tool-approval-decide-request", async (event) => {
 **CSS parts:** `base`,
 `entry`, `entry-marker`, `entry-header`, `entry-timestamp`, `entry-body`, `entry-details`,
 `entry-result`, `entry-error`, `entry-retries`, `entry-retries-count`, `entry-retries-label`,
-`entry-redacted-indicator`, `entry-approval-status`, `approval-dialog`, `empty`, `limit`.
+`entry-redacted-indicator`, `entry-approval-status`, `approval-dialog`, `empty`, `limit` (input-retention
+and rendered-window notices).
 Each entry's `lr-details` disclosure has a localized contextual summary naming that tool call, not a
 repeated bare "Details" label.