@kitn.ai/ui 0.15.0 → 0.16.0

package/src/agent-tooling/mcp/manifest.ts

@@ -0,0 +1,128 @@
+/**
+ * manifest.ts — reads dist/custom-elements.json (a Custom Elements Manifest)
+ * and exposes helpers for the component_reference tool.
+ *
+ * Resolution strategy (dual-context):
+ *  1. Bundled bin: dist/mcp.es.js lives in dist/, so custom-elements.json is
+ *     a sibling → try ./custom-elements.json relative to import.meta.url.
+ *  2. Vitest (source): manifest.ts lives in src/agent-tooling/mcp/, so we walk
+ *     up parent directories looking for <dir>/dist/custom-elements.json.
+ */
+
+import { readFileSync, existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { join, dirname } from 'node:path';
+
+// ── CEM types ────────────────────────────────────────────────────────────────
+
+export interface CemType {
+  text: string;
+}
+
+export interface CemMember {
+  kind: 'field' | 'method';
+  privacy?: 'public' | 'private' | 'protected';
+  name: string;
+  type?: CemType;
+  description?: string;
+}
+
+export interface CemAttribute {
+  name: string;
+  fieldName?: string;
+  type?: CemType;
+  description?: string;
+}
+
+export interface CemEvent {
+  name: string;
+  type?: CemType;
+  description?: string;
+}
+
+export interface CemCssProperty {
+  name: string;
+  description?: string;
+  default?: string;
+}
+
+export interface Declaration {
+  tagName?: string;
+  name: string;
+  kind: string;
+  description?: string;
+  members?: CemMember[];
+  attributes?: CemAttribute[];
+  events?: CemEvent[];
+  cssProperties?: CemCssProperty[];
+}
+
+interface CemModule {
+  path?: string;
+  declarations?: Declaration[];
+}
+
+interface CustomElementsManifest {
+  modules: CemModule[];
+}
+
+// ── Manifest resolution ───────────────────────────────────────────────────────
+
+function resolveManifestPath(): string {
+  const thisFile = fileURLToPath(import.meta.url);
+  const thisDir = dirname(thisFile);
+
+  // 1. Bundled bin: sibling in the same directory
+  const sibling = join(thisDir, 'custom-elements.json');
+  if (existsSync(sibling)) {
+    return sibling;
+  }
+
+  // 2. Source/Vitest: walk up parent directories looking for dist/custom-elements.json
+  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; // reached filesystem root
+    dir = parent;
+  }
+
+  throw new Error(
+    `Could not find custom-elements.json. Searched from: ${thisDir}`,
+  );
+}
+
+// ── Parsed manifest (module-level cache) ─────────────────────────────────────
+
+let _manifest: CustomElementsManifest | undefined;
+
+function getManifest(): CustomElementsManifest {
+  if (!_manifest) {
+    const path = resolveManifestPath();
+    const raw = readFileSync(path, 'utf-8');
+    _manifest = JSON.parse(raw) as CustomElementsManifest;
+  }
+  return _manifest;
+}
+
+function getDeclarations(): Declaration[] {
+  return getManifest().modules.flatMap((m) => m.declarations ?? []);
+}
+
+// ── Public API ────────────────────────────────────────────────────────────────
+
+/** Returns the Declaration for a given custom-element tag, or undefined. */
+export function getElement(tag: string): Declaration | undefined {
+  return getDeclarations().find((d) => d.tagName === tag);
+}
+
+/** Returns all custom-element tagNames, sorted alphabetically. */
+export function listElements(): string[] {
+  return getDeclarations()
+    .filter((d) => d.tagName)
+    .map((d) => d.tagName!)
+    .sort();
+}

package/src/agent-tooling/mcp/server.ts

