A drawing app built for agent/human collaboration
Last updated: 2026-11-12 23:00
klad: design
A 2D art application built for agents first and humans second, for professional game assets in any style.
An agent drives it through a CLI and sees results as PNG renders. A person with a pen opens the same file in a native editor to edit, add detail and animate. Both work on one document on disk at the same time.
Principles
- Everything is addressable. Layers, cels, vector nodes and individual paint strokes have ids. An agent never has to describe something by its pixels.
- One set of pixels. The CPU produces every pixel, in the CLI and in the editor, from the same code. What the agent renders is what the human sees.
- Non-destructive by default. Paint layers keep their strokes, vector layers keep their geometry, filters and adjustments keep their settings. Baking to plain pixels is an explicit choice.
- Time is in the model from the start. Every layer's content lives in cels on a timeline. A still image is a one-frame document.
- Edit and see in one call. Every mutating CLI command can render and return the PNG path.
- Professional output. 16-bit float layers, colour management, proper blend modes, exports a game engine can use as they are.
- Both hands can do everything. Every feature has a CLI form (a command or an
applyop) and an editor form (a tool, pane, window or command), doing the same thing through the same code. Only what makes sense on one side alone is exempt: the editor's view, pen calibration and keys; the CLI's batch, hash and test tools; and the ops that draw from shapes (ink,light,hatch,paint,scatter,fill --shape), which are how an agent draws what a person draws by hand.
Architecture
crates/
core document model, ids, timeline, stroke format, bundle IO, op log
brush tile store, brush engine, stroke replay, checkpoints
render compositing, vector rendering, filters, overlays (Skia, CPU raster)
cli the `klad` binary, and `klad-editor`
app the editor, behind the `editor` feature (on by default)
Two binaries from one crate: klad, the command line, and klad-editor, the editor alone (a windowed program on Windows, the executable of klad.app on a Mac, started by the Linux AppImage). klad open [bundle] launches the same editor from the command line, on the bundle or, without one, on the start window (new, open, recent). --no-default-features builds klad without the editor. klad --version and the editor's About show the version and git describe of the commit it was built from (crates/version.rs, shared by both crates' build scripts; KLAD_BUILD overrides it).
Platforms and packaging (M7). Folders follow each platform: settings in ~/Library/Application Support/klad, %APPDATA%\klad or $XDG_CONFIG_HOME/klad; downloaded fonts in the same places' data folder; drawings in ~/Drawings by default. The open panel is NSOpenPanel on macOS and rfd elsewhere (the XDG portal on Linux, the common dialog on Windows). The pen: macOS reads NSEvent; elsewhere a pen that the system reports as a touch with force (Windows pens through WM_POINTER) draws with that pressure (pen::from_egui), and anything else draws as a mouse at full pressure; Linux tablets report no pressure through winit yet. packaging/ makes the downloads: macos/app.sh builds klad.app (both binaries, lipo'd when several targets are given, the fonts, licences and skill in Resources, .klad declared as a document package of type com.indicode.klad.drawing so Finder shows a drawing as one item and opens it in klad) and a disk image; archive.sh <target> builds a tar.gz or zip with both binaries, fonts/, the licences and SKILL.md, and an AppImage on Linux when APPIMAGETOOL is set; icon/ draws the icon in klad and packs klad.icns and klad.ico (the icon is a K in two brush strokes with paint body and a dry edge, an ink stem and one ember stroke for the arm and the leg; build.sh <folder> keeps the drawing to open in the editor). Builds use the dist profile (no debug info, stripped, thin LTO); the samples hash the same from it. The fonts are found next to the binary (fonts/), in ../Resources/fonts or ../share/klad/fonts. On macOS a drawing opened from Finder arrives as an application:openURLs: message, which klad adds to NSObject before the event loop starts so it reaches whatever delegate winit installs; the paths queue up (opened.rs) and the start window or editor opens the last. klad install puts klad on the terminal's path (a link in /usr/local/bin through an administrator prompt on macOS, ~/.local/bin on Linux, the user's PATH on Windows); the editor's document menu runs it as a job. klad skill prints the agent skill compiled into the binary; klad samples lists and copies the sample drawings a build carries (First start, below). Builds are sold on itch.io (later Steam) for macOS and Windows, and Linux is built from source: on a version tag the release workflow builds the Windows version and pushes it to itch.io with butler (never as a workflow artifact, which anyone could download from a public repository) and publishes the changelog section as the release notes, and just itch-mac builds and pushes the Mac app from a Mac; check runs the format check and the licence and advisory audit on every pull request and every push to main; build runs on every push to main and when started by hand from the Actions tab (on any branch), not on pull requests, since three builds per pull request is a lot; it does what the README tells someone who clones klad, on macOS, Linux and Windows: the Linux packages it lists, just compile, then a stroke painted and rendered with that build, then the tests. Each job writes what it saw (the errors and the last lines of each step) into its summary on the run's page. The tests have to pass on all three. On Windows a program's main thread gets 1 MB of stack against 8 MB elsewhere, so crates/version.rs (the build script of the command line and the editor crates) asks the linker for 8 MB for klad's binaries, and the command line crate is compiled at opt-level = 1 in debug builds, where it otherwise needs 2 to 4 MB; the workflow prints the stack size the Windows binaries were linked with. Text files check out with unix line endings on every system (.gitattributes), because the agent skills and other texts are compiled into the binary and git on Windows would otherwise hand them over with Windows line endings; the fonts' licence texts, the notices and the drawings of earlier releases are kept byte for byte. Pixel hashes are the same on machines of one processor family only: the vector parts are drawn by Skia, whose fast paths differ between ARM and Intel. So the test that opens the drawings of each release (crates/cli/tests/formats.rs) compares pixels on ARM, where its hashes were made (the Macs and the macOS runner), and on Intel checks that every frame still opens and renders. The editor asks the GitHub releases API at most once a day (updates.rs, curl on a thread, off in the settings window) and, when a newer version is out, says so in the start window, the message line and About, with a link to what changed; it installs nothing. About's "check now" and klad updates check on demand (updates::spawn, a channel per check) and say why a check failed: no release published yet, no network, or a feed that does not parse.
Stack
| Part | Choice | Why |
|---|---|---|
| Language | Rust stable | Native threads and memory for large canvases, fast CLI start, one codebase for CLI and editor |
| Vector, text, filters, compositing | Skia via skia-safe, CPU raster only |
Mature 2D engine (paths, booleans, gradients, image filters, SkSL shaders, text shaping). Same build on macOS and Linux |
| Brush engine | Our own, dab based, on tiles | Full control over quality and determinism. Krita and MyPaint are the reference designs |
| Editor window and GPU display | winit + wgpu (Metal), through eframe |
The GPU only shows CPU-made tiles: pan, zoom, rotate, overlays |
| Editor panels | egui |
Fast to build, proven in pro tools (Rerun) |
| Pen input (macOS) | NSEvent local monitor through objc2-app-kit |
winit only reports trackpad pressure; the monitor gives tablet pressure, tilt and the eraser end at full rate |
| File dialogs (Windows, Linux) | rfd |
The platform's own dialog (the XDG portal on Linux); macOS keeps NSOpenPanel |
| Compression | zstd |
Stroke files and cache tiles |
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, proposing contributions and sharing drawings, which also covers the builds it sells (LICENSE; license-file in Cargo, since it has no SPDX identifier); the file format (docs/format.md), the command reference (docs/cli.md, written by klad reference), the agent skill and the klad-client crate (crates/client, which runs the CLI and depends on no other klad crate) are MIT (LICENSE-MIT), so any program or agent can work with klad drawings. Contributions come in under a CLA (CLA.md, signed through the CLA assistant). Every dependency is permissive: MIT, Apache-2.0, BSD-2/3, ISC, Zlib, BSL-1.0, Unicode-3.0, CC0-1.0, and for the fonts the editor shows its interface in, OFL-1.1 and the Ubuntu Font Licence. No GPL, LGPL or MPL unless dual licensed with one of these (two crates are, and are taken as self_cell under Apache-2.0 and r-efi under MIT). deny.toml holds the list, RustSec advisories, yanked versions and crates.io as the only source; just audit checks it with cargo deny and that THIRD-PARTY-NOTICES.md is current (just notices makes it with cargo about, plus the parts Cargo does not see: Skia's built-in libraries and the fonts, from licenses/bundled/). klad licences and the editor's About window show the same text.
Dependencies
Direct dependencies, checked 2026-11-04 (all on their latest release; cargo audit found no vulnerabilities):
| Crate | Used in | For | Licence |
|---|---|---|---|
skia-safe 0.157 |
render | paths, gradients, filters, compositing, PNG and JPEG codecs; links a prebuilt Skia m157 | MIT (Skia BSD-3) |
skrifa 0.44 |
render | font outlines, metrics and variation axes for text nodes (replaced the unmaintained ttf-parser, RUSTSEC-2026-0192) |
MIT OR Apache-2.0 |
harfrust 0.12 |
render | text shaping (kerning, ligatures, marks); already in the build through egui | MIT |
zune-jpeg |
render | JPEG decoding for picture layers | MIT OR Apache-2.0 OR Zlib |
png |
brush, render, app | PNG for brush pictures, picture layers and thumbnails | MIT OR Apache-2.0 |
zstd |
core, brush, cli, app | stroke files, cache tiles, history | BSD-3 |
half |
core, brush, render, app | f16 tiles | MIT OR Apache-2.0 |
libm |
core, brush, render, cli | deterministic transcendental math | MIT |
rayon |
brush, render, cli, app | parallel tiles and rows | MIT OR Apache-2.0 |
serde, serde_json |
all | the bundle's JSON, ops, settings | MIT OR Apache-2.0 |
bytemuck |
brush, render, app | pixel buffers as bytes | Zlib OR Apache-2.0 OR MIT |
anyhow |
all | errors with context | MIT OR Apache-2.0 |
clap |
cli | the klad command line |
MIT OR Apache-2.0 |
notify |
cli, app | watching a bundle for the other side's edits | CC0-1.0 |
libc |
cli | default SIGPIPE handling, so piping klad into head ends quietly |
MIT OR Apache-2.0 |
eframe, egui, egui-wgpu 0.37 |
app | the editor's window, GPU display and panels | MIT OR Apache-2.0 (egui's fonts: OFL-1.1, Ubuntu Font Licence) |
pollster |
app | blocking on wgpu setup | Apache-2.0 OR MIT |
objc2, objc2-app-kit, objc2-foundation, block2 |
app, macOS | the pen through NSEvent, the open panel, drawings opened from Finder | MIT |
rfd 0.17 |
app, Windows and Linux | the open panel (XDG portal, Windows common dialog) | MIT |
egui_kittest (dev) |
app tests | headless UI tests | MIT OR Apache-2.0 |
Accepted warnings: zvariant, zvariant_derive and zbus_names (unmaintained) and async-executor 1.14.0 (yanked) come only through eframe's Linux accessibility (accesskit_unix) and wait on eframe moving to zbus 6.
Determinism
The CLI render and the editor must agree. Rules for core, brush and render:
- Transcendental math (
pow,exp,sin,cos,atan2) goes through thelibmcrate, never the platform libm. - One seeded RNG type (
core::rng), seeded per stroke. No wall clock in rendering. - No
HashMapiteration order affecting output. Tiles live in a fixed grid. - Parallel work is split into independent units (tiles, image rows), each computed the same way regardless of thread count.
klad hashprints a hash of rendered pixels; the parity check compares macOS and Linux.
The document bundle
docs/format.md specifies everything below for other programs, byte by byte; this section is how klad itself uses it.
art.klad/
doc.json canonical document (pretty JSON, stable key order)
strokes/<layer>/<cel>.strokes stroke and fill records per cel (binary, zstd)
brushes/<id>.json every brush the document uses, embedded on first use
assets/ imported images (PNG)
.gitignore ignores .cache/
.cache/ rebuildable: pixel tiles, checkpoints, renders, op log
Committed: everything except .cache/. A fresh clone rebuilds the cache by replaying strokes and fills.
doc.json (format klad/7)
{
"format": "klad/6",
"canvas": { "width": 2048, "height": 2048, "background": "#f4efe6" },
"timeline": { "fps": 12, "frames": 24, "origin": [1024, 1800],
"clips": [{ "name": "run", "from": 0, "to": 11, "loop": true, "fps": 24 }, { "name": "jump", "from": 12, "to": 23 }] },
"export": { "godot": "../game/art/hero" },
"palette": [{ "color": "#1b1b1b", "name": "ink" }, { "color": "#f0c8a0", "name": "skin" }, { "color": "#5b6ee1" }],
"layers": [
{ "id": "l3", "name": "lines", "kind": "paint", "opacity": 1, "blend": "normal", "visible": true,
"cels": [
{ "id": "c1", "frame": 0, "hold": 2 },
{ "id": "c2", "frame": 2, "hold": 2 },
{ "id": "c3", "frame": 4, "hold": 2, "link": "c1" },
{ "id": "c9", "frame": 6, "hold": 1, "tween": { "from": "c2", "to": "c10", "t": 0.5, "made": "3f0c9e21a4b6d870" }, "parts": { "leaf": [14, 15] } },
{ "id": "c10", "frame": 7 }
] },
{ "id": "l5", "name": "shade", "kind": "paint", "blend": "multiply", "clip": true, "lockAlpha": true,
"cels": [{ "id": "c6", "frame": 0 }],
"mask": { "id": "l7", "name": "mask", "kind": "paint", "cels": [{ "id": "c8", "frame": 0 }] } },
{ "id": "g1", "name": "fx", "kind": "group", "opacity": 0.8, "blend": "screen", "visible": true,
"children": [] },
{ "id": "l4", "name": "shapes", "kind": "vector", "opacity": 1, "blend": "normal", "visible": true,
"cels": [{ "id": "c4", "frame": 0, "nodes": [
{ "id": "n5", "name": "sky", "type": "rect", "x": 0, "y": 0, "w": 2048, "h": 900,
"fill": { "linear": { "from": [0, 0], "to": [0, 900], "stops": [[0, "#121d31"], [1, "#4a6a8c"]] } } },
{ "id": "n6", "type": "group", "transform": { "rotate": -8, "x": -120 }, "children": [
{ "id": "n7", "type": "path", "d": "M380 560 L560 560 L530 600 L410 600 Z", "fill": "#2b1d14",
"stroke": { "paint": "#000000", "width": 3 } } ] }
] }] }
]
}
- Layers are listed bottom to top.
lsprints them top first, like a layers panel. - Ids are unique across the document (letters, digits,
-,_): new ones arel,candnplus a counter. - A cel is a layer's content from
frameon.holdlimits it to that many frames; withoutholdit lasts until the next cel. Drawing on twos ishold: 2.linkreuses another cel's content; links cannot chain. Paint cels keep their strokes instrokes/<layer>/<cel>.strokes. In animation terms a cel that is not a link is a drawing, the frames it shows on are its exposure, and frames no cel covers are blank. The timeline (frames) always covers every cel's first frame: an op that puts a cel past the end makes the timeline longer, and a stroke, fill or shape added at a frame past the end starts a cel there instead of landing in the last open exposure. - An in-between is a drawing made by
inbetweenfrom two keys: its cel keepstween(format 6) with the keys' drawing ids (from,to), its positiontbetween them (0 to 1, after spacing), how its marks were paired when not by id (match:orderornear, and forcedpairsas[first key id, second key id]) andmade, a hash of the marks as they were made.inbetween --redoremakes in-betweens from their keys and refuses one whose marks no longer hash tomade(drawn on or edited since) unless forced. A link cannot be an in-between;set <cel> tween=nullmakes it an ordinary drawing.unpaired(format 7) keeps how marks in one key only were shown (pop,pop 0.3,fade,draw-on), so a redo shows them the same way. - A cel's parts (format 7) name groups of its marks:
"parts": {"leaf": [14, 15], "near leg": [9]}. A mark is in one part at most. They live in the cel record, not in the stroke file, so naming parts never rewrites strokes; ids that no longer exist are ignored.dup,unlink,copyand in-betweens keep them (an in-between gets the first key's parts, as it keeps its ids). Format 6 documents open as format 7 without parts. - A clip is a named frame range, both ends included: an animation such as
idle,runorattack. It loops or plays once (loop), and may have its ownfps(format 5); without one it plays at the timeline's. Names are unique and clips may overlap. Clips are kept in order of their first frame. Exports turn each clip into an engine animation. Frame ops on every layer move and stretch clips (an insert inside a clip lengthens it, a remove shortens it, a clip left with no frames goes); frame ops on listed layers leave them alone; a shorter timeline trims clips and refuses to cut one off entirely. - The origin (
timeline.origin, format 5) is the canvas point an engine export puts on the node's position, the centre of the canvas when absent. export.godot(format 5) is the folder Godot exports go to, relative to the folder holding the bundle, so the CLI and the editor's "export to Godot" button write to the same place.- The palette is the document's colours, each with an optional unique name (not starting with
#). Wherever an op or a CLI flag takes a colour for a stroke or a fill it also takes a palette name; the stroke or fill stores the colour itself, so renaming or recolouring a swatch never changes what is drawn. - Nodes (vector cels):
rect(x, y, w, h, radius),ellipse(cx, cy, rx, ry),path(SVGd),group(children). Each takesfill,stroke,transform,opacity,blur(Gaussian sigma in px, softens the whole node; when the blur reaches 12 device px or more the node is drawn 2 to 32 times smaller on a power-of-two grid aligned in device space, blurred there with an exact Gaussian in Rust and scaled back up, which is about 3 times faster than Skia's CPU blur and closer to a true Gaussian; non-uniformly scaled nodes keep Skia's blur),clip(an SVG path in the node's own coordinates that clips it and its children),visible,name. - Paint is
"#rrggbb","#rrggbbaa","none",{ "linear": { "from", "to", "stops" } }or{ "radial": { "center", "radius", "stops" } }, in the node's own coordinates. As in SVG, a missing fill is black and a missing stroke is none. Strokes default to width 1 with round caps and joins;dashtakes SVG-style intervals. - Transform is
x,y,rotate(degrees),sx,sy,pivot; it applies translate, then rotate and scale about the pivot, which defaults to the centre of the node's bounds. - Masks.
maskis a paint layer kept under the layer it masks, with its own id, cels and stroke files (strokes/<mask id>/<cel>.strokes). Its alpha hides the layer: strokes and fills on the mask hide, the eraser shows the layer again, and an empty mask (or a frame without a mask cel) hides nothing.visible: falseturns the mask off. A mask keeps opacity 1 and blend normal and has no mask or clip of its own. Paint, vector and group layers can have one. Internally a mask's layer path ends inMASK, solocate,layer_atand the history treat it as a layer. - Clipping.
clip: trueshows a layer only where its base, the nearest layer below it in the same list withoutclip, has alpha. The base and the clipped layers above it draw as one group: each clipped layer blends onto the base with its own blend and opacity (masked by the base's alpha), then the group composites onto what is below with the base's blend and opacity, as in Photoshop with "blend clipped layers as group". A hidden base hides its clipped layers; the lowest layer of a list draws unclipped. - Lock alpha.
lockAlpha: trueon a paint layer makes new strokes and fills land only where the layer already has alpha: they composite source-atop and leave alpha unchanged. The flag is recorded on each stroke and fill (stroke format 5), so turning it off later never changes what was drawn. An eraser stroke on a lock-alpha layer changes nothing (the editor refuses it). - Nothing in
doc.jsonchanges on a write that does not change the drawing (klad/5, 2026-11-09): the revision and the id counter live in.cache/copy.json, so a stroke edit changes its stroke file only and git diffs and merges what was edited. Each copy of a drawing (a clone or a worktree: a folder without.cache/copy.json) picks a two-letter tag when klad first opens it; new layer, cel and node ids end in it (l48qa) and new mark ids carry it in their top 10 bits (c12:s349qa), and its counters only go up, so copies edited apart never make the same id, even across a branch switch in one copy. The copy a drawing is made in, and samples copied out, have no tag.klad infonames the tag. A drawing that still has an id used twice (two copies with the same tag, or a doc.json merged by hand) is refused on open withrepair::UsedTwice;klad repairand the start window's Repair and open runBundle::repair: in document order the first one keeps the id and every later layer, drawing or shape gets a new id from this copy, references inside its own layer (links, in-betweens, poses) or drawing (clips) follow it unless the old id is still there, and its stroke and weights files move, or are copied when the first one still uses the same file. References from other layers (a rig's skeleton) stay with the first. It is not an undo step: the drawing before it would not open.klad/1(2026-11-06) is the first.kladformat and starts clean: drawings from before it (.drawfolders,draw-anything/0to/9, stroke files markedDAST) are refused on open with the reason and not converted (migrate.rskeeps the place where later migrations go). From here on a format change bumps the number and migrates older.kladdrawings on open; history snapshots go through the same migration when undone.klad/2(2026-11-07) added IK (ikon skeletons and in poses); aklad/1drawing opens as it is, renamed.klad/3(2026-11-08) addedboneon paint layers, attaching a layer to one bone; older drawings open as they are.klad/4(2026-11-08) moved skeletons to bones layers that any paint layer joins throughrig(follow a bone, or bend); drawings from before open with their rigs dropped (a deliberate call: rigs were new and untested), their drawings kept. History patches never carry the change, because they are diffs of documents already migrated in memory. From 1.0 the format promise holds: every change migrates and nothing is dropped;tests/formats/<version>/keeps small copies of the samples saved by each release (just formats <version>,packaging/formats.sh) with each frame's hash, andcrates/cli/tests/formats.rsopens every one with today's build and compares the renders.tests/formats/pre-1.0/holds the samples as built before 1.0 (five drawings inklad/1andklad/4).
Edits
All edits are ops, applied as one transaction that either fully applies or changes nothing, and validated before anything is written. The CLI commands and klad apply (JSON lines) produce the same ops:
| Op | JSON line |
|---|---|
| add a layer | {"op":"add","layer":{"kind":"vector","name":"sky"},"above":"l2"} |
| add a node | {"op":"add","node":{"type":"rect","x":0,"y":0,"w":10,"h":10},"in":"l4","frame":0} |
| add a cel | {"op":"add","cel":{"frame":4,"hold":2,"link":"c1"},"in":"l3"} |
| set properties | {"op":"set","id":"n5","fill":"#ff0000","transform.rotate":15,"stroke":null} |
| remove | {"op":"rm","ids":["n5","l3"]} |
| move | {"op":"mv","id":"l3","below":"l4"} (or in, index) |
| paint a stroke | {"op":"stroke","layer":"l3","brush":"ink","size":8,"color":"ink","path":"M0 0 L90 40","taper":[12,30]} |
| fill | {"op":"fill","layer":"l2","at":[820,640],"ref":"lines","gap":4,"color":"skin"} or "polygon":[[x,y],...] |
| palette | {"op":"palette","add":"#f0c8a0","name":"skin"}, {"op":"palette","rm":"skin"}, {"op":"palette","set":[...]} |
| edit a stroke or fill | {"op":"set","id":"c4:s12","color":"skin","size":6,"brush":"pencil"}, {"op":"rm","ids":["c4:s12"]} |
| move, turn, scale marks | {"op":"transform","ids":["c4:s3","c4:s5"],"x":40,"y":-10,"rotate":15,"sx":1.2,"sy":1.2,"pivot":[512,400]} |
| path points | {"op":"path","id":"n7","move":3,"to":[412,230]}; also "move":[3,4],"by":[dx,dy], "handle":3,"out":[x,y], "insert":3,"t":0.5, "add":[x,y], "rm":[4,5], "corner":2, "smooth":6, "simplify":1.5 |
| add a mask | {"op":"add","mask":{"name":"mask"},"in":"l5"} ("hide":true starts it with a fill that hides the whole layer); rm the mask id to remove it |
| lasso | {"op":"lasso","layer":"l3","polygon":[[x,y],...],"cut":true,"x":40,"y":-10,"rotate":15,"sx":-1,"pivot":[..]} or "rm":true |
| timeline | {"op":"timeline","fps":12,"frames":24}, {"op":"timeline","origin":[512,700]} (null for the centre) |
| clips | {"op":"clip","add":"run","from":0,"to":11,"loop":true,"fps":24}, {"op":"clip","set":"run","name":"sprint","to":15,"loop":false,"fps":null} (null fps: the document's), {"op":"clip","rm":"run"} |
| export folder | {"op":"export","godot":"../game/art/hero"} (null forgets it) |
| frames | {"op":"frames","insert":4,"count":2}, {"op":"frames","remove":4,"count":2,"layers":["l3"]} |
| drawings | {"op":"cel","new":"l3","frame":5}, {"op":"cel","dup":"c4","frame":6,"insert":true}, {"op":"cel","link":"c4","frame":8,"hold":2}, {"op":"cel","unlink":"c9"}, {"op":"cel","move":"c5","frame":12} (keeps its length; the exposure it lands in is cut there and drawings it lands on are pushed along to its end); "id" names the new cel |
| duplicate a layer | {"op":"duplicate","layer":"l3"}: its cels, stroke files, links, in-between marks and mask copied with new ids, named " copy", right above it |
| copy marks | {"op":"copy","ids":["c1:s3","c1:s4"],"frame":4}, "to":"c9", "layer":"shade" with frame; x, y, rotate, sx, sy, scale, pivot as in transform; "cut":[[x,y],...] |
| retime | {"op":"retime","from":0,"to":11,"on":2}, "fit":16, "reverse":true, "pingpong":true; "layers":["l3"] |
| in-betweens | {"op":"inbetween","layers":["lines","colour"],"from":0,"to":6,"count":2,"spacing":"in-out","match":"near","pair":[[3,7]],"unpaired":"fade"}, {"op":"inbetween","layers":["lines"],"from":9,"loop":true}, {"op":"inbetween","redo":true,"keepDrawn":true} or "force":true (computed by the CLI; alone in its batch) |
| parts | {"op":"part","ids":["c4:s14","c4:s15"],"name":"leaf"} ("name":"" takes them out of their part); stroke, fill, ink, hatch and scatter take "part":"leaf" for the marks they add |
| ink from shapes | {"op":"ink","layer":"l3","from":["n5","n6"],"weight":6,"light":[-1,-1],"break":60,"gap":0,"wobble":0.6,"seed":1} or "path":"M..." (computed by the CLI into strokes) |
| shade and rim | {"op":"light","from":["n5"],"light":[-1,-1],"shade":"l5","rim":"l6","depth":14,"soft":3,"rimWidth":4,"shadeColor":"#5a4a6a","rimColor":"#fff1cc"} (computed into lasso fills with a cut) |
| hatching | {"op":"hatch","layer":"l5","in":["n5"],"angle":30,"spacing":6,"length":[12,30],"jitter":0.3,"weight":2} or "along":true (computed into strokes) |
| scatter | {"op":"scatter","layer":"l3","in":["n5"],"avoid":["n9"],"mark":"M0 0 L0 -18","count":40,"size":[0.7,1.2],"turn":[-15,15]} (computed into strokes) |
| fill a shape | {"op":"fill","layer":"l2","shape":"n5","color":"skin","expand":2} (computed into a lasso fill per closed outline); any fill may take "outside":[[x,y],...], a cut that keeps what lies outside that polygon |
| fills like a drawing | {"op":"fill","layer":"colour","like":"c4","frames":"0-11"} (computed by the CLI; alone in its batch) |
Unknown keys are errors that list the valid ones, so a typo never passes silently. Structure (id, kind, type, cels, children, nodes, mask) changes only through add, rm and mv; a mask cannot be moved, and nothing goes above or below it. A fill op needs pixels to compute its coverage, so the CLI computes it before the transaction, in op order: strokes and fills earlier in the same batch, and stroke edits, are part of what a fill sees.
Frames and drawings. frames insert puts count frames at a frame: what showed there now also shows on the inserted frames (the exposure covering it lengthens, a blank stays blank) and every later cel moves back. frames remove takes count frames out: exposures over them get shorter, later cels move forward, and a drawing left with no frames goes. Both work on every layer (then clips move with them and the timeline grows or shrinks) or on the listed layers and everything inside them (an insert lengthens the timeline only as far as their drawings need: a last drawing without a hold keeps its length, one with a hold must still fit; a remove leaves the length); a layer's mask always moves with it. Removing a drawing that links point to, by rm or by removing its frames, hands it to the first link: that link becomes the drawing (its strokes or nodes) and the other links point to it, so links never break. cel places a cel at frame on a layer: new a blank drawing, dup a new drawing with a copy of another's strokes and fills (mark ids kept, so a stroke in the copy is the same address in the new cel) or of its nodes (new node ids), link a link to another cel's drawing (a link to a link points to its source). Inside an exposure the new cel takes over the rest of it; on a blank frame it lasts until the next cel, or hold frames (dup and link default to their source's hold); dup and link default to the frame right after their source's exposure. With insert the layer's cels from that frame on move back by the new cel's length first (the timeline grows as for a listed-layer insert), which only works at the start or end of an exposure. unlink turns a link into a drawing of its own with a copy of its source. Copies of strokes are made when the batch is written, from the source as it is at that point of the batch.
Copies. copy copies strokes and fills (from one or more cels) into one drawing: to a cel, or the drawing a layer shows at frame (the marks' own layer unless layer; an empty frame or one past the end starts a drawing there; a frame showing a link names its source, which the editor resolves itself). The copies take the next ids of the target, keep their order (sources in the order given, marks in their source's order) and land on top; the op reports each from and to address. A move, turn, scale or flip applies to the copies together, about pivot or the middle of their bounds. cut adds a cut keeping the inside of a polygon to every copy, so only the parts inside are seen. Copies see the batch as it is at that point, like dup.
Retiming. retime takes frames from to to (both included) on every layer, or on the listed layers with their masks and children. The range is cut into pieces where any of those layers changes what it shows, so layers stay in step; each piece is one picture. on n gives every piece n frames; fit n makes the range n frames, each piece starting at its old position scaled (rounded, at least one frame each, order kept; fewer frames than pieces is refused); reverse plays the pieces backwards; pingpong adds them again backwards without repeating the ends (a b c d c b). Every affected layer is rebuilt from what it shows frame by frame: runs of the same drawing merge, a drawing's first run keeps the cel (and its hold style), later runs become links to it. Everything after the range moves by the change in length. On every layer, clips move and stretch with it (an end inside the range is scaled with the range) and the timeline grows or shrinks; on listed layers clips stay and the timeline only grows, as for a frame insert.
In-betweens. inbetween makes drawings between two keys on paint layers: the drawings shown at from and at to (where the second key's exposure starts; a link there names its source, so a loop's last in-betweens lead back to its first drawing). By default a cel goes on every frame between them; with count n they go on frames spread evenly between the keys, each held until the next, and the first key's exposure ends at the first one. Positions follow spacing: even (i/(n+1)), in (squared: bunched near the first key), out (bunched near the second), in-out (smoothstep), or the positions themselves. Cels already between the keys must be in-betweens of the same keys (they are replaced) unless forced. A layer that shows the same drawing at both keys is left alone. The CLI computes the marks, then the op adds the cels and their marks as one history step.
- Pairing: by id (default: a key duplicated from the other keeps its ids), by
order(strokes, lasso fills and flood fills each in order) ornear(greedy on the mean distance between 16 points along each, trying a stroke backwards too).pairforces pairs first. A stroke never pairs with a fill, nor a lasso fill with a flood fill; unpaired marks are left out and listed. - Each stroke pair is resampled by arc length to the longer one's sample count; pressure, tilt and time ride along. The best-fit rotation and scale from the first key's points to the second's (a similarity, least squares) is followed along its arc: about its fixed point, the angle and the log of the scale moving with t, and what the fit leaves is added on top in proportion. So a swinging stroke turns about the point it swings around and keeps its length.
- Strokes ride on the lines they touch: a stroke end that touches another stroke in both keys (within half that stroke's size plus 2 px, plus a quarter of its own) makes the shorter one ride the longer when the longer is at least 1.5 times its length (the longest such): the child moves in its parent's frame, the parent's motion at t, then its own turn relative to the parent along its arc, so a hand bending at the wrist stays on the turning arm. Every other stroke is carried by its neighbourhood: the strokes whose centres lie within 60 px and that move like it (they put its centre within 15% of its own travel, at least 6 px, of where its own fit does; failing three of those, of the median) give one similarity fit over all their samples, and the stroke follows that fit's arc, then its own leftover turn. A stroke with fewer than two such neighbours follows its own arc. So nothing composes deeper than a few links to strokes much longer than it, and dense brushwork that turns with a body (a paint-over carried from key to key) moves with it instead of drifting down chains of touching strokes, each inheriting the fit noise of the one before (B1). The touching end is then moved onto the other line at the interpolated contact (its place along that line and its offset, both interpolated), pulling the nearest third of the stroke (up to 48 px) with it, so closed shapes stay closed. On a closed line, the second key's contact is the one nearest along the line to the first key's, and a contact that jumps more than half the line is not kept.
- Size, opacity, flow, taper and colour interpolate (colour in OKLab, so lightness and hue change evenly; keys of one colour keep it exactly), so light can follow a turning limb when the second key is coloured for it; brush, seed, lock alpha and cuts come from the first key (cuts move with the stroke); in-between marks keep the first key's ids and are marked agent.
- Lasso fills interpolate their polygons the same way, and ride the fills they overlap (B2): fills are taken largest first; a fill at least 90% inside a larger one in both keys is a band and takes its container's motion (with its own turn relative to the container when it is not round and its fit is good, its outline's start in the second key chosen so its turn is closest to the container's); otherwise a fill that touches a larger one in both keys keeps its own arc but is pulled, by at most a tenth of its size, towards where the larger one carries the place they meet. So a band does not spin into a star, a foot does not slide off a shin that unfolds, and an outline whose first point sits at a fixed screen direction turns with its limb. Lone fills move exactly as before.
klad inbetweennotes how many fills ride. Flood fills are recomputed in each in-between: the seed is carried by the lines it sits next to (the nearest point on the nearest paired stroke of the reference, its place along that stroke and its offset across, found in each key, placed on the in-between strokes and blended by t), moved onto the nearest open pixel when it lands on a line, and the fill is computed with its own settings against the in-between's reference. Layers whose fills reference another in-betweened layer go after it,alllast. A fill that lands on a line, covers nothing, or comes out over 1.6 times (plus 64 px) or under 0.4 times what the keys' areas say is left out and listed.
Fills like another drawing. A fill with like carries every flood fill of one drawing to the layer's other drawings on frames (all, a range or a clip): for each target, the reference at the frame where it first shows is cut into regions as the fill would see them (its colour, tolerance and gap); each region near the old fill is compared with the old coverage shifted onto the region's centre (overlap over union, falling off with the distance moved), regions open to the canvas edge only when the old fill touched it; the seed goes to the best region's pixel nearest the shifted old seed and the fill is computed there. A target that already has a fill with that id has it replaced in place, otherwise the fill goes on top with that id (or the next free one). Fills that find no region, cover nothing or come out over 2.5 times (plus 256 px) the old one are listed. One history step for all targets.
Parts, arcs and hand work in in-betweens (M4.5 batch 2). Pairing for in-betweens goes forced pairs first (--pair), then part by part for every part name both keys have (within a part and a kind of mark, in drawing order when the counts match, by nearest shape when they do not), then the match rule for the rest, so keys drawn separately pair whatever their ids. --loop takes the loop's first drawing as the second key (the clip holding --from, else frame 0; --to defaults to the loop's end), so a cycle closes without a temporary link. Marks in one key only follow unpaired: left out (the default, listed), pop at the middle or at t, fade (opacity over the in-betweens), draw-on (drawn along their length; one-key marks of the first key draw off); they are carried with the lines around them (tween::carry: every point anchored along the nearest paired line and placed on that line in the in-between), and flood fills among them are still left out. --redo --keep-drawn splits an in-between's marks by author: it remakes the agent's from the keys and keeps the hand-drawn ones on top, carried from the old in-between's lines to the new ones (aligned by mark id; a hand mark in a part follows the lines of that part), with new ids and their parts; made stays the hash of the agent's marks, so a plain --redo still refuses it. Arcs (cli/src/arcs.rs) track a mark through the drawings that show its id, a part's centre in each drawing of a layer (the first paint layer that has the part, or layer:part), or a point carried by the stroke nearest to it at the first frame; each frame gives a centre, a lowest point (the middle of the samples within 1 px of the lowest y) and the sole (the span of the samples within 2 px of it, the part on the ground). --ground reports the lowest point under the line, and slides: consecutive changed positions both on the line (within --slack) where neither end of the sole nor its lowest point moved by -travel per frame (a cycle drawn in place should move a planted foot back by the travel); the slide is the smallest of those three moves, so a foot rolling from heel to toe, which keeps one end still, or turning a little on its lowest point, is not a slide, and a foot pushed along the ground, which moves all three, is; with two tracks, frames where their left-right order flips are swaps. --overlay arcs draws each track as a line with a dot and a tick across the path per frame, numbered, the current frame ringed; --overlay parts boxes and names each part.
Drawing from shapes. ink, light, hatch, scatter and fill with shape read the outlines of vector shapes (rects, ellipses, paths; a group means each shape in it), flattened every 2 px and taken to canvas coordinates through the node's transforms (klad_render::shapes), and are turned by the CLI into ordinary strokes and fills before the transaction (cli/src/shapes.rs), so they replay like any mark; shapes added earlier in the same batch are seen. Ink resamples each outline, splits it at corners sharper than break degrees (open paths at their ends too), and gives each sample a pressure from three rules multiplied together and smoothed: the outward normal against the light (0.55 facing it to 1 facing away), the silhouette (0.7 where the outline lies inside another closed outline of the call), the curvature (down to 0.65 on tight curves); a seeded two-sine wobble moves points along the normal. A closed outline without corners is one stroke that starts at its lightest point and overlaps its start by 12 px. light makes lasso fills of each closed outline with a cut that keeps the outside of the same outline moved towards the light by depth (in soft steps from 0.6 to 1.4 times the depth, each at a share of the opacity) for the shade, and moved away from the light by rimWidth for the rim. hatch cuts parallel lines (or inward offsets of the outline with along) into pieces of the given lengths, jittered and clipped to the area; scatter places a mark at jittered grid points or count random points inside the area and outside avoid, scaled and turned by seeded amounts. All of it is deterministic (libm, the seeded RNG). Lasso fills skip the CLI's catch-up of earlier marks (only flood fills need to see them), so 160 fills from one light of 40 shapes take about 260 ms.
Stroke addresses. Strokes and fills are addressed as <cel>:s<id>, for example c4:s12; fills share the id counter with strokes. set on a stroke takes color, size, opacity, flow, brush and taper, on a fill color and opacity; colours may be palette names. transform applies translate, then rotate (degrees, clockwise) and scale about pivot, by default the middle of the marks' bounds; stroke samples move at their stored 1/16 px precision, sizes and tapers scale by the square root of the area scale, tilt turns with the stroke, and fills move by whole pixels (their coverage shifts exactly) or are resampled bilinearly when turned or scaled. Marks keep their ids and their place in the order. Ids in several cels need an explicit pivot.
Lasso. A lasso op works on the strokes and fills of one paint cel inside a polygon. A stroke is inside when every sample it keeps (see cuts) is inside the polygon, a fill when every pixel it covers is; marks with some of each cross the edge. Without cut the op moves, turns, scales, flips (negative sx or sy) or removes ("rm":true) the marks inside. With cut, every crossing mark is first split in two: the original gains a cut that keeps the outside of the polygon and stays where it is, and a copy with a new id, placed right after it, gains a cut that keeps the inside and moves with the rest. So nothing outside the lasso changes, and the moved parts stay strokes (recolour them, thin them, move them again). The op is one history step and reports the ids it moved.
Cuts. A stroke or fill may carry cuts: polygons with a side to keep (inside or outside). When the mark is painted, its coverage is multiplied by each cut's coverage of the polygon (4x4 supersampled, even-odd) or one minus it; tiles a cut leaves untouched are skipped. Cuts move, turn and scale with their mark. A split stroke drawn in place shows a faint seam only where the lasso edge crosses its antialiased edge, the same as a raster cut and paste. A cut is not a layer mask: it belongs to the mark and replays with it.
Path points. A path, rect or ellipse reads as subpaths of anchors, each with an in and an out handle (absolute, in the shape's own coordinates; a handle on its anchor means none). Every SVG command parses into this form (quadratics become cubics exactly, arcs become cubics of at most 90 degrees) and is written back as M, L, C and Z with two decimals. A rect or ellipse becomes a path that looks the same on its first point edit. Anchors are numbered across subpaths. Smooth means both handles present and in line; moving one handle of a smooth point turns the other to stay in line unless free. insert splits a segment at t without changing its curve, add finds the nearest segment, rm joins the neighbours, corner drops the handles, smooth sets them along the line between the neighbours at a third of each distance, and simplify refits each run between sharp corners (over about 50 degrees) as least-squares cubics (Schneider) within the tolerance, keeping straight runs straight. Before a path op, the CLI and editor pin transform.pivot on the shape and every group above it whose transform is not identity and has no pivot, so a point edit never moves the rest of the shape.
Layer kinds
| Kind | Content | Mostly made by |
|---|---|---|
paint |
strokes, replayed to f16 tiles | human pen, agent scripted strokes |
vector |
shapes, paths, text, generators | agent |
pixel |
whole pixels bound to palette entries, no anti-aliasing (a paint layer with pixel: true, M9) |
agent and human |
adjust |
one adjustment: hsl, levels, curves, balance, gradient-map, fill (M5) |
either |
group |
children, blend mode, opacity, mask, clipping | either |
Every layer has blend, opacity, visible, locked, optional mask, clip and (M5, format 8) effects. Effects are layer settings, not a layer kind: the planned filter kind became them.
- Pixel layers (M9). A pixel layer is a paint layer flagged
pixel, so it shares cels, masks, clipping, lock alpha, effects, the timeline and every export with paint layers. One pixel is one canvas pixel: a 64x64 sprite is a 64x64 drawing shown enlarged, and a drawing never mixes pixel sizes. Its marks stay data, as strokes do: a pixel mark is a fill record whose source is cells (FillSource::Cells), a set of whole pixels (coverage 0 or 255) with the id of the palette swatch it was drawn with, or a set of pixels to erase. So the same addresses,set,rm,transform, lasso, copy and history work on them; scaling, flipping and turning sample the nearest pixel (markedit::resampledwithhard), which also makes an export above full size hard-edged. Colours are palette entries:Document::bind_swatchfinds or adds the swatch and gives it anidthe first time a mark uses it, andset color=on a pixel mark binds it to the new entry. Thepixelop (klad pixel) is the first way to make marks; brush strokes and flood or lasso fills are refused on a pixel layer (ops::off_the_grid). A drawing with a pixel layer (Document::pixel_art) gets a sharp view on both sides. In the editor the zoom moves in whole screen pixels per pixel above real size (View::whole,View::fit_whole; free below it), a pixel grid shows from 8 screen pixels per pixel (a dark line with light dashes, so it reads on any colour; View > Pixel grid), the pixel under the pointer is outlined on a pixel layer and named in the status line, and the Real size pane (Pane::Preview, opened the first time a pixel drawing is opened) shows the composed frame at 1, 2 or 4 screen pixels per pixel for drawings up to 512 px. In the CLI,klad renderand edit previews enlarge by a whole number to about 512 px (agent::pixel_scale), and--overlay griddraws the same lines with the pixel numbers along the top and left (overlay::draw_cells). The palette is what a pixel drawing is bound to. A mark stores its swatch's id and its colour, so every reader of a stroke file draws it without the palette; when a palette edit changes a swatch's colour,ops::follow_paletteadds aMarkChange::Entryfor every pixel drawing, which rewrites the colour of the marks bound to that swatch in the same transaction (one undo step), and a removed swatch unbinds its marks. A palette rewritten without ids keeps them by name, then by colour (carry_ids). Swatches carry an optionalrampname: a ramp is the swatches sharing it, in palette order, dark to light (palettes::rampmakes one from a base colour withcolor::value_step, darker and cooler to lighter and warmer). Palettes that come with klad are colour lists incore/src/palettes.rs(klad palettes), andpalettes::parsereads a list of hex colours or a GIMP palette. The pencil is grid geometry incore/src/pixel.rs, shared by both hands:line(Bresenham),extend(a run that follows the pen with no holes),perfect(drops the corner pixel of an L, so a hand-drawn line stays one pixel thin),stamp(a size is a square of whole pixels) andof_path(SVG path data flattened and traced; corners the path asks for are kept, the corners that flattening a curve leaves are not). Thepixelop takescellsor apath, and asize. In the editor the brush tool on a pixel layer is the pencil (the eraser command and the pen's eraser end erase): the run is drawn over the canvas as it grows and committed on release as onepixelop marked as made by hand, so the palette binding, history and sync are the op's. Shift click draws a straight line from the last pixel;[and]change the size. An agent reads and writes a pixel layer as text, which is exact where a picture is not.pixel::grid_ofworks out what a drawing's marks show, pixel by pixel (later marks over earlier ones, erasing marks, lock alpha, cuts), as the palette entry or the colour of each pixel;pixel::legendgives each one a character (the first letter of its name where free) andpixel::ruledorpixel::plainprint the rows (klad pixels). The other way,pixel::parse_textreads a legend and rows and the grid form of thepixelop (rows,legend,at) turns each character into one mark bound to its colour (klad pixel --grid), so whatklad pixels --plainprints draws the same picture again. Text grids are the agent's side only: a person draws with the pencil. Shapes and fills are the same op with other sources:line,rectandellipse(the ellipse that fits a box of pixels, by an integer midpoint walk, so even and odd sizes stay symmetric;filledtakes the rows between its outline) are pure geometry incore/src/pixel.rs;fillis a flood over what the drawing shows (pixel::floodon the grid ofgrid_of: pixels joined to the seed with exactly its entry or colour, four neighbours or eight), reading this layer, another pixel layer or all of them merged. A flood needs the marks, which an op cannot read, soBundle::settle_pixelsturns everyfillinto its cells before the ops are applied, walking the batch so a fill sees the marks the ops before it made;Bundle::apply_ascalls it, so the CLI,klad applyand the editor share it. In the editor the fill tool floods on a click and the shape tool drags a rectangle, an ellipse or a line of pixels on a pixel layer, previewed as the pixels it will make. Editing pixel marks reuses the selection and transform of strokes and fills, with three differences that keep the grid. A lasso that cuts would leave a supersampled cut on a mark (a soft edge), somarkedit::splitdivides a pixel mark's coverage between whole pixels instead, by pixel middles, and the two halves carry no cut. A transform whose matrix is whole numbers (flips, quarter turns, whole scales) is rounded onto the grid intransform_fill(on_the_grid: matrix and offset rounded), so every pixel lands on a pixel whatever the pivot and marks transformed together still fit; other transforms sample the nearest pixel. Recolouring pixel marks gives each exactly the target colour and its palette entry, where paint marks keep their shades. In the editor the stroke tool on a pixel layer drags a box (or a loop) that snaps out to whole pixels and takes pixels, its box is the selected area, drags move by whole pixels, scale by whole numbers and turn by quarters (Drag.whole), and Select same colour takes every mark of the selected marks' palette entries. Shading builds on ramps.shade(a number of ramp steps) is a way to colour, not a source: for the pixels of any source,Bundle::settledreads what the layer shows and makes one mark per target colour, each pixel taking the swatchDocument::ramp_stepgives for its own (pixels in no ramp, or at its end, are left).ditherkeeps the pixels a 4x4 Bayer pattern fixed to the canvas turns on for that share (pixel::dithered), andsecondgives the rest another colour, as a second mark.outlineis a source: the empty pixels that touch a drawn one (or,inside, the drawn ones that touch an empty one) on the grid of this layer, another or all (pixel::outline). All three need the drawing, so they are settled in the bundle withfill, andsettle_pixelsmay return more ops than it was given. Mark by mark,klad recolour --stepand the selection bar's Lighter and Darker move a mark to the next swatch of its ramp, andklad recolour --fromrebinds every mark of one colour. A colour's character in the text view is fixed by its place in the palette, not by which colours are in use. Two things multiply what is drawn. A mirror (mirrorX,mirrorYon thepixelop; the editor's mirror line) adds each pixel's twin across a line that stands between two pixels or through a column (pixel::mirrored); it is part of the op, so the mark holds both halves. Wrap is a property of the canvas (canvas.wrap, set by thecanvasop): the drawing is a tile, soPixelSpec::coveragebrings pixels past an edge back in on the other side (pixel::wrapped) instead of dropping them, and floods and outlines take their neighbours round the edges. It changes what is drawn, never how the drawing renders; to see the repeat, the editor draws the canvas quad three times across and down with the copies dimmed (the shader repeats the texture when the view's uniform says so) andklad render --repeat Ntiles the finished picture. Transforms of marks do not wrap. Animation on pixel layers is the timeline as it is: drawings on frames, holds, links, clips and onion skins need nothing new, since a pixel layer is a paint layer. Two things differ. A keyed layer or group that holds only pixel layers (Layer::grid_only) is drawn at its key's position rounded to whole pixels and sampled nearest (render::draw_content), so a keyed move never softens a sprite. And the ops that move points refuse pixel layers with the reason and what to do instead (ops::grid_refusal, checked inops::applyand before the CLI resolves anything):inbetween,pose,weightsand attaching to bones. Exports of a pixel drawing take whole-number scales only (export::check_scale: 1 toPIXEL_MAX_SCALE64, no side past 16384 px, checked before anything is drawn): the frame is drawn at its real size and enlarged with nearest sampling (export::render, the sameresamplethe preview uses), so the detail of the rasters stays 1 (export::detail_of) and every export path (a frame, sheets, numbered frames, GIF, Godot) is sharp by the same code. Fractional scales are refused, not rounded, because a rounded scale would silently change the size asked for. The Godot scenes of a pixel drawing settexture_filter = 1(nearest) on the sprite, or on the root of a parallax scene, so nothing depends on the project's default filter.render/src/gif.rswrites animated GIFs (klad export --gif, the export window's GIF choice) with no new dependency: one global table of up to 255 colours plus a clear index, exact when the frames hold 255 colours or fewer (always, for palette art), median cut otherwise, each pixel then taking the nearest entry, or with--dither(the export window's dither box) the nearest entry of the colour moved by an 8x8 ordered pattern, offset per channel, as far as the table's entries lie apart on average (gif::Pattern,spacing); ordered and not error diffusion, so the pattern holds still from frame to frame; it is an option and off by default because flat art is cleaner without it, and it does nothing when nothing was reduced; LZW with a table reset at 4096 codes; each run of equal pictures is one frame whose delay is its duration in hundredths with the rounding error carried to the next, so the total stays right; frames replace each other (disposal 2) since they are whole pictures with clear pixels. A test reads the result back with Skia's decoder. Palette variants (doc.variants, S9.12) are named sets of colour overrides by swatch id. The drawing always is in one variant: the palette and the marks hold the shown variant's colours,variants.basekeeps the base colours that variant overrides, and showing another one is an ordinary palette edit (PaletteEdit::Variant, throughfollow_palette), so the editor, the previews, undo and every reader of the file need nothing new and a variant can never be seen half applied. A view-only variant was the alternative; it would have needed a second set of rasters in the editor's compositor and would have left the question of which variant an edit belongs to. Here the rule is simple: a colour changed while a variant is shown is that variant's (ops::keep_variantrecords it, and drops it again when it is set back to the base colour); a variant follows the base wherever it has no colour of its own. Exports of a variant that is not shown do not touch the drawing:Document::dress(name)gives the colours that differ from what is shown, andlayers::dressedreplays the pixel drawings that use them with those colours (klad export --variant,--variants; file names take the variant after the drawing's name). Both paths rest onDocument::variant_colours. Aseprite files (S9.13):render/src/aseprite.rsreads and writes the published binary format into a plainSprite(layers with their nesting level, cels with a picture or a link, per-frame durations, tags, palette); reading turns indexed and grey pixels into RGBA (the transparent index is clear except on a background layer) and lists what it drops, writing is always RGBA with zlib cels. It was checked against files made by Aseprite itself (its public test sprites, not in the repository) and, for the writer, against an independent dump of the chunks.cli/src/aseprite.rsmaps a sprite to a drawing and back. In: oneadd layerop per top-level layer with its children and cels (explicit cel ids, so linked cels become klad links and a cel followed by an empty frame gets ahold), then one pixel op per colour per cel, bound to the palette entry with that colour (file palette first, other colours added, at most 1024), tags as clips; frame times become whole frames at the lowest fps from 1 to 120 with the least error (timing), said when it is not exact. Out: pixel layers and groups only (others are named in a note), one file frame per stretch of timeline in which no layer starts or ends a drawing and no clip starts or ends, so holds do not multiply frames and a file that came in goes out with the frames it had; a drawing shown again is a linked cel; a pixel layer's own keyed x, y and opacity go into the cel's position and opacity (every frame is then its own).klad importmakes the drawing,klad export --asepritethe file; the editor opens an Aseprite file by runningklad import(start::brought_in, used byHome::open, so the start window, a path given at launch and the system's open all work) and has an Aseprite choice in the export window. Indexed output and tag directions are not kept on the way out. Pictures to pixels (S9.14):render/src/pixelise.rsdecodes a picture with Skia, shrinks it by area average on premultiplied colour (shrunk; exact for whole-number reductions of enlarged pixel art), picks colours (colours: the picture's own, most used first, when few enough, else the GIF encoder's median cut, dark to light) and maps every pixel at least half solid to the nearest colour in Oklab (mapped).cli/src/pixelise.rsturns that into ordinary pixel ops, one mark per colour, so nothing new is stored: a picture file onto a pixel layer in the drawing's palette (klad pixelize --image --to), a picture as a new pixel drawing (klad import x.png), and a painted or vector layer, or the whole picture, as a new pixel drawing with every frame rendered through the export path, shrunk, and held when it equals the frame before (klad pixelize --size). The palette rule is the same everywhere:--colors Nmakes colours from the picture, else an existing palette of two or more solid colours is used as it is, else the picture's own colours (32 when it has more than 256, 16 for a painting). No dithering and no outline repair: the result is a start to clean up. The editor has one window for it (File > Pixels of a picture…,editor/pixels.rs) that runs the same command. Tilesets (S9.15):canvas.tileis the size of the tiles a drawing is cut into, and nothing else is stored: a tile is a region of the one canvas (Canvas::tile_at(column, row)), so every tool, layer, frame and palette works on a tileset as on any drawing, and the cut can be changed or taken away without touching a mark. The canvas has to be a whole number of tiles each way (Canvas::cut, checked by the op and when a drawing is opened), which keeps tile addresses and the export exact. The CLI reads and draws one tile at a time (klad pixels --tile,klad pixel --grid --tile), the editor draws the tile lines over the canvas at any zoom and sets the size in View > Tileset: cut into tiles…, andklad export --tileset(the export window's tile set button) renders the frame and writes a GodotTileSetwith oneTileSetAtlasSourceand a tile for every cell with anything in it (sprites::tile_set), into the drawing's Godot folder with a kept uid; a test loads it in Godot. Not there: animated tiles, per-tile wrapping, collision or terrain data, margins between tiles. Pixel checks (S9.16):core/src/pixelcheck.rsreads what a pixel layer shows (theGridof palette keys, wrapping where the canvas does) and returns findings, each a kind, a place and a note: a pixel with none of its colour among its eight neighbours; a pixel with exactly two neighbours of its colour beside it at right angles, nothing of its colour in the corner between them and an arm of one pixel, in a thin line that goes on, whose two neighbours are not such corners themselves (a doubled corner, as against a box corner, a staircase that is a two-pixel diagonal, the stepped edge of a shape or a three-pixel cluster; the sprout sample's legs and highlight showed the need for those exceptions); in chains of thin pixels, a straight run at least two shorter than the runs before and after it when the line keeps going the same way and stepping to the same side (a jag, as against the flat top of an arc or a notch); a one-pixel band whose lightness lies between the colours on its two sides for four pixels or more (banding, as against an outline or a line through one colour); and colours that are not palette entries. They are heuristics with those stated limits, and the wording says look, not error.klad checkprints them by layer and drawing; the editor's Check the pixels (Cmd::CheckPixels) runs the same function in the editor, marks the places on the canvas and recomputes when the drawing, the frame or the layer changes, until it is turned off. - Blend modes.
normal,multiply,screen,overlay,add, and since M5color-dodge,soft-light,hard-light,lighten,darken,color,luminosity, all as in the W3C compositing spec (Skia's modes;look::blend_rgbandlook::compositehold the formulas the tests check them against). - Effects (M5).
"effects": [{"glow": {...}}, {"outline": {...}}], applied in order to the layer's content (after its mask; for a clip base, to the base and its clipped layers together) before its opacity and blend:blur(radius, a Gaussian sigma),glow(radius, strength, threshold: 0 glows from every pixel, higher only from the bright ones; color: a tint; blend: how the glow mixes with what is under the layer, screen by default, normal lays it like paint under the layer),outline(width, color, inside),shadow(x, y, radius, color, laid under the layer),noise(amount, size, seed, mono: a grain fixed to the canvas),displace(amount, size, seed, by: smooth waves, or a layer whose red pushes across and green down),relief(strength, light, highlight, shade, softness: lights the paint height of the layer's drawings, below). Each effect knows its reach (look::reach), so a tile is composed from its content within the tile plus that margin and tiles meet without seams (noise and haze read only their own pixel and add no margin, so they cost no neighbouring tiles); a tile skips a clip stack or group that puts no pixel in it (none of its rasters, live tiles or onion ghosts has a tile in the tile grown by its effects' margin; layers moved by keys, adjustment layers and vector layers drawn from their nodes always count), which leaves the tile the same since every blend leaves the pixels under a transparent layer as they are; the pixels are computed in Rust (klad-render/effects.rs) on f32 with absolute coordinates, so a tile equals the same pixels of the whole image byte for byte (tested). Blurs use a direct kernel, below a sigma of 2 at full size and above it on a grid of 2, 4, ... px blocks anchored to the canvas, then sampled back. - Adjustment layers (M5). An
adjustlayer changes what is under it in its list: the layers below it in its group, or, clipped, its base. A group holding an adjustment is composed apart, so the adjustment stays inside it. The colour math is on unpremultiplied sRGB values with alpha kept:hsl(hue in degrees, saturation and lightness -1..1),levels(black, white, gamma, low, high),curves(points, and red, green, blue applied before them; monotone cubic, no overshoot),balance(shadows, midtones, highlights: cyan to red, magenta to green, yellow to blue, keepLight),gradient-map(stops by brightness). The layer's opacity, blend and mask decide how much of the adjusted colour replaces the colour under it.fill(a solid or gradient paint) is drawn like a content layer instead, with the layer's blend. - Rays (M5). A vector node
{"type": "rays", "x", "y", "angle", "spread", "count", "length", "start", "falloff", "noise", "seed"}draws soft beams from an origin (a gapstartpx wide), each a quad with a radial falloff and its own length and strength from the seed; the node'sfillcolours them and itsblursoftens them. Rays come from the agent (klad add rays); in the editor a selected rays node shows its settings in layer settings. - Depth and atmosphere (M5). A layer at the top of the stack (a plane, usually a group) may have a
depth(0 is near; validation refuses it deeper in the tree). The document'satmosphere(color, an optionaltopcolour blended down over the canvas height,density,blur,desaturate) turns each plane's depth into two effects after its own (Document::effects_of): ahazetowards the fog of1 - e^(-density x depth)withdesaturate x depthof its colour taken out, and a blur ofblur x depthpx.hazeis an ordinary effect too. The depths are kept for M6's Parallax2D export; in the editor a depth field sits in each plane's row and layer settings, layer settings hold the atmosphere, and holding D shows the planes (each flattened alone, in the background) sliding byoffset x 0.08 / (1 + depth)with the pointer. - References (M5). Any layer can be
reference: true: the editor shows it, renders, hashes and exports leave it out unless asked (--references), and fills never see it. - Pictures (M5). A picture is a vector node
{"type": "image", "src", "x", "y", "w", "h"}, so V moves and scales it and layer settings fade it. Importing (klad add layer image src=photo.jpg, dropping a PNG or JPEG on the editor, or "import a picture") decodes PNG withpngor JPEG withzune-jpeg, re-encodes it as PNG and stores it asimages/<content hash>.png, so the same file twice is stored once and every machine draws the same pixels; it lands on a new vector layer, fitted inside the canvas. The renderer finds pictures and fonts in the folders of every bundle the process opened (klad_render::assets). - Generators (M5).
scatter(copies of its children over a region,count,seed,sizeandturnranges,avoid: SVG paths no copy's centre may fall in),repeat(countcopies, eachstepfurther, turningturndegrees and growingscaleaboutpivot, or a gridcolumnswide withrowbetween rows) andmirror(its children and their reflection across a line throughx, yatangle) are nodes whose children are drawn once per instance (generators.rs); they stay settings, layer settings edit them, and "repeat it", "scatter it", "mirror it" put a selected shape inside one; "take the shapes out" removes one and keeps its shapes where its first copy was. Their children keep their ids, so V can still pick inside. - Text (M5).
{"type": "text", "text", "font", "x", "y", "size", "tracking", "leading", "align", "weight"}with the node's fill and outline. The font is a file in the bundle'sfonts/folder, so a drawing renders the same anywhere. Each line is shaped byharfrust(HarfBuzz's shaping in Rust: GPOS andkernkerning, ligatures, marks, scripts),weightsets a variable font'swghtaxis, and the outlines come from the file throughskrifa, each glyph's contours merged with Skia's path ops so an outline never shows the overlaps variable fonts are built with; they are drawn as one path, never by the system's font engine, so the Mac and the container draw the same pixels. A missing font is refused with its name. - Fonts (M5, S5.26). klad ships about fifty open families for game art in
fonts/(sans, serif, mono, display, handwriting, pixel; OFL-1.1 or Apache-2.0, unchanged from the Google Fonts repository at a pinned commit, listed with their licences in the notices;fonts/update.pyfetches them again).klad_render::fontsfinds that folder next to the binary (also../Resources/fontsin a Mac app and the repository'sfonts/for development builds;KLAD_FONTSoverrides), and keeps families downloaded on request in a per-user folder (~/Library/Application Support/klad/fonts,$XDG_DATA_HOME/klad/fonts,%APPDATA%\klad\fonts).fonts/catalogue.jsonlists every open family on Google Fonts (about 1,900) with its group and folder at the same commit, soklad fonts --searchworks offline and a download (klad fonts --get, or naming a family anywhere a font is taken) fetches exactly that commit's files withcurl. Choosing a font anywhere (the CLI'sfont=,klad font, the editor's picker) copies the file and its licence into the bundle; the node keeps the file name. This replaces M5 choice 3 (no fonts with the app). The editor's frame and plane caches foldklad_render::RENDER_VERSIONinto their keys, so pictures cached before a renderer change are not shown again. A light layer is no kind of its own: a paint layer set toaddwith a soft glow (a shortcut button for it only confused the layers pane). - Foliage (M5, S5.27).
foliageis a shape op (CLI only, principle 7): each closed shape becomes a clump built from leaf strokes on a jittered grid, each coloured from the clump lit as a round form (a normal from its bounding ellipse, mixed with the normal of an optionalmassshape so clumps turn with the whole crown, a key light or a lamp, the underside darker) and stepped into three value families betweenshade,colorandlit(OKLab; by default darker and cooler, lighter and warmer), with more variety in the light; then leaves along the outline, kept more where the outline faces the light or the sky, a few inglowon the shadow edge. Strokes are sorted dark to light so lit leaves land on top. It puts how foliage is painted (light families on the clump, the big mass before the texture, a broken silhouette) into one op, so an agent does not scatter leaves like confetti. - No agent inside the editor (M8). A first version ran a model in an Agent pane with the user's Claude API key; it was removed on 2026-11-06 in favour of an MCP server that any agent client can use (planned). Agents work on a drawing through the
kladCLI, and the person reaches them through notes, the selection and the shared history. - Rigs (M6). A paint layer or a group gets
bones(format 9): each a name, an optional parent that comes before it, a head and a tail in canvas px. A group's skeleton poses every paint layer in it together, so a character's lines, colour and shading layers stay in step. Each bone has a weight map inweights/<owner>.weights(zstd: a JSON header with the grid size and bone names, then one byte per cell per bone, cells of 4 px), written byBundle::applywith the edit and kept in its history step; weights are normalised across bones when read (bilinear between cells), and a place no bone weighs follows the nearest bone. Automatic weights are 1/(d + 0.15 L + 1)^3 by distance to each bone segment (L its length), so joints blend over a short stretch;setpaints soft dabs (smoothstep falloff towards a value),partgives a named part's cells to one bone at 1 and the others 0,smoothblurs every map once. A pose (poseon a cel: its rest drawing's id, an angle per bone in degrees from rest, a root move) is linear blend skinning: each bone's rest matrix (head, angle) and posed matrix (its parent's posed matrix times the rest offset times its turn) give a skin matrix, and every stroke sample moves by the weighted sum; stroke sizes scale by the mean local stretch (the Jacobian's determinant, square-rooted); polygon fills move their points; flood fills are warped through a 4 px triangle mesh over their coverage (each posed triangle rasterised, sampling the rest coverage by barycentric position). The rest pose returns the marks untouched.pose(computed by the CLI,cli/src/rig.rs) makes or re-poses a drawing attoon every paint layer under the skeleton from the rest drawing shown atfrom(a posed drawing's own rest whenfromshows one). In-betweens of two poses of one rest drawing (or a pose and its rest) mix the angles and root by t instead of matching strokes (rig::posed_pair), and keep the mixed pose. A bonemovewith atailtakes along the heads of the children that start at the old tail (within half a pixel), andbymoves a bone with all its children (rig::moved, which the editor also draws while dragging). The editor's bone tool (J) has three modes (draw, weights, pose) and in every mode a skeleton list in its options (each bone under its parent; picking one highlights it on the canvas); with no skeleton on the active layer the options name the layers and groups that have one, each a button that makes it active. Picking on the canvas is a click in draw and pose mode and cmd click (ctrl outside macOS) in weights mode. In draw mode a drag on empty canvas draws a root bone and starts a chain (S6.9, as Spine's create tool makes the new bone the next one's parent, but welded: Spine has no snapping and its users have asked for it): the next bone runs from the last tail to the pointer and each release (a click or a drag) adds it, its head exactly on that tail, sorig::movedand the joint grips treat it as a joint; shift as you let go keeps the joint and parent for the next bone (a fan); Esc, Enter, a right click, a click on the open end, or a change of mode, tool or skeleton owner ends it; a chain only commits on a release whose press reached the canvas, and each bone is its own undo step, so after cmd Z the chain (checked every frame against the bones) carries on from the last bone still there. With no chain, a press on a bone picks it and drags what is under the pointer (the picked bone shows handles at both ends): an end moves that end, the middle moves the bone and its children, and the head of a child that starts at its parent's tail is that joint, so dragging it moves the parent's tail; alt drag from a tail starts a chain from it (from a bone's middle, a child starting there); the options rename, reparent (a parent menu without the bone's own children), add or change the picked bone's IK, and remove. Draw and weights modes show the skeleton at rest. Weights are painted in the editor's own process (klad_core::rig::weights_for) over a tint of the picked bone's map, and pose mode turns bones, committing the pose (angles, root and targets) throughklad poseas a job; it loads the pose of the frame shown again whenever the frame, the owner or that pose changes; the drawing is not deformed live while posing, only the skeleton. - IK (M6, S6.10). Taken from Spine (constraints on one or two bones, a bend side, softness, a mix, solved parent first, posing a limb by its end) with two changes: a target is a point kept in each pose (
pose.ik), not a bone, because klad bones carry weight maps and go to Godot asBone2Ds, and constraints are ordered by the skeleton itself (the limb's top bone, then its bone), so there is no order to keep by hand. Constraints (layer.ik: bone, chain 1 or 2, bend, softness) live on the skeleton; a pose without a target for one leaves that limb to its angles, so adding a constraint changes no pose, and removing one (or a bone it holds) first writes its solved turns into the angles of every pose that used it (ops::bake, in frame order, each turn within half a turn of the pose before, so in-betweens made later go the short way), so those poses keep their look; where another IK in the same pose shares a bone with it, that one's target becomes turns too, since no stored turn survives a second solve. A bone edit that breaks a limb (a reparent that leaves it without a parent, a move that puts its head on its parent's head) drops the IK as Spine does and writes its turns, but the limb changed, so those poses need posing again, and the note says so;ik --setalso lists the poses that now solve differently from how their drawings were bent.rig::appliedsolves (f64, libm): FK frames from the angles and root, then per constraint an aim (atan2 to the target) or a limb by two circles meeting (the upper segment runs from the parent's head to the bone's head, so a child that starts off its parent's tail is exact), with Spine-like softness as a quadratic ease into full reach (r = d - (d - L + s)^2 / 4s between L - s and L + s, smooth at both ends, straight at L + s), and the mix along the short way round from the angle.skinning,tipsandRig::newtake the constraints, so every place a pose bends a drawing or draws a skeleton (the CLI's poses, in-betweens, the bones overlay, the Godot export's rotation tracks, the editor) uses the solved turns. In-betweens mix the targets, not the solved angles: a 100 + 100 px leg whose hip moves 120 px over a planted foot keeps the foot exactly with mixed targets and pushes it 9.7 px through the floor with mixed angles (rig::tests). A constraint in one key only is handed over as turns: that key's limb takes its solved turns, each within half a turn of the other key's, and the in-betweens turn it (fading the IK out instead flipped elbows when the solve and the angles stored under it were over half a turn apart). Pose values that are not finite, and mixes outside 0 to 1, are refused byDocument::validate, since JSON would store them as null. Joint limits, stretch and chains of three or more bones (Spine refuses them: the result would depend on earlier frames) are not built. The editor's pose mode: a press near an IK limb's end or its target drags the target (making one where the solve gives back the limb as shown,rig::target_for_end, which inverts the softness ease, so nothing jumps, when the pose had none; a limb posed against its IK's bend side turns over, and a message says so); near a root bone's head moves the root, the targets staying where they are; on a bone an IK holds moves its target with the pointer; anywhere else it turns the bone, and alt turns a bone by hand after writing its limb's solved turns into the angles (IK off). The options show an IK switch and a mix for the picked bone's limb. The pose being built stays across mode switches; it is loaded again when the frame, the owner or the frame's stored pose changes, never mid-drag, and after "make this pose a drawing" what was posed since is kept. Chains end with Return or Esc only when no field, palette, settings window or key capture has the keyboard (keys_busy, read at the top of the frame; the pen's Return and Esc follow it too). The options bar stays one row: the picked bone's hints live in tooltips. - Layer transforms (2026-11-08). The request: "a better way to select and transform a full layer instead of individual brush strokes only"; the choices made: the marks themselves move (not a transform kept on the layer), every drawing by default, started with cmd T. The
transformop withlayer(ops::ShiftSpec) moves, turns, scales or stretches a layer or group as one: the marks of every drawing on it and on the layers in it (only: just the drawings shown at one frame), its shapes (composed onto each top-level node's transform, so shapes scale evenly only, and keyed shapes may only be moved, their x and y keys shifted with them), and with every drawing also its bones, the weight maps (resampled through the inverse transform, nearest cell) and its poses' roots (turned and scaled) and IK targets, so a rigged character moves as one. Mark ids, shape transforms and moved weights need the stroke files and shape bounds, soklad_render::shiftworks them out (targets, read once, thenshiftedper transform) for the CLI and the editor, and core applies them. In the editor cmd T (Edit > Transform > Transform layer) puts the selection handles round the active layer's content at the frame shown (the V tool's handles: drag inside moves, corners scale, edges stretch, outside turns); each drag previews the frame on screen through the drag preview and commits for every drawing (an "every drawing" switch in the options), and Esc, Return, a click outside or another tool ends it. - Keys (M6, S6.5). Layers, groups and vector nodes keep
keys: per property (x,y,rotate,sx,sy,opacity) a sorted list of frame, value and ease (linear, in, out, in-out, step, or a cubic curve x1,y1,x2,y2 solved by bisection). A segment follows its first key's ease; values hold before the first key and after the last. Layers and groups composite with their keyed opacity and, when moved, with their keyed transform about the canvas centre (drawn whole, not tile by tile, while moved); nodes take keyed transforms and opacity when rasterised (nodes_at). The editor's frame and plane caches hash the keyed values; its vector raster cache does not follow node keys yet, so keyed shapes move inklad renderand the exports, not in the editor. - Godot scenes (M6, S6.6, S6.7).
export --godot-sceneflattens each visible top-level layer (with its fog; the background with the first) into a texture on aParallax2Dwithscroll_scale1/(1 + depth), the factor the editor's depth preview (hold D) uses.export --godot-rigwrites per skeleton: each part of the rest drawing (named parts of each paint layer's rest drawing, the loose marks as one) replayed alone, trimmed, on aPolygon2Dwith a 16 px triangle mesh over its pixels (one cell of margin), UVs, and per-vertex weights sampled from the maps; aSkeleton2Dwith aBone2Dper bone at rest (local position and angle against the parent,rest,length); and anAnimationPlayerwith one animation per clip (or one for the timeline) whose value tracks hold each bone's rest angle plus its pose at the frame each posed drawing starts (stepped, so drawings hold as in klad); frames that are not poses of the rest drawing are listed for the frames export. Re-exports keep their uids.samples/rigbuilds a figure with all of it. - Paint over (M5, S5.29).
paintover(cli/src/paintover.rs, resolved before the shape ops, alone in its batch) flattens the source (thefromlayers, or every visible layer below the target's top-level layer with the background) into OKLab, then follows Hertzmann's painterly method: for each brush size, biggest first, the source is blurred to that size, a grid at half the size finds cells whose mean difference from the painting so far (an estimate made by stamping discs of each stroke's colour) exceedsthreshold, and a stroke starts at each such cell's worst pixel in a seeded random order. A stroke walks in steps of half its size across the luminance gradient (Sobel), turning towards it bycurvetimes how sure the gradient is (weak gradients keep the stroke's direction; with none, a smooth seeded field of mostly level angles), and stops past its minimum length when the source there is closer to the painting than to the stroke's colour, at a colour change over twice the threshold, at the edge of the region or at its maximum length.focuskeeps the last size to a shape grown by three of those sizes. Each stroke becomes a stroke op with a press-in and lift-off pressure, its size a little varied, its colour broken byvaryfrom a hash of its seed, in the partpart.like <cel>carries a paint-over to another drawing: every source paint layer's two drawings are paired as in-betweens pair them; each stroke rides the topmost source mark under its centre (a stroke within half its size, a polygon fill, a flood fill's coverage) withtween::carryalong that mark's line (still marks: it stays; marks gone: it fades to opacity 0); it keeps its seed and is recoloured from the new source at its start, faded when it would now cross an edge; new strokes, in<part> added at <frame>(one part per drawing, so in-betweens never pair one drawing's added strokes with another's: marks in parts with different names never pair by id, order or nearness, only a forced pair joins them), only go where the source changed (its colour or alpha, grown by the biggest size) or where carried strokes left a gap.--frames a-brepeats that drawing to drawing, making a drawing on the target wherever a source layer starts one (a link where they link).samples/paintoverpaints over the lemons and carries a paint-over through the creature's walk; frame to frame its background changes by 0.03 of 255 on average. - Compare (M5, S5.30).
compare(cli/src/compare.rs) renders the drawing at the reference's width (or reads a PNG or JPEG), resamples it to the reference's size, composites both over white and compares in OKLab: L at the 5th, 50th and 95th percentile, mean chroma, texture as the mean absolute Laplacian of L, sharpness as the 99th percentile of the gradient, and the mean difference, each x100; per--regionthe mean colours and their difference; words when a difference passes a threshold (2 L, 1.5 in a or b, 10% chroma, 20% texture, 15% sharpness);--heatwrites the per-pixel difference as black to red to yellow to white at 20. The editor's "compare with the reference" runs it as a job against the first picture on a reference layer and shows the numbers and the heat in a window. - Grass (M5, S5.28).
grassis a shape op too: rows of blades from the far (top) edge of the shapes to the near one, scaled fromfarto 1 by depth, leaning bywindwith a bend, each from a dark root (color) to a lit tip (second, thebladebrush blends to it by pressure as the blade thins) over ground that rolls in a value noise foreshortened with depth, lit by the light or lamp in soft value families; taller blades root just inside the top edge and break it; lit blades get a thin glint on their lit side; strokes are sorted far to near. Each root picks a species (kinds, by default fine, broad, dry, seed heads and clover) weighted by its share and by a noise of its own, so species grow in patches; heads and low plants thin out with distance. Per blade the hue, chroma and taper vary. A picture brush gets one stamp per blade; a species with aheadgets a picture stamped at its tip;lowspecies are stamped near the root and drawn before the blades around them. Both ops take any brush: they place and light marks, the brush (often the agent's own pictures) gives them their look. - Picture brushes start facing the stroke (engine version 6). A brush whose angle follows the stroke places its first dab before it knows the stroke's direction, so that dab points right. For a picture tip that made one-dab marks (a leaf, a tuft) never turn; such a brush now holds its first dab until the second point gives the direction (a tap is drawn when the stroke ends,
StrokePainter::end, called by the replay and by the editor at pen up), the same live and in replay. Round, chalk and bristle tips keep the old first dab, so M1 drawings and every painted sample render as before; only strokes with picture tips and a following angle (leaves) change.
Strokes
Recording
Pen samples are quantised the moment they arrive, and the brush draws from the quantised values, so a replay matches what was drawn exactly. Before quantising, the editor passes each sample through:
- The pen's calibration curve: lightest and heaviest raw pressure and a gamma, kept per pen device in the user's settings (
~/Library/Application Support/klad/settings.json,$KLAD_SETTINGSoverrides). A touching pen never records below one pressure step, so 0 keeps meaning "no reading". - The brush's pressure smoothing: an exponential average with a time constant in ms.
- The brush's stabiliser: the position is the average of the raw positions of the last N ms. At pen up the window drains, so the line catches up to where the pen lifted.
Stored pressure is therefore device independent and replays need none of these settings. Mouse and trackpad samples that carry no pressure (a tap-drag) record 1; a stroke whose pressure is 0 on every sample draws as if pressure were 1.
| Channel | Stored as |
|---|---|
| x, y | 1/16 px, zigzag varint delta |
| pressure | 12 bit, zigzag varint delta |
| tilt x, y | 8 bit each (-1..1), delta |
| time | ms since previous sample, varint |
A stroke file starts with KLST and its version (1). A stroke header holds the stroke id, brush id, colour, base size, opacity, flow, seed, author, the channel mask and, when set, the taper (in and out lengths in px), the lock alpha bit in the channel mask and, when the mark has cuts, the cuts, and the second colour. Fills carry lock and cuts in the high bits of their source byte. Samples are stored per channel (all x deltas, then all y deltas, ...) so zstd compresses them well. One file per cel. Every record starts with a kind byte, stroke or fill, and strokes and fills share one id counter per cel. docs/format.md has the bytes.
Size budget
Estimate before M0: about 0.5 KB per stroke, so 10,000 strokes is about 5 MB. A fully painted 4096x4096 f16 layer is 128 MB uncompressed. Strokes are the small part; pixels live in the gitignored cache. M0 measures the real numbers.
Fills
A fill is a record in a paint cel, in order with the strokes: id, colour, opacity, author, how it was made, and the coverage it produced (a crop box and 8-bit alpha, run-length coded, then zstd with the rest of the file). Replay paints the stored coverage like a stroke buffer at full flow, so a fill never depends on other layers or on the fill code: CLI and editor, macOS and Linux get the same pixels.
- Flood fill (
at): pixels count as inside when every premultiplied channel is withintolerance(0 to 1, default 0.1) of the seed pixel in the reference:thislayer as it was just before the fill (its earlier marks), a named layer (paint, vector or group, drawn alone at full opacity, even when hidden) orall(everything visible over the background). Four-connected. - Gap closing (
gap, px): the lines are grown by(gap + 1) / 2, so openings up togappx wide close and the open space splits into free regions; the fill takes the seed's region (a click near a line starts from the nearest free region). The pixels the growth took from the open space go to whichever region reaches them first along paths that stay off the lines (chamfer distance, ties to this fill), so the fill reaches into corners and sharp points, two fills that meet in a gap meet on a line across it, and a fill never escapes through a gap it closed. Islands of free space with no pixel 2 px clear of the grown lines do not count as regions. Where a fill that grows under the lines (expandabove 0) ends in open space (across a gap, or at its tolerance), the pixels just outside it get a feathered edge from the fill's 3x3 neighbourhood (at most half cover), so a diagonal edge across a gap is smooth instead of a staircase and two fills meeting in a gap blend into each other with no seam; edges under the lines stay as they were. - Expand (
expand, px, default 2): the result grows that far into line pixels only, under the line's anti-aliased edge, so no paper shows between line and colour. - Lasso fill (
polygon): the polygon's area with 4x4 supersampled edges, nonzero winding. - Gaps:
klad gapscuts a fill layer's reference into closed regions (as a flood fill with the layer's gap would, one pixel further from the lines) and lists those no fill of the layer covers: pockets a fill missed, or drawings not coloured yet. Regions open to the canvas edge are the outside and do not count; smaller than--minpx (12) are ignored. The reference, gap and tolerance default to the layer's flood fills on those frames. - Refill:
klad refillrecomputes the coverage of every flood fill in a cel (or one,--id) from its stored seed and settings against the current reference, keeping its place in the order. - Speed (container): a 2048x2048 flood fill takes about 30 ms, 55 to 65 ms with gap closing; a whole
klad fillon a 2048 canvas, loading the reference from cached tiles, 80 to 110 ms. Fills are deterministic on any thread count.
Replay and checkpoints
A layer cel's pixels are its strokes and fills replayed in order. Each replay records every mark's footprint (the tiles it touched) and its key (id and a hash of its encoded record), and keeps a checkpoint every 128 marks: the tiles as they were at that point, shared with the previous checkpoint where they did not change. Checkpoints are capped at 128 MB per cel by thinning out every other one.
A stroke lands on its tiles only inside the rectangle its dabs wrote in each tile, and only that rectangle is cleared after it, so a small mark on a large tile costs its own area. Where no mark on a cel reads pixels (no wet, smudge or blender), the CLI replays a cel tile by tile on every core (CelReplay::replay_tiled): each mark goes to the tiles its samples' bounds reach (padded by the brush's largest dab and its scatter), each tile replays its marks in order with the others masked out, and the tiles are put together. Every mark's real footprint is then checked against the guess; if any mark reached a tile it was not sent to, the cel replays in order instead, so the pixels are always a full replay's. The tiled replay keeps no checkpoints beyond the first; the editor replays in order, since it edits cels and wants them. A 960x480 still of 41,731 strokes (about 2 million dabs) takes 0.85 s instead of 4.8 s in the container (klad bench, the still line).
When the marks change (an edit, a removal, an undo, an insert), the old and new lists are matched by key. Marks that kept their key and their order stay; the others are removed or changed. Replay starts from the last checkpoint before the first difference and only redraws the dirty tiles: those the removed and changed marks touched, plus the tiles a changed mark touches on its way. A tile a changed mark reaches that a later unchanged mark also touches is first restored from the checkpoint and caught up; a tile no later mark touches is already right. Unchanged marks are redrawn only where their footprint meets the dirty tiles, and only inside them (dabs outside are placed but not painted). The result is bit for bit a full replay; later checkpoints are remapped to the new positions and refreshed where tiles changed. If unchanged marks changed order, the cel replays in full.
The editor keeps this record per paint cel. The CLI keeps the final tiles in .cache/tiles/<cel>.raster and the keys and footprints in <cel>.marks, so the first render after an edit updates the cached tiles the same way (without checkpoints). "Bake" turns a cel into plain pixels stored as compressed tiles and drops its strokes (later).
Attached modifier strokes
An eraser, smudge or blender stroke (a brush with blend: erase, or paint of smudge or blend) records the marks it changed: when it is added (an op, or pen-up in the editor) klad_core::attach::targets takes the earlier marks in its drawing whose paint comes within both brushes' reach of its path (fills by their pixels), and the marks of any earlier smudge or blender whose work it reaches, so trimming a smear attaches to what was smeared. Detection is generous on purpose: attaching too much only splits a modifier more often, missing a mark is what would show. It costs 0.1 ms for a small eraser and 2.7 ms for a 160 px soft eraser over 1,800 strokes of a 4,300-stroke painting (container, release). The ids are stored on the modifier (stroke files version 2), so undo, diffs and copies carry them; ids that no longer exist are ignored everywhere.
Edits follow them (markedit::apply_following, attach::follow, prune, join): a transform or lasso moves the modifiers whose marks all move and splits one whose marks move in part, a copy for the moved marks landing right after the original; turns and scales stay about the chosen marks; a delete removes a modifier left with no marks; copies take every modifier attached to a copied mark; the lasso picks plain marks, and a piece it cuts off joins its mark's modifiers. A modifier moved on its own is attached again where it lands (Bundle::reattach). detach clears the list, and the modifier then acts as before attachments existed.
Smudges and blenders still act on whatever is under them; only erasers are scoped (klad_brush::scope). From an attached eraser's first mark up to the eraser, the replay keeps three layers over the eraser's reach (its padded bounds, grown to take in any smudge or blender in between): what was there before the first mark, the eraser's marks alone, and the other marks since, each painted in order with the same f16 landing code as the drawing (unattached erasers erase all three, smudges and blenders are run again on each). At the eraser, pixels it covers become the others over its marks erased, over what was before; others stay. When the eraser is drawn, everything under it is its marks, so the result is bit for bit the in-order erase (a test checks soft and hard erasers with fills, lock alpha, colour brushes, smudges and blenders). Moved, its marks erase together and composite over what they land on, and an unattached mark under it sits below its marks if it is older than the first of them, above them otherwise. Overlapping attached erasers scale each other's layers by whether they share marks. A wet stroke, or a smudge or blender with lock alpha, in range leaves the eraser erasing in order, since their landing is not linear in the pixels under them; height (body) is erased in order. The tiled replay keeps a scope per tile; an update that touches an eraser's area widens back to the checkpoint before its first mark, after drawing the new marks once to know every tile the edit changes. A drawing without attachments takes none of this. Costs (container, release): 600 attached trims on 300 ink lines render in 101 ms instead of 87, and moving one line takes 14 ms instead of 10; a 4,300-stroke painting with a big attached soft eraser renders as fast as without.
A mark its attached erasers wipe out completely (its coverage times what they leave under 1/255 everywhere, scope::hidden) is skipped by clicks and the lasso and listed as hidden by klad strokes --json.
Brush engine
- Dabs. A stroke's samples are interpolated along arc length and a dab is placed every
spacing x size(the size at that point, taper included). - Tip. Procedural round (hardness),
chalk, or a picture ({"image": {"image": "<name>"}}): six library pictures drawn in code (bristle-flat,bristle-round,sponge,leaf,grass,splatter) or a PNG the bundle carries inbrushes/images/<name>.png(dark is paint, or its alpha when it has one), with roundness, rotation (fixed, follow direction, or tilt) and seeded jitter. - Dual tip (M5). A second tip stamped
counttimes per dab at seeded offsets withinscattermain radii, atsizeof the main tip and a seeded turn; the dab keeps the main tip's coverage only where the second one has paint (the most of its stamps). - Texture (M5). The grain is paper noise or a picture, at a
scale, with acontrast, andpressurefills it in on a hard press; it stays fixed on the canvas. - Colour dynamics (M5). Per dab and per stroke hue, saturation and value jitter (seeded: the per-stroke offsets from the stroke's seed on a stream of their own, the per-dab ones drawn after the dab's other jitter, so brushes without colour dynamics replay exactly as before); colour from pressure (from the stroke's second colour at a light press to its colour at a full one) or along the stroke (to the second colour over
alongpx). Strokes carry an optional second colour (stroke format 6, a flag bit, so strokes without it encode as before). - Dynamics. Size, flow and opacity each multiply curves of pressure, tilt (0 upright to 1 flat) and speed (0 to 1 at 5 px/ms). A curve is
min + (max - min) x input^gamma. - Taper. Per stroke, by length and independent of pressure: the size eases (smoothstep) from 0 at the ends to full over the first
inand lastoutpx. Live painting can only taper the start; at pen up a tapered stroke is drawn once more with its length known, which is also what every replay does. - Grain. A canvas-space texture modulates dab alpha (paper tooth).
- Stroke buffer. Dabs build up in an f32 coverage buffer towards a cap, the brush opacity times its opacity curve (flow vs opacity, as in Photoshop: one stroke never darkens itself past the cap, overlapping strokes do). A round tip's coverage is its profile averaged over the pixel, so a hard tip has a one pixel antialiased edge. Where the tip's falloff is under about a pixel wide (hard tips), a pixel builds up only to the coverage the dab gives it, not past it: dabs are placed a few per pixel, and building up towards the cap turned the half covered pixels along a line's edge solid, so hard lines lost their antialiasing and lines under 2 px were drawn heavier than their size. Tips with a falloff of 2 px or more build up as before, with a blend between. The stroke then composites into the layer at the stroke's opacity with the brush's blend (normal, erase).
- Wet paint, smudge and blend (M5). A brush's
paintiswet(wetness, pickup, dilution),smudge(strength) orblend(strength). They read only the drawing they paint into (its pixels before the stroke, and the stroke's own work so far), never other layers. The stroke buffer gains a colour layer: per-dab colour (colour dynamics and wet pickup, weighted by the coverage each dab adds) or, for smudge and blend, the replaced pixels (smudge takes each pixel from where the dab was before, blend averages a ring around it at 0.3 of the radius); landing a stroke lays its per-pixel colour over the layer or moves the layer's pixels towards the replaced ones. Replay is in stroke order, so a reading stroke sees what was under it; a tile-local update rebuilds the drawing when a reading stroke comes after the first changed mark (a test checks an edit under a smudge against a full replay). Live painting reads the active drawing too, so what is drawn is what replays. - Paint with body (M5, S5.23). A brush's
body(0 to 1, 0 by default;oil0.45,oil-load0.8) makes its strokes lay paint height. A drawing's raster (klad_brush::Raster) is its colour tiles plus an optional height channel (one f16 per pixel, in the same tiles), made the first time a stroke with body lands, so drawings without body cost nothing and keep their hash. While a stroke with body is drawn, each dab keeps the highest thickness it reaches per pixel. The thickness is measured across the stroke, not from the dab's centre (the maximum over overlapping dabs would otherwise make every pixel a lip): a flat middle rising to lips where the paint is pushed to the sides, falling to nothing over an edge band of 2.5 px or a third of the half-width, whichever is wider (0.6 at most), with the same falloff at the ends of the stroke. Grooves come from a profile fixed per stroke from its seed, about one bristle per 3.5 px, placed by the distance in px from the stroke's line so the dabs' size jitter does not fill them in; they cut 30% into a loaded stroke and up to 60% as the brush runs dry (the paint thins to 55% after eight sizes of travel). The thickness grows with the square root of the brush size (a 24 px brush is 1, from 0.4 to 1.6), so a small brush lays a thin film and a big one tall ridges, and with the pressure (30% at none). When the stroke lands, the height becomesh (1 - 0.85 a) + body a' t, withathe stroke's coverage times opacity,a'half to all of the opacity where the coverage passes 0.35 (falling off below it, so the height has the shape of the paint, not of a soft dab's dome) andtthat thickness: new paint pushes most of the wet paint under it aside instead of stacking on it, so the newest strokes do not stand up as separate ridges. Lock alpha lays height only where there is paint; the eraser scales it down by its coverage; smudge and blend carry height with the pixels they move, and wet paint takes it into its reservoir like colour. Height is kept in replay checkpoints and in the drawing cache (a height section after the colour tiles; engine version 5). Thereliefeffect samples the height of the layer's drawings (a group: of all its paint layers) into the effect window at the view scale, eases the tallest stacks (1.6 tanh(h / 1.6)), blurs it bysoftness, and for each pixel moves the colour towardshighlightwhere the slope faceslight, less in dark paint (by the square root of its luminance, as a lamp shows the ridges of the lit side more than those in shadow), and multiplies it towardsshadewhere the slope faces away; flat paint stays as it is. Costs on a 2048 canvas with 600 big oil-load strokes: replay 980 ms instead of 760 ms without body (the edge band, lips and caps are tables made per dab and read with interpolation), 8 MB of height, a whole compose 136 ms instead of 15 ms, one dirty tile 2.2 ms. - Feather and fringe. A round tip's
feathermakes it solid up to the smaller of its hardness and 1 - feather, and turns off the edge's build-up: each pixel's coverage stops at what one dab gives there (the ceilingEdge::coveralready returns, withsoft0) instead of overlapping dabs adding up towards full, so the stroke's cross-section is the tip's own fade whatever the spacing. Without it a soft round eraser at spacing 0.06 laid about 16 dabs over each pixel and only the outer pixel or two showed the softness.fringescales the dab's coordinates per pixel by a reach from 1 down to 1 - 0.55 fringe, read from a 2D value noise in the stroke's frame (the dab's heading and its distance along the stroke): across the stroke about one bristle line per 2.5 px of the stroke's size, along it one cell per 0.9 sizes, two octaves, seeded by the stroke'sseed. Every dab that covers a pixel reads the same reach, so the frays are streaks along the stroke; the first dab waits for the heading. Brushes without either keep their pictures and their speed (one branch per pixel). - Reshaping (M5). A stroke's
pathcan be set (set,klad reshape, A in the editor): every sample keeps its pressure, tilt and timing and moves to the same fraction of the new path's length as it had of the old one. The editor andklad strokes --jsonfit a few points to a stroke (pathedit::fit_polyline, the simplificationklad pathuses, at 0.12 of the stroke's size between 1 and 6 px); A edits those points and writes the bent path as oneset.
Brushes as data
A brush is JSON. The library is built in (crates/core/brushes/library/: ink inking pen, pencil, marker, airbrush, soft, chalk, eraser, and since M5 the painting set: flat-bristle, round-bristle, sponge, fog, leaves, grass, splatter, wet, smudge, blender, dry-brush, two-tone). The brush window (F5, editor/brushwin.rs) edits every setting with a live sample, draws with the edits at once (as a variant id, like the quick tuning), and saves a named brush into the bundle; pictures for tips and textures come in by path or by dropping a PNG on it. The brush fingerprint covers the bundle's pictures when it has any. A tip may hold several pictures ("more" beside "image"); each dab takes one, chosen by a hash of the stroke's seed and the dab's number so other brushes' random sequences are untouched (leaves draws from four leaf shapes since S5.27). A bundle embeds every brush its strokes use in brushes/<id>.json the first time a stroke with it is written, and from then on that file defines the id for that document, so changing the library never changes an existing render. Lookups go bundle first, then library.
{
"format": "klad-brush/1",
"name": "Every key, with example values",
"tip": { "round": { "hardness": 0.92 } },
"spacing": 0.04,
"roundness": 1,
"angle": { "fixed": 0 },
"flow": 1,
"opacity": 1,
"dynamics": {
"size": { "pressure": { "min": 0.06, "gamma": 1.5 } },
"flow": { "tilt": { "min": 1, "max": 0.6 } },
"opacity": { "speed": { "min": 1, "max": 0.8 } }
},
"jitter": { "size": 0, "angle": 0, "scatter": 0 },
"grain": { "paper": { "seed": 11, "feature": 2 }, "strength": 0.55 },
"blend": "normal",
"taper": [10, 24],
"stabilizer": 24,
"smoothing": 12
}
tipis{"round": {"hardness"}}or{"chalk": {"seed"}};angleis{"fixed": radians},"follow"or"tilt"; jitter angles are radians. Everything butname,tipandspacinghas a default and is left out when it is the default.taper,stabilizer(ms) andsmoothing(ms) are defaults for new strokes and for recording; the stroke stores its own taper, so they never change a replay.- The editor's brush panel changes size, opacity and flow per stroke. Changing hardness or the size curve makes a variant: the same id when the bundle has no such brush yet, otherwise
<id>-<6 hex of its content>, embedded with the first stroke.
Pixels and compositing
- Tiles are 256x256, RGBA f16, premultiplied, sRGB encoded. Blending happens in sRGB space by default (what artists expect from Photoshop); a linear document setting comes later. A raster holds its tiles behind shared pointers and copies a tile only when it is written while shared (copy on write), so cloning a raster is cheap: background threads compose frames from the editor's drawings without copying them.
- Layers are composited by Skia on F16 raster surfaces. A mask is applied by drawing the mask's cel with destination-out over the layer's content in an isolated layer. A clip group is an isolated layer holding the base's content; each clipped layer is drawn in its own isolated layer, cut to the base with destination-in (the base drawn again), and blended onto the group.
- A layer with effects, or a clip group with an adjustment in it, is drawn into its own buffer covering the visible area plus the effects' reach (the tile path draws every raster tile that buffer touches), read back as f32, run through the effects and drawn back. Adjustments read and rewrite the pixels of the surface they are composed on, which is only allowed where nothing is isolated above it (a context flag says so); a group holding one gets a buffer of its own.
- The editor caches the composite of everything below and above the active layer, so a dab only recomposites three images in the dirty region. When a layer above blends through (a blend other than normal, an adjustment, a glow that is not normal), the layers above are composed live over the cached below and the active layer instead of cached. While painting, dirty tiles widen by the reach of the effects on the active layer and the groups around it (other edits widen by the largest reach in the document), and every live preview tile in reach is handed to the compositor, so a glow on the layer being painted grows across tile edges as you paint.
- Planes on disk (M5). The two cached composites are kept per frame and active layer in
.cache/planes(1 GB budget, oldest out first), keyed by the frame's layer structure, the active layer, the onion plan and the pixel-cache key of every drawing in it, with the layers' thumbnails. A lean (heavy) scene that finds them loads only the active drawing's pixels (and its onion ghosts) and the other drawings' strokes and edit records from the pixel cache. Preparing frames writes them too, and the ruler's blue line counts a frame with planes and the active drawing cached as drawable. - Frame keys read a stroke file only when its size, time or inode changed (writes are atomic renames, so a rewrite always gets a new inode); an edit no longer clears them.
- Onion skin (M3) is computed in
klad-render(onion), one piece of code for the CLI, the editor's canvas and its frame cache. For a layer at a frame it lists the drawings before and after the current one: counted in drawings (the exposures before and after, each drawing once at its nearest distance, the current drawing and links to it skipped) or in frames (the drawings shown 1, 2, ... frames away). Opacity isopacity x falloff^(distance - 1)(defaults 0.5 and 0.6, 2 before and 2 after); those before are tinted red and those after green (rgb x 0.25 + tint x alpha x 0.75) unless the tint is off. In a looping range the count wraps around inside the range, so the last drawing of a cycle shows the first. The ghosts of a layer are composed (furthest first, f32 per pixel, on tiles in parallel, deterministic) into one raster, which the compositor draws right under that layer, outside its opacity, blend and mask; the ghosts of a clip group's layers go under the whole group. Hidden layers show none. - Sheets (M3):
klad render --sheetlays frames out in a grid (columns about square,--columns), each cell the frame at--cellpx on its longest side with its frame number, aholdmark when it looks exactly like the frame before, and per layer (top first, listed in the heading) the cel it shows:c5starts a drawing,|c5holds it,c9>c1a link,.blank.--drawingsmerges frames that look the same into one cell titled with their range. A clip's sheet is headed with the clip's name and its fps. Frames that look the same are composed once; drawings load in batches under 768 MB, so long sheets of big canvases stay in memory. - Export (
klad export) renders the image, or one layer or group alone (a clipped layer alone stays clipped to its base's shape), at a frame, at a scale from 1/16 to 8, on transparency unless--background. Vector nodes are drawn at the export scale. Above full size the paint is drawn again at the export size: each drawing's marks are scaled (markedit::transform_mark: samples, sizes, tapers and cuts; fill coverage resampled bilinearly) and replayed with the brushes at that scale (BrushSet::at_scale: grain scaled with it, speed and bristle spacing measured in canvas px), the rasters drawn one to one (Ctx::detail), so lines stay crisp and textures keep their size; sprite sheets and frames do the same with their vector cels rasterized at that size. That replays without the cache (the lemons at 2x: 5.5 s instead of 0.7 s). Below full size the cached rasters are mipmapped down. PNGs are written byklad-render/pngwrite.rson every core: rows filtered in parallel (the filter with the smallest sum per row), compressed in strips of 256 KB as one deflate stream (each strip ends on a sync flush, the last finishes it), in IDAT chunks of 1 MB, with an sRGB chunk; the strips depend on the row size only, so the bytes are the same on any machine (2400x1800: 115 ms instead of Skia's 457 ms, the same size within 2%). 8-bit PNGs are ordered-dithered (8x8 Bayer) from the f16 pixels, colour and alpha, so gradients do not band; values within an eighth of a level of an 8-bit value are written as that value, so flat colours stay flat.--depth 16writes 16-bit PNG. Working renders (klad render,klad hash) stay undithered so their hashes hold.
The agent interface: klad CLI
Stateless: read the bundle, apply, write atomically, optionally render. Output is short text by default, --json for structure.
Every command with its options is in docs/cli.md, which klad reference (hidden) writes and a test keeps current. klad-client (crates/client) runs the commands from Rust: Klad finds the binary (KLAD or the path), Drawing applies op lines through klad apply and reads ls, show, strokes, notes and selection as JSON.
An error is one line on stderr (error: reading a.klad/doc.json: No such file or directory) and exit code 1, whatever RUST_BACKTRACE says; a bug (a panic) is one line too, with where it happened and where to report it. KLAD_BACKTRACE=1 prints the whole chain and the backtrace instead.
| Command | Purpose |
|---|---|
klad new <bundle> [--width --height --layers --background --fps --frames --sketch] |
create (--sketch adds a vector layer named sketch on top); the editor's New makes bundles with the same code |
klad ls <bundle> [--frame n] [--json] |
compact tree, top first: ids, kinds, names, contents, bounds, flags |
klad show <bundle> <id> |
one layer, cel, node, stroke or fill (<cel>:s<id>) in full, with bounds |
klad add / set / rm / mv |
single edits, all take --render, --scale, --json |
klad apply <bundle> [--file] |
many edits from JSON lines, one transaction, one write, one render |
klad stroke <bundle> <layer> --brush ink --path "M..." --pressure 0.2,1,0.1 [--taper 12,30] [--frame n] |
the agent paints: SVG path (several subpaths make several strokes) or --points; --taper defaults to the brush's; also a stroke op in apply |
klad brushes [<bundle>] [--show id] [--json] |
the library and the brushes a bundle embeds, with where each comes from |
klad strokes <bundle> <layer> [--frame n] [--json] |
stroke and fill list: address (<cel>:s<id>), author (human or agent), brush, samples, rate, pressure, tilt, bounds; fills with seed, reference, gap and pixels; JSON includes points and the order |
klad transform <bundle> <cel>:s<id>... [--move dx,dy] [--rotate deg] [--scale k] [--sx --sy] [--flip h|v] [--pivot x,y] |
move, turn, scale and flip strokes and fills; also a transform op. transform and lasso previews use the default size (their --scale scales the marks) |
klad lasso <bundle> <layer> --polygon 'x,y ...' [--cut] [--move dx,dy] [--rotate deg] [--scale k] [--sx --sy] [--flip h|v] [--pivot x,y] [--rm] |
without a move or --rm it lists the marks inside and crossing; otherwise one lasso op |
klad add <bundle> mask --in <layer> [hide=true] |
give a layer a mask (prints its id); paint it with klad stroke <bundle> <mask id> |
klad path <bundle> <node> [--move i x,y] [--nudge i,j dx,dy] [--handle i in|out x,y] [--insert i,t] [--add x,y] [--rm i,j] [--corner i] [--smooth i] [--simplify px] [--convert] |
list the points of a path, rect or ellipse, or edit them; also a path op |
klad fill <bundle> <layer> --at x,y [--ref this|all|<layer>] [--gap 4] [--tolerance 0.1] [--expand 2] [--color c] |
flood fill inside the lines; --polygon 'x,y x,y ...' for a lasso fill; also a fill op |
klad refill <bundle> <layer> [--id n] |
recompute flood fills after the lines changed |
klad palette <bundle> [--add '#..' --name n] [--rm key] |
the document palette; also a palette op |
klad frames <bundle> [--from n --to n] [--json] |
the exposure sheet: a row per frame, a column per layer (top first), the cel id where a drawing starts (c5* for an in-between), | while it shows, c5->c1 for a link, . for blank, clips on the right |
klad frame <bundle> insert|remove <n> [--count c] [--layers l3,l5] |
insert or remove frames; a frames op |
klad cel <bundle> new <layer> | dup <cel> | link <cel> | unlink <cel> | move <cel> [--frame n] [--hold h] [--insert] |
make, link and move drawings on the timeline; a cel op |
klad duplicate <bundle> <layer> |
a copy of a layer with its drawings, links and mask, above it; a duplicate op |
klad copy <bundle> <cel>:s<id>... --to <cel> | --frame n [--layer l] [--move dx,dy] [--rotate] [--scale] [--sx --sy] [--flip h|v] [--pivot] [--cut 'x,y ...'] |
copy marks into another drawing; prints c1:s3 -> c9:s12 for each; a copy op |
klad retime <bundle> <from>-<to> --on n | --fit n | --reverse | --pingpong [--layers] |
retime a range; a retime op |
klad inbetween <bundle> --layers l3,l5 --from a --to b [--count n] [--spacing even|in|out|in-out|0.2,0.5] [--match id|order|near] [--pair s3=s7] [--unpaired leave|pop|fade|draw-on] [--at t] [--force], --from a --loop, klad inbetween <bundle> --redo [--layers] [--from --to] [--keep-drawn | --force] [--only c12,c14] [--keep-cels c12] [--force-cels c14] |
make or remake in-betweens; lists pairs (by part first), touching ends kept, unpaired marks, fills left out and the time per frame |
klad part <bundle> <cel>:s<id>... --name leaf |
name marks as a part (--name '' takes them out); --part on stroke, fill, ink, hatch and scatter; klad strokes shows each mark's part |
klad arcs <bundle> --track c4:s12|leaf|lines:leaf|x,y ... [--clip walk | --from --to] [--ground y[,y]] [--travel px] [--slack 2] [--json] [--check] |
positions per frame, distance moved, lowest points; with --ground under the ground and slides, with two tracks swaps; --check fails on any of them |
klad ink <bundle> <layer> --from <node>,... | --path "M..." [--weight 6] [--light x,y] [--break 60] [--gap] [--wobble 0.6] [--taper in,out] [--brush] [--color] [--hand 1] |
ink the outlines of shapes as tapered strokes with weight rules, each drawn like a hand |
klad light <bundle> --from <node>,... [--light x,y] [--shade <layer>] [--rim <layer>] [--depth 14] [--soft 3] [--rim-width 4] [--lamp x,y,h] |
shade and rim fills from one light direction, or per shape away from a lamp |
klad hatch <bundle> <layer> --in <node>,... [--angle 30 | --along] [--spacing 6] [--length 12-30] [--jitter] [--weight] [--hand 1] |
short tapered strokes inside closed shapes, each drawn like a hand |
klad paint <bundle> <layer> --in <node>,... [--color] [--form round|flat|cylinder] [--axis 90] [--facing x,y,z] [--light x,y] [--elevation 0.6] [--lamp x,y,h] [--key] [--fill] [--bounce] [--core 0.35] [--shadow c] [--shadow-mix 0.7] [--weight 14] [--brush oil] [--bold oil-load] [--decisive 1] [--hand 1] |
paints each shape as a form: a height field from its outline (round), a plane or a cylinder, lit by a key light or lamp with fill, bounce and a core; strokes follow bands of equal light, take their colour from the model and stop where the light changes; big to small, then decisive strokes in the lights |
klad prepare <bundle> [--from] [--to] |
replay the painted drawings of a span of frames into the cache |
klad scatter <bundle> <layer> --in <node>,... [--mark "M..."] [--count n | --spacing 14] [--size 0.7-1.2] [--turn -15,15] [--avoid <node>,...] [--hand 1] |
copies of a small mark inside closed shapes |
klad fill <bundle> <layer> --shape <node> [--expand 2] |
fill exactly a shape's area |
klad fill <bundle> <layer> --like <cel> [--frames all|a-b|clip] |
carry a drawing's flood fills to the layer's other drawings |
klad gaps <bundle> <layer> [--frame n | --sheet all|a-b|clip] [--ref] [--gap] [--min 12] [--render] [--json] |
closed regions no fill covers, with bounds; a render marking them for each frame that has any |
klad timeline <bundle> [--fps n] [--frames n] [--origin x,y|centre] |
show the timeline (fps, length, origin, Godot folder, clips) or set fps, length and origin; a timeline op |
klad clip <bundle> [--add name --from a --to b [--loop] [--fps n]] [--set name [--name new] [--from] [--to] [--loop|--no-loop] [--fps n|doc]] [--rm name] [--json] |
list, add, change, rename and remove clips; a clip op |
klad render <bundle> [--frame n] [--focus id] [--scale s] [--region] [--overlay ids,bbox,grid,onion,parts,arcs] [--track ...] [--depth n] |
PNG, prints the path, and size, pixel hash and timing on stderr. --focus zooms to a layer, cel or node; overlays label boxes with ids. Onion: --onion 2,2 (before, after), --onion-by drawings|frames, --onion-layers l3,lines (default: every layer with more than one drawing), --no-tint, --onion-loop 0-7 (wrap inside a loop); any of them turns the onion overlay on |
klad render <bundle> --sheet all|0-11|<clip> [--drawings] [--cell 256] [--columns n] [--overlay onion,parts,arcs ...] [--track ...] |
many frames in one labelled grid (see Sheets); arcs span the sheet, each cell ringing its own frame |
klad selection <bundle> / klad notes <bundle> |
what the human selected or pinned |
klad log / undo / redo / diff [--step n] |
shared history of CLI and editor changes, before and after renders side by side |
klad export <bundle> [--layer id] [--frame n] [--scale s] [--depth 8|16] [--background] [-o out] |
PNG of the image or a layer or group |
klad export <bundle> --sheet all|<clip>|0-11 [--scale s] [--padding 2] [--max 4096] [--depth] [--layer] [-o out.png] |
sprite sheet pages and Aseprite array JSON (see Exports) |
klad export <bundle> --frames all|<clip>|0-11 [--scale s] [-o dir] |
numbered full-size PNGs, one per frame (run-0000.png, ...) |
klad export <bundle> --godot [dir] [--store] [--scale s] |
the sheet, a SpriteFrames .tres and an AnimatedSprite2D .tscn (see Exports) |
klad hash <bundle> [--frame n] [--all] |
pixel hash for the parity check; --all one line per frame |
klad open [bundle] |
the editor; without a bundle, the start window: New, Open (the platform's open panel or a pasted path), Recent with thumbnails |
klad bone <bundle> <layer> --add n [--parent p] --head x,y --tail x,y, --rm n, --rename n --as m, --move n [--head] [--tail] or --move n --by dx,dy, --reparent n [--parent p]; klad bones <bundle> [--json] |
skeletons (see Rigs) |
klad weights <bundle> <layer> --auto | --bone b --set 'x,y,r,w ...' | --bone b --part p [--value v] | --smooth |
how much each bone moves the drawing |
klad pose <bundle> <layer> [--from f] --to f --bone name=deg ... [--root x,y] [--hold n] |
a posed drawing from the rest drawing |
klad key <bundle> <id> --frame f prop=value ... [--ease e] [--rm]; klad keys <bundle> [id] [--json] |
animate layers, groups and shapes (see Keys) |
klad export <bundle> --godot-scene [dir], --godot-rig [dir] |
a Godot parallax scene; a Godot rig with its animations |
klad paintover <bundle> <layer> [--from] [--in] [--sizes 32,16,8] [--threshold 6] [--length 1,8] [--curve 0.5] [--brush oil] [--focus] [--vary] [--like <cel> [--frames a-b]] [--part] [--seed] |
brushwork from what is below the layer (see Paint over) |
klad compare <drawing|png> <reference> [--frame] [--region name=x,y,w,h]... [--heat out.png] [--json] |
values, saturation, texture, edges and colour against a reference, in numbers and words |
klad install [--dir], klad skill [drawing | pixel] |
put klad on the terminal's path; print the agent skill, or with drawing the skill that teaches the craft of drawing (docs/skill/drawing/SKILL.md), or with pixel the craft of pixel art (docs/skill/pixel/SKILL.md); all MIT, the craft skills written for any agent and any tool |
klad samples [--json], klad samples --copy <name> [--into <folder>] |
the sample drawings a build carries; copy one to draw on |
klad report [--drawing <bundle>] |
a problem report to paste into an issue, the drawing zipped to attach |
Scripts are any language that prints edit ops as JSON lines into klad apply. Generators that should stay editable (scatter, repeat, symmetry) are built-in vector node kinds with parameters.
--sheet run renders every frame of clip run in one grid with frame numbers, drawing ids and holds, so an agent sees a whole animation in one image.
The editor
- Canvas: pan, zoom, rotate; pen pressure, tilt and eraser end; 120 Hz on Apple Silicon. The window around the canvas is a neutral grey (
theme::SURROUND), so colours read true. - Layout (M4 batch 1): a tool strip on the left (the tools with their key letter, undo and redo, and at its foot the document and panels menus, the command palette, settings and, with developer tools on, numbers; the strip only has the height between the menu bar and the timeline, so when both groups do not fit its buttons shrink from 36 to 28 pt, then the foot folds into one menu pinned at the bottom, and last the tools scroll, never overlapping; each size is measured as it is drawn, so the choice does not flicker); a dock on the right holding panes (colour, brush, layers, layer settings (
Pane::Inspectorin code), notes for the agent, history), each with a title row that folds it, closes it and, dragged at its top edge, resizes the pane above; the timeline along the bottom, resizable and foldable to its toolbar; a status line under everything. Panes share the dock's height: they keep the sizes the user gave them, the last open one takes what is left, and when they do not fit they shrink towards their minimums and scroll inside (layout::Layout::bodies). Tab hides every panel but the status line, shift Tab the dock. Which panels are open, the dock's width, the timeline's height and each pane's size are kept in the user's settings (layout) and restored, clamped to the window. Pen calibration lives in the settings modal (cmd ,); the performance numbers in a numbers window that can stay open over the canvas, shown only with developer tools on (Settings > Layout,developerTools, off by default;commands::DEVELOPERlists its commands, which are in no menu, not in the palette and refused without it). - Commands (M4 batch 1): every editor action is a
Cmdin one list (commands.rs): an id (tool.brush,drawing.new, kept in settings), a name in plain words, a Phosphor icon, a group, its keys or the hold that triggers it, whether a held key repeats it, and a line on what it does. Keys, the strip, panel buttons, the timeline's buttons and context menu, and the palette all run commands throughEditor::invoke, which first askscan_run(a reason when it cannot, shown as a refusal) and remembers the last twelve run. A key matches only with exactly its modifiers (shift K is not K); key repeats run commands that repeat (=,[, cmd Z) and frame steps only once the frame on screen caught up. cmd K opens the palette: type to filter (name start, then a key, a word, a substring, the letters in order, the group; hyphens ignored, so "inb" finds in-between), arrows and Return run, rows grey out with the reason, recent commands first;?opens it too. Every control has a hover hint after 0.35 s (from its command where there is one) and is at least 24 pt high; a test walks every control of every panel and window to keep it so. - Tool options and selections (M4 batch 2): a bar over the canvas holds the active tool's settings (brush: picker, size, opacity, flow, for the eraser also feather, which sets its brush's
featherfor the E eraser and the pen's eraser end alike and is kept in the settings aseraserFeather, and a "more" menu for hardness, feather, lightest size, curve, taper, stabiliser and smoothing; fill: reference, gap, tolerance, grow, opacity; strokes: cut at the lasso edge, select all; points: corner, smooth, simplify, make it a path). The strip shows the eraser while the eraser brush or the pen's eraser end is on, and two colours (the current one over the second; X or a click swaps them; picking a colour from a swatch, the hex field or the eyedropper makes the old one the second). cmd alt drag sideways on the canvas sizes the brush (doubling every 120 pt), the circle staying where the drag began. H flips the view left-right (the view's mappings and the GPU matrix mirror; the document does not change); the status line's zoom takes a click for 100% and a double-click to fit, its rotation a click to turn upright. A selection bar sits under (or over) the selection's box: for strokes flips, quarter turns, recolour, thinner, thicker, opacity, copy, paste, duplicate in place, delete, deselect, and when erasers, smudges or blends are attached to the strokes their count (a click selects only them, Edit > Strokes > Attached only) and detach; for a shape flips (sx or sy negated and its rotation mirrored), quarter turns, fill with the colour and outline in the colour (rectangles, ellipses, paths and text:fill, orstroke.paint, or a newstrokeat the pen's width when it had none; Edit > Shape;klad set <id> fill=...is the CLI form), duplicate in place (anaddof the node without ids, above it), delete, deselect; for points corner, smooth, nudges, delete. Arrows nudge strokes, a shape or points by 1 px, 10 px with shift. Strokes select across layers (M5 batch 2 round 1): cmd or shift click on rows in the layers panel adds paint layers to the active one (marked with a blue edge); S then lassos, clicks and selects all on all of them, and the selection (one part per layer) moves, turns, scales, flips, recolours, cuts at the lasso edge, copies and deletes as one edit, each layer's marks staying on their layer. A selection on several layers moves as one edit, each layer previewed while it is dragged; copies of several layers paste back into their own layers, a copy of one layer into the active one. The strip's panels button lists the six panels and the timeline with a tick each, so a closed panel always has a way back. U draws rectangles and ellipses on a vector layer (shift for a square or circle, alt from the centre, rounded corners for rectangles; fill, outline and width shared with the pen, the fill in the first colour and the outline in the second, as for the pen's paths) asrectandellipsenodes. Mirror painting (the brush bar's "mirror" and its axis) paints every stroke's mirror image as it is drawn, in a second stroke buffer landed after the first, and commits both as plain marks in one history step. Handles are drawn at 12 pt and hit within 12 pt (grab); a press becomes a drag once it has moved 3 pt on screen, so a tap that wobbles selects and does not move; shapes whose rotation is a quarter turn get edge handles too (lift::stretchedscales their own axis). Pen events that arrive while a point edit is being written are held and replayed in order after it. The colour pane shows the picker and the palette (swatches drag to reorder; the x in a hovered swatch's corner, or a right-click, removes it) and recent colours; the brush pane (its own since 2026-11-08, on the request "make brush its own palette, like colour and layers") the size presets and the brushes as tiles, each with a sample stroke drawn byklad-brushonce per brush definition. A saved layout without a pane gets it after the pane it follows by default. - First start (S8.7,
start.rs,editor/first.rs,klad_core::samples): until the settings saywelcomed(set when any drawing opens, or by "Not now"), the start window opens with a welcome offering first steps. First steps makefirst steps.klad(1280 by 800 on paper, one paint layer) in the drawings folder and open it with a small window of three steps that tick as they happen: a brush stroke is saved, a fill is saved, the request for an agent is copied (a sentence with the drawing's path asking the agent to readklad skill, render the drawing and add a shadow; "install the klad command" sits next to it). Help > First steps opens and closes the window on any drawing. The checklist is the editor's alone: it teaches the hands on the canvas, and an agent's first steps areklad skill. Revisit the third step when klad is an MCP server (S8.10). Under the recent drawings the start window shows the samples: the drawingssamples/shipped.jsonnames (name, bundle, a line on what it shows), each a card with its thumbnail and that line; a click copies it into the drawings folder without its.cache(samples::copy,<name>.klador<name> 2.klad) and opens the copy, so a sample is never changed.klad sampleslists the same set and--copy <name> [--into folder]copies one (default the current folder). Samples are found like the fonts:KLAD_SAMPLES, thensamples/next to the binary,../Resources/samples,../share/klad/samples, and a source checkout'ssamples/up to five folders above the binary (where they exist afterjust samples; a sample not built is left out).packaging/samples.shputs them in every build: it builds any that are missing with that build'sklad(through the sample'sbuild.sh,PYTHONnaming the interpreter), copies them without caches, and renders each one's<name>.thumb.pngnext to it at 336 px, so the start window never renders into the app (a thumbnail outside the bundle is used as it is; only recent drawings'.cache/thumb.pngare remade when the drawing changes).app.shputs them inResources/samples,archive.shin the archive'ssamples/and the AppImage'susr/share/klad/samples; the six weigh about 4 MB. - Messages and problem reports (S8.8,
report.rs): a message says what happened and what to do next ("nothing to fill there: click inside closed lines, or raise the gap so small openings close"); a refusal names the step that makes the command possible. Errors that mean klad itself went wrong (an invariant broken, a picture missing that should be there) arereport::Bugs: the editor says "something went wrong inside klad (what), everything up to your last edit is saved; Help > Report a problem sends it to [email protected] or to klad's issues" instead of the bare detail; a job whose CLI crashed reads the same, and a job that failed says " did not finish: <the CLI's reason>". Every error message, job failure and crash of the editor or the CLI is appended toklad.lognext to the settings (KLAD_LOGoverrides it; past 512 KB the older half goes), one dated line each. Help > Report a problem opens a window with the report as it will be copied: klad's version and where it ran, the system (macOS version, the Linux distribution, Windows' version, and the processor), a place for what happened, the drawing's size, the last 40 messages and the last 40 lines of the log, with the home folder written as~and the drawing's folder as<the drawing's folder>. "include the drawing" zips the drawing without its cache next to it (<name> for a report.zip, stored entries, written by klad itself) and the report names the file to attach; "copy the report" copies it, "email it to support" opens an email to the support address with the report in it (the person attaches the zip), and "open klad's issues" opens GitHub. Help > Contact support opens an email with the version and the system filled in, and About links klad.studio and the address. Help > Guides and Help > What's new open the guides and the changelog on klad.studio, and the start window's welcome links the guides. The address, the site, the issues page, the guides and the changelog are constants inklad_core::contact; the site's sync reads the address from there. Nothing is sent by klad.klad report [--drawing <bundle>]prints the same report from the command line (version, system, log, the drawing zipped). - Menus (S8.6,
commands::MENUS,menus.rs): one list of menus holds every command but the holds (pan, zoom, the eyedropper, flipping, rolling, the parallax preview and sizing on the canvas, which are gestures), so the menus, the palette and the keys stay one list; a test fails when a command is in no menu or in two (the developer tools are the exception: in none). The menus, in order: File (new, open, recent, close; import; export; the path and the command line tool), Edit (undo; copy, paste, duplicate, delete; selecting; Transform, Strokes and Points submenus), Tools (the tools, the brush, the colours), Layer (new, duplicate, rename, group, delete; show, lock, clip, lock alpha; Mask and Shape generators submenus, paint over; refill and gaps), Frame (stepping, drawings, holds and moves, inserting and removing frames), Animation (playback, onion skin, exposure, Selected frames and Clip submenus, the checks across frames), View (zoom, rotation, flip, the reference), Window (the panels, the message log) and Help. Each command has a short menu label (Cmd::menu: "Show", "Clip to layer below", "Export…"), since the menu says what it acts on, while the palette and hints keep the longer names; "…" marks a command that opens a window. Items show one key each (Backspace for delete); toggles show a tick, except commands that open a window; a command that cannot run now is greyed out (its reason is the palette's). A test keeps labels unique in each menu and under 30 characters. On macOS the list becomes the system menu bar (menus::install, rebuilt when the keys or the recent drawings change): an app menu with About, Settings, Services, hide and Quit, then the list, whose Window menu also gets the system's Minimize, Zoom and Bring all to front (it is the app's windows menu). Items target one Objective-C object (KladMenuTarget,define_class!) whosekladRun:queues the command for the next frame (the editor runs it throughEditor::invokeas any key would) and whosevalidateMenuItem:reads a snapshot of what is off and on that the app refreshes every 0.4 s. The item keys are shown but not claimed: the object is each menu's delegate and answers no tomenuHasKeyEquivalent:forEvent:target:action:, so a key still reaches the editor's own dispatch (which knows holds, repeats and text fields) and nothing runs twice; only the app menu's own keys (cmd , cmd Q cmd H) and Window's cmd M are AppKit's. On Windows and Linux (and in tests) the same list is an egui menu bar over the window, hidden with the panels (Tab). File > Open recent lists the last ten drawings; File > Close the drawing (cmd W, refused while a job runs) goes back to the start window, where only new, open, recent and quit run. Settings and Quit sit in the app menu on macOS and in Edit and File elsewhere; About (with the licences) is in Help everywhere and also in the macOS app menu. - Messages and jobs (M4 batch 1): every result, refusal and error goes through
Editor::saywith a tone (info, done, refused, error). Done and refused messages show for 3.5 and 6 s as a toast in the bottom left corner of the canvas, newest lowest (2026-11-08: they used to follow the pointer, which got in the way), errors until dismissed, info only in the status line; the status line shows the latest message (a click opens the message log, the last 200 with times), the frame, where the next stroke goes ("draws on lines, frames 4 to 7"), running jobs with a cancel button, slow internal work (preparing a selection, drawing an edited path, loading a frame), zoom and rotation. Times that used to be status text (stroke, fill, edit, undo, sync, frame step, last play, last job) are kept by name for the numbers window. Nothing a user sees names an internal id: the status line, layer settings, the selection, the in-between window, undo messages and the history pane say layers by name and drawings by frame (Editor::plainrewrites history summaries and CLI reports), the timeline numbers each layer's drawings 1, 2, 3 in frame order, and new layers are named "paint 1", "vector 2" instead of by id. A kittest scan (scanin the control audit and over every tool) fails on an id (c12,l6,n357,s4), a milestone or a story number in any visible label. Background jobs (in-betweens, Godot export) run the samekladbinary through one job list (jobs.rs); when the CLI exits with code 75 (the document changed while it computed) the job runs again, up to three times, so an edit made in the editor meanwhile is never overwritten. - Tools: brush, eraser, smudge, fill (inside lines, gap closing), lasso select and transform, move/rotate/scale handles, path point editing, eyedropper.
- Stroke select (S, M2): a click picks the mark you see under the pointer. With "all layers" (the S and V options and Edit > Pick from all layers,
pickAllLayersin the settings, on by default) that is on the topmost visible, unlocked paint layer that shows paint there, which becomes active: a layer shows paint where its raster's alpha, times its own and its groups' opacity, outside its mask and inside its clip base, passes 5%, and a layer whose pixels are not loaded counts by its marks' shapes (Scene::seen_at,Scene::marks_at); with "this layer" it is the active layer. In that layer the mark is the topmost one covering the point (inside a stroke's painted width or a fill's coverage, never an eraser stroke or a mark its attached erasers wipe out), and only when none covers it does one within 5 pt of the point count, so a thin line is still easy to take (markedit::pick); when no layer shows paint there, the topmost mark within those 5 pt on any of the layers is taken. A shift click adds or removes on the active layer, a dragged loop picks every stroke whose samples are all inside it and every fill whose pixels are (attached erasers, smudges and blends follow their marks instead), shift adds or toggles. With "a lasso cuts strokes at its edge" (on by default) the loop also takes the parts of strokes and fills crossing it: the selection shows the dashed lasso and the parts that will move, and the first edit (move, recolour, delete, ...) writes onelassoop that splits them, after which the selection is the moved marks. The selection shows as thin lines and a box with corner handles (uniform scale), edge handles (stretch one axis; dragging past the other edge flips) and a rotate knob; dragging moves it on the GPU (the selected marks drawn alone, over the cel replayed without them) and release writes onetransformorlassoop. Layer settings recolour (the current colour), makes thinner or thicker, sets opacity, flips left-right or up-down and deletes, each as one history step. The selection is shared with the agent as addresses. - Layers (M2 batch 4): layer settings sets clip to the layer below and lock alpha, adds a mask (empty, or hiding all), turns it on and off, removes it, and "paint on the mask" makes the mask the active layer (it also has its own row under its layer). Painting on a mask hides the layer under the strokes; the eraser shows it again. While a mask is active, what it hides is tinted red ("show the mask in red", on by default), and the brush panel says whether the brush or the eraser is on. The brush and fill tools record lock alpha from the active layer.
- Live previews and clipping: the editor composes the active layer between cached images of everything below and above it only when that is exact (the active layer and the groups around it are not clipped, masked or a clip base); otherwise each dirty tile composes the whole stack. A drag (a shape with V, strokes with S or V, any grab: move, scale, turn, stretch, an alt-drag copy) previews the edit it will commit: at its first move the editor takes a snapshot of the document and the pixels (tiles are shared, so this is cheap), and while the pointer moves a background job applies the drag's ops in memory, redraws only the tiles they change (vector nodes through the tile patching below, strokes through the cel's replay) and composes those tiles through the whole stack, so clips, masks, blends, group effects and everything above the dragged thing stay exactly right. One job runs at a time and the newest pointer position wins; only tiles on screen are composed while dragging. The composed tiles go straight to the canvas plane, which is shown while a preview is up. On release the edit is written at once (it costs only its tiles), a last job composes the final position, and its tiles are taken as they are when the edit only moved vector nodes; tiles the preview touched that the edit did not are composed again. In a lean scene, while a mask is tinted, or before the canvas has caught up, a drag shows only its outline and lands on release.
- Vector edits redraw only their tiles: a changed vector cel whose node order is kept is patched where its changed nodes were and are (their bounds grown for strokes, miter joins, blur and generator instances; added, removed and hidden nodes count), drawn on one surface that holds every node touching those tiles and starts on a tile boundary, so no node is cut at a tile edge, big blurs downsample on the same grid, and the tiles are bit-identical to a full rasterization; hidden nodes and nodes without bounds draw nothing and are left out; a new order, or a node without bounds, redraws the cel. A swapped vector raster (an edit, undo or redo from the remembered rasters) dirties only the tiles whose pixels differ.
- Switching the active layer rebuilds only the caches below and above it: when the canvas was complete for that frame and revision, onion skins are off and no mask is tinted, the canvas plane is kept instead of composed again.
- Composed tiles and frame pictures reach the GPU through an outbox the paint callback empties, holding the newest version of each tile: a UI pass that egui discards (a grid or popup laid out for the first time) drops its paint callback, and the tiles it carried would otherwise never be uploaded.
- Direct select (A, M2): click a path, rect or ellipse (inside groups too) to show its points; clicking the selected shape again steps down to the next shape under the pointer, and layer settings list them all; click or shift click points, drag on empty canvas for a box; drag points or handles; alt click the outline adds a point, alt click a point toggles corner and smooth, alt drag a handle breaks it; delete removes points; layer settings have corner, smooth, delete points, simplify and "make it a path". While dragging, the edited outline is drawn live; on release the edit is one
pathop whose layer is rendered in the background, then swapped in. - Select and move (V, M4 test): a press picks what you see under the pen and drags it at once: the mark S would pick and the topmost vector shape there are compared by their layers' places in the stack and the higher one wins (clicking a shape again steps to the one under it); its layer becomes the active layer. With "this layer" only the active layer's marks or shapes are picked. A stroke picked this way is the same selection as S makes (its bar, layer settings, nudges, delete, copy), so V is the one tool for "move this". A press on empty canvas lassoes strokes on the active layer. Alt drag drags a copy: the copy is made (duplicate in place, one step) when the drag first moves, and the drag moves the copy (two history steps). A, the point editor, says so when a click lands on a brush stroke: strokes are samples, not paths.
- Pen (P, M4 test): draws vector paths on a vector layer: a click places a corner, a drag pulls out symmetric handles, a click on the first point closes the path, Return finishes it open, Esc drops it, and another tool finishes it. The path is one
addnode op into the layer at the current frame, in the current colour: closed paths are filled (unless "fill" is off) and outlined (unless "outline" is off), open ones always outlined, at the width in the options bar. On other layers it refuses and says why; the brush says so on a vector layer. - Colour (M2): a hue ring with a saturation and value square, hex, alpha; the document palette as swatches (click picks, right-click removes, "add colour" adds the current one with an optional name, all as ops); the last 16 colours used, kept in the user's settings. Alt-click with the brush or fill tool picks the colour of the image under the pointer, shift alt-click that of the active layer.
- Fill tool (G, M2): click fills inside the lines of this layer, all visible layers or a chosen layer, with gap, tolerance, expand and opacity settings; drag a loop to lasso fill.
- Gradients in layer settings (M2): a shape's fill switches between none, solid, linear and radial; gradients edit their geometry and stops (position, colour, add, remove).
- Canvas mipmaps (M2): every uploaded tile brings its own mip chain (box filtered on the CPU, down to one pixel per tile), so zoomed-out views sample trilinearly instead of shimmering.
- Frames (M3): the canvas, painting, fills (their reference at that frame), selection, drag previews, notes and the shared selection all work at the current frame. Painting paints into the drawing exposed there (on a link into its source, which the timeline says), and painting on a blank frame starts a drawing there.
,and.step a frame, alt,and alt.jump to the previous and next drawing on the active layer, Home and End go to the first and last frame. The scene keeps drawings loaded across frames, so going back to a frame only recomposes it; a frame with drawings not loaded yet loads in a background frame job while the last frame stays on screen (drawings a job loaded before the document changed are not kept, and load again when needed; see the frame cache below). Drawings away from the current frame drop their replay checkpoints, and beyond 1 GB the least recently shown are evicted; a drawing changed from outside while it is not shown is evicted and reloads when its frame comes back. - Timeline panel (M3), along the bottom: a frame ruler with the playhead, one row per layer top first (groups fold, a mask row opens under its layer with
[m+]), each cel a block across its exposure (drawings blue or green for vector, links purple marked->c1), blanks empty. Click a cell to go to that frame and layer; drag on the ruler or on empty cells to scrub; drag the right end of a block to change its exposure (later cels of the layer move); drag a block by its first frame to move it. Buttons, the context menu and keys: new drawing (K), duplicate to the next frame (the copy is placed after the exposure, later cels move back), show a drawing here (a link, picked from the layer's drawings), unlink, delete, hold longer and shorter (=and-), insert a frame (I, shift for every layer) and remove one, fps and length fields, "+ paint" and "+ vector" layers. Every action is one op and one history step. A row of playback controls sits above the buttons: play, the loop range (drawn orange on the ruler), onion skin and its settings, the shift K exposure, and the dropped frames of the last play; each layer name has an onion dot at its right end. - Onion skin (M3): O turns it on and off; "onion settings" in the timeline sets before and after, drawings or frames, opacity, falloff and tint; the dot at the right of a layer's name in the timeline shows that layer's onion too (the active layer always shows its own while onion is on). The scene composes the onion rasters (the same
klad-rendercode as--overlay onion) when the frame, the active layer, a marked layer, the settings or a drawing they show change, and loads the drawings they need with the frame. The active layer's onion is part of the cached image of everything below it, so painting with onion on composes exactly what it composes without; marked layers' onions are drawn inside the below and above caches. The eyedropper and fills never see the onion. - Frame cache and stepping (M3): the frame shown is the scene's frame (painting, the timeline and the agent channel all use it), and moving to a frame only sets it. What the canvas plane (the live, tiled GPU texture) shows catches up separately: at once when the frame's drawings are loaded and no cached picture of it exists, else 150 ms after the last step, or immediately when the pen touches the canvas. Meanwhile the frame cache shows the frame: one GPU texture per distinct picture (8-bit, premultiplied, with a CPU-made mip chain), at display resolution (the power-of-two level that the zoom needs, full size at 100% and closer), keyed by a hash of everything the picture depends on (the layer tree at that frame, the version of every drawing it shows: stroke file hashes and node hashes, the onion's ghosts when onion is on, the brushes and the level). Holds and links share a key, so they share a texture. A picture is composed by a background job that loads the drawings it is missing (kept in the scene afterwards, under the 1 GB drawing budget) and composes all tiles; at most two jobs run, plus one for the frame you just moved to. After a step the next 4 frames in that direction are composed ahead. The cache is capped at 640 MB, least recently shown first out; after every change the pictures no frame's key names any more are dropped, so an edit costs only the frames it changes. While the frame you stepped to is not on screen yet, held-key repeats are ignored (a fresh press still counts), so a held
.shows every frame. While a mask is active with its red tint, frames are not cached. - Heavy documents (M4 test): nothing that grows with the document runs on the UI thread. Catching the canvas up (loading the frame's drawings, the onion, and the caches of everything below and above the active layer) is a background job (
Scene::canvas_request,CanvasRequest::run,Scene::adopt): one runs at a time, a result for a frame, active layer, revision or onion that is no longer wanted keeps only the drawings it loaded, and the next is asked for. The editor opens with nothing loaded and waits for the first job at most 400 ms; a pen press on a frame that is not ready waits at most 60 ms, then says the frame is still loading and draws nothing; clicking a layer or changing the onion only marks the canvas stale. After a catch-up the canvas tiles are composed and uploaded 64 per frame while the frame's picture stays on screen. Background work runs in its own thread pool with one core fewer than the machine has. Only the active drawing keeps replay checkpoints. A document whose frame loads more than 512 MB of drawings is heavy: it runs one picture job at a time, no prefetch, and loads the frame you stop on through the canvas job alone. Drawings evicted from memory are freed on a background thread. - Caches on disk for heavy documents (M4 test, round 2): three layers of cache, all automatic and all thrown away safely (
.cache/is never in git).- Pixels per drawing (
klad_brush::cache,.cache/tiles): the replayed raster (zstd) and its edit record (each mark's key and the tiles it touches), keyed by the stroke file, the brushes, the canvas size and the engine version, shared by the CLI and the editor. A hit rebuilds the drawing's replay without painting anything (CelReplay::with_marks); a drawing whose file changed replays only its changed marks from the record. The CLI writes it after every load, as it always did; the editor writes it after a replay of 30 ms or more, so small drawings never touch the disk. 2 GB per bundle, least recently used out first. - Frame pictures (
.cache/frames, one file per frame cache key, zstd of the 8-bit picture at its display level, mips rebuilt on load): written after a picture that took 30 ms or more to make, read instead of loading a frame's drawings. The canvas job writes the picture of the frame it prepares (in the background pool, from the rasters it already holds), so on a heavy document every frame you stop on is seen at once next time. Heavy documents ask for a picture of a frame, and prefetch, only when it is on disk. 1 GB per bundle. - Lean scenes: in a heavy document, once the canvas job has made the caches below and above the active layer, the other layers' pixels on the current frame are dropped (their strokes stay, so V still picks them). A drawing counts as loaded only with its pixels, so pictures and canvas jobs reload what they need from the disk cache. Edits on the active drawing never need the others (the caches below and above stand); an edit that would (a change on another layer, a vector or onion change, a structure change, a clip that makes the stack slow) marks the canvas stale and the canvas job redoes it. The eyedropper samples what is on screen, a fill that references other layers loads them from the disk cache first, a drag shows only its outline, and the canvas job hands over thumbnails before the pixels go.
- Buffered frames and prepare (round 3,
editor/buffer.rs): a strip along the top of the ruler shows, per frame, green when its picture is buffered (in the frame cache or on disk: it shows at once) and blue under it when its drawings are cached (every paint drawing of the frame holds its pixels in memory or a current pixel cache on disk: drawing there starts within seconds). A background survey works it out (stat of each picture file, the first 8 bytes of each drawing's cache file against the key of its stroke file, stroke files hashed again only when their size or time changed) whenever the revision, display level, onion, frame cache, held drawings or a disk write changes. "Prepare frames" (the lightning in the timeline header, or cmd K) buffers the loop range, else the clip under the playhead, else every frame, one frame at a time on a background thread (frames sharing a picture once): it loads each drawing through the pixel cache (writing it), makes the picture at the current display level and writes it, skips what is already there, keeps nothing in memory, shows its progress next to the button and in the status line, and stops after the current frame when pressed again. The skipped frames count; the summary says how many pictures and drawings were made. - Container numbers on
klad stress --frames 12at 4096 px (30 layers of 300 strokes): a frame never seen is ready to draw on after 8.5 to 10 s (the replay, now also writing the caches); after reopening, a frame seen before is on screen in 12 to 45 ms and ready to draw on in about 3 s (30 drawings from the disk cache, then the caches below and above); drawings in memory 450 to 680 MB, down from 3.3 to 6 GB; UI frames while loading median 3.4 ms, p95 8 ms, slowest 62 to 88 ms.
- Pixels per drawing (
- Clips (M3 batch 3): a strip above the frame numbers shows each clip as a bar (teal when it loops, amber when it plays once, with its name and its own fps), overlapping clips in lanes. Drag along empty strip to make a clip (named
clip1,clip2, ..., looping, at the document's fps); click a bar to pick it; drag a bar's end to move that end. The row under the playback controls edits the picked clip, or the one under the playhead: name, loops, own fps, delete. Each change is oneclipop and one history step. Clip edits change no pixels, so the frame cache keeps every picture. - Playback (M3): Return plays and stops. It plays the range marked on the ruler when there is one (shift drag on the ruler, or the "loop range" fields), else the clip under the playhead (the picked clip first when it holds the playhead) at that clip's fps, looping or once (a clip that plays once stops on its last frame; from its last frame it starts over), else the whole timeline at the document's fps. A clock started at play time picks the frame from the elapsed time (
floor(t x fps)), so playback never drifts; a frame whose picture is not ready yet is skipped and counted, and the timeline shows the dropped frames per loop. Playback shows pictures without onion, composes the loop ahead in the background and ends on the frame on screen. A pen touch on the canvas stops it. - Frame by frame (M3): shift K makes a new drawing right after the current exposure, on ones, twos or threes (the "shift K exposes on" setting), and moves there: an open-ended last drawing first gets a hold that ends where the new one starts, later drawings move back when the new one needs the room, and the timeline grows at the end. Holding Q and moving the pointer sideways flips through the frames around the one where Q went down (one frame per 22 px), from the frame cache; letting go stays there. Holding W shows the previous drawing of the active layer (the whole frame where it starts; in a loop range the first drawing's previous is the range's last) and letting go comes back. While Q or W is held the pen does not paint.
- Copy and paste (M3 batch 4): with the stroke tool (S), cmd C keeps the selected marks (with a cut lasso, every mark inside or crossing it, copied with that cut, so only the parts inside show; marks shift-added outside it whole) and puts a line of text on the system clipboard, because egui reports cmd V only when the clipboard holds something. cmd V (any tool) copies them into the active paint layer's drawing at the current frame (on a link, its source; on an empty frame, a new drawing), in place, as one history step (one or two
copyops in one batch), then selects the copies with S. - Timeline selection (M3 batch 4): shift click a cell to select from the playhead's cell (or the selection's first corner) to it, or shift drag over cells; the selection is a rectangle of frames over rows, drawn white. A click without shift or Esc clears it. Its context menu retimes it (on ones, twos or threes, fit into n frames, reverse, ping-pong, on the selected rows or on every layer) as one
retimeop, and makes in-betweens: the keys are the first row's drawing at the first selected frame and the last drawing starting inside the selection; count (or one per frame), spacing and pairing are menu fields. In-betweens, and "redo the in-betweens in the selection", runklad inbetweenas a background process of the same binary, like "export to Godot", and the editor reloads when it ends. In-between cels show lighter, their id starred. - Layers (M4 batch 3): one layer row (
editor/layers.rs) is drawn by the layers pane and by the timeline's names column: eye (alt click shows only that layer: every other layer hidden, its groups shown, the layers inside it as they were, one history step fromops::solo, also Layer > Show only this andklad solo; alt clicking it again restores what was shown before), lock, the kind icon, the name (double-click renames it in that row; Return keeps, Esc leaves), clip and lock alpha marks, a mask chip (click paints on the mask, alt click turns it on or off, right-click opens its row in the timeline), in the timeline the onion dot and a fold caret on groups, in the pane a 40 by 28 thumbnail of the layer at the current frame (box filtered from its tiles, alpha boosted by a square root so thin ink still shows, cached per drawing and document revision, made by a background job: a row shows its last thumbnail until the new one is ready). Dragging a row moves the layer: the top or bottom half of a row puts it above or below, the middle half of a group puts it inside (the row lights up), and a mask, a group into itself or a drop beside a mask is refused with the reason (drop_at); the drop is onemvop. The pane's buttons: new paint, vector or group layer above the active one, duplicate (the copy becomes active), put in a new group, delete; the active layer's opacity and blend sit in the pane's title row. Each is one history step. - Timeline layout and drags (M4 batch 3): the header is one toolbar row (fold, a frame field, transport, loop range and its fields, onion and its settings, shift K exposure, fps, length, zoom). Under it the selection toolbar (
editor/cells.rs): new drawing, duplicate, link (the layer's drawings as thumbnails), unlink, delete, hold shorter, the hold as a field, hold longer, insert and remove a frame on this layer or every layer, copy cells, paste cells as copies or as links, retime (a menu: on ones, twos, threes, fit into n, reverse, ping-pong, every layer), in-between, redo in-betweens, new clip. What a press on the grid starts is decided where the press began (press_atanddrag_of, tested): on the ruler it scrubs (shift marks the loop range), near a block's end it changes the hold, on the dot of a block's first cell it moves the block (the cursor is a hand there; since the M4 test only the dot, so a drag from the rest of that cell selects), on any other cell it selects (dragging extends over frames and rows). A hold drag or a move draws the block itself at its new length or place (the moved one faded where it was), not an outline; block labels stop before the grip lines at the block's end. A moved block is acelmoveop, so drawings it lands on are pushed along; alt left and right move the drawing under the playhead by a frame. Clicking a clip's bar opens the clip window (name, loops, own fps, first and last frame as fields, delete, the Godot folder and export). Copied cells are the drawings and holds of the selected rows and frames (or the drawing under the playhead), pasted at the playhead on their own layers ascelduporlinkops in one batch; a drawing that was a link stays a link. - In-between panel (M4 batch 4,
editor/between.rs): "in-between" (the selection toolbar, the context menu, cmd K) opens a window instead of a menu: the first selected row's two keys as thumbnails with their frames (a frame not loaded yet says so), one on every frame or a count, spacing with the chart an animator draws between keys (key ticks at the ends, a tick per in-between where the spacing puts it), pairing (id, order, nearest shape; parts both keys have are named, they pair first), marks in one key only (leave, pop, fade, draw-on), and "make the in-betweens", which runsklad inbetweenas a job (between::args). When the job ends its output is parsed into rows (between::report): each layer's pairs, parts and touching ends; an unpaired mark is a button that goes to the other key's frame, turns on the stroke tool and waits for one stroke to be picked, then makes the in-betweens again with that pair added to--pair(pair_from); a fill left out goes to its frame. "Check what a redo would remake" lists the in-betweens of the selection (or all) with their state from their marks' hash and authors (redo_rows): remade, drawn on by hand (keep them on top, the default; in-between them too; leave it) or edited (in-between it again, or leave it, the default); "redo them" runs oneklad inbetween --redo --only ... --keep-cels ... --force-cels ..., one history step. - History (M4 batch 4,
editor/history.rs): the History pane lists the redo stack (as "undone" with who made the step, farthest first), a "the document is here" marker and the undo stack, latest first: who (you for the editor, the agent for the CLI), what, how long ago. Clicking a row undoes or redoes as many steps as it takes to stand right after it (steps_to), timed in the status line. The list is read again when the document's revision changes. - Notes on the canvas (M4 batch 4,
editor/pins.rs): every open note is a pin, those of other frames dimmed with their frame, done ones on this frame checked in green. With the note tool a click on a pin opens its popover (the text to edit and save, done, remove, close); elsewhere it opens a popover for a new note at that spot ("pin it"). A right click on any pin, of this frame or a dimmed one of another, goes to its frame and selects it (an accent ring and its popover); Delete removes the selected note. The Notes pane lists the open notes (a click goes to the frame and opens the pin) and the done ones folded, each can be opened again; every note is one line, cut to the pane's width (a done note's "open again" is laid out first, at the right, so the row never runs past the pane), and "clear all" beside the done header removes the done notes (notes::clear_done,klad notes --clear-done). The editor watches.cache/notes.json, so the agent'sklad notes --doneshows at once. - Settings (M4 batch 4,
settings.rs,editor/prefs.rs): the settings file carries aversion(2; files without one, the M1 to M4 ones, load with the new fields at their defaults and are stamped 2),keys(command id to key labels such asshift D, only the changed ones),uiScale(0.75 to 2, egui's zoom factor, so every control grows with it) anddefaults(brush and size for new windows, the shift K exposure, onion before, after and opacity, the grey around the canvas). Settings is a modal (cmd , or klad > Settings…; Esc, the close button or a click outside closes it, except while a new key is being pressed) with a sidebar of five sections and one section in the body at a time (editor/prefs.rs,prefs::Section): Pen (the pressure bars, lightest, heaviest, curve and the response graph), Drawing (the brush and size new windows start with, how long shift K's drawings hold, onion skin, the grey around the canvas), Keys (search, change by pressing the key, no key, reset one or all; the list fills the body), Layout (interface size, the timeline, developer tools and with them the numbers, reset the layout) and Updates (this version, the daily check, check now). Each section is a two-column grid, the label in grey on the left. While the modal is open the editor's own keys do nothing except cmd , (the modal blocks the pointer, and now the keys too).commands::Bindingsholds the keys: a changed command's keys replace its first ones, a key another command already uses is refused and that command named (taken_by), holds (Q, W, space) keep their keys, and every key lookup (dispatch, hints, the palette, the strip's letters) goes through it. - Export to Godot (M3 batch 3): the clip row has a "Godot folder" field (the document's
export.godot; a typed folder is relative to the folder holding the bundle) and an "export to Godot" button, which runsklad export <bundle> --godot(with the typed folder and--storewhen it differs) as a background job of the same binary, so the CLI and the editor write the same files; its summary or error is a message. - CLI forms in the editor (M5, S5.25,
editor/checks.rs,editor/export.rs): refill this drawing and show gaps (the fill tool's options and the palette), fill like the first drawing (the timeline selection toolbar), a part name for the selected marks (layer settings for strokes, thepartop), show parts and show arcs of the selected mark or part over the clip (the palette), an export window (the document menu, cmd E: this frame, a layer, numbered frames or a sprite sheet, and Godot) and add a font file (the document menu and layer settings for text, with the macOS open panel). The text tool (T, S5.26,editor/text.rs): a click starts a text on the active vector layer (or a new one when it is committed), typing shows on the canvas at once as a picture drawn by the same renderer while the node stays out of the document (an existing node is hidden in memory while it is edited), and Esc, a click outside or another tool commits it as one edit; a double click on text with V or T edits it in place. While typing the canvas holds egui's keyboard focus, so command keys type instead of switching tools. The font picker (the tool's options and layer settings for text) lists klad's families drawn in their own face, the drawing's own files and, for a search, open families to download as a backgroundklad fonts --getjob. Paint with body (S5.23): a body slider at the top of the brush window, and relief in the effects of layer settings with a light dial (click or drag towards the light). Everything but the part name runs thekladbinary as a background job with the same arguments a person would type (crate::start::draw_binaryfinds it next to the editor, and next to the test binaries in tests), so the CLI and the editor do the same thing by construction; gaps and arcs read the command's--jsonand draw on the canvas until the next edit. The ops that draw from shapes (ink,light,hatch,paint,scatter) stay CLI only (principle 7). - Agent channel: the current selection and pinned notes are written to
.cache/selection.jsonand.cache/notes.jsonforklad selectionandklad notes; both carry the frame. - Vector layers are rasterised into tiles when opened and when their nodes change; per-tile composition then only draws one tile per layer.
History
Every change, from the CLI or the editor, first stores a history entry in .cache/history/undo/<seq>/: meta.json (author, summary, revision, the stroke files it touches), patch.json.zst (the change to doc.json) and files/ (the stroke files it is about to change, zstd). The patch is a list of changes found by comparing the document before and after: object keys that differ ({"at": "/layers/3/cels/0/nodes/17", "old": {"x": 10}, "new": {"x": 35}}, null meaning absent) and list splices where items were added, removed or moved ("index", the removed and the inserted items). Lists are compared by common prefix and suffix; when the middle has the same items by id and type, the comparison goes into each of them, so a node edit in an 18,000-node document is one small change. undo checks that every changed key and item is still what the step left (otherwise it stops with "the document no longer matches it" and changes nothing), applies the old values in place, restores the stroke files, writes the document as a new revision and moves the reversed patch to the redo stack; any new change clears redo. An undone or redone step keeps the author and time of the change it records (since the M4 test; before that an undo wrote the undoer, so the agent's step became the user's once undone and redone). The last 100 steps are kept. Entries from before M2 batch 3 hold a whole doc.json snapshot and still undo. The editor syncs only the cels a node-level patch touches.
Sync between CLI and editor
The agent may run in a Linux container while the editor runs on the macOS host, sharing the folder through a bind mount.
- Every change is an op appended to the op log in
.cache/, with the author andrev. - Writers write files atomically (temp file plus rename) and bump
revin.cache/copy.json. - Before a CLI edit writes, it checks that the drawing's files are the ones it read (
Bundle::ensure_unchanged: the size, modified time, inode and change time ofdoc.json, the stroke files and the weights, taken before reading; a few milliseconds for 400 files, no file is read); when another writer or agit checkoutgot there first it writes nothing, says "the document changed while this edit was being made", and exits with code 75. Edits computed before the transaction (in-betweens, fills like another drawing) are the ones with a real window; the editor's job list runs them again.DRAW_TEST_WRITE_DELAY_MSmakes the CLI wait that long before its check, for the test that edits in the middle. - The editor watches the bundle. When its files differ from the ones it last read or wrote, it reloads, whoever changed them: the CLI, an agent or a
git checkout. Disk caches are keyed by those files (render names) or by the bytes of each stroke file (tiles), never by a counter, so nothing stale is drawn after a checkout. - Undo and redo work on the shared log, so the human can undo an agent edit and the other way round.
- M0 verifies file events and atomic renames across the OrbStack mount in both directions.
Exports
- PNG of the image, a layer or a group at a frame, at any scale from 1/16 to 8, transparent (see Pixels and compositing).
- Animations (M3 batch 3) take a spec:
all(every clip, or the whole timeline as one animationdefaultwhen there are no clips), a clip name, or a rangea-b. Each frame of them is rendered as in a PNG export (scale, depth,--layer,--background); frames showing the same drawings are composed once, and pictures with identical pixels (after dithering) are kept once, so holds, links and repeats share a picture. A picture is trimmed to its pixels with alpha (an empty one keeps one transparent pixel). An animation is a list of exposures: runs of consecutive frames showing the same picture, each with its length in frames and its duration in ms at the animation's fps, rounded so that the durations add up to the animation's length (round(end x 1000 / fps) - round(start x 1000 / fps)). - Sprite sheets (
--sheet): pictures in order of first appearance are packed in rows (shelves) with--paddingpx around each, at the width among a few candidates that gives the most compact last page, starting another page when the next row would pass--max. Pages are<name>.png,<name>-2.png, ...; a re-export removes pages it no longer needs. The JSON (<name>.json) is Aseprite's array layout:frameslists the exposures of each animation in turn (filename"<clip> <frame>",framethe rect in the page,trimmed,spriteSourceSizethe trim,sourceSize,durationin ms, andimagewhen the page is not the first), andmetahasapp,version,image,format(RGBA8888, orRGBA16161616for 16-bit),size,scale,frameTags(per clip:name,fromandtoindexingframes,directionforward,repeat"1"for clips that play once) and, with several pages,images. Readers of Aseprite JSON take single-page sheets as they are. - Numbered frames (
--frames): one full-size PNG per frame in order, holds repeated (<clip>-0000.png, ...), in a folder next to the bundle unless-o. - Godot (
--godot): into the folder (given, orexport.godot; the first folder given is kept in the document as one history step,--storereplaces a kept one) go the sheet pages,<name>.tresand<name>.tscn. The.tresis aSpriteFrameswith anext_resourceper page (by a path relative to the.tres, and the page's uid from its.png.importonce Godot has imported it), anAtlasTextureper picture (regionits rect in the page,marginits trim: offset and the rest of the full size, so every frame is the canvas size and lines up), and one animation per clip (ordefault) with its name,speed(fps),loopand per-frameduration(the exposure's length in frames). The.tscnholds anAnimatedSprite2Dusing it,centered = falseandoffsetthe negated origin at the export scale, autoplaying the first animation. Uids of the.tresand.tscnare read back from the files a re-export replaces (new ones come from a hash of the file's path, in Godot's alphabet), so scenes that use them keep working. A container test imports an export in headless Godot (4.6 in the container) and checks names, frame counts, durations, loops, the offset and that the old uids still load after a re-export. - Timings (container): the bounce sheet in about 0.25 s; a Godot export of 40 distinct frames of a 1024 canvas (4 layers, 60 strokes each) 2.3 s cold, 1.4 s warm, most of it PNG encoding of the 3080 px pages.
- Later:
Parallax2Dscenes (M6),Skeleton2Drigs (M6), SVG for vector layers.
Milestones
| Goal | |
|---|---|
| M0 | Prototype that proves the risky parts |
| M1 | Layers with time in the model, vector layers, the agent CLI loop, editor basics, sync |
| M2 | Drawing: brush engine with inking, pencil and fill, stroke editing, masks, blend modes |
| M3 | Frame-by-frame animation: timeline, onion skin, playback, clips, sprite sheet and Godot export |
| M4 | The editor, usable: docked panels, a look, tool strip, layers panel, timeline toolbar, status and progress, command palette, pen-sized targets |
| M4.5 | The agent's hand: ink, flats, shade, rim and texture from vector shapes; arcs and spacing checks, parts, in-betweens that keep hand work |
| M5 | Painting and the look: textured and wet brushes, adjustments, filters, light, depth fog, generators, text, image layers |
| M6 | Rigs and scenes: cut-out parts, bones, re-posing drawings, keyframes, parallax scenes |
| M9 | Pixel art: pixel layers of marks bound to the palette, a sharp view, pencil and shapes on the grid, text grids for agents, palette swaps, sharp exports, Aseprite files, checks and a pixel art skill |
Risks M0 retires
- Pen pressure and tilt in a native Rust window on macOS. Fallback: read them from
NSEventthroughobjc2. - Live brush latency on the CPU at 120 Hz with large textured brushes, and replay speed. Fallback: a GPU brush engine, giving up exact parity with agent renders.
- A 4k canvas with 30 layers panning and zooming smoothly.
- CLI render time on a real document in the container.
- File events and atomic writes across the container mount.
Out of scope for now
3D, an iPad app, a Windows or Linux editor, image-model layers, multi-human collaboration.