Skip to content

armgit / klad

Public Imported from GitHub
0

A drawing app built for agent/human collaboration

Rust

Brushes take feather and fringe; the eraser's slider is feather

Indicode BVf3c8b994850d
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 189f21d..7db16a6 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,7 +7,7 @@ The first builds, and klad's licences.
- Drawings are `.klad` folders in a fresh format, `klad/6` (drawings from the first builds open as they are, except their bones, which are dropped). Drawings from before (`.draw` folders) do not open and are not converted.
- Drawings live well in git: an edit changes only the files of what it edits (`doc.json` keeps no revision or id counter), and copies of a drawing edited apart, in a clone or a worktree, never make the same id, so edits to different layers merge. New ids end in the copy's two-letter tag (`l48qa`, `c12:s349qa`); `klad info` shows it. The editor follows a `git checkout` of an open drawing, and klad never renders an old picture from its cache after one. Recolouring several strokes or fills at once (the selection bar in the editor, or `klad recolour`) moves them to the new colour together and keeps each one's own shade, so a painted-over area stays painted. If a merge still leaves an id used twice, `klad repair` (or **Repair and open** when the drawing won't open) gives every later one a new id and moves its stroke files along.
- Erasers, smudges and blends stay with the strokes they were drawn over: move, copy or delete the strokes and they come along (or split, when only some of the strokes move), and an eraser erases only its own strokes, so moving them never bites into the paint they land on. The selection bar shows what is attached, "attached only" moves it on its own (it attaches to what it lands on), and detach frees it (`klad detach`); a stroke its erasers wipe out completely is skipped by clicks and the lasso. `klad strokes --json` lists `on`, `attached` and `hidden`. Stroke files move to version 2 (format `klad/6`); older drawings open with nothing attached.
-- Bending a stroke with the point tool bends what is attached to it. The eraser has a **soft** slider in the brush bar, for the pen's eraser end too.
+- Bending a stroke with the point tool bends what is attached to it. The eraser has a **feather** slider in the brush bar, for the pen's eraser end too: its edge fades out like an airbrush. Brushes take `feather` and `fringe` (an edge frayed into streaks along the stroke, like a dry brush), in the brush window and in `klad brushes --set`.
- klad is source-available, not open source: the app is under the PolyForm Internal Use License 1.0.0, with permission for personal use (building from source is free for it), to propose contributions and to share the drawings you make (`LICENSE`). Companies with 100,000 euros or more in revenue a year buy a licence for each person who uses klad; a bought build is that licence, under the same terms. The file format (`docs/format.md`), the command reference (`docs/cli.md`), the agent skill and the new `klad-client` crate are MIT (`LICENSE-MIT`), so any program or agent can read, write and make klad drawings. Contributions come in under a contributor licence agreement (`CLA.md`).
- `klad-client`: run klad from Rust, apply edits as JSON ops, read drawings back as JSON, render them.
- Builds for macOS (an app, Apple silicon and Intel in one) and Windows, sold on itch.io; Linux from source. Each has the `klad` command line, the editor, the fonts, the licences and the agent skill.
diff --git a/crates/app/src/editor.rs b/crates/app/src/editor.rs
index ba5e5ec..f2310a6 100644
--- a/crates/app/src/editor.rs
+++ b/crates/app/src/editor.rs
@@ -478,6 +478,7 @@ struct Live {
#[derive(Clone, Copy, Debug, PartialEq)]
struct Tuning {
hardness: Option<f32>,
+ feather: f32,
size_min: f32,
size_gamma: f32,
taper: [f32; 2],
@@ -494,6 +495,7 @@ impl Tuning {
});
Self {
hardness: def.hardness(),
+ feather: def.feather,
size_min: curve.min,
size_gamma: curve.gamma,
taper: def.taper,
@@ -507,6 +509,7 @@ impl Tuning {
if let (Some(hardness), TipDef::Round { .. }) = (self.hardness, &def.tip) {
def.tip = TipDef::Round { hardness };
}
+ def.feather = self.feather;
let old = Tuning::of(base);
if (self.size_min, self.size_gamma) != (old.size_min, old.size_gamma) {
def.dynamics.size.pressure = Some(Curve {
@@ -2763,28 +2766,26 @@ impl Editor {
fn tuned(&self, id: &str, def: &BrushDef) -> Tuning {
let tuning = Tuning::of(def);
- match (id, self.settings.eraser_soft, tuning.hardness) {
- ("eraser", Some(soft), Some(_)) => Tuning {
- hardness: Some(1.0 - soft),
- ..tuning
- },
+ match (id, self.settings.eraser_feather, tuning.hardness) {
+ ("eraser", Some(feather), Some(_)) => Tuning { feather, ..tuning },
_ => tuning,
}
}
- pub(super) fn eraser_soft(&self) -> Option<f32> {
+ pub(super) fn eraser_feather(&self) -> Option<f32> {
if self.is_on(Cmd::Eraser) != Some(true) {
return None;
}
- let hardness = self.brushes.def("eraser").and_then(BrushDef::hardness)?;
- Some(self.settings.eraser_soft.unwrap_or(1.0 - hardness))
+ let def = self.brushes.def("eraser").filter(|d| d.hardness().is_some())?;
+ Some(self.settings.eraser_feather.unwrap_or(def.feather))
}
- pub(super) fn set_eraser_soft(&mut self, soft: f32) {
- self.settings.eraser_soft = Some(soft.clamp(0.0, 1.0));
+ pub(super) fn set_eraser_feather(&mut self, feather: f32) {
+ let feather = feather.clamp(0.0, 1.0);
+ self.settings.eraser_feather = Some(feather);
self.settings_dirty = true;
if self.brush == "eraser" {
- self.tuning.hardness = Some(1.0 - soft.clamp(0.0, 1.0));
+ self.tuning.feather = feather;
}
}
@@ -4654,6 +4655,8 @@ mod tests {
..tuning
};
assert_eq!(harder.shape(ink).hardness(), Some(1.0));
+ let feathered = Tuning { feather: 0.5, ..tuning };
+ assert_eq!(feathered.shape(ink).feather, 0.5);
let lighter = Tuning {
size_min: 0.3,
..tuning
diff --git a/crates/app/src/editor/brushwin.rs b/crates/app/src/editor/brushwin.rs
index 97f6187..53228b4 100644
--- a/crates/app/src/editor/brushwin.rs
+++ b/crates/app/src/editor/brushwin.rs
@@ -295,6 +295,22 @@ impl Editor {
&pictures,
"the shape each dab stamps: round, chalk or a picture",
);
+ if matches!(def.tip, TipDef::Round { .. }) {
+ changed |= slider(
+ ui,
+ &mut def.feather,
+ 0.0..=1.0,
+ "feather",
+ "how far in the edge fades out like an airbrush; overlapping dabs don't build it back up",
+ );
+ }
+ changed |= slider(
+ ui,
+ &mut def.fringe,
+ 0.0..=1.0,
+ "fringe",
+ "breaks the edge into streaks along the stroke, like a dry brush",
+ );
});
ui.vertical(|ui| {
changed |= slider(
diff --git a/crates/app/src/editor/options.rs b/crates/app/src/editor/options.rs
index 5578d83..1070a75 100644
--- a/crates/app/src/editor/options.rs
+++ b/crates/app/src/editor/options.rs
@@ -213,13 +213,13 @@ impl Editor {
.text("size"),
)
.hint("brush size in canvas px ([ and ], or hold cmd alt and drag sideways on the canvas)");
- if let Some(mut soft) = self.eraser_soft()
+ if let Some(mut feather) = self.eraser_feather()
&& ui
- .add(egui::Slider::new(&mut soft, 0.0..=1.0).text("soft"))
- .hint("how soft the eraser's edge is: 0 cuts clean, 1 fades out like an airbrush; the pen's eraser end too")
+ .add(egui::Slider::new(&mut feather, 0.0..=1.0).text("feather"))
+ .hint("how far in the eraser's edge fades: 0 cuts clean, 1 fades out like an airbrush; the pen's eraser end too")
.changed()
{
- self.set_eraser_soft(soft);
+ self.set_eraser_feather(feather);
}
ui.add(egui::Slider::new(&mut self.opacity, 0.05..=1.0).text("opacity"))
.hint("a stroke never gets darker than this on its own");
@@ -234,6 +234,8 @@ impl Editor {
if let Some(hardness) = t.hardness.as_mut().filter(|_| !erasing) {
ui.add(egui::Slider::new(hardness, 0.0..=1.0).text("hardness"))
.hint("soft to hard edge; changing it draws as a variant of the brush");
+ ui.add(egui::Slider::new(&mut t.feather, 0.0..=1.0).text("feather"))
+ .hint("how far in the edge fades out like an airbrush, without dabs building it back up");
}
ui.add(egui::Slider::new(&mut t.size_min, 0.0..=1.0).text("lightest size"))
.hint("the size at the lightest press, as a part of the full size");
@@ -260,7 +262,9 @@ impl Editor {
}
let (id, _) = self.shaped()?;
if id != self.brush {
- ui.small(format!("hardness or curve changed: draws as {id}, kept in the bundle"));
+ ui.small(format!(
+ "hardness, feather or curve changed: draws as {id}, kept in the bundle"
+ ));
}
Ok(())
}
@@ -312,7 +316,7 @@ impl Editor {
self.check(|e| e.brush_more(ui));
})
.response
- .hint("hardness, pressure curve, taper, stabiliser and smoothing");
+ .hint("hardness, feather, pressure curve, taper, stabiliser and smoothing");
self.command_button(ui, Cmd::BrushWindow, Some("edit"));
self.command_check(ui, Cmd::Symmetry, "mirror");
if let Some(axis) = self.mirror.as_mut() {
diff --git a/crates/app/src/editor/ui_tests.rs b/crates/app/src/editor/ui_tests.rs
index 9e1e44e..4b370e7 100644
--- a/crates/app/src/editor/ui_tests.rs
+++ b/crates/app/src/editor/ui_tests.rs
@@ -2045,28 +2045,25 @@ fn erasers_follow_their_strokes_and_attached_only_and_detach_reach_them() {
}
#[test]
-fn the_eraser_has_a_soft_slider_that_stays_and_reaches_its_strokes() {
- let path = sample("soft-eraser");
+fn the_eraser_has_a_feather_slider_that_stays_and_reaches_its_strokes() {
+ let path = sample("feather-eraser");
let mut h = harness(editor(&path), vec2(1440.0, 900.0));
activate(&mut h, "notes");
h.key_press(Key::E);
h.run_steps(2);
+ assert_eq!(h.state().eraser_feather(), Some(0.0), "the library eraser cuts clean");
assert!(
- h.state().eraser_soft().is_some_and(|soft| (soft - 0.15).abs() < 1e-4),
- "the library eraser's own edge"
- );
- assert!(
- h.query_all_by_label_contains("soft").count() > 0,
+ h.query_all_by_label_contains("feather").count() > 0,
"the slider is in the bar"
);
- h.state_mut().set_eraser_soft(0.9);
+ h.state_mut().set_eraser_feather(0.9);
h.key_press(Key::B);
h.run_steps(2);
- assert!(h.state().eraser_soft().is_none(), "brushes keep hardness under more");
+ assert!(h.state().eraser_feather().is_none(), "brushes keep theirs under more");
h.key_press(Key::E);
h.run_steps(2);
assert_eq!(
- h.state().eraser_soft(),
+ h.state().eraser_feather(),
Some(0.9),
"it stays when the eraser comes back"
);
@@ -2079,12 +2076,9 @@ fn the_eraser_has_a_soft_slider_that_stays_and_reaches_its_strokes() {
.map(|s| s.brush.clone())
.unwrap();
let def = h.state().scene.bundle.brush(&brush).unwrap().unwrap();
- assert!(
- def.hardness().is_some_and(|hardness| (hardness - 0.1).abs() < 1e-4),
- "{brush} is a soft eraser: {:?}",
- def.hardness()
- );
- assert_eq!(h.state().settings.eraser_soft, Some(0.9), "kept in the settings");
+ assert_eq!(def.feather, 0.9, "{brush} is a feathered eraser");
+ assert_eq!(def.hardness(), Some(0.85), "{brush} keeps the eraser's hardness");
+ assert_eq!(h.state().settings.eraser_feather, Some(0.9), "kept in the settings");
let _ = std::fs::remove_dir_all(&path);
}
@@ -3309,6 +3303,45 @@ fn the_cli_only_features_run_from_the_editor_and_give_what_the_cli_gives() {
std::fs::remove_dir_all(&base).unwrap();
}
+#[test]
+fn the_brush_window_feathers_and_frays_a_round_brush() {
+ let path = sample("feather-fringe");
+ let mut h = harness(editor(&path), vec2(1440.0, 1400.0));
+ activate(&mut h, "lines");
+ h.state_mut().pick("ink");
+ h.key_press(Key::F5);
+ h.run_steps(3);
+ assert!(h.state().windows.brush);
+ ["feather", "fringe"].iter().for_each(|label| {
+ let track = h.get_by_role_and_label(Role::Slider, label).rect();
+ let at = egui::pos2(track.left() + track.width() * 0.9, track.center().y);
+ drag(&mut h, at, at);
+ h.run_steps(2);
+ });
+ let edited = h.state().custom.clone().unwrap();
+ assert!(
+ edited.feather > 0.7 && edited.fringe > 0.7,
+ "{} {}",
+ edited.feather,
+ edited.fringe
+ );
+ h.key_press(Key::F5);
+ h.run_steps(2);
+ let c = h.state().canvas_rect.center();
+ pen_line(&mut h, c + vec2(-60.0, 0.0), c + vec2(60.0, 0.0));
+ let brush = h
+ .state()
+ .scene
+ .active_marks()
+ .last()
+ .and_then(|m| m.as_stroke())
+ .map(|s| s.brush.clone())
+ .unwrap();
+ let def = h.state().scene.bundle.brush(&brush).unwrap().unwrap();
+ assert_eq!((def.feather, def.fringe), (edited.feather, edited.fringe), "{brush}");
+ let _ = std::fs::remove_dir_all(&path);
+}
+
#[test]
fn paint_with_body_from_the_brush_window_lit_by_a_relief_turned_with_its_dial() {
use klad_core::look::Effect;
diff --git a/crates/app/src/settings.rs b/crates/app/src/settings.rs
index 692ddd1..6af219b 100644
--- a/crates/app/src/settings.rs
+++ b/crates/app/src/settings.rs
@@ -89,8 +89,8 @@ pub struct Settings {
pub pick_all_layers: bool,
#[serde(default, rename = "developerTools", skip_serializing_if = "std::ops::Not::not")]
pub developer: bool,
- #[serde(default, rename = "eraserSoft", skip_serializing_if = "Option::is_none")]
- pub eraser_soft: Option<f32>,
+ #[serde(default, rename = "eraserFeather", skip_serializing_if = "Option::is_none")]
+ pub eraser_feather: Option<f32>,
}
fn yes() -> bool {
@@ -115,7 +115,7 @@ impl Default for Settings {
welcomed: false,
pick_all_layers: true,
developer: false,
- eraser_soft: None,
+ eraser_feather: None,
}
}
}
diff --git a/crates/brush/src/brush.rs b/crates/brush/src/brush.rs
index 5be55fe..e2d29e2 100644
--- a/crates/brush/src/brush.rs
+++ b/crates/brush/src/brush.rs
@@ -176,7 +176,12 @@ impl Brush {
}
pub fn with_pictures(def: &BrushDef, pictures: &Pictures) -> Result<Self> {
- let tip = tip_of(&def.tip, pictures)?;
+ let tip = match tip_of(&def.tip, pictures)? {
+ Tip::Round { hardness } if def.feather > 0.0 => Tip::Round {
+ hardness: hardness.min(1.0 - def.feather),
+ },
+ tip => tip,
+ };
let grain = def
.grain
.as_ref()
diff --git a/crates/brush/src/engine.rs b/crates/brush/src/engine.rs
index bd51775..b3937b9 100644
--- a/crates/brush/src/engine.rs
+++ b/crates/brush/src/engine.rs
@@ -85,6 +85,7 @@ pub struct StrokePainter {
reservoir_height: Option<f32>,
previous: Option<(f32, f32)>,
bristles: Option<Box<Bristles>>,
+ fringe: Option<Fringe>,
}
const STROKE_COLOUR_SEED: u64 = 0x9e37_79b9_7f4a_7c15;
@@ -140,6 +141,8 @@ impl StrokePainter {
previous: None,
bristles: (brush.def.body > 0.0)
.then(|| Box::new(Bristles::new(stroke.seed ^ 0x5bd1_e995, stroke.size, brush.scale))),
+ fringe: (brush.def.fringe > 0.0)
+ .then(|| Fringe::new(stroke.seed ^ 0x2c1b_3c6d, stroke.size, brush.def.fringe)),
}
}
@@ -174,8 +177,8 @@ impl StrokePainter {
};
let Some(prev) = self.last else {
let pictured = matches!(self.brush.def.tip, klad_core::brushes::TipDef::Image { .. });
- match (self.brush.angle, pictured) {
- (Angle::Follow, true) => self.pending = Some(next),
+ match (self.brush.angle, pictured, self.fringe.is_some()) {
+ (Angle::Follow, true, _) | (_, _, true) => self.pending = Some(next),
_ => self.dab(next, 0.0, buffer, under),
}
self.last = Some(next);
@@ -342,17 +345,26 @@ impl StrokePainter {
color,
lift,
pick: klad_core::rng::hash2(self.dabs as i32, self.seed as i32, 0x1eaf) as usize,
+ heading: self.heading,
+ along,
};
+ let fringe = self.fringe.as_ref();
match self.brush.def.paint {
- Some(PaintDef::Smudge { strength }) => {
- stamp_replace(buffer, &self.brush, dab, under, Replace::Smudge(shift), strength)
- }
+ Some(PaintDef::Smudge { strength }) => stamp_replace(
+ buffer,
+ &self.brush,
+ dab,
+ fringe,
+ under,
+ Replace::Smudge(shift),
+ strength,
+ ),
Some(PaintDef::Blend { strength }) => {
- stamp_replace(buffer, &self.brush, dab, under, Replace::Blend, strength)
+ stamp_replace(buffer, &self.brush, dab, fringe, under, Replace::Blend, strength)
}
_ => {
let bristles = self.bristles.as_deref().map(|b| (b, b.load(along)));
- stamp(buffer, &self.brush, dab, bristles)
+ stamp(buffer, &self.brush, dab, fringe, bristles)
}
}
}
@@ -466,8 +478,51 @@ struct Dab {
color: Option<[f32; 3]>,
lift: Option<f32>,
pick: usize,
+ heading: f32,
+ along: f32,
+}
+
+struct Fringe {
+ seed: u32,
+ across: f32,
+ along: f32,
+ band: f32,
+}
+
+impl Fringe {
+ fn new(seed: u32, size: f32, fringe: f32) -> Self {
+ Self {
+ seed,
+ across: (size / 2.5).clamp(5.0, 64.0),
+ along: 1.0 / (size * 0.9).max(4.0),
+ band: FRINGE * fringe,
+ }
+ }
+
+ fn reach(&self, dab: &Dab, px: f32, py: f32, radius: f32) -> f32 {
+ let (sin, cos) = (libm::sinf(dab.heading), libm::cosf(dab.heading));
+ let across = ((py * cos - px * sin) / radius).clamp(-1.0, 1.0);
+ let along = dab.along + px * cos + py * sin;
+ let a = (across + 1.0) * 0.5 * self.across;
+ let b = along * self.along;
+ let coarse = self.noise(a, b, 0);
+ let fine = self.noise(a * 2.7, b * 1.9, 1);
+ let g = smoothstep(0.25, 0.75, coarse * 0.6 + fine * 0.4);
+ 1.0 - self.band * g
+ }
+
+ fn noise(&self, a: f32, b: f32, octave: u32) -> f32 {
+ let (i, j) = (libm::floorf(a), libm::floorf(b));
+ let (sa, sb) = (smoothstep(0.0, 1.0, a - i), smoothstep(0.0, 1.0, b - j));
+ let seed = self.seed.wrapping_add(octave.wrapping_mul(0x9e37_79b9));
+ let at = |di: i32, dj: i32| hash2_unit(i as i32 + di, j as i32 + dj, seed);
+ let top = at(0, 0) + (at(1, 0) - at(0, 0)) * sa;
+ let bottom = at(0, 1) + (at(1, 1) - at(0, 1)) * sa;
+ top + (bottom - top) * sb
+ }
}
+const FRINGE: f32 = 0.55;
const GROOVES: usize = 256;
const RUN: f32 = 8.0;
const EDGE: f32 = 2.5;
@@ -581,15 +636,18 @@ struct Edge {
}
impl Edge {
- fn of(tip: &Tip, radius: f32) -> Option<Edge> {
- match tip {
+ fn of(brush: &Brush, radius: f32) -> Option<Edge> {
+ match brush.tip {
Tip::Round { hardness } => {
let solid = hardness * radius;
let fade = (radius - solid).max(1e-4);
Some(Edge {
solid,
fade,
- soft: smoothstep(0.5, 2.0, fade),
+ soft: match brush.def.feather > 0.0 {
+ true => 0.0,
+ false => smoothstep(0.5, 2.0, fade),
+ },
})
}
Tip::Mask(_) | Tip::Masks(_) => None,
@@ -615,6 +673,16 @@ impl Edge {
}
}
+fn fringed(u: f32, v: f32, reach: Option<f32>) -> (f32, f32, f32) {
+ match reach {
+ Some(r) => {
+ let (u, v) = (u / r, v / r);
+ (u, v, u * u + v * v)
+ }
+ None => (u, v, u * u + v * v),
+ }
+}
+
fn dual_value(brush: &Brush, dab: &Dab, u: f32, v: f32, radius: f32) -> f32 {
let Some(dual) = brush.dual.as_ref() else {
return 1.0;
@@ -684,7 +752,13 @@ fn area(buffer: &StrokeBuffer, dab: &Dab) -> Option<Area> {
})
}
-fn stamp(buffer: &mut StrokeBuffer, brush: &Brush, dab: Dab, bristles: Option<(&Bristles, f32)>) {
+fn stamp(
+ buffer: &mut StrokeBuffer,
+ brush: &Brush,
+ dab: Dab,
+ fringe: Option<&Fringe>,
+ bristles: Option<(&Bristles, f32)>,
+) {
let Some(Area {
x0,
y0,
@@ -702,7 +776,7 @@ fn stamp(buffer: &mut StrokeBuffer, brush: &Brush, dab: Dab, bristles: Option<(&
let inv_radius = 1.0 / radius;
let inv_round = 1.0 / brush.def.roundness;
let cols = buffer.grid().cols;
- let edge = Edge::of(&brush.tip, radius);
+ let edge = Edge::of(brush, radius);
let profile = bristles.map(|(b, load)| (b, b.profile(radius, brush.def.roundness, load, dab.p)));
for ty in y0 / TILE..=(y1 - 1) / TILE {
for tx in x0 / TILE..=(x1 - 1) / TILE {
@@ -729,9 +803,11 @@ fn stamp(buffer: &mut StrokeBuffer, brush: &Brush, dab: Dab, bristles: Option<(&
let row = (y - oy) * TILE;
for x in x0.max(ox)..x1.min(ox + TILE) {
let px = x as f32 + 0.5 - cx;
- let u = (px * cos + py * sin) * inv_radius;
- let v = (py * cos - px * sin) * inv_round * inv_radius;
- let d2 = u * u + v * v;
+ let (u, v, d2) = fringed(
+ (px * cos + py * sin) * inv_radius,
+ (py * cos - px * sin) * inv_round * inv_radius,
+ fringe.map(|f| f.reach(&dab, px, py, radius)),
+ );
if d2 >= reach2 {
continue;
}
@@ -784,6 +860,7 @@ fn stamp_replace(
buffer: &mut StrokeBuffer,
brush: &Brush,
dab: Dab,
+ fringe: Option<&Fringe>,
under: Option<&Raster>,
how: Replace,
strength: f32,
@@ -812,9 +889,11 @@ fn stamp_replace(
.filter(|&(x, y)| buffer.allowed((y / TILE) * cols + x / TILE))
.filter_map(|(x, y)| {
let (px, py) = (x as f32 + 0.5 - dab.cx, y as f32 + 0.5 - dab.cy);
- let u = (px * cos + py * sin) * inv_radius;
- let v = (py * cos - px * sin) * inv_round * inv_radius;
- let d2 = u * u + v * v;
+ let (u, v, d2) = fringed(
+ (px * cos + py * sin) * inv_radius,
+ (py * cos - px * sin) * inv_round * inv_radius,
+ fringe.map(|f| f.reach(&dab, px, py, radius)),
+ );
if d2 >= reach2 {
return None;
}
@@ -1543,6 +1622,80 @@ mod tests {
);
}
+ fn round(id: &str, spacing: f32, feather: f32, fringe: f32) -> BrushSet {
+ let def = klad_core::brushes::BrushDef::parse(&format!(
+ r#"{{"name":"Round","tip":{{"round":{{"hardness":0.85}}}},"spacing":{spacing},"feather":{feather},"fringe":{fringe}}}"#
+ ))
+ .unwrap();
+ let mut set = BrushSet::presets();
+ set.insert(id, def);
+ set
+ }
+
+ #[test]
+ fn a_feathered_edge_fades_like_one_airbrush_pass_whatever_the_spacing() {
+ let across = |spacing: f32, feather: f32| {
+ let set = round("r", spacing, feather, 0.0);
+ let r = replay(
+ 512,
+ 128,
+ &[line("r", 60.0, (40.0, 64.0), (470.0, 64.0), (1.0, 1.0)).into()],
+ &set,
+ )
+ .unwrap()
+ .raster;
+ [0usize, 6, 12, 18, 24].map(|dy| alpha(&r, 256, 64 + dy))
+ };
+ let (dense, sparse) = (across(0.02, 1.0), across(0.12, 1.0));
+ assert!(dense[0] > 0.97, "the middle is all there: {dense:?}");
+ assert!(dense[3] < 0.5 && dense[4] < 0.2, "the edge fades out: {dense:?}");
+ dense.iter().zip(sparse).for_each(|(a, b)| {
+ assert!(
+ (a - b).abs() < 0.05,
+ "dabs don't build the fade back up: {dense:?} {sparse:?}"
+ )
+ });
+ let clean = across(0.06, 0.0);
+ assert!(
+ clean[3] > 0.97 && across(0.06, 0.3)[3] > 0.97,
+ "a little feather keeps the stroke's body"
+ );
+ assert!(across(0.06, 0.6)[3] < clean[3] - 0.2, "more feather fades further in");
+ }
+
+ #[test]
+ fn a_fringe_breaks_the_edge_into_streaks_along_the_stroke() {
+ let raster = |fringe: f32| {
+ let set = round("r", 0.06, 0.0, fringe);
+ replay(
+ 512,
+ 128,
+ &[line("r", 60.0, (40.0, 64.0), (470.0, 64.0), (1.0, 1.0)).into()],
+ &set,
+ )
+ .unwrap()
+ .raster
+ };
+ let flips = |r: &Raster, step: (usize, usize)| {
+ (100..400)
+ .flat_map(|x| (80..94).map(move |y| (x, y)))
+ .filter(|&(x, y)| (alpha(r, x, y) > 0.5) != (alpha(r, x + step.0, y + step.1) > 0.5))
+ .count()
+ };
+ let (fringed, plain) = (raster(1.0), raster(0.0));
+ assert!(
+ (100..400).all(|x| (54..74).all(|y| alpha(&fringed, x, y) > 0.95)),
+ "the middle stays whole"
+ );
+ assert_eq!(flips(&plain, (1, 0)), 0, "without a fringe the edge runs clean");
+ let (along, across) = (flips(&fringed, (1, 0)), flips(&fringed, (0, 1)));
+ assert!(across > 300, "the edge breaks up: {across}");
+ assert!(
+ along * 3 < across,
+ "into streaks along the stroke: {along} along, {across} across"
+ );
+ }
+
#[test]
fn texture_stays_on_the_canvas_under_two_strokes() {
let mut def = klad_core::brushes::library("soft").unwrap();
diff --git a/crates/cli/src/brushes.rs b/crates/cli/src/brushes.rs
index 11b5a18..7ce30c0 100644
--- a/crates/cli/src/brushes.rs
+++ b/crates/cli/src/brushes.rs
@@ -59,6 +59,8 @@ fn tip(def: &BrushDef) -> String {
(matches!(def.paint, Some(brushes::PaintDef::Smudge { .. })), "smudge"),
(matches!(def.paint, Some(brushes::PaintDef::Blend { .. })), "blend"),
(def.body > 0.0, "body"),
+ (def.feather > 0.0, "feather"),
+ (def.fringe > 0.0, "fringe"),
]
.iter()
.filter(|(on, _)| *on)
diff --git a/crates/cli/tests/binary.rs b/crates/cli/tests/binary.rs
index 57e2de4..8cb053e 100644
--- a/crates/cli/tests/binary.rs
+++ b/crates/cli/tests/binary.rs
@@ -574,3 +574,81 @@ fn modifiers_move_go_and_copy_with_their_marks_and_attach_again_when_moved_alone
assert_eq!(copies[1]["on"], serde_json::json!([copies[0]["address"]]));
std::fs::remove_dir_all(&dir).unwrap();
}
+
+#[test]
+fn a_brush_with_a_feathered_or_fringed_edge_goes_in_from_the_command_line() {
+ let dir = std::env::temp_dir().join(format!("draw-binary-feather-{}", std::process::id()));
+ let _ = std::fs::remove_dir_all(&dir);
+ std::fs::create_dir_all(&dir).unwrap();
+ let run = |args: &[&str]| Command::new(env!("CARGO_BIN_EXE_klad")).args(args).output().unwrap();
+ let draw = |args: &[&str]| {
+ let out = run(args);
+ assert!(out.status.success(), "{}", String::from_utf8_lossy(&out.stderr));
+ String::from_utf8_lossy(&out.stdout).to_string()
+ };
+ let eraser = |feather: &str, fringe: &str| {
+ format!(
+ r#"{{"format":"klad-brush/1","name":"Eraser","tip":{{"round":{{"hardness":0.85}}}},"spacing":0.06,"blend":"erase","feather":{feather},"fringe":{fringe}}}"#
+ )
+ };
+ let hash = |name: &str, brush: Option<String>| {
+ let path = dir.join(format!("{name}.klad"));
+ let path = path.to_str().unwrap();
+ draw(&["new", path, "--width", "200", "--height", "100"]);
+ draw(&[
+ "fill",
+ path,
+ "l1",
+ "--polygon",
+ "0,0 200,0 200,100 0,100",
+ "--color",
+ "#204060",
+ ]);
+ let id = match brush {
+ Some(def) => {
+ let file = dir.join(format!("{name}.json"));
+ std::fs::write(&file, def).unwrap();
+ assert!(draw(&["brushes", path, "--set", "soft-eraser", file.to_str().unwrap()]).contains("added"));
+ "soft-eraser"
+ }
+ None => "eraser",
+ };
+ draw(&[
+ "stroke",
+ path,
+ "l1",
+ "--brush",
+ id,
+ "--size",
+ "40",
+ "--path",
+ "M20 50 L180 50",
+ ]);
+ let out = run(&["render", path, "-o", dir.join(format!("{name}.png")).to_str().unwrap()]);
+ let said = String::from_utf8_lossy(&out.stderr).to_string() + &String::from_utf8_lossy(&out.stdout);
+ (
+ draw(&["brushes", path]),
+ said.split("hash ").nth(1).unwrap()[..16].to_string(),
+ )
+ };
+ let (_, plain) = hash("plain", None);
+ let (listed, feathered) = hash("feathered", Some(eraser("0.8", "0")));
+ assert!(listed.contains("round 0.85 +feather"), "{listed}");
+ assert_ne!(plain, feathered, "the feather softens the edge");
+ let (listed, fringed) = hash("fringed", Some(eraser("0", "1")));
+ assert!(listed.contains("round 0.85 +fringe"), "{listed}");
+ assert_ne!(plain, fringed, "the fringe frays it");
+ let file = dir.join("bad.json");
+ std::fs::write(&file, eraser("2", "0")).unwrap();
+ let path = dir.join("plain.klad");
+ let out = run(&[
+ "brushes",
+ path.to_str().unwrap(),
+ "--set",
+ "bad",
+ file.to_str().unwrap(),
+ ]);
+ assert!(!out.status.success());
+ assert!(String::from_utf8_lossy(&out.stderr).contains("feather"));
+ let _ = std::fs::remove_dir_all(&dir);
+}
diff --git a/crates/core/src/brushes.rs b/crates/core/src/brushes.rs
index 02a80e4..546eeaa 100644
--- a/crates/core/src/brushes.rs
+++ b/crates/core/src/brushes.rs
@@ -80,6 +80,10 @@ pub struct BrushDef {
pub smoothing: f32,
#[serde(default, skip_serializing_if = "is_zero")]
pub body: f32,
+ #[serde(default, skip_serializing_if = "is_zero")]
+ pub feather: f32,
+ #[serde(default, skip_serializing_if = "is_zero")]
+ pub fringe: f32,
}
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
@@ -443,7 +447,9 @@ impl BrushDef {
within("taper out", self.taper[1], 0.0, 10_000.0)?;
within("stabilizer", self.stabilizer, 0.0, 500.0)?;
within("smoothing", self.smoothing, 0.0, 500.0)?;
- within("body", self.body, 0.0, 1.0)
+ within("body", self.body, 0.0, 1.0)?;
+ within("feather", self.feather, 0.0, 1.0)?;
+ within("fringe", self.fringe, 0.0, 1.0)
}
pub fn to_json(&self) -> Result<String> {
diff --git a/docs/DESIGN.md b/docs/DESIGN.md
index 8b49346..4585eaa 100644
--- a/docs/DESIGN.md
+++ b/docs/DESIGN.md
@@ -324,6 +324,7 @@ A mark its attached erasers wipe out completely (its coverage times what they le
- **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 `paint` is `wet` (wetness, pickup, dilution), `smudge` (strength) or `blend` (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; `oil` 0.45, `oil-load` 0.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 becomes `h (1 - 0.85 a) + body a' t`, with `a` the 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) and `t` that 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). The `relief` effect 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 by `softness`, and for each pixel moves the colour towards `highlight` where the slope faces `light`, 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 towards `shade` where 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 `feather` makes 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 ceiling `Edge::cover` already returns, with `soft` 0) 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. `fringe` scales 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's `seed`. 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 `path` can 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 and `klad strokes --json` fit a few points to a stroke (`pathedit::fit_polyline`, the simplification `klad path` uses, at 0.12 of the stroke's size between 1 and 6 px); A edits those points and writes the bent path as one `set`.
### Brushes as data
@@ -445,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 soft, which sets its tip's hardness for the E eraser and the pen's eraser end alike and is kept in the settings as `eraserSoft`, and a "more" menu for hardness, 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, 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.
- 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/format.md b/docs/format.md
index ef4d855..2f9e7b2 100644
--- a/docs/format.md
+++ b/docs/format.md
@@ -1,4 +1,4 @@
-_Last updated: 2026-11-09 18:00 (format `klad/6`, stroke files `KLST` version 2, brushes `klad-brush/1`)_
+_Last updated: 2026-11-09 21:30 (format `klad/6`, stroke files `KLST` version 2, brushes `klad-brush/1`)_
# The klad drawing format
@@ -315,6 +315,8 @@ When a lasso cuts across a mark, the mark is not split into new geometry: each p
| `taper` | `[in, out]` px, used when a stroke has none of its own |
| `stabilizer`, `smoothing` | how the editor steadies the pen while drawing (strokes store the result) |
| `body` | bristle body for bristle brushes |
+| `feather` | 0 to 1 (0): how far in a round tip's edge fades out, as one pass of an airbrush would; overlapping dabs don't build the fade back up, so it looks the same whatever the spacing. It takes the place of a harder `hardness` (the tip is solid up to the smaller of `hardness` and 1 - `feather`) |
+| `fringe` | 0 to 1 (0): frays the edge into streaks along the stroke, like a dry brush: the tip reaches out by a different amount for each bristle line across it, varying slowly along the stroke and seeded by the stroke's `seed`; up to about half the radius at 1, the middle stays whole |
A picture named by a tip or grain is `brushes/images/<name>.png` (dark is paint, or the alpha where there is one) when the bundle has it, and otherwise one of the pictures built into klad.
diff --git a/docs/guide/painting.md b/docs/guide/painting.md
index b3d88b9..6ef8a1b 100644
--- a/docs/guide/painting.md
+++ b/docs/guide/painting.md
@@ -1,4 +1,4 @@
-_Last updated: 2026-11-09 21:00_
+_Last updated: 2026-11-09 21:30_
# Painting
@@ -8,7 +8,7 @@ Paint with klad's brushes, blend colours on the canvas and make brushes of your
## Paint and erase
-Press **B** and paint on a paint layer. **E** switches to the eraser and back, and so does the eraser end of the pen. **[** and **]** make the brush smaller and bigger. With the eraser on, **soft** in the bar softens its edge.
+Press **B** and paint on a paint layer. **E** switches to the eraser and back, and so does the eraser end of the pen. **[** and **]** make the brush smaller and bigger. With the eraser on, **feather** in the bar fades its edge like an airbrush.
An eraser stroke stays with the strokes it erased, like a mask that travels with them: move them and the cut goes along, without biting into what they land on. Smudges and blends stay with their strokes the same way. [Move an eraser on its own](selecting.md#move-an-eraser-on-its-own) to change that.
diff --git a/docs/skill/SKILL.md b/docs/skill/SKILL.md
index ebba4d2..0828963 100644
--- a/docs/skill/SKILL.md
+++ b/docs/skill/SKILL.md
@@ -49,9 +49,9 @@ klad stroke art.klad l4 --brush ink --size 14 --color '#1b1b1b' --path 'M100 400
klad stroke art.klad l4 --brush ink --size 5 --taper 8,20 --path 'M100 100 L140 220'
```
-- `klad brushes art.klad` lists the brushes: the ones the bundle embeds and the library (`ink` inking pen, `pencil`, `marker`, `airbrush`, `soft`, `chalk`, `eraser`, and for painting `flat-bristle`, `round-bristle`, `sponge`, `fog`, `leaves`, `grass`, `splatter`, `wet`, `smudge`, `blender`, `dry-brush`, `two-tone`); the tip column says `+dual`, `+texture`, `+colour`, `+wet`, `+smudge`, `+blend` or `+body`. `--show <id>` prints one as JSON. A bundle keeps every brush it uses, so `ink` in an older bundle can be the older ink; `--brush` takes any id from that list.
+- `klad brushes art.klad` lists the brushes: the ones the bundle embeds and the library (`ink` inking pen, `pencil`, `marker`, `airbrush`, `soft`, `chalk`, `eraser`, and for painting `flat-bristle`, `round-bristle`, `sponge`, `fog`, `leaves`, `grass`, `splatter`, `wet`, `smudge`, `blender`, `dry-brush`, `two-tone`); the tip column says `+dual`, `+texture`, `+colour`, `+wet`, `+smudge`, `+blend`, `+body`, `+feather` or `+fringe`. `--show <id>` prints one as JSON. A bundle keeps every brush it uses, so `ink` in an older bundle can be the older ink; `--brush` takes any id from that list.
- Painting brushes: `wet` picks up the colour under it and mixes it in, `smudge` pulls paint along, `blender` softens what it crosses; all three read only the layer they paint on (paint the colours to mix on one layer). `leaves`, `grass` and `splatter` scatter their picture tips with jittered colour (`leaves` picks one of several leaf shapes per dab: `leaf`, `leaf-oval`, `leaf-lance`, `leaf-twig`; a tip takes more pictures as `{"image":{"image":"leaf","more":["leaf-oval","leaf-lobed"]}}`); `two-tone` paints `--second` at a light press and `--color` at a full one. `--second '#e0a040'` (`"second"` in `apply`) is the second colour for brushes with colour dynamics.
-- New brushes: write the JSON (copy one from `--show`; keys `tip` (`round`, `chalk` or `{"image":{"image":"name"}}`), `dual`, `grain` (`paper` or `image`, `strength`, `scale`, `contrast`, `pressure`), `color` (`hue`, `saturation`, `value`, `strokeHue`, ..., `pressure`, `along`), `paint` (`wet`, `smudge`, `blend`)) and `klad brushes art.klad --set my-oil brush.json` (`-` reads stdin). Pictures for tips and textures: `klad brushes art.klad --picture bark bark.png` (dark is paint, or the alpha). Ids and pictures are fixed once in the bundle, since strokes keep their brush.
+- New brushes: write the JSON (copy one from `--show`; keys `tip` (`round`, `chalk` or `{"image":{"image":"name"}}`), `dual`, `grain` (`paper` or `image`, `strength`, `scale`, `contrast`, `pressure`), `color` (`hue`, `saturation`, `value`, `strokeHue`, ..., `pressure`, `along`), `paint` (`wet`, `smudge`, `blend`), `feather` (0 to 1, a round tip's edge fades like an airbrush; a soft eraser is the eraser with `"feather":0.8`), `fringe` (0 to 1, the edge frays into streaks along the stroke, like a dry brush)) and `klad brushes art.klad --set my-oil brush.json` (`-` reads stdin). Pictures for tips and textures: `klad brushes art.klad --picture bark bark.png` (dark is paint, or the alpha). Ids and pictures are fixed once in the bundle, since strokes keep their brush.
- `--taper in,out` thins the first and last px of the line to a point whatever the pressure; without it the brush's taper applies (`ink` is `10,24`), `--taper 0,0` gives round ends. Short hatching wants about `8,20`, long contours `30,80`.
- `--pressure` spreads values evenly along the stroke; several subpaths in `--path` make several strokes. `--points 'x,y,p x,y,p'` gives explicit samples.
- In `apply`: `{"op":"stroke","layer":"l4","brush":"ink","size":14,"color":"#1b1b1b","path":"M...","pressure":[0.1,1,0.05],"taper":[12,30]}`.