feat(client): generic Dynamic View Content fallback renderers (bundled A2UI default)

[liady]

Summary

A2UI is a generative-UI format: servers return a declarative, typed UI document (application/a2ui+json) in tool results, and a generic renderer displays it. This PR adds generic Dynamic View Content support to <AppRenderer /> — per the ext-apps spec proposal modelcontextprotocol/ext-apps#699 — with a bundled generic A2UI renderer as the default fallback. mcp-ui hosts can render A2UI-returning MCP servers even when the server ships no renderer resource at all, including servers not built with mcp-ui.

The content↔renderer matching is MIME-generic; only three things stay a2ui-specific: the bundled renderer artifact, its default registry entry, and the legacy allowance for unmarked a2ui-MIME blocks (existing A2UI servers don't set the _meta.ui.content marker yet).

What's included

• fallbackContentRenderers prop — a MIME-keyed registry of fallback renderers, each entry either the renderer's self-contained HTML string (the UMD/no-dynamic-import escape hatch) or an async loader resolving to it:
  • undefined (default, opt-out): DEFAULT_FALLBACK_CONTENT_RENDERERS — the bundled generic A2UI renderer, lazily loaded, for application/a2ui+json + legacy application/json+a2ui. A2UI results "just work" with zero wiring.
  • {}: disable all fallbacks. A custom registry replaces the default; spread DEFAULT_FALLBACK_CONTENT_RENDERERS to extend.
  • Registry keys also gate the beyond-spec leniency: unmarked embedded resources count as view content only when their MIME is a registry key.
• Renderer resolution order — html prop → toolResourceUri prop → tool's declared _meta.ui.resourceUri → NEW, spec-native: first marked block's _meta.ui.content.rendererUri (read via client or onReadResource) → fallback registry → existing errors (late-arriving results still supersede the initial error).
• Bundled generic A2UI renderer — a private, never-published a2ui-renderer workspace package (Lit-based via @a2ui/lit + @a2ui/web_core) built into a self-contained single-file HTML artifact, checked into git (linguist-generated) and re-emitted at build time as the lazy @mcp-ui/client/a2ui-renderer subpath export. Zero new runtime dependencies; main bundle unchanged (~117 KB).
• Detection helpers — generic: isViewContentBlock, getViewContentBlocks (marked blocks + opt-in unmarkedMimeTypes), getViewContentRendererUri; a2ui wrappers: hasA2uiContent, getA2uiContentBlocks, isA2uiContentBlock + MIME constants. The generic module is the single swap point for the official ext-apps helpers once feat: Dynamic View Content SDK support (types, helpers, example) modelcontextprotocol/ext-apps#700 ships.
• Host capability — UI_EXTENSION_CONFIG advertises contentMimeTypes: ['application/a2ui+json', 'application/json+a2ui'], test-locked to Object.keys(DEFAULT_FALLBACK_CONTENT_RENDERERS) so the two can't drift.
• Docs — client guide page reworked to lead with the generic Dynamic View Content model (docs/src/guide/client/a2ui.md).
• Bumped client @modelcontextprotocol/ext-apps to ^1.7.4 (same protocol 2026-01-26; separate commit, droppable).

How the renderer works

The bundled renderer is a standard MCP App (ext-apps App class) with zero server-specific logic:

1. A2UI payloads are extracted from tool-result content blocks by MIME type (text or base64 blob; single message or array); each ui/notifications/tool-result is a full re-render.
2. A2UI user actions map back to server tools: action name → tools/call, resolved context → arguments; responses are applied incrementally.

Verification

• 123 unit tests pass (generic view-content semantics, a2ui wrapper regressions, the full AppRenderer fallback matrix incl. rendererUri paths and registry replacement, artifact invariants, capabilities drift-lock).
• E2E: the actual built artifact was loaded in a sandboxed iframe against an ext-apps JSON-RPC host harness — the a2ui sample counter payload rendered, and clicking the button round-tripped tools/call increase_counter_v0_9 with incremental data-model updates (counter 0→1→2).

Possible next steps

• Native direct rendering of application/a2ui+json by the host (rendering A2UI surfaces as host-DOM components, without the iframe HTML renderer).
• Swap detection to the official ext-apps helpers when PR #700 is released, and swap the bundled artifact for an official a2ui-published renderer resource if one ships.

Notes

• The a2ui-renderer subpath's CJS entry is emitted as dist/a2ui-renderer.cjs (not .js), matching the require() extension fix from fix: emit CJS build so require('@mcp-ui/client') exposes exports #211 ("type": "module" makes CJS-content .js files unloadable by Node).

🤖 Generated with Claude Code