---
name: crayonchat
description: CrayonChat (@crayonai/react-core, @crayonai/react-ui) integration guide. AI chat UI framework for building conversational interfaces with SSE streaming, custom response templates, thread management, and interactive cards. Covers CrayonChat component props, useThreadManager, useThreadState, useThreadActions, processStreamedMessage, template registration, conversation starters, welcome messages, and custom loading indicators.
---

# CrayonChat Integration Guide

## Purpose

Battle-tested patterns for building AI chat interfaces with `@crayonai/react-core` and `@crayonai/react-ui`.

## When to Use This Skill

Activates when:
- Working with CrayonChat, `@crayonai/react-core`, or `@crayonai/react-ui`
- Building AI chat interfaces with SSE streaming
- Creating custom response templates for chat
- Managing conversation threads with `useThreadManager`
- Implementing `processMessage` callbacks

---

## Quick Start

```tsx
import { useThreadManager, processStreamedMessage } from "@crayonai/react-core";
import { CrayonChat } from "@crayonai/react-ui";
import "@crayonai/react-ui/styles/index.css";

const templates = [
  { name: "my_card", Component: MyCard },
];

function Chat() {
  const threadManager = useThreadManager({
    threadId: null,
    loadThread: async (id) => [],
    onProcessMessage: async ({ message, threadManager: tm, abortController }) => {
      const response = await myProcessMessage({
        threadId: "new",
        messages: tm.messages.concat({ ...message, id: crypto.randomUUID() }),
        abortController,
      });
      await processStreamedMessage({
        response,
        createMessage: tm.appendMessages,
        updateMessage: tm.updateMessage,
        deleteMessage: tm.deleteMessage,
      });
      return [];
    },
    responseTemplates: templates,
  });

  return (
    <CrayonChat
      type="standalone"
      threadManager={threadManager}
      responseTemplates={templates}
      agentName="Assistant"
      logoUrl="/logo.svg"
      scrollVariant="always"
      messageLoadingComponent={() => <MyLoader />}
      welcomeMessage={{ title: "Hello", description: "How can I help?" }}
      conversationStarters={{
        variant: "long",
        options: [{ displayText: "Get started", prompt: "Help me get started" }],
      }}
    />
  );
}
```

---

## Navigation Guide

| Need to...                        | Read this                                |
|-----------------------------------|------------------------------------------|
| Understand CrayonChat props       | [component-api.md](component-api.md)     |
| Build SSE streaming               | [sse-streaming.md](sse-streaming.md)     |
| Create custom templates           | [templates.md](templates.md)             |
| Manage threads & state            | [thread-management.md](thread-management.md) |
| Style & theme the chat            | [styling.md](styling.md)                 |
| Avoid common pitfalls             | [gotchas.md](gotchas.md)                 |

---

## Core Architecture

```
CrayonChat (UI shell)
  ├── threadManager (state + actions)
  │   ├── messages[]  ← UserMessage | AssistantMessage
  │   ├── isRunning   ← true while streaming
  │   └── processMessage() → SSE Response → processStreamedMessage()
  ├── responseTemplates[] ← { name, Component }
  │   └── Templates use useThreadActions() / useThreadState()
  └── SSE stream format:
      event: text\ndata: word\n\n        ← streamed text
      event: tpl\ndata: {name, templateProps}\n\n  ← template card
```

---

## Key Types (from @crayonai/react-core)

```typescript
// Messages
type UserMessage = { id: string; role: "user"; type: "prompt"; message?: string; context?: JSONValue[] };
type AssistantMessage = {
  id: string; role: "assistant"; context?: JSONValue[];
  message?: ({ type: "text"; text: string } | { type: "template"; name: string; templateProps: any })[];
};
type Message = UserMessage | AssistantMessage;
type CreateMessage = Omit<UserMessage, "id">;

// Templates
interface ResponseTemplate { name: string; Component: React.ComponentType<any> }

// Thread state
type ThreadState = {
  isRunning?: boolean;
  isLoadingMessages?: boolean;
  messages: Message[];
  error: Error | null | undefined;
  responseTemplates: Record<string, ResponseTemplate>;
  isInitialized: boolean;
};

// Thread actions
type ThreadActions = {
  processMessage: (message: CreateMessage) => Promise<void>;
  appendMessages: (...messages: Message[]) => void;
  updateMessage: (message: Message) => void;
  deleteMessage: (messageId: string) => void;
  onCancel: () => void;
  setMessages: (messages: Message[]) => void;
};
```

---

## Quick Reference

**Imports:**
```typescript
// Core
import { useThreadManager, useThreadState, useThreadActions, processStreamedMessage } from "@crayonai/react-core";
import type { Message, UserMessage, AssistantMessage, CreateMessage, ResponseTemplate, ThreadManager } from "@crayonai/react-core";

// UI
import { CrayonChat, CheckBoxGroup, CheckBoxItem } from "@crayonai/react-ui";
import "@crayonai/react-ui/styles/index.css";
```

