Getting Started with Your First Contribution to Lightpanda

v8 boots faster from a precomputed startup heap than from a cold init path. Lightpanda generates that heap as src/snapshot.bin and embeds it in the release binary through -Dsnapshot_path. build-v8-snapshot runs first because build declares it as a prerequisite (build: build-v8-snapshot on line 59), so a fresh checkout running make build produces the snapshot, then the release binary that embeds it.

build-dev skips the -Doptimize flag and the snapshot path, falling back to the debug-mode default that creates the snapshot at startup instead. A first contributor should run make build-dev while iterating because debug builds compile faster and surface stack traces; make build is the release-fast variant for performance benchmarking.

make run wraps ./zig-out/bin/lightpanda with no arguments, which falls into the help mode unless a CLI verb is given. The interesting path is lightpanda serve --host 127.0.0.1 --port 9222, which lands in the .serve branch of this switch. Config.parseArgs earlier in the function converts --host and --port into the opts tagged here, so this code only sees a parsed structure.

The error handling is the part to read carefully. Address.parseIp validates the host or returns an error that the catch block logs and turns into a help-screen exit. Server.init distinguishes error.AddressInUse from other failures with a hint that mentions --port by name. Both patterns reflect a contributor-facing rule: every failure path returns a message a human can act on, never just a Zig error name.

Tests live inside source files as Zig test "..." blocks; there is no separate tests/ directory. zig build test compiles the lightpanda module under the test target defined in build.zig with src/test_runner.zig as the runner, so make test runs the entire suite by default. F="name" on the command line becomes TEST_FILTER="name", and src/test_runner.zig reads that env var to skip tests whose names do not match.

The script wrapper exists because Zig only emits color codes to a TTY; piping into grep would normally drop the colors. script allocates a pseudo-terminal so the child sees a TTY and prints colors anyway. The grep --line-buffered -v at the end strips the long compile command line that -freference-trace echoes, leaving only test results in the output.

Adding a Web API to Lightpanda follows one repeated pattern, and AbortController is among the smallest examples. The JsApi struct is what Env.zig picks up at v8 isolate setup: js.Bridge(AbortController) generates the function-template scaffolding, Meta sets the JS class name and prototype chain, and the trailing constructor, signal, and abort declarations bind Zig methods to JS members through bridge.constructor, bridge.accessor, and bridge.function.

The test pattern at the bottom is just as repeated. testing.htmlRunner loads an HTML file under tests/html/ in a real Page with a real v8 context and asserts on the result; event/abort_controller.html is a plain HTML file that drives the API from JavaScript. Adding an API means adding one Zig file with this shape and one HTML fixture, then watching make test run them both.

The contributing guide is intentionally short and points at one mechanism. Pull requests go through GitHub like any other repo. The wrinkle is the CLA: CLA.md is the agreement, and signing it is a one-time action a contributor takes during the first pull request through a comment on the PR. The cla-assistant-lite GitHub Action posts the prompt and records the acceptance.

PR #303 is the linked example so a first contributor can see the bot comment and the acceptance flow before submitting their own. There is no separate code-style guide here; the project relies on zig fmt for layout and on review for everything else. Discussions happen on the linked Discord and on the GitHub issues page.

The two numbers on the README are why anyone shows up to read this code: 123MB peak versus 2GB peak on 100 pages, 5s versus 46s. They come from a benchmark in lightpanda-io/demo that crawls 933 real web pages on an AWS m5.large, and the methodology lives in BENCHMARKS.md in that companion repo. A first contributor can reproduce the numbers in a few minutes once make build has produced a release binary.

Reading the benchmark numbers is also how the rest of the tour set earns its place. The 123MB is the per-page arena pool plus the moderate v8 memory pressure hint covered in the Zig Memory Management tour. The 9x speed comes from skipping the compositor, the layout pass, and the GPU plumbing covered in the Post-Chrome Browser Architecture tour. Both are linked from the hub.