@kitn.ai/ui 0.15.0 → 0.16.0

package/dist/mcp.es.js

@@ -0,0 +1,2140 @@
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { ListToolsRequestSchema, CallToolRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { z } from "zod";
+import { readFileSync, existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+function resolveManifestPath() {
+  const thisFile = fileURLToPath(import.meta.url);
+  const thisDir = dirname(thisFile);
+  const sibling = join(thisDir, "custom-elements.json");
+  if (existsSync(sibling)) {
+    return sibling;
+  }
+  let dir = thisDir;
+  for (let i = 0; i < 10; i++) {
+    const candidate = join(dir, "dist", "custom-elements.json");
+    if (existsSync(candidate)) {
+      return candidate;
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  throw new Error(
+    `Could not find custom-elements.json. Searched from: ${thisDir}`
+  );
+}
+let _manifest;
+function getManifest() {
+  if (!_manifest) {
+    const path = resolveManifestPath();
+    const raw = readFileSync(path, "utf-8");
+    _manifest = JSON.parse(raw);
+  }
+  return _manifest;
+}
+function getDeclarations() {
+  return getManifest().modules.flatMap((m) => m.declarations ?? []);
+}
+function getElement(tag) {
+  return getDeclarations().find((d) => d.tagName === tag);
+}
+function listElements() {
+  return getDeclarations().filter((d) => d.tagName).map((d) => d.tagName).sort();
+}
+const JS_ONLY_TYPE_PATTERNS = /\[\]|\{|Record</;
+function isJsOnlyType(typeText) {
+  return typeText ? JS_ONLY_TYPE_PATTERNS.test(typeText) : false;
+}
+function formatReference(tag) {
+  const el = getElement(tag);
+  if (!el) {
+    const all = listElements();
+    const sample = all.slice(0, 5).join(", ");
+    return `Unknown element: ${tag}
+
+Valid tags include: ${sample} (and ${Math.max(0, all.length - 5)} more).
+Call component_reference with no name (or name: "list") to list all ${all.length} elements.`;
+  }
+  const lines = [];
+  lines.push(`## <${tag}>`);
+  if (el.description) {
+    lines.push("", el.description.trim());
+  }
+  lines.push(
+    "",
+    "### AI/UI contract",
+    '`kai-*` elements accept **array and object data as JavaScript properties** (set in JavaScript via `el.property = value`, not as HTML attributes). Events are native CustomEvents — listen with `el.addEventListener("event-name", handler)` and read `event.detail` for the payload.'
+  );
+  const publicFields = (el.members ?? []).filter(
+    (m) => m.kind === "field" && m.privacy === "public"
+  );
+  if (publicFields.length > 0) {
+    lines.push("", "### Props (JavaScript properties)");
+    for (const field of publicFields) {
+      const type = field.type?.text ?? "unknown";
+      const jsOnly = isJsOnlyType(type);
+      const desc = field.description?.trim() ?? "";
+      const note = jsOnly ? " ⚑ set as a JS property, not an HTML attribute" : "";
+      lines.push(`- **${field.name}** \`${type}\`${note}`);
+      if (desc) {
+        lines.push(`  ${desc}`);
+      }
+    }
+  }
+  const attrs = el.attributes ?? [];
+  if (attrs.length > 0) {
+    lines.push("", "### Attributes (HTML-safe)");
+    for (const attr of attrs) {
+      const type = attr.type?.text ?? "unknown";
+      const desc = attr.description?.trim() ?? "";
+      lines.push(`- **${attr.name}** \`${type}\``);
+      if (desc) {
+        lines.push(`  ${desc}`);
+      }
+    }
+  }
+  const events = el.events ?? [];
+  if (events.length > 0) {
+    lines.push("", "### Events (CustomEvent, listen via addEventListener)");
+    for (const ev of events) {
+      const desc = ev.description?.trim() ?? "";
+      lines.push(`- **${ev.name}** — ${desc}`);
+    }
+  }
+  const cssProps = el.cssProperties ?? [];
+  if (cssProps.length > 0) {
+    lines.push("", "### CSS custom properties");
+    for (const prop of cssProps) {
+      const desc = prop.description?.trim() ?? "";
+      const def = prop.default ? ` (default: ${prop.default})` : "";
+      lines.push(`- **${prop.name}**${def}${desc ? ` — ${desc}` : ""}`);
+    }
+  }
+  return lines.join("\n");
+}
+const reference = {
+  name: "component_reference",
+  description: "Look up AI/UI (kai-*) web components: their tags, props, events, and usage examples.",
+  inputSchema: z.object({ name: z.string().optional() }),
+  handler: async (args) => {
+    const name = typeof args.name === "string" ? args.name.trim() : void 0;
+    let text2;
+    if (!name || name === "list") {
+      const tags = listElements();
+      text2 = `AI/UI elements (${tags.length} total):
+
+` + tags.map((t) => `  ${t}`).join("\n") + '\n\nCall component_reference with a specific name (e.g. { name: "kai-chat" }) for full API details.';
+    } else {
+      text2 = formatReference(name);
+    }
+    return { content: [{ type: "text", text: text2 }] };
+  }
+};
+const Category = z.enum(["provider", "gateway", "framework", "harness", "mock"]);
+const Language = z.enum(["ts", "python"]);
+const StreamFormat = z.enum(["openai-sse", "ai-sdk", "native"]);
+const Framework = z.enum(["html", "react", "next", "vue", "svelte", "fastapi", "express", "worker", "tanstack-start"]);
+const Placement = z.enum(["side", "full-page", "docked-widget", "inline"]);
+z.object({
+  id: z.string(),
+  title: z.string(),
+  category: Category,
+  language: Language,
+  streamFormat: StreamFormat,
+  envVars: z.array(z.string()).default([]),
+  routeTemplates: z.record(z.string(), z.string()),
+  // keyed by Framework value → code string
+  streamMapping: z.string(),
+  // prose: how the stream maps to messages
+  runNote: z.string(),
+  docsSlug: z.string()
+});
+z.object({
+  id: z.string(),
+  title: z.string(),
+  components: z.array(z.string()),
+  // kai-* tags, e.g. ['kai-chat', 'kai-sources']
+  defaultPlacement: Placement,
+  docsSlug: z.string()
+});
+const openrouter = {
+  id: "openrouter",
+  title: "OpenRouter",
+  category: "gateway",
+  language: "ts",
+  streamFormat: "openai-sse",
+  envVars: ["OPENROUTER_API_KEY"],
+  routeTemplates: {
+    next: `export async function POST(req: Request) {
+  const { model, messages } = await req.json();
+  const upstream = await fetch('https://openrouter.ai/api/v1/chat/completions', {
+    method: 'POST',
+    headers: { Authorization: \`Bearer \${process.env.OPENROUTER_API_KEY}\`, 'Content-Type': 'application/json' },
+    body: JSON.stringify({ model, messages, stream: true }),
+  });
+  return new Response(upstream.body, { headers: { 'Content-Type': 'text/event-stream' } });
+}`
+  },
+  streamMapping: "OpenRouter returns OpenAI-format SSE — pipe upstream.body straight to the browser; the Streaming-recipe reader handles it.",
+  runNote: "Set OPENROUTER_API_KEY. Model ids are vendor/model, e.g. openai/gpt-4o.",
+  docsSlug: "integrations/connect-any-model"
+};
+const vercelAiSdk = {
+  id: "vercel-ai-sdk",
+  title: "Vercel AI SDK",
+  category: "framework",
+  language: "ts",
+  streamFormat: "ai-sdk",
+  envVars: ["AI_GATEWAY_API_KEY"],
+  routeTemplates: {
+    next: `// app/api/chat/route.ts
+import { streamText } from 'ai';
+
+export const maxDuration = 30; // allow long streaming responses
+
+export async function POST(req: Request) {
+  const { messages } = await req.json();
+
+  const result = streamText({
+    model: 'openai/gpt-4o', // AI Gateway id; needs AI_GATEWAY_API_KEY
+    messages,
+  });
+
+  const encoder = new TextEncoder();
+  const sse = new ReadableStream({
+    async start(controller) {
+      for await (const delta of result.textStream) {
+        const chunk = { choices: [{ delta: { content: delta } }] };
+        controller.enqueue(encoder.encode(\`data: \${JSON.stringify(chunk)}\\n\\n\`));
+      }
+      controller.enqueue(encoder.encode('data: [DONE]\\n\\n'));
+      controller.close();
+    },
+  });
+
+  return new Response(sse, { headers: { 'Content-Type': 'text/event-stream' } });
+}`
+  },
+  streamMapping: "The Vercel AI SDK's toUIMessageStreamResponse() and toTextStreamResponse() don't emit OpenAI-format SSE. Wrap result.textStream manually: iterate text deltas and emit data: {choices:[{delta:{content}}]} frames, closing with data: [DONE]. The kai-chat SSE reader handles it.",
+  runNote: "Set AI_GATEWAY_API_KEY for the AI Gateway (string model id form: creator/model-name). For direct provider access, import its provider package (e.g. @ai-sdk/openai) and set the corresponding key (e.g. OPENAI_API_KEY).",
+  docsSlug: "integrations/vercel-ai-sdk"
+};
+const langgraph = {
+  id: "langgraph",
+  title: "LangGraph",
+  category: "framework",
+  language: "ts",
+  streamFormat: "openai-sse",
+  envVars: ["OPENAI_API_KEY"],
+  routeTemplates: {
+    next: `// POST /api/chat — stream a compiled LangGraph agent to the browser
+import { createReactAgent } from '@langchain/langgraph/prebuilt';
+import { ChatOpenAI } from '@langchain/openai';
+import { tool } from '@langchain/core/tools';
+import { z } from 'zod';
+
+const getWeather = tool(
+  async ({ city }) => \`It's 18°C and clear in \${city}.\`,
+  {
+    name: 'get_weather',
+    description: 'Get the current weather for a city.',
+    schema: z.object({ city: z.string() }),
+  },
+);
+
+const agent = createReactAgent({
+  llm: new ChatOpenAI({ model: 'gpt-4o' }),
+  tools: [getWeather],
+});
+
+export async function POST(req: Request) {
+  const { messages } = await req.json();
+
+  const stream = await agent.stream({ messages }, { streamMode: 'messages' });
+
+  const encoder = new TextEncoder();
+  const body = new ReadableStream({
+    async start(controller) {
+      const send = (obj: unknown) =>
+        controller.enqueue(encoder.encode(\`data: \${JSON.stringify(obj)}\\n\\n\`));
+
+      for await (const [chunk] of stream) {
+        if (typeof chunk.content === 'string' && chunk.content) {
+          send({ choices: [{ delta: { content: chunk.content } }] });
+        }
+      }
+      controller.enqueue(encoder.encode('data: [DONE]\\n\\n'));
+      controller.close();
+    },
+  });
+
+  return new Response(body, { headers: { 'Content-Type': 'text/event-stream' } });
+}`
+  },
+  streamMapping: "Use graph.stream(input, { streamMode: 'messages' }) to get [messageChunk, metadata] tuples. Extract chunk.content (string) and forward as OpenAI-format SSE frames: data: {choices:[{delta:{content}}]}. Close with data: [DONE]. The kai-chat reader handles it.",
+  runNote: "Set OPENAI_API_KEY (or the key for your chosen model provider). Install @langchain/langgraph, @langchain/openai, @langchain/core.",
+  docsSlug: "integrations/langgraph"
+};
+const cloudflare = {
+  id: "cloudflare",
+  title: "Cloudflare AI",
+  category: "provider",
+  language: "ts",
+  streamFormat: "openai-sse",
+  envVars: ["CF_ACCOUNT_ID", "CF_API_TOKEN"],
+  routeTemplates: {
+    next: `// app/api/chat/route.ts — proxy Workers AI, keep the token server-side
+export async function POST(req: Request) {
+  const { messages } = await req.json();
+
+  const upstream = await fetch(
+    \`https://api.cloudflare.com/client/v4/accounts/\${process.env.CF_ACCOUNT_ID}/ai/v1/chat/completions\`,
+    {
+      method: 'POST',
+      headers: {
+        Authorization: \`Bearer \${process.env.CF_API_TOKEN}\`,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({
+        model: '@cf/meta/llama-3.1-8b-instruct',
+        messages,
+        stream: true,
+      }),
+    },
+  );
+
+  // Workers AI returns OpenAI-format SSE — pass it straight through.
+  return new Response(upstream.body, { headers: { 'Content-Type': 'text/event-stream' } });
+}`,
+    worker: `// Worker handler — env.AI is bound in wrangler.toml
+// env.AI.run emits Cloudflare-native SSE (data: {"response":"<token>"}).
+// The TransformStream below re-frames each chunk to OpenAI-format SSE so
+// kai-chat's reader works without any client-side changes.
+export default {
+  async fetch(req: Request, env: Env): Promise<Response> {
+    const { messages } = await req.json();
+
+    const nativeStream = await env.AI.run('@cf/meta/llama-3.1-8b-instruct', {
+      messages,
+      stream: true,
+    });
+
+    // Re-frame Cloudflare-native SSE → OpenAI-format SSE
+    const { readable, writable } = new TransformStream();
+    const writer = writable.getWriter();
+    const encoder = new TextEncoder();
+    const decoder = new TextDecoder();
+
+    (async () => {
+      const reader = (nativeStream as ReadableStream<Uint8Array>).getReader();
+      let buffer = '';
+      while (true) {
+        const { value, done } = await reader.read();
+        if (done) break;
+        buffer += decoder.decode(value, { stream: true });
+        const lines = buffer.split('\\n');
+        buffer = lines.pop() ?? '';
+        for (const line of lines) {
+          const s = line.trim();
+          if (!s.startsWith('data:')) continue;
+          const payload = s.slice(5).trim();
+          if (payload === '[DONE]') continue;
+          try {
+            const { response } = JSON.parse(payload) as { response?: string };
+            if (response == null) continue;
+            const openaiChunk = JSON.stringify({ choices: [{ delta: { content: response } }] });
+            await writer.write(encoder.encode(\`data: \${openaiChunk}\\n\\n\`));
+          } catch { /* skip malformed lines */ }
+        }
+      }
+      await writer.write(encoder.encode('data: [DONE]\\n\\n'));
+      await writer.close();
+    })();
+
+    return new Response(readable, { headers: { 'Content-Type': 'text/event-stream' } });
+  },
+};`
+  },
+  streamMapping: `Workers AI via the OpenAI-compatible HTTP endpoint returns OpenAI-format SSE — pipe upstream.body straight to the browser; kai-chat's reader handles it. The native env.AI binding streams Cloudflare's own format (data: {"response":"...token..."}); the worker route template re-frames these chunks to OpenAI-format SSE via a TransformStream before returning.`,
+  runNote: 'Set CF_ACCOUNT_ID and CF_API_TOKEN. Model ids are prefixed with @cf/, e.g. @cf/meta/llama-3.1-8b-instruct. For the AI binding (worker key), add an [ai] block with binding = "AI" in wrangler.toml.',
+  docsSlug: "integrations/cloudflare-ai"
+};
+const ollama = {
+  id: "ollama",
+  title: "Ollama",
+  category: "provider",
+  language: "ts",
+  streamFormat: "openai-sse",
+  envVars: [],
+  routeTemplates: {
+    next: `// app/api/chat/route.ts — proxy the browser to local Ollama
+export async function POST(req: Request) {
+  const { messages } = await req.json();
+
+  const upstream = await fetch('http://localhost:11434/v1/chat/completions', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ model: 'llama3.2', messages, stream: true }),
+  });
+
+  // Ollama returns OpenAI-format SSE — stream it straight to the browser.
+  return new Response(upstream.body, { headers: { 'Content-Type': 'text/event-stream' } });
+}`,
+    html: `<kai-chat id="chat"></kai-chat>
+
+<script type="module">
+  import '@kitn.ai/ui/elements';
+  const chat = document.getElementById('chat');
+
+  chat.addEventListener('kai-submit', async (e) => {
+    const history = [...chat.messages, { id: crypto.randomUUID(), role: 'user', content: e.detail.value }];
+    chat.messages = [...history, { id: crypto.randomUUID(), role: 'assistant', content: '' }];
+    await fetch('/api/chat', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ messages: history }),
+    });
+    // stream the reply into the last message — see the Streaming recipe
+  });
+<\/script>`
+  },
+  streamMapping: "Ollama's OpenAI-compatible endpoint (http://localhost:11434/v1/chat/completions) returns OpenAI-format SSE — pipe upstream.body straight to the browser; kai-chat's reader handles it. No API key needed; pass any string if a client requires one (Ollama ignores it).",
+  runNote: "No API key required. Run: ollama serve (starts on 127.0.0.1:11434), then ollama pull <model>. For browser-direct access, set OLLAMA_ORIGINS to allow the page origin; restart Ollama after any env change.",
+  docsSlug: "integrations/ollama"
+};
+const mastra = {
+  id: "mastra",
+  title: "Mastra",
+  category: "harness",
+  language: "ts",
+  streamFormat: "openai-sse",
+  envVars: ["MASTRA_URL"],
+  routeTemplates: {
+    express: `// POST /api/chat — your server proxies a Mastra agent to the browser
+import { MastraClient } from '@mastra/client-js';
+
+const mastra = new MastraClient({ baseUrl: process.env.MASTRA_URL });
+
+const stream = await mastra.getAgent('supportAgent').stream({ messages });
+for await (const delta of stream.textStream) {
+  res.write(\`data: \${JSON.stringify({ choices: [{ delta: { content: delta } }] })}\\n\\n\`);
+}
+res.write('data: [DONE]\\n\\n');`
+  },
+  streamMapping: "Mastra agents speak Vercel AI SDK v5 and expose stream.textStream (async iterable of string deltas). Iterate textStream and emit data: {choices:[{delta:{content}}]} frames; close with data: [DONE]. kai-chat's SSE reader handles it. For tool calls and reasoning, convert the agent to a UI message stream with @mastra/ai-sdk.",
+  runNote: "Set MASTRA_URL to your Mastra server base URL (mastra dev exposes POST /api/agents/:agentId/stream on port 4111). Install @mastra/client-js.",
+  docsSlug: "integrations/harnesses"
+};
+const pi = {
+  id: "pi",
+  title: "Pi",
+  category: "harness",
+  language: "ts",
+  streamFormat: "native",
+  envVars: [],
+  routeTemplates: {
+    express: `import { spawn } from 'node:child_process';
+
+// POST /api/chat — bridge a Pi RPC session to the browser as SSE
+const pi = spawn('pi', ['--mode', 'rpc', '--no-session']);
+
+// Send the user's turn. Pi commands are { type, message }.
+pi.stdin.write(JSON.stringify({ type: 'prompt', message: prompt }) + '\\n');
+
+let buffer = '';
+pi.stdout.on('data', (chunk) => {
+  buffer += chunk.toString();
+  const lines = buffer.split('\\n');
+  buffer = lines.pop(); // hold the partial line for the next chunk
+  for (const line of lines) {
+    if (!line) continue;
+    const event = JSON.parse(line);
+    const part = event.assistantMessageEvent;
+    if (event.type === 'message_update' && part?.type === 'text_delta') {
+      res.write(\`data: \${JSON.stringify({ choices: [{ delta: { content: part.delta } }] })}\\n\\n\`);
+    }
+  }
+});
+pi.on('close', () => { res.write('data: [DONE]\\n\\n'); res.end(); });`
+  },
+  streamMapping: "Pi runs as a local stdio process in RPC mode (pi --mode rpc --no-session). It emits newline-delimited JSON events on stdout. Map message_update events where assistantMessageEvent.type === 'text_delta' to data: {choices:[{delta:{content:part.delta}}]} SSE frames; send data: [DONE] on close. Split stdout on \\n (not readline, which breaks on Unicode separators U+2028/U+2029). Pi also emits thinking_delta (map to reasoning) and toolcall_* events (map to tool calls).",
+  runNote: "Pi must be installed locally and available on PATH as 'pi'. No API key is required by the bridge itself; Pi uses its own credentials. Pi runs with full user permissions — sandbox before exposing to a public endpoint. See the RPC reference: https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/rpc.md",
+  docsSlug: "integrations/harnesses"
+};
+const pydanticAi = {
+  id: "pydantic-ai",
+  title: "Pydantic AI",
+  category: "framework",
+  language: "python",
+  streamFormat: "openai-sse",
+  envVars: ["OPENAI_API_KEY"],
+  routeTemplates: {
+    fastapi: `# main.py
+import json
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import StreamingResponse
+from pydantic import BaseModel
+from pydantic_ai import Agent
+
+agent = Agent('openai:gpt-4o')
+
+app = FastAPI()
+app.add_middleware(
+    CORSMiddleware, allow_origins=['*'], allow_methods=['*'], allow_headers=['*']
+)
+
+class Message(BaseModel):
+    role: str
+    content: str
+
+class ChatRequest(BaseModel):
+    messages: list[Message]
+
+async def openai_sse(messages: list[Message]):
+    prompt = messages[-1].content if messages else ''
+    async with agent.run_stream(prompt) as result:
+        async for delta in result.stream_text(delta=True):
+            chunk = {'choices': [{'delta': {'content': delta}}]}
+            yield f'data: {json.dumps(chunk)}\\n\\n'
+    yield 'data: [DONE]\\n\\n'
+
+@app.post('/api/chat')
+async def chat(req: ChatRequest):
+    return StreamingResponse(openai_sse(req.messages), media_type='text/event-stream')`
+  },
+  streamMapping: "Pydantic AI's agent.run_stream() yields text deltas via result.stream_text(delta=True). Each delta is re-framed as a data: {choices:[{delta:{content}}]} SSE line and the stream closes with data: [DONE]. The kai-chat reader is unchanged — it sees standard OpenAI-format SSE.",
+  runNote: "Install: pip install pydantic-ai fastapi uvicorn. Set OPENAI_API_KEY. Run: uvicorn main:app --reload (default port 8000). Point kai-chat at http://localhost:8000/api/chat.",
+  docsSlug: "integrations/pydantic-ai"
+};
+const mock = {
+  id: "mock",
+  title: "Mock (local preview)",
+  category: "mock",
+  language: "ts",
+  streamFormat: "native",
+  envVars: [],
+  routeTemplates: {},
+  streamMapping: "No backend. onSubmit streams a canned assistant reply client-side, one token at a time, reassigning messages (new array/object reference) per chunk so kai-chat re-renders. Swap integration for a real provider when ready.",
+  runNote: "No backend or API key needed — replies stream locally for preview. Run the front-end as-is; swap `integration` for a real provider (e.g. openrouter, ollama) when ready.",
+  docsSlug: "integrations/mock"
+};
+const archetypes$1 = [
+  {
+    id: "drop-in-chat",
+    title: "Drop-in chat",
+    components: ["kai-chat"],
+    defaultPlacement: "full-page",
+    docsSlug: "examples/drop-in-chat"
+  },
+  {
+    id: "support-widget",
+    title: "Support widget",
+    components: ["kai-chat"],
+    defaultPlacement: "docked-widget",
+    docsSlug: "examples/support-widget"
+  },
+  {
+    id: "knowledge-base",
+    title: "Knowledge base / RAG",
+    components: ["kai-chat", "kai-sources"],
+    defaultPlacement: "full-page",
+    docsSlug: "examples/knowledge-base"
+  },
+  {
+    id: "agentic",
+    title: "Agentic assistant",
+    components: ["kai-chat", "kai-tool", "kai-reasoning"],
+    defaultPlacement: "side",
+    docsSlug: "examples/agentic-assistant"
+  },
+  {
+    id: "workspace",
+    title: "Agentic workspace",
+    components: ["kai-chat", "kai-artifact", "kai-resizable"],
+    defaultPlacement: "side",
+    docsSlug: "examples/workspace"
+  },
+  {
+    id: "voice",
+    title: "Voice assistant",
+    components: ["kai-chat", "kai-voice-input"],
+    defaultPlacement: "full-page",
+    docsSlug: "examples/voice-assistant"
+  }
+];
+const integrations = [
+  openrouter,
+  vercelAiSdk,
+  langgraph,
+  cloudflare,
+  ollama,
+  mastra,
+  pi,
+  pydanticAi,
+  mock
+];
+const archetypes = archetypes$1;
+function getIntegration(id) {
+  return integrations.find((i) => i.id === id);
+}
+function getArchetype(id) {
+  return archetypes.find((a) => a.id === id);
+}
+function listIntegrations() {
+  return integrations;
+}
+function listArchetypes() {
+  return archetypes;
+}
+const text = (s) => ({
+  content: [{ type: "text", text: s }]
+});
+const FLEX_FILL = "flex: 1; min-height: 0;";
+function placementStyle(placement) {
+  switch (placement) {
+    case "full-page":
+      return {
+        style: "height: 100dvh; width: 100%; display: flex; flex-direction: column;",
+        chatFill: FLEX_FILL,
+        note: "fills the viewport (100dvh)"
+      };
+    case "inline":
+      return {
+        style: "width: 100%; max-width: 720px; height: 540px; margin: 0 auto; display: flex; flex-direction: column;",
+        chatFill: FLEX_FILL,
+        note: "in-flow block (sized by parent, not fixed)"
+      };
+    case "side":
+      return {
+        style: "position: fixed; top: 0; inset-inline-end: 0; height: 100dvh; width: 380px; border-inline-start: 1px solid var(--kai-color-border); display: flex; flex-direction: column; z-index: 1000;",
+        chatFill: FLEX_FILL,
+        note: "full-height side panel, docked to the trailing edge (100dvh)",
+        altNote: "In-flow alternative (push content instead of overlay): drop `position`/`z-index` and make this a `flex: 0 0 380px` column inside a `display: flex` row at `height: 100dvh`."
+      };
+    case "docked-widget":
+      return {
+        style: "position: fixed; bottom: 1.5rem; inset-inline-end: 1.5rem; width: 380px; height: 600px; max-height: calc(100dvh - 3rem); border-radius: 16px; overflow: hidden; box-shadow: 0 12px 32px var(--kai-shadow-color, rgba(0,0,0,0.18)); display: flex; flex-direction: column; z-index: 1000;",
+        chatFill: FLEX_FILL,
+        note: "fixed, floating bottom-right widget"
+      };
+    default:
+      return {
+        style: "height: 100dvh; width: 100%; display: flex; flex-direction: column;",
+        chatFill: FLEX_FILL,
+        note: "fills the viewport (100dvh)"
+      };
+  }
+}
+const DEFAULT_SUGGESTIONS = ["What's new?", "How can you help?"];
+const MOCK_REPLY = "Hi! I'm a local preview — no backend or API key needed. Swap `integration` for a real provider (openrouter, ollama, …) and I'll talk to a real model.";
+function jsArray(items) {
+  return "[" + items.map((s) => JSON.stringify(s)).join(", ") + "]";
+}
+function mockStreamBody(opts) {
+  const { pad, read, commitInitial, commitMap, setLoading, strictRoles = false } = opts;
+  const asConst = strictRoles ? " as const" : "";
+  const mapBody = `(m.id === assistantId ? { ...m, content: answer } : m)`;
+  return [
+    `${pad}const value = e.detail.value.trim();`,
+    `${pad}if (!value) return;`,
+    `${pad}const history = [...${read}, { id: crypto.randomUUID(), role: 'user'${asConst}, content: value }];`,
+    `${pad}const assistantId = crypto.randomUUID();`,
+    `${pad}${commitInitial(`[...history, { id: assistantId, role: 'assistant'${asConst}, content: '' }]`)}`,
+    `${pad}${setLoading("true")}`,
+    `${pad}// No backend: stream a canned reply client-side, one token at a time.`,
+    `${pad}const reply = ${JSON.stringify(MOCK_REPLY)};`,
+    `${pad}const tokens = reply.split(/(\\s+)/);`,
+    `${pad}let answer = '';`,
+    `${pad}for (const tok of tokens) {`,
+    `${pad}  await new Promise((r) => setTimeout(r, 24));`,
+    `${pad}  answer += tok;`,
+    `${pad}  // new array + object reference per chunk so kai-chat re-renders`,
+    `${pad}  ${commitMap(mapBody)}`,
+    `${pad}}`,
+    `${pad}${setLoading("false")}`
+  ].join("\n");
+}
+function defaultModelFor(integration) {
+  const routeSrc = Object.values(integration.routeTemplates).join("\n");
+  if (!routeSrc.includes("model")) return void 0;
+  const defaults = {
+    openrouter: "openai/gpt-4o-mini",
+    ollama: "llama3.2",
+    "vercel-ai-sdk": "openai/gpt-4o-mini",
+    cloudflare: "openai/gpt-4o-mini"
+  };
+  return defaults[integration.id] ?? "openai/gpt-4o-mini";
+}
+const MESSAGE_EMBEDDED_TAGS = /* @__PURE__ */ new Set(["kai-tool", "kai-reasoning"]);
+const WORKSPACE_STRUCTURAL_TAGS = /* @__PURE__ */ new Set(["kai-resizable", "kai-artifact"]);
+function isWorkspace(archetype) {
+  return archetype.components.includes("kai-resizable") && archetype.components.includes("kai-artifact");
+}
+const SAMPLE_AGENTIC_MESSAGE = {
+  id: "sample-assistant",
+  role: "assistant",
+  content: "Searched the web for current pricing.",
+  reasoning: { text: "I should call the search tool to get up-to-date data." },
+  tools: [
+    {
+      type: "search",
+      state: "output-available",
+      input: { query: "current pricing" },
+      output: { results: ["Result A", "Result B"] },
+      toolCallId: "tc_001"
+    }
+  ]
+};
+function componentTags(archetype, chatFill) {
+  if (isWorkspace(archetype)) {
+    return [
+      `  <!-- SCAF-14: workspace split — chat pane left, artifact preview right. -->`,
+      `  <!-- kai-resizable needs kai-resizable-item children to render panels. -->`,
+      `  <kai-resizable orientation="horizontal" style="display:block;width:100%;height:100%">`,
+      `    <kai-resizable-item size="40%" min="240px">`,
+      `      <kai-chat id="chat" suggestion-mode="submit" style="${chatFill}"></kai-chat>`,
+      `    </kai-resizable-item>`,
+      `    <kai-resizable-item min="280px">`,
+      `      <!-- Replace src with your artifact URL or set .files for multi-file preview. -->`,
+      `      <kai-artifact id="artifact" src="https://example.com" style="width:100%;height:100%"></kai-artifact>`,
+      `    </kai-resizable-item>`,
+      `  </kai-resizable>`
+    ].join("\n");
+  }
+  const companionTags = archetype.components.filter(
+    (t) => t !== "kai-chat" && !MESSAGE_EMBEDDED_TAGS.has(t) && !WORKSPACE_STRUCTURAL_TAGS.has(t)
+  );
+  const hasEmbedded = archetype.components.some((t) => MESSAGE_EMBEDDED_TAGS.has(t));
+  const hasStandaloneCompanions = companionTags.length > 0;
+  const lines = [];
+  lines.push(`  <kai-chat id="chat" suggestion-mode="submit" style="${chatFill}"></kai-chat>`);
+  if (hasEmbedded) {
+    lines.push(
+      `  <!-- kai-tool / kai-reasoning render INSIDE the thread, not as siblings.`,
+      `       Seed messages with { tools: [...], reasoning: { text: '...' } } — see the sample in the script below. -->`
+    );
+  }
+  for (const tag of companionTags) {
+    if (tag === "kai-sources") {
+      lines.push(
+        `  <!-- Replace sampleSources with your data. -->`,
+        `  <kai-sources id="sources"></kai-sources>`
+      );
+    } else {
+      lines.push(`  <${tag}></${tag}>`);
+    }
+  }
+  if (hasStandaloneCompanions) {
+    lines.push(`  <!-- wire data props — see the component_reference MCP tool -->`);
+  }
+  return lines.join("\n");
+}
+function htmlWiring(ctx, archetype) {
+  const hasEmbedded = archetype.components.some((t) => MESSAGE_EMBEDDED_TAGS.has(t));
+  const hasSources = archetype.components.includes("kai-sources");
+  const seedLines = hasEmbedded ? [
+    `    // SCAF-9: tool calls + reasoning render INSIDE the thread — set them on the message object.`,
+    `    // Replace this sample with real messages from your backend.`,
+    `    chat.messages = [${JSON.stringify(SAMPLE_AGENTIC_MESSAGE, null, 0)}];`,
+    ``
+  ] : [];
+  const sourcesSetupLines = hasSources ? [
+    `    const sourcesEl = document.getElementById('sources');`,
+    `    // Replace with your real source data (set as a JS property — it's an array).`,
+    `    const sampleSources = [`,
+    `      { href: 'https://example.com/doc1', title: 'Getting started', description: 'Overview of the product.' },`,
+    `      { href: 'https://example.com/doc2', title: 'API reference', description: 'Full API documentation.' },`,
+    `    ];`,
+    `    sourcesEl.sources = sampleSources;`,
+    ``
+  ] : [];
+  const head = [
+    `  <script type="module">`,
+    `    import '@kitn.ai/ui/elements';  // registers <kai-*> — required, must come first`,
+    `    import '@kitn.ai/ui/theme.tokens.css';  // compiled token defaults; use theme.css only for Tailwind-source apps`,
+    ``,
+    `    // Guard: module scripts run before the DOM is ready when inlined in <head>.`,
+    `    // DOMContentLoaded fires synchronously when already loaded; otherwise waits.`,
+    `    async function init() {`,
+    `      const chat = document.getElementById('chat');`,
+    `      // SCAF-15: kai-* register via an async dynamic import (SSR-safety), so the`,
+    `      // element may not be upgraded yet. Wait for the upgrade before setting any`,
+    `      // array/object property — values set pre-upgrade are dropped on upgrade.`,
+    `      await customElements.whenDefined('kai-chat');`,
+    `      // suggestions is a JS PROPERTY (arrays can't be HTML attributes)`,
+    `      chat.suggestions = ${jsArray(ctx.suggestions)};`,
+    `      chat.suggestionMode = 'submit';`,
+    ``,
+    ...seedLines.map((l) => l.trim() === "" ? l : `  ${l}`),
+    ...sourcesSetupLines.map((l) => l.trim() === "" ? l : `  ${l}`)
+  ];
+  const domReadyFooter = [
+    `    }`,
+    `    if (document.readyState === 'loading') {`,
+    `      document.addEventListener('DOMContentLoaded', init);`,
+    `    } else {`,
+    `      init();`,
+    `    }`
+  ];
+  if (ctx.isMock) {
+    const body = mockStreamBody({
+      pad: "        ",
+      read: "chat.messages",
+      commitInitial: (expr) => `chat.messages = ${expr};`,
+      // chat.messages is live (no React snapshot) — map over it directly
+      commitMap: (mapBody) => `chat.messages = chat.messages.map((m) => ${mapBody});`,
+      setLoading: (v) => `chat.loading = ${v};`
+    });
+    return [
+      ...head,
+      `      // No backend: stream a canned reply client-side (no fetch, no API key).`,
+      `      chat.addEventListener('kai-submit', async (e) => {`,
+      body,
+      `      });`,
+      ...domReadyFooter,
+      `  <\/script>`
+    ].join("\n");
+  }
+  const modelLines = ctx.defaultModel ? [
+    `        // SCAF-8: change this model id to any provider/model string you want to use.`,
+    `        const model = '${ctx.defaultModel}';`,
+    ``
+  ] : [];
+  const bodyPayload = ctx.defaultModel ? `{ model, messages: history.map((m) => ({ role: m.role, content: m.content })) }` : `{ messages: history.map((m) => ({ role: m.role, content: m.content })) }`;
+  return [
+    ...head,
+    `      chat.addEventListener('kai-submit', async (e) => {`,
+    `        const value = e.detail.value.trim();`,
+    `        if (!value) return;`,
+    ``,
+    ...modelLines,
+    `        // messages is a JS PROPERTY (objects can't be HTML attributes)`,
+    `        const history = [...chat.messages, { id: crypto.randomUUID(), role: 'user', content: value }];`,
+    `        const assistantId = crypto.randomUUID();`,
+    `        chat.messages = [...history, { id: assistantId, role: 'assistant', content: '' }];`,
+    `        chat.loading = true;`,
+    ``,
+    `        const res = await fetch('/api/chat', {`,
+    `          method: 'POST',`,
+    `          headers: { 'Content-Type': 'application/json' },`,
+    `          body: JSON.stringify(${bodyPayload}),`,
+    `        });`,
+    ``,
+    `        // Read the OpenAI-format SSE and stream it into the assistant message.`,
+    `        // This loop is the Streaming recipe — copy its exact body if you need keep-alive handling.`,
+    `        const reader = res.body.getReader();`,
+    `        const decoder = new TextDecoder();`,
+    `        let buffer = '', answer = '';`,
+    `        while (true) {`,
+    `          const { value: chunk, done } = await reader.read();`,
+    `          if (done) break;`,
+    `          buffer += decoder.decode(chunk, { stream: true });`,
+    `          const lines = buffer.split('\\n');`,
+    `          buffer = lines.pop();`,
+    `          for (const line of lines) {`,
+    `            const s = line.trim();`,
+    `            if (!s.startsWith('data:')) continue;`,
+    `            const payload = s.slice(5).trim();`,
+    `            if (payload === '[DONE]') continue;`,
+    `            try {`,
+    `              const delta = JSON.parse(payload).choices?.[0]?.delta?.content;`,
+    `              if (!delta) continue;`,
+    `              answer += delta;`,
+    `              chat.messages = chat.messages.map((m) => (m.id === assistantId ? { ...m, content: answer } : m));`,
+    `            } catch { /* skip keep-alive lines */ }`,
+    `          }`,
+    `        }`,
+    `        chat.loading = false;`,
+    `      });`,
+    ...domReadyFooter,
+    `  <\/script>`
+  ].join("\n");
+}
+function renderHtml(archetype, ctx) {
+  const { p, emptyHint } = ctx;
+  return [
+    `<!-- ${archetype.title} — ${p.note} -->`,
+    ...p.altNote ? [`<!-- ${p.altNote} -->`] : [],
+    `<div style="${p.style}">`,
+    componentTags(archetype, p.chatFill),
+    `</div>`,
+    ``,
+    htmlWiring(ctx, archetype),
+    ``,
+    `  <!-- empty-state hint: ${emptyHint} -->`
+  ].join("\n");
+}
+function toPascalCase(tag) {
+  return tag.replace(/^kai-/, "").split("-").map((s) => s.charAt(0).toUpperCase() + s.slice(1)).join("");
+}
+function renderJsx(archetype, ctx, framework) {
+  const { p, emptyHint, suggestions, isMock, defaultModel } = ctx;
+  const hasEmbedded = archetype.components.some((t) => MESSAGE_EMBEDDED_TAGS.has(t));
+  const workspace = isWorkspace(archetype);
+  const renderableTags = archetype.components.filter((t) => !MESSAGE_EMBEDDED_TAGS.has(t));
+  const importTags = workspace ? [.../* @__PURE__ */ new Set([...renderableTags.filter((t) => t !== "kai-resizable"), "kai-resizable", "kai-resizable-item"])] : renderableTags;
+  const wrapperNames = importTags.map(toPascalCase);
+  const importList = wrapperNames.join(", ");
+  const standaloneCompanionTags = archetype.components.filter(
+    (t) => t !== "kai-chat" && !MESSAGE_EMBEDDED_TAGS.has(t) && !WORKSPACE_STRUCTURAL_TAGS.has(t)
+  );
+  const companionJsxLines = [];
+  if (hasEmbedded) {
+    companionJsxLines.push(
+      `      {/* kai-tool / kai-reasoning render inside the thread. Tool calls + reasoning`,
+      `          are set on each message object — see the sampleMessages initializer above. */}`
+    );
+  }
+  for (const t of standaloneCompanionTags) {
+    if (t === "kai-sources") {
+      companionJsxLines.push(
+        `      {/* Replace sampleSources with your real data. */}`,
+        `      <Sources sources={sampleSources} />`
+      );
+    } else {
+      companionJsxLines.push(`      {/* wire data props — see the component_reference MCP tool */}`);
+      companionJsxLines.push(`      <${toPascalCase(t)} />`);
+    }
+  }
+  const companions = companionJsxLines.join("\n");
+  const chatMessageType = `type ChatMessage = { id: string; role: 'user' | 'assistant'; content: string; reasoning?: { text: string; label?: string }; tools?: { type: string; state: 'input-streaming' | 'input-available' | 'output-available' | 'output-error'; input?: Record<string, unknown>; output?: Record<string, unknown>; toolCallId?: string }[] };`;
+  const sampleMessagesInit = hasEmbedded ? [
+    `  // SCAF-9: tool calls and reasoning render inside the thread — set them on the message object.`,
+    `  // Replace with real messages streamed from your backend.`,
+    `  const sampleMessages: ChatMessage[] = [${JSON.stringify(SAMPLE_AGENTIC_MESSAGE)}];`,
+    `  const [messages, setMessages] = useState<ChatMessage[]>(sampleMessages);`
+  ].join("\n") : `  const [messages, setMessages] = useState<ChatMessage[]>([]);`;
+  const sampleSourcesInit = standaloneCompanionTags.includes("kai-sources") ? [
+    `  // Replace sampleSources with your real source data.`,
+    `  const sampleSources = [`,
+    `    { href: 'https://example.com/doc1', title: 'Getting started', description: 'Overview of the product.' },`,
+    `    { href: 'https://example.com/doc2', title: 'API reference', description: 'Full API documentation.' },`,
+    `  ];`
+  ].join("\n") : "";
+  const modelInit = defaultModel ? `  // SCAF-8: change this to any provider/model string you want to use.
+  const model = '${defaultModel}';` : "";
+  const bodyPayload = defaultModel ? `{ model, messages: history.map((m) => ({ role: m.role, content: m.content })) }` : `{ messages: history.map((m) => ({ role: m.role, content: m.content })) }`;
+  const onSubmitBody = isMock ? mockStreamBody({
+    pad: "    ",
+    read: "messages",
+    commitInitial: (expr) => `setMessages(${expr});`,
+    // functional updater so each token maps over the LATEST array, not the snapshot
+    commitMap: (mapBody) => `setMessages((prev) => prev.map((m) => ${mapBody}));`,
+    setLoading: (v) => `setLoading(${v});`,
+    strictRoles: true
+  }) : [
+    `    const value = e.detail.value.trim();`,
+    `    if (!value) return;`,
+    `    const history: ChatMessage[] = [...messages, { id: crypto.randomUUID(), role: 'user' as const, content: value }];`,
+    `    const assistantId = crypto.randomUUID();`,
+    `    setMessages([...history, { id: assistantId, role: 'assistant' as const, content: '' }]);`,
+    `    setLoading(true);`,
+    `    const res = await fetch('/api/chat', {`,
+    `      method: 'POST',`,
+    `      headers: { 'Content-Type': 'application/json' },`,
+    `      body: JSON.stringify(${bodyPayload}),`,
+    `    });`,
+    `    // Stream the OpenAI-format SSE into the assistant message — see the Streaming recipe.`,
+    `    const reader = res.body!.getReader();`,
+    `    const decoder = new TextDecoder();`,
+    `    let buffer = '', answer = '';`,
+    `    while (true) {`,
+    `      const { value: chunk, done } = await reader.read();`,
+    `      if (done) break;`,
+    `      buffer += decoder.decode(chunk, { stream: true });`,
+    `      const lines = buffer.split('\\n');`,
+    `      buffer = lines.pop()!;`,
+    `      for (const line of lines) {`,
+    `        const s = line.trim();`,
+    `        if (!s.startsWith('data:')) continue;`,
+    `        const payload = s.slice(5).trim();`,
+    `        if (payload === '[DONE]') continue;`,
+    `        try {`,
+    `          const delta = JSON.parse(payload).choices?.[0]?.delta?.content;`,
+    `          if (!delta) continue;`,
+    `          answer += delta;`,
+    `          setMessages((ms) => ms.map((m) => (m.id === assistantId ? { ...m, content: answer } : m)));`,
+    `        } catch { /* skip keep-alives */ }`,
+    `      }`,
+    `    }`,
+    `    setLoading(false);`
+  ].join("\n");
+  const useClientDirective = framework === "next" ? [`'use client';`, ``] : [];
+  if (framework === "next") {
+    const dynamicImports = wrapperNames.map(
+      (name) => `const ${name} = dynamic(() => import('@kitn.ai/ui/react').then((m) => m.${name}), { ssr: false });`
+    );
+    const nextConfigNote2 = [];
+    return [
+      // 'use client' must be the very first line for Next.js App Router.
+      ...useClientDirective,
+      `import { useState } from 'react';`,
+      `import dynamic from 'next/dynamic';`,
+      `import '@kitn.ai/ui/theme.tokens.css';  // compiled token defaults; use theme.css only for Tailwind-source apps`,
+      `// kai-* bundle Solid's client runtime → load client-only so SSR/prerender doesn't crash`,
+      ...dynamicImports,
+      ``,
+      ...nextConfigNote2,
+      `// ${archetype.title} — ${p.note}. empty-state hint: ${emptyHint}`,
+      ...p.altNote ? [`// ${p.altNote}`] : [],
+      chatMessageType,
+      ``,
+      `export default function App() {`,
+      sampleMessagesInit,
+      `  const [loading, setLoading] = useState(false);`,
+      `  const suggestions = ${jsArray(suggestions)};`,
+      ...sampleSourcesInit ? [sampleSourcesInit] : [],
+      ...modelInit ? [modelInit] : [],
+      ``,
+      `  async function onSubmit(e: CustomEvent<{ value: string }>) {`,
+      onSubmitBody,
+      `  }`,
+      ``,
+      `  return (`,
+      `    <div style={{ ${jsxStyle(p.style)} }}>`,
+      ...workspace ? [
+        `      {/* SCAF-14: workspace split — chat pane left, artifact preview right. */}`,
+        `      {/* Resizable needs ResizableItem children to render panels. */}`,
+        `      <Resizable orientation="horizontal" style={{ display: 'block', width: '100%', height: '100%' }}>`,
+        `        <ResizableItem size="40%" min="240px">`,
+        `          <Chat`,
+        `            messages={messages}`,
+        `            loading={loading}`,
+        `            suggestions={suggestions}`,
+        `            suggestionMode="submit"`,
+        `            onSubmit={onSubmit}`,
+        `            style={{ ${jsxStyle(p.chatFill)} }}`,
+        `          />`,
+        `        </ResizableItem>`,
+        `        <ResizableItem min="280px">`,
+        `          {/* Replace src with your artifact URL or set files for multi-file preview. */}`,
+        `          <Artifact src="https://example.com" style={{ width: '100%', height: '100%' }} />`,
+        `        </ResizableItem>`,
+        `      </Resizable>`
+      ] : [
+        `      <Chat`,
+        `        messages={messages}`,
+        `        loading={loading}`,
+        `        suggestions={suggestions}`,
+        `        suggestionMode="submit"`,
+        `        onSubmit={onSubmit}`,
+        `        style={{ ${jsxStyle(p.chatFill)} }}`,
+        `      />`,
+        companions
+      ],
+      `    </div>`,
+      `  );`,
+      `}`
+    ].filter((l) => l !== "").join("\n");
+  }
+  const nextConfigNote = [];
+  return [
+    // SCAF-2: 'use client' must be the very first line for Next.js App Router.
+    ...useClientDirective,
+    // (1) REQUIRED: registers <kai-*> — the react wrappers do NOT auto-register.
+    // Must come BEFORE importing the wrappers, or <kai-chat> renders empty.
+    `import '@kitn.ai/ui/elements';  // registers <kai-*> — required, must come first`,
+    `import { useState } from 'react';`,
+    `import { ${importList} } from '@kitn.ai/ui/react';`,
+    `import '@kitn.ai/ui/theme.tokens.css';  // compiled token defaults; use theme.css only for Tailwind-source apps`,
+    ``,
+    ...nextConfigNote,
+    `// ${archetype.title} — ${p.note}. empty-state hint: ${emptyHint}`,
+    ...p.altNote ? [`// ${p.altNote}`] : [],
+    chatMessageType,
+    ``,
+    `export default function App() {`,
+    sampleMessagesInit,
+    `  const [loading, setLoading] = useState(false);`,
+    `  const suggestions = ${jsArray(suggestions)};`,
+    ...sampleSourcesInit ? [sampleSourcesInit] : [],
+    ...modelInit ? [modelInit] : [],
+    ``,
+    `  async function onSubmit(e: CustomEvent<{ value: string }>) {`,
+    onSubmitBody,
+    `  }`,
+    ``,
+    `  return (`,
+    `    <div style={{ ${jsxStyle(p.style)} }}>`,
+    ...workspace ? [
+      `      {/* SCAF-14: workspace split — chat pane left, artifact preview right. */}`,
+      `      {/* Resizable needs ResizableItem children to render panels. */}`,
+      `      <Resizable orientation="horizontal" style={{ display: 'block', width: '100%', height: '100%' }}>`,
+      `        <ResizableItem size="40%" min="240px">`,
+      `          <Chat`,
+      `            messages={messages}`,
+      `            loading={loading}`,
+      `            suggestions={suggestions}`,
+      `            suggestionMode="submit"`,
+      `            onSubmit={onSubmit}`,
+      `            style={{ ${jsxStyle(p.chatFill)} }}`,
+      `          />`,
+      `        </ResizableItem>`,
+      `        <ResizableItem min="280px">`,
+      `          {/* Replace src with your artifact URL or set files for multi-file preview. */}`,
+      `          <Artifact src="https://example.com" style={{ width: '100%', height: '100%' }} />`,
+      `        </ResizableItem>`,
+      `      </Resizable>`
+    ] : [
+      `      <Chat`,
+      `        messages={messages}`,
+      `        loading={loading}`,
+      `        suggestions={suggestions}`,
+      `        suggestionMode="submit"`,
+      `        onSubmit={onSubmit}`,
+      `        style={{ ${jsxStyle(p.chatFill)} }}`,
+      `      />`,
+      companions
+    ],
+    `    </div>`,
+    `  );`,
+    `}`
+  ].filter((l) => l !== "").join("\n");
+}
+function renderVue(archetype, ctx) {
+  const { p, emptyHint, suggestions, isMock, defaultModel } = ctx;
+  const workspace = isWorkspace(archetype);
+  const standaloneCompanionTags = archetype.components.filter(
+    (t) => t !== "kai-chat" && !MESSAGE_EMBEDDED_TAGS.has(t) && !WORKSPACE_STRUCTURAL_TAGS.has(t)
+  );
+  const hasEmbedded = archetype.components.some((t) => MESSAGE_EMBEDDED_TAGS.has(t));
+  const companionLines = [];
+  if (hasEmbedded) {
+    companionLines.push(
+      `    <!-- kai-tool / kai-reasoning render INSIDE the thread — set tools/reasoning on each message object. -->`
+    );
+  }
+  for (const t of standaloneCompanionTags) {
+    if (t === "kai-sources") {
+      companionLines.push(`    <!-- Replace sampleSources with your real data (set as a JS property). -->`);
+      companionLines.push(`    <kai-sources ref="sourcesEl" />`);
+    } else {
+      companionLines.push(`    <!-- wire data props — see the component_reference MCP tool -->`);
+      companionLines.push(`    <${t} />`);
+    }
+  }
+  const companions = companionLines.join("\n");
+  const bodyPayload = defaultModel ? `{ model, messages: history.map((m) => ({ role: m.role, content: m.content })) }` : `{ messages: history.map((m) => ({ role: m.role, content: m.content })) }`;
+  const onSubmitBody = isMock ? mockStreamBody({
+    pad: "    ",
+    read: "messages.value",
+    commitInitial: (expr) => `messages.value = ${expr};`,
+    // messages.value is live — map over it directly
+    commitMap: (mapBody) => `messages.value = messages.value.map((m) => ${mapBody});`,
+    setLoading: (v) => `loading.value = ${v};`,
+    strictRoles: true
+  }) : [
+    `    const value = e.detail.value.trim();`,
+    `    if (!value) return;`,
+    `    const history: ChatMessage[] = [...messages.value, { id: crypto.randomUUID(), role: 'user' as const, content: value }];`,
+    `    const assistantId = crypto.randomUUID();`,
+    `    messages.value = [...history, { id: assistantId, role: 'assistant' as const, content: '' }];`,
+    `    loading.value = true;`,
+    `    // POST to /api/chat, then stream the OpenAI-format SSE into the`,
+    `    // assistant message (reassign messages.value per chunk) — see the Streaming recipe.`,
+    ...defaultModel ? [
+      `    // SCAF-8: change this to any provider/model string you want to use.`,
+      `    const model = '${defaultModel}';`
+    ] : [],
+    `    const res = await fetch('/api/chat', {`,
+    `      method: 'POST',`,
+    `      headers: { 'Content-Type': 'application/json' },`,
+    `      body: JSON.stringify(${bodyPayload}),`,
+    `    });`,
+    `    // Stream the OpenAI-format SSE — see the Streaming recipe.`,
+    `    const reader = res.body.getReader();`,
+    `    const decoder = new TextDecoder();`,
+    `    let buffer = '', answer = '';`,
+    `    while (true) {`,
+    `      const { value: chunk, done } = await reader.read();`,
+    `      if (done) break;`,
+    `      buffer += decoder.decode(chunk, { stream: true });`,
+    `      const lines = buffer.split('\\n');`,
+    `      buffer = lines.pop();`,
+    `      for (const line of lines) {`,
+    `        const s = line.trim();`,
+    `        if (!s.startsWith('data:')) continue;`,
+    `        const payload = s.slice(5).trim();`,
+    `        if (payload === '[DONE]') continue;`,
+    `        try {`,
+    `          const delta = JSON.parse(payload).choices?.[0]?.delta?.content;`,
+    `          if (!delta) continue;`,
+    `          answer += delta;`,
+    `          messages.value = messages.value.map((m) => (m.id === assistantId ? { ...m, content: answer } : m));`,
+    `        } catch { /* skip keep-alives */ }`,
+    `      }`,
+    `    }`,
+    `    loading.value = false;`
+  ].join("\n");
+  const chatMessageType = `type ChatMessage = { id: string; role: 'user' | 'assistant'; content: string; reasoning?: { text: string; label?: string }; tools?: { type: string; state: 'input-streaming' | 'input-available' | 'output-available' | 'output-error'; input?: Record<string, unknown>; output?: Record<string, unknown>; toolCallId?: string }[] };`;
+  const sampleSeed = hasEmbedded ? [
+    `// SCAF-9: tool calls + reasoning render inside the thread — set them on the message object.`,
+    `// Replace with real messages streamed from your backend.`,
+    `const messages = ref<ChatMessage[]>([${JSON.stringify(SAMPLE_AGENTIC_MESSAGE)}]);`
+  ] : [`const messages = ref<ChatMessage[]>([]);`];
+  const sourcesSeed = standaloneCompanionTags.includes("kai-sources") ? [
+    `// Replace sampleSources with your real source data.`,
+    `const sampleSources = [`,
+    `  { href: 'https://example.com/doc1', title: 'Getting started', description: 'Overview of the product.' },`,
+    `  { href: 'https://example.com/doc2', title: 'API reference', description: 'Full API documentation.' },`,
+    `];`,
+    `onMounted(() => {`,
+    `  const el = document.querySelector('kai-sources');`,
+    `  if (el) el.sources = sampleSources;`,
+    `});`
+  ] : [];
+  const vueImports = `import { ref, onMounted } from 'vue';`;
+  const workspaceTemplate = workspace ? [
+    `    <!-- SCAF-14: workspace split — chat pane left, artifact preview right. -->`,
+    `    <!-- kai-resizable needs kai-resizable-item children to render panels. -->`,
+    `    <kai-resizable orientation="horizontal" style="display:block;width:100%;height:100%">`,
+    `      <kai-resizable-item size="40%" min="240px">`,
+    `        <kai-chat`,
+    `          :messages.prop="messages"`,
+    `          :loading.prop="loading"`,
+    `          :suggestions.prop="suggestions"`,
+    `          suggestion-mode="submit"`,
+    `          style="${p.chatFill}"`,
+    `          @kai-submit="onSubmit"`,
+    `        ></kai-chat>`,
+    `      </kai-resizable-item>`,
+    `      <kai-resizable-item min="280px">`,
+    `        <!-- Replace src with your artifact URL or set .files for multi-file preview. -->`,
+    `        <kai-artifact src="https://example.com" style="width:100%;height:100%"></kai-artifact>`,
+    `      </kai-resizable-item>`,
+    `    </kai-resizable>`
+  ] : [
+    `    <kai-chat`,
+    `      :messages.prop="messages"`,
+    `      :loading.prop="loading"`,
+    `      :suggestions.prop="suggestions"`,
+    `      suggestion-mode="submit"`,
+    `      style="${p.chatFill}"`,
+    `      @kai-submit="onSubmit"`,
+    `    ></kai-chat>`,
+    companions
+  ];
+  return [
+    `<!-- vue — ${archetype.title} — ${p.note}. empty-state hint: ${emptyHint} -->`,
+    ...p.altNote ? [`<!-- ${p.altNote} -->`] : [],
+    `<!-- SCAF-3: vite.config.ts — tell Vue that kai-* are custom elements (not Vue components).`,
+    `     Without this, Vue warns "Unknown custom element" and .prop bindings may misbehave.`,
+    `     import vue from '@vitejs/plugin-vue';`,
+    `     export default { plugins: [vue({ template: { compilerOptions: { isCustomElement: (tag) => tag.startsWith('kai-') } } })] }; -->`,
+    `<script setup lang="ts">`,
+    `import '@kitn.ai/ui/elements';  // registers <kai-*> — required, must come first`,
+    `import '@kitn.ai/ui/theme.tokens.css';  // compiled token defaults; use theme.css only for Tailwind-source apps`,
+    vueImports,
+    ``,
+    chatMessageType,
+    ``,
+    ...sampleSeed,
+    `const loading = ref(false);`,
+    `const suggestions = ${jsArray(suggestions)};`,
+    ...sourcesSeed,
+    ``,
+    `// SCAF-15: kai-* register via an async dynamic import (SSR-safety). The .prop`,
+    `// bindings can apply before the element upgrades, which drops them — re-apply once`,
+    `// the element is defined so the initial messages/suggestions/loading stick.`,
+    `onMounted(async () => {`,
+    `  await customElements.whenDefined('kai-chat');`,
+    `  const el = document.querySelector('kai-chat');`,
+    `  if (el) Object.assign(el, { messages: messages.value, loading: loading.value, suggestions });`,
+    `});`,
+    ``,
+    `async function onSubmit(e: CustomEvent<{ value: string }>) {`,
+    onSubmitBody,
+    `}`,
+    `<\/script>`,
+    ``,
+    `<template>`,
+    `  <div style="${p.style}">`,
+    ...workspaceTemplate,
+    `  </div>`,
+    `</template>`
+  ].filter((l) => l !== "").join("\n");
+}
+function renderSvelte(archetype, ctx) {
+  const { p, emptyHint, suggestions, isMock, defaultModel } = ctx;
+  const workspace = isWorkspace(archetype);
+  const standaloneCompanionTags = archetype.components.filter(
+    (t) => t !== "kai-chat" && !MESSAGE_EMBEDDED_TAGS.has(t) && !WORKSPACE_STRUCTURAL_TAGS.has(t)
+  );
+  const hasEmbedded = archetype.components.some((t) => MESSAGE_EMBEDDED_TAGS.has(t));
+  const companionLinesList = [];
+  if (hasEmbedded) {
+    companionLinesList.push(
+      `  <!-- kai-tool / kai-reasoning render INSIDE the thread — set tools/reasoning on each message object. -->`
+    );
+  }
+  for (const t of standaloneCompanionTags) {
+    if (t === "kai-sources") {
+      companionLinesList.push(`  <!-- Replace sampleSources with your real data. -->`);
+      companionLinesList.push(`  <kai-sources bind:this={sourcesEl}></kai-sources>`);
+    } else {
+      companionLinesList.push(`  <!-- wire data props — see the component_reference MCP tool -->`);
+      companionLinesList.push(`  <${t}></${t}>`);
+    }
+  }
+  const companionLines = companionLinesList.join("\n");
+  const bodyPayload = defaultModel ? `{ model, messages: history.map((m) => ({ role: m.role, content: m.content })) }` : `{ messages: history.map((m) => ({ role: m.role, content: m.content })) }`;
+  const onSubmitBody = isMock ? mockStreamBody({
+    pad: "    ",
+    read: "messages",
+    commitInitial: (expr) => `messages = ${expr};`,
+    // `messages` is a live local — reassign to map over the latest array
+    commitMap: (mapBody) => `messages = messages.map((m) => ${mapBody});`,
+    setLoading: (v) => `loading = ${v};`,
+    strictRoles: true
+  }) : [
+    `    const value = e.detail.value.trim();`,
+    `    if (!value) return;`,
+    `    const history = [...messages, { id: crypto.randomUUID(), role: 'user' as const, content: value }];`,
+    `    const assistantId = crypto.randomUUID();`,
+    `    messages = [...history, { id: assistantId, role: 'assistant' as const, content: '' }];`,
+    `    loading = true;`,
+    ...defaultModel ? [
+      `    // SCAF-8: change this to any provider/model string you want to use.`,
+      `    const model = '${defaultModel}';`
+    ] : [],
+    `    const res = await fetch('/api/chat', {`,
+    `      method: 'POST',`,
+    `      headers: { 'Content-Type': 'application/json' },`,
+    `      body: JSON.stringify(${bodyPayload}),`,
+    `    });`,
+    `    // Stream the OpenAI-format SSE into the assistant message — see the Streaming recipe.`,
+    `    const reader = res.body.getReader();`,
+    `    const decoder = new TextDecoder();`,
+    `    let buffer = '', answer = '';`,
+    `    while (true) {`,
+    `      const { value: chunk, done } = await reader.read();`,
+    `      if (done) break;`,
+    `      buffer += decoder.decode(chunk, { stream: true });`,
+    `      const lines = buffer.split('\\n');`,
+    `      buffer = lines.pop();`,
+    `      for (const line of lines) {`,
+    `        const s = line.trim();`,
+    `        if (!s.startsWith('data:')) continue;`,
+    `        const payload = s.slice(5).trim();`,
+    `        if (payload === '[DONE]') continue;`,
+    `        try {`,
+    `          const delta = JSON.parse(payload).choices?.[0]?.delta?.content;`,
+    `          if (!delta) continue;`,
+    `          answer += delta;`,
+    `          messages = messages.map((m) => (m.id === assistantId ? { ...m, content: answer } : m));`,
+    `        } catch { /* skip keep-alives */ }`,
+    `      }`,
+    `    }`,
+    `    loading = false;`
+  ].join("\n");
+  const chatMessageType = `  type ChatMessage = { id: string; role: 'user' | 'assistant'; content: string; reasoning?: { text: string; label?: string }; tools?: { type: string; state: 'input-streaming' | 'input-available' | 'output-available' | 'output-error'; input?: Record<string, unknown>; output?: Record<string, unknown>; toolCallId?: string }[] };`;
+  const sampleMessagesInit = hasEmbedded ? [
+    `  // SCAF-9: tool calls + reasoning render INSIDE the thread — set them on the message object.`,
+    `  // Replace with real messages streamed from your backend.`,
+    `  let messages: ChatMessage[] = [${JSON.stringify(SAMPLE_AGENTIC_MESSAGE)}];`
+  ] : [`  let messages: ChatMessage[] = [];`];
+  const sourcesEl = standaloneCompanionTags.includes("kai-sources") ? [`  let sourcesEl: HTMLElement | undefined;`] : [];
+  const sourcesReactive = standaloneCompanionTags.includes("kai-sources") ? [
+    `  // Replace sampleSources with your real source data.`,
+    `  const sampleSources = [`,
+    `    { href: 'https://example.com/doc1', title: 'Getting started', description: 'Overview of the product.' },`,
+    `    { href: 'https://example.com/doc2', title: 'API reference', description: 'Full API documentation.' },`,
+    `  ];`,
+    `  $: if (sourcesEl) { sourcesEl.sources = sampleSources; }`
+  ] : [];
+  const workspaceMarkup = workspace ? [
+    `  <!-- SCAF-14: workspace split — chat pane left, artifact preview right. -->`,
+    `  <!-- kai-resizable needs kai-resizable-item children to render panels. -->`,
+    `  <kai-resizable orientation="horizontal" style="display:block;width:100%;height:100%">`,
+    `    <kai-resizable-item size="40%" min="240px">`,
+    `      <kai-chat bind:this={chatEl} suggestion-mode="submit" style="${p.chatFill}" on:kai-submit={onSubmit}></kai-chat>`,
+    `    </kai-resizable-item>`,
+    `    <kai-resizable-item min="280px">`,
+    `      <!-- Replace src with your artifact URL or set .files for multi-file preview. -->`,
+    `      <kai-artifact src="https://example.com" style="width:100%;height:100%"></kai-artifact>`,
+    `    </kai-resizable-item>`,
+    `  </kai-resizable>`
+  ] : [
+    `  <kai-chat bind:this={chatEl} suggestion-mode="submit" style="${p.chatFill}" on:kai-submit={onSubmit}></kai-chat>`,
+    companionLines
+  ];
+  return [
+    `<!-- svelte — ${archetype.title} — ${p.note}. empty-state hint: ${emptyHint} -->`,
+    ...p.altNote ? [`<!-- ${p.altNote} -->`] : [],
+    `<!-- SCAF-5: This uses Svelte-4 syntax ($:, on:event). Works in Svelte 5 via legacy mode;`,
+    `     runes-mode users should adapt to $state/$effect and onkai-submit event handlers. -->`,
+    `<script lang="ts">`,
+    `  import '@kitn.ai/ui/elements';  // registers <kai-*> — required, must come first`,
+    `  import type { KaiChatElement } from '@kitn.ai/ui/elements';`,
+    `  import '@kitn.ai/ui/theme.tokens.css';  // compiled token defaults; use theme.css only for Tailwind-source apps`,
+    `  import { onMount } from 'svelte';`,
+    chatMessageType,
+    `  let chatEl: KaiChatElement | undefined;`,
+    `  // SCAF-15: kai-* register via an async dynamic import (SSR-safety). Gate the`,
+    `  // reactive property block on the upgrade so the first application isn't dropped`,
+    `  // (props set on a not-yet-upgraded element are lost on upgrade).`,
+    `  let defined = false;`,
+    `  onMount(async () => { await customElements.whenDefined('kai-chat'); defined = true; });`,
+    ...sourcesEl,
+    ...sampleMessagesInit,
+    `  let loading: boolean = false;`,
+    `  const suggestions: string[] = ${jsArray(suggestions)};`,
+    `  // suggestions/messages are JS PROPERTIES (arrays/objects can't be attributes)`,
+    `  $: if (chatEl && defined) { chatEl.messages = messages; chatEl.loading = loading; chatEl.suggestions = suggestions; }`,
+    ...sourcesReactive,
+    ``,
+    `  async function onSubmit(e: CustomEvent<{ value: string }>) {`,
+    onSubmitBody,
+    `  }`,
+    `<\/script>`,
+    ``,
+    `<div style="${p.style}">`,
+    ...workspaceMarkup,
+    `</div>`
+  ].filter((l, i, arr) => !(l === "" && arr[i - 1] === "" && i === arr.length - 1)).join("\n");
+}
+function renderTanstackStart(archetype, ctx) {
+  const { p, emptyHint, suggestions, isMock, defaultModel } = ctx;
+  const hasEmbedded = archetype.components.some((t) => MESSAGE_EMBEDDED_TAGS.has(t));
+  const workspace = isWorkspace(archetype);
+  const renderableTags = archetype.components.filter((t) => !MESSAGE_EMBEDDED_TAGS.has(t));
+  const importTags = workspace ? [.../* @__PURE__ */ new Set([...renderableTags.filter((t) => t !== "kai-resizable"), "kai-resizable", "kai-resizable-item"])] : renderableTags;
+  const wrapperNames = importTags.map(toPascalCase);
+  const importList = wrapperNames.join(", ");
+  const standaloneCompanionTags = archetype.components.filter(
+    (t) => t !== "kai-chat" && !MESSAGE_EMBEDDED_TAGS.has(t) && !WORKSPACE_STRUCTURAL_TAGS.has(t)
+  );
+  const companionJsxLines = [];
+  if (hasEmbedded) {
+    companionJsxLines.push(
+      `      {/* kai-tool / kai-reasoning render inside the thread. Tool calls + reasoning`,
+      `          are set on each message object — see the sampleMessages initializer above. */}`
+    );
+  }
+  for (const t of standaloneCompanionTags) {
+    if (t === "kai-sources") {
+      companionJsxLines.push(
+        `      {/* Replace sampleSources with your real data. */}`,
+        `      <Sources sources={sampleSources} />`
+      );
+    } else {
+      companionJsxLines.push(`      {/* wire data props — see the component_reference MCP tool */}`);
+      companionJsxLines.push(`      <${toPascalCase(t)} />`);
+    }
+  }
+  const companions = companionJsxLines.join("\n");
+  const chatMessageType = `type ChatMessage = { id: string; role: 'user' | 'assistant'; content: string; reasoning?: { text: string; label?: string }; tools?: { type: string; state: 'input-streaming' | 'input-available' | 'output-available' | 'output-error'; input?: Record<string, unknown>; output?: Record<string, unknown>; toolCallId?: string }[] };`;
+  const sampleMessagesInit = hasEmbedded ? [
+    `  // SCAF-9: tool calls and reasoning render inside the thread — set them on the message object.`,
+    `  // Replace with real messages streamed from your backend.`,
+    `  const sampleMessages: ChatMessage[] = [${JSON.stringify(SAMPLE_AGENTIC_MESSAGE)}];`,
+    `  const [messages, setMessages] = useState<ChatMessage[]>(sampleMessages);`
+  ].join("\n") : `  const [messages, setMessages] = useState<ChatMessage[]>([]);`;
+  const sampleSourcesInit = standaloneCompanionTags.includes("kai-sources") ? [
+    `  // Replace sampleSources with your real source data.`,
+    `  const sampleSources = [`,
+    `    { href: 'https://example.com/doc1', title: 'Getting started', description: 'Overview of the product.' },`,
+    `    { href: 'https://example.com/doc2', title: 'API reference', description: 'Full API documentation.' },`,
+    `  ];`
+  ].join("\n") : "";
+  const modelInit = defaultModel ? `  // SCAF-8: change this to any provider/model string you want to use.
+  const model = '${defaultModel}';` : "";
+  const bodyPayload = defaultModel ? `{ model, messages: history.map((m) => ({ role: m.role, content: m.content })) }` : `{ messages: history.map((m) => ({ role: m.role, content: m.content })) }`;
+  const onSubmitBody = isMock ? mockStreamBody({
+    pad: "    ",
+    read: "messages",
+    commitInitial: (expr) => `setMessages(${expr});`,
+    commitMap: (mapBody) => `setMessages((prev) => prev.map((m) => ${mapBody}));`,
+    setLoading: (v) => `setLoading(${v});`,
+    strictRoles: true
+  }) : [
+    `    const value = e.detail.value.trim();`,
+    `    if (!value) return;`,
+    `    const history: ChatMessage[] = [...messages, { id: crypto.randomUUID(), role: 'user' as const, content: value }];`,
+    `    const assistantId = crypto.randomUUID();`,
+    `    setMessages([...history, { id: assistantId, role: 'assistant' as const, content: '' }]);`,
+    `    setLoading(true);`,
+    `    const res = await fetch('/api/chat', {`,
+    `      method: 'POST',`,
+    `      headers: { 'Content-Type': 'application/json' },`,
+    `      body: JSON.stringify(${bodyPayload}),`,
+    `    });`,
+    `    // Stream the OpenAI-format SSE into the assistant message — see the Streaming recipe.`,
+    `    const reader = res.body!.getReader();`,
+    `    const decoder = new TextDecoder();`,
+    `    let buffer = '', answer = '';`,
+    `    while (true) {`,
+    `      const { value: chunk, done } = await reader.read();`,
+    `      if (done) break;`,
+    `      buffer += decoder.decode(chunk, { stream: true });`,
+    `      const lines = buffer.split('\\n');`,
+    `      buffer = lines.pop()!;`,
+    `      for (const line of lines) {`,
+    `        const s = line.trim();`,
+    `        if (!s.startsWith('data:')) continue;`,
+    `        const payload = s.slice(5).trim();`,
+    `        if (payload === '[DONE]') continue;`,
+    `        try {`,
+    `          const delta = JSON.parse(payload).choices?.[0]?.delta?.content;`,
+    `          if (!delta) continue;`,
+    `          answer += delta;`,
+    `          setMessages((ms) => ms.map((m) => (m.id === assistantId ? { ...m, content: answer } : m)));`,
+    `        } catch { /* skip keep-alives */ }`,
+    `      }`,
+    `    }`,
+    `    setLoading(false);`
+  ].join("\n");
+  const filePathNote = [
+    `// TanStack Start route file — save as: src/routes/chat.tsx`,
+    `// Scaffold command: npx @tanstack/cli@latest create <app-name> --framework react --no-git --package-manager npm -y`,
+    `// Then: npm install @kitn.ai/ui`,
+    `// Dev: npm run dev (port 3000)  Build: npm run build  Preview: npm run preview`,
+    `// Note: there is no 'npm start' script — use 'npm run dev' or 'npm run preview'.`,
+    `// Backend: place TanStack server functions in src/server/chat.ts (createServerFn).`,
+    ``
+  ];
+  return [
+    ...filePathNote,
+    // TanStack Start uses @tanstack/react-router's createFileRoute
+    `import { createFileRoute } from '@tanstack/react-router'`,
+    `import { useState } from 'react'`,
+    // Elements registration: the library is SSR-import-safe; top-level import is safe here
+    `import '@kitn.ai/ui/elements';  // registers <kai-*> — required, must come first`,
+    `import { ${importList} } from '@kitn.ai/ui/react'`,
+    `import '@kitn.ai/ui/theme.tokens.css'  // compiled token defaults`,
+    ``,
+    `// ${archetype.title} — ${p.note}. empty-state hint: ${emptyHint}`,
+    ...p.altNote ? [`// ${p.altNote}`] : [],
+    chatMessageType,
+    ``,
+    `// ssr: false keeps the Solid-based web component client-only.`,
+    `// Server HTML for /chat omits <kai-chat> → no hydration mismatch.`,
+    `export const Route = createFileRoute('/chat')({`,
+    `  ssr: false,`,
+    `  component: ChatPage,`,
+    `})`,
+    ``,
+    `function ChatPage() {`,
+    sampleMessagesInit,
+    `  const [loading, setLoading] = useState(false);`,
+    `  const suggestions = ${jsArray(suggestions)};`,
+    ...sampleSourcesInit ? [sampleSourcesInit] : [],
+    ...modelInit ? [modelInit] : [],
+    ``,
+    `  async function onSubmit(e: CustomEvent<{ value: string }>) {`,
+    onSubmitBody,
+    `  }`,
+    ``,
+    `  return (`,
+    `    <main style={{ ${jsxStyle(p.style)} }}>`,
+    ...workspace ? [
+      `      {/* SCAF-14: workspace split — chat pane left, artifact preview right. */}`,
+      `      {/* Resizable needs ResizableItem children to render panels. */}`,
+      `      <Resizable orientation="horizontal" style={{ display: 'block', width: '100%', height: '100%' }}>`,
+      `        <ResizableItem size="40%" min="240px">`,
+      `          <Chat`,
+      `            messages={messages}`,
+      `            loading={loading}`,
+      `            suggestions={suggestions}`,
+      `            suggestionMode="submit"`,
+      `            onSubmit={onSubmit}`,
+      `            style={{ ${jsxStyle(p.chatFill)} }}`,
+      `          />`,
+      `        </ResizableItem>`,
+      `        <ResizableItem min="280px">`,
+      `          {/* Replace src with your artifact URL or set files for multi-file preview. */}`,
+      `          <Artifact src="https://example.com" style={{ width: '100%', height: '100%' }} />`,
+      `        </ResizableItem>`,
+      `      </Resizable>`
+    ] : [
+      `      <Chat`,
+      `        messages={messages}`,
+      `        loading={loading}`,
+      `        suggestions={suggestions}`,
+      `        suggestionMode="submit"`,
+      `        onSubmit={onSubmit}`,
+      `        style={{ ${jsxStyle(p.chatFill)} }}`,
+      `      />`,
+      companions
+    ],
+    `    </main>`,
+    `  );`,
+    `}`
+  ].filter((l) => l !== "").join("\n");
+}
+function jsxStyle(style) {
+  return style.split(";").map((d) => d.trim()).filter(Boolean).map((d) => {
+    const [prop, ...rest] = d.split(":");
+    const camel = prop.trim().replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+    return `${camel}: '${rest.join(":").trim()}'`;
+  }).join(", ");
+}
+function renderFrontend(framework, archetype, placement, emptyHint, suggestions, isMock, defaultModel) {
+  const ctx = { p: placementStyle(placement), emptyHint, suggestions, isMock, defaultModel };
+  switch (framework) {
+    case "react":
+    case "next":
+      return renderJsx(archetype, ctx, framework);
+    case "vue":
+      return renderVue(archetype, ctx);
+    case "svelte":
+      return renderSvelte(archetype, ctx);
+    case "tanstack-start":
+      return renderTanstackStart(archetype, ctx);
+    case "html":
+    default:
+      return renderHtml(archetype, ctx);
+  }
+}
+const RUNTIME_LABEL = {
+  next: "Next.js route handler (Node/Edge)",
+  express: "Express handler (Node)",
+  worker: "Cloudflare Worker",
+  fastapi: "FastAPI (Python)",
+  html: "browser-direct (no server route)",
+  "tanstack-start": "TanStack Start server function (Node)"
+};
+function preferredKeyFor(integration) {
+  return integration.language === "python" ? ["fastapi"] : ["next", "express", "worker"];
+}
+function chooseRoute(integration, framework) {
+  const templates = integration.routeTemplates;
+  if (templates[framework]) {
+    return { framework, template: templates[framework], runtime: RUNTIME_LABEL[framework] ?? framework, exact: true };
+  }
+  for (const key of preferredKeyFor(integration)) {
+    if (templates[key]) {
+      return { framework: key, template: templates[key], runtime: RUNTIME_LABEL[key] ?? key, exact: false };
+    }
+  }
+  for (const [key, template] of Object.entries(templates)) {
+    if (key === "html") continue;
+    return { framework: key, template, runtime: RUNTIME_LABEL[key] ?? key, exact: false };
+  }
+  return void 0;
+}
+function compose(archetype, integration, placement, framework, suggestions, audience) {
+  const audienceHint = audience ? `tuned for ${audience} — keep the empty state and tone audience-appropriate` : "add an empty-state prompt that fits your product";
+  const isMock = integration.id === "mock";
+  const defaultModel = isMock ? void 0 : defaultModelFor(integration);
+  const frontend = renderFrontend(framework, archetype, placement, audienceHint, suggestions, isMock, defaultModel);
+  const route = isMock ? void 0 : chooseRoute(integration, framework);
+  const header = [
+    `# AI/UI scaffold — ${archetype.title} × ${integration.title}`,
+    `combo: ${archetype.id} × ${integration.id} × ${placement} × ${framework}`,
+    `stream: ${integration.streamMapping}`
+  ].join("\n");
+  const block1 = [
+    `=== (1) FRONT-END (${framework}, ${placementStyle(placement).note}) ===`,
+    ``,
+    frontend
+  ].join("\n");
+  const block2Parts = [`=== (2) BACKEND ROUTE ===`, ``];
+  if (isMock) {
+    block2Parts.push(
+      `# No backend or API key needed — replies stream locally for preview (see the`,
+      `# front-end onSubmit above). Swap \`integration\` for a real provider (openrouter,`,
+      `# ollama, vercel-ai-sdk, …) when ready, and this block becomes its route handler.`
+    );
+  } else if (route) {
+    if (!route.exact) {
+      block2Parts.push(
+        `# Note: ${integration.title} has no template for "${framework}". Emitting its native`,
+        `# ${route.runtime} route instead (matches the integration's ${integration.language} language).`
+      );
+      if (framework === "react") {
+        block2Parts.push(
+          `#`,
+          `# WARNING: this is a Next.js route handler — it will NOT run in a Vite SPA`,
+          `# (a Vite \`react\` app has no /api routes). To make the front-end above work, either:`,
+          `#   • use Next.js (framework: "next"), or`,
+          `#   • add a Vite dev-server middleware/proxy to a server, or`,
+          `#   • run a separate server (framework: "express" | "worker"), or`,
+          `#   • use integration: "mock" for a zero-config local stream (no backend, no key).`
+        );
+      }
+      block2Parts.push(``);
+    } else {
+      block2Parts.push(`# Runtime: ${route.runtime}`, ``);
+    }
+    block2Parts.push(route.template);
+  } else {
+    block2Parts.push(
+      `# ${integration.title} ships no usable backend route template. See its docs`,
+      `# (${integration.docsSlug}) — wire the route by hand following the streamMapping above.`
+    );
+  }
+  const block2 = block2Parts.join("\n");
+  const envLines = integration.envVars.length ? integration.envVars.map((v) => `  - ${v}`).join("\n") : "  (none)";
+  const block3 = [
+    `=== (3) RUN NOTE ===`,
+    ``,
+    integration.runNote,
+    ``,
+    `Env vars to set:`,
+    envLines
+  ].join("\n");
+  return [header, block1, block2, block3].join("\n\n");
+}
+function rejectIntegration(id) {
+  const valid = listIntegrations().map((i) => `${i.id} (${i.title})`).join(", ");
+  return [
+    `Unknown integration: "${id}".`,
+    ``,
+    `Valid integrations: ${valid}.`,
+    `Pick one of those ids and call scaffold again.`
+  ].join("\n");
+}
+function rejectUseCase(id) {
+  const valid = listArchetypes().map((a) => `${a.id} (${a.title})`).join(", ");
+  return [
+    `Unknown useCase: "${id}".`,
+    ``,
+    `Valid useCases (archetypes): ${valid}.`,
+    `Pick one of those ids and call scaffold again.`
+  ].join("\n");
+}
+const scaffold = {
+  name: "scaffold",
+  description: 'Scaffold a working AI/UI chat surface from four axes: useCase (archetype) × integration × placement × framework. Emits a copy-pasteable front-end (kai-* components wired with messages + kai-submit + starter suggestions), the backend route for the chosen framework, and a run note with env vars. Use integration: "mock" for a zero-config local preview.',
+  inputSchema: z.object({
+    // useCase + integration are dynamic catalog ids — kept as strings and
+    // validated against the registry in the handler (the handler is called
+    // directly in tests, bypassing this schema). Use component_reference / the
+    // catalogs to discover valid ids.
+    useCase: z.string().describe(
+      'Archetype id, e.g. "drop-in-chat", "support-widget", "knowledge-base", "agentic", "workspace", "voice".'
+    ),
+    integration: z.string().describe(
+      'Backend integration id, e.g. "openrouter", "vercel-ai-sdk", "langgraph", "cloudflare", "ollama", "mastra", "pi", "pydantic-ai".'
+    ),
+    placement: Placement.describe(
+      "Where the surface lives: full-page | side | docked-widget | inline."
+    ),
+    framework: Framework.describe(
+      "Target front-end/back-end framework: html | react | next | vue | svelte | fastapi | express | worker | tanstack-start."
+    ),
+    suggestions: z.array(z.string()).optional().describe(
+      "Optional starter prompts shown above the input when the thread is empty (real kai-chat prop). Defaults to a generic pair if omitted so the feature always shows."
+    ),
+    audience: z.string().optional().describe("Optional audience hint (tweaks the empty-state comment only).")
+  }),
+  handler: async (args) => {
+    const useCase = String(args.useCase ?? "");
+    const integrationId = String(args.integration ?? "");
+    const placement = String(args.placement ?? "");
+    const framework = String(args.framework ?? "html");
+    const audience = args.audience ? String(args.audience) : void 0;
+    const suggestions = Array.isArray(args.suggestions) && args.suggestions.length > 0 ? args.suggestions.map(String) : DEFAULT_SUGGESTIONS;
+    const archetype = getArchetype(useCase);
+    if (!archetype) return text(rejectUseCase(useCase));
+    const integration = getIntegration(integrationId);
+    if (!integration) return text(rejectIntegration(integrationId));
+    const effectivePlacement = placement || archetype.defaultPlacement;
+    return text(compose(archetype, integration, effectivePlacement, framework, suggestions, audience));
+  }
+};
+function parseHex(hex) {
+  const s = hex.trim().replace(/^#/, "");
+  if (s.length === 3) {
+    const r = parseInt(s[0] + s[0], 16);
+    const g = parseInt(s[1] + s[1], 16);
+    const b = parseInt(s[2] + s[2], 16);
+    if (isNaN(r) || isNaN(g) || isNaN(b)) return null;
+    return { r, g, b };
+  }
+  if (s.length === 6) {
+    const r = parseInt(s.slice(0, 2), 16);
+    const g = parseInt(s.slice(2, 4), 16);
+    const b = parseInt(s.slice(4, 6), 16);
+    if (isNaN(r) || isNaN(g) || isNaN(b)) return null;
+    return { r, g, b };
+  }
+  return null;
+}
+function toHex(r, g, b) {
+  return "#" + [r, g, b].map((v) => Math.max(0, Math.min(255, Math.round(v))).toString(16).padStart(2, "0")).join("");
+}
+function relativeLuminance(r, g, b) {
+  const lin = (c) => {
+    const s = c / 255;
+    return s <= 0.04045 ? s / 12.92 : Math.pow((s + 0.055) / 1.055, 2.4);
+  };
+  return 0.2126 * lin(r) + 0.7152 * lin(g) + 0.0722 * lin(b);
+}
+function foreground(r, g, b) {
+  const lum = relativeLuminance(r, g, b);
+  const contrastWhite = 1.05 / (lum + 0.05);
+  const contrastBlack = (lum + 0.05) / 0.05;
+  return contrastWhite >= contrastBlack ? "#ffffff" : "#000000";
+}
+function lighten(r, g, b, ratio) {
+  return toHex(
+    r + (255 - r) * ratio,
+    g + (255 - g) * ratio,
+    b + (255 - b) * ratio
+  );
+}
+function darken(r, g, b, ratio) {
+  return toHex(r * (1 - ratio), g * (1 - ratio), b * (1 - ratio));
+}
+function accentSurface(r, g, b) {
+  return lighten(r, g, b, 0.88);
+}
+function darkModeBrand(r, g, b) {
+  const lum = relativeLuminance(r, g, b);
+  if (lum > 0.25) return toHex(r, g, b);
+  return lighten(r, g, b, 0.35);
+}
+function darkAccentSurface(r, g, b) {
+  return darken(r, g, b, 0.75);
+}
+const KEYWORD_COLORS = {
+  blue: "#3b82f6",
+  navy: "#1e3a8a",
+  sky: "#0ea5e9",
+  cyan: "#06b6d4",
+  teal: "#14b8a6",
+  green: "#22c55e",
+  emerald: "#10b981",
+  lime: "#84cc16",
+  yellow: "#eab308",
+  amber: "#f59e0b",
+  orange: "#f97316",
+  red: "#ef4444",
+  rose: "#f43f5e",
+  pink: "#ec4899",
+  purple: "#a855f7",
+  violet: "#7c3aed",
+  indigo: "#6366f1",
+  slate: "#64748b",
+  gray: "#6b7280",
+  zinc: "#71717a",
+  neutral: "#737373",
+  stone: "#78716c",
+  white: "#f8fafc",
+  black: "#0f172a"
+};
+const DEFAULT_BRAND = "#6366f1";
+function resolveBrand(brand, description) {
+  if (brand) {
+    const parsed2 = parseHex(brand);
+    if (parsed2) {
+      return { hex: brand.startsWith("#") ? brand : `#${brand}`, ...parsed2, note: "" };
+    }
+    const fallback = parseHex(DEFAULT_BRAND);
+    return {
+      hex: DEFAULT_BRAND,
+      ...fallback,
+      note: `Could not parse \`${brand}\` as a hex color — defaulted to **${DEFAULT_BRAND}** (indigo). Pass a valid \`#rgb\` or \`#rrggbb\` value to use your color.`
+    };
+  }
+  if (description) {
+    const lower = description.toLowerCase();
+    for (const [keyword, hex] of Object.entries(KEYWORD_COLORS)) {
+      if (lower.includes(keyword)) {
+        const parsed3 = parseHex(hex);
+        return {
+          hex,
+          ...parsed3,
+          note: `No brand color provided — inferred **${hex}** (${keyword}) from description. Override with \`brand: '#rrggbb'\` to use an exact color.`
+        };
+      }
+    }
+    const parsed2 = parseHex(DEFAULT_BRAND);
+    return {
+      hex: DEFAULT_BRAND,
+      ...parsed2,
+      note: `No recognizable color keyword in description — defaulted to **${DEFAULT_BRAND}** (indigo). Override with \`brand: '#rrggbb'\` for an exact color.`
+    };
+  }
+  const parsed = parseHex(DEFAULT_BRAND);
+  return {
+    hex: DEFAULT_BRAND,
+    ...parsed,
+    note: `No brand color or description provided — defaulted to **${DEFAULT_BRAND}** (indigo, the kit's own brand). Pass \`brand: '#rrggbb'\` to use your color.`
+  };
+}
+function buildTokenSet(r, g, b) {
+  const primary = toHex(r, g, b);
+  const primaryFg = foreground(r, g, b);
+  const accent = accentSurface(r, g, b);
+  const accentFgColor = foreground(
+    ...[accent].map((h) => parseHex(h)).flatMap((c) => [c.r, c.g, c.b])
+  );
+  return {
+    primary,
+    primaryFg,
+    ring: primary,
+    accent,
+    accentFg: accentFgColor
+  };
+}
+function buildDarkTokenSet(r, g, b) {
+  const darkBrand = darkModeBrand(r, g, b);
+  const parsed = parseHex(darkBrand);
+  const primary = darkBrand;
+  const primaryFg = foreground(parsed.r, parsed.g, parsed.b);
+  const accent = darkAccentSurface(r, g, b);
+  const accentFgParsed = parseHex(accent);
+  return {
+    primary,
+    primaryFg,
+    ring: darkBrand,
+    accent,
+    accentFg: foreground(accentFgParsed.r, accentFgParsed.g, accentFgParsed.b)
+  };
+}
+function cssBlock(selector, tokens) {
+  return [
+    `${selector} {`,
+    `  --kai-color-primary:             ${tokens.primary};`,
+    `  --kai-color-primary-foreground:  ${tokens.primaryFg};`,
+    `  --kai-color-ring:                ${tokens.ring};`,
+    `  --kai-color-accent:              ${tokens.accent};`,
+    `  --kai-color-accent-foreground:   ${tokens.accentFg};`,
+    `}`
+  ].join("\n");
+}
+const theme = {
+  name: "theme",
+  description: "Generate a --kai-* CSS token override block from a brand color or description. Paste the block into your global stylesheet to brand every kai-* element in one shot.",
+  inputSchema: z.object({
+    brand: z.string().optional().describe('Brand color as #rgb or #rrggbb hex (e.g. "#7c3aed")'),
+    description: z.string().optional().describe(
+      "Natural-language description of your product (used to infer a color when `brand` is omitted)"
+    ),
+    mode: z.enum(["light", "dark", "both"]).optional().describe(
+      '"light" → :root only (default); "dark" → .dark only; "both" → :root + .dark'
+    )
+  }),
+  handler: async (args) => {
+    const {
+      brand,
+      description,
+      mode = "light"
+    } = args;
+    const { hex, r, g, b, note } = resolveBrand(brand, description);
+    const lightTokens = buildTokenSet(r, g, b);
+    const darkTokens = buildDarkTokenSet(r, g, b);
+    const blocks = [];
+    if (mode === "light" || mode === "both") {
+      blocks.push(cssBlock(":root", lightTokens));
+    }
+    if (mode === "dark" || mode === "both") {
+      blocks.push(cssBlock(".dark", darkTokens));
+    }
+    const cssOutput = blocks.join("\n\n");
+    const noteLabel = note.startsWith("Could not parse") ? "Note" : "Assumption";
+    const noteSection = note ? `
+> **${noteLabel}:** ${note}
+` : "";
+    const text2 = `## AI/UI theme override — \`${hex}\`
+${noteSection}
+Paste this block into your **global stylesheet** (before the \`@import\` of \`@kitn.ai/ui\` or after — order doesn't matter since \`--kai-*\` tokens are resolved at runtime via \`var()\` fallbacks). For \`mode:'dark'\` overrides, the \`.dark\` class must be on a parent element (e.g. \`<html class="dark">\`) for them to take effect.
+
+\`\`\`css
+${cssOutput}
+\`\`\`
+
+### How it works
+
+The \`--kai-color-*\` tokens pierce the Shadow DOM via CSS custom-property inheritance. Every \`kai-*\` element reads them through a \`var(--kai-color-primary, <default>)\` fallback chain defined in \`theme.css\`. Setting them on \`:root\` (or a wrapper element) is enough to rebrand everything globally.
+
+**Tokens emitted** (verified names from \`theme.css\`):
+- \`--kai-color-primary\` — primary brand color
+- \`--kai-color-primary-foreground\` — AA-contrast foreground on primary (auto-selected black/white)
+- \`--kai-color-ring\` — keyboard focus ring
+- \`--kai-color-accent\` — tinted accent surface
+- \`--kai-color-accent-foreground\` — text on accent surface
+
+### Apply to a subtree only
+
+\`\`\`css
+/* scope to a specific container instead of :root */
+.my-chat-widget {
+${blocks[0]?.split("\n").slice(1, -1).map((l) => "  " + l).join("\n")}
+}
+\`\`\`
+
+### Fine-tune the full palette
+
+The theme editor lets you tweak every token interactively and copy the result:
+
+**→ [Open Theme Editor](https://ui.kitn.ai/theme/editor/)**
+
+For the complete token list see the [theming guide](https://ui.kitn.ai/guides/theming/) and the source \`theme.css\` in the package root.
+`;
+    return { content: [{ type: "text", text: text2 }] };
+  }
+};
+const RULES = [
+  {
+    // Rule 1 — array/object data set as an HTML attribute
+    // Source: for-ai-agents.mdx §1; context7.json rule 2
+    id: "array-as-attribute",
+    test: (t) => /\b(messages|models|context|suggestions|slashCommands)\s*=\s*["']/.test(t),
+    title: "Array/object prop set as an HTML attribute (silent failure)",
+    cause: "An HTML attribute is always a string. Passing `messages`, `models`, `context`, `suggestions`, or `slashCommands` as an HTML attribute silently fails — the element receives a stringified value it cannot parse.",
+    fix: "Set the property in JavaScript, not as an HTML attribute. Only scalar props (`placeholder`, `loading`, `theme`) work as attributes.\n\n```js\n// ✅ Works — set messages in JavaScript as a property\nconst chat = document.querySelector('kai-chat');\nchat.messages = [{ id: '1', role: 'assistant', content: 'Hello!' }];\n```\n\n```html\n<!-- ❌ Fails — messages cannot be an HTML attribute -->\n<kai-chat messages=\"[...]\"></kai-chat>\n```"
+  },
+  {
+    // Rule 2 — in-place mutation → no re-render
+    // Source: for-ai-agents.mdx §3; context7.json rule 4
+    id: "in-place-mutation",
+    test: (t) => /don'?t\s+update|doesn'?t\s+re.?render|no\s+re.?render|\.push\(|\bpush(?:es|ing)?\s+(?:to|into|onto)\b|mutate|in.place/.test(t),
+    title: "In-place mutation does not trigger a re-render",
+    cause: "Mutating an existing message object or array in place (e.g. `chat.messages.push(…)` or `chat.messages[i].content = …`) does not trigger a re-render. The element only reacts when it detects a new array/object reference.",
+    fix: "Assign a NEW array (and a new object) on every change — never mutate in place.\n\n```js\n// ✅ Triggers re-render — new array + new object reference\nchat.messages = [\n  ...chat.messages,\n  { id: crypto.randomUUID(), role: 'user', content: userText },\n];\n\n// ✅ During streaming — replace with a new array + new object on every chunk\nchat.messages = chat.messages.map((m) =>\n  m.id === assistantId ? { ...m, content: accumulated } : m\n);\n\n// ❌ Does NOT trigger re-render\nchat.messages.push(newMsg);\nchat.messages[i].content = accumulated;\n```"
+  },
+  {
+    // Rule 3 — listening for events on a parent / wrong element
+    // Source: for-ai-agents.mdx §2; context7.json rule 3
+    id: "event-bubbling",
+    test: (t) => /event.*not\s+fir|not\s+fir.*event|listen.*document|document.*listen|listen.*parent|parent.*listen|event.*bubbl/i.test(
+      t
+    ),
+    title: "Listening for events on the wrong element (events are non-bubbling)",
+    cause: "`kai-*` events are non-bubbling CustomEvents. Adding a listener to `document`, `window`, or a parent container will never fire because the event does not bubble up.",
+    fix: "Listen directly on the `kai-*` element. The submit event is `kai-submit` with `event.detail.value`.\n\n```js\nconst chat = document.querySelector('kai-chat');\n\n// ✅ Listen directly on the element\nchat.addEventListener('kai-submit', (e) => {\n  console.log(e.detail.value); // the text the user typed\n});\n\n// ❌ Never fires — kai-submit does not bubble\ndocument.addEventListener('kai-submit', handler);\n```\n\nCommon events: `kai-submit`, `kai-feedback`, `kai-model-change`, `kai-new-chat`, `kai-select`."
+  },
+  {
+    // Rule 4 — wrong element prefix kitn-
+    // Source: context7.json rule 1
+    id: "wrong-prefix",
+    test: (t) => /\bkitn-/.test(t),
+    title: "Wrong element prefix `kitn-` (should be `kai-`)",
+    cause: "The custom element prefix is `kai-` (e.g. `<kai-chat>`, `<kai-artifact>`). `kitn-chat` is only a bundle filename — it is not a registered element name. Using `<kitn-chat>` results in an unknown element that renders nothing.",
+    fix: "Replace the `kitn-` prefix with `kai-` everywhere.\n\n```html\n<!-- ✅ Correct element prefix -->\n<kai-chat></kai-chat>\n<kai-artifact></kai-artifact>\n\n<!-- ❌ Wrong — kitn-chat is a bundle filename, not an element -->\n<kitn-chat></kitn-chat>\n```"
+  },
+  {
+    // Rule 6 — custom elements not registered / renders nothing (React #1 failure)
+    // Source: field-test reports; for-ai-agents.mdx §"Import order matters"
+    id: "elements-not-registered",
+    test: (t) => {
+      if (/renders?\s+nothing|nothing\s+renders?|not\s+registered|unregistered|not\s+upgraded|unknown\s+element|customElements\.get|undefined\s+element|no\s+shadow\s+root/.test(t))
+        return true;
+      if (/\b(empty|blank)\b/.test(t) && /render|element|component|kai-|<[a-z]+-|shadow/.test(t))
+        return true;
+      if (/doesn'?t\s+render|won'?t\s+render/.test(t) && /kai-|element|component|custom.?element/.test(t))
+        return true;
+      return false;
+    },
+    title: "Custom elements not registered — renders nothing / empty box",
+    cause: "The `@kitn.ai/ui/react` wrappers (and bare `<kai-*>` tags) do NOT register the custom elements by themselves. Without the element-registration side-effect import, `<kai-chat>` / `<Chat>` is an un-upgraded unknown element — an empty box. `customElements.get('kai-chat') === undefined`.",
+    fix: "Import the elements bundle for its side effect BEFORE your first render — it must run before the component mounts.\n\n```tsx\nimport '@kitn.ai/ui/elements'   // registers <kai-*> — REQUIRED, must come first\nimport { Chat } from '@kitn.ai/ui/react'\nimport '@kitn.ai/ui/theme.css'\n```\n\nIn plain HTML: `import '@kitn.ai/ui/elements'` in your module script. The import is a side effect — keep it even if your linter flags it as \"unused\"."
+  },
+  {
+    // Rule 7 — tsc errors inside node_modules/@kitn.ai/ui/src (SolidJS source pulled in)
+    // Source: field-test reports; packaging gap (tracked upstream)
+    id: "tsc-source-pull",
+    test: (t) => /node_modules\/@kitn\.ai\/ui/.test(t) && /tsc|TS2786|cannot\s+be\s+used\s+as\s+a\s+jsx\s+component|Show\b|Portal\b|Dynamic\b|error\s+TS|type\s+error/.test(
+      t
+    ),
+    title: "tsc errors inside node_modules/@kitn.ai/ui/src (SolidJS source compiled under React)",
+    cause: "The package currently ships TypeScript/TSX source, and a type entry value-re-exports from it, so the consumer's `tsc` resolves and compiles the library's SolidJS internals (`src/ui/*.tsx`) under the app's React JSX config — `Show`/`Portal`/`Dynamic` aren't React components, causing TS2786 / \"cannot be used as a JSX component\" errors. `vite`/esbuild build fine (they strip types); only `tsc` breaks. `skipLibCheck` does not help (these are `.tsx` source, not `.d.ts`).",
+    fix: 'Redirect the type resolution for that subpath in your tsconfig (Vite ignores tsconfig `paths`, so runtime is unaffected):\n\n```jsonc\n// tsconfig (app)\n"baseUrl": ".",\n"paths": { "@kitn.ai/ui/elements": ["./src/stubs/kitn-elements.d.ts"] }\n```\n\n```ts\n// src/stubs/kitn-elements.d.ts\nexport {}\n```\n\n(This is a known packaging gap being tracked upstream.)'
+  },
+  {
+    // Rule 8 — fetch('/api/chat') 404 in a Vite SPA (no server-side routes)
+    // Source: field-test reports; common scaffold confusion
+    id: "vite-api-404",
+    test: (t) => {
+      if (/\/api\/chat/.test(t) && /\b404\b|not\s+found/i.test(t)) return true;
+      if (/\bvite\b/.test(t) && /api\s+route|route\s+handler|\bPOST\b.*not\s+work/.test(t)) return true;
+      if (/next\.?js.*route|route.*next\.?js/.test(t) && /\bvite\b/.test(t)) return true;
+      return false;
+    },
+    title: "fetch('/api/chat') 404 — Vite SPA has no server-side API routes",
+    cause: "A plain Vite/CRA React SPA has no server — there are no `/api` routes. A scaffolded Next.js route handler (`export async function POST`) does not run there, so `fetch('/api/chat')` 404s.",
+    fix: "Either run the backend somewhere real, or skip it entirely for local dev:\n\n```ts\n// Option A — use Next.js where route handlers are supported\n// app/api/chat/route.ts: export async function POST(req) { ... }\n\n// Option B — add a Vite dev-server middleware/proxy\n// vite.config.ts: server: { proxy: { '/api': 'http://localhost:3001' } }\n\n// Option C — run a separate Express/Hono server\n// framework: 'express' in your harness config\n\n// Option D — zero-config local dev with mock integration (no backend needed)\n// Use `integration: 'mock'` in the scaffold tool\n```"
+  },
+  {
+    // Rule 5 — SSR / server component / document is not defined
+    // Source: for-ai-agents.mdx (client-only import); context7.json rule 2 (property rule requires DOM)
+    id: "ssr-server-component",
+    test: (t) => {
+      if (/\bssr\b|server\s+component|document\s+is\s+not\s+defined|window\s+is\s+not\s+defined|next\.?js.*server|server.*next\.?js/.test(t)) return true;
+      if (/hydration/.test(t) && /kai|web.?component|custom.?element|<[a-z]+-/.test(t)) return true;
+      return false;
+    },
+    title: "SSR / server-side rendering — element requires the browser DOM",
+    cause: '`kai-*` elements are client-side web components. They require `document` and `customElements` to register and render. Importing them in a server component (Next.js App Router server component, Nuxt SSR, etc.) throws "document is not defined" or silently produces no output.',
+    fix: "Register the element on the client only. Use your framework's \"client-only\" / island / dynamic-import pattern.\n\n```js\n// ✅ Plain HTML / vanilla — import in a <script type=\"module\">\nimport '@kitn.ai/ui/elements';\n\n// ✅ Next.js App Router — mark the component with \"use client\"\n'use client';\nimport '@kitn.ai/ui/elements';\n\n// ✅ Next.js — dynamic import with ssr: false\nimport dynamic from 'next/dynamic';\nconst KaiChat = dynamic(() => import('@kitn.ai/ui/elements').then(() => 'kai-chat'), { ssr: false });\n\n// ✅ React wrapper (already client-safe)\nimport { Chat } from '@kitn.ai/ui/react';\n```"
+  }
+];
+function buildText(matched) {
+  if (matched.length === 0) {
+    return "No known failure pattern matched. Suggested next steps:\n\n1. Use the `component_reference` tool to look up the real API for the element (prop names, event names, attribute vs. property distinction).\n2. Check the **Streaming recipe** in `llms-full.txt` (`node_modules/@kitn.ai/ui/llms-full.txt` or https://ui.kitn.ai/llms-full.txt) for correct streaming wiring.\n3. Paste `https://ui.kitn.ai/llms.txt` into your prompt for a compact orientation.";
+  }
+  const sections = matched.map((rule, i) => {
+    const n = i + 1;
+    return `## ${n}. ${rule.title}
+
+**Cause:** ${rule.cause}
+
+**Fix:** ${rule.fix}`;
+  });
+  const header = matched.length === 1 ? "1 likely cause found:\n\n" : `${matched.length} likely causes found:
+
+`;
+  return header + sections.join("\n\n---\n\n");
+}
+const debug = {
+  name: "debug",
+  description: "Diagnose common AI/UI (kai-*) integration issues. Provide a `symptom` (prose description) and/or a `snippet` (code) and receive the likely cause + fix for classic kai-* failure modes.",
+  inputSchema: z.object({
+    symptom: z.string().optional(),
+    snippet: z.string().optional()
+  }),
+  handler: async (args) => {
+    const combined = `${args.symptom ?? ""} ${args.snippet ?? ""}`;
+    const matched = RULES.filter((rule) => rule.test(combined));
+    return {
+      content: [{ type: "text", text: buildText(matched) }]
+    };
+  }
+};
+const tools = [reference, scaffold, theme, debug];
+function createServer() {
+  const server = new Server(
+    { name: "@kitn.ai/ui", version: "0.15.0" },
+    { capabilities: { tools: {} } }
+  );
+  const byName = new Map(tools.map((t) => [t.name, t]));
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: tools.map((t) => ({
+      name: t.name,
+      description: t.description,
+      // The protocol requires a JSON Schema. We use zod 4's native converter
+      // (the repo is on zod 4); the SDK-bundled zod-to-json-schema only
+      // understands zod 3 and emits an empty schema for our zod 4 objects.
+      inputSchema: z.toJSONSchema(t.inputSchema)
+    }))
+  }));
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const tool = byName.get(request.params.name);
+    if (!tool) {
+      return {
+        isError: true,
+        content: [{ type: "text", text: `Unknown tool: ${request.params.name}` }]
+      };
+    }
+    return tool.handler(request.params.arguments ?? {});
+  });
+  server.__listToolsForTest = () => tools.map((t) => t.name);
+  return server;
+}
+async function startStdioServer() {
+  const server = createServer();
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+startStdioServer();
+export {
+  startStdioServer
+};