@assistant-ui/mcp-docs-server 0.2.1 → 0.2.3

package/.docs/raw/docs/runtimes/pick-a-runtime.mdx

@@ -6,6 +6,7 @@ description: Decision guide for choosing the right runtime, by framework or by f
 import { A2AIcon } from "@/components/icons/a2a";
 import { AdkIcon } from "@/components/icons/adk";
 import { AguiIcon } from "@/components/icons/agui";
+import { ClaudeIcon } from "@/components/icons/claude";
 import { CloudflareIcon } from "@/components/icons/cloudflare";
 import { LangChainIcon } from "@/components/icons/langchain";
 import { LangGraphIcon } from "@/components/icons/langgraph";
@@ -80,14 +81,14 @@ assistant-ui ships React adapter packages for these. Pick the matching card and
 
 ### Integration guides
 
-For frameworks without a dedicated adapter, these wiring guides route through one of the adapters above.
+For frameworks without a dedicated adapter, these wiring guides route through an existing runtime: an adapter above, or one of the core runtimes.
 
   <Cards>
     <Card
       icon={<CloudflareIcon width={20} height={20} />}
       title="Cloudflare Agents"
       description="Stateful agents on Durable Objects with WebSocket streaming. Wired through the Vercel AI SDK runtime."
-      href="/docs/integrations/frameworks/cloudflare-agents/overview"
+      href="/docs/integrations/frameworks/cloudflare-agents"
     />
     <Card
       icon={<MastraIcon width={20} height={20} />}
@@ -95,6 +96,12 @@ For frameworks without a dedicated adapter, these wiring guides route through on
       description="TypeScript agent framework. Wired through the Vercel AI SDK runtime."
       href="/docs/integrations/frameworks/mastra/overview"
     />
+    <Card
+      icon={<ClaudeIcon width={20} height={20} className="text-[#D97757]" />}
+      title="Claude Managed Agents"
+      description="Anthropic-hosted agent sessions. Wired through the external store runtime: event-log replay, approval gates, sessions as threads."
+      href="/docs/runtimes/claude-managed-agents"
+    />
   </Cards>
 
 </PlatformOnly>

package/.docs/raw/docs/tools/backend.mdx

@@ -10,10 +10,10 @@ For authoring tools, see [Defining Tools](/docs/tools/defining-tools). For MCP s
 
 ## The request body
 
-`@assistant-ui/react-ai-sdk` posts `{ messages, system, tools }` to your route. `tools` is the map of **frontend** tools the client serialized for this request (the model needs their schemas to call them, even though they run in the browser):
+`@assistant-ui/ai-sdk` posts `{ messages, system, tools }` to your route. `tools` is the map of **frontend** tools the client serialized for this request (the model needs their schemas to call them, even though they run in the browser):
 
 ```ts
-import type { FrontendTools } from "@assistant-ui/react-ai-sdk";
+import type { FrontendTools } from "@assistant-ui/ai-sdk";
 
 const {
   messages,
@@ -31,7 +31,7 @@ const {
 When you author tools in a [`"use generative"` file](/docs/tools/defining-tools#quick-start-use-generative), the same import resolves to the **server build** inside a route handler — schema plus any backend `execute`, with renderers stripped. Wrap it in an `AISDKToolkit` and call `.tools()` with the uploaded `tools`:
 
 ```ts title="app/api/chat/route.ts"
-import { AISDKToolkit } from "@assistant-ui/react-ai-sdk";
+import { AISDKToolkit } from "@assistant-ui/ai-sdk";
 import { streamText, convertToModelMessages, type UIMessage } from "ai";
 import { openai } from "@ai-sdk/openai";
 import toolkit from "../../toolkit";
@@ -70,7 +70,7 @@ serializes browser-executed tools into the request `tools`. Convert them to the
 AI SDK shape with `frontendTools` and spread your own server tools alongside:
 
 ```ts title="app/api/chat/route.ts"
-import { frontendTools } from "@assistant-ui/react-ai-sdk";
+import { frontendTools } from "@assistant-ui/ai-sdk";
 import { streamText, convertToModelMessages, tool, zodSchema } from "ai";
 import { openai } from "@ai-sdk/openai";
 import { z } from "zod";

package/.docs/raw/docs/tools/defining-tools.mdx

@@ -121,7 +121,7 @@ Import the toolkit in your runtime provider and pass it to `config` via `Tools`:
 "use client";
 
 import { AssistantRuntimeProvider, AuiConfig, Tools } from "@assistant-ui/react";
-import { useChatRuntime } from "@assistant-ui/react-ai-sdk";
+import { useChatRuntime } from "@assistant-ui/ai-sdk";
 import toolkit from "./toolkit";
 
 export function MyRuntimeProvider({ children }: { children: React.ReactNode }) {
@@ -148,7 +148,7 @@ export function MyRuntimeProvider({ children }: { children: React.ReactNode }) {
 The same import resolves to the **server build** inside a route handler. Wrap it in an `AISDKToolkit` so the model is configured with every tool's schema:
 
 ```ts title="app/api/chat/route.ts"
