pdf-manip 1.2.0

//! PDF/A color space normalization and OutputIntent management.
//!
//! Detects device-dependent color spaces and adds sRGB OutputIntent
//! for PDF/A conformity. Provides ICC profile embedding.

// Copyright (c) 2026 Innovation Trigger B.V.
//
// PDFluent is available under two licences, at your option: the GNU AGPLv3, or
// the PDFluent Commercial Licence. See the LICENSE file in this repository --
// that file travels with the copy you received, which a URL does not.

use crate::error::{ManipError, Result};
use lopdf::{dictionary, Document, Object, ObjectId, Stream};

/// Report from color space normalization.
#[derive(Debug, Clone)]
pub struct ColorSpaceReport {
    /// Whether an OutputIntent was already present.
    pub had_output_intent: bool,
    /// Whether an OutputIntent was added.
    pub output_intent_added: bool,
    /// Device-dependent color spaces found in page resources.
    pub device_colorspaces_found: Vec<String>,
    /// Number of pages scanned.
    pub pages_scanned: usize,
    /// Number of Separation colorspaces unified (rule 6.2.4.4:2).
    pub separations_unified: usize,
    /// Number of ExtGState OPM values fixed (rule 6.2.4.2:2).
    pub overprint_mode_fixed: usize,
    /// Number of ICCBased /N values corrected (rule 6.2.4.2:1).
    pub icc_n_fixed: usize,
    /// Which device colour families the document was found to reach, and so
    /// which Default* profiles it was given.
    pub device_color_use: DeviceColorUse,
}

/// Detect device-dependent color spaces used in page resources.
pub fn find_device_colorspaces(doc: &Document) -> Vec<(ObjectId, String)> {
    let mut result = Vec::new();

    for (id, obj) in &doc.objects {
        let Object::Dictionary(dict) = obj else {
            continue;
        };

        if get_name(dict, b"Type").as_deref() != Some("Page") {
            continue;
        }

        let resources = match dict.get(b"Resources").ok() {
            Some(Object::Dictionary(res)) => Some(res.clone()),
            Some(Object::Reference(res_id)) => {
                if let Some(Object::Dictionary(res)) = doc.objects.get(res_id) {
                    Some(res.clone())
                } else {
                    None
                }
            }
            _ => None,
        };

        if let Some(res) = &resources {
            if let Ok(Object::Dictionary(cs_dict)) = res.get(b"ColorSpace") {
                for (key, val) in cs_dict.iter() {
                    let cs_name = resolve_colorspace_name(doc, val);
                    if is_device_dependent(&cs_name) {
                        let key_str = String::from_utf8_lossy(key).to_string();
                        result.push((*id, format!("{key_str}={cs_name}")));
                    }
                }
            }
        }
    }

    result
}

/// Check if the document has a GTS_PDFA1 OutputIntent.
pub fn has_pdfa_output_intent(doc: &Document) -> bool {
    let catalog = match get_catalog(doc) {
        Some(c) => c,
        None => return false,
    };

    let intents = match catalog.get(b"OutputIntents").ok() {
        Some(Object::Array(arr)) => arr,
        Some(Object::Reference(id)) => {
            if let Some(Object::Array(arr)) = doc.objects.get(id) {
                arr
            } else {
                return false;
            }
        }
        _ => return false,
    };

    intents.iter().any(|item| {
        let dict = match item {
            Object::Reference(id) => {
                if let Some(Object::Dictionary(d)) = doc.objects.get(id) {
                    d
                } else {
                    return false;
                }
            }
            Object::Dictionary(d) => d,
            _ => return false,
        };
        get_name(dict, b"S").as_deref() == Some("GTS_PDFA1")
    })
}

/// Find the DestOutputProfile indirect reference of any OutputIntent
/// already present in the document, regardless of colour space.
///
/// PDF/A-2 §6.2.3:2 requires that all OutputIntent entries with a
/// DestOutputProfile key reference the **same** indirect ICC object,
/// unconditionally — the rule makes no exception for entries that use
/// different colour spaces (an all-too-common source PDF is a print-ready
/// CMYK doc with an existing FOGRA/CMYK OutputIntent; adding a *second*,
/// sRGB one used to violate 6.2.3:2 on essentially every such document,
/// and vice versa for CMYK-adding on an RGB source). Both
/// `add_srgb_output_intent` reuses an existing characterization instead of
/// minting a different ICC stream.
fn find_existing_dest_output_profile(doc: &Document) -> Option<lopdf::ObjectId> {
    let catalog = get_catalog(doc);
    catalog.and_then(|cat| {
        let intents = match cat.get(b"OutputIntents").ok()? {
            Object::Array(arr) => arr.clone(),
            _ => return None,
        };
        for item in &intents {
            let dict = match item {
                Object::Reference(id) => match doc.objects.get(id) {
                    Some(Object::Dictionary(d)) => d,
                    _ => continue,
                },
                Object::Dictionary(d) => d,
                _ => continue,
            };
            if let Ok(Object::Reference(icc_id)) = dict.get(b"DestOutputProfile") {
                return Some(*icc_id);
            }
        }
        None
    })
}

/// Add an sRGB OutputIntent to the document for PDF/A compliance.
///
/// See [`find_existing_dest_output_profile`] for why an existing
/// DestOutputProfile (of any colour space) is reused when present.
pub fn add_srgb_output_intent(doc: &mut Document) -> Result<()> {
    let existing_icc_ref = find_existing_dest_output_profile(doc);

    let icc_id = match existing_icc_ref {
        Some(id) => id,
        None => {
            let icc_bytes = srgb_icc_profile_bytes();
            let icc_dict = dictionary! {
                "N" => Object::Integer(3),
                "Alternate" => Object::Name(b"DeviceRGB".to_vec()),
            };
            let icc_stream = Stream::new(icc_dict, icc_bytes);
            doc.add_object(Object::Stream(icc_stream))
        }
    };

    let intent = dictionary! {
        "Type" => Object::Name(b"OutputIntent".to_vec()),
        "S" => Object::Name(b"GTS_PDFA1".to_vec()),
        "OutputConditionIdentifier" => Object::String(
            b"sRGB IEC61966-2.1".to_vec(),
            lopdf::StringFormat::Literal,
        ),
        "RegistryName" => Object::String(
            b"http://www.color.org".to_vec(),
            lopdf::StringFormat::Literal,
        ),
        "Info" => Object::String(
            b"sRGB IEC61966-2.1".to_vec(),
            lopdf::StringFormat::Literal,
        ),
        "DestOutputProfile" => Object::Reference(icc_id),
    };
    let intent_id = doc.add_object(Object::Dictionary(intent));

    let catalog_id = get_catalog_id(doc)?;

    if let Some(Object::Dictionary(ref mut catalog)) = doc.objects.get_mut(&catalog_id) {
        let mut existing = match catalog.get(b"OutputIntents") {
            Ok(Object::Array(arr)) => arr.clone(),
            _ => Vec::new(),
        };
        existing.push(Object::Reference(intent_id));
        catalog.set("OutputIntents", Object::Array(existing));
    }

    Ok(())
}

fn only_calrgb_registration_colors(doc: &Document) -> bool {
    fn visit(doc: &Document, obj: &Object, calrgb: &mut bool, other: &mut bool) {
        match obj {
            Object::Array(a) => {
                if a.len() >= 4
                    && a[0].as_name().ok() == Some(b"Separation")
                    && a[1].as_name().ok() == Some(b"All")
                {
                    let calibrated_rgb = doc
                        .dereference(&a[2])
                        .ok()
                        .and_then(|(_, o)| o.as_array().ok())
                        .and_then(|a| a.first())
                        .and_then(|o| o.as_name().ok())
                        == Some(b"CalRGB");
                    *calrgb |= calibrated_rgb;
                    *other |= !calibrated_rgb;
                }
                for o in a {
                    visit(doc, o, calrgb, other);
                }
            }
            Object::Dictionary(d) => {
                for (_, o) in d.iter() {
                    visit(doc, o, calrgb, other);
                }
            }
            Object::Stream(s) => {
                for (_, o) in s.dict.iter() {
                    visit(doc, o, calrgb, other);
                }
            }
            _ => {}
        }
    }
    let (mut calrgb, mut other) = (false, false);
    for obj in doc.objects.values() {
        visit(doc, obj, &mut calrgb, &mut other);
    }
    // Removing the output condition from CMYK registration content can darken
    // ordinary process text. Only the demonstrated CalRGB case is eligible;
    // mixed and unresolved alternates keep the established output profile.
    calrgb && !other
}

fn needs_explicit_output_device(doc: &Document) -> bool {
    // A conservative census: uncertain transparency/inline image context
    // keeps the existing archival output profile rather than claiming it is
    // redundant. Pixel samples are never rewritten to make a metric pass.
    for obj in doc.objects.values() {
        let d = match obj {
            Object::Dictionary(d) => d,
            Object::Stream(s) => &s.dict,
            _ => continue,
        };
        if d.has(b"SMask") || d.has(b"BM") || d.has(b"ca") || d.has(b"CA") || d.has(b"Group") {
            return true;
        }
        if let Object::Stream(s) = obj {
            if s.dict.has(b"Length1")
                || matches!(
                    get_name(&s.dict, b"Subtype").as_deref(),
                    Some("Image" | "Type1C" | "CIDFontType0C" | "OpenType")
                )
            {
                continue;
            }
            if let Ok(bytes) = s.get_plain_content() {
                // The lexical decoder distinguishes actual images from BI in
                // strings. Declining a damaged stream keeps the safe baseline.
                match crate::inline_image::decode_strict(&bytes) {
                    Ok(content) if content.operations.iter().any(|o| o.operator == "BI") => {
                        return true
                    }
                    Err(_) if bytes.windows(2).any(|w| w == b"BI") => return true,
                    _ => {}
                }
            }
        }
    }
    false
}

/// Which device colour space families a document can reach.
///
/// One flag per family, and a flag means "this document can put a mark on a
/// page in that device space, by any route" — not "a Default\* entry belongs in
/// some particular resource dictionary". The two coincide for our purposes:
/// the ICC profile behind `DefaultCMYK` is the same object
/// [`fix_device_colorspaces_in_deep_structures`] substitutes into an image or
/// shading dictionary, so one family flag decides both.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
pub struct DeviceColorUse {
    /// DeviceGray, including the initial colour space of every content stream.
    pub gray: bool,
    /// DeviceRGB.
    pub rgb: bool,
    /// DeviceCMYK.
    pub cmyk: bool,
    /// A stream that would not decode was met, so every family is set whether
    /// or not it was seen. Recorded separately because it is the difference
    /// between "this document uses CMYK" and "this document could not be read".
    pub undecodable_stream: bool,
}

impl DeviceColorUse {
    fn everything() -> Self {
        Self {
            gray: true,
            rgb: true,
            cmyk: true,
            undecodable_stream: false,
        }
    }

    fn saturated(&self) -> bool {
        self.gray && self.rgb && self.cmyk
    }

    /// Record a colour space name, in full or in the abbreviation an inline
    /// image is allowed. Anything else -- a resource key, a calibrated or ICC
    /// space -- is not a device colour space and is not one of these families.
    fn note(&mut self, family: &[u8]) {
        match family {
            b"DeviceGray" | b"G" => self.gray = true,
            b"DeviceRGB" | b"RGB" => self.rgb = true,
            b"DeviceCMYK" | b"CMYK" => self.cmyk = true,
            _ => {}
        }
    }
}

/// Every stream in the document is a content program unless it is demonstrably
/// opaque payload.
///
/// By exclusion, deliberately. Enumerating the containers that hold a content
/// stream — pages, Form XObjects, tiling patterns, Type3 glyph procedures,
/// annotation appearances, soft-mask groups — is the census with a hole this
/// module was warned about: a container nobody thought to list is a colour
/// operator nobody counted, and the document that proves it is one we do not
/// have. Getting the exclusions wrong costs bytes (a payload scanned as
/// content produces false operators, which keeps a profile that was not
/// needed); getting an inclusion wrong costs conformance.
fn is_opaque_payload(stream: &Stream) -> bool {
    let dict = &stream.dict;
    // A font program: Length1/2/3 on Type1, or the FontFile3 subtypes.
    if dict.has(b"Length1")
        || matches!(
            get_name(dict, b"Subtype").as_deref(),
            Some("Image" | "Type1C" | "CIDFontType0C" | "OpenType")
        )
    {
        return true;
    }
    if matches!(
        get_name(dict, b"Type").as_deref(),
        Some("Metadata" | "XRef" | "ObjStm" | "EmbeddedFile" | "CMap")
    ) {
        return true;
    }
    // An ICC profile stream (/N components), a sampled function, a shading
    // mesh: binary, and each carries its colour space in its dictionary where
    // the object walk below reads it.
    if dict.has(b"N") || dict.has(b"FunctionType") || dict.has(b"ShadingType") {
        return true;
    }
    // Image-shaped without saying so. A thumbnail is an image XObject whose
    // /Type and /Subtype "shall be omitted" (PDF 32000-1 §12.3.4), so the
    // subtype test above does not catch it and decoding it as content would
    // report an undecodable stream on every document that has one.
    if dict.has(b"Width") && dict.has(b"Height") {
        return true;
    }
    // An image codec is never a content stream's filter.
    if let Ok(filters) = stream.filters() {
        if filters.iter().any(|f| {
            matches!(
                AsRef::<[u8]>::as_ref(f),
                b"DCTDecode" | b"DCT" | b"JPXDecode" | b"CCITTFaxDecode" | b"CCF" | b"JBIG2Decode"
            )
        }) {
            return true;
        }
    }
    false
}

/// Device colour space names anywhere in the object graph.
///
/// A device colour space is either a name in the object graph or an operator in
/// a content stream; there is no third place. This half covers the first, which
/// is every image /ColorSpace, shading /ColorSpace, transparency group /CS,
/// Separation and DeviceN alternate, Indexed base, pattern colour space and
/// resource /ColorSpace entry at once — including the ones reached through a
/// reference to a bare name, because the referenced name is itself an object in
/// this walk.
///
/// The single exclusion is `/Alternate` inside an ICC profile stream. That
/// entry names what a reader would fall back to if it could not use the
/// profile; the colour space in use is the ICCBased one. Counting it would mean
/// every document carrying a CMYK ICC profile — and every output of ours, since
/// the sRGB output intent's profile has `/Alternate /DeviceRGB` — pays for a
/// Default\* it never uses.
fn note_colorspace_names(obj: &Object, in_icc_profile: bool, seen: &mut DeviceColorUse) {
    match obj {
        Object::Name(name) => {
            // Inline-image abbreviations are only legal inside a BI dictionary,
            // which is handled by the content scan; a bare /G in the object
            // graph is a resource key, not a colour space.
            if matches!(
                name.as_slice(),
                b"DeviceGray" | b"DeviceRGB" | b"DeviceCMYK"
            ) {
                seen.note(name);
            }
        }
        Object::Array(items) => {
            for item in items {
                note_colorspace_names(item, false, seen);
            }
        }
        Object::Dictionary(dict) => {
            for (key, value) in dict.iter() {
                if in_icc_profile && key == b"Alternate" {
                    continue;
                }
                note_colorspace_names(value, false, seen);
            }
        }
        Object::Stream(stream) => {
            let is_icc = stream.dict.has(b"N") && !stream.dict.has(b"Width");
            for (key, value) in stream.dict.iter() {
                if is_icc && key == b"Alternate" {
                    continue;
                }
                note_colorspace_names(value, false, seen);
            }
        }
        _ => {}
    }
}

/// Device colour operators read from bytes rather than tokens, for a content
/// stream the strict parser refused.
///
/// Refusal is common and mostly means the producer wrote something the parser
/// will not sign off on, not that the stream is unreadable: on the 300-document
/// tuning set `decode_strict` refuses 8,040 streams across 238 of the 300
/// documents. Counting all of those as "uses every device space" is a census
/// that has given up -- it was worth 7 of the 4.9 MB this round is about,
/// because 247 of 300 documents kept a CMYK profile on the strength of a
/// parser complaint.
///
/// So the bytes are read instead. The discipline is the operand count, exactly
/// as in the token scan: a whitespace-then-`k` byte pair occurs constantly in
/// arbitrary data -- including the inline-image payloads that are still inline
/// here, since the stream did not parse -- and four numbers in front of it do
/// not. What survives of the conservative rule is the direction of the error:
/// this over-counts on binary noise, which costs bytes, and it takes a
/// deliberately strange encoding of an operator to make it under-count.
fn note_content_bytes(content: &[u8], seen: &mut DeviceColorUse) {
    // Whatever this stream is, it is a content stream with bytes in it, so it
    // paints; and a content stream starts in DeviceGray.
    seen.gray = true;

    for (operator, operands) in [
        (b"k".as_slice(), 4usize),
        (b"K".as_slice(), 4),
        (b"rg".as_slice(), 3),
        (b"RG".as_slice(), 3),
        (b"g".as_slice(), 1),
        (b"G".as_slice(), 1),
    ] {
        if operator_with_operands(content, operator, operands) {
            seen.note(match operator {
                b"k" | b"K" => b"DeviceCMYK",
                b"rg" | b"RG" => b"DeviceRGB",
                _ => b"DeviceGray",
            });
        }
    }

    // Colour space names, including the inline-image abbreviations, which are
    // only meaningful inside a BI dictionary but cost nothing to over-count.
    for name in [
        b"/DeviceCMYK".as_slice(),
        b"/DeviceRGB",
        b"/DeviceGray",
        b"/CMYK",
        b"/RGB",
    ] {
        if content.windows(name.len()).any(|w| w == name) {
            seen.note(&name[1..]);
        }
    }
}

/// Whether `content` contains `operator` as a token with `operands` numeric
/// operands in front of it.
fn operator_with_operands(content: &[u8], operator: &[u8], operands: usize) -> bool {
    let is_space = |b: u8| matches!(b, b' ' | b'\t' | b'\r' | b'\n' | 0x0c | 0);
    let is_number = |b: u8| b.is_ascii_digit() || b == b'.' || b == b'-' || b == b'+';

    for start in 0..content.len().saturating_sub(operator.len() - 1) {
        if &content[start..start + operator.len()] != operator {
            continue;
        }
        if start == 0 || !is_space(content[start - 1]) {
            continue;
        }
        let after = content.get(start + operator.len());
        let ends = match after {
            None => true,
            Some(&b) => is_space(b) || matches!(b, b'/' | b'[' | b']' | b'<' | b'>' | b'(' | b')'),
        };
        if !ends {
            continue;
        }
        let mut at = start;
        let mut found = 0;
        while found < operands {
            while at > 0 && is_space(content[at - 1]) {
                at -= 1;
            }
            let end = at;
            while at > 0 && is_number(content[at - 1]) {
                at -= 1;
            }
            if at == end {
                break;
            }
            found += 1;
        }
        if found == operands {
            return true;
        }
    }
    false
}

/// Device colour operators in one decoded content program.
fn note_content_operators(operations: &[lopdf::content::Operation], seen: &mut DeviceColorUse) {
    // The last `count` operands, numeric. Trailing rather than exact because
    // the content lexer ends an operator token at the first digit, so the `1`
    // of a Type3 glyph's `d1` arrives as an operand of the operator after it:
    // `10 0 0 0 10 10 d1 / 0 0 0 1 k` parses as `d [10 0 0 0 10 10]` followed
    // by `k [1 0 0 0 1]`. Requiring exactly four operands there misses the
    // CMYK fill in every Type3 glyph procedure in existence.
    let numeric = |operands: &[Object], count: usize| {
        operands.len() >= count
            && operands[operands.len() - count..]
                .iter()
                .all(|o| o.as_float().is_ok())
    };
    for op in operations {
        match op.operator.as_str() {
            // The operand count is the operator. `k` with three numbers in
            // front of it is not setcmykcolor, and a whitespace-then-`k` byte
            // pair occurs constantly in arbitrary data (govdocs 104_104177 is
            // the document that taught this module the difference).
            "g" | "G" if numeric(&op.operands, 1) => seen.gray = true,
            "rg" | "RG" if numeric(&op.operands, 3) => seen.rgb = true,
            "k" | "K" if numeric(&op.operands, 4) => seen.cmyk = true,
            "cs" | "CS" => {
                if let Some(Ok(name)) = op.operands.first().map(Object::as_name) {
                    seen.note(name);
                }
            }
            // An inline image carries its colour space in a dictionary that is
            // not an object in the document, so the object walk never sees it.
            "BI" => {
                if let Some(Ok(image)) = op.operands.first().map(Object::as_stream) {
                    for key in [b"CS".as_slice(), b"ColorSpace"] {
                        match image.dict.get(key) {
                            Ok(Object::Name(name)) => seen.note(name),
                            Ok(other) => note_colorspace_names(other, false, seen),
                            Err(_) => {}
                        }
                    }
                }
            }
            // Everything a content stream can paint. The initial colour space
            // of a content stream is DeviceGray (PDF 32000-1 §8.6.8), so a mark
            // made before any colour operator is a DeviceGray mark. Deciding
            // per mark whether a colour was selected first needs a full
            // graphics-state interpreter across q/Q, form invocation and
            // pattern nesting; getting that wrong costs conformance to save the
            // 126 bytes a DefaultGray profile occupies.
            "S" | "s" | "f" | "F" | "f*" | "B" | "B*" | "b" | "b*" | "Tj" | "TJ" | "'" | "\"" => {
                seen.gray = true
            }
            _ => {}
        }
    }
}

/// Which device colour spaces this document can actually reach.
///
/// Complete over the two places a device colour space can be named — the object
/// graph and a content program — with three conservative rules where certainty
/// is not available:
///
///  * a stream whose bytes cannot be recovered at all -- a filter that fails --
///    counts as using all three, because a census that skips what it cannot
///    read is a census with a hole in it. A stream whose bytes are there but
///    whose syntax the strict parser refuses is read as bytes instead, with
///    the same operand-count discipline;
///  * anything not demonstrably opaque payload is read as a content program,
///    so an unrecognised container is scanned rather than skipped;
///  * any painting or text-showing operator counts as DeviceGray, because that
///    is the colour space a content stream starts in.
///
/// Being wrong in the conservative direction embeds a profile that was not
/// needed and costs bytes. Being wrong in the other direction is a conformance
/// regression on a document we do not have, which is why this is the shape it
/// is.
pub fn census_device_colors(doc: &Document) -> DeviceColorUse {
    let mut seen = DeviceColorUse::default();

    for obj in doc.objects.values() {
        note_colorspace_names(obj, false, &mut seen);
    }

    for obj in doc.objects.values() {
        if seen.saturated() {
            break;
        }
        let Object::Stream(stream) = obj else {
            continue;
        };
        if is_opaque_payload(stream) {
            continue;
        }
        // Undecodable: it may set any colour, and nothing here can say it does
        // not. A filter that fails is not an error here -- the decoder warns
        // and hands back nothing rather than refusing, so a filtered stream
        // that decodes to nothing is the shape a broken filter arrives in.
        let bytes = match stream.get_plain_content() {
            Ok(bytes) if !bytes.is_empty() || stream.content.is_empty() => bytes,
            _ => {
                let mut all = DeviceColorUse::everything();
                all.undecodable_stream = true;
                return all;
            }
        };
        match crate::inline_image::decode_strict(&bytes) {
            Ok(content) => note_content_operators(&content.operations, &mut seen),
            // Not "unreadable": the bytes are here, the parser declined them.
            // Read them.
            Err(_) => note_content_bytes(&bytes, &mut seen),
        }
    }

    seen
}

/// Load every object the cross-reference table names.
///
/// `doc.objects` holds what has been parsed so far; objects inside object
/// streams may not be there yet. A census over the parsed half is a census with
/// a hole, so this runs before one.
///
/// Iterate the xref entries, never `1..=trailer /Size`: a crafted file can set
/// /Size to `u32::MAX` and turn that range into four billion lookups
/// (PDFA-CS-DOS-01).
fn materialize_all_objects(doc: &mut Document) {
    let numbers: Vec<u32> = doc.reference_table.entries.keys().copied().collect();
    for number in numbers {
        let id = (number, 0);
        if doc.objects.contains_key(&id) {
            continue;
        }
        if let Some(obj) = doc.get_object(id).ok().cloned() {
            doc.objects.insert(id, obj);
        }
    }
}

/// Give every content-bearing stream a Resources dictionary of its own.
///
/// ISO 19005-2 6.2.2:2 -- "a content stream that references other objects ...
/// shall have an explicitly associated Resources dictionary" -- and veraPDF
/// enforces it by name: a Form XObject with no `/Resources` inherits the
/// page's, and resolving a name through that inheritance is the failure.
///
/// This used to happen by accident. Adding Default\* to every form, pattern and
/// appearance stream created the dictionary on the way past, for any of them
/// that had none, and 6.2.2:2 was satisfied by a colour pass that was not
/// thinking about it. Making the profiles conditional took that away, and
/// `PDFBOX-4372-...-p4_reduced.pdf` in the gate corpus went from conformant to
/// not: one nested form, no Resources of its own, one `/Fm0` resolved through
/// the page.
///
/// So it is done deliberately now, on the same containers and with the same
/// result. What it does not do is copy the inherited resources in, so a name
/// that only resolved through inheritance still does not resolve -- exactly as
/// before this was written down. That is the better fix and it is a different
/// one: it changes what a reader draws, and it needs the render axis to say so.
fn ensure_explicit_resources(doc: &mut Document) {
    let ids: Vec<ObjectId> = doc
        .objects
        .iter()
        .filter_map(|(id, obj)| {
            let Object::Stream(stream) = obj else {
                return None;
            };
            let is_container = get_name(&stream.dict, b"Subtype").as_deref() == Some("Form")
                || stream.dict.has(b"PatternType");
            // `has` is not the question. The document that found this carries
            // `/Resources null`, which is a key with nothing behind it: the old
            // colour pass read it, got no dictionary, and wrote a fresh one.
            let explicit = match stream.dict.get(b"Resources") {
                Ok(Object::Dictionary(_)) => true,
                Ok(Object::Reference(id)) => {
                    matches!(doc.objects.get(id), Some(Object::Dictionary(_)))
                }
                _ => false,
            };
            (is_container && !explicit).then_some(*id)
        })
        .collect();

    for id in ids {
        if let Some(Object::Stream(stream)) = doc.objects.get_mut(&id) {
            stream
                .dict
                .set("Resources", Object::Dictionary(lopdf::Dictionary::new()));
        }
    }
}

/// Characterize device colors through Default* profiles and preserve supplied output intents.
pub fn normalize_colorspaces(doc: &mut Document) -> Result<ColorSpaceReport> {
    // Before anything is counted or added: an object still inside an object
    // stream is an object the census cannot see.
    materialize_all_objects(doc);
    let census = census_device_colors(doc);
    let had_output_intent = has_pdfa_output_intent(doc);
    let device_cs = find_device_colorspaces(doc);
    let pages_scanned = count_pages(doc);

    let device_names: Vec<String> = device_cs.into_iter().map(|(_, name)| name).collect();
    // Deduplicate with a HashSet to avoid O(n²) Vec::contains. (#perf)
    let unique_names: Vec<String> = {
        let mut seen = std::collections::HashSet::new();
        device_names
            .into_iter()
            .filter(|n| seen.insert(n.clone()))
            .collect()
    };

    // Registration colours have special process-device semantics. Inventing
    // an RGB output device can turn /Separation /All tint 0 (paper) black in
    // readers. Fully characterized opaque content needs no output intent.
    // Retain the existing output-device policy for transparency and inline
    // images until their independent blending/resource context is established.
    let registration = only_calrgb_registration_colors(doc);
    let needs_output_device = registration && needs_explicit_output_device(doc);
    let output_intent_added = if !had_output_intent && (!registration || needs_output_device) {
        add_srgb_output_intent(doc)?;
        true
    } else {
        false
    };

    // Add Default{CMYK,RGB,Gray} where the document can reach that device
    // space, and nowhere else. Adding all three unconditionally was the safe
    // reading of "device color spaces may appear in compressed streams or
    // inline images", and it cost 16,333 bytes in every output — 4,899,900
    // over the 300-document tuning set, against a total overshoot of 5,400,759
    // (benchmarks/pdfa/size/ROUND1.md). `census_device_colors` is what makes
    // the condition safe: it reads the compressed streams and the inline
    // images rather than assuming about them, and it counts a stream it cannot
    // decode as using everything.
    // Independent of the census, and it has to come first: what used to give
    // these streams a Resources dictionary was the Default* pass walking past
    // them.
    ensure_explicit_resources(doc);

    let cmyk_cs_id = census.cmyk.then(|| add_default_cmyk_colorspace(doc));
    let rgb_cs_id = census.rgb.then(|| add_default_rgb_colorspace(doc));
    if census.gray {
        add_default_gray_colorspace(doc);
    }

    // Replace DeviceCMYK/DeviceRGB references in deep structures (Shading, Group, Pattern)
    // that are not covered by Default* resource fallback.
    fix_device_colorspaces_in_deep_structures(doc, cmyk_cs_id, rgb_cs_id);

    let separations_unified = normalize_separation_colorspaces(doc);

    // Replace DeviceCMYK/DeviceRGB in Separation alternate colorspaces.
    // veraPDF 6.2.4.3:3 fails when DeviceCMYK appears as a Separation alternate
    // and the output intent is not CMYK. Replacing with ICCBased also helps
    // 6.2.4.4:2 by ensuring the alternate field compares equal across traversal
    // paths (same object reference, not just same name).
    fix_separation_device_alternates(doc, cmyk_cs_id, rgb_cs_id);

    let overprint_mode_fixed = fix_overprint_mode(doc);
    let icc_n_fixed = fix_iccbased_n_value(doc);

    Ok(ColorSpaceReport {
        had_output_intent,
        output_intent_added,
        device_colorspaces_found: unique_names,
        pages_scanned,
        separations_unified,
        overprint_mode_fixed,
        icc_n_fixed,
        device_color_use: census,
    })
}

#[cfg(test)]
fn has_device_rgb_in_streams(doc: &Document) -> bool {
    doc.objects.values().any(|obj| {
        let Object::Stream(stream) = obj else {
            return false;
        };
        // /N is the ICCBased component count; 3 components is an RGB profile.
        if let Ok(Object::Integer(3)) = stream.dict.get(b"N") {
            return true;
        }
        let content = match stream.decompressed_content() {
            Ok(c) => c,
            Err(_) => stream.content.clone(),
        };
        content
            .windows(b"DeviceRGB".len())
            .any(|w| w == b"DeviceRGB")
    })
}

/// The same complete CMYK characterization already used by the renderer.
/// The previous 416-byte placeholder omitted the LUT input/output tables and
/// color lookup grid; readers could not perform a valid ICC transformation.
fn cmyk_icc_profile_bytes() -> Vec<u8> {
    include_bytes!("../assets/CGATS001Compat-v2-micro.icc").to_vec()
}

/// sRGB ICC v2.1 profile with all required tags for PDF/A compliance.
///
/// Contains 9 tags: desc, cprt, wtpt, rXYZ, gXYZ, bXYZ, rTRC, gTRC, bTRC.
/// Uses D50-adapted primaries and the IEC sRGB piecewise transfer curve.
/// ICC v2 encodes that curve as a sampled curveType (4096 samples), rather
/// than mislabeling a simple gamma-2.2 approximation as sRGB.
/// Reference: https://registry.color.org/rgb-registry/files/sRGB.pdf
fn srgb_icc_profile_bytes() -> Vec<u8> {
    // Layout:
    //   0..128   header
    //   128..132 tag count (9)
    //   132..240 9 tag entries (12 bytes each)
    //   240..336 desc tag data (96 bytes, padded)
    //   336..348 cprt tag data (12 bytes)
    //   348..368 wtpt tag data (20 bytes)
    //   368..388 rXYZ tag data (20 bytes)
    //   388..408 gXYZ tag data (20 bytes)
    //   408..428 bXYZ tag data (20 bytes)
    //   428..8632 shared curv tag data (12 + 4096 * 2 bytes)
    let total_size: u32 = 8632;
    let mut p = Vec::with_capacity(total_size as usize);

    // === Header (128 bytes) ===
    p.extend_from_slice(&total_size.to_be_bytes()); // profile size
    p.extend_from_slice(b"\0\0\0\0"); // preferred CMM
    p.extend_from_slice(&[2, 0x10, 0, 0]); // version 2.1.0
    p.extend_from_slice(b"mntr"); // device class: monitor
    p.extend_from_slice(b"RGB "); // color space
    p.extend_from_slice(b"XYZ "); // PCS
    p.extend_from_slice(&[0u8; 12]); // date/time
    p.extend_from_slice(b"acsp"); // signature
    p.extend_from_slice(&[0u8; 4]); // platform
    p.extend_from_slice(&[0u8; 4]); // flags
    p.extend_from_slice(&[0u8; 4]); // manufacturer
    p.extend_from_slice(&[0u8; 4]); // model
    p.extend_from_slice(&[0u8; 8]); // device attributes
    p.extend_from_slice(&[0u8; 4]); // rendering intent (perceptual)
                                    // PCS illuminant D50 (X=0.9642, Y=1.0, Z=0.8249)
    p.extend_from_slice(&0x0000F6D6_u32.to_be_bytes()); // X
    p.extend_from_slice(&0x00010000_u32.to_be_bytes()); // Y
    p.extend_from_slice(&0x0000D32D_u32.to_be_bytes()); // Z
    p.extend_from_slice(&[0u8; 4]); // creator
    p.extend_from_slice(&[0u8; 16]); // profile ID
    p.extend_from_slice(&[0u8; 128 - 100]); // reserved padding to 128
    debug_assert_eq!(p.len(), 128);

    // === Tag table ===
    p.extend_from_slice(&9_u32.to_be_bytes()); // 9 tags

    // Tag entries: signature(4) + offset(4) + size(4) = 12 bytes each
    let tags: &[(&[u8; 4], u32, u32)] = &[
        (b"desc", 240, 95),
        (b"cprt", 336, 12),
        (b"wtpt", 348, 20),
        (b"rXYZ", 368, 20),
        (b"gXYZ", 388, 20),
        (b"bXYZ", 408, 20),
        (b"rTRC", 428, 8204),
        (b"gTRC", 428, 8204), // shared with rTRC
        (b"bTRC", 428, 8204), // shared with rTRC
    ];
    for (sig, offset, size) in tags {
        p.extend_from_slice(*sig);
        p.extend_from_slice(&offset.to_be_bytes());
        p.extend_from_slice(&size.to_be_bytes());
    }
    debug_assert_eq!(p.len(), 240);

    // === desc tag (textDescriptionType) — 95 bytes + 1 pad = 96 ===
    p.extend_from_slice(b"desc"); // type signature
    p.extend_from_slice(&[0u8; 4]); // reserved
    p.extend_from_slice(&5_u32.to_be_bytes()); // ASCII length (incl. null)
    p.extend_from_slice(b"sRGB\0"); // ASCII string
    p.extend_from_slice(&[0u8; 4]); // Unicode language code
    p.extend_from_slice(&[0u8; 4]); // Unicode count (0 = none)
    p.extend_from_slice(&[0u8; 2]); // ScriptCode code
    p.push(0); // ScriptCode count
    p.extend_from_slice(&[0u8; 67]); // ScriptCode string (always 67)
    p.push(0); // pad to 4-byte alignment
    debug_assert_eq!(p.len(), 336);

    // === cprt tag (textType) — 12 bytes ===
    p.extend_from_slice(b"text"); // type signature
    p.extend_from_slice(&[0u8; 4]); // reserved
    p.extend_from_slice(b"CC0\0"); // copyright text
    debug_assert_eq!(p.len(), 348);

    // === XYZ tags (XYZType) — 20 bytes each ===
    // Helper: write XYZ tag
    fn write_xyz(p: &mut Vec<u8>, x: i32, y: i32, z: i32) {
        p.extend_from_slice(b"XYZ "); // type signature
        p.extend_from_slice(&[0u8; 4]); // reserved
        p.extend_from_slice(&x.to_be_bytes());
        p.extend_from_slice(&y.to_be_bytes());
        p.extend_from_slice(&z.to_be_bytes());
    }

    // wtpt — D50, consistent with the adapted primaries and PCS.
    write_xyz(&mut p, 0x0000F6D6, 0x00010000, 0x0000D32D);
    debug_assert_eq!(p.len(), 368);

    // rXYZ — Red primary (X=0.4361, Y=0.2225, Z=0.0139)
    write_xyz(&mut p, 0x00006FA3, 0x000038F6, 0x00000391);
    debug_assert_eq!(p.len(), 388);

    // gXYZ — Green primary (X=0.3851, Y=0.7169, Z=0.0971)
    write_xyz(&mut p, 0x00006294, 0x0000B785, 0x000018DC);
    debug_assert_eq!(p.len(), 408);

    // bXYZ — Blue primary (X=0.1431, Y=0.0606, Z=0.7142)
    write_xyz(&mut p, 0x000024A1, 0x00000F85, 0x0000B6D4);
    debug_assert_eq!(p.len(), 428);

    // The linear toe matters: gamma 2.2 darkens neutral shades in readers
    // that use real sRGB as their output space.
    p.extend_from_slice(b"curv");
    p.extend_from_slice(&[0u8; 4]);
    p.extend_from_slice(&4096_u32.to_be_bytes());
    for sample in 0..4096 {
        let encoded = f64::from(sample) / 4095.0;
        let linear = if encoded <= 0.04045 {
            encoded / 12.92
        } else {
            ((encoded + 0.055) / 1.055).powf(2.4)
        };
        p.extend_from_slice(&((linear * 65535.0).round() as u16).to_be_bytes());
    }
    debug_assert_eq!(p.len(), total_size as usize);

    p
}

/// Add DefaultCMYK ICCBased colorspace to all page resources.
/// This allows DeviceCMYK usage when the OutputIntent is sRGB (not CMYK).
/// Returns the ObjectId of the ICCBased colorspace array for reuse.
fn add_default_cmyk_colorspace(doc: &mut Document) -> ObjectId {
    let icc_bytes = cmyk_icc_profile_bytes();
    let icc_dict = dictionary! {
        "N" => Object::Integer(4),
        "Alternate" => Object::Name(b"DeviceCMYK".to_vec()),
    };
    let icc_stream = Stream::new(icc_dict, icc_bytes);
    let icc_id = doc.add_object(Object::Stream(icc_stream));

    // Create ICCBased colorspace array: [/ICCBased <ref>]
    let cs_array = Object::Array(vec![
        Object::Name(b"ICCBased".to_vec()),
        Object::Reference(icc_id),
    ]);
    let cs_id = doc.add_object(cs_array);

    // Add DefaultCMYK to each page's ColorSpace resources.
    let page_ids: Vec<ObjectId> = doc
        .objects
        .iter()
        .filter_map(|(id, obj)| {
            if let Object::Dictionary(dict) = obj {
                if get_name(dict, b"Type").as_deref() == Some("Page") {
                    return Some(*id);
                }
            }
            None
        })
        .collect();

    for page_id in page_ids {
        // Get or create Resources dict.
        let res_id = {
            let Some(Object::Dictionary(dict)) = doc.objects.get(&page_id) else {
                continue;
            };
            match dict.get(b"Resources").ok() {
                Some(Object::Reference(id)) => Some(*id),
                Some(Object::Dictionary(_)) => None, // inline resources — handle below
                _ => None,
            }
        };

        if let Some(res_id) = res_id {
            // Resources is a reference — modify the referenced dict.
            // First resolve ColorSpace if it's also a reference.
            let cs_ref_id = {
                if let Some(Object::Dictionary(res)) = doc.objects.get(&res_id) {
                    match res.get(b"ColorSpace").ok() {
                        Some(Object::Reference(id)) => Some(*id),
                        _ => None,
                    }
                } else {
                    None
                }
            };
            if let Some(cs_ref_id) = cs_ref_id {
                // ColorSpace is itself a reference — modify that dict.
                if let Some(Object::Dictionary(ref mut cs_dict)) = doc.objects.get_mut(&cs_ref_id) {
                    if !cs_dict.has(b"DefaultCMYK") {
                        cs_dict.set("DefaultCMYK", Object::Reference(cs_id));
                    }
                }
            } else if let Some(Object::Dictionary(ref mut res)) = doc.objects.get_mut(&res_id) {
                let mut cs_dict = match res.get(b"ColorSpace") {
                    Ok(Object::Dictionary(d)) => d.clone(),
                    _ => lopdf::Dictionary::new(),
                };
                if !cs_dict.has(b"DefaultCMYK") {
                    cs_dict.set("DefaultCMYK", Object::Reference(cs_id));
                    res.set("ColorSpace", Object::Dictionary(cs_dict));
                }
            }
        } else {
            // Resources is inline in the page dict.
            if let Some(Object::Dictionary(ref mut dict)) = doc.objects.get_mut(&page_id) {
                let mut res = match dict.get(b"Resources") {
                    Ok(Object::Dictionary(d)) => d.clone(),
                    _ => lopdf::Dictionary::new(),
                };
                let mut cs_dict = match res.get(b"ColorSpace") {
                    Ok(Object::Dictionary(d)) => d.clone(),
                    _ => lopdf::Dictionary::new(),
                };
                if !cs_dict.has(b"DefaultCMYK") {
                    cs_dict.set("DefaultCMYK", Object::Reference(cs_id));
                    res.set("ColorSpace", Object::Dictionary(cs_dict));
                    dict.set("Resources", Object::Dictionary(res));
                }
            }
        }
    }

    // Also add DefaultCMYK to ALL Form XObject Resources (even those without
    // an existing ColorSpace dict or without Resources at all).
    let form_ids: Vec<ObjectId> = doc
        .objects
        .iter()
        .filter_map(|(id, obj)| {
            if let Object::Stream(stream) = obj {
                if get_name(&stream.dict, b"Subtype").as_deref() == Some("Form") {
                    return Some(*id);
                }
            }
            None
        })
        .collect();

    for form_id in form_ids {
        let res_ref_id = {
            if let Some(Object::Stream(stream)) = doc.objects.get(&form_id) {
                match stream.dict.get(b"Resources").ok() {
                    Some(Object::Reference(id)) => Some(*id),
                    _ => None,
                }
            } else {
                None
            }
        };

        if let Some(res_ref_id) = res_ref_id {
            // Resources is a reference — modify the referenced dict.
            if let Some(Object::Dictionary(ref mut res)) = doc.objects.get_mut(&res_ref_id) {
                let mut cs_dict = match res.get(b"ColorSpace") {
                    Ok(Object::Dictionary(d)) => d.clone(),
                    _ => lopdf::Dictionary::new(),
                };
                if !cs_dict.has(b"DefaultCMYK") {
                    cs_dict.set("DefaultCMYK", Object::Reference(cs_id));
                    res.set("ColorSpace", Object::Dictionary(cs_dict));
                }
            }
        } else if let Some(Object::Stream(ref mut stream)) = doc.objects.get_mut(&form_id) {
            // Resources inline or missing — create/update.
            let mut res = match stream.dict.get(b"Resources") {
                Ok(Object::Dictionary(d)) => d.clone(),
                _ => lopdf::Dictionary::new(),
            };
            let mut cs_dict = match res.get(b"ColorSpace") {
                Ok(Object::Dictionary(d)) => d.clone(),
                _ => lopdf::Dictionary::new(),
            };
            if !cs_dict.has(b"DefaultCMYK") {
                cs_dict.set("DefaultCMYK", Object::Reference(cs_id));
                res.set("ColorSpace", Object::Dictionary(cs_dict));
                stream.dict.set("Resources", Object::Dictionary(res));
            }
        }
    }

    // Also add DefaultCMYK to tiling pattern streams (PatternType=1).
    let pattern_ids: Vec<ObjectId> = doc
        .objects
        .iter()
        .filter_map(|(id, obj)| {
            if let Object::Stream(stream) = obj {
                let pt = stream
                    .dict
                    .get(b"PatternType")
                    .ok()
                    .and_then(|o| o.as_i64().ok());
                if pt == Some(1) {
                    return Some(*id);
                }
            }
            None
        })
        .collect();

    for pat_id in pattern_ids {
        let res_ref_id = {
            if let Some(Object::Stream(stream)) = doc.objects.get(&pat_id) {
                match stream.dict.get(b"Resources").ok() {
                    Some(Object::Reference(id)) => Some(*id),
                    _ => None,
                }
            } else {
                None
            }
        };

        if let Some(res_ref_id) = res_ref_id {
            if let Some(Object::Dictionary(ref mut res)) = doc.objects.get_mut(&res_ref_id) {
                let mut cs_dict = match res.get(b"ColorSpace") {
                    Ok(Object::Dictionary(d)) => d.clone(),
                    _ => lopdf::Dictionary::new(),
                };
                if !cs_dict.has(b"DefaultCMYK") {
                    cs_dict.set("DefaultCMYK", Object::Reference(cs_id));
                    res.set("ColorSpace", Object::Dictionary(cs_dict));
                }
            }
        } else if let Some(Object::Stream(ref mut stream)) = doc.objects.get_mut(&pat_id) {
            let mut res = match stream.dict.get(b"Resources") {
                Ok(Object::Dictionary(d)) => d.clone(),
                _ => lopdf::Dictionary::new(),
            };
            let mut cs_dict = match res.get(b"ColorSpace") {
                Ok(Object::Dictionary(d)) => d.clone(),
                _ => lopdf::Dictionary::new(),
            };
            if !cs_dict.has(b"DefaultCMYK") {
                cs_dict.set("DefaultCMYK", Object::Reference(cs_id));
                res.set("ColorSpace", Object::Dictionary(cs_dict));
                stream.dict.set("Resources", Object::Dictionary(res));
            }
        }
    }

    // Also add DefaultCMYK to annotation appearance streams.
    // Widget annotations may have AP streams using DeviceCMYK operators (K/k)
    // with their own Resources that lack DefaultCMYK. (fixes §6.2.4.3:3 in APs)
    add_default_cs_to_annotation_appearances(doc, b"DefaultCMYK", cs_id);

    cs_id
}

/// Add DefaultRGB ICCBased colorspace (sRGB) to all page and Form XObject resources.
/// This maps DeviceRGB to an ICC profile for PDF/A compliance.
/// Returns the ObjectId of the ICCBased colorspace array for reuse.
fn add_default_rgb_colorspace(doc: &mut Document) -> ObjectId {
    let icc_bytes = srgb_icc_profile_bytes();
    let icc_dict = dictionary! {
        "N" => Object::Integer(3),
        "Alternate" => Object::Name(b"DeviceRGB".to_vec()),
    };
    let icc_stream = Stream::new(icc_dict, icc_bytes);
    let icc_id = doc.add_object(Object::Stream(icc_stream));

    let cs_array = Object::Array(vec![
        Object::Name(b"ICCBased".to_vec()),
        Object::Reference(icc_id),
    ]);
    let cs_id = doc.add_object(cs_array);

    // Add DefaultRGB to each page's ColorSpace resources.
    let page_ids: Vec<ObjectId> = doc
        .objects
        .iter()
        .filter_map(|(id, obj)| {
            if let Object::Dictionary(dict) = obj {
                if get_name(dict, b"Type").as_deref() == Some("Page") {
                    return Some(*id);
                }
            }
            None
        })
        .collect();

    for page_id in page_ids {
        let res_id = {
            let Some(Object::Dictionary(dict)) = doc.objects.get(&page_id) else {
                continue;
            };
            match dict.get(b"Resources").ok() {
                Some(Object::Reference(id)) => Some(*id),
                _ => None,
            }
        };

        if let Some(res_id) = res_id {
            let cs_ref_id = {
                if let Some(Object::Dictionary(res)) = doc.objects.get(&res_id) {
                    match res.get(b"ColorSpace").ok() {
                        Some(Object::Reference(id)) => Some(*id),
                        _ => None,
                    }
                } else {
                    None
                }
            };
            if let Some(cs_ref_id) = cs_ref_id {
                if let Some(Object::Dictionary(ref mut cs_dict)) = doc.objects.get_mut(&cs_ref_id) {
                    if !cs_dict.has(b"DefaultRGB") {
                        cs_dict.set("DefaultRGB", Object::Reference(cs_id));
                    }
                }
            } else if let Some(Object::Dictionary(ref mut res)) = doc.objects.get_mut(&res_id) {
                let mut cs_dict = match res.get(b"ColorSpace") {
                    Ok(Object::Dictionary(d)) => d.clone(),
                    _ => lopdf::Dictionary::new(),
                };
                if !cs_dict.has(b"DefaultRGB") {
                    cs_dict.set("DefaultRGB", Object::Reference(cs_id));
                    res.set("ColorSpace", Object::Dictionary(cs_dict));
                }
            }
        } else if let Some(Object::Dictionary(ref mut dict)) = doc.objects.get_mut(&page_id) {
            let mut res = match dict.get(b"Resources") {
                Ok(Object::Dictionary(d)) => d.clone(),
                _ => lopdf::Dictionary::new(),
            };
            let mut cs_dict = match res.get(b"ColorSpace") {
                Ok(Object::Dictionary(d)) => d.clone(),
                _ => lopdf::Dictionary::new(),
            };
            if !cs_dict.has(b"DefaultRGB") {
                cs_dict.set("DefaultRGB", Object::Reference(cs_id));
                res.set("ColorSpace", Object::Dictionary(cs_dict));
                dict.set("Resources", Object::Dictionary(res));
            }
        }
    }

    // Also add to Form XObjects.
    let form_ids: Vec<ObjectId> = doc
        .objects
        .iter()
        .filter_map(|(id, obj)| {
            if let Object::Stream(stream) = obj {
                if get_name(&stream.dict, b"Subtype").as_deref() == Some("Form") {
                    return Some(*id);
                }
            }
            None
        })
        .collect();

    for form_id in form_ids {
        let res_ref_id = {
            if let Some(Object::Stream(stream)) = doc.objects.get(&form_id) {
                match stream.dict.get(b"Resources").ok() {
                    Some(Object::Reference(id)) => Some(*id),
                    _ => None,
                }
            } else {
                None
            }
        };

        if let Some(res_ref_id) = res_ref_id {
            if let Some(Object::Dictionary(ref mut res)) = doc.objects.get_mut(&res_ref_id) {
                let mut cs_dict = match res.get(b"ColorSpace") {
                    Ok(Object::Dictionary(d)) => d.clone(),
                    _ => lopdf::Dictionary::new(),
                };
                if !cs_dict.has(b"DefaultRGB") {
                    cs_dict.set("DefaultRGB", Object::Reference(cs_id));
                    res.set("ColorSpace", Object::Dictionary(cs_dict));
                }
            }
        } else if let Some(Object::Stream(ref mut stream)) = doc.objects.get_mut(&form_id) {
            let mut res = match stream.dict.get(b"Resources") {
                Ok(Object::Dictionary(d)) => d.clone(),
                _ => lopdf::Dictionary::new(),
            };
            let mut cs_dict = match res.get(b"ColorSpace") {
                Ok(Object::Dictionary(d)) => d.clone(),
                _ => lopdf::Dictionary::new(),
            };
            if !cs_dict.has(b"DefaultRGB") {
                cs_dict.set("DefaultRGB", Object::Reference(cs_id));
                res.set("ColorSpace", Object::Dictionary(cs_dict));
                stream.dict.set("Resources", Object::Dictionary(res));
            }
        }
    }

    // Also add DefaultRGB to tiling pattern streams (PatternType=1).
    let pattern_ids: Vec<ObjectId> = doc
        .objects
        .iter()
        .filter_map(|(id, obj)| {
            if let Object::Stream(stream) = obj {
                let pt = stream
                    .dict
                    .get(b"PatternType")
                    .ok()
                    .and_then(|o| o.as_i64().ok());
                if pt == Some(1) {
                    return Some(*id);
                }
            }
            None
        })
        .collect();

    for pat_id in pattern_ids {
        let res_ref_id = {
            if let Some(Object::Stream(stream)) = doc.objects.get(&pat_id) {
                match stream.dict.get(b"Resources").ok() {
                    Some(Object::Reference(id)) => Some(*id),
                    _ => None,
                }
            } else {
                None
            }
        };

        if let Some(res_ref_id) = res_ref_id {
            if let Some(Object::Dictionary(ref mut res)) = doc.objects.get_mut(&res_ref_id) {
                let mut cs_dict = match res.get(b"ColorSpace") {
                    Ok(Object::Dictionary(d)) => d.clone(),
                    _ => lopdf::Dictionary::new(),
                };
                if !cs_dict.has(b"DefaultRGB") {
                    cs_dict.set("DefaultRGB", Object::Reference(cs_id));
                    res.set("ColorSpace", Object::Dictionary(cs_dict));
                }
            }
        } else if let Some(Object::Stream(ref mut stream)) = doc.objects.get_mut(&pat_id) {
            let mut res = match stream.dict.get(b"Resources") {
                Ok(Object::Dictionary(d)) => d.clone(),
                _ => lopdf::Dictionary::new(),
            };
            let mut cs_dict = match res.get(b"ColorSpace") {
                Ok(Object::Dictionary(d)) => d.clone(),
                _ => lopdf::Dictionary::new(),
            };
            if !cs_dict.has(b"DefaultRGB") {
                cs_dict.set("DefaultRGB", Object::Reference(cs_id));
                res.set("ColorSpace", Object::Dictionary(cs_dict));
                stream.dict.set("Resources", Object::Dictionary(res));
            }
        }
    }

    // Also add DefaultRGB to annotation appearance streams.
    add_default_cs_to_annotation_appearances(doc, b"DefaultRGB", cs_id);

    cs_id
}

/// Add a DefaultGray (sgray N=1 ICCBased) colorspace to all page, Form XObject,
/// and tiling pattern Resources. Satisfies 6.2.4.3:4 ("DeviceGray shall only be
/// used if a device independent DefaultGray colour space has been set").
fn add_default_gray_colorspace(doc: &mut Document) -> ObjectId {
    let icc_bytes = gray_icc_profile_bytes();
    let icc_dict = dictionary! {
        "N" => Object::Integer(1),
        "Alternate" => Object::Name(b"DeviceGray".to_vec()),
    };
    let icc_stream = Stream::new(icc_dict, icc_bytes);
    let icc_id = doc.add_object(Object::Stream(icc_stream));

    let cs_array = Object::Array(vec![
        Object::Name(b"ICCBased".to_vec()),
        Object::Reference(icc_id),
    ]);
    let cs_id = doc.add_object(cs_array);

    // Pages.
    let page_ids: Vec<ObjectId> = doc
        .objects
        .iter()
        .filter_map(|(id, obj)| {
            if let Object::Dictionary(dict) = obj {
                if get_name(dict, b"Type").as_deref() == Some("Page") {
                    return Some(*id);
                }
            }
            None
        })
        .collect();

    for page_id in page_ids {
        let res_id = {
            let Some(Object::Dictionary(dict)) = doc.objects.get(&page_id) else {
                continue;
            };
            match dict.get(b"Resources").ok() {
                Some(Object::Reference(id)) => Some(*id),
                _ => None,
            }
        };

        if let Some(res_id) = res_id {
            let cs_ref_id = {
                if let Some(Object::Dictionary(res)) = doc.objects.get(&res_id) {
                    match res.get(b"ColorSpace").ok() {
                        Some(Object::Reference(id)) => Some(*id),
                        _ => None,
                    }
                } else {
                    None
                }
            };
            if let Some(cs_ref_id) = cs_ref_id {
                if let Some(Object::Dictionary(ref mut cs_dict)) = doc.objects.get_mut(&cs_ref_id) {
                    if !cs_dict.has(b"DefaultGray") {
                        cs_dict.set("DefaultGray", Object::Reference(cs_id));
                    }
                }
            } else if let Some(Object::Dictionary(ref mut res)) = doc.objects.get_mut(&res_id) {
                let mut cs_dict = match res.get(b"ColorSpace") {
                    Ok(Object::Dictionary(d)) => d.clone(),
                    _ => lopdf::Dictionary::new(),
                };
                if !cs_dict.has(b"DefaultGray") {
                    cs_dict.set("DefaultGray", Object::Reference(cs_id));
                    res.set("ColorSpace", Object::Dictionary(cs_dict));
                }
            }
        } else if let Some(Object::Dictionary(ref mut dict)) = doc.objects.get_mut(&page_id) {
            let mut res = match dict.get(b"Resources") {
                Ok(Object::Dictionary(d)) => d.clone(),
                _ => lopdf::Dictionary::new(),
            };
            let mut cs_dict = match res.get(b"ColorSpace") {
                Ok(Object::Dictionary(d)) => d.clone(),
                _ => lopdf::Dictionary::new(),
            };
            if !cs_dict.has(b"DefaultGray") {
                cs_dict.set("DefaultGray", Object::Reference(cs_id));
                res.set("ColorSpace", Object::Dictionary(cs_dict));
                dict.set("Resources", Object::Dictionary(res));
            }
        }
    }

    // Form XObjects.
    let form_ids: Vec<ObjectId> = doc
        .objects
        .iter()
        .filter_map(|(id, obj)| {
            if let Object::Stream(stream) = obj {
                if get_name(&stream.dict, b"Subtype").as_deref() == Some("Form") {
                    return Some(*id);
                }
            }
            None
        })
        .collect();

    for form_id in form_ids {
        let res_ref_id = {
            if let Some(Object::Stream(stream)) = doc.objects.get(&form_id) {
                match stream.dict.get(b"Resources").ok() {
                    Some(Object::Reference(id)) => Some(*id),
                    _ => None,
                }
            } else {
                None
            }
        };

        if let Some(res_ref_id) = res_ref_id {
            if let Some(Object::Dictionary(ref mut res)) = doc.objects.get_mut(&res_ref_id) {
                let mut cs_dict = match res.get(b"ColorSpace") {
                    Ok(Object::Dictionary(d)) => d.clone(),
                    _ => lopdf::Dictionary::new(),
                };
                if !cs_dict.has(b"DefaultGray") {
                    cs_dict.set("DefaultGray", Object::Reference(cs_id));
                    res.set("ColorSpace", Object::Dictionary(cs_dict));
                }
            }
        } else if let Some(Object::Stream(ref mut stream)) = doc.objects.get_mut(&form_id) {
            let mut res = match stream.dict.get(b"Resources") {
                Ok(Object::Dictionary(d)) => d.clone(),
                _ => lopdf::Dictionary::new(),
            };
            let mut cs_dict = match res.get(b"ColorSpace") {
                Ok(Object::Dictionary(d)) => d.clone(),
                _ => lopdf::Dictionary::new(),
            };
            if !cs_dict.has(b"DefaultGray") {
                cs_dict.set("DefaultGray", Object::Reference(cs_id));
                res.set("ColorSpace", Object::Dictionary(cs_dict));
                stream.dict.set("Resources", Object::Dictionary(res));
            }
        }
    }

    // Tiling patterns.
    let pattern_ids: Vec<ObjectId> = doc
        .objects
        .iter()
        .filter_map(|(id, obj)| {
            if let Object::Stream(stream) = obj {
                let pt = stream
                    .dict
                    .get(b"PatternType")
                    .ok()
                    .and_then(|o| o.as_i64().ok());
                if pt == Some(1) {
                    return Some(*id);
                }
            }
            None
        })
        .collect();

    for pat_id in pattern_ids {
        let res_ref_id = {
            if let Some(Object::Stream(stream)) = doc.objects.get(&pat_id) {
                match stream.dict.get(b"Resources").ok() {
                    Some(Object::Reference(id)) => Some(*id),
                    _ => None,
                }
            } else {
                None
            }
        };

        if let Some(res_ref_id) = res_ref_id {
            if let Some(Object::Dictionary(ref mut res)) = doc.objects.get_mut(&res_ref_id) {
                let mut cs_dict = match res.get(b"ColorSpace") {
                    Ok(Object::Dictionary(d)) => d.clone(),
                    _ => lopdf::Dictionary::new(),
                };
                if !cs_dict.has(b"DefaultGray") {
                    cs_dict.set("DefaultGray", Object::Reference(cs_id));
                    res.set("ColorSpace", Object::Dictionary(cs_dict));
                }
            }
        } else if let Some(Object::Stream(ref mut stream)) = doc.objects.get_mut(&pat_id) {
            let mut res = match stream.dict.get(b"Resources") {
                Ok(Object::Dictionary(d)) => d.clone(),
                _ => lopdf::Dictionary::new(),
            };
            let mut cs_dict = match res.get(b"ColorSpace") {
                Ok(Object::Dictionary(d)) => d.clone(),
                _ => lopdf::Dictionary::new(),
            };
            if !cs_dict.has(b"DefaultGray") {
                cs_dict.set("DefaultGray", Object::Reference(cs_id));
                res.set("ColorSpace", Object::Dictionary(cs_dict));
                stream.dict.set("Resources", Object::Dictionary(res));
            }
        }
    }

    // Also add DefaultGray to annotation appearance streams.
    add_default_cs_to_annotation_appearances(doc, b"DefaultGray", cs_id);

    cs_id
}

/// Add a Default* colorspace entry to all annotation appearance streams.
/// Annotations have their own Resources; the page Default* doesn't apply.
fn add_default_cs_to_annotation_appearances(doc: &mut Document, name: &[u8], cs_id: ObjectId) {
    // Collect all appearance stream IDs referenced from annotations.
    let mut ap_stream_ids: Vec<ObjectId> = Vec::new();
    let ids: Vec<ObjectId> = doc.objects.keys().copied().collect();
    for id in &ids {
        let ap_refs = match doc.objects.get(id) {
            Some(Object::Dictionary(dict)) => {
                // Check if this is an annotation (has /Subtype and /Rect or /Type=Annot).
                let is_annot = dict.has(b"Rect") && (dict.has(b"Subtype") || dict.has(b"Type"));
                if !is_annot {
                    continue;
                }
                // Get /AP dict.
                let ap = match dict.get(b"AP").ok() {
                    Some(Object::Dictionary(ap)) => Some(ap.clone()),
                    Some(Object::Reference(r)) => {
                        if let Some(Object::Dictionary(ap)) = doc.objects.get(r) {
                            Some(ap.clone())
                        } else {
                            None
                        }
                    }
                    _ => None,
                };
                let Some(ap) = ap else { continue };
                // Collect stream references from /N, /R, /D values.
                let mut refs = Vec::new();
                for key in &[b"N".as_slice(), b"R", b"D"] {
                    match ap.get(key).ok() {
                        Some(Object::Reference(r)) => refs.push(*r),
                        Some(Object::Dictionary(sub)) => {
                            // Sub-appearance states dict: values are stream refs.
                            for (_, v) in sub.iter() {
                                if let Object::Reference(r) = v {
                                    refs.push(*r);
                                }
                            }
                        }
                        _ => {}
                    }
                }
                refs
            }
            _ => continue,
        };
        ap_stream_ids.extend(ap_refs);
    }

    // Deduplicate.
    ap_stream_ids.sort();
    ap_stream_ids.dedup();

    let name_str = String::from_utf8_lossy(name).to_string();
    for ap_id in ap_stream_ids {
        // Check if the AP stream is actually a stream.
        let is_stream = matches!(doc.objects.get(&ap_id), Some(Object::Stream(_)));
        if !is_stream {
            continue;
        }

        // Check if it has Resources (either referenced or inline).
        let res_ref_id = {
            if let Some(Object::Stream(stream)) = doc.objects.get(&ap_id) {
                match stream.dict.get(b"Resources").ok() {
                    Some(Object::Reference(id)) => Some(*id),
                    _ => None,
                }
            } else {
                None
            }
        };

        if let Some(res_ref_id) = res_ref_id {
            if let Some(Object::Dictionary(ref mut res)) = doc.objects.get_mut(&res_ref_id) {
                let mut cs_dict = match res.get(b"ColorSpace") {
                    Ok(Object::Dictionary(d)) => d.clone(),
                    _ => lopdf::Dictionary::new(),
                };
                if !cs_dict.has(name) {
                    cs_dict.set(name_str.clone(), Object::Reference(cs_id));
                    res.set("ColorSpace", Object::Dictionary(cs_dict));
                }
            }
        } else if let Some(Object::Stream(ref mut stream)) = doc.objects.get_mut(&ap_id) {
            let mut res = match stream.dict.get(b"Resources") {
                Ok(Object::Dictionary(d)) => d.clone(),
                _ => lopdf::Dictionary::new(),
            };
            let mut cs_dict = match res.get(b"ColorSpace") {
                Ok(Object::Dictionary(d)) => d.clone(),
                _ => lopdf::Dictionary::new(),
            };
            if !cs_dict.has(name) {
                cs_dict.set(name_str.clone(), Object::Reference(cs_id));
                res.set("ColorSpace", Object::Dictionary(cs_dict));
                stream.dict.set("Resources", Object::Dictionary(res));
            }
        }
    }
}

