canvas.hpp

Go to the documentation of this file.

#pragma once
 
#include <algorithm>
#include <cmath>
#include <cstdint>
#include <cstring>
#include <pulp/canvas/affine_transform.hpp>
#include <pulp/canvas/canvas_capability.hpp>
#include <pulp/canvas/gradient_interpolation.hpp>
#include <pulp/canvas/path.hpp>
#include <pulp/canvas/scene_recording.hpp>
#include <pulp/canvas/text_raster_policy.hpp>
#include <pulp/canvas/text_utf8.hpp>
#include <string>
#include <vector>
#include <memory>
#include <optional>
#include <variant>
#include <functional>
 
namespace pulp::canvas {

enum class RendererBackend {
    unknown,
    recording,
    core_graphics,
    skia_raster,
    skia_ganesh,
    skia_dawn,
};
 
constexpr const char* renderer_backend_name(RendererBackend backend) noexcept {
    switch (backend) {
        case RendererBackend::unknown: return "unknown";
        case RendererBackend::recording: return "recording";
        case RendererBackend::core_graphics: return "core_graphics";
        case RendererBackend::skia_raster: return "skia_raster";
        case RendererBackend::skia_ganesh: return "skia_ganesh";
        case RendererBackend::skia_dawn: return "skia_dawn";
    }
    return "unknown";
}
 
// ── Color ────────────────────────────────────────────────────────────────────
 
struct Color {
    float r = 0.0f, g = 0.0f, b = 0.0f, a = 1.0f;

    static constexpr Color rgba(float r, float g, float b, float a = 1.0f) {
        return {r, g, b, a};
    }

    static constexpr Color rgba8(uint8_t r, uint8_t g, uint8_t b, uint8_t a = 255) {
        return {r / 255.0f, g / 255.0f, b / 255.0f, a / 255.0f};
    }

    static Color hex(uint32_t rgb) {
        return rgba8(static_cast<uint8_t>((rgb >> 16) & 0xFF),
                     static_cast<uint8_t>((rgb >> 8) & 0xFF),
                     static_cast<uint8_t>(rgb & 0xFF));
    }
 
    // ── Color space conversions ─────────────────────────────────────
 
    struct HSV { float h = 0, s = 0, v = 0; };
    struct HSL { float h = 0, s = 0, l = 0; };
    struct OKLCH { float L = 0, C = 0, h = 0; };

    HSV to_hsv() const;
    static Color from_hsv(HSV hsv, float alpha = 1.0f);

    HSL to_hsl() const;
    static Color from_hsl(HSL hsl, float alpha = 1.0f);

    OKLCH to_oklch() const;
    static Color from_oklch(OKLCH oklch, float alpha = 1.0f);

    void encode(uint8_t* out) const;
    static Color decode(const uint8_t* data);
 
    // ── Color math ──────────────────────────────────────────────────

    Color interpolate(const Color& other, float t) const {
        return {r + (other.r - r) * t,
                g + (other.g - g) * t,
                b + (other.b - b) * t,
                a + (other.a - a) * t};
    }

    Color with_hdr_intensity(float multiplier) const {
        return {r * multiplier, g * multiplier, b * multiplier, a};
    }

    Color with_alpha(float alpha) const {
        return {r, g, b, alpha};
    }

    uint8_t r8() const { return static_cast<uint8_t>(std::clamp(r, 0.0f, 1.0f) * 255.0f + 0.5f); }
    uint8_t g8() const { return static_cast<uint8_t>(std::clamp(g, 0.0f, 1.0f) * 255.0f + 0.5f); }
    uint8_t b8() const { return static_cast<uint8_t>(std::clamp(b, 0.0f, 1.0f) * 255.0f + 0.5f); }
    uint8_t a8() const { return static_cast<uint8_t>(std::clamp(a, 0.0f, 1.0f) * 255.0f + 0.5f); }

    uint32_t to_argb32() const {
        return (static_cast<uint32_t>(a8()) << 24) |
               (static_cast<uint32_t>(r8()) << 16) |
               (static_cast<uint32_t>(g8()) << 8) |
               static_cast<uint32_t>(b8());
    }

    static Color from_argb32(uint32_t argb) {
        return rgba8(static_cast<uint8_t>((argb >> 16) & 0xFF),
                     static_cast<uint8_t>((argb >> 8) & 0xFF),
                     static_cast<uint8_t>(argb & 0xFF),
                     static_cast<uint8_t>((argb >> 24) & 0xFF));
    }
 
    bool operator==(const Color& other) const {
        return r == other.r && g == other.g && b == other.b && a == other.a;
    }
    bool operator!=(const Color& other) const { return !(*this == other); }
};
 
// ── Paint ────────────────────────────────────────────────────────────────────
 
struct GradientStop {
    float position; // 0.0 to 1.0
    Color color;
};
 
struct LinearGradient {
    float x0, y0, x1, y1;
    std::vector<GradientStop> stops;
};
 
struct RadialGradient {
    float cx, cy, radius;
    float focal_x = 0, focal_y = 0;  
    std::vector<GradientStop> stops;
};

struct ConicGradient {
    float cx, cy;         
    float start_angle;    
    std::vector<GradientStop> stops;
};

enum class GradientTileMode { clamp, repeat, mirror };

class FillStyle {
public:
    FillStyle() = default;
    FillStyle(Color c) : color_(c) {} // NOLINT: implicit for convenience
    FillStyle(LinearGradient g) : linear_(std::move(g)), type_(1) {}
    FillStyle(RadialGradient g) : radial_(std::move(g)), type_(2) {}
    FillStyle(ConicGradient g) : conic_(std::move(g)), type_(3) {}
 
    bool is_solid() const { return type_ == 0; }
    bool is_linear() const { return type_ == 1; }
    bool is_radial() const { return type_ == 2; }
    bool is_conic() const { return type_ == 3; }
 
    const Color& color() const { return color_; }
    const LinearGradient& linear() const { return linear_; }
    const RadialGradient& radial() const { return radial_; }
    const ConicGradient& conic() const { return conic_; }
 