-import { AISDKToolkit } from "@assistant-ui/react-ai-sdk";
+import { AISDKToolkit } from "@assistant-ui/ai-sdk";
 import { streamText, convertToModelMessages } from "ai";
 import { openai } from "@ai-sdk/openai";
 import toolkit from "../../toolkit";
@@ -194,6 +194,25 @@ The compiler also enforces, at build time:
 - a **frontend** tool declares a `render` or `renderText`;
 - a **human** tool declares a `render`.
 
+### Running without your own backend
+
+The client build skips uploading frontend/human schemas because it assumes your backend imported the same file's server build and already knows them. When no server of yours does — for example, cloud-hosted runs — that assumption breaks and the model never learns about those tools. Compile with the `backendless` option so the client keeps every schema uploadable, including the `present`/`prompt_user` schema of a `JSONGenerativeUI` component library:
+
+```ts title="next.config.ts"
+export default withAui({ ...yourConfig, aui: { backendless: true } });
+```
+
+```ts title="vite.config.ts"
+plugins: [aui({ backendless: true })];
+```
+
+```js title="metro.config.js"
+module.exports = withAui({
+  ...getDefaultConfig(__dirname),
+  aui: { backendless: true },
+});
+```
+
 ## Tool kinds
 
 ### Backend tools

package/.docs/raw/docs/tools/generative-ui-primitive.mdx

