API¶

def audit(fig: Figure, scale: float | None = None, placed_frac: float = 1.0,
          *,
          context_axes: Sequence[Axes] | None = None,
          venue: str | None = None,
          ) -> tuple[bool, list[tuple[str, bool | str, str]]]:
    """Run every gate over a figure. Returns `(ok, rows)`.

    `check_palette.check` returns the same shape. It returned `(rows, ok)`
    until 0.4.0, and unpacking either one the wrong way binds a bool to the
    rows and raises nothing at the call site, which is why they were made to
    agree rather than documented as differing.

    `rows` are `(label, status, detail)`, one per gate, in the order the report
    prints them. `status` is True, False, or the string "warn"; only a hard
    False sets `ok` to False, so an advisory row reports without gating a
    build.

    `placed_frac` is the fraction of the content width the figure is placed at,
    and `venue` names a row of `VENUE_WIDTH_PT` instead of setting
    `CONTENT_WIDTH_PT` by hand; between them they decide the page scale every
    type and stroke measurement runs through. `scale` overrides that
    calculation outright. `context_axes` names axes whose fill is a context
    surface rather than data ink, which is what stops a filled contourf panel
    reading as saturated.

    `context_axes` and `venue` are keyword-only. They were positional until
    0.9.0, and a `venue` passed in the `context_axes` slot was iterated into a
    frozenset of axes ids rather than raising, because a string is iterable.
    The venue was discarded and the figure was measured at the wrong width: a
    wrong verdict, reported green, from an argument order. Keyword-only is the
    only shape in which that call cannot be written.

    Args:
        fig: The built figure. Measured through an Agg canvas at `MEASURE_DPI`
            and handed back on its authored dpi, so the verdict depends on
            neither the backend it was made on nor the resolution it was set to.
        scale: Points per authored inch, overriding `page_scale` outright.
        placed_frac: Fraction of the content width the figure is placed at.
        venue: A key of `VENUE_WIDTH_PT`, overriding `CONTENT_WIDTH_PT`.
        context_axes: Axes whose fill is a context surface, not data ink.

    Returns:
        `(ok, rows)`. `rows` are `(label, status, detail)`, one per gate, in
        report order; `ok` is False only when a row is a hard False.
    """
    with _at_draw_rc(fig), _at_measure_dpi(fig):
        rows = _rows(fig, scale, placed_frac, venue, context_axes)
    # "warn" rows are advisory: they report something worth a look without
    # failing the build. Only a hard False gates.
    return all(s is not False for _, s, _ in rows), rows

def report(fig: Figure, name: str = "", scale: float | None = None,
           placed_frac: float = 1.0,
           *,
           context_axes: Sequence[Axes] | None = None,
           venue: str | None = None, suggest: bool = False) -> bool:
    """`audit()`, printed. Returns the same `ok` bool and nothing else.

    The arguments are `audit`'s, plus `name` for the heading. Advisory rows
    print as WARN and do not change the verdict, so a figure can be COMPOSED
    with advisories; only a hard FAIL makes this return False.

    `suggest=True` prints what `suggest_fixes.py` has to offer for the marked
    rows, under the table. Off by default and kept in that file rather than
    this one: a gate measures, and what to do about it is a separate claim that
    can be wrong on its own. Several rows get more than one suggestion, because
    the choice between them is the author's.

    This is what the examples and the CLI call. Use `audit()` when the rows
    themselves are wanted rather than a printed table.

    `context_axes`, `venue` and `suggest` are keyword-only, matching `audit`.
    They were positional until 0.9.0, and a `venue` passed in the
    `context_axes` slot was iterated into a frozenset of axes ids rather than
    raising, because a string is iterable. The venue was discarded and the
    figure was measured at the wrong width: a wrong verdict, reported green,
    from an argument order. Keyword-only is the only shape in which that call
    cannot be written.

    Args:
        fig: The built figure.
        name: A heading for the table.
        scale: Points per authored inch, overriding `page_scale` outright.
        placed_frac: Fraction of the content width the figure is placed at.
        venue: A key of `VENUE_WIDTH_PT`, overriding `CONTENT_WIDTH_PT`.
        context_axes: Axes whose fill is a context surface, not data ink.
        suggest: Print `suggest_fixes` remedies under the table.

    Returns:
        `audit`'s `ok` bool. Advisory rows print as WARN without changing it.
    """
    ok, rows = audit(fig, scale, placed_frac,
                     context_axes=context_axes, venue=venue)
    print(f"\nComposition audit{': ' + name if name else ''}")
    warned = False
    for label, status, detail in rows:
        tag = "WARN" if status == "warn" else ("PASS" if status else "FAIL")
        warned = warned or status == "warn"
        print(f"  [{tag}] {label:<18} {detail}")
    verdict = "COMPOSED" if ok else "FIX THE MARKED CHECKS"
    if ok and warned:
        verdict += " (with advisories)"
    print(f"\n  -> {verdict}\n")
    if suggest:
        _print_suggestions(rows)
    return ok

