# Composed UI

Composed UI is the interface an agent composes for a person, drawn natively, with consent. When an agent shows a person something, a recipe card, an order to confirm or a summary to act on, it composes it as data in Ouro's composed tree, and Ouro HX draws it. The tree is interface as validated data: each node names one of Ouro HX's components, every prop is checked against the catalog, and every button is one of your app's declared actions, pressed with that action's consent.[^validate] A sender can't relabel a button, loosen its consent or add a component the catalog lacks: the validator refuses the tree and says which node and why.[^forged]

The tree is Ouro's own. MCP Apps and A2UI are formats it speaks, not formats it depends on: an agent can send the tree itself, or send A2UI messages that the A2UI adapter turns into the same tree.[^formats]

## What a tree is

```json
{
  "id": "card",
  "component": "Card",
  "props": {},
  "children": [
    { "id": "title", "component": "Heading", "props": { "text": "Lemon orzo", "level": 1 }, "children": [] },
    { "id": "time", "component": "DescriptionList", "props": { "items": [{ "term": "Time", "detail": "25 min" }] }, "children": [] },
    {
      "id": "save",
      "component": "ActionButton",
      "props": { "action": "save_recipe", "label": "Save recipe", "consent": "write", "press": "run", "input": { "recipe": "rcp_lemon_orzo" }, "emphasis": "primary" },
      "children": []
    }
  ]
}
```

The components are Ouro HX's: `Card`, `Stack`, `Heading`, `Text`, `Image`, `Badge`, `List`, `DescriptionList`, `Separator` and `Alert`, the fields `TextField`, `Checkbox` and `Select`, plus `ActionButton` when your catalog has actions.[^components][^field-components] A component joins the catalog only when web and Apple both draw it and a conformance case covers it.[^joins]

## What a button does

An `ActionButton` names one of your actions and the input the agent prepared. Its label, consent class and what pressing it does come from your action's declaration, never from the agent ([the one action model](https://github.com/ourostack/ouro-ui-core/blob/main/docs/guides/actions.md)):[^button]

- **read** and **write** run when the person presses.[^run]
- **consequential** asks the person to confirm, on a sheet that shows each value the agent prepared under the field's own label, and runs only once they do.[^confirm]
- **person-only** takes the person to your app's own screen; it carries no input and sends nothing.[^handoff]

A press says the person made it (`by: "person"`).[^by-person] An agent never presses a button through the screen: it calls the action through its own door, its MCP tool or CLI command, and a person-only action answers it with a typed refusal.[^agent-press]

## What a field does

A `TextField`, `Checkbox` or `Select` asks the person for an answer. Its `value` is a JSON pointer, such as `/servings`, into a data model that travels beside the tree: `structuredContent.ouro.data` in an MCP tool result, or the surface's data model in A2UI. The field starts with what the data holds there and writes the person's answer back: a number field writes a number, a checkbox `true` or `false`, and a select the chosen option's text.[^fields]

An `ActionButton` input bound to the same path, `{"@path": "/servings"}`, sends what the person entered when they press, and a consequential button's confirm sheet shows it before anything runs. A field writes only the data model: nothing runs until the person presses a button.[^bound]

## Updating a card

An agent changes a card it already showed by sending only what changed, not the whole tree. In Ouro's tree, an MCP tool result carries `structuredContent.ouro.update` (core's `mcpAppTreeUpdateResult`): each of its `nodes` replaces the tree's node with the same id, children and all, and each of its `data` entries sets the data model at a JSON pointer, with `null` deleting the value.[^update] An update is all or nothing: an id the tree lacks, an id that a template's instances share, a pointer that names an object's prototype or a node that would relabel a button is refused, and nothing in it applies.[^update-refused] `OuroMcpApp` then shows the same short alert as a tree that fails the checks, and tells the agent why.[^update-refused]

In A2UI, the same changes are `updateComponents` and `updateDataModel` messages: `A2UISurface` draws them when you pass it the longer list of messages.[^a2ui-update] Either way, what the person entered stays, except where the update changed the value, or the list item it is in: there the agent's value wins.[^keeps]

## How a tree reaches the screen

