rpdfium_edit/

page_object.rs

// Derived from PDFium's fpdfsdk/fpdf_edit_impl.cpp / core/fpdfapi/page
// Original: Copyright 2014 The PDFium Authors
// Licensed under BSD-3-Clause / Apache-2.0
// See pdfium-upstream/LICENSE for the original license.

//! Page objects — typed wrappers for path, text, image, and form XObject
//! content that can be placed on a page.

use rpdfium_core::{Matrix, Name};
use rpdfium_font::FontEncoding;
use rpdfium_graphics::{
    Bitmap, BitmapFormat, BlendMode, Color, DashPattern, PathOp, TextRenderingMode,
};
use rpdfium_parser::object::ObjectId;

// ---------------------------------------------------------------------------
// Content Marks API  (FPDFPageObj*Mark* functions — tagged PDF / accessibility)
// ---------------------------------------------------------------------------

/// The value of a content mark parameter.
///
/// Corresponds to the three parameter types in the PDF spec for marked content
/// (`BMC`/`BDC`/`EMC` operators): integer, string, raw blob, and inline
/// dictionary.
#[derive(Debug, Clone, PartialEq)]
pub enum MarkParamValue {
    /// An integer parameter value.
    ///
    /// Corresponds to `FPDFPageObjMark_GetParamValueType` returning
    /// `FPDF_OBJECT_NUMBER` + `FPDFPageObjMark_GetParamIntValue`.
    Integer(i64),
    /// A float parameter value.
    ///
    /// Corresponds to `FPDFPageObjMark_GetParamValueType` returning
    /// `FPDF_OBJECT_NUMBER` (real) + `FPDFPageObjMark_GetParamFloatValue`.
    Float(f32),
    /// A UTF-8 string parameter value.
    ///
    /// Corresponds to `FPDFPageObjMark_GetParamValueType` returning
    /// `FPDF_OBJECT_STRING` + `FPDFPageObjMark_GetParamStringValue`.
    String(String),
    /// A raw byte blob parameter value.
    ///
    /// Corresponds to `FPDFPageObjMark_GetParamValueType` returning
    /// `FPDF_OBJECT_STRING` (binary) + `FPDFPageObjMark_GetParamBlobValue`.
    Blob(Vec<u8>),
    /// An inline dictionary parameter value.
    ///
    /// Serialized as `<< /Key Value ... >>` inline in the content stream.
    /// Entries are stored in insertion order (`Vec<(key, value)>`).
    ///
    /// This is used when a BDC mark carries a full parameter dictionary rather
    /// than a single typed value — for example, PDF/UA tagged content where the
    /// mark properties are specified inline rather than referencing a properties
    /// resource.
    Dictionary(Vec<(String, MarkParamValue)>),
}

/// A content mark attached to a page object (for tagged PDF / accessibility).
///
/// Content marks correspond to the BMC/BDC/EMC operators in PDF content
/// streams. Each mark has a name (the tag name, e.g. `"Span"`, `"P"`, `"Figure"`)
/// and an optional parameter dictionary (key → value pairs).
///
/// The most common parameter is `"MCID"` (Marked Content Identifier), an
/// integer that links the page object into the logical structure tree.
///
/// # Upstream Correspondence
///
/// - `FPDFPageObj_CountMarks` / `FPDFPageObj_GetMark` / `FPDFPageObj_AddMark` /
///   `FPDFPageObj_RemoveMark`
/// - `FPDFPageObjMark_GetName` / `FPDFPageObjMark_CountParams` /
///   `FPDFPageObjMark_GetParamKey` / `FPDFPageObjMark_GetParamValueType`
/// - `FPDFPageObjMark_GetIntParam` / `FPDFPageObjMark_GetStringParam` /
///   `FPDFPageObjMark_GetBlobParam`
/// - `FPDFPageObjMark_SetIntParam` / `FPDFPageObjMark_SetStringParam` /
///   `FPDFPageObjMark_SetBlobParam` / `FPDFPageObjMark_RemoveParam`
#[derive(Debug, Clone, PartialEq)]
pub struct ContentMark {
    /// The tag name (e.g. `"Span"`, `"P"`, `"Figure"`).
    pub name: String,
    /// Key–value parameters in insertion order.
    pub params: Vec<(String, MarkParamValue)>,
}

impl ContentMark {
    /// Create a new content mark with the given tag name and no parameters.
    ///
    /// Corresponds to `FPDFPageObj_AddMark`.
    pub fn new(name: impl Into<String>) -> Self {
        Self {
            name: name.into(),
            params: Vec::new(),
        }
    }

    /// Returns the tag name of this content mark.
    ///
    /// Corresponds to `FPDFPageObjMark_GetName`.
    pub fn name(&self) -> &str {
        &self.name
    }

    /// Upstream-aligned alias for [`name()`](Self::name).
    ///
    /// Corresponds to `FPDFPageObjMark_GetName`.
    #[inline]
    pub fn page_obj_mark_get_name(&self) -> &str {
        self.name()
    }

    /// Non-upstream alias — use [`page_obj_mark_get_name()`](Self::page_obj_mark_get_name).
    #[deprecated(
        note = "use `page_obj_mark_get_name()` — matches upstream `FPDFPageObjMark_GetName`"
    )]
    #[inline]
    pub fn get_name(&self) -> &str {
        self.name()
    }

    /// Return the number of parameters on this mark.
    ///
    /// Corresponds to `FPDFPageObjMark_CountParams`.
    pub fn param_count(&self) -> usize {
        self.params.len()
    }

    /// Upstream-aligned alias for [`param_count()`](Self::param_count).
    ///
    /// Corresponds to `FPDFPageObjMark_CountParams`.
    #[inline]
    pub fn page_obj_mark_count_params(&self) -> usize {
        self.param_count()
    }

    /// Non-upstream alias — use [`page_obj_mark_count_params()`](Self::page_obj_mark_count_params).
    #[deprecated(
        note = "use `page_obj_mark_count_params()` — matches upstream `FPDFPageObjMark_CountParams`"
    )]
    #[inline]
    pub fn count_params(&self) -> usize {
        self.param_count()
    }

    /// Return the key at the given parameter index, or `None` if out of range.
    ///
    /// Corresponds to `FPDFPageObjMark_GetParamKey`.
    pub fn param_key(&self, index: usize) -> Option<&str> {
        self.params.get(index).map(|(k, _)| k.as_str())
    }

    /// Upstream-aligned alias for [`param_key()`](Self::param_key).
    ///
    /// Corresponds to `FPDFPageObjMark_GetParamKey`.
    #[inline]
    pub fn page_obj_mark_get_param_key(&self, index: usize) -> Option<&str> {
        self.param_key(index)
    }

    /// Non-upstream alias — use [`page_obj_mark_get_param_key()`](Self::page_obj_mark_get_param_key).
    #[deprecated(
        note = "use `page_obj_mark_get_param_key()` — matches upstream `FPDFPageObjMark_GetParamKey`"
    )]
    #[inline]
    pub fn get_param_key(&self, index: usize) -> Option<&str> {
        self.param_key(index)
    }

    /// Return the integer value of the parameter with the given key, or `None`
    /// if the key is absent or has a non-integer value.
    ///
    /// Corresponds to `FPDFPageObjMark_GetParamIntValue`.
    pub fn int_param(&self, key: &str) -> Option<i64> {
        self.params.iter().find_map(|(k, v)| {
            if k == key {
                if let MarkParamValue::Integer(n) = v {
                    Some(*n)
                } else {
                    None
                }
            } else {
                None
            }
        })
    }

    /// Upstream-aligned alias for [`int_param()`](Self::int_param).
    ///
    /// Corresponds to `FPDFPageObjMark_GetParamIntValue`.
    #[inline]
    pub fn page_obj_mark_get_param_int_value(&self, key: &str) -> Option<i64> {
        self.int_param(key)
    }

    #[deprecated(
        note = "use `page_obj_mark_get_param_int_value()` — matches upstream `FPDFPageObjMark_GetParamIntValue`"
    )]
    #[inline]
    pub fn get_param_int_value(&self, key: &str) -> Option<i64> {
        self.int_param(key)
    }

    /// Non-upstream alias — use [`page_obj_mark_get_param_int_value()`](Self::page_obj_mark_get_param_int_value).
    #[deprecated(
        note = "use `page_obj_mark_get_param_int_value()` — matches upstream `FPDFPageObjMark_GetParamIntValue`"
    )]
    #[inline]
    pub fn get_int_param(&self, key: &str) -> Option<i64> {
        self.int_param(key)
    }

    /// Return the string value of the parameter with the given key, or `None`
    /// if the key is absent or has a non-string value.
    ///
    /// Corresponds to `FPDFPageObjMark_GetParamStringValue`.
    pub fn string_param(&self, key: &str) -> Option<&str> {
        self.params.iter().find_map(|(k, v)| {
            if k == key {
                if let MarkParamValue::String(s) = v {
                    Some(s.as_str())
                } else {
                    None
                }
            } else {
                None
            }
        })
    }

    /// Upstream-aligned alias for [`string_param()`](Self::string_param).
    ///
    /// Corresponds to `FPDFPageObjMark_GetParamStringValue`.
    #[inline]
    pub fn page_obj_mark_get_param_string_value(&self, key: &str) -> Option<&str> {
        self.string_param(key)
    }

    #[deprecated(
        note = "use `page_obj_mark_get_param_string_value()` — matches upstream `FPDFPageObjMark_GetParamStringValue`"
    )]
    #[inline]
    pub fn get_param_string_value(&self, key: &str) -> Option<&str> {
        self.string_param(key)
    }

    /// Non-upstream alias — use [`page_obj_mark_get_param_string_value()`](Self::page_obj_mark_get_param_string_value).
    #[deprecated(
        note = "use `page_obj_mark_get_param_string_value()` — matches upstream `FPDFPageObjMark_GetParamStringValue`"
    )]
    #[inline]
    pub fn get_string_param(&self, key: &str) -> Option<&str> {
        self.string_param(key)
    }

    /// Return the blob value of the parameter with the given key, or `None`
    /// if the key is absent or has a non-blob value.
    ///
    /// Corresponds to `FPDFPageObjMark_GetParamBlobValue`.
    pub fn blob_param(&self, key: &str) -> Option<&[u8]> {
        self.params.iter().find_map(|(k, v)| {
            if k == key {
                if let MarkParamValue::Blob(b) = v {
                    Some(b.as_slice())
                } else {
                    None
                }
            } else {
                None
            }
        })
    }

    /// Upstream-aligned alias for [`blob_param()`](Self::blob_param).
    ///
    /// Corresponds to `FPDFPageObjMark_GetParamBlobValue`.
    #[inline]
    pub fn page_obj_mark_get_param_blob_value(&self, key: &str) -> Option<&[u8]> {
        self.blob_param(key)
    }

    #[deprecated(
        note = "use `page_obj_mark_get_param_blob_value()` — matches upstream `FPDFPageObjMark_GetParamBlobValue`"
    )]
    #[inline]
    pub fn get_param_blob_value(&self, key: &str) -> Option<&[u8]> {
        self.blob_param(key)
    }

    /// Non-upstream alias — use [`page_obj_mark_get_param_blob_value()`](Self::page_obj_mark_get_param_blob_value).
    #[deprecated(
        note = "use `page_obj_mark_get_param_blob_value()` — matches upstream `FPDFPageObjMark_GetParamBlobValue`"
    )]
    #[inline]
    pub fn get_blob_param(&self, key: &str) -> Option<&[u8]> {
        self.blob_param(key)
    }

    /// Set (or replace) an integer parameter.
    ///
    /// If a parameter with the same key already exists, its value is replaced;
    /// otherwise a new entry is appended.
    ///
    /// Corresponds to `FPDFPageObjMark_SetIntParam`.
    pub fn set_int_param(&mut self, key: impl Into<String>, value: i64) {
        let key = key.into();
        for (k, v) in &mut self.params {
            if *k == key {
                *v = MarkParamValue::Integer(value);
                return;
            }
        }
        self.params.push((key, MarkParamValue::Integer(value)));
    }

    /// Upstream-aligned alias for [`set_int_param()`](Self::set_int_param).
    ///
    /// Corresponds to `FPDFPageObjMark_SetIntParam`.
    #[inline]
    pub fn page_obj_mark_set_int_param(&mut self, key: impl Into<String>, value: i64) {
        self.set_int_param(key, value)
    }

    /// Set (or replace) a string parameter.
    ///
    /// If a parameter with the same key already exists, its value is replaced;
    /// otherwise a new entry is appended.
    ///
    /// Corresponds to `FPDFPageObjMark_SetStringParam`.
    pub fn set_string_param(&mut self, key: impl Into<String>, value: impl Into<String>) {
        let key = key.into();
        let value = value.into();
        for (k, v) in &mut self.params {
            if *k == key {
                *v = MarkParamValue::String(value);
                return;
            }
        }
        self.params.push((key, MarkParamValue::String(value)));
    }

    /// Upstream-aligned alias for [`set_string_param()`](Self::set_string_param).
    ///
    /// Corresponds to `FPDFPageObjMark_SetStringParam`.
    #[inline]
    pub fn page_obj_mark_set_string_param(
        &mut self,
        key: impl Into<String>,
        value: impl Into<String>,
    ) {
        self.set_string_param(key, value)
    }

    /// Return the float value of the parameter with the given key, or `None`
    /// if the key is absent or has a non-float value.
    ///
    /// Note: In this implementation, floats are stored as a sub-case of the
    /// `Integer` variant using the bit pattern. If a float was stored via
    /// [`set_float_param`](Self::set_float_param), it can be retrieved here.
    ///
    /// Corresponds to `FPDFPageObjMark_GetParamFloatValue`.
    pub fn float_param(&self, key: &str) -> Option<f32> {
        self.params.iter().find_map(|(k, v)| {
            if k == key {
                if let MarkParamValue::Float(f) = v {
                    Some(*f)
                } else {
                    None
                }
            } else {
                None
            }
        })
    }

    /// Upstream-aligned alias for [`float_param()`](Self::float_param).
    ///
    /// Corresponds to `FPDFPageObjMark_GetParamFloatValue`.
    #[inline]
    pub fn page_obj_mark_get_param_float_value(&self, key: &str) -> Option<f32> {
        self.float_param(key)
    }

    #[deprecated(
        note = "use `page_obj_mark_get_param_float_value()` — matches upstream `FPDFPageObjMark_GetParamFloatValue`"
    )]
    #[inline]
    pub fn get_param_float_value(&self, key: &str) -> Option<f32> {
        self.float_param(key)
    }

    /// Set (or replace) a float parameter.
    ///
    /// If a parameter with the same key already exists, its value is replaced;
    /// otherwise a new entry is appended.
    ///
    /// Corresponds to `FPDFPageObjMark_SetFloatParam`.
    pub fn set_float_param(&mut self, key: impl Into<String>, value: f32) {
        let key = key.into();
        for (k, v) in &mut self.params {
            if *k == key {
                *v = MarkParamValue::Float(value);
                return;
            }
        }
        self.params.push((key, MarkParamValue::Float(value)));
    }

    /// Upstream-aligned alias for [`set_float_param()`](Self::set_float_param).
    ///
    /// Corresponds to `FPDFPageObjMark_SetFloatParam`.
    #[inline]
    pub fn page_obj_mark_set_float_param(&mut self, key: impl Into<String>, value: f32) {
        self.set_float_param(key, value)
    }

    /// Set (or replace) a blob parameter.
    ///
    /// If a parameter with the same key already exists, its value is replaced;
    /// otherwise a new entry is appended.
    ///
    /// Corresponds to `FPDFPageObjMark_SetBlobParam`.
    pub fn set_blob_param(&mut self, key: impl Into<String>, value: Vec<u8>) {
        let key = key.into();
        for (k, v) in &mut self.params {
            if *k == key {
                *v = MarkParamValue::Blob(value);
                return;
            }
        }
        self.params.push((key, MarkParamValue::Blob(value)));
    }

    /// Upstream-aligned alias for [`set_blob_param()`](Self::set_blob_param).
    ///
    /// Corresponds to `FPDFPageObjMark_SetBlobParam`.
    #[inline]
    pub fn page_obj_mark_set_blob_param(&mut self, key: impl Into<String>, value: Vec<u8>) {
        self.set_blob_param(key, value)
    }

    /// Remove a parameter by key.
    ///
    /// Returns `true` if the parameter was found and removed, `false` if not
    /// found.
    ///
    /// Corresponds to `FPDFPageObjMark_RemoveParam`.
    pub fn remove_param(&mut self, key: &str) -> bool {
        let before = self.params.len();
        self.params.retain(|(k, _)| k != key);
        self.params.len() < before
    }

    /// Upstream-aligned alias for [`remove_param()`](Self::remove_param).
    ///
    /// Corresponds to `FPDFPageObjMark_RemoveParam`.
    #[inline]
    pub fn page_obj_mark_remove_param(&mut self, key: &str) -> bool {
        self.remove_param(key)
    }

    /// Return the `/MCID` integer value from this mark, if present.
    ///
    /// This is a convenience wrapper around `int_param("MCID")`.
    ///
    /// Corresponds to `FPDFPageObj_GetMarkedContentID` (for the specific mark
    /// that carries the MCID).
    pub fn marked_content_id(&self) -> Option<i64> {
        self.int_param("MCID")
    }

    /// Returns the PDF object type code of the parameter with the given key.
    ///
    /// Return values follow PDFium's `FPDF_OBJECT_*` constants:
    /// - `2` (`FPDF_OBJECT_NUMBER`) for integer or float parameters
    /// - `3` (`FPDF_OBJECT_STRING`) for string or blob parameters
    /// - `7` (`FPDF_OBJECT_DICTIONARY`) for dictionary parameters
    /// - `0` (`FPDF_OBJECT_UNKNOWN`) if the key is not found
    ///
    /// Corresponds to `FPDFPageObjMark_GetParamValueType`.
    pub fn param_value_type(&self, key: &str) -> u32 {
        self.params
            .iter()
            .find_map(|(k, v)| {
                if k == key {
                    Some(match v {
                        MarkParamValue::Integer(_) | MarkParamValue::Float(_) => 2,
                        MarkParamValue::String(_) | MarkParamValue::Blob(_) => 3,
                        MarkParamValue::Dictionary(_) => 7,
                    })
                } else {
                    None
                }
            })
            .unwrap_or(0)
    }

    /// Upstream-aligned alias for [`param_value_type()`](Self::param_value_type).
    ///
    /// Corresponds to `FPDFPageObjMark_GetParamValueType`.
    #[inline]
    pub fn page_obj_mark_get_param_value_type(&self, key: &str) -> u32 {
        self.param_value_type(key)
    }

    /// Non-upstream alias — use [`page_obj_mark_get_param_value_type()`](Self::page_obj_mark_get_param_value_type).
    #[deprecated(
        note = "use `page_obj_mark_get_param_value_type()` — matches upstream `FPDFPageObjMark_GetParamValueType`"
    )]
    #[inline]
    pub fn get_param_value_type(&self, key: &str) -> u32 {
        self.param_value_type(key)
    }
}

// ---------------------------------------------------------------------------
// Clip Path API  (fpdf_transformpage.h — FPDF_CreateClipPath / FPDFClipPath_*)
// ---------------------------------------------------------------------------

/// A clipping path that can be attached to page objects or inserted into a page.
///
/// A clip path consists of one or more sub-paths. Each sub-path is a sequence
/// of [`PathSegment`]s. When applied, the intersection of all sub-paths defines
/// the clipping region.
///
/// # Upstream Correspondence
///
/// - `FPDF_CreateClipPath` — [`ClipPath::from_rect`]
/// - `FPDF_DestroyClipPath` — Rust: just drop
/// - `FPDFClipPath_CountPaths` — [`ClipPath::path_count`]
/// - `FPDFClipPath_CountPathSegments` — [`ClipPath::segment_count`]
/// - `FPDFClipPath_GetPathSegment` — [`ClipPath::segment`]
/// - `FPDFPageObj_GetClipPath` — [`PageObject::clip_path`]
/// - `FPDFPageObj_TransformClipPath` — [`PageObject::transform_clip_path`]
/// - `FPDFPage_InsertClipPath` — [`crate::document::EditDocument::insert_clip_path`]
#[derive(Debug, Clone)]
pub struct ClipPath {
    /// Sub-paths that define the clipping region.
    pub paths: Vec<Vec<PathSegment>>,
}

impl ClipPath {
    /// Create a rectangular clip path from left, bottom, right, top coordinates.
    ///
    /// Corresponds to `FPDF_CreateClipPath(left, bottom, right, top)`.
    pub fn from_rect(left: f64, bottom: f64, right: f64, top: f64) -> Self {
        let rect_path = vec![PathSegment::Rect(left, bottom, right - left, top - bottom)];
        Self {
            paths: vec![rect_path],
        }
    }

    /// Upstream-aligned alias for [`from_rect()`](Self::from_rect).
    #[inline]
    pub fn create_clip_path(left: f64, bottom: f64, right: f64, top: f64) -> Self {
        Self::from_rect(left, bottom, right, top)
    }

    /// Create a clip path from a list of sub-paths.
    pub fn new(paths: Vec<Vec<PathSegment>>) -> Self {
        Self { paths }
    }

    /// Returns the number of sub-paths in the clip path.
    ///
    /// Corresponds to `FPDFClipPath_CountPaths`.
    pub fn path_count(&self) -> usize {
        self.paths.len()
    }

    /// Upstream-aligned alias for [`path_count()`](Self::path_count).
    ///
    /// Corresponds to `FPDFClipPath_CountPaths`.
    #[inline]
    pub fn clip_path_count_paths(&self) -> usize {
        self.path_count()
    }

    /// Non-upstream alias — use [`clip_path_count_paths()`](Self::clip_path_count_paths).
    #[deprecated(
        note = "use `clip_path_count_paths()` — matches upstream `FPDFClipPath_CountPaths`"
    )]
    #[inline]
    pub fn count_paths(&self) -> usize {
        self.path_count()
    }

    /// Returns the number of segments in the sub-path at `path_index`.
    ///
    /// Returns `0` if `path_index` is out of range.
    ///
    /// Corresponds to `FPDFClipPath_CountPathSegments`.
    pub fn segment_count(&self, path_index: usize) -> usize {
        self.paths.get(path_index).map(|p| p.len()).unwrap_or(0)
    }

    /// Upstream-aligned alias for [`segment_count()`](Self::segment_count).
    ///
    /// Corresponds to `FPDFClipPath_CountPathSegments`.
    #[inline]
    pub fn clip_path_count_path_segments(&self, path_index: usize) -> usize {
        self.segment_count(path_index)
    }

    /// Non-upstream alias — use [`clip_path_count_path_segments()`](Self::clip_path_count_path_segments).
    #[deprecated(
        note = "use `clip_path_count_path_segments()` — matches upstream `FPDFClipPath_CountPathSegments`"
    )]
    #[inline]
    pub fn count_path_segments(&self, path_index: usize) -> usize {
        self.segment_count(path_index)
    }

    /// Returns the segment at `(path_index, seg_index)`, or `None` if out of range.
    ///
    /// Corresponds to `FPDFClipPath_GetPathSegment`.
    pub fn segment(&self, path_index: usize, seg_index: usize) -> Option<&PathSegment> {
        self.paths.get(path_index)?.get(seg_index)
    }

    /// Upstream-aligned alias for [`segment()`](Self::segment).
    ///
    /// Corresponds to `FPDFClipPath_GetPathSegment`.
    #[inline]
    pub fn clip_path_get_path_segment(
        &self,
        path_index: usize,
        seg_index: usize,
    ) -> Option<&PathSegment> {
        self.segment(path_index, seg_index)
    }

    /// Non-upstream alias — use [`clip_path_get_path_segment()`](Self::clip_path_get_path_segment).
    #[deprecated(
        note = "use `clip_path_get_path_segment()` — matches upstream `FPDFClipPath_GetPathSegment`"
    )]
    #[inline]
    pub fn get_path_segment(&self, path_index: usize, seg_index: usize) -> Option<&PathSegment> {
        self.segment(path_index, seg_index)
    }

    /// Applies a matrix transform to all segments in all sub-paths.
    ///
    /// Corresponds to `FPDFPageObj_TransformClipPath` (transform portion).
    pub fn transform(&mut self, matrix: &Matrix) {
        use rpdfium_core::Point;
        for sub_path in &mut self.paths {
            for seg in sub_path {
                match seg {
                    PathSegment::MoveTo(x, y) | PathSegment::LineTo(x, y) => {
                        let p = matrix.transform_point(Point::new(*x, *y));
                        *x = p.x;
                        *y = p.y;
                    }
                    PathSegment::CurveTo(x1, y1, x2, y2, x3, y3) => {
                        let p1 = matrix.transform_point(Point::new(*x1, *y1));
                        let p2 = matrix.transform_point(Point::new(*x2, *y2));
                        let p3 = matrix.transform_point(Point::new(*x3, *y3));
                        *x1 = p1.x;
                        *y1 = p1.y;
                        *x2 = p2.x;
                        *y2 = p2.y;
                        *x3 = p3.x;
                        *y3 = p3.y;
                    }
                    PathSegment::Rect(x, y, w, h) => {
                        let p = matrix.transform_point(Point::new(*x, *y));
                        let scale_x = (matrix.a * matrix.a + matrix.b * matrix.b).sqrt();
                        let scale_y = (matrix.c * matrix.c + matrix.d * matrix.d).sqrt();
                        *x = p.x;
                        *y = p.y;
                        *w *= scale_x;
                        *h *= scale_y;
                    }
                    PathSegment::Close => {}
                }
            }
        }
    }
}

/// A page object that can be placed on a page.
#[derive(Debug, Clone)]
pub enum PageObject {
    /// A path/shape object.
    Path(PathObject),
    /// A text object.
    Text(TextObject),
    /// An image XObject.
    Image(ImageObject),
    /// A form XObject reference.
    Form(FormObject),
}

impl PageObject {
    /// Explicitly destroy (free) a page object that has not been inserted into a page.
    ///
    /// # Not Supported
    ///
    /// Explicit page object lifecycle management is not supported in rpdfium.
    /// Page objects are owned by Rust and released automatically when dropped
    /// (RAII). Calling this method is unnecessary and returns an error.
    ///
    /// Corresponds to `FPDFPageObj_Destroy()`.
    pub fn page_obj_destroy(self) -> crate::error::EditResult<()> {
        // self is consumed (and thus dropped) by this method.
        // We return NotSupported to signal that explicit destruction is unnecessary
        // in rpdfium — Rust's RAII handles it automatically.
        Err(crate::error::EditError::NotSupported(
            "page_obj_destroy: object lifecycle is managed by RAII (ADR-002: Rust ownership model)"
                .into(),
        ))
    }

    /// Returns whether this page object is active (visible in generated content).
    ///
    /// Inactive objects are skipped by `generate_content_stream`.
    ///
    /// Corresponds to `FPDFPageObj_GetIsActive`.
    pub fn is_active(&self) -> bool {
        match self {
            PageObject::Path(p) => p.active,
            PageObject::Text(t) => t.active,
            PageObject::Image(img) => img.active,
            PageObject::Form(f) => f.active,
        }
    }

    /// Upstream-aligned alias for [`is_active()`](Self::is_active).
    ///
    /// Corresponds to `FPDFPageObj_GetIsActive`.
    #[inline]
    pub fn page_obj_get_is_active(&self) -> bool {
        self.is_active()
    }

