ggplot_rs/

plot.rs

#[cfg(all(feature = "plotters", not(target_arch = "wasm32")))]
use plotters::prelude::IntoDrawingArea;

use crate::aes::Aes;
use crate::annotate::Annotation;
use crate::build::PlotBuilder;
use crate::coord::cartesian::CoordCartesian;
use crate::coord::fixed::CoordFixed;
use crate::coord::flip::CoordFlip;
use crate::coord::polar::CoordPolar;
use crate::coord::Coord;
use crate::data::{DataFrame, GGData, Value};
use crate::facet::{Facet, FacetLabeller, FacetScales, FacetSpace};
use crate::geom::area::GeomArea;
use crate::geom::bar::GeomBar;
use crate::geom::bin2d::GeomBin2d;
use crate::geom::blank::GeomBlank;
use crate::geom::boxplot::GeomBoxplot;
use crate::geom::col::GeomCol;
use crate::geom::contour::GeomContour;
use crate::geom::count::GeomCount;
use crate::geom::crossbar::GeomCrossbar;
use crate::geom::curve::GeomCurve;
use crate::geom::density::GeomDensity;
use crate::geom::density2d::GeomDensity2d;
use crate::geom::dotplot::GeomDotplot;
use crate::geom::errorbar::GeomErrorbar;
use crate::geom::freqpoly::GeomFreqpoly;
use crate::geom::hex::GeomHex;
use crate::geom::histogram::GeomHistogram;
use crate::geom::jitter::GeomJitter;
use crate::geom::line::GeomLine;
use crate::geom::linerange::GeomLinerange;
use crate::geom::path::GeomPath;
use crate::geom::point::GeomPoint;
use crate::geom::pointrange::GeomPointrange;
use crate::geom::polygon::GeomPolygon;
use crate::geom::qq::{GeomQQ, GeomQQLine};
use crate::geom::rect::GeomRect;
use crate::geom::refline::{GeomAbline, GeomHline, GeomVline};
use crate::geom::ribbon::GeomRibbon;
use crate::geom::rug::GeomRug;
use crate::geom::segment::GeomSegment;
use crate::geom::smooth::GeomSmooth;
use crate::geom::spoke::GeomSpoke;
use crate::geom::step::GeomStep;
use crate::geom::text::{GeomLabel, GeomText};
use crate::geom::tile::GeomTile;
use crate::geom::violin::GeomViolin;
use crate::geom::{Geom, GeomParams};
use crate::position::Position;
use crate::render::layout::PlotLayout;
#[cfg(all(feature = "plotters", not(target_arch = "wasm32")))]
use crate::render::plotters_backend::PlottersAdapter;
use crate::render::renderer::PlotRenderer;
use crate::render::RenderError;
use crate::scale::continuous::ScaleContinuous;
use crate::scale::transform::ScaleTransform;
use crate::scale::Scale;
use crate::stat::Stat;
use crate::theme::Theme;

// Builder methods for the 0.17 statistical-graphics layers (QQ, step ribbons,
// ECDF bands, Cook's contours, horizontal error bars).
mod stat_layers;

/// Labels for the plot.
#[derive(Clone, Debug, Default)]
pub struct Labels {
    pub title: Option<String>,
    pub subtitle: Option<String>,
    pub x: Option<String>,
    pub y: Option<String>,
    pub caption: Option<String>,
    /// Corner tag (R's `labs(tag = ...)`), e.g. "A" for figure panels.
    pub tag: Option<String>,
}

/// A single layer in the plot.
pub struct Layer {
    pub data: Option<DataFrame>,
    pub mapping: Aes,
    pub geom: Box<dyn Geom>,
    pub stat: Box<dyn Stat>,
    pub position: Box<dyn Position>,
    pub params: GeomParams,
    pub show_legend: Option<bool>,
    /// The geom was configured explicitly (`geom_*_with(...)`), so its colours
    /// are deliberate and the theme's `primary_color` must not override them.
    pub explicit_style: bool,
    /// A `{column}` tooltip template ([`GGPlot::tooltip`]), rendered per row
    /// from the *built* layer data (post-stat) once that's available.
    pub tooltip_template: Option<String>,
}

/// The top-level plot specification — builder pattern.
pub struct GGPlot {
    pub(crate) data: DataFrame,
    pub(crate) mapping: Aes,
    pub(crate) layers: Vec<Layer>,
    pub(crate) scales: Vec<Box<dyn Scale>>,
    pub(crate) coord: Box<dyn Coord>,
    pub(crate) theme: Theme,
    pub(crate) labels: Labels,
    pub(crate) facet: Facet,
    pub(crate) annotations: Vec<Annotation>,
    pub(crate) guide_legend: crate::guide::config::GuideLegend,
    /// Warnings raised while specifying the plot (e.g. a clipped calendar
    /// span); prepended to the build warnings.
    pub(crate) warnings: Vec<String>,
    /// Panel aspect ratio used when the theme sets none (helpers such as
    /// `geom_calendar` need square cells; survives theme presets).
    pub(crate) default_aspect_ratio: Option<f64>,
    /// Plot-wide default locale for axis / legend labels ([`GGPlot::locale`]).
    pub(crate) locale: Option<crate::locale::Locale>,
    /// Whether the rendered root `<svg>` carries `data-plot`/`data-domain`/…
    /// ([`svg_root_data`](Self::svg_root_data)). Default `true`; a consumer
    /// overlaying a fragment on its own basemap (`render_svg_native_at`)
    /// turns it off so the fragment adds no root attributes of its own.
    pub(crate) svg_root_data: bool,
    /// Extra root `<svg>` attributes requested via [`svg_attr`](Self::svg_attr)/
    /// [`svg_attrs`](Self::svg_attrs), validated and applied at render time.
    pub(crate) root_attrs: Vec<(String, String)>,
    /// Whether to emit a `data-warnings` JSON array of the build warnings
    /// on the root `<svg>` ([`svg_warnings_attr`](Self::svg_warnings_attr)).
    /// Default off; byte-identical output when off.
    pub(crate) svg_warnings_attr: bool,
    /// Whether to emit `data-fvalue`/`data-fx` on marks
    /// ([`svg_formatted_values`](Self::svg_formatted_values)). Default off;
    /// byte-identical output when off.
    pub(crate) svg_formatted_values: bool,
}

impl GGPlot {
    /// Create a new plot with the given data source.
    ///
    /// Never panics on malformed input: e.g. column-oriented data whose columns
    /// have different lengths is padded with `NA` and reported as a
    /// [`GGError::ValidationError`] by [`try_build`](Self::try_build) and the
    /// `render_*`/`save*` methods.
    pub fn new(data: impl GGData) -> Self {
        GGPlot {
            data: data.into_dataframe(),
            mapping: Aes::default(),
            layers: Vec::new(),
            scales: Vec::new(),
            coord: Box::new(CoordCartesian::new()),
            theme: Theme::default(),
            labels: Labels::default(),
            facet: Facet::default(),
            annotations: Vec::new(),
            guide_legend: crate::guide::config::GuideLegend::default(),
            warnings: Vec::new(),
            default_aspect_ratio: None,
            locale: None,
            svg_root_data: true,
            root_attrs: Vec::new(),
            svg_warnings_attr: false,
            svg_formatted_values: false,
        }
    }

    /// Set the plot-level aesthetic mapping.
    pub fn aes(mut self, mapping: Aes) -> Self {
        self.warnings.extend(mapping.warnings.iter().cloned());
        self.mapping = mapping;
        self
    }

    // ─── Geom shortcuts ──────────────────────────────────────────

    pub fn geom_point(self) -> Self {
        self.add_geom(GeomPoint::default())
    }

    pub fn geom_point_with(self, geom: GeomPoint) -> Self {
        self.add_geom_with(geom)
    }

    pub fn geom_line(self) -> Self {
        self.add_geom(GeomLine::default())
    }

    pub fn geom_line_with(self, geom: GeomLine) -> Self {
        self.add_geom_with(geom)
    }

    pub fn geom_bar(self) -> Self {
        self.add_geom(GeomBar::default())
    }

    pub fn geom_bar_with(self, geom: GeomBar) -> Self {
        self.add_geom_with(geom)
    }

    pub fn geom_histogram(self) -> Self {
        self.add_geom(GeomHistogram::default())
    }

    pub fn geom_histogram_with(self, geom: GeomHistogram) -> Self {
        self.add_geom_with(geom)
    }

    pub fn geom_boxplot(self) -> Self {
        self.add_geom(GeomBoxplot::default())
    }

    pub fn geom_boxplot_with(self, geom: GeomBoxplot) -> Self {
        self.add_geom_with(geom)
    }

    pub fn geom_smooth(self) -> Self {
        self.add_geom(GeomSmooth::default())
    }

    pub fn geom_smooth_with(self, geom: GeomSmooth) -> Self {
        self.add_geom_with(geom)
    }

    pub fn geom_col(self) -> Self {
        self.add_geom(GeomCol::default())
    }

    pub fn geom_col_with(self, geom: GeomCol) -> Self {
        self.add_geom_with(geom)
    }

    /// Horizontal reference line at a constant `yintercept`. Like ggplot2 the
    /// intercept trains the y scale (the line is always visible) and the line
    /// appears in every facet panel.
    pub fn geom_hline(self, yintercept: f64) -> Self {
        self.add_refline(
            GeomHline::new(yintercept),
            false,
            &[("yintercept", yintercept)],
        )
    }

    /// Add a horizontal reference line with custom styling (color/linetype/width).
    pub fn geom_hline_with(self, geom: GeomHline) -> Self {
        let y = geom.yintercept;
        self.add_refline(geom, true, &[("yintercept", y)])
    }

    /// Data-mapped horizontal lines (ggplot2's `geom_hline(aes(yintercept =
    /// …))`): one line per row of the layer data (the plot data unless
    /// [`layer_data`](Self::layer_data) follows), per facet panel, styled by
    /// any `color`/`linetype`/`alpha` in `mapping`. The plot-level mapping is
    /// not inherited.
    ///
    /// ```
    /// # use ggplot_rs::prelude::*;
    /// let thresholds: Vec<(String, Vec<Value>)> = vec![
    ///     ("bound".into(), vec![Value::Float(-0.2), Value::Float(0.2)]),
    /// ];
    /// let svg = GGPlot::new(vec![
    ///         ("lag".to_string(), vec![Value::Float(1.0), Value::Float(2.0)]),
    ///         ("acf".to_string(), vec![Value::Float(0.5), Value::Float(0.1)]),
    ///     ])
    ///     .aes(Aes::new().x("lag").y("acf"))
    ///     .geom_col()
    ///     .geom_hline_aes(Aes::new().yintercept("bound"))
    ///     .layer_data(thresholds)
    ///     .render_svg_native()
    ///     .unwrap();
    /// assert!(svg.contains("data-value=\"0.2\""));
    /// ```
    pub fn geom_hline_aes(self, mapping: Aes) -> Self {
        self.add_geom(GeomHline::mapped()).layer_aes(mapping)
    }

    /// [`geom_hline_aes`](Self::geom_hline_aes) with custom default styling.
    pub fn geom_hline_aes_with(self, geom: GeomHline, mapping: Aes) -> Self {
        self.add_geom_with(geom).layer_aes(mapping)
    }

    /// Vertical reference line at a constant `xintercept` (trains the x
    /// scale, appears in every panel).
    pub fn geom_vline(self, xintercept: f64) -> Self {
        self.add_refline(
            GeomVline::new(xintercept),
            false,
            &[("xintercept", xintercept)],
        )
    }

    /// Add a vertical reference line with custom styling (color/linetype/width).
    pub fn geom_vline_with(self, geom: GeomVline) -> Self {
        let x = geom.xintercept;
        self.add_refline(geom, true, &[("xintercept", x)])
    }

    /// Data-mapped vertical lines (`aes(xintercept = …)`), one per row; see
    /// [`geom_hline_aes`](Self::geom_hline_aes).
    pub fn geom_vline_aes(self, mapping: Aes) -> Self {
        self.add_geom(GeomVline::mapped()).layer_aes(mapping)
    }

    /// [`geom_vline_aes`](Self::geom_vline_aes) with custom default styling.
    pub fn geom_vline_aes_with(self, geom: GeomVline, mapping: Aes) -> Self {
        self.add_geom_with(geom).layer_aes(mapping)
    }