**CrayonChat types:** `"standalone"` | `"copilot"` | `"bottom-tray"`

**Scroll variants:** `"always"` (auto-scroll) is the safe default

**Template component hooks:**
- `useThreadActions()` → `{ processMessage }` — send follow-up messages from cards
- `useThreadState()` → `{ isRunning, messages }` — read current state in templates

---

## Resource Files

### [component-api.md](component-api.md)
Complete CrayonChat component props, welcome message config, conversation starters

### [sse-streaming.md](sse-streaming.md)
SSE stream format, processMessage callback, building Response objects, text chunking

### [templates.md](templates.md)
Template registry, creating custom templates, template props, interactive cards

### [thread-management.md](thread-management.md)
useThreadManager hook, loading threads, processing messages, conversation persistence

### [styling.md](styling.md)
CSS scoping, theme integration, card animations, dark mode patterns

### [gotchas.md](gotchas.md)
Hard-won lessons: remount flashing, history building, response format parsing, state machine quirks

---

**Skill Status**: COMPLETE
**Line Count**: ~140
**Progressive Disclosure**: 6 resource files

# CrayonChat Component API

## CrayonChat Props

```typescript
type CrayonChatProps = {
  // ── Identity ──
  type?: "standalone" | "copilot" | "bottom-tray";  // Layout mode
  logoUrl?: string;          // Agent avatar (SVG data URL or image URL)
  agentName?: string;        // Displayed in header

  // ── State management (use ONE approach) ──
  // Option A: Simple — pass processMessage directly
  processMessage?: (params: {
    threadId: string;
    messages: Message[];
    abortController: AbortController;
  }) => Promise<Response>;

  // Option B: Full control — use threadManager from useThreadManager
  threadManager?: ThreadManager;

  // ── Thread list (optional sidebar) ──
  threadListManager?: ThreadListManager;

  // ── Templates ──
  responseTemplates?: ResponseTemplate[];  // { name, Component }[]
  messageLoadingComponent?: () => React.ReactNode;

  // ── Streaming (optional override) ──
  processStreamedMessage?: typeof processStreamedMessage;

  // ── UI ──
  scrollVariant?: "always" | "smart" | "manual";
  theme?: ThemeProps;
  disableThemeProvider?: boolean;

  // ── Welcome screen ──
  welcomeMessage?: WelcomeMessageConfig;
  conversationStarters?: ConversationStartersConfig;

  // ── Artifacts (side panel) ──
  isArtifactActive?: boolean;
  renderArtifact?: () => React.ReactNode;

  // ── Message updates ──
  onUpdateMessage?: (props: { message: Message }) => void;
  createThread?: (message: CreateMessage) => Promise<Thread>;
};
```

## Welcome Message

```typescript
type WelcomeMessageConfig =
  | React.ComponentType<any>  // Custom component
  | {
      title?: string;
      description?: string;
      image?: { url: string } | ReactNode;  // URL or custom JSX
    };
```

**Example with custom image:**
```tsx
<CrayonChat
  welcomeMessage={{
    title: "Hey there",
    description: "What can I help with?",
    image: <MyCustomIcon className="w-16 h-16" />,
  }}
/>
```

## Conversation Starters

Shown when the thread is empty. Clicking sends `prompt` as a user message.

```typescript
interface ConversationStartersConfig {
  variant?: "short" | "long";  // "short" = pill buttons, "long" = vertical list
  options: Array<{
    displayText: string;  // Button label
    prompt: string;       // Sent as user message
    icon?: ReactNode;     // Optional icon
  }>;
}
```

**Example:**
```tsx
<CrayonChat
  conversationStarters={{
    variant: "long",
    options: [
      {
        displayText: "Help me prepare for a meeting",
        prompt: "I need help preparing for a meeting",
        icon: <CalendarIcon />,
      },
      {
        displayText: "Find opportunities in my network",
        prompt: "Show me leverage opportunities",
        icon: <NetworkIcon />,
      },
    ],
  }}
/>
```

## Bottom Tray Mode

For embedded chat that slides up from the bottom:

```tsx
<CrayonChat
  type="bottom-tray"
  isOpen={isOpen}
  onOpenChange={setIsOpen}
  defaultOpen={false}
  // ...other props
/>
```

## Type Choices

| Type | Use case |
|------|----------|
| `standalone` | Full-page or dialog chat |
| `copilot` | Sidebar assistant |
| `bottom-tray` | Embedded slide-up panel |

## Available UI Components from @crayonai/react-ui

Beyond CrayonChat, these are available for building templates:

