Hypergraft

NOTE: Experimental. Not ready for general use.

Hypergraft is a bounded HTML-over-HTTP and WebSocket protocol for server-rendered Axum applications.

Ordinary Axum pages already serve documents, links and forms. Hypergraft adds enhanced navigation, command patches and live projections to those pages. The server stays authoritative.

JavaScript is required for live projections and command patches. HTTP still serves each initial document, deep link, reload and canonical GET page. Real links and forms define navigation, queries and commands. A native POST without patch metadata receives a no-store 400 before domain work.

Hypergraft has different goals to htmx. htmx supports backend-independent HTML swaps with attributes that select targets and swap behaviour. Hypergraft is a closed protocol for Axum and Askama. It owns request classification, bounded envelopes, one live socket and a JavaScript-required runtime. Commands are patch-only.

The source-preview Rust API and browser API remain experimental. Protocol version 1 is the versioned wire contract.

Run the example

The repository includes an anonymous shared task list. It has no sign-in page and no database. The process stores tasks in memory. A restart restores the seed data.

The example needs mise and a local checkout. mise supplies the pinned Rust, Node.js and pnpm versions.

From the repository root, install the pinned tools and dependencies:

mise install
pnpm install --frozen-lockfile

Build the browser assets and start the server:

mise run example

Open http://127.0.0.1:3000/tasks.

This launch does not install Playwright browsers. Contributor browser tests need extra setup. Read CONTRIBUTING.md and Compatibility.

See a live update

JavaScript is required for this walkthrough.

1. Open http://127.0.0.1:3000/tasks?status=open in two tabs.
2. Make sure that both tabs show Write the weekly notes.
3. In the second tab, open Write the weekly notes.
4. Press Complete.
5. Make sure that the first tab removes that task without a reload.

The example README has longer walkthroughs:

• Create tasks with validation
• Complete tasks and show a revision conflict
• Watch live updates after commands

What to read next

• Agent integration guide: a compact, self-contained reference for host applications.
• Anonymous task list
• Protocol version 1 and protocol-v1.json
• Host integration
• Browser runtime
• Live
• Security
• Compatibility

The streamed progress recipe and island recipe are separate from the reference application.

Adoption constraints

Patch targets use global document identifiers. Identifiers in inserted content and surviving document elements must match ^[A-Za-z][A-Za-z0-9_.:-]{0,127}$. They must be unique across the final document, including regions outside patch targets.

Intent prefetch requires a host eligibility policy and server response approval. Init options support marked links, exact route lists or all enhanced links. It permits one single-use navigation result for ten seconds from request start by default. Object options accept maxAgeMs to change that interval. HTTP responses retain no-store.

Private hosts own the route review and authorisation interval. Longer retention increases the interval between request-time authorisation and activation. The independent admission limit remains four requests per ten seconds. The prefetch contract defines valid ages and invalid-value errors.

Version 1 does not patch the document head. A titled patch updates document.title only.

History restoration is opt-in through scrollRestoration: true. Fresh responses restore window and registered container positions, with logical anchors before pixel offsets.

If the application serves private data, the host owns authentication and authorisation. Anonymous public data does not require authentication. Origin checks and CSP still apply.

Contribute

Read CONTRIBUTING.md before you propose a change. Report security issues through SECURITY.md.