    /// Line `y = intercept + slope · x` in data space, clipped to the panel.
    /// It does not train any scale (as in ggplot2).
    pub fn geom_abline(self, slope: f64, intercept: f64) -> Self {
        self.add_refline(
            GeomAbline::new(slope, intercept),
            false,
            &[("slope", slope), ("intercept", intercept)],
        )
    }

    /// Add a slope/intercept reference line with custom styling.
    pub fn geom_abline_with(self, geom: GeomAbline) -> Self {
        let (b, a) = (geom.slope, geom.intercept);
        self.add_refline(geom, true, &[("slope", b), ("intercept", a)])
    }

    /// Data-mapped ablines (`aes(slope = …, intercept = …)`), one per row; a
    /// missing aesthetic defaults to slope 1 / intercept 0.
    pub fn geom_abline_aes(self, mapping: Aes) -> Self {
        self.add_geom(GeomAbline::mapped()).layer_aes(mapping)
    }

    /// [`geom_abline_aes`](Self::geom_abline_aes) with custom default styling.
    pub fn geom_abline_aes_with(self, geom: GeomAbline, mapping: Aes) -> Self {
        self.add_geom_with(geom).layer_aes(mapping)
    }

    /// A constant reference line as ggplot2 builds it: a one-row layer frame
    /// holding the constants, mapped to their aesthetics.
    fn add_refline(
        self,
        geom: impl Geom + 'static,
        explicit: bool,
        values: &[(&str, f64)],
    ) -> Self {
        let mut data = DataFrame::new();
        let mut mapping = Aes::new();
        for (col, v) in values {
            data.add_column(col.to_string(), vec![Value::Float(*v)]);
            mapping = match *col {
                "xintercept" => mapping.xintercept(col),
                "yintercept" => mapping.yintercept(col),
                "slope" => mapping.slope(col),
                _ => mapping.intercept(col),
            };
        }
        let plot = if explicit {
            self.add_geom_with(geom)
        } else {
            self.add_geom(geom)
        };
        plot.layer_aes(mapping).layer_data(data)
    }

    pub fn geom_text(self) -> Self {
        self.add_geom(GeomText::default())
    }

    pub fn geom_text_with(self, geom: GeomText) -> Self {
        self.add_geom_with(geom)
    }

    /// Annotate with a correlation coefficient + p-value (`ggpubr::stat_cor()`).
    /// Adds a text layer whose statistic computes Pearson correlation via
    /// anofox-statistics; use [`GGPlot::stat_cor_with`] to pick Spearman or set
    /// the label position.
    #[cfg(feature = "ggpubr")]
    pub fn stat_cor(self) -> Self {
        self.geom_text().stat(crate::stat::cor::StatCor::default())
    }

    /// [`GGPlot::stat_cor`] with an explicit [`StatCor`](crate::stat::cor::StatCor)
    /// (method / label position).
    #[cfg(feature = "ggpubr")]
    pub fn stat_cor_with(self, stat: crate::stat::cor::StatCor) -> Self {
        self.geom_text().stat(stat)
    }

    /// Annotate grouped data with a group-comparison p-value
    /// (`ggpubr::stat_compare_means()`). Adds a text layer whose statistic
    /// compares y across the discrete x groups (Wilcoxon for two groups,
    /// Kruskal-Wallis for more) via anofox-statistics.
    #[cfg(feature = "ggpubr")]
    pub fn stat_compare_means(self) -> Self {
        self.geom_text()
            .stat(crate::stat::compare_means::StatCompareMeans::default())
    }

    /// [`GGPlot::stat_compare_means`] with an explicit
    /// [`StatCompareMeans`](crate::stat::compare_means::StatCompareMeans).
    #[cfg(feature = "ggpubr")]
    pub fn stat_compare_means_with(
        self,
        stat: crate::stat::compare_means::StatCompareMeans,
    ) -> Self {
        self.geom_text().stat(stat)
    }

    /// Auto-draw pairwise significance brackets (`ggpubr::stat_compare_means`
    /// with `comparisons`). For each `(group_a, group_b)` pair it runs a
    /// two-sample test (Wilcoxon by default) on the plot's y-values, formats the
    /// p-value, and stacks a labelled [`geom_bracket`](GGPlot::geom_bracket)
    /// above the data. Uses the plot's x/y mapping and data.
    #[cfg(feature = "ggpubr")]
    pub fn stat_compare_means_pairwise(self, comparisons: &[(&str, &str)]) -> Self {
        self.stat_compare_means_pairwise_with(
            crate::stat::compare_means::CompareMethod::Auto,
            comparisons,
        )
    }

    /// [`stat_compare_means_pairwise`](GGPlot::stat_compare_means_pairwise) with
    /// an explicit test method.
    #[cfg(feature = "ggpubr")]
    pub fn stat_compare_means_pairwise_with(
        self,
        method: crate::stat::compare_means::CompareMethod,
        comparisons: &[(&str, &str)],
    ) -> Self {
        // Resolve the x/y source columns from the plot mapping + data.
        let col_for = |a: crate::aes::Aesthetic| {
            self.mapping
                .mappings
                .iter()
                .find(|m| m.aesthetic == a)
                .map(|m| m.column.clone())
        };
        let (xcol, ycol) = match (
            col_for(crate::aes::Aesthetic::X),
            col_for(crate::aes::Aesthetic::Y),
        ) {
            (Some(x), Some(y)) => (x, y),
            _ => return self,
        };
        let (xc, yc) = match (self.data.column(&xcol), self.data.column(&ycol)) {
            (Some(x), Some(y)) => (x, y),
            _ => return self,
        };

        // Bucket y by x category (first-seen order) and find the data range.
        let mut groups: Vec<(String, Vec<f64>)> = Vec::new();
        let mut ymax = f64::NEG_INFINITY;
        let mut ymin = f64::INFINITY;
        for (xv, yv) in xc.iter().zip(yc.iter()) {
            let y = match yv.as_f64() {
                Some(y) if y.is_finite() => y,
                _ => continue,
            };
            ymax = ymax.max(y);
            ymin = ymin.min(y);
            let key = xv.to_group_key();
            if let Some(g) = groups.iter_mut().find(|(k, _)| *k == key) {
                g.1.push(y);
            } else {
                groups.push((key, vec![y]));
            }
        }
        if groups.len() < 2 {
            return self;
        }
        let step = if ymax > ymin {
            (ymax - ymin) * 0.12
        } else {
            1.0
        };

        // One stacked bracket per resolvable comparison.
        let (mut xmin_v, mut xmax_v, mut y_v, mut label_v) =
            (Vec::new(), Vec::new(), Vec::new(), Vec::new());
        let mut placed = 0usize;
        for (a, b) in comparisons {
            let ga = groups.iter().find(|(k, _)| k == a).map(|g| &g.1);
            let gb = groups.iter().find(|(k, _)| k == b).map(|g| &g.1);
            let (ga, gb) = match (ga, gb) {
                (Some(x), Some(y)) if x.len() >= 2 && y.len() >= 2 => (x, y),
                _ => continue,
            };
            let p = match crate::stat::compare_means::pairwise_p(method, ga, gb) {
                Some(p) => p,
                None => continue,
            };
            xmin_v.push(Value::Str((*a).to_string()));
            xmax_v.push(Value::Str((*b).to_string()));
            y_v.push(Value::Float(ymax + step * (placed as f64 + 1.0)));
            label_v.push(Value::Str(crate::stat::cor::format_p_value(p)));
            placed += 1;
        }
        if xmin_v.is_empty() {
            return self;
        }

        let data = vec![
            ("xmin".to_string(), xmin_v),
            ("xmax".to_string(), xmax_v),
            ("y".to_string(), y_v),
            ("label".to_string(), label_v),
        ];
        self.add_geom(crate::geom::bracket::GeomBracket::default())
            .layer_data(data)
            .layer_aes(Aes::new().xmin("xmin").xmax("xmax").y("y").label("label"))
    }

    /// Draw a significance bracket over the plot (`ggpubr::geom_bracket`): a bar
    /// spanning the categorical positions `xmin`..`xmax` at height `y`, captioned
    /// with `label` (e.g. a p-value or significance stars). Pairs with a boxplot
    /// and [`stat_compare_means`](GGPlot::stat_compare_means).
    pub fn geom_bracket(self, xmin: &str, xmax: &str, y: f64, label: &str) -> Self {
        self.geom_bracket_many(
            crate::geom::bracket::GeomBracket::default(),
            &[(xmin, xmax, y, label)],
        )
    }

    /// Draw several significance brackets at once with a configured
    /// [`GeomBracket`](crate::geom::bracket::GeomBracket). Each tuple is
    /// `(xmin, xmax, y, label)`.
    pub fn geom_bracket_many(
        self,
        geom: crate::geom::bracket::GeomBracket,
        brackets: &[(&str, &str, f64, &str)],
    ) -> Self {
        let xmin = brackets
            .iter()
            .map(|b| Value::Str(b.0.to_string()))
            .collect::<Vec<_>>();
        let xmax = brackets
            .iter()
            .map(|b| Value::Str(b.1.to_string()))
            .collect::<Vec<_>>();
        let y = brackets
            .iter()
            .map(|b| Value::Float(b.2))
            .collect::<Vec<_>>();
        let label = brackets
            .iter()
            .map(|b| Value::Str(b.3.to_string()))
            .collect::<Vec<_>>();
        let data = vec![
            ("xmin".to_string(), xmin),
            ("xmax".to_string(), xmax),
            ("y".to_string(), y),
            ("label".to_string(), label),
        ];
        self.add_geom(geom)
            .layer_data(data)
            .layer_aes(Aes::new().xmin("xmin").xmax("xmax").y("y").label("label"))
    }

    /// Significance brackets from a precomputed test table (ggpubr's
    /// `stat_pvalue_manual` / `geom_bracket(data = …)`) — e.g. the anofox
    /// `test` contract output (`group1`, `group2`, `p_adj`/`p_value`, optional
    /// `y_position`, `label`). No test is recomputed. See
    /// [`BracketTable`](crate::geom::bracket::BracketTable) for the column
    /// rules, label templates (`"p = {p_adj}"`, `"{p.signif}"`) and the
    /// automatic stacking of rows without a `y_position`. Rows that cannot be
    /// drawn are dropped with a build warning.
    pub fn geom_bracket_table(
        mut self,
        table: impl GGData,
        spec: crate::geom::bracket::BracketTable,
    ) -> Self {
        let table = table.into_dataframe();
        let col_for = |a: crate::aes::Aesthetic| {
            self.mapping
                .mappings
                .iter()
                .find(|m| m.aesthetic == a)
                .map(|m| m.column.clone())
        };
        // The plot's x categories (to reject unknown groups) and finite y
        // range (to stack brackets above the data).
        let x_levels: Vec<String> = col_for(crate::aes::Aesthetic::X)
            .and_then(|c| self.data.column(&c))
            .filter(|col| col.iter().any(|v| matches!(v, Value::Str(_))))
            .map(|col| {
                let mut seen = std::collections::HashSet::new();
                col.iter()
                    .filter(|v| !v.is_na())
                    .map(|v| v.to_group_key())
                    .filter(|k| seen.insert(k.clone()))
                    .collect()
            })
            .unwrap_or_default();
        let y_range = col_for(crate::aes::Aesthetic::Y)
            .and_then(|c| self.data.column(&c))
            .and_then(|col| {
                let (lo, hi) = col
                    .iter()
                    .filter_map(|v| v.as_f64())
                    .filter(|v| v.is_finite())
                    .fold((f64::INFINITY, f64::NEG_INFINITY), |(lo, hi), v| {
                        (lo.min(v), hi.max(v))
                    });
                (lo <= hi).then_some((lo, hi))
            });
        let mut warnings = Vec::new();
        let resolved = spec.resolve(&table, &x_levels, y_range, &mut warnings);
        self.warnings.extend(warnings);
        match resolved {
            Some(data) => self
                .add_geom(crate::geom::bracket::GeomBracket::from(spec.geom))
                .layer_data(data)
                .layer_aes(Aes::new().xmin("xmin").xmax("xmax").y("y").label("label")),
            None => self,
        }
    }

