@artooi/ag-ui-web-component 0.18.0 → 0.20.0

package/CHANGELOG.md

@@ -7,6 +7,168 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.20.0] — 2026-08-11
+
+### Added
+
+- **The panel is resizable.** A drag handle on the corner the layout grows
+  toward (or the inner edge when docked), with the size persisted per tab and
+  restored before the first paint. Arrow keys resize from the keyboard, since a pointer-only control
+  has no equivalent elsewhere in the UI; style it via the `resize-handle` part.
+
+  Which axes are draggable is the placement's call: `full` and `page` get no
+  handle at all (a `100vw`/`100vh` layout has nothing to drag), `sidebar` /
+  `side` get width only, everything else gets both.
+
+  ⚠ **It writes the custom properties, not inline `width` / `height`.** The
+  placement rules set those same properties, so an inline dimension would
+  outrank them — a panel dragged while floating would keep that width after
+  switching to fullscreen.
+
+  ⭐ **Which corner the grip sits on is measured, not assumed.** A resize is
+  computed from the edge that stays still, and which edge that is belongs to the
+  *host's* layout rather than to `placement` — a floating panel is pinned
+  bottom-right, an embedded one goes wherever the page's CSS puts it. Deriving
+  it from `placement` was wrong for any host that right-aligns the element, and
+  the symptom was bad enough to read as a broken control: the panel shrank when
+  dragged outward and travelled by its opposite corner. The element now probes
+  its own geometry and reflects the result as `data-resize-anchor`.
+
+### Changed
+
+- **The `/` palette leads with the command.** Each row now reads
+  `/fill-article Fill the article` rather than the label alone (part
+  `skill-item-token`), and a chip's tooltip names the token it stands for. A
+  palette that shows only labels cannot teach its own vocabulary — a user who
+  never sees `/fill-article` has no way to learn to type it.
+
+- **A skill blocked on an unfilled `{placeholder}` now hands back the
+  template.** The partially-filled prompt goes into the composer with the first
+  unresolved placeholder selected, so the next keystroke replaces it. Previously
+  the pick was refused with a hint and whatever the user had typed to open the
+  palette — a lone `/` — was left in the composer, which said nothing about what
+  the skill wanted or how to supply it. The hint now says what to do, too.
+
+- ⚠ **Picking a skill now sends it.** It used to write the text into the
+  composer and wait for a second click unless the skill set
+  `sendImmediately: true` — so the default behaviour of a shortcut was to not
+  take the shortcut. Set `sendImmediately: false` to keep pre-filling, which is
+  worth doing where the user is expected to edit before sending.
+
+- **`Skill.prompt` is now optional, and omitting it is the better default for
+  anything internal.** A skill with no prompt is **server-resolved**: picking it
+  sends the bare `/name` token and the agent expands it, from the harness
+  `Skills` capability or the server's own instructions.
+
+  ⛔ **The prompt was the leak.** A catalog is either a fetched `GET` or an
+  inline `data-skills` attribute sitting in the page source, and a skill is
+  often where a project's internal workflow is written down most plainly — so
+  the client-side catalog published it to anyone who opened the page. Sending a
+  token instead keeps the wording on the server entirely, which is what
+  "trigger a `/command` without exposing the prompt" actually requires; hiding
+  the text behind a chip label would only have moved it off screen.
+
+  `parseSkills` accepts a catalog entry with no `prompt` rather than dropping
+  it — requiring the field would have silently discarded exactly the skills
+  whose wording was kept off the browser. Pairs with `django-ag-ui`'s
+  `SkillSpec.prompt` becoming optional.
+
+## [0.19.0] — 2026-08-11
+
+### Changed
+
+- **A tool card's arguments and its result are now two labelled regions, not one
+  block.** Compact mode emitted `args: {...}` and the result into a single
+  `<pre>` separated by a blank line, with nothing marking where the call ended
+  and the answer began. Both payloads now have their own heading, their own
+  `part` (`tool-card-args` / `tool-card-result`, headings via
+  `tool-card-section-label`, body via `tool-card-body`), and are pretty-printed.
+
+  ⚠ Breaking for anyone styling `tool-card-result` as a single combined block.
+  A call with no arguments no longer renders an empty `{}` in a box of its own.
+
+- ⭐ **`data-tool-display` is now live.** Changing it restyles every card already
+  in the transcript, the way `data-answer-well` always has. The modes are pure
+  visibility over **one DOM shape**, selected by the shadow CSS from the host
+  attribute; previously each card baked its structure at construction from the
+  value read at that moment, so a change reached only cards created afterwards
+  and the setting appeared not to work until the next conversation.
+
+  `ToolCallCard`'s constructor consequently no longer takes a mode argument.
+
+- **The confirmation card leaves once it is answered.** It stayed in the
+  transcript as a spent form with its buttons disabled, which read as an
+  outstanding question rather than a settled one. A prompt and a record are
+  different objects: the record is the tool card it gates, which settles to the
+  outcome and scrolls with the rest of the transcript.
+
+- ⛔ **The confirmation card was appended to the wrong parent**, and it is the
+  reason it drifted to the foot of a turn. Every other inline card — tool,
+  approval, `ask_user`, run notices — goes into the turn's answer group; this
+  one went into the message list, so it became a sibling *after* the group and
+  anything that streamed afterwards rendered above it. It now joins the group
+  like its siblings.
+
+### Added
+
+- **A gated call records the decision**, from the client-side confirmation card
+  **and** the server-side approval interrupt. The tool card carries
+  `approved by you` / `declined by you` (part `tool-card-decision`, attribute
+  `data-decision`). Previously only a *refusal* left a trace — an approved call
+  simply ran, making a gated call's transcript identical to one that was never
+  gated, and the server-side gate left nothing at all even though it is the one
+  guarding tools that run on the backend.
+
+  ⚠ **Session-scoped, like the "run interrupted" notice.** AG-UI carries no
+  approval message — the answer rides `resume[]` as transient run input — so a
+  reload restores the call and its result but not the note. Durable "who
+  approved what" is an audit concern, not a transcript one.
+
+- **Each header control takes its own icon slot** — `icon-history`,
+  `icon-checkpoints`, `icon-new`, `icon-collapse` — with the built-in glyph as
+  the fallback, so existing embeds are unchanged. The glyph used to be the
+  button's own `textContent`: a host could restyle a control through its `part`,
+  or swap one character for another with a CSS `content` override, but could
+  never supply a brand `<img>` or `<svg>`.
+
+- **`argumentsLabel`, `decisionApproved` and `decisionDeclined`** in `UiStrings`.
+  `resultLabel` / `errorLabel` / `declinedLabel` are now the result region's
+  heading rather than a toggle label, and `details` labels the toggle in every
+  mode.
+
+### Fixed
+
+- **A server that reuses a message id now gets a warning.** `@ag-ui/client`
+  appends to a message id already in its history rather than starting a new one,
+  so two answers merge into one transcript entry — silently, and the merged
+  entry is what gets persisted. The protocol has no rule to enforce and refusing
+  the event would be worse than the merge, so this warns and continues.
+
+  ⭐ Found because the demo harness was doing exactly this, which is the
+  argument for the harness in miniature: the bug was the consumer's, the
+  invisibility was ours.
+
+- **The demo playground covers the surface it is meant to demonstrate.** The
+  scripted agent now dispatches on the latest turn — a server-resolved skill, a
+  tool that throws, an `ask_user` question, or the form-filling script — instead
+  of replaying one script for everything, and the page gained header-icon,
+  German-strings and reset-size controls plus a short "what to try" guide.
+
+  ⚠ Two harness defects were making the component look broken. Its follow-up
+  detection matched **any** tool message in the thread, so once a conversation
+  had run a single tool every later turn answered "Done" to everything. And the
+  page forced `flex: 1` on the element, which silently outranks the width a
+  resize writes — the drag worked and nothing moved.
+
+- **The demo harness reused message ids**, which produced three symptoms that
+  all read as component bugs and were none of them. It streamed every follow-up
+  answer under a hardcoded id, and `@ag-ui/client` appends to a message id
+  already in its history rather than starting a new one — so repeating a prompt
+  grew a single entry, that entry replayed out of order after a reload (sitting
+  where it was first created, with the later prompts after it), and the
+  unfinished-run notice then fired correctly over the corrupted history. Fresh
+  ids per message, as a real server issues.
+
 ## [0.18.0] — 2026-08-10
 
 ### Added
