Specification Overview
The HyperGen protocol specification: how AI agents stream interactive HTML via SSE into sandboxed iframes.
This document defines the HyperGen protocol — a standard for AI agents to deliver interactive user interfaces by streaming HTMX-attributed HTML fragments over Server-Sent Events (SSE) into sandboxed iframes.
The specification is normative. A conforming implementation MUST satisfy all requirements marked with MUST and MUST NOT. Requirements marked with SHOULD are strongly recommended. Requirements marked with MAY are optional.
Purpose
HyperGen defines the minimal contract between three participants:
- An agent server that generates HTML and streams it to a client
- A host application that embeds an iframe and manages its lifecycle
- The iframe document that receives streamed HTML, renders it with HTMX, and bridges events to the host
The specification covers the wire format, the iframe bootstrap document, the postMessage protocol between host and iframe, the CSS variable theming contract, and guidelines for agents authoring HTML fragments.
Terminology
| Term | Definition |
|---|---|
| Agent | Any server-side process that generates HTML fragments. This may be an LLM, a traditional server, or any system that outputs HTML. |
| Agent server | The HTTP server that exposes SSE and POST endpoints consumed by HTMX inside the iframe. |
| Host application | The top-level web application that creates and manages one or more HyperGen iframes. |
| Iframe | The sandboxed <iframe> element that renders agent-generated HTML. Also referred to as the "sandbox." |
| Bootstrap document | The complete HTML document loaded into the iframe. It includes HTMX, the SSE extension, the postMessage bridge, and base styles. |
| Fragment | A discrete unit of HTML sent by the agent as an SSE event. Fragments are swapped into the iframe's DOM by HTMX. |
| Theme | A set of CSS custom properties (--hg-*) injected from the host into the iframe to integrate with the host's design system. |
| Bridge | The postMessage-based communication channel between the iframe and the host. Used for theming, resize, navigation, and data exchange. |
Conformance Levels
This specification uses RFC 2119 keywords:
- MUST / MUST NOT — Absolute requirements. Non-compliance means the implementation is not conforming.
- SHOULD / SHOULD NOT — Strong recommendations. Deviation requires a documented reason.
- MAY — Truly optional. Implementations are free to include or omit.
Specification Sections
| Section | Defines |
|---|---|
| SSE Message Format | The Server-Sent Events wire format for streaming HTML fragments. Event names, keep-alive, stream lifecycle, required headers. |
| Iframe Bootstrap Document | The complete HTML document loaded into the iframe. Required elements, sandbox attributes, CSP, HTMX version requirements. |
| postMessage Protocol | All message types exchanged between the host and iframe. JSON shapes, origin validation, TypeScript type definitions. |
| CSS Variable Theming | The --hg-* CSS custom property namespace. Required and optional variables, defaults, injection mechanism. |
| Agent Authoring Guidelines | Best practices for agents generating HTML. HTMX attribute usage, styling, self-containment, accessibility. |
Design Rationale
The "why" behind HyperGen's architecture is documented in the Architecture Decision Records:
- ADR-001 — Why HTML is the protocol
- ADR-002 — Scope as spec + reference implementation
- ADR-003 — Why HTMX for interactivity
- ADR-004 — Sandboxed iframe security model
- ADR-005 — Zero custom HTMX attributes
This specification defines the "what." The ADRs explain the "why."
Versioning
This is version 0.1 of the HyperGen protocol specification. The protocol is in active development. Breaking changes are possible before version 1.0.