    /// Text labels that repel each other and their points
    /// (`ggrepel::geom_text_repel`) — deterministic (seeded) layout; see
    /// [`GeomTextRepel`](crate::geom::repel::GeomTextRepel). Requires `x`,
    /// `y` and `label`.
    pub fn geom_text_repel(self) -> Self {
        self.add_geom(crate::geom::repel::GeomTextRepel::default())
    }

    /// [`geom_text_repel`](Self::geom_text_repel) with a configured geom
    /// (padding, nudge, `max_overlaps`, seed, …).
    pub fn geom_text_repel_with(self, geom: crate::geom::repel::GeomTextRepel) -> Self {
        self.add_geom_with(geom)
    }

    /// Boxed labels that repel each other and their points
    /// (`ggrepel::geom_label_repel`).
    pub fn geom_label_repel(self) -> Self {
        self.add_geom(crate::geom::repel::GeomLabelRepel::default())
    }

    /// [`geom_label_repel`](Self::geom_label_repel) with a configured geom.
    pub fn geom_label_repel_with(self, geom: crate::geom::repel::GeomLabelRepel) -> Self {
        self.add_geom_with(geom)
    }

    pub fn geom_label(self) -> Self {
        self.add_geom(GeomLabel::default())
    }

    pub fn geom_label_with(self, geom: GeomLabel) -> Self {
        self.add_geom_with(geom)
    }

    pub fn geom_area(self) -> Self {
        self.add_geom(GeomArea::default())
    }

    pub fn geom_area_with(self, geom: GeomArea) -> Self {
        self.add_geom_with(geom)
    }

    pub fn geom_ribbon(self) -> Self {
        self.add_geom(GeomRibbon::default())
    }

    pub fn geom_ribbon_with(self, geom: GeomRibbon) -> Self {
        self.add_geom_with(geom)
    }

    pub fn geom_errorbar(self) -> Self {
        self.add_geom(GeomErrorbar::default())
    }

    pub fn geom_errorbar_with(self, geom: GeomErrorbar) -> Self {
        self.add_geom_with(geom)
    }

    pub fn geom_segment(self) -> Self {
        self.add_geom(GeomSegment::default())
    }

    pub fn geom_segment_with(self, geom: GeomSegment) -> Self {
        self.add_geom_with(geom)
    }

    pub fn geom_density(self) -> Self {
        self.add_geom(GeomDensity::default())
    }

    pub fn geom_density_with(self, geom: GeomDensity) -> Self {
        self.add_geom_with(geom)
    }

    pub fn geom_rug(self) -> Self {
        self.add_geom(GeomRug::default())
    }

    pub fn geom_rug_with(self, geom: GeomRug) -> Self {
        self.add_geom_with(geom)
    }

    pub fn geom_jitter(self) -> Self {
        self.add_geom(GeomJitter::default())
    }

    pub fn geom_jitter_with(self, geom: GeomJitter) -> Self {
        self.add_geom_with(geom)
    }

    pub fn geom_path(self) -> Self {
        self.add_geom(GeomPath::default())
    }

    pub fn geom_path_with(self, geom: GeomPath) -> Self {
        self.add_geom_with(geom)
    }

    /// Add a confidence-ellipse layer (default 95%) as a path per group.
    pub fn stat_ellipse(self) -> Self {
        self.geom_path()
            .stat(crate::stat::ellipse::StatEllipse::default())
    }

    /// Add a confidence-ellipse layer at the given level (0, 1).
    pub fn stat_ellipse_level(self, level: f64) -> Self {
        self.geom_path()
            .stat(crate::stat::ellipse::StatEllipse::new(level))
    }

    /// Add a quantile-regression line for each `tau` as a separate path layer
    /// (R's `stat_quantile`). Backed by anofox-regression (feature `regression`).
    #[cfg(feature = "regression")]
    pub fn stat_quantile(mut self, taus: &[f64]) -> Self {
        for &tau in taus {
            self = self
                .geom_path()
                .stat(crate::stat::quantile::StatQuantile::new(tau));
        }
        self
    }

    /// Quantile-regression lines at the quartiles (0.25, 0.5, 0.75).
    #[cfg(feature = "regression")]
    pub fn geom_quantile(self) -> Self {
        self.stat_quantile(&[0.25, 0.5, 0.75])
    }

    pub fn geom_step(self) -> Self {
        self.add_geom(GeomStep::default())
    }

    pub fn geom_step_with(self, geom: GeomStep) -> Self {
        self.add_geom_with(geom)
    }

    pub fn geom_freqpoly(self) -> Self {
        self.add_geom(GeomFreqpoly::default())
    }

    pub fn geom_freqpoly_with(self, geom: GeomFreqpoly) -> Self {
        self.add_geom_with(geom)
    }

    pub fn geom_linerange(self) -> Self {
        self.add_geom(GeomLinerange::default())
    }

    pub fn geom_linerange_with(self, geom: GeomLinerange) -> Self {
        self.add_geom_with(geom)
    }

    pub fn geom_pointrange(self) -> Self {
        self.add_geom(GeomPointrange::default())
    }

    pub fn geom_pointrange_with(self, geom: GeomPointrange) -> Self {
        self.add_geom_with(geom)
    }

    pub fn geom_crossbar(self) -> Self {
        self.add_geom(GeomCrossbar::default())
    }

    pub fn geom_crossbar_with(self, geom: GeomCrossbar) -> Self {
        self.add_geom_with(geom)
    }

    pub fn geom_spoke(self) -> Self {
        self.add_geom(GeomSpoke::default())
    }

    pub fn geom_spoke_with(self, geom: GeomSpoke) -> Self {
        self.add_geom_with(geom)
    }

    pub fn geom_rect(self) -> Self {
        self.add_geom(GeomRect::default())
    }

    pub fn geom_rect_with(self, geom: GeomRect) -> Self {
        self.add_geom_with(geom)
    }

    pub fn geom_tile(self) -> Self {
        self.add_geom(GeomTile::default())
    }

    pub fn geom_tile_with(self, geom: GeomTile) -> Self {
        self.add_geom_with(geom)
    }

    /// Dense regular grid of filled cells (heatmap/raster) from x, y, fill.
    pub fn geom_raster(self) -> Self {
        self.add_geom(crate::geom::raster::GeomRaster::default())
    }

    pub fn geom_raster_with(self, geom: crate::geom::raster::GeomRaster) -> Self {
        self.add_geom_with(geom)
    }

    pub fn geom_polygon(self) -> Self {
        self.add_geom(GeomPolygon::default())
    }

    pub fn geom_polygon_with(self, geom: GeomPolygon) -> Self {
        self.add_geom_with(geom)
    }

    /// Render simple-features geometry from a WKT `geometry` column (feature `sf`).
    #[cfg(feature = "sf")]
    pub fn geom_sf(self) -> Self {
        self.add_geom(crate::geom::sf::GeomSf::default())
    }

    #[cfg(feature = "sf")]
    pub fn geom_sf_with(self, geom: crate::geom::sf::GeomSf) -> Self {
        self.add_geom_with(geom)
    }

    pub fn geom_curve(self) -> Self {
        self.add_geom(GeomCurve::default())
    }

    pub fn geom_curve_with(self, geom: GeomCurve) -> Self {
        self.add_geom_with(geom)
    }

    pub fn geom_violin(self) -> Self {
        self.add_geom(GeomViolin::default())
    }

    pub fn geom_violin_with(self, geom: GeomViolin) -> Self {
        self.add_geom_with(geom)
    }

    pub fn geom_dotplot(self) -> Self {
        self.add_geom(GeomDotplot::default())
    }

    pub fn geom_dotplot_with(self, geom: GeomDotplot) -> Self {
        self.add_geom_with(geom)
    }

    pub fn geom_qq(self) -> Self {
        self.add_geom(GeomQQ::default())
    }

    pub fn geom_qq_with(self, geom: GeomQQ) -> Self {
        self.add_geom_with(geom)
    }

    pub fn geom_qq_line(self) -> Self {
        self.add_geom(GeomQQLine::default())
    }

    pub fn geom_qq_line_with(self, geom: GeomQQLine) -> Self {
        self.add_geom_with(geom)
    }

    pub fn geom_bin2d(self) -> Self {
        self.add_geom(GeomBin2d::default())
    }

    pub fn geom_bin2d_with(self, geom: GeomBin2d) -> Self {
        self.add_geom_with(geom)
    }

    pub fn geom_hex(self) -> Self {
        self.add_geom(GeomHex::default())
    }

    pub fn geom_hex_with(self, geom: GeomHex) -> Self {
        self.add_geom_with(geom)
    }

    pub fn geom_count(self) -> Self {
        self.add_geom(GeomCount::default())
    }

    pub fn geom_count_with(self, geom: GeomCount) -> Self {
        self.add_geom_with(geom)
    }

    pub fn geom_contour(self) -> Self {
        self.add_geom(GeomContour::default())
    }

    pub fn geom_contour_with(self, geom: GeomContour) -> Self {
        self.add_geom_with(geom)
    }

    /// Filled contour bands from gridded (x, y, z) data — draws polygons filled by
    /// band level. Pair with a continuous fill scale (e.g. `scale_fill_viridis_c`).
    pub fn geom_contour_filled(self) -> Self {
        self.add_geom(GeomPolygon {
            line_width: 0.0,
            alpha: 1.0,
            ..GeomPolygon::default()
        })
        .stat(crate::stat::contour_filled::StatContourFilled::default())
    }

    pub fn geom_density2d(self) -> Self {
        self.add_geom(GeomDensity2d::default())
    }

    pub fn geom_density2d_with(self, geom: GeomDensity2d) -> Self {
        self.add_geom_with(geom)
    }

    /// Candlestick chart: map `x` and `open`/`high`/`low`/`close`
    /// (`Aes::new().x("date").open("o").high("h").low("l").close("c")`).
    pub fn geom_candlestick(self) -> Self {
        self.add_geom(crate::geom::candlestick::GeomCandlestick::default())
    }

    pub fn geom_candlestick_with(self, geom: crate::geom::candlestick::GeomCandlestick) -> Self {
        self.add_geom_with(geom)
    }

    /// OHLC bar chart (high–low bar with open/close ticks); same aesthetics as
    /// [`geom_candlestick`](Self::geom_candlestick).
    pub fn geom_ohlc(self) -> Self {
        self.add_geom(crate::geom::candlestick::GeomOhlc::default())
    }

    pub fn geom_ohlc_with(self, geom: crate::geom::candlestick::GeomOhlc) -> Self {
        self.add_geom_with(geom)
    }

    /// Calendar heatmap (GitHub/ECharts style): the plot's `x` (a date —
    /// `DateTime`, epoch seconds or `"YYYY-MM-DD"`) is laid out as week
    /// columns × weekday rows (Sunday on top) via [`StatCalendar`], coloured
    /// by `fill`, with month labels along x, Mon/Wed/Fri along y, month
    /// boundary outlines and square cells. Spans over
    /// [`MAX_CALENDAR_YEARS`] are clipped to the most recent years (with a
    /// build warning). Uses the plot-level data and `x` mapping.
    ///
    /// [`StatCalendar`]: crate::stat::calendar::StatCalendar
    /// [`MAX_CALENDAR_YEARS`]: crate::stat::calendar::MAX_CALENDAR_YEARS
    pub fn geom_calendar(self) -> Self {
        self.geom_calendar_with(
            GeomTile {
                color: (255, 255, 255),
                line_width: 1.5,
                ..Default::default()
            },
            false,
        )
    }

