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

package/CHANGELOG.md

@@ -7,6 +7,421 @@ 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
@@ -1950,7 +2365,8 @@ hosts that both arrange the page the way it expects.
 ### Notes
 - First release — exercising the automated npm OIDC publish pipeline end-to-end.
 
-[Unreleased]: https://github.com/Artui/ag-ui-web-component/compare/v0.28.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