"""Public plot functions: pr_curve, confusion_matrix, top_confusions, per_category_ap,
tide_errors, reliability_diagram, comparison_bar, category_deltas.
"""

from __future__ import annotations

from pathlib import Path
from typing import Any

from .core import (
    TIDE_ERROR_ORDER,
    _annotate_f1_peak,
    _configure_axes,
    _headroom_for_bar_labels,
    _import_mpl,
    _mask_invalid_prec,
    _new_figure,
    _save_and_return,
    _top_confusion_keep,
)
from .data import PlotData
from .theme import CHROME, _build_rc, _get_theme, eval_colors


def pr_curve_iou_sweep(
    coco_eval,
    *,
    iou_thrs: list[float] | None = None,
    area_rng: str = "all",
    max_det: int | None = None,
    theme: str = "cyanotype",
    paper_mode: bool = False,
    ax=None,
    save_path: str | Path | None = None,
) -> tuple:
    """Plot mean precision-recall across all IoU thresholds.

    One line per IoU threshold, precision averaged across all categories. The
    primary line (lowest IoU) is annotated at its F1 peak, and filled under only
    when the plot has at most two curves — a fill runs to zero, so under the
    topmost curve of a wider sweep it tints every other curve's area too.

    Parameters
    ----------
    coco_eval : COCOeval
        Must have ``run()`` called first.
    iou_thrs : list[float], optional
        IoU thresholds to include. Default: all thresholds in params. Raises
        ``ValueError`` if a threshold is not in this run's grid.
    area_rng : str
        Area range label. Default ``"all"``.
    max_det : int, optional
        Max detections. Default: last entry in ``params.max_dets``.
    theme : str
        ``"cyanotype"`` (default) or ``"cyanotype-dark"``.
    paper_mode : bool
        White figure and axes background for PDF/LaTeX inclusion.
    ax : matplotlib.axes.Axes, optional
    save_path : str or Path, optional

    Returns
    -------
    (Figure, Axes)
    """
    mpl, _, _ = _import_mpl()
    data = PlotData.from_coco_eval(coco_eval)
    a_idx = data.area_idx(area_rng)
    m_idx = data.max_det_idx(max_det)

    t_indices = list(range(len(data.iou_thresholds))) if iou_thrs is None else data.iou_indices(iou_thrs)

    with mpl.rc_context(_build_rc(theme, paper_mode)):
        fig, ax = _new_figure((6, 6), ax, layout="compressed")

        n_curves = len(t_indices)
        for line_idx, t_idx in enumerate(t_indices):
            prec = data.mean_precision(t_idx, a_idx, m_idx)
            lw = 2 if line_idx == 0 else 1
            (line,) = ax.plot(data.recall_pts, prec, linewidth=lw, label=f"IoU={data.iou_thresholds[t_idx]:.2f}")
            if line_idx == 0:
                _annotate_f1_peak(ax, data.recall_pts, prec, line, fill=n_curves <= 2)

        ax.set(xlim=(0, 1), ylim=(0, 1), aspect="equal", xlabel="Recall", ylabel="Precision")
        # A PR sweep fills its own lower-left corner, so an inside legend lands on
        # the data as soon as there are more than a few lines. Past that, move it
        # out of the axes entirely rather than drawing over the curves.
        if n_curves > 4:
            ax.legend(fontsize=9, loc="center left", bbox_to_anchor=(1.02, 0.5))
        else:
            ax.legend(fontsize=9, loc="lower left")
        _configure_axes(ax, "Precision-Recall", subtitle="mean over categories", value_axis="y")
    return _save_and_return(fig, ax, save_path)


def pr_curve_by_category(
    coco_eval,
    cat_id: int,
    *,
    iou_thr: float = 0.5,
    area_rng: str = "all",
    max_det: int | None = None,
    theme: str = "cyanotype",
    paper_mode: bool = False,
    ax=None,
    save_path: str | Path | None = None,
) -> tuple:
    """Plot the precision-recall curve for a single category.

    Parameters
    ----------
    coco_eval : COCOeval
        Must have ``run()`` called first.
    cat_id : int
        Category ID to plot.
    iou_thr : float
        IoU threshold. Default 0.50.
    area_rng : str
        Area range label. Default ``"all"``.
    max_det : int, optional
        Max detections. Default: last entry in ``params.max_dets``.
    theme : str
        ``"cyanotype"`` (default) or ``"cyanotype-dark"``.
    paper_mode : bool
        White figure and axes background for PDF/LaTeX inclusion.
    ax : matplotlib.axes.Axes, optional
    save_path : str or Path, optional

    Returns
    -------
    (Figure, Axes)
    """

    mpl, _, _ = _import_mpl()
    data = PlotData.from_coco_eval(coco_eval)
    a_idx = data.area_idx(area_rng)
    m_idx = data.max_det_idx(max_det)

    if cat_id not in data.cat_ids:
        raise ValueError(f"cat_id {cat_id} not in params.cat_ids")

    k_idx = data.cat_ids.index(cat_id)
    t_idx = data.nearest_iou_idx(iou_thr)
    prec = _mask_invalid_prec(data.precision[t_idx, :, k_idx, a_idx, m_idx])
    cat_name = data.cat_names.get(cat_id, str(cat_id))

    with mpl.rc_context(_build_rc(theme, paper_mode)):
        fig, ax = _new_figure((6, 6), ax, layout="compressed")
        (line,) = ax.plot(data.recall_pts, prec, linewidth=2)
        _annotate_f1_peak(ax, data.recall_pts, prec, line)

        ax.set(xlim=(0, 1), ylim=(0, 1), aspect="equal", xlabel="Recall", ylabel="Precision")
        _configure_axes(ax, "Precision-Recall", subtitle=cat_name, value_axis="y")
    return _save_and_return(fig, ax, save_path)


def pr_curve_top_n(
    coco_eval,
    *,
    cat_ids: list[int] | None = None,
    top_n: int = 10,
    iou_thr: float = 0.5,
    area_rng: str = "all",
    max_det: int | None = None,
    theme: str = "cyanotype",
    paper_mode: bool = False,
    ax=None,
    save_path: str | Path | None = None,
) -> tuple:
    """Plot precision-recall curves for multiple categories.

    Parameters
    ----------
    coco_eval : COCOeval
        Must have ``run()`` called first.
    cat_ids : list[int], optional
        Categories to plot. If omitted, the top ``top_n`` by AP are selected.
    top_n : int
        Number of top categories when ``cat_ids`` is not given. Default 10.
    iou_thr : float
        IoU threshold. Default 0.50.
    area_rng : str
        Area range label. Default ``"all"``.
    max_det : int, optional
        Max detections. Default: last entry in ``params.max_dets``.
    theme : str
        ``"cyanotype"`` (default) or ``"cyanotype-dark"``.
    paper_mode : bool
        White figure and axes background for PDF/LaTeX inclusion.
    ax : matplotlib.axes.Axes, optional
    save_path : str or Path, optional

    Returns
    -------
    (Figure, Axes)
    """
    import numpy as np

    mpl, _, _ = _import_mpl()
    data = PlotData.from_coco_eval(coco_eval)
    a_idx = data.area_idx(area_rng)
    m_idx = data.max_det_idx(max_det)
    t_idx = data.nearest_iou_idx(iou_thr)

    if cat_ids is None:
        cat_aps = []
        for k_i, cid in enumerate(data.cat_ids):
            p = data.precision[t_idx, :, k_i, a_idx, m_idx]
            valid = p[p >= 0]
            cat_aps.append((cid, float(np.mean(valid)) if len(valid) else 0.0))
        cat_aps.sort(key=lambda x: x[1], reverse=True)
        cat_ids = [cid for cid, _ in cat_aps[:top_n]]

    cat_id_to_k = {cid: k for k, cid in enumerate(data.cat_ids)}

    with mpl.rc_context(_build_rc(theme, paper_mode)):
        fig, ax = _new_figure((6, 6), ax, layout="compressed")

        for cid in cat_ids:
            k_idx = cat_id_to_k.get(cid)
            if k_idx is None:
                continue
            prec = _mask_invalid_prec(data.precision[t_idx, :, k_idx, a_idx, m_idx])
            ax.plot(data.recall_pts, prec, linewidth=1.5, label=data.cat_names.get(cid, str(cid)))

        ax.set(xlim=(0, 1), ylim=(0, 1), aspect="equal", xlabel="Recall", ylabel="Precision")
        ax.legend(fontsize=8, loc="lower left")
        _configure_axes(
            ax, "Precision-Recall by Category", subtitle=f"IoU={data.iou_thresholds[t_idx]:.2f}", value_axis="y"
        )
    return _save_and_return(fig, ax, save_path)


def pr_curve(
    coco_eval,
    *,
    iou_thrs=None,
    cat_id=None,
    cat_ids=None,
    iou_thr=None,
    top_n=10,
    area_rng="all",
    max_det=None,
    theme="cyanotype",
    paper_mode=False,
    ax=None,
    save_path=None,
):
    """Plot a precision-recall curve, dispatching on the arguments given.

    ``cat_id=`` plots a single category (``pr_curve_by_category``);
    ``cat_ids=`` or ``iou_thr=`` plots one curve per category
    (``pr_curve_top_n``); with neither, one curve per IoU threshold
    (``pr_curve_iou_sweep``). The named functions take the same keyword
    arguments and can be called directly.
    """
    # `iou_thr if ... else 0.5`, not `iou_thr or 0.5`: an explicit 0.0 is a
    # valid threshold and must not be silently replaced by the default.
    resolved_iou_thr = iou_thr if iou_thr is not None else 0.5
    if cat_id is not None:
        return pr_curve_by_category(
            coco_eval,
            cat_id,
            iou_thr=resolved_iou_thr,
            area_rng=area_rng,
            max_det=max_det,
            theme=theme,
            paper_mode=paper_mode,
            ax=ax,
            save_path=save_path,
        )
    if cat_ids is not None or iou_thr is not None:
        return pr_curve_top_n(
            coco_eval,
            cat_ids=cat_ids,
            top_n=top_n,
            iou_thr=resolved_iou_thr,
            area_rng=area_rng,
            max_det=max_det,
            theme=theme,
            paper_mode=paper_mode,
            ax=ax,
            save_path=save_path,
        )
    return pr_curve_iou_sweep(
        coco_eval,
        iou_thrs=iou_thrs,
        area_rng=area_rng,
        max_det=max_det,
        theme=theme,
        paper_mode=paper_mode,
        ax=ax,
        save_path=save_path,
    )


def confusion_matrix(
    cm_dict: dict[str, Any],
    *,
    normalize: bool = True,
    top_n: int | None = None,
    group_by: str | None = None,
    cat_groups: dict[str, list[str]] | None = None,
    theme: str = "cyanotype",
    paper_mode: bool = False,
    ax=None,
    save_path: str | Path | None = None,
) -> tuple:
    """Plot a confusion matrix heatmap.

    Parameters
    ----------
    cm_dict : dict
        Output of ``coco_eval.confusion_matrix()``.
    normalize : bool
        Use row-normalized values (default True).
    top_n : int, optional
        Show only the top N categories by off-diagonal confusion mass.
        Auto-set to 25 when there are more than 30 categories and no explicit value is given.
    group_by : str, optional
        ``"supercategory"`` to aggregate into COCO supercategory groups.
        Requires ``cat_groups`` mapping.
    cat_groups : dict[str, list[str]], optional
        Mapping of group name to list of category names for ``group_by``.
    theme : str
        ``"cyanotype"`` (default) or ``"cyanotype-dark"``.
    paper_mode : bool
        White figure and axes background for PDF/LaTeX inclusion.
    ax : matplotlib.axes.Axes, optional
        Existing axes to draw on.
    save_path : str or Path, optional
        Save figure to this path.

    Returns
    -------
    (Figure, Axes)
    """
    import numpy as np

    mpl, _, _ = _import_mpl()

    raw_matrix = np.asarray(cm_dict["matrix"], dtype=float)
    norm_matrix = np.asarray(cm_dict["normalized"], dtype=float)
    cat_names = list(cm_dict["cat_names"])
    n_cats = len(cat_names)

    # ---- Supercategory grouping ----
    if group_by == "supercategory" and cat_groups is not None:
        name_to_idx = {n: i for i, n in enumerate(cat_names)}
        group_names = sorted(cat_groups.keys())
        n_groups = len(group_names)

        grouped = np.zeros((n_groups + 1, n_groups + 1), dtype=float)
        group_idx_map = {}
        for gi, gname in enumerate(group_names):
            for cname in cat_groups[gname]:
                if cname in name_to_idx:
                    group_idx_map[cname] = gi

        for i, iname in enumerate(cat_names):
            gi = group_idx_map.get(iname)
            if gi is None:
                continue
            for j, jname in enumerate(cat_names):
                gj = group_idx_map.get(jname)
                if gj is None:
                    continue
                grouped[gi, gj] += raw_matrix[i, j]
            grouped[gi, n_groups] += raw_matrix[i, n_cats]
        for j, jname in enumerate(cat_names):
            gj = group_idx_map.get(jname)
            if gj is not None:
                grouped[n_groups, gj] += raw_matrix[n_cats, j]
        grouped[n_groups, n_groups] = raw_matrix[n_cats, n_cats]

        if normalize:
            row_sums = grouped.sum(axis=1, keepdims=True)
            row_sums[row_sums == 0] = 1
            data = grouped / row_sums
        else:
            data = grouped

        labels = group_names + ["BG"]
        n_plotted = n_groups
    else:
        labels = cat_names + ["BG"]
        data = norm_matrix if normalize else raw_matrix
        n_plotted = n_cats

    # One tail for both branches. When this only ran on the ungrouped branch,
    # `top_n` was silently ignored alongside `group_by` — and a grouped matrix
    # with many supercategories got no auto-subset either.
    keep = _top_confusion_keep(data, n_plotted, top_n)
    if keep is not None:
        data = data[np.ix_(keep, keep)]
        labels = [labels[i] for i in keep]

    n = len(labels)
    size = min(max(6, 0.35 * n), 20)
    vmax = 1.0 if normalize else None
    rc = _build_rc(theme, paper_mode)
    with mpl.rc_context(rc):
        # layout=None: make_axes_locatable is incompatible with constrained/compressed layout
        fig, ax = _new_figure((size, size), ax, layout=None)

        im = ax.imshow(data, aspect="equal", vmin=0, vmax=vmax, interpolation="none")

        suppress = 0.01 if normalize else 1

        def _ink(value: float) -> str:
            """Pick the ink that survives on this cell.

            Driven by the cell's own luminance, not the theme: on a light theme
            the high cells are dark navy and on a dark theme they are bright
            steel, so a fixed "white for high values" is wrong in one of them.
            """
            r, g, b, _ = im.cmap(im.norm(value))
            chan = [c / 12.92 if c <= 0.03928 else ((c + 0.055) / 1.055) ** 2.4 for c in (r, g, b)]
            lum = 0.2126 * chan[0] + 0.7152 * chan[1] + 0.0722 * chan[2]
            return CHROME["plot_bg"] if lum < 0.45 else CHROME["text"]

        for i in range(n):
            for j in range(n):
                val = data[i, j]
                if val < suppress:
                    continue
                color = _ink(val)
                text = f"{val:.2f}" if normalize else f"{int(val)}"
                ax.text(j, i, text, ha="center", va="center", color=color, fontsize=max(5, min(9, 100 / n)))

        ax.set_xticks(range(n))
        ax.set_yticks(range(n))
        ax.set_xticklabels(labels, rotation=45, ha="right")
        ax.set_yticklabels(labels)
        ax.set_xlabel("Predicted")
        ax.set_ylabel("Ground truth")
        ax.set_frame_on(False)
        _configure_axes(ax, "Confusion Matrix", value_axis=None)
        from mpl_toolkits.axes_grid1 import make_axes_locatable

        divider = make_axes_locatable(ax)
        cax = divider.append_axes("right", size="5%", pad=0.08)
        fig.colorbar(im, cax=cax)

    return _save_and_return(fig, ax, save_path)


def top_confusions(
    cm_dict: dict[str, Any],
    *,
    top_n: int = 20,
    theme: str = "cyanotype",
    paper_mode: bool = False,
    ax=None,
    save_path: str | Path | None = None,
) -> tuple:
    """Plot the top N most common misclassifications as horizontal bars.

    This is the go-to plot for large numbers of categories (>30) where a
    full confusion matrix heatmap is unreadable. Shows only off-diagonal
    mistakes: "ground truth X predicted as Y".

    Parameters
    ----------
    cm_dict : dict
        Output of ``coco_eval.confusion_matrix()``.
    top_n : int
        Number of top confusions to show. Default 20.
    theme : str
        ``"cyanotype"`` (default) or ``"cyanotype-dark"``.
    paper_mode : bool
        White figure and axes background for PDF/LaTeX inclusion.
    ax : matplotlib.axes.Axes, optional
        Existing axes to draw on.
    save_path : str or Path, optional
        Save figure to this path.

    Returns
    -------
    (Figure, Axes)
    """
    import numpy as np

    mpl, _, _ = _import_mpl()

    matrix = np.asarray(cm_dict["matrix"], dtype=int)
    cat_names = list(cm_dict["cat_names"])
    n_cats = len(cat_names)
    labels = cat_names + ["BG"]

    pairs = []
    for i in range(n_cats + 1):
        for j in range(n_cats + 1):
            if i == j:
                continue
            count = int(matrix[i, j])
            if count > 0:
                pairs.append((labels[i], labels[j], count))

    pairs.sort(key=lambda x: x[2], reverse=True)
    pairs = pairs[:top_n]

    with mpl.rc_context(_build_rc(theme, paper_mode)):
        if not pairs:
            fig, ax = _new_figure((8, 3), ax)
            ax.text(0.5, 0.5, "No confusions found", ha="center", va="center", fontsize=12, transform=ax.transAxes)
            _configure_axes(ax, "Top Confusions", value_axis=None)
            return _save_and_return(fig, ax, save_path)

        bar_labels = [f"{gt} \u2192 {pred}" for gt, pred, _ in pairs]
        counts = [c for _, _, c in pairs]
        num_bars = len(bar_labels)

        fig, ax = _new_figure((8, max(4, 0.35 * num_bars)), ax)
        bars = ax.barh(range(num_bars), counts, height=0.7)
        ax.bar_label(bars, labels=[str(c) for c in counts], fontsize=8, padding=3)
        _headroom_for_bar_labels(ax, counts)

        ax.set_yticks(range(num_bars))
        ax.set_yticklabels(bar_labels)
        ax.invert_yaxis()
        ax.set_xlabel("Count")
        _configure_axes(ax, "Top Confusions", subtitle="ground truth \u2192 prediction", value_axis="x")

    return _save_and_return(fig, ax, save_path)


def per_category_ap(
    results_dict: dict[str, Any],
    *,
    top_n: int = 20,
    bottom_n: int = 5,
    theme: str = "cyanotype",
    paper_mode: bool = False,
    ax=None,
    save_path: str | Path | None = None,
) -> tuple:
    """Plot per-category AP as horizontal bars.

    Parameters
    ----------
    results_dict : dict
        Output of ``coco_eval.results(per_class=True)``.
    top_n : int
        Number of top categories to show.
    bottom_n : int
        Number of bottom categories to show.
    theme : str
        ``"cyanotype"`` (default) or ``"cyanotype-dark"``.
    paper_mode : bool
        White figure and axes background for PDF/LaTeX inclusion.
    ax : matplotlib.axes.Axes, optional
        Existing axes to draw on.
    save_path : str or Path, optional
        Save figure to this path.

    Returns
    -------
    (Figure, Axes)
    """
    mpl, _, _ = _import_mpl()

    per_class = results_dict.get("per_class", {})
    if not per_class:
        raise ValueError("No per-class data. Call results(per_class=True).")

    items = sorted(per_class.items(), key=lambda x: x[1], reverse=True)

    if len(items) > top_n + bottom_n:
        items = items[:top_n] + [("...", None)] + items[-bottom_n:]

    names = [x[0] for x in items]
    values = [x[1] if x[1] is not None else 0 for x in items]
    num_bars = len(names)

    with mpl.rc_context(_build_rc(theme, paper_mode)):
        fig, ax = _new_figure((8, max(4, 0.3 * num_bars)), ax)

        bar_color = next(iter(mpl.rcParams["axes.prop_cycle"]))["color"]
        sep_color = mpl.rcParams.get("grid.color", "#cccccc")
        colors = [sep_color if n == "..." else bar_color for n in names]
        bars = ax.barh(range(num_bars), values, height=0.7, color=colors)

        bar_labels = [f"{v:.2f}" if n != "..." else "" for n, v in zip(names, values)]
        ax.bar_label(bars, labels=bar_labels, fontsize=7.5, padding=3)
        _headroom_for_bar_labels(ax, values)

        real_values = [v for n, v in zip(names, values) if n != "..."]
        mean_ap = sum(real_values) / len(real_values) if real_values else 0
        ax.axvline(mean_ap, linestyle="--", linewidth=1, label=f"Mean AP: {mean_ap:.3f}")

        ax.set_yticks(range(num_bars))
        ax.set_yticklabels(names)
        ax.invert_yaxis()
        ax.set_xlabel("AP")
        ax.legend(fontsize=9, loc="lower right")
        _configure_axes(ax, "Per-Category AP", value_axis="x")

    return _save_and_return(fig, ax, save_path)


def tide_errors(
    tide_dict: dict[str, Any],
    *,
    theme: str = "cyanotype",
    paper_mode: bool = False,
    ax=None,
    save_path: str | Path | None = None,
) -> tuple:
    """Plot TIDE error breakdown as horizontal bars.

    Parameters
    ----------
    tide_dict : dict
        Output of ``coco_eval.tide_errors()``.
    theme : str
        ``"cyanotype"`` (default) or ``"cyanotype-dark"``.
    paper_mode : bool
        White figure and axes background for PDF/LaTeX inclusion.
    ax : matplotlib.axes.Axes, optional
        Existing axes to draw on.
    save_path : str or Path, optional
        Save figure to this path.

    Returns
    -------
    (Figure, Axes)
    """
    mpl, _, _ = _import_mpl()

    delta_ap = tide_dict["delta_ap"]
    ap_base = tide_dict["ap_base"]

    error_types = list(TIDE_ERROR_ORDER)
    values = [delta_ap.get(e, 0.0) for e in error_types]

    with mpl.rc_context(_build_rc(theme, paper_mode)):
        fig, ax = _new_figure((8, 4), ax)
        bars = ax.barh(range(len(error_types)), values, height=0.6)
        ax.bar_label(bars, labels=[f"{v:.3f}" for v in values], fontsize=9, padding=3)
        _headroom_for_bar_labels(ax, values)

        ax.set_yticks(range(len(error_types)))
        ax.set_yticklabels(error_types)
        ax.invert_yaxis()
        ax.set_xlabel("\u0394AP")
        _configure_axes(ax, "TIDE Error Breakdown", subtitle=f"baseline AP={ap_base:.3f}", value_axis="x")

    return _save_and_return(fig, ax, save_path)


def reliability_diagram(
    cal_or_eval,
    *,
    n_bins: int = 10,
    iou_threshold: float = 0.5,
    theme: str = "cyanotype",
    paper_mode: bool = False,
    ax=None,
    save_path: str | Path | None = None,
) -> tuple:
    """Plot a reliability diagram showing predicted confidence vs actual accuracy.

    Parameters
    ----------
    cal_or_eval : dict or COCOeval
        Either the output of ``ev.calibration()`` (a dict) or a ``COCOeval``
        instance (must have ``evaluate()`` called). If a ``COCOeval`` is
        passed, ``calibration()`` is called automatically.
    n_bins : int
        Number of bins (only used when ``cal_or_eval`` is a COCOeval).
    iou_threshold : float
        IoU threshold (only used when ``cal_or_eval`` is a COCOeval).
    theme : str
        ``"cyanotype"`` (default) or ``"cyanotype-dark"``.
    paper_mode : bool
        White figure and axes background for PDF/LaTeX inclusion.
    ax : matplotlib.axes.Axes, optional
    save_path : str or Path, optional

    Returns
    -------
    (Figure, Axes)
    """
    import numpy as np

    mpl, _, _ = _import_mpl()

    if isinstance(cal_or_eval, dict):
        cal = cal_or_eval
    else:
        cal = cal_or_eval.calibration(n_bins=n_bins, iou_threshold=iou_threshold)

    bins = cal["bins"]
    ece = cal["ece"]
    mce = cal["mce"]

    midpoints = np.array([(b["bin_lower"] + b["bin_upper"]) / 2 for b in bins])
    accuracies = np.array([b["avg_accuracy"] for b in bins])
    confidences = np.array([b["avg_confidence"] for b in bins])
    counts = np.array([b["count"] for b in bins])
    bin_width = bins[0]["bin_upper"] - bins[0]["bin_lower"] if bins else 0.1
    nonempty = counts > 0

    # A miscalibration gap is false-positive mass, so it takes the FP semantic.
    # Resolved by theme: `#B24A2E` is invisible on the dark ground.
    gap_color = eval_colors(theme)["fp"]

    with mpl.rc_context(_build_rc(theme, paper_mode)):
        # Chrome off the live rcParams, not the theme dict: _build_rc is the one
        # place that resolves a theme, and paper_mode swaps the grounds there.
        # Reading the dict instead re-derives that decision at the call site and
        # ignores an enclosing style() or the caller's own rc_context.
        rc = mpl.rcParams
        tick, spine, ink = rc["xtick.color"], rc["axes.edgecolor"], rc["text.color"]

        fig, ax = _new_figure((6, 6), ax, layout="compressed")

        # Gap shading: over/under-confident regions
        ax.fill_between([0, 1], [0, 1], [0, 0], alpha=0.06, color=tick, label="_nolegend_")

        # Perfect calibration diagonal
        ax.plot([0, 1], [0, 1], "--", color=tick, linewidth=1, label="Perfect", zorder=1)

        # Accuracy bars
        ax.bar(midpoints[nonempty], accuracies[nonempty], width=bin_width * 0.85, alpha=0.7, label="Accuracy", zorder=2)

        # Gap bars -- calibration error in both directions.
        # Overconfident (accuracy < confidence): solid gap above the bar.
        # Underconfident (accuracy > confidence): hatched gap inside the bar.
        #
        # Both opaque, and deliberately so. The two land on different grounds --
        # the solid gap on the plot background, the hatch on top of an accuracy
        # bar -- so any alpha below 1 composites one semantic into two different
        # colors. It also destroys the hue: the FP amber at 0.35 over `#141415`
        # resolves to `#664A30`, a brown, which is the same "an amber dark
        # enough drifts brown" failure the caveat color was chosen to avoid.
        mid = midpoints[nonempty]
        acc = accuracies[nonempty]
        conf = confidences[nonempty]
        gaps = conf - acc
        bar_w = bin_width * 0.85
        has_gap_label = False

        overconfident = gaps > 0
        if overconfident.any():
            ax.bar(
                mid[overconfident],
                gaps[overconfident],
                bottom=acc[overconfident],
                width=bar_w,
                color=gap_color,
                label="Gap",
                zorder=3,
            )
            has_gap_label = True

        underconfident = gaps < 0
        if underconfident.any():
            ax.bar(
                mid[underconfident],
                -gaps[underconfident],
                bottom=conf[underconfident],
                width=bar_w,
                facecolor="none",
                edgecolor=gap_color,
                hatch="///",
                linewidth=0,
                label="_nolegend_" if has_gap_label else "Gap",
                zorder=3,
            )

        ax.set(xlim=(0, 1), ylim=(0, 1), aspect="equal", xlabel="Confidence", ylabel="Accuracy")
        ax.legend(fontsize=9, loc="upper left")

        # ECE/MCE annotation
        ax.text(
            0.95,
            0.05,
            f"ECE = {ece:.4f}\nMCE = {mce:.4f}",
            transform=ax.transAxes,
            fontsize=9,
            ha="right",
            va="bottom",
            color=ink,
            bbox={
                # The plot ground, not white: a white box under the dark theme's
                # `#EAEAEA` text renders the two numbers invisible.
                "boxstyle": "round,pad=0.3",
                "facecolor": rc["axes.facecolor"],
                "alpha": 0.85,
                "edgecolor": spine,
            },
        )

        _configure_axes(
            ax,
            "Reliability Diagram",
            subtitle=f"IoU\u2265{cal['iou_threshold']:.2f}, {cal['num_detections']:,} detections",
            value_axis="y",
        )

    return _save_and_return(fig, ax, save_path)


