Developer docs#

For working on Pixel Lab: the pixellab program (the engine, the command line and the two servers, in Rust), and the Mac app. To use it, start with the README (install, a tour, shortcuts, MCP setup, troubleshooting).

These docs are Markdown in the repo, next to what they describe, and are also published as a site, built by npm run docs:site (Contributing).

Start here#

1. Architecture: the three doors onto one command registry, the document as the source of truth and the engine's home, and how an edit and an agent's proposal travel.
2. Contributing: intent → spec → plan, branches, the rules, and what a PR pastes.
3. Testing: the Rust suites, the repo tooling's tests, the app's unit tests, the script hook, snapshots and the acceptance pass.

For the two file kinds documents share objects and colors with, see Libraries and palette files.

The code#

• The program (crates/pixellab/, with the engine in crates/engine/): building it, the module map, a command's anatomy, adding a command, sessions and undo, errors.
• The Mac app (app/): the model, the server connection, the views, the rules the code keeps, adding a feature.
• Scripts (scripts/): building, installing, packaging the program, snapshots, the acceptance pass, the docs.
• Example documents (examples/): two documents with scene layers to try the app on and to test with.

Reference#

• Document format: the .pixellab folder, format 2: manifest, palette, objects, scenes, ambient loops and actions, canonical form.
• The site contract: what a site may rely on in a compiled SVG.
• Commands, the stdio protocol and MCP: generated from the program's registry by npm run docs:cli.
• CLAUDE.md: the instructions agents work by in this repo.

The design record#

Each change lives in docs/intents/YYYY-MM-<slug>/, with its intent, spec and plan:

• 2026-10-mac-app: the first build, Pixel Lab for Mac. Its plan is the architecture and design record, including the look (mood board 03, "Field notebook") and the follow-ups list.
• 2026-10-dev-docs: these developer docs and their site (spec, plan).
• 2026-10-depth-order: scenes draw their items by where they stand (spec, plan, the site's migration notes).
• 2026-10-rust-engine: the engine and the pixellab program in Rust, format 2 (JSON sources), self-contained SVGs and the app with no Node (spec, plan).

Screenshots from each build are in docs/screenshots/.