    /// [`geom_calendar`](Self::geom_calendar) with a custom cell style and
    /// optionally Monday-first weeks.
    pub fn geom_calendar_with(mut self, tile: GeomTile, monday_first: bool) -> Self {
        use crate::stat::calendar::{
            day_number, month_boundaries, month_breaks, month_breaks_localized, weekday_labels,
            CalendarGrid, StatCalendar, MAX_CALENDAR_YEARS,
        };
        let grid = self
            .mapping
            .get_mapping(&crate::aes::Aesthetic::X)
            .and_then(|c| self.data.column(c))
            .and_then(|col| {
                CalendarGrid::from_days(col.iter().filter_map(day_number), monday_first)
            });
        let Some((grid, clipped)) = grid else {
            // No dates: an empty calendar layer (renders an empty panel).
            return self.add_geom_with(tile).stat(StatCalendar {
                grid: None,
                monday_first,
            });
        };
        if clipped {
            self.warnings.push(format!(
                "geom_calendar: dates more than {MAX_CALENDAR_YEARS} years before the newest were dropped"
            ));
        }
        let (xb, _) = month_breaks(&grid);
        // Rows: y = 6 - weekday; label Mon/Wed/Fri.
        let yb = if monday_first {
            vec![6.0, 4.0, 2.0]
        } else {
            vec![5.0, 3.0, 1.0]
        };
        let segs = month_boundaries(&grid);
        let col = |f: fn(&(f64, f64, f64, f64)) -> f64| -> Vec<Value> {
            segs.iter().map(|s| Value::Float(f(s))).collect()
        };
        let boundaries = vec![
            ("x".to_string(), col(|s| s.0)),
            ("y".to_string(), col(|s| s.1)),
            ("xend".to_string(), col(|s| s.2)),
            ("yend".to_string(), col(|s| s.3)),
        ];
        self.default_aspect_ratio = Some(7.0 / grid.n_weeks().max(1) as f64);
        let plot = self
            .add_geom_with(tile)
            .stat(StatCalendar {
                grid: Some(grid),
                monday_first,
            })
            .scale_x_continuous(
                ScaleContinuous::new()
                    .with_breaks(xb)
                    // Month / weekday names follow the plot locale.
                    .with_localized_labels(move |l| month_breaks_localized(&grid, l).1)
                    .with_expand(0.0, 0.0),
            )
            .scale_y_continuous(
                ScaleContinuous::new()
                    .with_breaks(yb)
                    .with_localized_labels(weekday_labels)
                    .with_expand(0.0, 0.0),
            );
        if segs.is_empty() {
            return plot;
        }
        // Styled by the theme's `calendar_month_border` at draw time.
        plot.add_geom_with(crate::geom::segment::GeomCalendarBorder)
            .layer_data(boundaries)
            .layer_aes(Aes::new().x("x").y("y").xend("xend").yend("yend"))
            .show_legend(false)
    }

    pub fn geom_blank(self) -> Self {
        self.add_geom(GeomBlank)
    }

    /// Add a geom configured explicitly by the caller: its colours win over
    /// the theme's `primary_color`.
    fn add_geom_with(self, geom: impl Geom + 'static) -> Self {
        let mut plot = self.add_geom(geom);
        if let Some(layer) = plot.layers.last_mut() {
            layer.explicit_style = true;
        }
        plot
    }

    fn add_geom(mut self, geom: impl Geom + 'static) -> Self {
        let stat = geom.default_stat();
        let position = geom.default_position();
        let params = geom.default_params();
        self.layers.push(Layer {
            data: None,
            mapping: Aes::default(),
            geom: Box::new(geom),
            stat,
            position,
            params,
            show_legend: None,
            explicit_style: false,
            tooltip_template: None,
        });
        self
    }

    // ─── Layer-level overrides ──────────────────────────────────

    /// Override the stat for the most recently added layer.
    pub fn stat(mut self, stat: impl Stat + 'static) -> Self {
        if let Some(layer) = self.layers.last_mut() {
            layer.stat = Box::new(stat);
        }
        self
    }

    /// Override the position for the most recently added layer.
    pub fn position(mut self, pos: impl Position + 'static) -> Self {
        if let Some(layer) = self.layers.last_mut() {
            layer.position = Box::new(pos);
        }
        self
    }

    /// Override the data for the most recently added layer.
    pub fn layer_data(mut self, data: impl GGData) -> Self {
        if let Some(layer) = self.layers.last_mut() {
            layer.data = Some(data.into_dataframe());
        }
        self
    }

    /// Override the aesthetic mapping for the most recently added layer.
    pub fn layer_aes(mut self, mapping: Aes) -> Self {
        self.warnings.extend(mapping.warnings.iter().cloned());
        if let Some(layer) = self.layers.last_mut() {
            layer.mapping = mapping;
        }
        self
    }

    /// A `{column}` tooltip template for the most recently added layer
    /// (B2-5), replacing its default `<title>`. Each placeholder is filled
    /// from the *built* layer data (so it can reference a stat-computed
    /// column, e.g. a hex's `count`) at that row, formatted through the
    /// column's scale when it has one
    /// ([`Scale::format_value`](crate::scale::Scale::format_value)) — the same
    /// `data-fvalue` logic, but written into the tooltip text. A column
    /// that doesn't exist on this layer renders as empty, not literally
    /// `{column}`. `{{`/`}}` are literal braces. The result is escaped the
    /// same way any other tooltip is — this is plain text, not markup.
    pub fn tooltip(mut self, template: &str) -> Self {
        if let Some(layer) = self.layers.last_mut() {
            layer.tooltip_template = Some(template.to_string());
        }
        self
    }

    /// Control whether the most recently added layer contributes to the legend.
    /// `true` = always show, `false` = always hide, default (None) = auto.
    pub fn show_legend(mut self, show: bool) -> Self {
        if let Some(layer) = self.layers.last_mut() {
            layer.show_legend = Some(show);
        }
        self
    }

    // ─── Scales ──────────────────────────────────────────────────

    pub fn scale_x_continuous(mut self, s: ScaleContinuous) -> Self {
        let s = s.for_aesthetic(crate::aes::Aesthetic::X);
        self.scales.push(Box::new(s));
        self
    }

    pub fn scale_y_continuous(mut self, s: ScaleContinuous) -> Self {
        let s = s.for_aesthetic(crate::aes::Aesthetic::Y);
        self.scales.push(Box::new(s));
        self
    }

    pub fn scale_x_discrete(mut self, s: crate::scale::discrete::ScaleDiscrete) -> Self {
        let s = s.for_aesthetic(crate::aes::Aesthetic::X);
        self.scales.push(Box::new(s));
        self
    }

    pub fn scale_y_discrete(mut self, s: crate::scale::discrete::ScaleDiscrete) -> Self {
        let s = s.for_aesthetic(crate::aes::Aesthetic::Y);
        self.scales.push(Box::new(s));
        self
    }

    pub fn scale_color(mut self, s: impl Scale + 'static) -> Self {
        self.scales.push(Box::new(s));
        self
    }

    pub fn scale_fill(mut self, s: impl Scale + 'static) -> Self {
        self.scales.push(Box::new(s));
        self
    }

    pub fn scale_color_manual(self, values: Vec<(&str, crate::scale::color::RGBAColor)>) -> Self {
        let s = crate::scale::manual::ScaleManual::new(crate::aes::Aesthetic::Color, values);
        self.scale_color(s)
    }

    pub fn scale_fill_manual(self, values: Vec<(&str, crate::scale::color::RGBAColor)>) -> Self {
        let s = crate::scale::manual::ScaleManual::new(crate::aes::Aesthetic::Fill, values);
        self.scale_fill(s)
    }

    /// The `colour`/`color` column already holds `#RRGGBB`/`#RGB` hex
    /// strings, used as-is — no legend (R's `scale_colour_identity`).
    pub fn scale_colour_identity(self) -> Self {
        let s = crate::scale::identity::ScaleColorIdentity::new(crate::aes::Aesthetic::Color);
        self.scale_color(s)
    }

    /// American-spelling alias for [`scale_colour_identity`](Self::scale_colour_identity).
    pub fn scale_color_identity(self) -> Self {
        self.scale_colour_identity()
    }

    /// The `fill` column already holds `#RRGGBB`/`#RGB` hex strings, used
    /// as-is — no legend (R's `scale_fill_identity`).
    pub fn scale_fill_identity(self) -> Self {
        let s = crate::scale::identity::ScaleColorIdentity::new(crate::aes::Aesthetic::Fill);
        self.scale_fill(s)
    }

    pub fn scale_color_viridis(self) -> Self {
        use crate::scale::color::ScaleColorDiscrete;
        use crate::scale::palettes::PaletteName;
        let s = ScaleColorDiscrete::new(crate::aes::Aesthetic::Color)
            .with_named_palette(&PaletteName::Viridis);
        self.scale_color(s)
    }

    pub fn scale_color_brewer(self, name: crate::scale::palettes::PaletteName) -> Self {
        use crate::scale::color::ScaleColorDiscrete;
        let s = ScaleColorDiscrete::new(crate::aes::Aesthetic::Color).with_named_palette(&name);
        self.scale_color(s)
    }

    pub fn scale_color_gradient(
        self,
        low: crate::scale::color::RGBAColor,
        high: crate::scale::color::RGBAColor,
    ) -> Self {
        use crate::scale::color::ScaleColorContinuous;
        let s = ScaleColorContinuous::new(crate::aes::Aesthetic::Color).with_colors(low, high);
        self.scale_color(s)
    }

    pub fn scale_fill_gradient(
        self,
        low: crate::scale::color::RGBAColor,
        high: crate::scale::color::RGBAColor,
    ) -> Self {
        use crate::scale::color::ScaleColorContinuous;
        let s = ScaleColorContinuous::new(crate::aes::Aesthetic::Fill).with_colors(low, high);
        self.scale_fill(s)
    }

    pub fn scale_color_gradient2(
        self,
        low: crate::scale::color::RGBAColor,
        mid: crate::scale::color::RGBAColor,
        high: crate::scale::color::RGBAColor,
    ) -> Self {
        use crate::scale::gradient::ScaleColorGradient2;
        let s = ScaleColorGradient2::new(crate::aes::Aesthetic::Color).with_colors(low, mid, high);
        self.scale_color(s)
    }

    pub fn scale_fill_gradient2(
        self,
        low: crate::scale::color::RGBAColor,
        mid: crate::scale::color::RGBAColor,
        high: crate::scale::color::RGBAColor,
    ) -> Self {
        use crate::scale::gradient::ScaleColorGradient2;
        let s = ScaleColorGradient2::new(crate::aes::Aesthetic::Fill).with_colors(low, mid, high);
        self.scale_fill(s)
    }

    pub fn scale_fill_viridis(self) -> Self {
        use crate::scale::color::ScaleColorDiscrete;
        use crate::scale::palettes::PaletteName;
        let s = ScaleColorDiscrete::new(crate::aes::Aesthetic::Fill)
            .with_named_palette(&PaletteName::Viridis);
        self.scale_fill(s)
    }

    /// Continuous viridis color scale (for numeric data).
    pub fn scale_color_viridis_c(self) -> Self {
        use crate::scale::gradient_n::ScaleColorGradientN;
        let s = ScaleColorGradientN::viridis(crate::aes::Aesthetic::Color);
        self.scale_color(s)
    }

    /// Continuous viridis fill scale (for numeric data).
    pub fn scale_fill_viridis_c(self) -> Self {
        use crate::scale::gradient_n::ScaleColorGradientN;
        let s = ScaleColorGradientN::viridis(crate::aes::Aesthetic::Fill);
        self.scale_fill(s)
    }

    /// N-stop continuous color gradient.
    pub fn scale_color_gradientn(self, stops: Vec<(f64, crate::scale::color::RGBAColor)>) -> Self {
        use crate::scale::gradient_n::ScaleColorGradientN;
        let s = ScaleColorGradientN::new(crate::aes::Aesthetic::Color, stops);
        self.scale_color(s)
    }

    /// N-stop continuous fill gradient.
    pub fn scale_fill_gradientn(self, stops: Vec<(f64, crate::scale::color::RGBAColor)>) -> Self {
        use crate::scale::gradient_n::ScaleColorGradientN;
        let s = ScaleColorGradientN::new(crate::aes::Aesthetic::Fill, stops);
        self.scale_fill(s)
    }

    /// Binned (stepped) two-colour continuous colour scale — buckets the mapped
    /// variable into `n_bins` bins, each a discrete colour, with a stepped legend.
    pub fn scale_color_steps(
        self,
        low: crate::scale::color::RGBAColor,
        high: crate::scale::color::RGBAColor,
        n_bins: usize,
    ) -> Self {
        let s = crate::scale::steps::ScaleColorSteps::two(
            crate::aes::Aesthetic::Color,
            (low.r, low.g, low.b),
            (high.r, high.g, high.b),
            n_bins,
        );
        self.scale_color(s)
    }

    /// Binned N-stop continuous colour scale.
    pub fn scale_color_stepsn(
        self,
        stops: Vec<crate::scale::color::RGBAColor>,
        n_bins: usize,
    ) -> Self {
        let s = crate::scale::steps::ScaleColorSteps::new(
            crate::aes::Aesthetic::Color,
            stops.iter().map(|c| (c.r, c.g, c.b)).collect(),
            n_bins,
        );
        self.scale_color(s)
    }

