@assistant-ui/mcp-docs-server 0.1.25 → 0.1.27

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

@@ -0,0 +1,836 @@
+# Example: with-interactables
+
+## app/api/chat/route.ts
+
+```typescript
+import { openai } from "@ai-sdk/openai";
+import {
+  streamText,
+  convertToModelMessages,
+  stepCountIs,
+  jsonSchema,
+} from "ai";
+import type { UIMessage } from "ai";
+
+export const maxDuration = 30;
+
+type ToolDef = { description?: string; parameters: Record<string, unknown> };
+
+export async function POST(req: Request) {
+  const {
+    messages,
+    system,
+    tools: clientTools,
+  }: {
+    messages: UIMessage[];
+    system?: string;
+    tools?: Record<string, ToolDef>;
+  } = 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 useAssistantTool / useAssistantInteractable.
+  const tools = clientTools
+    ? Object.fromEntries(
+        Object.entries(clientTools).map(([name, def]) => [
+          name,
+          {
+            description: def.description ?? "",
+            inputSchema: jsonSchema(def.parameters),
+          },
+        ]),
+      )
+    : undefined;
+
+  const result = streamText({
+    model: openai("gpt-4o"),
+    messages: await convertToModelMessages(messages),
+    stopWhen: stepCountIs(10),
+    ...(system ? { system } : {}),
+    ...(tools ? { tools } : {}),
+  } as Parameters<typeof streamText>[0]);
+
+  return result.toUIMessageStreamResponse();
+}
+
+```
+
+## app/globals.css
+
+```css
+@import "tailwindcss";
+@import "tw-animate-css";
+
+@source "../../../packages/ui/src";
+
+@custom-variant dark (&:is(.dark *));
+
+@theme inline {
+  --radius-sm: calc(var(--radius) - 4px);
+  --radius-md: calc(var(--radius) - 2px);
+  --radius-lg: var(--radius);
+  --radius-xl: calc(var(--radius) + 4px);
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  --color-card: var(--card);
+  --color-card-foreground: var(--card-foreground);
+  --color-popover: var(--popover);
+  --color-popover-foreground: var(--popover-foreground);
+  --color-primary: var(--primary);
+  --color-primary-foreground: var(--primary-foreground);
+  --color-secondary: var(--secondary);
+  --color-secondary-foreground: var(--secondary-foreground);
+  --color-muted: var(--muted);
+  --color-muted-foreground: var(--muted-foreground);
+  --color-accent: var(--accent);
+  --color-accent-foreground: var(--accent-foreground);
+  --color-destructive: var(--destructive);
+  --color-border: var(--border);
+  --color-input: var(--input);
+  --color-ring: var(--ring);
+  --color-chart-1: var(--chart-1);
+  --color-chart-2: var(--chart-2);
+  --color-chart-3: var(--chart-3);
+  --color-chart-4: var(--chart-4);
+  --color-chart-5: var(--chart-5);
+  --color-sidebar: var(--sidebar);
+  --color-sidebar-foreground: var(--sidebar-foreground);
+  --color-sidebar-primary: var(--sidebar-primary);
+  --color-sidebar-primary-foreground: var(--sidebar-primary-foreground);
+  --color-sidebar-accent: var(--sidebar-accent);
+  --color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
+  --color-sidebar-border: var(--sidebar-border);
+  --color-sidebar-ring: var(--sidebar-ring);
+}
+
+:root {
+  --radius: 0.625rem;
+  --background: oklch(1 0 0);
+  --foreground: oklch(0.141 0.005 285.823);
+  --card: oklch(1 0 0);
+  --card-foreground: oklch(0.141 0.005 285.823);
+  --popover: oklch(1 0 0);
+  --popover-foreground: oklch(0.141 0.005 285.823);
+  --primary: oklch(0.21 0.006 285.885);
+  --primary-foreground: oklch(0.985 0 0);
+  --secondary: oklch(0.967 0.001 286.375);
+  --secondary-foreground: oklch(0.21 0.006 285.885);
+  --muted: oklch(0.967 0.001 286.375);
+  --muted-foreground: oklch(0.552 0.016 285.938);
+  --accent: oklch(0.967 0.001 286.375);
+  --accent-foreground: oklch(0.21 0.006 285.885);
+  --destructive: oklch(0.577 0.245 27.325);
+  --border: oklch(0.92 0.004 286.32);
+  --input: oklch(0.92 0.004 286.32);
+  --ring: oklch(0.705 0.015 286.067);
+  --chart-1: oklch(0.646 0.222 41.116);
+  --chart-2: oklch(0.6 0.118 184.704);
+  --chart-3: oklch(0.398 0.07 227.392);
+  --chart-4: oklch(0.828 0.189 84.429);
+  --chart-5: oklch(0.769 0.188 70.08);
+  --sidebar: oklch(0.985 0 0);
+  --sidebar-foreground: oklch(0.141 0.005 285.823);
+  --sidebar-primary: oklch(0.21 0.006 285.885);
+  --sidebar-primary-foreground: oklch(0.985 0 0);
+  --sidebar-accent: oklch(0.967 0.001 286.375);
+  --sidebar-accent-foreground: oklch(0.21 0.006 285.885);
+  --sidebar-border: oklch(0.92 0.004 286.32);
+  --sidebar-ring: oklch(0.705 0.015 286.067);
+}
+
+.dark {
+  --background: oklch(0.141 0.005 285.823);
+  --foreground: oklch(0.985 0 0);
+  --card: oklch(0.21 0.006 285.885);
+  --card-foreground: oklch(0.985 0 0);
+  --popover: oklch(0.21 0.006 285.885);
+  --popover-foreground: oklch(0.985 0 0);
+  --primary: oklch(0.92 0.004 286.32);
+  --primary-foreground: oklch(0.21 0.006 285.885);
+  --secondary: oklch(0.274 0.006 286.033);
+  --secondary-foreground: oklch(0.985 0 0);
+  --muted: oklch(0.274 0.006 286.033);
+  --muted-foreground: oklch(0.705 0.015 286.067);
+  --accent: oklch(0.274 0.006 286.033);
+  --accent-foreground: oklch(0.985 0 0);
+  --destructive: oklch(0.704 0.191 22.216);
+  --border: oklch(1 0 0 / 10%);
+  --input: oklch(1 0 0 / 15%);
+  --ring: oklch(0.552 0.016 285.938);
+  --chart-1: oklch(0.488 0.243 264.376);
+  --chart-2: oklch(0.696 0.17 162.48);
+  --chart-3: oklch(0.769 0.188 70.08);
+  --chart-4: oklch(0.627 0.265 303.9);
+  --chart-5: oklch(0.645 0.246 16.439);
+  --sidebar: oklch(0.21 0.006 285.885);
+  --sidebar-foreground: oklch(0.985 0 0);
+  --sidebar-primary: oklch(0.488 0.243 264.376);
+  --sidebar-primary-foreground: oklch(0.985 0 0);
+  --sidebar-accent: oklch(0.274 0.006 286.033);
+  --sidebar-accent-foreground: oklch(0.985 0 0);
+  --sidebar-border: oklch(1 0 0 / 10%);
+  --sidebar-ring: oklch(0.552 0.016 285.938);
+}
+
+@layer base {
+  * {
+    @apply border-border outline-ring/50;
+  }
+  body {
+    @apply bg-background text-foreground;
+  }
+}
+
+```
+
+## app/layout.tsx
+
+```tsx
+import type { Metadata } from "next";
+import "./globals.css";
+
+export const metadata: Metadata = {
+  title: "assistant-ui Interactables Example",
+  description:
+    "Example using assistant-ui interactable components with a task board",
+};
+
+export default function RootLayout({
+  children,
+}: Readonly<{
+  children: React.ReactNode;
+}>) {
+  return (
+    <html lang="en">
+      <body className="h-dvh">{children}</body>
+    </html>
+  );
+}
+
+```
+
+## app/page.tsx
+
+```tsx
+"use client";
+
+import { useRef, useState, useCallback, useEffect } from "react";
+import { Thread } from "@/components/assistant-ui/thread";
+import {
+  AssistantRuntimeProvider,
+  Interactables,
+  Suggestions,
+  useAui,
+  useAssistantInteractable,
+  useInteractableState,
+  useAssistantTool,
+} from "@assistant-ui/react";
+import { useChatRuntime } from "@assistant-ui/react-ai-sdk";
+import { lastAssistantMessageIsCompleteWithToolCalls } from "ai";
+import { z } from "zod";
+import {
+  CheckCircle2Icon,
+  CircleIcon,
+  ListTodoIcon,
+  Loader2Icon,
+  StickyNoteIcon,
+  Trash2Icon,
+  PlusIcon,
+} from "lucide-react";
+
+// ===========================================================================
+// 1. Task Board — single-instance interactable + custom tool
+// ===========================================================================
+
+type Task = { id: string; title: string; done: boolean };
+type TaskBoardState = { tasks: Task[] };
+
+const taskBoardSchema = z.object({
+  tasks: z.array(
+    z.object({
+      id: z.string(),
+      title: z.string(),
+      done: z.boolean(),
+    }),
+  ),
+});
+
+const taskBoardInitialState: TaskBoardState = { tasks: [] };
+
+let nextTaskId = 0;
+
+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 setStateRef = useRef(setState);
+  setStateRef.current = setState;
+
+  useAssistantTool({
+    toolName: "manage_tasks",
+    description:
+      'Manage tasks on the task board. Actions: "add" (requires title), "toggle" (requires id), "remove" (requires id), "clear" (no extra fields).',
+    parameters: z.object({
+      action: z.enum(["add", "toggle", "remove", "clear"]),
+      title: z.string().optional(),
+      id: z.string().optional(),
+    }),
+    execute: async (args) => {
+      const set = setStateRef.current;
+      switch (args.action) {
+        case "add": {
+          const id = `task-${++nextTaskId}`;
+          set((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" };
+          set((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" };
+          set((prev) => ({
+            tasks: prev.tasks.filter((t) => t.id !== args.id),
+          }));
+          return { success: true };
+        }
+        case "clear": {
+          set({ tasks: [] });
+          return { success: true };
+        }
+        default:
+          return { success: false, error: "Unknown action" };
+      }
+    },
+  });
+
+  const doneCount = state.tasks.filter((t) => t.done).length;
+
+  return (
+    <div className="flex flex-col">
+      <div className="flex items-center gap-2 border-b px-4 py-3">
+        <ListTodoIcon className="size-4 text-muted-foreground" />
+        <span className="font-semibold text-sm">Task Board</span>
+        {isPending && (
+          <Loader2Icon className="size-3 animate-spin text-muted-foreground" />
+        )}
+        {state.tasks.length > 0 && (
+          <span className="ml-auto rounded-full bg-primary/10 px-2 py-0.5 font-medium text-primary text-xs">
+            {doneCount}/{state.tasks.length}
+          </span>
+        )}
+      </div>
+      <div className="flex-1 overflow-y-auto p-3">
+        {state.tasks.length === 0 ? (
+          <p className="py-6 text-center text-muted-foreground text-xs">
+            No tasks yet. Ask the assistant!
+          </p>
+        ) : (
+          <ul className="space-y-1">
+            {state.tasks.map((task) => (
+              <li
+                key={task.id}
+                className="group flex items-center gap-2 rounded-lg px-3 py-2 transition-colors hover:bg-muted"
+              >
+                <button
+                  type="button"
+                  onClick={() =>
+                    setState((prev) => ({
+                      tasks: prev.tasks.map((t) =>
+                        t.id === task.id ? { ...t, done: !t.done } : t,
+                      ),
+                    }))
+                  }
+                  className="shrink-0"
+                >
+                  {task.done ? (
+                    <CheckCircle2Icon className="size-4 text-primary" />
+                  ) : (
+                    <CircleIcon className="size-4 text-muted-foreground" />
+                  )}
+                </button>
+                <span
+                  className={`flex-1 text-sm ${task.done ? "text-muted-foreground line-through" : ""}`}
+                >
+                  {task.title}
+                </span>
+                <button
+                  type="button"
+                  onClick={() =>
+                    setState((prev) => ({
+                      tasks: prev.tasks.filter((t) => t.id !== task.id),
+                    }))
+                  }
+                  className="shrink-0 opacity-0 transition-opacity group-hover:opacity-100"
+                >
+                  <Trash2Icon className="size-3.5 text-muted-foreground hover:text-destructive" />
+                </button>
+              </li>
+            ))}
+          </ul>
+        )}
+      </div>
+    </div>
+  );
+}
+
+// ===========================================================================
+// 2. Sticky Notes — multi-instance interactable + selection + partial updates
+// ===========================================================================
+
+type NoteState = { title: string; content: string; color: string };
+
+const noteSchema = z.object({
+  title: z.string(),
+  content: z.string(),
+  color: z.enum(["yellow", "blue", "green", "pink"]),
+});
+
+const noteInitialState: NoteState = {
+  title: "New Note",
+  content: "",
+  color: "yellow",
+};
+
+const COLORS: Record<string, string> = {
+  yellow: "bg-yellow-100 border-yellow-300",
+  blue: "bg-blue-100 border-blue-300",
+  green: "bg-green-100 border-green-300",
+  pink: "bg-pink-100 border-pink-300",
+};
+
+function NoteCard({
+  noteId,
+  selectedId,
+  onSelect,
+  onRemove,
+}: {
+  noteId: string;
+  selectedId: string | null;
+  onSelect: (id: string) => void;
+  onRemove: (id: string) => void;
+}) {
+  // Multi-instance: each NoteCard has a unique `id`, all share name "note"
+  // Partial updates: AI can send { color: "blue" } without resending title/content
+  // Selection: clicking a note calls setSelected(true)
+  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-2 ring-primary ring-offset-1" : "hover:shadow-sm"}`}
+    >
+      {isSelected && (
+        <span className="absolute top-1.5 right-2 rounded bg-primary px-1.5 py-0.5 font-medium text-[10px] text-primary-foreground leading-none">
+          SELECTED
+        </span>
+      )}
+      <span className="pr-16 font-semibold text-sm text-zinc-800">
+        {state.title}
+      </span>
+      <span className="line-clamp-3 text-xs text-zinc-600">
+        {state.content || "Empty note"}
+      </span>
+      <button
+        type="button"
+        onClick={(e) => {
+          e.stopPropagation();
+          onRemove(noteId);
+        }}
+        className="absolute right-2 bottom-2 rounded p-0.5 opacity-0 transition-opacity hover:bg-black/10 group-hover:opacity-100"
+      >
+        <Trash2Icon className="size-3 text-zinc-500" />
+      </button>
+    </div>
+  );
+}
+
+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 noteIdsRef = useRef(noteIds);
+  noteIdsRef.current = noteIds;
+  const setNoteIdsRef = useRef(setNoteIds);
+  setNoteIdsRef.current = setNoteIds;
+  const setSelectedIdRef = useRef(setSelectedId);
+  setSelectedIdRef.current = setSelectedId;
+
+  // Tool to add/remove notes (manages the list, not the note content)
+  useAssistantTool({
+    toolName: "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: z.object({
+      action: z.enum(["add", "remove", "clear"]),
+      noteId: z.string().optional(),
+    }),
+    execute: async (args) => {
+      switch (args.action) {
+        case "add": {
+          const id = `note-${Date.now().toString(36)}`;
+          setNoteIdsRef.current((prev) => [...prev, id]);
+          return { success: true, noteId: id };
+        }
+        case "remove": {
+          if (args.noteId) {
+            setNoteIdsRef.current((prev) =>
+              prev.filter((id) => id !== args.noteId),
+            );
+          }
+          return { success: true };
+        }
+        case "clear": {
+          setNoteIdsRef.current([]);
+          setSelectedIdRef.current(null);
+          return { success: true };
+        }
+        default:
+          return { success: false, error: "Unknown action" };
+      }
+    },
+  });
+
+  const handleSelect = useCallback((id: string) => {
+    setSelectedId(id);
+  }, []);
+
+  const handleRemove = useCallback((id: string) => {
+    setNoteIds((prev) => prev.filter((n) => n !== id));
+    setSelectedId((prev) => (prev === id ? null : prev));
+  }, []);
+
+  return (
+    <div className="flex flex-col">
+      <div className="flex items-center gap-2 border-b px-4 py-3">
+        <StickyNoteIcon className="size-4 text-muted-foreground" />
+        <span className="font-semibold text-sm">Notes</span>
+        <span className="ml-auto text-muted-foreground text-xs">
+          {noteIds.length}
+        </span>
+        <button
+          type="button"
+          onClick={() => {
+            const id = `note-${Date.now().toString(36)}`;
+            setNoteIds((prev) => [...prev, id]);
+          }}
+          className="rounded p-1 transition-colors hover:bg-muted"
+        >
+          <PlusIcon className="size-3.5 text-muted-foreground" />
+        </button>
+      </div>
+      <div className="flex-1 overflow-y-auto p-3">
+        {noteIds.length === 0 ? (
+          <p className="py-6 text-center text-muted-foreground text-xs">
+            No notes yet. Ask the assistant!
+          </p>
+        ) : (
+          <div className="grid gap-2">
+            {noteIds.map((noteId) => (
+              <NoteCard
+                key={noteId}
+                noteId={noteId}
+                selectedId={selectedId}
+                onSelect={handleSelect}
+                onRemove={handleRemove}
+              />
+            ))}
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}
+
+// ===========================================================================
+// App
+// ===========================================================================
+
+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
+      }
+    }
+
+    aui.interactables().setPersistenceAdapter({
+      save: (state) => {
+        localStorage.setItem(STORAGE_KEY, JSON.stringify(state));
+      },
+    });
+  }, [aui]);
+}
+
+export default function Home() {
+  const runtime = useChatRuntime({
+    sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithToolCalls,
+  });
+
+  const aui = useAui({
+    interactables: Interactables(),
+    suggestions: Suggestions([
+      {
+        title: "Add 3 tasks",
+        label: "for a grocery run",
+        prompt: "Add 3 tasks for a grocery run",
+      },
+      {
+        title: "Create 2 notes",
+        label: "and set different colors",
+        prompt:
+          "Create 2 sticky notes: one blue note about meeting prep, and one green note about project ideas",
+      },
+      {
+        title: "Change selected note",
+        label: "to pink color",
+        prompt: "Change the selected note's color to pink",
+      },
+    ]),
+  });
+
+  useInteractablePersistence(aui);
+
+  return (
+    <AssistantRuntimeProvider aui={aui} runtime={runtime}>
+      <main className="flex h-full">
+        <div className="flex-1">
+          <Thread />
+        </div>
+        <div className="flex w-80 flex-col border-l">
+          <div className="flex-1 overflow-y-auto">
+            <NotesPanel />
+          </div>
+          <div className="flex-1 overflow-y-auto border-t">
+            <TaskBoard />
+          </div>
+        </div>
+      </main>
+    </AssistantRuntimeProvider>
+  );
+}
+
+```
+
+## components.json
+
+```json
+{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "new-york",
+  "rsc": true,
+  "tsx": true,
+  "tailwind": {
+    "config": "",
+    "css": "app/globals.css",
+    "baseColor": "zinc",
+    "cssVariables": true,
+    "prefix": ""
+  },
+  "aliases": {
+    "components": "@/components",
+    "utils": "@/lib/utils",
+    "ui": "@/components/ui",
+    "lib": "@/lib",
+    "hooks": "@/hooks"
+  },
+  "iconLibrary": "lucide",
+  "registries": {
+    "@assistant-ui": "https://r.assistant-ui.com/{name}.json"
+  }
+}
+
+```
+
+## next.config.ts
+
+```typescript
+import type { NextConfig } from "next";
+
+const nextConfig: NextConfig = {
+  /* config options here */
+};
+
+export default nextConfig;
+
+```
+
+## package.json
+
+```json
+{
+  "name": "with-interactables",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start"
+  },
+  "dependencies": {
+    "@ai-sdk/openai": "^3.0.50",
+    "@assistant-ui/react": "workspace:*",
+    "@assistant-ui/react-ai-sdk": "workspace:*",
+    "@assistant-ui/ui": "workspace:*",
+    "ai": "^6.0.144",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "lucide-react": "^1.7.0",
+    "next": "^16.2.2",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
+    "tailwind-merge": "^3.5.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@assistant-ui/x-buildutils": "workspace:*",
+    "@tailwindcss/postcss": "^4.2.2",
+    "@types/node": "^25.5.0",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "postcss": "^8.5.8",
+    "tailwindcss": "^4.2.2",
+    "tw-animate-css": "^1.4.0",
+    "typescript": "5.9.3"
+  }
+}
+
+```
+
+## README.md
+
+```markdown
+# with-interactables
+
+Demonstrates **interactable components** — persistent UI components whose state can be read and updated by both the user and the AI assistant.
+
+## Features Demonstrated
+
+### Task Board (single instance + custom tool)
+- `useInteractable("taskBoard", config)` — registers a single interactable
+- `useAssistantTool("manage_tasks")` — custom tool for incremental add/toggle/remove/clear
+- Auto-generated `update_taskBoard` tool with **partial updates** (AI only sends changed fields)
+
+### 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
+
+## Getting Started
+
+```bash
+# Install dependencies (from monorepo root)
+pnpm install
+
+# Set your OpenAI API key
+cp .env.example .env.local
+# Edit .env.local and add your OPENAI_API_KEY
+
+# Run the development server
+pnpm --filter with-interactables dev
+```
+
+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 }]`
+- **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
+- **`useAssistantTool`** — custom frontend tools for fine-grained control
+- **`sendAutomaticallyWhen`** — auto-sends follow-up messages when tool calls complete
+
+```
+
+## tsconfig.json
+
+```json
+{
+  "extends": "@assistant-ui/x-buildutils/ts/next",
+  "compilerOptions": {
+    "paths": {
+      "@/*": ["./*"],
+      "@/components/assistant-ui/*": [
+        "../../packages/ui/src/components/assistant-ui/*"
+      ],
+      "@/components/ui/*": ["../../packages/ui/src/components/ui/*"],
+      "@/lib/utils": ["../../packages/ui/src/lib/utils"],
+      "@assistant-ui/ui/*": ["../../packages/ui/src/*"]
+    }
+  },
+  "include": ["**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
+  "exclude": ["node_modules"]
+}
+
+```
+