    /// Non-upstream alias — use [`page_obj_get_is_active()`](Self::page_obj_get_is_active).
    #[deprecated(
        note = "use `page_obj_get_is_active()` — matches upstream `FPDFPageObj_GetIsActive`"
    )]
    #[inline]
    pub fn get_is_active(&self) -> bool {
        self.is_active()
    }

    /// Sets the active flag on this page object.
    ///
    /// Inactive objects are skipped by `generate_content_stream`.
    ///
    /// Corresponds to `FPDFPageObj_SetIsActive`.
    pub fn set_active(&mut self, active: bool) {
        match self {
            PageObject::Path(p) => p.active = active,
            PageObject::Text(t) => t.active = active,
            PageObject::Image(img) => img.active = active,
            PageObject::Form(f) => f.active = active,
        }
    }

    /// Upstream-aligned alias for [`set_active()`](Self::set_active).
    ///
    /// Corresponds to `FPDFPageObj_SetIsActive`.
    #[inline]
    pub fn page_obj_set_is_active(&mut self, active: bool) {
        self.set_active(active)
    }

    /// Non-upstream alias — use [`page_obj_set_is_active()`](Self::page_obj_set_is_active).
    #[deprecated(
        note = "use `page_obj_set_is_active()` — matches upstream `FPDFPageObj_SetIsActive`"
    )]
    #[inline]
    pub fn set_is_active(&mut self, active: bool) {
        self.set_active(active)
    }

    /// Sets the fill color on path and text objects.
    ///
    /// Image and form objects are no-ops.
    ///
    /// Corresponds to `FPDFPageObj_SetFillColor`.
    pub fn set_fill_color(&mut self, color: Color) {
        match self {
            PageObject::Path(p) => p.set_fill_color(color),
            PageObject::Text(t) => t.set_fill_color(color),
            PageObject::Image(_) | PageObject::Form(_) => {}
        }
    }

    /// Upstream-aligned alias for [`set_fill_color()`](Self::set_fill_color).
    ///
    /// Corresponds to `FPDFPageObj_SetFillColor`.
    #[inline]
    pub fn page_obj_set_fill_color(&mut self, color: Color) {
        self.set_fill_color(color)
    }

    /// Returns the fill color from path or text objects.
    ///
    /// Returns `None` for image and form objects.
    ///
    /// Corresponds to `FPDFPageObj_GetFillColor`.
    pub fn fill_color(&self) -> Option<&Color> {
        match self {
            PageObject::Path(p) => p.fill_color(),
            PageObject::Text(t) => t.fill_color(),
            PageObject::Image(_) | PageObject::Form(_) => None,
        }
    }

    /// Upstream-aligned alias for [`fill_color()`](Self::fill_color).
    ///
    /// Corresponds to `FPDFPageObj_GetFillColor`.
    #[inline]
    pub fn page_obj_get_fill_color(&self) -> Option<&Color> {
        self.fill_color()
    }

    /// Non-upstream alias — use [`page_obj_get_fill_color()`](Self::page_obj_get_fill_color).
    #[deprecated(
        note = "use `page_obj_get_fill_color()` — matches upstream `FPDFPageObj_GetFillColor`"
    )]
    #[inline]
    pub fn get_fill_color(&self) -> Option<&Color> {
        self.fill_color()
    }

    /// Sets the stroke color on path and text objects.
    ///
    /// Image and form objects are no-ops.
    ///
    /// Corresponds to `FPDFPageObj_SetStrokeColor`.
    pub fn set_stroke_color(&mut self, color: Color) {
        match self {
            PageObject::Path(p) => p.set_stroke_color(color),
            PageObject::Text(t) => t.set_stroke_color(color),
            PageObject::Image(_) | PageObject::Form(_) => {}
        }
    }

    /// Upstream-aligned alias for [`set_stroke_color()`](Self::set_stroke_color).
    ///
    /// Corresponds to `FPDFPageObj_SetStrokeColor`.
    #[inline]
    pub fn page_obj_set_stroke_color(&mut self, color: Color) {
        self.set_stroke_color(color)
    }

    /// Returns the stroke color from path or text objects.
    ///
    /// Returns `None` for image and form objects.
    ///
    /// Corresponds to `FPDFPageObj_GetStrokeColor`.
    pub fn stroke_color(&self) -> Option<&Color> {
        match self {
            PageObject::Path(p) => p.stroke_color(),
            PageObject::Text(t) => t.stroke_color(),
            PageObject::Image(_) | PageObject::Form(_) => None,
        }
    }

    /// Upstream-aligned alias for [`stroke_color()`](Self::stroke_color).
    ///
    /// Corresponds to `FPDFPageObj_GetStrokeColor`.
    #[inline]
    pub fn page_obj_get_stroke_color(&self) -> Option<&Color> {
        self.stroke_color()
    }

    /// Non-upstream alias — use [`page_obj_get_stroke_color()`](Self::page_obj_get_stroke_color).
    #[deprecated(
        note = "use `page_obj_get_stroke_color()` — matches upstream `FPDFPageObj_GetStrokeColor`"
    )]
    #[inline]
    pub fn get_stroke_color(&self) -> Option<&Color> {
        self.stroke_color()
    }

    /// Returns the axis-aligned bounding box of the page object in page space.
    ///
    /// For `Path` objects, this is the tight bounding box of all segment
    /// control points.  For `Image` and `Form` objects the unit square
    /// `[0,0]–[1,1]` is mapped through the object matrix.  Returns `None`
    /// for `Text` objects (font metrics are required) and for objects with
    /// no geometry (empty path / degenerate matrix).
    ///
    /// Corresponds to `FPDFPageObj_GetBounds`.
    pub fn bounds(&self) -> Option<rpdfium_core::Rect> {
        match self {
            PageObject::Path(p) => p.bounds(),
            PageObject::Image(img) => img.bounds(),
            PageObject::Form(f) => f.bounds(),
            PageObject::Text(_) => None,
        }
    }

    /// Upstream-aligned alias for [`bounds()`](Self::bounds).
    ///
    /// Corresponds to `FPDFPageObj_GetBounds`.
    #[inline]
    pub fn page_obj_get_bounds(&self) -> Option<rpdfium_core::Rect> {
        self.bounds()
    }

    /// Non-upstream alias — use [`page_obj_get_bounds()`](Self::page_obj_get_bounds).
    #[deprecated(note = "use `page_obj_get_bounds()` — matches upstream `FPDFPageObj_GetBounds`")]
    #[inline]
    pub fn get_bounds(&self) -> Option<rpdfium_core::Rect> {
        self.bounds()
    }

    /// Returns the tight rotated bounding quadrilateral for this page object
    /// as 4 corner points in page coordinates.
    ///
    /// For `Text` and `Image` objects, the matrix is used to compute the
    /// rotated corners of the object.  For `Path` and `Form` objects, the
    /// axis-aligned bounding box corners are returned.  Returns `None` if
    /// the object has no computable bounds.
    ///
    /// Corresponds to `FPDFPageObj_GetRotatedBounds`.
    pub fn rotated_bounds(&self) -> Option<[rpdfium_core::Point; 4]> {
        match self {
            PageObject::Text(t) => t.rotated_bounds(),
            PageObject::Image(img) => img.rotated_bounds(),
            PageObject::Path(p) => p.bounds().map(|r| {
                [
                    rpdfium_core::Point {
                        x: r.left,
                        y: r.bottom,
                    },
                    rpdfium_core::Point {
                        x: r.right,
                        y: r.bottom,
                    },
                    rpdfium_core::Point {
                        x: r.right,
                        y: r.top,
                    },
                    rpdfium_core::Point {
                        x: r.left,
                        y: r.top,
                    },
                ]
            }),
            PageObject::Form(f) => f.bounds().map(|r| {
                [
                    rpdfium_core::Point {
                        x: r.left,
                        y: r.bottom,
                    },
                    rpdfium_core::Point {
                        x: r.right,
                        y: r.bottom,
                    },
                    rpdfium_core::Point {
                        x: r.right,
                        y: r.top,
                    },
                    rpdfium_core::Point {
                        x: r.left,
                        y: r.top,
                    },
                ]
            }),
        }
    }

    /// Upstream-aligned alias for [`rotated_bounds()`](Self::rotated_bounds).
    ///
    /// Corresponds to `FPDFPageObj_GetRotatedBounds`.
    #[inline]
    pub fn page_obj_get_rotated_bounds(&self) -> Option<[rpdfium_core::Point; 4]> {
        self.rotated_bounds()
    }

    /// Non-upstream alias — use [`page_obj_get_rotated_bounds()`](Self::page_obj_get_rotated_bounds).
    #[deprecated(
        note = "use `page_obj_get_rotated_bounds()` — matches upstream `FPDFPageObj_GetRotatedBounds`"
    )]
    #[inline]
    pub fn get_rotated_bounds(&self) -> Option<[rpdfium_core::Point; 4]> {
        self.rotated_bounds()
    }

    /// Applies a matrix transform to the page object.
    ///
    /// For `Path` objects the transform is applied to each segment point.
    /// For `Text`, `Image`, and `Form` objects the transform matrix is
    /// pre-multiplied into the object's own matrix.
    ///
    /// Corresponds to `FPDFPageObj_Transform`.
    pub fn transform(&mut self, matrix: &Matrix) {
        match self {
            PageObject::Path(p) => p.transform(matrix),
            PageObject::Text(t) => t.transform(matrix),
            PageObject::Image(img) => img.transform(matrix),
            PageObject::Form(f) => f.transform(matrix),
        }
    }

    /// Upstream-aligned alias for [`transform()`](Self::transform).
    ///
    /// Corresponds to `FPDFPageObj_Transform`.
    #[inline]
    pub fn page_obj_transform(&mut self, matrix: &Matrix) {
        self.transform(matrix)
    }

    /// Upstream-aligned alias for [`transform()`](Self::transform).
    ///
    /// `FPDFPageObj_TransformF` takes an `FS_MATRIX*` struct pointer instead
    /// of six scalar parameters; in rpdfium both variants accept `&Matrix`.
    ///
    /// Corresponds to `FPDFPageObj_TransformF`.
    #[inline]
    pub fn page_obj_transform_f(&mut self, matrix: &Matrix) {
        self.transform(matrix)
    }

    #[deprecated(note = "use `page_obj_transform_f()` — matches upstream `FPDFPageObj_TransformF`")]
    #[inline]
    pub fn transform_f(&mut self, matrix: &Matrix) {
        self.transform(matrix)
    }

    /// Returns the blend mode of this page object.
    ///
    /// Returns `None` for `Normal` (the default, meaning no special blending).
    ///
    /// Corresponds to `FPDFPageObj_GetBlendMode`.
    pub fn blend_mode(&self) -> Option<BlendMode> {
        match self {
            PageObject::Path(p) => p.blend_mode,
            PageObject::Text(t) => t.blend_mode,
            PageObject::Image(img) => img.blend_mode,
            PageObject::Form(f) => f.blend_mode,
        }
    }

    /// Upstream-aligned alias for [`blend_mode()`](Self::blend_mode).
    ///
    /// Corresponds to `FPDFPageObj_GetBlendMode`.
    #[inline]
    pub fn page_obj_get_blend_mode(&self) -> Option<BlendMode> {
        self.blend_mode()
    }

    /// Non-upstream alias — use [`page_obj_get_blend_mode()`](Self::page_obj_get_blend_mode).
    #[deprecated(
        note = "use `page_obj_get_blend_mode()` — matches upstream `FPDFPageObj_GetBlendMode`"
    )]
    #[inline]
    pub fn get_blend_mode(&self) -> Option<BlendMode> {
        self.blend_mode()
    }

    /// Sets the blend mode on this page object.
    ///
    /// Pass `None` (or `Some(BlendMode::Normal)`) for the default blending.
    ///
    /// Corresponds to `FPDFPageObj_SetBlendMode`.
    pub fn set_blend_mode(&mut self, mode: Option<BlendMode>) {
        match self {
            PageObject::Path(p) => p.blend_mode = mode,
            PageObject::Text(t) => t.blend_mode = mode,
            PageObject::Image(img) => img.blend_mode = mode,
            PageObject::Form(f) => f.blend_mode = mode,
        }
    }

    /// Upstream-aligned alias for [`set_blend_mode()`](Self::set_blend_mode).
    ///
    /// Corresponds to `FPDFPageObj_SetBlendMode`.
    #[inline]
    pub fn page_obj_set_blend_mode(&mut self, mode: Option<BlendMode>) {
        self.set_blend_mode(mode)
    }

    // -----------------------------------------------------------------------
    // Matrix dispatch  (FPDFPageObj_GetMatrix / FPDFPageObj_SetMatrix)
    // -----------------------------------------------------------------------

    /// Returns the transformation matrix of this page object.
    ///
    /// For `Image` and `Form` objects this is the object's explicit placement
    /// matrix.  For `Path` objects the identity matrix is returned (path
    /// coordinates are in absolute page space).  For `Text` objects the
    /// identity matrix is returned (text uses its own `Tm` matrix).
    ///
    /// Corresponds to `FPDFPageObj_GetMatrix`.
    pub fn matrix(&self) -> Matrix {
        match self {
            PageObject::Image(img) => *img.matrix(),
            PageObject::Form(f) => *f.matrix(),
            PageObject::Path(p) => p.matrix(),
            PageObject::Text(_) => Matrix::identity(),
        }
    }

    /// Upstream-aligned alias for [`matrix()`](Self::matrix).
    ///
    /// Corresponds to `FPDFPageObj_GetMatrix`.
    #[inline]
    pub fn page_obj_get_matrix(&self) -> Matrix {
        self.matrix()
    }

    /// Non-upstream alias — use [`page_obj_get_matrix()`](Self::page_obj_get_matrix).
    #[deprecated(note = "use `page_obj_get_matrix()` — matches upstream `FPDFPageObj_GetMatrix`")]
    #[inline]
    pub fn get_matrix(&self) -> Matrix {
        self.matrix()
    }

    /// Set the transformation matrix on this page object.
    ///
    /// Effective for `Image` and `Form` objects.  No-op for `Path` and `Text`
    /// objects (use [`transform()`](Self::transform) to apply a transform to
    /// those types).
    ///
    /// Corresponds to `FPDFPageObj_SetMatrix`.
    pub fn set_matrix(&mut self, matrix: Matrix) {
        match self {
            PageObject::Image(img) => img.set_matrix(matrix),
            PageObject::Form(f) => f.set_matrix(matrix),
            PageObject::Path(_) | PageObject::Text(_) => {}
        }
    }

    /// Upstream-aligned alias for [`set_matrix()`](Self::set_matrix).
    ///
    /// Corresponds to `FPDFPageObj_SetMatrix`.
    #[inline]
    pub fn page_obj_set_matrix(&mut self, matrix: Matrix) {
        self.set_matrix(matrix)
    }

    // -----------------------------------------------------------------------
    // Transparency dispatch  (FPDFPageObj_HasTransparency)
    // -----------------------------------------------------------------------

    /// Returns `true` if this page object has any transparency.
    ///
    /// An object is considered transparent when it has a non-`Normal` blend
    /// mode set.
    ///
    /// Corresponds to `FPDFPageObj_HasTransparency`.
    pub fn has_transparency(&self) -> bool {
        match self {
            PageObject::Path(p) => p.has_transparency(),
            PageObject::Text(t) => t.has_transparency(),
            PageObject::Image(img) => img.has_transparency(),
            PageObject::Form(f) => f.has_transparency(),
        }
    }

    /// Non-upstream convenience alias for [`has_transparency()`](Self::has_transparency).
    ///
    /// Prefer [`has_transparency()`](Self::has_transparency), which matches
    /// the upstream `FPDFPageObj_HasTransparency` name exactly.
    #[deprecated(note = "use `has_transparency()` — matches upstream FPDFPageObj_HasTransparency")]
    #[inline]
    pub fn is_transparent(&self) -> bool {
        self.has_transparency()
    }

    // -----------------------------------------------------------------------
    // Content marks dispatch  (FPDFPageObj_CountMarks / GetMark / AddMark /
    //                          RemoveMark / GetMarkedContentID)
    // -----------------------------------------------------------------------

    /// Return the number of content marks on this page object.
    ///
    /// Corresponds to `FPDFPageObj_CountMarks`.
    pub fn mark_count(&self) -> usize {
        match self {
            PageObject::Path(p) => p.mark_count(),
            PageObject::Text(t) => t.mark_count(),
            PageObject::Image(img) => img.mark_count(),
            PageObject::Form(f) => f.mark_count(),
        }
    }

    /// Upstream-aligned alias for [`mark_count()`](Self::mark_count).
    ///
    /// Corresponds to `FPDFPageObj_CountMarks`.
    #[inline]
    pub fn page_obj_count_marks(&self) -> usize {
        self.mark_count()
    }

    /// Non-upstream alias — use [`page_obj_count_marks()`](Self::page_obj_count_marks).
    #[deprecated(note = "use `page_obj_count_marks()` — matches upstream `FPDFPageObj_CountMarks`")]
    #[inline]
    pub fn count_marks(&self) -> usize {
        self.mark_count()
    }

    /// Return the content mark at the given index, or `None` if out of range.
    ///
    /// Corresponds to `FPDFPageObj_GetMark`.
    pub fn mark(&self, index: usize) -> Option<&ContentMark> {
        match self {
            PageObject::Path(p) => p.mark(index),
            PageObject::Text(t) => t.mark(index),
            PageObject::Image(img) => img.mark(index),
            PageObject::Form(f) => f.mark(index),
        }
    }

    /// Upstream-aligned alias for [`mark()`](Self::mark).
    ///
    /// Corresponds to `FPDFPageObj_GetMark`.
    #[inline]
    pub fn page_obj_get_mark(&self, index: usize) -> Option<&ContentMark> {
        self.mark(index)
    }

    /// Non-upstream alias — use [`page_obj_get_mark()`](Self::page_obj_get_mark).
    #[deprecated(note = "use `page_obj_get_mark()` — matches upstream `FPDFPageObj_GetMark`")]
    #[inline]
    pub fn get_mark(&self, index: usize) -> Option<&ContentMark> {
        self.mark(index)
    }

    /// Add a new content mark with the given name and return a mutable
    /// reference to it.
    ///
    /// Corresponds to `FPDFPageObj_AddMark`.
    pub fn add_mark(&mut self, name: impl Into<String>) -> &mut ContentMark {
        match self {
            PageObject::Path(p) => p.add_mark(name),
            PageObject::Text(t) => t.add_mark(name),
            PageObject::Image(img) => img.add_mark(name),
            PageObject::Form(f) => f.add_mark(name),
        }
    }

    /// Upstream-aligned alias for [`add_mark()`](Self::add_mark).
    ///
    /// Corresponds to `FPDFPageObj_AddMark`.
    #[inline]
    pub fn page_obj_add_mark(&mut self, name: impl Into<String>) -> &mut ContentMark {
        self.add_mark(name)
    }

    /// Remove the content mark at the given index.
    ///
    /// Returns `true` if the index was valid and the mark was removed, `false`
    /// if out of range.
    ///
    /// Corresponds to `FPDFPageObj_RemoveMark`.
    pub fn remove_mark(&mut self, index: usize) -> bool {
        match self {
            PageObject::Path(p) => p.remove_mark(index),
            PageObject::Text(t) => t.remove_mark(index),
            PageObject::Image(img) => img.remove_mark(index),
            PageObject::Form(f) => f.remove_mark(index),
        }
    }

    /// Upstream-aligned alias for [`remove_mark()`](Self::remove_mark).
    ///
    /// Corresponds to `FPDFPageObj_RemoveMark`.
    #[inline]
    pub fn page_obj_remove_mark(&mut self, index: usize) -> bool {
        self.remove_mark(index)
    }

    /// Return the marked content ID (`/MCID`) from the first mark that has one,
    /// or `None` if no mark carries an MCID.
    ///
    /// Corresponds to `FPDFPageObj_GetMarkedContentID`.
    pub fn marked_content_id(&self) -> Option<i64> {
        match self {
            PageObject::Path(p) => p.marked_content_id(),
            PageObject::Text(t) => t.marked_content_id(),
            PageObject::Image(img) => img.marked_content_id(),
            PageObject::Form(f) => f.marked_content_id(),
        }
    }

    /// Upstream-aligned alias for [`marked_content_id()`](Self::marked_content_id).
    ///
    /// Corresponds to `FPDFPageObj_GetMarkedContentID`.
    #[inline]
    pub fn page_obj_get_marked_content_id(&self) -> Option<i64> {
        self.marked_content_id()
    }

    /// Non-upstream alias — use [`page_obj_get_marked_content_id()`](Self::page_obj_get_marked_content_id).
    #[deprecated(
        note = "use `page_obj_get_marked_content_id()` — matches upstream `FPDFPageObj_GetMarkedContentID`"
    )]
    #[inline]
    pub fn get_marked_content_id(&self) -> Option<i64> {
        self.marked_content_id()
    }

    // -----------------------------------------------------------------------
    // Clip path dispatch  (FPDFPageObj_GetClipPath / TransformClipPath)
    // -----------------------------------------------------------------------

    /// Returns a reference to the clip path, if one is attached.
    ///
    /// Corresponds to `FPDFPageObj_GetClipPath`.
    pub fn clip_path(&self) -> Option<&ClipPath> {
        match self {
            PageObject::Path(p) => p.clip_path.as_ref(),
            PageObject::Text(t) => t.clip_path.as_ref(),
            PageObject::Image(img) => img.clip_path.as_ref(),
            PageObject::Form(f) => f.clip_path.as_ref(),
        }
    }

    /// Upstream-aligned alias for [`clip_path()`](Self::clip_path).
    ///
    /// Corresponds to `FPDFPageObj_GetClipPath`.
    #[inline]
    pub fn page_obj_get_clip_path(&self) -> Option<&ClipPath> {
        self.clip_path()
    }

    /// Deprecated — use [`page_obj_get_clip_path()`](Self::page_obj_get_clip_path) instead.
    ///
    /// Corresponds to `FPDFPageObj_GetClipPath`.
    #[deprecated(
        note = "use `page_obj_get_clip_path()` — matches upstream `FPDFPageObj_GetClipPath`"
    )]
    #[inline]
    pub fn get_clip_path(&self) -> Option<&ClipPath> {
        self.clip_path()
    }

    /// Sets or clears the clip path on this page object.
    pub fn set_clip_path(&mut self, clip: Option<ClipPath>) {
        match self {
            PageObject::Path(p) => p.clip_path = clip,
            PageObject::Text(t) => t.clip_path = clip,
            PageObject::Image(img) => img.clip_path = clip,
            PageObject::Form(f) => f.clip_path = clip,
        }
    }

    /// Applies a matrix transform to the clip path attached to this object.
    ///
    /// No-op if the object has no clip path.
    ///
    /// Corresponds to `FPDFPageObj_TransformClipPath`.
    pub fn transform_clip_path(&mut self, matrix: &Matrix) {
        let clip = match self {
            PageObject::Path(p) => p.clip_path.as_mut(),
            PageObject::Text(t) => t.clip_path.as_mut(),
            PageObject::Image(img) => img.clip_path.as_mut(),
            PageObject::Form(f) => f.clip_path.as_mut(),
        };
        if let Some(c) = clip {
            c.transform(matrix);
        }
    }

    /// Upstream alias for [`PageObject::transform_clip_path`].
    ///
    /// Tier-2 name for `FPDFPageObj_TransformClipPath`.
    #[inline]
    pub fn page_obj_transform_clip_path(&mut self, matrix: &Matrix) {
        self.transform_clip_path(matrix);
    }

    /// Returns `true` if this is a text object (`FPDF_PAGEOBJ_TEXT`).
    pub fn is_text(&self) -> bool {
        matches!(self, PageObject::Text(_))
    }

    /// Returns `true` if this is a path object (`FPDF_PAGEOBJ_PATH`).
    pub fn is_path(&self) -> bool {
        matches!(self, PageObject::Path(_))
    }

    /// Returns `true` if this is an image object (`FPDF_PAGEOBJ_IMAGE`).
    pub fn is_image(&self) -> bool {
        matches!(self, PageObject::Image(_))
    }

    /// Returns `true` if this is a form XObject reference (`FPDF_PAGEOBJ_FORM`).
    pub fn is_form(&self) -> bool {
        matches!(self, PageObject::Form(_))
    }

    /// Returns the PDFium page-object-type constant for this object.
    ///
    /// - Path  → `2` (`FPDF_PAGEOBJ_PATH`)
    /// - Text  → `1` (`FPDF_PAGEOBJ_TEXT`)
    /// - Image → `3` (`FPDF_PAGEOBJ_IMAGE`)
    /// - Form  → `5` (`FPDF_PAGEOBJ_FORM`)
    ///
    /// Corresponds to `FPDFPageObj_GetType`.
    pub fn object_type(&self) -> u32 {
        match self {
            PageObject::Path(o) => o.object_type(),
            PageObject::Text(o) => o.object_type(),
            PageObject::Image(o) => o.object_type(),
            PageObject::Form(o) => o.object_type(),
        }
    }

    /// Upstream-aligned alias for [`object_type()`](Self::object_type).
    ///
    /// Corresponds to `FPDFPageObj_GetType`.
    #[inline]
    pub fn page_obj_get_type(&self) -> u32 {
        self.object_type()
    }

    /// Non-upstream alias — use [`page_obj_get_type()`](Self::page_obj_get_type).
    ///
    /// The actual upstream function is `FPDFPageObj_GetType`; there is no
    /// `FPDFPageObj_GetObjectType`.
    #[deprecated(note = "use `page_obj_get_type()` — matches upstream FPDFPageObj_GetType")]
    #[inline]
    pub fn get_object_type(&self) -> u32 {
        self.object_type()
    }

    /// Non-upstream alias — use [`page_obj_get_type()`](Self::page_obj_get_type).
    #[deprecated(note = "use `page_obj_get_type()` — matches upstream FPDFPageObj_GetType")]
    #[inline]
    pub fn get_type(&self) -> u32 {
        self.object_type()
    }

    // -----------------------------------------------------------------------
    // Stroke width dispatch  (FPDFPageObj_GetStrokeWidth / SetStrokeWidth)
    // -----------------------------------------------------------------------

    /// Returns the stroke width of this page object.
    ///
    /// Returns `None` for text, image, and form objects (only path objects
    /// track a per-object stroke width in rpdfium's current model).
    ///
    /// Corresponds to `FPDFPageObj_GetStrokeWidth`.
    pub fn stroke_width(&self) -> Option<f32> {
        match self {
            PageObject::Path(p) => Some(p.line_width()),
            PageObject::Text(_) | PageObject::Image(_) | PageObject::Form(_) => None,
        }
    }

    /// Upstream-aligned alias for [`stroke_width()`](Self::stroke_width).
    ///
    /// Corresponds to `FPDFPageObj_GetStrokeWidth`.
    #[inline]
    pub fn page_obj_get_stroke_width(&self) -> Option<f32> {
        self.stroke_width()
    }

    #[deprecated(
        note = "use `page_obj_get_stroke_width()` — matches upstream `FPDFPageObj_GetStrokeWidth`"
    )]
    #[inline]
    pub fn get_stroke_width(&self) -> Option<f32> {
        self.stroke_width()
    }

    /// Sets the stroke width on path objects.
    ///
    /// No-op for text, image, and form objects.
    ///
    /// Corresponds to `FPDFPageObj_SetStrokeWidth`.
    pub fn set_stroke_width(&mut self, width: f32) {
        match self {
            PageObject::Path(p) => p.set_line_width(width),
            PageObject::Text(_) | PageObject::Image(_) | PageObject::Form(_) => {}
        }
    }

    /// Upstream-aligned alias for [`set_stroke_width()`](Self::set_stroke_width).
    ///
    /// Corresponds to `FPDFPageObj_SetStrokeWidth`.
    #[inline]
    pub fn page_obj_set_stroke_width(&mut self, width: f32) {
        self.set_stroke_width(width)
    }

    // -----------------------------------------------------------------------
    // Line join dispatch  (FPDFPageObj_GetLineJoin / SetLineJoin)
    // -----------------------------------------------------------------------

    /// Returns the line join style of this page object.
    ///
    /// Returns `None` for non-path objects that have no line join.
    ///
    /// Corresponds to `FPDFPageObj_GetLineJoin`.
    pub fn line_join(&self) -> Option<u8> {
        match self {
            PageObject::Path(p) => Some(p.line_join()),
            PageObject::Text(_) | PageObject::Image(_) | PageObject::Form(_) => None,
        }
    }

    /// Upstream-aligned alias for [`line_join()`](Self::line_join).
    ///
    /// Corresponds to `FPDFPageObj_GetLineJoin`.
    #[inline]
    pub fn page_obj_get_line_join(&self) -> Option<u8> {
        self.line_join()
    }

    #[deprecated(
        note = "use `page_obj_get_line_join()` — matches upstream `FPDFPageObj_GetLineJoin`"
    )]
    #[inline]
    pub fn get_line_join(&self) -> Option<u8> {
        self.line_join()
    }

    /// Sets the line join style on path objects.
    ///
    /// No-op for text, image, and form objects.
    ///
    /// Corresponds to `FPDFPageObj_SetLineJoin`.
    pub fn set_line_join(&mut self, join: u8) {
        match self {
            PageObject::Path(p) => p.set_line_join(join),
            PageObject::Text(_) | PageObject::Image(_) | PageObject::Form(_) => {}
        }
    }

    /// Upstream-aligned alias for [`set_line_join()`](Self::set_line_join).
    ///
    /// Corresponds to `FPDFPageObj_SetLineJoin`.
    #[inline]
    pub fn page_obj_set_line_join(&mut self, join: u8) {
        self.set_line_join(join)
    }

    // -----------------------------------------------------------------------
    // Line cap dispatch  (FPDFPageObj_GetLineCap / SetLineCap)
    // -----------------------------------------------------------------------

    /// Returns the line cap style of this page object.
    ///
    /// Returns `None` for non-path objects that have no line cap.
    ///
    /// Corresponds to `FPDFPageObj_GetLineCap`.
    pub fn line_cap(&self) -> Option<u8> {
        match self {
            PageObject::Path(p) => Some(p.line_cap()),
            PageObject::Text(_) | PageObject::Image(_) | PageObject::Form(_) => None,
        }
    }

    /// Upstream-aligned alias for [`line_cap()`](Self::line_cap).
    ///
    /// Corresponds to `FPDFPageObj_GetLineCap`.
    #[inline]
    pub fn page_obj_get_line_cap(&self) -> Option<u8> {
        self.line_cap()
    }

    #[deprecated(
        note = "use `page_obj_get_line_cap()` — matches upstream `FPDFPageObj_GetLineCap`"
    )]
    #[inline]
    pub fn get_line_cap(&self) -> Option<u8> {
        self.line_cap()
    }

    /// Sets the line cap style on path objects.
    ///
    /// No-op for text, image, and form objects.
    ///
    /// Corresponds to `FPDFPageObj_SetLineCap`.
    pub fn set_line_cap(&mut self, cap: u8) {
        match self {
            PageObject::Path(p) => p.set_line_cap(cap),
            PageObject::Text(_) | PageObject::Image(_) | PageObject::Form(_) => {}
        }
    }

    /// Upstream-aligned alias for [`set_line_cap()`](Self::set_line_cap).
    ///
    /// Corresponds to `FPDFPageObj_SetLineCap`.
    #[inline]
    pub fn page_obj_set_line_cap(&mut self, cap: u8) {
        self.set_line_cap(cap)
    }

    // -----------------------------------------------------------------------
    // Dash pattern dispatch  (FPDFPageObj_GetDashPhase / SetDashPhase /
    //                         FPDFPageObj_GetDashCount / GetDashArray /
    //                         SetDashArray)
    // -----------------------------------------------------------------------

    /// Returns the dash phase of this page object.
    ///
    /// Returns `None` for non-path objects that have no dash pattern.
    ///
    /// Corresponds to `FPDFPageObj_GetDashPhase`.
    pub fn dash_phase(&self) -> Option<f32> {
        match self {
            PageObject::Path(p) => Some(p.dash_phase()),
            PageObject::Text(_) | PageObject::Image(_) | PageObject::Form(_) => None,
        }
    }

    /// Upstream-aligned alias for [`dash_phase()`](Self::dash_phase).
    ///
    /// Corresponds to `FPDFPageObj_GetDashPhase`.
    #[inline]
    pub fn page_obj_get_dash_phase(&self) -> Option<f32> {
        self.dash_phase()
    }

    #[deprecated(
        note = "use `page_obj_get_dash_phase()` — matches upstream `FPDFPageObj_GetDashPhase`"
    )]
    #[inline]
    pub fn get_dash_phase(&self) -> Option<f32> {
        self.dash_phase()
    }

    /// Sets the dash phase on path objects.
    ///
    /// No-op for text, image, and form objects.
    ///
    /// Corresponds to `FPDFPageObj_SetDashPhase`.
    pub fn set_dash_phase(&mut self, phase: f32) {
        match self {
            PageObject::Path(p) => p.set_dash_phase(phase),
            PageObject::Text(_) | PageObject::Image(_) | PageObject::Form(_) => {}
        }
    }

    /// Upstream-aligned alias for [`set_dash_phase()`](Self::set_dash_phase).
    ///
    /// Corresponds to `FPDFPageObj_SetDashPhase`.
    #[inline]
    pub fn page_obj_set_dash_phase(&mut self, phase: f32) {
        self.set_dash_phase(phase)
    }

    /// Returns the number of elements in the dash array of this page object.
    ///
    /// Returns `None` for non-path objects that have no dash pattern.
    ///
    /// Corresponds to `FPDFPageObj_GetDashCount`.
    pub fn dash_count(&self) -> Option<usize> {
        match self {
            PageObject::Path(p) => Some(p.dash_count()),
            PageObject::Text(_) | PageObject::Image(_) | PageObject::Form(_) => None,
        }
    }

    /// Upstream-aligned alias for [`dash_count()`](Self::dash_count).
    ///
    /// Corresponds to `FPDFPageObj_GetDashCount`.
    #[inline]
    pub fn page_obj_get_dash_count(&self) -> Option<usize> {
        self.dash_count()
    }

    #[deprecated(
        note = "use `page_obj_get_dash_count()` — matches upstream `FPDFPageObj_GetDashCount`"
    )]
    #[inline]
    pub fn get_dash_count(&self) -> Option<usize> {
        self.dash_count()
    }

    /// Returns the dash array of this page object.
    ///
    /// Returns `None` for non-path objects that have no dash pattern.
    ///
    /// Corresponds to `FPDFPageObj_GetDashArray`.
    pub fn dash_array(&self) -> Option<&[f32]> {
        match self {
            PageObject::Path(p) => Some(p.dash_array()),
            PageObject::Text(_) | PageObject::Image(_) | PageObject::Form(_) => None,
        }
    }

    /// Upstream-aligned alias for [`dash_array()`](Self::dash_array).
    ///
    /// Corresponds to `FPDFPageObj_GetDashArray`.
    #[inline]
    pub fn page_obj_get_dash_array(&self) -> Option<&[f32]> {
        self.dash_array()
    }

    #[deprecated(
        note = "use `page_obj_get_dash_array()` — matches upstream `FPDFPageObj_GetDashArray`"
    )]
    #[inline]
    pub fn get_dash_array(&self) -> Option<&[f32]> {
        self.dash_array()
    }

    /// Sets the dash array and phase on path objects.
    ///
    /// No-op for text, image, and form objects.
    ///
    /// Corresponds to `FPDFPageObj_SetDashArray`.
    pub fn set_dash_array(&mut self, array: Vec<f32>, phase: f32) {
        match self {
            PageObject::Path(p) => p.set_dash_array(array, phase),
            PageObject::Text(_) | PageObject::Image(_) | PageObject::Form(_) => {}
        }
    }

    /// Upstream-aligned alias for [`set_dash_array()`](Self::set_dash_array).
    ///
    /// Corresponds to `FPDFPageObj_SetDashArray`.
    #[inline]
    pub fn page_obj_set_dash_array(&mut self, array: Vec<f32>, phase: f32) {
        self.set_dash_array(array, phase)
    }
}