def describe(fig: Figure, text: str) -> None:
    """Attach a text description to a figure, for readers who cannot see it.

    Across 100,000 public Jupyter notebooks, 99.81% of programmatically
    generated images shipped with no alt text at all, and the overwhelming
    majority of them were matplotlib. Matplotlib has no field for this, so the
    description is stashed on the figure and handed to `savefig`:

        describe(fig, "Validation loss against training epoch for three "
                      "optimisers. All three fall; the Bayesian run reaches "
                      "0.05 by epoch 6, the baseline is still at 0.25 at 12.")
        fig.savefig(path, metadata=alt_metadata(fig, path))

    Say what the reader would have taken from looking, not what the figure is
    made of. "A line chart with three lines" describes the file; the numbers
    and the direction describe the finding.

    Args:
        fig: The figure to attach the description to.
        text: The description. `ALT_TEXT_MIN_CHARS` is the gate's floor.

    Returns:
        `None`. The description is stashed on `fig` for `alt_metadata` to read.
    """
    setattr(fig, ALT_TEXT_ATTR, str(text))
    return fig

def alt_metadata(fig: Figure, path: Any = None) -> dict[str, str] | None:
    """The `metadata=` dict for `savefig`, carrying whatever `describe` set.

    Pass the same `path` you are about to save to, so the description lands in
    a field the target format actually has:

        fig.savefig(path, metadata=alt_metadata(fig, path))

    PNG, PDF and SVG all keep a description and none of them agrees with the
    others about what to call it, so the key is chosen from the suffix.

    For a format that carries no description -- ps, or any of the rasters --
    this returns `None` rather than an empty dict, and the difference is not
    cosmetic. matplotlib's guard is `elif metadata is not None: raise`, so an
    empty dict is rejected exactly as hard as a full one; `savefig(path,
    metadata={})` on a jpeg is a traceback. `None` is `savefig`'s own default
    for the argument and the only value those formats accept.

    Called without a path, or with a buffer whose format cannot be read, it
    returns `Description`. That is right for PNG and SVG and is what every
    earlier version returned unconditionally.

    Args:
        fig: The figure `describe` was called on.
        path: The path about to be saved to. The suffix picks the key.

    Returns:
        A dict for `savefig(metadata=)`, or `None` for a format that carries
        no description. Empty when `describe` was never called.
    """
    # Before the empty-description check, because a format that rejects the
    # kwarg rejects `{}` too -- the figure having nothing to say does not make
    # the jpeg save survive.
    suffix = _savefig_suffix(path) if path is not None else None
    if suffix in ALT_TEXT_UNSUPPORTED_SUFFIXES:
        return None
    text = getattr(fig, ALT_TEXT_ATTR, None)
    if not text:
        return {}
    if suffix is None:
        return {ALT_TEXT_KEY_DEFAULT: text}
    return {ALT_TEXT_KEY_BY_SUFFIX.get(suffix, ALT_TEXT_KEY_DEFAULT): text}