/// Replace `/ColorSpace /DeviceCMYK` and `/ColorSpace /DeviceRGB` in Shading dicts
/// and `/CS /DeviceCMYK|DeviceRGB` in transparency Group dicts with ICCBased references.
/// These deep structures are not covered by the Default* resource fallback mechanism.
fn fix_device_colorspaces_in_deep_structures(
    doc: &mut Document,
    cmyk_cs_id: Option<ObjectId>,
    rgb_cs_id: Option<ObjectId>,
) {
    // Helper: map a device colorspace name to its ICCBased replacement.
    //
    // `None` means the census found no use of that family, so there is nothing
    // here to substitute: every name this function reads is a name in the
    // object graph, and the census reads the same graph.
    let replacement = |cs_name: &str| -> Option<ObjectId> {
        match cs_name {
            "DeviceCMYK" => cmyk_cs_id,
            "DeviceRGB" => rgb_cs_id,
            _ => None,
        }
    };

    // Helper: resolve a device colorspace from a dict key, handling both
    // direct Name values and references to Name objects.
    let resolve_device_cs =
        |dict: &lopdf::Dictionary, key: &[u8], doc: &Document| -> Option<String> {
            match dict.get(key).ok() {
                Some(Object::Name(n)) => {
                    let name = String::from_utf8_lossy(n).to_string();
                    if name == "DeviceCMYK" || name == "DeviceRGB" {
                        Some(name)
                    } else {
                        None
                    }
                }
                Some(Object::Reference(ref_id)) => {
                    // Dereference: the referenced object may be a bare Name.
                    match doc.objects.get(ref_id) {
                        Some(Object::Name(n)) => {
                            let name = String::from_utf8_lossy(n).to_string();
                            if name == "DeviceCMYK" || name == "DeviceRGB" {
                                Some(name)
                            } else {
                                None
                            }
                        }
                        _ => None,
                    }
                }
                _ => None,
            }
        };

    let ids: Vec<ObjectId> = doc.objects.keys().copied().collect();

    for id in ids {
        let obj = match doc.objects.get(&id) {
            Some(o) => o,
            None => continue,
        };

        match obj {
            Object::Dictionary(dict) => {
                // Shading dicts have /ShadingType and may have a device ColorSpace.
                if dict.get(b"ShadingType").is_ok() {
                    if let Some(repl) =
                        resolve_device_cs(dict, b"ColorSpace", doc).and_then(|n| replacement(&n))
                    {
                        if let Some(Object::Dictionary(ref mut d)) = doc.objects.get_mut(&id) {
                            d.set("ColorSpace", Object::Reference(repl));
                        }
                        continue;
                    }
                }

                // ShadingPattern (PatternType=2) with an inline /Shading dict
                // whose /ColorSpace is a device colour space. The inline shading
                // is not a top-level object, so it isn't reached by the
                // ShadingType check above. Fixes #479 (gen-188: 125 failures).
                if dict.get(b"PatternType").ok().and_then(|o| o.as_i64().ok()) == Some(2) {
                    let inline_repl = match dict.get(b"Shading").ok() {
                        Some(Object::Dictionary(shading)) => {
                            resolve_device_cs(shading, b"ColorSpace", doc)
                                .and_then(|n| replacement(&n))
                        }
                        _ => None,
                    };
                    if let Some(repl) = inline_repl {
                        if let Some(Object::Dictionary(ref mut d)) = doc.objects.get_mut(&id) {
                            if let Ok(Object::Dictionary(ref mut shading)) = d.get_mut(b"Shading") {
                                shading.set("ColorSpace", Object::Reference(repl));
                            }
                        }
                    }
                }
            }
            Object::Stream(stream) => {
                let dict = &stream.dict;

                // Shading streams with device ColorSpace.
                if dict.get(b"ShadingType").is_ok() {
                    if let Some(repl) =
                        resolve_device_cs(dict, b"ColorSpace", doc).and_then(|n| replacement(&n))
                    {
                        if let Some(Object::Stream(ref mut s)) = doc.objects.get_mut(&id) {
                            s.dict.set("ColorSpace", Object::Reference(repl));
                        }
                        continue;
                    }
                }

                // Group dicts on XObject streams: /Group << /CS /DeviceCMYK|DeviceRGB >>
                let group_repl = if let Ok(Object::Dictionary(group)) = dict.get(b"Group") {
                    resolve_device_cs(group, b"CS", doc).and_then(|n| replacement(&n))
                } else {
                    None
                };
                if let Some(repl) = group_repl {
                    if let Some(Object::Stream(ref mut s)) = doc.objects.get_mut(&id) {
                        if let Ok(Object::Dictionary(ref mut group)) = s.dict.get_mut(b"Group") {
                            group.set("CS", Object::Reference(repl));
                        }
                    }
                    continue;
                }

                // Pattern streams with device ColorSpace.
                let is_pattern = get_name(dict, b"Type").as_deref() == Some("Pattern")
                    || dict.get(b"PatternType").is_ok();
                if is_pattern {
                    if let Some(repl) = get_name(dict, b"ColorSpace").and_then(|n| replacement(&n))
                    {
                        if let Some(Object::Stream(ref mut s)) = doc.objects.get_mut(&id) {
                            s.dict.set("ColorSpace", Object::Reference(repl));
                        }
                        continue;
                    }
                }

                // Image XObject streams with a device ColorSpace name.
                // Default* resources only substitute device CS in content-stream operators
                // (k/K/rg/RG etc.), not in XObject stream dict /ColorSpace entries.
                // Replace directly so veraPDF 6.2.3.3 is satisfied. Fixes #481.
                let is_image = get_name(dict, b"Subtype").as_deref() == Some("Image");
                if is_image {
                    if let Some(repl) = get_name(dict, b"ColorSpace").and_then(|n| replacement(&n))
                    {
                        if let Some(Object::Stream(ref mut s)) = doc.objects.get_mut(&id) {
                            s.dict.set("ColorSpace", Object::Reference(repl));
                        }
                    }
                }
            }
            _ => {}
        }
    }

    // Handle Group dicts stored as references from stream dicts.
    let ids2: Vec<ObjectId> = doc.objects.keys().copied().collect();
    for id in ids2 {
        let group_ref_id = {
            let obj = match doc.objects.get(&id) {
                Some(o) => o,
                None => continue,
            };
            match obj {
                Object::Stream(stream) => match stream.dict.get(b"Group").ok() {
                    Some(Object::Reference(gid)) => Some(*gid),
                    _ => None,
                },
                _ => None,
            }
        };
        if let Some(gid) = group_ref_id {
            let repl = if let Some(Object::Dictionary(group)) = doc.objects.get(&gid) {
                resolve_device_cs(group, b"CS", doc).and_then(|n| replacement(&n))
            } else {
                None
            };
            if let Some(repl) = repl {
                if let Some(Object::Dictionary(ref mut group)) = doc.objects.get_mut(&gid) {
                    group.set("CS", Object::Reference(repl));
                }
            }
        }
    }

    // Handle Pattern dicts (non-stream).
    let ids3: Vec<ObjectId> = doc.objects.keys().copied().collect();
    for id in ids3 {
        let repl = if let Some(Object::Dictionary(dict)) = doc.objects.get(&id) {
            let is_pattern = get_name(dict, b"Type").as_deref() == Some("Pattern")
                || dict.get(b"PatternType").is_ok();
            if is_pattern {
                get_name(dict, b"ColorSpace").and_then(|n| replacement(&n))
            } else {
                None
            }
        } else {
            None
        };
        if let Some(repl) = repl {
            if let Some(Object::Dictionary(ref mut dict)) = doc.objects.get_mut(&id) {
                dict.set("ColorSpace", Object::Reference(repl));
            }
        }
    }

    // Fix DeviceN/NChannel colorspaces: replace DeviceCMYK/DeviceRGB in the
    // alternate colorspace and in the Process/ColorSpace attribute (6.2.4.3:3).
    fix_devicen_process_colors(doc, cmyk_cs_id, rgb_cs_id);

    // Ensure all DeviceN spot colorants have entries in the Colorants dictionary.
    // This must run AFTER fix_devicen_process_colors which may rebuild attrs dicts
    // and lose Colorants entries that were added earlier by fix_devicen_colorants.
    ensure_devicen_colorants(doc);
}

/// Ensure all DeviceN/NChannel spot colorants have Colorants dict entries.
/// Scans all DeviceN array objects, identifies spot color names (not process
/// colors like Cyan/Magenta/Yellow/Black/None), and adds missing Colorants
/// entries to the attributes dict.
fn ensure_devicen_colorants(doc: &mut Document) {
    // Only Cyan/Magenta/Yellow/Black and None/All are universally "process".
    // Red/Green/Blue are only process in RGB alternate spaces but are spot
    // colors in CMYK alternate spaces.  We exclude them from the default
    // process list to avoid missing Colorants entries for spot "Blue" etc.
    let process_names: &[&[u8]] = &[b"Cyan", b"Magenta", b"Yellow", b"Black", b"None", b"All"];

    let ids: Vec<ObjectId> = doc.objects.keys().copied().collect();
    for id in ids {
        // Read DeviceN array info
        let info = {
            let Some(Object::Array(arr)) = doc.objects.get(&id) else {
                continue;
            };
            if arr.len() < 4 {
                continue;
            }
            let is_dn = matches!(&arr[0], Object::Name(n) if n == b"DeviceN" || n == b"NChannel");
            if !is_dn {
                continue;
            }

            // Get spot color names
            let names: Vec<Vec<u8>> = match &arr[1] {
                Object::Array(na) => na
                    .iter()
                    .filter_map(|o| {
                        if let Object::Name(n) = o {
                            Some(n.clone())
                        } else {
                            None
                        }
                    })
                    .collect(),
                _ => continue,
            };
            let spots: Vec<Vec<u8>> = names
                .into_iter()
                .filter(|n| !process_names.contains(&n.as_slice()))
                .collect();
            if spots.is_empty() {
                continue;
            }

            // Get alternateCS and tintTransform for building Separation entries
            let alt = arr.get(2).cloned();
            let tint = arr.get(3).cloned();

            // Get attrs dict ref
            let attrs_ref = if arr.len() > 4 {
                match &arr[4] {
                    Object::Reference(r) => Some(*r),
                    _ => None,
                }
            } else {
                None
            };

            (spots, alt, tint, attrs_ref)
        };

        let (spots, alt, tint, attrs_ref) = info;
        let (Some(alt_cs), Some(tint_fn)) = (alt, tint) else {
            continue;
        };

        if let Some(attrs_id) = attrs_ref {
            // Get or create Colorants dict inside the attrs
            let existing_colorants: Option<lopdf::Dictionary> = {
                if let Some(Object::Dictionary(d)) = doc.objects.get(&attrs_id) {
                    match d.get(b"Colorants").ok() {
                        Some(Object::Dictionary(cd)) => Some(cd.clone()),
                        Some(Object::Reference(r)) => {
                            if let Some(Object::Dictionary(cd)) = doc.objects.get(r) {
                                Some(cd.clone())
                            } else {
                                None
                            }
                        }
                        _ => None,
                    }
                } else {
                    None
                }
            };

            let mut cd = existing_colorants.unwrap_or_default();
            let mut added = false;
            for name in &spots {
                if !cd.has(name.as_slice()) {
                    let sep = Object::Array(vec![
                        Object::Name(b"Separation".to_vec()),
                        Object::Name(name.clone()),
                        alt_cs.clone(),
                        tint_fn.clone(),
                    ]);
                    let key = String::from_utf8_lossy(name).to_string();
                    cd.set(key, sep);
                    added = true;
                }
            }
            if added {
                if let Some(Object::Dictionary(ref mut attrs)) = doc.objects.get_mut(&attrs_id) {
                    attrs.set("Colorants", Object::Dictionary(cd));
                }
            }
        }
        // For DeviceN without attrs ref: create inline attrs dict with Colorants
        else {
            let mut cd = lopdf::Dictionary::new();
            for name in &spots {
                let sep = Object::Array(vec![
                    Object::Name(b"Separation".to_vec()),
                    Object::Name(name.clone()),
                    alt_cs.clone(),
                    tint_fn.clone(),
                ]);
                let key = String::from_utf8_lossy(name).to_string();
                cd.set(key, sep);
            }
            let attrs = lopdf::dictionary! {
                "Colorants" => Object::Dictionary(cd),
            };
            if let Some(Object::Array(ref mut arr)) = doc.objects.get_mut(&id) {
                if arr.len() == 4 {
                    arr.push(Object::Dictionary(attrs));
                }
            }
        }
    }
}

/// Fix DeviceN/NChannel colorspace arrays that reference DeviceCMYK or DeviceRGB
/// as their alternate colorspace or Process/ColorSpace attribute.
fn fix_devicen_process_colors(
    doc: &mut Document,
    cmyk_cs_id: Option<ObjectId>,
    rgb_cs_id: Option<ObjectId>,
) {
    let replacement = |name: &[u8]| -> Option<ObjectId> {
        if name == b"DeviceCMYK" {
            cmyk_cs_id
        } else if name == b"DeviceRGB" {
            rgb_cs_id
        } else {
            None
        }
    };

    // Pass 1: Fix DeviceN arrays stored as objects.
    // DeviceN array: [/DeviceN [names] alternateCS tintTransform attributesDict?]
    // NChannel is the same structure with /NChannel as the first element.
    let ids: Vec<ObjectId> = doc.objects.keys().copied().collect();
    for id in ids {
        let fix = {
            let Some(Object::Array(arr)) = doc.objects.get(&id) else {
                continue;
            };
            if arr.len() < 4 {
                continue;
            }
            let is_devicen =
                matches!(&arr[0], Object::Name(n) if n == b"DeviceN" || n == b"NChannel");
            if !is_devicen {
                continue;
            }
            // Check alternate colorspace (index 2).
            // The alternate may be a direct Name or a Reference to a Name object.
            let alt_repl = match &arr[2] {
                Object::Name(n) => replacement(n),
                Object::Reference(ref_id) => match doc.objects.get(ref_id) {
                    Some(Object::Name(n)) => replacement(n),
                    _ => None,
                },
                _ => None,
            };
            // Check attributes dict (index 4 if present) for Process/ColorSpace.
            // The attributes dict may be inline or a reference.
            let process_repl = if arr.len() > 4 {
                let attrs_dict = match &arr[4] {
                    Object::Dictionary(d) => Some(d),
                    Object::Reference(ref_id) => {
                        if let Some(Object::Dictionary(d)) = doc.objects.get(ref_id) {
                            Some(d)
                        } else {
                            None
                        }
                    }
                    _ => None,
                };
                if let Some(attrs) = attrs_dict {
                    // Process entry may also be inline or a reference.
                    let process_dict = match attrs.get(b"Process").ok() {
                        Some(Object::Dictionary(d)) => Some(d),
                        Some(Object::Reference(ref_id)) => {
                            if let Some(Object::Dictionary(d)) = doc.objects.get(ref_id) {
                                Some(d)
                            } else {
                                None
                            }
                        }
                        _ => None,
                    };
                    if let Some(process) = process_dict {
                        match process.get(b"ColorSpace").ok() {
                            Some(Object::Name(n)) => replacement(n),
                            _ => None,
                        }
                    } else {
                        None
                    }
                } else {
                    None
                }
            } else {
                None
            };
            (alt_repl, process_repl)
        };
        let (alt_repl, process_repl) = fix;
        if let Some(repl) = alt_repl {
            if let Some(Object::Array(ref mut arr)) = doc.objects.get_mut(&id) {
                arr[2] = Object::Reference(repl);
            }
        }
        if let Some(repl) = process_repl {
            if let Some(Object::Array(ref mut arr)) = doc.objects.get_mut(&id) {
                if arr.len() > 4 {
                    if let Object::Dictionary(ref mut attrs) = arr[4] {
                        if let Ok(Object::Dictionary(ref mut process)) = attrs.get_mut(b"Process") {
                            process.set("ColorSpace", Object::Reference(repl));
                        }
                    }
                }
            }
        }
    }

    // Pass 2: Fix attributes dicts stored as separate referenced objects.
    // Some DeviceN arrays reference the attributes dict by ObjectId.
    // The attributes dict may have Process as inline dict or reference.
    let ids2: Vec<ObjectId> = doc.objects.keys().copied().collect();
    for id in ids2 {
        let repl = {
            let Some(Object::Dictionary(dict)) = doc.objects.get(&id) else {
                continue;
            };
            // Check if this dict has a Process entry (inline dict).
            if let Ok(Object::Dictionary(process)) = dict.get(b"Process") {
                match process.get(b"ColorSpace").ok() {
                    Some(Object::Name(n)) => replacement(n),
                    _ => None,
                }
            } else {
                None
            }
        };
        if let Some(repl) = repl {
            if let Some(Object::Dictionary(ref mut dict)) = doc.objects.get_mut(&id) {
                if let Ok(Object::Dictionary(ref mut process)) = dict.get_mut(b"Process") {
                    process.set("ColorSpace", Object::Reference(repl));
                }
            }
        }
    }

    // Pass 3: Fix Process dicts referenced by ID from attributes dicts.
    // Pattern: attributes dict has /Process <ref> -> Process dict has /ColorSpace /DeviceCMYK.
    // Collect all Process reference IDs from attributes dicts.
    // Use HashSet for deduplication to avoid O(n²) Vec::contains over all objects. (#perf)
    let ids3: Vec<ObjectId> = doc.objects.keys().copied().collect();
    let mut process_ref_ids: std::collections::HashSet<ObjectId> = std::collections::HashSet::new();
    for id in &ids3 {
        if let Some(Object::Dictionary(dict)) = doc.objects.get(id) {
            if let Ok(Object::Reference(process_id)) = dict.get(b"Process") {
                process_ref_ids.insert(*process_id);
            }
        }
    }

    // Fix the referenced Process dicts directly.
    for process_id in process_ref_ids {
        let repl = if let Some(Object::Dictionary(process)) = doc.objects.get(&process_id) {
            match process.get(b"ColorSpace").ok() {
                Some(Object::Name(n)) => replacement(n),
                _ => None,
            }
        } else {
            None
        };
        if let Some(repl) = repl {
            if let Some(Object::Dictionary(ref mut process)) = doc.objects.get_mut(&process_id) {
                process.set("ColorSpace", Object::Reference(repl));
            }
        }
    }
}

/// Replace DeviceCMYK/DeviceRGB alternate colorspaces inside Separation arrays
/// with ICCBased references. Fixes 6.2.4.3:3 (DeviceCMYK used without CMYK
/// output intent) for Separation alternates. Also helps 6.2.4.4:2 by ensuring
/// all occurrences of a Separation with the same name have an identical alternate
/// object reference rather than a bare device colorspace name.
fn fix_separation_device_alternates(
    doc: &mut Document,
    cmyk_cs_id: Option<ObjectId>,
    rgb_cs_id: Option<ObjectId>,
) {
    let replacement = |name: &[u8]| -> Option<ObjectId> {
        if name == b"DeviceCMYK" {
            cmyk_cs_id
        } else if name == b"DeviceRGB" {
            rgb_cs_id
        } else {
            None
        }
    };

    // Collect IDs to fix first, then mutate (two-pass for borrow safety).
    let ids: Vec<ObjectId> = doc.objects.keys().copied().collect();
    let mut to_fix: Vec<(ObjectId, ObjectId)> = Vec::new();
    for id in ids {
        let repl = if let Some(Object::Array(arr)) = doc.objects.get(&id) {
            if arr.len() >= 4 {
                if let Object::Name(cs_type) = &arr[0] {
                    if cs_type == b"Separation" {
                        match &arr[2] {
                            Object::Name(n) => replacement(n),
                            Object::Reference(ref_id) => match doc.objects.get(ref_id) {
                                Some(Object::Name(n)) => replacement(n),
                                _ => None,
                            },
                            _ => None,
                        }
                    } else {
                        None
                    }
                } else {
                    None
                }
            } else {
                None
            }
        } else {
            None
        };
        if let Some(repl) = repl {
            to_fix.push((id, repl));
        }
    }
    for (id, repl) in to_fix {
        if let Some(Object::Array(ref mut arr)) = doc.objects.get_mut(&id) {
            arr[2] = Object::Reference(repl);
        }
    }
}

