catalogs

readonly CatalogInput[]

Components the renderer is allowed to instantiate. Each item is either a bare component (name read from displayName ?? name) or a tuple [component, manifest] where the manifest is the JSON the extractor emits at dist/catalog/<Name>/catalog.json.

className?

string

(Optional) Optional class name applied to the top-level surface-${surfaceId} view for the active surface. Use this when theme switching is expressed as surface-level classes.

messageStore

MessageStore

The raw-message buffer the developer pushes protocol messages into. <A2UI> subscribes via useSyncExternalStore and processes new messages incrementally.

The internal MessageProcessor (surfaces, signals, resources) is created once per mount and is **not reset** if messageStore is later replaced with a different instance. Pass a key prop derived from the store's identity if you want a fresh session, e.g. <A2UI key={turnId} messageStore={turnStore} ... />.

onAction?

(action: UserActionPayload) => void

(Optional) Called when a user action fires inside the rendered tree (button tap, etc.). Forward to your agent and push the response messages back into the same messageStore to update the UI. Fire-and-forget; the renderer never awaits this.

renderEmpty?

() => ReactNode

(Optional) Render before the first beginRendering arrives from the buffer.

renderError?

(err: unknown) => ReactNode

(Optional) Render when the active resource fails.

renderFallback?

() => ReactNode

(Optional) Render while the active resource is pending.

renderUnsupported?

(info: UnsupportedInfo) => ReactNode

(Optional) Render when unsupported data syntax or an unsupported component is encountered.

wrapSurface?

(children: ReactNode, ctx: { surfaceId: string; }) => ReactNode

(Optional) Wrap each top-level surface so consumers can apply an outer theme shell, wrapper className, or additional styles.