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

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-chat'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 working with the Thesys generative-UI stack. Full skill: state/skills/crayon-sdk/SKILL.md (290 lines, 11 sub-files). Prose-only; no lib, no sidecar.

Critical Rules

1. Prose-only skill with 11 sub-files. No state/lib/crayon-sdk.ts, no state/bin/crayon-sdk/. Drain "RUN THIS" briefs → emit [SKIPPED] action_kind=stale-brief-already-shipped.
2. Three ecosystems (April 2026). (1) Crayon SDK (@crayonai/react-core, @crayonai/react-ui) - original, MIT, production-tested. (2) C1 - hosted GenUI API (c1.thesys.dev), closed/managed. (3) OpenUI (@openuidev/*) - open-source rewrite, 67% token efficiency gain, March 2026 launch. Practical rule: Existing project on Crayon? Stay there. New project? Try OpenUI first. Want hosted backend? Use C1.
3. Quick Start: three non-negotiable traps. (a) threadId MUST be a string - String(numericId) or it silently breaks. (b) onProcessMessage MUST call processStreamedMessage and return [], NOT the messages. (c) Bump key prop on <CrayonChat> / <FullScreen> to force-remount on conversation/mode switch.
4. SSE wire format is fixed. Two events: text (streamed prose, word-by-word with leading space) and tpl (one JSON line {name, templateProps}). Template name EXACTLY matches registered template name. Headers: Content-Type: text/event-stream, Cache-Control: no-cache, no-transform. Always close stream controller or isRunning stays true. Paragraph breaks = empty data lines.
5. Navigation: 8 domains map to sub-files. Crayon vs C1 vs OpenUI → ecosystem.md | SSE construction → sse-streaming.md | useThreadManager + persistence → thread-management.md | Templates + follow-ups → templates.md | CrayonChat props → component-api.md | CSS overrides → styling.md | Voice mic portal → voice-integration.md | OpenUI DOM map → openui-dom-map.md.
6. OpenUI DOM trap: __submit-button is GRANDCHILD of __input-wrapper. Parent is __action-bar. inputWrapper.insertBefore(node, submit) throws NotFoundError and tears down React tree. Always insert relative to actual parentElement. Read openui-dom-map.md BEFORE any DOM mutation.
7. Theme three-leg cream-canvas: all three must land. (1) MutationObserver on documentElement.dataset.theme → mirror to React state. (2) Pass theme={{ mode: themeMode }} prop to <FullScreen>. (3) Provide deep lightTheme/darkTheme objects to ThemeProvider (not just mode). Token shape in @openuidev/react-ui/dist/components/ThemeProvider/types.d.ts.
8. OpenUI Lang args are POSITIONAL ONLY. Comp(arg0, arg1) not name=value. Prop order in defineComponent({ props: z.object({…}) }) is call order. Server-side translator MUST emit positional.
9. chat-inject serialization: MIN_COMMIT_FRAMES=3 rAFs before click. OpenUI IconButton has NO disabled attribute - :not(:disabled) matches on first rAF with stale closure + empty text. Serialize concurrent injects OR thread-id-scope. Two endpoints: chat-inject-push (text + auto-submit) vs chat-inject-control (button click only). CHAT_INJECT_POLL_MS = 3000ms (not 500ms).
10. Shape emitters MUST run on failure path. When claude-code backend hits spawn ENOENT, shapes stop cold unless emitter runs regardless. Check dispatch-chat.ndjson for spawn errors first before diagnosing missing card.
11. KNOWN_COMPONENTS gate MUST include all shapes. Missing entries silently filter LLM-emitted blocks. Add new shapes to the server gate before claiming "landed."
12. ComparisonTable: dispatch-card missing. Server emitter OK, parser exists, but DISPATCH_REGISTRY key absent. Must add before shape is live.
13. Sister-WIP collisions on 6 files. web/src/genui-library.tsx, dispatch-card.tsx, App.tsx, welcome-content.tsx, styles.css, state/bin/head-screen/server.ts. git status -- <path> BEFORE first Edit. Wait ≤120s. TOCTOU escape: git apply --cached or git stash/pop. Do NOT orphan-flush uncommitted WIP.
14. Window global augmentation in bridge.ts ONLY. TS2669 fires on duplicate declare global { interface Window {...} }. Extend existing block in web/src/bridge.ts only. Run cd web && npx tsc --noEmit not just vite build (vite silent-passes TS errors).
15. Vite manualChunks split: genui-library + vendor-react + vendor-openui. Bundle was 2.4MB pre-split. Check chunk impact when adding large deps.
16. No rgba() in styles.css or components. Use CSS vars only. Card-enter keyframe: opacity + transform ONLY. Blur filter is a regression.
17. head-screen launch tolerates EADDRINUSE. Diagnose: lsof -nP -iTCP:3147 -sTCP:LISTEN. Don't kill -9 blind.
18. Chip-popover row icons need BOTH icon prop AND class. Editing mode-chips.tsx alone is a no-op. Must extend chip-popover.tsx + add chip-popover-row-icon class.
19. ErrorToast surfaces bridge failures. web/src/components/error-toast.tsx. Wire new bridge failure paths through it, not console.error.
20. View fade transitions: 200ms. Inherit .view-enter class for new routes. Don't write a new transition.
21. Welcome starters: check duplicates. No ROTATING_FOURTH[n] collision with fixed slots.
22. Crayon shape data producers: LinkedIn, Email, Slack have NONE. Server Callout fallback on empty queue. Don't add chat-surface guard.
23. OpenUI visual polish requires :where(.openui-*) overrides in styles.css. Never inline styles. The override convention: :where(.openui-card), :where(.openui-table), :where(.openui-callout) etc. Author-level CSS wins over :where() specificity - this is intentional. Current polish targets: Cards (gradient depth + 2-layer shadow), Tables (rounded corners + banded rows), Callouts (accent left bar), Tags (pill shape), Buttons (hover lift). If generative UI looks plain/unstyled, check styles.css for missing :where(.openui-*) rules BEFORE changing the component.
24. Screenshot rendered Lang BEFORE and AFTER any styles.css change affecting OpenUI. See impeccable CRITICAL rule. peekaboo screenshot --app "Snappy Chat" --window-index 1 --output /tmp/before.png, dispatch a Lang-heavy intent, capture after.png, compare. Do not ship a styles.css change that affects OpenUI without visual verification.

Commands

| ui dashboard | state/skills/crayon-sdk/resources/ui.openui |

Self-Test

• [ ] Know 3 ecosystems and when to choose each?
• [ ] Know 3 Quick Start traps: threadId string, return [], bump key?
• [ ] Know SSE format: text + tpl events, exact name match, always close stream?
• [ ] Know 8 navigation domains and their sub-files?
• [ ] Know OpenUI DOM trap: submit is GRANDCHILD, read openui-dom-map.md first?
• [ ] 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 on failure path?
• [ ] Know KNOWN_COMPONENTS gate must include all shapes?
• [ ] Know sister-WIP on 6 files: git status ≤120s wait, TOCTOU escape?
• [ ] Know Window augmentation in bridge.ts ONLY?
• [ ] Know type-check truth: tsc --noEmit not vite?
• [ ] Know ComparisonTable DISPATCH_REGISTRY gap?
• [ ] Know Crayon shape data gaps: LinkedIn, Email, Slack?

<!-- kernel-ok: historical attribution for the PID-loader pattern. -->

Self-correcting loader (PID feedback)

This is the rule that makes loaders learn. Ported from snappy-kernel, where it demonstrably worked: the snappy-dom-cartographer skill mapped Skool admin UI once, every later ship-agent inherited the full map for free.

Before you finish, do two things:

1. Fix gaps (P - proportional). MANDATORY. If this loader didn't cover your case - if you had to read another file, run an undocumented command, work around a wrong selector, or discover a quirk - you MUST attempt an Edit to this AGENTS.md before you log.

• Default action: edit this file. Surgical. Add the missing line, table

row, or code example where it belongs. No restructuring.

• Only LOGGED is allowed when: the fix needs >10 lines, spans multiple

files, or requires a structural rewrite. In that case the state/regen/drain.sh queue picks it up asynchronously.

• "I didn't have time" / "it's minor" / "the next agent will figure it out"

are NOT valid reasons. Minor gaps compound - that's the whole point of this loop.

• Concrete example of a valid P-fix: discover agent-browser screenshot

takes path positionally not as --output <path>. One line in a table. Edit it in. Do not just log it.

• The goal: the next agent never has to leave the loader.

2. Log the result.

echo "[$(date -u +%FT%TZ)] crayon-sdk: <what was missing or fixed> [FIXED|LOGGED] action_kind=<kind>" >> state/log/loader-feedback.log

• FIXED = you patched this loader inline (P-fix).
• LOGGED = too large for inline; the regen drain will rewrite from scratch.
• action_kind: shape-ok | skill-ran | loader-rewritten | pattern-elevated

Do not skip this. Every agent run must leave the system better than it found it. The loader is the setpoint; you are the sensor; the gap is the error signal; closing the gap is the correction.

OpenUI Resource

• Skill-owned OpenUI Lang resource: state/skills/crayon-sdk/resources/ui.openui. Read it before rendering or editing this skill's generated component surface.
• Treat this resource as a first-class artifact of the skill, not a generic chat response. Improve it when the skill's user-facing output needs to become richer.
• System resources compose OpenUI primitives and inherit SnappyChat tokens. Use ui_contract: branded in SKILL.md only for deliberate platform or client visuals.