Skip to content

About

HTML/CSS to PNG in a single Rust process, with no browser in the loop: at least 31x less memory than headless Chromium on the repo's own 8-slide deck. Linux x86_64.

Topics

Resources

Contributing

Security policy

Stars

5 stars

Watchers

0 watching

Forks

Repository files navigation

html-render

Turns HTML and CSS into a PNG without a browser in the loop. One Rust binary, one process.

0.3.0-beta.10, one maintainer. Linux x86_64, glibc ≥ 2.35.

The 3200×1800 hero render: a slide titled "HTML + CSS → PNG, with no browser", beside bar charts of wall time and peak memory against Chromium

printf '<h1>hello</h1>' > t.html   # the argument is a path, not a URL; a missing file panics (101)
html-render assets/hero.html hero.png 1600 900 2 --document   # the PNG above

parity release licence

Why it exists

Getting a page into an image inside CI usually means shipping a browser: several hundred megabytes of image, a JavaScript engine the job never calls, a cold start ahead of the first pixel, and a runtime to install before any of it.

This one reads a file and writes a PNG. On an 8-slide deck its peak is at least 31× less memory than headless Chromium (the measurements), and deck and probe both ship in this repo, so python3 tools/bench.py re-derives every row.

Decks, social cards, report one-pagers, CI visual diffs: HTML plus CSS in, an image out.

Install

Linux x86_64 with glibc ≥ 2.35: Ubuntu 22.04+, Debian 12+, or a current Fedora. Anything else wants the container below.

V=v0.3.0-beta.10
N=html-render_0.3.0-beta.10_linux_amd64
BASE="https://github.com/leshchenko1979/html-render/releases/download/$V"
curl -fsSL -O "$BASE/$N.tar.gz" -O "$BASE/checksums.txt"
sha256sum -c checksums.txt && tar xzf "$N.tar.gz"
install -m755 html-render /usr/local/bin/ && html-render --version

Provenance is checkable without a key: each release asset is attested by the release workflow's own OIDC identity, with GitHub as issuer. The checksum catches a damaged download; the attestation names the repository, commit and workflow behind the build. Both need the gh CLI.

gh attestation verify "$N.tar.gz" --repo leshchenko1979/html-render
gh attestation verify checksums.txt --repo leshchenko1979/html-render

The release job applies both to the file it downloaded, so a release missing one fails before publication.

The binary names six libraries directly — libc, libssl, libcrypto, libfontconfig, libm, libgcc_s — and pulls freetype, expat, libpng, bzip2, brotli and zlib through fontconfig, so ldd lists 12 of them on bookworm and 13 on jammy. A slim Debian or Ubuntu host needs one extra package line: apt-get install -y libssl3 libfontconfig1 libfreetype6 libpng16-16 libbz2-1.0 libbrotli1 ca-certificates

The image carries those libraries and a font, but no network policy: a document's sub-resources are fetched at render time, so the container does not isolate egress (#29).

docker run --rm --user "$(id -u):$(id -g)" --cap-drop ALL --security-opt no-new-privileges \
    -v "$PWD:/work" ghcr.io/leshchenko1979/html-render:v0.3.0-beta.10 \
    /work/card.html /work/card.png 1280 720 2

