@aceshooting/lyra-ui 5.0.0 → 5.2.0

package/llms/components/lr-toast.md

@@ -0,0 +1,123 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/overlays.md — do not edit this file. -->
+
+# `lr-toast`
+
+- **Import** `import '@aceshooting/lyra-ui/components/overlays/toast/toast.js';` (registers the tag; side-effect import)
+- **Class** `LyraToast`, also available unregistered from `@aceshooting/lyra-ui/components/overlays/toast/toast.class.js`
+- **Family** `components/overlays/` — see `llms/index.md` for its siblings
+- **Optional peers** none
+- **Documented with** `lr-toast-item` (same section below)
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-toast` / `lr-toast-item` / `toast()`
+
+Stacking toast/notification region. Mirrors `<wa-toast>`/`<wa-toast-item>` under `lr-`.
+
+### `lr-toast`
+
+One per page recommended — the region.
+
+**Properties:**
+- `placement: ToastPlacement = 'top-end'` (reflected) — one of `'top-start'|'top-center'|'top-end'|
+  'bottom-start'|'bottom-center'|'bottom-end'`
+
+**Methods:** `async create(message: string, options?: ToastCreateOptions): Promise<LyraToastItem>` —
+`ToastCreateOptions = { variant?, duration?, size?, withIcon? }`
+
+**Events:** none.
+
+**Slots:** default (`<lr-toast-item>` children)
+
+**CSS parts:** `stack`
+
+**Themeable custom properties:** `--lr-toast-gap` (default `var(--lr-space-s)`),
+`--lr-toast-width` (default `28rem`) — set directly on the `<lr-toast>` element.
+
+**Optional peer deps:** none.
+
+### `lr-toast-item`
+
+A single notification.
+
+**Properties:**
+- `duration: number = 5000` (ms; `Infinity` or `<= 0` disables auto-dismiss)
+- `size: 'xs'|'s'|'m'|'l'|'xl' = 'm'` (reflected — drives both `--lr-toast-padding` and the toast's own
+  font-size via `:host([size=...])`, from a compact `xs` up to a roomier `xl`)
+- `variant: 'brand'|'success'|'warning'|'danger'|'neutral' = 'neutral'` (reflected)
+- `withIcon: boolean = false` (attribute `with-icon`)
+
+**Methods:** `async hide(): Promise<void>` — plays the hide animation, then removes itself from the
+DOM.
+
+**Events:** `lr-show`, `lr-after-show`, `lr-hide`, `lr-after-hide`
+
+**Slots:** default (message), `icon`
+
+**CSS parts:** `toast-item`, `accent`, `icon`, `content`, `close-button`
+
+**Themeable custom properties:** `--lr-toast-accent-width` (4px),
+`--lr-toast-show-duration`/`--lr-toast-hide-duration`
+(`var(--lr-transition-base, 180ms ease-out)` — 180ms by default, matching the JS-side show/hide
+animation timer, which is not itself reading this token), `--lr-toast-padding`
+(`var(--lr-space-m)`), `--lr-toast-font-size` (`1rem`) — both are auto-swapped per `size`, from a
+compact `xs` up to a roomier `xl` — `--lr-toast-accent-color` (defaults to `--lr-color-border`,
+auto-swapped per `variant` to `--lr-color-brand/-success/-warning/-danger`).
+
+**Optional peer deps:** none.
+
+`role` is chosen automatically per `variant`: `"alert"` for `danger`/`warning`, `"status"`
+otherwise — re-evaluated on every `variant` change, not just at first render, so reassigning
+`variant` to `danger`/`warning` after creation is announced as an interruption instead of keeping
+its original, now-stale role. Auto-dismiss timer **pauses** on `pointerenter`/`focusin`, **resumes**
+on `pointerleave`/`focusout`, with real elapsed-time bookkeeping (WCAG 2.2.1 timing-adjustable) —
+hover and focus are tracked as independent pause reasons, so releasing only one (e.g. the pointer
+leaves while focus remains, or vice versa) keeps the timer paused until *neither* holds it anymore.
+A `duration` change while the timer is actively counting down reschedules it immediately against
+the new value instead of waiting for the next pause/resume cycle.
+
+### `toast()`
+
+From the `toaster` controller — the ergonomic entry point, no manual `<lr-toast>` mounting
+needed:
+
+```ts
+import { toast } from '@aceshooting/lyra-ui';
+
+toast('Saved');
+toast({ message: 'Deleted', variant: 'danger', action: { label: 'Undo', onClick: (item) => {/*...*/} } });
+```
+
+`toast(input: ToastOptions | string): ToastHandle` where
+`ToastOptions = ToastCreateOptions & { message: string; placement?: ToastPlacement; action?: { label: string; onClick: (item: LyraToastItem) => void } }`,
+and `ToastHandle = { item: Promise<LyraToastItem>; dismiss: () => void }`. Lazily mounts (and
+re-mounts if removed) **one singleton `<lr-toast>` region per distinct `placement`** on
+`document.body` — a `toast()` call targeting one placement never relocates toasts already showing
+at another, since `placement` is a per-call option rather than a single global region's setting.
+
+```html
+<script type="module">
+  import { toast } from '@aceshooting/lyra-ui';
+  document.getElementById('save-btn').addEventListener('click', () => toast('Saved!'));
+</script>
+```
+
+**Known gotchas:**
+- possible nested live-region double-announcement: the stack region is
+  `role="status" aria-live="polite"` **and** each `lr-toast-item` independently self-assigns its
+  own `role` (`status`/`alert`) — nesting live regions can cause some screen readers to announce a
+  new toast twice. Plausible from the code, unverified against real AT.
+- the close button's accessible name is derived from the toast's own message text (`"Close: <first
+  40 chars>…"`, falling back to bare `"Close"` only when the toast has no text content) rather than
+  a bare `"Close"` on every instance — useful when several toasts are stacked and a screen-reader or
+  switch-access user needs to tell their close buttons apart without activating one first.
+- pause/resume-on-hover/focus (the component's main accessibility differentiator), including the
+  independent-hover-vs-focus pause reasons above, now has regression test coverage.
+- `hide()` is idempotent (a second call while already hiding is a no-op) and `[part="close-button"]`
+  gets `aria-disabled="true"` once hiding starts, so a stray extra click/Enter during the hide
+  animation can't re-enter it.
+- Prefer the `toast()` helper over manually creating `<lr-toast>`/`<lr-toast-item>` — it already
+  handles the singleton-region and remount-if-removed logic.
+
+---

package/llms/components/lr-token-input.md

@@ -0,0 +1,58 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/forms.md — do not edit this file. -->
+
+# `lr-token-input`
+
+- **Import** `import '@aceshooting/lyra-ui/components/forms/token-input/token-input.js';` (registers the tag; side-effect import)
+- **Class** `LyraTokenInput`, also available unregistered from `@aceshooting/lyra-ui/components/forms/token-input/token-input.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-token-input`
+
+An editable form-associated token list. Enter, comma, or blur commits a token; Backspace removes
+the last token. `value` is a `string[]` and repeated values are submitted under `name`.
+
+**Properties:** `value`, `label`, `hint`, `errorText` (`error-text`), `placeholder`, `name`,
+`required`, `disabled`, `accessibleLabel` (attribute `aria-label` — forwarded to the internal text
+input), `allowDuplicates` (`allow-duplicates`, default `false`), `editable` (reflected, default
+`false` — see below), and `delimiter: string | null` (default `','` — see below).
+**Slots:** `label`, `hint`, `error`.
+**Events:** `input`, `change`, `lr-add` (`detail: { value }`), `lr-remove`
+(`detail: { value, index }`), and `lr-token-edit`
+(`detail: { value, previousValue, index }` — an existing token was edited in place and committed).
+**CSS parts:** `form-control`, `form-control-label`, `input-wrapper`, `token`, `token-label` (the
+token's text, doubling as the roving-focus edit trigger — rendered only while `editable`),
+`token-editor` (the inline text field that replaces a token's text while it is open for editing —
+rendered only while `editable` and only for the token being edited), `remove` (the
+per-token remove button, floored at the shared `--lr-icon-button-size` tap size around a compact
+glyph), `input`, `hint`, `error`. `focus()` and `blur()` forward to the internal text input.
+
+**`editable` — editing a token in place.** Off by default, in which case the token row renders
+exactly as it does without the feature and stays non-focusable. Turn it on and each token becomes a
+roving tab stop (one Tab stop for the whole row): click, Enter, Space, or F2 opens an inline
+editor on that token; ArrowLeft/ArrowRight move between tokens (swapped under RTL, since they mean
+previous/next *visually*), Home/End jump to the first/last. Inside the editor, Enter commits and
+returns focus to the token, Escape cancels (and is consumed rather than left to bubble, so an
+enclosing dialog or popover does not also close), and blurring commits *without* pulling focus
+back — a blur means the user already aimed focus elsewhere. `lr-token-edit` fires only for an edit
+that actually changed something: a reverted, unchanged, emptied, or (under the default
+`allowDuplicates = false`) duplicate-colliding edit is discarded silently, mirroring how a
+duplicate draft is skipped rather than rejecting the whole entry.
+
+**`delimiter` is nullable, and only a single character acts as a commit key.** It does two separate
+jobs: it splits a committed draft into several tokens, and — *only when it is exactly one
+character* — it is the keystroke that commits the draft. A multi-character delimiter still splits a
+pasted or committed draft, but no keystroke can ever match it, so nothing commits on typing.
+Setting it to `null` disables both, so a token may contain the delimiter verbatim. **`delimiter="null"`
+does not work** — that is the four-character string `null`. Use `delimiter="none"`, `delimiter=""`
+(both of which the attribute converter maps to `null`), or a property binding
+(`.delimiter=${null}`). Removing the attribute restores the `,` default.
+
+**Themeable custom properties:** `--lr-token-input-input-inline-size` (the editable input's
+`flex-basis` inside the wrapped token row; undeclared by default, falling back inline to
+`--lr-size-8rem`), `--lr-token-input-min-input-inline-size` (default `--lr-size-4rem`, the floor
+that input keeps once tokens have consumed the row), and `--lr-token-input-editor-inline-size`
+(default `--lr-size-6rem`, the inline size of the inline token editor opened by `editable`).

package/llms/components/lr-tool-approval-dialog.md

@@ -0,0 +1,131 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/agent-tools.md — do not edit this file. -->
+
+# `lr-tool-approval-dialog`
+
+- **Import** `import '@aceshooting/lyra-ui/components/agent-tools/tool-approval-dialog/tool-approval-dialog.js';` (registers the tag; side-effect import)
+- **Class** `LyraToolApprovalDialog`, also available unregistered from `@aceshooting/lyra-ui/components/agent-tools/tool-approval-dialog/tool-approval-dialog.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-tool-approval-dialog`
+
+A human-in-the-loop gate: presents one proposed tool/function call (`toolName` + `args`) and blocks an
+agent from executing it until a person explicitly approves or denies it, with an optional inline
+"edit the arguments before approving" step. First-party invention (no Web Awesome equivalent). It
+keeps its own panel template rather than nesting `<lr-dialog>`, so it has no dependency on the
+general-purpose dialog component, while its modal behavior participates in the shared overlay stack.
+
+Approve/Deny/Edit are built-in chrome, not a `footer` slot a consumer must assemble — there is exactly
+one correct action set for "approve this call". The `footer` slot is offered only for *supplementary*
+content alongside those buttons (e.g. a "remember this choice for this tool" checkbox); its content
+renders at the start of the action row, before Deny/Edit/Approve.
+
+**Exported types:**
+- `ToolApprovalDialogCloseReason = 'escape' | 'backdrop' | 'approve' | 'deny' | 'api' | string` — the
+  `lr-close` detail; `'escape'`/`'backdrop'`/`'approve'`/`'deny'` come from the dialog's own built-in
+  dismiss triggers, any other string is whatever a caller passes to `close()` directly.
+
+**Properties:**
+- `open: boolean = false` (reflected) — set this (or call `close()`) to dismiss; there is no separate
+  `show()`/`hide()` pair
+- `accessibleLabel: string | null = null` (attribute `aria-label`) — directly names the internal
+  dialog panel; otherwise the tool-name heading supplies `aria-labelledby`. Mirrors
+  `<lr-tool-result-dialog>`'s/`<lr-tool-select-dialog>`'s own host-`aria-label` override pattern; fed
+  only by a host `aria-label`
+- `toolName: string = ''` (attribute `tool-name`) — the proposed call's name, e.g. `web_search`;
+  drives the heading and the dialog's accessible name
+- `args: unknown = {}` (attribute: false) — the proposed call's arguments, rendered via
+  `<lr-json-viewer>` read-only, or stringified into a `<textarea>` while editing
+- `editable: boolean = true` (reflected) — whether an "Edit" affordance is offered at all (assign
+  `false` via a PROPERTY binding, e.g. `.editable=${false}` — a `?editable=${false}`
+  boolean-attribute binding cannot override a true default). When `false`, `args` is always shown
+  read-only and can never be changed before approval.
+- `spellcheck: boolean = false`, `autocapitalize: string = 'off'`,
+  `autoCorrect: string = 'off'` (attribute `autocorrect`), `autocomplete: string = 'off'`,
+  `wrap: 'hard'|'soft'|'off' = 'soft'`, `inputMode: string = ''` (attribute `inputmode`),
+  and `enterKeyHint: string = ''` (attribute `enterkeyhint`) — forwarded to the raw-JSON
+  `<textarea>` while editing; the defaults keep browser editing assistance from changing JSON text
+
+**Methods:** `close(reason: ToolApprovalDialogCloseReason = 'api'): void` — closes the dialog, emits
+`lr-close` with `reason`, and returns focus to whatever had it before the dialog opened; a no-op if
+already closed.
+
+**Events:** `lr-approve` (`detail: { args: unknown }` — the current, already-parsed arguments: the
+original `args` prop, or the user's edited-and-validated version if an edit was in progress; always
+followed by `lr-close` with reason `'approve'`), `lr-deny` (no detail — `this.emit('lr-deny')` is
+called with no second argument, so per the DOM spec's `CustomEventInit` default, `event.detail` is
+`null`, not `undefined`; always followed by `lr-close` with reason `'deny'`), `lr-close`
+(`detail: ToolApprovalDialogCloseReason` — fired exactly once per dismissal, via Escape, a backdrop
+click, the Approve/Deny buttons, or a `close()` call)
+
+**Slots:** `footer` — optional supplementary content (e.g. a "remember this choice" checkbox),
+rendered before the built-in Deny/Edit/Approve buttons.
+
+**CSS parts:** `backdrop`, `panel`, `header`, `tool-name`, `body`, `args-view`, `args-editor`, `error`,
+`footer`, `deny-button`, `edit-button`, `approve-button`
+
+**Themeable custom properties:** `--lr-tool-approval-dialog-overlay-color` (default
+`rgb(0 0 0 / 0.5)` — the backdrop scrim color; component-specific since no shared overlay token
+exists), `--lr-tool-approval-dialog-mono-font` (default `ui-monospace, SFMono-Regular, Menlo,
+Consolas, monospace` — used by both `tool-name` and the raw-JSON editor), plus shared tokens
+`--lr-space-xs/-s/-m/-l`, `--lr-color-surface`, `--lr-color-border`, `--lr-radius`,
+`--lr-shadow`, `--lr-color-brand`, `--lr-color-on-brand`, `--lr-color-danger`,
+`--lr-color-text`, `--lr-focus-ring-width/-color/-offset`, `--lr-opacity-disabled`.
+
+**Optional peer deps:** none — internally renders `<lr-json-viewer>`, a bundled dependency of this
+package, not an optional peer.
+
+```html
+<lr-tool-approval-dialog
+  tool-name="send_email"
+  .args=${{ to: 'ops@example.com', subject: 'Deploy finished' }}
+  @lr-approve=${(e) => runTool(e.detail.args)}
+  @lr-deny=${() => console.log('denied')}
+  @lr-close=${(e) => console.log('closed:', e.detail)}
+></lr-tool-approval-dialog>
+<script type="module">
+  document.querySelector('lr-tool-approval-dialog').open = true;
+</script>
+```
+
+While `editable`, an Edit button swaps the read-only `<lr-json-viewer>` for a plain `<textarea>`
+pre-filled with `JSON.stringify(args, null, 2)`. Every keystroke re-validates with `JSON.parse` — the
+Approve button is `disabled` for as long as the current textarea content fails to parse, so a
+malformed edit can never be silently approved as either the broken text or a stale copy of the
+original args. The same button relabels to "Cancel" while editing; clicking it discards the draft
+entirely and returns to the read-only view of the *original* `args` — there is no separate "save"
+step independent of Approve itself. Both `editing` and any in-progress draft reset back to the
+read-only view every time the dialog transitions from closed to open, so a reused instance never
+leaks one proposal's half-finished edit into the next.
+
+Initial focus deliberately does *not* land on Approve: approving a tool call is a consequential,
+potentially irreversible action, so a user who opens the dialog and reflexively presses Enter/Space
+before reading anything should deny, not approve. Deny gets the initial focus instead — the same
+"focus the safe action" convention a native destructive-confirmation dialog typically follows for its
+own Cancel button. Tab/Shift+Tab are bounded to the panel's own focusable content, and
+`<lr-json-viewer>`'s internal controls plus slotted custom-element controls are found through the
+shared composed-tree focus traversal used by the other modal families.
+
+**Known gotchas:**
+- `editable` defaults to `true` and reflects — see the property note above about overriding it with a
+  property binding, not a boolean-attribute binding.
+- `lr-deny` has no detail payload: its `event.detail` is `null`, not `undefined`.
+- a consumer flipping `editable` off while an edit is already in progress automatically exits edit mode
+  and discards the draft, so an unreachable "Cancel" affordance is never left stranded on screen.
+- reconnecting the element while still `open` (e.g. a drag-and-drop reparent that keeps the same
+  instance) resumes its shared overlay registration and re-acquires the ref-counted scroll lock
+  dropped in `disconnectedCallback` — `willUpdate()` alone wouldn't otherwise notice, since
+  disconnect/reconnect fire back-to-back with no update in between.
+- the Approve button's native `disabled` attribute (while the draft is invalid JSON) automatically
+  excludes it from the shared Tab trap, whose focusable-set computation skips disabled controls.
+- the raw-JSON `args-editor` textarea always hardcodes `spellcheck="false"`, `autocapitalize="off"`,
+  and `autocorrect="off"` — not exposed as configurable properties, unlike `<lr-textarea>`'s/
+  `<lr-chat-composer>`'s passthrough props — since its content is always JSON, never prose; without
+  this a mobile browser (notably iOS Safari, which defaults textarea `autocapitalize` to
+  `'sentences'`) could auto-capitalize or auto-correct key/value text as the user edits, silently
+  corrupting the JSON.
+
+---

package/llms/components/lr-tool-call-chip.md

@@ -0,0 +1,101 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/agent-tools.md — do not edit this file. -->
+
+# `lr-tool-call-chip`
+
+- **Import** `import '@aceshooting/lyra-ui/components/agent-tools/tool-call-chip/tool-call-chip.js';` (registers the tag; side-effect import)
+- **Class** `LyraToolCallChip`, also available unregistered from `@aceshooting/lyra-ui/components/agent-tools/tool-call-chip/tool-call-chip.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-tool-call-chip`
+
+A compact inline pill representing one tool/function call an agent made mid-conversation, e.g.
+`web_search: Searching web…` with a `running` spinner. First-party invention (no Web Awesome
+equivalent). It owns no detail surface of its own — activating it (click or Enter/Space while
+focused) fires `lr-tool-call-chip-select`; a consumer wires that to opening a
+`<lr-tool-result-dialog>` (or anything else) at the call site, keeping the chip reusable wherever
+a compact call summary is useful, with or without a detail surface behind it.
+
+**Properties:**
+- `name: string = ''` — the tool/function name, e.g. `web_search`
+- `category: string = ''` — optional grouping label, e.g. `research`
+- `status: 'pending'|'running'|'success'|'error'|'denied' = 'pending'` (reflected) — drives the
+  glyph, accent color, and `status-text`; same status vocabulary as `<lr-tool-result-dialog>` so a
+  call's chip and its detail dialog always agree; unknown runtime values render the pending icon,
+  text, and accessible label instead of failing the update
+- `summary: string = ''` — short human-readable status text, e.g. `Searching web…`
+- `durationMs?: number` (attribute `duration-ms`) — how long the call took, in milliseconds; the
+  `duration` part is omitted entirely when unset
+- `icon: string = ''` — literal icon hint (e.g. an emoji) rendered when the `icon` slot is empty;
+  ignored once anything is assigned to `slot="icon"`
+- `callId: string = ''` (attribute `call-id`) — unique identifier for this invocation, echoed back
+  in `lr-tool-call-chip-select`'s detail so a listener can correlate the click with the call it fired for
+
+**Events:** `lr-tool-call-chip-select` (`detail: { name: string; callId: string }`) — fired on
+click or Enter/Space activation of the pill. The deprecated `lr-tool-chip-select` alias is fired
+alongside it for one minor compatibility cycle.
+
+**Slots:** default (rich tooltip/detail content — e.g. the tool's raw arguments or a short preview —
+shown in a floating tooltip on hover/focus; nothing renders at all, no hover affordance, when this
+slot is empty), `icon` (overrides the built-in per-status glyph entirely via native slot-fallback
+content — assigned content wins; otherwise the `icon` prop is rendered as a literal hint; otherwise
+the built-in glyph for the current `status` is used)
+
+**CSS parts:** `base` (the clickable `<button>`), `icon`, `label` (wrapper around `category`, `name`,
+`summary`), `category`, `name`, `summary`, `meta` (wrapper around `status-text` and `duration`),
+`status-text`, `duration`, `tooltip` (the floating detail popup, only meaningful while open)
+
+**Themeable custom properties:** `--lr-tool-call-chip-spin` (default `1s linear` — running-icon
+animation duration/timing) and `--lr-transition-ambient` (default `1.8s ease-in-out` — pending-icon
+pulse duration/timing). `--lr-tool-call-chip-accent`, `--lr-tool-call-chip-bg`, and
+`--lr-tool-call-chip-border` are internal per-status variables reassigned by this component's own
+`:host([status="…"])` rules (e.g. `pending` → `--lr-color-text-quiet`/`--lr-color-surface`/
+`--lr-color-border`; `running` → brand; `success` → success; `error` → danger; `denied` → warning),
+so a page-level override loses to them for every non-default status — they are not a practical
+public theming hook. Shared tokens
+referenced: `--lr-color-text-quiet`, `--lr-color-surface`, `--lr-color-border`,
+`--lr-color-brand`/`-brand-quiet`, `--lr-color-success`/`-success-quiet`,
+`--lr-color-danger`/`-danger-quiet`, `--lr-color-warning`/`-warning-quiet`, `--lr-color-text`,
+`--lr-space-xs/-s/-m`, `--lr-radius`, `--lr-shadow`, `--lr-focus-ring-*`,
+`--lr-transition-fast`.
+
+**Optional peer deps:** none.
+
+```html
+<lr-tool-call-chip
+  name="web_search"
+  category="research"
+  status="running"
+  summary="Searching web…"
+  duration-ms="820"
+  call-id="call_123"
+  @lr-tool-call-chip-select=${(e) => openDetail(e.detail.callId)}
+>
+  <pre slot="icon" style="display:none"></pre>
+  <code>{"query": "lyra ui components"}</code>
+</lr-tool-call-chip>
+```
+
+The default slot's tooltip is positioned with the same `internal/positioner.js` `place()` helper
+`<lr-combobox>` uses for its listbox (`placement: 'top-start'`), and appears/disappears instantly
+on hover/focus/blur/mouseleave with no fade transition and no "pointer moved into the tooltip"
+tracking — it's documented as read-only preview content, not an interactive surface meant to retain
+focus of its own. `denied` gets its own warning-toned glyph and color (a policy rejection, not a
+runtime failure) distinct from `error`'s danger tone, matching `<lr-tool-result-dialog>`'s
+identical status vocabulary so a call reads the same way in both places. Duration formatting is
+sub-1000ms `"820ms"`, else trimmed to at most one decimal of seconds (`"1.5s"`, `"2s"`).
+
+**Known gotchas:**
+- the default slot is checked for emptiness by scanning `Array.from(this.children)` for elements
+  once on first update, then kept in sync via `slotchange` — only *element* children count (a bare
+  text node assigned to the default slot won't trigger the tooltip)
+- `aria-label` on the host element (if you set one) wins over the component's own generated
+  accessible label (`"name — summary — Status — duration"`); otherwise that generated string is
+  what's announced
+- Escape only dismisses the tooltip when it's open; it does not fire any event or otherwise affect
+  `status`/`open` state, since the chip has no "open" state of its own beyond the tooltip
+
+---

package/llms/components/lr-tool-param-form.md

@@ -0,0 +1,148 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/agent-tools.md — do not edit this file. -->
+
+# `lr-tool-param-form`
+
+- **Import** `import '@aceshooting/lyra-ui/components/agent-tools/tool-param-form/tool-param-form.js';` (registers the tag; side-effect import)
+- **Class** `LyraToolParamForm`, also available unregistered from `@aceshooting/lyra-ui/components/agent-tools/tool-param-form/tool-param-form.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-tool-param-form`
+
+Renders one form control per top-level property of a JSON Schema object, for ad hoc tool invocation or
+approval-editing UIs (e.g. "the agent wants to call `create_event(title, attendees, allDay)` — let the
+user tweak the arguments before running it"). First-party invention (no Web Awesome equivalent).
+
+**Supported schema subset:** a *flat* object whose properties use one primitive `type`
+(`'string'`, `'number'`, `'integer'`, or `'boolean'`), `required` property presence, string `enum`,
+primitive `const`, and the `title`/`description`/`default` annotations. Nested objects, arrays, type
+unions, `oneOf`/`anyOf`/`allOf`, `$ref`, string/numeric constraints, and schema-valued
+`additionalProperties` are not interpreted. An unsupported property type renders a visible fallback
+and makes the form invalid instead of being silently accepted.
+
+**Exported types:**
+- `ToolParamFormPropertyType = 'string' | 'number' | 'integer' | 'boolean'` — the four leaf property
+  types this renderer understands
+- `ToolParamFormPrimitive = string | number | boolean` — values accepted by the supported `const`
+- `ToolParamFormProperty { type: ToolParamFormPropertyType; enum?: string[]; description?: string;
+  title?: string; default?: unknown; const?: ToolParamFormPrimitive }` — one `schema.properties`
+  entry. `enum` is only meaningful when `type` is `'string'` (rendered as a `<lr-select>`); `const`
+  enforces one exact primitive value; `title` is the display label; `description` is helper text;
+  `default` pre-fills a field whenever `value` doesn't already have that key.
+- `ToolParamFormSchema { type: 'object'; properties: Record<string, ToolParamFormProperty>; required?:
+  string[] }` — the (intentionally flat) schema shape this component can render.
+
+**Properties:**
+- `schema: ToolParamFormSchema = { type: 'object', properties: {} }` (attribute: false)
+- `value: Record<string, unknown> = {}` (attribute: false) — exactly what the consumer last set it to.
+  A field with no entry in `value` but a schema `default` *displays* (and is *emitted*, via
+  `lr-input`) as that default, but the `value` property itself is left alone until the user actually
+  edits that field. JSON Schema ordinarily treats `default` as an annotation; this renderer
+  deliberately materializes it before validation/submission, so a valid default can satisfy
+  `required`.
+- `name: string = ''` — submission key for optional native `<form>` participation
+- `disabled: boolean = false` (reflected)
+
+**Getters:**
+- `effectiveValue: Record<string, unknown>` — `value` with every property missing from it filled in
+  from `schema`'s own `default`; this is what actually renders and what `lr-input`'s detail carries.
+  A key the user has explicitly cleared (a real own property set to `undefined`) stays cleared rather
+  than snapping back to its default — only a key genuinely absent from `value` falls back.
+- `errors: Record<string, string>` — the current per-field validation errors (`{ [propertyKey]:
+  message }`) for required presence, primitive type, finite number/integer, enum, const, and
+  unsupported type; independent of which fields have been visited.
+- `formError: string` — a schema-wide/JSON-serialization error that has no honest field key; empty
+  when the current effective value is safe to submit.
+
+**Methods:**
+- `checkValidity(): boolean` — synchronously re-snapshots even an in-place-mutated value/schema,
+  updates `ElementInternals`, and returns validity without revealing inline errors.
+- `reportValidity(): boolean` — performs the same resynchronization, reveals all current field/root
+  errors, focuses the first invalid generated field when one exists, and delegates to native
+  `ElementInternals.reportValidity()`.
+
+**Events:** `lr-input` (`detail: { value: Record<string, unknown> }` — the full current value
+object, every property with defaults resolved, not just the field that changed), `lr-validity-change`
+(`detail: { valid: boolean; errors: Record<string, string> }` — fired whenever overall validity or
+the field-error set changes, including once up front at connect time; serialization-only failures
+set `valid: false` while `formError`, rather than a fabricated field key, carries the root message)
+
+**Slots:** none.
+
+**CSS parts:** `base`, `field`, `label`, `description`, `error`, `unsupported`, `empty`
+
+**Themeable custom properties:** no component-specific custom properties; shared tokens only —
+`--lr-space-l/-xs/-s`, `--lr-color-border`, `--lr-radius`, `--lr-color-surface`,
+`--lr-color-danger`, `--lr-color-text-quiet`, `--lr-focus-ring-width/-color/-offset`,
+`--lr-opacity-disabled`.
+
+**Optional peer deps:** none — internally renders `<lr-select>`, `<lr-option>`, and
+`<lr-checkbox>`, all bundled dependencies of this package imported directly, not optional peers.
+
+```html
+<lr-tool-param-form
+  .schema=${{
+    type: 'object',
+    properties: {
+      title: { type: 'string', title: 'Title' },
+      attendees: { type: 'string', enum: ['team', 'everyone'], default: 'team' },
+      allDay: { type: 'boolean', title: 'All day' },
+    },
+    required: ['title'],
+  }}
+  .value=${draftArgs}
+  @lr-input=${(e) => (draftArgs = e.detail.value)}
+  @lr-validity-change=${(e) => (formIsValid = e.detail.valid)}
+></lr-tool-param-form>
+```
+
+This component owns no Submit/Cancel/Approve chrome — a consumer composes it inside their own dialog
+(e.g. `<lr-tool-approval-dialog>`) and reads `.value`/`.errors`/`checkValidity()` (or calls
+`reportValidity()` right before acting). Fields render in `Object.keys(schema.properties)` order
+(insertion order). A `'string'` property with a non-empty `enum` renders as a `<lr-select>` of
+`<lr-option>`s; a plain `'string'` renders a text `<input>`; `'number'`/`'integer'` render a numeric
+`<input type="number">` (`step="1"` for integer, `step="any"` for number); `'boolean'` renders a
+`<lr-checkbox>` with the field's label projected into its default slot — real slotted content, since
+that's `<lr-checkbox>`'s documented way to give itself an accessible name, unlike `aria-describedby`
+(neither `<lr-select>` nor `<lr-checkbox>` forward a host-level `aria-describedby` to their
+internal focusable element, so for the enum-select case the error message is folded into `aria-label`
+instead, alongside the always-visible adjacent `[part="description"]` text). The outer component owns
+schema validity rather than forwarding HTML `required` constraints: JSON Schema `required` means an
+own property is present, so `''`, `0`, and `false` are valid present values. Use
+`{ type: 'boolean', const: true }` together with `required` for a must-confirm checkbox.
+
+Optional native `<form>` participation is implemented via `ElementInternals` attached directly in the
+constructor (`static formAssociated = true`) rather than a string-value mixin, since this component's
+value is a whole object: `formResetCallback()` clears `value`/touched state back to `{}`, and
+`formDisabledCallback(disabled)` tracks inherited fieldset state separately from the author-owned
+`disabled` property. JSON serialization is guarded: circular values, `BigInt`, throwing getters/`toJSON`, and
+non-finite numbers cannot escape from an assignment or leave stale form data; the form entry is
+temporarily removed and `formError`/custom validity are set until a serializable value replaces it.
+This is layered on top of the primary `value` + `lr-input`/`lr-validity-change` contract.
+The same safe serialized object is used as session-history/autofill state. Restoration accepts only
+a JSON object, falls back to `{}` for malformed/non-object state, and does not emit `lr-input`.
+
+**Known gotchas:**
+- a schema property whose `type` isn't `'string'`/`'number'`/`'integer'`/`'boolean'` renders an inline
+  "Unsupported field type" message (a plain `.unsupported`-classed element, not one of the documented
+  CSS parts) and fails closed with custom validity instead of throwing or being silently dropped.
+- inline per-field errors only render once a field has been visited (`focusout`) at least once, or
+  after an explicit `reportValidity()` call — `checkValidity()` alone never reveals them, matching
+  every other form control in this library (`<lr-select>`/`<lr-combobox>`/`<lr-model-select>`
+  all avoid flashing red before the user has touched anything).
+- `effectiveValue` distinguishes "key absent from `value`" (falls back to `default`) from "key present
+  but `undefined`" (stays cleared and counts as absent for `required`) via `hasOwnProperty`, not an
+  `=== undefined` fallback check.
+- additional value keys are retained and submitted (matching JSON Schema's default open-object
+  behavior), but schema-valued/false `additionalProperties` is outside this renderer's subset.
+- reassign `value`/`schema` after changing them. Direct in-place mutation is resnapshotted by the
+  component's own `checkValidity()`/`reportValidity()`, but native `form.checkValidity()` and
+  submission use the last synchronized snapshot because the browser cannot observe arbitrary object
+  mutation.
+- `lr-validity-change` fires once immediately at connect time even before any user interaction, so a
+  form with an unmet required field announces `valid: false` on mount, not only after the first edit.
+
+---