@artooi/ag-ui-web-component 0.39.0 → 0.40.0

package/CHANGELOG.md

@@ -7,6 +7,159 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.40.0] — 2026-09-17
+
+### Changed
+
+- **An `askUserRenderer` that throws now hands the question to the built-in
+  question card.** A throw, or a rejected promise, used to escape the `ask_user`
+  tool: its card settled as an error quoting the host's message, that message
+  went on to the agent as the tool result although it was never written for the
+  model, and the pending wait was never closed, so the next Stop aborted the
+  signal of a question that had already ended.
+
+  The renderer decides how the question looks, not whether it is asked -- the
+  same rule `approvalRenderer` follows -- so it now falls back to the built-in
+  card, with a `console.warn` naming the tool call, and the run carries on as if
+  no renderer had been set. The exception is a rejection after the signal has
+  fired, which is how a renderer is expected to honour Stop: that wait resolves
+  with an empty answer, as the built-in card does on the same signal, with no
+  card drawn and no warning.
+
+- **On a small viewport the composer stays at the foot of the panel, with the
+  greeting over the space above it.** Until a conversation had something in it,
+  `page` -- and an `embedded` panel that opts into a greeting -- centred the
+  composer between the greeting and the foot at every width. Centring is a shape
+  for a screen with room to spare: on a phone the on-screen keyboard takes the
+  room, and the composer was left halfway up what remained with an empty band
+  under it, which is the part of the screen a thumb is already on. At 600px wide
+  and below it now stays at the foot, directly over the keyboard, and the
+  greeting takes the space above it. The prompts in `data-starters`, or
+  whatever a host slots as `empty`, go to the foot with it and sit against the
+  composer: a prompt chip is a way into the conversation, and next to the field
+  it starts it reads as one. The greeting takes the middle of what they leave,
+  and the middle of the transcript where there are none.
+  `data-small-viewport="off"` keeps the centred shape at every width, as it
+  keeps the rest of the desktop layout.
+
+### Fixed
+
+- **A tool card called with no arguments stops drawing an empty ARGUMENTS
+  heading.** The card hides the region rather than framing an empty object, but
+  the region declares its own `display`, which beats the user-agent rule for
+  the hidden attribute, so 42px of card was drawn holding a heading over
+  nothing -- on every call an agent made with no arguments, in the display mode
+  that shows arguments by default, and on a pending card's result region too.
+
+- **A checkpoint continuation is let go of when its first save fails.** The
+  save runs through `conversationStore` synchronously inside the send, and a
+  store is the host's to replace: the built-in one swallows a write the browser
+  refused, a server-backed one need not. A throw there left the element holding
+  a client that would never run, so every later Resume or Fork was refused for
+  it with no way to clear it -- the composer's button is Send until a run
+  reports a start, so Stop was never offered -- and `sharedState` went on
+  writing into the dead client, which the next run then sent stale. The failure
+  is now reported with a `console.warn` and the panel takes another pick.
+
+- **A turn typed between picking a checkpoint and its run starting is parked
+  rather than raced.** The composer learns a run is going from its first event,
+  a request round trip behind the pick, so its button was still Send: a turn
+  sent in that window started a second run against the conversation the
+  continuation had already frozen to save against, and whichever saved last
+  dropped the other's turn from the store while both answers streamed into one
+  transcript. The composer now queues it, as it does during a run, and sends it
+  when the continuation settles. `sendMessage` no-ops in the same window, as it
+  already did during a run.
+
+- **An empty row of skill chips stops taking space above the composer.** The
+  row is hidden whenever the host offers no skills, which is most elements most
+  of the time, but it declares its own `display`, and an author display beats
+  the user-agent rule for the hidden attribute. So it kept its 20px of padding
+  under every placement: a band of panel between the transcript and the
+  composer, reading as the gap under whatever the transcript ended with. The
+  palette and the queued row beside it were fixed for this reason already, and
+  a tool card's payload regions turned out to be a fourth case, below.
+
+- **A checkpoint continuation waits for the run in flight.** Picking Resume or
+  Fork while an answer was streaming started a second run beside it, and an
+  earlier continuation kept streaming where Stop no longer reached it. The pick
+  is now refused with a composer hint, as Retry is; the run in flight is left
+  alone and the typed turn stays in the composer. `continueWhileRunning` is new
+  in the string table.
+
+- **A continued exchange is kept with its conversation.** It was never saved,
+  so a reload lost it, and the next message went out without it and with the
+  shared state from before the continuation. Each save now writes the
+  conversation with the exchange after it, through the existing `saveMessages`
+  -- `ClientConversationStore` is unchanged -- and the next message carries
+  both. After continuing from an earlier run, what is saved is what the
+  transcript shows, not only the turns up to that run. `sharedState` reads a
+  running continuation, and `AgUiClient.annotatedMessages` is new: the history
+  in the form a save writes it, with how each tool call ended.
+
+- **A full-screen panel stays on the visible screen when a keyboard opens under
+  the field.** To show the composer, iOS Safari pans the visible area down the
+  page, and a panel anchored at the top of the screen stayed where it was: sized
+  to the visible height, it showed only its lower part, with the header and the
+  greeting off the top and an empty band above the keyboard. That covered
+  `page`, `full`, `side` and `sidebar`, and at phone width the corner placements
+  too, because they become the whole screen there, and their keyboard lift never
+  moved them: a box with its top, height and bottom all set ignores the bottom.
+  The element now also publishes how far the visible area is panned, as
+  `--ag-ui-visual-viewport-inset-top`, and every panel anchored at the top moves
+  down by as much of it as goes past the host's `--ag-ui-viewport-inset-top`.
+  `--ag-ui-keyboard-inset-top` outranks that, as `--ag-ui-keyboard-inset` does
+  at the bottom; `0px` opts out.
+
+  The same panel with a bar reserved at the top also ran past the bottom of the
+  visible area by the bar's height whenever a keyboard was up, pan or no pan:
+  the measured height replaced the host's box rather than being cut from it, so
+  the bar stayed in the position and left the height. The height is now the
+  host's box cut to the visible area.
+
+  At the deepest pan, the one that shows a composer docked at the foot of the
+  screen, the panel still went back to the top of the page at full height. The
+  element read the page's height from `innerHeight`, which iOS Safari reports
+  less the pan for as long as the pan lasts; at that depth it equals the visible
+  height, so the element took the two viewports to agree and withdrew its
+  measurements. The band below the visible area came out as nothing at any pan
+  too, leaving a bottom-anchored panel behind the keyboard. The page's height
+  is now read from the root element's `clientHeight`, which an iPhone reported
+  unchanged through the pan.
+
+- **A full-screen panel no longer runs under Safari's bars with no keyboard
+  up.** Where nothing has been measured, the panel's height fell back to
+  `100vh`, which iOS Safari resolves to the screen with its bars collapsed, so
+  on a page that never scrolls them away the foot of the panel sat under the
+  address bar: 40px on the iPhone measured, with a docked composer in it. The
+  fallback is now `100dvh`, the screen with the bars as they are.
+
+- **An element removed from the document and inserted again is one element.**
+  Every insertion built the chrome again into the same shadow root, so a
+  re-inserted `<ag-ui-chat>` had two headers, two composers, a second set of
+  resize grips, and the conversation drawn a second time beneath the first. The
+  listeners on its long-lived parts were added again too:
+  - one click on Stop cancelled the run three times;
+  - one press of the built-in theme toggle flipped it twice, so it appeared to
+    do nothing;
+  - a dropped or pasted file was added twice;
+  - one arrow press moved the launcher two steps.
+
+  With `data-threads-url`, a second remote store wrapped the first, so every
+  rename and delete reached the server twice. Frameworks do this without being
+  asked (a portal, a keyed list, a move between containers), and removing and
+  re-inserting is the documented way to apply a connect-time attribute written
+  late.
+
+  Connecting now builds the chrome in place of the last connection's, and ties
+  every listener on a long-lived part to the connection, so leaving the document
+  removes them. The upload tray and the mic are mounted afresh. The thread store
+  is wrapped once, and a `data-threads-url` removed while detached takes its
+  remote store away. The transcript is rebuilt from history, as `reload()`
+  rebuilds it. The composer's recall history is kept. Re-inserting still applies
+  the attributes as they stand when the element comes back. A host that called
+  `offerQuoteInPage()` calls it again after re-inserting, as before.
+
 ## [0.39.0] — 2026-09-17
 
 ### Changed
