npm - @kitnai/chat - Versions diffs - 0.3.1 → 0.5.0 - Mend

@kitnai/chat 0.3.1 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (119) hide show

package/README.md +35 -5
package/dist/custom-elements.json +2969 -0
package/dist/kitn-chat.es.js +52 -39
package/dist/llms/llms-full.txt +718 -0
package/dist/llms/llms.txt +104 -0
package/dist/theme.tokens.css +137 -0
package/frameworks/react/index.tsx +584 -0
package/frameworks/react/runtime.tsx +94 -0
package/llms-full.txt +718 -0
package/llms.txt +104 -0
package/package.json +53 -6
package/src/components/attachments.tsx +4 -2
package/src/components/chain-of-thought.tsx +1 -1
package/src/components/chat-scope-picker.tsx +2 -2
package/src/components/chat-thread.tsx +217 -0
package/src/components/checkpoint.tsx +7 -3
package/src/components/context.tsx +14 -18
package/src/components/conversation-item.tsx +1 -1
package/src/components/conversation-list.tsx +5 -4
package/src/components/message-skills.tsx +1 -1
package/src/components/message.tsx +1 -0
package/src/components/model-switcher.tsx +3 -3
package/src/components/prompt-input.tsx +20 -2
package/src/components/reasoning.tsx +2 -2
package/src/components/scroll-button.tsx +1 -0
package/src/components/slash-command.tsx +17 -8
package/src/components/source.tsx +2 -2
package/src/components/thinking-bar.tsx +2 -2
package/src/components/tool.tsx +17 -6
package/src/components/voice-input.tsx +5 -1
package/src/elements/attachments.tsx +132 -0
package/src/elements/chain-of-thought.tsx +45 -0
package/src/elements/chat-scope-picker.tsx +36 -0
package/src/elements/chat-workspace.tsx +122 -0
package/src/elements/chat.tsx +31 -228
package/src/elements/checkpoint.tsx +43 -0
package/src/elements/code-block.tsx +42 -0
package/src/elements/compiled.css +1 -1
package/src/elements/context-meter.tsx +71 -0
package/src/elements/conversation-list.tsx +6 -0
package/src/elements/default-input.tsx +22 -1
package/src/elements/define.tsx +98 -12
package/src/elements/element-types.d.ts +444 -0
package/src/elements/empty.tsx +29 -0
package/src/elements/feedback-bar.tsx +33 -0
package/src/elements/file-upload.tsx +44 -0
package/src/elements/image.tsx +32 -0
package/src/elements/kitn-attachments.stories.tsx +181 -0
package/src/elements/kitn-chain-of-thought.stories.tsx +75 -0
package/src/elements/kitn-chat-scope-picker.stories.tsx +72 -0
package/src/elements/kitn-chat-workspace.stories.tsx +195 -0
package/src/elements/kitn-checkpoint.stories.tsx +71 -0
package/src/elements/kitn-code-block.stories.tsx +82 -0
package/src/elements/kitn-context-meter.stories.tsx +85 -0
package/src/elements/kitn-empty.stories.tsx +110 -0
package/src/elements/kitn-feedback-bar.stories.tsx +73 -0
package/src/elements/kitn-file-upload.stories.tsx +81 -0
package/src/elements/kitn-image.stories.tsx +70 -0
package/src/elements/kitn-loader.stories.tsx +87 -0
package/src/elements/kitn-markdown.stories.tsx +75 -0
package/src/elements/kitn-message-skills.stories.tsx +74 -0
package/src/elements/kitn-message.stories.tsx +105 -0
package/src/elements/kitn-model-switcher.stories.tsx +80 -0
package/src/elements/kitn-prompt-input.stories.tsx +74 -16
package/src/elements/kitn-prompt-suggestions.stories.tsx +157 -0
package/src/elements/kitn-reasoning.stories.tsx +76 -0
package/src/elements/kitn-response-stream.stories.tsx +79 -0
package/src/elements/kitn-source-list.stories.tsx +77 -0
package/src/elements/kitn-source.stories.tsx +87 -0
package/src/elements/kitn-text-shimmer.stories.tsx +63 -0
package/src/elements/kitn-thinking-bar.stories.tsx +72 -0
package/src/elements/kitn-tool.stories.tsx +88 -0
package/src/elements/kitn-voice-input.stories.tsx +87 -0
package/src/elements/loader.tsx +25 -0
package/src/elements/markdown.tsx +38 -0
package/src/elements/message-skills.tsx +22 -0
package/src/elements/message.tsx +125 -0
package/src/elements/model-switcher.tsx +35 -0
package/src/elements/prompt-input.tsx +83 -7
package/src/elements/prompt-suggestions.tsx +58 -0
package/src/elements/reasoning.tsx +50 -0
package/src/elements/register.ts +32 -0
package/src/elements/response-stream.tsx +40 -0
package/src/elements/source.tsx +67 -0
package/src/elements/styles.css +14 -0
package/src/elements/text-shimmer.tsx +28 -0
package/src/elements/thinking-bar.tsx +34 -0
package/src/elements/tool.tsx +23 -0
package/src/elements/voice-input.tsx +41 -0
package/src/index.ts +0 -1
package/src/primitives/chat-config.tsx +3 -3
package/src/stories/docs/Accessibility.mdx +119 -0
package/src/stories/docs/ForAIAgents.mdx +93 -0
package/src/stories/docs/GettingStarted.mdx +2 -2
package/src/stories/docs/Installation.mdx +29 -2
package/src/stories/docs/Integrations.mdx +417 -15
package/src/stories/docs/Introduction.mdx +17 -8
package/src/stories/docs/Theming.mdx +1 -1
package/src/stories/pattern-centered-conversation.stories.tsx +93 -0
package/src/stories/pattern-docked-widget.stories.tsx +93 -0
package/src/stories/pattern-empty-state.stories.tsx +76 -0
package/src/stories/typography.stories.tsx +78 -0
package/src/ui/button.tsx +1 -1
package/src/ui/collapsible.stories.tsx +70 -0
package/src/ui/collapsible.tsx +119 -8
package/src/ui/dropdown.stories.tsx +60 -0
package/src/ui/dropdown.tsx +177 -12
package/src/ui/hover-card.stories.tsx +78 -0
package/src/ui/hover-card.tsx +147 -26
package/src/ui/overlay.stories.tsx +115 -0
package/src/ui/overlay.tsx +151 -0
package/src/ui/scroll-area.stories.tsx +51 -0
package/src/ui/textarea.stories.tsx +77 -0
package/src/ui/textarea.tsx +1 -1
package/src/ui/tooltip.stories.tsx +1 -1
package/src/ui/tooltip.tsx +59 -13
package/src/utils/cn.ts +19 -1
package/theme.css +76 -43
package/src/ui/dialog.tsx +0 -21

