feat(a2ui): add A2UI spec v0.9 rendering support alongside v0.8

[lwangverizon]

Summary

adk-web can currently render A2UI spec 0.8 only. The renderer pins @a2ui/angular@^0.8.3, and both A2UI ingestion paths in chat.component.ts duck-type the 0.8 message kinds (beginRendering, surfaceUpdate, dataModelUpdate). An agent that emits 0.9 kinds (createSurface, updateComponents, updateDataModel, deleteSurface) is dropped silently — a2uiData is never populated, so nothing renders and no error surfaces anywhere.

This PR adds 0.9 support alongside 0.8, auto-detecting the spec version per payload, with no behavior change intended for existing 0.8 agents.

Motivating case: the staged-ui-widgets sample in adk-samples, which pins A2UI_VERSION = "0.9" and emits {"version": "v0.9", "createSurface": {...}}.

Note

Draft: the code is complete and CI-clean (678 unit tests green, ng build clean), but the manual browser verification in the checklist below has not been run yet. Marking ready once it passes. Design feedback very welcome in the meantime — particularly on the two questions at the bottom.

Approach

Version detection is per payload, not global. A new normalizeA2uiMessages in chat.component.ts prefers the explicit version discriminator and falls back to kind-key matching (the two versions' kind keys are disjoint, so this is unambiguous). Both ingestion paths — A2A DataParts and the inline <a2ui-json> text block — route through it.

The 0.8 renderer is not modified. A2uiCanvasComponent and its bindings are untouched; 0.9 gets a sibling A2uiCanvasV09Component and content-bubble.component.html dispatches on version. The two renderers have genuinely different lifecycles — 0.8's <a2ui-surface> needs a resolved [surface] object re-read from a Map on every ngOnChanges, while 0.9's <a2ui-v09-surface> takes only a surfaceId and resolves internally in ngOnInit — so sharing one component would have meant branching inside it. Keeping 0.8 literally unmodified is also the airtight guarantee against 0.8 regressions: its spec needed no edits.

Both renderers are always registered. No conditional provider gating; dispatch is payload-driven.

A2uiPayload.messages is an array because 0.9 legitimately sends N updateComponents/updateDataModel messages across several surfaces, which the existing three-slot last-wins object cannot represent. The three 0.8 aliases (beginRendering/surfaceUpdate/dataModelUpdate) are still populated for 0.8 payloads so the 0.8 render binding stays byte-identical.

Commits

Seven, each independently reviewable; the tree compiles and tests green at every step.

1	chore(deps) — package.json only
2	chore(deps) — regenerated package-lock.json alone, so it can be collapsed
3	refactor(a2ui) — pin 0.8 imports to the /v0_8 subpath; repair 0.8 regressions from the bump
4	feat(a2ui) — A2uiPayload + the normalizer. No rendering change yet
5	feat(a2ui) — the v0.9 canvas + main.ts providers. Not yet reachable from a template
6	feat(a2ui) — the content-bubble dispatch. This is the commit that turns the feature on; reverting it disables 0.9 without touching anything else
7	feat(a2ui) — the --a2ui-* theme block

Commit 3 going green is the evidence that the 0.9 bump did not break 0.8. Please don't squash 4 into 6 — the normalizer carries the highest 0.8-regression risk and is worth keeping bisectable on its own.

Dependencies

-    "@a2ui/angular": "^0.8.3",
+    "@a2ui/angular": "^0.9.1",
+    "@a2ui/lit": "^0.8.3",
+    "@a2ui/markdown-it": "^0.0.3",

• @a2ui/angular@0.9.1 ships both versions via the ./v0_8 and ./v0_9 subpath exports, so this is additive rather than a migration. Peer is @angular/core ^21.2.0 and the lockfile already resolves 21.2.4 — no Angular bump.
• @a2ui/lit@0.8.3 is promoted transitive → direct. 0.9 drops it, which would break a2ui-theme.ts's Styles import. Styles.merge cannot be hand-rolled to a spread: 8 of its 13 call sites merge different keys in the same color-c-* family, and a spread would leave two conflicting classes set.
• @a2ui/markdown-it@0.0.3 is an optional peer, but TextComponent injects MarkdownRenderer unconditionally and DefaultMarkdownRenderer does a bare await import('@a2ui/markdown-it'), which esbuild errors on when undeclared.

@a2ui/web_core is deliberately not added. I verified with tsc that Parameters<A2uiRendererService['processMessages']>[0][number] resolves to the real A2uiMessage rather than degrading to any, so the direct dependency isn't needed.

⚠️ One 0.8 behavior change to flag

Commit 3 adds provideMarkdownRenderer() to main.ts. This is a 0.8 fix, not 0.9 setup: MarkdownRenderer is providedIn: 'root' but its base class has no render method, so after the dep bump every 0.8 Text component threw render is not a function at a2ui-angular-v0_8.mjs:1446. The explicit provider swaps in DefaultMarkdownRenderer, which has it.

The side effect is that 0.8 Text now renders real markdown through @a2ui/markdown-it (with DOMPurify) instead of the regex passthrough. I confirmed @a2ui/markdown-it loads rather than falling back. This is a 0.8 rendering change and it's on the verification checklist below, but reviewers who know the 0.8 rendering expectations should look at it directly.

Theming

v0.9 has no theme object. Unlike 0.8, which is themed in TypeScript through the Theme token, 0.9 injects no root stylesheet and defines no a2ui-light/a2ui-dark classes — every component styles itself with inline var(--a2ui-X, <fallback>), and all but a handful of those fallbacks are hardcoded light-mode values (#fff, #333, #ccc). Without commit 7, 0.9 surfaces are unreadable in adk-web's default dark theme, so it's a correctness fix rather than a cosmetic one.

Commit 7 defines the ~50 --a2ui-* properties as var(--mat-sys-*). Because var() resolves at use time, the layer is pure indirection: a theme flip repaints --mat-sys-*, which repaints --a2ui-*. No JavaScript, no new classes, one definition site — ThemeService and styles.scss are untouched. It's scoped to :host rather than a global stylesheet, which also avoids two angular.json edits and keeps --a2ui-* out of the global namespace of an app embedding the component.

Three findings from reading the compiled 0.9 CSS, each commented at its mapping:

• The six --a2ui-font-size-* properties are mandatory. Upstream reads them as bare var(--a2ui-font-size-l) with no fallback, and an undefined custom property invalidates the whole declaration — every heading would silently drop to the browser default.
• --a2ui-color-on-secondary is the foreground of the default button, over an --a2ui-color-surface background. It maps to --mat-sys-on-surface; the intuitive --mat-sys-on-secondary-container gives low-contrast text.
• Two spots can only be reached from outside, via ::ng-deep: .a2ui-button:disabled hardcodes #e9ecef/#6c757d with no custom property, and the 0.9 CheckBox is a bare <input type="checkbox"> without appearance: none, so its --a2ui-checkbox-background/-border variables are inert and it renders in the browser's own light-mode chrome. accent-color is the one property a native checkbox honours. Both overrides should be deleted once upstream tokenizes them.

📌 Integration gotcha for agent authors

catalogId is required on 0.9 createSurface and must equal https://a2ui.org/specification/v0_9/basic_catalog.json, or surface creation fails silently — a console.warn and an empty div. This is the single most likely thing to trip up an agent author.

Because that failure mode is invisible, chat.component.spec.ts wires the real 0.9 provider graph rather than a stub, and asserts console.error was not called on the happy path. That's what converts the silent degradation into a test failure.

Tests

678 passing, up from 643 on main; ng build clean.

• chat.component.spec.ts — 15 table-driven detectA2uiVersion cases (envelope discriminator, kind-key fallback both ways, {}, unknown key, null, a string); a multi-message 0.9 fixture on both ingestion paths; <a2ui-json>[]</a2ui-json> leaves a2uiData undefined and still strips the text; a mixed-version batch warns.
• a2ui-canvas-v09.component.spec.ts (new) — dispatch and surfaceId derivation; no change record → no call; the same array reference twice → exactly one call; surfaceId derived from updateComponents alone (the cross-bubble streaming case); a redundant createSurface skipped so a history reload doesn't throw Surface already exists; a failed message contained without abandoning the rest of the batch; and the @if gate.
• content-bubble.component.spec.ts (new) — there was no spec for this component, and it's the file that catches a mis-dispatch. 0.8 → app-a2ui-canvas only; 0.9 → app-a2ui-canvas-v09 only; absent a2uiData → neither; untagged → falls back to 0.8.

Two notes on deliberate test choices:

• The @if (surfaceId()) gate in the 0.9 canvas template is load-bearing, not cosmetic — ComponentHostComponent.ngOnInit looks its surface up once and, on a miss, warns and never retries (a missing component, by contrast, recovers via componentsModel.onCreated). The gate guarantees createSurface has been processed before the child mounts, and there's a test for it.
• 0.9 fixtures are plain objects checked structurally, not as unknown as <Type> casts. The 0.8 spec uses those casts in four places, which erases all compile-time checking.

chat-panel.component.spec.ts's A2UI test stays xit, now with a comment explaining why: chat-panel doesn't own the canvas (the chain is chat-panel → event-row → event-content → content-bubble → a2ui-canvas) and its TestBed provides none of the A2UI DI graph, so re-enabling it is high-cost and redundant with the new content-bubble spec.

Verification checklist (outstanding — why this is a draft)

npm test and ng build are green. No unit test can catch a catalogId mismatch or 0.9's silent-degradation failure modes, so the following still needs a browser:

• A surface exercising Card / Button / TextField / Tabs / Modal / Slider / Checkbox, in both dark and light mode
• Toggling the theme while a surface is mounted (should be instant — pure CSS indirection)
• History reload of a session containing 0.9 surfaces
• Streaming where createSurface and updateComponents land in different events/bubbles
• An existing 0.8 agent still renders identically — including the markdown change flagged above
• Devtools console clean throughout; any a2ui warn/error treated as a failure

One known residual hazard I could not rule out by reading: if re-processing createSurface on a history reload constructs a new SurfaceModel, an already-mounted child holds a stale reference and blanks. The redundant-createSurface skip should prevent it. If the reload check shows a blank surface, the fix is a surfaceGeneration signal driving a keyed @for to force child recreation.

Explicitly out of scope

• event.actions.render_ui_widgets with provider: "a2ui" — the staged-ui-widgets sample's other incompatibility. I checked and this is not a standard A2UI contract: zero references in the A2UI spec repo, and A2UI's own official ADK sample uses A2A DataParts. It looks like a standard ADK API rather than a standard A2UI one, which makes it a maintainer question — tracked on A2UI does not work with ADK web #447. This PR adds 0.9 vocabulary support only; the sample can be updated separately to deliver over the <a2ui-json> text block, which I verified renders live and not only on history reload.
• Pre-existing latent issue at main.ts: {provide: Theme, useValue: A2UI_THEME} supplies a plain object where the Theme class is expected. It works only because consumers read exactly the four fields Theme exposes and A2UI_THEME happens to have exactly those four (upstream's own provideA2UI() does const t = new Theme(); t.update(config.theme)). Left alone — changing it invites regressions unrelated to this PR.
• Duplicate zod majors in the bundle — the app uses 4.x, web_core needs ^3.25.76. Already the status quo; npm nesting handles it and the two never meet at a type boundary. Deliberately not forcing a dedupe via overrides: zod 4 is not backward compatible and web_core's schema parsing would break at runtime, silently. Happy to measure with ng build --stats-json as a follow-up if you'd like.

Questions for maintainers

1. actionHandler is a console.debug stub with a TODO. 0.9 client actions (button clicks, field edits) are logged but not routed back to the agent. 0.8 does this through MessageProcessor.events. Should wiring that up land in this PR, or as a follow-up once the 0.9 rendering path is agreed? I left it out to keep this reviewable, and because the interactive round-trip deserves its own tests.
2. provideA2Ui() does not exist in 0.9.1 (it arrives in 0.10.5), so A2UI_RENDERER_CONFIG is registered by hand and A2uiRendererService is listed explicitly — it's a plain @Injectable() with no providedIn, unlike 0.8's MessageProcessor. Would you rather target 0.10.x now and use provideA2Ui()? I targeted 0.9 to match the spec version the sample pins, but that hand-rolled provider block is the part most likely to churn on the next upgrade.