Specification · v1 Working Draft
anvil·md

Specification · v1 working draft

ANVIL

A tiny DSL an agent writes inside a fenced code block, which a host renders as real UI inline in the conversation. 15 sections: the grammar, every block, the stamp wire format and its lifecycle, the security posture, and what conformance means. Nothing here requires a particular framework, a runtime service, or trust in the host.

  1. §0 Sixty seconds The whole idea in sixty seconds: a fenced block going down, a structured tag coming up, and nothing in between.
  2. §1 The axiom One sentence about append-only transcripts, from which every other rule in this document follows.
  3. §2 Vocabulary The ten blocks and one directive, why the set is closed, and why @markdown deliberately does not exist.
  4. §3 Grammar Sigils, the line shapes, and why the in-block literal delimiter is ~~~ rather than a nested backtick fence.
  5. §4 Blocks Every block in turn: attributes, the rows it accepts, and what it renders as, open and stamped.
  6. §5 Streaming Every prefix of a fence is a real input. Blocks stay inert until the fence closes.
  7. §6 The stamp The answer half: the <stamp> tag, its payload per block kind, and why it renders as the frozen block rather than a second bubble.
  8. §7 Stamp lifecycle The five laws, the state machine, idempotency on (blockId, nonce), expiry, reload safety and secrets.
  9. §8 Security Stamps are untrusted input, stamping is permission-gated, and attribute-position values are allowlisted rather than escaped.
  10. §9 Rendering and interaction rules Twelve interaction rules, each of which has cost someone a bug: focus, height, motion, keyboard, semantics, mobile.
  11. §10 Authoring rules, for the agent How an agent should use this: what to reach for, what to avoid, and how to run an interview rather than a form.
  12. §11 Parser contract The parser is total. What every malformed input degrades to, and why derived ids must come from content.
  13. §12 Failure modes, ranked by how much they hurt Sixteen ways to get this wrong, ranked by how much each one hurts, with the guard for each.
  14. §13 Reference card The whole language on one screen.
  15. §14 Conformance The seven things an implementation must do to call itself ANVIL v1 conformant.

Playground

Paste ANVIL source, watch it render. Runs entirely in the browser.

Overview

The short version: two halves, ten blocks, and why a block freezes.

Implementation

The parser and HTML renderer this site is built on, and their tests.