@artooi/ag-ui-web-component 0.15.0 → 0.17.0

package/CHANGELOG.md

@@ -7,6 +7,161 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.17.0] — 2026-08-10
+
+### Added
+
+- **`sendMessage(content, attachments?)`** — send as if the user had typed it:
+  user bubble, `ag-ui-submit`, run started. The programmatic half of the
+  composer, for an "Ask about this order" button, a command palette, or a
+  composer of your own replacing the built-in one. The built-in Send now reads
+  the composer, clears it, and calls this, so the two paths cannot drift.
+
+  It no-ops while a run is in flight — a second concurrent run would orphan the
+  first — and for an entirely empty message. ⚠ Unlike the built-in Send it does
+  **not** consult the attachment tray: what you pass is what is sent, so a host
+  composer stays in charge of its own state.
+
+- **`attachFile(file)`** — queue a file into the tray exactly as the picker and
+  drag-and-drop do, with the same validation and progress chip. Returns `false`
+  when uploads are not configured (no `data-attachments-url`, no
+  `uploadHandler`), which is the only way for a host to tell: with no tray there
+  is nothing to report through, and silence would read as a queued file that
+  never uploads.
+
+- **`ag-ui-attachments` event**, dispatched whenever the tray changes — a file
+  queued, an upload finishing or failing, a chip removed, the tray cleared after
+  a send. `detail` carries `{ attachments, pending }`: the durable refs of
+  everything settled, and how many are still in flight.
+
+  ⭐ **This is what makes `sendMessage` usable with files at all.** The tray only
+  ever spoke to the built-in Send button, so a host composer had no way to tell a
+  settled upload from one still uploading — the same information the built-in
+  Send needs, which was simply not exposed. The tray's `onChange` hook already
+  existed and nothing was wired to it.
+
+### Changed
+
+- **Assigning a connect-time-only attribute after the element has connected now
+  warns**, instead of being silently ignored: `data-attachments-url`,
+  `data-attachment-accept`, `data-attachment-max-bytes`, `data-transcribe-url`,
+  `data-threads-url`, `data-tools-url`, `data-skills-url`, `data-skills`,
+  `data-prompt-chips`, `data-slash-commands`, `data-theme-toggle`,
+  `data-strings`, `data-icon-url`.
+
+  Each is read once while connecting, to decide what chrome exists at all, and
+  no later read revisits the decision. ⚠ **The symptom is an affordance that
+  simply never appears** — which reads as a broken component rather than a
+  mis-timed assignment, and it is the common React/Vue shape: the element mounts
+  on the first render pass and the framework patches attributes in on the next.
+
+  Set them before the element enters the DOM, or remove and re-insert it to
+  apply a new value. ⭐ The attributes that genuinely *are* re-read per use —
+  `data-runs-url`, `data-page-actions`, `data-text-animation`,
+  `data-tool-display`, `endpoint`, and CSS-reactive `theme` / `collapsed` — are
+  deliberately excluded, since a late change works there and a warning would be
+  wrong.
+
+### Fixed
+
+- **The checkpoint panel now follows the theme.** Its rules read `--agui-surface`
+  / `--agui-border` / `--agui-hover` — note `--agui-`, not the `--ag-ui-`
+  namespace every other rule uses — each with a hardcoded light-mode fallback.
+  So the panel ignored `theme="dark"` entirely and rendered light-on-dark unless
+  a host happened to set three variables documented nowhere. Now derived from the
+  real theme tokens, with a new theme-aware `--ag-ui-hover` defined in every
+  theme block. ⭐ The fallbacks are what hid it: they made an unthemed panel look
+  deliberate.
+
+  `checkpoints-title` and `checkpoint-label` also gain `part` attributes — they
+  carried classes only, so neither could be styled from outside the shadow root.
+
+- **Markdown tables are styled.** `table` / `thead` / `tbody` / `tr` / `th` /
+  `td` are all in the sanitizer's `ALLOWED_TAGS`, so an agent emitting a table
+  rendered it — completely unstyled, overflowing its bubble. Wide tables now
+  scroll inside their own box rather than pushing the layout sideways.
+
+- **Sending while a file is still uploading now says so.** `readyRefs()` returns
+  only settled uploads and `clearReady()` deliberately keeps the rest for a
+  follow-up message — so the file was never lost, but the message went without
+  it and nothing indicated that. Attachments are frequently the entire point of
+  the message, which is what made the silence the defect. An inline notice now
+  names how many are still uploading and that they remain attached.
+
+  Send is deliberately **not** disabled while uploads are pending: that would
+  fight the tray's documented "keep for a follow-up" behaviour and could wedge
+  on an upload that never settles.
+
+## [0.16.0] — 2026-08-09
+
+### Added
+
+- **A stale-page guard on frontend tool calls.** A round's context records the
+  page it describes; if the page moves before the agent's tool call arrives, the
+  call is refused with a result telling the agent to call `read_page` and retry,
+  instead of running the handler. Most stale calls would simply miss and report
+  a failure — the case this prevents is the other one, where a same-named
+  control on the *new* page matches and the agent silently acts on the wrong
+  page. `read_page` itself and tools marked `x-navigates` are exempt, and the
+  guard is inert unless a `getPageMap` provider is set.
+- **New `UiStrings` keys `runInterrupted` and `pageMoved`**, both overridable
+  like every other string.
+
+### Changed
+
+- **Toolchain majors: Vitest 3 → 4 and TypeScript 5.9 → 7**, plus `marked`
+  18.0.9, Biome 2.5.7, `@types/node` 26.1.2. All development dependencies — the
+  emitted `.d.ts` files are **byte-identical** to the 5.9 output (verified by
+  building both and diffing; only the source maps move), so consumers see no
+  change.
+
+  ⚠ **Vitest 4 takes a provider *instance*, not the string `"playwright"`.**
+  The provider moved to its own package (`@vitest/browser-playwright`) and, with
+  v8 coverage, the old string form is a hard error rather than a deprecation.
+
+  ⚠ **TypeScript 7 requires `rootDir` explicitly** (TS5011) instead of
+  inferring it from the common source directory. Set to the value 5.x inferred,
+  so the published layout is unchanged.
+
+### Fixed
+
+- **A run interrupted by navigation no longer vanishes silently.** If the page
+  navigates or reloads while a run is in flight — routine in an MPA — the
+  element is destroyed with it, and on the next mount the transcript replayed
+  with the answer simply missing and no indication anything had gone wrong. The
+  element now reports it as an inline notice. Detected from the shape of the
+  transcript (`send()` persists the user turn *before* starting the run, so a
+  history ending on that turn means nothing came back), which is why it needs no
+  `ClientConversationStore` change and no `pagehide` listener — neither of which
+  would fire on a crash or a force-quit anyway.
+
+  It is deliberately **a notice, not a resume**: AG-UI has no
+  resume-an-aborted-run primitive, so re-sending the accumulated messages is
+  semantically a new run and would re-execute any server-side tool the agent had
+  already performed. The agent-initiated case is unaffected — a navigating tool
+  still checkpoints and resumes exactly as before.
+
+- **Six branches that were never actually covered.** Vitest 4's v8 provider
+  remaps coverage more precisely, and the 100% gate stopped being satisfiable —
+  not because anything regressed, but because v3 had been crediting six
+  branches and three callbacks that no test reached. Each is now genuinely
+  tested: the paperclip button opening the file picker, the built-in
+  transcription handler (every prior voice test supplied its own), a page-action
+  tool resolving through `resolvePageTarget`, a non-`Enter` keystroke in a
+  question card, a submit click with no answer, a non-string `error` in a
+  transcription error body, and a restored history message with an unrecognised
+  role.
+
+  ⭐ **One was a flaw in the test harness, not a missing test.** `makeFakeAgent`
+  ended a clean run by calling `onRunFinalized` alone, so the client's
+  `RUN_FINISHED` path could only ever be reached through `emit.interrupt()` —
+  the ordinary success outcome every real run carries was never exercised. The
+  fake now emits both events, in the order a real agent does.
+
+  `route_map`'s unreachable guard was restructured away rather than tested: its
+  regex capture group is mandatory, so the `undefined` case existed only to
+  satisfy `noUncheckedIndexedAccess` and no test could ever have reached it.
+
 ## [0.15.0] — 2026-08-08
 
 ### Changed