/// Fill mode for path objects.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum FillMode {
    /// No fill.
    None,
    /// Even-odd fill rule (alternate).
    EvenOdd,
    /// Non-zero winding fill rule.
    NonZero,
}

/// A segment of a path.
#[derive(Debug, Clone)]
pub enum PathSegment {
    /// Move to (x, y).
    MoveTo(f64, f64),
    /// Line to (x, y).
    LineTo(f64, f64),
    /// Cubic Bezier to (x1, y1, x2, y2, x3, y3).
    CurveTo(f64, f64, f64, f64, f64, f64),
    /// Rectangle at (x, y, w, h).
    Rect(f64, f64, f64, f64),
    /// Close the current subpath.
    Close,
}

impl PathSegment {
    /// Returns the endpoint coordinates of this segment, or `None` for
    /// `Close` segments.
    ///
    /// For `MoveTo` and `LineTo` segments returns `Some((x, y))`.
    /// For `CurveTo` segments returns `Some((x3, y3))` — the endpoint.
    /// For `Rect` segments returns `Some((x, y))` — the origin corner.
    /// For `Close` returns `None`.
    ///
    /// Corresponds to `FPDFPathSegment_GetPoint`.
    pub fn point(&self) -> Option<(f64, f64)> {
        match self {
            PathSegment::MoveTo(x, y) => Some((*x, *y)),
            PathSegment::LineTo(x, y) => Some((*x, *y)),
            PathSegment::CurveTo(_, _, _, _, x3, y3) => Some((*x3, *y3)),
            PathSegment::Rect(x, y, _, _) => Some((*x, *y)),
            PathSegment::Close => None,
        }
    }

    /// Upstream-aligned alias for [`point()`](Self::point).
    ///
    /// Corresponds to `FPDFPathSegment_GetPoint`.
    #[inline]
    pub fn path_segment_get_point(&self) -> Option<(f64, f64)> {
        self.point()
    }

    #[deprecated(
        note = "use `path_segment_get_point()` — matches upstream `FPDFPathSegment_GetPoint`"
    )]
    #[inline]
    pub fn get_point(&self) -> Option<(f64, f64)> {
        self.point()
    }

    /// Returns the numeric segment type code for this segment.
    ///
    /// Returns:
    /// - `FPDF_SEGMENT_MOVETO` (1) for `MoveTo`
    /// - `FPDF_SEGMENT_LINETO` (2) for `LineTo`
    /// - `FPDF_SEGMENT_BEZIERTO` (3) for `CurveTo` (Bezier)
    /// - `FPDF_SEGMENT_UNKNOWN` (−1) for `Close` and `Rect`
    ///
    /// Corresponds to `FPDFPathSegment_GetType`.
    pub fn segment_type(&self) -> i32 {
        match self {
            PathSegment::MoveTo(_, _) => 1,              // FPDF_SEGMENT_MOVETO
            PathSegment::LineTo(_, _) => 2,              // FPDF_SEGMENT_LINETO
            PathSegment::CurveTo(_, _, _, _, _, _) => 3, // FPDF_SEGMENT_BEZIERTO
            PathSegment::Rect(_, _, _, _) => -1,         // FPDF_SEGMENT_UNKNOWN
            PathSegment::Close => -1,                    // FPDF_SEGMENT_UNKNOWN
        }
    }

    /// Upstream-aligned alias for [`segment_type()`](Self::segment_type).
    ///
    /// Corresponds to `FPDFPathSegment_GetType`.
    #[inline]
    pub fn path_segment_get_type(&self) -> i32 {
        self.segment_type()
    }

    #[deprecated(
        note = "use `path_segment_get_type()` — matches upstream `FPDFPathSegment_GetType`"
    )]
    #[inline]
    pub fn get_type(&self) -> i32 {
        self.segment_type()
    }

    /// Returns whether this segment closes the current subpath.
    ///
    /// Returns `true` only for `Close` segments.
    ///
    /// Corresponds to `FPDFPathSegment_GetClose`.
    pub fn is_close(&self) -> bool {
        matches!(self, PathSegment::Close)
    }

    /// Upstream-aligned alias for [`is_close()`](Self::is_close).
    ///
    /// Corresponds to `FPDFPathSegment_GetClose`.
    #[inline]
    pub fn path_segment_get_close(&self) -> bool {
        self.is_close()
    }

    #[deprecated(
        note = "use `path_segment_get_close()` — matches upstream `FPDFPathSegment_GetClose`"
    )]
    #[inline]
    pub fn get_close(&self) -> bool {
        self.is_close()
    }
}

/// A path/shape object with fill and stroke properties.
#[derive(Debug, Clone)]
pub struct PathObject {
    /// Path segments.
    pub segments: Vec<PathSegment>,
    /// Transformation matrix.
    pub matrix: Matrix,
    /// Fill color (None = no fill).
    pub fill_color: Option<Color>,
    /// Stroke color (None = no stroke).
    pub stroke_color: Option<Color>,
    /// Line width for stroking.
    pub line_width: f32,
    /// Line cap style (0=butt, 1=round, 2=square).
    pub line_cap: u8,
    /// Line join style (0=miter, 1=round, 2=bevel).
    pub line_join: u8,
    /// Fill mode.
    pub fill_mode: FillMode,
    /// Dash pattern for stroking (None = solid line).
    ///
    /// Corresponds to `FPDFPath_GetDashArray` / `FPDFPath_SetDashArray`.
    pub dash_pattern: Option<DashPattern>,
    /// Blend mode for compositing.
    ///
    /// Corresponds to `FPDFPageObj_GetBlendMode` / `FPDFPageObj_SetBlendMode`.
    pub blend_mode: Option<BlendMode>,
    /// Whether the object is active (visible).
    ///
    /// Corresponds to `FPDFPageObj_GetIsActive` / `FPDFPageObj_SetIsActive`.
    pub active: bool,
    /// Content marks attached to this object (for tagged PDF / accessibility).
    ///
    /// Each mark corresponds to a `BDC`…`EMC` pair wrapping this object in
    /// the content stream.
    ///
    /// Corresponds to `FPDFPageObj_CountMarks` / `FPDFPageObj_GetMark` / etc.
    pub marks: Vec<ContentMark>,
    /// Optional clipping path attached to this object.
    ///
    /// Corresponds to `FPDFPageObj_GetClipPath` / `FPDFPageObj_TransformClipPath`.
    pub clip_path: Option<ClipPath>,
}

impl Default for PathObject {
    fn default() -> Self {
        Self {
            segments: Vec::new(),
            matrix: Matrix::identity(),
            fill_color: None,
            stroke_color: None,
            line_width: 1.0,
            line_cap: 0,
            line_join: 0,
            fill_mode: FillMode::None,
            dash_pattern: None,
            blend_mode: None,
            active: true,
            marks: Vec::new(),
            clip_path: None,
        }
    }
}

impl PathObject {
    /// Sets the fill color.
    ///
    /// Corresponds to `FPDFPageObj_SetFillColor`.
    pub fn set_fill_color(&mut self, color: Color) {
        self.fill_color = Some(color);
    }

    /// Returns the fill color, if set (upstream `FPDFPageObj_GetFillColor`).
    pub fn fill_color(&self) -> Option<&Color> {
        self.fill_color.as_ref()
    }

    /// Upstream-aligned alias for [`fill_color()`](Self::fill_color).
    ///
    /// Corresponds to `FPDFPageObj_GetFillColor`.
    #[inline]
    pub fn page_obj_get_fill_color(&self) -> Option<&Color> {
        self.fill_color()
    }

    /// Non-upstream alias — use [`page_obj_get_fill_color()`](Self::page_obj_get_fill_color).
    ///
    /// Corresponds to `FPDFPageObj_GetFillColor`.
    #[deprecated(
        note = "use `page_obj_get_fill_color()` — matches upstream `FPDFPageObj_GetFillColor`"
    )]
    #[inline]
    pub fn get_fill_color(&self) -> Option<&Color> {
        self.fill_color()
    }

    /// Sets the stroke color.
    ///
    /// Corresponds to `FPDFPageObj_SetStrokeColor`.
    pub fn set_stroke_color(&mut self, color: Color) {
        self.stroke_color = Some(color);
    }

    /// Returns the stroke color, if set (upstream `FPDFPageObj_GetStrokeColor`).
    pub fn stroke_color(&self) -> Option<&Color> {
        self.stroke_color.as_ref()
    }

    /// Upstream-aligned alias for [`stroke_color()`](Self::stroke_color).
    ///
    /// Corresponds to `FPDFPageObj_GetStrokeColor`.
    #[inline]
    pub fn page_obj_get_stroke_color(&self) -> Option<&Color> {
        self.stroke_color()
    }

    /// Non-upstream alias — use [`page_obj_get_stroke_color()`](Self::page_obj_get_stroke_color).
    ///
    /// Corresponds to `FPDFPageObj_GetStrokeColor`.
    #[deprecated(
        note = "use `page_obj_get_stroke_color()` — matches upstream `FPDFPageObj_GetStrokeColor`"
    )]
    #[inline]
    pub fn get_stroke_color(&self) -> Option<&Color> {
        self.stroke_color()
    }

    /// Sets the stroke (line) width.
    ///
    /// Corresponds to `FPDFPageObj_SetStrokeWidth`.
    pub fn set_line_width(&mut self, width: f32) {
        self.line_width = width;
    }

    /// Upstream-aligned alias for [`Self::set_line_width()`].
    ///
    /// Corresponds to `FPDFPageObj_SetStrokeWidth`.
    #[inline]
    pub fn page_obj_set_stroke_width(&mut self, width: f32) {
        self.set_line_width(width);
    }

    /// Non-upstream alias — use [`page_obj_set_stroke_width()`](Self::page_obj_set_stroke_width).
    ///
    /// Corresponds to `FPDFPageObj_SetStrokeWidth`.
    #[deprecated(
        note = "use `page_obj_set_stroke_width()` — matches upstream `FPDFPageObj_SetStrokeWidth`"
    )]
    #[inline]
    pub fn set_stroke_width(&mut self, width: f32) {
        self.set_line_width(width);
    }

    /// Returns the stroke (line) width (upstream `FPDFPageObj_GetStrokeWidth`).
    pub fn line_width(&self) -> f32 {
        self.line_width
    }

    /// Non-upstream alias — use [`page_obj_get_stroke_width()`](Self::page_obj_get_stroke_width).
    ///
    /// There is no `FPDFPageObj_GetLineWidth`; the upstream function is
    /// `FPDFPageObj_GetStrokeWidth`.
    #[deprecated(
        note = "use `page_obj_get_stroke_width()` — matches upstream FPDFPageObj_GetStrokeWidth"
    )]
    #[inline]
    pub fn get_line_width(&self) -> f32 {
        self.line_width()
    }

    /// Upstream-aligned alias for [`line_width()`](Self::line_width).
    ///
    /// Corresponds to `FPDFPageObj_GetStrokeWidth`.
    #[inline]
    pub fn page_obj_get_stroke_width(&self) -> f32 {
        self.line_width()
    }

    /// Non-upstream alias — use [`page_obj_get_stroke_width()`](Self::page_obj_get_stroke_width).
    ///
    /// Corresponds to `FPDFPageObj_GetStrokeWidth`.
    #[deprecated(
        note = "use `page_obj_get_stroke_width()` — matches upstream `FPDFPageObj_GetStrokeWidth`"
    )]
    #[inline]
    pub fn get_stroke_width(&self) -> f32 {
        self.line_width()
    }

    /// Sets the line join style (0=miter, 1=round, 2=bevel).
    ///
    /// Corresponds to `FPDFPageObj_SetLineJoin`.
    pub fn set_line_join(&mut self, join: u8) {
        self.line_join = join;
    }

    /// Returns the line join style (upstream `FPDFPageObj_GetLineJoin`).
    pub fn line_join(&self) -> u8 {
        self.line_join
    }

    /// Upstream-aligned alias for [`line_join()`](Self::line_join).
    ///
    /// Corresponds to `FPDFPageObj_GetLineJoin`.
    #[inline]
    pub fn page_obj_get_line_join(&self) -> u8 {
        self.line_join()
    }

    /// Non-upstream alias — use [`page_obj_get_line_join()`](Self::page_obj_get_line_join).
    ///
    /// Corresponds to `FPDFPageObj_GetLineJoin`.
    #[deprecated(
        note = "use `page_obj_get_line_join()` — matches upstream `FPDFPageObj_GetLineJoin`"
    )]
    #[inline]
    pub fn get_line_join(&self) -> u8 {
        self.line_join()
    }

    /// Sets the line cap style (0=butt, 1=round, 2=square).
    ///
    /// Corresponds to `FPDFPageObj_SetLineCap`.
    pub fn set_line_cap(&mut self, cap: u8) {
        self.line_cap = cap;
    }

    /// Returns the line cap style (upstream `FPDFPageObj_GetLineCap`).
    pub fn line_cap(&self) -> u8 {
        self.line_cap
    }

    /// Upstream-aligned alias for [`line_cap()`](Self::line_cap).
    ///
    /// Corresponds to `FPDFPageObj_GetLineCap`.
    #[inline]
    pub fn page_obj_get_line_cap(&self) -> u8 {
        self.line_cap()
    }

    /// Non-upstream alias — use [`page_obj_get_line_cap()`](Self::page_obj_get_line_cap).
    ///
    /// Corresponds to `FPDFPageObj_GetLineCap`.
    #[deprecated(
        note = "use `page_obj_get_line_cap()` — matches upstream `FPDFPageObj_GetLineCap`"
    )]
    #[inline]
    pub fn get_line_cap(&self) -> u8 {
        self.line_cap()
    }

    // -----------------------------------------------------------------------
    // Dash pattern API  (FPDFPath_GetDashPhase / GetDashCount / GetDashArray /
    //                    FPDFPath_SetDashArray / SetDashPhase)
    // -----------------------------------------------------------------------

    /// Returns the current dash pattern, if any.
    ///
    /// Corresponds to `FPDFPath_GetDashArray` + `FPDFPath_GetDashPhase`.
    pub fn dash_pattern(&self) -> Option<&DashPattern> {
        self.dash_pattern.as_ref()
    }

    /// Sets or clears the dash pattern.
    ///
    /// Pass `None` to revert to a solid stroke.
    ///
    /// Corresponds to `FPDFPath_SetDashArray`.
    pub fn set_dash_pattern(&mut self, pattern: Option<DashPattern>) {
        self.dash_pattern = pattern;
    }

    /// Returns the dash phase offset.
    ///
    /// Returns `0.0` when no dash pattern is set.
    ///
    /// Corresponds to `FPDFPath_GetDashPhase`.
    pub fn dash_phase(&self) -> f32 {
        self.dash_pattern.as_ref().map(|d| d.phase).unwrap_or(0.0)
    }

    /// Upstream-aligned alias for [`dash_phase()`](Self::dash_phase).
    ///
    /// Corresponds to `FPDFPath_GetDashPhase`.
    #[inline]
    pub fn path_get_dash_phase(&self) -> f32 {
        self.dash_phase()
    }

    /// Non-upstream alias — use [`path_get_dash_phase()`](Self::path_get_dash_phase).
    ///
    /// Corresponds to `FPDFPath_GetDashPhase`.
    #[deprecated(note = "use `path_get_dash_phase()` — matches upstream `FPDFPath_GetDashPhase`")]
    #[inline]
    pub fn get_dash_phase(&self) -> f32 {
        self.dash_phase()
    }

    /// Sets the dash phase on the existing dash pattern.
    ///
    /// If no dash pattern is set, this is a no-op.
    ///
    /// Corresponds to `FPDFPath_SetDashPhase`.
    pub fn set_dash_phase(&mut self, phase: f32) {
        if let Some(ref mut d) = self.dash_pattern {
            d.phase = phase;
        }
    }

    /// Returns the number of elements in the dash array.
    ///
    /// Returns `0` when no dash pattern is set.
    ///
    /// Corresponds to `FPDFPageObj_GetDashCount`.
    pub fn dash_count(&self) -> usize {
        self.dash_pattern
            .as_ref()
            .map(|d| d.array.len())
            .unwrap_or(0)
    }

    /// Upstream-aligned alias for [`dash_count()`](Self::dash_count).
    ///
    /// Corresponds to `FPDFPageObj_GetDashCount`.
    #[inline]
    pub fn page_obj_get_dash_count(&self) -> usize {
        self.dash_count()
    }

    /// Non-upstream alias — use [`page_obj_get_dash_count()`](Self::page_obj_get_dash_count).
    ///
    /// Corresponds to `FPDFPageObj_GetDashCount`.
    #[deprecated(
        note = "use `page_obj_get_dash_count()` — matches upstream `FPDFPageObj_GetDashCount`"
    )]
    #[inline]
    pub fn get_dash_count(&self) -> usize {
        self.dash_count()
    }

    /// Returns the dash array (alternating dash/gap lengths).
    ///
    /// Returns an empty slice when no dash pattern is set.
    ///
    /// Corresponds to `FPDFPath_GetDashArray`.
    pub fn dash_array(&self) -> &[f32] {
        self.dash_pattern
            .as_ref()
            .map(|d| d.array.as_slice())
            .unwrap_or(&[])
    }

    /// Upstream-aligned alias for [`dash_array()`](Self::dash_array).
    ///
    /// Corresponds to `FPDFPath_GetDashArray`.
    #[inline]
    pub fn path_get_dash_array(&self) -> &[f32] {
        self.dash_array()
    }

    /// Non-upstream alias — use [`path_get_dash_array()`](Self::path_get_dash_array).
    ///
    /// Corresponds to `FPDFPath_GetDashArray`.
    #[deprecated(note = "use `path_get_dash_array()` — matches upstream `FPDFPath_GetDashArray`")]
    #[inline]
    pub fn get_dash_array(&self) -> &[f32] {
        self.dash_array()
    }

    /// Sets the dash array and phase, replacing any existing dash pattern.
    ///
    /// Passing an empty array clears the dash pattern (solid line).
    ///
    /// Corresponds to `FPDFPath_SetDashArray`.
    pub fn set_dash_array(&mut self, array: Vec<f32>, phase: f32) {
        if array.is_empty() {
            self.dash_pattern = None;
        } else {
            self.dash_pattern = Some(DashPattern { array, phase });
        }
    }

    // -----------------------------------------------------------------------
    // Blend mode  (FPDFPageObj_GetBlendMode / FPDFPageObj_SetBlendMode)
    // -----------------------------------------------------------------------

    /// Returns the blend mode for this object.
    ///
    /// Corresponds to `FPDFPageObj_GetBlendMode`.
    pub fn blend_mode(&self) -> Option<BlendMode> {
        self.blend_mode
    }

    /// Upstream-aligned alias for [`blend_mode()`](Self::blend_mode).
    ///
    /// Corresponds to `FPDFPageObj_GetBlendMode`.
    #[inline]
    pub fn page_obj_get_blend_mode(&self) -> Option<BlendMode> {
        self.blend_mode()
    }

    /// Non-upstream alias — use [`page_obj_get_blend_mode()`](Self::page_obj_get_blend_mode).
    ///
    /// Corresponds to `FPDFPageObj_GetBlendMode`.
    #[deprecated(
        note = "use `page_obj_get_blend_mode()` — matches upstream `FPDFPageObj_GetBlendMode`"
    )]
    #[inline]
    pub fn get_blend_mode(&self) -> Option<BlendMode> {
        self.blend_mode()
    }

    /// Sets the blend mode for this object.
    ///
    /// Corresponds to `FPDFPageObj_SetBlendMode`.
    pub fn set_blend_mode(&mut self, mode: Option<BlendMode>) {
        self.blend_mode = mode;
    }

    // -----------------------------------------------------------------------
    // Content marks  (FPDFPageObj_CountMarks / GetMark / AddMark / RemoveMark)
    // -----------------------------------------------------------------------

    /// Return the number of content marks on this object.
    ///
    /// Corresponds to `FPDFPageObj_CountMarks`.
    pub fn mark_count(&self) -> usize {
        self.marks.len()
    }

    /// Upstream-aligned alias for [`mark_count()`](Self::mark_count).
    ///
    /// Corresponds to `FPDFPageObj_CountMarks`.
    #[inline]
    pub fn page_obj_count_marks(&self) -> usize {
        self.mark_count()
    }

    /// Non-upstream alias — use [`page_obj_count_marks()`](Self::page_obj_count_marks).
    ///
    /// Corresponds to `FPDFPageObj_CountMarks`.
    #[deprecated(note = "use `page_obj_count_marks()` — matches upstream `FPDFPageObj_CountMarks`")]
    #[inline]
    pub fn count_marks(&self) -> usize {
        self.mark_count()
    }

    /// Return the content mark at the given index, or `None` if out of range.
    ///
    /// Corresponds to `FPDFPageObj_GetMark`.
    pub fn mark(&self, index: usize) -> Option<&ContentMark> {
        self.marks.get(index)
    }

    /// Upstream-aligned alias for [`mark()`](Self::mark).
    ///
    /// Corresponds to `FPDFPageObj_GetMark`.
    #[inline]
    pub fn page_obj_get_mark(&self, index: usize) -> Option<&ContentMark> {
        self.mark(index)
    }

    /// Non-upstream alias — use [`page_obj_get_mark()`](Self::page_obj_get_mark).
    ///
    /// Corresponds to `FPDFPageObj_GetMark`.
    #[deprecated(note = "use `page_obj_get_mark()` — matches upstream `FPDFPageObj_GetMark`")]
    #[inline]
    pub fn get_mark(&self, index: usize) -> Option<&ContentMark> {
        self.mark(index)
    }

    /// Add a new content mark with the given name and return a mutable
    /// reference to it.
    ///
    /// Corresponds to `FPDFPageObj_AddMark`.
    pub fn add_mark(&mut self, name: impl Into<String>) -> &mut ContentMark {
        self.marks.push(ContentMark::new(name));
        self.marks.last_mut().unwrap()
    }

    /// Remove the content mark at the given index.
    ///
    /// Returns `true` if the index was valid and the mark was removed, `false`
    /// if out of range.
    ///
    /// Corresponds to `FPDFPageObj_RemoveMark`.
    pub fn remove_mark(&mut self, index: usize) -> bool {
        if index < self.marks.len() {
            self.marks.remove(index);
            true
        } else {
            false
        }
    }

    /// Return a slice of all content marks on this object.
    pub fn marks(&self) -> &[ContentMark] {
        &self.marks
    }

    /// Return the marked content ID (`/MCID`) from the first mark that has one,
    /// or `None` if no mark carries an MCID.
    ///
    /// Corresponds to `FPDFPageObj_GetMarkedContentID`.
    pub fn marked_content_id(&self) -> Option<i64> {
        self.marks.iter().find_map(|m| m.marked_content_id())
    }

    /// Upstream-aligned alias for [`marked_content_id()`](Self::marked_content_id).
    ///
    /// Corresponds to `FPDFPageObj_GetMarkedContentID`.
    #[inline]
    pub fn page_obj_get_marked_content_id(&self) -> Option<i64> {
        self.marked_content_id()
    }

    /// Non-upstream alias — use [`page_obj_get_marked_content_id()`](Self::page_obj_get_marked_content_id).
    ///
    /// Corresponds to `FPDFPageObj_GetMarkedContentID`.
    #[deprecated(
        note = "use `page_obj_get_marked_content_id()` — matches upstream `FPDFPageObj_GetMarkedContentID`"
    )]
    #[inline]
    pub fn get_marked_content_id(&self) -> Option<i64> {
        self.marked_content_id()
    }

    /// Returns `true` if this path object has any transparency.
    ///
    /// A path is considered transparent when it has a non-`Normal` blend mode.
    ///
    /// Corresponds to `FPDFPageObj_HasTransparency`.
    pub fn has_transparency(&self) -> bool {
        matches!(self.blend_mode, Some(bm) if bm != BlendMode::Normal)
    }

    /// Non-upstream convenience alias for [`has_transparency()`](Self::has_transparency).
    ///
    /// Prefer [`has_transparency()`](Self::has_transparency), which matches
    /// the upstream `FPDFPageObj_HasTransparency` name exactly.
    #[deprecated(note = "use `has_transparency()` — matches upstream FPDFPageObj_HasTransparency")]
    #[inline]
    pub fn is_transparent(&self) -> bool {
        self.has_transparency()
    }

    /// Returns the PDFium page-object-type constant for path objects: `2`.
    ///
    /// Corresponds to `FPDFPageObj_GetType` returning `FPDF_PAGEOBJ_PATH`.
    pub fn object_type(&self) -> u32 {
        2
    }

    /// Non-upstream alias — use [`page_obj_get_type()`](Self::page_obj_get_type).
    ///
    /// The actual upstream function is `FPDFPageObj_GetType`; there is no
    /// `FPDFPageObj_GetObjectType`.
    #[deprecated(note = "use `page_obj_get_type()` — matches upstream `FPDFPageObj_GetType`")]
    #[inline]
    pub fn get_object_type(&self) -> u32 {
        self.object_type()
    }

    /// Upstream-aligned alias for [`object_type()`](Self::object_type).
    ///
    /// Corresponds to `FPDFPageObj_GetType`.
    #[inline]
    pub fn page_obj_get_type(&self) -> u32 {
        self.object_type()
    }

    #[deprecated(note = "use `page_obj_get_type()` — matches upstream `FPDFPageObj_GetType`")]
    #[inline]
    pub fn get_type(&self) -> u32 {
        self.object_type()
    }

    /// Applies a matrix transform to all path segments.
    ///
    /// Each control point is transformed by `matrix`. For `Rect` segments,
    /// the origin is transformed and width/height are uniformly scaled.
    ///
    /// Corresponds to `FPDFPageObj_Transform`.
    pub fn transform(&mut self, matrix: &Matrix) {
        use rpdfium_core::Point;
        for seg in &mut self.segments {
            match seg {
                PathSegment::MoveTo(x, y) | PathSegment::LineTo(x, y) => {
                    let p = matrix.transform_point(Point::new(*x, *y));
                    *x = p.x;
                    *y = p.y;
                }
                PathSegment::CurveTo(x1, y1, x2, y2, x3, y3) => {
                    let p1 = matrix.transform_point(Point::new(*x1, *y1));
                    let p2 = matrix.transform_point(Point::new(*x2, *y2));
                    let p3 = matrix.transform_point(Point::new(*x3, *y3));
                    *x1 = p1.x;
                    *y1 = p1.y;
                    *x2 = p2.x;
                    *y2 = p2.y;
                    *x3 = p3.x;
                    *y3 = p3.y;
                }
                PathSegment::Rect(x, y, w, h) => {
                    let p = matrix.transform_point(Point::new(*x, *y));
                    let scale_x = (matrix.a * matrix.a + matrix.b * matrix.b).sqrt();
                    let scale_y = (matrix.c * matrix.c + matrix.d * matrix.d).sqrt();
                    *x = p.x;
                    *y = p.y;
                    *w *= scale_x;
                    *h *= scale_y;
                }
                PathSegment::Close => {}
            }
        }
    }

    /// Returns the transformation matrix for this path object.
    ///
    /// For path objects, coordinates are stored in page space (absolute),
    /// so this returns the identity matrix unless a matrix was explicitly
    /// assigned via the `matrix` field.
    ///
    /// Corresponds to `FPDFPageObj_GetMatrix`.
    pub fn matrix(&self) -> Matrix {
        self.matrix
    }

    /// Upstream-aligned alias for [`matrix()`](Self::matrix).
    ///
    /// Corresponds to `FPDFPageObj_GetMatrix`.
    #[inline]
    pub fn page_obj_get_matrix(&self) -> Matrix {
        self.matrix()
    }

    #[deprecated(note = "use `page_obj_get_matrix()` — matches upstream `FPDFPageObj_GetMatrix`")]
    #[inline]
    pub fn get_matrix(&self) -> Matrix {
        self.matrix()
    }

    /// Returns the number of path segments in this path object.
    ///
    /// Corresponds to `FPDFPath_CountSegments`.
    pub fn segment_count(&self) -> usize {
        self.segments.len()
    }

    /// Upstream-aligned alias for [`segment_count()`](Self::segment_count).
    ///
    /// Corresponds to `FPDFPath_CountSegments`.
    #[inline]
    pub fn path_count_segments(&self) -> usize {
        self.segment_count()
    }

    #[deprecated(note = "use `path_count_segments()` — matches upstream `FPDFPath_CountSegments`")]
    #[inline]
    pub fn count_segments(&self) -> usize {
        self.segment_count()
    }

    /// Returns the draw mode of this path object as `(fill_mode, stroke)`.
    ///
    /// `fill_mode` is the current [`FillMode`]; `stroke` is `true` when this
    /// path has a stroke color set.
    ///
    /// Corresponds to `FPDFPath_GetDrawMode`.
    pub fn draw_mode(&self) -> (FillMode, bool) {
        (self.fill_mode, self.stroke_color.is_some())
    }

    /// Upstream-aligned alias for [`draw_mode()`](Self::draw_mode).
    ///
    /// Corresponds to `FPDFPath_GetDrawMode`.
    #[inline]
    pub fn path_get_draw_mode(&self) -> (FillMode, bool) {
        self.draw_mode()
    }

    #[deprecated(note = "use `path_get_draw_mode()` — matches upstream `FPDFPath_GetDrawMode`")]
    #[inline]
    pub fn get_draw_mode(&self) -> (FillMode, bool) {
        self.draw_mode()
    }

    /// Sets the draw mode of this path object.
    ///
    /// `fill_mode` controls whether and how the path interior is filled.
    /// `stroke` controls whether a stroke color is retained; when `false` the
    /// existing stroke color is cleared.
    ///
    /// Corresponds to `FPDFPath_SetDrawMode`.
    pub fn set_draw_mode(&mut self, fill_mode: FillMode, stroke: bool) {
        self.fill_mode = fill_mode;
        if !stroke {
            self.stroke_color = None;
        }
    }

    /// Upstream-aligned alias for [`set_draw_mode()`](Self::set_draw_mode).
    ///
    /// Corresponds to `FPDFPath_SetDrawMode`.
    #[inline]
    pub fn path_set_draw_mode(&mut self, fill_mode: FillMode, stroke: bool) {
        self.set_draw_mode(fill_mode, stroke)
    }

    /// Returns the fill mode for this path object.
    ///
    /// Corresponds to the `fillmode` out-parameter of `FPDFPath_GetDrawMode`.
    pub fn fill_mode(&self) -> FillMode {
        self.fill_mode
    }

    /// Sets the fill mode for this path object.
    ///
    /// Corresponds to the `fillmode` parameter of `FPDFPath_SetDrawMode`.
    pub fn set_fill_mode(&mut self, mode: FillMode) {
        self.fill_mode = mode;
    }

    /// Returns whether this path is stroked (i.e. has a stroke color set).
    ///
    /// Corresponds to the `stroke` out-parameter of `FPDFPath_GetDrawMode`.
    pub fn is_stroked(&self) -> bool {
        self.stroke_color.is_some()
    }

    /// Corresponds to `FPDFPageObj_GetBounds`.
    pub fn bounds(&self) -> Option<rpdfium_core::Rect> {
        let mut min_x = f64::MAX;
        let mut min_y = f64::MAX;
        let mut max_x = f64::MIN;
        let mut max_y = f64::MIN;
        let mut has_point = false;

        for seg in &self.segments {
            match seg {
                PathSegment::MoveTo(x, y) | PathSegment::LineTo(x, y) => {
                    min_x = min_x.min(*x);
                    max_x = max_x.max(*x);
                    min_y = min_y.min(*y);
                    max_y = max_y.max(*y);
                    has_point = true;
                }
                PathSegment::CurveTo(x1, y1, x2, y2, x3, y3) => {
                    for &(x, y) in &[(*x1, *y1), (*x2, *y2), (*x3, *y3)] {
                        min_x = min_x.min(x);
                        max_x = max_x.max(x);
                        min_y = min_y.min(y);
                        max_y = max_y.max(y);
                    }
                    has_point = true;
                }
                PathSegment::Rect(x, y, w, h) => {
                    min_x = min_x.min(*x);
                    max_x = max_x.max(*x + *w);
                    min_y = min_y.min(*y);
                    max_y = max_y.max(*y + *h);
                    has_point = true;
                }
                PathSegment::Close => {}
            }
        }

        if has_point {
            Some(rpdfium_core::Rect {
                left: min_x,
                bottom: min_y,
                right: max_x,
                top: max_y,
            })
        } else {
            None
        }
    }

    /// Returns the path segment at `index`, or `None` if out of range.
    ///
    /// Corresponds to `FPDFPath_GetPathSegment`.
    pub fn segment(&self, index: usize) -> Option<&PathSegment> {
        self.segments.get(index)
    }

    /// Upstream-aligned alias for [`segment()`](Self::segment).
    ///
    /// Corresponds to `FPDFPath_GetPathSegment`.
    #[inline]
    pub fn path_get_path_segment(&self, index: usize) -> Option<&PathSegment> {
        self.segment(index)
    }

    #[deprecated(
        note = "use `path_get_path_segment()` — matches upstream `FPDFPath_GetPathSegment`"
    )]
    #[inline]
    pub fn get_path_segment(&self, index: usize) -> Option<&PathSegment> {
        self.segment(index)
    }

    /// Creates a new path object with an initial MoveTo at `(x, y)`.
    ///
    /// The path starts with default stroke (black, 1pt) and no fill.
    /// Use the builder-style `move_to`, `line_to`, `bezier_to`, and `close`
    /// methods to append further segments.
    ///
    /// Corresponds to `FPDFPageObj_CreateNewPath(x, y)`.
    pub fn create_at(x: f64, y: f64) -> Self {
        let mut path = PathObject::default();
        path.segments.push(PathSegment::MoveTo(x, y));
        path
    }

    /// Upstream-aligned alias for [`create_at()`](Self::create_at).
    ///
    /// Corresponds to `FPDFPageObj_CreateNewPath`.
    #[inline]
    pub fn page_obj_create_new_path(x: f64, y: f64) -> Self {
        Self::create_at(x, y)
    }

    /// Creates a new rectangular path object at `(x, y)` with `width × height`.
    ///
    /// The rectangle is encoded as a closed `Rect` segment matching upstream
    /// `CPDF_PathObject::AppendRect(x, y, x+w, y+h)`. Default stroke is black,
    /// 1pt; no fill is set.
    ///
    /// Corresponds to `FPDFPageObj_CreateNewRect(x, y, w, h)`.
    pub fn create_rect(x: f64, y: f64, width: f64, height: f64) -> Self {
        let mut path = PathObject::default();
        path.segments.push(PathSegment::Rect(x, y, width, height));
        path
    }

    /// Upstream-aligned alias for [`create_rect()`](Self::create_rect).
    ///
    /// Corresponds to `FPDFPageObj_CreateNewRect`.
    #[inline]
    pub fn page_obj_create_new_rect(x: f64, y: f64, width: f64, height: f64) -> Self {
        Self::create_rect(x, y, width, height)
    }

    /// Append a MoveTo segment to this path.
    ///
    /// Corresponds to `FPDFPath_MoveTo`.
    pub fn move_to(&mut self, x: f64, y: f64) -> &mut Self {
        self.segments.push(PathSegment::MoveTo(x, y));
        self
    }

    /// Upstream-aligned alias for [`move_to()`](Self::move_to).
    ///
    /// Corresponds to `FPDFPath_MoveTo`.
    #[inline]
    pub fn path_move_to(&mut self, x: f64, y: f64) -> &mut Self {
        self.move_to(x, y)
    }

    /// Append a LineTo segment to this path.
    ///
    /// Corresponds to `FPDFPath_LineTo`.
    pub fn line_to(&mut self, x: f64, y: f64) -> &mut Self {
        self.segments.push(PathSegment::LineTo(x, y));
        self
    }

    /// Upstream-aligned alias for [`line_to()`](Self::line_to).
    ///
    /// Corresponds to `FPDFPath_LineTo`.
    #[inline]
    pub fn path_line_to(&mut self, x: f64, y: f64) -> &mut Self {
        self.line_to(x, y)
    }

    /// Append a cubic Bézier curve segment to this path.
    ///
    /// `(x1, y1)` and `(x2, y2)` are the control points; `(x3, y3)` is the
    /// end point.
    ///
    /// Corresponds to `FPDFPath_BezierTo`.
    pub fn bezier_to(&mut self, x1: f64, y1: f64, x2: f64, y2: f64, x3: f64, y3: f64) -> &mut Self {
        self.segments
            .push(PathSegment::CurveTo(x1, y1, x2, y2, x3, y3));
        self
    }

    /// Upstream-aligned alias for [`bezier_to()`](Self::bezier_to).
    ///
    /// Corresponds to `FPDFPath_BezierTo`.
    #[inline]
    pub fn path_bezier_to(
        &mut self,
        x1: f64,
        y1: f64,
        x2: f64,
        y2: f64,
        x3: f64,
        y3: f64,
    ) -> &mut Self {
        self.bezier_to(x1, y1, x2, y2, x3, y3)
    }

    /// Close the current subpath.
    ///
    /// Corresponds to `FPDFPath_Close`.
    pub fn close(&mut self) -> &mut Self {
        self.segments.push(PathSegment::Close);
        self
    }

    /// Upstream-aligned alias for [`close()`](Self::close).
    ///
    /// Corresponds to `FPDFPath_Close`.
    #[inline]
    pub fn path_close(&mut self) -> &mut Self {
        self.close()
    }
}

