create-kai 0.1.0

package/dist/templates/angular/src/app/state/chat.store.ts

@@ -0,0 +1,47 @@
+import { signal, type WritableSignal } from '@angular/core';
+import type { ChatMessage } from '@kitn.ai/ui';
+import {
+  appendMessage,
+  createAssistantStream,
+  onStreamSettled,
+  type SetMessages,
+  type AssistantStream,
+} from '@kitn.ai/ui/state';
+
+/**
+ * Angular port of the kit's `useKaiChat` (a React hook), built on the SAME
+ * framework-neutral state core (`@kitn.ai/ui/state`) the React hook uses. It owns
+ * the message array + the `loading` flag and exposes ergonomic ops. Swap
+ * `mockResponse(text)` for a real `fetch` to ship a real app.
+ *
+ * `messages` is a plain Angular signal: every op assigns a BRAND-NEW array
+ * reference (`messages.set(updater(prev))`), which is exactly what re-renders
+ * `<kai-thread>` when the template re-binds `[messages]` — mutating the array in
+ * place does not. Signals also keep the array plain (no proxy), so what reaches the
+ * element's `messages` property is a clean `ChatMessage[]`.
+ */
+export interface ChatStore {
+  messages: WritableSignal<ChatMessage[]>;
+  loading: WritableSignal<boolean>;
+  append: (msg: ChatMessage) => void;
+  setMessages: (next: ChatMessage[]) => void;
+  streamAssistant: (init?: Partial<ChatMessage>) => AssistantStream;
+}
+
+export function createChat(initialMessages: ChatMessage[] = []): ChatStore {
+  const messages = signal<ChatMessage[]>([...initialMessages]);
+  const loading = signal(false);
+
+  // The one universal contract the state core drives: a functional-updater setter
+  // (React setState shape) that assigns a fresh array each time.
+  const set: SetMessages = (updater) => messages.set(updater(messages()));
+
+  const append = (msg: ChatMessage) => set((prev) => appendMessage(prev, msg));
+  const setMessages = (next: ChatMessage[]) => messages.set([...next]);
+  const streamAssistant = (init?: Partial<ChatMessage>): AssistantStream => {
+    loading.set(true);
+    return onStreamSettled(createAssistantStream(set, init), () => loading.set(false));
+  };
+
+  return { messages, loading, append, setMessages, streamAssistant };
+}

package/dist/templates/angular/src/app/state/conversations.store.ts

@@ -0,0 +1,42 @@
+import { signal, type WritableSignal } from '@angular/core';
+import { THREADS, newId, type Conversation } from '../../chat-data';
+import type { ChatStore } from './chat.store';
+
+/**
+ * Owns the conversation list + which one is active, plus the in-memory `THREADS`
+ * stash: on select/new we swap the OPEN thread out to `THREADS` and swap the picked
+ * one in. Takes the `createChat` store so it can read the live messages when
+ * stashing and reset them when loading another thread. Mirrors the Vue/React
+ * `useConversations`.
+ */
+export interface ConversationsStore {
+  conversations: WritableSignal<Conversation[]>;
+  activeId: WritableSignal<string>;
+  selectConversation: (id: string) => void;
+  newChat: () => void;
+}
+
+export function createConversations(chat: ChatStore, initial: Conversation[]): ConversationsStore {
+  const conversations = signal<Conversation[]>([...initial]);
+  const activeId = signal(initial[0].id);
+
+  const selectConversation = (id: string) => {
+    THREADS[activeId()] = chat.messages(); // stash the open thread
+    activeId.set(id);
+    chat.setMessages(THREADS[id] ?? []); // load the picked one
+  };
+
+  const newChat = () => {
+    const id = newId();
+    THREADS[activeId()] = chat.messages();
+    THREADS[id] = [];
+    conversations.set([
+      { id, title: 'New conversation', scope: { type: 'collection' }, messageCount: 0, lastMessageAt: new Date().toISOString(), updatedAt: new Date().toISOString() },
+      ...conversations(),
+    ]);
+    activeId.set(id);
+    chat.setMessages([]);
+  };
+
+  return { conversations, activeId, selectConversation, newChat };
+}

package/dist/templates/angular/src/app/state/voice-input.ts

