@artooi/ag-ui-web-component 0.24.0 → 0.25.0

package/CHANGELOG.md

@@ -7,6 +7,122 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.25.0] — 2026-08-14
+
+### Added
+
+- **Every deferred call is asked about in its own card, and all of them at once.**
+  A run can defer more than one call, and the wire takes a different answer for
+  each — so the UI has to let a person give one, which means saying which card is
+  which. Importing three rows gated three `create_event` calls and produced three
+  identical prompts: the text comes from the tool, so all three read "Add this
+  event to the board?", and nothing else on the card named the row. They were also
+  serial, each appearing only once the previous was answered, appended below the
+  three calls they gated — so a person answering the first could not compare them
+  or tell that two more were coming. **A batch gate that can only be answered
+  uniformly is one you have to answer blind.**
+
+  Each prompt now renders into the tool card of the call it gates, under that
+  call's own arguments, and every card opens at once. No new wire field was needed:
+  the arguments were already there, and the call site already held the card. A
+  card being asked about shows its arguments in every `data-tool-display` mode,
+  since a density setting must not hide the answer to "which one is this". New
+  part: `tool-card-approval`.
+
+- **A status for "deferred, awaiting a decision".** `TOOL_CALL_STATUS` was
+  `pending | done | error | declined`, so a gated call sat at `pending` and read
+  **running…** while the stream was over and the server idle. A status enum missing
+  a state does not omit that state, it renders it as whichever neighbour is
+  closest, and this one claimed the opposite of the truth. Gated cards now read
+  `waiting for you` (`data-status="deferred"`, `strings.toolDeferred`), with a
+  steady dot instead of a spinner, and go back to `pending` on approval — because
+  then the tool really is running. A **frontend** tool such as `ask_user` keeps
+  saying "running…" while its card is open: the browser is executing it.
+
+- **The checkpoint rows lead with what the run was about.** A run index that
+  answers `GET runs/` with a `preview` — the run's first user message — and the
+  panel now shows it, with the time demoted to a chip beside it (new part:
+  `checkpoint-time`). A row with no preview keeps the old time-plus-short-id
+  layout, so an older server is unaffected.
+
+- **`toggleCheckpoints()` and `closeCheckpoints()`.** The built-in ⭯ control now
+  calls the toggle, so pressing it a second time dismisses the panel;
+  `openCheckpoints()` keeps its open-only meaning for a host that wants exactly
+  that.
+- **The checkpoint rows show a short run id.** A time is not an identity: two runs
+  of the same minute both read "just now", and choosing between them was choosing
+  blind. Eight characters of the id, muted, beside the time — with the whole id on
+  its own `title` rather than on the row's label, so hovering a row no longer
+  raises a full UUID over it. Now the fallback rather than the rule: a row that
+  arrives with a `preview` leads with the words instead (see above).
+
+### Changed
+
+- **`approvalRenderer` is called once per interrupt, concurrently.** It used to be
+  awaited one at a time. A host that can only ask one question at a time should
+  queue inside its renderer.
+
+### Fixed
+
+- **The README's parts list was missing an entire feature, and now a test reads
+  it.** Part names are declared public API there, and an undocumented part is not a
+  part: a host cannot style what it cannot know exists, and a name guessed wrong
+  fails silently. Absent were all twelve checkpoint-panel parts plus
+  `checkpoints-button`, and five strays from other features (`code-copy`,
+  `resize-handle`, `run-notice-icon`, `run-notice-text`, `skill-item-token`). The
+  list drifted because nothing read it, so the fix is not only the missing names:
+  it is now a table, spelled out in full rather than as `tool-card` *plus* `-icon`
+  shorthand, and a test collects every part the source sets and fails on one the
+  table does not name. The handful assembled at runtime are enumerated in that
+  test, and adding another such call site fails it too.
+
+- **The checkpoint panel could not be closed by the control that opened it.**
+  The button called `open()`, which returns early when the panel is already open,
+  so the first gesture anyone tries did nothing. Escape worked, and answering a row
+  worked, and that was all. It now toggles, and a pointer landing anywhere else in
+  the widget dismisses it — the thread drawer has a backdrop that swallows such a
+  click, and this popover has none.
+
+- **The thread drawer and the checkpoint popover could be open at once.** Opening
+  either now closes the other. The pointer case was already covered by the
+  click-away above, but a host driving its own chrome through `openThreads()` /
+  `openCheckpoints()` raises no pointer event, and the drawer would slide open
+  underneath a popover still floating over it.
+
+- **The panel read as a list of clickable rows.** Each row painted itself on hover
+  while nothing about the row was pressable: the two buttons that *were* pressable
+  sat on that highlight as transparent outlines. The row now carries a resting
+  surface and no hover at all, and the actions carry the filled-primary /
+  outlined-secondary pair the confirmation and approval cards already use, plus
+  `:active` and — new — a visible `:focus-visible` ring, in a panel that traps
+  focus and is reached by Tab.
+
+- **A narrow panel crushed the timestamp to nothing.** The row is a flex line whose
+  only flexible child is the label, so it absorbs every fixed-width element the row
+  gains; at 320px the label kept its text, reported it correctly, and measured 0px.
+  This is the tool-call head's defect (0.24.0) one panel along, and it is now
+  measured in a real browser at both widths — happy-dom lays out no boxes and
+  called the broken row a pass.
+
+- **The ⭯ glyph is now ↺.** The old one has no font behind it in most browsers and
+  rendered as an unreadable mark at 14px. A header control nobody can name is one
+  nobody presses.
+
+- **The composer painted a paperclip that could not upload anything.** The element
+  sets `hidden` on the attach button until a host gives it somewhere to upload —
+  an `uploadHandler` or `data-attachments-url` — but the button's own
+  `display: inline-flex` beat the UA stylesheet's rule for the hidden property, so
+  it stayed visible and clickable, opening a file picker whose file had nowhere to
+  go. This is the third instance of one trap: the attachment tray was fixed in
+  0.23.0 and carries a comment about it two rules away in the same file. Found in
+  the framework gallery, where three of the four host apps were in exactly that
+  state and nobody had noticed the clip was inert.
+
+  **The mic does not share it**, and the asymmetry is pinned by a test rather than
+  assumed: the clip is created and hidden, while the voice wiring returns before
+  constructing anything, leaving an empty slot that measures nothing. A
+  hidden-state rule for the mic would match no element, so there is one rule.
+
 ## [0.24.0] — 2026-08-13
 
 ### Added
