@kitnai/chat 0.3.0 → 0.4.0

package/src/stories/docs/ForAIAgents.mdx

@@ -0,0 +1,93 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+
+<Meta title="Docs/For AI Agents" />
+
+# For AI Agents / LLMs
+
+`@kitnai/chat` ships machine-readable orientation files that follow the
+[llmstxt.org](https://llmstxt.org) convention, so coding agents (Claude Code,
+Copilot, Cursor, Codex, …) can wire up the components correctly without guessing.
+
+**View them now:** <a href="/llms.txt" target="_blank" rel="noreferrer">llms.txt</a> ·
+<a href="/llms-full.txt" target="_blank" rel="noreferrer">llms-full.txt</a>
+(open in a new tab)
+
+## The files
+
+| File | Audience | Where to find it |
+|---|---|---|
+| <a href="/llms.txt" target="_blank" rel="noreferrer"><code>llms.txt</code></a> | Agents + humans | Repo root, the npm package root (`node_modules/@kitnai/chat/llms.txt`), and `https://kitn.dev/llms.txt` |
+| <a href="/llms-full.txt" target="_blank" rel="noreferrer"><code>llms-full.txt</code></a> | Agents | Same locations; the per-element API reference for **every** `kitn-*` element |
+
+Both files are **auto-generated** from `dist/custom-elements.json` by
+`scripts/gen-llms.mjs` during `npm run build`, so they never drift from the
+shipped API. Do not edit them by hand.
+
+- **`llms.txt`** (~4 KB) — a dense orientation: install, the property-vs-attribute
+  rule, the two-layer architecture, theming, and framework wiring. Fast to read.
+- **`llms-full.txt`** (~32 KB) — everything in `llms.txt` plus a generated props/events
+  table for each element, a streaming recipe, and a "build a chat app" runbook.
+
+## The #1 rule agents get wrong
+
+**Array and object data must be set as JavaScript properties, not HTML attributes.**
+An HTML attribute is always a string, so passing `messages`, `models`, `context`,
+`suggestions`, or `slashCommands` as an attribute silently fails.
+
+```js
+const chat = document.querySelector('kitn-chat');
+chat.messages = [{ id: '1', role: 'assistant', content: 'Hi!' }]; // ✅ property
+```
+
+```html
+<kitn-chat messages="[...]"></kitn-chat>  <!-- ❌ never works -->
+```
+
+Only scalar props (string / number / boolean) work as attributes — for example
+`placeholder`, `loading`, and `theme`.
+
+## How agents consume these files
+
+| Tool | How it finds them |
+|---|---|
+| Claude Code | Reference `@llms.txt` in `CLAUDE.md`, or read `node_modules/@kitnai/chat/llms-full.txt` |
+| GitHub Copilot | Workspace indexing picks up the file in `node_modules`; reference it from `.github/copilot-instructions.md` |
+| Cursor | Point `.cursorrules` at the installed `llms.txt` |
+| Codex / ChatGPT | Fetch https://kitn.dev/llms.txt directly |
+| Any agent | `npm install @kitnai/chat` → file is at `node_modules/@kitnai/chat/llms.txt` |
+
+## Build a chat app (the runbook agents follow)
+
+```js
+import '@kitnai/chat/elements';
+const chat = document.querySelector('kitn-chat');
+chat.messages = [];
+
+chat.addEventListener('submit', async (e) => {
+  const userText = e.detail.value;
+
+  // Append the user message (new array)
+  const history = [...chat.messages, { id: crypto.randomUUID(), role: 'user', content: userText }];
+  chat.messages = history;
+  chat.loading = true;
+
+  // Empty assistant placeholder to stream into
+  const aid = crypto.randomUUID();
+  chat.messages = [...history, { id: aid, role: 'assistant', content: '' }];
+
+  // Stream — reassign a NEW array with a NEW message object each chunk.
+  // Mutating in place will NOT re-render.
+  let answer = '';
+  for await (const token of streamFromYourAPI(history)) {
+    answer += token;
+    chat.messages = chat.messages.map((m) => (m.id === aid ? { ...m, content: answer } : m));
+  }
+  chat.loading = false;
+});
+```
+
+## Links
+
+- <a href="/llms.txt" target="_blank" rel="noreferrer"><code>llms.txt</code></a> — orientation (also published at `https://kitn.dev/llms.txt`)
+- <a href="/llms-full.txt" target="_blank" rel="noreferrer"><code>llms-full.txt</code></a> — full per-element reference (also `https://kitn.dev/llms-full.txt`)
+- Custom Elements Manifest — `dist/custom-elements.json` (published at `https://unpkg.com/@kitnai/chat/dist/custom-elements.json`)

