Skip to content

armgit / klad

Public Imported from GitHub
0

A drawing app built for agent/human collaboration

Rust

README: build from source first, the list on klad.studio for builds

Indicode BV51bb3533a2d0
diff --git a/Cargo.lock b/Cargo.lock
index 9c519d5..a5e86e7 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -1744,7 +1744,7 @@ dependencies = [
[[package]]
name = "klad-app"
-version = "0.1.14"
+version = "0.1.15"
dependencies = [
"anyhow",
"block2 0.6.2",
@@ -1773,7 +1773,7 @@ dependencies = [
[[package]]
name = "klad-brush"
-version = "0.1.14"
+version = "0.1.15"
dependencies = [
"anyhow",
"bytemuck",
@@ -1789,7 +1789,7 @@ dependencies = [
[[package]]
name = "klad-cli"
-version = "0.1.14"
+version = "0.1.15"
dependencies = [
"anyhow",
"clap",
@@ -1815,7 +1815,7 @@ dependencies = [
[[package]]
name = "klad-core"
-version = "0.1.14"
+version = "0.1.15"
dependencies = [
"anyhow",
"half",
@@ -1827,7 +1827,7 @@ dependencies = [
[[package]]
name = "klad-render"
-version = "0.1.14"
+version = "0.1.15"
dependencies = [
"anyhow",
"bytemuck",
diff --git a/Cargo.toml b/Cargo.toml
index a325f0a..42463b0 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -3,7 +3,7 @@ resolver = "3"
members = ["crates/*"]
[workspace.package]
-version = "0.1.14"
+version = "0.1.15"
edition = "2024"
license-file = "LICENSE"
repository = "https://github.com/klad-app/klad"
diff --git a/README.md b/README.md
index 6db081c..014aba7 100644
--- a/README.md
+++ b/README.md
@@ -39,7 +39,7 @@ klad ink courier.klad lines --from shell-4,head-4,near-leg-4 --weight 5 --frame
Early, and open for testing. What works today:
- The `klad` CLI on macOS, Linux and Windows: layers, brush strokes, vector shapes, fills, inking, painting from shapes, light, effects, depth and fog, text in about fifty open fonts that come with it (and any other Google Fonts family on request), frames and clips, in-betweens, exports.
-- The editor on macOS, and in a first version on Windows and Linux: a pen with pressure and tilt (pressure only on Windows; on Linux the mouse for now), brushes, layers, masks, a text tool, the timeline, onion skins, notes for the agent, and a start window for new and recent drawings.
+- The editor on macOS, and in a first version on Windows and Linux (it starts on Linux; on Windows nobody has run it on a real machine yet, so tell us what you see): a pen with pressure and tilt (pressure only on Windows; on Linux the mouse for now), brushes, layers, masks, a text tool, the timeline, onion skins, notes for the agent, and a start window for new and recent drawings.
![The start window](docs/images/start-window.png)
@@ -47,8 +47,8 @@ The guides in `docs/guide/` show how to paint, select, fill, animate, rig and ex
## 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.
-- Linux: build it from source, free.
+- Build it from source, free, on macOS, Linux or Windows: see below.
+- Rather install it with a double click? Signed builds for macOS, Windows and Linux are planned, under the same licence as the source (see [Licence](#licence)). [Leave your email on klad.studio](https://klad.studio/pricing) to hear when they are ready.
Every build holds the `klad` command line tool, the editor, the fonts, the licences, the agent skill (`klad skill` prints it) and six sample drawings to look at and draw on (the start window shows them; `klad samples` lists them and copies one out). The first start offers first steps: draw a shape, fill it and hand the drawing to an agent. In the editor, the document menu's "install the klad command" puts `klad` on your terminal's path for you and for agents (`klad install` does the same). The editor checks klad's releases once a day for a new version and says so; it installs nothing by itself (turn it off in the settings window).
diff --git a/docs/DESIGN.md b/docs/DESIGN.md
index 4585eaa..74d96c7 100644
--- a/docs/DESIGN.md
+++ b/docs/DESIGN.md
@@ -1,4 +1,4 @@
-_Last updated: 2026-11-09 21:30_
+_Last updated: 2026-11-10 11:20_
# klad: design
@@ -152,7 +152,7 @@ Committed: everything except `.cache/`. A fresh clone rebuilds the cache by repl
- **Masks.** `mask` is 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: false` turns 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 in `MASK`, so `locate`, `layer_at` and the history treat it as a layer.
- **Clipping.** `clip: true` shows a layer only where its base, the nearest layer below it in the same list without `clip`, 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: true` on 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.json` changes 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 info` names 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 with `repair::UsedTwice`; `klad repair` and the start window's **Repair and open** run `Bundle::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 `.klad` format and starts clean: drawings from before it (`.draw` folders, `draw-anything/0` to `/9`, stroke files marked `DAST`) are refused on open with the reason and not converted (`migrate.rs` keeps the place where later migrations go). From here on a format change bumps the number and migrates older `.klad` drawings on open; history snapshots go through the same migration when undone. `klad/2` (2026-11-07) added IK (`ik` on skeletons and in poses); a `klad/1` drawing opens as it is, renamed. `klad/3` (2026-11-08) added `bone` on 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 through `rig` (follow a bone, or bend); drawings from before open with their rigs dropped (Kevin's 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, and `crates/cli/tests/formats.rs` opens 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 in `klad/1` and `klad/4`).
+- Nothing in `doc.json` changes 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 info` names 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 with `repair::UsedTwice`; `klad repair` and the start window's **Repair and open** run `Bundle::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 `.klad` format and starts clean: drawings from before it (`.draw` folders, `draw-anything/0` to `/9`, stroke files marked `DAST`) are refused on open with the reason and not converted (`migrate.rs` keeps the place where later migrations go). From here on a format change bumps the number and migrates older `.klad` drawings on open; history snapshots go through the same migration when undone. `klad/2` (2026-11-07) added IK (`ik` on skeletons and in poses); a `klad/1` drawing opens as it is, renamed. `klad/3` (2026-11-08) added `bone` on 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 through `rig` (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, and `crates/cli/tests/formats.rs` opens 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 in `klad/1` and `klad/4`).
### Edits
@@ -246,7 +246,7 @@ Every layer has `blend`, `opacity`, `visible`, `locked`, optional `mask`, `clip`
- **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 `klad` CLI, 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 in `weights/<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 by `Bundle::apply` with 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; `set` paints soft dabs (smoothstep falloff towards a value), `part` gives a named part's cells to one bone at 1 and the others 0, `smooth` blurs every map once. A pose (`pose` on 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 at `to` on every paint layer under the skeleton from the rest drawing shown at `from` (a posed drawing's own rest when `from` shows 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 bone `move` with a `tail` takes along the heads of the children that start at the old tail (within half a pixel), and `by` moves 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, so `rig::moved` and 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) through `klad pose` as 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 as `Bone2D`s, 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 --set` also lists the poses that now solve differently from how their drawings were bent. `rig::applied` solves (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`, `tips` and `Rig::new` take 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 by `Document::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).** Kevin: "a better way to select and transform a full layer instead of individual brush strokes only"; his choices: the marks themselves move (not a transform kept on the layer), every drawing by default, started with cmd T. The `transform` op with `layer` (`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, so `klad_render::shift` works them out (`targets`, read once, then `shifted` per 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.
+- **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 `transform` op with `layer` (`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, so `klad_render::shift` works them out (`targets`, read once, then `shifted` per 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 in `klad render` and the exports, not in the editor.
- **Godot scenes (M6, S6.6, S6.7).** `export --godot-scene` flattens each visible top-level layer (with its fog; the background with the first) into a texture on a `Parallax2D` with `scroll_scale` 1/(1 + depth), the factor the editor's depth preview (hold D) uses. `export --godot-rig` writes 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 a `Polygon2D` with a 16 px triangle mesh over its pixels (one cell of margin), UVs, and per-vertex weights sampled from the maps; a `Skeleton2D` with a `Bone2D` per bone at rest (local position and angle against the parent, `rest`, `length`); and an `AnimationPlayer` with 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/rig` builds 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 (the `from` layers, 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) exceeds `threshold`, 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 by `curve` times 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. `focus` keeps 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 by `vary` from a hash of its seed, in the part `part`. `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) with `tween::carry` along 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-b` repeats that drawing to drawing, making a drawing on the target wherever a source layer starts one (a link where they link). `samples/paintover` paints 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.
@@ -446,7 +446,7 @@ Scripts are any language that prints edit ops as JSON lines into `klad apply`. G
- 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::Inspector` in 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::DEVELOPER` lists its commands, which are in no menu, not in the palette and refused without it).
- Commands (M4 batch 1): every editor action is a `Cmd` in 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 through `Editor::invoke`, which first asks `can_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 `feather` for the E eraser and the pen's eraser end alike and is kept in the settings as `eraserFeather`, 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`, or `stroke.paint`, or a new `stroke` at the pen's width when it had none; Edit > Shape; `klad set <id> fill=...` is the CLI form), duplicate in place (an `add` of 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) as `rect` and `ellipse` nodes. 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::stretched` scales 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, Kevin: "make brush its own palette, like colour and layers") the size presets and the brushes as tiles, each with a sample stroke drawn by `klad-brush` once per brush definition. A saved layout without a pane gets it after the pane it follows by default.
+- 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 `feather` for the E eraser and the pen's eraser end alike and is kept in the settings as `eraserFeather`, 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`, or `stroke.paint`, or a new `stroke` at the pen's width when it had none; Edit > Shape; `klad set <id> fill=...` is the CLI form), duplicate in place (an `add` of 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) as `rect` and `ellipse` nodes. 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::stretched` scales 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 by `klad-brush` once 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 say `welcomed` (set when any drawing opens, or by "Not now"), the start window opens with a welcome offering first steps. First steps make `first 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 read `klad 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 are `klad skill`. Revisit the third step when klad is an MCP server (S8.10). Under the recent drawings the start window shows the samples: the drawings `samples/shipped.json` names (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>.klad` or `<name> 2.klad`) and opens the copy, so a sample is never changed. `klad samples` lists the same set and `--copy <name> [--into folder]` copies one (default the current folder). Samples are found like the fonts: `KLAD_SAMPLES`, then `samples/` next to the binary, `../Resources/samples`, `../share/klad/samples`, and a source checkout's `samples/` up to five folders above the binary (where they exist after `just samples`; a sample not built is left out). `packaging/samples.sh` puts them in every build: it builds any that are missing with that build's `klad` (through the sample's `build.sh`, `PYTHON` naming the interpreter), copies them without caches, and renders each one's `<name>.thumb.png` next 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.png` are remade when the drawing changes). `app.sh` puts them in `Resources/samples`, `archive.sh` in the archive's `samples/` and the AppImage's `usr/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) are `report::Bug`s: 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 "<job> did not finish: <the CLI's reason>". Every error message, job failure and crash of the editor or the CLI is appended to `klad.log` next to the settings (`KLAD_LOG` overrides 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 in `klad_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!`) whose `kladRun:` queues the command for the next frame (the editor runs it through `Editor::invoke` as any key would) and whose `validateMenuItem:` 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 to `menuHasKeyEquivalent: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.
diff --git a/docs/guide/getting-started.md b/docs/guide/getting-started.md
index 24a0b64..97a3de9 100644
--- a/docs/guide/getting-started.md
+++ b/docs/guide/getting-started.md
@@ -1,4 +1,4 @@
-_Last updated: 2026-11-08 14:50_
+_Last updated: 2026-11-10 11:20_
# Getting started
@@ -8,7 +8,7 @@ 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). On a Mac the pen gives pressure and tilt, on Windows pressure, and on Linux you draw with the mouse for now.
+[Build klad from source](https://github.com/klad-app/klad#from-source): it is free and takes about ten minutes. Signed builds that install with a double click are planned; [klad.studio](https://klad.studio/pricing) has the list to hear when. On a Mac the pen gives pressure and tilt, on Windows pressure, and on Linux you draw with the mouse for now.
## Make a drawing