We Derived htmx from a 4,000-Word Document

htxlang → The Derivation

What happened

We wrote a constraint seed — 3,937 words of English prose describing what htmx must do. Not how. What.

Then we fed it to an AI model and said: derive a conformant implementation. No code to look at. No reference. Just the prose.

It worked.

Not approximately. Not "similar to htmx." It passes 53 of 54 tests designed for a completely separate implementation built over months of iterative development.

The constraint seed

The seed is 19 constraints organized into four rings:

Core (C1–C6)	HTTP verbs, swap strategies, target resolution, triggers, boost
Ring 1 (C7–C10)	Response headers, out-of-band swaps, script eval, public API
Ring 2 (C11–C14)	Config system, history cache, composable parameters, event lifecycle
Ring 3 (C15–C19)	SSE/WebSocket, extensions API, validation, disinherit, credentials

Each constraint is one sentence stating an invariant. Example:

C2: The response from the server is HTML. The library does not parse JSON. The server returns an HTML fragment; the library swaps it into the DOM.

That's it. No pseudocode. No algorithms. Just: what must be true.

Read the full seed →

The convergence experiment

We didn't just derive once. We derived, diffed against our reference, tightened the seed, and derived again. Four times.

Iteration	Seed	Blind derivation	vs reference
v1	2,685 words	2,160 lines	+64%
v2	3,611 words	1,648 lines	+25%
v3	3,727 words	1,433 lines	+8%
v4	3,937 words	1,373 lines	+4%
v4.1	3,937 words	1,057 lines	-19%

Reference implementation: 1,316 lines. The blind derivation converged to within 4% — then overcorrected to 19% under. The prose is now tight enough that the model produces a more compact implementation than we did by hand.

The behavioral pin

Here's where it gets interesting.

When we ran our 54-test suite against the v4 blind derivation, only 34 tests passed (63%). The page went haywire — tests looping, redirecting, racing each other.

Root cause: one missing sentence in the seed. The derivation's init() function was re-executing the page's own <script> tags, causing an infinite loop.

We added one constraint:

Script re-execution and hx-on binding are swap-only operations, never called during init().

One sentence. 19 test failures resolved. Pass rate: 63% → 98%.

That's the pin-art model: one constraint, precisely placed, determines the shape of 19 features.

Two implementations, one seed

We now have two independent implementations derived from the same constraint seed. One was built iteratively over a session. The other was derived blind — from the seed alone — by a model that never saw the first.

	htmx-derived.js (iterative build)	htmx-fresh-v4.js (blind from seed)
Lines	1,316	1,057
Bytes	53 KB	36 KB
Named functions	41	32
hx-* attributes	29	28
Events	32	32
Tests passing	54 / 54	53 / 54

The blind derivation is 20% smaller than the iterative build — and passes 98% of the same tests. It's more compact because the seed's structural constraints eliminated code our iterative build accumulated: section-header comments, decorator lines, extra helper functions.

Both are drop-in replacements for htmx. Same hx-* namespace. Same behavior. Different paths to the same destination.

What does this mean for htmx users?

htmx is 14,000 lines of development source. Built feature-by-feature over 11 years.

The blind derivation is 1,057 lines. Same behavior. Derived from 3,937 words of prose by a model that never saw htmx's source code.

The difference is not compression. It's a different kind of object. htmx is a library — it has history, edge cases, backwards compatibility. The seed is a specification — it has invariants. The library accretes. The specification determines.

The deeper point: the behavior of htmx can be captured in 19 sentences. Everything else is implementation detail.

Try it yourself

The method

This is called the derivation inversion. Instead of building features and hoping they cohere, you state the constraints and derive the implementation. The constraints are the primitive unit, not the features.

It works because constraints compose predictably. Features interact in ways you can't see until you build them. Constraints have defined boundaries. When you add a constraint, you know exactly what it determines and what it leaves open.

The pin-art model is the analytical framework: each constraint is a pin pressed into foam. The foam is the space of possible implementations. The pins determine the shape. The more pins you press, the less freedom the foam has, the more the derivation converges to a specific implementation.

We pressed 19 pins. The foam had 57 lines of freedom left.

---

Full technical write-up (Doc 288) · Convergence experiment (Doc 289) · Mathematical formalization (Doc 290) · Source on GitHub