A2uiComponentScope

@Composable
fun <T : Any> A2uiComponentProperties.bind(property: DynamicA2uiProperty<T>): T?

Evaluates a dynamic property against the surface's reactive data model and subscribes the component to future updates.

This method resolves various payload types sent by the agent:

• Literal values.

• Data model bindings via JSON pointer paths (e.g., {"path": "/user/name"}).

• Local client-side function executions (e.g., {"call": "formatString", ...}).

If the agent provides an invalid payload or a type mismatch occurs, this method returns null to prevent crashes and automatically dispatches a runtime error back to the agent, facilitating an explicit feedback loop for self-correction. During progressive rendering (when the required data has not yet arrived to the data model), this will also evaluate to null.

@Composable
fun A2uiComponentProperties.bindChildReferences(
    property: ChildListA2uiProperty
): List<A2uiComponentReference>?

Resolves a structural list of child component references based on the provided property and subscribes the component to future updates.

This method supports both static and dynamic component hierarchies as defined by the protocol:

• Static Lists: Direct arrays of component IDs.

• Dynamic Templates: An object defining a componentId and a data path (e.g., {"path": "/items", "componentId": "item_template"}). The list will reactively expand or contract based on the underlying data model array, injecting the correct relative base data paths into the resulting component references.

Note: This method only resolves the references. It does not observe the state of the child components themselves. The returned component references can be used to call observeA2uiComponentState to observe and render the children. This separation allows for lazy observation of child states in lazy layouts like LazyColumn.

If the agent hallucinates a malformed structure or points a template to a non-list data node, an error is automatically dispatched to the agent for self-correction and null is returned.

@Composable
fun <T : Any> A2uiComponentProperties.bindUpdater(
    property: DynamicA2uiProperty<T>
): ((T?) -> Unit)?

Establishes a two-way data binding by providing a stable callback that updates the underlying data model for the given dynamic property.

This method is useful for interactive components (like text fields or checkboxes) that must write local user input back to the surface's reactive data model. The component may pass null to the returned lambda to erase the data in the data model for the specified property.

If the agent binds the property to a writable JSON pointer path (e.g., {"path": "/form/name"}), this returns a lambda that mutates the model at that path. If the agent instead provides a read-only payload (such as a literal string or a function call), this method returns null. Components should utilize a null result to degrade into a read-only or disabled state, preventing user input that cannot be synchronized.

fun dispatchAction(actionPayload: Map<String, Any?>): Unit

Dispatches an A2UI action (such as a server event or local function call) as defined in the component's properties.

@Composable
fun observeA2uiComponentState(id: String, baseDataPath: String? = null): A2uiComponentState

Resolves the current A2uiComponentState of a component by its unique ID and subscribes for future updates.

fun reportError(exception: A2uiException): Unit

Reports a runtime error that occurred during the evaluation or rendering of this component.

@Composable
fun A2uiComponentScope.ProvideActionInterceptor(
    onIntercept: (actionPayload: Map<String, Any?>) -> Boolean,
    content: @Composable () -> Unit
): Unit

Intercepts actions dispatched by descendant components within content.

Useful for container components (such as modals) that handle actions from child triggers (like buttons or cards) to update local UI state instead of dispatching to the surface.

Interceptor Chaining

Interceptors chain from the innermost (deepest child) to the outermost (ancestor) in the composition tree:

• If onIntercept returns true, the action is consumed immediately; outer interceptors and the underlying surface will not receive the action.

• If onIntercept returns false, the action falls back to the parent interceptor.

• If all chained interceptors return false, the action dispatches to the surface.

@Composable
fun A2uiComponentScope.observeA2uiComponentState(
    reference: A2uiComponentReference
): A2uiComponentState

Resolves the current A2uiComponentState of a component by its A2uiComponentReference and subscribes for future updates.