@assistant-ui/mcp-docs-server 0.2.3 → 0.3.1

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

@@ -1,740 +0,0 @@
-# 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/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";
-const ANONYMOUS_SESSION_HEADER = "x-assistant-ui-anonymous-session";
-
-// Mirrors examples/with-expo/hooks/anonymous-session-fetch.ts; keep in sync.
-function createAnonymousSessionFetch(chatApi: string): typeof fetch {
-  let tokenPromise: Promise<string | null> | null = null;
-
-  const getToken = () => {
-    tokenPromise ??= (async () => {
-      const endpoint = new URL(chatApi, window.location.origin);
-      endpoint.pathname = "/api/anonymous-session";
-      endpoint.search = "";
-      const response = await fetch(endpoint, { credentials: "same-origin" });
-      if (!response.ok) {
-        throw new Error("Unable to start an anonymous session");
-      }
-      if (response.status === 204) return null;
-      const payload = (await response.json()) as { token?: unknown };
-      if (typeof payload.token !== "string" || !payload.token) {
-        throw new Error("Anonymous session token is missing");
-      }
-      return payload.token;
-    })().catch(() => {
-      tokenPromise = null;
-      return null;
-    });
-    return tokenPromise;
-  };
-
-  return async (input, init) => {
-    const requestTemplate =
-      input instanceof Request ? new Request(input, init) : null;
-
-    const send = async () => {
-      const headers = new Headers(requestTemplate?.headers ?? init?.headers);
-      const token = await getToken();
-      if (token) headers.set(ANONYMOUS_SESSION_HEADER, token);
-      if (requestTemplate) {
-        return fetch(requestTemplate.clone(), { headers });
-      }
-      return fetch(input, { ...init, headers });
-    };
-
-    const response = await send();
-    if (response.status !== 401) return response;
-    tokenPromise = null;
-    return send();
-  };
-}
-
-export const InkApp = () => {
-  const transport = useMemo(
-    () =>
-      new AssistantChatTransport({
-        api: CHAT_API,
-        fetch: createAnonymousSessionFetch(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 {
-  AuiIf,
-  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.
-const BrowserMarkdownText = ({ text }: { text: string }) => {
-  const { stdout } = useStdout();
-  return (
-    <MarkdownText
-      text={text}
-      width={(stdout?.columns ?? 80) - 4}
-      hyperlinks={false}
-      color
-    />
-  );
-};
-
-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>
-      <AuiIf condition={(s) => s.thread.isEmpty}>
-        <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>
-      </AuiIf>
-
-      <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/ai-sdk": "workspace:*",
-    "@assistant-ui/react-ink": "workspace:*",
-    "@assistant-ui/react-ink-markdown": "workspace:*",
-    "@wterm/dom": "^0.3.4",
-    "@wterm/react": "^0.3.4",
-    "ai": "^7.0.77",
-    "ink": "^7.1.1",
-    "ink-web": "^0.2.0",
-    "next": "^16.3.2",
-    "react": "^19.2.8",
-    "react-dom": "^19.2.8",
-    "react-reconciler": "^0.33.0",
-    "scheduler": "^0.27.0"
-  },
-  "devDependencies": {
-    "@types/node": "^26.2.0",
-    "@types/react": "^19.2.18",
-    "typescript": "^7.0.2"
-  }
-}
-
-```
-
-## 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). The app obtains a signed anonymous session when the backend supports it and holds no API keys; custom backends without the session route continue to receive normal chat requests.
-
-## 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/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:*;"
-        }
-      ]
-    }
-  ]
-}
-
-```
-