def page_scale(fig: Figure, placed_frac: float = 1.0,
               venue: str | None = None) -> float:
    """Scale from authored inches to points on the page.

    `placed_frac` is the fraction of the content width the figure is placed at,
    so it reads like the call site: `\\includegraphics[width=0.48\\textwidth]`
    is `placed_frac=0.48`. Without it every figure is measured as if it were
    full width, and a half-width figure is certified at twice the type size it
    actually ships at - which is the wrong direction for a legibility gate to
    be wrong in.

    `venue` names a row of `VENUE_WIDTH_PT` and overrides `CONTENT_WIDTH_PT` for
    this call, which is the usual way in: the width is a property of the
    document, not of the checkout.

    Args:
        fig: The figure, read for its authored width in inches.
        placed_frac: Fraction of the content width the figure is placed at.
        venue: A key of `VENUE_WIDTH_PT`, overriding `CONTENT_WIDTH_PT`.

    Returns:
        Points on the page per authored inch. `1.0` when no content width is
        set, which measures the figure at the size it was authored.

    Raises:
        ValueError: `placed_frac` is not 1.0 and no content width is set.
    """
    width = content_width_pt(venue)
    if width is None:
        if placed_frac != 1.0:
            raise ValueError(
                "placed_frac requires a content width. With CONTENT_WIDTH_PT "
                "None and no venue= the checker assumes you authored the "
                "figure at the width it is placed at, which already makes the "
                "scale 1.0; a fractional placement contradicts that. Pass "
                "venue=, set CONTENT_WIDTH_PT, or author at the placed width "
                "and drop placed_frac.")
        return 1.0
    return width * placed_frac / (fig.get_size_inches()[0] * 72)

def content_width_pt(venue: str | None = None) -> float | None:
    """The usable page width to measure against, in points.

    Args:
        venue: A key of `VENUE_WIDTH_PT`. `None` reads `CONTENT_WIDTH_PT`.

    Returns:
        The width in points, or `None` when neither is set.

    Raises:
        KeyError: The venue is not in `VENUE_WIDTH_PT`.
    """
    if venue is None:
        return CONTENT_WIDTH_PT
    try:
        return VENUE_WIDTH_PT[venue]
    except KeyError:
        raise KeyError(
            f"unknown venue {venue!r}. Known: "
            f"{', '.join(sorted(VENUE_WIDTH_PT))}. For anything else, put "
            "\\the\\textwidth in the document, read the log, and set "
            "CONTENT_WIDTH_PT to what it says.") from None

def scatter_diameter_pt(size: float | np.ndarray) -> float | np.ndarray:
    """The diameter in points that `scatter(s=size)` actually draws.

    matplotlib documents `s` as "the marker size in points**2", which reads as
    an area and is not one. The unit marker path for 'o' is a circle of radius
    0.5, and scatter scales it by `sqrt(s)`: the drawn diameter is `sqrt(s)`
    points and the drawn area is `pi * s / 4`, a factor 4/pi below the nominal
    number.

    Measured rather than inferred. At 200 dpi, `scatter(s=100)` and
    `plot(markersize=10)` each lay down 741 pixels of ink, which is what makes
    `markersize` and `sqrt(s)` the same quantity and `s` an area only up to
    that constant. `test_scatter_size_is_a_squared_diameter` pins it against
    matplotlib rather than against this docstring.

    Args:
        size: The value passed to `scatter(s=)`. A float or a numpy array.

    Returns:
        The drawn diameter in points, `sqrt(size)`, in the same shape as
        `size` was given.

    Public because both `check_mark_ratio` and `check_overplotting` decide on
    it.
    """
    return size ** 0.5

