A2UI adapter
@kimen/adapter-a2ui is Kimen’s first protocol adapter. It translates
declarative A2UI messages into the neutral
UI spec and renders every surface through the
guarded renderer alone. The catalog and the ki-* elements are the durable
assets; the adapter is disposable by design — the exact supported A2UI
version(s) live in the package’s COMPAT.md, protocol churn is absorbed
there, and an unabsorbable break retires the package without touching core.
Why it is safe
Section titled “Why it is safe”The adapter owns no rendering path of its own. It builds a neutral UiSpec
and hands it to renderUiSpec from @kimen/catalog; the guardrail’s four
invariants (only catalog components render, only declared actions dispatch,
unknown props are rejected, no code path executes from message data) are
enforced there, once. Two complementary checks prove the adapter never opens
a side channel: a static module boundary (no other rendering library is
importable) and a runtime guarantee that every render call arrives at the
guarded renderer.
import { createA2uiAdapter } from '@kimen/adapter-a2ui';
const adapter = createA2uiAdapter({ surface: document.querySelector('#genui'), onAction: (event) => channelToAgent.send(event), // A2UI `action` round-trip onError: (error) => channelToAgent.send(error), // VALIDATION_FAILED reports onDegradation: (report) => log(report), // fallback gaps, as data});
// A2UI v0.9.1 messages render as catalog components:adapter.apply({ version: 'v0.9.1', createSurface: { surfaceId: 'checkout', catalogId: 'https://a2ui.org/specification/v0_9/catalogs/basic/catalog.json', },});const result = adapter.apply({ version: 'v0.9.1', updateComponents: { surfaceId: 'checkout', components: [ { id: 'root', component: 'Card', child: 'confirm' }, { id: 'confirm', component: 'Button', child: 'confirm-label', action: { event: { name: 'confirm-order' } }, }, { id: 'confirm-label', component: 'Text', text: 'Confirm order' }, ], },});result.ok; // true — or false with inert diagnostics naming each offenderThe adapter implements A2UI 1.0 (preferred) and v0.9.1 over the basic
catalog of each. Every message is validated against the version its envelope
declares ("1.0", or "v0.9.1"/"v0.9"), and a surface accepts only the
version that created it. The surface’s data model (bindings, updateDataModel,
list templates) is resolved inside the adapter; the catalog never learns about
it.
Modal uses its trigger and content references to render a button and a
dialog linked within the surface. Users can open and close it through the
rendered controls in both protocol versions.
Degradation rules
Section titled “Degradation rules”An A2UI message is data, never code:
- Basic-catalog types without a catalog counterpart degrade per node (Slider, DateTimeInput and others) to a fixed fallback that never carries agent content.
Imagemaps toki-image. Supply the alternative text in@accessibility.labelon 1.0 oraccessibility.labelon 0.9.1. Sethidden: truein that object for decorative images. An informative image with an empty or missing label degrades per node (missing-image-alt).Iconmaps toki-icon.- Forbidden types reject the whole message — a type the compatibility
matrix declares
forbidden(e.g. rawhtml) is never partially rendered; so do undeclared properties and client functions that reach a browser capability (openUrl). - Unsupported protocol versions are rejected naming the supported set
(
1.0,v0.9.1,v0.9), and so is a message that uses the other version’s vocabulary. - Agents cannot run renderer functions: every A2UI 1.0
callRendererFunctionis refused withINVALID_FUNCTION_CALL. - The action set is fixed: incremental
updateComponents/updateDataModelmessages revise the surface without discarding it, but no later update can bind an undeclared action.
Transport is caller-owned: the adapter consumes already-delivered A2UI
messages and emits action and error messages to the supplied callbacks.
deleteSurface drops adapter state; the host owns teardown of its surface
element.
The canonical package documentation, including the compatibility policy,
lives in the repository:
packages/adapter-a2ui.