    GradientTileMode tile_mode() const { return tile_mode_; }
    void set_tile_mode(GradientTileMode m) { tile_mode_ = m; }
 
private:
    Color color_;
    LinearGradient linear_;
    RadialGradient radial_;
    ConicGradient conic_;
    int type_ = 0;  // 0=solid, 1=linear, 2=radial, 3=conic
    GradientTileMode tile_mode_ = GradientTileMode::clamp;
};
 
using Paint = std::variant<Color, LinearGradient, RadialGradient, ConicGradient>;
 
// ── Drawing commands ─────────────────────────────────────────────────────────
 
// LineCap, LineJoin, and FillRule are defined in <pulp/canvas/path.hpp> — the
// retained Path value type needs them and sits BELOW this header, so they live
// there and are used unqualified here (same namespace, one definition).
//
// FillRule is the Canvas2D fill rule for fill() / clip(). It mirrors the
// spec's ('nonzero' | 'evenodd') string enum; the default 'nonzero' matches
// CSS behavior and the JS shim's fillRule==='evenodd'?1:0 mapping in
// `core/view/js/web-compat-canvas.js`.
// CSS / RN `text-align: justify`. SkiaCanvas dispatches `kJustify` via
// SkParagraph when the backend supports it; CG / RecordingCanvas back-ends
// approximate as `left` (no kerning-controlled space distribution) until full
// SkParagraph integration lands. `auto` is resolved at the widget layer before
// reaching the canvas: Label::paint translates it to `left` (LTR) or `right`
// (RTL).
enum class TextAlign { left, center, right, justify };
enum class TextVerticalAlign { top, center, bottom, baseline };
// Canvas2D text baselines. `alphabetic` is the CSS/Canvas2D initial value:
// the y passed to fill_text IS the baseline, which is what browser-authored
// canvas code assumes when it never assigns ctx.textBaseline. `hanging` and
// `ideographic` have no dedicated font metric here and are approximated from
// ascent/descent, matching how engines fall back when the face carries no
// BASE table. Enumerators are appended so the wire codes the widget bridge
// records for top/middle/bottom keep their existing values.
enum class TextBaseline { top, middle, bottom, alphabetic, hanging, ideographic };
enum class TextDirection { left_to_right, right_to_left, top_to_bottom, bottom_to_top };
 
// CanvasCapability lives in its own header so capability-query call sites can
// include just the enum; canvas.hpp re-exports it here for back-compat, so any
// TU that includes canvas.hpp still sees CanvasCapability unchanged.
 
// Abstract canvas for 2D drawing
// Widgets paint against this interface. Concrete backends (Skia, CoreGraphics,
// software) implement the virtual methods.
class Canvas {
public:
    struct ShaderDrawOptions;
    virtual ~Canvas() = default;

    virtual RendererBackend renderer_backend() const noexcept {
        return RendererBackend::unknown;
    }

    virtual float backing_scale() const noexcept { return 1.0f; }
 
    // ── State ────────────────────────────────────────────────────────────
    virtual void save() = 0;
    virtual void restore() = 0;

    virtual int save_count() const { return 0; }

    virtual void restore_to_count(int target) { (void)target; }
 
    // ── Transform ────────────────────────────────────────────────────────
    virtual void translate(float x, float y) = 0;
    virtual void scale(float sx, float sy) = 0;
    virtual void rotate(float radians) = 0;

    virtual void set_transform(float a, float b, float c,
                               float d, float e, float f) {
        (void)a; (void)b; (void)c; (void)d; (void)e; (void)f;
    }

    virtual void capture_paint_baseline_transform() {}

    virtual void concat_transform(float a, float b, float c,
                                  float d, float e, float f) {
        (void)a; (void)b; (void)c; (void)d; (void)e; (void)f;
    }

    struct AffineTransform2x3 {
        float a = 1.0f, b = 0.0f;
        float c = 0.0f, d = 1.0f;
        float e = 0.0f, f = 0.0f;
    };

    virtual AffineTransform2x3 current_transform() const {
        return {};
    }
 
    // ── Clipping ─────────────────────────────────────────────────────────
    virtual void clip_rect(float x, float y, float w, float h) = 0;

    virtual void clip(FillRule rule = FillRule::nonzero) { (void)rule; }

    virtual void clip_path_svg(const std::string& svg_path_d) {
        (void)svg_path_d;
    }
 
    // ── Fill and stroke style ────────────────────────────────────────────
    virtual void set_fill_color(Color c) = 0;
    virtual void set_stroke_color(Color c) = 0;
    virtual void set_line_width(float w) = 0;
    virtual void set_line_cap(LineCap cap) = 0;
    virtual void set_line_join(LineJoin join) = 0;

    virtual void set_miter_limit(float limit) { (void)limit; }

    enum class ImageSmoothingQuality { low, medium, high };

    virtual void set_image_smoothing(bool enabled,
                                     ImageSmoothingQuality quality
                                         = ImageSmoothingQuality::low) {
        (void)enabled; (void)quality;
    }
 
    // ── Gradients ────────────────────────────────────────────────────────
    virtual void set_fill_gradient_linear(float x0, float y0, float x1, float y1,
                                          const Color* colors, const float* positions,
                                          int count) {
        if (count > 0) set_fill_color(colors[0]); // fallback: first color
    }

    virtual void set_fill_gradient_radial(float cx, float cy, float radius,
                                          const Color* colors, const float* positions,
                                          int count) {
        if (count > 0) set_fill_color(colors[0]);
    }

    virtual void set_fill_gradient_radial_elliptical(
            float cx, float cy, float rx, float ry,
            const Color* colors, const float* positions, int count) {
        (void)ry;
        set_fill_gradient_radial(cx, cy, rx, colors, positions, count);
    }

    virtual void set_fill_gradient_radial_two_circles(
            float x0, float y0, float r0,
            float x1, float y1, float r1,
            const Color* colors, const float* positions, int count) {
        (void)x0; (void)y0; (void)r0;
        set_fill_gradient_radial(x1, y1, r1, colors, positions, count);
    }

    virtual void set_fill_gradient_conic(float cx, float cy, float start_angle,
                                          const Color* colors, const float* positions,
                                          int count) {
        if (count > 0) set_fill_color(colors[0]); // fallback
    }

    virtual void clear_fill_gradient() {}
 
    // ── Stroke gradients ────────────────────────────────────────────────
    //
    // Mirror of the fill-gradient surface for `ctx.strokeStyle =
    // createLinearGradient(...) | createRadialGradient(...) |
    // createConicGradient(...)`. Defaults degrade to the first-stop
    // color via `set_stroke_color`; SkiaCanvas overrides with real
    // `SkShaders` gradient shaders stored on `stroke_shader_` so subsequent
    // stroke paths
    // (stroke_rect / stroke_current_path / stroke_text) pick the
    // gradient up via `apply_stroke_state`.
    virtual void set_stroke_gradient_linear(float x0, float y0, float x1, float y1,
                                             const Color* colors, const float* positions,
                                             int count) {
        if (count > 0) set_stroke_color(colors[0]); // fallback: first color
    }
 
