The Malleable HTML File Specification

The Malleable HTML File Specification

Version 1, draft. July 2026. This specification is public domain (CC0). You can copy it, change it, and ship it.

The one-line version

A malleable HTML file is a plain .html file that saves itself: the page serializes its own DOM and POSTs it to one endpoint, and the host writes it back to disk. The file is the app, the DOM is the database, and any server that implements one route can host it.

The problem

The web browser is the best application platform ever shipped. It is on every machine, it is sandboxed, and it has powerful APIs for drawing, storage, media, and networking. A useful personal tool, a checklist, a tracker, a diary, a small database, fits comfortably in a few hundred kilobytes of HTML.

But an HTML file cannot save itself. And every existing way around that is hostile to normal people:

Native apps must be signed and notarized per platform, or the operating system actively warns users away: "unidentified developer," SmartScreen, quarantine dialogs. Email and chat services refuse to carry executables at all. You cannot hand someone an app the way you hand them a document.

Terminal software asks the recipient to curl an installer and run a server by hand. Fine for developers. A dead end for everyone else.

Browser file APIs (the File System Access API) work only in Chromium browsers and sit behind permission prompts. A document format cannot require a specific browser and a permission ceremony.

Self-modifying executables are the tempting dead end. A binary that rewrites itself invalidates its own code signature on every save, so it can never be signed, and no mail system will deliver it anyway.

So personal software gets pushed onto platforms: someone else's server, someone else's account system, someone else's subscription. The tool stops being yours.

The idea

Split the problem in two, and keep the halves separate:

The document stays plain HTML. One file. Its DOM is its storage: state lives in elements, attributes, and text. It travels through email, chat, and USB sticks. It is small, readable, and unscary. Nothing about it needs signing, because it is not an executable.

The host is any HTTP server that can do two things: serve the file, and accept one POST that overwrites it. A host can be twenty lines of script, a signed desktop app, or a hosted platform. Hosts are interchangeable. The file does not care which one it is sitting on.

Saving is the whole trick: the page clones its own DOM, cleans it up, serializes it, and POSTs it to the host. The host writes the bytes over the file. From then on, the file is its own latest state. Open it anywhere and your data is already inside.

The document is mutable and the runtime is not. That is the property no single-file executable can ever have, and it is why this format can be both powerful and safe to receive.

The specification

Four terms:

Document : the HTML file. Both the file at rest and the artifact a save writes.

Host : the program serving the document and accepting saves.

Snapshot : the full serialized state of the live page, before anything is stripped for saving.

Save : the POST that carries a document to the host.

1. The document

A document is a single HTML file. Its durable state lives in the DOM, so that serializing the DOM captures everything worth keeping.

A document should:

keep state in markup (elements, attributes, text), not only in JavaScript variables,

write any state that lives outside markup (form field values, for example) into the DOM before a snapshot is taken,

mark purely ephemeral interface elements so they can be stripped (section 2),

work when opened as a static file: a malleable document degrades to a read-only document, never to a broken one.

Two boundaries every document lives within:

Everything durable lives inside the root element. Serialization is the doctype plus the root element, so comments or processing instructions outside do not survive a save.

The format is HTML5. A saved document always begins with , whatever doctype the file started with.

2. The snapshot and the document

A snapshot is the string:

"" + documentElement.outerHTML

taken from a prepared clone of the live DOM, never from the live DOM itself. Preparing the clone means, in order:

Clone the root element, without disturbing the live page.

Sync : copy live form state into markup (value, checked, selected as attributes) so it survives serialization. Password and file inputs are never written into markup.

Run the page's own pre-snapshot hooks , so a document can reshape its clone before capture.

Strip [no-snapshot] elements : things that exist only on the live page and should never leave it.

Strip extension debris : password managers and grammar checkers inject elements and attributes into pages. In a format where the file is the database, that junk would be saved into the document forever. Remove it from every snapshot.

The document to...