def check(colors: Sequence[str], surface: str = "#ffffff",
          all_pairs: bool = False, ordinal: bool = False,
          ink: Collection[str] = frozenset(),
          ) -> tuple[bool, list[tuple[str, bool | str, str]]]:
    """Gate a palette. Returns `(ok, rows)`.

    The order matches `check_figure.audit`. It did not until 0.4.0: this
    returned `(rows, ok)` and the README carried a paragraph warning about the
    difference, which is documentation standing in for a fix. Unpacking either
    one the wrong way binds a bool to the rows and raises nothing, so the two
    were made the same rather than described.

    `rows` are `(name, status, detail)`, one per gate. `status` is True,
    False, or the string "warn" for the advisory contrast row, and only a
    hard False sets `ok` to False.

    `colors` are hex strings. `surface` is the page they are drawn on and sets
    what the contrast row measures against. `all_pairs` gates every pair rather
    than adjacent ones, which is what a scatter needs and a line chart does
    not. `ordinal` swaps the categorical separation rows for the ramp rows:
    monotone lightness, even steps, a light end that still holds contrast.
    `ink` names colours to treat as furniture rather than data.

    Args:
        colors: Hex strings, the palette to gate.
        surface: The page colour they are drawn on.
        all_pairs: Gate every pair rather than adjacent ones.
        ordinal: Swap the categorical rows for the ramp rows.
        ink: Colours to treat as furniture rather than data.

    Returns:
        `(ok, rows)`. `rows` are `(name, status, detail)`, one per gate;
        `status` is True, False or "warn", and `ok` is False only when a
        row is a hard False.
    """
    lin = [hex_to_linear(c) for c in colors]
    lab = [linear_to_oklab(v) for v in lin]
    rows: list[tuple[str, bool | str, str]] = []
    ok = True

    if ordinal:
        ls = [v[0] for v in lab]
        mono = all(x > y for x, y in zip(ls, ls[1:])) or all(x < y for x, y in zip(ls, ls[1:]))
        rows.append(("Lightness monotone", mono, "steps read light->dark" if mono
                     else "steps are not monotone in lightness"))
        gaps = [abs(x - y) for x, y in zip(ls, ls[1:])]
        gap_ok = all(g >= ORDINAL_DL_MIN for g in gaps)
        rows.append(("Adjacent dL", gap_ok,
                     f"min gap {min(gaps):.3f}" if gaps else "single step"))
        light_end = max(colors, key=lambda c: linear_to_oklab(hex_to_linear(c))[0])
        cr = contrast(light_end, surface)
        rows.append(("Light-end contrast", cr >= ORDINAL_LIGHT_END_CONTRAST_MIN,
                     f"{light_end} at {cr:.2f}:1 vs surface"))
        # Step uniformity replaced an earlier "Single hue" gate (hue spread <= 20
        # degrees). That gate was a proxy for the property actually wanted, and it
        # rejected perceptually uniform multi-hue ramps such as viridis while
        # accepting a single-hue ramp with wildly uneven steps. What makes a ramp
        # readable is monotone lightness in even increments, which the three rows
        # above plus this one measure directly. The rainbow failure mode the old
        # gate was aimed at (jet) is caught by "Lightness monotone".
        ratio = max(gaps) / min(gaps) if gaps and min(gaps) > 0 else float("inf")
        rows.append(("Step uniformity", ratio <= ORDINAL_STEP_RATIO_MAX,
                     f"largest/smallest dL {ratio:.2f}" if gaps else "single step"))
        return all(r[1] for r in rows), rows

    ink_set = set(ink) if isinstance(ink, frozenset) else set(ink)
    band = [c for c, v in zip(colors, lab)
            if c not in ink_set and not (L_MIN <= v[0] <= L_MAX)]
    n_exempt_band = sum(1 for c in colors if c in ink_set and
                        not (L_MIN <= linear_to_oklab(hex_to_linear(c))[0] <= L_MAX))
    rows.append(("Lightness band", not band,
                 f"all {len(colors)} inside L {L_MIN}-{L_MAX}" if not band
                 else f"outside: {band}"
                 + (f" ({n_exempt_band} ink tokens exempted)" if n_exempt_band else "")))

    chroma = [c for c, v in zip(colors, lab)
              if c not in ink_set and math.hypot(v[1], v[2]) < CHROMA_MIN]
    n_exempt_chroma = sum(1 for c in colors if c in ink_set and
                          math.hypot(*linear_to_oklab(hex_to_linear(c))[1:]) < CHROMA_MIN)
    rows.append(("Chroma floor", not chroma,
                 f"all {len(colors)} >= {CHROMA_MIN}" if not chroma
                 else f"too gray: {chroma}"
                 + (f" ({n_exempt_chroma} ink tokens exempted)" if n_exempt_chroma else "")))

    pairs = (list(itertools.combinations(range(len(colors)), 2)) if all_pairs
             else [(i, i + 1) for i in range(len(colors) - 1)])
    label = "all-pairs" if all_pairs else "adjacent"

    # Gate on protanopia and deuteranopia (~8% of males between them). Tritan is
    # reported but not gated: it is ~0.01% prevalence, and the Vienot matrix used
    # here is only validated for the red-green forms, so a tritan number is
    # indicative rather than decisive.
    #
    # Swept over severity, not read at the endpoint. Dichromacy is not the worst
    # case: measured over 240000 pairs of hues this file would accept as series
    # slots, 0.87% clear CVD_TARGET at dichromacy and miss it at some lower
    # severity. See MACHADO.
    worst_cvd, worst_cvd_at = float("inf"), None
    for i, j in pairs:
        for kind in ("protan", "deutan"):
            views = [(delta_e(simulate(lin[i], kind), simulate(lin[j], kind)),
                      1.0)]
            views += [(delta_e(simulate_anomalous(lin[i], kind, s),
                               simulate_anomalous(lin[j], kind, s)), s)
                      for s in ANOMALOUS_SEVERITIES]
            d, at = min(views)
            if d < worst_cvd:
                worst_cvd, worst_cvd_at = d, (colors[i], colors[j], kind, at)
    worst_tri = min((delta_e(simulate(lin[i], "tritan"), simulate(lin[j], "tritan"))
                     for i, j in pairs), default=float("nan"))
    if worst_cvd_at:
        a, b, kind, at = worst_cvd_at
        good = worst_cvd >= CVD_TARGET
        rows.append((f"CVD separation ({label})", good,
                     f"worst {a} vs {b} dE {worst_cvd:.1f} ({kind} at severity "
                     f"{at:.1f}) - tritan {worst_tri:.1f}"
                     + ("" if good else "  [FIX] needs direct labels/gaps/texture, or re-step")))

    worst_n, worst_n_at = float("inf"), None
    for i, j in pairs:
        d = delta_e(lin[i], lin[j])
        if d < worst_n:
            worst_n, worst_n_at = d, (colors[i], colors[j])
    if worst_n_at:
        a, b = worst_n_at
        good = worst_n >= NORMAL_FLOOR
        rows.append((f"Normal-vision floor ({label})", good,
                     f"worst {a} vs {b} dE {worst_n:.1f}"
                     + ("" if good else
                        "  [FIX] move one of the pair, or re-step the ramp"
                        f"  [WHY] below {NORMAL_FLOOR}, hard to tell apart in "
                        "full color")))

    # Advisory, not a gate: a sub-3:1 hue is legal, it just obligates a visible
    # direct label. Reporting it as FAIL while the run still passes reads as a
    # contradiction, so it carries its own status.
    low = [(c, round(contrast(c, surface), 2)) for c in colors if contrast(c, surface) < CONTRAST_MIN]
    rows.append(("Contrast vs surface", "warn" if low else True,
                 f"all >= {CONTRAST_MIN}:1" if not low
                 else f"under {CONTRAST_MIN}:1, each needs a visible direct label: {low}"))

    ok = all(r[1] is True for r in rows if r[1] != "warn")
    return ok, rows

