A drawing app built for agent/human collaboration
Rust
Last updated: 2026-11-10 16:10
Last updated: 2026-11-04 19:41
Agent-first 2D art application in Rust: a klad CLI for agents and a native editor for people with a pen, sharing one document bundle on disk. What and why: docs/DESIGN.md. How to build, test and send a change: CONTRIBUTING.md. How an agent draws with it: docs/skill/SKILL.md.
Toolchain
- Rust stable through rustup with clippy and rustfmt (
rust-toolchain.toml),justfor recipes.justbuilds into a folder per platform,target/on macOS andtarget/linux(ortarget/windows) elsewhere, whateverCARGO_TARGET_DIRsays, so a checkout shared between a Mac and a Linux machine never mixes their binaries (KLAD_TARGET_DIRoverrides it);just buildends by running the binary, so a binary for the wrong platform fails there. Run cargo from the repository root, withCARGO_TARGET_DIRset to the same folder when calling cargo directly. - The editor (
crates/app,klad open) runs on macOS for now. It compiles and its tests run on Linux too;klad openexists only in the macOS build. - The editor's panels run headless in tests through
egui_kittest(Editor::openneeds no GPU): click, type, drag, read sizes and accessible names.just ui-picturesandcargo test -p klad-app -- --ignored start_picturesrender the UI intoscratch/ui/with a blank canvas;editor_picturedraws the canvas too, andguide_picturesrenders the editor pictures indocs/guide/from the built samples (copy them fromscratch/ui/guide/todocs/images/guide-*.png) (the kittest renderer gets the canvas resources, and the canvas is redrawn once it has caught up, since uploads made in a pass kittest did not render are lost).just ui-timemeasures UI work per frame;just drag-time(orjust drag-time <bundle>, which drags in a copy) measures drags on a generated poster-like drawing: how often the preview updates, the release frame and what follows it, and a layer switch. cargo test -p klad-appalone does not rebuild thekladbinary that the job and thumbnail tests run;just test(the workspace) does.- macOS-only code (
crates/app/src/pen.rs,crates/app/src/picker.rs) can be type-checked from Linux withrustup target add aarch64-apple-darwinand a small scratch crate holding the module and its objc2 dependencies (cargo check --offline --target aarch64-apple-darwin); the full workspace cannot,zstd-sysneeds the macOS SDK.
Working
- Every doc in
docs/starts with a_Last updated: YYYY-MM-DD HH:MM_line; update it when the doc changes. - Guides in
docs/guide/are short how-to pages for people in the editor. A page opens with one sentence on what it lets you do and stays under about 300 words; each section is one task titled as the goal, verb first, done the shortest way in numbered steps of one action each (where, then what, then what happens), at most five. No option catalogues, no alternatives, no explaining how klad works inside: the editor names its options and?lists the keys. Keys and editor labels in bold, labels exactly as the editor writes them. Getting started is the one tutorial: a single path from a new drawing to changing a stroke. - Never commit build output or binaries, and check
git statusbeforegit add -A.samples/holds generators only; the bundles and pictures they make stay out of git. - Commit messages and docs name no one: say what changed and why.
mainis protected: never commit on it. Work on a branch off the newestorigin/main(feature/...,bugfix/...); it reachesmainthrough a pull request.
Done means
- Tests for new behaviour in the crate that owns it.
just lint(fmt check plus clippy with-D warnings),just testandjust auditare clean.- A change that moves a sample's hash says why.
Standing rules
- Every feature has a CLI form and an editor form (DESIGN principle 7): a change that adds one adds the other, with tests on both sides, unless it only makes sense on one side (the editor's view and settings; the CLI's batch, hash and test tools; the ops that draw from shapes,
ink,light,hatch,paint,scatterandfill --shape, which stay CLI only). - No comments in code except
// TODO:. - Iterator chains over
forloops where they read better; plain loops in hot pixel paths where they are clearer or faster. - Determinism in
core,brushandrender: transcendental math throughlibm, one seeded RNG (klad_core::rng), no wall clock, noHashMapiteration order in output, parallelism only over independent units (tiles, image rows). - Bundles are never broken by a format change: bump the format version (
klad/Nindoc.json) and add a migration, and updatedocs/format.mdin the same change.klad/1(2026-11-06) started clean: the.drawfolders before it (draw-anything/0to/9) do not open. - Permissive dependencies only: MIT, Apache-2.0, BSD-2/3, ISC, Zlib, BSL-1.0, Unicode-3.0, CC0-1.0; fonts bundled in the editor may be OFL-1.1 or the Ubuntu Font Licence (egui's), and the fonts in
fonts/OFL-1.1 or Apache-2.0 (fonts/update.pyfetches them unchanged; the notices list them). No GPL, LGPL or MPL unless dual licensed with one of these.deny.tomlholds the list andjust auditchecks it; every shipped licence text is inTHIRD-PARTY-NOTICES.md(just notices). - klad is source-available, not open source, copyright Indicode BV: the app is under the PolyForm Internal Use License 1.0.0 with permissions for personal use (free to build from source), proposing contributions and sharing drawings, and a limit: a company with 500,000 euros or more in revenue in its last tax year needs a bought licence per person; it also covers the builds it sells, and a bought build is such a licence (
LICENSE;license-filein Cargo, since it has no SPDX identifier).docs/format.md,docs/cli.md,docs/skill/andcrates/clientare MIT (LICENSE-MIT):klad-clientdepends on none of the other crates, a format change updatesdocs/format.mdin the same change, and a command change runsjust reference(a test checksdocs/cli.md). Outside contributions come in under the CLA (CLA.md). - No em-dashes in docs, messages or UI text.
just buildcounts the version up (patch;minorandmajoron request) for every release build made on the maintainer's machine; agents build withjust compile, which does not (plainjustisjust compile), and commit a counted-upCargo.tomlandCargo.lockwith the next change.