@assistant-ui/mcp-docs-server 0.1.22 → 0.1.24

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

@@ -45,9 +45,7 @@ For `useChatRuntime`, attachments work automatically without additional configur
 ```tsx title="/app/MyRuntimeProvider.tsx"
 import { useChatRuntime } from "@assistant-ui/react-ai-sdk";
 
-const runtime = useChatRuntime({
-  api: "/api/chat",
-});
+const runtime = useChatRuntime();
 ```
 
 <Callout type="info">
@@ -479,6 +477,31 @@ class ValidatedImageAdapter implements AttachmentAdapter {
 }
 ```
 
+### External Source Attachments
+
+Add attachments from external sources (URLs, API data, CMS references) without needing a `File` object or an `AttachmentAdapter`:
+
+```tsx
+const aui = useAui();
+
+// Add an attachment from an external source
+await aui.composer().addAttachment({
+  name: "report.pdf",
+  contentType: "application/pdf",
+  content: [{ type: "text", text: "Extracted document content..." }],
+});
+
+// Optionally provide id and type
+await aui.composer().addAttachment({
+  id: "cms-doc-123",
+  type: "document",
+  name: "Product Spec",
+  content: [{ type: "text", text: "Product specification content..." }],
+});
+```
+
+External attachments are added as complete attachments directly — they skip the `AttachmentAdapter` entirely and can be removed without one.
+
 ### Multiple File Selection
 
 Enable multi-file selection with custom limits:

package/.docs/raw/docs/(docs)/guides/chain-of-thought.mdx

@@ -46,7 +46,7 @@ const ChainOfThought: FC = () => {
       <ChainOfThoughtPrimitive.AccordionTrigger className="flex w-full cursor-pointer items-center gap-2 px-4 py-2 font-medium text-sm hover:bg-muted/50">
         Thinking
       </ChainOfThoughtPrimitive.AccordionTrigger>
-      <AuiIf condition={({ chainOfThought }) => !chainOfThought.collapsed}>
+      <AuiIf condition={(s) => !s.chainOfThought.collapsed}>
         <ChainOfThoughtPrimitive.Parts
           components={{ Reasoning, tools: { Fallback: ToolFallback } }}
         />
@@ -110,7 +110,7 @@ A button that toggles the collapsed/expanded state. Collapsed by default.
 Renders the grouped parts when expanded (nothing when collapsed).
 
 ```tsx