/// A text object with font, position, and color.
#[derive(Debug, Clone)]
pub struct TextObject {
    /// Font name (must match a resource font name).
    pub font_name: Name,
    /// Font size in points.
    pub font_size: f32,
    /// Transformation matrix (includes position).
    pub matrix: Matrix,
    /// The text string to render.
    pub text: String,
    /// Fill color.
    pub fill_color: Option<Color>,
    /// Stroke color.
    pub stroke_color: Option<Color>,
    /// Text rendering mode.
    pub rendering_mode: TextRenderingMode,
    /// Character spacing.
    pub char_spacing: f32,
    /// Word spacing.
    pub word_spacing: f32,
    /// Object ID of the registered font dictionary, if created via
    /// [`TextObject::with_font`].  `None` means the legacy path where the
    /// font resource is resolved by name alone.
    pub(crate) font_object_id: Option<ObjectId>,
    /// Font encoding for content stream generation.
    ///
    /// Controls how Unicode characters in `text` are encoded to PDF byte codes.
    /// Defaults to `WinAnsi` (the most common PDF encoding).
    pub(crate) encoding: FontEncoding,
    /// Blend mode for compositing.
    ///
    /// Corresponds to `FPDFPageObj_GetBlendMode` / `FPDFPageObj_SetBlendMode`.
    pub blend_mode: Option<BlendMode>,
    /// Whether the object is active (visible).
    ///
    /// Corresponds to `FPDFPageObj_GetIsActive` / `FPDFPageObj_SetIsActive`.
    pub active: bool,
    /// Content marks attached to this object (for tagged PDF / accessibility).
    ///
    /// Each mark corresponds to a `BDC`…`EMC` pair wrapping this object in
    /// the content stream.
    ///
    /// Corresponds to `FPDFPageObj_CountMarks` / `FPDFPageObj_GetMark` / etc.
    pub marks: Vec<ContentMark>,
    /// Optional clipping path attached to this object.
    ///
    /// Corresponds to `FPDFPageObj_GetClipPath` / `FPDFPageObj_TransformClipPath`.
    pub clip_path: Option<ClipPath>,
}

impl Default for TextObject {
    fn default() -> Self {
        Self {
            font_name: Name::from_bytes(b"Helvetica".to_vec()),
            font_size: 12.0,
            matrix: Matrix::identity(),
            text: String::new(),
            fill_color: Some(Color::gray(0.0)),
            stroke_color: None,
            rendering_mode: TextRenderingMode::Fill,
            char_spacing: 0.0,
            word_spacing: 0.0,
            font_object_id: None,
            encoding: FontEncoding::WinAnsi,
            blend_mode: None,
            active: true,
            marks: Vec::new(),
            clip_path: None,
        }
    }
}

impl TextObject {
    /// Create a text object using a Standard-14 font name.
    ///
    /// This is a convenience constructor that sets the font name directly.
    /// For precise resource registration, prefer
    /// [`TextObject::with_font`] together with
    /// [`EditDocument::load_standard_font`](crate::document::EditDocument::load_standard_font).
    ///
    /// Corresponds to `FPDFPageObj_NewTextObj`.
    pub fn with_standard_font(font_name: &str, size: f32) -> Self {
        Self {
            font_name: Name::from_bytes(font_name.as_bytes().to_vec()),
            font_size: size,
            ..Default::default()
        }
    }

    /// Create a text object from a [`crate::font_reg::FontRegistration`].
    ///
    /// Sets `font_object_id` so that content-stream generation uses the exact
    /// PDF object ID of the registered font dictionary.
    ///
    /// Corresponds to `FPDFPageObj_CreateTextObj`.
    pub fn with_font(registration: &crate::font_reg::FontRegistration, size: f32) -> Self {
        Self {
            font_name: Name::from_bytes(registration.base_font_name().as_bytes().to_vec()),
            font_size: size,
            font_object_id: Some(registration.object_id),
            ..Default::default()
        }
    }

    /// Non-upstream alias — use [`with_font()`](Self::with_font).
    ///
    /// `FPDFPageObj_CreateTextObj` maps to `create_text_obj`; this name
    /// (`from_font_registration`) is not an upstream FPDF_* name.
    #[deprecated(
        note = "use `with_font()` — `from_font_registration` is not an upstream FPDF name"
    )]
    #[inline]
    pub fn from_font_registration(
        font_registration: &crate::font_reg::FontRegistration,
        font_size: f32,
    ) -> Self {
        Self::with_font(font_registration, font_size)
    }

    // -----------------------------------------------------------------------
    // Getters  (FPDFTextObj_Get* equivalents)
    // -----------------------------------------------------------------------

    /// Return the text string stored in this object.
    ///
    /// Corresponds to `FPDFTextObj_GetText` (without requiring a `text_page`).
    pub fn text(&self) -> &str {
        &self.text
    }

    /// Upstream-aligned alias for [`text()`](Self::text).
    ///
    /// Corresponds to `FPDFTextObj_GetText`.
    #[inline]
    pub fn text_obj_get_text(&self) -> &str {
        self.text()
    }

    #[deprecated(note = "use `text_obj_get_text()` — matches upstream `FPDFTextObj_GetText`")]
    #[inline]
    pub fn get_text(&self) -> &str {
        self.text()
    }

    /// Return the font size in points.
    ///
    /// Corresponds to `FPDFTextObj_GetFontSize`.
    pub fn font_size(&self) -> f32 {
        self.font_size
    }

    /// Upstream-aligned alias for [`font_size()`](Self::font_size).
    ///
    /// Corresponds to `FPDFTextObj_GetFontSize`.
    #[inline]
    pub fn text_obj_get_font_size(&self) -> f32 {
        self.font_size()
    }

    #[deprecated(
        note = "use `text_obj_get_font_size()` — matches upstream `FPDFTextObj_GetFontSize`"
    )]
    #[inline]
    pub fn get_font_size(&self) -> f32 {
        self.font_size()
    }

    /// Return the text rendering mode.
    ///
    /// Corresponds to `FPDFTextObj_GetTextRenderMode`.
    pub fn rendering_mode(&self) -> TextRenderingMode {
        self.rendering_mode
    }

    /// Upstream-aligned alias for [`rendering_mode()`](Self::rendering_mode).
    ///
    /// Corresponds to `FPDFTextObj_GetTextRenderMode`.
    #[inline]
    pub fn text_obj_get_text_render_mode(&self) -> TextRenderingMode {
        self.rendering_mode()
    }

    #[deprecated(
        note = "use `text_obj_get_text_render_mode()` — matches upstream `FPDFTextObj_GetTextRenderMode`"
    )]
    #[inline]
    pub fn get_text_render_mode(&self) -> TextRenderingMode {
        self.rendering_mode()
    }

    /// Return the font name as a PDF [`Name`].
    ///
    /// Corresponds to `FPDFTextObj_GetFont` (name only; for full font metrics
    /// use the rpdfium-font crate).
    pub fn font_name(&self) -> &Name {
        &self.font_name
    }

    /// Upstream-aligned alias for [`font_name()`](Self::font_name).
    ///
    /// Corresponds to `FPDFTextObj_GetFont`.
    #[inline]
    pub fn text_obj_get_font(&self) -> &Name {
        self.font_name()
    }

    #[deprecated(note = "use `text_obj_get_font()` — matches upstream `FPDFTextObj_GetFont`")]
    #[inline]
    pub fn get_font(&self) -> &Name {
        self.font_name()
    }

    /// Sets the fill color.
    ///
    /// Corresponds to `FPDFPageObj_SetFillColor`.
    pub fn set_fill_color(&mut self, color: Color) {
        self.fill_color = Some(color);
    }

    /// Returns the fill color, if set (upstream `FPDFPageObj_GetFillColor`).
    pub fn fill_color(&self) -> Option<&Color> {
        self.fill_color.as_ref()
    }

    /// Upstream-aligned alias for [`fill_color()`](Self::fill_color).
    ///
    /// Corresponds to `FPDFPageObj_GetFillColor`.
    #[inline]
    pub fn page_obj_get_fill_color(&self) -> Option<&Color> {
        self.fill_color()
    }

    /// Non-upstream alias — use [`page_obj_get_fill_color()`](Self::page_obj_get_fill_color).
    ///
    /// Corresponds to `FPDFPageObj_GetFillColor`.
    #[deprecated(
        note = "use `page_obj_get_fill_color()` — matches upstream `FPDFPageObj_GetFillColor`"
    )]
    #[inline]
    pub fn get_fill_color(&self) -> Option<&Color> {
        self.fill_color()
    }

    /// Sets the stroke color.
    ///
    /// Corresponds to `FPDFPageObj_SetStrokeColor`.
    pub fn set_stroke_color(&mut self, color: Color) {
        self.stroke_color = Some(color);
    }

    /// Returns the stroke color, if set (upstream `FPDFPageObj_GetStrokeColor`).
    pub fn stroke_color(&self) -> Option<&Color> {
        self.stroke_color.as_ref()
    }

    /// Upstream-aligned alias for [`stroke_color()`](Self::stroke_color).
    ///
    /// Corresponds to `FPDFPageObj_GetStrokeColor`.
    #[inline]
    pub fn page_obj_get_stroke_color(&self) -> Option<&Color> {
        self.stroke_color()
    }

    /// Non-upstream alias — use [`page_obj_get_stroke_color()`](Self::page_obj_get_stroke_color).
    ///
    /// Corresponds to `FPDFPageObj_GetStrokeColor`.
    #[deprecated(
        note = "use `page_obj_get_stroke_color()` — matches upstream `FPDFPageObj_GetStrokeColor`"
    )]
    #[inline]
    pub fn get_stroke_color(&self) -> Option<&Color> {
        self.stroke_color()
    }

    /// Sets the font size in points.
    ///
    /// Corresponds to `FPDFTextObj_SetFontSize` (not a direct upstream function,
    /// but enables mutation after construction).
    pub fn set_font_size(&mut self, size: f32) {
        self.font_size = size;
    }

    /// Sets the text content of this text object.
    ///
    /// Corresponds to `FPDFTextObj_SetText`.
    pub fn set_text(&mut self, text: impl Into<String>) {
        self.text = text.into();
    }

    /// Upstream-aligned alias for [`set_text()`](Self::set_text).
    ///
    /// Corresponds to `FPDFTextObj_SetText`.
    #[inline]
    pub fn text_obj_set_text(&mut self, text: impl Into<String>) {
        self.set_text(text)
    }

    /// Non-upstream convenience alias for [`set_text()`](Self::set_text).
    ///
    /// Prefer [`set_text()`](Self::set_text), which matches the upstream
    /// `FPDFText_SetText` name exactly.
    #[deprecated(note = "use `set_text()` — matches upstream FPDFText_SetText")]
    #[inline]
    pub fn set_text_content(&mut self, text: String) {
        self.set_text(text);
    }

    /// Sets the text rendering mode.
    ///
    /// Corresponds to `FPDFTextObj_SetTextRenderMode`.
    pub fn set_rendering_mode(&mut self, mode: TextRenderingMode) {
        self.rendering_mode = mode;
    }

    /// Upstream-aligned alias for [`Self::set_rendering_mode()`].
    ///
    /// Corresponds to `FPDFTextObj_SetTextRenderMode`.
    #[inline]
    pub fn text_obj_set_text_render_mode(&mut self, mode: TextRenderingMode) {
        self.set_rendering_mode(mode);
    }

    /// Non-upstream alias — use [`text_obj_set_text_render_mode()`](Self::text_obj_set_text_render_mode).
    ///
    /// Corresponds to `FPDFTextObj_SetTextRenderMode`.
    #[deprecated(
        note = "use `text_obj_set_text_render_mode()` — matches upstream `FPDFTextObj_SetTextRenderMode`"
    )]
    #[inline]
    pub fn set_text_render_mode(&mut self, mode: TextRenderingMode) {
        self.set_rendering_mode(mode);
    }

    /// Applies a matrix transform by pre-multiplying into the object's matrix.
    ///
    /// Corresponds to `FPDFPageObj_Transform`.
    pub fn transform(&mut self, m: &Matrix) {
        self.matrix = m.pre_concat(&self.matrix);
    }

    /// Returns the blend mode for this object.
    ///
    /// Corresponds to `FPDFPageObj_GetBlendMode`.
    pub fn blend_mode(&self) -> Option<BlendMode> {
        self.blend_mode
    }

    /// Upstream-aligned alias for [`blend_mode()`](Self::blend_mode).
    ///
    /// Corresponds to `FPDFPageObj_GetBlendMode`.
    #[inline]
    pub fn page_obj_get_blend_mode(&self) -> Option<BlendMode> {
        self.blend_mode()
    }

    /// Non-upstream alias — use [`page_obj_get_blend_mode()`](Self::page_obj_get_blend_mode).
    ///
    /// Corresponds to `FPDFPageObj_GetBlendMode`.
    #[deprecated(
        note = "use `page_obj_get_blend_mode()` — matches upstream `FPDFPageObj_GetBlendMode`"
    )]
    #[inline]
    pub fn get_blend_mode(&self) -> Option<BlendMode> {
        self.blend_mode()
    }

    /// Sets the blend mode for this object.
    ///
    /// Corresponds to `FPDFPageObj_SetBlendMode`.
    pub fn set_blend_mode(&mut self, mode: Option<BlendMode>) {
        self.blend_mode = mode;
    }

    // -----------------------------------------------------------------------
    // Content marks  (FPDFPageObj_CountMarks / GetMark / AddMark / RemoveMark)
    // -----------------------------------------------------------------------

    /// Return the number of content marks on this object.
    ///
    /// Corresponds to `FPDFPageObj_CountMarks`.
    pub fn mark_count(&self) -> usize {
        self.marks.len()
    }

    /// Upstream-aligned alias for [`mark_count()`](Self::mark_count).
    ///
    /// Corresponds to `FPDFPageObj_CountMarks`.
    #[inline]
    pub fn page_obj_count_marks(&self) -> usize {
        self.mark_count()
    }

    /// Non-upstream alias — use [`page_obj_count_marks()`](Self::page_obj_count_marks).
    ///
    /// Corresponds to `FPDFPageObj_CountMarks`.
    #[deprecated(note = "use `page_obj_count_marks()` — matches upstream `FPDFPageObj_CountMarks`")]
    #[inline]
    pub fn count_marks(&self) -> usize {
        self.mark_count()
    }

    /// Return the content mark at the given index, or `None` if out of range.
    ///
    /// Corresponds to `FPDFPageObj_GetMark`.
    pub fn mark(&self, index: usize) -> Option<&ContentMark> {
        self.marks.get(index)
    }

    /// Upstream-aligned alias for [`mark()`](Self::mark).
    ///
    /// Corresponds to `FPDFPageObj_GetMark`.
    #[inline]
    pub fn page_obj_get_mark(&self, index: usize) -> Option<&ContentMark> {
        self.mark(index)
    }

    /// Non-upstream alias — use [`page_obj_get_mark()`](Self::page_obj_get_mark).
    ///
    /// Corresponds to `FPDFPageObj_GetMark`.
    #[deprecated(note = "use `page_obj_get_mark()` — matches upstream `FPDFPageObj_GetMark`")]
    #[inline]
    pub fn get_mark(&self, index: usize) -> Option<&ContentMark> {
        self.mark(index)
    }

    /// Add a new content mark with the given name and return a mutable
    /// reference to it.
    ///
    /// Corresponds to `FPDFPageObj_AddMark`.
    pub fn add_mark(&mut self, name: impl Into<String>) -> &mut ContentMark {
        self.marks.push(ContentMark::new(name));
        self.marks.last_mut().unwrap()
    }

    /// Remove the content mark at the given index.
    ///
    /// Returns `true` if the index was valid and the mark was removed, `false`
    /// if out of range.
    ///
    /// Corresponds to `FPDFPageObj_RemoveMark`.
    pub fn remove_mark(&mut self, index: usize) -> bool {
        if index < self.marks.len() {
            self.marks.remove(index);
            true
        } else {
            false
        }
    }

    /// Return a slice of all content marks on this object.
    pub fn marks(&self) -> &[ContentMark] {
        &self.marks
    }

    /// Return the marked content ID (`/MCID`) from the first mark that has one,
    /// or `None` if no mark carries an MCID.
    ///
    /// Corresponds to `FPDFPageObj_GetMarkedContentID`.
    pub fn marked_content_id(&self) -> Option<i64> {
        self.marks.iter().find_map(|m| m.marked_content_id())
    }

    /// Upstream-aligned alias for [`marked_content_id()`](Self::marked_content_id).
    ///
    /// Corresponds to `FPDFPageObj_GetMarkedContentID`.
    #[inline]
    pub fn page_obj_get_marked_content_id(&self) -> Option<i64> {
        self.marked_content_id()
    }

    /// Non-upstream alias — use [`page_obj_get_marked_content_id()`](Self::page_obj_get_marked_content_id).
    ///
    /// Corresponds to `FPDFPageObj_GetMarkedContentID`.
    #[deprecated(
        note = "use `page_obj_get_marked_content_id()` — matches upstream `FPDFPageObj_GetMarkedContentID`"
    )]
    #[inline]
    pub fn get_marked_content_id(&self) -> Option<i64> {
        self.marked_content_id()
    }

    /// Returns `true` if this text object has any transparency.
    ///
    /// A text object is considered transparent when it has a non-`Normal`
    /// blend mode.
    ///
    /// Corresponds to `FPDFPageObj_HasTransparency`.
    pub fn has_transparency(&self) -> bool {
        matches!(self.blend_mode, Some(bm) if bm != BlendMode::Normal)
    }

    /// Non-upstream convenience alias for [`has_transparency()`](Self::has_transparency).
    ///
    /// Prefer [`has_transparency()`](Self::has_transparency), which matches
    /// the upstream `FPDFPageObj_HasTransparency` name exactly.
    #[deprecated(note = "use `has_transparency()` — matches upstream FPDFPageObj_HasTransparency")]
    #[inline]
    pub fn is_transparent(&self) -> bool {
        self.has_transparency()
    }

    /// Returns the PDFium page-object-type constant for text objects: `1`.
    ///
    /// Corresponds to `FPDFPageObj_GetType` returning `FPDF_PAGEOBJ_TEXT`.
    pub fn object_type(&self) -> u32 {
        1
    }

    /// Non-upstream alias — use [`get_type()`](Self::get_type).
    ///
    /// The actual upstream function is `FPDFPageObj_GetType`; there is no
    /// `FPDFPageObj_GetObjectType`.
    #[deprecated(note = "use `page_obj_get_type()` — matches upstream `FPDFPageObj_GetType`")]
    #[inline]
    pub fn get_object_type(&self) -> u32 {
        self.object_type()
    }

    /// Upstream-aligned alias for [`object_type()`](Self::object_type).
    ///
    /// Corresponds to `FPDFPageObj_GetType`.
    #[inline]
    pub fn page_obj_get_type(&self) -> u32 {
        self.object_type()
    }

    #[deprecated(note = "use `page_obj_get_type()` — matches upstream `FPDFPageObj_GetType`")]
    #[inline]
    pub fn get_type(&self) -> u32 {
        self.object_type()
    }

    /// Returns the tight rotated bounding quadrilateral for this text object
    /// as 4 corner points in page coordinates.
    ///
    /// The corners are computed by transforming the unit square through the
    /// object's text matrix, which encodes position, scale, and rotation.
    ///
    /// Corresponds to `FPDFPageObj_GetRotatedBounds`.
    pub fn rotated_bounds(&self) -> Option<[rpdfium_core::Point; 4]> {
        let m = &self.matrix;
        let corners = [
            rpdfium_core::Point { x: m.e, y: m.f },
            rpdfium_core::Point {
                x: m.a + m.e,
                y: m.b + m.f,
            },
            rpdfium_core::Point {
                x: m.a + m.c + m.e,
                y: m.b + m.d + m.f,
            },
            rpdfium_core::Point {
                x: m.c + m.e,
                y: m.d + m.f,
            },
        ];
        Some(corners)
    }

    /// Upstream-aligned alias for [`rotated_bounds()`](Self::rotated_bounds).
    ///
    /// Corresponds to `FPDFPageObj_GetRotatedBounds`.
    #[inline]
    pub fn page_obj_get_rotated_bounds(&self) -> Option<[rpdfium_core::Point; 4]> {
        self.rotated_bounds()
    }

    /// Non-upstream alias — use [`page_obj_get_rotated_bounds()`](Self::page_obj_get_rotated_bounds).
    ///
    /// Corresponds to `FPDFPageObj_GetRotatedBounds`.
    #[deprecated(
        note = "use `page_obj_get_rotated_bounds()` — matches upstream `FPDFPageObj_GetRotatedBounds`"
    )]
    #[inline]
    pub fn get_rotated_bounds(&self) -> Option<[rpdfium_core::Point; 4]> {
        self.rotated_bounds()
    }

    /// Sets text content from raw PDF character codes.
    ///
    /// Unlike [`set_text()`](Self::set_text) which takes a Unicode string,
    /// this takes PDF-specific character codes directly. Each code is
    /// converted to a Unicode scalar value if valid, or the replacement
    /// character (`U+FFFD`) otherwise.
    ///
    /// Corresponds to `FPDFText_SetCharcodes`.
    pub fn set_char_codes(&mut self, codes: &[u32]) {
        self.text = codes
            .iter()
            .map(|&c| char::from_u32(c).unwrap_or('\u{FFFD}'))
            .collect();
    }

    /// Upstream-aligned alias for [`set_char_codes()`](Self::set_char_codes).
    ///
    /// Corresponds to `FPDFText_SetCharcodes`.
    #[inline]
    pub fn text_set_charcodes(&mut self, codes: &[u32]) {
        self.set_char_codes(codes)
    }

    /// Non-upstream alias — use [`text_set_charcodes()`](Self::text_set_charcodes).
    ///
    /// Corresponds to `FPDFText_SetCharcodes`.
    #[deprecated(note = "use `text_set_charcodes()` — matches upstream `FPDFText_SetCharcodes`")]
    #[inline]
    pub fn set_charcodes(&mut self, codes: &[u32]) {
        self.set_char_codes(codes)
    }

    /// Returns the rendered bitmap for this text object at the given scale.
    ///
    /// # Not Supported
    ///
    /// Rendering a page object to bitmap requires a live CPDF_Document/CPDF_Page
    /// handle not available in rpdfium's edit layer (read-only, ADR-002).
    ///
    /// Corresponds to `FPDFTextObj_GetRenderedBitmap`.
    pub fn rendered_bitmap(
        &self,
        _page_index: usize,
        _scale: f32,
    ) -> Result<Bitmap, crate::error::EditError> {
        Err(crate::error::EditError::NotSupported(
            "rendered_bitmap: rendering page objects to bitmap requires document context (ADR-002: read-only)".into()
        ))
    }

    /// Upstream-aligned alias for [`rendered_bitmap()`](Self::rendered_bitmap).
    ///
    /// Corresponds to `FPDFTextObj_GetRenderedBitmap`.
    #[inline]
    pub fn text_obj_get_rendered_bitmap(
        &self,
        page_index: usize,
        scale: f32,
    ) -> Result<Bitmap, crate::error::EditError> {
        self.rendered_bitmap(page_index, scale)
    }

    /// Non-upstream alias — use [`text_obj_get_rendered_bitmap()`](Self::text_obj_get_rendered_bitmap).
    ///
    /// Corresponds to `FPDFTextObj_GetRenderedBitmap`.
    #[deprecated(
        note = "use `text_obj_get_rendered_bitmap()` — matches upstream `FPDFTextObj_GetRenderedBitmap`"
    )]
    #[inline]
    pub fn get_rendered_bitmap(
        &self,
        page_index: usize,
        scale: f32,
    ) -> Result<Bitmap, crate::error::EditError> {
        self.rendered_bitmap(page_index, scale)
    }
}

