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

package/CHANGELOG.md

@@ -7,6 +7,224 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.48.0] — 2026-11-07
+
+### Added
+
+- **Choose how a step group draws its calls.** A new `data-tool-group-display`
+  attribute and `toolGroupDisplay` property, one of `full`, `compact`,
+  `minimal` or `inline`, set how an opened group draws its calls under
+  `grouped`. Each draws the regions the flat card of that mode draws, as a row
+  of the group. It is read only under `grouped`, is live, and leaves an
+  approval's arguments and buttons on screen in every mode. Exported as
+  `TOOL_GROUP_DISPLAY` with the `ToolGroupDisplayMode` type. **Opt-in**: an
+  absent or unknown value reads as `full`, which is what a group drew before,
+  so a host sees no change until it sets the attribute.
+- **Collapse into a bottom bar.** A new live `collapse-to` attribute chooses
+  what a collapsed panel becomes. `bar` draws a strip along the bottom edge in
+  place of the round launcher, with the title, the unread badge, a running
+  mark and a history button that opens and closes the conversation list as a
+  popover;
+  the panel rises from the bar's right end. `none` hides the collapsed widget
+  so the host's own toolbar drives it, and the `anchor` attribute or property
+  names the host element the panel rises from. Under both, the panel's height
+  stops at the bar or the anchor, so `--ag-ui-inset` is not needed, and a
+  docked panel can be resized but not moved. The read-only `barHeight`
+  property and the `ag-ui-bar-height` event (`BAR_HEIGHT_EVENT`, detail
+  `BarHeightDetail`) give the host the height to pad its page by. Under
+  `none` the element dispatches `ag-ui-toggle` once at connect with the state
+  it mounted in. On a phone the open panel stays full-bleed and the bar shows
+  only while collapsed. New parts `bar` and `bar-history`, and
+  `describeSurface()` reports `collapseTo`. **Opt-in**: absent,
+  `collapse-to` reads as `auto`, which leaves every placement as it was.
+- **Clear a host toolbar under `collapse-to="none"`.** The new
+  `--ag-ui-anchor-gap` token sets the gap between the panel and the anchor it
+  rises from, for a host whose button sits inside a taller toolbar; a gap
+  wider than the gutter also comes off the panel's max height, so a tall panel
+  stays on screen. **Opt-in**: absent, the gap stays 8px.
+
+### Changed
+
+- **The chat surface tools describe every collapsed shape.** With
+  `data-page-actions` including `chat`, the `minimise_chat` tool no longer
+  promises a launcher: its description names the launcher, the rail, the
+  bottom bar or the page's own control, and its refusal on a placement with no
+  collapsed state no longer mentions a launcher. The report `describeSurface()`
+  returns, and so `read_chat_surface`, gains `collapseTo`, and a move
+  refused on a docked panel says it is docked. This reaches every host that
+  enables the chat tools, whatever `collapse-to` is: an agent prompt that
+  quoted the old wording sees new text. No host action is needed.
+- **Tested against `@ag-ui/client` and `@ag-ui/core` 1.0.4.** The lockfile moves
+  from 1.0.3, and the declared range (`>=1.0.0 <2`) is unchanged, so a fresh
+  install of 0.47.0 already resolved 1.0.4. The element passes `threadId` to
+  the agent rather than reading the one 1.0.4 now creates on first read, and it
+  never edits a message the agent emits, which 1.0.4 now documents as
+  read-only. `zod` stays an undeclared peer of `@ag-ui/core`, as it was in
+  1.0.3. **No opt-in** and no behavioural change.
+
+- **The demo shows the 0.47.0 additions.** The playground gains a card under
+  the form with a control and a readout for each: the `above-composer` slot
+  (also a checkbox on the full-page route, where it travels with the centred
+  composer), the thread API (`threadId`, `newChat()`, `switchThread()` and a
+  log of `ag-ui-thread` events), the `tool-card-status-*` and `tool-group-*`
+  parts (drawn in one colour each, with a census of the parts in the
+  transcript) and the `--ag-ui-ring` token. Demo only, nothing shipped
+  changes, and **a host owes nothing**.
+
+### Fixed
+
+- **A collapsed embedded chat no longer shows the above-composer slot.** The
+  collapse hid the composer and its stack but not the `above-composer` slot, so
+  a host's row stayed on screen under the header bar. The slot is hidden with
+  the composer and returns on expand. No opt-in: a host that kept content in
+  that slot to stay visible while collapsed should use the footer slot, which
+  collapse leaves alone.
+
+- **`switchThread()` keeps the old thread when the store's load rejects.** The element
+  used to point at the new thread id, show an empty transcript and fire no
+  `ag-ui-thread`, so it named a thread it was not showing. It now stays on the thread
+  it was on, draws it again without an event, and the returned promise rejects with
+  the store's error. A second `switchThread()` for the thread still loading now
+  settles with that load, after the replay, instead of resolving at once. No host
+  opt-in.
+- **`newChat()` before the element connects waits for the connect.** It used to mint a
+  thread in the unscoped store and fire `ag-ui-thread` for a chat that was not yet
+  shown, leaving `threadId` non-null against the README. Now `threadId` is `null` and
+  nothing fires until the element connects, which starts the new chat and fires one
+  `ag-ui-thread` with reason `new`. A host that called `newChat()` early and relied on
+  the immediate event or thread id reads them after connect instead.
+
+- **Rings hold 3:1 against what they are drawn on.** The step group head's
+  focus ring was the accent at 55% over transparent, so a light host accent
+  fell to 1.6:1 on the default light panel (Django admin's `#79aec8`). Unset,
+  `--ag-ui-ring` is now two parts accent to three parts ink, which holds 3:1
+  against the panel for any accent in every theme and scheme; Quiet's ring
+  turns from a translucent grey to near-ink. The field highlight ring, when it
+  falls back to the chat's own accent, is now held to 3:1 against the surface
+  behind the target: a dark widget on a light page drew its near-white accent
+  at 1.1:1, and now draws the light half of its accent pair, or the accent
+  stepped toward black or white. **No opt-in is needed**, and a host's
+  `--ag-ui-ring`, `--ag-ui-highlight-ring-color` or page `--ag-ui-accent` is
+  still drawn exactly as given.
+
+- **The docs no longer advise `--ag-ui-font: inherit`.** The README and the
+  0.45.0 entry said it would keep the page's font under any theme. It does
+  nothing: a CSS-wide keyword in a custom property applies to the custom
+  property itself, so it takes the parent's `--ag-ui-font`, which nothing sets,
+  and the theme's stack wins. Set `--ag-ui-font` to the page's family or to a
+  page token instead, for example `--ag-ui-font: var(--body-font)`. A host that
+  followed the old advice has to change it to get the page's font.
+
+- **A chat never dragged no longer inherits a dragged size.** The size a drag
+  writes inline on the host was left undeclared on every other chat, so a chat
+  slotted into a dragged one, or under any page rule naming the private
+  property, came out at that size. It is now declared on `:host` like every
+  other private property. **No opt-in is needed.**
+
+- **Picking a thread from the history drawer no longer leaves an unhandled
+  rejection when the store cannot load it.** The drawer's pick dropped the promise
+  `switchThread()` returns, so a store whose load rejected surfaced as an unhandled
+  rejection on the page. The pick now ends that rejection itself, and the thread on
+  screen stays as it was. No host opt-in.
+
+- **A gated call with no arguments no longer draws an empty arguments box.** Under
+  `data-tool-display="compact"` and `"inline"`, the rule that shows a deferred call's
+  arguments outranked the `hidden` attribute the card sets when there are none, so an
+  empty box sat above the Approve button. The rule now skips a hidden section. No host
+  opt-in.
+
+- **The theme toggle flips the scheme the panel is drawn in.** With no `light` or
+  `dark` word in `theme`, as under `auto` on a dark system or when a host rule sets
+  the element's `color-scheme`, the first press wrote `dark` over a panel that was
+  already dark, and the glyph offered dark. The toggle and its glyph now read the
+  drawn scheme. A `light` or `dark` word also now holds against a host rule that
+  sets `color-scheme` on the element, which used to win over it. No host opt-in.
+
+## [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
@@ -4761,7 +4979,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.46.0...HEAD
+[Unreleased]: https://github.com/Artui/ag-ui-web-component/compare/v0.48.0...HEAD
+[0.48.0]: https://github.com/Artui/ag-ui-web-component/compare/v0.47.0...v0.48.0
+[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