-<AuiIf condition={({ chainOfThought }) => !chainOfThought.collapsed}>
+<AuiIf condition={(s) => !s.chainOfThought.collapsed}>
   <ChainOfThoughtPrimitive.Parts
     components={{
       Reasoning,
@@ -140,10 +140,10 @@ import { ChevronDownIcon, ChevronRightIcon } from "lucide-react";
 const ChainOfThoughtAccordionTrigger = () => {
   return (
     <ChainOfThoughtPrimitive.AccordionTrigger className="flex w-full cursor-pointer items-center gap-2 px-4 py-2 text-sm">
-      <AuiIf condition={({ chainOfThought }) => chainOfThought.collapsed}>
+      <AuiIf condition={(s) => s.chainOfThought.collapsed}>
         <ChevronRightIcon className="size-4" />
       </AuiIf>
-      <AuiIf condition={({ chainOfThought }) => !chainOfThought.collapsed}>
+      <AuiIf condition={(s) => !s.chainOfThought.collapsed}>
         <ChevronDownIcon className="size-4" />
       </AuiIf>
       Thinking
@@ -154,7 +154,7 @@ const ChainOfThoughtAccordionTrigger = () => {
 
 ## Full Example
 
-See the complete [with-chain-of-thought example](https://github.com/Yonom/assistant-ui/tree/main/examples/with-chain-of-thought) for a working implementation with tool calls and reasoning.
+See the complete [with-chain-of-thought example](https://github.com/assistant-ui/assistant-ui/tree/main/examples/with-chain-of-thought) for a working implementation with tool calls and reasoning.
 
 ## Related Guides
 

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 = useAuiState(({ message }) => message.role);
+  const role = useAuiState((s) => s.message.role);
 
   // ✅ Available: thread scope (parent)
-  const isRunning = useAuiState(({ thread }) => thread.isRunning);
+  const isRunning = useAuiState((s) => s.thread.isRunning);
 }
 ```
 
@@ -76,14 +76,14 @@ Read state reactively with automatic re-renders when values change. This hook wo
 import { useAuiState } from "@assistant-ui/react";
 
 // Basic usage - extract a single property
-const role = useAuiState(({ message }) => message.role); // "user" | "assistant"
-const isRunning = useAuiState(({ thread }) => thread.isRunning); // boolean
+const role = useAuiState((s) => s.message.role); // "user" | "assistant"
+const isRunning = useAuiState((s) => s.thread.isRunning); // boolean
 
 // Access nested data
 const attachmentCount = useAuiState(
-  ({ composer }) => composer.attachments.length,
+  (s) => s.composer.attachments.length,
 );
-const lastMessage = useAuiState(({ thread }) => thread.messages.at(-1));
+const lastMessage = useAuiState((s) => s.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.
@@ -93,25 +93,25 @@ The selector function receives all available scopes for your component's locatio
 ```tsx
 // Access multiple scopes
 const canSend = useAuiState(
-  ({ thread, composer }) => !thread.isRunning && composer.text.length > 0,
+  (s) => !s.thread.isRunning && s.composer.text.length > 0,
 );
 
 // Compute derived state
-const messageCount = useAuiState(({ thread }) => thread.messages.length);
+const messageCount = useAuiState((s) => s.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 = useAuiState(({ message }) => ({
-  role: message.role,
-  content: message.content,
+const data = useAuiState((s) => ({
+  role: s.message.role,
+  content: s.message.content,
 }));
 
 // ✅ Good - returns stable values
-const role = useAuiState(({ message }) => message.role);
-const content = useAuiState(({ message }) => message.content);
+const role = useAuiState((s) => s.message.role);
+const content = useAuiState((s) => s.message.content);
 ```
 
 ### useAui
@@ -191,7 +191,8 @@ api.part().getState();
 aui.composer().send();
 aui.composer().setText(text);
 aui.composer().setRole(role);
-aui.composer().addAttachment(file);
+aui.composer().addAttachment(file); // File object
+aui.composer().addAttachment({ name, content }); // external source
 aui.composer().clearAttachments();
 aui.composer().reset();
 aui.composer().getState();
@@ -335,7 +336,7 @@ const threadItem = aui.threads().item({ id: "thread_123" });
 
 ```tsx
 function RunIndicator() {
-  const isRunning = useAuiState(({ thread }) => thread.isRunning);
+  const isRunning = useAuiState((s) => s.thread.isRunning);
 
   if (!isRunning) return null;
   return <div>Assistant is thinking...</div>;
@@ -361,8 +362,8 @@ function CopyButton() {
 ```tsx
 function SmartComposer() {
   const aui = useAui();
-  const isRunning = useAuiState(({ thread }) => thread.isRunning);
-  const text = useAuiState(({ composer }) => composer.text);
+  const isRunning = useAuiState((s) => s.thread.isRunning);
+  const text = useAuiState((s) => s.composer.text);
 
   const canSend = !isRunning && text.length > 0;
 
@@ -424,11 +425,11 @@ 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 = useAuiState(
-  ({ thread }) => thread.messages.filter((m) => m.role === "user").length,
+  (s) => s.thread.messages.filter((m) => m.role === "user").length,
 );
 
 // ✅ Memoize expensive computations
-const messages = useAuiState(({ thread }) => thread.messages);
+const messages = useAuiState((s) => s.thread.messages);
 const userCount = useMemo(
   () => messages.filter((m) => m.role === "user").length,
   [messages],
@@ -439,20 +440,20 @@ const userCount = useMemo(
 
 ```tsx
 // ❌ Subscribes to entire thread state
-const thread = useAuiState(({ thread }) => thread);
+const thread = useAuiState((s) => s.thread);
 
 // ✅ Subscribe only to needed values
-const isRunning = useAuiState(({ thread }) => thread.isRunning);
+const isRunning = useAuiState((s) => s.thread.isRunning);
 ```
 
 ## API Reference
 
 ### Hooks
 
-| Hook                                | Purpose                    | Returns        |
-| ----------------------------------- | -------------------------- | -------------- |
+| Hook                          | Purpose                    | Returns        |
+| ----------------------------- | -------------------------- | -------------- |
 | `useAuiState(selector)`       | Subscribe to state changes | Selected value |
-| `useAui()`                 | Get API instance           | API object     |
+| `useAui()`                    | Get API instance           | API object     |
 | `useAuiEvent(event, handler)` | Subscribe to events        | void           |
 
 ### Scope States
@@ -469,28 +470,28 @@ const isRunning = useAuiState(({ thread }) => thread.isRunning);
 
 ### Available Actions by Scope
 
-| Scope          | Actions                                                               | Use Cases                                 |
-| -------------- | --------------------------------------------------------------------- | ----------------------------------------- |
-| ThreadList     | `switchToNewThread()`, `switchToThread(id)`, `getState()`             | Thread navigation and creation            |
-| ThreadListItem | `switchTo()`, `rename(title)`, `archive()`, `unarchive()`, `delete()` | Thread management operations              |
-| Thread         | `append(message)`, `startRun()`, `cancelRun()`, `switchToNewThread()` | Message handling and conversation control |
-| Message        | `reload()`, `speak()`, `stopSpeaking()`, `submitFeedback(feedback)`   | Message interactions and regeneration     |
-| Composer       | `send()`, `setText(text)`, `addAttachment(file)`, `reset()`           | Text input and message composition        |
-| Part           | `addResult(result)`, `getState()`                                     | Tool call result handling                 |
-| Attachment     | `remove()`, `getState()`                                              | File management                           |
+| Scope          | Actions                                                                   | Use Cases                                 |
+| -------------- | ------------------------------------------------------------------------- | ----------------------------------------- |
+| ThreadList     | `switchToNewThread()`, `switchToThread(id)`, `getState()`                 | Thread navigation and creation            |
+| ThreadListItem | `switchTo()`, `rename(title)`, `archive()`, `unarchive()`, `delete()`     | Thread management operations              |
+| Thread         | `append(message)`, `startRun()`, `cancelRun()`, `switchToNewThread()`     | Message handling and conversation control |
+| Message        | `reload()`, `speak()`, `stopSpeaking()`, `submitFeedback(feedback)`       | Message interactions and regeneration     |
+| Composer       | `send()`, `setText(text)`, `addAttachment(file \| attachment)`, `reset()` | Text input and message composition        |
+| Part           | `addResult(result)`, `getState()`                                         | Tool call result handling                 |
+| Attachment     | `remove()`, `getState()`                                                  | File management                           |
 
 ### Common Events
 
-| Event                            | Description                   |
-| -------------------------------- | ----------------------------- |
-| `thread.runStart`                | Assistant starts generating   |
-| `thread.runEnd`                  | Assistant finishes generating |
-| `thread.initialize`              | Thread is initialized         |
-| `thread.modelContextUpdate`      | Model context is updated      |
-| `composer.send`                  | Message is sent               |
-| `composer.attachmentAdd`         | Attachment added to composer  |
-| `threadListItem.switchedTo`      | Switched to a thread          |
-| `threadListItem.switchedAway`    | Switched away from a thread   |
+| Event                         | Description                   |
+| ----------------------------- | ----------------------------- |
+| `thread.runStart`             | Assistant starts generating   |
+| `thread.runEnd`               | Assistant finishes generating |
+| `thread.initialize`           | Thread is initialized         |
+| `thread.modelContextUpdate`   | Model context is updated      |
+| `composer.send`               | Message is sent               |
+| `composer.attachmentAdd`      | Attachment added to composer  |
+| `threadListItem.switchedTo`   | Switched to a thread          |
+| `threadListItem.switchedAway` | Switched away from a thread   |
 
 ## Troubleshooting
 
@@ -500,14 +501,14 @@ const isRunning = useAuiState(({ thread }) => thread.isRunning);
 
 ```tsx
 // ❌ This will throw if not inside a message component
-const role = useAuiState(({ message }) => message.role);
+const role = useAuiState((s) => s.message.role);
 
 // ✅ Check scope availability first
 function SafeMessageButton() {
   const aui = useAui();
 
-  const role = useAuiState(({ message }) =>
-    api.message.source !== undefined ? message.role : "none",
+  const role = useAuiState((s) =>
+    api.message.source !== undefined ? s.message.role : "none",
   );
 
   return <div>Role: {role}</div>;
@@ -518,14 +519,14 @@ function SafeMessageButton() {
 
 ```tsx
 // ❌ Creating new objects in selectors causes infinite re-renders
-const data = useAuiState(({ message }) => ({
-  role: message.role,
-  content: message.content, // New object every time!
+const data = useAuiState((s) => ({
+  role: s.message.role,
+  content: s.message.content, // New object every time!
 }));
 
 // ✅ Return primitive values or use separate selectors
-const role = useAuiState(({ message }) => message.role);
-const content = useAuiState(({ message }) => message.content);
+const role = useAuiState((s) => s.message.role);
+const content = useAuiState((s) => s.message.content);
 ```
 
 **"Scope resolution failed" / Stale scope references**
@@ -553,7 +554,7 @@ useEffect(() => {
 
 ```tsx
 // Read state
-const value = useAuiState(({ scope }) => scope.property);
+const value = useAuiState((s) => s.scope.property);
 
 // Perform action
 const aui = useAui();

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

@@ -22,7 +22,6 @@ The `WebSpeechDictationAdapter` is supported in Chrome, Edge, and Safari. Check
 import { WebSpeechDictationAdapter } from "@assistant-ui/react";
 
 const runtime = useChatRuntime({
-  api: "/api/chat",
   adapters: {
     dictation: new WebSpeechDictationAdapter({
       // Optional configuration
@@ -345,7 +344,6 @@ export class ElevenLabsScribeAdapter implements DictationAdapter {
 
 ```tsx
 const runtime = useChatRuntime({
-  api: "/api/chat",
   adapters: {
     dictation: new ElevenLabsScribeAdapter({
       tokenEndpoint: "/api/scribe-token",

package/.docs/raw/docs/(docs)/guides/message-timing.mdx

@@ -0,0 +1,169 @@
+---
+title: Message Timing
+description: Display stream timing metadata like duration, tokens per second, and time to first token.
+---
+
+Display stream performance metrics — duration, tokens per second, TTFT — on assistant messages.
+
+<Callout type="info">
+  The [`MessageTiming`](/docs/ui/message-timing) registry component provides a ready-made badge + popover UI. This guide covers the underlying `useMessageTiming()` hook for custom implementations and runtime-specific setup.
+</Callout>
+
+## Reading Timing Data
+
+Use `useMessageTiming()` inside a message component to access timing data:
+
+```tsx
+import { useMessageTiming } from "@assistant-ui/react";
+
+const MessageTimingDisplay: FC = () => {
+  const timing = useMessageTiming();
+  if (!timing?.totalStreamTime) return null;
+
+  const formatMs = (ms: number) =>
+    ms < 1000 ? `${Math.round(ms)}ms` : `${(ms / 1000).toFixed(2)}s`;
+
+  return (
+    <span className="text-xs text-muted-foreground">
+      {formatMs(timing.totalStreamTime)}
+      {timing.tokensPerSecond !== undefined &&
+        ` · ${timing.tokensPerSecond.toFixed(1)} tok/s`}
+    </span>
+  );
+};
+```
+
+Place it inside `MessagePrimitive.Root`, typically near the action bar:
+
+```tsx {8}
+const AssistantMessage: FC = () => {
+  return (
+    <MessagePrimitive.Root>
+      <MessagePrimitive.Parts components={{ ... }} />
+      <ActionBarPrimitive.Root>
+        <ActionBarPrimitive.Copy />
+        <ActionBarPrimitive.Reload />
+        <MessageTimingDisplay />
+      </ActionBarPrimitive.Root>
+    </MessagePrimitive.Root>
+  );
+};
+```
+
+### `useMessageTiming()` Return Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `streamStartTime` | `number` | Unix timestamp when stream started |
+| `firstTokenTime` | `number?` | Time to first text token (ms) |
+| `totalStreamTime` | `number?` | Total stream duration (ms) |
+| `tokenCount` | `number?` | Real or estimated output token count |
+| `tokensPerSecond` | `number?` | Throughput (tokens/sec); see [accuracy note](#ai-sdk-usechatruntime) |
+| `totalChunks` | `number` | Total stream chunks received |
+| `toolCallCount` | `number` | Number of tool calls |
+
+## Runtime Support
+
+| Runtime | Supported | Notes |
+|---------|:-:|-------|
+| DataStream | Yes | Automatic via `AssistantMessageAccumulator` |
+| AI SDK (`useChatRuntime`) | Yes | Automatic via client-side tracking |
+| Local (`useLocalRuntime`) | Yes | Pass timing in `ChatModelRunResult.metadata` |
+| ExternalStore | Yes | Pass timing in `ThreadMessageLike.metadata` |
+| LangGraph | No | Not yet implemented |
+| AG-UI | No | Not yet implemented |
+
+### DataStream
+
+Timing is tracked automatically inside `AssistantMessageAccumulator`. No setup required.
+
+```tsx
+import { useDataStreamRuntime } from "@assistant-ui/react-data-stream";
+
+const runtime = useDataStreamRuntime({ api: "/api/chat" });
+// useMessageTiming() works out of the box
+```
+
+### AI SDK (`useChatRuntime`)
+
+Timing is tracked automatically on the client side by observing streaming state transitions and content changes. Timing is finalized when each stream completes.
+
+<Callout type="warn">
+  `tokenCount` and `tokensPerSecond` are **estimated** using a 4 characters per token approximation — real token counts from the server are not extracted. This can overcount significantly for short messages.
+</Callout>
+
+```tsx
+import { useChatRuntime } from "@assistant-ui/react-ai-sdk";
+
+const runtime = useChatRuntime();
+// useMessageTiming() works out of the box
+```
+
+### Local (`useLocalRuntime`)
+
+Pass timing in the `metadata` field of your `ChatModelRunResult`:
+
+```tsx
+import type { ChatModelAdapter } from "@assistant-ui/react";
+
+const myAdapter: ChatModelAdapter = {
+  async run({ messages, abortSignal }) {
+    const startTime = Date.now();
+    const result = await callMyAPI(messages, abortSignal);
+    const totalStreamTime = Date.now() - startTime;
+
+    return {
+      content: [{ type: "text", text: result.text }],
+      metadata: {
+        timing: {
+          streamStartTime: startTime,
+          totalStreamTime,
+          tokenCount: result.usage?.completionTokens,
+          tokensPerSecond:
+            result.usage?.completionTokens
+              ? result.usage.completionTokens / (totalStreamTime / 1000)
+              : undefined,
+          totalChunks: 1,
+          toolCallCount: 0,
+        },
+      },
+    };
+  },
+};
+```
+
+### ExternalStore (`useExternalStoreRuntime`)
+
+Pass timing in the `metadata.timing` field of your `ThreadMessageLike` messages:
+
+```tsx
+import type { ThreadMessageLike } from "@assistant-ui/react";
+
+const message: ThreadMessageLike = {
+  role: "assistant",
+  content: [{ type: "text", text: fullText }],
+  metadata: {
+    timing: {
+      streamStartTime: startTime,
+      firstTokenTime,
+      totalStreamTime,
+      tokenCount,
+      tokensPerSecond,
+      totalChunks: chunks,
+      toolCallCount: 0,
+    },
+  },
+};
+```
+
+## API Reference
+
+### `useMessageTiming()`
+
+```tsx
+const timing: MessageTiming | undefined = useMessageTiming();
+```
+
+Returns timing metadata for the current assistant message, or `undefined` for non-assistant messages or when no timing data is available.
+
+Must be used inside a `MessagePrimitive.Root` context.