Draws Ouro's composed tree with Ouro HX, whatever format it came in: core's ComposedNode, from A2UI messages, an MCP tool result's structuredContent.ouro, or your own code. Every button is one of your app's declared actions: read and write run, a consequential one asks the person to confirm what the agent prepared, and a person-only one takes them to your app's own screen.
Install
Once per app, with Tailwind CSS v4 and an @/* path alias (Ouro HX is built on Base UI, so --base base; skip -t in an existing app):
npx shadcn@latest init --base base --preset nova --yes --no-monoreponpx shadcn@latest add ourostack/ouro-ui/ouro-base#v1.3.258Then the component. From v0.8.0 it installs only the helpers it imports and never touches your stylesheet (Installing):
npx shadcn@latest add ourostack/ouro-ui/composed-surface#v1.3.258Or, with the @ouro namespace set up:
npx shadcn@latest add @ouro/ouro-base @ouro/composed-surfaceIts tests, stories and Playwright spec are optional. They need Vitest 4.1.11 or later, and from v0.8.0 never change a version your app has (Testing):
npx shadcn@latest add ourostack/ouro-ui/composed-surface#v1.3.258 ourostack/ouro-ui/composed-surface-tests#v1.3.258import { ComposedSurface } from "@/components/ouro/composed-surface/composed-surface";Paths use shadcn's default @/ alias; the CLI rewrites them to yours.
Example
<ComposedSurface
tree={result.structuredContent.ouro.tree}
onPress={(press) => callTool(press.action, press.input)}
onHandoff={({ action }) => navigate(`/recipes/${id}?do=${action}`)}
/>Use instead when
- Use A2UISurface instead for A2UI messages, and HX's components directly when your own code, not an agent, decides the layout.
Props
Type: ComposedSurfaceProps.
className- Type:
string - Layout only: margins, width (
max-w-md). onHandoff(required)- Type:
(handoff: ComposedHandoff) => void - A person-only button never runs from composed UI: take the person to your app's own screen for it.
onPress(required)- Type:
(press: PersonPress, button: ComposedNode) => void | Promise<void> - Runs a pressed read or write button, and a consequential one once the person confirms.
pressis core'sPersonPress(the action, the prepared input, its consent, and that the person pressed it);buttonis the node, for a format that names its source. Return a promise to show the button loading until it settles. tree(required)- Type:
ComposedNode - The composed tree to draw: core's
ComposedNode, its values resolved. Check one you didn't resolve yourself with core'svalidateTreeagainst the app's catalog first; A2UI's resolver already has.
Don't use
These are not props. Passing one fails the type check with the fix in the error, and in development a console message names the fix.
onAction: Not a prop. A pressed button callsonPress, oronHandofffor a person-only one:<ComposedSurface onPress={run} onHandoff={openApp}>.
className is for layout only
Pass margins, width and grid placement (mt-4, w-full, col-span-2).
Appearance comes from props, not classes. In development, a class that sets appearance logs one warning per component instance, naming the prop to use instead. A class sets appearance when, after its variants (hover:, sm:) and any ! are removed, it starts with bg-, text-, border-, rounded-, shadow-, font-, ring-, from-, via-, to-, fill- or stroke-, or is border, rounded, shadow or ring, or has a dark: variant. Text wrapping, overflow and table layout classes (text-wrap, text-ellipsis, border-collapse) are layout and do not warn.
Alignment classes (text-center) warn too: set alignment on a parent element.
Types
ComposedHandoff
Where a person-only button takes the person: the action's id and the catalog's how.
interface ComposedHandoff {
action: string;
how: string;
}
