@assistant-ui/mcp-docs-server 0.1.34 → 0.1.36

package/.docs/raw/docs/tools/interactables.mdx

@@ -1,45 +1,58 @@
 ---
-title: Interactable Components
-description: Build persistent UI elements whose state the AI can read and update — copilot interactables in React with assistant-ui for forms, dashboards, and tools.
+title: Interactable Tool UIs
+description: Build stateful components and tool UIs that both the user and the model can read and edit. Render them beside the thread, or inside messages as versioned, editable surfaces like notepads and artifacts.
 platforms: ["react"]
 ---
 
 import { InteractableSample } from "@/components/docs/samples/interactable";
 
-Interactables are React components that live outside the chat message flow and have state that both the user and the AI can read and write. This enables AI-driven UI patterns where the assistant controls parts of your application beyond the chat window.
+Interactables allow both agents and users to read and edit tool UIs and components. They can be in-thread tool UIs like an email composer, or app-scoped components, like artifacts, task boards, or settings panels.
 
 <InteractableSample />
 
 ## Overview
 
-Unlike regular tool UIs that appear inline within messages, interactables:
+### Types of Interactables
 
-- **Persist across messages** — they live outside the chat thread
-- **Have shared state** — both the user (via React) and the AI (via auto-generated tools) can update them
-- **Support partial updates** — the AI only needs to send the fields it wants to change
-- **Are developer-placed** — you decide where they render in your app
-- **Auto-register tools** — the AI automatically gets a tool to update each interactable's state
+- **App-scoped:** a component you mount yourself with `unstable_useInteractable`, anywhere in your app (a sidebar, a panel, wherever). The model automatically gets an `update_{name}` tool to read and edit it, and its state can persist across threads.
+- **Thread-scoped:** an interactable tool UI the model can call in-thread. You define it with `unstable_interactableTool` inside `defineToolkit`, and it renders inline when called.
 
-Common use cases:
+### Features
 