@@ -1421,7 +1537,8 @@ 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.24.0...HEAD
+[Unreleased]: https://github.com/Artui/ag-ui-web-component/compare/v0.25.0...HEAD
+[0.25.0]: https://github.com/Artui/ag-ui-web-component/compare/v0.24.0...v0.25.0
 [0.24.0]: https://github.com/Artui/ag-ui-web-component/compare/v0.23.1...v0.24.0
 [0.23.1]: https://github.com/Artui/ag-ui-web-component/compare/v0.23.0...v0.23.1
 [0.23.0]: https://github.com/Artui/ag-ui-web-component/compare/v0.22.0...v0.23.0

package/README.md

@@ -546,19 +546,31 @@ approval card below is for.
 ### Server-side tool approval (interrupts)
 
 When the server gates a destructive tool (e.g. django-ag-ui's `ToolGuard`), the tool **defers**
-instead of executing and the run finishes on an AG-UI *interrupt*. The element then appends an
+instead of executing and the run finishes on an AG-UI *interrupt*. The element then renders an
 **inline approval card** (a `<div class="approval">`) via
-[`requestApproval`](src/ui/approval_card.ts), next to the pending tool-call card:
+[`requestApproval`](src/ui/approval_card.ts) **inside the tool card of the call it gates**:
 
 - **Approve** → the run resumes and the server runs the tool; its result streams back into the
   same card.
 - **Deny** → the run resumes carrying a `cancelled` answer, so the model learns the tool was
-  declined; the pending card settles as declined.
+  declined; the card settles as declined.
 
 This uses the AG-UI protocol's own interrupt/resume mechanism (`RunAgentInput.resume[]`) — the
 wire stays vanilla AG-UI. A **Stop** while an approval card is open denies every open card and
 cancels the run. No configuration is needed on the client; the gate is enabled server-side.
 
+**A run can defer several calls, and each is answered on its own.** Importing three rows defers
+three `create_event` calls, and the wire takes a different answer for each. So every question is
+asked **at once**, each in its own tool card, above that call's own arguments — which is what says
+*which* call it is about. The prompt cannot: it comes from the tool, so all three read "Add this
+event to the board?". While the run waits, those cards read **`waiting for you`**
+(`data-status="deferred"`), not "running…" — nothing is running, the stream is over and the server
+is idle. A card asking a question shows its arguments in every `data-tool-display` mode, since
+hiding them would hide the answer to "which one is this".
+
+A **frontend** tool such as `ask_user` stays at "running…" while its card is open, because the
+browser really is running it. Only a deferred call was claiming something untrue.
+
 **What the card asks.** An AG-UI interrupt carries the question as `message`, and the default is the
 call spelled out — `Approve create_event({"title": "Design sync", …})?` — which is accurate and not
 something to put in front of a person. A server can supply its own wording as **`x-confirm` in the
@@ -584,10 +596,12 @@ if your page renders the data it touched, listen for
 [`ag-ui-run-finished`](#host-seams-the-spa-story) and refetch.
 
 Like the question card, the approval card is customizable at three levels: **text** (`strings`:
-`approveAction` / `approvalPrompt` / `approve` / `deny`), **CSS** (`::part()`: `approval`,
-`approval-body`, `approval-actions`, `approval-button`, `approval-approve`, `approval-deny`), and
-**full replacement** via `chat.approvalRenderer` — given the request (`message` + `toolName`) and
-a Stop `AbortSignal`, render your own UI and resolve `true`/`false`:
+`approveAction` / `approvalPrompt` / `approve` / `deny` / `toolDeferred`), **CSS** (`::part()`:
+`approval`, `approval-body`, `approval-actions`, `approval-button`, `approval-approve`,
+`approval-deny`, and `tool-card-approval` for the region inside the card), and **full replacement**
+via `chat.approvalRenderer` — given the request (`message` + `toolName`) and a Stop `AbortSignal`,
+render your own UI and resolve `true`/`false`. A renderer is called **once per interrupt,
+concurrently**, so a host that can only ask one thing at a time should queue inside it:
 
 ```js
 chat.approvalRenderer = (request, { signal }) =>
@@ -1228,10 +1242,17 @@ component at the run index and a ⭯ button appears in the header:
 
 The panel lists runs the server marked **continuable** — those with a saved
 snapshot to seed from. A run that never reached a provider-valid boundary has
-none, so it isn't offered: resuming it would start from nothing. Each row shows
-when the run started (the id is on hover, for correlating with server logs) and
-marks a run that branched from another, so a fork doesn't read as a duplicate
-of its parent.
+none, so it isn't offered: resuming it would start from nothing.
+
+A row leads with the run's **first user message**, from the index's `preview`
+field, and shows when it started beside it. That is what makes the list a list of
+conversations: a time is not an identity, since two runs a minute apart both read
+"just now", and a run id is not something a person recognises. Where the server
+sends no preview — an older index, or a run that opened on an image with no
+caption — the row falls back to the time plus the first eight characters of the
+id (full id on hover, for correlating with server logs). Either way a run that
+branched from another is marked, so a fork doesn't read as a duplicate of its
+parent.
 
 Type the next turn in the composer, then pick a row:
 
@@ -1388,7 +1409,7 @@ re-export point. Internal modules import from leaf paths.
 | `ThreadMeta` | type | A thread-drawer row (`{ threadId, title, updatedAt, preview }`). |
 | `NavigationCheckpoint` | type | The pre-reload checkpoint marker. |
 | `RunIndex` | class | Reads a `data-runs-url` run index and derives its resume / fork endpoints. |
-| `RunRow` | type | One run index row (`{ run_id, thread_id, parent_run_id, started_at, continuable }`). |
+| `RunRow` | type | One run index row (`{ run_id, thread_id, parent_run_id, started_at, continuable, preview? }`). |
 | `CheckpointMenu` | class | The *Continue a run* panel. |
 | `CheckpointVerb` | type | `"resume" | "fork"`. |
 
@@ -1555,30 +1576,28 @@ ag-ui-chat::part(send)    { text-transform: uppercase; }
 ag-ui-chat::part(tool-card) { font-family: var(--my-mono); }
 ```
 
-Available parts: `panel`, `header`, `title`, `icon`, `header-controls`, `header-button`
-(plus `history-button` / `new-button` / `collapse-button` / `theme-toggle`), `messages`,
-`answer` (the per-turn group), `thoughts` (plus `thoughts-toggle` / `thoughts-body` /
-`thoughts-label`), `message`
-(plus `message-user` / `message-assistant`), `empty`, `pending`, `stopped` (the "⏹ Stopped" note),
-`tool-card`
-(plus `tool-card-head` / `-icon` / `-name` / `-status` / `-args` / `-toggle` / `-result`),
-`confirm` (plus `confirm-body` /
-`-args` / `-actions` / `-button` / `-cancel` / `-confirm`),
-`approval` (plus `approval-body` / `-actions` / `-button` / `-approve` / `-deny`),
-`question` (plus `question-body` / `-options` / `-choice` / `-choice-text` / `-radio` / `-input` /
-`-actions` / `-button`), `composer` (plus `composer-surface` / `composer-tools`), `input`, `send`,
-`attach-button`, `voice-button`,
-the attachment chips — `attachment-tray` and `attachment-chips` (the read-only chips on sent
-bubbles) with the shared chip parts `attachment-chip` (plus `-icon` / `-name` / `-size` / `-bar` /
-`-bar-fill` / `-retry` / `-remove`),
-the skills UI (`skill-chips`, `skill-chip`, `skill-palette`, `skill-item`, `skill-item-title`,
-`skill-item-desc`, and the missing-placeholder `skill-hint`),
-`launcher`, `launcher-icon`, `launcher-badge`, and the drawer parts
-(`drawer`, `drawer-backdrop`, `drawer-panel`, `drawer-header`, `drawer-title`, `drawer-new`,
-`drawer-list`, `drawer-empty`, `drawer-row`, `drawer-row-select`, `drawer-row-title`,
-`drawer-row-time`, `drawer-row-preview`, `drawer-row-actions`, `drawer-row-rename`,
-`drawer-row-delete`, `drawer-rename-input`, `drawer-confirm`, `drawer-confirm-label`,
-`drawer-confirm-yes`, `drawer-confirm-no`).
+Every part, by the feature it belongs to. Spelled out rather than abbreviated: the list used to
+read `tool-card` *plus* `-icon` / `-name`, which is compact and is also how an entire feature went
+missing from it for two releases. A test reads this table and compares it with the parts the
+component sets, so a new one cannot ship undocumented.
+
+| Feature | Parts |
+| --- | --- |
+| Shell | `panel`, `header`, `title`, `icon`, `header-controls`, `messages`, `empty`, `pending`, `stopped`, `resize-handle` |
+| Header buttons | `header-button` on each, plus `history-button`, `checkpoints-button`, `new-button`, `collapse-button`, `theme-toggle` |
+| Collapsed widget | `launcher`, `launcher-icon`, `launcher-badge` |
+| Answers | `answer` (the per-turn group), `message` (plus `message-user`, `message-assistant`), `code-copy` |
+| Reasoning | `thoughts`, `thoughts-toggle`, `thoughts-body`, `thoughts-label` |
+| Run notices | `run-notice` (plus `run-notice-interrupted`, `run-notice-attachment-pending`, `run-notice-compaction`, `run-notice-skill`), `run-notice-icon`, `run-notice-text` |
+| Tool cards | `tool-card`, `tool-card-head`, `tool-card-icon`, `tool-card-name`, `tool-card-status`, `tool-card-decision`, `tool-card-toggle`, `tool-card-body`, `tool-card-section` (plus `tool-card-args-section`, `tool-card-result-section`), `tool-card-section-label` (plus `tool-card-args-label`, `tool-card-result-label`), `tool-card-args`, `tool-card-result`, `tool-card-approval` |
+| Client-side confirmation | `confirm`, `confirm-body`, `confirm-args`, `confirm-actions`, `confirm-button` (plus `confirm-confirm`, `confirm-cancel`) |
+| Server-side approval | `approval`, `approval-body`, `approval-actions`, `approval-button` (plus `approval-approve`, `approval-deny`) |
+| Typed question | `question`, `question-body`, `question-options`, `question-choice`, `question-choice-text`, `question-radio`, `question-input`, `question-actions`, `question-button` |
+| Composer | `composer`, `composer-surface`, `composer-tools`, `input`, `send`, `attach-button`, `voice-button` |
+| Attachments | `attachment-tray`, `attachment-chips` (the read-only chips on sent bubbles), and the shared chip parts `attachment-chip`, `attachment-chip-icon`, `attachment-chip-name`, `attachment-chip-size`, `attachment-chip-bar`, `attachment-chip-bar-fill`, `attachment-chip-retry`, `attachment-chip-remove` |
+| Skills | `skill-chips`, `skill-chip`, `skill-palette`, `skill-item`, `skill-item-title`, `skill-item-desc`, `skill-item-token`, `skill-hint` (the missing-placeholder hint) |
+| Thread drawer | `drawer`, `drawer-backdrop`, `drawer-panel`, `drawer-header`, `drawer-title`, `drawer-new`, `drawer-list`, `drawer-empty`, `drawer-row`, `drawer-row-select`, `drawer-row-title`, `drawer-row-time`, `drawer-row-preview`, `drawer-row-actions`, `drawer-row-rename`, `drawer-row-delete`, `drawer-rename-input`, `drawer-confirm`, `drawer-confirm-label`, `drawer-confirm-yes`, `drawer-confirm-no` |
+| Checkpoints panel | `checkpoints`, `checkpoints-header`, `checkpoints-title`, `checkpoints-list`, `checkpoints-empty`, `checkpoint-row`, `checkpoint-label`, `checkpoint-time`, `checkpoint-id`, `checkpoint-branch`, `checkpoint-action` (plus `checkpoint-resume`, `checkpoint-fork`) |
 
 > **Hiding `::part(header)` hides the controls inside it.** The history, checkpoints, new-chat,
 > theme and collapse buttons are all children of the header, so a host that renders its own title