    /// Binned ColorBrewer colour scale (R's `scale_color_fermenter`).
    pub fn scale_color_fermenter(
        self,
        name: crate::scale::palettes::PaletteName,
        n_bins: usize,
    ) -> Self {
        let stops = crate::scale::palettes::palette(&name)
            .iter()
            .map(|c| (c.r, c.g, c.b))
            .collect();
        let s =
            crate::scale::steps::ScaleColorSteps::new(crate::aes::Aesthetic::Color, stops, n_bins);
        self.scale_color(s)
    }

    /// Binned (stepped) two-colour continuous fill scale.
    pub fn scale_fill_steps(
        self,
        low: crate::scale::color::RGBAColor,
        high: crate::scale::color::RGBAColor,
        n_bins: usize,
    ) -> Self {
        let s = crate::scale::steps::ScaleColorSteps::two(
            crate::aes::Aesthetic::Fill,
            (low.r, low.g, low.b),
            (high.r, high.g, high.b),
            n_bins,
        );
        self.scale_fill(s)
    }

    /// Binned ColorBrewer fill scale.
    pub fn scale_fill_fermenter(
        self,
        name: crate::scale::palettes::PaletteName,
        n_bins: usize,
    ) -> Self {
        let stops = crate::scale::palettes::palette(&name)
            .iter()
            .map(|c| (c.r, c.g, c.b))
            .collect();
        let s =
            crate::scale::steps::ScaleColorSteps::new(crate::aes::Aesthetic::Fill, stops, n_bins);
        self.scale_fill(s)
    }

    /// Default discrete fill palette with levels in sorted order, so a level
    /// keeps its colour across charts regardless of data order. For a custom
    /// palette: `scale_fill(ScaleColorDiscrete::new(Aesthetic::Fill)
    /// .with_palette(p).sorted())`.
    pub fn scale_fill_discrete_sorted(self) -> Self {
        use crate::scale::color::ScaleColorDiscrete;
        self.scale_fill(ScaleColorDiscrete::new(crate::aes::Aesthetic::Fill).sorted())
    }

    /// Default discrete colour palette with levels in sorted order (see
    /// [`scale_fill_discrete_sorted`](Self::scale_fill_discrete_sorted)).
    pub fn scale_color_discrete_sorted(self) -> Self {
        use crate::scale::color::ScaleColorDiscrete;
        self.scale_color(ScaleColorDiscrete::new(crate::aes::Aesthetic::Color).sorted())
    }

    pub fn scale_fill_brewer(self, name: crate::scale::palettes::PaletteName) -> Self {
        use crate::scale::color::ScaleColorDiscrete;
        let s = ScaleColorDiscrete::new(crate::aes::Aesthetic::Fill).with_named_palette(&name);
        self.scale_fill(s)
    }

    pub fn scale_linetype_manual(
        self,
        values: Vec<(&str, crate::render::backend::Linetype)>,
    ) -> Self {
        let s = crate::scale::linetype_manual::ScaleLinetypeManual::new(values);
        self.scale_color(s)
    }

    pub fn scale_shape_manual(
        self,
        values: Vec<(&str, crate::render::backend::PointShape)>,
    ) -> Self {
        let s = crate::scale::shape_manual::ScaleShapeManual::new(values);
        self.scale_color(s)
    }

    pub fn scale_color_grey(self) -> Self {
        let s = crate::scale::grey::ScaleColorGrey::new(crate::aes::Aesthetic::Color);
        self.scale_color(s)
    }

    pub fn scale_fill_grey(self) -> Self {
        let s = crate::scale::grey::ScaleColorGrey::new(crate::aes::Aesthetic::Fill);
        self.scale_fill(s)
    }

    pub fn scale_color_grey_with(self, s: crate::scale::grey::ScaleColorGrey) -> Self {
        self.scale_color(s)
    }

    pub fn scale_fill_grey_with(self, s: crate::scale::grey::ScaleColorGrey) -> Self {
        self.scale_fill(s)
    }

    pub fn scale_x_reverse(self) -> Self {
        self.scale_x_continuous(ScaleContinuous::new().with_transform(ScaleTransform::Reverse))
    }

    pub fn scale_y_reverse(self) -> Self {
        self.scale_y_continuous(ScaleContinuous::new().with_transform(ScaleTransform::Reverse))
    }

    pub fn scale_x_datetime(mut self, s: crate::scale::datetime::ScaleDateTime) -> Self {
        let s = s.for_aesthetic(crate::aes::Aesthetic::X);
        self.scales.push(Box::new(s));
        self
    }

    pub fn scale_y_datetime(mut self, s: crate::scale::datetime::ScaleDateTime) -> Self {
        let s = s.for_aesthetic(crate::aes::Aesthetic::Y);
        self.scales.push(Box::new(s));
        self
    }

    pub fn scale_size(mut self, s: crate::scale::size::ScaleSizeContinuous) -> Self {
        self.scales.push(Box::new(s));
        self
    }

    pub fn scale_alpha(mut self, s: crate::scale::alpha::ScaleAlphaContinuous) -> Self {
        self.scales.push(Box::new(s));
        self
    }

    /// Continuous linewidth scale for the `linewidth` aesthetic (segment,
    /// curve, path, line) — see
    /// [`ScaleLinewidthContinuous`](crate::scale::linewidth::ScaleLinewidthContinuous).
    pub fn scale_linewidth(mut self, s: crate::scale::linewidth::ScaleLinewidthContinuous) -> Self {
        self.scales.push(Box::new(s));
        self
    }

    pub fn xlim(self, min: f64, max: f64) -> Self {
        self.scale_x_continuous(ScaleContinuous::new().with_limits(min, max))
    }

    pub fn ylim(self, min: f64, max: f64) -> Self {
        self.scale_y_continuous(ScaleContinuous::new().with_limits(min, max))
    }

    pub fn scale_x_log10(self) -> Self {
        self.scale_x_continuous(ScaleContinuous::new().with_transform(ScaleTransform::Log10))
    }

    pub fn scale_y_log10(self) -> Self {
        self.scale_y_continuous(ScaleContinuous::new().with_transform(ScaleTransform::Log10))
    }

    pub fn scale_x_sqrt(self) -> Self {
        self.scale_x_continuous(ScaleContinuous::new().with_transform(ScaleTransform::Sqrt))
    }

    pub fn scale_y_sqrt(self) -> Self {
        self.scale_y_continuous(ScaleContinuous::new().with_transform(ScaleTransform::Sqrt))
    }

    pub fn scale_x_log2(self) -> Self {
        self.scale_x_continuous(ScaleContinuous::new().with_transform(ScaleTransform::Log2))
    }

    pub fn scale_y_log2(self) -> Self {
        self.scale_y_continuous(ScaleContinuous::new().with_transform(ScaleTransform::Log2))
    }

    pub fn scale_x_ln(self) -> Self {
        self.scale_x_continuous(ScaleContinuous::new().with_transform(ScaleTransform::Ln))
    }

    pub fn scale_y_ln(self) -> Self {
        self.scale_y_continuous(ScaleContinuous::new().with_transform(ScaleTransform::Ln))
    }

    /// Logit-transformed x axis (for proportions in (0, 1)).
    pub fn scale_x_logit(self) -> Self {
        self.scale_x_continuous(ScaleContinuous::new().with_transform(ScaleTransform::Logit))
    }

    pub fn scale_y_logit(self) -> Self {
        self.scale_y_continuous(ScaleContinuous::new().with_transform(ScaleTransform::Logit))
    }

    /// Probit-transformed x axis (inverse normal CDF, for proportions in (0, 1)).
    pub fn scale_x_probit(self) -> Self {
        self.scale_x_continuous(ScaleContinuous::new().with_transform(ScaleTransform::Probit))
    }

    pub fn scale_y_probit(self) -> Self {
        self.scale_y_continuous(ScaleContinuous::new().with_transform(ScaleTransform::Probit))
    }

    /// Sign-preserving pseudo-log x axis (handles zero and negative values).
    pub fn scale_x_pseudo_log(self) -> Self {
        self.scale_x_continuous(ScaleContinuous::new().with_transform(ScaleTransform::PseudoLog))
    }

    pub fn scale_y_pseudo_log(self) -> Self {
        self.scale_y_continuous(ScaleContinuous::new().with_transform(ScaleTransform::PseudoLog))
    }

    /// Reciprocal (1/x) x axis.
    pub fn scale_x_reciprocal(self) -> Self {
        self.scale_x_continuous(ScaleContinuous::new().with_transform(ScaleTransform::Reciprocal))
    }

    pub fn scale_y_reciprocal(self) -> Self {
        self.scale_y_continuous(ScaleContinuous::new().with_transform(ScaleTransform::Reciprocal))
    }

    /// Exponential x axis (labels spaced logarithmically).
    pub fn scale_x_exp(self) -> Self {
        self.scale_x_continuous(ScaleContinuous::new().with_transform(ScaleTransform::Exp))
    }

    pub fn scale_y_exp(self) -> Self {
        self.scale_y_continuous(ScaleContinuous::new().with_transform(ScaleTransform::Exp))
    }

    /// Box–Cox x axis with the given lambda (x > 0).
    pub fn scale_x_boxcox(self, lambda: f64) -> Self {
        self.scale_x_continuous(
            ScaleContinuous::new().with_transform(ScaleTransform::BoxCox(lambda)),
        )
    }

    pub fn scale_y_boxcox(self, lambda: f64) -> Self {
        self.scale_y_continuous(
            ScaleContinuous::new().with_transform(ScaleTransform::BoxCox(lambda)),
        )
    }

    // ─── Faceting ─────────────────────────────────────────────────

    pub fn facet_wrap(mut self, var: &str, ncol: Option<usize>) -> Self {
        self.facet = Facet::Wrap {
            var: var.to_string(),
            ncol,
            scales: FacetScales::Fixed,
            labeller: FacetLabeller::default(),
        };
        self
    }

    pub fn facet_wrap_free(mut self, var: &str, ncol: Option<usize>, scales: FacetScales) -> Self {
        self.facet = Facet::Wrap {
            var: var.to_string(),
            ncol,
            scales,
            labeller: FacetLabeller::default(),
        };
        self
    }

    pub fn facet_wrap_labeller(
        mut self,
        var: &str,
        ncol: Option<usize>,
        labeller: FacetLabeller,
    ) -> Self {
        self.facet = Facet::Wrap {
            var: var.to_string(),
            ncol,
            scales: FacetScales::Fixed,
            labeller,
        };
        self
    }

    pub fn facet_grid(mut self, row: Option<&str>, col: Option<&str>) -> Self {
        self.facet = Facet::Grid {
            row_var: row.map(String::from),
            col_var: col.map(String::from),
            scales: FacetScales::Fixed,
            labeller: FacetLabeller::default(),
            space: FacetSpace::Fixed,
        };
        self
    }

    pub fn facet_grid_free(
        mut self,
        row: Option<&str>,
        col: Option<&str>,
        scales: FacetScales,
    ) -> Self {
        self.facet = Facet::Grid {
            row_var: row.map(String::from),
            col_var: col.map(String::from),
            scales,
            labeller: FacetLabeller::default(),
            space: FacetSpace::Fixed,
        };
        self
    }

    /// `facet_grid` over **multiple** column variables (R's `rows ~ b + c`):
    /// the columns become the combination of the given variables' values.
    /// Also accepts free scales + proportional `space` for full parity.
    pub fn facet_grid_multi(
        mut self,
        row: Option<&str>,
        cols: &[&str],
        scales: FacetScales,
        space: FacetSpace,
    ) -> Self {
        let col_var = if cols.len() > 1 {
            // Build a synthetic column that is the interaction of the col vars.
            let n = self.data.nrows();
            let mut combined = Vec::with_capacity(n);
            for i in 0..n {
                let parts: Vec<String> = cols
                    .iter()
                    .map(|c| {
                        self.data
                            .column(c)
                            .and_then(|col| col.get(i))
                            .map(|v| v.to_group_key())
                            .unwrap_or_default()
                    })
                    .collect();
                combined.push(crate::data::Value::Str(parts.join(" . ")));
            }
            let name = "__facet_cols__".to_string();
            self.data.add_column(name.clone(), combined);
            Some(name)
        } else {
            cols.first().map(|s| s.to_string())
        };
        self.facet = Facet::Grid {
            row_var: row.map(String::from),
            col_var,
            scales,
            labeller: FacetLabeller::default(),
            space,
        };
        self
    }