@@ -0,0 +1,180 @@
+---
+title: Generative UI primitive
+description: Render agent-described React UI from a JSON spec with a consumer-provided component allowlist, using the MessagePrimitive.GenerativeUI primitive.
+platforms: ["react"]
+---
+
+<Callout type="info">
+This page is for a **backend that already emits `generative-ui` message parts**. If you are starting fresh and want the model to compose an interface, use the [`present` tool](/docs/tools/generative-ui) instead: it ships a component vocabulary, generates the model-facing schema for you, and renders inside the stock `Thread` without extra wiring. The two are not versions of one API and their specs are not interchangeable; see [Spec shape](#spec-shape).
+</Callout>
+
+`MessagePrimitive.GenerativeUI` renders UI described by the agent at runtime as a JSON spec. Instead of hard-coding a component per tool, the agent emits a `generative-ui` message part containing a tree of components by name. assistant-ui resolves each name against a **consumer-provided allowlist** and renders the result. The producer is your backend rather than a model tool call: you decide what goes into the part and prompt your agent to emit it.
+
+The allowlist controls **which** components the agent may render: any name not in it throws a typed `GenerativeUIRenderError` (no implicit fallback). It does not constrain the props passed to those components; see [Security](#security).
+
+<Callout type="warn">
+The default shadcn `Thread` does **not** render `generative-ui` parts. You must wire the primitive explicitly, see [Opt-in wiring](#opt-in-wiring).
+</Callout>
+
+## When not to use the primitive
+
+- **A vocabulary the model composes freely** → the [`present` tool](/docs/tools/generative-ui)
+- **User input and two-way interaction** → [Tool UI](/docs/tools/tool-ui) or [Interactables](/docs/tools/interactables)
+- **LangGraph `push_ui_message`** → [LangGraph data UI](/docs/runtimes/langgraph/generative-ui)
+- **Untrusted HTML or third-party widgets** → [MCP Apps](/docs/tools/mcp-apps) (sandboxed frames)
+
+## Quick start
+
+### 1. Define your component allowlist
+
+```tsx title="components/gui.tsx"
+const Card = ({ title, children }) => (
+  <div className="rounded-xl border bg-card p-4 shadow-sm">
+    <div className="text-base font-semibold">{title}</div>
+    <div className="mt-2">{children}</div>
+  </div>
+);
+
+const Button = ({ label }) => (
+  <button className="rounded-md bg-primary px-3 py-1.5 text-primary-foreground">
+    {label}
+  </button>
+);
+
+export const componentsAllowlist = { Card, Button };
+```
+
+### 2. Wire the primitive into your message renderer
+
+See [Opt-in wiring](#opt-in-wiring) for all three integration patterns.
+
+### 3. Have the agent emit UI
+
+**ExternalStore / manual messages** attach a native part:
+
+```ts
+{
+  type: "generative-ui",
+  spec: {
+    root: {
+      component: "Card",
+      props: { title: "Welcome" },
+      children: [
+        { component: "Button", props: { label: "Get started" } },
+      ],
+    },
+  },
+}
+```
+
+**AI SDK (`useChatRuntime`)** maps tool results to `tool-call` parts, not `generative-ui` parts. Use the [AI SDK interim bridge](#pattern-3--ai-sdk-interim-bridge).
+
+Live routes in [`examples/with-generative-ui`](https://github.com/assistant-ui/assistant-ui/tree/main/examples/with-generative-ui): static primitive (`/primitive`), GUI chat bridge (`/gui-chat`).
+
+## Opt-in wiring
+
+The stock `@assistant-ui/ui` `Thread` switch returns `null` for unknown part types, including `generative-ui`. Add one of these patterns in **your** assistant message renderer.
+
+### Pattern 1 — `MessagePrimitive.Parts`
+
+```tsx
+<MessagePrimitive.Parts
+  components={{
+    generativeUI: {
+      components: componentsAllowlist,
+      Fallback: UnknownComponentFallback,
+    },
+  }}
+/>
+```
+
+### Pattern 2 — `GroupedParts` case (shadcn Thread fork)
+
+```tsx
+case "generative-ui":
+  return (
+    <MessagePrimitive.GenerativeUI
+      components={componentsAllowlist}
+      Fallback={UnknownComponentFallback}
+    />
+  );
+```
+
+Also exclude `render_gui` from tool-group chrome in `groupBy` if you use the AI SDK bridge (return `null` for that tool name).
+
+### Pattern 3 — AI SDK interim bridge
+
+When using `useChatRuntime`, map a dedicated tool result to the renderer:
+
+```tsx
+case "tool-call":
+  if (part.toolName === "render_gui") {
+    const spec = parseRenderGuiResult(part.result);
+    if (spec) {
+      return (
+        <MessagePrimitive.GenerativeUI
+          spec={spec}
+          components={componentsAllowlist}
+          Fallback={UnknownComponentFallback}
+        />
+      );
+    }
+  }
+  return part.toolUI ?? <ToolFallback {...part} />;
+```
+
+The message store still holds a `tool-call` on this path, not a `generative-ui` part. See `examples/with-generative-ui/app/gui-chat` for a working reference.
+
+Bare strings act as inline text leaves.
+
+## Spec shape
+
+```ts
+type GenerativeUINode =
+  | string
+  | {
+      component: string;             // resolved against the allowlist
+      props?: Record<string, unknown>;
+      children?: GenerativeUINode[];
+      key?: string;                   // optional stable React key
+    };
+
+type GenerativeUISpec = {
+  root: GenerativeUINode | GenerativeUINode[];
+};
+```
+
+The spec is plain JSON, easy for any agent to emit and easy to validate on the server before delivery.
+
+This is a different shape from the flat `$type` tree the [`present` tool](/docs/tools/generative-ui) uses. The two are not interchangeable, and the Slack, Teams, and A2UI converters only accept the `$type` form.
+
+## Streaming
+
+When a message contains native `generative-ui` parts whose `spec` updates incrementally (for example via ExternalStore), the primitive renders progressively as nodes and props arrive.
+
+The AI SDK `render_gui` tool path returns the full spec at **tool completion**, not incrementally during the tool execute step. For args streaming during generation, use [Tool UI](/docs/tools/tool-ui) instead.
+
+## Security
+
+The allowlist is the boundary on **which** components render: a spec can only instantiate components you put in the registry, with no `eval` and no dynamic import (names are looked up in the registry and nothing else). An unknown name throws `GenerativeUIRenderError` or invokes your `Fallback`.
+
+It does **not** constrain the `props` the agent supplies. Spec props are spread directly onto your allowlisted components, so treat every allowlisted component as receiving untrusted input: never forward agent-supplied props into `dangerouslySetInnerHTML`, validate or reject `href` and `src` values (for example block `javascript:` URLs), and avoid passing spec props anywhere they become executable. The safest allowlisted components accept only primitive, display-oriented props.
+
+## Error handling
+
+Unknown component names throw `GenerativeUIRenderError` with a typed `componentName` field. Catch it with a React error boundary, or pass a `Fallback` component to opt into a soft-fail UX:
+
+```tsx
+<MessagePrimitive.GenerativeUI
+  components={componentsAllowlist}
+  Fallback={({ component }) => (
+    <span className="rounded bg-muted px-1.5 py-0.5 font-mono text-xs">
+      unknown component: {component}
+    </span>
+  )}
+/>
+```
+
+## Composing with other primitives
+
+`generative-ui` is a regular `MessagePart` type, so it composes cleanly with `MessagePrimitive.Parts`, `MessagePrimitive.PartByIndex`, and `MessagePrimitive.GroupedParts`. Render it alongside text, tool calls, and reasoning in the same message.

package/.docs/raw/docs/tools/generative-ui-slack.mdx

@@ -0,0 +1,167 @@
+---
+title: Generative UI on Slack
+description: Convert a generative UI tree into Slack Block Kit, post it, and decode the block_actions payload Slack sends back into your action handlers.
+platforms: ["react"]
+---
+
+The `$type` tree your assistant renders in the browser is plain JSON, so it does not have to stay in the browser. `@assistant-ui/react-generative-ui/slack` converts the same tree into [Block Kit](https://docs.slack.dev/reference/block-kit/blocks) JSON, decodes the interactions Slack posts back, and parses Block Kit payloads into the tree.
+
+The subpath is React-free, so a server action, queue worker, or webhook handler imports it without pulling React into the bundle.
+
+## Posting a tree
+
+```ts
+import { WebClient } from "@slack/web-api";
+import { toSlackBlocks } from "@assistant-ui/react-generative-ui/slack";
+
+const slack = new WebClient(process.env.SLACK_BOT_TOKEN);
+
+const { blocks, warnings } = toSlackBlocks({
+  $type: "Card",
+  title: "Order #48213",
+  children: [{ $type: "Text", value: "Shipped, arriving Thursday." }],
+});
+
+await slack.chat.postMessage({ channel: "#orders", blocks });
+```
+
+`toSlackBlocks(node, options?)` returns `{ blocks, warnings }` and never throws: an input it cannot convert at all comes back as empty `blocks` plus one warning rather than an exception. Pass `{ surface: "modal" }` to target a modal instead of a message; the surface changes the block budget and unlocks the native `alert` block.
+
+## Warnings
+
+Conversion is total. Every downgrade is reported rather than thrown, so one unsupported node never costs you the whole message:
+
+```ts
+type SlackConversionWarning = {
+  code: "clamped" | "dropped" | "fallback";
+  component: string; // the IR component name, or "Root" for whole-payload issues
+  detail: string;
+};
+```
+
+`clamped` means content was truncated to fit a Slack limit, `dropped` means a node or one of its props was discarded and may have left a placeholder note behind (an oversized button payload is dropped while the button itself is kept, a `Chart` becomes an omission note), and `fallback` means the node rendered through a different construct than requested. Warnings arrive in traversal order and are not deduplicated. Logging them in development is the fastest way to see why a composition looks different on Slack than in the browser.
+
+## Component mapping
+
+| Component | Slack output | Fidelity |
+|---|---|---|
+| `Header` | `header` block | Only `text` survives; `size` is dropped silently, since Slack's `header` block has no size |
+| `Text` | `section` block with `mrkdwn` text | Only `value` survives; `size`, `weight`, and `color` are dropped silently |
+| `Markdown` | `markdown` block | Downgrades to a `section` once the payload's markdown budget is spent |
+| `Caption`, `Badge` | `context` block with one element | The two become identical output and cannot be told apart coming back |
+| `Image` | `image` block | Only `src` and `alt` survive; `size` and `round` are dropped silently |
+| `Divider` | `divider` block | `flush` is dropped silently |
+| `Fact` | Merged into one `section`'s `fields`, as `*label*` then value | Consecutive facts merge; every 10 fields start a new section |
+| `Table` | `data_table` block, first row as header | Cells become `raw_number` or `raw_text`; rows are padded to a uniform width; a column without a string label keeps its position with an empty header and warns |
+| `Card` | Native `card` block, or a header plus inline blocks | See [Cards](#cards) |
+| `Carousel` | `carousel` block of `card` elements | A non-card child that would have rendered is dropped with a warning; a card that cannot map cleanly is reshaped to title and body, and separately reports the images, tables, charts, and controls that reshape loses |
+| `Alert` | Native `alert` block on a modal; a `context` plus `section` pair on a message | Slack supports `alert` [only in modals](https://docs.slack.dev/reference/block-kit/blocks/alert-block) |
+| `ListView` | One `section` per item, with `divider` blocks between them | Item children collapse into concatenated text; a non-item child that would have rendered is dropped with a warning |
+| `ListViewItem` | `section`, plus an "Open" button accessory when it carries an action | |
+| `Button` | `button` element inside an `actions` block | `primary` and `danger` styles survive; other styles are dropped |
+| `Select` | `static_select` element | An option without a string label and value is dropped with a warning |
+| `RadioGroup` | `radio_buttons` element | An option without a string label and value is dropped with a warning |
+| `Checkbox` | `checkboxes` element with a single option | |
+| `DatePicker` | `datepicker` element | `min` and `max` are dropped; a non-`YYYY-MM-DD` value is dropped with a warning |
+| `Input` | Its own `input` block | Not grouped into an `actions` block |
+| `Form` | Children inline, then a "Submit" button | Slack has no form container |
+| `Row` | One `context` block when every child is a `Badge` or `Caption`, otherwise flattened | Horizontal layout is lost in the flattened case |
+| `Col`, `Box` | Flattened into the sibling block stream | Slack has no nesting container |
+| `Chart` | Replaced by a note block | Always warns |
+| `Spacer`, `Icon` | Dropped | Silently, since neither has a Slack equivalent |
+
+An unknown component and a bare string child are both handled: the unknown one is dropped with a warning, and the string becomes a `section`.
+
+Presentation props the converter does not map are dropped silently, without a warning, because the node itself still renders. That covers `Box`'s `width`, `height`, `radius`, and `background`; `Card`'s `padding` and `background`; `gap` on `Row`, `Col`, and `Form`, `align` on `Row` and `Col`, and `justify` on `Row`; `Badge`'s `variant`; `Carousel`'s `label`; and `Button`'s `block`. `Card`'s `asForm` and `Button`'s `submit` are dropped for a different reason: Slack has no client-side form model to submit into, so a submit button and a click button both convert to the same `button` element carrying the node's `$action`, and a card marked `asForm` converts exactly like one that is not.
+
+### Cards
+
+`Card` takes the native `card` block only when its children fit that block's fixed fields, because Slack's `card` carries `hero_image`, `title`, `body`, `subtext`, and up to three action buttons rather than nesting arbitrary blocks. The converter fills those from the first `Image`, the first `Text` or `Markdown`, and the first `Caption`.
+
+Anything else in the card, including a second image, a `Fact`, or a loose `Button`, makes the card fall back to a header plus the children rendered inline plus an actions block, and reports a `fallback` warning. A card carrying none of an image, title, body, or actions is dropped outright.
+
+Inside a `Carousel` that fallback is unavailable, so an over-full card is reshaped to title and body text instead, with a `fallback` warning. Text carried in a `text`, `value`, `label`, `title`, or `description` prop survives the reshape at any depth, which covers a `Caption`'s text and a `Button`'s label. An image, a `Table`, a `Chart`, and any control do not, since none of them is text, and those are reported separately as `dropped` so the two facts stay distinguishable. A control here is a `Button`, `Select`, `DatePicker`, `Checkbox`, `RadioGroup`, `Input`, or `Form`, plus a `ListViewItem` or a nested `Card` footer that carries an action. An `$action` on a layout node such as `Box`, `Col`, or `Row` does not count, because those render no control on the clean path either.
+
+## Limits
+
+The converter clamps to Slack's published budgets rather than letting the API reject the payload. The ones you are most likely to hit:
+
+| Budget | Value | Behavior when exceeded |
+|---|---|---|
+| Blocks per message | 50 (100 in a modal) | Extra blocks are dropped and a note block reports the count |
+| Section text | 3,000 characters | Truncated |
+| Section fields | 10 per section, 2,000 characters each | Chunked into further sections; text truncated |
+| Actions elements | 25 per block | Chunked into further actions blocks |
+| Select options | 100 | Truncated |
+| Radio options | 10 | Truncated |
+| Button label | 75 characters | Truncated |
+| Button action payload | 2,000 characters | Dropped entirely, not truncated, so a partial payload never round-trips |
+| Card title | 150 characters, body and subtext 200 | Truncated |
+| Carousel cards | 10 | Truncated; a carousel with no renderable card is dropped |
+| Table | 200 data rows, 20 columns, 20,000 characters across all tables in one payload | Rows truncated; a table whose header alone busts the budget is dropped |
+| Markdown | 12,000 characters across the payload | Every markdown block from that point on becomes a `section` |
+
+Traversal itself is bounded too: 200 children per level, 5,000 nodes per call, and 32 levels of element nesting, each reported as a `Root` warning. These bounds exist because the tree arrives from a model.
+
+## Actions
+
+### Outbound
+
+A node's `$action` is split across two Block Kit fields. `$action.type` becomes the element's `action_id`, and the remaining keys are JSON-serialized into the element's `value`.
+
+```json
+{
+  "$type": "Button",
+  "label": "Approve",
+  "$action": { "type": "approve_order", "orderId": "48213" }
+}
+```
+
+becomes a button with `action_id: "approve_order"` and `value: "{\"orderId\":\"48213\"}"`.
+
+<Callout type="warn">
+Only buttons carry `value`. `Select`, `Input`, `DatePicker`, `Checkbox`, and `RadioGroup` emit `action_id` alone, so any extra keys on their `$action` are dropped. Keep those controls' actions to a bare `type`, or put the payload on a button that submits alongside them.
+</Callout>
+
+### Inbound
+
+Slack posts interactions to your request URL as a [`block_actions` payload](https://docs.slack.dev/reference/interaction-payloads/block_actions-payload). `decodeBlockAction` takes one entry from its `actions` array and rebuilds the action your tree dispatched, with the user's runtime selection under `$input`:
+
+```ts
+import { decodeBlockAction } from "@assistant-ui/react-generative-ui/slack";
+
+const action = decodeBlockAction(payload.actions[0]);
+// { type: "approve_order", orderId: "48213", $input: "…" }
+```
+
+It returns `undefined` for anything without a usable `action_id`, and never throws. `type` always comes from `action_id`, so a payload key named `type` cannot override it, and a `$input` key smuggled into the serialized payload is always stripped.
+
+What lands in `$input` depends on the element:
+
+| Element | `$input` |
+|---|---|
+| `static_select`, `radio_buttons` | The selected option's value, as a string |
+| `datepicker` | The selected date, as `YYYY-MM-DD` |
+| `checkboxes` | An array of selected values, empty when nothing is checked |
+| `plain_text_input` | The typed text |
+| `button` | The raw `value` string, when it is not a serialized object |
+
+### Reading a tree back
+
+`fromSlackBlocks` is the inverse direction, mapping a Block Kit payload into vocabulary nodes and returning `{ nodes, warnings }`. It accepts a bare array or a `{ blocks }` wrapper.
+
+The round trip is faithful on the plain building blocks (text, images, facts, controls, tables, simple cards) and documented-lossy elsewhere: context elements all return as `Caption`, so the `Badge` distinction is gone, button styles beyond `primary` and `danger` are dropped, an alert's title and description come back merged into the description, and card layouts flatten to the fields the `card` block carries. Card footers are re-derived from button style, with the primary-styled button becoming `confirm`; when style cannot decide it, position does, and that emits a `fallback` warning.
+
+## Before interactions work
+
+Converting and posting a tree needs only a bot token with `chat:write`. Making its buttons do anything additionally needs, on the Slack app side:
+
+- **Interactivity enabled with a request URL**, under Interactivity & Shortcuts. Slack posts every `block_actions` payload there.
+- **An acknowledgement within 3 seconds.** Return HTTP 200 first and do the work afterwards; the payload's `response_url` accepts up to five follow-up posts within 30 minutes if you need to update or replace the message.
+- **[Request signature verification](https://docs.slack.dev/authentication/verifying-requests-from-slack)** on that endpoint, using your signing secret.
+
+Receiving the webhook, verifying it, and routing the decoded action to your handler stay your application's responsibility. The converter only speaks JSON in and JSON out.
+
+## Reference
+
+The generated per-export reference, including every type in the subpath, is at [Slack Block Kit](/docs/api-reference/generative-ui/slack). For the Teams equivalent of this page, see [Generative UI on Microsoft Teams](/docs/tools/generative-ui-teams).

package/.docs/raw/docs/tools/generative-ui-teams.mdx

@@ -0,0 +1,160 @@
+---
+title: Generative UI on Microsoft Teams
+description: Convert a generative UI tree into an Adaptive Card, send it from a bot, and decode the Action.Submit payload Teams sends back into your action handlers.
+platforms: ["react"]
+---
+
+The `$type` tree your assistant renders in the browser is plain JSON, so it does not have to stay in the browser. `@assistant-ui/react-generative-ui/teams` converts the same tree into an [Adaptive Card](https://adaptivecards.io/explorer/) and decodes the submit payload a Teams bot receives back.
+
+The subpath is React-free, so a server action, queue worker, or bot handler imports it without pulling React into the bundle.
+
+## Sending a card
+
+```ts
+import { toAdaptiveCard } from "@assistant-ui/react-generative-ui/teams";
+
+const { card, warnings } = toAdaptiveCard({
+  $type: "Card",
+  title: "Order #48213",
+  children: [{ $type: "Text", value: "Shipped, arriving Thursday." }],
+});
+
+await context.sendActivity({
+  attachments: [
+    {
+      contentType: "application/vnd.microsoft.card.adaptive",
+      content: card,
+    },
+  ],
+});
+```
+
+`toAdaptiveCard(node)` returns `{ card, warnings }` and never throws; an input it cannot convert comes back as an empty card plus one warning. `toTeamsAttachments(node)` wraps the same conversion in the [attachment envelope](https://learn.microsoft.com/en-us/microsoftteams/platform/task-modules-and-cards/cards/cards-reference) for you, which is the form you want for a carousel.
+
+Cards are stamped at Adaptive Cards schema **1.5**, the version [Teams supports on desktop](https://learn.microsoft.com/en-us/microsoftteams/platform/task-modules-and-cards/cards/cards-reference). Teams mobile clients cap at 1.2, so a card using 1.5-only elements (notably `Table`) may not render there.
+
+## Warnings
+
+Conversion is total. Every downgrade is reported rather than thrown:
+
+```ts
+type TeamsConversionWarning = {
+  code: "clamped" | "dropped" | "fallback" | "advisory";
+  component: string; // the IR component name, or "Root" for whole-payload issues
+  detail: string;
+};
+```
+
+`clamped` means content was truncated or capped, `dropped` means a node or one of its props was discarded and may have left a placeholder note behind (a `Chart` becomes an omission note), `fallback` means the node rendered through a different construct than requested (buttons past the sixth moved to secondary mode, a renamed input id), and `advisory` means nothing was changed at all and the result may still render poorly or be refused (a `Row` beyond three columns, a card or carousel over the byte budget).
+
+## Component mapping
+
+| Component | Adaptive Card output | Fidelity |
+|---|---|---|
+| `Header` | `TextBlock` with heading style | `size` is ignored; the heading always emits `large` |
+| `Text` | `TextBlock` | Six text sizes collapse to five rendered sizes, four weights to bold or not, and the five subtle color tokens to `isSubtle` while `emphasis` is dropped |
+| `Markdown` | `TextBlock`, passed through verbatim | Teams renders [a markdown subset](https://learn.microsoft.com/en-us/microsoftteams/platform/task-modules-and-cards/cards/cards-format); headings, tables, images, and blockquotes render literally |
+| `Caption`, `Badge` | Small subtle `TextBlock` | The two become identical output |
+| `Image` | `Image` | A numeric `size` is dropped with a warning; `round` is dropped silently |
+| `Fact` | `FactSet` | Consecutive facts merge into one set |
+| `Table` | Native `Table` with the first row as headers | Requires schema 1.5, so it will not render on Teams mobile; a column without a string label keeps its position with an empty header and warns |
+| `Card` | `Container`, with the title as a leading heading | Footer buttons become an `ActionSet` beside the container, not inside it |
+| `Alert` | `Container` with a semantic style (`accent`, `good`, `warning`, `attention`) | Title and description become two text blocks |
+| `Carousel` | Multiple attachments through `toTeamsAttachments` | See [Carousels](#carousels); a non-card child that would have rendered is dropped with a warning |
+| `ListView` | One `Container` per item, separated after the first | A non-item child that would have rendered is dropped with a warning, and never reserves an input id |
+| `ListViewItem` | `Container`, with a select action when it carries an action | |
+| `Button` | `Action.Submit` inside an `ActionSet` | Consecutive buttons merge into one set; `buttonStyle` is dropped, since Teams [ignores action styling](https://learn.microsoft.com/en-us/microsoftteams/platform/task-modules-and-cards/cards/cards-reference) |
+| `Select` | `Input.ChoiceSet`, compact | An option without a string value is dropped with a warning |
+| `RadioGroup` | `Input.ChoiceSet`, expanded | An option without a string value is dropped with a warning |
+| `Checkbox` | `Input.Toggle` | Its value is the string `"true"` or `"false"` |
+| `Input` | `Input.Text` | |
+| `DatePicker` | `Input.Date` | `value`, `min`, and `max` are kept only in `YYYY-MM-DD` form, otherwise dropped silently |
+| `Form` | Children inline, then a "Submit" `ActionSet` | Adaptive Cards has no form container; inputs on the card submit together |
+| `Row` | `ColumnSet` with one auto-width column per child | Beyond three columns you get a warning, but all columns are kept |
+| `Col`, `Box` | `Container` | The two become indistinguishable |
+| `Divider` | Nothing; sets `separator` on the next sibling | See [Layout differences](#layout-differences) |
+| `Spacer` | Nothing; sets `spacing` on the next sibling | See [Layout differences](#layout-differences) |
+| `Chart` | Replaced by a subtle note | Always warns |
+| `Icon` | Dropped | Silently |
+
+`Text`'s size collapse is narrower than it looks: `sm`, `lg`, `xl`, `2xl`, and `3xl` map to `small`, `medium`, `large`, `extraLarge`, and `extraLarge`, while `md` emits no `size` at all and renders at the card's default. So six tokens reach five rendered sizes, and only `2xl` and `3xl` become indistinguishable. Color splits rather than collapses: `secondary`, `alpha-70`, `white`, `white-70`, and `white-50` all set `isSubtle: true`, while `emphasis` maps to nothing the converter emits and is dropped outright, so emphasized text renders identically to unstyled text.
+
+Presentation props the converter does not map are dropped silently, without a warning, because the node itself still renders. That covers `Box`'s `width`, `height`, `radius`, and `background`; `Card`'s `padding` and `background`; `gap` on `Row`, `Col`, and `Form`, `align` on `Row` and `Col`, and `justify` on `Row`; `Badge`'s `variant`; `Carousel`'s `label`; `Divider`'s `flush`; and `Button`'s `block`. `Card`'s `asForm` and `Button`'s `submit` are dropped for a different reason: every input on an Adaptive Card submits together, so a submit button and a click button both convert to the same `Action.Submit`, and a card marked `asForm` converts exactly like one that is not.
+
+## Layout differences
+
+Two vocabulary components behave differently here than anywhere else, because Adaptive Cards models separation as a property of an element rather than as an element:
+
+- A `Divider` emits nothing and sets `separator: true` on the next element that does emit.
+- A `Spacer` emits nothing and sets `spacing: "large"` on the next element that does emit.
+
+A component that emits nothing, such as an `Icon`, does not consume a pending mark; it carries through to the next real element. A `Divider` or `Spacer` with nothing after it disappears entirely, without a warning. The practical consequence is that a trailing separator you would see on Slack is simply absent on Teams.
+
+Two consolidations also apply, both run-based rather than global: consecutive `Fact` siblings merge into one `FactSet`, and consecutive `Button` siblings merge into one `ActionSet`. A different component between them breaks the run and starts a new set.
+
+## Inputs
+
+Adaptive Cards merges every input's current value into one submit object keyed by the input's `id`, which has two consequences worth knowing.
+
+**Ids come from `name`.** Each control's `id` is its `name` prop, falling back to a per-type default (`"select"`, `"radiogroup"`, `"input"`, `"datepicker"`). `Checkbox` is the exception: it falls back to its `label` first and only then to `"checkbox"`, so an unnamed checkbox keys the submit object by its visible label. Two controls that share a name on the same card would collide, so the converter renames the later one and warns. The key `aui` is reserved for the action envelope; a control named `aui` is renamed too.
+
+**There is no change event.** Adaptive Cards has no way to dispatch when a control's value changes, so a standalone control carrying `$action` gets a companion "Submit" `ActionSet` appended, plus a `fallback` warning. Five such controls produce five separate submit buttons. The idiomatic shape is to put `$action` on a `Form` or a `Card` footer and leave the controls actionless, which yields one submit for the whole card.
+
+## Actions
+
+### Outbound
+
+A node's `$action` is carried inside the submit payload's reserved `aui` key, so it never collides with input values:
+
+```json
+{
+  "type": "Action.Submit",
+  "title": "Approve",
+  "data": { "aui": { "type": "approve_order", "payload": { "orderId": "48213" } } }
+}
+```
+
+Unlike Slack, the payload is not serialized to a string and carries no size cap of its own, so the converter never drops or truncates it the way an oversized Slack button value is dropped. Size is checked once, against the whole card, and that check only warns; whether an oversized card is then accepted is Teams' call, not the converter's.
+
+### Inbound
+
+A bot receives the merged submit object as `activity.value`. `decodeSubmitData` splits it back into the action your tree dispatched, with the card's input values under `$input`:
+
+```ts
+import { decodeSubmitData } from "@assistant-ui/react-generative-ui/teams";
+
+const action = decodeSubmitData(context.activity.value);
+// { type: "approve_order", orderId: "48213", $input: { quantity: "2" } }
+```
+
+`$input` here is an **object keyed by input id**, which differs from Slack, where a single control's `$input` is a bare value. It is omitted when the card had no inputs. The function returns `undefined` for a payload without a well-formed `aui` envelope and never throws; `type` always comes from the envelope, and a `$input` key smuggled into the payload is stripped.
+
+The converter emits `Action.Submit`. Teams also offers [`Action.Execute`](https://learn.microsoft.com/en-us/adaptive-cards/authoring-cards/universal-action-model) from schema 1.4, which lets a bot return a replacement card in the invoke response; reaching for that means constructing the action yourself.
+
+## Carousels
+
+A carousel is an activity-level construct on Teams rather than a card-level one, so it only works through `toTeamsAttachments`:
+
+```ts
+const { attachments, attachmentLayout } = toTeamsAttachments(tree);
+
+await context.sendActivity({ attachments, attachmentLayout });
+```
+
+With a `Carousel` at the root you get one attachment per card child and `attachmentLayout: "carousel"`, capped at ten cards. Anywhere other than the root, a carousel falls back to its cards rendered in sequence, with a `fallback` warning. Input ids are scoped per card, so two attachments may safely reuse the same name.
+
+## Limits
+
+| Budget | Value | Behavior when exceeded |
+|---|---|---|
+| Carousel attachments | 10 | Truncated |
+| Table | 100 rows, 20 columns | Truncated |
+| Choice options | 100 | Truncated |
+| Primary actions | 6 | Later actions move to secondary mode; none are dropped |
+| Payload size | 80,000 serialized bytes, set below Teams' 100 KB bot message limit | Warned, never truncated, so you decide whether to split |
+
+Traversal is bounded as well: 200 children per level, 5,000 nodes per call, and 32 levels of element nesting, each reported as a `Root` warning. These bounds exist because the tree arrives from a model.
+
+## Reference
+
+The generated per-export reference, including every type in the subpath, is at [Microsoft Teams](/docs/api-reference/generative-ui/teams). For the Slack equivalent of this page, see [Generative UI on Slack](/docs/tools/generative-ui-slack).