ADR-001: Project Concept — Why HyperGen Exists

Status: Accepted Date: 2026-03-28 Authors: HyperGen founding contributors

---

Context

The Generative UI landscape in 2026 is experiencing a protocol explosion. Multiple specifications compete to define how AI agents transmit UI to clients: AG-UI (CopilotKit), A2UI (Google), Open-JSON-UI (OpenAI-derived), and MCP Apps (Anthropic/community). Each claims to be "agent-agnostic" and "open," yet all share a fundamental architectural assumption that we believe is flawed.

This ADR documents our critical analysis of these existing approaches and establishes the founding vision for HyperGen.

---

The Problem: False Agnosticism

Every existing Generative UI protocol claims agent-agnosticism — the ability to work with any AI agent framework. In practice, none achieve it. The reason is structural: they all introduce an intermediate representation (JSON schemas, component catalogs, proprietary event systems) that requires framework-specific integration code on both sides.

This is the "old abstraction" mindset: the belief that you need a translation layer between producer and consumer. But the web already has a universal representation for UI — HTML. The entire intermediation layer is unnecessary.

---

Critical Analysis of Existing Approaches

AG-UI (CopilotKit)

What it is: An event-based protocol connecting AI agents to frontend applications. Positioned as the "runtime channel" between agents and UIs.

What it gets right:

• Recognizes the need for a standardized agent-to-UI connection
• Event-based streaming design is conceptually clean (~16 event types)
• Transport-agnostic at the specification level (SSE, WebSocket, etc.)

What it gets wrong:

• Not actually a Generative UI protocol. AG-UI defines how agents and UIs communicate events, not how UI is generated. It delegates UI generation to A2UI, Open-JSON-UI, or MCP-UI — making it a transport layer, not a solution.
• CopilotKit lock-in. Despite "open" branding, the only complete frontend client is CopilotKit itself. The project originated as CopilotKit's internal agent integration layer. Community contributors have noted: "AG-UI was CopilotKit's internal tool for adding agent framework integrations using a standard." (GitHub Issue #291)
• SDK proliferation. Separate adapter packages exist for LangGraph, CrewAI, Google ADK, AWS Strands, Mastra, Pydantic AI, and more — each maintained independently. This is the exact opposite of agnosticism.
• Heavy dependency chain. The TypeScript SDK depends on RxJS, Zod, fast-json-patch, and uuid. The Python SDK requires Pydantic ≥2.11.2.

Verdict: AG-UI is a well-intentioned transport protocol masquerading as a Generative UI solution. Its real purpose is to funnel agent frameworks into the CopilotKit ecosystem.

---

A2UI (Google)

What it is: A declarative JSON specification for AI agents to describe UI components. Agents send structured JSON; clients render it natively.

What it gets right:

• Clean separation between UI structure, application state, and client rendering
• Flat component list with ID references is LLM-friendly (supports incremental generation)
• The "Surface" concept (dialog, sidebar, main view) is genuinely useful
• Transport-agnostic — works over A2A, AG-UI, SSE, WebSocket

What it gets wrong:

• Component catalog bottleneck. Agents can only use components defined in the client's catalog. Need a drag-and-drop widget? A custom data visualization? Too bad — if it's not in the catalog, you can't use it. This fundamentally limits what "Generative" means.
• Platform-specific renderers required. Despite claiming platform independence, you need separate renderer implementations for Web (Lit), Flutter, Angular, and planned React/SwiftUI/Jetpack Compose. Each renderer is a substantial engineering effort.
• Instability. v0.8 (public preview) with v0.9 already introducing breaking format changes (nested → flat structure). v1.0 isn't expected until Q4 2026.
• JSON overhead for LLMs. While the flat structure helps, LLMs still need to produce valid JSON with correct component IDs, data binding paths, and structural relationships. JSON schema validation wrapping is required.
• A2UI alone is incomplete. Does not define transport, lifecycle events, or bidirectional interaction semantics — needs AG-UI or another protocol for those.

Verdict: A2UI is the most thoughtfully designed of the existing specifications, but its component catalog approach recreates the limitations of pre-shadcn/ui component libraries — a fixed vocabulary that constrains rather than enables.

---

Open-JSON-UI (OpenAI-derived)

What it is: An open standardization of OpenAI's internal declarative UI schema. Optimized for LLM token efficiency and generation accuracy under JSON Schema constraints.

What it gets right:

• Prioritizes "ease of generation" — minimal nesting, flat content arrays
• Aligns with OpenAI's Structured Outputs for reliable JSON generation
• Acknowledges the fundamental trade-off between generation ease and rendering precision

What it gets wrong:

• Cannot render standalone. Requires AG-UI/CopilotKit ecosystem or a translation layer (e.g., SimpleA2UI) to actually display anything.
• No independent ecosystem. No standalone npm package, no SDK, no official specification document from OpenAI. It exists primarily within CopilotKit's orbit.
• Layout semantics are limited. Precise layout control is impossible; the renderer must infer intent.
• The core trade-off is a dead end. By choosing "ease of generation" over "rendering precision," Open-JSON-UI produces JSON that is ambiguous for renderers. This means clients must make assumptions, leading to inconsistent results across platforms.

Verdict: Open-JSON-UI is an honest acknowledgment that making LLMs produce structured UI definitions is hard — but its solution (make the format simpler) merely shifts the complexity to the renderer without solving it.

---

MCP Apps (Anthropic / Community)

What it is: An extension to MCP (Model Context Protocol) that allows MCP servers to return interactive HTML interfaces, rendered in sandboxed iframes.

What it gets right:

