zenpixels-convert 0.2.12

//! Embedded CC0-licensed ICC profiles for common wide-gamut color spaces.
//!
//! All profiles are from [Compact-ICC-Profiles](https://github.com/saucecontrol/Compact-ICC-Profiles)
//! by Clinton Ingram, released under the [CC0 1.0 Universal](https://creativecommons.org/publicdomain/zero/1.0/)
//! public domain dedication. They are embedded at compile time via `include_bytes!()`.
//!
//! # Available profiles
//!
//! | Constant | Color space | Format | Size | TRC form |
//! |----------|-------------|--------|------|----------|
//! | [`DISPLAY_P3_V4`] | Display P3 | ICC v4 | 480 bytes | paraType-3 sRGB |
//! | [`DISPLAY_P3_V2`] | Display P3 | ICC v2 | 736 bytes | paraType-3 sRGB |
//! | [`ADOBE_RGB`] | Adobe RGB (1998) | ICC v2 | 374 bytes | **curv count=1** (pure gamma) |
//! | [`REC2020_V4`] | Rec. 2020 | ICC v4 | 480 bytes | paraType-3 BT.709 |
//!
//! # Notes on choices
//!
//! ## Adobe RGB — pure gamma, not paraType-3
//!
//! We deliberately bundle the saucecontrol **v2** variant (`curv count=1`,
//! gamma 2.19921875, no linear toe) rather than their **v4** variant
//! (`paraType funcType=3` with linear toe). Rationale: surveying the in-the-wild
//! corpus, ~85% of Adobe RGB ICC profiles encode the TRC as pure gamma
//! (Adobe CS4 distribution, Windows `ClayRGB1998` / `AdobeRGB1998`, macOS
//! `AdobeRGB1998`, Linux `AdobeRGB1998`/`compatibleWithAdobeRGB1998`, Nikon,
//! and per-camera profiles). The Adobe RGB 1998 encoding spec (§4.3.4.2)
//! itself defines pure gamma with no toe. Bundling the pure-gamma form
//! matches both the spec and the majority of the ecosystem, and means the
//! embedded profile round-trips byte-exact against moxcms's `new_adobe_rgb()`
//! canonical reference.
//!
//! ## ProPhoto — not bundled
//!
//! Unlike Adobe RGB, real-world ProPhoto / ROMM ICC profiles are fragmented:
//! ~50% pure gamma 1.8, ~30% `paraType funcType=3` with the ISO 22028-2 toe
//! (`c=1/16, d=1/32`), some with a non-standard Apple `d=1/512`, one
//! `ProPhotoLin.icm` with a linear TRC despite the name, and two ISO 22028-2
//! v4 profiles that are mAB/mBA LUTs (no rTRC at all). Picking any single
//! "canonical" ProPhoto profile to embed would misrepresent the other
//! variants. Instead we leave ProPhoto un-accelerated: callers handing us a
//! ProPhoto ICC profile fall through to full CMS so the exact encoded curve
//! is honored.
//!
//! ## Display P3 / Rec. 2020 — kept as-is for embedding output
//!
//! The DisplayP3Compat and Rec2020Compat profiles use saucecontrol's
//! D50-sum-exact matrix rebalancing (truncating negative `rXYZ.Z` / `bXYZ.Z`
//! to clean s15.16 values, compensating via `chad` row 3). They diverge
//! ~500-900 u16 from canonical matrix math for the same reason — but they're
//! intended as **compact encoder-friendly output profiles**, not as
//! fast-path identification targets. They're bundled here for embedding in
//! encoded JPEG/PNG/WebP/etc. The ICC identification table in
//! `zenpixels/src/icc` deliberately excludes them from the safe-for-fast-path
//! set (see `scripts/icc-gen/src/main.rs`).
//!
//! # Lookup by primaries
//!
//! Use [`icc_profile_for_primaries`] to get the recommended ICC profile bytes
//! for a [`ColorPrimaries`] value. Returns `None` for `Bt709` (sRGB is assumed
//! by default and rarely needs an explicit ICC profile), `ProPhoto` (not
//! bundled; see above), and `Unknown`.
//!
//! # Precision warnings
//!
//! Rec. 2020 has a very wide gamut. Using 8-bit precision with Rec. 2020
//! will cause visible banding in gradients. Use 16-bit or f32 precision.

