@kitnai/chat 0.1.0

package/src/stories/conversation-with-sources.stories.tsx

@@ -0,0 +1,165 @@
+import type { Meta, StoryObj } from 'storybook-solidjs-vite';
+import {
+  ChatContainer, ChatContainerContent, ChatContainerScrollAnchor,
+  Message, MessageAvatar, MessageContent, MessageActions,
+  PromptInput, PromptInputTextarea, PromptInputActions,
+  Source, SourceTrigger, SourceContent, SourceList,
+  Button, Separator,
+} from '../index';
+import { Copy, ThumbsUp, ThumbsDown, ArrowUp } from 'lucide-solid';
+
+const meta: Meta = {
+  title: 'Examples/Conversation with Sources',
+  parameters: { layout: 'padded' },
+};
+
+export default meta;
+type Story = StoryObj;
+
+export const Default: Story = {
+  render: () => (
+    <div class="flex flex-col h-[650px] w-full max-w-2xl bg-background rounded-xl shadow-lg overflow-hidden">
+      <div class="flex items-center px-4 py-3">
+        <h2 class="text-sm font-semibold text-foreground">Research: WebAssembly in Production</h2>
+      </div>
+      <Separator />
+
+      <ChatContainer class="flex-1 p-4">
+        <ChatContainerContent class="space-y-6 py-4">
+
+          {/* First exchange */}
+          <Message>
+            <MessageAvatar src="" fallback="U" alt="User" />
+            <MessageContent>
+              What are the real-world performance benefits of using WebAssembly in production web apps? I want concrete examples, not just benchmarks.
+            </MessageContent>
+          </Message>
+
+          <Message>
+            <MessageAvatar src="" fallback="AI" alt="Assistant" />
+            <div class="flex-1 space-y-2">
+              <MessageContent markdown>
+{`Several major companies have deployed WebAssembly in production with measurable results:
+
+**Figma** replaced their C++ to asm.js pipeline with Wasm and saw a **3x performance improvement** in load times. Their design tool renders complex vector graphics at 60fps using a Wasm-compiled engine.
+
+**Google Earth** ported their native rendering engine to Wasm, enabling the full 3D globe experience in browsers without plugins. Frame rendering dropped from **40ms to 12ms** per frame.
+
+**Shopify** uses Wasm for their theme editor's Liquid template parsing, achieving **10x faster** template compilation compared to their previous JavaScript parser.
+
+The pattern is consistent: CPU-intensive tasks like **image processing, cryptography, physics simulation, and codec operations** see the largest gains. IO-bound operations don't benefit as much.`}
+              </MessageContent>
+
+              <SourceList>
+                <Source href="https://www.figma.com/blog/webassembly-cut-figmas-load-time-by-3x/">
+                  <SourceTrigger label={1} />
+                  <SourceContent
+                    title="WebAssembly cut Figma's load time by 3x"
+                    description="How Figma leveraged WebAssembly to dramatically improve their browser-based design tool performance."
+                  />
+                </Source>
+                <Source href="https://web.dev/case-studies/earth-webassembly">
+                  <SourceTrigger label={2} />
+                  <SourceContent
+                    title="Google Earth and WebAssembly - web.dev"
+                    description="Case study on porting Google Earth's C++ rendering engine to WebAssembly for browser delivery."
+                  />
+                </Source>
+                <Source href="https://shopify.engineering/shopify-webassembly">
+                  <SourceTrigger label={3} />
+                  <SourceContent
+                    title="How Shopify Uses WebAssembly"
+                    description="Shopify's journey using WebAssembly for Liquid template parsing in their online store editor."
+                  />
+                </Source>
+              </SourceList>
+
+              <MessageActions>
+                <Button variant="ghost" size="icon-sm"><Copy class="size-3.5" /></Button>
+                <Button variant="ghost" size="icon-sm"><ThumbsUp class="size-3.5" /></Button>
+                <Button variant="ghost" size="icon-sm"><ThumbsDown class="size-3.5" /></Button>
+              </MessageActions>
+            </div>
+          </Message>
+
+          {/* Second exchange with different citation pattern */}
+          <Message>
+            <MessageAvatar src="" fallback="U" alt="User" />
+            <MessageContent>
+              What about the downsides? Are there situations where Wasm actually hurts performance?
+            </MessageContent>
+          </Message>
+
+          <Message>
+            <MessageAvatar src="" fallback="AI" alt="Assistant" />
+            <div class="flex-1 space-y-2">
+              <MessageContent markdown>
+{`Yes, there are real tradeoffs to consider:
+
+**Bundle size** -- Wasm modules can be significantly larger than equivalent JavaScript. The Squoosh image editor found their Wasm codecs added **2-4MB** of download size, which they mitigated with lazy loading.
+
+**DOM access overhead** -- Every call from Wasm to the DOM crosses a boundary with serialization cost. Applications that frequently manipulate the DOM (like React-style UI frameworks) can actually be **slower** in Wasm than optimized JavaScript.
+
+**Startup latency** -- Wasm modules must be compiled before execution. While streaming compilation helps, large modules can take **200-500ms** to initialize on mobile devices.
+
+**Garbage collection** -- Until the Wasm GC proposal ships broadly, languages like Go and Java bring their own GC runtime, adding **5-20MB** to module size.
+
+The consensus from the Chrome team's analysis is: **use Wasm for compute-heavy inner loops, keep UI and orchestration in JavaScript**.`}
+              </MessageContent>
+
+              <SourceList>
+                <Source href="https://web.dev/squoosh-v2/">
+                  <SourceTrigger label={1} showFavicon />
+                  <SourceContent
+                    title="Squoosh v2: codec improvements with WebAssembly"
+                    description="How the Squoosh team manages Wasm codec size and loading strategies for their image compression tool."
+                  />
+                </Source>
+                <Source href="https://surma.dev/things/js-to-asc/">
+                  <SourceTrigger label={2} showFavicon />
+                  <SourceContent
+                    title="JavaScript to AssemblyScript - Surma.dev"
+                    description="Detailed performance comparison of JS vs AssemblyScript/Wasm for various workloads including DOM-heavy tasks."
+                  />
+                </Source>
+                <Source href="https://v8.dev/blog/wasm-compilation-pipeline">
+                  <SourceTrigger label={3} showFavicon />
+                  <SourceContent
+                    title="Liftoff: V8's Wasm baseline compiler"
+                    description="V8 team's analysis of Wasm compilation latency and their streaming compilation optimization."
+                  />
+                </Source>
+                <Source href="https://chromestatus.com/feature/6062715726462976">
+                  <SourceTrigger label={4} showFavicon />
+                  <SourceContent
+                    title="WebAssembly Garbage Collection - Chrome Platform Status"
+                    description="Status of the WasmGC proposal and its impact on languages targeting WebAssembly."
+                  />
+                </Source>
+              </SourceList>
+
+              <MessageActions>
+                <Button variant="ghost" size="icon-sm"><Copy class="size-3.5" /></Button>
+                <Button variant="ghost" size="icon-sm"><ThumbsUp class="size-3.5" /></Button>
+                <Button variant="ghost" size="icon-sm"><ThumbsDown class="size-3.5" /></Button>
+              </MessageActions>
+            </div>
+          </Message>
+
+          <ChatContainerScrollAnchor />
+        </ChatContainerContent>
+      </ChatContainer>
+
+      <div class="px-4 pb-4">
+        <PromptInput>
+          <PromptInputTextarea placeholder="Ask about WebAssembly..." />
+          <PromptInputActions class="justify-end">
+            <Button variant="default" size="icon-sm" class="rounded-full">
+              <ArrowUp class="size-4" />
+            </Button>
+          </PromptInputActions>
+        </PromptInput>
+      </div>
+    </div>
+  ),
+};

