@artooi/ag-ui-web-component 0.28.0 → 0.30.0

package/README.md

@@ -49,7 +49,13 @@ No framework, no Django, no admin specifics live here. Downstream consumers (e.g
 - [New chat and collapse](#new-chat-and-collapse)
   - [Collapsing to the launcher](#collapsing-to-the-launcher)
 - [Tool-call display modes](#tool-call-display-modes)
+- [Delegated sub-agents](#delegated-sub-agents)
 - [Markdown rendering](#markdown-rendering)
+- [Follow-up suggestions](#follow-up-suggestions)
+- [Editing a gated call before approving it](#editing-a-gated-call-before-approving-it)
+- [Localizing the timestamps](#localizing-the-timestamps)
+- [Message actions: copy, retry, feedback](#message-actions-copy-retry-feedback)
+- [Quoting a selection](#quoting-a-selection)
 - [Run notices: compaction and agent skills](#run-notices-compaction-and-agent-skills)
 - [Skills: prompt chips and slash palette](#skills-prompt-chips-and-slash-palette)
 - [MPA durability: surviving full page reloads](#mpa-durability-surviving-full-page-reloads)
@@ -156,7 +162,7 @@ another origin, add `credentials="include"` too; see
 | --- | --- | --- |
 | `endpoint` | `endpoint` | The AG-UI endpoint URL. Required to send. Reflecting getter + setter. |
 | `credentials` | `credentials` | Cookie policy for every request the element makes: `omit` / `same-origin` / `include`. Unset means the browser default (`same-origin`), which sends no cookies cross-origin. See [Authenticating requests](#authenticating-requests). |
-| `title-text` | — | Header label; defaults to `"Assistant"`. The only **observed** attribute (live-updates the header). |
+| `title-text` | — | Header label; defaults to `"Assistant"`. Live: writing it after the element connects re-labels the header. See [When each attribute is read](#when-each-attribute-is-read). |
 | `data-tool-display` | `toolDisplay` | Tool-call card detail: `inline` / `minimal` / `compact` / `full` (default `full`). |
 | `data-text-animation` | — | Incoming-text reveal: `none` (default) / `fade` / `word`. |
 | `data-prompt-chips` | — | Present (bare, or any value but `"false"`) to surface skills as chips. |
@@ -177,6 +183,16 @@ another origin, add `credentials="include"` too; see
 | `data-icon-url` | — | Header (and launcher) icon image URL. A slotted `slot="icon"` wins; see [Header & launcher icon](#header-and-launcher-icon). |
 | `data-launcher-icon-url` | — | Icon image URL for the collapsed launcher only, when it should differ from the header's. Falls back to `data-icon-url`; a slotted `slot="launcher"` wins over both. |
 | `data-unread-badge` | — | **On by default.** `="false"` hides the launcher's unread badge; the count and the `ag-ui-unread` event keep running. See [Collapsing to the launcher](#collapsing-to-the-launcher). |
+| `data-quote-selection` | — | **On by default.** `="false"` stops the transcript offering to quote a selection. `quote()` keeps working either way. See [Quoting a selection](#quoting-a-selection). |
+| `data-message-actions` | — | **All on by default.** A comma list of the actions a finished answer keeps: `copy` / `retry` / `feedback` (e.g. `"copy,retry"`). `="false"` removes the row entirely. See [Message actions](#message-actions-copy-retry-feedback). |
+| `data-max-tool-rounds` | — | Upper bound on frontend tool-call → re-run rounds within one send (default 10; a value below 1 is ignored). Raise it for a page-driving agent whose turn takes many small steps. See [The run loop](#the-run-loop-and-the-ag-ui-client). |
+| `data-page-actions` | — | Opt-in built-in page-action tools: a comma list of `scroll` / `drag` (e.g. `"scroll,drag"`). See [Page-action tools](#page-action-tools). |
+| `data-side` | — | CSS-only, for `placement="sidebar"`: which edge it docks to — `right` (default) / `left`. |
+| `data-answer-well` | — | CSS-only boolean: box each assistant turn (its text, tool cards, and thinking) in one bordered "well". Off by default. See [The answer well](#the-answer-well). |
+| `collapsed` | `collapsed` | Reflected boolean; collapses the widget to its [launcher](#collapsing-to-the-launcher) (a rail under `placement="sidebar"`, the header bar under `embedded` / `page`). Persisted per-tab in `sessionStorage`. |
+| `theme` | — | CSS-only: `light` (default) / `dark` / `auto` / `code`. |
+| `density` | — | CSS-only: `comfortable` (default) / `compact`. |
+| `placement` | — | CSS-only: `floating` (default) / `bottom-left` / `side` / `sidebar` / `full` / `page` / `embedded`. |
 
 Each header control also takes its own icon slot — `icon-history`, `icon-checkpoints`,
 `icon-new`, `icon-collapse` — with the built-in glyph as the fallback, so a host can project a
@@ -188,19 +204,39 @@ same way: `icon-send`, `icon-stop`, `icon-attach`, `icon-voice`.
   <svg slot="icon-new" width="16" height="16"><!-- ... --></svg>
 </ag-ui-chat>
 ```
-| `data-page-actions` | — | Opt-in built-in page-action tools: a comma list of `scroll` / `drag` (e.g. `"scroll,drag"`). See [Page-action tools](#page-action-tools). |
-| `data-side` | — | CSS-only, for `placement="sidebar"`: which edge it docks to — `right` (default) / `left`. |
-| `data-answer-well` | — | CSS-only boolean: box each assistant turn (its text, tool cards, and thinking) in one bordered "well". Off by default. See [The answer well](#the-answer-well). |
-| `collapsed` | `collapsed` | Reflected boolean; collapses the widget to its [launcher](#collapsing-to-the-launcher) (a rail under `placement="sidebar"`, the header bar under `embedded` / `page`). Persisted per-tab in `sessionStorage`. |
-| `theme` | — | CSS-only: `light` (default) / `dark` / `auto` / `code`. |
-| `density` | — | CSS-only: `comfortable` (default) / `compact`. |
-| `placement` | — | CSS-only: `floating` (default) / `bottom-left` / `side` / `sidebar` / `full` / `page` / `embedded`. |
 
-**Properties** (JS only, not attributes): `headers`, `getHeaders`, `allowImages`, `autoConfirm`,
-`confirmPredicate`, `askUser`, `agentFactory`, `getTools`, `getContext`, `routeMap`, `navigate`,
-`getPageMap`, `autoInjectPageMap`, `conversationStore`, `uploadHandler`, `transcribeHandler`,
-`navigationResult`, `skillContext`, `toolSummaries`, `strings`, `resolvePageTarget`, plus the
-mirrors `endpoint` / `userKey` / `toolDisplay` / `collapsed` / `credentials`.
+#### When each attribute is read
+
+The element observes two groups of attributes, and they behave differently once it is in the DOM.
+Nothing outside those groups is observed: a CSS-only attribute (`theme`, `density`, `data-side`,
+`data-answer-well`) is read by the stylesheet rather than by script, and `endpoint`,
+`data-tool-display`, `data-text-animation`, `data-runs-url`, `data-page-actions`,
+`data-message-actions`, `data-max-tool-rounds`, `data-unread-badge` and `data-quote-selection` are
+re-read at each use, so a late write to any of those simply takes effect. The one attribute in
+neither camp is `data-launcher-icon-url`: it is read while the element connects, like the group
+below, but is not observed, so a late write is inert and says nothing.
+
+**Live attributes.** Written at any time, before or after the element connects, and acted on
+either way: `title-text`, `placement`, `credentials`, `user-key`.
+
+**Connect-time attributes.** Read once, while the element connects, to decide what chrome exists at
+all — the tray, the mic, the skills menu, the header mark. Writing one afterwards has **no effect**;
+the element logs a console warning naming the attribute rather than failing silently, because the
+symptom is an affordance that never appears and that reads as a broken component. Set them before
+the element enters the DOM, or remove and re-insert it. See
+[Framework hosts](#framework-hosts-configure-before-you-insert), where the boundary bites hardest.
+The list: `data-attachments-url`, `data-attachment-accept`, `data-attachment-max-bytes`,
+`data-transcribe-url`, `data-threads-url`, `data-threads-cache`, `data-tools-url`,
+`data-skills-url`, `data-skills`, `data-prompt-chips`, `data-slash-commands`, `data-theme-toggle`,
+`data-strings`, `data-icon-url`.
+
+**Properties** (JS only, not attributes): `headers`, `getHeaders`, `trustedOrigins`, `allowImages`,
+`autoConfirm`, `confirmPredicate`, `askUser`, `askUserRenderer`, `approvalRenderer`,
+`approveWithEdits`, `agentFactory`, `getTools`, `getContext`, `routeMap`, `navigate`, `getPageMap`,
+`autoInjectPageMap`, `conversationStore`, `uploadHandler`, `transcribeHandler`, `navigationResult`,
+`skillContext`, `toolSummaries`, `formatToolPayload`, `formatRelativeTime`, `strings`,
+`resolvePageTarget`, `sharedState`, plus the read-only `unread` and `unhandledActivityTypes`, and
+the attribute mirrors `endpoint` / `userKey` / `toolDisplay` / `collapsed` / `credentials`.
 
 `headers` and `getHeaders` authenticate **every** request the element makes, not only the agent
 run; `getHeaders` is the one to use for a credential that rotates. See
@@ -220,15 +256,20 @@ the django-ag-ui `@tool` registry), whose schema never reaches the browser — e
 labels are fetched automatically — per card, `x-summary` → an explicit
 `toolSummaries` entry → the fetched catalog → the raw name.
 
-**Properties** (selected): `sharedState` — AG-UI shared state (documented under Tools & state).
+`sharedState` is AG-UI shared state, documented under
+[the run loop](#the-run-loop-and-the-ag-ui-client); `unread` and `unhandledActivityTypes` are
+read-only counters, covered under [the unread badge](#the-unread-badge) and
+[finding out what arrived](#finding-out-what-arrived).
 
 Code blocks in an agent's answer carry a **copy button**, revealed on hover or
 keyboard focus and styleable via the `code-copy` part. Override its labels with
 the `copyCode` / `copied` / `copyFailed` strings.
 
-**Methods**: `registerTool`, `registerPageState`, `setSkills`, `sendMessage`, `attachFile`,
-`appendMessage`, `newChat`, `setCollapsed`, `toggleCollapsed`, `toggleTheme`, `openThreads`,
-`openCheckpoints`, `reload`.
+**Methods**: `registerTool`, `registerPageState`, `registerActivityRenderer`, `setSkills`,
+`sendMessage`, `attachFile`, `appendMessage`, `retryLastTurn`, `quote`, `offerQuoteInPage`,
+`enableCharts`, `newChat`, `setCollapsed`, `toggleCollapsed`, `toggleTheme`, `openThreads`,
+`openCheckpoints`, `closeCheckpoints`, `toggleCheckpoints`, `reload`, and the deprecated
+`registerStateHook` (renamed to `registerPageState`).
 
 ### Sending from your own UI
 
@@ -480,7 +521,12 @@ an AG-UI `AbstractAgent`. On the first send the element builds a client (via the
    render into a bubble; each `TOOL_CALL_END` becomes a tool-call card.
 3. Any **frontend** tool calls collected during the run are executed locally, their results are
    appended as `tool` messages, and the agent is re-run with the results.
-4. This repeats until the agent stops calling frontend tools, bounded by `MAX_TOOL_ROUNDS`.
+4. This repeats until the agent stops calling frontend tools, bounded by `MAX_TOOL_ROUNDS`
+   (10) — raise it with `data-max-tool-rounds`, or `AgUiClientConfig.maxToolRounds` when you
+   drive the client yourself. The default suits a chat whose tools answer questions; a
+   page-driving deployment reaches it legitimately, one round per field filled, and the symptom
+   is not an error but an answer that stops mid-task. A value below 1 is ignored rather than
+   honoured — it would be a send that never runs the agent at all.
 
 Tool calls the client doesn't own (server-side tools the server already executed) are left alone —
 the loop doesn't re-run them, but their streamed `TOOL_CALL_RESULT` is rendered into the tool-call
@@ -561,6 +607,8 @@ transcript as a resolved record after the decision:
 - **Confirm** → the handler runs and the result is posted back.
 - **Cancel** → a `"User declined the action."` result is posted; the agent acknowledges on its
   next turn.
+- **Always allow** → the handler runs *and* this tool stops prompting for the rest of the
+  session. See below for when this button appears.
 
 Whether a call is gated is decided in this order:
 
@@ -568,9 +616,27 @@ Whether a call is gated is decided in this order:
 2. Else if `chat.confirmPredicate` is set, its boolean return is authoritative — given the tool
    name + parsed args it decides per-call (so one tool can be instant for some args and confirmed
    for others, which a static flag can't express).
-3. Else the element falls back to [`isDestructive(parameters)`](src/tools/is_destructive.ts),
+3. Else if the user has waived this tool name for the session, the call runs.
+4. Else the element falls back to [`isDestructive(parameters)`](src/tools/is_destructive.ts),
    which reads the `x-destructive` JSON-Schema flag.
 
+#### "Always allow", and why only sometimes
+
+A prompt that is approved nearly every time is not a decision, it is a speed bump — and the
+reflex it trains is what makes the rare refusal easy to miss. Anthropic published that users
+approve **~93%** of Claude Code permission prompts manually and called interactive confirmation
+*"behaviorally unreliable as a sole safety mechanism"* on that basis. The waiver exists so the
+prompts that remain still mean something.
+
+**The button is offered only on cards raised by step 4** — the `x-destructive` default. Where
+`confirmPredicate` is what gated the call, there is no button, because that predicate is
+documented as authoritative and letting one click retire it would silently defeat a host policy.
+The offer and the allowlist sit on the same path, so there is no dead button either.
+
+The waiver is **per tool name and per element**, held in memory and never persisted. A session
+decision that outlived the tab would be a permanent grant made by one click — which is what
+`autoConfirm` already exists to say deliberately. It is cleared when the element goes away.
+
 AG-UI has no built-in risk flag, so destructiveness is carried as a JSON-Schema extension at the
 **schema root**: `parameters["x-destructive"] = true` (use the exported `X_DESTRUCTIVE_KEY`
 constant). There is no parallel metadata channel and no name heuristic — destructiveness is exactly
@@ -1009,6 +1075,67 @@ it runs again every time the conversation is restored.
 
 ---
 
+## Drawing other things the server pushes
+
+`activityType` is an open string the protocol does not enumerate — `"chart"` is
+just the one the component ships a renderer for. Register your own and the
+server can push anything it likes into the transcript:
+
+```js
+chat.registerActivityRenderer({
+  type: "build_status",
+  render: (content) => {
+    const el = document.createElement("div");
+    el.className = "build";
+    el.textContent = `Build ${content.status}`;
+    return el;   // return null for content not worth drawing
+  },
+});
+```
+
+**`render` runs again on every thread load**, so it carries the same contract as
+a client tool's `render`: a pure function of `content`, deterministic, and free
+of effects outside the node it returns. Activities are materialised into
+`role: "activity"` messages and persisted with the transcript, so a renderer that
+writes to the page instead of returning DOM fires again on every restore.
+
+The component places what you return, keyed by the activity's `messageId`, so a
+server repeating an id **replaces** your node rather than adding a second one —
+the same in-place update charts get. Returning `null` removes whatever was there:
+live and reload should agree, and the stored content is the version that could
+not be drawn.
+
+`chart` and `compaction` are registrations exactly like yours, not privileged
+branches, so registering either name **replaces the built-in**.
+
+### Which carrier should the server use?
+
+AG-UI leaves exactly two payload names open, and they are not
+interchangeable:
+
+| | Carrier | Reaches | Persisted | Replayed |
+| --- | --- | --- | --- | --- |
+| **Content** | `ACTIVITY_SNAPSHOT` | the transcript | yes | yes |
+| **Imperative** | `CUSTOM` | your page, as [`ag-ui-custom`](#host-seams-the-spa-story) | no | no |
+
+⇒ **Content has a place in the conversation and should come back. An imperative
+has no place and no meaning once acted on** — replaying "refetch the board" on
+every thread load is a bug, not a feature. If it has to survive a reload, it is
+content.
+
+### Finding out what arrived
+
+An activity nobody registered for draws nothing and logs nothing — that is the
+protocol's own answer, and warning would fire on every forward-compatible
+server. But silence is hard to debug, so the names are readable:
+
+```js
+chat.unhandledActivityTypes; // ["pydantic_ai_thinking", …]
+```
+
+Note `"chart"` appears there until you call `enableCharts(["activity"])`, which
+is the honest answer to "I pushed a chart and nothing happened".
+
 ## Tool-call display modes
 
 How much a tool-call card shows is set via the `data-tool-display` attribute (or `toolDisplay`
@@ -1031,6 +1158,42 @@ visible. Style them via the `tool-card-args` / `tool-card-result` parts, their h
 transcript, the way `data-answer-well` does — the modes are pure visibility over one DOM shape,
 selected by the shadow CSS from the host attribute.
 
+### Drawing a card's body yourself
+
+A thirty-field result is a wall of JSON where a host wanted a table, or a
+sentence. `formatToolPayload` is the seam: it is asked about each region of each
+card and may return a `Node` to take it over, a `string` to replace its text, or
+`null` to leave the built-in pretty-print alone.
+
+```js
+chat.formatToolPayload = (payload) => {
+  if (payload.kind !== "result" || payload.toolName !== "list_orders") {
+    return null; // everything else keeps the default rendering
+  }
+  const table = document.createElement("table");
+  // ... build it from JSON.parse(payload.text)
+  return table;
+};
+```
+
+Both halves come through the same hook, told apart by `kind`: `arguments`
+carries the parsed record the call was made with, `result` the raw string the
+tool returned plus the outcome it settled on. A region a formatter took over is
+marked `data-formatted`, which relaxes the preformatted whitespace the default
+JSON block relies on — a table would otherwise inherit it as mangled cell
+spacing. Whitespace only: the card's face, frame and scroll cap stay, so one long
+payload still cannot stretch the transcript, and a host wanting different
+typography restyles the `tool-card-result` part.
+
+This is **presentation, not translation.** The card and the model already read
+separate copies of a tool result — the model's is maintained by `@ag-ui/client`
+from the same event — so a formatter changes what the person reads and nothing
+the agent reads. That is what makes restyling safe here, and it is also why
+*rewording* belongs on the server: renamed there, the new wording reaches the
+model's prose too, instead of leaving the card disagreeing with the answer beside
+it. A returned string is set as text, never parsed as markup — this is not a
+second HTML channel into the transcript.
+
 A gated call carries the decision (`approved by you` / `declined by you`, part
 `tool-card-decision`, attribute `data-decision`) — from the client-side confirmation card and
 from the server-side approval interrupt alike. The prompt itself disappears once answered: a
@@ -1057,6 +1220,72 @@ speed; the spin respects `prefers-reduced-motion`).
 
 ---
 
+## Delegated sub-agents
+
+A run that hands work to a sub-agent reads as a stall. The parent's
+`delegate_task` card sits at "running…" for the child's entire duration —
+however many tools the child calls, however long it takes — with nothing on
+screen to say anything is happening.
+
+If your server narrates that, the component draws it. The wire is an ordinary
+AG-UI `CUSTOM` event named `ag_ui.subagent`, carrying:
+
+| Key | Meaning |
+| --- | --- |
+| `delegationId` | the **parent's own `delegate_task` tool-call id** — not the child's run id |
+| `agent` | the child agent's name |
+| `phase` | one of `started`, `tool_call`, `tool_result`, `finished`, `failed` |
+| `status` | a pre-rendered line, ready to show |
+| `tool` | `toolCallId`, `name` and `ok`, on the two tool phases only |
+
+Exactly one `started` opens a delegation and exactly one `finished` or `failed`
+closes it. `ok` is a tri-state: `null` while the child's call runs, `true` on a
+result it accepted, `false` on one that came back to it.
+
+Because the key is the *parent's* call id, the surface attaches to a card that
+already exists rather than floating a second element with the same identity: one
+**collapsed row per delegation**, live, carrying the server's `status` line and
+nothing else, expanding onto the child's own tool calls. A ten-step child costs
+one row until somebody opens it, and there is no second visual language — it
+reads the way tool cards already read.
+
+`status` is why the collapsed row needs no wording of its own. The structured
+keys are there for a host that would rather write its own.
+
+The row shows in **every** [display mode](#tool-call-display-modes), including
+`minimal`. It sits outside the card body rather than in it, because the body is
+what the density modes hide — and a live progress line that only appeared in
+`full` would leave exactly the stall it exists to end. Same reasoning that shows
+a deferred card's arguments whatever the mode.
+
+**A failure carries no exception text on this channel, deliberately** — the same
+reasoning that redacts a `RUN_ERROR`, since an exception's words are written for
+an operator. The detail rides the ordinary tool result for that delegation, which
+lands in the same card's `Result` region a few pixels below. Nothing here invents
+words the server declined to send.
+
+**None of it is persisted.** A `CUSTOM` event never enters the message list, so
+nothing replays on a thread restore — which is the right half of the
+[carrier split](#which-carrier-should-the-server-use): a delegation that was live
+an hour ago is not live now, and replaying its progress would be a lie about a
+run that is over. Reload mid-run and the tool card is still there; the nested
+detail is not. That is the intended behaviour.
+
+Like `ag_ui.invalidate`, this name is **routed** rather than forwarded: it draws
+itself and does not also arrive as an `ag-ui-custom` event. Every other name
+still reaches your page untouched.
+
+Style it through `tool-card-subagent` (the region inside the card), `subagent`,
+`subagent-row`, `subagent-icon`, `subagent-status`, `subagent-steps`,
+`subagent-step`, `subagent-step-icon` and `subagent-step-name`. The two glyph
+states reuse the card's own `--ag-ui-tool-icon-done` / `--ag-ui-tool-icon-error`
+properties and its spinner speed, so re-theming the cards re-themes these. The
+row's own chrome comes from `subAgentWorking` and `subAgentSteps` in
+[`UiStrings`](#internationalization-i18n); everything else on the row is the
+server's text.
+
+---
+
 ## Resizing the panel
 
 The panel carries a drag handle on its leading corner (or leading edge, docked),
@@ -1127,6 +1356,197 @@ reveal). It honours `prefers-reduced-motion` (collapsing to instant).
 
 ---
 
+## Follow-up suggestions
+
+The agent can offer the *next* question, not just answer this one. Registered
+skill chips are static and host-configured, so they can say "summarize this" but
+never "want me to update the shipping address too?" after a tool has run.
+
+The server pushes an `ACTIVITY_SNAPSHOT` under the `suggestions` type — with
+django-ag-ui, `suggestions_activity([...])`. The component draws each prompt as
+a chip; clicking one sends it as the user's message, exactly as if they had
+typed it.
+
+```json
+{ "activityType": "suggestions",
+  "content": { "prompts": ["Update the shipping address too"] } }
+```
+
+**Chips are content.** They ride the same activity envelope as charts, so they
+persist and a reload puts them back, and a set pushed under an id already on
+screen replaces that row rather than adding a second one.
+
+At most **4** prompts of **120** characters each — `MAX_SUGGESTIONS` and
+`MAX_SUGGESTION_CHARS`, both exported. The server-side helper *raises* past
+those bounds while this side silently drops: that asymmetry is deliberate, since
+the producer can report the problem and the client cannot.
+
+Nothing to enable. A `suggestions` activity from a server that pushes one is
+drawn; an `activity_type` this component does not know is ignored, which is what
+the open field is for.
+
+## Editing a gated call before approving it
+
+AG-UI's resume payload carries `editedArgs`, and the protocol gates it on the
+agent's own `approveWithEdits` capability. The approval card can offer it:
+
+```js
+chat.approveWithEdits = true; // your server accepts editedArgs
+```
+
+**Off by default, and an assertion about your server rather than a
+negotiation** — capabilities are not on the wire this component reads, so it
+cannot check. Turned on against a server that ignores `editedArgs`, a user would
+edit arguments it silently discards, which is worse than not offering.
+
+The card then shows the call's arguments as editable JSON. `editedArgs` rides
+the resume payload **only when something actually changed**, so a server can tell
+"approved as proposed" from "approved, but like this" without diffing what it
+already sent. Unparseable JSON, or JSON that is not an object, keeps the card
+open with the reason on it rather than approving the original behind the user's
+back.
+
+Only offered for an interrupt naming a tool call this component holds a card
+for — the card is where the arguments still are.
+
+## Localizing the timestamps
+
+There is **no `Intl` anywhere in this component**. The relative timestamps in the
+thread drawer and checkpoint panel (`"5m ago"`, `"2d ago"`) are deliberately
+locale-neutral: a component that guessed a locale would disagree with the page
+it is embedded in, and being wrong in a second language is worse than being
+neutral in one.
+
+That is a good default and a bad requirement, so it is replaceable:
+
+```js
+const rtf = new Intl.RelativeTimeFormat("de", { numeric: "auto" });
+chat.formatRelativeTime = (ts) =>
+  rtf.format(Math.round((ts - Date.now()) / 60000), "minute");
+```
+
+`relativeTime` is exported too, for a host that wants to build on the built-in
+rather than replace it.
+
+## Message actions: copy, retry, feedback
+
+Every finished assistant message carries a small row of actions beneath it —
+a **sibling** of the bubble, never a child, so the buttons never join the
+message's own text.
+
+- **Retry** re-asks the question. History is truncated to the most recent user
+  message inclusive and the run repeats, so the agent answers what it was asked
+  rather than being told its last answer was wrong.
+- **Copy** puts the message's text on the clipboard, and says so on the button.
+  A refused clipboard permission is reported there too, rather than thrown.
+- **Thumbs up / down** fire `ag-ui-feedback` (wired below) and **store nothing**.
+
+Retry sits on the **last** answer only. Re-running an older turn is branching,
+and for a page-driving agent editing a past turn is not neutral — those turns
+clicked buttons, and re-running turn 3 does not un-save what turn 5 saved.
+
+!!! note
+    A retried turn **re-runs its tools.** The previous attempt already did what
+    it did, and this does not undo it. Confirmation still applies, so a
+    destructive tool asks again — unless the user waived it for this session
+    with *Always allow*.
+
+A failed run gets the same row, with Retry and Copy and no rating: error text is
+what people paste into a bug report, but "the connection dropped" is not a
+statement about answer quality and mixing it into feedback makes that signal say
+less. This is why a dropped connection is still rendered as an **error** rather
+than demoted to a run notice — a notice "never settles, takes no action, and
+carries no controls", and a failure with a way back needs one.
+
+The row can be trimmed, or removed, with `data-message-actions` — a comma list of
+the actions to keep, or `="false"` for none at all:
+
+```html
+<!-- copy only: nothing here listens for a rating, and the surface forbids re-runs -->
+<ag-ui-chat endpoint="/agent/" data-message-actions="copy"></ag-ui-chat>
+```
+
+It is per-action rather than one switch because the three disappear for
+different reasons. Thumbs are only useful to a host listening for
+`ag-ui-feedback`, and two buttons that lead nowhere are worse than none. Retry
+re-runs the agent, which a constrained surface may not permit. Copy is the one
+nobody objects to — and with a single switch, dropping either of the others would
+have cost it too. Nothing survives, and no row is built at all: an empty row
+still takes its margin and still announces itself as a group of actions.
+
+`retryLastTurn()` is public, for a host driving its own message UI.
+
+```js
+chat.addEventListener("ag-ui-feedback", (e) => {
+  analytics.track("assistant_rating", e.detail); // { content, rating }
+});
+
+await chat.retryLastTurn(); // false when there is nothing to ask again
+```
+
+## Quoting a selection
+
+Select any text in the transcript and a small **Quote** offer floats beside it.
+Taking it drops the selection into the composer as a markdown blockquote and
+leaves the caret on a fresh line under it — a quotation is how a question
+narrows to one part of an answer, so nothing is sent until you say what you are
+asking.
+
+Quoting **appends**, after whatever is already typed, so a second quotation is a
+second thing being asked about rather than a replacement for the first. Long
+selections are capped at 500 characters: select-all-then-quote is a gesture the
+transcript already answers, and pasting the whole conversation back costs tokens
+to say nothing.
+
+Set `data-quote-selection="false"` to turn the offer off. The `quote-selection`
+`part` styles it.
+
+### The half that matters: selection in **your** page
+
+The transcript is the easy half. A chat mounted beside a table, a diff or a
+report is sitting in the surface the user actually works in — and *that*
+selection is one no hosted chat can reach.
+
+`offerQuoteInPage()` extends the same select-then-offer gesture to the whole
+page. It is opt-in, because it listens on your document:
+
+```js
+const stop = chat.offerQuoteInPage();       // the whole page
+chat.offerQuoteInPage(document.querySelector("#report")); // or one region
+```
+
+For a deliberate trigger instead of a selection, `quote(text)` is the seam
+underneath:
+
+```js
+// "Ask about this row" — a button on each row of your own table.
+row.querySelector(".ask").addEventListener("click", () => {
+  chat.quote(row.innerText);
+});
+```
+
+`quote()` never sends — pair it with [`sendMessage()`](#sending-from-your-own-ui)
+if you want a one-click "explain this" that skips the composer entirely.
+
+> **Do not write the four-line version of `offerQuoteInPage()`.**
+> A `mouseup` listener that quotes every settled selection appends to the
+> composer on every drag the user made to *read*, to copy, or to fix a typo —
+> and it cannot tell a selection in your prose from one inside the user's own
+> half-typed `<input>`, because Chrome reports a field's internal selection
+> through `document.getSelection()` as an ordinary range over the field's
+> **wrapper**. The text reads back perfectly and nothing about the range says
+> where it came from; the only signal is `document.activeElement`. That guard,
+> plus skipping the widget's own transcript, plus retiring a fixed-position
+> affordance on scroll, is what the method is for.
+
+> **Reading a selection out of a shadow tree takes care too.**
+> Engines disagree about what `document.getSelection()` reports for a selection
+> made *inside* a shadow root: WebKit rescopes the endpoints to the host element,
+> so you get the whole widget and none of the words, while Chromium hands back
+> the shadow nodes directly. `getComposedRanges` settles it, and this component
+> uses it where it exists. `quotableSelection(container, roots)` is exported if
+> you have the same problem in your own component.
+
 ## Run notices: compaction and agent skills
 
 Some things a run does are neither text nor a tool the user asked for — the server condensed
@@ -1467,6 +1887,83 @@ substitute the other way round either, because shared state requires the *agent*
 `STATE_SNAPSHOT`, which is not the host's decision to make. Use state when the two ends edit one
 object; use this when your page owns the data and just needs to know it moved.
 
+**`ag-ui-custom`** *(event)* — the agent sent an AG-UI `CUSTOM` event.
+`detail: { name, value }` (typed `CustomAgentDetail`), both verbatim and uninterpreted.
+
+```js
+chat.addEventListener("ag-ui-custom", (e) => {
+  if (e.detail.name === "invalidate") {
+    void refetch(e.detail.value);
+  }
+  // Any other name: no listener, nothing happens. That is the intended outcome.
+});
+```
+
+`CUSTOM` is one of exactly two AG-UI carriers whose payload name is an open
+string the protocol does not enumerate, and it is the **imperative** one:
+something for your page to *do*. Its sibling `ACTIVITY_SNAPSHOT` carries
+transcript **content**, which is why an activity is materialised into a message,
+persisted with the thread and replayed on restore, and this is not.
+
+**That asymmetry is the rule for choosing between them.** Content has a place in
+the conversation and should replay. An imperative has no place and no meaning
+once acted on — replaying "refetch the board" on every thread load is a bug, not
+a feature. If it must survive a reload, it belongs on the other carrier.
+
+The element takes no view of what a name means and forwards every one, so a name
+it has never heard of reaches you unchanged. A host with no listener for a name
+simply ignores it, which is the graceful outcome an open field exists for.
+
+**`ag-ui-invalidate`** *(event)* — the agent named resources its write moved.
+`detail: { keys, reason }` (typed `InvalidateDetail`).
+
+One `CUSTOM` name routed to its own event so you do not have to string-match;
+every other name still arrives as `ag-ui-custom`. It fires **as each
+announcement arrives**, during the run, and the same keys ride
+`ag-ui-run-finished` again at the end as `invalidated`, de-duplicated.
+
+> **Do not reload the page on this.** The user was probably typing. An
+> agent-triggered reload or a blind refetch into a live form destroys unsaved
+> input, and from their side the page threw their work away on its own. Check
+> first, and offer rather than act:
+
+```js
+chat.addEventListener("ag-ui-invalidate", (e) => {
+  if (formIsDirty()) {
+    showBanner("This data changed. Refresh when you're ready.", e.detail.keys);
+    return;
+  }
+  refetch(e.detail.keys);   // e.detail.keys → ["orders", "orders/42"]
+});
+```
+
+**Keys are opaque and matching is exact.** `orders/42` does not imply `orders` —
+a prefix rule would be the component guessing at a scheme it does not own, and
+`orders/1` would match `orders/11`. A server that wants the collection refreshed
+names it. Your own matching may be hierarchical, because in your vocabulary the
+scheme is known; that is what TanStack query keys are built for.
+
+Already listening on `ag-ui-run-finished`? Upgrading is one line, and the `else`
+is the whole compatibility story:
+
+```js
+if (detail.invalidated.length > 0) refetchOnly(detail.invalidated);
+else if (detail.tools.some((t) => t.side === "server")) refetchEverything();
+```
+
+| Server | Client | Result |
+| --- | --- | --- |
+| old | old | coarse refetch, as today |
+| new | old | the `CUSTOM` event is ignored; coarse refetch still fires |
+| old | new | `invalidated` is empty; the `else` branch runs |
+| new | new | precise, and live during the run |
+
+Nothing negotiates and nothing handshakes, which is what makes this shippable
+across repos with independent release cadences.
+
+**Note:** it reaches **the page that started the run**, during the run. There is one
+response stream per run and no channel to anybody else's browser.
+
 ## Resuming a run
 
 When the server persists run checkpoints (django-ag-ui's `step_store`), a run
@@ -1624,9 +2121,9 @@ re-export point. Internal modules import from leaf paths.
 | `isNavigates(parameters)` | function | Read the `x-navigates` flag. |
 | `createPageActionTools(enabled, resolveTarget)` | function | Build the opt-in `scroll_to` / `drag_and_drop` tools. |
 | `PAGE_ACTIONS` | const | The page-action opt-in tokens (`scroll` / `drag`). |
-| `ResolvePageTarget` | type | `(target) => HTMLElement | null` — the page-target resolver. |
+| `ResolvePageTarget` | type | `(target) => HTMLElement \| null` — the page-target resolver. |
 | `X_DESTRUCTIVE_KEY` / `X_NAVIGATES_KEY` | const | The JSON-Schema extension keys. |
-| `parseToolCatalog(data)` | function | Parse a fetched `data-tools-url` catalog into a `name` → `summary` map. |
+| `parseToolCatalog(data)` | function | Parse a fetched `data-tools-url` catalog into a `Record<string, ToolCatalogEntry>` — whole entries, not bare summaries, so a caller can reach `description` too. Malformed input yields an empty map rather than throwing. |
 | `ToolCatalogEntry` | type | One row of that catalog. |
 | `prettifyToolName(name)` | function | Last fallback of the tool-card label chain (`delete_record` reads as *Delete record*). |
 
@@ -1643,6 +2140,18 @@ re-export point. Internal modules import from leaf paths.
 | `PageState` | type | A page-state binding declaration. |
 | `Skill` | type | A launchable prompt (chip / `/`-command). |
 | `RunFinishedDetail` / `ToolRun` | type | `ag-ui-run-finished` detail: the tools an interaction ran, and which side ran them. |
+| `CustomAgentDetail` | type | `ag-ui-custom` detail: an AG-UI `CUSTOM` event's `name` and `value`, verbatim. |
+| `InvalidateDetail` | type | `ag-ui-invalidate` detail: the resource `keys` that moved, and the `reason`. |
+| `FeedbackDetail` | type | `ag-ui-feedback` detail: the rated message's `content` and the `rating`. |
+| `relativeTime` | function | The built-in locale-neutral timestamp formatter (`"5m ago"`), for a host building on it. |
+| `RelativeTimeFormatter` | type | What `formatRelativeTime` takes: an epoch-ms timestamp in, row text out. |
+| `renderSuggestionChips` | function | Draw a `suggestions` activity as chips that send themselves; `null` when nothing survives. |
+| `suggestionPrompts` | function | The usable prompts in a `suggestions` activity's content, bounded and trimmed. |
+| `attachMessageActions` | function | Give a finished bubble its action row (copy, and feedback when a handler is passed). |
+| `messageActionBar` | function | The empty action row for a bubble, created if it has none — the shared shell both callers use. |
+| `MessageActionsOptions` | type | What `attachMessageActions` takes: `strings`, a `text` source, an optional `onFeedback`. |
+| `ActivityRenderer` | type | Draws one activity from its `content`. Pure: it runs again on every restore. |
+| `ActivityRegistration` | type | What `registerActivityRenderer` takes: `type`, `render`, and an optional `removedNotice`. |
 | `createStateHookTools(binding)` / `StateHook` | deprecated | The former names for `createPageStateTools` / `PageState`. |
 
 ### Durability
@@ -1657,15 +2166,15 @@ re-export point. Internal modules import from leaf paths.
 | `RunIndex` | class | Reads a `data-runs-url` run index and derives its resume / fork endpoints. |
 | `RunRow` | type | One run index row (`{ run_id, thread_id, parent_run_id, started_at, continuable, preview? }`). |
 | `CheckpointMenu` | class | The *Continue a run* panel. |
-| `CheckpointVerb` | type | `"resume" | "fork"`. |
+| `CheckpointVerb` | type | `"resume" \| "fork"`. |
 
 ### Attachments
 
 | Export | Kind | Summary |
 | --- | --- | --- |
 | `uploadAttachment(file, options)` | function | The built-in upload (multipart, progress) → `AttachmentRef`. |
-| `UploadOptions` | type | `{ url, headers?, onProgress?, signal? }`. |
-| `UploadHandler` | type | `(file, onProgress) => Promise<AttachmentRef>` — the `uploadHandler` swap seam (TUS / S3). |
+| `UploadOptions` | type | `{ url, headers?, credentials?, onProgress?, signal? }`. `credentials` is spelled as a fetch mode but carried by `XMLHttpRequest.withCredentials`, so only `"include"` is distinguishable. |
+| `UploadHandler` | type | `(file, onProgress, signal?) => Promise<AttachmentRef>` — the `uploadHandler` swap seam (tus / S3). The signal fires when the tray removes a chip or the element is torn down; a handler that honours it aborts its own transport, so a cancelled upload leaves no orphaned file on the server. |
 | `AttachmentRef` | type | The durable upload ref (`{ id, name, mime, size, url? }`). |
 | `messageAttachments(message)` | function | Read the refs a restored user message carries. |
 
@@ -1674,7 +2183,7 @@ re-export point. Internal modules import from leaf paths.
 | Export | Kind | Summary |
 | --- | --- | --- |
 | `transcribeAudio(audio, options)` | function | The built-in transcription POST (multipart) → the transcript text. |
-| `TranscribeOptions` | type | `{ url, headers? }`. |
+| `TranscribeOptions` | type | `{ url, headers?, credentials? }` — `credentials` as fetch's own cookie mode. |
 | `TranscribeHandler` | type | `(audio) => Promise<string>` — the `transcribeHandler` swap seam (Web Speech, direct-to-provider). |
 
 ### UI & DOM primitives
@@ -1683,25 +2192,34 @@ re-export point. Internal modules import from leaf paths.
 | --- | --- | --- |
 | `ToolCallCard` | class | A live tool-call card for the transcript. |
 | `ToolCallStatus` / `SettledStatus` / `ToolDisplayMode` | type | Card lifecycle states + display mode. |
+| `ToolPayloadFormatter` | type | Draws one region of a card's body (`AgUiChat.formatToolPayload`); `null` falls through to the built-in pretty-print. |
+| `ToolPayload` | type | The region being drawn: `arguments` (the parsed record) or `result` (the raw string and its outcome). |
+| `ToolCallCardOptions` | type | Per-card wiring beyond name / args / label / strings — currently `formatPayload`. |
 | `requestConfirmation(host, request, options?)` | function | Append the inline confirmation card to the transcript. |
 | `ConfirmationRequest` | type | What the card displays. |
-| `ConfirmationOptions` | type | `{ signal?, strings? }` — abort resolves the card as declined; `strings` localizes it. |
+| `ConfirmationOptions` | type | `{ signal?, strings?, onAlwaysAllow? }` — abort resolves the card as declined; `strings` localizes it; passing `onAlwaysAllow` is what adds the third button. |
 | `UiStrings` | type | The flat table of every user-facing string. |
 | `DEFAULT_UI_STRINGS` | const | The English defaults (the override floor). |
 | `mergeUiStrings(overrides)` | function | Merge a partial override over the defaults. |
 | `renderMarkdown(text, options?)` | function | Render sanitized markdown/HTML (marked + DOMPurify). |
 | `RenderMarkdownOptions` | type | `{ allowImages? }` — opt `<img>` back into the sanitized output. |
 | `requestApproval(host, request, options?)` | function | Append the inline approval card that gates a server-side tool. |
-| `ApprovalRequest` | type | What that card displays (`{ message?, toolName? }`). |
-| `ApprovalOptions` | type | `{ signal?, strings? }` — abort resolves the card as denied; `strings` localizes it. |
+| `ApprovalRequest` | type | What that card displays (`{ message?, toolName?, args? }`). |
+| `ApprovalOptions` | type | `{ signal?, strings?, onEdit? }` — abort resolves the card as denied; `strings` localizes it; passing `onEdit` offers the call's arguments for editing and is called only when they actually changed. |
 | `ApprovalRenderer` | type | Replace the built-in approval card outright (`AgUiChat.approvalRenderer`). |
 | `requestQuestion(host, request, options?)` | function | Append the inline `ask_user` card (radios and/or free text). |
 | `QuestionRequest` | type | What that card asks. |
 | `QuestionOptions` | type | `{ signal?, strings? }` — abort resolves it with an empty answer. |
-| `QuestionRenderer` | type | Replace the built-in question card outright (`AgUiChat.questionRenderer`). |
+| `QuestionRenderer` | type | Replace the built-in question card outright (`AgUiChat.askUserRenderer`). |
 | `renderChart(spec)` | function | Draw one spec as a self-contained block, or `null` when it says nothing. |
 | `chartSpecFrom(value)` | function | Read an arbitrary payload into a `ChartSpec`, or `null` if it cannot be drawn honestly. |
 | `ChartSpec` / `ChartSeries` / `ChartKind` | type | A chart as data, one named series, and how it is drawn. |
+| `attachQuoteOffer(options)` | function | The page-side select-then-quote offer, with its guards. `AgUiChat.offerQuoteInPage()` is the one-line form. |
+| `PageQuoteOffer` / `PageQuoteOfferOptions` | type | The live offer (`{ element, detach }`) and what it takes. |
+| `quotableSelection(container, roots, near?)` | function | The current selection when it lies inside `container`, read through the shadow-aware API where the engine has one. `near` is where the gesture ended, used to pick the line the offer hangs from. |
+| `QuotableSelection` | type | `{ text, rect }` — what was selected, and where it sits. |
+| `asQuote(text)` | function | Shape text as a markdown blockquote with a blank line after it. |
+| `MAX_QUOTE_CHARS` | const | The cap a quotation is truncated to (500). |
 | `typeInto` / `highlightThenClick` / `pressThenClick` / `selectOption` / `toggleControl` / `scrollIntoCenterView` / `flash` / `focusWithFlash` / `prefersReducedMotion` | function | Animation primitives. |
 | `fillField` / `clickElement` / `pressButton` / `selectControl` / `setControlValue` / `toggleCheckbox` | function | DOM-driver primitives. |
 | `setNativeValue` / `setNativeChecked` | function | Set a control via its native prototype setter (React-controlled inputs). |
@@ -1716,6 +2234,13 @@ re-export point. Internal modules import from leaf paths.
 | `TOGGLE_EVENT` | The collapse-toggle CustomEvent name (`ag-ui-toggle`). |
 | `UNREAD_EVENT` | The unread-count CustomEvent name (`ag-ui-unread`). |
 | `RUN_FINISHED_EVENT` | The interaction-finished CustomEvent name (`ag-ui-run-finished`). |
+| `CUSTOM_AGENT_EVENT` | The agent-`CUSTOM` CustomEvent name (`ag-ui-custom`). |
+| `INVALIDATE_EVENT` | The resource-invalidation CustomEvent name (`ag-ui-invalidate`). |
+| `FEEDBACK_EVENT` | The message-rating CustomEvent name (`ag-ui-feedback`). |
+| `SUGGESTIONS_ACTIVITY_TYPE` | The `activity_type` carrying follow-up prompts (`suggestions`). |
+| `MAX_SUGGESTIONS` | Most prompts one push draws (4). Mirrors the server's cap. |
+| `MAX_SUGGESTION_CHARS` | Longest one prompt may be (120). Mirrors the server's cap. |
+| `INVALIDATE_CUSTOM_NAME` | The AG-UI `CUSTOM` `name` that carries one (`ag_ui.invalidate`). |
 | `ATTACHMENT_EVENT` | The attachments-changed CustomEvent name (`ag-ui-attachments`). |
 | `STATE_EVENT` | The shared-state CustomEvent name (`ag-ui-state`). |
 | `CHART_ACTIVITY_TYPE` | The `ACTIVITY_SNAPSHOT` type a server sets to push a chart. |
@@ -1723,8 +2248,9 @@ re-export point. Internal modules import from leaf paths.
 | `COMPACTION_ACTIVITY_TYPE` | The `ACTIVITY_SNAPSHOT` type reporting a trimmed history. |
 | `LOAD_CAPABILITY_TOOL` | The agent-side capability-loading tool's name. |
 | `MESSAGE_ROLE` | Message role constants. |
+| `MESSAGE_ACTIONS` | The message-action tokens `data-message-actions` selects by (`copy` / `retry` / `feedback`). |
 | `TOOL_CALL_STATUS` | Tool-call card status constants. |
-| `TOOL_DISPLAY` | Tool-call display-mode constants (`minimal` / `compact` / `full`). |
+| `TOOL_DISPLAY` | Tool-call display-mode constants (`inline` / `minimal` / `compact` / `full`). |
 | `X_CONFIRM_KEY` | Confirmation-prompt key: on a tool's JSON Schema for a client-side confirmation, and in an AG-UI interrupt's `metadata` for a server-side approval. |
 | `X_SUMMARY_KEY` | JSON-Schema key carrying a short tool-card label. |
 | `MAX_TOOL_ROUNDS` | Upper bound on tool-call → re-run rounds per send. |
@@ -1855,15 +2381,18 @@ component sets, so a new one cannot ship undocumented.
 
 | Feature | Parts |
 | --- | --- |
-| Shell | `panel`, `header`, `title`, `icon`, `header-controls`, `messages`, `empty`, `pending`, `stopped`, `resize-handle` |
+| Shell | `panel`, `header`, `title`, `icon`, `header-controls`, `messages`, `empty`, `pending`, `stopped`, `jump-latest`, `resize-handle` |
 | Header buttons | `header-button` on each, plus `history-button`, `checkpoints-button`, `new-button`, `collapse-button`, `theme-toggle` |
 | Collapsed widget | `launcher`, `launcher-icon`, `launcher-badge` |
 | Answers | `answer` (the per-turn group), `message` (plus `message-user`, `message-assistant`), `code-copy` |
 | Reasoning | `thoughts`, `thoughts-toggle`, `thoughts-body`, `thoughts-label` |
-| Run notices | `run-notice` (plus `run-notice-interrupted`, `run-notice-attachment-pending`, `run-notice-compaction`, `run-notice-skill`), `run-notice-icon`, `run-notice-text` |
-| Tool cards | `tool-card`, `tool-card-head`, `tool-card-icon`, `tool-card-name`, `tool-card-status`, `tool-card-decision`, `tool-card-toggle`, `tool-card-body`, `tool-card-section` (plus `tool-card-args-section`, `tool-card-result-section`), `tool-card-section-label` (plus `tool-card-args-label`, `tool-card-result-label`), `tool-card-args`, `tool-card-result`, `tool-card-approval` |
-| Client-side confirmation | `confirm`, `confirm-body`, `confirm-args`, `confirm-actions`, `confirm-button` (plus `confirm-confirm`, `confirm-cancel`) |
-| Server-side approval | `approval`, `approval-body`, `approval-actions`, `approval-button` (plus `approval-approve`, `approval-deny`) |
+| Follow-up suggestions | `suggestions`, `suggestion-chip` |
+| Message actions | `message-actions`, `message-action` (plus `message-action-retry`, `message-action-copy`, `message-action-up`, `message-action-down`) |
+| Run notices | `run-notice` (plus `run-notice-interrupted`, `run-notice-attachment-pending`, `run-notice-compaction`, `run-notice-skill`, `run-notice-history-replaced`, `run-notice-chart-undrawable`), `run-notice-icon`, `run-notice-text` |
+| Tool cards | `tool-card`, `tool-card-head`, `tool-card-icon`, `tool-card-name`, `tool-card-status`, `tool-card-decision`, `tool-card-toggle`, `tool-card-body`, `tool-card-section` (plus `tool-card-args-section`, `tool-card-result-section`), `tool-card-section-label` (plus `tool-card-args-label`, `tool-card-result-label`), `tool-card-args`, `tool-card-result`, `tool-card-approval`, `tool-card-subagent` |
+| Delegated sub-agents | `subagent`, `subagent-row`, `subagent-icon`, `subagent-status`, `subagent-steps`, `subagent-step`, `subagent-step-icon`, `subagent-step-name` |
+| Client-side confirmation | `confirm`, `confirm-body`, `confirm-args`, `confirm-actions`, `confirm-button` (plus `confirm-confirm`, `confirm-cancel`, `confirm-always`) |
+| Server-side approval | `approval`, `approval-body`, `approval-actions`, `approval-button` (plus `approval-approve`, `approval-deny`), `approval-edit`, `approval-args`, `approval-error` |
 | Typed question | `question`, `question-body`, `question-options`, `question-choice`, `question-choice-text`, `question-radio`, `question-input`, `question-actions`, `question-button` |
 | Composer | `composer`, `composer-surface`, `composer-tools`, `input`, `send`, `attach-button`, `voice-button` |
 | Attachments | `attachment-tray`, `attachment-chips` (the read-only chips on sent bubbles), and the shared chip parts `attachment-chip`, `attachment-chip-icon`, `attachment-chip-name`, `attachment-chip-size`, `attachment-chip-bar`, `attachment-chip-bar-fill`, `attachment-chip-retry`, `attachment-chip-remove` |