create-kai 0.1.0

package/dist/templates/vanilla/src/view.ts

@@ -0,0 +1,222 @@
+import type { ChatMessage } from '@kitn.ai/ui';
+import { partsToText } from '@kitn.ai/ui/state';
+import type { AppState, Theme } from './state';
+import { SUGGESTIONS, TRIGGERS, type Conversation } from './chat-data';
+import { createVoiceInput } from './voice-input';
+
+/**
+ * The whole view: builds the hand-composed `kai-*` workspace imperatively, wires
+ * every element's CustomEvents, and returns a `render(state)` that syncs app state
+ * onto element properties. There is no framework here, so this file owns the two
+ * cross-framework gotchas directly:
+ *
+ *  1. UPGRADE RACE. main.ts `await customElements.whenDefined(...)` BEFORE calling
+ *     createView, so every element created below is already upgraded and the
+ *     array/object PROPERTIES we set (messages, conversations, triggers) land.
+ *  2. BOOLEAN FLAGS as PROPERTIES. `promptInput.voice = true`, not a bare `voice`
+ *     attribute (the facade's flag() reads a value-less attribute as false).
+ *
+ * The composed split is <kai-resizable>/<kai-resizable-item> (sidebar | main), the
+ * sidebar is <kai-conversations>, the messages are a <kai-thread>, and the composer
+ * is a <kai-prompt-input>. Scalars (theme, placeholder, active-id) go on as
+ * attributes; arrays/objects go on as properties.
+ */
+
+// Custom-element property shapes we set from render (typed so we avoid `any`).
+type ConversationsEl = HTMLElement & { groups?: unknown[]; conversations?: Conversation[]; collapsed?: boolean };
+type ThreadEl = HTMLElement & { messages?: ChatMessage[] };
+type PromptEl = HTMLElement & {
+  value?: unknown;
+  clear?: () => void;
+  loading?: boolean;
+  suggestions?: string[];
+  triggers?: unknown[];
+  voice?: boolean;
+};
+type ItemEl = HTMLElement & { collapsed?: boolean };
+
+export interface ViewCallbacks {
+  onConversationSelect(id: string): void;
+  onNewChat(): void;
+  onToggleSidebar(): void;
+  onShowSidebar(): void;
+  onToggleTheme(): void;
+  onSubmit(value: string): void;
+  onSuggestion(value: string): void;
+}
+
+export interface View {
+  render(state: AppState): void;
+}
+
+/** Tiny hyperscript: create an element, set string attributes, append children. */
+function el(tag: string, attrs: Record<string, string> = {}, children: (Node | string)[] = []): HTMLElement {
+  const node = document.createElement(tag);
+  for (const [k, v] of Object.entries(attrs)) node.setAttribute(k, v);
+  node.append(...children);
+  return node;
+}
+
+/** Parse an inline SVG string to a live node (moon/sun aren't in the kit's icons). */
+function svgIcon(markup: string): SVGElement {
+  const tpl = document.createElement('template');
+  tpl.innerHTML = markup.trim();
+  return tpl.content.firstElementChild as SVGElement;
+}
+
+const MOON_SVG =
+  '<svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" slot="icon" aria-hidden="true"><path d="M12 3a6 6 0 0 0 9 9 9 9 0 1 1-9-9Z"/></svg>';
+const SUN_SVG =
+  '<svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" slot="icon" aria-hidden="true"><circle cx="12" cy="12" r="4"/><path d="M12 2v2"/><path d="M12 20v2"/><path d="m4.93 4.93 1.41 1.41"/><path d="m17.66 17.66 1.41 1.41"/><path d="M2 12h2"/><path d="M20 12h2"/><path d="m6.34 17.66-1.41 1.41"/><path d="m19.07 4.93-1.41 1.41"/></svg>';
+
+// Stable references so re-setting them on every render is a no-op (only a NEW
+// array reference re-renders a facade). Streaming re-runs render each chunk.
+const NO_SUGGESTIONS: string[] = [];
+
+export function createView(root: HTMLElement, callbacks: ViewCallbacks): View {
+  // ── Build the DOM (elements are already upgraded — see gotcha 1) ────────────
+  const conversations = el('kai-conversations') as ConversationsEl;
+  const aside = el('aside', { class: 'sidebar' }, [conversations]);
+  const sidebarItem = el('kai-resizable-item', { size: '280px', min: '220px', max: '420px' }, [aside]) as ItemEl;
+
+  const showSidebarBtn = el('kai-button', { variant: 'ghost', size: 'icon', icon: 'panel-left', label: 'Show sidebar' });
+  const brand = el('span', { class: 'brand' });
+  brand.textContent = '@kitn.ai/ui · composed chat';
+  const themeToggleBtn = el('kai-button', { variant: 'ghost', size: 'icon', label: 'Toggle light/dark theme' });
+  const barLeft = el('div', { class: 'bar-left' }, [showSidebarBtn, brand]);
+  const bar = el('header', { class: 'bar' }, [barLeft, themeToggleBtn]);
+
+  const thread = el('kai-thread', { class: 'thread' }) as ThreadEl;
+
+  const promptInput = el('kai-prompt-input', { placeholder: 'Message the demo…' }) as PromptEl;
+  const hint = el('p', { class: 'composer-hint' });
+  hint.innerHTML = 'Type <kbd>/</kbd> for skills · <kbd>@</kbd> for agents';
+  const composer = el('div', { class: 'composer' }, [promptInput, hint]);
+
+  const main = el('main', { class: 'main' }, [bar, thread, composer]);
+  const mainItem = el('kai-resizable-item', {}, [main]) as ItemEl;
+
+  const resizable = el('kai-resizable', { orientation: 'horizontal' }, [sidebarItem, mainItem]);
+  const app = el('div', { class: 'app' }, [resizable]);
+  root.append(app);
+
+  // Static properties (never change) — set once. `groups` is always empty (we feed
+  // a flat `conversations`); the composer's triggers + voice flag are constant.
+  conversations.groups = [];
+  promptInput.triggers = TRIGGERS;
+  promptInput.voice = true; // gotcha 2: a truthy PROPERTY, not a bare attribute
+
+  // Persistent theme-toggle glyphs, swapped by theme (avoids re-parsing per render).
+  const moonIcon = svgIcon(MOON_SVG);
+  const sunIcon = svgIcon(SUN_SVG);
+
+  // ── Composer state (kept uncontrolled so the /+@ trigger menus keep a caret) ──
+  // liveText mirrors the input text (from kai-value-change) so voice can append to
+  // it. We NEVER assign a plain string `value` (that flips the element into
+  // controlled mode and breaks the caret-anchored menus); voice seeds a ComposerDoc
+  // and clear-on-submit goes through the element's clear() method.
+  let liveText = '';
+  const voice = createVoiceInput((transcript) => {
+    const next = (liveText ? liveText + ' ' : '') + transcript;
+    liveText = next;
+    promptInput.value = [{ type: 'text', text: next }]; // ComposerDoc seed, not a string
+  });
+
+  // ── Wire events (non-bubbling kai-* CustomEvents; kai-button uses native click) ──
+  conversations.addEventListener('kai-conversation-select', (e) =>
+    callbacks.onConversationSelect((e as CustomEvent<{ id: string }>).detail.id),
+  );
+  conversations.addEventListener('kai-new-chat', () => callbacks.onNewChat());
+  conversations.addEventListener('kai-toggle-sidebar', () => callbacks.onToggleSidebar());
+
+  showSidebarBtn.addEventListener('click', () => callbacks.onShowSidebar());
+  themeToggleBtn.addEventListener('click', () => callbacks.onToggleTheme());
+
+  thread.addEventListener('kai-message-action', (e) => {
+    const detail = (e as CustomEvent<{ messageId: string; action: string }>).detail;
+    if (detail.action !== 'speak') return;
+    // `copy` (and the feedback votes) are handled inside the element; the custom
+    // `speak` action is ours — read the message text aloud via speech synthesis.
+    const m = currentMessages.find((x) => x.id === detail.messageId);
+    if (!m) return;
+    window.speechSynthesis.cancel();
+    window.speechSynthesis.speak(new SpeechSynthesisUtterance(partsToText(m.parts)));
+  });
+
+  promptInput.addEventListener('kai-voice', () => {
+    if (!voice.supported) {
+      alert('Voice input needs a Chromium browser.');
+      return;
+    }
+    voice.start();
+  });
+  promptInput.addEventListener('kai-value-change', (e) => {
+    liveText = (e as CustomEvent<{ value: string }>).detail.value;
+  });
+  promptInput.addEventListener('kai-submit', (e) => {
+    // Reset the mirror + clear the uncontrolled input (uncontrolled-safe: clear()
+    // fires kai-value-change internally, never a string assignment), then hand the
+    // text up. main.ts owns append + streaming.
+    liveText = '';
+    promptInput.clear?.();
+    callbacks.onSubmit((e as CustomEvent<{ value: string }>).detail.value);
+  });
+  promptInput.addEventListener('kai-suggestion-click', (e) =>
+    callbacks.onSuggestion((e as CustomEvent<{ value: string }>).detail.value),
+  );
+
+  // ── Render: sync state onto element props ───────────────────────────────────
+  let currentMessages: ChatMessage[] = [];
+  let renderedTheme: Theme | null = null;
+
+  // Bake the per-message actions onto assistant turns, memoized on the messages
+  // reference so a theme-only render doesn't churn <kai-thread>. A NEW array from a
+  // streaming chunk produces a new baked array, which re-renders the thread.
+  let lastMessages: ChatMessage[] | null = null;
+  let lastBaked: ChatMessage[] = [];
+  function bakeActions(messages: ChatMessage[]): ChatMessage[] {
+    if (messages === lastMessages) return lastBaked;
+    lastMessages = messages;
+    lastBaked = messages.map((m): ChatMessage =>
+      m.role === 'assistant'
+        ? { ...m, actions: ['copy', { id: 'speak', label: 'Read aloud', icon: 'volume-2' }] }
+        : m,
+    );
+    return lastBaked;
+  }
+
+  function render(state: AppState): void {
+    const { theme } = state;
+    app.classList.toggle('dark', theme === 'dark');
+
+    // theme on the group AND every item so slotted chrome inherits the right tokens
+    for (const node of [resizable, sidebarItem, mainItem, conversations, thread, promptInput, showSidebarBtn, themeToggleBtn]) {
+      node.setAttribute('theme', theme);
+    }
+
+    // Sidebar collapse: the item's `collapsed` prop drops the panel + its divider,
+    // and the conversations rail's `collapsed` is CONTROLLED to stay in sync.
+    sidebarItem.collapsed = state.collapsed;
+    conversations.conversations = state.conversations;
+    conversations.setAttribute('active-id', state.activeId);
+    conversations.collapsed = state.collapsed;
+
+    // The reopen button only shows while collapsed (mirrors the React/Vue v-if).
+    showSidebarBtn.style.display = state.collapsed ? '' : 'none';
+
+    // Swap the toggle glyph only when the theme actually changes.
+    if (theme !== renderedTheme) {
+      themeToggleBtn.replaceChildren(theme === 'light' ? moonIcon : sunIcon);
+      renderedTheme = theme;
+    }
+
+    currentMessages = state.messages;
+    thread.messages = bakeActions(state.messages);
+
+    promptInput.loading = state.loading;
+    // Suggestions only in the near-empty state (mirrors the React/Vue computed).
+    promptInput.suggestions = state.messages.length <= 1 ? SUGGESTIONS : NO_SUGGESTIONS;
+  }
+
+  return { render };
+}

