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

package/.docs/raw/docs/tools/tool-ui.mdx

@@ -96,14 +96,14 @@ Learn more about creating tools in the [Tools Guide](/docs/tools/defining-tools)
 If your tool is defined elsewhere (e.g., in your backend API, MCP server, or LangGraph), register a backend toolkit entry with just `render`:
 
 ```tsx
-const toolkit = {
+const toolkit = defineToolkit({
   getWeather: {
     type: "backend",
     render: ({ args, result, status }) => {
       // UI rendering logic only
     },
   },
-} satisfies Toolkit;
+});
 ```
 
 ## Quick Start Example
@@ -180,12 +180,12 @@ const WeatherToolUI: ToolCallMessagePartComponent<
 Put the renderer on the matching backend toolkit entry:
 
 ```tsx
-const toolkit = {
+const toolkit = defineToolkit({
   getWeather: {
     type: "backend",
     render: WeatherToolUI,
   },
-} satisfies Toolkit;
+});
 
 function App({ runtime }: { runtime: AssistantRuntime }) {
   const aui = useAui({ tools: Tools({ toolkit }) });
@@ -286,12 +286,12 @@ export const WebSearchToolUI: ToolCallMessagePartComponent<
 Register it on the toolkit:
 
 ```tsx
-const toolkit = {
+const toolkit = defineToolkit({
   webSearch: {
     type: "backend",
     render: WebSearchToolUI,
   },
-} satisfies Toolkit;
+});
 ```
 
 ### Dynamic Toolkit Pattern
@@ -301,7 +301,7 @@ Use a toolkit hook in its own file when the renderer needs component state:
 ```tsx title="analyze-data-toolkit.tsx"
 "use client";
 
-import { type Toolkit, useInlineRender } from "@assistant-ui/react";
+import { defineToolkit, useInlineRender } from "@assistant-ui/react";
 import { useMemo } from "react";
 
 export function useAnalyzeDataToolkit(theme: "light" | "dark") {
@@ -317,12 +317,12 @@ export function useAnalyzeDataToolkit(theme: "light" | "dark") {
 
   return useMemo(
     () =>
-      ({
+      defineToolkit({
         analyzeData: {
           type: "backend",
           render: renderAnalyzeData,
         },
-      }) satisfies Toolkit,
+      }),
     [renderAnalyzeData],
   );
 }
@@ -358,7 +358,7 @@ For tools that need access to parent component props:
 ```tsx title="inventory-toolkit.tsx"
 "use client";
 
-import { type Toolkit, useInlineRender } from "@assistant-ui/react";
+import { defineToolkit, useInlineRender } from "@assistant-ui/react";
 import { useMemo } from "react";
 
 export function useInventoryToolkit(productId: string, productName: string) {
@@ -376,12 +376,12 @@ export function useInventoryToolkit(productId: string, productName: string) {
 
   return useMemo(
     () =>
-      ({
+      defineToolkit({
         checkInventory: {
           type: "backend",
           render: renderInventory,
         },
-      }) satisfies Toolkit,
+      }),
     [renderInventory],
   );
 }
@@ -419,7 +419,7 @@ Create tools that collect user input during execution:
 </Callout>
 
 ```tsx
-const toolkit = {
+const toolkit = defineToolkit({
   selectDate: {
     type: "human",
     description: "Ask the user to select a date.",
@@ -445,7 +445,7 @@ const toolkit = {
       );
     },
   },
-} satisfies Toolkit;
+});
 ```
 
 ### Multi-Step Interactions
@@ -540,7 +540,7 @@ export default defineToolkit({
 Some runtimes (notably AI SDK v6's `needsApproval` tools) pause on the server and emit an approval request that the client must acknowledge before the tool runs. assistant-ui surfaces this on the tool part as `approval` and exposes `respondToApproval({ approved, reason? })` on the renderer:
 
 ```tsx
