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

package/CHANGELOG.md

@@ -7,6 +7,211 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.41.0] — 2026-09-22
+
+### Changed
+
+- **Requires `@ag-ui/client` and `@ag-ui/core` 1.0.** Both ranges are now
+  `>=1.0.0 <2`. A host that bundles the package itself resolves 1.0 beside it;
+  the vendored bundle carries its own copy.
+
+- **A tool result whose content arrives as parts shows its text.** Since 1.0 a
+  tool may return an ordered list of parts rather than a string, so a result can
+  carry an image beside its text. The card shows the text parts joined, both
+  while the run streams and when a reload replays it, and the saved conversation
+  keeps the message whole, parts included.
+
+- **A tool call's outcome and a message's attachment refs travel in
+  `metadata`.** `@ag-ui/client` 1.0 strips every key its schemas do not declare,
+  from an inbound event before any subscriber sees it and from the outgoing run
+  input before it is sent, and `metadata` is the one field on events and
+  messages it declares open by key. The element now reads a `TOOL_CALL_RESULT`'s
+  outcome from `metadata.outcome` only, which is also what
+  `AgUiClientHandlers.onToolResult` receives, and `sendMessage` puts a user
+  message's refs at `metadata.attachments`.
+
+  The client folds a result's metadata onto the tool message it keeps, so a
+  server's outcome is now saved on the message itself, and the element writes
+  the outcomes it decides on its own -- a declined confirmation, a frontend tool
+  that threw, a call the run left unfinished -- in the same place. The outcome
+  therefore goes back to the server with the rest of the history on every run,
+  which it never did before. `metadata` is a declared field, and a server that
+  does not read the key ignores it.
+
+- **Needs django-ag-ui 0.63.0 or later for outcomes and attachments.** An older
+  server writes the outcome, and reads the refs, at the top level, where 1.0
+  strips them. The chat still runs against one, but the agent is never told a
+  file was attached, and a failed or declined server-side tool call settles as
+  done.
+
+- **Conversations stored by an earlier release keep both.** Their tool messages
+  carry `outcome`, and their user messages `attachments`, at the top level. The
+  replay reads `metadata` first and falls back to the top-level key, so a
+  declined card stays declined after the upgrade and a bubble keeps its chips.
+  A client seeded from such a conversation moves both keys into `metadata`
+  before its first request, so the server is still told about every file
+  attached before the upgrade, and the next save writes the new shape.
+
+### Deprecated
+
+- **`AgUiClient.annotatedMessages` is the same list as `messages`.** It returned
+  a copy with each tool call's outcome added for the store, which the outcome
+  being on the message has made unnecessary. It is kept so code written against
+  it compiles and gets the same history.
+
+## [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 +4178,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.39.0...HEAD
+[Unreleased]: https://github.com/Artui/ag-ui-web-component/compare/v0.41.0...HEAD
+[0.41.0]: https://github.com/Artui/ag-ui-web-component/compare/v0.40.0...v0.41.0
+[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
@@ -561,8 +569,9 @@ the current page state.
 
 #### A tool call that failed
 
-A `TOOL_CALL_RESULT` may carry an optional **`outcome`** field saying how the call ended. It takes
-pydantic-ai's own `ToolReturnPart` vocabulary — read the values off `TOOL_OUTCOME`:
+A `TOOL_CALL_RESULT` may say how the call ended, as an optional **`outcome`** key in the event's
+`metadata` (`"metadata": { "outcome": "failed" }`). It takes pydantic-ai's own `ToolReturnPart`
+vocabulary — read the values off `TOOL_OUTCOME`:
 
 | `outcome` | Card | Means |
 | --- | --- | --- |
@@ -578,18 +587,23 @@ recognise a word is not grounds for claiming failure. So no server has to change
 rendering it has today, and a server that adds the field gets the truth on screen instead of a
 green card with a refusal folded inside it.
 
-Nothing in `@ag-ui/core` needs to declare the field: AG-UI's event schemas are zod `passthrough`, so
-an unknown key survives parsing and reaches the subscriber. It arrives on
-`AgUiClientHandlers.onToolResult` as an optional third argument, typed `unknown` because the
-protocol does not validate it; `toolStatusFromOutcome` does the narrowing.
+It has to be in `metadata`. `@ag-ui/client` 1.0 strips every key its schemas do not declare from an
+event before any subscriber sees it, with a `[ag-ui][enforce]` console warning, and `metadata` is
+the one place on an event it declares open by key. An `outcome` at the top level of the event —
+where a server wrote it for the 0.x client, and where a django-ag-ui older than 0.63.0 still does —
+never arrives, so the card settles as done. The key arrives on `AgUiClientHandlers.onToolResult` as
+an optional third argument, typed `unknown` because the protocol validates nothing inside
+`metadata`; `toolStatusFromOutcome` does the narrowing.
 
 A **frontend** tool never streams this event — the client posts its own result — so its outcome is
 recorded on the `ToolExecution` the executor returns (`{ content, outcome: "denied" }`). That covers
 the two refusals the component makes itself: a confirmation card the user declined, and a call
 blocked because the page moved under the round.
 
-Either way the outcome is **persisted beside the tool message**, so a reload replays the card as it
-settled rather than as a plain result. See
+Either way the outcome is **persisted on the tool message, in its `metadata`**, so a reload replays
+the card as it settled rather than as a plain result. For a server's result `@ag-ui/client` puts it
+there itself, folding the event's metadata onto the tool message it appends; for its own results the
+client writes it in the same place. See
 [MPA durability](#mpa-durability-surviving-full-page-reloads).
 
 **Every request carries a result for every tool call in it.** Several model providers reject a
@@ -869,6 +883,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 +1103,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
@@ -2001,16 +2025,23 @@ On mount the element rehydrates the transcript from the store, so the chat looks
 including tool-call cards and their results (reconstructed from the persisted `toolCalls` and `tool`
 messages), not just the text turns.
 
-A tool message is saved with an extra **`outcome`** field when the call did not simply succeed, in
-the same vocabulary the wire uses (see [A tool call that failed](#a-tool-call-that-failed)), so a
-failed or declined card replays as failed or declined instead of turning green on reload. `Message`
-does not declare the field, exactly as it does not declare the `attachments` an upload rides on a
-user message; the default store round-trips both through `JSON.stringify`. **A store that drops
-unknown fields loses only the distinction** — the card falls back to *done*, which is what it did
-before. It is written onto the copy handed to the store and never onto `agent.messages`, so it is
-not sent back to the server on the next run. That holds after a restore too: the client seeded from
-a stored conversation takes the field off every message it is seeded with and writes it back on the
-next save.
+A tool message is saved with an **`outcome`** in its `metadata` when the call did not simply
+succeed, in the same vocabulary the wire uses (see [A tool call that failed](#a-tool-call-that-failed)),
+so a failed or declined card replays as failed or declined instead of turning green on reload. A user
+message keeps the refs of its uploads the same way, under `attachments` in its `metadata`. Both
+round-trip through `JSON.stringify` in the default store. **A store that drops `metadata` loses only
+the distinction** — the card falls back to *done*, which is what it did before, and the bubble loses
+its chips.
+
+What is saved is exactly what the next request sends, so both go back to the server on every run.
+That is the protocol's own behaviour for a declared field rather than a client-side addition: a server
+validates `metadata` as an open object, and one that does not read a key ignores it — django-ag-ui
+reads `attachments` and ignores `outcome`.
+
+A conversation stored by an earlier release has both keys at the top level of the message instead.
+The history replay reads them from there when the metadata has none, and a client seeded from such a
+conversation moves them into `metadata` before its first request, because `@ag-ui/client` 1.0 would
+strip them from the request as it stands. The next save writes them in the new shape.
 
 **3. Resumable loop (`x-navigates` + `navigationResult`).** A tool whose schema carries
 `x-navigates: true` (use `X_NAVIGATES_KEY`; read back by [`isNavigates`](src/tools/is_navigates.ts))
@@ -2384,6 +2415,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 +2438,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 +2448,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.
@@ -2426,7 +2468,10 @@ out-of-band (multipart, with the element's `headers`) and shows a chip in a pend
 `uploading` (with a progress bar) → `ready`, or `error` with a retry. On send, the ready files'
 **refs** ride on the user bubble as read-only chips and the agent reads their contents
 server-side via the `read_attachment` tool. The wire stays vanilla AG-UI: only lightweight refs
-(`{ id, name, mime, size }`) travel, never the bytes.
+(`{ id, name, mime, size }`) travel, never the bytes, in the user message's `metadata` under
+`attachments` — the one place on a message `@ag-ui/client` 1.0 does not strip an unknown key from.
+django-ag-ui reads them from there as of 0.63.0; an older one reads only the top-level key 1.0
+removes, so against it the agent is never told a file was attached.
 
 ### Pasting
 
@@ -2597,7 +2642,7 @@ re-export point. Internal modules import from leaf paths.
 | `UploadOptions` | type | `{ url, headers?, credentials?, onProgress?, signal? }`. `credentials` is spelled as a fetch mode but carried by `XMLHttpRequest.withCredentials`, so only `"include"` is distinguishable. |
 | `UploadHandler` | type | `(file, onProgress, signal?) => Promise<AttachmentRef>` — the `uploadHandler` swap seam (tus / S3). The signal fires when the tray removes a chip or the element is torn down; a handler that honours it aborts its own transport, so a cancelled upload leaves no orphaned file on the server. |
 | `AttachmentRef` | type | The durable upload ref (`{ id, name, mime, size, url? }`). |
-| `messageAttachments(message)` | function | Read the refs a restored user message carries. |
+| `messageAttachments(message)` | function | Read the refs a restored user message carries: from its `metadata`, or from the top level where an earlier release stored them. |
 
 ### Voice input
 
@@ -2745,6 +2790,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 +2882,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 +3026,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 +3115,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 +3137,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
@@ -3107,9 +3181,9 @@ When a reasoning model streams its chain-of-thought (django-ag-ui forwards it as
 events — enable a thinking budget via `MODEL_SETTINGS`, see its docs), the element renders a muted,
 collapsible **thoughts region** (part `thoughts`) at the top of the current answer group. It opens
 while the model reasons and folds away on the answer's first token; the reader can reopen it. The
-web component handles the `REASONING_*` event family (and the deprecated `THINKING_*`, which
-`@ag-ui/client` maps onto it), so no client config is needed — the thoughts appear whenever the
-server forwards reasoning.
+web component handles the `REASONING_*` event family (and the retired `THINKING_*`, which
+`@ag-ui/client` still converts onto it, with a console warning, during its deprecation window), so
+no client config is needed — the thoughts appear whenever the server forwards reasoning.
 
 ### The composer
 
@@ -3240,11 +3314,17 @@ Other workflow targets (all identical in name to the sibling Python packages):
 | --- | --- | --- |
 | Node (tooling/tests only) | 22 | 22, 24 |
 | Browsers (runtime target) | ES2022 / evergreen | Chrome / Firefox / Safari 17+ |
-| `@ag-ui/client` | latest 0.x | — |
+| `@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 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
+schemas do not declare. Against an older django-ag-ui the chat still runs, but the agent is never
+told about an attached file and a failed or declined server-side tool call settles as done.
+
 ---
 
 ## License