package/src/stories/docs/GettingStarted.mdx

@@ -1,7 +1,7 @@
 import { Meta, Canvas } from '@storybook/addon-docs/blocks';
 import * as FullChat from '../full-chat.stories';
 
-<Meta title="Getting Started" />
+<Meta title="Docs/Getting Started" />
 
 # Getting Started
 
@@ -73,4 +73,4 @@ Everything assembled into a real app — a conversation sidebar, a message threa
 
 Open it full-screen under **Examples → Full Chat App**, then explore each building block on its own page in the sidebar.
 
-Ready to make it yours? See **[Theming](?path=/docs/theming--docs)**. Wiring a real model? See **[Integrations](?path=/docs/integrations--docs)**.
+Ready to make it yours? See **[Theming](?path=/docs/docs-theming--docs)**. Wiring a real model? See **[Integrations](?path=/docs/docs-frameworks-integrations--docs)**.

package/src/stories/docs/Installation.mdx

@@ -1,6 +1,6 @@
 import { Meta } from '@storybook/addon-docs/blocks';
 
-<Meta title="Installation" />
+<Meta title="Docs/Installation" />
 
 # Installation
 
@@ -45,4 +45,4 @@ npm run build   # emits dist/kitn-chat.es.js
 - **SolidJS is bundled in** — the host page needs nothing else.
 - The kit's CSS is injected into each element's Shadow DOM automatically; importing `theme.css` is optional and only needed if you want to override design tokens.
 
-Head to **[Getting Started](?path=/docs/getting-started--docs)** to render your first chat.
+Head to **[Getting Started](?path=/docs/docs-getting-started--docs)** to render your first chat.

package/src/stories/docs/Integrations.mdx

@@ -1,37 +1,436 @@
 import { Meta } from '@storybook/addon-docs/blocks';
 
-<Meta title="Integrations" />
+<Meta title="Docs/Frameworks & Integrations" />
 
-# Integrations
+# Frameworks & Integrations
 