package/src/stories/docs/Integrations.mdx CHANGED Viewed

@@ -1,37 +1,438 @@
 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.
+> **Want the whole shell in one tag?** `<kitn-chat-workspace>` bundles the conversation-list sidebar, the drag-to-resize handle, and the full chat thread together. Set `conversations`, `messages`, and optionally `models` as properties; listen for `conversationselect` and `submit`. See the <a href="?path=/docs/web-components-kitn-chat-workspace--docs">kitn-chat-workspace story</a> and the <a href="https://github.com/kitn-ai/kitn-chat/blob/main/docs/web-components.md#kitn-chat-workspace--kitnchatworkspace">web-components.md reference</a> for the full API.
+```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 +453,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 +473,8 @@ chat.addEventListener('submit', async (e) => {
 });
 ```
+---
 ## Text-to-speech (TTS)
 ### Browser-native (zero dependencies)
@@ -91,7 +493,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 +509,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 CHANGED Viewed

@@ -1,11 +1,11 @@
 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
-**A SolidJS + Shadow-DOM web component kit for building AI chat interfaces.**
+**Framework-agnostic, Shadow-DOM web components for building AI chat interfaces.**
 Message threads, prompt inputs, streaming responses, markdown + code rendering, reasoning & tool-call panels, attachments, and a conversation sidebar — composable building blocks you can drop into any app.
@@ -13,17 +13,26 @@ Message threads, prompt inputs, streaming responses, markdown + code rendering,
 ## Why @kitnai/chat
-- **Two ways to use it** — import the SolidJS components for full compositional control, or drop in framework-agnostic **web components** (`<kitn-chat>`) that work in React, Vue, Svelte, or plain HTML.
+- **Works in any framework** — drop in the framework-agnostic **web components** (`<kitn-chat>`) and they just work in React, Vue, Angular, Svelte, or plain HTML. Authored in SolidJS, so SolidJS apps can also import the components natively for full compositional control.
 - **Zero style conflicts** — the web components render in **Shadow DOM**, so the host page's CSS can't leak in and the kit's Tailwind can't leak out.
 - **Lightweight** — a markdown-only `<kitn-chat>` is **~61 KB gzip**, a single file. Syntax highlighting loads **on demand, per language, with no WASM** — and never loads at all if you don't render code.