    virtual void set_stroke_gradient_radial(float cx, float cy, float radius,
                                             const Color* colors, const float* positions,
                                             int count) {
        if (count > 0) set_stroke_color(colors[0]);
    }

    virtual void set_stroke_gradient_radial_two_circles(
            float x0, float y0, float r0,
            float x1, float y1, float r1,
            const Color* colors, const float* positions, int count) {
        (void)x0; (void)y0; (void)r0;
        set_stroke_gradient_radial(x1, y1, r1, colors, positions, count);
    }
 
    virtual void set_stroke_gradient_conic(float cx, float cy, float start_angle,
                                            const Color* colors, const float* positions,
                                            int count) {
        if (count > 0) set_stroke_color(colors[0]);
    }

    virtual void clear_stroke_gradient() {}

    enum class PatternTileMode { repeat, no_repeat };

    virtual void set_fill_pattern(const std::string& image_src,
                                   PatternTileMode tile_x,
                                   PatternTileMode tile_y) {
        (void)image_src; (void)tile_x; (void)tile_y;
    }

    virtual void set_stroke_pattern(const std::string& image_src,
                                     PatternTileMode tile_x,
                                     PatternTileMode tile_y) {
        (void)image_src; (void)tile_x; (void)tile_y;
    }
 
    // ── Blend modes ─────────────────────────────────────────────────────
    enum class BlendMode {
        // Advanced (separable & non-separable W3C blend modes)
        normal = 0, multiply, screen, overlay, darken, lighten,
        color_dodge, color_burn, hard_light, soft_light,
        difference, exclusion, hue, saturation, color, luminosity,
        // Porter-Duff compositing modes
        source_over,        // 16 — alias for normal/source-over (CSS default)
        destination_over,   // 17
        source_in,          // 18
        destination_in,     // 19
        source_out,         // 20
        destination_out,    // 21
        source_atop,        // 22
        destination_atop,   // 23
        xor_mode,           // 24 — "xor" CSS string
        copy,               // 25
        lighter             // 26 — additive ("plus" / SVG kPlus)
    };

    virtual void set_blend_mode(BlendMode mode) { (void)mode; }
 
    // ── Path building ───────────────────────────────────────────────────
    virtual void begin_path() {}
    virtual void move_to(float x, float y) { (void)x; (void)y; }
    virtual void line_to(float x, float y) { (void)x; (void)y; }
    virtual void quad_to(float cpx, float cpy, float x, float y) {
        (void)cpx; (void)cpy; line_to(x, y); // fallback: straight line
    }

    virtual void cubic_to(float cp1x, float cp1y, float cp2x, float cp2y,
                          float x, float y) {
        (void)cp1x; (void)cp1y; (void)cp2x; (void)cp2y; line_to(x, y);
    }

    virtual void arc(float cx, float cy, float radius,
                     float start_angle, float end_angle,
                     bool anticlockwise) {
        (void)cx; (void)cy; (void)radius;
        (void)start_angle; (void)end_angle; (void)anticlockwise;
    }

    virtual void arc_to(float x1, float y1, float x2, float y2, float radius) {
        (void)x1; (void)y1; (void)x2; (void)y2; (void)radius;
    }

    virtual void ellipse(float cx, float cy, float rx, float ry,
                         float rotation,
                         float start_angle, float end_angle,
                         bool anticlockwise) {
        (void)cx; (void)cy; (void)rx; (void)ry; (void)rotation;
        (void)start_angle; (void)end_angle; (void)anticlockwise;
    }

    virtual void round_rect(float x, float y, float w, float h,
                            float tl_x, float tl_y,
                            float tr_x, float tr_y,
                            float br_x, float br_y,
                            float bl_x, float bl_y) {
        (void)x; (void)y; (void)w; (void)h;
        (void)tl_x; (void)tl_y; (void)tr_x; (void)tr_y;
        (void)br_x; (void)br_y; (void)bl_x; (void)bl_y;
    }

    virtual void close_path() {}
    virtual void fill_current_path(FillRule rule = FillRule::nonzero) {
        (void)rule;
    }

    virtual void stroke_current_path() {}
 
    // ── Bloom / Glow post-effect ────────────────────────────────────────
    virtual void save_layer_with_bloom(float x, float y, float w, float h,
                                       float intensity, float threshold,
                                       float radius) {
        save_layer(x, y, w, h, 1.0f, radius * intensity);
    }
 
    // ── Shapes ───────────────────────────────────────────────────────────
    virtual void fill_rect(float x, float y, float w, float h) = 0;
    virtual void stroke_rect(float x, float y, float w, float h) = 0;
    virtual void fill_rounded_rect(float x, float y, float w, float h, float radius) = 0;
    virtual void stroke_rounded_rect(float x, float y, float w, float h, float radius) = 0;
    virtual void fill_circle(float cx, float cy, float radius) = 0;
    virtual void stroke_circle(float cx, float cy, float radius) = 0;

    virtual void clear_rect(float x, float y, float w, float h) {
        // Default: best-effort SrcOver fill with transparent color. Pixel
        // backends should override to use kSrc / kClear blend.
        set_fill_color(Color::rgba(0.0f, 0.0f, 0.0f, 0.0f));
        fill_rect(x, y, w, h);
    }
 
    // ── Arcs ─────────────────────────────────────────────────────────────
    virtual void stroke_arc(float cx, float cy, float radius,
                           float start_angle, float end_angle) = 0;
 
    // ── Lines ────────────────────────────────────────────────────────────
    virtual void stroke_line(float x0, float y0, float x1, float y1) = 0;

    using Point2D = pulp::canvas::Point2D;

    virtual void stroke_path(const Point2D* points, size_t count) {
        // Fallback: separate segments, so no joins. Curve backends should override.
        if (points == nullptr || count < 2) return;
        for (size_t i = 1; i < count; ++i)
            stroke_line(points[i-1].x, points[i-1].y, points[i].x, points[i].y);
    }

    virtual void fill_path(const Point2D* points, size_t count,
                           FillRule rule = FillRule::nonzero) {
        if (points == nullptr || count < 3) return;
        begin_path();
        move_to(points[0].x, points[0].y);
        for (size_t i = 1; i < count; ++i)
            line_to(points[i].x, points[i].y);
        close_path();
        fill_current_path(rule);
    }

