@artooi/ag-ui-web-component 0.12.0 → 0.13.0

package/CHANGELOG.md

@@ -7,6 +7,56 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.13.0] — 2026-07-27
+
+### Added
+
+- **AG-UI shared state.** `<ag-ui-chat>` now speaks the protocol's own state
+  channel: assign `chat.sharedState = {...}` to seed it, listen for the
+  `ag-ui-state` event (`detail.state`) to react when the agent changes it.
+  State rides `RunAgentInput.state` on every run and is replaced in place when
+  the server streams `STATE_SNAPSHOT` / `STATE_DELTA`.
+  - **Adoption, not implementation.** `@ag-ui/client` already applies both
+    events to `agent.state` and exposes an `onStateChanged` subscriber hook;
+    what was missing was seeding it (`initialState`) and surfacing it to the
+    host. Deriving state from the raw event stream ourselves would have
+    duplicated — and eventually contradicted — the client's own handling,
+    including its JSON-Patch delta application.
+  - Assigning **after** the conversation has started pushes through to the live
+    agent rather than waiting for a new one, so a host that seeds state late
+    isn't silently stranded.
+  - The event is `composed: true`, so a host listening on `document` receives it
+    through the shadow boundary.
+  - **Distinct from `registerPageState`**, which exposes host state to the agent
+    as ordinary *tools*. Use shared state when agent and page edit the same
+    object; use page-state tools when the agent should *ask* — a tool call is
+    visible in the transcript and can be gated by a confirmation card, which
+    state events cannot.
+
+### Changed
+
+- **`registerStateHook` is now `registerPageState`** (and `createStateHookTools` /
+  `StateHook` are `createPageStateTools` / `PageState`). **The old names implied a
+  feature that does not exist**: they read as AG-UI shared-state sync —
+  `STATE_SNAPSHOT` / `STATE_DELTA`, the protocol events that carry a state object
+  between agent and client — which neither this component nor `django-ag-ui`
+  implements. What the method actually does is generate two ordinary client tools
+  (`read_<name>` / `set_<name>`) over host page state, which the agent calls like
+  any other tool. `page` matches the vocabulary already used throughout the
+  component (`page_map`, `page_action_tools`, `route_map`, the DOM driver).
+  - **Not a hard break.** The old spellings are kept as deprecated aliases and
+    behave identically; they will be removed in a future major. A rename is only
+    ever cheaper the earlier it happens, which is why this ships now rather than
+    waiting for state support to exist.
+
+### Documentation
+
+- **The README now distinguishes the two state mechanisms**, which the old
+  method name conflated. `sharedState` is the protocol's state channel;
+  `registerPageState` generates ordinary client tools. The rename and the
+  feature landed together, so the docs answer "which one" rather than leaving
+  two similar names side by side.
+
 ## [0.12.0] — 2026-07-27
 
 ### Added
@@ -528,7 +578,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.12.0...HEAD
+[Unreleased]: https://github.com/Artui/ag-ui-web-component/compare/v0.13.0...HEAD
+[0.13.0]: https://github.com/Artui/ag-ui-web-component/compare/v0.12.0...v0.13.0
 [0.12.0]: https://github.com/Artui/ag-ui-web-component/compare/v0.11.0...v0.12.0
 [0.11.0]: https://github.com/Artui/ag-ui-web-component/compare/v0.10.0...v0.11.0
 [0.10.0]: https://github.com/Artui/ag-ui-web-component/compare/v0.9.0...v0.10.0

package/README.md

@@ -191,7 +191,9 @@ the django-ag-ui `@tool` registry), whose schema never reaches the browser — e
 labels are fetched automatically — per card, `x-summary` → an explicit
 `toolSummaries` entry → the fetched catalog → the raw name.
 
-**Methods**: `registerTool`, `registerStateHook`, `setSkills`, `appendMessage`, `newChat`,
+**Properties** (selected): `sharedState` — AG-UI shared state (documented under Tools & state).
+
+**Methods**: `registerTool`, `registerPageState`, `setSkills`, `appendMessage`, `newChat`,
 `setCollapsed`, `toggleCollapsed`.
 
 A self-contained live playground lives in [`demo/`](demo/) — run `make demo` to serve it against a
@@ -621,12 +623,12 @@ so it reflects the page the agent is currently looking at:
 chat.getPageMap = () => ({ fields: introspectForm(), buttons: visibleButtons() });
 ```
 
-**`registerStateHook({ name, read, write?, schema? })`** — ergonomic sugar over `registerTool` for
+**`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`:
 
 ```js
-chat.registerStateHook({
+chat.registerPageState({
   name: "cart",
   read: () => store.getState().cart,
   write: ({ items }) => store.dispatch(setCart(items)),
@@ -634,6 +636,42 @@ chat.registerStateHook({
 });
 ```
 
+**This is not AG-UI shared state** — that is `sharedState`, below. `registerPageState` generates two
+ordinary client tools; the agent reads or writes your store by *calling a tool*. The method was
+called `registerStateHook` through 0.12, a name that read as protocol state sync; the old spelling
+still works and is deprecated.
+
+**`sharedState`** *(property)* — AG-UI **shared state**: the protocol's own state channel, sent as
+`RunAgentInput.state` on every run and replaced in place when the server streams `STATE_SNAPSHOT` /
+`STATE_DELTA`. Assign to seed it, listen for `ag-ui-state` to react:
+
+```js
+chat.sharedState = { document: "" };
+
+chat.addEventListener("ag-ui-state", (e) => {
+  editor.value = e.detail.state.document;   // the agent rewrote it
+});
+```
+
+Server-side, a tool mutates `ctx.deps.state` and returns the snapshot as `ToolReturn` metadata —
+pydantic-ai does not emit deltas for you:
+
+```python
+@tool(registry)
+async def write_document(ctx: RunContext[AgentDeps], body: str) -> ToolReturn:
+    """Replace the shared document."""
+    ctx.deps.state = {**(ctx.deps.state or {}), "document": body}
+    return ToolReturn(
+        return_value="written",
+        metadata=[StateSnapshotEvent(type=EventType.STATE_SNAPSHOT, snapshot=ctx.deps.state)],
+    )
+```
+
+Use this when the agent and the page are editing **the same object** (a document, a form, a
+canvas). Use `registerPageState` when the agent should *ask* for a value or *request* a change —
+the tool call is visible in the transcript and can be gated by a confirmation card, which state
+events cannot.
+
 **`navigate(path): void`** *(optional)* — a host routing callback. **This single seam is what
 distinguishes an SPA from an MPA.** When set, `navigate_to_route` routes client-side (no reload) and
 the in-memory run loop simply continues — the whole resumable-loop / checkpoint machinery is
@@ -798,8 +836,8 @@ re-export point. Internal modules import from leaf paths.
 | `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. |
+| `createPageStateTools(binding)` | function | Build `read_<name>` / `set_<name>` tools. |
+| `PageState` | type | A page-state binding declaration. |
 | `Skill` | type | A launchable prompt (chip / `/`-command). |
 
 ### Durability