@aceshooting/lyra-ui 5.0.0 → 5.2.0

package/llms/components/lr-tabs.md

@@ -0,0 +1,91 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/layout.md — do not edit this file. -->
+
+# `lr-tabs`
+
+- **Import** `import '@aceshooting/lyra-ui/components/layout/tabs/tabs.js';` (registers the tag; side-effect import)
+- **Class** `LyraTabs`, also available unregistered from `@aceshooting/lyra-ui/components/layout/tabs/tabs.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-tabs`
+
+A tab strip whose panels are direct light-DOM children, each carrying `slot="<id>"` (the panel's
+stable id) and `label="<text>"` (the tab button's text). One named `<slot>` is rendered per distinct
+`slot` name found among the current children — a child with no `label`, or a name with no matching
+child, simply never produces a tab. Implements the WAI-ARIA APG tabs pattern with automatic
+activation: Left/Right (swapped under RTL) move focus *and* selection together, Home/End jump to the
+first/last enabled tab, and a roving `tabindex` follows whichever tab is currently selected.
+
+A tab button's *visible* content can carry a leading icon without ever changing its *accessible
+name* (always exactly `label`'s text): give a tab an extra direct-child sibling of `<lr-tabs>`
+carrying `slot="<id>-icon"` (that sibling's own content — inline SVG, emoji span, a custom icon
+element, anything — is entirely up to the consumer). It renders ahead of the label inside that tab's
+button, wrapped in an `aria-hidden="true"` `[part="tab-icon"]` so it's excluded from accessible-name
+computation regardless of content. A tab with no matching `<id>-icon` sibling renders no icon
+wrapper at all, so existing text-only tabs are unaffected.
+
+**Properties:**
+- `active: string = ''` (reflected) — the active tab's `slot`/id; falls back to the first enabled
+  tab whenever the current value doesn't resolve to one (including on every children/attribute
+  change, tracked via a `MutationObserver`)
+- `accessibleLabel: string | null = null` (attribute `aria-label`) — accessible name applied to the
+  `role="tablist"` 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-tabs-change` (`detail: { tabId: string }`) — fired when the active tab changes via
+click or keyboard. Not fired when `active` self-corrects to a valid tab (initial default, or a tab
+disappearing/becoming disabled underneath the current selection).
+
+**Slots:** default — direct children with `slot="<id>" label="<text>"` (and optionally `disabled`);
+one becomes each tab's panel. `<id>-icon` — optional sibling direct child supplying a tab's leading
+icon content; excluded from the tab button's accessible name.
+
+**CSS parts:** `base` (root wrapper around the tablist and panels), `tablist` (the `role="tablist"`
+row of tab buttons), `tab` (a single tab button), `tab-icon` (the optional leading-icon wrapper
+inside a tab button; only rendered when that tab has a matching `<id>-icon` sibling), `panel` (a
+single `role="tabpanel"` wrapper, one per tab, hidden unless active)
+
+**Themeable custom properties:** `--lr-scroll-fade-size` (default `2rem`) — width of the static
+mask fade at each horizontal scroll edge of the tablist. `--lr-tabs-selected-color` (default
+`var(--lr-color-brand)`) — text color of the selected tab, scoped to `[aria-selected='true']` only,
+so it never repaints a hovered unselected tab. `--lr-tabs-indicator-color` (default
+`var(--lr-color-brand)`) — the selected tab's underline, themeable independently of its text color.
+`--lr-tabs-hover-color` (default `var(--lr-color-text)`) — text color of a hovered, non-disabled
+tab, independent of the two selected-state hooks. All three are declared as inline `var()` fallbacks
+at the point of use rather than on `:host`, so each can be set on the element *or on any ancestor* —
+the pattern exists because `::part(tab)[aria-selected='true']` is invalid CSS (Shadow Parts forbids
+an attribute selector after `::part()`), which previously left overriding the library-wide
+`--lr-color-brand`/`--lr-color-text` tokens as the only way to restyle a selected or hovered tab,
+repainting everything else that reads them. Unset, each falls back to the token its rule used
+before, so rendering is unchanged. Otherwise shared tokens —
+`--lr-space-xs/-s/-m`, `--lr-color-border/-text-quiet/-text/-brand`, `--lr-transition-fast`,
+`--lr-radius`, `--lr-focus-ring-width/-color/-offset`, `--lr-opacity-disabled`.
+
+**Optional peer deps:** none.
+
+```html
+<lr-tabs active="general">
+  <div slot="general" label="General">General settings…</div>
+  <div slot="advanced" label="Advanced" disabled>Advanced settings…</div>
+</lr-tabs>
+<script type="module">
+  document.querySelector('lr-tabs').addEventListener('lr-tabs-change', (e) => console.log(e.detail.tabId));
+</script>
+```
+
+**Known gotchas:**
+- Tabs are rebuilt from direct children via a `MutationObserver` watching `childList` plus
+  `attributeFilter: ['slot', 'label', 'disabled']` — not `slotchange` — because a brand-new tab's
+  `slot` name has no matching `<slot>` to fire `slotchange` on until this component has already
+  rendered one for it, and neither `slotchange` nor any Lit lifecycle hook observes a plain
+  attribute edit on a light-DOM child at all.
+- If two children share the same `slot` name, the *first* one wins for the tab button's label
+  (matches native slot assignment: both would render into the one panel, but only one label can back
+  the button).
+- Left/Right are swapped under RTL (read via `internal/rtl.ts`'s `isRtl()`); Up/Down are not used —
+  this is a horizontal strip only.
+
+---

package/llms/components/lr-tag.md

@@ -0,0 +1,32 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/overlays.md — do not edit this file. -->
+
+# `lr-tag`
+
+- **Import** `import '@aceshooting/lyra-ui/components/overlays/badge/tag.js';` (registers the tag; side-effect import)
+- **Class** `LyraTag`, also available unregistered from `@aceshooting/lyra-ui/components/overlays/badge/tag.class.js`
+- **Family** `components/overlays/` — see `llms/index.md` for its siblings
+- **Optional peers** none
+- **Documented with** `lr-badge` (same section below)
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-badge` and `lr-tag`
+
+Compact status labels. Both expose `variant: 'neutral' | 'brand' | 'success' | 'warning' | 'danger'`
+and `size: '2xs' | 'xs' | 's' | 'm' | 'l' | 'xl' = 'm'` (reflected) — the same visual-density scale
+`<lr-chip>` uses, for typography/padding/minimum block size; `m` preserves the original badge
+dimensions. `lr-tag` inherits `size` unchanged from `lr-badge` rather than redeclaring it.
+The two tags share the same visual contract; `lr-tag` is a semantic alias for migration-friendly
+markup.
+
+**Slots:** default content. **CSS parts:** `base`.
+
+**Themeable custom properties:** `--lr-badge-background`, `--lr-badge-color`, `--lr-badge-border`
+— the trio each `:host([variant])` rule rewrites (`neutral` defaults to
+`--lr-color-surface`/`-text`/`-border`; the other four to the matching `*-quiet` fill with the loud
+color for text and border). Set one directly on the element for a tint outside the five variants.
+`--lr-badge-font-size` (default `var(--lr-font-size-sm)`), `--lr-badge-padding-inline` (default
+`var(--lr-space-s)`), and `--lr-badge-min-height` (default `var(--lr-size-1-25rem)`) — the density
+trio each `:host([size])` rule rewrites to that step's font size, inline padding, and minimum block
+size; the `m` defaults above exactly reproduce the pre-`size` fixed badge treatment.

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

@@ -0,0 +1,52 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/agent-tools.md — do not edit this file. -->
+
+# `lr-task-list`
+
+- **Import** `import '@aceshooting/lyra-ui/components/agent-tools/task-list/task-list.js';` (registers the tag; side-effect import)
+- **Class** `LyraTaskList`, also available unregistered from `@aceshooting/lyra-ui/components/agent-tools/task-list/task-list.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-task-list`
+
+A live, collapsible tracker for an agent's plan: ordered steps with per-step lifecycle status and one
+level of nested sub-steps, embedded in the transcript. `items` is controlled and never mutated by this
+component. Unlike `<lr-stepper>`'s single-`current` navigation, task-list is a read-only status
+report: several steps may be `running` at once, there is no selection, and status changes are
+announced through an internal `<lr-live-region>`.
+
+**Properties:** `items: TaskItem[] = []` (attribute: false) — `TaskItem { id: string; label: string;
+status: TaskStatus; detail?: string; children?: TaskItem[] }` with `TaskStatus = 'pending' |
+'running' | 'success' | 'error'` (both exported here). `detail` is an optional secondary plain-text
+line; `children` is exactly **one** level of sub-steps — a child's own `children` is ignored with a
+`console.warn`. `label: string = 'Tasks'`, `expanded: boolean = true` (reflected), and
+`collapsible: boolean = true`. `compact: boolean = false` (reflected) — tighter header/body padding
+and item gap for dense contexts (a plan tracker nested in an already-padded transcript row), same
+convention as `<lr-agent-run>`'s/`<lr-source-card>`'s `compact`; purely a density knob, the border
+and background stay. `appearance: 'card' | 'plain' = 'card'` (reflected) — mirrors `lr-card`'s
+`appearance` vocabulary; `'plain'` removes `[part="base"]`'s border, background, and corner radius so
+a list embedded in a frame that already draws a border (an agent-run panel, a message bubble) doesn't
+double it.
+
+**Slots:** `detail-<id>` — dynamic, one per item id (e.g. `slot="detail-step-3"`); rich detail under
+that item's label, typically a `<lr-tool-call-chip>` or file `<lr-chip>`.
+
+**Events:** `lr-toggle` — the header was activated, expanding or collapsing the panel. `detail: {
+expanded }`.
+
+**CSS parts:** `base`, `header` (a `<button>` when `collapsible`, a plain heading otherwise), `label`,
+`summary` (the visible "N of M completed" summary, top-level items only), `toggle` (the chevron
+indicator, only rendered when `collapsible`), `body` (the list of items, `hidden` while collapsed),
+`item` (`role="listitem"`; carries `data-status`/`data-id`/`data-depth`), `status-icon`, `item-label`,
+`item-detail`, and `item-children` (the nested `role="list"` wrapper around a top-level item's
+children).
+
+**Themeable custom properties:** `--lr-task-list-spin` (default `1s linear`) — running-status icon
+spin animation duration/timing; `--lr-task-list-compact-header-padding` (default
+`var(--lr-space-2xs) var(--lr-space-s)`) — `[part="header"]` padding while `compact`;
+`--lr-task-list-compact-gap` (default `var(--lr-space-2xs)`) — gap between `[part="body"]`'s item
+rows while `compact`; `--lr-task-list-compact-body-padding` (default `var(--lr-space-2xs)
+var(--lr-space-s) var(--lr-space-s)`) — `[part="body"]` padding while `compact`.

package/llms/components/lr-terminal.md

@@ -0,0 +1,56 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/agent-tools.md — do not edit this file. -->
+
+# `lr-terminal`
+
+- **Import** `import '@aceshooting/lyra-ui/components/agent-tools/terminal/terminal.js';` (registers the tag; side-effect import)
+- **Class** `LyraTerminal`, also available unregistered from `@aceshooting/lyra-ui/components/agent-tools/terminal/terminal.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-terminal`
+
+A read-only ANSI console for streamed agent/tool output. Not a PTY: no stdin/keystroke handling, no
+cursor-addressed full-screen apps.
+
+**Properties:** `content: string = ''` — initial/replaceable buffer content, parsed for ANSI/SGR
+codes. `maxScrollback: number = 5000` (attribute `max-scrollback`), `follow: boolean = true`
+(reflected) — stick-to-bottom, `wrap: boolean = true` (reflected), `copyable: boolean = true`
+(reflected) and `downloadable: boolean = false` (reflected) toggle the toolbar buttons, `filename:
+string = 'terminal.log'`, `announceOutput: boolean = false` (attribute `announce-output`),
+`accessibleLabel: string = ''` (attribute `aria-label`), `highlights: LyraHighlight[] = []` (attribute:
+false), and `activeHighlightId: string | null = null` (attribute: false). `anchorKinds` is a readonly
+`['page', 'text-quote', 'region']` for the shared anchor-target contract.
+
+**Methods:** `write(text)` appends ANSI-parsed text to the buffer. `clear()` empties the buffer.
+`scrollToBottom()` and `scrollToAnchor(anchor)` control scroll position. `search(query)`,
+`searchNext()`, `searchPrevious()`, and `clearSearch()` drive in-buffer text search. `getPlainText()`
+returns the SGR-stripped plain text of the whole buffer.
+
+**Events:** `lr-copy` (`detail: { text }`), `lr-download` (`detail: { filename }`),
+`lr-follow-change` (`detail: { following }`), `lr-search-change` (`detail: { query, matchCount,
+activeIndex }`), `lr-highlight-activate` (`detail: { id }`), and `lr-text-select` (`detail: {
+text, anchor, rects }`).
+
+**CSS parts:** `base`, `toolbar` (only rendered when copy/download are enabled), `copy-button`,
+`download-button`, `viewport` (the `role="log"` scrollable region), `line` (one rendered line; carries
+`data-line-number`/`data-match`/`data-highlight-tone`, and is forwarded via `exportparts` so
+`lr-terminal::part(line)` reaches the rendered lines from a consumer stylesheet despite them living
+in the internal `<lr-virtual-list>`'s shadow root), `jump-to-latest` (shown while `follow` is
+disengaged and new output has arrived), and `announcer` (the visually-hidden `role="status"` region
+used when `announce-output` is set).
+
+**Themeable custom properties:** `--lr-terminal-height` (default `var(--lr-size-20rem)`) — the
+viewport's block size; not declared on `:host`, so it is inherited from the host or any ancestor.
+`--lr-terminal-highlight-accent-bg` (default `var(--lr-color-brand-quiet)`),
+`--lr-terminal-highlight-success-bg` (default `var(--lr-color-success-quiet)`),
+`--lr-terminal-highlight-warning-bg` (default `var(--lr-color-warning-quiet)`),
+`--lr-terminal-highlight-danger-bg` (default `var(--lr-color-danger-quiet)`), and
+`--lr-terminal-highlight-neutral-bg` (default `var(--lr-color-surface)`) — the background of a
+`highlights[]` entry of the matching `tone`. Each is decoupled from the identical shared token it
+falls back to (e.g. `accent`'s `--lr-color-brand-quiet` is also the copy/download-button hover tint)
+so retinting one tone doesn't repaint the other surface reading that token, and from any
+`::part('line')` stylesheet override — the background is applied inline, so a stylesheet rule can't
+beat it without `!important`.

package/llms/components/lr-test-results.md

@@ -0,0 +1,49 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/agent-tools.md — do not edit this file. -->
+
+# `lr-test-results`
+
+- **Import** `import '@aceshooting/lyra-ui/components/agent-tools/test-results/test-results.js';` (registers the tag; side-effect import)
+- **Class** `LyraTestResults`, also available unregistered from `@aceshooting/lyra-ui/components/agent-tools/test-results/test-results.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-test-results`
+
+A pass/fail suite summary with per-status counts, status filter toggles, and per-test rows whose
+failures auto-expand by default and can host rich slotted detail (e.g. a diff or code block)
+alongside the plain failure message.
+
+**Properties:** `suites: TestSuiteResult[] = []` (attribute: false) — `TestSuiteResult { id: string;
+name: string; tests: TestCaseResult[] }` and `TestCaseResult { id: string; name: string; status:
+TestStatus; durationMs?: number; message?: string }`, with `TestStatus = 'passed' | 'failed' |
+'skipped' | 'running'` (all three exported here). `statusFilter: TestStatus[] =
+[]` (attribute: false) — empty shows every status; and `autoExpandFailures: boolean = true`
+(attribute `auto-expand-failures`).
+
+**Slots:** `detail-{testId}` — rich failure detail for that test, rendered after its plain `message`
+text once the row is expanded.
+
+**Events:** `lr-test-select` (`detail: { suiteId: string; testId: string }`, a test row's name was
+activated), `lr-filter-change` (`detail: { statuses: TestStatus[] }` — the complete next filter set; the
+component updates its own `statusFilter` first, then emits),
+and `lr-toggle` (`detail: { id: string; expanded: boolean }`, a row's failure detail was
+expanded/collapsed).
+
+**CSS parts:** `base`, `summary` (the status-count strip), `count` (carries `data-status`), `filter`,
+`filter-toggle` (carries `data-status`/`aria-pressed`), `suite`, `suite-header`, `test` (carries
+`data-status`), `test-status`, `test-name`, `test-duration`, `test-expand-toggle`, `failure`
+(hidden while collapsed), and `failure-message`.
+
+**Themeable custom properties:** `--lr-test-results-filter-active-bg` (default
+`var(--lr-color-brand-quiet)`), `--lr-test-results-filter-active-border` (default
+`var(--lr-color-brand)`) and `--lr-test-results-filter-active-color` (default
+`var(--lr-color-brand)`) — the background, border color and text color of a pressed (active) status
+filter toggle. All three follow the state-scoped-property convention described under
+`lr-span-waterfall`: inline `var()` fallbacks rather than `:host` declarations, so each can be set on
+the element or on any ancestor. They exist because
+`::part(filter-toggle)[aria-pressed='true']` is invalid CSS — Shadow Parts forbids an attribute
+selector after `::part()` — so restyling the pressed state otherwise meant overriding the
+library-wide brand tokens.

package/llms/components/lr-textarea.md

@@ -0,0 +1,111 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/forms.md — do not edit this file. -->
+
+# `lr-textarea`
+
+- **Import** `import '@aceshooting/lyra-ui/components/forms/textarea/textarea.js';` (registers the tag; side-effect import)
+- **Class** `LyraTextarea`, also available unregistered from `@aceshooting/lyra-ui/components/forms/textarea/textarea.class.js`
+- **Family** `components/forms/` — 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-textarea
+
+A multiline plain-text input primitive, form-associated (participates in native `<form>`
+submission/validation/reset via `name`/`value`/`disabled`/`required`/`checkValidity()`/
+`reportValidity()`). Ships an opt-in `label`/`hint`/`errorText` form-control chrome mirroring
+`lr-select` -- left unset, none of it renders.
+
+```html
+<lr-textarea placeholder="Notes" rows="4"></lr-textarea>
+```
+
+### Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `value` | `value` | `string` | `''` | The current text value. |
+| `rows` | `rows` | `number` | `3` | Visible text rows. |
+| `resize` | `resize` | `'none' \| 'vertical' \| 'both' \| 'auto'` | `'vertical'` | Native CSS `resize` behavior, plus `'auto'` (`ResizeObserver`-driven grow-to-content, no manual handle). |
+| `placeholder` | `placeholder` | `string` | `''` | Placeholder text. |
+| `label` | `label` | `string` | `''` | Visible label text. Unset: no label chrome renders. |
+| `hint` | `hint` | `string` | `''` | Hint text below the field. |
+| `errorText` | `error-text` | `string` | `''` | Error text below the field (overridden by slotted `error` content). |
+| `accessibleLabel` | `aria-label` | `string \| null` | `null` | Accessible-name override forwarded to the internal `<textarea>`; wins over `label`, `placeholder`, and the localized default. |
+| `spellcheck` | `spellcheck` | `boolean` | `true` | Forwarded to the native `<textarea>`. |
+| `autocapitalize` | `autocapitalize` | `string` | `''` | Forwarded to the native `<textarea>`; empty omits the attribute. |
+| `autoCorrect` | `autocorrect` | `string` | `''` | Forwarded to the native `<textarea>` (Safari/WebKit-specific); empty omits the attribute. |
+| `wrap` | `wrap` | `'hard' \| 'soft' \| 'off'` | `'soft'` | Native line-wrapping/submission behavior. |
+| `autocomplete` | `autocomplete` | `string` | `''` | Forwarded to the native `<textarea>`; empty omits the attribute. |
+| `inputMode` | `inputmode` | `string` | `''` | Virtual-keyboard input hint forwarded to the native `<textarea>`. |
+| `enterKeyHint` | `enterkeyhint` | `string` | `''` | Virtual-keyboard Enter-key hint forwarded to the native `<textarea>`. |
+| `name` | `name` | `string` | `''` | Form field name. |
+| `disabled` | `disabled` | `boolean` | `false` | Disables the control. |
+| `required` | `required` | `boolean` | `false` | Participates in native constraint validation. |
+
+The visible label, hint, and error live in the same shadow tree as the native control, so their
+generated ids safely drive the native `<label>`/`aria-describedby` relationships. Name precedence
+is `accessibleLabel`/host `aria-label`, visible `label`, `placeholder`, then the localized
+`textareaLabel` message. External `aria-labelledby`/`aria-describedby` idrefs are not copied across
+the shadow boundary.
+
+### Getters and selection properties
+
+- `input: HTMLTextAreaElement | null` — the internal native control.
+- `selectionStart: number | null`, `selectionEnd: number | null`, and
+  `selectionDirection: 'forward'|'backward'|'none'|null` — readable and writable passthroughs to
+  the native selection state.
+- The shared form-associated getters `form`, `labels`, `validity`, `validationMessage`,
+  `willValidate`, and `effectiveDisabled` are also available.
+
+### Methods
+
+| Method | Description |
+| --- | --- |
+| `focus(options?)` / `blur()` | Focus or blur the internal native control. |
+| `select()` | Select all text. |
+| `setSelectionRange(start, end, direction?)` | Set the native selection range and optional direction. |
+| `setRangeText(replacement, start?, end?, selectMode?)` | Apply a native range edit, then synchronize the component `value`, form value, validity, and auto-grown size without emitting a user event. |
+| `setFormValue(value)` | Set the reactive and submitted value synchronously. |
+| `checkValidity()` / `reportValidity()` | Run native constraint validation through `ElementInternals`. |
+
+### Events
+
+| Event | Detail | Description |
+| --- | --- | --- |
+| `lr-input` | `{ value: string }` | Fired on every user-driven edit. |
+| `lr-change` | `{ value: string }` | Fired on native `change` timing (blur after a committed edit). |
+| `blur` | none | Re-dispatched from the internal native `<textarea>`'s own `blur` -- bubbling and composed, unlike the native event. |
+| `focus` | none | Re-dispatched from the internal native `<textarea>`'s own `focus`, for the same reason as `blur`. |
+
+Programmatic property assignments, selection changes, `setRangeText()`, form reset, and form-state
+restoration are silent. User edits update `value`, submitted form data, and required validity before
+the corresponding `lr-input`/`lr-change` event is dispatched. `form.reset()` restores the
+original declarative `value`, matching native `defaultValue` behavior.
+
+### Slots
+
+| Slot | Description |
+| --- | --- |
+| `label` | Custom label content. |
+| `hint` | Custom hint content. |
+| `error` | Custom error content. |
+
+### CSS Parts
+
+| Part | Description |
+| --- | --- |
+| `form-control` | The outer wrapper around label, textarea, error and hint. |
+| `form-control-label` | The `<label>` element. |
+| `textarea` | The native `<textarea>` element. |
+| `hint` | The hint message. |
+| `error` | The error message. |
+
+### Themeable custom properties
+
+- `--lr-textarea-max-block-size` (default `none`) — bounds `resize="auto"`; content beyond the
+  bound scrolls inside the native textarea. Auto-resize remeasures after user edits, programmatic
+  `value`/`rows` changes, range edits, and container-width changes.
+
+---

package/llms/components/lr-thinking-panel.md

@@ -0,0 +1,93 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/agent-tools.md — do not edit this file. -->
+
+# `lr-thinking-panel`
+
+- **Import** `import '@aceshooting/lyra-ui/components/agent-tools/thinking-panel/thinking-panel.js';` (registers the tag; side-effect import)
+- **Class** `LyraThinkingPanel`, also available unregistered from `@aceshooting/lyra-ui/components/agent-tools/thinking-panel/thinking-panel.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-thinking-panel`
+
+A collapsible panel for an AI agent's intermediate reasoning/"thinking" transcript, kept visually
+and semantically distinct from its final response. First-party invention (no Web Awesome
+equivalent). Same collapsible header-button-plus-region shape as `<lr-source-list>`; the default
+slot is entirely free-form (a consumer-composed `<lr-streaming-text>`, `<lr-markdown>`, or
+plain text) — this component has no dependency on either.
+
+**Properties:**
+- `label: string = 'Thinking'`
+- `expanded: boolean = false` (reflected) — starts collapsed, matching `<lr-source-list>`'s
+  default.
+- `mode: 'live' | 'post-hoc' = 'live'` (reflected) — `'live'` while reasoning is actively streaming
+  in; `'post-hoc'` once it's complete and being reviewed after the fact. Drives two concrete
+  behavior differences, see prose below.
+- `durationMs?: number` (attribute `duration-ms`) — how long the reasoning took. Omitted entirely
+  (nothing rendered in `'post-hoc'`, a pulsing placeholder in `'live'`) while unset.
+
+**Methods:** `scrollToBottom(): void` — scrolls `[part="body"]` to its current bottom immediately
+(no smooth-scroll animation). Safe to call directly, e.g. from a host that wants to force a
+jump-to-latest action of its own.
+
+**Events:** `lr-toggle` (`detail: { expanded: boolean }`, same event name and shape as
+`<lr-source-list>`'s own `lr-toggle`) — fired whenever the header button is activated.
+
+**Slots:** default (the reasoning/thinking content; entirely free-form)
+
+**CSS parts:** `base`, `header`, `label`, `duration`, `toggle`, `body`
+
+**Themeable custom properties:** `--lr-thinking-panel-max-block-size` (default `16rem` —
+consumer-overridable cap on how tall `[part="body"]` grows before it scrolls internally; not
+exposed as a component property since it's a pure layout knob, not something a template branches
+on), plus shared `--lr-color-border`/`-surface`/`-text`/`-text-quiet`/`-brand`/`-brand-quiet`,
+`--lr-space-xs`/`-s`/`-m`, `--lr-radius`, `--lr-focus-ring-width`/`-color`/`-offset`,
+`--lr-transition-fast`/`-base`.
+
+**Optional peer deps:** none.
+
+```html
+<lr-thinking-panel label="Reasoning" mode="live" expanded>
+  <lr-streaming-text content="Considering the user's constraints…" streaming></lr-streaming-text>
+</lr-thinking-panel>
+
+<lr-thinking-panel label="Reasoning" mode="post-hoc" duration-ms="4200">
+  <p>Finished reasoning, collapsed by default.</p>
+</lr-thinking-panel>
+```
+
+`mode` drives two concrete behavior differences, not just a styling hook. **Header hint:** while
+`duration-ms` is unset, `'live'` shows a pulsing "Thinking…" placeholder in `[part="duration"]`;
+`'post-hoc'` shows nothing there. Once `duration-ms` is set, both modes show the same static
+"Thought for …" text. **Auto-scroll:** only `'live'` mode auto-follows new content appended to the
+default slot while `expanded`; `'post-hoc'` never scrolls on its own.
+
+Live-mode auto-scroll ("stick to bottom") is the classic chat-transcript convention: while
+`mode="live"` and `expanded`, new content keeps the panel scrolled to its latest line — unless the
+user has manually scrolled up to re-read earlier content (tracked via a `scroll` listener on
+`[part="body"]`: every user-driven scroll records whether the body was left within 48px of its own
+max scroll position, and only a mutation that arrives while that's still true triggers a follow-up
+scroll). Opening an already-`'live'` panel — or a still-`expanded` panel later becoming `'live'` —
+always resets this to "anchored" and jumps to the latest content. New content is detected via a `MutationObserver` on this element's own light DOM
+(`childList`+`subtree`+`characterData`), not `slotchange`, since streamed reasoning typically
+appends chunks to an existing node's `textContent` rather than re-slotting a whole new element per
+token; scroll-to-bottom calls are coalesced to at most one per animation frame under a fast token
+stream.
+
+**Known gotchas:**
+- The `MutationObserver` only watches this element's own light-DOM subtree — it cannot see a
+  mutation that happens entirely inside a slotted custom element's own shadow root (e.g. a
+  `<lr-markdown>` re-rendering its shadow tree after a `content` change). A slotted element whose
+  own internal updates should drive auto-scroll needs to append/mutate visible light-DOM text
+  itself (as `<lr-streaming-text>` does), or the host can call `scrollToBottom()` directly.
+- Either half of the pair can trigger the jump-to-bottom/reset-stickiness behavior, as long as the
+  *other* half already holds: an `expanded` transition to `true` while `mode` is already `'live'`,
+  **or** a `mode` transition to `'live'` while the panel is already `expanded`, both jump to the
+  bottom and reset stickiness. Only a change that leaves the panel in some other combination
+  (collapsed, or `mode !== 'live'`) skips it.
+- The sticky-bottom flag starts `true` internally, so a panel that mounts already `expanded` and
+  `mode="live"` follows its very first content mutation even before any `scroll` event has fired.
+
+---