@aceshooting/lyra-ui 5.0.0 → 5.2.0

package/llms/components/lr-trace-tree.md

@@ -0,0 +1,58 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/agent-tools.md — do not edit this file. -->
+
+# `lr-trace-tree`
+
+- **Import** `import '@aceshooting/lyra-ui/components/agent-tools/trace-tree/trace-tree.js';` (registers the tag; side-effect import)
+- **Class** `LyraTraceTree`, also available unregistered from `@aceshooting/lyra-ui/components/agent-tools/trace-tree/trace-tree.class.js`
+- **Family** `components/agent-tools/` — see `llms/index.md` for its siblings
+- **Optional peers** none
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-trace-tree`
+
+A collapsible span hierarchy for one agent/LLM trace (Langfuse/LangSmith run-tree style): kind icon,
+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>`.
+
+**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. `activeSpanId: string | null = null`
+(attribute `active-span-id`), `label: string = ''`, `showTokens: boolean = false` (attribute
+`show-tokens`) — surfaces `tokensIn`/`tokensOut`, `showCost: boolean = false` (attribute
+`show-cost`) — surfaces `costText`, and `hideBars: boolean = false` (attribute `hide-bars`).
+
+**Methods:** `expandAll()` and `collapseAll()` set every row's expanded state at once.
+
+**Events:** `lr-span-select` (`detail: { id: string }`, a row was activated) and `lr-span-toggle`
+(`detail: { id: string; expanded: boolean }`, a row was expanded or collapsed).
+
+**CSS parts:** `base` (`role="tree"`), `header` (the column-header row, only when
+`showTokens`/`showCost`), `row` (`role="treeitem"`), `toggle`, `icon`, `name`, `detail`, `status-text`,
+`duration`, `tokens-in`, `tokens-out` (when `showTokens`), `cost` (when `showCost`), `bar-track`,
+`bar`, `empty` (shown when `spans` is empty), and `live-region`.
+
+**Themeable custom properties:** `--lr-trace-tree-row-active-bg` (default
+`var(--lr-color-brand-quiet)`) — the background of the active (`activeSpanId`) row — and
+`--lr-trace-tree-row-active-color` (default `var(--lr-color-text)`) — the color of that row's
+secondary text (`detail`, `duration`, `tokens-in`, `tokens-out`, `cost`, and the `pending`
+`status-text` label). Same state-scoped-property convention described under `lr-span-waterfall`
+above: an inline `var()` fallback rather than a `:host` declaration, so either can be set on the
+element or any ancestor, and they exist because `::part(row)[data-active]` is invalid CSS.
+
+**Contrast note:** the active row is more than a tint. Its secondary text would sit at ~4.25:1
+against the default tint if it stayed at `--lr-color-text-quiet`, so it rises to full-strength
+`--lr-color-text` while the row is active, and the semantic `status-text` labels are rendered as
+`color-mix(in srgb, var(--lr-color-<tone>) 75%, var(--lr-color-text))` — keeping the status hue
+(an error row stays red) while clearing the 4.5:1 floor (success 4.46 → 6.18, `denied` 4.28 →
+5.96). Both adjustments are theme-symmetric, because `--lr-color-text` flips with the color
+scheme. `[part='bar']` is deliberately untouched: it is a non-text graphic on a 3:1 floor, and its
+saturation is the row's primary status signal.
+
+The two properties are a **pair**. The defaults assume the active background stays on the same
+side of the lightness midpoint as the ambient surface, so a consumer who sets
+`--lr-trace-tree-row-active-bg` to a dark tint in light mode (or a light one in dark mode) must
+set `--lr-trace-tree-row-active-color` to match, and should re-check the status-label tones
+against the new tint as well.

package/llms/components/lr-transcript-feed.md

