@artooi/ag-ui-web-component 0.45.0 → 0.47.0

package/CHANGELOG.md

@@ -7,6 +7,149 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.47.0] — 2026-11-07
+
+### Added
+
+- **Tool cards name their status as a part.** The `tool-card` part gains a
+  status modifier beside it, `tool-card-pending`, `tool-card-deferred`,
+  `tool-card-done`, `tool-card-error`, `tool-card-declined` or
+  `tool-card-interrupted`, and the status pill's `tool-card-status` gains the
+  matching `tool-card-status-<status>`. `::part()` takes no attribute selector,
+  so a host could not style failures only; now
+  `ag-ui-chat::part(tool-card-status-error)` does. The modifier is replaced as
+  the status changes. The folded step group does the same with its state:
+  `tool-group-waiting`, `tool-group-running`, `tool-group-done` or
+  `tool-group-error` beside `tool-group`. **No opt-in is needed**: the base
+  parts are unchanged, so an existing `::part(tool-card)` rule still matches,
+  and a host that wants the modifiers just writes the selector.
+
+- **`resetSize()`.** Drops a dragged size and its stored copy, so the placement's
+  size and the host's `--ag-ui-width` / `--ag-ui-height` apply again. For a host
+  entering a sized state of its own, which a user's drag would otherwise outrank.
+
+- **A public thread API, for a host that lists conversations in its own
+  chrome.** `switchThread(threadId)` puts a stored thread on screen and resolves
+  once it is replayed; during a run it cancels the run, as the drawer and
+  `newChat()` do. `deleteThread(threadId)` deletes one as the drawer row does,
+  replacing the thread on screen with a fresh one when it was that thread. The
+  read-only `threadId` is the thread on screen and never mints one, unlike
+  `conversationStore.threadId()`. The read-only `running` is the composer's own
+  state, across tool rounds, a Retry and a checkpoint continuation, reflected as
+  `data-running` on the element. A new `ag-ui-thread` event (`THREAD_EVENT`,
+  typed `ThreadDetail`) fires once per change of conversation, after the
+  transcript is replaced, with `{ threadId, previousThreadId, reason }` and
+  `reason` one of `new`, `switch`, `delete`, `restore` (on connect and on
+  `reload()`) or `rescope` (a `user-key` change). `ag-ui-run-finished` gains
+  `threadId`, the thread the run belonged to. **No opt-in is needed**; all of it
+  is additive. A host can now drop a patch that reached the private thread
+  switch, an attribute observer that inferred the running state, and reads of
+  `conversationStore.threadId()` made only to learn the thread on screen.
+  `ag-ui-submit` keeps its meaning: a turn was sent, not a run started.
+
+- **An `above-composer` slot.** Light-DOM content with
+  `slot="above-composer"` sits directly above the composer, after the skill
+  chips, the hint, the queued turns and the attachment tray, in every placement,
+  and moves with the composer in the greeting layout. An empty slot takes no
+  space. **Opt-in**: a host uses it by slotting content. A host that slotted
+  into `footer` and reordered the panel's flex column through `::part(composer)`
+  to lift it above the input can slot here instead and drop the reorder.
+
+### Changed
+
+- **Highlight rings on an unthemed page follow the widget's theme.** Since
+  0.45.0 the default accent is Quiet's near-black, but the rings the DOM
+  driver draws in the page (`flash`, `focusWithFlash`, `highlightThenClick`,
+  `pressThenClick`, `selectOption`, `toggleControl`, `showHighlightOverlay`)
+  still fell back to the old indigo. They now take the chat's resolved accent,
+  per theme and per scheme. A page that sets `--ag-ui-accent` on `:root`, or
+  passes `color`, keeps the rings it has. **No opt-in is needed.**
+  - New token `--ag-ui-highlight-ring-color`, beside
+    `--ag-ui-highlight-ring-width`. Set on `ag-ui-chat` (or above it) it
+    colours every ring with no `color` option, ahead of a target's
+    `--ag-ui-accent`; set on the page it reaches the target and wins over the
+    chat's.
+  - The press and toggle halo is now the ring colour at 40%. A host that
+    themes `--ag-ui-accent` had a solid halo in that colour; it is now
+    translucent, as the unthemed one always was.
+  - The rings read the most recently connected `<ag-ui-chat>`. A page with two
+    passes the acting one as the new `chat` option, which every ring-drawing
+    primitive and `showHighlightOverlay` take.
+
+- **A dragged panel size stays out of the host's tokens and out of the phone
+  shape.** The drag, and the size restored before first paint, no longer write
+  `--ag-ui-width` / `--ag-ui-height` on the element; they write the private
+  `--_drag-width` / `--_drag-height`, still persisted per tab under the same key.
+  Above 600px the dragged size beats the host's tokens, `!important` included:
+  the private properties are read before the public ones, so a host rule such as
+  `ag-ui-chat.expanded { --ag-ui-width: 900px !important }` used to beat a drag
+  and now loses to it until `resetSize()` is called. At 600px or less the
+  small-viewport block does not read the dragged size, so a persisted or freshly
+  dragged size leaves the full-bleed shape alone, including after a window
+  narrows. **Who owes what**: a host with no sized state of its own owes nothing.
+  A host that enters a sized state (an "expanded" class, a mode switch) and
+  relied on `!important` to outrank a user's drag must call `resetSize()` when it
+  enters that state. A host that read `--ag-ui-width` back from the element's
+  inline style to learn the dragged size must measure the element instead.
+
+## [0.46.0] — 2026-11-05
+
+### Changed
+
+- **Tool calls fold into a step group by default.** `data-tool-display`
+  gains `grouped`, and it is the new default (also for an absent or unknown
+  value). A run's consecutive tool calls fold into one quiet row, "Worked
+  through 5 steps", with a note such as "1 failed", and the per-call cards one
+  click down as `full` cards. Anything else in the turn ends the group, except
+  a call's own rendered output. **No
+  opt-in is needed, and a host that wants the old per-call cards opts out with
+  `data-tool-display="full"`**; `inline`, `minimal`, `compact` and `full`
+  render exactly as in 0.45.0. Grouping is the same under every theme; Soft
+  draws the row as a tinted pill and Ledger as a monospace heading.
+  - The group opens itself while a step waits on the user (a server-side
+    approval, which renders inside its card), once per wait; the user can
+    fold it again. It opens before the approval is drawn, so the Approve
+    button takes focus and scrolls into view, as it does under `full`. A
+    client-side confirmation or an `ask_user` question renders beside the
+    group and is in view without it opening, and the row reads "waiting for
+    you" for as long as one is open rather than "running".
+  - A running sub-agent does not open it: the folded row keeps its spinner
+    and names the delegation ("Delegated to researcher").
+  - Repeated labels are told apart inside a group, "Fill field" then "Fill
+    field (2)", in an element of its own; `tool-card-name` is never rewritten.
+  - A tool's rendered output (a chart) is placed after the group, in call
+    order, so it is never folded away, and a later call still joins the
+    group above it.
+  - Grouping is decided as each card is built. Switching to `grouped` folds
+    only calls drawn afterwards; switching to a card mode flattens existing
+    groups by CSS into the cards that mode builds.
+  - A restored conversation folds the same way as the live one.
+
+### Added
+
+- Parts `tool-group`, `tool-group-head`, `tool-group-icon`,
+  `tool-group-label`, `tool-group-meta`, `tool-group-list`, and
+  `tool-card-repeat` on a repeated step.
+- The `--ag-ui-ring` token (the group head's focus outline) and the
+  `--ag-ui-ico-chevron` mask image (its disclosure chevron).
+- Strings `toolGroupSteps`, `toolGroupWorking`, `toolGroupWorked`,
+  `toolGroupWaiting`, `toolGroupFailed`, `toolGroupDeclined` (`{count}`) and
+  `toolStepRepeat` (`{n}`).
+- `TOOL_DISPLAY.GROUPED`.
+- A `data-asking` attribute on a tool-call card while a question or a
+  confirmation is open on it. It is internal, read by the step group; the
+  card's `data-status` is unchanged.
+
+### Fixed
+
+- **The wheel scrolls the transcript when the pointer rests on a tool call's
+  arguments or result, a code block, the reasoning or a confirmation's
+  arguments.** Those blocks swallowed the wheel even when they had nothing
+  left to scroll, so the transcript sat still until the pointer moved to plain
+  text. They now hand the wheel on to the transcript, including a wheel that
+  carries a little sideways motion, as a real mouse or trackpad nearly always
+  does. This is long-standing and needs no opt-in.
+
 ## [0.45.0] — 2026-11-05
 
 ### Added
@@ -4703,7 +4846,9 @@ hosts that both arrange the page the way it expects.
 ### Notes
 - First release — exercising the automated npm OIDC publish pipeline end-to-end.
 
-[Unreleased]: https://github.com/Artui/ag-ui-web-component/compare/v0.45.0...HEAD
+[Unreleased]: https://github.com/Artui/ag-ui-web-component/compare/v0.47.0...HEAD
+[0.47.0]: https://github.com/Artui/ag-ui-web-component/compare/v0.46.0...v0.47.0
+[0.46.0]: https://github.com/Artui/ag-ui-web-component/compare/v0.45.0...v0.46.0
 [0.45.0]: https://github.com/Artui/ag-ui-web-component/compare/v0.44.0...v0.45.0
 [0.44.0]: https://github.com/Artui/ag-ui-web-component/compare/v0.43.0...v0.44.0
 [0.43.0]: https://github.com/Artui/ag-ui-web-component/compare/v0.42.0...v0.43.0

package/README.md

@@ -177,7 +177,7 @@ another origin, add `credentials="include"` too; see
 | `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"`. Live: writing it after the element connects re-labels the header. See [When each attribute is read](#when-each-attribute-is-read). |
-| `data-tool-display` | `toolDisplay` | Tool-call card detail: `inline` / `minimal` / `compact` / `full` (default `full`). |
+| `data-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-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. |
@@ -210,6 +210,7 @@ another origin, add `credentials="include"` too; see
 | `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-small-viewport` | — | CSS-only: `off` keeps the desktop layout at every width, opting out of the [small-viewport override](#small-viewports). 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. |
@@ -264,7 +265,7 @@ element after the fact.
 `approveWithEdits`, `agentFactory`, `getTools`, `getContext`, `routeMap`, `navigate`, `getPageMap`,
 `autoInjectPageMap`, `conversationStore`, `uploadHandler`, `transcribeHandler`, `navigationResult`,
 `skillContext`, `toolSummaries`, `formatToolPayload`, `formatRelativeTime`, `strings`,
-`resolvePageTarget`, `sharedState`, `extraStyles` ([unstable](#d-extrastyles-the-last-mile)), plus the read-only `unread` and `unhandledActivityTypes`, and
+`resolvePageTarget`, `sharedState`, `extraStyles` ([unstable](#d-extrastyles-the-last-mile)), plus the read-only `unread`, `unhandledActivityTypes`, `threadId` and `running`, and
 the attribute mirrors `endpoint` / `userKey` / `userName` / `toolDisplay` / `collapsed` /
 `credentials`.
 
@@ -289,7 +290,8 @@ labels are fetched automatically — per card, `x-summary` → an explicit
 `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).
+[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
@@ -298,14 +300,17 @@ the `copyCode` / `copied` / `copyFailed` strings.
 **Methods**: `registerTool`, `registerPageState`, `registerActivityRenderer`, `setSkills`,
 `sendMessage`, `attachFile`, `appendMessage`, `retryLastTurn`, `quote`, `offerQuoteInPage`,
 `enableCharts`, `newChat`, `setCollapsed`, `toggleCollapsed`, `describeSurface`, `moveTo`,
-`toggleTheme`, `openThreads`, `closeThreads`,
+`resetSize`, `toggleTheme`, `openThreads`, `closeThreads`, `switchThread`, `deleteThread`,
 `openCheckpoints`, `closeCheckpoints`, `toggleCheckpoints`, `reload`, and the deprecated
 `registerStateHook` (renamed to `registerPageState`).
 
 ### Sending from your own UI
 
 `sendMessage(content, attachments?)` sends as if the user had typed it — user bubble,
-`ag-ui-submit` event, run started. Use it for an "Ask about this order" button, a command
+`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.
 
@@ -960,8 +965,8 @@ human-readable speed (configurable; pass small/zero durations in tests):
   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 comes from the target's own `--ag-ui-accent` (so a themed
-  page is flashed in its own colour), or from `color`.
+  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`
@@ -999,11 +1004,13 @@ operations a tool handler typically wants:
   **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, the same place the flat ring reads `--ag-ui-accent`. Set them wherever they inherit to
-  the elements the agent touches, usually `:root`:
+  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 */
@@ -1047,6 +1054,29 @@ 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;
+5. the package indigo, when no chat is on the page at all.
+
+```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
@@ -1138,6 +1168,9 @@ matching JS API:
   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.
+- `resetSize()` — drop a size the user dragged, and its stored copy, so the placement's own
+  size and your `--ag-ui-width` / `--ag-ui-height` apply again. For a host that enters a sized
+  state of its own (an expanded mode): a user's drag outranks host tokens, so call this first.
 - `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.
@@ -1152,6 +1185,49 @@ chat.toggleCollapsed();
 chat.addEventListener("ag-ui-toggle", (e) => console.log(e.detail.collapsed));
 ```
 
+### 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.
+- `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.
+- `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 —
@@ -1475,15 +1551,22 @@ is the honest answer to "I pushed a chart and nothing happened".
 
 ## Tool-call display modes
 
-How much a tool-call card shows is set via the `data-tool-display` attribute (or `toolDisplay`
-property), one of `inline` / `minimal` / `compact` / `full` (default `full`):
+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. 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).
+- `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
@@ -1491,9 +1574,66 @@ never run together into one block, so where the call ends and the answer begins
 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`.
 
-**The attribute is live.** Changing `data-tool-display` 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.
+**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).
+
+### 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 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
 
@@ -1669,11 +1809,30 @@ and which grip carries the keyboard.
 
 ### Sizes, keyboard, and parts
 
-A drag writes `--ag-ui-width` / `--ag-ui-height` on the host as custom
-properties.
-
-**That alone does not leave placement in charge** — an inline custom property
-still outranks a `:host([placement=…])` rule setting the same property. So the
+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,
+  a mode switch) calls `resetSize()` when it does, which drops the dragged size
+  and its stored copy and hands control back to the host tokens. A host with no
+  such state needs nothing.
+- **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
@@ -2397,8 +2556,10 @@ chat.navigate = (path) => router.push(path); // SPA: in-page, no reload
 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: { tools: readonly ToolRun[] }` (typed `RunFinishedDetail`), where each `ToolRun` is
-`{ name, side: "server" | "client" }` in settle order.
+`detail: { threadId, tools: readonly ToolRun[], invalidated }` (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.
 
 **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
@@ -2681,6 +2842,7 @@ re-export point. Internal modules import from leaf paths.
 | `defineAgUiChat()` | function | Idempotently register the element. |
 | `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 }`). |
 | `UnreadDetail` | type | `detail` shape of the `ag-ui-unread` event (`{ unread }`). |
 | `AttachmentsDetail` | type | `detail` shape of the `ag-ui-attachments` event (`{ attachments, pending }`). |
@@ -2822,7 +2984,7 @@ re-export point. Internal modules import from leaf paths.
 | `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` | type | Primitive option shapes. |
+| `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
 
@@ -2830,6 +2992,7 @@ re-export point. Internal modules import from leaf paths.
 | --- | --- |
 | `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`). |
 | `TOGGLE_EVENT` | The collapse-toggle CustomEvent name (`ag-ui-toggle`). |
 | `UNREAD_EVENT` | The unread-count CustomEvent name (`ag-ui-unread`). |
 | `RUN_FINISHED_EVENT` | The interaction-finished CustomEvent name (`ag-ui-run-finished`). |
@@ -2960,7 +3123,8 @@ first, so each stays an override point. The tokens the themes add:
   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.
+  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 (the accent at 55%).
 
 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. Set
@@ -3297,7 +3461,8 @@ component sets, so a new one cannot ship undocumented.
 | 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`, `tool-card-head`, `tool-card-icon`, `tool-card-name`, `tool-card-status`, `tool-card-decision`, `tool-card-toggle`, `tool-card-body`, `tool-card-section` (plus `tool-card-args-section`, `tool-card-result-section`), `tool-card-section-label` (plus `tool-card-args-label`, `tool-card-result-label`), `tool-card-args`, `tool-card-result`, `tool-card-approval`, `tool-card-subagent` |
+| 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` |
@@ -3338,6 +3503,7 @@ with a matching `slot=`):
 | `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). |