A2UI Catalog

The A2UI catalog turns A2UI from a custom-per-deploy capability into a marketplace ecosystem. Twenty vetted composite surface presets ship with the SDK; install one with a single CLI command and the agent gains the ability to render a contractually-bounded UI moment.

What a catalog component is

Each catalog entry under a2ui-catalog/ is a thin composition layer on top of basicCatalog. It bundles:

• Frame factory (preset.ts) — buildFrames(seed): A2UIv09Frame[]. The agent transport calls this to emit a streaming surface.
• dataModel schema (schema.json) — JSON Schema subset validated by the SDK before the surface mounts. If validation fails the renderer falls through to A2UI_RENDER_FAILED.
• Action allowlist (actions.ts + manifest actionPolicy) — explicit allow and confirm arrays. Anything else is blocked at the action bridge.
• Host React renderer (component.tsx) — optional override for hosts that bypass @a2ui/react, required for Tier D experimental components.
• Mock scenario (mock.ts) — MockScenario factory used by the showcase gallery and customer test suites.
• i18n keys (i18n.ts) — defaultLocale and reserved key names. v1 ships English strings; translations land in v1.1.
• Manifest (manifest.json) — typed source of truth. Mirrors schemas/ui-catalog-manifest.schema.json.

Lifecycle states

Every manifest declares one of three lifecycles:

• stable — basicCatalog primitives only, full WCAG 2.2 AA via axe, visreg-covered. Safe for production.
• experimental — requiresCustomPrimitives: true. basicCatalog cannot express the surface (canvas, map, table), so a host React renderer is required. v1 documents reduced a11y guarantees; full coverage is v1.1.
• deprecated — manifest stays in the catalog for graceful migration; gecx ui:doctor flags installed copies.

Integrity and version drift

scripts/build-ui-catalog-registry.ts computes sha256 over each component's files[] and embeds it in the manifest. The CLI writes the same hash into .gecx/install.log at install time, and gecx ui:doctor recomputes the hash against the installed copy on demand.

• Local edits to an installed component → reported as integrity_drift. The host knows the file has diverged from its installed origin.
• Pinned version older than the registry's → reported as outdated. Upgrade with gecx add ui:<name> (re-installs latest).
• Component lifecycle changed to deprecated → surfaced in gecx ui:doctor.

Telemetry is local-only in v1: the install log lives in .gecx/install.log under your project root and never leaves the host. Pass --no-telemetry to gecx add to skip it.

ProductAnalytics integration

Three new event variants land in schemas/product-analytics.schema.json:

• a2ui_catalog_install — emitted by the CLI when a component is added.
• a2ui_catalog_render — emitted by A2UISurface.tsx when a catalog-recognized surface mounts.
• a2ui_catalog_action — emitted by useA2UIActionBridge.ts for every action with its allow/confirm/block decision.

These flow into the existing showcase /analytics dashboard.

Storybook vs. Playwright preview routes

We do not ship Storybook. Each component renders inside the showcase at /components/<slug> using the real useChatSession + createMockTransport + A2UISurface code path. Playwright's toHaveScreenshot() captures baselines under apps/showcase/tests/__screenshots__/a2ui-catalog/, axe-core scans the same DOM. This gives us authentic protocol coverage — Storybook would only exercise the React layer.

When to use the catalog vs. a custom A2UI surface

• Use a catalog component when one matches your use case. You get free a11y, action policy, integrity guarantees, and analytics events.
• Build a custom A2UI surface (see apps/applied-ai-retail/src/lib/retailTransport.ts giftBundleFlow) when your moment doesn't fit any catalog entry. Use a catalog component's manifest as a template for the contract.

Acceptance contract

Every catalog component must:

1. Emit frames that pass validateA2UIFrame for each A2UIv09Frame variant.
2. Seed a dataModel that validates against its declared dataModelSchema.
3. Emit only actions declared in actionPolicy.allow ∪ actionPolicy.confirm.
4. Pass axe WCAG 2.2 AA on its preview surface (stable tier).
5. Carry a toHaveScreenshot baseline (stable tier).
6. Be installable via gecx add ui:<name> into a fresh project.

The shared test harness at a2ui-catalog/_shared/catalogTestHarness.ts enforces contracts 1–3 in vitest. Contracts 4–6 are enforced by the @a2ui-catalog-tagged Playwright suite.