@assistant-ui/mcp-docs-server 0.1.19 → 0.1.21

package/.docs/raw/docs/(docs)/guides/context-api.mdx

@@ -50,10 +50,10 @@ assistant-ui organizes state into **scopes** - logical boundaries that provide a
 // Inside a message component
 function MessageButton() {
   // ✅ Available: message scope (current message)
-  const role = useAssistantState(({ message }) => message.role);
+  const role = useAuiState(({ message }) => message.role);
 
   // ✅ Available: thread scope (parent)
-  const isRunning = useAssistantState(({ thread }) => thread.isRunning);
+  const isRunning = useAuiState(({ thread }) => thread.isRunning);
 }
 ```
 
@@ -68,22 +68,22 @@ The Context API follows a predictable state management pattern:
 
 ## Essential Hooks
 
-### useAssistantState
+### useAuiState
 
 Read state reactively with automatic re-renders when values change. This hook works like Zustand's selector pattern - you provide a function that extracts the specific data you need, and your component only re-renders when that data changes.
 
 ```tsx
-import { useAssistantState } from "@assistant-ui/react";
+import { useAuiState } from "@assistant-ui/react";
 
 // Basic usage - extract a single property
-const role = useAssistantState(({ message }) => message.role); // "user" | "assistant"
-const isRunning = useAssistantState(({ thread }) => thread.isRunning); // boolean
+const role = useAuiState(({ message }) => message.role); // "user" | "assistant"
+const isRunning = useAuiState(({ thread }) => thread.isRunning); // boolean
 
 // Access nested data
