Debug Invalid ToonUI

When ToonUI is invalid, do NOT guess.

Parse it. Validate it. Read the exact failure.

The debugging loop

const blocks = toon.extractBlocks(content);

for (const block of blocks) {
  const ast = toon.parse(block.raw);
  const result = toon.validate(ast);

  if (!result.ok) {
    console.error(result.errors);
  }
}

The most common failure classes

1. Missing required field

Example:

form "Create product":
  button primary "Create" submit

Why it fails:

• forms need at least one field

2. Invalid nesting

Example:

list "Products":
  text "Not allowed here"

Why it fails:

• list can only contain item

3. Invalid syntax

Example:

button primary "Create product" "start-create-product"

Why it fails:

• button actions must use reply="..." or submit

4. Invalid strict node shape

Example:

alert "Low stock"

Why it fails:

• alert needs variant + title + : + children

5. Unsafe content

Example:

text "<script>alert('xss')</script>"

Why it fails:

• raw script-like HTML is not allowed in text

Table debugging rule

If a table behaves strangely, quote every column and every cell.

Bad:

row: May 09, $ 8,155.35, Completed

Better:

row: "May 09", "$ 8,155.35", "Completed"

Field debugging rule

If a field default value is behaving strangely, check value="...".

Correct:

field active switch "Active" value="true"
field score slider "Score" min=0 max=10 step=1 value="7"

Recommended workflow in CI

Use parsing + validation for:

• fixture tests
• golden examples
• generated output checks
• debugging prompt regressions

Read next

1. Errors and Validation
2. Complete Syntax Reference
3. Build a Real ToonUI Flow