/// An image XObject to be placed on a page.
#[derive(Debug, Clone)]
pub struct ImageObject {
    /// Raw image data (format depends on filter).
    pub image_data: Vec<u8>,
    /// Image width in pixels.
    pub width: u32,
    /// Image height in pixels.
    pub height: u32,
    /// Bits per color component.
    pub bits_per_component: u8,
    /// Color space name (e.g., DeviceRGB, DeviceGray).
    pub color_space: Name,
    /// Transformation matrix (scales/positions the image on the page).
    pub matrix: Matrix,
    /// Optional filter name (e.g., FlateDecode, DCTDecode).
    pub filter: Option<Name>,
    /// Optional pre-existing XObject ID. If set, the image is already stored
    /// in the document and will be referenced by this ID. If `None`, the
    /// caller must create the image stream and assign an ID before generating
    /// the content stream.
    pub xobject_id: Option<ObjectId>,
    /// Blend mode for compositing.
    ///
    /// Corresponds to `FPDFPageObj_GetBlendMode` / `FPDFPageObj_SetBlendMode`.
    pub blend_mode: Option<BlendMode>,
    /// Whether the object is active (visible).
    ///
    /// Corresponds to `FPDFPageObj_GetIsActive` / `FPDFPageObj_SetIsActive`.
    pub active: bool,
    /// Content marks attached to this object (for tagged PDF / accessibility).
    ///
    /// Each mark corresponds to a `BDC`…`EMC` pair wrapping this object in
    /// the content stream.
    ///
    /// Corresponds to `FPDFPageObj_CountMarks` / `FPDFPageObj_GetMark` / etc.
    pub marks: Vec<ContentMark>,
    /// Optional clipping path attached to this object.
    ///
    /// Corresponds to `FPDFPageObj_GetClipPath` / `FPDFPageObj_TransformClipPath`.
    pub clip_path: Option<ClipPath>,
}

/// Metadata about an image XObject.
///
/// Corresponds to the output of `FPDFImageObj_GetImageMetadata`.
#[derive(Debug, Clone, PartialEq)]
pub struct ImageMetadata {
    /// Image width in pixels.
    pub width: u32,
    /// Image height in pixels.
    pub height: u32,
    /// Horizontal resolution in pixels per inch.
    ///
    /// Computed from the image's transformation matrix: `width * 72 / |x-axis length|`.
    /// Returns `0.0` if the matrix scale is zero (degenerate transform).
    pub horizontal_dpi: f32,
    /// Vertical resolution in pixels per inch.
    ///
    /// Computed from the image's transformation matrix: `height * 72 / |y-axis length|`.
    /// Returns `0.0` if the matrix scale is zero (degenerate transform).
    pub vertical_dpi: f32,
    /// Bits per color component.
    pub bits_per_component: u8,
    /// Color space name (e.g., `DeviceRGB`, `DeviceGray`).
    pub color_space: Name,
    /// Filter name (e.g., `FlateDecode`); `None` if the image is uncompressed.
    pub filter: Option<Name>,
    /// Marked content ID, or `-1` if the image is not associated with a marked-content sequence.
    ///
    /// Corresponds to `FPDF_IMAGEOBJ_METADATA::marked_content_id`.
    pub marked_content_id: i32,
}

/// A reference to a form XObject (pre-existing content).
#[derive(Debug, Clone)]
pub struct FormObject {
    /// The object ID of the form XObject.
    pub xobject_id: ObjectId,
    /// Transformation matrix.
    pub matrix: Matrix,
    /// Blend mode for compositing.
    ///
    /// Corresponds to `FPDFPageObj_GetBlendMode` / `FPDFPageObj_SetBlendMode`.
    pub blend_mode: Option<BlendMode>,
    /// Whether the object is active (visible).
    ///
    /// Corresponds to `FPDFPageObj_GetIsActive` / `FPDFPageObj_SetIsActive`.
    pub active: bool,
    /// Content marks attached to this object (for tagged PDF / accessibility).
    ///
    /// Each mark corresponds to a `BDC`…`EMC` pair wrapping this object in
    /// the content stream.
    ///
    /// Corresponds to `FPDFPageObj_CountMarks` / `FPDFPageObj_GetMark` / etc.
    pub marks: Vec<ContentMark>,
    /// Optional clipping path attached to this object.
    ///
    /// Corresponds to `FPDFPageObj_GetClipPath` / `FPDFPageObj_TransformClipPath`.
    pub clip_path: Option<ClipPath>,
}

impl FormObject {
    /// Create a `FormObject` referencing an existing Form XObject.
    ///
    /// `xobject_id` is the PDF object ID of the Form XObject stream in the
    /// document.  `matrix` controls placement on the destination page.
    ///
    /// Corresponds to `FPDF_NewFormObjectFromXObject`.
    pub fn from_xobject(xobject_id: ObjectId, matrix: Matrix) -> Self {
        Self {
            xobject_id,
            matrix,
            blend_mode: None,
            active: true,
            marks: Vec::new(),
            clip_path: None,
        }
    }

    /// Upstream-aligned alias for [`from_xobject()`](Self::from_xobject).
    ///
    /// Corresponds to `FPDF_NewFormObjectFromXObject`.
    #[inline]
    pub fn new_form_object_from_x_object(xobject_id: ObjectId, matrix: Matrix) -> Self {
        Self::from_xobject(xobject_id, matrix)
    }

    /// Deprecated — use [`new_form_object_from_x_object()`](Self::new_form_object_from_x_object) instead.
    ///
    /// Corresponds to `FPDF_NewFormObjectFromXObject`.
    #[deprecated(
        note = "use `new_form_object_from_x_object()` — matches upstream `FPDF_NewFormObjectFromXObject`"
    )]
    #[inline]
    pub fn new_form_object_from_xobject(xobject_id: ObjectId, matrix: Matrix) -> Self {
        Self::from_xobject(xobject_id, matrix)
    }

    /// Applies a matrix transform by pre-multiplying into the object's matrix.
    ///
    /// Corresponds to `FPDFPageObj_Transform`.
    pub fn transform(&mut self, m: &Matrix) {
        self.matrix = m.pre_concat(&self.matrix);
    }

    /// Returns the blend mode for this object.
    ///
    /// Corresponds to `FPDFPageObj_GetBlendMode`.
    pub fn blend_mode(&self) -> Option<BlendMode> {
        self.blend_mode
    }

    /// Upstream-aligned alias for [`blend_mode()`](Self::blend_mode).
    ///
    /// Corresponds to `FPDFPageObj_GetBlendMode`.
    #[inline]
    pub fn page_obj_get_blend_mode(&self) -> Option<BlendMode> {
        self.blend_mode()
    }

    /// Non-upstream alias — use [`page_obj_get_blend_mode()`](Self::page_obj_get_blend_mode).
    ///
    /// Corresponds to `FPDFPageObj_GetBlendMode`.
    #[deprecated(
        note = "use `page_obj_get_blend_mode()` — matches upstream `FPDFPageObj_GetBlendMode`"
    )]
    #[inline]
    pub fn get_blend_mode(&self) -> Option<BlendMode> {
        self.blend_mode()
    }

    /// Sets the blend mode for this object.
    ///
    /// Corresponds to `FPDFPageObj_SetBlendMode`.
    pub fn set_blend_mode(&mut self, mode: Option<BlendMode>) {
        self.blend_mode = mode;
    }

    /// Returns a reference to the transformation matrix.
    ///
    /// Corresponds to `FPDFPageObj_GetMatrix`.
    pub fn matrix(&self) -> &Matrix {
        &self.matrix
    }

    /// Upstream-aligned alias for [`matrix()`](Self::matrix).
    ///
    /// Corresponds to `FPDFPageObj_GetMatrix`.
    #[inline]
    pub fn page_obj_get_matrix(&self) -> &Matrix {
        self.matrix()
    }

    #[deprecated(note = "use `page_obj_get_matrix()` — matches upstream `FPDFPageObj_GetMatrix`")]
    #[inline]
    pub fn get_matrix(&self) -> &Matrix {
        self.matrix()
    }

    /// Set the transformation matrix.
    ///
    /// Corresponds to `FPDFPageObj_SetMatrix`.
    pub fn set_matrix(&mut self, matrix: Matrix) {
        self.matrix = matrix;
    }

    /// Returns the bounding box of this form object in page coordinates.
    ///
    /// The unit square `[0,0]–[1,1]` is mapped through `self.matrix` and the
    /// axis-aligned bounding box of the four transformed corners is returned.
    ///
    /// Corresponds to `FPDFPageObj_GetBounds` for form objects.
    pub fn bounds(&self) -> Option<rpdfium_core::Rect> {
        let unit = rpdfium_core::Rect::new(0.0, 0.0, 1.0, 1.0);
        let r = self.matrix.transform_rect(unit);
        if r.is_empty() { None } else { Some(r) }
    }

    // -----------------------------------------------------------------------
    // Content marks  (FPDFPageObj_CountMarks / GetMark / AddMark / RemoveMark)
    // -----------------------------------------------------------------------

    /// Return the number of content marks on this object.
    ///
    /// Corresponds to `FPDFPageObj_CountMarks`.
    pub fn mark_count(&self) -> usize {
        self.marks.len()
    }

    /// Upstream-aligned alias for [`mark_count()`](Self::mark_count).
    ///
    /// Corresponds to `FPDFPageObj_CountMarks`.
    #[inline]
    pub fn page_obj_count_marks(&self) -> usize {
        self.mark_count()
    }

    /// Non-upstream alias — use [`page_obj_count_marks()`](Self::page_obj_count_marks).
    ///
    /// Corresponds to `FPDFPageObj_CountMarks`.
    #[deprecated(note = "use `page_obj_count_marks()` — matches upstream `FPDFPageObj_CountMarks`")]
    #[inline]
    pub fn count_marks(&self) -> usize {
        self.mark_count()
    }

    /// Return the content mark at the given index, or `None` if out of range.
    ///
    /// Corresponds to `FPDFPageObj_GetMark`.
    pub fn mark(&self, index: usize) -> Option<&ContentMark> {
        self.marks.get(index)
    }

    /// Upstream-aligned alias for [`mark()`](Self::mark).
    ///
    /// Corresponds to `FPDFPageObj_GetMark`.
    #[inline]
    pub fn page_obj_get_mark(&self, index: usize) -> Option<&ContentMark> {
        self.mark(index)
    }

    /// Non-upstream alias — use [`page_obj_get_mark()`](Self::page_obj_get_mark).
    ///
    /// Corresponds to `FPDFPageObj_GetMark`.
    #[deprecated(note = "use `page_obj_get_mark()` — matches upstream `FPDFPageObj_GetMark`")]
    #[inline]
    pub fn get_mark(&self, index: usize) -> Option<&ContentMark> {
        self.mark(index)
    }

    /// Add a new content mark with the given name and return a mutable
    /// reference to it.
    ///
    /// Corresponds to `FPDFPageObj_AddMark`.
    pub fn add_mark(&mut self, name: impl Into<String>) -> &mut ContentMark {
        self.marks.push(ContentMark::new(name));
        self.marks.last_mut().unwrap()
    }

    /// Remove the content mark at the given index.
    ///
    /// Returns `true` if the index was valid and the mark was removed, `false`
    /// if out of range.
    ///
    /// Corresponds to `FPDFPageObj_RemoveMark`.
    pub fn remove_mark(&mut self, index: usize) -> bool {
        if index < self.marks.len() {
            self.marks.remove(index);
            true
        } else {
            false
        }
    }

    /// Return a slice of all content marks on this object.
    pub fn marks(&self) -> &[ContentMark] {
        &self.marks
    }

    /// Return the marked content ID (`/MCID`) from the first mark that has one,
    /// or `None` if no mark carries an MCID.
    ///
    /// Corresponds to `FPDFPageObj_GetMarkedContentID`.
    pub fn marked_content_id(&self) -> Option<i64> {
        self.marks.iter().find_map(|m| m.marked_content_id())
    }

    /// Upstream-aligned alias for [`marked_content_id()`](Self::marked_content_id).
    ///
    /// Corresponds to `FPDFPageObj_GetMarkedContentID`.
    #[inline]
    pub fn page_obj_get_marked_content_id(&self) -> Option<i64> {
        self.marked_content_id()
    }

    /// Non-upstream alias — use [`page_obj_get_marked_content_id()`](Self::page_obj_get_marked_content_id).
    ///
    /// Corresponds to `FPDFPageObj_GetMarkedContentID`.
    #[deprecated(
        note = "use `page_obj_get_marked_content_id()` — matches upstream `FPDFPageObj_GetMarkedContentID`"
    )]
    #[inline]
    pub fn get_marked_content_id(&self) -> Option<i64> {
        self.marked_content_id()
    }

    /// Returns `true` if this form object has any transparency.
    ///
    /// A form object is considered transparent when it has a non-`Normal`
    /// blend mode.
    ///
    /// Corresponds to `FPDFPageObj_HasTransparency`.
    pub fn has_transparency(&self) -> bool {
        matches!(self.blend_mode, Some(bm) if bm != BlendMode::Normal)
    }

    /// Non-upstream convenience alias for [`has_transparency()`](Self::has_transparency).
    ///
    /// Prefer [`has_transparency()`](Self::has_transparency), which matches
    /// the upstream `FPDFPageObj_HasTransparency` name exactly.
    #[deprecated(note = "use `has_transparency()` — matches upstream FPDFPageObj_HasTransparency")]
    #[inline]
    pub fn is_transparent(&self) -> bool {
        self.has_transparency()
    }

    /// Returns the PDFium page-object-type constant for form objects: `5`.
    ///
    /// Corresponds to `FPDFPageObj_GetType` returning `FPDF_PAGEOBJ_FORM`.
    pub fn object_type(&self) -> u32 {
        5
    }

    /// Non-upstream alias — use [`get_type()`](Self::get_type).
    ///
    /// The actual upstream function is `FPDFPageObj_GetType`; there is no
    /// `FPDFPageObj_GetObjectType`.
    #[deprecated(note = "use `page_obj_get_type()` — matches upstream `FPDFPageObj_GetType`")]
    #[inline]
    pub fn get_object_type(&self) -> u32 {
        self.object_type()
    }

    /// Upstream-aligned alias for [`object_type()`](Self::object_type).
    ///
    /// Corresponds to `FPDFPageObj_GetType`.
    #[inline]
    pub fn page_obj_get_type(&self) -> u32 {
        self.object_type()
    }

    #[deprecated(note = "use `page_obj_get_type()` — matches upstream `FPDFPageObj_GetType`")]
    #[inline]
    pub fn get_type(&self) -> u32 {
        self.object_type()
    }

    /// Returns the number of page objects within this Form XObject.
    ///
    /// # Not Supported
    ///
    /// Reading child objects from Form XObject content streams requires a live
    /// document reference not available at the page object level.
    ///
    /// Corresponds to `FPDFFormObj_CountObjects`.
    pub fn object_count(&self) -> Result<usize, crate::error::EditError> {
        Err(crate::error::EditError::NotSupported(
            "object_count: Form XObject child enumeration not supported (requires document context)"
                .into(),
        ))
    }

    /// Upstream-aligned alias for [`object_count()`](Self::object_count).
    ///
    /// Corresponds to `FPDFFormObj_CountObjects`.
    #[inline]
    pub fn form_obj_count_objects(&self) -> Result<usize, crate::error::EditError> {
        self.object_count()
    }

    /// Non-upstream alias — use [`form_obj_count_objects()`](Self::form_obj_count_objects).
    ///
    /// Corresponds to `FPDFFormObj_CountObjects`.
    #[deprecated(
        note = "use `form_obj_count_objects()` — matches upstream `FPDFFormObj_CountObjects`"
    )]
    #[inline]
    pub fn count_objects(&self) -> Result<usize, crate::error::EditError> {
        self.object_count()
    }

    /// Returns the page object at `index` within this Form XObject.
    ///
    /// # Not Supported
    ///
    /// See [`object_count()`](Self::object_count) for explanation.
    ///
    /// Corresponds to `FPDFFormObj_GetObject`.
    pub fn object_at(&self, _index: usize) -> Result<PageObject, crate::error::EditError> {
        Err(crate::error::EditError::NotSupported(
            "object_at: Form XObject child enumeration not supported (requires document context)"
                .into(),
        ))
    }

    /// Upstream-aligned alias for [`object_at()`](Self::object_at).
    ///
    /// Corresponds to `FPDFFormObj_GetObject`.
    #[inline]
    pub fn form_obj_get_object(&self, index: usize) -> Result<PageObject, crate::error::EditError> {
        self.object_at(index)
    }

    /// Non-upstream alias — use [`form_obj_get_object()`](Self::form_obj_get_object).
    ///
    /// Corresponds to `FPDFFormObj_GetObject`.
    #[deprecated(note = "use `form_obj_get_object()` — matches upstream `FPDFFormObj_GetObject`")]
    #[inline]
    pub fn get_object(&self, index: usize) -> Result<PageObject, crate::error::EditError> {
        self.object_at(index)
    }

    /// Removes a page object from this Form XObject.
    ///
    /// # Not Supported
    ///
    /// Mutation of Form XObject content streams is not currently supported.
    ///
    /// Corresponds to `FPDFFormObj_RemoveObject`.
    pub fn remove_object(&mut self, _index: usize) -> Result<PageObject, crate::error::EditError> {
        Err(crate::error::EditError::NotSupported(
            "remove_object: Form XObject child mutation not supported".into(),
        ))
    }
}

impl ImageObject {
    /// Create an `ImageObject` from a rendered [`Bitmap`].
    ///
    /// Converts an `Rgba32` (premultiplied-alpha) bitmap to RGB24, applies
    /// `FlateDecode` compression, and returns an `ImageObject` ready for
    /// embedding in a PDF page.
    ///
    /// The `matrix` parameter controls placement on the page.  A typical
    /// value for a *w*×*h* image at page coordinates `(x, y)` is
    /// `Matrix::new(w as f64, 0.0, 0.0, h as f64, x, y)`.
    ///
    /// # Panics
    ///
    /// Panics if `bitmap.format != BitmapFormat::Rgba32`.
    pub fn from_bitmap(bitmap: &Bitmap, matrix: Matrix) -> Self {
        assert_eq!(
            bitmap.format,
            BitmapFormat::Rgba32,
            "from_bitmap requires Rgba32 format"
        );

        let w = bitmap.width as usize;
        let h = bitmap.height as usize;
        let stride = bitmap.stride as usize;
        let mut rgb_data = Vec::with_capacity(w * h * 3);

        for row in 0..h {
            for col in 0..w {
                let offset = row * stride + col * 4;
                let r = bitmap.data[offset];
                let g = bitmap.data[offset + 1];
                let b = bitmap.data[offset + 2];
                let a = bitmap.data[offset + 3];
                if a == 0 {
                    rgb_data.extend_from_slice(&[0, 0, 0]);
                } else if a == 255 {
                    rgb_data.extend_from_slice(&[r, g, b]);
                } else {
                    let a32 = a as u32;
                    let ru = ((r as u32 * 255 + a32 / 2) / a32).min(255) as u8;
                    let gu = ((g as u32 * 255 + a32 / 2) / a32).min(255) as u8;
                    let bu = ((b as u32 * 255 + a32 / 2) / a32).min(255) as u8;
                    rgb_data.extend_from_slice(&[ru, gu, bu]);
                }
            }
        }

        let compressed = crate::cpdf_flateencoder::flate_compress(&rgb_data);

        Self {
            image_data: compressed,
            width: bitmap.width,
            height: bitmap.height,
            bits_per_component: 8,
            color_space: Name::from_bytes(b"DeviceRGB".to_vec()),
            matrix,
            filter: Some(Name::from_bytes(b"FlateDecode".to_vec())),
            xobject_id: None,
            blend_mode: None,
            active: true,
            marks: Vec::new(),
            clip_path: None,
        }
    }

    /// Creates an image object embedding raw JPEG bytes directly (DCTDecode filter).
    ///
    /// No decompression or recompression occurs — the JPEG data is stored as-is with
    /// a `/Filter /DCTDecode` stream entry. The JPEG SOF header is parsed to extract
    /// the image dimensions.
    ///
    /// Returns an error if the provided bytes are not a recognisable JPEG (missing
    /// valid SOF0 or SOF2 marker).
    ///
    /// Corresponds to `FPDFImageObj_LoadJpegFile` / `FPDFImageObj_LoadJpegFileInline`
    /// in PDFium's `fpdf_edit.h`.
    pub fn from_jpeg_bytes(
        jpeg_data: Vec<u8>,
        matrix: Matrix,
    ) -> Result<Self, crate::error::EditError> {
        let (width, height) = parse_jpeg_dimensions(&jpeg_data).ok_or_else(|| {
            crate::error::EditError::Other(
                "from_jpeg_bytes: could not parse JPEG dimensions (no SOF0/SOF2 marker found)"
                    .to_owned(),
            )
        })?;

        Ok(Self {
            image_data: jpeg_data,
            width,
            height,
            bits_per_component: 8,
            color_space: Name::from_bytes(b"DeviceRGB".to_vec()),
            matrix,
            filter: Some(Name::from_bytes(b"DCTDecode".to_vec())),
            xobject_id: None,
            blend_mode: None,
            active: true,
            marks: Vec::new(),
            clip_path: None,
        })
    }

    /// Applies a matrix transform by pre-multiplying into the object's matrix.
    ///
    /// Corresponds to `FPDFPageObj_Transform`.
    pub fn transform(&mut self, m: &Matrix) {
        self.matrix = m.pre_concat(&self.matrix);
    }

    /// Returns the blend mode for this object.
    ///
    /// Corresponds to `FPDFPageObj_GetBlendMode`.
    pub fn blend_mode(&self) -> Option<BlendMode> {
        self.blend_mode
    }

    /// Upstream-aligned alias for [`blend_mode()`](Self::blend_mode).
    ///
    /// Corresponds to `FPDFPageObj_GetBlendMode`.
    #[inline]
    pub fn page_obj_get_blend_mode(&self) -> Option<BlendMode> {
        self.blend_mode()
    }