use alloc::borrow::Cow;

use crate::{Cicp, ColorPrimaries, TransferFunction};

// ---------------------------------------------------------------------------
// Embedded ICC profiles (CC0 license from Compact-ICC-Profiles)
// https://github.com/saucecontrol/Compact-ICC-Profiles
// ---------------------------------------------------------------------------

/// Display P3 Compatible ICC profile, v4 format (480 bytes).
///
/// Recommended for modern software. ICC v4 profiles are more compact
/// and have better-defined semantics than v2.
///
/// Source: <https://github.com/saucecontrol/Compact-ICC-Profiles> (CC0)
pub const DISPLAY_P3_V4: &[u8] = include_bytes!("profiles/DisplayP3Compat-v4.icc");

/// Display P3 Compatible ICC profile, v2 format (736 bytes).
///
/// Use this for compatibility with older software that doesn't support ICC v4.
/// The "magic" variant includes workarounds for buggy v2 parsers.
///
/// Source: <https://github.com/saucecontrol/Compact-ICC-Profiles> (CC0)
pub const DISPLAY_P3_V2: &[u8] = include_bytes!("profiles/DisplayP3Compat-v2-magic.icc");

/// Adobe RGB (1998) Compatible ICC profile, v2 format (374 bytes, **pure gamma**).
///
/// Encodes the rTRC/gTRC/bTRC as `curv count=1` with gamma 2.19921875 (= 563/256),
/// matching the Adobe RGB 1998 spec and ~85% of real-world Adobe RGB ICC
/// profiles. See the module-level docs for the rationale on picking pure gamma
/// over the paraType-3 toe form.
///
/// Source: <https://github.com/saucecontrol/Compact-ICC-Profiles> (CC0)
pub const ADOBE_RGB: &[u8] = include_bytes!("profiles/AdobeCompat-v2.icc");

/// Deprecated alias for [`ADOBE_RGB`]. The v4 paraType-3 variant was replaced
/// with the v2 pure-gamma variant to match the spec and ~85% of the ecosystem.
#[deprecated(
    since = "0.2.4",
    note = "renamed to ADOBE_RGB (now v2 pure-gamma form)"
)]
pub const ADOBE_RGB_V4: &[u8] = ADOBE_RGB;

/// Deprecated: ProPhoto is not bundled due to TRC fragmentation.
/// See module-level docs for details.
#[deprecated(
    since = "0.2.4",
    note = "ProPhoto removed — TRC too fragmented to pick a canonical form"
)]
pub const PROPHOTO_V4: &[u8] = &[];

/// Rec. 2020 Compatible ICC profile, v4 format (480 bytes).
///
/// Rec. 2020 has a very wide gamut (~75% of visible colors).
/// **Use 16-bit or f32 precision** to avoid banding.
///
/// Source: <https://github.com/saucecontrol/Compact-ICC-Profiles> (CC0)
pub const REC2020_V4: &[u8] = include_bytes!("profiles/Rec2020Compat-v4.icc");

// ProPhoto / ROMM RGB is intentionally not bundled — see the module-level
// "ProPhoto — not bundled" note for the fragmentation analysis.