--user is not decorative: the image's own uid is 10001, and omitting the flag exits 101. Two tags exist, v0.3.0-beta.10 and latest. A moving tag lets two builds of one commit disagree, so pin the version, or the digest when the image itself must be frozen. The tarball's attestation does not extend to the image, so verify that one by digest (#31). Building from source: CONTRIBUTING.md.

Usage

The viewport is given in CSS pixels. Scale multiplies output resolution, and a single-image run may leave it out. Sub-resources are fetched at render time with no allowlist, so an untrusted document reaches the network by design.

html-render page.html out.png 1280 720 2                            # one PNG
html-render --clip deck.html slides/ 1280 720 2 'section.slide'    # one PNG per match
html-render --clip deck.html slides/ 1280 720 2 'section.slide' --per-element   # element-sized canvases

--clip writes slides/clip_01.png, clip_02.png and so on, numbered from 01 in document order. The three shapes differ in memory: --full holds least, 37.6 MiB, then --per-element at 47.4 MiB; --clip holds most, 75.5 MiB, because it keeps one canvas as wide as the widest match. --full paints one image down to the document's full height, in row bands, streamed to the encoder, so page height is not a memory limit and has no ceiling; a position:fixed element forces one canvas instead, and says so.

On one host the output is reproducible: hold the document, the font stack and the host fixed and the bytes repeat. Vary any of the three and the digest moves, so a changed pixel in CI is one of them. For a 1280×640 card at scale 2, the shape of assets/og.png at 2560×1280, change the numbers and nothing else.

The exit code is part of the contract, and CI tests it against a real binary:

code meaning
0 a PNG was written, or --help / --version was printed
2 bad arguments: unknown flag, --clip not first, --per-element outside --clip, --full with --clip, --document with --fragment
3 the selector matched nothing
4 output written but known to be incomplete: a sub-resource failed to fetch (404, DNS, connection refused), was refused as too large, a fetch hit BLITZ_DEADLINE_SECS, or a frame past 65,408 px was cut
5 one canvas would exceed the renderer limit (65,408 wide, 65,532 tall) and nothing was written; with banding on, that means one band or one element is too large, or banding was disabled with BLITZ_BAND_MIB=0
101 panic: unparsable number, invalid selector, unreadable input

html-render --help is the maintained list of flags. Six environment variables exist. Three change what is rendered: BLITZ_BAND_MIB (4), BLITZ_DEADLINE_SECS (120), BLITZ_MAX_IMAGE_MP (128). Three are diagnostics: BLITZ_DRAIN (quiet), BLITZ_RUNTIME (current-thread), BLITZ_TRACE (unset). --help also names BLITZ_BAND_MIB, in the passage that explains a refused band.

No --json, no manifest (#28). Two surfaces are machine-readable, and they sit on different streams: TIMING (parse, layout, paint, total, scale, mode, plus content_h=/canvas_h= when a document was cut) on stderr, and one line per frame on stdout under --clip:

clip_01 css x=0.00 y=21.44 w=400.00 h=38.00  physical 400x38 at 0,21

Performance

Nothing below is typed by hand: bench/results.json is a receipt that tools/bench.py wrote on a GitHub runner, and the repo commits it unedited. The deck comes from a seed, so one command reproduces this document anywhere:

git clone https://github.com/leshchenko1979/html-render && cd html-render
python3 tools/bench.py --bin <path-to-render> --chrome <path-to-chrome> --out /tmp/mine.json

A deck.html digest of b77aac2de5931588dfa01eb5af418bc5 means the same document as the receipt. Any other digest means the generator moved, and the rows below describe a different document.

Eight slides at 1280×5760 CSS px, scale 2, three renders per engine; peak RSS sums every process the engine spawned:

measurement Chromium html-render ratio
peak RSS, --full 2350.8 MiB 37.6 MiB 62.52×
peak RSS, --clip 2350.8 MiB 75.5 MiB 31.14×
peak RSS, --per-element 2350.8 MiB 47.4 MiB 49.59×

Memory carries the claim. At least 31× less in the least favourable mode, and 49× in the advertised one. The band repeats: five runs of the probe on one runner image (43744837000, 43746767310, 43752965645, 43754284965, 43762042304) kept html-render's --full peak inside 37.6 MiB to 37.9 MiB, a 0.8 % spread, while Chromium ranged over 2336 MiB to 2453 MiB.

Wall clock is measured, gated, and not advertised. The receipt carries it for both engines, and the drift check gates the wall ratio at a deliberately coarse 45 %: a 1.85× slowdown of this renderer trips it, a 1.80× one does not. Absolute seconds stay ungated, because on one host, one deck and one binary Chromium read 1.604 s on one run and 3.120 s on the next. A ratio that mostly reports the other program's load is not a property of this one.

Method, host and the run itself: GATES.md.

Fidelity against Chromium

At the same viewport and scale, pixel for pixel against Chromium, the probe's deck differs on 4.7083 % of pixels by more than 16 levels across 29,491,200 pixels. The mean channel difference is 8.2889; ink coverage is 17.073 % (Blitz) against 16.6941 % (Chromium). This is the entire deck at full resolution rather than a sample, and tools/bench_compare.py recomputes it from the two PNG sets.

Pixel divergence is what the deck measures. On this deck it is mostly antialiasing and glyph rasterisation; how much of it is layout is not quantified here. The deck contains a border-collapse table, and table layout is one of the known divergences below.

The reproducible number is the corpus. Every run measures geometry over 36 fixtures at one viewport, against Chromium: the corpus agrees on 42 of its 54 text-free rows; 11 diverge and 1 asserts a shared absence. tools/parity_baseline.json pins all 11 box by box, so a regression reddens the build while the current defects stay visible. The divergence is not spread: one table accounts for 7 rows (#9), one <br> run for 4 (#15).

Limits

  • Linux x86_64 only. glibc ≥ 2.35 is the floor. No macOS or Windows build exists.
  • No JavaScript. Script does not run; the document renders as the HTML that arrived.
  • PNG only. No PDF and no print model: @page, page boxes and page counters are all absent.
  • Blitz's CSS, not Chromium's. An unknown property is dropped, not rejected, so what a reader sees is a declaration with no effect.
  • Linked against the host's libraries. Six libraries are named directly and the rest arrive through fontconfig, so ldd on your own host is the only accurate list. The container carries its own copy.
  • Beta. Flags and output names can move between minor versions; nothing here is a stable API.
  • Nothing sandboxes the input. Sub-resources are fetched with no allowlist, and file:// can be read (SECURITY.md). No offline mode: a document controls its own outbound HTTP (#29).
  • Peak memory follows canvas area, not page length. The figures above count the whole process tree, but on one deck. One 128 MP decode costs about 512 MiB of RGBA, and clip_oversized_frame in tools/memory_baseline.json peaks at 809.5 MiB, 21× the 37.6 MiB headline. Budget a container from that.
  • Three defects exit 0 with wrong pixels, all reproduced on 0.3.0-beta.10: table layout, off by up to 18px and painting the table taller than Chromium does, 104 px against 86 (#9); <br> runs shifting content 16px per break (#15); and a 200 whose body is not an image, which fails to decode inside Blitz after the bytes were delivered, so nothing upstream of the decoder sees it (#27). The corpus gate pins #9 and #15; the non-image 200 has no test at all.
  • Taller than the canvas means a truncated PNG. The output keeps the requested <width> x <height> at exit 0, because every golden depends on that default, but TIMING carries content_h=<document px> canvas_h=<canvas px> and stderr names how many rows were lost (#10). --full paints the whole document instead.
  • A missing font is substituted, and named on stderr. fontconfig resolves a substitute rather than failing, so a family the host lacks renders in whatever was picked, at exit 0, with a layout that still looks like a layout. Each such family is named once. Generic keywords and @font-face families go unreported: there the substitution is the request being honoured. Exit stays 0, and the caller decides.
  • A failed sub-resource exits 4 (#11): a 404, a DNS failure, a refused connection, or an image past BLITZ_MAX_IMAGE_MP leaves a partial PNG and the resource named on stderr.
  • A frame wider than the viewport is written at its own width. The default --clip band is as wide as the widest match, so a 1600 px element in an 800 px viewport comes out 1600 px wide, at a peak of one band. Beyond the renderer's 65,408 px limit no paint happens, so that residual case is still a cut, at exit 4.
  • A killed render leaves a truncated PNG at the output path: no temp file, no rename (#26). No SBOM is generated and no dependency advisory scan runs in CI (#25).

Where the detail lives

file holds
GATES.md determinism, device scale, element clip, cost, corpus, fidelity, CSS audit
CONTRIBUTING.md build requirements, the CI workflows, the rules a change must pass
SECURITY.md what rendering does to the machine, measured egress, reporting
CHANGELOG.md what moved between releases
bench/README.md the probe: what it measures, how to re-run it, what the bands mean
docs/why-html-first.md what HTML-and-CSS-first rendering is good for, with sources

Contributing

A minimal HTML repro in a bug report is the most useful thing to send. Pull requests get read and reviewed, at the pace of one person on a beta; CONTRIBUTING.md lists the rules a change has to pass, and CONTRIBUTING.md#building has the build and the CI workflows.

Licence

Apache-2.0, with an explicit patent grant. Full text in LICENSE. The release tarball ships no licence text of its own (#32), so redistribute the LICENSE with it.

About

HTML/CSS to PNG in a single Rust process, with no browser in the loop: at least 31x less memory than headless Chromium on the repo's own 8-slide deck. Linux x86_64.

Topics

Resources

Contributing

Security policy

Stars

5 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages