Merge branch 'canvas-formats'

The canvas was two spin buttons, so "an Instagram story" or "A4 at 300 dpi"
was a number the user had to work out. src/core/canvas.cpp now holds one
table of standard sizes both front-ends read: a web format is a fixed pixel
size, a print format a sheet in millimetres that becomes pixels at a dpi.
Adding a format is a line in canvasFormats() — the dropdown, --format and
--help all walk the table.

The pixels stay the truth everywhere; renderChain never hears about formats.
A format is the presentation of a canvas, carried alongside the pixels in
Options and Project and empty for a custom size, and where one is named it
decides the pixels — so a project saved as A4 reopens as A4 rather than as
whatever it happened to measure.

In the interface a format fills the width and height in and greys them out
rather than hiding them: the size a sheet works out to is worth seeing. A
print format also shows a DPI row, and Custom hands the spins back keeping
the last size, which makes starting from a format and then tweaking it the
ordinary path.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

CLAUDE.md

@@ -14,8 +14,8 @@ Everything is warning-clean under `-Wall -Wextra -Wpedantic`; keep it that way.
 
 The test suite is a single hand-rolled binary (no framework), so there is no
 per-test filter: run `./build/tests/effector_tests` directly to see the section
-headings (`rng`, `registry`, `scanlines`, `blur`, `chain`, `project`, `image
-io`, `batch loading`) and the `ok`/`FAIL` lines. To iterate on one area, comment
+headings (`rng`, `registry`, `scanlines`, `tiles`, `blur`, `chain`, `project`,
+`image io`, `batch loading`) and the `ok`/`FAIL` lines. To iterate on one area, comment
 out the other blocks in `tests/core_tests.cpp` or add a new
 `std::cout << "section\n"` block — checks are plain
 `check(condition, "description")` calls and `main()` returns the failure count.
@@ -41,10 +41,15 @@ env -u WAYLAND_DISPLAY GDK_BACKEND=x11 DISPLAY=:79 build/effector ...
 
 `Effect` (`src/core/effect.hpp`) exposes `params()` returning `std::vector<ParamSpec>`
 (`src/core/params.hpp`). Those specs are the *only* thing the GUI and CLI know
-about an effect: `src/gui/window.cpp` builds SpinButtons/Switches/DropDowns from
-them and `src/cli/options.cpp` generates flags from them (`strip_height` →
-`--strip-height`). Never add effect-specific branches to the GUI or the parser —
-add a `ParamSpec` instead. Values travel as `ParamValues` (a
+about an effect: `src/gui/window.cpp` builds SpinButtons/Switches/DropDowns/file
+choosers from them and `src/cli/options.cpp` generates flags from them
+(`strip_height` → `--strip-height`). Never add effect-specific branches to the
+GUI or the parser — add a `ParamSpec` instead. A `Path` param names a file on
+disk; like a source path it is written relative to the project folder. A `Text`
+param is free-form text the user types, and a `Color` param is a colour written
+`#rrggbb` (`parseColor`/`formatColor`/`paramColor` in `src/core/params.hpp`),
+shown as a colour button in the interface. Values
+travel as `ParamValues` (a
 `map<string, variant<long,double,bool,string>>`), read back with
 `paramInt`/`paramDouble`/`paramBool`/`paramChoice`.
 
@@ -75,6 +80,17 @@ CLI builds it from repeated `-e`: `-e scanlines --strip-height 6 -e blur
 (`src/cli/options.cpp`) hands each flag to the stage whose effect declares it —
 two effects must not declare the same param key.
 
+### The canvas is a format or plain pixels
+
+`src/core/canvas.cpp` holds the one table of standard sizes both front-ends
+offer: web formats are a fixed pixel size, print formats a sheet in millimetres
+that becomes pixels at a dpi. Adding a format is a line in `canvasFormats()` —
+the dropdown, `--format` and `--help` all walk that table. The pixels stay the
+truth everywhere (`renderChain` never hears about formats); a format is the
+*presentation* of a canvas, carried alongside the pixels in `Options` and
+`Project` and empty for a custom size. Where a format is named it decides the
+pixels, so a project saved as A4 reopens as A4.
+
 ### Projects are plain JSON
 
 `src/core/project.cpp` reads and writes the whole setup — source paths, the
@@ -94,7 +110,8 @@ is discarded rather than mixed into the new project (`dropLoadedImages_`).
 ### Two link targets, deliberately
 
 `effector_core` (static) holds image IO, params, effects, rng and links only
-`gdk-pixbuf-2.0` + Threads — **no gtkmm, no display**. The `effector` executable
+`gdk-pixbuf-2.0`, `pangocairo` (the text effect's glyphs; Pango and Cairo need
+no display) + Threads — **no gtkmm, no display**. The `effector` executable
 adds `src/main.cpp`, `src/cli/`, `src/gui/` and links gtkmm. Keep GTK out of
 `src/core/` and `src/effects/`; the tests link the core alone and rely on this.
 
@@ -103,7 +120,10 @@ adds `src/main.cpp`, `src/cli/`, `src/gui/` and links gtkmm. Keep GTK out of
 `Rng` (`src/core/rng.hpp`) is a hand-written xoshiro256\*\* rather than
 `<random>`, because libstdc++ distributions are not portable across
 implementations. Same sources + settings + seed must produce byte-identical
-output on any machine — the tests assert this. Effects must draw *every* random
+output on any machine — the tests assert this. The one thing outside this is the
+text effect's glyphs, which are whatever shapes the machine's fonts and
+fontconfig give: everything it is handed, the rng included, is still used the
+same way. Effects must draw *every* random
 value from the `Rng&` they are handed, and must not depend on thread scheduling:
 the scanlines effect first draws the whole strip plan serially from the rng,
 then copies pixels in parallel.

CMakeLists.txt

@@ -15,11 +15,15 @@ set(CMAKE_CXX_FLAGS_RELEASE "-O3 -DNDEBUG")
 find_package(PkgConfig REQUIRED)
 pkg_check_modules(GTKMM REQUIRED IMPORTED_TARGET gtkmm-4.0)
 pkg_check_modules(GDKPIXBUF REQUIRED IMPORTED_TARGET gdk-pixbuf-2.0)
+# Pango and Cairo draw the text effect's glyphs. Neither needs a display, so
+# the core stays headless.
+pkg_check_modules(PANGOCAIRO REQUIRED IMPORTED_TARGET pangocairo)
 
 find_package(Threads REQUIRED)
 
 # --- core: effects and image handling, no GUI ---------------------------------
 add_library(effector_core STATIC
+    src/core/canvas.cpp
     src/core/chain.cpp
     src/core/effect.cpp
     src/core/image.cpp
@@ -29,12 +33,16 @@ add_library(effector_core STATIC
     src/core/rng.cpp
     src/effects/blur.cpp
     src/effects/grain.cpp
+    src/effects/monochrome.cpp
+    src/effects/overlay.cpp
     src/effects/scanlines.cpp
+    src/effects/text.cpp
+    src/effects/tiles.cpp
 )
 target_include_directories(effector_core PUBLIC src)
 # The core is GUI-free: it only needs gdk-pixbuf for decoding and encoding,
 # so headless rendering works without a display.
-target_link_libraries(effector_core PUBLIC PkgConfig::GDKPIXBUF Threads::Threads)
+target_link_libraries(effector_core PUBLIC PkgConfig::GDKPIXBUF PkgConfig::PANGOCAIRO Threads::Threads)
 target_compile_options(effector_core PRIVATE -Wall -Wextra -Wpedantic)
 
 # --- application --------------------------------------------------------------

README.md

@@ -34,6 +34,22 @@ build/effector -o out.png -s 1920x1080 \
     --strip-height 8 --jitter 4 --seed 42 photo1.jpg photo2.png
 ```
 
+The canvas is either a size in pixels (`-s 1920x1080`, the Custom entry in the
+interface) or one of the standard formats, which `--help` lists in full:
+
+```bash
+build/effector -o post.png --format instagram-post -e tiles
+build/effector -o sheet.png --format a4 --dpi 300 -e scanlines
+```
+
+A web format — the Instagram sizes, Full HD, 4K UHD — is a fixed pixel size. A
+print format — A5, A4, A3, US Letter — is a sheet of paper, and becomes pixels
+at `--dpi` (36–1200, 300 by default), so A4 at 300 dpi is 2480×3508. Picking a
+format in the interface fills the width and height in and greys them out;
+Custom hands them back, keeping whatever the format last worked out to. A
+format is saved with the project, so an A4 project reopens as A4 rather than as
+the pixels it happened to be.
+
 Any option can also be passed when launching the interface; it becomes the
 starting state (images, canvas size, effect settings, seed).
 

src/cli/options.cpp

@@ -1,9 +1,11 @@
 #include "cli/options.hpp"
 
 #include <charconv>
+#include <cstdint>
 #include <cstring>
 #include <sstream>
 
+#include "core/canvas.hpp"
 #include "core/chain.hpp"
 #include "core/effect.hpp"
 #include "core/registry.hpp"
@@ -73,6 +75,20 @@ Options parseOptions(int argc, char** argv) {
                                   "each side between " + std::to_string(kMinCanvasSide) + " and " +
                                   std::to_string(kMaxCanvasSide));
             }
+        } else if (arg == "--format") {
+            const std::string value = requireValue(argc, argv, i, arg);
+            if (canvasFormatByKey(value) == nullptr) {
+                throw EffectError("unknown canvas format '" + value + "', see --help");
+            }
+            options.format = value;
+        } else if (arg == "--dpi") {
+            const std::string value = requireValue(argc, argv, i, arg);
+            long dpi = 0;
+            if (!parseLong(value, dpi) || dpi < kMinDpi || dpi > kMaxDpi) {
+                throw EffectError("invalid dpi '" + value + "', expected " +
+                                  std::to_string(kMinDpi) + "-" + std::to_string(kMaxDpi));
+            }
+            options.dpi = static_cast<int>(dpi);
         } else if (arg == "--seed") {
             const std::string value = requireValue(argc, argv, i, arg);
             long seed = 0;
@@ -110,6 +126,20 @@ Options parseOptions(int argc, char** argv) {
                     }
                     break;
                 }
+                case ParamSpec::Type::Path:
+                case ParamSpec::Type::Text:
+                    options.params[spec->key] = requireValue(argc, argv, i, arg);
+                    break;
+                case ParamSpec::Type::Color: {
+                    const std::string text = requireValue(argc, argv, i, arg);
+                    std::uint8_t rgb[3];
+                    if (!parseColor(text, rgb)) {
+                        throw EffectError(arg + ": '" + text +
+                                          "' is not a colour, expected e.g. #ff8800");
+                    }
+                    options.params[spec->key] = formatColor(rgb);
+                    break;
+                }
                 case ParamSpec::Type::Choice: {
                     const std::string text = requireValue(argc, argv, i, arg);
                     bool valid = false;
@@ -125,6 +155,11 @@ Options parseOptions(int argc, char** argv) {
             options.images.push_back(arg);
         }
     }
+    // Applied once everything is parsed, so --dpi may come before --format and
+    // so a format always wins over an -s given alongside it.
+    if (const auto* format = canvasFormatByKey(options.format)) {
+        canvasFormatSize(*format, options.dpi, options.width, options.height);
+    }
     if (options.effects.empty()) options.effects.push_back(defaultEffectName());
     return options;
 }
