Create a new A2UI surface (UI container) for rendering components.

A surface is the top-level container for A2UI components. You must create a surface before adding components to it.

Args:

• surface_id (string): Unique identifier for the surface

• catalog_id (string, optional): Component catalog to use

Returns: JSON message confirming surface creation

Example: Create a surface for a booking form: { "surface_id": "booking_form" }

Add or update components on an A2UI surface.

Components are defined as a flat list with ID references. The component tree is built using the 'children' property.

IMPORTANT: You must include a component with id='root' as the entry point.

Available components:

• Column: Vertical layout container (children: string[])

• Row: Horizontal layout container (children: string[])

• Card: Card container with optional title (children: string[], title?: string)

• Text: Text display (text: string, style?: {...})

• Button: Clickable button (label: string, variant?: 'primary'|'secondary'|'outlined', action?: string)

• TextField: Input field (label: string, placeholder?: string, value?: string)

• Image: Image display (src: string, alt?: string)

• Divider: Horizontal line

• Progress: Progress bar (value?: number 0-100, indeterminate?: boolean)

Example - Simple form: { "surface_id": "my_form", "components": [ { "id": "root", "component": "Column", "children": ["title", "name_field", "submit_btn"] }, { "id": "title", "component": "Text", "text": "Contact Form", "style": { "fontSize": 24, "fontWeight": "bold" } }, { "id": "name_field", "component": "TextField", "label": "Your Name", "placeholder": "Enter name..." }, { "id": "submit_btn", "component": "Button", "label": "Submit", "variant": "primary" } ] }

Update the data model of an A2UI surface.

The data model provides dynamic values that components can bind to using dataBinding.

Operations:

• replace: Completely replace the data model

• merge: Shallow merge with existing data

• remove: Delete specified keys

Example: { "surface_id": "booking_form", "operation": "merge", "data": { "userName": "John Doe", "selectedDate": "2025-01-15", "guestCount": 4 } }

Open a live preview of all A2UI surfaces in the browser.

The preview auto-updates when you make changes using other a2ui_* tools.

Returns the preview URL that you can share or open manually.

Clear all A2UI surfaces and reset the state.

Get the current state of all A2UI surfaces and their components.

Poll for UI events from the browser (button clicks, text input, etc.).

Events are consumed when polled (unless peek=true). Use this to react to user interactions.

Event types:

• tap: Button was clicked (payload: { action?: string })

• change: TextField value changed (payload: { value: string, dataBinding?: string })

Example response: [ { "eventId": "abc-123", "surfaceId": "my_form", "componentId": "submit_btn", "eventType": "tap", "timestamp": 1234567890, "payload": { "action": "submit" } } ]

To enable events on components, set onTap=true (Button) or onChange=true (TextField).