@@ -0,0 +1,59 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+import { z } from 'zod';
+import { reference } from './tools/reference';
+import { scaffold } from './tools/scaffold';
+import { theme } from './tools/theme';
+import { debug } from './tools/debug';
+import type { Tool } from './tools/types';
+
+const tools: Tool[] = [reference, scaffold, theme, debug];
+
+/**
+ * The AI/UI MCP server. A stdio server (see ./stdio.ts) exposing the AI/UI tools
+ * to any MCP harness. Registers four tools; Tasks 2–5 fill in each handler.
+ *
+ * The returned `Server` is augmented with `__listToolsForTest()`, a test-only
+ * helper that returns the registered tool names without touching the transport.
+ */
+export interface AiUiServer extends Server {
+  __listToolsForTest(): string[];
+}
+
+export function createServer(): AiUiServer {
+  const server = new Server(
+    { name: '@kitn.ai/ui', version: '0.15.0' },
+    { capabilities: { tools: {} } },
+  ) as AiUiServer;
+
+  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) as Record<string, unknown>,
+    })),
+  }));
+
+  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;
+}

package/src/agent-tooling/mcp/stdio.ts

@@ -0,0 +1,18 @@
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createServer } from './server';
+
+/**
+ * Build entry for the AI/UI MCP server. Connects the server (./server.ts) to a
+ * stdio transport so any MCP harness (Claude Code, Codex, …) can drive it over
+ * stdin/stdout. Compiled to dist/mcp.es.js by vite.config.mcp.ts and launched by
+ * bin/mcp.js, which handles fatal errors / exit (this file stays free of Node
+ * globals so it typechecks under the repo's vite/client-only tsconfig).
+ */
+export async function startStdioServer(): Promise<void> {
+  const server = createServer();
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+// Auto-start when imported as the entry (the only consumer is bin/mcp.js).
+startStdioServer();

package/src/agent-tooling/mcp/tools/debug.ts

@@ -0,0 +1,305 @@
+import { z } from 'zod';
+import type { Tool } from './types';
+
+/**
+ * debug — diagnose common AI/UI (kai-*) integration failures.
+ *
+ * Given a `symptom` (prose) and/or a `snippet` (code), returns the likely
+ * cause + fix for the classic `kai-*` failure modes so a harness can
+ * self-correct without a human in the loop.
+ *
+ * Rule set sourced from:
+ *  - docs-site/src/content/docs/guides/for-ai-agents.mdx §"What agents most commonly get wrong"
+ *  - context7.json `rules` array (5 contract rules)
+ */
+
+interface Rule {
+  id: string;
+  test: (text: string) => boolean;
+  title: string;
+  cause: string;
+  fix: string;
+}
+
+const RULES: Rule[] = [
+  {
+    // 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\n" +
+      "const chat = document.querySelector('kai-chat');\n" +
+      "chat.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\n' +
+      'chat.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\n' +
+      'chat.messages = chat.messages.map((m) =>\n' +
+      '  m.id === assistantId ? { ...m, content: accumulated } : m\n' +
+      ');\n\n' +
+      '// ❌ Does NOT trigger re-render\n' +
+      'chat.messages.push(newMsg);\n' +
+      'chat.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\n' +
+      "const chat = document.querySelector('kai-chat');\n\n" +
+      "// ✅ Listen directly on the element\n" +
+      "chat.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\n" +
+      "document.addEventListener('kai-submit', handler);\n" +
+      '```\n\n' +
+      'Common 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) => {
+      // Core render-nothing / unregistered-element signals
+      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;
+      // "empty" / "blank" / "doesn't render" / "won't render" only fire when
+      // a render/element/component context is also present to avoid false positives
+      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\n' +
+      "import '@kitn.ai/ui/elements'   // registers <kai-*> — REQUIRED, must come first\n" +
+      "import { Chat } from '@kitn.ai/ui/react'\n" +
+      "import '@kitn.ai/ui/theme.css'\n" +
+      '```\n\n' +
+      'In 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\n' +
+      'export {}\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) => {
+      // /api/chat 404
+      if (/\/api\/chat/.test(t) && /\b404\b|not\s+found/i.test(t)) return true;
+      // Vite + missing API route / route handler / POST
+      if (/\bvite\b/.test(t) && /api\s+route|route\s+handler|\bPOST\b.*not\s+work/.test(t)) return true;
+      // Next.js route handler used in a Vite app
+      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) => {
+      // Core SSR signals — always trigger
+      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;
+      // "hydration" only triggers when a web-component / kai context is also present
+      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\">\n" +
+      "import '@kitn.ai/ui/elements';\n\n" +
+      '// ✅ Next.js App Router — mark the component with "use client"\n' +
+      "'use client';\n" +
+      "import '@kitn.ai/ui/elements';\n\n" +
+      '// ✅ Next.js — dynamic import with ssr: false\n' +
+      "import dynamic from 'next/dynamic';\n" +
+      "const KaiChat = dynamic(() => import('@kitn.ai/ui/elements').then(() => 'kai-chat'), { ssr: false });\n\n" +
+      '// ✅ React wrapper (already client-safe)\n' +
+      "import { Chat } from '@kitn.ai/ui/react';\n" +
+      '```',
+  },
+];
+
+function buildText(matched: Rule[]): string {
+  if (matched.length === 0) {
+    return (
+      'No known failure pattern matched. Suggested next steps:\n\n' +
+      '1. Use the `component_reference` tool to look up the real API for the element ' +
+      '(prop names, event names, attribute vs. property distinction).\n' +
+      '2. 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.\n' +
+      '3. 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}\n\n**Cause:** ${rule.cause}\n\n**Fix:** ${rule.fix}`;
+  });
+
+  const header =
+    matched.length === 1
+      ? '1 likely cause found:\n\n'
+      : `${matched.length} likely causes found:\n\n`;
+
+  return header + sections.join('\n\n---\n\n');
+}
+
+export const debug: Tool = {
+  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 as string | undefined) ?? ''} ${(args.snippet as string | undefined) ?? ''}`;
+    const matched = RULES.filter((rule) => rule.test(combined));
+
+    return {
+      content: [{ type: 'text', text: buildText(matched) }],
+    };
+  },
+};

package/src/agent-tooling/mcp/tools/reference.ts

@@ -0,0 +1,132 @@
+import { z } from 'zod';
+import type { Tool } from './types';
+import { getElement, listElements } from '../manifest';
+
+/**
+ * component_reference — look up AI/UI (kai-*) web components, their props,
+ * events, attributes, and CSS custom properties from the live Custom Elements
+ * Manifest (dist/custom-elements.json).
+ *
+ * Backed by manifest.ts which resolves the CEM in both the bundled bin
+ * (dist/mcp.es.js sibling) and the Vitest source context (walks up to find
+ * dist/custom-elements.json in the repo root).
+ */
+
+/** Types that warrant the JS-property contract note. */
+const JS_ONLY_TYPE_PATTERNS = /\[\]|\{|Record</;
+
+function isJsOnlyType(typeText: string | undefined): boolean {
+  return typeText ? JS_ONLY_TYPE_PATTERNS.test(typeText) : false;
+}
+
+function formatReference(tag: string): string {
+  const el = getElement(tag);
+
+  if (!el) {
+    const all = listElements();
+    const sample = all.slice(0, 5).join(', ');
+    return (
+      `Unknown element: ${tag}\n\n` +
+      `Valid tags include: ${sample} (and ${Math.max(0, all.length - 5)} more).\n` +
+      `Call component_reference with no name (or name: "list") to list all ${all.length} elements.`
+    );
+  }
+
+  const lines: string[] = [];
+
+  // ── Header ─────────────────────────────────────────────────────────────────
+  lines.push(`## <${tag}>`);
+  if (el.description) {
+    lines.push('', el.description.trim());
+  }
+
+  // ── Contract note ──────────────────────────────────────────────────────────
+  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.',
+  );
+
+  // ── Public JS properties ───────────────────────────────────────────────────
+  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}`);
+      }
+    }
+  }
+
+  // ── HTML attributes ────────────────────────────────────────────────────────
+  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}`);
+      }
+    }
+  }
+
+  // ── Events ────────────────────────────────────────────────────────────────
+  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}`);
+    }
+  }
+
+  // ── CSS custom properties ─────────────────────────────────────────────────
+  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');
+}
+
+export const reference: Tool = {
+  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: Record<string, unknown>) => {
+    const name = typeof args.name === 'string' ? args.name.trim() : undefined;
+
+    let text: string;
+
+    if (!name || name === 'list') {
+      const tags = listElements();
+      text =
+        `AI/UI elements (${tags.length} total):\n\n` +
+        tags.map((t) => `  ${t}`).join('\n') +
+        '\n\nCall component_reference with a specific name (e.g. { name: "kai-chat" }) for full API details.';
+    } else {
+      text = formatReference(name);
+    }
+
+    return { content: [{ type: 'text' as const, text }] };
+  },
+};