-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathllms.txt
More file actions
44 lines (29 loc) · 11.3 KB
/
Copy pathllms.txt
File metadata and controls
44 lines (29 loc) · 11.3 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
# htmlcapsule
> An open specification, reference implementation, and example corpus for the htmlcapsule family: Capsule, a profile of HTML for sealed, self-contained, provenance-bearing snapshots of work worth preserving, and Bundle, the sibling format for manifested multi-file artifacts.
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. Capsule is one sealed `.html` file with five required inline blocks (manifest, data, style, root, runtime), twelve normative rules, optional profile overlays (`static`, `interactive`, `data`), optional declared presentations (`reader`, `mobile`, `print-letter`, `slides`, `reel`, `interactive`), optional `capsule-data.presentation_model.cards[]` source material for compiler-generated presentations, and no network dependencies. Bundle is a manifested directory/zip for heavy or multi-viewer artifacts that do not fit Capsule's single-file boundary, with optional `bundle_profile` vocabulary for the top-level file-set pattern (`viewer`, `data_package`, `multi_entry`, `project_archive`). 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.12. 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.8 lands the document-first technical thesis and five-tier framework. v0.3.9 adds `presentations[]` manifest declarations for capsule-owned views, validator checks for declared presentation shape and fragment-entry resolution, and a recommended `presentation_model.cards[]` source shape for compiler-generated slides/reel/story surfaces. v0.3.10 adds the `sealed_sources` recommended data-block convention (data-backed capsules seal resolved payloads per source key, so reopen re-resolves offline — Core-promotion candidate for v0.4), §8.4 hash_scope display guidance, and validator version identity for cross-repo producer CI. v0.3.11 names the two-track version story (`spec_version` declares the normative Core line; a conformance statement is the pair declared-line + validator-version), adds the float-bearing Test Vector B (§9.1.1 — correctly-rounded parsing and reference number formatting are normative; JCS is not this spec's canonical form), and adds `parents[].content_hash` digest pinning for layered artifacts. v0.3.12 graduates `domain.annotation` to a full named domain — a sealed layer of marks (circle/highlight/arrow/strikeout/star/margin-note) over a digest-pinned base, anchored to the base's data (sealed record / layer id / CRS coordinate), never the regenerable DOM.
- [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), `domain.compositor` (first externally-owned compiler domain; composed document artifacts sealing their resolved data via `sealed_sources`, the F33-driven addition), and `domain.annotation` (a sealed layer of marks over a digest-pinned base, anchored to sealed truth not the DOM; the F40 graduation of the markup-as-language thesis).
- [Bundle spec — sibling format for heavy / multi-viewer artifacts](https://htmlcapsule.org/spec/BUNDLE_SPEC.md): The htmlcapsule project's second format, introduced in project v0.4.0 (2026-05-24). A Bundle is a manifested directory of files rather than a single sealed HTML file. Shares Capsule's three foundational principles (identity / integrity / provenance); relaxes the network-boundary commitment to allow declared external dependencies while keeping primary artifact data in the file inventory. Built for artifacts that exceed what a Capsule can reasonably contain (heavy georeferenced rasters, LiDAR, multi-viewer projects). Not a relaxed Capsule: use Capsule for one offline HTML file, Bundle for manifest-described file sets. Bundle v0.1.1 adds recommended `bundle_profile` vocabulary for file-set patterns. Initial schema: `spec/bundle.schema.json`; validator: `compiler/validate_bundle.py`; fixture: `spec/examples/minimal_bundle/`. Emerged from real producer pressure (the strata leak investigation) and was promoted to a sibling spec in project v0.4.0; full trajectory in F31.
- [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-F39 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), Bundle as the first sibling format (F31), the first data-backed compiler producer sealing its resolved data via `sealed_sources` (F33), `hash_scope: "data+manifest"` as a deliberate production default with the scope-legibility rule (F34), the reference validator becoming version-identified cross-repo CI infrastructure (F35), the two-track version story surfaced by the first production custody run (F36), a 1-ULP float parse filing a false tampered verdict and the float-bearing test vector that answers it (F37), the mintel push-flow producer review — first production use of the `^x-` extension namespace and the first unenforced registry MUST (F38), the annotation-layer review: a normal sealed capsule over a digest-pinned base, anchored to truth rather than projection (F39), and its graduation to a named domain one day later when the producer's real annotation capsule independently converged on the reviewed shape (F40).
- [Presentation study](https://github.com/bigfancygarden/htmlcapsule/blob/main/design/PRESENTATION_STUDY.md): Active design note for the 2x2 desktop/mobile x scroll/one-screen presentation model, `sections -> cards -> renderers`, and the boundary between Capsule spec, compiler templates, and HTML Vault.
- [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 + validators](https://github.com/bigfancygarden/htmlcapsule/tree/main/compiler): Stdlib-only (no pip deps). Capsule compiler renders JSON+templates to capsules; Capsule validator runs 29 base conformance checks including declared presentation validation, and supports both local files and URLs (URL mode cross-checks any `x-capsule-*` host-attestation headers). The validator carries a version identity (`--version`; `VALIDATOR_VERSION` tracks the full-spec version it enforces) so producer CI consuming it cross-repo can pin legibly. Bundle validator checks directory or zip manifests, `bundle_profile`, file hashes, entry files, and local/external references.
- [Compiler templates](https://github.com/bigfancygarden/htmlcapsule/tree/main/templates): `decision_board`, `news_capsule`. `compiler/compile_multiview.py` is the current user-facing command for compiling one `sections[] + assets[] + presentation_model.cards[]` source into one Capsule with `reader`, mobile snap, mobile feed, `slides`, and `reel` presentations. `compiler/repair_integrity.py` repairs provisional or stale Capsule integrity hashes deterministically.
- [Presentation surface demos](https://github.com/bigfancygarden/htmlcapsule/tree/main/demos/presentation-surfaces): Informative renderer skeletons for compiler/host defaults, including mobile story/reel and desktop slides surfaces. These demonstrate expected ergonomics but are not conformance requirements.
- [Worked examples](https://github.com/bigfancygarden/htmlcapsule/tree/main/spec/examples): Canonical example capsules — `briefing_example.html`, `implementation_notes_example.html`. Each validates cleanly 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.11), landing iterations, voices archive growth, research findings (F1–F39), 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.