@artooi/ag-ui-web-component 0.41.3 → 0.43.0

package/CHANGELOG.md

@@ -7,6 +7,307 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.43.0] — 2026-10-10
+
+### Fixed
+
+- **A second click on the mic while its permission prompt is open no longer
+  leaves a recording nothing can stop.** The mic button reads idle for as long
+  as the browser's prompt is up, which is seconds the first time an origin asks
+  and a few milliseconds after that, so a double click or an impatient second
+  click started twice. Both starts recorded and held a live track, but the
+  control kept only the second: one stop click ended that one, the first kept
+  recording with the browser's recording indicator on for a button reading
+  idle, and `dispose()` could not reach it either. The first start's two-minute
+  cap timer was orphaned too, and when it fired it stopped whatever recording
+  was current, so a later, unrelated one was cut short with "Stopped at the
+  2-minute limit". If the second start's recorder then failed, the failure
+  released the second stream and hid the first. The latest click now wins: a
+  start that settles after a newer one began, or after the control was disposed,
+  releases the microphone it was granted and touches nothing the newer start
+  owns, and a refusal on such a start no longer draws an error over the newer
+  one. The button is not blocked while a prompt is open, so a prompt the user
+  dismissed without answering, which a browser may leave pending forever, does
+  not stop the next click from asking again. Nothing for a host to opt into.
+
+- **A send made while a stored conversation loads no longer goes out without
+  it.** Every restore asks the conversation store for the conversation first:
+  on connect, on `reload()`, when a thread is picked from the drawer, and when
+  `user-key` changes from one principal to another. With `data-threads-url`
+  that is a request to the server,
+  and nothing held the composer while it was out unless the restore was about
+  to resume a run. So a send in that time went out carrying only its own turn,
+  and the agent answered without the conversation. Its save replaced the
+  stored conversation with the new exchange, and the replay then drew the
+  stored conversation under the new turn. The client the send built stayed
+  cached without the history, so every later turn on that page went out
+  without it too. A Retry in the window was refused, but it left the same
+  empty client cached, so the first send after the load lost the history the
+  same way. With the built-in store the window is one microtask, so it was
+  reached only by a send in the same task as the insertion: a script right
+  after `append`, a framework ref callback, or a layout effect.
+  Now every restore holds the composer until the conversation is drawn:
+  - A host's `sendMessage()` waits for the restore, then sends with the
+    conversation. Its bubble, its `ag-ui-submit` event and its request all move
+    to after the replay, so they arrive later than the call by the length of
+    the load. A host that listens on `ag-ui-submit` hears it that much later.
+  - If New chat, a thread switch, a change from one `user-key` to another or
+    `reload()` comes while the send waits, the send is dropped and resolves
+    `false` at once, because the conversation it was addressed to is no longer
+    on screen. If the element leaves the page, the send is dropped too, but it
+    resolves `false` only once the load answers or the element is inserted
+    again. A first `user-key` on an anonymous conversation adopts it rather than
+    replacing it, so a send waiting then still goes out. A second
+    `sendMessage()` while one waits is refused.
+  - The built-in Send queues what is typed during the load, showing it as
+    "Waiting to send", and sends it after the conversation is drawn, behind a
+    `sendMessage()` that was waiting.
+  - `retryLastTurn()` resolves `false` during the load, before it builds a
+    client.
+  - A checkpoint pick is refused during the load with a new composer hint,
+    `continueWhileLoading` ("Wait for the conversation to finish loading, then
+    pick a run to continue."). Hosts that translate the UI strings can override
+    it in `data-strings`; until they do, it shows in English. `UiStrings` gains
+    the key. The `strings` property and `data-strings` take a partial table, so
+    only code that builds a complete `UiStrings` object of its own has to add
+    it.
+  - A restore that will resume a run a navigating tool interrupted keeps
+    refusing a host's `sendMessage()`, as in 0.42.0, because that restore ends
+    by starting the run.
+
+  No host opt-in is needed: this applies to every element as soon as it is
+  upgraded. A host that sends on mount gets the conversation without changing
+  anything. The cost is that the composer queues for as long as each load
+  takes, and the load has no timeout of its own, so a request that hangs keeps
+  it queueing until the request fails. A store whose load rejects ends the wait
+  too, and what waited then goes out into the empty conversation the page is left
+  showing, so a custom store that rejects loses its stored copy to that send, as
+  a turn typed after the failure always has. The built-in remote store falls back
+  to its local cache on a failed fetch instead of rejecting.
+
+- **Clearing the conversation while a frontend tool waits no longer leaves a
+  "thinking" indicator in the next one.** A handler cannot be aborted, and a
+  confirmation card that is open when the run stops is declined, so the call
+  resumes after the conversation has been cleared. It then showed the run
+  waiting on its next round in whatever conversation had replaced it: the
+  indicator's answer group hid the greeting and the starter chips, and nothing
+  took it down until the next run there ended. This happened after New chat,
+  picking another thread from the drawer, deleting the active thread,
+  `reload()` and re-inserting the element, each with a handler still running
+  or a confirmation card open. A `user-key` handover already drew nothing there, as of 0.42.0.
+  Now the call draws nothing once the conversation it was dispatched in has
+  been cleared. Everything else it did is unchanged:
+  - Its card still settles as done, failed or declined.
+  - A failed navigating tool still clears its checkpoint from the thread it
+    was written to.
+  - Its result still goes to the run it belonged to, as after a Stop.
+
+  No host opt-in is needed: this applies to every element as soon as it is
+  upgraded, and nothing about the tool registry or its handlers changes.
+
+- **A microphone the browser grants but cannot record no longer fails silently.**
+  With `data-transcribe-url` set, the mic button asks for the microphone and
+  then builds a `MediaRecorder` on the stream. If the browser refuses that, as
+  Chromium does with `NotSupportedError` for a stream whose tracks have already
+  ended, the click ended in an unhandled promise rejection and the button stayed
+  idle with no message. Any track of the stream that was still live kept
+  running, so the browser's recording indicator stayed lit, and starting again
+  replaced the stream without stopping it. Now a recorder that cannot start is
+  treated as a refused microphone: the tracks are released, the button shows
+  "Transcription failed" as it does for a denied permission, and it stays idle,
+  ready to try again. The message reuses that existing string, so `UiStrings` is
+  unchanged.
+
+  No host opt-in is needed: this applies to every element as soon as it is
+  upgraded.
+
+### Changed
+
+- **`sendMessage()` resolves to whether it sent.** It returns
+  `Promise<boolean>` where it returned `Promise<void>`. It resolves `true` once
+  the turn was handed to the agent and the interaction settled, and `false`
+  when nothing was sent: an empty message, a run or a send already in flight, a
+  reload's resume, no `endpoint`, or a send dropped while it waited for a
+  restore. Code that ignores the result behaves as before, but type-checking
+  breaks wherever `sendMessage` is annotated, implemented, overridden or
+  replaced as returning `Promise<void>`: a wrapper's ref type declaring it, a
+  subclass override, and a test double that replaces it on the element all have
+  to return a boolean to type-check.
+
+## [0.42.0] — 2026-10-07
+
+### Fixed
+
+- **A send is in flight from the moment it is taken, not from when its run
+  starts.** A send draws its turn and dispatches `ag-ui-submit` before it asks
+  the client for a run, and only the run counted. So a `sendMessage()` from an
+  `ag-ui-submit` listener, or a second call in the same task, passed every
+  guard and went out as a second request on the same client, with the
+  listener's turn drawn between the user's turn and its answer. Both are now
+  refused, so a listener that sends hears the event once, and the built-in
+  Send queues in that time as it does during a run. A listener that stops the
+  send -- a new chat, a thread switch, a change of `user-key`, moving the
+  element -- now stops it before its request is made. It used to go out into
+  the conversation that replaced it, which after a change of `user-key` put one
+  principal's turn at the top of the next one's conversation.
+- **ArrowUp reaches a turn queued behind a run, and one sent to resume or
+  fork a run.** Arrow-key recall recorded only a turn the composer sent at
+  once. A turn typed while a run was going entered it only if Stop discarded
+  the queue, so ArrowUp skipped it while it waited and after the queue sent it.
+  A turn sent from the checkpoint panel never entered it, though it was typed
+  in the composer like any other. Both are now recorded as they leave the
+  composer, and a turn taken back from the queue stays recallable, as one Stop
+  declined to send already did. Stop no longer adds the queue again, so the
+  history holds each turn once. Queueing or continuing with a turn you walked
+  back to now starts the next walk from the newest turn, as sending one did.
+  Turns a host sends with `sendMessage` are still not recorded, and the purge a
+  change of `user-key` makes still clears them.
+- **Retry and a checkpoint pick keep the rules a send keeps.** `retryLastTurn()`
+  checked only for a run in flight. A Retry made before a send's run had
+  started, or while a picked checkpoint was in flight, started a second run in
+  the same conversation. A Retry is now refused in both cases. It also counts
+  from the call, as a send does, so a `sendMessage()` or a second Retry made
+  before its run starts is refused and the built-in Send queues. A pick made
+  before a send's or a Retry's run has started is now refused with the same hint
+  as a pick during a run. A conversation store, or an activity or tool renderer
+  the Retry redraws through, that starts a new chat or changes `user-key` now
+  stops it, and `retryLastTurn()` returns `false`. The Retry used to go ahead,
+  drawing the old conversation into the new one and asking its answer again.
+  One new refusal follows from the same rule: a Retry from an
+  `ag-ui-run-finished` listener for a picked checkpoint's run returns `false`,
+  because the continuation is still in flight when that event fires. A
+  `sendMessage()` from the same place was already refused for that reason.
+- **A recall walk ends on any write into the composer, not only on typing.**
+  Walking back to a past turn with Up and then quoting text, from the
+  transcript or from the page through `offerQuoteInPage`, or clicking a skill
+  chip that prefills the composer, left the walk running: the next Up replaced
+  what had just been written with an older turn, and Down emptied the box. The
+  walk now checks that the composer still holds the turn it put there, so any
+  other write ends it, including a host page writing the composer itself.
+- **A `user-key` changed while the element is out of the document now hands
+  over when it is inserted again.** The attribute was acted on only while the
+  element was connected, and inserting it again is a reload that keeps the
+  composer's recall on purpose. So removing the element, changing the key and
+  inserting it again left the previous principal's stored conversation in
+  `sessionStorage`, their turns one ArrowUp away, their Always allow waivers
+  live, their shared state seeded into the next principal's first run, their
+  unread count on the launcher, and their threads in a drawer left open.
+  Connecting now compares the key the element's state belongs to with the
+  attribute, and runs the handover a live change runs when they differ. The
+  first key to arrive is still an adoption rather than a purge, and a move that
+  keeps the key, a key that goes away and comes back while detached, and a
+  first connect hand nothing over.
+- **A Stop your own code makes while a turn is starting now stops it.** A
+  conversation store, a `getContext` or `getTools`, or the save that answers a
+  tool call left open, that started a new chat or changed `user-key` during a
+  send or a Retry stopped nothing: the request still went out into the
+  conversation being left, with all of its history. Nothing is sent now. On
+  `AgUiClient`, a `cancel()` from `onPersist`, `getContext` or `getTools` before
+  the request is honoured and fires `onCancelled` and `onSettled` as any Stop
+  does, and a `cancel()` with nothing in flight is still forgotten by the next
+  `send()` or `resume()`. A Retry stopped this way resolves `true`, because the
+  provider runs after the Retry has handed its turn to the client.
+- **A Retry whose save the store refuses leaves the conversation as it was.**
+  `truncateToLastUser()` shortened the history before saving it, so a store
+  that threw left the answer on screen but out of the next request, and the
+  agent was then asked a follow-up about an answer it was never told it gave.
+  It now saves first, so a refused save changes nothing, and `retryLastTurn()`
+  rejects with the store's error.
+- **A reload that resumes a run no longer lets a second run start beside it.**
+  A reload in the middle of a navigating tool's run resumes that run once the
+  conversation store answers, and with a remote store that answer is a real
+  request. A send, a Retry or a checkpoint pick made while it was out was not
+  refused: the send went out without the stored conversation and its save
+  replaced it, then the resume ran beside it on the same client, answering a
+  call the conversation no longer held. A restore that will resume now counts
+  as in flight from the moment it asks the store, so `sendMessage()` returns
+  without sending, the built-in Send queues the turn behind the resumed answer,
+  `retryLastTurn()` returns `false`, and a pick says why at the composer. New
+  chat while the store answers stands the resume down. A host calling
+  `sendMessage()` as the element connects, on a page a navigating tool
+  reloaded, now has that call refused, as it would be behind any run.
+- **A conversation restore stops where New chat, leaving the page or host
+  code stopped it.** A restore stood down only for a newer restore or, when it
+  was about to resume a run, for the Stop New chat makes; a restore with
+  nothing to resume holds nothing for a Stop to let go of. So New chat pressed
+  while a remote store was still answering drew the conversation being left
+  into the new chat, and the first turn sent there carried that whole
+  conversation. An element removed meanwhile ran the host's renderers for a
+  node no longer on the page. An activity or tool renderer that started a new
+  chat during the replay had the rest of the old conversation drawn into the
+  new one, and after a reload mid-run, a renderer, the store's save of the
+  checkpoint or `navigationResult` doing the same still let the resume go out,
+  answering the navigating call from the new chat. Once any of these happens,
+  the restore now draws nothing more and resumes nothing. The navigation
+  checkpoint such a stop leaves behind is forgotten, so coming back to that
+  conversation later answers its navigating call as not finished rather than
+  resuming it from whatever page is current then. When the element only left
+  the page, the checkpoint is kept, and the run resumes once the element is
+  put back. That holds after a `reload()` the host made while the store was
+  answering, too: a restore standing down for a newer restore of the same
+  conversation leaves the checkpoint to it, and the restore that resumes is
+  the one that clears it.
+- **A run stopped by a change of `user-key` no longer saves into the next
+  principal's storage.** The handover stopped the run, but a stopped run saves
+  what it had once its request closes, and by then the store had been purged
+  and scoped to whoever arrived. The previous principal's question and partial
+  answer were filed under their own thread id in the next principal's
+  namespace, and the history drawer listed a conversation titled with a
+  question the new user never asked. A tool result returned after the Stop, a
+  stopped checkpoint continuation, and a key changed while the element was
+  detached did the same. A state snapshot already read off the wire put the
+  previous principal's shared state back after the handover had emptied it, so
+  it went out on the next principal's first run. A client built before a
+  handover now writes nothing at all. A key's first arrival is still an
+  adoption, so a run in flight across it keeps saving into the namespace it
+  moved to, and New chat still files a stopped run's last save under the
+  conversation it left.
+- **A change of `user-key` no longer replaces a conversation store the host
+  assigned after the element connected.** Connecting remembered the element's
+  own store, and a later key change rebuilt that store under the new namespace
+  whether or not it was still the one in use. A store the host assigned to a
+  connected element was swapped for a `sessionStorage` one, and a
+  `RemoteConversationStore` built with `cacheMessages: false` to keep message
+  bodies off the client started caching every one of them in the tab. A store
+  the host assigned is now left alone whenever it was assigned, and scopes
+  itself. The one exception is unchanged: a plain `SessionStorageStore`
+  assigned before connecting is the same kind as the element's own default,
+  so the element still namespaces it as its own.
+- **A change of `user-key` clears the composer.** The transcript and recall
+  history were already cleared so the previous principal's words were not in
+  front of the next one, but a turn they had typed and not sent stayed in the
+  box, on a live change and on one made while detached. A handover now empties
+  the composer, which takes a quotation or a skill's template with it. It also
+  takes down the skill hint, closes a slash palette the text had opened, and on
+  a live change stops a voice recording in progress before it is transcribed.
+  The first arrival of a key, a move that keeps the key, and New chat leave the
+  text where it is.
+- **A tool call whose run was stopped or handed over while it waited no longer
+  acts afterwards.** Dispatch awaited the host's `confirmPredicate`, the
+  confirmation card and the handler, and checked after none of them whether
+  the run was still going. A predicate that answered after Stop opened its
+  card or ran its handler for a run the user had ended, and a Confirm clicked
+  in the same task as Stop still ran the call. Across a change of `user-key`,
+  the previous principal's handler ran on the next principal's page, a
+  navigating tool's checkpoint went into the next principal's storage, and a
+  handler failing after the handover cleared their checkpoint instead of its
+  own. Such a call now settles as not finished and posts nothing, so the next
+  request answers it as not finished, and after a handover it draws and
+  writes nothing. Both checkpoint writes go to the thread the call was
+  dispatched under. A plain Stop while a handler runs still keeps its result,
+  since that action did happen on the page.
+- **A voice clip that comes back after a change of `user-key` is dropped, not
+  written into the next principal's composer.** The mic checked whether it had
+  been taken down only before it posted the clip, so a transcript already on
+  its way when the key changed landed in the composer the change had just
+  emptied, and a failed one drew its error on the old button. The permission
+  prompt had the same gap: a mic granted after the key changed or the element
+  left the page started a recording nobody could see or stop, and its tracks
+  were never released, so the browser's recording indicator stayed lit.
+  Removing the element while a clip transcribes now drops that clip too, as
+  removing it mid-recording already did, and that holds for a move that keeps
+  the key.
+
 ## [0.41.3] — 2026-10-07
 
 ### Fixed
@@ -4250,7 +4551,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.41.3...HEAD
+[Unreleased]: https://github.com/Artui/ag-ui-web-component/compare/v0.43.0...HEAD
+[0.43.0]: https://github.com/Artui/ag-ui-web-component/compare/v0.42.0...v0.43.0
+[0.42.0]: https://github.com/Artui/ag-ui-web-component/compare/v0.41.3...v0.42.0
 [0.41.3]: https://github.com/Artui/ag-ui-web-component/compare/v0.41.2...v0.41.3
 [0.41.2]: https://github.com/Artui/ag-ui-web-component/compare/v0.41.1...v0.41.2
 [0.41.1]: https://github.com/Artui/ag-ui-web-component/compare/v0.41.0...v0.41.1

package/README.md

@@ -305,13 +305,56 @@ 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 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.
+palette, a prompt fired when your page mounts the chat, or a composer of your own replacing the
+built-in one.
+
+It returns a `Promise<boolean>`. It resolves `true` once the turn has been handed to the agent
+and its run has settled, frontend-tool rounds included, and `false` when nothing was sent:
+
+- for an entirely empty message;
+- while a run, or a checkpoint continuation picked from the panel, is in flight. A continuation
+  counts from the pick, and a send from the call rather than from when its run starts, so a
+  `sendMessage` from an `ag-ui-submit` listener, or a second call in the same task, is refused
+  rather than starting a second run;
+- with no `endpoint` set, which the transcript also says;
+- while a reload resumes a run a navigating tool interrupted. The resume counts from the moment
+  the element asks its conversation store for the conversation, and it ends by starting that
+  run, so a send then is refused, and the built-in Send queues behind the resumed answer;
+- when your own code that runs on the way to the request — an `ag-ui-submit` listener, the
+  conversation store's save — stops it by starting a new chat or changing `user-key`. A
+  `getContext` or `getTools` that does the same stops it too, but after the turn was handed
+  over, so the call resolves `true`.
+
+**While the element restores a stored conversation, a send waits for it.** Every restore —
+when the element connects, on `reload()`, when a thread is picked from the drawer, and when
+`user-key` changes from one principal to another — first asks the conversation store for the conversation, and with
+`data-threads-url` that is a request to your server. A `sendMessage` made in that time waits
+until the conversation is drawn, then sends with it: the bubble, the `ag-ui-submit` event and the
+request all come after the replay, later than the call by the length of the load. So a prompt
+fired on mount needs no timing of its own. If New chat, a thread switch, a change from one
+`user-key` to another or a `reload()` comes while it waits, the conversation it was addressed
+to is gone, so it is dropped and resolves `false` at once. The element leaving the page drops it
+too, but it resolves `false` only once the load answers or the element is inserted again. A
+first `user-key` on an anonymous conversation adopts that conversation rather than replacing
+it, so a send waiting then still goes out. A second `sendMessage` while one waits is refused. The built-in Send queues what is typed during the load ("Waiting to send"),
+and sends it after the conversation is drawn, behind a `sendMessage` that was waiting.
+
+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.
+
+`retryLastTurn()` keeps the same rules, because it starts a run on the same conversation. It
+returns `false` while a run, a send, another Retry or a continuation is in flight, and while
+any restore of the stored conversation is still loading. It does not wait for the load as a send
+does: until the conversation is drawn there is nothing on screen to retry, and afterwards it
+would ask the previous visit's last question again. It counts from the call as a send does: until its run starts, a `sendMessage` or a
+second Retry is refused, the built-in Send queues, and a checkpoint pick is refused. It also
+returns `false` when your own code stops it before its run starts: a conversation store, or an
+activity or tool renderer it redraws through, that starts a new chat or changes `user-key`. A
+`getContext` or `getTools` that does the same stops it too, before anything is sent, but it runs
+after the Retry has handed its turn to the client, so the call resolves `true`. A store that
+throws from the Retry's save leaves the conversation as it was, and `retryLastTurn()` rejects
+with its error.
 
 `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
@@ -482,9 +525,10 @@ function Assistant() {
 
 Writing it as `<ag-ui-chat ref={...} />` in JSX and configuring in the ref callback mostly works —
 the catalog requests are held back one microtask precisely so a ref assigned in the same commit is
-honoured — but the thread-history request is **not** deferred (a deferred replay could land after a
-`sendMessage()` and duplicate the transcript), so that one goes out with whatever was configured at
-insertion.
+honoured — but the thread-history request is **not** deferred, so that one goes out with whatever
+was configured at insertion. It starts at insertion because the restore is what a `sendMessage()`
+from the same commit waits on: a restore that had not started yet would have nothing to hold it,
+and the send would go out without the conversation.
 
 If your credentials can only arrive later still — an awaited token, a passive effect — call
 **`reload()`** once they land:
@@ -655,7 +699,10 @@ AG-UI has no server-side cancel route: cancelling **aborts the streaming request
 `cancel()` with no run in flight is a safe no-op. `newChat()` cancels any in-flight run before
 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.
+these end it too. So does a turn that has not made its request yet: called from host code a send
+or a resume runs on the way — the conversation store's save, `getContext`, `getTools` —
+`cancel()` stops it before anything is sent, and `onCancelled()` and `onSettled()` fire as for any
+other Stop.
 
 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
@@ -717,7 +764,8 @@ Whether a call is gated is decided in this order:
    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.
+   error goes to the console, never to the endpoint. A predicate still pending when the run is
+   stopped decides nothing: the call does not run, and its card settles as not finished.
 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.
@@ -1078,7 +1126,10 @@ matching JS API:
   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. Focus moves to the composer, whichever control started the new chat, unless the
-  widget is collapsed, and the page is not scrolled to it.
+  widget is collapsed, and the page is not scrolled to it. A restore still loading or replaying
+  the conversation being left stops there, so nothing of it is drawn into the new chat, and a
+  run it was about to resume after a reload is not resumed: coming back to that conversation
+  later answers the interrupted call as not finished.
 - `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.
@@ -1110,17 +1161,24 @@ 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
-opposite of what stopping meant. It is not thrown away, though — a queued
-message has already left the composer, so it goes to the front of the recall
-history below rather than nowhere.
+opposite of what stopping meant. Nothing is lost, though — a queued message
+entered the recall history below when it left the composer, so **Up** gets it
+back after a Stop, and after its chip is taken back.
 
 The composer also walks back through what you have already sent, on **Up** and
-**Down** — the shape every shell and every coding agent uses. Only from an empty
-composer and only with the skills palette closed: an arrow inside text is how you
-move the caret, and taking it unconditionally would break editing to add a
-shortcut. Arrowing forward past the newest turn empties the box again, so the way
-out is the key that got you in. The history is this conversation's: starting a
-new chat, switching threads or changing `user-key` clears it with the transcript.
+**Down** — the shape every shell and every coding agent uses. It holds every turn
+that left the composer: one sent at once, one queued behind a run (from the
+moment it is queued), and one sent to resume or fork a run from the checkpoint
+panel. A message sent with `sendMessage` is not in it, because it was never
+typed there. Only from an empty composer and only with the skills palette closed:
+an arrow inside text is how you move the caret, and taking it unconditionally
+would break editing to add a shortcut. Arrowing forward past the newest turn
+empties the box again, so the way out is the key that got you in. A walk lasts
+only while the composer holds the turn it put there: anything else that writes
+the box — typing, a quotation, a skill, dictation, or the host page itself — ends
+it, so the next arrow moves the caret in what was written rather than replacing
+it. The history is this conversation's: starting a new chat, switching threads
+or changing `user-key` clears it with the transcript.
 
 ### Collapsing to the launcher
 
@@ -1858,7 +1916,7 @@ chat.addEventListener("ag-ui-feedback", (e) => {
   analytics.track("assistant_rating", e.detail); // { content, rating }
 });
 
-await chat.retryLastTurn(); // false when there is nothing to ask again
+await chat.retryLastTurn(); // false when there is nothing to ask again, a run is in flight, or a restore is loading
 ```
 
 ## Quoting a selection
@@ -2091,6 +2149,16 @@ waived with *Always allow* are forgotten with it, so the next principal is asked
 sent on the next principal's first run, so a host that seeds shared state assigns it again for the
 principal who arrived.
 
+A handover also ends what the previous principal had in flight. Their run is stopped, and nothing
+it does afterwards is written into the next principal's storage or shared state: not the save a
+stopped run makes once its request closes, not a tool result that comes back after the Stop, not
+state already on its way. A tool call still waiting on `confirmPredicate` or its confirmation card
+does not run, one whose handler is still running draws nothing when it returns, and a navigating
+tool's checkpoint is never written into the next principal's thread. What they had typed into the
+composer and not sent is cleared with the transcript, quotations and skill templates included. A
+voice recording in progress is stopped before it is transcribed, and a clip already sent for
+transcription is dropped when its transcript comes back.
+
 Set it live, from script, as part of signing out or in:
 
 ```js
@@ -2102,10 +2170,17 @@ out through its own router without remounting anything, so the host naming the n
 dropping the attribute — is the only signal the element will ever get. Removing the attribute
 purges too, so a sign-out that simply clears it is safe.
 
+It holds for an element that is out of the document too, such as a view a router keeps alive.
+Nothing is purged while it is detached: the handover runs when it is inserted again, against the
+key it has by then, so a key that changes and changes back while detached hands nothing over. An
+element that is never inserted again leaves the previous principal's conversation in
+`sessionStorage` under their key, where only an element naming that principal again can reach it.
+
 The **first** value to arrive is treated as a host naming the user who was already there, not as a
 handover: the conversation in progress moves into the principal's namespace instead of being
 destroyed. So an element configured by an async auth handshake — the shape described in
-[Framework hosts](#framework-hosts-configure-before-you-insert) — keeps what is on screen.
+[Framework hosts](#framework-hosts-configure-before-you-insert) — keeps what is on screen,
+including a run still streaming and whatever is in the composer.
 
 Two things it deliberately does not do. It does not scope the panel's own collapsed / dragged-size
 / theme preferences, which are this element's UI state and carry no conversation content. And it
@@ -2141,6 +2216,15 @@ chat.conversationStore = new RemoteConversationStore(
 );
 ```
 
+A conversation store you assign yourself is never replaced by a change of `user-key`, whether you
+assign it before the element connects or after. The one exception is a plain `SessionStorageStore`
+assigned before the element connects: that is the same kind as the element's own default, which is
+all connecting can see, so the element namespaces it as its own and moves it on every key change.
+Assign it after connecting, or wrap it, to keep it yours. A store that keeps its data somewhere
+the element cannot see has to scope itself; the element purges only its own `sessionStorage`
+namespace and clears what is on screen. If your store wraps a `SessionStorageStore`, build a new
+one per principal.
+
 `SessionStorageStore.purge(namespace)` is the same primitive the element uses, for a host driving
 its own store from its own sign-out path.
 
@@ -2424,6 +2508,11 @@ 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.
 
+Picking a row while a stored conversation is still loading is refused the same
+way, with a hint asking you to wait for the load: a continuation sends only the
+new turn, so it must not start before the history it continues is on screen. The
+wording is the `continueWhileLoading` string.
+
 ### One URL, three endpoints
 
 `data-runs-url` is the only thing to configure. `resume/<id>/` and `fork/<id>/`