# htmlcapsule

> An open specification, reference implementation, and example corpus for HTML Capsule — a profile of HTML for sealed, self-contained, provenance-bearing snapshots of work worth preserving.

HTML Capsule addresses the gap between AI tools producing HTML artifacts by default (LLM canvases, agent outputs, design-tool exports like Claude Design) and the lack of discipline around making those artifacts durable, inspectable, and shareable beyond the platform that produced them. The format is one sealed `.html` file with five required inline blocks (manifest, data, style, root, runtime), twelve normative rules, and no network dependencies. Producers include LLMs given the Core spec, deterministic compilers, and humans — multi-producer interop is the load-bearing claim.

This project is research-led with an empirical-pressure-driven spec discipline: rules emerge from observed production failures across multiple producer kinds, recorded as numbered F-findings in the research log. The format itself is hosting-agnostic; hosts (MinDev, htmlbin.dev) compose with the format optionally.

## Spec

- [Core spec — twelve rules, one page, designed to paste into an LLM prompt](https://htmlcapsule.org/CAPSULE_CORE.md): The minimal contract producers actually use. Versioned at v0.3.0; tagged in git as `core-v0.3.0`.
- [Full spec — implementer-grade definition](https://htmlcapsule.org/spec/CAPSULE_SPEC.md): Format definition, validation rules, security model, content-hash recipe (normative test vector), response protocol, parked v0.4+ candidates. Currently v0.3.8. v0.3.6 graduated `derived_from[]` (non-Capsule provenance) from Appendix E.11, formalized the `media.*` capability family + `export.fragment_provenance` universal envelope, and promoted graceful degradation to a named design principle (§2.3.1) with an optional `fallbacks` manifest section. v0.3.7 (doc patch) added §2.3.3 "No-JS interactivity techniques" — pattern inventory for declarative interactivity through native HTML controls + CSS state selectors (radio-button tabs, checkbox layer toggles, `:target` navigation, pre-rendered alternates, `<details>` drawers). v0.3.8 (doc patch) lands the technical thesis: §2.3 gains a slogan epigraph ("A capsule is a document first, an app second. Apps when alive. Documents when dormant."); new §2.3.2 introduces the five-tier framework (Tier 0 Static document → Tier 1 Native HTML interaction → Tier 2 CSS-state interaction → Tier 3 Precomputed interactivity → Tier 4 JavaScript runtime); §2.3.3 (renumbered from §2.3.2) reorganizes the technique inventory by tier.
- [Domain capsule schemas](https://htmlcapsule.org/spec/DOMAIN_CAPSULES.md): Per-domain extensions of the base contract — `domain.implementation_notes`, `domain.design_system`, `domain.exploration_map` (with image-fallback carve-out for visualization geometry, the F20-driven addition).
- [Hosting pattern — descriptive convention](https://htmlcapsule.org/spec/HOSTING.md): The shape independent hosts (MinDev, htmlbin.dev) converged on without coordinating. Documents the host-contract pattern for future host implementers; descriptive, not normative.
- [Glossary](https://htmlcapsule.org/GLOSSARY.md): Vocabulary including Capsule, Domain Capsule, Project Capsule, Interactive archive, Sealed handoff format, Universal AI reader, the four-layer table, phase status.

## Research

- [Research log — F1-F29 findings, methodology, recurring failures](https://htmlcapsule.org/RESEARCH.md): The running narrative of what's been investigated, what's been observed, what's been spec-changed in response. Includes the empirical-pressure-driven spec evolution principle and the corpus across multiple producer kinds. Recent findings extend the layer convergences to host-vs-registry (F24, the missing commitment layer) and the ChatGPT producer-population's reliable Core-supplementary-guidance reads (F25).
- [Precedents and related work](https://htmlcapsule.org/PRECEDENTS.md): Positioning against RO-Crate, BagIt, WARC, EPUB, C2PA, TiddlyWiki, MHTML, Hugging Face Model Cards, plus current voices in the same family across the lifecycle layers (live editing: Raunaq Bhutoria / html-docs.com; format: Thariq, Karpathy, Blake, Steph Ango; hosting: Utkarsh Sengar / htmlbin; discovery: Jeremy Howard / llms.txt).
- [Maintainer's journey essay (first-person)](https://htmlcapsule.org/notes.html): The personal account of why this project exists — from copy-pasting between AI tools and getting frustrated with share-links to landing on HTML as the substrate and writing the discipline down.

## Voices (archived primary sources)

- [Andrej Karpathy on HTML as the current best default for LLM output (2026-05-11)](https://htmlcapsule.org/voices/karpathy-html-progression-2026.html): Verbatim archive of his X post laying out the four-step progression (raw text → markdown → HTML → eventually interactive neural simulations) plus the "structure your response as HTML" tip.
- [Utkarsh Sengar — htmlbin.dev — agent-first HTML hosting (2026-05-17)](https://htmlcapsule.org/voices/utsengar-htmlbin-2026.html): Independent public hosting layer that converged with MinDev's hosting pattern. The hosting-layer voice in the conversation Capsule is part of.

## Implementation

- [Reference Python compiler + validator](https://github.com/bigfancygarden/htmlcapsule/tree/main/compiler): Stdlib-only (no pip deps). Compiler renders JSON+templates to capsules; validator runs 26 conformance checks. Validator supports both local files and URLs (URL mode cross-checks any `x-capsule-*` host-attestation headers).
- [Compiler templates](https://github.com/bigfancygarden/htmlcapsule/tree/main/templates): `decision_board`, `news_capsule`.
- [Worked examples](https://github.com/bigfancygarden/htmlcapsule/tree/main/spec/examples): Canonical example capsules — `briefing_example.html`, `implementation_notes_example.html`. Each validates at 26/26 strict against the reference validator.
- [GitHub repository](https://github.com/bigfancygarden/htmlcapsule): Source of truth. Apache 2.0 licensed.

## Project trajectory

- [CHANGELOG.md at repo root](https://github.com/bigfancygarden/htmlcapsule/blob/main/CHANGELOG.md): Curated narrative of what shipped at each spec version (v0.3.0 through v0.3.8), landing iterations, voices archive growth, research findings (F1–F29), and infrastructure additions. Reverse-chronological by version; commit IDs cross-referenced.

## How to cite

- [CITATION.cff at repo root](https://github.com/bigfancygarden/htmlcapsule/blob/main/CITATION.cff): GitHub auto-detects and renders a "Cite this repository" button. Citation tools (Zotero, citation managers) consume the format directly. Zenodo DOI integration parked for the next milestone release.