/// Normalize Separation colorspaces so all with the same name use identical
/// alternateSpace and tintTransform (PDF/A rule 6.2.4.4:2).
fn normalize_separation_colorspaces(doc: &mut Document) -> usize {
    use std::collections::{HashMap, HashSet};

    // Separation arrays referenced outside the currently loaded object set are
    // still considered for 6.2.4.4:2 consistency checks.
    materialize_all_objects(doc);

    // Phase 1: Collect all Separation arrays across all objects.
    // A Separation array is: [/Separation name alternateCS tintTransform]
    // We record (ObjectId, name) → (alternateCS, tintTransform).
    let mut by_name: HashMap<Vec<u8>, Vec<(ObjectId, Object, Object)>> = HashMap::new();
    let mut visited_refs: HashSet<ObjectId> = HashSet::new();

    for (&id, obj) in &doc.objects {
        collect_separations_recursive(doc, id, obj, &mut by_name, &mut visited_refs, 0);
    }

    // Phase 2: For each name with multiple Separation array objects, pick a
    // canonical object and redirect all other references to it. veraPDF checks
    // 6.2.4.4:2 consistency by object identity: two Separation colorspaces with
    // the same name must be THE SAME PDF object (same object number), not just
    // equal-content objects. So we must make every /ColorSpace key that pointed
    // to a non-canonical Separation array point to the canonical one instead.
    //
    // Additionally, unify the tintTransform within the canonical object: if the
    // canonical has a Reference tintTransform, keep it; if it's inline, promote
    // it to a standalone object so it can be shared via reference too.

    // Build: for each spot-color name → canonical object ID, list of non-canonical IDs.
    let mut redirects: Vec<(ObjectId, ObjectId)> = Vec::new(); // (old_id, new_id) for ref redirect
    let mut content_fixes: Vec<(ObjectId, Vec<u8>, Object, Object)> = Vec::new();

    for (name, entries) in &by_name {
        if entries.len() <= 1 {
            continue;
        }

        // Deduplicate by object ID: the same Separation object may be recorded
        // multiple times when encountered both directly and via reference following.
        let mut seen_ids: HashSet<ObjectId> = HashSet::new();
        let mut unique_entries: Vec<&(ObjectId, Object, Object)> = entries
            .iter()
            .filter(|(id, _, _)| seen_ids.insert(*id))
            .collect();

        if unique_entries.len() <= 1 {
            continue;
        }

        // Sort by object ID (lowest first) for deterministic canonical selection.
        // Using the lowest ID as canonical guarantees that the redirects always
        // point from higher-numbered objects to a lower-numbered one. This avoids
        // the case where the "canonical" is already the object that all references
        // point to, making the redirect a no-op.
        unique_entries.sort_by_key(|(id, _, _)| *id);

        let (canon_id, canon_alt, canon_tint) = unique_entries[0];

        // Promote the canonical tintTransform to a standalone object if it isn't
        // already a reference. This gives us a stable ObjectId to share.
        let canonical_tint_ref: Object = match canon_tint {
            Object::Reference(_) => canon_tint.clone(),
            other => {
                let new_id = doc.add_object(other.clone());
                Object::Reference(new_id)
            }
        };

        // Update ALL Separation objects for this name (canonical + non-canonical)
        // to have the same alternateSpace and tintTransform. veraPDF 6.2.4.4:2
        // scans ALL objects in the file, including unreferenced ones, so we must
        // make even non-canonical objects content-identical to the canonical.
        for (obj_id, _, _) in &unique_entries {
            content_fixes.push((
                *obj_id,
                name.clone(),
                canon_alt.clone(),
                canonical_tint_ref.clone(),
            ));
        }

        // All non-canonical objects: redirect document references to the canon.
        for (non_canon_id, _, _) in &unique_entries[1..] {
            redirects.push((*non_canon_id, *canon_id));
        }
    }

    // Phase 3: Update canonical Separation array content.
    let mut seen: HashSet<(ObjectId, Vec<u8>)> = HashSet::new();
    let mut count = 0usize;
    for (id, name, alt, tint) in content_fixes {
        if seen.insert((id, name.clone())) {
            if let Some(obj) = doc.objects.get_mut(&id) {
                fix_separation_recursive(obj, &name, &alt, &tint, 0);
                count += 1;
            }
        }
    }

    // Phase 4: Redirect all document references from non-canonical → canonical.
    // Scan every object and replace Reference(old_id) with Reference(new_id).
    if !redirects.is_empty() {
        let all_ids: Vec<ObjectId> = doc.objects.keys().copied().collect();
        for obj_id in all_ids {
            if let Some(obj) = doc.objects.get_mut(&obj_id) {
                for (old_id, new_id) in &redirects {
                    redirect_references_recursive(obj, *old_id, *new_id, 0);
                }
            }
        }
        count += redirects.len();
    }

    // Phase 5: Delete non-canonical Separation objects from the document.
    // veraPDF scans ALL objects (including unreferenced ones) for 6.2.4.4:2
    // consistency. After redirecting references, non-canonical Separation objects
    // are unreferenced, but veraPDF still finds them. Remove them entirely.
    for (old_id, _new_id) in &redirects {
        doc.objects.remove(old_id);
    }

    count
}

// Depth limit for inline-object recursion — prevents stack overflow on
// pathological PDFs with thousands of nested arrays/dicts. (#oracle-gen-stackoverflow)
const MAX_OBJECT_DEPTH: usize = 128;

fn collect_separations_recursive(
    doc: &Document,
    id: ObjectId,
    obj: &Object,
    map: &mut std::collections::HashMap<Vec<u8>, Vec<(ObjectId, Object, Object)>>,
    visited_refs: &mut std::collections::HashSet<ObjectId>,
    depth: usize,
) {
    if depth > MAX_OBJECT_DEPTH {
        return;
    }
    match obj {
        Object::Array(arr) => {
            if arr.len() >= 4 {
                if let Object::Name(cs_type) = &arr[0] {
                    if cs_type == b"Separation" {
                        if let Object::Name(name) = &arr[1] {
                            map.entry(normalize_spot_name(name)).or_default().push((
                                id,
                                arr[2].clone(),
                                arr[3].clone(),
                            ));
                        }
                    }
                }
            }
            for item in arr {
                collect_separations_recursive(doc, id, item, map, visited_refs, depth + 1);
            }
        }
        Object::Dictionary(dict) => {
            for (_, val) in dict.iter() {
                collect_separations_recursive(doc, id, val, map, visited_refs, depth + 1);
            }
        }
        Object::Stream(stream) => {
            for (_, val) in stream.dict.iter() {
                collect_separations_recursive(doc, id, val, map, visited_refs, depth + 1);
            }
        }
        Object::Reference(ref_id) if visited_refs.insert(*ref_id) => {
            if let Ok(resolved) = doc.get_object(*ref_id) {
                collect_separations_recursive(doc, *ref_id, resolved, map, visited_refs, depth + 1);
            }
        }
        _ => {}
    }
}

/// Recursively replace all Reference(old_id) with Reference(new_id) in an object tree.
fn redirect_references_recursive(
    obj: &mut Object,
    old_id: ObjectId,
    new_id: ObjectId,
    depth: usize,
) {
    if depth > MAX_OBJECT_DEPTH {
        return;
    }
    match obj {
        Object::Reference(r) if *r == old_id => {
            *r = new_id;
        }
        Object::Array(arr) => {
            for item in arr.iter_mut() {
                redirect_references_recursive(item, old_id, new_id, depth + 1);
            }
        }
        Object::Dictionary(dict) => {
            for (_, val) in dict.iter_mut() {
                redirect_references_recursive(val, old_id, new_id, depth + 1);
            }
        }
        Object::Stream(stream) => {
            for (_, val) in stream.dict.iter_mut() {
                redirect_references_recursive(val, old_id, new_id, depth + 1);
            }
        }
        _ => {}
    }
}

fn fix_separation_recursive(
    obj: &mut Object,
    name: &[u8],
    alt: &Object,
    tint: &Object,
    depth: usize,
) {
    if depth > MAX_OBJECT_DEPTH {
        return;
    }
    match obj {
        Object::Array(arr) => {
            if arr.len() >= 4 {
                if let Object::Name(cs_type) = &arr[0] {
                    if cs_type == b"Separation" {
                        if let Object::Name(n) = &arr[1] {
                            if normalize_spot_name(n) == name {
                                arr[2] = alt.clone();
                                arr[3] = tint.clone();
                            }
                        }
                    }
                }
            }
            for item in arr.iter_mut() {
                fix_separation_recursive(item, name, alt, tint, depth + 1);
            }
        }
        Object::Dictionary(dict) => {
            for (_, val) in dict.iter_mut() {
                fix_separation_recursive(val, name, alt, tint, depth + 1);
            }
        }
        Object::Stream(stream) => {
            for (_, val) in stream.dict.iter_mut() {
                fix_separation_recursive(val, name, alt, tint, depth + 1);
            }
        }
        _ => {}
    }
}

/// Normalize a PDF Name object for logical comparison.
///
/// PDF names may encode bytes using `#XX` hex escapes. For clause 6.2.4.4:2,
/// names that differ only by escape form should be treated as the same spot
/// color name.
fn normalize_spot_name(name: &[u8]) -> Vec<u8> {
    let mut decoded = Vec::with_capacity(name.len());
    let mut i = 0usize;
    while i < name.len() {
        if name[i] == b'#' && i + 2 < name.len() {
            let h1 = name[i + 1];
            let h2 = name[i + 2];
            let hi = (h1 as char).to_digit(16);
            let lo = (h2 as char).to_digit(16);
            if let (Some(hi), Some(lo)) = (hi, lo) {
                decoded.push(((hi << 4) | lo) as u8);
                i += 3;
                continue;
            }
        }
        decoded.push(name[i]);
        i += 1;
    }

    // Canonicalize ASCII names: trim/collapse whitespace and fold to upper-case
    // so escape/case variants of the same spot name group together.
    let mut out = Vec::with_capacity(decoded.len());
    let mut prev_space = true;
    for b in decoded {
        let is_space = matches!(b, b' ' | b'\t' | b'\r' | b'\n');
        if is_space {
            if !prev_space {
                out.push(b' ');
            }
            prev_space = true;
            continue;
        }
        prev_space = false;
        out.push(b.to_ascii_uppercase());
    }
    if out.last() == Some(&b' ') {
        out.pop();
    }
    out
}

/// Fix overprint mode: set OPM to 0 when overprinting is enabled (PDF/A rule 6.2.4.2:2).
///
/// When ICCBased CMYK is in use, OPM=1 is forbidden if overprinting is on.
/// Safest fix: set OPM to 0 in all ExtGState dictionaries.
fn fix_overprint_mode(doc: &mut Document) -> usize {
    let mut count = 0;
    let ids: Vec<ObjectId> = doc.objects.keys().copied().collect();
    for id in ids {
        let needs_fix = if let Some(Object::Dictionary(dict)) = doc.objects.get(&id) {
            matches!(dict.get(b"OPM").ok(), Some(Object::Integer(1)))
        } else {
            false
        };
        if needs_fix {
            if let Some(Object::Dictionary(ref mut dict)) = doc.objects.get_mut(&id) {
                dict.set("OPM", Object::Integer(0));
                count += 1;
            }
        }
    }
    count
}

/// Fix ICCBased colorspace streams: ensure /N matches the profile header and
/// replace invalid ICC profiles (rule 6.2.4.2:1).
///
/// For each ICCBased stream:
/// 1. Decompress the stream content to read the actual ICC header.
/// 2. If /N doesn't match the profile's color space, update /N.
/// 3. If the ICC profile header is invalid (garbage device class, color space, or version),
///    replace the entire profile with our known-good sRGB or CMYK profile.
fn fix_iccbased_n_value(doc: &mut Document) -> usize {
    // Pre-generate replacement profiles.
    let srgb_profile = srgb_icc_profile_bytes();
    let cmyk_profile = cmyk_icc_profile_bytes();
    let gray_profile = gray_icc_profile_bytes();

    let mut count = 0;
    let ids: Vec<ObjectId> = doc.objects.keys().copied().collect();
    for id in ids {
        let action = if let Some(Object::Stream(stream)) = doc.objects.get(&id) {
            // Only process streams that have /N (ICCBased profile indicator).
            let declared_n = match stream.dict.get(b"N").ok() {
                Some(Object::Integer(n)) => *n,
                _ => continue,
            };

            // Decompress the stream content to read the actual ICC header.
            // If no filters are present, decompressed_content returns empty;
            // in that case the raw content IS the profile data.
            let icc_bytes = {
                let decompressed = stream.decompressed_content().unwrap_or_default();
                if decompressed.is_empty() && !stream.content.is_empty() {
                    stream.content.clone()
                } else {
                    decompressed
                }
            };

            if icc_bytes.len() < 128 {
                // ICC header must be at least 128 bytes. Replace.
                IccAction::Replace(declared_n)
            } else {
                // Validate the ICC profile header.
                let cs_sig = &icc_bytes[16..20];
                let device_class = &icc_bytes[12..16];
                let acsp_sig = &icc_bytes[36..40];
                let version_major = icc_bytes[8];

                let cs_valid = matches!(
                    cs_sig,
                    b"GRAY"
                        | b"RGB "
                        | b"CMYK"
                        | b"Lab "
                        | b"XYZ "
                        | b"Luv "
                        | b"YCbr"
                        | b"Yxy "
                        | b"HSV "
                        | b"HLS "
                        | b"CMY "
                );
                let class_valid = matches!(
                    device_class,
                    b"scnr" | b"mntr" | b"prtr" | b"link" | b"spac" | b"abst" | b"nmcl"
                );
                let acsp_valid = acsp_sig == b"acsp";
                let version_valid = version_major < 5;

                if cs_valid && class_valid && acsp_valid && version_valid {
                    // Profile is valid. Check /N consistency.
                    let expected_n: i64 = match cs_sig {
                        b"GRAY" => 1,
                        b"RGB " | b"Lab " => 3,
                        b"CMYK" => 4,
                        _ => declared_n,
                    };
                    if declared_n != expected_n {
                        IccAction::FixN(expected_n)
                    } else {
                        IccAction::None
                    }
                } else {
                    // Invalid ICC profile — replace.
                    IccAction::Replace(declared_n)
                }
            }
        } else {
            IccAction::None
        };

        match action {
            IccAction::None => {}
            IccAction::FixN(n) => {
                if let Some(Object::Stream(ref mut stream)) = doc.objects.get_mut(&id) {
                    stream.dict.set("N", Object::Integer(n));
                    count += 1;
                }
            }
            IccAction::Replace(declared_n) => {
                if let Some(Object::Stream(ref mut stream)) = doc.objects.get_mut(&id) {
                    let replacement = match declared_n {
                        4 => cmyk_profile.clone(),
                        1 => gray_profile.clone(),
                        _ => srgb_profile.clone(),
                    };
                    stream.content = replacement;
                    // Remove compression filter since we store raw data.
                    stream.dict.remove(b"Filter");
                    stream.dict.remove(b"DecodeParms");
                    stream.dict.remove(b"F");
                    stream.dict.remove(b"FFilter");
                    stream.dict.remove(b"FDecodeParms");
                    let new_n = match declared_n {
                        4 => 4_i64,
                        1 => 1,
                        _ => 3,
                    };
                    stream.dict.set("N", Object::Integer(new_n));
                    stream.dict.set(
                        "Length",
                        Object::Integer(stream.content.len().min(i64::MAX as usize) as i64),
                    );
                    count += 1;
                }
            }
        }
    }
    count
}

/// Actions for ICC profile fixing.
enum IccAction {
    /// No action needed.
    None,
    /// Fix /N value to the given number.
    FixN(i64),
    /// Replace the entire ICC profile. i64 is the declared /N value.
    Replace(i64),
}

/// Minimal Gray ICC v2 profile (1-component).
fn gray_icc_profile_bytes() -> Vec<u8> {
    let total_size: u32 = 324;
    let mut p = Vec::with_capacity(total_size as usize);

    // === Header (128 bytes) ===
    p.extend_from_slice(&total_size.to_be_bytes());
    p.extend_from_slice(b"\0\0\0\0"); // preferred CMM
    p.extend_from_slice(&[2, 0x10, 0, 0]); // version 2.1.0
    p.extend_from_slice(b"mntr"); // device class: monitor
    p.extend_from_slice(b"GRAY"); // color space
    p.extend_from_slice(b"XYZ "); // PCS
    p.extend_from_slice(&[0u8; 12]); // date/time
    p.extend_from_slice(b"acsp"); // signature
    p.extend_from_slice(&[0u8; 4]); // platform
    p.extend_from_slice(&[0u8; 4]); // flags
    p.extend_from_slice(&[0u8; 4]); // manufacturer
    p.extend_from_slice(&[0u8; 4]); // model
    p.extend_from_slice(&[0u8; 8]); // device attributes
    p.extend_from_slice(&[0u8; 4]); // rendering intent
                                    // PCS illuminant D50
    p.extend_from_slice(&0x0000F6D6_u32.to_be_bytes());
    p.extend_from_slice(&0x00010000_u32.to_be_bytes());
    p.extend_from_slice(&0x0000D32D_u32.to_be_bytes());
    p.extend_from_slice(&[0u8; 4]); // creator
    p.extend_from_slice(&[0u8; 16]); // profile ID
    p.extend_from_slice(&[0u8; 128 - 100]); // reserved
    debug_assert_eq!(p.len(), 128);

    // === Tag table: 4 tags ===
    p.extend_from_slice(&4_u32.to_be_bytes());
    // 128 + 4 + 4*12 = 180 bytes for header + tag table

    let tags: &[(&[u8; 4], u32, u32)] = &[
        (b"desc", 180, 95),
        (b"wtpt", 276, 20),
        (b"cprt", 296, 12),
        (b"kTRC", 308, 14),
    ];
    for (sig, offset, size) in tags {
        p.extend_from_slice(*sig);
        p.extend_from_slice(&offset.to_be_bytes());
        p.extend_from_slice(&size.to_be_bytes());
    }
    debug_assert_eq!(p.len(), 180);

    // === desc tag (textDescriptionType) — 95 bytes ===
    p.extend_from_slice(b"desc");
    p.extend_from_slice(&[0u8; 4]);
    p.extend_from_slice(&5_u32.to_be_bytes()); // ASCII length incl null
    p.extend_from_slice(b"Gray\0");
    p.extend_from_slice(&[0u8; 4]); // Unicode language
    p.extend_from_slice(&[0u8; 4]); // Unicode count
    p.extend_from_slice(&[0u8; 2]); // ScriptCode code
    p.push(0); // ScriptCode count
    p.extend_from_slice(&[0u8; 67]); // ScriptCode string
    debug_assert_eq!(p.len(), 275);
    // Pad to offset 276 (4-byte alignment)
    p.push(0);
    debug_assert_eq!(p.len(), 276);

    // === wtpt (XYZType) — D50 ===
    p.extend_from_slice(b"XYZ ");
    p.extend_from_slice(&[0u8; 4]);
    p.extend_from_slice(&0x0000F6D6_i32.to_be_bytes());
    p.extend_from_slice(&0x00010000_i32.to_be_bytes());
    p.extend_from_slice(&0x0000D32D_i32.to_be_bytes());
    debug_assert_eq!(p.len(), 296);

    // === cprt ===
    p.extend_from_slice(b"text");
    p.extend_from_slice(&[0u8; 4]);
    p.extend_from_slice(b"CC0\0");
    debug_assert_eq!(p.len(), 308);

    // === kTRC (curveType with gamma 2.2) ===
    p.extend_from_slice(b"curv");
    p.extend_from_slice(&[0u8; 4]);
    p.extend_from_slice(&1_u32.to_be_bytes()); // count=1 means gamma value
    p.extend_from_slice(&[0x02, 0x33]); // gamma ~ 2.2
    debug_assert_eq!(p.len(), 322);
    p.extend_from_slice(&[0u8; 2]); // pad to 324
    debug_assert_eq!(p.len(), 324);

    p
}