• HTML-native approach. Server sends full HTML — the most universal UI representation. This aligns with HyperGen's philosophy.
• Strong security model. 4-layer defense: iframe sandbox, pre-declared templates, auditable JSON-RPC messages, user consent.
• Broad client support. Claude, ChatGPT, VS Code GitHub Copilot, Goose, and more.
• Pragmatic design. Uses ui:// URI scheme for resource declaration and text/html;profile=mcp-app MIME type.

What it gets wrong:

• No streaming. MCP Apps delivers complete HTML payloads. There is no incremental rendering — the entire widget must be generated before it appears. This is the critical gap that HyperGen fills with HTMX's SSE extension inside the iframe.
• Heavy client-side requirements. Despite using HTML, the JSON-RPC 2.0 over postMessage bridge and security infrastructure require significant client implementation effort.
• MCP coupling. Only works within the MCP ecosystem. An agent that doesn't speak MCP cannot use MCP Apps.
• Static after render. Once the HTML is delivered, interactivity requires the iframe's own JavaScript. There is no declarative interactivity pattern like HTMX provides.

Verdict: MCP Apps is the closest existing approach to HyperGen's vision — it correctly identifies HTML + sandboxed iframes as the right medium. HyperGen builds on this foundation by adding HTMX for declarative interactivity and SSE for streaming, while removing the MCP coupling to achieve true agent-agnosticism.

---

The Insight: HTML Already Won

All four approaches share a hidden assumption: the agent's output needs to be translated into something before it becomes UI. AG-UI translates events into component updates. A2UI translates JSON into platform-native widgets. Open-JSON-UI translates flat JSON into renderable structures. MCP Apps wraps HTML in iframe sandboxes.

But consider what Claude already does when generating UI: it writes HTML and CSS directly. This is not a limitation — it's a strength. HTML is:

• Universal: Every browser renders it. No SDK required.
• Streamable: HTML fragments can be sent and rendered incrementally.
• Interactive (with HTMX): HTMX attributes make static HTML interactive with zero JavaScript.
• LLM-native: LLMs are trained on vastly more HTML than any JSON UI schema. HTML generation is more reliable and more expressive.
• Inspectable: Users can view source, copy, and modify generated UI. The shadcn/ui principle of code ownership applies naturally.

The missing piece has always been interactivity and streaming — and that's exactly what HTMX provides.

---

Decision

We are building HyperGen: an HTMX-based protocol for Generative UI that treats HTML fragments as the universal interface between AI agents and clients.

Core Principles

1. HTML is the protocol. Agents generate HTML with HTMX attributes. No intermediate JSON representation. No component catalogs. No proprietary event systems.

2. Truly agent-agnostic. Any system that can output an HTML string can participate. No SDK required. No adapter packages. No framework-specific integration code.

3. Streaming-first. HTML fragments are streamed via SSE and incrementally rendered using HTMX's built-in swap mechanisms. UI appears progressively as the agent generates it.

4. HTMX for interactivity. HTMX attributes (hx-get, hx-post, hx-target, hx-swap, hx-trigger) provide declarative interactivity without JavaScript. User interactions flow back to the agent as standard HTTP requests.

5. Scope (B): Specification + reference implementation. We publish a protocol specification and a minimal reference implementation. The reference is meant to be copied and adapted (shadcn/ui model), not installed as a dependency.

6. CSS variable-based theming. Generated UI inherits the host application's design system through CSS custom properties. No style conflicts, no design system coupling.

7. Sandboxed iframe rendering. Generated UI is rendered inside a sandboxed iframe for security isolation. HTMX operates within the iframe, communicating directly with the agent server. Host application integration uses postMessage. This combines MCP Apps' security model with HTMX's interactivity — see ADR-004.

What HyperGen is NOT

• Not a framework. No npm install hypergen. No build step required.
• Not a component library. No fixed vocabulary of widgets. Agents generate whatever HTML they need.
• Not an agent framework. HyperGen doesn't care how your agent works internally.

---

Consequences

Positive

• Zero integration cost for agents. Any agent that outputs HTML can use HyperGen immediately. This is a fundamentally lower bar than any competing protocol.
• Familiar technology. HTML + HTMX is understood by millions of developers. No new concepts to learn.
• Progressive enhancement. HyperGen UI works even without JavaScript (basic HTML), becomes interactive with HTMX, and can be enhanced further with custom JavaScript.
• Streamable by default. SSE + HTMX fragment swapping provides real-time progressive rendering out of the box.

Negative

• Web-only (initially). HTML is a web technology. Native mobile and desktop applications would need a WebView or an HTML rendering layer. This is a conscious trade-off — we optimize for the web platform first.
• iframe overhead. Sandboxed iframes add a layer of indirection. CSS variable injection from host to iframe requires explicit bridging. This is an acceptable trade-off for security.
• Less precise than catalog-based approaches. A2UI's component catalog guarantees consistent rendering. HyperGen's raw HTML approach means visual consistency depends on the agent's adherence to CSS variables and the host's design system.

Risks

• iframe escape attacks. While sandboxed iframes are strong isolation boundaries, misconfigured sandbox attributes could weaken security. Mitigation: the specification defines a strict default sandbox policy — see ADR-004.
• HTMX dependency. While HTMX is lightweight (14KB), it is still a dependency. Mitigation: HTMX is a single script tag with no transitive dependencies, and HyperGen can work with basic HTML even without it (losing interactivity).

---

References

• AG-UI Protocol — CopilotKit's agent-UI protocol
• A2UI — Google's declarative agent UI specification
• Open-JSON-UI — OpenAI-derived UI schema
• MCP Apps — MCP's HTML-in-iframe extension
• HTMX — Hypermedia-driven interactivity
• How Claude's Generative UI Works — Architecture analysis of Claude's approach
• Hypermedia Systems — The philosophical foundation
• shadcn/ui — The ownership model we follow for reference implementations