@kitn.ai/ui 0.14.1

package/src/stories/docs/ChildElements.mdx

@@ -0,0 +1,269 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+
+<Meta title="Docs/Composition & Child Elements" />
+
+# Composition & Child Elements
+
+Seven collection elements in the kit accept two input paths — **data** (a JS property array) and **composition** (declarative child markup). Both produce identical rendered output and can be mixed on the same element.
+
+## Two ways to populate a collection
+
+### Data — the JS property array
+
+Set the element's array property from JavaScript. The parent re-renders reactively whenever the reference changes.
+
+```html
+<kai-suggestions id="s"></kai-suggestions>
+
+<script type="module">
+  import '@kitn.ai/ui/elements';
+
+  document.getElementById('s').suggestions = [
+    { label: 'Summarise this', value: 'summarise' },
+    { label: 'Translate to French', value: 'translate' },
+  ];
+</script>
+```
+
+### Composition — declarative child elements
+
+Place `<kai-*>` child elements directly in markup. They live in the light DOM but are invisible — the parent's Shadow DOM has no `<slot>` for them, so it reads them via `querySelectorAll` and a `MutationObserver` instead. No JavaScript required.
+
+```html
+<kai-suggestions>
+  <kai-suggestion value="summarise">Summarise this</kai-suggestion>
+  <kai-suggestion value="translate">Translate to French</kai-suggestion>
+</kai-suggestions>
+
+<script type="module">
+  import '@kitn.ai/ui/elements';
+</script>
+```
+
+### Merge order
+
+When both are provided, **property items render first** and child elements are appended after. There is no conflict — they simply concatenate.
+
+---
+
+## Choosing the right path
+
+| Situation | Reach for |
+|-----------|-----------|
+| Data arrives from a fetch, a stream, or application state | **Data (property)** |
+| Content is model-driven, user-specific, or changes at runtime | **Data (property)** |
+| You're working in React, Vue, Svelte, or Angular with a component model | **Data (property)** |
+| Content is static and known at build time | **Composition (children)** |
+| You're authoring a CMS template, server-rendered HTML, or a no-build page | **Composition (children)** |
+| You want zero JavaScript for the initial population | **Composition (children)** |
+
+---
+
+## Child element reference
+
+Each row below is verified against the element's source in `src/elements/`.
+
+### `<kai-action>`
+
+**Parents:** `<kai-message>` (action bar → `kai-message-action`) and `<kai-prompt-input>` (custom toolbar buttons → `kai-toolbar-action`)
+
+| Attribute | Maps to | Notes |
+|-----------|---------|-------|
+| `id` | `CustomAction.id` | Falls back to the `action` attribute when `id` is absent |
+| `action` | `CustomAction.id` | Secondary fallback when `id` is also absent |
+| `icon` | `CustomAction.icon` | Optional icon name |
+| `tooltip` | `CustomAction.tooltip` | Optional tooltip string |
+| *(text content)* | `CustomAction.label` | Falls back to the `label` attribute, then `id` |
+
+**Event fired by parent:** `kai-message-action` → `{ messageId: string, action: string }`
+
+```html
+<kai-message>
+  <kai-action id="copy" icon="copy" tooltip="Copy to clipboard">Copy</kai-action>
+  <kai-action id="retry" icon="refresh">Retry</kai-action>
+</kai-message>
+```
+
+---
+
+### `<kai-suggestion>`
+
+**Parent:** `<kai-suggestions>`
+
+| Attribute | Maps to | Notes |
+|-----------|---------|-------|
+| `value` | `Item.value` | Falls back to text content when absent |
+| *(text content)* | `Item.label` | The chip label |
+
+**Event fired by parent:** `kai-select` → `{ value: string }`
+
+```html
+<kai-suggestions>
+  <kai-suggestion value="summarise">Summarise this</kai-suggestion>
+  <kai-suggestion value="translate">Translate to French</kai-suggestion>
+</kai-suggestions>
+```
+
+---
+
+### `<kai-source>`
+
+**Parent:** `<kai-sources>`
+
+| Attribute | Maps to | Notes |
+|-----------|---------|-------|
+| `href` | `SourceItem.href` | Required — the citation URL |
+| `label` | `SourceItem.label` | Trigger label (defaults to the domain) |
+| `headline` | `SourceItem.title` | Hover-card headline. Named `headline` (not `title`) because `title` is a reserved HTML global attribute |
+| `description` | `SourceItem.description` | Hover-card body text |
+| `show-favicon` | `SourceItem.showFavicon` | Boolean — bare attribute or `show-favicon="true"` |
+| *(text content)* | *(not read by `kai-sources`)* | Text content on a child `<kai-source>` is not mapped by the parent; use `label`/`headline`/`description` attributes instead |
+
+**No interaction event** — sources open their `href` as links.
+
+```html
+<kai-sources>
+  <kai-source
+    href="https://example.com/page"
+    label="Example"
+    headline="Example Domain"
+    description="An illustrative domain used in documentation."
+    show-favicon
+  ></kai-source>
+</kai-sources>
+```
+
+> **Note:** `<kai-source>` also works as a **standalone** element — its own `href`, `label`, `headline`, `description`, and `show-favicon` props drive a single citation chip with a hover-card. The child-element role above is its use *inside* `<kai-sources>`.
+
+---
+
+### `<kai-conversation>`
+
+**Parent:** `<kai-conversations>`
+
+| Attribute | Maps to | Notes |
+|-----------|---------|-------|
+| `id` | `ConversationSummary.id` | Required — stable conversation identifier |
+| `group-id` | `ConversationSummary.groupId` | Optional group bucket (e.g. "today", "yesterday") |
+| *(text content)* | `ConversationSummary.title` | The conversation title shown in the list |
+
+Required fields not expressible as HTML attributes (`scope`, `messageCount`, `lastMessageAt`, `updatedAt`) receive safe defaults so the list item is fully functional with just `id` and text.
+
+**Events fired by parent:** `kai-conversation-select` → `{ id: string }`, `kai-new-chat` → `{}`, `kai-toggle-sidebar` → `{}`
+
+```html
+<kai-conversations>
+  <kai-conversation id="conv-1" group-id="today">Morning standup recap</kai-conversation>
+  <kai-conversation id="conv-2" group-id="yesterday">API design review</kai-conversation>
+</kai-conversations>
+```
+
+---
+
+### `<kai-step>`
+
+**Parent:** `<kai-chain-of-thought>`
+
+| Attribute | Maps to | Notes |
+|-----------|---------|-------|
+| `label` | `Step.label` | The always-visible step heading (required) |
+| *(text content)* | `Step.content` | Optional expandable detail; empty string is treated as `undefined` (no expand affordance) |
+
+**No interaction event** — steps expand/collapse internally.
+
+```html
+<kai-chain-of-thought>
+  <kai-step label="Understand the request">The user wants a concise summary.</kai-step>
+  <kai-step label="Draft a response">Condense the key points into three sentences.</kai-step>
+  <kai-step label="Review"></kai-step>
+</kai-chain-of-thought>
+```
+
+---
+
+### `<kai-model>`
+
+**Parent:** `<kai-model-switcher>`
+
+| Attribute | Maps to | Notes |
+|-----------|---------|-------|
+| `id` | `ModelOption.id` | Required — the model identifier passed in `kai-model-change` |
+| `provider` | `ModelOption.provider` | Optional provider name shown in the switcher UI |
+| *(text content)* | `ModelOption.name` | Human-readable model name |
+
+**Event fired by parent:** `kai-model-change` → `{ modelId: string }`
+
+The switcher only renders when more than one model is provided.
+
+```html
+<kai-model-switcher>
+  <kai-model id="gpt-4o" provider="OpenAI">GPT-4o</kai-model>
+  <kai-model id="gpt-4o-mini" provider="OpenAI">GPT-4o mini</kai-model>
+  <kai-model id="claude-3-7-sonnet" provider="Anthropic">Claude 3.7 Sonnet</kai-model>
+</kai-model-switcher>
+```
+
+---
+
+### `<kai-skill>`
+
+**Parent:** `<kai-skills>`
+
+| Attribute | Maps to | Notes |
+|-----------|---------|-------|
+| `id` | `Skill.id` | Falls back to text content when absent |
+| *(text content)* | `Skill.name` | The badge label |
+
+**No interaction event** — skills badges are display-only.
+
+```html
+<kai-skills>
+  <kai-skill id="web-search">Web Search</kai-skill>
+  <kai-skill id="code">Code</kai-skill>
+</kai-skills>
+```
+
+---
+
+## Side-by-side comparison
+
+The same set of suggestions rendered both ways — identical output, different authoring model.
+
+**Data path:**
+
+```html
+<kai-suggestions id="s1"></kai-suggestions>
+
+<script type="module">
+  import '@kitn.ai/ui/elements';
+  document.getElementById('s1').suggestions = [
+    { label: 'Explain quantum computing', value: 'explain-quantum' },
+    { label: 'Write a haiku', value: 'haiku' },
+    { label: 'Summarise in bullet points', value: 'summarise' },
+  ];
+</script>
+```
+
+**Composition path:**
+
+```html
+<kai-suggestions>
+  <kai-suggestion value="explain-quantum">Explain quantum computing</kai-suggestion>
+  <kai-suggestion value="haiku">Write a haiku</kai-suggestion>
+  <kai-suggestion value="summarise">Summarise in bullet points</kai-suggestion>
+</kai-suggestions>
+
+<script type="module">
+  import '@kitn.ai/ui/elements';
+</script>
+```
+
+Both fire `kai-select` with the same `value` string. The only difference is where the data lives — in application state or in the HTML.
+
+---
+
+## Customisation
+
+Child elements are **attribute- and text-driven data carriers**. Their visual appearance is entirely controlled by the parent element's props and the kit's design tokens (`--kai-*`, `--color-*`). There is no CSS to pierce through Shadow DOM boundaries and no per-child styling surface — reach for the parent's documented attributes and tokens instead.
+
+See **[Theming](?path=/docs/theming-overview--docs)** for the full token reference.