    virtual void draw_image(void* native_handle,
                            float x, float y, float w, float h) {
        (void)native_handle; (void)x; (void)y; (void)w; (void)h;
    }
 
    // ── Retained paths ────────────────────────────────────────────────────
    // These take a `pulp::canvas::Path` — a retained VALUE (build once, store
    // it, draw it every frame) — rather than streaming verbs through the
    // immediate-mode builder above. See <pulp/canvas/path.hpp>.
    //
    // Every default implementation below is a real fallback, not a no-op: it
    // replays the path through the immediate-mode API that every backend
    // already implements. A Canvas subclass that overrides nothing still draws
    // the path correctly; backends override only to skip the state round-trip
    // and hand a native path object straight to the rasterizer.

    virtual void fill_path(const Path& path, FillRule rule = FillRule::nonzero) {
        if (path.is_empty()) return;
        begin_path();
        path.replay(*this);
        fill_current_path(rule);
    }

    virtual void stroke_path(const Path& path, const StrokeStyle& style) {
        if (path.is_empty()) return;
        set_line_width(style.width);
        set_line_cap(style.cap);
        set_line_join(style.join);
        set_miter_limit(style.miter_limit);
        if (style.dash.empty())
            set_line_dash(nullptr, 0, 0.0f);
        else
            set_line_dash(style.dash.data(), static_cast<int>(style.dash.size()),
                          style.dash_phase);
        begin_path();
        path.replay(*this);
        stroke_current_path();
    }

    virtual void clip_path(const Path& path, FillRule rule = FillRule::nonzero) {
        if (path.is_empty()) return;
        begin_path();
        path.replay(*this);
        clip(rule);
    }

    virtual void draw_path_shadow(const Path& path, float dx, float dy,
                                  float blur, float spread, Color color) {
        if (path.is_empty()) return;
        (void)blur;  // the fallback has no blur; backends override.
        Path shadow = path;
        if (spread != 0.0f) {
            const Rect2D b = path.bounds();
            if (b.width > 0.0f && b.height > 0.0f) {
                const float sx = (b.width + 2.0f * spread) / b.width;
                const float sy = (b.height + 2.0f * spread) / b.height;
                shadow.apply_transform(AffineTransform::scaling(
                    sx, sy, b.x + b.width * 0.5f, b.y + b.height * 0.5f));
            }
        }
        shadow.apply_transform(AffineTransform::translation(dx, dy));
        save();
        set_fill_color(color);
        fill_path(shadow, FillRule::nonzero);
        restore();
    }
 
    // ── Opacity & Layers ──────────────────────────────────────────────────
    virtual void set_opacity(float alpha) { (void)alpha; }

    struct LayerHandle {
        uint64_t id = 0;
        constexpr bool operator==(const LayerHandle& o) const { return id == o.id; }
        constexpr bool operator!=(const LayerHandle& o) const { return id != o.id; }
        constexpr explicit operator bool() const { return id != 0; }
    };

    virtual LayerHandle begin_layer(Rect2D bounds, bool cacheable = false) {
        (void)cacheable;
        save();
        clip_rect(bounds.x, bounds.y, bounds.width, bounds.height);
        return LayerHandle{};
    }

    virtual LayerHandle end_layer() {
        restore();
        return LayerHandle{};
    }

    virtual void draw_layer(LayerHandle layer, float alpha = 1.0f,
                            BlendMode mode = BlendMode::normal) {
        (void)layer; (void)alpha; (void)mode;
    }

    virtual void draw_layer_fitted(LayerHandle layer, Rect2D dest) {
        (void)layer; (void)dest;
    }

    virtual void draw_layer_rotated(LayerHandle layer, float angle_rad) {
        (void)layer; (void)angle_rad;
    }

    virtual bool layer_valid(LayerHandle layer) const {
        (void)layer;
        return false;
    }

    virtual void invalidate_layer(LayerHandle layer) { (void)layer; }
 
    // ── Scene recording (subtree cache, FU-3) ─────────────────────────────
    virtual std::shared_ptr<SceneRecording> record_scene(
            float w, float h, const std::function<void(Canvas&)>& paint) {
        (void)w; (void)h; (void)paint;
        return nullptr;
    }

    virtual bool draw_scene(const SceneRecording& rec) {
        (void)rec;
        return false;
    }

    virtual void save_layer(float x, float y, float w, float h,
                            float opacity = 1.0f, float blur_radius = 0.0f) {
        save(); // fallback: just save state
        (void)x; (void)y; (void)w; (void)h;
        (void)opacity; (void)blur_radius;
    }

    virtual void save_layer_with_blend(float x, float y, float w, float h,
                                       float opacity, float blur_radius,
                                       BlendMode mode) {
        (void)mode;
        save_layer(x, y, w, h, opacity, blur_radius);
    }

    struct FilterChainEntry {
        enum class Kind {
            blur,
            brightness,
            contrast,
            grayscale,
            hue_rotate,
            invert,
            opacity,
            saturate,
            sepia,
            drop_shadow,
        };
        Kind kind = Kind::blur;
        float amount = 0.0f;
        float angle_deg = 0.0f;
        float ds_offset_x = 0.0f;
        float ds_offset_y = 0.0f;
        float ds_blur = 0.0f;
        Color ds_color{};
    };
    virtual void save_layer_with_filters(float x, float y, float w, float h,
                                          float opacity,
                                          const FilterChainEntry* chain,
                                          int count) {
        // Fallback: collapse blur + opacity filters into a plain save_layer.
        float blur = 0.0f;
        for (int i = 0; i < count; ++i) {
            if (chain[i].kind == FilterChainEntry::Kind::blur) {
                blur += chain[i].amount;
            } else if (chain[i].kind == FilterChainEntry::Kind::opacity) {
                opacity *= chain[i].amount;
            }
        }
        save_layer(x, y, w, h, opacity, blur);
    }

    virtual void save_layer_with_shader_effect(float x, float y,
                                               float w, float h,
                                               const std::string& effect_name,
                                               float intensity) {
        (void)effect_name;
        (void)intensity;
        save_layer(x, y, w, h);
    }

    virtual void save_layer_with_mask(float x, float y, float w, float h,
                                       float opacity,
                                       const std::string& mask_image,
                                       const std::string& mask_size) {
        (void)mask_image; (void)mask_size;
        save_layer(x, y, w, h, opacity, 0.0f);
    }
 
