themelia-ui 2.0.1 → 3.0.0

package/docs/generated/components/features--ai-chat.md

@@ -20,7 +20,7 @@ import "themelia-ui/features/ai-chat.css"
 
 ## Composition
 
-This family composes `base/badge`, `base/buttons`, `base/copyable`, `base/display`, `base/feedback`, `base/text-inputs`, `base/typography`, `base/upload`.
+This module composes `base/badge`, `base/buttons`, `base/copyable`, `base/display`, `base/feedback`, `base/text-inputs`, `base/typography`, `base/upload`.
 
 Application policy—routing, fetching, persistence, permissions, and translation—stays
 outside the package and arrives through the public props, callbacks, slots, or accessors below.
@@ -31,6 +31,8 @@ outside the package and arrives through the public props, callbacks, slots, or a
 
 Kind: callable.
 
+The identity strip that says which agent is answering.
+
 ```text
 ({ name, icon, avatar, subtitle, tone, status, variant, trailing, className, strings, }: AiAgentProps) => import("react").JSX.Element
 ```
@@ -80,6 +82,8 @@ Exclude<SemanticTone, "secondary">
 
 Kind: callable.
 
+The frame around a produced artifact: its title, its actions, and what it holds.
+
 ```text
 ({ title, subtitle, icon, copyText, children, collapsed, onOpen, actions, onDownload, className, strings, }: AiArtifactProps) => import("react").JSX.Element
 ```
@@ -129,6 +133,8 @@ Kind: interface.
 
 Kind: callable.
 
+One file a turn carried, as a chip or a thumbnail tile, with its upload progress.
+
 ```text
 ({ name, meta, kind, icon, thumbnailUrl, progress, errored, onOpen, onRemove, className, strings, }: AiAttachmentProps) => import("react").JSX.Element
 ```
@@ -173,6 +179,8 @@ Kind: interface.
 
 Kind: callable.
 
+The step timeline of an agent's plan.
+
 ```text
 ({ steps, hideHeader, streaming, className, strings, }: AiChainOfThoughtProps) => import("react").JSX.Element
 ```
@@ -223,6 +231,10 @@ Kind: type.
 
 Kind: callable.
 
+The agent header, the transcript, and the composer, wired together. No fetcher, router or
+streaming client: messages, input, queue and attachments are props, and submitting is a
+callback.
+
 ```text
 ({ messages, inputValue, onInputChange, onSubmit, onStop, streaming, disabled, attachments, onRemoveAttachment, onAttach, showAttach, agent, headerActions, queue, onCancelQueueItem, suggestions, onPickSuggestion, onMessageCopy, onMessageRegenerate, onAttachmentOpen, disableAutoScroll, slots, strings, className, }: AiChatProps<TSuggestionData>) => import("react").JSX.Element
 ```
@@ -257,6 +269,9 @@ Kind: interface.
 
 Kind: callable.
 
+The files attached to the turn being written, as one of the strips above the composer's
+field; a sent turn's attachments render as one too.
+
 ```text
 ({ attachments, onRemove, onOpen, className, }: AiChatAttachmentsStripProps) => import("react").JSX.Element | null
 ```
@@ -276,6 +291,9 @@ Kind: interface.
 
 Kind: callable.
 
+The transcript. Exported, like the composer and the empty state, because a consumer building
+a different chat layout against the same data should get the parts without taking the shell.
+
 ```text
 ({ messages, renderMessage, intro, footer, empty, disableAutoScroll, className, strings, }: AiChatConversationProps) => import("react").JSX.Element
 ```
@@ -310,6 +328,10 @@ Kind: interface.
 
 Kind: callable.
 
+The state before the first turn. Exported, like the transcript and the composer, because a
+consumer building a different chat layout against the same data should get the parts
+without taking the shell.
+
 ```text
 ({ title, description, icon, below, className, }: AiChatEmptyStateProps) => import("react").JSX.Element
 ```
@@ -388,6 +410,9 @@ Kind: interface.
 
 Kind: callable.
 
+The composer. Exported, like the transcript and the empty state, because a consumer building
+a different chat layout against the same data should get the parts without taking the shell.
+
 ```text
 ({ value, onValueChange, onSubmit, onStop, streaming, disabled, attachments, onRemoveAttachment, onAttach, showAttach, leadingActions, trailingActions, hideHint, minRows, maxRows, autoFocus, submitKeyLabel, className, strings, }: AiChatPromptInputProps) => import("react").JSX.Element
 ```
