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

package/.docs/organized/code-examples/with-react-ink-web.md

@@ -0,0 +1,691 @@
+# Example: with-react-ink-web
+
+## app/globals.css
+
+```css
+* {
+  box-sizing: border-box;
+}
+
+html,
+body {
+  height: 100%;
+  margin: 0;
+  background: #1a1a1a;
+}
+
+.terminal-center {
+  display: flex;
+  height: 100vh;
+  align-items: center;
+  justify-content: center;
+}
+
+.terminal-host {
+  width: 100%;
+  max-width: 960px;
+  height: min(100%, 560px);
+}
+
+.terminal-host .wterm {
+  height: 100%;
+  border-radius: 0;
+  box-shadow: none;
+  background: #1a1a1a;
+  --term-bg: #1a1a1a;
+  --term-fg: #e0e0e0;
+  --term-cursor: #34d399;
+  --term-font-family: Menlo, Monaco, "Courier New", monospace;
+  --term-font-size: 13px;
+  --term-line-height: 1.3;
+}
+
+.terminal-loading {
+  display: flex;
+  height: 100vh;
+  align-items: center;
+  justify-content: center;
+  font-family: ui-monospace, Menlo, Monaco, monospace;
+  font-size: 14px;
+  color: #6b7280;
+}
+
+```
+
+## app/ink-app.tsx
+
+```tsx
+"use client";
+
+// Mirrors examples/with-react-ink/src/app.tsx; keep in sync.
+import { useMemo } from "react";
+import { Box, Text } from "ink";
+import {
+  AssistantRuntimeProvider,
+  StatusBarPrimitive,
+  useAui,
+} from "@assistant-ui/react-ink";
+import {
+  useChatRuntime,
+  AssistantChatTransport,
+} from "@assistant-ui/react-ai-sdk";
+import { lastAssistantMessageIsCompleteWithToolCalls } from "ai";
+import { Thread } from "./thread";
+
+const CHAT_API =
+  process.env.NEXT_PUBLIC_CHAT_ENDPOINT_URL ??
+  (process.env.NODE_ENV === "development"
+    ? "http://localhost:3000/api/chat"
+    : "https://www.assistant-ui.com/api/chat");
+
+const MODEL_NAME = "assistant-ui";
+
+export const InkApp = () => {
+  const transport = useMemo(
+    () => new AssistantChatTransport({ api: CHAT_API }),
+    [],
+  );
+  const runtime = useChatRuntime({
+    transport,
+    sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithToolCalls,
+  });
+  const aui = useAui();
+
+  return (
+    <AssistantRuntimeProvider aui={aui} runtime={runtime}>
+      <Box flexDirection="column" padding={1}>
+        <Box>
+          <Text bold color="cyan">
+            {MODEL_NAME}
+          </Text>
+          <Text dimColor>{"  ~/assistant-ui"}</Text>
+        </Box>
+        <StatusBarPrimitive.Root>
+          <Text dimColor>
+            model: <StatusBarPrimitive.ModelName name={MODEL_NAME} /> ·{" "}
+            <StatusBarPrimitive.MessageCount /> · <StatusBarPrimitive.Status />
+          </Text>
+        </StatusBarPrimitive.Root>
+        <Box marginTop={1}>
+          <Thread />
+        </Box>
+      </Box>
+    </AssistantRuntimeProvider>
+  );
+};
+
+```
+
+## app/ink-streams.ts
+
+```typescript
+type Listener = (...args: unknown[]) => void;
+
+class MiniEmitter {
+  private listeners = new Map<string, Set<Listener>>();
+
+  on(event: string, fn: Listener) {
+    let set = this.listeners.get(event);
+    if (!set) {
+      set = new Set();
+      this.listeners.set(event, set);
+    }
+    set.add(fn);
+    return this;
+  }
+
+  off(event: string, fn: Listener) {
+    this.listeners.get(event)?.delete(fn);
+    return this;
+  }
+
+  addListener(event: string, fn: Listener) {
+    return this.on(event, fn);
+  }
+
+  removeListener(event: string, fn: Listener) {
+    return this.off(event, fn);
+  }
+
+  emit(event: string, ...args: unknown[]) {
+    const set = this.listeners.get(event);
+    if (!set) return false;
+    for (const fn of [...set]) fn(...args);
+    return set.size > 0;
+  }
+}
+
+export type InkStreams = {
+  stdout: NodeJS.WriteStream;
+  stdin: NodeJS.ReadStream;
+  pushInput: (data: string) => void;
+  setSize: (cols: number, rows: number) => void;
+};
+
+// Fake streams implementing the subset of the Node stream API that ink 6
+// touches (see ink's Ink/App classes). The writer receives ink's ANSI output
+// with bare \n rewritten to \r\n (wterm does not emulate ONLCR). Ink's
+// clear-terminal sequence passes through: its 3J resets wterm's scrollback on
+// every overflow repaint, leaving only the final frame's overflow scrollable.
+export function createInkStreams(
+  writeToTerminal: (data: string) => void,
+): InkStreams {
+  const stdoutBase = new MiniEmitter() as MiniEmitter & Record<string, unknown>;
+  Object.assign(stdoutBase, {
+    columns: 80,
+    rows: 24,
+    isTTY: true,
+    writable: true,
+    setDefaultEncoding: () => stdoutBase,
+    cork: () => {},
+    uncork: () => {},
+    write: (chunk: unknown, encoding?: unknown, cb?: () => void) => {
+      const str = typeof chunk === "string" ? chunk : String(chunk);
+      if (str.length > 0) {
+        writeToTerminal(str.replace(/\r?\n/g, "\r\n"));
+      }
+      if (typeof encoding === "function") (encoding as () => void)();
+      else cb?.();
+      return true;
+    },
+  });
+
+  const inputBuffer: string[] = [];
+  const stdinBase = new MiniEmitter() as MiniEmitter & Record<string, unknown>;
+  Object.assign(stdinBase, {
+    columns: 80,
+    rows: 24,
+    isTTY: true,
+    readable: true,
+    setEncoding: () => stdinBase,
+    setRawMode: () => stdinBase,
+    resume: () => stdinBase,
+    pause: () => stdinBase,
+    ref: () => stdinBase,
+    unref: () => stdinBase,
+    read: () => (inputBuffer.length > 0 ? inputBuffer.shift()! : null),
+  });
+
+  return {
+    stdout: stdoutBase as unknown as NodeJS.WriteStream,
+    stdin: stdinBase as unknown as NodeJS.ReadStream,
+    pushInput: (data: string) => {
+      inputBuffer.push(data);
+      stdinBase.emit("readable");
+    },
+    setSize: (cols: number, rows: number) => {
+      const changed =
+        stdoutBase["columns"] !== cols || stdoutBase["rows"] !== rows;
+      stdoutBase["columns"] = cols;
+      stdoutBase["rows"] = rows;
+      stdinBase["columns"] = cols;
+      stdinBase["rows"] = rows;
+      if (changed) stdoutBase.emit("resize");
+    },
+  };
+}
+
+```
+
+## app/layout.tsx
+
+```tsx
+import type { Metadata } from "next";
+import type { ReactNode } from "react";
+import "./globals.css";
+
+export const metadata: Metadata = {
+  title: "assistant-ui ink demo",
+  description: "The with-react-ink example running in the browser via ink-web.",
+};
+
+export default function RootLayout({ children }: { children: ReactNode }) {
+  return (
+    <html lang="en">
+      <body>{children}</body>
+    </html>
+  );
+}
+
+```
+
+## app/page.tsx
+
+```tsx
+"use client";
+
+import dynamic from "next/dynamic";
+
+const Terminal = dynamic(() => import("./terminal"), {
+  ssr: false,
+  loading: () => <div className="terminal-loading">starting terminal...</div>,
+});
+
+export default function Home() {
+  return <Terminal />;
+}
+
+```
+
+## app/terminal.tsx
+
+```tsx
+"use client";
+
+import { useCallback, useEffect, useRef } from "react";
+import { Terminal, useTerminal, type WTerm } from "@wterm/react";
+import { render, type Instance } from "ink";
+import { waitForYogaInit } from "ink-web";
+import { createInkStreams, type InkStreams } from "./ink-streams";
+import { InkApp } from "./ink-app";
+import "@wterm/dom/src/terminal.css";
+
+const inkApp = <InkApp />;
+
+export default function InkTerminal() {
+  const { ref, write } = useTerminal();
+  const wrapperRef = useRef<HTMLDivElement>(null);
+  const streamsRef = useRef<InkStreams | null>(null);
+  const instanceRef = useRef<Instance | null>(null);
+  const startedRef = useRef(false);
+  const disposedRef = useRef(false);
+  const colsRef = useRef(0);
+  const scrollPendingRef = useRef(false);
+
+  const writeRef = useRef(write);
+  writeRef.current = write;
+
+  // wterm does not auto-scroll on new output (vercel-labs/wterm#61); follow
+  // the tail after its coalesced write -> setTimeout(0) -> rAF render pass.
+  // Skipped while the visitor has scrolled up to read scrollback.
+  const scheduleScroll = useCallback(() => {
+    if (scrollPendingRef.current) return;
+    const el = wrapperRef.current?.querySelector(".wterm");
+    if (el && el.scrollHeight - el.scrollTop - el.clientHeight > 100) return;
+    scrollPendingRef.current = true;
+    setTimeout(() => {
+      requestAnimationFrame(() => {
+        scrollPendingRef.current = false;
+        const target = wrapperRef.current?.querySelector(".wterm");
+        if (target) target.scrollTop = target.scrollHeight;
+      });
+    }, 0);
+  }, []);
+
+  const getStreams = useCallback(() => {
+    streamsRef.current ??= createInkStreams((data) => {
+      writeRef.current(data);
+      scheduleScroll();
+    });
+    return streamsRef.current;
+  }, [scheduleScroll]);
+
+  const handleReady = useCallback(
+    (wt: WTerm) => {
+      const streams = getStreams();
+      colsRef.current = wt.cols;
+      streams.setSize(wt.cols, wt.rows);
+      // ink components draw their own cursor; the bundled ink's cli-cursor
+      // shim is a no-op, so hide wterm's grid cursor here.
+      wt.write("\x1b[?25l");
+
+      if (!startedRef.current) {
+        startedRef.current = true;
+        void waitForYogaInit().then(() => {
+          if (disposedRef.current) return;
+          instanceRef.current = render(inkApp, {
+            stdout: streams.stdout,
+            stderr: streams.stdout,
+            stdin: streams.stdin,
+            patchConsole: false,
+            exitOnCtrlC: false,
+          });
+        });
+      } else if (instanceRef.current) {
+        instanceRef.current.clear();
+        instanceRef.current.rerender(inkApp);
+      }
+    },
+    [getStreams],
+  );
+
+  // wterm encodes the Backspace key as \x7f, which the bundled ink 6 parses
+  // as key.delete (forward delete); rewrite to \x08, which it parses as
+  // backspace. \x03 (Ctrl+C) is dropped so it stays free for copy.
+  const handleData = useCallback(
+    (data: string) => {
+      const mapped = data.replaceAll("\x7f", "\x08").replaceAll("\x03", "");
+      if (mapped.length === 0) return;
+      getStreams().pushInput(mapped);
+    },
+    [getStreams],
+  );
+
+  const handleResize = useCallback(
+    (cols: number, rows: number) => {
+      if (cols < colsRef.current && instanceRef.current) {
+        instanceRef.current.clear();
+        writeRef.current("\x1b[2J\x1b[3J\x1b[H");
+      }
+      colsRef.current = cols;
+      getStreams().setSize(cols, rows);
+    },
+    [getStreams],
+  );
+
+  useEffect(() => {
+    disposedRef.current = false;
+    return () => {
+      disposedRef.current = true;
+      instanceRef.current?.unmount();
+      instanceRef.current = null;
+      startedRef.current = false;
+    };
+  }, []);
+
+  return (
+    <div className="terminal-center">
+      <div ref={wrapperRef} className="terminal-host">
+        <Terminal
+          ref={ref}
+          autoResize
+          onReady={handleReady}
+          onData={handleData}
+          onResize={handleResize}
+        />
+      </div>
+    </div>
+  );
+}
+
+```
+
+## app/thread.tsx
+
+```tsx
+// Mirrors examples/with-react-ink/src/components/thread.tsx; keep in sync.
+import { Box, Text, useStdout } from "ink";
+import {
+  ThreadPrimitive,
+  ComposerPrimitive,
+  MessagePrimitive,
+  ErrorPrimitive,
+  LoadingPrimitive,
+  LiveChecklist,
+} from "@assistant-ui/react-ink";
+import { MarkdownText } from "@assistant-ui/react-ink-markdown";
+
+// markdansi defaults width and color from process.stdout, which does not
+// exist in the browser bundle; pass both explicitly so it never reads it.
+// color is forwarded to markdansi but not yet declared on MarkdownTextProps.
+const BrowserMarkdownText = ({ text }: { text: string }) => {
+  const { stdout } = useStdout();
+  return (
+    <MarkdownText
+      text={text}
+      width={(stdout?.columns ?? 80) - 4}
+      hyperlinks={false}
+      {...{ color: true }}
+    />
+  );
+};
+
+const UserMessage = () => (
+  <MessagePrimitive.Root>
+    <Box marginBottom={1}>
+      <Text bold color="green">
+        You:{" "}
+      </Text>
+      <MessagePrimitive.Content
+        renderText={({ part }) => <Text wrap="wrap">{part.text}</Text>}
+      />
+    </Box>
+  </MessagePrimitive.Root>
+);
+
+const AssistantMessage = () => (
+  <MessagePrimitive.Root>
+    <Box flexDirection="column" marginBottom={1}>
+      <Text bold color="blue">
+        AI:
+      </Text>
+      <MessagePrimitive.Content
+        renderText={({ part }) => <BrowserMarkdownText text={part.text} />}
+        renderReasoning={({ part }) => (
+          <Text dimColor italic>
+            {part.text}
+          </Text>
+        )}
+      />
+      <LiveChecklist title="Plan" showProgress marginTop={1} />
+      <ErrorPrimitive.Root>
+        <ErrorPrimitive.Message />
+      </ErrorPrimitive.Root>
+    </Box>
+  </MessagePrimitive.Root>
+);
+
+const Loading = () => (
+  <LoadingPrimitive.Root marginBottom={1}>
+    <LoadingPrimitive.Spinner />
+    <Text> </Text>
+    <LoadingPrimitive.Text>Working</LoadingPrimitive.Text>
+    <Text> </Text>
+    <LoadingPrimitive.ElapsedTime />
+  </LoadingPrimitive.Root>
+);
+
+export const Thread = () => {
+  return (
+    <ThreadPrimitive.Root>
+      <ThreadPrimitive.Empty>
+        <Box flexDirection="column" marginBottom={1}>
+          <Text>
+            A real LLM streaming into a real Ink render loop in your browser.
+          </Text>
+          <Text dimColor>
+            {'  try: "what is assistant-ui?" or "how do I render markdown?"'}
+          </Text>
+        </Box>
+      </ThreadPrimitive.Empty>
+
+      <ThreadPrimitive.Messages>
+        {({ message }) =>
+          message.role === "user" ? <UserMessage /> : <AssistantMessage />
+        }
+      </ThreadPrimitive.Messages>
+
+      <Loading />
+
+      <Box borderStyle="round" borderColor="gray" paddingX={1}>
+        <Text color="gray">{"> "}</Text>
+        <ComposerPrimitive.Input
+          submitOnEnter
+          multiLine
+          placeholder="Type a message... (Enter to send)"
+          autoFocus
+        />
+      </Box>
+    </ThreadPrimitive.Root>
+  );
+};
+
+```
+
+## next.config.ts
+
+```typescript
+import path from "node:path";
+import type { NextConfig } from "next";
+
+const config: NextConfig = {
+  output: "export",
+  transpilePackages: ["ink-web"],
+  turbopack: {
+    // Pin the workspace root; vercel build's environment makes Turbopack's
+    // lockfile-based inference resolve to the app directory instead of the
+    // monorepo root, which breaks resolution of pnpm-symlinked packages.
+    root: path.join(__dirname, "../.."),
+    resolveAlias: {
+      ink: "ink-web",
+      "supports-hyperlinks": {
+        browser: "./shims/supports-hyperlinks.ts",
+      },
+    },
+  },
+};
+
+export default config;
+
+```
+
+## package.json
+
+```json
+{
+  "name": "with-react-ink-web",
+  "version": "0.0.0",
+  "private": true,
+  "scripts": {
+    "dev": "next dev -p 8081",
+    "build": "next build",
+    "start": "next start"
+  },
+  "dependencies": {
+    "@assistant-ui/react-ai-sdk": "workspace:*",
+    "@assistant-ui/react-ink": "workspace:*",
+    "@assistant-ui/react-ink-markdown": "workspace:*",
+    "@wterm/dom": "^0.3.0",
+    "@wterm/react": "^0.3.0",
+    "ai": "^6.0.208",
+    "ink": "^7.1.0",
+    "ink-web": "^0.2.0",
+    "next": "^16.2.9",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7",
+    "react-reconciler": "^0.33.0",
+    "scheduler": "^0.27.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.0.0",
+    "@types/react": "^19.2.17",
+    "typescript": "^6.0.3"
+  }
+}
+
+```
+
+## README.md
+
+```markdown
+# Welcome to the assistant-ui ink web demo 👋
+
+This app runs the [`@assistant-ui/react-ink`](https://www.assistant-ui.com/docs/ink) terminal chat in the browser against a real LLM. It powers the live demo embedded at [assistant-ui.com/ink](https://www.assistant-ui.com/ink) and is deployed at [assistant-ui-ink.vercel.app](https://assistant-ui-ink.vercel.app).
+
+## Get started
+
+1. Install dependencies
+
+   ```bash
+   pnpm install
+   ```
+
+2. Start the docs app, which serves the chat endpoint on [localhost:3000](http://localhost:3000)
+
+   ```bash
+   pnpm --filter @assistant-ui/docs dev
+   ```
+
+3. Start the app
+
+   ```bash
+   pnpm dev
+   ```
+
+The terminal opens on [localhost:8081](http://localhost:8081), and the docs app embeds this URL on its `/ink` page in development.
+
+## How it works
+
+Ink has no official web target, so this app renders the real `@assistant-ui/react-ink` component tree through [ink-web](https://github.com/cjroth/ink-web)'s browser build of Ink, bridged to a [wterm](https://github.com/vercel-labs/wterm) terminal. wterm renders to the DOM, so text selection, copy, find, and screen readers work natively.
+
+Chat requests go to the assistant-ui docs site's `/api/chat`, the same pattern as the React Native demo at [assistant-ui-expo.vercel.app](https://assistant-ui-expo.vercel.app). This app holds no API keys; set `NEXT_PUBLIC_CHAT_ENDPOINT_URL` to point at a different endpoint.
+
+## Learn more
+
+- [assistant-ui ink documentation](https://www.assistant-ui.com/docs/ink): primitives, hooks, and adapters for terminal UIs.
+- [with-react-ink](../with-react-ink): the real terminal version of this example. Start there if you are building an Ink app.
+
+```
+
+## shims/supports-hyperlinks.ts
+
+```typescript
+const supportsHyperlinks = {
+  stdout: false,
+  stderr: false,
+};
+
+export default supportsHyperlinks;
+
+```
+
+## tsconfig.json
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "allowJs": false,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "react-jsx",
+    "incremental": true,
+    "plugins": [
+      {
+        "name": "next"
+      }
+    ]
+  },
+  "include": [
+    "next-env.d.ts",
+    "**/*.ts",
+    "**/*.tsx",
+    ".next/types/**/*.ts",
+    ".next/dev/types/**/*.ts"
+  ],
+  "exclude": ["node_modules"]
+}
+
+```
+
+## vercel.json
+
+```json
+{
+  "$schema": "https://openapi.vercel.sh/vercel.json",
+  "ignoreCommand": "bash ../../scripts/vercel-ignore-changeset-release.sh",
+  "buildCommand": "cd ../.. && pnpm turbo build --filter=@assistant-ui/react-ink --filter=@assistant-ui/react-ink-markdown --filter=@assistant-ui/react-ai-sdk && cd examples/with-react-ink-web && pnpm run build",
+  "outputDirectory": "out",
+  "framework": null,
+  "headers": [
+    {
+      "source": "/(.*)",
+      "headers": [
+        {
+          "key": "Content-Security-Policy",
+          "value": "frame-ancestors 'self' https://*.assistant-ui.com https://*.vercel.app http://localhost:*;"
+        }
+      ]
+    }
+  ]
+}
+
+```
+