Contributing

This repo replaces opinions with measurements wherever it can. The result is a set of guard scripts, and knowing which one to reach for is most of knowing how to work here.

The governing principle

Nothing stays dynamic unless it is proven it must.

Before adding anything to the runtime — a per-frame cost, runtime state, a new entry in the shared-memory schema — the question is whether the work can happen at build time instead. bun run runtime-surface holds the runtime to a ratchet: exported symbols and bundled bytes may fall freely and may not rise without editing the baseline in the same commit.

The guards

Each of these proves one thing. Several use a browser or mdn-data as an oracle — they compare dziry against an external authority rather than against itself.

Run	Proves	Oracle
bun run protocol-guard Protocol identity	Proves the shared-memory protocol's two halves still agree — offsets, field identity, enums, FFI symbols.	—
bun run boundary-diff Boundary sanity	Validates the tables Bun is about to hand the engine: link consistency, index ranges, sibling cycles, arena bounds.	—
bun run characterize Compiler output frozen	Golden files of compiled output, so a refactor is provably behaviour-preserving.	—
bun run golden Visual regression	Renders scenarios headlessly and compares against blessed PNGs.	—
bun run conformance CSS conformance	Compiles a declaration and compares the emitted value with what the browser computes.	headless Chrome
bun run layout-diff Layout conformance	Lays out the same html+css in dziry and in the browser at the same viewport, then compares every box.	headless Chrome
bun run spec-audit Initial values	Checks computed-style defaults and inheritance flags for every style field.	mdn-data
bun run css-coverage Coverage, measured	What CSS exists versus what dziry supports, bucketed as supported / unsupported / committed non-goal.	mdn-data
bun run tailwind-coverage Tailwind coverage	What fraction of Tailwind works, and what is blocking the rest ranked by classes unblocked.	—
bun run html-coverage Element defaults	How each HTML element renders in dziry versus the browser — the table that specifies the UA stylesheet.	headless Chrome
bun run doc-lint Citations resolve	Verifies that every `file.ext:LINE` citation in the Markdown docs still points at something.	—
bun run probe Browser facts	Measures what a browser actually does over CDP, so behaviour claims are recorded rather than remembered.	headless Chrome

Two more that are not in that table:

Run	Proves
bun run docs-check	Doc examples compile against the real types; the public API is covered; frontmatter is present.
bun run arch:check	The architecture map still matches the repo. --emit regenerates ARCHITECTURE.md.

Which one to run

You changed	Run
A CSS property, or STYLE_FIELDS	conformance, spec-audit, css-coverage
src/protocol/schema.ts	protocol-guard
Anything in src/compiler/	characterize first, to freeze the before
paint.rs, layout.rs, text.rs	golden
Taffy style construction, sizing, wrapping	layout-diff
The emitter, list splicing, relinking, hidden	boundary-diff
The authoring API in src/index.ts	docs-check
Any doc, or any file a doc cites	doc-lint

Before a commit that touches more than one of those: bun run test && bun run check.

The whole suite

bun run test              # bun test + cargo test
bun run check             # tsc over src, scripts, windows, and architecture
bun run lint              # cargo fmt --check && clippy

Working on docs

The docs site is docs/, and it is built rather than merely written — a rotted citation fails bun run docs:build, and so does an example that no longer compiles.

bun run docs              # dev server; citations warn instead of failing
bun run docs-check        # examples, API coverage, frontmatter
bun run docs:build        # the gate: doc-lint + docs-check + build

See Writing docs for the rules that keep them true, and the one failure no checker can catch.

A note on measurements

NOTES.md contains numbers from before the Rust engine landed, sitting unlabelled next to current ones. Check provenance before quoting any figure from it, and prefer running the relevant script to citing a number you found written down.

The same applies to coverage claims. bun run tailwind-coverage is the measurement; a percentage in prose is a memory of one.