@assistant-ui/mcp-docs-server 0.1.29 → 0.1.31

package/.docs/raw/docs/(reference)/api-reference/hooks/utilities.mdx

@@ -0,0 +1,30 @@
+---
+title: Utility Hooks
+description: Focused helpers for message parts, quotes, timing, and viewport behavior.
+---
+
+Utility hooks expose commonly needed slices of assistant-ui behavior without requiring a full primitive.
+
+## Message Helpers
+
+- `useMessageQuote` reads the quote state for the current message.
+- `useMessageTiming` reads timing metadata for the current message.
+
+## Message Part Helpers
+
+- `useMessagePartText`
+- `useMessagePartReasoning`
+- `useMessagePartSource`
+- `useMessagePartFile`
+- `useMessagePartImage`
+- `useMessagePartData`
+
+These hooks are intended for custom message part renderers. They read the nearest message part context established by `MessagePrimitive.Parts`, `MessagePartPrimitive`, or the lower-level providers.
+
+## Viewport Helpers
+
+- `useThreadViewport` reads and controls the thread viewport.
+- `useThreadViewportAutoScroll` wires auto-scroll behavior for custom viewport compositions.
+- `useScrollLock` helps reasoning and grouped-part UIs preserve scroll behavior while content changes.
+
+For primitive-specific prop APIs, see [Primitives](/docs/api-reference/primitives).

package/.docs/raw/docs/(reference)/api-reference/integrations/index.mdx

@@ -0,0 +1,23 @@
+---
+title: Overview
+description: Package-level API reference for assistant-ui React integrations.
+---
+
+{/* AUTO-GENERATED by scripts/generate-api-reference-overviews.mts */}
+{/* Do not edit manually. */}
+
+Integration packages adapt assistant-ui to framework libraries and adjacent React ecosystems. Use these pages when you need package-specific hook names, options, and helper exports.
+
+## Pages
+
+<Cards>
+  <Card title={"@assistant-ui/react-ai-sdk"} href={"/docs/api-reference/integrations/vercel-ai-sdk"}>
+    {"Vercel AI SDK integration with chat runtime hooks and transport utilities."}
+  </Card>
+  <Card title={"@assistant-ui/react-data-stream"} href={"/docs/api-reference/integrations/react-data-stream"}>
+    {"Hooks for connecting to data stream protocol endpoints and Assistant Cloud."}
+  </Card>
+  <Card title={"@assistant-ui/react-hook-form"} href={"/docs/api-reference/integrations/react-hook-form"}>
+    {"React Hook Form integration for AI-assisted form filling."}
+  </Card>
+</Cards>

package/.docs/raw/docs/(reference)/api-reference/overview.mdx

@@ -16,6 +16,27 @@ export const contextColors = {
   "ThreadListItem Context": "#c678dd",
 };
 
