a2ui-vue3

a2ui-vue3

Vue 3 renderer adapter for the A2UI v0.9.1 protocol. The current npm package version is 0.0.1; package versioning is independent from the A2UI wire version.

The adapter uses @a2ui/web_core@0.10.6. Its v0_9 export accepts v0.9 and v0.9.1 envelopes and provides the official message schemas, state models, data binding, Basic Catalog APIs, and functions. This repository adds the Vue renderer, transports, catalog registry, theme bridge, component laboratory, and tests.

Requirements

• Node.js 20 or newer
• pnpm 9 or newer
• Vue 3.5 or newer in the consuming application

node --version
pnpm --version

Install

pnpm add a2ui-vue3 vue @a2ui/web_core@0.10.6

The runtime is exported from a2ui-vue3. Import the framework-independent CSS separately with a2ui-vue3/style.css.

Use the renderer

Create one client for the message stream, feed A2UI v0.9.1 messages into it, and mount a surface under A2UIProvider:

import { createApp } from 'vue'
import { A2UIProvider, A2UISurface, createA2UI } from 'a2ui-vue3'
import 'a2ui-vue3/style.css'

const client = createA2UI({
  onAction: (action) => {
    void fetch('/a2ui/action', {
      method: 'POST',
      headers: { 'content-type': 'application/json' },
      body: JSON.stringify({ version: 'v0.9.1', action }),
    })
  },
  onError: (error) => console.error('A2UI error', error),
})

client.feed({
  version: 'v0.9.1',
  createSurface: {
    surfaceId: 'main',
    catalogId: 'https://a2ui.org/specification/v0_9_1/catalogs/basic/catalog.json',
    sendDataModel: true,
  },
})

client.feed({
  version: 'v0.9.1',
  updateComponents: {
    surfaceId: 'main',
    components: [{ id: 'root', component: 'Text', text: { path: '/message' }, variant: 'h2' }],
  },
})

client.feed({
  version: 'v0.9.1',
  updateDataModel: { surfaceId: 'main', path: '/', value: { message: 'Hello from A2UI' } },
})

const app = createApp({
  components: { A2UIProvider, A2UISurface },
  template: '<A2UIProvider :client="client"><A2UISurface surface-id="main" /></A2UIProvider>',
  setup: () => ({ client }),
})
app.mount('#app')

feed() accepts protocol objects, JSON strings, JSONL streams, SSE data: frames, and WebSocket text or binary payloads. The core validates messages before state mutation. strict: true rejects invalid component updates; default mode reports a diagnostic error and keeps the remaining surface renderable.

Transports

The transport interface is independent of A2A, MCP, AG-UI, or a particular HTTP server:

interface A2UITransport {
  readonly writable?: boolean
  connect(handlers: TransportHandlers): Promise<void> | void
  send(message: A2uiClientMessage, metadata?: Record<string, unknown>): Promise<void> | void
  close(): void
}

Built-in adapters are ManualTransport, SSETransport, and WebSocketTransport. SSE is read-only; action/error messages are delivered to local callbacks and writable transports. Use getClientCapabilities() and getClientDataModel() to place official metadata into the host protocol envelope.

Component laboratory

The local gallery at http://127.0.0.1:3000/ groups all 18 Basic Catalog components by protocol role. It includes a live surface preview, a property inspector backed by real updateDataModel messages, component selection backed by deleteSurface/createSurface/updateComponents, and Inbound, Outbound, Data model, and Conformance debug tabs.

pnpm install
pnpm --dir examples/gallery dev

The initial view shows common interactive components. Use the left navigation to open Text, Image, Icon, Video, AudioPlayer, Row, Column, List, Card, Tabs, Modal, Divider, Button, TextField, CheckBox, ChoicePicker, Slider, and DateTimeInput fixtures.

Development

git clone <repository-url>
cd a2ui-vue3
pnpm install

pnpm run typecheck   # vue-tsc, no emit
pnpm run test        # all Vitest unit/component tests
pnpm run conformance # official examples and protocol conformance gate
pnpm run build       # Vite library build
pnpm run test:e2e    # Playwright gallery tests
pnpm --dir examples/gallery dev

Generated dist, Playwright output, coverage, and dependency directories are ignored by Git.

Debugging

For a blank or missing surface, check the catalog ID, component id/component, the root component, and client.getProtocolConformanceReport(). Attach onError and inspect code, surfaceId, path, and message.

For values that do not update, verify the property is a dynamic { path: '/demo/value' } binding and that the update uses the same surfaceId and JSON Pointer. Use the gallery Data model tab or run pnpm exec vitest run tests/components/surface.test.ts.

For transport issues, use ManualTransport to isolate protocol processing, inject EventSource/WebSocket constructors in tests, and map the transport metadata argument to the host's A2A, MCP, AG-UI, or HTTP envelope.

Protocol conformance

The protocol source is the A2UI v0.9.1 specification. Runtime validation uses the official schemas from @a2ui/web_core@0.10.6. The repository validates server/client messages, Basic Catalog properties, component-tree references, capabilities/data-model metadata, and all published Basic Catalog examples.

pnpm run conformance

The conformance gate covers the A2UI protocol layer. Pixel-level visual parity and mapping metadata into a specific external transport are host-integration concerns. See docs/compatibility.md.

Publishing

The package is unscoped and public by default. Run the complete checks and inspect the tarball first:

pnpm run typecheck
pnpm run test
pnpm run conformance
pnpm run build
pnpm run test:e2e
npm pack --dry-run

Log in with the npm account that owns the package name:

npm login --auth-type=web
npm whoami

Publishing requires account 2FA or a granular access token configured to bypass 2FA. Publish the current version with:

npm publish

After publishing:

npm view a2ui-vue3 version
npm install a2ui-vue3@0.0.1

Never commit an npm token or paste one into issue comments. For CI, use npm trusted publishing or a repository secret.

Contributing

1. Create a branch from main.
2. Read the relevant A2UI specification section and docs/compatibility.md.
3. Add a failing test before changing behavior.
4. Keep protocol changes in the core adapter boundary and gallery-only changes under examples/gallery.
5. Run the focused test, pnpm run typecheck, and then pnpm run test.
6. For protocol or renderer changes, also run pnpm run conformance, pnpm run build, and pnpm run test:e2e.
7. Run git diff --check and include verification commands in the pull request.

Use official wire field names. Do not use eval, arbitrary component resolution, or SDK-local fields in serialized A2UI messages. New Basic Catalog behavior should include a fixture, focused component test, and schema or official-example assertion when applicable.

License

This project follows the license declared in the repository. The A2UI protocol and official core package remain subject to their upstream project terms.