@kitn.ai/ui 0.14.1

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

@@ -0,0 +1,238 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+
+<Meta title="Docs/Frameworks/Vue" />
+
+# Vue
+
+Use the `kai-*` custom elements directly in Vue templates. Pass arrays and objects via the **`.prop`
+modifier** so Vue sets them as live DOM properties (not stringified attributes). Events use the
+standard `@event` syntax.
+
+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**
+`createApp().mount()`. Vue stamps the tags at mount time — if the elements aren't registered yet,
+array/object props set by Vue are clobbered when the elements upgrade later and the UI renders blank.
+
+```ts
+// src/main.ts
+import '@kitn.ai/ui/elements'; // MUST come before createApp
+import { createApp } from 'vue';
+import App from './App.vue';
+
+createApp(App).mount('#app');
+```
+
+Tell Vue's template compiler that `kai-*` tags are native custom elements, not Vue components —
+this prevents "Unknown custom element" warnings and ensures `.prop` bindings work correctly:
+
+```ts
+// vite.config.ts
+import { defineConfig } from 'vite';
+import vue from '@vitejs/plugin-vue';
+
+export default defineConfig({
+  plugins: [
+    vue({
+      template: {
+        compilerOptions: {
+          isCustomElement: (tag) => tag.startsWith('kai-'),
+        },
+      },
+    }),
+  ],
+});
+```
+
+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**).
+
+### TypeScript / Volar augmentation
+
+Add a reference to the kit's type declarations once so Vue's template compiler (and Volar) knows
+the element's attributes and properties:
+
+```ts
+// env.d.ts (or vite-env.d.ts)
+/// <reference types="@kitn.ai/ui/elements" />
+```
+
+## 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 setup lang="ts">
+import '@kitn.ai/ui/elements';
+import { ref } from 'vue';
+
+type Message = { id: string; role: 'user' | 'assistant'; content: string };
+
+const messages = ref<Message[]>([
+  { id: '1', role: 'assistant', content: 'Hello! How can I help?' },
+]);
+
+const handleSubmit = async (e: CustomEvent<{ value: string }>) => {
+  const history = [...messages.value, { id: crypto.randomUUID(), role: 'user' as const, content: e.detail.value }];
+  messages.value = history;
+
+  const aid = crypto.randomUUID();
+  messages.value = [...history, { id: aid, role: 'assistant', content: '' }];
+
+  let answer = '';
+  for await (const token of streamFromYourAPI(history)) {
+    answer += token;
+    messages.value = messages.value.map((m) => (m.id === aid ? { ...m, content: answer } : m));
+  }
+};
+</script>
+
+<template>
+  <!-- The elements fill their container — use 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.prop="messages"
+      :suggestions.prop="['Summarize the chat', 'Start fresh']"
+      style="flex: 1; min-height: 0;"
+      @kai-submit="handleSubmit"
+    />
+  </div>
+</template>
+```
+
+## Go further — compose the pieces
+
+`<kai-chat>` is one option, not the only one. Every element can be composed in your own layout.
+Here's a multi-conversation shell — a `<kai-conversations>` sidebar next to the `<kai-chat>` thread:
+
+```html
+<script setup lang="ts">
+import '@kitn.ai/ui/elements';
+import { ref } from 'vue';
+
+const conversations = ref([
+  {
+    id: 'c1',
+    title: 'First chat',
+    scope: { type: 'document' },
+    messageCount: 3,
+    lastMessageAt: '2026-06-01T12:00:00Z',
+    updatedAt: '2026-06-01T12:00:00Z',
+  },
+]);
+const activeId = ref('c1');
+const messages = ref([{ id: '1', role: 'assistant', content: 'Hi!' }]);
+
+const onSelect = (e: CustomEvent<{ id: string }>) => {
+  activeId.value = e.detail.id;
+  // load messages for the selected conversation
+};
+
+const onSubmit = (e: CustomEvent<{ value: string }>) => {
+  // send message and stream reply
+};
+</script>
+
+<template>
+  <!-- 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.prop="conversations"
+      :active-id="activeId"
+      style="width: 300px; flex-shrink: 0;"
+      @kai-conversation-select="onSelect"
+      @kai-new-chat="startNewConversation"
+    />
+    <kai-chat
+      :messages.prop="messages"
+      style="flex: 1; min-width: 0;"
+      @kai-submit="onSubmit"
+    />
+  </div>
+</template>
+```
+
+### 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
+<template>
+  <div style="display: flex; flex-direction: column; height: 100dvh;">
+    <kai-resizable orientation="horizontal" style="flex: 1; min-height: 0;">
+      <kai-resizable-item size="25%" min="200px">
+        <kai-conversations
+          :conversations.prop="conversations"
+          :active-id="activeId"
+          @kai-conversation-select="onSelect"
+        />
+      </kai-resizable-item>
+      <kai-resizable-item>
+        <kai-chat :messages.prop="messages" @kai-submit="onSubmit" />
+      </kai-resizable-item>
+    </kai-resizable>
+  </div>
+</template>
+```
+
+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 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 Vue (and every other framework).
+
+## Props & events
+
+The rule for all elements: **rich data (arrays, objects) goes in as DOM properties; interactions
+come out as CustomEvents.**
+
+In Vue templates, use the **`.prop` modifier** to bind rich data as DOM properties rather than
+stringified HTML attributes. Scalar values (strings, booleans, numbers) can go through normal
+attribute bindings. Events use `@event` and carry their payload in `event.detail`.
+
+| Binding type | Vue syntax | When to use |
+|---|---|---|
+| Rich data (array/object) | `:messages.prop="messages"` | Always for arrays and objects |
+| Scalar attribute | `:active-id="activeId"` or `active-id="c1"` | Strings, booleans, numbers |
+| Event | `@kai-conversation-select="onSelect"` | All CustomEvents |
+
+Common events and their `detail` payloads:
+
+| Element | DOM event | `detail` |
+|---|---|---|
+| `kai-chat` | `submit` | `{ value: string }` |
+| `kai-conversations` | `conversationselect` | `{ id: string }` |
+| `kai-conversations` | `newchat` | — |
+| `kai-conversations` | `togglesidebar` | — |
+| `kai-resizable` | `change` | `{ sizes: string[] }` |
+
+Example event handler pattern:
+
+```ts
+const onSelect = (e: CustomEvent<{ id: string }>) => {
+  activeId.value = e.detail.id;
+};
+```