/// Get the recommended ICC profile for a set of color primaries.
///
/// Returns the recommended ICC profile bytes for the given primaries, or
/// `None` when no embedded profile is available. Returns `None` for:
/// - [`ColorPrimaries::Bt709`] — sRGB is the assumed default and rarely
///   needs an explicit ICC profile
/// - [`ColorPrimaries::Unknown`]
///
/// # Transfer-blind — prefer [`synthesize_icc_for_cicp`] when lowering a CICP
///
/// This function looks at primaries **only**, so the profile it returns always
/// carries the bundled SDR TRC for that gamut. Handing it a gamut whose source
/// is HDR — e.g. BT.2020 pixels that are actually **PQ** or **HLG** — gets back
/// the SDR-TRC Rec.2020 profile, which *mis-tags* the transfer. When you have a
/// full [`Cicp`] (primaries **and** transfer), call [`synthesize_icc_for_cicp`]
/// instead: it matches the TRC, can generate HDR profiles via the `cms-moxcms`
/// feature, and never substitutes a contradicting curve.
///
/// # Examples
///
/// ```
/// # #![allow(deprecated)] // demonstrating the (deprecated) primaries-only lookup
/// use zenpixels_convert::icc_profiles::icc_profile_for_primaries;
/// use zenpixels_convert::ColorPrimaries;
///
/// let p3_icc = icc_profile_for_primaries(ColorPrimaries::DisplayP3);
/// assert!(p3_icc.is_some());
/// assert_eq!(p3_icc.unwrap().len(), 480);
///
/// // sRGB returns None (assumed default)
/// assert!(icc_profile_for_primaries(ColorPrimaries::Bt709).is_none());
/// ```
#[deprecated(
    since = "0.2.12",
    note = "transfer-blind (can mis-tag an HDR gamut with an SDR TRC); use \
            synthesize_icc_for_cicp for transfer-aware synthesis, or embed a \
            bundled const (DISPLAY_P3_V4 / REC2020_V4 / ADOBE_RGB) directly"
)]
#[inline]
pub const fn icc_profile_for_primaries(primaries: ColorPrimaries) -> Option<&'static [u8]> {
    match primaries {
        ColorPrimaries::DisplayP3 => Some(DISPLAY_P3_V4),
        ColorPrimaries::Bt2020 => Some(REC2020_V4),
        ColorPrimaries::AdobeRgb => Some(ADOBE_RGB),
        // BT.709/sRGB is the assumed default; no explicit ICC profile needed.
        // ProPhoto is deliberately not bundled — see module-level notes.
        ColorPrimaries::Bt709 | ColorPrimaries::Unknown | _ => None,
    }
}

/// Get the Display P3 ICC profile, choosing v4 or v2 format.
///
/// Returns v4 by default, or v2 if `prefer_v2` is true (for compatibility
/// with older software).
#[inline]
pub const fn display_p3_icc(prefer_v2: bool) -> &'static [u8] {
    if prefer_v2 {
        DISPLAY_P3_V2
    } else {
        DISPLAY_P3_V4
    }
}