-- Task boards that the AI can add items to
-- Data dashboards that update based on conversation
-- Forms that the AI pre-fills
-- Canvas/editor components that the AI can manipulate
+- **Shared, editable state**: the user (via React) and the model (via the auto-generated `update_{name}` tool) both write to the same state, and each sees the other's edits.
+- **Streaming and partial updates**: updates are streamed to the interactable, and the model only needs to update the fields it wants to change.
+- **Versioning and history**: each user edit and model `update_*` is recorded as a version you can display, list, and `restore()` ([Versions](#versions))
+- **Persistent**: state outlives the tool call and the turn, and can survive a reload (thread-scoped via thread history; app-scoped with a persistence adapter).
+- **Auto-generated update tools:** based on the interactable's state schema, an `update_{name}` tool is generated for the model to update and edit it.
+
+### Use Cases
+
+- Settings panels or dashboards the agent can edit and interact with
+- Collaborative task lists, sticky notes, document editors
+- Making artifacts editable and versioned
+- Anything else, **any React component can be an interactable!**
 
 ## Quick Start
 
-### 1. Register the Interactables scope
+<Steps>
+<Step>
+
+### Register the interactables scope
 
 ```tsx
-import { useAui, Interactables, AssistantRuntimeProvider } from "@assistant-ui/react";
+import {
+  useAui,
+  unstable_Interactables,
+  AssistantRuntimeProvider,
+  Tools,
+} from "@assistant-ui/react";
 import { useChatRuntime } from "@assistant-ui/react-ai-sdk";
 
 function MyRuntimeProvider({ children }: { children: React.ReactNode }) {
   const runtime = useChatRuntime();
 
   const aui = useAui({
-    interactables: Interactables(),
+    unstable_interactables: unstable_Interactables(), // [!code ++]
   });
 
   return (
@@ -50,277 +63,577 @@ function MyRuntimeProvider({ children }: { children: React.ReactNode }) {
 }
 ```
 
-### 2. Create an interactable
-
-<Callout type="warn">
-  Define the `stateSchema` and `initialState` **outside** the component (or
-  memoize them). Creating a new schema on every render will cause the
-  interactable to re-register and reset its state.
+<Callout type="idea">
+  The legacy `interactables: Interactables()` scope and the new
+  `unstable_interactables: unstable_Interactables()` scope are mutually
+  exclusive. Mount only one interactables API in a single `useAui` provider.
 </Callout>
 
+This scope is needed for both kinds of interactable. Thread-scoped interactables also live in a toolkit, which you register with `Tools` (shown below).
+
+</Step>
+<Step>
+
+### Define an interactable
+
+Pick the path that matches who creates it.
+
+<Tabs items={["App-scoped", "Thread-scoped"]}>
+<Tab>
+
+A component you mount yourself. Define it with `unstable_useInteractable` where you render it (a sidebar, a panel, wherever).
+
 ```tsx
-import { useAssistantInteractable, useInteractableState } from "@assistant-ui/react";
+import { unstable_useInteractable } from "@assistant-ui/react";
 import { z } from "zod";
 
 const taskBoardSchema = z.object({
   tasks: z.array(
-    z.object({
-      id: z.string(),
-      title: z.string(),
-      done: z.boolean(),
-    }),
+    z.object({ id: z.string(), title: z.string(), done: z.boolean() }),
   ),
 });
 
-const taskBoardInitialState = { tasks: [] };
-
 function TaskBoard() {
-  const id = useAssistantInteractable("taskBoard", {
-    description: "A task board showing the user's tasks",
+  const [state, { setState }] = unstable_useInteractable("taskBoard", {
+    description:
+      "A task board panel that lists tasks. Use update_taskBoard with tasks.add/update/remove/clear to manage tasks. New tasks need a title and done=false.",
     stateSchema: taskBoardSchema,
-    initialState: taskBoardInitialState,
+    initialState: { tasks: [] },
   });
-  const [state, { setState }] = useInteractableState(id, taskBoardInitialState);
 
   return (
-    <div>
-      <h2>Tasks</h2>
-      <ul>
-        {state.tasks.map((task) => (
-          <li key={task.id}>
-            <label>
-              <input
-                type="checkbox"
-                checked={task.done}
-                onChange={() =>
-                  setState((prev) => ({
-                    tasks: prev.tasks.map((t) =>
-                      t.id === task.id ? { ...t, done: !t.done } : t,
-                    ),
-                  }))
-                }
-              />
-              {task.title}
-            </label>
-          </li>
-        ))}
-      </ul>
-    </div>
+    <ul>
+      {state.tasks.map((task) => (
+        <li key={task.id}>
+          <input
+            type="checkbox"
+            checked={task.done}
+            onChange={() =>
+              setState((prev) => ({
+                tasks: prev.tasks.map((t) =>
+                  t.id === task.id ? { ...t, done: !t.done } : t,
+                ),
+              }))
+            }
+          />
+          {task.title}
+        </li>
+      ))}
+    </ul>
   );
 }
 ```
 
-### 3. Place it in your layout
+That's all you need, `update_taskBoard` is generated automatically from your `stateSchema` once the `TaskBoard` component is mounted in your app.
+
+<Callout type="tip">
+  App-scoped state is shared across every thread and can be persisted by
+  defining a [persistence adapter](#persistence).
+</Callout>
+
+</Tab>
+<Tab>
+
+An interactable tool UI the model can call in-thread. Define it with `unstable_interactableTool` inside `defineToolkit`; it renders inline when the model calls it, and its `update_{name}` tool is generated automatically from your `stateSchema` once the tool is called by the model.
+
+```tsx
+"use generative";
+
+import { defineToolkit, unstable_interactableTool } from "@assistant-ui/react";
+import { z } from "zod";
+
+const notepadSchema = z.object({
+  title: z.string(),
+  content: z.string(),
+});
+
+const toolkit = defineToolkit({
+  notepad: unstable_interactableTool({
+    description: "A notepad with drafted text the user can read and edit.",
+    stateSchema: notepadSchema,
+    render: ({ state, setState, version, streaming }) => (
+      <Notepad
+        value={state}
+        onChange={setState}
+        busy={streaming}
+        readOnly={version ? !version.isLatest : false}
+      />
+    ),
+  }),
+});
+```
+
+Register the toolkit alongside the `unstable_Interactables` scope:
 
 ```tsx
-function App() {
-  return (
-    <MyRuntimeProvider>
-      <div className="flex">
-        <Thread className="flex-1" />
-        <TaskBoard /> {/* Lives outside the chat */}
-      </div>
-    </MyRuntimeProvider>
-  );
+const aui = useAui({
+  unstable_interactables: unstable_Interactables(),
+  tools: Tools({ toolkit }), // [!code ++]
+});
+```
+
+<Callout type="info">
+  Thread-scoped state rides the thread's history, so it survives reloads with
+  nothing extra to persist. `render` is run when the interactable is created,
+  and whenever it's updated (via `update_{name}`).
+</Callout>
+
+</Tab>
+</Tabs>
+
+</Step>
+<Step>
+
+### Surface state to the model in your route
+
+<Tabs items={["AI-SDK", "Other Backends"]}>
+<Tab>
+Each user message carries its state snapshots in its metadata, but the AI SDK's `convertToModelMessages` ignores metadata. Use `unstable_injectInteractableContext` to pass interactable state to the model:
+
+```ts title="app/api/chat/route.ts"
+import { openai } from "@ai-sdk/openai";
+import { convertToModelMessages, streamText } from "ai";
+import { unstable_injectInteractableContext as injectInteractableContext } from "@assistant-ui/react-ai-sdk";
+
+export async function POST(req: Request) {
+  const { messages } = await req.json();
+
+  const result = streamText({
+    model: openai("gpt-5.4"),
+    messages: await convertToModelMessages(injectInteractableContext(messages)), // [!code ++]
+  });
+
+  return result.toUIMessageStreamResponse();
 }
 ```
 
-Now when the user says _"Add a task called 'Buy groceries'"_, the AI will automatically call the `update_taskBoard` tool to update the state. Thanks to partial updates, the AI only needs to send the fields it wants to change.
+<Callout type="info">
+  The format of the snapshot sent to the model can be customized, see [State
+  snapshots](#state-snapshots) for more details.
+</Callout>
 
-## Partial Updates
+</Tab>
+<Tab>
 
-Auto-generated tools use a partial schema — all fields become optional. The AI only sends the fields it wants to change; omitted fields keep their current values.
+Each user message carries its state snapshots at `metadata.custom.interactables`. For other backends (LangGraph, Mastra, a custom runtime), build the equivalent injection with the two helpers exported from `@assistant-ui/react`:
 
-```tsx
-// If the state is { title: "My Note", content: "Hello", color: "yellow" }
-// The AI can call: update_note({ color: "blue" })
-// Result: { title: "My Note", content: "Hello", color: "blue" }
+```ts
+import {
+  unstable_getInteractableSnapshots, // (message) => snapshot entries | undefined
+  unstable_formatInteractableSnapshot, // (entry) => the model-facing formatting of the snapshot injection
+} from "@assistant-ui/react";
+
+for (const message of messages) {
+  if (message.role !== "user") continue;
+  const items = unstable_getInteractableSnapshots(message);
+  if (!items?.length) continue;
+  const text = items.map(unstable_formatInteractableSnapshot).join("\n");
+  // prepend `text` to the message content in whatever shape your backend expects
+}
 ```
 
-This is especially useful for large state objects where regenerating the entire state would be expensive and error-prone.
+<Callout type="info">
+  For more details, and how to customize the snapshot format for other backends,
+  see [State snapshots](#customizing-the-format).
+</Callout>
+
+</Tab>
+</Tabs>
+
+</Step>
+</Steps>
+
+## State snapshots
+
+Outgoing user messages can carry the interactable's state to the model as a snapshot, stamped when the state has changed since the model last saw it. When only some fields change, a partial snapshot is created containing a shallow diff of only the changed fields and the id.
+
+Default full snapshot formatting:
+
+```ts
+`[Current state of "note" (id: "n1"): {"title":"Q3 launch","body":"Ship the beta by Friday."}]`;
+```
+
+Default partial snapshot formatting:
+
+```ts
+`[State of "note" (id: "n1") changed — updated fields: {"title":"Q4 launch"}; fields not listed are unchanged]`;
+```
+
+### Customizing the format
+
+A formatter receives one snapshot `entry` and returns the line the model sees:
+
+- `name` and `id` identify the instance. Keep the `id` visible so the model knows what the state belongs to.
+- `state` is the snapshot payload.
+- `partial` is `true` when `state` carries a shallow diff of only the fields that changed since the model's last known state. Handle it.
+
+Write a custom formatter:
+
+```ts
+import { type Unstable_InteractableSnapshotEntry } from "@assistant-ui/react";
+
+const formatSnapshot = (entry: Unstable_InteractableSnapshotEntry) =>
+  entry.partial
+    ? `State of "${entry.name}" (id: "${entry.id}") has been updated, the following fields have changed: ${JSON.stringify(entry.state)}`
+    : `Current state of "${entry.name}" (id: "${entry.id}"): ${JSON.stringify(entry.state)}`;
+```
 
 <Callout type="info">
-  Merge is shallow (one level deep). If the AI sends a nested object, it replaces
-  that entire field rather than deep-merging into it.
+  When customizing format, remember to:
+  - Handle `partial: true` entries, whose `state` carries a shallow diff of only the fields that changed.
+  - Keep each instance's `id` visible so the model knows what the state belongs to.
 </Callout>
 
-## Multiple Instances
+Then wire it to your backend:
 
-You can render multiple interactables with the same `name` but different `id`s. Each gets its own update tool:
+- **AI SDK:** pass it as the second argument, `unstable_injectInteractableContext(messages, formatSnapshot)`.
+- **Other backends:** use it in place of `unstable_formatInteractableSnapshot` in your helper (see [Step 3](#surface-state-to-the-model-in-your-route)'s "Other Backends" tab).
 
-```tsx
-import { useAssistantInteractable, useInteractableState } from "@assistant-ui/react";
-import { z } from "zod";
+```ts title="app/api/chat/route.ts"
+messages: await convertToModelMessages(
+  unstable_injectInteractableContext(messages, formatSnapshot),
+),
+```
 
-const noteSchema = z.object({
-  title: z.string(),
-  content: z.string(),
-  color: z.enum(["yellow", "blue", "green", "pink"]),
-});
+## Artifacts
 
-const noteInitialState = { title: "New Note", content: "", color: "yellow" as const };
+An artifact combines two pieces that point at the same interactable:
 
-function NoteCard({ noteId }: { noteId: string }) {
-  useAssistantInteractable("note", {
-    id: noteId,
-    description: "A sticky note",
-    stateSchema: noteSchema,
-    initialState: noteInitialState,
+- a thread tool (`unstable_interactableTool`) the model calls to create the artifact inline (a button or small preview in the message), and
+- a panel you mount with `unstable_useInteractable` that opens that same instance at full size.
+
+Both use the same `id`, so they are one interactable, not two: the model creates it in the conversation, and the panel is just a larger view of the very same state. Because the thread holds the creating call, the artifact is **thread-scoped**: it persists with the thread's history (no [persistence adapter](#persistence) needed), and each message's trigger can open that message's version (see [Versions](#versions)).
+
+```
+  in the thread (model-created)            your layout (mounted once)
+──────────────────────────────          ──────────────────────────────
+unstable_interactableTool("document")    ArtifactPanel()
+  render: a button / inline preview        unstable_useInteractable("document", { id })
+    onClick → openArtifact(id) ────┐         → live, editable, full height
+                                   │                    │
+                                   └─────  same id  ────┘
+                                     one thread-scoped instance
+```
+
+```tsx
+const toolkit = defineToolkit({
+  document: unstable_interactableTool({
+    description: "A document the user can open and edit.",
+    stateSchema: documentSchema,
+    render: ({ state, version, id }) => (
+      <ArtifactButton
+        title={(version?.state ?? state).title}
+        onClick={() => openArtifact(id)} // your own state: which artifact is open
+      />
+    ),
+  }),
+});
+
+function ArtifactPanel({ id }: { id: string }) {
+  const [state, { setState }] = unstable_useInteractable("document", {
+    id,
+    description: "A document the user can open and edit.",
+    stateSchema: documentSchema,
+    initialState: emptyDocument, // fallback only; existing state comes from the thread
   });
-  const [state] = useInteractableState(noteId, noteInitialState);
+  const versions = unstable_useInteractableVersions<Document>(id, "document");
 
-  return <div>{state.title}</div>;
+  return (
+    <aside>
+      <VersionMenu>
+        {versions.map((v, i) => (
+          <DropdownItem key={i} onSelect={v.restore}>
+            v{i + 1}: {v.origin === "user-edit" ? "you" : "assistant"}
+          </DropdownItem>
+        ))}
+      </VersionMenu>
+      <Editor value={state} onChange={setState} />
+    </aside>
+  );
 }
+```
+
+You don't mount anything per artifact: the model renders the inline part on its own, and `openArtifact(id)` is your own state setter for which artifact the panel currently shows. Outside message parts the hook always returns the live state (`version` is `undefined`), so the panel is plainly editable. The panel and the inline tool UIs register the same `id`, so they share one instance; registration is reference-counted, and the instance stays alive until the last one unmounts.
+
+<Callout type="warn">
+  Keep one mount of the artifact on screen (hidden is fine) whenever its instance
+  should stay available. If the panel is closed and every inline button has
+  scrolled out of a virtualized thread, the instance and its `update_{name}` tool
+  unregister and the tool list churns. The state itself is safe, since it rides
+  thread history.
+</Callout>
+
+## Companion tools
+
+The generated `update_{name}` tool covers everything that lives in the state: editing fields, and adding, updating, removing, or clearing items in a list. Reach for a separate frontend tool only for what state can't express: a side effect like sending, exporting, or saving.
+
+Take an email composer the user and assistant co-edit. `update_email` keeps the draft in sync from both sides, but actually **sending** it is a side effect that no amount of state editing can perform. That is what a companion tool is for: `send_email` acts on the current draft and fires it.
+
+How you wire one depends on what its executor touches.
+
+**Closes over React state** (here, the live draft): declare the contract with `stubTool()` in your `"use generative"` toolkit, and supply the executor with `useAuiToolOverrides` in the component that owns the state. See [Dynamic Tools](/docs/tools/dynamic-tools).
+
+```tsx title="app/email-toolkit.tsx"
+"use generative";
+
+import { defineToolkit, stubTool } from "@assistant-ui/react";
+import { z } from "zod";
+
+export default defineToolkit({
+  send_email: {
+    description:
+      "Send the email currently shown in the composer. Call this only once the draft is ready.",
+    parameters: z.object({}),
+    execute: stubTool(),
+    renderText: { running: "Sending...", complete: "Email sent" },
+  },
+});
+```
+
+```tsx title="app/EmailComposer.tsx"
+import {
+  unstable_useInteractable,
+  useAuiToolOverrides,
+} from "@assistant-ui/react";
+
+function EmailComposer() {
+  const [draft, { setState }] = unstable_useInteractable("email", {
+    description: "An email draft the user and assistant can read and edit.",
+    stateSchema: emailSchema,
+    initialState: { to: "", subject: "", body: "" },
+  });
 
-function App() {
   return (
     <>
-      <NoteCard noteId="note-1" /> {/* → update_note_note-1 tool */}
-      <NoteCard noteId="note-2" /> {/* → update_note_note-2 tool */}
+      <SendEmailTool draft={draft} />
+      {/* inputs bound to draft + setState */}
     </>
   );
 }
+
+// A null-returning child supplies the executor, closing over the live draft.
+function SendEmailTool({ draft }: { draft: Email }) {
+  useAuiToolOverrides({
+    send_email: {
+      execute: async () => {
+        await fetch("/api/send-email", {
+          method: "POST",
+          body: JSON.stringify(draft),
+        });
+        return { success: true };
+      },
+    },
+  });
+  return null;
+}
 ```
 
-When only one instance of a name exists, the tool is named `update_{name}` (e.g., `update_note`). When multiple instances exist, tools are named `update_{name}_{id}` (e.g., `update_note_note-1`).
+The split is the whole point: `update_email` edits the draft, `send_email` does the thing the draft can't describe. The executor reads the live `draft`, so it always sends what is currently on screen.
 
-## Selection
+**Self-contained** (needs nothing from React, only its args and browser APIs): put a real `execute` with an inner `"use client"` directly in the toolkit. A `copy_share_link({ id })` that builds a URL and writes it to the clipboard is a good fit. See [Defining Tools](/docs/tools/defining-tools#frontend-tools).
 
-When multiple interactables are present, you can mark one as "selected" to tell the AI which one the user is focused on:
+## Custom Update Rendering
+
+`render` draws the create call; `updateRender` draws each `update_{name}` call. `unstable_interactableTool` reuses your one `render` for both, so edits look like the creation. Supply your own `updateRender` to render edits differently.
+
+<Callout type="info">
+  To vary by this message's version, or render older messages differently from
+  the newest, you don't need `updateRender`. The render already receives
+  `version`; see [Versions](#versions).
+</Callout>
+
+### Render edits differently from the create
+
+A thread tool locks the create and edit renders together. Drop to `unstable_useInteractable` to split them, here showing the full notepad on the create call and a one-line summary on every edit:
 
 ```tsx
-function NoteCard({ noteId }: { noteId: string }) {
-  useAssistantInteractable("note", {
-    id: noteId,
-    description: "A sticky note",
-    stateSchema: noteSchema,
-    initialState: noteInitialState,
+// Hoisted so its identity is stable; an inline updateRender re-registers the
+// tool UI on every render.
+const EditSummaryRender: ToolCallMessagePartComponent = ({ args }) => (
+  <EditSummary changed={args} />
+);
+
+const NotepadToolUI: ToolCallMessagePartComponent<NotepadArgs> = ({
+  toolCallId,
+  args,
+  result,
+}) => {
+  if (!result) return <NotepadDraft args={args} />;
+  return <Notepad id={toolCallId} initial={args} />;
+};
+
+function Notepad({ id, initial }: { id: string; initial: NotepadArgs }) {
+  const [state, { setState }] = unstable_useInteractable("notepad", {
+    id,
+    description: "A notepad the user can read and edit.",
+    stateSchema: notepadSchema,
+    initialState: initial,
+    updateRender: EditSummaryRender,
   });
-  const [state, { setSelected }] = useInteractableState(noteId, noteInitialState);
-
-  return (
-    <div onClick={() => setSelected(true)}>
-      {state.title}
-    </div>
-  );
+  return <NotepadEditor value={state} onChange={setState} />;
 }
-```
 
-The AI sees `(SELECTED)` in the system prompt for the focused interactable, allowing it to prioritize that one in responses. For example, the user can say _"Change the color to blue"_ and the AI knows which note to update.
+// NotepadToolUI is the create call's render; updateRender handles the edits.
+const toolkit = defineToolkit({
+  notepad: {
+    type: "frontend",
+    description: "A notepad the user can read and edit.",
+    parameters: notepadSchema,
+    display: "standalone",
+    execute: async () => ({ success: true as const }),
+    render: NotepadToolUI,
+  },
+});
+```
 
-## API Reference
+Pass the create call's `toolCallId` as the `id`: that one convention ties both renders to a single instance and restores its state from thread history after a reload.
 
-### `useAssistantInteractable`
+### Mark edits on an app-scoped surface
 
-Registers an interactable with the AI assistant. Returns the instance id.
+An app-scoped interactable lives in your layout (a sidebar, a panel), so it has no inline presence in the thread. Pass `updateRender` and each `update_{name}` call gains one: an inline marker of what the model just did, while the live component keeps updating in place.
 
 ```tsx
-const id = useAssistantInteractable(name, config);
+const EditMarkerRender: ToolCallMessagePartComponent = ({ args }) => (
+  <EditMarker changed={args} />
+);
+
+function DocumentPanel() {
+  const [state, { setState }] = unstable_useInteractable("document", {
+    description: "A document the user can read and edit.",
+    stateSchema: documentSchema,
+    initialState: emptyDocument,
+    updateRender: EditMarkerRender,
+  });
+  return <Editor value={state} onChange={setState} />;
+}
 ```
 
-**Parameters:**
+## Versions
+
+A thread is an append-only log, so an instance accumulates **versions**: each user edit, each `update_*` call, and (thread-scoped only) the creating call. For thread-scoped interactables these are computed from the thread record, so history survives reloads with nothing extra to persist. There are two ways to reach them.
 
-| Parameter | Type | Description |
-| --- | --- | --- |
-| `name` | `string` | Name for the interactable (used in tool names) |
-| `config.description` | `string` | Description shown to the AI |
-| `config.stateSchema` | `StandardSchemaV1 \| JSONSchema7` | Schema for the state (e.g., a Zod schema) |
-| `config.initialState` | `unknown` | Initial state value |
-| `config.id` | `string?` | Optional unique instance ID (auto-generated if omitted) |
-| `config.selected` | `boolean?` | Whether this interactable is selected |
+**This message's version.** Inside a thread-scoped `render`, `state` / `setState` are the **live** instance (there's exactly one, shared by every message), while `version` is **this message's** snapshot: `{ state, isLatest, restore }`. `version.state` is the interactable as it was at that point in the conversation; `restore()` sets the live state back to it.
 
-**Returns:** `string` — the instance id (auto-generated or provided).
+Those three fields are all you need, and two independent choices decide how history behaves:
 
-### `useInteractableState`
+- **Editable or read-only?** Render the live `state` / `setState` to let any message edit the shared instance, or `version.state` read-only to freeze it.
+- **Restorable?** Offer `version.restore()` to roll an old version back to live, or leave it out.
 
-Reads and writes the state of a registered interactable.
+| You want             | Render                                  |
+| -------------------- | --------------------------------------- |
+| Frozen history       | `version.state` read-only on old        |
+| Live-editable        | `state` / `setState` everywhere         |
+| Read-only + rollback | `version.state` read-only plus `restore` |
 
 ```tsx
-const [state, { setState, setSelected, isPending, error, flush }] = useInteractableState<TState>(id, fallback?);
+// Read-only history with rollback:
+// old messages are frozen but can roll their version back to live
+render: ({ state, setState, version }) =>
+  version && !version.isLatest ? (
+    <Notepad value={version.state} readOnly onRestore={version.restore} />
+  ) : (
+    <Notepad value={state} onChange={setState} />
+  );
 ```
 
-**Parameters:**
-
-| Parameter | Type | Description |
-| --- | --- | --- |
-| `id` | `string` | The interactable instance id (from `useAssistantInteractable`) |
-| `fallback` | `TState?` | Fallback value before the interactable is registered |
+```tsx
+// Live-editable:
+// every message edits the shared instance; restore reverts to this point
+render: ({ state, setState, version }) => (
+  <Notepad value={state} onChange={setState} onRestore={version?.restore} />
+);
+```
 
-**Returns:** `[state, methods]`
+**Every version at once.** `unstable_useInteractableVersions(id, name)` returns them oldest-first, each with the full `state` and a `restore()`. Use it for a history dropdown; it works for both app- and thread-scoped interactables:
 
-| Return | Type | Description |
-| --- | --- | --- |
-| `state` | `TState` | Current state |
-| `setState` | `(updater: TState \| (prev: TState) => TState) => void` | State setter (like `useState`) |
-| `setSelected` | `(selected: boolean) => void` | Mark this interactable as selected |
-| `isPending` | `boolean` | Whether a persistence save is in-flight |
-| `error` | `unknown` | Error from the last failed save |
-| `flush` | `() => Promise<void>` | Force an immediate persistence save |
+```tsx
+function VersionDropdown({ id, name }: { id: string; name: string }) {
+  const versions = unstable_useInteractableVersions(id, name);
+  if (versions.length < 2) return null;
 
-### `Interactables`
+  return (
+    <select onChange={(e) => versions[+e.target.value]!.restore()}>
+      {versions.map((v, i) => (
+        <option key={i} value={i}>
+          v{i + 1}: {v.origin === "user-edit" ? "you" : "assistant"}
+        </option>
+      ))}
+    </select>
+  );
+}
+```
 
-The scope resource that manages all interactables. Register it via `useAui`:
+**Thread-scoped:**
 
 ```tsx
-const aui = useAui({
-  interactables: Interactables(),
-});
+const Notepad = ({
+  id,
+  state,
+  setState,
+}: Unstable_InteractableToolRenderProps<NotepadArgs>) => (
+  <div>
+    <VersionDropdown id={id} name="notepad" />
+    {/* ...editor... */}
+  </div>
+);
 ```
 
-## How It Works
+**App-scoped:**
 
-When you call `useAssistantInteractable("taskBoard", config)`:
+```tsx
+const [state, { id }] = unstable_useInteractable("taskBoard", config);
+return <VersionDropdown id={id} name="taskBoard" />;
+```
 
-1. **Registration** — the interactable is registered in the `interactables` scope with its name, description, schema, and initial state.
-2. **Tool generation** — an `update_taskBoard` frontend tool is automatically created with a partial schema (all fields optional). For multiple instances, tools are named `update_{name}_{id}`.
-3. **System prompt** — the AI receives a system message describing the interactable, its current state, and whether it is selected.
-4. **Streaming updates** — as the AI generates the tool arguments, the interactable's state updates progressively rather than waiting for complete arguments. This gives users immediate visual feedback.
-5. **Partial merge** — only the fields the AI sends are updated; the rest are preserved.
-6. **Bidirectional updates** — when the AI calls the tool, the state updates and React re-renders. When the user updates state via `setState`, the model context is notified so the AI sees the latest state on the next turn.
+An app-scoped item's history covers the current conversation, not its full cross-thread lifetime.
 
 ## Persistence
 
-By default, interactable state is in-memory and lost on page refresh. You can add persistence by providing a save callback:
+By default, app-scoped interactable state is in-memory and lost on page refresh. You can add persistence by passing an adapter to `unstable_Interactables`:
 
 ```tsx
-import { useEffect } from "react";
-import { useAui, Interactables } from "@assistant-ui/react";
-
-function MyRuntimeProvider({ children }) {
-  const aui = useAui({ interactables: Interactables() });
+import { useAui, unstable_Interactables } from "@assistant-ui/react";
 
-  useEffect(() => {
-    // Set up persistence adapter
-    aui.interactables().setPersistenceAdapter({
-      save: async (state) => {
-        localStorage.setItem("interactables", JSON.stringify(state));
-      },
-    });
-
-    // Restore saved state on mount
+// Module-level (or memoized) so the adapter identity is stable across renders.
+const persistenceAdapter = {
+  load: () => {
     const saved = localStorage.getItem("interactables");
-    if (saved) {
-      aui.interactables().importState(JSON.parse(saved));
-    }
-  }, [aui]);
+    return saved ? JSON.parse(saved) : undefined;
+  },
+  save: (state) => {
+    localStorage.setItem("interactables", JSON.stringify(state));
+  },
+};
+
+function MyRuntimeProvider({ children }) {
+  const aui = useAui({
+    unstable_interactables: unstable_Interactables({
+      persistence: persistenceAdapter,
+    }),
+  });
 
   return /* ... */;
 }
 ```
 
+`load` is called when the adapter is attached and may be async. Loaded state seeds interactables as they register; a local edit made while a slow `load` is still in flight wins over the loaded value. Thread-scoped interactables are not touched by the adapter; they persist via thread history.
+
+For dynamic setups (an adapter that depends on auth), call `aui.interactables().setPersistenceAdapter(adapter)` imperatively instead.
+
 ### Sync Status
 
-When a persistence adapter is set, `useInteractableState` exposes sync metadata:
+When a persistence adapter is set, interactable hooks expose sync metadata:
 
 ```tsx
-const [state, { setState, isPending, error, flush }] = useInteractableState(id, fallback);
+const [state, { setState, isPending, error, flush }] =
+  unstable_useInteractableState<TState>(id);
 
-// isPending — true while a save is in-flight
-// error — the error from the last failed save, if any
-// flush() — force an immediate save (useful before navigation)
+// isPending: true while a save is in-flight
+// error: the error from the last failed save, if any
+// flush(): force an immediate save (useful before navigation)
 ```
 
-State changes are automatically debounced (500ms) before saving. When a component unregisters, any pending save is flushed immediately.
+State changes are automatically debounced (500ms) before saving. When the owning component unmounts, any pending save is flushed immediately.
 
 ### Export / Import
 
@@ -334,70 +647,426 @@ aui.interactables().importState(snapshot);
 // Imported state is picked up when components next register
 ```
 
-## Combining with Tools
+### Schema Evolution
+
+<Callout type="warn">
+  If you change a Zod schema after state has been persisted, the loaded snapshot
+  may silently mis-match the new shape. The adapter does a shallow merge, so
+  extra fields are preserved and missing fields keep their initial values, but
+  type mismatches are not caught at runtime. To avoid silent corruption, version
+  your schema key (e.g. `"taskBoard_v2"`) or namespace it by schema hash
+  whenever you make breaking changes. Alternatively, add a migration step in
+  your `load` or `importState` call.
+</Callout>
+
+## Streaming Updates
+
+The same partial merge runs token by token as the model generates an `update_{name}` call, so the interactable fills in live: a field the model is writing updates character by character, and only the fields and array items the call touches change. Everything it doesn't mention stays exactly as it was.
 
-You can use `Interactables` alongside `Tools`:
+That stability is concrete, not just visual. While one array item streams in, the items the model isn't editing keep their exact object identity for the whole stream, so a memoized row for them never re-renders:
 
 ```tsx
-const aui = useAui({
-  tools: Tools({ toolkit: myToolkit }),
-  interactables: Interactables(),
+import { memo } from "react";
+
+const TaskRow = memo(function TaskRow({ task }: { task: Task }) {
+  return <li>{task.title}</li>;
 });
+
+function TaskBoard() {
+  const [state] = unstable_useInteractable("taskBoard", config);
+
+  return (
+    <ul>
+      {state.tasks.map((task) => (
+        <TaskRow key={task.id} task={task} />
+      ))}
+    </ul>
+  );
+}
 ```
 
-## Streaming Updates
+As `update_taskBoard` streams an edit to one task, that row re-renders as its fields arrive while every other `TaskRow` stays put, no flicker and no work. You get a live-updating list for free; you only reach for the partial state when you want to show something extra during the stream.
 
-While the AI is generating tool arguments, `useInteractableState` reflects the partial state in real time as fields stream in. You can use the partial state itself plus the thread's running status to show a skeleton UI while the AI is mid-stream:
+One case worth handling: at the very start of a fresh create the model may not have produced any items yet. Use the thread's `isRunning` to tell "still streaming, nothing yet" apart from "the model returned an empty result", and show a skeleton only for that gap:
 
 ```tsx
 import { useAuiState } from "@assistant-ui/react";
 
-function TaskBoard() {
-  const id = useAssistantInteractable("taskBoard", config);
-  const [state] = useInteractableState(id, taskBoardInitialState);
-  const isRunning = useAuiState((s) => s.thread.isRunning);
+const isRunning = useAuiState((s) => s.thread.isRunning);
+const isLoading = isRunning && state.tasks.length === 0;
+```
+
+Inside a thread-scoped `render`, `streaming: true` carries the same live state: at the creating call `state` is the partial draft (fields may be missing); at an `update_{name}` call it's the live state filling in as the edit streams. Render a preview; edits made during a create stream are dropped.
+
+## Multiple Instances
+
+A `name` can have many live instances at once. They all share one `update_{name}` tool: the model addresses an instance with the tool's `id` parameter, which it reads from the state snapshots in the conversation. The tool's name, schema, and description never change as instances mount and unmount, so the model's tool list (and provider prompt caches) stay stable. While exactly one instance exists, the model may omit `id`; a call with an unknown `id` returns an error listing the valid ids, so the model can recover.
+
+How instances come into being differs by scope.
 
-  const isLoading = isRunning && state.tasks.length === 0;
+### Thread-scoped: instances for free
 
+A thread-scoped interactable gets a fresh instance every time the model calls its tool. The instance `id` is the creating call's `toolCallId`, so two calls are two instances with no extra code on your side: the same `render` and the same `update_{name}` tool serve all of them. This is how a model spins up several artifacts or notepads in one conversation, each addressed by its own `toolCallId`.
+
+### App-scoped: one instance per mount
+
+For app-scoped interactables you decide how many instances exist by mounting `unstable_useInteractable` in more than one place, one instance per mount. Give each mount a distinct `id`:
+
+```tsx
+import { unstable_useInteractable } from "@assistant-ui/react";
+import { z } from "zod";
+
+const noteSchema = z.object({
+  title: z.string(),
+  content: z.string(),
+  color: z.enum(["yellow", "blue", "green", "pink"]),
+});
+
+const noteInitialState = {
+  title: "New Note",
+  content: "",
+  color: "yellow" as const,
+};
+
+function NoteCard({ noteId }: { noteId: string }) {
+  const [state] = unstable_useInteractable("note", {
+    id: noteId,
+    description: "A sticky note",
+    stateSchema: noteSchema,
+    initialState: noteInitialState,
+  });
+
+  return <div>{state.title}</div>;
+}
+
+function App() {
   return (
-    <div>
-      <h2>Tasks</h2>
-      {isLoading ? (
-        <div className="animate-pulse h-8 rounded bg-muted" />
-      ) : (
-        <ul>
-          {state.tasks.map((task) => (
-            <li key={task.id}>{task.title}</li>
-          ))}
-        </ul>
-      )}
-    </div>
+    <>
+      <NoteCard noteId="note-1" />
+      <NoteCard noteId="note-2" />
+      {/* one update_note tool: update_note({ id: "note-2", color: "blue" }) */}
+    </>
   );
 }
 ```
 
-The state object updates progressively as the AI streams in each field, so partial renders work without any extra wiring. Use the runtime's `isRunning` to distinguish "still streaming, no fields yet" from "model returned an empty result".
+Pass an explicit `id` whenever you need to reach a specific instance: to read or write it from another component with `unstable_useInteractableState(id)`, to share it between an [artifact](#artifacts) panel and its inline trigger, or to keep [persisted](#persistence) state attached across reloads. Omitting `id` also works, and each mount then gets its own auto-generated id, but those ids are positional and shift as a dynamic list adds and removes items, so persisted state keyed by an old id would not reattach. Leave `id` off only when the component is the sole reader and its state is not persisted.
+
+<Callout type="info">
+  A top-level `id` field in your `stateSchema` is reserved: the update tool uses
+  it for instance addressing, so the model cannot write a state field named
+  `id`. Nest it or name it differently (e.g. `noteId`).
+</Callout>
 
-## Schema Evolution
+`update_note` edits a note that is already mounted: its `title`, `content`, `color`, and any other schema fields. It cannot mount a new `NoteCard` or unmount one; which components exist is your app's state. If you want the model to add and remove notes, model them as a single interactable holding an array (one `notes` field), and `update_notes` then adds, updates, removes, and clears entries directly, the way the [Quick Start](#quick-start) task board does. Use separate mounted instances only when each note is genuinely its own component; mounting and unmounting those is app work you can expose as a [companion tool](#companion-tools).
 
-<Callout type="warn">
-  If you change a Zod schema after state has been persisted, the imported snapshot may silently mis-match the new shape. The adapter does a shallow merge, so extra fields are preserved and missing fields keep their initial values, but type mismatches are not caught at runtime. To avoid silent corruption, version your schema key (e.g. `"taskBoard_v2"`) or namespace it by schema hash whenever you make breaking changes. Alternatively, add a migration step in your `importState` call.
+## Partial Updates
+
+Auto-generated tools use a partial schema in which all fields are optional. The AI only sends the fields it wants to change; omitted fields keep their current values.
+
+```tsx
+// If the state is { title: "My Note", content: "Hello", color: "yellow" }
+// The AI can call: update_note({ color: "blue" })
+// Result: { title: "My Note", content: "Hello", color: "blue" }
+```
+
+This is especially useful for large state objects where regenerating the entire state would be expensive and error-prone.
+
+For array fields whose items carry an `id`, the AI doesn't send a replacement array, it sends operations (`add`, `update`, `remove`, `clear`) and the framework applies them to the current list. Added items get their `id` from the framework; existing items are addressed by the `id` you gave them.
+
+<Callout type="info">
+  Merge is shallow (one level deep). If the AI sends a nested object, it
+  replaces that entire field rather than deep-merging into it.
 </Callout>
 
+## How It Works
+
+1. **Register**: the interactable joins the `interactables` scope with its name, description, schema, and initial state.
+2. **Generate the tool**: one `update_{name}` tool per name, with a partial schema (every field optional) plus a required `id`. The tool list stays stable as instances mount and unmount, so provider prompt caches stay warm.
+3. **Snapshot**: each sent user message carries the current state in `metadata.custom`, but only when the model doesn't already know it. A user edit stamps a snapshot; the model's own `update_*` calls and an in-message instance's create args don't. When the change fits a shallow merge it stamps only the changed fields (`partial: true`). Your route turns snapshots into model-visible text (see [State snapshots](#state-snapshots)).
+4. **Stream**: state updates field-by-field as the model generates the tool arguments, so the UI fills in live.
+5. **Merge**: only the fields the model sends are applied; the rest stay. Array fields keyed by `id` take operations (add/update/remove/clear) instead of a replacement array, and the framework mints ids for added items.
+6. **Both directions**: a model `update_*` updates state and re-renders; a user `setState` rides the next message as a fresh snapshot.
+
 ## Unmount Behavior
 
-When a component that called `useAssistantInteractable` unmounts, the interactable is unregistered from the AI's tool list and system prompt. However, its state is preserved in the `Interactables` scope. When the component mounts again with the same name and id, the scope re-merges the preserved state rather than resetting to `initialState`. This means transient unmounts (such as React Strict Mode double-mounts or tab switches) do not lose state.
+When a component that called `unstable_useInteractable` unmounts, the interactable is unregistered, but its state is preserved in the `unstable_Interactables` scope. When the component mounts again with the same name and id, the scope restores the preserved state rather than resetting to `initialState`. This means transient unmounts (such as React Strict Mode double-mounts or tab switches) do not lose state.
+
+An instance registered from several places (its creating tool call, `update_*` calls, an artifact panel) stays registered until the last one unmounts, so scrolling one out of a virtualized thread doesn't tear the instance down while another is visible.
+
+## API Reference
+
+### `unstable_useInteractable`
+
+Registers an interactable with the AI assistant and returns its state. It behaves like `useState`, except the model can also read and update the value. Call it once per instance.
+
+```tsx
+const [state, { id, setState, isPending, error, flush }] =
+  unstable_useInteractable(name, config);
+```
+
+**Parameters:**
+
+<PrimitivesTypeTable
+  type="unstable_useInteractable-params"
+  parameters={[
+    {
+      name: "name",
+      type: "string",
+      required: true,
+      description: (
+        <>
+          Name for the interactable (determines the{" "}
+          <code>update_{"{name}"}</code> tool).
+        </>
+      ),
+    },
+    {
+      name: "config",
+      type: "Unstable_InteractableConfig<TSchema>",
+      required: true,
+      description: "Configuration for the interactable.",
+      children: [
+        {
+          parameters: [
+            {
+              name: "description",
+              type: "string",
+              required: true,
+              description: "Description shown to the AI.",
+            },
+            {
+              name: "stateSchema",
+              type: "StandardSchemaV1 | JSONSchema7",
+              required: true,
+              description: "Schema for the state (e.g., a Zod schema).",
+            },
+            {
+              name: "initialState",
+              type: "TState",
+              required: true,
+              description: (
+                <>
+                  Initial state value. The type is inferred from{" "}
+                  <code>stateSchema</code>.
+                </>
+              ),
+            },
+            {
+              name: "id",
+              type: "string",
+              required: false,
+              description:
+                "Unique instance ID, used to address this instance when multiple interactables share a name. Auto-generated if omitted.",
+            },
+            {
+              name: "updateRender",
+              type: "ToolCallMessagePartComponent",
+              required: false,
+              description: (
+                <>
+                  Renders the model's <code>update_{"{name}"}</code> tool calls
+                  yourself; installed once per name. See{" "}
+                  <a href="#custom-update-rendering">Custom Update Rendering</a>.
+                </>
+              ),
+            },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
+**Returns:** `[state, methods]`
+
+<PrimitivesTypeTable
+  type="unstable_useInteractable-returns"
+  parameters={[
+    {
+      name: "state",
+      type: "TState",
+      required: true,
+      description: (
+        <>
+          Current state. Inferred from <code>stateSchema</code>.
+        </>
+      ),
+    },
+    {
+      name: "id",
+      type: "string",
+      required: true,
+      description: (
+        <>
+          The instance id; pass it to <code>unstable_useInteractableState</code>{" "}
+          in other components.
+        </>
+      ),
+    },
+    {
+      name: "setState",
+      type: "(updater: TState | ((prev: TState) => TState)) => void",
+      required: true,
+      description: (
+        <>
+          State setter, like <code>useState</code>.
+        </>
+      ),
+    },
+    {
+      name: "version",
+      type: "{ state: TState; isLatest: boolean; restore: () => void } | undefined",
+      required: true,
+      description: (
+        <>
+          This message's version of the instance, when rendered inside a
+          tool-call part; see <a href="#versions">Versions</a>.{" "}
+          <code>undefined</code> outside messages and for app scope.
+        </>
+      ),
+    },
+    {
+      name: "isPending",
+      type: "boolean",
+      required: true,
+      description: "Whether a persistence save is in-flight.",
+    },
+    {
+      name: "error",
+      type: "unknown",
+      required: true,
+      description: "Error from the last failed save.",
+    },
+    {
+      name: "flush",
+      type: "() => Promise<void>",
+      required: true,
+      description: "Force an immediate persistence save.",
+    },
+  ]}
+/>
+
+<Callout type="info">
+  Selection is not a built-in field. To tell the AI which interactable is
+  focused, add a selection field such as `selectedId` to your own state; see
+  [Selection](#selection).
+</Callout>
+
+### `unstable_useInteractableState`
+
+Reads and writes the state of an interactable registered elsewhere, by id. Use this from secondary readers (children, siblings of the owning component).
+
+```tsx
+const [state, { setState, isPending, error, flush }] =
+  unstable_useInteractableState<TState>(id);
+```
+
+**Parameters:**
+
+<PrimitivesTypeTable
+  type="unstable_useInteractableState-params"
+  parameters={[
+    {
+      name: "id",
+      type: "string",
+      required: true,
+      description: (
+        <>
+          The interactable instance id (from{" "}
+          <code>unstable_useInteractable</code>).
+        </>
+      ),
+    },
+  ]}
+/>
+
+**Returns:** `[state, methods]`, the same shape as `unstable_useInteractable` without `id`. `state` is `TState | undefined` until the owning `unstable_useInteractable` has registered.
+
+### `unstable_interactableTool`
+
+```tsx
+notepad: unstable_interactableTool({ description, stateSchema, render }),
+```
+
+Returns a complete toolkit tool entry (a frontend tool with standalone display); the entry key is the interactable name, and the tool's arguments are its initial state. The same `render` then appears at every message that creates or updates the instance. `render` receives:
+
+<PrimitivesTypeTable
+  type="unstable_interactableTool-render-props"
+  parameters={[
+    {
+      name: "state",
+      type: "TState",
+      required: true,
+      description:
+        "The live state. While streaming, fields the model has not finished generating may be missing.",
+    },
+    {
+      name: "setState",
+      type: "(updater: TState | ((prev: TState) => TState)) => void",
+      required: true,
+      description: "Updates the live state.",
+    },
+    {
+      name: "version",
+      type: "{ state: TState; isLatest: boolean; restore: () => void } | undefined",
+      required: true,
+      description:
+        "This message's version of the instance; undefined while streaming.",
+    },
+    {
+      name: "id",
+      type: "string",
+      required: true,
+      description: "The instance id (the creating call's toolCallId).",
+    },
+    {
+      name: "streaming",
+      type: "boolean",
+      required: true,
+      description: "True while the tool call's arguments are still streaming.",
+    },
+  ]}
+/>
+
+### `unstable_useInteractableVersions`
+
+```tsx
+const versions = unstable_useInteractableVersions<TState>(id, name);
+// → [{ state, origin: "create" | "update" | "user-edit", toolCallId?, restore }, ...]
+```
+
+Every version of an interactable recorded in the current thread, oldest first. Each entry carries the full `state` and a `restore()` that sets the live instance back to it. Works for both scopes; see [Versions](#versions) for usage. The non-React equivalent for backends is `unstable_getInteractableVersions(messages, id, name)`, exported from `@assistant-ui/react`.
+
+### `unstable_Interactables`
+
+The scope resource that manages all interactables. Register it via `useAui`, optionally with a [persistence adapter](#persistence):
+
+```tsx
+const aui = useAui({
+  unstable_interactables: unstable_Interactables({ persistence: myAdapter }),
+});
+```
+
+## Migrating from the Previous API
+
+If you used an earlier version of the interactables API:
+
+- `useAssistantInteractable` and `useInteractableState` have been merged into a single [`unstable_useInteractable`](#unstable_useinteractable) hook that registers and returns state. `unstable_useInteractableState` remains for secondary readers.
+- Per-instance tools (`update_note_note-1`) are gone. Each name has one stable `update_{name}` tool with a required `id` parameter.
+- The top-level `selected` prop and `setSelected` method have been removed. Represent selection as ordinary state; see [Selection](#selection).
 
 ## Full Example
 
 See the complete [with-interactables example](https://github.com/assistant-ui/assistant-ui/tree/main/examples/with-interactables) for a working implementation featuring:
 
-- **Task Board** — single-instance interactable with a custom `manage_tasks` tool
-- **Sticky Notes** — multi-instance interactables with selection and partial updates
-- **localStorage persistence** — state survives page refresh via `setPersistenceAdapter`
-- **Sync indicator** — spinning icon while a save is in-flight (`isPending`)
+- **Task Board**: one interactable whose `tasks` array the AI edits with `update_taskBoard` (add/update/remove/clear)
+- **Sticky Notes**: one `notes` interactable with a `selectedId` field, where the AI adds, edits, removes, and selects notes through `update_notes`
+- **localStorage persistence**: state survives page refresh via a `load`/`save` persistence adapter
+- **Sync indicator**: spinning icon while a save is in-flight (`isPending`)
 
 ## Related
 
-- [Tool UI](/docs/tools/tool-ui) — Inline tool call UIs rendered inside messages
-- [LangGraph Generative UI](/docs/runtimes/langgraph/generative-ui) — Structured UI components emitted by a LangGraph graph alongside messages
+- [Dynamic Tools](/docs/tools/dynamic-tools): Frontend tools whose executors close over React state
+- [Tool UI](/docs/tools/tool-ui): Inline tool call UIs rendered inside messages
+- [LangGraph Generative UI](/docs/runtimes/langgraph/generative-ui): Structured UI components emitted by a LangGraph graph alongside messages