@@ -0,0 +1,45 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/conversation.md — do not edit this file. -->
+
+# `lr-transcript-feed`
+
+- **Import** `import '@aceshooting/lyra-ui/components/conversation/transcript-feed/transcript-feed.js';` (registers the tag; side-effect import)
+- **Class** `LyraTranscriptFeed`, also available unregistered from `@aceshooting/lyra-ui/components/conversation/transcript-feed/transcript-feed.class.js`
+- **Family** `components/conversation/` — see `llms/index.md` for its siblings
+- **Optional peers** none
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-transcript-feed`
+
+Live captions for an in-progress voice session: speaker-grouped entries, interim-vs-final styling
+with in-place upgrades keyed by `id`, and a stick-to-bottom auto-scroll with release, the same
+`follow`/`lr-follow-change` contract `<lr-terminal>` uses. Live captions only — recorded-media
+transcript sync is a separate concern.
+
+**Properties:** `entries: LyraTranscriptEntry[] = []` (attribute: false) — `LyraTranscriptEntry { id:
+string; speaker?: string; text: string; interim?: boolean; timestamp?: number }` (exported by this
+module; `timestamp` is epoch **milliseconds**). Reconciled keyed by `id` via Lit's `repeat()`: a
+same-`id` entry with new `text` replaces in place, and a same-`id` entry whose `interim` flips from
+`true` to unset/`false` moves from the interim area into the `role="log"` region and announces
+exactly once. Interim entries render *after* the log container — visible, but structurally outside
+it — so per-token mutations are never spoken by assistive tech. `follow: boolean = true`
+(reflected), `showTimestamps: boolean = false` (attribute `show-timestamps`), `formatTimestamp?:
+(epochMs: number) => string` (attribute: false), `maxRenderedEntries: number = 0` (attribute
+`max-rendered-entries`) — `0` renders every entry; a positive value keeps only the newest N,
+`label: string = ''` — accessible name for the `role="log"` region
+(default: the localized `transcriptFeedLabel`), and `accessibleLabel: string | null = null`
+(attribute `aria-label`) — overrides the log's computed accessible name, winning over `label` and
+the localized default; attribute-reflects from a host-level `aria-label`.
+
+**Methods:** `scrollToBottom()` re-engages `follow` and scrolls to the latest entry.
+
+**Slots:** `empty` — custom empty state (default: the localized "No transcript yet").
+
+**Events:** `lr-follow-change` — `detail: { following }`, fires on every `follow` transition.
+
+**CSS parts:** `base` (the scroll container), `log` (the `role="log"` region wrapping final entries
+only), `entry`, `speaker` (omitted for a row repeating the previous row's speaker), `text`
+(`dir="auto"`), `timestamp` (only while `show-timestamps`), `interim` (present alongside `entry` on
+an interim row), `interim-area` (the wrapper holding the interim row, present whether or not an
+interim entry is showing), `jump-button` (shown only while `follow` is `false`), and `empty`.

package/llms/components/lr-tree-node.md

@@ -0,0 +1,151 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/data.md — do not edit this file. -->
+
+# `lr-tree-node`
+
+- **Import** `import '@aceshooting/lyra-ui/components/data/tree/tree-node.js';` (registers the tag; side-effect import)
+- **Class** `LyraTreeNode`, also available unregistered from `@aceshooting/lyra-ui/components/data/tree/tree-node.class.js`
+- **Family** `components/data/` — see `llms/index.md` for its siblings
+- **Optional peers** none
+- **Documented with** `lr-tree` (same section below)
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-tree` / `lr-tree-node`
+
+An expand/collapse hierarchy (document/graph navigation tree). `lr-tree` owns the data and
+imperatively creates/reconciles light-DOM `<lr-tree-node>` children by `id`; `lr-tree-node`
+recursively renders itself and its own nested children.
+
+### `lr-tree`
+
+Implements the full WAI-ARIA treeitem keyboard pattern: a single roving `tabindex` (tracked as
+`activeId`, pushed down to every `<lr-tree-node>` including nested ones) and
+ArrowUp/Down/Right/Left/Home/End/Enter/Space handled by one delegated `keydown` listener (native
+`KeyboardEvent`s are `composed: true` and bubble across shadow-DOM boundaries, so a press inside a
+deeply-nested node's own shadow root still reaches it).
+
+**Properties:**
+- `data: TreeItem[] = []` (attribute: false) — `TreeItem { id: string; label: string; children?:
+  TreeItem[]; badge?: string | number; icon?: unknown; description?: string; accessibleLabel?:
+  string }`; `icon` renders as a decorative leading visual, `description` as secondary visible row
+  text, and `accessibleLabel` names the `role="treeitem"` host without changing its visible label
+- `label: string = ''` — accessible name for the tree; `role="tree"` lives on an internal
+  `[part="base"]` element. The component forwards a host `aria-label` to that semantic element when
+  `label` is empty; `label` takes precedence when both are set. External `aria-labelledby` idrefs
+  are not forwarded across the shadow boundary.
+- `reorderable: boolean = false` (reflected) — opts into keyboard reordering. Unset, no `lr-reorder`
+  is ever emitted, Ctrl/Cmd+Arrow behaves exactly like a plain Arrow press, and the internal live
+  region is not rendered at all.
+
+**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
+child) or moves into an already-expanded node's first child. ArrowLeft collapses an expanded node, or
+moves focus to its parent. Home/End jump to the first/last visible node. Enter/Space activate
+`select()` on the focused node. While `reorderable`, **Ctrl/Cmd**+ArrowUp/ArrowDown moves the focused
+node within its own parent's child list instead of navigating. Ctrl/Cmd rather than Alt: Alt+Arrow is
+browser back/forward on Windows and Linux. ArrowUp/ArrowDown are not direction-sensitive, so this
+binding is deliberately **not** RTL-swapped — "down" always means later in the sibling list.
+
+**Methods:** `expandAll()`, `collapseAll()` (both recursive, properly sequenced around Lit's render
+cycle).
+
+**Events:** `lr-reorder` (`detail: { id, parentId, fromIndex, toIndex }`, only while `reorderable`).
+Like every other event here it is a **request**: `data` is host-owned and is never mutated by this
+component, so nothing moves until the host reassigns a reordered `data` — focus then follows the
+moved node. `parentId` is `null` for a top-level item, and `fromIndex`/`toIndex` are **sibling-scoped
+indices**, not positions in the flattened visible list. The move is constrained to one sibling list
+and never fires at a subtree boundary, so a reorder can never become a reparent: Ctrl+ArrowDown on
+the last child of a subtree is ambiguous (the visually next row is a top-level uncle, so "move down"
+could mean either "swap with the next sibling" — there is none — or "reparent up a level"), and
+reparenting is a structural edit with no keyboard affordance distinguishing the two. Such a request
+is simply not made: no event, no announcement, focus stays put. Otherwise this element dispatches
+nothing directly (see `lr-tree-node` below — those bubble up and are also observed internally to keep
+the roving `activeId` in sync with clicks).
+
+**Slots:** default (holds the `<lr-tree-node>` elements it manages).
+
+**CSS parts:** `base`, `empty` (the empty-state message shown when `data` is empty)
+
+**Themeable custom properties:** shared tokens `--lr-space-xs`/`-s`, `--lr-color-brand-quiet`,
+`--lr-color-text-quiet`, `--lr-color-border`, `--lr-color-text`, `--lr-radius`,
+`--lr-focus-ring-*` (row `:focus-visible` ring, driven by `:host(:focus-visible)` since the host
+itself is the focusable `role="treeitem"`).
+
+**Optional peer deps:** none.
+
+### `lr-tree-node`
+
+Normally set internally by `lr-tree`, but a public element. `role="treeitem"` (plus
+`aria-expanded`/`aria-level`/`aria-setsize`/`aria-posinset` 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 (rendered in its own shadow root as further `role="group"` content) are genuine DOM
+descendants of the treeitem, matching the WAI-ARIA treeitem pattern's containment expectation.
+
+**Properties:**
+- `item: TreeItem` (required, attribute: false)
+- `depth: number = 0`
+- `expanded: boolean = false` (reflected)
+- `activeId: string | null = null` (attribute: false) — the id of the tree's roving-tabindex-focused
+  item, pushed down from `<lr-tree>`; normally set internally, not by consumers
+- `setSize: number = 1`, `posInSet: number = 1` (attribute: false) — this node's `aria-setsize`/
+  `aria-posinset` values among its siblings, pushed down from `<lr-tree>`; normally set internally,
+  not by consumers
+- `hasChildren: boolean` (read-only getter) — reports whether `item.children` contains at least one
+  child; leaf nodes never expose `aria-expanded` and cannot expand or collapse
+
+**Methods:** `expand()`, `collapse()` (each a no-op if already in that state, or a leaf), `select()`
+(fires `lr-node-select`).
+
+**Events:** `lr-node-toggle` (`detail: { id, expanded }`, fired by `expand()`/`collapse()` — via
+the toggle button or ArrowRight/ArrowLeft), `lr-node-select` (`detail: { id }`, fired by `select()`
+— via clicking anywhere in the row or Enter/Space) — dispatched from `lr-tree-node`,
+bubble/compose up
+through `lr-tree`'s light DOM.
+
+**Slots:** none.
+
+**CSS parts:** `row`, `toggle`, `icon`, `content`, `label`, `description`, `badge`, `group`. `icon` is
+`aria-hidden="true"`; `content` groups the primary label and optional wrapping secondary
+description while preserving one interactive treeitem per row.
+
+**Themeable custom properties:** `--lr-tree-depth` (internal, set inline per row for
+indentation), plus the shared tokens listed above.
+
+**Optional peer deps:** none.
+
+```html
+<lr-tree></lr-tree>
+<script>
+  document.querySelector('lr-tree').data = [
+    {
+      id: '1',
+      label: 'Root',
+      description: 'Two child documents',
+      accessibleLabel: 'Root, two child documents',
+      icon: document.createTextNode('◇'),
+      children: [{ id: '1a', label: 'Child A' }, { id: '1b', label: 'Child B', badge: 3 }],
+    },
+  ];
+</script>
+```
+
+**Known gotchas:**
+- all four previously-known ARIA gaps in this pair are fixed: the treeitem row is now genuinely
+  keyboard-operable with a roving tabindex and full arrow-key navigation (not just the expand/collapse
+  button); the expanded-children `role="group"` is now a real DOM descendant of its `role="treeitem"`
+  host rather than a shadow-DOM sibling; by-id reconciliation (preserving `expanded` state across
+  data reassignment) now applies at every depth via a keyed `repeat()`, not just depth 0; and
+  `role="tree"` now has an accessible name via the new `label` property.
+- `lr-tree`'s `getUpdateComplete()` cascades into every currently-known descendant
+  `<lr-tree-node>`'s own `updateComplete` (see `update-cascade.ts`) so that code awaiting the
+  tree's `updateComplete` (e.g. after `focusNode()`) doesn't run before an arbitrarily-nested node has
+  actually finished rendering its pushed-down `activeId`/`tabIndex` — one more pending update per
+  depth level, otherwise.
+- row enrichment is intentionally structured rather than an unrestricted renderer: use `icon`,
+  `label`, `description`, `badge`, 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 `TreeItem[]` is derived
+  from `nodes` on every render and keyed by filesystem path, an order it does not own.
+
+---

package/llms/components/lr-tree.md

@@ -0,0 +1,151 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/data.md — do not edit this file. -->
+
+# `lr-tree`
+
+- **Import** `import '@aceshooting/lyra-ui/components/data/tree/tree.js';` (registers the tag; side-effect import)
+- **Class** `LyraTree`, also available unregistered from `@aceshooting/lyra-ui/components/data/tree/tree.class.js`
+- **Family** `components/data/` — see `llms/index.md` for its siblings
+- **Optional peers** none
+- **Documented with** `lr-tree-node` (same section below)
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-tree` / `lr-tree-node`
+
+An expand/collapse hierarchy (document/graph navigation tree). `lr-tree` owns the data and
+imperatively creates/reconciles light-DOM `<lr-tree-node>` children by `id`; `lr-tree-node`
+recursively renders itself and its own nested children.
+
+### `lr-tree`
+
+Implements the full WAI-ARIA treeitem keyboard pattern: a single roving `tabindex` (tracked as
+`activeId`, pushed down to every `<lr-tree-node>` including nested ones) and
+ArrowUp/Down/Right/Left/Home/End/Enter/Space handled by one delegated `keydown` listener (native
+`KeyboardEvent`s are `composed: true` and bubble across shadow-DOM boundaries, so a press inside a
+deeply-nested node's own shadow root still reaches it).
+
+**Properties:**
+- `data: TreeItem[] = []` (attribute: false) — `TreeItem { id: string; label: string; children?:
+  TreeItem[]; badge?: string | number; icon?: unknown; description?: string; accessibleLabel?:
+  string }`; `icon` renders as a decorative leading visual, `description` as secondary visible row
+  text, and `accessibleLabel` names the `role="treeitem"` host without changing its visible label
+- `label: string = ''` — accessible name for the tree; `role="tree"` lives on an internal
+  `[part="base"]` element. The component forwards a host `aria-label` to that semantic element when
+  `label` is empty; `label` takes precedence when both are set. External `aria-labelledby` idrefs
+  are not forwarded across the shadow boundary.
+- `reorderable: boolean = false` (reflected) — opts into keyboard reordering. Unset, no `lr-reorder`
+  is ever emitted, Ctrl/Cmd+Arrow behaves exactly like a plain Arrow press, and the internal live
+  region is not rendered at all.
+
+**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
+child) or moves into an already-expanded node's first child. ArrowLeft collapses an expanded node, or
+moves focus to its parent. Home/End jump to the first/last visible node. Enter/Space activate
+`select()` on the focused node. While `reorderable`, **Ctrl/Cmd**+ArrowUp/ArrowDown moves the focused
+node within its own parent's child list instead of navigating. Ctrl/Cmd rather than Alt: Alt+Arrow is
+browser back/forward on Windows and Linux. ArrowUp/ArrowDown are not direction-sensitive, so this
+binding is deliberately **not** RTL-swapped — "down" always means later in the sibling list.
+
+**Methods:** `expandAll()`, `collapseAll()` (both recursive, properly sequenced around Lit's render
+cycle).
+
+**Events:** `lr-reorder` (`detail: { id, parentId, fromIndex, toIndex }`, only while `reorderable`).
+Like every other event here it is a **request**: `data` is host-owned and is never mutated by this
+component, so nothing moves until the host reassigns a reordered `data` — focus then follows the
+moved node. `parentId` is `null` for a top-level item, and `fromIndex`/`toIndex` are **sibling-scoped
+indices**, not positions in the flattened visible list. The move is constrained to one sibling list
+and never fires at a subtree boundary, so a reorder can never become a reparent: Ctrl+ArrowDown on
+the last child of a subtree is ambiguous (the visually next row is a top-level uncle, so "move down"
+could mean either "swap with the next sibling" — there is none — or "reparent up a level"), and
+reparenting is a structural edit with no keyboard affordance distinguishing the two. Such a request
+is simply not made: no event, no announcement, focus stays put. Otherwise this element dispatches
+nothing directly (see `lr-tree-node` below — those bubble up and are also observed internally to keep
+the roving `activeId` in sync with clicks).
+
+**Slots:** default (holds the `<lr-tree-node>` elements it manages).
+
+**CSS parts:** `base`, `empty` (the empty-state message shown when `data` is empty)
+
+**Themeable custom properties:** shared tokens `--lr-space-xs`/`-s`, `--lr-color-brand-quiet`,
+`--lr-color-text-quiet`, `--lr-color-border`, `--lr-color-text`, `--lr-radius`,
+`--lr-focus-ring-*` (row `:focus-visible` ring, driven by `:host(:focus-visible)` since the host
+itself is the focusable `role="treeitem"`).
+
+**Optional peer deps:** none.
+
+### `lr-tree-node`
+
+Normally set internally by `lr-tree`, but a public element. `role="treeitem"` (plus
+`aria-expanded`/`aria-level`/`aria-setsize`/`aria-posinset` 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 (rendered in its own shadow root as further `role="group"` content) are genuine DOM
+descendants of the treeitem, matching the WAI-ARIA treeitem pattern's containment expectation.
+
+**Properties:**
+- `item: TreeItem` (required, attribute: false)
+- `depth: number = 0`
+- `expanded: boolean = false` (reflected)
+- `activeId: string | null = null` (attribute: false) — the id of the tree's roving-tabindex-focused
+  item, pushed down from `<lr-tree>`; normally set internally, not by consumers
+- `setSize: number = 1`, `posInSet: number = 1` (attribute: false) — this node's `aria-setsize`/
+  `aria-posinset` values among its siblings, pushed down from `<lr-tree>`; normally set internally,
+  not by consumers
+- `hasChildren: boolean` (read-only getter) — reports whether `item.children` contains at least one
+  child; leaf nodes never expose `aria-expanded` and cannot expand or collapse
+
+**Methods:** `expand()`, `collapse()` (each a no-op if already in that state, or a leaf), `select()`
+(fires `lr-node-select`).
+
+**Events:** `lr-node-toggle` (`detail: { id, expanded }`, fired by `expand()`/`collapse()` — via
+the toggle button or ArrowRight/ArrowLeft), `lr-node-select` (`detail: { id }`, fired by `select()`
+— via clicking anywhere in the row or Enter/Space) — dispatched from `lr-tree-node`,
+bubble/compose up
+through `lr-tree`'s light DOM.
+
+**Slots:** none.
+
+**CSS parts:** `row`, `toggle`, `icon`, `content`, `label`, `description`, `badge`, `group`. `icon` is
+`aria-hidden="true"`; `content` groups the primary label and optional wrapping secondary
+description while preserving one interactive treeitem per row.
+
+**Themeable custom properties:** `--lr-tree-depth` (internal, set inline per row for
+indentation), plus the shared tokens listed above.
+
+**Optional peer deps:** none.
+
+```html
+<lr-tree></lr-tree>
+<script>
+  document.querySelector('lr-tree').data = [
+    {
+      id: '1',
+      label: 'Root',
+      description: 'Two child documents',
+      accessibleLabel: 'Root, two child documents',
+      icon: document.createTextNode('◇'),
+      children: [{ id: '1a', label: 'Child A' }, { id: '1b', label: 'Child B', badge: 3 }],
+    },
+  ];
+</script>
+```
+
+**Known gotchas:**
+- all four previously-known ARIA gaps in this pair are fixed: the treeitem row is now genuinely
+  keyboard-operable with a roving tabindex and full arrow-key navigation (not just the expand/collapse
+  button); the expanded-children `role="group"` is now a real DOM descendant of its `role="treeitem"`
+  host rather than a shadow-DOM sibling; by-id reconciliation (preserving `expanded` state across
+  data reassignment) now applies at every depth via a keyed `repeat()`, not just depth 0; and
+  `role="tree"` now has an accessible name via the new `label` property.
+- `lr-tree`'s `getUpdateComplete()` cascades into every currently-known descendant
+  `<lr-tree-node>`'s own `updateComplete` (see `update-cascade.ts`) so that code awaiting the
+  tree's `updateComplete` (e.g. after `focusNode()`) doesn't run before an arbitrarily-nested node has
+  actually finished rendering its pushed-down `activeId`/`tabIndex` — one more pending update per
+  depth level, otherwise.
+- row enrichment is intentionally structured rather than an unrestricted renderer: use `icon`,
+  `label`, `description`, `badge`, 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 `TreeItem[]` is derived
+  from `nodes` on every render and keyed by filesystem path, an order it does not own.
+
+---

package/llms/components/lr-typing-indicator.md

@@ -0,0 +1,80 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/conversation.md — do not edit this file. -->
+
+# `lr-typing-indicator`
+
+- **Import** `import '@aceshooting/lyra-ui/components/conversation/typing-indicator/typing-indicator.js';` (registers the tag; side-effect import)
+- **Class** `LyraTypingIndicator`, also available unregistered from `@aceshooting/lyra-ui/components/conversation/typing-indicator/typing-indicator.class.js`
+- **Family** `components/conversation/` — see `llms/index.md` for its siblings
+- **Optional peers** none
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-typing-indicator`
+
+A purely presentational "assistant is responding" presence cue — no events, no interactivity. A
+consumer mounts it while a response is being generated and removes (or hides) it once real content
+arrives. Three visual variants share one component rather than three separate tags, since callers
+pick between them along a single axis (how the surrounding surface wants the cue to read) and
+nothing else about the component differs: `dots` (default, three dots with a staggered bounce — the
+classic "typing…" affordance for a standalone status line), `pulse` (a single breathing dot, a
+quieter cue for a tight space, e.g. next to an avatar), `cursor` (a blinking vertical bar, meant to
+sit inline at the tail end of streamed text still being appended to).
+
+**Properties:**
+- `variant: TypingIndicatorVariant = 'dots'` (`'dots' | 'pulse' | 'cursor'`, reflected)
+- `label: string = 'Thinking…'` — the accessible name, exposed via `role="status"`; not re-announced
+  on every animation frame, only on mount and on any later change to this property
+- `size: TypingIndicatorSize = 'md'` (`'sm' | 'md'`, reflected) — compact sizing for dense layouts
+
+**Events:** none — purely presentational.
+
+**Slots:** none.
+
+**CSS parts:** `base` (the decorative, `aria-hidden`, wrapper around the animated shape), `dot`
+(each of the three dots in the `dots` variant), `pulse` (the single pulsing dot in the `pulse`
+variant), `cursor` (the blinking bar in the `cursor` variant)
+
+**Themeable custom properties:** `--lr-typing-dot-size` (default `0.5rem`, `0.375rem` at
+`size="sm"`), `--lr-typing-gap` (default `0.25rem`, `0.1875rem` at `size="sm"`),
+`--lr-typing-cursor-width` (default `0.125rem`, `0.09375rem` at `size="sm"`),
+`--lr-typing-cursor-height` (default `1em`, unaffected by `size`),
+`--lr-typing-dot-stagger-1` (default `600ms`, second dot), and
+`--lr-typing-dot-stagger-2` (default `1200ms`, third dot). Every variant uses the shared
+`--lr-transition-ambient` compound duration/timing token (default `1.8s ease-in-out`) as its
+animation cycle.
+
+**Optional peer deps:** none.
+
+```html
+<lr-typing-indicator label="Assistant is responding…"></lr-typing-indicator>
+<lr-typing-indicator variant="pulse" size="sm"></lr-typing-indicator>
+<lr-typing-indicator variant="cursor"></lr-typing-indicator>
+<lr-typing-indicator
+  style="--lr-transition-ambient: 900ms ease-in-out; --lr-typing-dot-stagger-1: 300ms; --lr-typing-dot-stagger-2: 600ms"
+></lr-typing-indicator>
+```
+
+Accessibility: since this indicator typically mounts and unmounts around a real generation lifecycle
+(appears when a response starts, disappears once one arrives) rather than emitting a stream of
+updates of its own, it does **not** route through `<lr-live-region>`/the internal `Announcer` —
+that machinery exists to coalesce many rapidly-changing announcements into one, and there is only
+ever a single announcement here: the mount itself. `role="status"` plus an accessible name derived
+from `label` is set both as `aria-label` on the host *and* as a visually-hidden text node
+(`.sr-only`) in the shadow tree, so the name survives even if only one of the two is picked up by a
+given assistive-tech/browser pairing. The animated shape itself is `aria-hidden="true"` — it's
+decorative; `label` is the entire accessible content, nothing narrates individual animation frames.
+
+**Known gotchas:**
+- under `prefers-reduced-motion: reduce`, every variant collapses to its plain, fully-visible resting
+  state (`opacity: 1`, no transform, `animation: none !important`) rather than freezing on whatever
+  frame the animation happened to be on — notably relevant for `cursor`, which would otherwise risk
+  freezing on its invisible ("off") blink half.
+- `--lr-transition-ambient` is a compound `duration timing-function` value and cannot be divided
+  with `calc()`. When retiming it, override both stagger properties alongside it to preserve the
+  default one-third/two-thirds dot phasing, as shown above.
+- `size="sm"` shrinks the dot size, gap, and cursor width, but **not** `--lr-typing-cursor-height`
+  (still `1em` at any size) — the cursor bar's height is meant to track surrounding text size via
+  `1em`, not the component's own `size` property.
+
+---

package/llms/components/lr-usage-badge.md

@@ -0,0 +1,44 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/conversation.md — do not edit this file. -->
+
+# `lr-usage-badge`
+
+- **Import** `import '@aceshooting/lyra-ui/components/conversation/usage-badge/usage-badge.js';` (registers the tag; side-effect import)
+- **Class** `LyraUsageBadge`, also available unregistered from `@aceshooting/lyra-ui/components/conversation/usage-badge/usage-badge.class.js`
+- **Family** `components/conversation/` — see `llms/index.md` for its siblings
+- **Optional peers** none
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-usage-badge`
+
+Compact, static resource strip for one message or run — tokens in/out, cost, latency — with a
+hover/focus tooltip breakdown. Purely formatting: computes no counts, rates, or prices; every segment
+is independently optional, and with nothing set, nothing renders at all (not even a focusable shell).
+The tooltip reuses `lr-tool-call-chip`'s hover/focus/Escape/`aria-describedby` contract wholesale.
+Not `lr-context-meter` (occupancy of a fixed capacity); not `lr-generation-status` (live, with a
+Stop button) — this is static after the fact.
+
+**Properties:** `tokensIn?: number` (attribute `tokens-in`) — input tokens, normalized to a
+non-negative integer, locale-formatted; segment omitted while unset/non-finite. `tokensOut?: number`
+(attribute `tokens-out`) — same rules. `costText: string = ''` (attribute `cost-text`) —
+pre-formatted cost (e.g. `"$0.012"`), rendered verbatim. `latencyMs?: number` (attribute
+`latency-ms`) — formatted with the shared duration algorithm (`820 -> "820ms"`, `1500 -> "1.5s"`), or
+`formatLatency` when set. `formatLatency?: (ms: number) => string` — overrides the built-in duration
+algorithm (which has no minutes/hours tier) in both the visible strip and the tooltip row; mirrors
+`lr-activity-feed`'s `formatTimestamp` convention. `compact: boolean = false` — token counts render
+via `Intl.NumberFormat` `notation: 'compact'`; the tooltip always shows full grouped figures.
+
+**Slots:** default — extra rows appended below the built-in tooltip breakdown (e.g. cache-read
+tokens); the visible strip itself is prop-driven only.
+
+**CSS parts:** `base` (a focusable non-button `role="group"`, only rendered while at least one
+segment or the default slot has content), `tokens-in`, `tokens-out`, `cost`, `latency`, `tooltip`.
+
+```html
+<lr-chat-message role="assistant" status="sent">
+  <lr-usage-badge slot="badges" tokens-in="1204" tokens-out="386"
+    cost-text="$0.012" latency-ms="2350"></lr-usage-badge>
+  <lr-markdown .content=${answer}></lr-markdown>
+</lr-chat-message>
+```