/// Get a bundled ICC profile matching both a primaries set and a transfer
/// function.
///
/// This is a finer-grained accessor than [`icc_profile_for_primaries`]: it
/// matches against the TRC encoded in each bundled profile, so a caller
/// that asks for `(Bt2020, Bt709)` gets the same Rec. 2020 profile, but a
/// caller asking for `(Bt2020, Pq)` gets `None` (no PQ profile bundled).
///
/// # Currently bundled combinations
///
/// | Primaries | Transfer | Returned profile |
/// |-----------|----------|------------------|
/// | [`Bt709`](ColorPrimaries::Bt709) | [`Srgb`](TransferFunction::Srgb) | `None` — sRGB is the assumed default |
/// | [`DisplayP3`](ColorPrimaries::DisplayP3) | [`Srgb`](TransferFunction::Srgb) | [`DISPLAY_P3_V4`] |
/// | [`Bt2020`](ColorPrimaries::Bt2020) | [`Bt709`](TransferFunction::Bt709) | [`REC2020_V4`] |
/// | [`AdobeRgb`](ColorPrimaries::AdobeRgb) | [`Gamma22`](TransferFunction::Gamma22) | [`ADOBE_RGB`] |
///
/// # Not bundled (returns `None`)
///
/// - HDR transfers ([`Pq`](TransferFunction::Pq), [`Hlg`](TransferFunction::Hlg))
///   on any primaries. Ultra HDR / HDR10 / HLG broadcast workflows that need
///   a PQ- or HLG-tagged profile should either generate one via a CMS crate
///   (e.g., `moxcms::ColorProfile::new_bt2020_pq().encode()`) or signal color
///   via CICP instead of ICC.
/// - [`Linear`](TransferFunction::Linear) on any primaries. Linear-light
///   working spaces are typically expressed with CICP transfer code 8
///   rather than an ICC profile.
/// - Adobe RGB with any transfer other than `Gamma22`.
/// - BT.2020 primaries with sRGB or BT.709 `Gamma22` / `Linear` transfers
///   other than the single bundled BT.709 paraType-3 form.
///
/// When this function returns `None`, call [`icc_profile_for_primaries`] as
/// a fallback if you can tolerate the profile's encoded TRC differing from
/// your requested transfer (e.g., accept the bundled BT.709 TRC for an
/// SDR BT.2020 export regardless of whether the caller asked for `Srgb` or
/// `Bt709`).
#[inline]
pub(crate) const fn bundled_icc_profile(
    primaries: ColorPrimaries,
    transfer: TransferFunction,
) -> Option<&'static [u8]> {
    match (primaries, transfer) {
        // Display P3 + sRGB: saucecontrol's DisplayP3Compat uses paraType-3
        // sRGB TRC, so both the sRGB and BT.709 transfer callers (which differ
        // only in the near-black linear segment) get the same profile.
        (ColorPrimaries::DisplayP3, TransferFunction::Srgb)
        | (ColorPrimaries::DisplayP3, TransferFunction::Bt709) => Some(DISPLAY_P3_V4),
        // BT.2020 + BT.709 TRC: saucecontrol's Rec2020Compat uses paraType-3
        // BT.709 TRC. Accept the sRGB request alias (same curve shape
        // outside the near-black toe), as this matches what ultrahdr-style
        // SDR BT.2020 base images need.
        (ColorPrimaries::Bt2020, TransferFunction::Bt709)
        | (ColorPrimaries::Bt2020, TransferFunction::Srgb) => Some(REC2020_V4),
        // Adobe RGB + Gamma22: bundled v2 pure-gamma variant.
        (ColorPrimaries::AdobeRgb, TransferFunction::Gamma22) => Some(ADOBE_RGB),
        // Everything else: no bundled profile with that exact TRC.
        _ => None,
    }
}