@@ -3973,7 +4126,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.39.0...HEAD
+[Unreleased]: https://github.com/Artui/ag-ui-web-component/compare/v0.40.0...HEAD
+[0.40.0]: https://github.com/Artui/ag-ui-web-component/compare/v0.39.0...v0.40.0
 [0.39.0]: https://github.com/Artui/ag-ui-web-component/compare/v0.38.0...v0.39.0
 [0.38.0]: https://github.com/Artui/ag-ui-web-component/compare/v0.37.0...v0.38.0
 [0.37.0]: https://github.com/Artui/ag-ui-web-component/compare/v0.36.0...v0.37.0

package/README.md

@@ -253,6 +253,11 @@ The list: `data-attachments-url`, `data-attachment-accept`, `data-attachment-max
 `data-skills-url`, `data-skills`, `data-prompt-chips`, `data-slash-commands`, `data-theme-toggle`,
 `data-strings`, `data-icon-url`.
 
+What re-inserting costs: the chrome is built again from the attributes as they stand, a run in
+progress is cancelled, and the conversation is redrawn from its stored history — the same rebuild
+`reload()` performs, and the reason that method exists for a host that can only configure the
+element after the fact.
+
 **Properties** (JS only, not attributes): `headers`, `getHeaders`, `trustedOrigins`, `allowImages`,
 `autoConfirm`, `confirmPredicate`, `askUser`, `askUserRenderer`, `approvalRenderer`,
 `approveWithEdits`, `agentFactory`, `getTools`, `getContext`, `routeMap`, `navigate`, `getPageMap`,
@@ -300,10 +305,13 @@ the `copyCode` / `copied` / `copyFailed` strings.
 
 `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