- `CheckBoxGroup` / `CheckBoxItem` — Checkbox lists
- `RadioGroup` / `RadioItem` — Radio buttons
- `Accordion` — Collapsible sections
- `Button` / `Buttons` — Action buttons
- `Card` / `CardHeader` — Card layouts
- `Carousel` — Image/card carousels
- `Charts` — Data visualization
- `CodeBlock` — Syntax-highlighted code
- `DatePicker` — Date selection
- `Image` / `ImageGallery` — Media display
- `Input` / `TextArea` / `FormControl` — Form inputs
- `ListBlock` / `ListItem` — Structured lists
- `MarkDownRenderer` — Markdown content
- `Select` — Dropdown selection
- `Steps` — Step indicators
- `Table` — Data tables
- `Tabs` — Tab navigation
- `Tag` / `TagBlock` — Labels/badges

# Gotchas & Hard-Won Lessons

## 1. Component Remounts Cause Flashing

**Problem:** CrayonChat's internal state machine can mount/unmount your `messageLoadingComponent` multiple times rapidly during streaming, causing visual flashing.

**Solution:** Never use CSS animations with delays or React state for visibility in loading components. Render the component immediately with full opacity:

```tsx
// BAD — flashes on each remount
function Loader() {
  const [ready, setReady] = useState(false);
  return <div style={{ opacity: ready ? 1 : 0 }}>...</div>;
}

// GOOD — instant, no state
function Loader() {
  const { isRunning } = useThreadState();
  if (!isRunning) return null;
  return <div>Loading...</div>;
}
```

## 2. History Building: Templates Are Stripped

**Problem:** When building conversation history from `messages` array, assistant messages contain template objects that the backend can't process.

**Solution:** Extract only text content, skip template objects:

```typescript
const history = messages
  .filter(m => m.role === "user" || m.role === "assistant")
  .slice(-10)
  .map(m => {
    if (m.role === "user") return { role: "user", content: m.message || "" };
    const text = Array.isArray(m.message)
      ? m.message.filter(p => p.type === "text").map(p => p.text).join(" ")
      : "";
    return { role: "assistant", content: text };
  })
  .filter(m => m.content);
```

## 3. Response Format Inconsistency

**Problem:** Backend can return responses in 3+ formats: string, array, nested JSON, object with `response` field. If you don't handle all, some responses break.

**Solution:** Always normalize before streaming:

```typescript
function normalize(raw: unknown): ResponseItem[] {
  if (typeof raw === "string") {
    try { return normalize(JSON.parse(raw)); } catch { return [{ type: "text", text: raw }]; }
  }
  if (Array.isArray(raw)) return raw;
  if (raw && typeof raw === "object" && "response" in raw) return normalize((raw as any).response);
  return [{ type: "text", text: String(raw) }];
}
```

## 4. Raw JSON in Stored Messages

**Problem:** Some messages get stored with raw JSON as the `content` string (e.g., `'{"text":"hello"}'` instead of `"hello"`). When loading saved conversations, these render as raw JSON.

**Solution:** In `loadThread`, try to parse and recover:

```typescript
let text = msg.content;
try {
  const parsed = JSON.parse(text);
  if (typeof parsed === "string") text = parsed;
  else if (parsed.text) text = parsed.text;
} catch { /* not JSON, use as-is */ }
```

## 5. useThreadActions Only Works Inside CrayonChat

**Problem:** `useThreadActions()` and `useThreadState()` require the CrayonChat context. Calling them outside the CrayonChat tree throws.

**Solution:** Template components are rendered inside CrayonChat, so they work. For parent-child communication, use CustomEvents (see templates.md).

## 6. processMessage Return Type Mismatch

**Problem:** When using `processMessage` as a CrayonChat prop, it must return `Promise<Response>`. When using `onProcessMessage` in `useThreadManager`, it must return `Promise<Message[]>`.

**Solution:**
- CrayonChat prop: Return a `Response` with SSE body
- useThreadManager: Call `processStreamedMessage()` yourself, then return `[]`

## 7. Thread ID Must Be String

**Problem:** CrayonChat expects `threadId` as `string | null`. If your backend uses numeric IDs, passing a number silently breaks.

**Solution:** Always `String(numericId)`:

```typescript
const threadManager = useThreadManager({
  threadId: conversationId ? String(conversationId) : null,
  // ...
});
```

## 8. shouldResetThreadState Timing

**Problem:** When `threadId` changes, messages don't clear unless `shouldResetThreadState: true`. But this can also clear messages during initial load if not careful.

**Solution:** Set `shouldResetThreadState: true` and use `key` prop for clean remounts:

```tsx
<CrayonChat
  key={`chat-${chatKey.current}`}
  threadManager={threadManager}
/>
```

Increment `chatKey.current` whenever switching conversations.

## 9. Card Filtering During Interviews

**Problem:** During multi-step interview flows, the backend may return cards prematurely. These cards trigger side effects or confuse the user.

**Solution:** Filter blocked templates during interview state:

```typescript
const blockedDuringInterview = ["contact_card", "summary_card", "result_card"];

const items = normalizedResponse.filter(item => {
  if (isInterviewing && item.name && blockedDuringInterview.includes(item.name)) {
    return false;
  }
  return true;
});
```

## 10. Auto-Sending Programmatic Messages