fn is_device_dependent(name: &str) -> bool {
    matches!(name, "DeviceRGB" | "DeviceCMYK" | "DeviceGray")
}

fn resolve_colorspace_name(doc: &Document, obj: &Object) -> String {
    match obj {
        Object::Name(n) => String::from_utf8_lossy(n).to_string(),
        Object::Array(arr) if !arr.is_empty() => {
            if let Object::Name(n) = &arr[0] {
                String::from_utf8_lossy(n).to_string()
            } else {
                "Unknown".into()
            }
        }
        Object::Reference(id) => {
            if let Some(resolved) = doc.objects.get(id) {
                resolve_colorspace_name(doc, resolved)
            } else {
                "Unknown".into()
            }
        }
        _ => "Unknown".into(),
    }
}

fn get_name(dict: &lopdf::Dictionary, key: &[u8]) -> Option<String> {
    match dict.get(key).ok()? {
        Object::Name(n) => String::from_utf8(n.clone()).ok(),
        _ => None,
    }
}

fn get_catalog(doc: &Document) -> Option<&lopdf::Dictionary> {
    let root_ref = match doc.trailer.get(b"Root").ok()? {
        Object::Reference(id) => *id,
        _ => return None,
    };
    match doc.objects.get(&root_ref)? {
        Object::Dictionary(d) => Some(d),
        _ => None,
    }
}

fn get_catalog_id(doc: &Document) -> Result<ObjectId> {
    match doc.trailer.get(b"Root").ok() {
        Some(Object::Reference(id)) => Ok(*id),
        _ => Err(ManipError::Other("no Root in trailer".into())),
    }
}

