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
{
"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.componentsfield-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):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 tree, from your own code or server
- Web: ComposedSurface
- Apple:
ComposedSurface, fromComposedTree(1.1.0)apple-tree - Windows:
OuroComposedSurface OuroComposedSurface- The tree, in an MCP tool result's
structuredContent.ouro - Web: OuroMcpApp, inside any MCP Apps host
- Apple:
ComposedTree(1.1.0), thenComposedSurfaceapple-tree - Windows:
OuroComposedSurface, fromOuroComposedResult.From OuroComposedSurface, fromOuroComposed.read- An update to the card it shows, in
structuredContent.ouro.update - Web: OuroMcpAppupdate
- Apple:
ComposedSurface(results:catalog:)(1.2.0)apple-update - Windows:
OuroComposedSurface(v0.3.0), or itsUpdatewindows-update OuroComposedState(v0.3.0), withreceiveorupdateandroid-update- A2UI messages
- Web: A2UISurface
- Apple:
OuroA2UI, which draws the tree withComposedSurface - Windows: 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 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
Claim sources
- 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) - 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.0verify: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)