**Problem:** CrayonChat doesn't expose an API to programmatically send a message. You can't just call `processMessage()` externally to inject a user message.

**Solution:** Use DOM manipulation to inject text and trigger the send button:

```typescript
function autoSendMessage(text: string) {
  const textarea = document.querySelector(".crayon-input textarea") as HTMLTextAreaElement;
  if (!textarea) return;

  // Use native setter to trigger React's onChange
  const nativeSetter = Object.getOwnPropertyDescriptor(
    HTMLTextAreaElement.prototype, "value"
  )?.set;
  nativeSetter?.call(textarea, text);
  textarea.dispatchEvent(new Event("input", { bubbles: true }));

  // Wait for send button to enable, then click
  setTimeout(() => {
    const sendBtn = document.querySelector(".crayon-send-button") as HTMLButtonElement;
    sendBtn?.click();
  }, 100);
}
```

This is a hack but the only reliable way currently.

## 11. Template Name Must Match Exactly

**Problem:** The `name` in the SSE `tpl` event must exactly match a registered template name. No fuzzy matching, no fallbacks.

**Solution:** Keep a constant for template names:

```typescript
export const TEMPLATE_NAMES = {
  CONTACT_CARD: "contact_card",
  BUTTON_GROUP: "button_group",
  // ...
} as const;
```

Use these constants in both the template registry and the backend response builder.

## 12. SSE Stream Must Close Properly

**Problem:** If the ReadableStream controller isn't closed, CrayonChat stays in `isRunning: true` forever.

**Solution:** Always call `controller.close()` at the end of the stream:

```typescript
const stream = new ReadableStream({
  start(controller) {
    // ... enqueue events ...
    controller.close();  // CRITICAL
  },
});
```

## 13. Multiple Templates in One Response

**Problem:** CrayonChat can render multiple templates in a single assistant message, but text + template ordering matters.

**Solution:** Stream text first, then templates. Each `tpl` event creates a new template block in the message:

```
event: text
data: Here are your results:

event: tpl
data: {"name":"contact_card","templateProps":{"name":"Jane"}}

event: tpl
data: {"name":"contact_card","templateProps":{"name":"John"}}
```

## 14. AbortController vs Error Handling

**Problem:** When the user clicks "Stop" (cancel), the AbortController fires and can throw `AbortError`. If unhandled, this shows as an error in the UI.

**Solution:** Catch abort errors silently:

```typescript
try {
  const response = await fetch(url, { signal: abortController.signal });
  // ...
} catch (error) {
  if (error instanceof DOMException && error.name === "AbortError") {
    return; // User cancelled, not an error
  }
  throw error;
}
```

# SSE Streaming

## How CrayonChat Consumes Streams

CrayonChat expects `processMessage` to return a `Response` object with `text/event-stream` content-type. The stream uses Server-Sent Events (SSE) format.

## SSE Event Format

Two event types:

```
event: text
data: Hello

event: text
data: world

event: tpl
data: {"name":"contact_card","templateProps":{"name":"John","company":"Acme"}}
```

- `event: text` — Streamed text (word by word for typing effect)
- `event: tpl` — Template card (single JSON event, rendered immediately)

## Building the processMessage Callback

The callback receives `{ threadId, messages, abortController }` and must return a `Response` with an SSE body.

### Minimal Example

```typescript
async function processMessage({
  threadId,
  messages,
  abortController,
}: {
  threadId: string;
  messages: Message[];
  abortController: AbortController;
}): Promise<Response> {
  // 1. Extract user message
  const lastMessage = messages.filter(m => m.role === "user").pop();
  const userText = typeof lastMessage?.message === "string"
    ? lastMessage.message
    : "";

  // 2. Call your backend
  const apiResponse = await fetch("/api/chat", {
    method: "POST",
    body: JSON.stringify({ message: userText }),
    signal: abortController.signal,
  });
  const data = await apiResponse.json();

  // 3. Build SSE stream
  const stream = new ReadableStream({
    start(controller) {
      const encoder = new TextEncoder();

      for (const item of data.response) {
        if (item.type === "text") {
          // Stream text word by word for typing effect
          const words = item.text.split(" ");
          for (const word of words) {
            controller.enqueue(encoder.encode(`event: text\ndata: ${word} \n\n`));
          }
        } else if (item.name) {
          // Template card — single event
          controller.enqueue(
            encoder.encode(
              `event: tpl\ndata: ${JSON.stringify({ name: item.name, templateProps: item.templateProps })}\n\n`
            )
          );
        }
      }
      controller.close();
    },
  });

  return new Response(stream, {
    headers: {
      "Content-Type": "text/event-stream",
      "Cache-Control": "no-cache, no-transform",
      Connection: "keep-alive",
    },
  });
}
```

## Text Chunking Strategy

Stream text **word by word** for a natural typing effect:

```typescript
const words = text.split(" ");
for (const word of words) {
  controller.enqueue(encoder.encode(`event: text\ndata: ${word} \n\n`));
}
```

