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

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

@@ -14,6 +14,10 @@ import {
 } from "ai";
 import type { UIMessage } from "ai";
 import { z } from "zod";
+import {
+  renderGuiToolDescription,
+  renderGuiToolInputSchema,
+} from "../../../lib/render-gui-tool";
 
 export const maxDuration = 30;
 
@@ -44,13 +48,21 @@ export async function POST(req: Request) {
     : {};
 
   const result = streamText({
-    model: openai("gpt-4o"),
+    model: openai("gpt-5.4-nano"),
     messages: await convertToModelMessages(messages),
     stopWhen: stepCountIs(10),
     ...(system ? { system } : {}),
     tools: {
       ...frontendToolDefs,
 
+      render_gui: tool({
+        description: renderGuiToolDescription,
+        inputSchema: zodSchema(renderGuiToolInputSchema),
+        execute: async (input) => ({
+          spec: input.spec,
+        }),
+      }),
+
       // Backend tool: generate chart data
       generate_chart: tool({
         description:
@@ -231,6 +243,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,8 +337,9 @@ import { Thread } from "@/components/assistant-ui/thread";
 import {
   AssistantRuntimeProvider,
   Suggestions,
+  Tools,
+  type Toolkit,
   useAui,
-  useAssistantTool,
 } from "@assistant-ui/react";
 import { useChatRuntime } from "@assistant-ui/react-ai-sdk";
 import { lastAssistantMessageIsCompleteWithToolCalls } from "ai";
@@ -276,11 +348,11 @@ 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 { ExampleNav } from "@/components/example-nav";
 
-// Register frontend tool schemas (no execute — resolved via addResult in the UI)
-function FrontendTools() {
-  useAssistantTool({
-    toolName: "select_date",
+const toolkit = {
+  select_date: {
+    type: "human",
     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({
@@ -288,10 +360,10 @@ function FrontendTools() {
       minDate: z.string().optional().describe("Minimum date (ISO string)"),
       maxDate: z.string().optional().describe("Maximum date (ISO string)"),
     }),
-  });
-
-  useAssistantTool({
-    toolName: "collect_contact",
+    render: DatePickerToolUI,
+  },
+  collect_contact: {
+    type: "human",
     description:
       "Collect contact information from the user. Use this when you need the user's name, email, or phone number.",
     parameters: z.object({
@@ -300,10 +372,17 @@ function FrontendTools() {
         .array(z.enum(["name", "email", "phone"]))
         .describe("Which fields to collect"),
     }),
-  });
-
-  return null;
-}
+    render: ContactFormToolUI,
+  },
+  generate_chart: {
+    type: "backend",
+    render: ChartToolUI,
+  },
+  show_location: {
+    type: "backend",
+    render: LocationToolUI,
+  },
+} satisfies Toolkit;
 
 export default function Home() {
   const runtime = useChatRuntime({
@@ -311,6 +390,7 @@ export default function Home() {
   });
 
   const aui = useAui({
+    tools: Tools({ toolkit }),
     suggestions: Suggestions([
       {
         title: "Show a bar chart",
@@ -339,22 +419,119 @@ 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>
   );
 }
 
 ```
 
+## app/primitive/page.tsx
+
+```tsx
+"use client";
+
+import { GenerativeUIRender, type GenerativeUISpec } from "@assistant-ui/react";
+import {
+  UnknownComponentFallback,
+  componentsAllowlist,
+} from "@/components/gui";
+import { ExampleNav } from "@/components/example-nav";
+
+/**
+ * Self-contained demo of the GenerativeUI primitive.
+ *
+ * Renders a hand-written `GenerativeUISpec` directly via `GenerativeUIRender`,
+ * the same renderer that backs `MessagePrimitive.GenerativeUI` when a
+ * `generative-ui` part flows through `MessagePrimitive.Parts`.
+ *
+ * In a real integration the spec arrives as a `generative-ui` message part
+ * from the agent; the consumer-provided allowlist is the security boundary.
+ */
+const exampleSpec: GenerativeUISpec = {
+  root: [
+    {
+      component: "Card",
+      props: {
+        title: "Welcome",
+        description: "An agent-described card with a primary CTA.",
+      },
+      children: [
+        {
+          component: "Stack",
+          props: { gap: "sm" },
+          children: [
+            {
+              component: "Text",
+              children: [
+                "This card was rendered from a JSON spec emitted by the agent.",
+              ],
+            },
+            {
+              component: "Button",
+              props: {
+                label: "Get started",
+                variant: "primary",
+                onClickPrompt: "open onboarding",
+              },
+            },
+          ],
+        },
+      ],
+    },
+    {
+      component: "Card",
+      props: { title: "Stats" },
+      children: [
+        {
+          component: "Stack",
+          props: { direction: "row", gap: "md" },
+          children: [
+            { component: "Stat", props: { label: "Revenue", value: "$124k" } },
+            {
+              component: "Stat",
+              props: { label: "Active Users", value: "8.2k" },
+            },
+            { component: "Stat", props: { label: "Latency", value: "42ms" } },
+          ],
+        },
+      ],
+    },
+  ],
+};
+
+export default function GenerativeUIPrimitivePage() {
+  return (
+    <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>
+  );
+}
+
+```
+
 ## components.json
 
 ```json
@@ -385,12 +562,257 @@ export default function Home() {
 
 ```
 
+## 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,
@@ -428,13 +850,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>
@@ -447,7 +868,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" ? (
@@ -520,8 +941,7 @@ export const ChartToolUI = makeAssistantToolUI<ChartArgs, ChartResult>({
         </div>
       </div>
     );
-  },
-});
+  };
 
 ```
 
@@ -531,7 +951,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 = {
@@ -545,86 +965,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>
+  );
+};
 
 ```
 
@@ -634,7 +1047,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 = {
@@ -647,53 +1060,485 @@ 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>
+  );
+};
+
+```
+
+## components/gui/index.tsx
+
+```tsx
+"use client";
+
+import type { ComponentType, PropsWithChildren } from "react";
+
+/**
+ * The component allowlist passed to `<MessagePrimitive.GenerativeUI />`.
+ * 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="bg-card rounded-xl border p-4 shadow-sm">
+    {title ? <div className="text-base font-semibold">{title}</div> : null}
+    {description ? (
+      <div className="text-muted-foreground mt-1 text-sm">{description}</div>
+    ) : null}
+    {children ? <div className="mt-3">{children}</div> : null}
+  </div>
+);
+
+const Button: ComponentType<
+  PropsWithChildren<{
+    label?: string;
+    variant?: "primary" | "secondary";
+    onClickPrompt?: string;
+  }>
+> = ({ label, variant = "primary", onClickPrompt, children }) => {
+  const cls =
+    variant === "primary"
+      ? "bg-primary text-primary-foreground hover:bg-primary/90"
+      : "bg-secondary text-secondary-foreground hover:bg-secondary/80";
+  return (
+    <button
+      type="button"
+      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.
+          alert(`button -> ${onClickPrompt}`);
+        }
+      }}
+    >
+      {children ?? label ?? "Click"}
+    </button>
+  );
+};
+
+const Stack: ComponentType<
+  PropsWithChildren<{ gap?: "sm" | "md" | "lg"; direction?: "row" | "column" }>
+> = ({ gap = "md", direction = "column", children }) => {
+  const gapClass = gap === "sm" ? "gap-2" : gap === "lg" ? "gap-6" : "gap-4";
+  const dirClass = direction === "row" ? "flex-row" : "flex-col";
+  return <div className={`flex ${dirClass} ${gapClass}`}>{children}</div>;
+};
+
+const Heading: ComponentType<
+  PropsWithChildren<{ level?: 1 | 2 | 3; children?: React.ReactNode }>
+> = ({ level = 2, children }) => {
+  const cls =
+    level === 1
+      ? "text-2xl font-bold"
+      : level === 2
+        ? "text-lg font-semibold"
+        : "text-base font-semibold";
+  const Tag = `h${level}` as keyof React.JSX.IntrinsicElements;
+  return <Tag className={cls}>{children}</Tag>;
+};
+
+const Text: ComponentType<PropsWithChildren> = ({ children }) => (
+  <p className="text-foreground text-sm leading-6">{children}</p>
+);
+
+const Stat: ComponentType<{ label: string; value: string | number }> = ({
+  label,
+  value,
+}) => (
+  <div className="bg-muted/40 flex flex-col rounded-lg border p-3">
+    <span className="text-muted-foreground text-xs">{label}</span>
+    <span className="text-xl font-semibold">{value}</span>
+  </div>
+);
+
+export const componentsAllowlist = {
+  Card,
+  Button,
+  Stack,
+  Heading,
+  Text,
+  Stat,
+} as const;
 
 ```
 
@@ -702,7 +1547,7 @@ export const DatePickerToolUI = makeAssistantToolUI<
 ```tsx
 "use client";
 
-import { makeAssistantToolUI } from "@assistant-ui/react";
+import type { ToolCallMessagePartComponent } from "@assistant-ui/react";
 import { MapPinIcon, Loader2Icon } from "lucide-react";
 
 type LocationArgs = {
@@ -716,60 +1561,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);
 
 ```
 
@@ -784,34 +1768,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.61",
+    "@ai-sdk/openai": "^3.0.67",
     "@assistant-ui/react": "workspace:*",
     "@assistant-ui/react-ai-sdk": "workspace:*",
     "@assistant-ui/ui": "workspace:*",
-    "ai": "^6.0.175",
+    "ai": "^6.0.193",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
-    "lucide-react": "^1.14.0",
-    "next": "^16.2.4",
-    "react": "^19.2.5",
-    "react-dom": "^19.2.5",
+    "lucide-react": "^1.17.0",
+    "next": "^16.2.6",
+    "react": "^19.2.6",
+    "react-dom": "^19.2.6",
     "recharts": "^3.8.1",
-    "tailwind-merge": "^3.5.0",
+    "tailwind-merge": "^3.6.0",
     "zod": "^4.4.3"
   },
   "devDependencies": {
+    "@assistant-ui/next": "workspace:*",
     "@assistant-ui/x-buildutils": "workspace:*",
-    "@tailwindcss/postcss": "^4.2.4",
-    "@types/node": "^25.6.0",
-    "@types/react": "^19.2.14",
+    "@tailwindcss/postcss": "^4.3.0",
+    "@types/node": "^25.9.1",
+    "@types/react": "^19.2.15",
     "@types/react-dom": "^19.2.3",
-    "postcss": "^8.5.14",
-    "tailwindcss": "^4.2.4",
+    "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.7"
   }
 }
 
@@ -839,3 +1826,17 @@ export default nextConfig;
 
 ```
 
+## vitest.config.ts
+
+```typescript
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    environment: "node",
+    include: ["lib/**/*.test.ts"],
+  },
+});
+
+```
+