@@ -436,18 +461,18 @@ Kind: interface.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `messages` | yes | `readonly AiChatMessageData[]` | Oldest first. |
-| `inputValue` | yes | `string` |  |
-| `onInputChange` | yes | `(value: string) => void` |  |
-| `onSubmit` | no | `(values: AiChatSubmitValues) => void` |  |
-| `onStop` | no | `() => void` |  |
-| `streaming` | no | `boolean` |  |
+| `messages` | yes | `readonly AiChatMessageData[]` | Oldest first. Each carries `parts`, which is where the mix lives — text, reasoning, a chain<br>of thought, a tool call, code, sources, a task, an artifact, a confirmation, attachments,<br>or custom. |
+| `inputValue` | yes | `string` | The composer's text. Controlled: the composer holds no draft of its own, so clearing it<br>after a submit is the consumer's, which is also where the failed-send-restores-the-text<br>case lives. |
+| `onInputChange` | yes | `(value: string) => void` | Receives every edit to `inputValue`. |
+| `onSubmit` | no | `(values: AiChatSubmitValues) => void` | Fires on Enter or the send button. An attachment on its own is a valid message — “here,<br>look at this” needs no words. |
+| `onStop` | no | `() => void` | What the stop control calls while `streaming`. |
+| `streaming` | no | `boolean` | Flips submit to stop. Separate from `disabled`, because a streaming chat is still readable<br>and still cancellable; a disabled one is neither. |
 | `disabled` | no | `boolean` |  |
 | `attachments` | no | `readonly AiChatAttachment[]` |  |
 | `onRemoveAttachment` | no | `(id: string) => void` |  |
 | `onAttach` | no | `() => void` |  |
 | `showAttach` | no | `boolean` |  |
-| `agent` | no | `AiChatAgent \| null` | `null` hides the header strip. |
+| `agent` | no | `AiChatAgent \| null` | Name, icon, subtitle, tone and status for the header strip. `null` hides the strip<br>entirely. |
 | `headerActions` | no | `ReactNode` |  |
 | `queue` | no | `readonly AiChatQueueItem[]` |  |
 | `onCancelQueueItem` | no | `(id: string) => void` |  |
@@ -457,7 +482,7 @@ Kind: interface.
 | `onMessageRegenerate` | no | `(message: AiChatMessageData) => void` |  |
 | `onAttachmentOpen` | no | `(messageId: string, attachmentId: string) => void` |  |
 | `disableAutoScroll` | no | `boolean` |  |
-| `slots` | no | `AiChatSlots` |  |
+| `slots` | no | `AiChatSlots` | Seven regions replaced outright — `header`, `intro`, `belowMessages`, `empty`, `queue`,<br>`suggestions`, `input` — plus `renderMessage` for a turn. This is the seam that keeps a<br>prop per idea out of the API. |
 | `strings` | no | `Partial<AiChatStrings>` |  |
 | `className` | no | `string` |  |
 
@@ -465,6 +490,8 @@ Kind: interface.
 
 Kind: callable.
 
+The strip above the composer holding the messages waiting to send.
+
 ```text
 ({ items, hideHeader, onCancel, className, strings, }: AiChatQueueProps) => import("react").JSX.Element | null
 ```
@@ -565,6 +592,8 @@ Kind: interface.
 
 Kind: callable.
 
+The strip above the composer offering prompt suggestions.
+
 ```text
 ({ suggestions, onPick, hideHeader, className, strings, }: AiChatSuggestionsRowProps<TData>) => import("react").JSX.Element | null
 ```
@@ -593,6 +622,10 @@ Kind: interface.
 
 Kind: callable.
 
+Code as produced. There is deliberately no syntax highlighting — that means shipping a
+grammar per language, and a chat can be handed any of them. Bring a highlighter and pass its
+output as `AiArtifact` children, or replace the code block.
+
 ```text
 ({ code, language, filename, showLineNumbers, highlightLines, hideHeader, maxHeight, headerActions, onCopy, className, strings, }: AiCodeBlockProps) => import("react").JSX.Element
 ```
@@ -607,7 +640,7 @@ Kind: interface.
 | `language` | no | `string` |  |
 | `filename` | no | `string` |  |
 | `showLineNumbers` | no | `boolean` |  |
-| `highlightLines` | no | `readonly number[]` | 1-indexed. |
+| `highlightLines` | no | `readonly number[]` | 1-indexed. The gutter and the line share a grid row, so a highlight covers both rather than<br>stopping at the number. |
 | `hideHeader` | no | `boolean` |  |
 | `maxHeight` | no | `number \| string` |  |
 | `headerActions` | no | `ReactNode` |  |