The trailing space after each word is important — CrayonChat concatenates the `data` values.

## Response Format Handling

Backend responses come in many shapes. Normalize before streaming:

```typescript
function normalizeResponse(raw: unknown): Array<{ type: "text"; text: string } | { name: string; templateProps: Record<string, unknown> }> {
  // String → wrap in text item
  if (typeof raw === "string") return [{ type: "text", text: raw }];

  // Already an array → use as-is
  if (Array.isArray(raw)) return raw;

  // Object with response field → unwrap
  if (raw && typeof raw === "object" && "response" in raw) {
    return normalizeResponse((raw as any).response);
  }

  // Nested JSON string → parse and retry
  if (typeof raw === "string") {
    try { return normalizeResponse(JSON.parse(raw)); } catch { /* fall through */ }
  }

  return [{ type: "text", text: String(raw) }];
}
```

## Using processStreamedMessage (Thread Manager Pattern)

When using `useThreadManager`, the `onProcessMessage` callback handles streaming differently:

```typescript
onProcessMessage: async ({ message, threadManager: tm, abortController }) => {
  // Append user message first
  tm.appendMessages({ ...message, id: crypto.randomUUID() });

  // Get SSE response
  const response = await processMessage({
    threadId: tm.messages[0]?.id || "new",
    messages: [...tm.messages, { ...message, id: crypto.randomUUID() }],
    abortController,
  });

  // Let CrayonChat handle the stream parsing
  const { processStreamedMessage } = await import("@crayonai/react-core");
  await processStreamedMessage({
    response,
    createMessage: tm.appendMessages,
    updateMessage: tm.updateMessage,
    deleteMessage: tm.deleteMessage,
  });

  return [];
}
```

`processStreamedMessage` reads the SSE stream and:
- Creates a new assistant message on first `text` or `tpl` event
- Updates the message as more events arrive
- Handles cleanup on stream end

## Building Conversation History

When sending history to the backend, extract only text content from previous messages:

```typescript
function buildHistory(messages: Message[]) {
  return messages
    .filter(m => m.role === "user" || m.role === "assistant")
    .slice(-10) // Limit to last 10 for payload size
    .map(m => {
      if (m.role === "user") {
        return { role: "user", content: typeof m.message === "string" ? m.message : "" };
      }
      // Extract text from assistant messages, skip templates
      const textParts = Array.isArray(m.message)
        ? m.message.filter(p => p.type === "text").map(p => p.text).join(" ")
        : "";
      return { role: "assistant", content: textParts };
    })
    .filter(m => m.content);
}
```

## Abort Handling

The `abortController` signal should be passed to fetch calls:

```typescript
const response = await fetch(url, {
  signal: abortController.signal,
  // ...
});
```

When the user clicks "Stop", CrayonChat aborts the controller, cancelling the fetch.

# Styling & Theming

## Required CSS Import

Always import the base CrayonChat styles:

```typescript
import "@crayonai/react-ui/styles/index.css";
```

## Scoping Custom Styles

Wrap CrayonChat in a scoped class to prevent CSS leaks:

```tsx
<div className="my-chat-wrapper">
  <CrayonChat ... />
</div>
```

```css
/* Scope ALL custom styles under the wrapper */
.my-chat-wrapper .crayon-chat-container {
  /* overrides */
}
```

## Theme Integration with CSS Variables

CrayonChat supports theming via its `ThemeProvider`. You can also override via CSS:

```css
.my-chat-wrapper {
  /* Map your app's design tokens to CrayonChat */
  --crayon-bg: var(--background);
  --crayon-fg: var(--foreground);
  --crayon-primary: var(--primary);
  --crayon-muted: var(--muted-foreground);
}
```

## Card Entrance Animation

Standard animation for template cards:

```css
@keyframes cardEntrance {
  from {
    opacity: 0;
    transform: translateY(14px) scale(0.985);
  }
  to {
    opacity: 1;
    transform: translateY(0) scale(1);
  }
}

.chat-card-enter {
  animation: cardEntrance 0.45s cubic-bezier(0.16, 1, 0.3, 1) both;
}
```

Apply `chat-card-enter` class to all template card root elements.

## Dark Theme Card Pattern

```css
.my-card {
  background: rgba(0, 0, 0, 0.2);
  border: 1px solid rgba(255, 255, 255, 0.08);
  border-radius: 16px;
  padding: 20px;
  color: rgba(255, 255, 255, 0.92);
  backdrop-filter: blur(12px);
}

.my-card:hover {
  border-color: rgba(255, 255, 255, 0.14);
}
```

## Button Patterns

### Gradient Action Button
```css
.action-button {
  background: linear-gradient(135deg, #6366f1 0%, #a855f7 100%);
  color: white;
  border: none;
  border-radius: 10px;
  padding: 10px 18px;
  font-weight: 600;
  cursor: pointer;
  transition: opacity 0.2s, transform 0.15s;
}

.action-button:hover {
  opacity: 0.92;
  transform: translateY(-1px);
}

.action-button:disabled {
  opacity: 0.5;
  cursor: not-allowed;
  transform: none;
}
```