    // ── Text ─────────────────────────────────────────────────────────────
    virtual void set_font(const std::string& family, float size) = 0;
    virtual void set_text_align(TextAlign align) = 0;
    virtual void fill_text(const std::string& text, float x, float y) = 0;
    virtual float measure_text(const std::string& text) = 0;

    virtual float text_x_for_byte(const std::string& text,
                                  std::size_t byte_index) {
        // Clamp back to a UTF-8 codepoint boundary: a caller-supplied byte
        // index that lands inside a multi-byte sequence would otherwise slice
        // an invalid prefix. On the CoreGraphics backend that invalid UTF-8
        // made NSString conversion return nil and NSAttributedString THROW
        // inside the editor's drawRect:, killing the host's whole AU process
        // (and every plugin in it). Never measure an invalid prefix.
        return measure_text(text.substr(0, safe_utf8_prefix_size(text, byte_index)));
    }

    enum class TextAnchor {
        Baseline,
        GlyphTop,
        GlyphCenter,
        EmBoxTop,
    };
    virtual void fill_text_anchored(const std::string& text,
                                    float x, float y, TextAnchor anchor) {
        // Default fallback: treat all anchors as Baseline. Backends
        // that have access to font metrics override this. The override
        // path is the one widget callsites use; the default exists so
        // RecordingCanvas / base mocks compile without changes.
        (void)anchor;
        fill_text(text, x, y);
    }

    virtual void fill_text_with_max_width(const std::string& text,
                                          float x, float y, float max_width) {
        (void)max_width;
        fill_text(text, x, y);
    }

    virtual void stroke_text(const std::string& text, float x, float y,
                             float max_width = 0.0f) {
        (void)max_width;
        // Fallback: caller must have set fill color to stroke color before
        // invoking. Matches the strokeText shim approximation.
        fill_text(text, x, y);
    }

    virtual void set_font_full(const std::string& family, float size,
                                int weight, int slant, float letter_spacing) {
        (void)weight; (void)slant; (void)letter_spacing;
        set_font(family, size);
    }

    virtual void set_font_smoothing(FontSmoothing smoothing) {
        (void)smoothing;
    }
 
    // OpenType feature flags for font-variant. Each
    // FontFeature is a 4-byte tag (e.g. "tnum" / "smcp" / "onum" /
    // "lnum" / "pnum") + an on/off value (0 disables, 1 enables).
    // SkiaCanvas applies these via SkParagraph TextStyle::addFontFeature
    // inside make_paragraph(), at HarfBuzz shape time. The default impl
    // is a no-op (CG / Recording canvases ignore); SkiaCanvas captures
    // into a vector consumed by the make_paragraph() calls behind
    // fill_text / stroke_text / measure_text.
    struct FontFeature {
        uint32_t tag;    // 4-byte big-endian tag (use make_font_feature_tag).
        uint32_t value;  // 0 = disable, 1 = enable, higher = feature-specific.
        bool operator==(const FontFeature&) const = default;
    };

    static constexpr uint32_t make_font_feature_tag(const char (&s)[5]) {
        return (static_cast<uint32_t>(static_cast<uint8_t>(s[0])) << 24) |
               (static_cast<uint32_t>(static_cast<uint8_t>(s[1])) << 16) |
               (static_cast<uint32_t>(static_cast<uint8_t>(s[2])) <<  8) |
                static_cast<uint32_t>(static_cast<uint8_t>(s[3]));
    }
    virtual void set_font_features(std::vector<FontFeature> features) {
        (void)features;
        // Default: no-op. Backends without HarfBuzz feature support
        // (recording canvas, CG path) silently drop the request — text
        // still renders, just without the OpenType feature applied.
    }
    virtual void clear_font_features() {
        // Default: no-op. Same rationale as set_font_features.
    }

    struct TextMetrics {
        float width = 0;        
        float ascent = 0;       
        float descent = 0;      
        float line_height = 0;  
 
        // ── HTML5 TextMetrics extensions ────────────────────────────
        float actual_bounding_box_left = 0;
        float actual_bounding_box_right = 0;
        float actual_bounding_box_ascent = 0;
        float actual_bounding_box_descent = 0;
    };
 
    // ── SDF Text (GPU-accelerated, resolution-independent) ────────────

    virtual void fill_text_sdf(const std::string& text, float x, float y,
                               const class SdfAtlas& atlas) {
        // Default: fall back to standard text rendering
        (void)atlas;
        fill_text(text, x, y);
    }
 
    // ── Capability queries ───────────────────────────────────────────────
    virtual bool supports(CanvasCapability) const { return false; }
 
    // ── Images ───────────────────────────────────────────────────────────
    bool supports_image_draw() const { return supports(CanvasCapability::images); }

    virtual bool draw_image_from_data(const uint8_t* data, size_t size,
                                      float x, float y, float w, float h) {
        (void)data; (void)size; (void)x; (void)y; (void)w; (void)h;
        return false; // Base class can't draw images
    }

    virtual bool draw_image_from_file(const std::string& path,
                                       float x, float y, float w, float h) {
        (void)path; (void)x; (void)y; (void)w; (void)h;
        return false; // Override in Skia backend
    }

    virtual bool draw_svg(const std::string& svg_document,
                          float x, float y, float w, float h) {
        (void)svg_document; (void)x; (void)y; (void)w; (void)h;
        return false; // Override in Skia backend
    }
 
    // 9-arg drawImage(img, sx,sy,sw,sh, dx,dy,dw,dh) source-rect
    // slicing. Default impl delegates to the dst-only form (loses the slice);
    // Skia overrides to use drawImageRect(src, dst); other backends keep
    // the destination-only fallback.
    virtual bool draw_image_from_file_rect(const std::string& path,
                                            float sx, float sy, float sw, float sh,
                                            float dx, float dy, float dw, float dh) {
        (void)sx; (void)sy; (void)sw; (void)sh;
        return draw_image_from_file(path, dx, dy, dw, dh);
    }
    virtual bool draw_image_from_data_rect(const uint8_t* data, size_t size,
                                            float sx, float sy, float sw, float sh,
                                            float dx, float dy, float dw, float dh) {
        (void)sx; (void)sy; (void)sw; (void)sh;
        return draw_image_from_data(data, size, dx, dy, dw, dh);
    }

    virtual bool measure_image_from_file(const std::string& path,
                                          float& out_width, float& out_height) {
        (void)path;
        out_width = 0.0f; out_height = 0.0f;
        return false;
    }