@@ -630,6 +663,9 @@ Kind: interface.
 
 Kind: callable.
 
+The approval prompt that stops an agent before it acts. A confirmation is a decision surface:
+it does not auto-dismiss.
+
 ```text
 ({ title, description, icon, tone, status, onApprove, onReject, approveLabel, rejectLabel, details, className, strings, }: AiConfirmationProps) => import("react").JSX.Element
 ```
@@ -734,6 +770,8 @@ Kind: type.
 
 Kind: callable.
 
+The reasoning disclosure: the model's trace, and how long it thought.
+
 ```text
 ({ children, streaming, durationSeconds, expandWhileStreaming, defaultExpanded, expanded: expandedProp, onExpandedChange, className, strings, }: AiReasoningProps) => import("react").JSX.Element
 ```
@@ -747,7 +785,7 @@ Kind: interface.
 | `children` | no | `ReactNode` | The trace. A string is rendered pre-wrapped; anything else is rendered as given. |
 | `streaming` | no | `boolean` |  |
 | `durationSeconds` | no | `number` |  |
-| `expandWhileStreaming` | no | `boolean` | Opens while streaming and closes when it stops. |
+| `expandWhileStreaming` | no | `boolean` | Opens on the edge where streaming starts and closes on the edge where it stops, so a reader<br>who opened or closed it in between is not fought. |
 | `defaultExpanded` | no | `boolean` |  |
 | `expanded` | no | `boolean` |  |
 | `onExpandedChange` | no | `(expanded: boolean) => void` |  |
@@ -770,6 +808,11 @@ Kind: interface.
 
 Kind: callable.
 
+“Thinking…” as a swept highlight rather than a spinner. A spinner says something is
+happening; a sweep says something is being produced, which is the difference the reader is
+waiting on. It paints through `background-clip`, so its colour is transparent by design — a
+contrast probe reading `color` alone will call it a 1:1 failure.
+
 ```text
 ({ children, paused, duration, className, }: AiShimmerProps) => import("react").JSX.Element
 ```
@@ -802,6 +845,9 @@ Kind: interface.
 
 Kind: callable.
 
+What the model read. Sources are listed rather than footnoted, because a reader checking an
+answer is looking for the list, not for a marker in the prose.
+
 ```text
 ({ sources, variant, maxAvatars, expanded: expandedProp, defaultExpanded, onExpandedChange, onSelect, className, strings, }: AiSourcesProps) => import("react").JSX.Element
 ```
@@ -818,7 +864,7 @@ Kind: interface.
 | `expanded` | no | `boolean` |  |
 | `defaultExpanded` | no | `boolean` |  |
 | `onExpandedChange` | no | `(expanded: boolean) => void` |  |
-| `onSelect` | no | `(source: AiSourceItem, index: number) => void` | Preferred over `url`, so a source can route inside the app. |
+| `onSelect` | no | `(source: AiSourceItem, index: number) => void` | Wins over `url`, so an app that routes internally is not forced to hand the reader a full<br>page load to reach its own document. |
 | `className` | no | `string` |  |
 | `strings` | no | `Partial<Strings.AiSourcesStrings>` |  |
 
@@ -845,6 +891,9 @@ Kind: type.
 
 Kind: callable.
 
+One task of an agent's plan, with its status and its sub-tasks. A task reports what is being
+done, not merely that something is.
+
 ```text
 ({ task, density, indent, className, strings, }: AiTaskProps) => import("react").JSX.Element
 ```
@@ -897,6 +946,10 @@ Kind: interface.
 
 Kind: callable.
 
+One tool call: its name, status, arguments and result. With neither args nor result (nor an
+error) the header is a plain row, not a disclosure — a control that opens an empty panel is
+worse than no control.
+
 ```text
 ({ name, status, icon, args, result, error, durationMs, expanded: expandedProp, defaultExpanded, onExpandedChange, className, strings, }: AiToolCallProps) => import("react").JSX.Element
 ```
@@ -908,7 +961,7 @@ Kind: interface.
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
 | `name` | yes | `string` |  |
-| `status` | yes | `AiToolCallStatus` |  |
+| `status` | yes | `AiToolCallStatus` | Where the call is, as the header's badge: its tone, glyph and label. |
 | `icon` | no | `LucideIcon` |  |
 | `args` | no | `ReactNode` |  |
 | `result` | no | `ReactNode` |  |