### Ghost Button
```css
.ghost-button {
  background: rgba(255, 255, 255, 0.06);
  color: rgba(255, 255, 255, 0.7);
  border: 1px solid rgba(255, 255, 255, 0.1);
  border-radius: 8px;
  padding: 8px 14px;
}
```

## Useful Animations

```css
/* Pulsing glow */
@keyframes glowPulse {
  0%, 100% { box-shadow: 0 0 8px rgba(99, 102, 241, 0.3); }
  50% { box-shadow: 0 0 16px rgba(99, 102, 241, 0.6); }
}

/* Shimmer loading */
@keyframes shimmer {
  0% { background-position: -200% 0; }
  100% { background-position: 200% 0; }
}
.shimmer {
  background: linear-gradient(90deg, transparent 25%, rgba(255,255,255,0.08) 50%, transparent 75%);
  background-size: 200% 100%;
  animation: shimmer 1.5s infinite;
}

/* Dot pulse (loading dots) */
@keyframes dotPulse {
  0%, 80%, 100% { transform: scale(0.6); opacity: 0.4; }
  40% { transform: scale(1); opacity: 1; }
}
```

## Hiding CrayonChat Default Elements

Override specific internal elements:

```css
/* Hide default loading */
.my-chat-wrapper .crayon-message-loading {
  display: none;
}

/* Custom scrollbar */
.my-chat-wrapper .crayon-messages-container::-webkit-scrollbar {
  width: 6px;
}
.my-chat-wrapper .crayon-messages-container::-webkit-scrollbar-thumb {
  background: rgba(255, 255, 255, 0.15);
  border-radius: 3px;
}
```

## Inline Styles in Templates

