@artooi/agents-web-components 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,4398 @@
-# Temporary Holding Version
+# @artooi/agents-web-components
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![CI](https://github.com/Artui/agents-web-components/workflows/tests/badge.svg)](https://github.com/Artui/agents-web-components/actions/workflows/tests.yml)
+[![npm](https://img.shields.io/npm/v/@artooi/agents-web-components.svg)](https://www.npmjs.com/package/@artooi/agents-web-components)
+[![License](https://img.shields.io/npm/l/@artooi/agents-web-components.svg)](https://github.com/Artui/agents-web-components/blob/main/LICENSE)
+
+A **framework-free** `<ag-ui-chat>` Web Component over the [AG-UI](https://docs.ag-ui.com)
+protocol. Drop it into any page — SPA or MPA, any framework or none — point it at an AG-UI
+endpoint, and you get a streaming chat sidebar that can call tools you register in the browser.
+
+It wraps [`@ag-ui/client`](https://www.npmjs.com/package/@ag-ui/client)'s `HttpAgent` and ships:
+
+- A Custom Element with a self-contained Shadow DOM chat UI (header, scrolling transcript,
+  input row), themeable via CSS custom properties.
+- A pluggable **client-side tool registry** — `registerTool({ name, description, parameters,
+  handler })`; every registered tool is added to each run's `RunAgentInput.tools`.
+- Generic **DOM-driver primitives** (`fillField`, `clickElement`, `setControlValue`) and
+  **animation primitives** (`typeInto`, `highlightThenClick`, …) so the agent can drive the page
+  at human-readable speed.
+- An **inline confirmation card** that intercepts tool calls needing confirmation (those whose
+  JSON Schema carries `x-destructive: true`, or a per-call `confirmPredicate`) before the handler
+  runs — rendered right in the transcript, never a modal overlay.
+- **Markdown + HTML rendering** of assistant replies (sanitized `marked` + DOMPurify), with
+  themes, density/placement presets, incoming-text animations, tool-call display modes, an
+  animated thinking indicator, and an opt-in **skills** palette (prompt chips + `/`-commands).
+- A **new-chat** button and a **collapse** toggle built into the header.
+- An **MPA durability story**: a durable conversation store, a stable thread id, and a resumable
+  run loop that survives full page reloads (`x-navigates` + `navigationResult`).
+- **Host seams** for SPAs: a route map, an auto-injected page map, page state, and an optional
+  `navigate()` callback.
+
+No framework, no Django, no admin specifics live here. Downstream consumers (e.g.
+`django-admin-agent`) register their own tool handlers on top via the pluggable registry.
+
+This package is the successor of `@artooi/ag-ui-web-component`. Coming from it? See
+[Moving from `@artooi/ag-ui-web-component`](#moving-from-artooiag-ui-web-component).
+
+---
+
+## Table of contents
+
+- [Install](#install)
+- [Quickstart](#quickstart)
+- [Authenticating requests](#authenticating-requests)
+- [Core concepts](#core-concepts)
+  - [The run loop and the AG-UI client](#the-run-loop-and-the-ag-ui-client)
+  - [Stopping a run](#stopping-a-run)
+  - [Registering tools](#registering-tools)
+  - [Inline confirmation (`x-destructive` / `x-confirm` / `confirmPredicate`)](#inline-confirmation-x-destructive--x-confirm--confirmpredicate)
+  - [DOM-driver and animation primitives](#dom-driver-and-animation-primitives)
+  - [Page-action tools](#page-action-tools)
+- [New chat and collapse](#new-chat-and-collapse)
+  - [Maximizing the panel](#maximizing-the-panel)
+  - [Collapsing to the launcher](#collapsing-to-the-launcher)
+  - [Collapsing to a bottom bar](#collapsing-to-a-bottom-bar)
+- [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)
+  - [Who the stored conversation belongs to (`user-key`)](#who-the-stored-conversation-belongs-to-user-key)
+  - [Mounting more than one chat on a page](#mounting-more-than-one-chat-on-a-page)
+- [Host seams: the SPA story](#host-seams-the-spa-story)
+  - [Where the user is: the place chip](#where-the-user-is-the-place-chip)
+- [Public API surface](#public-api-surface)
+- [Theming, density, and placement](#theming-density-and-placement)
+  - [Themes](#themes)
+- [Internationalization (i18n)](#internationalization-i18n)
+- [Building the bundle](#building-the-bundle)
+- [Moving from `@artooi/ag-ui-web-component`](#moving-from-artooiag-ui-web-component)
+- [Compatibility](#compatibility)
+
+---
+
+## Install
+
+```bash
+npm install @artooi/agents-web-components
+```
+
+The package ships two builds (see [`package.json` exports](package.json)):
+
+| Entry | What it is | When to use |
+| --- | --- | --- |
+| `@artooi/agents-web-components` | ESM library build; `@ag-ui/*` stay **external** | You bundle the app yourself (Vite, webpack, esbuild) and want to dedupe `@ag-ui/*`. |
+| `@artooi/agents-web-components/chat` | The same library build's `<ag-ui-chat>` entry: `AgUiChat` and `defineChat` | Beside the root entry; the two share one module instance, so import from both freely. |
+| `@artooi/agents-web-components/bundle` | ESM bundle with `@ag-ui/*` **inlined**, minified | Drop in via a single `<script type="module">` with no build step. |
+
+### The vendored-bundle story
+
+The `/bundle` entry inlines every dependency into one self-contained ESM file
+(`dist/agents-web-components.bundle.js`). This is the artefact intended for **vendoring**: a host
+that can't (or won't) run a JS build — for example a Django app — copies the built bundle into its
+`static/` directory and serves it directly. `django-admin-agent` re-vendors a pinned built bundle
+on every release. For SPA hosts that already have a bundler, import the bare package name instead
+so `@ag-ui/client` / `@ag-ui/core` are deduped against the rest of your app.
+
+---
+
+## Quickstart
+
+Drop the element into your page and register the tools the agent may call:
+
+```html
+<script type="module">
+  import { fillField, clickElement, X_DESTRUCTIVE_KEY } from "@artooi/agents-web-components";
+  import { defineChat } from "@artooi/agents-web-components/chat";
+
+  // Register the <ag-ui-chat> Custom Element. An explicit call, not an import
+  // side effect, so importing the package defines nothing. Idempotent; it throws
+  // if another class already holds the tag (a second copy of the element).
+  defineChat();
+
+  const chat = document.querySelector("ag-ui-chat");
+
+  // Extra request headers (e.g. CSRF), sent with every request the element makes.
+  // For a credential that rotates, set chat.getHeaders instead - it is consulted
+  // per request. See "Authenticating requests".
+  chat.headers = { "X-CSRFToken": getCsrfToken() };
+
+  // A non-destructive tool: fills a text field with a typing animation.
+  chat.registerTool({
+    name: "fill_field",
+    description: "Fill a text input by id with a value.",
+    parameters: {
+      type: "object",
+      properties: { field: { type: "string" }, value: { type: "string" } },
+      required: ["field", "value"],
+    },
+    handler: async ({ field, value }) => {
+      await fillField(document.getElementById(field), String(value));
+      return "ok";
+    },
+  });
+
+  // A destructive tool: x-destructive at the JSON-Schema root gates it behind
+  // the inline confirmation card before the handler runs.
+  chat.registerTool({
+    name: "save_article",
+    description: "Save the article. Destructive — asks for confirmation.",
+    parameters: { type: "object", properties: {}, [X_DESTRUCTIVE_KEY]: true },
+    handler: async () => {
+      await clickElement(document.getElementById("save"));
+      return "saved";
+    },
+  });
+</script>
+
+<ag-ui-chat endpoint="/agent/" title-text="Assistant"></ag-ui-chat>
+```
+
+> [!IMPORTANT]
+> **If nothing appears, check that `defineChat()` ran.** Forgetting it looks
+> like nothing at all. `<ag-ui-chat>` is then an *unknown element*, which every
+> browser renders as an inline 0x0 box, in flow, with no console warning and no
+> error — so the page looks finished and the chat is simply absent. There is
+> nothing to search for.
+>
+> A bare `import "@artooi/agents-web-components"` registers nothing, deliberately:
+> registration is an explicit call so the package stays tree-shakeable.
+>
+> `customElements.get("ag-ui-chat")` in a console answers it in one line.
+> `undefined` means the call did not run.
+
+That's the whole integration: an `endpoint` attribute pointing at your AG-UI server, optional
+`headers`, and the tools you want the agent to be able to invoke in the browser. If your API is on
+another origin, add `credentials="include"` too; see
+[Authenticating requests](#authenticating-requests).
+
+### Attributes and properties
+
+**Attributes** (set in HTML; the CSS-only ones are styling presets with no JS API):
+
+| Attribute | Property | Notes |
+| --- | --- | --- |
+| `endpoint` | `endpoint` | The AG-UI endpoint URL. Required to send: without it a send is refused with a `console.error` naming the missing attribute and a `not-connected` run notice in the transcript. 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"`. `"auto"` makes the header, the rail and the bar label follow the thread on screen (`threadTitle`), falling back to the strings table's `title` while it has none. 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` | How tool calls are drawn: `grouped` (the default: a run's consecutive calls fold into one row) / `inline` / `minimal` / `compact` / `full` (per-call cards; `full` was the default before `grouped`). An unknown value reads as `grouped`. See [Tool-call display modes](#tool-call-display-modes). |
+| `data-tool-group-display` | `toolGroupDisplay` | How an opened step group draws its calls under `grouped`: `full` (the default) / `compact` / `minimal` / `inline`. Ignored under the four card modes. An absent or unknown value reads as `full`. See [Choosing how a group draws its calls](#choosing-how-a-group-draws-its-calls). |
+| `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. |
+| `data-slash-commands` | — | Present (bare, or any value but `"false"`) to enable the `/`-command palette. |
+| `data-skills` | — | Inline JSON skill catalog. A value that will not parse is ignored and reported on the console, rather than reading as an empty catalog. |
+| `data-skills-url` | — | URL of a JSON skill catalog (fetched with the element's headers and cookie policy). |
+| `data-tools-url` | — | URL of a server tool-label catalog (`[{ name, summary, description? }]`), fetched with the element's headers and cookie policy; labels tool-call cards for server-side tools. |
+| `user-key` | `userKey` | Who the stored conversation belongs to — any string identifying the signed-in principal. Joins the storage namespace, and **changing it purges what the previous principal left behind**. Live (not connect-time): a logout is the host's to announce. See [Who the stored conversation belongs to](#who-the-stored-conversation-belongs-to-user-key). |
+| `user-name` | `userName` | The signed-in user's display name, for the [greeting](#the-greeting-on-an-empty-page) an empty conversation shows under `placement="page"`. Presentation only: unlike `user-key` it scopes nothing and is never sent. Absent or blank gives the nameless greeting. Live. |
+| `data-threads-url` | — | URL of a server thread index (django-ag-ui's `ThreadsView`); enables durable, cross-device chat history. |
+| `data-threads-cache` | — | **On by default.** `="false"` stops mirroring message bodies into `sessionStorage` when `data-threads-url` is set, for a deployment that put history on the server so transcripts stay off the client. Only meaningful alongside `data-threads-url`. |
+| `data-runs-url` | — | URL of a server run index (django-ag-ui's `RunsView`); reveals the header's *Continue a run* panel. See [Resuming a run](#resuming-a-run). |
+| `data-attachments-url` | — | URL of the file-upload endpoint (django-ag-ui's `AttachmentsView`); reveals the composer's paperclip picker, drag-and-drop, and paste. |
+| `data-attachment-accept` | — | `<input accept>` list for client-side type filtering (e.g. `image/*,.pdf`). The server stays authoritative. |
+| `data-attachment-max-bytes` | — | Client-side upload size cap in bytes (default 10 MiB; `0` disables). The server stays authoritative. |
+| `data-transcribe-url` | — | URL of the voice-transcription endpoint (django-ag-ui's `TranscribeView`); reveals the composer's mic button. See [Voice input](#voice-input). |
+| `data-theme-toggle` | — | Boolean: show a built-in header light⇄dark toggle (persists per tab). Off by default. See [Theme toggle](#theme-toggle). |
+| `data-strings` | `strings` | Partial JSON override of the UI string table (localization). The property wins key-by-key over the attribute; a value that will not parse is ignored and reported on the console. See [Internationalization](#internationalization-i18n). |
+| `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-launcher-drag` | — | **On by default.** `="false"` leaves the widget wherever your CSS puts it. Otherwise the collapsed launcher can be dragged anywhere on screen (the panel opens into the clearest space) and the open panel can be dragged by its header. See [Moving the launcher](#moving-the-launcher) and [Moving the panel](#moving-the-panel). |
+| `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` | — | **Copy and retry by default; feedback is opt-in.** A comma list of the actions a finished answer keeps: `copy` / `retry` / `feedback` (e.g. `"copy,retry,feedback"` to add the rating pair, which needs an `ag-ui-feedback` listener). `="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` / `chat` (e.g. `"scroll,drag"`). See [Page-action tools](#page-action-tools). |
+| `data-side` | — | For `placement="sidebar"`: which edge it docks to, `right` (default) / `left`. Styling, and read by script for the side `dockWidth` and `ag-ui-dock-width` report. Live. |
+| `data-collapse-icon` | — | The header collapse control's mark: `panel-close` (a window with its docked pane and an arrow into the edge, mirrored on `data-side="left"`) / `chevron-up` / `chevron-down` / `chevron-left` / `chevron-right`. Absent, or any other value, follows the placement: `panel-close` on `sidebar` (and `side`), `chevron-down` everywhere else. A host icon in `slot="icon-collapse"` wins over it. Live. |
+| `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`). Persisted per tab. `placement="page"` has no collapsed state and ignores it. |
+| `collapse-to` | — | What the panel collapses to: `auto` (the default; absent or any other value reads the same) leaves every placement as it is, `bar` draws a strip along the bottom edge in place of the round launcher, `none` hides the collapsed widget so the host's own control brings it back. Under either, a corner panel still moves by its header and `moveTo` on a wide viewport, and remembers where it was dragged. Live. See [Collapsing to a bottom bar](#collapsing-to-a-bottom-bar). |
+| `anchor` | `anchor` | Under `collapse-to="none"`, a selector for the host's element the panel rises from, right-aligned to it. The `anchor` property takes an element instead and wins over the attribute. Live. |
+| `maximized` | `maximized` | Reflected boolean; grows the open panel to its [maximized size](#maximizing-the-panel). Refused on `page`, `full` and `embedded`, at 600px or less, and while collapsed; a collapse leaves it. Not persisted. Live. |
+| `anchor-side` | — | Under `collapse-to="none"` with an anchor, which side of it the panel opens on: `above`, `below`, or `auto` (the default, and any other value), which takes the side with more room and re-decides on a window resize, never during a drag. Live. |
+| `data-dragging` | — | **Written by the element, not by you.** Stamped on whichever handle a gesture is currently using, so the styles can react and so the element knows not to re-place the widget under a drag in progress. Cleared on `pointerup` and on `pointercancel`. |
+| `data-expand-corner` | — | **Written by the element, not by you.** It stamps the corner a dragged or agent-moved panel opens from, so the collapse animation starts where the panel actually is. Listed because the element reads its own stamp back; setting it yourself is overwritten on the next move. |
+| `data-greeting` | — | CSS-only: `off` turns the [greeting layout](#the-greeting-on-an-empty-page) off under `placement="page"`, where it is on by default. Any other value turns it on under `placement="embedded"`. No other placement has it. |
+| `data-empty` | — | **Written by the element, not by you.** Present while the conversation has nothing in it, which is when the greeting shows. Public as a styling hook, so the chrome around a full-page chat can react to the same state, e.g. `ag-ui-chat[data-empty] ~ .page-footer { display: none }`. |
+| `data-running` | — | **Written by the element, not by you.** Present while an interaction is in flight, the same state that shows the Stop button (see the `running` property). Public as a styling hook, as `data-empty` is, so the chrome around the chat can react to it, e.g. `ag-ui-chat[data-running] ~ .toolbar button { pointer-events: none }`. |
+| `data-threads-search` | — | When the conversation list shows its search box: `auto` (absent, or any other value) from eight conversations, `always` over any list, `never` not at all. Live. See [The conversation list](#the-conversation-list). |
+| `data-small-viewport` | — | `off` keeps the desktop layout at every width, opting out of the [small-viewport override](#small-viewports). Styling, and read by script for the width `dockWidth` reports on a phone. Live. Everything that override sets is a token you can re-state; its trigger is a media query, which is the one thing you cannot. |
+| `data-paste-attach` | — | When to turn a long text paste into an attachment instead of composer text: absent for the 5000-character default, `off` to never, or a positive number of characters. Only acts where `data-attachments-url` (or a custom `uploadHandler`) gives it somewhere to go. |
+| `data-starters` | — | JSON array of prompts offered on an empty transcript, e.g. `'["Summarise this page"]'`. Fallback content for `slot="empty"`, so slotting your own replaces them. Shares the four-prompt and 120-character limits with the suggestion chips a run pushes. Read once at connect. |
+| `data-start-open` | — | Mount the panel open on a first visit. The corner placements otherwise rest at their launcher, the way every corner chat does; a stored choice wins over both. The placements that place themselves are unaffected. |
+| `theme` | — | Styling: an optional theme name (`quiet` (default) / `soft` / `ledger` / `classic`, or a word of your own) and an optional scheme (`light` (default) / `dark` / `auto`), in any order, e.g. `soft dark`. Live: the [header theme toggle](#theme-toggle)'s glyph follows a scheme written after connect. See [Themes](#themes). |
+| `density` | — | CSS-only: `comfortable` (default) / `compact`. |
+| `placement` | — | CSS-only: `floating` (default) / `sidebar` / `page` / `embedded` / `full`. `full` fills the viewport at every width, inside the safe-area insets; the `--ag-ui-inset`, size and `--ag-ui-panel-radius` tokens still apply. |
+
+Each header control also takes its own icon slot — `icon-history`, `icon-checkpoints`,
+`icon-new`, `icon-maximize`, `icon-collapse` — with the built-in drawn glyph as the fallback, so a host can project a
+brand `<img>` or `<svg>` in its place. The built-in header marks are drawn at
+`--ag-ui-glyph-size`. The composer's glyphs work the
+same way: `icon-send`, `icon-stop`, `icon-attach`, `icon-voice`.
+
+```html
+<ag-ui-chat endpoint="/agent/">
+  <svg slot="icon-new" width="16" height="16"><!-- ... --></svg>
+</ag-ui-chat>
+```
+
+The collapse control's built-in mark follows the placement, because a sidebar hides sideways
+into its edge rather than down: `panel-close` (a window with its docked pane and an arrow into
+the edge) on `sidebar` and `side`, mirrored for either on `data-side="left"`, and
+`chevron-down` on `floating`, `full`, `embedded` and every other placement. `data-collapse-icon`
+picks one of the built-in marks outright, at any placement and live: `panel-close`,
+`chevron-up`, `chevron-down`, `chevron-left` or `chevron-right`; any other value reads as
+absent. `panel-close` always points into the edge the panel docks to, so it mirrors on a left
+docked panel whether chosen or defaulted; the chevrons do not turn. For a mark of your own, slot it
+into `icon-collapse`, which wins over the attribute and every placement:
+
+```html
+<ag-ui-chat endpoint="/agent/" placement="floating" data-collapse-icon="chevron-right"></ag-ui-chat>
+<ag-ui-chat endpoint="/agent/" placement="sidebar">
+  <svg slot="icon-collapse" width="16" height="16"><!-- ... --></svg>
+</ag-ui-chat>
+```
+
+#### 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-answer-well`, `data-tool-group-display`) 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`, `data-launcher-drag` 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`, `collapse-to`, `anchor`, `anchor-side`, `maximized`, `data-side`, `data-small-viewport`, `data-threads-search`, `credentials`, `user-key`,
+`user-name`, `data-tool-group-display`, `data-collapse-icon`, `theme`.
+
+**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`.
+
+What re-inserting costs: the chrome is built again from the attributes as they stand, a run in
+progress is cancelled, and the conversation is redrawn from its stored history — the same rebuild
+`reload()` performs, and the reason that method exists for a host that can only configure the
+element after the fact.
+
+**Properties** (JS only, not attributes): `headers`, `getHeaders`, `trustedOrigins`, `allowImages`,
+`autoConfirm`, `confirmPredicate`, `askUser`, `askUserRenderer`, `approvalRenderer`,
+`approveWithEdits`, `agentFactory`, `getTools`, `getContext`, `routeMap`, `navigate`, `getPageMap`,
+`autoInjectPageMap`, `getPlace`, `conversationStore`, `uploadHandler`, `transcribeHandler`, `navigationResult`,
+`skillContext`, `toolSummaries`, `formatToolPayload`, `formatRelativeTime`, `strings`,
+`resolvePageTarget`, `sharedState`, `anchor` (an element, which wins over the attribute's selector), `extraStyles` ([unstable](#d-extrastyles-the-last-mile)), plus the read-only `unread`, `unhandledActivityTypes`, `threadId`, `threadTitle`, `running`, `barHeight` and `dockWidth`, and
+the attribute mirrors `endpoint` / `userKey` / `userName` / `toolDisplay` / `toolGroupDisplay` / `collapsed` /
+`maximized` / `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
+[Authenticating requests](#authenticating-requests).
+
+`allowImages` (default `false`) re-enables `<img>` in rendered assistant markdown.
+It is off by default because a model-controlled image URL is fetched by the browser
+with no user interaction — a zero-click exfiltration channel for prompt-injected
+page data. Enable only when the content source is trusted.
+
+`toolSummaries` is a `Record<string, string>` mapping tool name → a friendly card
+label, used when a tool has no `x-summary` in its own schema. Built-in and client tools
+should carry `x-summary` directly; this map is the seam for **server-side tools** (drf-mcp,
+the django-ag-ui `@tool` registry), whose schema never reaches the browser — e.g.
+`chat.toolSummaries = { list_projects: "Search projects" }`. Or point
+`data-tools-url` at a server catalog endpoint (django-ag-ui's `tools/`) and the
+labels are fetched automatically — per card, `x-summary` → an explicit
+`toolSummaries` entry → the fetched catalog → the raw name.
+
+`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); `threadId` and `running` are covered under
+[driving the conversation from your own chrome](#driving-the-conversation-from-your-own-chrome).
+
+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`, `registerActivityRenderer`, `setSkills`,
+`sendMessage`, `attachFile`, `appendMessage`, `retryLastTurn`, `quote`, `offerQuoteInPage`,
+`enableCharts`, `newChat`, `setCollapsed`, `toggleCollapsed`, `setMaximized`, `toggleMaximized`,
+`describeSurface`, `moveTo`, `resetSize`, `toggleTheme`, `openThreads`, `closeThreads`, `switchThread`, `deleteThread`,
+`openCheckpoints`, `closeCheckpoints`, `toggleCheckpoints`, `refreshPlace` and `reload`.
+
+### Sending from your own UI
+
+`sendMessage(content, attachments?)` sends as if the user had typed it — user bubble,
+`ag-ui-submit` event, run started. `ag-ui-submit` means a turn was sent, not that a run started:
+a Retry and a run continued from the checkpoint panel start runs without one. To know whether
+anything is running, read [`running`](#driving-the-conversation-from-your-own-chrome) or style on
+`data-running`. Use it for an "Ask about this order" button, a command
+palette, a prompt fired when your page mounts the chat, or a composer of your own replacing the
+built-in one.
+
+It returns a `Promise<boolean>`. It resolves `true` once the turn has been handed to the agent
+and its run has settled, frontend-tool rounds included, and `false` when nothing was sent:
+
+- for an entirely empty message;
+- while a run, or a checkpoint continuation picked from the panel, is in flight. A continuation
+  counts from the pick, and a send from the call rather than from when its run starts, so a
+  `sendMessage` from an `ag-ui-submit` listener, or a second call in the same task, is refused
+  rather than starting a second run;
+- with no `endpoint` set, which the transcript also says;
+- while a reload resumes a run a navigating tool interrupted. The resume counts from the moment
+  the element asks its conversation store for the conversation, and it ends by starting that
+  run, so a send then is refused, and the built-in Send queues behind the resumed answer;
+- when your own code that runs on the way to the request — an `ag-ui-submit` listener, the
+  conversation store's save — stops it by starting a new chat or changing `user-key`. A
+  `getContext` or `getTools` that does the same stops it too, but after the turn was handed
+  over, so the call resolves `true`.
+
+**While the element restores a stored conversation, a send waits for it.** Every restore —
+when the element connects, on `reload()`, when a thread is picked from the drawer, and when
+`user-key` changes from one principal to another — first asks the conversation store for the conversation, and with
+`data-threads-url` that is a request to your server. A `sendMessage` made in that time waits
+until the conversation is drawn, then sends with it: the bubble, the `ag-ui-submit` event and the
+request all come after the replay, later than the call by the length of the load. So a prompt
+fired on mount needs no timing of its own. If New chat, a thread switch, a change from one
+`user-key` to another or a `reload()` comes while it waits, the conversation it was addressed
+to is gone, so it is dropped and resolves `false` at once. The element leaving the page drops it
+too, but it resolves `false` only once the load answers or the element is inserted again. A
+first `user-key` on an anonymous conversation adopts that conversation rather than replacing
+it, so a send waiting then still goes out. A second `sendMessage` while one waits is refused. The built-in Send queues what is typed during the load ("Waiting to send"),
+and sends it after the conversation is drawn, behind a `sendMessage` that was waiting.
+
+Unlike the built-in Send it does **not** queue, so your composer keeps what it tried to send, and
+it does **not** consult the attachment tray: what you pass is what is sent, so your composer stays
+in charge of its own state.
+
+`retryLastTurn()` keeps the same rules, because it starts a run on the same conversation. It
+returns `false` while a run, a send, another Retry or a continuation is in flight, and while
+any restore of the stored conversation is still loading. It does not wait for the load as a send
+does: until the conversation is drawn there is nothing on screen to retry, and afterwards it
+would ask the previous visit's last question again. It counts from the call as a send does: until its run starts, a `sendMessage` or a
+second Retry is refused, the built-in Send queues, and a checkpoint pick is refused. It also
+returns `false` when your own code stops it before its run starts: a conversation store, or an
+activity or tool renderer it redraws through, that starts a new chat or changes `user-key`. A
+`getContext` or `getTools` that does the same stops it too, before anything is sent, but it runs
+after the Retry has handed its turn to the client, so the call resolves `true`. A store that
+throws from the Retry's save leaves the conversation as it was, and `retryLastTurn()` rejects
+with its error.
+
+`attachFile(file)` queues a file into the tray exactly as the picker and drag-and-drop do, with
+the same validation and progress chip. It returns `false` when uploads are not configured
+(no `data-attachments-url` and no `uploadHandler`) — the only way to tell, since with no tray
+there is nothing to report through.
+
+Uploading is asynchronous, so watch `ag-ui-attachments` for the result. Its `detail` carries
+`{ attachments, pending }`: the durable refs of everything that has finished, and how many are
+still in flight. Send once `pending` is `0`, or you will leave files behind.
+
+```js
+chat.addEventListener("ag-ui-attachments", (e) => {
+  const { attachments, pending } = e.detail;
+  sendButton.disabled = pending > 0;
+  sendButton.onclick = () => chat.sendMessage(input.value, attachments);
+});
+chat.attachFile(fileInput.files[0]);
+```
+
+A self-contained live playground lives in [`demo/`](demo/) — run `make demo` to serve it against a
+mock AG-UI server.
+
+---
+
+## Authenticating requests
+
+The element talks to more than one endpoint. Beyond the AG-UI run itself, it may fetch the thread
+index and a thread's messages, the tool-label and skill catalogs, the run index, and it may POST an
+upload or a voice clip. **Every one of them is authenticated the same way**, by the element rather
+than by the agent — so configuring authentication on a custom `agentFactory` authenticates the run
+and nothing else, and the history drawer comes back empty because its request was anonymous.
+
+| Request | Endpoint | Transport |
+| --- | --- | --- |
+| The agent run | `endpoint` | `fetch` (SSE), via `agentFactory` |
+| Thread index / a thread's messages / rename / delete | `data-threads-url` | `fetch` |
+| Tool-label catalog | `data-tools-url` | `fetch` |
+| Skill catalog | `data-skills-url` | `fetch` |
+| Run index | `data-runs-url` | `fetch` |
+| Voice transcription | `data-transcribe-url` | `fetch` |
+| File upload | `data-attachments-url` | `XMLHttpRequest` (for progress events) |
+
+### `headers` and `getHeaders`
+
+`headers` is a plain record sent with every request above:
+
+```js
+chat.headers = { "X-CSRFToken": getCsrfToken() };
+```
+
+It is read at request time, but only an assignment changes it — so a token captured there is pinned
+until you remember to assign again. For anything that rotates (a short-lived JWT, a re-issued CSRF
+token) set **`getHeaders`** instead, a function consulted immediately before every request:
+
+```js
+chat.getHeaders = () => ({ Authorization: `Bearer ${auth.accessToken()}` });
+```
+
+Because it is called per request, a token refreshed between two requests reaches the second one —
+including mid-conversation, on the cached agent's own stream.
+
+The two **compose**: they are merged per key, `getHeaders` winning, so a fixed header and a rotating
+one can be configured independently and neither silently drops the other.
+
+```js
+chat.headers = { "X-Client": "admin" };
+chat.getHeaders = () => ({ Authorization: `Bearer ${auth.accessToken()}` });
+// every request: X-Client: admin + a freshly-read Authorization
+```
+
+### Cross-origin cookies (`credentials`)
+
+If your API is on a different origin from the page — `app.example.com` calling `api.example.com`
+counts, subdomains are cross-origin — the browser's default of `same-origin` sends **no cookies at
+all**. The requests still go out; they arrive unauthenticated, and the server answers `401` while
+looking perfectly configured. Set the cookie policy explicitly:
+
+```html
+<ag-ui-chat endpoint="https://api.example.com/agent/" credentials="include"></ag-ui-chat>
+```
+
+```js
+chat.credentials = "include"; // mirrors the attribute
+```
+
+It takes `fetch`'s own three modes — `omit`, `same-origin`, `include` — applies to every request in
+the table above, and is read per request, so a late assignment applies to everything after it.
+Anything else is rejected where you wrote it: an unknown value assigned as a property throws, and an
+unknown value in the attribute is reported to the console and ignored, rather than becoming a `401`
+later on.
+
+The server has to agree: `Access-Control-Allow-Credentials: true` and a concrete
+`Access-Control-Allow-Origin` (the wildcard is invalid with credentials).
+
+One asymmetry: uploads use `XMLHttpRequest` for real progress events, and its cookie switch is
+two-state. `include` turns it on; every other value leaves it off. `omit` therefore cannot suppress
+cookies on a *same-origin* upload — supply your own `uploadHandler` if that matters.
+
+### Where those credentials are allowed to go
+
+Every URL in the table above is a plain HTML attribute, and `headers` / `getHeaders` are attached to
+whatever they name. That is what makes a cross-origin agent work — and it is also why a page must
+never build one of those attributes out of a URL parameter, a CMS field, or anything else it did not
+choose itself. Whoever supplies the value chooses where the token goes: the browser preflights the
+custom header, any server willing to answer receives it, and it leaves on the element's first
+request, before the user has typed anything.
+
+Treat all seven as trusted configuration. When any of them resolves to another origin, the element
+says so on the console once per origin, naming the destination and the header names it is about to
+send. That covers all seven, not the agent endpoint alone: the tool catalog, the skills list, the
+thread index, the attachment upload and the transcription endpoint carry the same headers, and
+reporting only the agent would report the least interesting of them.
+
+To confirm destinations you chose on purpose and silence the notice, name their origins:
+
+```js
+chat.trustedOrigins = ["https://api.example.com"];
+```
+
+That covers every endpoint the element requests itself, and is forwarded to `createHttpAgent`, so a
+host that does not override `agentFactory` needs nothing else. A custom factory can also be given
+the option directly:
+
+```js
+chat.agentFactory = (options) =>
+  createHttpAgent({ ...options, trustedOrigins: ["https://api.example.com"] });
+```
+
+Origins are compared as `URL.origin` produces them — scheme, host and port. A notice is a notice,
+not a refusal: nothing is blocked, because a cross-origin agent is a supported deployment and
+refusing would break working installations to defend against a page that is already interpolating
+untrusted data into its own markup.
+
+### Framework hosts: configure before you insert
+
+`headers`, `getHeaders` and `credentials` are read when a request is made, so they can be set at any
+time. Several other things are read once, while the element **connects**: `strings`, `uploadHandler`
+and `transcribeHandler` (they decide whether the attach and voice affordances exist at all) and
+every chrome-building `data-*` attribute — and the catalogs and thread history are requested at, or
+just after, that same moment.
+
+React attaches `ref`s *after* it inserts the node, which puts the canonical integration on the wrong
+side of that boundary. Create the element, configure it, then append:
+
+```jsx
+function Assistant() {
+  const host = useRef(null);
+
+  useEffect(() => {
+    defineChat();
+    const chat = document.createElement("ag-ui-chat");
+
+    // Configure first - every one of these is read as the element connects.
+    chat.setAttribute("endpoint", "/agent/");
+    chat.setAttribute("data-threads-url", "/agent/threads/");
+    chat.credentials = "include";
+    chat.getHeaders = () => ({ Authorization: `Bearer ${auth.accessToken()}` });
+    chat.registerTool(myTool);
+
+    // ...then insert it.
+    host.current.appendChild(chat);
+    return () => chat.remove();
+  }, []);
+
+  return <div ref={host} />;
+}
+```
+
+Writing it as `<ag-ui-chat ref={...} />` in JSX and configuring in the ref callback mostly works —
+the catalog requests are held back one microtask precisely so a ref assigned in the same commit is
+honoured — but the thread-history request is **not** deferred, so that one goes out with whatever
+was configured at insertion. It starts at insertion because the restore is what a `sendMessage()`
+from the same commit waits on: a restore that had not started yet would have nothing to hold it,
+and the send would go out without the conversation.
+
+If your credentials can only arrive later still — an awaited token, a passive effect — call
+**`reload()`** once they land:
+
+```js
+const token = await auth.login();
+chat.getHeaders = () => ({ Authorization: `Bearer ${token}` });
+await chat.reload();
+```
+
+`reload()` re-runs everything the element loads on startup (tool catalog, skills, thread history)
+with the configuration as it then stands. It is a reload, not a merge: the in-flight run is
+cancelled and the transcript is rebuilt from the persisted history, so call it when configuration
+lands rather than between turns.
+
+#### The same boundary in four frameworks
+
+Each framework reaches that pre-insertion window differently, and only one of them reaches it
+declaratively. Built and driven in all four:
+
+| Host | Pre-insertion window | What to do |
+| --- | --- | --- |
+| React | None — refs attach after insertion | `createElement`, configure, `appendChild` (above) |
+| **Vue 3** | **Yes** — a directive's `beforeMount` | Attributes in the template, properties in the directive |
+| Svelte 5 | None — `use:` actions and `$effect` run after insertion | Same as React |
+| Angular | None — bindings apply during change detection | Same as React, in `ngOnInit` with `@ViewChild({ static: true })` |
+
+**Vue** is the one host that can configure declaratively, because a custom directive's `beforeMount`
+runs while the element is still detached:
+
+```vue
+<script setup>
+const vConfigure = {
+  beforeMount(element) {
+    element.getHeaders = () => ({ Authorization: `Bearer ${token()}` });
+    element.registerTool(myTool);
+  },
+};
+</script>
+
+<template>
+  <ag-ui-chat v-configure endpoint="/agent/" data-threads-url="/agent/threads/" />
+</template>
+```
+
+Tell Vue's compiler the tag is a custom element, or it will warn and try to resolve a component:
+`vue({ template: { compilerOptions: { isCustomElement: (tag) => tag === "ag-ui-chat" } } })`.
+
+**Svelte 5**'s `use:` action and `$effect` both run after the node is in the DOM, so build the
+element by hand in an `$effect` and append it — the React shape, in runes. **Angular** needs
+`CUSTOM_ELEMENTS_SCHEMA` on the component and, if it wraps the panel in its own component, one line
+of CSS: `:host { display: contents }`. Angular's host element otherwise lands between your grid and
+the children it sizes, and the panel renders a few hundred pixels tall in the middle of the page.
+
+---
+
+## Core concepts
+
+### The run loop and the AG-UI client
+
+`<ag-ui-chat>` is the view; [`AgUiClient`](src/core/agui_client.ts) is the orchestration layer over
+an AG-UI `AbstractAgent`. On the first send the element builds a client (via the overridable
+`agentFactory`, which defaults to [`createHttpAgent`](src/core/create_http_agent.ts)). Each turn:
+
+1. The user message is appended and the agent runs once.
+2. AG-UI subscriber events are translated into the element's handlers — streaming text deltas
+   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`
+   (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
+card (honouring `data-tool-display`), so server-side output is visible too. The current tool catalog
+and context are read **fresh on every run** (`getTools()` / `getContext()`), so they always reflect
+the current page state.
+
+#### A tool call that failed
+
+A `TOOL_CALL_RESULT` may say how the call ended, as an optional **`outcome`** key in the event's
+`metadata` (`"metadata": { "outcome": "failed" }`). It takes pydantic-ai's own `ToolReturnPart`
+vocabulary — read the values off `TOOL_OUTCOME`:
+
+| `outcome` | Card | Means |
+| --- | --- | --- |
+| *(absent)* | done | A result, said the way every server has always said it. |
+| `success` | done | The same thing, stated. |
+| `failed` | error | The call ran and failed. |
+| `denied` | declined | A person or a guard refused it, so it never ran. |
+| `interrupted` | not finished | It produced no result because the run ended first, and nobody refused it. |
+
+**Absent is a success, and anything unrecognised is too** — including a value from a later protocol
+version. A card is a claim about what happened, and refusing to
+recognise a word is not grounds for claiming failure. So no server has to change to keep the
+rendering it has today, and a server that adds the field gets the truth on screen instead of a
+green card with a refusal folded inside it.
+
+It has to be in `metadata`. `@ag-ui/client` 1.0 strips every key its schemas do not declare from an
+event before any subscriber sees it, with a `[ag-ui][enforce]` console warning, and `metadata` is
+the one place on an event it declares open by key. An `outcome` at the top level of the event —
+where a server wrote it for the 0.x client, and where a django-ag-ui older than 0.63.0 still does —
+never arrives, so the card settles as done. The key arrives on `AgUiClientHandlers.onToolResult` as
+an optional third argument, typed `unknown` because the protocol validates nothing inside
+`metadata`; `toolStatusFromOutcome` does the narrowing.
+
+A **frontend** tool never streams this event — the client posts its own result — so its outcome is
+recorded on the `ToolExecution` the executor returns (`{ content, outcome: "denied" }`). That covers
+the two refusals the component makes itself: a confirmation card the user declined, and a call
+blocked because the page moved under the round.
+
+Either way the outcome is **persisted on the tool message, in its `metadata`**, so a reload replays
+the card as it settled rather than as a plain result. For a server's result `@ag-ui/client` puts it
+there itself, folding the event's metadata onto the tool message it appends; for its own results the
+client writes it in the same place. See
+[MPA durability](#mpa-durability-surviving-full-page-reloads).
+
+**Every request carries a result for every tool call in it.** Several model providers reject a
+turn holding a tool call with no result, and a run can leave one open in more ways than one: Stop
+while the stream is still arriving, a round that ends on `RUN_ERROR`, a call naming a tool nothing
+here owns, a server that never streamed the result. So before each request the client answers
+every call still open with the `callNotFinished` string (by default `Not finished: the run ended
+or moved on before this tool call returned a result.`) and the outcome `interrupted`, placed at the
+end of the round that made the call, and the card settles to **not finished** in the same words.
+That result blames nobody, because nobody declined: `declinedAction` is kept for a call a person
+was asked about and turned down — a confirmation card or an approval they declined, or one Stop
+closed while it was open. The calls a resumed approval is answering are left alone, because the
+resume is their answer.
+
+The catalog a run advertises is also the set that run can execute. Override `getTools` to scope
+what a page offers — say, exposing `delete_record` only where deleting makes sense — and a call
+naming a tool you withheld is treated exactly as a call naming a tool you never registered: no
+handler runs, the card settles as not finished, and the next request answers the call in those
+words. Withholding is per run, so the
+mount-wide registry can stay complete. Hosts that leave `getTools` alone advertise the built-ins
+plus everything registered, which is precisely what dispatch could reach anyway.
+
+### Stopping a run
+
+While a run is in flight the **Send button becomes Stop** (same button, label/`aria-label` swap,
+`data-state="running"` for styling); clicking it — or pressing **Escape** in the composer (when
+the skills palette is closed; the palette owns Escape while open) — calls `AgUiClient.cancel()`.
+AG-UI has no server-side cancel route: cancelling **aborts the streaming request**
+(`abortRun()`), and the server observes the disconnect. On cancel:
+
+- Partial assistant text already streamed **stays in the transcript** and is persisted via
+  `onPersist`, so a reload shows the truncated exchange. A muted **"⏹ Stopped"** note is appended
+  (`.stopped-note`) — a deliberate stop is not an error, so no bubble.
+- The run loop stops: tool calls collected before the abort are **not executed**, and no further
+  round starts. A frontend tool handler already running completes and its result is kept, but it
+  doesn't trigger a re-run, and the calls after it in the same round do not start. Each call that
+  did not run settles as **not finished**, and the next request answers
+  it in those words rather than sending it without a result.
+- An **open confirmation card is declined** (`data-resolved="declined"`) — cancelling the run
+  answers the pending question. Likewise an open **approval card** is denied, and the next request
+  carries that decline as the call's result; a call already approved when Stop lands was declined
+  by nobody, so it is answered as not finished instead. An open **question card** (`ask_user`)
+  resolves with an empty answer. Reloading the page while a card is open does not decline it,
+  because nobody answered: the call comes back not finished; see
+  [MPA durability](#mpa-durability-surviving-full-page-reloads).
+- The new `onCancelled()` handler fires instead of `onError()`; `onSettled()` still follows
+  (the terminal-rest guarantee), returning the button to **Send**.
+
+`cancel()` with no run in flight is a safe no-op. `newChat()` cancels any in-flight run before
+discarding the client, and so do switching conversations, `reload()` and removing the element. A
+[checkpoint continuation](#resuming-a-run) is the run in flight while it lasts, so Stop and all of
+these end it too. So does a turn that has not made its request yet: called from host code a send
+or a resume runs on the way — the conversation store's save, `getContext`, `getTools` —
+`cancel()` stops it before anything is sent, and `onCancelled()` and `onSettled()` fire as for any
+other Stop.
+
+A cancelled run ends a moment later, once its request has closed or a running tool handler has
+returned. What it does then stays with the conversation it belonged to: its truncated exchange is
+saved to that thread, `ag-ui-run-finished` still reports the tools it ran, and nothing reaches the
+transcript or the Stop button of the conversation that replaced it.
+
+### Registering tools
+
+A tool is a `ClientTool`: `{ name, description, parameters, handler }`, where `parameters` is a
+**JSON Schema** and `handler` receives the parsed args and returns a value that is JSON-serialised
+into the tool-result message. Register them on the element:
+
+```js
+chat.registerTool({
+  name: "search_products",
+  description: "Search the catalog.",
+  parameters: {
+    type: "object",
+    properties: { query: { type: "string" } },
+    required: ["query"],
+  },
+  handler: async ({ query }) => await api.search(query),
+});
+```
+
+Registering a name twice replaces the earlier handler rather than throwing, so a re-fired
+host ref or React StrictMode's double-invoke is harmless -- but two different tools sharing
+a name means the second silently wins. Each `<ag-ui-chat>` element owns its own
+registry, AG-UI client, and Shadow DOM, so **multiple instances on one page never interfere**.
+The one record they share is which storage namespace each has claimed, and it exists to keep two
+of them out of each other's conversation.
+
+**A handler's thrown message leaves the browser.** If a handler rejects, its `Error.message` is
+posted back as that call's tool result: into the conversation, on to the AG-UI endpoint, persisted
+there, and replayed to the model provider on every later round. That is deliberate — a real reason
+is what lets the agent recover — but it means an internal hostname, a signed URL or a
+stack-derived path in a rethrown error is disclosed to parties you never chose. Throw the message
+you would be content for the model to read, and log the detail instead.
+
+### Inline confirmation (`x-destructive` / `x-confirm` / `confirmPredicate`)
+
+When a tool call needs confirmation, the element appends an **inline confirmation card** (a
+`<div class="confirm">`) to the transcript via
+[`requestConfirmation`](src/ui/confirmation_card.ts) — it is not a modal overlay. The card reads
+naturally after the assistant's explanation, never steals focus from the page, and stays in the
+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:
+
+1. If `chat.autoConfirm === true`, the call **never** prompts (an "autopilot" toggle).
+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). **A predicate that throws or rejects refuses
+   the call**: no card, the handler does not run, the tool card settles as declined, and the agent
+   gets the `confirmCheckFailed` string as the result and carries on, as after a decline. The
+   error goes to the console, never to the endpoint. A predicate still pending when the run is
+   stopped decides nothing: the call does not run, and its card settles as not finished.
+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, and
+when [`user-key`](#who-the-stored-conversation-belongs-to-user-key) changes hands: one person's
+*Always allow* is not the next person's, and a sign-out in the same tab does not remount anything.
+The first key to arrive keeps it, for the same reason it keeps the conversation.
+
+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
+the `x-destructive` flag (or `confirmPredicate`). The registry forwards the flag verbatim to
+`RunAgentInput.tools`.
+
+If the schema carries an `x-confirm` string (use `X_CONFIRM_KEY`), the card shows it as the prompt;
+otherwise it falls back to a generic `Run "<tool>"?`.
+
+**This gate covers frontend tools only.** A server-side tool's schema never reaches the browser —
+tool definitions travel client-to-server on `RunAgentInput.tools`, and the only channel coming back
+is the label catalog (`data-tools-url`), which carries `{ name, summary, description? }` and no
+flags. So marking a server tool destructive does not produce a card here; gate it server-side
+instead (see [Server-side tool approval](#server-side-tool-approval-interrupts)), which surfaces as
+an approval card in the same transcript.
+
+```js
+// Per-call: confirm a delete only when it would remove more than one row.
+chat.confirmPredicate = (name, args) =>
+  name === "delete_rows" && Array.isArray(args.ids) && args.ids.length > 1;
+
+// Prompt text via x-confirm:
+chat.registerTool({
+  name: "activate_project",
+  description: "Activate the current project.",
+  parameters: { type: "object", properties: {}, [X_DESTRUCTIVE_KEY]: true, [X_CONFIRM_KEY]: "Activate this project?" },
+  handler: async () => await api.activate(),
+});
+```
+
+The confirmation card gates **client-registered** tools *before* they run. A **server-side**
+tool runs on the server, so the browser can't intercept it the same way — that is what the
+approval card below is for.
+
+### Server-side tool approval (interrupts)
+
+When the server gates a destructive tool (e.g. django-ag-ui's `ToolGuard`), the tool **defers**
+instead of executing and the run finishes on an AG-UI *interrupt*. The element then renders an
+**inline approval card** (a `<div class="approval">`) via
+[`requestApproval`](src/ui/approval_card.ts) **inside the tool card of the call it gates**:
+
+- **Approve** → the run resumes and the server runs the tool; its result streams back into the
+  same card.
+- **Deny** → the run resumes carrying a `cancelled` answer, so the model learns the tool was
+  declined; the card settles as declined.
+
+This uses the AG-UI protocol's own interrupt/resume mechanism (`RunAgentInput.resume[]`) — the
+wire stays vanilla AG-UI. A **Stop** while an approval card is open denies every open card and
+cancels the run. No configuration is needed on the client; the gate is enabled server-side.
+
+**A run can defer several calls, and each is answered on its own.** Importing three rows defers
+three `create_event` calls, and the wire takes a different answer for each. So every question is
+asked **at once**, each in its own tool card, above that call's own arguments — which is what says
+*which* call it is about. The prompt cannot: it comes from the tool, so all three read "Add this
+event to the board?". While the run waits, those cards read **`waiting for you`**
+(`data-status="deferred"`), not "running…" — nothing is running, the stream is over and the server
+is idle. A card asking a question shows its arguments in every `data-tool-display` mode, since
+hiding them would hide the answer to "which one is this".
+
+A **frontend** tool such as `ask_user` stays at "running…" while its card is open, because the
+browser really is running it. Only a deferred call was claiming something untrue.
+
+**What the card asks.** An AG-UI interrupt carries the question as `message`, and the default is the
+call spelled out — `Approve create_event({"title": "Design sync", …})?` — which is accurate and not
+something to put in front of a person. A server can supply its own wording as **`x-confirm` in the
+interrupt's `metadata`**, the same key a client-side confirmation reads off the tool's schema, and
+the card prefers it:
+
+```json
+{ "id": "int-1", "reason": "tool_call", "toolCallId": "call-1",
+  "message": "Approve create_event({\"title\": \"Design sync\"})?",
+  "metadata": { "x-confirm": "Book Design sync on Friday at 14:00?" } }
+```
+
+Anything non-string or blank under that key is ignored in favour of `message`, and with neither the
+card falls back to `strings.approvalPrompt`.
+
+**The card approves or denies, and nothing else.** The interrupt's `responseSchema` also advertises
+`editedArgs` and `reason` — the protocol allows a client to rewrite a gated call's arguments before
+letting it run. The built-in card does not offer that; a host that wants it can implement
+`approvalRenderer` and resolve the interrupt itself.
+
+**A gated write is still a write the page cannot see.** Approving one runs a *server-side* tool, so
+if your page renders the data it touched, listen for
+[`ag-ui-run-finished`](#host-seams-the-spa-story) and refetch.
+
+Like the question card, the approval card is customizable at three levels: **text** (`strings`:
+`approveAction` / `approvalPrompt` / `approve` / `deny` / `toolDeferred`), **CSS** (`::part()`:
+`approval`, `approval-body`, `approval-actions`, `approval-button`, `approval-approve`,
+`approval-deny`, and `tool-card-approval` for the region inside the card), and **full replacement**
+via `chat.approvalRenderer` — given the request (`message` + `toolName`) and a Stop `AbortSignal`,
+render your own UI and resolve `true`/`false`. A renderer is called **once per interrupt,
+concurrently**, so a host that can only ask one thing at a time should queue inside it:
+
+```js
+chat.approvalRenderer = (request, { signal }) =>
+  myConfirmDialog(request.message ?? `Run ${request.toolName}?`, { signal });
+```
+
+**A renderer that throws or rejects falls back to the built-in card** for that interrupt, with a
+`console.warn` naming it. The renderer decides how the question looks, not whether it is asked, so
+nothing runs without a click and the run carries on as if no renderer were set. The one exception
+is a rejection after the signal fired, which is how a renderer is expected to honour Stop: that
+wait resolves as denied, as the built-in card does on the same signal, with no card and no warning.
+
+### Asking the user a question (`ask_user`)
+
+Set `chat.askUser = true` to offer the agent a built-in `ask_user` frontend tool. When the agent
+calls it, the element renders an **inline question card** (a `<div class="question">`) via
+[`requestQuestion`](src/ui/question_card.ts) and returns the user's answer as the tool result:
+
+```js
+chat.askUser = true; // opt in; off by default so the tool catalog is unchanged otherwise
+```
+
+`ask_user(question, options?, allow_custom?)` renders `options` as radio buttons, adds a free-text
+field when `allow_custom` is set (or when no options are given), and feeds the chosen or typed
+answer back through the normal frontend-tool path — no new protocol. A **Stop** dismisses an open
+question with an empty answer.
+
+The question card is **fully customizable** at three levels:
+
+- **Text** — every label is a `strings` key: `askUserAction` (the card's `aria-label`),
+  `otherOption`, `answerPlaceholder`, `submit`.
+- **CSS** — every element exposes a `::part()`: `question`, `question-body`, `question-options`,
+  `question-choice`, `question-radio`, `question-input`, `question-actions`, `question-button`
+  (plus the `--ag-ui-*` theme variables). No shadow piercing.
+- **Full replacement** — set `chat.askUserRenderer` to own the entire UI. Given the parsed request
+  and an `AbortSignal` (fired on Stop), render anything — a native modal, a framework component —
+  and resolve with the answer (empty string = no answer). The built-in card is bypassed entirely.
+
+```js
+// Level 1+2: restyle the built-in card.
+chat.strings = { submit: "Answer", answerPlaceholder: "Type here…" };
+// ag-ui-chat::part(question) { border-radius: 0; }
+
+// Level 3: replace the card with your own UI.
+chat.askUserRenderer = (request, { signal }) =>
+  myModal.ask(request.question, request.options, { allowCustom: request.allowCustom, signal });
+```
+
+**A renderer that throws or rejects falls back to the built-in card** for that call, with a
+`console.warn` naming the tool call. As with `approvalRenderer`, the renderer decides how the
+question looks, not whether it is asked, so the run carries on as if no renderer were set. The one
+exception is a rejection after the signal fired, which is how a renderer is expected to honour Stop:
+that wait resolves with an empty answer, as the built-in card does on the same signal, with no card
+and no warning.
+
+### DOM-driver and animation primitives
+
+So the agent can visibly drive the host page, the package ships generic, framework-free
+primitives. The **animation** primitives ([`animations.ts`](src/dom/animations.ts)) operate at
+human-readable speed (configurable; pass small/zero durations in tests):
+
+- `typeInto(el, value, { charDelayMs })` — clears and types a value character by character,
+  firing `input`/`change` events as a real user would.
+- `highlightThenClick(el, { highlightMs })` / `pressThenClick(el, options)` — outline/press an
+  element, pause, then click.
+- `selectOption(el, value)` / `toggleControl(el, checked)` — animate a `<select>` / checkbox.
+- `scrollIntoCenterView(el, { settleMs })` — scrolls the element to the vertical centre and
+  resolves once the scroll has **settled**, so the ring that follows is drawn where the user is
+  looking rather than mid-glide. Awaiting is optional; the scroll is requested synchronously
+  either way. Settlement is `scrollend` where the browser has it, a short probe when nothing
+  actually moved (the element was already in view), and a 600 ms cap otherwise.
+- `flash(el, { flashMs, color })` / `focusWithFlash(el, { flashMs, color, focus })` — ring the
+  element so the user can find it. The ring is an `outline`, not a `box-shadow`, because a shadow
+  paints outside the border box and any `overflow: hidden` ancestor sharing the element's box (a
+  card, a table cell) clips it away entirely. It holds for **1200 ms** by default and fades out
+  over the last third — a 200 ms blink is not long enough to be *found* by someone who does not
+  yet know where to look. The colour is `color` when passed, else — see
+  [Ring colour](#ring-colour) — the widget's own accent.
+  `flash` leaves focus alone; `focusWithFlash` moves it — see "Flash versus focus" below.
+- `prefersReducedMotion()` — honoured by every primitive that *moves* something: the hold delays
+  in `pressThenClick` / `selectOption` / `toggleControl` collapse to instant, `scrollIntoCenterView`
+  jumps instead of gliding and settles immediately, and the flash drops its fade while still
+  holding the ring for its full duration. Reduced motion asks for no animation, not for no
+  feedback. `typeInto` and `highlightThenClick` are the exceptions: they keep their
+  explicit-duration contract, so pass `charDelayMs: 0` / `highlightMs: 0` yourself if you want
+  them instant.
+
+The **DOM-driver** primitives ([`dom_driver.ts`](src/dom/dom_driver.ts)) compose those into the
+operations a tool handler typically wants:
+
+- `fillField(el, value, options)` — scroll to, focus-flash, and type into a text field. The
+  flash defaults to `flashMs: 0` here: the field is about to be typed into, which is its own
+  highlight. Pass `flashMs` (and optionally `color`) to ring it first.
+- `clickElement(el, options)` / `pressButton(el, options)` — scroll to, highlight/press, and click.
+- `showHighlightOverlay(el, options)` — ring an element from an **overlay drawn outside it**, and
+  optionally dim everything else (`scrim`) or flow a gradient round it (`gradient`). Returns a
+  function that removes it. `flash` and `focusWithFlash` take `scrim` and `gradient` too and route
+  through this when either is asked for.
+
+  **Why a second mechanism.** The plain ring is an `outline` on the element, which is deliberate:
+  a `box-shadow` paints outside the border box, so an `overflow: hidden` ancestor sharing the
+  target's box clips the whole ring away while the helper still reports success. But an outline
+  takes a *colour* — there is no `outline-image` — so a gradient cannot be one, and anything else
+  that can be is a property of the target and lands back inside whatever is clipping it. Dimming
+  everything else needs a surface larger than the target, which is the same problem from the other
+  side. So they are one overlay rather than two features.
+
+  **It is inert.** The overlay never takes a pointer event, at the cut-out or anywhere else — a dim
+  that swallows clicks is a modal the user did not open, and `highlightThenClick` has to reach the
+  control it just finished pointing at. It follows the target on scroll and resize, and under
+  reduced motion the gradient is drawn but does not travel.
+
+  **Themed from the element you point at, not from the widget.** The overlay is appended to the
+  document body so it can escape the clipping it exists to avoid, which means a `var()` in its own
+  style would resolve against the body — so every token is read from the *target's* computed style
+  instead. Set them wherever they inherit to the elements the agent touches, usually `:root`. The
+  ring colour is the one exception, read from the widget as well; see
+  [Ring colour](#ring-colour).
+
+  ```css
+  :root {
+    --ag-ui-highlight-ring-color: #0f766e; /* also read from ag-ui-chat; see Ring colour */
+    --ag-ui-highlight-scrim: rgba(15, 15, 25, 0.45);
+    --ag-ui-highlight-gradient: linear-gradient(115deg, transparent 20%, #4f46e5 50%, transparent 80%);
+    --ag-ui-highlight-ring-width: 3;    /* unitless; px */
+    --ag-ui-highlight-flow-ms: 2400;    /* one pass of the gradient */
+    --ag-ui-highlight-z-index: 2147483001;
+  }
+  ```
+
+  `ringWidth` and `flowMs` options override the tokens per call; `color`, `padding` and `radius`
+  have no token because they are per-target rather than per-theme. The overlay's own styles are
+  inline and it lives in the light DOM, so neither a stylesheet rule nor `::part` can reach it —
+  these tokens and options are the whole surface, which is why they cover every value it draws.
+- `selectControl(el, value)` / `toggleCheckbox(el, checked)` — animate a `<select>` / checkbox.
+- `setControlValue(el, value)` — set a `<select>` or checkbox without animation, dispatching
+  `input`/`change`.
+
+Every driver primitive **awaits the scroll** before it animates. A smooth scroll is not awaitable
+on its own, so a highlight fired straight after `scrollIntoView` could be applied and removed
+while the element was still travelling — visible to nobody. Budget up to ~600 ms of settle time
+per action in a browser without `scrollend`; an element already in view costs ~100 ms.
+
+**Flash versus focus.** `focusWithFlash` does what its name says: it moves keyboard focus. That is
+rarely what you want just to *point at* something — it takes focus off the composer, can fire blur
+validation on whatever the user was mid-edit in, and can close an open menu. Reach for `flash(el)`
+to highlight, and keep `focusWithFlash(el)` for the case where the agent is about to type. Either
+way you can be explicit with `focus`:
+
+```js
+await flash(el);                            // highlight, focus untouched
+await focusWithFlash(el);                   // highlight and take focus
+await focusWithFlash(el, { focus: false }); // same as flash(el)
+```
+
+`focusWithFlash` focuses with `preventScroll: true`, so it cannot fight a smooth scroll that is
+still in flight.
+
+The native-setter helpers ([`native_setter.ts`](src/dom/native_setter.ts)) — `setNativeValue` /
+`setNativeChecked` — set a control through its native prototype setter so React-controlled inputs
+register the change.
+
+Each takes an element the caller has already located; host packages wrap them with
+environment-aware lookups (e.g. "find `#id_<name>`, then `fillField`").
+
+#### Ring colour
+
+Every ring the driver draws — the flash outline, the overlay ring, the press and toggle halo — is
+drawn in the host's page, outside the widget, so a token set on `ag-ui-chat` never reaches it
+through the cascade. The driver reads the widget directly instead, so on a page that themes
+nothing the rings follow the widget's theme: Quiet's near-black, Soft's violet, the dark half in a
+dark scheme. When a call passes no `color`, the first of these that is set wins:
+
+1. `--ag-ui-highlight-ring-color` on the target (so `:root` reaches every ring);
+2. `--ag-ui-highlight-ring-color` on the chat — on `ag-ui-chat` or anything above it;
+3. the target's `--ag-ui-accent`, so a page that themes its accent keeps the rings it has;
+4. the chat's resolved accent, its theme's default included, held to 3:1 against the page (below);
+5. the package indigo, when no chat is on the page at all.
+
+The chat's own accent follows the widget's scheme, not the page's, so a dark widget's near-white
+accent would all but vanish on a light page. When the ring falls to step 4 it is measured against
+**the surface behind the target**: the background of the target's parent, and of each element
+above it until one is opaque, composited over the page canvas (which follows the root's
+`color-scheme`). The target's own fill is not that surface, because the ring is drawn outside its
+box: a white field on a dark page is ringed on the dark page. Background images are not read. The
+ring takes the first of these that holds 3:1 there (WCAG 2.4.13): the accent as the chat resolves
+it, the other half of the chat's `light-dark()` pair, or the accent stepped toward black or white.
+Steps 1 to 3 are a host's own choice and are drawn as given, contrast or not.
+
+```css
+/* Rings in the brand colour, whatever the widget's accent. */
+ag-ui-chat { --ag-ui-highlight-ring-color: #0f766e; }
+```
+
+The halo of `pressThenClick` and `toggleControl` is the chosen colour at 40%. "The chat" is the
+most recently connected `<ag-ui-chat>`; on a page with two, pass the one acting as the `chat`
+option (`RingOwnerOptions`, which every ring-drawing primitive and `showHighlightOverlay` take).
+
+### Page-action tools
+
+Two built-in client tools let the agent perform common page interactions without every host
+re-implementing them. They are **opt-in** via `data-page-actions` — a comma list of the tokens you
+want — so you control the agent's interaction surface:
+
+```html
+<ag-ui-chat endpoint="/agent/" data-page-actions="scroll,drag"></ag-ui-chat>
+```
+
+- **`scroll_to`** — scroll a target into view. `target` is `"top"`, `"bottom"`, or a CSS selector
+  / page-map element id. Read-only (no confirmation). It centres the target **vertically** and
+  brings it into view **horizontally** (`inline: "nearest"`), so on a two-axis surface a
+  horizontal target lands at the near edge rather than in the middle. In view is the contract;
+  "centred" is not, in that axis.
+- **`drag_and_drop`** — drag the `from` element onto the `to` element (selectors / page-map ids),
+  firing the standard HTML5 drag sequence (`dragstart` → `dragenter`/`dragover`/`drop` → `dragend`)
+  so the page's own drop handler reacts. Useful for reordering sortable lists.
+- **`chat`** — four tools that let the agent move the panel it is speaking from:
+  `read_chat_surface`, `move_chat`, `minimise_chat`, `restore_chat`.
+
+  This is the one nobody else can offer. Every other assistant's chat is a surface of its own, so
+  there is nothing for it to be in the way *of*; ours is mounted in the page the user is working
+  in, which makes "let me move this aside so you can see the table" something the agent can act on
+  rather than apologise for.
+
+  **They report what happened, not what was asked.** A panel that fills the screen has nowhere to
+  move to, and a placement that places itself owns its position — so `move_chat` answers
+  `moved: false` with the reason and what would work instead, rather than reporting success on a
+  panel that did not budge. `read_chat_surface` is there so the agent can ask before it acts
+  instead of learning through a failure; it is read-only.
+
+  None of them is stamped `x-destructive`. Moving a window destroys nothing, and a confirmation
+  card in front of it would be worse than the move.
+
+**Your drag surface must listen to drag events, and many "modern" ones do not.** `drag_and_drop`
+dispatches the native HTML5 sequence with one shared `DataTransfer`. A surface built on a
+pointer-event drag library — dnd-kit, most React DnD packages, the Angular CDK — listens to
+`pointerdown`/`pointermove` and **never sees any of it**: the agent's drag is a silent no-op that
+still reports success. Either use the native API or pick a library that listens to drag events.
+React's synthetic `onDrop` does receive the dispatched sequence, `DataTransfer` included.
+
+**A page action reports that it fired, not that it worked.** `drag_and_drop` returns as soon as the
+sequence is dispatched; whether your drop handler's save succeeded is invisible to it, so a refused
+change still looks like a successful tool call. Two things follow. Have the page report its own
+refusals somewhere the agent can read them, and have the agent re-read the page before claiming
+anything. Where the outcome matters more than the gesture, call the operation as a **server tool**
+instead — it can return the real error.
+
+**A page that saves asynchronously should say so.** A verification read straight after a drag can
+outrun the page's own save and conclude that nothing happened. Report a busy flag in your
+`getPageMap` (`{ saving: true }` while a write is in flight) and the agent can wait for a page that
+says it is busy. It cannot wait for one that does not.
+
+Targets resolve through the overridable `resolvePageTarget` property — `(target) => HTMLElement |
+null`, defaulting to `document.querySelector`. A host with a page map overrides it to map its own
+element ids (the same way the DOM-driver primitives are wrapped with environment-aware lookups):
+
+```js
+chat.resolvePageTarget = (id) => myPageMap.elementFor(id);
+```
+
+**Destructiveness.** Page actions are *not* stamped `x-destructive` — a drag rearranges transient
+state, and the durable change happens at the page's explicit commit (a Save), which stays in the
+user's hands. If your page persists *on drop* (a kanban board firing a PATCH from the drop
+handler), gate `drag_and_drop` with [`confirmPredicate`](#inline-confirmation-x-destructive--x-confirm--confirmpredicate)
+— or don't enable it. A target that resolves to nothing returns a clean, model-readable tool error.
+
+---
+
+## New chat and collapse
+
+The header carries built-in buttons for a new chat (a pencil on a square), maximize (two arrows pointing out) and
+collapse (a chevron down, or on a sidebar a panel closing into its edge; `data-collapse-icon`
+chooses it). The
+matching JS API:
+
+- `newChat()` — clears the transcript, drops the in-memory run state, and mints a new thread id.
+  The conversation it leaves is **kept**: it stays in the history drawer to return to, and on a
+  server-backed store it stays on the server. Deleting one is the drawer row's own action. A chat
+  nothing was ever sent in is the exception — it was never listed, so it is dropped rather than
+  left behind. Focus moves to the composer, whichever control started the new chat, unless the
+  widget is collapsed, and the page is not scrolled to it. A restore still loading or replaying
+  the conversation being left stops there, so nothing of it is drawn into the new chat, and a
+  run it was about to resume after a reload is not resumed: coming back to that conversation
+  later answers the interrupted call as not finished. Called before the element connects (or while
+  it is out of the document), it waits: `threadId` stays `null` and nothing fires until the
+  element connects, which then starts the new chat, so the one `ag-ui-thread` event is a `new`.
+- `describeSurface()` — where the panel is and what can be done to it: placement, collapsed,
+  `maximized` (read-only), what it collapses to (`collapseTo`), whether it can be moved, whether it fills the screen, its box and the viewport. `movable` folds
+  the two reasons a move can fail into the one answer a caller needs.
+- `moveTo(corner)` — send the panel to `top-left` / `top-right` / `bottom-left` / `bottom-right`,
+  returning whether it went. It takes the axes the same way a user drag does, so the launcher
+  travels with it and switching placement hands them back. Returns `false` rather than pretending
+  when the placement owns its position or the panel fills the screen. Under `collapse-to="bar"`
+  or `"none"` it moves the panel within the room above the bar or the anchor.
+- `resetSize()` — drop the size the user dragged in the current placement, and its stored copy,
+  so the placement's own size and your `--ag-ui-width` / `--ag-ui-height` apply again; sizes
+  dragged in other placements are kept. For a host that enters a sized state of its own (an
+  expanded mode) instead of the built-in [maximize](#maximizing-the-panel): a user's drag
+  outranks host tokens, so call this first.
+  Under `collapse-to="bar"` or `"none"` it also returns a panel the user dragged off its dock to
+  the dock and forgets the stored spot; a corner panel under `auto` keeps its dragged position.
+- `setCollapsed(collapsed)` / `toggleCollapsed()` — collapse or expand the widget. The state is
+  reflected as the boolean `collapsed` attribute/property and persisted per-tab in
+  `sessionStorage`, so it survives a reload.
+
+Each change emits an `ag-ui-toggle` event (the `TOGGLE_EVENT` constant) with
+`detail: { collapsed: boolean }` (typed `ToggleDetail`), so a host can mirror the state in its own
+chrome — or hide the built-in toggle and drive the `collapsed` attribute itself.
+
+```js
+chat.newChat();
+chat.toggleCollapsed();
+chat.addEventListener("ag-ui-toggle", (e) => console.log(e.detail.collapsed));
+```
+
+### Maximizing the panel
+
+The maximize control (two arrows pointing out, `maximize-button` part, `icon-maximize` slot) grows the open panel,
+and pressed again it restores it (the arrows point in). It is labelled "Maximize" and "Restore" (the `maximize`
+and `restore` strings), apart from the launcher's and the rail's "Expand", which opens the panel.
+
+- **Where it is offered.** A corner panel (`floating`, `bottom-left`, the default) and a docked
+  one (`collapse-to="bar"` or `"none"`) grow on both axes; `sidebar` and `side` grow in width
+  only. `page`, `full` and `embedded` have no control, and neither does any viewport of 600px or
+  less, `data-small-viewport="off"` included. The control is absent from the header there, not
+  hidden, and the state is refused: a panel maximized when its placement switches to one of
+  these, or when the window narrows to 600px, leaves it.
+- **What it grows to.** `--ag-ui-maximized-width` and `--ag-ui-maximized-height`, which default
+  to the panel's cap (`--ag-ui-max-width` / `--ag-ui-max-height`, the room the host left less
+  one gutter). A side column reads the width only.
+- **The drag.** Entering it takes the dragged size off without forgetting it, and the resize
+  grips are hidden while it lasts. Restoring, and collapsing (which leaves the state), put the
+  placement's own size back, or the size the user dragged in it.
+- **The API.** `chat.maximized` (reflected as the `maximized` attribute), `setMaximized(bool)`
+  and `toggleMaximized()`. Each change emits `ag-ui-maximize` (the `MAXIMIZE_EVENT` constant)
+  with `detail: { maximized }` (typed `MaximizeDetail`). It fires only while connected: a
+  markup `maximized` is announced once at connect, and only if it holds (a panel that mounts
+  collapsed announces nothing), and a change made while detached is announced once on reconnect,
+  only if it differs from what listeners last heard. It is not stored: a reload opens at the
+  placement's own size. `describeSurface()` reports it, and no agent tool changes it.
+
+```js
+chat.addEventListener("ag-ui-maximize", (e) => console.log(e.detail.maximized));
+```
+
+```css
+ag-ui-chat { --ag-ui-maximized-width: 960px; --ag-ui-maximized-height: 85vh; }
+```
+
+`--ag-ui-min-page-width` keeps that much of the page beside a `sidebar` or `side` column: it caps
+the column's width at the viewport less it, whether the width was dragged, set by
+`--ag-ui-width`, or maximized. It is unset by default, which caps nothing.
+
+```css
+ag-ui-chat[placement="sidebar"] { --ag-ui-min-page-width: 480px; }
+```
+
+A host that wants its own sized state can still build it: hide the control
+(`ag-ui-chat::part(maximize-button) { display: none }`), slot a button into `header-actions`, set
+its own `--ag-ui-width` / `--ag-ui-height` in a class, and call `resetSize()` as it enters, so a
+dragged size does not outrank its tokens.
+
+### Driving the conversation from your own chrome
+
+A host that lists conversations in its own bar, rather than in the built-in drawer, drives the
+one on screen with the drawer's own paths:
+
+- `switchThread(threadId)` — put a stored thread on screen and replay it, as picking its row in
+  the drawer does. Returns a `Promise<void>` that resolves once the thread is drawn. **A run in
+  flight is cancelled**, as the drawer and `newChat()` cancel it; read `running` first if you
+  would rather wait. Switching to the thread already on screen does nothing, and so does a call
+  before the element connects; a second call for the thread that is still loading settles with
+  that load, after the replay. If the store rejects the load, the element stays on the thread it
+  was on, redraws it, fires no `ag-ui-thread`, and the promise rejects with the store's error.
+- `deleteThread(threadId)` — delete a stored thread, as the drawer row's delete does. Deleting
+  the thread on screen cancels its run and puts a fresh thread in its place; deleting another
+  leaves the screen alone. Prefer it to `conversationStore.clear()`, which deletes the record and
+  nothing else: the run, the transcript and the drawer are left pointing at it.
+- `threadId` *(read-only)* — the thread on screen, `null` before the element first connects.
+  It only reads. `conversationStore.threadId()` mints and stores a thread when the store points
+  at none, so asking it which conversation is showing can start one.
+- `threadTitle` *(read-only)* — the title of the thread on screen, `""` while nothing has been
+  sent in it. A title renamed here, or one the conversation list shows that the messages do not
+  derive (a server's own), wins; otherwise it is the first user message, and a first message that
+  is exactly a skill's `/token` reads as that skill's catalog `title`, else as the token in words
+  (`/summarize_draw` reads "Summarize draw"). It is set on the first send, before the server lists
+  the thread. Every change fires one **`ag-ui-thread-title`** event (`THREAD_TITLE_EVENT`, detail
+  `{ threadId, title }`, typed `ThreadTitleDetail`), after the `ag-ui-thread` event of the change
+  that caused it. `title-text="auto"` draws it without a listener.
+- `running` *(read-only)* — whether an interaction is in flight: the composer's own state, the
+  one it shows Stop for, across every tool round, a Retry and a checkpoint continuation as well
+  as a send. Reflected on the element as the `data-running` attribute, written by the element
+  rather than by you, as `data-empty` is, so the chrome around the chat can style on it.
+
+Every change of conversation fires one **`ag-ui-thread`** event (the `THREAD_EVENT` constant),
+after the transcript has been replaced, so a listener reads the conversation it is told about.
+`detail` is `{ threadId, previousThreadId, reason }` (typed `ThreadDetail`). `previousThreadId`
+is the thread the previous event reported, `null` before the first, and `reason` is one of:
+
+| `reason` | When |
+| --- | --- |
+| `new` | `newChat()` or the built-in New chat button. |
+| `switch` | `switchThread()` or a row picked in the drawer. Two switches made before the first had replayed report only the second. |
+| `delete` | The thread on screen was deleted, and a fresh one took its place. |
+| `restore` | The stored thread was replayed: when the element connects (`previousThreadId` is `null` the first time), or by `reload()`. |
+| `rescope` | A `user-key` change handed the element to another principal, live or while it was out of the document. |
+
+A page reload keeps restoring the thread, as [MPA durability](#mpa-durability-surviving-full-page-reloads) describes, and
+reports it as `restore`. Ignore a `reason` you do not know: more may be added.
+
+```js
+chat.addEventListener("ag-ui-thread", (e) => myBar.markActive(e.detail.threadId));
+myBar.onPick = (threadId) => chat.switchThread(threadId);
+```
+
+### The composer's own keys
+
+**Enter during a run queues.** A second run cannot start while one is in flight —
+it would orphan the first — so that key used to do nothing at all, silently. A
+checkpoint continuation picked from the panel counts as in flight from the pick
+rather than from its first event, which is a request later, so a turn typed in
+that gap is parked too rather than racing it. What
+is waiting shows above the composer as chips, each of which takes its message
+back when pressed, and the next one is sent when the run settles. Stopping the
+run discards them: sending into a conversation someone has just stopped is the
+opposite of what stopping meant. Nothing is lost, though — a queued message
+entered the recall history below when it left the composer, so **Up** gets it
+back after a Stop, and after its chip is taken back.
+
+The composer also walks back through what you have already sent, on **Up** and
+**Down** — the shape every shell and every coding agent uses. It holds every turn
+that left the composer: one sent at once, one queued behind a run (from the
+moment it is queued), and one sent to resume or fork a run from the checkpoint
+panel. A message sent with `sendMessage` is not in it, because it was never
+typed there. Only from an empty composer and only with the skills palette closed:
+an arrow inside text is how you move the caret, and taking it unconditionally
+would break editing to add a shortcut. Arrowing forward past the newest turn
+empties the box again, so the way out is the key that got you in. A walk lasts
+only while the composer holds the turn it put there: anything else that writes
+the box — typing, a quotation, a skill, dictation, or the host page itself — ends
+it, so the next arrow moves the caret in what was written rather than replacing
+it. The history is this conversation's: starting a new chat, switching threads
+or changing `user-key` clears it with the transcript.
+
+### Collapsing to the launcher
+
+A collapsed widget shrinks to a **floating launcher** in the corner it already occupies: the
+panel scales down into it and fades, the launcher grows out of the same point, and clicking the
+launcher reverses it. Only `transform` and `opacity` animate, so the motion is compositor-only and
+never reflows your page. Two placements collapse to something else instead — `sidebar` slides out
+to its [edge rail](#sidebar-placement), and `embedded` / `page` keep the header bar, since one is
+laid out by your page and the other is a full-screen route.
+
+The launcher's mark comes from the same seam as the header icon, most specific first: a slotted
+`slot="launcher"` child, then `data-launcher-icon-url`, then `data-icon-url`, then the built-in
+speech bubble.
+
+```html
+<ag-ui-chat endpoint="/agent/" data-launcher-icon-url="/mark.svg"></ag-ui-chat>
+
+<!-- or any markup at all -->
+<ag-ui-chat endpoint="/agent/">
+  <svg slot="launcher" width="26" height="26"><!-- ... --></svg>
+</ag-ui-chat>
+```
+
+```css
+ag-ui-chat {
+  --ag-ui-launcher-size: 48px;
+  --ag-ui-launcher-radius: 14px;  /* 50% for a circle */
+  --ag-ui-launcher-bg: #14532d;   /* defaults to the panel background */
+  --ag-ui-launcher-fg: #ffffff;   /* defaults to the text colour */
+  --ag-ui-launcher-icon-size: 22px;
+  --ag-ui-launcher-inset: auto 0 0 auto;  /* which corner of the widget's box */
+}
+```
+
+The sizes and defaults above are Quiet's. The other themes bring their own launcher: `classic`
+the 56px circle in the header's colours, `soft` a 56px accent tile, and `ledger` a 44px tile in
+the text colour.
+
+> **The collapsed host keeps its box.** Animating the element's own width and height would animate
+> layout; instead the box stays put with `pointer-events: none`, and the launcher takes the clicks.
+> A host measuring `getBoundingClientRect()` on a collapsed widget still sees the panel's
+> footprint — nothing there paints or takes input.
+
+#### The unread badge
+
+A collapsed widget is the one state where an answer can arrive with nothing on screen to say so,
+so the launcher carries a count of the answers that finished while it was closed (capped at `9+`).
+It is the only affordance here that is **on by default**; `data-unread-badge="false"` turns the
+badge off.
+
+**Unseen answers are kept per thread.** Each answer counts against the thread it ran on, and a
+thread is read only when it is on screen **and** the panel is expanded. On screen in a collapsed
+panel is not read. So an answer that finished on thread A while collapsed stays unread across a
+collapsed switch to B, a `newChat()`, or an expand on B, and is read once A is on screen in the
+open panel. `unread` is the total across threads, which is what the badge shows; it shows on the
+collapsed launcher only, so an open panel whose other threads hold unseen answers shows no
+badge. A principal change (a new `user-key`) drops the previous principal's marks, and deleting a
+thread drops its own.
+
+A store can carry read state across pages and devices, through two optional members. The element
+fetches the thread list when the drawer opens or a thread switches, not at page load, so a
+store's `unread` rows are counted from that fetch on: a page that never opens the drawer shows
+no badge for answers that finished elsewhere.
+
+- **`ThreadMeta.unread`** (boolean): a thread `listThreads()` reports as unread, and the page has
+  not counted, counts once, when the list is fetched.
+- **`markRead(threadId)`**: called when the element reads a thread with unseen answers, and when
+  an answer finishes on the thread in view. A server store maps it to its read endpoint, and
+  should list the thread with `unread: false` afterwards.
+
+A store without either still has its threads counted and cleared in the page. Neither is
+implemented by the default `SessionStorageStore`.
+
+The count is also the launcher's accessible name (`Expand — 2 unread`, from the `expandUnread`
+string), because a coloured dot says nothing to a screen reader.
+
+#### Moving the launcher
+
+The collapsed launcher can be dragged anywhere on screen, and it stays there — per tab, in
+`sessionStorage`, namespaced per element exactly like the collapsed, theme and size preferences.
+Arrow keys move it from the keyboard (`Shift` for a larger step). `data-launcher-drag="false"`
+turns it off; so does any placement that already places the launcher itself — `sidebar` collapses
+it to a full-height rail, `embedded` and `page` hide it and keep their header bar, and a
+full-bleed panel has no clear space to open into.
+
+**The panel then opens into whichever side of the launcher has more room.** For each axis the
+element compares the space a panel would have on either side of the launcher and pins the side
+with more of it, so a launcher dragged to the top-left opens down and to the right. What it
+compares is the room the *panel* would get, not which half of the screen the launcher is in —
+those give different answers either side of centre, and only the first one is about whether the
+panel fits.
+
+A launcher parked where the panel fits neither way — the middle of a short viewport — keeps its
+position anyway: the panel is clamped into the viewport and the launcher carries the difference,
+which is why it can end up sitting outside its own host box. Nothing clips it there.
+
+A drag writes `--ag-ui-inset` and `--ag-ui-launcher-inset` on the host, and an inline custom
+property outranks your stylesheet's rule for the same one — the same trade a dragged size makes
+against a placement. Switching to a placement that places itself hands both back.
+
+> **An undragged launcher is untouched.** With nothing stored, the element writes neither
+> property and your CSS decides, exactly as before. The geometry is built so that feeding it the
+> resting position reproduces the default `auto 24px 24px auto` unchanged.
+
+#### Moving the panel
+
+An open panel moves by its **header**, the way a window moves by its title bar.
+
+**The launcher travels the same distance.** Drag the panel 100px left and the bubble it collapses
+into is 100px left of where it was — it is one widget being moved, not two things being placed.
+The distance is the panel's own, so a panel held against the viewport's margin stops and the
+bubble stops with it, and the bubble is then held on screen in its own right.
+
+**A position you state is kept, not re-derived.** That is the difference between the two drags: a
+launcher drag says where the bubble goes and lets the panel open into whatever room the viewport
+has, which is re-decided on every expand and every window resize; a header drag states the
+panel's own position, so it survives collapsing, reopening and reloading. Dragging the bubble
+again hands the decision back. Both are stored per tab, and `data-launcher-drag="false"` turns
+off both.
+
+Which corner the panel is *pinned* by is re-picked when the drag ends, from where the bubble has
+ended up, so the next expand still opens into clear space. Re-picking it moves nothing: the
+corner only says which edges the two insets are written from, and both are written from positions
+that are already decided.
+
+The controls in the header keep their own presses — a drag started on a button, a link or a field
+never begins, including one you slot in.
+
+There is no keyboard shortcut on the header, deliberately. A header is not a control, and making
+it focusable would put a tab stop with no role ahead of the controls a keyboard user came for —
+while arrow keys on the collapsed launcher already move the widget, panel included.
+
+```js
+chat.unread; // 2
+
+// Every change, whether or not the badge renders it — so a host that hides the
+// badge can put the count in its own chrome. `threadIds` names the threads the
+// change marked or cleared, and is empty for a collapse toggle that touched none.
+chat.addEventListener("ag-ui-unread", (e) => setDockBadge(e.detail.unread, e.detail.threadIds));
+```
+
+```css
+ag-ui-chat {
+  --ag-ui-badge-bg: #b91c1c;   /* defaults to --ag-ui-danger */
+  --ag-ui-badge-fg: #ffffff;
+  --ag-ui-badge-size: 18px;
+  --ag-ui-badge-font-size: 11px;
+}
+```
+
+### Collapsing to a bottom bar
+
+`collapse-to` chooses what a collapsed panel becomes, for a host whose layout has a bottom
+toolbar. It is opt-in: absent, `auto`, or any other value leaves every placement as the
+sections above describe. It is live, like `placement`.
+
+- **`bar`: the component's own bar.** A strip along the whole bottom edge of the viewport, in
+  place of the round launcher: the title, the [unread badge](#the-unread-badge), and a running
+  indicator while an interaction is in flight. Pressing the strip toggles the panel, which rises
+  from the bar's right end with the bar still beneath it as the minimise target. The bar's
+  history button opens the conversation list as a popover above the bar, without expanding the
+  panel, its outer edge in line with the panel's on a wide viewport, and a second press closes
+  it; `openThreads()` while collapsed opens it too. Expanding the panel closes the popover, so the
+  panel opens on the conversation. It replaces the launcher only, so it applies to the corner
+  placements, `side` and `full`: `sidebar` keeps its rail, `embedded` its header bar, and `page`
+  has no collapsed state at all.
+- **`none`: your own bar.** Collapsed is hidden: nothing of the widget is left to see or hit,
+  under every collapsible placement. Your bar's button drives the [public
+  API](#driving-the-conversation-from-your-own-chrome) (`collapsed`, `toggleCollapsed()`), and
+  `anchor` names the element the panel rises from, right-aligned to it. An anchor that resolves
+  to nothing opens the panel from the placement's own corner, with one console warning.
+  While collapsed, `openThreads()` opens the conversation list as a popover beside the anchor,
+  or beside the element you pass as `openThreads({ anchor })`, which wins over the attribute and
+  property for that call. It opens below a button in the top half of the viewport and above one
+  in the bottom half, right-aligned to it and held inside the window (full width less 8px on a
+  phone). Picking a conversation switches to it and closes the list, and leaves the panel
+  collapsed: you get `ag-ui-thread` and decide whether to expand. Escape, a press outside,
+  `closeThreads()` and expanding the panel close it; a press on the button itself does not, so
+  your button can toggle the list. With no anchor at all, `openThreads()` warns once per call
+  and draws nothing. `embedded` hides the whole element while collapsed under `none`, so it has
+  no popover.
+
+```html
+<nav class="toolbar">
+  <!-- ... -->
+  <button id="agent-button" type="button">Agent</button>
+</nav>
+<ag-ui-chat endpoint="/agent/" collapse-to="none" anchor="#agent-button"></ag-ui-chat>
+<script type="module">
+  const chat = document.querySelector("ag-ui-chat");
+  const button = document.getElementById("agent-button");
+  button.addEventListener("click", () => chat.toggleCollapsed());
+  // Under none the element announces the state it mounted in, once, so the
+  // button can be labelled before anyone presses it.
+  chat.addEventListener("ag-ui-toggle", (e) => {
+    button.setAttribute("aria-pressed", String(!e.detail.collapsed));
+  });
+</script>
+```
+
+**Clearing your toolbar.** Under `none` the panel stands `--ag-ui-anchor-gap` (default `8px`)
+above the anchor's top edge. The anchor is the button, not the toolbar around it, so a button
+sitting inside a taller toolbar puts the panel's foot across the toolbar's top border. Set the gap
+to the button's distance from the toolbar's top plus the clearance you want:
+
+```css
+/* The button stands 7px below the toolbar's top edge; clear it by 8px. */
+ag-ui-chat {
+  --ag-ui-anchor-gap: 15px;
+}
+```
+
+A gap wider than the gutter is taken off the panel's max height as well, so a tall panel still
+stops at the top of the window.
+
+**A button in a header.** The panel opens on the side of the anchor with more room, so a button
+in a top header opens it below the button and one in a bottom bar opens it above, with no inset
+of your own. `anchor-side="above"` or `"below"` fixes the side; `auto`, the default, decides again
+when the window is resized (never during a drag), so an anchor near the middle of the window can
+change sides. Below the anchor the gap is measured from the button's bottom edge, and the max
+height is the room under it less one gutter. On either side the panel lines up with the anchor's
+right edge unless that would put either edge inside the 24px gutter of the window, where it stops
+instead; its width cap is the window less two gutters, maximized included.
+
+```html
+<ag-ui-chat endpoint="/agent/" collapse-to="none" anchor="#agent-button" anchor-side="below"></ag-ui-chat>
+```
+
+Under `none` the element dispatches `ag-ui-toggle` once as it connects, with whichever state it
+mounted in, collapsed or open. Under `auto` and `bar` it does not, as before. That event touches
+neither the stored state nor the unread count.
+
+**The page's space is yours.** The bar is fixed over the page, so a host pads its own page by
+the bar's height. The component never writes your CSS, and a custom property cannot carry the
+height up to your page (it inherits down, never up), so it hands you a number:
+`barHeight` (CSS px, read-only) and an `ag-ui-bar-height` event (the `BAR_HEIGHT_EVENT`
+constant, detail `{ height }`) on every change, including a font-size change. Both read `0`
+where no bar is drawn: under `auto` and `none`, on a phone while the panel is open, and while your
+size fills the window with the panel open. If you write the height into
+`--ag-ui-viewport-inset-bottom`, a panel that fills the box that leaves stays judged against that
+box once the bar goes and the box grows by the bar's height: it settles with the bar gone and room
+at its foot. Writing some other share of the height does not settle; publish it to your page as below.
+
+```js
+const chat = document.querySelector("ag-ui-chat");
+const pad = () => {
+  document.documentElement.style.setProperty("--chat-bar-height", `${chat.barHeight}px`);
+};
+chat.addEventListener("ag-ui-bar-height", pad);
+pad();
+```
+
+```css
+body {
+  padding-bottom: var(--chat-bar-height, 0px);
+}
+```
+
+**A fixed sidebar pushes your page the same way.** A docked `placement="sidebar"` (or `"side"`)
+is fixed over the page, so `dockWidth` (CSS px, read-only) and an `ag-ui-dock-width` event (the
+`DOCK_WIDTH_EVENT` constant, detail `{ width, side }`, `side` being `"left"` or `"right"`, as
+`data-side` says) hand you the width it covers at rest: the panel's width while open, the rail's
+(`--ag-ui-rail-width`, 52 by default) while collapsed to it, and `0` under `collapse-to="none"` or
+a launcher, under every other placement, on a phone while the panel is open, and under
+`--ag-ui-position: static`, where your own layout already makes room. The event fires once per
+change of the resting value, never per frame of the width transition, and once at the end of a
+resize drag.
+
+```js
+const chat = document.querySelector("ag-ui-chat");
+const push = () => {
+  const { dockWidth: width } = chat;
+  const side = document.querySelector("ag-ui-chat").getAttribute("data-side") ?? "right";
+  document.documentElement.style.setProperty("--chat-dock-left", side === "left" ? `${width}px` : "0px");
+  document.documentElement.style.setProperty("--chat-dock-right", side === "left" ? "0px" : `${width}px`);
+};
+chat.addEventListener("ag-ui-dock-width", push);
+push();
+```
+
+```css
+body {
+  padding-left: var(--chat-dock-left, 0px);
+  padding-right: var(--chat-dock-right, 0px);
+}
+```
+
+**No inset needed.** Under `bar` and `none` you do not set `--ag-ui-inset` to keep the panel off
+your toolbar: its max height is the viewport less the bar's height (or, under `none`, the
+distance to the anchor's top, or below it from the anchor's bottom) and one gutter, and its
+bottom sits on the bar or the anchor (its top, when it opens below).
+
+**Docked, and still movable.** On a wide viewport a docked corner panel (the corner placements
+under `bar`, or under `none` with or without an anchor) moves by its header, and `moveTo` moves
+it, as it would the corner panel it is; `describeSurface()` reports `movable: true`. There is no
+launcher to drag: the bar and your own control stay where they are.
+
+- **Above the dock.** A dragged panel stays inside the viewport and above the bar's top edge, so it
+  never covers the bar it minimises to. Under `none` with an anchor it stays above the anchor's
+  top edge the same way (below its bottom edge, when the panel opens below it), because the
+  anchor is your own way back and has to stay in view;
+  `--ag-ui-anchor-gap` no longer applies once the panel is dragged, and the screen-edge margin
+  (8px) does. Under `none` with no anchor only the viewport holds it, as for a corner panel.
+- **Remembered like a corner panel.** Minimising and reopening brings it back where it was
+  dragged, and so does a reload. The spot is kept apart from the one a corner panel stores under
+  `auto`, so switching `collapse-to` never puts one surface's spot on the other. A spot that no
+  longer fits, because the window shrank or the bar grew, is held inside the room that is left
+  and comes back whole when there is room again.
+- **Resizing.** A panel standing on its dock keeps the edges on the bar or the anchor still and the
+  free ones follow the grip. Once dragged off, every edge follows its grip, as on a corner panel.
+- **Back to the dock.** `resetSize()` drops the placement's dragged size and returns the panel to its dock,
+  forgetting the stored spot, so a reload opens it there too.
+- **Keeping it fixed.** `data-launcher-drag="false"` turns the header drag and `moveTo` off here as
+  everywhere else, and the panel stays on its dock.
+- **A host's size that fills the window.** Set `--ag-ui-width` and `--ag-ui-height` to the whole
+  window, with `--ag-ui-max-width` and `--ag-ui-max-height` out of the way (the defaults stop short
+  of it), and the panel stands at the start of the room you left free, whether it was moved or not.
+  The bar and the grips go while it does, as on a phone, with `barHeight` at 0 and the header's
+  minimise control as the way back. The bar comes back when the panel is collapsed, and both when
+  your size stops filling. The stored spot stays, and the panel goes back to it, or to its dock,
+  once your size stops filling. An inline `--ag-ui-inset` of your own stays where you wrote it.
+
+Placements that own their position (`side` and `full` under `bar`, `sidebar` and `embedded`
+under `none`) do not move, as without `collapse-to`.
+
+**Phones.** At 600px or less the open panel stays full-bleed, over the bar, and the header's
+minimise control is the way back; the bar shows only while collapsed, so no second strip sits
+at the bottom edge while the keyboard is up. The panel does not move there, and a spot dragged on
+a wide viewport does not apply: it comes back when the window is wide again.
+
+The bar is styled through the parts `bar` (the strip's wrapper, holding the launcher, the place and
+the history button) and `bar-history`, and the launcher's own parts (`launcher`, `rail-label`,
+`launcher-badge`) inside it.
+
+**The place in the bar.** When [`getPlace`](#where-the-user-is-the-place-chip) (or the route map
+standing in for it) names a place, the strip shows it beside the title as quiet secondary text: the
+`bar-place` part holding `place-label` and `place-detail`, the parts the chip uses. It comes from
+the chip's one read, so `refreshPlace()`, `popstate` and a withheld place update it as they update
+the chip. A long place truncates with an ellipsis before the history button leaves the strip, and
+no place draws nothing. A place the user withheld stays in the strip dashed and struck through
+(`data-excluded` on `bar-place`), because the bar must not claim the page is sent. The phone strip,
+shown while collapsed, carries it too.
+
+
+---
+
+## Charts
+
+Markdown here goes through a narrow sanitiser and images are off by default — a
+model-controlled image URL is fetched with no user interaction, which turns
+prompt-injected page data into a zero-click exfiltration channel. So a chart
+does not arrive as markup. It arrives as **data**, and the component builds the
+SVG itself: the model chooses the numbers, the component chooses the DOM.
+
+Off unless you ask for it, by either route or both:
+
+```js
+const chat = document.querySelector("ag-ui-chat");
+chat.enableCharts(["tool", "activity"]);
+```
+
+Order does not matter. Calling it after the element is on the page redraws any
+charts already in the restored history, so you do not have to reach the element
+before it connects — which you generally cannot.
+
+Specs are bounded, and anything outside is dropped rather than half-drawn: at
+most **20,000 points** and **2,000 labels**, and every point a finite number no
+larger than **1e15**. The first two keep a stored transcript from blocking the
+main thread on every reload; the last one keeps the value range finite, since
+scaling divides by it.
+
+**`"tool"`** registers a `render_chart` tool the agent may call. The numbers are
+in its context, so it can talk about them; it costs one model round.
+
+**`"activity"`** draws a chart the server pushes as an `ACTIVITY_SNAPSHOT` with
+`activityType: "chart"` (exported as `CHART_ACTIVITY_TYPE`). The data never
+reaches the model, there is no extra round, and this is the only route that can
+**update a chart in place** — the server repeats the same `messageId` to redraw
+it, or sends an `ACTIVITY_DELTA` to move one series as a computation advances.
+
+**Whether a pushed chart survives a reload depends on where the conversation is
+stored.** A client-side store keeps activities, so it comes back. A server that
+stores the thread as the model's message history does not — a pushed chart is
+deliberately not in that history, which is the reason to push it. A chart the
+agent asked for survives either way, because its spec travels as the tool call's
+arguments and the component redraws from those without re-running anything.
+
+Either way the payload is the same shape:
+
+```json
+{
+  "kind": "bar",
+  "title": "Signups this week",
+  "labels": ["Mon", "Tue", "Wed"],
+  "series": [{ "label": "new", "points": [12, 19, 9] }]
+}
+```
+
+`kind` is one of `bar`, `line`, `pie`, `scatter`, `stacked`; anything else is
+drawn as a bar rather than refused. Every series needs exactly one point per
+label — a shorter one misaligns every value after the gap, and a chart that is
+subtly wrong still reads as authoritative, so the whole spec is dropped instead.
+A pie's slices are its labels, so it draws the first series only.
+
+Theme the series with `--ag-ui-chart-1` … `--ag-ui-chart-6`, size it with
+`--ag-ui-chart-max-width`, and style the block through the `chart-block`,
+`chart-title` and `chart-legend` parts.
+
+**A chart stops at its own width, and is sized in pixels rather than scaled to
+them.** Two separate things, and a widened panel needs both.
+
+It is drawn for the width the block actually has -- one SVG unit per CSS pixel
+-- and redrawn when that width changes, so a 10px axis label is 10px in a 380px
+panel and in a 1200px one. Where the labels no longer fit, the axis draws every
+second or third rather than a smear of overlapping words. Below 220px it goes
+back to scaling, since at that size nothing fits either way.
+
+And it takes the width it needs rather than the width it is offered, capping at
+`--ag-ui-chart-max-width` (**480px**): widening the panel should no more resize
+a chart than it resizes a message. Raise the token for a bigger chart and the
+labels stay 10px -- the cap is about how much room the drawing gets, never
+about how big its type is. Height follows width inside a 160-320px band.
+
+### Drawing something other than a chart
+
+`render_chart` is built on a seam any tool can use. A `ClientTool` may declare a
+pure `render` beside its `handler`:
+
+```js
+chat.registerTool({
+  name: "show_route",
+  description: "Draw the route on a map.",
+  parameters: { type: "object", properties: { stops: { type: "array" } } },
+  handler: () => "route shown",
+  render: (args) => buildMapElement(args.stops),   // pure; no side effects
+});
+```
+
+**`render` is the only half a restored transcript replays.** Replaying a tool's
+*effect* is out of the question — re-running a form-filling tool on every reload
+is a bug. The replay path is handed the `render` function alone, never the tool
+that owns it, so the code that runs on restore cannot reach `handler` even by
+mistake: adding a "no render? fall back to the handler" convenience there means
+changing a type signature first, which is the moment the question gets asked.
+
+That is why `render` has to be a pure, deterministic function of its arguments —
+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 tool calls are drawn is set via the `data-tool-display` attribute (or `toolDisplay`
+property), one of `grouped` / `inline` / `minimal` / `compact` / `full` (default `grouped`; an
+absent or unknown value reads as `grouped`):
+
+- `grouped` — the default. A run's consecutive tool calls fold into one quiet row, **"Worked
+  through 5 steps"**, with a note such as **"1 failed"** beside it, and the calls one click down
+  as `full` cards, or in the mode `data-tool-group-display` names. Anything else in the turn (text, a confirmation, a question) ends the group, and
+  the next call starts a new one; a call's own rendered output does not. A group of one call shows that call's own label. See
+  [The step group](#the-step-group).
+- `inline` — the lightest mode: a single status row (icon + summary, no card chrome) with the
+  result behind its own toggle. Reads as one line of the answer — pairs with [the answer
+  well](#the-answer-well).
+- `minimal` — tool name + status pill only.
+- `compact` — name + status, with arguments *and* result behind a single collapsed toggle.
+- `full` — arguments visible, result behind the toggle. The default before `grouped`: set
+  `data-tool-display="full"` to keep per-call cards.
+
+Whichever mode is on, a settled card's body holds **two labelled regions** — `Arguments` and
+`Result` (or `Error` / `Declined`) — each with its own part and each pretty-printed. They are
+never run together into one block, so where the call ends and the answer begins is always
+visible. Style them via the `tool-card-args` / `tool-card-result` parts, their headings via
+`tool-card-section-label`, and the whole body via `tool-card-body`.
+
+**A card names its status as a part.** `::part()` takes no attribute selector, so a rule on
+`tool-card-status` reaches every outcome alike. The card and its status pill each carry a modifier
+beside the base part, one of `pending`, `deferred`, `done`, `error`, `declined` or `interrupted`,
+and it is replaced whenever the status changes:
+
+```css
+ag-ui-chat::part(tool-card-error)        { border-color: crimson; }
+ag-ui-chat::part(tool-card-status-error) { font-weight: 700; }
+```
+
+**The attribute is live.** Changing `data-tool-display` between the four card modes restyles every
+card already in the 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. Grouping is decided as
+each card is built: switching **to** `grouped` folds only the calls drawn afterwards, and
+switching **away** from it flattens the groups already drawn, by CSS, into exactly the cards the
+new mode builds (the group stops generating a box and its row is hidden).
+
+### Choosing how a group draws its calls
+
+Under `grouped`, an opened group draws its calls as `full` cards unless the
+`data-tool-group-display` attribute (or `toolGroupDisplay` property) names another of the card
+modes: `compact`, `minimal` or `inline`. Each draws the regions the flat card of that mode draws,
+laid out as a row of the group's list rather than as a boxed card. An absent or unknown value
+reads as `full`, so nothing changes for a host that does not set it.
+
+```html
+<ag-ui-chat endpoint="/agent/" data-tool-group-display="compact"></ag-ui-chat>
+```
+
+It is read only under `grouped`. Under one of the four card modes the groups are flattened into
+that mode's cards and the inner value is ignored; switching back to `grouped` applies it again.
+It is live like the outer attribute: changing it restyles groups already in the transcript.
+
+A call waiting on an approval shows its arguments and its Approve and Deny buttons in every inner
+mode, as it does in every card mode, and Approve takes focus when the group opens for it.
+
+### The step group
+
+Under `grouped` the row reads, by state:
+
+| State (`data-state` on the `tool-group` part) | Label | Mark |
+| --- | --- | --- |
+| `running` | "Working through 3 steps", and the running step's label as a note | spinner |
+| `waiting` | "3 steps", with "1 waiting for you" | accent dot |
+| `done` | "Worked through 3 steps" | check |
+| `error` | "Worked through 3 steps", with "1 failed" in the danger colour | error mark |
+
+"N declined" is added as a note whenever a step was declined. `data-count` carries the number of
+steps and `data-open` whether the cards are showing; the head is a button with `aria-expanded`.
+
+- **It opens itself while a step waits on you.** A server-side approval renders inside the gated
+  call's own card, so a folded group would hide the question it is asking: the group opens when a
+  step goes `deferred`, once per wait, and stays folded if you fold it again. It opens before the
+  approval is drawn, so the Approve button takes focus and scrolls into view. A client-side
+  confirmation and an `ask_user` question render in the answer beside the group rather than inside
+  a card, so they are in view without it opening; the row still reads `waiting` ("1 waiting for
+  you") while one is open, as the card carries a `data-asking` flag for the group to read, and its
+  `data-status` stays `pending`.
+- **A one-step group is named after its call, and the card's head is not repeated inside.** A turn
+  with exactly one call reads as that call's label ("Fill field"), and the opened list shows the
+  card without its own `tool-card-head` (the row's state mark and notes carry the status). The
+  Details toggle and arguments stay, except under `data-tool-group-display="minimal"`, where the
+  card is only its head: there the row draws no chevron, though it still opens for an approval. A
+  card display mode keeps the head. A run that grows to two calls brings both heads back.
+- **A running sub-agent does not open it.** The row keeps its spinner and names the delegation
+  instead, "Delegated to researcher" (the `subAgentDelegatedTo` string).
+- **Repeated labels are told apart.** Two "Fill field" steps read "Fill field" and "Fill field
+  (2)": the ordinal is an element of its own (part `tool-card-repeat`) beside the card's name, so
+  `tool-card-name` is never rewritten, and a card mode hides the ordinal.
+- **Rendered output stays in view.** A tool's `render` output is placed after the group, in call
+  order, rather than inside it, so a chart is never one click down. It does not end the group: a
+  later call joins the group above it, which is also how a restored conversation draws the run.
+
+Parts: `tool-group` (with the state beside it as `tool-group-waiting`, `tool-group-running`,
+`tool-group-done` or `tool-group-error`), `tool-group-head` (the button), `tool-group-icon`, `tool-group-label`,
+`tool-group-meta` (holding one `.tool-group-note` per note), `tool-group-list` (the cards), and
+`tool-card-repeat` on a repeated step. The focus ring is `--ag-ui-ring` and the disclosure chevron
+`--ag-ui-ico-chevron`. Strings (`strings` / `data-strings`): `toolGroupSteps`,
+`toolGroupWorking`, `toolGroupWorked` (each with `{count}`, always 2 or more), `toolGroupWaiting`,
+`toolGroupFailed`, `toolGroupDeclined` (each with `{count}`) and `toolStepRepeat` (with `{n}`).
+
+```html
+<!-- Keep per-call cards, as before grouped was the default -->
+<ag-ui-chat endpoint="/agent/" data-tool-display="full"></ag-ui-chat>
+```
+
+### 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
+prompt and a record are different objects, and the record is the card.
+
+**The annotation is session-scoped**, like the "run interrupted" notice. AG-UI carries no
+approval message — the answer rides `resume[]` as transient run input — so a reload restores the
+tool call and its result but not the note that a human waved it through. If you need "who
+approved what" durably, that is an audit concern rather than a transcript one; record it
+server-side.
+
+If a tool's schema carries an `x-summary` string (use `X_SUMMARY_KEY`), the card shows it on the
+label instead of the raw tool name.
+
+Every card leads with a **status icon** drawn entirely in CSS — a spinning ring while the call
+runs, then a check / cross / slash / dotted ring on success / error / decline / not finished.
+Re-theme it via custom properties (or the `tool-card-icon` part): `--ag-ui-tool-icon-done`,
+`--ag-ui-tool-icon-error`, `--ag-ui-tool-icon-declined`, `--ag-ui-tool-icon-interrupted`
+(quoted-string glyphs) and `--ag-ui-tool-spin-duration` (spinner
+speed; the spin respects `prefers-reduced-motion`).
+
+```html
+<ag-ui-chat endpoint="/agent/" data-tool-display="compact"></ag-ui-chat>
+```
+
+---
+
+## 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 grip on **every edge and every corner**, so it can be
+dragged from whichever side you are already near.
+
+- `placement="page"` gets **no grips** — a full-bleed layout
+  is `100vw`/`100vh` by definition, so there is nothing to drag.
+- `placement="sidebar"` keeps only the two vertical edges;
+  the placement owns the height, so a horizontal edge or a corner would
+  advertise a drag that does nothing.
+- Everything else gets all eight.
+
+**The edge a grip does not drag is the one that stays put.** That is the whole
+model: the left grip moves the left edge and holds the right, the right grip
+does the reverse, a corner does both axes. A grip names its own edge, so no
+layout can invert it.
+
+### Dragging the edge your layout was holding still
+
+A floating panel pinned bottom-right cannot grow rightward on its own — its
+right edge is what the placement fixed. So **a drag on a pinned edge moves the
+panel as well as resizing it**, and the component takes the position over by
+writing `--ag-ui-inset`, the same ownership a dragged launcher takes.
+
+A grip on a free edge writes nothing but the size, exactly as before, so a host
+positioning the panel with its own rule keeps that rule until someone drags the
+edge it was holding.
+
+Which edges those are belongs to *your* CSS rather than to `placement` — a
+floating panel a host right-aligns is anchored bottom-left — so the element
+probes its own geometry and reflects the result as `data-resize-anchor` (e.g.
+`bottom-right` means those two edges are fixed). Nothing in the stylesheet reads
+it any more; the element uses it to decide what a drag on a pinned edge costs,
+and which grip carries the keyboard.
+
+> **The probe shrinks rather than grows.** Growing by a pixel cannot answer the
+> question at a size already resting against `max-width` or `max-height`: the
+> box does not change, no edge moves, and every clamped axis reads as pinned on
+> the side that is actually free. That was reachable with no user action at all
+> — the default panel is 380px wide against a max-width of `100vw - 48px`, so
+> any viewport under 428px was born clamped, with the grip on the wrong corner
+> and the drag inverted.
+
+### Sizes, keyboard, and parts
+
+A drag writes the private `--_drag-width` / `--_drag-height` on the host, not
+your `--ag-ui-width` / `--ag-ui-height` tokens, which stay yours. The precedence
+is:
+
+- **Above 600px**, the dragged size beats a host's `--ag-ui-width` /
+  `--ag-ui-height`, `!important` included, so a user who resized the panel keeps
+  their size. A host that enters a sized state of its own (an "expanded" class)
+  calls `resetSize()` when it does, which drops the current placement's dragged
+  size and its stored copy and hands control back to the host tokens. A host
+  with no such state needs nothing.
+- **Per placement.** A dragged size belongs to the `placement` it was dragged in
+  and is stored under it: absent and `floating` share one, and `bottom-left`,
+  `sidebar`, `side` and `embedded` each keep their own (`data-side` is not a
+  placement, so a left and a right sidebar share one). Switching `placement`
+  swaps in the new placement's size, or its default when it has none, so a
+  placement switch needs no `resetSize()`. A `collapse-to` change keeps the size.
+  A size stored by a release before this one is read as floating's.
+- **At 600px or less**, the small-viewport shape ignores the dragged size
+  entirely, for the placements that block covers (`floating`, `bottom-left`,
+  `sidebar`, `side` and the default): the panel is full-bleed whatever was
+  dragged or stored, and a window narrowed after a wide-window drag goes
+  full-bleed too. `page` is already that shape, and `embedded` is left to the
+  host's own box, so neither is touched by the block. `data-small-viewport="off"`
+  keeps a dragged size at every width on the covered placements.
+
+A dragged size is a private property, so a host should not read it back from
+the element's inline style; use `getBoundingClientRect()`, or `resetSize()` to
+clear it.
+
+**A custom property alone does not leave placement in charge** — an inline custom
+property still outranks a `:host([placement=…])` rule setting the same property. So the
+component enforces the split directly: **a placement owns the axes it fixes**,
+and a dragged or persisted size is only ever applied to the ones it leaves free.
+Switching placement hands the owned axes back. Without that, a height dragged
+while floating capped a docked sidebar that had asked for `100vh`.
+
+**A host rule that sizes the element wins over both.** `ag-ui-chat { flex: 1 }`
+stretches the panel to its container and the dragged width has no visible
+effect — which reads as a broken control rather than as your stylesheet winning.
+Give the element `flex: 0 1 auto` (plus `max-width: 100%`) if it lives in a flex
+container.
+
+The size persists per tab (`sessionStorage`, namespaced per element like the
+collapsed and theme preferences) and is restored before the first paint.
+
+**Exactly one grip is in the tab order** — the corner diagonally opposite the
+pinned one, so an arrow key changes the size and never the position. Eight
+separators between the transcript and the composer would be a keyboard
+obstacle rather than keyboard parity, and one grip already reaches both axes.
+Arrow keys resize from it (`Shift` for a larger step).
+
+Each grip draws a short pill centred on its edge — a dot in a corner — on hover
+and focus as well as during a drag. **The hit area and the mark are separate on
+purpose**: the area is the whole strip, so the grip is easy to catch, while the
+mark stays small enough that it cannot be read as a border and never meets the
+panel's corner radius.
+
+Every grip has its own part (`resize-handle-left`, `resize-handle-bottom-right`,
+and so on, plus `resize-handle` on all of them). Hit areas and marks are sized
+separately, so a coarser pointer can get a bigger target without a heavier mark.
+
+```css
+ag-ui-chat {
+  --ag-ui-grip-corner: 20px;          /* the corner squares */
+  --ag-ui-grip-edge: 10px;            /* the edge strips */
+  --ag-ui-grip-mark-length: 28px;     /* the pill drawn inside them */
+  --ag-ui-grip-mark-thickness: 3px;
+}
+```
+
+---
+
+## Markdown rendering
+
+Assistant bubbles render sanitized markdown/HTML via [`marked`](https://www.npmjs.com/package/marked)
+(GitHub-flavoured, single-newline line breaks) piped through
+[DOMPurify](https://www.npmjs.com/package/dompurify). User messages stay literal text. The
+allowlist permits emphasis, code, lists, quotes, headings, links, tables, and — when `allowImages`
+is set — images; links are hardened with `target="_blank" rel="noopener noreferrer"`;
+`iframe`/`style`/scripting are excluded, as are every `data-*` and `aria-*` attribute and every
+`class` but a code fence's `language-*` hint, so model output cannot dress itself up as the
+component's own approval or tool-call chrome. The exported helper `renderMarkdown(text)` does this
+standalone. `marked` and `dompurify`
+are runtime dependencies.
+
+An animated 3-dot "thinking" indicator (`role="status"`, with an aria-label) appears before the
+first token and between tool rounds, honouring `prefers-reduced-motion`. It has no public API.
+
+### Incoming-text animations
+
+The `data-text-animation` attribute controls how a fully-received assistant message reveals:
+`none` (default) / `fade` (a CSS fade) / `word` (JS word-by-word via the internal `wrapWords`
+reveal). It honours `prefers-reduced-motion` (collapsing to instant).
+
+```html
+<ag-ui-chat endpoint="/agent/" data-text-animation="word"></ag-ui-chat>
+```
+
+---
+
+## 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**.
+  **Off unless you ask for them** — `data-message-actions="copy,retry,feedback"`.
+  Without a listener the buttons still latch, so a reader is told a rating was
+  taken while nothing recorded it.
+
+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>
+```
+
+The default is `copy,retry`. Those two work with nothing wired; the rating pair
+needs a listener, so it is asked for rather than assumed.
+
+### What Copy puts on the clipboard
+
+Both flavours of the message: `text/plain` for anywhere, and `text/html` for a
+target that understands it. A table therefore pastes into a spreadsheet as
+columns and into a document as a table.
+
+The plain flavour is serialised structurally rather than read off `textContent`,
+which is the obvious source and loses everything: it concatenates descendants
+with no separator, so a table arrives as one unbroken run of cells with the
+headers welded to the first row. Rows are tab separated because that is what a
+spreadsheet splits on; list items keep their bullets and numbers; a code block
+keeps its own whitespace.
+
+Both flavours are taken from a copy of the message with the component's own
+buttons removed. The code blocks' copy buttons live *inside* their `pre`, so
+they are descendants of the message: before this, copying an answer containing a
+code block copied the word Copy along with it.
+
+A host that drives its own bar gets the same by passing `html` alongside `text`
+to `attachMessageActions`; with `text` alone the clipboard gets plain text only,
+exactly as before.
+
+### Sizing and theming the row
+
+The controls are icon-only, so the whole box is the target. It is sized from
+`--ag-ui-action-size`, with a floor rather than a fixed height so the compact
+density cannot shrink it below the 24px that keeps it reliably tappable.
+
+Each control draws its own label on hover **and on keyboard focus**. That is not
+the `title` attribute repeated: a `title` never appears on focus, so an
+icon-only button is unnamed for anyone tabbing to it. On a touch device, where
+there is no hover to reveal it and it would sit over the answer, it is not
+drawn at all.
+
+```css
+ag-ui-chat {
+  --ag-ui-action-size: 28px;        /* the control box; floors at 24px */
+  --ag-ui-action-icon-size: 15px;   /* the mark inside it */
+  --ag-ui-tooltip-bg: #1f2430;
+  --ag-ui-tooltip-fg: #f5f6fa;
+}
+```
+
+To swap a mark for your own, style its part — `message-action-icon-copy` and its
+siblings. A slot would be the better channel and cannot be used: these repeat
+once per message, and a named slot can only be filled once.
+
+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
+await chat.retryLastTurn(); // false when there is nothing to ask again, a run is in flight, or a restore is loading
+```
+
+### Storing a rating
+
+`ag-ui-feedback` names the message that was rated, so a host can file the
+rating against it rather than against its text — two answers can read the same,
+and nothing about the text survives a reload:
+
+| Field | Type | What it is |
+| --- | --- | --- |
+| `messageId` | `string` | The AG-UI id of the rated assistant message: the id it streamed under (`TEXT_MESSAGE_START` / `TEXT_MESSAGE_END`), or the stored message's `id` when it was restored from history. A restored answer whose store returned no id offers no rating pair, since a rating has to name a message. |
+| `threadId` | `string` | The conversation it belongs to: the element's thread when the message was drawn. |
+| `runId` | `string`, optional | The run that streamed it, as that run's `RUN_STARTED` named it. Text a sub-agent streams through the parent run carries the parent's `runId`. **Absent on a restored message** — an AG-UI message carries no run id, so there is none to give and the key is left out rather than guessed. |
+| `content` | `string` | The message's text, as rendered. |
+| `rating` | `"up"` \| `"down"` | Which button. |
+
+```js
+chat.setAttribute("data-message-actions", "copy,retry,feedback");
+chat.addEventListener("ag-ui-feedback", (e) => {
+  const { messageId, threadId, runId, rating } = e.detail;
+  // Keyed by message: rating the same answer again replaces the earlier rating.
+  fetch(`/api/threads/${threadId}/ratings/${messageId}/`, {
+    method: "PUT",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ rating, ...(runId === undefined ? {} : { runId }) }),
+  });
+});
+```
+
+> [!NOTE]
+> **A restored message is named by whatever `id` the conversation store returns
+> for it.** The built-in browser store saves the conversation as it streamed, so
+> there a message keeps its id across a reload. With `data-threads-url` or a
+> `conversationStore` of your own, the conversation comes back from your server,
+> and a message keeps its id only if the server persists the ids it streamed:
+> one that stores the conversation under fresh ids makes a rating made live and a
+> rating made after a reload name the same answer by two different ids. Live,
+> the id is always the one on the wire.
+
+## 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
+earlier turns to fit the context window, or the model pulled in an agent skill. Those render as
+**run notices**: a muted one-line annotation inline in the transcript, styleable via the
+`run-notice`, `run-notice-icon` and `run-notice-text` `part`s.
+
+> **Two different things are called "skills".**
+> The [prompt chips and slash palette](#skills-prompt-chips-and-slash-palette) below are a
+> **human** affordance — prompts *the user* launches. An **agent skill** is a folder of
+> instructions *the model* chooses to load mid-run. Only the second produces a run notice.
+
+Neither notice needs configuration here — both appear when the server is set up to produce them.
+
+**Compaction.** `django-ag-ui` emits a standard AG-UI `ACTIVITY_SNAPSHOT` with
+`activityType: "compaction"` when a compaction capability trimmed the history; the notice reports
+how many messages went. Server side, that means wrapping the capability in `CompactionObserver` —
+see [django-ag-ui's compaction guide](https://artui.github.io/django-ag-ui/compaction/). Activity
+events of any other type pass through untouched, so another producer on that channel is not
+mistaken for a compaction.
+
+**Agent skills.** There is no dedicated event for these: loading a deferred capability *is* an
+ordinary `load_capability` tool call, which is what reaches the client. The component recognises
+it, renders `Using skill <id>`, and suppresses the raw tool card that would otherwise appear
+beside it — on the live stream and on restored history alike, so a reload shows the same
+transcript. A `load_capability` call with no usable id falls back to a normal tool card rather
+than being dropped, since it is still real activity.
+
+Both strings are overridable like every other — `historyCompacted` (token `{count}`) and
+`usingSkill` (token `{name}`).
+
+## Skills: prompt chips and slash palette
+
+Skills are pre-defined prompts the user can launch from a chip or the `/`-command palette. They are
+opt-in via two attributes:
+
+```html
+<ag-ui-chat endpoint="/agent/" data-prompt-chips="true" data-slash-commands="true"></ag-ui-chat>
+```
+
+A `Skill` is `{ name, title, description?, prompt?, sendImmediately?, chip? }`. Skills are merged
+from three sources — **backend → embed → client** (later wins by `name`):
+
+- `data-skills-url` — a JSON endpoint, fetched with the element's `headers`.
+- `data-skills` — an inline JSON catalog.
+- `setSkills(skills)` — set the client catalog from JS.
+
+```js
+chat.setSkills([
+  // Server-resolved: no prompt here, so picking it sends the bare "/triage"
+  // token and the agent decides what it means.
+  { name: "triage", title: "Triage this", chip: true },
+  // Client-side: the page owns the wording and fills the placeholders.
+  { name: "summarize", title: "Summarize page", prompt: "Summarize {title}.", chip: true },
+]);
+```
+
+**Prefer omitting `prompt` for anything internal.** A skill is often where a project's workflow is
+written down most plainly, and a catalog is either a plain `GET` or sits in the page source — so
+shipping the wording to the browser publishes it. Without a `prompt` the component sends `/name`
+and the agent expands it (from the harness `Skills` capability, or your own instructions); the text
+never leaves the server. `django-ag-ui`'s `SkillRegistry` supports this by leaving `prompt` unset.
+
+A skill that *does* carry a `prompt` may use `{placeholder}` tokens; the `skillContext` property
+(`() => Record<string, unknown>`) supplies the values, filled in before send. A missing placeholder
+blocks the send and shows a hint instead.
+
+```js
+chat.skillContext = () => ({ title: document.title });
+```
+
+**Picking a skill sends it.** A chip that needs a second click to do anything is a two-step
+shortcut. Set `sendImmediately: false` on a prompt-carrying skill to pre-fill the composer instead —
+useful when the user is expected to edit before sending. A server-resolved skill always sends.
+
+---
+
+## MPA durability: surviving full page reloads
+
+In a multi-page app, a tool that navigates reloads the whole page and destroys the in-memory run
+loop. The package keeps the conversation continuous across that boundary with three generic
+mechanisms.
+
+**1. Thread identity.** AG-UI's `thread_id` is the conversation key. It is generated once and
+persisted (so the element reattaches after a reload) by the
+[`ClientConversationStore`](src/core/conversation_store.ts).
+
+**2. Durable conversation.** A pluggable `ClientConversationStore` holds the message list. The
+default [`SessionStorageStore`](src/core/conversation_store.ts) keeps everything per-tab in
+`sessionStorage`, so the chat survives full page reloads and clears on tab close. `loadMessages`
+is async-friendly, so a host can inject a server-backed store (e.g. one that rehydrates from a
+history endpoint) for cross-tab/device durability:
+
+```js
+chat.conversationStore = new MyServerBackedStore();
+```
+
+On mount the element rehydrates the transcript from the store, so the chat looks continuous —
+including tool-call cards and their results (reconstructed from the persisted `toolCalls` and `tool`
+messages), not just the text turns.
+
+A tool message is saved with an **`outcome`** in its `metadata` when the call did not simply
+succeed, in the same vocabulary the wire uses (see [A tool call that failed](#a-tool-call-that-failed)),
+so a failed or declined card replays as failed or declined instead of turning green on reload. A user
+message keeps the refs of its uploads the same way, under `attachments` in its `metadata`. Both
+round-trip through `JSON.stringify` in the default store. **A store that drops `metadata` loses only
+the distinction** — the card falls back to *done*, which is what it did before, and the bubble loses
+its chips.
+
+What is saved is exactly what the next request sends, so both go back to the server on every run.
+That is the protocol's own behaviour for a declared field rather than a client-side addition: a server
+validates `metadata` as an open object, and one that does not read a key ignores it — django-ag-ui
+reads `attachments` and ignores `outcome`.
+
+A conversation stored by an earlier release has both keys at the top level of the message instead.
+The history replay reads them from there when the metadata has none, and a client seeded from such a
+conversation moves them into `metadata` before its first request, because `@ag-ui/client` 1.0 would
+strip them from the request as it stands. The next save writes them in the new shape.
+
+**3. Resumable loop (`x-navigates` + `navigationResult`).** A tool whose schema carries
+`x-navigates: true` (use `X_NAVIGATES_KEY`; read back by [`isNavigates`](src/tools/is_navigates.ts))
+triggers a full reload. Before the handler navigates, the element writes a checkpoint
+(`{ toolCallId }`) to the store. On the next page mount it:
+
+1. restores the transcript,
+2. completes the dangling navigating tool call by supplying a result built from the landed page
+   via the overridable **`navigationResult(checkpoint)`** callback (defaults to
+   `{ navigated: true, url }`; a host can return a page snapshot or post-reload validation errors
+   instead),
+3. and resumes the run loop from there.
+
+The MPA round-trip becomes a clean observation point instead of a dropped conversation.
+
+**A reload the run did not expect settles every open call as not finished.** A round's history is
+saved when its stream ends, before the element asks about a gated call, runs a frontend tool or
+collects a server-side approval, so a reload in that window finds the round's calls with no result
+and no run left to produce one. On restore, every call without a result (other than a checkpointed
+navigating call) is answered the way the client answers an open call before a request: its card
+settles as `interrupted` ("not finished"), and the restored conversation gains the `callNotFinished`
+result with the outcome `interrupted`, so the next request carries a result for every call and a
+later reload shows the same.
+
+It is not declined, although Stop declines an open card. Pressing Stop is a person answering the
+question; a reload answers nothing. The saved history is the same whether the round was waiting on a
+person or on a frontend tool the reload killed, so a decline would be unproven for one and false for
+the other, and "not finished" is true of both. The same goes for a server-side approval left open.
+
+### Who the stored conversation belongs to (`user-key`)
+
+`sessionStorage` is scoped to a tab, not to a session. It survives every same-tab navigation,
+and a logout is a navigation — so on a shared workstation, one user's transcript is still sitting
+there when the next user signs in and the chat mounts again. Transcripts routinely quote record
+data, so treat that as the default and turn it off:
+
+```html
+<ag-ui-chat endpoint="/agent/" user-key="{{ request.user.pk }}"></ag-ui-chat>
+```
+
+The value is any string that identifies the principal — a user id, an account id, a hash of one.
+It joins the storage namespace, so two principals in the same tab cannot reach each other's
+conversation, and **changing it purges everything the previous principal stored**: transcript,
+history drawer index and navigation checkpoints, for this element's namespace only. The tools they
+waived with *Always allow* are forgotten with it, so the next principal is asked again, and so is
+[`sharedState`](#host-seams-the-spa-story): whatever the agent last wrote into it for them is cleared rather than
+sent on the next principal's first run, so a host that seeds shared state assigns it again for the
+principal who arrived.
+
+A handover also ends what the previous principal had in flight. Their run is stopped, and nothing
+it does afterwards is written into the next principal's storage or shared state: not the save a
+stopped run makes once its request closes, not a tool result that comes back after the Stop, not
+state already on its way. A tool call still waiting on `confirmPredicate` or its confirmation card
+does not run, one whose handler is still running draws nothing when it returns, and a navigating
+tool's checkpoint is never written into the next principal's thread. What they had typed into the
+composer and not sent is cleared with the transcript, quotations and skill templates included. A
+voice recording in progress is stopped before it is transcribed, and a clip already sent for
+transcription is dropped when its transcript comes back.
+
+Set it live, from script, as part of signing out or in:
+
+```js
+chat.userKey = String(session.userId); // or "" on sign-out
+```
+
+That is why it is a live attribute rather than a connect-time one. A single-page app signs a user
+out through its own router without remounting anything, so the host naming the new principal — or
+dropping the attribute — is the only signal the element will ever get. Removing the attribute
+purges too, so a sign-out that simply clears it is safe.
+
+It holds for an element that is out of the document too, such as a view a router keeps alive.
+Nothing is purged while it is detached: the handover runs when it is inserted again, against the
+key it has by then, so a key that changes and changes back while detached hands nothing over. An
+element that is never inserted again leaves the previous principal's conversation in
+`sessionStorage` under their key, where only an element naming that principal again can reach it.
+
+The **first** value to arrive is treated as a host naming the user who was already there, not as a
+handover: the conversation in progress moves into the principal's namespace instead of being
+destroyed. So an element configured by an async auth handshake — the shape described in
+[Framework hosts](#framework-hosts-configure-before-you-insert) — keeps what is on screen,
+including a run still streaming and whatever is in the composer.
+
+Two things it deliberately does not do. It does not scope the panel's own collapsed / dragged-size
+/ theme preferences, which are this element's UI state and carry no conversation content. And it
+does not encrypt or hide anything from the page: any script on the origin can still read
+`sessionStorage`. It scopes and it purges.
+
+**Without it, nothing changes** — including the carry-over above. A conversation is scoped to the
+element and to nobody in particular, and on a shared workstation it will be there for whoever signs
+in next in the same tab.
+
+For a deployment that keeps history server-side, `data-threads-cache="false"` stops the local
+mirror of the message bodies as well, so choosing `data-threads-url` actually keeps transcripts off
+the client:
+
+```html
+<ag-ui-chat endpoint="/agent/" data-threads-url="/agent/threads/" data-threads-cache="false">
+</ag-ui-chat>
+```
+
+The client-only concerns (the active thread id, the navigation checkpoint) keep their local store
+either way, so reloads and navigating tools still work. What is lost is the offline fallback: when
+the thread endpoint is unreachable the transcript comes back empty rather than stale, and the
+drawer's offline list loses its previews — a preview being an excerpt of a message, which is the
+thing being kept off the client. Constructing the store yourself takes the same option:
+
+```js
+chat.conversationStore = new RemoteConversationStore(
+  "/agent/threads/",
+  () => ({ "X-CSRFToken": token }),
+  new SessionStorageStore(),
+  () => "same-origin",
+  false, // cacheMessages
+);
+```
+
+A conversation store you assign yourself is never replaced by a change of `user-key`, whether you
+assign it before the element connects or after. The one exception is a plain `SessionStorageStore`
+assigned before the element connects: that is the same kind as the element's own default, which is
+all connecting can see, so the element namespaces it as its own and moves it on every key change.
+Assign it after connecting, or wrap it, to keep it yours. A store that keeps its data somewhere
+the element cannot see has to scope itself; the element purges only its own `sessionStorage`
+namespace and clears what is on screen. If your store wraps a `SessionStorageStore`, build a new
+one per principal.
+
+`SessionStorageStore.purge(namespace)` is the same primitive the element uses, for a host driving
+its own store from its own sign-out path.
+
+### Mounting more than one chat on a page
+
+Give each `<ag-ui-chat>` its own `id`. The storage namespace is the element's `id`, falling back to
+its `endpoint` — so two elements with no `id` against the same agent mount (a docked support panel
+and an inline page assistant, say) would resolve to the same namespace and share a thread pointer,
+a history drawer and every message key.
+
+They no longer do: the first element to mount keeps the namespace, and a second is given a
+throwaway one of its own plus a console warning. That keeps the two conversations apart, but the
+throwaway namespace is minted per mount, so the second element will not restore its conversation
+across a reload until it has an `id`.
+
+---
+
+## Host seams: the SPA story
+
+`<ag-ui-chat>` is a generic embedding kit; these typed seams let a host feed the agent richer
+context up front so it explores less. All are framework-free and admin-agnostic.
+
+**`routeMap: RouteMap`** — a manifest of navigable routes (`{ id, path, title?, group?,
+description? }`). When set, the element exposes two built-in tools so the agent navigates by intent
+rather than by exploring:
+
+- `list_routes` — read-only; lists the routes.
+- `navigate_to_route(route_id, params?)` — resolves the id to a path and navigates.
+
+A route `path` may contain `:param` segments — e.g. `/projects/:id/users/:userId/`.
+`navigate_to_route` substitutes the path params (URL-encoded) and sends any leftover params as a
+query string; a missing or empty required path param throws. The resolved shape is the exported
+`RouteWithParams` type.
+
+```js
+chat.routeMap = [
+  { id: "users", path: "/users", title: "Users", description: "Manage user accounts" },
+  { id: "billing", path: "/billing", title: "Billing" },
+  { id: "user-detail", path: "/projects/:id/users/:userId/", title: "User detail" },
+];
+```
+
+**`getPageMap(): PageMap`** — a per-run provider returning the current page's compact actionable
+surface (field names/types/labels, button labels+handles — *not* values). It is auto-injected into
+each run's `context` as a `page_map` entry (toggle with `autoInjectPageMap`):
+
+```js
+chat.getPageMap = () => ({ fields: introspectForm(), buttons: visibleButtons() });
+```
+
+It is recomputed at the top of **every tool round**, not once per `send()` — so after the agent
+acts, the next round already sees the resulting page. Within a round the agent can pull a fresh
+view at any time with the built-in `read_page` tool, which is registered whenever this provider is
+set.
+
+**Check that your server reads `context` at all — pydantic-ai's AG-UI adapter does not.** The
+auto-injected `page_map` rides in `RunAgentInput.context`, and an adapter that ignores that field
+drops it silently: nothing errors, and the model simply never sees the page. On such a backend
+`read_page` is the channel that works, and it is the one to rely on. Nothing to configure — just do
+not assume the injected copy arrived, and if the page map matters to your prompt, put it there
+server-side or let the agent call `read_page`.
+
+That leaves one window: the page can move *after* a round's context was built but *before* the
+agent's tool call arrives — the user clicks a link, or presses back. Calls landing in that window
+are **refused** with a result telling the agent to call `read_page` and retry. Most would have
+missed anyway; the guard exists for the case where a same-named control on the new page matches and
+the agent would otherwise act on the wrong page without either side noticing. `read_page` and tools
+marked `x-navigates` are exempt. The guard runs in any round that offered `read_page`, including
+one you registered yourself, and is inert in a round that did not (no `getPageMap`, or a
+[place the user withheld](#where-the-user-is-the-place-chip)), since its result would name a tool
+the agent does not have.
+
+**`registerPageState({ name, read, write?, schema? })`** — ergonomic sugar over `registerTool` for
+SPA app state (Redux/Zustand/signals). It auto-generates a `read_<name>` (read-only) tool and, when
+`write` is supplied, a `set_<name>` tool stamped `x-destructive`:
+
+```js
+chat.registerPageState({
+  name: "cart",
+  read: () => store.getState().cart,
+  write: ({ items }) => store.dispatch(setCart(items)),
+  schema: { type: "object", properties: { items: { type: "array" } } },
+});
+```
+
+**This is not AG-UI shared state** — that is `sharedState`, below. `registerPageState` generates two
+ordinary client tools; the agent reads or writes your store by *calling a tool*.
+
+**`sharedState`** *(property)* — AG-UI **shared state**: the protocol's own state channel, sent as
+`RunAgentInput.state` on every run and replaced in place when the server streams `STATE_SNAPSHOT` /
+`STATE_DELTA`. Assign to seed it, listen for `ag-ui-state` to react:
+
+```js
+chat.sharedState = { document: "" };
+
+chat.addEventListener("ag-ui-state", (e) => {
+  editor.value = e.detail.state.document;   // the agent rewrote it
+});
+```
+
+Server-side, a tool mutates `ctx.deps.state` and returns the snapshot as `ToolReturn` metadata —
+pydantic-ai does not emit deltas for you:
+
+```python
+@tool(registry)
+async def write_document(ctx: RunContext[AgentDeps], body: str) -> ToolReturn:
+    """Replace the shared document."""
+    ctx.deps.state = {**(ctx.deps.state or {}), "document": body}
+    return ToolReturn(
+        return_value="written",
+        metadata=[StateSnapshotEvent(type=EventType.STATE_SNAPSHOT, snapshot=ctx.deps.state)],
+    )
+```
+
+Use this when the agent and the page are editing **the same object** (a document, a form, a
+canvas). Because it is the page's object rather than the conversation's, **New chat keeps it**; a
+change of [`user-key`](#who-the-stored-conversation-belongs-to-user-key) clears it. Use
+`registerPageState` when the agent should *ask* for a value or *request* a change —
+the tool call is visible in the transcript and can be gated by a confirmation card, which state
+events cannot.
+
+**`navigate(path): void`** *(optional)* — a host routing callback. **This single seam is what
+distinguishes an SPA from an MPA.** When set, `navigate_to_route` routes client-side (no reload) and
+the in-memory run loop simply continues — the whole resumable-loop / checkpoint machinery is
+bypassed. When unset, navigation falls back to `window.location` and the MPA reload model above
+applies.
+
+```js
+chat.navigate = (path) => router.push(path); // SPA: in-page, no reload
+// leave unset for an MPA: window.location + checkpoint/resume
+```
+
+Route map + `navigate()` and the reload model are the same feature seen from two ends.
+
+**`ag-ui-run-finished`** *(event)* — an interaction has ended, and here is what ran in it.
+`detail: { threadId, tools: readonly ToolRun[], invalidated, outcome }` (typed `RunFinishedDetail`),
+where each `ToolRun` is `{ name, side: "server" | "client" }` in settle order. `threadId` is the
+thread the run belonged to, which is not always the one on screen: a run that a new chat or a
+thread switch stopped still reports once its request closes. `outcome` is how the interaction
+ended: `"completed"`, `"stopped"` (Stop, a new chat or a thread switch cut it off) or `"failed"`
+(the agent reported an error). Ignore an `outcome` you do not know: more may be added.
+
+**This is the seam for a host that renders data the agent can change.** A server-side tool writes
+without your page's knowledge: nothing else the element dispatches implies "something may have moved
+underneath you", so a page that fetched its data on mount has no reason to refetch and quietly goes
+stale. Approve a server-side booking on a calendar and the row exists while the calendar keeps
+showing the week it loaded.
+
+```js
+chat.addEventListener("ag-ui-run-finished", (e) => {
+  // A "client" tool ran in your own handler, so you already know what it did.
+  if (e.detail.tools.some((tool) => tool.side === "server")) {
+    void refetchBoard();
+  }
+});
+```
+
+It fires **once per interaction**, not once per tool round, and it fires on completion, error and
+cancellation alike — a partial write is still a write. A capability load (an agent skill activating)
+is not counted: it moves nothing a host renders.
+
+A run a switch stopped reports `outcome: "stopped"` whichever thread is on screen when it does,
+so a listener that marks attention or counts completions tells a cancelled run's late event from a
+finished one by `outcome`, not by `threadId`.
+
+**Deferring a switch until the run is over** keys on `running` and `data-running`, never on this
+event: it fires for a stopped run too, late, and a stale one can arrive while the next run is live.
+`data-running` toggles only for the live run, and there is no running-change event, so watch the
+attribute:
+
+```js
+let queued = null;
+const release = () => {
+  if (!chat.running && queued !== null) {
+    const id = queued;
+    queued = null;
+    void chat.switchThread(id);
+  }
+};
+new MutationObserver(release).observe(chat, { attributes: true, attributeFilter: ["data-running"] });
+myBar.onPick = (id) => {
+  if (chat.running) {
+    queued = id;
+  } else {
+    void chat.switchThread(id);
+  }
+};
+```
+
+`sharedState` above is the richer channel and this is not a replacement for it — but it is not a
+substitute the other way round either, because shared state requires the *agent* to emit
+`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.
+
+### Where the user is: the place chip
+
+The composer can say where in your app the user is writing from: a chip in its tool row, between the
+attach and voice controls and Send, naming the page, tab or record on screen. The same read is sent
+to the agent as one context entry, so the place the user sees is the place the agent is told.
+
+**`getPlace: () => Place | null`** returns a `Place`: `{ label, detail?, icon?, href? }`. The chip
+draws the label, the detail after a dot, and the icon (an image URL; a pin when absent). The agent
+gets a `place` context entry whose value is the JSON of the label, detail and href; the icon is
+never sent. The href identifies the place; without one, the label and detail do.
+
+```js
+chat.getPlace = () => ({
+  label: `Order #${order.number}`,
+  detail: "Orders",
+  href: location.pathname,
+});
+```
+
+- **With no `getPlace`, a route map stands in.** The `routeMap` route whose path matches
+  `location.pathname` names the place: its `title` (else its `id`) as the label, its `group` as the
+  detail, and the path as the href. A host with a route map gets the chip without writing anything.
+  With neither, no chip is drawn and nothing is sent; set `getPlace = () => null` to opt a
+  route-mapped host out.
+- **When it is read.** Before every tool round, so an agent that navigates mid-run is told the new
+  page on its next round; and on connect, on expand, when the composer gains focus, on `popstate`
+  and `hashchange`, and when the conversation on screen changes (`switchThread`, the drawer,
+  `newChat`): the chip always names the live page, never the page a thread started on. Between runs
+  it shows the last read. A single-page app calls **`refreshPlace()`** after its router moves,
+  since `pushState` fires no event.
+- **The entry rides after your `getContext`.** It is appended to whatever `getContext` returns, so a
+  host that replaces `getContext` still sends it.
+- **The eye toggle withholds it.** Pressing it leaves the chip in place, dashed and struck through
+  (`data-excluded` on the `place` part), and the next round sends no `place` entry. It withholds the
+  page too: that round also drops the `page_map` entry, whatever `getContext` returned, and does not
+  offer `read_page`. Tools you register yourself, such as `registerPageState`'s, stay as you
+  registered them. The choice holds while the same place is read, lapses when a different place is
+  read, is not persisted, and cannot be lifted by the host.
+- **Placement.** The same position in every placement, on a phone and in the greeting layout; the
+  label truncates with an ellipsis before it can push Send off the row, and the chip's title
+  carries it in full. Nothing shows while the panel is collapsed. The chip is separate from the
+  `above-composer` slot, and filling the slot never hides it.
+- **Styling and words.** Parts `place`, `place-icon`, `place-label`, `place-detail` and
+  `place-toggle`; the colours come from the existing tokens. The tooltip and the toggle's labels are
+  the `placeShared` and `placeWithheld` (token `{label}`), `placeStopSharing` and `placeShareAgain`
+  strings.
+
+## Resuming a run
+
+When the server persists run checkpoints (django-ag-ui's `step_store`), a run
+that stopped part-way can be **continued** rather than restarted. Point the
+component at the run index and a checkpoints button (an arrow turning back) appears in the header:
+
+```html
+<ag-ui-chat endpoint="/agent/" data-runs-url="/agent/runs/"></ag-ui-chat>
+```
+
+The panel lists runs the server marked **continuable** — those with a saved
+snapshot to seed from. A run that never reached a provider-valid boundary has
+none, so it isn't offered: resuming it would start from nothing.
+
+A row leads with the run's **first user message**, from the index's `preview`
+field, and shows when it started beside it. That is what makes the list a list of
+conversations: a time is not an identity, since two runs a minute apart both read
+"just now", and a run id is not something a person recognises. Where the server
+sends no preview — an older index, or a run that opened on an image with no
+caption — the row falls back to the time plus the first eight characters of the
+id (full id on hover, for correlating with server logs), and so does a row whose
+preview another row repeats: words shared with a second row identify neither, and
+one board tends to be asked about more than once. Either way a run that branched
+from another is marked, so a fork doesn't read as a duplicate of its parent.
+
+Type the next turn in the composer, then pick a row:
+
+- **Resume** — continue that run.
+- **Fork** — branch it, leaving the original untouched.
+
+Both send to the matching server endpoint and stream into the same transcript. The
+turn you typed is drawn there ahead of the answer and announced with `ag-ui-submit`,
+exactly as a send is, so a host that keeps its own record of what the user said sees
+continued turns too.
+
+Picking a row with an empty composer says so above the input and puts the caret
+there, rather than closing the panel over nothing: a continuation sends **only**
+the new turn, so with nothing typed there is nothing to send.
+
+Picking a row while an answer is still streaming — the conversation's own, or
+another continuation's — is refused the same way: the hint asks you to wait or
+stop it, and what you typed stays in the composer for the pick after. The run in
+flight is not cancelled for you, since a continuation starting over it would
+leave two answers streaming into one transcript with Stop reaching only one.
+
+Picking a row while a stored conversation is still loading is refused the same
+way, with a hint asking you to wait for the load: a continuation sends only the
+new turn, so it must not start before the history it continues is on screen. The
+wording is the `continueWhileLoading` string.
+
+### One URL, three endpoints
+
+`data-runs-url` is the only thing to configure. `resume/<id>/` and `fork/<id>/`
+are siblings of the index — django-ag-ui mounts all three under one prefix
+whenever a step store is set — so they're derived, and there's no way to end up
+with a half-configured set.
+
+### The client contract, handled for you
+
+Those endpoints expect a request carrying a **fresh run id** and **only the new
+turn**: the server supplies the prior turns from the snapshot, so re-sending
+them would duplicate the conversation.
+
+The component satisfies that structurally rather than by remembering a rule. A
+continuation runs on its own short-lived agent, built pointing at the resume
+endpoint and seeded with **no** history — so "only the new turn" is the only
+thing it *can* send, and the fresh run id comes free because a new agent mints
+one. Nothing of the conversation's history goes out on its request.
+
+A resumed run is a normal run in every other respect: frontend tools execute,
+approval interrupts render their card, `headers` are re-read per request so
+a rotated CSRF token or JWT still reaches the endpoint, it carries and updates
+[shared state](#host-seams-the-spa-story) like any other run, it is bounded by
+`data-max-tool-rounds`, and Stop ends it. Its client is built by the same
+construction as the conversation's own, differing only in the endpoint and the
+empty seed.
+
+The continued exchange joins the conversation. Its agent holds only the new turn
+and the answer, and a store keeps one message list per thread, so each save
+writes the conversation as it stood when you picked the row with the exchange
+after it — through the same `saveMessages` as any other run, and as far as it
+got if it was stopped. A reload then replays the exchange, and the next message
+you send, now to `endpoint` again, carries it together with the shared state the
+continuation left. What is saved is what the transcript shows: a fork's exchange
+follows the conversation it was picked from, in that same thread.
+
+If the index can't be reached, the panel shows its empty state rather than an
+error — a history affordance that fails is empty, not broken.
+
+## File uploads
+
+Set **`data-attachments-url`** (django-ag-ui's `AttachmentsView`) to let the user attach files
+to a message. A button, drag-and-drop, and **paste** appear on the composer; each picked file uploads
+out-of-band (multipart, with the element's `headers`) and shows a chip in a pending tray —
+`uploading` (with a progress bar) → `ready`, or `error` with a retry. On send, the ready files'
+**refs** ride on the user bubble as read-only chips and the agent reads their contents
+server-side via the `read_attachment` tool. The wire stays vanilla AG-UI: only lightweight refs
+(`{ id, name, mime, size }`) travel, never the bytes, in the user message's `metadata` under
+`attachments` — the one place on a message `@ag-ui/client` 1.0 does not strip an unknown key from.
+django-ag-ui reads them from there as of 0.63.0; an older one reads only the top-level key 1.0
+removes, so against it the agent is never told a file was attached.
+
+### Pasting
+
+A paste carrying files puts them on the tray, the same way the picker and a drop
+do — a screenshot straight from the clipboard, or a file copied in the file
+manager.
+
+Two rules keep it from stealing a paste that was never about files. Text pastes
+carry no files at all, so ordinary pasting is untouched. And the default is
+prevented **only when the clipboard carries no text**: copying a rich selection
+that happens to contain an image puts both on the clipboard, and swallowing the
+words someone meant to paste in order to attach a picture they did not is the
+worse of the two failures.
+
+A pasted blob that arrives with no filename — some engines hand one over that
+way — is given one, rather than reaching the server as an empty `filename` and
+showing in the tray as a chip with no label.
+
+```html
+<ag-ui-chat
+  endpoint="/agent/"
+  data-attachments-url="/agent/attachments/"
+  data-attachment-accept="image/*,application/pdf,text/plain"
+  data-attachment-max-bytes="10485760"
+></ag-ui-chat>
+```
+
+Client-side `accept` / size checks are an instant-feedback nicety — **the server is
+authoritative**. Refs persist on the message, so a restored conversation re-renders its chips.
+Without the attribute the affordance stays hidden and the chat is text-only.
+
+The built-in handler sends the element's `headers` / `getHeaders` with every upload, and honours
+`credentials="include"` — with the caveat that it is an `XMLHttpRequest` (for real progress
+events), whose cookie switch is two-state: `include` turns it on, every other value leaves it off.
+See [Authenticating requests](#authenticating-requests).
+
+**Swapping the upload transport.** The built-in multipart `POST` is just the default
+`uploadHandler`. Set your own to use a different transport — a resumable
+[`tus-js-client`](https://github.com/tus/tus-js-client) adapter, direct-to-S3 multipart, etc.
+— without touching the tray, the chips, or the AG-UI wire (refs are transport-agnostic). The
+handler is `(file, onProgress) => Promise<AttachmentRef>`; when set, the affordance appears
+even with no `data-attachments-url`, and your handler owns its own endpoint and headers:
+
+```js
+import { Upload } from "tus-js-client";
+
+chat.uploadHandler = (file, onProgress) =>
+  new Promise((resolve, reject) => {
+    const up = new Upload(file, {
+      endpoint: "/tus/",
+      headers: chat.headers,
+      onProgress: (sent, total) => onProgress(sent / total),
+      onError: reject,
+      onSuccess: () =>
+        resolve({ id: up.url.split("/").pop(), name: file.name, mime: file.type, size: file.size }),
+    });
+    up.start();
+  });
+```
+
+The server side is the matching half: the agent reads bytes by ref id, so point the
+`read_attachment` store at wherever your transport persisted them (django-ag-ui's
+`AttachmentStore` is the seam). The refs themselves never change shape.
+
+---
+
+## Public API surface
+
+Everything below is re-exported from the package root ([`src/index.ts`](src/index.ts)), except
+`AgUiChat` and `defineChat`, which are the `./chat` entry. The
+vendored bundle ([`src/bundle.ts`](src/bundle.ts)) carries both. Internal modules import from leaf
+paths.
+
+### Element & registration
+
+| Export | Kind | Summary |
+| --- | --- | --- |
+| `AgUiChat` | class | The `<ag-ui-chat>` Custom Element (`./chat`). |
+| `defineChat()` | function | Register the element (`./chat`); a no-op if it is already registered, and throws if another class holds the tag. |
+| `MessageRole` | type | Role of a rendered chat message. |
+| `SubmitDetail` | type | `detail` shape of the submit event. |
+| `ThreadDetail` | type | `detail` shape of the `ag-ui-thread` event (`{ threadId, previousThreadId, reason }`). |
+| `ToggleDetail` | type | `detail` shape of the `ag-ui-toggle` event (`{ collapsed }`). |
+| `MaximizeDetail` | type | `detail` shape of the `ag-ui-maximize` event (`{ maximized }`). |
+| `BarHeightDetail` | type | `detail` shape of the `ag-ui-bar-height` event (`{ height }`). |
+| `DockWidthDetail` | type | `detail` shape of the `ag-ui-dock-width` event (`{ width, side }`). |
+| `ThreadTitleDetail` | type | `detail` shape of the `ag-ui-thread-title` event (`{ threadId, title }`). |
+| `UnreadDetail` | type | `detail` shape of the `ag-ui-unread` event (`{ unread, threadIds }`). |
+| `AttachmentsDetail` | type | `detail` shape of the `ag-ui-attachments` event (`{ attachments, pending }`). |
+| `StateDetail` | type | `detail` shape of the `ag-ui-state` event (`{ state }`). |
+
+### AG-UI client & agent
+
+| Export | Kind | Summary |
+| --- | --- | --- |
+| `AgUiClient` | class | Orchestration layer over an AG-UI `AbstractAgent`. |
+| `AgUiClientConfig` / `AgUiClientHandlers` / `AgUiRunInputs` | type | Client config, lifecycle handlers, per-run input providers. |
+| `AgUiToolCall` / `ToolExecution` / `ExecuteTool` | type | Tool-call shape, execution result, executor signature. |
+| `AgUiMessageIds` | type | Which message `AgUiClientHandlers.onTextEnd` completed: its `messageId`, and the `runId` its `RUN_STARTED` named. |
+| `ToolOutcome` | type | The `TOOL_OUTCOME` values as a union. |
+| `toolStatusFromOutcome` | function | Map a wire outcome to the card status it settles into; anything absent or unrecognised is a success. |
+| `ConnectionLostError` | class | Raised (→ `onError`) when a run's stream closes with no terminal AG-UI event. |
+| `createHttpAgent(options)` | function | Default agent factory (wraps `HttpAgent`). |
+| `AgentFactory` / `HttpAgentOptions` | type | Factory signature and its options. |
+| `ResolveInterrupts` | type | Resolver for server-side-tool approval interrupts (one decision per interrupt). |
+| `InterruptResponse` | type | One interrupt's answer: `resolved` (with an optional payload) or `cancelled`. |
+
+### Tools & flags
+
+| Export | Kind | Summary |
+| --- | --- | --- |
+| `ClientToolRegistry` | class | Per-element tool registry. |
+| `ClientTool` | type | A frontend tool declaration. |
+| `isDestructive(parameters)` | function | Read the `x-destructive` flag. |
+| `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`). |
+| `createChatSurfaceTools(surface)` | function | Build the opt-in `read_chat_surface` / `move_chat` / `minimise_chat` / `restore_chat` tools, which let the agent move the panel it is speaking from. |
+| `ChatSurface` | type | The narrow port those tools drive — `describeSurface` / `moveTo` / `setCollapsed`. The element satisfies it. |
+| `ChatSurfaceReport` | type | What `describeSurface()` answers: placement, collapsed, collapseTo, collapsible, movable, draggable, fullBleed, and the panel's box against the viewport it sits in. |
+| `ChatCorner` | type | `"top-left"` / `"top-right"` / `"bottom-left"` / `"bottom-right"` — the argument to `moveTo`. |
+| `CHAT_CORNERS` | const | Those four, as a list. |
+| `isChatCorner(value)` | function | Whether a string names one of them. |
+| `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 `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*). |
+
+### Host seams
+
+| Export | Kind | Summary |
+| --- | --- | --- |
+| `createRouteTools(...)` | function | Build the built-in `route.*` tools. |
+| `Route` / `RouteMap` | type | Navigable-route shapes. |
+| `RouteWithParams` | type | A route resolved with `:param` path segments + leftover query params. |
+| `createPageMapContext(...)` | function | Build the per-run `page_map` context entry. |
+| `PageMap` | type | The compact page-surface shape. |
+| `Place` | type | Where the user is: what `getPlace` returns and the chip draws. |
+| `createPageStateTools(binding)` | function | Build `read_<name>` / `set_<name>` tools. |
+| `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, which side ran them, and how it ended. |
+| `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 `messageId`, its `threadId`, the `runId` that streamed it (live only), its `content` and the `rating`. See [Storing a rating](#storing-a-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 `html` source for the rich clipboard flavour, 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`. |
+
+### Durability
+
+| Export | Kind | Summary |
+| --- | --- | --- |
+| `SessionStorageStore` | class | Default per-tab conversation store. |
+| `RemoteConversationStore` | class | Server-backed store over a `data-threads-url` endpoint. |
+| `ClientConversationStore` | type | The persistence seam. |
+| `ThreadMeta` | type | A thread-drawer row (`{ threadId, title, updatedAt, preview, unread? }`). |
+| `NavigationCheckpoint` | type | The pre-reload checkpoint marker. |
+| `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"`. |
+
+### Attachments
+
+| Export | Kind | Summary |
+| --- | --- | --- |
+| `uploadAttachment(file, options)` | function | The built-in upload (multipart, progress) → `AttachmentRef`. |
+| `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: from its `metadata`, or from the top level where an earlier release stored them. |
+
+### Voice input
+
+| Export | Kind | Summary |
+| --- | --- | --- |
+| `transcribeAudio(audio, options)` | function | The built-in transcription POST (multipart) → the transcript text. |
+| `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
+
+| Export | Kind | Summary |
+| --- | --- | --- |
+| `ToolCallCard` | class | A live tool-call card for the transcript. |
+| `ToolCallStatus` / `SettledStatus` / `ToolDisplayMode` | type | Card lifecycle states + display mode. |
+| `ToolGroupDisplayMode` | type | How an opened step group draws its calls (`TOOL_GROUP_DISPLAY`'s values). |
+| `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?, 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?, 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.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. |
+| `showHighlightOverlay` | function | Ring a host-page element from an overlay drawn outside it, optionally dimming everything else or flowing a gradient round it. Returns a function that removes it. |
+| `HighlightOverlayOptions` | type | Options for `showHighlightOverlay`. |
+| `fillField` / `clickElement` / `pressButton` / `selectControl` / `setControlValue` / `toggleCheckbox` | function | DOM-driver primitives. |
+| `setNativeValue` / `setNativeChecked` | function | Set a control via its native prototype setter (React-controlled inputs). |
+| `TypeOptions` / `HighlightClickOptions` / `PressOptions` / `SelectOptions` / `ToggleOptions` / `FlashOptions` / `ScrollOptions` / `FillFieldOptions` / `TextLikeElement` / `RingOwnerOptions` | type | Primitive option shapes. `RingOwnerOptions` is the `chat` the ring-drawing ones share; see [Ring colour](#ring-colour). |
+
+### Constants
+
+| Export | Summary |
+| --- | --- |
+| `ELEMENT_TAG` | The registered tag name (`ag-ui-chat`). |
+| `SUBMIT_EVENT` | The submit CustomEvent name. |
+| `THREAD_EVENT` | The conversation-changed CustomEvent name (`ag-ui-thread`). |
+| `THREAD_TITLE_EVENT` | The thread-title CustomEvent name (`ag-ui-thread-title`). |
+| `TOGGLE_EVENT` | The collapse-toggle CustomEvent name (`ag-ui-toggle`). |
+| `MAXIMIZE_EVENT` | The maximized-state CustomEvent name (`ag-ui-maximize`). |
+| `BAR_HEIGHT_EVENT` | The bottom bar's height CustomEvent name (`ag-ui-bar-height`). |
+| `DOCK_WIDTH_EVENT` | The docked panel's width CustomEvent name (`ag-ui-dock-width`). |
+| `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. |
+| `CHART_TOOL_NAME` | The name the built-in chart tool registers under (`render_chart`). |
+| `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 (`inline` / `minimal` / `compact` / `full`). |
+| `TOOL_GROUP_DISPLAY` | How an opened step group draws its calls under `grouped` (`inline` / `minimal` / `compact` / `full`). |
+| `TOOL_OUTCOME` | How a tool call ended, as a server states it on `TOOL_CALL_RESULT` (`success` / `failed` / `denied`). |
+| `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. |
+| `VERSION` | The package version string. |
+
+---
+
+## Theming, density, and placement
+
+The chat shell is styled inside its Shadow DOM and exposes a large set of `--ag-ui-*` CSS custom
+properties (colors, status, surface, spacing, layout), so you theme it from outside without
+piercing the shadow boundary. Set them anywhere above the element and they inherit in — on the
+element itself, on a wrapper, or on `:root` for a whole page. The closest declaration wins, the
+way any inherited CSS property behaves:
+
+```css
+/* All three work. The most specific one that applies wins. */
+:root      { --ag-ui-accent: #4f46e5; }  /* whole page */
+.chat-dock { --ag-ui-accent: #0f766e; }  /* one region */
+ag-ui-chat { --ag-ui-accent: #b91c1c; }  /* one widget */
+```
+
+> Until 0.20.x the defaults were declared on `:host`, which set them *on the element* — and an
+> element's own value beats anything inherited from an ancestor, so only the `ag-ui-chat { … }`
+> form did anything and the wrapper form silently did nothing. The defaults now sit behind an
+> internal alias, so all three forms work.
+
+A few of the knobs, at Quiet's light values:
+
+```css
+ag-ui-chat {
+  --ag-ui-accent: #232326;        /* #f0f0f2 in the dark scheme */
+  --ag-ui-bg: #ffffff;            /* #161618 */
+  --ag-ui-fg: #1b1b1d;            /* #ececee */
+  --ag-ui-radius: 12px;
+  --ag-ui-header-btn-size: 30px;  /* the header's controls; 44px on touch */
+  --ag-ui-header-gap: 4px;
+
+  /* What is drawn on top of the accent and danger fills. Unset, the one on
+     the accent is white or black by the accent's luminance (see Text on the
+     accent below); set it to pin a colour of your own. */
+  --ag-ui-on-accent: #ffffff;
+  --ag-ui-on-danger: #ffffff;
+
+  /* Layout */
+  --ag-ui-width: 380px;
+  --ag-ui-height: 560px;
+  --ag-ui-inset: auto 24px 24px auto;
+  --ag-ui-shadow: 0 1px 2px rgb(0 0 0 / 0.05), 0 12px 32px -16px rgb(0 0 0 / 0.22);
+}
+```
+
+`--ag-ui-radius` is the theme's corner radius. It rounds the panel's frame and the corners inside
+the panel that have no radius of their own: the answer well, the conversation list's *New chat*
+button and filter field, and the *Undo* on a run notice. The frame is the exception where it meets
+the edge of the window. `page` and `sidebar` draw it square, and so does every placement but
+`embedded` on a small viewport, while the corners inside keep the theme's radius, since none of them
+meets that edge. `--ag-ui-panel-radius` sets the frame on its own, in any placement. Each theme
+gives the floating frame a radius of its own (`--ag-ui-frame-radius`: 14px in Quiet against 12px
+inside), and a host's `--ag-ui-radius` still sets both.
+
+### Themes
+
+`theme` is up to two words, in any order, matched as words (`~=`):
+
+```
+theme = [name] [scheme]
+name   = quiet | soft | ledger | classic | <a word of your own>
+scheme = light | dark | auto            default: light
+```
+
+| Value | Result |
+| --- | --- |
+| *(absent)* | Quiet, light |
+| `dark` | Quiet, dark |
+| `auto` | Quiet, following the system's `prefers-color-scheme` |
+| `soft`, `soft dark`, `ledger auto` | that theme in that scheme |
+| `classic`, `classic dark` | the look from before themes, for a host that pins it |
+| `acme` | a word the component does not ship adds no rules, so this is Quiet, ready for your `[theme~="acme"]` CSS |
+| `soft acme` | starts from Soft; your `[theme~="acme"]` rules layer on top |
+
+The built-in themes:
+
+| Theme | Look |
+| --- | --- |
+| `quiet` | The default. Neutral graphite on white, no bubble for the agent's turn, hairlines, status as an icon. Set one brand accent and the user's turn, the send button and the links follow it. |
+| `soft` | Rounded and tinted: surfaces mixed from the accent, pill chips, a deep frame shadow. Violet by default. |
+| `ledger` | Dense and editorial: paper and ink, square corners, serif for what the agent says and monospace for the chrome. |
+| `classic` | The look before themes: the indigo header, the accent user bubble, the status pill and the round launcher. Pin it to keep that look. |
+
+**The default scheme is `light`, not `auto`**, because the widget sits on your page and only you
+know that page's scheme. A light admin screen on a machine in dark mode would otherwise get a dark
+panel on a white page. If your page follows the system, say `auto`.
+
+Each theme is three seeds, `--ag-ui-bg`, `--ag-ui-fg` and `--ag-ui-accent`, each declared with
+`light-dark()` so the scheme word picks the half. Every other colour is mixed from them with
+`color-mix(in oklch, ...)` -- hover, borders, the secondary text inks, washes, the user's turn (the
+accent at 12% over the background) -- and every derived value still reads its own public token
+first, so each stays an override point. The tokens the themes add:
+
+- **Inks and lines:** `--ag-ui-ink-2`, `--ag-ui-ink-3`, `--ag-ui-line`, `--ag-ui-line-strong`.
+- **Surfaces:** `--ag-ui-wash`, `--ag-ui-accent-ink`, `--ag-ui-tint`, `--ag-ui-tint-2`.
+- **Type:** `--ag-ui-text-xs`, `--ag-ui-text-sm`, `--ag-ui-text-md`, `--ag-ui-text-lg`,
+  `--ag-ui-leading`, `--ag-ui-serif`.
+- **Frame:** `--ag-ui-frame-radius`, `--ag-ui-frame-shadow`. These are what a theme sets for the
+  frame; `--ag-ui-panel-radius` and `--ag-ui-shadow` stay the final say, and are what a docked
+  placement squares or flattens.
+- **Charts:** `--ag-ui-chart-1` to `--ag-ui-chart-6`. A host's value beats the theme's.
+- **Status marks:** `--ag-ui-ico-check`, `--ag-ui-ico-error`, `--ag-ui-ico-declined`, mask images
+  drawn in the state's colour, and `--ag-ui-ico-chevron`, the step group's disclosure chevron.
+- **Focus:** `--ag-ui-ring`, the step group head's focus outline. Unset, it is two parts accent
+  to three parts ink (`--ag-ui-fg`), which holds 3:1 against the panel for any accent.
+
+The font is part of the theme: Quiet, Soft and Ledger set their own stack (Inter, then the system
+UI font), and Classic inherits the page's font as the component always did. To take the page's font
+under any theme, set `--ag-ui-font` to the page's family, or to the page's own font token:
+
+```css
+ag-ui-chat { --ag-ui-font: var(--body-font); }   /* or the family itself */
+```
+
+`--ag-ui-font: inherit` does not do this. A CSS-wide keyword in a custom property applies to the
+custom property itself, so it takes the `--ag-ui-font` of the parent, which nothing sets, and the
+theme's stack wins.
+
+#### Text on the accent
+
+`--ag-ui-on-accent`, unless you set it, is picked from the accent's own luminance: white on an
+accent darker than WCAG relative luminance 0.179, black on a lighter one, which is the better of
+the two on every colour (never under 4.58:1). It is computed with relative colour syntax with
+channel arithmetic, behind `@supports` for that exact expression: Chrome 119, Firefox 128, Safari
+18.
+
+**The fallback.** Two browsers at or above the floor cannot compute it: Firefox 120 to 127, which
+lack relative colour syntax, and Safari 17.5 and 17.6, which shipped an earlier draft that rejects
+this expression. They keep a fixed colour per theme instead:
+
+| Theme | Without relative colour syntax |
+| --- | --- |
+| `quiet`, `soft`, `ledger` | the scheme's: white in the light scheme, near-black (`#111111`) in the dark one |
+| `classic`, `code` | white in both schemes, the colour they always drew |
+
+On every built-in accent but code's the fixed colour is on the same side as the computed one, so
+those browsers see the same contrast. On code's green the computed pick is black (8.3:1) and the
+fallback white (2.5:1), as it always was. What they miss is the correction for a host's accent: a
+mid-tone brand accent can fall under 4.5:1 there, under any theme. If you support those browsers
+and set a mid-tone accent, set `--ag-ui-on-accent` yourself. There is no script path.
+
+#### Keeping a brand accent on the header
+
+Quiet draws the header, the launcher and the tool names in the panel's own colours, so a host that
+sets only `--ag-ui-accent` gets a neutral header. To put the accent back without leaving Quiet, set
+the surfaces to the accent and the text on them to a colour that reads on it. The same recipe holds
+under every other theme:
+
+```css
+ag-ui-chat {
+  --ag-ui-header-bg: #3d5afe;
+  --ag-ui-header-fg: #ffffff;
+  --ag-ui-launcher-bg: #3d5afe;
+  --ag-ui-launcher-fg: #ffffff;
+  --ag-ui-tool-fg: #3d5afe;
+}
+```
+
+- **The header buttons follow `--ag-ui-header-fg`, under every theme.** Unset, each theme draws
+  them its own way at 0.85 opacity: Quiet, Soft and Ledger in their third ink, Classic and Code in
+  the header text, each on its own hover square. Once you set the header text they draw in it at
+  full opacity, and the hover square is the opposite of that text at about a fifth (a darker square
+  under white text, a lighter one under dark text), so a hovered button reads at least what your
+  header pair reads. A theme word of your own starts from Quiet, so it holds there too. No
+  `::part(header-button)` rule is needed. The opposite is computed with relative
+  colour syntax; the browsers without it (see the fallback above) mix the square from the text
+  itself, which on a mid-tone header can take the hovered glyph under your pair (white on
+  `#3d5afe`: 3.75:1).
+- **`--ag-ui-header-btn-hover` sets the hover square outright** under every theme, whether or not
+  the header text is set, and is drawn exactly as given. For a square that lightens under white
+  text instead, at the cost of contrast on a mid-tone header:
+
+  ```css
+  ag-ui-chat { --ag-ui-header-btn-hover: color-mix(in srgb, #ffffff 18%, transparent); }
+  ```
+- **`--ag-ui-tool-fg` colours every tool call**, in a step group as well as in the card displays.
+  Unset, a grouped call is drawn in the second ink (`--ag-ui-ink-2`) under every theme.
+- Pick the pair yourself: `--ag-ui-header-fg` is not derived from the header colour the way
+  `--ag-ui-on-accent` is from the accent.
+
+#### Overriding a theme, lightest layer first
+
+Four layers, each documented and each lighter than the next. Reach for the first one that does
+the job.
+
+##### (a) Tokens
+
+Any `--ag-ui-*` token, on the element or any ancestor, as above. Per theme, from your own CSS:
+
+```css
+body { --ag-ui-accent: #0f766e; }          /* accent only: the rest follows */
+ag-ui-chat[theme~="soft"] { --ag-ui-accent: #c2410c; --ag-ui-frame-radius: 12px; }
+```
+
+A page rule always beats the theme's own value, because the theme only ever sets the private
+alias behind the public token.
+
+##### (b) Parts
+
+`::part()` reaches the structural elements, as listed in [Parts and slots](#parts-and-slots):
+
+```css
+ag-ui-chat::part(header) { background: linear-gradient(#f2f7f6, transparent); }
+```
+
+##### (c) A theme of your own
+
+Name it, and style the name. An unknown word adds no built-in rules, so it starts from Quiet (or
+from the built-in theme beside it):
+
+```html
+<ag-ui-chat theme="acme dark"></ag-ui-chat>
+```
+
+```css
+ag-ui-chat[theme~="acme"] {
+  --ag-ui-bg: light-dark(#fbfaf7, #10161c);
+  --ag-ui-fg: light-dark(#14212b, #e4ebf0);
+  --ag-ui-accent: light-dark(#0b5cad, #6cb2ff);
+  --ag-ui-frame-radius: 4px;
+}
+```
+
+Use `light-dark()` in the seeds and the scheme word, and the theme toggle, work for your theme
+too.
+
+##### (d) `extraStyles`: the last mile
+
+> **Unstable.** `extraStyles` reaches the class names inside the shadow root, and those are not a
+> public API: they may change in any minor release. Layers (a) to (c) are the supported ones; use
+> this for what they cannot reach, and expect to revisit it on upgrade.
+
+```ts
+const sheet = new CSSStyleSheet();
+sheet.replaceSync(`.message--assistant { padding: 10px 12px; border-radius: 10px; }`);
+chat.extraStyles = [sheet];
+```
+
+- `extraStyles: readonly CSSStyleSheet[]`, per element, default `[]`. Two elements can carry
+  different sheets.
+- Adopted after the built-in sheet, so a rule of equal specificity wins.
+- Setting it re-adopts at once. The array is copied, so changing the one you passed does nothing
+  until you set it again; changing a sheet's rules does apply, since the sheet itself is shared.
+- Constructed sheets are not subject to `style-src`, so this works under the same strict CSP as
+  the built-in sheet. There is no string form and no `<style>` injection.
+
+### Small viewports
+
+At **600px wide and below** every placement but `embedded` becomes one full-bleed
+shape: edge to edge, no radius, no shadow, no resize grips. A phone is not an
+eighth placement — it is an override that collapses the others onto one of them.
+The host picked a placement for the desktop it was designing, and a 380x560
+panel with a 24px margin is not a smaller version of that decision, it is most
+of the screen with a frame drawn round it.
+
+`embedded` is left alone deliberately: it sits in a box you sized and placed, and
+only you know whether that column should become the whole screen.
+
+The [greeting layout](#the-greeting-on-an-empty-page) changes shape here too, and
+it is the one part of this that `embedded` gets as well, because it moves nothing
+about the box you placed: an empty conversation keeps its composer at the foot of
+the panel, with the starters against it and the greeting over the space above
+them, instead of centring all three together.
+
+The corner placements still rest at their launcher, so a full-bleed panel is
+something the user opens rather than something they are given.
+
+**To keep your desktop layout at every width**, set `data-small-viewport="off"`.
+That exists because the *trigger* is the one part of this you cannot reach: every
+value the override sets is a `--ag-ui-*` token you can re-state, but a media
+query cannot read a custom property, so the breakpoint itself is a literal.
+
+**A size or inset token set at every width restates the phone shape too.** The phone
+block reads `--ag-ui-inset`, `--ag-ui-width`, `--ag-ui-height` and `--ag-ui-max-height`
+before it falls back to the full-bleed values, so a host rule such as the one below keeps
+its 420x640 panel with a 24px margin on a phone, and the panel runs off the screen's left
+edge. Put the desktop sizes above the breakpoint and the phone shape needs nothing:
+
+```css
+/* Wrong on a phone: the tokens apply at every width. */
+ag-ui-chat {
+  --ag-ui-inset: auto 24px 24px auto;
+  --ag-ui-width: 420px;
+  --ag-ui-height: 640px;
+  --ag-ui-max-height: 80vh;
+}
+
+/* Right: desktop only. At 600px and below the panel is full-bleed with no reset. */
+@media (min-width: 601px) {
+  ag-ui-chat {
+    --ag-ui-inset: auto 24px 24px auto;
+    --ag-ui-width: 420px;
+    --ag-ui-height: 640px;
+    --ag-ui-max-height: 80vh;
+  }
+}
+```
+
+Setting the tokens at every width stays right for a host that wants a non-full-bleed phone
+panel, a bottom sheet for example. The size a user dragged is a separate matter; see
+[Sizes, keyboard, and parts](#sizes-keyboard-and-parts) for its precedence.
+
+The breakpoint is a width rather than a pointer test, and that is on purpose: a
+touch laptop is coarse-pointered and wide, a narrow desktop window is
+fine-pointered and small. Width decides the layout; the pointer decides which
+controls make sense.
+
+### The conversation list
+
+The chat-history list slides over the transcript at every width and under every
+placement, a full page included. Opening it moves nothing underneath: the
+conversation, the centred greeting and the composer are exactly where they were.
+While it is open it is a modal dialog: focus moves into it, Tab stays inside it,
+and Escape, its close control or a click on the backdrop beside it closes it and
+returns focus to where it was. `openThreads()` and `closeThreads()` do the same
+from your own chrome.
+
+The list also grows a filter once there are eight or more conversations in it
+— above that a search box is worth having, below it it is a control asking to be
+used on a list you can already read in one glance. It matches the title **and**
+the preview, because the title is often the model's one-line summary and the
+phrase you remember is as likely to be inside the conversation as on it, and it
+filters what the drawer already holds rather than going back to the server for a
+list that is already in memory. `data-threads-search="always"` shows it over any
+list and `"never"` hides it, for a host whose lists are always short or always long.
+
+The rows are grouped by when they were last active: **Today**, **Previous 7 days**
+and **Older**, counted from local midnight. A group with no rows is not drawn,
+and a list that falls in one group draws no heading at all. A conversation with no
+readable date goes under Older. A filtered list keeps its groups. The headings
+are not in the Tab order, are styled as `::part(drawer-group-label)`, and take
+their text from the `threadsToday`, `threadsPreviousWeek` and `threadsOlder`
+strings. Every drawer has them: the slide-over, the bar's popover and the popover
+beside your own button.
+
+### Reserving the space your own chrome occupies
+
+A fixed placement covers the viewport it is given, and it does not know about
+your sticky header. Tell it which edges are already spent and every placement
+does its own arithmetic:
+
+```css
+ag-ui-chat {
+  --ag-ui-viewport-inset-top: 64px;    /* your nav bar */
+}
+```
+
+`page` and `full` inset by all four edges; `sidebar` and `side` by three, leaving
+the docked edge free; `floating` adds them to its own margins.
+**The heights follow on their own** — that is the point of these rather than
+restating `--ag-ui-inset` per placement, which leaves you to keep
+`--ag-ui-height` and `--ag-ui-max-height` in step by hand and overflows the panel
+off the bottom of the screen the one time you forget.
+
+Four longhands rather than one shorthand because a custom property is a token
+stream and CSS cannot index one; the height arithmetic needs the vertical pair on
+its own. Any CSS length works — `px`, `rem`, `env(safe-area-inset-*)`, or a
+`calc()` combining them; the widget reads the resolved value rather than the text
+you wrote, so the number it clamps against is the one the stylesheet uses:
+
+```css
+ag-ui-chat {
+  --ag-ui-viewport-inset-top: env(safe-area-inset-top);
+  --ag-ui-viewport-inset-bottom: env(safe-area-inset-bottom);
+}
+```
+
+If your chrome changes height — a bar that wraps at narrow widths — measure it
+and publish the value, since no CSS length tracks it:
+
+```js
+new ResizeObserver(() => {
+  document.documentElement.style.setProperty("--bar-h", `${bar.offsetHeight}px`);
+}).observe(bar);
+```
+
+```css
+ag-ui-chat { --ag-ui-viewport-inset-top: var(--bar-h, 0px); }
+```
+
+`--ag-ui-edge-gutter` (default `24px`) is the gap a resting `floating` panel
+keeps between itself and that box. The size cap subtracts the same one, so a
+panel grown to its limit reaches the far edge of the usable box and no further —
+set it to `0` for a panel flush against the corner.
+
+`--ag-ui-anchor-gap` (default `8px`) is the gap between the panel and the button
+it rises from under `collapse-to="none"`; see [Collapsing to a bottom
+bar](#collapsing-to-a-bottom-bar).
+
+`--ag-ui-keyboard-inset` overrides the lift an on-screen keyboard earns. The
+widget measures the hidden band and publishes it as
+`--ag-ui-visual-viewport-inset-bottom`; state this one instead to outrank that
+measurement, or set it to `0px` to opt out of the lift entirely.
+
+`--ag-ui-keyboard-inset-top` does the same at the top. To show a field a
+keyboard would cover, a mobile browser pans the visible area down the page, and
+a panel anchored to the screen (`page`, `full`, `side`, `sidebar`, and at phone
+width the corner placements too) moves down with it. An `embedded` panel renders
+in your own box rather than against the screen, so it does not move at any width.
+The widget publishes the pan as `--ag-ui-visual-viewport-inset-top`, and the
+panel moves by as much of it as goes past your `--ag-ui-viewport-inset-top`,
+since the pan scrolls a reserved bar away with the page. State
+`--ag-ui-keyboard-inset-top` to outrank that distance, or `0px` to keep the
+panel below your reserved top.
+
+`--ag-ui-viewport-height` and `--ag-ui-viewport-width` state the usable box
+outright, for the case where no viewport-percentage length describes it. An
+on-screen keyboard is the one that matters: it changes neither `vh` nor `dvh` nor
+`svh` on any current mobile browser, so a full-bleed panel has to be told the
+visual viewport's height rather than deriving it. The widget does that itself;
+where it has nothing to report, the panel falls back to `100dvh` rather than
+`100vh`, because iOS Safari resolves `vh` to the screen with its bars collapsed
+and a panel sized from it runs under them.
+
+Marks are variables too, so one vocabulary covers a re-theme rather than
+leaving half the transcript in the built-in set: `--ag-ui-tool-icon-done` /
+`-error` / `-declined` for tool status, and `--ag-ui-disclosure-collapsed` /
+`--ag-ui-disclosure-expanded` for every expandable row.
+
+```css
+ag-ui-chat {
+  --ag-ui-disclosure-collapsed: "+";
+  --ag-ui-disclosure-expanded: "-";
+}
+```
+
+### Where to put the variables
+
+There is one vocabulary — the `--ag-ui-*` names above — and it works from any ancestor. What
+differs is only *which* declaration wins, and that is ordinary CSS inheritance:
+
+```css
+/* A whole page or design-system scope. */
+:root { --ag-ui-accent: var(--brand-600); --ag-ui-radius: 4px; }
+
+/* One region — the widget picks this up through the wrapper. */
+aside.support-dock { --ag-ui-accent: #0f766e; }
+
+/* One widget. Beats both of the above, because it targets the element. */
+ag-ui-chat#support { --ag-ui-accent: #b91c1c; }
+
+/* Set at runtime with el.style.setProperty(...) — an inline style beats all of the above. */
+```
+
+Two that do not work:
+
+```css
+/* ::part() reaches structural elements, not variables — a custom property set
+   here applies to that part's own subtree, not to the whole shell. */
+ag-ui-chat::part(panel) { --ag-ui-accent: #b91c1c; }
+
+/* The internal --_* aliases are private and unversioned; they are renamed
+   without notice. Always set the public --ag-ui-* name. */
+ag-ui-chat { --_accent: #b91c1c; }
+```
+
+The preset attributes below sit *underneath* anything you declare: a `theme="dark"` widget still
+honours an explicit `--ag-ui-bg` from your CSS, so you can adopt a preset and correct one token
+rather than re-declaring the whole palette.
+
+`--ag-ui-accent` reaches further than the widget: it also colours the rings the DOM driver draws
+on **your** page. Each primitive reads it from the computed style of the element it is about to
+touch, so setting it on `:root` (or on any ancestor of the elements the agent drives) themes the
+highlights too. Without it they fall back to the package indigo.
+
+For the common cases there are three CSS-reactive **preset attributes** (no JS API), so you don't
+have to hand-tune the variables:
+
+- `theme` — a theme name and a scheme; see [Themes](#themes).
+- `density` — `comfortable` (default) / `compact`.
+- `placement` — `floating` (default) / `sidebar` / `page` / `embedded`. `embedded` drops the
+  fixed positioning and z-index so the widget sits in normal document flow; `page` is a
+  full-screen [centred reading column](#page-placement) for a route of its own.
+
+  Four, because those are the four shapes that differ structurally: a corner panel, a docked
+  rail, a surface that owns the screen, and a thing in your layout. Three older values --
+  `bottom-left`, `side` and `full` -- still parse and still work, and are no longer documented:
+  each is a variant of one of the four rather than a shape of its own. `full` is `page` with
+  `--ag-ui-content-max-width: none`, `bottom-left` is `floating` with a different
+  `--ag-ui-inset`, and `side` is `sidebar` that collapses to the floating launcher instead of
+  an edge rail. Nothing warns and nothing breaks; there is simply less to choose between.
+
+**`embedded` fills the box your page gives it, so give it one.** It is the placement app-shell
+layouts reach for, and a grid or flex item defaults to `min-height: auto` — which lets a growing
+transcript push the composer off the bottom of the window instead of scrolling inside the panel. The
+fix belongs to the containing element, not to the widget:
+
+```css
+.assistant-pane { min-height: 0; overflow: hidden; }   /* the box the element is given */
+```
+
+```html
+<ag-ui-chat endpoint="/agent/" theme="dark" density="compact" placement="sidebar"></ag-ui-chat>
+```
+
+See [`src/ui/shell/token_styles.ts`](src/ui/shell/token_styles.ts) for the full variable list and
+[`src/ui/placement/`](src/ui/placement/) for the placement presets. The
+[`demo/`](demo/) live playground (`node demo/mock-server.mjs`) flips theme, density, placement,
+text-animation, tool-display, and the answer well live from a single page, and demos the
+streamed thoughts region, the mic, and the header theme toggle.
+
+It binds every interface and prints the addresses this machine can be reached on, so you can open the playground on a phone — which is the only way to see the small-viewport layout with a real on-screen keyboard rather than a resized desktop window. `HOST=127.0.0.1` keeps it to this machine.
+
+### Parts and slots
+
+For styling beyond the `--ag-ui-*` variables, every structural element exposes a `part` so you can
+reach it from outside the Shadow DOM with `::part()` — no shadow piercing. The part names are
+**public API** (additions are non-breaking; renames are breaking):
+
+```css
+ag-ui-chat::part(panel)   { border-radius: 0; }
+ag-ui-chat::part(header)  { background: #111; }
+ag-ui-chat::part(send)    { text-transform: uppercase; }
+ag-ui-chat::part(tool-card) { font-family: var(--my-mono); }
+```
+
+Every part, by the feature it belongs to. Spelled out rather than abbreviated: the list used to
+read `tool-card` *plus* `-icon` / `-name`, which is compact and is also how an entire feature went
+missing from it for two releases. A test reads this table and compares it with the parts the
+component sets, so a new one cannot ship undocumented.
+
+| Feature | Parts |
+| --- | --- |
+| Shell | `panel`, `header`, `title`, `icon`, `header-controls`, `messages`, `empty`, `greeting`, `pending`, `stopped`, `jump-latest`, and one per resize grip: `resize-handle` plus `resize-handle-top`, `resize-handle-bottom`, `resize-handle-left`, `resize-handle-right`, `resize-handle-top-left`, `resize-handle-top-right`, `resize-handle-bottom-left`, `resize-handle-bottom-right` |
+| Header buttons | `header-button` on each, plus `history-button`, `checkpoints-button`, `new-button`, `maximize-button`, `collapse-button`, `theme-toggle` |
+| Collapsed widget | `launcher`, `launcher-icon`, `launcher-badge`, `rail-label`, `bar` (the [bottom bar](#collapsing-to-a-bottom-bar)'s wrapper, around the launcher), `bar-place` (the place beside the bar's title; its text carries `place-label` and `place-detail`), `bar-history` |
+| Answers | `answer` (the per-turn group), `message` (plus `message-user`, `message-assistant`), `code-copy` |
+| Reasoning | `thoughts`, `thoughts-toggle`, `thoughts-body`, `thoughts-label` |
+| 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`), and the icon holder inside each: `message-action-icon` (plus `message-action-icon-retry`, `message-action-icon-copy`, `message-action-icon-up`, `message-action-icon-down`) |
+| Queued messages | `queued`, `queued-chip` |
+| 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-surface`, `run-notice-not-connected`), `run-notice-icon`, `run-notice-text`, `run-notice-undo` |
+| Tool cards | `tool-card` (plus one status modifier: `tool-card-pending`, `tool-card-deferred`, `tool-card-done`, `tool-card-error`, `tool-card-declined`, `tool-card-interrupted`), `tool-card-head`, `tool-card-icon`, `tool-card-name`, `tool-card-status` (plus `tool-card-status-pending`, `tool-card-status-deferred`, `tool-card-status-done`, `tool-card-status-error`, `tool-card-status-declined`, `tool-card-status-interrupted`), `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`, `tool-card-repeat` |
+| Tool-step group | `tool-group` (plus one state modifier: `tool-group-waiting`, `tool-group-running`, `tool-group-done`, `tool-group-error`), `tool-group-head`, `tool-group-icon`, `tool-group-label`, `tool-group-meta`, `tool-group-list` |
+| 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` |
+| Place chip | `place` (carries `data-excluded` while the user withholds the place), `place-icon`, `place-label`, `place-detail`, `place-toggle` |
+| 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` |
+| Skills | `skill-chips`, `skill-chip`, `skill-palette`, `skill-item`, `skill-item-title`, `skill-item-desc`, `skill-item-token`, `skill-hint` (the composer hint: a skill’s missing placeholders, and a run continuation picked with nothing typed or while a run is in flight) |
+| Thread drawer | `drawer`, `drawer-backdrop`, `drawer-panel`, `drawer-header`, `drawer-title`, `drawer-new`, `drawer-close`, `drawer-filter`, `drawer-list`, `drawer-empty`, `drawer-group-label`, `drawer-row`, `drawer-row-select`, `drawer-row-title`, `drawer-row-time`, `drawer-row-preview`, `drawer-row-actions`, `drawer-row-rename`, `drawer-row-delete`, `drawer-rename-input`, `drawer-confirm`, `drawer-confirm-label`, `drawer-confirm-yes`, `drawer-confirm-no` |
+| Charts | `chart-block`, `chart-title`, `chart-legend` |
+| Checkpoints panel | `checkpoints`, `checkpoints-header`, `checkpoints-title`, `checkpoints-list`, `checkpoints-empty`, `checkpoint-row`, `checkpoint-label`, `checkpoint-time`, `checkpoint-id`, `checkpoint-branch`, `checkpoint-action` (plus `checkpoint-resume`, `checkpoint-fork`) |
+
+> **Hiding `::part(header)` hides the controls inside it.** The history, checkpoints, new-chat,
+> theme and collapse buttons are all children of the header, so a host that renders its own title
+> bar and does `ag-ui-chat::part(header) { display: none }` loses thread switching entirely. Every
+> one of them has an imperative equivalent, so your own chrome can drive them:
+>
+> | Control | Method |
+> | --- | --- |
+> | History drawer | `chat.openThreads()` |
+> | Checkpoints panel | `chat.openCheckpoints()` |
+> | New chat | `chat.newChat()` |
+> | Collapse | `chat.toggleCollapsed()` / `chat.setCollapsed(bool)` |
+> | Theme toggle | `chat.toggleTheme()` |
+>
+> ```js
+> myHeaderButton.onclick = () => chat.openThreads();
+> ```
+>
+> The built-in buttons call exactly these methods, so the two routes cannot drift. If you only want
+> to restyle the header, prefer `::part(header)` styling or the `header-actions` slot over hiding it.
+>
+> To drop single controls instead, hide their parts:
+> `ag-ui-chat::part(history-button), ag-ui-chat::part(new-button) { display: none }`.
+> `display: none` removes them from the accessibility tree and the tab order as well.
+
+Coarse **slots** let you replace whole regions with your own markup (project light-DOM children
+with a matching `slot=`):
+
+| Slot | Where |
+| --- | --- |
+| `icon` | A header brand icon, before the title. |
+| `header-actions` | Extra controls between the title and the built-in buttons. |
+| `greeting` | The greeting's text, above the empty state, where the [greeting layout](#the-greeting-on-an-empty-page) is on. Replaces the text only; `empty` and the starters still render beneath it. |
+| `empty` | The empty-state shown before any message. |
+| `above-composer` | Directly above the composer, below the skill chips, hint, queued turns and attachment tray. Takes no space when empty, and moves with the composer in the [greeting layout](#the-greeting-on-an-empty-page). |
+| `footer` | Below the composer. |
+| `launcher` | The collapsed widget's mark — the floating launcher, or the sidebar rail. |
+| `icon-send` / `icon-stop` | The composer button's two glyphs (idle and mid-run). |
+| `icon-attach` / `icon-voice` | The paperclip and mic glyphs. |
+| `icon-history` / `icon-checkpoints` / `icon-new` / `icon-maximize` / `icon-collapse` | The header controls' glyphs. A slotted `icon-collapse` wins over `data-collapse-icon`. |
+
+```html
+<ag-ui-chat endpoint="/agent/">
+  <img slot="icon" src="/logo.svg" alt="" />
+  <button slot="header-actions" onclick="openHelp()">?</button>
+</ag-ui-chat>
+```
+
+### Header and launcher icon
+
+Give the header a brand icon with either the `icon` slot (any markup) or the `data-icon-url`
+convenience attribute (an `<img>`); the slot wins when both are set, and with neither the header
+stays icon-less. The same icon seam feeds the collapsed sidebar rail. Size it via
+`--ag-ui-icon-size` (default `22px`) and round it with `--ag-ui-icon-radius` (default `4px`).
+
+```html
+<ag-ui-chat endpoint="/agent/" data-icon-url="/logo.png"></ag-ui-chat>
+```
+
+### Sidebar placement
+
+`placement="sidebar"` is a full-height **docked** panel that slides open/closed and collapses to a
+slim **icon rail** rather than the [floating launcher](#collapsing-to-the-launcher) — the same
+element, shaped by the placement. It docks right by default; `data-side="left"` docks it left. The
+panel slides out through the edge it docks against. Collapse state reuses the `collapsed` attribute
+(persisted per-tab), and the rail carries `aria-expanded`. The slide honours
+`prefers-reduced-motion`.
+
+```html
+<ag-ui-chat endpoint="/agent/" placement="sidebar" data-side="left"></ag-ui-chat>
+```
+
+It overlays the page by default (no host-layout coupling). To make the host content reflow around
+it instead, set `--ag-ui-position: static` and place the element in your own grid/flex layout.
+
+### Page placement
+
+`placement="page"` turns the widget into a full-screen chat **page**: a full-bleed background with
+the conversation in a centred reading column (default ~820px, set via `--ag-ui-content-max-width`).
+The assistant turn spans the column width while the user message stays a right-aligned pill. Unlike
+`full` (edge-to-edge, left-aligned), it's the layout you want for a dedicated `/chat` route. Pairs
+naturally with the [answer well](#the-answer-well).
+
+```html
+<ag-ui-chat endpoint="/agent/" placement="page" data-answer-well></ag-ui-chat>
+```
+
+#### The greeting on an empty page
+
+Until the first message is sent, a page shows a greeting with the composer centred beneath it,
+and the composer moves to the foot of the page once the conversation has something in it. On a
+phone it starts at the foot, for the reason below.
+
+```html
+<ag-ui-chat endpoint="/agent/" placement="page" user-name="Ada"></ag-ui-chat>
+```
+
+- **The text** is `Hello, {name}`, filled from `user-name`, or `Hello there` when there is no
+  name. Both are string-table keys, `greeting` and `greetingNoName`, so `strings` and
+  `data-strings` translate them like everything else. `user-name` is live: a name that arrives
+  after an auth handshake replaces the greeting on screen.
+- **Your own greeting** goes in `slot="greeting"`, which replaces the text and nothing else. A
+  brand mark belongs there too. The `empty` slot and `data-starters` still render beneath it.
+- **Styling**: the `greeting` part, plus `--ag-ui-greeting-font` (default: the widget's font) and
+  `--ag-ui-greeting-size` (default `clamp(1.5rem, 4vw, 2.25rem)`, scaling with the viewport rather
+  than stepping at a breakpoint).
+- **`data-empty`** is present on the element while the conversation is empty, for chrome of your
+  own that should react to the same state.
+- **Which placements**: on by default for `page`, which is a route of its own. `data-greeting="off"`
+  restores the plain layout there. `embedded` opts in with `data-greeting` (any value but `off`),
+  for an app shell that gives the panel a page-sized box. The corner placements and the sidebar
+  never show it: a panel opened from a launcher is already mid-task.
+- **On a phone** the composer stays at the foot, the starters (or your own `empty` content) sit
+  against it, and the greeting takes the middle of what they leave — the middle of the
+  transcript when there are none. Centring is a shape for a screen with room to spare; at
+  [600px wide and below](#small-viewports) the room is what the on-screen keyboard takes, and a
+  composer centred over an empty band sits halfway up what is left of the screen, with the
+  prompts that start a conversation nowhere near the field that sends one.
+  `data-small-viewport="off"` keeps the centred shape at every width, as it keeps the rest of
+  the desktop layout.
+
+The composer's rows stay centred while you type, while a draft grows and while attachments are
+added, because the centring is two equal flexible halves either side of them and growth splits
+into both. Nothing in the DOM moves, so focus, the caret and IME composition are unaffected.
+
+**Sending is what moves it**, not typing, and the composer slides to the foot of the page over
+`--ag-ui-motion` (a single frame under reduced motion). Everything else that changes the
+conversation snaps: a restored conversation mounts docked, picking a thread from the list or
+continuing a run docks at once, and a new chat returns to the centre at once. While a slow
+conversation store is still fetching, the page stays docked with the greeting hidden, so a
+restored conversation never paints the empty layout first.
+
+### The answer well
+
+Each assistant turn renders inside one `.answer` group (part `answer`) that holds its streamed
+text, tool cards, and pending indicator — so a turn that calls tools reads as a single answer
+rather than a string of loose siblings. Add the boolean `data-answer-well` attribute to box that
+group in a bordered, padded "well"; without it the layout is the flat stack as before. The well is
+pure CSS and turn-scoped — no JS API — and themeable via `--ag-ui-well-bg`, `--ag-ui-well-border`
+and `--ag-ui-well-radius` (and `::part(answer)`).
+
+The well's corners default to `--ag-ui-radius`, 12px unless you set it, in every placement. The
+panel's own frame is different: `page` and `sidebar` draw it square because it meets the edge of
+the window, but nothing inside the panel does, so the well stays round there too. Set
+`--ag-ui-well-radius` to round the well differently from the rest of the panel.
+
+```html
+<ag-ui-chat endpoint="/agent/" data-answer-well></ag-ui-chat>
+```
+
+### Model reasoning (thoughts)
+
+When a reasoning model streams its chain-of-thought (django-ag-ui forwards it as AG-UI reasoning
+events — enable a thinking budget via `MODEL_SETTINGS`, see its docs), the element renders a muted,
+collapsible **thoughts region** (part `thoughts`) at the top of the current answer group. It opens
+while the model reasons and folds away on the answer's first token; the reader can reopen it. The
+web component handles the `REASONING_*` event family (and the retired `THINKING_*`, which
+`@ag-ui/client` still converts onto it, with a console warning, during its deprecation window), so
+no client config is needed — the thoughts appear whenever the server forwards reasoning.
+
+The header is a toggle only once reasoning has text: a provider that opens and closes reasoning
+without sending any (redacted thinking, or summaries off) gets a plain label with no body, and no
+`thoughts-toggle` part. When reasoning ends the header settles to how long it took, string
+`thoughtFor` (`"Thought for {seconds}s"`, the sum of the turn's reasoning rounds); under a second it
+reads `thoughts`. A tool call likewise offers its details only over something: with no arguments
+and a blank result its toggle, and a one-step group's row, are not offered until a result with text
+arrives.
+
+### The composer
+
+The composer is one bordered surface (part `composer-surface`) that owns the border and the focus
+ring: the field sits on top and grows with what is typed until it hits its ceiling and scrolls,
+and a tool row (part `composer-tools`) sits underneath with the paperclip and mic as quiet icon
+buttons on the left and a circular **Send** on the right. Send is icon-only — its accessible name
+still comes from the `send` / `stop` [strings](#internationalization-i18n) — and it becomes the
+Stop control mid-run by swapping its glyph, so nothing moves when a run starts.
+
+```css
+ag-ui-chat {
+  --ag-ui-composer-radius: 14px;
+  --ag-ui-composer-max-height: 40vh;  /* where the growing field starts scrolling */
+  --ag-ui-tool-btn-size: 30px;        /* the paperclip / mic hit targets */
+  --ag-ui-send-size: 30px;            /* the send circle */
+  --ag-ui-glyph-size: 18px;
+  --ag-ui-glyph-stroke: 1.75;
+}
+```
+
+Every glyph is a slot with the built-in mark as its fallback (`icon-send`, `icon-stop`,
+`icon-attach`, `icon-voice`), so projecting your own icon set never means restyling a character.
+
+### Motion
+
+One duration and two curves drive every collapse, expand and slide-over, so the whole widget
+settles as one thing:
+
+```css
+ag-ui-chat {
+  --ag-ui-motion: 0.28s;
+  --ag-ui-ease: cubic-bezier(0.32, 0.72, 0, 1);      /* the settle */
+  --ag-ui-ease-pop: cubic-bezier(0.34, 1.36, 0.64, 1); /* the arrival, with overshoot */
+}
+```
+
+Under `prefers-reduced-motion: reduce` the duration collapses to a single frame: states still
+change, nothing travels. Set `--ag-ui-motion: 0s` to switch the animation off outright.
+
+### Voice input
+
+Set `data-transcribe-url` (django-ag-ui's `TranscribeView`) to reveal a mic button in the
+composer (part `voice-button`). Click it to record via `MediaRecorder`, click again to stop — the
+clip is POSTed to the endpoint and the returned transcript is dropped into the textarea. Swap the
+transport with a custom `transcribeHandler` — `(audio: Blob) => Promise<string>` — to use a
+different STT endpoint or a browser Web Speech adapter without touching the button; when set, the
+mic appears even with no `data-transcribe-url`.
+
+```html
+<ag-ui-chat endpoint="/agent/" data-transcribe-url="/agent/transcribe/"></ag-ui-chat>
+```
+
+### Theme toggle
+
+`theme` is a plain attribute you can set yourself, and a host can always drop its own switch into
+`slot="header-actions"`. For convenience, the boolean `data-theme-toggle` attribute adds a built-in
+light⇄dark toggle to the header (part `theme-toggle`) that flips the scheme word of `theme` and
+persists the choice per tab. Only the scheme changes: `soft` becomes `soft dark`, `soft dark`
+becomes `soft light`, and `auto` becomes the opposite of what the system shows, an explicit
+choice. With no scheme word the toggle flips the scheme the panel is drawn in, so a host rule
+that sets the element's `color-scheme` (to follow the page's own dark mode) is flipped from,
+and the written word then holds against that rule. The toggle's glyph follows a `theme` the host
+writes later too, so a host's own picker and the toggle never disagree. Only the scheme is saved, too:
+on the next load it is put beside whatever theme name the markup carries, so `dark` chosen on a
+`soft` page restores as `classic dark` on a `classic` one. Off by default so it never competes with
+a host-supplied control.
+
+```html
+<ag-ui-chat endpoint="/agent/" data-theme-toggle></ag-ui-chat>
+```
+
+---
+
+## Internationalization (i18n)
+
+Every user-facing string — labels, placeholders, `aria-label`s, and `title` tooltips — is read
+from a flat `UiStrings` table, so a non-English host can translate the widget without forking it.
+Override any subset; the rest fall back to the English defaults. Two equivalent seams:
+
+```js
+// As a property (merged over the defaults):
+chat.strings = { send: "Senden", inputPlaceholder: "Frag mich…", stop: "Stopp" };
+```
+
+```html
+<!-- Or inline, as JSON (the property wins key-by-key when both are set): -->
+<ag-ui-chat endpoint="/agent/" data-strings='{"send": "Senden", "inputPlaceholder": "Frag mich…"}'></ag-ui-chat>
+```
+
+Set `strings` / `data-strings` **before** the element connects (they resolve on mount). A few keys
+are templates carrying `{token}` placeholders the widget fills in — e.g. `minutesAgo`
+(`"{n}m ago"`), `confirmRun` (`"Run “{tool}”?"`), `tooLarge` (`"Too large (max {size})"`). Keep the
+token verbatim when translating. The full key list and English defaults live in
+[`src/ui/ui_strings.ts`](src/ui/ui_strings.ts) (exported as `DEFAULT_UI_STRINGS`); `mergeUiStrings`
+is exported too if you want to compute a complete table yourself.
+
+---
+
+## Building the bundle
+
+The build is driven by [esbuild](esbuild.config.mjs) plus `tsc` for type declarations:
+
+```bash
+make build      # node esbuild.config.mjs && tsc -p tsconfig.build.json
+```
+
+This produces, into `dist/`:
+
+- `index.js` — the ESM library build; `@ag-ui/*` are left **external** so npm consumers dedupe
+  them.
+- `agents-web-components.bundle.js` — the **vendored** ESM bundle, every dependency inlined and
+  minified, suitable for direct `<script type="module">` embedding.
+- `index.d.ts` (+ source maps) — type declarations; emitted `.js` import specifiers are preserved
+  so consumers resolve types without extra flags.
+
+There is **no CSS file to load**. The styles are string constants adopted into
+the shadow root at construction, so they ship inside the JS and cannot leak into
+the host page. Restyle through the [CSS custom properties](#theming-density-and-placement) and the
+`part` attributes, not a stylesheet override.
+
+Other workflow targets (all identical in name to the sibling Python packages):
+
+| Target | What it does |
+| --- | --- |
+| `make test` | Vitest with a 100% line + branch + function + statement coverage gate. |
+| `make lint` | `biome check .` + `tsc --noEmit`. |
+| `make format` | `biome format --write .`. |
+| `make demo` | Build, then serve the live playground (`demo/themes/index.html`) on port 5173 via `demo/mock-server.mjs`. |
+
+---
+
+## Moving from `@artooi/ag-ui-web-component`
+
+The old package is replaced, not upgraded: the tags, events, parts, slots and `--ag-ui-*` custom
+properties keep their names, so markup and stylesheets carry over untouched. What changes is the
+package, how the element is defined, and a handful of removals.
+
+**Install the new package and remove the old one.** Never keep both on a page: each defines the
+`<ag-ui-chat>` tag, and the second to load cannot claim it.
+
+```bash
+npm uninstall @artooi/ag-ui-web-component
+npm install @artooi/agents-web-components
+```
+
+A vendored bundle is renamed too: `dist/agents-web-components.bundle.js` replaces
+`dist/ag-ui-web-component.bundle.js`.
+
+**Define the element.** `defineAgUiChat` is now `defineChat`, and it lives on the `./chat` entry.
+Importing the package still registers nothing, so the call stays explicit:
+
+```js
+// before
+import { defineAgUiChat } from "@artooi/ag-ui-web-component";
+defineAgUiChat();
+
+// after
+import { defineChat } from "@artooi/agents-web-components/chat";
+defineChat();
+```
+
+The bundle exports it too (`import { defineChat } from "@artooi/agents-web-components/bundle"`).
+`defineChat()` does nothing when `AgUiChat` already holds the tag, and throws, naming the tag,
+when another class holds it, which is how a second copy of the element shows itself.
+
+**The first deploy forgets what the browser stored.** Every storage key now starts with
+`agents-web-components` instead of `ag-ui-chat`, and nothing migrates the old keys. The first page
+load after the move starts from the defaults: the open thread, the collapsed state, the panel
+size, the launcher and dock position and the theme are gone once, and so is the drawer's list of
+threads, unless `data-threads-url` is set, in which case the server still supplies it.
+A host that reads the old keys itself must read the new root.
+
+**Removed names.** Each is gone; most have a replacement that behaves the same:
+
+| Removed | Use instead |
+| --- | --- |
+| `defineAgUiChat` | `defineChat`, from `./chat` |
+| `createStateHookTools`, `StateHook` | `createPageStateTools`, `PageState` |
+| the element's `registerStateHook` method | `registerPageState` |
+| `AgUiClient.annotatedMessages` | `AgUiClient.messages` |
+| the `noResult` string in `UiStrings` | nothing: `callNotFinished` answers a call that never returned |
+
+A string table that still sets `noResult` stops type-checking; delete the entry.
+
+**Server-side rendering.** The element extends `HTMLElement` and some helpers read the DOM, so
+evaluating the package in Node throws. Import it on the client only: from a client-side module, a
+dynamic `import()` behind a browser check, or your framework's client-only boundary. The package
+declares `sideEffects: false`, so an unused import is dropped, but that is a bundling property,
+not a promise that the modules load without a DOM.
+
+---
+
+## Compatibility
+
+| Component | Floor | Tested |
+| --- | --- | --- |
+| Node (tooling/tests only) | 22 | 22, 24 |
+| Browsers (runtime target) | Chrome 123, Firefox 120, Safari 17.5 | Chromium |
+| `@ag-ui/client`, `@ag-ui/core` | 1.0 | 1.0 |
+| django-ag-ui (server) | 0.63.0 | — |
+
+The shipped artefact targets evergreen browsers (Shadow DOM, Custom Elements v1, ES2022). The
+browser floor is set by `light-dark()`, which every theme declares its colours with: below Chrome
+123, Firefox 120 or Safari 17.5 those colours do not resolve. Node is only the build/test runtime,
+not a runtime target.
+
+The server floor is a wire contract rather than a dependency. A tool call's outcome and a user
+message's attachment refs travel in `metadata`, since `@ag-ui/client` 1.0 strips every key its
+schemas do not declare. Against an older django-ag-ui the chat still runs, but the agent is never
+told about an attached file and a failed or declined server-side tool call settles as done.
+
+---
+
+## License
+
+[MIT](LICENSE) © Artur Veres