@@ -0,0 +1,57 @@
+/** Minimal shape of a Web Speech recognition result event — enough to read the
+ *  first transcript. The full SpeechRecognition API isn't 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;
+}
+
+/**
+ * Web Speech mic → one-shot transcript. Chromium-only (`webkitSpeechRecognition`);
+ * `supported` is false elsewhere so the caller can degrade gracefully. Vue port of
+ * the kit's `useVoiceInput` (a React hook). 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.
+ * @returns `supported` (Chromium-only availability) and a `start` that begins one
+ *   recognition pass (a no-op when unsupported).
+ */
+export function useVoiceInput(onTranscript: (transcript: string) => void): {
+  supported: boolean;
+  start: () => void;
+} {
+  // Latest-callback ref: keeps `start` stable while always calling the current
+  // `onTranscript`, mirroring the React hook (no stale closure).
+  const cbRef = { current: onTranscript };
+  cbRef.current = onTranscript;
+
+  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) => cbRef.current(event.results[0][0].transcript);
+    rec.start();
+  };
+
+  return { supported, start };
+}

package/dist/templates/angular/src/app/types.ts

@@ -0,0 +1,2 @@
+// Shared across the example's components. Mirrors the Vue reference's `types.ts`.
+export type Theme = 'light' | 'dark';

