@kitn.ai/ui 0.14.1

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

@@ -0,0 +1,47 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+
+<Meta title="Docs/Frameworks/Overview" />
+
+# Frameworks
+
+`@kitn.ai/ui` is **transport-agnostic**: every element renders a `messages` array and emits a
+`submit` event. You bring the model; the kit owns the UI. It works in any framework — pick yours:
+[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).
+Recipes for streaming, text-to-speech, and speech-to-text live under **Docs/Recipes**.
+
+## Two ways to build
+
+You can adopt the kit at whatever level you need — and mix the two freely:
+
+1. **`<kai-chat>` — the all-in-one shell.** One tag gives you a whole chat experience (message
+   thread, prompt input, model switcher, …). The fastest way to ship.
+2. **Compose the individual elements.** Assemble `<kai-conversations>`, `<kai-message>`,
+   `<kai-prompt-input>`, `<kai-markdown>`, `<kai-artifact>`, … into your own layout for full control —
+   or drop a single display element into an app you already have.
+
+`<kai-chat>` is the quick start, **not** the only way in. Every framework page shows both paths,
+and each element's **API** tab (under **Components**) lists its full props, events, and copy-paste
+usage for every framework.
+
+## The #1 rule: properties vs. attributes
+
+Arrays and objects **must** be set as JavaScript **properties** on the 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.
+
+```js
+const chat = document.querySelector('kai-chat');
+
+// ✅ correct — set as a JS property
+chat.messages = [{ id: '1', role: 'assistant', content: 'Hello!' }];
+
+// ❌ wrong — an HTML attribute is always a string, never works
+// <kai-chat messages="[...]"></kai-chat>
+```
+
+Scalar values (strings, numbers, booleans) work fine as attributes: `placeholder`, `loading`,
+`theme`, `prose-size`, and so on. Each framework's binding syntax (React props, Vue's `.prop`
+modifier, Angular's `[prop]`, Svelte's `{prop}`) handles this for you — see your framework's page.
+
+The kit ships **40+ elements**. SolidJS apps can also import the **native components** directly for
+full compositional control — see the [Solid](?path=/docs/docs-frameworks-solid--docs) page and the **Solid (Advanced)** section.

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

