# Getting started

A **Leaf** is a self-contained HTML page taken apart into editable files, and put
back without losing a byte.

```bash
npx leaf                                        # prints this guide
npx leaf unpack page.html --output-dir ./out    # take it apart
npx leaf pack ./out --out page.html             # put it back
npx leaf check page.html                        # is it actually self-contained?
```

## What you get

```
out/
  shell.html          the original document, with /*leaf:N*/ where each block was
  parts/00-style.css
  parts/01-script.js
  leaf.json           order, types, byte counts, digests
```

Edit the parts. `pack` puts them back in the order `leaf.json` records and tells
you whether the result is byte-identical to what you unpacked — unchanged in,
unchanged out.

## Why the shell keeps the original

Most tools that do this rebuild the document from a parse tree, which is how a
page comes back with its attribute quoting normalised, its shader indentation
re-flowed and a newline missing from inside a template literal. It still loads.
It still looks right. That is the problem.

Leaf never rebuilds. It records byte offsets, cuts the block bodies out, and puts
them back where they were. The round trip is the guarantee, and it is tested
against every page in the studio rather than a fixture chosen to pass.

## check

`check` answers one question: does this page fetch anything from another origin?
A single-file page claims it opens from `file://` on a machine with no network
and looks the same. A Google Fonts stylesheet or a CDN import map breaks that
claim quietly — the page renders in a fallback typeface and reports nothing.

Hyperlinks, canonical URLs and `og:image` are not failures. Only what the browser
fetches to render the page counts.

## Licence

MIT — `LICENSE` in this package. Copyright (c) 2026 Joe Asare.