Protocol and Types

This is the CONTRACT layer of ToonUI.

If you do not understand these types, you are integrating blindly.

`ToonProtocol`

createToonProtocol() returns a ToonProtocol.

It exposes:

prompt
rules
catalog
events
messages

const toon = createToonProtocol();

`ToonRuntime`

A runtime extends the protocol with execution helpers:

components
parse
validate
extractBlocks

That means a runtime is effectively:

protocol contract
parsing tools
validation tools
renderer-facing component registry

`ToonRules`

rules is the compact machine-usable representation of the language.

It includes:

components
buttonVariants
badgeVariants
alertVariants
confirmVariants
fieldTypes
chartTypes

This is useful when composing prompts programmatically.

`ToonDocument`

The parser returns a ToonDocument:

type ToonDocument = {
  type: 'document';
  body: ToonNode[];
}

The body array is the AST root.

`ToonBlock`

extractBlocks() identifies fenced ToonUI blocks inside larger markdown content.

Each block includes:

raw
language
start
end
complete

This is useful when parsing model output that mixes prose and UI.

`ValidationIssue`

Each validation issue contains:

code
message
optional line
optional column

This makes syntax and semantic failures traceable back to the original source.

`ValidationResult`

Validation returns:

{
  ok: boolean;
  errors: ValidationIssue[];
  warnings: ValidationIssue[];
}

In practice, the most important field is ok, but the real debugging value is in errors.

`ReplyPayload`

Used for button-style interactions.

type ReplyPayload = {
  kind: 'ui_reply';
  eventId: string;
  source: 'button';
  value: string;
  component: 'button';
  line?: number;
  context?: Record<string, SubmitValue>;
}

Important meaning:

value is the app-facing user intent
eventId uniquely identifies the interaction
context lets you attach extra structured metadata when needed

`SubmitPayload`

Used for form-style interactions.

type SubmitPayload = {
  kind: 'ui_submit';
  eventId: string;
  source: 'form';
  intent: string;
  formTitle: string;
  values: Record<string, SubmitValue>;
  line?: number;
}

Important meaning:

intent identifies the host-level action
formTitle is human-facing context
values is the normalized submitted data

`ToonModelMessage`

Use this when the next step is feeding the interaction back into the model loop.

It includes:

role
kind
content
displayContent
payload

`ToonUIMessage`

Use this when the next step is appending a message into UI/chat state.

It includes:

id
role
parts
metadata

This shape is intentionally friendly to message-based chat interfaces.

Type aliases worth knowing

ToonChatMessage = model-facing interaction message
ToonChatUIMessage = UI-facing interaction message
ToonInteractionPayload = ReplyPayload | SubmitPayload

Practical takeaway

If you remember only one thing, remember this:

events create interaction payloads
messages convert those payloads for the next host step

On this page