    /// `facet_grid` with proportional panel sizing (R's `space =`): panels are
    /// sized to their data range. Typically paired with free scales.
    pub fn facet_grid_space(
        mut self,
        row: Option<&str>,
        col: Option<&str>,
        scales: FacetScales,
        space: FacetSpace,
    ) -> Self {
        self.facet = Facet::Grid {
            row_var: row.map(String::from),
            col_var: col.map(String::from),
            scales,
            labeller: FacetLabeller::default(),
            space,
        };
        self
    }

    pub fn facet_grid_labeller(
        mut self,
        row: Option<&str>,
        col: Option<&str>,
        labeller: FacetLabeller,
    ) -> Self {
        self.facet = Facet::Grid {
            row_var: row.map(String::from),
            col_var: col.map(String::from),
            scales: FacetScales::Fixed,
            labeller,
            space: FacetSpace::Fixed,
        };
        self
    }

    // ─── Coordinates ─────────────────────────────────────────────

    pub fn coord_flip(mut self) -> Self {
        self.coord = Box::new(CoordFlip);
        self
    }

    pub fn coord_fixed(mut self, ratio: f64) -> Self {
        self.coord = Box::new(CoordFixed::new(ratio));
        self
    }

    /// Spatial coordinate system (feature `sf`): equal aspect derived from the
    /// data extent, so projected geometry keeps its shape. Pair with a `geom_sf`
    /// projection (e.g. Mercator) for a conformal map.
    #[cfg(feature = "sf")]
    pub fn coord_sf(mut self) -> Self {
        self.coord = Box::new(crate::coord::sf::CoordSf::new());
        self
    }

    /// Spatial coordinate system with explicit settings (`xlim`/`ylim`/
    /// `expand`) — see [`CoordSf`](crate::coord::sf::CoordSf). Used by
    /// consumers overlaying a fragment on their own projected basemap: a
    /// fixed pixel window via `xlim`/`ylim` and `expand(false)`.
    #[cfg(feature = "sf")]
    pub fn coord_sf_with(mut self, coord: crate::coord::sf::CoordSf) -> Self {
        self.coord = Box::new(coord);
        self
    }

    /// Whether the rendered root `<svg>` carries `data-plot`/`data-domain`/
    /// `data-xdomain`/… (see [`root_data_attrs`](crate::render::svg_backend::root_data_attrs)).
    /// Default `true`. A consumer that overlays a rendered fragment
    /// (`render_svg_native_at`) on its own basemap — which already has its
    /// own root attributes and window — turns this off so the fragment adds
    /// none of its own.
    pub fn svg_root_data(mut self, on: bool) -> Self {
        self.svg_root_data = on;
        self
    }

    /// Add one extra attribute to the root `<svg>` element — a host
    /// identifier, an ARIA label, a CSS hook, and so on. Allowed names:
    /// `data-*`, `aria-*`, `role`, `id`, `class`, `lang`; anything else, or
    /// a name ggplot-rs already writes to the root (`data-plot`,
    /// `data-domain`, …, or `data-warnings` when
    /// [`svg_warnings_attr`](Self::svg_warnings_attr) is also on), is
    /// ignored with a build warning instead of being silently dropped or
    /// duplicated. Values are escaped on output. PlotGrid has the same API
    /// ([`PlotGrid::svg_attr`](crate::compose::PlotGrid::svg_attr)).
    pub fn svg_attr(mut self, name: impl Into<String>, value: impl Into<String>) -> Self {
        self.root_attrs.push((name.into(), value.into()));
        self
    }

    /// [`svg_attr`](Self::svg_attr) for several attributes at once.
    pub fn svg_attrs(mut self, attrs: impl IntoIterator<Item = (String, String)>) -> Self {
        self.root_attrs.extend(attrs);
        self
    }

    /// Emit a `data-warnings` attribute on the root `<svg>` — a JSON array
    /// of the build warnings (rows dropped for non-finite positions, an
    /// `svg_attr` name rejected, …), `[]` when there are none. Default off,
    /// and omitted entirely when off (byte-identical to not calling this).
    pub fn svg_warnings_attr(mut self, on: bool) -> Self {
        self.svg_warnings_attr = on;
        self
    }

    /// Emit `data-fvalue`/`data-fx` on marks: the value aesthetic's raw
    /// data value (y for most geoms, fill for hex/tile) and the x value,
    /// each formatted through its scale (currency/locale numbers, ISO or
    /// locale dates — [`Scale::format_value`](crate::scale::Scale::format_value))
    /// rather than the plain display string `data-value`/`data-x` already
    /// carry. `data-fx` is omitted when it would just duplicate `data-x`.
    /// Default off, and omitted entirely when off (byte-identical to not
    /// calling this).
    pub fn svg_formatted_values(mut self, on: bool) -> Self {
        self.svg_formatted_values = on;
        self
    }

    /// Transform the coordinate space at draw time (R's `coord_trans`) — stats are
    /// computed on raw data but drawn on non-linear axes. Pass a per-axis
    /// [`ScaleTransform`] (e.g. `Some(ScaleTransform::Log10)`), `None` to leave an
    /// axis linear.
    pub fn coord_trans(mut self, x: Option<ScaleTransform>, y: Option<ScaleTransform>) -> Self {
        self.coord = Box::new(crate::coord::trans::CoordTrans::new(x, y));
        self
    }

    /// `coord_trans` on the y-axis only.
    pub fn coord_trans_y(self, y: ScaleTransform) -> Self {
        self.coord_trans(None, Some(y))
    }

    /// `coord_trans` on the x-axis only.
    pub fn coord_trans_x(self, x: ScaleTransform) -> Self {
        self.coord_trans(Some(x), None)
    }

    /// Zoom into a region without filtering data (unlike xlim/ylim which filter).
    pub fn coord_cartesian_zoom(
        mut self,
        xlim: Option<(f64, f64)>,
        ylim: Option<(f64, f64)>,
    ) -> Self {
        let mut c = CoordCartesian::new();
        if let Some((min, max)) = xlim {
            c = c.xlim(min, max);
        }
        if let Some((min, max)) = ylim {
            c = c.ylim(min, max);
        }
        self.coord = Box::new(c);
        self
    }

    pub fn coord_polar(mut self) -> Self {
        self.coord = Box::new(CoordPolar::new());
        self
    }

    /// Radar / spider chart coordinates: discrete `x` → spokes, `y` → distance
    /// from the centre, straight segments, ring/spoke guides. Pair with
    /// `geom_polygon` (closed series) and `geom_point`.
    pub fn coord_radar(mut self) -> Self {
        self.coord = Box::new(crate::coord::radar::CoordRadar::new());
        self
    }

    pub fn coord_radar_with(mut self, coord: crate::coord::radar::CoordRadar) -> Self {
        self.coord = Box::new(coord);
        self
    }

    pub fn coord_polar_with(mut self, coord: CoordPolar) -> Self {
        self.coord = Box::new(coord);
        self
    }

    // ─── Theme ───────────────────────────────────────────────────

    /// Replace the theme. A `primary_color` set earlier is kept unless the new
    /// theme sets its own, so preset/`primary_color` call order doesn't matter.
    pub fn theme(mut self, theme: Theme) -> Self {
        self.apply_preset(theme);
        self
    }

    fn apply_preset(&mut self, theme: Theme) {
        let primary = self.theme.primary;
        self.theme = theme;
        if self.theme.primary.is_none() {
            self.theme.primary = primary;
        }
    }

    /// Rotate the x-axis tick labels by `degrees` (R's
    /// `guides(x = guide_axis(angle = ...))` / `axis.text.x = element_text(angle)`).
    /// Useful for long category labels. Call after any `theme_*()` preset.
    pub fn axis_text_x_angle(mut self, degrees: f64) -> Self {
        self.theme.axis_text_x.angle = degrees;
        self
    }

    /// Rotate the y-axis tick labels by `degrees`.
    pub fn axis_text_y_angle(mut self, degrees: f64) -> Self {
        self.theme.axis_text_y.angle = degrees;
        self
    }

    /// Stagger x-axis tick labels across `n` rows to avoid overlap (R's
    /// `guides(x = guide_axis(n.dodge = n))`). `1` = no dodging.
    pub fn axis_text_x_dodge(mut self, n: usize) -> Self {
        self.theme.axis_text_x_dodge = n.max(1);
        self
    }

    /// Fix the panel's height:width ratio (R's `aspect.ratio`). Call after any
    /// `theme_*()` preset.
    pub fn aspect_ratio(mut self, ratio: f64) -> Self {
        self.theme.aspect_ratio = Some(ratio);
        self
    }

    /// Draw gridlines on top of the data layers (R's `panel.ontop`).
    pub fn panel_ontop(mut self) -> Self {
        self.theme.panel_ontop = true;
        self
    }

    /// Draw minor tick marks between major ticks (R's `axis.minor.ticks`).
    pub fn axis_minor_ticks(mut self) -> Self {
        self.theme.axis_minor_ticks = true;
        self
    }

    /// Align title/subtitle/caption to the panel or the whole plot width
    /// (R's `plot.title.position`).
    pub fn title_position(mut self, pos: crate::theme::TitlePosition) -> Self {
        self.theme.title_position = pos;
        self
    }

    /// Corner for the `tag()` label (R's `plot.tag.position`).
    pub fn tag_position(mut self, pos: crate::theme::TagPosition) -> Self {
        self.theme.tag_position = pos;
        self
    }

    /// Force the legend key layout direction (R's `legend.direction`).
    pub fn legend_direction(mut self, dir: crate::theme::LegendDirection) -> Self {
        self.theme.legend_direction = Some(dir);
        self
    }

    /// Set the brand/primary color used as the default for single-series geoms
    /// that have no color/fill aesthetic mapped. Composes with any theme — one
    /// render process can serve different tenants' brands at render time.
    /// Place the legend inside the panel at panel-relative coordinates
    /// (0..1, 0..1) — `(0,0)` bottom-left, `(1,1)` top-right (R's
    /// `legend.position = c(x, y)`).
    pub fn legend_position_inside(mut self, x: f64, y: f64) -> Self {
        self.theme.legend_position = crate::theme::LegendPosition::Inside(x, y);
        self
    }

    /// Set the legend position (R's `legend.position`, e.g. `Top`/`Bottom`).
    pub fn legend_position(mut self, pos: crate::theme::LegendPosition) -> Self {
        self.theme.legend_position = pos;
        self
    }

    pub fn primary_color(mut self, color: (u8, u8, u8)) -> Self {
        self.theme.primary = Some(color);
        self
    }

    pub fn theme_minimal(mut self) -> Self {
        self.apply_preset(crate::theme::presets::theme_minimal());
        self
    }

    pub fn theme_bw(mut self) -> Self {
        self.apply_preset(crate::theme::presets::theme_bw());
        self
    }

    pub fn theme_gray(mut self) -> Self {
        self.apply_preset(crate::theme::presets::theme_gray());
        self
    }

    pub fn theme_classic(mut self) -> Self {
        self.apply_preset(crate::theme::presets::theme_classic());
        self
    }

    /// Apply the publication-ready `theme_pubr()` (ggpubr style).
    pub fn theme_pubr(mut self) -> Self {
        self.apply_preset(crate::theme::presets::theme_pubr());
        self
    }

    pub fn theme_linedraw(mut self) -> Self {
        self.apply_preset(crate::theme::presets::theme_linedraw());
        self
    }

    pub fn theme_light(mut self) -> Self {
        self.apply_preset(crate::theme::presets::theme_light());
        self
    }

    pub fn theme_dark(mut self) -> Self {
        self.apply_preset(crate::theme::presets::theme_dark());
        self
    }

    pub fn theme_void(mut self) -> Self {
        self.apply_preset(crate::theme::presets::theme_void());
        self
    }

    /// Apply incremental theme modifications on top of the current theme.
    /// Like R's `+ theme(axis.text.x = element_text(...))`.
    pub fn theme_update(mut self, update: crate::theme::ThemeUpdate) -> Self {
        self.theme = self.theme.update(update);
        self
    }