package/dist/templates/vanilla/src/vite-env.d.ts

@@ -0,0 +1 @@
+/// <reference types="vite/client" />

package/dist/templates/vanilla/src/voice-input.ts

@@ -0,0 +1,55 @@
+/** Minimal shape of a Web Speech recognition result event, enough to read the
+ *  first transcript. The full SpeechRecognition API is not in TS's lib.dom yet. */
+interface SpeechResultEvent {
+  results: ArrayLike<ArrayLike<{ transcript: string }>>;
+}
+interface SpeechRecognitionLike {
+  lang: string;
+  interimResults: boolean;
+  onresult: ((event: SpeechResultEvent) => void) | null;
+  start(): void;
+}
+type SpeechRecognitionCtor = new () => SpeechRecognitionLike;
+
+/** Resolve the Chromium (`webkitSpeechRecognition`) or standard constructor, if any. */
+function getSpeechRecognition(): SpeechRecognitionCtor | undefined {
+  if (typeof window === 'undefined') return undefined;
+  const w = window as unknown as {
+    SpeechRecognition?: SpeechRecognitionCtor;
+    webkitSpeechRecognition?: SpeechRecognitionCtor;
+  };
+  return w.SpeechRecognition ?? w.webkitSpeechRecognition;
+}
+
+export interface VoiceInput {
+  /** Chromium-only availability. False elsewhere so the caller can degrade. */
+  supported: boolean;
+  /** Begin one recognition pass (a no-op when unsupported). */
+  start: () => void;
+}
+
+/**
+ * Web Speech mic to one-shot transcript. Chromium-only (`webkitSpeechRecognition`);
+ * `supported` is false elsewhere so the caller can degrade gracefully. Framework
+ * ports (the React `useVoiceInput` hook, the Vue composable) share this exact
+ * logic. It hands the raw transcript to `onTranscript` and lets the caller decide
+ * what to do with it (the composer mic appends it to the live text). No composer
+ * or DOM knowledge.
+ *
+ * @param onTranscript called with the final recognized transcript.
+ */
+export function createVoiceInput(onTranscript: (transcript: string) => void): VoiceInput {
+  const supported = getSpeechRecognition() !== undefined;
+
+  const start = () => {
+    const Recognition = getSpeechRecognition();
+    if (!Recognition) return;
+    const rec = new Recognition();
+    rec.lang = 'en-US';
+    rec.interimResults = false;
+    rec.onresult = (event) => onTranscript(event.results[0][0].transcript);
+    rec.start();
+  };
+
+  return { supported, start };
+}

