UI Protocol - Charm Docs

Overview

Charm Store uses a Server-Driven UI architecture. Agents are required to return either spec-compliant JSON or standard Markdown. Outputs are rendered into native UI components automatically by the Charm Universal Renderer.

Standard Markdown

Supports direct string streaming with rich formatting, including titles, lists, code blocks, bold/italic text, and links.

Structured JSON (Explicit Rendering)

The preferred way to trigger rich UI is to explicitly declare a _charm_render_type in your JSON output. This bypasses heuristic guessing and guarantees consistent, robust rendering.

Chart Components

// 1. Bar Chart
{
  "_charm_render_type": "bar_chart",
  "title": "Revenue by Region",
  "data": [
    { "name": "NA", "value": 125000 },
    { "name": "EU", "value": 85000 }
  ]
}

// 2. Line Chart (Sparkline style)
{
  "_charm_render_type": "line_chart",
  "title": "User Growth",
  "data": [
    { "name": "Mon", "value": 10 },
    { "name": "Tue", "value": 25 },
    { "name": "Wed", "value": 40 }
  ]
}

// 3. Pie Chart
{
  "_charm_render_type": "pie_chart",
  "title": "Traffic Sources",
  "data": [
    { "name": "Organic", "value": 45 },
    { "name": "Direct", "value": 30 }
  ]
}

Data Grid

Renders a clean, scrollable table. Automatically extracts column headers from the keys of the first row object.

{
  "_charm_render_type": "data_grid",
  "title": "Recent Transactions",
  "rows": [
    { "id": "TX-1", "amount": "$450", "status": "Paid" },
    { "id": "TX-2", "amount": "$120", "status": "Pending" }
  ]
}

Metric Card

Renders a dashboard-style grid of metric cards with optional trend indicators.

{
  "_charm_render_type": "metric_card",
  "title": "Performance Dashboard",
  "metrics": [
    { "label": "Active Users", "value": 1204, "change": 12, "unit": "users" },
    { "label": "Churn Rate", "value": "2.4", "change": -0.5, "unit": "%" }
  ]
}

Structured JSON (Heuristic Rendering)

If an explicit _charm_render_type is not provided, the Charm Store will attempt to infer the best UI representation based on the presence of certain keys.

Viral Card

Purpose-built for sharing and revealing underlying mechanisms.

// Trigger condition: JSON must include "type": "viral_card"

{
  "type": "viral_card",
  "content": {
    "cover_mode": true,        // Whether to enable the “reveal” cover mode
    "cover_data": {
      "title": "CONFIDENTIAL", // Title displayed on the cover (e.g. SECRET, TOP SECRET)
      "subtitle": "VIBE CHECK",// Subtitle displayed on the cover
      "cover_image": "https://..." // (Optional) Background image for the cover
    },
    "image_url": "https://...",    // Final result image shown after reveal (or when downloaded)
    "description": "This is your analysis result...", // Text description displayed below the card
    "action": {
      "type": "smart_share_trigger", // Fixed value, triggers native share/download logic
      "label": "REVEAL & SHARE"      // Button label
    },
    "metadata": {
      "sticker_link": "https://..."  // (Optional) Link automatically copied to clipboard when sharing (e.g. IG “Add Yours”)
    }
  }
}

Universal Timeline

Render a sequence of events as a vertical timeline.

// Trigger condition (heuristic detection):
// Return an Array where each object contains any of the following keywords: date, time, year, timestamp

[
  {
    "date": "2024-01-15",
    "event": "Project Kickoff",
    "description": "Initial meeting with stakeholders.",
    "location": "Taipei HQ"
  },
  {
    "date": "2024-02-01",
    "event": "Alpha Release",
    "status": "success" // Will automatically render a green check icon
  }
]

// Special style keywords:

// Content containing "error", "fail", "conflict" → Red warning style
// Content containing "success", "complete", "solve" → Green success style
// Content containing "announce", "tweet", "report" → Blue informational style

Comparison View

Render multiple objects as a responsive comparison table.

// Trigger condition (heuristic detection):
// Return an Array where the object keys contain comparison-related keywords: vs, competitor, price, feature, target

[
  {
    "Feature": "AI Model",
    "Charm_OS": "GPT-4o + Claude 3.5",
    "Competitor_X": "GPT-3.5"
  },
  {
    "Feature": "Viral Sharing",
    "Charm_OS": "Native Support",
    "Competitor_X": "None"
  }
]

// This array will be rendered as a responsive comparison table

Optimization Diff

Display the differences between content before and after optimization, suitable for copywriting revision or code refactoring agents.

// Trigger condition (heuristic detection):
// Return an Object containing keys related to both "original" and "optimized" content

// Original-related keys: original, before, weakness
// Optimized-related keys: optimized, after, rewrite

{
  "section": "Instagram Bio Rewrite",
  "original_content": "I like coffee and coding.",      // Original content
  "optimized_version": "Fueled by caffeine.\nBuilding the future of AI.\nCheck my vibe below.",  // Optimized content
  "reason": "Added emojis and line breaks for better readability." // Explanation for the optimization
}

Universal Article

Suitable for long-form content, automatically extracts headings and optimizes formatting.

// Trigger condition (heuristic detection):
// Return an Object containing a title (or headline) and content (or body)
// The content length must exceed 150 characters

{
  "title": "The Future of AI Agents",          // Title or headline
  "author": "Charm Intelligence",            // Optional metadata
  "body": "Artificial Intelligence is evolving from chatbots to autonomous agents...",  // Main content (long-form, >150 characters)
  "key_takeaways": [                          // Array will be automatically rendered as a list
    "Agents act autonomously",
    "Memory is crucial"
  ]
}

Custom UI (HTML & SVG via Markdown)

The Charm Universal Renderer is built on top of Markdown. The renderer natively supports HTML and SVG elements, safely sanitized via DOMPurify. This enables agents to deliver custom UI by returning valid HTML or SVG strings inside their markdown response. For code examples on how to dynamically stream HTML or SVG strings from your agent, see the How to Render Rich UI guide.

Security Note: The Charm Store frontend uses DOMPurify to strip <script>, <iframe>, and other potentially malicious vectors. Supported capabilities are constrained to static HTML, CSS classes (Tailwind is supported on the Store), and SVGs.

Best Practices

Explicit is better than implicit: Use _charm_render_type whenever possible instead of relying on heuristics.
Keep JSON flat: Minimize deep nesting. The Universal Renderer performs best with flat objects.
Use standard keywords: When using heuristic detection, using standard English field names (e.g., date instead of d_time) ensures the correct UI is triggered.
Mix in Markdown: You can still use Markdown syntax in JSON string values. The renderer will parse it correctly.

​Overview

​Standard Markdown

​Structured JSON (Explicit Rendering)

​Chart Components

​Data Grid

​Metric Card

​Structured JSON (Heuristic Rendering)

​Viral Card

​Universal Timeline

​Comparison View

​Optimization Diff

​Universal Article

​Custom UI (HTML & SVG via Markdown)

​Best Practices