| The agent sends | Web | Apple | Windows | Android |
| --- | --- | --- | --- | --- |
| The tree, from your own code or server | [ComposedSurface](composed-surface.md) | `ComposedSurface`, from `ComposedTree` (1.1.0)[^apple-tree] | `OuroComposedSurface` | `OuroComposedSurface` |
| The tree, in an MCP tool result's `structuredContent.ouro` | [OuroMcpApp](ouro-mcp-app.md), inside any MCP Apps host | `ComposedTree` (1.1.0), then `ComposedSurface`[^apple-tree] | `OuroComposedSurface`, from `OuroComposedResult.From` | `OuroComposedSurface`, from `OuroComposed.read` |
| An update to the card it shows, in `structuredContent.ouro.update` | [OuroMcpApp](ouro-mcp-app.md)[^update] | `ComposedSurface(results:catalog:)` (1.2.0)[^apple-update] | `OuroComposedSurface` (v0.3.0), or its `Update`[^windows-update] | `OuroComposedState` (v0.3.0), with `receive` or `update`[^android-update] |
| A2UI messages | [A2UISurface](a2ui-surface.md) | `OuroA2UI`, which draws the tree with `ComposedSurface` | Not read: send the tree | Not read: send the tree |

Each draws the same tree with the same components and the same consent.[^draws] Core holds the tree, its validator and the adapters (`ouro-composed.mts`, `ouro-mcp-app.mts`, `ouro-a2ui.mts`), which your app vendors from a core release; [core's guide](https://github.com/ourostack/ouro-ui-core/blob/main/docs/guides/a2ui.md) says how, and how to generate your catalog from your actions.[^vendor]

## Which platforms draw it

Every kit draws the tree natively: web and Apple, and Windows and Android with `OuroComposedSurface`, which read the tree itself rather than A2UI messages.[^kits] Every renderer passes the same conformance cases from core, so a card looks and behaves alike wherever it is drawn.[^platforms]

Ouro's kits are written in their platforms' own toolkits: React on the web, SwiftUI on Apple, WinUI 3 on Windows and Compose on Android.[^native] There is no Flutter, React Native or other cross-platform kit, on purpose: agents now write each platform's native app, so sharing one implementation no longer pays for the compromise in how it feels.[^native]

[^validate]: https://github.com/ourostack/ouro-ui-core/blob/a8d6c3076a342bfcede72d874de9354dcaa4e2fa/src/composed.mts; test:registry/ouro/components/ouro/composed-surface/composed-surface.test.tsx::ComposedSurface > draws a tree built in code, which core's validator accepts, with HX components verify:urlOk(https://github.com/ourostack/ouro-ui-core/blob/a8d6c3076a342bfcede72d874de9354dcaa4e2fa/src/composed.mts) verify:testExists(registry/ouro/components/ouro/composed-surface/composed-surface.test.tsx::ComposedSurface > draws a tree built in code, which core's validator accepts, with HX components)
[^forged]: https://github.com/ourostack/ouro-ui-core/blob/a8d6c3076a342bfcede72d874de9354dcaa4e2fa/test/composed.test.mts#L34-L66 verify:urlOk(https://github.com/ourostack/ouro-ui-core/blob/a8d6c3076a342bfcede72d874de9354dcaa4e2fa/test/composed.test.mts#L34-L66) verify:testExists(registry/ouro/components/ouro/mcp-app/ouro-mcp-app.test.tsx::OuroMcpApp > tells the agent what to correct when a composed tree fails the checks, and shows the person the same short alert)
[^formats]: https://github.com/ourostack/ouro-ui-core/blob/a8d6c3076a342bfcede72d874de9354dcaa4e2fa/test/composed.test.mts#L81-L98 verify:urlOk(https://github.com/ourostack/ouro-ui-core/blob/a8d6c3076a342bfcede72d874de9354dcaa4e2fa/test/composed.test.mts#L81-L98) verify:testExists(registry/ouro/components/ouro/mcp-app/ouro-mcp-app.test.tsx::OuroMcpApp > draws a composed tree in structuredContent.ouro with ComposedSurface)
[^components]: https://github.com/ourostack/ouro-ui-core/blob/a8d6c3076a342bfcede72d874de9354dcaa4e2fa/src/composed.mts#L54-L130 verify:urlOk(https://github.com/ourostack/ouro-ui-core/blob/a8d6c3076a342bfcede72d874de9354dcaa4e2fa/src/composed.mts#L54-L130)
[^field-components]: https://github.com/ourostack/ouro-ui-core/blob/2e8069b82fbcf88ae7fa01f7c409af5c4ae2a5a5/src/composed.mts#L120-L150 verify:urlOk(https://github.com/ourostack/ouro-ui-core/blob/2e8069b82fbcf88ae7fa01f7c409af5c4ae2a5a5/src/composed.mts#L120-L150) verify:testExists(registry/ouro/components/ouro/composed-surface/composed-surface.test.tsx::ComposedSurface fields > draws each field with HX, its label and hint, starting from what the data holds)
[^fields]: test:registry/ouro/components/ouro/composed-surface/composed-surface.test.tsx::ComposedSurface fields > draws each field with HX, its label and hint, starting from what the data holds; https://github.com/ourostack/ouro-ui-core/blob/2e8069b82fbcf88ae7fa01f7c409af5c4ae2a5a5/docs/decisions/2026-11-17-composed-fields.md verify:testExists(registry/ouro/components/ouro/composed-surface/composed-surface.test.tsx::ComposedSurface fields > draws each field with HX, its label and hint, starting from what the data holds) verify:testExists(registry/ouro/components/ouro/composed-surface/composed-surface.test.tsx::ComposedSurface fields > presses a bound button with what the person typed, ticked and chose) verify:testExists(registry/ouro/components/ouro/mcp-app/ouro-mcp-app.test.tsx::OuroMcpApp > starts a tree's fields from structuredContent.ouro.data, and calls the tool with what the person typed) verify:testExists(registry/ouro/components/ouro/a2ui-surface/a2ui-surface.test.tsx::A2UISurface > starts its fields from the surface's data model, and sends what the person entered in a bound field) verify:urlOk(https://github.com/ourostack/ouro-ui-core/blob/2e8069b82fbcf88ae7fa01f7c409af5c4ae2a5a5/docs/decisions/2026-11-17-composed-fields.md)
[^bound]: test:registry/ouro/components/ouro/composed-surface/composed-surface.test.tsx::ComposedSurface fields > shows what the person typed on a consequential button's confirm sheet, and sends it on confirm; https://github.com/ourostack/ouro-ui-core/blob/2e8069b82fbcf88ae7fa01f7c409af5c4ae2a5a5/src/composed.mts#L443-L470 verify:testExists(registry/ouro/components/ouro/composed-surface/composed-surface.test.tsx::ComposedSurface fields > presses a bound button with what the person typed, ticked and chose) verify:testExists(registry/ouro/components/ouro/composed-surface/composed-surface.test.tsx::ComposedSurface fields > shows what the person typed on a consequential button's confirm sheet, and sends it on confirm) verify:urlOk(https://github.com/ourostack/ouro-ui-core/blob/2e8069b82fbcf88ae7fa01f7c409af5c4ae2a5a5/src/composed.mts#L443-L470)
[^joins]: https://github.com/ourostack/ouro-ui-core/blob/a8d6c3076a342bfcede72d874de9354dcaa4e2fa/AGENTS.md#agent-composed-ui verify:urlOk(https://github.com/ourostack/ouro-ui-core/blob/a8d6c3076a342bfcede72d874de9354dcaa4e2fa/AGENTS.md#agent-composed-ui)
[^button]: https://github.com/ourostack/ouro-ui-core/blob/a8d6c3076a342bfcede72d874de9354dcaa4e2fa/test/composed.test.mts#L74-L80 verify:urlOk(https://github.com/ourostack/ouro-ui-core/blob/a8d6c3076a342bfcede72d874de9354dcaa4e2fa/test/composed.test.mts#L74-L80)
[^run]: test:registry/ouro/components/ouro/composed-surface/composed-surface.test.tsx::ComposedSurface > presses a write button with the prepared input, pressed by the person verify:testExists(registry/ouro/components/ouro/composed-surface/composed-surface.test.tsx::ComposedSurface > presses a write button with the prepared input, pressed by the person)
[^confirm]: test:registry/ouro/components/ouro/composed-surface/composed-surface.test.tsx::ComposedSurface > asks the person to confirm a consequential action with what the agent prepared, and presses it only on confirm verify:testExists(registry/ouro/components/ouro/composed-surface/composed-surface.test.tsx::ComposedSurface > asks the person to confirm a consequential action with what the agent prepared, and presses it only on confirm) verify:testExists(registry/ouro/components/ouro/mcp-app/ouro-mcp-app.test.tsx::OuroMcpApp > shows the app's own name for an id on the confirm sheet, with the id beside it)
[^handoff]: test:registry/ouro/components/ouro/composed-surface/composed-surface.test.tsx::ComposedSurface > hands a person-only action to the app's own screen and never presses it verify:testExists(registry/ouro/components/ouro/composed-surface/composed-surface.test.tsx::ComposedSurface > hands a person-only action to the app's own screen and never presses it)
[^by-person]: test:registry/ouro/components/ouro/composed-surface/composed-surface.test.tsx::ComposedSurface > presses a write button with the prepared input, pressed by the person verify:testExists(registry/ouro/components/ouro/composed-surface/composed-surface.test.tsx::ComposedSurface > presses a write button with the prepared input, pressed by the person) verify:urlOk(https://github.com/ourostack/ouro-ui-core/blob/a8d6c3076a342bfcede72d874de9354dcaa4e2fa/test/composed.test.mts#L67-L73)
[^agent-press]: https://github.com/ourostack/ouro-ui-core/blob/a8d6c3076a342bfcede72d874de9354dcaa4e2fa/test/a2ui.test.mts#L85-L92 verify:urlOk(https://github.com/ourostack/ouro-ui-core/blob/a8d6c3076a342bfcede72d874de9354dcaa4e2fa/test/a2ui.test.mts#L85-L92) verify:testExists(registry/ouro/components/ouro/mcp-app/ouro-mcp-app.test.tsx::OuroMcpApp > refuses an agent's attempt to press a button through the screen with the catalog's INVALID_FUNCTION_CALL)
[^draws]: https://github.com/ourostack/ouro-ui-apple/blob/b0580c86da4d81e8d4e07bb8dcaf143a01454cd9/Tests/OuroA2UITests/ComposedTests.swift verify:urlOk(https://github.com/ourostack/ouro-ui-apple/blob/b0580c86da4d81e8d4e07bb8dcaf143a01454cd9/Tests/OuroA2UITests/ComposedTests.swift) verify:testExists(registry/ouro/components/ouro/mcp-app/ouro-mcp-app.test.tsx::OuroMcpApp > draws a composed tree in structuredContent.ouro with ComposedSurface) verify:testExists(registry/ouro/components/ouro/composed-surface/composed-surface.test.tsx::ComposedSurface > draws a tree built in code, which core's validator accepts, with HX components)
[^vendor]: https://github.com/ourostack/ouro-ui-core/blob/a8d6c3076a342bfcede72d874de9354dcaa4e2fa/docs/guides/a2ui.md#1-vendor-the-files verify:urlOk(https://github.com/ourostack/ouro-ui-core/blob/a8d6c3076a342bfcede72d874de9354dcaa4e2fa/docs/guides/a2ui.md#1-vendor-the-files)
[^apple-tree]: https://github.com/ourostack/ouro-ui-apple/releases/tag/v1.1.0 verify:urlOk(https://github.com/ourostack/ouro-ui-apple/releases/tag/v1.1.0)
[^platforms]: https://github.com/ourostack/ouro-ui-apple/blob/b0580c86da4d81e8d4e07bb8dcaf143a01454cd9/Sources/OuroA2UI/ComposedSurface.swift; https://github.com/ourostack/ouro-ui-core/blob/a8d6c3076a342bfcede72d874de9354dcaa4e2fa/docs/decisions/2026-11-14-android-kit.md verify:urlOk(https://github.com/ourostack/ouro-ui-apple/blob/b0580c86da4d81e8d4e07bb8dcaf143a01454cd9/Sources/OuroA2UI/ComposedSurface.swift) verify:urlOk(https://github.com/ourostack/ouro-ui-core/blob/a8d6c3076a342bfcede72d874de9354dcaa4e2fa/docs/decisions/2026-11-14-android-kit.md)
[^native]: https://github.com/ourostack/ouro-ui-core/blob/5f520a112feb806aa51a8e8bf6a716acdcdf6a54/docs/decisions/2026-11-17-native-kits-no-cross-platform.md verify:urlOk(https://github.com/ourostack/ouro-ui-core/blob/5f520a112feb806aa51a8e8bf6a716acdcdf6a54/docs/decisions/2026-11-17-native-kits-no-cross-platform.md)
[^kits]: https://github.com/ourostack/ouro-ui-windows/blob/2138b3d29b89e335857da610ae05eab99511faa1/src/Ouro.UI.Windows/OuroComposedSurface.cs; https://github.com/ourostack/ouro-ui-android/blob/8ba5196a9e9062e495dde8c23f136913094cbdf4/ouro-hx/src/main/kotlin/bot/ouro/ui/hx/OuroComposedSurface.kt verify:urlOk(https://github.com/ourostack/ouro-ui-windows/blob/2138b3d29b89e335857da610ae05eab99511faa1/src/Ouro.UI.Windows/OuroComposedSurface.cs) verify:urlOk(https://github.com/ourostack/ouro-ui-android/blob/8ba5196a9e9062e495dde8c23f136913094cbdf4/ouro-hx/src/main/kotlin/bot/ouro/ui/hx/OuroComposedSurface.kt) verify:equals(scripts/parity-data/versions.json#windows.tag)=v0.5.0 verify:equals(scripts/parity-data/versions.json#android.tag)=v0.6.0
[^update]: https://github.com/ourostack/ouro-ui-core/blob/c90da442be466dfd0f80b435c3a44d3c175c6092/docs/decisions/2026-11-18-composed-tree-updates.md; test:registry/ouro/components/ouro/mcp-app/ouro-mcp-app.test.tsx::OuroMcpApp > applies an update in structuredContent.ouro to the tree it shows, keeping what the person typed where the update left it verify:urlOk(https://github.com/ourostack/ouro-ui-core/blob/c90da442be466dfd0f80b435c3a44d3c175c6092/docs/decisions/2026-11-18-composed-tree-updates.md) verify:testExists(registry/ouro/components/ouro/mcp-app/ouro-mcp-app.test.tsx::OuroMcpApp > applies an update in structuredContent.ouro to the tree it shows, keeping what the person typed where the update left it) verify:testExists(test/a2ui.test.ts::composed tree update conformance > %s gives its expect)
[^update-refused]: https://github.com/ourostack/ouro-ui-core/blob/c90da442be466dfd0f80b435c3a44d3c175c6092/test/composed.test.mts; test:registry/ouro/components/ouro/mcp-app/ouro-mcp-app.test.tsx::OuroMcpApp > tells the agent why an update can't apply, shows the person the short alert, and applies a corrected one to the last tree verify:urlOk(https://github.com/ourostack/ouro-ui-core/blob/c90da442be466dfd0f80b435c3a44d3c175c6092/test/composed.test.mts) verify:testExists(registry/ouro/components/ouro/mcp-app/ouro-mcp-app.test.tsx::OuroMcpApp > tells the agent why an update can't apply, shows the person the short alert, and applies a corrected one to the last tree) verify:testExists(test/a2ui.test.ts::composed tree update conformance > %s gives its expect)
[^a2ui-update]: test:registry/ouro/components/ouro/a2ui-surface/a2ui-surface.test.tsx::A2UISurface > keeps what the person entered across a new label function and new messages, until a message changes that field's value verify:testExists(registry/ouro/components/ouro/a2ui-surface/a2ui-surface.test.tsx::A2UISurface > keeps what the person entered across a new label function and new messages, until a message changes that field's value)
[^keeps]: test:registry/ouro/components/ouro/composed-surface/composed-surface.test.tsx::ComposedSurface fields > keeps what the person entered across a new tree and data, except where the new data changed it verify:testExists(registry/ouro/components/ouro/composed-surface/composed-surface.test.tsx::ComposedSurface fields > drops what the person entered in a list item the agent changed, even where the value it held stays the same) verify:testExists(registry/ouro/components/ouro/composed-surface/composed-surface.test.tsx::ComposedSurface fields > keeps what the person entered across a new tree and data, except where the new data changed it) verify:testExists(registry/ouro/components/ouro/a2ui-surface/a2ui-surface.test.tsx::A2UISurface > keeps what the person entered across a new label function and new messages, until a message changes that field's value)
[^windows-update]: https://github.com/ourostack/ouro-ui-windows/blob/2138b3d29b89e335857da610ae05eab99511faa1/README.md; https://github.com/ourostack/ouro-ui-windows/releases/tag/v0.3.0 verify:urlOk(https://github.com/ourostack/ouro-ui-windows/blob/2138b3d29b89e335857da610ae05eab99511faa1/README.md) verify:urlOk(https://github.com/ourostack/ouro-ui-windows/releases/tag/v0.3.0)
[^android-update]: https://github.com/ourostack/ouro-ui-android/blob/8ba5196a9e9062e495dde8c23f136913094cbdf4/README.md; https://github.com/ourostack/ouro-ui-android/releases/tag/v0.3.0 verify:urlOk(https://github.com/ourostack/ouro-ui-android/blob/8ba5196a9e9062e495dde8c23f136913094cbdf4/README.md) verify:urlOk(https://github.com/ourostack/ouro-ui-android/releases/tag/v0.3.0)
[^apple-update]: https://github.com/ourostack/ouro-ui-apple/releases/tag/v1.2.0; https://github.com/ourostack/ouro-ui-apple/blob/dfdcc158b659e6448beec6a290fa161911e04d93/README.md verify:urlOk(https://github.com/ourostack/ouro-ui-apple/releases/tag/v1.2.0) verify:urlOk(https://github.com/ourostack/ouro-ui-apple/blob/dfdcc158b659e6448beec6a290fa161911e04d93/README.md)