package/dist/templates/vanilla/tsconfig.json

@@ -0,0 +1,24 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "useDefineForClassFields": true,
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "skipLibCheck": true,
+
+    /* Bundler mode */
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "isolatedModules": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+
+    /* Linting */
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedSideEffectImports": true
+  },
+  "include": ["src"]
+}

package/dist/templates/vanilla/vite.config.ts

@@ -0,0 +1,14 @@
+import { defineConfig } from 'vite';
+
+// `@kitn.ai/ui` is linked into this example via `workspace:*`, so it resolves
+// through node_modules + the package's `exports` map exactly like a published
+// consumer would (no aliases, no source stubs). Build the kit first (`nx build ui`).
+//
+// No framework plugin here: the browser upgrades the `kai-*` custom elements
+// natively, so unlike the React/Vue examples there is nothing for a template
+// compiler to learn about the tags. This is the "pure web components, zero
+// framework" showcase.
+// https://vite.dev/config/
+export default defineConfig({
+  server: { port: 5176 },
+});

package/dist/templates/vue/_gitignore

@@ -0,0 +1,6 @@
+node_modules/
+dist/
+.env
+.env.local
+*.log
+.DS_Store

package/dist/templates/vue/index.html

@@ -0,0 +1,16 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>@kitn.ai/ui Vue example</title>
+    <style>
+      * { box-sizing: border-box; margin: 0; padding: 0; }
+      html, body, #app { height: 100%; }
+    </style>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>