-const attachmentCount = useAssistantState(
+const attachmentCount = useAuiState(
   ({ composer }) => composer.attachments.length,
 );
-const lastMessage = useAssistantState(({ thread }) => thread.messages.at(-1));
+const lastMessage = useAuiState(({ thread }) => thread.messages.at(-1));
 ```
 
 The selector function receives all available scopes for your component's location and should return a specific value. The component re-renders only when that returned value changes.
@@ -92,54 +92,54 @@ The selector function receives all available scopes for your component's locatio
 
 ```tsx
 // Access multiple scopes
-const canSend = useAssistantState(
+const canSend = useAuiState(
   ({ thread, composer }) => !thread.isRunning && composer.text.length > 0,
 );
 
 // Compute derived state
-const messageCount = useAssistantState(({ thread }) => thread.messages.length);
+const messageCount = useAuiState(({ thread }) => thread.messages.length);
 ```
 
 **Important:** Never create new objects in selectors. Return primitive values or stable references to avoid infinite re-renders.
 
 ```tsx
 // ❌ Bad - creates new object every time
-const data = useAssistantState(({ message }) => ({
+const data = useAuiState(({ message }) => ({
   role: message.role,
   content: message.content,
 }));
 
 // ✅ Good - returns stable values
-const role = useAssistantState(({ message }) => message.role);
-const content = useAssistantState(({ message }) => message.content);
+const role = useAuiState(({ message }) => message.role);
+const content = useAuiState(({ message }) => message.content);
 ```
 
-### useAssistantApi
+### useAui
 
-Access the API instance for imperative operations and actions. Unlike `useAssistantState`, this hook returns a stable object that never changes, making it perfect for event handlers and imperative operations.
+Access the API instance for imperative operations and actions. Unlike `useAuiState`, this hook returns a stable object that never changes, making it perfect for event handlers and imperative operations.
 
 ```tsx
-import { useAssistantApi } from "@assistant-ui/react";
+import { useAui } from "@assistant-ui/react";
 
 function CustomMessageActions() {
-  const api = useAssistantApi();
+  const aui = useAui();
 
   // Perform actions in event handlers
   const handleSend = () => {
-    api.composer().send();
+    aui.composer().send();
   };
 
   const handleReload = () => {
-    api.message().reload();
+    aui.message().reload();
   };
 
   // Read state imperatively when needed
   const handleConditionalAction = () => {
-    const { isRunning } = api.thread().getState();
-    const { text } = api.composer().getState();
+    const { isRunning } = aui.thread().getState();
+    const { text } = aui.composer().getState();
 
     if (!isRunning && text.length > 0) {
-      api.composer().send();
+      aui.composer().send();
     }
   };
 
@@ -164,86 +164,86 @@ The API object is stable and doesn't cause re-renders. Use it for:
 
 ```tsx
 // Thread actions
-api.thread().append(message);
-api.thread().startRun(config);
-api.thread().cancelRun();
-api.thread().switchToNewThread();
-api.thread().switchToThread(threadId);
-api.thread().getState();
-api.thread().message(idOrIndex);
-api.thread().composer;
+aui.thread().append(message);
+aui.thread().startRun(config);
+aui.thread().cancelRun();
+aui.thread().switchToNewThread();
+aui.thread().switchToThread(threadId);
+aui.thread().getState();
+aui.thread().message(idOrIndex);
+aui.thread().composer;
 
 // Message actions
-api.message().reload();
-api.message().speak();
-api.message().stopSpeaking();
-api.message().submitFeedback({ type: "positive" | "negative" });
-api.message().switchToBranch({ position, branchId });
-api.message().getState();
-api.message().part(indexOrToolCallId);
-api.message().composer;
+aui.message().reload();
+aui.message().speak();
+aui.message().stopSpeaking();
+aui.message().submitFeedback({ type: "positive" | "negative" });
+aui.message().switchToBranch({ position, branchId });
+aui.message().getState();
+aui.message().part(indexOrToolCallId);
+aui.message().composer;
 
 // Part actions
 api.part().addResult(result);
 api.part().getState();
 
 // Composer actions
-api.composer().send();
-api.composer().setText(text);
-api.composer().setRole(role);
-api.composer().addAttachment(file);
-api.composer().clearAttachments();
-api.composer().reset();
-api.composer().getState();
+aui.composer().send();
+aui.composer().setText(text);
+aui.composer().setRole(role);
+aui.composer().addAttachment(file);
+aui.composer().clearAttachments();
+aui.composer().reset();
+aui.composer().getState();
 
 // Attachment actions
-api.attachment().remove();
-api.attachment().getState();
+aui.attachment().remove();
+aui.attachment().getState();
 
 // ThreadList actions
-api.threads().switchToNewThread();
-api.threads().switchToThread(threadId);
-api.threads().getState();
+aui.threads().switchToNewThread();
+aui.threads().switchToThread(threadId);
+aui.threads().getState();
 
 // ThreadListItem actions
-api.threadListItem().switchTo();
-api.threadListItem().rename(title);
-api.threadListItem().archive();
-api.threadListItem().unarchive();
-api.threadListItem().delete();
-api.threads().getState();
+aui.threadListItem().switchTo();
+aui.threadListItem().rename(title);
+aui.threadListItem().archive();
+aui.threadListItem().unarchive();
+aui.threadListItem().delete();
+aui.threads().getState();
 
 // Tools actions
-api.tools().setToolUI(toolName, render);
-api.tools().getState();
+aui.tools().setToolUI(toolName, render);
+aui.tools().getState();
 ```
 
-### useAssistantEvent
+### useAuiEvent
 
 Subscribe to events with automatic cleanup on unmount. This hook is perfect for reacting to user interactions, system events, or integrating with external analytics.
 
 ```tsx
-import { useAssistantEvent } from "@assistant-ui/react";
+import { useAuiEvent } from "@assistant-ui/react";
 
 // Listen to current scope events (most common)
-useAssistantEvent("composer.send", (event) => {
+useAuiEvent("composer.send", (event) => {
   console.log("Current composer sent message:", event.message);
 });
 
 // Listen to all events of a type across all scopes
-useAssistantEvent({ event: "composer.send", scope: "*" }, (event) => {
+useAuiEvent({ event: "composer.send", scope: "*" }, (event) => {
   console.log("Any composer sent a message:", event);
 });
 
 // Listen to ALL events (useful for debugging or analytics)
-useAssistantEvent("*", (event) => {
+useAuiEvent("*", (event) => {
   console.log("Event occurred:", event.type, "from:", event.source);
   // Send to analytics, logging, etc.
 });
 
 // Practical example: Track user interactions
 function AnalyticsTracker() {
-  useAssistantEvent("composer.send", (event) => {
+  useAuiEvent("composer.send", (event) => {
     analytics.track("message_sent", {
       messageLength: event.message.content.length,
       hasAttachments: event.message.attachments.length > 0,
@@ -256,7 +256,7 @@ function AnalyticsTracker() {
 
 **Event name patterns:**
 
-- Event names follow `source.action` format (e.g., `composer.send`, `thread.run-start`)
+- Event names follow `source.action` format in camelCase (e.g., `composer.send`, `thread.runStart`)
 - Use `"*"` as the event name to listen to all events
 - The `scope` parameter controls which instances trigger the event
 
@@ -281,11 +281,11 @@ The Context API automatically resolves the current scope based on component loca
 
 ```tsx
 function MessageButton() {
-  const api = useAssistantApi();
+  const aui = useAui();
 
   // Automatically uses the current message scope
   const handleReload = () => {
-    api.message().reload();
+    aui.message().reload();
   };
 
   return <button onClick={handleReload}>Reload</button>;
@@ -297,12 +297,12 @@ function MessageButton() {
 Before accessing a scope, check if it's available:
 
 ```tsx
-const api = useAssistantApi();
+const aui = useAui();
 
 // Check if message scope exists
 if (api.message.source) {
   // Safe to use message scope
-  const { role } = api.message().getState();
+  const { role } = aui.message().getState();
 }
 ```
 
@@ -311,22 +311,22 @@ if (api.message.source) {
 Navigate through the scope hierarchy programmatically:
 
 ```tsx
-const api = useAssistantApi();
+const aui = useAui();
 
 // Access specific message by ID or index
-const messageById = api.thread().message({ id: "msg_123" });
-const messageByIndex = api.thread().message({ index: 0 });
+const messageById = aui.thread().message({ id: "msg_123" });
+const messageByIndex = aui.thread().message({ index: 0 });
 
 // Access part by index or tool call ID
-const partByIndex = api.message().part({ index: 0 });
-const partByToolCall = api.message().part({ toolCallId: "call_123" });
+const partByIndex = aui.message().part({ index: 0 });
+const partByToolCall = aui.message().part({ toolCallId: "call_123" });
 
 // Access attachment by index
-const attachment = api.composer().attachment({ index: 0 }).getState();
+const attachment = aui.composer().attachment({ index: 0 }).getState();
 
 // Access thread from thread list
-const thread = api.threads().thread("main");
-const threadItem = api.threads().item({ id: "thread_123" });
+const thread = aui.threads().thread("main");
+const threadItem = aui.threads().item({ id: "thread_123" });
 ```
 
 ## Common Patterns
@@ -335,7 +335,7 @@ const threadItem = api.threads().item({ id: "thread_123" });
 
 ```tsx
 function RunIndicator() {
-  const isRunning = useAssistantState(({ thread }) => thread.isRunning);
+  const isRunning = useAuiState(({ thread }) => thread.isRunning);
 
   if (!isRunning) return null;
   return <div>Assistant is thinking...</div>;
@@ -346,10 +346,10 @@ function RunIndicator() {
 
 ```tsx
 function CopyButton() {
-  const api = useAssistantApi();
+  const aui = useAui();
 
   const handleCopy = () => {
-    navigator.clipboard.writeText(api.message().getCopyText());
+    navigator.clipboard.writeText(aui.message().getCopyText());
   };
 
   return <button onClick={handleCopy}>Copy</button>;
@@ -360,9 +360,9 @@ function CopyButton() {
 
 ```tsx
 function SmartComposer() {
-  const api = useAssistantApi();
-  const isRunning = useAssistantState(({ thread }) => thread.isRunning);
-  const text = useAssistantState(({ composer }) => composer.text);
+  const aui = useAui();
+  const isRunning = useAuiState(({ thread }) => thread.isRunning);
+  const text = useAuiState(({ composer }) => composer.text);
 
   const canSend = !isRunning && text.length > 0;
 
@@ -370,10 +370,10 @@ function SmartComposer() {
     <div>
       <textarea
         value={text}
-        onChange={(e) => api.composer().setText(e.target.value)}
+        onChange={(e) => aui.composer().setText(e.target.value)}
         disabled={isRunning}
       />
-      <button onClick={() => api.composer().send()} disabled={!canSend}>
+      <button onClick={() => aui.composer().send()} disabled={!canSend}>
         Send
       </button>
     </div>
@@ -387,7 +387,7 @@ function SmartComposer() {
 function MessageCounter() {
   const [sendCount, setSendCount] = useState(0);
 
-  useAssistantEvent("composer.send", () => {
+  useAuiEvent("composer.send", () => {
     setSendCount((c) => c + 1);
   });
 
@@ -402,16 +402,16 @@ function MessageCounter() {
 When you call `api.scope()`, the API resolves the current scope at that moment. This resolution happens each time you call the function, which matters when dealing with changing contexts:
 
 ```tsx
-const api = useAssistantApi();
+const aui = useAui();
 
 // Get current thread
-const thread1 = api.thread();
+const thread1 = aui.thread();
 thread1.append({ role: "user", content: "Hello" });
 
 // User might switch threads here
 
 // This could be a different thread
-const thread2 = api.thread();
+const thread2 = aui.thread();
 thread2.cancelRun(); // Cancels the current thread's run, not necessarily thread1's
 ```
 
@@ -423,12 +423,12 @@ For most use cases, this behavior is intuitive. In advanced scenarios where you
 
 ```tsx
 // ❌ Expensive computation in selector (runs on every store update)
-const result = useAssistantState(
+const result = useAuiState(
   ({ thread }) => thread.messages.filter((m) => m.role === "user").length,
 );
 
 // ✅ Memoize expensive computations
-const messages = useAssistantState(({ thread }) => thread.messages);
+const messages = useAuiState(({ thread }) => thread.messages);
 const userCount = useMemo(
   () => messages.filter((m) => m.role === "user").length,
   [messages],
@@ -439,10 +439,10 @@ const userCount = useMemo(
 
 ```tsx
 // ❌ Subscribes to entire thread state
-const thread = useAssistantState(({ thread }) => thread);
+const thread = useAuiState(({ thread }) => thread);
 
 // ✅ Subscribe only to needed values
-const isRunning = useAssistantState(({ thread }) => thread.isRunning);
+const isRunning = useAuiState(({ thread }) => thread.isRunning);
 ```
 
 ## API Reference
@@ -451,9 +451,9 @@ const isRunning = useAssistantState(({ thread }) => thread.isRunning);
 
 | Hook                                | Purpose                    | Returns        |
 | ----------------------------------- | -------------------------- | -------------- |
-| `useAssistantState(selector)`       | Subscribe to state changes | Selected value |
-| `useAssistantApi()`                 | Get API instance           | API object     |
-| `useAssistantEvent(event, handler)` | Subscribe to events        | void           |
+| `useAuiState(selector)`       | Subscribe to state changes | Selected value |
+| `useAui()`                 | Get API instance           | API object     |
+| `useAuiEvent(event, handler)` | Subscribe to events        | void           |
 
 ### Scope States
 
@@ -483,14 +483,14 @@ const isRunning = useAssistantState(({ thread }) => thread.isRunning);
 
 | Event                            | Description                   |
 | -------------------------------- | ----------------------------- |
-| `thread.run-start`               | Assistant starts generating   |
-| `thread.run-end`                 | Assistant finishes generating |
+| `thread.runStart`                | Assistant starts generating   |
+| `thread.runEnd`                  | Assistant finishes generating |
 | `thread.initialize`              | Thread is initialized         |
-| `thread.model-context-update`    | Model context is updated      |
+| `thread.modelContextUpdate`      | Model context is updated      |
 | `composer.send`                  | Message is sent               |
-| `composer.attachment-add`        | Attachment added to composer  |
-| `thread-list-item.switched-to`   | Switched to a thread          |
-| `thread-list-item.switched-away` | Switched away from a thread   |
+| `composer.attachmentAdd`         | Attachment added to composer  |
+| `threadListItem.switchedTo`      | Switched to a thread          |
+| `threadListItem.switchedAway`    | Switched away from a thread   |
 
 ## Troubleshooting
 
@@ -500,13 +500,13 @@ const isRunning = useAssistantState(({ thread }) => thread.isRunning);
 
 ```tsx
 // ❌ This will throw if not inside a message component
-const role = useAssistantState(({ message }) => message.role);
+const role = useAuiState(({ message }) => message.role);
 
 // ✅ Check scope availability first
 function SafeMessageButton() {
-  const api = useAssistantApi();
+  const aui = useAui();
 
-  const role = useAssistantState(({ message }) =>
+  const role = useAuiState(({ message }) =>
     api.message.source !== undefined ? message.role : "none",
   );
 
@@ -518,22 +518,22 @@ function SafeMessageButton() {
 
 ```tsx
 // ❌ Creating new objects in selectors causes infinite re-renders
-const data = useAssistantState(({ message }) => ({
+const data = useAuiState(({ message }) => ({
   role: message.role,
   content: message.content, // New object every time!
 }));
 
 // ✅ Return primitive values or use separate selectors
-const role = useAssistantState(({ message }) => message.role);
-const content = useAssistantState(({ message }) => message.content);
+const role = useAuiState(({ message }) => message.role);
+const content = useAuiState(({ message }) => message.content);
 ```
 
 **"Scope resolution failed" / Stale scope references**
 
 ```tsx
 // ❌ Storing scope references can lead to stale data
-const api = useAssistantApi();
-const thread = api.thread(); // This reference might become stale
+const aui = useAui();
+const thread = aui.thread(); // This reference might become stale
 
 useEffect(() => {
   // This might reference the wrong thread if user switched
@@ -541,26 +541,26 @@ useEffect(() => {
 }, [thread]);
 
 // ✅ Resolve scopes fresh each time
-const api = useAssistantApi();
+const aui = useAui();
 
 useEffect(() => {
   // Always gets the current thread
-  api.thread().cancelRun();
-}, [api]);
+  aui.thread().cancelRun();
+}, [aui]);
 ```
 
 ## Quick Reference
 
 ```tsx
 // Read state
-const value = useAssistantState(({ scope }) => scope.property);
+const value = useAuiState(({ scope }) => scope.property);
 
 // Perform action
-const api = useAssistantApi();
+const aui = useAui();
 api.scope().action();
 
 // Listen to events
-useAssistantEvent("source.event", (e) => {});
+useAuiEvent("source.event", (e) => {});
 
 // Check scope availability
 if (api.scope.source) {
@@ -571,5 +571,5 @@ if (api.scope.source) {
 const state = api.scope().getState();
 
 // Navigate scopes
-api.thread().message({ id: "..." }).getState();
+aui.thread().message({ id: "..." }).getState();
 ```