package/src/stories/docs/ForAIAgents.mdx

@@ -0,0 +1,162 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+
+<Meta title="Docs/Using with AI" />
+
+# Using with AI
+
+`@kitn.ai/ui` 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.
+
+The philosophy is **human-led, AI-assisted**: humans own the architecture,
+the design decisions, and the final review. The files below exist so that AI
+tools do the wiring work correctly the first time instead of hallucinating
+prop names or attribute APIs.
+
+**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
+
+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.
+
+| File | Size | Audience | Contents |
+|---|---|---|---|
+| `llms.txt` | ~4 KB | Agents + humans | Dense orientation: install command, the property-vs-attribute rule, two-layer architecture, framework wiring (React / Vue / plain HTML), theming tokens. Fast to read — the right file to paste into a prompt. |
+| `llms-full.txt` | ~60 KB | Agents | Everything in `llms.txt` plus a generated props/events table for every element, a streaming recipe, and a step-by-step "build a chat app" runbook. |
+
+### Where to find them after `npm install`
+
+```
+node_modules/@kitn.ai/ui/llms.txt
+node_modules/@kitn.ai/ui/llms-full.txt
+```
+
+Both paths are listed in the package's `files` field and are therefore always
+present after install. They are also copied to `dist/llms/` inside the package
+(at `node_modules/@kitn.ai/ui/dist/llms/llms.txt`), and published at:
+
+- https://kitn.dev/llms.txt
+- https://kitn.dev/llms-full.txt
+
+## How to point an agent at them
+
+| Tool | What to do |
+|---|---|
+| **Claude Code** | Add `@node_modules/@kitn.ai/ui/llms.txt` to `CLAUDE.md`, or run `read node_modules/@kitn.ai/ui/llms-full.txt` inside the session |
+| **GitHub Copilot** | Add the path to `.github/copilot-instructions.md`; workspace indexing picks it up automatically |
+| **Cursor** | Reference the file in `.cursorrules` |
+| **Codex / ChatGPT** | Paste the URL `https://kitn.dev/llms.txt` into the prompt, or fetch it with a browsing tool |
+| **Any agent** | `npm install @kitn.ai/ui` → file is at `node_modules/@kitn.ai/ui/llms.txt` |
+
+For one-off sessions, pasting the content of `llms.txt` directly into the
+system prompt is enough. For a project where the agent will revisit these
+components repeatedly, point it at the installed file path so it always reads
+the version that matches the installed package.
+
+## What agents most need to know
+
+These are the facts that AI tools most commonly get wrong when working with
+`kai-*` elements. They appear in both machine-readable files, but they are
+worth knowing up front.
+
+### 1 — Array and object data goes on JS properties, not HTML attributes
+
+An HTML attribute is always a string. Passing `messages`, `models`, `context`,
+`suggestions`, or `slashCommands` as an attribute silently fails.
+
+```js
+const chat = document.querySelector('kai-chat');
+chat.messages = [{ id: '1', role: 'assistant', content: 'Hi!' }]; // ✅ property
+```
+
+```html
+<kai-chat messages="[...]"></kai-chat>  <!-- ❌ never works -->
+```
+
+Only scalar props (string / number / boolean) work as attributes — for example
+`placeholder`, `loading`, and `theme`.
+
+### 2 — Events are kebab-case `kai-*` CustomEvents, and they do not bubble
+
+Listen directly on the element, not on a parent:
+
+```js
+chat.addEventListener('kai-submit', (e) => console.log(e.detail.value));
+```
+
+Common events: `kai-submit`, `kai-feedback`, `kai-model-change`, `kai-new-chat`, `kai-select`.
+
+### 3 — Streaming requires a new array + new object on every chunk
+
+Mutating an existing message object in place does **not** trigger a re-render.
+Replace, don't mutate:
+
+```js
+// ✅ re-renders on every chunk
+chat.messages = chat.messages.map(
+  (m) => (m.id === aid ? { ...m, content: answer } : m)
+);
+
+// ❌ does NOT re-render
+chat.messages[i].content = next;
+```
+
+The same rule applies to every array/object property: always assign a new
+reference.
+
+## Build a chat app (the runbook agents follow)
+
+```js
+import '@kitn.ai/ui/elements';
+const chat = document.querySelector('kai-chat');
+chat.messages = [];
+
+chat.addEventListener('kai-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;
+});
+```
+
+## Agent Skills (progressive loading) — planned
+
+Web Awesome and similar design systems are moving toward a **skills directory**:
+a structured set of per-component markdown files that AI tools load
+progressively, fetching only the documentation relevant to the current task.
+
+`@kitn.ai/ui` already provides `dist/llms/llms-full.txt` as a single,
+comprehensive reference (60 KB, all 42 elements). A per-element skills
+directory would let agents pull just the `kai-chat` spec when they only need
+that one element, rather than loading the full file.
+
+This is tracked as a follow-up improvement. If you want it sooner, the starting
+point is `scripts/gen-llms.mjs` — it already reads `dist/custom-elements.json`
+and has all the data needed to emit `dist/skills/kai-chat.md`,
+`dist/skills/kai-message.md`, etc.
+
+## Links
+
+- <a href="/llms.txt" target="_blank" rel="noreferrer"><code>llms.txt</code></a> — orientation (~4 KB; also 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 (~60 KB; also at `https://kitn.dev/llms-full.txt`)
+- Custom Elements Manifest — `dist/custom-elements.json` (published at `https://unpkg.com/@kitn.ai/ui/dist/custom-elements.json`)
+- Repository — https://github.com/kitn-ai/ui

package/src/stories/docs/GettingStarted.mdx

@@ -0,0 +1,65 @@
+import { Meta, Canvas } from '@storybook/addon-docs/blocks';
+import * as FullChat from '../full-chat.stories';
+
+<Meta title="Docs/Getting Started" />
+
+# Getting Started
+
+`<kai-chat>` is **transport-agnostic**: give it a `messages` array, it renders the conversation and
+emits a `submit` event when the user sends. You own the request and the streaming; the component
+owns the UI.
+
+## Your first chat in ~10 lines
+
+Set rich data as JS **properties** and listen for **events**. This is the universal pattern — every
+framework just wraps it in its own binding syntax.
+
+```html
+<kai-chat id="chat" style="display:block; height:100dvh;"></kai-chat>
+
+<script type="module">
+  import '@kitn.ai/ui/elements';
+
+  const chat = document.getElementById('chat');
+  chat.messages = [
+    { id: '1', role: 'assistant', content: 'Hello! How can I help?' },
+  ];
+
+  chat.addEventListener('kai-submit', (e) => {
+    const text = e.detail.value;
+    chat.messages = [
+      ...chat.messages,
+      { id: crypto.randomUUID(), role: 'user', content: text },
+    ];
+    // …call your model, then append an assistant message
+  });
+</script>
+```
+
+> Reactivity tip: assign a **new array** (and a new object for any message you change) when updating
+> `chat.messages` — that's what triggers a re-render.
+
+## Now pick your stack
+
+That's the raw element. For install, setup, and idiomatic examples in your framework — plus the
+**two ways** to use the kit (the all-in-one `<kai-chat>` and composing the individual elements):
+
+[HTML](?path=/docs/docs-frameworks-html--docs) ·
+[React](?path=/docs/docs-frameworks-react--docs) ·
+[Solid](?path=/docs/docs-frameworks-solid--docs) ·
+[Vue](?path=/docs/docs-frameworks-vue--docs) ·
+[Svelte](?path=/docs/docs-frameworks-svelte--docs) ·
+[Angular](?path=/docs/docs-frameworks-angular--docs)
+
+## A complete example
+
+Everything assembled into a real app — a conversation sidebar, a message thread with markdown,
+reasoning blocks and a tool call, a model switcher, context-usage meter, and a rich prompt input
+with attachments:
+
+<Canvas of={FullChat.Default} />
+
+Open it full-screen under **Examples → Full Chat App**, then explore each building block on its own
+page under **Components**.
+
+Ready to make it yours? See **[Theming](?path=/docs/theming-overview--docs)**.

package/src/stories/docs/Installation.mdx

@@ -0,0 +1,83 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+
+<Meta title="Docs/Installation" />
+
+# Installation
+
+```bash
+npm install @kitn.ai/ui
+```
+
+The package ships two entry points — pick whichever fits your stack, and you can mix them:
+
+- **`@kitn.ai/ui/elements`** — the framework-agnostic **web components** (`<kai-chat>`, …). Works
+  in React, Vue, Angular, Svelte, or plain HTML. **This is what most apps use.**
+- **`@kitn.ai/ui`** — the native **SolidJS** components, if you're building in SolidJS.
+
+## Web components (React, Vue, Angular, Svelte, HTML)
+
+Import the element bundle once as a **side effect** — that registers `<kai-chat>` and every other
+`<kai-*>` element globally:
+
+```js
+import '@kitn.ai/ui/elements';
+```
+
+- The bundle is **ESM-only** and loads via `<script type="module">` or any modern bundler.
+- **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, only to override design tokens.
+
+Then head to your framework's page for setup + examples:
+[HTML](?path=/docs/docs-frameworks-html--docs) ·
+[React](?path=/docs/docs-frameworks-react--docs) ·
+[Vue](?path=/docs/docs-frameworks-vue--docs) ·
+[Svelte](?path=/docs/docs-frameworks-svelte--docs) ·
+[Angular](?path=/docs/docs-frameworks-angular--docs).
+
+### Via CDN (no build step, no npm)
+
+The element bundle is a self-contained ES module, so you can load it straight from a CDN — no
+install, no bundler. It's published on both <a href="https://www.jsdelivr.com/package/npm/@kitn.ai/ui" target="_blank" rel="noreferrer">jsDelivr</a> and <a href="https://unpkg.com/browse/@kitn.ai/ui/" target="_blank" rel="noreferrer">unpkg</a>:
+
+```html
+<script type="module">
+  import 'https://cdn.jsdelivr.net/npm/@kitn.ai/ui/dist/kitn-chat.es.js';
+</script>
+
+<kai-chat></kai-chat>
+```
+
+- The URL above tracks the **latest** release (no version) — great for demos and quick starts.
+- **For production, pin an exact version** — e.g. `.../npm/@kitn.ai/ui@0.4.0/dist/kitn-chat.es.js`.
+  Pinned URLs are immutable and cached aggressively, and — since this package is **pre-1.0** —
+  pinning shields you from breaking changes in a future minor. A range (`@0` / `@0.4`) won't: pre-1.0
+  it can still resolve to a breaking minor.
+- SolidJS and the kit's CSS are bundled in, and the lazy syntax-highlighting chunks load from the
+  **same CDN** automatically. To override design tokens, also pull in `theme.css`:
+
+```html
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@kitn.ai/ui/theme.css">
+```
+
+## SolidJS projects
+
+The kit is authored in SolidJS, so SolidJS apps can import the components natively for full
+compositional control. `solid-js` is a peer dependency:
+
+```bash
+npm install solid-js
+```
+
+```tsx
+import { ChatContainer, Message, MessageContent, PromptInput } from '@kitn.ai/ui';
+import '@kitn.ai/ui/theme.css';
+```
+
+The `@kitn.ai/ui` entry ships as source, so your bundler tree-shakes it to exactly what you
+import. See the [Solid](?path=/docs/docs-frameworks-solid--docs) page and the **Solid (Advanced)**
+section for the full component + primitive reference.
+
+---
+
+Ready? Head to **[Getting Started](?path=/docs/docs-getting-started--docs)** to render your first chat.

package/src/stories/docs/Introduction.mdx

@@ -0,0 +1,50 @@
+import { Meta, Canvas } from '@storybook/addon-docs/blocks';
+import * as ChatPanel from '../chat-panel-layout.stories';
+
+<Meta title="Docs/Introduction" />
+
+# @kitn.ai/ui
+
+**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.
+
+<Canvas of={ChatPanel.ChatGPTStyle} />
+
+## Why @kitn.ai/ui
+
+- **Works in any framework** — drop in the framework-agnostic **web components** (`<kai-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 `<kai-chat>` is **~110 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 → 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:**
+
+- **Components** — the framework-agnostic `<kai-*>` 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.
+- **Solid (Advanced)** — under it, **Elements** (the native SolidJS 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 `<kai-chat>` web component is a thin facade over the SolidJS `ChatContainer`/`Message`/… components — same UI, different consumption model. When in doubt, reach for **Components**.
+
+## Components, Patterns & Recipes
+
+Three sidebar groups answer different questions:
+
+- **Components** — one reusable building block with one job and a documented prop/event API (`kai-message`, `kai-prompt-input`). Answers _"what is this control and how do I configure it?"_
+- **Patterns** — a prescriptive, framework-agnostic solution to a recurring chat-UX problem. Answers _"how do I solve this scenario?"_ A Pattern **stands alone if you delete every code block** — the guidance is the value, not the snippet.
+- **Recipes / Examples** — concrete, copy-paste assemblies tied to specific components, frameworks, or services. **Worthless without their code** — that's what makes them Recipes, not Patterns.
+
+> **The delete-the-code test:** remove every code block. If the page is gutted, it's a Recipe. If the guidance stands alone, it's a Pattern.
+
+Browse **Patterns** for recurring chat-UX solutions (streaming, empty state, message actions) and **Examples** for full assembled apps and task-specific snippets. The **[Choosing Components](?path=/docs/docs-choosing-components--docs)** guide explains which tier of building block to reach for first.
+
+## Where to next
+
+- **[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/theming-overview--docs)** — make it match your brand
+- **[Frameworks & Integrations](?path=/docs/docs-frameworks-overview--docs)** — wire up React, Vue, Svelte, Angular, or plain HTML; stream responses from OpenRouter and add text-to-speech
+
+Or browse every component in isolation from the sidebar.

package/src/stories/docs/SolidJsAdvanced.mdx

@@ -0,0 +1,17 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+
+<Meta title="Solid (Advanced)/Overview" />
+
+# Solid (Advanced)
+
+**Most people want the [Components](?path=/docs/components-chat--docs).** This tier is
+only for building a **custom chat UI in SolidJS** — the kit is authored in SolidJS, and these
+are the same building blocks the web components compose from.
+
+- **Elements** — the composed SolidJS pieces (message, tool, reasoning, …). Each maps to a
+  `kai-*` element; reach for these only if you're assembling your own layout in Solid.
+- **Primitives** — the low-level base components (button, tooltip, dropdown, …) the components
+  are built on. You rarely use these directly.
+
+Using a web component instead? Every element's **API** tab has copy-paste examples for
+HTML, React, Svelte, Vue, Angular, and Solid.