A drawing app built for agent/human collaboration
Rust
Guides: recipes for the editor, with pictures rendered from the samples
Indicode BVe2b465d80ec1
diff --git a/CLAUDE.md b/CLAUDE.mdindex cd334bc..86b8af3 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -8,7 +8,7 @@ Agent-first 2D art application in Rust: a `klad` CLI for agents and a native edi- Rust stable through rustup with clippy and rustfmt (`rust-toolchain.toml`), `just` for recipes. `just` builds into a folder per platform, `target/` on macOS and `target/linux` (or `target/windows`) elsewhere, whatever `CARGO_TARGET_DIR` says, so a checkout shared between a Mac and a Linux machine never mixes their binaries (`KLAD_TARGET_DIR` overrides it); `just build` ends by running the binary, so a binary for the wrong platform fails there. Run cargo from the repository root, with `CARGO_TARGET_DIR` set to the same folder when calling cargo directly.- The editor (`crates/app`, `klad open`) runs on macOS for now. It compiles and its tests run on Linux too; `klad open` exists only in the macOS build.-- The editor's panels run headless in tests through `egui_kittest` (`Editor::open` needs no GPU): click, type, drag, read sizes and accessible names. `just ui-pictures` and `cargo test -p klad-app -- --ignored start_pictures` render the UI into `scratch/ui/` with a blank canvas; `editor_picture` draws the canvas too (the kittest renderer gets the canvas resources, and the canvas is redrawn once it has caught up, since uploads made in a pass kittest did not render are lost). `just ui-time` measures UI work per frame; `just drag-time` (or `just drag-time <bundle>`, which drags in a copy) measures drags on a generated poster-like drawing: how often the preview updates, the release frame and what follows it, and a layer switch.+- The editor's panels run headless in tests through `egui_kittest` (`Editor::open` needs no GPU): click, type, drag, read sizes and accessible names. `just ui-pictures` and `cargo test -p klad-app -- --ignored start_pictures` render the UI into `scratch/ui/` with a blank canvas; `editor_picture` draws the canvas too, and `guide_pictures` renders the editor pictures in `docs/guide/` from the built samples (copy them from `scratch/ui/guide/` to `docs/images/guide-*.png`) (the kittest renderer gets the canvas resources, and the canvas is redrawn once it has caught up, since uploads made in a pass kittest did not render are lost). `just ui-time` measures UI work per frame; `just drag-time` (or `just drag-time <bundle>`, which drags in a copy) measures drags on a generated poster-like drawing: how often the preview updates, the release frame and what follows it, and a layer switch.- `cargo test -p klad-app` alone does not rebuild the `klad` binary that the job and thumbnail tests run; `just test` (the workspace) does.- macOS-only code (`crates/app/src/pen.rs`, `crates/app/src/picker.rs`) can be type-checked from Linux with `rustup target add aarch64-apple-darwin` and a small scratch crate holding the module and its objc2 dependencies (`cargo check --offline --target aarch64-apple-darwin`); the full workspace cannot, `zstd-sys` needs the macOS SDK.diff --git a/README.md b/README.mdindex 61a416a..945eea6 100644--- a/README.md+++ b/README.md@@ -43,6 +43,8 @@ Early, and open for testing. What works today:+The guides in `docs/guide/` show how to paint, select, fill, animate, rig and export in the editor, one recipe at a time, starting with [Getting started](docs/guide/getting-started.md).+## Try it- macOS and Windows: signed installers will be sold on itch.io and Steam, under the same licence as the source (see [Licence](#licence)). Until then, build klad from source as below.diff --git a/crates/app/src/editor/ui_tests.rs b/crates/app/src/editor/ui_tests.rsindex 6e86436..9c31778 100644--- a/crates/app/src/editor/ui_tests.rs+++ b/crates/app/src/editor/ui_tests.rs@@ -3878,3 +3878,85 @@ fn check_now_in_about_says_what_the_releases_feed_holds() {);let _ = std::fs::remove_file(&feed);}++type Moment = fn(&mut Editor) -> anyhow::Result<()>;++#[test]+#[ignore]+fn guide_pictures() {+ let root = Path::new(env!("CARGO_MANIFEST_DIR")).join("../..");+ let samples = std::env::var("KLAD_SAMPLES").map_or_else(|_| root.join("samples"), PathBuf::from);+ let out = root.join("scratch/ui/guide");+ std::fs::create_dir_all(&out).unwrap();+ let moments: [(&str, &str, &str, Moment); 5] = [+ ("painting", "lemons/lemons.klad", "lemon-a", |ed| {+ ed.invoke(Cmd::Brush)?;+ ed.pick("oil");+ Ok(())+ }),+ ("animation", "creature/creature.klad", "lines", |ed| {+ ed.go_to(16)?;+ ed.invoke(Cmd::Onion)+ }),+ ("bones", "rig/rig.klad", "figure", |ed| ed.invoke(Cmd::BoneTool)),+ ("brush", "lemons/lemons.klad", "lemon-a", |ed| {+ ed.pick("oil");+ ed.invoke(Cmd::BrushWindow)+ }),+ ("selection", "lantern/lantern.klad", "lines", |ed| {+ ed.tool = Tool::Strokes;+ ed.select_all_strokes();+ Ok(())+ }),+ ];+ moments.iter().for_each(|(name, sample, layer, moment)| {+ let source = std::fs::canonicalize(samples.join(sample))+ .expect("run just samples first, or point KLAD_SAMPLES at built samples");+ let dir = std::env::temp_dir().join(format!("draw-guide-{name}-{}", std::process::id()));+ let _ = std::fs::remove_dir_all(&dir);+ std::fs::create_dir_all(&dir).unwrap();+ let path = dir.join(source.file_name().unwrap());+ let copied = std::process::Command::new("cp")+ .arg("-R")+ .arg(&source)+ .arg(&path)+ .status()+ .unwrap();+ assert!(copied.success());+ let gpu = egui_kittest::wgpu::create_render_state(+ egui_kittest::wgpu::default_wgpu_setup(),+ egui_wgpu::RendererOptions::PREDICTABLE,+ );+ let mut settings = Settings::default();+ settings.layout.timeline_height = 210.0;+ let mut first = crate::home::Home::with(settings, None, Some(gpu.clone()));+ first.open(&egui::Context::default(), &path).unwrap();+ let mut h = Harness::builder()+ .with_size(vec2(1600.0, 1000.0))+ .renderer(egui_kittest::wgpu::WgpuTestRenderer::from_render_state(gpu))+ .build_ui_state(|ui, home: &mut crate::home::Home| home.frame(ui), first);+ let settle = |h: &mut Harness<'static, crate::home::Home>| {+ let started = std::time::Instant::now();+ while !h.state().editor.as_ref().unwrap().canvas_current() && started.elapsed().as_secs() < 180 {+ h.step();+ h.render().unwrap();+ std::thread::sleep(std::time::Duration::from_millis(20));+ }+ h.state_mut().editor.as_mut().unwrap().redraw_canvas();+ (0..8).for_each(|_| {+ h.step();+ h.render().unwrap();+ });+ };+ settle(&mut h);+ let ed = h.state_mut().editor.as_mut().unwrap();+ let id = ed.scene.bundle.doc.find_layer(layer).unwrap().id.clone();+ if let Some(klad_core::doc::Loc::Layer(at)) = ed.scene.bundle.doc.locate(&id) {+ ed.activate(at).unwrap();+ }+ moment(ed).unwrap();+ settle(&mut h);+ h.render().unwrap().save(out.join(format!("{name}.png"))).unwrap();+ std::fs::remove_dir_all(&dir).unwrap();+ });+}diff --git a/docs/guide/animating.md b/docs/guide/animating.mdnew file mode 100644index 0000000..98fff51--- /dev/null+++ b/docs/guide/animating.md@@ -0,0 +1,56 @@+# Animating frame by frame++++## Read the timeline++The timeline runs along the bottom of the window: a ruler with the playhead, then one row per layer, top layer first. Each drawing is a block that runs across the frames it shows on (blue on paint layers, green on vector layers). A purple block marked `->c4` is a link: it shows a drawing from earlier in the row again. Clips sit in a strip above the frame numbers.++Click a cell to go to that frame and layer, and drag on the ruler to scrub.++## Draw the next frame++- **shift K** makes a blank drawing right after the current one and takes you there. The "shift K on" buttons in the timeline header pick whether it holds for 1, 2 or 3 frames, for animating on ones, twos or threes.+- **K** makes a blank drawing on the frame you're on.+- Painting on an empty frame starts a drawing there too.++## Step through frames++- **,** and **.** go a frame back and forward; alt , and alt . jump to the previous and next drawing on the active layer; Home and End go to the first and last frame.+- Hold **Q** and move the pen sideways to flip through the drawings around this one, like the corner of a stack of paper. Let go to stay on the frame you reached.+- Hold **W** to see the previous drawing, and let go to come back.++## Onion skin++O turns onion skin on and off: the drawings before show in red and the ones after in green, under the active layer. The onion settings in the timeline header set how many to show before and after, whether to count drawings or frames, and their opacity, falloff and tint. The dot at the right end of a layer's name shows that layer's onion as well.++## Change the timing++- **=** and **-** make the drawing under the playhead hold a frame longer or shorter. Later drawings move along.+- Drag the right end of a block to change its hold, or drag the dot on its first cell to move it. Alt left and alt right move it a frame at a time.+- **I** inserts a frame in the active layer and **shift I** in every layer; the remove buttons next to them take one out.++## Reuse a drawing++"duplicate to the next frame" copies the drawing right after itself, with the same stroke ids, so you can change the copy into the next pose. "show a drawing here" links one of the row's drawings at this frame: drawing on either changes both. "unlink" makes a link a drawing of its own.++## Play it++Return plays and stops. It plays the loop range when there is one (shift drag on the ruler, or the loop button), otherwise the clip under the playhead, otherwise the whole timeline, at the fps in the timeline header. If frames drop, the lightning button ("prepare frames") buffers the range first; the strip along the ruler turns green where frames are ready to show at once.++## Make clips++A clip is a named range of frames, like idle, walk or attack, and an export turns each clip into its own animation. Drag along the empty strip above the frame numbers to make one. Click its bar to name it and set whether it loops, its own fps and its first and last frame.++## Retime frames++Shift click a cell, or shift drag over cells, to select frames on one or more rows. The selection bar retimes them on ones, twos or threes, fits them into a number of frames, reverses them or adds them again backwards as a ping-pong, on the selected rows or on every layer. It also copies cells and pastes them as copies or as links.++## Let klad draw the in-betweens++1. Draw two keys on a row with empty frames between them. Name the parts of each key (a leaf, the near leg) under "part" in layer settings ([Selecting](selecting.md)): in-betweens pair strokes part by part, so keys drawn separately still match up.+2. Click the first key's cell, then shift click the second key's cell to select both and the frames between them.+3. Click "in-between" in the selection bar. The window shows both keys and asks how many drawings to make (or one on every frame), how they're spaced, with the chart an animator draws between keys, and what to do with strokes that are only in one key: leave them out, pop them, fade them or draw them on.+4. Click "make the in-betweens".++In-betweens show lighter in the timeline and their ids carry a star. The window then lists any stroke that found no partner; click it, pick its partner in the other key and the in-betweens are made again with that pair. When you change a key later, "redo the in-betweens" remakes them, and keeps what you drew on top of any of them unless you say otherwise.diff --git a/docs/guide/bones.md b/docs/guide/bones.mdnew file mode 100644index 0000000..8d521ac--- /dev/null+++ b/docs/guide/bones.md@@ -0,0 +1,27 @@+# Posing with bones++Instead of redrawing a character on every frame, you can draw it once, give it a skeleton and pose it. The skeleton belongs to a layer or a group, and moves every layer in that group together.++++## Draw a skeleton++1. Put the character's layers (lines, colour, shading) in a group and make the group the active layer.+2. Press J for the bone tool, with "draw" picked in the bar over the canvas.+3. Drag on empty canvas to draw the first bone. The chain carries on from its end: each click adds the next bone, and Esc ends the chain.++Drag a bone's end or middle to move it, and alt drag from a bone's end to start a child chain there. The skeleton list in the bar picks a bone by name, renames it (Return keeps the name) and changes the bone it hangs from.++## Paint how much each bone moves the drawing++Switch to "weights". "automatic weights" gives every bone a first set of weights by distance. Cmd click a bone to pick it, then paint its weight onto the drawing: size sets the brush's radius and weight how much each dab gives, and alt paints the weight away. "smooth" blurs every bone's weights a little. Hold rigid things, like a head or a hand, with full weight on one bone, so they don't bend.++## Pose it++Switch to "pose", go to a frame and drag a bone's end to turn it; its children follow. "make this pose a drawing" bends the drawing on this frame into the pose, and "back to rest" drops the turns, the move and the targets of this pose. Poses of the same drawing in-between on the bones ([Animating](animating.md)), so a limb swings around its joint instead of sliding.++## Let a limb reach (IK)++Pick the lower bone of a limb, say a shin, and click "make it a limb with" its parent. In pose mode, dragging the shin's end now turns both bones so the end reaches where you drag, bending the way the leg is drawn, or the other way if you switch it to bend clockwise or counterclockwise. Softness keeps the knee from snapping straight near full reach. "make it an aim" turns one bone alone to point at the target instead. For a pose where you'd rather turn the bones by hand, switch the limb off for that pose, or hold alt while you drag.++A planted foot is a target that stays where it is while the body moves, which is most of a walk cycle.diff --git a/docs/guide/exporting.md b/docs/guide/exporting.mdnew file mode 100644index 0000000..f04f577--- /dev/null+++ b/docs/guide/exporting.md@@ -0,0 +1,28 @@+# Exporting++## Export a picture or frames++File > Export (cmd E) opens the export window, which writes the same files as `klad export`:++- **image**: the frame you're on as one PNG, the whole image or one layer or group, at any scale. It's transparent unless you tick "keep the background colour".+- **frames**: numbered PNGs, one per frame, for all frames, a clip or a range like 0-11.+- **sprite sheet**: one PNG holding each distinct picture once, trimmed to its pixels, and a JSON file in Aseprite's layout with a tag per clip. Holds and links share their picture. Padding and the largest page size are settings; more frames go on more pages.+- **Godot**: the sheet, a SpriteFrames resource with one animation per clip at its own speed and loop, and a scene with an AnimatedSprite2D. "as a rig" exports a Skeleton2D with the drawing's parts and an AnimationPlayer with the poses ([Posing with bones](bones.md)); "as a parallax scene" exports each top-level layer as a texture on a Parallax2D that scrolls by its depth.++An empty path writes next to the drawing; a relative path counts from the drawing's folder.++## Export straight into a Godot project++Click a clip's bar in the timeline, type the folder in your Godot project under "Godot folder" and click "export to Godot". The folder is kept in the drawing, so later exports go to the same place. Re-exports keep Godot's ids for the files, so scenes that use them keep working.++## From the command line++The same exports, for a build script or an agent:++```sh+klad export art.klad --scale 2+klad export art.klad --sheet all+klad export art.klad --godot ../game/art/hero+```++Every option is in the [command reference](../cli.md#klad-export).diff --git a/docs/guide/filling.md b/docs/guide/filling.mdnew file mode 100644index 0000000..406eede--- /dev/null+++ b/docs/guide/filling.md@@ -0,0 +1,25 @@+# Filling++## Fill inside lines++Press G and click inside closed lines. The bar over the canvas sets what the fill looks at:++- **reference**: this layer, all visible layers, or a layer you pick. Flat colour usually goes on its own layer under the lines, filled with the lines layer as the reference, so the colour never covers the lines.+- **gap**: closes openings in the lines up to that many pixels wide.+- **tolerance**: how different a pixel may be from the one you clicked and still be filled.+- **grow**: how far the fill reaches under the lines, so no paper shows between line and colour.+- **opacity**.++klad keeps a fill as a fill, not as pixels mixed into the layer, so you can pick it up with S like a stroke, recolour it and delete it.++## Fill a shape you draw++With G, drag a loop instead of clicking: the area inside the loop is filled.++## Fill again after the lines changed++When you move or redraw lines, find "refill this drawing" with cmd K: it makes the drawing's fills again from where you clicked them. "show gaps" outlines the closed areas that no fill covers yet.++## Colour every frame of an animation++Fill the first drawing, select it and the frames after it in the timeline, and run "fill like the first drawing" from the timeline's selection bar. klad finds each fill's area in the other drawings by its shape and fills it there.diff --git a/docs/guide/getting-started.md b/docs/guide/getting-started.mdnew file mode 100644index 0000000..4e4b5ca--- /dev/null+++ b/docs/guide/getting-started.md@@ -0,0 +1,52 @@+# Getting started++klad is a drawing, painting and animation app. You can do everything in these guides by hand, with a pen or a mouse; an agent is something you add when you want one ([Working with an agent](with-an-agent.md)).++Keys are written the way a Mac shows them. On Windows and Linux, cmd is ctrl.++## Get klad++Signed builds for macOS and Windows will be sold on itch.io and Steam. Until then, and on Linux, [build klad from source](https://github.com/klad-app/klad#from-source); the first build takes about ten minutes. A build holds the editor, the `klad` command line tool, about fifty open fonts and six sample drawings.++The editor is most complete on macOS, where the pen gives pressure and tilt. On Windows it's a first version with pressure but no tilt, and on Linux you draw with the mouse for now.++## Make a drawing++++1. Start klad. The start window lists your recent drawings and the samples.+2. Press cmd N, give the drawing a name and pick its folder, size and background.+3. Press B and paint.++There's no save command: every change is written to the drawing as you make it. A drawing is a folder whose name ends in `.klad`, holding plain files, so you can copy it, zip it or put it in a shared folder. cmd W closes it and takes you back to the start window.++To open a sample, click its card. klad copies it into your drawings folder and opens the copy, so the sample stays as it was. Help > First steps walks you through drawing a shape, filling it and handing the drawing to an agent.++## Find your way around++The tools sit in a strip on the left, each with its key letter in the corner. On the right is the dock with its panes: colour and brush, layers, layer settings, notes for the agent, and history. The timeline runs along the bottom, and the status line under it says what just happened and where your next stroke will go ("draws into c12 on lines, frames 4 to 7").++- **cmd K** finds any command: type a few letters of what you want to do. Commands that can't run right now are greyed out, with the reason.+- **?** lists every key. Change them in the settings (cmd ,), under Keys.+- **Tab** hides every panel; **shift Tab** hides only the dock. A pane you closed comes back from the Window menu.++## Move around the canvas++| To | Do |+|---|---|+| Pan | Hold space and drag, or drag with the middle button |+| Zoom | Pinch, or hold cmd and scroll |+| See the whole canvas | F |+| See it at 100% | 1 |+| Turn the view | R and shift R, 15 degrees at a time |+| Check the drawing mirrored | H (the drawing itself doesn't change) |++The zoom in the status line also takes a click for 100% and a double click to fit, and a click on its rotation turns the view upright again.++## Undo++cmd Z undoes and cmd shift Z redoes, whether the change was yours or an agent's. The History pane lists the last hundred steps with who made each one; click a row to go straight back to that point.++## Tune your pen++Open the settings (cmd ,) and the Pen section, then press on the tablet: two bars show the pen's raw pressure and the pressure your strokes record. If your hardest press never reaches full pressure, press as hard as you'd ever draw and click "heaviest = my peak". Lightest sets the raw pressure that counts as the lightest touch, and the curve makes light presses record heavier (below 1) or lighter (above 1).diff --git a/docs/guide/layers.md b/docs/guide/layers.mdnew file mode 100644index 0000000..080a2b6--- /dev/null+++ b/docs/guide/layers.md@@ -0,0 +1,40 @@+# Layers, masks and clipping++## Add a layer++The buttons at the top of the Layers pane add a layer above the active one:++- **paint** for brush strokes and fills;+- **vector** for rectangles, ellipses, paths and text ([Shapes, paths and text](shapes-and-text.md));+- **group** to hold other layers;+- **adjust** for an adjustment layer: it starts as curves, and layer settings switch it to levels, hue, colour balance, a gradient map or a colour fill. It changes what is under it in its group.++The same pane duplicates the active layer, puts it in a new group and deletes it. cmd Z brings a deleted layer back.++## Pick, rename and reorder layers++Click a row to make that layer the active one. Double-click its name to rename it: Return keeps the new name, Esc leaves the old one. Drag a row to move the layer: drop it on the top or bottom half of another row to put it above or below, or on the middle of a group to put it inside.++## Show, hide and lock++The eye shows and hides a layer. Alt click an eye to see only that layer; alt click it again and everything comes back as it was. A locked layer can't be picked or painted on.++## Opacity and blend mode++The active layer's opacity and blend mode sit in the Layers pane's title row. Multiply is the usual one for shading, screen and add for light.++## Clip a layer to the one below++Tick "clip to layer below" in layer settings and the layer only shows where the layer under it has paint. This is how shading stays inside flat colour: flat colours on one layer, a multiply layer for the shadows and a layer for the rim light above it, both clipped.++## Paint only where there's paint already++"lock alpha" in layer settings makes new strokes and fills land only where the layer already has paint. A big soft stroke over line art then recolours just the lines. Turn it off again when you're done, or your next strokes on that layer will seem to vanish.++## Hide parts of a layer with a mask++"add mask" gives the layer an empty mask, and "add mask hiding all" one that hides everything. While you paint on the mask, your strokes hide the layer and the eraser shows it again, and what's hidden is tinted red so you can see it. The mask has a chip in the layer's row: click it to paint on the mask, and use "back to the layer" to paint on the layer itself again. Alt click the chip to turn the mask off and on.++## Trace over a picture++"import a picture" in the File menu (or dropping a PNG or JPEG on the window) places it on a new layer. Tick "reference" in its layer settings: you keep seeing it while you draw, but it stays out of exports.diff --git a/docs/guide/meta.json b/docs/guide/meta.jsonnew file mode 100644index 0000000..520c442--- /dev/null+++ b/docs/guide/meta.json@@ -0,0 +1,4 @@+{+ "title": "Guides",+ "pages": ["getting-started", "painting", "layers", "selecting", "filling", "shapes-and-text", "animating", "bones", "exporting", "with-an-agent"]+}diff --git a/docs/guide/painting.md b/docs/guide/painting.mdnew file mode 100644index 0000000..9b41bb3--- /dev/null+++ b/docs/guide/painting.md@@ -0,0 +1,52 @@+# Painting++++## Paint a stroke++Press B for the brush and paint on the canvas. The stroke goes into the active paint layer at the current frame; the status line says which drawing it lands in. On a vector layer the brush won't paint and tells you so: pick a paint layer in the Layers pane, or add one.++## Pick a brush++The bar over the canvas holds the brush picker, and the colour and brush pane shows the same brushes as tiles, each with a sample stroke. klad comes with 23 brushes and an eraser. Inking pen, Pencil and Marker are for line work. Oil, Loaded oil, Round bristle, Flat bristle and Dry brush are for painting. Wet round, Smudge and Blender mix and push the paint already on the layer, and Leaves, Grass and Splatter stamp little pictures along the stroke.++The mixing brushes only read the layer they paint on, so put the colours you want to mix on one layer.++## Change the size, opacity and flow++The bar has sliders for size, opacity and flow. [ and ] make the brush smaller and bigger. To size it right on the canvas, hold cmd alt and drag sideways: the circle shows the size, and it doubles for every 120 points you drag.++"more" opens hardness, the size at the lightest press, the pressure curve, the taper at both ends, a stabiliser and smoothing.++## Erase++E switches between the brush and the eraser, and the eraser end of the pen erases too. On a layer with lock alpha on, the eraser does nothing (see [Layers](layers.md)).++## Pick colours++- The hue ring and the square in the colour and brush pane pick the colour; the hex field and the alpha slider sit next to them.+- The palette belongs to the drawing. Click a swatch to use it, drag swatches to reorder them, and right-click one (or its x) to remove it. "add colour" adds the current one, with a name if you type one.+- The two squares under the tools in the strip are the current colour and the one before it. X, or a click on them, swaps them.+- Hold alt and click to pick the colour under the pointer. With shift alt it reads only the active layer.++## Make your own brush++++F5, or "edit" in the brush bar, opens the brush editor with a live sample stroke at the top. From there you set:++- the tip: round, chalk or a picture, with its hardness, spacing, roundness and angle (fixed, or turning with the stroke or the pen's tilt), and jitter and scatter for each dab;+- a dual tip and a texture;+- how pressure and tilt change the size, flow and opacity, and the curve between the lightest and the heaviest press;+- colour dynamics;+- the kind of paint: dry, wet (picks up and mixes the colour under it), smudge or blend, and body.++Give it a name and click "save in this drawing". A drawing keeps every brush its strokes use, so it looks the same on any machine and the brush travels with it.++## Thick paint++Brushes with body, such as Oil and Loaded oil, lay paint with a height: ridges along the bristles and lips at the edges. The height only shows once the layer has a relief effect. In layer settings, add relief under the effects and click or drag on the light dial towards where the light comes from. Use a strong relief for a figure or fruit and a light one for a wall or a table.++## Paint in mirror++Turn on "mirror" in the brush bar to paint every stroke and its mirror image across an upright line at the same time. Both land as ordinary strokes, so you can change either one afterwards.diff --git a/docs/guide/selecting.md b/docs/guide/selecting.mdnew file mode 100644index 0000000..cf2ed9c--- /dev/null+++ b/docs/guide/selecting.md@@ -0,0 +1,41 @@+# Selecting and changing strokes++A stroke stays a stroke after you draw it: klad keeps its path, its pressure, its brush and its colour. So you can pick up any stroke later, yours or an agent's, and move it, recolour it or bend it, and klad paints it again.++++## Move something++Press V, then press on what you want to move and drag. V picks whatever you see under the pen, a brush stroke or a vector shape, and makes its layer the active one. Alt drag drags a copy and leaves the original where it was. A drag that starts on empty canvas lassoes strokes on the active layer.++## Select strokes++Press S, then:++- click a stroke to select it, and shift click to add or remove more;+- drag a loop around strokes to lasso them;+- press cmd A for every stroke and fill of the active layer at this frame.++In the bar over the canvas, "this layer" and "all layers" decide whether a click picks only on the active layer or on whatever layer shows paint there. With "a lasso cuts strokes at its edge" on, a lasso also takes the parts of strokes that cross it, and the first change splits them there; with it off, it takes only strokes that lie wholly inside.++## Change the selection++The selection shows a box. Drag inside it to move, a corner to scale, an edge to stretch (past the opposite edge it flips) and the knob to turn. The arrow keys nudge it 1 px, or 10 px with shift.++The bar next to the selection flips it, turns it a quarter turn, recolours it with the current colour, makes the strokes thinner or thicker, sets their opacity, copies, pastes, duplicates in place (cmd D), deletes (Backspace) and drops the selection (Esc). Each of these is one step in the history.++## Copy and paste strokes++With strokes selected under S, cmd C keeps them and cmd V pastes copies into the active layer at the current frame, in the same place. On a frame with no drawing yet, the paste starts one.++## Work on several layers at once++In the Layers pane, cmd click or shift click other paint layers to add them to the active one; they get a blue edge. S then selects on all of them, and the selection moves, turns, recolours and deletes as one change, with every stroke staying on its own layer.++## Bend a stroke++Press A and click a stroke or a vector shape to show its points. Drag a point or a handle to change the path; a brush stroke keeps its pressure along the new path, so its taper and weight stay where they were. Alt click on the outline adds a point, alt click on a point switches it between a corner and a smooth point, and alt drag on a handle breaks it from its partner. Backspace removes the selected points. Layer settings also make points corners or smooth and simplify a path.++## Name parts++Select the strokes of one piece (a leaf, a leg), type a name under "part" in layer settings and click "make them this part". Parts are how in-betweens know which strokes belong together ([Animating](animating.md)).diff --git a/docs/guide/shapes-and-text.md b/docs/guide/shapes-and-text.mdnew file mode 100644index 0000000..1b5bda4--- /dev/null+++ b/docs/guide/shapes-and-text.md@@ -0,0 +1,29 @@+# Shapes, paths and text++Shapes, paths and text live on vector layers. Add one with "vector" in the Layers pane. Their points stay editable, they stay sharp at any size, and they can be filled with gradients.++## Draw rectangles and ellipses++Press U and drag. Shift makes a square or a circle, alt draws from the centre, and rectangles can have rounded corners. The fill is the current colour and the outline the second one, at the width in the bar over the canvas.++## Draw paths++Press P. Click to place a corner, drag to pull out a curve, click the first point to close the path, Return to finish it open, Esc to drop it. Closed paths are filled and outlined, open ones outlined; "fill" and "outline" in the bar turn either off.++## Change points++Press A and click the shape. Drag points and handles; alt click on the outline adds a point, alt click on a point switches it between corner and smooth, alt drag on a handle breaks it. A rectangle or an ellipse becomes a path the moment you change a point, and "simplify the path" turns a dense traced outline into a few smooth points.++## Colour a shape++Select the shape with V. The bar next to it fills it with the current colour or outlines it in the current colour. For a gradient, switch the fill in layer settings to linear or radial and edit its stops.++## Write text++Press T, click and type. Return starts a new line and Esc finishes. Double click existing text with V or T to edit it in place.++The font picker shows each family in its own face: about fifty open fonts come with klad, and a search finds any family on Google Fonts and downloads it. The font is copied into the drawing with its licence, so the text looks the same on every machine. "add a font" in the File menu puts a font file of your own in the drawing.++## Repeat, scatter and mirror a shape++Select a shape and use "repeat it" (copies along a line, an arc or a grid), "scatter it" (copies strewn over an area, each sized and turned from a seed) or "mirror it" from the Layer menu. They stay settings you can change, and "take the shapes out" turns them back into plain shapes.diff --git a/docs/guide/with-an-agent.md b/docs/guide/with-an-agent.mdnew file mode 100644index 0000000..25b0265--- /dev/null+++ b/docs/guide/with-an-agent.md@@ -0,0 +1,18 @@+# Working with an agent++klad has no model inside. The agent is one you already run, Claude Code, Codex or anything else that can use a terminal, and it paints through the `klad` command line into the drawing you have open. Its strokes show up in your editor within about a second.++## Set it up++1. In the editor's document menu (at the foot of the tool strip), click "install the klad command". It puts `klad` on your terminal's path for you and your agent (`klad install` does the same).+2. Tell the agent to run `klad skill` and read what it prints: that's its manual.+3. Copy the drawing's path from the File menu and give it to the agent with what you want: "Paint a lantern on its own layer in art.klad, lit from the left."++## Point at things++- Press N and click the canvas to pin a note there ("more moss on this side"). The agent reads open notes with `klad notes`, and when it marks one done the pin turns green. The Notes pane lists them all.+- Whatever you select in the editor, the agent can read with `klad selection`, so "make the selected strokes thinner" works.++## Keep control++Every change the agent makes is a step in the same history as yours. The History pane says who made each step, and cmd Z undoes the agent's step just like your own. Its strokes are ordinary strokes marked as the agent's: repaint, move or delete them by hand, and its next pass starts from your version.diff --git a/docs/images/guide-animation.png b/docs/images/guide-animation.pngnew file mode 100644index 0000000..8e3efdcBinary files /dev/null and b/docs/images/guide-animation.png differdiff --git a/docs/images/guide-bones.png b/docs/images/guide-bones.pngnew file mode 100644index 0000000..c77a548Binary files /dev/null and b/docs/images/guide-bones.png differdiff --git a/docs/images/guide-brush.png b/docs/images/guide-brush.pngnew file mode 100644index 0000000..796c769Binary files /dev/null and b/docs/images/guide-brush.png differdiff --git a/docs/images/guide-painting.png b/docs/images/guide-painting.pngnew file mode 100644index 0000000..b167801Binary files /dev/null and b/docs/images/guide-painting.png differdiff --git a/docs/images/guide-selection.png b/docs/images/guide-selection.pngnew file mode 100644index 0000000..c936359Binary files /dev/null and b/docs/images/guide-selection.png differ