@adia-ai/a2ui-runtime

A2UI runtime — renderer, registry, streams, surface manifest, and wiring primitives for the A2UI (Agent-to-UI) protocol. Framework-agnostic; pairs with any A2UI-conformant component set.

Install

npm install @adia-ai/a2ui-runtime

Typically paired with @adia-ai/web-components (which provides the custom-element catalog the renderer resolves against):

npm install @adia-ai/a2ui-runtime @adia-ai/web-components

What's in the box

• A2UIRenderer — processes A2UI protocol messages and writes custom elements to a container.
• registry / resolveTag / registerType — A2UI protocol component name → custom-element tag map. Extensible via registerType.
• Transports — sseStream, wsStream, mockStream, mcpStream, jsonlStream. Normalize inbound A2UI messages from SSE, WebSocket, mock fixtures, MCP tool calls, or JSONL logs.
• SurfaceManifest / Surface — design-time surface shape + runtime lifecycle for cross-surface data flow.
• Wiring primitives — WiringEngine, wiringRegistry, createDockables, plus the dockable base classes (ControllerDock, DataSourceDock, ActionDock, ProviderDock, LifecycleDock).
• Controllers — lazy-loaded runtime state managers at controllers/: FormController, DataStreamController, SelectionController, ToggleController, AccordionController, StateMachineController, plus BaseController. Registered in the wiring registry for lazy resolution; surface only imports what it declares.

Minimal usage

import { A2UIRenderer, jsonlStream } from '@adia-ai/a2ui-runtime';
import '@adia-ai/web-components';   // register the custom elements

const container = document.querySelector('#app');
const renderer = new A2UIRenderer(container);

for await (const msg of jsonlStream(fetch('/api/ui-trace.jsonl').then(r => r.body))) {
  renderer.process(msg);
}

For declarative embedding in HTML, use the <a2ui-root> element from @adia-ai/web-modules/runtime — it wraps A2UIRenderer + stream wiring in a custom element. (Was @adia-ai/web-components/patterns/ prior to the package split per ADR-0012.)

Public entry points

The default export bundles the common surface. Granular subpath imports are available if you want to tree-shake:

import { A2UIRenderer }    from '@adia-ai/a2ui-runtime/renderer';
import { resolveTag }      from '@adia-ai/a2ui-runtime/registry';
import { sseStream }       from '@adia-ai/a2ui-runtime/streams';
import { SurfaceManifest } from '@adia-ai/a2ui-runtime/surface';
import { WiringEngine }    from '@adia-ai/a2ui-runtime/wiring';
import { ActionDock }      from '@adia-ai/a2ui-runtime/dockables';

Relationship to other packages

• @adia-ai/web-components — the custom-element catalog the renderer resolves tags against. Depends on this package at runtime (as of web-components v0.0.4).
• @adia-ai/web-modules/runtime/a2ui-root — the declarative <a2ui-root> custom element; wraps this package's renderer + stream. Extracted from @adia-ai/web-components/patterns/ per ADR-0012.

License

(See repository root.)