package/src/stories/docs/GettingStarted.mdx

@@ -0,0 +1,76 @@
+import { Meta, Canvas } from '@storybook/addon-docs/blocks';
+import * as FullChat from '../full-chat.stories';
+
+<Meta title="Getting Started" />
+
+# Getting Started
+
+`<kitn-chat>` is **transport-agnostic**: you give it a `messages` array, it renders the conversation, and it emits a `submit` event when the user sends. You own the request and the streaming; the component owns the UI.
+
+## A web component in ~10 lines
+
+Set rich data as JS **properties** and listen for **events** on the element:
+
+```html
+<kitn-chat id="chat" style="display:block; height:100vh;"></kitn-chat>
+
+<script type="module">
+  import '@kitnai/chat/elements';
+
+  const chat = document.getElementById('chat');
+  chat.messages = [
+    { id: '1', role: 'assistant', content: 'Hello! How can I help?' },
+  ];
+
+  chat.addEventListener('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.
+
+## The same thing in SolidJS
+
+```tsx
+import {
+  ChatConfig, ChatContainer, ChatContainerContent,
+  Message, MessageContent,
+  PromptInput, PromptInputTextarea, PromptInputActions,
+} from '@kitnai/chat';
+import { createSignal } from 'solid-js';
+
+function Chat() {
+  const [input, setInput] = createSignal('');
+  return (
+    <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>
+  );
+}
+```
+
+## 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 in the sidebar.
+
+Ready to make it yours? See **[Theming](?path=/docs/theming--docs)**. Wiring a real model? See **[Integrations](?path=/docs/integrations--docs)**.

package/src/stories/docs/Installation.mdx

@@ -0,0 +1,48 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+
+<Meta title="Installation" />
+
+# Installation
+
+```bash
+npm install @kitnai/chat
+```
+
+The package ships two entry points: the SolidJS components (`@kitnai/chat`) and the framework-agnostic web components (`@kitnai/chat/elements`). Pick whichever fits your stack — you can mix them.
+
+## SolidJS projects
+
+SolidJS is a peer dependency:
+
+```bash
+npm install solid-js
+```
+
+Import the components and the design tokens once:
+
+```tsx
+import { ChatContainer, Message, MessageContent, PromptInput } from '@kitnai/chat';
+import '@kitnai/chat/theme.css';
+```
+
+The `@kitnai/chat` entry is shipped as source, so your bundler tree-shakes it down to exactly what you import.
+
+## Web components (React, Vue, plain HTML, …)
+
+Build the element bundle, then import it as a **side effect** — that registers `<kitn-chat>`, `<kitn-conversation-list>`, and `<kitn-prompt-input>`:
+
+```bash
+npm run build   # emits dist/kitn-chat.es.js
+```
+
+```html
+<script type="module">
+  import '@kitnai/chat/elements';
+</script>
+```
+
+- The bundle is **ESM-only** and loads via `<script type="module">` in every modern browser.
+- **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 and only needed if you want to override design tokens.
+
+Head to **[Getting Started](?path=/docs/getting-started--docs)** to render your first chat.

package/src/stories/docs/Integrations.mdx

@@ -0,0 +1,110 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+
+<Meta title="Integrations" />
+
+# 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.
+
+## 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.
+
+> **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.
+
+```js
+chat.addEventListener('submit', async (e) => {
+  const text = e.detail.value.trim();
+  if (!text) return;
+
+  // 1. Show the user message; clear the input
+  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
+  const assistantId = crypto.randomUUID();
+  chat.messages = [...history, { id: assistantId, role: 'assistant', content: '' }];
+
+  // In production, replace this URL 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!
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify({
+      model: 'anthropic/claude-sonnet-4',
+      stream: true,
+      messages: history.map((m) => ({ role: m.role, content: m.content })),
+    }),
+  });
+
+  const reader = res.body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = '';
+  let answer = '';
+
+  while (true) {
+    const { value, done } = await reader.read();
+    if (done) break;
+    buffer += decoder.decode(value, { stream: true });
+
+    const lines = buffer.split('\n');
+    buffer = lines.pop();                       // keep the partial last line
+    for (const line of lines) {
+      const s = line.trim();
+      if (!s.startsWith('data:')) continue;     // skip keep-alive comments
+      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
+        );
+      } catch { /* ignore non-JSON keep-alive lines */ }
+    }
+  }
+  chat.loading = false;
+});
+```
+
+## Text-to-speech (TTS)
+
+### Browser-native (zero dependencies)
+
+Speak each reply once it finishes streaming — call `speak(answer)` right before `chat.loading = false`:
+
+```js
+function speak(text) {
+  if (!('speechSynthesis' in window)) return;
+  const utter = new SpeechSynthesisUtterance(text);
+  utter.lang = 'en-US';
+  speechSynthesis.cancel();
+  speechSynthesis.speak(utter);
+}
+```
+
+### 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):
+
+```js
+async function speakCloud(text) {
+  const res = await fetch('/api/tts', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ text, voice: 'alloy' }),
+  });
+  const audio = new Audio(URL.createObjectURL(await res.blob()));
+  audio.play();
+}
+```
+
+## 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.

package/src/stories/docs/Introduction.mdx

@@ -0,0 +1,29 @@
+import { Meta, Canvas } from '@storybook/addon-docs/blocks';
+import * as ChatPanel from '../chat-panel-layout.stories';
+
+<Meta title="Introduction" />
+
+# @kitnai/chat
+
+**A SolidJS + Shadow-DOM web component kit 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 @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.
+- **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.
+- **Themeable** — restyle everything by overriding a handful of `--color-*` design tokens.
+
+## 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
+
+Or browse every component in isolation from the sidebar.

package/src/stories/docs/Theming.mdx

@@ -0,0 +1,87 @@
+import { Meta, Canvas } from '@storybook/addon-docs/blocks';
+import * as TokenRef from '../token-reference.stories';
+
+<Meta title="Theming" />
+
+# 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-flex',
+    alignItems: 'center',
+    gap: '0.45rem',
+    background: 'var(--color-primary, #18181b)',
+    color: 'var(--color-primary-foreground, #fafafa)',
+    padding: '0.55rem 1rem',
+    borderRadius: 'var(--radius-md, 0.5rem)',
+    fontWeight: 600,
+    fontSize: '0.875rem',
+    lineHeight: 1,
+    textDecoration: 'none',
+    boxShadow: '0 1px 2px rgba(0,0,0,0.08)',
+  }}
+>
+  Open the theme editor <span aria-hidden="true">→</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 `<kitn-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
+<kitn-chat prose-size="base" code-theme="github-dark-dimmed"></kitn-chat>
+```
+
+That's the whole theming surface — tokens for color, `ChatConfig` for sizing and code. Everything else is encapsulated.

package/src/stories/docs/theme-editor/canvas.tsx

@@ -0,0 +1,32 @@
+import { ChatScene } from '../../chat-scene';
+
+/** Class the editor targets to write the active mode's token values directly onto
+ *  this wrapper — so the preview reflects the editor's mode independently of any
+ *  ancestor `.dark` (e.g. Storybook's own dark theme), and only the canvas reskins. */
+export const CANVAS_CLASS = 'kitn-editor-canvas';
+
+/** Live preview: the real chat app scene + a small rail for tokens the chat
+ *  doesn't naturally surface. The editor sets the active palette on CANVAS_CLASS;
+ *  the `.dark` class is also applied for any `dark:`-keyed component styling. */
+export function Canvas(props: { mode: 'light' | 'dark' }) {
+  return (
+    <div classList={{ [CANVAS_CLASS]: true, dark: props.mode === 'dark' }} class="h-full">
+      <div class="h-full flex flex-col rounded-xl border border-border overflow-hidden bg-background">
+        {/* The real product UI — same component the Full Chat App example uses */}
+        <div class="flex-1 min-h-0">
+          <ChatScene class="h-full" />
+        </div>
+
+        {/* Coverage rail: tokens the chat scene doesn't surface at rest */}
+        <div class="shrink-0 border-t border-border px-4 py-2.5 flex flex-wrap items-center gap-2 bg-background text-foreground">
+          <span class="text-[11px] text-muted-foreground mr-1">Other tokens:</span>
+          <button class="bg-destructive text-destructive-foreground rounded-md px-3 h-8 text-xs font-medium">Destructive</button>
+          <button class="bg-secondary text-secondary-foreground rounded-md px-3 h-8 text-xs font-medium">Secondary</button>
+          <span class="bg-accent text-accent-foreground rounded-md px-2.5 py-1.5 text-xs">Accent</span>
+          <span class="bg-popover text-popover-foreground border border-border shadow rounded-md px-2.5 py-1.5 text-xs">Popover</span>
+          <input class="bg-input border border-border rounded-md px-2 h-8 text-xs ring-2 ring-ring" placeholder="Focus ring" />
+        </div>
+      </div>
+    </div>
+  );
+}

package/src/stories/docs/theme-editor/inspector.tsx

@@ -0,0 +1,66 @@
+// src/stories/docs/theme-editor/inspector.tsx
+import { For, type JSX } from 'solid-js';
+import { toHex, PURPOSE } from '../theme-tokens';
+import type { Palette } from './theme-css';
+
+const RADIUS_MAX = 1.4; // rem
+
+export function Inspector(props: {
+  tokens: string[]; // ordered '--color-*' names
+  values: Palette; // active-mode palette (drives swatch colors)
+  radius: string; // e.g. '0.6rem'
+  onColorChange: (token: string, hex: string) => void;
+  onRadiusChange: (rem: string) => void;
+}) {
+  const radiusRem = () => parseFloat(props.radius) || 0;
+  const swatch: JSX.CSSProperties = {
+    width: '1.75rem', height: '1.75rem', padding: '0', border: '1px solid var(--color-border)',
+    'border-radius': '6px', background: 'none', cursor: 'pointer', 'flex-shrink': '0',
+  };
+  return (
+    <div class="p-3 text-foreground">
+      <div class="text-xs font-semibold mb-2.5 text-muted-foreground uppercase tracking-wide">Tokens</div>
+      <div class="flex flex-col gap-2.5">
+        <For each={props.tokens}>
+          {(name) => {
+            const hex = () => {
+              try {
+                return toHex(props.values[name]);
+              } catch {
+                return '#888888';
+              }
+            };
+            return (
+              <label class="flex items-center gap-2.5">
+                <input
+                  type="color"
+                  value={hex()}
+                  onInput={(e) => props.onColorChange(name, e.currentTarget.value)}
+                  style={swatch}
+                />
+                <span class="flex min-w-0 flex-col leading-tight">
+                  <span class="text-sm font-medium truncate">{name.replace('--color-', '')}</span>
+                  <span class="text-xs text-muted-foreground truncate">{PURPOSE[name] ?? ''}</span>
+                </span>
+              </label>
+            );
+          }}
+        </For>
+      </div>
+
+      <div class="text-xs font-semibold mt-5 mb-2.5 text-muted-foreground uppercase tracking-wide">Radius</div>
+      <label class="flex items-center gap-2.5 text-sm">
+        <input
+          type="range"
+          min="0"
+          max={RADIUS_MAX}
+          step="0.05"
+          value={radiusRem()}
+          onInput={(e) => props.onRadiusChange(`${e.currentTarget.value}rem`)}
+          class="flex-1"
+        />
+        <span class="text-sm tabular-nums w-16 text-right">{props.radius}</span>
+      </label>
+    </div>
+  );
+}

package/src/stories/docs/theme-editor/presets.test.ts

@@ -0,0 +1,32 @@
+import { describe, it, expect } from 'vitest';
+import { buildPresets, BRAND_OVERRIDES } from './presets';
+
+const base = {
+  light: { '--color-primary': 'hsl(240 5.9% 10%)', '--color-border': 'hsl(240 5.9% 90%)', '--radius': '0.6rem' },
+  dark: { '--color-primary': 'hsl(0 0% 98%)', '--color-border': 'hsl(240 3.7% 15.9%)' },
+};
+
+describe('buildPresets', () => {
+  it('orders Default first, then the brand presets', () => {
+    expect(buildPresets(base).map((p) => p.name)).toEqual(['Default', 'Violet', 'Emerald', 'Mono']);
+  });
+
+  it('Default preset equals the base palette (no drift)', () => {
+    const def = buildPresets(base).find((p) => p.name === 'Default')!;
+    expect(def.light).toEqual(base.light);
+    expect(def.dark).toEqual(base.dark);
+  });
+
+  it('brand presets override primary but preserve base neutrals', () => {
+    const violet = buildPresets(base).find((p) => p.name === 'Violet')!;
+    expect(violet.light['--color-primary']).toBe(BRAND_OVERRIDES.Violet.light['--color-primary']);
+    expect(violet.light['--color-border']).toBe(base.light['--color-border']);
+    expect(violet.light['--radius']).toBe(base.light['--radius']);
+  });
+
+  it('does not mutate the base palette', () => {
+    const snapshot = JSON.stringify(base);
+    buildPresets(base);
+    expect(JSON.stringify(base)).toBe(snapshot);
+  });
+});