@artooi/ag-ui-web-component 0.44.0 → 0.46.0

package/CHANGELOG.md

@@ -7,6 +7,185 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
+
+- **A theme set.** `theme` is now up to two words in any order, a theme name
+  and a scheme, matched as words: `soft`, `soft dark`, `ledger auto`. The
+  names are `quiet` (the new default), `soft` (rounded, tinted from the
+  accent), `ledger` (dense, serif and monospace) and `classic` (the look
+  before this release). The schemes are `light` (the default), `dark` and
+  `auto`, which follows `prefers-color-scheme`. A word the component does not
+  ship adds no rules, so `theme="acme"` is Quiet and a hook for the host's own
+  `[theme~="acme"]` CSS, and `soft acme` starts from Soft.
+- **Three seeds theme everything.** Each theme declares `--ag-ui-bg`,
+  `--ag-ui-fg` and `--ag-ui-accent` with `light-dark()`, and every other colour
+  is mixed from them in oklch while still reading its own public token first.
+  New tokens: `--ag-ui-ink-2`, `--ag-ui-ink-3`, `--ag-ui-line`,
+  `--ag-ui-line-strong`, `--ag-ui-wash`, `--ag-ui-accent-ink`, `--ag-ui-tint`,
+  `--ag-ui-tint-2`, the type scale `--ag-ui-text-xs` to `--ag-ui-text-lg`,
+  `--ag-ui-leading`, `--ag-ui-serif`, `--ag-ui-frame-radius`,
+  `--ag-ui-frame-shadow`, and the status masks `--ag-ui-ico-check`,
+  `--ag-ui-ico-error` and `--ag-ui-ico-declined`.
+- **`extraStyles` (unstable).** A per-element `CSSStyleSheet[]` adopted after
+  the built-in sheet, for structure the tokens and parts cannot reach. It
+  works under a strict `style-src` CSP. It reaches class names inside the
+  shadow root, which are not a stable API and may change in any minor release.
+- **Text on the accent follows the accent.** Unless `--ag-ui-on-accent` is
+  set, it is white or black by the accent's luminance, whichever contrasts
+  more, where relative colour syntax is supported (Chrome 119, Firefox 128,
+  Safari 18). Firefox 120 to 127 and Safari 17.5 and 17.6 cannot compute it
+  and keep a fixed colour: white under `classic` and `code`, as before, and
+  the scheme's colour (white light, `#111111` dark) under `quiet`, `soft`
+  and `ledger`. Every built-in accent but `code`'s gets the same side either
+  way; a host's mid-tone accent there needs `--ag-ui-on-accent` set by hand.
+
+### Changed
+
+- **The default look changes for every host that sets no `theme`.** The
+  default is now Quiet: a neutral panel with the header on the panel itself,
+  no bubble for the agent's turn, status as an icon rather than a pill, its
+  own font stack instead of the page's, and a 48px launcher. `theme="dark"`
+  is Quiet in the dark scheme. **A host that wants the old look must opt in
+  with `theme="classic"`** (or `theme="classic dark"`); explicitly set tokens
+  keep working under every theme. Set `--ag-ui-font: inherit` to keep the
+  page's font under any theme.
+- **A host that sets only `--ag-ui-accent` loses the accent header,
+  launcher and tool names.** Quiet draws them in the panel's own colours,
+  and its user bubble is the accent at 12% rather than the fixed indigo it
+  was. To get them back, opt in with `theme="classic"`, or keep Quiet and
+  set `--ag-ui-header-bg`, `--ag-ui-launcher-bg` and `--ag-ui-tool-fg` to
+  the accent and `--ag-ui-header-fg` and `--ag-ui-launcher-fg` to the
+  colour on it.
+- **One chip row and one action row per answer**, under every theme but
+  `classic` and `code`. The skill chips show on the empty state only and,
+  once a message is sent, live in the slash palette alone. In an answer
+  that spans several bubbles (text, a tool call, more text), only the last
+  bubble keeps its copy, retry and feedback row.
+- **`ledger` replaces `code`.** `theme="code"` keeps working but is no
+  longer documented; Ledger is the monospace look now. `code` changes in
+  two ways: it sets `color-scheme: dark`, so native controls, scrollbars
+  and the placeholder draw dark, and text on its green accent (the send
+  icon) is black where relative colour syntax is supported, 8.3:1 where
+  white was 2.5:1.
+- **The browser floor rises to Chrome 123, Firefox 120 and Safari 17.5**,
+  from Chrome 120 and Safari 17. Every theme declares its colours with
+  `light-dark()`, which those versions are the first to support, and it is
+  used without a fallback: below the floor the colours do not resolve and
+  the widget draws without them. There is nothing to opt in to; a host
+  that must support an older browser stays on the previous release.
+- **`classic` meets AA contrast.** The status pill's text in both schemes,
+  the indigo tool names in the dark scheme (2.38:1) and the dark composer
+  placeholder (3.93:1) now clear 4.5:1, and the done mark in the dark scheme
+  clears 3:1. Otherwise classic is the old look.
+- **The theme toggle flips only the scheme word**, so `soft` becomes
+  `soft dark` and `soft dark` becomes `soft light`. Before, any value but
+  `dark` became `dark`, which dropped a theme name. It saves only the scheme
+  word, and a load puts the saved scheme beside the markup's own theme name,
+  so a scheme chosen on one page never carries that page's theme to
+  another. A value saved by an earlier release (`light` or `dark`) restores
+  as before.
+- **Chart series read the theme's palette.** `--ag-ui-chart-1` to
+  `--ag-ui-chart-6` still win; without them each theme supplies its own first
+  two series.
+
+- **The shadow stylesheet is split by concern.** `src/ui/styles.ts`, one
+  3,774-line string, is now composed from 27 modules, each in the directory of
+  the concern it styles: the token defaults and themes under `ui/shell/`, one
+  module per placement under `ui/placement/`, and the transcript, composer,
+  tool steps, interrupts, history and charts in theirs. The composed sheet is
+  the old one with every rule in the same order; only two comments changed
+  wording. Nothing a host sees changes, and **no host has to opt in**: tokens,
+  parts, attributes and the public type declarations are as they were.
+- **One record per placement.** What each `placement` does on the script side
+  -- what it collapses to, whether its launcher can be dragged, which axes it
+  resizes on, whether a first mount starts collapsed -- is now one descriptor
+  per placement in `src/ui/placement/surface_for.ts`, replacing three separate
+  tables that each listed placements. Every placement behaves as before, an
+  unknown value included, and **no host has to opt in**.
+- **The element builds its DOM through free functions.** The header, the
+  transcript and empty state, the composer and the launcher are each built by
+  a function in the directory of their concern (`ui/shell/build_header.ts`,
+  `ui/transcript/build_transcript.ts`, `ui/composer/build_composer.ts`,
+  `ui/shell/build_launcher.ts`), and the flag and JSON attribute readers are
+  free functions under `core/`. Internal restructuring: the DOM, its parts,
+  slots and listeners are the same and mount in the same order, the public
+  type declarations are unchanged, and **no host has to opt in**.
+- **The sub-agent test fixture is the wire django-ag-ui 0.72.0 writes.** The
+  recorded run was a copy from before pydantic-ai 2.63, which django-ag-ui now
+  floors. The regenerated one carries `role` on every `TEXT_MESSAGE_START`, a
+  `protocolVersion` on `RUN_STARTED`, an `entityId` on the reasoning event
+  that records a tool retry (a `REASONING_ENCRYPTED_VALUE`, new to the run),
+  and a retry result that no longer ends in pydantic-ai's "Fix the errors and
+  try again." prompt. The component reads none of the new keys: it takes message
+  ids from the events and builds the card from the `SUBAGENT_*` and
+  `ag_ui.subagent` events, and the unit and Chromium sub-agent tests, the
+  latter through the element's real `HttpAgent`, pass on the new file unchanged.
+  The demo's mock server sends the same retry-free result. A Chromium test now
+  asserts the run's closing answer renders past the new event; it fails on a
+  fixture whose event is malformed, where every delegation assertion settled
+  before it and passed. Test and demo only, nothing shipped changes,
+  and **a host owes nothing**.
+
 ## [0.44.0] — 2026-10-20
 
 ### Fixed
@@ -4582,7 +4761,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.44.0...HEAD
+[Unreleased]: https://github.com/Artui/ag-ui-web-component/compare/v0.46.0...HEAD
+[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
 [0.42.0]: https://github.com/Artui/ag-ui-web-component/compare/v0.41.3...v0.42.0

package/README.md

@@ -64,6 +64,7 @@ No framework, no Django, no admin specifics live here. Downstream consumers (e.g
 - [Host seams: the SPA story](#host-seams-the-spa-story)
 - [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)
 - [Compatibility](#compatibility)
@@ -176,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. |
@@ -213,7 +214,7 @@ another origin, add `credentials="include"` too; see
 | `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` | — | CSS-only: `light` (default) / `dark` / `auto` / `code`. |
+| `theme` | — | CSS-only: 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`. See [Themes](#themes). |
 | `density` | — | CSS-only: `comfortable` (default) / `compact`. |
 | `placement` | — | CSS-only: `floating` (default) / `sidebar` / `page` / `embedded`. |
 
@@ -263,7 +264,7 @@ element after the fact.
 `approveWithEdits`, `agentFactory`, `getTools`, `getContext`, `routeMap`, `navigate`, `getPageMap`,
 `autoInjectPageMap`, `conversationStore`, `uploadHandler`, `transcribeHandler`, `navigationResult`,
 `skillContext`, `toolSummaries`, `formatToolPayload`, `formatRelativeTime`, `strings`,
-`resolvePageTarget`, `sharedState`, plus the read-only `unread` and `unhandledActivityTypes`, and
+`resolvePageTarget`, `sharedState`, `extraStyles` ([unstable](#d-extrastyles-the-last-mile)), plus the read-only `unread` and `unhandledActivityTypes`, and
 the attribute mirrors `endpoint` / `userKey` / `userName` / `toolDisplay` / `collapsed` /
 `credentials`.
 
@@ -1182,7 +1183,7 @@ or changing `user-key` clears it with the transcript.
 
 ### Collapsing to the launcher
 
-A collapsed widget shrinks to a round **floating launcher** in the corner it already occupies: the
+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
@@ -1204,15 +1205,19 @@ speech bubble.
 
 ```css
 ag-ui-chat {
-  --ag-ui-launcher-size: 56px;
-  --ag-ui-launcher-radius: 50%;   /* 12px for a squircle */
-  --ag-ui-launcher-bg: #14532d;   /* defaults to the header background */
-  --ag-ui-launcher-fg: #ffffff;
-  --ag-ui-launcher-icon-size: 26px;
+  --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
@@ -1470,15 +1475,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
@@ -1486,9 +1498,55 @@ 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.
+**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`, `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
 
@@ -2873,19 +2931,20 @@ ag-ui-chat { --ag-ui-accent: #b91c1c; }  /* one widget */
 > 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:
+A few of the knobs, at Quiet's light values:
 
 ```css
 ag-ui-chat {
-  --ag-ui-accent: #4f46e5;
-  --ag-ui-bg: #ffffff;
-  --ag-ui-fg: #1a1a2e;
+  --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. Change these with
-     the fills: a pale accent leaves white-on-pale everywhere they are used. */
+  /* 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;
 
@@ -2893,7 +2952,7 @@ ag-ui-chat {
   --ag-ui-width: 380px;
   --ag-ui-height: 560px;
   --ag-ui-inset: auto 24px 24px auto;
-  --ag-ui-shadow: 0 12px 32px rgba(20, 20, 50, 0.18);
+  --ag-ui-shadow: 0 1px 2px rgb(0 0 0 / 0.05), 0 12px 32px -16px rgb(0 0 0 / 0.22);
 }
 ```
 
@@ -2902,7 +2961,153 @@ the panel that have no radius of their own: the answer well, the conversation li
 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.
+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 (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
+`--ag-ui-font: inherit` to take the page's font under any theme.
+
+#### 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.
+
+#### 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
 
@@ -3082,7 +3287,7 @@ 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` — `light` (default) / `dark` / `auto` (follow the OS) / `code`.
+- `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
@@ -3109,7 +3314,8 @@ fix belongs to the containing element, not to the widget:
 <ag-ui-chat endpoint="/agent/" theme="dark" density="compact" placement="sidebar"></ag-ui-chat>
 ```
 
-See [`src/ui/styles.ts`](src/ui/styles.ts) for the full variable + preset list. The
+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.
@@ -3145,7 +3351,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`, `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-card-repeat` |
+| Tool-step group | `tool-group`, `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` |
@@ -3367,8 +3574,12 @@ mic appears even with no `data-transcribe-url`.
 
 `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 `theme` and persists the choice
-per tab. Off by default so it never competes with a host-supplied control.
+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 `dark`, an explicit choice. 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>
@@ -3418,7 +3629,7 @@ This produces, into `dist/`:
 - `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 a template literal injected into
+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.
@@ -3439,12 +3650,14 @@ Other workflow targets (all identical in name to the sibling Python packages):
 | Component | Floor | Tested |
 | --- | --- | --- |
 | Node (tooling/tests only) | 22 | 22, 24 |
-| Browsers (runtime target) | ES2022 / evergreen | Chrome / Firefox / Safari 17+ |
+| 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). Node is
-only the build/test runtime, not a runtime target.
+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