@assistant-ui/mcp-docs-server 0.1.32 → 0.1.34

package/.docs/organized/code-examples/with-generative-ui.md

@@ -8,16 +8,26 @@ import {
   streamText,
   convertToModelMessages,
   stepCountIs,
-  jsonSchema,
   tool,
   zodSchema,
 } from "ai";
 import type { UIMessage } from "ai";
 import { z } from "zod";
+import {
+  AISDKToolkit,
+  type AISDKToolkitToolsOptions,
+} from "@assistant-ui/react-ai-sdk";
+import {
+  renderGuiToolDescription,
+  renderGuiToolInputSchema,
+} from "../../../lib/render-gui-tool";
+import toolkit from "../../toolkit";
 
 export const maxDuration = 30;
 
-type ToolDef = { description?: string; parameters: Record<string, unknown> };
+const aiToolkit = new AISDKToolkit({ toolkit });
+
+type FrontendToolDefs = NonNullable<AISDKToolkitToolsOptions["frontend"]>;
 
 export async function POST(req: Request) {
   const {
@@ -27,21 +37,12 @@ export async function POST(req: Request) {
   }: {
     messages: UIMessage[];
     system?: string;
-    tools?: Record<string, ToolDef>;
+    tools?: FrontendToolDefs;
   } = await req.json();
 
-  // Convert client-defined frontend tools to AI SDK format
-  const frontendToolDefs = clientTools
-    ? Object.fromEntries(
-        Object.entries(clientTools).map(([name, def]) => [
-          name,
-          {
-            description: def.description ?? "",
-            inputSchema: jsonSchema(def.parameters),
-          },
-        ]),
-      )
-    : {};
+  const toolkitTools = await aiToolkit.tools({
+    ...(clientTools && { frontend: clientTools }),
+  });
 
   const result = streamText({
     model: openai("gpt-5.4-nano"),
@@ -49,7 +50,15 @@ export async function POST(req: Request) {
     stopWhen: stepCountIs(10),
     ...(system ? { system } : {}),
     tools: {
-      ...frontendToolDefs,
+      ...toolkitTools,
+
+      render_gui: tool({
+        description: renderGuiToolDescription,
+        inputSchema: zodSchema(renderGuiToolInputSchema),
+        execute: async (input) => ({
+          spec: input.spec,
+        }),
+      }),
 
       // Backend tool: generate chart data
       generate_chart: tool({
@@ -231,6 +240,65 @@ export async function POST(req: Request) {
 
 ```
 
+## app/gui-chat/page.tsx
+
+```tsx
+"use client";
+
+import { ExampleNav } from "@/components/example-nav";
+import { GuiThread } from "@/components/gui-thread";
+import {
+  AssistantRuntimeProvider,
+  Suggestions,
+  useAssistantInstructions,
+  useAui,
+} from "@assistant-ui/react";
+import { useChatRuntime } from "@assistant-ui/react-ai-sdk";
+import { lastAssistantMessageIsCompleteWithToolCalls } from "ai";
+import { renderGuiChatInstructions } from "@/lib/render-gui-tool";
+
+const GuiChatInstructions = () => {
+  useAssistantInstructions(renderGuiChatInstructions);
+  return null;
+};
+
+export default function GuiChatPage() {
+  const runtime = useChatRuntime({
+    sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithToolCalls,
+  });
+
+  const aui = useAui({
+    suggestions: Suggestions([
+      {
+        title: "Welcome card",
+        label: "with a Get started button",
+        prompt:
+          "Show me a welcome card with a Get started button using render_gui.",
+      },
+      {
+        title: "Stats dashboard",
+        label: "revenue and users",
+        prompt:
+          "Use render_gui to show a stats card with Revenue $124k and Active Users 8.2k.",
+      },
+    ]),
+  });
+
+  return (
+    <AssistantRuntimeProvider aui={aui} runtime={runtime}>
+      <GuiChatInstructions />
+      <div className="flex h-full flex-col">
+        <ExampleNav />
+        <main className="min-h-0 flex-1">
+          <GuiThread />
+        </main>
+      </div>
+    </AssistantRuntimeProvider>
+  );
+}
+
+```
+
 ## app/layout.tsx
 
 ```tsx
@@ -266,44 +334,13 @@ import { Thread } from "@/components/assistant-ui/thread";
 import {
   AssistantRuntimeProvider,
   Suggestions,
+  Tools,
   useAui,
-  useAssistantTool,
 } from "@assistant-ui/react";
 import { useChatRuntime } from "@assistant-ui/react-ai-sdk";
 import { lastAssistantMessageIsCompleteWithToolCalls } from "ai";
-import { z } from "zod";
-import { ChartToolUI } from "@/components/chart-tool-ui";
-import { DatePickerToolUI } from "@/components/date-picker-tool-ui";
-import { ContactFormToolUI } from "@/components/contact-form-tool-ui";
-import { LocationToolUI } from "@/components/location-tool-ui";
-
-// Register frontend tool schemas (no execute — resolved via addResult in the UI)
-function FrontendTools() {
-  useAssistantTool({
-    toolName: "select_date",
-    description:
-      "Ask the user to select a date. Use this when you need to collect a date (e.g. for scheduling, booking, deadlines).",
-    parameters: z.object({
-      prompt: z.string().describe("Message to display to the user"),
-      minDate: z.string().optional().describe("Minimum date (ISO string)"),
-      maxDate: z.string().optional().describe("Maximum date (ISO string)"),
-    }),
-  });
-
-  useAssistantTool({
-    toolName: "collect_contact",
-    description:
-      "Collect contact information from the user. Use this when you need the user's name, email, or phone number.",
-    parameters: z.object({
-      prompt: z.string().describe("Message to display to the user"),
-      fields: z
-        .array(z.enum(["name", "email", "phone"]))
-        .describe("Which fields to collect"),
-    }),
-  });
-
-  return null;
-}
+import { ExampleNav } from "@/components/example-nav";
+import toolkit from "./toolkit";
 
 export default function Home() {
   const runtime = useChatRuntime({
@@ -311,6 +348,7 @@ export default function Home() {
   });
 
   const aui = useAui({
+    tools: Tools({ toolkit }),
     suggestions: Suggestions([
       {
         title: "Show a bar chart",
@@ -339,16 +377,12 @@ export default function Home() {
 
   return (
     <AssistantRuntimeProvider aui={aui} runtime={runtime}>
-      {/* Frontend tools: register schemas, resolved via addResult in UI */}
-      <FrontendTools />
-      {/* Tool UIs: render components for each tool call */}
-      <ChartToolUI />
-      <LocationToolUI />
-      <DatePickerToolUI />
-      <ContactFormToolUI />
-      <main className="h-full">
-        <Thread />
-      </main>
+      <div className="flex h-full flex-col">
+        <ExampleNav />
+        <main className="min-h-0 flex-1">
+          <Thread />
+        </main>
+      </div>
     </AssistantRuntimeProvider>
   );
 }
@@ -361,13 +395,11 @@ export default function Home() {
 "use client";
 
 import { GenerativeUIRender, type GenerativeUISpec } from "@assistant-ui/react";
-import { componentsAllowlist } from "@/components/gui";
-
-const UnknownComponentFallback = ({ component }: { component: string }) => (
-  <span className="rounded bg-muted px-1.5 py-0.5 font-mono text-xs">
-    unknown component: {component}
-  </span>
-);
+import {
+  UnknownComponentFallback,
+  componentsAllowlist,
+} from "@/components/gui";
+import { ExampleNav } from "@/components/example-nav";
 
 /**
  * Self-contained demo of the GenerativeUI primitive.
@@ -433,28 +465,79 @@ const exampleSpec: GenerativeUISpec = {
 
 export default function GenerativeUIPrimitivePage() {
   return (
-    <main className="mx-auto flex h-full max-w-2xl flex-col gap-6 p-8">
-      <header>
-        <h1 className="font-bold text-2xl">MessagePrimitive.GenerativeUI</h1>
-        <p className="mt-1 text-muted-foreground text-sm">
-          Agent-described React UI rendered from a JSON spec via a
-          consumer-provided component allowlist.
-        </p>
-      </header>
-
-      <section className="flex flex-col gap-4">
-        <GenerativeUIRender
-          spec={exampleSpec}
-          components={componentsAllowlist}
-          Fallback={UnknownComponentFallback}
-        />
-      </section>
-    </main>
+    <div className="flex h-full flex-col">
+      <ExampleNav />
+      <main className="mx-auto flex h-full max-w-2xl flex-col gap-6 overflow-y-auto p-8">
+        <header>
+          <h1 className="text-2xl font-bold">MessagePrimitive.GenerativeUI</h1>
+          <p className="text-muted-foreground mt-1 text-sm">
+            Agent-described React UI rendered from a JSON spec via a
+            consumer-provided component allowlist.
+          </p>
+        </header>
+
+        <section className="flex flex-col gap-4">
+          <GenerativeUIRender
+            spec={exampleSpec}
+            components={componentsAllowlist}
+            Fallback={UnknownComponentFallback}
+          />
+        </section>
+      </main>
+    </div>
   );
 }
 
 ```
 
+## app/toolkit.tsx
+
+```tsx
+"use generative";
+
+import { defineToolkit, externalTool, humanTool } from "@assistant-ui/react";
+import { ChartToolUI } from "@/components/chart-tool-ui";
+import { DatePickerToolUI } from "@/components/date-picker-tool-ui";
+import { ContactFormToolUI } from "@/components/contact-form-tool-ui";
+import { LocationToolUI } from "@/components/location-tool-ui";
+import { z } from "zod";
+
+export default defineToolkit({
+  select_date: {
+    description:
+      "Ask the user to select a date. Use this when you need to collect a date (e.g. for scheduling, booking, deadlines).",
+    parameters: z.object({
+      prompt: z.string().describe("Message to display to the user"),
+      minDate: z.string().optional().describe("Minimum date (ISO string)"),
+      maxDate: z.string().optional().describe("Maximum date (ISO string)"),
+    }),
+    execute: humanTool(),
+    render: DatePickerToolUI,
+  },
+  collect_contact: {
+    description:
+      "Collect contact information from the user. Use this when you need the user's name, email, or phone number.",
+    parameters: z.object({
+      prompt: z.string().describe("Message to display to the user"),
+      fields: z
+        .array(z.enum(["name", "email", "phone"]))
+        .describe("Which fields to collect"),
+    }),
+    execute: humanTool(),
+    render: ContactFormToolUI,
+  },
+  generate_chart: {
+    execute: externalTool(),
+    render: ChartToolUI,
+  },
+  show_location: {
+    execute: externalTool(),
+    render: LocationToolUI,
+  },
+});
+
+```
+
 ## components.json
 
 ```json
@@ -485,12 +568,257 @@ export default function GenerativeUIPrimitivePage() {
 
 ```
 
+## components/assistant-message-gui.tsx
+
+```tsx
+"use client";
+
+import { MarkdownText } from "@/components/assistant-ui/markdown-text";
+import {
+  Reasoning,
+  ReasoningContent,
+  ReasoningRoot,
+  ReasoningText,
+  ReasoningTrigger,
+} from "@/components/assistant-ui/reasoning";
+import { ToolFallback } from "@/components/assistant-ui/tool-fallback";
+import {
+  ToolGroupContent,
+  ToolGroupRoot,
+  ToolGroupTrigger,
+} from "@/components/assistant-ui/tool-group";
+import { TooltipIconButton } from "@/components/assistant-ui/tooltip-icon-button";
+import {
+  UnknownComponentFallback,
+  componentsAllowlist,
+} from "@/components/gui";
+import {
+  RENDER_GUI_TOOL_NAME,
+  isLeakedRenderGuiText,
+  parseRenderGuiResult,
+} from "@/lib/render-gui-tool";
+import { cn } from "@/lib/utils";
+import type { GenerativeUISpec } from "@assistant-ui/react";
+import {
+  ActionBarPrimitive,
+  AuiIf,
+  BranchPickerPrimitive,
+  ErrorPrimitive,
+  getMcpAppFromToolPart,
+  MessagePrimitive,
+  useAuiState,
+} from "@assistant-ui/react";
+import {
+  CheckIcon,
+  ChevronLeftIcon,
+  ChevronRightIcon,
+  CopyIcon,
+  RefreshCwIcon,
+} from "lucide-react";
+import { type FC, useEffect, useRef } from "react";
+
+type AssistantMessageGuiProps = {
+  /** Set false in dev to surface the dropped-bridge warning. */
+  bridgeEnabled?: boolean;
+};
+
+const AllowlistedGenerativeUI = ({ spec }: { spec?: GenerativeUISpec }) => (
+  <MessagePrimitive.GenerativeUI
+    spec={spec}
+    components={componentsAllowlist}
+    Fallback={UnknownComponentFallback}
+  />
+);
+
+const useDroppedGenerativeUIWarning = (bridgeEnabled: boolean) => {
+  const content = useAuiState((s) => s.message.content);
+  const warned = useRef(false);
+
+  useEffect(() => {
+    if (
+      process.env.NODE_ENV === "production" ||
+      bridgeEnabled ||
+      warned.current
+    ) {
+      return;
+    }
+
+    const hasRenderGui = content.some(
+      (part) =>
+        part.type === "tool-call" &&
+        part.toolName === RENDER_GUI_TOOL_NAME &&
+        part.result != null &&
+        parseRenderGuiResult(part.result) != null,
+    );
+
+    const hasUnhandledGenerativeUI = content.some(
+      (part) => part.type === "generative-ui",
+    );
+
+    if (hasRenderGui || hasUnhandledGenerativeUI) {
+      warned.current = true;
+      console.warn(
+        "[generative-ui] Message contains render_gui or generative-ui parts but the bridge is disabled. " +
+          "Enable the bridge in assistant-message-gui.tsx or wire MessagePrimitive.GenerativeUI.",
+      );
+    }
+  }, [bridgeEnabled, content]);
+};
+
+export const AssistantMessageGui: FC<AssistantMessageGuiProps> = ({
+  bridgeEnabled = true,
+}) => {
+  useDroppedGenerativeUIWarning(bridgeEnabled);
+
+  const hasBridgedRenderGui = useAuiState((s) =>
+    s.message.content.some(
+      (part) =>
+        part.type === "tool-call" &&
+        part.toolName === RENDER_GUI_TOOL_NAME &&
+        parseRenderGuiResult(part.result) != null,
+    ),
+  );
+
+  const ACTION_BAR_PT = "pt-1.5";
+  const ACTION_BAR_HEIGHT = `-mb-7.5 min-h-7.5 ${ACTION_BAR_PT}`;
+
+  return (
+    <MessagePrimitive.Root
+      data-slot="aui_assistant-message-root"
+      data-role="assistant"
+      className="fade-in slide-in-from-bottom-1 animate-in relative duration-150"
+    >
+      <div
+        data-slot="aui_assistant-message-content"
+        // [contain-intrinsic-size:auto_24px] fixes issue #4104, don't change without checking for regressions
+        className="text-foreground px-2 leading-relaxed wrap-break-word [contain-intrinsic-size:auto_24px] [content-visibility:auto]"
+      >
+        <MessagePrimitive.GroupedParts
+          groupBy={(part) => {
+            if (part.type === "reasoning") {
+              return ["group-chainOfThought", "group-reasoning"];
+            }
+            if (part.type === "tool-call") {
+              if (getMcpAppFromToolPart(part)) return [];
+              if (part.toolName === RENDER_GUI_TOOL_NAME) return [];
+              return ["group-chainOfThought", "group-tool"];
+            }
+            return [];
+          }}
+        >
+          {({ part, children }) => {
+            switch (part.type) {
+              case "group-chainOfThought":
+                return <div data-slot="aui_chain-of-thought">{children}</div>;
+              case "group-reasoning": {
+                const running = part.status.type === "running";
+                return (
+                  <ReasoningRoot defaultOpen={running}>
+                    <ReasoningTrigger active={running} />
+                    <ReasoningContent aria-busy={running}>
+                      <ReasoningText>{children}</ReasoningText>
+                    </ReasoningContent>
+                  </ReasoningRoot>
+                );
+              }
+              case "group-tool":
+                return (
+                  <ToolGroupRoot>
+                    <ToolGroupTrigger
+                      count={part.indices.length}
+                      active={part.status.type === "running"}
+                    />
+                    <ToolGroupContent>{children}</ToolGroupContent>
+                  </ToolGroupRoot>
+                );
+              case "text":
+                if (
+                  bridgeEnabled &&
+                  hasBridgedRenderGui &&
+                  isLeakedRenderGuiText(part.text)
+                ) {
+                  return null;
+                }
+                return <MarkdownText />;
+              case "reasoning":
+                return <Reasoning {...part} />;
+              case "generative-ui":
+                return bridgeEnabled ? <AllowlistedGenerativeUI /> : null;
+              case "tool-call": {
+                if (bridgeEnabled && part.toolName === RENDER_GUI_TOOL_NAME) {
+                  const spec = parseRenderGuiResult(part.result);
+                  if (spec) return <AllowlistedGenerativeUI spec={spec} />;
+                }
+                return part.toolUI ?? <ToolFallback {...part} />;
+              }
+              default:
+                return null;
+            }
+          }}
+        </MessagePrimitive.GroupedParts>
+        <MessagePrimitive.Error>
+          <ErrorPrimitive.Root className="aui-message-error-root border-destructive bg-destructive/10 text-destructive dark:bg-destructive/5 mt-2 rounded-md border p-3 text-sm dark:text-red-200">
+            <ErrorPrimitive.Message className="aui-message-error-message line-clamp-2" />
+          </ErrorPrimitive.Root>
+        </MessagePrimitive.Error>
+      </div>
+
+      <div
+        data-slot="aui_assistant-message-footer"
+        className={cn("ms-2 flex items-center", ACTION_BAR_HEIGHT)}
+      >
+        <BranchPickerPrimitive.Root
+          hideWhenSingleBranch
+          className="aui-branch-picker-root text-muted-foreground -ms-2 me-2 inline-flex items-center text-xs"
+        >
+          <BranchPickerPrimitive.Previous asChild>
+            <TooltipIconButton tooltip="Previous">
+              <ChevronLeftIcon />
+            </TooltipIconButton>
+          </BranchPickerPrimitive.Previous>
+          <span className="aui-branch-picker-state font-medium">
+            <BranchPickerPrimitive.Number /> / <BranchPickerPrimitive.Count />
+          </span>
+          <BranchPickerPrimitive.Next asChild>
+            <TooltipIconButton tooltip="Next">
+              <ChevronRightIcon />
+            </TooltipIconButton>
+          </BranchPickerPrimitive.Next>
+        </BranchPickerPrimitive.Root>
+        <ActionBarPrimitive.Root
+          hideWhenRunning
+          autohide="not-last"
+          className="aui-assistant-action-bar-root text-muted-foreground -ms-1 flex gap-1"
+        >
+          <ActionBarPrimitive.Copy asChild>
+            <TooltipIconButton tooltip="Copy">
+              <AuiIf condition={(s) => s.message.isCopied}>
+                <CheckIcon />
+              </AuiIf>
+              <AuiIf condition={(s) => !s.message.isCopied}>
+                <CopyIcon />
+              </AuiIf>
+            </TooltipIconButton>
+          </ActionBarPrimitive.Copy>
+          <ActionBarPrimitive.Reload asChild>
+            <TooltipIconButton tooltip="Refresh">
+              <RefreshCwIcon />
+            </TooltipIconButton>
+          </ActionBarPrimitive.Reload>
+        </ActionBarPrimitive.Root>
+      </div>
+    </MessagePrimitive.Root>
+  );
+};
+
+```
+
 ## components/chart-tool-ui.tsx
 
 ```tsx
 "use client";
 
-import { makeAssistantToolUI } from "@assistant-ui/react";
+import type { ToolCallMessagePartComponent } from "@assistant-ui/react";
 import {
   BarChart,
   Bar,
@@ -528,13 +856,12 @@ const COLORS = [
   "oklch(0.769 0.188 70.08)",
 ];
 
-export const ChartToolUI = makeAssistantToolUI<ChartArgs, ChartResult>({
-  toolName: "generate_chart",
-  render: function ChartUI({ args, status }) {
+export const ChartToolUI: ToolCallMessagePartComponent<ChartArgs, ChartResult> =
+  function ChartUI({ args, status }) {
     if (status.type === "running" && !args.data?.length) {
       return (
         <div className="flex items-center gap-2 rounded-lg border p-4">
-          <Loader2Icon className="size-4 animate-spin text-muted-foreground" />
+          <Loader2Icon className="text-muted-foreground size-4 animate-spin" />
           <span className="text-muted-foreground text-sm">
             Generating chart...
           </span>
@@ -547,7 +874,7 @@ export const ChartToolUI = makeAssistantToolUI<ChartArgs, ChartResult>({
 
     return (
       <div className="my-2 rounded-lg border p-4">
-        <h3 className="mb-3 text-center font-semibold text-sm">{title}</h3>
+        <h3 className="mb-3 text-center text-sm font-semibold">{title}</h3>
         <div className="h-[280px] w-full">
           <ResponsiveContainer width="100%" height="100%">
             {type === "bar" ? (
@@ -620,8 +947,7 @@ export const ChartToolUI = makeAssistantToolUI<ChartArgs, ChartResult>({
         </div>
       </div>
     );
-  },
-});
+  };
 
 ```
 
@@ -631,7 +957,7 @@ export const ChartToolUI = makeAssistantToolUI<ChartArgs, ChartResult>({
 "use client";
 
 import { useState } from "react";
-import { makeAssistantToolUI } from "@assistant-ui/react";
+import type { ToolCallMessagePartComponent } from "@assistant-ui/react";
 import { UserIcon, CheckCircle2Icon } from "lucide-react";
 
 type ContactFormArgs = {
@@ -645,86 +971,79 @@ type ContactFormResult = {
   phone?: string;
 };
 
-export const ContactFormToolUI = makeAssistantToolUI<
+export const ContactFormToolUI: ToolCallMessagePartComponent<
   ContactFormArgs,
   ContactFormResult
->({
-  toolName: "collect_contact",
-  render: function ContactFormUI({ args, result, addResult }) {
-    const [form, setForm] = useState<ContactFormResult>({});
-
-    if (result) {
-      return (
-        <div className="my-2 rounded-lg border border-green-200 bg-green-50 p-3">
-          <div className="mb-1 flex items-center gap-2">
-            <CheckCircle2Icon className="size-4 text-green-600" />
-            <span className="font-medium text-green-800 text-sm">
-              Contact info collected
-            </span>
-          </div>
-          <div className="ml-6 space-y-0.5 text-green-700 text-xs">
-            {result.name && <p>Name: {result.name}</p>}
-            {result.email && <p>Email: {result.email}</p>}
-            {result.phone && <p>Phone: {result.phone}</p>}
-          </div>
-        </div>
-      );
-    }
-
-    const fields = args.fields ?? ["name", "email", "phone"];
-    const isValid = fields.every((f) => form[f]?.trim());
+> = function ContactFormUI({ args, result, addResult }) {
+  const [form, setForm] = useState<ContactFormResult>({});
 
+  if (result) {
     return (
-      <div className="my-2 rounded-lg border p-4">
-        <div className="mb-3 flex items-center gap-2">
-          <UserIcon className="size-4 text-muted-foreground" />
-          <span className="font-medium text-sm">{args.prompt}</span>
+      <div className="my-2 rounded-lg border border-green-200 bg-green-50 p-3">
+        <div className="mb-1 flex items-center gap-2">
+          <CheckCircle2Icon className="size-4 text-green-600" />
+          <span className="text-sm font-medium text-green-800">
+            Contact info collected
+          </span>
         </div>
-        <div className="space-y-2">
-          {fields.includes("name") && (
-            <input
-              type="text"
-              placeholder="Name"
-              value={form.name ?? ""}
-              onChange={(e) => setForm((p) => ({ ...p, name: e.target.value }))}
-              className="w-full rounded-md border bg-background px-3 py-2 text-sm"
-            />
-          )}
-          {fields.includes("email") && (
-            <input
-              type="email"
-              placeholder="Email"
-              value={form.email ?? ""}
-              onChange={(e) =>
-                setForm((p) => ({ ...p, email: e.target.value }))
-              }
-              className="w-full rounded-md border bg-background px-3 py-2 text-sm"
-            />
-          )}
-          {fields.includes("phone") && (
-            <input
-              type="tel"
-              placeholder="Phone"
-              value={form.phone ?? ""}
-              onChange={(e) =>
-                setForm((p) => ({ ...p, phone: e.target.value }))
-              }
-              className="w-full rounded-md border bg-background px-3 py-2 text-sm"
-            />
-          )}
-          <button
-            type="button"
-            disabled={!isValid}
-            onClick={() => addResult(form)}
-            className="w-full rounded-md bg-primary px-4 py-2 font-medium text-primary-foreground text-sm disabled:opacity-50"
-          >
-            Submit
-          </button>
+        <div className="ml-6 space-y-0.5 text-xs text-green-700">
+          {result.name && <p>Name: {result.name}</p>}
+          {result.email && <p>Email: {result.email}</p>}
+          {result.phone && <p>Phone: {result.phone}</p>}
         </div>
       </div>
     );
-  },
-});
+  }
+
+  const fields = args.fields ?? ["name", "email", "phone"];
+  const isValid = fields.every((f) => form[f]?.trim());
+
+  return (
+    <div className="my-2 rounded-lg border p-4">
+      <div className="mb-3 flex items-center gap-2">
+        <UserIcon className="text-muted-foreground size-4" />
+        <span className="text-sm font-medium">{args.prompt}</span>
+      </div>
+      <div className="space-y-2">
+        {fields.includes("name") && (
+          <input
+            type="text"
+            placeholder="Name"
+            value={form.name ?? ""}
+            onChange={(e) => setForm((p) => ({ ...p, name: e.target.value }))}
+            className="bg-background w-full rounded-md border px-3 py-2 text-sm"
+          />
+        )}
+        {fields.includes("email") && (
+          <input
+            type="email"
+            placeholder="Email"
+            value={form.email ?? ""}
+            onChange={(e) => setForm((p) => ({ ...p, email: e.target.value }))}
+            className="bg-background w-full rounded-md border px-3 py-2 text-sm"
+          />
+        )}
+        {fields.includes("phone") && (
+          <input
+            type="tel"
+            placeholder="Phone"
+            value={form.phone ?? ""}
+            onChange={(e) => setForm((p) => ({ ...p, phone: e.target.value }))}
+            className="bg-background w-full rounded-md border px-3 py-2 text-sm"
+          />
+        )}
+        <button
+          type="button"
+          disabled={!isValid}
+          onClick={() => addResult(form)}
+          className="bg-primary text-primary-foreground w-full rounded-md px-4 py-2 text-sm font-medium disabled:opacity-50"
+        >
+          Submit
+        </button>
+      </div>
+    </div>
+  );
+};
 
 ```
 
@@ -734,7 +1053,7 @@ export const ContactFormToolUI = makeAssistantToolUI<
 "use client";
 
 import { useState } from "react";
-import { makeAssistantToolUI } from "@assistant-ui/react";
+import type { ToolCallMessagePartComponent } from "@assistant-ui/react";
 import { CalendarIcon, CheckCircle2Icon } from "lucide-react";
 
 type DatePickerArgs = {
@@ -747,53 +1066,378 @@ type DatePickerResult = {
   date: string;
 };
 
-export const DatePickerToolUI = makeAssistantToolUI<
+export const DatePickerToolUI: ToolCallMessagePartComponent<
   DatePickerArgs,
   DatePickerResult
->({
-  toolName: "select_date",
-  render: function DatePickerUI({ args, result, addResult }) {
-    const [value, setValue] = useState("");
+> = function DatePickerUI({ args, result, addResult }) {
+  const [value, setValue] = useState("");
 
-    if (result) {
-      return (
-        <div className="my-2 flex items-center gap-2 rounded-lg border border-green-200 bg-green-50 p-3">
-          <CheckCircle2Icon className="size-4 text-green-600" />
-          <span className="text-green-800 text-sm">
-            Selected: {new Date(result.date).toLocaleDateString()}
-          </span>
+  if (result) {
+    return (
+      <div className="my-2 flex items-center gap-2 rounded-lg border border-green-200 bg-green-50 p-3">
+        <CheckCircle2Icon className="size-4 text-green-600" />
+        <span className="text-sm text-green-800">
+          Selected: {new Date(result.date).toLocaleDateString()}
+        </span>
+      </div>
+    );
+  }
+
+  return (
+    <div className="my-2 rounded-lg border p-4">
+      <div className="mb-3 flex items-center gap-2">
+        <CalendarIcon className="text-muted-foreground size-4" />
+        <span className="text-sm font-medium">{args.prompt}</span>
+      </div>
+      <div className="flex items-center gap-2">
+        <input
+          type="date"
+          value={value}
+          min={args.minDate}
+          max={args.maxDate}
+          onChange={(e) => setValue(e.target.value)}
+          className="bg-background rounded-md border px-3 py-2 text-sm"
+        />
+        <button
+          type="button"
+          disabled={!value}
+          onClick={() => addResult({ date: new Date(value).toISOString() })}
+          className="bg-primary text-primary-foreground rounded-md px-4 py-2 text-sm font-medium disabled:opacity-50"
+        >
+          Confirm
+        </button>
+      </div>
+    </div>
+  );
+};
+
+```
+
+## components/example-nav.tsx
+
+```tsx
+import Link from "next/link";
+
+const links = [
+  { href: "/", label: "Tool UI demo" },
+  { href: "/primitive", label: "Static primitive" },
+  { href: "/gui-chat", label: "GUI chat" },
+] as const;
+
+export function ExampleNav() {
+  return (
+    <nav className="bg-background flex flex-wrap items-center gap-2 border-b px-4 py-2 text-sm">
+      <span className="text-muted-foreground font-medium">Examples:</span>
+      {links.map(({ href, label }) => (
+        <Link
+          key={href}
+          href={href}
+          className="text-foreground hover:bg-muted rounded-md px-2 py-1"
+        >
+          {label}
+        </Link>
+      ))}
+    </nav>
+  );
+}
+
+```
+
+## components/gui-thread.tsx
+
+```tsx
+import {
+  ComposerAddAttachment,
+  ComposerAttachments,
+  UserMessageAttachments,
+} from "@/components/assistant-ui/attachment";
+import { TooltipIconButton } from "@/components/assistant-ui/tooltip-icon-button";
+import { Button } from "@/components/ui/button";
+import { cn } from "@/lib/utils";
+import {
+  ActionBarPrimitive,
+  AuiIf,
+  BranchPickerPrimitive,
+  ComposerPrimitive,
+  MessagePrimitive,
+  SuggestionPrimitive,
+  ThreadPrimitive,
+  useAuiState,
+} from "@assistant-ui/react";
+import {
+  ArrowDownIcon,
+  ArrowUpIcon,
+  ChevronLeftIcon,
+  ChevronRightIcon,
+  PencilIcon,
+  SquareIcon,
+} from "lucide-react";
+import type { FC } from "react";
+import { AssistantMessageGui } from "@/components/assistant-message-gui";
+
+/** Thread fork: swaps the assistant message renderer for the generative-ui bridge. */
+export const GuiThread: FC = () => {
+  return (
+    <ThreadPrimitive.Root
+      className="aui-root aui-thread-root bg-background @container flex h-full flex-col"
+      style={{
+        ["--thread-max-width" as string]: "44rem",
+        ["--composer-radius" as string]: "24px",
+        ["--composer-padding" as string]: "10px",
+      }}
+    >
+      <ThreadPrimitive.Viewport
+        turnAnchor="top"
+        data-slot="aui_thread-viewport"
+        className="relative flex flex-1 flex-col overflow-x-auto overflow-y-scroll scroll-smooth"
+      >
+        <div className="mx-auto flex w-full max-w-(--thread-max-width) flex-1 flex-col px-4 pt-4">
+          <AuiIf condition={(s) => s.thread.isEmpty}>
+            <ThreadWelcome />
+          </AuiIf>
+
+          <div
+            data-slot="aui_message-group"
+            className="mb-10 flex flex-col gap-y-8 empty:hidden"
+          >
+            <ThreadPrimitive.Messages>
+              {() => <ThreadMessage />}
+            </ThreadPrimitive.Messages>
+          </div>
+
+          <ThreadPrimitive.ViewportFooter className="aui-thread-viewport-footer bg-background sticky bottom-0 mt-auto flex flex-col gap-4 overflow-visible rounded-t-(--composer-radius) pb-4 md:pb-6">
+            <ThreadScrollToBottom />
+            <Composer />
+          </ThreadPrimitive.ViewportFooter>
         </div>
-      );
-    }
+      </ThreadPrimitive.Viewport>
+    </ThreadPrimitive.Root>
+  );
+};
 
-    return (
-      <div className="my-2 rounded-lg border p-4">
-        <div className="mb-3 flex items-center gap-2">
-          <CalendarIcon className="size-4 text-muted-foreground" />
-          <span className="font-medium text-sm">{args.prompt}</span>
+const ThreadMessage: FC = () => {
+  const role = useAuiState((s) => s.message.role);
+  const isEditing = useAuiState((s) => s.message.composer.isEditing);
+
+  if (isEditing) return <EditComposer />;
+  if (role === "user") return <UserMessage />;
+  return <AssistantMessageGui />;
+};
+
+const ThreadScrollToBottom: FC = () => {
+  return (
+    <ThreadPrimitive.ScrollToBottom asChild>
+      <TooltipIconButton
+        tooltip="Scroll to bottom"
+        variant="outline"
+        className="aui-thread-scroll-to-bottom dark:border-border dark:bg-background dark:hover:bg-accent absolute -top-12 z-10 self-center rounded-full p-4 disabled:invisible"
+      >
+        <ArrowDownIcon />
+      </TooltipIconButton>
+    </ThreadPrimitive.ScrollToBottom>
+  );
+};
+
+const ThreadWelcome: FC = () => {
+  return (
+    <div className="aui-thread-welcome-root my-auto flex grow flex-col">
+      <div className="aui-thread-welcome-center flex w-full grow flex-col items-center justify-center">
+        <div className="aui-thread-welcome-message flex size-full flex-col justify-center px-4">
+          <h1 className="aui-thread-welcome-message-inner fade-in slide-in-from-bottom-1 animate-in fill-mode-both text-2xl font-semibold duration-200">
+            Compose UI from a spec
+          </h1>
+          <p className="aui-thread-welcome-message-inner fade-in slide-in-from-bottom-1 animate-in fill-mode-both text-muted-foreground text-xl delay-75 duration-200">
+            Ask the agent to call render_gui with Card, Button, and Stack.
+          </p>
         </div>
-        <div className="flex items-center gap-2">
-          <input
-            type="date"
-            value={value}
-            min={args.minDate}
-            max={args.maxDate}
-            onChange={(e) => setValue(e.target.value)}
-            className="rounded-md border bg-background px-3 py-2 text-sm"
+      </div>
+      <ThreadSuggestions />
+    </div>
+  );
+};
+
+const ThreadSuggestions: FC = () => {
+  return (
+    <div className="aui-thread-welcome-suggestions grid w-full gap-2 pb-4 @md:grid-cols-2">
+      <ThreadPrimitive.Suggestions>
+        {() => <ThreadSuggestionItem />}
+      </ThreadPrimitive.Suggestions>
+    </div>
+  );
+};
+
+const ThreadSuggestionItem: FC = () => {
+  return (
+    <div className="aui-thread-welcome-suggestion-display fade-in slide-in-from-bottom-2 animate-in fill-mode-both duration-200 nth-[n+3]:hidden @md:nth-[n+3]:block">
+      <SuggestionPrimitive.Trigger send asChild>
+        <Button
+          variant="ghost"
+          className="aui-thread-welcome-suggestion bg-background hover:bg-muted h-auto w-full flex-wrap items-start justify-start gap-1 rounded-3xl border px-4 py-3 text-start text-sm transition-colors @md:flex-col"
+        >
+          <SuggestionPrimitive.Title className="aui-thread-welcome-suggestion-text-1 font-medium" />
+          <SuggestionPrimitive.Description className="aui-thread-welcome-suggestion-text-2 text-muted-foreground empty:hidden" />
+        </Button>
+      </SuggestionPrimitive.Trigger>
+    </div>
+  );
+};
+
+const Composer: FC = () => {
+  return (
+    <ComposerPrimitive.Root className="aui-composer-root relative flex w-full flex-col">
+      <ComposerPrimitive.AttachmentDropzone asChild>
+        <div
+          data-slot="aui_composer-shell"
+          className="bg-background focus-within:border-ring/75 focus-within:ring-ring/20 data-[dragging=true]:border-ring data-[dragging=true]:bg-accent/50 flex w-full flex-col gap-2 rounded-(--composer-radius) border p-(--composer-padding) transition-shadow focus-within:ring-2 data-[dragging=true]:border-dashed"
+        >
+          <ComposerAttachments />
+          <ComposerPrimitive.Input
+            placeholder="Send a message..."
+            className="aui-composer-input placeholder:text-muted-foreground/80 max-h-32 min-h-10 w-full resize-none bg-transparent px-1.75 py-1 text-sm outline-none"
+            rows={1}
+            autoFocus
+            aria-label="Message input"
           />
-          <button
+          <ComposerAction />
+        </div>
+      </ComposerPrimitive.AttachmentDropzone>
+    </ComposerPrimitive.Root>
+  );
+};
+
+const ComposerAction: FC = () => {
+  return (
+    <div className="aui-composer-action-wrapper relative flex items-center justify-between">
+      <ComposerAddAttachment />
+      <AuiIf condition={(s) => !s.thread.isRunning}>
+        <ComposerPrimitive.Send asChild>
+          <TooltipIconButton
+            tooltip="Send message"
+            side="bottom"
             type="button"
-            disabled={!value}
-            onClick={() => addResult({ date: new Date(value).toISOString() })}
-            className="rounded-md bg-primary px-4 py-2 font-medium text-primary-foreground text-sm disabled:opacity-50"
+            variant="default"
+            size="icon"
+            className="aui-composer-send size-8 rounded-full"
+            aria-label="Send message"
           >
-            Confirm
-          </button>
+            <ArrowUpIcon className="aui-composer-send-icon size-4" />
+          </TooltipIconButton>
+        </ComposerPrimitive.Send>
+      </AuiIf>
+      <AuiIf condition={(s) => s.thread.isRunning}>
+        <ComposerPrimitive.Cancel asChild>
+          <Button
+            type="button"
+            variant="default"
+            size="icon"
+            className="aui-composer-cancel size-8 rounded-full"
+            aria-label="Stop generating"
+          >
+            <SquareIcon className="aui-composer-cancel-icon size-3 fill-current" />
+          </Button>
+        </ComposerPrimitive.Cancel>
+      </AuiIf>
+    </div>
+  );
+};
+
+const UserMessage: FC = () => {
+  return (
+    <MessagePrimitive.Root
+      data-slot="aui_user-message-root"
+      className="fade-in slide-in-from-bottom-1 animate-in grid auto-rows-auto grid-cols-[minmax(72px,1fr)_auto] content-start gap-y-2 px-2 duration-150 [contain-intrinsic-size:auto_60px] [content-visibility:auto] [&:where(>*)]:col-start-2"
+      data-role="user"
+    >
+      <UserMessageAttachments />
+
+      <div className="aui-user-message-content-wrapper relative col-start-2 min-w-0">
+        <div className="aui-user-message-content peer bg-muted text-foreground rounded-2xl px-4 py-2.5 wrap-break-word empty:hidden">
+          <MessagePrimitive.Parts />
+        </div>
+        <div className="aui-user-action-bar-wrapper absolute start-0 top-1/2 -translate-x-full -translate-y-1/2 pe-2 peer-empty:hidden rtl:translate-x-full">
+          <UserActionBar />
         </div>
       </div>
-    );
-  },
-});
+
+      <BranchPicker
+        data-slot="aui_user-branch-picker"
+        className="col-span-full col-start-1 row-start-3 -me-1 justify-end"
+      />
+    </MessagePrimitive.Root>
+  );
+};
+
+const UserActionBar: FC = () => {
+  return (
+    <ActionBarPrimitive.Root
+      hideWhenRunning
+      autohide="not-last"
+      className="aui-user-action-bar-root flex flex-col items-end"
+    >
+      <ActionBarPrimitive.Edit asChild>
+        <TooltipIconButton tooltip="Edit" className="aui-user-action-edit p-4">
+          <PencilIcon />
+        </TooltipIconButton>
+      </ActionBarPrimitive.Edit>
+    </ActionBarPrimitive.Root>
+  );
+};
+
+const EditComposer: FC = () => {
+  return (
+    <MessagePrimitive.Root
+      data-slot="aui_edit-composer-wrapper"
+      className="flex flex-col px-2"
+    >
+      <ComposerPrimitive.Root className="aui-edit-composer-root bg-muted ms-auto flex w-full max-w-[85%] flex-col rounded-2xl">
+        <ComposerPrimitive.Input
+          className="aui-edit-composer-input text-foreground min-h-14 w-full resize-none bg-transparent p-4 text-sm outline-none"
+          autoFocus
+        />
+        <div className="aui-edit-composer-footer mx-3 mb-3 flex items-center gap-2 self-end">
+          <ComposerPrimitive.Cancel asChild>
+            <Button variant="ghost" size="sm">
+              Cancel
+            </Button>
+          </ComposerPrimitive.Cancel>
+          <ComposerPrimitive.Send asChild>
+            <Button size="sm">Update</Button>
+          </ComposerPrimitive.Send>
+        </div>
+      </ComposerPrimitive.Root>
+    </MessagePrimitive.Root>
+  );
+};
+
+const BranchPicker: FC<BranchPickerPrimitive.Root.Props> = ({
+  className,
+  ...rest
+}) => {
+  return (
+    <BranchPickerPrimitive.Root
+      hideWhenSingleBranch
+      className={cn(
+        "aui-branch-picker-root text-muted-foreground -ms-2 me-2 inline-flex items-center text-xs",
+        className,
+      )}
+      {...rest}
+    >
+      <BranchPickerPrimitive.Previous asChild>
+        <TooltipIconButton tooltip="Previous">
+          <ChevronLeftIcon />
+        </TooltipIconButton>
+      </BranchPickerPrimitive.Previous>
+      <span className="aui-branch-picker-state font-medium">
+        <BranchPickerPrimitive.Number /> / <BranchPickerPrimitive.Count />
+      </span>
+      <BranchPickerPrimitive.Next asChild>
+        <TooltipIconButton tooltip="Next">
+          <ChevronRightIcon />
+        </TooltipIconButton>
+      </BranchPickerPrimitive.Next>
+    </BranchPickerPrimitive.Root>
+  );
+};
 
 ```
 
@@ -809,13 +1453,23 @@ import type { ComponentType, PropsWithChildren } from "react";
  * The agent's JSON spec can reference any of these by name.
  */
 
+export const UnknownComponentFallback = ({
+  component,
+}: {
+  component: string;
+}) => (
+  <span className="bg-muted rounded px-1.5 py-0.5 font-mono text-xs">
+    unknown component: {component}
+  </span>
+);
+
 const Card: ComponentType<
   PropsWithChildren<{ title?: string; description?: string }>
 > = ({ title, description, children }) => (
-  <div className="rounded-xl border bg-card p-4 shadow-sm">
-    {title ? <div className="font-semibold text-base">{title}</div> : null}
+  <div className="bg-card rounded-xl border p-4 shadow-sm">
+    {title ? <div className="text-base font-semibold">{title}</div> : null}
     {description ? (
-      <div className="mt-1 text-muted-foreground text-sm">{description}</div>
+      <div className="text-muted-foreground mt-1 text-sm">{description}</div>
     ) : null}
     {children ? <div className="mt-3">{children}</div> : null}
   </div>
@@ -835,7 +1489,7 @@ const Button: ComponentType<
   return (
     <button
       type="button"
-      className={`mt-2 inline-flex items-center rounded-md px-3 py-1.5 font-medium text-sm ${cls}`}
+      className={`mt-2 inline-flex items-center rounded-md px-3 py-1.5 text-sm font-medium ${cls}`}
       onClick={() => {
         if (onClickPrompt) {
           // In a richer integration this would call composer.setText / send.
@@ -877,9 +1531,9 @@ const Stat: ComponentType<{ label: string; value: string | number }> = ({
   label,
   value,
 }) => (
-  <div className="flex flex-col rounded-lg border bg-muted/40 p-3">
+  <div className="bg-muted/40 flex flex-col rounded-lg border p-3">
     <span className="text-muted-foreground text-xs">{label}</span>
-    <span className="font-semibold text-xl">{value}</span>
+    <span className="text-xl font-semibold">{value}</span>
   </div>
 );
 
@@ -899,7 +1553,7 @@ export const componentsAllowlist = {
 ```tsx
 "use client";
 
-import { makeAssistantToolUI } from "@assistant-ui/react";
+import type { ToolCallMessagePartComponent } from "@assistant-ui/react";
 import { MapPinIcon, Loader2Icon } from "lucide-react";
 
 type LocationArgs = {
@@ -913,60 +1567,199 @@ type LocationResult = {
   success: boolean;
 };
 
-export const LocationToolUI = makeAssistantToolUI<LocationArgs, LocationResult>(
-  {
-    toolName: "show_location",
-    render: function LocationUI({ args, status }) {
-      if (status.type === "running" && !args.lat) {
-        return (
-          <div className="flex items-center gap-2 rounded-lg border p-4">
-            <Loader2Icon className="size-4 animate-spin text-muted-foreground" />
-            <span className="text-muted-foreground text-sm">
-              Loading location...
-            </span>
-          </div>
-        );
-      }
+export const LocationToolUI: ToolCallMessagePartComponent<
+  LocationArgs,
+  LocationResult
+> = function LocationUI({ args, status }) {
+  if (status.type === "running" && (args.lat == null || args.lng == null)) {
+    return (
+      <div className="flex items-center gap-2 rounded-lg border p-4">
+        <Loader2Icon className="text-muted-foreground size-4 animate-spin" />
+        <span className="text-muted-foreground text-sm">
+          Loading location...
+        </span>
+      </div>
+    );
+  }
 
-      const { name, address, lat, lng } = args;
-      if (!lat || !lng) return null;
+  const { name, address, lat, lng } = args;
+  if (lat == null || lng == null) return null;
 
-      const mapSrc = `https://www.openstreetmap.org/export/embed.html?bbox=${lng - 0.01},${lat - 0.01},${lng + 0.01},${lat + 0.01}&layer=mapnik&marker=${lat},${lng}`;
+  const mapSrc = `https://www.openstreetmap.org/export/embed.html?bbox=${lng - 0.01},${lat - 0.01},${lng + 0.01},${lat + 0.01}&layer=mapnik&marker=${lat},${lng}`;
 
-      return (
-        <div className="my-2 overflow-hidden rounded-lg border">
-          <div className="flex items-center gap-2 border-b px-3 py-2">
-            <MapPinIcon className="size-4 text-muted-foreground" />
-            <div>
-              <p className="font-medium text-sm">{name}</p>
-              {address && (
-                <p className="text-muted-foreground text-xs">{address}</p>
-              )}
-            </div>
-          </div>
-          <iframe
-            title={`Map of ${name}`}
-            src={mapSrc}
-            className="h-[200px] w-full border-0"
-          />
+  return (
+    <div className="my-2 overflow-hidden rounded-lg border">
+      <div className="flex items-center gap-2 border-b px-3 py-2">
+        <MapPinIcon className="text-muted-foreground size-4" />
+        <div>
+          <p className="text-sm font-medium">{name}</p>
+          {address && (
+            <p className="text-muted-foreground text-xs">{address}</p>
+          )}
         </div>
-      );
-    },
-  },
+      </div>
+      <iframe
+        title={`Map of ${name}`}
+        src={mapSrc}
+        className="h-[200px] w-full border-0"
+      />
+    </div>
+  );
+};
+
+```
+
+## lib/render-gui-tool.test.ts
+
+```typescript
+import { describe, expect, it } from "vitest";
+import {
+  generativeUISpecSchema,
+  isLeakedRenderGuiText,
+  parseRenderGuiResult,
+  renderGuiToolResultSchema,
+} from "./render-gui-tool";
+
+describe("render-gui-tool", () => {
+  it("accepts a valid Card + Button spec", () => {
+    const spec = {
+      root: {
+        component: "Card",
+        props: { title: "Welcome" },
+        children: [
+          {
+            component: "Button",
+            props: { label: "Get started", variant: "primary" },
+          },
+        ],
+      },
+    };
+
+    expect(generativeUISpecSchema.parse(spec)).toEqual(spec);
+    expect(
+      parseRenderGuiResult(renderGuiToolResultSchema.parse({ spec })),
+    ).toEqual(spec);
+  });
+
+  it("rejects a spec with empty component name", () => {
+    expect(() =>
+      generativeUISpecSchema.parse({
+        root: { component: "", props: { title: "Bad" } },
+      }),
+    ).toThrow();
+  });
+
+  it("returns undefined for malformed tool results", () => {
+    expect(parseRenderGuiResult({ notSpec: true })).toBeUndefined();
+    expect(parseRenderGuiResult(null)).toBeUndefined();
+  });
+
+  it("detects leaked render_gui tool result text", () => {
+    const payload = renderGuiToolResultSchema.parse({
+      spec: {
+        root: {
+          component: "Card",
+          children: [{ component: "Text", children: ["Hello"] }],
+        },
+      },
+    });
+
+    expect(isLeakedRenderGuiText(JSON.stringify(payload, null, 2))).toBe(true);
+    expect(
+      isLeakedRenderGuiText(
+        "```json\n" + JSON.stringify(payload, null, 2) + "\n```",
+      ),
+    ).toBe(true);
+    expect(isLeakedRenderGuiText("Here is your card.")).toBe(false);
+  });
+});
+
+```
+
+## lib/render-gui-tool.ts
+
+```typescript
+import { z } from "zod";
+import type { GenerativeUISpec } from "@assistant-ui/react";
+
+export const RENDER_GUI_TOOL_NAME = "render_gui" as const;
+
+const generativeUINodeSchema: z.ZodType<unknown> = z.lazy(() =>
+  z.union([
+    z.string(),
+    z.object({
+      component: z.string().min(1),
+      props: z.record(z.string(), z.unknown()).optional(),
+      children: z.array(generativeUINodeSchema).optional(),
+      key: z.string().optional(),
+    }),
+  ]),
 );
 
+export const generativeUISpecSchema = z.object({
+  root: z.union([
+    generativeUINodeSchema,
+    z.array(generativeUINodeSchema).min(1),
+  ]),
+});
+
+export const renderGuiToolInputSchema = z.object({
+  spec: generativeUISpecSchema,
+});
+
+export const renderGuiToolResultSchema = renderGuiToolInputSchema;
+
+export const parseRenderGuiResult = (
+  result: unknown,
+): GenerativeUISpec | undefined => {
+  const parsed = renderGuiToolResultSchema.safeParse(result);
+  return parsed.success ? (parsed.data.spec as GenerativeUISpec) : undefined;
+};
+
+export const renderGuiToolDescription =
+  "Compose inline UI from the allowlisted component library (Card, Text, Button, Stack, Stat, Heading). " +
+  "Pass a JSON spec with a root node tree. Use for dashboards, status panels, and structured layouts — not for user input forms (use interactive tool UI instead).";
+
+export const renderGuiChatInstructions =
+  "When the user asks for UI, call render_gui with the spec. " +
+  "Do not paste JSON, code blocks, or the tool result in your text reply — the client renders the UI from the tool output automatically. " +
+  "Keep any text reply brief or omit it when the UI alone answers the request.";
+
+const stripMarkdownJsonFence = (text: string): string => {
+  const trimmed = text.trim();
+  const match = trimmed.match(/^```(?:json)?\s*\n?([\s\S]*?)\n?```\s*$/i);
+  return match ? match[1]!.trim() : trimmed;
+};
+
+/** Text echo of a render_gui tool result/spec — hide when the bridge already rendered it. */
+export const isLeakedRenderGuiText = (text: string): boolean => {
+  const candidate = stripMarkdownJsonFence(text);
+  if (!candidate.startsWith("{")) return false;
+
+  try {
+    const parsed = JSON.parse(candidate);
+    if (renderGuiToolResultSchema.safeParse(parsed).success) return true;
+    if (generativeUISpecSchema.safeParse(parsed).success) return true;
+  } catch {
+    return false;
+  }
+
+  return false;
+};
+
 ```
 
 ## next.config.ts
 
 ```typescript
+import { withAui } from "@assistant-ui/next";
 import type { NextConfig } from "next";
 
 const nextConfig: NextConfig = {
   /* config options here */
 };
 
-export default nextConfig;
+export default withAui(nextConfig);
 
 ```
 
@@ -981,34 +1774,37 @@ export default nextConfig;
   "scripts": {
     "dev": "next dev",
     "build": "next build",
-    "start": "next start"
+    "start": "next start",
+    "test": "vitest run"
   },
   "dependencies": {
-    "@ai-sdk/openai": "^3.0.64",
+    "@ai-sdk/openai": "^3.0.68",
     "@assistant-ui/react": "workspace:*",
     "@assistant-ui/react-ai-sdk": "workspace:*",
     "@assistant-ui/ui": "workspace:*",
-    "ai": "^6.0.188",
+    "ai": "^6.0.197",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
-    "lucide-react": "^1.16.0",
-    "next": "^16.2.6",
-    "react": "^19.2.6",
-    "react-dom": "^19.2.6",
+    "lucide-react": "^1.17.0",
+    "next": "^16.2.7",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7",
     "recharts": "^3.8.1",
     "tailwind-merge": "^3.6.0",
     "zod": "^4.4.3"
   },
   "devDependencies": {
+    "@assistant-ui/next": "workspace:*",
     "@assistant-ui/x-buildutils": "workspace:*",
     "@tailwindcss/postcss": "^4.3.0",
-    "@types/node": "^25.9.1",
-    "@types/react": "^19.2.15",
+    "@types/node": "^25.9.2",
+    "@types/react": "^19.2.17",
     "@types/react-dom": "^19.2.3",
     "postcss": "^8.5.15",
     "tailwindcss": "^4.3.0",
     "tw-animate-css": "^1.4.0",
-    "typescript": "^6.0.3"
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.8"
   }
 }
 
@@ -1036,3 +1832,17 @@ export default nextConfig;
 
 ```
 
+## vitest.config.ts
+
+```typescript
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    environment: "node",
+    include: ["lib/**/*.test.ts"],
+  },
+});
+
+```
+