A drawing app built for agent/human collaboration
Contributing
Thank you for looking. klad is young and changes fast; issues with a drawing that shows the problem are the most useful thing you can send.
Before you start
- Bugs: open an issue with what you did, what you saw (run the command again with
KLAD_BACKTRACE=1for the details of an error),klad --version, your OS, and if you can the.kladfolder (zipped) or the commands that make it. - Larger changes: open an issue first, so we can agree on the shape before you build it.
- Something you made with klad: send it in through the "Made with klad" issue form, and it can go in the gallery on klad.studio. The site reads the form's answers by their headings, so a change to a field's label there goes together with
scripts/lib/showcase.mjsin klad-site. - Security problems: see
SECURITY.md, not the issue tracker.
Building
- Rust through rustup;
rust-toolchain.tomlpicks the version.justruns the recipes. - macOS: the Xcode command line tools. Linux:
pkg-config,libfreetype-dev,libfontconfig1-dev,libxkbcommon-devandlibwayland-dev. Windows: Visual Studio's C++ build tools; the check on every pull request builds it there. - The first build downloads a prebuilt Skia for your platform (
skia-bindingsdoes this), so it needs network once. just buildcounts the patch version up and buildskladandklad-editorfor this machine (just build minor,just build major;just compile, orjuston its own, builds without counting up),just test,just lint. They build intotarget/on macOS andtarget/linuxon Linux, so one checkout can be built from both.just auditneedscargo-denyandcargo-about(cargo install cargo-deny --lockedandcargo install cargo-about --locked --features cli).- The editor is
klad open, orklad-editoron its own (the app on a Mac, the program to start on Windows).cargo build --no-default-features -p klad-clibuildskladwithout the editor, for servers. Its panels are tested headless withegui_kittest;cargo test -p klad-app -- --ignored editor_picture(the editor with a sample drawing on its canvas),start_picturesandjust ui-pictureswrite pictures of the UI toscratch/ui/.
The rules the code follows
These come from CLAUDE.md, which is also the guide for coding agents working on the repository.
- No comments in code except
// TODO:. Names and small functions carry the meaning. - Iterator chains where they read better than loops; plain loops in hot pixel code where they are clearer or faster.
- Determinism:
core,brushandrendergive the same pixels on every machine. Transcendental math goes throughlibm, randomness through the seededklad_core::rng, no clock, noHashMaporder in output, parallelism only over independent tiles or rows. A change that moves a sample's hash says why. - Drawings never break: a format change bumps the format version (
klad/N) and adds a migration, so older.kladdrawings open unchanged, and updatesdocs/format.md. A migration converts, it never drops: what a drawing holds survives every later version. (klad/4dropping the rigs ofklad/1toklad/3, before 1.0, was the last exception.)tests/formats/holds drawings saved by each release with their frame hashes; the test opens them all, and a change that makes one render differently is fixed, or listed intests/formats/accepted.txt(<version>/<bundle> <frame> <new hash>) and in the release notes. - Dependencies are permissive only (MIT, Apache-2.0, BSD, ISC, Zlib and the others in
deny.toml). Adding one meansjust auditpasses andjust noticesregeneratesTHIRD-PARTY-NOTICES.mdin the same change. - Every feature has a CLI form and an editor form: a new command or op also gets its place in the editor, and an editor feature gets its command or op, with tests on both sides. The ops that draw from shapes (
ink,light,hatch,paint,scatter) are the exception and stay CLI only. - New behaviour comes with tests in the crate that owns it.
just lintandjust testare clean before a pull request. - No em-dashes in docs or messages; every doc in
docs/starts with a_Last updated:_line. - Guides in
docs/guide/are short how-to pages: one task per section, titled as the goal, done the shortest way in numbered steps, under about 300 words a page, with no catalogues of options.
Sending a change
- Fork, branch from
main, keep the change to one thing. just lint,just testandjust auditpass.- Describe what changed and how you checked it; for anything visual, attach a render (
klad render) before and after. - The first time, the CLA assistant asks you in the pull request to sign the contributor licence agreement (
CLA.md): one click, and it covers every later change. Under it your contribution is licensed to Indicode BV for inclusion in klad and in the builds of klad it sells; you keep the copyright to your work.
klad is source-available, not open source (LICENSE): its licence lets you send changes to Indicode BV to propose them, so a fork on GitHub for pull requests is fine; publishing klad or builds of it elsewhere is not. docs/format.md, docs/cli.md, docs/skill/ and crates/client/ are MIT (LICENSE-MIT); klad-client depends on nothing in the other crates, so it stays MIT on its own.
Releases
The Mac and Windows builds are sold on itch.io (and later Steam); Linux is built from source. GitHub has the release notes, not downloads.
just build minor(ormajor) sets the release's version; move the changes under "Unreleased" inCHANGELOG.mdto a section## x.y.z (date)with that version..just formats x.y.zsaves seven samples with their hashes intotests/formats/x.y.z/(afterjust samples;packaging/formats.sh <klad> x.y.z <folder>takes them from another folder, laid out as<name>/<name>.klad). Commit.- On a Mac with butler logged in:
ITCH_TARGET=<user>/<page> just itch-macbuilds the app (arm64 and x86_64 in one) and pushes it to the page'smacchannel. - Tag
vx.y.zand push the tag. Thereleaseworkflow runs the checks, builds the Windows version and pushes it to thewindowschannel (with theBUTLER_API_KEYsecret and theITCH_TARGETvariable set in the repository), then publishes that changelog section as the release notes, which the editor's update check reads. - The builds are not signed yet.