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

package/.docs/organized/code-examples/with-interactables.md

@@ -4,17 +4,16 @@
 
 ```typescript
 import { openai } from "@ai-sdk/openai";
-import {
-  streamText,
-  convertToModelMessages,
-  stepCountIs,
-  jsonSchema,
-} from "ai";
+import { streamText, convertToModelMessages, stepCountIs } from "ai";
 import type { UIMessage } from "ai";
+import {
+  frontendTools,
+  unstable_injectInteractableContext,
+} from "@assistant-ui/react-ai-sdk";
 
 export const maxDuration = 30;
 
-type ToolDef = { description?: string; parameters: Record<string, unknown> };
+type FrontendTools = Parameters<typeof frontendTools>[0];
 
 export async function POST(req: Request) {
   const {
@@ -24,30 +23,19 @@ export async function POST(req: Request) {
   }: {
     messages: UIMessage[];
     system?: string;
-    tools?: Record<string, ToolDef>;
+    tools?: FrontendTools;
   } = await req.json();
 
-  // Convert client-defined tools (forwarded from model context) to AI SDK format.
-  // These have no `execute` — they are frontend tools executed on the client
-  // via Tools({ toolkit }) / useAssistantInteractable.
-  const tools = clientTools
-    ? Object.fromEntries(
-        Object.entries(clientTools).map(([name, def]) => [
-          name,
-          {
-            description: def.description ?? "",
-            inputSchema: jsonSchema(def.parameters),
-          },
-        ]),
-      )
-    : undefined;
+  const modelMessages = await convertToModelMessages(
+    unstable_injectInteractableContext(messages),
+  );
 
   const result = streamText({
     model: openai("gpt-5.4-nano"),
-    messages: await convertToModelMessages(messages),
+    messages: modelMessages,
     stopWhen: stepCountIs(10),
     ...(system ? { system } : {}),
-    ...(tools ? { tools } : {}),
+    ...(clientTools ? { tools: frontendTools(clientTools) } : {}),
   } as Parameters<typeof streamText>[0]);
 
   return result.toUIMessageStreamResponse();
@@ -214,25 +202,15 @@ export default function RootLayout({
 ```tsx
 "use client";
 
-import {
-  useRef,
-  useState,
-  useCallback,
-  useEffect,
-  type Dispatch,
-  type SetStateAction,
-} from "react";
+import { useCallback } from "react";
 import { Thread } from "@/components/assistant-ui/thread";
 import {
   AssistantRuntimeProvider,
   AuiProvider,
-  Interactables,
+  unstable_Interactables,
   Suggestions,
-  Tools,
   useAui,
-  useAuiToolOverrides,
-  useAssistantInteractable,
-  useInteractableState,
+  unstable_useInteractable,
 } from "@assistant-ui/react";
 import { useChatRuntime } from "@assistant-ui/react-ai-sdk";
 import { lastAssistantMessageIsCompleteWithToolCalls } from "ai";
@@ -247,34 +225,29 @@ import {
 } from "lucide-react";
 import {
   type NoteState,
-  type TaskBoardState,
   noteInitialState,
-  noteSchema,
+  notesInitialState,
+  notesSchema,
   taskBoardInitialState,
   taskBoardSchema,
 } from "./state";
