@aceshooting/lyra-ui 4.2.0 → 5.1.0

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

@@ -0,0 +1,77 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/agent-tools.md — do not edit this file. -->
+
+# `lr-stack-trace`
+
+- **Import** `import '@aceshooting/lyra-ui/components/agent-tools/stack-trace/stack-trace.js';` (registers the tag; side-effect import)
+- **Class** `LyraStackTrace`, also available unregistered from `@aceshooting/lyra-ui/components/agent-tools/stack-trace/stack-trace.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-stack-trace`
+
+Parses common V8/JS-TS, Firefox/Safari, and Python stack traces into a leading message plus
+activatable frames, splitting chained/caused-by errors (`Caused by:`, `[cause]:`, Python's "direct
+cause"/"During handling" separators) into separate groups. Frames matching `internalPatterns` fold
+behind a count-labeled toggle. Falls back to verbatim raw text when nothing parses. First-party
+invention (no Web Awesome equivalent).
+
+**Properties:**
+- `trace: string = ''` — the raw stack trace text to parse and render.
+- `collapseInternal: boolean = true` (attribute: `collapse-internal`) — folds runs of internal
+  frames behind a toggle.
+- `internalPatterns: (string | RegExp)[] = DEFAULT_INTERNAL_PATTERNS` (attribute: false) —
+  file-path substrings/`RegExp`s that mark a frame as internal.
+- `copyable: boolean = true` — shows a copy-to-clipboard button for the raw trace text.
+- `maxHeight: string = ''` (attribute: `max-height`) — caps the rendered block size and enables an
+  internal scrollbar once content exceeds it (any valid CSS length). Empty string (the default)
+  grows with content.
+
+**Events:**
+- `lr-frame-select` (`detail: { file?: string; line?: number; column?: number; raw: string }`) —
+  a frame was activated. `column` is always undefined for Python frames, which carry no column
+  information.
+- `lr-copy` (`detail: { text: string }`) — the raw, unparsed trace text, fired on copy-button
+  activation regardless of whether the clipboard write actually succeeded.
+
+**Slots:** none.
+
+**CSS parts:** `base` (the root wrapper; respects `max-height`), `message` (the leading error
+message text for a group), `group` (one chained-error group of frames), `frame` (a single frame
+button; carries `data-internal` for internal frames), `frame-function` (the frame's function
+name), `frame-location` (the frame's `file:line:col` text), `internal-toggle` (the collapse/expand
+toggle for a run of internal frames), `raw` (the verbatim fallback when zero structured frames
+parsed), `copy-button` (only rendered while `copyable`).
+
+**Themeable custom properties:** `--lr-stack-trace-max-height` (default `none`),
+`--lr-stack-trace-font` (default `var(--lr-font-mono)`), plus shared tokens
+`--lr-color-border`/`-surface`/`-text`/`-text-quiet`/`-brand`, `--lr-radius`,
+`--lr-border-width-thin`, `--lr-space-xs`/`-s`/`-2xs`, `--lr-font-size-sm`/`-xs`,
+`--lr-font-weight-bold`/`-semibold`, `--lr-focus-ring-*`.
+
+**Optional peer deps:** none.
+
+```html
+<lr-stack-trace></lr-stack-trace>
+<script type="module">
+  const stackTrace = document.querySelector('lr-stack-trace');
+  stackTrace.trace = 'TypeError: boom\n    at doThing (/app/src/util.js:10:5)';
+  stackTrace.addEventListener('lr-frame-select', (e) => console.log(e.detail.file, e.detail.line));
+</script>
+```
+
+The package root also exports the pure `parseStackTrace(trace: string, internalPatterns: (string |
+RegExp)[]): StackGroup[]` helper (plus `DEFAULT_INTERNAL_PATTERNS`, and the `StackFrame`/
+`StackGroup` types) — the same parsing function this component's own `willUpdate()` calls, exposed
+standalone so a consumer can parse or unit-test traces without instantiating the element at all.
+
+**Known gotchas:**
+- an internal-frame run only collapses behind the `internal-toggle` when it is two or more
+  consecutive internal frames; a single isolated internal frame renders as a normal `frame` button
+  (there is nothing useful to fold).
+- when `trace` doesn't match any of the supported formats, `parseStackTrace()` returns `[]` and the
+  component renders the text verbatim in a `raw` part instead of silently dropping content.
+
+---

package/llms/components/lr-stat.md

@@ -0,0 +1,89 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/data.md — do not edit this file. -->
+
+# `lr-stat`
+
+- **Import** `import '@aceshooting/lyra-ui/components/data/stat/stat.js';` (registers the tag; side-effect import)
+- **Class** `LyraStat`, also available unregistered from `@aceshooting/lyra-ui/components/data/stat/stat.class.js`
+- **Family** `components/data/` — 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-stat`
+
+KPI/stat card — value + unit + label + optional icon/trend/caption.
+
+**Properties:**
+- `label: string = ''`
+- `value: string = ''`
+- `unit: string = ''`
+- `href?: string` — when it resolves to a safe URL, the root is a real whole-stat `<a>`; unsafe
+  URL schemes keep the stat non-interactive
+- `target?: string` / `rel?: string` — forwarded to the anchor while `href` is active
+- `variant: 'neutral'|'success'|'warning'|'danger' = 'neutral'` (reflected)
+- `trend: number = NaN` (a `NaN` sentinel hides the trend pill entirely — set an actual number to
+  show it)
+- `caption: string = ''`
+- `goodDirection: 'up'|'down' = 'up'` (attribute `good-direction`) — which trend direction counts
+  as "good"; inverts arrow/color polarity for cost/latency/error-rate-style metrics where a
+  *decrease* is the win.
+- `rows: StatRow[] = []` (attribute: false) — `StatRow { label: string; value: string; exactValue?:
+  string }`; rendered as a simple label/value breakdown list (`[part="rows"]`/`[part="row"]`/
+  `[part="row-label"]`/`[part="row-value"]`) beneath the caption, hidden entirely when empty. A row's
+  optional `exactValue` mirrors the headline `exactValue`/`exact-value` pattern: rendered as a `title`
+  tooltip on that row's `[part="row-value"]` and gives it `tabindex="0"`, independently per row —
+  unset rows are unaffected.
+- `emphasis: boolean = false` (reflected) — visual emphasis (e.g. for a "headline" stat in a group):
+  a brand-colored accent edge, orthogonal to the status `variant`; status semantics still win over
+  it — `emphasis` only additionally tints `[part="value"]` brand-colored when `variant` is still
+  `'neutral'`, never overriding an actual `success`/`warning`/`danger` value color
+- `exactValue: string = ''` (attribute `exact-value`) — rendered as a `title` attribute on
+  `[part="value"]` for a hover tooltip (e.g. `value="$1.2K" exact-value="$1,204.37"`); also gives
+  `[part="value"]` `tabindex="0"` (only when set) so the tooltip is reachable by keyboard focus, not
+  just hover
+- `sub: string = ''` — a secondary line distinct from `caption`, e.g. a comparison-period label,
+  rendered as `[part="sub"]` between the trend pill and the caption; hidden entirely when unset
+- `prose: boolean = false` (reflected) — CSS-only variant that shrinks/lightens `[part="value"]` and
+  hides `[part="unit"]`, for rendering a loading/status message in place of a numeric value
+- `compact: boolean = false` (reflected) — tighter card padding; same convention as `lr-empty`'s and
+  `lr-widget`'s `compact`
+
+**Events:** none.
+
+**Slots:** default (leading icon), `caption` (rich caption content — overrides the `caption`
+attribute when slotted content is provided), `spark` (a sparkline, e.g. `<lr-sparkline
+slot="spark">`, or other compact trend visual — `lr-stat` only reserves the slot and doesn't
+render one itself), `sub` (rich sub-line content — overrides the `sub` attribute when slotted content
+is provided)
+
+**CSS parts:** `base` (a `<div>`, or an `<a>` for a safe `href`), `icon`, `label`, `value-row`, `value`, `unit`, `trend`, `sub`, `spark`,
+`caption`, `rows`, `row`, `row-label`, `row-value` — `[part="value"]` gets `aria-labelledby` pairing
+it with `[part="label"]`'s generated id whenever `label` is non-empty (so tabbing straight to the
+`exactValue`-focusable value still announces e.g. "Revenue $1.2K", not just the bare value); each
+`[part="row-value"]` is paired the same way with its own row's `[part="row-label"]`.
+
+**Themeable custom properties:** shared tokens only (`--lr-color-success/-warning/-danger` drive
+the `variant`-colored value text and up/down trend pill; `--lr-color-brand` drives `emphasis`'s
+accent edge and value tint).
+
+**Optional peer deps:** none.
+
+```html
+<lr-stat label="Active users" value="1,204" trend="4.2" variant="success">
+  <svg slot="">...</svg>
+</lr-stat>
+<lr-stat label="Memories" value="128" href="/memories"></lr-stat>
+```
+
+**Known gotchas:**
+- When `href` makes the whole stat a link, exact-value spans keep their hover tooltips but omit
+  their own `tabindex` to avoid nesting focus targets inside the anchor.
+- no `aria-live` region wraps `value`/`trend` — an in-place update after first render still isn't
+  proactively announced to screen readers. The trend pill's direction/polarity is no longer
+  conveyed by icon rotation/color alone, though: a visually-hidden span now spells it out in plain
+  language (e.g. "increased 4.2%, good" / "decreased 2%, bad" / "unchanged"), so a screen reader
+  landing on the pill (rather than being live-notified of a change) gets the full meaning, not just
+  an `aria-hidden` arrow glyph.
+
+---

package/llms/components/lr-stepper.md

@@ -0,0 +1,118 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/layout.md — do not edit this file. -->
+
+# `lr-stepper`
+
+- **Import** `import '@aceshooting/lyra-ui/components/layout/stepper/stepper.js';` (registers the tag; side-effect import)
+- **Class** `LyraStepper`, also available unregistered from `@aceshooting/lyra-ui/components/layout/stepper/stepper.class.js`
+- **Family** `components/layout/` — 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-stepper`
+
+Ordered multi-step wizard/form navigation: an index/label per step, `current`/`completed`/`disabled`/
+`error` state, and click-to-jump. First-party invention (no Web Awesome equivalent). Fully
+data-driven and controlled, like `lr-table`'s `columns`/`rows` — it never mutates `steps` itself; a
+click, or Enter/Space on a non-disabled step, fires a cancelable `lr-step-select`, and the host
+decides whether/how `steps` changes in response (mirroring `lr-dialog-close`'s cancelable-event
+convention).
+
+**Properties:**
+- `steps: StepItem[] = []` (attribute: false) — `StepItem { id: string; label: string; state:
+  'pending' | 'current' | 'completed' | 'disabled' | 'error'; title?: string }`; `title` is an
+  optional native tooltip for the step's button (e.g. explaining why a `disabled` step is locked) —
+  omit it for no `title` attribute at all, not an empty string. Never mutated by this component.
+  Empty (the default) renders nothing.
+- `orientation: 'horizontal' | 'vertical' = 'horizontal'` (reflected) — `'horizontal'` (the default)
+  lays steps out in a row (Left/Right, RTL-aware, navigate); `'vertical'` stacks them (Up/Down
+  navigate instead, no RTL swap needed). The axis used at/above `orientationBreakpoint` (or always,
+  when that's unset).
+- `orientationBreakpoint?: number | string` (attribute `orientation-breakpoint`) — opt-in inline-size
+  breakpoint measured on `[part='base']`; unset (the default) means no behavior change at all, and
+  no `ResizeObserver` is armed. Below it, `narrowOrientation` becomes the effective axis instead of
+  `orientation`. Accepts a bare pixel number (`900`, `orientation-breakpoint="900"`) or a CSS length
+  string: `'900px'`, `'56.25rem'`, `'3em'`. Under the default `orientationBreakpointBasis='container'`,
+  `rem` resolves against the document root's **computed** font size (the rule a `@container` query
+  follows) and `em` against this element's own computed font size. The length is **re-resolved on
+  every measurement**, never cached at first render, so a root font-size change moves the crossing
+  width with no invalidation step on the consumer's side. Anything that isn't a resolvable length
+  behaves exactly as unset (no observation, no `data-effective-orientation`): `''`, `'auto'`,
+  garbage, a non-finite number, and deliberately `%`, `vw`/`vh` and `calc()` — a viewport-relative
+  threshold would mix reference boxes against a measurement of the element's own allocation. Mirrors
+  `<lr-split>`'s identically-named contract, unit handling included.
+- `orientationBreakpointBasis: 'container'|'viewport' = 'container'` (reflected, attribute
+  `orientation-breakpoint-basis`) — which box `orientationBreakpoint` is compared against. Unset,
+  behavior is identical to before this property existed. `'container'` measures the stepper's own
+  `[part='base']` via `ResizeObserver`, comparing strictly `<`; `'viewport'` evaluates
+  `matchMedia('(max-width: <breakpoint>)')`, arms no `ResizeObserver`, and compares inclusively
+  (`<=`) per native `max-width` semantics. **A stepper given a fixed width in a row layout cannot
+  react to that row stacking by measuring itself — its own width never changes — so that case
+  requires `'viewport'`.** Relative units also differ by basis: inside a media query they resolve
+  against the browser's *initial* font size, ignoring `html { font-size }`, which is precisely why
+  `'viewport'` matches a CSS `@media` rule authored with the same length. Mirrors `<lr-split>`'s
+  identically-named contract.
+- `narrowOrientation: 'horizontal' | 'vertical' = 'vertical'` (reflected, attribute
+  `narrow-orientation`)
+- `effectiveOrientation: 'horizontal' | 'vertical'` (readonly getter) — the live layout/navigation
+  axis actually in effect; identical to `orientation` whenever `orientationBreakpoint` is unset or
+  doesn't resolve to a length. Also reflected as `data-effective-orientation` (only present while
+  `orientationBreakpoint` resolves to a usable length).
+- `accessibleLabel: string | null = null` (attribute `aria-label`) — accessible name applied to the
+  `role="tablist"` step strip; attribute-reflects from a host-level `aria-label`. Unset, the
+  tablist renders without an `aria-label` (there is no localized default name).
+
+**Events:** `lr-step-select` (`detail: { index, id }`) — fired on click, or Enter/Space while
+focused, on a non-`disabled` step. Cancelable, though this component takes no default action of its
+own to prevent (it never mutates `steps`) — `preventDefault()` is available for a host that wants a
+single place to short-circuit its own listener's follow-up work. `lr-stepper-orientation-change`
+(`detail: { orientation }`) — fired only when an enabled `orientationBreakpoint` actually changes
+`effectiveOrientation`.
+
+**Slots:** none.
+
+**CSS parts:** `base` (root wrapper, `role="tablist"`), `step` (a single step button, `role="tab"`),
+`step-index` (the numbered index chip, shown for `pending`/`current`/`error` steps), `step-check`
+(the completed-checkmark glyph, shown for `completed` steps instead of `step-index`), `step-label`
+(the step's label text).
+
+**Themeable custom properties:** shared tokens only — `--lr-space-m`/`-xs`/`-2xs`,
+`--lr-color-text-quiet`/`-text`/`-danger`/`-brand`/`-surface`, `--lr-radius`/`-pill`,
+`--lr-font-size-xs`, `--lr-font-weight-semibold`, `--lr-opacity-disabled`,
+`--lr-focus-ring-*`.
+
+**Optional peer deps:** none.
+
+```html
+<lr-stepper></lr-stepper>
+<script type="module">
+  const stepper = document.querySelector('lr-stepper');
+  stepper.steps = [
+    { id: 'account', label: 'Account', state: 'completed' },
+    { id: 'billing', label: 'Billing', state: 'current' },
+    { id: 'review', label: 'Review', state: 'pending' },
+  ];
+  stepper.addEventListener('lr-step-select', (e) => console.log(e.detail.index, e.detail.id));
+</script>
+```
+
+**Known gotchas:**
+- `orientationBreakpointBasis='container'` (the default) observes **the stepper's own allocated
+  inline size**, so it fits a stepper that is the sole flex/grid item in its measured container. In
+  a row where the stepper is a fixed-width sidebar beside another element, its own width never
+  changes with the viewport at all, so no container breakpoint can react to that row stacking via a
+  CSS `@media` rule. Use `orientationBreakpointBasis='viewport'` for that layout — give the stepper
+  and its sibling the same `orientation-breakpoint` and both flip in lockstep with the CSS rule. See
+  `<lr-split>`'s own note above for the full explanation of why a shared row can't be inferred from
+  one element's measurement, and for a worked example.
+- there's no built-in "step forward/back" method — advancing the wizard is entirely the host's job:
+  react to `lr-step-select` (or its own Next/Back buttons) and reassign `steps` with updated
+  `state` values.
+- `role="tablist"`/`role="tab"` back the keyboard/focus contract (roving tabindex, arrow-key
+  navigation) even though this isn't a `<lr-tabs>`-style panel switcher — there's no associated
+  `role="tabpanel"`, since this component renders no panel content of its own.
+- Left/Right (horizontal) and Up/Down (vertical) are mutually exclusive per `orientation` — there's
+  no single set of keys that works in both.
+
+---

package/llms/components/lr-stream-status.md

@@ -0,0 +1,128 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/conversation.md — do not edit this file. -->
+
+# `lr-stream-status`
+
+- **Import** `import '@aceshooting/lyra-ui/components/conversation/stream-status/stream-status.js';` (registers the tag; side-effect import)
+- **Class** `LyraStreamStatus`, also available unregistered from `@aceshooting/lyra-ui/components/conversation/stream-status/stream-status.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-stream-status`
+
+A compact status indicator for a single streaming connection (SSE, WebSocket, long-poll, …), with
+built-in heartbeat-aware stall detection. First-party invention (no Web Awesome equivalent). The
+host drives `phase` directly for `idle`/`connecting`/`streaming`, and calls the imperative
+`recordActivity()` method on every *semantic* frame received while streaming — a real content
+chunk, never a transport-level keep-alive ping. This component has no payload-inspection logic of
+its own: "ignore heartbeats" is entirely call-site discipline, which is exactly why a connection
+that's only sending keep-alives (no real content) for longer than `stall-threshold-ms` correctly
+reads as stalled.
+
+**Properties:**
+- `phase: 'idle' | 'connecting' | 'streaming' | 'stalled' = 'idle'` (reflected) — current
+  connection phase. Fully public and directly settable by the host at any time, including a manual
+  override to `'stalled'`; the component never fights a host-driven reassignment.
+- `stallThresholdMs: number = 10000` (attribute `stall-threshold-ms`) — how long `phase` may stay
+  `'streaming'` with no `recordActivity()` call before the component auto-transitions to
+  `'stalled'`. A non-finite or `<= 0` value disables the stall timer entirely (arming becomes a
+  no-op, so the phase will never auto-stall). Changing this value while already `'streaming'`
+  re-arms the timer immediately against the new value, rather than waiting for the next
+  `recordActivity()` call or phase change.
+
+**Methods:**
+- `recordActivity(): void` — call on every semantic (non-heartbeat) frame received while
+  streaming.
+  - While `phase === 'streaming'`: (re)arms the stall timer, pushing the stall deadline
+    `stallThresholdMs` further out.
+  - While `phase === 'stalled'`: recovers — `phase` becomes `'streaming'` again (firing
+    `lr-recover` and arming the timer fresh, via the same transition handling a direct host
+    assignment would also go through).
+  - While `phase` is `'idle'` or `'connecting'`: a no-op. Safe to call defensively before formally
+    flipping to `'streaming'`; it never throws or starts a timer early.
+
+**Events:** `lr-stall` (no detail payload) — fires whenever `phase` transitions into `'stalled'`
+from any other phase, whether timer-driven or via a direct host assignment. `lr-recover` (no
+detail payload) — fires whenever `phase` transitions out of `'stalled'` to any other phase,
+whether via `recordActivity()` or a direct host assignment. Neither fires for a same-value
+reassignment, and neither fires for whatever phase the element happens to *mount* with — only a
+later change counts as a transition.
+
+**Slots:** default (custom copy shown only while `phase="stalled"`, e.g. "Taking longer than
+usual…" — falls back to a built-in default message when nothing is slotted), `actions` (a
+stop/retry button row; always present in the template regardless of `phase` — its wrapper's
+visibility is driven purely by whether anything is slotted into it, not by `phase`)
+
+**CSS parts:** `base`, `indicator`, `message`, `actions`
+
+**Themeable custom properties:** shared tokens only — `--lr-color-text-quiet` (idle dot color),
+`--lr-color-brand` (connecting/streaming dot color), `--lr-color-warning` (stalled dot color,
+message text color, stalled border), `--lr-color-warning-quiet` (stalled background tint),
+`--lr-space-s` / `--lr-space-xs` (base gap, stalled padding, actions gap), `--lr-radius`
+(base corner radius), `--lr-transition-base` (background/border-color transitions and the
+streaming pulse animation's cycle length). The component also sets two internal, phase-driven
+custom properties (`--lr-stream-status-dot-color`, `--lr-stream-status-dot-opacity`) on
+`:host`, but its own `:host([phase="..."])` rules outrank a page-level override for every phase
+except the default `idle`, so these aren't a practical external theming hook.
+
+**Optional peer deps:** none.
+
+```html
+<lr-stream-status phase="streaming" stall-threshold-ms="8000">
+  <span slot="actions"><button>Stop</button></span>
+</lr-stream-status>
+```
+```ts
+const status = document.querySelector('lr-stream-status')!;
+status.addEventListener('lr-stall', () => console.warn('stream stalled'));
+status.addEventListener('lr-recover', () => console.info('stream recovered'));
+
+// on every real content chunk from the transport (never on a keep-alive ping):
+status.recordActivity();
+```
+
+Internally, the inactivity timer runs only while `phase === 'streaming'`. It's (re)armed whenever
+the phase transitions to `'streaming'` (directly, or via `recordActivity()` recovering from
+`'stalled'`) and on every subsequent `recordActivity()` call while already streaming; it's disarmed
+the instant `phase` becomes anything else, including a host-driven reassignment away from
+`'streaming'` — so a stale timer can never fire a stall transition after the host has already moved
+on. Phase transitions into/out of `'stalled'` are announced through an internal
+`<lr-live-region>` rather than a hand-rolled `aria-live` region: entering `'stalled'` announces
+"Connection stalled." with `mode="assertive"` (a stall can need the user's attention before they
+give up and navigate away). Leaving `'stalled'` always announces with `mode="polite"` (good news
+doesn't need to interrupt), but the *wording* depends on the destination phase: "Connection
+restored." only when leaving `'stalled'` for `'streaming'` (a genuine recovery, typically via
+`recordActivity()`); a neutral "No longer stalled." when the destination is `'idle'`/`'connecting'`
+instead (the host gave up on the stream, which is not the same thing as it recovering — a
+screen-reader user must not be told the opposite of what a sighted user sees). Calling
+`recordActivity()` itself never announces anything, no
+matter how often the host calls it — only the phase *transition* announces, exactly once. The
+decorative indicator dot is `aria-hidden` (a color/motion cue only) and only pulses while
+`phase="streaming"`; `'stalled'` is styled as a warning tone, not danger, since a stall is usually
+recoverable — a host that wants to escalate after N stalls can scope its own CSS off
+`[phase="stalled"]`, or stop rendering this component and show its own danger-styled error state
+instead. The pulse animation is suppressed under `prefers-reduced-motion: reduce`.
+
+**Known gotchas:**
+- `recordActivity()` is a plain instance method, not a reactive property — there's nothing to bind
+  to in a template; call it directly from streaming/application code on every real chunk received.
+- Never call `recordActivity()` for a heartbeat/keep-alive ping. This component has no
+  payload-inspection logic of its own, so a connection that's only sending pings (no real content)
+  for longer than `stall-threshold-ms` is *supposed* to read as stalled — that's the entire
+  point of the API.
+- Setting `stallThresholdMs` to `0`, a negative number, or a non-finite value disables the stall
+  timer outright; the component will stay `'streaming'` forever until the host manually changes
+  `phase`.
+- `phase` remains directly settable at all times; assigning `'stalled'` yourself fires `lr-stall`
+  and the assertive announcement exactly as if the timer had fired.
+- reconnecting the element while still `phase === 'streaming'` (e.g. a drag-and-drop reparent that
+  keeps the same instance) automatically re-arms the stall timer in `connectedCallback` —
+  `disconnectedCallback` always disarms it, and disconnect/reconnect fire back-to-back with no
+  `updated()` cycle in between, so nothing else would otherwise notice.
+- The `actions` slot's wrapper is always present in the DOM and toggled with the `hidden` attribute
+  based on slotted content, not gated by `phase` — content placed there is visible regardless of
+  the current phase.
+
+---

package/llms/components/lr-streaming-text.md

@@ -0,0 +1,101 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/conversation.md — do not edit this file. -->
+
+# `lr-streaming-text`
+
+- **Import** `import '@aceshooting/lyra-ui/components/conversation/streaming-text/streaming-text.js';` (registers the tag; side-effect import)
+- **Class** `LyraStreamingText`, also available unregistered from `@aceshooting/lyra-ui/components/conversation/streaming-text/streaming-text.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-streaming-text`
+
+A token-coalescing incremental text renderer for streaming assistant output, with an optional
+blinking cursor and auto-detected Markdown rendering. First-party invention (no Web Awesome
+equivalent). The host is expected to assign the *entire* current text on every update to `content`,
+not a delta — this component does no accumulation or ordering of its own.
+
+**Properties:**
+- `content: string = ''` — the full current text so far.
+- `streaming: boolean = false` (reflected) — shows the blinking cursor after the rendered text;
+  reflects so a host can also target `lr-streaming-text[streaming]` in CSS.
+- `coalesceMs: number = 50` (attribute `coalesce-ms`) — trailing-edge coalesce window, in ms, for
+  `content` updates (see prose below).
+- `markdown?: boolean` (attribute `markdown`, tri-state via a custom `ComplexAttributeConverter`) —
+  `undefined` (attribute absent, the default) auto-detects via `looksLikeMarkdown`; the attribute
+  present with no value or `="true"` forces `true`; `markdown="false"` forces `false`. An explicit
+  `true`/`false` always wins over the heuristic.
+
+**Exported helper:** `looksLikeMarkdown(text: string): boolean` — runs a fixed, ordered list of
+lightweight regexes (ATX heading, fenced code block, `**bold**`, `_italic_`, inline code, bullet
+list item, numbered list item, `[text](url)` link, blockquote) against the whole string and returns
+`true` on the first match. Used internally whenever `markdown` is left unset; exported standalone
+so the heuristic is directly testable without going through the component's render cycle. None of
+the patterns need to be airtight — a false positive just routes ordinary prose harmlessly through
+`<lr-markdown>`; a false negative just shows literal `**`/backticks/etc. as plain text until more
+of the stream arrives.
+
+**Events:** none.
+
+**Slots:** none — content renders from `content`, not a slot.
+
+**CSS parts:** `base`, `cursor` (only rendered while `streaming` is `true`)
+
+**Themeable custom properties:** `--lr-streaming-text-cursor-width` (default `0.125rem` — the
+cursor bar's inline size), `--lr-streaming-text-cursor-height` (default `1em`) — both
+component-specific, since no shared "inline cursor bar" token exists, the same pattern
+`<lr-typing-indicator>`'s own `--lr-typing-cursor-width`/`-height` use, plus shared
+`--lr-space-xs` (cursor's `margin-inline-start`) and `--lr-transition-base` (blink animation
+cycle length).
+
+**Optional peer deps:** none — internally imports and auto-registers `<lr-markdown>` for
+Markdown-mode rendering (a side-effect import; the host never needs to import or register it
+itself).
+
+```html
+<lr-streaming-text id="out" coalesce-ms="80" streaming></lr-streaming-text>
+<script type="module">
+  const out = document.getElementById('out');
+  let text = '';
+  for await (const token of tokenStream) {
+    text += token;
+    out.content = text; // always the full string so far, never a delta
+  }
+  out.streaming = false; // forces the final chunk through immediately; cursor disappears
+</script>
+```
+
+Token-by-token streaming can update `content` far faster than a human can usefully perceive a
+re-render, so updates funnel through `Announcer` (`../../internal/announcer.js`), reused here
+purely as a generic "coalesce rapid calls, flush the latest" timing primitive — with none of that
+class's usual DOM/ARIA plumbing. Within any `coalesce-ms` window, only the *last* `content` value
+assigned actually reaches the rendered DOM. Two cases always bypass the throttle and flush
+immediately: the very first `content` assignment after mount, and any transition of `streaming`
+between `true` and `false` in *either* direction — so the final chunk of a finished stream can
+never be left stranded mid-window, and a stream restarting on a reused element can never keep
+showing the previous stream's stale final content for the length of the window.
+
+Rendering itself is never reimplemented here: Markdown mode composes `<lr-markdown>` directly,
+forwarding this component's own `streaming` through as that component's `streaming` hint prop;
+plain-text mode renders into a `white-space: pre-wrap` span instead. The blinking cursor degrades
+to a static, always-visible bar under `prefers-reduced-motion: reduce`. In plain-text mode it sits
+inline at the tail of the final character; in Markdown mode it renders as its own trailing block
+below the rendered content instead of attempting to splice into whatever nested block Markdown
+happens to end with.
+
+**Known gotchas:**
+- `content` must always be the complete string so far, never a delta — this component does no
+  accumulation of its own.
+- Only the very *first* `content` assignment after mount bypasses `coalesceMs` unconditionally —
+  every later assignment is throttled normally except when it lands in the same update as a
+  `streaming` transition (either `true → false` or `false → true`), which also forces an immediate
+  flush.
+- `markdown="false"` (any string value other than exactly `"false"` is treated as `true` by the
+  converter) forces plain-text mode even if the text obviously contains Markdown syntax.
+- Purely presentational: no events, and it does not announce anything to assistive tech itself — a
+  host that needs streamed text announced needs `<lr-live-region>` for that (e.g. composed inside
+  `<lr-chat-message>`).
+
+---

package/llms/components/lr-suggestion-chips.md

@@ -0,0 +1,40 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/conversation.md — do not edit this file. -->
+
+# `lr-suggestion-chips`
+
+- **Import** `import '@aceshooting/lyra-ui/components/conversation/suggestion-chips/suggestion-chips.js';` (registers the tag; side-effect import)
+- **Class** `LyraSuggestionChips`, also available unregistered from `@aceshooting/lyra-ui/components/conversation/suggestion-chips/suggestion-chips.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-suggestion-chips`
+
+Starter prompts (empty thread) and follow-up suggestions (after a response) as a horizontally
+scrollable chip row; activation hands the prompt to the host, which decides whether to compose it
+into an input or send it directly. Never writes into a composer or sends anything itself.
+Streaming-friendly: chips render through a keyed `repeat()` on `id`, so replacing follow-ups
+mid-conversation preserves focus on any chip whose `id` survives.
+
+**Properties:** `suggestions: ChatSuggestion[] = []` (attribute: false) — `ChatSuggestion { id:
+string; label: string; detail?: string }` (exported here); `detail` is an optional secondary line.
+Empty renders nothing at all. `wrap: boolean = false`
+(reflected) — wraps into multiple rows instead of a single horizontally scrollable line. `label:
+string = ''` — accessible name for the group, defaults to the localized `suggestionsLabel`.
+
+**Events:** `lr-suggestion-select` — `detail: { id, label }`.
+
+**CSS parts:** `base` (the labeled group), `chip` (each suggestion button), `chip-label` (the primary
+text), `chip-detail` (the secondary line, only rendered when `detail` is set).
+
+Keyboard: roving tabindex across chips; ArrowLeft/ArrowRight (direction-aware) plus Home/End;
+Enter/Space activate. Renders inside an internal `lr-scroller` (`orientation="horizontal"`,
+`hide-scrollbar`) unless `wrap` is set.
+
+```html
+<lr-suggestion-chips .suggestions=${followUps}
+  @lr-suggestion-select=${(e) => (composer.value = e.detail.label)}></lr-suggestion-chips>
+<lr-chat-composer></lr-chat-composer>
+```

package/llms/components/lr-svg-viewer.md

@@ -0,0 +1,47 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/viewers.md — do not edit this file. -->
+
+# `lr-svg-viewer`
+
+- **Import** `import '@aceshooting/lyra-ui/components/viewers/svg-viewer/svg-viewer.js';` (registers the tag; side-effect import)
+- **Class** `LyraSvgViewer`, also available unregistered from `@aceshooting/lyra-ui/components/viewers/svg-viewer/svg-viewer.class.js`
+- **Family** `components/viewers/` — see `llms/index.md` for its siblings
+- **Optional peers** `dompurify` — see `llms/peers.md`
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-svg-viewer`
+
+Fetches an SVG document, sanitizes it with the optional `dompurify` peer, and renders it inline.
+
+**Properties:** `src`, `name`, and `maxHeight` (attribute `max-height`) are strings. `maxHeight` caps
+the scrollable body. `zoomable: boolean = false` (reflected) — wraps the rendered content in an
+internal `<lr-zoomable-frame>`. `false` (the default) preserves the exact pre-`zoomable` DOM — an
+inline thumbnail (e.g. in a chat stream) must not unexpectedly grow a focusable zoom-chrome viewport;
+an inspection surface opts in. `highlights: LyraHighlight[] = []` (attribute: false) — display-only
+`region` highlights painted over the rendered SVG. `activeHighlightId: string | null = null`
+(attribute `active-highlight-id`) — the `highlights` entry, if any, currently treated as active
+(`data-active` on its `region-highlight`). `anchorKinds` is a readonly `['region']` (this viewer's
+supported `LyraAnchor.kind` values for the shared anchor-target contract).
+
+**Methods:** `scrollToAnchor(target)` — scrolls a `region` highlight (by id, or a `LyraAnchor` matched
+back to its owning `LyraHighlight` by reference) into view; resolves `false` when nothing matches, the
+anchor isn't `region`, or the document isn't loaded yet (no retry loop — a caller invoking this before
+`src` resolves simply gets `false`).
+
+**Events:** `lr-render-error` with `detail.error` when fetching or sanitizing fails.
+`lr-highlight-activate` (`detail: { id }`) — a region highlight was clicked or activated via
+Enter/Space.
+
+**CSS parts:** `base`, `body`, `svg`, `spinner`, `error`, `highlight-layer` (wrapper around every
+rendered region highlight), `region-highlight` (one region highlight, `data-tone`, `data-active`),
+`frame-viewport`/`frame-content`/`frame-controls`/`frame-zoom-in`/`frame-zoom-out`/`frame-reset`
+(forwarded from the internal `<lr-zoomable-frame>` while `zoomable`).
+
+**Themeable custom properties:** `--lr-svg-viewer-max-height` (default `none`) — maximum block size
+of `[part="body"]`; also settable via the `max-height` property, which writes this token inline.
+
+**Optional peer dependency:** `dompurify`.
+
+Remote resources are capped at 25 MB; exceeding it surfaces the localized
+`documentPreviewResourceTooLarge` message instead of the graphic.