-const toolkit = {
+const toolkit = defineToolkit({
   deploy: {
     type: "backend",
     render: ({ args, approval, respondToApproval, result }) => {
@@ -570,19 +570,55 @@ const toolkit = {
       return <p>Deployed</p>;
     },
   },
-} satisfies Toolkit;
+});
 ```
 
 `approval.approved` is a three-state signal:
 
 - `undefined`: gate is open, the renderer should ask the user. This is the only state in which `respondToApproval` is legal.
 - `true`: decision recorded as allow. The server is producing the result (or has produced one, available on `result`).
-- `false`: decision recorded as deny. `output-denied` from the runtime sets `isError` and exposes `approval.reason`.
+- `false`: decision recorded as deny. The runtime records an error result (`isError`) and exposes `approval.reason`.
 
 `approval.isAutomatic` is `true` when the runtime granted the decision from a server-side policy rather than the user; render a "auto-approved" badge instead of buttons in that case.
 
+Approval gates require a runtime that implements them: the AI SDK v6 runtime emits them for `needsApproval` tools, and `LocalRuntime` supports gates emitted by your `ChatModelAdapter`; see [LocalRuntime approval gates](/docs/runtimes/custom/local-runtime#approval-gates). For tools where the user supplies the result itself, use `unstable_humanToolNames` with `addResult` instead; see [human-in-the-loop tools](/docs/runtimes/custom/local-runtime#human-in-the-loop-tools).
+
 For the wire-side setup (`needsApproval`, `sendAutomaticallyWhen`), see [AI SDK v6 server-side tool approval](/docs/runtimes/ai-sdk/v6#server-side-tool-approval).
 
+### Approval options
+
+Beyond the plain allow / deny pair, the host can attach a list of decision options to an approval, for example "allow once", "allow for this session", and "always allow". Each option carries a machine-readable `kind` (`"allow-once"`, `"allow-always"`, `"reject-once"`, `"reject-always"`); scope semantics like session versus global belong to the option's `id` and `label`, which only the host interprets:
+
+```ts
+const approval = {
+  id: "a1",
+  options: [
+    { id: "once", kind: "allow-once" },
+    { id: "session", kind: "allow-always", label: "Allow for this session" },
+    {
+      id: "always",
+      kind: "allow-always",
+      label: "Always allow",
+      grants: ["git *"],
+      confirm: true,
+    },
+    { id: "deny", kind: "reject-once" },
+  ],
+};
+```
+
+Renderers respond with the chosen option instead of a boolean; the option's kind resolves the decision:
+
+```tsx
+respondToApproval({ optionId: "session" });
+```
+
+The runtime receives `{ approvalId, approved, optionId, reason? }`, so a host that persists "always allow" decisions can key its store off `optionId`. Persistence is entirely host-owned: assistant-ui never stores a decision and never auto-answers future approvals. `grants` lists the patterns an option would persist (shown to the user before they commit), and `confirm` opts the option into a confirmation step. Options with custom `_`-prefixed kinds are skipped by the default `ToolFallback` bar and must be answered with an explicit `approved` value, optionally alongside the `optionId` so the chosen option is still recorded.
+
+Approvals that end without a decision (a cancelled run or an expired request) are recorded by the host as `approval.resolution: "cancelled" | "expired"`, which closes the gate without recording a deny.
+
+The default `ToolFallback` component renders supplied options automatically, including the confirmation step.
+
 ## Advanced Features
 
 ### Tool Status Handling
@@ -626,7 +662,7 @@ Sometimes you want to capture a tool call's streaming arguments but only render
 Return `null` from the tool UI's `render` until `status.type === "complete"`. The streaming args still arrive in `args` as the model emits them, you just ignore them until the call is done:
 
 ```tsx
-const toolkit = {
+const toolkit = defineToolkit({
   renderChart: {
     type: "backend",
     render: ({ args, status }) => {
@@ -634,7 +670,7 @@ const toolkit = {
       return <Chart title={args.title} data={args.series} />;
     },
   },
-} satisfies Toolkit;
+});
 ```
 
 The chart mounts once, with the final args, after streaming finishes. No re-renders during the stream.
@@ -682,7 +718,7 @@ Use `useToolArgsStatus` to react to per-field streaming state. The hook returns
 ```tsx
 import { useToolArgsStatus } from "@assistant-ui/react";
 
-const toolkit = {
+const toolkit = defineToolkit({
   submitForm: {
     type: "backend",
     render: ({ args }) => {
@@ -714,7 +750,7 @@ const toolkit = {
       );
     },
   },
-} satisfies Toolkit;
+});
 ```
 
 ### Partial Results & Streaming
@@ -722,7 +758,7 @@ const toolkit = {
 Display results as they stream in:
 
 ```tsx
-const toolkit = {
+const toolkit = defineToolkit({
   analyzeData: {
     type: "backend",
     render: ({ result, status }) => {
@@ -757,7 +793,7 @@ const toolkit = {
       );
     },
   },
-} satisfies Toolkit;
+});
 ```
 
 ### Custom Tool Fallback
@@ -802,7 +838,7 @@ type ToolCallMessagePartProps<TArgs, TResult> = {
 When a tool calls `human()` during execution, the payload becomes available in the render function as `interrupt.payload`:
 
 ```tsx
-const toolkit = {
+const toolkit = defineToolkit({
   confirmAction: {
     type: "backend",
     render: ({ args, result, interrupt, resume }) => {
@@ -825,7 +861,7 @@ const toolkit = {
       return <div>Processing...</div>;
     },
   },
-} satisfies Toolkit;
+});
 ```
 
 Learn more about tool human input in the [Tools Guide](/docs/tools/defining-tools#human-tools).
@@ -882,7 +918,7 @@ Use `useInlineRender` to prevent unnecessary re-renders:
 ```tsx title="heavy-computation-toolkit.tsx"
 "use client";
 
-import { type Toolkit, useInlineRender } from "@assistant-ui/react";
+import { defineToolkit, useInlineRender } from "@assistant-ui/react";
 import { useMemo } from "react";
 
 export function useHeavyComputationToolkit() {
@@ -892,12 +928,12 @@ export function useHeavyComputationToolkit() {
 
   return useMemo(
     () =>
-      ({
+      defineToolkit({
         heavyComputation: {
           type: "backend",
           render: renderHeavyComputation,
         },
-      }) satisfies Toolkit,
+      }),
     [renderHeavyComputation],
   );
 }

package/.docs/raw/docs/tools/user-managed-mcp.mdx

@@ -17,12 +17,12 @@ Both flow through one connection lifecycle, one persisted state surface, and one
 ```
 useAui({ mcp: McpManagerResource({ connectors }) })
         │
-        ├─ Tap resource — connection lifecycle, server lookup, OAuth/bearer auth
+        ├─ Resource — connection lifecycle, server lookup, OAuth/bearer auth
         ├─ Auto-mounts the modelContext scope when no chat runtime provides one
         └─ Registers connected tools as frontend tools — your chat sees them automatically
 ```
 
-The manager is a single tap resource. Mount it with `useAui` like any other scope. OAuth (PKCE + RFC 7591 dynamic client registration), bearer, and "no auth" are first-class. Token refresh runs inside the MCP SDK on 401; this package mediates persistence and the redirect step.
+The manager is a single resource. Mount it with `useAui` like any other scope. OAuth (PKCE + RFC 7591 dynamic client registration), bearer, and "no auth" are first-class. Token refresh runs inside the MCP SDK on 401; this package mediates persistence and the redirect step.
 
 ## Setup
 
@@ -221,7 +221,7 @@ Tool names are prefixed `serverId__toolName` to avoid collisions across connecte
 If no chat runtime is mounted, `McpManagerResource` brings its own minimal `modelContext` along. Tools are still callable directly:
 
 ```ts
-// In an event handler — never in render. See the tap conventions.
+// In an event handler, never in render.
 const aui = useAui();
 const out = await aui.mcp().server({ id: "linear" }).callTool("search", { q });
 ```
@@ -293,7 +293,7 @@ const connectionState = useAuiState((s) => s.mcpServer.connectionState);
 //                                          ^ requires McpServerByIdProvider
 ```
 
-Imperative methods — `useAui` + resolve in a callback (never during render — see the [tap skill](https://github.com/assistant-ui/assistant-ui/blob/main/.claude/skills/tap/SKILL.md) for why):
+Imperative methods: `useAui` + resolve in a callback (never during render):
 
 ```ts
 const aui = useAui();

package/.docs/raw/docs/ui/dot-matrix.mdx

@@ -0,0 +1,133 @@
+---
+title: Dot Matrix
+description: Tiny 5x5 dot-matrix indicator with 20 state-specific blink patterns.
+platforms: ["react"]
+---
+
+import { PreviewCode } from "@/components/docs/preview-code.server";
+import {
+  DotMatrixSample,
+  DotMatrixLifecycleSample,
+  DotMatrixInlineSample,
+  DotMatrixSizesSample,
+} from "@/components/docs/samples/dot-matrix";
+
+<Callout>
+  This is a **standalone component** that does not depend on the assistant-ui runtime. Use it anywhere in your application.
+</Callout>
+
+<DotMatrixSample />
+
+## Installation
+
+<InstallCommand shadcn={["dot-matrix"]} />
+
+This adds a `/components/assistant-ui/dot-matrix.tsx` file to your project, which you can adjust as needed. The component has no dependencies beyond React.
+
+## Usage
+
+```tsx
+import { DotMatrix } from "@/components/assistant-ui/dot-matrix";
+
+export function RunIndicator({ isRunning }: { isRunning: boolean }) {
+  return <DotMatrix state={isRunning ? "loading" : "success"} />;
+}
+```
+
+Dots inherit the surrounding text color, so the matrix renders dark dots on light backgrounds and light dots on dark backgrounds without configuration. Every state is a combination of a dot pattern, a motion, and a color, and switching states cross-fades each dot into its new pattern.
+
+## States
+
+| State | Pattern |
+|-------|---------|
+| `idle` | Dim static grid |
+| `loading` | Randomized twinkle (default) |
+| `thinking` | Diagonal wave |
+| `streaming` | Falling rain, per-column streaks |
+| `searching` | Horizontal sweep |
+| `syncing` | Rotating sweep around the center |
+| `connecting` | Ripple expanding from the center |
+| `waiting` | Ellipsis dots blinking in sequence |
+| `uploading` | Wave rising upward |
+| `downloading` | Wave falling downward |
+| `listening` | Slow equalizer columns |
+| `speaking` | Fast equalizer columns |
+| `recording` | Red center dot breathing |
+| `success` | Green check glyph, static |
+| `error` | Red cross glyph, blinking |
+| `warning` | Amber exclamation glyph, slow blink |
+| `info` | Blue info glyph, static |
+| `paused` | Pause bars glyph, static |
+| `stopped` | Square glyph, static |
+| `offline` | Very dim static grid |
+
+The component exports `dotMatrixStates` (the ordered list above) and the `DotMatrixState` union type, so UIs can enumerate or map states without duplicating the list. New states are added by extending the `STATES` record in the component source with a glyph and a per-dot blink function.
+
+## Examples
+
+### State Lifecycle
+
+Drive the `state` prop from your run status; the matrix morphs between patterns instead of swapping components.
+
+<PreviewCode file="components/docs/samples/dot-matrix" name="DotMatrixLifecycleSample">
+  <DotMatrixLifecycleSample />
+</PreviewCode>
+
+### Inline With Text
+
+At the default `size-4` the matrix aligns with text like an icon, and the dots adapt to inverted surfaces through `currentColor`.
+
+<PreviewCode file="components/docs/samples/dot-matrix" name="DotMatrixInlineSample">
+  <DotMatrixInlineSample />
+</PreviewCode>
+
+### Sizes
+
+The matrix is an SVG, so any size utility scales it crisply.
+
+<DotMatrixSizesSample />
+
+## How It Works
+
+The grid is a 5x5 SVG of `currentColor` circles. Blinking is a single CSS keyframe animation whose high/low opacity bounds come from registered per-dot CSS variables; the animation runs in every state (static states collapse the bounds) and the bounds carry a transition, which is what makes state changes cross-fade per dot. The randomized loading rhythm uses deterministic per-dot delays and durations, so server and client render identical markup and no JavaScript runs after render. With `prefers-reduced-motion`, the dots hold their resting opacity instead of blinking.
+
+The root is a `role="status"` live region whose text content is the state name (or the `label` prop), so screen readers announce state changes; the SVG itself is `aria-hidden`.
+
+## API Reference
+
+### DotMatrix
+
+<ParametersTable
+  type="DotMatrixProps"
+  parameters={[
+    {
+      name: "state",
+      type: "DotMatrixState",
+      default: '"loading"',
+      description:
+        "One of the 20 built-in states listed above, controlling pattern, motion, and color.",
+    },
+    {
+      name: "label",
+      type: "string",
+      description:
+        "Accessible label announced by screen readers. Defaults to the state name.",
+    },
+    {
+      name: "className",
+      type: "string",
+      description:
+        "Additional CSS classes. Use size utilities to scale and text color utilities to recolor.",
+    },
+  ]}
+/>
+
+### Styling
+
+Color follows `currentColor`, so `className="text-blue-500"` recolors the whole matrix; the outcome states (`success`, `error`, `warning`, `info`, `recording`, and the muted static states) set their own color which a `className` can override. Dots are targetable via `[data-slot="dot-matrix"]` and `[data-slot="dot-matrix-dot"]`, and the current state is exposed as `data-state` on the root.
+
+## Related Components
+
+- [Number Roll](/docs/ui/number-roll) - Animated rolling number
+- [Badge](/docs/ui/badge) - Small status and metadata labels
+- [Voice](/docs/ui/voice) - Voice activity visualization

package/.docs/raw/docs/ui/mermaid.mdx

@@ -50,34 +50,41 @@ export const MarkdownText = memo(MarkdownTextImpl);
 
 ## Configuration
 
-Configure mermaid options in `mermaid-diagram.tsx`:
+Configure rendering options in `mermaid-diagram.tsx`:
 
 ```tsx title="/components/assistant-ui/mermaid-diagram.tsx"
-mermaid.initialize({ theme: "default" });
+renderMermaidSVG(code, {
+  bg: "var(--background)",
+  fg: "var(--foreground)",
+  muted: "var(--muted-foreground)",
+  border: "var(--border)",
+  accent: "var(--foreground)",
+  transparent: true,
+});
 ```
 
+The palette follows your theme's background, foreground, and shadcn color tokens, so diagrams match light and dark mode automatically.
+
 ## Streaming Performance
 
 The `MermaidDiagram` component is optimized for streaming scenarios:
 
-- **Smart completion detection**: Only renders when the specific code block is complete
-- **Zero failed renders**: Avoids parsing incomplete diagram code during streaming  
+- **Skeleton while streaming**: Shows a placeholder skeleton until the response finishes streaming, then renders the diagram synchronously
+- **Raw source fallback**: Invalid or unsupported diagrams fall back to displaying the raw source
 
 
 ## Supported Diagram Types
 
-Mermaid supports various diagram types including:
+The component renders these diagram types:
 
 - Flowcharts and decision trees
 - Sequence diagrams
-- Gantt charts
 - Class diagrams
 - State diagrams
-- Git graphs
-- User journey maps
 - Entity relationship diagrams
+- XY charts (bar, line, combined)
 
-See the [Mermaid documentation](https://mermaid.js.org/) for complete syntax reference.
+Other mermaid diagram types fall back to displaying the raw source. See the [Mermaid documentation](https://mermaid.js.org/) for syntax reference.
 
 ## Related Components