package/dist/templates/vue/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@kitn.ai/ui-example-vue",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vue-tsc -b && vite build",
+    "preview": "vite preview",
+    "typecheck": "vue-tsc -b"
+  },
+  "dependencies": {
+    "@kitn.ai/ui": "workspace:*",
+    "vue": "^3.5.13"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.21",
+    "@vitejs/plugin-vue": "^5.2.1",
+    "typescript": "~5.7.2",
+    "vite": "^6.0.0",
+    "vue-tsc": "^2.2.0"
+  }
+}

package/dist/templates/vue/src/App.vue

@@ -0,0 +1,104 @@
+<script setup lang="ts">
+import { computed, ref } from 'vue';
+import { readOpenAIStream } from '@kitn.ai/ui/wire';
+import { CONVERSATIONS, THREADS, SUGGESTIONS, TRIGGERS, newId, mockResponse } from './chat-data';
+import type { Theme } from './types';
+import { useChat, useConversations } from './composables';
+import Sidebar from './components/Sidebar.vue';
+import ThreadView from './components/ThreadView.vue';
+import Composer from './components/Composer.vue';
+import ThemeToggle from './components/ThemeToggle.vue';
+
+/**
+ * A mini chat workspace COMPOSED BY HAND from @kitn.ai/ui's individual elements —
+ * the Vue mirror of `examples/react`. It shows how the raw `kai-*` web components
+ * fit together (vs. dropping in one batteries-included `<kai-chat>`/`<kai-workspace>`):
+ *
+ *   <kai-resizable>/<kai-resizable-item>  — the draggable sidebar | main split (the
+ *                                           divider is the kit's default `line` hairline)
+ *   <kai-conversations>  — the sidebar list (fed `conversations`, emits select/new)
+ *   <kai-thread>         — the scrolling message list (stick-to-bottom built in)
+ *   <kai-prompt-input>   — the composer at the bottom
+ *
+ * The pieces are split into `components/` (the UI subcomponents + the example's own
+ * moon/sun icons) and `composables/` (`useChat` owns the message array + streaming,
+ * `useConversations` the conversation stash, `useVoiceInput` the mic). Everything
+ * else is plain Vue refs. Swap `mockResponse(text)` for a real `fetch` to ship.
+ */
+const theme = ref<Theme>('dark');
+const collapsed = ref(false);
+const chat = useChat(THREADS[CONVERSATIONS[0].id] ?? []);
+const { messages, loading } = chat;
+const { conversations, activeId, selectConversation, newChat } = useConversations(chat, CONVERSATIONS);
+
+const suggestions = computed(() => (messages.value.length <= 1 ? SUGGESTIONS : []));
+
+async function send(raw: string) {
+  const text = raw.trim();
+  if (!text) return;
+  // The Composer already cleared its own input; here we just append the user
+  // message and stream the (mock) assistant reply.
+  chat.append({ id: newId(), role: 'user', parts: [{ type: 'text', text }] });
+  const stream = chat.streamAssistant();
+  // NO BACKEND AND NO PROVIDER. mockResponse() yields canned SSE frames that go
+  // through the SAME reader a real model's response would, so this preview
+  // exercises the real path. To go live, only this one expression changes —
+  // `mockResponse(text)` becomes a POST to your route, with
+  // toOpenAIMessages(messages.value) as the body. The line below stays.
+  await readOpenAIStream(mockResponse(text), stream);
+  stream.done();
+}
+</script>
+
+<template>
+  <div class="app" :class="{ dark: theme === 'dark' }">
+    <!-- <kai-resizable> owns the sidebar width + the divider. The handle defaults to
+         the `line` hairline (transparent at rest, tinting on hover/drag); collapsing
+         the sidebar maps to <kai-resizable-item :collapsed>. Pass `theme` to the group
+         AND every item so slotted chrome inherits the right light/dark tokens. -->
+    <kai-resizable :theme="theme" orientation="horizontal">
+      <kai-resizable-item :theme="theme" size="280px" min="220px" max="420px" :collapsed.prop="collapsed">
+        <Sidebar
+          :theme="theme"
+          :conversations="conversations"
+          :active-id="activeId"
+          :collapsed="collapsed"
+          @select="selectConversation"
+          @new-chat="newChat"
+          @toggle="collapsed = !collapsed"
+        />
+      </kai-resizable-item>
+
+      <kai-resizable-item :theme="theme">
+        <main class="main">
+          <header class="bar">
+            <div class="bar-left">
+              <kai-button
+                v-if="collapsed"
+                :theme="theme"
+                variant="ghost"
+                size="icon"
+                icon="panel-left"
+                label="Show sidebar"
+                @click="collapsed = false"
+              ></kai-button>
+              <span class="brand">@kitn.ai/ui · composed chat</span>
+            </div>
+            <ThemeToggle :theme="theme" @toggle="theme = theme === 'light' ? 'dark' : 'light'" />
+          </header>
+
+          <ThreadView :theme="theme" :messages="messages" />
+
+          <Composer
+            :theme="theme"
+            :loading="loading"
+            :suggestions="suggestions"
+            :triggers="TRIGGERS"
+            @submit="send"
+            @suggestion="send"
+          />
+        </main>
+      </kai-resizable-item>
+    </kai-resizable>
+  </div>
+</template>