For template components, prefer inline styles (they're isolated components):

```tsx
function MyCard({ title }: { title: string }) {
  return (
    <div
      className="chat-card-enter"
      style={{
        background: "rgba(0,0,0,0.2)",
        border: "1px solid rgba(255,255,255,0.08)",
        borderRadius: 16,
        padding: 20,
        fontFamily: "Inter, -apple-system, sans-serif",
      }}
    >
      <h4 style={{ margin: 0, fontSize: 15, fontWeight: 600 }}>{title}</h4>
    </div>
  );
}
```

## CrayonChat Built-in Theme

```tsx
import { themePresets } from "@crayonai/react-ui";

<CrayonChat
  theme={themePresets.dark}  // or themePresets.light
  // Or custom:
  theme={{
    colors: {
      primary: "#6366f1",
      background: "#0a0a0f",
      foreground: "#ffffff",
    },
  }}
/>
```

# Custom Response Templates

## Template Registration

Templates are registered as an array of `{ name, Component }` objects:

```typescript
import type { ResponseTemplate } from "@crayonai/react-core";

export const templates: ResponseTemplate[] = [
  { name: "contact_card", Component: ContactCard },
  { name: "button_group", Component: ButtonGroup },
  { name: "error_message", Component: ErrorMessage },
];
```

Pass this array to both `useThreadManager` and `<CrayonChat>`:

```tsx
const threadManager = useThreadManager({
  responseTemplates: templates,
  // ...
});

<CrayonChat
  threadManager={threadManager}
  responseTemplates={templates}  // Must match
/>
```

## Template Component Pattern

Templates receive `templateProps` from the SSE stream as their props:

```typescript
interface MyCardProps {
  title: string;
  description?: string;
  items?: Array<{ label: string; value: string }>;
}

export function MyCard(props: MyCardProps) {
  const { title, description, items = [] } = props;

  return (
    <div className="my-card chat-card-enter">
      <h3>{title}</h3>
      {description && <p>{description}</p>}
      {items.map(item => (
        <div key={item.value}>{item.label}: {item.value}</div>
      ))}
    </div>
  );
}
```

## Interactive Templates (Follow-up Messages)

Use `useThreadActions()` to send follow-up user messages from within a template:

```typescript
import { useThreadActions } from "@crayonai/react-core";

export function ButtonGroup({ question, options }: ButtonGroupProps) {
  const { processMessage } = useThreadActions();
  const [selected, setSelected] = useState<string | null>(null);

  const handleSelect = async (option: { label: string; value: string }) => {
    setSelected(option.value);
    try {
      await processMessage({
        role: "user",
        type: "prompt",
        message: option.label,
      });
    } catch (error) {
      console.error("Failed to process:", error);
      setSelected(null);
    }
  };

  return (
    <div className="button-group chat-card-enter">
      <p>{question}</p>
      {options?.map(opt => (
        <button
          key={opt.value}
          disabled={!!selected}
          onClick={() => handleSelect(opt)}
          style={{ opacity: selected && selected !== opt.value ? 0.5 : 1 }}
        >
          {opt.emoji && <span>{opt.emoji}</span>}
          {opt.label}
        </button>
      ))}
    </div>
  );
}
```

## Reading Thread State in Templates

Use `useThreadState()` for reactive access to thread state:

```typescript
import { useThreadState } from "@crayonai/react-core";

export function LoadingIndicator() {
  const { isRunning, messages } = useThreadState();

  if (!isRunning) return null;

  const lastUserMsg = messages
    .filter(m => m.role === "user")
    .pop();

  return <div>Thinking about: {lastUserMsg?.message}...</div>;
}
```

## Communicating with Parent App

Templates can't receive props from the parent (only from `templateProps`). Use events:

```typescript
// In template — dispatch event
function handleAction() {
  window.dispatchEvent(new CustomEvent("my-feature:action", {
    detail: { personId: 123, action: "activate" },
  }));
}

// In parent app — listen
useEffect(() => {
  const handler = (e: CustomEvent) => {
    console.log(e.detail); // { personId: 123, action: "activate" }
  };
  window.addEventListener("my-feature:action", handler);
  return () => window.removeEventListener("my-feature:action", handler);
}, []);
```

## Template Props from Backend

The backend sends template data in SSE `tpl` events:

```
event: tpl
data: {"name":"contact_card","templateProps":{"name":"Jane","company":"Acme","role":"CEO"}}
```

CrayonChat matches `name` to the registered template and passes `templateProps` as the component's props.

## Proven Template Patterns

### Card with Actions
```typescript
interface ActionCardProps {
  title: string;
  description: string;
  actions: Array<{ label: string; action: string; emoji?: string }>;
}

function ActionCard({ title, description, actions }: ActionCardProps) {
  const { processMessage } = useThreadActions();
  return (
    <div className="chat-card-enter" style={{ /* card styles */ }}>
      <h4>{title}</h4>
      <p>{description}</p>
      <div style={{ display: "flex", gap: 8 }}>
        {actions.map(a => (
          <button key={a.action} onClick={() =>
            processMessage({ role: "user", type: "prompt", message: a.label })
          }>
            {a.emoji} {a.label}
          </button>
        ))}
      </div>
    </div>
  );
}
```

### Question with "I Don't Know"
```typescript
function QuestionCard({ title, buttons, allowDontKnow = true }: QuestionCardProps) {
  const { processMessage } = useThreadActions();
  return (
    <div className="chat-card-enter">
      <h4>{title}</h4>
      {buttons.map(b => (
        <button key={b.value} onClick={() =>
          processMessage({ role: "user", type: "prompt", message: b.label })
        }>
          {b.label}
        </button>
      ))}
      {allowDontKnow && (
        <button onClick={() =>
          processMessage({ role: "user", type: "prompt", message: "I don't know" })
        }>
          I'm not sure
        </button>
      )}
    </div>
  );
}
```

### Dispatch Confirmation (Submit + Side Effects)
```typescript
function DispatchCard({ summary, label }: DispatchCardProps) {
  const [dispatched, setDispatched] = useState(false);

  const handleDispatch = () => {
    setDispatched(true);
    window.dispatchEvent(new CustomEvent("chat:ready-to-dispatch", {
      detail: { summary },
    }));
  };

  return (
    <div className="chat-card-enter">
      <p>{summary}</p>
      <button disabled={dispatched} onClick={handleDispatch}>
        {dispatched ? "Dispatched" : label || "Launch"}
      </button>
    </div>
  );
}
```

## Template Naming Convention

Use `snake_case` for template names. These are matched exactly against the SSE `name` field:

| Name | Purpose |
|------|---------|
| `contact_card` | Rich person display |
| `button_group` | Multiple choice selection |
| `question_card` | Interview question with options |
| `error_message` | Dismissible error |
| `submit_button` | Dispatch trigger |
| `loading_indicator` | Custom loading state |
| `dispatch_confirmation` | Inline dispatch with summary |

# Thread Management

## useThreadManager Hook

The primary hook for managing conversation state:

```typescript
import { useThreadManager, processStreamedMessage } from "@crayonai/react-core";
import type { Message, ThreadManager } from "@crayonai/react-core";

const threadManager = useThreadManager({
  threadId: conversationId ? String(conversationId) : null,
  shouldResetThreadState: true,

  loadThread: async (threadId: string) => {
    const messages = await getMessages(Number(threadId));
    return messages.map(transformToMessage);
  },

  onProcessMessage: async ({ message, threadManager: tm, abortController }) => {
    // 1. Append user message to thread
    tm.appendMessages({ ...message, id: crypto.randomUUID() });

    // 2. Get SSE response from your processMessage function
    const response = await processMessage({
      threadId: tm.messages[0]?.id || "new",
      messages: [...tm.messages, { ...message, id: crypto.randomUUID() }],
      abortController,
    });

    // 3. Let CrayonChat handle streaming
    await processStreamedMessage({
      response,
      createMessage: tm.appendMessages,
      updateMessage: tm.updateMessage,
      deleteMessage: tm.deleteMessage,
    });

    return [];
  },

  responseTemplates: templates,
});
```

## UseThreadManagerParams

```typescript
type UseThreadManagerParams = {
  threadId: string | null;           // null = new conversation
  shouldResetThreadState?: boolean;  // Clear messages when threadId changes
  loadThread: (threadId: string) => Promise<Message[]>;
  onProcessMessage: (props: {
    message: CreateMessage;
    threadManager: ThreadManager;
    abortController: AbortController;
  }) => Promise<Message[]>;
  onUpdateMessage?: (props: { message: Message }) => void;
  responseTemplates: ResponseTemplate[];
};
```

## ThreadManager Methods

```typescript
// Returned by useThreadManager
type ThreadManager = {
  // State
  isRunning?: boolean;           // True while processing
  isLoadingMessages?: boolean;   // True while loading thread
  messages: Message[];           // All messages in thread
  error: Error | null;           // Last error
  isInitialized: boolean;        // Ready to show UI

  // Actions
  processMessage: (msg: CreateMessage) => Promise<void>;
  appendMessages: (...msgs: Message[]) => void;
  updateMessage: (msg: Message) => void;
  deleteMessage: (id: string) => void;
  setMessages: (msgs: Message[]) => void;
  onCancel: () => void;          // Cancel current processing
};
```

## Loading Saved Conversations

Transform backend messages to CrayonChat `Message` format:

```typescript
async function loadThread(threadId: string): Promise<Message[]> {
  const backendMessages = await getMessages(Number(threadId));

  return backendMessages.map((msg) => {
    if (msg.role === "user") {
      return {
        id: String(msg.id),
        role: "user" as const,
        type: "prompt" as const,
        message: msg.content,
      };
    }

    // Assistant messages may have templates
    const messageParts: AssistantMessage["message"] = [];

    if (msg.template_name && msg.template_props) {
      messageParts.push({
        type: "template",
        name: msg.template_name,
        templateProps: msg.template_props,
      });
    } else if (msg.content) {
      // Handle raw JSON that was accidentally stored
      let text = msg.content;
      try {
        const parsed = JSON.parse(text);
        if (typeof parsed === "string") text = parsed;
      } catch { /* not JSON, use as-is */ }

      messageParts.push({ type: "text", text });
    }

    return {
      id: String(msg.id),
      role: "assistant" as const,
      message: messageParts,
    };
  });
}
```

## Conversation Persistence Pattern

Save messages to backend after each exchange:

```typescript
// In processMessage callback, after streaming completes:

// 1. Save user message
await addMessage(conversationId, {
  role: "user",
  content: userText,
});

// 2. Save assistant response
// Extract text and template parts from the streamed response
for (const item of responseItems) {
  if (item.type === "text") {
    await addMessage(conversationId, {
      role: "assistant",
      content: item.text,
    });
  } else if (item.name) {
    await addMessage(conversationId, {
      role: "assistant",
      content: `[${item.name}]`,  // Marker text
      template_name: item.name,
      template_props: item.templateProps,
    });
  }
}
```

## Thread Switching

When switching conversations, increment a key to force CrayonChat to remount:

```typescript
const chatKey = useRef(0);

const switchConversation = (newId: number) => {
  setConversationId(newId);
  chatKey.current++;  // Force remount
};

<CrayonChat
  key={`chat-${chatKey.current}`}
  threadManager={threadManager}
  // ...
/>
```

## Thread List Management (Optional)

For a sidebar of previous conversations:

```typescript
import { useThreadListManager } from "@crayonai/react-core";

const threadListManager = useThreadListManager({
  loadThreadList: async () => {
    const conversations = await getConversations();
    return conversations.map(c => ({
      threadId: String(c.id),
      title: c.title,
      createdAt: new Date(c.created_at * 1000),
    }));
  },
  loadThread: async (threadId) => loadThread(threadId),
  onProcessMessage: async (props) => { /* same as above */ },
  createThread: async (message) => {
    const conv = await createConversation({ title: message.message || "New" });
    return { threadId: String(conv.id), title: conv.title, createdAt: new Date() };
  },
  deleteThread: async (threadId) => {
    await deleteConversation(Number(threadId));
  },
  responseTemplates: templates,
});

<CrayonChat
  threadListManager={threadListManager}
  threadManager={threadListManager.threadManager}  // Derived
  // ...
/>
```

## Important: processMessage vs onProcessMessage

| Feature | `processMessage` (CrayonChat prop) | `onProcessMessage` (useThreadManager) |
|---------|-----------------------------------|------------------------------------|
| Returns | `Promise<Response>` (SSE stream) | `Promise<Message[]>` |
| Streaming | Handled by CrayonChat internally | You call `processStreamedMessage()` |
| State control | Less control | Full control via `threadManager` |
| Use when | Simple integrations | Need conversation persistence, custom state |