package/dist/templates/angular/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.ts`." }] },
+  ],
+  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 = this.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 });

package/dist/templates/angular/src/index.html

@@ -0,0 +1,16 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>@kitn.ai/ui Angular example</title>
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <style>
+      * { box-sizing: border-box; margin: 0; padding: 0; }
+      html, body, app-root { height: 100%; }
+      app-root { display: block; }
+    </style>
+  </head>
+  <body>
+    <app-root></app-root>
+  </body>
+</html>

package/dist/templates/angular/src/main.ts

@@ -0,0 +1,16 @@
+import '@kitn.ai/ui/elements'; // registers the kai-* custom elements (async)
+import { bootstrapApplication } from '@angular/platform-browser';
+import { App } from './app/app';
+import { appConfig } from './app/app.config';
+
+// The kai-* elements register ASYNCHRONOUSLY. Angular sets array/object DOM
+// properties ([conversations], [messages], [triggers], …) the moment it stamps a
+// <kai-*> tag; if that happens before the element upgrades, the property write hits
+// a plain, not-yet-upgraded node and is clobbered by the element's empty defaults on
+// upgrade. Raw web-component consumers have no upgrade-race guard (unlike the React
+// wrappers), so we gate bootstrap on `whenDefined` for every tag we use — Angular
+// then binds against UPGRADED elements. Attributes survive upgrade; properties do not.
+const TAGS = ['kai-resizable', 'kai-resizable-item', 'kai-conversations', 'kai-thread', 'kai-prompt-input', 'kai-button'];
+Promise.all(TAGS.map((t) => customElements.whenDefined(t)))
+  .then(() => bootstrapApplication(App, appConfig))
+  .catch((err) => console.error(err));

package/dist/templates/angular/src/styles.css

@@ -0,0 +1,10 @@
+html,
+body,
+#root {
+  height: 100%;
+  margin: 0;
+}
+
+body {
+  font-family: system-ui, -apple-system, sans-serif;
+}

package/dist/templates/angular/tsconfig.app.json

@@ -0,0 +1,9 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./dist/out-tsc/app",
+    "types": []
+  },
+  "files": ["src/main.ts"],
+  "include": ["src/**/*.d.ts"]
+}

package/dist/templates/angular/tsconfig.json

@@ -0,0 +1,22 @@
+{
+  "compileOnSave": false,
+  "compilerOptions": {
+    "strict": true,
+    "noImplicitOverride": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "skipLibCheck": true,
+    "isolatedModules": true,
+    "esModuleInterop": true,
+    "experimentalDecorators": true,
+    "importHelpers": true,
+    "target": "ES2022",
+    "module": "preserve"
+  },
+  "angularCompilerOptions": {
+    "enableI18nLegacyMessageIdFormat": false,
+    "strictInjectionParameters": true,
+    "strictInputAccessModifiers": true,
+    "strictTemplates": true
+  }
+}

package/dist/templates/nextjs/_gitignore

@@ -0,0 +1,11 @@
+node_modules/
+.next/
+out/
+.env
+.env.local
+*.log
+.DS_Store
+next-env.d.ts
+*.tsbuildinfo
+vendor/
+*.tgz

package/dist/templates/nextjs/app/chat-data.ts

@@ -0,0 +1,125 @@
+// Self-contained sample data + the kit's shared mock responder — no backend.
+//
+// THIS MODULE IS EVALUATED TWICE: once on the server while the page is being
+// prerendered, and once in the browser. Everything in it is therefore plain data
+// and pure functions — nothing here touches `window`, `document` or
+// `customElements`, which is the rule for any module a Server Component's tree
+// reaches, client island or not.
+//
+// The date helper below is the one thing that produces a DIFFERENT value on each
+// of those two evaluations, and it is safe for a specific reason worth knowing:
+// `CONVERSATIONS` is only ever handed to `<kai-conversations>` as a JS PROPERTY,
+// and the React wrappers assign properties in a layout effect, which never runs
+// on the server. So no timestamp reaches the server-rendered HTML and there is
+// nothing for hydration to compare. Render one of these into JSX and that stops
+// being true — that is the shape of a real hydration mismatch.
+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: 'Server components', 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: 'Where does the "use client" directive go, and how do the kai-* elements survive the App Router?' }] },
+    { id: 'c1a', role: 'assistant', parts: [{ type: 'text', text: "`app/layout.tsx` and `app/page.tsx` are **Server Components** — neither carries a directive. `app/workspace.tsx` does, because IT uses hooks and event handlers. That is the standard RSC rule, not a kit requirement: the React wrappers ship their own `'use client'` banner, so a Server Component can render one directly.\n\nThe elements themselves server-render as **bare tags**. Each wrapper registers its element inside a layout effect, which never runs on the server, so the prerendered HTML contains `<kai-thread></kai-thread>` and nothing inside it. After hydration the wrapper defines the element and assigns `messages` as a live JS **property** — arrays go across unstringified, so nothing has to be serialized into an attribute.\n\nView source on this page and you will find the empty tags. Then watch this reply stream in: that is the same property channel still working, one new array reference per chunk." }] },
+  ],
+  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: "Put a `<Thread>` in a scroll area, a `<PromptInput>` below it, and let `useKaiChat` own the message array and the streaming. That's exactly what this app does — read `app/workspace.tsx`." }] },
+  ],
+  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 client 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 = [
+  'Where does "use client" go?',
+  '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
+// <PromptInput> 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 route handler) to ship a real app.",
+  "Install it:\n\n```bash\nnpm install @kitn.ai/ui\n```\n\nThen import the wrappers + tokens:\n\n```tsx\nimport { Thread, PromptInput } from '@kitn.ai/ui/react';\nimport '@kitn.ai/ui/theme.tokens.css';\n```",
+  "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.",
+  "Nothing about this thread came from the server. Next prerendered the **empty** `<kai-thread>` tag, the browser hydrated it, and every chunk you are reading now arrived as a new `messages` array assigned to that element as a JS property.",
+];
+
+/**
+ * The kit's own mock responder, shared with the `kai` MCP scaffolder and
+ * `create-kai` so there is ONE implementation of this and not eight.
+ *
+ * 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 });

package/dist/templates/nextjs/app/components/Composer.tsx

@@ -0,0 +1,88 @@
+import { useCallback, useRef } from 'react';
+import { PromptInput, useVoiceInput } from '@kitn.ai/ui/react';
+import type { PromptInputProps } from '@kitn.ai/ui/react';
+import type { Theme } from '../theme';
+
+interface ComposerProps {
+  theme: Theme;
+  loading: boolean;
+  suggestions: string[];
+  triggers: PromptInputProps['triggers'];
+  onSubmit: (value: string) => void;
+  onSuggestionClick: (value: string) => void;
+}
+
+/**
+ * The bottom composer. Wraps `<kai-prompt-input>` and owns the input-DOM concerns:
+ * the element ref, a live text mirror, clear-on-submit, and seeding voice.
+ *
+ * The prompt input stays UNCONTROLLED so the `/`+`@` trigger menus keep a live
+ * caret. Assigning a plain STRING `value` flips the element into controlled mode,
+ * which re-applies the property and collapses the shadow-DOM selection — that
+ * disables the caret-anchored menu. So we NEVER push a string: clear-on-submit
+ * goes through the element's `clear()` method, and voice seeds a ComposerDoc (a
+ * non-string value is a one-time seed that leaves the input uncontrolled). We keep
+ * the live text mirrored into `textRef` (from `onValueChange`) so voice can append.
+ *
+ * SERVER-RENDERING NOTE. `useVoiceInput` reports `supported: false` on the server
+ * (there is no `window.SpeechRecognition` there) and true in Chromium, so that
+ * flag is read ONLY inside the click handler and never during render. Branching
+ * render output on it would put a different tree in the prerendered HTML than the
+ * client builds on hydration, which is the textbook hydration mismatch — and one
+ * `next build` would minify into a numbered React error rather than explain.
+ */
+export function Composer({ theme, loading, suggestions, triggers, onSubmit, onSuggestionClick }: ComposerProps) {
+  // Ref to the underlying <kai-prompt-input> element for the imperative pushes
+  // (clear() on submit, ComposerDoc seed from voice); textRef mirrors the live text.
+  const promptRef = useRef<HTMLElement>(null);
+  const textRef = useRef('');
+
+  const { supported: voiceSupported, start: startVoice } = useVoiceInput((transcript) => {
+    const next = (textRef.current ? textRef.current + ' ' : '') + transcript;
+    textRef.current = next;
+    const el = promptRef.current as (HTMLElement & { value?: unknown }) | null;
+    if (el) el.value = [{ type: 'text', text: next }];
+  });
+
+  const handleVoice = useCallback(() => {
+    // Mic is Chromium-only; degrade gracefully everywhere else.
+    if (!voiceSupported) {
+      alert('Voice input needs a Chromium browser.');
+      return;
+    }
+    startVoice();
+  }, [voiceSupported, startVoice]);
+
+  const handleSubmit = useCallback(
+    (value: string) => {
+      // Clear our own uncontrolled input first — reset the mirror + call the
+      // element's clear() method (uncontrolled-safe; never a string assignment) —
+      // then hand the text up. The workspace owns append + streaming.
+      textRef.current = '';
+      (promptRef.current as (HTMLElement & { clear?: () => void }) | null)?.clear?.();
+      onSubmit(value);
+    },
+    [onSubmit],
+  );
+
+  return (
+    <div className="composer">
+      <PromptInput
+        ref={promptRef}
+        theme={theme}
+        placeholder="Message the demo…"
+        loading={loading}
+        suggestions={suggestions}
+        triggers={triggers}
+        voice
+        onVoice={handleVoice}
+        onValueChange={(e) => { textRef.current = e.detail.value; }}
+        onSubmit={(e) => handleSubmit(e.detail.value)}
+        onSuggestionClick={(e) => onSuggestionClick(e.detail.value)}
+      />
+      <p className="composer-hint">
+        Type <kbd>/</kbd> for skills · <kbd>@</kbd> for agents
+      </p>
+    </div>
+  );
+}

package/dist/templates/nextjs/app/components/HydrationBadge.tsx

@@ -0,0 +1,68 @@
+import { useEffect, useState } from 'react';
+
+/**
+ * THE SERVER-RENDERING PROOF, ON THE PAGE.
+ *
+ * This starter's original job was to show that a `kai-*` element survives Next's
+ * prerender + hydration, and this badge is what makes that visible without opening
+ * devtools. It is worth keeping alongside the working chat because HYDRATION
+ * FAILURE LOOKS LIKE SUCCESS: Next can emit perfectly correct HTML and then throw
+ * during hydration, leaving a page that reads exactly right and does nothing. A
+ * screenshot cannot tell those apart. This badge can, because the only way it
+ * turns green is for client JavaScript to have run.
+ *
+ * IT IS WORTH MORE ON NEXT THAN ANYWHERE ELSE, because a production React build
+ * MINIFIES hydration errors into a numbered link — so `next build && next start`
+ * shows you a silently dead page, and only `next dev` logs the mismatch in words.
+ * The badge is the same signal without the dev-only console.
+ *
+ * HOW IT AVOIDS BEING THE BUG IT REPORTS. The state starts `null` — the same value
+ * on the server and on React's first client render — so the two trees agree and
+ * hydration has nothing to reconcile. Only afterwards does the effect (which never
+ * runs on the server) look at `customElements` and re-render. Reading
+ * `customElements` during render instead would produce "none" in the server HTML
+ * and "5" in the client tree, i.e. a hydration mismatch inside the hydration
+ * detector.
+ *
+ * The tags are polled on a rAF loop rather than checked once: each React wrapper
+ * registers its own element from a layout effect and the element modules load as
+ * dynamic imports, so the definitions land over the next few frames rather than
+ * all at once.
+ */
+const TAGS = ['kai-button', 'kai-conversations', 'kai-thread', 'kai-prompt-input', 'kai-resizable'] as const;
+
+export function HydrationBadge() {
+  const [defined, setDefined] = useState<number | null>(null);
+
+  useEffect(() => {
+    let raf = 0;
+    const check = () => {
+      const n = TAGS.filter((t) => !!customElements.get(t)).length;
+      setDefined(n);
+      if (n < TAGS.length) raf = requestAnimationFrame(check);
+    };
+    check();
+    return () => cancelAnimationFrame(raf);
+  }, []);
+
+  const hydrated = defined === TAGS.length;
+  return (
+    <span
+      className="hydration"
+      data-testid="registration-status"
+      data-state={hydrated ? 'hydrated' : 'server'}
+      title={
+        hydrated
+          ? `Client JS ran: all ${TAGS.length} kai-* elements are defined in customElements.`
+          : 'Server-rendered markup. The kai-* tags are still bare — no client JS has registered them yet.'
+      }
+    >
+      <span className="hydration-dot" aria-hidden />
+      {defined === null
+        ? 'server-rendered · elements not yet registered'
+        : hydrated
+          ? `hydrated · ${defined}/${TAGS.length} kai-* elements registered`
+          : `hydrating · ${defined}/${TAGS.length} kai-* elements registered`}
+    </span>
+  );
+}