@artooi/ag-ui-web-component 0.25.2 → 0.26.1

package/CHANGELOG.md

@@ -7,6 +7,95 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.26.1] — 2026-08-25
+
+### Fixed
+
+- **A chart the server retracted stayed on screen.** When an update replaced a
+  chart with a payload that could not be drawn, the superseded chart was left in
+  place — showing numbers the server had already withdrawn, reading as current —
+  and then vanished on the next reload, because the *stored* content was the
+  version that could not be drawn. Live and reload now agree, and both say gone.
+
+- **`enableCharts()` after the element connected silently dropped every chart in
+  restored history.** History replays on connect, and charts were off at that
+  moment, so they were skipped. That is the ordinary way to call it — you have
+  to query the element to call anything on it — so the first call now redraws
+  rather than the docs asking for an ordering nobody can satisfy. The README
+  example was that order.
+
+- **A stacked chart wrote `NaN` into the DOM** for a series carrying more points
+  than there are labels. `renderChart` is exported, so it can be handed a spec
+  the validator would have refused; a cast there claimed that could not happen.
+
+- **A sparse `labels` array was accepted**, drawing a chart with blank axis
+  labels — `Array.prototype.some` skips holes.
+
+- **A spec inside the point budget could still block the main thread.** The
+  point limit bounds the data; the DOM is bounded by labels, since each emits an
+  axis node whatever the series count. Now capped at 2,000 labels, and the
+  ceiling applies again on every reload of a stored conversation.
+
+### Documentation
+
+- **Whether a pushed chart survives a reload depends on where the conversation
+  is stored**, and the README now says which is which. A client-side store keeps
+  activities; a server storing the thread as the model's message history does
+  not, because a pushed chart is deliberately not in that history. An
+  agent-requested chart survives either way — its spec travels as the tool
+  call's arguments.
+
+### Changed
+
+- **The handler/render split is now enforced by a signature rather than a
+  comment.** The replay path is handed the `render` function alone, never the
+  tool that owns it, so the code that runs on restore cannot reach `handler`.
+  The documentation claimed this guarantee was structural while the code passed
+  the whole tool around and relied on two call sites happening not to use it.
+
+- The built-in chart tool no longer builds the chart twice per call, once only
+  to choose its reply string.
+
+## [0.26.0] — 2026-08-25
+
+### Added
+
+- **Charts in the transcript**, by two routes that share one renderer, both
+  opt-in via a new `enableCharts(routes)` method. Nothing draws a chart unless a
+  host asks for it.
+
+  - `enableCharts(["tool"])` registers a `render_chart` frontend tool the agent
+    can call. The numbers are in its context, so it can discuss them.
+  - `enableCharts(["activity"])` draws a server-pushed `ACTIVITY_SNAPSHOT` of
+    type `chart`. The data never enters the model's context, there is no extra
+    model round, and only this route can update a chart in place — repeat a
+    `messageId` to redraw, or send an `ACTIVITY_DELTA` to move one series.
+
+  Bar, line, pie, scatter and stacked, drawn as SVG built with `createElement`
+  and never parsed from a string. That is the reason a chart is safe on a
+  surface that keeps `img` off by default: the model chooses the numbers, the
+  component chooses the DOM, so nothing chart-shaped reaches the sanitiser at
+  all. Six theme tokens, `--ag-ui-chart-1` through `--ag-ui-chart-6`, and three
+  parts: `chart-block`, `chart-title`, `chart-legend`.
+
+- **`ClientTool.render`** — an optional, pure `(args) => Node | null` beside
+  `handler`, and **the only half a restored transcript replays**. Replaying a
+  tool's *effect* is out of the question — re-running a form-filling tool on
+  every reload is a bug — so the two halves are separated structurally rather
+  than by a flag: the restore path holds no reference to `handler`, so it cannot
+  run it whatever a tool author intended. `render` must be a pure, deterministic
+  function of its arguments; it runs again on every restore.
+
+### Changed
+
+- **`AgUiClientHandlers` gained a required `onActivityChanged` member**, and
+  `onActivity` now receives the activity's `messageId` as a third argument. Both
+  types are exported, so a consumer implementing the handler interface directly
+  must add the member; anyone using `<ag-ui-chat>` is unaffected.
+- `ClientTool.handler` now receives an optional `callId` as a second argument,
+  for a handler that renders into the transcript and needs to place itself
+  against its own card. Existing one-parameter handlers are unaffected.
+
 ## [0.25.2] — 2026-08-25
 
 ### Fixed