@@ -1084,6 +1137,11 @@ AiToolCallStrings
 
 Kind: callable.
 
+The stick-to-bottom behaviour without the layout, for a consumer building their own
+transcript: new content scrolls it only while the reader is at the bottom. Returns the
+`containerRef` for the scroll viewport, the `endRef` sentinel for the end of the content,
+`isAtBottom`, and `scrollToBottom`.
+
 ```text
 ({ threshold, dependency, disableAutoScroll, }?: UseAiChatScrollOptions) => UseAiChatScrollResult
 ```
@@ -1116,72 +1174,348 @@ Preview route: AI chat — `/ai-chat`
 ### The chat
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<AiChat
-  messages={messages}
-  inputValue={input}
-  onInputChange={setInput}
-  onSubmit={({ text, attachments }) => send(text, attachments)}
-  onStop={() => abort()}
-  streaming={isStreaming}
-  agent={{ name: "Atlas", subtitle: "claude-opus-5", status: "thinking" }}
-  suggestions={suggestions}
-  onPickSuggestion={(s) => setInput(String(s.label))}
-/>
+import { useRef, useState } from "react"
+
+import { Button } from "themelia-ui/base/buttons"
+import { Stack } from "themelia-ui/base/structure"
+import { Text } from "themelia-ui/base/typography"
+import { AiChat, type AiChatMessageData } from "themelia-ui/features/ai-chat"
+
+import { MESSAGES, SUGGESTIONS } from "./data"
+
+export default function Chat() {
+	const [input, setInput] = useState("")
+	const [streaming, setStreaming] = useState(false)
+	const [messages, setMessages] = useState<AiChatMessageData[]>(MESSAGES)
+	const [activeResponseId, setActiveResponseId] = useState<string | null>(null)
+	const messageSequence = useRef(0)
+	const [log, setLog] = useState<string[]>([])
+
+	const note = (line: string) => setLog((lines) => [line, ...lines].slice(0, 4))
+
+	return (
+		<>
+			{/* The chat fills the box it is given, and the transcript scrolls inside it. */}
+			<div style={{ height: "40rem" }}>
+				<AiChat
+					messages={messages}
+					inputValue={input}
+					onInputChange={setInput}
+					onSubmit={({ text }) => {
+						messageSequence.current += 1
+						const sequence = messageSequence.current
+						const responseId = `demo-response-${sequence}`
+						setMessages((current) => [
+							...current,
+							{
+								id: `demo-user-${sequence}`,
+								role: "user",
+								authorName: "You",
+								parts: [{ type: "text", content: text }],
+							},
+							{
+								id: responseId,
+								role: "assistant",
+								authorName: "Atlas",
+								parts: [],
+								pending: true,
+							},
+						])
+						note(`sent: ${text}`)
+						setInput("")
+						setActiveResponseId(responseId)
+						setStreaming(true)
+					}}
+					onStop={() => {
+						setMessages((current) =>
+							current.map((message) =>
+								message.id === activeResponseId
+									? {
+										...message,
+										pending: false,
+										parts: [{ type: "text", content: "Generation stopped." }],
+									}
+									: message,
+							),
+						)
+						note("stopped generation")
+						setActiveResponseId(null)
+						setStreaming(false)
+					}}
+					streaming={streaming}
+					agent={{
+						name: "Atlas",
+						subtitle: "model-large",
+						status: streaming ? "working" : "idle",
+					}}
+					headerActions={
+						<Button type="button" tone="neutral" buttonStyle="ghost" onClick={() => note("settings")}>
+							Settings
+						</Button>
+					}
+					suggestions={SUGGESTIONS}
+					onPickSuggestion={(suggestion) => setInput(String(suggestion.label))}
+					onAttach={() => note("attach")}
+					onMessageCopy={(message) => note(`copied ${message.id}`)}
+					onMessageRegenerate={(message) => note(`regenerate ${message.id}`)}
+					queue={[
+						{ id: "q1", label: "Backfill the 2025 invoices", status: "running" },
+						{ id: "q2", label: "Run the billing tests" },
+					]}
+					onCancelQueueItem={(id) => note(`cancelled ${id}`)}
+				/>
+			</div>
+
+			{log.length > 0 && (
+				<Stack gap="none">
+					{log.map((line, index) => (
+						<Text key={`${line}-${index}`} size="xs" type="secondary">{line}</Text>
+					))}
+				</Stack>
+			)}
+		</>
+	)
+}
 ```
 
 ### A turn
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<AiMessageBubble role="assistant" authorName="Atlas" onRegenerate={retry}>
-  The totals are summed as floats.
-</AiMessageBubble>
-
-<AiShimmer>Thinking…</AiShimmer>
+import { useState } from "react"
+
+import { Stack } from "themelia-ui/base/structure"
+import { Text } from "themelia-ui/base/typography"
+import { AiMessageBubble, AiShimmer } from "themelia-ui/features/ai-chat"
+
+export default function Turn() {
+	const [log, setLog] = useState<string[]>([])
+
+	const note = (line: string) => setLog((lines) => [line, ...lines].slice(0, 4))
+
+	return (
+		<>
+			<Stack gap="lg">
+				<AiMessageBubble
+					role="user"
+					authorName="You"
+					timestamp="09:12"
+				>
+					Why is the invoice total off by a cent on some orders?
+				</AiMessageBubble>
+				<AiMessageBubble
+					role="assistant"
+					authorName="Atlas"
+					timestamp="09:12"
+					plainText="Each line is rounded before the sum, so the error compounds."
+					onRegenerate={() => note("regenerate")}
+				>
+					Each line is rounded before the sum, so the error compounds.
+				</AiMessageBubble>
+				<AiMessageBubble role="system">
+					Atlas switched to model-large.
+				</AiMessageBubble>
+				<AiShimmer />
+			</Stack>
+
+			{log.length > 0 && (
+				<Stack gap="none">
+					{log.map((line, index) => (
+						<Text key={`${line}-${index}`} size="xs" type="secondary">{line}</Text>
+					))}
+				</Stack>
+			)}
+		</>
+	)
+}
 ```
 
 ### Reasoning and plans
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<AiReasoning streaming={isThinking} durationSeconds={4}>
-  {trace}
-</AiReasoning>
-
-<AiChainOfThought steps={steps} streaming />
-<AiTask task={plan} />
+import { Stack } from "themelia-ui/base/structure"
+import { AiChainOfThought, AiReasoning, AiTask } from "themelia-ui/features/ai-chat"
+
+const PLAN = {
+	id: "t0",
+	title: "Fix the rounding",
+	status: "running" as const,
+	rightSlot: "2 of 4",
+	children: [
+		{ id: "t1", title: "Move amounts to cents", status: "completed" as const },
+		{ id: "t2", title: "Round once in formatTotal", status: "completed" as const },
+		{ id: "t3", title: "Backfill the existing invoices", status: "running" as const },
+		{ id: "t4", title: "Add a regression test", status: "queued" as const },
+	],
+}
+
+const CHAIN = [
+	{ id: "c1", title: "Read the failing orders", description: "Nine of 4,102 are off by one cent.", status: "completed" as const },
+	{ id: "c2", title: "Compare the sums", description: "Per-line rounding, then a sum.", status: "completed" as const },
+	{ id: "c3", title: "Draft the fix", status: "active" as const },
+	{ id: "c4", title: "Write the test", status: "pending" as const },
+]
+
+export default function Thinking() {
+	return (
+		<Stack gap="lg">
+			<AiReasoning durationSeconds={4}>
+				The totals are summed as floats. 0.1 + 0.2 is 0.30000000000000004, and rounding
+				each line before summing compounds the error across a long invoice.
+			</AiReasoning>
+			<AiReasoning streaming>
+				Checking whether the backfill needs to run per tenant…
+			</AiReasoning>
+			<AiChainOfThought steps={CHAIN} streaming />
+			<AiTask task={PLAN} density="expanded" />
+		</Stack>
+	)
+}
 ```
 
 ### Tool calls
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<AiToolCall
-  name="search_codebase"
-  status="success"
-  durationMs={820}
-  args={JSON.stringify(args, null, 2)}
-  result={summary}
-/>
+import { SearchIcon } from "lucide-react"
+
+import { Stack } from "themelia-ui/base/structure"
+import { AiToolCall } from "themelia-ui/features/ai-chat"
+
+export default function Tools() {
+	return (
+		<Stack gap="md">
+			<AiToolCall name="read_file" status="pending" />
+			<AiToolCall
+				name="search_codebase"
+				status="running"
+				icon={SearchIcon}
+				args={'{ "query": "invoice total" }'}
+			/>
+			<AiToolCall
+				name="search_codebase"
+				status="success"
+				icon={SearchIcon}
+				durationMs={820}
+				defaultExpanded
+				args={'{\n  "query": "invoice total",\n  "path": "src/billing"\n}'}
+				result={"3 matches\n  invoice.ts:41\n  totals.ts:12\n  order.ts:88"}
+			/>
+			<AiToolCall
+				name="run_migration"
+				status="error"
+				durationMs={14_200}
+				defaultExpanded
+				args={'{ "name": "amounts_to_cents" }'}
+				error={"SQLSTATE 23505: duplicate key value violates unique constraint"}
+			/>
+		</Stack>
+	)
+}
 ```
 
 ### What it produced
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<AiArtifact title="totals.ts" subtitle="TypeScript" copyText={code} onDownload={save}>
-  <AiCodeBlock code={code} language="TypeScript" showLineNumbers highlightLines={[2, 8]} />
-</AiArtifact>
-
-<AiSources sources={sources} defaultExpanded />
-<AiSources sources={sources} variant="avatars" />
+import { useState } from "react"
+import { FileTextIcon } from "lucide-react"
+
+import { Stack } from "themelia-ui/base/structure"
+import { Text } from "themelia-ui/base/typography"
+import { AiArtifact, AiAttachment, AiCodeBlock, AiSources } from "themelia-ui/features/ai-chat"
+
+import { SAMPLE_CODE, SOURCES, STAGED } from "./data"
+
+export default function Output() {
+	const [attachments, setAttachments] = useState(STAGED)
+	const [log, setLog] = useState<string[]>([])
+
+	const note = (line: string) => setLog((lines) => [line, ...lines].slice(0, 4))
+
+	return (
+		<>
+			<Stack gap="lg">
+				<AiArtifact
+					title="totals.ts"
+					subtitle="TypeScript · 11 lines"
+					icon={FileTextIcon}
+					copyText={SAMPLE_CODE}
+					onDownload={() => note("download")}
+					onOpen={() => note("open artifact")}
+				>
+					<AiCodeBlock
+						code={SAMPLE_CODE}
+						language="TypeScript"
+						showLineNumbers
+						highlightLines={[2, 8]}
+						hideHeader
+					/>
+				</AiArtifact>
+
+				<AiSources sources={SOURCES} defaultExpanded />
+				<AiSources sources={SOURCES} variant="avatars" />
+
+				<Stack direction="horizontal" gap="md" wrap>
+					{attachments.map((attachment) => (
+						<AiAttachment
+							key={attachment.id}
+							name={attachment.name}
+							meta={attachment.meta}
+							kind={attachment.kind}
+							progress={attachment.progress}
+							onOpen={() => note(`open ${attachment.name}`)}
+							onRemove={() =>
+								setAttachments((current) => current.filter((item) => item.id !== attachment.id))
+							}
+						/>
+					))}
+					<AiAttachment name="broken.zip" meta="upload failed" kind="archive" errored />
+				</Stack>
+			</Stack>
+
+			{log.length > 0 && (
+				<Stack gap="none">
+					{log.map((line, index) => (
+						<Text key={`${line}-${index}`} size="xs" type="secondary">{line}</Text>
+					))}
+				</Stack>
+			)}
+		</>
+	)
+}
 ```
 
 ### Asking first
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<AiConfirmation
-  title="Run the backfill on 4,102 invoices"
-  description="Rewrites every amount into cents. Not reversible."
-  tone="destructive"
-  status={status}
-  onApprove={approve}
-  onReject={reject}
-/>
+import { useState } from "react"
+import { SparklesIcon } from "lucide-react"
+
+import { Button } from "themelia-ui/base/buttons"
+import { Stack } from "themelia-ui/base/structure"
+import { AiAgent, AiConfirmation } from "themelia-ui/features/ai-chat"
+
+export default function Approval() {
+	const [approval, setApproval] = useState<"pending" | "approved" | "rejected">("pending")
+
+	return (
+		<Stack gap="lg">
+			<AiConfirmation
+				title="Run the backfill on 4,102 invoices"
+				description="Rewrites every stored amount into cents. There is no undo."
+				tone="destructive"
+				status={approval}
+				onApprove={() => setApproval("approved")}
+				onReject={() => setApproval("rejected")}
+			/>
+			{approval !== "pending" && (
+				<Stack direction="horizontal" gap="md">
+					<Button type="button" tone="neutral" buttonStyle="outline" onClick={() => setApproval("pending")}>
+						Ask again
+					</Button>
+				</Stack>
+			)}
+			<AiAgent name="Atlas" subtitle="model-large" status="working" variant="card" />
+			<AiAgent name="Scribe" icon={SparklesIcon} tone="success" status="done" />
+		</Stack>
+	)
+}
 ```