+## Start Here
+
+The React API reference is organized by how you build with assistant-ui:
+
+<Cards>
+  <Card title="Primitives" href="/docs/api-reference/primitives">
+    Composable React components such as `ThreadPrimitive`, `MessagePrimitive`, and `ComposerPrimitive`. These pages are generated from the package source where possible.
+  </Card>
+  <Card title="Hooks" href="/docs/api-reference/hooks">
+    Reactive state hooks, runtime hooks, model context hooks, and utility hooks.
+  </Card>
+  <Card title="Adapters" href="/docs/api-reference/adapters">
+    Runtime extension points for attachments, persistence, feedback, speech, dictation, and suggestions.
+  </Card>
+  <Card title="Runtime State" href="/docs/api-reference/runtimes/assistant-runtime">
+    Runtime action and state shapes used by `useAui` and `useAuiState`.
+  </Card>
+</Cards>
+
+The lower sections on this page show how the contexts nest and where each primitive, hook, and runtime object is available.
+
 ## Cloud
 
 - [`AssistantCloud`](#assistant-cloud)

package/.docs/raw/docs/(reference)/api-reference/primitives/assistant-if.mdx

@@ -111,6 +111,13 @@ The condition function receives an `AssistantState` object with the following pr
   <Disclaimer />
 </AuiIf>
 
+// Render content only after the assistant finishes streaming
+<AuiIf condition={(s) =>
+  s.message.role === "assistant" && s.message.status?.type === "complete"
+}>
+  <FollowUpCard />
+</AuiIf>
+
 // Toggle copy icon based on copied state
 <ActionBarPrimitive.Copy>
   <AuiIf condition={(s) => !s.message.isCopied}>

package/.docs/raw/docs/(reference)/api-reference/primitives/composer.mdx

@@ -416,76 +416,124 @@ import { AuiIf } from "@assistant-ui/react";
 </AuiIf>
 ```
 
-## Mention Primitives (Unstable)
+## Trigger Popover Primitives (Unstable)
 
 <Callout type="warn">
   These primitives are under the `Unstable_` prefix and may change without notice.
 </Callout>
 
-Primitives for an @-mention picker in the composer. See the [Mention component guide](/docs/ui/mention) for a pre-built implementation.
+Unified primitives for any character-triggered popover (`@` mentions, `/` slash commands, `:` emoji, etc.). Multiple triggers coexist under a single `TriggerPopoverRoot`. See the [Mentions guide](/docs/guides/mentions) and [Slash Commands guide](/docs/guides/slash-commands) for full documentation and the [ComposerTriggerPopover component](/docs/ui/composer-trigger-popover) for a pre-built implementation.
 
 ### Anatomy
 
 ```tsx
 import { ComposerPrimitive } from "@assistant-ui/react";
+import { unstable_defaultDirectiveFormatter } from "@assistant-ui/core";
 
 const Composer = () => (
-  <ComposerPrimitive.Unstable_MentionRoot adapter={mentionAdapter}>
+  <ComposerPrimitive.Unstable_TriggerPopoverRoot>
     <ComposerPrimitive.Root>
       <ComposerPrimitive.Input />
-      <ComposerPrimitive.Unstable_MentionPopover>
-        <ComposerPrimitive.Unstable_MentionCategories>
+
+      <ComposerPrimitive.Unstable_TriggerPopover
+        char="@"
+        adapter={mention.adapter}
+      >
+        <ComposerPrimitive.Unstable_TriggerPopover.Directive
+          {...mention.directive}
+        />
+        <ComposerPrimitive.Unstable_TriggerPopoverCategories>
           {(categories) =>
             categories.map((cat) => (
-              <ComposerPrimitive.Unstable_MentionCategoryItem
+              <ComposerPrimitive.Unstable_TriggerPopoverCategoryItem
                 key={cat.id}
                 categoryId={cat.id}
               >
                 {cat.label}
-              </ComposerPrimitive.Unstable_MentionCategoryItem>
+              </ComposerPrimitive.Unstable_TriggerPopoverCategoryItem>
             ))
           }
-        </ComposerPrimitive.Unstable_MentionCategories>
-        <ComposerPrimitive.Unstable_MentionItems>
+        </ComposerPrimitive.Unstable_TriggerPopoverCategories>
+        <ComposerPrimitive.Unstable_TriggerPopoverItems>
           {(items) =>
             items.map((item) => (
-              <ComposerPrimitive.Unstable_MentionItem
+              <ComposerPrimitive.Unstable_TriggerPopoverItem
                 key={item.id}
                 item={item}
               >
                 {item.label}
-              </ComposerPrimitive.Unstable_MentionItem>
+              </ComposerPrimitive.Unstable_TriggerPopoverItem>
             ))
           }
-        </ComposerPrimitive.Unstable_MentionItems>
-        <ComposerPrimitive.Unstable_MentionBack>
+        </ComposerPrimitive.Unstable_TriggerPopoverItems>
+        <ComposerPrimitive.Unstable_TriggerPopoverBack>
           Back
-        </ComposerPrimitive.Unstable_MentionBack>
-      </ComposerPrimitive.Unstable_MentionPopover>
+        </ComposerPrimitive.Unstable_TriggerPopoverBack>
+      </ComposerPrimitive.Unstable_TriggerPopover>
     </ComposerPrimitive.Root>
-  </ComposerPrimitive.Unstable_MentionRoot>
+  </ComposerPrimitive.Unstable_TriggerPopoverRoot>
 );
 ```
 
-### Unstable_MentionRoot
+### Unstable_TriggerPopoverRoot
+
+Root provider that groups one or more `TriggerPopover` declarations. Owns the shared `ComposerInputPluginRegistry` that routes cursor and keyboard events to each registered trigger.
+
+No props.
+
+### Unstable_TriggerPopover
+
+Declares a trigger and renders its popover container. Only renders its DOM (and children) while this trigger is active in the composer input. Each declaration has an isolated scope — sub-primitives placed inside read state from this declaration only.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `char` | `string` | — | Character(s) that activate the trigger (e.g. `"@"`, `"/"`) — unique within the root |
+| `adapter` | `Unstable_TriggerAdapter` | — | Provides categories, items, and search |
+
+Selection behavior is declared by rendering **exactly one** behavior sub-primitive inside the `TriggerPopover`:
+
+- [`Unstable_TriggerPopover.Directive`](#unstable_triggerpopoverdirective) — inserts `:type[label]{name=id}` into the composer on selection (mention behavior).
+- [`Unstable_TriggerPopover.Action`](#unstable_triggerpopoveraction) — fires `onExecute` on selection; leaves a directive chip as an audit trail by default.
+
+Renders a `<div>` with `role="listbox"` when open.
+
+### Unstable_TriggerPopover.Directive
+
+Behavior sub-primitive. Placed inside a `<Unstable_TriggerPopover>`. Renders nothing — registers an `"directive"` behavior with its parent. Exactly one behavior sub-primitive is allowed per `TriggerPopover`.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `formatter` | `Unstable_DirectiveFormatter` | `unstable_defaultDirectiveFormatter` | Serializes the selected item into composer text (and parses it back). |
+| `onInserted` | `(item) => void` | — | Fires after the directive text has been inserted. |
+
+### Unstable_TriggerPopover.Action
 
-Provider that wraps the composer with mention trigger detection, keyboard navigation, and popover state.
+Behavior sub-primitive. Placed inside a `<Unstable_TriggerPopover>`. Renders nothing — registers an `"action"` behavior with its parent. Exactly one behavior sub-primitive is allowed per `TriggerPopover`.
 
 | Prop | Type | Default | Description |
 | --- | --- | --- | --- |
-| `adapter` | `Unstable_MentionAdapter` | — | Provides categories, items, and search |
-| `trigger` | `string` | `"@"` | Character(s) that activate the popover |
-| `formatter` | `Unstable_DirectiveFormatter` | Default | Serializer/parser for mention directives |
+| `formatter` | `Unstable_DirectiveFormatter` | `unstable_defaultDirectiveFormatter` | Serializes the audit-trail chip (unused when `removeOnExecute` is true). |
+| `onExecute` | `(item) => void` | — | Called the moment an item is selected — typically routes to a handler map. Required. |
+| `removeOnExecute` | `boolean` | `false` | When `true`, strips the trigger text from the composer instead of leaving a chip. |
 
-### Unstable_MentionPopover
+### Unstable_TriggerBehavior
 
-Container that only renders when a mention trigger is active. Renders a `<div>` with `role="listbox"`.
+Union type returned by the two behavior sub-primitives and consumed internally by the popover resources. Exported for advanced use cases (e.g. custom sub-primitives).
 
-### Unstable_MentionCategories
+```ts
+import type { Unstable_TriggerBehavior } from "@assistant-ui/react";
+
+// Equivalent shape:
+// Unstable_TriggerBehavior =
+//   | { kind: "directive"; formatter: Unstable_DirectiveFormatter; onInserted?: (item) => void }
+//   | { kind: "action"; formatter: Unstable_DirectiveFormatter; onExecute: (item) => void; removeOnExecute?: boolean }
+```
+
+### Unstable_TriggerPopoverCategories
 
 Renders the top-level category list. Accepts a render function `(categories) => ReactNode`. Hidden when a category is selected or when in search mode.
 
-### Unstable_MentionCategoryItem
+### Unstable_TriggerPopoverCategoryItem
 
 A button that drills into a category. Renders `role="option"` with automatic `data-highlighted` and `aria-selected` when keyboard-navigated.
 
@@ -493,25 +541,26 @@ A button that drills into a category. Renders `role="option"` with automatic `da
 | --- | --- | --- |
 | `categoryId` | `string` | The category to select on click |
 
-### Unstable_MentionItems
+### Unstable_TriggerPopoverItems
 
 Renders the item list for the active category or search results. Accepts a render function `(items) => ReactNode`. Hidden when no category is selected and not in search mode.
 
-### Unstable_MentionItem
+### Unstable_TriggerPopoverItem
 
-A button that inserts a mention into the composer. Renders `role="option"` with automatic `data-highlighted` and `aria-selected` when keyboard-navigated.
+A button that selects an item. Renders `role="option"` with automatic `data-highlighted` and `aria-selected` when keyboard-navigated.
 
 | Prop | Type | Description |
 | --- | --- | --- |
-| `item` | `Unstable_MentionItem` | The item to insert on click |
+| `item` | `Unstable_TriggerItem` | The item to select on click |
+| `index` | `number` | Optional index override for highlight matching |
 
-### Unstable_MentionBack
+### Unstable_TriggerPopoverBack
 
 A button that navigates back from items to the category list. Only renders when a category is active.
 
-### unstable_useMentionContext
+### unstable_useTriggerPopoverScopeContext
 
-Hook to access the mention popover state and actions from within `Unstable_MentionRoot`.
+Hook to access the popover state and actions for the nearest enclosing `Unstable_TriggerPopover`.
 
 ```tsx
 const {
@@ -527,19 +576,79 @@ const {
   goBack,
   close,
   handleKeyDown,
-  formatter,
-} = unstable_useMentionContext();
+} = unstable_useTriggerPopoverScopeContext();
 ```
 
-### unstable_useToolMentionAdapter
+### unstable_useTriggerPopoverTriggers
+
+Hook to iterate every trigger registered under the current `Unstable_TriggerPopoverRoot`. Intended for input-level integrations (e.g. Lexical `DirectivePlugin`). Returns `ReadonlyMap<string, Unstable_RegisteredTrigger>`.
+
+### unstable_useMentionAdapter
 
-Hook that creates a `Unstable_MentionAdapter` from registered tools (via `useAssistantTool`).
+Returns a spreadable `{ adapter, directive }` bundle for `@` mentions. Reads tools registered via `useAssistantTool`, accepts explicit `items`, and supports multi-category drill-down.
 
 ```tsx
-import { unstable_useToolMentionAdapter } from "@assistant-ui/react";
+import {
+  unstable_useMentionAdapter,
+  type Unstable_Mention,
+} from "@assistant-ui/react";
+
+function MyComposer() {
+  // Default: tools from model context as a single "Tools" category
+  const mention = unstable_useMentionAdapter();
+
+  return (
+    <ComposerTriggerPopover char="@" {...mention} />
+  );
+}
+```
 
-const adapter = unstable_useToolMentionAdapter({
-  formatLabel: (name) => name.replaceAll("_", " "),
-  categoryLabel: "Tools",
+```tsx
+// Multi-category + tools appended as their own category
+const mention = unstable_useMentionAdapter({
+  categories: [
+    { id: "users", label: "Users", items: [/* ... */] },
+    { id: "files", label: "Files", items: [/* ... */] },
+  ],
+  includeModelContextTools: true,
 });
 ```
+
+Options:
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `items` | `Unstable_Mention[]` | Flat list; ignored when `categories` is set. |
+| `categories` | `{ id, label, items: Unstable_Mention[] }[]` | Drill-down groups. |
+| `includeModelContextTools` | `boolean \| { category?, formatLabel?, icon? }` | Tools integration. Defaults to `true` iff neither `items` nor `categories`. |
+| `formatter` | `Unstable_DirectiveFormatter` | Override directive serialization. |
+| `onInserted` | `(item) => void` | Fires after the directive is inserted. |
+| `iconMap` | `Record<string, Unstable_IconComponent>` | `metadata.icon` / category id → React component. |
+| `fallbackIcon` | `Unstable_IconComponent` | Fallback when no `iconMap` entry matches. |
+
+Returns `{ adapter, directive, iconMap?, fallbackIcon? }`.
+
+### unstable_useSlashCommandAdapter
+
+Returns a spreadable `{ adapter, action }` bundle for slash commands. Commands are declared as data + inline `execute` callbacks; `execute` lives in the hook closure and is never attached to the returned `Unstable_TriggerItem`, keeping items JSON-serializable.
+
+```tsx
+import {
+  unstable_useSlashCommandAdapter,
+  type Unstable_SlashCommand,
+} from "@assistant-ui/react";
+
+const SLASH_COMMANDS: readonly Unstable_SlashCommand[] = [
+  { id: "summarize", execute: () => runSummarize(), icon: "FileText" },
+  { id: "translate", execute: () => runTranslate(), icon: "Languages" },
+];
+
+function MyComposer() {
+  const slash = unstable_useSlashCommandAdapter({ commands: SLASH_COMMANDS });
+  return (
+    <ComposerTriggerPopover char="/" {...slash} />
+  );
+}
+```
+
+Pass `removeOnExecute: true` on the hook options to strip the trigger text from the composer after executing. The hook also accepts `iconMap` / `fallbackIcon` options that flow into the returned bundle — `{...slash}` spreads them into `ComposerTriggerPopover`.

package/.docs/raw/docs/(reference)/api-reference/primitives/index.mdx

@@ -0,0 +1,65 @@
+---
+title: Overview
+description: Generated API reference for assistant-ui React primitive namespaces and parts.
+---
+
+{/* AUTO-GENERATED by scripts/generate-api-reference-overviews.mts */}
+{/* Do not edit manually. */}
+
+Primitives are the composable React components exported from `@assistant-ui/react`. These pages focus on parts, props, rendered elements, and composition behavior.
+
+## Pages
+
+<Cards>
+  <Card title={"ActionBarPrimitive"} href={"/docs/api-reference/primitives/action-bar"}>
+    {"Buttons for message actions like copy, edit, reload, speak, and feedback."}
+  </Card>
+  <Card title={"ActionBarMorePrimitive"} href={"/docs/api-reference/primitives/action-bar-more"}>
+    {"API reference for ActionBarMorePrimitive."}
+  </Card>
+  <Card title={"AuiIf"} href={"/docs/api-reference/primitives/assistant-if"}>
+    {"Conditional rendering component based on thread, message, or composer state."}
+  </Card>
+  <Card title={"AssistantModalPrimitive"} href={"/docs/api-reference/primitives/assistant-modal"}>
+    {"A popover chat interface for floating assistant UI in the corner of the screen."}
+  </Card>
+  <Card title={"AttachmentPrimitive"} href={"/docs/api-reference/primitives/attachment"}>
+    {"Components for displaying and managing file attachments in messages and composer."}
+  </Card>
+  <Card title={"BranchPickerPrimitive"} href={"/docs/api-reference/primitives/branch-picker"}>
+    {"Navigate between conversation branches with previous/next controls."}
+  </Card>
+  <Card title={"ComposerPrimitive"} href={"/docs/api-reference/primitives/composer"}>
+    {"Primitives for the text input, send button, and attachments."}
+  </Card>
+  <Card title={"ErrorPrimitive"} href={"/docs/api-reference/primitives/error"}>
+    {"Components for displaying error messages in the chat interface."}
+  </Card>
+  <Card title={"MessagePrimitive"} href={"/docs/api-reference/primitives/message"}>
+    {"Components for rendering message content, parts, and attachments."}
+  </Card>
+  <Card title={"MessagePartPrimitive"} href={"/docs/api-reference/primitives/message-part"}>
+    {"Primitives for text, images, tool calls, and other message content."}
+  </Card>
+  <Card title={"SelectionToolbarPrimitive"} href={"/docs/api-reference/primitives/selection-toolbar"}>
+    {"A floating toolbar that appears when text is selected within a message."}
+  </Card>
+  <Card title={"SuggestionPrimitive"} href={"/docs/api-reference/primitives/suggestion"}>
+    {"API reference for SuggestionPrimitive."}
+  </Card>
+  <Card title={"ThreadPrimitive"} href={"/docs/api-reference/primitives/thread"}>
+    {"Primitives for the message list, viewport, and welcome screen."}
+  </Card>
+  <Card title={"ThreadListPrimitive"} href={"/docs/api-reference/primitives/thread-list"}>
+    {"Display and manage multiple conversation threads with create and archive actions."}
+  </Card>
+  <Card title={"ThreadListItemPrimitive"} href={"/docs/api-reference/primitives/thread-list-item"}>
+    {"Individual thread item with title, archive, and delete controls."}
+  </Card>
+  <Card title={"ThreadListItemMorePrimitive"} href={"/docs/api-reference/primitives/thread-list-item-more"}>
+    {"Dropdown menu for additional thread actions like archive and delete."}
+  </Card>
+  <Card title={"Composition"} href={"/docs/api-reference/primitives/composition"}>
+    {"How to compose primitives with custom components using asChild."}
+  </Card>
+</Cards>

package/.docs/raw/docs/(reference)/api-reference/primitives/message-part.mdx

@@ -187,6 +187,8 @@ function MyComponent() {
 
 Each data component receives the full data part as props: `{ type: "data", name: string, data: T, status: MessagePartStatus }`.
 
+For a catch-all renderer (e.g. LangSmith's [`LoadExternalComponent`](/docs/runtimes/langgraph#dynamic-loading-with-fallback) loaded at runtime), pass `Fallback` via the inline `data` config on `MessagePrimitive.Parts`, or use the LangGraph adapter's [`uiComponents.fallback`](/docs/runtimes/langgraph#dynamic-loading-with-fallback) option.
+
 ### Messages (Sub-Agent)
 
 Renders nested messages from a tool call part's `messages` field. This is used in multi-agent setups where a sub-agent's conversation is embedded inside a tool call.

package/.docs/raw/docs/(reference)/api-reference/primitives/message.mdx

@@ -3,6 +3,8 @@ title: MessagePrimitive
 description: Components for rendering message content, parts, and attachments.
 ---
 
+import { MessagePrimitive as MessagePrimitiveDocs } from "@/generated/primitiveDocs";
+
 A single message in a conversation. Messages may consist of multiple parts.
 
 
@@ -95,13 +97,13 @@ The content of the message. This renders a separate component for each message p
               name: "Reasoning",
               type: "ReasoningMessagePartComponent",
               description:
-                "The component to render for each reasoning message part. Cannot be used alongside ChainOfThought.",
+                "Deprecated components-map renderer for each reasoning message part. Prefer the children render function or MessagePrimitive.GroupedParts.",
             },
             {
               name: "tools",
               type: "object",
               description:
-                "Configuration for tool call rendering. Cannot be used alongside ChainOfThought.",
+                "Deprecated components-map configuration for tool call rendering. Prefer part.toolUI in the children render function or MessagePrimitive.GroupedParts.",
               children: [
                 {
                   parameters: [
@@ -155,7 +157,7 @@ The content of the message. This renders a separate component for each message p
               name: "ToolGroup",
               type: "ComponentType<PropsWithChildren<{ startIndex: number; endIndex: number }>>",
               description:
-                "Deprecated: This feature is still experimental and subject to change. Component for rendering grouped consecutive tool calls. When provided, consecutive tool-call message parts will be automatically grouped and wrapped with this component. Cannot be used alongside ChainOfThought.",
+                "Deprecated legacy wrapper for grouped consecutive tool calls. Prefer MessagePrimitive.GroupedParts with groupBy returning \"group-tool\".",
               children: [
                 {
                   type: "ToolGroupProps",
@@ -187,7 +189,7 @@ The content of the message. This renders a separate component for each message p
               name: "ReasoningGroup",
               type: "ReasoningGroupComponent",
               description:
-                "Component for rendering grouped consecutive reasoning parts. Cannot be used alongside ChainOfThought.",
+                "Deprecated legacy wrapper for grouped consecutive reasoning parts. Prefer MessagePrimitive.GroupedParts with groupBy returning \"group-reasoning\".",
               children: [
                 {
                   type: "ReasoningGroupProps",
@@ -219,7 +221,7 @@ The content of the message. This renders a separate component for each message p
               name: "ChainOfThought",
               type: "ComponentType",
               description:
-                "When set, groups all consecutive reasoning and tool-call parts into a single collapsible component. Mutually exclusive with Reasoning, tools, ToolGroup, and ReasoningGroup.",
+                "Deprecated legacy grouping path. Prefer MessagePrimitive.GroupedParts for grouped reasoning and tool calls.",
             },
             {
               name: "Empty",
@@ -400,9 +402,51 @@ type QuoteInfo = {
 See the [Quoting guide](/docs/guides/quoting) for a complete walkthrough.
 </Callout>
 
+### GroupedParts
+
+Renders adjacent message parts through a hierarchical grouping tree. Use this for grouped Chain of Thought, consecutive tool calls, or any other adjacent grouping where each part stays in chronological order.
+
+```tsx
+<MessagePrimitive.GroupedParts
+  groupBy={(part) => {
+    if (part.type === "reasoning")
+      return ["group-chainOfThought", "group-reasoning"];
+    if (part.type === "tool-call")
+      return ["group-chainOfThought", "group-tool"];
+    return null;
+  }}
+>
+  {({ part, children }) => {
+    switch (part.type) {
+      case "group-chainOfThought":
+        return <div>{children}</div>;
+      case "group-reasoning":
+        return <ReasoningRoot>{children}</ReasoningRoot>;
+      case "group-tool":
+        return <ToolGroupRoot>{children}</ToolGroupRoot>;
+      case "text":
+        return <MarkdownText />;
+      case "reasoning":
+        return <Reasoning {...part} />;
+      case "tool-call":
+        return part.toolUI ?? <ToolFallback {...part} />;
+      case "data":
+        return part.dataRendererUI;
+      default:
+        return null;
+    }
+  }}
+</MessagePrimitive.GroupedParts>
+```
+
+<ParametersTable
+  type="MessagePrimitiveGroupedPartsProps"
+  parameters={MessagePrimitiveDocs.GroupedParts.props}
+/>
+
 ### Unstable_PartsGrouped
 
-Renders the parts of a message grouped by a custom grouping function. Use this component when you need to visually group related message parts together — for example, grouping parts that share a common parent ID, or collecting consecutive tool calls under a single header.
+Renders the parts of a message grouped by a custom grouping function. Use this unstable API only when you need non-adjacent clustering, such as collecting parts that share a common parent ID across different positions. For adjacent grouping, prefer `MessagePrimitive.GroupedParts`.
 
 The `groupingFunction` prop controls how parts are grouped. It receives the full array of message parts and must return an array of group descriptors, each with a `groupKey` (or `undefined` for ungrouped parts) and an array of `indices` into the message parts array. The optional `components.Group` component is then rendered once per group and receives the `groupKey`, `indices`, and the rendered part children.
 

package/.docs/raw/docs/(reference)/api-reference/primitives/thread-list.mdx

@@ -124,3 +124,18 @@ Renders a single thread list item at the specified index.
     },
   ]}
 />
+
+### LoadMore
+
+A button that calls `aui.threads().loadMore()` to append the next page. See the [LoadMore primitive reference](/docs/primitives/thread-list#loadmore) for usage and [Threads concepts](/docs/runtimes/concepts/threads#paginating-the-thread-list) for the adapter contract.
+
+This primitive renders a `<button>` element unless `asChild` is set.
+
+<ParametersTable
+  type="ThreadListPrimitiveLoadMoreProps"
+  parameters={[
+    {
+      name: "asChild",
+    },
+  ]}
+/>

package/.docs/raw/docs/(reference)/api-reference/primitives/thread.mdx

@@ -67,6 +67,33 @@ This primitive renders a `<div>` element unless `asChild` is set.
       description:
         'Controls scroll anchoring behavior for new messages. "bottom" is the classic chat behavior where messages anchor at the bottom. "top" anchors new user messages at the top of the viewport for a focused reading experience.',
     },
+    {
+      name: "topAnchorMessageClamp",
+      type: '{ tallerThan?: string; visibleHeight?: string }',
+      default: '{ tallerThan: "10em", visibleHeight: "6em" }',
+      description:
+        'Clamps tall user messages so the assistant response stays in view when turnAnchor is "top". Messages up to `tallerThan` stay fully visible; taller messages show only `visibleHeight` of their bottom edge above the assistant response.',
+      children: [
+        {
+          type: '{ tallerThan?: string; visibleHeight?: string }',
+          parameters: [
+            {
+              name: "tallerThan",
+              type: "string",
+              default: '"10em"',
+              description: "Clamp messages taller than this CSS length.",
+            },
+            {
+              name: "visibleHeight",
+              type: "string",
+              default: '"6em"',
+              description:
+                "Visible portion of a clamped message's bottom edge.",
+            },
+          ],
+        },
+      ],
+    },
     {
       name: "scrollToBottomOnRunStart",
       type: "boolean",
@@ -90,9 +117,17 @@ This primitive renders a `<div>` element unless `asChild` is set.
   ]}
 />
 
+<Callout type="info">
+  `ThreadPrimitive.ViewportSlack` has been removed. When `turnAnchor="top"` is
+  set, `MessagePrimitive.Root` handles top-anchor registration automatically. If
+  you previously customized `fillClampThreshold` or `fillClampOffset` on
+  `ViewportSlack` or `MessagePrimitive.Root`, use `topAnchorMessageClamp`
+  instead.
+</Callout>
+
 ### ViewportFooter
 
-A footer container placed inside `ThreadPrimitive.Viewport` that measures its own height (including top margin) and reports it to the viewport context. The viewport uses this measurement in scroll calculations — for example, as the minimum height for `ViewportSlack` — so that the scroll-to-bottom behaviour accounts for any sticky footer overlapping the message list.
+A footer container placed inside `ThreadPrimitive.Viewport` that measures its own height (including top margin) and reports it to the viewport context. The viewport uses this measurement in scroll calculations so the scroll-to-bottom behaviour accounts for any sticky footer overlapping the message list.
 
 Multiple `ViewportFooter` components may be used; their heights are summed.