Overview

Heddlemail is an IR contract, with tools around it

Heddlemail gives people and AI agents Figma-like control over email layout, and makes it impossible to express an email that breaks in a major client. The EmailDocument IR is a bounded, closed vocabulary: everything it can express compiles to proven email markup.

Most email builders are an editor that happens to emit HTML. Heddlemail is a Block IR that happens to have an editor. The canvas, the MCP server, the CLI and the importers are all producers or consumers of that one tree. A visual tool whose output is a pile of nested tables cannot be reviewed, diffed or trusted by the engineers who own the send queue; a tree validated at the boundary can be compiled to whatever those engineers already use.

the conveyor belt

  editor ─┐
    agent ─┼──▶  EmailDocument  ──┬──▶  HTML
importer ─┘     (one contract)    ├──▶  MJML
                                  └──▶  React Email

             × Handlebars · Jinja2 · Liquid · Thymeleaf

The moat is the contract, not the compiler alone. Cross-client HTML is table stakes; what is rare is a schema an agent can write against where unsafe output cannot be expressed, a visual round trip that never parses HTML, multi-target × multi-dialect output, and verification in CI. The product is developer-first: the MCP server is the surface developers and their agents use, and the editor is a peer of it.

The one rule to read first

No file outside a registry may branch on a block’s type. No switch (block.type), no per-type if/else. Per-type behaviour is data in a registry entry, and a test fails the build when that slips. Why that matters →

Where to go next

If you are here to understand the system, read in order. If you are here to add a block type, skip to Adding a block type.

The Block IR

Document & grammar

A single rooted tree, its grammar of sections, bounded frames and leaves.

Block reference

Every type, its content, its styles, and what it may contain.

Variables & bindings

Variable runs, field, repeat and conditional bindings, and why the dialect is a compile option.

Invariants

The nine properties the schema enforces on every document.

Extending

The registry

Registries stitched by key parity, and the rule against per-type switches.

Adding a block type

The only sanctioned expansion path: two registry entries.

Output

The compiler

Targets, the generic walker, and the no-silent-drop rule.

Preview & lint

Why preview is compiled HTML, and what the compatibility lint catches.

Agents

MCP server

The developer surface: an agent checks, repairs, compiles and previews against the contract.

Project

Roadmap & status

Shipped history, Phases A–H, their gates, and where the build is now.

Status

What ships today is IR v2: the IR (@repo/block-ir) with bounded auto-layout frames, inline variable runs and style safety tiers; the compiler (@repo/email-compiler) with HTML, MJML and React Email targets, the Handlebars, Jinja2, Liquid and Thymeleaf dialects, and lint; the MCP server and CLI (heddlemail-mcp); and the editor (@repo/editor, at /editor), whose canvas is the compiled HTML. Older v1 documents are upgraded by migrate(). These pages describe that shipped behaviour and mark anything still to come as planned. Phase by phase, it is on the roadmap.