@aceshooting/lyra-ui 4.2.0 → 5.1.0

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

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

@@ -0,0 +1,106 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/agent-tools.md — do not edit this file. -->
+
+# `lr-tool-result-dialog`
+
+- **Import** `import '@aceshooting/lyra-ui/components/agent-tools/tool-result-dialog/tool-result-dialog.js';` (registers the tag; side-effect import)
+- **Class** `LyraToolResultDialog`, also available unregistered from `@aceshooting/lyra-ui/components/agent-tools/tool-result-dialog/tool-result-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-result-dialog`
+
+A full tool-call detail overlay: a status/duration header plus a `body` slot where a consumer
+typically places a `<lr-tabs>` with Input/Preview/JSON/Raw panels. First-party invention (no Web
+Awesome equivalent). This component knows nothing about what's inside that slot — it only supplies
+the modal chrome around it. It keeps its own shadow template rather than nesting a `<lr-dialog>`,
+so slot-forwarding does not put a forwarding `<slot>` where a slotted `<lr-tabs>`'s own light-DOM
+child scan expects real projected content, while its modal behavior participates in the shared
+overlay stack.
+
+**Properties:**
+- `open: boolean = false` (reflected) — whether the dialog is open; set this (or call `close()`) —
+  there is no separate `show()`/`hide()` pair
+- `accessibleLabel: string | null = null` (attribute `aria-label`) — directly names the internal
+  dialog panel; otherwise the tool-name title supplies `aria-labelledby`
+- `toolName: string = ''` (attribute `tool-name`) — the tool's name, rendered prominently in the
+  header
+- `status: 'pending'|'running'|'success'|'error'|'denied' = 'pending'` (reflected) — drives the
+  header's status badge; same status vocabulary as `<lr-tool-call-chip>`
+- `durationMs?: number` (attribute `duration-ms`) — how long the call took, in milliseconds; omitted
+  from the header entirely when unset
+- `maximized: boolean = false` (reflected) — near-fullscreen presentation of the same open dialog
+
+**Methods:** `close(reason: ToolResultDialogCloseReason = 'api'): void` — closes the dialog (no-op if
+already closed), emits `lr-close` with `reason`, and returns focus to whatever had it before
+the dialog opened. Built-in triggers call this with `'escape'`/`'backdrop'`/`'close-button'`; a
+consumer's own close affordance (e.g. a footer action button) should call it directly with its own
+reason string so every dismissal path funnels through the same event.
+
+**Events:** `lr-close` (`detail: ToolResultDialogCloseReason` — `'escape'|'backdrop'|
+'close-button'|'api'|string`) fired exactly once per dismissal; `lr-maximize-change` (`detail:
+boolean`, the new `maximized` state) fired when the header's maximize/restore toggle is clicked.
+
+**Slots:** `body` (the dialog's main content — typically a `<lr-tabs>` with Input/Preview/JSON/Raw
+panels, entirely consumer-assembled), `footer` (optional action buttons, rendered in a bottom row —
+the footer row itself is hidden via `[hidden]` when nothing is slotted)
+
+**CSS parts:** `backdrop`, `panel` (`role="dialog"` while open), `header`, `title` (wrapper around
+tool name/status/duration), `tool-name`, `status`, `duration`, `header-actions`, `maximize-button`,
+`close-button`, `body`, `footer`
+
+**Themeable custom properties:** `--lr-tool-result-dialog-overlay-color` (default `rgb(0 0 0 /
+0.5)` — the backdrop scrim color; component-specific since no shared overlay token exists),
+`--lr-tool-result-dialog-maximized-inset` (default `var(--lr-space-l)` — inset applied to the
+panel while `[maximized]`, overridable e.g. to leave a persistent app rail visible), and
+`--lr-tool-result-dialog-spin` (default `1s linear`, stopped under reduced motion), plus shared
+tokens `--lr-color-surface/-border/-text-quiet/-brand/-brand-quiet/-success/-success-quiet/
+-danger/-danger-quiet/-warning/-warning-quiet`, `--lr-space-*`, `--lr-radius`, `--lr-shadow`,
+`--lr-icon-button-size`, `--lr-focus-ring-*`, `--lr-transition-base`.
+
+**Optional peer deps:** none.
+
+```html
+<lr-tool-result-dialog
+  tool-name="run_query"
+  status="success"
+  duration-ms="1240"
+  ?open=${dialogOpen}
+  @lr-close=${(e) => (dialogOpen = false)}
+  @lr-maximize-change=${(e) => console.log('maximized:', e.detail)}
+>
+  <lr-tabs slot="body">
+    <div slot="preview" label="Preview">…</div>
+    <div slot="json" label="JSON"><lr-json-viewer .data=${result}></lr-json-viewer></div>
+  </lr-tabs>
+  <button slot="footer">Rerun</button>
+</lr-tool-result-dialog>
+```
+
+While open, `[part="panel"]` takes `role="dialog"` + `aria-modal="true"` with `aria-labelledby`
+pointing at the tool-name element, document scroll is locked, and Tab/Shift+Tab are bounded to the
+panel's own focusable content in header-buttons → `body` slot → `footer` slot order (resolved
+shadow-piercingly, so a slotted custom element's real focusable target inside its own shadow root is
+found too). On open, focus moves to the first focusable element (falling back to the panel itself);
+on close, focus returns to whatever element triggered the open (captured at open time via the active
+element, since the trigger typically lives entirely outside this component). `maximized` toggles
+between the constrained modal size and a near-fullscreen size within the same open dialog and
+open/close lifecycle — unlike `<lr-widget>`'s fullscreen mode there's no separate non-modal resting
+state, so no additional scroll-lock/focus-trap bookkeeping is needed for that transition alone.
+
+**Known gotchas:**
+- a reconnect that preserves the same element instance (e.g. a drag-and-drop reparent) resumes its
+  shared overlay registration and re-acquires the scroll lock if `open` was still `true` across the
+  move — `disconnectedCallback`/`connectedCallback` fire back-to-back with no intervening update, so
+  `willUpdate` never reruns to notice `open` did not change
+- this component deliberately does **not** compose `<lr-dialog>` internally; it keeps its own
+  panel template so a slotted `<lr-tabs>` (or any other light-DOM-scanning child) sees real
+  projected content rather than a forwarding `<slot>`, while still sharing the overlay stack
+- `close()` is a no-op when `open` is already `false` — calling it twice in a row only fires
+  `lr-close` once
+- the `maximize`/`close` buttons are always the first elements in the Tab order while open,
+  regardless of visual position, followed by `body` then `footer` content
+
+---