-palette, or a composer of your own replacing the built-in one. It no-ops while a run is in
-flight and for an entirely empty message, and unlike the built-in Send it does **not** consult
-the attachment tray: what you pass is what is sent, so your composer stays in charge of its
-own state.
+palette, or a composer of your own replacing the built-in one. It no-ops for an entirely
+empty message, and while a run — or a checkpoint continuation picked from the panel — is in
+flight; a continuation counts from the pick, not from its first event, so the gap where two
+runs could start against one conversation is closed. Unlike the built-in Send it does **not**
+queue, so your composer keeps what it tried to send, and it does **not** consult the
+attachment tray: what you pass is what is sent, so your composer stays in charge of its own
+state.
 
 `attachFile(file)` queues a file into the tray exactly as the picker and drag-and-drop do, with
 the same validation and progress chip. It returns `false` when uploads are not configured
@@ -869,6 +877,13 @@ chat.askUserRenderer = (request, { signal }) =>
   myModal.ask(request.question, request.options, { allowCustom: request.allowCustom, signal });
 ```
 
+**A renderer that throws or rejects falls back to the built-in card** for that call, with a
+`console.warn` naming the tool call. As with `approvalRenderer`, the renderer decides how the
+question looks, not whether it is asked, so the run carries on as if no renderer were set. The one
+exception is a rejection after the signal fired, which is how a renderer is expected to honour Stop:
+that wait resolves with an empty answer, as the built-in card does on the same signal, with no card
+and no warning.
+
 ### DOM-driver and animation primitives
 
 So the agent can visibly drive the host page, the package ships generic, framework-free
@@ -1082,7 +1097,10 @@ chat.addEventListener("ag-ui-toggle", (e) => console.log(e.detail.collapsed));
 ### The composer's own keys
 
 **Enter during a run queues.** A second run cannot start while one is in flight —
-it would orphan the first — so that key used to do nothing at all, silently. What
+it would orphan the first — so that key used to do nothing at all, silently. A
+checkpoint continuation picked from the panel counts as in flight from the pick
+rather than from its first event, which is a request later, so a turn typed in
+that gap is parked too rather than racing it. What
 is waiting shows above the composer as chips, each of which takes its message
 back when pressed, and the next one is sent when the run settles. Stopping the
 run discards them: sending into a conversation someone has just stopped is the
@@ -2384,6 +2402,12 @@ Picking a row with an empty composer says so above the input and puts the caret
 there, rather than closing the panel over nothing: a continuation sends **only**
 the new turn, so with nothing typed there is nothing to send.
 
+Picking a row while an answer is still streaming — the conversation's own, or
+another continuation's — is refused the same way: the hint asks you to wait or
+stop it, and what you typed stays in the composer for the pick after. The run in
+flight is not cancelled for you, since a continuation starting over it would
+leave two answers streaming into one transcript with Stop reaching only one.
+
 ### One URL, three endpoints
 
 `data-runs-url` is the only thing to configure. `resume/<id>/` and `fork/<id>/`
@@ -2401,7 +2425,7 @@ The component satisfies that structurally rather than by remembering a rule. A
 continuation runs on its own short-lived agent, built pointing at the resume
 endpoint and seeded with **no** history — so "only the new turn" is the only
 thing it *can* send, and the fresh run id comes free because a new agent mints
-one. Your main agent's history is never touched.
+one. Nothing of the conversation's history goes out on its request.
 
 A resumed run is a normal run in every other respect: frontend tools execute,
 approval interrupts render their card, `headers` are re-read per request so
@@ -2411,9 +2435,14 @@ a rotated CSRF token or JWT still reaches the endpoint, it carries and updates
 construction as the conversation's own, differing only in the endpoint and the
 empty seed.
 
-It does not write the conversation store. Its agent holds only the new turn and
-the answer, and a store keeps one message list per thread, so saving that would
-replace the stored conversation with its last exchange.
+The continued exchange joins the conversation. Its agent holds only the new turn
+and the answer, and a store keeps one message list per thread, so each save
+writes the conversation as it stood when you picked the row with the exchange
+after it — through the same `saveMessages` as any other run, and as far as it
+got if it was stopped. A reload then replays the exchange, and the next message
+you send, now to `endpoint` again, carries it together with the shared state the
+continuation left. What is saved is what the transcript shows: a fork's exchange
+follows the conversation it was picked from, in that same thread.
 
 If the index can't be reached, the panel shows its empty state rather than an
 error — a history affordance that fails is empty, not broken.
@@ -2745,6 +2774,12 @@ of the screen with a frame drawn round it.
 `embedded` is left alone deliberately: it sits in a box you sized and placed, and
 only you know whether that column should become the whole screen.
 
+The [greeting layout](#the-greeting-on-an-empty-page) changes shape here too, and
+it is the one part of this that `embedded` gets as well, because it moves nothing
+about the box you placed: an empty conversation keeps its composer at the foot of
+the panel, with the starters against it and the greeting over the space above
+them, instead of centring all three together.
+
 The corner placements still rest at their launcher, so a full-bleed panel is
 something the user opens rather than something they are given.
 
@@ -2831,11 +2866,25 @@ widget measures the hidden band and publishes it as
 `--ag-ui-visual-viewport-inset-bottom`; state this one instead to outrank that
 measurement, or set it to `0px` to opt out of the lift entirely.
 
+`--ag-ui-keyboard-inset-top` does the same at the top. To show a field a
+keyboard would cover, a mobile browser pans the visible area down the page, and
+a panel anchored to the screen (`page`, `full`, `side`, `sidebar`, and at phone
+width the corner placements too) moves down with it. An `embedded` panel renders
+in your own box rather than against the screen, so it does not move at any width.
+The widget publishes the pan as `--ag-ui-visual-viewport-inset-top`, and the
+panel moves by as much of it as goes past your `--ag-ui-viewport-inset-top`,
+since the pan scrolls a reserved bar away with the page. State
+`--ag-ui-keyboard-inset-top` to outrank that distance, or `0px` to keep the
+panel below your reserved top.
+
 `--ag-ui-viewport-height` and `--ag-ui-viewport-width` state the usable box
 outright, for the case where no viewport-percentage length describes it. An
 on-screen keyboard is the one that matters: it changes neither `vh` nor `dvh` nor
 `svh` on any current mobile browser, so a full-bleed panel has to be told the
-visual viewport's height rather than deriving it.
+visual viewport's height rather than deriving it. The widget does that itself;
+where it has nothing to report, the panel falls back to `100dvh` rather than
+`100vh`, because iOS Safari resolves `vh` to the screen with its bars collapsed
+and a panel sized from it runs under them.
 
 Marks are variables too, so one vocabulary covers a re-theme rather than
 leaving half the transcript in the built-in set: `--ag-ui-tool-icon-done` /
@@ -2961,7 +3010,7 @@ component sets, so a new one cannot ship undocumented.
 | 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 composer hint: a skill’s missing placeholders, and a run continuation with nothing typed) |
+| Skills | `skill-chips`, `skill-chip`, `skill-palette`, `skill-item`, `skill-item-title`, `skill-item-desc`, `skill-item-token`, `skill-hint` (the composer hint: a skill’s missing placeholders, and a run continuation picked with nothing typed or while a run is in flight) |
 | Thread drawer | `drawer`, `drawer-backdrop`, `drawer-panel`, `drawer-header`, `drawer-title`, `drawer-new`, `drawer-close`, `drawer-filter`, `drawer-list`, `drawer-empty`, `drawer-row`, `drawer-row-select`, `drawer-row-title`, `drawer-row-time`, `drawer-row-preview`, `drawer-row-actions`, `drawer-row-rename`, `drawer-row-delete`, `drawer-rename-input`, `drawer-confirm`, `drawer-confirm-label`, `drawer-confirm-yes`, `drawer-confirm-no` |
 | Charts | `chart-block`, `chart-title`, `chart-legend` |
 | Checkpoints panel | `checkpoints`, `checkpoints-header`, `checkpoints-title`, `checkpoints-list`, `checkpoints-empty`, `checkpoint-row`, `checkpoint-label`, `checkpoint-time`, `checkpoint-id`, `checkpoint-branch`, `checkpoint-action` (plus `checkpoint-resume`, `checkpoint-fork`) |
@@ -3050,7 +3099,8 @@ naturally with the [answer well](#the-answer-well).
 #### The greeting on an empty page
 
 Until the first message is sent, a page shows a greeting with the composer centred beneath it,
-and the composer moves to the foot of the page once the conversation has something in it.
+and the composer moves to the foot of the page once the conversation has something in it. On a
+phone it starts at the foot, for the reason below.
 
 ```html
 <ag-ui-chat endpoint="/agent/" placement="page" user-name="Ada"></ag-ui-chat>
@@ -3071,6 +3121,14 @@ and the composer moves to the foot of the page once the conversation has somethi
   restores the plain layout there. `embedded` opts in with `data-greeting` (any value but `off`),
   for an app shell that gives the panel a page-sized box. The corner placements and the sidebar
   never show it: a panel opened from a launcher is already mid-task.
+- **On a phone** the composer stays at the foot, the starters (or your own `empty` content) sit
+  against it, and the greeting takes the middle of what they leave — the middle of the
+  transcript when there are none. Centring is a shape for a screen with room to spare; at
+  [600px wide and below](#small-viewports) the room is what the on-screen keyboard takes, and a
+  composer centred over an empty band sits halfway up what is left of the screen, with the
+  prompts that start a conversation nowhere near the field that sends one.
+  `data-small-viewport="off"` keeps the centred shape at every width, as it keeps the rest of
+  the desktop layout.
 
 The composer's rows stay centred while you type, while a draft grows and while attachments are
 added, because the centring is two equal flexible halves either side of them and growth splits