@@ -1573,7 +1662,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.25.2...HEAD
+[Unreleased]: https://github.com/Artui/ag-ui-web-component/compare/v0.26.1...HEAD
+[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
 [0.25.2]: https://github.com/Artui/ag-ui-web-component/compare/v0.25.1...v0.25.2
 [0.25.1]: https://github.com/Artui/ag-ui-web-component/compare/v0.25.0...v0.25.1
 [0.25.0]: https://github.com/Artui/ag-ui-web-component/compare/v0.24.0...v0.25.0

package/README.md

@@ -856,6 +856,94 @@ ag-ui-chat {
 
 ---
 
+## Charts
+
+Markdown here goes through a narrow sanitiser and images are off by default — a
+model-controlled image URL is fetched with no user interaction, which turns
+prompt-injected page data into a zero-click exfiltration channel. So a chart
+does not arrive as markup. It arrives as **data**, and the component builds the
+SVG itself: the model chooses the numbers, the component chooses the DOM.
+
+Off unless you ask for it, by either route or both:
+
+```js
+const chat = document.querySelector("ag-ui-chat");
+chat.enableCharts(["tool", "activity"]);
+```
+
+Order does not matter. Calling it after the element is on the page redraws any
+charts already in the restored history, so you do not have to reach the element
+before it connects — which you generally cannot.
+
+Specs are bounded, and anything outside is dropped rather than half-drawn: at
+most **20,000 points** and **2,000 labels**, and every point a finite number no
+larger than **1e15**. The first two keep a stored transcript from blocking the
+main thread on every reload; the last one keeps the value range finite, since
+scaling divides by it.
+
+**`"tool"`** registers a `render_chart` tool the agent may call. The numbers are
+in its context, so it can talk about them; it costs one model round.
+
+**`"activity"`** draws a chart the server pushes as an `ACTIVITY_SNAPSHOT` with
+`activityType: "chart"` (exported as `CHART_ACTIVITY_TYPE`). The data never
+reaches the model, there is no extra round, and this is the only route that can
+**update a chart in place** — the server repeats the same `messageId` to redraw
+it, or sends an `ACTIVITY_DELTA` to move one series as a computation advances.
+
+**Whether a pushed chart survives a reload depends on where the conversation is
+stored.** A client-side store keeps activities, so it comes back. A server that
+stores the thread as the model's message history does not — a pushed chart is
+deliberately not in that history, which is the reason to push it. A chart the
+agent asked for survives either way, because its spec travels as the tool call's
+arguments and the component redraws from those without re-running anything.
+
+Either way the payload is the same shape:
+
+```json
+{
+  "kind": "bar",
+  "title": "Signups this week",
+  "labels": ["Mon", "Tue", "Wed"],
+  "series": [{ "label": "new", "points": [12, 19, 9] }]
+}
+```
+
+`kind` is one of `bar`, `line`, `pie`, `scatter`, `stacked`; anything else is
+drawn as a bar rather than refused. Every series needs exactly one point per
+label — a shorter one misaligns every value after the gap, and a chart that is
+subtly wrong still reads as authoritative, so the whole spec is dropped instead.
+A pie's slices are its labels, so it draws the first series only.
+
+Theme the series with `--ag-ui-chart-1` … `--ag-ui-chart-6`, and style the block
+through the `chart-block`, `chart-title` and `chart-legend` parts.
+
+### Drawing something other than a chart
+
+`render_chart` is built on a seam any tool can use. A `ClientTool` may declare a
+pure `render` beside its `handler`:
+
+```js
+chat.registerTool({
+  name: "show_route",
+  description: "Draw the route on a map.",
+  parameters: { type: "object", properties: { stops: { type: "array" } } },
+  handler: () => "route shown",
+  render: (args) => buildMapElement(args.stops),   // pure; no side effects
+});
+```
+
+**`render` is the only half a restored transcript replays.** Replaying a tool's
+*effect* is out of the question — re-running a form-filling tool on every reload
+is a bug. The replay path is handed the `render` function alone, never the tool
+that owns it, so the code that runs on restore cannot reach `handler` even by
+mistake: adding a "no render? fall back to the handler" convenience there means
+changing a type signature first, which is the moment the question gets asked.
+
+That is why `render` has to be a pure, deterministic function of its arguments —
+it runs again every time the conversation is restored.
+
+---
+
 ## Tool-call display modes
 
 How much a tool-call card shows is set via the `data-tool-display` attribute (or `toolDisplay`
@@ -1598,6 +1686,7 @@ component sets, so a new one cannot ship undocumented.
 | Attachments | `attachment-tray`, `attachment-chips` (the read-only chips on sent bubbles), and the shared chip parts `attachment-chip`, `attachment-chip-icon`, `attachment-chip-name`, `attachment-chip-size`, `attachment-chip-bar`, `attachment-chip-bar-fill`, `attachment-chip-retry`, `attachment-chip-remove` |
 | Skills | `skill-chips`, `skill-chip`, `skill-palette`, `skill-item`, `skill-item-title`, `skill-item-desc`, `skill-item-token`, `skill-hint` (the missing-placeholder hint) |
 | Thread drawer | `drawer`, `drawer-backdrop`, `drawer-panel`, `drawer-header`, `drawer-title`, `drawer-new`, `drawer-list`, `drawer-empty`, `drawer-row`, `drawer-row-select`, `drawer-row-title`, `drawer-row-time`, `drawer-row-preview`, `drawer-row-actions`, `drawer-row-rename`, `drawer-row-delete`, `drawer-rename-input`, `drawer-confirm`, `drawer-confirm-label`, `drawer-confirm-yes`, `drawer-confirm-no` |
+| Charts | `chart-block`, `chart-title`, `chart-legend` |
 | Checkpoints panel | `checkpoints`, `checkpoints-header`, `checkpoints-title`, `checkpoints-list`, `checkpoints-empty`, `checkpoint-row`, `checkpoint-label`, `checkpoint-time`, `checkpoint-id`, `checkpoint-branch`, `checkpoint-action` (plus `checkpoint-resume`, `checkpoint-fork`) |
 
 > **Hiding `::part(header)` hides the controls inside it.** The history, checkpoints, new-chat,