@@ -138,10 +173,21 @@ std::string usage(const char* programName) {
         << "  -o, --output FILE     render headlessly to this file and exit\n"
         << "  -s, --size WxH        canvas size, each side " << kMinCanvasSide << "-"
         << kMaxCanvasSide << " (default: 1920x1080)\n"
+        << "      --format NAME     canvas format, overrides --size (see below)\n"
+        << "      --dpi N           resolution of a print format, " << kMinDpi << "-" << kMaxDpi
+        << " (default: " << kDefaultDpi << ")\n"
         << "      --seed N          random seed (default: random)\n"
         << "      --list-effects    list available effects and exit\n"
         << "  -h, --help            show this help and exit\n";
 
+    out << "\nCanvas formats (--format):\n";
+    for (const auto& format : canvasFormats()) {
+        out << "  " << format.key;
+        if (format.key.size() < 20) out << std::string(20 - format.key.size(), ' ');
+        out << "  " << format.label << ", " << canvasFormatDetail(format)
+            << (format.print ? " at --dpi" : "") << "\n";
+    }
+
     for (const auto& effect : effects()) {
         out << "\n" << effect->title() << " options:\n";
         for (const auto& spec : effect->params()) {

src/cli/options.hpp

@@ -5,6 +5,7 @@
 #include <string>
 #include <vector>
 
+#include "core/canvas.hpp"
 #include "core/chain.hpp"
 #include "core/params.hpp"
 
@@ -16,6 +17,8 @@ struct Options {
     std::string output;              // empty -> launch the interface
     int width = 1920;
     int height = 1080;
+    std::string format;      // a named canvas format, empty for plain pixels
+    int dpi = kDefaultDpi;   // only a print format is rendered at a resolution
     std::optional<std::uint64_t> seed;
     ParamValues params;              // only the keys the user actually passed
     bool listEffects = false;

src/core/canvas.cpp

@@ -0,0 +1,76 @@
+#include "core/canvas.hpp"
+
+#include <algorithm>
+#include <cmath>
+#include <locale>
+#include <sstream>
+
+#include "core/chain.hpp"
+
+namespace effector {
+namespace {
+
+// 210 mm reads as "210", 215.9 mm as "215.9". In the C locale whatever the
+// user's is: gtkmm sets the global locale from the environment, so a stream
+// left to its default writes "210,0" on a German desktop.
+std::string millimetres(double mm) {
+    std::ostringstream out;
+    out.imbue(std::locale::classic());
+    out.setf(std::ios::fixed);
+    out.precision(1);
+    out << mm;
+    std::string text = out.str();
+    if (text.size() > 2 && text.compare(text.size() - 2, 2, ".0") == 0) text.resize(text.size() - 2);
+    return text;
+}
+
+}  // namespace
+
+const std::vector<CanvasFormat>& canvasFormats() {
+    // Written out once and handed back by reference: the table is fixed, and
+    // both front-ends walk it for their menu and their --help.
+    static const std::vector<CanvasFormat> formats = {
+        {"instagram-post", "Instagram post", false, 1080, 1080, 0.0, 0.0},
+        {"instagram-portrait", "Instagram portrait", false, 1080, 1350, 0.0, 0.0},
+        {"instagram-story", "Instagram story", false, 1080, 1920, 0.0, 0.0},
+        {"hd", "Full HD", false, 1920, 1080, 0.0, 0.0},
+        {"uhd", "4K UHD", false, 3840, 2160, 0.0, 0.0},
+        {"a5", "A5", true, 0, 0, 148.0, 210.0},
+        {"a4", "A4", true, 0, 0, 210.0, 297.0},
+        {"a3", "A3", true, 0, 0, 297.0, 420.0},
+        {"letter", "US Letter", true, 0, 0, 215.9, 279.4},
+    };
+    return formats;
+}
+
+const CanvasFormat* canvasFormatByKey(const std::string& key) {
+    if (key.empty()) return nullptr;
+    for (const auto& format : canvasFormats()) {
+        if (format.key == key) return &format;
+    }
+    return nullptr;
+}
+
+void canvasFormatSize(const CanvasFormat& format, int dpi, int& width, int& height) {
+    if (!format.print) {
+        width = format.width;
+        height = format.height;
+        return;
+    }
+    const int clamped = std::clamp(dpi, kMinDpi, kMaxDpi);
+    const auto pixels = [clamped](double mm) {
+        const long value = std::lround(mm / 25.4 * clamped);
+        return static_cast<int>(std::clamp<long>(value, kMinCanvasSide, kMaxCanvasSide));
+    };
+    width = pixels(format.widthMm);
+    height = pixels(format.heightMm);
+}
+
+std::string canvasFormatDetail(const CanvasFormat& format) {
+    if (format.print) {
+        return millimetres(format.widthMm) + " × " + millimetres(format.heightMm) + " mm";
+    }
+    return std::to_string(format.width) + " × " + std::to_string(format.height) + " px";
+}
+
+}  // namespace effector

src/core/canvas.hpp

@@ -0,0 +1,45 @@
+#pragma once
+
+#include <string>
+#include <vector>
+
+namespace effector {
+
+// A named canvas size both front-ends offer, so "A4 at 300 dpi" is one choice
+// rather than a pixel count the user has to work out. Web formats are a fixed
+// pixel size; print formats are a physical size in millimetres and only become
+// pixels once a resolution is given, which is why the dpi belongs to the
+// canvas rather than to any one format.
+struct CanvasFormat {
+    std::string key;    // written in a project and given to --format, e.g. "a4"
+    std::string label;  // shown in the interface, e.g. "A4"
+    bool print = false;
+    int width = 0;         // pixels, web formats only
+    int height = 0;        //
+    double widthMm = 0.0;  // millimetres, print formats only
+    double heightMm = 0.0;
+};
+
+// The dpi a print format is rendered at. The bounds keep A3 — the largest
+// sheet here — inside kMaxCanvasSide at the top end, and keep a sheet from
+// coming out too small to see at the bottom.
+inline constexpr int kMinDpi = 36;
+inline constexpr int kMaxDpi = 1200;
+inline constexpr int kDefaultDpi = 300;
+
+// In the order they are offered: the web formats first, then the paper sizes.
+const std::vector<CanvasFormat>& canvasFormats();
+
+// Null when the key names no format, which is how a custom canvas — the user's
+// own pixel sizes — is spelled everywhere: an empty or unknown key.
+const CanvasFormat* canvasFormatByKey(const std::string& key);
+
+// The pixel size of a format. `dpi` is ignored by a web format, which already
+// is a pixel size; a print format is rounded to the nearest pixel and clamped
+// to the canvas bounds.
+void canvasFormatSize(const CanvasFormat& format, int dpi, int& width, int& height);
+
+// "1080 × 1080 px" or "210 × 297 mm", for the dropdown and for --help.
+std::string canvasFormatDetail(const CanvasFormat& format);
+
+}  // namespace effector

src/core/effect.cpp

@@ -16,6 +16,9 @@ ParamValues Effect::defaults() const {
                 values[spec.key] = spec.defaultValue != 0.0;
                 break;
             case ParamSpec::Type::Choice:
+            case ParamSpec::Type::Path:
+            case ParamSpec::Type::Text:
+            case ParamSpec::Type::Color:
                 values[spec.key] = spec.defaultChoice;
                 break;
         }

src/core/image.cpp

@@ -43,7 +43,7 @@ Image::Image(int width, int height)
       pixels_(static_cast<std::size_t>(std::max(width, 0)) * 3 *
               static_cast<std::size_t>(std::max(height, 0))) {}
 
-Image Image::load(const std::string& path) {
+Image Image::load(const std::string& path, std::vector<std::uint8_t>* alphaOut) {
     GError* error = nullptr;
     PixbufPtr pixbuf = wrap(gdk_pixbuf_new_from_file(path.c_str(), &error));
     if (!pixbuf) throw std::runtime_error(takeError(error));
@@ -59,11 +59,23 @@ Image Image::load(const std::string& path) {
     const guint8* src = gdk_pixbuf_get_pixels(pixbuf.get());
 
     Image image(width, height);
+    if (alphaOut != nullptr) {
+        alphaOut->assign(static_cast<std::size_t>(std::max(width, 0)) *
+                             static_cast<std::size_t>(std::max(height, 0)),
+                         255);
+    }
     for (int y = 0; y < height; ++y) {
         const guint8* in = src + static_cast<std::size_t>(y) * srcStride;
         std::uint8_t* out = image.row(y);
         if (channels == 3) {
             std::memcpy(out, in, static_cast<std::size_t>(width) * 3);
+        } else if (alphaOut != nullptr) {
+            // Kept apart rather than flattened: the caller does the compositing.
+            std::uint8_t* alpha = alphaOut->data() + static_cast<std::size_t>(y) * width;
+            for (int x = 0; x < width; ++x) {
+                for (int c = 0; c < 3; ++c) out[x * 3 + c] = in[x * channels + c];
+                alpha[x] = in[x * channels + 3];
+            }
         } else {
             // Flatten alpha onto white, matching what a viewer would show.
             for (int x = 0; x < width; ++x) {

src/core/image.hpp

@@ -34,7 +34,11 @@ public:
 
     // Decodes via GdkPixbuf (PNG, JPEG, WebP, TIFF, BMP, ...), applying the
     // embedded EXIF orientation. Throws std::runtime_error on failure.
-    static Image load(const std::string& path);
+    // Transparency is flattened onto white, as a viewer would show it, unless
+    // `alphaOut` is given: it then receives one byte per pixel (255 throughout
+    // for a file without an alpha channel) and the colours are left untouched,
+    // which is what an effect compositing the image needs.
+    static Image load(const std::string& path, std::vector<std::uint8_t>* alphaOut = nullptr);
 
     // Encodes by file extension; png is used when the extension is unknown.
     void save(const std::string& path) const;

src/core/params.cpp

@@ -63,6 +63,37 @@ ParamSpec ParamSpec::makeChoice(std::string key, std::string label, std::string
     return spec;
 }
 
+ParamSpec ParamSpec::makePath(std::string key, std::string label, std::string help) {
+    ParamSpec spec;
+    spec.type = Type::Path;
+    spec.key = std::move(key);
+    spec.label = std::move(label);
+    spec.help = std::move(help);
+    return spec;
+}
+
+ParamSpec ParamSpec::makeText(std::string key, std::string label, std::string defaultText,
+                              std::string help) {
+    ParamSpec spec;
+    spec.type = Type::Text;
+    spec.key = std::move(key);
+    spec.label = std::move(label);
+    spec.help = std::move(help);
+    spec.defaultChoice = std::move(defaultText);
+    return spec;
+}
+
+ParamSpec ParamSpec::makeColor(std::string key, std::string label, std::string defaultColor,
+                               std::string help) {
+    ParamSpec spec;
+    spec.type = Type::Color;
+    spec.key = std::move(key);
+    spec.label = std::move(label);
+    spec.help = std::move(help);
+    spec.defaultChoice = std::move(defaultColor);
+    return spec;
+}
+
 namespace {
 
 const ParamValue* find(const ParamValues& values, const std::string& key) {
@@ -99,10 +130,61 @@ bool paramBool(const ParamValues& values, const std::string& key, bool fallback)
 
 std::string paramChoice(const ParamValues& values, const std::string& key,
                         const std::string& fallback) {
+    return paramText(values, key, fallback);
+}
+
+std::string paramText(const ParamValues& values, const std::string& key,
+                      const std::string& fallback) {
     if (const auto* value = find(values, key)) {
         if (const auto* v = std::get_if<std::string>(value)) return *v;
     }
     return fallback;
 }
 
+namespace {
+
+int hexDigit(char c) {
+    if (c >= '0' && c <= '9') return c - '0';
+    if (c >= 'a' && c <= 'f') return c - 'a' + 10;
+    if (c >= 'A' && c <= 'F') return c - 'A' + 10;
+    return -1;
+}
+
+}  // namespace
+
+bool parseColor(const std::string& text, std::uint8_t rgb[3]) {
+    std::string digits = text;
+    if (!digits.empty() && digits.front() == '#') digits.erase(digits.begin());
+    if (digits.size() != 3 && digits.size() != 6) return false;
+
+    int parsed[6];
+    for (std::size_t i = 0; i < digits.size(); ++i) {
+        parsed[i] = hexDigit(digits[i]);
+        if (parsed[i] < 0) return false;
+    }
+    for (int c = 0; c < 3; ++c) {
+        // "#abc" is the usual shorthand for "#aabbcc".
+        const int value = digits.size() == 3 ? parsed[c] * 17 : parsed[c * 2] * 16 + parsed[c * 2 + 1];
+        rgb[c] = static_cast<std::uint8_t>(value);
+    }
+    return true;
+}
+
+std::string formatColor(const std::uint8_t rgb[3]) {
+    static const char* const kDigits = "0123456789abcdef";
+    std::string text = "#";
+    for (int c = 0; c < 3; ++c) {
+        text += kDigits[rgb[c] >> 4];
+        text += kDigits[rgb[c] & 0x0F];
+    }
+    return text;
+}
+
+void paramColor(const ParamValues& values, const std::string& key, const std::string& fallback,
+                std::uint8_t rgb[3]) {
+    if (parseColor(paramText(values, key, fallback), rgb)) return;
+    if (parseColor(fallback, rgb)) return;
+    rgb[0] = rgb[1] = rgb[2] = 0;
+}
+
 }  // namespace effector

src/core/params.hpp

@@ -1,5 +1,6 @@
 #pragma once
 
+#include <cstdint>
 #include <map>
 #include <string>
 #include <variant>
@@ -10,7 +11,7 @@ namespace effector {
 // Declarative description of one effect knob. The GUI turns these into widgets
 // and the CLI turns them into flags, so neither knows about any effect.
 struct ParamSpec {
-    enum class Type { Int, Double, Bool, Choice };
+    enum class Type { Int, Double, Bool, Choice, Path, Text, Color };
 
     Type type = Type::Int;
     std::string key;
@@ -35,6 +36,18 @@ struct ParamSpec {
                               std::string help = {});
     static ParamSpec makeChoice(std::string key, std::string label, std::string defaultChoice,
                                 std::vector<std::string> choices, std::string help = {});
+    // A path to a file on disk, empty by default: a chooser in the interface, a
+    // flag taking any string on the command line, written relative to the
+    // project folder so that a folder still opens after it is moved.
+    static ParamSpec makePath(std::string key, std::string label, std::string help = {});
+    // Free-form text the user types: an entry in the interface, a flag taking
+    // any string on the command line.
+    static ParamSpec makeText(std::string key, std::string label, std::string defaultText,
+                              std::string help = {});
+    // A colour written "#rrggbb": a colour button in the interface, the same
+    // spelling as a flag value.
+    static ParamSpec makeColor(std::string key, std::string label, std::string defaultColor,
+                               std::string help = {});
 };
 
 using ParamValue = std::variant<long, double, bool, std::string>;
@@ -45,5 +58,17 @@ double paramDouble(const ParamValues& values, const std::string& key, double fal
 bool paramBool(const ParamValues& values, const std::string& key, bool fallback);
 std::string paramChoice(const ParamValues& values, const std::string& key,
                         const std::string& fallback);
+std::string paramText(const ParamValues& values, const std::string& key,
+                      const std::string& fallback);
+
+// Reads "#rgb" or "#rrggbb" (the leading hash optional) into three bytes.
+// Returns false and leaves `rgb` untouched for anything else, so a malformed
+// value falls back to the default rather than painting an arbitrary colour.
+bool parseColor(const std::string& text, std::uint8_t rgb[3]);
+std::string formatColor(const std::uint8_t rgb[3]);
+
+// The colour of a param, or `fallback` when the value does not parse.
+void paramColor(const ParamValues& values, const std::string& key, const std::string& fallback,
+                std::uint8_t rgb[3]);
 
 }  // namespace effector

src/core/project.cpp

@@ -1,12 +1,16 @@
 #include "core/project.hpp"
 
+#include <charconv>
 #include <cmath>
+#include <cstdint>
 #include <cstdio>
 #include <cstdlib>
 #include <filesystem>
 #include <fstream>
+#include <locale>
 #include <sstream>
 
+#include "core/canvas.hpp"
 #include "core/effect.hpp"
 #include "core/registry.hpp"
 
@@ -24,7 +28,7 @@ struct Json {
     bool boolean = false;
     double number = 0.0;
     bool integral = true;  // written without a fraction or exponent
-    std::string text;
+    std::string text;      // the string, or the digits a number was written as
     std::vector<Json> items;
     std::vector<std::pair<std::string, Json>> members;
 
@@ -226,11 +230,15 @@ private:
         Json value;
         value.kind = Json::Kind::Number;
         value.integral = integral;
-        try {
-            value.number = std::stod(text_.substr(start, pos_ - start));
-        } catch (const std::exception&) {
+        // from_chars rather than stod: a number in JSON always has a point for
+        // a decimal mark, whatever LC_NUMERIC says the user's decimal mark is.
+        const char* const first = text_.data() + start + (text_[start] == '+' ? 1 : 0);
+        const char* const last = text_.data() + pos_;
+        const auto parsed = std::from_chars(first, last, value.number);
+        if (parsed.ec != std::errc() || parsed.ptr != last) {
             fail("'" + text_.substr(start, pos_ - start) + "' is not a number");
         }
+        value.text.assign(first, last);  // kept whole for the seed, see below
         return value;
     }
 
@@ -263,6 +271,7 @@ std::string quote(const std::string& text) {
 
 std::string number(double value, int digits) {
     std::ostringstream out;
+    out.imbue(std::locale::classic());
     out.setf(std::ios::fixed);
     out.precision(digits);
     out << value;
@@ -298,6 +307,18 @@ int canvasSide(const Json& value, const char* what) {
     return static_cast<int>(value.number);
 }
 
+// Checked as a double before narrowing, exactly as a canvas side is.
+int canvasDpi(const Json& value) {
+    if (value.kind != Json::Kind::Number || value.number != std::trunc(value.number)) {
+        throw EffectError("the canvas dpi must be a whole number");
+    }
+    if (!(value.number >= kMinDpi) || !(value.number <= kMaxDpi)) {
+        throw EffectError("the canvas dpi must be between " + std::to_string(kMinDpi) + " and " +
+                          std::to_string(kMaxDpi));
+    }
+    return static_cast<int>(value.number);
+}
+
 std::string resolve(const std::string& path, const std::string& directory) {
     std::filesystem::path file(path);
     if (file.is_absolute() || directory.empty()) return path;
@@ -307,11 +328,23 @@ std::string resolve(const std::string& path, const std::string& directory) {
 }  // namespace
 
 std::string projectToJson(const Project& project, const std::string& directory) {
+    // JSON is written in the C locale whatever the user's is: a decimal comma
+    // or a digit grouping would make the file something this reader — or any
+    // other — cannot read back. gtkmm sets the global locale from the
+    // environment, so a stream left to its default is the user's locale.
     std::ostringstream out;
+    out.imbue(std::locale::classic());
     out << "{\n";
     out << "  \"effector_project\": 1,\n";
-    out << "  \"canvas\": {\"width\": " << project.width << ", \"height\": " << project.height
-        << "},\n";
+    out << "  \"canvas\": {\"width\": " << project.width << ", \"height\": " << project.height;
+    // The pixels are always written, so a project opens the same in a reader
+    // that knows nothing of formats; the format and its dpi come after them
+    // and only when there is one to name.
+    if (const auto* format = canvasFormatByKey(project.format)) {
+        out << ", \"format\": " << quote(format->key);
+        if (format->print) out << ", \"dpi\": " << project.dpi;
+    }
+    out << "},\n";
     if (project.seed) out << "  \"seed\": " << *project.seed << ",\n";
 
     out << "  \"sources\": [";
@@ -346,8 +379,22 @@ std::string projectToJson(const Project& project, const std::string& directory)
                                   spec.digits);
                     break;
                 case ParamSpec::Type::Choice:
-                    out << quote(paramChoice(stage.values, spec.key, spec.defaultChoice));
+                case ParamSpec::Type::Text:
+                    out << quote(paramText(stage.values, spec.key, spec.defaultChoice));
                     break;
+                case ParamSpec::Type::Color: {
+                    std::uint8_t rgb[3];
+                    paramColor(stage.values, spec.key, spec.defaultChoice, rgb);
+                    out << quote(formatColor(rgb));
+                    break;
+                }
+                case ParamSpec::Type::Path: {
+                    // Written relative to the project folder, exactly as the
+                    // sources are, so a folder still opens once it is moved.
+                    const auto path = paramText(stage.values, spec.key, "");
+                    out << quote(path.empty() ? path : relativeTo(path, directory));
+                    break;
+                }
             }
         }
         out << (specs.empty() ? "}" : "\n      }") << "\n    }";
@@ -369,11 +416,32 @@ Project projectFromJson(const std::string& text, const std::string& directory) {
         if (const auto* height = canvas->member("height")) {
             project.height = canvasSide(*height, "height");
         }
+        if (const auto* dpi = canvas->member("dpi")) project.dpi = canvasDpi(*dpi);
+        // A format the build does not know is simply a custom canvas: the
+        // pixels were written too, so the project still renders as it was
+        // saved. Where the format is known it decides the pixels, so a
+        // hand-edited dpi takes effect and a preset stays true to its name.
+        if (const auto* name = canvas->member("format"); name != nullptr &&
+                                                         name->kind == Json::Kind::String) {
+            if (const auto* format = canvasFormatByKey(name->text)) {
+                project.format = format->key;
+                canvasFormatSize(*format, project.dpi, project.width, project.height);
+            }
+        }
     }
 
     if (const auto* seed = root.member("seed")) {
-        if (seed->kind == Json::Kind::Number) {
-            project.seed = static_cast<std::uint64_t>(seed->number);
+        // Taken from the digits rather than from the double: a 64-bit seed has
+        // more bits than a double has mantissa, and a seed that comes back off
+        // by a few is a project that no longer renders its own picture.
+        std::uint64_t value = 0;
+        const char* const first = seed->text.data();
+        const char* const last = first + seed->text.size();
+        if (seed->kind == Json::Kind::Number && seed->integral &&
+            std::from_chars(first, last, value).ptr == last) {
+            project.seed = value;
+        } else if (seed->kind == Json::Kind::Number) {
+            throw EffectError("the seed must be a whole number that fits in 64 bits");
         }
     }
 
@@ -418,6 +486,24 @@ Project projectFromJson(const std::string& text, const std::string& directory) {
                     case ParamSpec::Type::Double:
                         if (value->kind == Json::Kind::Number) stage.values[spec.key] = value->number;
                         break;
+                    case ParamSpec::Type::Path:
+                        if (value->kind == Json::Kind::String) {
+                            stage.values[spec.key] =
+                                value->text.empty() ? value->text : resolve(value->text, directory);
+                        }
+                        break;
+                    case ParamSpec::Type::Text:
+                        if (value->kind == Json::Kind::String) stage.values[spec.key] = value->text;
+                        break;
+                    case ParamSpec::Type::Color: {
+                        // A colour that does not parse keeps the default,
+                        // exactly as an unknown choice does.
+                        std::uint8_t rgb[3];
+                        if (value->kind == Json::Kind::String && parseColor(value->text, rgb)) {
+                            stage.values[spec.key] = formatColor(rgb);
+                        }
+                        break;
+                    }
                     case ParamSpec::Type::Choice:
                         for (const auto& choice : spec.choices) {
                             if (value->kind == Json::Kind::String && value->text == choice) {

src/core/project.hpp

@@ -5,6 +5,7 @@
 #include <string>
 #include <vector>
 
+#include "core/canvas.hpp"
 #include "core/chain.hpp"
 #include "core/params.hpp"
 
@@ -18,6 +19,12 @@ struct Project {
     std::vector<ChainStage> stages;
     int width = 1920;
     int height = 1080;
+    // The named format the canvas came from, empty for a custom pixel size.
+    // The pixels above stay the truth for the render; this is what the
+    // interface puts back in its dropdown, and what a print format needs its
+    // resolution for.
+    std::string format;
+    int dpi = kDefaultDpi;
     std::optional<std::uint64_t> seed;
 };
 

src/core/registry.cpp

@@ -2,7 +2,11 @@
 
 #include "effects/blur.hpp"
 #include "effects/grain.hpp"
+#include "effects/monochrome.hpp"
+#include "effects/overlay.hpp"
 #include "effects/scanlines.hpp"
+#include "effects/text.hpp"
+#include "effects/tiles.hpp"
 
 namespace effector {
 
@@ -12,6 +16,10 @@ const std::vector<EffectPtr>& effects() {
         std::make_shared<ScanlinesEffect>(),
         std::make_shared<BlurEffect>(),
         std::make_shared<GrainEffect>(),
+        std::make_shared<MonochromeEffect>(),
+        std::make_shared<OverlayEffect>(),
+        std::make_shared<TextEffect>(),
+        std::make_shared<TilesEffect>(),
     };
     return registry;
 }

src/effects/monochrome.cpp

@@ -0,0 +1,105 @@
+#include "effects/monochrome.hpp"
+
+#include <algorithm>
+#include <array>
+#include <cstdint>
+
+#include "core/parallel.hpp"
+#include "effects/source_fill.hpp"
+
+namespace effector {
+
+const std::vector<ParamSpec>& MonochromeEffect::params() const {
+    static const std::vector<ParamSpec> specs = {
+        ParamSpec::makeChoice("mono_weighting", "Weighting", "luminance",
+                              {"luminance", "average", "red", "green", "blue"},
+                              "How the three channels are mixed into one grey; the colour names "
+                              "weigh that channel most, like a filter over the lens."),
+        ParamSpec::makeDouble("mono_contrast", "Contrast", 1.0, 0.1, 4.0,
+                              "Pull of the greys away from mid grey; 1 leaves them as they are."),
+        ParamSpec::makeChoice("mono_tone", "Toner", "none",
+                              {"none", "sepia", "selenium", "cyanotype"},
+                              "Tints the finished greys, as a darkroom toner would."),
+        ParamSpec::makeDouble("mono_strength", "Strength", 1.0, 0.0, 1.0,
+                              "How far the result is mixed back over the colour input."),
+    };
+    return specs;
+}
+
+namespace {
+
+// Channel weights summing to 1024, so a grey is one integer multiply-add away.
+std::array<int, 3> weightsFor(const std::string& weighting) {
+    if (weighting == "average") return {341, 342, 341};
+    if (weighting == "red") return {819, 154, 51};
+    if (weighting == "green") return {154, 819, 51};
+    if (weighting == "blue") return {154, 51, 819};
+    return {218, 732, 74};  // Rec. 709 luminance.
+}
+
+// Tint multipliers per channel, as 256ths.
+std::array<int, 3> tintFor(const std::string& tone) {
+    if (tone == "sepia") return {282, 251, 205};
+    if (tone == "selenium") return {261, 251, 271};
+    if (tone == "cyanotype") return {205, 243, 307};
+    return {256, 256, 256};
+}
+
+}  // namespace
+
+Image MonochromeEffect::render(const std::vector<Image>& sources, int width, int height, Rng& rng,
+                               const ParamValues& values) const {
+    if (width < 1 || height < 1) throw EffectError("Canvas size must be at least 1x1 pixels.");
+
+    const auto weights = weightsFor(paramChoice(values, "mono_weighting", "luminance"));
+    const auto tint = tintFor(paramChoice(values, "mono_tone", "none"));
+    const double contrast = std::clamp(paramDouble(values, "mono_contrast", 1.0), 0.1, 4.0);
+    const double strength = std::clamp(paramDouble(values, "mono_strength", 1.0), 0.0, 1.0);
+
+    Image canvas(width, height);
+    if (!sources.empty()) {
+        // Drawn before any threading, so that a seed always gives the same image.
+        const std::size_t index = rng.below(sources.size() - 1);
+        const Image& src = sources[index];
+        const int sx = static_cast<int>(rng.inRange(0, std::max(0, src.width() - width)));
+        const int sy = static_cast<int>(rng.inRange(0, std::max(0, src.height() - height)));
+        fillFromSource(canvas, src, sx, sy);
+    }
+
+    if (strength <= 0.0) return canvas;
+
+    // Contrast and toner only ever see one grey, so the whole tail of the
+    // conversion is a table: grey in, the three toned channels out.
+    std::array<std::array<std::uint8_t, 256>, 3> table{};
+    for (int grey = 0; grey < 256; ++grey) {
+        const int pulled =
+            std::clamp(static_cast<int>(128.0 + (grey - 128) * contrast + 0.5), 0, 255);
+        for (int c = 0; c < 3; ++c) {
+            table[static_cast<std::size_t>(c)][static_cast<std::size_t>(grey)] =
+                static_cast<std::uint8_t>(
+                    std::clamp(pulled * tint[static_cast<std::size_t>(c)] / 256, 0, 255));
+        }
+    }
+
+    const int mix = static_cast<int>(strength * 256.0 + 0.5);
+
+    parallelFor(static_cast<std::size_t>(height), [&](std::size_t begin, std::size_t end) {
+        for (std::size_t y = begin; y < end; ++y) {
+            std::uint8_t* out = canvas.row(static_cast<int>(y));
+            for (int x = 0; x < width; ++x) {
+                std::uint8_t* px = out + static_cast<std::size_t>(x) * 3;
+                const int grey =
+                    (px[0] * weights[0] + px[1] * weights[1] + px[2] * weights[2]) / 1024;
+                for (int c = 0; c < 3; ++c) {
+                    const int toned = table[static_cast<std::size_t>(c)]
+                                           [static_cast<std::size_t>(std::clamp(grey, 0, 255))];
+                    px[c] = static_cast<std::uint8_t>(px[c] + (toned - px[c]) * mix / 256);
+                }
+            }
+        }
+    });
+
+    return canvas;
+}
+
+}  // namespace effector

src/effects/monochrome.hpp

@@ -0,0 +1,28 @@
+#pragma once
+
+#include "core/effect.hpp"
+
+namespace effector {
+
+// Converts its input to black and white, with the choice of channel weighting
+// a photographer would make behind the lens (a red filter darkening a sky, for
+// instance), an optional contrast pull and an optional toner. Like the blur it
+// needs no source images of its own, so it can lead a chain; given sources it
+// fills the canvas from one of them first.
+class MonochromeEffect : public Effect {
+   public:
+    std::string name() const override { return "monochrome"; }
+    std::string title() const override { return "Black and white"; }
+    std::string description() const override {
+        return "Converts its input to black and white with a choice of channel weighting, an "
+               "optional contrast pull and an optional toner; with sources loaded it fills the "
+               "canvas from a randomly chosen one first.";
+    }
+    const std::vector<ParamSpec>& params() const override;
+    bool needsSources() const override { return false; }
+
+    Image render(const std::vector<Image>& sources, int width, int height, Rng& rng,
+                 const ParamValues& values) const override;
+};
+
+}  // namespace effector

src/effects/overlay.cpp

@@ -0,0 +1,220 @@
+#include "effects/overlay.hpp"
+
+#include <algorithm>
+#include <cmath>
+#include <cstdint>
+
+#include "core/parallel.hpp"
+#include "effects/source_fill.hpp"
+
+namespace effector {
+
+const std::vector<ParamSpec>& OverlayEffect::params() const {
+    static const std::vector<ParamSpec> specs = {
+        ParamSpec::makePath("overlay_image", "Image",
+                            "The picture laid over the input: a logo, a texture, a frame."),
+        ParamSpec::makeChoice("overlay_fit", "Fitting", "fit",
+                              {"fit", "fill", "stretch", "original", "tile"},
+                              "fit keeps the proportions and shows the whole image; fill keeps "
+                              "them and covers the canvas, cropping what does not fit; stretch "
+                              "distorts it to the canvas exactly; original leaves it at its own "
+                              "size; tile repeats it at its own size over the whole canvas."),
+        ParamSpec::makeDouble("overlay_scale", "Scale", 1.0, 0.05, 8.0,
+                              "Resizes the fitted image (the tile, for tiling) by this factor.",
+                              0.05),
+        ParamSpec::makeBool("overlay_center", "Centre", true,
+                            "Places the image in the middle of the canvas rather than at its top "
+                            "left corner; the offset is counted from there either way."),
+        ParamSpec::makeInt("overlay_offset_x", "Offset X", 0, -20000, 20000,
+                           "Moves the image right by this many pixels (left when negative)."),
+        ParamSpec::makeInt("overlay_offset_y", "Offset Y", 0, -20000, 20000,
+                           "Moves the image down by this many pixels (up when negative)."),
+        ParamSpec::makeDouble("overlay_opacity", "Opacity", 1.0, 0.0, 1.0,
+                              "How strongly the image is mixed over the input; its own "
+                              "transparency is taken into account as well."),
+    };
+    return specs;
+}
+
+namespace {
+
+// Where the overlay lands on the canvas, in canvas pixels.
+struct Placement {
+    int x = 0;
+    int y = 0;
+    int width = 1;
+    int height = 1;
+};
+
+Placement placeOverlay(const std::string& fit, double scale, bool centre, int offsetX, int offsetY,
+                       int srcWidth, int srcHeight, int width, int height) {
+    double drawWidth = srcWidth;
+    double drawHeight = srcHeight;
+    if (fit == "stretch") {
+        drawWidth = width;
+        drawHeight = height;
+    } else if (fit == "fit" || fit == "fill") {
+        const double byWidth = static_cast<double>(width) / srcWidth;
+        const double byHeight = static_cast<double>(height) / srcHeight;
+        const double factor = fit == "fit" ? std::min(byWidth, byHeight) : std::max(byWidth, byHeight);
+        drawWidth = srcWidth * factor;
+        drawHeight = srcHeight * factor;
+    }
+    // "original" and "tile" keep the file's own size; the scale below applies
+    // to every mode, so a fitted image can still be nudged a little larger.
+
+    Placement placement;
+    placement.width = std::max(1, static_cast<int>(std::lround(drawWidth * scale)));
+    placement.height = std::max(1, static_cast<int>(std::lround(drawHeight * scale)));
+    placement.x = centre ? (width - placement.width) / 2 : 0;
+    placement.y = centre ? (height - placement.height) / 2 : 0;
+    placement.x += offsetX;
+    placement.y += offsetY;
+    return placement;
+}
+
+int wrapIndex(int value, int limit) {
+    const int wrapped = value % limit;
+    return wrapped < 0 ? wrapped + limit : wrapped;
+}
+
+// Bilinear sample of the overlay at a point in its own pixel coordinates,
+// clamped at the edges or wrapped around when the image is being tiled.
+void sampleOverlay(const Image& src, const std::uint8_t* alpha, double u, double v, bool wrap,
+                   int rgb[3], int& outAlpha) {
+    const int w = src.width();
+    const int h = src.height();
+    const double fu = std::floor(u);
+    const double fv = std::floor(v);
+    const int u0 = static_cast<int>(fu);
+    const int v0 = static_cast<int>(fv);
+    const double du = u - fu;
+    const double dv = v - fv;
+
+    int xs[2];
+    int ys[2];
+    for (int i = 0; i < 2; ++i) {
+        xs[i] = wrap ? wrapIndex(u0 + i, w) : std::clamp(u0 + i, 0, w - 1);
+        ys[i] = wrap ? wrapIndex(v0 + i, h) : std::clamp(v0 + i, 0, h - 1);
+    }
+
+    double accum[3] = {0.0, 0.0, 0.0};
+    double accumAlpha = 0.0;
+    for (int j = 0; j < 2; ++j) {
+        const double wy = j == 0 ? 1.0 - dv : dv;
+        const std::uint8_t* row = src.row(ys[j]);
+        const std::uint8_t* alphaRow = alpha + static_cast<std::size_t>(ys[j]) * w;
+        for (int i = 0; i < 2; ++i) {
+            const double weight = wy * (i == 0 ? 1.0 - du : du);
+            const std::uint8_t* px = row + static_cast<std::size_t>(xs[i]) * 3;
+            const double alphaWeight = weight * alphaRow[xs[i]];
+            // Colour weighted by alpha: a transparent pixel in a PNG is usually
+            // black, and averaging it in unweighted draws a dark fringe around
+            // everything the image cuts out.
+            for (int c = 0; c < 3; ++c) accum[c] += px[c] * alphaWeight;
+            accumAlpha += alphaWeight;
+        }
+    }
+    outAlpha = std::clamp(static_cast<int>(accumAlpha + 0.5), 0, 255);
+    for (int c = 0; c < 3; ++c) {
+        rgb[c] = accumAlpha <= 0.0 ? 0
+                                   : std::clamp(static_cast<int>(accum[c] / accumAlpha + 0.5), 0,
+                                                255);
+    }
+}
+
+}  // namespace
+
+void OverlayEffect::loadOverlay(const std::string& path, Image& image,
+                                std::vector<std::uint8_t>& alpha) const {
+    std::lock_guard<std::mutex> lock(cacheMutex_);
+    if (cachedPath_ != path || cached_.empty()) {
+        std::vector<std::uint8_t> loadedAlpha;
+        Image loaded;
+        try {
+            loaded = Image::load(path, &loadedAlpha);
+        } catch (const std::exception& error) {
+            throw EffectError("Cannot read the overlay image '" + path + "': " + error.what());
+        }
+        if (loaded.empty()) throw EffectError("The overlay image '" + path + "' is empty.");
+        cached_ = std::move(loaded);
+        cachedAlpha_ = std::move(loadedAlpha);
+        cachedPath_ = path;
+    }
+    image = cached_;
+    alpha = cachedAlpha_;
+}
+
+Image OverlayEffect::render(const std::vector<Image>& sources, int width, int height, Rng& rng,
+                            const ParamValues& values) const {
+    if (width < 1 || height < 1) throw EffectError("Canvas size must be at least 1x1 pixels.");
+
+    Image canvas(width, height);
+    if (!sources.empty()) {
+        // Drawn before any threading, so that a seed always gives the same image.
+        const std::size_t index = rng.below(sources.size() - 1);
+        const Image& src = sources[index];
+        const int sx = static_cast<int>(rng.inRange(0, std::max(0, src.width() - width)));
+        const int sy = static_cast<int>(rng.inRange(0, std::max(0, src.height() - height)));
+        fillFromSource(canvas, src, sx, sy);
+    }
+
+    const std::string path = paramText(values, "overlay_image", "");
+    const double opacity = std::clamp(paramDouble(values, "overlay_opacity", 1.0), 0.0, 1.0);
+    // No image chosen yet is the state the interface starts in, not an error:
+    // the stage simply passes its input through.
+    if (path.empty() || opacity <= 0.0) return canvas;
+
+    Image overlay;
+    std::vector<std::uint8_t> alpha;
+    loadOverlay(path, overlay, alpha);
+
+    const std::string fit = paramChoice(values, "overlay_fit", "fit");
+    const Placement place = placeOverlay(
+        fit, std::clamp(paramDouble(values, "overlay_scale", 1.0), 0.05, 8.0),
+        paramBool(values, "overlay_center", true),
+        static_cast<int>(paramInt(values, "overlay_offset_x", 0)),
+        static_cast<int>(paramInt(values, "overlay_offset_y", 0)), overlay.width(),
+        overlay.height(), width, height);
+
+    const bool tiling = fit == "tile";
+    // Source pixels per canvas pixel, the same both ways for every mode but
+    // stretch, where the two axes are scaled apart on purpose.
+    const double stepX = static_cast<double>(overlay.width()) / place.width;
+    const double stepY = static_cast<double>(overlay.height()) / place.height;
+
+    const int firstRow = tiling ? 0 : std::max(0, place.y);
+    const int lastRow = tiling ? height : std::min(height, place.y + place.height);
+    const int firstCol = tiling ? 0 : std::max(0, place.x);
+    const int lastCol = tiling ? width : std::min(width, place.x + place.width);
+    if (firstRow >= lastRow || firstCol >= lastCol) return canvas;  // entirely off the canvas
+
+    const int mix = static_cast<int>(opacity * 255.0 + 0.5);
+    const std::uint8_t* alphaData = alpha.data();
+
+    parallelFor(static_cast<std::size_t>(lastRow - firstRow), [&](std::size_t begin,
+                                                                 std::size_t end) {
+        int rgb[3];
+        int pixelAlpha = 255;
+        for (std::size_t i = begin; i < end; ++i) {
+            const int y = firstRow + static_cast<int>(i);
+            const double v = (y - place.y + 0.5) * stepY - 0.5;
+            std::uint8_t* out = canvas.row(y);
+            for (int x = firstCol; x < lastCol; ++x) {
+                const double u = (x - place.x + 0.5) * stepX - 0.5;
+                sampleOverlay(overlay, alphaData, u, v, tiling, rgb, pixelAlpha);
+
+                const int weight = pixelAlpha * mix / 255;
+                if (weight == 0) continue;
+                std::uint8_t* px = out + static_cast<std::size_t>(x) * 3;
+                for (int c = 0; c < 3; ++c) {
+                    px[c] = static_cast<std::uint8_t>(px[c] + (rgb[c] - px[c]) * weight / 255);
+                }
+            }
+        }
+    });
+
+    return canvas;
+}
+
+}  // namespace effector

src/effects/overlay.hpp

@@ -0,0 +1,45 @@
+#pragma once
+
+#include <cstdint>
+#include <mutex>
+#include <string>
+#include <vector>
+
+#include "core/effect.hpp"
+
+namespace effector {
+
+// Lays one picture from disk over its input: a logo, a texture, a frame. The
+// overlay is fitted to the canvas in the chosen way, placed from the top left
+// or from the centre, nudged by an offset and mixed in by its opacity. Like the
+// blur it needs no source images of its own, so it can lead a chain; given
+// sources it fills the canvas from a randomly chosen one first.
+class OverlayEffect : public Effect {
+public:
+    std::string name() const override { return "overlay"; }
+    std::string title() const override { return "Image overlay"; }
+    std::string description() const override {
+        return "Lays a single image from disk over its input, fitted to the canvas, centred or "
+               "not, nudged by an offset and mixed in by its opacity.";
+    }
+    const std::vector<ParamSpec>& params() const override;
+    bool needsSources() const override { return false; }
+
+    Image render(const std::vector<Image>& sources, int width, int height, Rng& rng,
+                 const ParamValues& values) const override;
+
+private:
+    // The same file is re-read on every param change otherwise, and a render is
+    // a keystroke away in the interface. Renders can overlap, so it is guarded.
+    // Returns the decoded file and its alpha, reading it only when the path
+    // differs from the one already held.
+    void loadOverlay(const std::string& path, Image& image,
+                     std::vector<std::uint8_t>& alpha) const;
+
+    mutable std::mutex cacheMutex_;
+    mutable std::string cachedPath_;
+    mutable Image cached_;
+    mutable std::vector<std::uint8_t> cachedAlpha_;
+};
+
+}  // namespace effector

src/effects/text.cpp

@@ -0,0 +1,306 @@
+#include "effects/text.hpp"
+
+#include <pango/pangocairo.h>
+
+#include <algorithm>
+#include <cmath>
+#include <cstdint>
+
+#include "core/parallel.hpp"
+#include "effects/source_fill.hpp"
+
+namespace effector {
+
+const std::vector<ParamSpec>& TextEffect::params() const {
+    static const std::vector<ParamSpec> specs = {
+        ParamSpec::makeText("text", "Text", "Effector",
+                            "What to write; a line break starts a new line."),
+        ParamSpec::makeText("font_family", "Font", "Sans",
+                            "Font family, as it is named on this machine: Sans, Serif, Monospace, "
+                            "\"DejaVu Serif\", ..."),
+        ParamSpec::makeChoice("font_weight", "Weight", "normal",
+                              {"thin", "light", "normal", "medium", "semibold", "bold", "heavy"},
+                              "How bold the glyphs are; a family without the chosen weight is "
+                              "rendered in the nearest one it has."),
+        ParamSpec::makeBool("font_italic", "Italic", false, "Slants the glyphs."),
+        ParamSpec::makeDouble("font_size", "Size", 96.0, 4.0, 2000.0,
+                              "Height of the glyphs in pixels.", 1.0, 1),
+        ParamSpec::makeColor("text_color", "Colour", "#ffffff", "The colour of the glyphs."),
+        ParamSpec::makeChoice("text_align", "Alignment", "center", {"left", "center", "right"},
+                              "How several lines line up against each other."),
+        ParamSpec::makeInt("text_wrap", "Wrap width", 0, 0, 20000,
+                           "Breaks the text into lines no wider than this many pixels; 0 writes "
+                           "it as given."),
+        ParamSpec::makeChoice("text_box", "Box", "none", {"none", "colour", "image"},
+                              "What the text sits on: nothing, a filled rectangle, or a picture "
+                              "from disk cropped to the rectangle."),
+        ParamSpec::makeColor("box_color", "Box colour", "#000000",
+                            "The colour the box is filled with."),
+        ParamSpec::makePath("box_image", "Box picture",
+                            "The picture the box is filled with, scaled to cover it."),
+        ParamSpec::makeInt("box_padding", "Box padding", 24, 0, 2000,
+                           "How far the box reaches past the text on every side."),
+        ParamSpec::makeDouble("box_opacity", "Box opacity", 1.0, 0.0, 1.0,
+                              "How strongly the box is mixed over the input."),
+        ParamSpec::makeBool("text_center", "Centre", true,
+                            "Places the text in the middle of the canvas rather than at its top "
+                            "left corner; the offset is counted from there either way."),
+        ParamSpec::makeInt("text_offset_x", "Offset X", 0, -20000, 20000,
+                           "Moves the text right by this many pixels (left when negative)."),
+        ParamSpec::makeInt("text_offset_y", "Offset Y", 0, -20000, 20000,
+                           "Moves the text down by this many pixels (up when negative)."),
+        ParamSpec::makeDouble("text_opacity", "Text opacity", 1.0, 0.0, 1.0,
+                              "How strongly the glyphs are mixed over what is behind them."),
+    };
+    return specs;
+}
+
+namespace {
+
+// Small holders so that an EffectError thrown half way through still frees the
+// Cairo and Pango objects.
+struct SurfaceHandle {
+    cairo_surface_t* get = nullptr;
+    ~SurfaceHandle() {
+        if (get != nullptr) cairo_surface_destroy(get);
+    }
+};
+
+struct ContextHandle {
+    cairo_t* get = nullptr;
+    ~ContextHandle() {
+        if (get != nullptr) cairo_destroy(get);
+    }
+};
+
+struct LayoutHandle {
+    PangoLayout* get = nullptr;
+    ~LayoutHandle() {
+        if (get != nullptr) g_object_unref(get);
+    }
+};
+
+struct FontHandle {
+    PangoFontDescription* get = nullptr;
+    ~FontHandle() {
+        if (get != nullptr) pango_font_description_free(get);
+    }
+};
+
+PangoWeight weightFor(const std::string& name) {
+    if (name == "thin") return PANGO_WEIGHT_THIN;
+    if (name == "light") return PANGO_WEIGHT_LIGHT;
+    if (name == "medium") return PANGO_WEIGHT_MEDIUM;
+    if (name == "semibold") return PANGO_WEIGHT_SEMIBOLD;
+    if (name == "bold") return PANGO_WEIGHT_BOLD;
+    if (name == "heavy") return PANGO_WEIGHT_HEAVY;
+    return PANGO_WEIGHT_NORMAL;
+}
+
+PangoAlignment alignmentFor(const std::string& name) {
+    if (name == "left") return PANGO_ALIGN_LEFT;
+    if (name == "right") return PANGO_ALIGN_RIGHT;
+    return PANGO_ALIGN_CENTER;
+}
+
+// An RGB image plus its alpha as a Cairo ARGB32 surface, premultiplied, which
+// is the only layout Cairo paints from.
+cairo_surface_t* toSurface(const Image& image, const std::vector<std::uint8_t>& alpha) {
+    cairo_surface_t* surface =
+        cairo_image_surface_create(CAIRO_FORMAT_ARGB32, image.width(), image.height());
+    if (cairo_surface_status(surface) != CAIRO_STATUS_SUCCESS) {
+        cairo_surface_destroy(surface);
+        throw EffectError("Cannot hold the box picture in memory.");
+    }
+    const int stride = cairo_image_surface_get_stride(surface);
+    unsigned char* data = cairo_image_surface_get_data(surface);
+    const bool hasAlpha = alpha.size() == static_cast<std::size_t>(image.width()) *
+                                              static_cast<std::size_t>(image.height());
+
+    for (int y = 0; y < image.height(); ++y) {
+        const std::uint8_t* in = image.row(y);
+        auto* out = reinterpret_cast<std::uint32_t*>(data + static_cast<std::size_t>(y) * stride);
+        for (int x = 0; x < image.width(); ++x) {
+            const std::uint32_t a =
+                hasAlpha ? alpha[static_cast<std::size_t>(y) * image.width() + x] : 255;
+            const std::uint32_t r = in[x * 3 + 0] * a / 255;
+            const std::uint32_t g = in[x * 3 + 1] * a / 255;
+            const std::uint32_t b = in[x * 3 + 2] * a / 255;
+            out[x] = (a << 24) | (r << 16) | (g << 8) | b;
+        }
+    }
+    cairo_surface_mark_dirty(surface);
+    return surface;
+}
+
+void setColor(cairo_t* cr, const std::uint8_t rgb[3], double opacity) {
+    cairo_set_source_rgba(cr, rgb[0] / 255.0, rgb[1] / 255.0, rgb[2] / 255.0, opacity);
+}
+
+// Mixes the drawn layer, ARGB32 and premultiplied, over the canvas.
+void composite(Image& canvas, const cairo_surface_t* surface) {
+    const int stride = cairo_image_surface_get_stride(const_cast<cairo_surface_t*>(surface));
+    const unsigned char* data =
+        cairo_image_surface_get_data(const_cast<cairo_surface_t*>(surface));
+    const int width = canvas.width();
+
+    parallelFor(static_cast<std::size_t>(canvas.height()), [&](std::size_t begin, std::size_t end) {
+        for (std::size_t y = begin; y < end; ++y) {
+            const auto* in =
+                reinterpret_cast<const std::uint32_t*>(data + static_cast<std::size_t>(y) * stride);
+            std::uint8_t* out = canvas.row(static_cast<int>(y));
+            for (int x = 0; x < width; ++x) {
+                const std::uint32_t pixel = in[x];
+                const std::uint32_t a = pixel >> 24;
+                if (a == 0) continue;
+                // Premultiplied: the colour is already scaled by alpha, so the
+                // mix is an addition once the background is scaled down.
+                const std::uint32_t channel[3] = {(pixel >> 16) & 0xFF, (pixel >> 8) & 0xFF,
+                                                  pixel & 0xFF};
+                std::uint8_t* px = out + static_cast<std::size_t>(x) * 3;
+                for (int c = 0; c < 3; ++c) {
+                    const std::uint32_t value = channel[c] + px[c] * (255 - a) / 255;
+                    px[c] = static_cast<std::uint8_t>(std::min<std::uint32_t>(value, 255));
+                }
+            }
+        }
+    });
+}
+
+}  // namespace
+
+void TextEffect::loadBoxImage(const std::string& path, Image& image,
+                              std::vector<std::uint8_t>& alpha) const {
+    std::lock_guard<std::mutex> lock(cacheMutex_);
+    if (cachedPath_ != path || cached_.empty()) {
+        std::vector<std::uint8_t> loadedAlpha;
+        Image loaded;
+        try {
+            loaded = Image::load(path, &loadedAlpha);
+        } catch (const std::exception& error) {
+            throw EffectError("Cannot read the box picture '" + path + "': " + error.what());
+        }
+        if (loaded.empty()) throw EffectError("The box picture '" + path + "' is empty.");
+        cached_ = std::move(loaded);
+        cachedAlpha_ = std::move(loadedAlpha);
+        cachedPath_ = path;
+    }
+    image = cached_;
+    alpha = cachedAlpha_;
+}
+
+Image TextEffect::render(const std::vector<Image>& sources, int width, int height, Rng& rng,
+                         const ParamValues& values) const {
+    if (width < 1 || height < 1) throw EffectError("Canvas size must be at least 1x1 pixels.");
+
+    Image canvas(width, height);
+    if (!sources.empty()) {
+        // Drawn before any threading, so that a seed always gives the same image.
+        const std::size_t index = rng.below(sources.size() - 1);
+        const Image& src = sources[index];
+        const int sx = static_cast<int>(rng.inRange(0, std::max(0, src.width() - width)));
+        const int sy = static_cast<int>(rng.inRange(0, std::max(0, src.height() - height)));
+        fillFromSource(canvas, src, sx, sy);
+    }
+
+    const std::string text = paramText(values, "text", "");
+    const double textOpacity = std::clamp(paramDouble(values, "text_opacity", 1.0), 0.0, 1.0);
+    const std::string boxKind = paramChoice(values, "text_box", "none");
+    const double boxOpacity = std::clamp(paramDouble(values, "box_opacity", 1.0), 0.0, 1.0);
+    const bool drawsText = !text.empty() && textOpacity > 0.0;
+    const bool drawsBox = boxKind != "none" && boxOpacity > 0.0;
+    // No text typed yet is the state the interface starts in, not an error: the
+    // stage simply passes its input through.
+    if (!drawsText && !drawsBox) return canvas;
+
+    SurfaceHandle surface;
+    surface.get = cairo_image_surface_create(CAIRO_FORMAT_ARGB32, width, height);
+    if (cairo_surface_status(surface.get) != CAIRO_STATUS_SUCCESS) {
+        throw EffectError("Cannot hold the text layer in memory.");
+    }
+    ContextHandle cr;
+    cr.get = cairo_create(surface.get);
+
+    LayoutHandle layout;
+    layout.get = pango_cairo_create_layout(cr.get);
+    pango_layout_set_text(layout.get, text.c_str(), -1);
+    pango_layout_set_alignment(layout.get, alignmentFor(paramChoice(values, "text_align", "center")));
+    const int wrap = static_cast<int>(paramInt(values, "text_wrap", 0));
+    if (wrap > 0) {
+        pango_layout_set_width(layout.get, wrap * PANGO_SCALE);
+        pango_layout_set_wrap(layout.get, PANGO_WRAP_WORD_CHAR);
+    }
+
+    FontHandle font;
+    font.get = pango_font_description_new();
+    const std::string family = paramText(values, "font_family", "Sans");
+    pango_font_description_set_family(font.get, family.empty() ? "Sans" : family.c_str());
+    pango_font_description_set_weight(font.get, weightFor(paramChoice(values, "font_weight", "normal")));
+    pango_font_description_set_style(
+        font.get, paramBool(values, "font_italic", false) ? PANGO_STYLE_ITALIC : PANGO_STYLE_NORMAL);
+    // Absolute size: the param is in pixels, not in points at some unstated dpi.
+    pango_font_description_set_absolute_size(
+        font.get, std::clamp(paramDouble(values, "font_size", 96.0), 4.0, 2000.0) * PANGO_SCALE);
+    pango_layout_set_font_description(layout.get, font.get);
+
+    PangoRectangle logical;
+    pango_layout_get_pixel_extents(layout.get, nullptr, &logical);
+
+    const int padding = static_cast<int>(paramInt(values, "box_padding", 24));
+    const int boxWidth = std::max(1, logical.width + 2 * padding);
+    const int boxHeight = std::max(1, logical.height + 2 * padding);
+    const bool centre = paramBool(values, "text_center", true);
+    const double boxX = (centre ? (width - boxWidth) / 2.0 : 0.0) +
+                        static_cast<double>(paramInt(values, "text_offset_x", 0));
+    const double boxY = (centre ? (height - boxHeight) / 2.0 : 0.0) +
+                        static_cast<double>(paramInt(values, "text_offset_y", 0));
+
+    if (drawsBox) {
+        cairo_save(cr.get);
+        cairo_rectangle(cr.get, boxX, boxY, boxWidth, boxHeight);
+        cairo_clip(cr.get);
+        if (boxKind == "image") {
+            const std::string path = paramText(values, "box_image", "");
+            if (!path.empty()) {
+                Image picture;
+                std::vector<std::uint8_t> alpha;
+                loadBoxImage(path, picture, alpha);
+                SurfaceHandle fill;
+                fill.get = toSurface(picture, alpha);
+                // Scaled to cover the box, keeping its proportions, exactly as
+                // the overlay's "fill" does; what does not fit is clipped away.
+                const double factor = std::max(static_cast<double>(boxWidth) / picture.width(),
+                                               static_cast<double>(boxHeight) / picture.height());
+                cairo_translate(cr.get, boxX + (boxWidth - picture.width() * factor) / 2.0,
+                                boxY + (boxHeight - picture.height() * factor) / 2.0);
+                cairo_scale(cr.get, factor, factor);
+                cairo_set_source_surface(cr.get, fill.get, 0.0, 0.0);
+                cairo_pattern_set_filter(cairo_get_source(cr.get), CAIRO_FILTER_BILINEAR);
+                cairo_paint_with_alpha(cr.get, boxOpacity);
+            }
+        } else {
+            std::uint8_t rgb[3];
+            paramColor(values, "box_color", "#000000", rgb);
+            setColor(cr.get, rgb, boxOpacity);
+            cairo_paint(cr.get);
+        }
+        cairo_restore(cr.get);
+    }
+
+    if (drawsText) {
+        std::uint8_t rgb[3];
+        paramColor(values, "text_color", "#ffffff", rgb);
+        setColor(cr.get, rgb, textOpacity);
+        // logical.x/y are where the layout actually starts, which a wrapped or
+        // right-aligned layout shifts; subtracting them puts the glyphs inside
+        // the padding on every side.
+        cairo_move_to(cr.get, boxX + padding - logical.x, boxY + padding - logical.y);
+        pango_cairo_show_layout(cr.get, layout.get);
+    }
+
+    cairo_surface_flush(surface.get);
+    composite(canvas, surface.get);
+    return canvas;
+}
+
+}  // namespace effector

src/effects/text.hpp

@@ -0,0 +1,49 @@
+#pragma once
+
+#include <cstdint>
+#include <mutex>
+#include <string>
+#include <vector>
+
+#include "core/effect.hpp"
+
+namespace effector {
+
+// Writes a line (or several) over its input: a title, a caption, a watermark.
+// The family and the weight are chosen freely, and the text can sit on a box
+// filled with a colour or with a picture from disk. Like the blur and the
+// overlay it needs no source images of its own, so it can lead a chain; given
+// sources it fills the canvas from a randomly chosen one first.
+//
+// The glyphs come from Pango, so the exact pixels depend on the fonts the
+// machine has installed: a seed reproduces everything this effect draws, but a
+// machine without the chosen family renders the substitute its fontconfig
+// picks.
+class TextEffect : public Effect {
+public:
+    std::string name() const override { return "text"; }
+    std::string title() const override { return "Text"; }
+    std::string description() const override {
+        return "Writes text over its input in a chosen family, weight and size, optionally on a "
+               "box filled with a colour or with a picture.";
+    }
+    const std::vector<ParamSpec>& params() const override;
+    bool needsSources() const override { return false; }
+
+    Image render(const std::vector<Image>& sources, int width, int height, Rng& rng,
+                 const ParamValues& values) const override;
+
+private:
+    // The box picture is re-read on every param change otherwise, and a render
+    // is a keystroke away in the interface. Renders can overlap, so it is
+    // guarded.
+    void loadBoxImage(const std::string& path, Image& image,
+                      std::vector<std::uint8_t>& alpha) const;
+
+    mutable std::mutex cacheMutex_;
+    mutable std::string cachedPath_;
+    mutable Image cached_;
+    mutable std::vector<std::uint8_t> cachedAlpha_;
+};
+
+}  // namespace effector

src/effects/tiles.cpp

@@ -0,0 +1,180 @@
+#include "effects/tiles.hpp"
+
+#include <algorithm>
+#include <cstring>
+#include <vector>
+
+#include "core/parallel.hpp"
+#include "effects/source_fill.hpp"
+
+namespace effector {
+
+const std::vector<ParamSpec>& TilesEffect::params() const {
+    static const std::vector<ParamSpec> specs = {
+        ParamSpec::makeChoice("tile_layout", "Layout", "grid", {"grid", "brick", "scatter"},
+                              "grid lines the tiles up in rows and columns; brick packs every row "
+                              "on its own so the seams do not meet; scatter drops loose tiles over "
+                              "a filled background, overlapping."),
+        ParamSpec::makeInt("tile_width", "Tile width", 96, 1, 2048,
+                           "Width in pixels of each cut-out tile."),
+        ParamSpec::makeInt("tile_height", "Tile height", 96, 1, 2048,
+                           "Height in pixels of each cut-out tile."),
+        ParamSpec::makeInt("tile_jitter", "Size jitter", 0, 0, 512,
+                           "Random +/- variation added to both tile sizes (0 = uniform)."),
+        ParamSpec::makeInt("tile_count", "Tile count", 64, 1, 4096,
+                           "How many tiles are dropped on the canvas; scattered layout only."),
+        ParamSpec::makeBool("tile_keep_order", "Cycle images in order", false,
+                            "Take tiles from the images in order instead of picking randomly."),
+    };
+    return specs;
+}
+
+namespace {
+
+// One cut-out: `w` by `h` pixels taken from source `sourceIndex` at (sx, sy)
+// and laid down at (dstX, dstY).
+struct Tile {
+    int dstX;
+    int dstY;
+    int w;
+    int h;
+    int sourceIndex;
+    int sx;
+    int sy;
+};
+
+// Splits `span` into consecutive pieces of `base` pixels give or take `jitter`,
+// the last one clipped so that the pieces cover the span exactly.
+std::vector<int> planSpans(Rng& rng, int base, int jitter, int span) {
+    std::vector<int> spans;
+    spans.reserve(static_cast<std::size_t>(span / base) + 8);
+    int used = 0;
+    while (used < span) {
+        int size = base;
+        if (jitter > 0) size += static_cast<int>(rng.inRange(-jitter, jitter));
+        size = std::max(1, std::min(size, span - used));
+        spans.push_back(size);
+        used += size;
+    }
+    return spans;
+}
+
+void paintTile(Image& canvas, const Image& src, const Tile& tile) {
+    const int copyWidth = std::min(tile.w, src.width() - tile.sx);
+    const int copyHeight = std::min(tile.h, src.height() - tile.sy);
+    const std::size_t copyBytes = static_cast<std::size_t>(copyWidth) * 3;
+    const std::size_t total = static_cast<std::size_t>(tile.w) * 3;
+    const std::size_t offset = static_cast<std::size_t>(tile.dstX) * 3;
+
+    for (int line = 0; line < copyHeight; ++line) {
+        const std::uint8_t* in = src.row(tile.sy + line) + static_cast<std::size_t>(tile.sx) * 3;
+        std::uint8_t* out = canvas.row(tile.dstY + line) + offset;
+
+        std::memcpy(out, in, copyBytes);
+        // Repeat the cut sideways when the source is narrower than the tile,
+        // doubling the filled span on each pass.
+        std::size_t filled = copyBytes;
+        while (filled < total) {
+            const std::size_t chunk = std::min(filled, total - filled);
+            std::memcpy(out + filled, out, chunk);
+            filled += chunk;
+        }
+    }
+    // Same again downwards, out of the lines already written.
+    for (int line = copyHeight; line < tile.h; ++line) {
+        std::memcpy(canvas.row(tile.dstY + line) + offset,
+                    canvas.row(tile.dstY + (line % copyHeight)) + offset, total);
+    }
+}
+
+}  // namespace
+
+Image TilesEffect::render(const std::vector<Image>& sources, int width, int height, Rng& rng,
+                          const ParamValues& values) const {
+    if (sources.empty()) throw EffectError("No source images.");
+    if (width < 1 || height < 1) throw EffectError("Canvas size must be at least 1x1 pixels.");
+
+    const std::string layout = paramChoice(values, "tile_layout", "grid");
+    const int tileWidth = static_cast<int>(std::max(1L, paramInt(values, "tile_width", 96)));
+    const int tileHeight = static_cast<int>(std::max(1L, paramInt(values, "tile_height", 96)));
+    const int jitter = static_cast<int>(std::max(0L, paramInt(values, "tile_jitter", 0)));
+    const long count = std::max(1L, paramInt(values, "tile_count", 64));
+    const bool keepOrder = paramBool(values, "tile_keep_order", false);
+
+    Image canvas(width, height);
+
+    // The whole plan is drawn sequentially so that a seed always gives the same
+    // layout; only the pixel copying afterwards is parallelised.
+    std::size_t index = 0;
+    auto cut = [&](int dstX, int dstY, int w, int h) {
+        const int sourceIndex = keepOrder ? static_cast<int>(index++ % sources.size())
+                                          : static_cast<int>(rng.below(sources.size() - 1));
+        const Image& src = sources[static_cast<std::size_t>(sourceIndex)];
+        const int sx = static_cast<int>(rng.inRange(0, std::max(0, src.width() - w)));
+        const int sy = static_cast<int>(rng.inRange(0, std::max(0, src.height() - h)));
+        return Tile{dstX, dstY, w, h, sourceIndex, sx, sy};
+    };
+
+    std::vector<Tile> plan;
+    if (layout == "scatter") {
+        // Loose tiles leave gaps, so the canvas starts as one of the images
+        // rather than as black.
+        const std::size_t backdrop = rng.below(sources.size() - 1);
+        const Image& src = sources[backdrop];
+        const int sx = static_cast<int>(rng.inRange(0, std::max(0, src.width() - width)));
+        const int sy = static_cast<int>(rng.inRange(0, std::max(0, src.height() - height)));
+        fillFromSource(canvas, src, sx, sy);
+
+        plan.reserve(static_cast<std::size_t>(count));
+        for (long i = 0; i < count; ++i) {
+            int w = tileWidth;
+            int h = tileHeight;
+            if (jitter > 0) {
+                w += static_cast<int>(rng.inRange(-jitter, jitter));
+                h += static_cast<int>(rng.inRange(-jitter, jitter));
+            }
+            const int dstX = static_cast<int>(rng.inRange(0, width - 1));
+            const int dstY = static_cast<int>(rng.inRange(0, height - 1));
+            w = std::max(1, std::min(w, width - dstX));
+            h = std::max(1, std::min(h, height - dstY));
+            plan.push_back(cut(dstX, dstY, w, h));
+        }
+    } else {
+        const std::vector<int> rows = planSpans(rng, tileHeight, jitter, height);
+        // In a grid every row is cut at the same columns; in the brick layout
+        // each row is packed on its own, so the vertical seams do not line up.
+        std::vector<int> columns;
+        if (layout != "brick") columns = planSpans(rng, tileWidth, jitter, width);
+
+        plan.reserve(rows.size() * (columns.empty() ? 8 : columns.size()));
+        int y = 0;
+        for (const int rowHeight : rows) {
+            if (layout == "brick") columns = planSpans(rng, tileWidth, jitter, width);
+            int x = 0;
+            for (const int cellWidth : columns) {
+                plan.push_back(cut(x, y, cellWidth, rowHeight));
+                x += cellWidth;
+            }
+            y += rowHeight;
+        }
+    }
+
+    if (layout == "scatter") {
+        // Scattered tiles overlap, so they are painted in plan order on one
+        // thread: letting threads race for the same pixels would make the
+        // output depend on their scheduling.
+        for (const Tile& tile : plan) {
+            paintTile(canvas, sources[static_cast<std::size_t>(tile.sourceIndex)], tile);
+        }
+    } else {
+        parallelFor(plan.size(), [&](std::size_t begin, std::size_t end) {
+            for (std::size_t i = begin; i < end; ++i) {
+                paintTile(canvas, sources[static_cast<std::size_t>(plan[i].sourceIndex)], plan[i]);
+            }
+        });
+    }
+
+    return canvas;
+}
+
+}  // namespace effector

src/effects/tiles.hpp

@@ -0,0 +1,23 @@
+#pragma once
+
+#include "core/effect.hpp"
+
+namespace effector {
+
+// Covers the canvas with rectangular tiles cut at random positions from the
+// source images: the two-dimensional counterpart of the scanlines effect.
+class TilesEffect : public Effect {
+public:
+    std::string name() const override { return "tiles"; }
+    std::string title() const override { return "Tiles"; }
+    std::string description() const override {
+        return "Cuts rectangular tiles at random positions from the source images and lays "
+               "them over the canvas, in a grid, in offset rows or scattered about.";
+    }
+    const std::vector<ParamSpec>& params() const override;
+
+    Image render(const std::vector<Image>& sources, int width, int height, Rng& rng,
+                 const ParamValues& values) const override;
+};
+
+}  // namespace effector

src/gui/window.cpp

@@ -2,9 +2,12 @@
 
 #include <algorithm>
 #include <chrono>
+#include <cmath>
+#include <cstdint>
 #include <filesystem>
 #include <sstream>
 
+#include "core/canvas.hpp"
 #include "core/chain.hpp"
 #include "core/project.hpp"
 #include "core/registry.hpp"
@@ -173,28 +176,7 @@ Gtk::Widget& EffectorWindow::buildSidebar() {
     sidebar->append(sourcesExpander_);
 
     sidebar->append(*sectionLabel("Canvas"));
-    auto* grid = Gtk::make_managed<Gtk::Grid>();
-    grid->set_column_spacing(8);
-    grid->set_row_spacing(6);
-    widthSpin_.set_range(kMinCanvasSide, kMaxCanvasSide);
-    widthSpin_.set_increments(1, 100);
-    widthSpin_.set_value(1920);
-    heightSpin_.set_range(kMinCanvasSide, kMaxCanvasSide);
-    heightSpin_.set_increments(1, 100);
-    heightSpin_.set_value(1080);
-    for (auto* spin : {&widthSpin_, &heightSpin_}) {
-        spin->set_hexpand(true);
-        spin->signal_value_changed().connect(sigc::mem_fun(*this, &EffectorWindow::onParamChanged));
-    }
-    auto* widthLabel = Gtk::make_managed<Gtk::Label>("Width");
-    widthLabel->set_xalign(0.0F);
-    auto* heightLabel = Gtk::make_managed<Gtk::Label>("Height");
-    heightLabel->set_xalign(0.0F);
-    grid->attach(*widthLabel, 0, 0);
-    grid->attach(widthSpin_, 1, 0);
-    grid->attach(*heightLabel, 0, 1);
-    grid->attach(heightSpin_, 1, 1);
-    sidebar->append(*grid);
+    sidebar->append(buildCanvasSection());
 
     auto* seedBox = Gtk::make_managed<Gtk::Box>(Gtk::Orientation::HORIZONTAL, 8);
     auto* seedLabel = Gtk::make_managed<Gtk::Label>("Seed");
@@ -218,6 +200,122 @@ void EffectorWindow::updateSourcesLabel() {
                                           : "Source images (" + std::to_string(count) + ")");
 }
 
+// The canvas is either a named format — a web size, or a sheet of paper at a
+// resolution — or the user's own pixels. A format owns the two spin buttons
+// while it is picked, which is why they are shown greyed out rather than
+// hidden: the size a format works out to is worth seeing.
+Gtk::Widget& EffectorWindow::buildCanvasSection() {
+    auto* box = Gtk::make_managed<Gtk::Box>(Gtk::Orientation::VERTICAL, 6);
+
+    // Index 0 is "Custom"; every later index is canvasFormats()[index - 1].
+    std::vector<Glib::ustring> labels{"Custom"};
+    for (const auto& format : canvasFormats()) {
+        labels.push_back(format.label + " (" + canvasFormatDetail(format) + ")");
+    }
+    formatDrop_.set_model(Gtk::StringList::create(labels));
+    formatDrop_.set_selected(0);
+    formatDrop_.set_tooltip_text("Standard web and print sizes, or your own pixels");
+    formatDrop_.property_selected().signal_changed().connect(
+        sigc::mem_fun(*this, &EffectorWindow::syncCanvasWidgets));
+    box->append(formatDrop_);
+
+    auto* grid = Gtk::make_managed<Gtk::Grid>();
+    grid->set_column_spacing(8);
+    grid->set_row_spacing(6);
+    widthSpin_.set_range(kMinCanvasSide, kMaxCanvasSide);
+    widthSpin_.set_increments(1, 100);
+    widthSpin_.set_value(1920);
+    heightSpin_.set_range(kMinCanvasSide, kMaxCanvasSide);
+    heightSpin_.set_increments(1, 100);
+    heightSpin_.set_value(1080);
+    dpiSpin_.set_range(kMinDpi, kMaxDpi);
+    dpiSpin_.set_increments(1, 50);
+    dpiSpin_.set_value(kDefaultDpi);
+    for (auto* spin : {&widthSpin_, &heightSpin_, &dpiSpin_}) {
+        spin->set_hexpand(true);
+    }
+    for (auto* spin : {&widthSpin_, &heightSpin_}) {
+        spin->signal_value_changed().connect([this] {
+            if (!suspendCanvasSync_) onParamChanged();
+        });
+    }
+    // The dpi decides the pixels of a sheet, so moving it goes through the
+    // same path a format change does.
+    dpiSpin_.signal_value_changed().connect([this] {
+        if (!suspendCanvasSync_) syncCanvasWidgets();
+    });
+
+    auto* widthLabel = Gtk::make_managed<Gtk::Label>("Width");
+    widthLabel->set_xalign(0.0F);
+    auto* heightLabel = Gtk::make_managed<Gtk::Label>("Height");
+    heightLabel->set_xalign(0.0F);
+    auto* dpiLabel = Gtk::make_managed<Gtk::Label>("DPI");
+    dpiLabel->set_xalign(0.0F);
+    dpiLabel_ = dpiLabel;
+    grid->attach(*widthLabel, 0, 0);
+    grid->attach(widthSpin_, 1, 0);
+    grid->attach(*heightLabel, 0, 1);
+    grid->attach(heightSpin_, 1, 1);
+    grid->attach(*dpiLabel, 0, 2);
+    grid->attach(dpiSpin_, 1, 2);
+    box->append(*grid);
+
+    // Quietly: the sidebar is still being built, and nothing is to be rendered
+    // until the initial options or a project have had their say.
+    suspendCanvasSync_ = true;
+    syncCanvasWidgets();
+    suspendCanvasSync_ = false;
+    return *box;
+}
+
+std::string EffectorWindow::canvasFormatKey() const {
+    const auto selected = formatDrop_.get_selected();
+    if (selected == GTK_INVALID_LIST_POSITION || selected == 0) return {};
+    const auto index = static_cast<std::size_t>(selected) - 1;
+    const auto& formats = canvasFormats();
+    return index < formats.size() ? formats[index].key : std::string();
+}
+
+// A key the build does not know — an old project, or a hand-edited file — lands
+// on "Custom", which leaves the pixels the project carries alone.
+void EffectorWindow::setCanvasFormat(const std::string& key, int dpi) {
+    const bool suspended = suspendCanvasSync_;
+    suspendCanvasSync_ = true;
+    dpiSpin_.set_value(std::clamp(dpi, kMinDpi, kMaxDpi));
+    guint selected = 0;
+    const auto& formats = canvasFormats();
+    for (std::size_t i = 0; i < formats.size(); ++i) {
+        if (formats[i].key == key) selected = static_cast<guint>(i + 1);
+    }
+    formatDrop_.set_selected(selected);
+    syncCanvasWidgets();  // still suspended, so the spins follow without a render
+    suspendCanvasSync_ = suspended;
+}
+
+void EffectorWindow::syncCanvasWidgets() {
+    // Suspended means a caller is putting the canvas together — the initial
+    // options, or a project being opened — and will ask for the render itself.
+    const bool quiet = suspendCanvasSync_;
+    const auto* format = canvasFormatByKey(canvasFormatKey());
+    const bool print = format != nullptr && format->print;
+    dpiLabel_->set_visible(print);
+    dpiSpin_.set_visible(print);
+    widthSpin_.set_sensitive(format == nullptr);
+    heightSpin_.set_sensitive(format == nullptr);
+
+    if (format != nullptr) {
+        int width = 0;
+        int height = 0;
+        canvasFormatSize(*format, static_cast<int>(dpiSpin_.get_value()), width, height);
+        const bool suspended = suspendCanvasSync_;
+        suspendCanvasSync_ = true;  // one render for the change, not one per spin
+        widthSpin_.set_value(width);
+        heightSpin_.set_value(height);
+        suspendCanvasSync_ = suspended;
+    }
+    if (!quiet) onParamChanged();
+}
+
 Gtk::Widget& EffectorWindow::buildPreview() {
     picture_.set_can_shrink(true);
     picture_.set_content_fit(Gtk::ContentFit::CONTAIN);
@@ -293,6 +391,56 @@ void EffectorWindow::buildParamWidgets() {
                 widget = std::move(spin);
                 break;
             }
+            case ParamSpec::Type::Path: {
+                // An entry holding the path, with a chooser beside it; the
+                // entry is what paramValues() reads back.
+                auto box = std::make_unique<Gtk::Box>(Gtk::Orientation::HORIZONTAL, 6);
+                auto* entry = Gtk::make_managed<Gtk::Entry>();
+                entry->set_hexpand(true);
+                entry->set_text(paramText(stage.values, spec.key, ""));
+                entry->set_placeholder_text("No image chosen");
+                entry->signal_activate().connect(
+                    sigc::mem_fun(*this, &EffectorWindow::onParamChanged));
+                auto* choose = Gtk::make_managed<Gtk::Button>("Choose…");
+                const int index = selectedStage_;
+                const std::string key = spec.key;
+                const std::string title = spec.label;
+                choose->signal_clicked().connect(
+                    [this, index, key, title] { onChoosePath(index, key, title); });
+                box->append(*entry);
+                box->append(*choose);
+                paramWidgets_.push_back({spec, entry});
+                widget = std::move(box);
+                break;
+            }
+            case ParamSpec::Type::Text: {
+                auto entry = std::make_unique<Gtk::Entry>();
+                entry->set_text(paramText(stage.values, spec.key, spec.defaultChoice));
+                // Re-rendering on every keystroke would start a render per
+                // letter typed, so the text is taken when the entry is left or
+                // Enter is pressed.
+                entry->signal_activate().connect(
+                    sigc::mem_fun(*this, &EffectorWindow::onParamChanged));
+                auto focus = Gtk::EventControllerFocus::create();
+                focus->signal_leave().connect(
+                    sigc::mem_fun(*this, &EffectorWindow::onParamChanged));
+                entry->add_controller(focus);
+                widget = std::move(entry);
+                break;
+            }
+            case ParamSpec::Type::Color: {
+                auto button = std::make_unique<Gtk::ColorDialogButton>(Gtk::ColorDialog::create());
+                button->set_halign(Gtk::Align::START);
+                std::uint8_t rgb[3];
+                paramColor(stage.values, spec.key, spec.defaultChoice, rgb);
+                Gdk::RGBA colour;
+                colour.set_rgba(rgb[0] / 255.0, rgb[1] / 255.0, rgb[2] / 255.0, 1.0);
+                button->set_rgba(colour);
+                button->property_rgba().signal_changed().connect(
+                    sigc::mem_fun(*this, &EffectorWindow::onParamChanged));
+                widget = std::move(button);
+                break;
+            }
             case ParamSpec::Type::Choice: {
                 std::vector<Glib::ustring> choices(spec.choices.begin(), spec.choices.end());
                 auto dropdown = std::make_unique<Gtk::DropDown>();
@@ -311,7 +459,9 @@ void EffectorWindow::buildParamWidgets() {
         widget->set_hexpand(true);
         paramGrid_.attach(*label, 0, row);
         paramGrid_.attach(*widget, 1, row);
-        paramWidgets_.push_back({spec, widget.get()});
+        // A path attaches a box but reads back from the entry inside it, which
+        // it has registered itself.
+        if (spec.type != ParamSpec::Type::Path) paramWidgets_.push_back({spec, widget.get()});
         ownedWidgets_.push_back(std::move(label));
         ownedWidgets_.push_back(std::move(widget));
         ++row;
@@ -333,6 +483,20 @@ ParamValues EffectorWindow::paramValues() const {
             case ParamSpec::Type::Double:
                 values[entry.spec.key] = static_cast<Gtk::SpinButton*>(entry.widget)->get_value();
                 break;
+            case ParamSpec::Type::Path:
+            case ParamSpec::Type::Text:
+                values[entry.spec.key] =
+                    std::string(static_cast<Gtk::Entry*>(entry.widget)->get_text());
+                break;
+            case ParamSpec::Type::Color: {
+                const auto colour = static_cast<Gtk::ColorDialogButton*>(entry.widget)->get_rgba();
+                const std::uint8_t rgb[3] = {
+                    static_cast<std::uint8_t>(std::lround(colour.get_red() * 255.0)),
+                    static_cast<std::uint8_t>(std::lround(colour.get_green() * 255.0)),
+                    static_cast<std::uint8_t>(std::lround(colour.get_blue() * 255.0))};
+                values[entry.spec.key] = formatColor(rgb);
+                break;
+            }
             case ParamSpec::Type::Choice: {
                 const auto index = static_cast<Gtk::DropDown*>(entry.widget)->get_selected();
                 if (index < entry.spec.choices.size()) values[entry.spec.key] = entry.spec.choices[index];
@@ -361,6 +525,7 @@ void EffectorWindow::applyInitial(const Options& initial) {
 
     widthSpin_.set_value(initial.width);
     heightSpin_.set_value(initial.height);
+    setCanvasFormat(initial.format, initial.dpi);  // a format fills the spins itself
     if (initial.seed) {
         seed_ = *initial.seed;
         seedEntry_.set_text(std::to_string(seed_));
@@ -809,6 +974,36 @@ void EffectorWindow::onParamChanged() {
     requestRender();
 }
 
+void EffectorWindow::onChoosePath(int stage, const std::string& key, const std::string& label) {
+    auto dialog = Gtk::FileDialog::create();
+    dialog->set_title("Select the " + label);
+
+    auto filter = Gtk::FileFilter::create();
+    filter->set_name("Images");
+    for (const char* pattern : kImagePatterns) filter->add_pattern(pattern);
+    auto filters = Gio::ListStore<Gtk::FileFilter>::create();
+    filters->append(filter);
+    dialog->set_filters(filters);
+    dialog->set_default_filter(filter);
+
+    dialog->open(*this, [this, dialog, stage, key](const Glib::RefPtr<Gio::AsyncResult>& result) {
+        std::string path;
+        try {
+            const auto file = dialog->open_finish(result);
+            if (file) path = file->get_path();
+        } catch (const Glib::Error&) {
+            return;  // cancelled
+        }
+        if (path.empty() || stage < 0 || static_cast<std::size_t>(stage) >= stages_.size()) return;
+        // The widgets may be showing another stage by now: store what they hold
+        // first, then write the path into the stage that asked for it.
+        storeParams();
+        stages_[static_cast<std::size_t>(stage)].values[key] = path;
+        if (stage == selectedStage_) buildParamWidgets();
+        requestRender();
+    });
+}
+
 void EffectorWindow::onSeedEntered() {
     try {
         seed_ = std::stoull(seedEntry_.get_text());
@@ -1000,6 +1195,8 @@ Project EffectorWindow::currentProject() const {
     project.stages = stages_;
     project.width = static_cast<int>(widthSpin_.get_value());
     project.height = static_cast<int>(heightSpin_.get_value());
+    project.format = canvasFormatKey();
+    project.dpi = static_cast<int>(dpiSpin_.get_value());
     project.seed = seed_;
     return project;
 }
@@ -1016,6 +1213,7 @@ void EffectorWindow::applyProject(const Project& project, const std::string& pat
 
     widthSpin_.set_value(project.width);
     heightSpin_.set_value(project.height);
+    setCanvasFormat(project.format, project.dpi);
     seed_ = project.seed.value_or(Rng::randomSeed());
     seedEntry_.set_text(std::to_string(seed_));
 

src/gui/window.hpp

@@ -49,6 +49,14 @@ private:
     void cancelLoad();
     void appendSourceRow(const std::string& path);
     void updateSourcesLabel();  // the collapsed expander shows the count
+
+    Gtk::Widget& buildCanvasSection();
+    // "" while "Custom" is picked, otherwise the format's key.
+    std::string canvasFormatKey() const;
+    void setCanvasFormat(const std::string& key, int dpi);  // dropdown and dpi
+    // A format owns the pixel sizes, so the spins follow it and are greyed
+    // out; "Custom" hands them back to the user untouched.
+    void syncCanvasWidgets();
     void removeSource(Gtk::ListBoxRow* row);
 
     Gtk::Widget& buildChainSection();
@@ -75,6 +83,10 @@ private:
     void updateTitle();
 
     void onParamChanged();
+    // The chooser behind a Path param. The chosen file goes straight into the
+    // stage's values rather than into the widget, which may well have been
+    // rebuilt by the time the dialog comes back.
+    void onChoosePath(int stage, const std::string& key, const std::string& label);
     void onSeedEntered();
     void onRecreate();
     void onSave();
@@ -142,8 +154,14 @@ private:
     Gtk::Label* loadFileLabel_ = nullptr;
     Gtk::Expander sourcesExpander_;
     Gtk::ListBox sourceList_;
+    Gtk::DropDown formatDrop_;
     Gtk::SpinButton widthSpin_;
     Gtk::SpinButton heightSpin_;
+    Gtk::SpinButton dpiSpin_;
+    Gtk::Label* dpiLabel_ = nullptr;  // hidden along with the dpi spin
+    // Set while a format fills the spins, so their own handler does not queue
+    // a second render on top of the one the format change asks for.
+    bool suspendCanvasSync_ = false;
     Gtk::Grid paramGrid_;
     Gtk::Label paramHeading_;
     Gtk::Entry seedEntry_;

tests/core_tests.cpp

@@ -1,11 +1,14 @@
 // Small self-contained checks for the pieces that have no GUI dependency.
 
+#include <array>
 #include <atomic>
+#include <clocale>
 #include <cstdio>
 #include <cstdlib>
 #include <filesystem>
 #include <fstream>
 #include <iostream>
+#include <locale>
 #include <mutex>
 #include <optional>
 #include <string>
@@ -13,13 +16,18 @@
 #include <vector>
 
 #include "cli/options.hpp"
+#include "core/canvas.hpp"
 #include "core/chain.hpp"
 #include "core/project.hpp"
 #include "core/registry.hpp"
 #include "core/rng.hpp"
 #include "effects/blur.hpp"
 #include "effects/grain.hpp"
+#include "effects/monochrome.hpp"
+#include "effects/overlay.hpp"
 #include "effects/scanlines.hpp"
+#include "effects/text.hpp"
+#include "effects/tiles.hpp"
 
 namespace {
 
@@ -69,6 +77,25 @@ std::optional<std::pair<int, int>> canvasFromSize(const std::string& size) {
     }
 }
 
+// The options a whole command line ends up as, or nothing when the parser
+// refuses it.
+std::optional<effector::Options> parsedOptions(const std::vector<std::string>& args) {
+    std::vector<std::vector<char>> storage;
+    storage.push_back({'e', 'f', 'f', 'e', 'c', 't', 'o', 'r', '\0'});
+    for (const auto& arg : args) {
+        std::vector<char> buffer(arg.begin(), arg.end());
+        buffer.push_back('\0');
+        storage.push_back(std::move(buffer));
+    }
+    std::vector<char*> argv;
+    for (auto& buffer : storage) argv.push_back(buffer.data());
+    try {
+        return effector::parseOptions(static_cast<int>(argv.size()), argv.data());
+    } catch (const effector::EffectError&) {
+        return std::nullopt;
+    }
+}
+
 bool sameBytes(const effector::Image& a, const effector::Image& b) {
     if (a.width() != b.width() || a.height() != b.height()) return false;
     return std::equal(a.data(), a.data() + a.byteSize(), b.data());
@@ -106,6 +133,65 @@ effector::Image renderGrain(const std::vector<effector::Image>& sources, int wid
     return effect.render(sources, width, height, rng, merged);
 }
 
+effector::Image renderMono(const std::vector<effector::Image>& sources, int width, int height,
+                           std::uint64_t seed, const effector::ParamValues& values) {
+    effector::MonochromeEffect effect;
+    effector::Rng rng(seed);
+    auto merged = effect.defaults();
+    for (const auto& [key, value] : values) merged[key] = value;
+    return effect.render(sources, width, height, rng, merged);
+}
+
+effector::Image renderOverlay(const std::vector<effector::Image>& sources, int width, int height,
+                              const effector::ParamValues& values) {
+    effector::OverlayEffect effect;
+    effector::Rng rng(7);
+    auto merged = effect.defaults();
+    for (const auto& [key, value] : values) merged[key] = value;
+    return effect.render(sources, width, height, rng, merged);
+}
+
+effector::Image renderText(const std::vector<effector::Image>& sources, int width, int height,
+                           const effector::ParamValues& values) {
+    effector::TextEffect effect;
+    effector::Rng rng(7);
+    auto merged = effect.defaults();
+    for (const auto& [key, value] : values) merged[key] = value;
+    return effect.render(sources, width, height, rng, merged);
+}
+
+effector::Image renderTiles(const std::vector<effector::Image>& sources, int width, int height,
+                            std::uint64_t seed, const effector::ParamValues& values) {
+    effector::TilesEffect effect;
+    effector::Rng rng(seed);
+    auto merged = effect.defaults();
+    for (const auto& [key, value] : values) merged[key] = value;
+    return effect.render(sources, width, height, rng, merged);
+}
+
+// The three channels of one pixel, to read a placement off directly.
+std::array<int, 3> pixel(const effector::Image& image, int x, int y) {
+    const auto* px = image.row(y) + static_cast<std::size_t>(x) * 3;
+    return {px[0], px[1], px[2]};
+}
+
+bool isRed(const std::array<int, 3>& px) { return px[0] > 200 && px[1] < 60 && px[2] < 60; }
+bool isBlue(const std::array<int, 3>& px) { return px[2] > 200 && px[0] < 60 && px[1] < 60; }
+
+// A flat field of one colour, to read the channel weighting off directly.
+effector::Image solid(int width, int height, std::uint8_t r, std::uint8_t g, std::uint8_t b) {
+    effector::Image image(width, height);
+    for (int y = 0; y < height; ++y) {
+        auto* row = image.row(y);
+        for (int x = 0; x < width; ++x) {
+            row[x * 3 + 0] = r;
+            row[x * 3 + 1] = g;
+            row[x * 3 + 2] = b;
+        }
+    }
+    return image;
+}
+
 // A flat field of one shade, to measure what the grain does to it.
 effector::Image flat(int width, int height, std::uint8_t shade) {
     effector::Image image(width, height);
@@ -197,6 +283,81 @@ int main() {
         check(threw, "no sources throws");
     }
 
+    std::cout << "tiles\n";
+    {
+        std::vector<Image> sources = {gradient(1200, 800, 10), gradient(640, 480, 90),
+                                      gradient(300, 200, 200)};
+
+        for (const std::string layout : {"grid", "brick", "scatter"}) {
+            const ParamValues values = {{"tile_layout", layout},
+                                        {"tile_width", 70L},
+                                        {"tile_height", 50L},
+                                        {"tile_jitter", 12L}};
+            const auto first = renderTiles(sources, 400, 300, 1, values);
+            const auto again = renderTiles(sources, 400, 300, 1, values);
+            const auto other = renderTiles(sources, 400, 300, 2, values);
+
+            check(first.width() == 400 && first.height() == 300, layout + " has the requested size");
+            check(sameBytes(first, again), layout + ": same seed reproduces the image");
+            check(!sameBytes(first, other), layout + ": a different seed changes the image");
+        }
+
+        // With no jitter the grid cells line up: the gradient's red channel
+        // counts up with x inside a tile and only breaks at a cell boundary.
+        const auto aligned = renderTiles(sources, 400, 300, 5,
+                                         {{"tile_layout", std::string("grid")}, {"tile_width", 100L},
+                                          {"tile_height", 100L}});
+        bool onlyAtBoundaries = true;
+        for (int y = 0; y < aligned.height(); ++y) {
+            const auto* row = aligned.row(y);
+            for (int x = 1; x < aligned.width(); ++x) {
+                const bool breaks = row[x * 3] != ((row[(x - 1) * 3] + 1) & 0xFF);
+                if (breaks && x % 100 != 0) onlyAtBoundaries = false;
+            }
+        }
+        check(onlyAtBoundaries, "grid cells break only on the cell boundaries");
+
+        // One source smaller than a single tile: the cut is repeated to fill
+        // the cell, so the canvas is covered rather than left black.
+        std::vector<Image> small = {gradient(60, 40, 200)};
+        const auto covered = renderTiles(small, 500, 400, 9,
+                                         {{"tile_layout", std::string("brick")},
+                                          {"tile_width", 200L},
+                                          {"tile_height", 150L}});
+        bool filled = true;
+        for (int y = 0; y < covered.height(); ++y) {
+            const auto* row = covered.row(y);
+            for (int x = 0; x < covered.width(); ++x) filled = filled && row[x * 3 + 2] == 200;
+        }
+        check(filled, "a source smaller than a tile still covers the canvas");
+
+        const auto tiny = renderTiles(sources, 120, 90, 3,
+                                      {{"tile_width", 1L}, {"tile_height", 1L}});
+        check(tiny.width() == 120 && tiny.height() == 90, "tiles one pixel across");
+
+        const auto ordered = renderTiles(sources, 300, 200, 4,
+                                         {{"tile_width", 40L}, {"tile_keep_order", true}});
+        check(ordered.height() == 200, "keep_order fills the canvas");
+
+        // A single scattered tile leaves the rest of the canvas to the backdrop.
+        const auto sparse = renderTiles(small, 400, 300, 6,
+                                        {{"tile_layout", std::string("scatter")}, {"tile_count", 1L}});
+        bool backdrop = true;
+        for (int y = 0; y < sparse.height(); ++y) {
+            const auto* row = sparse.row(y);
+            for (int x = 0; x < sparse.width(); ++x) backdrop = backdrop && row[x * 3 + 2] == 200;
+        }
+        check(backdrop, "scattered tiles land on a filled backdrop");
+
+        bool threw = false;
+        try {
+            renderTiles({}, 100, 100, 1, {});
+        } catch (const EffectError&) {
+            threw = true;
+        }
+        check(threw, "no sources throws");
+    }
+
     std::cout << "blur\n";
     {
         std::vector<Image> sources = {gradient(1200, 800, 10), gradient(640, 480, 90)};
@@ -312,6 +473,361 @@ int main() {
         check(speckled && any, "without sources grain works on an empty canvas");
     }
 
+    std::cout << "monochrome\n";
+    {
+        std::vector<Image> sources = {gradient(1200, 800, 10), gradient(640, 480, 90)};
+
+        const auto first = renderMono(sources, 400, 300, 4, {});
+        const auto again = renderMono(sources, 400, 300, 4, {});
+        check(first.width() == 400 && first.height() == 300, "canvas has the requested size");
+        check(sameBytes(first, again), "same seed reproduces the image");
+
+        bool grey = true;
+        for (std::size_t i = 0; i + 2 < first.byteSize(); i += 3) {
+            grey = grey && first.data()[i] == first.data()[i + 1] &&
+                   first.data()[i + 1] == first.data()[i + 2];
+        }
+        check(grey, "every pixel comes out neutral grey");
+
+        // A pure red field: the luminance weighting keeps little of it, the red
+        // weighting nearly all, and the blue weighting almost none.
+        std::vector<Image> red = {solid(64, 64, 255, 0, 0)};
+        const auto viaLuma = renderMono(red, 64, 64, 1, {});
+        const auto viaRed = renderMono(red, 64, 64, 1, {{"mono_weighting", std::string("red")}});
+        const auto viaBlue = renderMono(red, 64, 64, 1, {{"mono_weighting", std::string("blue")}});
+        check(viaLuma.data()[0] > 40 && viaLuma.data()[0] < 70, "luminance darkens a pure red");
+        check(viaRed.data()[0] > 190, "the red weighting keeps a pure red light");
+        check(viaBlue.data()[0] < 50, "the blue weighting renders a pure red dark");
+
+        // Contrast works about mid grey: it leaves that alone and pushes the
+        // shades either side of it apart.
+        const auto midHard =
+            renderMono({solid(32, 32, 128, 128, 128)}, 32, 32, 1, {{"mono_contrast", 2.0}});
+        check(midHard.data()[0] >= 127 && midHard.data()[0] <= 129, "contrast pivots on mid grey");
+        const auto darkFlat = renderMono({solid(32, 32, 80, 80, 80)}, 32, 32, 1, {});
+        const auto darkHard =
+            renderMono({solid(32, 32, 80, 80, 80)}, 32, 32, 1, {{"mono_contrast", 2.0}});
+        check(darkHard.data()[0] < darkFlat.data()[0], "contrast deepens the shadows");
+
+        // The toners tint the greys, each in its own direction.
+        const auto sepia = renderMono({solid(32, 32, 128, 128, 128)}, 32, 32, 1,
+                                      {{"mono_tone", std::string("sepia")}});
+        check(sepia.data()[0] > sepia.data()[1] && sepia.data()[1] > sepia.data()[2],
+              "sepia warms the greys");
+        const auto cyan = renderMono({solid(32, 32, 128, 128, 128)}, 32, 32, 1,
+                                     {{"mono_tone", std::string("cyanotype")}});
+        check(cyan.data()[2] > cyan.data()[1] && cyan.data()[1] > cyan.data()[0],
+              "the cyanotype toner cools them");
+
+        // Strength mixes back towards the colour input: zero is a pass through,
+        // half sits between the two.
+        check(sameBytes(
+                  renderMono({solid(32, 32, 200, 40, 10)}, 32, 32, 1, {{"mono_strength", 0.0}}),
+                  solid(32, 32, 200, 40, 10)),
+              "zero strength leaves the colours untouched");
+        const auto half =
+            renderMono({solid(32, 32, 200, 40, 10)}, 32, 32, 1, {{"mono_strength", 0.5}});
+        const auto full = renderMono({solid(32, 32, 200, 40, 10)}, 32, 32, 1, {});
+        check(half.data()[0] > full.data()[0] && half.data()[0] < 200,
+              "half strength sits between the grey and the colour");
+
+        // Like blur and grain it needs no sources: with none it converts the
+        // empty canvas, which stays black.
+        const auto blank = renderMono({}, 50, 50, 1, {});
+        bool allBlack = blank.width() == 50 && blank.height() == 50;
+        for (std::size_t i = 0; i < blank.byteSize(); ++i) {
+            allBlack = allBlack && blank.data()[i] == 0;
+        }
+        check(allBlack, "without sources monochrome renders an empty canvas");
+    }
+
+    std::cout << "overlay\n";
+    {
+        const auto dir = std::filesystem::temp_directory_path() / "effector_test_overlay";
+        std::filesystem::create_directories(dir);
+        const auto logo = (dir / "logo.png").string();
+        solid(40, 20, 255, 0, 0).save(logo);  // wider than it is tall, to tell the fittings apart
+
+        const std::vector<Image> blue = {solid(100, 100, 0, 0, 255)};
+        const ParamValues at = {{"overlay_image", logo}, {"overlay_fit", std::string("original")}};
+
+        const auto centred = renderOverlay(blue, 100, 100, at);
+        check(isRed(pixel(centred, 50, 50)), "the overlay lands in the middle of the canvas");
+        check(isBlue(pixel(centred, 2, 2)), "and leaves the rest of the input alone");
+        check(isRed(pixel(centred, 30, 40)) && isBlue(pixel(centred, 29, 40)),
+              "centred, a 40x20 image starts 30 pixels in");
+
+        ParamValues corner = at;
+        corner["overlay_center"] = false;
+        const auto topLeft = renderOverlay(blue, 100, 100, corner);
+        check(isRed(pixel(topLeft, 0, 0)) && isBlue(pixel(topLeft, 41, 0)),
+              "without centring it sits in the top left corner");
+
+        ParamValues nudged = corner;
+        nudged["overlay_offset_x"] = 10L;
+        nudged["overlay_offset_y"] = 5L;
+        const auto moved = renderOverlay(blue, 100, 100, nudged);
+        check(isRed(pixel(moved, 10, 5)) && isBlue(pixel(moved, 9, 5)) && isBlue(pixel(moved, 10, 4)),
+              "the offset moves it right and down");
+
+        ParamValues back = at;
+        back["overlay_offset_x"] = -25L;
+        const auto half = renderOverlay(blue, 100, 100, back);
+        check(isRed(pixel(half, 5, 50)) && isBlue(pixel(half, 96, 50)),
+              "a negative offset moves it off the left edge, and it is clipped");
+
+        // Fitting: fit shows the whole image and keeps its proportions, so a
+        // 40x20 logo becomes 100x50 with a band of input above and below; fill
+        // and stretch and tile all cover the canvas.
+        ParamValues fitted = at;
+        fitted["overlay_fit"] = std::string("fit");
+        const auto fit = renderOverlay(blue, 100, 100, fitted);
+        check(isBlue(pixel(fit, 50, 10)) && isRed(pixel(fit, 50, 50)) && isRed(pixel(fit, 1, 50)),
+              "fit shows the whole image, in its own proportions");
+
+        for (const char* mode : {"fill", "stretch", "tile"}) {
+            ParamValues covering = at;
+            covering["overlay_fit"] = std::string(mode);
+            const auto image = renderOverlay(blue, 100, 100, covering);
+            bool everywhere = true;
+            for (int y = 0; y < 100; y += 7) {
+                for (int x = 0; x < 100; x += 7) everywhere = everywhere && isRed(pixel(image, x, y));
+            }
+            check(everywhere, std::string(mode) + " covers the whole canvas");
+        }
+
+        // Scale resizes what the fitting worked out: half of 100x50 is 50x25.
+        ParamValues scaled = fitted;
+        scaled["overlay_scale"] = 0.5;
+        const auto smaller = renderOverlay(blue, 100, 100, scaled);
+        check(isRed(pixel(smaller, 50, 50)) && isBlue(pixel(smaller, 20, 50)),
+              "the scale shrinks the fitted image about its centre");
+
+        // Opacity mixes over the input rather than replacing it.
+        ParamValues faint = at;
+        faint["overlay_opacity"] = 0.5;
+        const auto mixed = pixel(renderOverlay(blue, 100, 100, faint), 50, 50);
+        check(mixed[0] > 100 && mixed[0] < 155 && mixed[2] > 100 && mixed[2] < 155,
+              "half opacity sits between the overlay and the input");
+        check(sameBytes(renderOverlay(blue, 100, 100, {{"overlay_image", logo},
+                                                       {"overlay_opacity", 0.0}}),
+                        solid(100, 100, 0, 0, 255)),
+              "zero opacity leaves the input untouched");
+
+        // No image chosen is the state the interface starts in: a pass through.
+        check(sameBytes(renderOverlay(blue, 100, 100, {}), solid(100, 100, 0, 0, 255)),
+              "with no image chosen the stage passes its input through");
+
+        // Like blur and monochrome it needs no sources of its own.
+        check(!OverlayEffect().needsSources(), "the overlay can lead a chain");
+        const auto alone = renderOverlay({}, 60, 40, {{"overlay_image", logo},
+                                                      {"overlay_fit", std::string("stretch")}});
+        check(alone.width() == 60 && isRed(pixel(alone, 30, 20)),
+              "without sources it draws on an empty canvas");
+
+        bool threw = false;
+        try {
+            renderOverlay(blue, 100, 100, {{"overlay_image", std::string("/nope/missing.png")}});
+        } catch (const EffectError&) {
+            threw = true;
+        }
+        check(threw, "a missing overlay image is reported");
+
+        // The path travels with the project, written relative to its folder.
+        Project project;
+        project.width = 100;
+        project.height = 100;
+        project.stages.push_back({effectByName("overlay"), {{"overlay_image", logo}}});
+        const auto json = projectToJson(project, dir.string());
+        check(json.find("\"logo.png\"") != std::string::npos,
+              "an overlay image inside the project folder is written relative");
+        const auto reread = projectFromJson(json, dir.string());
+        check(paramText(reread.stages[0].values, "overlay_image", "") == logo,
+              "and comes back as the same file");
+
+        std::filesystem::remove_all(dir);
+    }
+
+    std::cout << "colour params\n";
+    {
+        std::uint8_t rgb[3] = {0, 0, 0};
+        check(parseColor("#ff8800", rgb) && rgb[0] == 255 && rgb[1] == 136 && rgb[2] == 0,
+              "a six digit colour is read");
+        check(parseColor("00FF80", rgb) && rgb[1] == 255 && rgb[2] == 128,
+              "the hash is optional and the case does not matter");
+        check(parseColor("#f80", rgb) && rgb[0] == 255 && rgb[1] == 136 && rgb[2] == 0,
+              "the three digit shorthand doubles each digit");
+        check(!parseColor("#12345", rgb) && !parseColor("#gg0000", rgb) && !parseColor("", rgb),
+              "anything else is refused");
+        const std::uint8_t written[3] = {1, 171, 255};
+        check(formatColor(written) == "#01abff", "a colour is written back as six digits");
+
+        // A value that does not parse falls back rather than painting
+        // something arbitrary.
+        std::uint8_t fallback[3] = {0, 0, 0};
+        paramColor({{"c", std::string("nonsense")}}, "c", "#102030", fallback);
+        check(fallback[0] == 0x10 && fallback[1] == 0x20 && fallback[2] == 0x30,
+              "a malformed colour keeps the default");
+
+        // Both new types survive a project round trip, and the reader drops a
+        // colour it cannot read exactly as it drops an unknown choice.
+        Project project;
+        project.width = 64;
+        project.height = 64;
+        project.stages.push_back({effectByName("text"),
+                                  {{"text", std::string("a \"quoted\" line")},
+                                   {"text_color", std::string("#ff0080")}}});
+        const auto reread = projectFromJson(projectToJson(project, ""), "");
+        check(paramText(reread.stages[0].values, "text", "") == "a \"quoted\" line",
+              "text with quotes in it survives a project round trip");
+        check(paramText(reread.stages[0].values, "text_color", "") == "#ff0080",
+              "and so does a colour");
+        const auto broken = projectFromJson(
+            "{\"chain\": [{\"effect\": \"text\", \"params\": {\"text_color\": \"#zz\"}}]}", "");
+        check(paramText(broken.stages[0].values, "text_color", "") == "#ffffff",
+              "a colour a project cannot be read keeps the effect's default");
+
+        // The command line refuses one too, rather than drawing black.
+        bool threw = false;
+        try {
+            const char* argv[] = {"effector", "-e", "text", "--text-color", "purple"};
+            parseOptions(5, const_cast<char**>(argv));
+        } catch (const EffectError&) {
+            threw = true;
+        }
+        check(threw, "an unparseable colour on the command line is reported");
+    }
+
+    std::cout << "text\n";
+    {
+        const std::vector<Image> blue = {solid(200, 120, 0, 0, 255)};
+        const ParamValues plain = {{"text", std::string("Hi")},
+                                   {"font_size", 60.0},
+                                   {"text_color", std::string("#ff0000")}};
+
+        // Counting the red pixels is how every placement below is read: the
+        // exact glyphs belong to whatever font this machine has.
+        const auto countRed = [](const Image& image, int x0, int y0, int x1, int y1) {
+            int found = 0;
+            for (int y = y0; y < y1; ++y) {
+                for (int x = x0; x < x1; ++x) {
+                    if (isRed(pixel(image, x, y))) ++found;
+                }
+            }
+            return found;
+        };
+
+        const auto centred = renderText(blue, 200, 120, plain);
+        check(countRed(centred, 60, 30, 140, 90) > 0, "the text lands in the middle of the canvas");
+        check(countRed(centred, 0, 0, 200, 120) == countRed(centred, 50, 20, 150, 100),
+              "and nothing is written outside it");
+
+        ParamValues corner = plain;
+        corner["text_center"] = false;
+        const auto topLeft = renderText(blue, 200, 120, corner);
+        check(countRed(topLeft, 0, 0, 100, 60) > 0 && countRed(topLeft, 100, 60, 200, 120) == 0,
+              "uncentred it starts at the top left corner");
+
+        ParamValues nudged = corner;
+        nudged["text_offset_x"] = 100L;
+        nudged["text_offset_y"] = 60L;
+        const auto moved = renderText(blue, 200, 120, nudged);
+        check(countRed(moved, 100, 60, 200, 120) > 0 && countRed(moved, 0, 0, 100, 60) == 0,
+              "the offset moves it down and to the right");
+
+        // Weight and size are the two knobs the glyphs themselves answer to: a
+        // bolder or a larger setting covers strictly more of the canvas.
+        ParamValues bold = plain;
+        bold["font_weight"] = std::string("heavy");
+        check(countRed(renderText(blue, 200, 120, bold), 0, 0, 200, 120) >
+                  countRed(centred, 0, 0, 200, 120),
+              "a heavier weight inks more pixels than a normal one");
+        ParamValues large = plain;
+        large["font_size"] = 90.0;
+        check(countRed(renderText(blue, 200, 120, large), 0, 0, 200, 120) >
+                  countRed(centred, 0, 0, 200, 120),
+              "and so does a larger size");
+
+        // The box is drawn under the text, in a colour or from a picture.
+        ParamValues boxed = plain;
+        boxed["text_box"] = std::string("colour");
+        boxed["box_color"] = std::string("#00ff00");
+        boxed["box_padding"] = 10L;
+        const auto onBox = renderText(blue, 200, 120, boxed);
+        const auto corner_px = pixel(onBox, 2, 2);
+        check(corner_px[2] > 200, "the box leaves the canvas outside it alone");
+        bool greenSomewhere = false;
+        for (int y = 0; y < 120 && !greenSomewhere; ++y) {
+            for (int x = 0; x < 200; ++x) {
+                const auto px = pixel(onBox, x, y);
+                if (px[1] > 200 && px[0] < 60 && px[2] < 60) greenSomewhere = true;
+            }
+        }
+        check(greenSomewhere, "and is filled with the colour it was given");
+        check(countRed(onBox, 0, 0, 200, 120) > 0, "the text is drawn over the box");
+
+        ParamValues faint = boxed;
+        faint["box_opacity"] = 0.5;
+        const auto half = renderText(blue, 200, 120, faint);
+        bool mixed = false;
+        for (int y = 0; y < 120 && !mixed; ++y) {
+            for (int x = 0; x < 200; ++x) {
+                const auto px = pixel(half, x, y);
+                // Half the green box over the blue input, and neither of them.
+                if (px[1] > 100 && px[1] < 200 && px[2] > 100 && px[2] < 200) mixed = true;
+            }
+        }
+        check(mixed, "half a box opacity sits between the box and the input");
+
+        const auto dir = std::filesystem::temp_directory_path() / "effector_test_text";
+        std::filesystem::create_directories(dir);
+        const auto picture = (dir / "fill.png").string();
+        solid(40, 40, 255, 255, 0).save(picture);
+        ParamValues fromPicture = boxed;
+        fromPicture["text_box"] = std::string("image");
+        fromPicture["box_image"] = picture;
+        const auto onPicture = renderText(blue, 200, 120, fromPicture);
+        bool yellowSomewhere = false;
+        for (int y = 0; y < 120 && !yellowSomewhere; ++y) {
+            for (int x = 0; x < 200; ++x) {
+                const auto px = pixel(onPicture, x, y);
+                if (px[0] > 200 && px[1] > 200 && px[2] < 60) yellowSomewhere = true;
+            }
+        }
+        check(yellowSomewhere, "a box picture fills the box");
+        check(pixel(onPicture, 2, 2)[2] > 200, "and stops at its edge");
+
+        bool threw = false;
+        try {
+            ParamValues missing = fromPicture;
+            missing["box_image"] = std::string("/nope/missing.png");
+            renderText(blue, 200, 120, missing);
+        } catch (const EffectError&) {
+            threw = true;
+        }
+        check(threw, "a missing box picture is reported");
+
+        // Nothing to draw is the state the interface starts in: a pass through.
+        check(sameBytes(renderText(blue, 200, 120, {{"text", std::string("")}}),
+                        solid(200, 120, 0, 0, 255)),
+              "with no text typed the stage passes its input through");
+        check(sameBytes(renderText(blue, 200, 120, {{"text", std::string("Hi")},
+                                                    {"text_opacity", 0.0}}),
+                        solid(200, 120, 0, 0, 255)),
+              "zero opacity leaves the input untouched");
+
+        // Like blur and overlay it needs no sources of its own, and the same
+        // settings render the same bytes twice over.
+        check(!TextEffect().needsSources(), "text can lead a chain");
+        const auto alone = renderText({}, 200, 120, plain);
+        check(alone.width() == 200 && countRed(alone, 0, 0, 200, 120) > 0,
+              "without sources it draws on an empty canvas");
+        check(sameBytes(renderText(blue, 200, 120, boxed), onBox),
+              "the same settings render the same bytes");
+
+        std::filesystem::remove_all(dir);
+    }
+
     std::cout << "chain\n";
     {
         std::vector<Image> sources = {gradient(1200, 800, 10), gradient(640, 480, 90)};
@@ -452,6 +968,51 @@ int main() {
         }
         check(threw, "a missing project file throws");
 
+        // A project is JSON whatever the user's locale is. gtkmm sets both the
+        // C and the C++ global locale from the environment, so on a German
+        // desktop an unguarded stream writes "0,35" and a grouped "1.920" —
+        // which is not JSON, and the project could not be opened again.
+        const char* const commaLocales[] = {"de_DE.UTF-8", "de_DE.utf8", "fr_FR.UTF-8",
+                                            "fr_FR.utf8"};
+        bool decimalCommaTried = false;
+        for (const char* name : commaLocales) {
+            if (std::setlocale(LC_ALL, name) == nullptr) continue;
+            std::locale previous;
+            try {
+                previous = std::locale::global(std::locale(name));
+            } catch (const std::exception&) {
+                continue;
+            }
+            decimalCommaTried = true;
+
+            Project wide;
+            wide.width = 1920;
+            wide.height = 1080;
+            wide.seed = 17353667313003709502ULL;  // more bits than a double holds
+            wide.stages.push_back({effectByName("grain"), {{"grain_amount", 0.35}}});
+
+            const auto text = projectToJson(wide);
+            bool reread = false;
+            try {
+                const auto back = projectFromJson(text);
+                reread = back.width == 1920 && back.height == 1080 &&
+                         back.seed == wide.seed &&
+                         paramDouble(back.stages[0].values, "grain_amount", -1.0) == 0.35;
+            } catch (const EffectError&) {
+            }
+            check(text.find("0.35") != std::string::npos &&
+                      text.find("\"width\": 1920") != std::string::npos,
+                  std::string("a project is written as JSON under ") + name);
+            check(reread, std::string("a project written under ") + name + " opens again");
+
+            std::locale::global(previous);
+            std::setlocale(LC_ALL, "C");
+            break;
+        }
+        if (!decimalCommaTried) {
+            std::cout << "  skip a decimal-comma locale (none installed)\n";
+        }
+
         std::filesystem::remove_all(dir);
     }
 
@@ -521,6 +1082,120 @@ int main() {
               "-s refuses a side that is not positive");
     }
 
+    std::cout << "canvas formats\n";
+    {
+        using effector::canvasFormatByKey;
+        using effector::canvasFormats;
+        using effector::canvasFormatSize;
+
+        // Every format the menu offers must land inside the canvas bounds at
+        // every resolution it can be asked for, or the dropdown would offer a
+        // size the renderer refuses.
+        int usable = 0;
+        for (const auto& format : canvasFormats()) {
+            int width = 0;
+            int height = 0;
+            bool ok = true;
+            for (const int dpi : {effector::kMinDpi, effector::kDefaultDpi, effector::kMaxDpi}) {
+                canvasFormatSize(format, dpi, width, height);
+                ok = ok && width >= kMinCanvasSide && width <= kMaxCanvasSide &&
+                     height >= kMinCanvasSide && height <= kMaxCanvasSide;
+            }
+            if (ok) ++usable;
+        }
+        check(usable == static_cast<int>(canvasFormats().size()),
+              "every format stays inside the canvas bounds at every dpi");
+
+        int unique = 0;
+        for (const auto& format : canvasFormats()) {
+            if (canvasFormatByKey(format.key) == &format) ++unique;
+        }
+        check(unique == static_cast<int>(canvasFormats().size()), "format keys are unique");
+        check(canvasFormatByKey("") == nullptr && canvasFormatByKey("a6") == nullptr,
+              "an empty or unknown key is a custom canvas");
+
+        int width = 0;
+        int height = 0;
+        canvasFormatSize(*canvasFormatByKey("a4"), 300, width, height);
+        check(width == 2480 && height == 3508, "A4 at 300 dpi is 2480x3508");
+        canvasFormatSize(*canvasFormatByKey("a4"), 600, width, height);
+        check(width == 4961 && height == 7016, "doubling the dpi doubles the sheet");
+        canvasFormatSize(*canvasFormatByKey("instagram-story"), 600, width, height);
+        check(width == 1080 && height == 1920, "a web format ignores the dpi");
+
+        // The CLI: a format decides the canvas whichever side of -s it is on,
+        // and --dpi may come before the format it applies to.
+        const auto sheet = parsedOptions({"--format", "a4", "--dpi", "600"});
+        check(sheet && sheet->width == 4961 && sheet->height == 7016,
+              "--format a4 --dpi 600 sets the canvas");
+        const auto reordered = parsedOptions({"--dpi", "600", "--format", "a4"});
+        check(reordered && reordered->width == 4961, "--dpi may be given before --format");
+        const auto both = parsedOptions({"-s", "800x600", "--format", "instagram-post"});
+        check(both && both->width == 1080 && both->height == 1080, "--format overrides -s");
+        const auto custom = parsedOptions({"-s", "800x600"});
+        check(custom && custom->format.empty() && custom->width == 800,
+              "-s alone leaves the canvas custom");
+        check(!parsedOptions({"--format", "a6"}), "--format refuses an unknown format");
+        check(!parsedOptions({"--dpi", "0"}) && !parsedOptions({"--dpi", "5000"}) &&
+                  !parsedOptions({"--dpi", "many"}),
+              "--dpi refuses a resolution outside the bounds");
+
+        // A project keeps the format, and the format keeps the pixels: a dpi
+        // edited by hand moves the canvas with it.
+        Project sheetProject;
+        sheetProject.stages.push_back({effectByName("blur"), {}});
+        sheetProject.format = "a4";
+        sheetProject.dpi = 600;
+        canvasFormatSize(*canvasFormatByKey("a4"), 600, sheetProject.width, sheetProject.height);
+        const auto backProject = projectFromJson(projectToJson(sheetProject));
+        check(backProject.format == "a4" && backProject.dpi == 600 && backProject.width == 4961,
+              "a print format and its dpi survive a round trip");
+
+        const auto retuned = projectFromJson(
+            "{\"canvas\": {\"width\": 800, \"height\": 600, \"format\": \"a4\", "
+            "\"dpi\": 300},\n \"chain\": [{\"effect\": \"blur\"}]}");
+        check(retuned.width == 2480 && retuned.height == 3508,
+              "a named format decides the pixels over whatever was written beside it");
+
+        // A format this build does not know — a newer file, or a typo — is a
+        // custom canvas, so the pixels the file carries are still rendered.
+        const auto unknown = projectFromJson(
+            "{\"canvas\": {\"width\": 800, \"height\": 600, \"format\": \"a6\"},\n"
+            " \"chain\": [{\"effect\": \"blur\"}]}");
+        check(unknown.format.empty() && unknown.width == 800 && unknown.height == 600,
+              "an unknown format falls back to the canvas the file names");
+
+        Project plainProject;
+        plainProject.stages.push_back({effectByName("blur"), {}});
+        plainProject.width = 800;
+        plainProject.height = 600;
+        const auto plainText = projectToJson(plainProject);
+        check(plainText.find("format") == std::string::npos &&
+                  plainText.find("dpi") == std::string::npos,
+              "a custom canvas writes no format and no dpi");
+
+        const auto webText = projectToJson([] {
+            Project web;
+            web.stages.push_back({effectByName("blur"), {}});
+            web.format = "hd";
+            return web;
+        }());
+        check(webText.find("\"format\": \"hd\"") != std::string::npos &&
+                  webText.find("dpi") == std::string::npos,
+              "a web format writes no dpi it would never use");
+
+        int badDpi = 0;
+        for (const char* bad : {"0", "5000", "300.5", "\"300\""}) {
+            try {
+                projectFromJson(std::string("{\"canvas\": {\"dpi\": ") + bad +
+                                "},\n \"chain\": [{\"effect\": \"blur\"}]}");
+            } catch (const EffectError&) {
+                ++badDpi;
+            }
+        }
+        check(badDpi == 4, "a dpi outside the bounds is refused");
+    }
+
     std::cout << "image io\n";
     {
         const auto path = std::filesystem::temp_directory_path() / "effector_test_roundtrip.png";