def cmap_kind(samples: Sequence[str]) -> str:
    """Classify hex samples as `qualitative`, `sequential`, `diverging`,
    `cyclic` or `misc`.

    `misc` is the failure: the lightness reverses, or its span is flat, or its
    halves are monotone and its ends match neither cyclic nor diverging. A
    colormap in that state encodes nothing the reader can order.

    Fewer than `CMAP_QUALITATIVE_N = 40` samples is read as a set of category
    colours rather than a ramp, and gated on separation instead.

    Args:
        samples: Hex strings sampled along the colormap, in order.

    Returns:
        One of `"qualitative"`, `"sequential"`, `"diverging"`, `"cyclic"` or
        `"misc"`.
    """
    if len(samples) < CMAP_QUALITATIVE_N:
        return "qualitative"

    ls = [linear_to_oklab(hex_to_linear(h))[0] for h in samples]

    if max(ls) - min(ls) < CMAP_SPAN_MIN:
        return "misc"

    if _back_travel(ls) < CMAP_BACKTRAVEL_MAX:
        return "sequential"

    half = len(ls) // 2
    if (_back_travel(ls[:half + 1]) < CMAP_BACKTRAVEL_MAX
            and _back_travel(ls[half:]) < CMAP_BACKTRAVEL_MAX):
        wrap = delta_e(hex_to_linear(samples[0]), hex_to_linear(samples[-1]))
        return "cyclic" if wrap < CMAP_WRAP_DE_MAX else "diverging"

    return "misc"

