Crayon SDK - Master Reference

Purpose

Operate like a master with the Thesys generative-UI stack. This skill captures every hard-won lesson from a production implementation (Orbiter Frontend's copilot - 2,400+ LOC orchestrator, 18 templates, voice integration, full conversation persistence) plus the official ecosystem (Crayon, C1, OpenUI).

When to Use This Skill

Activates when working with:

• @crayonai/react-core, @crayonai/react-ui, or the new @openuidev/* packages
• Thesys C1 GenUI API (the OpenAI-compatible streaming endpoint that emits Crayon responses)
• CrayonChat, useThreadManager, useThreadState, useThreadActions, processStreamedMessage
• Building AI chat UIs with SSE streaming + interactive response templates
• Voice composers, portal-mounted UI inside Crayon's composer
• Migrating from @crayonai/* to the open-source @openuidev/* packages
• Any prompt mentioning C1, Crayon, CrayonChat, OpenUI, GenUI, generative UI, response template, thread manager

Rubric

criteria:
  - name: reference_completeness
    kind: deterministic
    check: "All major sections present: Crayon Ecosystem (3 products), Quick Start standalone example, thread manager flow, SSE streaming, templates, portal mounting patterns, persistence, migration notes."
  - name: example_parses
    kind: deterministic
    check: "The Quick Start code example (useThreadManager + CrayonChat) is syntactically valid and demonstrates processStreamedMessage integration."
  - name: agent_ecosystem_clarity
    kind: judge
    check: "When a future agent encounters @crayonai/* or @openuidev/*, they understand the three products (Crayon SDK, C1, OpenUI), when to use each, and how to migrate. The distinction Crayon vs C1 vs OpenUI is unambiguous."

The Crayon Ecosystem (April 2026)

There are three related products. They are easy to confuse.

Practical guidance:

• Existing project on @crayonai/*? Stay there. Everything in this skill applies. The packages still work and are still maintained.
• New project? Try @openuidev/* first via npx @openuidev/cli@latest create. The token efficiency is real and the API surface is cleaner.
• Want a hosted backend? C1 is the managed offering - point your client at c1.thesys.dev like an OpenAI endpoint.

The rest of this skill uses @crayonai/* examples because that's the production-tested surface. See ecosystem.md for OpenUI migration notes and side-by-side comparison.

Quick Start (Standalone Chat)

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

import { templates } from "./templates";              // [{ name, Component }]
import { processMessage } from "./process-message";   // returns Promise<Response> with SSE body

function Copilot({ conversationId }: { conversationId: number | null }) {
  const threadManager = useThreadManager({
    threadId: conversationId ? String(conversationId) : null,
    shouldResetThreadState: true,
    loadThread: async (threadId) => loadFromBackend(threadId),
    onProcessMessage: async ({ message, threadManager: tm, abortController }) => {
      tm.appendMessages({ ...message, id: crypto.randomUUID() });
      const response = await processMessage({
        threadId: String(conversationId ?? "new"),
        messages: [...tm.messages, { ...message, id: crypto.randomUUID() }],
        abortController,
      });
      await processStreamedMessage({
        response,
        createMessage: tm.appendMessages,
        updateMessage: tm.updateMessage,
        deleteMessage: tm.deleteMessage,
      });
      return [];
    },
    responseTemplates: templates,
  });

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

Three things to internalize:

1. Thread ID is always a string (String(numericId) if your backend uses numbers - passing a number silently breaks).
2. onProcessMessage MUST call processStreamedMessage and return [] - not the messages.
3. Bump the key prop to force-remount when switching conversations or modes.

Navigation Guide

Core Architecture

┌─────────────────────────────────────────────────────┐
│  CrayonChat (UI shell)                              │
│   ├── threadManager  ← from useThreadManager        │
│   │    ├── messages[]      UserMessage|Assistant…   │
│   │    ├── isRunning       true while streaming     │
│   │    ├── appendMessages, updateMessage, …         │
│   │    └── onProcessMessage(message, tm, abort)     │
│   │         └── return processStreamedMessage(…)    │
│   │                                                 │
│   ├── responseTemplates[]  { name, Component }      │
│   │    └── inside Component:                        │
│   │         useThreadState() / useThreadActions()   │
│   │                                                 │
│   └── SSE wire format:                              │
│        event: text\ndata: <word>\n\n                │
│        event: tpl \ndata: {name,templateProps}\n\n  │
└─────────────────────────────────────────────────────┘

Key Types (from @crayonai/react-core)

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">;

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

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

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

SSE Wire Format (memorize this)

event: text
data: Hello

event: text
data:  world

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

Rules:

• Two events: text (streamed prose) and tpl (instant template card).
• Word-by-word text events with a leading space gives the smoothest typing illusion.
• Paragraph break = a text event with empty data lines.
• Template data is a single JSON line. The name MUST exactly match a registered template - no fallback, no fuzzy match.
• Content-Type: text/event-stream, Cache-Control: no-cache, no-transform.
• Always close the stream controller or isRunning stays true forever.

Quick Reference

Imports

// 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 } from "@crayonai/react-ui";
import "@crayonai/react-ui/styles/index.css";

CrayonChat shapes

Inside a template component

const { processMessage } = useThreadActions();   // send a follow-up user message
const { isRunning, messages } = useThreadState(); // read live state reactively

Cross-tree communication: window.dispatchEvent(new CustomEvent("…", { detail })) (see templates.md).

Programmatic send into the composer: native-setter DOM hack (see dom-patterns.md).

Resource Files

ecosystem.md

Crayon SDK vs C1 vs OpenUI. Package matrix. Migration notes. Token-efficiency claims (67% fewer tokens than JSON for OpenUI Lang v0.5).

sse-streaming.md

Exact SSE format. Word-by-word chunking. Response normalization for the four shapes backends actually return (string, array, stringified JSON, {response: …}). Abort handling. Conversation history extraction.

thread-management.md

useThreadManager configuration. loadThread with raw-JSON recovery. Conversation persistence write paths. useThreadListManager for sidebar threads. processMessage (CrayonChat prop) vs onProcessMessage (hook param).

templates.md

Template registry. useThreadActions / useThreadState. Interactive cards. Cross-tree CustomEvent pattern. Blocked-templates-during-interview filter. Mode-aware template logic.

component-api.md

Every CrayonChat prop. Welcome message variants. Conversation starters. Artifacts (side panel). Available @crayonai/react-ui primitives (Accordion, Carousel, Charts, CodeBlock, DatePicker, Steps, Tabs, etc.).

styling.md

Wrapper-class scoping. The complete list of overridable .crayon-shell-* selectors (composer, thread, message bubbles, conversation starters, send button). Card-entrance animation. Dark theme via CSS variables. Inline-style strategy for templates.

voice-integration.md

Portal-mounting a voice mic into .crayon-shell-thread-composer__input-wrapper. MutationObserver re-injection so it survives Crayon rerenders. Dual-provider TTS (Gradium primary, ElevenLabs streaming fallback). STT with Web Speech API + MediaRecorder fallback. The stoppingRef flag pattern. Selectors here are Crayon-only - for OpenUI (@openuidev/*), see openui-dom-map.md; the submit button lives one level deeper, inside __action-bar.

openui-dom-map.md

Canonical parent-child DOM map for @openuidev/react-ui v0.11.4 (snappy-os's stack). Every .openui-shell-* class with its real children, generated from a source-of-truth read of the installed dist. Covers composer (in-thread + welcome), thread messages, welcome screen, sidebar, IconButton. Insertion-point cookbook ("where do I put a mic", "what's the submit button's parent") and anti-patterns ported from real production crashes - including the inputWrapper.insertBefore(node, submit) NotFoundError that took down the React tree on 2026-04-28.

dom-patterns.md

Native HTMLTextAreaElement.value setter to bypass React's controlled-input. Selector chains for the composer input + send button. Enter-key fallback. Live-transcription class toggle on the input wrapper.

production-patterns.md

Refs vs state in async callbacks. Conversation creation race guard. Mode state machines (default / leverage / outcome / meeting). Suggestion request polling with visibility pause. Auto-generated dispatch-confirmation fallback. Quick-action markers. FLIP avatar-travel animations between picker and chat.

gotchas.md

14 hard-won lessons with why they bite: remount flashing, history building strips templates, response format inconsistency, raw-JSON in stored content, useThreadActions outside CrayonChat throws, return-type mismatch between processMessage and onProcessMessage, threadId must be string, shouldResetThreadState timing, card filtering during interviews, programmatic message injection, exact template-name matching, stream controller MUST close, multi-template ordering, AbortError silencing.

Related Skills

• crayonchat - The previous version of this skill. Superseded by this one but still installed.
• seymour-papert - Design philosophy that pairs well with Crayon's progressive-disclosure card stream.
• emil-design-eng - UI polish principles for animating cards.

Skill Status: COMPLETE Line Count: ~290 Progressive Disclosure: 10 resource files Reference Implementation: orbiter-frontend/src/features/copilot/ (2,400+ LOC, 18 templates, voice, persistence)

crayon-sdk - loader

Per-turn reference for the Thesys generative-UI stack. Full skill: state/skills/crayon-sdk/SKILL.md. Prose-only with 11 sub-files; eval=auto-shape. Reference resource for chat integrations.

Critical Rules

1. Prose-only with 11 sub-files, no lib/sidecar. "RUN THIS" briefs → [SKIPPED]. Deliverable is guidance + reference docs, not executable code.
2. Three ecosystems (April 2026). Crayon SDK (@crayonai/react-core|react-ui, MIT, production-tested) | C1 (hosted GenUI API at c1.thesys.dev, managed) | OpenUI (@openuidev/*, open-source, 67% token efficiency). Existing projects: stay on Crayon. New projects: try OpenUI. Want hosted: use C1.
3. Quick Start traps. (a) threadId MUST be string (String(numericId) if needed). (b) onProcessMessage MUST call processStreamedMessage() and return []. (c) Bump key prop on <CrayonChat> to force-remount on conversation switch.
4. SSE wire format. Two events: text (streamed prose, word-by-word with leading space) and tpl (one JSON line {name, templateProps}). Template name EXACTLY matches registered name. Headers: Content-Type: text/event-stream, Cache-Control: no-cache, no-transform. Always close stream controller. Paragraph breaks = empty data lines.
5. 8 navigation domains → 8 sub-files. Ecosystems→ecosystem.md | SSE→sse-streaming.md | useThreadManager→thread-management.md | Templates→templates.md | CrayonChat props→component-api.md | CSS→styling.md | Voice→voice-integration.md | OpenUI DOM→openui-dom-map.md.
6. OpenUI DOM: __submit-button is GRANDCHILD of __input-wrapper. Parent is __action-bar. insertBefore(node, submit) throws NotFoundError if submit not in its direct children → React tree teardown. Read openui-dom-map.md FIRST before any DOM mutation.
7. Theme three-leg cream-canvas. (1) MutationObserver on documentElement.dataset.theme → React state. (2) theme={{mode: themeMode}} prop to <FullScreen>. (3) Deep lightTheme/darkTheme objects to ThemeProvider (not just mode).
8. chat-inject serialization: MIN_COMMIT_FRAMES=3 rAFs. OpenUI IconButton has NO disabled attr → :not(:disabled) matches stale closure first rAF. Serialize concurrent injects OR thread-id-scope. Endpoints: chat-inject-push (text + auto-submit) | chat-inject-control (button click only). POLL_MS=3000.
9. Shape emitters run on failure path. When dispatch backend fails (spawn ENOENT), shapes stop unless emitter fires regardless. Check dispatch-chat.ndjson for spawn errors before diagnosing missing card.
10. KNOWN_COMPONENTS gate must include all shapes. Missing entries silently filter LLM-emitted blocks. Add new shapes to server gate before claiming live.

Commands

This skill is prose-only reference with 11 sub-files. No HTTP endpoints.

Sub-files: ecosystem.md | sse-streaming.md | thread-management.md | templates.md | component-api.md | styling.md | voice-integration.md | openui-dom-map.md | dom-patterns.md | production-patterns.md | gotchas.md

Reference impl: ~/projects/orbiter-frontend/src/features/copilot/ (2400+ LOC, 18 templates, voice, persistence)

Self-Test

• [ ] Know 3 ecosystems + when to choose each (Crayon/C1/OpenUI)
• [ ] Know Quick Start traps: threadId string, return [], bump key
• [ ] Know SSE: text + tpl events, exact name match, always close
• [ ] Know 8 navigation domains + sub-file refs
• [ ] Know OpenUI DOM trap: submit GRANDCHILD, read openui-dom-map.md
• [ ] Know 3-leg cream-canvas: MutationObserver + theme prop + deep tokens
• [ ] Know chat-inject: MIN_COMMIT_FRAMES=3, serialize, POLL_MS=3000
• [ ] Know shape emitters run failure path
• [ ] Know KNOWN_COMPONENTS gate must include all shapes
• [ ] Know 11 sub-files are reference, not generated

<!-- footer-injection-point -->