* Adopt the shared AGENTS.md (RFC-0072) and test rules (RFC-0071) * AGENTS.md: correct the repository facts Correct the layer list (no psd or codecs crate; ipp, raw and tablet are standalone; test helper crates), name the example plug-in that uses unsafe, and renumber a stale rule reference in docs/contributing.md. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --------- Co-authored-by: FredApps <FredApps@users.noreply.github.com> Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
14 KiB
Contributing
- Language: Rust only. No JavaScript or TypeScript. On the web,
wasm-bindgengenerates a small loader; never hand-write JS. - Licence: contributions are MIT OR Apache-2.0 (
LICENSE-MIT,LICENSE-APACHE,NOTICE). The ArtCraft logos indocs/brand/are not open source (docs/brand/LICENSE-brand.txt). - Clean-room: do not copy code, shaders, icons, ICC profiles or other assets from proprietary software (such as Photoshop). Match behaviour and look by observation and public specs. Only use assets with permissive licences, keep their license next to the asset (e.g.
assets/fonts/OFL-*.txt,assets/icons/LICENSE-lucide.txt), and list every asset inATTRIBUTION.md. Fonts live in storytold/craft-fonts, never in this repo: add new fonts there, and build with them through the optionalCRAFT_FONTS_DIRbuild input (docs/development.md› Fonts). - Never crash: non-test code must not panic: no
unwrap/expect/panic!/unreachable!/todo!/unimplemented!and nounsafe. Errors go throughResultand?, input-derived indices and sizes are checked, and every crash fix ships with a regression test. See Never crash inAGENTS.md. - Commands, not handlers: new features are engine commands, and the UI calls them (checklist below).
- Layering:
cargo xtask layersmust pass. Register new crates inxtask/src/layers.rs. - Tests: follow the test rules in
AGENTS.mdand standards/testing.md. Format code can use round-trip and malformed-input tests. Pixel code can be tested at 8, 16 and 32-bit. If you touch psd, io, codecs, compose, gpu, text or format, also run the real-file corpus tests:cargo xtask test-corpus(fetches the pinned corpora, including our Photoshop oracles from https://github.com/storytold/photocraft-corpus, then runs thecorpus-feature tests; CI always runs them). Never commit corpus files; seedocs/development.md› Test corpora. Tests never require a string to be translated: a missing translation shows in English, so no test may fail because a catalog lacks a row (cargo xtask i18n-reportlists the gaps instead). - Style:
cargo fmt, andcargo clippy -- -D warnings. Match surrounding code. Comments explain why. - UI: use
theme::Tokensand the framework components (Button,NumberField,Select,Slider). Verify visually (offscreensnapshotexample or the control channel) before submitting, and attach before/after screenshots to PRs. - Commits: small, focused, with a clear subject line.
Adding a command
- Find the id. Search
crates/ui-egui/src/menu_catalog.rsfor the Photoshop menu item. Using its id makes the menu item live with no UI work. Commands without a Photoshop menu entry use a descriptive id in the same style (layer.smartFilter.delete) and an empty menu path. - Algorithm goes in the lowest crate that fits (
algofor imaging,paint,vector,text; colour management iscraft-cmsin craft-libs), with unit tests. It takes depth-agnostic surfaces (photocraft-raster), works per tile, and is deterministic (seeded randomness). - Command goes in an engine module (
crates/engine/src/<area>_cmds.rs) exposingspecs(), registered by adding("<module>", crate::<module>::specs)toTABLESincrates/engine/src/install.rs(after the table it follows in the menus) and its ids tocrates/engine/src/install/command_ids.txt(the order test says how). A command in a core menu goes in the owner fragmentcrates/engine/src/cmd/table/<owner>/<menu>.rsinstead. Fill in:id,label,menupath and Photoshop's defaultshortcut,- a params doc string such as
{"radius":px=4,"mode":"a|b"="a"}(this is what agents read throughcommands/command_list), - an
enabledpredicate (greys the menu item out), run, which returns a JSON result and records exactly one history step (usecoalescefor drags and typing sessions).
- Respect the context: active selection (feathered), layer vs mask target, locks, the colour model and depth.
- Tests in the module for behaviour that could regress, such as undo/redo and several depths. Add the command to the
panic_huntsweep (crates/engine/tests) instead of writing a bad-params test per command. - Dialog (if it has parameters): filters and adjustments get schema-driven dialogs with live preview (
ui-egui/src/filter_dialog.rs,dialogs.rs). - Run
cargo xtask parityand commit the updateddocs/parity-checklist.md.
Repository guide
Documents
| Read | Why |
|---|---|
docs/architecture.md |
Crate map, dependency layers, the engine/UI seam, document model |
docs/development.md |
Build, test, run, drive the app programmatically, debug tricks |
docs/contributing.md |
Rules: clean-room, tests, layering, style, commits; the "add a command" checklist |
docs/control-protocol.md |
JSON control channel: how agents drive and screenshot the running app |
docs/ui-design.md |
Design tokens, themes, widgets, and how to match Photoshop's look |
ROADMAP.md |
One-page summary: stage, the two parity numbers, every dimension, languages, what's next |
docs/target-app-parity.md |
The authoritative parity assessment against Photoshop 2026: numbers, weights, evidence, hours |
docs/gaps.md |
Every known shortfall, ranked: the work list to pick from |
docs/roadmap.md |
Milestones, current focus, what's next with estimates |
docs/ui-parity.md, docs/brush-parity.md, docs/context-menu-parity.md, docs/file-format-parity.md, docs/hardware-parity.md, docs/localization-parity.md |
Per-dimension parity checklists |
docs/parity-checklist.md |
Generated list of every Photoshop menu item, live or missing |
docs/scorecard.md |
Generated scorecard: performance budgets and numbers, corpus floors, per-area checklists (tools, files, UI, type, automation, reliability, distribution), settings that do nothing |
crates/<name>/README.md (where present) |
Public API of that crate |
photocraft-corpus + docs/development.md › Test corpora |
Real-file test oracles (our Photoshop-authored PSDs and GIMP-authored XCFs); with psd-tools, ag-psd and PngSuite fetched into corpus/ by cargo xtask corpus --all at the pins in xtask/src/corpus_pins.rs |
Workspace map
crates/
geom color raster L0 foundation (geometry, pixel formats + blend math, COW tiles); ICC colour management is craft-cms (craft-libs)
ipp raw L0 standalone crates (no workspace deps): CUPS printing client, camera-raw develop
tablet L0 standalone pen tablet input (macOS AppKit, X11 XInput2, Windows barrel button); the one isolated unsafe crate
doc L1 document model (layers, masks, adjustments, effects, smart objects: pure data)
ops paint algo text vector L2 history, brush engine, imaging algorithms, type engine, paths/shapes
compose gpu format L3 CPU compositor (the oracle), wgpu compositor, .pcraft native format
io plugins L4 document <-> PSD / flat formats; sandboxed WebAssembly plug-ins
engine L5 Session + command registry (every action is a command)
ui-egui automation L6 egui shell (thin: all actions go through the engine); MCP server
testkit oil-round-proof test helpers
apps/
photocraft desktop app (eframe/wgpu), TCP control server
photocraft-cli headless CLI (convert/info/run/batch/commands/mcp)
photocraft-web the same app in the browser (trunk + wasm-bindgen)
photocraft-web-boot starts the packaged browser app from compressed parts of its wasm (no file over a host's size cap)
xtask/ cargo xtask layers | wasm | ci | stats | corpus | test-corpus | parity | perf | scorecard
Layering is enforced by cargo xtask layers. A crate may depend only on lower layers. psd and codecs depend on nothing in the workspace. Nothing below ui-egui may use egui, eframe, winit or rfd. A new crate must be registered in xtask/src/layers.rs.
Picking work
Priorities: important infrastructure first, then low-hanging parity, then the long tail.
- Read
ROADMAP.md, thendocs/gaps.md.docs/target-app-parity.mdsays, dimension by dimension, where PhotoCraft is lacking;docs/gaps.mdranks the work.docs/parity-checklist.md(menu wiring) is not a measure of behaviour. When your work moves a number or closes a gap, update the parity doc and gap entry it belongs to, with the date, and bump their status line and revision history. - Check
docs/scorecard.mdbefore picking work: each area'smissingandpartialrows, the performance scenarios that are over budget or not measurable yet, and the count of settings that do nothing. Its numbers are measured; prefer them to estimates. docs/roadmap.md→ Current focus.cargo xtask parity→docs/parity-checklist.mdlists every missing menu item, grouped by menu. Low-hanging fruit is usually a missing command whose algorithm already exists inalgo,paint,vectorortext.log/devlog.md→ the "Still open" bullets of recent entries.
When parity rises, raise FLOOR in crates/ui-egui/src/parity.rs (never lower it).
Checks by area
cargo test -p <crates you touched>
cargo clippy -p <crates> --all-targets -- -D warnings
cargo xtask layers
cargo xtask panel-commands # if you touched ui-egui: click handlers dispatch command ids (AGENTS.md rule 14)
cargo xtask wasm # if you touched L0–L6
cargo xtask parity # if you added commands; commit the regenerated docs/parity-checklist.md
cargo test -p photocraft-engine --test panic_hunt -- --ignored # hostile-input sweep over every command
cargo xtask scorecard # if you moved a number: flip the checklist row in scorecard/*.toml, raise a
# corpus floor, fix a dead preference, or meet a budget (then set enforce = true
# in perf/budgets.toml); commit the regenerated docs/scorecard.md (CI checks it)
cargo xtask perf --quick # if you touched a hot path; `cargo xtask perf --update-baseline` publishes a full run
cargo xtask test-corpus # if you touched psd, io, codecs, compose, gpu, text or format (or: --changed decides)
While iterating, run less and keep the full commands above as the final gate: cargo test -p <crate> --lib --tests skips the examples and doctests plain cargo test builds every time (ui-egui has 11 examples), and cargo test -p <crate> --test <file> runs one integration-test file. cargo nextest run runs tests in parallel across binaries; see docs/development.md › Faster test loops.
MCP in tests and agent sessions: photocraft-cli mcp --headless. Plain photocraft-cli mcp works in the open PhotoCraft window while the ArtCraft Launcher's agents switch is on, and then may start PhotoCraft on the developer's machine when it is closed. Scripts, tests and agents that want a session without a window pass --headless (or use photocraft-cli serve); a test that runs the CLI also gives it its own settings, launcher and flags folders (PHOTOCRAFT_CONFIG_DIR, CRAFT_MCP_DIR, CRAFT_FLAGS_FILE, as crate::command() in apps/photocraft-cli/tests/it/main.rs does). To drive the running app on purpose, use --control (docs/development.md).
Test corpora. Real-file corpora live in corpus/ (gitignored, never committed), fetched at pinned commits and sha256-verified by cargo xtask corpus --all: our Photoshop- and GIMP-authored oracles from https://github.com/storytold/photocraft-corpus plus psd-tools, ag-psd and PngSuite from their upstreams. Pins: xtask/src/corpus_pins.rs. The corpus tests are opt-in (cargo feature corpus): plain cargo test skips them, and with the feature on a missing corpus fails ("run cargo xtask corpus --all"). cargo xtask test-corpus fetches and runs them all. CI always runs them (the corpus job, cached by pin). Never commit corpus files; new oracles go to photocraft-corpus (its AGENTS.md), then a pin bump here. Details: docs/development.md › Test corpora.
The dev log is log/devlog.md (local, gitignored).
Where things are tracked
docs/roadmap.md: milestones M0–M12, status and the current focus.ROADMAP.md,docs/target-app-parity.md,docs/gaps.mdand thedocs/*-parity.mdchecklists: where we stand against Photoshop.docs/parity-checklist.md: generated Photoshop menu coverage.docs/scorecard.md: generated scorecard (sources:scorecard/*.toml,perf/budgets.toml,perf/baseline.json, corpus floors, prefs audit).docs/releasing.md: cutting a release (cargo xtask version, thereleasebranch), signing secrets, packaging scripts inpackaging/.plan/is an optional gitignored notebook (research, parity notes, estimates). Do not ask for it and do not stop when it is absent.log/(local, gitignored): the dev log.
Native format
photocraft-format deliberately fails to compile when a photocraft-doc struct gains a field, so
nothing is silently dropped from .pcraft saves. When you add a doc field, add it to
crates/format/src/manifest.rs and convert.rs with #[serde(default)] so older files still load.
If the field has a PSD equivalent, map it in crates/io too, and keep unknown PSD blocks verbatim.
Contributor credits (About window)
About, Contributors and Models are compiled into the binary from contributors/contributors.json (generated, never hand-edited) and contributors/people.toml (names people chose for themselves). See docs/contributors.md.