def cmap_kind_rgb(samples: Sequence[tuple[float, float, float]]) -> str:
    """`cmap_kind` on float sRGB. See `cmap_back_travel_rgb` for why."""
    if len(samples) < CMAP_QUALITATIVE_N:
        return "qualitative"
    ls = [_lightness_rgb(s) for s in samples]
    if max(ls) - min(ls) < CMAP_SPAN_MIN:
        return "misc"
    if _back_travel(ls) < CMAP_BACKTRAVEL_MAX:
        return "sequential"
    half = len(ls) // 2
    if (_back_travel(ls[:half + 1]) < CMAP_BACKTRAVEL_MAX
            and _back_travel(ls[half:]) < CMAP_BACKTRAVEL_MAX):
        first = tuple(_srgb_to_linear(float(c)) for c in samples[0])
        last = tuple(_srgb_to_linear(float(c)) for c in samples[-1])
        wrap = delta_e(first, last)
        return "cyclic" if wrap < CMAP_WRAP_DE_MAX else "diverging"
    return "misc"

def cmap_back_travel(samples: Sequence[str]) -> float:
    """How much of a ramp's lightness runs backwards, as a fraction of its span.

    0.0 is monotone. `CMAP_BACKTRAVEL_MAX = 0.02` is where a ramp stops
    counting as ordered, because lightness that reverses makes two different
    values render at the same lightness.

    Args:
        samples: Hex strings sampled along the ramp, in ramp order.

    Returns:
        Backward lightness travel as a fraction of the ramp's span. 0.0 is
        monotone.
    """
    return _back_travel([linear_to_oklab(hex_to_linear(h))[0] for h in samples])

def cmap_back_travel_rgb(samples: Sequence[tuple[float, float, float]]) -> float:
    """`cmap_back_travel` on float sRGB, without the 8-bit round trip.

    The hex API rounds every channel to 1/255 before lightness is computed. On
    a smooth ramp those roundings are oscillations of about 0.001 OKLab that
    accumulate into the measure: `winter` reads 0.0343 through hex against
    0.0139 in float, which straddles the 0.02 floor and made a sequential map
    classify `misc`. Maps that genuinely reverse are unaffected, because their
    reversals are orders of magnitude larger than the rounding.

    Args:
        samples: `(r, g, b)` floats in 0..1, in ramp order.

    Returns:
        Backward lightness travel as a fraction of the ramp's span.
    """
    return _back_travel([_lightness_rgb(s) for s in samples])

def contrast(hex_a: str, hex_b: str) -> float:
    """WCAG contrast ratio between two hex colours, from 1.0 to 21.0.

    The floors it is compared against: 4.5 for text, 3.0 for a hue against the
    surface it sits on.

    Args:
        hex_a: A `#rrggbb` string.
        hex_b: The colour to measure it against.

    Returns:
        The ratio, 1.0 (identical) to 21.0 (black on white).
    """
    la, lb = relative_luminance(hex_to_linear(hex_a)), relative_luminance(hex_to_linear(hex_b))
    hi, lo = max(la, lb), min(la, lb)
    return (hi + 0.05) / (lo + 0.05)

def delta_e(rgb_a: Sequence[float], rgb_b: Sequence[float]) -> float:
    """CAM02-UCS colour difference between two linear-light colours.

    Euclidean distance in CAM02-UCS, which is the space's intended use: Luo,
    Cui & Li (2006) fitted it so that this distance predicts perceived
    difference, so the number carries a unit somebody measured. `CVD_TARGET`
    and `NORMAL_FLOOR` are quoted in it.

    Not a CIELAB dE*ab and not a CIEDE2000. Over the gamut this file gates as
    series slots, one CAM02-UCS unit is a median 1.99 CIELAB dE*ab, but the
    ratio runs 1.72-2.24 across the interquartile range, so the two are not
    interconvertible at a fixed rate and a threshold quoted in one does not
    transfer to the other.

    Before 0.8.0 this returned OKLab distance x100. See the CIECAM02 section
    above for why that number could not support a threshold.

    Args:
        rgb_a: Linear-light `(r, g, b)`.
        rgb_b: The colour to measure it against.

    Returns:
        CAM02-UCS euclidean distance.
    """
    a, b = linear_to_cam02ucs(rgb_a), linear_to_cam02ucs(rgb_b)
    return math.sqrt(sum((x - y) ** 2 for x, y in zip(a, b)))