@@ -678,7 +833,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.15.0...HEAD
+[Unreleased]: https://github.com/Artui/ag-ui-web-component/compare/v0.17.0...HEAD
+[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
 [0.15.0]: https://github.com/Artui/ag-ui-web-component/compare/v0.14.1...v0.15.0
 [0.14.1]: https://github.com/Artui/ag-ui-web-component/compare/v0.14.0...v0.14.1
 [0.14.0]: https://github.com/Artui/ag-ui-web-component/compare/v0.13.0...v0.14.0

package/README.md

@@ -194,8 +194,35 @@ labels are fetched automatically — per card, `x-summary` → an explicit
 
 **Properties** (selected): `sharedState` — AG-UI shared state (documented under Tools & state).
 
-**Methods**: `registerTool`, `registerPageState`, `setSkills`, `appendMessage`, `newChat`,
-`setCollapsed`, `toggleCollapsed`.
+**Methods**: `registerTool`, `registerPageState`, `setSkills`, `sendMessage`, `attachFile`,
+`appendMessage`, `newChat`, `setCollapsed`, `toggleCollapsed`.
+
+### Sending from your own UI
+
+`sendMessage(content, attachments?)` sends as if the user had typed it — user bubble,
+`ag-ui-submit` event, run started. Use it for an "Ask about this order" button, a command
+palette, or a composer of your own replacing the built-in one. It no-ops while a run is in
+flight and for an entirely empty message, and unlike the built-in Send it does **not** consult
+the attachment tray: what you pass is what is sent, so your composer stays in charge of its
+own state.
+
+`attachFile(file)` queues a file into the tray exactly as the picker and drag-and-drop do, with
+the same validation and progress chip. It returns `false` when uploads are not configured
+(no `data-attachments-url` and no `uploadHandler`) — the only way to tell, since with no tray
+there is nothing to report through.
+
+Uploading is asynchronous, so watch `ag-ui-attachments` for the result. Its `detail` carries
+`{ attachments, pending }`: the durable refs of everything that has finished, and how many are
+still in flight. Send once `pending` is `0`, or you will leave files behind.
+
+```js
+chat.addEventListener("ag-ui-attachments", (e) => {
+  const { attachments, pending } = e.detail;
+  sendButton.disabled = pending > 0;
+  sendButton.onclick = () => chat.sendMessage(input.value, attachments);
+});
+chat.attachFile(fileInput.files[0]);
+```
 
 A self-contained live playground lives in [`demo/`](demo/) — run `make demo` to serve it against a
 mock AG-UI server.
@@ -648,13 +675,24 @@ chat.routeMap = [
 
 **`getPageMap(): PageMap`** — a per-run provider returning the current page's compact actionable
 surface (field names/types/labels, button labels+handles — *not* values). It is auto-injected into
-each run's `context` as a `page_map` entry (toggle with `autoInjectPageMap`). Recomputed every run
-so it reflects the page the agent is currently looking at:
+each run's `context` as a `page_map` entry (toggle with `autoInjectPageMap`):
 
 ```js
 chat.getPageMap = () => ({ fields: introspectForm(), buttons: visibleButtons() });
 ```
 
+It is recomputed at the top of **every tool round**, not once per `send()` — so after the agent
+acts, the next round already sees the resulting page. Within a round the agent can pull a fresh
+view at any time with the built-in `read_page` tool, which is registered whenever this provider is
+set.
+
+That leaves one window: the page can move *after* a round's context was built but *before* the
+agent's tool call arrives — the user clicks a link, or presses back. Calls landing in that window
+are **refused** with a result telling the agent to call `read_page` and retry. Most would have
+missed anyway; the guard exists for the case where a same-named control on the new page matches and
+the agent would otherwise act on the wrong page without either side noticing. `read_page` and tools
+marked `x-navigates` are exempt, and the guard is inert when no `getPageMap` is set.
+
 **`registerPageState({ name, read, write?, schema? })`** — ergonomic sugar over `registerTool` for
 SPA app state (Redux/Zustand/signals). It auto-generates a `read_<name>` (read-only) tool and, when
 `write` is supplied, a `set_<name>` tool stamped `x-destructive`: