@artooi/ag-ui-web-component 0.1.1 → 0.2.1

package/CHANGELOG.md

@@ -7,6 +7,102 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.1] — 2026-06-02
+
+### Added
+- **Server-side tool results in the card.** The element now subscribes to
+  AG-UI's `TOOL_CALL_RESULT` event and settles the matching tool-call card with
+  the real server output (honouring the `data-tool-display` mode), instead of
+  the generic "Executed on the server." placeholder — which remains only as a
+  fallback when no result event is streamed.
+- **Tool calls and results survive a page refresh.** History replay now
+  reconstructs tool-call cards (from assistant `toolCalls`) and settles them
+  from the persisted `tool` result messages, so a rehydrated transcript shows
+  the full tool activity, not just the prose. Applies to every conversation
+  store (the data was already persisted; only the replay was incomplete).
+
+### Fixed
+- **Pending indicator could hang after a server-only round.** A round whose
+  tool calls were all server-side re-showed the "thinking" indicator after the
+  run had already finished, leaving it stuck. The indicator is no longer shown
+  speculatively for server tools, and a terminal `onSettled` guarantee clears
+  it (and re-enables input) on every run-loop exit — including the
+  `MAX_TOOL_ROUNDS` ceiling and errors.
+
+## [0.2.0] — 2026-06-02
+
+### Added
+- **Markdown + HTML rendering** in assistant message bubbles (`renderMarkdown`),
+  sanitised with DOMPurify (scripts, event handlers, and `javascript:` URLs
+  stripped; links hardened with `target`/`rel`). User messages stay literal.
+- **Pending indicator** — an animated "thinking" indicator shown while the agent
+  is awaited (before the first token and between tool rounds), honouring
+  `prefers-reduced-motion`.
+- **New-chat button** in the header — clears the transcript, the persisted
+  conversation, and the in-memory run state, and mints a fresh thread.
+- **Collapse seam** — a reflected `collapsed` attribute, a built-in header
+  toggle, a persisted (per-tab) collapsed state, and a `TOGGLE_EVENT`
+  (`ag-ui-toggle`) so a host can drive its own chrome.
+- **Tool-call display modes** (`TOOL_DISPLAY`, `data-tool-display`): `minimal`
+  (name + status), `compact` (args + result behind one "Details" toggle), and
+  `full` (the default; original behaviour).
+- **Richer action animations**: `pressThenClick`, `selectOption`,
+  `toggleControl` (+ `pressButton` / `selectControl` / `toggleCheckbox` driver
+  wrappers), all honouring `prefers-reduced-motion`.
+- **Dynamic route syntax**: `Route.path` supports `:name` placeholders;
+  `navigate_to_route` substitutes path params (leftover params → query string)
+  and `list_routes` advertises each route's `pathParams`.
+- `X_CONFIRM_KEY` (`x-confirm`) tool metadata for a human-readable confirmation
+  prompt.
+- `setNativeValue` / `setNativeChecked` utilities (also used internally).
+- **Theming** — a `theme` attribute (`light` / `dark` / `auto` / `code`); `auto`
+  follows `prefers-color-scheme`, `code` is a monospace terminal palette. Plus a
+  wider set of themeable `--ag-ui-*` variables.
+- **Density + placement presets** — `density` (`comfortable` / `compact`) and
+  `placement` (`bottom-left` / `side` / `full` / `embedded`); `embedded` drops
+  the floating chrome and high z-index so the widget lives in the host layout.
+- **Incoming-text animations** — `data-text-animation` (`none` / `fade` /
+  `word`), the last revealing assistant text word-by-word; honours
+  `prefers-reduced-motion`.
+- **`confirmPredicate`** — a per-call `(toolName, args) => boolean | Promise`
+  hook deciding confirmation dynamically (authoritative over `x-destructive`).
+- **Built-in `read_page` tool** — present when a `getPageMap` provider is set, so
+  the agent can re-read the page mid-turn after acting.
+- **`x-summary`** tool metadata (`X_SUMMARY_KEY`) — a friendly label shown on the
+  tool-call card instead of the raw tool name.
+- `observedAttributes` / `attributeChangedCallback` so a late `title-text`
+  change updates the header.
+- Accessibility: `role="log"`/`aria-live` on the transcript, `role="status"` on
+  the pending indicator, `role="group"` on the confirmation card, input label.
+- **Skills** — pre-defined prompts surfaced as **chips** (`data-prompt-chips`)
+  and/or a **`/`-command palette** (`data-slash-commands`), both opt-in over one
+  catalog. Catalog from the `skills` setter (`setSkills`), a `data-skills` JSON
+  embed, and/or a fetched `data-skills-url` (merged backend → embed → client).
+  Picking pre-fills the input (or auto-sends with `sendImmediately`); prompts
+  support `{placeholder}`s filled from `skillContext`, with a missing value
+  blocking the send and showing a hint. Exports the `Skill` type.
+
+### Changed
+- The destructive-action confirmation is now an **inline card in the transcript**
+  (Confirm / Cancel, with the `x-confirm` message) instead of a focus-stealing
+  modal overlay. `requestConfirmation` now renders inline; the
+  `confirmation_modal` module was removed.
+- **Framework-controlled inputs now work.** `fillField` / `typeInto` /
+  `selectOption` / `toggleControl` / `setControlValue` set `value` / `checked`
+  through the **native prototype setter** before dispatching `input`, so
+  React/Vue/Svelte value-tracking sees the change (previously the field looked
+  filled but host state stayed empty).
+- **Framework interop:** reflecting **property setters** for `endpoint`,
+  `toolDisplay`, and `collapsed` (React 19 assigns matching props as element
+  properties — getter-only props previously threw).
+- `registerTool` is now **idempotent** — re-registering a tool name replaces it
+  instead of throwing (re-fired refs / React StrictMode).
+
+### Fixed
+- The Markdown/HTML allowlist now permits sanitised **`<img>`** (safe-scheme
+  `src`, no event handlers); `javascript:` srcs and disallowed tags (e.g.
+  `iframe`) are still stripped.
+
 ## [0.1.1] — 2026-06-01
 
 ### Changed