def simulate(rgb: Sequence[float], kind: str) -> tuple[float, float, float]:
    """Linear-light RGB as a `"protan"`, `"deutan"` or `"tritan"` viewer sees it.

    Vienot, Brettel & Mollon (1999), applied on linear light. Protan and deutan
    are what the gates decide on; the tritan matrix is validated only for the
    red-green forms, so its distances are printed and never gated.

    Args:
        rgb: Linear-light `(r, g, b)`, each channel in 0..1.
        kind: `"protan"`, `"deutan"` or `"tritan"`.

    Returns:
        Linear-light `(r, g, b)` as that viewer sees it.
    """
    m = CVD[kind]
    r, g, b = (max(0.0, min(1.0, sum(m[i][j] * rgb[j] for j in range(3))))
               for i in range(3))
    return r, g, b

def simulate_anomalous(rgb: Sequence[float], kind: str,
                       severity: float) -> tuple[float, float, float]:
    """Linear-light RGB as an anomalous trichromat of this severity sees it.

    `kind` is `"protan"` or `"deutan"`. `severity` runs 0.0 (normal vision) to
    1.0 (dichromacy) and is read at the nearest tenth, which is where Machado,
    Oliveira & Fernandes publish the table. No interpolation between two
    published matrices, because that is a modelling claim the paper does not
    make and this file would then be asserting.

    `simulate` remains the dichromacy model and the anchor for every number the
    style guide quotes. This is the range between the two ends, which is where
    most colour vision deficiency actually sits.

    Args:
        rgb: Linear-light `(r, g, b)`, each channel in 0..1.
        kind: `"protan"` or `"deutan"`.
        severity: 0.0 (normal vision) to 1.0 (dichromacy), read at the
            nearest tenth.

    Returns:
        Linear-light `(r, g, b)` as that viewer sees it.
    """
    if kind not in MACHADO:
        raise ValueError(f"severity is modelled for protan and deutan only, "
                         f"not {kind!r} - see the note above MACHADO")
    if not 0.0 <= severity <= 1.0:
        raise ValueError(f"severity runs 0.0 to 1.0, got {severity!r}")
    tenths = int(round(severity * 10))
    if tenths == 0:
        r, g, b = (max(0.0, min(1.0, c)) for c in rgb)
        return r, g, b
    m = MACHADO[kind][tenths]
    r, g, b = (max(0.0, min(1.0, sum(m[i][j] * rgb[j] for j in range(3))))
               for i in range(3))
    return r, g, b

def hex_to_linear(h: str) -> tuple[float, float, float]:
    """A `#rrggbb` string as linear-light RGB, each channel in 0..1.

    Linear light, not the 0..255 the hex digits carry: every distance and
    luminance below is defined on it, and averaging or mixing gamma-encoded
    values is the usual source of a wrong answer that looks plausible.

    Args:
        h: A `#rrggbb` string. The leading `#` is optional.

    Returns:
        `(r, g, b)`, each channel linear-light in 0..1.
    """
    h = h.lstrip("#")
    if len(h) != 6:
        raise ValueError(f"expected 6-digit hex, got {h!r}")
    r, g, b = (_srgb_to_linear(int(h[i:i + 2], 16) / 255) for i in (0, 2, 4))
    return r, g, b

