@nano-ui-kit/a2ui-utils

A2UI runtime — takes an A2UI (Agent-to-UI) JSON tree and stamps DOM nodes. Framework-agnostic leaf: no runtime dependency on any particular component set.

Pairs naturally with @nano-ui-kit/web-components, which registers the *-n custom elements the default registry maps to. Works just as well with your own components — swap the registry via registerType().

Install

npm install @nano-ui-kit/a2ui-utils
# optional: default component set
npm install @nano-ui-kit/web-components

Render A2UI JSON into a DOM node

import { A2UIRenderer, registry } from '@nano-ui-kit/a2ui-utils';
import '@nano-ui-kit/web-components';   // registers card-n, button-n, …

const target = document.getElementById('canvas');
const renderer = new A2UIRenderer(target, registry);

renderer.update([
  { id: 'root', component: 'Card', children: ['sec'] },
  { id: 'sec',  component: 'Section', children: ['btn'] },
  { id: 'btn',  component: 'Button', text: 'Hello', variant: 'primary' },
]);

Connect to a live stream

import { A2UIRenderer, registry, sseStream } from '@nano-ui-kit/a2ui-utils';

const renderer = new A2UIRenderer(document.body, registry);

for await (const msg of sseStream('/api/agent')) {
  renderer.apply(msg);   // updateComponents / patchComponents / removeComponents
}

Stream adapters: sseStream, wsStream, jsonlStream, mcpStream, mockStream.

Use a different component set

Override the registry before rendering:

import { A2UIRenderer, registerType } from '@nano-ui-kit/a2ui-utils';

registerType('Card', 'my-card');
registerType('Button', 'my-button');

const renderer = new A2UIRenderer(target);
renderer.update(tree);

Wire handlers + data sources (Tier 2)

import { SurfaceManifest } from '@nano-ui-kit/a2ui-utils';

const manifest = new SurfaceManifest({
  actions: [
    { event: { event: 'press', target: 'save-btn' },
      handler: 'submit-resource',
      config: { uri: 'api://users', method: 'POST' } },
  ],
  dataSources: [{ id: 'users', uri: 'api://users' }],
});

SurfaceManifest is the declarative config object. Runtime activation against a live surface — resolving handlers, provisioning data sources, binding controllers — is driven by the consumer. @nano-ui-kit/a2ui-compose ships a reference runtime; roll your own against the same manifest shape if you need alternate handler resolution or async semantics.

What's NOT here

• Custom elements themselves — pull from @nano-ui-kit/web-components or any other A2UI-conformant set.
• <nano-a2ui-root> convenience element — lives in @nano-ui-kit/web-components/patterns/a2ui-root so this package stays a framework-agnostic leaf.
• Pattern retrieval, validation, feedback scoring — those are gen-UI concerns and live in @nano-ui-kit/a2ui-compose (private/workspace-only).

License

MIT © Kim Granlund