@assistant-ui/mcp-docs-server 0.1.3 → 0.1.5

package/.docs/organized/code-examples/with-parent-id-grouping.md

@@ -0,0 +1,1374 @@
+# Example: with-parent-id-grouping
+
+## app/globals.css
+
+```css
+@import "tailwindcss";
+@import "tw-animate-css";
+
+@custom-variant dark (&:is(.dark *));
+
+@theme inline {
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  --font-sans: var(--font-geist-sans);
+  --font-mono: var(--font-geist-mono);
+  --color-sidebar-ring: var(--sidebar-ring);
+  --color-sidebar-border: var(--sidebar-border);
+  --color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
+  --color-sidebar-accent: var(--sidebar-accent);
+  --color-sidebar-primary-foreground: var(--sidebar-primary-foreground);
+  --color-sidebar-primary: var(--sidebar-primary);
+  --color-sidebar-foreground: var(--sidebar-foreground);
+  --color-sidebar: var(--sidebar);
+  --color-chart-5: var(--chart-5);
+  --color-chart-4: var(--chart-4);
+  --color-chart-3: var(--chart-3);
+  --color-chart-2: var(--chart-2);
+  --color-chart-1: var(--chart-1);
+  --color-ring: var(--ring);
+  --color-input: var(--input);
+  --color-border: var(--border);
+  --color-destructive: var(--destructive);
+  --color-accent-foreground: var(--accent-foreground);
+  --color-accent: var(--accent);
+  --color-muted-foreground: var(--muted-foreground);
+  --color-muted: var(--muted);
+  --color-secondary-foreground: var(--secondary-foreground);
+  --color-secondary: var(--secondary);
+  --color-primary-foreground: var(--primary-foreground);
+  --color-primary: var(--primary);
+  --color-popover-foreground: var(--popover-foreground);
+  --color-popover: var(--popover);
+  --color-card-foreground: var(--card-foreground);
+  --color-card: var(--card);
+  --radius-sm: calc(var(--radius) - 4px);
+  --radius-md: calc(var(--radius) - 2px);
+  --radius-lg: var(--radius);
+  --radius-xl: calc(var(--radius) + 4px);
+}
+
+:root {
+  --radius: 0.625rem;
+  --background: oklch(1 0 0);
+  --foreground: oklch(0.141 0.005 285.823);
+  --card: oklch(1 0 0);
+  --card-foreground: oklch(0.141 0.005 285.823);
+  --popover: oklch(1 0 0);
+  --popover-foreground: oklch(0.141 0.005 285.823);
+  --primary: oklch(0.21 0.006 285.885);
+  --primary-foreground: oklch(0.985 0 0);
+  --secondary: oklch(0.967 0.001 286.375);
+  --secondary-foreground: oklch(0.21 0.006 285.885);
+  --muted: oklch(0.967 0.001 286.375);
+  --muted-foreground: oklch(0.552 0.016 285.938);
+  --accent: oklch(0.967 0.001 286.375);
+  --accent-foreground: oklch(0.21 0.006 285.885);
+  --destructive: oklch(0.577 0.245 27.325);
+  --border: oklch(0.92 0.004 286.32);
+  --input: oklch(0.92 0.004 286.32);
+  --ring: oklch(0.705 0.015 286.067);
+  --chart-1: oklch(0.646 0.222 41.116);
+  --chart-2: oklch(0.6 0.118 184.704);
+  --chart-3: oklch(0.398 0.07 227.392);
+  --chart-4: oklch(0.828 0.189 84.429);
+  --chart-5: oklch(0.769 0.188 70.08);
+  --sidebar: oklch(0.985 0 0);
+  --sidebar-foreground: oklch(0.141 0.005 285.823);
+  --sidebar-primary: oklch(0.21 0.006 285.885);
+  --sidebar-primary-foreground: oklch(0.985 0 0);
+  --sidebar-accent: oklch(0.967 0.001 286.375);
+  --sidebar-accent-foreground: oklch(0.21 0.006 285.885);
+  --sidebar-border: oklch(0.92 0.004 286.32);
+  --sidebar-ring: oklch(0.705 0.015 286.067);
+}
+
+.dark {
+  --background: oklch(0.141 0.005 285.823);
+  --foreground: oklch(0.985 0 0);
+  --card: oklch(0.21 0.006 285.885);
+  --card-foreground: oklch(0.985 0 0);
+  --popover: oklch(0.21 0.006 285.885);
+  --popover-foreground: oklch(0.985 0 0);
+  --primary: oklch(0.92 0.004 286.32);
+  --primary-foreground: oklch(0.21 0.006 285.885);
+  --secondary: oklch(0.274 0.006 286.033);
+  --secondary-foreground: oklch(0.985 0 0);
+  --muted: oklch(0.274 0.006 286.033);
+  --muted-foreground: oklch(0.705 0.015 286.067);
+  --accent: oklch(0.274 0.006 286.033);
+  --accent-foreground: oklch(0.985 0 0);
+  --destructive: oklch(0.704 0.191 22.216);
+  --border: oklch(1 0 0 / 10%);
+  --input: oklch(1 0 0 / 15%);
+  --ring: oklch(0.552 0.016 285.938);
+  --chart-1: oklch(0.488 0.243 264.376);
+  --chart-2: oklch(0.696 0.17 162.48);
+  --chart-3: oklch(0.769 0.188 70.08);
+  --chart-4: oklch(0.627 0.265 303.9);
+  --chart-5: oklch(0.645 0.246 16.439);
+  --sidebar: oklch(0.21 0.006 285.885);
+  --sidebar-foreground: oklch(0.985 0 0);
+  --sidebar-primary: oklch(0.488 0.243 264.376);
+  --sidebar-primary-foreground: oklch(0.985 0 0);
+  --sidebar-accent: oklch(0.274 0.006 286.033);
+  --sidebar-accent-foreground: oklch(0.985 0 0);
+  --sidebar-border: oklch(1 0 0 / 10%);
+  --sidebar-ring: oklch(0.552 0.016 285.938);
+}
+
+@layer base {
+  * {
+    @apply border-border outline-ring/50;
+  }
+  body {
+    @apply bg-background text-foreground;
+  }
+}
+
+```
+
+## app/layout.tsx
+
+```tsx
+import type { Metadata } from "next";
+import { MyRuntimeProvider } from "@/app/MyRuntimeProvider";
+
+import "./globals.css";
+
+export const metadata: Metadata = {
+  title: "Create Next App",
+  description: "Generated by create next app",
+};
+
+export default function RootLayout({
+  children,
+}: Readonly<{
+  children: React.ReactNode;
+}>) {
+  return (
+    <MyRuntimeProvider>
+      <html lang="en" className="h-dvh">
+        <body className="h-dvh font-sans">{children}</body>
+      </html>
+    </MyRuntimeProvider>
+  );
+}
+
+```
+
+## app/MyRuntimeProvider.tsx
+
+```tsx
+"use client";
+
+import {
+  ThreadMessageLike,
+  AppendMessage,
+  AssistantRuntimeProvider,
+  useExternalStoreRuntime,
+} from "@assistant-ui/react";
+import { useState } from "react";
+
+const convertMessage = (message: ThreadMessageLike) => {
+  return message;
+};
+
+export function MyRuntimeProvider({
+  children,
+}: Readonly<{
+  children: React.ReactNode;
+}>) {
+  const [messages, setMessages] = useState<readonly ThreadMessageLike[]>([
+    {
+      id: "msg-1",
+      createdAt: new Date("2024-01-01T10:00:00"),
+      role: "user",
+      content: [
+        {
+          type: "text",
+          text: "Tell me about climate change and its effects",
+        },
+      ],
+    },
+    {
+      id: "msg-2",
+      createdAt: new Date("2024-01-01T10:00:05"),
+      role: "assistant",
+      content: [
+        {
+          type: "text",
+          text: "Climate change refers to long-term shifts in global temperatures and weather patterns. Let me provide you with information about its causes and effects.",
+        },
+        {
+          type: "tool-call",
+          toolCallId: "call-1",
+          toolName: "search_research",
+          args: { query: "climate change causes" },
+          argsText: '{"query": "climate change causes"}',
+          result: {
+            sources: [
+              "https://climate.nasa.gov/causes/",
+              "https://www.ipcc.ch/report/ar6/wg1/",
+            ],
+          },
+          parentId: "research-climate-causes",
+        },
+        {
+          type: "source",
+          sourceType: "url",
+          id: "source-1",
+          url: "https://climate.nasa.gov/causes/",
+          title: "NASA: Climate Change Causes",
+          parentId: "research-climate-causes",
+        },
+        {
+          type: "source",
+          sourceType: "url",
+          id: "source-2",
+          url: "https://www.ipcc.ch/report/ar6/wg1/",
+          title: "IPCC Sixth Assessment Report",
+          parentId: "research-climate-causes",
+        },
+        {
+          type: "text",
+          text: "The main causes of climate change include:",
+          parentId: "research-climate-causes",
+        },
+        {
+          type: "text",
+          text: "1. **Greenhouse Gas Emissions**: The burning of fossil fuels releases CO2 and other greenhouse gases that trap heat in the atmosphere.",
+          parentId: "research-climate-causes",
+        },
+        {
+          type: "text",
+          text: "2. **Deforestation**: Removing forests reduces the Earth's capacity to absorb CO2.",
+          parentId: "research-climate-causes",
+        },
+        {
+          type: "text",
+          text: "Now, let me search for information about the effects of climate change:",
+        },
+        {
+          type: "tool-call",
+          toolCallId: "call-2",
+          toolName: "search_research",
+          args: { query: "climate change effects impacts" },
+          argsText: '{"query": "climate change effects impacts"}',
+          result: {
+            sources: [
+              "https://www.who.int/health-topics/climate-change",
+              "https://www.unep.org/facts-about-climate-emergency",
+            ],
+          },
+          parentId: "research-climate-effects",
+        },
+        {
+          type: "source",
+          sourceType: "url",
+          id: "source-3",
+          url: "https://www.who.int/health-topics/climate-change",
+          title: "WHO: Climate Change and Health",
+          parentId: "research-climate-effects",
+        },
+        {
+          type: "source",
+          sourceType: "url",
+          id: "source-4",
+          url: "https://www.unep.org/facts-about-climate-emergency",
+          title: "UNEP: Climate Emergency Facts",
+          parentId: "research-climate-effects",
+        },
+        {
+          type: "text",
+          text: "The major effects of climate change include:",
+          parentId: "research-climate-effects",
+        },
+        {
+          type: "text",
+          text: "• **Rising Sea Levels**: Melting ice caps and thermal expansion of oceans threaten coastal communities.",
+          parentId: "research-climate-effects",
+        },
+        {
+          type: "text",
+          text: "• **Extreme Weather Events**: More frequent and intense hurricanes, droughts, and heatwaves.",
+          parentId: "research-climate-effects",
+        },
+        {
+          type: "text",
+          text: "• **Ecosystem Disruption**: Changes in temperature and precipitation patterns affect biodiversity and agriculture.",
+          parentId: "research-climate-effects",
+        },
+        {
+          type: "text",
+          text: "In conclusion, climate change is one of the most pressing challenges facing humanity, requiring immediate action on both mitigation and adaptation strategies.",
+        },
+      ] as any, // Using any to bypass strict typing for demo purposes
+      status: { type: "complete", reason: "stop" },
+    },
+  ]);
+
+  const onNew = async (message: AppendMessage) => {
+    if (message.content.length !== 1 || message.content[0]?.type !== "text")
+      throw new Error("Only text content is supported");
+
+    const userMessage: ThreadMessageLike = {
+      id: `msg-user-${Date.now()}`,
+      createdAt: new Date(),
+      role: "user",
+      content: [{ type: "text", text: message.content[0].text }],
+    };
+    setMessages((currentMessages) => [...currentMessages, userMessage]);
+
+    // Simulate assistant response with parent IDs
+    await new Promise((resolve) => setTimeout(resolve, 1000));
+
+    const assistantMessage: ThreadMessageLike = {
+      id: `msg-assistant-${Date.now()}`,
+      createdAt: new Date(),
+      role: "assistant",
+      content: [
+        {
+          type: "text",
+          text: "I understand you want to know more. Let me research that for you.",
+        },
+        {
+          type: "tool-call",
+          toolCallId: `call-${Date.now()}`,
+          toolName: "search",
+          args: { query: "recent developments" },
+          argsText: '{"query": "recent developments"}',
+          result: { data: "Latest information found" },
+          parentId: "new-research",
+        },
+        {
+          type: "text",
+          text: "Based on my research:",
+          parentId: "new-research",
+        },
+        {
+          type: "text",
+          text: "Here's what I found about your query...",
+          parentId: "new-research",
+        },
+        {
+          type: "text",
+          text: "I hope this information helps!",
+        },
+      ] as any, // Using any to bypass strict typing for demo purposes
+      status: { type: "complete", reason: "stop" },
+    };
+    setMessages((currentMessages) => [...currentMessages, assistantMessage]);
+  };
+
+  const runtime = useExternalStoreRuntime<ThreadMessageLike>({
+    messages,
+    setMessages,
+    onNew,
+    convertMessage,
+  });
+
+  return (
+    <AssistantRuntimeProvider runtime={runtime}>
+      {children}
+    </AssistantRuntimeProvider>
+  );
+}
+
+```
+
+## app/page.tsx
+
+```tsx
+"use client";
+
+import { Thread } from "@/components/assistant-ui/thread";
+
+export default function Home() {
+  return (
+    <main className="h-dvh">
+      <Thread />
+    </main>
+  );
+}
+
+```
+
+## components.json
+
+```json
+{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "new-york",
+  "rsc": true,
+  "tsx": true,
+  "tailwind": {
+    "config": "",
+    "css": "app/globals.css",
+    "baseColor": "zinc",
+    "cssVariables": true,
+    "prefix": ""
+  },
+  "aliases": {
+    "components": "@/components",
+    "utils": "@/lib/utils",
+    "ui": "@/components/ui",
+    "lib": "@/lib",
+    "hooks": "@/hooks"
+  },
+  "iconLibrary": "lucide"
+}
+
+```
+
+## components/assistant-ui/markdown-text.tsx
+
+```tsx
+"use client";
+
+import "@assistant-ui/react-markdown/styles/dot.css";
+
+import {
+  CodeHeaderProps,
+  MarkdownTextPrimitive,
+  unstable_memoizeMarkdownComponents as memoizeMarkdownComponents,
+  useIsMarkdownCodeBlock,
+} from "@assistant-ui/react-markdown";
+import remarkGfm from "remark-gfm";
+import { FC, memo, useState } from "react";
+import { CheckIcon, CopyIcon } from "lucide-react";
+
+import { TooltipIconButton } from "@/components/assistant-ui/tooltip-icon-button";
+import { cn } from "@/lib/utils";
+
+const MarkdownTextImpl = () => {
+  return (
+    <MarkdownTextPrimitive
+      remarkPlugins={[remarkGfm]}
+      className="aui-md"
+      components={defaultComponents}
+    />
+  );
+};
+
+export const MarkdownText = memo(MarkdownTextImpl);
+
+const CodeHeader: FC<CodeHeaderProps> = ({ language, code }) => {
+  const { isCopied, copyToClipboard } = useCopyToClipboard();
+  const onCopy = () => {
+    if (!code || isCopied) return;
+    copyToClipboard(code);
+  };
+
+  return (
+    <div className="flex items-center justify-between gap-4 rounded-t-lg bg-zinc-900 px-4 py-2 text-sm font-semibold text-white">
+      <span className="lowercase [&>span]:text-xs">{language}</span>
+      <TooltipIconButton tooltip="Copy" onClick={onCopy}>
+        {!isCopied && <CopyIcon />}
+        {isCopied && <CheckIcon />}
+      </TooltipIconButton>
+    </div>
+  );
+};
+
+const useCopyToClipboard = ({
+  copiedDuration = 3000,
+}: {
+  copiedDuration?: number;
+} = {}) => {
+  const [isCopied, setIsCopied] = useState<boolean>(false);
+
+  const copyToClipboard = (value: string) => {
+    if (!value) return;
+
+    navigator.clipboard.writeText(value).then(() => {
+      setIsCopied(true);
+      setTimeout(() => setIsCopied(false), copiedDuration);
+    });
+  };
+
+  return { isCopied, copyToClipboard };
+};
+
+const defaultComponents = memoizeMarkdownComponents({
+  h1: ({ className, ...props }) => (
+    <h1
+      className={cn(
+        "mb-8 scroll-m-20 text-4xl font-extrabold tracking-tight last:mb-0",
+        className,
+      )}
+      {...props}
+    />
+  ),
+  h2: ({ className, ...props }) => (
+    <h2
+      className={cn(
+        "mb-4 mt-8 scroll-m-20 text-3xl font-semibold tracking-tight first:mt-0 last:mb-0",
+        className,
+      )}
+      {...props}
+    />
+  ),
+  h3: ({ className, ...props }) => (
+    <h3
+      className={cn(
+        "mb-4 mt-6 scroll-m-20 text-2xl font-semibold tracking-tight first:mt-0 last:mb-0",
+        className,
+      )}
+      {...props}
+    />
+  ),
+  h4: ({ className, ...props }) => (
+    <h4
+      className={cn(
+        "mb-4 mt-6 scroll-m-20 text-xl font-semibold tracking-tight first:mt-0 last:mb-0",
+        className,
+      )}
+      {...props}
+    />
+  ),
+  h5: ({ className, ...props }) => (
+    <h5
+      className={cn(
+        "my-4 text-lg font-semibold first:mt-0 last:mb-0",
+        className,
+      )}
+      {...props}
+    />
+  ),
+  h6: ({ className, ...props }) => (
+    <h6
+      className={cn("my-4 font-semibold first:mt-0 last:mb-0", className)}
+      {...props}
+    />
+  ),
+  p: ({ className, ...props }) => (
+    <p
+      className={cn("mb-5 mt-5 leading-7 first:mt-0 last:mb-0", className)}
+      {...props}
+    />
+  ),
+  a: ({ className, ...props }) => (
+    <a
+      className={cn(
+        "text-primary font-medium underline underline-offset-4",
+        className,
+      )}
+      {...props}
+    />
+  ),
+  blockquote: ({ className, ...props }) => (
+    <blockquote
+      className={cn("border-l-2 pl-6 italic", className)}
+      {...props}
+    />
+  ),
+  ul: ({ className, ...props }) => (
+    <ul
+      className={cn("my-5 ml-6 list-disc [&>li]:mt-2", className)}
+      {...props}
+    />
+  ),
+  ol: ({ className, ...props }) => (
+    <ol
+      className={cn("my-5 ml-6 list-decimal [&>li]:mt-2", className)}
+      {...props}
+    />
+  ),
+  hr: ({ className, ...props }) => (
+    <hr className={cn("my-5 border-b", className)} {...props} />
+  ),
+  table: ({ className, ...props }) => (
+    <table
+      className={cn(
+        "my-5 w-full border-separate border-spacing-0 overflow-y-auto",
+        className,
+      )}
+      {...props}
+    />
+  ),
+  th: ({ className, ...props }) => (
+    <th
+      className={cn(
+        "bg-muted px-4 py-2 text-left font-bold first:rounded-tl-lg last:rounded-tr-lg [&[align=center]]:text-center [&[align=right]]:text-right",
+        className,
+      )}
+      {...props}
+    />
+  ),
+  td: ({ className, ...props }) => (
+    <td
+      className={cn(
+        "border-b border-l px-4 py-2 text-left last:border-r [&[align=center]]:text-center [&[align=right]]:text-right",
+        className,
+      )}
+      {...props}
+    />
+  ),
+  tr: ({ className, ...props }) => (
+    <tr
+      className={cn(
+        "m-0 border-b p-0 first:border-t [&:last-child>td:first-child]:rounded-bl-lg [&:last-child>td:last-child]:rounded-br-lg",
+        className,
+      )}
+      {...props}
+    />
+  ),
+  sup: ({ className, ...props }) => (
+    <sup
+      className={cn("[&>a]:text-xs [&>a]:no-underline", className)}
+      {...props}
+    />
+  ),
+  pre: ({ className, ...props }) => (
+    <pre
+      className={cn(
+        "overflow-x-auto rounded-b-lg bg-black p-4 text-white",
+        className,
+      )}
+      {...props}
+    />
+  ),
+  code: function Code({ className, ...props }) {
+    const isCodeBlock = useIsMarkdownCodeBlock();
+    return (
+      <code
+        className={cn(
+          !isCodeBlock && "bg-muted rounded border font-semibold",
+          className,
+        )}
+        {...props}
+      />
+    );
+  },
+  CodeHeader,
+});
+
+```
+
+## components/assistant-ui/thread.tsx
+
+```tsx
+import {
+  ActionBarPrimitive,
+  BranchPickerPrimitive,
+  ComposerPrimitive,
+  MessagePrimitive,
+  ThreadPrimitive,
+} from "@assistant-ui/react";
+import type { FC, PropsWithChildren } from "react";
+import {
+  ArrowDownIcon,
+  CheckIcon,
+  ChevronLeftIcon,
+  ChevronRightIcon,
+  CopyIcon,
+  PencilIcon,
+  RefreshCwIcon,
+  SendHorizontalIcon,
+  ChevronDownIcon,
+  ChevronUpIcon,
+} from "lucide-react";
+import { cn } from "@/lib/utils";
+
+import { Button } from "@/components/ui/button";
+import { MarkdownText } from "@/components/assistant-ui/markdown-text";
+import { TooltipIconButton } from "@/components/assistant-ui/tooltip-icon-button";
+import { useState } from "react";
+
+export const Thread: FC = () => {
+  return (
+    <ThreadPrimitive.Root
+      className="bg-background box-border flex h-full flex-col overflow-hidden"
+      style={{
+        ["--thread-max-width" as string]: "42rem",
+      }}
+    >
+      <ThreadPrimitive.Viewport className="flex h-full flex-col items-center overflow-y-scroll scroll-smooth bg-inherit px-4 pt-8">
+        <ThreadWelcome />
+
+        <ThreadPrimitive.Messages
+          components={{
+            UserMessage: UserMessage,
+            EditComposer: EditComposer,
+            AssistantMessage: AssistantMessage,
+          }}
+        />
+
+        <ThreadPrimitive.If empty={false}>
+          <div className="min-h-8 flex-grow" />
+        </ThreadPrimitive.If>
+
+        <div className="sticky bottom-0 mt-3 flex w-full max-w-[var(--thread-max-width)] flex-col items-center justify-end rounded-t-lg bg-inherit pb-4">
+          <ThreadScrollToBottom />
+          <Composer />
+        </div>
+      </ThreadPrimitive.Viewport>
+    </ThreadPrimitive.Root>
+  );
+};
+
+const ThreadScrollToBottom: FC = () => {
+  return (
+    <ThreadPrimitive.ScrollToBottom asChild>
+      <TooltipIconButton
+        tooltip="Scroll to bottom"
+        variant="outline"
+        className="absolute -top-8 rounded-full disabled:invisible"
+      >
+        <ArrowDownIcon />
+      </TooltipIconButton>
+    </ThreadPrimitive.ScrollToBottom>
+  );
+};
+
+const ThreadWelcome: FC = () => {
+  return (
+    <ThreadPrimitive.Empty>
+      <div className="flex w-full max-w-[var(--thread-max-width)] flex-grow flex-col">
+        <div className="flex w-full flex-grow flex-col items-center justify-center">
+          <p className="mt-4 font-medium">Parent ID Grouping Demo</p>
+          <p className="text-muted-foreground mt-2 text-sm">
+            This example demonstrates how message parts can be grouped by parent
+            ID
+          </p>
+        </div>
+        <ThreadWelcomeSuggestions />
+      </div>
+    </ThreadPrimitive.Empty>
+  );
+};
+
+const ThreadWelcomeSuggestions: FC = () => {
+  return (
+    <div className="mt-3 flex w-full items-stretch justify-center gap-4">
+      <ThreadPrimitive.Suggestion
+        className="hover:bg-muted/80 flex max-w-sm grow basis-0 flex-col items-center justify-center rounded-lg border p-3 transition-colors ease-in"
+        prompt="Tell me more about this"
+        method="replace"
+        autoSend
+      >
+        <span className="line-clamp-2 text-ellipsis text-sm font-semibold">
+          Tell me more about this
+        </span>
+      </ThreadPrimitive.Suggestion>
+      <ThreadPrimitive.Suggestion
+        className="hover:bg-muted/80 flex max-w-sm grow basis-0 flex-col items-center justify-center rounded-lg border p-3 transition-colors ease-in"
+        prompt="What are the latest updates?"
+        method="replace"
+        autoSend
+      >
+        <span className="line-clamp-2 text-ellipsis text-sm font-semibold">
+          What are the latest updates?
+        </span>
+      </ThreadPrimitive.Suggestion>
+    </div>
+  );
+};
+
+const Composer: FC = () => {
+  return (
+    <ComposerPrimitive.Root className="focus-within:border-ring/20 flex w-full flex-wrap items-end rounded-lg border bg-inherit px-2.5 shadow-sm transition-colors ease-in">
+      <ComposerPrimitive.Input
+        rows={1}
+        autoFocus
+        placeholder="Write a message..."
+        className="placeholder:text-muted-foreground max-h-40 flex-grow resize-none border-none bg-transparent px-2 py-4 text-sm outline-none focus:ring-0 disabled:cursor-not-allowed"
+      />
+      <ComposerAction />
+    </ComposerPrimitive.Root>
+  );
+};
+
+const ComposerAction: FC = () => {
+  return (
+    <>
+      <ThreadPrimitive.If running={false}>
+        <ComposerPrimitive.Send asChild>
+          <TooltipIconButton
+            tooltip="Send"
+            variant="default"
+            className="my-2.5 size-8 p-2 transition-opacity ease-in"
+          >
+            <SendHorizontalIcon />
+          </TooltipIconButton>
+        </ComposerPrimitive.Send>
+      </ThreadPrimitive.If>
+      <ThreadPrimitive.If running>
+        <ComposerPrimitive.Cancel asChild>
+          <TooltipIconButton
+            tooltip="Cancel"
+            variant="default"
+            className="my-2.5 size-8 p-2 transition-opacity ease-in"
+          >
+            <CircleStopIcon />
+          </TooltipIconButton>
+        </ComposerPrimitive.Cancel>
+      </ThreadPrimitive.If>
+    </>
+  );
+};
+
+const UserMessage: FC = () => {
+  return (
+    <MessagePrimitive.Root className="grid w-full max-w-[var(--thread-max-width)] auto-rows-auto grid-cols-[minmax(72px,1fr)_auto] gap-y-2 py-4 [&:where(>*)]:col-start-2">
+      <UserActionBar />
+
+      <div className="bg-muted text-foreground col-start-2 row-start-2 max-w-[calc(var(--thread-max-width)*0.8)] break-words rounded-3xl px-5 py-2.5">
+        <MessagePrimitive.Parts />
+      </div>
+
+      <BranchPicker className="col-span-full col-start-1 row-start-3 -mr-1 justify-end" />
+    </MessagePrimitive.Root>
+  );
+};
+
+const UserActionBar: FC = () => {
+  return (
+    <ActionBarPrimitive.Root
+      hideWhenRunning
+      autohide="not-last"
+      className="col-start-1 row-start-2 mr-3 mt-2.5 flex flex-col items-end"
+    >
+      <ActionBarPrimitive.Edit asChild>
+        <TooltipIconButton tooltip="Edit">
+          <PencilIcon />
+        </TooltipIconButton>
+      </ActionBarPrimitive.Edit>
+    </ActionBarPrimitive.Root>
+  );
+};
+
+const EditComposer: FC = () => {
+  return (
+    <ComposerPrimitive.Root className="bg-muted my-4 flex w-full max-w-[var(--thread-max-width)] flex-col gap-2 rounded-xl">
+      <ComposerPrimitive.Input className="text-foreground flex h-8 w-full resize-none bg-transparent p-4 pb-0 outline-none" />
+
+      <div className="mx-3 mb-3 flex items-center justify-center gap-2 self-end">
+        <ComposerPrimitive.Cancel asChild>
+          <Button variant="ghost">Cancel</Button>
+        </ComposerPrimitive.Cancel>
+        <ComposerPrimitive.Send asChild>
+          <Button>Send</Button>
+        </ComposerPrimitive.Send>
+      </div>
+    </ComposerPrimitive.Root>
+  );
+};
+
+// Custom Group component for parent ID grouping
+const ParentIdGroup: FC<
+  PropsWithChildren<{ groupKey: string | undefined; indices: number[] }>
+> = ({ groupKey, indices, children }) => {
+  const [isCollapsed, setIsCollapsed] = useState(false);
+
+  if (!groupKey) {
+    // Ungrouped parts - just render them directly
+    return <>{children}</>;
+  }
+
+  return (
+    <div className="border-border/50 bg-muted/20 my-2 overflow-hidden rounded-lg border">
+      <button
+        onClick={() => setIsCollapsed(!isCollapsed)}
+        className="hover:bg-muted/40 flex w-full items-center justify-between px-4 py-2 text-sm font-medium transition-colors"
+      >
+        <span className="flex items-center gap-2">
+          <span className="text-muted-foreground">Research Group:</span>
+          <span className="text-foreground">
+            {groupKey === "research-climate-causes" && "Climate Change Causes"}
+            {groupKey === "research-climate-effects" &&
+              "Climate Change Effects"}
+            {groupKey === "new-research" && "Recent Research"}
+            {![
+              "research-climate-causes",
+              "research-climate-effects",
+              "new-research",
+            ].includes(groupKey) && groupKey}
+          </span>
+          <span className="text-muted-foreground text-xs">
+            ({indices.length} parts)
+          </span>
+        </span>
+        {isCollapsed ? (
+          <ChevronDownIcon className="h-4 w-4" />
+        ) : (
+          <ChevronUpIcon className="h-4 w-4" />
+        )}
+      </button>
+      {!isCollapsed && <div className="space-y-2 px-4 py-2">{children}</div>}
+    </div>
+  );
+};
+
+const AssistantMessage: FC = () => {
+  return (
+    <MessagePrimitive.Root className="relative grid w-full max-w-[var(--thread-max-width)] grid-cols-[auto_auto_1fr] grid-rows-[auto_1fr] py-4">
+      <div className="text-foreground col-span-2 col-start-2 row-start-1 my-1.5 max-w-[calc(var(--thread-max-width)*0.8)] break-words leading-7">
+        <MessagePrimitive.Unstable_PartsGroupedByParentId
+          components={{
+            Text: MarkdownText,
+            Group: ParentIdGroup,
+            Source: ({ url, title }) => (
+              <div className="text-muted-foreground text-sm">
+                <a
+                  href={url}
+                  target="_blank"
+                  rel="noopener noreferrer"
+                  className="hover:underline"
+                >
+                  📄 {title || url}
+                </a>
+              </div>
+            ),
+            tools: {
+              Fallback: ({ toolName, args, result }) => (
+                <div className="bg-muted/40 my-1 rounded-md p-2 text-sm">
+                  <div className="text-muted-foreground font-medium">
+                    🔧 {toolName}
+                  </div>
+                  <div className="text-muted-foreground mt-1 text-xs">
+                    <details>
+                      <summary className="cursor-pointer">View details</summary>
+                      <pre className="mt-2 overflow-x-auto">
+                        {JSON.stringify({ args, result }, null, 2)}
+                      </pre>
+                    </details>
+                  </div>
+                </div>
+              ),
+            },
+          }}
+        />
+      </div>
+
+      <AssistantActionBar />
+
+      <BranchPicker className="col-start-2 row-start-2 -ml-2 mr-2" />
+    </MessagePrimitive.Root>
+  );
+};
+
+const AssistantActionBar: FC = () => {
+  return (
+    <ActionBarPrimitive.Root
+      hideWhenRunning
+      autohide="not-last"
+      autohideFloat="single-branch"
+      className="text-muted-foreground data-[floating]:bg-background col-start-3 row-start-2 -ml-1 flex gap-1 data-[floating]:absolute data-[floating]:rounded-md data-[floating]:border data-[floating]:p-1 data-[floating]:shadow-sm"
+    >
+      <ActionBarPrimitive.Copy asChild>
+        <TooltipIconButton tooltip="Copy">
+          <MessagePrimitive.If copied>
+            <CheckIcon />
+          </MessagePrimitive.If>
+          <MessagePrimitive.If copied={false}>
+            <CopyIcon />
+          </MessagePrimitive.If>
+        </TooltipIconButton>
+      </ActionBarPrimitive.Copy>
+      <ActionBarPrimitive.Reload asChild>
+        <TooltipIconButton tooltip="Refresh">
+          <RefreshCwIcon />
+        </TooltipIconButton>
+      </ActionBarPrimitive.Reload>
+    </ActionBarPrimitive.Root>
+  );
+};
+
+const BranchPicker: FC<BranchPickerPrimitive.Root.Props> = ({
+  className,
+  ...rest
+}) => {
+  return (
+    <BranchPickerPrimitive.Root
+      hideWhenSingleBranch
+      className={cn(
+        "text-muted-foreground inline-flex items-center text-xs",
+        className,
+      )}
+      {...rest}
+    >
+      <BranchPickerPrimitive.Previous asChild>
+        <TooltipIconButton tooltip="Previous">
+          <ChevronLeftIcon />
+        </TooltipIconButton>
+      </BranchPickerPrimitive.Previous>
+      <span className="font-medium">
+        <BranchPickerPrimitive.Number /> / <BranchPickerPrimitive.Count />
+      </span>
+      <BranchPickerPrimitive.Next asChild>
+        <TooltipIconButton tooltip="Next">
+          <ChevronRightIcon />
+        </TooltipIconButton>
+      </BranchPickerPrimitive.Next>
+    </BranchPickerPrimitive.Root>
+  );
+};
+
+const CircleStopIcon = () => {
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      viewBox="0 0 16 16"
+      fill="currentColor"
+      width="16"
+      height="16"
+    >
+      <rect width="10" height="10" x="3" y="3" rx="2" />
+    </svg>
+  );
+};
+
+```
+
+## components/assistant-ui/tooltip-icon-button.tsx
+
+```tsx
+"use client";
+
+import { ComponentPropsWithoutRef, forwardRef } from "react";
+
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipTrigger,
+} from "@/components/ui/tooltip";
+import { Button } from "@/components/ui/button";
+import { cn } from "@/lib/utils";
+
+export type TooltipIconButtonProps = ComponentPropsWithoutRef<typeof Button> & {
+  tooltip: string;
+  side?: "top" | "bottom" | "left" | "right";
+};
+
+export const TooltipIconButton = forwardRef<
+  HTMLButtonElement,
+  TooltipIconButtonProps
+>(({ children, tooltip, side = "bottom", className, ...rest }, ref) => {
+  return (
+    <Tooltip>
+      <TooltipTrigger asChild>
+        <Button
+          variant="ghost"
+          size="icon"
+          {...rest}
+          className={cn("size-6 p-1", className)}
+          ref={ref}
+        >
+          {children}
+          <span className="sr-only">{tooltip}</span>
+        </Button>
+      </TooltipTrigger>
+      <TooltipContent side={side}>{tooltip}</TooltipContent>
+    </Tooltip>
+  );
+});
+
+TooltipIconButton.displayName = "TooltipIconButton";
+
+```
+
+## components/ui/button.tsx
+
+```tsx
+"use client";
+
+import * as React from "react";
+import { Slot } from "@radix-ui/react-slot";
+import { cva, type VariantProps } from "class-variance-authority";
+
+import { cn } from "@/lib/utils";
+
+const buttonVariants = cva(
+  "inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-md text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring disabled:pointer-events-none disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:size-4 [&_svg]:shrink-0",
+  {
+    variants: {
+      variant: {
+        default:
+          "bg-primary text-primary-foreground shadow hover:bg-primary/90",
+        destructive:
+          "bg-destructive text-destructive-foreground shadow-sm hover:bg-destructive/90",
+        outline:
+          "border border-input bg-background shadow-sm hover:bg-accent hover:text-accent-foreground",
+        secondary:
+          "bg-secondary text-secondary-foreground shadow-sm hover:bg-secondary/80",
+        ghost: "hover:bg-accent hover:text-accent-foreground",
+        link: "text-primary underline-offset-4 hover:underline",
+      },
+      size: {
+        default: "h-9 px-4 py-2",
+        sm: "h-8 rounded-md px-3 text-xs",
+        lg: "h-10 rounded-md px-8",
+        icon: "h-9 w-9",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+      size: "default",
+    },
+  },
+);
+
+export interface ButtonProps
+  extends React.ButtonHTMLAttributes<HTMLButtonElement>,
+    VariantProps<typeof buttonVariants> {
+  asChild?: boolean;
+}
+
+const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
+  ({ className, variant, size, asChild = false, ...props }, ref) => {
+    const Comp = asChild ? Slot : "button";
+    return (
+      <Comp
+        className={cn(buttonVariants({ variant, size, className }))}
+        ref={ref}
+        {...props}
+      />
+    );
+  },
+);
+Button.displayName = "Button";
+
+export { Button, buttonVariants };
+
+```
+
+## components/ui/tooltip.tsx
+
+```tsx
+"use client";
+
+import * as React from "react";
+import * as TooltipPrimitive from "@radix-ui/react-tooltip";
+
+import { cn } from "@/lib/utils";
+
+function TooltipProvider({
+  delayDuration = 0,
+  ...props
+}: React.ComponentProps<typeof TooltipPrimitive.Provider>) {
+  return (
+    <TooltipPrimitive.Provider
+      data-slot="tooltip-provider"
+      delayDuration={delayDuration}
+      {...props}
+    />
+  );
+}
+
+function Tooltip({
+  ...props
+}: React.ComponentProps<typeof TooltipPrimitive.Root>) {
+  return (
+    <TooltipProvider>
+      <TooltipPrimitive.Root data-slot="tooltip" {...props} />
+    </TooltipProvider>
+  );
+}
+
+function TooltipTrigger({
+  ...props
+}: React.ComponentProps<typeof TooltipPrimitive.Trigger>) {
+  return <TooltipPrimitive.Trigger data-slot="tooltip-trigger" {...props} />;
+}
+
+function TooltipContent({
+  className,
+  sideOffset = 0,
+  children,
+  ...props
+}: React.ComponentProps<typeof TooltipPrimitive.Content>) {
+  return (
+    <TooltipPrimitive.Portal>
+      <TooltipPrimitive.Content
+        data-slot="tooltip-content"
+        sideOffset={sideOffset}
+        className={cn(
+          "bg-primary text-primary-foreground animate-in fade-in-0 zoom-in-95 data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 z-50 w-fit origin-[--radix-tooltip-content-transform-origin] text-balance rounded-md px-3 py-1.5 text-xs",
+          className,
+        )}
+        {...props}
+      >
+        {children}
+        <TooltipPrimitive.Arrow className="bg-primary fill-primary z-50 size-2.5 translate-y-[calc(-50%_-_2px)] rotate-45 rounded-[2px]" />
+      </TooltipPrimitive.Content>
+    </TooltipPrimitive.Portal>
+  );
+}
+
+export { Tooltip, TooltipTrigger, TooltipContent, TooltipProvider };
+
+```
+
+## eslint.config.ts
+
+```typescript
+export { default } from "@assistant-ui/x-buildutils/eslint";
+
+```
+
+## lib/utils.ts
+
+```typescript
+import { clsx, type ClassValue } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}
+
+```
+
+## next.config.ts
+
+```typescript
+import type { NextConfig } from "next";
+
+const nextConfig: NextConfig = {
+  /* config options here */
+};
+
+export default nextConfig;
+
+```
+
+## package.json
+
+```json
+{
+  "name": "with-parent-id-grouping",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "dev": "next dev --turbo",
+    "build": "next build",
+    "start": "next start",
+    "lint": "next lint"
+  },
+  "dependencies": {
+    "@ai-sdk/openai": "^1.3.22",
+    "@assistant-ui/react": "workspace:*",
+    "@assistant-ui/react-markdown": "workspace:*",
+    "@radix-ui/react-slot": "^1.2.3",
+    "@radix-ui/react-tooltip": "^1.2.7",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "lucide-react": "^0.535.0",
+    "next": "15.4.5",
+    "react": "19.1.1",
+    "react-dom": "19.1.1",
+    "remark-gfm": "^4.0.1",
+    "tailwind-merge": "^3.3.1",
+    "tw-animate-css": "^1.3.6"
+  },
+  "devDependencies": {
+    "@assistant-ui/x-buildutils": "workspace:*",
+    "@types/node": "^24",
+    "@types/react": "^19",
+    "@types/react-dom": "^19",
+    "eslint": "^9",
+    "eslint-config-next": "15.4.5",
+    "postcss": "^8",
+    "tailwindcss": "^4.1.11",
+    "typescript": "^5"
+  }
+}
+
+```
+
+## README.md
+
+```markdown
+# Parent ID Grouping Example
+
+This example demonstrates how to use the parent ID feature in assistant-ui to group related message parts together.
+
+## Features
+
+- **Parent ID Support**: Message parts can have a `parentId` field that groups them together
+- **Visual Grouping**: Related parts are displayed in collapsible groups
+- **Custom Group Component**: The example shows how to create a custom Group component that:
+  - Shows grouped parts in a bordered container
+  - Provides expand/collapse functionality
+  - Displays meaningful labels for each group
+  - Leaves ungrouped parts (without parentId) as-is
+
+## How it works
+
+1. **Message Structure**: The example uses the external store runtime with predefined messages that include parts with `parentId` fields:
+   ```typescript
+   {
+     type: "text",
+     text: "Some related text",
+     parentId: "research-climate-causes"
+   }
+   ```
+
+2. **Grouping Component**: Uses `MessagePrimitive.Unstable_PartsGroupedByParentId` which automatically:
+   - Groups parts by their `parentId`
+   - Maintains order based on first occurrence
+   - Places ungrouped parts after grouped ones
+
+3. **Custom Rendering**: The `ParentIdGroup` component provides:
+   - Collapsible sections for each group
+   - Custom styling with borders and backgrounds
+   - Meaningful labels based on the parent ID
+
+## Running the Example
+
+```bash
+# Install dependencies
+npm install
+
+# Run the development server
+npm run dev
+```
+
+Open [http://localhost:3000](http://localhost:3000) to see the example.
+
+## Key Components
+
+- `MyRuntimeProvider.tsx`: Sets up the external store with dummy messages containing parent IDs
+- `thread.tsx`: Contains the custom `ParentIdGroup` component and uses `Unstable_PartsGroupedByParentId`
+
+## Use Cases
+
+This pattern is useful for:
+- Grouping research sources with their related findings
+- Organizing multi-step tool executions
+- Creating hierarchical content structures
+- Showing related content in collapsible sections
+```
+
+## tsconfig.json
+
+```json
+{
+  "extends": "@assistant-ui/x-buildutils/ts/base",
+  "compilerOptions": {
+    "target": "ES6",
+    "module": "ESNext",
+    "incremental": true,
+    "plugins": [
+      {
+        "name": "next"
+      }
+    ],
+    "allowJs": true,
+    "strictNullChecks": true,
+    "jsx": "preserve",
+    "paths": {
+      "@/*": ["./*"],
+      "@assistant-ui/*": ["../../packages/*/src"],
+      "@assistant-ui/react/*": ["../../packages/react/src/*"],
+      "assistant-stream": ["../../packages/assistant-stream/src"],
+      "assistant-stream/*": ["../../packages/assistant-stream/src/*"]
+    }
+  },
+  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
+  "exclude": ["node_modules"]
+}
+
+```
+