-- **~50 composable components** across three layers: headless primitives → UI primitives (built on [Kobalte](https://kobalte.dev)) → AI feature components.
+- **~50 composable components** across three layers: headless primitives → accessible UI primitives (built in-house, WCAG 2.1 AA — no third-party UI dependency) → AI feature components.
 - **Themeable** — restyle everything by overriding a handful of `--color-*` design tokens.
+## Browsing the sidebar — which group do I copy from?
+The kit ships at two layers, and the sidebar reflects that. **Use the right one for your stack:**
+- **Web Components** — the framework-agnostic `<kitn-*>` custom elements. **This is what to copy into a React, Vue, Angular, Svelte, or plain-HTML app.** Data goes on JS properties, interactions come back as events.
+- **Components · SolidJS** and **UI · SolidJS** — the **native SolidJS** components (feature components) and primitives (Button, Dropdown, HoverCard, …) that the web components are *built from*. Their snippets are SolidJS JSX, so **only copy these into a SolidJS app**.
+In other words: the `<kitn-chat>` web component is a thin facade over the SolidJS `ChatContainer`/`Message`/… components — same UI, different consumption model. When in doubt, reach for **Web Components**.
 ## 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 CHANGED Viewed

@@ -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

package/src/stories/pattern-centered-conversation.stories.tsx ADDED Viewed

@@ -0,0 +1,93 @@
+import type { Meta, StoryObj } from 'storybook-solidjs-vite';
+import { createSignal } from 'solid-js';
+import {
+  ChatConfig, ChatContainer, ChatContainerContent, ChatContainerScrollAnchor,
+  Message, MessageContent, MessageActions,
+  PromptInput, PromptInputTextarea, PromptInputActions,
+  ModelSwitcher, Button,
+} from '../index';
+import type { ModelOption } from '../types';
+import { Copy, ThumbsUp, ArrowUp } from 'lucide-solid';
+const meta: Meta = {
+  title: 'Patterns/Centered Conversation',
+  parameters: {
+    layout: 'centered',
+    docs: {
+      description: {
+        component:
+          'A single, centered reading column with no sidebar (Claude.ai-style). The messages and composer share one `max-w` measure centered in the viewport — ideal for a focused, full-window chat. Contrast with **Chat Panel Layout** (a compact embedded panel) and the **Full Chat App** example (a resizable workspace).',
+      },
+    },
+  },
+};
+export default meta;
+type Story = StoryObj;
+const models: ModelOption[] = [
+  { id: 'claude-4', name: 'Claude 4 Opus', provider: 'Anthropic' },
+  { id: 'gpt-4o', name: 'GPT-4o', provider: 'OpenAI' },
+];
+const answer = `Sure — here's the gist:
+- **Signals** are fine-grained, so only the DOM that reads a signal updates.
+- **No re-renders** — components run once; reactive expressions do the work.
+- **No dependency arrays** — effects auto-track what they read.
+Want a code example next?`;
+export const Focused: Story = {
+  render: () => {
+    const [input, setInput] = createSignal('');
+    const [model, setModel] = createSignal('claude-4');
+    return (
+      <ChatConfig proseSize="base">
+        <div style={{ width: '860px', height: '680px' }} class="flex flex-col overflow-hidden rounded-xl border border-border bg-background">
+          <header class="flex h-14 shrink-0 items-center justify-between border-b border-border px-5">
+            <span class="text-sm font-semibold text-foreground">New conversation</span>
+            <ModelSwitcher models={models} currentModelId={model()} onModelChange={setModel} />
+          </header>
+          <div class="relative flex-1 overflow-y-auto">
+            <ChatContainer class="h-full">
+              <ChatContainerContent class="space-y-6 px-5 py-6">
+                <Message class="mx-auto flex w-full max-w-2xl flex-col items-end">
+                  <MessageContent class="bg-muted text-primary max-w-[85%] rounded-3xl px-5 py-2.5">
+                    In one paragraph, why is SolidJS reactivity fast?
+                  </MessageContent>
+                </Message>
+                <Message class="mx-auto flex w-full max-w-2xl flex-col items-start">
+                  <div class="group flex w-full flex-col">
+                    <MessageContent markdown class="bg-transparent p-0 text-foreground">
+                      {answer}
+                    </MessageContent>
+                    <MessageActions class="-ml-2.5 flex gap-0 opacity-0 transition-opacity duration-150 group-hover:opacity-100">
+                      <Button variant="ghost" size="icon-sm" class="rounded-full"><Copy class="size-3.5" /></Button>
+                      <Button variant="ghost" size="icon-sm" class="rounded-full"><ThumbsUp class="size-3.5" /></Button>
+                    </MessageActions>
+                  </div>
+                </Message>
+                <ChatContainerScrollAnchor />
+              </ChatContainerContent>
+            </ChatContainer>
+          </div>
+          <div class="shrink-0 px-5 pb-5">
+            <div class="mx-auto max-w-2xl">
+              <PromptInput value={input()} onValueChange={setInput} onSubmit={() => setInput('')}>
+                <PromptInputTextarea placeholder="Reply…" class="min-h-[44px] pt-3 pl-4" />
+                <PromptInputActions class="mt-2 flex w-full items-center justify-end gap-2 px-3 pb-3">
+                  <Button size="icon-sm" class="rounded-full" disabled={!input().trim()}>
+                    <ArrowUp class="size-4" />
+                  </Button>
+                </PromptInputActions>
+              </PromptInput>
+            </div>
+          </div>
+        </div>
+      </ChatConfig>
+    );
+  },
+};