Golden suite
Lock comparison is geometry + render plan + content hash. Engine commit SHA and appearance_hash are not golden-equal (they differ between debug UNKNOWN and release git SHA).
Local (fast): one compile per case, no PNG. Default when CI is unset:
cargo run -p k2f-test-runner -- run
cargo test -p k2f_sdk -p k2f_package -p k2f
CI: five compiles per case (determinism) plus a small PNG appearance gate (elevation_shadows, card_variants, running_footer_page_numbers). Published examples (examples/published/*.K2F) are not PNG-golden.
Visual-gate PNG (optional locally):
cargo run -p k2f-test-runner -- run --check-png --dataset-runs 1
Cases without committed page_*.png skip the pixel check. To refresh gate PNGs: --update --check-png.
Default cargo test -p k2f_paint still renders those scenes and checks PNG magic bytes, but does not byte-compare goldens (macOS vs Linux raster bytes can differ). Linux CI compares via CHECK_PAINT_GOLDENS=1 and the --check-png job. Refresh paint-crate goldens with UPDATE_PAINT_GOLDENS=1.
Nightly: same determinism + PNG gate; see .github/workflows/golden-nightly.yml.