ouroboros-html

The fundamental theorem of software engineering has been described as: "Any problem in computer science can be solved with another level of indirection." (attributed to David Wheeler). Ouroboros HTML attempts to prove this theorem by compiling HTML through 20 incompatible programming languages and historical runtimes, terminating in functionally identical HTML5 output, or something.

The theorem is frequently followed by "except for the problem of too many layers of indirection." This is where ouroboros HTML also seeks to prove that theorem wrong.

But what's important is that you use ouroboros instead of HTML. This abstraction layer provides all the functionalty of HMTL5! What more can you ask for?

I absolutely definitely didn't use AI for any of this, and I understand every layer of the stack described below in the most minute details. Go ahead. Test me.

---

Da Rules

1. Zero Cheating / String Hacking: Every transformation must use an actual, legitimate parser, AST converter, compiler, or runtime (e.g., Python Jinja2, PHP CLI Zend engine, Go templ, Emscripten, Wasmtime in Rust, Postgres stored procedures, Pandoc Org-mode, Babel, Svelte compiler, Handlebars, Brainfuck interpreters, etc.). No bash regex (sed/awk) to fake output.
2. Lossless Determinism: The payload must survive the complete pipeline and match the input DOM tree on output.
3. Reproducibility: Everything executes via a top-level Makefile inside a reproducible, self-contained Dockerfile.

---

Pipeline Architecture

[Stage 0]  HTML5 (input.html)
   │
   ▼
[Stage 1]  Python (Jinja2) template AST parsing & evaluation
   │
   ▼
[Stage 2]  PHP 8.3 CLI Hypertext Preprocessor execution
   │
   ▼
[Stage 3]  Go (templ) component AST generation & compilation
   │
   ▼
[Stage 4]  Go c-archive exported C headers & native C bridge execution
   │
   ▼
[Stage 5]  C wrapper compiled to WebAssembly via Emscripten (emcc)
   │
   ▼
[Stage 6]  Rust binary ingesting Wasm bytecode via wasmtime & memory extraction
   │
   ▼
[Stage 7]  Brainfuck generator encoding the stream onto a memory tape
   │
   ▼
[Stage 8]  Brainfuck runtime (beef/interpreter) executing tape to ES5 JavaScript
   │
   ▼
[Stage 9]  Babel AST pipeline converting JS string to JSX AST
   │
   ▼
[Stage 10] Svelte component AST compiler & SSR execution (svelte/compiler)
   │
   ▼
[Stage 11] JSX / Svelte compiled down to strict XML
   │
   ▼
[Stage 12] PostgreSQL stored procedure (PL/pgSQL) XML recursive query emitting LaTeX
   │
   ▼
[Stage 13] Pandoc converting LaTeX -> Org-Mode AST -> DocBook XML
   │
   ▼
[Stage 14] XSLT transforming DocBook to Pug (Jade)
   │
   ▼
[Stage 15] Handlebars template AST compilation & evaluation
   │
   ▼
[Stage 16] Pug/Handlebars rendering to HTMX fragment executed in ephemeral headless DOM harness
   │
   ▼
[Stage 17] DOM serialization to XHTML 1.0 Strict
   │
   ▼
[Stage 18] PostHTML / HTML minifier outputting output.html (HTML5)
   │
   ▼
[Stage 19] Automated assertion step verifying input.html DOM === output.html DOM

---

Run Instantly with Docker / GHCR

Pre-built multi-runtime container images are automatically published to the GitHub Container Registry. No local toolchain installation required.

1. Run All 20 Compiler Stages

docker run --rm ghcr.io/spcbeck/ouroboros-html:latest

2. Run Comprehensive HTML5 Fixture Suite

Empirically verifies that the pipeline compiles diverse HTML structures (nested lists, multi-paragraphs, blockquotes):

docker run --rm ghcr.io/spcbeck/ouroboros-html:latest make test-suite

3. Run Recursive Ouroboros Idempotency Loop

Demonstrates mathematical idempotency ($\forall k \in [1..N], \text{DOM}(\text{Pipeline}^k(S_0)) \equiv \text{DOM}(S_0)$) by feeding the output of Stage 18 back into Stage 0 for $N$ generations:

docker run --rm ghcr.io/spcbeck/ouroboros-html:latest make ouroboros CYCLES=3

4. Compile the Example App

Compiles example/index.html through the entire 20-stage pipeline into example/dist/index.html:

docker run --rm -v "$(pwd):/workspace" -w /workspace ghcr.io/spcbeck/ouroboros-html:latest make example

---

Local Development

If you prefer building or mounting your local workspace:

# Build local Docker image
make docker-build

# Run all 20 stages mounted locally
make docker-run

# Run fixture test suite
make docker-test-suite

# Run 3-cycle Ouroboros loop
make docker-ouroboros CYCLES=3

# Compile the example app
make docker-example

---

Fixture Suite & AST Generalization

The test harness in scripts/test_suite.py exercises multiple distinct HTML5 payloads across all 20 stages:

Fixture	Structure Tested	Runtimes Exercised
01_canonical.html	Base <article><h1>...</h1><p>...</p></article>	All 20 runtimes
02_multi_paragraph.html	Sibling <p> paragraph nodes	Jinja2, PHP, Svelte, PL/pgSQL, Pandoc Org-mode, Handlebars
03_unordered_list.html	Nested <ul><li>...</li></ul> structures	LaTeX itemize $\to$ Org-mode $\to$ DocBook $\to$ Pug $\to$ Handlebars
04_blockquote.html	Semantic <blockquote><p>...</p></blockquote>	LaTeX quote $\to$ Org-mode $\to$ DocBook $\to$ Pug $\to$ Handlebars
05_subheadings.html	Hierarchical <h2>, <h3> subheadings	LaTeX \subsection $\to$ Org headings $\to$ DocBook $\to$ Pug
06_inline_formatting.html	Inline <strong>, <em>, <code> styling	Mixed AST $\to$ LaTeX \textbf/\textit $\to$ Org markup $\to$ Pug

---

Mathematical Idempotency Guarantee

$$\forall k \ge 1, \quad \operatorname{DOM}\left(\mathcal{P}^k\left(S_0\right)\right) \equiv \operatorname{DOM}\left(S_0\right)$$

Where $\mathcal{P}$ represents the composition of all 20 stages: $$\mathcal{P} = \mathcal{S}{19} \circ \mathcal{S}{18} \circ \dots \circ \mathcal{S}_1 \circ \mathcal{S}_0$$

Every generation is stored as an immutable snapshot in artifacts/gen_NN_output.html and verified via recursive JSDOM tree assertions.

---

License

MIT © 2026 Sean Beck