package/src/stories/docs/generative-ui-overview.mdx

@@ -0,0 +1,186 @@
+{/* src/stories/docs/generative-ui-overview.mdx */}
+import { Meta } from '@storybook/addon-docs/blocks';
+
+<Meta title="Generative UI/Overview" />
+
+# Generative UI
+
+Agents don't just reply with text — they ask the chat to **render typed, interactive
+cards**: a form to fill, an action to approve, a plan to pick from, a link to preview.
+`@kitn.ai/ui` does this with a small, typed **Card Contract** and a turnkey dispatcher.
+
+## The loop
+
+```
+agent/server ──CardEnvelope(s)──▶ host sets <kai-cards>.cards
+     ▲                                      │
+     │                              dispatcher renders the right kai-* by `type`
+     │                                      │
+     └── result / next envelopes ◀─ CardPolicy ◀─ kai-card event ◀─ user interacts
+```
+
+## Envelopes vs. cards
+
+Two things are easy to conflate — keeping them straight makes the rest click:
+
+- An **envelope** is what the agent *sends*: an addressed data wrapper, not UI. Like a
+  postal envelope, it *carries* a card spec but isn't the card itself.
+- A **card** is what the user *sees*: the rendered, interactive UI the dispatcher mounts
+  for that envelope (a `kai-form`, `kai-confirm`, … inside the shared card chrome).
+
+The dispatcher's whole job is **envelope in → card out** — one envelope renders one card.
+
+Everything an agent sends is a `CardEnvelope`:
+
+```ts
+interface CardEnvelope {
+  type: string;        // selects the card: form | confirm | choice | tasks | link | embed
+  id: string;          // correlates every event back to this card
+  data: unknown;       // follows that type's JSON Schema (shipped in dist/schemas)
+  title?: string;      // optional chrome heading
+  resolution?: CardResolution; // set once the user acts → renders the read-only view
+}
+```
+
+`data` follows the `type`'s **JSON Schema**, so an agent/server can validate before
+sending; `id` correlates every event back to this card. (For **remote** cards, a transport
+`WireFrame` wraps this *same* envelope over `postMessage` — the envelope inside is identical;
+see Remote cards.)
+
+## Turnkey: drop `<kai-cards>`
+
+```html
+<kai-cards></kai-cards>
+<script type="module">
+  import '@kitn.ai/ui/elements';
+  const cards = document.querySelector('kai-cards');
+  cards.cards = [{ type: 'confirm', id: 'deploy', title: 'Deploy?',
+    data: { body: 'Ship it?', actions: [{ id: 'go', label: 'Deploy', default: true }] } }];
+  cards.policy = { onAction: (id, action) => console.log(id, action) };
+</script>
+```
+
+`<kai-cards>` renders one card per envelope and routes every interaction through `policy`
+(or listen for the raw bubbling `kai-card` event). In SolidJS, use `renderCard(envelope)` /
+`<CardRenderer>` inside a `<CardProvider>`.
+
+## Streaming & follow-ups
+
+Swap the `cards` array to add, replace, or remove cards — e.g. replace a `confirm` with a
+result card once the user acts. For **live streaming into a single card**, the SolidJS
+`<CardRenderer>` re-renders reactively as its envelope's `data` changes, so an agent can
+stream into it as work progresses. (Keyed-by-`id` in-place updates within a `<kai-cards>`
+list are a planned refinement.)
+
+## Resolved cards
+
+Interactive cards (`kai-confirm`, `kai-choice`, `kai-tasks`, `kai-form`) flip to a **chromed
+read-only** view the moment the user acts — optimistically, before any server round-trip.
+
+To make that survive a **reload or history re-hydration**, the card reads an optional
+`resolution` field on its `CardEnvelope`. Persist it by feeding the card's terminal event
+back into the array with the `applyResolution` helper:
+
+```ts
+import { applyResolution } from '@kitn.ai/ui';
+
+// <kai-cards> is controlled — persist the resolution so it survives reload:
+el.addEventListener('kai-card', (e) => {
+  el.cards = applyResolution(el.cards, e.detail); // resolved cards re-hydrate read-only
+  // …then save el.cards to your store/server.
+});
+```
+
+`applyResolution` is pure and safe to call on every `kai-card` event — non-terminal events
+(`ready` / `error` / …) and unknown card ids return the same array unchanged. The terminal
+verbs are `action` (confirm / choice) and `submit` (tasks / form).
+
+## Remote cards
+
+Everything above renders cards you **bundle yourself** — the dispatcher mounts a native
+`kai-*` element for each envelope. That native `types` seam stays the easy path: register a
+card type, ship its element, done.
+
+**Remote cards** are the power feature for **provider-owned, cross-origin UI** — a card
+whose code lives on a *different* origin (a partner, a plugin, your own card service) and
+that you don't want to bundle or trust in your DOM. `<kai-remote>` renders it inside a
+**sandboxed cross-origin `<iframe>`** and bridges it to the host over `postMessage`, carrying
+the **exact same** `CardEnvelope` / `CardContext` / `CardEvent` shapes and routing every
+event through the **same `CardPolicy`** as a native card. The envelope inside is identical —
+a transport `WireFrame` just wraps it on the wire.
+
+```html
+<kai-remote
+  provider-origin="https://cards.provider.example"
+  src="https://cards.provider.example/card"
+></kai-remote>
+<script type="module">
+  import '@kitn.ai/ui/elements'; // registers <kai-remote>
+
+  const el = document.querySelector('kai-remote');
+  // The CardEnvelope is set as a JS property — it travels down the wire unchanged.
+  el.envelope = { type: 'form', id: 'signup', title: 'Join the beta',
+    data: { type: 'object', required: ['email'],
+      properties: { email: { type: 'string', title: 'Email', format: 'email' } } } };
+
+  // Every routed event is re-emitted as a bubbling kai-card CustomEvent — persist the
+  // resolution exactly like a native card:
+  el.addEventListener('kai-card', (e) => {
+    if (e.detail.kind === 'submit') save(e.detail.data);
+  });
+  // …or pass a CardPolicy directly: el.policy = { onSubmit: (id, data) => save(data) };
+</script>
+```
+
+Prefer the **imperative** SDK when you manage the lifecycle yourself (theme refresh, swapping
+cards in one warm frame):
+
+```ts
+import { mountRemoteCard } from '@kitn.ai/ui';
+
+const handle = mountRemoteCard({
+  container: document.querySelector('#slot'),
+  providerOrigin: 'https://cards.provider.example',
+  src: 'https://cards.provider.example/card',
+  envelope,
+  context: { theme: { mode: 'dark' }, locale: 'en', authToken },
+  policy: { onSubmit: (cardId, data) => { /* persist via applyResolution, advance the chat */ } },
+});
+
+handle.updateContext({ theme: { mode: 'light' } }); // re-themes the framed card live
+handle.update(nextEnvelope);                          // swap cards in the same iframe
+handle.destroy();                                     // teardown + remove the frame
+```
+
+**Inputs.** `providerOrigin` is the exact origin (`https://…`, or `http://localhost` for
+dev) the iframe is pinned to. `src` is the provider page URL (must be on `providerOrigin`).
+`envelope` is the `CardEnvelope` to render. `policy` is the optional `CardPolicy`. `context`
+carries theme/locale/`a11y` and a short-lived `authToken`.
+
+**Theme changes remount; token/locale refreshes are silent (v1).** A host **theme change
+re-renders (remounts) the remote card**, so any in-progress remote-card state (e.g. a
+half-filled form) **resets on a theme toggle** — renderers apply theme imperatively at mount,
+and v1 has no in-place renderer theme hook yet. **Token / locale / `a11y` refreshes are
+silent** (no remount — renderers read `host.context()` on demand). A future refinement is a
+renderer context subscription for live re-theme without remount.
+
+**Security model.** The host mints a per-instance **nonce** and pins every inbound frame on
+**origin + source window + nonce + negotiated protocol version** — a frame failing any check
+is dropped, so a wrong-origin or forged `postMessage` can't drive your policy. The iframe is
+sandboxed (`allow-scripts allow-forms allow-same-origin`, **no** `allow-popups`) and gets a
+`no-referrer` policy. Any `authToken` you pass should be **short-lived** (the provider sees
+it). The **host page must set `Content-Security-Policy: frame-ancestors 'self'`** (or
+`'none'`) so it can't itself be reframed; the **provider** locks who may embed it with its
+own `frame-ancestors` listing your exact host origin (no wildcards).
+
+**Reference runtime.** `examples/remote-provider/` is the runnable provider iframe a real
+provider copies — it calls `createCardBridge` (from `@kitn.ai/ui/provider`, a SolidJS-free
+bundle) and registers one renderer per card `type`. `examples/remote-host/` is the matching
+host page. The real cross-origin behavior is verified by the standalone Playwright suite
+(`tests/e2e/`).
+
+## Card elements are `kai-*` components too
+
+Each card type (`kai-confirm`, `kai-choice`, `kai-tasks`, `kai-form`, `kai-link`, `kai-embed`, `kai-remote`) is a registered `kai-*` custom element with its own prop/event API — the same model as everything else under **Components**. They live here under **Generative UI / Cards** because they only make sense inside the dispatcher/envelope system, but they follow the same component contract: attributes, JS properties, a `kai-card` event, CSS parts. Browse **Generative UI → Cards** for the per-element API references and live demos.
+
+See **Cards** for each card type, and **SDK** for the dispatcher in action.