    // ─── Guides ──────────────────────────────────────────────────

    /// Configure legend guide (title, ncol, reverse).
    pub fn guides(mut self, guide: crate::guide::config::GuideLegend) -> Self {
        self.guide_legend = guide;
        self
    }

    // ─── Labels ──────────────────────────────────────────────────

    pub fn labs(mut self, labels: Labels) -> Self {
        if labels.title.is_some() {
            self.labels.title = labels.title;
        }
        if labels.subtitle.is_some() {
            self.labels.subtitle = labels.subtitle;
        }
        if labels.x.is_some() {
            self.labels.x = labels.x;
        }
        if labels.y.is_some() {
            self.labels.y = labels.y;
        }
        if labels.caption.is_some() {
            self.labels.caption = labels.caption;
        }
        if labels.tag.is_some() {
            self.labels.tag = labels.tag;
        }
        self
    }

    pub fn title(mut self, title: &str) -> Self {
        self.labels.title = Some(title.to_string());
        self
    }

    /// Corner tag label (R's `labs(tag = ...)`), drawn at the top-left — handy
    /// for labelling figure panels ("A", "B", …).
    pub fn tag(mut self, tag: &str) -> Self {
        self.labels.tag = Some(tag.to_string());
        self
    }

    pub fn subtitle(mut self, subtitle: &str) -> Self {
        self.labels.subtitle = Some(subtitle.to_string());
        self
    }

    pub fn xlab(mut self, label: &str) -> Self {
        self.labels.x = Some(label.to_string());
        self
    }

    pub fn ylab(mut self, label: &str) -> Self {
        self.labels.y = Some(label.to_string());
        self
    }

    pub fn caption(mut self, caption: &str) -> Self {
        self.labels.caption = Some(caption.to_string());
        self
    }

    // ─── Annotations ──────────────────────────────────────────────

    /// Add an annotation to the plot.
    pub fn annotate(mut self, annotation: Annotation) -> Self {
        self.annotations.push(annotation);
        self
    }

    /// Add a text annotation at data coordinates.
    pub fn annotate_text(self, label: &str, x: f64, y: f64) -> Self {
        self.annotate(Annotation::text(label, x, y))
    }

    /// Add a rectangle annotation at data coordinates.
    pub fn annotate_rect(self, xmin: f64, xmax: f64, ymin: f64, ymax: f64) -> Self {
        self.annotate(Annotation::rect(xmin, xmax, ymin, ymax))
    }

    /// Add a segment annotation between data coordinates.
    pub fn annotate_segment(self, x: f64, y: f64, xend: f64, yend: f64) -> Self {
        self.annotate(Annotation::segment(x, y, xend, yend))
    }

    /// Default [`Locale`](crate::locale::Locale) for the plot's axis and
    /// legend labels: every continuous position / colour / size / alpha scale
    /// labels its default breaks with the locale's decimal and thousands marks
    /// (`1.000`, `2,5` in de-DE), and date/datetime scales use its month names
    /// and date formats (`Okt. 2026`, `15. Okt. 2026`). A scale's own
    /// `with_locale` and custom `label_*` formatters take precedence.
    /// Without this call labels are unchanged (`.` decimal mark, no grouping,
    /// ISO dates).
    ///
    /// ```
    /// use ggplot_rs::prelude::*;
    /// let svg = GGPlot::new(vec![
    ///         ("x".to_string(), vec![Value::Float(0.0), Value::Float(3000.0)]),
    ///         ("y".to_string(), vec![Value::Float(0.5), Value::Float(2.5)]),
    ///     ])
    ///     .aes(Aes::new().x("x").y("y"))
    ///     .geom_point()
    ///     .locale(Locale::from_tag("de-DE"))
    ///     .render_svg_native()
    ///     .unwrap();
    /// assert!(svg.contains(">1.000<") && svg.contains(">1,5<"));
    /// ```
    pub fn locale(mut self, locale: crate::locale::Locale) -> Self {
        self.locale = Some(locale);
        self
    }

    // ─── Build and Render ────────────────────────────────────────

    /// Build the plot without rendering, returning errors on validation failure.
    pub fn try_build(self) -> Result<crate::build::BuiltPlot, GGError> {
        PlotBuilder::build(self)
    }

    /// Build the plot without rendering (analogous to R's ggplot_build()).
    /// Returns the fully computed BuiltPlot with layer data ready for inspection.
    /// Panics on validation errors — use `try_build()` for error handling.
    pub fn build(self) -> crate::build::BuiltPlot {
        self.try_build().expect("plot build failed")
    }

    /// Build and save the plot to a file. Format determined by extension.
    /// (Requires the `plotters` feature, on by default; native only — wasm has
    /// no filesystem/plotters backend.)
    #[cfg(all(feature = "plotters", not(target_arch = "wasm32")))]
    pub fn save(self, path: &str) -> Result<(), GGError> {
        self.save_with_size(path, 800, 600)
    }

    /// Build and save with custom dimensions. (Feature `plotters`; native only.)
    #[cfg(all(feature = "plotters", not(target_arch = "wasm32")))]
    pub fn save_with_size(self, path: &str, w: u32, h: u32) -> Result<(), GGError> {
        let (built, layout) = self.prepare(w, h)?;

        // Determine backend from file extension
        let ext = path.rsplit('.').next().unwrap_or("svg").to_lowercase();

        match ext.as_str() {
            "svg" => {
                let backend = plotters::prelude::SVGBackend::new(path, (w, h));
                Self::render_into(backend.into_drawing_area(), &built, &layout)?;
            }
            "png" | "bmp" | "gif" | "jpeg" | "jpg" | "tiff" => {
                let backend = plotters::prelude::BitMapBackend::new(path, (w, h));
                Self::render_into(backend.into_drawing_area(), &built, &layout)?;
            }
            _ => {
                return Err(GGError::UnsupportedFormat(ext));
            }
        }

        Ok(())
    }

    /// Render the plot to an in-memory SVG document (default 800x600).
    ///
    /// Unlike [`save`](Self::save), this writes nothing to disk — handy for
    /// serving charts from a web/MCP service. Requires the `plotters` feature
    /// (on by default); without it use [`render_svg_native`](Self::render_svg_native).
    #[cfg(all(feature = "plotters", not(target_arch = "wasm32")))]
    pub fn render_svg(self) -> Result<String, GGError> {
        self.render_svg_with_size(800, 600)
    }

    /// Render the plot to an in-memory SVG document with custom dimensions.
    /// (Feature `plotters`; native only — on wasm or without `plotters` use
    /// [`render_svg_native_with_size`](Self::render_svg_native_with_size).)
    #[cfg(all(feature = "plotters", not(target_arch = "wasm32")))]
    pub fn render_svg_with_size(self, w: u32, h: u32) -> Result<String, GGError> {
        let (built, layout) = self.prepare(w, h)?;
        let mut buf = String::new();
        {
            let backend = plotters::prelude::SVGBackend::with_string(&mut buf, (w, h));
            Self::render_into(backend.into_drawing_area(), &built, &layout)?;
        }
        Ok(buf)
    }

    /// Render to SVG through the self-contained [`SvgBackend`](crate::render::svg_backend::SvgBackend)
    /// — a plotters-free path that drives the same `PlotRenderer`, proving the
    /// `DrawBackend` abstraction (and needing no glyph rasterization).
    pub fn render_svg_native(self) -> Result<String, GGError> {
        self.render_svg_native_with_size(800, 600)
    }

    /// [`render_svg_native`](Self::render_svg_native) with an explicit size.
    ///
    /// The root `<svg>` carries `data-plot="x y w h"` (the panel rect) and the
    /// trained position domains (`data-domain`, `data-xdomain`, `data-ydomain`,
    /// `data-xlevels`, `data-ylevels` — see
    /// [`root_data_attrs`](crate::render::svg_backend::root_data_attrs)).
    /// Hoverable marks carry `data-x`, `data-series` and `data-value`.
    pub fn render_svg_native_with_size(self, w: u32, h: u32) -> Result<String, GGError> {
        Ok(self.render_native(w, h)?.0.finish())
    }

    /// Like [`render_svg_native_with_size`](Self::render_svg_native_with_size),
    /// but also returns the build warnings (rows dropped for non-finite
    /// positions, layers whose stat produced no data, …) — see
    /// [`BuiltPlot::warnings`](crate::build::BuiltPlot::warnings).
    pub fn render_svg_native_with_warnings(
        self,
        w: u32,
        h: u32,
    ) -> Result<(String, Vec<String>), GGError> {
        let (backend, warnings, _) = self.render_native(w, h)?;
        Ok((backend.finish(), warnings))
    }

    /// Render a `w`×`h` chart as a *nested* `<svg x=.. y=.. width=.. height=..
    /// viewBox="0 0 w h">` fragment for composition into a larger SVG (a
    /// dashboard): no `xmlns` (inherited from the parent), positioned at
    /// `(x, y)` in the parent's user space. No string surgery needed:
    ///
    /// ```ignore
    /// let mut page = String::from(r#"<svg xmlns="http://www.w3.org/2000/svg" width="900" height="400">"#);
    /// page += &plot_a.render_svg_native_at(0.0, 0.0, 450, 400)?;
    /// page += &plot_b.render_svg_native_at(450.0, 0.0, 450, 400)?;
    /// page += "</svg>";
    /// ```
    pub fn render_svg_native_at(self, x: f64, y: f64, w: u32, h: u32) -> Result<String, GGError> {
        Ok(self.render_native(w, h)?.0.finish_fragment(x, y))
    }

    /// Like [`render_svg_native_with_size`](Self::render_svg_native_with_size),
    /// but also returns the panel rect in pixels `[x, y, w, h]` — enough to
    /// overlay a WebGL/canvas layer that draws marks in data coordinates.
    pub fn render_svg_area_with_size(self, w: u32, h: u32) -> Result<(String, [f64; 4]), GGError> {
        let (backend, _, pa) = self.render_native(w, h)?;
        Ok((backend.finish(), [pa.x, pa.y, pa.width, pa.height]))
    }

    /// Shared native-SVG pipeline: build, lay out, render into an
    /// [`SvgBackend`](crate::render::svg_backend::SvgBackend) (not yet
    /// finished), returning it with the build warnings and the panel rect.
    fn render_native(
        self,
        w: u32,
        h: u32,
    ) -> Result<
        (
            crate::render::svg_backend::SvgBackend,
            Vec<String>,
            crate::render::Rect,
        ),
        GGError,
    > {
        let svg_root_data = self.svg_root_data;
        let root_attrs = self.root_attrs.clone();
        let svg_warnings_attr = self.svg_warnings_attr;
        let svg_formatted_values = self.svg_formatted_values;
        let (built, layout) = self.prepare(w, h)?;
        let pa = layout.plot_area.clone();
        let mut backend = crate::render::svg_backend::SvgBackend::new(w, h, pa.clone());
        backend.set_formatted_values(svg_formatted_values);
        let existing_root_attrs = if svg_root_data {
            let attrs = crate::render::svg_backend::root_data_attrs(&built);
            backend.set_root_attrs(attrs.clone());
            // `data-plot` itself is a literal in `root_open`, not part of
            // `root_data_attrs`'s output, but it is written whenever
            // `svg_root_data` is on — reserve it too.
            let mut reserved = attrs;
            reserved.push(("data-plot".to_string(), String::new()));
            reserved
        } else {
            backend.without_plot_attr();
            Vec::new()
        };
        PlotRenderer::render(&built, &mut backend).map_err(GGError::Render)?;
        let mut warnings = built.warnings;
        warnings.extend(backend.take_warnings());

        let mut reserved = existing_root_attrs;
        if svg_warnings_attr {
            reserved.push(("data-warnings".to_string(), String::new()));
        }
        let extra = crate::render::svg_backend::validate_root_attrs(
            &root_attrs,
            &reserved,
            "plot",
            &mut warnings,
        );
        backend.extend_root_attrs(extra);
        if svg_warnings_attr {
            backend.extend_root_attrs(vec![(
                "data-warnings".to_string(),
                crate::render::svg_backend::warnings_json(&warnings),
            )]);
        }
        Ok((backend, warnings, pa))
    }