-The components don't talk to any model for you — they render `messages` and emit `submit`. That keeps you free to wire up any provider, streaming protocol, or extra like text-to-speech.
+`@kitnai/chat` is transport-agnostic: every element renders `messages` and emits `submit`. You bring the model; the kit owns the UI. This page covers how to wire it up in plain HTML, React, Vue, Svelte, and Angular, then shows how to stream a real response.
+
+---
+
+## The #1 rule: properties vs. attributes
+
+Arrays and objects **must** be set as JavaScript **properties** on the DOM element — never as HTML attributes. An HTML attribute is always a string, so passing `messages`, `models`, `context`, `suggestions`, or `slashCommands` as an attribute silently fails or is ignored.
+
+```js
+const chat = document.querySelector('kitn-chat');
+
+// ✅ correct — set as a JS property
+chat.messages = [{ id: '1', role: 'assistant', content: 'Hello!' }];
+
+// ❌ wrong — HTML attribute, always a string, never works
+// <kitn-chat messages="[...]"></kitn-chat>
+```
+
+Scalar values (strings, numbers, booleans) work as attributes: `placeholder`, `loading`, `theme`, `prose-size`, and so on.
+
+---
+
+## Plain HTML
+
+Import the element bundle once as a side-effect (it registers all `kitn-*` custom elements), then set properties and listen for events in a `<script type="module">` block.
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <!-- optional: only needed to rebrand host-page markup -->
+  <link rel="stylesheet" href="./node_modules/@kitnai/chat/dist/theme.tokens.css" />
+</head>
+<body style="height: 100vh; margin: 0;">
+  <kitn-chat id="chat" style="display: block; height: 100%;"></kitn-chat>
+
+  <script type="module">
+    import '@kitnai/chat/elements';
+
+    const chat = document.getElementById('chat');
+
+    // Arrays and objects → JS properties
+    chat.messages = [
+      { id: '1', role: 'assistant', content: 'Hello! How can I help?', actions: ['copy', 'like', 'dislike'] },
+    ];
+    chat.suggestions = ['Summarize the chat', 'Start fresh'];
+
+    // Events → addEventListener on the element (they don't bubble)
+    chat.addEventListener('submit', async (e) => {
+      const text = e.detail.value;
+
+      // Append user message (new array → triggers re-render)
+      const history = [...chat.messages, { id: crypto.randomUUID(), role: 'user', content: text }];
+      chat.messages = history;
+      chat.loading = true;
+
+      // Stream into an empty assistant placeholder
+      const aid = crypto.randomUUID();
+      chat.messages = [...history, { id: aid, role: 'assistant', content: '' }];
+
+      let answer = '';
+      for await (const token of streamFromYourAPI(history)) {
+        answer += token;
+        // Replace the placeholder with a new object each chunk
+        chat.messages = chat.messages.map((m) =>
+          m.id === aid ? { ...m, content: answer } : m
+        );
+      }
+      chat.loading = false;
+    });
+  </script>
+</body>
+</html>
+```
+
+> **Reactivity:** always assign a **new array** (and a new object for any message you change). Mutating an existing object in place will not trigger a re-render.
+
+### Scalar attributes
+
+Scalars can go directly in the HTML as attributes:
+
+```html
+<!-- theme, placeholder, and loading are scalar → safe as attributes -->
+<kitn-chat
+  theme="dark"
+  placeholder="Ask anything…"
+></kitn-chat>
+```
+
+---
+
+## React
+
+The kit ships auto-generated, typed React wrappers under `@kitnai/chat/react`. They handle the ref plumbing internally — rich props are set as DOM **properties** and CustomEvents are exposed as `on<Event>` handlers, so you write idiomatic JSX without touching refs yourself.
+
+```tsx
+import { KitnChat, KitnConversationList } from '@kitnai/chat/react';
+import { useState } from 'react';
+
+type Message = {
+  id: string;
+  role: 'user' | 'assistant';
+  content: string;
+  actions?: string[];
+};
+
+export function App() {
+  const [messages, setMessages] = useState<Message[]>([
+    { id: '1', role: 'assistant', content: 'Hello! How can I help?', actions: ['copy'] },
+  ]);
+
+  const handleSubmit = async (e: CustomEvent<{ value: string }>) => {
+    const text = e.detail.value;
+
+    const history = [...messages, { id: crypto.randomUUID(), role: 'user' as const, content: text }];
+    setMessages(history);
+
+    // Placeholder to stream into
+    const aid = crypto.randomUUID();
+    setMessages([...history, { id: aid, role: 'assistant', content: '' }]);
+
+    let answer = '';
+    for await (const token of streamFromYourAPI(history)) {
+      answer += token;
+      setMessages((prev) =>
+        prev.map((m) => (m.id === aid ? { ...m, content: answer } : m))
+      );
+    }
+  };
+
+  return (
+    <KitnChat
+      messages={messages}
+      suggestions={['Summarize the chat', 'Start fresh']}
+      onSubmit={handleSubmit}
+      onMessageaction={(e) => console.log('action', e.detail)}
+      style={{ display: 'block', height: '100vh' }}
+    />
+  );
+}
+```
+
+### Event prop naming
+
+Event props follow the `on` + event-name pattern (camelCased):
+
+| DOM event name | React prop |
+|---|---|
+| `submit` | `onSubmit` |
+| `valuechange` | `onValuechange` |
+| `messageaction` | `onMessageaction` |
+| `modelchange` | `onModelchange` |
+| `suggestionclick` | `onSuggestionclick` |
+| `slashselect` | `onSlashselect` |
+| `search` | `onSearch` |
+| `voice` | `onVoice` |
+
+### All 27 elements have typed wrappers
+
+Component names are the PascalCase of the tag name:
+
+```tsx
+import {
+  KitnChat,
+  KitnConversationList,
+  KitnPromptInput,
+  KitnMessage,
+  KitnMarkdown,
+  KitnCodeBlock,
+  KitnReasoning,
+  KitnTool,
+  KitnContextMeter,
+  KitnModelSwitcher,
+  KitnAttachments,
+  KitnLoader,
+  // …all 27 elements
+} from '@kitnai/chat/react';
+```
+
+### Without the React wrappers (raw custom element)
+
+If you prefer to work with the raw custom element directly (e.g. with React 19's improved custom-element support), use a `ref` + `useEffect`:
+
+```tsx
+import { useEffect, useRef, useState } from 'react';
+import '@kitnai/chat/elements';
+
+export function Chat() {
+  const chatRef = useRef<HTMLElement>(null);
+  const [messages, setMessages] = useState([
+    { id: '1', role: 'assistant', content: 'Hello!' },
+  ]);
+
+  // Set object/array properties — cannot go through JSX props
+  useEffect(() => {
+    const el = chatRef.current;
+    if (!el) return;
+    (el as any).messages = messages;
+  }, [messages]);
+
+  // Wire events with addEventListener
+  useEffect(() => {
+    const el = chatRef.current;
+    if (!el) return;
+
+    const onSubmit = (e: Event) => {
+      const { value } = (e as CustomEvent<{ value: string }>).detail;
+      setMessages((prev) => [
+        ...prev,
+        { id: crypto.randomUUID(), role: 'user', content: value },
+      ]);
+    };
+
+    el.addEventListener('submit', onSubmit);
+    return () => el.removeEventListener('submit', onSubmit);
+  }, []);
+
+  return <kitn-chat ref={chatRef} style={{ display: 'block', height: '100vh' }} />;
+}
+```
+
+---
+
+## Vue
+
+In Vue, use the element directly in your template. Pass arrays and objects via the `.prop` modifier (or `:propName.prop` for dynamic bindings) so Vue sets them as DOM properties rather than HTML attributes. Events use the standard `@event` syntax.
+
+```html
+<script setup lang="ts">
+import { ref, onMounted } from 'vue';
+import '@kitnai/chat/elements';
+
+const messages = ref([
+  { id: '1', role: 'assistant', content: 'Hello! How can I help?' },
+]);
+
+const handleSubmit = (e: CustomEvent<{ value: string }>) => {
+  const text = e.detail.value;
+  messages.value = [
+    ...messages.value,
+    { id: crypto.randomUUID(), role: 'user', content: text },
+  ];
+  // …stream a reply and append an assistant message
+};
+</script>
+
+<template>
+  <!-- Arrays/objects → .prop modifier; scalars → plain attributes -->
+  <kitn-chat
+    :messages.prop="messages"
+    placeholder="Ask anything…"
+    theme="auto"
+    style="display: block; height: 100vh"
+    @submit="handleSubmit"
+  />
+</template>
+```
+
+### Vue + TypeScript: augmenting JSX types
+
+Add `@kitnai/chat/elements` to your `vite.config.ts` / `env.d.ts` once so Vue's template compiler knows the element's attributes:
+
+```ts
+// env.d.ts (or vite-env.d.ts)
+/// <reference types="@kitnai/chat/elements" />
+```
+
+### Sidebar + chat together (Vue)
+
+Cross-element coordination goes through the host component — the `<kitn-conversation-list>` fires `select`, you update a reactive ref, and pass it into `<kitn-chat>`:
+
+```html
+<script setup lang="ts">
+import '@kitnai/chat/elements';
+import { ref } from 'vue';
+
+const conversations = ref([
+  { id: 'c1', title: 'First chat', scope: { type: 'document' }, messageCount: 3,
+    lastMessageAt: '2026-06-01T12:00:00Z', updatedAt: '2026-06-01T12:00:00Z' },
+]);
+const activeId = ref('c1');
+const messages = ref([{ id: '1', role: 'assistant', content: 'Hi!' }]);
+
+const onSelect = (e: CustomEvent<{ id: string }>) => {
+  activeId.value = e.detail.id;
+  // load messages for the selected conversation
+};
+</script>
+
+<template>
+  <div style="display: flex; height: 100vh;">
+    <kitn-conversation-list
+      :conversations.prop="conversations"
+      :active-id="activeId"
+      style="width: 260px"
+      @select="onSelect"
+    />
+    <kitn-chat
+      :messages.prop="messages"
+      style="flex: 1"
+    />
+  </div>
+</template>
+```
+
+---
+
+## Svelte
+
+Svelte's template compiler sets DOM **properties** when you bind with `bind:` or use the `|propname` directive. For custom events, use `on:eventname`:
+
+```html
+<script>
+  import '@kitnai/chat/elements';
+
+  let messages = [
+    { id: '1', role: 'assistant', content: 'Hello!' }
+  ];
+
+  function handleSubmit(e) {
+    const text = e.detail.value;
+    messages = [...messages, { id: crypto.randomUUID(), role: 'user', content: text }];
+    // …stream reply
+  }
+</script>
+
+<!-- use:action pattern to set properties -->
+<kitn-chat
+  use:setProps={{ messages }}
+  style="display: block; height: 100vh"
+  on:submit={handleSubmit}
+/>
+
+<script context="module">
+  function setProps(node, props) {
+    Object.assign(node, props);
+    return {
+      update(newProps) { Object.assign(node, newProps); }
+    };
+  }
+</script>
+```
+
+---
+
+## Angular
+
+Angular needs **no wrappers** — its property binding (`[prop]="value"`) assigns the DOM **property** directly, so arrays and objects pass through unstringified. Register the elements once, allow the custom tags with `CUSTOM_ELEMENTS_SCHEMA`, and handle events with `(event)="handler($event)"` (the payload is on `$event.detail`).
+
+```ts
+// main.ts — register the kitn-* elements once, app-wide
+import '@kitnai/chat/elements';
+```
+
+```ts
+// app.component.ts
+import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
+
+@Component({
+  selector: 'app-root',
+  standalone: true,
+  templateUrl: './app.component.html',
+  schemas: [CUSTOM_ELEMENTS_SCHEMA], // allow the <kitn-*> custom elements
+})
+export class AppComponent {
+  messages = [{ id: '1', role: 'assistant', content: 'Hello!' }];
+  models = [{ id: 'opus', name: 'Claude Opus' }];
+  loading = false;
+
+  onSubmit(e: Event) {
+    const { value } = (e as CustomEvent<{ value: string }>).detail;
+    // Reassign a NEW array so change detection re-renders.
+    this.messages = [
+      ...this.messages,
+      { id: crypto.randomUUID(), role: 'user', content: value },
+    ];
+    // …stream the reply, reassigning this.messages with a new array each chunk
+  }
+
+  onModelChange(e: Event) {
+    console.log('model:', (e as CustomEvent<{ modelId: string }>).detail.modelId);
+  }
+}
+```
+
+```html
+<!-- app.component.html -->
+<kitn-chat
+  [messages]="messages"
+  [models]="models"
+  [loading]="loading"
+  theme="auto"
+  style="display: block; height: 100vh"
+  (submit)="onSubmit($event)"
+  (modelchange)="onModelChange($event)"
+></kitn-chat>
+```
+
+> **Why `[messages]` works:** Angular's `[prop]` binding writes to the element's DOM property (not an attribute), so the property-vs-attribute rule is satisfied automatically. Scalars like `theme` can be plain attributes. `CUSTOM_ELEMENTS_SCHEMA` is required so Angular doesn't error on the unknown `kitn-*` tags.
+
+---
 
 ## Streaming from OpenRouter
 
-[OpenRouter](https://openrouter.ai) exposes an OpenAI-compatible streaming API (Server-Sent Events). On `submit`, append the user message plus an empty assistant message, then grow the assistant message as tokens arrive.
+[OpenRouter](https://openrouter.ai) exposes an OpenAI-compatible streaming API (Server-Sent Events). Wire it into the `submit` event:
 
-> **Security:** never ship an API key to the browser. In production, point `fetch` at your own backend that proxies to OpenRouter and injects the key. The parsing is identical either way.
+> **Security:** never ship an API key to the browser. In production, point `fetch` at your own backend that proxies to OpenRouter and injects the key.
 
 ```js
 chat.addEventListener('submit', async (e) => {
   const text = e.detail.value.trim();
   if (!text) return;
 
-  // 1. Show the user message; clear the input
+  // 1. Show the user message
   const history = [...chat.messages, { id: crypto.randomUUID(), role: 'user', content: text }];
   chat.messages = history;
-  chat.value = '';
   chat.loading = true;
 
-  // 2. Add an empty assistant message to stream into
+  // 2. Empty assistant placeholder to stream into
   const assistantId = crypto.randomUUID();
   chat.messages = [...history, { id: assistantId, role: 'assistant', content: '' }];
 
-  // In production, replace this URL with your own proxy endpoint.
+  // In production, replace this with your own proxy endpoint.
   const res = await fetch('https://openrouter.ai/api/v1/chat/completions', {
     method: 'POST',
     headers: {
-      'Authorization': `Bearer ${OPENROUTER_API_KEY}`, // server-side in production!
+      'Authorization': `Bearer ${OPENROUTER_API_KEY}`,
       'Content-Type': 'application/json',
     },
     body: JSON.stringify({
@@ -52,17 +451,16 @@ chat.addEventListener('submit', async (e) => {
     buffer += decoder.decode(value, { stream: true });
 
     const lines = buffer.split('\n');
-    buffer = lines.pop();                       // keep the partial last line
+    buffer = lines.pop();
     for (const line of lines) {
       const s = line.trim();
-      if (!s.startsWith('data:')) continue;     // skip keep-alive comments
+      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;
-        // New object for the streaming message so the row re-renders
         chat.messages = chat.messages.map((m) =>
           m.id === assistantId ? { ...m, content: answer } : m
         );
@@ -73,6 +471,8 @@ chat.addEventListener('submit', async (e) => {
 });
 ```
 
+---
+
 ## Text-to-speech (TTS)
 
 ### Browser-native (zero dependencies)
@@ -91,7 +491,7 @@ function speak(text) {
 
 ### Cloud TTS (OpenAI, ElevenLabs, …)
 
-For higher-quality voices, have your backend call a TTS API and return audio, then play it (keep the provider key server-side):
+For higher-quality voices, have your backend call a TTS API and return audio (keep the provider key server-side):
 
 ```js
 async function speakCloud(text) {
@@ -107,4 +507,4 @@ async function speakCloud(text) {
 
 ## Speech-to-text
 
-The reverse direction is built in — the kit ships a `VoiceInput` component for capturing microphone input. Find it in the sidebar under the component stories.
+The reverse direction is built in — the kit ships `<kitn-voice-input>` (and a `VoiceInput` SolidJS component). Find it in the sidebar under the component stories.

package/src/stories/docs/Introduction.mdx

@@ -1,7 +1,7 @@
 import { Meta, Canvas } from '@storybook/addon-docs/blocks';
 import * as ChatPanel from '../chat-panel-layout.stories';
 
-<Meta title="Introduction" />
+<Meta title="Docs/Introduction" />
 
 # @kitnai/chat
 
@@ -21,9 +21,9 @@ Message threads, prompt inputs, streaming responses, markdown + code rendering,
 
 ## Where to next
 
-- **[Installation](?path=/docs/installation--docs)** — add it to your project
-- **[Getting Started](?path=/docs/getting-started--docs)** — your first chat in a few lines, plus a full example
-- **[Theming](?path=/docs/theming--docs)** — make it match your brand
-- **[Integrations](?path=/docs/integrations--docs)** — stream responses from OpenRouter and add text-to-speech
+- **[Installation](?path=/docs/docs-installation--docs)** — add it to your project
+- **[Getting Started](?path=/docs/docs-getting-started--docs)** — your first chat in a few lines, plus a full example
+- **[Theming](?path=/docs/docs-theming--docs)** — make it match your brand
+- **[Integrations](?path=/docs/docs-frameworks-integrations--docs)** — stream responses from OpenRouter and add text-to-speech
 
 Or browse every component in isolation from the sidebar.

package/src/stories/docs/Theming.mdx

@@ -1,7 +1,7 @@
 import { Meta, Canvas } from '@storybook/addon-docs/blocks';
 import * as TokenRef from '../token-reference.stories';
 
-<Meta title="Theming" />
+<Meta title="Docs/Theming" />
 
 # Theming