@adia-ai/a2ui

Formerly @adia-ai/a2ui-runtime; renamed at ADR-0048 P3, which folded the runtime into this package root and added protocol-side validation at ./validate. Runtime subpath exports are unchanged.

The A2UI protocol — renderer, registry, streams, surface manifest, and wiring primitives for A2UI (Agent-to-UI), plus protocol-side validation. Framework-agnostic and dependency-free; pairs with any A2UI-conformant component set.

Install

npm install @adia-ai/a2ui

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

npm install @adia-ai/a2ui @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';
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/renderer';
import { resolveTag }      from '@adia-ai/a2ui/registry';
import { sseStream }       from '@adia-ai/a2ui/streams';
import { SurfaceManifest } from '@adia-ai/a2ui/surface';
import { WiringEngine }    from '@adia-ai/a2ui/wiring';
import { ActionDock }      from '@adia-ai/a2ui/dockables';
import { validateSchema } from '@adia-ai/a2ui/validate';

import catalog   from '@adia-ai/a2ui/catalog'        with { type: 'json' };
import tierIndex from '@adia-ai/a2ui/catalog/tiers'  with { type: 'json' };

./catalog is the contract (ADR-0050): one freestanding JSON Schema document listing every component, its props, and its taxonomy — enough to emit valid A2UI with nothing else installed. ./catalog/tiers is the derived L0–L4 ladder index (L0 primitives · L1 widgets · L2 layouts · L3 shells · L4 flows), under one law: every tier-N entry is a declared composition of tier-(N−1) entries. L0 (every component) and L1 (curated widget compositions) are populated today; L2–L4 are reserved while curation lands. ./catalog/common-types and ./catalog/functions are the catalog's authoring sources. All of it is exported data — this package stays dependency-free. The harvested chunk corpus that derives from the catalog is generation fuel and lives in @adia-ai/gen-ui.

./validate is the protocol-side validator — structural + wiring/registry coherence checks against the A2UI protocol, no catalog and no LLM, so it keeps this package dependency-free. Catalog-aware validation and the LLM semantic judge live in @adia-ai/gen-ui (./validate/catalog, ./validate/semantic) per ADR-0048.

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.)