@@ -33,6 +129,8 @@ 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.1.1...HEAD
+[Unreleased]: https://github.com/Artui/ag-ui-web-component/compare/v0.2.1...HEAD
+[0.2.1]: https://github.com/Artui/ag-ui-web-component/compare/v0.2.0...v0.2.1
+[0.2.0]: https://github.com/Artui/ag-ui-web-component/compare/v0.1.1...v0.2.0
 [0.1.1]: https://github.com/Artui/ag-ui-web-component/compare/v0.1.0...v0.1.1
 [0.1.0]: https://github.com/Artui/ag-ui-web-component/releases/tag/v0.1.0

package/README.md

@@ -17,8 +17,13 @@ It wraps [`@ag-ui/client`](https://www.npmjs.com/package/@ag-ui/client)'s `HttpA
 - Generic **DOM-driver primitives** (`fillField`, `clickElement`, `setControlValue`) and
   **animation primitives** (`typeInto`, `highlightThenClick`, …) so the agent can drive the page
   at human-readable speed.
-- A **confirmation modal** that intercepts destructive tool calls (those whose JSON Schema
-  carries `x-destructive: true`) before the handler runs.
+- An **inline confirmation card** that intercepts tool calls needing confirmation (those whose
+  JSON Schema carries `x-destructive: true`, or a per-call `confirmPredicate`) before the handler
+  runs — rendered right in the transcript, never a modal overlay.
+- **Markdown + HTML rendering** of assistant replies (sanitized `marked` + DOMPurify), with
+  themes, density/placement presets, incoming-text animations, tool-call display modes, an
+  animated thinking indicator, and an opt-in **skills** palette (prompt chips + `/`-commands).
+- A **new-chat** button and a **collapse** toggle built into the header.
 - An **MPA durability story**: a durable conversation store, a stable thread id, and a resumable
   run loop that survives full page reloads (`x-navigates` + `navigationResult`).
 - **Host seams** for SPAs: a route map, an auto-injected page map, state hooks, and an optional
@@ -36,12 +41,16 @@ No framework, no Django, no admin specifics live here. Downstream consumers (e.g
 - [Core concepts](#core-concepts)
   - [The run loop and the AG-UI client](#the-run-loop-and-the-ag-ui-client)
   - [Registering tools](#registering-tools)
-  - [The confirmation modal (`x-destructive`)](#the-confirmation-modal-x-destructive)
+  - [Inline confirmation (`x-destructive` / `x-confirm` / `confirmPredicate`)](#inline-confirmation-x-destructive--x-confirm--confirmpredicate)
   - [DOM-driver and animation primitives](#dom-driver-and-animation-primitives)
+- [New chat and collapse](#new-chat-and-collapse)
+- [Tool-call display modes](#tool-call-display-modes)
+- [Markdown rendering](#markdown-rendering)
+- [Skills: prompt chips and slash palette](#skills-prompt-chips-and-slash-palette)
 - [MPA durability: surviving full page reloads](#mpa-durability-surviving-full-page-reloads)
 - [Host seams: the SPA story](#host-seams-the-spa-story)
 - [Public API surface](#public-api-surface)
-- [Theming](#theming)
+- [Theming, density, and placement](#theming-density-and-placement)
 - [Building the bundle](#building-the-bundle)
 - [Compatibility](#compatibility)
 
@@ -110,7 +119,7 @@ Drop the element into your page and register the tools the agent may call:
   });
 
   // A destructive tool: x-destructive at the JSON-Schema root gates it behind
-  // the confirmation modal before the handler runs.
+  // the inline confirmation card before the handler runs.
   chat.registerTool({
     name: "save_article",
     description: "Save the article. Destructive — asks for confirmation.",
@@ -130,14 +139,32 @@ That's the whole integration: an `endpoint` attribute pointing at your AG-UI ser
 
 ### Attributes and properties
 
+**Attributes** (set in HTML; the CSS-only ones are styling presets with no JS API):
+
 | Attribute | Property | Notes |
 | --- | --- | --- |
-| `endpoint` | `endpoint` (getter) | The AG-UI endpoint URL. Required to send. |
-| `title-text` | — | Header label; defaults to `"Assistant"`. |
-| — | `headers` | `Record<string, string>` of extra HTTP headers. |
-| — | `autoConfirm` | When `true`, destructive tools run without the modal. |
-
-A self-contained working example lives in [`demo/`](demo/) — run `make demo` to serve it against a
+| `endpoint` | `endpoint` | The AG-UI endpoint URL. Required to send. Reflecting getter + setter. |
+| `title-text` | — | Header label; defaults to `"Assistant"`. The only **observed** attribute (live-updates the header). |
+| `data-tool-display` | `toolDisplay` | Tool-call card detail: `minimal` / `compact` / `full` (default `full`). |
+| `data-text-animation` | — | Incoming-text reveal: `none` (default) / `fade` / `word`. |
+| `data-prompt-chips` | — | `"true"` to surface skills as chips. |
+| `data-slash-commands` | — | `"true"` to enable the `/`-command palette. |
+| `data-skills` | — | Inline JSON skill catalog. |
+| `data-skills-url` | — | URL of a JSON skill catalog (fetched with `headers`). |
+| `collapsed` | `collapsed` | Reflected boolean; collapses the widget. Persisted per-tab in `sessionStorage`. |
+| `theme` | — | CSS-only: `light` (default) / `dark` / `auto` / `code`. |
+| `density` | — | CSS-only: `comfortable` (default) / `compact`. |
+| `placement` | — | CSS-only: `floating` (default) / `bottom-left` / `side` / `full` / `embedded`. |
+
+**Properties** (JS only, not attributes): `headers`, `autoConfirm`, `confirmPredicate`,
+`agentFactory`, `getTools`, `getContext`, `routeMap`, `navigate`, `getPageMap`,
+`autoInjectPageMap`, `conversationStore`, `navigationResult`, `skillContext`, plus the mirrors
+`endpoint` / `toolDisplay` / `collapsed`.
+
+**Methods**: `registerTool`, `registerStateHook`, `setSkills`, `appendMessage`, `newChat`,
+`setCollapsed`, `toggleCollapsed`.
+
+A self-contained live playground lives in [`demo/`](demo/) — run `make demo` to serve it against a
 mock AG-UI server.
 
 ---
@@ -146,9 +173,9 @@ mock AG-UI server.
 
 ### The run loop and the AG-UI client
 
-`<ag-ui-chat>` is the view; [`AgUiClient`](src/agui_client.ts) is the orchestration layer over an
-AG-UI `AbstractAgent`. On the first send the element builds a client (via the overridable
-`agentFactory`, which defaults to [`createHttpAgent`](src/create_http_agent.ts)). Each turn:
+`<ag-ui-chat>` is the view; [`AgUiClient`](src/core/agui_client.ts) is the orchestration layer over
+an AG-UI `AbstractAgent`. On the first send the element builds a client (via the overridable
+`agentFactory`, which defaults to [`createHttpAgent`](src/core/create_http_agent.ts)). Each turn:
 
 1. The user message is appended and the agent runs once.
 2. AG-UI subscriber events are translated into the element's handlers — streaming text deltas
@@ -158,8 +185,10 @@ AG-UI `AbstractAgent`. On the first send the element builds a client (via the ov
 4. This repeats until the agent stops calling frontend tools, bounded by `MAX_TOOL_ROUNDS`.
 
 Tool calls the client doesn't own (server-side tools the server already executed) are left alone —
-the loop doesn't re-run them. The current tool catalog and context are read **fresh on every run**
-(`getTools()` / `getContext()`), so they always reflect the current page state.
+the loop doesn't re-run them, but their streamed `TOOL_CALL_RESULT` is rendered into the tool-call
+card (honouring `data-tool-display`), so server-side output is visible too. The current tool catalog
+and context are read **fresh on every run** (`getTools()` / `getContext()`), so they always reflect
+the current page state.
 
 ### Registering tools
 
@@ -184,48 +213,181 @@ Names must be unique (registering a duplicate throws). Each `<ag-ui-chat>` eleme
 registry, AG-UI client, and Shadow DOM, so **multiple instances on one page never interfere** —
 there is no module-level shared state anywhere in the package.
 
-### The confirmation modal (`x-destructive`)
+### Inline confirmation (`x-destructive` / `x-confirm` / `confirmPredicate`)
+
+When a tool call needs confirmation, the element appends an **inline confirmation card** (a
+`<div class="confirm">`) to the transcript via
+[`requestConfirmation`](src/ui/confirmation_card.ts) — it is not a modal overlay. The card reads
+naturally after the assistant's explanation, never steals focus from the page, and stays in the
+transcript as a resolved record after the decision:
+
+- **Confirm** → the handler runs and the result is posted back.
+- **Cancel** → a `"User declined the action."` result is posted; the agent acknowledges on its
+  next turn.
+
+Whether a call is gated is decided in this order:
+
+1. If `chat.autoConfirm === true`, the call **never** prompts (an "autopilot" toggle).
+2. Else if `chat.confirmPredicate` is set, its boolean return is authoritative — given the tool
+   name + parsed args it decides per-call (so one tool can be instant for some args and confirmed
+   for others, which a static flag can't express).
+3. Else the element falls back to [`isDestructive(parameters)`](src/tools/is_destructive.ts),
+   which reads the `x-destructive` JSON-Schema flag.
 
 AG-UI has no built-in risk flag, so destructiveness is carried as a JSON-Schema extension at the
 **schema root**: `parameters["x-destructive"] = true` (use the exported `X_DESTRUCTIVE_KEY`
-constant). There is no parallel metadata channel — the flag lives on the schema, the registry
-forwards it verbatim to `RunAgentInput.tools`, and [`isDestructive`](src/is_destructive.ts) reads
-it back.
+constant). There is no parallel metadata channel and no name heuristic — destructiveness is exactly
+the `x-destructive` flag (or `confirmPredicate`). The registry forwards the flag verbatim to
+`RunAgentInput.tools`.
 
-When the agent calls a destructive tool, the element shows the
-[confirmation modal](src/confirmation_modal.ts) (rendered inside its own Shadow DOM) **before**
-dispatching to the handler:
+If the schema carries an `x-confirm` string (use `X_CONFIRM_KEY`), the card shows it as the prompt;
+otherwise it falls back to a generic `Run "<tool>"?`.
 
-- **Confirm** → the handler runs and the result is posted back.
-- **Cancel / dismiss** → a `"User declined the action."` result is posted; the agent acknowledges
-  on its next turn.
+```js
+// Per-call: confirm a delete only when it would remove more than one row.
+chat.confirmPredicate = (name, args) =>
+  name === "delete_rows" && Array.isArray(args.ids) && args.ids.length > 1;
 
-Set `chat.autoConfirm = true` to bypass the modal (an "autopilot" toggle).
+// Prompt text via x-confirm:
+chat.registerTool({
+  name: "activate_project",
+  description: "Activate the current project.",
+  parameters: { type: "object", properties: {}, [X_DESTRUCTIVE_KEY]: true, [X_CONFIRM_KEY]: "Activate this project?" },
+  handler: async () => await api.activate(),
+});
+```
 
 ### DOM-driver and animation primitives
 
 So the agent can visibly drive the host page, the package ships generic, framework-free
-primitives. The **animation** primitives ([`animations.ts`](src/animations.ts)) operate at
+primitives. The **animation** primitives ([`animations.ts`](src/dom/animations.ts)) operate at
 human-readable speed (configurable; pass small/zero durations in tests):
 
 - `typeInto(el, value, { charDelayMs })` — clears and types a value character by character,
   firing `input`/`change` events as a real user would.
-- `highlightThenClick(el, { highlightMs })` — outlines an element, pauses, then clicks.
+- `highlightThenClick(el, { highlightMs })` / `pressThenClick(el, options)` — outline/press an
+  element, pause, then click.
+- `selectOption(el, value)` / `toggleControl(el, checked)` — animate a `<select>` / checkbox.
 - `scrollIntoCenterView(el)` / `focusWithFlash(el, { flashMs })`.
+- `prefersReducedMotion()` — honoured throughout so animations collapse to instant when the user
+  asks for reduced motion.
 
-The **DOM-driver** primitives ([`dom_driver.ts`](src/dom_driver.ts)) compose those into the
+The **DOM-driver** primitives ([`dom_driver.ts`](src/dom/dom_driver.ts)) compose those into the
 operations a tool handler typically wants:
 
 - `fillField(el, value, options)` — scroll to, focus-flash, and type into a text field.
-- `clickElement(el, options)` — scroll to, highlight, and click.
+- `clickElement(el, options)` / `pressButton(el, options)` — scroll to, highlight/press, and click.
+- `selectControl(el, value)` / `toggleCheckbox(el, checked)` — animate a `<select>` / checkbox.
 - `setControlValue(el, value)` — set a `<select>` or checkbox without animation, dispatching
   `input`/`change`.
 
+The native-setter helpers ([`native_setter.ts`](src/dom/native_setter.ts)) — `setNativeValue` /
+`setNativeChecked` — set a control through its native prototype setter so React-controlled inputs
+register the change.
+
 Each takes an element the caller has already located; host packages wrap them with
 environment-aware lookups (e.g. "find `#id_<name>`, then `fillField`").
 
 ---
 
+## New chat and collapse
+
+The header carries two built-in buttons: a new-chat (✚) button and a collapse (—) toggle. The
+matching JS API:
+
+- `newChat()` — clears the transcript and the persisted history, drops the in-memory run state,
+  and mints a new thread id.
+- `setCollapsed(collapsed)` / `toggleCollapsed()` — collapse or expand the widget. The state is
+  reflected as the boolean `collapsed` attribute/property and persisted per-tab in
+  `sessionStorage`, so it survives a reload.
+
+Each change emits an `ag-ui-toggle` event (the `TOGGLE_EVENT` constant) with
+`detail: { collapsed: boolean }` (typed `ToggleDetail`), so a host can mirror the state in its own
+chrome — or hide the built-in toggle and drive the `collapsed` attribute itself.
+
+```js
+chat.newChat();
+chat.toggleCollapsed();
+chat.addEventListener("ag-ui-toggle", (e) => console.log(e.detail.collapsed));
+```
+
+---
+
+## Tool-call display modes
+
+How much a tool-call card shows is set via the `data-tool-display` attribute (or `toolDisplay`
+property), one of `minimal` / `compact` / `full` (default `full`):
+
+- `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).
+
+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.
+
+```html
+<ag-ui-chat endpoint="/agent/" data-tool-display="compact"></ag-ui-chat>
+```
+
+---
+
+## Markdown rendering
+
+Assistant bubbles render sanitized markdown/HTML via [`marked`](https://www.npmjs.com/package/marked)
+(GitHub-flavoured, single-newline line breaks) piped through
+[DOMPurify](https://www.npmjs.com/package/dompurify). User messages stay literal text. The
+allowlist permits emphasis, code, lists, quotes, headings, links, tables, and images (`img`); links
+are hardened with `target="_blank" rel="noopener noreferrer"`; `iframe`/`style`/scripting are
+excluded. The exported helper `renderMarkdown(text)` does this standalone. `marked` and `dompurify`
+are runtime dependencies.
+
+An animated 3-dot "thinking" indicator (`role="status"`, with an aria-label) appears before the
+first token and between tool rounds, honouring `prefers-reduced-motion`. It has no public API.
+
+### Incoming-text animations
+
+The `data-text-animation` attribute controls how a fully-received assistant message reveals:
+`none` (default) / `fade` (a CSS fade) / `word` (JS word-by-word via the internal `wrapWords`
+reveal). It honours `prefers-reduced-motion` (collapsing to instant).
+
+```html
+<ag-ui-chat endpoint="/agent/" data-text-animation="word"></ag-ui-chat>
+```
+
+---
+
+## Skills: prompt chips and slash palette
+
+Skills are pre-defined prompts the user can launch from a chip or the `/`-command palette. They are
+opt-in via two attributes:
+
+```html
+<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
+from three sources — **backend → embed → client** (later wins by `name`):
+
+- `data-skills-url` — a JSON endpoint, fetched with the element's `headers`.
+- `data-skills` — an inline JSON catalog.
+- `setSkills(skills)` — set the client catalog from JS.
+
+```js
+chat.setSkills([
+  { name: "summarize", title: "Summarize page", prompt: "Summarize {title}.", chip: true },
+]);
+```
+
+A skill `prompt` may contain `{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.
+
+```js
+chat.skillContext = () => ({ title: document.title });
+```
+
+---
+
 ## MPA durability: surviving full page reloads
 
 In a multi-page app, a tool that navigates reloads the whole page and destroys the in-memory run
@@ -234,10 +396,10 @@ mechanisms.
 
 **1. Thread identity.** AG-UI's `thread_id` is the conversation key. It is generated once and
 persisted (so the element reattaches after a reload) by the
-[`ClientConversationStore`](src/conversation_store.ts).
+[`ClientConversationStore`](src/core/conversation_store.ts).
 
 **2. Durable conversation.** A pluggable `ClientConversationStore` holds the message list. The
-default [`SessionStorageStore`](src/conversation_store.ts) keeps everything per-tab in
+default [`SessionStorageStore`](src/core/conversation_store.ts) keeps everything per-tab in
 `sessionStorage`, so the chat survives full page reloads and clears on tab close. `loadMessages`
 is async-friendly, so a host can inject a server-backed store (e.g. one that rehydrates from a
 history endpoint) for cross-tab/device durability:
@@ -246,10 +408,12 @@ history endpoint) for cross-tab/device durability:
 chat.conversationStore = new MyServerBackedStore();
 ```
 
-On mount the element rehydrates the transcript from the store, so the chat looks continuous.
+On mount the element rehydrates the transcript from the store, so the chat looks continuous —
+including tool-call cards and their results (reconstructed from the persisted `toolCalls` and `tool`
+messages), not just the text turns.
 
 **3. Resumable loop (`x-navigates` + `navigationResult`).** A tool whose schema carries
-`x-navigates: true` (use `X_NAVIGATES_KEY`; read back by [`isNavigates`](src/is_navigates.ts))
+`x-navigates: true` (use `X_NAVIGATES_KEY`; read back by [`isNavigates`](src/tools/is_navigates.ts))
 triggers a full reload. Before the handler navigates, the element writes a checkpoint
 (`{ toolCallId }`) to the store. On the next page mount it:
 
@@ -276,10 +440,16 @@ rather than by exploring:
 - `list_routes` — read-only; lists the routes.
 - `navigate_to_route(route_id, params?)` — resolves the id to a path and navigates.
 
+A route `path` may contain `:param` segments — e.g. `/projects/:id/users/:userId/`.
+`navigate_to_route` substitutes the path params (URL-encoded) and sends any leftover params as a
+query string; a missing or empty required path param throws. The resolved shape is the exported
+`RouteWithParams` type.
+
 ```js
 chat.routeMap = [
   { id: "users", path: "/users", title: "Users", description: "Manage user accounts" },
   { id: "billing", path: "/billing", title: "Billing" },
+  { id: "user-detail", path: "/projects/:id/users/:userId/", title: "User detail" },
 ];
 ```
 
@@ -333,6 +503,7 @@ re-export point. Internal modules import from leaf paths.
 | `defineAgUiChat()` | function | Idempotently register the element. |
 | `MessageRole` | type | Role of a rendered chat message. |
 | `SubmitDetail` | type | `detail` shape of the submit event. |
+| `ToggleDetail` | type | `detail` shape of the `ag-ui-toggle` event (`{ collapsed }`). |
 
 ### AG-UI client & agent
 
@@ -360,10 +531,12 @@ re-export point. Internal modules import from leaf paths.
 | --- | --- | --- |
 | `createRouteTools(...)` | function | Build the built-in `route.*` tools. |
 | `Route` / `RouteMap` | type | Navigable-route shapes. |
+| `RouteWithParams` | type | A route resolved with `:param` path segments + leftover query params. |
 | `createPageMapContext(...)` | function | Build the per-run `page_map` context entry. |
 | `PageMap` | type | The compact page-surface shape. |
 | `createStateHookTools(hook)` | function | Build `read_<name>` / `set_<name>` tools. |
 | `StateHook` | type | A state-binding declaration. |
+| `Skill` | type | A launchable prompt (chip / `/`-command). |
 
 ### Durability
 
@@ -378,12 +551,14 @@ re-export point. Internal modules import from leaf paths.
 | Export | Kind | Summary |
 | --- | --- | --- |
 | `ToolCallCard` | class | A live tool-call card for the transcript. |
-| `ToolCallStatus` / `SettledStatus` | type | Card lifecycle states. |
-| `requestConfirmation(host, request)` | function | Render the confirmation modal. |
-| `ConfirmationRequest` | type | What the modal displays. |
-| `typeInto` / `highlightThenClick` / `scrollIntoCenterView` / `focusWithFlash` | function | Animation primitives. |
-| `fillField` / `clickElement` / `setControlValue` | function | DOM-driver primitives. |
-| `TypeOptions` / `HighlightClickOptions` / `FlashOptions` / `FillFieldOptions` / `TextLikeElement` | type | Primitive option shapes. |
+| `ToolCallStatus` / `SettledStatus` / `ToolDisplayMode` | type | Card lifecycle states + display mode. |
+| `requestConfirmation(host, request)` | function | Append the inline confirmation card to the transcript. |
+| `ConfirmationRequest` | type | What the card displays. |
+| `renderMarkdown(text)` | function | Render sanitized markdown/HTML (marked + DOMPurify). |
+| `typeInto` / `highlightThenClick` / `pressThenClick` / `selectOption` / `toggleControl` / `scrollIntoCenterView` / `focusWithFlash` / `prefersReducedMotion` | function | Animation primitives. |
+| `fillField` / `clickElement` / `pressButton` / `selectControl` / `setControlValue` / `toggleCheckbox` | function | DOM-driver primitives. |
+| `setNativeValue` / `setNativeChecked` | function | Set a control via its native prototype setter (React-controlled inputs). |
+| `TypeOptions` / `HighlightClickOptions` / `PressOptions` / `SelectOptions` / `ToggleOptions` / `FlashOptions` / `FillFieldOptions` / `TextLikeElement` | type | Primitive option shapes. |
 
 ### Constants
 
@@ -391,17 +566,22 @@ re-export point. Internal modules import from leaf paths.
 | --- | --- |
 | `ELEMENT_TAG` | The registered tag name (`ag-ui-chat`). |
 | `SUBMIT_EVENT` | The submit CustomEvent name. |
+| `TOGGLE_EVENT` | The collapse-toggle CustomEvent name (`ag-ui-toggle`). |
 | `MESSAGE_ROLE` | Message role constants. |
 | `TOOL_CALL_STATUS` | Tool-call card status constants. |
+| `TOOL_DISPLAY` | Tool-call display-mode constants (`minimal` / `compact` / `full`). |
+| `X_CONFIRM_KEY` | JSON-Schema key carrying a confirmation prompt. |
+| `X_SUMMARY_KEY` | JSON-Schema key carrying a short tool-card label. |
 | `MAX_TOOL_ROUNDS` | Upper bound on tool-call → re-run rounds per send. |
 | `VERSION` | The package version string. |
 
 ---
 
-## Theming
+## Theming, density, and placement
 
-The chat shell is styled inside its Shadow DOM and exposes CSS custom properties on `:host`, so you
-theme it from outside without piercing the shadow boundary. A few of the knobs:
+The chat shell is styled inside its Shadow DOM and exposes a large set of `--ag-ui-*` CSS custom
+properties on `:host` (colors, status, surface, spacing, layout), so you theme it from outside
+without piercing the shadow boundary. A few of the knobs:
 
 ```css
 ag-ui-chat {
@@ -410,8 +590,7 @@ ag-ui-chat {
   --ag-ui-fg: #1a1a2e;
   --ag-ui-radius: 12px;
 
-  /* Layout — float (default) or embed in your own flow with --ag-ui-position: static */
-  --ag-ui-position: fixed;
+  /* Layout */
   --ag-ui-width: 380px;
   --ag-ui-height: 560px;
   --ag-ui-inset: auto 24px 24px auto;
@@ -419,8 +598,21 @@ ag-ui-chat {
 }
 ```
 
-See [`src/styles.ts`](src/styles.ts) for the full list, and [`demo/themes/`](demo/themes/) for
-worked examples (default, dark, embedded, and a "claude" theme).
+For the common cases there are three CSS-reactive **preset attributes** (no JS API), so you don't
+have to hand-tune the variables:
+
+- `theme` — `light` (default) / `dark` / `auto` (follow the OS) / `code`.
+- `density` — `comfortable` (default) / `compact`.
+- `placement` — `floating` (default) / `bottom-left` / `side` / `full` / `embedded`. `embedded`
+  drops the fixed positioning and z-index so the widget sits in normal document flow.
+
+```html
+<ag-ui-chat endpoint="/agent/" theme="dark" density="compact" placement="side"></ag-ui-chat>
+```
+
+See [`src/ui/styles.ts`](src/ui/styles.ts) for the full variable + preset list. The
+[`demo/`](demo/) live playground (`node demo/mock-server.mjs`) flips theme, density, placement,
+text-animation, and tool-display live from a single page.
 
 ---
 
@@ -449,7 +641,7 @@ Other workflow targets (all identical in name to the sibling Python packages):
 | `make test` | Vitest with a 100% line + branch + function + statement coverage gate. |
 | `make lint` | `biome check .` + `tsc --noEmit`. |
 | `make format` | `biome format --write .`. |
-| `make demo` | Build, then serve `demo/` against a mock AG-UI server. |
+| `make demo` | Build, then serve the live playground (`demo/themes/index.html`) on port 5173 via `demo/mock-server.mjs`. |
 
 ---
 
@@ -457,7 +649,7 @@ Other workflow targets (all identical in name to the sibling Python packages):
 
 | Component | Floor | Tested |
 | --- | --- | --- |
-| Node (tooling/tests only) | 20 | 20, 22, 24 |
+| Node (tooling/tests only) | 22 | 22, 24 |
 | Browsers (runtime target) | ES2022 / evergreen | Chrome / Firefox / Safari 17+ |
 | `@ag-ui/client` | latest 0.x | — |