@aceshooting/lyra-ui 5.0.0 → 5.1.0

package/llms/components/lr-tour.md

@@ -0,0 +1,100 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/utility.md — do not edit this file. -->
+
+# `lr-tour`
+
+- **Import** `import '@aceshooting/lyra-ui/components/utility/tour/tour.js';` (registers the tag; side-effect import)
+- **Class** `LyraTour`, also available unregistered from `@aceshooting/lyra-ui/components/utility/tour/tour.class.js`
+- **Family** `components/utility/` — 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-tour`
+
+A spotlight-and-step guided walkthrough for first-run onboarding: each step anchors a popover to a
+target element elsewhere in the page via the shared Floating UI positioner, over a dimmed
+full-viewport backdrop with a cutout/ring around the current target, with Next/Previous/Skip
+controls and a step-progress indicator. Controlled component — `steps` is never mutated; only
+`activeIndex` and `open` are self-managed.
+
+**Properties:**
+- `open: boolean = false` (reflected) — no separate `show()`/`hide()`; set this or call
+  `start()`/`end()`
+- `steps: TourStep[] = []` (attribute: false) — empty renders nothing
+- `activeIndex: number = 0` (attribute `active-index`, reflected) — clamped to
+  `[0, steps.length - 1]`, including for a direct property/attribute write that bypasses
+  `goToStep()`
+- `placement: Placement = 'bottom'` (reflected) — tour-level Floating UI default, overridable per
+  step; resolved through `rtlAwarePlacement()`
+- `distance: number = 12` — px offset between target and popover. Tour-level only (no per-step
+  override); may be negative for overlap
+- `spotlightPadding: number = 4` (attribute `spotlight-padding`) — extra px between the target's box
+  and the cutout/ring; overridable per step
+- `lightDismiss: boolean = false` (attribute `light-dismiss`) — a deliberate inversion of
+  `lr-dialog`'s `noLightDismiss`: a backdrop click does **nothing** by default so a stray click
+  can't discard onboarding progress. Set it to make a backdrop click `end('skip')`
+- `showProgress: boolean = true` (attribute `show-progress`) — renders the "Step X of Y" text + dots
+- `aria-label` (a plain host attribute, not a public JS property) — names **every** step's popover,
+  overriding each step's own `heading` as the `aria-labelledby` source
+
+**Exported types:** `TourStep { id: string; target: TourTarget; heading: string; content?: string;
+placement?: Placement; spotlightPadding?: number; interactiveTarget?: boolean; hidePrevious?: boolean }`;
+`TourTarget = string | HTMLElement | (() => HTMLElement | null)` — a string resolves via
+`ownerDocument.querySelector` (top-level light DOM only), and every form is re-resolved on each step
+activation, never cached, so a target mounted later still resolves. `heading` is required and
+becomes the panel's accessible name; `content` renders as plain text (no HTML/markdown parsing).
+`TourEndReason = 'completed' | 'skip' | 'escape' | 'api' | 'unmount' | (string & {})`.
+
+**Methods:** `start(index = 0)` (clamps, opens, emits `lr-tour-start`), `next()` (on the last step
+ends with `'completed'` instead), `back()` (no-op on the first step), `goToStep(index)` (clamped),
+`skip()` (sugar for `end('skip')`), `end(reason: TourEndReason = 'api')`.
+
+**Events:** `lr-tour-start` (`detail: { index }`, not cancelable); `lr-tour-step-change`
+(`detail: { index, previousIndex, step, via: 'next'|'back'|'goto' }`, **cancelable** — fires before
+`activeIndex` changes, so `preventDefault()` gates advancement on a real action; a deliberate
+departure from `lr-carousel`'s non-cancelable `lr-slide-change`); `lr-tour-end`
+(`detail: TourEndReason`, cancelable except in practice for `'unmount'`, which is emitted when the
+element is removed while still open by something other than its own `end()`);
+`lr-tour-target-missing` (`detail: { index, step }`, informational — the tour does **not** auto-end,
+it renders that step viewport-centered with no spotlight).
+
+**Slots:** default — rich content replacing the active step's plain-text `content`. Not scoped per
+step: a consumer needing different rich content per step swaps the slotted children itself (e.g. on
+`lr-tour-step-change`).
+
+**CSS parts:** `backdrop` (the full-viewport `<svg>` scrim with the cutout, `aria-hidden`),
+`spotlight` (the decorative ring around the padded target rect, `pointer-events: none`),
+`popover` (the step panel, `role="dialog" aria-modal="true"`, `data-unanchored` when the target
+didn't resolve), `heading` (the `aria-labelledby` target), `body` (slot or `step.content`),
+`progress` (wrapper), `progress-text` (the "Step X of Y" text — an `aria-describedby` target),
+`progress-dot` (one decorative dot per step, `data-current` on the active one, `aria-hidden`),
+`footer` (the control row), `previous-button`, `skip-button`, `next-button` (the Next control's
+label switches to Done on the last step).
+
+**Themeable custom properties:** `--lr-tour-backdrop-color` (default `--lr-color-overlay`),
+`--lr-tour-spotlight-radius` (default `--lr-radius` — shared by the cutout and the ring),
+`--lr-tour-spotlight-ring-color` (default `--lr-color-brand`), `--lr-tour-spotlight-ring-width`
+(default `--lr-border-width-medium`), `--lr-tour-popover-max-width` (default `--lr-size-22rem`,
+further capped by `92vw` and the positioner's available space).
+
+**Known gotchas:**
+- By default the spotlighted target is **non-interactive**: it stays visible and announceable (not
+  `inert`, not `aria-hidden`) but every pointer event over the viewport is captured by the backdrop.
+  Set `step.interactiveTarget` to clip the backdrop around the target so clicks fall through — that
+  restores pointer reachability only. The focus trap still confines Tab to the popover regardless,
+  so for a keyboard-reachable demonstrated interaction have the app's own listener call `next()`.
+- Uses the overlay manager with `modal: false` deliberately: `modal: true` would mark the whole page
+  (including the target, which lives outside this element) `inert`. `role="dialog"` +
+  `aria-modal="true"` are still rendered on the panel so screen readers confine their virtual cursor.
+- Each step transition mounts a genuinely new popover node (keyed on `step.id`) so focus reliably
+  re-enters the panel — don't cache a reference to `[part="popover"]` across steps.
+- No `Home`/`End` shortcut and no click-to-jump progress dots (unlike `lr-stepper`): later steps may
+  depend on an earlier step's side effect having run. `goToStep()` is available for a caller that
+  knows better. ArrowRight/ArrowLeft do move between steps (swapped under RTL), except while focus
+  is in an `input`/`textarea`/`contenteditable` inside slotted content.
+- A direct `HTMLElement` target is re-checked for `isConnected` on every activation and treated as
+  missing if it was remounted — prefer a selector string or resolver function for targets that can
+  be replaced mid-tour.
+- The active step's target is `scrollIntoView({ block: 'center' })`'d on activation, smoothly unless
+  `prefers-reduced-motion: reduce`.

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

@@ -0,0 +1,35 @@
+<!-- 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`.

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,133 @@
+<!-- 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.
+
+**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.
+
+**Methods:** `expandAll()`, `collapseAll()` (both recursive, properly sequenced around Lit's render
+cycle).
+
+**Events:** none dispatched directly (see `lr-tree-node` below — they 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.
+
+---

package/llms/components/lr-tree.md

@@ -0,0 +1,133 @@
+<!-- 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.
+
+**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.
+
+**Methods:** `expandAll()`, `collapseAll()` (both recursive, properly sequenced around Lit's render
+cycle).
+
+**Events:** none dispatched directly (see `lr-tree-node` below — they 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.
+
+---

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>
+```