package/src/stories/docs/recipes/SpeechToText.mdx

@@ -0,0 +1,7 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+
+<Meta title="Docs/Recipes/Speech-to-Text" />
+
+# Speech-to-text
+
+The reverse direction is built in — the kit ships `<kai-voice-input>` (and a `VoiceInput` SolidJS component). Find it in the sidebar under the component stories.

package/src/stories/docs/recipes/Streaming.mdx

@@ -0,0 +1,68 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+
+<Meta title="Docs/Recipes/Streaming (OpenRouter)" />
+
+# Streaming from OpenRouter
+
+[OpenRouter](https://openrouter.ai) exposes an OpenAI-compatible streaming API (Server-Sent Events). Wire it into the `submit` event:
+
+> **Security:** never ship an API key to the browser. In production, point `fetch` at your own backend that proxies to OpenRouter and injects the key.
+
+```js
+chat.addEventListener('kai-submit', async (e) => {
+  const text = e.detail.value.trim();
+  if (!text) return;
+
+  // 1. Show the user message
+  const history = [...chat.messages, { id: crypto.randomUUID(), role: 'user', content: text }];
+  chat.messages = history;
+  chat.loading = true;
+
+  // 2. Empty assistant placeholder to stream into
+  const assistantId = crypto.randomUUID();
+  chat.messages = [...history, { id: assistantId, role: 'assistant', content: '' }];
+
+  // In production, replace this with your own proxy endpoint.
+  const res = await fetch('https://openrouter.ai/api/v1/chat/completions', {
+    method: 'POST',
+    headers: {
+      'Authorization': `Bearer ${OPENROUTER_API_KEY}`,
+      '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();
+    for (const line of lines) {
+      const s = line.trim();
+      if (!s.startsWith('data:')) continue;
+      const payload = s.slice(5).trim();
+      if (payload === '[DONE]') continue;
+      try {
+        const delta = JSON.parse(payload).choices?.[0]?.delta?.content;
+        if (!delta) continue;
+        answer += delta;
+        chat.messages = chat.messages.map((m) =>
+          m.id === assistantId ? { ...m, content: answer } : m
+        );
+      } catch { /* ignore non-JSON keep-alive lines */ }
+    }
+  }
+  chat.loading = false;
+});
+```

package/src/stories/docs/recipes/TextToSpeech.mdx

@@ -0,0 +1,35 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+
+<Meta title="Docs/Recipes/Text-to-Speech" />
+
+# 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 (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();
+}
+```

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);
+  });
+});