# Architecture

The plugin adds one model-facing Tool, `a2ui_present`, and one keyed React 18 Tool card. The model supplies a bounded interaction template. The host validates it and deterministically compiles three A2UI 0.9.1 messages with the required `version: "v0.9"` envelope: `createSurface`, `updateComponents`, and `updateDataModel`. Components use the official v0.9 Basic Catalog's flat discriminator form and the conventional `root` component id.

The browser reconstructs the same surface from durable Tool arguments. A browser refresh or reconnect therefore does not need private client state to recover the card. A valid click is posted over Harness Connection RPC and must match the owning session, call, surface, declared source component, declared action, and complete typed data model. The host accepts only the first valid submission.

```mermaid
sequenceDiagram
  participant M as Model
  participant H as Harness host
  participant U as A2UI Tool card
  participant T as Ordinary Harness tools
  M->>H: a2ui_present(template)
  H->>H: validate + compile A2UI messages
  H-->>U: durable Tool call arguments
  U->>U: render catalog subset
  U->>H: session + call + surface + declared action
  H->>H: validate and settle once
  H-->>M: structured Tool result
  M->>T: optional side effect under normal policy
```

## Trust boundary

- A2UI action events never execute shell, filesystem, network, approval, or plugin operations.
- The model cannot send HTML, JavaScript, CSS, remote images, or a raw component catalog.
- The default RPC authority is loopback. `trusted-host` is opt-in and is only Harness's host-header/same-origin fence, not user authentication.
- Tool arguments and submitted values are durable model-visible data. Never collect credentials or other secrets.
- Browser reconnects are supported while the host process lives. Host restart interrupts pending calls; it does not guess or replay a user action.

## Deliberate v0.1 limits

This is A2UI over Harness Tool calls and Connection RPC. The nested client event follows the v0.9 `action` shape while Harness adds session/call correlation around it. It is not AG-UI, A2A, or a complete renderer for arbitrary third-party A2UI catalogs. The renderer supports the checked-in subset manifest for the official v0.9 Basic Catalog: forms, choices, reviews, and read-only status steps.