fn count_pages(doc: &Document) -> usize {
    doc.objects
        .values()
        .filter(|obj| {
            if let Object::Dictionary(dict) = obj {
                get_name(dict, b"Type").as_deref() == Some("Page")
            } else {
                false
            }
        })
        .count()
}

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

    fn make_doc_with_device_rgb() -> Document {
        let mut doc = Document::with_version("1.7");
        let pages_id = doc.new_object_id();

        let content = Stream::new(dictionary! {}, b"BT /F1 12 Tf (Hello) Tj ET".to_vec());
        let content_id = doc.add_object(Object::Stream(content));

        let mut cs_dict = lopdf::Dictionary::new();
        cs_dict.set("CS1", Object::Name(b"DeviceRGB".to_vec()));

        let mut res = lopdf::Dictionary::new();
        res.set("ColorSpace", Object::Dictionary(cs_dict));

        let page = dictionary! {
            "Type" => "Page",
            "Parent" => Object::Reference(pages_id),
            "MediaBox" => Object::Array(vec![
                Object::Integer(0), Object::Integer(0),
                Object::Integer(612), Object::Integer(792),
            ]),
            "Contents" => Object::Reference(content_id),
            "Resources" => Object::Dictionary(res),
        };
        let page_id = doc.add_object(Object::Dictionary(page));

        let pages = dictionary! {
            "Type" => "Pages",
            "Count" => Object::Integer(1),
            "Kids" => Object::Array(vec![Object::Reference(page_id)]),
        };
        doc.objects.insert(pages_id, Object::Dictionary(pages));

        let catalog = dictionary! {
            "Type" => "Catalog",
            "Pages" => Object::Reference(pages_id),
        };
        let catalog_id = doc.add_object(Object::Dictionary(catalog));
        doc.trailer.set("Root", Object::Reference(catalog_id));

        doc
    }

    #[test]
    fn test_no_output_intent() {
        let doc = make_doc_with_device_rgb();
        assert!(!has_pdfa_output_intent(&doc));
    }

    #[test]
    fn test_add_output_intent() {
        let mut doc = make_doc_with_device_rgb();
        add_srgb_output_intent(&mut doc).unwrap();
        assert!(has_pdfa_output_intent(&doc));
    }

    #[test]
    fn test_find_device_colorspaces() {
        let doc = make_doc_with_device_rgb();
        let found = find_device_colorspaces(&doc);
        assert!(!found.is_empty());
        assert!(found[0].1.contains("DeviceRGB"));
    }

    #[test]
    fn normalization_characterizes_device_spaces_with_output_intent() {
        let mut doc = make_doc_with_device_rgb();
        let report = normalize_colorspaces(&mut doc).unwrap();
        assert!(!report.had_output_intent);
        assert!(report.output_intent_added);
        assert_eq!(report.pages_scanned, 1);
    }

    #[test]
    fn opaque_registration_paper_keeps_its_tint_transform_without_rgb_output_device() {
        let mut doc = make_doc_with_device_rgb();
        let tint = doc.add_object(dictionary! {"FunctionType"=>2,"Domain"=>vec![0.into(),1.into()],"C0"=>vec![1.into(),1.into(),1.into()],"C1"=>vec![0.into(),0.into(),0.into()],"N"=>1});
        let calrgb = doc.add_object(Object::Array(vec![
            "CalRGB".into(),
            dictionary! {"WhitePoint"=>vec![0.9505.into(),1.into(),1.089.into()]}.into(),
        ]));
        let separation = doc.add_object(Object::Array(vec![
            Object::Name(b"Separation".to_vec()),
            Object::Name(b"All".to_vec()),
            calrgb.into(),
            tint.into(),
        ]));
        let before = doc.objects[&tint].clone();
        let report = normalize_colorspaces(&mut doc).unwrap();
        assert!(!report.output_intent_added);
        assert!(!has_pdfa_output_intent(&doc));
        assert_eq!(doc.objects[&tint], before);
        assert_eq!(
            doc.get_object(separation).unwrap().as_array().unwrap()[1]
                .as_name()
                .unwrap(),
            b"All"
        );
        // Transparency still needs an explicit blending/output condition.
        doc.add_object(dictionary! {"Type"=>"ExtGState","ca"=>0.5});
        assert!(normalize_colorspaces(&mut doc).unwrap().output_intent_added);
    }

    #[test]
    fn cmyk_mixed_and_unresolved_registration_keep_the_output_condition() {
        for alternate in ["DeviceCMYK", "DeviceRGB", "UnknownColorSpace"] {
            let mut doc = make_doc_with_device_rgb();
            let calrgb = doc.add_object(Object::Array(vec![
                "CalRGB".into(),
                dictionary! {"WhitePoint"=>vec![0.9505.into(),1.into(),1.089.into()]}.into(),
            ]));
            let tint = doc.add_object(
                dictionary! {"FunctionType"=>2,"Domain"=>vec![0.into(),1.into()],"N"=>1},
            );
            doc.add_object(Object::Array(vec![
                "Separation".into(),
                "All".into(),
                calrgb.into(),
                tint.into(),
            ]));
            doc.add_object(Object::Array(vec![
                "Separation".into(),
                "All".into(),
                Object::Name(alternate.as_bytes().to_vec()),
                tint.into(),
            ]));
            assert!(
                normalize_colorspaces(&mut doc).unwrap().output_intent_added,
                "{alternate}"
            );
        }
    }
    #[test]
    fn gray_profile_white_point_matches_its_d50_pcs_illuminant() {
        let gray = gray_icc_profile_bytes();
        assert_eq!(&gray[284..296], &gray[68..80]);
    }

    #[test]
    fn test_normalize_skips_existing() {
        let mut doc = make_doc_with_device_rgb();
        add_srgb_output_intent(&mut doc).unwrap();
        let report = normalize_colorspaces(&mut doc).unwrap();
        assert!(report.had_output_intent);
        assert!(!report.output_intent_added);
    }

    #[test]
    fn test_icc_profile_structure() {
        let profile = srgb_icc_profile_bytes();
        assert_eq!(profile.len(), 8632);
        // Header checks
        assert_eq!(&profile[36..40], b"acsp");
        assert_eq!(&profile[16..20], b"RGB ");
        assert_eq!(&profile[12..16], b"mntr");
        // Size field
        let size = u32::from_be_bytes([profile[0], profile[1], profile[2], profile[3]]);
        assert_eq!(size as usize, profile.len());
        // 9 tags
        let tag_count =
            u32::from_be_bytes([profile[128], profile[129], profile[130], profile[131]]);
        assert_eq!(tag_count, 9);
        // desc tag signature at first entry
        assert_eq!(&profile[132..136], b"desc");
    }

    #[test]
    fn srgb_profile_uses_linear_toe_and_d50_adapted_white() {
        let p = srgb_icc_profile_bytes();
        assert_eq!(&p[356..368], &p[68..80]);
        assert_eq!(u32::from_be_bytes(p[436..440].try_into().unwrap()), 4096);
        let sample = |i: usize| {
            f64::from(u16::from_be_bytes(
                p[440 + 2 * i..442 + 2 * i].try_into().unwrap(),
            )) / 65535.0
        };
        assert_eq!(sample(0), 0.0);
        assert_eq!(sample(4095), 1.0);
        assert!((sample(100) - (100.0 / 4095.0 / 12.92)).abs() < 1.0 / 65535.0);
        assert!((sample(2048) - 0.214154).abs() < 0.00002);
        for i in 1..4096 {
            assert!(sample(i) >= sample(i - 1));
        }
    }

    #[test]
    fn cmyk_profile_contains_complete_color_transform_tables() {
        let profile = cmyk_icc_profile_bytes();
        let u32_at = |p: usize| u32::from_be_bytes(profile[p..p + 4].try_into().unwrap()) as usize;
        assert_eq!(u32_at(0), profile.len());
        assert_eq!(&profile[16..20], b"CMYK");
        let mut found = false;
        for i in 0..u32_at(128) {
            let at = 132 + i * 12;
            if &profile[at..at + 4] != b"A2B0" {
                continue;
            }
            found = true;
            let offset = u32_at(at + 4);
            let length = u32_at(at + 8);
            assert!(offset + length <= profile.len());
            let tag = &profile[offset..offset + length];
            let inputs = tag[8] as usize;
            let outputs = tag[9] as usize;
            assert_eq!(inputs, 4);
            assert_eq!(outputs, 3);
            let grid = tag[10] as usize;
            let required = match &tag[..4] {
                b"mft1" => 48 + inputs * 256 + grid.pow(inputs as u32) * outputs + outputs * 256,
                b"mft2" => {
                    let ni = u16::from_be_bytes(tag[48..50].try_into().unwrap()) as usize;
                    let no = u16::from_be_bytes(tag[50..52].try_into().unwrap()) as usize;
                    52 + 2 * (inputs * ni + grid.pow(inputs as u32) * outputs + outputs * no)
                }
                other => panic!("unexpected LUT signature {other:?}"),
            };
            assert!(
                length >= required,
                "a LUT header without its samples is not a usable transform"
            );
        }
        assert!(found, "missing forward CMYK transform");
    }

    #[test]
    fn test_empty_doc() {
        let mut doc = Document::with_version("1.7");
        let pages_id = doc.new_object_id();
        let pages = dictionary! {
            "Type" => "Pages",
            "Count" => Object::Integer(0),
            "Kids" => Object::Array(vec![]),
        };
        doc.objects.insert(pages_id, Object::Dictionary(pages));
        let catalog = dictionary! {
            "Type" => "Catalog",
            "Pages" => Object::Reference(pages_id),
        };
        let catalog_id = doc.add_object(Object::Dictionary(catalog));
        doc.trailer.set("Root", Object::Reference(catalog_id));

        let report = normalize_colorspaces(&mut doc).unwrap();
        assert!(!report.had_output_intent);
        assert!(report.output_intent_added);
        assert!(report.device_colorspaces_found.is_empty());
    }

    #[test]
    fn test_separation_no_conflict() {
        let mut doc = Document::with_version("1.7");
        let tint_fn = dictionary! {
            "FunctionType" => Object::Integer(2),
            "N" => Object::Integer(1),
        };
        let tint_id = doc.add_object(Object::Dictionary(tint_fn));

        let sep1 = Object::Array(vec![
            Object::Name(b"Separation".to_vec()),
            Object::Name(b"SpotRed".to_vec()),
            Object::Name(b"DeviceRGB".to_vec()),
            Object::Reference(tint_id),
        ]);
        let sep2 = Object::Array(vec![
            Object::Name(b"Separation".to_vec()),
            Object::Name(b"SpotRed".to_vec()),
            Object::Name(b"DeviceRGB".to_vec()),
            Object::Reference(tint_id),
        ]);
        doc.add_object(sep1);
        doc.add_object(sep2);

        let count = normalize_separation_colorspaces(&mut doc);
        // Both Separation objects share the same name, so the function unifies them
        // to satisfy veraPDF 6.2.4.4:2 (same name → same PDF object). Even when
        // content is identical, 2 content fixes + 1 redirect = 3 operations.
        assert_eq!(count, 3);
    }

    #[test]
    fn test_separation_conflict_unified() {
        let mut doc = Document::with_version("1.7");

        let tint1_id = doc.add_object(Object::Dictionary(dictionary! {
            "FunctionType" => Object::Integer(2),
            "N" => Object::Integer(1),
        }));
        let tint2_id = doc.add_object(Object::Dictionary(dictionary! {
            "FunctionType" => Object::Integer(2),
            "N" => Object::Integer(2),
        }));

        let sep1 = Object::Array(vec![
            Object::Name(b"Separation".to_vec()),
            Object::Name(b"SpotBlue".to_vec()),
            Object::Name(b"DeviceRGB".to_vec()),
            Object::Reference(tint1_id),
        ]);
        let sep2 = Object::Array(vec![
            Object::Name(b"Separation".to_vec()),
            Object::Name(b"SpotBlue".to_vec()),
            Object::Name(b"DeviceCMYK".to_vec()),
            Object::Reference(tint2_id),
        ]);
        let sep1_id = doc.add_object(sep1);
        let sep2_id = doc.add_object(sep2);

        let count = normalize_separation_colorspaces(&mut doc);
        // 2 content fixes (canonical + non-canonical) + 1 redirect = 3 operations
        assert_eq!(count, 3);

        // sep2 (non-canonical) should be deleted from the document entirely
        // (Phase 5: veraPDF scans all objects including unreferenced ones).
        assert!(
            !doc.objects.contains_key(&sep2_id),
            "non-canonical Separation should be removed"
        );
        // sep1 (canonical) should retain DeviceRGB and canonical tint.
        if let Object::Array(arr) = &doc.objects[&sep1_id] {
            assert_eq!(arr[2], Object::Name(b"DeviceRGB".to_vec()));
        } else {
            panic!("expected array");
        }
    }

    #[test]
    fn test_separation_in_dict_value() {
        let mut doc = Document::with_version("1.7");

        let tint1_id = doc.add_object(Object::Dictionary(dictionary! {
            "FunctionType" => Object::Integer(2),
            "N" => Object::Integer(1),
        }));
        let tint2_id = doc.add_object(Object::Dictionary(dictionary! {
            "FunctionType" => Object::Integer(4),
            "N" => Object::Integer(1),
        }));

        // sep1 as top-level array
        doc.add_object(Object::Array(vec![
            Object::Name(b"Separation".to_vec()),
            Object::Name(b"Cyan".to_vec()),
            Object::Name(b"DeviceRGB".to_vec()),
            Object::Reference(tint1_id),
        ]));

        // sep2 nested inside a Colorants dictionary
        let mut colorants = lopdf::Dictionary::new();
        colorants.set(
            "Cyan",
            Object::Array(vec![
                Object::Name(b"Separation".to_vec()),
                Object::Name(b"Cyan".to_vec()),
                Object::Name(b"DeviceCMYK".to_vec()),
                Object::Reference(tint2_id),
            ]),
        );
        let colorants_id = doc.add_object(Object::Dictionary(colorants));

        let count = normalize_separation_colorspaces(&mut doc);
        // 2 content fixes (top-level + nested) + 1 redirect = 3 operations
        assert_eq!(count, 3);

        // The Colorants dictionary (which contained the non-canonical nested
        // Separation) is removed in Phase 5: veraPDF scans all objects including
        // unreferenced ones, so non-canonical Separation containers are deleted.
        // All document references to colorants_id are redirected to the canonical.
        assert!(
            !doc.objects.contains_key(&colorants_id),
            "container with non-canonical Separation should be removed"
        );
    }

    #[test]
    fn test_output_intent_survives_roundtrip() {
        let mut doc = make_doc_with_device_rgb();
        add_srgb_output_intent(&mut doc).unwrap();
        let report = normalize_colorspaces(&mut doc).unwrap();
        assert!(!report.output_intent_added);
        assert!(has_pdfa_output_intent(&doc));

        // Save and reload
        let mut buf = Vec::new();
        doc.save_to(&mut buf).unwrap();
        let doc2 = Document::load_mem(&buf).unwrap();

        // Check OutputIntent survives serialization
        assert!(
            has_pdfa_output_intent(&doc2),
            "OutputIntent must survive save/load roundtrip"
        );

        // Check the DestOutputProfile ICC profile is present
        let catalog = get_catalog(&doc2).unwrap();
        let intents = match catalog.get(b"OutputIntents").unwrap() {
            Object::Array(arr) => arr.clone(),
            Object::Reference(id) => {
                if let Object::Array(arr) = doc2.objects.get(id).unwrap() {
                    arr.clone()
                } else {
                    panic!("expected array")
                }
            }
            _ => panic!("expected array"),
        };
        assert_eq!(intents.len(), 1);
        let intent = match &intents[0] {
            Object::Reference(id) => {
                if let Object::Dictionary(d) = doc2.objects.get(id).unwrap() {
                    d
                } else {
                    panic!("expected dict")
                }
            }
            Object::Dictionary(d) => d,
            _ => panic!("expected dict"),
        };

        // Must have DestOutputProfile reference
        let profile_ref = intent.get(b"DestOutputProfile").unwrap();
        match profile_ref {
            Object::Reference(id) => {
                let profile_obj = doc2.objects.get(id).expect("profile object must exist");
                match profile_obj {
                    Object::Stream(stream) => {
                        // Verify ICC profile size
                        let content = &stream.content;
                        assert!(
                            content.len() > 100,
                            "ICC profile must be non-trivial, got {} bytes",
                            content.len()
                        );
                        // Verify N=3 (RGB)
                        let n = stream.dict.get(b"N").unwrap();
                        assert_eq!(*n, Object::Integer(3));
                    }
                    _ => panic!("expected stream for ICC profile"),
                }
            }
            _ => panic!("expected reference for DestOutputProfile"),
        }
    }

    #[test]
    fn test_overprint_mode_fixed() {
        let mut doc = Document::with_version("1.7");
        let gs = dictionary! {
            "Type" => "ExtGState",
            "OPM" => Object::Integer(1),
            "OP" => Object::Boolean(true),
        };
        let gs_id = doc.add_object(Object::Dictionary(gs));

        let count = fix_overprint_mode(&mut doc);
        assert_eq!(count, 1);

        if let Object::Dictionary(dict) = &doc.objects[&gs_id] {
            assert_eq!(*dict.get(b"OPM").unwrap(), Object::Integer(0));
        }
    }

    #[test]
    fn test_overprint_mode_zero_untouched() {
        let mut doc = Document::with_version("1.7");
        let gs = dictionary! {
            "Type" => "ExtGState",
            "OPM" => Object::Integer(0),
        };
        doc.add_object(Object::Dictionary(gs));

        let count = fix_overprint_mode(&mut doc);
        assert_eq!(count, 0);
    }

    #[test]
    fn test_icc_n_value_mismatch() {
        let mut doc = Document::with_version("1.7");
        // Create a minimal ICC profile header with RGB color space (bytes 16..20 = "RGB ")
        let mut icc_data = vec![0u8; 128];
        icc_data[12..16].copy_from_slice(b"mntr"); // valid device class
        icc_data[16..20].copy_from_slice(b"RGB ");
        icc_data[36..40].copy_from_slice(b"acsp");
        icc_data[8] = 2; // version 2.x

        let icc_dict = dictionary! {
            "N" => Object::Integer(4), // Wrong: should be 3 for RGB
        };
        let stream = Stream::new(icc_dict, icc_data);
        let stream_id = doc.add_object(Object::Stream(stream));

        let count = fix_iccbased_n_value(&mut doc);
        assert_eq!(count, 1);

        if let Object::Stream(s) = &doc.objects[&stream_id] {
            assert_eq!(*s.dict.get(b"N").unwrap(), Object::Integer(3));
        }
    }

    #[test]
    fn test_icc_n_value_correct() {
        let mut doc = Document::with_version("1.7");
        let mut icc_data = vec![0u8; 128];
        icc_data[12..16].copy_from_slice(b"prtr"); // valid device class
        icc_data[16..20].copy_from_slice(b"CMYK");
        icc_data[36..40].copy_from_slice(b"acsp");
        icc_data[8] = 2; // version 2.x

        let icc_dict = dictionary! {
            "N" => Object::Integer(4), // Correct for CMYK
        };
        let stream = Stream::new(icc_dict, icc_data);
        doc.add_object(Object::Stream(stream));

        let count = fix_iccbased_n_value(&mut doc);
        assert_eq!(count, 0);
    }

    // Regression: PDFA-CS-DOS-01 — normalize_separation_colorspaces must not iterate
    // 1..=max_id when max_id is huge. A crafted PDF sets max_id to u32::MAX via /Size;
    // the old code would perform ~4 billion HashMap lookups.
    #[test]
    fn normalize_separation_colorspaces_with_huge_max_id_completes_fast() {
        let mut doc = Document::with_version("1.7");
        // Simulate a crafted PDF: set max_id to a large value while actual objects
        // remain minimal (no xref entries for those phantom IDs).
        doc.max_id = 1_000_000;

        let pages_id = doc.new_object_id();
        let pages = dictionary! {
            "Type" => "Pages",
            "Count" => Object::Integer(0),
            "Kids" => Object::Array(vec![]),
        };
        doc.objects.insert(pages_id, Object::Dictionary(pages));
        let catalog = dictionary! {
            "Type" => "Catalog",
            "Pages" => Object::Reference(pages_id),
        };
        let catalog_id = doc.add_object(Object::Dictionary(catalog));
        doc.trailer.set("Root", Object::Reference(catalog_id));

        // If this completes without hanging, the DoS fix is in effect.
        // (The old 1..=max_id loop would iterate 1 million times on phantom IDs.)
        let count = normalize_separation_colorspaces(&mut doc);
        assert_eq!(count, 0);
    }

    // Regression: PDFA-CS-INFO-02 — Length cast for replaced ICC profile stream.
    // Verifies that fix_iccbased_n_value sets /Length correctly after profile replacement.
    #[test]
    fn fix_iccbased_n_value_sets_length_after_replace() {
        let mut doc = Document::with_version("1.7");
        // A stream with /N but < 128 bytes — will be replaced.
        let icc_dict = dictionary! {
            "N" => Object::Integer(3),
        };
        let tiny_icc = vec![0u8; 10]; // too short to be a valid ICC header
        let stream = Stream::new(icc_dict, tiny_icc);
        let sid = doc.add_object(Object::Stream(stream));

        let count = fix_iccbased_n_value(&mut doc);
        assert_eq!(count, 1);

        if let Some(Object::Stream(s)) = doc.objects.get(&sid) {
            let len_obj = s
                .dict
                .get(b"Length")
                .expect("/Length must be set after replace");
            if let Object::Integer(len) = len_obj {
                assert!(*len > 0, "/Length must be positive");
                assert_eq!(*len as usize, s.content.len(), "/Length must match content");
            } else {
                panic!("/Length is not an Integer");
            }
        } else {
            panic!("stream object not found");
        }
    }
}

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

    fn doc_with_stream(dict: lopdf::Dictionary, content: &[u8]) -> Document {
        let mut doc = Document::with_version("1.7");
        doc.add_object(Object::Stream(Stream::new(dict, content.to_vec())));
        doc
    }

    /// An inline image is not an object: it lives between `BI` and `EI` inside
    /// a content stream, so nothing that walks `doc.objects` looking for a
    /// `/ColorSpace` name will ever see its `/CS /DeviceRGB`. By the time the
    /// OutputIntent decision runs, the object-level RGB XObjects have already
    /// become ICCBased, so an inline image can be the document's only
    /// remaining RGB usage — and missing it costs the sRGB OutputIntent the
    /// document needs (govdocs holdout 104_104177).
    #[test]
    fn inline_image_device_rgb_is_found() {
        let doc = doc_with_stream(
            dictionary! {},
            b"q 100 0 0 100 0 0 cm\nBI /W 2 /H 2 /CS /DeviceRGB /BPC 8 ID \x00\x01\x02 EI\nQ",
        );
        assert!(has_device_rgb_in_streams(&doc));
    }

    /// A three-component ICCBased profile is an RGB profile; its stream never
    /// spells "DeviceRGB" anywhere, so the /N count is the only signal.
    #[test]
    fn three_component_iccbased_counts_as_rgb() {
        let doc = doc_with_stream(dictionary! { "N" => Object::Integer(3) }, b"\x00\x01\x02");
        assert!(has_device_rgb_in_streams(&doc));
    }

    /// The converse must hold, or the check is just "always true": a CMYK-only
    /// document must not be handed an sRGB OutputIntent it has no use for.
    #[test]
    fn cmyk_only_document_has_no_rgb() {
        let doc = doc_with_stream(
            dictionary! { "N" => Object::Integer(4) },
            b"q /DeviceCMYK cs 0 0 0 1 sc 0 0 10 10 re f Q",
        );
        assert!(!has_device_rgb_in_streams(&doc));
    }

    /// The pass must actually consult the scan. Testing the detector alone
    /// would leave the call site free to disappear — the exact shape of defect
    /// this project keeps hitting: the check exists and nothing invokes it.
    ///
    /// The fixture has to carry CMYK too. Without CMYK the pass adds sRGB
    /// unconditionally (`has_rgb || !has_cmyk`), so an RGB-only document
    /// cannot tell whether the scan ran — it was green with the call site
    /// deleted. A CMYK document whose only RGB is an inline image is the one
    /// shape where the answer decides the outcome, and it is 104_104177's.
    #[test]
    fn normalization_characterizes_inline_rgb_alongside_named_cmyk() {
        let mut doc = Document::with_version("1.7");
        let pages_id = doc.new_object_id();

        // Named CMYK in the resources; the RGB exists only inside the content.
        let content = Stream::new(
            dictionary! {},
            b"q /CS1 cs 0 0 0 1 sc 0 0 10 10 re f\nBI /W 1 /H 1 /CS /DeviceRGB /BPC 8 ID \x00 EI\nQ".to_vec(),
        );
        let content_id = doc.add_object(Object::Stream(content));
        let mut cs_dict = lopdf::Dictionary::new();
        cs_dict.set("CS1", Object::Name(b"DeviceCMYK".to_vec()));
        let mut res = lopdf::Dictionary::new();
        res.set("ColorSpace", Object::Dictionary(cs_dict));

        let page = dictionary! {
            "Type" => "Page",
            "Parent" => Object::Reference(pages_id),
            "MediaBox" => Object::Array(vec![
                Object::Integer(0), Object::Integer(0),
                Object::Integer(612), Object::Integer(792),
            ]),
            "Contents" => Object::Reference(content_id),
            "Resources" => Object::Dictionary(res),
        };
        let page_id = doc.add_object(Object::Dictionary(page));
        doc.objects.insert(
            pages_id,
            Object::Dictionary(dictionary! {
                "Type" => "Pages",
                "Count" => Object::Integer(1),
                "Kids" => Object::Array(vec![Object::Reference(page_id)]),
            }),
        );
        let catalog_id = doc.add_object(Object::Dictionary(dictionary! {
            "Type" => "Catalog",
            "Pages" => Object::Reference(pages_id),
        }));
        doc.trailer.set("Root", Object::Reference(catalog_id));

        normalize_colorspaces(&mut doc).expect("normalize");

        let page = doc.get_dictionary(page_id).unwrap();
        let resources = page.get(b"Resources").unwrap().as_dict().unwrap();
        let cs = resources.get(b"ColorSpace").unwrap().as_dict().unwrap();
        for (key, n) in [(b"DefaultRGB".as_slice(), 3), (b"DefaultCMYK", 4)] {
            let id = cs.get(key).unwrap().as_reference().unwrap();
            let array = doc.get_object(id).unwrap().as_array().unwrap();
            assert_eq!(array[0].as_name().unwrap(), b"ICCBased");
            let profile = doc
                .get_object(array[1].as_reference().unwrap())
                .unwrap()
                .as_stream()
                .unwrap();
            assert_eq!(profile.dict.get(b"N").unwrap().as_i64().unwrap(), n);
        }
        assert!(doc.catalog().unwrap().has(b"OutputIntents"));
    }

    /// The byte-level fallback in `note_content_bytes` reads `k` as
    /// `setcmykcolor` only with its four operands. Without insisting on
    /// them, any whitespace-then-`k` byte pair reads as CMYK usage — and
    /// inline-image samples are arbitrary binary, so they hit it constantly.
    /// The consequence is not cosmetic: a spurious CMYK OutputIntent takes the
    /// single ICC slot §6.2.3:2 allows, and the document's real RGB content
    /// then has no output intent to stand on (govdocs holdout 104_104177 and
    /// 212_212392, 58 and 8 §6.2.4.3:2 failures, zero CMYK anywhere in either).
    fn cmyk_operator_in_bytes(content: &[u8]) -> bool {
        operator_with_operands(content, b"k", 4) || operator_with_operands(content, b"K", 4)
    }

    #[test]
    fn cmyk_operator_needs_its_four_operands() {
        assert!(cmyk_operator_in_bytes(b"q 0 0 0 1 k 10 10 100 100 re f Q"));
        assert!(cmyk_operator_in_bytes(b"0.1 0.2 0.3 0.4 K\n"));
        assert!(cmyk_operator_in_bytes(b"BT 1 1 1 1 k ET"));
    }

    #[test]
    fn stray_k_bytes_are_not_cmyk_usage() {
        // Binary image samples: a space followed by 0x6B means nothing.
        assert!(!cmyk_operator_in_bytes(
            b"BI /W 2 /H 2 ID \x01\x02 k\x99\x04 EI"
        ));
        // A `k` that is part of a longer token is not the operator.
        assert!(!cmyk_operator_in_bytes(b"q 0 0 0 1 kilo Q"));
        // Text, not colour.
        assert!(!cmyk_operator_in_bytes(b"BT (a black cat) Tj ET"));
        // Three operands is `rg`-shaped, not `k`.
        assert!(!cmyk_operator_in_bytes(b"0 0 1 k"[..6].as_ref()));
    }

    /// Compressed streams have to be searched decompressed, or a Flate content
    /// stream hides its inline image from the scan entirely.
    #[test]
    fn compressed_stream_is_searched_decompressed() {
        // Padded so DEFLATE actually wins — lopdf keeps the plain bytes when
        // compression does not pay, and an uncompressed fixture would pass
        // this test without exercising the decompression path at all.
        let mut content = b"q 1 0 0 1 0 0 cm ".repeat(64);
        content.extend_from_slice(b"BI /W 1 /H 1 /CS /DeviceRGB /BPC 8 ID \x00 EI Q");
        let mut stream = Stream::new(dictionary! {}, content);
        stream.compress().expect("compress");
        assert!(
            !stream.content.windows(9).any(|w| w == b"DeviceRGB"),
            "fixture must actually be compressed, or it proves nothing"
        );
        let mut doc = Document::with_version("1.7");
        doc.add_object(Object::Stream(stream));

        assert!(has_device_rgb_in_streams(&doc));
    }
}

/// How many of the streams [`census_device_colors`] reads as content programs
/// the strict parser refuses, so that the census has to read their bytes.
///
/// For `examples/pdfa_device_colour_census.rs`. It is the figure that decides
/// whether a parser complaint may be treated as "unreadable": on the
/// 300-document tuning set it may not, by three orders of magnitude.
///
/// Opaque payload is excluded on the same test the census uses. Counting every
/// stream instead reports four times as many refusals -- images and font
/// programs, which are not content and are never parsed as any.
pub fn content_streams_the_parser_refuses(doc: &Document) -> usize {
    doc.objects
        .values()
        .filter(|object| match object {
            Object::Stream(stream) if !is_opaque_payload(stream) => stream
                .get_plain_content()
                .is_ok_and(|bytes| crate::inline_image::decode_strict(&bytes).is_err()),
            _ => false,
        })
        .count()
}