    virtual TextMetrics measure_text_full(const std::string& text) {
        TextMetrics m;
        m.width = measure_text(text);
        m.ascent = font_size_ * 0.75f;   // approximate
        m.descent = font_size_ * 0.25f;
        m.line_height = font_size_ * 1.2f;
        // HTML5 TextMetrics fields — fall back to font-metric
        // estimates when no shaped bounding box is available.
        m.actual_bounding_box_left = 0;
        m.actual_bounding_box_right = m.width;
        m.actual_bounding_box_ascent = m.ascent;
        m.actual_bounding_box_descent = m.descent;
        return m;
    }
 
    // ── Line Dash ───────────────────────────────────────────────────
    virtual void set_line_dash(const float* intervals, int count, float phase = 0.0f) {
        (void)intervals; (void)count; (void)phase;
    }
 
    // ── Pixel manipulation ──────────────────────────────────────────
    virtual bool read_pixels(int x, int y, int width, int height, uint8_t* out) {
        (void)x; (void)y; (void)width; (void)height; (void)out;
        return false;
    }

    virtual bool write_pixels(const uint8_t* data, int width, int height,
                              int dx, int dy) {
        (void)data; (void)width; (void)height; (void)dx; (void)dy;
        return false;
    }
 
    // ── SDF Shape Primitives (GPU-accelerated) ─────────────────────────
    enum class SDFShape {
        rect,           // 0 — axis-aligned rectangle
        circle,         // 1 — circle (min dimension as radius)
        rounded_rect,   // 2 — rectangle with corner_radius
        arc,            // 3 — ring arc (arc_start + arc_sweep)
        diamond,        // 4 — rotated square
        squircle,       // 5 — continuous-curvature rounded rect (power param)
        triangle,       // 6 — equilateral triangle
        ring,           // 7 — circle with inner radius (donut)
        stadium,        // 8 — pill/capsule shape
        cross,          // 9 — plus sign with configurable arm width
        flat_segment,   // 10 — line segment with flat caps
        rounded_segment,// 11 — line segment with rounded caps
        flat_arc,       // 12 — arc with thickness and flat caps
        quadratic_bezier,// 13 — quadratic bezier curve with thickness
    };
 
    struct SDFStyle {
        Color fill_color = Color::rgba(0.392f, 1.0f, 0.392f);
        Color stroke_color = Color::rgba(0.392f, 1.0f, 0.392f);
        float stroke_width = 0;       
        float corner_radius = 0;      
        float arc_start = 0;          
        float arc_sweep = 4.712f;     
        float squircle_power = 4.0f;  
        float inner_radius = 0.5f;    
        float arm_width = 0.3f;       
        float bezier_cx = 0.0f;       
        float bezier_cy = -1.0f;      
        // Analytic chart feathering. 0=uniform, 1=glow, 2=inner,
        // 3=outer, 4=inset, 5=radial, 6=sweep.
        float feather_sigma = 0.0f;
        int feather_curve = 0;        
        int feather_mode = 0;
    };
 
    virtual void draw_sdf_shape(SDFShape shape, float x, float y, float w, float h,
                                const SDFStyle& style) {
        // CPU fallback: use existing rect/rounded_rect
        if (style.stroke_width > 0) {
            set_stroke_color(style.stroke_color);
            set_line_width(style.stroke_width);
            if (shape == SDFShape::circle)
                stroke_rounded_rect(x, y, w, h, std::min(w, h) * 0.5f);
            else if (shape == SDFShape::rounded_rect)
                stroke_rounded_rect(x, y, w, h, style.corner_radius);
            else
                stroke_rounded_rect(x, y, w, h, 0);
        } else {
            set_fill_color(style.fill_color);
            if (shape == SDFShape::circle)
                fill_rounded_rect(x, y, w, h, std::min(w, h) * 0.5f);
            else if (shape == SDFShape::rounded_rect)
                fill_rounded_rect(x, y, w, h, style.corner_radius);
            else
                fill_rounded_rect(x, y, w, h, 0);
        }
    }

    virtual bool draw_sdf_shape_with_shader(SDFShape shape, float x, float y,
                                             float w, float h,
                                             const SDFStyle& style,
                                             const std::string& sksl,
                                             const ShaderDrawOptions& options) {
        (void)sksl; (void)options;
        draw_sdf_shape(shape, x, y, w, h, style);
        return false;
    }
 
    // ── Blur / Backdrop filter ─────────────────────────────────────────
    virtual void draw_blurred_backdrop(float x, float y, float w, float h,
                                       float blur_radius, float corner_radius = 0,
                                       Color tint = Color::rgba(0.0f, 0.0f, 0.0f, 0.314f)) {
        // CPU fallback: just draw a semi-transparent rect (no blur)
        set_fill_color(tint);
        fill_rounded_rect(x, y, w, h, corner_radius);
    }

    virtual void save_backdrop_filter(float x, float y, float w, float h,
                                      float blur_radius) {
        (void)x; (void)y; (void)w; (void)h; (void)blur_radius;
        save();
    }

    virtual void save_backdrop_filter_chain(float x, float y, float w, float h,
                                            const FilterChainEntry* chain,
                                            int count) {
        float blur = 0.0f;
        for (int i = 0; i < count; ++i)
            if (chain[i].kind == FilterChainEntry::Kind::blur)
                blur += chain[i].amount;
        save_backdrop_filter(x, y, w, h, blur);
    }
 
    // ── Box shadow ──────────────────────────────────────────────────
    virtual void draw_box_shadow(float x, float y, float w, float h,
                                 float dx, float dy, float blur, float spread,
                                 Color color, bool inset = false,
                                 float corner_radius = 0.0f);
 
    // ── Canvas2D drop shadow state ──────────────────────────────────
    virtual void set_shadow_color(Color color) { (void)color; }
    virtual void set_shadow_blur(float blur)   { (void)blur; }
    virtual void set_shadow_offset_x(float dx) { (void)dx; }
    virtual void set_shadow_offset_y(float dy) { (void)dy; }
 
    // ── Canvas2D direction / filter ─────────────────────────────────
    enum class TextDirection { ltr, rtl, inherit };
    virtual void set_direction(TextDirection direction) { (void)direction; }

    virtual void set_filter(const std::string& filter) { (void)filter; }
 
