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

package/.docs/organized/code-examples/with-browser-extension.md

@@ -0,0 +1,357 @@
+# Example: with-browser-extension
+
+## app.css
+
+```css
+@import "tailwindcss";
+@import "tw-animate-css";
+
+@source "../../packages/ui/src";
+@source ".";
+
+@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);
+}
+
+: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);
+}
+
+@layer base {
+  * {
+    @apply border-border outline-ring/50;
+  }
+  body {
+    @apply bg-background text-foreground;
+  }
+}
+
+```
+
+## background.ts
+
+```typescript
+chrome.action.onClicked.addListener((tab) => {
+  if (tab.id == null) return;
+  chrome.sidePanel.open({ tabId: tab.id });
+});
+
+```
+
+## manifest.json
+
+```json
+{
+  "manifest_version": 3,
+  "name": "assistant-ui Browser Extension Example",
+  "version": "0.1.0",
+  "description": "Example Chrome extension with assistant-ui chat in a side panel",
+  "permissions": ["sidePanel"],
+  "action": {
+    "default_title": "Open assistant-ui Chat"
+  },
+  "background": {
+    "service_worker": "background.js"
+  },
+  "side_panel": {
+    "default_path": "sidepanel.html"
+  },
+  "icons": {
+    "16": "icon16.png",
+    "32": "icon32.png",
+    "48": "icon48.png",
+    "128": "icon128.png"
+  }
+}
+
+```
+
+## mock-store.ts
+
+```typescript
+import { useCallback, useRef, useState } from "react";
+import type { ThreadMessageLike, AppendMessage } from "@assistant-ui/react";
+
+const INITIAL_MESSAGES: ThreadMessageLike[] = [];
+
+const CANNED_RESPONSE = `Great question! Here's what I think:
+
+This is a **mock response** from the external store runtime. In a real extension, you'd connect this to an AI backend like:
+
+- [assistant-ui Cloud](https://www.assistant-ui.com)
+- OpenAI via AI SDK
+- Any custom API
+
+The UI you're seeing is built with \`@assistant-ui/react\` -- the same components work in Next.js, Vite, React Native, and now browser extensions.`;
+
+export function useMockStore() {
+  const [messages, setMessages] =
+    useState<readonly ThreadMessageLike[]>(INITIAL_MESSAGES);
+  const [isRunning, setIsRunning] = useState(false);
+  // Tracks the in-flight stream so a second `onNew` cancels the first and the
+  // late-arriving loop no longer mutates state once a newer one starts.
+  const activeRunRef = useRef<{ cancelled: boolean } | null>(null);
+
+  const onNew = useCallback(async (message: AppendMessage) => {
+    if (message.content.length !== 1 || message.content[0]?.type !== "text")
+      return;
+
+    if (activeRunRef.current) activeRunRef.current.cancelled = true;
+    const run = { cancelled: false };
+    activeRunRef.current = run;
+
+    const userMessage: ThreadMessageLike = {
+      role: "user",
+      content: [{ type: "text", text: message.content[0].text }],
+    };
+
+    setMessages((prev) => [...prev, userMessage]);
+    setIsRunning(true);
+
+    const words = CANNED_RESPONSE.split(" ");
+    let partial = "";
+    for (let i = 0; i < words.length; i++) {
+      await new Promise((resolve) => setTimeout(resolve, 30));
+      if (run.cancelled) return;
+      partial = partial ? `${partial} ${words[i]}` : (words[i] ?? "");
+      setMessages((prev) => {
+        const withoutLast =
+          prev.at(-1)?.role === "assistant" ? prev.slice(0, -1) : prev;
+        return [
+          ...withoutLast,
+          { role: "assistant", content: [{ type: "text", text: partial }] },
+        ];
+      });
+    }
+
+    if (activeRunRef.current === run) {
+      activeRunRef.current = null;
+      setIsRunning(false);
+    }
+  }, []);
+
+  return {
+    messages,
+    setMessages,
+    isRunning,
+    onNew,
+    convertMessage: (m: ThreadMessageLike) => m,
+  };
+}
+
+```
+
+## MyThread.tsx
+
+```tsx
+import { Thread } from "@assistant-ui/ui/components/assistant-ui/thread.tsx";
+import { useAui, AuiProvider, Suggestions } from "@assistant-ui/react";
+
+const suggestions = Suggestions([
+  {
+    title: "What can you do?",
+    label: "Learn about my capabilities",
+    prompt: "What can you help me with?",
+  },
+  {
+    title: "How does this demo work?",
+    label: "Peek under the hood",
+    prompt: "How does this browser extension example work?",
+  },
+]);
+
+export function MyThread() {
+  const aui = useAui({ suggestions });
+  return (
+    <AuiProvider value={aui}>
+      <Thread />
+    </AuiProvider>
+  );
+}
+
+```
+
+## package.json
+
+```json
+{
+  "name": "with-browser-extension",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "build": "tsx scripts/build.mts",
+    "dev": "tsx scripts/build.mts --watch"
+  },
+  "dependencies": {
+    "@assistant-ui/react": "workspace:*",
+    "@assistant-ui/ui": "workspace:*",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "lucide-react": "^1.17.0",
+    "react": "^19.2.6",
+    "react-dom": "^19.2.6",
+    "tailwind-merge": "^3.6.0"
+  },
+  "devDependencies": {
+    "@tailwindcss/postcss": "^4.3.0",
+    "@types/chrome": "^0.1.42",
+    "@types/node": "^25.9.1",
+    "@types/react": "^19.2.15",
+    "@types/react-dom": "^19.2.3",
+    "esbuild": "^0.28.0",
+    "postcss": "^8.5.15",
+    "tailwindcss": "^4.3.0",
+    "tsx": "^4.22.4",
+    "tw-animate-css": "^1.4.0",
+    "typescript": "5.9.3"
+  }
+}
+
+```
+
+## README.md
+
+```markdown
+# with-browser-extension
+
+A Chrome extension that hosts an assistant-ui chat interface in a browser side panel.
+
+Uses `useExternalStoreRuntime` with mock messages to demonstrate the UI without a backend. Swap in your own runtime (Cloud, AI SDK, etc.) for real AI responses.
+
+## Getting Started
+
+1. Install dependencies from the monorepo root:
+
+   ```bash
+   pnpm install
+   ```
+
+2. Build the extension:
+
+   ```bash
+   cd examples/with-browser-extension
+   pnpm build
+   ```
+
+3. Load into Chrome:
+
+   - Open `chrome://extensions`
+   - Enable **Developer mode** (top right)
+   - Click **Load unpacked**
+   - Select the `dist/` folder
+
+4. Click the extension icon in the toolbar. The side panel opens with the chat UI.
+
+## Development
+
+```bash
+pnpm dev
+```
+
+This watches for TypeScript and CSS changes. After each rebuild, reload the extension in `chrome://extensions` (click the refresh icon on the extension card).
+
+## Connecting a Real Backend
+
+Replace `useMockStore()` in `sidepanel.tsx` with a real runtime. Since the extension runs client-side, you'll need to point to an external API endpoint rather than a local route handler.
+
+```
+
+## sidepanel.tsx
+
+```tsx
+import { createRoot } from "react-dom/client";
+import {
+  AssistantRuntimeProvider,
+  useExternalStoreRuntime,
+} from "@assistant-ui/react";
+import { MyThread } from "./MyThread";
+import { useMockStore } from "./mock-store";
+
+function App() {
+  const runtime = useExternalStoreRuntime(useMockStore());
+
+  return (
+    <AssistantRuntimeProvider runtime={runtime}>
+      <main className="h-dvh">
+        <MyThread />
+      </main>
+    </AssistantRuntimeProvider>
+  );
+}
+
+const root = document.getElementById("root");
+if (root) {
+  createRoot(root).render(<App />);
+}
+
+```
+
+## tsconfig.json
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["DOM", "DOM.Iterable", "ES2022"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "jsx": "react-jsx",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "allowImportingTsExtensions": true,
+    "types": ["chrome", "node"],
+    "paths": {
+      "@/components/*": ["../../packages/ui/src/components/*"],
+      "@/lib/*": ["../../packages/ui/src/lib/*"],
+      "@/hooks/*": ["../../packages/ui/src/hooks/*"]
+    }
+  },
+  "include": ["*.ts", "*.tsx", "scripts/*.mts"]
+}
+
+```
+