def oklab_distance(rgb_a: Sequence[float], rgb_b: Sequence[float]) -> float:
    """OKLab distance between two linear-light colours, x100.

    What `delta_e` measured before 0.8.0, kept because the lightness rows still
    reason in OKLab and because a caller comparing against a number this project
    published earlier needs the old scale to do it.

    It is not a colour difference in any calibrated sense: OKLab was fitted for
    hue uniformity, not for discrimination, so distances in it have no published
    referent. Gate on `delta_e`.

    Args:
        rgb_a: Linear-light `(r, g, b)`.
        rgb_b: The colour to measure it against.

    Returns:
        OKLab euclidean distance, x100.
    """
    a, b = linear_to_oklab(rgb_a), linear_to_oklab(rgb_b)
    return 100 * math.sqrt(sum((x - y) ** 2 for x, y in zip(a, b)))

def linear_to_oklab(rgb: Sequence[float]) -> tuple[float, float, float]:
    """Linear-light RGB as OKLab `(L, a, b)`.

    OKLab rather than CIELAB because its lightness tracks perceived lightness
    across hues, which is what every gate here asks about. `l, m, s` below are
    the cone responses the published matrix names, not a lint slip.

    Args:
        rgb: Linear-light `(r, g, b)`, each channel in 0..1.

    Returns:
        `(L, a, b)` in OKLab. `L` is 0..1.
    """
    r, g, b = rgb
    l = 0.4122214708 * r + 0.5363325363 * g + 0.0514459929 * b
    m = 0.2119034982 * r + 0.6806995451 * g + 0.1073969566 * b
    s = 0.0883024619 * r + 0.2817188376 * g + 0.6299787005 * b
    l_, m_, s_ = (math.copysign(abs(v) ** (1 / 3), v) for v in (l, m, s))
    return (
        0.2104542553 * l_ + 0.7936177850 * m_ - 0.0040720468 * s_,
        1.9779984951 * l_ - 2.4285922050 * m_ + 0.4505937099 * s_,
        0.0259040371 * l_ + 0.7827717662 * m_ - 0.8086757660 * s_,
    )

def linear_to_cam02ucs(rgb: Sequence[float]) -> tuple[float, float, float]:
    """Linear-light RGB as CAM02-UCS `(J', a', b')`.

    The space `delta_e` measures in. Euclidean distance here is a perceived
    colour difference in the units Luo, Cui & Li (2006) fitted, which is what
    lets the floors in this file cite a measurement instead of a preference.

    Args:
        rgb: Linear-light `(r, g, b)`, each channel in 0..1.

    Returns:
        `(J', a', b')` in CAM02-UCS. `J'` runs 0..100 for in-gamut colours.
    """
    xyz = tuple(100.0 * v for v in _mul3(_M_XYZ, rgb))
    rgb_c = tuple(dr * v for dr, v in zip(_D_RGB, _mul3(_M_CAT02, xyz)))
    return _cam02ucs_from_post_adapted(
        _post_adapt(_mul3(_M_HPE, _mul3(_M_CAT02_INV, rgb_c)), _F_L))

def relative_luminance(rgb: Sequence[float]) -> float:
    """WCAG relative luminance of linear-light RGB.

    The WCAG coefficients, and deliberately not OKLab's `L`: the contrast
    ratios this project cites are defined against this number, so computing
    them from a perceptual lightness would report figures no standard backs.

    Args:
        rgb: Linear-light `(r, g, b)`, each channel in 0..1.

    Returns:
        Relative luminance in 0..1, by the WCAG coefficients.
    """
    r, g, b = rgb
    return 0.2126 * r + 0.7152 * g + 0.0722 * b

def suggest(rows: Sequence[tuple[str, bool | str, str]],
            ) -> list[tuple[str, list[Remedy]]]:
    """Remedies for the rows of an `audit` that are not passing.

    Takes `rows` rather than the figure: what is on offer depends on which
    gates fired, and nothing here needs to look at the figure again. Returns
    `[(gate_name, [Remedy, ...]), ...]` in the order the gates reported, and
    skips gates with nothing to offer rather than padding them with a
    restatement of the failure.

    Args:
        rows: `(label, status, detail)` triples, as `audit` or `check`
            returned them. Passing rows are ignored.

    Returns:
        `[(gate_name, [Remedy, ...]), ...]`, in the order the gates reported.
        Empty when nothing fired that this file has an answer for.
    """
    marked = [name for name, status, _ in rows if status is not True]
    out = []
    for name in marked:
        found = [r for r in REMEDIES if r.gate == name]
        if found:
            out.append((name, found))
    return out