@polyxd/a2ui

@polyxd/a2ui

Exports Polyxd UI documents to A2UI v1.0 (release candidate) agent-to-renderer messages. It also ships the Polyxd catalog in A2UI catalog format.

The target is the official schemas at a2ui-project/a2ui commit 04e6f07 (2026-09-18). They are vendored unmodified in vendor/a2ui/v1_0-04e6f07/, and that directory's README records provenance and hashes. Background is in docs/decisions/0001-a2ui-and-foundations.md §1 and §6.

What's exported

import { exportToA2UI, createValidator, checkComponentTree } from "@polyxd/a2ui";

const { messages, lossy, idMap } = exportToA2UI(doc);                   // one createSurface with components + dataModel
const streamed = exportToA2UI(doc, { mode: "stream" });                 // createSurface, updateComponents, updateDataModel
exportToA2UI(doc, { surfaceId: "send-7f3a", extensions: false, sendDataModel: true });

const v = createValidator();          // Ajv 2020-12 over the vendored official schemas, Polyxd catalog as the active catalog
v.message(messages[0]);               // [] when valid against agent_to_renderer.json
v.catalogDefinition(catalog);         // [] when valid against catalog_definition.json
checkComponentTree(components);       // "root" exists, ids unique, ComponentId/ChildList references resolve, allowedChildren

Export	What it is
exportToA2UI(doc, options?)	Returns { messages, lossy, idMap }. lossy holds JSON Pointers into the Polyxd document for every field with no A2UI representation. idMap lists renamed ids.
catalog/catalog.json	The Polyxd A2UI catalog. catalogId and $id are https://polyxd.com/catalog/0.1/a2ui, protocolVersion is 1.0. instructions carries whenToUse, whenNotToUse, rendering, accessibility and agent guidance per component. Generated by npm run build:catalog from @polyxd/spec components/*.json.
createValidator(catalog?), checkComponentTree()	Validation against the vendored official schemas. The catalog is aliased as https://a2ui.org/specification/v1_0/catalog.json, the same as the upstream test runner.
MAPPING	The per-component export decision (below).

How the projection works

• Surface: surface.id becomes createSurface.surfaceId, and data becomes dataModel (or updateDataModel with no path, which replaces the whole model). The surface default catalogId is the Polyxd catalog.
• Ids and children: Ids and child lists are copied as they are. A2UI mounts the component with id root, so the Polyxd root component is renamed root. Any other component already called root becomes root_2, and every reference follows (children, Card.media, Collection.empty, Status.action, Confirm.summary, Views/Steps content, templates). The rewrite is schema-driven: every Polyxd Id-typed value is remapped.
• Templated children: Collection.items {path, componentId} is an A2UI ChildList template. Relative paths inside the template resolve against the item, as in A2UI.
• Bindings: {path} JSON Pointers are copied as they are. A2UI's DataBinding has the same shape and scoping rules.
• Actions: action.event {name, context} is copied as it is (the A2UI agent action). Polyxd's renderer-handled ui.dismiss, ui.back and ui.next become A2UI local actions, {functionCall: {call: "dismiss" | "back" | "next"}}. The Polyxd catalog declares these as rendererOnly void functions.
• Accessibility: accessibility {label, description, live, hidden} is copied into the A2UI accessibility block. Polyxd's fields are a subset of A2UI's.
• Polyxd-only metadata: This goes under metadata.extensions.com_polyxd on the surface (specVersion, title, intent, pattern, journey, dismissible, original root id) and on each component (key). A2UI renderers must ignore unknown extensions, so these fields are still reported in lossy. Pass extensions: false to omit them.

Component mapping

Rule: a component maps to a Basic-catalog component only when every Polyxd prop has a Basic equivalent with the same meaning. Otherwise it is a custom component in the Polyxd catalog, with the same name and props (helper types inlined, as A2UI catalogs require). That keeps the export a faithful projection rather than a lossy flattening.

Result: 0 Basic, 24 custom. Each catalog entry records its nearest Basic analog in metadata.extensions.com_polyxd.