    /// Non-upstream alias — use [`page_obj_get_blend_mode()`](Self::page_obj_get_blend_mode).
    ///
    /// Corresponds to `FPDFPageObj_GetBlendMode`.
    #[deprecated(
        note = "use `page_obj_get_blend_mode()` — matches upstream `FPDFPageObj_GetBlendMode`"
    )]
    #[inline]
    pub fn get_blend_mode(&self) -> Option<BlendMode> {
        self.blend_mode()
    }

    /// Sets the blend mode for this object.
    ///
    /// Corresponds to `FPDFPageObj_SetBlendMode`.
    pub fn set_blend_mode(&mut self, mode: Option<BlendMode>) {
        self.blend_mode = mode;
    }

    /// Returns metadata about this image object.
    ///
    /// Corresponds to `FPDFImageObj_GetImageMetadata`.
    pub fn metadata(&self) -> ImageMetadata {
        // Compute DPI from the transformation matrix.
        // The matrix maps from image space (unit square) to page space (user units, 72 per inch).
        // x-axis scale = sqrt(a^2 + b^2), y-axis scale = sqrt(c^2 + d^2).
        let m = &self.matrix;
        let scale_x = (m.a * m.a + m.b * m.b).sqrt() as f32;
        let scale_y = (m.c * m.c + m.d * m.d).sqrt() as f32;
        let horizontal_dpi = if scale_x > 0.0 {
            self.width as f32 * 72.0 / scale_x
        } else {
            0.0
        };
        let vertical_dpi = if scale_y > 0.0 {
            self.height as f32 * 72.0 / scale_y
        } else {
            0.0
        };

        ImageMetadata {
            width: self.width,
            height: self.height,
            horizontal_dpi,
            vertical_dpi,
            bits_per_component: self.bits_per_component,
            color_space: self.color_space.clone(),
            filter: self.filter.clone(),
            marked_content_id: -1,
        }
    }

    /// Upstream-aligned alias for [`metadata()`](Self::metadata).
    ///
    /// Corresponds to `FPDFImageObj_GetImageMetadata`.
    #[inline]
    pub fn image_obj_get_image_metadata(&self) -> ImageMetadata {
        self.metadata()
    }

    #[deprecated(
        note = "use `image_obj_get_image_metadata()` — matches upstream `FPDFImageObj_GetImageMetadata`"
    )]
    #[inline]
    pub fn get_image_metadata(&self) -> ImageMetadata {
        self.metadata()
    }

    /// Returns the raw (possibly compressed) image data.
    ///
    /// Corresponds to `FPDFImageObj_GetImageDataRaw`.
    pub fn raw_data(&self) -> &[u8] {
        &self.image_data
    }

    /// Upstream-aligned alias for [`raw_data()`](Self::raw_data).
    ///
    /// Corresponds to `FPDFImageObj_GetImageDataRaw`.
    #[inline]
    pub fn image_obj_get_image_data_raw(&self) -> &[u8] {
        self.raw_data()
    }

    #[deprecated(
        note = "use `image_obj_get_image_data_raw()` — matches upstream `FPDFImageObj_GetImageDataRaw`"
    )]
    #[inline]
    pub fn get_image_data_raw(&self) -> &[u8] {
        self.raw_data()
    }

    /// Returns the decoded (decompressed) image data.
    ///
    /// If a filter is set (e.g. `FlateDecode`), the data is decompressed via
    /// the filter pipeline.  If the image is uncompressed, returns the raw
    /// data unchanged.
    ///
    /// Corresponds to `FPDFImageObj_GetImageDataDecoded`.
    pub fn decoded_data(&self) -> Result<Vec<u8>, crate::error::EditError> {
        if let Some(ref filter_name) = self.filter {
            let filter = parse_image_filter(filter_name)?;
            rpdfium_codec::apply_filter_chain(
                &self.image_data,
                &[(filter, rpdfium_codec::FilterParams::default())],
            )
            .map_err(|e| crate::error::EditError::Other(format!("image decode error: {e}")))
        } else {
            Ok(self.image_data.clone())
        }
    }

    /// Upstream-aligned alias for [`decoded_data()`](Self::decoded_data).
    ///
    /// Corresponds to `FPDFImageObj_GetImageDataDecoded`.
    #[inline]
    pub fn image_obj_get_image_data_decoded(&self) -> Result<Vec<u8>, crate::error::EditError> {
        self.decoded_data()
    }

    #[deprecated(
        note = "use `image_obj_get_image_data_decoded()` — matches upstream `FPDFImageObj_GetImageDataDecoded`"
    )]
    #[inline]
    pub fn get_image_data_decoded(&self) -> Result<Vec<u8>, crate::error::EditError> {
        self.decoded_data()
    }

    /// Decodes the image data and returns it as a [`Bitmap`].
    ///
    /// - `DeviceRGB` images → `BitmapFormat::Rgba32` (alpha = 255)
    /// - `DeviceGray` images → `BitmapFormat::Gray8`
    ///
    /// Returns an error for unsupported color spaces or if the decoded data is
    /// too short for the declared dimensions.
    ///
    /// Corresponds to `FPDFImageObj_GetBitmap`.
    pub fn to_bitmap(&self) -> Result<Bitmap, crate::error::EditError> {
        let decoded = self.decoded_data()?;
        let cs = self.color_space.as_bytes();
        if cs == b"DeviceRGB" || cs == b"RGB" {
            let w = self.width as usize;
            let h = self.height as usize;
            let expected = w * h * 3;
            if decoded.len() < expected {
                return Err(crate::error::EditError::Other(format!(
                    "decoded image too short: {} < {} (DeviceRGB {}x{})",
                    decoded.len(),
                    expected,
                    self.width,
                    self.height
                )));
            }
            let mut bmp = Bitmap::new(self.width, self.height, BitmapFormat::Rgba32);
            let stride = bmp.stride as usize;
            for row in 0..h {
                for col in 0..w {
                    let src = (row * w + col) * 3;
                    let dst = row * stride + col * 4;
                    bmp.data[dst] = decoded[src];
                    bmp.data[dst + 1] = decoded[src + 1];
                    bmp.data[dst + 2] = decoded[src + 2];
                    bmp.data[dst + 3] = 255;
                }
            }
            Ok(bmp)
        } else if cs == b"DeviceGray" || cs == b"Gray" {
            let w = self.width as usize;
            let h = self.height as usize;
            let expected = w * h;
            if decoded.len() < expected {
                return Err(crate::error::EditError::Other(format!(
                    "decoded image too short: {} < {} (DeviceGray {}x{})",
                    decoded.len(),
                    expected,
                    self.width,
                    self.height
                )));
            }
            let mut bmp = Bitmap::new(self.width, self.height, BitmapFormat::Gray8);
            let stride = bmp.stride as usize;
            for row in 0..h {
                let src = row * w;
                let dst = row * stride;
                bmp.data[dst..dst + w].copy_from_slice(&decoded[src..src + w]);
            }
            Ok(bmp)
        } else {
            Err(crate::error::EditError::Other(format!(
                "to_bitmap: unsupported color space {:?}",
                self.color_space
            )))
        }
    }

    /// Upstream-aligned alias for [`to_bitmap()`](Self::to_bitmap).
    ///
    /// Corresponds to `FPDFImageObj_GetBitmap`.
    #[inline]
    pub fn image_obj_get_bitmap(&self) -> Result<Bitmap, crate::error::EditError> {
        self.to_bitmap()
    }

    /// Non-upstream alias — use [`image_obj_get_bitmap()`](Self::image_obj_get_bitmap).
    ///
    /// Corresponds to `FPDFImageObj_GetBitmap`.
    #[deprecated(note = "use `image_obj_get_bitmap()` — matches upstream `FPDFImageObj_GetBitmap`")]
    #[inline]
    pub fn get_bitmap(&self) -> Result<Bitmap, crate::error::EditError> {
        self.to_bitmap()
    }

    /// Returns a reference to the transformation matrix.
    ///
    /// Corresponds to `FPDFPageObj_GetMatrix`.
    pub fn matrix(&self) -> &Matrix {
        &self.matrix
    }

    /// Upstream-aligned alias for [`matrix()`](Self::matrix).
    ///
    /// Corresponds to `FPDFPageObj_GetMatrix`.
    #[inline]
    pub fn page_obj_get_matrix(&self) -> &Matrix {
        self.matrix()
    }

    #[deprecated(note = "use `page_obj_get_matrix()` — matches upstream `FPDFPageObj_GetMatrix`")]
    #[inline]
    pub fn get_matrix(&self) -> &Matrix {
        self.matrix()
    }

    /// Set the transformation matrix.
    ///
    /// Corresponds to `FPDFImageObj_SetMatrix`.
    pub fn set_matrix(&mut self, matrix: Matrix) {
        self.matrix = matrix;
    }

    /// Upstream-aligned alias for [`set_matrix()`](Self::set_matrix).
    ///
    /// Corresponds to `FPDFImageObj_SetMatrix`.
    #[inline]
    pub fn image_obj_set_matrix(&mut self, matrix: Matrix) {
        self.set_matrix(matrix)
    }

    /// Returns the bounding box of this image object in page coordinates.
    ///
    /// The unit square `[0,0]–[1,1]` is mapped through `self.matrix` and the
    /// axis-aligned bounding box of the four transformed corners is returned.
    ///
    /// Corresponds to `FPDFPageObj_GetBounds` for image objects.
    pub fn bounds(&self) -> Option<rpdfium_core::Rect> {
        let unit = rpdfium_core::Rect::new(0.0, 0.0, 1.0, 1.0);
        let r = self.matrix.transform_rect(unit);
        if r.is_empty() { None } else { Some(r) }
    }

    // -----------------------------------------------------------------------
    // Content marks  (FPDFPageObj_CountMarks / GetMark / AddMark / RemoveMark)
    // -----------------------------------------------------------------------

    /// Return the number of content marks on this object.
    ///
    /// Corresponds to `FPDFPageObj_CountMarks`.
    pub fn mark_count(&self) -> usize {
        self.marks.len()
    }

    /// Upstream-aligned alias for [`mark_count()`](Self::mark_count).
    ///
    /// Corresponds to `FPDFPageObj_CountMarks`.
    #[inline]
    pub fn page_obj_count_marks(&self) -> usize {
        self.mark_count()
    }

    /// Non-upstream alias — use [`page_obj_count_marks()`](Self::page_obj_count_marks).
    ///
    /// Corresponds to `FPDFPageObj_CountMarks`.
    #[deprecated(note = "use `page_obj_count_marks()` — matches upstream `FPDFPageObj_CountMarks`")]
    #[inline]
    pub fn count_marks(&self) -> usize {
        self.mark_count()
    }

    /// Return the content mark at the given index, or `None` if out of range.
    ///
    /// Corresponds to `FPDFPageObj_GetMark`.
    pub fn mark(&self, index: usize) -> Option<&ContentMark> {
        self.marks.get(index)
    }

    /// Upstream-aligned alias for [`mark()`](Self::mark).
    ///
    /// Corresponds to `FPDFPageObj_GetMark`.
    #[inline]
    pub fn page_obj_get_mark(&self, index: usize) -> Option<&ContentMark> {
        self.mark(index)
    }

    /// Non-upstream alias — use [`page_obj_get_mark()`](Self::page_obj_get_mark).
    ///
    /// Corresponds to `FPDFPageObj_GetMark`.
    #[deprecated(note = "use `page_obj_get_mark()` — matches upstream `FPDFPageObj_GetMark`")]
    #[inline]
    pub fn get_mark(&self, index: usize) -> Option<&ContentMark> {
        self.mark(index)
    }

    /// Add a new content mark with the given name and return a mutable
    /// reference to it.
    ///
    /// Corresponds to `FPDFPageObj_AddMark`.
    pub fn add_mark(&mut self, name: impl Into<String>) -> &mut ContentMark {
        self.marks.push(ContentMark::new(name));
        self.marks.last_mut().unwrap()
    }

    /// Remove the content mark at the given index.
    ///
    /// Returns `true` if the index was valid and the mark was removed, `false`
    /// if out of range.
    ///
    /// Corresponds to `FPDFPageObj_RemoveMark`.
    pub fn remove_mark(&mut self, index: usize) -> bool {
        if index < self.marks.len() {
            self.marks.remove(index);
            true
        } else {
            false
        }
    }

    /// Return a slice of all content marks on this object.
    pub fn marks(&self) -> &[ContentMark] {
        &self.marks
    }

    /// Return the marked content ID (`/MCID`) from the first mark that has one,
    /// or `None` if no mark carries an MCID.
    ///
    /// Corresponds to `FPDFPageObj_GetMarkedContentID`.
    pub fn marked_content_id(&self) -> Option<i64> {
        self.marks.iter().find_map(|m| m.marked_content_id())
    }

    /// Upstream-aligned alias for [`marked_content_id()`](Self::marked_content_id).
    ///
    /// Corresponds to `FPDFPageObj_GetMarkedContentID`.
    #[inline]
    pub fn page_obj_get_marked_content_id(&self) -> Option<i64> {
        self.marked_content_id()
    }

    /// Non-upstream alias — use [`page_obj_get_marked_content_id()`](Self::page_obj_get_marked_content_id).
    ///
    /// Corresponds to `FPDFPageObj_GetMarkedContentID`.
    #[deprecated(
        note = "use `page_obj_get_marked_content_id()` — matches upstream `FPDFPageObj_GetMarkedContentID`"
    )]
    #[inline]
    pub fn get_marked_content_id(&self) -> Option<i64> {
        self.marked_content_id()
    }

    /// Returns `true` if this image object has any transparency.
    ///
    /// An image object is considered transparent when it has a non-`Normal`
    /// blend mode.
    ///
    /// Corresponds to `FPDFPageObj_HasTransparency`.
    pub fn has_transparency(&self) -> bool {
        matches!(self.blend_mode, Some(bm) if bm != BlendMode::Normal)
    }

    /// Non-upstream convenience alias for [`has_transparency()`](Self::has_transparency).
    ///
    /// Prefer [`has_transparency()`](Self::has_transparency), which matches
    /// the upstream `FPDFPageObj_HasTransparency` name exactly.
    #[deprecated(note = "use `has_transparency()` — matches upstream FPDFPageObj_HasTransparency")]
    #[inline]
    pub fn is_transparent(&self) -> bool {
        self.has_transparency()
    }

    /// Returns the PDFium page-object-type constant for image objects: `3`.
    ///
    /// Corresponds to `FPDFPageObj_GetType` returning `FPDF_PAGEOBJ_IMAGE`.
    pub fn object_type(&self) -> u32 {
        3
    }

    /// Non-upstream alias — use [`page_obj_get_type()`](Self::page_obj_get_type).
    ///
    /// The actual upstream function is `FPDFPageObj_GetType`; there is no
    /// `FPDFPageObj_GetObjectType`.
    #[deprecated(note = "use `page_obj_get_type()` — matches upstream `FPDFPageObj_GetType`")]
    #[inline]
    pub fn get_object_type(&self) -> u32 {
        self.object_type()
    }

    /// Upstream-aligned alias for [`object_type()`](Self::object_type).
    ///
    /// Corresponds to `FPDFPageObj_GetType`.
    #[inline]
    pub fn page_obj_get_type(&self) -> u32 {
        self.object_type()
    }

    #[deprecated(note = "use `page_obj_get_type()` — matches upstream `FPDFPageObj_GetType`")]
    #[inline]
    pub fn get_type(&self) -> u32 {
        self.object_type()
    }

    /// Returns the number of filters applied to this image's data stream.
    ///
    /// This implementation stores at most one filter; returns `1` when a filter
    /// is present, `0` otherwise.
    ///
    /// Corresponds to `FPDFImageObj_GetImageFilterCount`.
    pub fn filter_count(&self) -> usize {
        if self.filter.is_some() { 1 } else { 0 }
    }

    /// Upstream-aligned alias for [`filter_count()`](Self::filter_count).
    ///
    /// Corresponds to `FPDFImageObj_GetImageFilterCount`.
    #[inline]
    pub fn image_obj_get_image_filter_count(&self) -> usize {
        self.filter_count()
    }

    /// Non-upstream alias — use [`image_obj_get_image_filter_count()`](Self::image_obj_get_image_filter_count).
    ///
    /// Corresponds to `FPDFImageObj_GetImageFilterCount`.
    #[deprecated(
        note = "use `image_obj_get_image_filter_count()` — matches upstream `FPDFImageObj_GetImageFilterCount`"
    )]
    #[inline]
    pub fn get_image_filter_count(&self) -> usize {
        self.filter_count()
    }

    /// Returns the filter name at the given index as a `&str`, or `None` if the
    /// index is out of range.
    ///
    /// Only index `0` is valid; any other index returns `None`.
    ///
    /// Corresponds to `FPDFImageObj_GetImageFilter`.
    pub fn filter(&self, index: usize) -> Option<&str> {
        if index == 0 {
            self.filter
                .as_ref()
                .and_then(|n| std::str::from_utf8(n.as_bytes()).ok())
        } else {
            None
        }
    }

    /// Upstream-aligned alias for [`filter()`](Self::filter).
    ///
    /// Corresponds to `FPDFImageObj_GetImageFilter`.
    #[inline]
    pub fn image_obj_get_image_filter(&self, index: usize) -> Option<&str> {
        self.filter(index)
    }

    /// Non-upstream alias — use [`image_obj_get_image_filter()`](Self::image_obj_get_image_filter).
    ///
    /// Corresponds to `FPDFImageObj_GetImageFilter`.
    #[deprecated(
        note = "use `image_obj_get_image_filter()` — matches upstream `FPDFImageObj_GetImageFilter`"
    )]
    #[inline]
    pub fn get_image_filter(&self, index: usize) -> Option<&str> {
        self.filter(index)
    }

    /// Non-upstream alias — use [`image_obj_get_image_filter()`](Self::image_obj_get_image_filter).
    ///
    /// Corresponds to `FPDFImageObj_GetImageFilter`.
    #[deprecated(
        note = "use `image_obj_get_image_filter()` — matches upstream FPDFImageObj_GetImageFilter"
    )]
    #[inline]
    pub fn get_filter(&self, index: usize) -> Option<&str> {
        self.image_obj_get_image_filter(index)
    }

    /// Returns the pixel dimensions of this image object.
    ///
    /// Returns `(width, height)` in pixels.
    ///
    /// Corresponds to `FPDFImageObj_GetImagePixelSize`.
    pub fn pixel_size(&self) -> (u32, u32) {
        (self.width, self.height)
    }

    /// Upstream-aligned alias for [`pixel_size()`](Self::pixel_size).
    ///
    /// Corresponds to `FPDFImageObj_GetImagePixelSize`.
    #[inline]
    pub fn image_obj_get_image_pixel_size(&self) -> (u32, u32) {
        self.pixel_size()
    }

    /// Non-upstream alias — use [`image_obj_get_image_pixel_size()`](Self::image_obj_get_image_pixel_size).
    ///
    /// Corresponds to `FPDFImageObj_GetImagePixelSize`.
    #[deprecated(
        note = "use `image_obj_get_image_pixel_size()` — matches upstream `FPDFImageObj_GetImagePixelSize`"
    )]
    #[inline]
    pub fn get_image_pixel_size(&self) -> (u32, u32) {
        self.pixel_size()
    }

    /// Returns the tight rotated bounding quadrilateral for this image object
    /// as 4 corner points in page coordinates.
    ///
    /// The corners are computed by transforming the unit square
    /// `[0,0]–[1,1]` through the image's placement matrix, giving the
    /// exact (possibly rotated) bounding quad.
    ///
    /// Corresponds to `FPDFPageObj_GetRotatedBounds`.
    pub fn rotated_bounds(&self) -> Option<[rpdfium_core::Point; 4]> {
        let m = &self.matrix;
        let corners = [
            rpdfium_core::Point { x: m.e, y: m.f },
            rpdfium_core::Point {
                x: m.a + m.e,
                y: m.b + m.f,
            },
            rpdfium_core::Point {
                x: m.a + m.c + m.e,
                y: m.b + m.d + m.f,
            },
            rpdfium_core::Point {
                x: m.c + m.e,
                y: m.d + m.f,
            },
        ];
        Some(corners)
    }

    /// Upstream-aligned alias for [`rotated_bounds()`](Self::rotated_bounds).
    ///
    /// Corresponds to `FPDFPageObj_GetRotatedBounds`.
    #[inline]
    pub fn page_obj_get_rotated_bounds(&self) -> Option<[rpdfium_core::Point; 4]> {
        self.rotated_bounds()
    }

    /// Non-upstream alias — use [`page_obj_get_rotated_bounds()`](Self::page_obj_get_rotated_bounds).
    ///
    /// Corresponds to `FPDFPageObj_GetRotatedBounds`.
    #[deprecated(
        note = "use `page_obj_get_rotated_bounds()` — matches upstream `FPDFPageObj_GetRotatedBounds`"
    )]
    #[inline]
    pub fn get_rotated_bounds(&self) -> Option<[rpdfium_core::Point; 4]> {
        self.rotated_bounds()
    }

    /// Returns the rendered bitmap for this image object at the given scale.
    ///
    /// # Not Supported
    ///
    /// Rendering a page object to bitmap requires a live CPDF_Document/CPDF_Page
    /// handle not available in rpdfium's edit layer (read-only, ADR-002).
    ///
    /// Corresponds to `FPDFImageObj_GetRenderedBitmap`.
    pub fn rendered_bitmap(
        &self,
        _page_index: usize,
        _scale: f32,
    ) -> Result<Bitmap, crate::error::EditError> {
        Err(crate::error::EditError::NotSupported(
            "rendered_bitmap: rendering page objects to bitmap requires document context (ADR-002: read-only)".into()
        ))
    }

    /// Upstream-aligned alias for [`rendered_bitmap()`](Self::rendered_bitmap).
    ///
    /// Corresponds to `FPDFImageObj_GetRenderedBitmap`.
    #[inline]
    pub fn image_obj_get_rendered_bitmap(
        &self,
        page_index: usize,
        scale: f32,
    ) -> Result<Bitmap, crate::error::EditError> {
        self.rendered_bitmap(page_index, scale)
    }

    /// Non-upstream alias — use [`image_obj_get_rendered_bitmap()`](Self::image_obj_get_rendered_bitmap).
    ///
    /// Corresponds to `FPDFImageObj_GetRenderedBitmap`.
    #[deprecated(
        note = "use `image_obj_get_rendered_bitmap()` — matches upstream `FPDFImageObj_GetRenderedBitmap`"
    )]
    #[inline]
    pub fn get_rendered_bitmap(
        &self,
        page_index: usize,
        scale: f32,
    ) -> Result<Bitmap, crate::error::EditError> {
        self.rendered_bitmap(page_index, scale)
    }

    /// Returns the decoded ICC profile bytes embedded in this image object, if any.
    ///
    /// Returns `None` if the image has no embedded ICC profile.
    /// ICC profile extraction requires parsing the image's color space stream,
    /// which is not performed at the edit layer.
    ///
    /// Corresponds to `FPDFImageObj_GetIccProfileDataDecoded`.
    pub fn icc_profile_data_decoded(&self) -> Option<&[u8]> {
        // ICC profile data is stored in the /ColorSpace stream for images.
        // Extraction requires parsing the image's color space stream,
        // which is not performed at the edit layer.
        None
    }

    /// Upstream-aligned alias for [`icc_profile_data_decoded()`](Self::icc_profile_data_decoded).
    ///
    /// Corresponds to `FPDFImageObj_GetIccProfileDataDecoded`.
    #[inline]
    pub fn image_obj_get_icc_profile_data_decoded(&self) -> Option<&[u8]> {
        self.icc_profile_data_decoded()
    }

    /// Non-upstream alias — use [`image_obj_get_icc_profile_data_decoded()`](Self::image_obj_get_icc_profile_data_decoded).
    ///
    /// Corresponds to `FPDFImageObj_GetIccProfileDataDecoded`.
    #[deprecated(
        note = "use `image_obj_get_icc_profile_data_decoded()` — matches upstream `FPDFImageObj_GetIccProfileDataDecoded`"
    )]
    #[inline]
    pub fn get_icc_profile_data_decoded(&self) -> Option<&[u8]> {
        self.icc_profile_data_decoded()
    }
}

/// Convert a slice of renderer [`PathOp`]s to [`PathSegment`]s.
///
/// Coordinates are widened from `f32` to `f64`.  `PathOp::Close` maps to
/// `PathSegment::Close`.  No rectangle detection is performed.
pub fn path_ops_to_segments(ops: &[PathOp]) -> Vec<PathSegment> {
    ops.iter()
        .map(|op| match op {
            PathOp::MoveTo { x, y } => PathSegment::MoveTo(*x as f64, *y as f64),
            PathOp::LineTo { x, y } => PathSegment::LineTo(*x as f64, *y as f64),
            PathOp::CurveTo {
                x1,
                y1,
                x2,
                y2,
                x3,
                y3,
            } => PathSegment::CurveTo(
                *x1 as f64, *y1 as f64, *x2 as f64, *y2 as f64, *x3 as f64, *y3 as f64,
            ),
            PathOp::Close => PathSegment::Close,
        })
        .collect()
}

/// Convert a slice of [`PathSegment`]s to renderer [`PathOp`]s.
///
/// Coordinates are narrowed from `f64` to `f32`.
/// `PathSegment::Rect(x, y, w, h)` expands to five `PathOp`s:
/// `MoveTo`, three `LineTo`s forming the rectangle, and `Close`.
pub fn segments_to_path_ops(segs: &[PathSegment]) -> Vec<PathOp> {
    let mut out = Vec::with_capacity(segs.len());
    for seg in segs {
        match seg {
            PathSegment::MoveTo(x, y) => {
                out.push(PathOp::MoveTo {
                    x: *x as f32,
                    y: *y as f32,
                });
            }
            PathSegment::LineTo(x, y) => {
                out.push(PathOp::LineTo {
                    x: *x as f32,
                    y: *y as f32,
                });
            }
            PathSegment::CurveTo(x1, y1, x2, y2, x3, y3) => {
                out.push(PathOp::CurveTo {
                    x1: *x1 as f32,
                    y1: *y1 as f32,
                    x2: *x2 as f32,
                    y2: *y2 as f32,
                    x3: *x3 as f32,
                    y3: *y3 as f32,
                });
            }
            PathSegment::Rect(x, y, w, h) => {
                let (x, y, w, h) = (*x as f32, *y as f32, *w as f32, *h as f32);
                out.push(PathOp::MoveTo { x, y });
                out.push(PathOp::LineTo { x: x + w, y });
                out.push(PathOp::LineTo { x: x + w, y: y + h });
                out.push(PathOp::LineTo { x, y: y + h });
                out.push(PathOp::Close);
            }
            PathSegment::Close => {
                out.push(PathOp::Close);
            }
        }
    }
    out
}

/// Map a PDF filter name to a [`rpdfium_codec::DecodeFilter`] variant.
///
/// Accepts both the full name (`FlateDecode`) and the abbreviated alias (`Fl`).
fn parse_image_filter(name: &Name) -> Result<rpdfium_codec::DecodeFilter, crate::error::EditError> {
    match name.as_bytes() {
        b"FlateDecode" | b"Fl" => Ok(rpdfium_codec::DecodeFilter::Flate),
        b"DCTDecode" | b"DCT" => Ok(rpdfium_codec::DecodeFilter::DCT),
        b"LZWDecode" | b"LZW" => Ok(rpdfium_codec::DecodeFilter::LZW),
        b"RunLengthDecode" | b"RL" => Ok(rpdfium_codec::DecodeFilter::RunLength),
        b"ASCII85Decode" | b"A85" => Ok(rpdfium_codec::DecodeFilter::ASCII85),
        b"ASCIIHexDecode" | b"AHx" => Ok(rpdfium_codec::DecodeFilter::ASCIIHex),
        b"CCITTFaxDecode" | b"CCF" => Ok(rpdfium_codec::DecodeFilter::CCITTFax),
        b"JBIG2Decode" => Ok(rpdfium_codec::DecodeFilter::JBIG2),
        b"JPXDecode" => Ok(rpdfium_codec::DecodeFilter::JPX),
        _ => Err(crate::error::EditError::Other(format!(
            "unsupported image filter: {:?}",
            name
        ))),
    }
}

