ADR-003: HTMX as the Interactivity Layer

Status: Accepted Date: 2026-03-28

Context

HyperGen's core thesis (see ADR-001) is that HTML itself should be the protocol for Generative UI. But static HTML alone is insufficient — users need interactive interfaces: forms that submit, content that updates, widgets that respond to clicks.

The question is: how do we add interactivity to agent-generated HTML without requiring the agent to produce complex JavaScript, and without requiring the client to install a heavy framework?

The Anthropic Insight

Claude's Generative UI approach (as documented in Saurabh Singh's architecture analysis) demonstrates a key insight: LLMs excel at generating raw HTML and CSS. Claude produces complete, styled interfaces — not JSON descriptions of interfaces.

This works because:

1. LLMs are trained on vastly more HTML/CSS than any JSON UI schema. The web's corpus is HTML. Generation quality and reliability are inherently higher.
2. HTML + CSS is self-contained. No build step, no bundler, no framework runtime. The output is the UI.
3. CSS custom properties enable design system integration. By defining --color-surface, --color-accent, etc., the host application's design system flows into generated UI automatically.

However, Anthropic's approach requires significant infrastructure to make generated UI interactive:

• Partial JSON parsing for streaming tool call arguments
• Morphdom for incremental DOM diffing
• Custom script execution (replacing <script> tags with programmatically created elements)
• A bidirectional communication bridge (window.sendToAgent)

This is where HTMX enters. HTMX provides all of this interactivity — declaratively, in HTML attributes, with zero custom infrastructure.

Decision

HyperGen adopts HTMX as its interactivity layer. Agents generate HTML with HTMX attributes to create interactive UI. The host application includes HTMX (14KB, single script tag) to process these attributes.

What HyperGen Generates

A HyperGen-compliant agent generates a complete UI artifact consisting of three layers:

1. HTML Structure (Required)

Semantic HTML with HTMX attributes for interactivity:

<form hx-post="/api/agent/submit" hx-target="#result" hx-swap="innerHTML">
  <input type="text" name="query" placeholder="Ask a question..." />
  <button type="submit">Send</button>
</form>
<div id="result"></div>

This is just HTML. An LLM generates this as naturally as it writes a paragraph.

2. CSS Styling (Generated alongside HTML)

Inline styles or <style> blocks using the host's CSS custom properties:

<style>
  .hg-card {
    background: var(--hg-surface);
    color: var(--hg-text);
    border: 1px solid var(--hg-border);
    border-radius: var(--hg-radius);
    padding: var(--hg-space-4);
  }
  .hg-btn {
    background: var(--hg-accent);
    color: var(--hg-accent-foreground);
  }
</style>

Following Anthropic's approach: the agent generates CSS that references the host's design tokens via CSS variables. The host defines these variables; the agent uses them. No style conflicts, no CSS-in-JS runtime.

3. JavaScript (Minimal, when necessary)

Most interactivity is handled by HTMX attributes alone. When additional behavior is needed (e.g., local calculations, animations, chart rendering), inline <script> blocks are included:

<script>
  // Local-only logic that doesn't need server round-trips
  document.querySelector('#slider').addEventListener('input', (e) => {
    document.querySelector('#value').textContent = e.target.value;
  });
</script>

Key principle: JavaScript is for client-local behavior. Server communication always goes through HTMX attributes.

Why HTMX Specifically

Alternatives Considered

Why HTMX Wins

1. LLMs can generate it perfectly.

HTMX attributes are just HTML attributes. There is no new syntax, no DSL, no compilation step. An LLM that can write <a href="..."> can write <button hx-get="/data" hx-target="#output">. The training data contains millions of HTMX examples.

2. Interactivity without JavaScript.

HTMX handles the five problems identified in Claude's Generative UI architecture:

3. Streaming is first-class.

HTMX's SSE extension enables progressive rendering natively:

<div hx-ext="sse" sse-connect="/api/agent/stream" sse-swap="message">
  <!-- Content appears here as the agent generates it -->
</div>

No Morphdom. No partial JSON parsing. No custom streaming infrastructure. HTMX handles it.

4. Bidirectional communication is built in.

When a user interacts with generated UI (clicks a button, submits a form), HTMX sends a standard HTTP request back to the server. The agent receives this as a new input and can respond with updated HTML. This creates the same feedback loop as Claude's window.sendToAgent, but using standard web mechanics.

5. Progressive enhancement.

A HyperGen UI works at three levels:

• Without HTMX: Static HTML renders. Links and forms work via standard navigation. Degraded but functional.
• With HTMX: Full interactivity via hx-* attributes. No page reloads. Streaming works.
• With HTMX + inline JS: Enhanced local behavior (animations, calculations, charts).

6. 14KB, zero dependencies.

HTMX is a single script tag. No npm install. No build step. No transitive dependency graph. This aligns perfectly with HyperGen's philosophy.

HTMX Attributes in HyperGen Context

The following HTMX attributes are most relevant to Generative UI:

Consequences

Positive

• Minimal client infrastructure. One <script> tag (HTMX) replaces Morphdom, partial JSON parsers, custom streaming code, and bidirectional bridges.
• LLM generation reliability. HTML attributes are in the LLM's strongest generation domain. No JSON schema validation needed.
• Standard web patterns. HTTP requests, SSE, HTML fragments — all battle-tested, well-documented, widely understood.
• Progressive enhancement. Generated UI is functional even without HTMX loaded.

Negative

• Web-only. HTMX is a browser technology. Native mobile/desktop apps would need a WebView. (Accepted trade-off — see ADR-001.)
• Server round-trips for interaction. Every user action triggers an HTTP request. For high-frequency interactions (drag-and-drop, real-time drawing), inline JavaScript is needed instead.
• HTMX learning curve for LLMs. While HTMX attributes are simple HTML, LLMs may need prompt engineering or system instructions to use them correctly. The specification will define recommended prompt patterns.

Open Questions

• HTMX version pinning. Should HyperGen target a specific HTMX version or a feature set? HTMX 2.x is current and stable.
• Extension strategy. HTMX has extensions (SSE, WebSocket, etc.). Which extensions should be part of the HyperGen specification vs. optional?
• Sanitization of HTMX attributes. hx-get and hx-post can target arbitrary URLs. The security model (future ADR) must define which attributes are safe and which require sanitization.

References

• HTMX — Official documentation
• HTMX SSE Extension — Server-Sent Events support
• Hypermedia Systems — The philosophical foundation
• How Claude's Generative UI Works — Anthropic's approach analysis
• Hypermedia Friendly MCP App Architecture — HTMX + MCP essay
• HTMX: Replace React with 14KB HTML — Practical comparison
• Locality of Behaviour — HTMX design principle