@@ -0,0 +1,227 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+
+<Meta title="Docs/Frameworks/React" />
+
+# React
+
+The kit ships auto-generated, **typed React wrappers** under `@kitn.ai/ui/react`. They hide the
+custom-element plumbing — rich data goes in as React props (set as DOM **properties**, never
+stringified) and CustomEvents come out as `on<Event>` handlers — so you write idiomatic JSX
+without touching refs.
+
+There are **two ways to build with the kit**, and you can mix them:
+
+1. **`<Chat>`** — the batteries-included shell: a whole chat experience in one tag. Fastest start.
+2. **Compose the individual elements** (`<Conversations>`, `<Markdown>`, `<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 typed wrappers anywhere:
+
+```tsx
+// Once, near your app entry — registers the <kai-*> elements globally.
+import '@kitn.ai/ui/elements';
+
+// Then import the wrappers you need (tree-shaken).
+import { Chat, Conversations, Markdown } from '@kitn.ai/ui/react';
+```
+
+- **`@kitn.ai/ui/react`** — the typed wrappers (recommended). Component names are the PascalCase
+  of the tag: `kai-chat → Chat`, `kai-prompt-input → PromptInput`.
+- **`@kitn.ai/ui/elements`** — the raw custom elements, if you'd rather wire refs yourself
+  (see [Without the wrappers](#without-the-wrappers-raw-custom-element)).
+- 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**).
+
+> One name collides with a browser global: `kai-image → Image`. Alias it if you import it:
+> `import { Image as KaiImage } from '@kitn.ai/ui/react'`.
+
+## Quick start — the all-in-one shell
+
+`<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.
+
+```tsx
+import '@kitn.ai/ui/elements';
+import { Chat } from '@kitn.ai/ui/react';
+import { useState } from 'react';
+
+type Message = { id: string; role: 'user' | 'assistant'; content: string };
+
+export function App() {
+  const [messages, setMessages] = useState<Message[]>([
+    { id: '1', role: 'assistant', content: 'Hello! How can I help?' },
+  ]);
+
+  const handleSubmit = async (e: CustomEvent<{ value: string }>) => {
+    const history = [...messages, { id: crypto.randomUUID(), role: 'user' as const, content: e.detail.value }];
+    setMessages(history);
+
+    const aid = crypto.randomUUID();
+    setMessages([...history, { id: aid, role: 'assistant', content: '' }]);
+
+    let answer = '';
+    for await (const token of streamFromYourAPI(history)) {
+      answer += token;
+      // Assign a NEW array (and a new object for the message you change) to trigger a re-render.
+      setMessages((prev) => prev.map((m) => (m.id === aid ? { ...m, content: answer } : m)));
+    }
+  };
+
+  // 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.
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', height: '100dvh' }}>
+      <Chat
+        messages={messages}
+        suggestions={['Summarize the chat', 'Start fresh']}
+        onSubmit={handleSubmit}
+        style={{ flex: 1, minHeight: 0 }}
+      />
+    </div>
+  );
+}
+```
+
+## Go further — compose the pieces
+
+`<Chat>` is one option, not the only one. Every element has its own wrapper, so you can assemble
+your own layout. Here's a multi-conversation shell — a `<Conversations>` sidebar next to the
+`<Chat>` thread:
+
+```tsx
+import '@kitn.ai/ui/elements';
+import { Chat, Conversations } from '@kitn.ai/ui/react';
+import { useState } from 'react';
+
+export function Workspace() {
+  const [conversations, setConversations] = useState(myConversations);
+  const [activeId, setActiveId] = useState(conversations[0]?.id);
+  const [messages, setMessages] = useState(loadMessages(activeId));
+
+  // 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.
+  return (
+    <div style={{ display: 'flex', height: '100dvh' }}>
+      <Conversations
+        conversations={conversations}
+        activeId={activeId}
+        onConversationSelect={(e) => {
+          setActiveId(e.detail.id);
+          setMessages(loadMessages(e.detail.id));
+        }}
+        onNewChat={() => startNewConversation()}
+        style={{ width: 300, flexShrink: 0 }}
+      />
+
+      <Chat
+        messages={messages}
+        onSubmit={(e) => sendMessage(e.detail.value)}
+        style={{ flex: 1, minWidth: 0 }}
+      />
+    </div>
+  );
+}
+```
+
+### Make the panels resizable
+
+Want a draggable divider between the sidebar and the thread? Wrap the panels in `<Resizable>`
+with one `<ResizableItem>` each — the handles are inserted for you (up to 3 panels). Each item
+takes a `size` (px or `%`) plus optional `min`/`max`; listen for `onChange` (`detail.sizes`) to
+persist the layout.
+
+```tsx
+import { Chat, Conversations, Resizable, ResizableItem } from '@kitn.ai/ui/react';
+
+<div style={{ display: 'flex', flexDirection: 'column', height: '100dvh' }}>
+  <Resizable orientation="horizontal" style={{ flex: 1, minHeight: 0 }}>
+    <ResizableItem size="25%" min="200px">
+      <Conversations conversations={conversations} activeId={activeId} onConversationSelect={handleSelect} />
+    </ResizableItem>
+    <ResizableItem>
+      <Chat messages={messages} onSubmit={handleSubmit} />
+    </ResizableItem>
+  </Resizable>
+</div>
+```
+
+You can also drop **standalone display elements** anywhere in your own UI — `<Markdown>`,
+`<CodeBlock>`, `<Artifact>`, `<Reasoning>`, `<Tool>` — to render rich AI content without adopting
+the whole chat. Each fills its container and is controlled via props and events.
+
+> **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 React (and every other framework).
+
+## Props & events
+
+The rule for all elements: **rich data goes in as properties, interactions come out as events.**
+The wrappers do this for you — pass arrays/objects as props and they're assigned as live DOM
+properties (not stringified), while CustomEvents surface as `on<Event>` handlers.
+
+Event props are `on` + the event name with the `kai-` prefix stripped and each
+hyphen-segment PascalCased:
+
+| DOM event | React prop |
+|---|---|
+| `kai-submit` | `onSubmit` |
+| `kai-value-change` | `onValueChange` |
+| `kai-message-action` | `onMessageAction` |
+| `kai-model-change` | `onModelChange` |
+| `kai-conversation-select` | `onConversationSelect` |
+| `kai-suggestion-click` | `onSuggestionClick` |
+
+All **40+ elements** have a typed wrapper:
+
+```tsx
+import {
+  Chat, Conversations, PromptInput, Message, Markdown, CodeBlock,
+  Reasoning, Tool, Context, ModelSwitcher, Attachments, Loader,
+  // …every kai-* element
+} from '@kitn.ai/ui/react';
+```
+
+## Without the wrappers (raw custom element)
+
+Prefer the raw element (e.g. with React 19's improved custom-element support)? Use a `ref` to set
+object props and wire events:
+
+```tsx
+import { useEffect, useRef, useState } from 'react';
+import '@kitn.ai/ui/elements';
+
+export function RawChat() {
+  const ref = useRef<HTMLElement>(null);
+  const [messages, setMessages] = useState([{ id: '1', role: 'assistant', content: 'Hello!' }]);
+
+  useEffect(() => {
+    const el = ref.current;
+    if (!el) return;
+    (el as any).messages = messages; // object/array props can't go through attributes
+  }, [messages]);
+
+  useEffect(() => {
+    const el = ref.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('kai-submit', onSubmit);
+    return () => el.removeEventListener('kai-submit', onSubmit);
+  }, []);
+
+  return <kai-chat ref={ref} style={{ display: 'block', height: '100vh' }} />;
+}
+```

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

@@ -0,0 +1,173 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+
+<Meta title="Docs/Frameworks/Solid" />
+
+# Solid
+
+The kit is **authored in SolidJS** — the `<kai-*>` web components are compiled from these very
+components. So Solid devs get the richest path of any framework, with **two ways to build** that
+you can freely mix:
+
+1. **Native SolidJS components** (`@kitn.ai/ui`) — `ChatContainer`, `Message`, `PromptInput`, and
+   the rest, composed in your own JSX. Full compositional control and the smallest output for a
+   Solid app. **This is the recommended Solid path.**
+2. The same framework-agnostic **`<kai-*>` web components** (`@kitn.ai/ui/elements`) — the
+   drop-in shells (`<kai-chat>`, …) when you just want batteries included.
+
+Both work in the same app; reach for whichever fits the surface you're building.
+
+## Install & setup
+
+```bash
+npm i @kitn.ai/ui
+```
+
+`solid-js` is a peer dependency — install it if you haven't already:
+
+```bash
+npm i solid-js
+```
+
+Import the design tokens **once**, near your app entry:
+
+```ts
+import '@kitn.ai/ui/theme.css';
+```
+
+The `@kitn.ai/ui` entry ships as **source** (TSX), so your bundler compiles and tree-shakes it
+alongside your own Solid code — you only pay for what you import.
+
+## Quick start — native components
+
+Compose the native components directly in your JSX. Drive the prompt input with a `createSignal`,
+and let the components fill their container — size them with flex / `class="h-full"` rather than a
+hard-coded `height: 100vh`.
+
+```tsx
+import {
+  ChatConfig, ChatContainer, ChatContainerContent,
+  Message, MessageContent,
+  PromptInput, PromptInputTextarea, PromptInputActions,
+} from '@kitn.ai/ui';
+import '@kitn.ai/ui/theme.css';
+import { createSignal } from 'solid-js';
+
+function Chat() {
+  const [input, setInput] = createSignal('');
+
+  // The components fill their box — give them a flex parent and let
+  // ChatContainer grow with `h-full`/flex rather than a fixed viewport height.
+  return (
+    <div class="flex flex-col h-full">
+      <ChatConfig proseSize="sm">
+        <ChatContainer class="h-full">
+          <ChatContainerContent class="space-y-4 p-4">
+            <Message>
+              <MessageContent markdown>{`Ask me anything.`}</MessageContent>
+            </Message>
+          </ChatContainerContent>
+        </ChatContainer>
+        <PromptInput value={input()} onValueChange={setInput} onSubmit={() => setInput('')}>
+          <PromptInputTextarea placeholder="Ask anything..." />
+          <PromptInputActions>{/* your buttons */}</PromptInputActions>
+        </PromptInput>
+      </ChatConfig>
+    </div>
+  );
+}
+```
+
+`<ChatContainer>` is **transport-agnostic**: it owns the conversation UI, you own the request.
+Render your message list inside `<ChatContainerContent>` (a `<For>` over your signal of messages),
+and append the user turn — then stream the assistant reply — in `onSubmit`.
+
+## Go further — compose & the web components
+
+### The native components *are* the granular composition
+
+There's no separate "advanced" component set — the pieces above (`ChatContainer`, `Message`,
+`PromptInput`) plus the feature components (`Markdown`, `CodeBlock`, `Reasoning`, `Tool`,
+`Conversations`, `ModelSwitcher`, …) **are** the building blocks. Assemble them into any layout you
+like: a sidebar next to a thread, a split view, a custom composer — it's all just Solid JSX.
+
+For a resizable layout, use the native `Resizable` convenience component with one `ResizablePanel`
+per pane (handles are auto-inserted between visible panels). Each panel takes `defaultSize`
+(px or `%`) plus optional `minSize`/`maxSize`; listen for `onChange` (an array of percent sizes) to
+persist the layout.
+
+```tsx
+import { Resizable, ResizablePanel } from '@kitn.ai/ui';
+
+function Workspace() {
+  return (
+    <div class="flex flex-col h-full">
+      <Resizable orientation="horizontal" withHandle onChange={(sizes) => persist(sizes)}>
+        <ResizablePanel defaultSize="25%" minSize="200px">
+          {/* your conversation sidebar */}
+        </ResizablePanel>
+        <ResizablePanel>
+          {/* the message thread + prompt input */}
+        </ResizablePanel>
+      </Resizable>
+    </div>
+  );
+}
+```
+
+> **Full reference:** the **[Solid (Advanced)](?path=/docs/solid-advanced-overview--docs)** sidebar
+> tier documents every native building block — the composed **Elements** (message, tool, reasoning,
+> …) and the low-level **Primitives** (button, tooltip, dropdown, …) they're built on.
+
+### Prefer the drop-in shell? Use the web component
+
+When you just want a whole chat in one tag, register the `<kai-*>` elements and use `<kai-chat>`.
+Solid sets rich data as DOM **properties** on custom elements (so arrays/objects pass through
+without stringifying), and you listen for CustomEvents with Solid's `on:` namespace:
+
+```tsx
+import '@kitn.ai/ui/elements'; // registers the <kai-*> elements once
+import { createSignal } from 'solid-js';
+
+function Shell() {
+  const [messages, setMessages] = createSignal([
+    { id: '1', role: 'assistant', content: 'Hello! How can I help?' },
+  ]);
+
+  const onSubmit = (e: CustomEvent<{ value: string }>) => {
+    setMessages((prev) => [
+      ...prev,
+      { id: crypto.randomUUID(), role: 'user', content: e.detail.value },
+    ]);
+    // ...call your model, then append an assistant message
+  };
+
+  return (
+    <div class="flex flex-col h-full">
+      <kai-chat
+        // `prop:` forces a property assignment (not an attribute) for rich data.
+        prop:messages={messages()}
+        on:kai-submit={onSubmit}
+        style={{ flex: 1, 'min-height': 0 }}
+      />
+    </div>
+  );
+}
+```
+
+For a resizable web-component layout, use `<kai-resizable>` the same way (set properties, listen
+with `on:`) — though in a Solid app the native `Resizable` above gives you tighter control.
+
+> **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.
+
+## When to use which
+
+- **Native components** (`@kitn.ai/ui`) — full compositional control and the **smallest output**
+  for a Solid app, since they compile and tree-shake with your own code. The recommended path when
+  you're building in Solid.
+- **Web components** (`@kitn.ai/ui/elements`) — the **fastest drop-in** and fully
+  framework-agnostic. Reach for `<kai-chat>` (or any `<kai-*>` shell) when you want batteries included
+  or you're sharing UI across frameworks.
+
+Mix freely: a native composed thread on one screen, a drop-in `<kai-chat>` on another.

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

@@ -0,0 +1,194 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+
+<Meta title="Docs/Frameworks/Svelte" />
+
+# Svelte
+
+Custom elements are **first-class citizens in Svelte**: the compiler sets DOM properties directly
+when you pass non-primitive values, and `on:eventname` wires up CustomEvents with no extra
+boilerplate. No wrappers, no refs, no workarounds needed.
+
+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) near your app entry:
+
+```js
+// e.g. src/main.js or src/app.svelte <script>
+import '@kitn.ai/ui/elements';
+```
+
+- **`@kitn.ai/ui/elements`** — registers every `<kai-*>` element globally. One import is enough
+  for the whole app.
+- **No special config needed**: Svelte sets object and array values as DOM **properties** (not
+  stringified attributes) when you use the `{prop}` shorthand or `prop={value}` syntax. Custom
+  events fire as standard DOM `CustomEvent`s, so `on:eventname` just works.
+- **No CSS to import**: each element is styled inside its own Shadow DOM. Pull in
+  `@kitn.ai/ui/theme.css` only 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 element owns the UI.
+
+```html
+<script>
+  import '@kitn.ai/ui/elements';
+
+  let messages = [
+    { id: '1', role: 'assistant', content: 'Hello! How can I help?' },
+  ];
+
+  async function handleSubmit(e) {
+    const userContent = e.detail.value;
+    const history = [...messages, { id: crypto.randomUUID(), role: 'user', content: userContent }];
+    messages = history;
+
+    const aid = crypto.randomUUID();
+    messages = [...history, { id: aid, role: 'assistant', content: '' }];
+
+    let answer = '';
+    for await (const token of streamFromYourAPI(history)) {
+      answer += token;
+      // Reassign the array (and the changed object) so Svelte detects the update.
+      messages = messages.map((m) => (m.id === aid ? { ...m, content: answer } : m));
+    }
+  }
+</script>
+
+<!--
+  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}
+    suggestions={['Summarize the chat', 'Start fresh']}
+    on:kai-submit={handleSubmit}
+    style="flex: 1; min-height: 0;"
+  />
+</div>
+```
+
+> **`{messages}`** is Svelte shorthand for `messages={messages}`. Because the value is an array,
+> Svelte assigns it as a DOM **property** (not an attribute), so the element always receives a live
+> JS array — never a stringified version. The same applies to any object prop.
+
+## Go further — compose the pieces
+
+`<kai-chat>` is one option, not the only one. Every element can be used on its own, so you can
+assemble your own layout. Here's a multi-conversation shell — a `<kai-conversations>` sidebar next
+to the `<kai-chat>` thread:
+
+```html
+<script>
+  import '@kitn.ai/ui/elements';
+
+  let conversations = myConversations;
+  let activeId = conversations[0]?.id;
+  let messages = loadMessages(activeId);
+
+  function handleConversationSelect(e) {
+    activeId = e.detail.id;
+    messages = loadMessages(activeId);
+  }
+</script>
+
+<!--
+  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}
+    {activeId}
+    on:kai-conversation-select={handleConversationSelect}
+    on:kai-new-chat={() => startNewConversation()}
+    on:kai-toggle-sidebar={() => sidebarOpen = !sidebarOpen}
+    style="width: 300px; flex-shrink: 0;"
+  />
+
+  <kai-chat
+    {messages}
+    on:kai-submit={(e) => sendMessage(e.detail.value)}
+    style="flex: 1; min-width: 0;"
+  />
+</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 the `change` event
+(`detail.sizes`) to persist the layout.
+
+```html
+<script>
+  import '@kitn.ai/ui/elements';
+
+  function handleResize(e) {
+    // e.detail.sizes is an array of the current panel sizes
+    savePanelSizes(e.detail.sizes);
+  }
+</script>
+
+<div style="display: flex; flex-direction: column; height: 100dvh;">
+  <kai-resizable orientation="horizontal" on:kai-change={handleResize} style="flex: 1; min-height: 0;">
+    <kai-resizable-item size="25%" min="200px">
+      <kai-conversations {conversations} {activeId} on:kai-conversation-select={handleConversationSelect} />
+    </kai-resizable-item>
+    <kai-resizable-item>
+      <kai-chat {messages} on:kai-submit={handleSubmit} />
+    </kai-resizable-item>
+  </kai-resizable>
+</div>
+```
+
+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 shell. Each fills its container and is controlled via props and
+events.
+
+> **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 Svelte (and every other framework).
+
+## Props & events
+
+The rule for all elements: **rich data goes in as properties, interactions come out as events.**
+
+In Svelte, this maps cleanly to the template syntax you already know:
+
+| What | Svelte syntax | Notes |
+|---|---|---|
+| Pass a string | `prop="value"` or `{prop}` shorthand | Standard attribute or property |
+| Pass an array / object | `{prop}` or `prop={value}` | Svelte assigns as DOM property — no stringification |
+| Listen to a CustomEvent | `on:eventname={handler}` | `handler(e)` receives the `CustomEvent`; data is on `e.detail` |
+
+Key events and their `detail` shapes:
+
+| Element | Event | `e.detail` |
+|---|---|---|
+| `kai-chat` | `submit` | `{ value: string }` — the user's input text |
+| `kai-conversations` | `conversationselect` | `{ id: string }` — the selected conversation id |
+| `kai-conversations` | `newchat` | `{}` |
+| `kai-conversations` | `togglesidebar` | `{}` |
+| `kai-resizable` | `change` | `{ sizes: string[] }` — current panel sizes |
+
+No adapters, no special directives: Svelte's compiler handles property assignment on custom elements
+automatically, so `{messages}` always delivers a live JS array to the element.