def comparison_bar(
    compare_result: dict[str, Any],
    *,
    theme: str = "cyanotype",
    paper_mode: bool = False,
    ax=None,
    save_path: str | Path | None = None,
) -> tuple:
    """Grouped bar chart comparing metrics between two models.

    Parameters
    ----------
    compare_result : dict
        Output of ``hotcoco.compare(eval_a, eval_b)``.
    theme : str
        ``"cyanotype"`` (default) or ``"cyanotype-dark"``.
    paper_mode : bool
        White figure and axes background for PDF/LaTeX inclusion.
    ax : matplotlib.axes.Axes, optional
    save_path : str or Path, optional

    Returns
    -------
    (Figure, Axes)
    """
    import numpy as np

    mpl, _, _ = _import_mpl()

    metrics_a = compare_result["metrics_a"]
    metrics_b = compare_result["metrics_b"]
    ci = compare_result.get("ci")
    name_a = compare_result.get("name_a", "Model A")
    name_b = compare_result.get("name_b", "Model B")

    keys = compare_result.get("metric_keys")
    if keys:
        keys = [k for k in keys if metrics_a.get(k, -1) >= 0 or metrics_b.get(k, -1) >= 0]
    else:
        keys = sorted(k for k in metrics_a if metrics_a[k] >= 0 or metrics_b.get(k, -1) >= 0)

    vals_a = np.array([max(metrics_a.get(k, 0), 0) for k in keys])
    vals_b = np.array([max(metrics_b.get(k, 0), 0) for k in keys])

    x = np.arange(len(keys))
    bar_width = 0.35

    with mpl.rc_context(_build_rc(theme, paper_mode)):
        fig, ax = _new_figure((max(8, 0.8 * len(keys)), 5), ax)
        colors = mpl.rcParams["axes.prop_cycle"].by_key()["color"]
        color_a = colors[0]
        color_b = colors[1] if len(colors) > 1 else colors[0]

        # Error bars from bootstrap CIs (on delta, applied to model B bars)
        yerr_b = None
        if ci:
            lo = np.array([ci[k]["lower"] if k in ci else 0 for k in keys])
            hi = np.array([ci[k]["upper"] if k in ci else 0 for k in keys])
            # CI is on delta (B-A), center is vals_b, so asymmetric error
            yerr_b = np.array([vals_b - (vals_a + lo), vals_a + hi - vals_b])
            yerr_b = np.clip(yerr_b, 0, None)

        ax.bar(x - bar_width / 2, vals_a, bar_width, label=name_a, color=color_a)
        ax.bar(
            x + bar_width / 2,
            vals_b,
            bar_width,
            label=name_b,
            color=color_b,
            yerr=yerr_b,
            capsize=3,
            error_kw={"linewidth": 1},
        )

        ax.set_xticks(x)
        ax.set_xticklabels(keys, rotation=45, ha="right", fontsize=9)
        ax.set_ylabel("Score")
        ax.legend(fontsize=9)
        _configure_axes(ax, "Model Comparison", value_axis="y")

    return _save_and_return(fig, ax, save_path)


def category_deltas(
    compare_result: dict[str, Any],
    *,
    top_k: int = 20,
    theme: str = "cyanotype",
    paper_mode: bool = False,
    ax=None,
    save_path: str | Path | None = None,
) -> tuple:
    """Horizontal bar chart of per-category AP deltas between two models.

    Parameters
    ----------
    compare_result : dict
        Output of ``hotcoco.compare(eval_a, eval_b)``.
    top_k : int
        Number of categories to show from each end (top improvements + top
        regressions). Default 20.
    theme : str
        ``"cyanotype"`` (default) or ``"cyanotype-dark"``.
    paper_mode : bool
        White figure and axes background for PDF/LaTeX inclusion.
    ax : matplotlib.axes.Axes, optional
    save_path : str or Path, optional

    Returns
    -------
    (Figure, Axes)
    """
    mpl, _, _ = _import_mpl()

    cats = compare_result.get("per_category", [])
    if not cats:
        raise ValueError("No per-category data in compare result.")

    name_a = compare_result.get("name_a", "Model A")
    name_b = compare_result.get("name_b", "Model B")

    # Already sorted by delta ascending (worst regressions first)
    # Take top_k from each end
    if len(cats) > 2 * top_k:
        shown = cats[:top_k] + cats[-top_k:]
    else:
        shown = list(cats)

    names = [c["cat_name"] for c in shown]
    deltas = [c["delta"] for c in shown]
    # Madder for a regression, Fern for an improvement — the palette's own two.
    # Read from the theme rather than rcParams: this runs before the rc_context
    # below is entered, so rcParams would still hold the caller's palette.
    series = _get_theme(theme)["series"]
    down, up = series[1], series[8]
    colors = [down if d < 0 else up for d in deltas]
    num_bars = len(names)

    with mpl.rc_context(_build_rc(theme, paper_mode)):
        fig, ax = _new_figure((8, max(4, 0.3 * num_bars)), ax)

        ax.barh(range(num_bars), deltas, height=0.7, color=colors)
        ax.axvline(0, color=mpl.rcParams["axes.edgecolor"], linewidth=0.8, linestyle="-")

        ax.set_yticks(range(num_bars))
        ax.set_yticklabels(names)
        ax.invert_yaxis()
        ax.set_xlabel(f"AP Delta ({name_b} \u2212 {name_a})")
        _configure_axes(ax, "Per-Category AP Delta", subtitle=f"{name_b} vs {name_a}", value_axis="x")

    return _save_and_return(fig, ax, save_path)