Polyxd	A2UI component	Catalog	Nearest Basic analog	Why not Basic
Action	Action	custom	Button + Text child	No danger tone or disabled state. Only default/primary/borderless. Needs a synthesized Text child.
ActionBar	ActionBar	custom	Row of Button	Loses the "actions ordered by importance" semantics and narrow-screen stacking.
Card	Card	custom	Card > Column(Image, Text, ...)	Basic Card has a single child and no action. Title, subtitle, badge, media and card action would be synthesized or lost.
Chart	Chart	custom	Text(summary) + List	No chart in Basic.
Choice	Choice	custom	ChoicePicker	Options must be literal (Polyxd options can come from data). No option descriptions or help text.
Collection	Collection	custom	List (templated)	No label, empty state or selection.
Comparison	Comparison	custom	List of Card	No comparison in Basic.
Confirm	Confirm	custom	Modal + Column + Buttons	Modal needs a trigger. No severity, consequence or type-to-confirm.
DateInput	DateInput	custom	DateTimeInput	No date range or help text.
DetailList	DetailList	custom	Column of Row(Text, Text)	Loses the label/value semantics, keys and formats.
Disclosure	Disclosure	custom	Column	No expand/collapse.
Form	Form	custom	Column + Button	No submit/cancel semantics.
Group	Group	custom	Column / Row	Loses the adaptive arrangement hint.
Media	Media	custom	Image	Image takes a URL, not a host-data binding. No decorative flag or aspect hint.
Metric	Metric	custom	Column of Text	Loses format, change and favourable direction.
RangeInput	RangeInput	custom	Slider	Step count, not step size. No format.
Section	Section	custom	Column + Text	No heading level or landmark.
Status	Status	custom	Row(Icon, Text)	Loses status kinds and live semantics.
Steps	Steps	custom	Column	No stepper.
Table	Table	custom	List of Row	No table.
Text	Text	custom	Text	Basic Text renders Markdown. No supporting variant or format.
TextInput	TextInput	custom	TextField	Missing currency/email/phone/url/search kinds, help text and autocomplete.
Toggle	Toggle	custom	CheckBox	No description or immediate-apply action.
Views	Views	custom	Tabs	No view keys or selected-view binding.

Where every child slot of a component is restricted, the catalog sets allowedChildren: ActionBar, Card, Status, Confirm and Table.

Lossy fields

These Polyxd fields have no A2UI representation. When a document contains them, they appear in lossy as JSON Pointers:

Polyxd field	Why	Carried in
/$schema	Editor hint	(dropped)
/specVersion	A2UI versions messages, not documents	surface metadata.extensions.com_polyxd
/surface/title	createSurface has no title	surface extension
/surface/intent	No task semantics in A2UI	surface extension
/surface/pattern	No pattern semantics	surface extension
/surface/journey	No journey semantics	surface extension
/surface/dismissible	No surface-level dismiss flag	surface extension
/components/N/key	Stable semantic key for interface memory. A2UI ids are surface-local.	component extension
/components/N/.../action/event/context on a ui.* action	A2UI local function calls take no event context	(dropped)

The Polyxd root id is not lossy. It becomes root and appears in idMap and the surface extension. Everything else, including format, visible, validation, options from data, badges, tones and nested item keys, is represented because it is a prop of a Polyxd catalog component. All 20 example documents report /surface/title and /specVersion, plus their intents, patterns and component keys.

Scripts

• npm test: node --test "test/**/*.test.ts". Checks that the catalog is up to date and valid against catalog_definition.json and the A2UI catalog rules. Exports all 20 @polyxd/spec examples in both modes and validates every message against agent_to_renderer.json, with tree checks and spot checks of ids, children, templates, bindings, actions, accessibility and lossy.
• npm run build:catalog: regenerates catalog/catalog.json.

Not yet verified / follow-ups

• Official React renderer: @a2ui/react 0.11.1 (latest on npm, 2026-09) only has v0_8 (default) and v0_9 entry points. @a2ui/web_core ships the v1.0 JSON schemas but no v1.0 renderer. Exported v1.0 streams therefore can't be rendered by an official renderer yet. Even once they can, the renderer needs implementations for the 24 Polyxd catalog components. That is the job of a Polyxd React catalog on top of @a2ui/react, and it is the remaining half of the decision-0001 exit test.
• Basic-only fallback: An optional lossy mode that flattens into Basic components (the a2ui notes in components/*.json) would let stock renderers show something. It is not implemented.
• Upstream movement: A2UI v1.0 is a release candidate. Re-vendor and re-run the tests when it is final.