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

package/README.md

@@ -184,6 +184,7 @@ another origin, add `credentials="include"` too; see
 | `data-skills-url` | — | URL of a JSON skill catalog (fetched with the element's headers and cookie policy). |
 | `data-tools-url` | — | URL of a server tool-label catalog (`[{ name, summary, description? }]`), fetched with the element's headers and cookie policy; labels tool-call cards for server-side tools. |
 | `user-key` | `userKey` | Who the stored conversation belongs to — any string identifying the signed-in principal. Joins the storage namespace, and **changing it purges what the previous principal left behind**. Live (not connect-time): a logout is the host's to announce. See [Who the stored conversation belongs to](#who-the-stored-conversation-belongs-to-user-key). |
+| `user-name` | `userName` | The signed-in user's display name, for the [greeting](#the-greeting-on-an-empty-page) an empty conversation shows under `placement="page"`. Presentation only: unlike `user-key` it scopes nothing and is never sent. Absent or blank gives the nameless greeting. Live. |
 | `data-threads-url` | — | URL of a server thread index (django-ag-ui's `ThreadsView`); enables durable, cross-device chat history. |
 | `data-threads-cache` | — | **On by default.** `="false"` stops mirroring message bodies into `sessionStorage` when `data-threads-url` is set, for a deployment that put history on the server so transcripts stay off the client. Only meaningful alongside `data-threads-url`. |
 | `data-runs-url` | — | URL of a server run index (django-ag-ui's `RunsView`); reveals the header's ⭯ *Continue a run* panel. See [Resuming a run](#resuming-a-run). |
@@ -206,6 +207,8 @@ another origin, add `credentials="include"` too; see
 | `collapsed` | `collapsed` | Reflected boolean; collapses the widget to its [launcher](#collapsing-to-the-launcher) (a rail under `placement="sidebar"`, the header bar under `embedded`). Persisted per tab. `placement="page"` has no collapsed state and ignores it. |
 | `data-dragging` | — | **Written by the element, not by you.** Stamped on whichever handle a gesture is currently using, so the styles can react and so the element knows not to re-place the widget under a drag in progress. Cleared on `pointerup` and on `pointercancel`. |
 | `data-expand-corner` | — | **Written by the element, not by you.** It stamps the corner a dragged or agent-moved panel opens from, so the collapse animation starts where the panel actually is. Listed because the element reads its own stamp back; setting it yourself is overwritten on the next move. |
+| `data-greeting` | — | CSS-only: `off` turns the [greeting layout](#the-greeting-on-an-empty-page) off under `placement="page"`, where it is on by default. Any other value turns it on under `placement="embedded"`. No other placement has it. |
+| `data-empty` | — | **Written by the element, not by you.** Present while the conversation has nothing in it, which is when the greeting shows. Public as a styling hook, so the chrome around a full-page chat can react to the same state, e.g. `ag-ui-chat[data-empty] ~ .page-footer { display: none }`. |
 | `data-small-viewport` | — | CSS-only: `off` keeps the desktop layout at every width, opting out of the [small-viewport override](#small-viewports). Everything that override sets is a token you can re-state; its trigger is a media query, which is the one thing you cannot. |
 | `data-paste-attach` | — | When to turn a long text paste into an attachment instead of composer text: absent for the 5000-character default, `off` to never, or a positive number of characters. Only acts where `data-attachments-url` (or a custom `uploadHandler`) gives it somewhere to go. |
 | `data-starters` | — | JSON array of prompts offered on an empty transcript, e.g. `'["Summarise this page"]'`. Fallback content for `slot="empty"`, so slotting your own replaces them. Shares the four-prompt and 120-character limits with the suggestion chips a run pushes. Read once at connect. |
@@ -237,7 +240,7 @@ neither camp is `data-launcher-icon-url`: it is read while the element connects,
 below, but is not observed, so a late write is inert and says nothing.
 
 **Live attributes.** Written at any time, before or after the element connects, and acted on
-either way: `title-text`, `placement`, `credentials`, `user-key`.
+either way: `title-text`, `placement`, `credentials`, `user-key`, `user-name`.
 
 **Connect-time attributes.** Read once, while the element connects, to decide what chrome exists at
 all — the tray, the mic, the skills menu, the header mark. Writing one afterwards has **no effect**;
@@ -250,13 +253,19 @@ 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`,
 `autoInjectPageMap`, `conversationStore`, `uploadHandler`, `transcribeHandler`, `navigationResult`,
 `skillContext`, `toolSummaries`, `formatToolPayload`, `formatRelativeTime`, `strings`,
 `resolvePageTarget`, `sharedState`, plus the read-only `unread` and `unhandledActivityTypes`, and
-the attribute mirrors `endpoint` / `userKey` / `toolDisplay` / `collapsed` / `credentials`.
+the attribute mirrors `endpoint` / `userKey` / `userName` / `toolDisplay` / `collapsed` /
+`credentials`.
 
 `headers` and `getHeaders` authenticate **every** request the element makes, not only the agent
 run; `getHeaders` is the one to use for a credential that rotates. See
@@ -296,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
@@ -566,9 +578,10 @@ pydantic-ai's own `ToolReturnPart` vocabulary — read the values off `TOOL_OUTC
 | `success` | done | The same thing, stated. |
 | `failed` | error | The call ran and failed. |
 | `denied` | declined | A person or a guard refused it, so it never ran. |
+| `interrupted` | not finished | It produced no result because the run ended first, and nobody refused it. |
 
 **Absent is a success, and anything unrecognised is too** — including a value from a later protocol
-version, and pydantic-ai's own `interrupted`. A card is a claim about what happened, and refusing to
+version. A card is a claim about what happened, and refusing to
 recognise a word is not grounds for claiming failure. So no server has to change to keep the
 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.
@@ -587,10 +600,23 @@ Either way the outcome is **persisted beside the tool message**, so a reload rep
 settled rather than as a plain result. 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
+turn holding a tool call with no result, and a run can leave one open in more ways than one: Stop
+while the stream is still arriving, a round that ends on `RUN_ERROR`, a call naming a tool nothing
+here owns, a server that never streamed the result. So before each request the client answers
+every call still open with the `callNotFinished` string (by default `Not finished: the run ended
+or moved on before this tool call returned a result.`) and the outcome `interrupted`, placed at the
+end of the round that made the call, and the card settles to **not finished** in the same words.
+That result blames nobody, because nobody declined: `declinedAction` is kept for a call a person
+was asked about and turned down — a confirmation card or an approval they declined, or one Stop
+closed while it was open. The calls a resumed approval is answering are left alone, because the
+resume is their answer.
+
 The catalog a run advertises is also the set that run can execute. Override `getTools` to scope
 what a page offers — say, exposing `delete_record` only where deleting makes sense — and a call
 naming a tool you withheld is treated exactly as a call naming a tool you never registered: no
-handler runs, and the card settles with the no-result label. Withholding is per run, so the
+handler runs, the card settles as not finished, and the next request answers the call in those
+words. Withholding is per run, so the
 mount-wide registry can stay complete. Hosts that leave `getTools` alone advertise the built-ins
 plus everything registered, which is precisely what dispatch could reach anyway.
 
@@ -606,16 +632,29 @@ AG-UI has no server-side cancel route: cancelling **aborts the streaming request
   `onPersist`, so a reload shows the truncated exchange. A muted **"⏹ Stopped"** note is appended
   (`.stopped-note`) — a deliberate stop is not an error, so no bubble.
 - The run loop stops: tool calls collected before the abort are **not executed**, and no further
-  round starts. A frontend tool handler already running completes, but its result doesn't trigger
-  a re-run.
+  round starts. A frontend tool handler already running completes and its result is kept, but it
+  doesn't trigger a re-run, and the calls after it in the same round do not start. Each call that
+  did not run settles as **not finished**, and the next request answers
+  it in those words rather than sending it without a result.
 - An **open confirmation card is declined** (`data-resolved="declined"`) — cancelling the run
-  answers the pending question. Likewise an open **approval card** is denied and an open
-  **question card** (`ask_user`) resolves with an empty answer.
+  answers the pending question. Likewise an open **approval card** is denied, and the next request
+  carries that decline as the call's result; a call already approved when Stop lands was declined
+  by nobody, so it is answered as not finished instead. An open **question card** (`ask_user`)
+  resolves with an empty answer. Reloading the page while a card is open does not decline it,
+  because nobody answered: the call comes back not finished; see
+  [MPA durability](#mpa-durability-surviving-full-page-reloads).
 - The new `onCancelled()` handler fires instead of `onError()`; `onSettled()` still follows
   (the terminal-rest guarantee), returning the button to **Send**.
 
 `cancel()` with no run in flight is a safe no-op. `newChat()` cancels any in-flight run before
-discarding the client.
+discarding the client, and so do switching conversations, `reload()` and removing the element. A
+[checkpoint continuation](#resuming-a-run) is the run in flight while it lasts, so Stop and all of
+these end it too.
+
+A cancelled run ends a moment later, once its request has closed or a running tool handler has
+returned. What it does then stays with the conversation it belonged to: its truncated exchange is
+saved to that thread, `ag-ui-run-finished` still reports the tools it ran, and nothing reaches the
+transcript or the Stop button of the conversation that replaced it.
 
 ### Registering tools
 
@@ -639,8 +678,9 @@ chat.registerTool({
 Registering a name twice replaces the earlier handler rather than throwing, so a re-fired
 host ref or React StrictMode's double-invoke is harmless -- but two different tools sharing
 a name means the second silently wins. Each `<ag-ui-chat>` element owns its own
-registry, AG-UI client, and Shadow DOM, so **multiple instances on one page never interfere** —
-there is no module-level shared state anywhere in the package.
+registry, AG-UI client, and Shadow DOM, so **multiple instances on one page never interfere**.
+The one record they share is which storage namespace each has claimed, and it exists to keep two
+of them out of each other's conversation.
 
 **A handler's thrown message leaves the browser.** If a handler rejects, its `Error.message` is
 posted back as that call's tool result: into the conversation, on to the AG-UI endpoint, persisted
@@ -668,7 +708,10 @@ Whether a call is gated is decided in this order:
 1. If `chat.autoConfirm === true`, the call **never** prompts (an "autopilot" toggle).
 2. Else if `chat.confirmPredicate` is set, its boolean return is authoritative — given the tool
    name + parsed args it decides per-call (so one tool can be instant for some args and confirmed
-   for others, which a static flag can't express).
+   for others, which a static flag can't express). **A predicate that throws or rejects refuses
+   the call**: no card, the handler does not run, the tool card settles as declined, and the agent
+   gets the `confirmCheckFailed` string as the result and carries on, as after a decline. The
+   error goes to the console, never to the endpoint.
 3. Else if the user has waived this tool name for the session, the call runs.
 4. Else the element falls back to [`isDestructive(parameters)`](src/tools/is_destructive.ts),
    which reads the `x-destructive` JSON-Schema flag.
@@ -688,7 +731,10 @@ The offer and the allowlist sit on the same path, so there is no dead button eit
 
 The waiver is **per tool name and per element**, held in memory and never persisted. A session
 decision that outlived the tab would be a permanent grant made by one click — which is what
-`autoConfirm` already exists to say deliberately. It is cleared when the element goes away.
+`autoConfirm` already exists to say deliberately. It is cleared when the element goes away, and
+when [`user-key`](#who-the-stored-conversation-belongs-to-user-key) changes hands: one person's
+*Always allow* is not the next person's, and a sign-out in the same tab does not remount anything.
+The first key to arrive keeps it, for the same reason it keeps the conversation.
 
 AG-UI has no built-in risk flag, so destructiveness is carried as a JSON-Schema extension at the
 **schema root**: `parameters["x-destructive"] = true` (use the exported `X_DESTRUCTIVE_KEY`
@@ -789,6 +835,12 @@ chat.approvalRenderer = (request, { signal }) =>
   myConfirmDialog(request.message ?? `Run ${request.toolName}?`, { signal });
 ```
 
+**A renderer that throws or rejects falls back to the built-in card** for that interrupt, with a
+`console.warn` naming it. The renderer decides how the question looks, not whether it is asked, so
+nothing runs without a click and 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 as denied, as the built-in card does on the same signal, with no card and no warning.
+
 ### Asking the user a question (`ask_user`)
 
 Set `chat.askUser = true` to offer the agent a built-in `ask_user` frontend tool. When the agent
@@ -825,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
@@ -1012,7 +1071,8 @@ matching JS API:
   The conversation it leaves is **kept**: it stays in the history drawer to return to, and on a
   server-backed store it stays on the server. Deleting one is the drawer row's own action. A chat
   nothing was ever sent in is the exception — it was never listed, so it is dropped rather than
-  left behind.
+  left behind. Focus moves to the composer, whichever control started the new chat, unless the
+  widget is collapsed, and the page is not scrolled to it.
 - `describeSurface()` — where the panel is and what can be done to it: placement, collapsed,
   whether it can be moved, whether it fills the screen, its box and the viewport. `movable` folds
   the two reasons a move can fail into the one answer a caller needs.
@@ -1037,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
@@ -1414,9 +1477,10 @@ If a tool's schema carries an `x-summary` string (use `X_SUMMARY_KEY`), the card
 label instead of the raw tool name.
 
 Every card leads with a **status icon** drawn entirely in CSS — a spinning ring while the call
-runs, then a check / cross / slash on success / error / decline. Re-theme it via custom
-properties (or the `tool-card-icon` part): `--ag-ui-tool-icon-done`, `--ag-ui-tool-icon-error`,
-`--ag-ui-tool-icon-declined` (quoted-string glyphs) and `--ag-ui-tool-spin-duration` (spinner
+runs, then a check / cross / slash / dotted ring on success / error / decline / not finished.
+Re-theme it via custom properties (or the `tool-card-icon` part): `--ag-ui-tool-icon-done`,
+`--ag-ui-tool-icon-error`, `--ag-ui-tool-icon-declined`, `--ag-ui-tool-icon-interrupted`
+(quoted-string glyphs) and `--ag-ui-tool-spin-duration` (spinner
 speed; the spin respects `prefers-reduced-motion`).
 
 ```html
@@ -1962,7 +2026,9 @@ does not declare the field, exactly as it does not declare the `attachments` an
 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.
+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.
 
 **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))
@@ -1978,6 +2044,20 @@ triggers a full reload. Before the handler navigates, the element writes a check
 
 The MPA round-trip becomes a clean observation point instead of a dropped conversation.
 
+**A reload the run did not expect settles every open call as not finished.** A round's history is
+saved when its stream ends, before the element asks about a gated call, runs a frontend tool or
+collects a server-side approval, so a reload in that window finds the round's calls with no result
+and no run left to produce one. On restore, every call without a result (other than a checkpointed
+navigating call) is answered the way the client answers an open call before a request: its card
+settles as `interrupted` ("not finished"), and the restored conversation gains the `callNotFinished`
+result with the outcome `interrupted`, so the next request carries a result for every call and a
+later reload shows the same.
+
+It is not declined, although Stop declines an open card. Pressing Stop is a person answering the
+question; a reload answers nothing. The saved history is the same whether the round was waiting on a
+person or on a frontend tool the reload killed, so a decline would be unproven for one and false for
+the other, and "not finished" is true of both. The same goes for a server-side approval left open.
+
 ### Who the stored conversation belongs to (`user-key`)
 
 `sessionStorage` is scoped to a tab, not to a session. It survives every same-tab navigation,
@@ -1992,7 +2072,11 @@ data, so treat that as the default and turn it off:
 The value is any string that identifies the principal — a user id, an account id, a hash of one.
 It joins the storage namespace, so two principals in the same tab cannot reach each other's
 conversation, and **changing it purges everything the previous principal stored**: transcript,
-history drawer index and navigation checkpoints, for this element's namespace only.
+history drawer index and navigation checkpoints, for this element's namespace only. The tools they
+waived with *Always allow* are forgotten with it, so the next principal is asked again, and so is
+[`sharedState`](#host-seams-the-spa-story): whatever the agent last wrote into it for them is cleared rather than
+sent on the next principal's first run, so a host that seeds shared state assigns it again for the
+principal who arrived.
 
 Set it live, from script, as part of signing out or in:
 
@@ -2158,7 +2242,9 @@ async def write_document(ctx: RunContext[AgentDeps], body: str) -> ToolReturn:
 ```
 
 Use this when the agent and the page are editing **the same object** (a document, a form, a
-canvas). Use `registerPageState` when the agent should *ask* for a value or *request* a change —
+canvas). Because it is the page's object rather than the conversation's, **New chat keeps it**; a
+change of [`user-key`](#who-the-stored-conversation-belongs-to-user-key) clears it. Use
+`registerPageState` when the agent should *ask* for a value or *request* a change —
 the tool call is visible in the transcript and can be gated by a confirmation card, which state
 events cannot.
 
@@ -2316,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>/`
@@ -2333,11 +2425,24 @@ 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, and `headers` are re-read per request so
-a rotated CSRF token or JWT still reaches the endpoint.
+approval interrupts render their card, `headers` are re-read per request so
+a rotated CSRF token or JWT still reaches the endpoint, it carries and updates
+[shared state](#host-seams-the-spa-story) like any other run, it is bounded by
+`data-max-tool-rounds`, and Stop ends it. Its client is built by the same
+construction as the conversation's own, differing only in the endpoint and the
+empty seed.
+
+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.
@@ -2650,6 +2755,13 @@ ag-ui-chat {
 }
 ```
 
+`--ag-ui-radius` is the theme's corner radius. It rounds the panel's frame and the corners inside
+the panel that have no radius of their own: the answer well, the conversation list's *New chat*
+button and filter field, and the *Undo* on a run notice. The frame is the exception where it meets
+the edge of the window. `page` and `sidebar` draw it square, and so does every placement but
+`embedded` on a small viewport, while the corners inside keep the theme's radius, since none of them
+meets that edge. `--ag-ui-panel-radius` sets the frame on its own, in any placement.
+
 ### Small viewports
 
 At **600px wide and below** every placement but `embedded` becomes one full-bleed
@@ -2662,25 +2774,34 @@ 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.
 
-### The conversation list on a full page
+**To keep your desktop layout at every width**, set `data-small-viewport="off"`.
+That exists because the *trigger* is the one part of this you cannot reach: every
+value the override sets is a `--ag-ui-*` token you can re-state, but a media
+query cannot read a custom property, so the breakpoint itself is a literal.
 
-On `placement="page"`, once the panel is at least **900px** wide, the chat-history
-list **docks beside the transcript** instead of covering it — no backdrop, no
-focus trap, and `role="region"` rather than a modal dialog. Covering the
-conversation to show the list of conversations hides the thing you are trying to
-get back to, and a dedicated route is the one surface with width to spare.
+The breakpoint is a width rather than a pointer test, and that is on purpose: a
+touch laptop is coarse-pointered and wide, a narrow desktop window is
+fine-pointered and small. Width decides the layout; the pointer decides which
+controls make sense.
 
-Narrower than that, or under any other placement, it stays the slide-over it was:
-a few hundred pixels of panel with a list docked into it leaves a column of
-transcript narrower than the messages in it. Width alone is not the test — an app
-shell can hand `embedded` a page-sized box, and that box is still a column of
-somebody's layout.
+### The conversation list
 
-`--ag-ui-threads-rail-width` sets the docked width (default 280px). While it is
-docked the host carries `data-threads-docked`, so your own CSS can react.
+The chat-history list slides over the transcript at every width and under every
+placement, a full page included. Opening it moves nothing underneath: the
+conversation, the centred greeting and the composer are exactly where they were.
+While it is open it is a modal dialog: focus moves into it, Tab stays inside it,
+and Escape, its close control or a click on the backdrop beside it closes it and
+returns focus to where it was. `openThreads()` and `closeThreads()` do the same
+from your own chrome.
 
 The list also grows a filter once there are eight or more conversations in it
 — above that a search box is worth having, below it it is a control asking to be
@@ -2690,16 +2811,6 @@ phrase you remember is as likely to be inside the conversation as on it, and it
 filters what the drawer already holds rather than going back to the server for a
 list that is already in memory.
 
-**To keep your desktop layout at every width**, set `data-small-viewport="off"`.
-That exists because the *trigger* is the one part of this you cannot reach: every
-value the override sets is a `--ag-ui-*` token you can re-state, but a media
-query cannot read a custom property, so the breakpoint itself is a literal.
-
-The breakpoint is a width rather than a pointer test, and that is on purpose: a
-touch laptop is coarse-pointered and wide, a narrow desktop window is
-fine-pointered and small. Width decides the layout; the pointer decides which
-controls make sense.
-
 ### Reserving the space your own chrome occupies
 
 A fixed placement covers the viewport it is given, and it does not know about
@@ -2755,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` /
@@ -2869,7 +2994,7 @@ component sets, so a new one cannot ship undocumented.
 
 | Feature | Parts |
 | --- | --- |
-| Shell | `panel`, `header`, `title`, `icon`, `header-controls`, `messages`, `empty`, `pending`, `stopped`, `jump-latest`, and one per resize grip: `resize-handle` plus `resize-handle-top`, `resize-handle-bottom`, `resize-handle-left`, `resize-handle-right`, `resize-handle-top-left`, `resize-handle-top-right`, `resize-handle-bottom-left`, `resize-handle-bottom-right` |
+| Shell | `panel`, `header`, `title`, `icon`, `header-controls`, `messages`, `empty`, `greeting`, `pending`, `stopped`, `jump-latest`, and one per resize grip: `resize-handle` plus `resize-handle-top`, `resize-handle-bottom`, `resize-handle-left`, `resize-handle-right`, `resize-handle-top-left`, `resize-handle-top-right`, `resize-handle-bottom-left`, `resize-handle-bottom-right` |
 | Header buttons | `header-button` on each, plus `history-button`, `checkpoints-button`, `new-button`, `collapse-button`, `theme-toggle` |
 | Collapsed widget | `launcher`, `launcher-icon`, `launcher-badge`, `rail-label` |
 | Answers | `answer` (the per-turn group), `message` (plus `message-user`, `message-assistant`), `code-copy` |
@@ -2885,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`) |
@@ -2917,6 +3042,7 @@ with a matching `slot=`):
 | --- | --- |
 | `icon` | A header brand icon, before the title. |
 | `header-actions` | Extra controls between the title and the built-in buttons. |
+| `greeting` | The greeting's text, above the empty state, where the [greeting layout](#the-greeting-on-an-empty-page) is on. Replaces the text only; `empty` and the starters still render beneath it. |
 | `empty` | The empty-state shown before any message. |
 | `footer` | Below the composer. |
 | `launcher` | The collapsed widget's mark — the floating launcher, or the sidebar rail. |
@@ -2970,14 +3096,64 @@ naturally with the [answer well](#the-answer-well).
 <ag-ui-chat endpoint="/agent/" placement="page" data-answer-well></ag-ui-chat>
 ```
 
+#### 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. 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>
+```
+
+- **The text** is `Hello, {name}`, filled from `user-name`, or `Hello there` when there is no
+  name. Both are string-table keys, `greeting` and `greetingNoName`, so `strings` and
+  `data-strings` translate them like everything else. `user-name` is live: a name that arrives
+  after an auth handshake replaces the greeting on screen.
+- **Your own greeting** goes in `slot="greeting"`, which replaces the text and nothing else. A
+  brand mark belongs there too. The `empty` slot and `data-starters` still render beneath it.
+- **Styling**: the `greeting` part, plus `--ag-ui-greeting-font` (default: the widget's font) and
+  `--ag-ui-greeting-size` (default `clamp(1.5rem, 4vw, 2.25rem)`, scaling with the viewport rather
+  than stepping at a breakpoint).
+- **`data-empty`** is present on the element while the conversation is empty, for chrome of your
+  own that should react to the same state.
+- **Which placements**: on by default for `page`, which is a route of its own. `data-greeting="off"`
+  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
+into both. Nothing in the DOM moves, so focus, the caret and IME composition are unaffected.
+
+**Sending is what moves it**, not typing, and the composer slides to the foot of the page over
+`--ag-ui-motion` (a single frame under reduced motion). Everything else that changes the
+conversation snaps: a restored conversation mounts docked, picking a thread from the list or
+continuing a run docks at once, and a new chat returns to the centre at once. While a slow
+conversation store is still fetching, the page stays docked with the greeting hidden, so a
+restored conversation never paints the empty layout first.
+
 ### The answer well
 
 Each assistant turn renders inside one `.answer` group (part `answer`) that holds its streamed
 text, tool cards, and pending indicator — so a turn that calls tools reads as a single answer
 rather than a string of loose siblings. Add the boolean `data-answer-well` attribute to box that
 group in a bordered, padded "well"; without it the layout is the flat stack as before. The well is
-pure CSS and turn-scoped — no JS API — and themeable via `--ag-ui-well-bg` / `--ag-ui-well-border`
-(and `::part(answer)`).
+pure CSS and turn-scoped — no JS API — and themeable via `--ag-ui-well-bg`, `--ag-ui-well-border`
+and `--ag-ui-well-radius` (and `::part(answer)`).
+
+The well's corners default to `--ag-ui-radius`, 12px unless you set it, in every placement. The
+panel's own frame is different: `page` and `sidebar` draw it square because it meets the edge of
+the window, but nothing inside the panel does, so the well stays round there too. Set
+`--ag-ui-well-radius` to round the well differently from the rest of the panel.
 
 ```html
 <ag-ui-chat endpoint="/agent/" data-answer-well></ag-ui-chat>