    // ── Waveform (GPU-accelerated) ─────────────────────────────────────
    struct WaveformStyle {
        Color line_color = Color::rgba(0.392f, 0.706f, 0.980f);
        Color fill_color = Color::rgba(0.392f, 0.706f, 0.980f, 0.157f);
        float line_thickness = 1.5f;
        bool show_fill = true;
        float fill_center = 0.5f;  
    };
 
    virtual void draw_waveform(const float* samples, size_t count,
                               float x, float y, float width, float height,
                               const WaveformStyle& style) {
        // CPU fallback: connected line strip
        if (count < 2) return;
        set_stroke_color(style.line_color);
        set_line_width(style.line_thickness);
        float cy = y + height * style.fill_center;
        float half_h = height * 0.5f;
        float prev_x = x;
        float prev_y = cy - samples[0] * half_h;
        for (size_t i = 1; i < count; ++i) {
            float sx = x + (static_cast<float>(i) / static_cast<float>(count - 1)) * width;
            float sy = cy - samples[i] * half_h;
            stroke_line(prev_x, prev_y, sx, sy);
            prev_x = sx;
            prev_y = sy;
        }
    }
 
    // ── Custom SkSL Shader Rendering (GPU) ──────────────────────────────
    //
    // SkSL is the custom-widget-shader contract. It is deliberately declared on
    // the abstract Canvas rather than on SkiaCanvas: `setWidgetShader(id, sksl)`
    // in the JS widget bridge accepts SkSL, so every backend must answer for it
    // — either by compiling it or by degrading predictably.
    //
    // A backend without SkSL degrades gracefully and reports the failure rather
    // than pretending to draw: `compile_sksl` returns a non-empty error string
    // on non-Skia builds, and `draw_with_sksl` paints a fallback rect and
    // returns false. Callers must therefore treat a false return / non-empty
    // error as "no shader ran", not as a hard error.
    //
    // The Skia-independent escape hatch is the WGSL tier — the JS WebGPU bridge
    // talks to Dawn directly with zero Skia involvement — for UIs that need GPU
    // work on a backend where SkSL is unavailable.

    struct ShaderUniforms {
        float value = 0;           
        float time = 0;            
        Color accent_color{};
        Color bg_color{};
        Color track_color{};
        Color fill_color{};
        Color thumb_color{};
    };

    struct NamedUniform {
        std::string name;
        int count = 1;             
        float v[4] = {0, 0, 0, 0};
    };

    struct ShaderDataTexture {
        std::string name;
        std::vector<float> samples;
        std::uint32_t count = 0;
        bool live = false;
        float neutral = 0.0f;
        std::uint32_t publish_sequence = 0;
    };
 
    struct ShaderGeometry {
        SDFShape shape = SDFShape::rect;
        SDFStyle style{};
        // Optional generated SDF expression for a bounded operator tree.
        // It is emitted from validated geometry JSON and evaluated per
        // fragment alongside the primitive prelude.
        std::string sdf_expression;
        std::uint64_t topology_hash = 0;
        // Parameters for a validated operator tree. The expression refers
        // to pulp_leafN_* uniforms; keeping the values separate lets a
        // same-topology update avoid recompiling the composed shader.
        std::vector<NamedUniform> leaf_uniforms;
        std::uint32_t leaf_count = 0;
    };
 
    struct ShaderDrawOptions {
        ShaderUniforms uniforms;
        std::vector<NamedUniform> named_uniforms;
        float reach = 0.0f;
        std::shared_ptr<const ShaderDataTexture> data_texture;
        std::optional<ShaderGeometry> geometry;
    };

    static std::string compile_sksl(const std::string& sksl);

    static std::string compile_sdf_chart_sksl(SDFShape shape, const std::string& sksl);

    static float sdf_feather_min_reach(const SDFStyle& style) {
        if (!(style.feather_sigma > 0.0f))
            return 0.0f;
        if (style.feather_mode != 1 && style.feather_mode != 3)
            return 0.0f;
        return 3.0f * style.feather_sigma;
    }

    static bool sksl_declares_uniform(const std::string& sksl,
                                      const std::string& uniform_name);

    virtual bool draw_with_sksl(const std::string& sksl,
                                float x, float y, float w, float h,
                                const ShaderUniforms& uniforms) {
        // CPU fallback: draw a colored placeholder rect
        set_fill_color(uniforms.fill_color.a > 0.0f ? uniforms.fill_color : Color::rgba(0.314f, 0.314f, 0.392f, 0.784f));
        fill_rect(x, y, w, h);
        return false; // shader not rendered
    }
 
    virtual bool draw_with_sksl(const std::string& sksl,
                                float x, float y, float w, float h,
                                const ShaderDrawOptions& options) {
        return draw_with_sksl(sksl, x, y, w, h, options.uniforms);
    }

    virtual bool save_layer_with_sksl_post_effect(
            float x, float y, float w, float h,
            const std::string& sksl, const ShaderUniforms& uniforms,
            float sample_radius = 0.0f,
            const std::vector<NamedUniform>& extra_uniforms = {},
            BlendMode blend_mode = BlendMode::normal) {
        (void)sksl; (void)uniforms; (void)sample_radius;
        (void)extra_uniforms; (void)blend_mode;
        save_layer(x, y, w, h, 1.0f, 0.0f);
        return false;
    }
 
    // ── Image transforms, fitting, and tiling ───────────────────────────
    //
    // These extend the opaque-handle image-draw path (`draw_image`) with the
    // rest of the general 2D image-placement vocabulary: an arbitrary affine
    // placement, preserve-aspect fitting into a destination box, and tiled
    // fill of a region. Every method here has a neutral default expressed in
    // primitives every backend already implements (save / restore / clip_rect
    // / concat_transform / draw_image), so a backend that overrides none of
    // them still paints correctly. Pixel backends may override any of them
    // with a single native call (e.g. a shader-backed tile) for efficiency.

    enum class ImageFit { fill, contain, cover, none, scale_down };

    struct FitResult { float x = 0, y = 0, w = 0, h = 0; };