    /// Render to a raw RGBA pixel buffer via the self-contained raster
    /// [`PixelBackend`](crate::render::pixel_backend::PixelBackend) (feature
    /// `canvas`) — fast for large-N and wasm-compatible. Returns `(w, h, rgba)`,
    /// ready for a `<canvas>` `putImageData`.
    #[cfg(feature = "canvas")]
    pub fn render_rgba_with_size(self, w: u32, h: u32) -> Result<(u32, u32, Vec<u8>), GGError> {
        let (built, layout) = self.prepare(w, h)?;
        let mut backend =
            crate::render::pixel_backend::PixelBackend::new(w, h, layout.plot_area.clone());
        PlotRenderer::render(&built, &mut backend).map_err(GGError::Render)?;
        let (ow, oh) = backend.dimensions();
        Ok((ow, oh, backend.into_rgba()))
    }

    /// Like [`render_rgba_with_size`](Self::render_rgba_with_size), but also
    /// returns the panel rect in pixels `[x, y, w, h]` — enough to map a canvas
    /// pixel back to data coordinates for interactive hover.
    #[cfg(feature = "canvas")]
    pub fn render_rgba_area_with_size(
        self,
        w: u32,
        h: u32,
    ) -> Result<(Vec<u8>, [f64; 4]), GGError> {
        let (built, layout) = self.prepare(w, h)?;
        let pa = layout.plot_area.clone();
        let mut backend = crate::render::pixel_backend::PixelBackend::new(w, h, pa.clone());
        PlotRenderer::render(&built, &mut backend).map_err(GGError::Render)?;
        Ok((backend.into_rgba(), [pa.x, pa.y, pa.width, pa.height]))
    }

    /// Render to PNG bytes via the raster [`PixelBackend`](crate::render::pixel_backend::PixelBackend)
    /// (feature `canvas`). Unlike [`render_png`](Self::render_png) this needs no
    /// plotters bitmap backend, so it also works on wasm.
    #[cfg(feature = "canvas")]
    pub fn render_png_raster_with_size(self, w: u32, h: u32) -> Result<Vec<u8>, GGError> {
        let (built, layout) = self.prepare(w, h)?;
        let mut backend =
            crate::render::pixel_backend::PixelBackend::new(w, h, layout.plot_area.clone());
        PlotRenderer::render(&built, &mut backend).map_err(GGError::Render)?;
        backend.into_png().map_err(GGError::Render)
    }

    /// Render the plot to in-memory PNG bytes (default 800x600).
    ///
    /// Returns a fully-encoded PNG, ready to write to an HTTP response or
    /// embed as a data URI — no temp files involved. Requires the `plotters`
    /// feature (on by default); see also `render_png_raster_with_size`
    /// (feature `canvas`).
    #[cfg(all(feature = "plotters", not(target_arch = "wasm32")))]
    pub fn render_png(self) -> Result<Vec<u8>, GGError> {
        self.render_png_with_size(800, 600)
    }

    /// Render the plot to in-memory PNG bytes with custom dimensions. (Feature
    /// `plotters`; native only — PNG needs the plotters bitmap backend.)
    #[cfg(all(feature = "plotters", not(target_arch = "wasm32")))]
    pub fn render_png_with_size(self, w: u32, h: u32) -> Result<Vec<u8>, GGError> {
        let (built, layout) = self.prepare(w, h)?;

        // plotters' BitMapBackend draws into a raw RGB buffer; we then encode
        // that buffer to PNG via the `image` crate.
        let mut rgb = vec![0u8; (w as usize) * (h as usize) * 3];
        {
            let backend = plotters::prelude::BitMapBackend::with_buffer(&mut rgb, (w, h));
            Self::render_into(backend.into_drawing_area(), &built, &layout)?;
        }

        let img = image::RgbImage::from_raw(w, h, rgb).ok_or_else(|| {
            GGError::Render(RenderError::BackendError(
                "PNG buffer size mismatch".to_string(),
            ))
        })?;
        let mut out = std::io::Cursor::new(Vec::new());
        img.write_to(&mut out, image::ImageOutputFormat::Png)
            .map_err(|e| GGError::Render(RenderError::BackendError(format!("{:?}", e))))?;
        Ok(out.into_inner())
    }

    /// Shared pipeline: build the plot, apply label overrides, compute layout.
    pub(crate) fn prepare(
        self,
        w: u32,
        h: u32,
    ) -> Result<(crate::build::BuiltPlot, PlotLayout), GGError> {
        let (mut built, meta) = self.build_for_render()?;
        let layout = Self::layout_built(&mut built, &meta, w, h);
        Ok((built, layout))
    }

    /// The size-independent half of [`prepare`](Self::prepare): build the plot,
    /// resolve theme inheritance and apply axis-label overrides.
    pub(crate) fn build_for_render(self) -> Result<(crate::build::BuiltPlot, RenderMeta), GGError> {
        let plot = self;

        let has_title = plot.labels.title.is_some();
        let has_subtitle = plot.labels.subtitle.is_some();
        let has_caption = plot.labels.caption.is_some();
        let has_legend = plot.has_legend_mapping();
        let x_label = plot.labels.x.clone();
        let y_label = plot.labels.y.clone();

        let mut built = PlotBuilder::build(plot)?;

        // Resolve R-style theme inheritance (root `text` → child text elements).
        built.theme.resolve_inheritance();

        // Apply user label overrides to scales
        if let Some(ref label) = x_label {
            if let Some(s) = built.scales.get_mut(&crate::aes::Aesthetic::X) {
                s.set_name(label);
            }
        }
        if let Some(ref label) = y_label {
            if let Some(s) = built.scales.get_mut(&crate::aes::Aesthetic::Y) {
                s.set_name(label);
            }
        }

        Ok((
            built,
            RenderMeta {
                has_title,
                has_subtitle,
                has_caption,
                has_legend,
            },
        ))
    }

    /// The size-dependent half of [`prepare`](Self::prepare): auto-tune axis
    /// labels for `w`×`h` and compute the layout.
    pub(crate) fn layout_built(
        built: &mut crate::build::BuiltPlot,
        meta: &RenderMeta,
        w: u32,
        h: u32,
    ) -> PlotLayout {
        let RenderMeta {
            has_title,
            has_subtitle,
            has_caption,
            has_legend,
        } = *meta;
        let x_axis_top = built
            .scales
            .get(&crate::aes::Aesthetic::X)
            .map(|s| s.axis_position_opposite())
            .unwrap_or(false);

        // Auto-tune categorical axis labels so they stay legible. A flip swaps
        // which trained scale sits on each visual axis: the bottom (x) axis reads
        // the Y scale when flipped, the left (y) axis reads the X scale.
        let flipped = built.coord.is_flipped();
        let h_aes = if flipped {
            crate::aes::Aesthetic::Y
        } else {
            crate::aes::Aesthetic::X
        };
        let v_aes = if flipped {
            crate::aes::Aesthetic::X
        } else {
            crate::aes::Aesthetic::Y
        };

        // Crowded discrete bottom-axis labels overlap when drawn flat. Rotate
        // them — 45° if that de-collides, otherwise vertical (90°) — and reserve
        // the bottom space they actually need. Only when no explicit angle was set.
        let x_rot: Option<(f64, f64)> =
            if built.theme.axis_text_x.visible && built.theme.axis_text_x.angle.abs() < 1.0 {
                built.scales.get(&h_aes).and_then(|hs| {
                    if !hs.is_discrete() {
                        return None;
                    }
                    let breaks = hs.breaks();
                    let n = breaks.len().max(1) as f64;
                    let max_ch = breaks
                        .iter()
                        .map(|(_, l)| l.chars().count())
                        .max()
                        .unwrap_or(0) as f64;
                    let font = built.theme.axis_text_x.size;
                    let label_w = max_ch * font * 0.6; // horizontal extent, drawn flat
                    let spacing = 0.9 * w as f64 / n; // ~px between adjacent ticks
                    if label_w <= spacing {
                        return None; // fits flat — leave it
                    }
                    // 45° shrinks the horizontal footprint by cos45; if that fits,
                    // use it, else go vertical (270° = reads bottom-to-top, hanging
                    // below the axis like the y-axis title). Reserve the drop height.
                    let vertical = label_w * 0.707 > spacing;
                    let angle = if vertical { 270.0 } else { 45.0 };
                    let drop = if vertical { label_w } else { label_w * 0.707 };
                    Some((angle, drop + font + 4.0))
                })
            } else {
                None
            };
        let x_label_height = x_rot.map(|(_, drop)| drop);
        if let Some((angle, _)) = x_rot {
            built.theme.axis_text_x.angle = angle;
        }

        // Reserve the left-axis width from the actual label lengths so long
        // category names (a flipped bar chart's rows) aren't clipped. Never
        // shrinks below the default; grows up to 35% of the width.
        let y_label_width = if built.theme.axis_text_y.visible {
            built.scales.get(&v_aes).map(|vs| {
                let max_ch = vs
                    .breaks()
                    .iter()
                    .map(|(_, l)| l.chars().count())
                    .max()
                    .unwrap_or(0);
                let measured = max_ch as f64 * built.theme.axis_text_y.size * 0.6 + 4.0;
                let default = built.theme.axis_text_y.size * 3.5 + 4.0;
                measured.max(default).min(0.35 * w as f64)
            })
        } else {
            None
        };

        PlotLayout::compute_full(
            w as f64,
            h as f64,
            &built.theme,
            has_title,
            has_subtitle,
            has_caption,
            has_legend,
            x_axis_top,
            y_label_width,
            x_label_height,
        )
    }

    /// Fill the background, render the built plot, and flush — for any plotters
    /// backend. (Native only.)
    #[cfg(all(feature = "plotters", not(target_arch = "wasm32")))]
    fn render_into<DB>(
        area: plotters::drawing::DrawingArea<DB, plotters::coord::Shift>,
        built: &crate::build::BuiltPlot,
        layout: &PlotLayout,
    ) -> Result<(), GGError>
    where
        DB: plotters::prelude::DrawingBackend,
        DB::ErrorType: 'static,
    {
        area.fill(&plotters::prelude::WHITE)
            .map_err(|e| GGError::Render(RenderError::BackendError(format!("{:?}", e))))?;
        let mut adapter = PlottersAdapter::new(&area, layout.plot_area.clone());
        PlotRenderer::render(built, &mut adapter).map_err(GGError::Render)?;
        area.present()
            .map_err(|e| GGError::Render(RenderError::BackendError(format!("{:?}", e))))?;
        Ok(())
    }

    /// Save with physical dimensions (inches) and DPI. (Feature `plotters`;
    /// native only.)
    #[cfg(all(feature = "plotters", not(target_arch = "wasm32")))]
    pub fn ggsave(
        self,
        path: &str,
        width_inches: f64,
        height_inches: f64,
        dpi: f64,
    ) -> Result<(), GGError> {
        let w = (width_inches * dpi) as u32;
        let h = (height_inches * dpi) as u32;
        self.save_with_size(path, w, h)
    }

    fn has_legend_mapping(&self) -> bool {
        self.mapping.mappings.iter().any(|m| {
            matches!(
                m.aesthetic,
                crate::aes::Aesthetic::Color
                    | crate::aes::Aesthetic::Fill
                    | crate::aes::Aesthetic::Shape
                    | crate::aes::Aesthetic::Linetype
                    | crate::aes::Aesthetic::Size
                    | crate::aes::Aesthetic::Alpha
            )
        })
    }
}

/// Size-independent facts about a built plot that its layout needs.
#[derive(Clone, Copy, Debug)]
pub(crate) struct RenderMeta {
    pub(crate) has_title: bool,
    pub(crate) has_subtitle: bool,
    pub(crate) has_caption: bool,
    pub(crate) has_legend: bool,
}

/// Top-level error type.
#[derive(Debug)]
pub enum GGError {
    Render(RenderError),
    UnsupportedFormat(String),
    Io(std::io::Error),
    ValidationError(String),
}

impl std::fmt::Display for GGError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            GGError::Render(e) => write!(f, "Render error: {e}"),
            GGError::UnsupportedFormat(ext) => write!(f, "Unsupported output format: {ext}"),
            GGError::Io(e) => write!(f, "IO error: {e}"),
            GGError::ValidationError(msg) => write!(f, "Validation error: {msg}"),
        }
    }
}

impl std::error::Error for GGError {}