-import toolkit from "./toolkits";
 
 function TaskBoard() {
-  const id = useAssistantInteractable("taskBoard", {
-    description:
-      "A task board showing the user's tasks. Use the manage_tasks tool (not update_taskBoard) to add/toggle/remove/clear tasks.",
-    stateSchema: taskBoardSchema,
-    initialState: taskBoardInitialState,
-  });
-  const [state, { setState, isPending }] = useInteractableState<TaskBoardState>(
-    id,
-    taskBoardInitialState,
+  const [state, { setState, isPending }] = unstable_useInteractable(
+    "taskBoard",
+    {
+      description:
+        "A task board showing the user's 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,
+    },
   );
 
-  const aui = useAui({ tools: Tools({ toolkit }) });
-
   const doneCount = state.tasks.filter((t) => t.done).length;
 
   return (
-    <AuiProvider value={aui}>
-      <TaskBoardToolOverrides setState={setState} />
-      <div className="flex flex-col">
+    <>
+      <div className="flex h-full flex-col">
         <div className="flex items-center gap-2 border-b px-4 py-3">
           <ListTodoIcon className="text-muted-foreground size-4" />
           <span className="text-sm font-semibold">Task Board</span>
@@ -294,9 +267,9 @@ function TaskBoard() {
             </p>
           ) : (
             <ul className="space-y-1">
-              {state.tasks.map((task) => (
+              {state.tasks.map((task, index) => (
                 <li
-                  key={task.id}
+                  key={task.id ?? `streaming-${index}`}
                   className="group hover:bg-muted flex items-center gap-2 rounded-lg px-3 py-2 transition-colors"
                 >
                   <button
@@ -309,6 +282,9 @@ function TaskBoard() {
                       }))
                     }
                     className="shrink-0"
+                    aria-label={
+                      task.done ? "Mark task undone" : "Mark task done"
+                    }
                   >
                     {task.done ? (
                       <CheckCircle2Icon className="text-primary size-4" />
@@ -329,6 +305,7 @@ function TaskBoard() {
                       }))
                     }
                     className="shrink-0 opacity-0 transition-opacity group-hover:opacity-100"
+                    aria-label={`Remove task ${task.title}`}
                   >
                     <Trash2Icon className="text-muted-foreground hover:text-destructive size-3.5" />
                   </button>
@@ -338,59 +315,11 @@ function TaskBoard() {
           )}
         </div>
       </div>
-    </AuiProvider>
+    </>
   );
 }
 
-function TaskBoardToolOverrides({
-  setState,
-}: {
-  setState: Dispatch<SetStateAction<TaskBoardState>>;
-}) {
-  useAuiToolOverrides({
-    manage_tasks: {
-      execute: async (args) => {
-        switch (args.action) {
-          case "add": {
-            const id = crypto.randomUUID();
-            setState((prev) => ({
-              tasks: [
-                ...prev.tasks,
-                { id, title: args.title ?? "Untitled", done: false },
-              ],
-            }));
-            return { success: true, id };
-          }
-          case "toggle": {
-            if (!args.id) return { success: false, error: "id is required" };
-            setState((prev) => ({
-              tasks: prev.tasks.map((t) =>
-                t.id === args.id ? { ...t, done: !t.done } : t,
-              ),
-            }));
-            return { success: true };
-          }
-          case "remove": {
-            if (!args.id) return { success: false, error: "id is required" };
-            setState((prev) => ({
-              tasks: prev.tasks.filter((t) => t.id !== args.id),
-            }));
-            return { success: true };
-          }
-          case "clear": {
-            setState({ tasks: [] });
-            return { success: true };
-          }
-          default:
-            return { success: false, error: "Unknown action" };
-        }
-      },
-    },
-  });
-  return null;
-}
-
-const COLORS: Record<string, string> = {
+const COLORS: Record<NoteState["color"], string> = {
   yellow: "bg-yellow-100 border-yellow-300",
   blue: "bg-blue-100 border-blue-300",
   green: "bg-green-100 border-green-300",
@@ -398,62 +327,41 @@ const COLORS: Record<string, string> = {
 };
 
 function NoteCard({
-  noteId,
-  selectedId,
+  note,
+  selected,
   onSelect,
   onRemove,
 }: {
-  noteId: string;
-  selectedId: string | null;
+  note: NoteState;
+  selected: boolean;
   onSelect: (id: string) => void;
   onRemove: (id: string) => void;
 }) {
-  useAssistantInteractable("note", {
-    id: noteId,
-    description:
-      "A sticky note. The AI can partially update any field (title, content, color) without resending the others.",
-    stateSchema: noteSchema,
-    initialState: noteInitialState,
-    selected: selectedId === noteId,
-  });
-  const [state, { setSelected }] = useInteractableState<NoteState>(
-    noteId,
-    noteInitialState,
-  );
-
-  const isSelected = selectedId === noteId;
-
-  const handleClick = () => {
-    onSelect(noteId);
-    setSelected(true);
-  };
-
   return (
-    <div
-      role="button"
-      tabIndex={0}
-      onClick={handleClick}
-      onKeyDown={(e) => (e.key === "Enter" || e.key === " ") && handleClick()}
-      className={`group relative flex w-full cursor-pointer flex-col gap-1 rounded-lg border-2 p-3 text-left transition-all ${COLORS[state.color] ?? COLORS.yellow} ${isSelected ? "ring-primary ring-2 ring-offset-1" : "hover:shadow-sm"}`}
-    >
-      {isSelected && (
-        <span className="bg-primary text-primary-foreground absolute top-1.5 right-2 rounded px-1.5 py-0.5 text-[10px] leading-none font-medium">
-          SELECTED
+    <div className="group relative">
+      <button
+        type="button"
+        onClick={() => onSelect(note.id)}
+        className={`flex w-full cursor-pointer flex-col gap-1 rounded-lg border-2 p-3 text-left transition-all ${COLORS[note.color] ?? COLORS.yellow} ${selected ? "ring-primary ring-2 ring-offset-1" : "hover:shadow-sm"}`}
+        aria-pressed={selected}
+      >
+        {selected && (
+          <span className="bg-primary text-primary-foreground absolute top-1.5 right-2 rounded px-1.5 py-0.5 text-[10px] leading-none font-medium">
+            SELECTED
+          </span>
+        )}
+        <span className="pr-16 text-sm font-semibold text-zinc-800">
+          {note.title}
+        </span>
+        <span className="line-clamp-3 text-xs text-zinc-600">
+          {note.content || "Empty note"}
         </span>
-      )}
-      <span className="pr-16 text-sm font-semibold text-zinc-800">
-        {state.title}
-      </span>
-      <span className="line-clamp-3 text-xs text-zinc-600">
-        {state.content || "Empty note"}
-      </span>
+      </button>
       <button
         type="button"
-        onClick={(e) => {
-          e.stopPropagation();
-          onRemove(noteId);
-        }}
+        onClick={() => onRemove(note.id)}
         className="absolute right-2 bottom-2 rounded p-0.5 opacity-0 transition-opacity group-hover:opacity-100 hover:bg-black/10"
+        aria-label={`Remove note ${note.title}`}
       >
         <Trash2Icon className="size-3 text-zinc-500" />
       </button>
@@ -461,79 +369,69 @@ function NoteCard({
   );
 }
 
-const NOTE_IDS_KEY = "interactables-example-note-ids";
-
-function loadNoteIds(): string[] {
-  try {
-    const saved = localStorage.getItem(NOTE_IDS_KEY);
-    return saved ? JSON.parse(saved) : [];
-  } catch {
-    return [];
-  }
-}
-
 function NotesPanel() {
-  const [noteIds, setNoteIds] = useState<string[]>([]);
-  const [selectedId, setSelectedId] = useState<string | null>(null);
-  const hydratedRef = useRef(false);
-
-  useEffect(() => {
-    if (!hydratedRef.current) {
-      hydratedRef.current = true;
-      const saved = loadNoteIds();
-      if (saved.length > 0) setNoteIds(saved);
-      return;
-    }
-    localStorage.setItem(NOTE_IDS_KEY, JSON.stringify(noteIds));
-  }, [noteIds]);
-
-  const aui = useAui({ tools: Tools({ toolkit }) });
+  const [state, { setState }] = unstable_useInteractable("notes", {
+    description:
+      "The sticky-note collection and selected note id. Use update_notes with notes.add/update/remove/clear to manage notes, and set selectedId to change focus. New notes need a title, content, and color.",
+    stateSchema: notesSchema,
+    initialState: notesInitialState,
+  });
 
-  const handleSelect = useCallback((id: string) => {
-    setSelectedId(id);
-  }, []);
+  const handleAdd = useCallback(() => {
+    const id = `note-${crypto.randomUUID()}`;
+    setState((prev) => ({
+      notes: [...prev.notes, { id, ...noteInitialState }],
+      selectedId: id,
+    }));
+  }, [setState]);
+
+  const handleSelect = useCallback(
+    (id: string) => {
+      setState((prev) => ({ ...prev, selectedId: id }));
+    },
+    [setState],
+  );
 
-  const handleRemove = useCallback((id: string) => {
-    setNoteIds((prev) => prev.filter((n) => n !== id));
-    setSelectedId((prev) => (prev === id ? null : prev));
-  }, []);
+  const handleRemove = useCallback(
+    (id: string) => {
+      setState((prev) => ({
+        notes: prev.notes.filter((note) => note.id !== id),
+        selectedId: prev.selectedId === id ? null : prev.selectedId,
+      }));
+    },
+    [setState],
+  );
 
   return (
-    <AuiProvider value={aui}>
-      <NotesToolOverrides
-        setNoteIds={setNoteIds}
-        setSelectedId={setSelectedId}
-      />
-      <div className="flex flex-col">
+    <>
+      <div className="flex h-full flex-col">
         <div className="flex items-center gap-2 border-b px-4 py-3">
           <StickyNoteIcon className="text-muted-foreground size-4" />
           <span className="text-sm font-semibold">Notes</span>
           <span className="text-muted-foreground ml-auto text-xs">
-            {noteIds.length}
+            {state.notes.length}
           </span>
           <button
             type="button"
-            onClick={() => {
-              const id = `note-${crypto.randomUUID()}`;
-              setNoteIds((prev) => [...prev, id]);
-            }}
+            onClick={handleAdd}
             className="hover:bg-muted rounded p-1 transition-colors"
+            aria-label="Add note"
           >
             <PlusIcon className="text-muted-foreground size-3.5" />
           </button>
         </div>
         <div className="flex-1 overflow-y-auto p-3">
-          {noteIds.length === 0 ? (
+          {state.notes.length === 0 ? (
             <p className="text-muted-foreground py-6 text-center text-xs">
               No notes yet. Ask the assistant!
             </p>
           ) : (
             <div className="grid gap-2">
-              {noteIds.map((noteId) => (
+              {state.notes.map((note, index) => (
                 <NoteCard
-                  key={noteId}
-                  noteId={noteId}
-                  selectedId={selectedId}
+                  key={note.id ?? `streaming-${index}`}
+                  note={note}
+                  selected={state.selectedId === note.id}
                   onSelect={handleSelect}
                   onRemove={handleRemove}
                 />
@@ -542,74 +440,32 @@ function NotesPanel() {
           )}
         </div>
       </div>
-    </AuiProvider>
+    </>
   );
 }
 
-function NotesToolOverrides({
-  setNoteIds,
-  setSelectedId,
-}: {
-  setNoteIds: Dispatch<SetStateAction<string[]>>;
-  setSelectedId: Dispatch<SetStateAction<string | null>>;
-}) {
-  useAuiToolOverrides({
-    manage_notes: {
-      execute: async (args) => {
-        switch (args.action) {
-          case "add": {
-            const id = `note-${crypto.randomUUID()}`;
-            setNoteIds((prev) => [...prev, id]);
-            return { success: true, noteId: id };
-          }
-          case "remove": {
-            if (args.noteId) {
-              setNoteIds((prev) => prev.filter((id) => id !== args.noteId));
-            }
-            return { success: true };
-          }
-          case "clear": {
-            setNoteIds([]);
-            setSelectedId(null);
-            return { success: true };
-          }
-          default:
-            return { success: false, error: "Unknown action" };
-        }
-      },
-    },
-  });
-  return null;
-}
-
 const STORAGE_KEY = "interactables-example";
 
-function useInteractablePersistence(aui: ReturnType<typeof useAui>) {
-  useEffect(() => {
-    const saved = localStorage.getItem(STORAGE_KEY);
-    if (saved) {
-      try {
-        aui.interactables().importState(JSON.parse(saved));
-      } catch {
-        // ignore malformed data
-      }
+// Module-level so the adapter identity is stable across renders.
+const persistenceAdapter = {
+  load: () => {
+    try {
+      const saved = localStorage.getItem(STORAGE_KEY);
+      return saved ? JSON.parse(saved) : undefined;
+    } catch {
+      return undefined;
     }
+  },
+  save: (state: unknown) => {
+    localStorage.setItem(STORAGE_KEY, JSON.stringify(state));
+  },
+};
 
-    aui.interactables().setPersistenceAdapter({
-      save: (state) => {
-        localStorage.setItem(STORAGE_KEY, JSON.stringify(state));
-      },
-    });
-  }, [aui]);
-}
-
-export default function Home() {
-  const runtime = useChatRuntime({
-    sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithToolCalls,
-  });
-
+function InteractablesExample() {
   const aui = useAui({
-    interactables: Interactables(),
+    unstable_interactables: unstable_Interactables({
+      persistence: persistenceAdapter,
+    }),
     suggestions: Suggestions([
       {
         title: "Add 3 tasks",
@@ -630,23 +486,33 @@ export default function Home() {
     ]),
   });
 
-  useInteractablePersistence(aui);
-
   return (
-    <AssistantRuntimeProvider aui={aui} runtime={runtime}>
-      <main className="flex h-full">
-        <div className="flex-1">
+    <AuiProvider value={aui}>
+      <main className="flex h-full min-h-0">
+        <div className="min-w-0 flex-1">
           <Thread />
         </div>
         <div className="flex w-80 flex-col border-l">
-          <div className="flex-1 overflow-y-auto">
+          <div className="min-h-0 flex-1 overflow-y-auto">
             <NotesPanel />
           </div>
-          <div className="flex-1 overflow-y-auto border-t">
+          <div className="min-h-0 flex-1 overflow-y-auto border-t">
             <TaskBoard />
           </div>
         </div>
       </main>
+    </AuiProvider>
+  );
+}
+
+export default function Home() {
+  const runtime = useChatRuntime({
+    sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithToolCalls,
+  });
+
+  return (
+    <AssistantRuntimeProvider runtime={runtime}>
+      <InteractablesExample />
     </AssistantRuntimeProvider>
   );
 }
@@ -664,7 +530,7 @@ export type TaskBoardState = { tasks: Task[] };
 export const taskBoardSchema = z.object({
   tasks: z.array(
     z.object({
-      id: z.string(),
+      id: z.string().describe("Stable task id, unique within this board."),
       title: z.string(),
       done: z.boolean(),
     }),
@@ -673,69 +539,34 @@ export const taskBoardSchema = z.object({
 
 export const taskBoardInitialState: TaskBoardState = { tasks: [] };
 
-export const manageTasksParameters = z.object({
-  action: z.enum(["add", "toggle", "remove", "clear"]),
-  title: z.string().optional(),
-  id: z.string().optional(),
-});
-
-export type ManageTasksArgs = z.infer<typeof manageTasksParameters>;
-
-export type NoteState = { title: string; content: string; color: string };
+export const noteColorSchema = z.enum(["yellow", "blue", "green", "pink"]);
 
 export const noteSchema = z.object({
+  id: z.string().describe("Stable note id, unique within this collection."),
   title: z.string(),
   content: z.string(),
-  color: z.enum(["yellow", "blue", "green", "pink"]),
+  color: noteColorSchema,
 });
 
-export const noteInitialState: NoteState = {
+export type NoteState = z.infer<typeof noteSchema>;
+
+export const noteInitialState: Omit<NoteState, "id"> = {
   title: "New Note",
   content: "",
   color: "yellow",
 };
 
-export const manageNotesParameters = z.object({
-  action: z.enum(["add", "remove", "clear"]),
-  noteId: z.string().optional(),
+export const notesSchema = z.object({
+  notes: z.array(noteSchema),
+  selectedId: z.string().nullable(),
 });
 
-export type ManageNotesArgs = z.infer<typeof manageNotesParameters>;
-
-```
-
-## app/toolkits.ts
+export type NotesState = z.infer<typeof notesSchema>;
 
-```typescript
-"use generative";
-
-import { defineToolkit, stubTool } from "@assistant-ui/react";
-import { manageNotesParameters, manageTasksParameters } from "./state";
-
-export default defineToolkit({
-  manage_tasks: {
-    description:
-      'Manage tasks on the task board. Actions: "add" (requires title), "toggle" (requires id), "remove" (requires id), "clear" (no extra fields).',
-    parameters: manageTasksParameters,
-    // The generative compiler strips this stub; TaskBoardToolOverrides provides the real executor.
-    execute: stubTool(),
-    renderText: {
-      running: ({ args }) => `Updating tasks: ${args.action}`,
-      complete: "Tasks updated",
-    },
-  },
-  manage_notes: {
-    description:
-      'Manage sticky notes. Actions: "add" (creates a new note, returns its id), "remove" (requires noteId), "clear" (removes all notes). After adding, use the update_note_{id} tool to set its content.',
-    parameters: manageNotesParameters,
-    // The generative compiler strips this stub; NotesToolOverrides provides the real executor.
-    execute: stubTool(),
-    renderText: {
-      running: ({ args }) => `Updating notes: ${args.action}`,
-      complete: "Notes updated",
-    },
-  },
-});
+export const notesInitialState: NotesState = {
+  notes: [],
+  selectedId: null,
+};
 
 ```
 
@@ -772,14 +603,13 @@ export default defineToolkit({
 ## next.config.ts
 
 ```typescript
-import { withAui } from "@assistant-ui/next";
 import type { NextConfig } from "next";
 
 const nextConfig: NextConfig = {
   /* config options here */
 };
 
-export default withAui(nextConfig);
+export default nextConfig;
 
 ```
 
@@ -797,14 +627,14 @@ export default withAui(nextConfig);
     "start": "next start"
   },
   "dependencies": {
-    "@ai-sdk/openai": "^3.0.71",
+    "@ai-sdk/openai": "^3.0.73",
     "@assistant-ui/react": "workspace:*",
     "@assistant-ui/react-ai-sdk": "workspace:*",
     "@assistant-ui/ui": "workspace:*",
-    "ai": "^6.0.204",
+    "ai": "^6.0.208",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
-    "lucide-react": "^1.18.0",
+    "lucide-react": "^1.21.0",
     "next": "^16.2.9",
     "react": "^19.2.7",
     "react-dom": "^19.2.7",
@@ -812,10 +642,9 @@ export default withAui(nextConfig);
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@assistant-ui/next": "workspace:*",
     "@assistant-ui/x-buildutils": "workspace:*",
     "@tailwindcss/postcss": "^4.3.1",
-    "@types/node": "^25.9.3",
+    "@types/node": "^26.0.0",
     "@types/react": "^19.2.17",
     "@types/react-dom": "^19.2.3",
     "postcss": "^8.5.15",
@@ -836,16 +665,16 @@ Demonstrates **interactable components** — persistent UI components whose stat
 
 ## Features Demonstrated
 
-### Task Board (single instance + custom tool)
-- `useInteractable("taskBoard", config)` — registers a single interactable
-- `Tools({ toolkit })` — custom tool for incremental add/toggle/remove/clear
-- Auto-generated `update_taskBoard` tool with **partial updates** (AI only sends changed fields)
+### Task Board
+- `unstable_useInteractable("taskBoard", config)` — registers a single interactable
+- Auto-generated `update_taskBoard` tool with partial scalar updates and array operations
+- Collection edits go through `tasks.add`, `tasks.update`, `tasks.remove`, and `tasks.clear` on the generated update tool
 
-### Sticky Notes (multi-instance + selection + partial updates)
-- Multiple `<NoteCard>` components each call `useInteractable("note", { id: noteId, ... })`
-- **Multi-instance**: each note gets its own `update_note_{id}` tool automatically
-- **Selection**: click a note to select it; AI sees `(SELECTED)` in system prompt and prioritizes it
-- **Partial updates**: AI can change just `{ color: "pink" }` without resending title and content
+### Sticky Notes
+- `unstable_useInteractable("notes", config)` — registers the sticky-note collection and `selectedId` as one state object
+- Auto-generated `update_notes` manages both note collection edits and selected-note focus
+- **Selection**: click a note to set `selectedId`; the AI can change focus by updating the same normal state field
+- **Partial updates**: AI can change just one note field with `notes.update: [{ id, color: "pink" }]`
 
 ## Getting Started
 
@@ -865,12 +694,11 @@ Open [http://localhost:3000](http://localhost:3000) to see the example.
 
 ## Key Concepts
 
-- **`Interactables()`** — scope resource registered via `useAui`
-- **`useInteractable(name, config)`** — returns `[state, setState, { id, setSelected }]`
+- **`unstable_Interactables({ persistence })`** — scope resource registered via `useAui`, with a `load`/`save` adapter
+- **`unstable_useInteractable(name, config)`** — returns `[state, { id, setState, isPending, error, flush }]`
 - **Partial updates** — auto-generated tools use partial schemas; AI only sends changed fields
-- **Multi-instance** — same `name`, different `id`; tools named `update_{name}_{id}`
-- **Selection** — `setSelected(true)` marks a component as focused for the AI
-- **`Tools({ toolkit })`** — custom frontend tools for fine-grained control
+- **Array operations** — array fields support generated `add`, `update`, `remove`, `clear`, and `set` operations on the same `update_{name}` tool
+- **Selection as state** — focused UI state lives in the interactable's normal schema (`selectedId`), not in a separate manage tool
 - **`sendAutomaticallyWhen`** — auto-sends follow-up messages when tool calls complete
 
 ```