package/dist/templates/vue/src/chat-data.ts

@@ -0,0 +1,106 @@
+// Self-contained sample data + the kit's shared mock responder, no backend.
+import type { MessagePart } from '@kitn.ai/ui';
+import { createMockResponder } from '@kitn.ai/ui/state';
+
+export interface Conversation {
+  id: string;
+  title: string;
+  scope: { type: 'document' | 'collection' };
+  messageCount: number;
+  lastMessageAt: string;
+  updatedAt: string;
+}
+export interface Msg {
+  id: string;
+  role: 'user' | 'assistant';
+  parts: MessagePart[];
+}
+
+export function newId(): string {
+  return typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function'
+    ? crypto.randomUUID()
+    : 'id-' + Math.random().toString(36).slice(2);
+}
+
+const iso = (daysAgo = 0) => new Date(Date.now() - daysAgo * 86_400_000).toISOString();
+
+export const CONVERSATIONS: Conversation[] = [
+  { id: 'c1', title: 'Getting started', scope: { type: 'collection' }, messageCount: 2, lastMessageAt: iso(0), updatedAt: iso(0) },
+  { id: 'c2', title: 'Composing your own chat', scope: { type: 'collection' }, messageCount: 2, lastMessageAt: iso(0), updatedAt: iso(0) },
+  { id: 'c3', title: 'Theming + dark mode', scope: { type: 'collection' }, messageCount: 2, lastMessageAt: iso(1), updatedAt: iso(1) },
+];
+
+export const THREADS: Record<string, Msg[]> = {
+  c1: [
+    { id: 'c1u', role: 'user', parts: [{ type: 'text', text: 'What is @kitn.ai/ui?' }] },
+    { id: 'c1a', role: 'assistant', parts: [{ type: 'text', text: '**@kitn.ai/ui** is a set of framework-agnostic web components for AI chat UIs: message threads, streaming, markdown, tool panels, and more. This demo composes its `<kai-conversations>`, `<kai-thread>`, and `<kai-prompt-input>` elements by hand.' }] },
+  ],
+  c2: [
+    { id: 'c2u', role: 'user', parts: [{ type: 'text', text: 'How do I build my own chat instead of dropping in `<kai-chat>`?' }] },
+    { id: 'c2a', role: 'assistant', parts: [{ type: 'text', text: "Feed your `messages` to a `<kai-thread>`, put a `<kai-prompt-input>` below, and wire `kai-submit` to append + stream. That's exactly what this example does. Read `App.vue`." }] },
+  ],
+  c3: [
+    { id: 'c3u', role: 'user', parts: [{ type: 'text', text: 'How does dark mode work?' }] },
+    { id: 'c3a', role: 'assistant', parts: [{ type: 'text', text: "Each element takes a `theme` prop (`light` / `dark` / `auto`). Drive it from app state. Toggle it with the button top-right. The kit's `--color-*` tokens flip under a `.dark` class for your own surrounding chrome." }] },
+  ],
+};
+
+export const SUGGESTIONS = ['What is @kitn.ai/ui?', 'How do I install it?', 'Show me some markdown'];
+
+// Rich entity triggers for the prompt input: typing `/` opens the skills menu,
+// `@` opens the agents menu. Each selection inserts an atomic pill. Set on
+// <kai-prompt-input> as the `triggers` JS property (a TriggerDef[]).
+export const TRIGGERS = [
+  {
+    char: '/',
+    kind: 'skill',
+    items: [
+      { id: 'summarize', label: 'Summarize', description: 'Summarize the thread', promptText: 'Summarize the thread.' },
+      { id: 'translate', label: 'Translate', description: 'Translate to English', promptText: 'Translate to English.' },
+      { id: 'rewrite', label: 'Rewrite', description: 'Rewrite for clarity', promptText: 'Rewrite this for clarity.' },
+    ],
+  },
+  {
+    char: '@',
+    kind: 'agent',
+    items: [
+      { id: 'researcher', label: 'Researcher', description: 'Deep web research', group: 'Agents' },
+      { id: 'coder', label: 'Coder', description: 'Writes and edits code', group: 'Agents' },
+      { id: 'designer', label: 'Designer', description: 'UI and visual design', group: 'Agents' },
+    ],
+  },
+];
+
+// The replies the mock cycles through, one per turn. Markdown-rich on purpose:
+// the thread renders markdown, code blocks and blockquotes, so the canned
+// replies exercise that instead of only proving text arrives.
+//
+// The first one says it is a mock in words. That is the WEAKEST of the
+// responder's tells and the only one a real model could imitate, which is
+// exactly why it is not the only one — the rest are on the wire, below.
+const MOCK_REPLIES = [
+  "This reply streams token-by-token from the kit's own mock responder. No API key, no backend, no provider was contacted. Replace `mockResponse(text)` with a real model call (Anthropic, OpenAI, your own endpoint) to ship a real app.",
+  "Install it:\n\n```bash\nnpm install @kitn.ai/ui\n```\n\nThen register the elements + load the tokens:\n\n```ts\nimport '@kitn.ai/ui/elements';\nimport '@kitn.ai/ui/theme.tokens.css';\n```\n\nNow drop `<kai-thread>` and `<kai-prompt-input>` into your template.",
+  "I render **bold**, *italic*, `inline code`, lists, and code blocks:\n\n```ts\nconst stream = chat.streamAssistant();\nawait readOpenAIStream(mockResponse(text), stream);\nstream.done();\n```\n\n> Blockquotes too.",
+  "This chat is **composed by hand**: `<kai-conversations>` for the sidebar, a `<kai-thread>` for the messages, and `<kai-prompt-input>` at the bottom, all wired with plain reactive state. Swap `mockResponse(text)` for your own model call and you're shipping.",
+];
+
+/**
+ * The kit's own mock responder, shared with the `kai` MCP scaffolder and
+ * `create-kai` so there is ONE implementation of this and not seven.
+ *
+ * It yields canned SSE frames in the OpenAI chat-completions shape, which
+ * `readOpenAIStream` parses exactly as it parses a real provider's. So this
+ * no-backend preview runs the kit's REAL streaming path — the SSE reader, the
+ * part folding, all of it — rather than a hand-rolled loop that merely
+ * resembles it. Going live then changes one expression, not the handler.
+ *
+ * It also cannot be mistaken for a real turn: the stream opens with a
+ * `: kai-mock` SSE comment, every frame carries a `_kai_mock` field, `model`
+ * reports as `kai-mock` (no provider serves that, so an echoed mock frame is
+ * rejected upstream rather than quietly believed), and usage is all zeros.
+ *
+ * MODULE scope, not per-send: the responder owns the cursor into the replies
+ * above, so rebuilding it each turn would answer with the first one forever.
+ */
+export const mockResponse = createMockResponder({ replies: MOCK_REPLIES });