@assistant-ui/mcp-docs-server 0.1.26 → 0.1.28

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

@@ -488,14 +488,14 @@ export default nextConfig;
   "dependencies": {
     "@assistant-ui/store": "workspace:*",
     "@assistant-ui/tap": "workspace:*",
-    "next": "^16.2.1",
+    "next": "^16.2.2",
     "react": "^19.2.4",
     "react-dom": "^19.2.4"
   },
   "devDependencies": {
     "@assistant-ui/x-buildutils": "workspace:*",
     "@tailwindcss/postcss": "^4.2.2",
-    "@types/node": "^25.5.0",
+    "@types/node": "^25.5.2",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
     "postcss": "^8.5.8",
@@ -645,7 +645,12 @@ useAuiEvent("*", (data) => {
 {
   "extends": "@assistant-ui/x-buildutils/ts/next",
   "compilerOptions": {
-    "paths": { "@/*": ["./*"] }
+    "paths": {
+      "@/*": ["./*"]
+    },
+    "allowJs": true,
+    "incremental": true,
+    "jsx": "preserve"
   },
   "include": ["**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
   "exclude": ["node_modules"]

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

@@ -65,8 +65,8 @@
     "@assistant-ui/react": "workspace:*",
     "@assistant-ui/react-markdown": "workspace:*",
     "@tailwindcss/vite": "^4.2.2",
-    "@tanstack/react-router": "^1.168.4",
-    "@tanstack/react-start": "^1.167.8",
+    "@tanstack/react-router": "^1.168.10",
+    "@tanstack/react-start": "^1.167.16",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "lucide-react": "^1.7.0",
@@ -81,12 +81,12 @@
   },
   "devDependencies": {
     "@assistant-ui/x-buildutils": "workspace:*",
-    "@types/node": "^25.5.0",
+    "@types/node": "^25.5.2",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
     "@vitejs/plugin-react": "^6.0.1",
     "typescript": "5.9.3",
-    "vite": "^8.0.2"
+    "vite": "^8.0.5"
   }
 }
 

package/.docs/organized/code-examples/with-tap-runtime.md

@@ -598,7 +598,7 @@ export default nextConfig;
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "lucide-react": "^1.7.0",
-    "next": "^16.2.1",
+    "next": "^16.2.2",
     "react": "^19.2.4",
     "react-dom": "^19.2.4",
     "tailwind-merge": "^3.5.0"
@@ -606,7 +606,7 @@ export default nextConfig;
   "devDependencies": {
     "@assistant-ui/x-buildutils": "workspace:*",
     "@tailwindcss/postcss": "^4.2.2",
-    "@types/node": "^25.5.0",
+    "@types/node": "^25.5.2",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
     "postcss": "^8.5.8",

package/.docs/raw/docs/(docs)/copilots/model-context.mdx

@@ -14,17 +14,25 @@ System instructions define the base behavior and knowledge available to the assi
 ```tsx
 import {
   useAssistantInstructions,
+  useAssistantContext,
   makeAssistantVisible,
 } from "@assistant-ui/react";
 
-// Via useAssistantInstructions
+// Static instructions
 useAssistantInstructions("You are a helpful assistant...");
 
+// Dynamic context — callback is evaluated lazily at send-time
+useAssistantContext({
+  getContext: () => `Current page: ${window.location.href}`,
+});
+
 // Via makeAssistantVisible
 const ReadableComponent = makeAssistantVisible(MyComponent);
 // Automatically provides component HTML as system context
 ```
 
+`useAssistantInstructions` takes a static string that re-registers when changed. `useAssistantContext` takes a callback that is evaluated fresh each time the model context is read, making it ideal for injecting frequently-changing application state without triggering re-registrations.
+
 ### Tools
 
 Tools are functions that the assistant can use to interact with your application. They can be provided through various mechanisms:

package/.docs/raw/docs/(docs)/guides/interactables.mdx

@@ -58,7 +58,7 @@ function MyRuntimeProvider({ children }: { children: React.ReactNode }) {
 </Callout>
 
 ```tsx
-import { useInteractable } from "@assistant-ui/react";
+import { useAssistantInteractable, useInteractableState } from "@assistant-ui/react";
 import { z } from "zod";
 
 const taskBoardSchema = z.object({
@@ -74,11 +74,12 @@ const taskBoardSchema = z.object({
 const taskBoardInitialState = { tasks: [] };
 
 function TaskBoard() {
-  const [state, setState] = useInteractable("taskBoard", {
+  const id = useAssistantInteractable("taskBoard", {
     description: "A task board showing the user's tasks",
     stateSchema: taskBoardSchema,
     initialState: taskBoardInitialState,
   });
+  const [state, { setState }] = useInteractableState(id, taskBoardInitialState);
 
   return (
     <div>
@@ -147,7 +148,7 @@ This is especially useful for large state objects where regenerating the entire
 You can render multiple interactables with the same `name` but different `id`s. Each gets its own update tool:
 
 ```tsx
-import { useInteractable } from "@assistant-ui/react";
+import { useAssistantInteractable, useInteractableState } from "@assistant-ui/react";
 import { z } from "zod";
 
 const noteSchema = z.object({
@@ -159,12 +160,13 @@ const noteSchema = z.object({
 const noteInitialState = { title: "New Note", content: "", color: "yellow" as const };
 
 function NoteCard({ noteId }: { noteId: string }) {
-  const [state] = useInteractable("note", {
+  useAssistantInteractable("note", {
     id: noteId,
     description: "A sticky note",
     stateSchema: noteSchema,
     initialState: noteInitialState,
   });
+  const [state] = useInteractableState(noteId, noteInitialState);
 
   return <div>{state.title}</div>;
 }
@@ -187,12 +189,13 @@ When multiple interactables are present, you can mark one as "selected" to tell
 
 ```tsx
 function NoteCard({ noteId }: { noteId: string }) {
-  const [state, setState, { setSelected }] = useInteractable("note", {
+  useAssistantInteractable("note", {
     id: noteId,
     description: "A sticky note",
     stateSchema: noteSchema,
     initialState: noteInitialState,
   });
+  const [state, { setSelected }] = useInteractableState(noteId, noteInitialState);
 
   return (
     <div onClick={() => setSelected(true)}>
@@ -206,12 +209,12 @@ The AI sees `(SELECTED)` in the system prompt for the focused interactable, allo
 
 ## API Reference
 
-### `useInteractable`
+### `useAssistantInteractable`
 
-Hook that registers an interactable and returns its state with a setter.
+Registers an interactable with the AI assistant. Returns the instance id.
 
 ```tsx
-const [state, setState, meta] = useInteractable<TState>(name, config);
+const id = useAssistantInteractable(name, config);
 ```
 
 **Parameters:**
@@ -221,43 +224,37 @@ const [state, setState, meta] = useInteractable<TState>(name, config);
 | `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` | `TState` | Initial state value |
+| `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 |
 
-**Returns:** `[state, setState, { id, setSelected }]`
+**Returns:** `string` — the instance id (auto-generated or provided).
 
-| Return | Type | Description |
-| --- | --- | --- |
-| `state` | `TState` | Current state |
-| `setState` | `(updater: TState \| (prev: TState) => TState) => void` | State setter (like `useState`) |
-| `meta.id` | `string` | The instance ID (auto-generated or provided) |
-| `meta.setSelected` | `(selected: boolean) => void` | Mark this interactable as selected |
-
-### `makeInteractable`
+### `useInteractableState`
 
-Declarative API that creates a component which registers an interactable when mounted. Useful for static configurations.
+Reads and writes the state of a registered interactable.
 
 ```tsx
-import { makeInteractable } from "@assistant-ui/react";
+const [state, { setState, setSelected, isPending, error, flush }] = useInteractableState<TState>(id, fallback?);
+```
 
-const TaskBoardInteractable = makeInteractable({
-  name: "taskBoard",
-  description: "A task board showing the user's tasks",
-  stateSchema: taskBoardSchema,
-  initialState: taskBoardInitialState,
-});
+**Parameters:**
 
-// Mount it anywhere — renders nothing, just registers the interactable
-function App() {
-  return (
-    <>
-      <TaskBoardInteractable />
-      <Thread />
-    </>
-  );
-}
-```
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `id` | `string` | The interactable instance id (from `useAssistantInteractable`) |
+| `fallback` | `TState?` | Fallback value before the interactable is registered |
+
+**Returns:** `[state, methods]`
+
+| 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 |
 
 ### `Interactables`
 
@@ -271,7 +268,7 @@ const aui = useAui({
 
 ## How It Works
 
-When you call `useInteractable("taskBoard", config)`:
+When you call `useAssistantInteractable("taskBoard", config)`:
 
 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}`.
@@ -280,6 +277,62 @@ When you call `useInteractable("taskBoard", config)`:
 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.
 
+## Persistence
+
+By default, interactable state is in-memory and lost on page refresh. You can add persistence by providing a save callback:
+
+```tsx
+import { useEffect } from "react";
+import { useAui, Interactables } from "@assistant-ui/react";
+
+function MyRuntimeProvider({ children }) {
+  const aui = useAui({ interactables: Interactables() });
+
+  useEffect(() => {
+    // Set up persistence adapter
+    aui.interactables().setPersistenceAdapter({
+      save: async (state) => {
+        localStorage.setItem("interactables", JSON.stringify(state));
+      },
+    });
+
+    // Restore saved state on mount
+    const saved = localStorage.getItem("interactables");
+    if (saved) {
+      aui.interactables().importState(JSON.parse(saved));
+    }
+  }, [aui]);
+
+  return /* ... */;
+}
+```
+
+### Sync Status
+
+When a persistence adapter is set, `useInteractableState` exposes sync metadata:
+
+```tsx
+const [state, { setState, isPending, error, flush }] = useInteractableState(id, fallback);
+
+// 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.
+
+### Export / Import
+
+For custom persistence strategies, use `exportState` and `importState` directly:
+
+```tsx
+const snapshot = aui.interactables().exportState();
+// => { "note-1": { name: "note", state: { title: "Hello" } }, ... }
+
+aui.interactables().importState(snapshot);
+// Imported state is picked up when components next register
+```
+
 ## Combining with Tools
 
 You can use `Interactables` alongside `Tools`:
@@ -290,3 +343,12 @@ const aui = useAui({
   interactables: Interactables(),
 });
 ```
+
+## 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`)