@artooi/ag-ui-web-component 0.27.0 → 0.29.0

package/CHANGELOG.md

@@ -7,6 +7,666 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.29.0] — 2026-08-29
+
+### Added
+
+- **Quote a selection into the composer.** Selecting text in the transcript now
+  floats a **Quote** offer beside it; taking it drops the selection in as a
+  markdown blockquote and leaves the caret on a fresh line under it. Nothing is
+  sent -- a quotation is how a question narrows to one part of an answer, so the
+  question still has to be written. Quoting appends, so a second quotation is a
+  second thing being asked about. Long selections cap at 500 characters.
+  `data-quote-selection="false"` turns the offer off; the `quote-selection`
+  `::part()` styles it.
+
+  **The half worth having is the one the transcript cannot reach.** A chat
+  mounted beside a table, a diff or a report sits in the surface the user
+  actually works in, and a selection made *there* is one no hosted chat can see.
+  `offerQuoteInPage()` extends the same select-then-offer gesture to the host's
+  own page, or to one region of it, and `quote(text)` is the seam underneath for
+  a deliberate trigger like a per-row "ask about this" button.
+
+  **The page half is a method rather than a documented recipe, and that is the
+  correction, not the design.** It shipped first as four lines in the README --
+  quote every settled selection -- which appends to the composer on every drag
+  the user made to *read*, to copy, or to fix a typo. Worse, it cannot tell a
+  selection in the page's prose from one inside the user's own half-typed
+  `<input>`: Chrome reports a field's internal selection through
+  `document.getSelection()` as an ordinary range over the field's **wrapper**,
+  so the text reads back perfectly and nothing about the range says where it
+  came from. The only signal is `document.activeElement`. That guard, plus
+  skipping the widget's own transcript -- which needs the *event path*, since
+  `Node.contains` is false across a shadow boundary -- plus retiring a
+  fixed-position affordance on scroll, is three non-obvious guards, and three
+  guards is a feature rather than a snippet. `attachQuoteOffer` is exported for
+  a host that wants it without the element.
+
+  **A selection across several elements is not a paragraph, and was treated as
+  one twice over.** The offer was hung off the selection's *bounding box*, whose
+  centre belongs to no line -- a drag from a form's left column down to a
+  full-width line running under the chat panel put the offer on the panel,
+  pointing at a line the user had never looked at. It now hangs off the line the
+  gesture ended on, or the first line for a keyboard selection. And the text was
+  read with `Range.toString()`, which concatenates text nodes and asks nothing
+  about CSS: quoting a form returned the values of every `<option>` in a closed
+  `<select>`, the markup's own indentation on every line, and a blank `>` for
+  every gap between elements -- twenty-four lines of which twelve were empty.
+  The read is now what the engine says is rendered (`checkVisibility`), with the
+  whitespace a collapsing `white-space` collapses, and preformatted text passed
+  through so a quoted code block keeps its shape. Four leading spaces inside a
+  blockquote is a markdown code block, so this was a rendering defect and not
+  only an untidy one.
+
+  Reading a selection out of a shadow tree is the part that takes care, and the
+  component now does it properly: engines disagree about what
+  `document.getSelection()` reports for a selection made inside a shadow root,
+  and `getComposedRanges` is used where the engine has it, with the direct read
+  behind it. `quotableSelection`, `asQuote` and `MAX_QUOTE_CHARS` are exported
+  for a host with the same problem in its own component.
+
+- **`approveWithEdits` — edit a gated call's arguments before approving it.**
+  AG-UI's resume payload carries `editedArgs` and the protocol gates it on the
+  agent's `approveWithEdits` capability; the approval card could not offer it.
+  It now shows the call's arguments as editable JSON.
+
+  **Off by default, and an assertion about the server rather than a
+  negotiation.** Capabilities are not on the wire this component reads, so it
+  cannot check — and turned on against a server that ignores `editedArgs`, a
+  user would edit arguments it silently discards, which is worse than not
+  offering.
+
+  `editedArgs` rides the payload **only when something actually changed**, so a
+  server can tell "approved as proposed" from "approved, but like this" without
+  diffing what it sent. Unparseable JSON, or JSON that is not an object, keeps
+  the card open with the reason on it rather than approving the original behind
+  the user's back. Offered only for an interrupt naming a call this component
+  holds a card for, since the card is where the arguments still are.
+
+  New `::part()`s `approval-edit`, `approval-args`, `approval-error`, and three
+  strings.
+
+- **`formatRelativeTime` — replace the drawer and checkpoint timestamps.** There
+  is no `Intl` anywhere in this component, and the locale-neutral `"5m ago"` is
+  deliberate: guessing a locale would disagree with the host page, and being
+  wrong in a second language is worse than being neutral in one. That is a good
+  default and a bad requirement, and a host previously could not even reach the
+  formatter to replace it.
+
+  `relativeTime` and the `RelativeTimeFormatter` type are now exported, and the
+  formatter is read at render rather than at connect, so setting it after mount
+  works.
+
+
+- **Server-pushed follow-up suggestions.** A `suggestions` activity draws its
+  prompts as chips; clicking one sends it as the user's message. Registered
+  skill chips are static and host-configured, so they can say "summarize this"
+  but never "want me to update the shipping address too?" after a tool has run.
+
+  Rides the activity envelope charts already use rather than a `CUSTOM` event,
+  which buys persistence for nothing: chips are content, so a reload puts them
+  back, and a set pushed under an id already on screen replaces that row.
+
+  Bounded at 4 prompts of 120 characters, mirroring django-ag-ui's
+  `suggestions_activity()`. The producer *raises* past those bounds while this
+  side silently drops — deliberate asymmetry, because the producer can report
+  the problem and the client cannot. Both numbers live on both sides for the
+  reason the chart bounds do: mirroring only some of them leaves exactly the
+  silent-drop hole they exist to close.
+
+  New `::part()`s `suggestions` / `suggestion-chip`, new
+  `SUGGESTIONS_ACTIVITY_TYPE`, and `renderSuggestionChips` / `suggestionPrompts`
+  exported for a host drawing its own.
+
+
+- **A message action row — copy, retry, thumbs up/down — under every finished
+  assistant message.** There were **zero** message-level actions before this;
+  `attachCopyButtons` handled fenced code and nothing else.
+
+  **Retry is the item that earns it.** History truncates to the most recent user
+  message inclusive and the run repeats, so the agent answers the question it was
+  asked rather than being told its last answer was wrong. It sits on the **last**
+  answer only: re-running an older turn is branching, and for a page-driving
+  agent editing a past turn is not neutral, because those turns clicked buttons.
+  `retryLastTurn()` is public for a host driving its own message UI.
+
+  A retried turn **re-runs its tools**, which the previous attempt already ran.
+  Confirmation still applies, so a destructive tool asks again unless the user
+  waived it this session.
+
+  Ratings fire `ag-ui-feedback` and **store nothing**: a rating belongs to
+  whatever the host already uses for product signal, and a write-only table
+  inside a chat widget is a schema nobody reads.
+
+  New `::part()`s `message-actions` / `message-action` (plus
+  `message-action-retry`, `-copy`, `-up`, `-down`), new `FEEDBACK_EVENT` and
+  `FeedbackDetail`, and `attachMessageActions` / `messageActionBar` exported for
+  a host assembling its own transcript.
+
+- **A dropped run has a way back.** `ConnectionLostError` rendered a dead
+  "Connection lost" bubble; only *uploads* had retry. The failed bubble now
+  carries the same action row, with Retry and Copy and no rating — error text is
+  what people paste into a bug report, while "the connection dropped" is not a
+  statement about answer quality and mixing it into feedback makes that signal
+  say less.
+
+  **Kept as an error rather than demoted to a run notice**, which is what was
+  originally proposed. `renderRunNotice`'s contract is that a notice "never
+  settles, takes no action, and carries no controls" and is "distinct from an
+  error, which is a failure". This is a failure that now needs a control, so the
+  taxonomy already had the answer.
+
+
+- **"Always allow" on the confirmation card — a session-scoped waiver, per tool
+  name.** Confirmation was binary and permanent: `autoConfirm` is
+  all-or-nothing and `confirmPredicate` has no memory, so a tool the user
+  approves every single time keeps asking every single time.
+
+  A prompt approved nearly every time is not a decision, it is a speed bump, and
+  the reflex it trains is what makes the rare refusal easy to miss. Anthropic
+  published that users approve **~93%** of Claude Code permission prompts
+  manually and called interactive confirmation *"behaviorally unreliable as a
+  sole safety mechanism"* on exactly that basis. The waiver exists so the
+  prompts that remain still mean something.
+
+  **The button appears only where the `x-destructive` default is what gated the
+  call.** `confirmPredicate` is documented as authoritative, so letting one
+  click retire it would silently defeat a host policy — and because the offer
+  and the allowlist sit on the same path, there is no dead button either. 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.
+
+  New `::part()` `confirm-always`, new string `confirmAlways`, and
+  `requestConfirmation` gains an `onAlwaysAllow` option — its presence is what
+  renders the button, so the affordance can never appear with nothing listening.
+  The card still resolves `true`: the waiver is *in addition to* approving this
+  call, not instead of it.
+
+
+- **`ag-ui-invalidate` and `RunFinishedDetail.invalidated` — the agent tells your
+  page what it moved.** The agent writes and the page still shows the old list.
+  `ag-ui-run-finished` already said *something* moved, so this is **precision on
+  a channel that ships**: the server names the resources and a host refetches
+  only those.
+
+  ```js
+  chat.addEventListener("ag-ui-invalidate", (e) => {
+    if (formIsDirty()) return showBanner("This data changed.", e.detail.keys);
+    refetch(e.detail.keys);
+  });
+  ```
+
+  **Do not reload on this.** The user was probably typing, and an
+  agent-triggered reload into a live form destroys unsaved input with no
+  explanation the user can see. The component never reloads by itself and offers
+  no option that would.
+
+  **Two dispatches, deliberately.** The live event fires as each announcement
+  arrives, which is what makes a long multi-step run feel live -- the list
+  refreshes as the third of eight writes lands. `invalidated` on the existing
+  run-finished detail carries the same keys de-duplicated at the end, so a host
+  already listening there upgrades by reading one extra field:
+
+  ```js
+  if (detail.invalidated.length > 0) refetchOnly(detail.invalidated);
+  else if (detail.tools.some((t) => t.side === "server")) refetchEverything();
+  ```
+
+  That `else` is the whole compatibility story. A new server with an old client
+  has its `CUSTOM` event ignored and still gets the coarse refetch; an old server
+  with a new client leaves `invalidated` empty and falls through to the same
+  branch. Nothing negotiates, which is what makes this shippable across repos
+  with independent release cadences.
+
+  **Keys are opaque and matching is exact.** `orders/42` does not imply `orders`
+  -- a prefix rule would be this component guessing at a scheme it does not own,
+  and `orders/1` would match `orders/11`. A server that wants the collection
+  refreshed names it. Hosts may match hierarchically in their own vocabulary,
+  where the scheme is known.
+
+  Built on the `CUSTOM` carrier rather than `ACTIVITY_SNAPSHOT`, because an
+  invalidation is an imperative: activities are materialised into messages,
+  persisted and replayed on every thread restore, and an invalidation replayed on
+  every thread load is a refetch storm. Nothing is rendered or persisted, and
+  that absence is asserted. Every other `CUSTOM` name still arrives on
+  `ag-ui-custom` unchanged, and an invalidation does **not** also fire it -- a
+  host listening to both would otherwise refetch twice for one announcement.
+
+  Requires django-ag-ui 0.51 to have anything to receive.
+
+- **`registerActivityRenderer` — `activityType` is an open set now, not two
+  branches.** AG-UI leaves exactly two payload names an open string the protocol
+  does not enumerate, and the component treated neither as open: `chart` and
+  `compaction` were handled and everything else fell through a bare `return`,
+  with no host seam and no record that anything had arrived. The server could
+  only say things the client had been compiled to understand, in a protocol
+  designed so it can say more.
+
+  ```js
+  chat.registerActivityRenderer({
+    type: "build_status",
+    render: (content) => {
+      const el = document.createElement("div");
+      el.textContent = `Build ${content.status}`;
+      return el;
+    },
+  });
+  ```
+
+  `render` carries the same contract as a client tool's `render`, and for the
+  same reason rather than by analogy: activities are materialised into
+  `role: "activity"` messages, persisted with the transcript and re-fired on
+  restore, so a renderer that writes to the page instead of returning DOM fires
+  again on every thread load.
+
+  **Both built-ins go through the registry**, which is the test that the seam is
+  real — a built-in needing a privileged branch would mean the seam cannot
+  express what the component itself needs. Registering either name replaces it.
+
+  Compaction gains two things by going through the seam: a reload puts the
+  notice back (it is content, and content replays), and a server redrawing under
+  the same `messageId` replaces it instead of leaving two notices standing for
+  one event.
+
+- **`unhandledActivityTypes`** — the activity types that arrived with nobody
+  registered to draw them. Deliberately the only trace: ignoring an unknown name
+  is the protocol's own answer, and a warning would fire on every
+  forward-compatible server, but "nothing happened and nothing was said" is
+  impossible to debug. Note `chart` is listed until `enableCharts(["activity"])`
+  is called, which is the honest answer to "I pushed a chart and nothing
+  happened".
+
+- **`ag-ui-custom`** (`CUSTOM_AGENT_EVENT`, detail `CustomAgentDetail`) — the
+  other open carrier, which had no implementation at all. An AG-UI `CUSTOM`
+  event is forwarded to the host page whole and uninterpreted, `bubbles` and
+  `composed` like every other event the element dispatches.
+
+  **It is deliberately not rendered, persisted or replayed.** That asymmetry is
+  the rule for choosing between the two carriers: `ACTIVITY_SNAPSHOT` is content
+  and has a place in the conversation, `CUSTOM` is an imperative with no meaning
+  once acted on, and replaying "refetch the board" on every thread load would be
+  a bug rather than a feature.
+
+  **Note:** pydantic-ai emits its own compaction activity under
+  `pydantic_ai_compaction`, by a different route than the harness sink this
+  package renders as `compaction`. The registry deliberately does **not** answer
+  to both names — doing so would give a deployment running both two notices for
+  one event. It shows up in `unhandledActivityTypes` instead, so a host that
+  wants it can register it and decide about duplication itself.
+
+### Fixed
+
+- **The message action row sat closer to the block below it than to the message
+  it acts on.** The answer group is a flex column with a 10px gap, so the row's
+  `margin-top: 6px` **added** to that gap instead of tightening it: 16px above,
+  10px below, and the buttons read as belonging to whatever card followed. A
+  negative margin pulls the row back inside the gap — 4px above, 10px below.
+
+  Found by driving the demo, not by any assertion: every existing check was
+  satisfied by the broken spacing. Ordered correctly, contained correctly,
+  visible — and grouped with the wrong thing. The new browser case fails against
+  the previous stylesheet with `expected 16 to be less than 10`.
+
+
+- **The action row is a sibling of the message bubble, not a child.** Inside, the
+  buttons join the bubble's `textContent` — which is what Copy reads, what
+  history persists, and what every existing assertion about a message's text
+  compares against. An answer would have been copied back carrying the glyphs of
+  the buttons that copied it. Caught by twelve existing tests failing at once,
+  which is the check working.
+
+
+- **The confirmation card's action row could push a button outside the card.**
+  It was a `justify-content: flex-end` flex line with no wrap, built when there
+  were two buttons. Measured in Chromium at a 260px panel: the three buttons want
+  71 + 107 + 81 plus two 8px gaps against a 200px row, and the overflow went off
+  the **left** edge — Cancel rendered, styled and reporting its label, 27px
+  outside the box the user can see and hit.
+
+  `flex-wrap: wrap` lets the row take a second line instead, as the checkpoint
+  row already does. Found by measuring rather than by review: happy-dom lays out
+  no boxes and answers 0 for every width, so it called the overflowing row and
+  the fitting one the same pass. The new browser test fails against the previous
+  stylesheet at that width and passes at the two wider ones, which is the honest
+  shape of the bug.
+
+
+- **A server that replaced the conversation did it in silence.** AG-UI's
+  `MESSAGES_SNAPSHOT` is applied by `@ag-ui/client` before any subscriber runs,
+  so `agent.messages` **is** the server's list by the time the host sees
+  anything — and the run loop persists `agent.messages`. The replacement
+  therefore reached the conversation store either way, while the DOM was
+  untouched. Nothing looked wrong until a reload, in a later session, served a
+  transcript the user had never seen, with no event that could be correlated to
+  it. That is not reported as a bug; it is reported as "the chat lost my
+  messages".
+
+  The store still follows the server, deliberately — the server is authoritative
+  about what the conversation *is*, and it would follow it regardless. What
+  changes is that the replacement is now announced in the transcript.
+
+  **Re-rendering from the snapshot was the other candidate and is declined.** A
+  snapshot can land mid-run, and rebuilding the transcript then destroys the
+  in-flight run's own state: the streaming bubble, the open answer group, and
+  every tool card keyed by call id, some still waiting on results. This is the
+  same answer the same question already got for compaction.
+
+- **One string-valued point silently dropped a whole chart that was on screen.**
+  `chartSpecFrom` returns `null` for the entire spec when any point is not a
+  finite number — not the offending series, the whole chart — and the pushed
+  activity path then removed any chart already rendered and returned, with no
+  `console` call anywhere on that path. The triggering shape is not exotic: a
+  Django `Sum` over a `DecimalField` serialises as a JSON string, and money is
+  the most common chart input there is.
+
+  **Removing it is still right** and is unchanged: leaving retracted numbers on
+  screen reading as current is worse, and a reload drops the chart anyway
+  because the *stored* content is the version that could not be drawn. Live and
+  reload should agree. What was wrong was doing it silently. The path now warns
+  on the console naming the likely cause, and posts a notice in the transcript
+  when a chart that had been drawn is taken away.
+
+  Nothing is coerced, client-side or server-side. `django-ag-ui` already raises
+  at construction and names `Decimal` on purpose, and guessing whether
+  `"1234.50"` lost precision upstream is not a favour worth doing.
+
+
+- **A screen reader re-announced the whole answer tens of times per turn.** The
+  transcript carried both `role="log"` and an explicit `aria-live="polite"`,
+  and the streaming bubble's `innerHTML` is replaced inside it on every
+  animation frame. `role="log"` already implies polite announcement and the
+  default `aria-relevant` includes text additions, so every frame was a fresh
+  announcement of the answer so far. That is not merely unhelpful; it is
+  hostile.
+
+  The transcript is demoted out of live-region duty with an explicit
+  `aria-live="off"`, which overrides the value the role implies. **The role
+  stays** -- the log semantics are what let the transcript be navigated as one,
+  and only the announcing was the defect.
+
+  A separate visually-hidden status region takes over, and roughly four short
+  statuses land per turn: responding, answered, a decision is waiting and how
+  many, stopped, failed. Five new `strings` keys (`announceResponding`,
+  `announceAnswerReady`, `announceAwaitingDecision`, `announceStopped`,
+  `announceFailed`) make all of them translatable. The answer's own words never
+  reach it, and neither does an exception's.
+
+- **The transcript could not be read while anything streamed.** Eleven separate
+  sites assigned `scrollTop = scrollHeight` unconditionally, and nothing in the
+  element listened for a `scroll` event -- so nothing knew the reader had
+  scrolled up, and scrolling back during a run was undone by the next token.
+
+  All eleven now follow the foot only while the reader is already there. A
+  **jump-to-latest** button (`jump-latest` part, `jumpToLatest` string) appears
+  once they have scrolled away *and* have since missed something; scrolling up
+  through a settled transcript is not a reason to nag. A user's own message
+  still goes to the foot -- pressing Send is as deliberate as pressing the
+  button. `overflow-anchor: none` stops the browser's own scroll anchoring
+  competing for the same job.
+
+- **A strict-CSP host got an unstyled widget.** The stylesheet was injected as
+  an inline `<style>`, which a host with a strict `style-src` and no
+  `'unsafe-inline'` drops silently: the component mounted, functioned, and
+  rendered with no styling at all, and nothing in the console pointed at why.
+  It is attached with `adoptedStyleSheets` instead, which carries no
+  inline-style origin.
+
+  The sheet is per instance rather than shared at module scope. A shared one
+  would also stop re-parsing the stylesheet once per mount, but a module-level
+  singleton is what this package forbids, and per instance is no worse than the
+  `<style>` it replaces.
+
+  All three came out of a **survey of how other products build chat**, not a
+  review. Two review passes and a full audit wave went over this component
+  without surfacing any of them, because each is invisible unless you ask how
+  everyone else does it.
+
+## [0.28.0] — 2026-08-26
+
+### Added
+
+- **A conversation could carry from one signed-in user to the next in the same
+  tab.** New `user-key` attribute (and matching `userKey` property): set it to
+  whatever identifies the signed-in principal, and the stored conversation is
+  scoped to them, so two principals in one tab cannot reach each other's
+  transcript. Changing it — or clearing it — purges everything the previous
+  principal left behind under this element: the transcript, the history drawer
+  index and any navigation checkpoint. That purge is why it is a live attribute
+  rather than a connect-time one: `sessionStorage` is scoped to the tab and not
+  to the session, so it survives the navigation a logout is, and a single-page
+  app signs out through its own router without remounting anything — the host
+  naming the new principal is the only signal there is. The first value to
+  arrive is treated as a host naming the user who was already there rather than
+  as a handover, so an element configured by an async auth handshake keeps the
+  conversation on screen. Absent, behaviour is exactly what it was, including
+  that carry-over; the README says so where the attribute is documented.
+  `SessionStorageStore.purge(namespace)` exposes the same primitive for a host
+  driving its own sign-out.
+
+- **Pointing history at a server still left a full copy of every transcript in
+  the browser.** `RemoteConversationStore` mirrored each message body into
+  `sessionStorage` whatever the deployment had chosen, so an operator who
+  configured `data-threads-url` precisely to keep conversations in the database
+  got them in both places. The mirror is now a `cacheMessages` constructor
+  option, exposed on the element as `data-threads-cache="false"`, and it still
+  defaults to the caching behaviour so nobody's setup changes silently. Turning
+  it off keeps only the client-only state — the active thread id and the
+  navigation checkpoint — so reloads and navigating tools work as before; what
+  it costs is the offline fallback, since there is no longer a local copy to
+  fall back to.
+
+- **`UiStrings.recordingLimit`** — what the mic button says after a recording
+  stopped itself at the length cap. Token: `{n}`, the cap in minutes. Like every
+  other key it has an English default, so an existing `strings` override keeps
+  working untouched.
+
+- **`trustedOrigins` on the agent factory options** — the origins, besides the
+  document's own, the agent may carry host credentials to. Naming one confirms
+  the destination was chosen deliberately and silences the notice above for it.
+  Compared as serialized origins (`https://agent.example.com`), scheme and port
+  included. Reachable through a custom `agentFactory`, which is how a host wraps
+  `createHttpAgent` today.
+
+- **`trustedOrigins` on the element** — the origins, besides the page's own, that
+  every one of its seven configurable URLs may carry host credentials to without
+  a console notice. Forwarded to the agent factory as well, so a host that does
+  not override `agentFactory` configures all seven in one place.
+
+### Changed
+
+- **`parseToolCatalog` returns whole catalog entries, not bare summaries.** Its
+  return type was `Record<string, string>`, so the `description` field that
+  `ToolCatalogEntry` declares and documents was dropped at parse time for every
+  entry — a documented wire field no consumer could reach, and none could be
+  added without changing this signature first. It now returns
+  `Record<string, ToolCatalogEntry>`. Tool-call cards still label themselves from
+  `summary`; callers of the exported parser get the entry the server actually
+  sent. A malformed `description` costs that field, not the entry, matching the
+  tolerance the rest of the parse already had.
+
+### Fixed
+
+- **A reasoning block lost its last sentence, and a short one never appeared at
+  all.** The protocol client hands a delta subscriber the text accumulated
+  *before* the delta it is announcing, so following that callback alone trails
+  the stream by one and renders nothing whatsoever for reasoning that arrives as
+  a single delta. The answer text was spared because its own end event carries
+  the whole message; reasoning subscribed to an end event that carries no buffer.
+  It now also listens to the one that does. The test helper was the reason this
+  went unseen: it handed the subscriber the full buffer on every delta, a wire no
+  server writes, so every existing test agreed with the bug.
+
+- **Two chats on one page shared one conversation.** The storage namespace falls
+  back from the element's `id` to its `endpoint`, so two `<ag-ui-chat>` elements
+  with no `id` against the same agent mount — a docked support panel and an
+  inline page assistant, say, and nothing requires an `id` — resolved to the same
+  namespace and shared a thread pointer, a history drawer and every message key.
+  Whichever mounted second adopted the first's active thread and rehydrated its
+  transcript into its own panel. The first element to mount now keeps the
+  namespace, so the ordinary single-element case is untouched, and a second is
+  given a throwaway namespace of its own plus a console warning naming the fix.
+  The throwaway namespace is minted per mount, so give each element an `id` for
+  its conversation to survive a reload.
+
+- **A full storage quota was reported as an agent failure.** `sessionStorage`
+  writes throw once the quota is exhausted — a long conversation, or one turn
+  carrying a large tool result — and in privacy modes that deny storage
+  outright. The transcript is persisted from inside the run loop, so that throw
+  surfaced as a run error and told the user the agent had failed when nothing
+  but the browser's storage had; on the cancel path it escaped as an unhandled
+  rejection instead. A write that cannot be made now costs the reload and not
+  the conversation, and says so in the console once rather than once per turn.
+
+- **A tool a page deliberately withheld from a run still ran when the agent
+  called it.** `getTools` is a per-run catalog provider, so a host is invited to
+  scope what a given page offers while registering everything once at mount.
+  Dispatch never consulted it: it resolved the call name straight against the
+  mount-wide registry, so a call naming a scoped-out tool found its handler and
+  ran it — with the confirmation card the only remaining gate, and that card is
+  waived by `autoConfirm`, by a `confirmPredicate`, or by a schema without
+  `x-destructive`. The page's decision not to offer the tool carried no weight
+  where it mattered. The names a run advertises are now captured as the catalog
+  goes out, and a call outside that set is treated exactly as a call naming a
+  tool that was never registered. The set is the snapshot, not a fresh
+  `getTools()` at dispatch time — asking the provider again would re-open the
+  window it exists to close. Hosts that never override `getTools` advertise the
+  built-ins plus everything registered, which is exactly what dispatch could
+  reach before, so nothing changes for them.
+
+- **A long streamed answer slowed the tab down as it arrived, and destroyed any
+  text selected inside it on every token.** Each `TEXT_MESSAGE_CONTENT` event
+  carries the whole answer so far, and every one of them re-parsed the markdown,
+  re-sanitised it and replaced the bubble's entire subtree. Cost grew with the
+  square of the answer's length — a 40 KB answer streamed token by token meant
+  thousands of full parses over a document that kept getting longer — and
+  because the subtree was rebuilt each time, a selection or a focus inside the
+  bubble could not survive a single token. Since a long answer is entirely
+  agent-controlled, an agent induced to produce one turned an ordinary run into
+  a stalling tab. Deltas now coalesce into one render per animation frame: a
+  burst of tokens costs one parse, and a frame is the fastest anything on screen
+  can change anyway, so the text still flows rather than arriving in chunks. The
+  bubble opens on the first token as before, keeps its identity throughout, and
+  a run that ends without closing its text message — a cancel, an error, a round
+  boundary — draws the queued delta before letting the bubble go, so a stopped
+  answer keeps its last words.
+
+- **Model output could draw a pixel-accurate copy of the approval card.** The
+  markdown sanitiser kept `class` on every element it allowed, and the shadow
+  stylesheet's component classes are unscoped selectors, so a
+  `<span class="approval-btn approval-btn--approve">` in an assistant message
+  resolved to the same background, border and radius as the genuine
+  human-in-the-loop approve button — rendered as ordinary prose, inside the one
+  surface where the user decides whether to approve something. The same trick
+  reproduced the question card, the tool-call card and a turn the user never
+  took. `class` was on the allowlist for exactly one thing, `marked`'s
+  `language-*` code-fence hint, and is now narrowed to it: a `language-*` token
+  on a `code` or `pre` element survives, and every other class is dropped.
+  Highlighting a fenced code block is unaffected.
+
+- **The sanitiser allowed far more attributes than the three it declared.**
+  DOMPurify's `ALLOW_DATA_ATTR` and `ALLOW_ARIA_ATTR` default to `true`, so every
+  `data-*` and `aria-*` attribute passed through alongside `href`/`title`/`class`
+  while the configuration read as though only those three could survive. That
+  handed model output the attributes the cards drive their resolved, status and
+  expanded appearance from, and let an `aria-label` make a screen reader announce
+  something other than what a sighted user reads. Both are now off, so the
+  declared allowlist is the effective one.
+
+- **Rendered markdown was edited after the sanitiser had finished with it.** The
+  sanitised string was parsed into a `<template>`, given its `target`/`rel` link
+  hardening there, and re-serialised — so the markup actually inserted into a
+  bubble was never markup DOMPurify inspected, and it carried two attributes the
+  allowlist did not name. Nothing exploitable came of it, because no allowed
+  element serialises asymmetrically, but that held by accident rather than by
+  design: adding `svg`, `style` or `noscript` to the allowlist would have turned
+  the round trip into a bypass, and the suite asserted on the sanitiser's output
+  instead of on what was inserted. Link hardening now runs inside the sanitiser,
+  so what a caller inserts is exactly what DOMPurify approved, and a test holds
+  it there.
+
+- **Resizing the panel from the keyboard called `commit` on every key repeat.**
+  It is documented as one call per completed resize and the pointer path honours
+  that, but the keyboard path called it straight from each `keydown`. Holding an
+  arrow key means OS key repeat at twenty to thirty events a second, so a host
+  that put a `sessionStorage` write or a `PATCH` behind `commit` got that many
+  for a single press — landing hardest on the keyboard users the path exists for.
+  Live feedback still happens per key event; the commit now waits for the key to
+  come up, or for focus to leave the grip mid-press.
+
+- **A voice recording ran until somebody stopped it.** Tapping the mic and then
+  being interrupted left `MediaRecorder` running with no upper bound: audio
+  accumulated in memory, the browser's recording indicator stayed lit in a tab
+  nobody was looking at, and whenever the user came back the whole accumulated
+  clip was posted to the transcription endpoint in one body no client-side check
+  sized. A recording now stops itself after two minutes — far longer than a
+  dictated chat message, short enough to bound a forgotten one. The audio is kept
+  and transcribed rather than discarded, and the mic button says why it stopped.
+
+- **The README's "Public API surface" tables were missing a third of the surface
+  they enumerate.** The section presents itself as complete, so a consumer who
+  went looking for the chart-drawing seam, the approval and question card
+  helpers, the transcription defaults, `prettifyToolName`, `parseToolCatalog` or
+  two of the event-name constants found no mention and concluded the package had
+  none. Thirty-two absent exports are now listed, and a test compares the tables
+  against the package root's export list so the next new export cannot go missing
+  quietly.
+
+- **`UiStrings.checkpoints` had no documentation to hover.** An insertion of the
+  copy-button strings landed between the checkpoint panel's doc comment and the
+  field it described, stranding the comment above `copyCode`. It is back on
+  `checkpoints`, and the copy-button and checkpoint fields now have sections of
+  their own rather than splitting the relative-time group in half.
+
+### Security
+
+- **Host credentials no longer leave the page's origin silently.** `endpoint` and
+  its sibling URL attributes are plain HTML, so a page that builds one from a
+  query parameter or from tenant-authored configuration has handed whoever wrote
+  that value the destination of the element's requests. The browser preflights
+  the custom header, any server willing to answer receives it, and the CSRF token
+  or bearer the host supplies through `headers` / `getHeaders()` leaves on the
+  very first request — before the user has done anything. Nothing in the package
+  compared a configured URL against an expected origin, so the delivery was
+  invisible. The agent now reports it on the console, naming the destination and
+  the header names, once per origin.
+
+  It reports rather than refuses: an agent on another subdomain is a documented
+  deployment and keeps working unchanged. What is removed is the silence.
+
+  All seven configurable URLs are covered, not the agent endpoint alone. The tool
+  catalog, the skills list, the thread index, the attachment upload and the
+  transcription endpoint are named by the same kind of host attribute and carry
+  the same headers, so reporting only the agent would have reported the least
+  interesting of the seven.
+
+### Documentation
+
+- **Registering a duplicate tool name does not throw.** The README said it did.
+  `ClientToolRegistry.register` is a plain map write, deliberately, so a re-fired
+  host ref or React StrictMode's double-invoke replaces rather than raises. The
+  harm in the claim is not the defensive guard nobody needs; it is a host
+  believing two tools cannot quietly share a name, where the second wins.
+
+- **`x-destructive` gates frontend tools only, and the docs claimed otherwise.**
+  `isDestructive` described the flag as one the server stamps, which cannot
+  reach it: tool schemas travel client-to-server on `RunAgentInput.tools`, and
+  the only channel coming back is the label catalog, which carries names and
+  summaries and no flags. Marking a server-side tool destructive therefore
+  produces no confirmation card in the browser — it has to be gated server-side,
+  which surfaces as an approval card instead. The helper's doc comment and the
+  README's confirmation section now say so.
+
+- **A tool handler's thrown message reaches the model.** When 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 there, and replayed to the
+  model provider on every later round. That is deliberate — a real reason is
+  what lets the agent recover — but the same string is only ever shown to the
+  user as a short card label, so a host rethrowing an internal error had no way
+  to see that an internal hostname, a signed URL or a stack-derived path had
+  left the browser. `registerTool` and the README now say it plainly, so hosts
+  can throw the message they would be content for the model to read.
+
 ## [0.27.0] — 2026-08-26
 
 ### Fixed
@@ -1705,7 +2365,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.27.0...HEAD
+[Unreleased]: https://github.com/Artui/ag-ui-web-component/compare/v0.29.0...HEAD
+[0.29.0]: https://github.com/Artui/ag-ui-web-component/compare/v0.28.0...v0.29.0
+[0.28.0]: https://github.com/Artui/ag-ui-web-component/compare/v0.27.0...v0.28.0
 [0.27.0]: https://github.com/Artui/ag-ui-web-component/compare/v0.26.1...v0.27.0
 [0.26.1]: https://github.com/Artui/ag-ui-web-component/compare/v0.26.0...v0.26.1
 [0.26.0]: https://github.com/Artui/ag-ui-web-component/compare/v0.25.2...v0.26.0