@@ -877,7 +1039,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Notes
 - First release — exercising the automated npm OIDC publish pipeline end-to-end.
 
-[Unreleased]: https://github.com/Artui/ag-ui-web-component/compare/v0.18.0...HEAD
+[Unreleased]: https://github.com/Artui/ag-ui-web-component/compare/v0.20.0...HEAD
+[0.20.0]: https://github.com/Artui/ag-ui-web-component/compare/v0.19.0...v0.20.0
+[0.19.0]: https://github.com/Artui/ag-ui-web-component/compare/v0.18.0...v0.19.0
 [0.18.0]: https://github.com/Artui/ag-ui-web-component/compare/v0.17.0...v0.18.0
 [0.17.0]: https://github.com/Artui/ag-ui-web-component/compare/v0.16.0...v0.17.0
 [0.16.0]: https://github.com/Artui/ag-ui-web-component/compare/v0.15.0...v0.16.0

package/README.md

@@ -164,6 +164,16 @@ That's the whole integration: an `endpoint` attribute pointing at your AG-UI ser
 | `data-theme-toggle` | — | Boolean: show a built-in header light⇄dark toggle (persists per tab). Off by default. See [Theme toggle](#theme-toggle). |
 | `data-strings` | `strings` | Partial JSON override of the UI string table (localization). The property wins key-by-key over the attribute; see [Internationalization](#internationalization-i18n). |
 | `data-icon-url` | — | Header (and sidebar-rail) icon image URL. A slotted `slot="icon"` wins; see [Header & launcher icon](#header-and-launcher-icon). |
+
+Each header control also takes its own icon slot — `icon-history`, `icon-checkpoints`,
+`icon-new`, `icon-collapse` — with the built-in glyph as the fallback, so a host can project a
+brand `<img>` or `<svg>` rather than only restyling the character:
+
+```html
+<ag-ui-chat endpoint="/agent/">
+  <svg slot="icon-new" width="16" height="16"><!-- ... --></svg>
+</ag-ui-chat>
+```
 | `data-page-actions` | — | Opt-in built-in page-action tools: a comma list of `scroll` / `drag` (e.g. `"scroll,drag"`). See [Page-action tools](#page-action-tools). |
 | `data-side` | — | CSS-only, for `placement="sidebar"`: which edge it docks to — `right` (default) / `left`. |
 | `data-answer-well` | — | CSS-only boolean: box each assistant turn (its text, tool cards, and thinking) in one bordered "well". Off by default. See [The answer well](#the-answer-well). |
@@ -506,8 +516,29 @@ property), one of `inline` / `minimal` / `compact` / `full` (default `full`):
   result behind its own toggle. Reads as one line of the answer — pairs with [the answer
   well](#the-answer-well).
 - `minimal` — tool name + status pill only.
-- `compact` — name + status, with args *and* result behind a single collapsed "Details" toggle.
-- `full` — args inline, result behind its own toggle (the original behaviour).
+- `compact` — name + status, with arguments *and* result behind a single collapsed toggle.
+- `full` — arguments visible, result behind the toggle (the default).
+
+Whichever mode is on, a settled card's body holds **two labelled regions** — `Arguments` and
+`Result` (or `Error` / `Declined`) — each with its own part and each pretty-printed. They are
+never run together into one block, so where the call ends and the answer begins is always
+visible. Style them via the `tool-card-args` / `tool-card-result` parts, their headings via
+`tool-card-section-label`, and the whole body via `tool-card-body`.
+
+**The attribute is live.** Changing `data-tool-display` restyles every card already in the
+transcript, the way `data-answer-well` does — the modes are pure visibility over one DOM shape,
+selected by the shadow CSS from the host attribute.
+
+A gated call carries the decision (`approved by you` / `declined by you`, part
+`tool-card-decision`, attribute `data-decision`) — from the client-side confirmation card and
+from the server-side approval interrupt alike. The prompt itself disappears once answered: a
+prompt and a record are different objects, and the record is the card.
+
+⚠ **The annotation is session-scoped**, like the "run interrupted" notice. AG-UI carries no
+approval message — the answer rides `resume[]` as transient run input — so a reload restores the
+tool call and its result but not the note that a human waved it through. If you need "who
+approved what" durably, that is an audit concern rather than a transcript one; record it
+server-side.
 
 If a tool's schema carries an `x-summary` string (use `X_SUMMARY_KEY`), the card shows it on the
 label instead of the raw tool name.
@@ -524,6 +555,43 @@ speed; the spin respects `prefers-reduced-motion`).
 
 ---
 
+## Resizing the panel
+
+The panel carries a drag handle on its leading corner (or leading edge, docked),
+so a reader can widen it without the host having to re-theme anything.
+
+- `placement="full"` / `placement="page"` get **no handle** — a full-bleed layout
+  is `100vw`/`100vh` by definition, so there is nothing to drag.
+- `placement="sidebar"` / `placement="side"` get **width only**; the placement
+  owns the height.
+- Everything else resizes on both axes.
+
+**The grip sits at the corner your layout grows toward, and the component
+measures which one that is.** A resize has to be computed from the edge that
+stays still, and that belongs to *your* CSS rather than to `placement` — a
+floating panel is pinned bottom-right, an embedded one goes wherever the page
+puts it. The element probes its own geometry and reflects the result as
+`data-resize-anchor` (e.g. `bottom-right` means those two edges are fixed), which
+is what positions the grip.
+
+A drag writes `--ag-ui-width` / `--ag-ui-height` on the host **as custom
+properties, not inline `width`/`height`** — the placement rules set those same
+properties, so an inline dimension would outrank them and a panel dragged while
+floating would keep that width after switching to fullscreen.
+
+⚠ **A host rule that sizes the element wins over both.** `ag-ui-chat { flex: 1 }`
+stretches the panel to its container and the dragged width has no visible
+effect — which reads as a broken control rather than as your stylesheet winning.
+Give the element `flex: 0 1 auto` (plus `max-width: 100%`) if it lives in a flex
+container.
+
+The size persists per tab (`sessionStorage`, namespaced per element like the
+collapsed and theme preferences) and is restored before the first paint.
+Arrow keys resize from the keyboard (`Shift` for a larger step); style the grip
+via the `resize-handle` part.
+
+---
+
 ## Markdown rendering
 
 Assistant bubbles render sanitized markdown/HTML via [`marked`](https://www.npmjs.com/package/marked)
@@ -589,7 +657,7 @@ opt-in via two attributes:
 <ag-ui-chat endpoint="/agent/" data-prompt-chips="true" data-slash-commands="true"></ag-ui-chat>
 ```
 
-A `Skill` is `{ name, title, description?, prompt, sendImmediately?, chip? }`. Skills are merged
+A `Skill` is `{ name, title, description?, prompt?, sendImmediately?, chip? }`. Skills are merged
 from three sources — **backend → embed → client** (later wins by `name`):
 
 - `data-skills-url` — a JSON endpoint, fetched with the element's `headers`.
@@ -598,11 +666,21 @@ from three sources — **backend → embed → client** (later wins by `name`):
 
 ```js
 chat.setSkills([
+  // Server-resolved: no prompt here, so picking it sends the bare "/triage"
+  // token and the agent decides what it means.
+  { name: "triage", title: "Triage this", chip: true },
+  // Client-side: the page owns the wording and fills the placeholders.
   { name: "summarize", title: "Summarize page", prompt: "Summarize {title}.", chip: true },
 ]);
 ```
 
-A skill `prompt` may contain `{placeholder}` tokens; the `skillContext` property
+**Prefer omitting `prompt` for anything internal.** A skill is often where a project's workflow is
+written down most plainly, and a catalog is either a plain `GET` or sits in the page source — so
+shipping the wording to the browser publishes it. Without a `prompt` the component sends `/name`
+and the agent expands it (from the harness `Skills` capability, or your own instructions); the text
+never leaves the server. `django-ag-ui`'s `SkillRegistry` supports this by leaving `prompt` unset.
+
+A skill that *does* carry a `prompt` may use `{placeholder}` tokens; the `skillContext` property
 (`() => Record<string, unknown>`) supplies the values, filled in before send. A missing placeholder
 blocks the send and shows a hint instead.
 
@@ -610,6 +688,10 @@ blocks the send and shows a hint instead.
 chat.skillContext = () => ({ title: document.title });
 ```
 
+**Picking a skill sends it.** A chip that needs a second click to do anything is a two-step
+shortcut. Set `sendImmediately: false` on a prompt-carrying skill to pre-fill the composer instead —
+useful when the user is expected to edit before sending. A server-resolved skill always sends.
+
 ---
 
 ## MPA durability: surviving full page reloads