@kitn.ai/ui 0.14.1

package/src/stories/docs/Theming.mdx

@@ -0,0 +1,85 @@
+import { Meta, Canvas } from '@storybook/addon-docs/blocks';
+import * as TokenRef from '../token-reference.stories';
+
+<Meta title="Theming/Overview" />
+
+# Theming
+
+The kit's appearance is driven entirely by **CSS custom properties** (`--color-*` design tokens) defined in `theme.css`. Override them to rebrand everything — buttons, bubbles, borders, the sidebar, code blocks — without touching component code.
+
+## Overriding tokens
+
+Because inherited CSS pierces the Shadow DOM boundary, setting tokens on `:root` re-themes both the SolidJS components and the web components:
+
+```css
+:root {
+  --color-background: #0f0f0f;
+  --color-foreground: #f5f5f5;
+  --color-primary: #7c3aed;
+  --color-primary-foreground: #ffffff;
+  --color-muted: #1e1e1e;
+  --color-border: #2a2a2a;
+}
+```
+
+Scope the same variables to a parent element instead of `:root` to theme just one subtree. The tokens follow the **shadcn/ui convention**: they're *semantic* (`--color-primary`, not `--color-blue`) and come in **`X` / `X-foreground` pairs** — a surface color and the text color that sits on it.
+
+## Live editor
+
+Edit every token for **light and dark** modes and watch a real chat UI re-skin live — pick a preset, tweak swatches, then **Copy CSS** for a paste-ready `:root` + `.dark` block.
+
+<a
+  href="?path=/story/theming-editor--editor"
+  style={{
+    display: 'inline-block',
+    background: 'var(--color-primary, #18181b)',
+    borderRadius: 'var(--radius-md, 0.5rem)',
+    padding: '0.4rem 0.85rem',
+    textDecoration: 'none',
+  }}
+>
+  <span style={{
+    color: 'var(--color-primary-foreground, #fafafa)',
+    fontWeight: 600,
+    fontSize: '0.8125rem',
+    lineHeight: 1.3,
+  }}>Open the theme editor</span>
+</a>
+
+_(Opens full-screen — it needs more room than this docs column.)_
+
+## Token reference
+
+A complete, auto-generated reference of every token you can override — generated live from the loaded CSS, so it never drifts from `theme.css`:
+
+<Canvas of={TokenRef.TokenReference} />
+
+## Dark mode
+
+The kit ships light and dark token sets. Toggle dark mode by adding the `dark` class to a root element (this Storybook's toolbar does exactly that):
+
+```js
+document.documentElement.classList.toggle('dark');
+```
+
+## Appearance settings
+
+`ChatConfig` (SolidJS) and matching properties on `<kai-chat>` control non-color appearance:
+
+| Setting | Values | Purpose |
+| --- | --- | --- |
+| `proseSize` | `xs` · `sm` · `base` · `lg` | Text/markdown sizing |
+| `codeTheme` | any Shiki theme name | Syntax-highlight theme for code blocks |
+| `codeHighlight` | `true` / `false` | Turn code highlighting off entirely (renders plain text, loads no Shiki) |
+
+```tsx
+<ChatConfig proseSize="base" codeTheme="github-dark-dimmed">
+  {/* ... */}
+</ChatConfig>
+```
+
+```html
+<kai-chat prose-size="base" code-theme="github-dark-dimmed"></kai-chat>
+```
+
+That's the whole theming surface — tokens for color, `ChatConfig` for sizing and code. Everything else is encapsulated.

package/src/stories/docs/element-controls.ts

@@ -0,0 +1,121 @@
+import meta from '../../elements/element-meta.json';
+
+type Prop = { name: string; type: string; default?: string; scalar: boolean };
+type ElementMeta = { tag: string; props: Prop[] };
+const all = meta as unknown as ElementMeta[];
+
+// A small, consistent pointer at the top of every Web Component's Docs tab,
+// directing readers to the dedicated API tab (which holds the full generated
+// spec). Keeps the Docs tab focused on examples while keeping the spec one click
+// away — and discoverable, since everyone reads the description first.
+const API_POINTER =
+  '> **Full API reference** — every property, event, default and token is on the **API** tab above.';
+
+/**
+ * Build a Storybook `docs.description` from an element's intro paragraphs, with
+ * the API-tab pointer prepended. The generated spec itself lives in the **API**
+ * tab (see `.storybook/api-tab.tsx`), not inline here.
+ * (`tag` is kept in the signature so callers don't churn if we re-inline later.)
+ */
+export function specDescription(_tag: string, paragraphs: string[]): { component: string } {
+  return { component: [API_POINTER, ...paragraphs].join('\n\n') };
+}
+
+// The Components/UI sibling of API_POINTER — same idea, component vocabulary
+// (props/callbacks/slots rather than properties/events/attributes).
+const COMPONENT_POINTER =
+  '> **Full API reference** — every prop, callback, slot and token is on the **API** tab above.';
+
+/**
+ * Build a Storybook `docs.description` for a SolidJS/UI component story, with the
+ * API-tab pointer prepended. The generated spec (props/callbacks/slots/tokens)
+ * lives on the **API** tab (see `.storybook/api-tab.tsx`), from
+ * `src/components/component-meta.json`.
+ */
+export function componentDescription(paragraphs: string[]): { component: string } {
+  return { component: [COMPONENT_POINTER, ...paragraphs].join('\n\n') };
+}
+
+/**
+ * Parse a type string from element-meta.json into meaningful parts.
+ *
+ * The meta generator writes types like:
+ *   - `"undefined | false | true"` for booleans (NOT "boolean")
+ *   - `"undefined | \"preview\" | \"code\""` for enums (double-quoted, with leading undefined)
+ *
+ * We normalise by splitting on `|`, trimming, and dropping `undefined` / `null`.
+ */
+const normaliseParts = (type: string): string[] =>
+  type
+    .split('|')
+    .map((s) => s.trim())
+    .filter((s) => s !== 'undefined' && s !== 'null');
+
+const enumValues = (parts: string[]): string[] | null => {
+  // Accept both single-quoted ('foo') and double-quoted ("foo") string literals.
+  if (parts.length > 0 && parts.every((p) => /^(['"])[^'"]*\1$/.test(p)))
+    return parts.map((p) => p.slice(1, -1));
+  return null;
+};
+
+const isBooleanParts = (parts: string[], rawType: string): boolean => {
+  // Explicit boolean keyword (future-proof)
+  if (/\bboolean\b/.test(rawType)) return true;
+  // element-meta encodes booleans as "undefined | false | true"
+  const sorted = [...parts].sort().join(',');
+  return sorted === 'false,true';
+};
+
+/**
+ * Storybook argTypes for an element's props (theme select, booleans, text,
+ * number, object/JSON for complex types, and no control for functions).
+ *
+ * Classification order:
+ *  1. enum  → select
+ *  2. boolean → boolean
+ *  3. number  → number
+ *  4. contains `=>` (function / function-bearing object) → control: false
+ *  5. not all-string after normalisation (arrays, records, generics…) → object
+ *  6. all-string → text
+ */
+export function argTypesFor(tag: string): Record<string, unknown> {
+  const el = all.find((e) => e.tag === tag);
+  if (!el) return {};
+  const out: Record<string, unknown> = {};
+  for (const p of el.props) {
+    const parts = normaliseParts(p.type);
+
+    // 1–3: scalar classifications (enums, booleans, numbers only appear in scalar props)
+    if (p.scalar) {
+      const values = enumValues(parts);
+      if (values) {
+        out[p.name] = { control: { type: 'select' }, options: values };
+        continue;
+      }
+      if (isBooleanParts(parts, p.type)) {
+        out[p.name] = { control: 'boolean' };
+        continue;
+      }
+      if (/\bnumber\b/.test(p.type)) {
+        out[p.name] = { control: 'number' };
+        continue;
+      }
+    }
+
+    // 4. Function / function-bearing object: contains `=>` in raw type string
+    if (p.type.includes('=>')) {
+      out[p.name] = { control: false };
+      continue;
+    }
+
+    // 5. Complex/object: parts are not all exactly the string "string"
+    if (!parts.every((part) => part === 'string')) {
+      out[p.name] = { control: 'object' };
+      continue;
+    }
+
+    // 6. Pure string
+    out[p.name] = { control: 'text' };
+  }
+  return out;
+}

package/src/stories/docs/frameworks/Angular.mdx

@@ -0,0 +1,245 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+
+<Meta title="Docs/Frameworks/Angular" />
+
+# 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)"`.
+
+There are **two ways to build with the kit**, and you can mix them:
+
+1. **`<kai-chat>`** — the batteries-included shell: a whole chat experience in one tag. Fastest start.
+2. **Compose the individual elements** (`<kai-conversations>`, `<kai-markdown>`, `<kai-artifact>`, …)
+   into your own layout when you want full control.
+
+Both are shown below.
+
+## Install & setup
+
+```bash
+npm i @kitn.ai/ui
+```
+
+Register the custom elements once as a static side-effect import in `main.ts`, **before**
+`bootstrapApplication(...)`. Then add `CUSTOM_ELEMENTS_SCHEMA` to each standalone component that
+uses `<kai-*>` tags:
+
+```ts
+// main.ts — import BEFORE bootstrapApplication so elements are defined first
+import '@kitn.ai/ui/elements';
+import { bootstrapApplication } from '@angular/platform-browser';
+import { AppComponent } from './app/app.component';
+import { appConfig } from './app/app.config';
+
+bootstrapApplication(AppComponent, appConfig);
+```
+
+```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], // required: allows <kai-*> tags in the template
+})
+export class AppComponent { /* … */ }
+```
+
+- **`@kitn.ai/ui/elements`** — the side-effect import that registers every `<kai-*>` element
+  globally. Import it once, in `main.ts`.
+- **`CUSTOM_ELEMENTS_SCHEMA`** — tells the Angular compiler to accept unknown element names (the
+  `<kai-*>` tags). Add it to every standalone component whose template uses them.
+- No CSS to import: each element is styled inside its own Shadow DOM. Only pull in
+  `@kitn.ai/ui/theme.css` if you want to override design tokens (see **Theming**).
+
+## Quick start — the all-in-one shell
+
+`<kai-chat>` is **transport-agnostic**: give it a `messages` array, handle the `submit` event, and
+stream your model's reply back into state. You own the request; the component owns the UI.
+
+```ts
+// app.component.ts
+import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
+
+type Message = { id: string; role: 'user' | 'assistant'; content: string };
+
+@Component({
+  selector: 'app-root',
+  standalone: true,
+  templateUrl: './app.component.html',
+  schemas: [CUSTOM_ELEMENTS_SCHEMA],
+})
+export class AppComponent {
+  messages: Message[] = [
+    { id: '1', role: 'assistant', content: 'Hello! How can I help?' },
+  ];
+
+  async onSubmit(e: Event) {
+    const { value } = (e as CustomEvent<{ value: string }>).detail;
+    // Reassign a NEW array so Angular's change detection picks it up.
+    const history = [...this.messages, { id: crypto.randomUUID(), role: 'user' as const, content: value }];
+    this.messages = history;
+
+    const aid = crypto.randomUUID();
+    this.messages = [...history, { id: aid, role: 'assistant' as const, content: '' }];
+
+    let answer = '';
+    for await (const token of streamFromYourAPI(history)) {
+      answer += token;
+      // Reassign a new array — and a new object for the message being streamed.
+      this.messages = this.messages.map((m) =>
+        m.id === aid ? { ...m, content: answer } : m
+      );
+    }
+  }
+}
+```
+
+```html
+<!-- app.component.html -->
+<!-- The elements are display:block and fill their container — lay them out with flex
+     and let the element grow with flex:1 rather than hard-coding a height. -->
+<div style="display: flex; flex-direction: column; height: 100dvh">
+  <kai-chat
+    [messages]="messages"
+    (kai-submit)="onSubmit($event)"
+    style="flex: 1; min-height: 0"
+  ></kai-chat>
+</div>
+```
+
+## Go further — compose the pieces
+
+`<kai-chat>` is one option, not the only one. You can assemble your own layout from individual
+elements. Here is a multi-conversation shell — a `<kai-conversations>` sidebar next to the
+`<kai-chat>` thread:
+
+```ts
+// workspace.component.ts
+import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
+
+@Component({
+  selector: 'app-workspace',
+  standalone: true,
+  templateUrl: './workspace.component.html',
+  schemas: [CUSTOM_ELEMENTS_SCHEMA],
+})
+export class WorkspaceComponent {
+  conversations = myConversations;
+  activeId = this.conversations[0]?.id;
+  messages = loadMessages(this.activeId);
+
+  onConversationSelect(e: Event) {
+    this.activeId = (e as CustomEvent<{ id: string }>).detail.id;
+    this.messages = loadMessages(this.activeId);
+  }
+
+  onNewChat() {
+    startNewConversation();
+  }
+
+  onSubmit(e: Event) {
+    const { value } = (e as CustomEvent<{ value: string }>).detail;
+    sendMessage(value);
+  }
+}
+```
+
+```html
+<!-- workspace.component.html -->
+<!-- Lay panels out with flex: the sidebar is fixed-width, the thread takes the rest
+     with flex:1. The elements fill whatever box you give them. -->
+<div style="display: flex; height: 100dvh">
+  <kai-conversations
+    [conversations]="conversations"
+    [activeId]="activeId"
+    (kai-conversation-select)="onConversationSelect($event)"
+    (kai-new-chat)="onNewChat()"
+    style="width: 300px; flex-shrink: 0"
+  ></kai-conversations>
+
+  <kai-chat
+    [messages]="messages"
+    (kai-submit)="onSubmit($event)"
+    style="flex: 1; min-width: 0"
+  ></kai-chat>
+</div>
+```
+
+### Make the panels resizable
+
+Want a draggable divider between the sidebar and the thread? Wrap the panels in `<kai-resizable>`
+with one `<kai-resizable-item>` each — the handles are inserted for you (up to 3 panels). Each item
+takes a `size` (px or `%`) plus optional `min`/`max`; listen for `(change)` (`$event.detail.sizes`)
+to persist the layout.
+
+```html
+<div style="display: flex; flex-direction: column; height: 100dvh">
+  <kai-resizable
+    orientation="horizontal"
+    (kai-change)="onResize($event)"
+    style="flex: 1; min-height: 0"
+  >
+    <kai-resizable-item size="25%" min="200px">
+      <kai-conversations
+        [conversations]="conversations"
+        [activeId]="activeId"
+        (kai-conversation-select)="onConversationSelect($event)"
+      ></kai-conversations>
+    </kai-resizable-item>
+    <kai-resizable-item>
+      <kai-chat [messages]="messages" (kai-submit)="onSubmit($event)"></kai-chat>
+    </kai-resizable-item>
+  </kai-resizable>
+</div>
+```
+
+```ts
+onResize(e: Event) {
+  const { sizes } = (e as CustomEvent<{ sizes: string[] }>).detail;
+  // persist sizes to localStorage, a service, etc.
+  console.log('panel sizes:', sizes);
+}
+```
+
+You can also drop **standalone display elements** anywhere in your own UI — `<kai-markdown>`,
+`<kai-code-block>`, `<kai-artifact>`, `<kai-reasoning>`, `<kai-tool>` — to render rich AI content
+without adopting the whole chat. Each fills its container and is controlled via `[prop]` bindings
+and `(event)` listeners.
+
+> **See it all assembled:** **[Examples → Full Chat App](?path=/story/examples-full-chat-app--default)**
+> wires a sidebar, threaded markdown, reasoning, a tool call, a model switcher, a context meter, and
+> a rich prompt input into one screen — a working reference to crib from.
+
+> **Find every element:** browse the **Components** section in the sidebar. Each element's **API**
+> tab lists its props, events, and copy-paste usage for Angular (and every other framework).
+
+## Props & events
+
+The rule for all elements: **rich data goes in as properties, interactions come out as events.**
+Angular's `[prop]="…"` binding writes to the element's DOM property (not an HTML attribute), so
+arrays and objects pass through unstringified — no adapter or wrapper needed.
+
+`(event)="handler($event)"` listens for a DOM CustomEvent. `$event` is the `CustomEvent` itself;
+read the payload from `$event.detail`:
+
+| Element | Property binding | Event | `$event.detail` |
+|---|---|---|---|
+| `kai-chat` | `[messages]="messages"` | `(submit)` | `{ value: string }` |
+| `kai-conversations` | `[conversations]="…"` | `(conversationselect)` | `{ id: string }` |
+| `kai-conversations` | `[groups]="…"` | `(newchat)` | — |
+| `kai-conversations` | — | `(togglesidebar)` | — |
+| `kai-resizable` | `orientation="horizontal"` | `(change)` | `{ sizes: string[] }` |
+| `kai-resizable-item` | `size="25%"` `min="200px"` `max="…"` | — | — |
+
+> **Scalar attributes** like `orientation="horizontal"` or `theme="dark"` can be plain HTML
+> attributes (no brackets). Use `[prop]="…"` only when passing non-string values (arrays, objects,
+> booleans) or Angular expressions.
+
+> **`CUSTOM_ELEMENTS_SCHEMA` is required** in every standalone component (or NgModule) whose
+> template contains `<kai-*>` tags. Without it, the Angular compiler rejects unknown element names at
+> build time.

package/src/stories/docs/frameworks/Html.mdx

@@ -0,0 +1,227 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+
+<Meta title="Docs/Frameworks/HTML" />
+
+# HTML
+
+The kit ships as standard **custom elements** (`kai-*` tags) — no framework required. Import the
+bundle once as a side-effect and every element is registered globally, ready to drop into any HTML
+page or templating system.
+
+There are **two ways to build with the kit**, and you can mix them:
+
+1. **`<kai-chat>`** — the batteries-included shell: a whole chat experience in one tag. Fastest start.
+2. **Compose the individual elements** (`<kai-conversations>`, `<kai-markdown>`, `<kai-artifact>`, …)
+   into your own layout when you want full control.
+
+Both are shown below.
+
+## Install & setup
+
+```bash
+npm i @kitn.ai/ui
+```
+
+Register the custom elements once (a side-effect import), then use the tags anywhere in your HTML:
+
+```js
+// Once, near your app entry — registers all <kai-*> elements globally.
+import '@kitn.ai/ui/elements';
+```
+
+- No CSS to import: each element is styled inside its own Shadow DOM. Only pull in
+  `@kitn.ai/ui/theme.css` if you want to override design tokens (see **Theming**).
+
+### No-build / CDN option
+
+No bundler? Load the module directly from a CDN and you're done:
+
+```html
+<script type="module">
+  import 'https://cdn.jsdelivr.net/npm/@kitn.ai/ui/dist/kitn-chat.es.js';
+</script>
+```
+
+Every `<kai-*>` element is then available as a global custom element — no install, no build step.
+
+## Quick start — the all-in-one shell
+
+`<kai-chat>` is **transport-agnostic**: give it a `messages` array, handle the `submit` event, and
+stream your model's reply back into the property. You own the request; the element owns the UI.
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <!-- optional: only needed to override design tokens -->
+  <link rel="stylesheet" href="./node_modules/@kitn.ai/ui/theme.css" />
+  <style>
+    html, body { margin: 0; height: 100%; }
+    .app { display: flex; flex-direction: column; height: 100dvh; }
+  </style>
+</head>
+<body>
+  <!-- Put the element in a flex parent and give it flex: 1.
+       The elements are display:block and fill their box. -->
+  <div class="app">
+    <kai-chat id="chat" style="flex: 1; min-height: 0;"></kai-chat>
+  </div>
+
+  <script type="module">
+    import '@kitn.ai/ui/elements';
+
+    const chat = document.getElementById('chat');
+
+    // Arrays and objects → JS properties (never attributes)
+    chat.messages = [
+      { id: '1', role: 'assistant', content: 'Hello! How can I help?', actions: ['copy', 'like', 'dislike'] },
+    ];
+    chat.suggestions = ['Summarize the chat', 'Start fresh'];
+
+    // Interactions → addEventListener (CustomEvents, they don't bubble)
+    chat.addEventListener('kai-submit', async (e) => {
+      const text = e.detail.value;
+
+      // Append user message — always assign a NEW array to trigger a 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.
+
+## Go further — compose the pieces
+
+`<kai-chat>` is one option, not the only one. Every element can be placed independently, so you can
+assemble your own layout. Here's a multi-conversation shell — a `<kai-conversations>` sidebar next
+to the `<kai-chat>` thread:
+
+```html
+<style>
+  html, body { margin: 0; height: 100%; }
+  .workspace { display: flex; height: 100dvh; }
+</style>
+
+<div class="workspace">
+  <kai-conversations id="sidebar" style="width: 300px; flex-shrink: 0;"></kai-conversations>
+  <kai-chat id="chat" style="flex: 1; min-width: 0;"></kai-chat>
+</div>
+
+<script type="module">
+  import '@kitn.ai/ui/elements';
+
+  const sidebar = document.getElementById('sidebar');
+  const chat = document.getElementById('chat');
+
+  // Rich data → JS properties
+  sidebar.conversations = myConversations;
+  chat.messages = loadMessages(myConversations[0]?.id);
+
+  sidebar.addEventListener('kai-conversation-select', (e) => {
+    chat.messages = loadMessages(e.detail.id);
+  });
+
+  sidebar.addEventListener('kai-new-chat', () => startNewConversation());
+
+  chat.addEventListener('kai-submit', (e) => sendMessage(e.detail.value));
+</script>
+```
+
+### Make the panels resizable
+
+Want a draggable divider between the sidebar and the thread? Wrap the panels in `<kai-resizable>`
+with one `<kai-resizable-item>` each — the handles are inserted for you (up to 3 panels). Each item
+takes a `size` (px or `%`) plus optional `min`/`max`; listen for `change` (`detail.sizes`) to
+persist the layout.
+
+```html
+<style>
+  html, body { margin: 0; height: 100%; }
+  .app { display: flex; flex-direction: column; height: 100dvh; }
+</style>
+
+<div class="app">
+  <kai-resizable orientation="horizontal" style="flex: 1; min-height: 0;">
+    <kai-resizable-item size="25%" min="200px">
+      <kai-conversations id="sidebar"></kai-conversations>
+    </kai-resizable-item>
+    <kai-resizable-item>
+      <kai-chat id="chat"></kai-chat>
+    </kai-resizable-item>
+  </kai-resizable>
+</div>
+
+<script type="module">
+  import '@kitn.ai/ui/elements';
+
+  const resizable = document.querySelector('kai-resizable');
+  resizable.addEventListener('kai-change', (e) => {
+    console.log('panel sizes:', e.detail.sizes);
+    // persist to localStorage, etc.
+  });
+</script>
+```
+
+You can also drop **standalone display elements** anywhere in your own page — `<kai-markdown>`,
+`<kai-code-block>`, `<kai-artifact>` — to render rich AI content without adopting the whole chat.
+Each element fills its container and is controlled via properties and events.
+
+> **See it all assembled:** **[Examples → Full Chat App](?path=/story/examples-full-chat-app--default)**
+> wires a sidebar, threaded markdown, a model switcher, a context meter, and a rich prompt input
+> into one screen — a working reference to crib from.
+
+> **Find every element:** browse the **Components** section in the sidebar. Each element's **API**
+> tab lists its props, events, and copy-paste usage for HTML (and every other framework).
+
+## Props & events
+
+The rule for all elements: **rich data goes in as JS properties, interactions come out as events.**
+
+```js
+// ✅ Arrays and objects — always set as a JS property
+el.messages = [{ id: '1', role: 'assistant', content: 'Hi' }];
+el.conversations = myConversations;
+
+// ✅ Events — addEventListener on the element (CustomEvents, they don't bubble)
+el.addEventListener('kai-submit', (e) => console.log(e.detail.value));
+el.addEventListener('kai-conversation-select', (e) => console.log(e.detail.id));
+```
+
+**Scalar attributes** (strings, booleans, numbers) can go directly in HTML markup:
+
+```html
+<!-- theme, placeholder, and loading are scalars → safe as attributes -->
+<kai-chat
+  theme="dark"
+  placeholder="Ask anything…"
+></kai-chat>
+```
+
+Key events by element:
+
+| Element | Event | `detail` |
+|---|---|---|
+| `kai-chat` | `submit` | `{ value: string }` |
+| `kai-conversations` | `conversationselect` | `{ id: string }` |
+| `kai-conversations` | `newchat` | — |
+| `kai-conversations` | `togglesidebar` | — |
+| `kai-resizable` | `change` | `{ sizes: string[] }` |