@kitnai/chat 0.3.0 → 0.4.0

package/llms-full.txt

@@ -0,0 +1,667 @@
+<!-- AUTO-GENERATED by scripts/gen-llms.mjs — do not edit by hand. Run `npm run build`. -->
+# @kitnai/chat — Full Reference
+
+# @kitnai/chat
+
+> SolidJS + Shadow-DOM web component kit for building AI chat interfaces. 27 `kitn-*` custom elements: streaming responses, markdown + code rendering, reasoning/tool panels, attachments, conversation sidebar, voice input. Zero framework dependency for consumers; SolidJS is bundled in.
+
+## Install
+
+```bash
+npm install @kitnai/chat
+# SolidJS consumers also need the peer dep:
+npm install solid-js
+```
+
+## #1 rule: array/object data goes on JS PROPERTIES, not HTML attributes
+
+This is the single most common mistake. Arrays and objects (`messages`, `models`, `context`, `suggestions`, `slashCommands`, …) MUST be assigned as JavaScript properties on the element. They CANNOT be passed as HTML attributes — an HTML attribute is always a string and will be ignored or mis-parsed.
+
+```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 values (string/number/boolean) work as attributes (e.g. `placeholder`, `loading`, `theme`).
+
+## Two layers
+
+**Layer 1 — batteries-included web components** (`import '@kitnai/chat/elements'`):
+Drop an element into any framework (React, Vue, plain HTML). Data in via JS properties; interactions out via non-bubbling CustomEvents.
+
+- `<kitn-chat>` — full chat UI (message list + prompt input). The primary starting point.
+- `<kitn-conversation-list>` — sidebar conversation browser with group support.
+- `<kitn-prompt-input>` — standalone composer with send button.
+
+**Layer 2 — composable primitives** (`import { … } from '@kitnai/chat'`):
+All 27 elements are also exported individually. Use them for custom layouts or features `<kitn-chat>` does not expose (ChainOfThought, FeedbackBar, ThinkingBar, VoiceInput, …). Your bundler tree-shakes the rest.
+
+## Key rules for the web components
+
+1. **Array/object data = JS properties** (see above). Scalars may be attributes.
+2. **Events are non-bubbling `CustomEvent`s** — listen directly on the element:
+   `chat.addEventListener('submit', (e) => console.log(e.detail.value))`
+3. **`theme` attribute** (`'light' | 'dark' | 'auto'`) works on every element. Default `auto` follows `prefers-color-scheme`.
+4. **Theming via CSS custom properties** — override `--kitn-color-*` tokens on `:root`; they pierce Shadow DOM.
+
+## ChatMessage schema (required for `<kitn-chat>`)
+
+```ts
+interface ChatMessage {
+  id: string;
+  role: 'user' | 'assistant';
+  content: string;
+  reasoning?: { text: string; label?: string };
+  tools?: ToolPart[];
+  attachments?: AttachmentData[];
+  actions?: ('copy' | 'like' | 'dislike' | 'regenerate' | 'edit')[];
+}
+```
+
+## Framework wiring
+
+**Plain HTML / CDN**
+```html
+<script type="module" src="https://unpkg.com/@kitnai/chat/elements"></script>
+<kitn-chat style="display:block;height:100vh"></kitn-chat>
+<script type="module">
+  const chat = document.querySelector('kitn-chat');
+  chat.messages = [];
+</script>
+```
+
+**React** — typed wrappers auto-set properties and expose `on<Event>` props:
+```tsx
+import { KitnChat } from '@kitnai/chat/react';
+<KitnChat messages={messages} onSubmit={(e) => send(e.detail.value)} />
+```
+
+**Vue** — use the element directly; pass arrays via `.prop`:
+```vue
+<kitn-chat :messages.prop="messages" @submit="send" />
+```
+
+## Theming
+
+```css
+:root {
+  --kitn-color-background: #0f0f0f;
+  --kitn-color-primary: #7c3aed;
+  --kitn-color-muted: #1e1e1e;
+}
+```
+
+For plain HTML/CDN: `<link rel="stylesheet" href="…/@kitnai/chat/theme.tokens.css">`.
+For Tailwind builds: `@import "@kitnai/chat/theme.css"` in your CSS.
+
+## Docs
+
+- Full element reference (all 27 elements, every prop/event): ./llms-full.txt — https://kitn.dev/llms-full.txt
+- Machine-readable Custom Elements Manifest: https://unpkg.com/@kitnai/chat/dist/custom-elements.json
+- Working examples: https://github.com/kitn-ai/chat/tree/main/examples
+- Storybook: https://storybook.kitn.dev
+- Repository: https://github.com/kitn-ai/chat
+
+---
+
+## How to build a chat app in 5 steps
+
+### 1 — Install
+```bash
+npm install @kitnai/chat
+```
+
+### 2 — Pick your layer
+Drop-in: use `<kitn-chat>` for a full chat UI in one tag (`import '@kitnai/chat/elements'`).
+Composable: combine `<kitn-message>`, `<kitn-prompt-input>`, `<kitn-reasoning>`, … in your own markup.
+
+### 3 — Handle `submit` and stream
+```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 — see streaming note)
+  const history = [...chat.messages, { id: crypto.randomUUID(), role: 'user', content: userText }];
+  chat.messages = history;
+  chat.loading = true;
+
+  // Add an empty assistant placeholder to stream into
+  const aid = crypto.randomUUID();
+  chat.messages = [...history, { id: aid, role: 'assistant', content: '' }];
+
+  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;
+});
+```
+
+### 4 — Wire optional features
+- Reasoning: add `reasoning: { text: '…' }` to an assistant message.
+- Tool calls: add `tools: [{ type: 'search', state: 'output-available', input: {…}, output: {…} }]`.
+- Model switcher: `chat.models = [{ id: 'gpt-4o', name: 'GPT-4o' }]; chat.currentModel = 'gpt-4o';` — listen for `modelchange`.
+- Token meter: `chat.context = { usedTokens: 1200, maxTokens: 128000 };`.
+- History sidebar: add `<kitn-conversation-list>`; listen for `select` and `newchat`.
+
+### 5 — Theme
+Override `--kitn-color-*` tokens on `:root` (they pierce Shadow DOM).
+
+---
+
+## Streaming recipe (critical)
+
+To update messages while streaming, **reassign a NEW array containing a NEW message object** on every chunk. Mutating an existing message object in place will NOT trigger a re-render:
+
+```js
+// ✅ re-renders
+chat.messages = chat.messages.map((m) => (m.id === id ? { ...m, content: next } : m));
+
+// ❌ does NOT re-render
+chat.messages[i].content = next;
+```
+
+The same rule applies to every array/object property (`models`, `context`, `suggestions`, …): replace, don't mutate.
+
+---
+
+## Element reference (27 elements, generated from custom-elements.json)
+
+Every element also accepts the `theme` attribute. Array/object properties are marked with a `—` attribute: they must be set as JS properties.
+
+### `kitn-attachments` / `KitnAttachments`
+
+**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):
+
+| Property | Attribute | Type | Description |
+|---|---|---|---|
+| `items` | — | `{ id: string; type: "file" \| "source-document"; filename?: undefined \| string; mediaType?: undefined \| string; url?: undefined \| string; title?: undefined \| string }[]` | The attachments to render. Set as a JS property (array). |
+| `variant` | `variant` | `undefined \| "grid" \| "inline" \| "list"` | Layout: `grid` = visual tiles, `inline` = icon + label chips, `list` = rows. |
+| `hoverCard` | `hover-card` | `undefined \| false \| true` | Wrap each item in a hover card that previews its details. |
+| `removable` | `removable` | `undefined \| false \| true` | Show a remove button per item; clicking it fires a `remove` event. |
+| `showMediaType` | `show-media-type` | `undefined \| false \| true` | Also show the media type beneath the filename (non-grid variants). |
+| `emptyText` | `empty-text` | `undefined \| string` | Text shown when `items` is empty. |
+
+**Events** (non-bubbling `CustomEvent`s — listen directly on the element):
+
+| Event | `detail` type | Description |
+|---|---|---|
+| `remove` | `CustomEvent<{ id: string }>` | A remove button was clicked. |
+
+---
+
+### `kitn-chain-of-thought` / `KitnChainOfThought`
+
+**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):
+
+| Property | Attribute | Type | Description |
+|---|---|---|---|
+| `steps` | — | `{ label: string; content?: undefined \| string }[]` | The reasoning steps. Set as a JS property. Compound sub-parts collapse to this one data model (Route 1). |
+
+_No events._
+
+---
+
+### `kitn-chat` / `KitnChat`
+
+**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):
+
+| Property | Attribute | Type | Description |
+|---|---|---|---|
+| `messages` | — | `{ id: string; role: "user" \| "assistant"; content: string; reasoning?: undefined \| { text: string; label?: undefined \| string }; tools?: undefined \| { type: string; state: "input-streaming" \| "input-available" \| "output-available" \| "output-error"; input?: undefined \| Record<string, unknown>; output?: undefined \| Record<string, unknown>; toolCallId?: undefined \| string; errorText?: undefined \| string }[]; attachments?: undefined \| { id: string; type: "file" \| "source-document"; filename?: undefined \| string; mediaType?: undefined \| string; url?: undefined \| string; title?: undefined \| string }[]; actions?: undefined \| ("copy" \| "like" \| "dislike" \| "regenerate" \| "edit")[] }[]` | The full message thread to render, newest last. Each entry carries its role, content, and optional reasoning/tools/attachments/actions. Set as a JS property (`el.messages = [...]`). |
+| `value` | `value` | `undefined \| string` | Controlled value of the input. When set, the host owns the input text and must update it on `valuechange`; leave unset for uncontrolled behavior. |
+| `placeholder` | `placeholder` | `undefined \| string` | Placeholder text shown in the empty input. |
+| `loading` | `loading` | `undefined \| false \| true` | When true, shows the loading/streaming state and disables submit (use while awaiting the assistant's reply). |
+| `suggestions` | — | `undefined \| string[]` | Starter prompts shown above the input when the thread is empty. Clicking one follows `suggestionMode`. Set as a JS property. |
+| `suggestionMode` | `suggestion-mode` | `undefined \| "submit" \| "fill"` | What clicking a suggestion does: `'submit'` (default) sends it immediately as if typed and submitted; `'fill'` just places it in the input. |
+| `proseSize` | `prose-size` | `undefined \| "xs" \| "sm" \| "base" \| "lg"` | Body/prose font scale for rendered markdown (`'xs' \| 'sm' \| 'base' \| 'lg'`). Defaults to `'sm'`. |
+| `codeTheme` | `code-theme` | `undefined \| string` | Shiki theme name for syntax-highlighted code blocks (e.g. `'github-dark-dimmed'`). |
+| `codeHighlight` | `code-highlight` | `undefined \| false \| true` | Enable Shiki syntax highlighting in code blocks. Turn off to render plain `<pre>` blocks (lighter, no highlighter load). Default true. |
+| `chatTitle` | `chat-title` | `undefined \| string` | Optional header title shown on the left of the header. |
+| `models` | — | `undefined \| { id: string; name: string; provider?: undefined \| string }[]` | Optional model list. When set (>1 model) a ModelSwitcher is shown in the header and a `modelchange` event fires on selection. |
+| `currentModel` | `current-model` | `undefined \| string` | The currently selected model id (pairs with `models`). |
+| `context` | — | `undefined \| { usedTokens: number; maxTokens: number; inputTokens?: undefined \| number; outputTokens?: undefined \| number; estimatedCost?: undefined \| number }` | Optional context-window token usage. When set, a Context token meter is shown in the header. |
+| `scrollButton` | `scroll-button` | `undefined \| false \| true` | Show the scroll-to-bottom button inside the scroll area. Default true. |
+| `search` | `search` | `undefined \| false \| true` | Show a Search (Globe) button in the input toolbar; fires a `search` event. |
+| `voice` | `voice` | `undefined \| false \| true` | Show a Voice (Mic) button in the input toolbar; fires a `voice` event. |
+| `slashCommands` | — | `undefined \| { id: string; label: string; description?: undefined \| string; category?: undefined \| string }[]` | Slash commands — when set, typing `/` in the input opens the command palette and fires `slashselect`. Set as a JS property. |
+| `slashActiveIds` | — | `undefined \| string[]` | Command ids to highlight as active in the palette. |
+| `slashCompact` | `slash-compact` | `undefined \| false \| true` | Single-line palette rows. |
+
+**Events** (non-bubbling `CustomEvent`s — listen directly on the element):
+
+| Event | `detail` type | Description |
+|---|---|---|
+| `messageaction` | `CustomEvent<unknown>` |  |
+| `modelchange` | `CustomEvent<unknown>` |  |
+| `search` | `CustomEvent<unknown>` |  |
+| `slashselect` | `CustomEvent<unknown>` |  |
+| `submit` | `CustomEvent<unknown>` |  |
+| `suggestionclick` | `CustomEvent<unknown>` |  |
+| `valuechange` | `CustomEvent<unknown>` |  |
+| `voice` | `CustomEvent<unknown>` |  |
+
+---
+
+### `kitn-chat-scope-picker` / `KitnChatScopePicker`
+
+**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):
+
+| Property | Attribute | Type | Description |
+|---|---|---|---|
+| `availableAuthors` | — | `string[]` | Authors to offer as scope filters. Set as a JS property. |
+| `availableTags` | — | `string[]` | Tags to offer as scope filters. Set as a JS property. |
+| `currentLabel` | `current-label` | `undefined \| string` | The label shown on the trigger for the active scope. |
+
+**Events** (non-bubbling `CustomEvent`s — listen directly on the element):
+
+| Event | `detail` type | Description |
+|---|---|---|
+| `scopechange` | `CustomEvent<{ filters: undefined \| { tags?: undefined \| string[]; authors?: undefined \| string[]; contentType?: undefined \| "transcript" \| "markdown"; dateRange?: undefined \| { from: string; to: string } } }>` | A scope was chosen (`undefined` filters = "All Content"). |
+
+---
+
+### `kitn-checkpoint` / `KitnCheckpoint`
+
+**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):
+
+| Property | Attribute | Type | Description |
+|---|---|---|---|
+| `label` | `label` | `undefined \| string` | Optional text beside the icon. |
+| `tooltip` | `tooltip` | `undefined \| string` | Tooltip on hover. |
+| `variant` | `variant` | `undefined \| "ghost" \| "default" \| "outline"` | Visual button style. |
+| `size` | `size` | `undefined \| "sm" \| "lg" \| "md" \| "icon" \| "icon-sm"` | Button size (use an `icon*` size for an icon-only checkpoint). |
+
+**Events** (non-bubbling `CustomEvent`s — listen directly on the element):
+
+| Event | `detail` type | Description |
+|---|---|---|
+| `select` | `CustomEvent` | The checkpoint was clicked. |
+
+---
+
+### `kitn-code-block` / `KitnCodeBlock`
+
+**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):
+
+| Property | Attribute | Type | Description |
+|---|---|---|---|
+| `code` | `code` | `string` | The source code to render. |
+| `language` | `language` | `undefined \| string` | Language grammar (e.g. `js`, `python`). Defaults to `tsx`. |
+| `codeTheme` | `code-theme` | `undefined \| string` | Shiki theme name. |
+| `codeHighlight` | `code-highlight` | `undefined \| false \| true` | Disable syntax highlighting (renders plain text, no Shiki). |
+| `proseSize` | `prose-size` | `undefined \| "xs" \| "sm" \| "base" \| "lg"` | Code text sizing. |
+
+_No events._
+
+---
+
+### `kitn-context-meter` / `KitnContextMeter`
+
+**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):
+
+| Property | Attribute | Type | Description |
+|---|---|---|---|
+| `context` | — | `undefined \| { usedTokens: number; maxTokens: number; inputTokens?: undefined \| number; outputTokens?: undefined \| number; reasoningTokens?: undefined \| number; cacheTokens?: undefined \| number; estimatedCost?: undefined \| number }` | Token-usage data. Set as a JS property. |
+
+_No events._
+
+---
+
+### `kitn-conversation-list` / `KitnConversationList`
+
+**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):
+
+| Property | Attribute | Type | Description |
+|---|---|---|---|
+| `groups` | — | `{ id: string; userId?: undefined \| string; teamId?: undefined \| string; name: string; sortOrder: number; createdAt: string }[]` | Pre-bucketed conversation groups (e.g. "Today", "Yesterday"), each with its own conversations. Use this when you want to control the grouping/headers yourself; otherwise pass a flat `conversations` array. Set as a JS property. |
+| `conversations` | — | `{ id: string; title: string; groupId?: undefined \| string; scope: { type: "document" \| "collection"; documentId?: undefined \| string; filters?: undefined \| { tags?: undefined \| string[]; authors?: undefined \| string[]; contentType?: undefined \| "transcript" \| "markdown"; dateRange?: undefined \| { from: string; to: string } } }; messageCount: number; lastMessageAt: string; updatedAt: string }[]` | A flat list of conversation summaries; the component buckets them by recency for you. Ignored when `groups` is provided. Set as a JS property. |
+| `activeId` | `active-id` | `undefined \| string` | The id of the currently-open conversation, highlighted in the list. |
+
+**Events** (non-bubbling `CustomEvent`s — listen directly on the element):
+
+| Event | `detail` type | Description |
+|---|---|---|
+| `newchat` | `CustomEvent<unknown>` |  |
+| `select` | `CustomEvent<unknown>` |  |
+| `togglesidebar` | `CustomEvent<unknown>` |  |
+
+---
+
+### `kitn-empty` / `KitnEmpty`
+
+**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):
+
+| Property | Attribute | Type | Description |
+|---|---|---|---|
+| `emptyTitle` | `empty-title` | `undefined \| string` | Title text. Attribute: `empty-title` (`title` is a global HTML attribute). |
+| `description` | `description` | `undefined \| string` | Description text. |
+
+_No events._
+
+---
+
+### `kitn-feedback-bar` / `KitnFeedbackBar`
+
+**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):
+
+| Property | Attribute | Type | Description |
+|---|---|---|---|
+| `barTitle` | `bar-title` | `undefined \| string` | The banner label (e.g. "Was this helpful?"). Attribute: `bar-title` (`title` is avoided — it's a global HTML attribute). |
+
+**Events** (non-bubbling `CustomEvent`s — listen directly on the element):
+
+| Event | `detail` type | Description |
+|---|---|---|
+| `close` | `CustomEvent` | The user dismissed the banner. |
+| `helpful` | `CustomEvent` | The user clicked thumbs-up. |
+| `nothelpful` | `CustomEvent` | The user clicked thumbs-down. |
+
+---
+
+### `kitn-file-upload` / `KitnFileUpload`
+
+**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):
+
+| Property | Attribute | Type | Description |
+|---|---|---|---|
+| `multiple` | `multiple` | `undefined \| false \| true` | Allow selecting multiple files (default true). |
+| `accept` | `accept` | `undefined \| string` | `accept` attribute for the file picker (e.g. `image/*`). |
+| `disabled` | `disabled` | `undefined \| false \| true` | Disable the dropzone — no clicking, no drag-and-drop. |
+| `label` | `label` | `undefined \| string` | Default dropzone label (overridable via the default slot). |
+
+**Events** (non-bubbling `CustomEvent`s — listen directly on the element):
+
+| Event | `detail` type | Description |
+|---|---|---|
+| `filesadded` | `CustomEvent<{ files: File[] }>` | Files were picked or dropped. |
+
+---
+
+### `kitn-image` / `KitnImage`
+
+**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):
+
+| Property | Attribute | Type | Description |
+|---|---|---|---|
+| `base64` | `base64` | `undefined \| string` | Base64-encoded image data (pair with `media-type`). |
+| `bytes` | — | `undefined \| Uint8Array<ArrayBufferLike>` | Raw image bytes (set as a JS property). |
+| `alt` | `alt` | `undefined \| string` | Alt text. |
+| `mediaType` | `media-type` | `undefined \| string` | MIME type (default `image/png`). |
+
+_No events._
+
+---
+
+### `kitn-loader` / `KitnLoader`
+
+**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):
+
+| Property | Attribute | Type | Description |
+|---|---|---|---|
+| `variant` | `variant` | `undefined \| "circular" \| "classic" \| "pulse" \| "pulse-dot" \| "dots" \| "typing" \| "wave" \| "bars" \| "terminal" \| "text-blink" \| "text-shimmer" \| "loading-dots"` | The animation style: `'circular' \| 'classic' \| 'pulse' \| 'pulse-dot' \| 'dots' \| 'typing' \| 'wave' \| 'bars' \| 'terminal' \| 'text-blink' \| 'text-shimmer' \| 'loading-dots'`. Defaults to `'circular'`. |
+| `size` | `size` | `undefined \| "sm" \| "lg" \| "md"` | Loader size: `'sm' \| 'md' \| 'lg'`. Defaults to `'md'`. |
+| `text` | `text` | `undefined \| string` | Label for the text-based variants. |
+
+_No events._
+
+---
+
+### `kitn-markdown` / `KitnMarkdown`
+
+**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):
+
+| Property | Attribute | Type | Description |
+|---|---|---|---|
+| `content` | `content` | `string` | The markdown source to render. |
+| `proseSize` | `prose-size` | `undefined \| "xs" \| "sm" \| "base" \| "lg"` | Text/markdown sizing. |
+| `codeTheme` | `code-theme` | `undefined \| string` | Shiki theme for fenced code blocks. |
+| `codeHighlight` | `code-highlight` | `undefined \| false \| true` | Disable syntax highlighting (no Shiki loads). |
+
+_No events._
+
+---
+
+### `kitn-message` / `KitnMessage`
+
+**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):
+
+| Property | Attribute | Type | Description |
+|---|---|---|---|
+| `message` | — | `undefined \| { id: string; role: "user" \| "assistant"; content: string; reasoning?: undefined \| { text: string; label?: undefined \| string }; tools?: undefined \| { type: string; state: "input-streaming" \| "input-available" \| "output-available" \| "output-error"; input?: undefined \| Record<string, unknown>; output?: undefined \| Record<string, unknown>; toolCallId?: undefined \| string; errorText?: undefined \| string }[]; attachments?: undefined \| { id: string; type: "file" \| "source-document"; filename?: undefined \| string; mediaType?: undefined \| string; url?: undefined \| string; title?: undefined \| string }[]; actions?: undefined \| ("copy" \| "like" \| "dislike" \| "regenerate" \| "edit")[] }` | The full message object. Set as a JS property. |
+| `role` | `role` | `undefined \| "user" \| "assistant"` | Convenience for simple cases when not passing a `message` object. |
+| `content` | `content` | `undefined \| string` | Convenience content (used when `message` is not set). |
+| `markdown` | `markdown` | `undefined \| false \| true` | Force markdown on/off. Defaults to on for assistant, off for user. |
+| `proseSize` | `prose-size` | `undefined \| "xs" \| "sm" \| "base" \| "lg"` | Text/markdown sizing for the message body. |
+| `codeTheme` | `code-theme` | `undefined \| string` | Shiki theme name used for fenced code blocks in the content. |
+| `codeHighlight` | `code-highlight` | `undefined \| false \| true` | Disable syntax highlighting for code blocks (no Shiki loads). |
+
+**Events** (non-bubbling `CustomEvent`s — listen directly on the element):
+
+| Event | `detail` type | Description |
+|---|---|---|
+| `messageaction` | `CustomEvent<{ messageId: string; action: "copy" \| "like" \| "dislike" \| "regenerate" \| "edit" }>` | An action button was clicked. |
+
+---
+
+### `kitn-message-skills` / `KitnMessageSkills`
+
+**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):
+
+| Property | Attribute | Type | Description |
+|---|---|---|---|
+| `skills` | — | `{ id: string; name: string }[]` | The active skills to badge. Set as a JS property. |
+
+_No events._
+
+---
+
+### `kitn-model-switcher` / `KitnModelSwitcher`
+
+**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):
+
+| Property | Attribute | Type | Description |
+|---|---|---|---|
+| `models` | — | `{ id: string; name: string; provider?: undefined \| string }[]` | The selectable models. Set as a JS property (array). |
+| `currentModel` | `current-model` | `undefined \| string` | The currently-selected model id. Defaults to the first model. |
+
+**Events** (non-bubbling `CustomEvent`s — listen directly on the element):
+
+| Event | `detail` type | Description |
+|---|---|---|
+| `modelchange` | `CustomEvent<{ modelId: string }>` | A model was selected. |
+
+---
+
+### `kitn-prompt-input` / `KitnPromptInput`
+
+**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):
+
+| Property | Attribute | Type | Description |
+|---|---|---|---|
+| `value` | `value` | `undefined \| string` | Controlled value of the input. When set, the host owns the text and must update it on `valuechange`; leave unset for uncontrolled behavior. |
+| `placeholder` | `placeholder` | `undefined \| string` | Placeholder text shown in the empty input. |
+| `disabled` | `disabled` | `undefined \| false \| true` | Disable the input and submit button entirely (non-interactive). |
+| `loading` | `loading` | `undefined \| false \| true` | Show the loading/streaming state and block submit (use while awaiting a reply). |
+| `suggestions` | — | `undefined \| string[]` | Starter prompts shown above the input. Clicking one follows `suggestionMode`. Set as a JS property. |
+| `suggestionMode` | `suggestion-mode` | `undefined \| "submit" \| "fill"` | What clicking a suggestion does: `'submit'` (default) sends it immediately as if typed and submitted; `'fill'` just places it in the input. |
+| `slashCommands` | — | `undefined \| { id: string; label: string; description?: undefined \| string; category?: undefined \| string }[]` | Slash commands — when set, typing `/` opens the command palette. Set as a JS property. |
+| `slashActiveIds` | — | `undefined \| string[]` | Command ids to highlight as active. |
+| `slashCompact` | `slash-compact` | `undefined \| false \| true` | Single-line palette rows. |
+| `search` | `search` | `undefined \| false \| true` | Show a Search (Globe) button in the left toolbar; clicking it fires a `search` event. |
+| `voice` | `voice` | `undefined \| false \| true` | Show a Voice (Mic) button in the left toolbar; clicking it fires a `voice` event. |
+| `attachments` | — | `undefined \| { id: string; type: "file" \| "source-document"; filename?: undefined \| string; mediaType?: undefined \| string; url?: undefined \| string; title?: undefined \| string }[]` | Attachments to seed the input with (so a consumer can pre-populate staged files without an upload). Set as a JS property; the element then manages its own attachment state from there (add via the paperclip, remove per chip). |
+
+**Events** (non-bubbling `CustomEvent`s — listen directly on the element):
+
+| Event | `detail` type | Description |
+|---|---|---|
+| `search` | `CustomEvent<undefined>` | The Search (Globe) toolbar button was clicked. |
+| `slashselect` | `CustomEvent<{ command: { id: string; label: string; description?: undefined \| string; category?: undefined \| string } }>` | A slash command was chosen from the palette. |
+| `submit` | `CustomEvent<{ value: string; attachments: { id: string; type: "file" \| "source-document"; filename?: undefined \| string; mediaType?: undefined \| string; url?: undefined \| string; title?: undefined \| string }[] }>` | The user submitted the prompt (Enter or send button) with its attachments. |
+| `suggestionclick` | `CustomEvent<{ value: string }>` | A suggestion was clicked while `suggestion-mode="fill"`. |
+| `valuechange` | `CustomEvent<{ value: string }>` | The input text changed (fires on every keystroke). |
+| `voice` | `CustomEvent<undefined>` | The Voice (Mic) toolbar button was clicked. |
+
+---
+
+### `kitn-prompt-suggestions` / `KitnPromptSuggestions`
+
+**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):
+
+| Property | Attribute | Type | Description |
+|---|---|---|---|
+| `suggestions` | — | `(string \| { label: string; value?: undefined \| string })[]` | The suggestions. Strings, or `{ label, value }` when the displayed text and the emitted value differ. Set as a JS property. |
+| `variant` | `variant` | `undefined \| "ghost" \| "default" \| "outline"` | Chip style: `'outline'` (default), `'ghost'`, or `'default'` (filled). |
+| `size` | `size` | `undefined \| "sm" \| "lg" \| "md" \| "icon" \| "icon-sm"` | Size preset for each chip. Defaults to the pill default (`'lg'`); pass `'sm'` for smaller pills (or `'md'`). |
+| `block` | `block` | `undefined \| false \| true` | Full-width left-aligned rows instead of pills. |
+| `highlight` | `highlight` | `undefined \| string` | Substring to highlight within each suggestion. |
+
+**Events** (non-bubbling `CustomEvent`s — listen directly on the element):
+
+| Event | `detail` type | Description |
+|---|---|---|
+| `select` | `CustomEvent<{ value: string }>` | A suggestion was clicked. |
+
+---
+
+### `kitn-reasoning` / `KitnReasoning`
+
+**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):
+
+| Property | Attribute | Type | Description |
+|---|---|---|---|
+| `text` | `text` | `string` | The reasoning text to display. |
+| `label` | `label` | `undefined \| string` | Trigger label. |
+| `open` | `open` | `undefined \| false \| true` | Controlled open state — set as a property (`el.open = true`). Omit for uncontrolled (the trigger toggles it). |
+| `streaming` | `streaming` | `undefined \| false \| true` | While true, auto-expands (and re-collapses when it flips false). |
+| `markdown` | `markdown` | `undefined \| false \| true` | Render `text` as markdown. |
+
+**Events** (non-bubbling `CustomEvent`s — listen directly on the element):
+
+| Event | `detail` type | Description |
+|---|---|---|
+| `openchange` | `CustomEvent<{ open: false \| true }>` | Open state changed (via the trigger or streaming auto-open). |
+
+---
+
+### `kitn-response-stream` / `KitnResponseStream`
+
+**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):
+
+| Property | Attribute | Type | Description |
+|---|---|---|---|
+| `text` | — | `undefined \| string \| AsyncIterable<string>` | Text to stream. A string, or an `AsyncIterable<string>` (set as a JS property — async iterables can't be HTML attributes). |
+| `mode` | `mode` | `undefined \| "typewriter" \| "fade"` | Reveal animation. |
+| `speed` | `speed` | `undefined \| number` | Characters/segments per tick. |
+| `as` | `as` | `undefined \| string` | Element tag to render as. |
+
+**Events** (non-bubbling `CustomEvent`s — listen directly on the element):
+
+| Event | `detail` type | Description |
+|---|---|---|
+| `complete` | `CustomEvent` | Streaming finished. |
+
+---
+
+### `kitn-source` / `KitnSource`
+
+**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):
+
+| Property | Attribute | Type | Description |
+|---|---|---|---|
+| `href` | `href` | `undefined \| string` | The URL this citation links to (the domain also seeds the default label/favicon). |
+| `label` | `label` | `undefined \| string` | Trigger label (defaults to the domain). |
+| `headline` | `headline` | `undefined \| string` | Hover-card headline. Attribute: `headline` (`title` is avoided — it's a global HTML attribute that reflects in a CE constructor and breaks it). |
+| `description` | `description` | `undefined \| string` | Hover-card body text describing the source. |
+| `showFavicon` | `show-favicon` | `undefined \| false \| true` | Show the source's favicon next to the trigger label. |
+
+_No events._
+
+---
+
+### `kitn-source-list` / `KitnSourceList`
+
+**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):
+
+| Property | Attribute | Type | Description |
+|---|---|---|---|
+| `sources` | — | `{ href: string; title?: undefined \| string; description?: undefined \| string; label?: undefined \| string; showFavicon?: undefined \| false \| true }[]` | The sources to render. Set as a JS property. |
+| `showFavicon` | `show-favicon` | `undefined \| false \| true` | Show favicons on all items (per-item `showFavicon` overrides). |
+
+_No events._
+
+---
+
+### `kitn-text-shimmer` / `KitnTextShimmer`
+
+**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):
+
+| Property | Attribute | Type | Description |
+|---|---|---|---|
+| `text` | `text` | `undefined \| string` | The text to shimmer. |
+| `as` | `as` | `undefined \| string` | Element tag to render as (default `span`). |
+| `duration` | `duration` | `undefined \| number` | Animation duration in seconds. |
+| `spread` | `spread` | `undefined \| number` | Gradient spread (5–45). |
+
+_No events._
+
+---
+
+### `kitn-thinking-bar` / `KitnThinkingBar`
+
+**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):
+
+| Property | Attribute | Type | Description |
+|---|---|---|---|
+| `text` | `text` | `undefined \| string` | The shimmering label, e.g. "Thinking…". |
+| `stoppable` | `stoppable` | `undefined \| false \| true` | When true, show a "stop" affordance that fires a `stop` event. |
+| `stopLabel` | `stop-label` | `undefined \| string` | Label for the stop affordance. |
+
+**Events** (non-bubbling `CustomEvent`s — listen directly on the element):
+
+| Event | `detail` type | Description |
+|---|---|---|
+| `stop` | `CustomEvent` | The "stop / answer now" affordance was clicked. |
+
+---
+
+### `kitn-tool` / `KitnTool`
+
+**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):
+
+| Property | Attribute | Type | Description |
+|---|---|---|---|
+| `tool` | — | `undefined \| { type: string; state: "input-streaming" \| "input-available" \| "output-available" \| "output-error"; input?: undefined \| Record<string, unknown>; output?: undefined \| Record<string, unknown>; toolCallId?: undefined \| string; errorText?: undefined \| string }` | The tool-call to display. Set as a JS property. |
+| `open` | `open` | `undefined \| false \| true` | Start expanded. |
+
+_No events._
+
+---
+
+### `kitn-voice-input` / `KitnVoiceInput`
+
+**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):
+
+| Property | Attribute | Type | Description |
+|---|---|---|---|
+| `transcribe` | — | `undefined \| (audio: Blob) => Promise<string>` | Transcriber the host supplies — records audio, returns the text. This is a **function-valued property** (`el.transcribe = async blob => '...'`) because a value-returning callback can't be modelled as a fire-and-forget event. |
+| `disabled` | `disabled` | `undefined \| false \| true` | Disable the mic button (non-interactive). |
+
+**Events** (non-bubbling `CustomEvent`s — listen directly on the element):
+
+| Event | `detail` type | Description |
+|---|---|---|
+| `audiocaptured` | `CustomEvent<{ blob: Blob }>` | Raw audio captured (before transcription) — for hosts that prefer to handle transcription themselves instead of via the `transcribe` property. |
+| `transcription` | `CustomEvent<{ text: string }>` | Transcription completed (the `transcribe` property resolved). |
+
+---
+