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

package/.docs/raw/docs/ui/model-selector.mdx

@@ -1,12 +1,12 @@
 ---
-title: ModelSelector
-description: Model picker with unified overlay positioning and runtime integration.
+title: Model Selector
+description: Composable model picker with reasoning effort levels, search, and runtime integration.
 platforms: ["react"]
 ---
 
 import { ModelSelectorSample } from "@/components/docs/samples/model-selector";
 
-A select component that lets users switch between AI models. Uses item-aligned positioning so the selected model overlays the trigger for a unified look. Integrates with assistant-ui's `ModelContext` system to automatically propagate the selected model to your backend.
+A picker that lets users switch between AI models and choose a reasoning effort (thinking) level. It is built on Popover + Command, so search, provider grouping, and filtering compose in without being built in. The default export integrates with assistant-ui's `ModelContext` system, so the selection reaches your backend on every request with no extra wiring.
 
 <ModelSelectorSample />
 
@@ -24,9 +24,9 @@ A select component that lets users switch between AI models. Uses item-aligned p
 
 ### Use in your application
 
-Place the `ModelSelector` inside your thread component, typically in the composer area:
+Place the `ModelSelector` inside your thread component, typically in the composer area. Each model needs an `id` and a display `name`; everything else is optional:
 
-```tsx title="/components/assistant-ui/thread.tsx" {1,6-14}
+```tsx title="/components/assistant-ui/thread.tsx" {1,6-15}
 import { ModelSelector } from "@/components/assistant-ui/model-selector";
 
 const ComposerAction: FC = () => {
@@ -36,9 +36,10 @@ const ComposerAction: FC = () => {
         models={[
           { id: "gpt-5.4-nano", name: "GPT-5.4 Nano", description: "Fast and efficient" },
           { id: "gpt-5.4-mini", name: "GPT-5.4 Mini", description: "Balanced performance" },
-          { id: "gpt-5.5", name: "GPT-5.5", description: "Most capable" },
+          { id: "gpt-5.5", name: "GPT-5.5", description: "Most capable", efforts: true },
         ]}
         defaultValue="gpt-5.4-nano"
+        defaultEffort="medium"
         size="sm"
       />
     </div>
@@ -49,16 +50,22 @@ const ComposerAction: FC = () => {
   </Step>
   <Step>
 
-### Read the model in your API route
+### Read the selection in your API route
 
-The selected model's `id` is sent as `config.modelName` in the request body:
+The selected model's `id` arrives as `config.modelName`, and the effort level as `config.reasoningEffort`:
 
-```tsx title="app/api/chat/route.ts" {2,5}
+```tsx title="app/api/chat/route.ts" {2,5-11}
 export async function POST(req: Request) {
   const { messages, config } = await req.json();
 
   const result = streamText({
     model: openai(config?.modelName ?? "gpt-5.4-nano"),
+    providerOptions: {
+      openai:
+        config?.reasoningEffort !== undefined
+          ? { reasoningEffort: config.reasoningEffort }
+          : {},
+    },
     messages: await convertToModelMessages(messages),
   });
 
@@ -66,77 +73,126 @@ export async function POST(req: Request) {
 }
 ```
 
+`config.reasoningEffort` is only present when the selected model supports the chosen level, so the route only forwards it when it exists. See [How It Works](#how-it-works).
+
   </Step>
 </Steps>
 
-## Variants
+## Reasoning Efforts
 
-Use the `variant` prop to change the trigger's visual style.
+A model that declares `efforts` shows a "Thinking" row at the bottom of the popover. `efforts: true` enables the default Low / Medium / High levels; pass a list of `{ id, name }` objects to define your own:
 
 ```tsx
-<ModelSelector variant="outline" /> // Border (default)
-<ModelSelector variant="ghost" />   // No background
-<ModelSelector variant="muted" />   // Solid background
+{
+  id: "gpt-5.5",
+  name: "GPT-5.5",
+  efforts: [
+    { id: "minimal", name: "Minimal" },
+    { id: "high", name: "High" },
+  ],
+}
 ```
 
-| Variant   | Description                                    |
-| --------- | ---------------------------------------------- |
-| `outline` | Border with transparent background (default)   |
-| `ghost`   | No background, subtle hover                    |
-| `muted`   | Solid secondary background                     |
+Omit `efforts` for models without configurable reasoning. The row is hidden while such a model is selected.
 
-## Sizes
+### Sticky Selection
 
-Use the `size` prop to control the trigger dimensions.
+The effort selection survives model switches. Switching to a model that doesn't support the current level omits `reasoningEffort` from the request instead of resetting the user's choice, and the level applies again when the user switches back. The exported `resolveModelEffort` helper applies the same rule if you build your own runtime integration around `ModelSelector.Root`; see [`resolveModelEffort`](#resolvemodeleffort).
 
-```tsx
-<ModelSelector size="sm" />      // Compact (h-8, text-xs)
-<ModelSelector size="default" /> // Standard (h-9)
-<ModelSelector size="lg" />      // Large (h-10)
-```
-
-## Model Options
+### Custom Effort UI
 
-Each model in the `models` array supports:
+`ModelSelector.Effort` lays the levels out as horizontal segments, which overflows the popover width once a model has more than a few. For those cases, or for a different layout such as a slider or a sub-dropdown, build your own control with the `useModelSelectorEfforts` hook. It exposes the selected model's levels and the active selection:
 
 ```tsx
-const models = [
-  {
-    id: "gpt-5.4-nano",           // Sent to backend as config.modelName
-    name: "GPT-5.4 Nano",   // Display name in trigger and items
-    description: "Fast and efficient", // Optional subtitle in items only
-    icon: <SparklesIcon />,      // Optional icon (any ReactNode)
-  },
-];
+import { useModelSelectorEfforts } from "@/components/assistant-ui/model-selector";
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuRadioGroup,
+  DropdownMenuRadioItem,
+  DropdownMenuTrigger,
+} from "@/components/ui/dropdown-menu";
+
+function EffortDropdown() {
+  const { efforts, effort, setEffort } = useModelSelectorEfforts();
+  if (!efforts?.length) return null;
+
+  return (
+    <div className="flex items-center justify-between gap-3 border-t px-3 py-2">
+      <span className="text-muted-foreground text-xs">Thinking</span>
+      <DropdownMenu>
+        <DropdownMenuTrigger className="text-xs">
+          {efforts.find((e) => e.id === effort)?.name ?? "Select"}
+        </DropdownMenuTrigger>
+        <DropdownMenuContent align="end">
+          <DropdownMenuRadioGroup value={effort} onValueChange={setEffort}>
+            {efforts.map((option) => (
+              <DropdownMenuRadioItem key={option.id} value={option.id}>
+                {option.name}
+              </DropdownMenuRadioItem>
+            ))}
+          </DropdownMenuRadioGroup>
+        </DropdownMenuContent>
+      </DropdownMenu>
+    </div>
+  );
+}
 ```
 
-## Runtime Integration
+Render it inside `ModelSelector.Content` in place of `ModelSelector.Effort`. The same hook supports any shape that reads the levels and writes the selection.
 
-The default `ModelSelector` export automatically registers the selected model with assistant-ui's `ModelContext` system. When a user selects a model:
+## Search
 
-1. The component calls `aui.modelContext().register()` with `config.modelName`
-2. The `AssistantChatTransport` includes `config` in the request body
-3. Your API route reads `config.modelName` to determine which model to use
+Search is opt-in. Pass `searchable` to the default component:
 
-This works out of the box with `@assistant-ui/react-ai-sdk`.
+```tsx
+<ModelSelector models={models} searchable />
+```
 
-## API Reference
+Or compose `ModelSelector.Search` into a custom layout. Matching runs against each model's `id`, `name`, and `keywords`; add the provider name to `keywords` so typing "openai" finds its models.
 
-### Composable API
+## Composition
 
-For custom layouts, use the sub-components directly with `ModelSelector.Root`:
+All parts are exported individually. The default popover content is `List` + `Effort`; replace it to add search, provider groups, or anything else:
 
 ```tsx
 import {
   ModelSelectorRoot,
   ModelSelectorTrigger,
   ModelSelectorContent,
+  ModelSelectorSearch,
+  ModelSelectorList,
+  ModelSelectorEmpty,
+  ModelSelectorGroup,
   ModelSelectorItem,
+  ModelSelectorEffort,
 } from "@/components/assistant-ui/model-selector";
 
-<ModelSelectorRoot models={models} value={modelId} onValueChange={setModelId}>
+<ModelSelectorRoot
+  models={models}
+  value={modelId}
+  onValueChange={setModelId}
+  effort={effort}
+  onEffortChange={setEffort}
+>
   <ModelSelectorTrigger variant="outline" />
-  <ModelSelectorContent />
+  <ModelSelectorContent>
+    <ModelSelectorSearch placeholder="Search models..." />
+    <ModelSelectorList>
+      <ModelSelectorEmpty />
+      <ModelSelectorGroup heading="OpenAI">
+        {openaiModels.map((model) => (
+          <ModelSelectorItem key={model.id} model={model} />
+        ))}
+      </ModelSelectorGroup>
+      <ModelSelectorGroup heading="Anthropic">
+        {anthropicModels.map((model) => (
+          <ModelSelectorItem key={model.id} model={model} />
+        ))}
+      </ModelSelectorGroup>
+    </ModelSelectorList>
+    <ModelSelectorEffort label="Thinking" />
+  </ModelSelectorContent>
 </ModelSelectorRoot>
 ```
 
@@ -144,9 +200,64 @@ import {
 |-----------|-------------|
 | `ModelSelector` | Default export with runtime integration |
 | `ModelSelector.Root` | Presentational root (no runtime, controlled state) |
-| `ModelSelector.Trigger` | CVA-styled trigger showing current model |
-| `ModelSelector.Content` | Select content with model items |
-| `ModelSelector.Item` | Individual model option with icon, name, description |
+| `ModelSelector.Trigger` | CVA-styled trigger showing the current selection |
+| `ModelSelector.Value` | Selected model name, icon, and active effort |
+| `ModelSelector.Content` | Popover content wrapping a Command |
+| `ModelSelector.Search` | Search input that filters the list |
+| `ModelSelector.List` | List of model items (renders all models by default) |
+| `ModelSelector.Empty` | Empty state shown when search has no matches |
+| `ModelSelector.Group` | Labeled group of items (e.g. by provider) |
+| `ModelSelector.Separator` | Divider between groups or items |
+| `ModelSelector.Item` | Individual model option |
+| `ModelSelector.Effort` | Thinking level row for the selected model |
+
+`ModelSelector.List` is a Command list, so filtering and keyboard navigation work across groups automatically. Custom sorting is plain code: order the models before rendering items.
+
+<Callout type="warn">
+  `ModelSelector.Content` wraps a Command whose root keydown handler claims
+  <kbd>Enter</kbd> to select the highlighted model. Interactive elements
+  composed inside it (filter chips, custom effort controls) should stop
+  propagation for Enter in their own `onKeyDown` so the focused control
+  activates instead. `ModelSelector.Effort` already does this.
+</Callout>
+
+## Variants
+
+Use the `variant` prop to change the trigger's visual style.
+
+```tsx
+<ModelSelector variant="outline" /> // Border (default)
+<ModelSelector variant="ghost" />   // No background
+<ModelSelector variant="muted" />   // Solid background
+```
+
+| Variant   | Description                                    |
+| --------- | ---------------------------------------------- |
+| `outline` | Border with transparent background (default)   |
+| `ghost`   | No background, subtle hover                    |
+| `muted`   | Solid secondary background                     |
+
+## Sizes
+
+Use the `size` prop to control the trigger dimensions.
+
+```tsx
+<ModelSelector size="sm" />      // Compact (h-8, text-xs)
+<ModelSelector size="default" /> // Standard (h-9)
+<ModelSelector size="lg" />      // Large (h-10)
+```
+
+## How It Works
+
+The default `ModelSelector` export registers the selection with assistant-ui's `ModelContext` system:
+
+1. The component calls `aui.modelContext().register()` with `config.modelName`, plus `config.reasoningEffort` when the selected model supports the chosen level
+2. The `AssistantChatTransport` includes `config` in the request body of every chat request
+3. Your API route reads `config.modelName` and `config.reasoningEffort`
+
+This works out of the box with `@assistant-ui/react-ai-sdk`. `ModelSelector.Root` performs no registration; it is purely presentational, with controlled and uncontrolled props for the value, effort, and open state.
+
+## API Reference
 
 ### ModelSelector
 
@@ -162,7 +273,7 @@ import {
     {
       name: "defaultValue",
       type: "string",
-      description: "Initial model ID for uncontrolled usage.",
+      description: "Initial model ID for uncontrolled usage. Defaults to the first model, captured on first render; if models loads asynchronously, control the value instead.",
     },
     {
       name: "value",
@@ -174,6 +285,27 @@ import {
       type: "(value: string) => void",
       description: "Callback when selected model changes.",
     },
+    {
+      name: "defaultEffort",
+      type: "string",
+      description: "Initial effort level ID for uncontrolled usage.",
+    },
+    {
+      name: "effort",
+      type: "string",
+      description: "Controlled effort level ID.",
+    },
+    {
+      name: "onEffortChange",
+      type: "(effort: string) => void",
+      description: "Callback when effort level changes.",
+    },
+    {
+      name: "searchable",
+      type: "boolean",
+      default: "false",
+      description: "Render a search input above the model list.",
+    },
     {
       name: "variant",
       type: '"outline" | "ghost" | "muted"',
@@ -221,5 +353,40 @@ import {
       type: "React.ReactNode",
       description: "Optional icon displayed before the model name.",
     },
+    {
+      name: "disabled",
+      type: "boolean",
+      description: "Disable selection of this model.",
+    },
+    {
+      name: "keywords",
+      type: "string[]",
+      description: "Extra search terms matched by ModelSelector.Search (e.g. the provider name).",
+    },
+    {
+      name: "efforts",
+      type: "boolean | ModelSelectorEffortOption[]",
+      description: "Reasoning effort levels. true enables the default Low/Medium/High; pass a custom { id, name } list to override. Omit for models without configurable reasoning.",
+    },
   ]}
 />
+
+### `useModelSelectorEfforts`
+
+```tsx
+const { efforts, effort, setEffort } = useModelSelectorEfforts();
+```
+
+The selected model's effort levels and the active selection, for building a [custom effort UI](#custom-effort-ui) inside `ModelSelector.Content`. `efforts` is `undefined` for models without configurable reasoning.
+
+### `resolveModelEffort`
+
+```tsx
+resolveModelEffort(models, modelId, effort); // => string | undefined
+```
+
+Returns the effort ID when the given model supports it, otherwise `undefined`. This is the [sticky selection](#sticky-selection) rule the default component applies before registering the selection.
+
+## Related
+
+- [Model Context](/docs/copilots/model-context): How registered context (instructions, tools, config) reaches your backend

package/.docs/raw/docs/ui/number-roll.mdx

@@ -0,0 +1,154 @@
+---
+title: Number Roll
+description: Animated number that rolls digits odometer-style when the value changes.
+platforms: ["react"]
+---
+
+import { PreviewCode } from "@/components/docs/preview-code.server";
+import {
+  NumberRollSample,
+  NumberRollCompactSample,
+  NumberRollFormatSample,
+  NumberRollLiveSample,
+} from "@/components/docs/samples/number-roll";
+
+<Callout>
+  This is a **standalone component** that does not depend on the assistant-ui runtime. Use it anywhere in your application.
+</Callout>
+
+<NumberRollSample />
+
+## Installation
+
+<InstallCommand shadcn={["number-roll"]} />
+
+This adds a `/components/assistant-ui/number-roll.tsx` file to your project, which you can adjust as needed. The component has no dependencies beyond React.
+
+## Usage
+
+```tsx
+import { NumberRoll } from "@/components/assistant-ui/number-roll";
+
+export function TokenCounter({ count }: { count: number }) {
+  return <NumberRoll value={count} format={{ notation: "compact" }} />;
+}
+```
+
+When `value` changes, each digit rolls in place to its new value. Formatting is handled by `Intl.NumberFormat`, so structural changes animate too: when `700` becomes `1.1K` with compact notation, the surviving ones digit rolls from 0 to 1 while the leading `70` slides out and the decimal point, fraction digit, and `K` suffix slide in.
+
+## Examples
+
+### Compact Notation
+
+Pass any `Intl.NumberFormatOptions` via the `format` prop. Crossing a compact-notation threshold animates the formatting change instead of remounting the whole string.
+
+<PreviewCode file="components/docs/samples/number-roll" name="NumberRollCompactSample">
+  <NumberRollCompactSample />
+</PreviewCode>
+
+### Formats and Locales
+
+Currencies, percentages, suffixes, and non-English locales all work through the same `Intl.NumberFormat` pipeline. Compact thresholds and suffixes are locale-dependent (`1.2万` in `zh-CN`), so never hardcode them.
+
+<PreviewCode file="components/docs/samples/number-roll" name="NumberRollFormatSample">
+  <NumberRollFormatSample />
+</PreviewCode>
+
+### Live Counter
+
+Rapid successive updates retarget the in-flight roll smoothly, which makes the component suitable for streaming token counts and other live metrics.
+
+<PreviewCode file="components/docs/samples/number-roll" name="NumberRollLiveSample">
+  <NumberRollLiveSample />
+</PreviewCode>
+
+## How It Works
+
+The value is formatted with `Intl.NumberFormat.formatToParts` and split into keyed parts. Integer digits are keyed by place value counted from the right, so when `999` becomes `1,000` the existing columns keep their identity and roll in place while only the new leading digit and separator enter. Symbols (decimal point, group separators, currency signs, compact suffixes) cross-fade and collapse via animated `grid-template-columns`.
+
+Each digit renders a strip of 0 to 9 and animates a registered CSS custom property; CSS `mod()` math wraps the strip into an endless ribbon, so rolling from 9 to 0 continues in the trend direction instead of spinning backwards. There is no JavaScript animation loop and no animation library dependency.
+
+In browsers without CSS `mod()` support, and during server rendering, the component renders the plain formatted string. With `prefers-reduced-motion`, values swap instantly without rolling. When server rendering, pass an explicit `locales`: the server's default locale can differ from the visitor's browser locale, and a mismatched formatted string causes a React hydration error. Locales whose default numbering system is non-Latin (such as `ar-EG`) cross-fade their digits as symbols instead of rolling.
+
+The formatted value is exposed to screen readers as plain text while the animated digits are `aria-hidden`. Value changes are not announced automatically; wrap the component in an `aria-live` region if you need announcements.
+
+## API Reference
+
+### NumberRoll
+
+<ParametersTable
+  type="NumberRollProps"
+  parameters={[
+    {
+      name: "value",
+      type: "number",
+      required: true,
+      description: "The number to display.",
+    },
+    {
+      name: "format",
+      type: "Intl.NumberFormatOptions",
+      description:
+        "Number formatting options, e.g. `{ notation: \"compact\" }` or `{ style: \"currency\", currency: \"USD\" }`.",
+    },
+    {
+      name: "locales",
+      type: "Intl.LocalesArgument",
+      description:
+        "Locale(s) passed to `Intl.NumberFormat`. Pass an explicit value in server-rendered apps so the server and client format identically.",
+    },
+    {
+      name: "prefix",
+      type: "string",
+      description: "Static text rendered before the number.",
+    },
+    {
+      name: "suffix",
+      type: "string",
+      description: "Static text rendered after the number.",
+    },
+    {
+      name: "trend",
+      type: '"auto" | "up" | "down"',
+      default: '"auto"',
+      description:
+        "Roll direction. `auto` follows the sign of the value change; `up` and `down` force a direction, wrapping digits through 9/0 as needed.",
+    },
+    {
+      name: "duration",
+      type: "number",
+      default: "500",
+      description:
+        "Digit roll duration in milliseconds. Enter/exit fades run at 60% of this value.",
+    },
+    {
+      name: "className",
+      type: "string",
+      description: "Additional CSS classes.",
+    },
+  ]}
+/>
+
+### Styling
+
+The root applies `tabular-nums` so digits keep a constant width while rolling; the font you use must provide tabular figures for the layout to stay stable. Size and color are inherited from the surrounding text, so style it like any span:
+
+```tsx
+<NumberRoll value={value} className="text-4xl font-semibold" />
+```
+
+Change the animation speed via the `duration` prop; it drives both the CSS timing and the cleanup that unmounts exited characters, so overriding the duration variable in CSS alone would remove them mid-fade. The fade and easing variables are safe to override via the `style` prop (the defaults are set as inline styles, so plain `className` overrides do not apply):
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `--aui-number-roll-duration` | `500ms` (from the `duration` prop) | Digit roll duration. |
+| `--aui-number-roll-fade` | 60% of the duration | Enter/exit fade and width-collapse duration. |
+| `--aui-number-roll-ease` | `cubic-bezier(0.23, 1, 0.32, 1)` | Digit roll easing. |
+
+Parts are targetable via data attributes: `[data-slot="number-roll"]`, `[data-slot="number-roll-part"]`, `[data-slot="number-roll-digit"]`, and `[data-slot="number-roll-symbol"]`.
+
+## Related Components
+
+- [Context Display](/docs/ui/context-display) - Live token usage ring and bar
+- [Message Timing](/docs/ui/message-timing) - Streaming stats badge
+- [Badge](/docs/ui/badge) - Small status and metadata labels

package/.docs/raw/docs/ui/part-grouping.mdx

@@ -213,7 +213,7 @@ Tool UIs fall into three buckets: prompting the user (human-in-the-loop), inform
 Mark a tool with `display: "standalone"` to keep its UI out of the grouped trace. `human` tools and MCP apps are standalone automatically; every other tool defaults to `"inline"` and opts in explicitly:
 
 ```tsx
-const toolkit = {
+const toolkit = defineToolkit({
   ask_user: { type: "human", render: AskUI }, // standalone (forced)
   search_web: { type: "frontend", render: SearchUI }, // inline trace (default)
   checkout: {
@@ -221,7 +221,7 @@ const toolkit = {
     render: CheckoutUI,
     display: "standalone", // opt in
   },
-} satisfies Toolkit;
+});
 ```
 
 The synthetic `"standalone-tool-call"` key on `groupPartByType` matches all of these. `MessagePrimitive.GroupedParts` passes the live tool-UI registry to `groupBy` as a second `context` argument, and the helper reads it to resolve the registry-driven cases — MCP-app calls are detected from the part alone, so nothing is threaded in:

package/.docs/raw/docs/ui/reasoning.mdx

@@ -28,7 +28,7 @@ Previously, reasoning parts were rendered via `components.Reasoning` and grouped
 
 Render reasoning parts through `MessagePrimitive.GroupedParts`. Group consecutive reasoning parts with `"group-reasoning"`, then compose `ReasoningRoot`, `ReasoningTrigger`, `ReasoningContent`, and `ReasoningText` around the grouped children.
 
-While reasoning is streaming, `part.status.type === "running"`. Pass that to `defaultOpen` so the accordion auto-opens during streaming and lets the user collapse it once the model moves on.
+While reasoning is streaming, `part.status.type === "running"`. Pass that to `streaming` so the accordion auto-opens during streaming with a bottom-pinned live preview of the newest tokens, auto-collapses when the model moves on, and permanently defers to the first manual toggle. When `streaming` is provided it supersedes `defaultOpen`.
 
 ```tsx title="/app/components/assistant-ui/thread.tsx"
 import { MessagePrimitive, groupPartByType } from "@assistant-ui/react";
@@ -56,7 +56,7 @@ const AssistantMessage: FC = () => {
               case "group-reasoning": { // [!code ++]
                 const running = part.status.type === "running"; // [!code ++]
                 return ( // [!code ++]
-                  <ReasoningRoot defaultOpen={running}> // [!code ++]
+                  <ReasoningRoot streaming={running}> // [!code ++]
                     <ReasoningTrigger active={running} /> // [!code ++]
                     <ReasoningContent aria-busy={running}> // [!code ++]
                       <ReasoningText>{children}</ReasoningText> // [!code ++]
@@ -139,7 +139,7 @@ const ReasoningGroupImpl: ReasoningGroupComponent = ({
   });
 
   return (
-    <ReasoningRoot defaultOpen={isReasoningStreaming}>
+    <ReasoningRoot streaming={isReasoningStreaming}>
       <ReasoningTrigger active={isReasoningStreaming} />
       <ReasoningContent aria-busy={isReasoningStreaming}>
         <ReasoningText>{children}</ReasoningText>

package/.docs/raw/docs/ui/streamdown.mdx

@@ -119,6 +119,8 @@ const StreamdownText = () => (
 | `components` | `object` | - | Custom components including `SyntaxHighlighter` and `CodeHeader` |
 | `componentsByLanguage` | `object` | - | Language-specific component overrides |
 | `preprocess` | `(text: string) => string` | - | Text preprocessing function |
+| `defer` | `boolean` | `false` | Defer markdown parsing to a lower priority via `useDeferredValue` so typing and scrolling stay responsive during streaming |
+| `smooth` | `boolean \| SmoothOptions` | `false` | Typewriter-style reveal via `useSmooth`; the caret and controls stay active until the reveal catches up. Prefer the native `animated` prop for entrance animations |
 | `controls` | `boolean \| object` | `true` | Enable/disable UI controls for code blocks and tables |
 | `caret` | `"block" \| "circle"` | - | Streaming caret style |
 | `mermaid` | `MermaidOptions` | - | Mermaid diagram configuration |

package/.docs/raw/docs/ui/syntax-highlighting.mdx

@@ -29,7 +29,7 @@ import { SyntaxHighlightingSample } from "@/components/docs/samples/syntax-highl
 
 This adds a `/components/assistant-ui/shiki-highlighter.tsx` file to your project and
 installs the `react-shiki` dependency. The highlighter can be customized by editing
-the config in the `shiki-highlighter.tsx` file.
+the config in the `shiki-highlighter.tsx` file. While a message part is still streaming, the component renders the plain code without tokenization and highlights once the part settles, so streaming stays cheap.
 
   </Step>
   <Step>

package/.docs/raw/docs/ui/thread.mdx

@@ -133,6 +133,58 @@ const SuggestionItem = () => (
 );
 ```
 
+## Component Overrides
+
+`Thread` accepts an optional `components` prop that swaps parts of the rendering without editing the copied file. All slots are optional; omitted slots keep the built-in rendering.
+
+```tsx
+import { Thread, type ThreadComponents } from "@/components/assistant-ui/thread";
+
+const THREAD_COMPONENTS: ThreadComponents = {
+  ToolFallback: MyToolFallback,
+  ToolGroup: MyToolGroup,
+};
+
+export default function Chat() {
+  return <Thread components={THREAD_COMPONENTS} />;
+}
+```
+
+<ParametersTable
+  type="ThreadComponents"
+  parameters={[
+    {
+      name: "AssistantMessage",
+      type: "ComponentType",
+      description: "Replaces the entire assistant message, including the action bar and branch picker.",
+    },
+    {
+      name: "Welcome",
+      type: "ComponentType",
+      description: "Replaces the welcome screen shown for a new chat.",
+    },
+    {
+      name: "ToolFallback",
+      type: "ToolCallMessagePartComponent",
+      description: "Renders tool calls that have no tool UI registered by name. Registered tool UIs take precedence over this slot.",
+    },
+    {
+      name: "ToolGroup",
+      type: "ComponentType<PropsWithChildren<{ group: ThreadGroupPart }>>",
+      description: "Wraps runs of consecutive tool calls. Receives the group part (`indices`, `status`) and the rendered children.",
+    },
+    {
+      name: "ReasoningGroup",
+      type: "ComponentType<PropsWithChildren<{ group: ThreadGroupPart }>>",
+      description: "Wraps runs of consecutive reasoning parts. Receives the group part and the rendered children.",
+    },
+  ]}
+/>
+
+Define the `components` object once at module scope (or memoize it) so message subtrees do not re-render whenever the parent re-renders.
+
+For per-tool UI, prefer registering a renderer by tool name over overriding `ToolFallback`: put `render` on the matching toolkit entry (see [Tool UI](/docs/tools/tool-ui)). `data` message parts render through renderers registered with `useAssistantDataUI`; parts without a registered renderer are not displayed.
+
 ## API Reference
 
 The following primitives are used within the Thread component and can be customized in your `/components/assistant-ui/thread.tsx` file.