    static FitResult fit_image_rect(float iw, float ih,
                                    float dx, float dy, float dw, float dh,
                                    ImageFit fit,
                                    float align_x = 0.5f,
                                    float align_y = 0.5f) {
        FitResult r{dx, dy, dw, dh};
        if (iw <= 0.0f || ih <= 0.0f || dw <= 0.0f || dh <= 0.0f) return r;
        float scale = 1.0f;
        switch (fit) {
            case ImageFit::fill:       return {dx, dy, dw, dh};
            case ImageFit::contain:    scale = std::min(dw / iw, dh / ih); break;
            case ImageFit::cover:      scale = std::max(dw / iw, dh / ih); break;
            case ImageFit::none:       scale = 1.0f; break;
            case ImageFit::scale_down: scale = std::min(1.0f, std::min(dw / iw, dh / ih)); break;
        }
        const float w = iw * scale;
        const float h = ih * scale;
        return {dx + (dw - w) * align_x, dy + (dh - h) * align_y, w, h};
    }

    virtual void draw_image_transformed(void* native_handle, float w, float h,
                                        const AffineTransform& t) {
        save();
        concat_transform(t.a, t.b, t.c, t.d, t.e, t.f);
        draw_image(native_handle, 0.0f, 0.0f, w, h);
        restore();
    }

    virtual void draw_image_fitted(void* native_handle, float iw, float ih,
                                   float dx, float dy, float dw, float dh,
                                   ImageFit fit,
                                   float align_x = 0.5f,
                                   float align_y = 0.5f) {
        const FitResult r = fit_image_rect(iw, ih, dx, dy, dw, dh, fit, align_x, align_y);
        save();
        clip_rect(dx, dy, dw, dh);
        draw_image(native_handle, r.x, r.y, r.w, r.h);
        restore();
    }

    virtual bool draw_image_file_fitted(const std::string& path,
                                        float dx, float dy, float dw, float dh,
                                        ImageFit fit,
                                        float align_x = 0.5f,
                                        float align_y = 0.5f) {
        float iw = 0.0f, ih = 0.0f;
        if (!measure_image_from_file(path, iw, ih) || iw <= 0.0f || ih <= 0.0f) {
            return draw_image_from_file(path, dx, dy, dw, dh);
        }
        const FitResult r = fit_image_rect(iw, ih, dx, dy, dw, dh, fit, align_x, align_y);
        save();
        clip_rect(dx, dy, dw, dh);
        const bool ok = draw_image_from_file(path, r.x, r.y, r.w, r.h);
        restore();
        return ok;
    }

    virtual void draw_image_tiled(void* native_handle,
                                  float tile_w, float tile_h,
                                  float dx, float dy, float dw, float dh,
                                  float offset_x = 0.0f, float offset_y = 0.0f) {
        if (tile_w <= 0.0f || tile_h <= 0.0f || dw <= 0.0f || dh <= 0.0f) return;
        save();
        clip_rect(dx, dy, dw, dh);
        // Start at or just before the box's leading edge so the offset never
        // leaves an uncovered gap along the top / left.
        float start_x = dx - std::fmod(offset_x, tile_w);
        if (start_x > dx) start_x -= tile_w;
        float start_y = dy - std::fmod(offset_y, tile_h);
        if (start_y > dy) start_y -= tile_h;
        for (float ty = start_y; ty < dy + dh; ty += tile_h) {
            for (float tx = start_x; tx < dx + dw; tx += tile_w) {
                draw_image(native_handle, tx, ty, tile_w, tile_h);
            }
        }
        restore();
    }
 
protected:
    float font_size_ = 14.0f;  
 
  public:
    virtual void set_fill_gradient_conic_repeating(float cx, float cy, float start_angle,
                                                    float sweep_turns,
                                                    const Color* colors, const float* positions,
                                                    int count) {
        (void)sweep_turns;
        set_fill_gradient_conic(cx, cy, start_angle, colors, positions, count);
    }

    virtual void set_fill_gradient_linear_repeating(float x0, float y0,
                                                     float x1, float y1,
                                                     const Color* colors,
                                                     const float* positions,
                                                     int count) {
        set_fill_gradient_linear(x0, y0, x1, y1, colors, positions, count);
    }
 
  public:
    virtual bool draw_image_from_static_data_rect(const uint8_t* data, size_t size, float sx,
                                                  float sy, float sw, float sh, float dx, float dy,
                                                  float dw, float dh) {
        return draw_image_from_data_rect(data, size, sx, sy, sw, sh, dx, dy, dw, dh);
    }

    virtual bool draw_image_from_keyed_data(const std::string& content_key, const uint8_t* data,
                                            size_t size, float x, float y, float w, float h) {
        (void)content_key;
        return draw_image_from_data(data, size, x, y, w, h);
    }

    virtual bool draw_image_from_keyed_data_rect(const std::string& content_key,
                                                 const uint8_t* data, size_t size, float sx,
                                                 float sy, float sw, float sh, float dx, float dy,
                                                 float dw, float dh) {
        (void)content_key;
        return draw_image_from_data_rect(data, size, sx, sy, sw, sh, dx, dy, dw, dh);
    }

    virtual bool measure_image_from_data(const uint8_t* data, size_t size, float& out_width,
                                         float& out_height) {
        out_width = 0.0f;
        out_height = 0.0f;
        static constexpr uint8_t kPngSignature[] = {0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a};
        if (!data || size < 24)
            return false;
        for (size_t i = 0; i < sizeof(kPngSignature); ++i)
            if (data[i] != kPngSignature[i])
                return false;
        const auto read_be32 = [&](size_t offset) {
            return (static_cast<uint32_t>(data[offset]) << 24) |
                   (static_cast<uint32_t>(data[offset + 1]) << 16) |
                   (static_cast<uint32_t>(data[offset + 2]) << 8) |
                   static_cast<uint32_t>(data[offset + 3]);
        };
        // The first chunk must be IHDR; PNG caps each dimension at 2^31 - 1.
        if (data[12] != 'I' || data[13] != 'H' || data[14] != 'D' || data[15] != 'R')
            return false;
        const uint32_t w = read_be32(16);
        const uint32_t h = read_be32(20);
        if (w == 0 || h == 0 || w > 0x7fffffffu || h > 0x7fffffffu)
            return false;
        out_width = static_cast<float>(w);
        out_height = static_cast<float>(h);
        return true;
    }

    virtual void set_gradient_interpolation(GradientInterpolation m) {
        gradient_interpolation_ = m;
    }
    GradientInterpolation gradient_interpolation() const {
        return gradient_interpolation_;
    }
 
  private:
    GradientInterpolation gradient_interpolation_{};
};
 
} // namespace pulp::canvas
 
// RecordingCanvas lives in its own header; included here so consumers that
// only include canvas.hpp keep seeing it. The include sits after the
// namespace close because RecordingCanvas derives from Canvas.
#include <pulp/canvas/recording_canvas.hpp>