@aceshooting/lyra-ui 29.0.2 → 29.1.0

package/llms/components/lr-trace-tree.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** 17 parts, 11 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 23 parts, 11 custom properties — see this component's own `@csspart`/`@cssprop` list below
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
 
 ---
@@ -20,15 +20,92 @@ A collapsible span hierarchy for one agent/LLM trace (Langfuse/LangSmith run-tre
 name, status, an inline duration bar on the shared trace time scale, and optional tokens/cost
 columns. Consumes the same `LyraSpan[]` as `<lr-span-waterfall>`.
 
-Span views omit whitespace-only IDs and preserve every nonblank business ID exactly, including
+With `treeSource` unset, span views omit whitespace-only IDs and preserve every nonblank business ID exactly, including
 surrounding whitespace. The first valid admitted duplicate continues to win.
 
+**Complete provider hierarchy:** `treeSource: TraceTreeSource | undefined`
+(attribute: false) takes display precedence over `spans`, including when a defined provider is
+invalid. Invalid input shows a localized source failure; setting `undefined` restores current
+legacy spans. `maxNodes` limits only the legacy span projection, not complete provider counts.
+
+```ts
+import type { TraceTreeSource } from
+  "@aceshooting/lyra-ui/components/agent-tools/trace-tree/trace-tree.class.js";
+import type { LyraSpan } from
+  "@aceshooting/lyra-ui/components/agent-tools/trace-tree/span.js";
+import type { LyraHierarchySource, LyraHierarchyQuery, LyraTraceSourceSummary } from
+  "@aceshooting/lyra-ui/data-sources.js";
+```
+
+`TraceTreeSource` is exactly
+`LyraHierarchySource<LyraSpan, LyraHierarchyQuery, LyraTraceSourceSummary>`. Its immutable `revision`
+is a nonempty string or finite number. `project(request)` receives revision, locale, abort signal,
+previous opaque `state` (initially `null`), an action (`reset`, `toggle`, `reveal` or item `select`),
+and `{ search: '', hiddenKinds }`. The provider applies kind filtering to the complete hierarchy;
+the component has no source search or copy controls. Return
+`{ state, total, rows, summary: { startMs, endMs }, focusIndex? }`: `total` counts every logical
+node including collapsed nodes, and `rows.count` is the complete currently visible preorder.
+Counts are safe nonnegative integers with `rows.count <= total`; `state` is a nonempty immutable
+snapshot token of at most 65,536 UTF-16 units.
+
+The required `LyraTraceSourceSummary` describes the entire trace's timing extent, independent of
+loaded rows, collapsed branches and kind filters. Both endpoints are finite nonnegative
+trace-relative milliseconds, `endMs >= startMs`, with finite difference. Equal endpoints remain
+valid and reported unchanged. Missing/invalid summaries fail visibly; the component never derives
+the global extent from the current window or legacy spans. Bars subtract the global start before
+scaling; running spans retain a visible minimum width without rewriting the supplied extent.
+
+`rows` is an immutable `LyraHierarchyView<LyraHierarchyRow<LyraSpan>>`, either indexed
+`itemAt`/`keyAt`/`indexOfKey` or asynchronous `read` plus required `indexOfKey`. Each row has globally
+unique nonblank `key === value.id`, `parentKey`, one-based `level`/`position`, exact sibling
+`setSize`, `childCount`, `expanded`, `selected`, and optional `disabled`/`selectionState`. These
+fields own topology, expansion and provider selection; span `parentId` and nested children never
+rebuild a local hierarchy. Global uniqueness and immutable consistency remain provider obligations
+beyond the bounded admitted window.
+
+Only closed span display fields are copied: `id`, `name`, `detail`, `costText`, normalized
+`kind`/`status`, `startMs`, optional `endMs` and valid `tokensIn`/`tokensOut`. Nonblank IDs preserve
+surrounding whitespace. Source start must be finite/nonnegative; an explicit end must be finite
+and at least start. Unknown kinds become `other`, absent statuses `pending`, explicit unknown
+statuses `unknown`; invalid token metrics are omitted. Oversized display strings/rows fail without
+clipping. Keys/state/display strings are each at most 65,536 UTF-16 units; aggregate normalized
+row text including key/parent accounting is bounded to 65,536 units. Admitted cache/staging,
+focused-row and projection-state payloads share 2,000,000 units. Opaque metadata is not traversed.
+
+Four 100-row pages are retained (400 rows), plus at most one focused ready row. At most 301 rows
+mount, including the focused row; range reads request at most 100 rows with two physically pending
+reads. One projection call runs at a time with only the latest replacement queued. Ignored aborts
+retain physical permits until settlement. No complete source array, ancestor index or count-sized
+key map is built. Flat rows expose exact logical ARIA depth/sibling positions while visual
+indentation remains bounded; source rows own one treeitem/focus target each.
+
+`revealSourceKey(key: string): Promise<boolean>` directly resolves a global provider key, opens its
+ancestors and focuses the returned row. Absent, disabled, invalid, failed, canceled, obsolete and
+unset-source targets resolve `false`; there is no source-wide scan fallback. Source Home/End uses
+the full visible preorder, parent/reveal navigation uses direct lookup and branch arrows are
+RTL-aware. Disabled-row traversal examines at most 32 candidates. `activeSpanId` remains
+caller-controlled: source activation emits `lr-span-select { spanId }` only after the accepted
+item-selection action, without changing it. The active ID paints `aria-current` and reveals once
+per binding/ID; unrelated paints do not repeatedly undo user navigation. Accepted expansion emits
+exactly `lr-span-toggle { spanId, expanded }`. No additional source-selection event is introduced.
+`expandAll()`/`collapseAll()` are no-ops in source mode.
+
+Reassign even the same source, or call a keyless `requestUpdate()`, after revision/state changes.
+Changing `hiddenKinds` refreshes the provider query; named selection/presentation paints reuse
+accepted data. Locale/lifecycle refresh and source replacement revoke obsolete controls, requests,
+announcements and reveal effects. Loading/error/empty/retry are localized; window movement does
+not announce historical loaded span statuses as fresh changes. Source-only parts are `source-list`,
+`source-row`, `source-label`, `source-toggle`, `source-status` and `source-error`; existing span
+icon/name/detail/status/duration/token/cost/bar parts remain on their content. The following array
+admission and local hierarchy rules apply with `treeSource` unset.
+
 **Properties:** `spans: LyraSpan[] = []` (attribute: false) — the same `LyraSpan` shape documented
 under `lr-span-waterfall` above (exported from `trace-tree/span.ts`); hierarchy comes from
 `parentId`, and a span whose `parentId` is missing or doesn't resolve within the same array renders
 as a root rather than being dropped. Duration bars scale to the whole trace, measured before the
-shared 500-span cap is applied, so a truncated tail never stretches the surviving bars across their
-tracks. `activeSpanId: string | null = null`
+configured span cap is applied, so a truncated tail never stretches the surviving bars across their
+tracks. `maxNodes: number = 500` (attribute `max-nodes`) sets that cap, normalized to `1..5000`;
+unset or non-finite values restore 500. `activeSpanId: string | null = null`
 (attribute `active-span-id`), `label?: string`, `withTokens: boolean = false` (attribute
 `with-tokens`, reflected) — surfaces `tokensIn`/`tokensOut`, `withCost: boolean = false` (attribute
 `with-cost`, reflected) — surfaces `costText`, and `withoutBars: boolean = false` (attribute
@@ -39,26 +116,35 @@ Token counts render only when finite and non-negative; invalid metrics are omitt
 reaching `Intl.NumberFormat`. A row's accessible name includes its optional `detail` text as well
 as its name/status/metrics, and updates when the supplied span data changes. Every trace view uses
 the same bounded runtime projection: provider records are normalized with deterministic first-wins
-identity, then at most 500 mount. The controlled `activeSpanId` and its resolvable ancestor path
-reserve positions before ordinary input-order spans. Non-object records, empty/blank ids, non-finite
+identity, then at most `maxNodes` mount. The controlled `activeSpanId` and its nearest resolvable
+ancestors reserve positions inside that budget before ordinary input-order spans. Non-object records, empty/blank ids, non-finite
 starts/ends, and later duplicate ids are omitted; negative starts clamp to zero, ends clamp to at
 least their start, unknown kinds become `other`, and explicit unknown statuses become `unknown`;
 an absent status defaults to `pending`. A localized
-`[part="limit"]` note exposes truncation.
+`[part="limit"]` note exposes source or projection truncation. The first 10,000 outer input entries
+are admitted by identity; canonical display fields are copied without traversing opaque provider
+metadata. The active span cannot reserve an entry excluded by source admission. Initial limit
+notices are silent; a later transition into truncation is announced politely.
 
-**Methods:** `expandAll()` and `collapseAll()` set every row's expanded state at once.
+**Methods:** with `treeSource` unset, `expandAll()` and `collapseAll()` set every row's expanded
+state at once; `revealSourceKey(key)` is the provider navigation method described above.
 
 **Events:** `lr-span-select` (`detail: { spanId: string }`, a row was activated) and `lr-span-toggle`
 (`detail: { spanId: string; expanded: boolean }`, a row was expanded or collapsed).
 
-**Hidden kinds and focus:** `hiddenKinds: readonly LyraSpan['kind'][] = []` (attribute: false) leaves those kinds out of the tree; a span whose parent is hidden becomes a root, and the duration bars and the 500-row limit notice keep following the whole trace (`lr-agent-trace` forwards its own `hiddenKinds` here). `spans` is kept by item identity, so a large trace with opaque provider metadata is never cut by a field budget. The browsed row stays the tab stop across `spans`/collapse changes, and the active row scrolls into view only when `active-span-id` changes.
+**Hidden kinds and focus with `treeSource` unset:** `hiddenKinds: readonly LyraSpan['kind'][] = []` (attribute: false) leaves those kinds out of the tree; a span whose parent is hidden becomes a root, and the duration bars and configured limit notice keep following the whole admitted trace (`lr-agent-trace` forwards its own `hiddenKinds` here). Opaque provider metadata does not consume a deep-field budget. The browsed row stays the tab stop across `spans`/collapse changes, and the active row scrolls into view only when `active-span-id` changes.
 
 **CSS parts:** `base` (`role="tree"`), `header` (the column-header row, only when
 `with-tokens`/`with-cost`), `row` (`role="treeitem"`), `toggle`, `icon`, `name`, `detail`, `status-text`,
 `duration`, `tokens-in`, `tokens-out` (when `with-tokens`), `cost` (when `with-cost`), `bar-track`,
-`bar`, `empty` (shown when `spans` is empty), `limit` (the 500-span projection notice), and
+`bar`, `empty` (shown when `spans` is empty), `limit` (source or projection truncation notice), and
 `live-region`.
 
+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-trace-tree-row-active-bg` (default
 `var(--lr-color-brand-quiet)`) — the background of the active (`activeSpanId`) row, and the base
 its hover/press mixes from — and

package/llms/components/lr-transcript-feed.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** 10 parts, 0 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 11 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`
 
 ---
@@ -21,6 +21,12 @@ with in-place upgrades keyed by `id`, and a stick-to-bottom auto-scroll with rel
 `follow`/`lr-follow-change` contract `<lr-terminal>` uses. Live captions only — recorded-media
 transcript sync is a separate concern.
 
+`entries` retains the newest 10,000 records within the shared 50,000-value deep snapshot budget.
+The visible `limit` part discloses omitted input through `transcriptFeedInputLimit`, with `count`
+and `total` placeholders. Final-caption replay suppression keeps up to 10,000 recent IDs, always
+preserving currently retained captions. An ID evicted from that history may be announced if later
+reintroduced.
+
 Activating the focused jump action resumes follow and transfers focus to the scroll base when the
 action disappears, unless a newer outside focus move takes precedence.
 
@@ -63,4 +69,5 @@ state or the built-in jump action re-engages it. Direct `follow` assignments and
 only), `entry`, `speaker` (omitted for a row repeating the previous row's speaker), `text`
 (`dir="auto"`), `timestamp` (only while `with-timestamps`), `interim` (present alongside `entry` on
 an interim row), `interim-area` (the wrapper holding interim rows, rendered only while at least one
-interim entry exists), `jump-button` (shown only while `follow` is `false`), and `empty`.
+interim entry exists), `jump-button` (shown only while `follow` is `false`), `empty`, and `limit`
+(input-loss notice).

package/llms/components/lr-tree.md

@@ -9,7 +9,7 @@
 - **Release history** [CHANGELOG.md](../../CHANGELOG.md)
 - **Deprecations** none
 - **Optional peers** none
-- **Themeable via** 4 parts, 5 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 10 parts, 5 custom properties — see this component's own `@csspart`/`@cssprop` list below
 - **Documented with** `lr-tree-item` (same section below)
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
 
@@ -39,7 +39,55 @@ with `badges: [{ text: String(value) }]`. The former item-controller fields (`ac
 `depth`, `setSize`, `posInSet`) and context setters were never consumer state; they are now private
 owner context maintained by `<lr-tree>`.
 
-**Two child models are accepted, and they never interleave.**
+**Provider hierarchy:** `treeSource: TreeSource | undefined` (attribute: false) is an
+identity-owned full-source route. `TreeSource` is
+`LyraHierarchySource<LyraTreeNodeData, LyraHierarchyQuery>` from
+`@aceshooting/lyra-ui/data-sources.js`. A defined source takes precedence over `data` and authored
+items; invalid defined input shows a localized source error instead of restoring legacy rows.
+Setting `undefined` restores the current authored-over-data precedence below. Source descriptors
+are never assigned to `data`, and author-written items are retained without being rendered in
+source mode. Reassign the source, including the same object, or call a keyless `requestUpdate()`
+after revision or provider-state changes. Locale changes and reconnect/adoption refresh the
+projection; unrelated named display updates do not.
+
+The provider's `project(request)` handles `reset`, `toggle`, `reveal` and `select` actions and returns
+an immutable `{ state, total, rows, focusIndex? }` projection. Requests include revision, locale,
+abort signal, previous opaque `state` (initially `null`), and the fixed query
+`{ search: '', hiddenKinds: [] }`. `total` counts all logical nodes, including collapsed nodes;
+`rows.count` counts the complete currently visible preorder. Both are nonnegative safe integers,
+with `rows.count <= total`. The summary reports those logical counts, not mounted rows. A million
+nodes can remain in host-owned storage without a library-wide flattening or ancestor index.
+
+`rows` is a `LyraHierarchyView<LyraHierarchyRow<LyraTreeNodeData>>`: either indexed
+`itemAt`/`keyAt`/`indexOfKey`, or asynchronous `read` plus required `indexOfKey`. There is no scan
+fallback for key lookup. Each row supplies its global unique `key`, matching `value.id`, plus
+`parentKey`, one-based `level`/`position`, exact sibling `setSize`, `childCount`, `expanded`,
+`selected`, and optional
+`disabled`/`selectionState`. Hierarchy metadata owns those states; nested `value.children` is never
+read. Keys must be nonblank strings of at most 65,536 UTF-16 units and are preserved verbatim.
+The opaque state token must be a nonempty string of at most 65,536 units. Display values use own
+data properties, at most 100 badges and 65,536 aggregate display-text units per row; malformed or
+oversized rows fail visibly without compacting logical indices. The provider owns global key
+uniqueness and immutable snapshot consistency; validation covers the bounded admitted window.
+
+The source view mounts at most 301 rows, retaining four 100-row pages plus at most one focused
+ready row (401 total). Range requests contain at most 100 rows, with at most two physically pending
+reads. One projection call runs at a time with only the latest replacement queued. Loading/error
+rows are not selectable records; localized retry preserves their logical position. Empty is a
+separate valid state. Providers should honor abort signals; revoked results cannot commit, but an
+ignored abort does not release a physical request until it settles.
+
+Source keyboard navigation uses the full visible count for Home/End, direct provider lookup for
+parents/reveal, and RTL-aware branch arrows. Disabled-row navigation examines at most 32 candidates
+and keeps current focus if none can be resolved. Logical ARIA depth/sibling positions remain exact
+while visual indentation clamps at 32 levels. A bounded roving row or root entry stop remains
+available as rows scroll; an off-window focused row is retained within the same mount bound.
+The provider owns selection/cascade/partial state: `single` selects an item, `leaf` permits only
+leaves, `multiple` toggles an item or a branch's `subtree`, and `leaf-multiple` toggles leaves only.
+These adapters expose exploration and selection, with no component source search/copy controls.
+`maxNodes` governs the legacy data model, not the source total or its fixed window bounds.
+
+**With `treeSource` undefined, two legacy child models are accepted and never interleave.**
 
 - **Declarative** (mirrors the upstream markup, so a tag rename is the whole migration): write
   nested `<lr-tree-item>` elements as light-DOM children, each carrying its own
@@ -56,6 +104,7 @@ owner context maintained by `<lr-tree>`.
 
 A tree containing any author-written `<lr-tree-item>` child is read purely as the declarative model
 and `data` is ignored. The empty state renders only when neither model has any items.
+Author-written light-DOM items have no total-node cap; traversal still stops at 64 descendant levels.
 
 Both child models use the same selection, roving-focus, checkbox-cascade, icon, and lazy-loading
 engine. The upstream lifecycle names are normalized to the library-wide `lr-` prefix;
@@ -80,10 +129,10 @@ deeply-nested node's own shadow root still reaches it).
   after changes (rebinding the same array is a no-op). A refresh is diffed by id: a node whose
   fields (including an icon template from the same literal with equal values) and children are
   unchanged keeps its previous object, so its row neither re-renders nor re-seeds element state.
-  Normalization accepts at most 1,000 valid nodes and 64 descendant levels, and lazily
+  Normalization accepts at most `maxNodes` valid nodes (default 1,000) and 64 descendant levels, and lazily
   inspects at most 10,000 root/child array positions globally in depth-first order. It never
   invokes caller accessors and exposes `dataTruncated = true` when malformed or over-budget input
-  was omitted or the inspected-position ceiling was reached. When more than 1,000 valid nodes are
+  was omitted or the inspected-position ceiling was reached. When more than `maxNodes` valid nodes are
   supplied, the localized `limit` part reports the retained-node cap; malformed input alone does
   not show that cap notice. Collapsed branches do not instantiate descendants; disclosure projects only normalized
   children while `aria-setsize` preserves the declared sibling count. `LyraTreeNodeData` is
@@ -100,6 +149,9 @@ LyraVariant; readonly label?: string }`. `badges` renders tone-mapped chips in o
   removed by later object refreshes; removing the author attribute restores the current data name.
   `id` is the event, roving-focus, reconciliation, and reorder identity and must be unique across
   the complete reachable hierarchy; malformed rows, blank IDs and later duplicates are omitted as described above
+- `maxNodes: number = 1000` (attribute `max-nodes`) — the object-data node budget, normalized to
+  `1..10000`; unset or non-finite values restore 1,000. Set it before assigning `data`. Raising it
+  does not recover excluded input automatically: reassign the original source after raising the cap.
 - `selection: 'single'|'multiple'|'leaf'|'leaf-multiple' = 'single'` — self-managed selection for
   both child models. `single` selects one item; `leaf` selects one loaded leaf; `multiple` displays
   checkboxes and cascades through enabled descendants; `leaf-multiple` applies that cascade only
@@ -114,7 +166,9 @@ LyraVariant; readonly label?: string }`. `badges` renders tone-mapped chips in o
 
 **Read-only getters:** `selectedItems: readonly LyraTreeItem[]` returns a new frozen snapshot of
 selected item elements in document order, including derived fully-selected parents in either
-multiple mode. `dataTruncated: boolean` reports bounded/malformed normalization as described above.
+multiple mode. It returns an empty frozen array in source mode; it never enumerates unmounted
+provider selection. `dataTruncated: boolean` reports legacy bounded/malformed normalization as
+described above.
 
 **Keyboard:** ArrowDown/ArrowUp move the roving focus to the next/previous _visible_ node.
 ArrowRight expands a collapsed node (focus stays put; a second ArrowRight then steps into the first
@@ -148,10 +202,22 @@ roving stop to the next reachable row instead of stranding it, and the state is
   `selectedItems` and the multiple-mode cascade are unchanged and a modal that inerts the page can
   never silently wipe a tree's selection.
 
-**Methods:** `expandAll(): Promise<void>`, `collapseAll(): Promise<void>` (both iterative, bounded,
-and resolved only after the affected rendered item cascade settles).
-
-**Events:** `lr-selection-change` (`detail: { selection }`, where both the detail and selection
+**Methods:** `revealSourceKey(key: string): Promise<boolean>` asks the source to reveal a global
+key and focuses its current visible row; it resolves `false` for absent, invalid, obsolete or
+unset-source requests. Source `reveal` responses need a valid `focusIndex` to resolve successfully.
+`expandAll(): Promise<void>`, `collapseAll(): Promise<void>` (both iterative, bounded
+by hierarchy depth, and resolved only after the affected rendered item cascade settles). Items at
+each depth expand together, preserving their individual lifecycle events, motion durations and lazy
+loading behavior.
+
+Both bulk methods are no-ops in source mode, and `reorderable` has no source-mode effect. Expansion
+and selection use provider projection actions rather than legacy item/lazy lifecycle events.
+
+**Events:** source mode emits `lr-source-selection-change` only after a current user selection
+projection commits: frozen readonly `detail: { key: string; selected: boolean;
+scope: 'item' | 'subtree'; state: string }`. It reports the accepted global-key intent and new
+opaque state, without constructing a DOM selection array. The following events are legacy-only:
+`lr-selection-change` (`detail: { selection }`, where both the detail and selection
 snapshot are frozen; fired for user selection and when a `data` refresh removes or re-seeds selected
 rows) and `lr-reorder` (`detail: { nodeId, parentNodeId, fromIndex, toIndex }`, only while `reorderable`).
 Like every other event here it is a **request**: `data` is host-owned and is never mutated by this
@@ -175,7 +241,11 @@ icons; an item-level slot with the same name takes precedence.
 
 **CSS parts:** `base` and `tree` are aliases on the same `role="tree"` root; `empty` is the
 empty-state message shown when neither child model has any items; `limit` is the localized
-retained-node cap notice when more than 1,000 valid nodes are supplied.
+retained-node cap notice when valid object-data nodes exceed `maxNodes`.
+Source mode adds `source-list`, `source-row`, `source-toggle` (branch and retry buttons),
+`source-label`, `source-status`, and `source-error`, retaining the `base`/`tree` aliases. Its tree
+root owns the accessible name, busy state and multiselectability; flat source rows own their
+treeitem metadata. Source rows are not `<lr-tree-item>` instances and do not use its item slots.
 
 **Themeable custom properties:** shared tokens `--lr-space-xs`/`-s`, `--lr-color-brand-quiet`,
 `--lr-color-text-quiet`, `--lr-color-border`, `--lr-color-border-subtle`, `--lr-color-text`,
@@ -187,7 +257,8 @@ since the host itself is the focusable `role="treeitem"`), plus `--indent-size`,
 
 ### `lr-tree-item`
 
-One row of the tree, in either child model. `role="treeitem"` (plus
+One row of the tree, in either legacy child model; provider source mode renders its own bounded
+flat rows instead. `role="treeitem"` (plus
 `aria-expanded`/`aria-level`/`aria-setsize`/`aria-posinset`/`aria-selected` and the roving
 `tabindex`, driven by `<lr-tree>`) live on the _host_ element itself, not an internal row `<div>` —
 so this node's own nested children (whether rendered in its own shadow root or projected from the
@@ -364,13 +435,14 @@ The declarative model — the same shape a renamed `wa-tree`/`sl-tree` subtree l
 - `lr-tree`'s `getUpdateComplete()` cascades through owner-controlled descendants
   `<lr-tree-item>`'s own `updateComplete` (see `update-cascade.ts`) so that code awaiting the
   tree's `updateComplete` does not run before a reachable nested node has finished rendering its
-  roving `tabIndex`. The same 64-level/1,000-node work bounds apply to context, focus, selection,
-  and disclosure walks.
+  roving `tabIndex`. Context, selection and disclosure walks retain the 64-level depth guard;
+  object data also retains its configured node cap. Moving focus patches the previous and next
+  item without rebuilding the hierarchy.
 - row enrichment is intentionally structured rather than an unrestricted renderer: use `icon`,
   `label`, `description`, `badges`, and `accessibleLabel`. This keeps the host as the single
   `role="treeitem"` interaction target and preserves the APG keyboard model.
-- `lr-file-tree` does **not** forward `reorderable`, and deliberately so: its `LyraTreeNodeData[]` is derived
-  from `nodes` on every render and keyed by filesystem path, an order it does not own.
+- `lr-file-tree` does **not** forward `reorderable`, and deliberately so: its `LyraTreeNodeData[]` is
+  derived from `nodes` and keyed by filesystem path, an order it does not own.
 - in the declarative model, appending a child while the parent is collapsed still registers: a
   `childList` MutationObserver assigns the `children` slot and requests an update, because
   `slotchange` alone cannot see a child added to a slot that is not currently rendered. Editing a

package/llms/components/lr-unit-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`
 
 ---
@@ -30,6 +30,11 @@ symbols. Selection edits no amount and performs no unit conversion. Catalog type
 resolution 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`),
@@ -42,8 +47,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-video-playlist.md

@@ -34,6 +34,8 @@ visible but disabled while live children are unavailable; after hydration, each
 title/poster/duration and native `inert` state become authoritative in a corrective update that
 reuses the server-rendered row nodes. Once live children have been observed, later removal does not
 make stale seed rows reappear.
+Live-child updates no longer scan the superseded seed metadata. Removing every adopted child
+keeps live-child ownership; it does not reactivate the original seed rows.
 
 **Methods:** `goTo(index)` selects a finite integer direct-child index; invalid, fractional, and
 inert-child indexes are no-ops. Calling it for the current index still emits `lr-video-change`, matching

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

@@ -46,7 +46,9 @@ indexOfKey?(key): number }`. When set it takes precedence over `items`. The inde
   target an indexed source: the list never performs a count-sized fallback scan; invalid or
   out-of-range results mean no match. An array source receives the same clone-owned frozen sequence
   and row-identity contract as `items`; an indexed-source object passes through by identity and is
-  not capped, so use one beyond 10,000 rows. `groups` keeps at most 10,000 entries and 50,000 nested values.
+  not capped, so use one beyond 10,000 rows. After changing an indexed count or callback closure,
+  call `requestUpdate()` to refresh the source and active-key lookup; this also works when a
+  named property update is pending. `groups` keeps at most 10,000 entries and 50,000 nested values.
 - `renderItem: (item: unknown, index: number) => unknown = () => nothing` (attribute: false) — renders
   one row's content, typically returning a `lit-html` `TemplateResult`. JS-only. The returned value
   is stamped inside `<lr-virtual-list>`'s own shadow root, not the caller's light DOM, so
@@ -189,18 +191,25 @@ In auto-height mode, estimate-based jumps are corrected as row and group-marker
 That correction is bound to the source, key function, and target identity and is canceled on a new
 target, data replacement, manual scroll intent, or disconnect, so late observations cannot pull a
 newer view back to stale content.
-`offsetForIndex(index)` returns the pixel top row `index` renders at, in the same coordinate space as
-the scroll container's `scrollTop`; under an external `scrollElement` that space is unchanged — it
+`offsetForIndex(index)` returns the logical pixel top of row `index`; under an external
+`scrollElement` that space is unchanged — it
 measures from the top of the list itself, not from the top of the external scroller's content, and
 the component converts between the two. It is clamped to `0…count`, so `offsetForIndex(count)`
-is the total content height and an empty list is always `0`. `indexAtOffset(px)` is its inverse — the
+is the logical total content height and an empty list is always `0`. `indexAtOffset(px)` is its inverse — the
 row whose box contains that offset, clamped at both ends, `-1` for an empty list — so
-`indexAtOffset(offsetForIndex(i)) === i` and `indexAtOffset(scrollContainer.scrollTop)` is the row at
-the top of the viewport. In `row-height="auto"` mode both are estimate-based for any row that (or
+`indexAtOffset(offsetForIndex(i)) === i`. Native `scrollTop` shares this logical space only while
+scrollbar scaling is inactive. In `row-height="auto"` mode both are estimate-based for any row that (or
 above which) has not been measured yet, and converge as those `ResizeObserver` measurements land;
 fixed numeric `row-height` offsets are exact from the first render. Both read the most recent render,
 so `await el.updateComplete` after assigning `items` or `source` before querying.
 
+Above 8,000,000 logical pixels, the list scales native scrollbar travel below browser layout limits.
+Visible row heights and adjacent spacing remain unchanged. Position methods, `active-item-id` and
+`lr-virtual-scroll` use logical pixels; native `scrollContainer.scrollTop` uses compressed scrollbar
+space. Scaling emits a one-time development warning and also applies with an external
+`scrollElement`. Use the component's position methods for large indexed sources instead of assigning
+logical offsets to native `scrollTop`.
+
 **Getters:** `scrollContainer: HTMLElement | undefined` — the real scroll container (`[part="base"]`),
 `undefined` before the first render; for a host that needs the live scroll position or wants to scroll
 the list itself without reaching into the shadow root. While `scrollElement` is set this element
@@ -235,8 +244,8 @@ changes, this reports _sub-row_ movement, which is what scroll-linked layout nee
 **CSS parts:** `base` (the scrollable container, `role="list"` — or `role="rowgroup"` in
 `item-role="row"` mode — `tabindex="0"`; under an external `scrollElement` it stops scrolling, drops
 that `tabindex` and its hover outline, and sizes itself to the list's full virtual extent instead of
-`--lr-virtual-list-height`), `spacer` (the full-content-height inner element
-establishing true scroll extent; `role="presentation"` in `item-role="row"` mode), `row` (one
+`--lr-virtual-list-height`), `spacer` (the inner element establishing the physical scroll extent,
+compressed for very large sources; `role="presentation"` in `item-role="row"` mode), `row` (one
 rendered row's absolutely-positioned wrapper, `role="listitem"` — or `role="row"` with
 `aria-rowindex` in `item-role="row"` mode), `group` (a `groups` entry's positioned marker; not
 rendered for an entry whose `label` is the empty string), `sticky-group` (the pinned copy of the

package/llms/components/lr-voice-picker.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** 18 parts, 34 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 19 parts, 34 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`
 
 ---
@@ -18,7 +18,7 @@
 
 Override `--lr-voice-picker-trigger-padding`, `--lr-voice-picker-font-size`, and `--lr-voice-picker-expand-size` for trigger spacing, text size, and the expand control’s minimum target cap.
 
-The voice list follows the [shared surface treatment](shared/styles-and-tokens.md);
+The voice list follows the [shared surface treatment](../shared/styles-and-tokens.md);
 its editing field retains an opaque fill.
 
 A TTS voice selector over a host-supplied `catalog`, mirroring `lr-model-select`'s
@@ -64,6 +64,11 @@ voice list; omit (or leave empty) to fall back to plain free-text entry; replaci
 internal preview before the rendered candidate changes. Ids use the shared unique, nonempty,
 first-wins catalog rule documented under `lr-model-select`, including preview lookup. Assignments
 become bounded clone-owned frozen snapshots; create and reassign a new array after row changes.
+Admission retains the first 1,024 source rows within the shared 50,000-value deep snapshot budget;
+normalization examines that admitted prefix. The localized `limit` part reports omitted input
+through `catalogPickerInputLimit`. A synthetic row for a committed value outside the catalog can
+still be appended. Closed listboxes contain no option rows after their exit transition; trigger
+labels and free-text behavior remain available.
 `allowCustom: boolean = false` (attribute
 `allow-custom`, reflected) — let the user type/commit a value that isn't in `catalog`.
 `withoutPreview: boolean = false` (attribute `without-preview`, reflected) — renders no preview
@@ -141,7 +146,7 @@ constraint validation (own `disabled` or `readonly`, or an ancestor `<fieldset d
 reports no violation and publishes neither `:state(invalid)` nor
 `:state(user-invalid)`.
 
-**CSS parts:** `form-control` (the complete field frame), `form-control-label`, `trigger` (closed-dropdown mode), `combobox`/`combobox-input`
+**CSS parts:** `limit` (input-loss notice), `form-control` (the complete field frame), `form-control-label`, `trigger` (closed-dropdown mode), `combobox`/`combobox-input`
 (free-text mode), `provider-badge`, `listbox`, `option`, `option-icon` (an object-shaped catalog
 row's optional decorative leading icon), `option-label`, `option-meta` (the quiet
 `language · description` second line), `option-badge` (the "not in catalog" badge on a synthetic