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

package/.docs/organized/code-examples/with-virtualized-thread.md

@@ -0,0 +1,656 @@
+# Example: with-virtualized-thread
+
+## app/globals.css
+
+```css
+@import "tailwindcss";
+@import "tw-animate-css";
+
+@source "../../../packages/ui/src";
+
+@custom-variant dark (&:is(.dark *));
+
+@theme inline {
+  --radius-sm: calc(var(--radius) - 4px);
+  --radius-md: calc(var(--radius) - 2px);
+  --radius-lg: var(--radius);
+  --radius-xl: calc(var(--radius) + 4px);
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  --color-card: var(--card);
+  --color-card-foreground: var(--card-foreground);
+  --color-popover: var(--popover);
+  --color-popover-foreground: var(--popover-foreground);
+  --color-primary: var(--primary);
+  --color-primary-foreground: var(--primary-foreground);
+  --color-secondary: var(--secondary);
+  --color-secondary-foreground: var(--secondary-foreground);
+  --color-muted: var(--muted);
+  --color-muted-foreground: var(--muted-foreground);
+  --color-accent: var(--accent);
+  --color-accent-foreground: var(--accent-foreground);
+  --color-destructive: var(--destructive);
+  --color-border: var(--border);
+  --color-input: var(--input);
+  --color-ring: var(--ring);
+  --color-chart-1: var(--chart-1);
+  --color-chart-2: var(--chart-2);
+  --color-chart-3: var(--chart-3);
+  --color-chart-4: var(--chart-4);
+  --color-chart-5: var(--chart-5);
+  --color-sidebar: var(--sidebar);
+  --color-sidebar-foreground: var(--sidebar-foreground);
+  --color-sidebar-primary: var(--sidebar-primary);
+  --color-sidebar-primary-foreground: var(--sidebar-primary-foreground);
+  --color-sidebar-accent: var(--sidebar-accent);
+  --color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
+  --color-sidebar-border: var(--sidebar-border);
+  --color-sidebar-ring: var(--sidebar-ring);
+}
+
+: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: "assistant-ui virtualized thread",
+  description: "Long threads with @tanstack/react-virtual",
+};
+
+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 {
+  AssistantRuntimeProvider,
+  type AppendMessage,
+  type ThreadMessageLike,
+  useExternalStoreRuntime,
+} from "@assistant-ui/react";
+import { useRef, useState, type ReactNode } from "react";
+import { generateSeedMessages, REPLY_CHUNKS } from "./seed-messages";
+
+const convertMessage = (message: ThreadMessageLike) => message;
+
+export function MyRuntimeProvider({ children }: { children: ReactNode }) {
+  const [messages, setMessages] =
+    useState<readonly ThreadMessageLike[]>(generateSeedMessages);
+  const [isRunning, setIsRunning] = useState(false);
+  const nextIdRef = useRef(0);
+
+  const onNew = async (message: AppendMessage) => {
+    if (message.content[0]?.type !== "text")
+      throw new Error("Only text content is supported");
+    const userText = message.content[0].text;
+    const id = `reply-${nextIdRef.current++}`;
+
+    setMessages((current) => [
+      ...current,
+      { id: `${id}-user`, role: "user", content: userText },
+    ]);
+    setIsRunning(true);
+    try {
+      for (let i = 1; i <= REPLY_CHUNKS.length; i++) {
+        await new Promise((resolve) => setTimeout(resolve, 40));
+        const content = REPLY_CHUNKS.slice(0, i).join("");
+        setMessages((current) =>
+          current.at(-1)?.id === id
+            ? [...current.slice(0, -1), { id, role: "assistant", content }]
+            : [...current, { id, role: "assistant", content }],
+        );
+      }
+    } finally {
+      setIsRunning(false);
+    }
+  };
+
+  const runtime = useExternalStoreRuntime<ThreadMessageLike>({
+    messages,
+    setMessages,
+    isRunning,
+    onNew,
+    convertMessage,
+  });
+
+  return (
+    <AssistantRuntimeProvider runtime={runtime}>
+      {children}
+    </AssistantRuntimeProvider>
+  );
+}
+
+```
+
+## app/page.tsx
+
+```tsx
+"use client";
+
+import { VirtualizedThread } from "@/app/VirtualizedThread";
+
+export default function Home() {
+  return (
+    <main className="h-dvh">
+      <VirtualizedThread />
+    </main>
+  );
+}
+
+```
+
+## app/seed-messages.ts
+
+```typescript
+import type { ThreadMessageLike } from "@assistant-ui/react";
+
+const SEED_COUNT = 500;
+
+const SNIPPETS = [
+  "Virtualization keeps the DOM small by only mounting the messages near the viewport. Everything else is represented by empty space, so scrolling through thousands of messages stays cheap.",
+  "Here is a list of things to keep in mind:\n\n- only mount what is visible\n- measure real heights after mount\n- keep React keys stable across index shifts",
+  "```ts\nconst virtualizer = useVirtualizer({\n  count: turns.length,\n  estimateSize: () => 200,\n  getScrollElement: () => scrollerRef.current,\n});\n```",
+  "Padding spacers keep the mounted items in normal document flow, which means CSS like `position: sticky` and the regular kit styling keep working inside each message.",
+  "Auto-follow works by observing the content size with a ResizeObserver and re-pinning the scroller to the bottom while the user has not scrolled away.",
+];
+
+export const generateSeedMessages = (): ThreadMessageLike[] =>
+  Array.from({ length: SEED_COUNT }, (_, i) => ({
+    id: `seed-${i}`,
+    role: i % 2 === 0 ? ("user" as const) : ("assistant" as const),
+    content:
+      i % 2 === 0
+        ? `Question ${i / 2 + 1}: tell me more about long threads.`
+        : SNIPPETS.slice(0, (i % 3) + 1).join("\n\n"),
+  }));
+
+export const REPLY_CHUNKS =
+  "Sure! This reply is streamed chunk by chunk so you can watch the thread follow the newest tokens. Scroll up at any point and the view stops following until you return to the bottom or press the scroll to bottom button. The reply is intentionally long enough to grow past a single viewport so the auto-follow behavior is easy to observe while it streams in."
+    .split(" ")
+    .map((word) => `${word} `);
+
+```
+
+## app/VirtualizedThread.tsx
+
+```tsx
+"use client";
+
+import { MarkdownText } from "@/components/assistant-ui/markdown-text";
+import {
+  ComposerPrimitive,
+  MessagePrimitive,
+  ThreadPrimitive,
+  useAuiState,
+} from "@assistant-ui/react";
+import { useVirtualizer } from "@tanstack/react-virtual";
+import { ArrowDownIcon, SendHorizontalIcon } from "lucide-react";
+import {
+  type ComponentProps,
+  type FC,
+  useCallback,
+  useEffect,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
+
+const ESTIMATED_TURN_HEIGHT = 200;
+const AT_BOTTOM_THRESHOLD = 4;
+
+type MessageComponents = ComponentProps<
+  typeof ThreadPrimitive.MessageByIndex
+>["components"];
+
+type Turn = { id: string; indices: number[] };
+
+const buildTurns = (signature: string): Turn[] => {
+  if (!signature) return [];
+  const turns: Turn[] = [];
+  for (const row of signature.split("\n")) {
+    const firstColon = row.indexOf(":");
+    const secondColon = row.indexOf(":", firstColon + 1);
+    const index = Number(row.slice(0, firstColon));
+    const role = row.slice(firstColon + 1, secondColon);
+    const id = row.slice(secondColon + 1);
+    const last = turns.at(-1);
+    if (role === "user" || !last) turns.push({ id, indices: [index] });
+    else last.indices.push(index);
+  }
+  return turns;
+};
+
+const UserMessage: FC = () => (
+  <MessagePrimitive.Root
+    data-role="user"
+    className="bg-muted ml-auto w-fit max-w-[80%] rounded-xl px-4 py-2"
+  >
+    <MessagePrimitive.Parts />
+  </MessagePrimitive.Root>
+);
+
+const AssistantMessage: FC = () => (
+  <MessagePrimitive.Root
+    data-role="assistant"
+    className="text-foreground leading-relaxed"
+  >
+    <MessagePrimitive.Parts components={{ Text: MarkdownText }} />
+  </MessagePrimitive.Root>
+);
+
+const MESSAGE_COMPONENTS: MessageComponents = { UserMessage, AssistantMessage };
+
+const Composer: FC = () => (
+  <ComposerPrimitive.Root className="border-border bg-background focus-within:ring-ring flex items-end rounded-xl border shadow-sm focus-within:ring-1">
+    <ComposerPrimitive.Input
+      placeholder="Send a message to watch the thread follow the stream"
+      className="placeholder:text-muted-foreground max-h-40 flex-1 resize-none bg-transparent px-4 py-3 text-sm outline-none"
+      rows={1}
+      autoFocus
+    />
+    <ComposerPrimitive.Send
+      aria-label="Send"
+      className="text-muted-foreground hover:text-foreground m-2 rounded-lg p-2 transition-colors disabled:opacity-40"
+    >
+      <SendHorizontalIcon className="size-4" />
+    </ComposerPrimitive.Send>
+  </ComposerPrimitive.Root>
+);
+
+export const VirtualizedThread: FC = () => {
+  const signature = useAuiState((s) =>
+    s.thread.messages.map((m, i) => `${i}:${m.role}:${m.id}`).join("\n"),
+  );
+  const isRunning = useAuiState((s) => s.thread.isRunning);
+  const turns = useMemo(() => buildTurns(signature), [signature]);
+
+  const scrollerRef = useRef<HTMLDivElement>(null);
+  const contentRef = useRef<HTMLDivElement>(null);
+  const stickyRef = useRef(true);
+  const [isAtBottom, setIsAtBottom] = useState(true);
+
+  const virtualizer = useVirtualizer({
+    count: turns.length,
+    estimateSize: () => ESTIMATED_TURN_HEIGHT,
+    getItemKey: (index) => turns[index]!.id,
+    getScrollElement: () => scrollerRef.current,
+    initialRect: { height: 800, width: 800 },
+    overscan: 4,
+    scrollToFn: (offset, _options, instance) => {
+      const el = instance.scrollElement;
+      if (!el) return;
+      if (stickyRef.current) {
+        const maxScroll = el.scrollHeight - el.clientHeight;
+        if (
+          maxScroll - el.scrollTop <= AT_BOTTOM_THRESHOLD &&
+          offset < maxScroll
+        )
+          return;
+      }
+      el.scrollTo(0, offset);
+    },
+  });
+
+  const jumpToBottom = useCallback(() => {
+    stickyRef.current = true;
+    if (turns.length > 0)
+      virtualizer.scrollToIndex(turns.length - 1, { align: "end" });
+    requestAnimationFrame(() => {
+      const el = scrollerRef.current;
+      if (el && stickyRef.current) el.scrollTop = el.scrollHeight;
+    });
+  }, [turns.length, virtualizer]);
+
+  useEffect(() => {
+    const el = scrollerRef.current;
+    if (!el) return;
+    let lastScrollTop = el.scrollTop;
+    let lastScrollHeight = el.scrollHeight;
+    let lastClientHeight = el.clientHeight;
+    const onScroll = () => {
+      const atBottom =
+        el.scrollHeight - el.scrollTop - el.clientHeight <= AT_BOTTOM_THRESHOLD;
+      if (atBottom) {
+        stickyRef.current = true;
+      } else if (
+        el.scrollTop < lastScrollTop &&
+        el.scrollHeight === lastScrollHeight &&
+        Math.abs(el.clientHeight - lastClientHeight) <= 1
+      ) {
+        stickyRef.current = false;
+      }
+      lastScrollTop = el.scrollTop;
+      lastScrollHeight = el.scrollHeight;
+      lastClientHeight = el.clientHeight;
+      setIsAtBottom(atBottom);
+    };
+    const onWheel = (e: WheelEvent) => {
+      if (e.deltaY < 0) stickyRef.current = false;
+    };
+    const disarm = () => {
+      stickyRef.current = false;
+    };
+    el.addEventListener("scroll", onScroll, { passive: true });
+    el.addEventListener("wheel", onWheel, { passive: true });
+    el.addEventListener("touchmove", disarm, { passive: true });
+    return () => {
+      el.removeEventListener("scroll", onScroll);
+      el.removeEventListener("wheel", onWheel);
+      el.removeEventListener("touchmove", disarm);
+    };
+  }, []);
+
+  useEffect(() => {
+    const el = scrollerRef.current;
+    const content = contentRef.current;
+    if (!el || !content) return;
+    const observer = new ResizeObserver(() => {
+      if (stickyRef.current) el.scrollTop = el.scrollHeight;
+    });
+    observer.observe(content);
+    return () => observer.disconnect();
+  }, []);
+
+  const prevIsRunningRef = useRef(false);
+  useLayoutEffect(() => {
+    if (isRunning && !prevIsRunningRef.current) jumpToBottom();
+    prevIsRunningRef.current = isRunning;
+  }, [isRunning, jumpToBottom]);
+
+  const didInitialJumpRef = useRef(false);
+  useLayoutEffect(() => {
+    if (didInitialJumpRef.current || turns.length === 0) return;
+    didInitialJumpRef.current = true;
+    jumpToBottom();
+  }, [turns.length, jumpToBottom]);
+
+  const items = virtualizer.getVirtualItems();
+  const paddingTop = items[0]?.start ?? 0;
+  const paddingBottom = Math.max(
+    0,
+    virtualizer.getTotalSize() - (items.at(-1)?.end ?? 0),
+  );
+
+  return (
+    <ThreadPrimitive.Root className="bg-background flex h-full flex-col">
+      <div
+        ref={scrollerRef}
+        className="flex-1 overflow-y-auto overscroll-contain"
+      >
+        <div ref={contentRef} className="mx-auto w-full max-w-3xl px-4 pt-4">
+          <div style={{ paddingTop, paddingBottom }}>
+            {items.map((item) => (
+              <div
+                key={item.key}
+                data-index={item.index}
+                ref={virtualizer.measureElement}
+                className="flex flex-col gap-4 py-3"
+              >
+                {turns[item.index]!.indices.map((index) => (
+                  <ThreadPrimitive.MessageByIndex
+                    key={index}
+                    index={index}
+                    components={MESSAGE_COMPONENTS}
+                  />
+                ))}
+              </div>
+            ))}
+          </div>
+        </div>
+      </div>
+      <div className="relative mx-auto w-full max-w-3xl px-4 pb-4">
+        {!isAtBottom && (
+          <button
+            type="button"
+            onClick={jumpToBottom}
+            aria-label="Scroll to bottom"
+            className="border-border bg-background hover:bg-muted absolute -top-12 left-1/2 -translate-x-1/2 rounded-full border p-2 shadow-sm transition-colors"
+          >
+            <ArrowDownIcon className="size-4" />
+          </button>
+        )}
+        <Composer />
+      </div>
+    </ThreadPrimitive.Root>
+  );
+};
+
+```
+
+## 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",
+  "registries": {
+    "@assistant-ui": "https://r.assistant-ui.com/{name}.json"
+  }
+}
+
+```
+
+## next.config.ts
+
+```typescript
+import { withAui } from "@assistant-ui/next";
+import type { NextConfig } from "next";
+
+const nextConfig: NextConfig = {
+  /* config options here */
+};
+
+export default withAui(nextConfig);
+
+```
+
+## package.json
+
+```json
+{
+  "name": "with-virtualized-thread",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start"
+  },
+  "dependencies": {
+    "@assistant-ui/react": "workspace:*",
+    "@assistant-ui/react-markdown": "workspace:*",
+    "@assistant-ui/ui": "workspace:*",
+    "@tanstack/react-virtual": "^3.14.2",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "lucide-react": "^1.18.0",
+    "next": "^16.2.9",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7",
+    "tailwind-merge": "^3.6.0"
+  },
+  "devDependencies": {
+    "@assistant-ui/next": "workspace:*",
+    "@assistant-ui/x-buildutils": "workspace:*",
+    "@tailwindcss/postcss": "^4.3.1",
+    "@types/node": "^25.9.3",
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3",
+    "postcss": "^8.5.15",
+    "tailwindcss": "^4.3.1",
+    "tw-animate-css": "^1.4.0",
+    "typescript": "^6.0.3"
+  }
+}
+
+```
+
+## README.md
+
+```markdown
+# Virtualized thread example
+
+Renders a 500-message thread with `@tanstack/react-virtual` so only the turns near the viewport are mounted. The runtime is a self-contained external store with a fake streaming reply, so the example runs fully offline with no environment variables.
+
+## Quick start
+
+```sh
+pnpm install
+pnpm --filter with-virtualized-thread dev
+```
+
+## What the example demonstrates
+
+| Concern | File |
+| --- | --- |
+| Virtualizer over user turns, padding spacers, `measureElement` | `app/VirtualizedThread.tsx` |
+| Per-message rendering through `ThreadPrimitive.MessageByIndex` | `app/VirtualizedThread.tsx` |
+| Sticky-bottom auto-follow with a user-scroll disarm guard | `app/VirtualizedThread.tsx` |
+| External store runtime with seeded messages and a streaming tail | `app/MyRuntimeProvider.tsx` |
+| Deterministic synthetic thread content | `app/seed-messages.ts` |
+
+See the [thread virtualization guide](https://assistant-ui.com/docs/guides/virtualization) for the full walkthrough.
+
+```
+
+## tsconfig.json
+
+```json
+{
+  "extends": "@assistant-ui/x-buildutils/ts/next",
+  "compilerOptions": {
+    "paths": {
+      "@/*": ["./*"],
+      "@/components/assistant-ui/*": [
+        "../../packages/ui/src/components/assistant-ui/*"
+      ],
+      "@/components/ui/*": ["../../packages/ui/src/components/ui/*"],
+      "@/lib/utils": ["../../packages/ui/src/lib/utils"],
+      "@assistant-ui/ui/*": ["../../packages/ui/src/*"]
+    }
+  },
+  "include": ["**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
+  "exclude": ["node_modules"]
+}
+
+```
+

package/.docs/raw/docs/(docs)/architecture.mdx

@@ -7,18 +7,19 @@ import { Sparkles, PanelsTopLeft, Database, Terminal } from "lucide-react";
 
 ## assistant-ui is built on these main pillars:
 
-<div className="grid grid-cols-1 md:grid-cols-3 gap-4">
-    <Card title='1. Frontend components'>
-        Shadcn UI chat components with built-in state management
-    </Card>
-
-    <Card title='2. Runtime'>
-        State management layer connecting UI to LLMs and backend services
-    </Card>
-
-    <Card title='3. Assistant Cloud'>
-        Hosted service for thread persistence, history, and user management
-    </Card>
+<div className="not-prose grid grid-cols-1 gap-4 md:grid-cols-3">
+  <Card
+    title="1. Frontend components"
+    description="Shadcn UI chat components with built-in state management"
+  />
+  <Card
+    title="2. Runtime"
+    description="State management layer connecting UI to LLMs and backend services"
+  />
+  <Card
+    title="3. Assistant Cloud"
+    description="Hosted service for thread persistence, history, and user management"
+  />
 </div>