@assistant-ui/mcp-docs-server 0.2.0 → 0.2.2

package/.docs/organized/code-examples/with-svelte.md

@@ -0,0 +1,415 @@
+# Example: with-svelte
+
+## package.json
+
+```json
+{
+  "name": "with-svelte",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite dev --port 3000",
+    "build": "vite build",
+    "serve": "vite preview"
+  },
+  "dependencies": {
+    "@assistant-ui/core": "workspace:*",
+    "@assistant-ui/store": "workspace:*",
+    "@assistant-ui/svelte": "workspace:*",
+    "@assistant-ui/tap": "workspace:*",
+    "@lucide/svelte": "^1.31.0",
+    "svelte": "^5.56.8"
+  },
+  "devDependencies": {
+    "@sveltejs/vite-plugin-svelte": "^7.3.0",
+    "@tailwindcss/vite": "^4.3.3",
+    "@types/react": "^19.2.18",
+    "tailwindcss": "^4.3.3",
+    "typescript": "^7.0.2",
+    "vite": "^8.2.1"
+  }
+}
+
+```
+
+## src/env.d.ts
+
+```typescript
+declare module "*.svelte" {
+  import type { Component } from "svelte";
+  const component: Component<Record<string, never>>;
+  export default component;
+}
+
+```
+
+## src/main.ts
+
+```typescript
+import { mount } from "svelte";
+import "./styles.css";
+import Root from "./Root.svelte";
+
+mount(Root, { target: document.getElementById("app")! });
+
+```
+
+## src/runtime.ts
+
+```typescript
+import type { AppendMessage, ExternalStoreAdapter } from "@assistant-ui/core";
+import {
+  AssistantRuntimeImpl,
+  ExternalStoreRuntimeCore,
+} from "@assistant-ui/core/internal";
+
+export type EchoMessage = {
+  id: string;
+  role: "user" | "assistant";
+  text: string;
+};
+
+type EchoThread = {
+  id: string;
+  title: string;
+  messages: EchoMessage[];
+};
+
+let nextId = 0;
+const freshId = (prefix: string) => `${prefix}-${nextId++}`;
+
+const messageText = (message: AppendMessage) =>
+  message.content
+    .map((part) => (part.type === "text" ? part.text : ""))
+    .join("");
+
+const convertEchoMessage = (message: EchoMessage) => ({
+  id: message.id,
+  role: message.role,
+  content: [{ type: "text" as const, text: message.text }],
+});
+
+export const createEchoRuntime = () => {
+  let threads: EchoThread[] = [
+    { id: freshId("thread"), title: "", messages: [] },
+  ];
+  let currentId = threads[0]!.id;
+  let isRunning = false;
+  let replyTimer: ReturnType<typeof setTimeout> | undefined;
+
+  const current = () => threads.find((thread) => thread.id === currentId)!;
+  const updateCurrent = (updater: (thread: EchoThread) => EchoThread) => {
+    threads = threads.map((thread) =>
+      thread.id === currentId ? updater(thread) : thread,
+    );
+  };
+
+  const reply = (text: string) => {
+    const replyTo = currentId;
+    isRunning = true;
+    sync();
+    replyTimer = setTimeout(() => {
+      if (currentId !== replyTo) return;
+      updateCurrent((thread) => ({
+        ...thread,
+        messages: [
+          ...thread.messages,
+          {
+            id: freshId("assistant"),
+            role: "assistant",
+            text: `Echo: ${text}`,
+          },
+        ],
+      }));
+      isRunning = false;
+      sync();
+    }, 600);
+  };
+
+  const appendUser = (text: string) => {
+    updateCurrent((thread) => ({
+      ...thread,
+      title: thread.title || text.slice(0, 40),
+      messages: [
+        ...thread.messages,
+        { id: freshId("user"), role: "user", text },
+      ],
+    }));
+  };
+
+  const makeAdapter = (): ExternalStoreAdapter<EchoMessage> => ({
+    messages: current().messages,
+    isRunning,
+    convertMessage: convertEchoMessage,
+    setMessages: (next) => {
+      updateCurrent((thread) => ({ ...thread, messages: next }));
+      sync();
+    },
+    onNew: async (message) => {
+      const text = messageText(message);
+      appendUser(text);
+      reply(text);
+    },
+    onEdit: async (message) => {
+      const text = messageText(message);
+      const parentIndex = message.parentId
+        ? current().messages.findIndex(
+            (entry) => entry.id === message.parentId,
+          ) + 1
+        : 0;
+      updateCurrent((thread) => ({
+        ...thread,
+        messages: thread.messages.slice(0, parentIndex),
+      }));
+      appendUser(text);
+      reply(text);
+    },
+    onReload: async (parentId) => {
+      let parentIndex = 0;
+      if (parentId) {
+        const index = current().messages.findIndex(
+          (entry) => entry.id === parentId,
+        );
+        if (index === -1) return;
+        parentIndex = index + 1;
+      }
+      const sliced = current().messages.slice(0, parentIndex);
+      const lastUser = [...sliced]
+        .reverse()
+        .find((entry) => entry.role === "user");
+      updateCurrent((thread) => ({ ...thread, messages: sliced }));
+      reply(`${lastUser?.text ?? ""} (again)`);
+    },
+    onCancel: async () => {
+      clearTimeout(replyTimer);
+      if (isRunning && current().messages.at(-1)?.role === "user") {
+        updateCurrent((thread) => ({
+          ...thread,
+          messages: thread.messages.slice(0, -1),
+        }));
+      }
+      isRunning = false;
+      // cancelRun restores the trailing user message into the composer
+      // synchronously after onCancel returns; an eager sync would delete it
+      // before that restore reads it.
+      queueMicrotask(sync);
+    },
+    adapters: {
+      threadList: {
+        threadId: currentId,
+        threads: threads.map((thread) => ({
+          status: "regular" as const,
+          id: thread.id,
+          title: thread.title,
+        })),
+        onSwitchToThread: (threadId) => {
+          clearTimeout(replyTimer);
+          isRunning = false;
+          currentId = threadId;
+          sync();
+        },
+        onSwitchToNewThread: () => {
+          clearTimeout(replyTimer);
+          isRunning = false;
+          const id = freshId("thread");
+          threads = [...threads, { id, title: "", messages: [] }];
+          currentId = id;
+          sync();
+        },
+      },
+    },
+  });
+
+  const core = new ExternalStoreRuntimeCore(makeAdapter());
+  const sync = () => core.setAdapter(makeAdapter());
+  return new AssistantRuntimeImpl(core);
+};
+
+```
+
+## src/styles.css
+
+```css
+@import "tailwindcss";
+
+@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;
+  }
+}
+
+html,
+body,
+#app {
+  height: 100%;
+}
+
+```
+
+## svelte.config.js
+
+```javascript
+import { vitePreprocess } from "@sveltejs/vite-plugin-svelte";
+
+export default {
+  preprocess: vitePreprocess(),
+};
+
+```
+
+## tsconfig.json
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "types": ["vite/client"]
+  },
+  "include": ["src", "vite.config.ts"]
+}
+
+```
+
+## vite.config.ts
+
+```typescript
+import { defineConfig } from "vite";
+import { svelte } from "@sveltejs/vite-plugin-svelte";
+import tailwindcss from "@tailwindcss/vite";
+
+// The assistant-ui runtime is written against react hook imports but runs on
+// @assistant-ui/tap; aliasing react to the standalone shim resolves it with
+// no React installed.
+export default defineConfig({
+  plugins: [svelte(), tailwindcss()],
+  resolve: {
+    alias: [
+      {
+        find: /^react\/compiler-runtime$/,
+        replacement: "@assistant-ui/tap/standalone-shim/compiler-runtime",
+      },
+      { find: /^react$/, replacement: "@assistant-ui/tap/standalone-shim" },
+    ],
+  },
+});
+
+```
+