package/llms/components/lr-tool-result-view.md

@@ -0,0 +1,162 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/agent-tools.md — do not edit this file. -->
+
+# `lr-tool-result-view`
+
+- **Import** `import '@aceshooting/lyra-ui/components/agent-tools/tool-result-view/tool-result-view.js';` (registers the tag; side-effect import)
+- **Class** `LyraToolResultView`, also available unregistered from `@aceshooting/lyra-ui/components/agent-tools/tool-result-view/tool-result-view.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-result-view`
+
+Renders a tool call's result via whichever custom renderer a host app has registered for it,
+falling back to `<lr-json-viewer>` whenever no renderer matches, a candidate renderer's
+`matches()` predicate throws during dispatch, a renderer's optional `load()` rejects, or its
+`render()` throws. First-party invention (no Web Awesome equivalent). This component
+owns none of the actual visual weight of a populated tool result — that's entirely whatever the
+registered renderer returns; `<lr-tool-result-view>` is just the dispatch + fallback + loading-state
+shell around it.
+
+**Properties:**
+- `registry?: ToolRendererRegistry` (property only, no attribute) — a custom `Map<string,
+  ToolRendererDefinition>` to dispatch against instead of the module-level default registry (see
+  `registry.ts` below)
+- `toolName: string = ''` (attribute `tool-name`) — the tool's name; the primary dispatch key
+- `result: unknown` (property only, no attribute) — the tool call's result payload, handed to the
+  matched renderer's `render()` (and to `matches()` for shape-based dispatch, and to the
+  `<lr-json-viewer>` fallback)
+- `args: unknown` (property only, no attribute) — the tool call's original arguments, if available,
+  handed to the matched renderer's `render()` alongside `result`
+- `fallback: string = 'json'` (reflected) — fallback-kind selector. `"json"` (the default) is
+  an unconditional `<lr-json-viewer>`. `"text"` renders a *string* `result` as preformatted text
+  instead — falling back to the `"json"` behavior when `result` isn't a string, so setting
+  `fallback="text"` defensively against an unpredictable result shape never renders broken output.
+  Any other value also uses the `"json"` behavior, forward-compatible plumbing only.
+- `copyable: boolean = false` (reflected) — shows a copy-to-clipboard affordance alongside the
+  fallback view, for either `fallback` kind: forwarded to `<lr-json-viewer>`'s own `copyable` for
+  `"json"`, or a `<lr-copy-button>` rendered next to the text for `"text"`.
+
+**Events:** `lr-render-error` (`detail: { toolName: string; error: unknown }`) — fired immediately
+before falling back to `<lr-json-viewer>`, whether because no renderer matched, a candidate
+renderer's `matches()` predicate threw during dispatch, a renderer's `load()` rejected, or its
+`render()` threw.
+
+**Slots:** none.
+
+**CSS parts:** `base` — the root wrapper around the resolved renderer's output (or the loading/
+fallback view). `fallback-text` — the `<pre>` element for the `fallback="text"` kind's preformatted
+result text (only present in that mode). `fallback-copy` — the `<lr-copy-button>` shown when
+`copyable` is set alongside the `fallback="text"` kind (only present when both are set).
+
+**Themeable custom properties:** `--lr-tool-result-view-font` (default `ui-monospace,
+SFMono-Regular, Menlo, Consolas, monospace` — component-specific since no shared monospace token
+exists, matching `<lr-json-viewer>`'s own `--lr-json-viewer-font` convention) — only used by the
+`fallback="text"` kind's `[part='fallback-text']`. Otherwise none — the component's own styling is
+deliberately minimal; all visible styling comes from whatever renderer/`<lr-skeleton>`/
+`<lr-json-viewer>`/`<lr-copy-button>` child is currently mounted.
+
+**Optional peer deps:** none required by the component itself — individual registered renderers may
+of course pull in whatever they need (a charting library, a markdown renderer), which is exactly what
+the lazy `load()` path in the registry exists for.
+
+```html
+<lr-tool-result-view
+  tool-name="get_weather"
+  .result=${{ tempC: 21, condition: 'cloudy' }}
+  .args=${{ city: 'Brussels' }}
+  @lr-render-error=${(e) => console.warn('renderer failed', e.detail)}
+></lr-tool-result-view>
+```
+
+### `registerToolRenderer()` and the tool-renderer registry (`registry.ts`)
+
+A type-keyed dispatch registry — a tiny plugin system so a host app can teach
+`<lr-tool-result-view>` how to draw the result of e.g. a `get_weather` or `run_query` tool call
+without this library knowing anything about either. Every registered instance dispatches against
+this same module-level registry unless a given `<lr-tool-result-view>`'s `registry` property is
+set to a different `Map` instance.
+
+**`ToolRendererDefinition`** — the shape of one registered renderer:
+- `render?: (result: unknown, args: unknown) => unknown` — renders the result (and the args that
+  produced it) as UI. Typed as `unknown` rather than Lit's `TemplateResult` so any lit-html-renderable
+  value works (a plain string, a DOM node, an array of templates) — consumers already own their own
+  Lit import and don't need this module to add one
+- `matches?: (payload: unknown) => boolean` — facade/shape-based dispatch predicate, consulted only
+  when no exact `toolName` key matches (see dispatch order below); only ever consulted *before*
+  `load` resolves when supplied inline at registration time — a definition that needs shape-based
+  dispatch and also wants to lazy-load its `render` should register a lightweight synchronous
+  `matches` up front alongside `load`
+- `load?: () => Promise<ToolRendererDefinition | { default: ToolRendererDefinition }>` — lazy loader
+  for a code-split renderer, so a host app can defer the cost of a rarely-used or heavy renderer
+  (e.g. one pulling in a charting library) instead of paying for it on every page that merely
+  registers it. Resolves to either a definition directly, or a `{ default }`-shaped module namespace
+  object, so `load: () => import('./my-renderer.js')` works unmodified when that module's default
+  export is itself a `ToolRendererDefinition`
+
+**Exports:**
+- `registerToolRenderer(name: string, def: ToolRendererDefinition): void` — registers (or
+  overwrites) the renderer for `name` in the module-level default registry
+- `getDefaultToolRendererRegistry(): ToolRendererRegistry` — returns the default `Map` that
+  `registerToolRenderer()` writes to and every `<lr-tool-result-view>` reads from unless its own
+  `registry` prop is set
+- `findToolRenderer(toolName: string, payload: unknown, registry?: ToolRendererRegistry):
+  ToolRendererDefinition | undefined` — the dispatch function `<lr-tool-result-view>` calls
+  internally on every resolve; exposed for direct use/testing too
+- `loadToolRenderer(def: ToolRendererDefinition): Promise<ToolRendererDefinition>` — resolves `def`
+  to a definition guaranteed to carry a real `render`, awaiting/unwrapping `def.load()` when present
+  (or returning `def` unchanged otherwise)
+- `clearToolRenderers(): void` — test-only utility that empties the default registry and its
+  `load()` cache, so one test's `registerToolRenderer()` calls can't leak into the next
+
+**Dispatch order** (`findToolRenderer`), exactly as `<lr-tool-result-view>`'s own `resolve()` uses
+it:
+1. An exact `toolName` key match in the registry.
+2. Failing that, the first entry — in registration order, since a `Map` already iterates that way —
+   whose `matches(payload)` returns `true`. Useful when several tool names share one result shape
+   (e.g. every `*_search` tool returning `{ results: [...] }`) or when the caller doesn't reliably
+   know the tool name at all.
+3. `undefined` if neither matches — `<lr-tool-result-view>` falls back to `<lr-json-viewer>` and
+   fires `lr-render-error`.
+
+Once a definition is found, if it carries `load`, `<lr-tool-result-view>` shows a
+`<lr-skeleton variant="rect" height="4rem">` while `loadToolRenderer()` resolves it. The resolved
+`load()` promise is cached keyed by *definition object identity* (a `WeakMap`, not by tool-name
+string) — two different registries that happen to reuse the same tool-name string get independently
+cached loads, and any given lazy definition's `load()` runs at most once no matter how many times
+it's dispatched to, across every `<lr-tool-result-view>` instance that resolves to it. A **rejected**
+`load()` is *not* cached — the definition stays registered, so a later resolution attempt (e.g. after
+a transient network failure) gets a fresh `load()` call rather than being stuck replaying one failed
+promise forever.
+
+```ts
+import { registerToolRenderer } from '@aceshooting/lyra-ui/components/agent-tools/tool-result-view/registry.js';
+
+registerToolRenderer('get_weather', {
+  render: (result, args) => html`<weather-card .data=${result} .city=${args?.city}></weather-card>`,
+});
+
+// Lazily loaded, shape-based fallback for every *_search tool:
+registerToolRenderer('web_search', {
+  matches: (payload) => typeof payload === 'object' && payload !== null && 'results' in payload,
+  load: () => import('./search-result-renderer.js'), // default export is a ToolRendererDefinition
+});
+```
+
+**Known gotchas:**
+- `<lr-tool-result-view>` re-resolves (re-runs the full dispatch → load → render pipeline)
+  whenever `toolName`, `result`, `args`, or `registry` changes, or on first update — a stale
+  in-flight `load()` superseded by a newer change is detected via an internal generation counter and
+  its result is discarded rather than clobbering a more recent render
+- registering under the same `name` twice silently overwrites the earlier definition — there is no
+  warning or error
+- `matches` is a linear scan over every registered definition's `matches` in registration order; it
+  only runs when the exact-name lookup misses, so tool names with a direct registration never pay
+  that scan cost
+- `fallback` implements exactly two kinds, `"json"` and `"text"`; any *other* value silently behaves
+  as `"json"`, as does `"text"` whenever `result` isn't a string. Only `"text"` renders
+  `[part="fallback-text"]`/`[part="fallback-copy"]`
+
+---

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

@@ -0,0 +1,124 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/agent-tools.md — do not edit this file. -->
+
+# `lr-tool-select-dialog`
+
+- **Import** `import '@aceshooting/lyra-ui/components/agent-tools/tool-select-dialog/tool-select-dialog.js';` (registers the tag; side-effect import)
+- **Class** `LyraToolSelectDialog`, also available unregistered from `@aceshooting/lyra-ui/components/agent-tools/tool-select-dialog/tool-select-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-select-dialog`
+
+A category-grouped, filterable, searchable tool-enablement dialog for picking which agent tools are
+available in a conversation. It keeps its own panel template rather than nesting `<lr-dialog>`, so
+it has no dependency on the general-purpose dialog, while its modal behavior participates in the
+shared overlay stack. First-party invention (no Web Awesome equivalent).
+
+**Exported types:**
+- `ToolSelectDialogTool { id: string; name: string; description?: string; category?: string; icon?:
+  string; disabled?: boolean; disabledReason?: string }` — one selectable agent tool. `category` groups
+  the row into a heading; tools with no `category` (or an empty/whitespace-only one) fall into a
+  trailing "Other" bucket. `icon` is a literal glyph (e.g. an emoji) rendered next to `name` — an opaque
+  string, not a registry lookup, the same convention `<lr-tool-call-chip>`'s `icon` uses. `disabled`
+  individually gates a tool regardless of `useDefaults`/`selected` (e.g. a tool requiring admin
+  approval); `disabledReason` is supporting text shown under a disabled row, ignored when `disabled` is
+  falsy.
+- `ToolSelectFilter = (tool: ToolSelectDialogTool, query: string) => boolean` — a predicate deciding
+  whether `tool` matches an already-trimmed, already-lowercased `query`. Assign `filter` to replace the
+  built-in case-insensitive name/description substring match entirely (mirrors `<lr-combobox>`'s
+  `OptionFilter` convention).
+- `ToolSelectionChangeDetail { selected: string[]; useDefaults: boolean }` — the `lr-change` detail
+  shape.
+- `ToolSelectDialogCloseReason = 'escape' | 'backdrop' | 'api' | string` — the `lr-close` detail;
+  `'escape'`/`'backdrop'` 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.
+- `tools: ToolSelectDialogTool[] = []` (attribute: false) — the full set of tools a consumer offers,
+  across all categories.
+- `selected: string[] = []` (attribute: false) — the currently-enabled tool ids.
+- `useDefaults: boolean = false` (attribute `use-defaults`, reflected) — whether the conversation is
+  using the default tool set (`true`) or a custom selection (`false`).
+- `label: string = 'Select tools'` — the dialog's visible heading and accessible name.
+- `accessibleLabel: string | null = null` (attribute `aria-label`) — overrides the dialog panel's
+  accessible name, taking precedence over the visible `label` heading; mirrors `<lr-dialog>`'s
+  own host-`aria-label` override pattern.
+- `searchPlaceholder: string = 'Search tools…'` (attribute `search-placeholder`)
+- `filter: ToolSelectFilter | null = null` (attribute: false) — overrides the built-in
+  case-insensitive name/description substring match.
+- `autocomplete: string = ''`, `spellcheck: boolean = true`, `autocapitalize: string = ''`,
+  `autoCorrect: string = ''` (`autocorrect`), `inputMode: string = ''` (`inputmode`), and
+  `enterKeyHint: string = ''` (`enterkeyhint`) — forwarded to the search `<input>`.
+
+**Methods:** `close(reason: ToolSelectDialogCloseReason = 'api'): void` — closes the dialog, emits
+`lr-close` with `reason`, and returns focus to whatever had it before the dialog opened.
+
+**Events:** `lr-change` (`detail: ToolSelectionChangeDetail` — the enabled-tool selection or the
+`useDefaults` toggle changed), `lr-close` (`detail: ToolSelectDialogCloseReason` — fired exactly once
+per dismissal, via Escape, a backdrop click, or a `close()` call)
+
+**Slots:** `footer` — optional action buttons (e.g. a "Done" button), rendered in a bottom row. Changes
+already apply live via `lr-change`, so this slot is purely optional; only visually shown once it has
+assigned elements.
+
+**CSS parts:** `backdrop`, `panel`, `header`, `title`, `subtitle`, `search-row`, `search-input`,
+`defaults-row`, `defaults-toggle`, `defaults-hint`, `body`, `empty`, `category`, `category-heading`,
+`category-count`, `category-list`, `tool-row`, `tool-checkbox`, `tool-name`, `tool-icon`,
+`tool-description`, `tool-disabled-reason`, `footer`
+
+**Themeable custom properties:** `--lr-tool-select-dialog-overlay-color` (default `rgb(0 0 0 / 0.5)` —
+the backdrop scrim color; component-specific since no shared overlay token exists, mirrors
+`<lr-dialog>`'s/`<lr-tool-result-dialog>`'s identical pattern), plus shared `--lr-space-*`,
+`--lr-color-surface/-border/-text/-text-quiet/-warning`, `--lr-radius`, `--lr-shadow`,
+`--lr-focus-ring-width/-color/-offset`, `--lr-opacity-disabled`.
+
+**Optional peer deps:** none — internally renders `<lr-checkbox>` and `<lr-switch>`, both bundled
+dependencies of this package imported directly, not optional peers.
+
+```html
+<lr-tool-select-dialog
+  label="Select tools"
+  .tools=${[
+    { id: 'search', name: 'Web search', category: 'Research' },
+    { id: 'python', name: 'Python', category: 'Code', description: 'Run sandboxed Python' },
+    { id: 'admin', name: 'Admin console', disabled: true, disabledReason: 'Requires admin approval' },
+  ]}
+  .selected=${enabledToolIds}
+  ?use-defaults=${usingDefaults}
+  ?open=${dialogOpen}
+  @lr-change=${(e) => updateTools(e.detail.selected, e.detail.useDefaults)}
+  @lr-close=${() => (dialogOpen = false)}
+>
+  <button slot="footer" @click=${(e) => e.target.closest('lr-tool-select-dialog').close('done')}>
+    Done
+  </button>
+</lr-tool-select-dialog>
+```
+
+`useDefaults` is a single top-level switch: while `true`, every per-tool checkbox renders disabled
+(still reflecting whatever `selected` holds — populate that with the actual default tool set whenever
+`useDefaults` is true) alongside a hint explaining that turning the switch off is how to customize.
+Turning it off is the only control that both flips `useDefaults` to `false` *and* unlocks the per-tool
+checkboxes for editing.
+
+**Known gotchas:**
+- No built-in footer/close button — dismissal happens via Escape, a backdrop click, or a consumer's own
+  `footer`-slotted action calling `close()` directly.
+- A row is effectively disabled whenever *either* its own `tool.disabled` is true *or* the top-level
+  `useDefaults` switch is on — a tool without `disabled` set can still render as a locked checkbox while
+  `useDefaults` is true.
+- `disabledReason` text only renders when both `tool.disabled` and `tool.disabledReason` are set.
+- Categories are grouped in first-seen order across `tools`; an empty/whitespace-only `category` folds
+  into a trailing "Other" bucket that's always rendered last. A category left with zero matches after
+  filtering is dropped entirely, not rendered as an empty heading.
+- 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 scroll lock dropped in
+  `disconnectedCallback`.
+- The search input is the first focusable element in the panel and receives focus automatically on open.
+
+---

package/llms/components/lr-tool-timeline.md

@@ -0,0 +1,56 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/agent-tools.md — do not edit this file. -->
+
+# `lr-tool-timeline`
+
+- **Import** `import '@aceshooting/lyra-ui/components/agent-tools/tool-timeline/tool-timeline.js';` (registers the tag; side-effect import)
+- **Class** `LyraToolTimeline`, also available unregistered from `@aceshooting/lyra-ui/components/agent-tools/tool-timeline/tool-timeline.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-timeline`
+
+Chronological list of agent tool/function calls composed from tool-call, result, and approval
+primitives, with retry counts and sensitive-field redaction.
+
+**Properties:**
+- `entries: ToolTimelineEntry[] = []` (attribute: false) — `ToolTimelineEntry` **extends
+  `ToolInvocation` from `@aceshooting/lyra-ui/ai`** (`{ id: string; name: string; args:
+  Record<string, unknown>; status: ToolCallStatus; result?: unknown; error?: string }`, where
+  `ToolCallStatus = 'pending' | 'running' | 'success' | 'error' | 'denied'`) with `{ startedAt?:
+  number; endedAt?: number; retryCount?: number; redactedFields?: string[]; needsApproval?: boolean;
+  approved?: boolean }`. Timestamps are epoch milliseconds; entries sort ascending by `startedAt`,
+  and an entry with none sorts after every timed entry (keeping its relative position among other
+  untimed ones) and renders no visible timestamp. `startedAt`+`endedAt` derive the `durationMs`
+  handed to the per-entry `lr-tool-call-chip`. `retryCount: 2` means the call reached its current
+  state on its third try; `0`/omitted renders no retry indicator. `redactedFields` are dotted paths
+  within `args`/`result`/`error` to mask in the rendered detail view (e.g.
+  `['args.apiKey', 'result.rows.0.ssn']`, or a bare `'args'`/`'result'`/`'error'` to mask a whole
+  branch); an unmatched path is a no-op, never an error — and redaction is **never** applied to the
+  copy of `args` handed to the approval dialog. While `needsApproval` is `true` and `approved` is
+  still `undefined`, activating the entry's chip opens the shared approval dialog instead of merely
+  firing the chip's own selection event
+- `approvalEditable: boolean = true` (attribute `approval-editable`, reflected) — forwarded to the
+  shared approval dialog's `editable`: whether a reviewer may edit an entry's arguments before
+  approving. Uses a `true`-defaulting string converter, so plain-HTML `approval-editable="false"`
+  works
+- `formatTimestamp?: (date: Date) => string` (attribute: false) — overrides the default
+  `hour:minute` rendering of each entry's `startedAt`
+
+**Events:** `lr-tool-approval-decide` (`detail: ToolTimelineApprovalDetail` =
+`ToolApprovalEventDetail & { args?: unknown }` = `{ invocationId: string; approved: boolean; args?:
+unknown }`, extending the shared detail from `@aceshooting/lyra-ui/ai`). `args` is present only when
+`approved` is `true`, and may differ from what the entry originally proposed — the dialog's inline
+edit step can hand back different arguments. A listener that only needs `{ invocationId, approved }`
+can ignore it; one actually executing the tool needs it.
+
+**CSS parts:** `base`,
+`entry`, `entry-marker`, `entry-header`, `entry-timestamp`, `entry-body`, `entry-details`,
+`entry-result`, `entry-error`, `entry-retries`, `entry-retries-count`, `entry-retries-label`,
+`entry-redacted-indicator`, `entry-approval-status`, `approval-dialog`.
+
+**Themeable custom properties:** `--lr-tool-timeline-gap` (default `var(--lr-space-l)`) — vertical
+gap between entries; `--lr-tool-timeline-marker-size` (default `var(--lr-size-0-625rem)`) — the
+per-entry timeline marker dot's size, which also sets the entry grid's leading column width.

package/llms/components/lr-tooltip.md

@@ -0,0 +1,47 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/overlays.md — do not edit this file. -->
+
+# `lr-tooltip`
+
+- **Import** `import '@aceshooting/lyra-ui/components/overlays/overlay/tooltip.js';` (registers the tag; side-effect import)
+- **Class** `LyraTooltip`, also available unregistered from `@aceshooting/lyra-ui/components/overlays/overlay/tooltip.class.js`
+- **Family** `components/overlays/` — 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-tooltip`
+
+A hover/focus tooltip positioned with the shared Floating UI positioner.
+
+**Properties:** `open`, `manual`, `delay`, `placement`, `distance`, `content`, and
+`accessibleLabel` (`aria-label`). **Methods:** `showAt(rect: { x, y, width?, height?,
+contextElement? }, options?: { returnFocusTo?: HTMLElement })` — same virtual-anchor contract as
+`lr-popover.showAt()` above (anchors to an arbitrary rectangle instead of the slotted `trigger`,
+`width`/`height` default to `0`, `contextElement` gives `autoUpdate()` something to observe,
+Escape returns focus to `options.returnFocusTo` or skips focus-return, re-call with fresh
+coordinates to re-anchor a moving point). Opens immediately, bypassing `delay`/`manual` (both are
+hover-debounce concerns for a slotted trigger, not a deliberate programmatic call); close it the
+same way any tooltip closes, by setting `open = false`. **Slots:** `trigger`, default content.
+**CSS parts:** `trigger`, `popup`. **Themeable custom properties:** `--lr-tooltip-max-inline-size`
+(default `--lr-size-20rem`), `--lr-tooltip-background` (default `--lr-color-neutral`), and
+`--lr-tooltip-color` (default `--lr-color-on-neutral`).
+
+**`showAt()` composed with `lr-graph`** — anchoring a popover to a clicked graph node. Note:
+`lr-graph.getNodePosition()` and the `lr-node-click` event's `{ x, y }` are in the graph's own
+*local drawing space* (pre pan/zoom), not viewport pixels, so they can't be passed to `showAt()`
+directly. For `renderer="svg"` (the default), read the clicked node's own rendered element instead,
+whose `getBoundingClientRect()` is already viewport-relative; for `renderer="canvas"` (no per-node
+DOM element), use the click event's own `clientX`/`clientY`.
+
+```js
+const graph = document.querySelector('lr-graph');
+const detail = document.querySelector('lr-popover'); // no slotted trigger needed for showAt()
+
+graph.addEventListener('click', (event) => {
+  const nodeEl = event.composedPath().find((el) => el instanceof Element && el.matches('[part="node"]'));
+  if (!nodeEl) return; // clicked empty canvas/background, not a node
+  const rect = nodeEl.getBoundingClientRect();
+  detail.showAt({ x: rect.left + rect.width / 2, y: rect.top, width: rect.width, height: rect.height });
+});
+```