Message Reference

Message Types

beginRendering

Signals the client to start rendering a surface.

Schema:

{
  beginRendering: {
    surfaceId: string; // Required: Unique surface identifier
    root: string;      // Required: The ID of the root component to render
    catalogId?: string; // Optional: URL of component catalog
    styles?: object;    // Optional: Styling information
  }
}

Example:

{ "beginRendering": { "surfaceId": "main", "root": "root-component" } }

surfaceUpdate

Defines or updates UI components.

Schema:

{
  surfaceUpdate: {
    surfaceId: string; // Required: Target surface
    components: Array<{ // Required: List of components
      id: string; // Required: Component ID
      component: { // Required: Wrapper for component data
        [ComponentType]: { // Required: Exactly one component type
          ...properties // Component-specific properties
        }
      }
    }>
  }
}

Usage Notes:

• Components form an adjacency list (flat structure).
• Sending a component with an existing ID updates it.
• Components can be added incrementally.

Example:

{
  "surfaceUpdate": {
    "surfaceId": "main",
    "components": [
      {
        "id": "greeting",
        "component": {
          "Text": {
            "text": {"literalString": "Hello, World!"},
            "usageHint": "h1"
          }
        }
      }
    ]
  }
}

dataModelUpdate

Updates the application state (data model) for a surface.

Schema:

{
  dataModelUpdate: {
    surfaceId: string; // Required: Target surface
    path?: string;     // Optional: Path to a location in the model
    contents: Array<{  // Required: Data entries
      key: string;
      valueString?: string;
      valueNumber?: number;
      valueBoolean?: boolean;
      valueMap?: Array<{...}>;
    }>
  }
}

Usage Notes:

• The contents array is LLM-friendly, avoiding generic value inference issues.
• Supports granular updates via path.

deleteSurface

Removes a UI surface and its data.

Schema:

{
  deleteSurface: {
    surfaceId: string; // Required: Surface to delete
  }
}

Example:

{ "deleteSurface": { "surfaceId": "modal" } }

Message Ordering

Recommended Order:

1. surfaceUpdate (Define components)
2. dataModelUpdate (Populate data)
3. beginRendering (Show UI)
4. Subsequent surfaceUpdate / dataModelUpdate (Interactive updates)
5. deleteSurface (Cleanup)