/// Outcome of [`synthesize_icc_for_cicp`] — what ICC profile (if any) to embed for a
/// CICP color description, and *why* there are no bytes when there aren't.
///
/// The point is to make lowering an `IccDisposition::SynthesizeFrom` explicit:
/// an implementer can tell apart "got bytes", "no profile needed", "we'd need a
/// CMS for this one", and "even the CMS couldn't" — instead of an ambiguous
/// `Option` that conflates them.
#[derive(Clone, Debug, PartialEq, Eq)]
#[non_exhaustive]
pub enum SynthesizedIcc {
    /// A profile is available — embed these bytes. `Cow::Borrowed` is a bundled
    /// `&'static` profile (no allocation, `no_std`); `Cow::Owned` was generated by
    /// the `cms-moxcms` CMS.
    Profile(Cow<'static, [u8]>),
    /// No ICC is needed: the CICP is the universally-assumed sRGB / BT.709 default,
    /// so omitting a profile loses nothing.
    ///
    /// In the encode pipeline this *shouldn't* occur — `resolve_color_emit` never
    /// asks to synthesize for sRGB (its `synth_worthwhile` test excludes it) — but
    /// it's surfaced explicitly rather than masquerading as a missing profile.
    NotNeeded,
    /// No bundled `&'static` profile matches this CICP, and producing one needs a
    /// CMS — but the `cms-moxcms` feature is **off** in this build. Enable it to
    /// synthesize a profile, or carry the color via the CICP carrier alone.
    ///
    /// A non-CMS build can't tell whether a CMS *would* succeed; a `cms-moxcms`
    /// build answers that with [`Profile`](Self::Profile) or
    /// [`CmsUnsupported`](Self::CmsUnsupported).
    NeedsCms,
    /// The `cms-moxcms` CMS is enabled but could not generate a profile for this
    /// CICP — e.g. unrecognized primaries/transfer code points. Genuinely
    /// unavailable; carry the color via the CICP carrier instead.
    CmsUnsupported,
}

/// Resolve an ICC profile for a full [`Cicp`] color description (primaries **and**
/// transfer), returning a [`SynthesizedIcc`] that says exactly what happened.
///
/// This is the transfer-aware lowering for `IccDisposition::SynthesizeFrom`. Unlike
/// [`icc_profile_for_primaries`] (primaries-only — which would hand a BT.2020-**PQ**
/// source the SDR-TRC Rec.2020 profile), this never mis-tags: an HDR transfer with
/// no bundled match returns [`NeedsCms`](SynthesizedIcc::NeedsCms) /
/// [`CmsUnsupported`](SynthesizedIcc::CmsUnsupported), so you embed a CMS-generated
/// profile or none — never a profile whose TRC contradicts the pixels.
///
/// Coverage:
/// - **Bundled** (`no_std`, no CMS): the bundled `&'static` set ([`DISPLAY_P3_V4`],
///   [`REC2020_V4`]) — Display-P3 (sRGB TRC) and BT.2020 (BT.709 TRC) are reachable
///   via CICP; Adobe RGB has no CICP code point.
/// - **`cms-moxcms`**: generated for any CICP moxcms recognizes, including PQ/HLG.
/// - **sRGB / BT.709 default** → [`NotNeeded`](SynthesizedIcc::NotNeeded).
///
/// # Examples
/// ```
/// use zenpixels_convert::icc_profiles::{synthesize_icc_for_cicp, SynthesizedIcc};
/// use zenpixels_convert::Cicp;
///
/// // Display-P3 → a bundled profile.
/// assert!(matches!(synthesize_icc_for_cicp(Cicp::DISPLAY_P3), SynthesizedIcc::Profile(_)));
/// // sRGB → no profile needed.
/// assert_eq!(synthesize_icc_for_cicp(Cicp::SRGB), SynthesizedIcc::NotNeeded);
/// ```
pub fn synthesize_icc_for_cicp(cicp: Cicp) -> SynthesizedIcc {
    // Genuine sRGB / BT.709 / unspecified default — no embedded ICC needed.
    //
    // This is gated on the **raw** H.273 code points, NOT the enum mapping:
    // `color_primaries_enum` folds every gamut zenpixels doesn't model (BT.601 = 6,
    // SMPTE240 = 7, BT.470M/BG = 4/5, EBU3213 = 22, …) into `Unknown`, so an
    // enum-based check would treat those real, non-sRGB gamuts as "sRGB default"
    // and drop their colour — and worse, skip the CMS path below that can actually
    // synthesize many of them. Only colour-primaries 1 (BT.709) / 2 (unspecified)
    // with transfer 1 (BT.709) / 2 (unspecified) / 13 (sRGB) is the assumed default.
    if matches!(cicp.color_primaries, 1 | 2) && matches!(cicp.transfer_characteristics, 1 | 2 | 13)
    {
        return SynthesizedIcc::NotNeeded;
    }

    let primaries = cicp.color_primaries_enum();
    let transfer = cicp.transfer_function_enum();

    // A bundled, transfer-matched profile (const, no allocation).
    if let Some(bytes) = bundled_icc_profile(primaries, transfer) {
        return SynthesizedIcc::Profile(Cow::Borrowed(bytes));
    }

    // No bundled match → a CMS is required to generate one.
    #[cfg(feature = "cms-moxcms")]
    {
        match crate::cms_moxcms::icc_bytes_for_cicp(&cicp) {
            Some(bytes) => SynthesizedIcc::Profile(Cow::Owned(bytes)),
            None => SynthesizedIcc::CmsUnsupported,
        }
    }
    #[cfg(not(feature = "cms-moxcms"))]
    {
        SynthesizedIcc::NeedsCms
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn v4_profiles_valid_structure() {
        let profiles: &[(&[u8], &str)] = &[
            (DISPLAY_P3_V4, "Display P3 v4"),
            (REC2020_V4, "Rec. 2020 v4"),
        ];

        for (profile, name) in profiles {
            assert_eq!(profile.len(), 480, "{name}: expected 480 bytes");
            assert_eq!(
                &profile[36..40],
                b"acsp",
                "{name}: missing ICC 'acsp' signature at offset 36"
            );
            assert_eq!(
                &profile[12..16],
                b"mntr",
                "{name}: expected 'mntr' (monitor) profile class at offset 12"
            );
        }
    }

    #[test]
    fn adobe_rgb_profile_valid_structure() {
        assert_eq!(
            ADOBE_RGB.len(),
            374,
            "Adobe RGB: expected 374 bytes (ICC v2)"
        );
        assert_eq!(
            &ADOBE_RGB[36..40],
            b"acsp",
            "Adobe RGB: missing ICC 'acsp' signature at offset 36"
        );
        assert_eq!(
            &ADOBE_RGB[12..16],
            b"mntr",
            "Adobe RGB: expected 'mntr' (monitor) profile class at offset 12"
        );
        // TRC is `curv count=1` (pure gamma) — offset at rTRC tag, 14 bytes.
        // `curv` signature (4) + reserved (4) + count=1 (4) + u16 gamma (2) = 14.
        // This is the marker distinguishing the v2 pure-gamma variant from the
        // v4 paraType-3 variant (32+ bytes).
        let tag_count = u32::from_be_bytes([
            ADOBE_RGB[128],
            ADOBE_RGB[129],
            ADOBE_RGB[130],
            ADOBE_RGB[131],
        ]) as usize;
        let mut found_pure_gamma_trc = false;
        for i in 0..tag_count {
            let b = 132 + i * 12;
            if &ADOBE_RGB[b..b + 4] == b"rTRC" {
                let off = u32::from_be_bytes([
                    ADOBE_RGB[b + 4],
                    ADOBE_RGB[b + 5],
                    ADOBE_RGB[b + 6],
                    ADOBE_RGB[b + 7],
                ]) as usize;
                assert_eq!(
                    &ADOBE_RGB[off..off + 4],
                    b"curv",
                    "Adobe RGB: rTRC must be curveType (pure gamma)"
                );
                let count = u32::from_be_bytes([
                    ADOBE_RGB[off + 8],
                    ADOBE_RGB[off + 9],
                    ADOBE_RGB[off + 10],
                    ADOBE_RGB[off + 11],
                ]);
                assert_eq!(
                    count, 1,
                    "Adobe RGB: curveType count must be 1 (pure gamma, no toe)"
                );
                found_pure_gamma_trc = true;
                break;
            }
        }
        assert!(found_pure_gamma_trc, "Adobe RGB: rTRC tag not found");
    }

    #[test]
    fn v2_profile_valid_structure() {
        assert_eq!(
            DISPLAY_P3_V2.len(),
            736,
            "Display P3 v2: expected 736 bytes"
        );
        assert_eq!(
            &DISPLAY_P3_V2[36..40],
            b"acsp",
            "Display P3 v2: missing ICC 'acsp' signature at offset 36"
        );
        assert_eq!(
            &DISPLAY_P3_V2[12..16],
            b"mntr",
            "Display P3 v2: expected 'mntr' (monitor) profile class at offset 12"
        );
    }

    #[test]
    fn display_p3_icc_selector() {
        assert_eq!(display_p3_icc(false).len(), 480); // v4
        assert_eq!(display_p3_icc(true).len(), 736); // v2
    }

    #[test]
    #[allow(deprecated)] // exercises the deprecated primaries-only lookup
    fn icc_profile_for_primaries_mapping() {
        assert_eq!(
            icc_profile_for_primaries(ColorPrimaries::DisplayP3),
            Some(DISPLAY_P3_V4)
        );
        assert_eq!(
            icc_profile_for_primaries(ColorPrimaries::Bt2020),
            Some(REC2020_V4)
        );
        assert_eq!(
            icc_profile_for_primaries(ColorPrimaries::AdobeRgb),
            Some(ADOBE_RGB)
        );
        assert!(icc_profile_for_primaries(ColorPrimaries::Bt709).is_none());
        assert!(icc_profile_for_primaries(ColorPrimaries::Unknown).is_none());
    }

    #[test]
    fn bundled_icc_profile_hits_combinations() {
        // Display P3 + sRGB / BT.709 paraType-3 curves both map to the bundled
        // DisplayP3Compat-v4 profile.
        assert_eq!(
            bundled_icc_profile(ColorPrimaries::DisplayP3, TransferFunction::Srgb),
            Some(DISPLAY_P3_V4)
        );
        assert_eq!(
            bundled_icc_profile(ColorPrimaries::DisplayP3, TransferFunction::Bt709),
            Some(DISPLAY_P3_V4)
        );
        // Rec 2020 SDR: BT.709 TRC profile is the canonical export for SDR
        // BT.2020 base images (matches the ultrahdr 8-bit base JPEG case).
        assert_eq!(
            bundled_icc_profile(ColorPrimaries::Bt2020, TransferFunction::Bt709),
            Some(REC2020_V4)
        );
        assert_eq!(
            bundled_icc_profile(ColorPrimaries::Bt2020, TransferFunction::Srgb),
            Some(REC2020_V4)
        );
        // Adobe RGB: pure-gamma-2.2 TRC.
        assert_eq!(
            bundled_icc_profile(ColorPrimaries::AdobeRgb, TransferFunction::Gamma22),
            Some(ADOBE_RGB)
        );
    }

    #[test]
    fn bundled_icc_profile_rejects_hdr_transfers() {
        // HDR PQ / HLG profiles aren't bundled; callers should use CICP or
        // a CMS-side generator.
        assert!(bundled_icc_profile(ColorPrimaries::Bt2020, TransferFunction::Pq).is_none());
        assert!(bundled_icc_profile(ColorPrimaries::Bt2020, TransferFunction::Hlg).is_none());
        assert!(bundled_icc_profile(ColorPrimaries::DisplayP3, TransferFunction::Pq).is_none());
        assert!(bundled_icc_profile(ColorPrimaries::DisplayP3, TransferFunction::Hlg).is_none());
        // Linear likewise isn't bundled — CICP 8 is the canonical signal.
        assert!(bundled_icc_profile(ColorPrimaries::Bt2020, TransferFunction::Linear).is_none());
        assert!(bundled_icc_profile(ColorPrimaries::DisplayP3, TransferFunction::Linear).is_none());
    }

    #[test]
    fn bundled_icc_profile_rejects_mismatched_trc() {
        // We only bundle Adobe RGB with gamma 2.2 — asking for sRGB TRC on
        // Adobe RGB primaries returns None rather than lying with a mismatched
        // curve. Callers who want a fallback use icc_profile_for_primaries.
        assert!(bundled_icc_profile(ColorPrimaries::AdobeRgb, TransferFunction::Srgb).is_none());
        assert!(bundled_icc_profile(ColorPrimaries::AdobeRgb, TransferFunction::Bt709).is_none());
        // Gamma 2.2 on DisplayP3 / Bt2020 isn't bundled either.
        assert!(
            bundled_icc_profile(ColorPrimaries::DisplayP3, TransferFunction::Gamma22).is_none()
        );
        assert!(bundled_icc_profile(ColorPrimaries::Bt2020, TransferFunction::Gamma22).is_none());
    }

    #[test]
    fn bundled_icc_profile_bt709_returns_none() {
        // Same as icc_profile_for_primaries: BT.709 / sRGB is the assumed
        // default and isn't bundled.
        assert!(bundled_icc_profile(ColorPrimaries::Bt709, TransferFunction::Srgb).is_none());
        assert!(bundled_icc_profile(ColorPrimaries::Bt709, TransferFunction::Bt709).is_none());
        assert!(bundled_icc_profile(ColorPrimaries::Unknown, TransferFunction::Unknown).is_none());
    }

    #[test]
    fn synthesize_icc_for_cicp_srgb_is_not_needed() {
        // sRGB / BT.709 is the universally-assumed default — no profile to embed.
        assert_eq!(
            synthesize_icc_for_cicp(Cicp::SRGB),
            SynthesizedIcc::NotNeeded
        );
    }

    #[test]
    fn synthesize_icc_for_cicp_display_p3_is_bundled_borrowed() {
        // Display P3 (sRGB TRC) is in the bundled set — resolvable with no CMS and
        // no allocation, so it must come back as a borrowed &'static profile.
        match synthesize_icc_for_cicp(Cicp::DISPLAY_P3) {
            SynthesizedIcc::Profile(Cow::Borrowed(bytes)) => assert_eq!(bytes, DISPLAY_P3_V4),
            other => panic!("expected bundled borrowed Display P3 profile, got {other:?}"),
        }
    }

    #[test]
    fn synthesize_icc_for_cicp_hdr_pq_needs_cms_or_generates() {
        // BT.2020 PQ: no bundled profile (HDR TRC). The outcome distinguishes the
        // two builds — never a mis-tagged SDR profile.
        let bt2020_pq = Cicp::new(9, 16, 9, false); // primaries 9, transfer 16 (PQ)
        let got = synthesize_icc_for_cicp(bt2020_pq);
        #[cfg(feature = "cms-moxcms")]
        match got {
            // moxcms recognizes BT.2020 PQ → generates an owned, non-empty profile.
            SynthesizedIcc::Profile(Cow::Owned(bytes)) => assert!(!bytes.is_empty()),
            other => panic!("expected CMS-generated owned PQ profile, got {other:?}"),
        }
        #[cfg(not(feature = "cms-moxcms"))]
        // No CMS in this build → caller is told a CMS is required, not handed an
        // SDR-TRC profile that contradicts the PQ pixels.
        assert_eq!(got, SynthesizedIcc::NeedsCms);
    }

    #[test]
    fn synthesize_icc_for_cicp_reserved_transfer_is_unsupported_not_mistagged() {
        // Recognized primaries (BT.2020) but a reserved transfer code (0). moxcms
        // folds reserved codes into `Reserved` and `new_from_cicp` would silently
        // emit a TRC-less base profile — so synthesis must refuse, not mis-tag.
        let bt2020_reserved_trc = Cicp::new(9, 0, 9, false);
        let got = synthesize_icc_for_cicp(bt2020_reserved_trc);
        #[cfg(feature = "cms-moxcms")]
        assert_eq!(got, SynthesizedIcc::CmsUnsupported);
        #[cfg(not(feature = "cms-moxcms"))]
        assert_eq!(got, SynthesizedIcc::NeedsCms);
    }

    #[test]
    fn synthesize_icc_for_cicp_real_gamut_not_assumed_srgb() {
        // BT.601 primaries (code 6) + gamma-2.2 transfer (code 4): a real, non-sRGB
        // colour description that zenpixels' enum folds into `Unknown`/`Unknown`.
        // It must NOT be treated as the sRGB default — that would silently drop the
        // gamut. The `NotNeeded` gate keys on raw code points, so this falls through
        // to the CMS path (synthesizable — moxcms recognizes both codes).
        let bt601_g22 = Cicp::new(6, 4, 0, false);
        let got = synthesize_icc_for_cicp(bt601_g22);
        assert_ne!(
            got,
            SynthesizedIcc::NotNeeded,
            "a real non-sRGB gamut must never be assumed to be the sRGB default"
        );
        #[cfg(feature = "cms-moxcms")]
        assert!(matches!(got, SynthesizedIcc::Profile(_)));
        #[cfg(not(feature = "cms-moxcms"))]
        assert_eq!(got, SynthesizedIcc::NeedsCms);
    }
}