/// Parse the pixel dimensions from a JPEG byte stream.
///
/// Scans the JPEG markers for a Start-Of-Frame (SOF) segment: either
/// `SOF0` (0xFFC0) for baseline DCT or `SOF2` (0xFFC2) for progressive DCT.
/// Both store the image height at bytes +3..+4 and width at bytes +5..+6
/// within the segment (after the 2-byte length field).
///
/// Returns `Some((width, height))` when the SOF marker is found, or `None`
/// if the data is too short or contains no recognisable SOF segment.
///
/// Corresponds to the dimension-extraction logic inside
/// `FPDFImageObj_LoadJpegFile` in PDFium.
pub fn parse_jpeg_dimensions(data: &[u8]) -> Option<(u32, u32)> {
    // JPEG streams must start with SOI (0xFF 0xD8).
    if data.len() < 2 || data[0] != 0xFF || data[1] != 0xD8 {
        return None;
    }

    let mut i = 2usize;
    while i + 3 < data.len() {
        // Each marker begins with 0xFF (possibly padded).
        if data[i] != 0xFF {
            return None;
        }
        // Skip any 0xFF padding bytes.
        while i < data.len() && data[i] == 0xFF {
            i += 1;
        }
        if i >= data.len() {
            return None;
        }
        let marker = data[i];
        i += 1;

        // Skip stand-alone markers that have no length field.
        match marker {
            0xD8 | 0xD9 | 0x01 => continue,
            _ => {}
        }

        // Read 2-byte segment length (includes the 2 length bytes themselves).
        if i + 2 > data.len() {
            return None;
        }
        let seg_len = u16::from_be_bytes([data[i], data[i + 1]]) as usize;
        if seg_len < 2 {
            return None;
        }

        // SOF0 = 0xC0 (baseline), SOF2 = 0xC2 (progressive).
        if marker == 0xC0 || marker == 0xC2 {
            // Segment layout: [length(2), precision(1), height(2), width(2), ...]
            // i points at start of length field.
            //   i+0, i+1: length (already read above)
            //   i+2:       precision (bits per sample)
            //   i+3, i+4:  height (big-endian u16)
            //   i+5, i+6:  width  (big-endian u16)
            if i + 7 > data.len() {
                return None;
            }
            let height = u16::from_be_bytes([data[i + 3], data[i + 4]]) as u32;
            let width = u16::from_be_bytes([data[i + 5], data[i + 6]]) as u32;
            return Some((width, height));
        }

        // Advance past this segment.
        let next = i.checked_add(seg_len)?;
        if next > data.len() {
            return None;
        }
        i = next;
    }
    None
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::font_reg::{FontRegistration, FontType};

    fn make_id(n: u32) -> ObjectId {
        ObjectId::new(n, 0)
    }

    #[test]
    fn test_path_object_default() {
        let p = PathObject::default();
        assert!(p.segments.is_empty());
        assert!(p.fill_color.is_none());
        assert!(p.stroke_color.is_none());
        assert_eq!(p.fill_mode, FillMode::None);
        assert!(p.active, "PathObject::default() should be active");
    }

    #[test]
    fn test_path_object_create_at_has_move_to() {
        let p = PathObject::create_at(10.0, 20.0);
        assert_eq!(p.segments.len(), 1);
        assert!(matches!(p.segments[0], PathSegment::MoveTo(x, y) if x == 10.0 && y == 20.0));
    }

    #[test]
    fn test_path_object_create_at_alias() {
        let p1 = PathObject::create_at(5.0, 7.0);
        let p2 = PathObject::page_obj_create_new_path(5.0, 7.0);
        assert_eq!(p1.segments.len(), p2.segments.len());
        assert!(matches!(p1.segments[0], PathSegment::MoveTo(x, y) if x == 5.0 && y == 7.0));
    }

    #[test]
    fn test_path_object_create_rect_has_rect_segment() {
        let p = PathObject::create_rect(0.0, 0.0, 100.0, 50.0);
        assert_eq!(p.segments.len(), 1);
        assert!(matches!(
            p.segments[0],
            PathSegment::Rect(x, y, w, h) if x == 0.0 && y == 0.0 && w == 100.0 && h == 50.0
        ));
    }

    #[test]
    fn test_path_object_create_rect_alias() {
        let p1 = PathObject::create_rect(1.0, 2.0, 3.0, 4.0);
        let p2 = PathObject::page_obj_create_new_rect(1.0, 2.0, 3.0, 4.0);
        assert_eq!(p1.segments.len(), p2.segments.len());
    }

    #[test]
    fn test_page_obj_destroy_returns_not_supported() {
        let p = PageObject::Path(PathObject::default());
        let result = p.page_obj_destroy();
        assert!(result.is_err());
    }

    #[test]
    fn test_text_object_default() {
        let t = TextObject::default();
        assert_eq!(t.font_size, 12.0);
        assert!(t.fill_color.is_some());
        assert!(t.text.is_empty());
        assert!(t.font_object_id.is_none());
        assert!(t.active, "TextObject::default() should be active");
    }

    #[test]
    fn test_page_object_is_active_set_active() {
        let mut p = PageObject::Path(PathObject::default());
        assert!(p.is_active());
        p.set_active(false);
        assert!(!p.is_active());
        p.set_active(true);
        assert!(p.is_active());

        let mut t = PageObject::Text(TextObject::default());
        assert!(t.is_active());
        t.set_active(false);
        assert!(!t.is_active());
    }

    #[test]
    fn test_fill_mode_variants() {
        assert_ne!(FillMode::None, FillMode::EvenOdd);
        assert_ne!(FillMode::EvenOdd, FillMode::NonZero);
    }

    #[test]
    fn test_page_object_enum_variants() {
        let p = PageObject::Path(PathObject::default());
        assert!(matches!(p, PageObject::Path(_)));

        let t = PageObject::Text(TextObject::default());
        assert!(matches!(t, PageObject::Text(_)));
    }

    // ------------------------------------------------------------------
    // New API tests
    // ------------------------------------------------------------------

    #[test]
    fn test_text_object_with_standard_font_name_matches() {
        let t = TextObject::with_standard_font("Times-Roman", 14.0);
        assert_eq!(t.font_name(), &Name::from_bytes(b"Times-Roman".to_vec()));
        assert_eq!(t.font_size(), 14.0);
        assert!(t.font_object_id.is_none());
    }

    #[test]
    fn test_text_object_with_font_uses_registration_id() {
        let reg = FontRegistration::new_standard(make_id(42), "Courier");
        let t = TextObject::with_font(&reg, 10.0);
        assert_eq!(t.font_object_id, Some(make_id(42)));
        assert_eq!(t.font_name(), &Name::from_bytes(b"Courier".to_vec()));
        assert_eq!(t.font_size(), 10.0);
    }

    #[test]
    fn test_text_object_getters_return_correct_values() {
        let mut t = TextObject::with_standard_font("Helvetica", 12.0);
        t.text = "Hello, PDF!".into();
        t.rendering_mode = TextRenderingMode::FillStroke;

        assert_eq!(t.text(), "Hello, PDF!");
        assert_eq!(t.font_size(), 12.0);
        assert_eq!(t.rendering_mode(), TextRenderingMode::FillStroke);
        assert_eq!(t.font_name(), &Name::from_bytes(b"Helvetica".to_vec()));
    }

    #[test]
    fn test_text_object_with_embedded_font() {
        let reg = FontRegistration::new_embedded(
            make_id(99),
            "MyFont",
            FontType::TrueType,
            vec![1, 2, 3],
        );
        let t = TextObject::with_font(&reg, 16.0);
        assert_eq!(t.font_object_id, Some(make_id(99)));
        assert_eq!(t.font_name(), &Name::from_bytes(b"MyFont".to_vec()));
    }

    // ------------------------------------------------------------------
    // Feature 1: PathOp ↔ PathSegment bridge
    // ------------------------------------------------------------------

    #[test]
    fn test_round_trip_basic_path() {
        let ops = vec![
            PathOp::MoveTo { x: 10.0, y: 20.0 },
            PathOp::LineTo { x: 50.0, y: 60.0 },
            PathOp::Close,
        ];
        let segs = path_ops_to_segments(&ops);
        assert!(matches!(segs[0], PathSegment::MoveTo(10.0, 20.0)));
        assert!(matches!(segs[1], PathSegment::LineTo(50.0, 60.0)));
        assert!(matches!(segs[2], PathSegment::Close));

        let back = segments_to_path_ops(&segs);
        assert_eq!(back.len(), ops.len());
        assert!(matches!(back[0], PathOp::MoveTo { x, y } if x == 10.0 && y == 20.0));
        assert!(matches!(back[1], PathOp::LineTo { x, y } if x == 50.0 && y == 60.0));
        assert!(matches!(back[2], PathOp::Close));
    }

    #[test]
    fn test_rect_segment_expands_to_5_ops() {
        let segs = vec![PathSegment::Rect(0.0, 0.0, 10.0, 20.0)];
        let ops = segments_to_path_ops(&segs);
        assert_eq!(ops.len(), 5);
        assert!(matches!(ops[0], PathOp::MoveTo { x, y } if x == 0.0 && y == 0.0));
        assert!(matches!(ops[1], PathOp::LineTo { x, y } if x == 10.0 && y == 0.0));
        assert!(matches!(ops[2], PathOp::LineTo { x, y } if x == 10.0 && y == 20.0));
        assert!(matches!(ops[3], PathOp::LineTo { x, y } if x == 0.0 && y == 20.0));
        assert!(matches!(ops[4], PathOp::Close));
    }

    #[test]
    fn test_f32_precision_preserved() {
        let ops = vec![PathOp::MoveTo {
            x: 0.5_f32,
            y: 1.25_f32,
        }];
        let segs = path_ops_to_segments(&ops);
        if let PathSegment::MoveTo(x, y) = segs[0] {
            assert!((x - 0.5_f64).abs() < 1e-6);
            assert!((y - 1.25_f64).abs() < 1e-6);
        } else {
            panic!("expected MoveTo");
        }
    }

    // ------------------------------------------------------------------
    // Feature 3: Bitmap → ImageObject
    // ------------------------------------------------------------------

    fn make_rgba_bitmap(pixels: &[(u8, u8, u8, u8)], w: u32, h: u32) -> Bitmap {
        let mut bmp = Bitmap::new(w, h, BitmapFormat::Rgba32);
        for (i, &(r, g, b, a)) in pixels.iter().enumerate() {
            let offset = i * 4;
            bmp.data[offset] = r;
            bmp.data[offset + 1] = g;
            bmp.data[offset + 2] = b;
            bmp.data[offset + 3] = a;
        }
        bmp
    }

    #[test]
    fn test_bitmap_to_image_object_dimensions() {
        let bmp = Bitmap::new(2, 2, BitmapFormat::Rgba32);
        let obj = ImageObject::from_bitmap(&bmp, Matrix::identity());
        assert_eq!(obj.width, 2);
        assert_eq!(obj.height, 2);
        assert_eq!(obj.bits_per_component, 8);
    }

    #[test]
    fn test_bitmap_to_image_object_unpremultiply() {
        // Premultiplied: r=128, g=64, b=0, a=128 → unpremultiplied: r≈255, g≈128, b=0
        let bmp = make_rgba_bitmap(&[(128, 64, 0, 128)], 1, 1);
        let obj = ImageObject::from_bitmap(&bmp, Matrix::identity());
        // Decompress the image data to verify the RGB values
        let rgb = rpdfium_codec::apply_filter_chain(
            &obj.image_data,
            &[(
                rpdfium_codec::DecodeFilter::Flate,
                rpdfium_codec::FilterParams::default(),
            )],
        )
        .unwrap();
        assert_eq!(rgb.len(), 3);
        assert_eq!(rgb[0], 255); // r: 128*255/128 = 255
        assert_eq!(rgb[1], 128); // g: 64*255/128 = 128 (rounded)
        assert_eq!(rgb[2], 0); // b: 0
    }

    #[test]
    fn test_bitmap_to_image_object_opaque_pixel_unchanged() {
        let bmp = make_rgba_bitmap(&[(200, 100, 50, 255)], 1, 1);
        let obj = ImageObject::from_bitmap(&bmp, Matrix::identity());
        let rgb = rpdfium_codec::apply_filter_chain(
            &obj.image_data,
            &[(
                rpdfium_codec::DecodeFilter::Flate,
                rpdfium_codec::FilterParams::default(),
            )],
        )
        .unwrap();
        assert_eq!(rgb, vec![200, 100, 50]);
    }

    #[test]
    fn test_bitmap_to_image_object_transparent_pixel_is_black() {
        let bmp = make_rgba_bitmap(&[(100, 100, 100, 0)], 1, 1);
        let obj = ImageObject::from_bitmap(&bmp, Matrix::identity());
        let rgb = rpdfium_codec::apply_filter_chain(
            &obj.image_data,
            &[(
                rpdfium_codec::DecodeFilter::Flate,
                rpdfium_codec::FilterParams::default(),
            )],
        )
        .unwrap();
        assert_eq!(rgb, vec![0, 0, 0]);
    }

    #[test]
    fn test_bitmap_to_image_object_filter_is_flatedecode() {
        let bmp = Bitmap::new(1, 1, BitmapFormat::Rgba32);
        let obj = ImageObject::from_bitmap(&bmp, Matrix::identity());
        assert_eq!(obj.filter, Some(Name::from_bytes(b"FlateDecode".to_vec())));
    }

    // ------------------------------------------------------------------
    // B1: PageObject setters / getters / transform / bounds
    // ------------------------------------------------------------------

    #[test]
    fn test_path_object_set_fill_color() {
        let mut p = PathObject::default();
        assert!(p.fill_color().is_none());
        p.set_fill_color(Color::rgb(1.0, 0.0, 0.0));
        let c = p.fill_color().unwrap();
        assert_eq!(c.components, vec![1.0, 0.0, 0.0]);
    }

    #[test]
    fn test_path_object_set_stroke_color() {
        let mut p = PathObject::default();
        assert!(p.stroke_color().is_none());
        p.set_stroke_color(Color::gray(0.5));
        let c = p.stroke_color().unwrap();
        assert_eq!(c.components, vec![0.5]);
    }

    #[test]
    fn test_path_object_set_line_width() {
        let mut p = PathObject::default();
        assert_eq!(p.line_width(), 1.0);
        p.set_line_width(3.5);
        assert_eq!(p.line_width(), 3.5);
    }

    #[test]
    fn test_path_object_set_line_join_and_cap() {
        let mut p = PathObject::default();
        assert_eq!(p.line_join(), 0);
        assert_eq!(p.line_cap(), 0);
        p.set_line_join(2);
        p.set_line_cap(1);
        assert_eq!(p.line_join(), 2);
        assert_eq!(p.line_cap(), 1);
    }

    /// Upstream: TEST_F(PDFEditTest, LineCap)
    #[test]
    fn test_pdf_edit_line_cap() {
        let mut path = PathObject::default();
        // Default is butt cap (0).
        assert_eq!(path.line_cap(), 0);

        // Set to projecting square (2) and verify.
        path.set_line_cap(2);
        assert_eq!(path.line_cap(), 2);

        // Set to round (1) and verify.
        path.set_line_cap(1);
        assert_eq!(path.line_cap(), 1);

        // Set back to butt (0) and verify.
        path.set_line_cap(0);
        assert_eq!(path.line_cap(), 0);

        // PageObject dispatch: line_cap returns Some for Path, None for others.
        let page_obj = PageObject::Path(path);
        assert_eq!(page_obj.line_cap(), Some(0));

        let text_obj = PageObject::Text(TextObject::default());
        assert_eq!(text_obj.line_cap(), None);
    }

    #[test]
    fn test_path_object_bounds_simple_rect() {
        let p = PathObject {
            segments: vec![PathSegment::Rect(10.0, 20.0, 100.0, 50.0)],
            ..Default::default()
        };
        let b = p.bounds().unwrap();
        assert_eq!(b.left, 10.0);
        assert_eq!(b.bottom, 20.0);
        assert_eq!(b.right, 110.0);
        assert_eq!(b.top, 70.0);
    }

    #[test]
    fn test_path_object_bounds_with_lines() {
        let p = PathObject {
            segments: vec![
                PathSegment::MoveTo(0.0, 0.0),
                PathSegment::LineTo(100.0, 0.0),
                PathSegment::LineTo(100.0, 50.0),
                PathSegment::Close,
            ],
            ..Default::default()
        };
        let b = p.bounds().unwrap();
        assert_eq!(b.left, 0.0);
        assert_eq!(b.bottom, 0.0);
        assert_eq!(b.right, 100.0);
        assert_eq!(b.top, 50.0);
    }

    #[test]
    fn test_path_object_bounds_empty_returns_none() {
        let p = PathObject {
            segments: vec![PathSegment::Close],
            ..Default::default()
        };
        assert!(p.bounds().is_none());
    }

    #[test]
    fn test_path_object_transform_translate() {
        let mut p = PathObject {
            segments: vec![
                PathSegment::MoveTo(10.0, 20.0),
                PathSegment::LineTo(30.0, 40.0),
            ],
            ..Default::default()
        };
        let m = Matrix::new(1.0, 0.0, 0.0, 1.0, 100.0, 200.0);
        p.transform(&m);
        assert!(
            matches!(p.segments[0], PathSegment::MoveTo(x, y) if (x - 110.0).abs() < 1e-9 && (y - 220.0).abs() < 1e-9)
        );
        assert!(
            matches!(p.segments[1], PathSegment::LineTo(x, y) if (x - 130.0).abs() < 1e-9 && (y - 240.0).abs() < 1e-9)
        );
    }

    #[test]
    fn test_path_object_transform_scale_curve() {
        let mut p = PathObject {
            segments: vec![PathSegment::CurveTo(1.0, 2.0, 3.0, 4.0, 5.0, 6.0)],
            ..Default::default()
        };
        let m = Matrix::new(2.0, 0.0, 0.0, 3.0, 0.0, 0.0);
        p.transform(&m);
        if let PathSegment::CurveTo(x1, y1, x2, y2, x3, y3) = p.segments[0] {
            assert!((x1 - 2.0).abs() < 1e-9);
            assert!((y1 - 6.0).abs() < 1e-9);
            assert!((x2 - 6.0).abs() < 1e-9);
            assert!((y2 - 12.0).abs() < 1e-9);
            assert!((x3 - 10.0).abs() < 1e-9);
            assert!((y3 - 18.0).abs() < 1e-9);
        } else {
            panic!("expected CurveTo");
        }
    }

    #[test]
    fn test_text_object_set_fill_and_stroke_color() {
        let mut t = TextObject::default();
        t.set_fill_color(Color::rgb(0.0, 1.0, 0.0));
        assert_eq!(t.fill_color().unwrap().components, vec![0.0, 1.0, 0.0]);
        t.set_stroke_color(Color::gray(0.25));
        assert_eq!(t.stroke_color().unwrap().components, vec![0.25]);
    }

    #[test]
    fn test_text_object_set_font_size_and_text() {
        let mut t = TextObject::default();
        t.set_font_size(24.0);
        assert_eq!(t.font_size(), 24.0);
        t.set_text("new text");
        assert_eq!(t.text(), "new text");
    }

    #[test]
    fn test_text_object_set_rendering_mode() {
        let mut t = TextObject::default();
        t.set_rendering_mode(TextRenderingMode::Stroke);
        assert_eq!(t.rendering_mode(), TextRenderingMode::Stroke);
    }

    #[test]
    fn test_text_object_set_text_updates_content() {
        let mut t = TextObject::default();
        assert_eq!(t.text(), "");
        t.set_text("Hello, world!");
        assert_eq!(t.text(), "Hello, world!");
    }

    #[test]
    fn test_text_object_set_text_accepts_string_and_str() {
        let mut t = TextObject::default();
        // &str via Into<String>
        t.set_text("foo");
        assert_eq!(t.text(), "foo");
        // String via Into<String>
        t.set_text(String::from("bar"));
        assert_eq!(t.text(), "bar");
    }

    #[test]
    fn test_page_object_delegated_fill_color() {
        let mut po = PageObject::Path(PathObject::default());
        po.set_fill_color(Color::rgb(1.0, 0.5, 0.0));
        assert_eq!(po.fill_color().unwrap().components, vec![1.0, 0.5, 0.0]);

        let mut to = PageObject::Text(TextObject::default());
        to.set_fill_color(Color::gray(0.8));
        assert_eq!(to.fill_color().unwrap().components, vec![0.8]);
    }

    #[test]
    fn test_page_object_delegated_bounds() {
        let po = PageObject::Path(PathObject {
            segments: vec![PathSegment::Rect(0.0, 0.0, 50.0, 30.0)],
            ..Default::default()
        });
        let b = po.bounds().unwrap();
        assert_eq!(b.right, 50.0);
        assert_eq!(b.top, 30.0);

        // Text objects return None for bounds
        let to = PageObject::Text(TextObject::default());
        assert!(to.bounds().is_none());

        // Image object: unit square scaled to 100x200 at (50, 60)
        let img_matrix = Matrix::new(100.0, 0.0, 0.0, 200.0, 50.0, 60.0);
        let img = ImageObject {
            image_data: vec![],
            width: 1,
            height: 1,
            bits_per_component: 8,
            color_space: Name::from_bytes(b"DeviceRGB".to_vec()),
            matrix: img_matrix,
            filter: None,
            xobject_id: None,
            blend_mode: None,
            active: true,
            marks: vec![],
            clip_path: None,
        };
        let ib = PageObject::Image(img).bounds().unwrap();
        assert!((ib.left - 50.0).abs() < 1e-9);
        assert!((ib.bottom - 60.0).abs() < 1e-9);
        assert!((ib.right - 150.0).abs() < 1e-9);
        assert!((ib.top - 260.0).abs() < 1e-9);

        // Form object: unit square rotated 90° at origin
        let form_matrix = Matrix::new(0.0, 1.0, -1.0, 0.0, 5.0, 10.0);
        let form = FormObject {
            xobject_id: rpdfium_parser::object::ObjectId::new(1, 0),
            matrix: form_matrix,
            blend_mode: None,
            active: true,
            marks: vec![],
            clip_path: None,
        };
        let fb = PageObject::Form(form).bounds().unwrap();
        // corners after 90° rotation + translate:
        // (0,0)→(5,10), (1,0)→(5,11), (0,1)→(4,10), (1,1)→(4,11)
        assert!((fb.left - 4.0).abs() < 1e-9);
        assert!((fb.bottom - 10.0).abs() < 1e-9);
        assert!((fb.right - 5.0).abs() < 1e-9);
        assert!((fb.top - 11.0).abs() < 1e-9);
    }

    // ------------------------------------------------------------------
    // ImageObject read API
    // ------------------------------------------------------------------

    #[test]
    fn test_image_object_metadata_round_trip() {
        let bmp = Bitmap::new(4, 3, BitmapFormat::Rgba32);
        let obj = ImageObject::from_bitmap(&bmp, Matrix::identity());
        let meta = obj.metadata();
        assert_eq!(meta.width, 4);
        assert_eq!(meta.height, 3);
        // Identity matrix: scale=1 user unit per image unit; 4px at 72dpi/user-unit = 288 dpi
        assert_eq!(meta.horizontal_dpi, 4.0 * 72.0);
        assert_eq!(meta.vertical_dpi, 3.0 * 72.0);
        assert_eq!(meta.bits_per_component, 8);
        assert_eq!(meta.color_space, Name::from_bytes(b"DeviceRGB".to_vec()));
        assert_eq!(meta.filter, Some(Name::from_bytes(b"FlateDecode".to_vec())));
        assert_eq!(meta.marked_content_id, -1);
    }

    #[test]
    fn test_image_object_metadata_dpi_from_matrix() {
        // 100×200 image rendered into a 2.0 × 4.0 user-unit area (scale matrix).
        // 2 user units wide, 4 user units tall.
        // horizontal_dpi = 100 * 72 / 2.0 = 3600
        // vertical_dpi   = 200 * 72 / 4.0 = 3600
        let bmp = Bitmap::new(100, 200, BitmapFormat::Rgba32);
        let mat = Matrix {
            a: 2.0,
            b: 0.0,
            c: 0.0,
            d: 4.0,
            e: 0.0,
            f: 0.0,
        };
        let obj = ImageObject::from_bitmap(&bmp, mat);
        let meta = obj.metadata();
        assert!((meta.horizontal_dpi - 3600.0).abs() < 0.1);
        assert!((meta.vertical_dpi - 3600.0).abs() < 0.1);
    }

    #[test]
    fn test_image_object_metadata_dpi_degenerate_matrix() {
        // Zero-scale matrix should produce 0.0 DPI (no division by zero).
        let bmp = Bitmap::new(10, 10, BitmapFormat::Rgba32);
        let mat = Matrix {
            a: 0.0,
            b: 0.0,
            c: 0.0,
            d: 0.0,
            e: 0.0,
            f: 0.0,
        };
        let obj = ImageObject::from_bitmap(&bmp, mat);
        let meta = obj.metadata();
        assert_eq!(meta.horizontal_dpi, 0.0);
        assert_eq!(meta.vertical_dpi, 0.0);
    }

    #[test]
    fn test_image_object_raw_data_is_compressed() {
        let bmp = Bitmap::new(2, 2, BitmapFormat::Rgba32);
        let obj = ImageObject::from_bitmap(&bmp, Matrix::identity());
        // raw_data returns the FlateDecode-compressed bytes; can't be equal to decoded
        let raw = obj.raw_data();
        assert!(!raw.is_empty());
    }

    #[test]
    fn test_image_object_decoded_data_matches_rgb_pixels() {
        // 1x1 opaque red pixel
        let mut bmp = Bitmap::new(1, 1, BitmapFormat::Rgba32);
        bmp.data[0] = 200; // R
        bmp.data[1] = 100; // G
        bmp.data[2] = 50; // B
        bmp.data[3] = 255; // A
        let obj = ImageObject::from_bitmap(&bmp, Matrix::identity());
        let decoded = obj.decoded_data().unwrap();
        // DeviceRGB packed → 3 bytes per pixel
        assert_eq!(decoded, vec![200, 100, 50]);
    }

    #[test]
    fn test_image_object_decoded_data_no_filter_returns_raw() {
        let obj = ImageObject {
            image_data: vec![1, 2, 3, 4, 5],
            width: 5,
            height: 1,
            bits_per_component: 8,
            color_space: Name::from_bytes(b"DeviceGray".to_vec()),
            matrix: Matrix::identity(),
            filter: None,
            xobject_id: None,
            blend_mode: None,
            active: true,
            marks: vec![],
            clip_path: None,
        };
        let decoded = obj.decoded_data().unwrap();
        assert_eq!(decoded, vec![1, 2, 3, 4, 5]);
    }

    #[test]
    fn test_image_object_to_bitmap_rgb() {
        let mut bmp_src = Bitmap::new(2, 1, BitmapFormat::Rgba32);
        // pixel 0: R=10, G=20, B=30, A=255
        bmp_src.data[0] = 10;
        bmp_src.data[1] = 20;
        bmp_src.data[2] = 30;
        bmp_src.data[3] = 255;
        // pixel 1: R=40, G=50, B=60, A=255
        bmp_src.data[4] = 40;
        bmp_src.data[5] = 50;
        bmp_src.data[6] = 60;
        bmp_src.data[7] = 255;
        let obj = ImageObject::from_bitmap(&bmp_src, Matrix::identity());
        let bmp_out = obj.to_bitmap().unwrap();
        assert_eq!(bmp_out.width, 2);
        assert_eq!(bmp_out.height, 1);
        assert_eq!(bmp_out.format, BitmapFormat::Rgba32);
        // pixel 0
        assert_eq!(bmp_out.data[0], 10);
        assert_eq!(bmp_out.data[1], 20);
        assert_eq!(bmp_out.data[2], 30);
        assert_eq!(bmp_out.data[3], 255);
        // pixel 1
        assert_eq!(bmp_out.data[4], 40);
        assert_eq!(bmp_out.data[5], 50);
        assert_eq!(bmp_out.data[6], 60);
        assert_eq!(bmp_out.data[7], 255);
    }

    #[test]
    fn test_image_object_to_bitmap_gray() {
        let obj = ImageObject {
            image_data: vec![128, 64],
            width: 2,
            height: 1,
            bits_per_component: 8,
            color_space: Name::from_bytes(b"DeviceGray".to_vec()),
            matrix: Matrix::identity(),
            filter: None,
            xobject_id: None,
            blend_mode: None,
            active: true,
            marks: vec![],
            clip_path: None,
        };
        let bmp = obj.to_bitmap().unwrap();
        assert_eq!(bmp.format, BitmapFormat::Gray8);
        assert_eq!(bmp.data[0], 128);
        assert_eq!(bmp.data[1], 64);
    }

    // ------------------------------------------------------------------
    // FormObject::from_xobject
    // ------------------------------------------------------------------

    #[test]
    fn test_form_object_from_xobject_stores_id_and_matrix() {
        let id = ObjectId::new(42, 0);
        let m = Matrix::new(2.0, 0.0, 0.0, 3.0, 10.0, 20.0);
        let fo = FormObject::from_xobject(id, m);
        assert_eq!(fo.xobject_id, id);
        assert_eq!(fo.matrix.a, 2.0);
        assert_eq!(fo.matrix.f, 20.0);
        assert!(fo.active);
    }

    // ------------------------------------------------------------------
    // Fix A: Dash pattern API
    // ------------------------------------------------------------------

    #[test]
    fn test_dash_pattern_get_set_roundtrip() {
        let mut p = PathObject::default();
        assert!(p.dash_pattern().is_none());
        assert_eq!(p.dash_phase(), 0.0);
        assert_eq!(p.dash_array(), &[] as &[f32]);

        p.set_dash_array(vec![5.0, 3.0], 1.0);
        assert_eq!(p.dash_array(), &[5.0, 3.0]);
        assert_eq!(p.dash_phase(), 1.0);

        // Update phase only
        p.set_dash_phase(2.5);
        assert_eq!(p.dash_phase(), 2.5);

        // Clear with empty array
        p.set_dash_array(vec![], 0.0);
        assert!(p.dash_pattern().is_none());
    }

    #[test]
    fn test_dash_pattern_set_and_clear() {
        let mut p = PathObject::default();
        p.set_dash_pattern(Some(DashPattern {
            array: vec![10.0, 5.0],
            phase: 3.0,
        }));
        assert_eq!(p.dash_pattern().unwrap().array, vec![10.0, 5.0]);
        p.set_dash_pattern(None);
        assert!(p.dash_pattern().is_none());
    }

    // ------------------------------------------------------------------
    // Fix B: Transform on Text / Image / Form
    // ------------------------------------------------------------------

    #[test]
    fn test_text_object_transform_translates_matrix() {
        let mut t = TextObject::default();
        // Start at identity, translate by (10, 20)
        let m = Matrix::new(1.0, 0.0, 0.0, 1.0, 10.0, 20.0);
        t.transform(&m);
        assert!((t.matrix.e - 10.0).abs() < 1e-9);
        assert!((t.matrix.f - 20.0).abs() < 1e-9);
    }

    #[test]
    fn test_image_object_transform_scales_matrix() {
        let bmp = Bitmap::new(2, 2, BitmapFormat::Rgba32);
        let mut img = ImageObject::from_bitmap(&bmp, Matrix::identity());
        let scale = Matrix::new(2.0, 0.0, 0.0, 3.0, 0.0, 0.0);
        img.transform(&scale);
        assert!((img.matrix.a - 2.0).abs() < 1e-9);
        assert!((img.matrix.d - 3.0).abs() < 1e-9);
    }

    #[test]
    fn test_form_object_transform_updates_matrix() {
        let id = ObjectId::new(1, 0);
        let mut fo = FormObject::from_xobject(id, Matrix::identity());
        let m = Matrix::new(1.0, 0.0, 0.0, 1.0, 5.0, 10.0);
        fo.transform(&m);
        assert!((fo.matrix.e - 5.0).abs() < 1e-9);
        assert!((fo.matrix.f - 10.0).abs() < 1e-9);
    }

    #[test]
    fn test_page_object_transform_dispatches_to_all_types() {
        let m = Matrix::new(1.0, 0.0, 0.0, 1.0, 3.0, 4.0);

        let mut t = PageObject::Text(TextObject::default());
        t.transform(&m);
        if let PageObject::Text(inner) = &t {
            assert!((inner.matrix.e - 3.0).abs() < 1e-9);
        }

        let bmp = Bitmap::new(1, 1, BitmapFormat::Rgba32);
        let mut img = PageObject::Image(ImageObject::from_bitmap(&bmp, Matrix::identity()));
        img.transform(&m);
        if let PageObject::Image(inner) = &img {
            assert!((inner.matrix.e - 3.0).abs() < 1e-9);
        }

        let id = ObjectId::new(1, 0);
        let mut fo = PageObject::Form(FormObject::from_xobject(id, Matrix::identity()));
        fo.transform(&m);
        if let PageObject::Form(inner) = &fo {
            assert!((inner.matrix.e - 3.0).abs() < 1e-9);
        }
    }

    // ------------------------------------------------------------------
    // Fix C: Blend mode API
    // ------------------------------------------------------------------

    #[test]
    fn test_blend_mode_get_set_path() {
        let mut p = PathObject::default();
        assert!(p.blend_mode().is_none());
        p.set_blend_mode(Some(BlendMode::Multiply));
        assert_eq!(p.blend_mode(), Some(BlendMode::Multiply));
        p.set_blend_mode(None);
        assert!(p.blend_mode().is_none());
    }

    #[test]
    fn test_blend_mode_page_object_enum() {
        let mut po = PageObject::Path(PathObject::default());
        assert!(po.blend_mode().is_none());
        po.set_blend_mode(Some(BlendMode::Screen));
        assert_eq!(po.blend_mode(), Some(BlendMode::Screen));

        let mut to = PageObject::Text(TextObject::default());
        to.set_blend_mode(Some(BlendMode::Overlay));
        assert_eq!(to.blend_mode(), Some(BlendMode::Overlay));
    }

    // ------------------------------------------------------------------
    // Item 2: parse_jpeg_dimensions + ImageObject::from_jpeg_bytes
    // ------------------------------------------------------------------

    /// Build a minimal well-formed JPEG byte sequence with a SOF0 segment
    /// declaring the given `width` × `height` dimensions.
    fn make_minimal_jpeg(width: u16, height: u16) -> Vec<u8> {
        let mut data: Vec<u8> = Vec::new();
        // SOI
        data.extend_from_slice(&[0xFF, 0xD8]);
        // SOF0 marker
        data.extend_from_slice(&[0xFF, 0xC0]);
        // Segment length: 2 (len) + 1 (precision) + 2 (height) + 2 (width) + 1 (components) = 8
        let seg_len: u16 = 8;
        data.extend_from_slice(&seg_len.to_be_bytes());
        // Precision (8-bit)
        data.push(8);
        // Height
        data.extend_from_slice(&height.to_be_bytes());
        // Width
        data.extend_from_slice(&width.to_be_bytes());
        // Number of components (3 = RGB)
        data.push(3);
        // EOI
        data.extend_from_slice(&[0xFF, 0xD9]);
        data
    }

    #[test]
    fn test_parse_jpeg_dimensions_baseline() {
        let jpeg = make_minimal_jpeg(320, 240);
        let result = parse_jpeg_dimensions(&jpeg);
        assert_eq!(result, Some((320, 240)));
    }

    #[test]
    fn test_parse_jpeg_dimensions_progressive() {
        // Build a JPEG with SOF2 (progressive) instead of SOF0
        let mut data: Vec<u8> = Vec::new();
        data.extend_from_slice(&[0xFF, 0xD8]);
        data.extend_from_slice(&[0xFF, 0xC2]); // SOF2
        let seg_len: u16 = 8;
        data.extend_from_slice(&seg_len.to_be_bytes());
        data.push(8); // precision
        data.extend_from_slice(&100u16.to_be_bytes()); // height
        data.extend_from_slice(&200u16.to_be_bytes()); // width
        data.push(3);
        data.extend_from_slice(&[0xFF, 0xD9]);
        assert_eq!(parse_jpeg_dimensions(&data), Some((200, 100)));
    }

    #[test]
    fn test_parse_jpeg_dimensions_sof_after_app0() {
        // Realistic JPEG: SOI + APP0 + SOF0
        let mut data: Vec<u8> = Vec::new();
        // SOI
        data.extend_from_slice(&[0xFF, 0xD8]);
        // APP0 marker with 16 bytes of dummy content
        data.extend_from_slice(&[0xFF, 0xE0]);
        let app0_len: u16 = 18; // 2 (len) + 16 bytes payload
        data.extend_from_slice(&app0_len.to_be_bytes());
        data.extend_from_slice(&[0u8; 16]);
        // SOF0
        data.extend_from_slice(&[0xFF, 0xC0]);
        let seg_len: u16 = 8;
        data.extend_from_slice(&seg_len.to_be_bytes());
        data.push(8); // precision
        data.extend_from_slice(&480u16.to_be_bytes()); // height
        data.extend_from_slice(&640u16.to_be_bytes()); // width
        data.push(3);
        // EOI
        data.extend_from_slice(&[0xFF, 0xD9]);
        assert_eq!(parse_jpeg_dimensions(&data), Some((640, 480)));
    }

    #[test]
    fn test_parse_jpeg_dimensions_invalid_no_soi() {
        let data = vec![0x00, 0x01, 0x02];
        assert_eq!(parse_jpeg_dimensions(&data), None);
    }

    #[test]
    fn test_parse_jpeg_dimensions_empty() {
        assert_eq!(parse_jpeg_dimensions(&[]), None);
    }

    #[test]
    fn test_parse_jpeg_dimensions_truncated() {
        // SOI only, no further markers
        let data = vec![0xFF, 0xD8];
        assert_eq!(parse_jpeg_dimensions(&data), None);
    }

    #[test]
    fn test_from_jpeg_bytes_creates_image_object() {
        let jpeg = make_minimal_jpeg(100, 75);
        let obj =
            ImageObject::from_jpeg_bytes(jpeg, Matrix::identity()).expect("should parse JPEG");
        assert_eq!(obj.width, 100);
        assert_eq!(obj.height, 75);
        assert_eq!(
            obj.filter.as_ref().map(|n| n.as_bytes()),
            Some(b"DCTDecode".as_ref())
        );
        assert_eq!(obj.bits_per_component, 8);
        assert!(obj.active);
        assert!(obj.xobject_id.is_none());
    }

    #[test]
    fn test_from_jpeg_bytes_metadata_dimensions() {
        let jpeg = make_minimal_jpeg(800, 600);
        let obj = ImageObject::from_jpeg_bytes(jpeg, Matrix::new(800.0, 0.0, 0.0, 600.0, 0.0, 0.0))
            .expect("should parse JPEG");
        let meta = obj.metadata();
        assert_eq!(meta.width, 800);
        assert_eq!(meta.height, 600);
        assert_eq!(
            meta.filter.as_ref().map(|n| n.as_bytes()),
            Some(b"DCTDecode".as_ref())
        );
        // DPI should be ~72 when width/height exactly match matrix scale.
        assert!(
            (meta.horizontal_dpi - 72.0).abs() < 0.1,
            "horizontal_dpi={}",
            meta.horizontal_dpi
        );
        assert!(
            (meta.vertical_dpi - 72.0).abs() < 0.1,
            "vertical_dpi={}",
            meta.vertical_dpi
        );
    }

    #[test]
    fn test_from_jpeg_bytes_invalid_data_returns_error() {
        let bad_data = vec![0xDE, 0xAD, 0xBE, 0xEF];
        let result = ImageObject::from_jpeg_bytes(bad_data, Matrix::identity());
        assert!(result.is_err());
    }

    #[test]
    fn test_from_jpeg_bytes_raw_data_preserved() {
        // raw_data() should return the original JPEG bytes unchanged.
        let jpeg = make_minimal_jpeg(50, 50);
        let jpeg_clone = jpeg.clone();
        let obj = ImageObject::from_jpeg_bytes(jpeg, Matrix::identity()).unwrap();
        assert_eq!(obj.raw_data(), jpeg_clone.as_slice());
    }

    // ------------------------------------------------------------------
    // Content Marks API  (FPDFPageObj*Mark* functions — tagged PDF)
    // ------------------------------------------------------------------

    #[test]
    fn test_content_mark_add_and_count() {
        let mut p = PathObject::default();
        assert_eq!(p.mark_count(), 0);
        p.add_mark("Span");
        assert_eq!(p.mark_count(), 1);
        p.add_mark("P");
        assert_eq!(p.mark_count(), 2);
    }

    #[test]
    fn test_content_mark_get_by_index() {
        let mut p = PathObject::default();
        p.add_mark("Figure");
        p.add_mark("Artifact");

        let m0 = p.mark(0).unwrap();
        assert_eq!(m0.name, "Figure");

        let m1 = p.page_obj_get_mark(1).unwrap();
        assert_eq!(m1.name, "Artifact");

        // out-of-range returns None
        assert!(p.mark(2).is_none());
        assert!(p.page_obj_get_mark(99).is_none());
    }

    #[test]
    fn test_content_mark_int_param_roundtrip() {
        let mut mark = ContentMark::new("Span");
        assert_eq!(mark.param_count(), 0);
        assert_eq!(mark.page_obj_mark_count_params(), 0);

        mark.set_int_param("MCID", 7);
        assert_eq!(mark.param_count(), 1);
        assert_eq!(mark.int_param("MCID"), Some(7));
        assert_eq!(mark.page_obj_mark_get_param_int_value("MCID"), Some(7)); // alias

        // Replace existing key — still only 1 entry
        mark.set_int_param("MCID", 42);
        assert_eq!(mark.param_count(), 1);
        assert_eq!(mark.int_param("MCID"), Some(42));

        // Wrong type returns None
        assert!(mark.string_param("MCID").is_none());
        assert!(mark.blob_param("MCID").is_none());
    }

    #[test]
    fn test_content_mark_string_param_roundtrip() {
        let mut mark = ContentMark::new("Link");
        mark.set_string_param("ActualText", "Hello world");
        assert_eq!(mark.string_param("ActualText"), Some("Hello world"));
        assert_eq!(
            mark.page_obj_mark_get_param_string_value("ActualText"),
            Some("Hello world")
        ); // alias
        assert_eq!(mark.param_key(0), Some("ActualText"));
        assert_eq!(mark.page_obj_mark_get_param_key(0), Some("ActualText"));

        // Replace
        mark.set_string_param("ActualText", "Goodbye");
        assert_eq!(mark.string_param("ActualText"), Some("Goodbye"));
        assert_eq!(mark.param_count(), 1);
    }

    #[test]
    fn test_content_mark_blob_param_roundtrip() {
        let mut mark = ContentMark::new("CustomTag");
        mark.set_blob_param("Raw", vec![0xDE, 0xAD, 0xBE, 0xEF]);
        assert_eq!(mark.blob_param("Raw"), Some(&[0xDE, 0xAD, 0xBE, 0xEF][..]));
        assert_eq!(
            mark.page_obj_mark_get_param_blob_value("Raw"),
            Some(&[0xDE, 0xAD, 0xBE, 0xEF][..])
        ); // alias

        // Replace blob
        mark.set_blob_param("Raw", vec![0x01, 0x02]);
        assert_eq!(mark.blob_param("Raw"), Some(&[0x01, 0x02][..]));
        assert_eq!(mark.param_count(), 1);
    }

    #[test]
    fn test_content_mark_marked_content_id() {
        let mut p = PathObject::default();

        // No marks → None
        assert!(p.marked_content_id().is_none());

        // Mark without MCID → None
        p.add_mark("NoId");
        assert!(p.marked_content_id().is_none());

        // Mark with MCID
        p.add_mark("Span").set_int_param("MCID", 5);
        assert_eq!(p.marked_content_id(), Some(5));

        // ContentMark itself
        let mut m = ContentMark::new("P");
        m.set_int_param("MCID", 99);
        assert_eq!(m.marked_content_id(), Some(99));
    }

    #[test]
    fn test_content_mark_remove_mark_valid_and_invalid_index() {
        let mut p = PathObject::default();
        p.add_mark("A");
        p.add_mark("B");

        // Invalid index returns false
        assert!(!p.remove_mark(5));
        assert_eq!(p.mark_count(), 2);

        // Valid index returns true and decrements count
        assert!(p.remove_mark(0));
        assert_eq!(p.mark_count(), 1);
        assert_eq!(p.mark(0).unwrap().name, "B");
    }

    #[test]
    fn test_content_mark_remove_param() {
        let mut mark = ContentMark::new("Tag");
        mark.set_int_param("A", 1);
        mark.set_string_param("B", "hello");
        assert_eq!(mark.param_count(), 2);

        // Remove existing key returns true
        assert!(mark.remove_param("A"));
        assert_eq!(mark.param_count(), 1);
        assert!(mark.int_param("A").is_none());

        // Remove non-existent key returns false
        assert!(!mark.remove_param("NotHere"));
        assert_eq!(mark.param_count(), 1);
    }

    #[test]
    fn test_content_mark_page_object_enum_dispatch() {
        // Test that PageObject enum properly dispatches all content-mark methods.
        let mut po = PageObject::Text(TextObject::default());

        assert_eq!(po.mark_count(), 0);
        po.add_mark("Span").set_int_param("MCID", 3);
        assert_eq!(po.mark_count(), 1);
        assert_eq!(po.mark(0).unwrap().name, "Span");
        assert_eq!(po.marked_content_id(), Some(3));

        assert!(po.remove_mark(0));
        assert_eq!(po.mark_count(), 0);
        assert!(po.marked_content_id().is_none());
    }

    // -----------------------------------------------------------------------
    // ClipPath tests
    // -----------------------------------------------------------------------

    #[test]
    fn test_clip_path_from_rect() {
        let clip = ClipPath::from_rect(10.0, 20.0, 110.0, 120.0);
        assert_eq!(clip.path_count(), 1);
        assert_eq!(clip.clip_path_count_paths(), 1);
        assert_eq!(clip.segment_count(0), 1);
        assert_eq!(clip.clip_path_count_path_segments(0), 1);

        // Check that the rect segment has correct dimensions
        match clip.segment(0, 0) {
            Some(PathSegment::Rect(x, y, w, h)) => {
                assert!((x - 10.0).abs() < 1e-9);
                assert!((y - 20.0).abs() < 1e-9);
                assert!((w - 100.0).abs() < 1e-9);
                assert!((h - 100.0).abs() < 1e-9);
            }
            other => panic!("expected Rect segment, got {:?}", other),
        }
    }

    #[test]
    fn test_clip_path_from_rect_alias() {
        let clip = ClipPath::create_clip_path(0.0, 0.0, 100.0, 200.0);
        assert_eq!(clip.path_count(), 1);
        match clip.segment(0, 0) {
            Some(PathSegment::Rect(x, y, w, h)) => {
                assert!((x - 0.0).abs() < 1e-9);
                assert!((y - 0.0).abs() < 1e-9);
                assert!((w - 100.0).abs() < 1e-9);
                assert!((h - 200.0).abs() < 1e-9);
            }
            other => panic!("expected Rect, got {:?}", other),
        }
    }

    #[test]
    fn test_clip_path_multi_sub_paths() {
        let clip = ClipPath::new(vec![
            vec![
                PathSegment::MoveTo(0.0, 0.0),
                PathSegment::LineTo(100.0, 0.0),
                PathSegment::LineTo(100.0, 100.0),
                PathSegment::Close,
            ],
            vec![
                PathSegment::MoveTo(200.0, 200.0),
                PathSegment::LineTo(300.0, 200.0),
                PathSegment::Close,
            ],
        ]);

        assert_eq!(clip.path_count(), 2);
        assert_eq!(clip.segment_count(0), 4);
        assert_eq!(clip.segment_count(1), 3);
        assert_eq!(clip.segment_count(999), 0); // out of range

        assert!(clip.segment(0, 0).is_some());
        assert!(clip.segment(0, 3).is_some());
        assert!(clip.segment(0, 4).is_none());
        assert!(clip.segment(1, 2).is_some());
        assert!(clip.segment(999, 0).is_none());

        // Aliases
        assert!(clip.clip_path_get_path_segment(0, 0).is_some());
    }

    #[test]
    fn test_clip_path_transform() {
        let mut clip = ClipPath::from_rect(0.0, 0.0, 100.0, 100.0);
        let matrix = Matrix::new(2.0, 0.0, 0.0, 2.0, 10.0, 20.0);
        clip.transform(&matrix);

        match clip.segment(0, 0) {
            Some(PathSegment::Rect(x, y, w, h)) => {
                assert!((x - 10.0).abs() < 1e-9, "x={x}");
                assert!((y - 20.0).abs() < 1e-9, "y={y}");
                assert!((w - 200.0).abs() < 1e-9, "w={w}");
                assert!((h - 200.0).abs() < 1e-9, "h={h}");
            }
            other => panic!("expected Rect, got {:?}", other),
        }
    }

    #[test]
    fn test_page_object_clip_path_dispatch() {
        let mut po = PageObject::Path(PathObject::default());
        assert!(po.clip_path().is_none());
        assert!(po.page_obj_get_clip_path().is_none());

        let clip = ClipPath::from_rect(0.0, 0.0, 100.0, 100.0);
        po.set_clip_path(Some(clip));
        assert!(po.clip_path().is_some());
        assert_eq!(po.clip_path().unwrap().path_count(), 1);

        // Transform the clip path
        let matrix = Matrix::new(1.0, 0.0, 0.0, 1.0, 50.0, 50.0);
        po.transform_clip_path(&matrix);
        // Should still exist
        assert!(po.clip_path().is_some());

        // Clear
        po.set_clip_path(None);
        assert!(po.clip_path().is_none());

        // No-op transform on no clip
        po.transform_clip_path(&Matrix::identity()); // should not panic
    }

    #[test]
    fn test_page_object_clip_path_all_types() {
        // Verify clip_path field works for all four page object types
        for mut po in [
            PageObject::Path(PathObject::default()),
            PageObject::Text(TextObject::default()),
            PageObject::Image(ImageObject {
                image_data: vec![],
                width: 1,
                height: 1,
                bits_per_component: 8,
                color_space: Name::from_bytes(b"DeviceRGB".to_vec()),
                matrix: Matrix::identity(),
                filter: None,
                xobject_id: None,
                blend_mode: None,
                active: true,
                marks: Vec::new(),
                clip_path: None,
            }),
            PageObject::Form(FormObject::from_xobject(make_id(1), Matrix::identity())),
        ] {
            assert!(po.clip_path().is_none());
            po.set_clip_path(Some(ClipPath::from_rect(0.0, 0.0, 50.0, 50.0)));
            assert!(po.clip_path().is_some());
        }
    }

    // ------------------------------------------------------------------
    // Gap 3: has_transparency() (upstream-aligned primary)
    // ------------------------------------------------------------------

    #[test]
    fn test_path_object_has_transparency_false_when_no_blend_mode() {
        let p = PathObject::default();
        assert!(!p.has_transparency());
    }

    #[test]
    fn test_path_object_has_transparency_true_for_non_normal_blend_mode() {
        let mut p = PathObject::default();
        p.set_blend_mode(Some(BlendMode::Multiply));
        assert!(p.has_transparency());

        // Normal blend mode → not transparent
        p.set_blend_mode(Some(BlendMode::Normal));
        assert!(!p.has_transparency());
    }

    #[test]
    fn test_page_object_has_transparency_dispatches_all_types() {
        // Path: non-Normal blend mode → transparent
        let mut path_po = PageObject::Path(PathObject::default());
        assert!(!path_po.has_transparency());
        path_po.set_blend_mode(Some(BlendMode::Screen));
        assert!(path_po.has_transparency());

        // Text: same behaviour
        let mut text_po = PageObject::Text(TextObject::default());
        assert!(!text_po.has_transparency());
        text_po.set_blend_mode(Some(BlendMode::Overlay));
        assert!(text_po.has_transparency());

        // Image: transparent when blend mode set
        let img_po = PageObject::Image(ImageObject {
            image_data: vec![],
            width: 1,
            height: 1,
            bits_per_component: 8,
            color_space: Name::from_bytes(b"DeviceRGB".to_vec()),
            matrix: Matrix::identity(),
            filter: None,
            xobject_id: None,
            blend_mode: Some(BlendMode::Darken),
            active: true,
            marks: Vec::new(),
            clip_path: None,
        });
        assert!(img_po.has_transparency());

        // Form: transparent when blend mode set
        let mut form_po =
            PageObject::Form(FormObject::from_xobject(make_id(2), Matrix::identity()));
        assert!(!form_po.has_transparency());
        form_po.set_blend_mode(Some(BlendMode::Luminosity));
        assert!(form_po.has_transparency());
    }

    // ------------------------------------------------------------------
    // Gap 2: matrix() / set_matrix() on page objects
    // ------------------------------------------------------------------

    #[test]
    fn test_image_object_matrix_get_set() {
        let scale = Matrix::new(100.0, 0.0, 0.0, 150.0, 50.0, 75.0);
        let mut img = ImageObject {
            image_data: vec![],
            width: 10,
            height: 10,
            bits_per_component: 8,
            color_space: Name::from_bytes(b"DeviceRGB".to_vec()),
            matrix: Matrix::identity(),
            filter: None,
            xobject_id: None,
            blend_mode: None,
            active: true,
            marks: Vec::new(),
            clip_path: None,
        };
        // Default matrix is identity
        assert_eq!(*img.matrix(), Matrix::identity());
        // Set a new matrix
        img.set_matrix(scale);
        assert_eq!(img.matrix().a, 100.0);
        assert_eq!(img.matrix().d, 150.0);
        assert_eq!(img.matrix().e, 50.0);
        assert_eq!(img.matrix().f, 75.0);
    }

    #[test]
    fn test_form_object_matrix_get_set() {
        let m = Matrix::new(2.0, 0.0, 0.0, 3.0, 10.0, 20.0);
        let mut f = FormObject::from_xobject(make_id(5), Matrix::identity());
        assert_eq!(*f.matrix(), Matrix::identity());
        f.set_matrix(m);
        assert_eq!(f.matrix().a, 2.0);
        assert_eq!(f.matrix().d, 3.0);
    }

    #[test]
    fn test_page_object_matrix_dispatch() {
        let m = Matrix::new(4.0, 0.0, 0.0, 4.0, 0.0, 0.0);

        // Image: matrix is stored and returned
        let mut img_po = PageObject::Image(ImageObject {
            image_data: vec![],
            width: 1,
            height: 1,
            bits_per_component: 8,
            color_space: Name::from_bytes(b"DeviceRGB".to_vec()),
            matrix: Matrix::identity(),
            filter: None,
            xobject_id: None,
            blend_mode: None,
            active: true,
            marks: Vec::new(),
            clip_path: None,
        });
        assert_eq!(img_po.matrix(), Matrix::identity());
        img_po.set_matrix(m);
        assert_eq!(img_po.matrix().a, 4.0);

        // Path: always returns identity; set_matrix is a no-op
        let mut path_po = PageObject::Path(PathObject::default());
        assert_eq!(path_po.matrix(), Matrix::identity());
        path_po.set_matrix(m); // no-op
        assert_eq!(path_po.matrix(), Matrix::identity());

        // Text: always returns identity
        let text_po = PageObject::Text(TextObject::default());
        assert_eq!(text_po.matrix(), Matrix::identity());
    }

    // ------------------------------------------------------------------
    // Task 2: object_type() — FPDFPageObj_GetType
    // ------------------------------------------------------------------

    #[test]
    fn test_path_object_type_is_2() {
        let p = PathObject::default();
        assert_eq!(p.object_type(), 2);
        assert_eq!(p.page_obj_get_type(), 2);
        let po = PageObject::Path(PathObject::default());
        assert_eq!(po.object_type(), 2);
        assert_eq!(po.page_obj_get_type(), 2);
    }

    #[test]
    fn test_text_object_type_is_1() {
        let t = TextObject::default();
        assert_eq!(t.object_type(), 1);
        assert_eq!(t.page_obj_get_type(), 1);
        let po = PageObject::Text(TextObject::default());
        assert_eq!(po.object_type(), 1);
        assert_eq!(po.page_obj_get_type(), 1);
    }

    #[test]
    fn test_image_object_type_is_3() {
        let img = ImageObject {
            image_data: vec![],
            width: 1,
            height: 1,
            bits_per_component: 8,
            color_space: Name::from_bytes(b"DeviceRGB".to_vec()),
            matrix: Matrix::identity(),
            filter: None,
            xobject_id: None,
            blend_mode: None,
            active: true,
            marks: Vec::new(),
            clip_path: None,
        };
        assert_eq!(img.object_type(), 3);
        assert_eq!(img.page_obj_get_type(), 3);
        let img2 = ImageObject {
            image_data: vec![],
            width: 1,
            height: 1,
            bits_per_component: 8,
            color_space: Name::from_bytes(b"DeviceRGB".to_vec()),
            matrix: Matrix::identity(),
            filter: None,
            xobject_id: None,
            blend_mode: None,
            active: true,
            marks: Vec::new(),
            clip_path: None,
        };
        let po = PageObject::Image(img2);
        assert_eq!(po.object_type(), 3);
        assert_eq!(po.page_obj_get_type(), 3);
    }

    #[test]
    fn test_form_object_type_is_5() {
        let fo = FormObject::from_xobject(ObjectId::new(1, 0), Matrix::identity());
        assert_eq!(fo.object_type(), 5);
        assert_eq!(fo.page_obj_get_type(), 5);
        let fo2 = FormObject::from_xobject(ObjectId::new(2, 0), Matrix::identity());
        let po = PageObject::Form(fo2);
        assert_eq!(po.object_type(), 5);
        assert_eq!(po.page_obj_get_type(), 5);
    }

    // ------------------------------------------------------------------
    // Task 3: filter_count() / filter() — FPDFImageObj_GetImageFilterCount /
    //         FPDFImageObj_GetImageFilter
    // ------------------------------------------------------------------

    #[test]
    fn test_image_filter_count_no_filter() {
        let img = ImageObject {
            image_data: vec![],
            width: 1,
            height: 1,
            bits_per_component: 8,
            color_space: Name::from_bytes(b"DeviceGray".to_vec()),
            matrix: Matrix::identity(),
            filter: None,
            xobject_id: None,
            blend_mode: None,
            active: true,
            marks: Vec::new(),
            clip_path: None,
        };
        assert_eq!(img.filter_count(), 0);
        assert_eq!(img.image_obj_get_image_filter_count(), 0);
        assert!(img.filter(0).is_none());
        assert!(img.image_obj_get_image_filter(0).is_none());
    }

    #[test]
    fn test_image_filter_count_with_filter() {
        let img = ImageObject {
            image_data: vec![],
            width: 1,
            height: 1,
            bits_per_component: 8,
            color_space: Name::from_bytes(b"DeviceRGB".to_vec()),
            matrix: Matrix::identity(),
            filter: Some(Name::from_bytes(b"FlateDecode".to_vec())),
            xobject_id: None,
            blend_mode: None,
            active: true,
            marks: Vec::new(),
            clip_path: None,
        };
        assert_eq!(img.filter_count(), 1);
        assert_eq!(img.image_obj_get_image_filter_count(), 1);
        assert_eq!(img.filter(0), Some("FlateDecode"));
        assert_eq!(img.image_obj_get_image_filter(0), Some("FlateDecode"));
    }

    #[test]
    fn test_image_filter_index_out_of_range_returns_none() {
        let img = ImageObject {
            image_data: vec![],
            width: 1,
            height: 1,
            bits_per_component: 8,
            color_space: Name::from_bytes(b"DeviceRGB".to_vec()),
            matrix: Matrix::identity(),
            filter: Some(Name::from_bytes(b"DCTDecode".to_vec())),
            xobject_id: None,
            blend_mode: None,
            active: true,
            marks: Vec::new(),
            clip_path: None,
        };
        // Index 0 is valid.
        assert_eq!(img.filter(0), Some("DCTDecode"));
        // Index 1 is out of range — only one filter is stored.
        assert!(img.filter(1).is_none());
        assert!(img.image_obj_get_image_filter(1).is_none());
    }

    // -----------------------------------------------------------------------
    // Batch 17: rendered_bitmap / icc_profile_data_decoded stubs
    // -----------------------------------------------------------------------

    #[test]
    fn test_image_obj_rendered_bitmap_returns_not_supported() {
        let img = ImageObject {
            image_data: vec![],
            width: 1,
            height: 1,
            bits_per_component: 8,
            color_space: Name::from_bytes(b"DeviceRGB".to_vec()),
            matrix: Matrix::identity(),
            filter: None,
            xobject_id: None,
            blend_mode: None,
            active: true,
            marks: Vec::new(),
            clip_path: None,
        };
        assert!(img.rendered_bitmap(0, 1.0).is_err());
        assert!(img.image_obj_get_rendered_bitmap(0, 1.0).is_err());
    }

    #[test]
    fn test_image_obj_icc_profile_returns_none() {
        let img = ImageObject {
            image_data: vec![],
            width: 1,
            height: 1,
            bits_per_component: 8,
            color_space: Name::from_bytes(b"DeviceRGB".to_vec()),
            matrix: Matrix::identity(),
            filter: None,
            xobject_id: None,
            blend_mode: None,
            active: true,
            marks: Vec::new(),
            clip_path: None,
        };
        assert!(img.icc_profile_data_decoded().is_none());
        assert!(img.image_obj_get_icc_profile_data_decoded().is_none());
    }

    #[test]
    fn test_text_obj_rendered_bitmap_returns_not_supported() {
        let obj = TextObject::with_standard_font("Helvetica", 12.0);
        assert!(obj.rendered_bitmap(0, 1.0).is_err());
        assert!(obj.text_obj_get_rendered_bitmap(0, 1.0).is_err());
    }

    // ------------------------------------------------------------------
    // Batch 17b: rotated_bounds, set_char_codes, float params, Form stubs
    // ------------------------------------------------------------------

    #[test]
    fn test_text_obj_set_char_codes_ascii() {
        let mut t = TextObject::default();
        t.set_char_codes(&[0x41, 0x42, 0x43]);
        assert_eq!(t.text(), "ABC");
    }

    #[test]
    fn test_text_obj_set_char_codes_alias() {
        let mut t = TextObject::default();
        t.text_set_charcodes(&[0x48, 0x69]); // 'H', 'i'
        assert_eq!(t.text(), "Hi");
    }

    #[test]
    fn test_text_obj_set_char_codes_invalid_replaced_with_replacement_char() {
        let mut t = TextObject::default();
        // 0xD800 is a surrogate, not a valid Unicode scalar
        t.set_char_codes(&[0x41, 0xD800, 0x42]);
        let s = t.text();
        let chars: Vec<char> = s.chars().collect();
        assert_eq!(chars[0], 'A');
        assert_eq!(chars[1], '\u{FFFD}');
        assert_eq!(chars[2], 'B');
    }

    #[allow(deprecated)]
    #[test]
    fn test_text_obj_from_font_registration_has_correct_size() {
        let reg = FontRegistration::new_standard(make_id(10), "Courier-Bold");
        let t = TextObject::from_font_registration(&reg, 12.0);
        assert_eq!(t.font_size(), 12.0);
        assert_eq!(t.font_name(), &Name::from_bytes(b"Courier-Bold".to_vec()));
        assert_eq!(t.font_object_id, Some(make_id(10)));
    }

    #[allow(deprecated)]
    #[test]
    fn test_text_obj_from_font_registration_equals_with_font() {
        let reg = FontRegistration::new_standard(make_id(5), "Helvetica");
        let t1 = TextObject::with_font(&reg, 14.0);
        let t2 = TextObject::from_font_registration(&reg, 14.0);
        assert_eq!(t1.font_name(), t2.font_name());
        assert_eq!(t1.font_size(), t2.font_size());
        assert_eq!(t1.font_object_id, t2.font_object_id);
    }

    #[test]
    fn test_page_obj_mark_float_param_set_and_get() {
        let mut mark = ContentMark::new("Tag");
        mark.set_float_param("Scale", 1.5_f32);
        assert_eq!(mark.float_param("Scale"), Some(1.5_f32));
        assert_eq!(
            mark.page_obj_mark_get_param_float_value("Scale"),
            Some(1.5_f32)
        );
    }

    #[test]
    fn test_page_obj_mark_float_param_replace_existing() {
        let mut mark = ContentMark::new("Tag");
        mark.set_float_param("X", 0.5_f32);
        mark.set_float_param("X", 2.0_f32);
        assert_eq!(mark.float_param("X"), Some(2.0_f32));
        assert_eq!(mark.param_count(), 1);
    }

    #[test]
    fn test_page_obj_mark_float_param_absent_returns_none() {
        let mark = ContentMark::new("Tag");
        assert!(mark.float_param("Missing").is_none());
    }

    #[test]
    fn test_page_obj_mark_float_wrong_type_returns_none() {
        let mut mark = ContentMark::new("Tag");
        mark.set_int_param("Key", 42);
        assert!(mark.float_param("Key").is_none());
        mark.set_float_param("FKey", 1.0);
        assert!(mark.int_param("FKey").is_none());
    }

    #[test]
    fn test_form_obj_object_count_stub() {
        let id = ObjectId::new(1, 0);
        let fo = FormObject::from_xobject(id, Matrix::identity());
        let result = fo.object_count();
        assert!(matches!(
            result,
            Err(crate::error::EditError::NotSupported(_))
        ));
        let result2 = fo.form_obj_count_objects();
        assert!(matches!(
            result2,
            Err(crate::error::EditError::NotSupported(_))
        ));
    }

    #[test]
    fn test_form_obj_object_at_stub() {
        let id = ObjectId::new(1, 0);
        let fo = FormObject::from_xobject(id, Matrix::identity());
        let result = fo.object_at(0);
        assert!(matches!(
            result,
            Err(crate::error::EditError::NotSupported(_))
        ));
        let result2 = fo.form_obj_get_object(0);
        assert!(matches!(
            result2,
            Err(crate::error::EditError::NotSupported(_))
        ));
    }

    #[test]
    fn test_form_obj_remove_object_stub() {
        let id = ObjectId::new(1, 0);
        let mut fo = FormObject::from_xobject(id, Matrix::identity());
        let result = fo.remove_object(0);
        assert!(matches!(
            result,
            Err(crate::error::EditError::NotSupported(_))
        ));
    }

    #[test]
    fn test_text_obj_rotated_bounds_identity_matrix() {
        let mut t = TextObject::default();
        t.matrix = Matrix::new(1.0, 0.0, 0.0, 1.0, 10.0, 20.0);
        let bounds = t.rotated_bounds().unwrap();
        assert!((bounds[0].x - 10.0).abs() < 1e-9);
        assert!((bounds[0].y - 20.0).abs() < 1e-9);
    }

    #[test]
    fn test_image_obj_rotated_bounds_uses_matrix() {
        let bmp = Bitmap::new(1, 1, BitmapFormat::Rgba32);
        let c = std::f64::consts::FRAC_1_SQRT_2;
        let mat = Matrix {
            a: c,
            b: c,
            c: -c,
            d: c,
            e: 0.0,
            f: 0.0,
        };
        let obj = ImageObject::from_bitmap(&bmp, mat);
        let bounds = obj.rotated_bounds().unwrap();
        assert_eq!(bounds.len(), 4);
        assert!((bounds[0].x).abs() < 1e-9);
        assert!((bounds[0].y).abs() < 1e-9);
    }

    #[test]
    fn test_page_object_rotated_bounds_dispatch() {
        let t = PageObject::Text(TextObject::default());
        assert!(t.rotated_bounds().is_some());
        assert!(t.page_obj_get_rotated_bounds().is_some());

        let bmp = Bitmap::new(1, 1, BitmapFormat::Rgba32);
        let img = PageObject::Image(ImageObject::from_bitmap(&bmp, Matrix::identity()));
        assert!(img.rotated_bounds().is_some());

        // Empty path → no bounds → None
        let path_empty = PageObject::Path(PathObject::default());
        assert!(path_empty.rotated_bounds().is_none());

        // Non-empty path → Some
        let path_with_segs = PageObject::Path(PathObject {
            segments: vec![PathSegment::Rect(0.0, 0.0, 10.0, 20.0)],
            ..Default::default()
        });
        assert!(path_with_segs.rotated_bounds().is_some());

        // Form with non-degenerate matrix → Some
        let id = ObjectId::new(1, 0);
        let fo = PageObject::Form(FormObject::from_xobject(
            id,
            Matrix::new(2.0, 0.0, 0.0, 3.0, 5.0, 10.0),
        ));
        assert!(fo.rotated_bounds().is_some());
    }
}