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

package/.docs/raw/docs/runtimes/concepts/threads.mdx

@@ -37,10 +37,11 @@ const cloud = new AssistantCloud({
 const runtime = useLocalRuntime(modelAdapter, { cloud });
 ```
 
-Framework adapters take `cloud` directly:
+Framework adapters take `cloud` directly. `AISDKThreads({ cloud })` is the store-entry list for `AuiConfig` hosts. It mounts only the visible thread, so a switch cancels an in-flight run and that exchange is not persisted.
 
 ```tsx
 const runtime = useChatRuntime({ cloud });
+const threads = AISDKThreads({ cloud });
 const runtime = useLangGraphRuntime({ cloud /* stream, load, ... */ });
 const runtime = useAdkRuntime({ cloud, stream });
 ```
@@ -130,44 +131,68 @@ export function MyProvider({ children }: { children: React.ReactNode }) {
 }
 ```
 
-### Persisting messages with `unstable_Provider`
+### Persisting messages
 
-`RemoteThreadListAdapter` only manages thread metadata. To persist messages within each thread, expose a thread-scoped history adapter via the optional `unstable_Provider`:
+`RemoteThreadListAdapter` only manages thread metadata. Per-thread history and attachments are a separate seam with two faces:
+
+- `unstable_useAdapters` is a hook. The `RemoteThreadList` store entry calls it inside the client tree, so any `createAssistantClient` host gets the same adapters as a React hook host. `useRemoteThreadListRuntime` also calls it when `unstable_Provider` is omitted.
+- `unstable_Provider` is a React component. `useRemoteThreadListRuntime` renders it when present. The store entry ignores it.
+
+On the store entry, wrap the thread factory with `withKey` so the thread remounts on a switch. History adapters load once per mount. An unkeyed factory keeps one instance, and the next thread's messages never appear.
+
+```tsx
+import { withKey } from "@assistant-ui/tap";
+import { RemoteThreadList } from "@assistant-ui/react";
+
+threads: RemoteThreadList({
+  adapter,
+  thread: (id) => withKey(id, MyThread({ threadId: id })),
+}),
+```
+
+Share one hook between both faces:
 
 ```tsx
 import {
   RuntimeAdapterProvider,
   useAui,
+  type RemoteThreadListAdapter,
   type ThreadHistoryAdapter,
 } from "@assistant-ui/react";
 import { useMemo } from "react";
 
+function useThreadListAdapters() {
+  const aui = useAui();
+  const history = useMemo<ThreadHistoryAdapter>(
+    () => ({
+      async load() {
+        const { remoteId } = aui.threadListItem.getState();
+        if (!remoteId) return { messages: [] };
+        const rows = await fetch(
+          `/api/threads/${remoteId}/messages`,
+        ).then((r) => r.json());
+        return { messages: rows.map(toThreadMessage) };
+      },
+      async append({ message, parentId }) {
+        const { remoteId } = await aui.threadListItem.initialize();
+        await fetch(`/api/threads/${remoteId}/messages`, {
+          method: "POST",
+          body: JSON.stringify({ message, parentId }),
+        });
+      },
+    }),
+    [aui],
+  );
+  return useMemo(() => ({ history }), [history]);
+}
+
 const adapterWithHistory: RemoteThreadListAdapter = {
   // ...metadata methods above...
+  unstable_useAdapters: useThreadListAdapters,
   unstable_Provider({ children }) {
-    const aui = useAui();
-    const history = useMemo<ThreadHistoryAdapter>(
-      () => ({
-        async load() {
-          const { remoteId } = aui.threadListItem.getState();
-          if (!remoteId) return { messages: [] };
-          const rows = await fetch(
-            `/api/threads/${remoteId}/messages`,
-          ).then((r) => r.json());
-          return { messages: rows.map(toThreadMessage) };
-        },
-        async append({ message, parentId }) {
-          const { remoteId } = await aui.threadListItem.initialize();
-          await fetch(`/api/threads/${remoteId}/messages`, {
-            method: "POST",
-            body: JSON.stringify({ message, parentId }),
-          });
-        },
-      }),
-      [aui],
-    );
+    const adapters = useThreadListAdapters();
     return (
-      <RuntimeAdapterProvider adapters={{ history }}>
+      <RuntimeAdapterProvider adapters={adapters}>
         {children}
       </RuntimeAdapterProvider>
     );
@@ -192,6 +217,15 @@ async append({ message, parentId }) {
 
 `initialize()` is safe to call multiple times. It always resolves to the same `remoteId` for the active thread.
 
+The same rule applies to a custom external store's dispatch. The runtime does not hold `onNew` or `onEdit` until the thread record exists (that would keep the user's message off screen for the whole roundtrip), so a handler that talks to a backend keyed by the remote identity must await `initialize()` itself:
+
+```ts
+onNew: async (message) => {
+  const { remoteId } = await aui.threadListItem.initialize();
+  await sendToBackend(remoteId, message);
+},
+```
+
 ### Reloading after async authentication
 
 If your adapter depends on a user that resolves asynchronously (oidc, `next-auth`, `better-auth`), the initial `list()` may run before the user is available. Call `aui.threads.reload()` after auth completes:
@@ -230,13 +264,13 @@ A thread that has not been sent yet is left alone because it holds no remote sta
 
 What happens to a run in progress depends on the path. The remount path drops the runtime that was rendering the run; whether the run itself stops is up to that hook's unmount cleanup, which core cannot enforce. On the in-place path the runtime that declared the capability decides, since core does not stop the run for it. Either way this belongs on an event rather than a short timer: drive it from a state change like the one above, or skip the call while `useAuiState((s) => s.thread.isRunning)` is true.
 
-How the refetch happens depends on the runtime, in one of three ways. When it declares the capability, the thread runtime is reused: composer drafts survive, existing messages stay rendered while the fresh state loads, and the returned promise settles with the refetch, rejecting if it fails. A remote thread list without the capability remounts the runtime hook instead, which re-runs `load()` at the cost of discarding unsent composer input, and resolves once the new runtime attaches. The single and in-memory thread lists hold no remote state and have no hook to remount, so there it resolves without doing anything.
+How the refetch happens depends on the runtime, in one of three ways. When it declares the capability, the thread runtime is reused: composer drafts survive, existing messages stay rendered while the fresh state loads, and the returned promise settles with the refetch, rejecting if it fails. A remote thread list without the capability remounts the runtime hook instead, which re-runs `load()` at the cost of discarding unsent composer input, and resolves once the new runtime attaches. The single and in-memory thread lists have no hook to remount: they take the in-place path when their tap `ExternalThread` was given `onRefetchThread`, and resolve without doing anything when it was not.
 
 `useAuiState((s) => s.thread.capabilities.refetchThread)` reports which of those you would get, in place or not. It is not a signal for whether to offer a refresh at all: it is false on the remount path, where the call still does the work, and false again where the call does nothing.
 
 Both the LangGraph and Google ADK adapters register the in-place refetch capability when their runtime hook receives a `load` function; without one they fall back to the remount path. Other remote adapters take the remount path unless they provide the capability themselves.
 
-For an external store runtime, declare it with `onRefetchThread`, which is unrelated to `onReload` (that one re-generates an assistant message):
+For an external store runtime, declare it with `onRefetchThread`, which is unrelated to `onReload` (that one re-generates an assistant message); the tap `ExternalThread` accepts the same prop:
 
 ```ts
 useExternalStoreRuntime({
@@ -367,7 +401,13 @@ A few invariants worth knowing when wiring a custom UI on top of `loadMore()`:
       name: "unstable_Provider",
       type: "RemoteThreadListProviderComponent",
       description:
-        "Optional wrapper rendered around each active thread. Inject thread-scoped adapters (history, attachments) here.",
+        "Optional React wrapper rendered around each active thread by useRemoteThreadListRuntime when present. Inject thread-scoped adapters here. Omit it to let that host use unstable_useAdapters.",
+    },
+    {
+      name: "unstable_useAdapters",
+      type: "() => RuntimeAdapters | null | undefined",
+      description:
+        "Optional hook called by the RemoteThreadList store entry, and by useRemoteThreadListRuntime when unstable_Provider is omitted. Per-thread history requires the thread factory to be keyed with withKey.",
     },
   ]}
 />

package/.docs/raw/docs/runtimes/custom/assistant-transport.mdx

@@ -308,7 +308,7 @@ aui-state:[{"type":"set","path":["status"],"value":"completed"}]
   prepareSendCommandsRequest?: (body: SendCommandsRequestBody) => Record<string, unknown> | Promise<Record<string, unknown>>,
   capabilities?: { edit?: boolean },
   adapters?: { attachments?: AttachmentAdapter; history?: ThreadHistoryAdapter },
-  onResponse?: (response: Response) => void,
+  onResponse?: (response: Response) => void | Promise<void>,
   onFinish?: () => void,
   onError?: (error: Error, params: { commands: AssistantTransportCommand[]; updateState: (updater: (state: T) => T) => void }) => void | Promise<void>,
   onCancel?: (params: { commands: AssistantTransportCommand[]; updateState: (updater: (state: T) => T) => void; error?: Error }) => void

package/.docs/raw/docs/runtimes/custom/external-store.mdx

@@ -421,13 +421,13 @@ useEffect(() => {
 }, [isRunning, queue]);
 ```
 
-Queue policy on cancel, edit, and reload is host-owned. Call `queue.notifyCancelled()` in your `onCancel` handler before aborting so the cancelled run's settle pauses draining instead of dispatching the next item (the next send or run start resumes it), or call `queue.clear()` to drop the pending items. Call `queue.clear()` in your `onEdit` and `onReload` handlers so stale items do not drain onto the new branch.
+With a `createMessageQueue` adapter, cancelling pauses the queue for you: the runtime tells the queue before your `onCancel` runs, so the cancelled run's settle keeps the pending items instead of dispatching the next one, and the next send resumes draining. Call `queue.clear()` in `onCancel` instead if you want a cancel to drop them. A hand-rolled adapter has no such channel, so it owns its cancel policy the same way it owns the rest. Edit and reload stay host-owned: call `queue.clear()` in your `onEdit` and `onReload` handlers so stale items do not drain onto the new branch.
 
 ```tsx
 const runtime = useExternalStoreRuntime({
   // ...
   onCancel: async () => {
-    queue.notifyCancelled(); // or queue.clear() to drop pending items
+    // the runtime already paused the queue; clear() here to drop the items
     await cancelRun();
   },
   onEdit: async (message) => {
@@ -447,6 +447,10 @@ const runtime = useExternalStoreRuntime({
 
 ## Integration examples
 
+<Callout type="info">
+**Real-world example:** the [Claude Managed Agents guide](/docs/runtimes/claude-managed-agents) maps Anthropic-hosted agent sessions onto this runtime, with Anthropic's official [quickstart](https://github.com/anthropics/claude-quickstarts/tree/main/managed-agents/assistant-ui) as the runnable reference.
+</Callout>
+
 ### Redux
 
 ```tsx title="app/chatSlice.ts"

package/.docs/raw/docs/runtimes/langchain.mdx

@@ -262,7 +262,7 @@ Follow the [Ink setup](/docs/ink).
 
 ### Forwarding per-run config
 
-When a message is sent, its `runConfig.custom` (for example a selected mode or model) is forwarded on the underlying `useStream().submit` call as `config.configurable`. Read it in the graph from `config["configurable"]`; on LangGraph v1 the same values are also reachable through the Runtime `context`, which `config.configurable` is aliased to. This lets per-run app config reach the graph without extra wiring.
+When a message is sent, its `runConfig.custom` (for example a selected mode or model) is forwarded on the underlying `useStream().submit` call as `config.configurable`. Automatic tool-result resumes and the interrupt helpers (`useLangChainRespond`, `useLangChainRespondAll`, and `useLangChainSubmit(null, { command })`) reuse that same recorded `configurable` unless the caller passes `config`. Raw `useLangChainSubmit` / `useLangChainSend` calls that start a new run do not inherit it. The recording is session-scoped and does not survive a reload. Read it in the graph from `config["configurable"]`; on LangGraph v1 the same values are also reachable through the Runtime `context`, which `config.configurable` is aliased to. This lets per-run app config reach the graph without extra wiring.
 
 ## Reading custom state keys
 

package/.docs/raw/docs/runtimes/langgraph/streaming.mdx

@@ -119,6 +119,10 @@ const runtime = useLangGraphRuntime({
 
 Render the pending messages with [`ComposerPrimitive.Queue`](/docs/api-reference/primitives/composer) and [`QueueItemPrimitive`](/docs/api-reference/primitives/queue-item).
 
+## Per-run config
+
+When a message is sent, its `runConfig` is forwarded to `stream` and, if you use `unstable_createLangGraphStream`, posted as the LangGraph SDK run `config`. Automatic frontend tool-result resumes and `useLangGraphSendCommand` reuse the `runConfig` of the run that produced the pending tool call or interrupt. An explicit `runConfig` on `useLangGraphSend` still wins. A thread refetch that still carries the interrupt keeps that owner. History loaded without local ownership stays unconfigured on resume; the recording is session-scoped and does not survive a reload.
+
 ## Next
 
 <Cards>

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,7 +81,7 @@ 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
@@ -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/defining-tools.mdx

@@ -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).