@aceshooting/lyra-ui 5.0.0 → 5.2.0

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,61 @@
+<!-- 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;
+`--lr-tool-timeline-denied-marker-color` (default `var(--lr-color-warning)`) — rail-dot color for a
+`status="denied"` entry, decoupled from the pending-approval border color below so either can be
+retinted independently; `--lr-tool-timeline-pending-approval-border-color` (default
+`var(--lr-color-warning)`) — color of the entry body's leading border while that entry's
+`data-pending-approval` is `"true"`.

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 });
+});
+```

package/llms/components/lr-tour.md

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