rpdfium_render/

renderer.rs

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

//! Display tree renderer that bridges [`DisplayVisitor`] to [`RenderBackend`].

use std::collections::HashMap;
use std::sync::Arc;

use rpdfium_core::{Matrix, Name};
use rpdfium_font::ResolvedFont;
use rpdfium_font::font_type::PdfFontType;
#[cfg(test)]
use rpdfium_graphics::TextRenderingMode;
use rpdfium_graphics::{
    BlendMode, ClipPath, Color, ColorSpaceFamily, FillRule, ImageRef, PathOp, PathStyle,
};
use rpdfium_page::ShadingDict;
use rpdfium_page::display::{DisplayTree, DisplayVisitor, SoftMask, SoftMaskSubtype, TextRun};
use rpdfium_page::pattern::TilingPattern;
use rpdfium_parser::Operand;

use crate::cfx_glyphcache::{MAX_CACHED_SIZE, RasterGlyph, RasterGlyphKey, RasterizedGlyphCache};
use crate::color_convert::RgbaColor;
use crate::image::ImageDecoder;
use crate::render_defines::ColorScheme;
use crate::renderdevicedriver_iface::RenderBackend;
use crate::stroke::StrokeStyle;

/// Tracks what was pushed so `leave_group` can pop in the right order.
#[derive(Debug, Clone, Copy)]
enum GroupAction {
    Nothing,
    ClipOnly,
    GroupOnly,
    ClipAndGroup,
}

/// Maximum number of entries in the renderer-level glyph outline cache.
const MAX_GLYPH_CACHE_SIZE: usize = 4096;

/// Renders a [`DisplayTree`] by implementing
/// [`DisplayVisitor`] and forwarding drawing commands to a [`RenderBackend`].
pub struct DisplayRenderer<'a, B: RenderBackend> {
    backend: &'a mut B,
    surface: &'a mut B::Surface,
    page_transform: Matrix,
    image_decoder: Option<&'a dyn ImageDecoder>,
    group_stack: Vec<GroupAction>,
    /// Optional fallback fonts to try when the primary font is missing a glyph.
    fallback_fonts: Vec<Arc<ResolvedFont>>,
    /// Accumulated glyph outlines for text clipping (Tr modes 4-7).
    /// Collected during `render_text_run` when the rendering mode includes clipping.
    text_clip_ops: Vec<PathOp>,
    /// Number of text clip regions currently pushed on the clip stack.
    /// These get popped at `leave_group`.
    text_clip_depth: usize,
    /// Per-render glyph outline cache, keyed by (font pointer identity, glyph_id).
    /// Avoids repeated DashMap lookups into ResolvedFont's internal cache.
    glyph_cache: HashMap<(usize, u16), Option<Vec<PathOp>>>,
    /// Rasterized glyph cache for fast text rendering at common sizes.
    raster_cache: RasterizedGlyphCache,
    /// Optional forced color scheme for accessibility (high-contrast) rendering.
    forced_color_scheme: Option<ColorScheme>,
    /// Per-feature anti-aliasing flags from `RenderConfig`.
    text_antialiasing: bool,
    path_antialiasing: bool,
    image_antialiasing: bool,
}

impl<'a, B: RenderBackend> DisplayRenderer<'a, B> {
    /// Create a new renderer targeting the given backend and surface.
    pub fn new(
        backend: &'a mut B,
        surface: &'a mut B::Surface,
        page_transform: Matrix,
        image_decoder: Option<&'a dyn ImageDecoder>,
    ) -> Self {
        Self {
            backend,
            surface,
            page_transform,
            image_decoder,
            group_stack: Vec::new(),
            fallback_fonts: Vec::new(),
            text_clip_ops: Vec::new(),
            text_clip_depth: 0,
            glyph_cache: HashMap::new(),
            raster_cache: RasterizedGlyphCache::new(),
            forced_color_scheme: None,
            text_antialiasing: true,
            path_antialiasing: true,
            image_antialiasing: true,
        }
    }

    /// Set fallback fonts to use when the primary font is missing a glyph.
    pub fn with_fallback_fonts(mut self, fonts: Vec<Arc<ResolvedFont>>) -> Self {
        self.fallback_fonts = fonts;
        self
    }

    /// Set a forced color scheme for accessibility rendering.
    pub fn with_forced_color_scheme(mut self, scheme: ColorScheme) -> Self {
        self.forced_color_scheme = Some(scheme);
        self
    }

    /// Set per-feature anti-aliasing flags.
    pub fn with_per_feature_aa(mut self, text_aa: bool, path_aa: bool, image_aa: bool) -> Self {
        self.text_antialiasing = text_aa;
        self.path_antialiasing = path_aa;
        self.image_antialiasing = image_aa;
        self
    }
}

impl<B: RenderBackend> DisplayRenderer<'_, B> {
    /// Render a single text run by extracting glyph outlines and drawing them.
    fn render_text_run(&mut self, run: &TextRun) {
        // Per-feature AA: use text_antialiasing for text rendering.
        self.backend.set_antialiasing(self.text_antialiasing);

        let resolved_font = match run.resolved_font.as_ref() {
            Some(font) => font,
            None => return, // No font data — skip this run
        };

        // Dispatch to Type 3 rendering if this is a Type 3 font
        if resolved_font.font_type == PdfFontType::Type3 {
            self.render_type3_text_run(run, resolved_font);
            return;
        }

        let units_per_em = resolved_font.units_per_em().unwrap_or(1000) as f32;
        if units_per_em == 0.0 {
            return;
        }

        let rendering_mode = run.rendering_mode;
        // Invisible mode: no fill, no stroke — skip rendering
        if rendering_mode.is_invisible() {
            return;
        }

        let should_fill = rendering_mode.is_fill();
        let should_stroke = rendering_mode.is_stroke();
        let should_clip = rendering_mode.is_clip();

        let fill_rgba = if let Some(ref scheme) = self.forced_color_scheme {
            scheme.text_color
        } else if should_fill {
            run.fill_color
                .as_ref()
                .map(|c| RgbaColor::from_pdf_color(c, 1.0))
                .unwrap_or(RgbaColor::BLACK)
        } else {
            RgbaColor::BLACK
        };

        let stroke_rgba = if let Some(ref scheme) = self.forced_color_scheme {
            scheme.text_color
        } else if should_stroke {
            run.stroke_color
                .as_ref()
                .map(|c| RgbaColor::from_pdf_color(c, 1.0))
                .unwrap_or(RgbaColor::BLACK)
        } else {
            RgbaColor::BLACK
        };

        let font_size = run.font_size;
        let scale = font_size / units_per_em;
        let rise = run.rise;
        let is_vertical = run.is_vertical;

        // Track position through the run.
        // For horizontal text, x_pos advances rightward.
        // For vertical text, y_pos advances downward (negative in PDF y-up space).
        let mut x_pos: f32 = 0.0;
        let mut y_pos: f32 = 0.0;

        // Whether spacing heuristic can apply (P1-b: charposlist.cpp ApplyGlyphSpacingHeuristic).
        // Only for non-embedded TrueType/CIDFontType2 fonts with explicit widths.
        let can_apply_spacing_heuristic = !is_vertical
            && !resolved_font.is_embedded
            && matches!(
                resolved_font.font_type,
                PdfFontType::TrueType | PdfFontType::CIDFontType2
            )
            && !resolved_font.widths.is_empty();

        for (i, &byte) in run.text.iter().enumerate() {
            // Try the primary font first, then fallback fonts.
            let (glyph_id, active_font, active_scale) =
                match resolved_font.glyph_from_char_code(byte as u16) {
                    Some(gid) => (gid, resolved_font.as_ref(), scale),
                    None => {
                        // Try each fallback font in order
                        match self.find_fallback_glyph(byte as u16, font_size) {
                            Some(info) => info,
                            None => {
                                // No fallback found — skip glyph
                                if i < run.positions.len() {
                                    if is_vertical {
                                        y_pos -= run.positions[i];
                                    } else {
                                        x_pos += run.positions[i];
                                    }
                                }
                                continue;
                            }
                        }
                    }
                };

            // Determine if a fallback font is being used (different from the primary).
            let using_fallback = !std::ptr::eq(active_font, resolved_font.as_ref());

            // P1-b: Glyph spacing heuristic for substituted non-embedded TrueType fonts.
            // Matches charposlist.cpp ApplyGlyphSpacingHeuristic() / position adjust logic.
            // Shift the glyph right by half the excess when the PDF width > font width,
            // or apply a horizontal scaling matrix when PDF width < font width.
            let mut x_shift: f32 = 0.0;
            let mut h_scale: f32 = 1.0;
            if can_apply_spacing_heuristic && using_fallback {
                let pdf_glyph_width = resolved_font.char_width(byte as u16) as f32;
                if let Some(outline) = active_font.glyph_outline(glyph_id) {
                    let font_upem = active_font.units_per_em().unwrap_or(1000) as f32;
                    if font_upem > 0.0 {
                        // Normalize font glyph advance to 1/1000 em units
                        let font_glyph_width = outline.advance_width / font_upem * 1000.0;
                        if pdf_glyph_width > font_glyph_width + 1.0 {
                            // Shift right by half the excess (text space coordinates)
                            x_shift = (pdf_glyph_width - font_glyph_width) * font_size / 2000.0;
                        } else if pdf_glyph_width > 0.0
                            && font_glyph_width > 0.0
                            && pdf_glyph_width < font_glyph_width
                        {
                            // Scale glyph horizontally to fit PDF-specified width
                            h_scale = pdf_glyph_width / font_glyph_width;
                        }
                    }
                }
            }

            // Look up glyph outline through the renderer-level cache.
            let font_key = active_font as *const ResolvedFont as usize;
            let cache_key = (font_key, glyph_id);
            if !self.glyph_cache.contains_key(&cache_key) {
                let ops = active_font.glyph_outline(glyph_id).map(|o| o.ops.clone());
                // Evict all entries if cache exceeds limit.
                if self.glyph_cache.len() >= MAX_GLYPH_CACHE_SIZE {
                    self.glyph_cache.clear();
                }
                self.glyph_cache.insert(cache_key, ops);
            }

            let outline_ops = match self.glyph_cache.get(&cache_key) {
                Some(Some(ops)) => ops,
                _ => {
                    if i < run.positions.len() {
                        if is_vertical {
                            y_pos -= run.positions[i];
                        } else {
                            x_pos += run.positions[i];
                        }
                    }
                    continue;
                }
            };

            // Build the glyph transform.
            //
            // Horizontal: text_matrix * translate(x_pos + x_shift, rise) * scale(h_scale * active_scale, active_scale)
            // Vertical:   text_matrix * translate(-vx * fs/1000, y_pos - vy * fs/1000) * scale(active_scale, active_scale)
            //   where (vx, vy) are the vertical origin offsets from /W2 or /DW2.
            let glyph_transform = if is_vertical {
                let (vx, vy) = run.vert_origins.get(i).copied().unwrap_or((0, 880));
                let gx = -(vx as f32) * font_size / 1000.0;
                let gy = y_pos - vy as f32 * font_size / 1000.0;
                let glyph_translate = Matrix::from_translation(gx as f64, gy as f64);
                let glyph_scale =
                    Matrix::new(active_scale as f64, 0.0, 0.0, active_scale as f64, 0.0, 0.0);
                run.matrix
                    .pre_concat(&glyph_translate)
                    .pre_concat(&glyph_scale)
            } else {
                let glyph_translate =
                    Matrix::from_translation((x_pos + x_shift) as f64, rise as f64);
                let glyph_scale = Matrix::new(
                    (active_scale * h_scale) as f64,
                    0.0,
                    0.0,
                    active_scale as f64,
                    0.0,
                    0.0,
                );
                run.matrix
                    .pre_concat(&glyph_translate)
                    .pre_concat(&glyph_scale)
            };

            // Apply page transform
            let final_transform = self.page_transform.pre_concat(&glyph_transform);

            // For common fill-only rendering at small sizes, try raster cache.
            // Only for horizontal text (raster cache doesn't account for vertical origin offsets).
            if !is_vertical
                && should_fill
                && !should_stroke
                && !should_clip
                && font_size < MAX_CACHED_SIZE
            {
                let raster_key = RasterGlyphKey {
                    font_id: font_key,
                    glyph_id,
                    size_q: RasterizedGlyphCache::quantize_size(font_size),
                };

                if let Some(cached) = self.raster_cache.get(&raster_key) {
                    match cached {
                        Some(glyph) => {
                            self.backend.draw_alpha_bitmap(
                                self.surface,
                                &glyph.alpha,
                                glyph.width,
                                glyph.height,
                                glyph.bearing_x,
                                glyph.bearing_y,
                                &fill_rgba,
                                &final_transform,
                            );
                            if i < run.positions.len() {
                                x_pos += run.positions[i];
                            }
                            continue;
                        }
                        None => {
                            // Negative cache — no outline, skip
                            if i < run.positions.len() {
                                x_pos += run.positions[i];
                            }
                            continue;
                        }
                    }
                }

                // Cache miss — rasterize the glyph outline to an alpha bitmap.
                // Use a pixel size based on font_size and rasterize at 1:1 scale.
                let pixel_size = font_size.ceil() as u32;
                let glyph_dim = (pixel_size * 2).min(256);
                if glyph_dim > 0 {
                    let raster =
                        rasterize_glyph_alpha(outline_ops, active_scale, pixel_size, glyph_dim);
                    if let Some(ref rg) = raster {
                        self.backend.draw_alpha_bitmap(
                            self.surface,
                            &rg.alpha,
                            rg.width,
                            rg.height,
                            rg.bearing_x,
                            rg.bearing_y,
                            &fill_rgba,
                            &final_transform,
                        );
                    }
                    self.raster_cache.insert(raster_key, raster);
                    if i < run.positions.len() {
                        x_pos += run.positions[i];
                    }
                    continue;
                }
            }

            // Draw the glyph outline
            if should_fill {
                self.backend.fill_path(
                    self.surface,
                    outline_ops,
                    FillRule::NonZero,
                    &fill_rgba,
                    &final_transform,
                );
            }
            if should_stroke {
                let stroke_style = StrokeStyle {
                    width: 1.0, // Glyph stroke width in font units
                    line_cap: rpdfium_graphics::LineCapStyle::default(),
                    line_join: rpdfium_graphics::LineJoinStyle::default(),
                    miter_limit: 10.0,
                    dash: None,
                };
                self.backend.stroke_path(
                    self.surface,
                    outline_ops,
                    &stroke_style,
                    &stroke_rgba,
                    &final_transform,
                );
            }

            // Accumulate glyph outline for text clipping (Tr modes 4-7).
            if should_clip {
                // Transform each PathOp by the final_transform and accumulate.
                for op in outline_ops {
                    self.text_clip_ops
                        .push(transform_path_op(op, &final_transform));
                }
            }

            // Advance position
            if i < run.positions.len() {
                if is_vertical {
                    y_pos -= run.positions[i];
                } else {
                    x_pos += run.positions[i];
                }
            }
        }
    }

    /// Try fallback fonts for a missing glyph.
    ///
    /// Returns `(glyph_id, font_ref, scale)` for the first fallback font that
    /// has the glyph, or `None` if no fallback font has it.
    fn find_fallback_glyph(
        &self,
        char_code: u16,
        font_size: f32,
    ) -> Option<(u16, &ResolvedFont, f32)> {
        for fb_font in &self.fallback_fonts {
            if let Some(gid) = fb_font.glyph_from_char_code(char_code) {
                let fb_upem = fb_font.units_per_em().unwrap_or(1000) as f32;
                if fb_upem == 0.0 {
                    continue;
                }
                let fb_scale = font_size / fb_upem;
                return Some((gid, fb_font.as_ref(), fb_scale));
            }
        }
        None
    }

    /// Render a Type 3 font text run.
    ///
    /// Type 3 fonts define glyphs via content streams. When pre-interpreted
    /// glyph ops are available (from `TextRun.type3_glyph_ops`), they are
    /// rendered directly. Otherwise, a placeholder rectangle is drawn.
    fn render_type3_text_run(&mut self, run: &TextRun, resolved_font: &rpdfium_font::ResolvedFont) {
        let type3 = match resolved_font.type3.as_ref() {
            Some(t3) => t3,
            None => return,
        };

        let rendering_mode = run.rendering_mode;
        if rendering_mode.is_invisible() {
            return;
        }

        let should_fill = rendering_mode.is_fill();
        let should_stroke = rendering_mode.is_stroke();
        let should_clip = rendering_mode.is_clip();

        let fill_rgba = if let Some(ref scheme) = self.forced_color_scheme {
            scheme.text_color
        } else if should_fill {
            run.fill_color
                .as_ref()
                .map(|c| RgbaColor::from_pdf_color(c, 1.0))
                .unwrap_or(RgbaColor::BLACK)
        } else {
            RgbaColor::BLACK
        };

        let stroke_rgba = if let Some(ref scheme) = self.forced_color_scheme {
            scheme.text_color
        } else if should_stroke {
            run.stroke_color
                .as_ref()
                .map(|c| RgbaColor::from_pdf_color(c, 1.0))
                .unwrap_or(RgbaColor::BLACK)
        } else {
            RgbaColor::BLACK
        };

        // Build the font matrix as a Matrix
        let fm = &type3.font_matrix;
        let font_matrix = Matrix::new(
            fm[0] as f64,
            fm[1] as f64,
            fm[2] as f64,
            fm[3] as f64,
            fm[4] as f64,
            fm[5] as f64,
        );

        let font_size = run.font_size;
        let rise = run.rise;
        let mut x_pos: f32 = 0.0;

        for (i, &byte) in run.text.iter().enumerate() {
            // Build transform: text_matrix * translate(x_pos, rise) * scale(fontSize) * font_matrix
            let glyph_translate = Matrix::from_translation(x_pos as f64, rise as f64);
            let size_scale = Matrix::new(font_size as f64, 0.0, 0.0, font_size as f64, 0.0, 0.0);
            let glyph_transform = run
                .matrix
                .pre_concat(&glyph_translate)
                .pre_concat(&size_scale)
                .pre_concat(&font_matrix);

            let final_transform = self.page_transform.pre_concat(&glyph_transform);

            // Try pre-interpreted glyph ops first, then fallback to placeholder
            let glyph_ops = run.type3_glyph_ops.as_ref().and_then(|map| map.get(&byte));

            let ops_to_render: &[PathOp];
            let placeholder_ops;

            if let Some(ops) = glyph_ops {
                if !ops.is_empty() {
                    ops_to_render = ops;
                } else {
                    // Empty glyph ops (e.g., space character) — skip rendering
                    if i < run.positions.len() {
                        x_pos += run.positions[i];
                    }
                    continue;
                }
            } else if type3.char_proc_for_code(byte).is_some() {
                // Fallback: render a placeholder rectangle
                let width = type3.char_width_f(byte);
                placeholder_ops = vec![
                    PathOp::MoveTo { x: 0.0, y: 0.0 },
                    PathOp::LineTo { x: width, y: 0.0 },
                    PathOp::LineTo {
                        x: width,
                        y: 1000.0,
                    },
                    PathOp::LineTo { x: 0.0, y: 1000.0 },
                    PathOp::Close,
                ];
                ops_to_render = &placeholder_ops;
            } else {
                // No char proc — skip
                if i < run.positions.len() {
                    x_pos += run.positions[i];
                }
                continue;
            }

            if should_fill {
                self.backend.fill_path(
                    self.surface,
                    ops_to_render,
                    FillRule::NonZero,
                    &fill_rgba,
                    &final_transform,
                );
            }
            if should_stroke {
                let stroke_style = StrokeStyle {
                    width: 1.0,
                    line_cap: rpdfium_graphics::LineCapStyle::default(),
                    line_join: rpdfium_graphics::LineJoinStyle::default(),
                    miter_limit: 10.0,
                    dash: None,
                };
                self.backend.stroke_path(
                    self.surface,
                    ops_to_render,
                    &stroke_style,
                    &stroke_rgba,
                    &final_transform,
                );
            }

            // Accumulate for text clipping (Tr modes 4-7).
            if should_clip {
                for op in ops_to_render {
                    self.text_clip_ops
                        .push(transform_path_op(op, &final_transform));
                }
            }

            // Advance position
            if i < run.positions.len() {
                x_pos += run.positions[i];
            }
        }
    }
}

/// Transform a `PathOp` by a matrix, producing pre-transformed coordinates.
///
/// This is used for text clipping where glyph outlines need to be accumulated
/// in device coordinates (already transformed) rather than passing a separate
/// transform to the clip path.
fn transform_path_op(op: &PathOp, m: &Matrix) -> PathOp {
    use rpdfium_core::Point;
    match *op {
        PathOp::MoveTo { x, y } => {
            let p = m.transform_point(Point {
                x: x as f64,
                y: y as f64,
            });
            PathOp::MoveTo {
                x: p.x as f32,
                y: p.y as f32,
            }
        }
        PathOp::LineTo { x, y } => {
            let p = m.transform_point(Point {
                x: x as f64,
                y: y as f64,
            });
            PathOp::LineTo {
                x: p.x as f32,
                y: p.y as f32,
            }
        }
        PathOp::CurveTo {
            x1,
            y1,
            x2,
            y2,
            x3,
            y3,
        } => {
            let p1 = m.transform_point(Point {
                x: x1 as f64,
                y: y1 as f64,
            });
            let p2 = m.transform_point(Point {
                x: x2 as f64,
                y: y2 as f64,
            });
            let p3 = m.transform_point(Point {
                x: x3 as f64,
                y: y3 as f64,
            });
            PathOp::CurveTo {
                x1: p1.x as f32,
                y1: p1.y as f32,
                x2: p2.x as f32,
                y2: p2.y as f32,
                x3: p3.x as f32,
                y3: p3.y as f32,
            }
        }
        PathOp::Close => PathOp::Close,
    }
}

/// Rasterize a glyph outline to an alpha bitmap for caching.
///
/// Creates a tiny-skia Pixmap, fills the outline at the given scale,
/// and extracts the alpha channel. Returns `None` if the outline cannot
/// be rasterized (e.g., empty path or zero dimensions).
fn rasterize_glyph_alpha(
    outline_ops: &[PathOp],
    scale: f32,
    _pixel_size: u32,
    dim: u32,
) -> Option<RasterGlyph> {
    if outline_ops.is_empty() || dim == 0 {
        return None;
    }

    // Compute bounding box of the outline (in font units)
    let mut min_x = f32::MAX;
    let mut min_y = f32::MAX;
    let mut max_x = f32::MIN;
    let mut max_y = f32::MIN;
    for op in outline_ops {
        match *op {
            PathOp::MoveTo { x, y } | PathOp::LineTo { x, y } => {
                min_x = min_x.min(x);
                min_y = min_y.min(y);
                max_x = max_x.max(x);
                max_y = max_y.max(y);
            }
            PathOp::CurveTo {
                x1,
                y1,
                x2,
                y2,
                x3,
                y3,
            } => {
                min_x = min_x.min(x1).min(x2).min(x3);
                min_y = min_y.min(y1).min(y2).min(y3);
                max_x = max_x.max(x1).max(x2).max(x3);
                max_y = max_y.max(y1).max(y2).max(y3);
            }
            PathOp::Close => {}
        }
    }

    if min_x >= max_x || min_y >= max_y {
        return None;
    }

    // Scale to pixel coordinates
    let width = ((max_x - min_x) * scale).ceil() as u32 + 2; // +2 for padding
    let height = ((max_y - min_y) * scale).ceil() as u32 + 2;
    let width = width.min(dim).max(1);
    let height = height.min(dim).max(1);

    let mut pixmap = tiny_skia::Pixmap::new(width, height)?;

    // Build a path from the outline
    let mut pb = tiny_skia::PathBuilder::new();
    for op in outline_ops {
        match *op {
            PathOp::MoveTo { x, y } => pb.move_to(x, y),
            PathOp::LineTo { x, y } => pb.line_to(x, y),
            PathOp::CurveTo {
                x1,
                y1,
                x2,
                y2,
                x3,
                y3,
            } => pb.cubic_to(x1, y1, x2, y2, x3, y3),
            PathOp::Close => pb.close(),
        }
    }
    let path = pb.finish()?;

    // Transform: scale and translate so the glyph fits in the pixmap
    let ts = tiny_skia::Transform::from_row(
        scale,
        0.0,
        0.0,
        -scale,               // flip Y (font coords are Y-up)
        -min_x * scale + 1.0, // center with padding
        max_y * scale + 1.0,
    );

    let mut paint = tiny_skia::Paint::default();
    paint.set_color(tiny_skia::Color::WHITE);
    paint.anti_alias = true;

    pixmap.fill_path(&path, &paint, tiny_skia::FillRule::Winding, ts, None);

    // Extract alpha channel
    let pixels = pixmap.data();
    let alpha: Vec<u8> = pixels.chunks_exact(4).map(|px| px[3]).collect();

    let bearing_x = (min_x * scale).floor() as i32 - 1;
    let bearing_y = (max_y * scale).ceil() as i32 + 1;

    Some(RasterGlyph {
        width,
        height,
        bearing_x,
        bearing_y,
        alpha,
    })
}

/// Check whether a color space family is a CMYK variant.
///
/// Used for overprint simulation: when overprint is active and the color space
/// is CMYK-based, the blend mode is forced to Darken.
fn is_cmyk_family(cs: Option<&ColorSpaceFamily>) -> bool {
    matches!(cs, Some(ColorSpaceFamily::DeviceCMYK))
}

/// Pre-scale an image transform from pixel coordinates to the PDF unit square.
///
/// PDF image XObjects occupy a (0,0)-(1,1) unit square in user space. The CTM
/// maps from this unit square to device space. Since decoded images are in
/// pixel coordinates (0,0)-(W,H), we pre-scale to map pixels → unit square.
///
/// Image pixel data is stored top-to-bottom: pixel row 0 is the top of the
/// image, which corresponds to y=1 in the PDF unit square (since PDF Y-axis
/// points upward). The pre-scale therefore includes a Y-flip:
///   pixel (px, py) → unit (px/W, 1 - py/H)
///
/// As a matrix: `[1/W, 0, 0, -1/H, 0, 1]`
fn image_unit_transform(img: &crate::image::DecodedImage, transform: &Matrix) -> Matrix {
    let w = img.width.max(1) as f64;
    let h = img.height.max(1) as f64;
    let pre_scale = Matrix::new(1.0 / w, 0.0, 0.0, -1.0 / h, 0.0, 1.0);
    transform.pre_concat(&pre_scale)
}

/// Check whether bilinear interpolation should be used for an image.
///
/// Matches PDFium's auto-bilinear heuristic in `CStretchEngine::UseInterpolateBilinear`:
/// when the image is being upscaled, use bilinear filtering to smooth the result.
///
/// The heuristic triggers when:
///   `|dest_height| / 8 < src_width * src_height / |dest_width|`
///
/// which roughly means the destination area is large relative to the source.
fn should_interpolate_image(img: &crate::image::DecodedImage, transform: &Matrix) -> bool {
    // The transform maps pixel coords to device coords.
    // For an axis-aligned image, a and d are the scale factors.
    // For a general affine transform, compute effective width/height from the matrix.
    let src_w = img.width as f64;
    let src_h = img.height as f64;

    // Effective destination dimensions from the image transform:
    // The image occupies pixel coords (0,0)-(W,H). After transform:
    //   dest_width  ≈ |(a*W, b*W)| ≈ W * sqrt(a² + b²)
    //   dest_height ≈ |(c*H, d*H)| ≈ H * sqrt(c² + d²)
    let dest_w = src_w * (transform.a * transform.a + transform.b * transform.b).sqrt();
    let dest_h = src_h * (transform.c * transform.c + transform.d * transform.d).sqrt();

    if dest_w < 1.0 || dest_h < 1.0 {
        return false;
    }

    // PDFium heuristic: abs(dest_height) / 8 < src_width * src_height / abs(dest_width)
    dest_h / 8.0 < src_w * src_h / dest_w
}

/// Apply a transfer function to an RGBA color.
///
/// The transfer function maps each component (in the [0,1] range) through
/// the given PDF function. Alpha is left unchanged.
fn apply_transfer(color: &mut RgbaColor, tf: &rpdfium_page::function::TransferFunction) {
    use rpdfium_page::function::{TransferFunction, evaluate};
    match tf {
        TransferFunction::Identity => {}
        TransferFunction::Single(f) => {
            let rv = evaluate(f, &[color.r as f32 / 255.0]);
            let gv = evaluate(f, &[color.g as f32 / 255.0]);
            let bv = evaluate(f, &[color.b as f32 / 255.0]);
            color.r = (rv.first().copied().unwrap_or(0.0).clamp(0.0, 1.0) * 255.0) as u8;
            color.g = (gv.first().copied().unwrap_or(0.0).clamp(0.0, 1.0) * 255.0) as u8;
            color.b = (bv.first().copied().unwrap_or(0.0).clamp(0.0, 1.0) * 255.0) as u8;
        }
        TransferFunction::PerComponent { r, g, b, k: _ } => {
            let rv = evaluate(r.as_ref(), &[color.r as f32 / 255.0]);
            let gv = evaluate(g.as_ref(), &[color.g as f32 / 255.0]);
            let bv = evaluate(b.as_ref(), &[color.b as f32 / 255.0]);
            color.r = (rv.first().copied().unwrap_or(0.0).clamp(0.0, 1.0) * 255.0) as u8;
            color.g = (gv.first().copied().unwrap_or(0.0).clamp(0.0, 1.0) * 255.0) as u8;
            color.b = (bv.first().copied().unwrap_or(0.0).clamp(0.0, 1.0) * 255.0) as u8;
        }
    }
}

/// Maximum number of tile repetitions in each axis to prevent runaway rendering.
const MAX_PATTERN_TILES: i32 = 512;

/// Render a tiling pattern fill by tiling the pattern cell across the path's bounding box.
///
/// Steps:
/// 1. Compute the path bounding box in user space.
/// 2. Clip the backend surface to the fill path.
/// 3. Render the pattern cell to a temporary surface at the cell size.
/// 4. Blit the cell at each tile position within the bounding box.
/// 5. Pop the clip.
#[allow(clippy::too_many_arguments)]
fn render_pattern_fill<B: RenderBackend>(
    backend: &mut B,
    surface: &mut B::Surface,
    path_ops: &[PathOp],
    fill_rule: FillRule,
    pattern: &TilingPattern,
    pattern_tree: &DisplayTree,
    page_transform: &Matrix,
    ctm: &Matrix,
    image_decoder: Option<&dyn ImageDecoder>,
) {
    use rpdfium_page::display::walk as walk_tree;

    let x_step = pattern.x_step.abs();
    let y_step = pattern.y_step.abs();
    if x_step < 0.001 || y_step < 0.001 {
        return; // Degenerate pattern — avoid division by zero
    }

    // Combined transform: page_transform * CTM * pattern_matrix
    let device_ctm = page_transform.pre_concat(ctm);
    let combined = device_ctm.pre_concat(&pattern.matrix);
    let cell_w = (x_step as f64 * combined.a.abs().max(combined.c.abs())).ceil() as u32;
    let cell_h = (y_step as f64 * combined.d.abs().max(combined.b.abs())).ceil() as u32;
    if cell_w == 0 || cell_h == 0 || cell_w > 4096 || cell_h > 4096 {
        return; // Cell too small or too large
    }

    // Render the pattern cell to a temporary surface
    let cell_transform =
        Matrix::from_scale(cell_w as f64 / x_step as f64, cell_h as f64 / y_step as f64);
    let mut cell_surface = backend.create_surface(cell_w, cell_h, &RgbaColor::TRANSPARENT);
    {
        let mut sub_renderer =
            DisplayRenderer::new(backend, &mut cell_surface, cell_transform, image_decoder);
        walk_tree(pattern_tree, &mut sub_renderer);
    }
    let cell_pixels = backend.surface_pixels(&cell_surface);

    // Clip to the fill path
    let mut clip = ClipPath::new();
    clip.push(path_ops.to_vec(), fill_rule);
    backend.push_clip(surface, &clip, &device_ctm);

    // Compute the path's bounding box in user space
    let bbox = path_bounding_box(path_ops);

    // Transform bbox corners by combined matrix to get pixel-space bounds
    let p1 = combined.transform_point(rpdfium_core::Point {
        x: bbox[0] as f64,
        y: bbox[1] as f64,
    });
    let p2 = combined.transform_point(rpdfium_core::Point {
        x: bbox[2] as f64,
        y: bbox[3] as f64,
    });
    let px_min_x = p1.x.min(p2.x) as i32;
    let px_min_y = p1.y.min(p2.y) as i32;
    let px_max_x = p1.x.max(p2.x).ceil() as i32;
    let px_max_y = p1.y.max(p2.y).ceil() as i32;

    // Determine tile grid indices
    let cell_w_i = cell_w as i32;
    let cell_h_i = cell_h as i32;
    if cell_w_i == 0 || cell_h_i == 0 {
        backend.pop_clip(surface);
        return;
    }

    // Use floor division for negative coordinates
    let start_col = px_min_x.div_euclid(cell_w_i) - 1;
    let end_col = px_max_x.div_euclid(cell_w_i) + 1;
    let start_row = px_min_y.div_euclid(cell_h_i) - 1;
    let end_row = px_max_y.div_euclid(cell_h_i) + 1;

    // Clamp to max tiles
    let n_cols = (end_col - start_col).min(MAX_PATTERN_TILES);
    let n_rows = (end_row - start_row).min(MAX_PATTERN_TILES);

    // Blit the cell at each tile position using draw_image
    let decoded = crate::image::DecodedImage {
        width: cell_w,
        height: cell_h,
        data: cell_pixels,
        format: crate::image::DecodedImageFormat::Rgba32,
    };

    for row in 0..n_rows {
        for col in 0..n_cols {
            let tile_x = (start_col + col) * cell_w_i;
            let tile_y = (start_row + row) * cell_h_i;
            // Build a transform that places the tile at the correct pixel position
            // The image is drawn in a unit square [0,1]x[0,1] scaled to cell_w x cell_h
            let tile_transform = Matrix::new(
                cell_w as f64,
                0.0,
                0.0,
                cell_h as f64,
                tile_x as f64,
                tile_y as f64,
            );
            backend.draw_image(surface, &decoded, &tile_transform, false);
        }
    }

    backend.pop_clip(surface);
}

/// Compute the axis-aligned bounding box of a set of path operations.
/// Returns `[min_x, min_y, max_x, max_y]`.
fn path_bounding_box(ops: &[PathOp]) -> [f32; 4] {
    let mut min_x = f32::MAX;
    let mut min_y = f32::MAX;
    let mut max_x = f32::MIN;
    let mut max_y = f32::MIN;

    for op in ops {
        match *op {
            PathOp::MoveTo { x, y } | PathOp::LineTo { x, y } => {
                min_x = min_x.min(x);
                min_y = min_y.min(y);
                max_x = max_x.max(x);
                max_y = max_y.max(y);
            }
            PathOp::CurveTo {
                x1,
                y1,
                x2,
                y2,
                x3,
                y3,
            } => {
                min_x = min_x.min(x1).min(x2).min(x3);
                min_y = min_y.min(y1).min(y2).min(y3);
                max_x = max_x.max(x1).max(x2).max(x3);
                max_y = max_y.max(y1).max(y2).max(y3);
            }
            PathOp::Close => {}
        }
    }

    if min_x > max_x {
        [0.0, 0.0, 0.0, 0.0]
    } else {
        [min_x, min_y, max_x, max_y]
    }
}

/// Render a soft mask's display tree and return the alpha buffer.
///
/// Returns `(alpha_data, width, height)` or `None` if the surface cannot be
/// created.  The function creates a fresh sub-renderer to avoid borrow
/// conflicts with the main renderer.
fn render_soft_mask_alpha<B: RenderBackend>(
    backend: &mut B,
    surface: &B::Surface,
    sm: &SoftMask,
    page_transform: Matrix,
    image_decoder: Option<&dyn ImageDecoder>,
) -> Option<(Vec<u8>, u32, u32)> {
    use rpdfium_page::display::walk as walk_tree;

    let (w, h) = backend.surface_dimensions(surface);
    if w == 0 || h == 0 {
        return None;
    }

    // Determine the backdrop color for the mask surface.
    // If a backdrop color is specified (from /BC in the soft mask dict),
    // fill the surface with that color before rendering the mask content.
    // This matches upstream PDFium's CPDF_RenderStatus::LoadSMask() behavior.
    let bg = match sm.backdrop_color {
        Some(ref bc) => {
            let r = bc.first().copied().unwrap_or(0.0);
            let g = bc.get(1).copied().unwrap_or(r);
            let b = bc.get(2).copied().unwrap_or(r);
            RgbaColor {
                r: (r.clamp(0.0, 1.0) * 255.0).round() as u8,
                g: (g.clamp(0.0, 1.0) * 255.0).round() as u8,
                b: (b.clamp(0.0, 1.0) * 255.0).round() as u8,
                a: 255,
            }
        }
        None => RgbaColor::TRANSPARENT,
    };

    // Render the mask group to a temporary surface.
    let mut mask_surface = backend.create_surface(w, h, &bg);
    {
        let mut sub_renderer =
            DisplayRenderer::new(backend, &mut mask_surface, page_transform, image_decoder);
        walk_tree(&sm.group, &mut sub_renderer);
    }

    // Extract pixel data from the rendered mask surface.
    let pixels = backend.surface_pixels(&mask_surface);

    // Convert to single-channel alpha buffer.
    let pixel_count = (w * h) as usize;
    let mut alpha = vec![0u8; pixel_count];

    match sm.subtype {
        SoftMaskSubtype::Alpha => {
            // Use the alpha channel directly (every 4th byte in RGBA).
            for (i, a) in alpha.iter_mut().enumerate() {
                let idx = i * 4 + 3;
                if idx < pixels.len() {
                    *a = pixels[idx];
                }
            }
        }
        SoftMaskSubtype::Luminosity => {
            // Convert RGB to luminosity: 0.2126R + 0.7152G + 0.0722B
            // Pixels are premultiplied RGBA; un-premultiply first.
            for (i, a) in alpha.iter_mut().enumerate() {
                let base = i * 4;
                if base + 3 >= pixels.len() {
                    break;
                }
                let pa = pixels[base + 3] as f32;
                if pa == 0.0 {
                    *a = 0;
                    continue;
                }
                let factor = 255.0 / pa;
                let r = (pixels[base] as f32 * factor).min(255.0);
                let g = (pixels[base + 1] as f32 * factor).min(255.0);
                let b = (pixels[base + 2] as f32 * factor).min(255.0);
                let lum = 0.2126 * r + 0.7152 * g + 0.0722 * b;
                *a = (lum.round() as u32).min(255) as u8;
            }
        }
    }

    // Apply transfer function to alpha values if present.
    if let Some(ref tf) = sm.transfer_function {
        use rpdfium_page::function::{TransferFunction, evaluate};
        match tf.as_ref() {
            TransferFunction::Identity => {}
            TransferFunction::Single(f) => {
                for a in alpha.iter_mut() {
                    let input = *a as f32 / 255.0;
                    let output = evaluate(f, &[input])
                        .first()
                        .copied()
                        .unwrap_or(input)
                        .clamp(0.0, 1.0);
                    *a = (output * 255.0).round() as u8;
                }
            }
            TransferFunction::PerComponent { r, .. } => {
                // For SMask, use the first (R) function for all alpha values
                for a in alpha.iter_mut() {
                    let input = *a as f32 / 255.0;
                    let output = evaluate(r.as_ref(), &[input])
                        .first()
                        .copied()
                        .unwrap_or(input)
                        .clamp(0.0, 1.0);
                    *a = (output * 255.0).round() as u8;
                }
            }
        }
    }

    Some((alpha, w, h))
}

/// Apply an image mask to a decoded image.
///
/// - **Stencil**: The image data is a 1-bit mask. For each pixel, if the sample
///   is nonzero (opaque in the mask), the pixel is painted with `fill_color`;
///   otherwise it is fully transparent.
/// - **ColorKey**: Pixels whose sample values fall within the specified ranges
///   are made fully transparent (alpha = 0).
/// - **ExplicitMask**: Decode the mask stream as a grayscale image and apply
///   as the alpha channel.
/// - **SoftMask**: Decode the mask stream as a grayscale image and apply
///   as the alpha channel, with optional matte color removal.
fn apply_image_mask(
    mut img: crate::image::DecodedImage,
    mask: Option<&rpdfium_page::display::ImageMask>,
    fill_color: Option<&Color>,
    decoder: Option<&dyn ImageDecoder>,
) -> crate::image::DecodedImage {
    use crate::image::DecodedImageFormat;
    use rpdfium_page::display::ImageMask;

    let mask = match mask {
        Some(m) => m,
        None => return img,
    };

    match mask {
        ImageMask::Stencil => {
            let rgba = fill_color
                .map(|c| RgbaColor::from_pdf_color(c, 1.0))
                .unwrap_or(RgbaColor::BLACK);

            let w = img.width as usize;
            let h = img.height as usize;
            let pixel_count = w * h;
            let mut out = vec![0u8; pixel_count * 4];

            match img.format {
                DecodedImageFormat::Gray8 => {
                    // Each byte is a grayscale sample; nonzero → fill color
                    for i in 0..pixel_count.min(img.data.len()) {
                        let dst = i * 4;
                        if img.data[i] != 0 {
                            out[dst] = rgba.r;
                            out[dst + 1] = rgba.g;
                            out[dst + 2] = rgba.b;
                            out[dst + 3] = rgba.a;
                        }
                        // else: stays [0,0,0,0] (transparent)
                    }
                }
                DecodedImageFormat::Rgb24 => {
                    // Treat as grayscale via luminance of each pixel
                    for i in 0..pixel_count {
                        let src = i * 3;
                        let dst = i * 4;
                        if src + 2 < img.data.len() {
                            let lum = img.data[src] as u16
                                + img.data[src + 1] as u16
                                + img.data[src + 2] as u16;
                            if lum > 0 {
                                out[dst] = rgba.r;
                                out[dst + 1] = rgba.g;
                                out[dst + 2] = rgba.b;
                                out[dst + 3] = rgba.a;
                            }
                        }
                    }
                }
                DecodedImageFormat::Rgba32 => {
                    // Use alpha channel as mask signal
                    for i in 0..pixel_count {
                        let src = i * 4;
                        let dst = i * 4;
                        if src + 3 < img.data.len() && img.data[src + 3] != 0 {
                            out[dst] = rgba.r;
                            out[dst + 1] = rgba.g;
                            out[dst + 2] = rgba.b;
                            out[dst + 3] = rgba.a;
                        }
                    }
                }
            }

            img.data = out;
            img.format = DecodedImageFormat::Rgba32;
            img
        }
        ImageMask::ColorKey { ranges } => {
            // Convert to RGBA if needed, then set alpha=0 for matching pixels
            let w = img.width as usize;
            let h = img.height as usize;
            let pixel_count = w * h;

            match img.format {
                DecodedImageFormat::Gray8 => {
                    // 1 component: check ranges[0]
                    let mut out = vec![0u8; pixel_count * 4];
                    for i in 0..pixel_count.min(img.data.len()) {
                        let g = img.data[i];
                        let dst = i * 4;
                        out[dst] = g;
                        out[dst + 1] = g;
                        out[dst + 2] = g;
                        let masked = ranges
                            .first()
                            .is_some_and(|r| (g as u32) >= r[0] && (g as u32) <= r[1]);
                        out[dst + 3] = if masked { 0 } else { 255 };
                    }
                    img.data = out;
                    img.format = DecodedImageFormat::Rgba32;
                }
                DecodedImageFormat::Rgb24 => {
                    // 3 components: check ranges[0..3]
                    let mut out = vec![0u8; pixel_count * 4];
                    for i in 0..pixel_count {
                        let src = i * 3;
                        let dst = i * 4;
                        if src + 2 >= img.data.len() {
                            break;
                        }
                        let r = img.data[src];
                        let g = img.data[src + 1];
                        let b = img.data[src + 2];
                        out[dst] = r;
                        out[dst + 1] = g;
                        out[dst + 2] = b;

                        let components = [r, g, b];
                        let masked = components.iter().enumerate().all(|(ci, &val)| {
                            ranges
                                .get(ci)
                                .is_some_and(|rng| (val as u32) >= rng[0] && (val as u32) <= rng[1])
                        }) && !ranges.is_empty();
                        out[dst + 3] = if masked { 0 } else { 255 };
                    }
                    img.data = out;
                    img.format = DecodedImageFormat::Rgba32;
                }
                DecodedImageFormat::Rgba32 => {
                    // 3 visible components (R, G, B), alpha already present
                    for i in 0..pixel_count {
                        let base = i * 4;
                        if base + 3 >= img.data.len() {
                            break;
                        }
                        let components = [img.data[base], img.data[base + 1], img.data[base + 2]];
                        let masked = components.iter().enumerate().all(|(ci, &val)| {
                            ranges
                                .get(ci)
                                .is_some_and(|rng| (val as u32) >= rng[0] && (val as u32) <= rng[1])
                        }) && !ranges.is_empty();
                        if masked {
                            img.data[base + 3] = 0;
                        }
                    }
                }
            }
            img
        }
        ImageMask::ExplicitMask { mask_object_id } => {
            // Decode the mask stream as a grayscale image and apply as alpha
            let Some(dec) = decoder else {
                return img;
            };
            let mask_ref = ImageRef {
                object_id: *mask_object_id,
            };
            let mask_img = match dec.decode_image(&mask_ref, &rpdfium_core::Matrix::identity()) {
                Ok(m) => m,
                Err(_) => return img,
            };

            apply_grayscale_mask_alpha(&mut img, &mask_img, None);
            img
        }
        ImageMask::SoftMask {
            smask_object_id,
            matte,
        } => {
            // Decode the soft mask stream as a grayscale image and apply as alpha
            let Some(dec) = decoder else {
                return img;
            };
            let mask_ref = ImageRef {
                object_id: *smask_object_id,
            };
            let mask_img = match dec.decode_image(&mask_ref, &rpdfium_core::Matrix::identity()) {
                Ok(m) => m,
                Err(_) => return img,
            };

            apply_grayscale_mask_alpha(&mut img, &mask_img, matte.as_deref());
            img
        }
    }
}

/// Apply a grayscale mask image as the alpha channel of the target image.
///
/// If `matte` is provided, performs matte color removal (un-pre-multiplication):
/// `result[c] = clamp((pixel[c] - matte_int) * 255 / mask + matte_int, 0, 255)`
///
/// Matte is only applied when the number of matte components matches the
/// image's original color component count (matching upstream PDFium behavior
/// from cpdf_dib.cpp: `pMatte->size() == components_`).
fn apply_grayscale_mask_alpha(
    img: &mut crate::image::DecodedImage,
    mask: &crate::image::DecodedImage,
    matte: Option<&[f32]>,
) {
    use crate::image::DecodedImageFormat;

    let w = img.width as usize;
    let h = img.height as usize;
    let pixel_count = w * h;

    // Determine the original color component count for matte validation.
    // Matte is only applied when matte.len() == components (upstream check).
    let original_components: usize = match img.format {
        DecodedImageFormat::Gray8 => 1,
        DecodedImageFormat::Rgb24 | DecodedImageFormat::Rgba32 => 3,
    };
    let validated_matte: Option<&[f32]> = matte.filter(|m| m.len() == original_components);

    // Extract grayscale values from the mask
    let mask_values: Vec<u8> = match mask.format {
        DecodedImageFormat::Gray8 => mask.data.clone(),
        DecodedImageFormat::Rgb24 => mask
            .data
            .chunks_exact(3)
            .map(|p| ((p[0] as u16 + p[1] as u16 + p[2] as u16) / 3) as u8)
            .collect(),
        DecodedImageFormat::Rgba32 => mask.data.chunks_exact(4).map(|p| p[0]).collect(),
    };

    // Scale mask to image dimensions if they differ (simple nearest-neighbor)
    let scaled_mask: Vec<u8> = if mask.width == img.width && mask.height == img.height {
        mask_values
    } else {
        let mw = mask.width as usize;
        let mh = mask.height as usize;
        if mw == 0 || mh == 0 {
            return;
        }
        let mut scaled = vec![0u8; pixel_count];
        for y in 0..h {
            for x in 0..w {
                let mx = x * mw / w;
                let my = y * mh / h;
                let mi = my * mw + mx;
                scaled[y * w + x] = mask_values.get(mi).copied().unwrap_or(0);
            }
        }
        scaled
    };

    // Ensure image is RGBA
    match img.format {
        DecodedImageFormat::Gray8 => {
            let mut rgba = vec![0u8; pixel_count * 4];
            for i in 0..pixel_count.min(img.data.len()) {
                let g = img.data[i];
                let base = i * 4;
                rgba[base] = g;
                rgba[base + 1] = g;
                rgba[base + 2] = g;
                rgba[base + 3] = 255;
            }
            img.data = rgba;
            img.format = DecodedImageFormat::Rgba32;
        }
        DecodedImageFormat::Rgb24 => {
            let mut rgba = vec![0u8; pixel_count * 4];
            for i in 0..pixel_count {
                let src = i * 3;
                let dst = i * 4;
                if src + 2 < img.data.len() {
                    rgba[dst] = img.data[src];
                    rgba[dst + 1] = img.data[src + 1];
                    rgba[dst + 2] = img.data[src + 2];
                    rgba[dst + 3] = 255;
                }
            }
            img.data = rgba;
            img.format = DecodedImageFormat::Rgba32;
        }
        DecodedImageFormat::Rgba32 => {}
    }

    // Apply the mask as alpha channel
    for i in 0..pixel_count {
        let base = i * 4;
        if base + 3 >= img.data.len() {
            break;
        }
        let alpha = scaled_mask.get(i).copied().unwrap_or(0);

        // Apply matte color removal if validated (component count matches).
        // Uses the upstream PDFium integer formula from cpdf_imagerenderer.cpp:
        //   orig[c] = (pixel[c] - matte_int) * 255 / mask + matte_int
        if let Some(m) = validated_matte {
            if alpha > 0 {
                let mask_i = alpha as i32;
                for c in 0..3 {
                    let mc = m.get(c).copied().unwrap_or(0.0);
                    let matte_int = (mc * 255.0).round() as i32;
                    let pixel_val = img.data[base + c] as i32;
                    let orig = (pixel_val - matte_int) * 255 / mask_i + matte_int;
                    img.data[base + c] = orig.clamp(0, 255) as u8;
                }
            }
        }

        img.data[base + 3] = alpha;
    }
}

/// Apply a transfer function to each pixel of a decoded image (R, G, B channels).
fn apply_transfer_to_image(
    img: &mut crate::image::DecodedImage,
    tf: &rpdfium_page::function::TransferFunction,
) {
    use crate::image::DecodedImageFormat;
    use rpdfium_page::function::{TransferFunction, evaluate};

    if matches!(tf, TransferFunction::Identity) {
        return;
    }

    match img.format {
        DecodedImageFormat::Gray8 => {
            for pixel in img.data.iter_mut() {
                let v = *pixel as f32 / 255.0;
                let result = match tf {
                    TransferFunction::Identity => v,
                    TransferFunction::Single(f) => evaluate(f, &[v]).first().copied().unwrap_or(v),
                    TransferFunction::PerComponent { r, .. } => {
                        evaluate(r.as_ref(), &[v]).first().copied().unwrap_or(v)
                    }
                };
                *pixel = (result.clamp(0.0, 1.0) * 255.0) as u8;
            }
        }
        DecodedImageFormat::Rgb24 => {
            for chunk in img.data.chunks_exact_mut(3) {
                for (c, byte) in chunk.iter_mut().enumerate() {
                    let v = *byte as f32 / 255.0;
                    let result = match tf {
                        TransferFunction::Identity => v,
                        TransferFunction::Single(f) => {
                            evaluate(f, &[v]).first().copied().unwrap_or(v)
                        }
                        TransferFunction::PerComponent { r, g, b, .. } => {
                            let f = match c {
                                0 => r.as_ref(),
                                1 => g.as_ref(),
                                _ => b.as_ref(),
                            };
                            evaluate(f, &[v]).first().copied().unwrap_or(v)
                        }
                    };
                    *byte = (result.clamp(0.0, 1.0) * 255.0) as u8;
                }
            }
        }
        DecodedImageFormat::Rgba32 => {
            for chunk in img.data.chunks_exact_mut(4) {
                #[allow(clippy::needless_range_loop)]
                for c in 0..3 {
                    let v = chunk[c] as f32 / 255.0;
                    let result = match tf {
                        TransferFunction::Identity => v,
                        TransferFunction::Single(f) => {
                            evaluate(f, &[v]).first().copied().unwrap_or(v)
                        }
                        TransferFunction::PerComponent { r, g, b, .. } => {
                            let f = match c {
                                0 => r.as_ref(),
                                1 => g.as_ref(),
                                _ => b.as_ref(),
                            };
                            evaluate(f, &[v]).first().copied().unwrap_or(v)
                        }
                    };
                    chunk[c] = (result.clamp(0.0, 1.0) * 255.0) as u8;
                }
                // Alpha channel unchanged
            }
        }
    }
}

impl<B: RenderBackend> DisplayVisitor for DisplayRenderer<'_, B> {
    fn enter_group(
        &mut self,
        blend_mode: BlendMode,
        clip: Option<&ClipPath>,
        opacity: f32,
        isolated: bool,
        knockout: bool,
        soft_mask: &Option<Box<SoftMask>>,
    ) -> bool {
        let has_clip = clip.is_some_and(|c| !c.is_empty());
        let has_smask = soft_mask.is_some();
        let has_group = blend_mode != BlendMode::Normal || opacity < 1.0 || knockout || has_smask;

        if has_clip {
            self.backend
                .push_clip(self.surface, clip.unwrap(), &self.page_transform);
        }
        if has_group {
            self.backend
                .push_group(self.surface, blend_mode, opacity, isolated, knockout);
        }

        // Render soft mask into an alpha buffer and attach to the group.
        if let Some(sm) = soft_mask {
            let alpha = render_soft_mask_alpha(
                self.backend,
                self.surface,
                sm,
                self.page_transform,
                self.image_decoder,
            );
            if let Some((data, w, h)) = alpha {
                self.backend.set_group_mask(data, w, h);
            }
        }

        let action = match (has_clip, has_group) {
            (false, false) => GroupAction::Nothing,
            (true, false) => GroupAction::ClipOnly,
            (false, true) => GroupAction::GroupOnly,
            (true, true) => GroupAction::ClipAndGroup,
        };
        self.group_stack.push(action);
        true // always descend
    }

    fn leave_group(&mut self) {
        // Pop any text clips accumulated during this group's text objects.
        while self.text_clip_depth > 0 {
            self.backend.pop_clip(self.surface);
            self.text_clip_depth -= 1;
        }

        if let Some(action) = self.group_stack.pop() {
            match action {
                GroupAction::Nothing => {}
                GroupAction::ClipOnly => {
                    self.backend.pop_clip(self.surface);
                }
                GroupAction::GroupOnly => {
                    self.backend.pop_group(self.surface);
                }
                GroupAction::ClipAndGroup => {
                    self.backend.pop_group(self.surface);
                    self.backend.pop_clip(self.surface);
                }
            }
        }
    }

    fn visit_path(
        &mut self,
        ops: &[PathOp],
        style: &PathStyle,
        matrix: &Matrix,
        fill_color: Option<&Color>,
        stroke_color: Option<&Color>,
        fill_color_space: Option<&ColorSpaceFamily>,
        stroke_color_space: Option<&ColorSpaceFamily>,
        transfer_function: Option<&rpdfium_page::function::TransferFunction>,
        overprint: bool,
        _overprint_mode: u32,
    ) {
        // Combine CTM with page transform: user space → page space → device space
        let transform = self.page_transform.pre_concat(matrix);

        // Per-feature AA: set backend to path_antialiasing for path rendering.
        self.backend.set_antialiasing(self.path_antialiasing);

        // Overprint simulation: when overprint is active and the color is CMYK,
        // force Darken blend mode for the operation (simplified upstream approach).
        let fill_overprint_darken = overprint && is_cmyk_family(fill_color_space);
        let stroke_overprint_darken = overprint && is_cmyk_family(stroke_color_space);

        // Fill
        if let (Some(fill_rule), Some(color)) = (style.fill, fill_color) {
            if fill_overprint_darken {
                self.backend
                    .push_group(self.surface, BlendMode::Darken, 1.0, false, false);
            }
            let mut rgba = if let Some(ref scheme) = self.forced_color_scheme {
                scheme.text_color
            } else {
                RgbaColor::from_pdf_color(color, 1.0)
            };
            if let Some(tf) = transfer_function {
                apply_transfer(&mut rgba, tf);
            }
            self.backend
                .fill_path(self.surface, ops, fill_rule, &rgba, &transform);
            if fill_overprint_darken {
                self.backend.pop_group(self.surface);
            }
        }
        // Stroke
        if style.stroke {
            if let Some(color) = stroke_color {
                if stroke_overprint_darken {
                    self.backend
                        .push_group(self.surface, BlendMode::Darken, 1.0, false, false);
                }
                let mut rgba = if let Some(ref scheme) = self.forced_color_scheme {
                    scheme.text_color
                } else {
                    RgbaColor::from_pdf_color(color, 1.0)
                };
                if let Some(tf) = transfer_function {
                    apply_transfer(&mut rgba, tf);
                }
                let stroke_style = StrokeStyle::from_path_style(style);
                self.backend
                    .stroke_path(self.surface, ops, &stroke_style, &rgba, &transform);
                if stroke_overprint_darken {
                    self.backend.pop_group(self.surface);
                }
            }
        }
    }

    fn visit_image(
        &mut self,
        image_ref: &ImageRef,
        matrix: &Matrix,
        mask: Option<&rpdfium_page::display::ImageMask>,
        fill_color: Option<&Color>,
        transfer_function: Option<&rpdfium_page::function::TransferFunction>,
    ) {
        if let Some(decoder) = self.image_decoder {
            let transform = self.page_transform.pre_concat(matrix);
            match decoder.decode_image(image_ref, &transform) {
                Ok(img) => {
                    let mut masked = apply_image_mask(img, mask, fill_color, self.image_decoder);
                    if let Some(tf) = transfer_function {
                        apply_transfer_to_image(&mut masked, tf);
                    }
                    // PDF images occupy a unit square (0,0)-(1,1) in user space.
                    // The CTM maps from unit square to device space. Since the
                    // decoded image is in pixel coords (0,0)-(W,H), pre-scale
                    // to map pixel coords → unit square before applying the CTM.
                    let img_transform = image_unit_transform(&masked, &transform);
                    let interpolate = self.image_antialiasing
                        && should_interpolate_image(&masked, &img_transform);
                    self.backend
                        .draw_image(self.surface, &masked, &img_transform, interpolate);
                }
                Err(e) => tracing::warn!(
                    object_id = %image_ref.object_id,
                    error = %e,
                    "failed to decode image XObject"
                ),
            }
        }
    }

    fn visit_inline_image(
        &mut self,
        properties: &HashMap<Name, Operand>,
        data: &[u8],
        matrix: &Matrix,
    ) {
        if let Some(decoder) = self.image_decoder {
            let transform = self.page_transform.pre_concat(matrix);
            match decoder.decode_inline_image(properties, data, &transform) {
                Ok(img) => {
                    let img_transform = image_unit_transform(&img, &transform);
                    let interpolate = should_interpolate_image(&img, &img_transform);
                    self.backend
                        .draw_image(self.surface, &img, &img_transform, interpolate);
                }
                Err(e) => tracing::warn!(
                    data_len = data.len(),
                    error = %e,
                    "failed to decode inline image"
                ),
            }
        }
    }

    fn visit_pattern_fill(
        &mut self,
        path_ops: &[PathOp],
        fill_rule: FillRule,
        pattern: &TilingPattern,
        pattern_tree: &DisplayTree,
        _fill_color: Option<&Color>,
        matrix: &Matrix,
    ) {
        render_pattern_fill(
            self.backend,
            self.surface,
            path_ops,
            fill_rule,
            pattern,
            pattern_tree,
            &self.page_transform,
            matrix,
            self.image_decoder,
        );
    }

    fn visit_shading_fill(&mut self, shading: &ShadingDict, matrix: &Matrix) {
        let transform = self.page_transform.pre_concat(matrix);
        // `sh` operator = direct shading object, so is_shading_object=true
        // (background not rendered per upstream L1019).
        crate::render_shading::render_shading(
            self.backend,
            self.surface,
            shading,
            &transform,
            true,
        );
    }

    fn visit_text(&mut self, runs: &[TextRun]) {
        for run in runs {
            self.render_text_run(run);
        }

        // Apply accumulated text clip (Tr modes 4-7).
        // The clip was accumulated during render_text_run for runs with is_clip().
        if !self.text_clip_ops.is_empty() {
            let ops = std::mem::take(&mut self.text_clip_ops);
            let mut clip = ClipPath::new();
            // The ops are already in device coordinates (pre-transformed),
            // so use identity transform when pushing.
            clip.push(ops, FillRule::NonZero);
            self.backend
                .push_clip(self.surface, &clip, &Matrix::identity());
            self.text_clip_depth += 1;
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use rpdfium_graphics::{Bitmap, BitmapFormat, FillRule};
    use rpdfium_page::display::{DisplayNode, DisplayTree, walk};
    use std::sync::Mutex;

    use crate::image::DecodedImage;

    /// Trivial surface type for mock backend (avoids clippy::let_unit_value).
    struct MockSurface;

    /// A mock backend that records operations for testing.
    struct MockBackend {
        log: Mutex<Vec<String>>,
    }

    impl MockBackend {
        fn new() -> Self {
            Self {
                log: Mutex::new(Vec::new()),
            }
        }

        fn log(&self) -> Vec<String> {
            self.log.lock().unwrap().clone()
        }
    }

    impl RenderBackend for MockBackend {
        type Surface = MockSurface;

        fn create_surface(&self, _w: u32, _h: u32, _bg: &RgbaColor) -> Self::Surface {
            MockSurface
        }

        fn fill_path(
            &mut self,
            _surface: &mut Self::Surface,
            _ops: &[PathOp],
            _fill_rule: FillRule,
            _color: &RgbaColor,
            _transform: &Matrix,
        ) {
            self.log.lock().unwrap().push("fill_path".to_string());
        }

        fn stroke_path(
            &mut self,
            _surface: &mut Self::Surface,
            _ops: &[PathOp],
            _style: &StrokeStyle,
            _color: &RgbaColor,
            _transform: &Matrix,
        ) {
            self.log.lock().unwrap().push("stroke_path".to_string());
        }

        fn draw_image(
            &mut self,
            _surface: &mut Self::Surface,
            _image: &DecodedImage,
            _transform: &Matrix,
            _interpolate: bool,
        ) {
            self.log.lock().unwrap().push("draw_image".to_string());
        }

        fn push_clip(
            &mut self,
            _surface: &mut Self::Surface,
            _clip: &ClipPath,
            _transform: &Matrix,
        ) {
            self.log.lock().unwrap().push("push_clip".to_string());
        }

        fn pop_clip(&mut self, _surface: &mut Self::Surface) {
            self.log.lock().unwrap().push("pop_clip".to_string());
        }

        fn push_group(
            &mut self,
            _surface: &mut Self::Surface,
            _blend_mode: BlendMode,
            _opacity: f32,
            _isolated: bool,
            _knockout: bool,
        ) {
            self.log.lock().unwrap().push("push_group".to_string());
        }

        fn pop_group(&mut self, _surface: &mut Self::Surface) {
            self.log.lock().unwrap().push("pop_group".to_string());
        }

        fn surface_dimensions(&self, _surface: &Self::Surface) -> (u32, u32) {
            (100, 100)
        }

        fn composite_over(&mut self, _dst: &mut Self::Surface, _src: &Self::Surface) {}

        fn surface_pixels(&self, _surface: &Self::Surface) -> Vec<u8> {
            vec![0u8; 100 * 100 * 4]
        }

        fn finish(self, _surface: Self::Surface) -> Bitmap {
            Bitmap::new(1, 1, BitmapFormat::Rgba32)
        }
    }

    /// Helper to create a MockBackend + MockSurface and run the renderer on a tree.
    fn run_mock_renderer(tree: &DisplayTree) -> Vec<String> {
        let mut backend = MockBackend::new();
        let mut surface = backend.create_surface(100, 100, &RgbaColor::WHITE);
        {
            let mut renderer =
                DisplayRenderer::new(&mut backend, &mut surface, Matrix::identity(), None);
            walk(tree, &mut renderer);
        }
        backend.log()
    }

    #[test]
    fn test_renderer_empty_tree() {
        let tree = DisplayTree {
            root: DisplayNode::Group {
                blend_mode: BlendMode::Normal,
                clip: None,
                opacity: 1.0,
                isolated: false,
                knockout: false,
                soft_mask: None,
                children: Vec::new(),
            },
        };
        // Normal blend + opacity 1.0 + no clip = GroupAction::Nothing
        assert!(run_mock_renderer(&tree).is_empty());
    }

    #[test]
    fn test_renderer_fill_path() {
        let tree = DisplayTree {
            root: DisplayNode::Group {
                blend_mode: BlendMode::Normal,
                clip: None,
                opacity: 1.0,
                isolated: false,
                knockout: false,
                soft_mask: None,
                children: vec![DisplayNode::Path {
                    ops: vec![
                        PathOp::MoveTo { x: 0.0, y: 0.0 },
                        PathOp::LineTo { x: 100.0, y: 0.0 },
                        PathOp::LineTo { x: 100.0, y: 100.0 },
                        PathOp::Close,
                    ],
                    style: PathStyle {
                        fill: Some(FillRule::NonZero),
                        ..PathStyle::default()
                    },
                    matrix: Matrix::identity(),
                    fill_color: Some(Color::rgb(1.0, 0.0, 0.0)),
                    stroke_color: None,
                    fill_color_space: None,
                    stroke_color_space: None,
                    transfer_function: None,
                    overprint: false,
                    overprint_mode: 0,
                }],
            },
        };
        assert_eq!(run_mock_renderer(&tree), vec!["fill_path"]);
    }

    #[test]
    fn test_renderer_stroke_path() {
        let tree = DisplayTree {
            root: DisplayNode::Group {
                blend_mode: BlendMode::Normal,
                clip: None,
                opacity: 1.0,
                isolated: false,
                knockout: false,
                soft_mask: None,
                children: vec![DisplayNode::Path {
                    ops: vec![
                        PathOp::MoveTo { x: 0.0, y: 0.0 },
                        PathOp::LineTo { x: 100.0, y: 0.0 },
                    ],
                    style: PathStyle {
                        stroke: true,
                        ..PathStyle::default()
                    },
                    matrix: Matrix::identity(),
                    fill_color: None,
                    stroke_color: Some(Color::gray(0.0)),
                    fill_color_space: None,
                    stroke_color_space: None,
                    transfer_function: None,
                    overprint: false,
                    overprint_mode: 0,
                }],
            },
        };
        assert_eq!(run_mock_renderer(&tree), vec!["stroke_path"]);
    }

    #[test]
    fn test_renderer_fill_and_stroke() {
        let tree = DisplayTree {
            root: DisplayNode::Group {
                blend_mode: BlendMode::Normal,
                clip: None,
                opacity: 1.0,
                isolated: false,
                knockout: false,
                soft_mask: None,
                children: vec![DisplayNode::Path {
                    ops: vec![
                        PathOp::MoveTo { x: 0.0, y: 0.0 },
                        PathOp::LineTo { x: 50.0, y: 0.0 },
                        PathOp::LineTo { x: 50.0, y: 50.0 },
                        PathOp::Close,
                    ],
                    style: PathStyle {
                        fill: Some(FillRule::EvenOdd),
                        stroke: true,
                        ..PathStyle::default()
                    },
                    matrix: Matrix::identity(),
                    fill_color: Some(Color::rgb(0.0, 1.0, 0.0)),
                    stroke_color: Some(Color::gray(0.0)),
                    fill_color_space: None,
                    stroke_color_space: None,
                    transfer_function: None,
                    overprint: false,
                    overprint_mode: 0,
                }],
            },
        };
        assert_eq!(run_mock_renderer(&tree), vec!["fill_path", "stroke_path"]);
    }

    #[test]
    fn test_renderer_group_with_clip() {
        let mut clip = ClipPath::new();
        clip.push(
            vec![
                PathOp::MoveTo { x: 0.0, y: 0.0 },
                PathOp::LineTo { x: 50.0, y: 50.0 },
                PathOp::Close,
            ],
            FillRule::NonZero,
        );
        let tree = DisplayTree {
            root: DisplayNode::Group {
                blend_mode: BlendMode::Normal,
                clip: Some(clip),
                opacity: 1.0,
                isolated: false,
                knockout: false,
                soft_mask: None,
                children: Vec::new(),
            },
        };
        assert_eq!(run_mock_renderer(&tree), vec!["push_clip", "pop_clip"]);
    }

    #[test]
    fn test_renderer_group_with_blend_mode() {
        let tree = DisplayTree {
            root: DisplayNode::Group {
                blend_mode: BlendMode::Multiply,
                clip: None,
                opacity: 0.5,
                isolated: false,
                knockout: false,
                soft_mask: None,
                children: Vec::new(),
            },
        };
        assert_eq!(run_mock_renderer(&tree), vec!["push_group", "pop_group"]);
    }

    #[test]
    fn test_renderer_group_with_clip_and_blend() {
        let mut clip = ClipPath::new();
        clip.push(
            vec![PathOp::MoveTo { x: 0.0, y: 0.0 }, PathOp::Close],
            FillRule::NonZero,
        );
        let tree = DisplayTree {
            root: DisplayNode::Group {
                blend_mode: BlendMode::Screen,
                clip: Some(clip),
                opacity: 0.8,
                isolated: false,
                knockout: false,
                soft_mask: None,
                children: Vec::new(),
            },
        };
        // push_clip, push_group, then pop_group, pop_clip
        assert_eq!(
            run_mock_renderer(&tree),
            vec!["push_clip", "push_group", "pop_group", "pop_clip"]
        );
    }

    #[test]
    fn test_renderer_text_no_font_is_noop() {
        let tree = DisplayTree {
            root: DisplayNode::Group {
                blend_mode: BlendMode::Normal,
                clip: None,
                opacity: 1.0,
                isolated: false,
                knockout: false,
                soft_mask: None,
                children: vec![DisplayNode::Text { runs: vec![] }],
            },
        };
        // Empty text runs — no backend calls
        assert!(run_mock_renderer(&tree).is_empty());
    }

    #[test]
    fn test_renderer_type3_text_fills_glyphs() {
        use rpdfium_font::font_type::PdfFontType;
        use rpdfium_font::resolved::ResolvedFont;
        use rpdfium_font::type3_font::{Type3Encoding, Type3Font};
        use std::sync::Arc;

        let mut char_procs = std::collections::HashMap::new();
        char_procs.insert(Name::from("a"), rpdfium_core::ObjectId::new(10, 0));

        let type3 = Type3Font {
            font_matrix: [0.001, 0.0, 0.0, 0.001, 0.0, 0.0],
            char_procs,
            encoding: Type3Encoding::Differences(vec![(65, Name::from("a"))]),
            first_char: 65,
            last_char: 65,
            widths: vec![600.0],
        };

        let font = Arc::new(ResolvedFont {
            font_type: PdfFontType::Type3,
            base_font_name: "TestType3".to_string(),
            widths: vec![600],
            default_width: 600,
            first_char: 65,
            ascent: 800,
            descent: -200,
            italic_angle: 0.0,
            is_embedded: false,
            to_unicode: None,
            encoding: rpdfium_font::fx_codepage::FontEncoding::Standard,
            font_data: None,
            cid_to_gid: None,
            wmode: 0,
            vertical_metrics: None,
            cid_cmap: None,
            type3: Some(type3),
            weight: None,
            flags: None,
            cid_coding: rpdfium_font::cid_font::CidCoding::Unknown,
            ttc_face_index: 0,
            glyph_outline_cache: std::sync::OnceLock::new(),
        });

        let tree = DisplayTree {
            root: DisplayNode::Group {
                blend_mode: BlendMode::Normal,
                clip: None,
                opacity: 1.0,
                isolated: false,
                knockout: false,
                soft_mask: None,
                children: vec![DisplayNode::Text {
                    runs: vec![TextRun {
                        font_name: Name::from("F1"),
                        font_size: 12.0,
                        matrix: Matrix::identity(),
                        text: vec![65], // 'A' -> maps to glyph "a"
                        positions: vec![7.2],
                        resolved_font: Some(font),
                        rendering_mode: TextRenderingMode::Fill,
                        rise: 0.0,
                        fill_color: Some(Color::gray(0.0)),
                        stroke_color: None,
                        actual_text: None,
                        type3_glyph_ops: None,
                        actual_text_id: None,
                        is_vertical: false,
                        vert_origins: vec![],
                    }],
                }],
            },
        };
        // Type 3 glyph with a char proc should produce a fill_path call
        assert_eq!(run_mock_renderer(&tree), vec!["fill_path"]);
    }

    #[test]
    fn test_renderer_type3_no_type3_data_is_noop() {
        use rpdfium_font::font_type::PdfFontType;
        use rpdfium_font::resolved::ResolvedFont;
        use std::sync::Arc;

        // Type 3 font but with no type3 data
        let font = Arc::new(ResolvedFont {
            font_type: PdfFontType::Type3,
            base_font_name: "TestType3".to_string(),
            widths: vec![],
            default_width: 600,
            first_char: 0,
            ascent: 800,
            descent: -200,
            italic_angle: 0.0,
            is_embedded: false,
            to_unicode: None,
            encoding: rpdfium_font::fx_codepage::FontEncoding::Standard,
            font_data: None,
            cid_to_gid: None,
            wmode: 0,
            vertical_metrics: None,
            cid_cmap: None,
            type3: None, // No Type 3 data
            weight: None,
            flags: None,
            cid_coding: rpdfium_font::cid_font::CidCoding::Unknown,
            ttc_face_index: 0,
            glyph_outline_cache: std::sync::OnceLock::new(),
        });

        let tree = DisplayTree {
            root: DisplayNode::Group {
                blend_mode: BlendMode::Normal,
                clip: None,
                opacity: 1.0,
                isolated: false,
                knockout: false,
                soft_mask: None,
                children: vec![DisplayNode::Text {
                    runs: vec![TextRun {
                        font_name: Name::from("F1"),
                        font_size: 12.0,
                        matrix: Matrix::identity(),
                        text: vec![65],
                        positions: vec![7.2],
                        resolved_font: Some(font),
                        rendering_mode: TextRenderingMode::Fill,
                        rise: 0.0,
                        fill_color: Some(Color::gray(0.0)),
                        stroke_color: None,
                        actual_text: None,
                        type3_glyph_ops: None,
                        actual_text_id: None,
                        is_vertical: false,
                        vert_origins: vec![],
                    }],
                }],
            },
        };
        // No type3 data — should not produce any backend calls
        assert!(run_mock_renderer(&tree).is_empty());
    }

    #[test]
    fn test_renderer_image_without_decoder_is_noop() {
        let tree = DisplayTree {
            root: DisplayNode::Group {
                blend_mode: BlendMode::Normal,
                clip: None,
                opacity: 1.0,
                isolated: false,
                knockout: false,
                soft_mask: None,
                children: vec![DisplayNode::Image {
                    image_ref: ImageRef {
                        object_id: rpdfium_core::ObjectId::new(1, 0),
                    },
                    matrix: Matrix::identity(),
                    mask: None,
                    fill_color: None,
                    transfer_function: None,
                }],
            },
        };
        // No decoder provided — should not call draw_image
        assert!(run_mock_renderer(&tree).is_empty());
    }

    #[test]
    fn test_renderer_group_with_smask_pushes_group() {
        use rpdfium_page::display::SoftMaskSubtype;
        // A group with an SMask should trigger push_group even with Normal blend + opacity 1.0.
        let mask_tree = DisplayTree {
            root: DisplayNode::Group {
                blend_mode: BlendMode::Normal,
                clip: None,
                opacity: 1.0,
                isolated: true,
                knockout: false,
                soft_mask: None,
                children: vec![DisplayNode::Path {
                    ops: vec![
                        PathOp::MoveTo { x: 0.0, y: 0.0 },
                        PathOp::LineTo { x: 50.0, y: 0.0 },
                        PathOp::LineTo { x: 50.0, y: 50.0 },
                        PathOp::Close,
                    ],
                    style: PathStyle {
                        fill: Some(FillRule::NonZero),
                        ..PathStyle::default()
                    },
                    matrix: Matrix::identity(),
                    fill_color: Some(Color::gray(0.5)),
                    stroke_color: None,
                    fill_color_space: None,
                    stroke_color_space: None,
                    transfer_function: None,
                    overprint: false,
                    overprint_mode: 0,
                }],
            },
        };
        let smask = SoftMask {
            subtype: SoftMaskSubtype::Alpha,
            group: mask_tree,
            backdrop_color: None,
            transfer_function: None,
        };
        let tree = DisplayTree {
            root: DisplayNode::Group {
                blend_mode: BlendMode::Normal,
                clip: None,
                opacity: 1.0,
                isolated: true,
                knockout: false,
                soft_mask: Some(Box::new(smask)),
                children: vec![DisplayNode::Path {
                    ops: vec![
                        PathOp::MoveTo { x: 0.0, y: 0.0 },
                        PathOp::LineTo { x: 100.0, y: 100.0 },
                        PathOp::Close,
                    ],
                    style: PathStyle {
                        fill: Some(FillRule::NonZero),
                        ..PathStyle::default()
                    },
                    matrix: Matrix::identity(),
                    fill_color: Some(Color::rgb(1.0, 0.0, 0.0)),
                    stroke_color: None,
                    fill_color_space: None,
                    stroke_color_space: None,
                    transfer_function: None,
                    overprint: false,
                    overprint_mode: 0,
                }],
            },
        };
        let log = run_mock_renderer(&tree);
        // SMask triggers push_group and pop_group even though blend is Normal + opacity 1.0
        assert!(log.contains(&"push_group".to_string()));
        assert!(log.contains(&"pop_group".to_string()));
        assert!(log.contains(&"fill_path".to_string()));
    }

    #[test]
    fn test_renderer_group_without_smask_unchanged() {
        // Regression: Normal blend + opacity 1.0 + no clip + no SMask = Nothing
        let tree = DisplayTree {
            root: DisplayNode::Group {
                blend_mode: BlendMode::Normal,
                clip: None,
                opacity: 1.0,
                isolated: false,
                knockout: false,
                soft_mask: None,
                children: vec![DisplayNode::Path {
                    ops: vec![
                        PathOp::MoveTo { x: 0.0, y: 0.0 },
                        PathOp::LineTo { x: 50.0, y: 0.0 },
                        PathOp::Close,
                    ],
                    style: PathStyle {
                        fill: Some(FillRule::NonZero),
                        ..PathStyle::default()
                    },
                    matrix: Matrix::identity(),
                    fill_color: Some(Color::rgb(0.0, 1.0, 0.0)),
                    stroke_color: None,
                    fill_color_space: None,
                    stroke_color_space: None,
                    transfer_function: None,
                    overprint: false,
                    overprint_mode: 0,
                }],
            },
        };
        let log = run_mock_renderer(&tree);
        // No group actions — just the fill_path
        assert_eq!(log, vec!["fill_path"]);
    }

    #[test]
    fn test_renderer_with_fallback_fonts_builder() {
        use rpdfium_font::resolved::ResolvedFont;
        use std::sync::Arc;

        let fallback = Arc::new(ResolvedFont {
            font_type: rpdfium_font::font_type::PdfFontType::TrueType,
            base_font_name: "FallbackFont".to_string(),
            widths: vec![],
            default_width: 500,
            first_char: 0,
            ascent: 800,
            descent: -200,
            italic_angle: 0.0,
            is_embedded: false,
            to_unicode: None,
            encoding: rpdfium_font::fx_codepage::FontEncoding::Standard,
            font_data: None,
            cid_to_gid: None,
            wmode: 0,
            vertical_metrics: None,
            cid_cmap: None,
            type3: None,
            weight: None,
            flags: None,
            cid_coding: rpdfium_font::cid_font::CidCoding::Unknown,
            ttc_face_index: 0,
            glyph_outline_cache: std::sync::OnceLock::new(),
        });

        let mut backend = MockBackend::new();
        let mut surface = backend.create_surface(100, 100, &RgbaColor::WHITE);
        let renderer = DisplayRenderer::new(&mut backend, &mut surface, Matrix::identity(), None)
            .with_fallback_fonts(vec![fallback]);
        assert_eq!(renderer.fallback_fonts.len(), 1);
    }

    #[test]
    fn test_renderer_find_fallback_glyph_no_fallbacks() {
        let mut backend = MockBackend::new();
        let mut surface = backend.create_surface(100, 100, &RgbaColor::WHITE);
        let renderer = DisplayRenderer::new(&mut backend, &mut surface, Matrix::identity(), None);
        // No fallback fonts — should return None
        assert!(renderer.find_fallback_glyph(65, 12.0).is_none());
    }

    #[test]
    fn test_renderer_find_fallback_glyph_no_font_data() {
        use rpdfium_font::resolved::ResolvedFont;
        use std::sync::Arc;

        // Fallback font without font_data — char_to_glyph_id returns None
        let fallback = Arc::new(ResolvedFont {
            font_type: rpdfium_font::font_type::PdfFontType::TrueType,
            base_font_name: "NoData".to_string(),
            widths: vec![],
            default_width: 500,
            first_char: 0,
            ascent: 800,
            descent: -200,
            italic_angle: 0.0,
            is_embedded: false,
            to_unicode: None,
            encoding: rpdfium_font::fx_codepage::FontEncoding::Standard,
            font_data: None,
            cid_to_gid: None,
            wmode: 0,
            vertical_metrics: None,
            cid_cmap: None,
            type3: None,
            weight: None,
            flags: None,
            cid_coding: rpdfium_font::cid_font::CidCoding::Unknown,
            ttc_face_index: 0,
            glyph_outline_cache: std::sync::OnceLock::new(),
        });

        let mut backend = MockBackend::new();
        let mut surface = backend.create_surface(100, 100, &RgbaColor::WHITE);
        let renderer = DisplayRenderer::new(&mut backend, &mut surface, Matrix::identity(), None)
            .with_fallback_fonts(vec![fallback]);
        // Fallback font has no font_data, so char_to_glyph_id returns None
        assert!(renderer.find_fallback_glyph(65, 12.0).is_none());
    }

    #[test]
    fn test_renderer_text_missing_glyph_no_fallback_skips() {
        use rpdfium_font::resolved::ResolvedFont;
        use std::sync::Arc;

        // Primary font with no font data — all glyphs are missing
        let font = Arc::new(ResolvedFont {
            font_type: rpdfium_font::font_type::PdfFontType::TrueType,
            base_font_name: "NoGlyphs".to_string(),
            widths: vec![500],
            default_width: 500,
            first_char: 65,
            ascent: 800,
            descent: -200,
            italic_angle: 0.0,
            is_embedded: false,
            to_unicode: None,
            encoding: rpdfium_font::fx_codepage::FontEncoding::Standard,
            font_data: None,
            cid_to_gid: None,
            wmode: 0,
            vertical_metrics: None,
            cid_cmap: None,
            type3: None,
            weight: None,
            flags: None,
            cid_coding: rpdfium_font::cid_font::CidCoding::Unknown,
            ttc_face_index: 0,
            glyph_outline_cache: std::sync::OnceLock::new(),
        });

        let tree = DisplayTree {
            root: DisplayNode::Group {
                blend_mode: BlendMode::Normal,
                clip: None,
                opacity: 1.0,
                isolated: false,
                knockout: false,
                soft_mask: None,
                children: vec![DisplayNode::Text {
                    runs: vec![TextRun {
                        font_name: Name::from("F1"),
                        font_size: 12.0,
                        matrix: Matrix::identity(),
                        text: vec![65],
                        positions: vec![7.2],
                        resolved_font: Some(font),
                        rendering_mode: TextRenderingMode::Fill,
                        rise: 0.0,
                        fill_color: Some(Color::gray(0.0)),
                        stroke_color: None,
                        actual_text: None,
                        type3_glyph_ops: None,
                        actual_text_id: None,
                        is_vertical: false,
                        vert_origins: vec![],
                    }],
                }],
            },
        };
        // No font data, no fallback — should produce no backend calls
        assert!(run_mock_renderer(&tree).is_empty());
    }

    #[test]
    fn test_renderer_luminosity_smask_pushes_group() {
        use rpdfium_page::display::SoftMaskSubtype;
        let mask_tree = DisplayTree {
            root: DisplayNode::Group {
                blend_mode: BlendMode::Normal,
                clip: None,
                opacity: 1.0,
                isolated: true,
                knockout: false,
                soft_mask: None,
                children: vec![DisplayNode::Path {
                    ops: vec![
                        PathOp::MoveTo { x: 0.0, y: 0.0 },
                        PathOp::LineTo { x: 100.0, y: 0.0 },
                        PathOp::LineTo { x: 100.0, y: 100.0 },
                        PathOp::LineTo { x: 0.0, y: 100.0 },
                        PathOp::Close,
                    ],
                    style: PathStyle {
                        fill: Some(FillRule::NonZero),
                        ..PathStyle::default()
                    },
                    matrix: Matrix::identity(),
                    fill_color: Some(Color::rgb(1.0, 1.0, 1.0)),
                    stroke_color: None,
                    fill_color_space: None,
                    stroke_color_space: None,
                    transfer_function: None,
                    overprint: false,
                    overprint_mode: 0,
                }],
            },
        };
        let smask = SoftMask {
            subtype: SoftMaskSubtype::Luminosity,
            group: mask_tree,
            backdrop_color: None,
            transfer_function: None,
        };
        let tree = DisplayTree {
            root: DisplayNode::Group {
                blend_mode: BlendMode::Normal,
                clip: None,
                opacity: 1.0,
                isolated: true,
                knockout: false,
                soft_mask: Some(Box::new(smask)),
                children: Vec::new(),
            },
        };
        let log = run_mock_renderer(&tree);
        assert!(log.contains(&"push_group".to_string()));
        assert!(log.contains(&"pop_group".to_string()));
    }

    // ---- WS3: Text Clipping Tests ----

    /// Helper to create a Type3 font that produces char procs (needed for clip tests).
    fn make_type3_font() -> Arc<rpdfium_font::resolved::ResolvedFont> {
        use rpdfium_font::font_type::PdfFontType;
        use rpdfium_font::resolved::ResolvedFont;
        use rpdfium_font::type3_font::{Type3Encoding, Type3Font};

        let mut char_procs = std::collections::HashMap::new();
        char_procs.insert(Name::from("a"), rpdfium_core::ObjectId::new(10, 0));

        let type3 = Type3Font {
            font_matrix: [0.001, 0.0, 0.0, 0.001, 0.0, 0.0],
            char_procs,
            encoding: Type3Encoding::Differences(vec![(65, Name::from("a"))]),
            first_char: 65,
            last_char: 65,
            widths: vec![600.0],
        };

        Arc::new(ResolvedFont {
            font_type: PdfFontType::Type3,
            base_font_name: "TestType3".to_string(),
            widths: vec![600],
            default_width: 600,
            first_char: 65,
            ascent: 800,
            descent: -200,
            italic_angle: 0.0,
            is_embedded: false,
            to_unicode: None,
            encoding: rpdfium_font::fx_codepage::FontEncoding::Standard,
            font_data: None,
            cid_to_gid: None,
            wmode: 0,
            vertical_metrics: None,
            cid_cmap: None,
            type3: Some(type3),
            weight: None,
            flags: None,
            cid_coding: rpdfium_font::cid_font::CidCoding::Unknown,
            ttc_face_index: 0,
            glyph_outline_cache: std::sync::OnceLock::new(),
        })
    }

    #[test]
    fn test_text_clip_mode4_fill_and_clip() {
        // Mode 4 (FillClip): should fill AND apply clip.
        let font = make_type3_font();
        let tree = DisplayTree {
            root: DisplayNode::Group {
                blend_mode: BlendMode::Normal,
                clip: None,
                opacity: 1.0,
                isolated: false,
                knockout: false,
                soft_mask: None,
                children: vec![DisplayNode::Text {
                    runs: vec![TextRun {
                        font_name: Name::from("F1"),
                        font_size: 12.0,
                        matrix: Matrix::identity(),
                        text: vec![65],
                        positions: vec![7.2],
                        resolved_font: Some(font),
                        rendering_mode: TextRenderingMode::FillClip,
                        rise: 0.0,
                        fill_color: Some(Color::gray(0.0)),
                        stroke_color: None,
                        actual_text: None,
                        type3_glyph_ops: None,
                        actual_text_id: None,
                        is_vertical: false,
                        vert_origins: vec![],
                    }],
                }],
            },
        };
        let log = run_mock_renderer(&tree);
        // Should contain fill_path (for the fill) AND push_clip (for the clip)
        assert!(
            log.contains(&"fill_path".to_string()),
            "expected fill_path in {:?}",
            log
        );
        assert!(
            log.contains(&"push_clip".to_string()),
            "expected push_clip in {:?}",
            log
        );
        // Clip should be popped at leave_group
        assert!(
            log.contains(&"pop_clip".to_string()),
            "expected pop_clip in {:?}",
            log
        );
    }

    #[test]
    fn test_text_clip_mode7_clip_only() {
        // Mode 7 (Clip): no fill, no stroke, clip IS applied.
        let font = make_type3_font();
        let tree = DisplayTree {
            root: DisplayNode::Group {
                blend_mode: BlendMode::Normal,
                clip: None,
                opacity: 1.0,
                isolated: false,
                knockout: false,
                soft_mask: None,
                children: vec![DisplayNode::Text {
                    runs: vec![TextRun {
                        font_name: Name::from("F1"),
                        font_size: 12.0,
                        matrix: Matrix::identity(),
                        text: vec![65],
                        positions: vec![7.2],
                        resolved_font: Some(font),
                        rendering_mode: TextRenderingMode::Clip,
                        rise: 0.0,
                        fill_color: Some(Color::gray(0.0)),
                        stroke_color: None,
                        actual_text: None,
                        type3_glyph_ops: None,
                        actual_text_id: None,
                        is_vertical: false,
                        vert_origins: vec![],
                    }],
                }],
            },
        };
        let log = run_mock_renderer(&tree);
        // Should NOT contain fill_path or stroke_path
        assert!(
            !log.contains(&"fill_path".to_string()),
            "unexpected fill_path in {:?}",
            log
        );
        assert!(
            !log.contains(&"stroke_path".to_string()),
            "unexpected stroke_path in {:?}",
            log
        );
        // Should contain push_clip (for the clip)
        assert!(
            log.contains(&"push_clip".to_string()),
            "expected push_clip in {:?}",
            log
        );
        assert!(
            log.contains(&"pop_clip".to_string()),
            "expected pop_clip in {:?}",
            log
        );
    }

    #[test]
    fn test_text_fill_mode0_no_clip() {
        // Regression: Mode 0 (Fill): fill happens, NO clip applied.
        let font = make_type3_font();
        let tree = DisplayTree {
            root: DisplayNode::Group {
                blend_mode: BlendMode::Normal,
                clip: None,
                opacity: 1.0,
                isolated: false,
                knockout: false,
                soft_mask: None,
                children: vec![DisplayNode::Text {
                    runs: vec![TextRun {
                        font_name: Name::from("F1"),
                        font_size: 12.0,
                        matrix: Matrix::identity(),
                        text: vec![65],
                        positions: vec![7.2],
                        resolved_font: Some(font),
                        rendering_mode: TextRenderingMode::Fill,
                        rise: 0.0,
                        fill_color: Some(Color::gray(0.0)),
                        stroke_color: None,
                        actual_text: None,
                        type3_glyph_ops: None,
                        actual_text_id: None,
                        is_vertical: false,
                        vert_origins: vec![],
                    }],
                }],
            },
        };
        let log = run_mock_renderer(&tree);
        // Should contain fill_path but NOT push_clip
        assert!(log.contains(&"fill_path".to_string()));
        assert!(
            !log.contains(&"push_clip".to_string()),
            "unexpected push_clip in {:?}",
            log
        );
    }

    // ---- T4: Text rendering modes Tr 5 / Tr 6 / Tr 3 ----

    #[test]
    fn test_text_clip_mode5_stroke_clip() {
        // Tr 5 (StrokeClip): stroke text AND add to clipping path — no fill.
        let font = make_type3_font();
        let tree = DisplayTree {
            root: DisplayNode::Group {
                blend_mode: BlendMode::Normal,
                clip: None,
                opacity: 1.0,
                isolated: false,
                knockout: false,
                soft_mask: None,
                children: vec![DisplayNode::Text {
                    runs: vec![TextRun {
                        font_name: Name::from("F1"),
                        font_size: 12.0,
                        matrix: Matrix::identity(),
                        text: vec![65],
                        positions: vec![7.2],
                        resolved_font: Some(font),
                        rendering_mode: TextRenderingMode::StrokeClip,
                        rise: 0.0,
                        fill_color: Some(Color::gray(0.0)),
                        stroke_color: Some(Color::gray(0.0)),
                        actual_text: None,
                        type3_glyph_ops: None,
                        actual_text_id: None,
                        is_vertical: false,
                        vert_origins: vec![],
                    }],
                }],
            },
        };
        let log = run_mock_renderer(&tree);
        // Stroke should be present, fill absent, clip applied and released.
        assert!(
            log.contains(&"stroke_path".to_string()),
            "expected stroke_path in {log:?}"
        );
        assert!(
            !log.contains(&"fill_path".to_string()),
            "unexpected fill_path in {log:?}"
        );
        assert!(
            log.contains(&"push_clip".to_string()),
            "expected push_clip in {log:?}"
        );
        assert!(
            log.contains(&"pop_clip".to_string()),
            "expected pop_clip in {log:?}"
        );
    }

    #[test]
    fn test_text_clip_mode6_fill_stroke_clip() {
        // Tr 6 (FillStrokeClip): fill AND stroke AND add to clipping path.
        let font = make_type3_font();
        let tree = DisplayTree {
            root: DisplayNode::Group {
                blend_mode: BlendMode::Normal,
                clip: None,
                opacity: 1.0,
                isolated: false,
                knockout: false,
                soft_mask: None,
                children: vec![DisplayNode::Text {
                    runs: vec![TextRun {
                        font_name: Name::from("F1"),
                        font_size: 12.0,
                        matrix: Matrix::identity(),
                        text: vec![65],
                        positions: vec![7.2],
                        resolved_font: Some(font),
                        rendering_mode: TextRenderingMode::FillStrokeClip,
                        rise: 0.0,
                        fill_color: Some(Color::gray(0.0)),
                        stroke_color: Some(Color::gray(0.0)),
                        actual_text: None,
                        type3_glyph_ops: None,
                        actual_text_id: None,
                        is_vertical: false,
                        vert_origins: vec![],
                    }],
                }],
            },
        };
        let log = run_mock_renderer(&tree);
        // Both fill and stroke must be present, plus clip.
        assert!(
            log.contains(&"fill_path".to_string()),
            "expected fill_path in {log:?}"
        );
        assert!(
            log.contains(&"stroke_path".to_string()),
            "expected stroke_path in {log:?}"
        );
        assert!(
            log.contains(&"push_clip".to_string()),
            "expected push_clip in {log:?}"
        );
        assert!(
            log.contains(&"pop_clip".to_string()),
            "expected pop_clip in {log:?}"
        );
    }

    #[test]
    fn test_text_clip_mode3_invisible_no_draw_no_clip() {
        // Tr 3 (Invisible): no fill, no stroke, no clip accumulation.
        let font = make_type3_font();
        let tree = DisplayTree {
            root: DisplayNode::Group {
                blend_mode: BlendMode::Normal,
                clip: None,
                opacity: 1.0,
                isolated: false,
                knockout: false,
                soft_mask: None,
                children: vec![DisplayNode::Text {
                    runs: vec![TextRun {
                        font_name: Name::from("F1"),
                        font_size: 12.0,
                        matrix: Matrix::identity(),
                        text: vec![65],
                        positions: vec![7.2],
                        resolved_font: Some(font),
                        rendering_mode: TextRenderingMode::Invisible,
                        rise: 0.0,
                        fill_color: Some(Color::gray(0.0)),
                        stroke_color: None,
                        actual_text: None,
                        type3_glyph_ops: None,
                        actual_text_id: None,
                        is_vertical: false,
                        vert_origins: vec![],
                    }],
                }],
            },
        };
        let log = run_mock_renderer(&tree);
        // Invisible text: no drawing operations, no clip operations.
        assert!(
            !log.contains(&"fill_path".to_string()),
            "unexpected fill_path in {log:?}"
        );
        assert!(
            !log.contains(&"stroke_path".to_string()),
            "unexpected stroke_path in {log:?}"
        );
        assert!(
            !log.contains(&"push_clip".to_string()),
            "unexpected push_clip in {log:?}"
        );
    }

    #[test]
    fn test_transform_path_op_identity() {
        let m = Matrix::identity();
        let op = PathOp::MoveTo { x: 10.0, y: 20.0 };
        let result = transform_path_op(&op, &m);
        match result {
            PathOp::MoveTo { x, y } => {
                assert!((x - 10.0).abs() < 0.01);
                assert!((y - 20.0).abs() < 0.01);
            }
            _ => panic!("expected MoveTo"),
        }
    }

    #[test]
    fn test_transform_path_op_scale() {
        let m = Matrix::from_scale(2.0, 3.0);
        let op = PathOp::LineTo { x: 5.0, y: 10.0 };
        let result = transform_path_op(&op, &m);
        match result {
            PathOp::LineTo { x, y } => {
                assert!((x - 10.0).abs() < 0.01);
                assert!((y - 30.0).abs() < 0.01);
            }
            _ => panic!("expected LineTo"),
        }
    }

    #[test]
    fn test_transform_path_op_close() {
        let m = Matrix::from_scale(2.0, 3.0);
        let result = transform_path_op(&PathOp::Close, &m);
        assert!(matches!(result, PathOp::Close));
    }

    // ---- WS4: Pattern Fill Tests ----

    #[test]
    fn test_path_bounding_box_basic() {
        let ops = vec![
            PathOp::MoveTo { x: 10.0, y: 20.0 },
            PathOp::LineTo { x: 100.0, y: 20.0 },
            PathOp::LineTo { x: 100.0, y: 200.0 },
            PathOp::LineTo { x: 10.0, y: 200.0 },
            PathOp::Close,
        ];
        let bbox = path_bounding_box(&ops);
        assert_eq!(bbox, [10.0, 20.0, 100.0, 200.0]);
    }

    #[test]
    fn test_path_bounding_box_empty() {
        let bbox = path_bounding_box(&[]);
        assert_eq!(bbox, [0.0, 0.0, 0.0, 0.0]);
    }

    #[test]
    fn test_path_bounding_box_with_curves() {
        let ops = vec![
            PathOp::MoveTo { x: 0.0, y: 0.0 },
            PathOp::CurveTo {
                x1: 50.0,
                y1: 100.0,
                x2: 150.0,
                y2: 100.0,
                x3: 200.0,
                y3: 0.0,
            },
        ];
        let bbox = path_bounding_box(&ops);
        assert_eq!(bbox[0], 0.0);
        assert_eq!(bbox[1], 0.0);
        assert_eq!(bbox[2], 200.0);
        assert_eq!(bbox[3], 100.0);
    }

    #[test]
    fn test_renderer_pattern_fill_clips_and_draws() {
        use rpdfium_page::pattern::{PaintType, TilingPattern, TilingType};

        // Pattern tree: a single red rectangle
        let pattern_tree = DisplayTree {
            root: DisplayNode::Group {
                blend_mode: BlendMode::Normal,
                clip: None,
                opacity: 1.0,
                isolated: true,
                knockout: false,
                soft_mask: None,
                children: vec![DisplayNode::Path {
                    ops: vec![
                        PathOp::MoveTo { x: 0.0, y: 0.0 },
                        PathOp::LineTo { x: 10.0, y: 0.0 },
                        PathOp::LineTo { x: 10.0, y: 10.0 },
                        PathOp::LineTo { x: 0.0, y: 10.0 },
                        PathOp::Close,
                    ],
                    style: PathStyle {
                        fill: Some(FillRule::NonZero),
                        ..PathStyle::default()
                    },
                    matrix: Matrix::identity(),
                    fill_color: Some(Color::rgb(1.0, 0.0, 0.0)),
                    stroke_color: None,
                    fill_color_space: None,
                    stroke_color_space: None,
                    transfer_function: None,
                    overprint: false,
                    overprint_mode: 0,
                }],
            },
        };

        let pattern = TilingPattern {
            paint_type: PaintType::Colored,
            tiling_type: TilingType::ConstantSpacing,
            bbox: [0.0, 0.0, 10.0, 10.0],
            x_step: 10.0,
            y_step: 10.0,
            matrix: Matrix::identity(),
            resources_id: None,
            stream_id: rpdfium_core::ObjectId::new(1, 0),
        };

        let tree = DisplayTree {
            root: DisplayNode::Group {
                blend_mode: BlendMode::Normal,
                clip: None,
                opacity: 1.0,
                isolated: false,
                knockout: false,
                soft_mask: None,
                children: vec![DisplayNode::PatternFill {
                    path_ops: vec![
                        PathOp::MoveTo { x: 0.0, y: 0.0 },
                        PathOp::LineTo { x: 50.0, y: 0.0 },
                        PathOp::LineTo { x: 50.0, y: 50.0 },
                        PathOp::LineTo { x: 0.0, y: 50.0 },
                        PathOp::Close,
                    ],
                    fill_rule: FillRule::NonZero,
                    pattern,
                    pattern_tree: Box::new(pattern_tree),
                    fill_color: None,
                    matrix: Matrix::identity(),
                }],
            },
        };
        let log = run_mock_renderer(&tree);
        // Should clip, draw images (tiles), then pop clip
        assert!(
            log.contains(&"push_clip".to_string()),
            "expected push_clip in {:?}",
            log
        );
        assert!(
            log.contains(&"pop_clip".to_string()),
            "expected pop_clip in {:?}",
            log
        );
    }

    // ---- Image Masking Tests ----

    #[test]
    fn test_apply_image_mask_none_passes_through() {
        use crate::image::{DecodedImage, DecodedImageFormat};

        let img = DecodedImage {
            width: 2,
            height: 2,
            data: vec![100, 200, 50, 255],
            format: DecodedImageFormat::Gray8,
        };
        let result = apply_image_mask(img, None, None, None);
        assert_eq!(result.format, DecodedImageFormat::Gray8);
        assert_eq!(result.data, vec![100, 200, 50, 255]);
    }

    #[test]
    fn test_apply_stencil_mask_gray8() {
        use crate::image::{DecodedImage, DecodedImageFormat};
        use rpdfium_page::display::ImageMask;

        // 2x1 gray image: pixel 0 is nonzero (opaque), pixel 1 is zero (transparent)
        let img = DecodedImage {
            width: 2,
            height: 1,
            data: vec![255, 0],
            format: DecodedImageFormat::Gray8,
        };
        let fill = Color::rgb(1.0, 0.0, 0.0);
        let mask = ImageMask::Stencil;
        let result = apply_image_mask(img, Some(&mask), Some(&fill), None);

        assert_eq!(result.format, DecodedImageFormat::Rgba32);
        assert_eq!(result.data.len(), 8); // 2 pixels * 4 bytes
        // Pixel 0: red fill (nonzero mask)
        assert_eq!(result.data[0], 255); // R
        assert_eq!(result.data[1], 0); // G
        assert_eq!(result.data[2], 0); // B
        assert_eq!(result.data[3], 255); // A
        // Pixel 1: transparent (zero mask)
        assert_eq!(result.data[4], 0);
        assert_eq!(result.data[5], 0);
        assert_eq!(result.data[6], 0);
        assert_eq!(result.data[7], 0);
    }

    #[test]
    fn test_apply_stencil_mask_no_fill_uses_black() {
        use crate::image::{DecodedImage, DecodedImageFormat};
        use rpdfium_page::display::ImageMask;

        let img = DecodedImage {
            width: 1,
            height: 1,
            data: vec![128],
            format: DecodedImageFormat::Gray8,
        };
        let mask = ImageMask::Stencil;
        let result = apply_image_mask(img, Some(&mask), None, None);

        assert_eq!(result.format, DecodedImageFormat::Rgba32);
        // Default fill is black
        assert_eq!(result.data[0], 0); // R
        assert_eq!(result.data[1], 0); // G
        assert_eq!(result.data[2], 0); // B
        assert_eq!(result.data[3], 255); // A
    }

    #[test]
    fn test_apply_color_key_mask_gray8() {
        use crate::image::{DecodedImage, DecodedImageFormat};
        use rpdfium_page::display::ImageMask;

        // 3 pixels: gray values 100, 150, 200
        // Mask range: [100, 160] → pixels 0 and 1 should be transparent
        let img = DecodedImage {
            width: 3,
            height: 1,
            data: vec![100, 150, 200],
            format: DecodedImageFormat::Gray8,
        };
        let mask = ImageMask::ColorKey {
            ranges: vec![[100, 160]],
        };
        let result = apply_image_mask(img, Some(&mask), None, None);

        assert_eq!(result.format, DecodedImageFormat::Rgba32);
        // Pixel 0 (100): in range → transparent
        assert_eq!(result.data[3], 0);
        // Pixel 1 (150): in range → transparent
        assert_eq!(result.data[7], 0);
        // Pixel 2 (200): out of range → opaque
        assert_eq!(result.data[11], 255);
    }

    #[test]
    fn test_apply_color_key_mask_rgb24() {
        use crate::image::{DecodedImage, DecodedImageFormat};
        use rpdfium_page::display::ImageMask;

        // 2 pixels RGB: (255, 0, 0) and (0, 255, 0)
        // Mask ranges: R=[200,255], G=[0,10], B=[0,10] → only first pixel matches
        let img = DecodedImage {
            width: 2,
            height: 1,
            data: vec![255, 0, 0, 0, 255, 0],
            format: DecodedImageFormat::Rgb24,
        };
        let mask = ImageMask::ColorKey {
            ranges: vec![[200, 255], [0, 10], [0, 10]],
        };
        let result = apply_image_mask(img, Some(&mask), None, None);

        assert_eq!(result.format, DecodedImageFormat::Rgba32);
        // Pixel 0: matches all ranges → transparent
        assert_eq!(result.data[0], 255); // R preserved
        assert_eq!(result.data[3], 0); // A = 0
        // Pixel 1: G=255 doesn't match [0,10] → opaque
        assert_eq!(result.data[4], 0); // R
        assert_eq!(result.data[5], 255); // G
        assert_eq!(result.data[7], 255); // A = 255
    }

    #[test]
    fn test_apply_explicit_mask_passes_through() {
        use crate::image::{DecodedImage, DecodedImageFormat};
        use rpdfium_page::display::ImageMask;

        let img = DecodedImage {
            width: 1,
            height: 1,
            data: vec![128],
            format: DecodedImageFormat::Gray8,
        };
        let mask = ImageMask::ExplicitMask {
            mask_object_id: rpdfium_core::ObjectId::new(5, 0),
        };
        let result = apply_image_mask(img, Some(&mask), None, None);

        // ExplicitMask without decoder passes through unchanged
        assert_eq!(result.format, DecodedImageFormat::Gray8);
        assert_eq!(result.data, vec![128]);
    }

    #[test]
    fn test_apply_soft_mask_passes_through() {
        use crate::image::{DecodedImage, DecodedImageFormat};
        use rpdfium_page::display::ImageMask;

        let img = DecodedImage {
            width: 1,
            height: 1,
            data: vec![64, 128, 192],
            format: DecodedImageFormat::Rgb24,
        };
        let mask = ImageMask::SoftMask {
            smask_object_id: rpdfium_core::ObjectId::new(6, 0),
            matte: None,
        };
        let result = apply_image_mask(img, Some(&mask), None, None);

        // SoftMask without decoder passes through unchanged
        assert_eq!(result.format, DecodedImageFormat::Rgb24);
        assert_eq!(result.data, vec![64, 128, 192]);
    }

    #[test]
    fn test_renderer_pattern_fill_with_non_identity_matrix() {
        use rpdfium_page::pattern::{PaintType, TilingPattern, TilingType};

        let pattern_tree = DisplayTree {
            root: DisplayNode::Group {
                blend_mode: BlendMode::Normal,
                clip: None,
                opacity: 1.0,
                isolated: true,
                knockout: false,
                soft_mask: None,
                children: vec![],
            },
        };

        // Pattern with 2x scale matrix
        let pattern = TilingPattern {
            paint_type: PaintType::Colored,
            tiling_type: TilingType::ConstantSpacing,
            bbox: [0.0, 0.0, 5.0, 5.0],
            x_step: 5.0,
            y_step: 5.0,
            matrix: Matrix::from_scale(2.0, 2.0),
            resources_id: None,
            stream_id: rpdfium_core::ObjectId::new(1, 0),
        };

        let tree = DisplayTree {
            root: DisplayNode::Group {
                blend_mode: BlendMode::Normal,
                clip: None,
                opacity: 1.0,
                isolated: false,
                knockout: false,
                soft_mask: None,
                children: vec![DisplayNode::PatternFill {
                    path_ops: vec![
                        PathOp::MoveTo { x: 0.0, y: 0.0 },
                        PathOp::LineTo { x: 20.0, y: 0.0 },
                        PathOp::LineTo { x: 20.0, y: 20.0 },
                        PathOp::LineTo { x: 0.0, y: 20.0 },
                        PathOp::Close,
                    ],
                    fill_rule: FillRule::EvenOdd,
                    pattern,
                    pattern_tree: Box::new(pattern_tree),
                    fill_color: None,
                    matrix: Matrix::identity(),
                }],
            },
        };
        let log = run_mock_renderer(&tree);
        // Should still clip and tile
        assert!(
            log.contains(&"push_clip".to_string()),
            "expected push_clip in {:?}",
            log
        );
        assert!(
            log.contains(&"pop_clip".to_string()),
            "expected pop_clip in {:?}",
            log
        );
    }

    // ---- Transfer Function Tests ----

    #[test]
    fn test_apply_transfer_identity_no_change() {
        use rpdfium_page::function::TransferFunction;
        let mut color = RgbaColor {
            r: 128,
            g: 64,
            b: 200,
            a: 255,
        };
        apply_transfer(&mut color, &TransferFunction::Identity);
        assert_eq!(color.r, 128);
        assert_eq!(color.g, 64);
        assert_eq!(color.b, 200);
        assert_eq!(color.a, 255);
    }

    #[test]
    fn test_apply_transfer_single_function() {
        use rpdfium_page::function::{PdfFunction, TransferFunction};
        // Invert function: f(x) = 1 - x
        let func = PdfFunction::Type2 {
            domain: [0.0, 1.0],
            range: vec![],
            c0: vec![1.0],
            c1: vec![0.0],
            n: 1.0,
        };
        let tf = TransferFunction::Single(func);
        let mut color = RgbaColor {
            r: 0,
            g: 255,
            b: 128,
            a: 200,
        };
        apply_transfer(&mut color, &tf);
        // r=0 -> f(0) = 1.0 -> 255
        assert_eq!(color.r, 255);
        // g=255 -> f(1) = 0.0 -> 0
        assert_eq!(color.g, 0);
        // b=128 -> f(~0.502) = ~0.498 -> ~127
        assert!((color.b as i32 - 127).abs() <= 1);
        // Alpha unchanged
        assert_eq!(color.a, 200);
    }

    #[test]
    fn test_apply_transfer_per_component() {
        use rpdfium_page::function::{PdfFunction, TransferFunction};
        // R: identity; G: always 1.0; B: always 0.0
        let r_fn = PdfFunction::Type2 {
            domain: [0.0, 1.0],
            range: vec![],
            c0: vec![0.0],
            c1: vec![1.0],
            n: 1.0,
        };
        let g_fn = PdfFunction::Type2 {
            domain: [0.0, 1.0],
            range: vec![],
            c0: vec![1.0],
            c1: vec![1.0],
            n: 1.0,
        };
        let b_fn = PdfFunction::Type2 {
            domain: [0.0, 1.0],
            range: vec![],
            c0: vec![0.0],
            c1: vec![0.0],
            n: 1.0,
        };
        let k_fn = PdfFunction::Type2 {
            domain: [0.0, 1.0],
            range: vec![],
            c0: vec![0.0],
            c1: vec![1.0],
            n: 1.0,
        };
        let tf = TransferFunction::PerComponent {
            r: Box::new(r_fn),
            g: Box::new(g_fn),
            b: Box::new(b_fn),
            k: Box::new(k_fn),
        };
        let mut color = RgbaColor {
            r: 128,
            g: 128,
            b: 128,
            a: 255,
        };
        apply_transfer(&mut color, &tf);
        // R: identity at 128/255 ~0.502 -> ~128
        assert!((color.r as i32 - 128).abs() <= 1);
        // G: always 1.0 -> 255
        assert_eq!(color.g, 255);
        // B: always 0.0 -> 0
        assert_eq!(color.b, 0);
        // Alpha unchanged
        assert_eq!(color.a, 255);
    }

    #[test]
    fn test_transfer_function_identity_default_graphics_state() {
        // GraphicsState defaults to None (no transfer function)
        let gs = rpdfium_page::GraphicsState::default();
        assert!(gs.transfer_function.is_none());
    }

    #[test]
    fn test_apply_transfer_identity_sampling_256() {
        use rpdfium_page::function::TransferFunction;
        // All 256 input values should round-trip through identity TF unchanged
        for v in 0..=255u8 {
            let mut color = RgbaColor {
                r: v,
                g: v,
                b: v,
                a: v,
            };
            apply_transfer(&mut color, &TransferFunction::Identity);
            assert_eq!(color.r, v, "r mismatch at {v}");
            assert_eq!(color.g, v, "g mismatch at {v}");
            assert_eq!(color.b, v, "b mismatch at {v}");
            assert_eq!(color.a, v, "a should be unchanged at {v}");
        }
    }

    #[test]
    fn test_apply_transfer_per_component_rgb_independent() {
        use rpdfium_page::function::{PdfFunction, TransferFunction};
        // R: always 0.0; G: identity; B: always 1.0
        let r_fn = PdfFunction::Type2 {
            domain: [0.0, 1.0],
            range: vec![],
            c0: vec![0.0],
            c1: vec![0.0],
            n: 1.0,
        };
        let g_fn = PdfFunction::Type2 {
            domain: [0.0, 1.0],
            range: vec![],
            c0: vec![0.0],
            c1: vec![1.0],
            n: 1.0,
        };
        let b_fn = PdfFunction::Type2 {
            domain: [0.0, 1.0],
            range: vec![],
            c0: vec![1.0],
            c1: vec![1.0],
            n: 1.0,
        };
        let k_fn = PdfFunction::Type2 {
            domain: [0.0, 1.0],
            range: vec![],
            c0: vec![0.0],
            c1: vec![1.0],
            n: 1.0,
        };
        let tf = TransferFunction::PerComponent {
            r: Box::new(r_fn),
            g: Box::new(g_fn),
            b: Box::new(b_fn),
            k: Box::new(k_fn),
        };
        let mut color = RgbaColor {
            r: 200,
            g: 100,
            b: 50,
            a: 180,
        };
        apply_transfer(&mut color, &tf);
        // R: always 0
        assert_eq!(color.r, 0);
        // G: identity at 100/255 ~0.392 → ~100
        assert!((color.g as i32 - 100).abs() <= 1);
        // B: always 1.0 → 255
        assert_eq!(color.b, 255);
        // Alpha unchanged
        assert_eq!(color.a, 180);
    }

    #[test]
    fn test_apply_transfer_zero_alpha_preserved() {
        use rpdfium_page::function::{PdfFunction, TransferFunction};
        // Invert function that would change alpha if it were applied
        let func = PdfFunction::Type2 {
            domain: [0.0, 1.0],
            range: vec![],
            c0: vec![1.0],
            c1: vec![0.0],
            n: 1.0,
        };
        let tf = TransferFunction::Single(func);
        let mut color = RgbaColor {
            r: 128,
            g: 128,
            b: 128,
            a: 0,
        };
        apply_transfer(&mut color, &tf);
        // Alpha must remain 0 — TF does NOT modify alpha
        assert_eq!(color.a, 0);
        // RGB inverted: 128/255 ~0.502 → 1-0.502=0.498 → ~127
        assert!((color.r as i32 - 127).abs() <= 1);
    }

    #[test]
    fn test_apply_transfer_boundary_values() {
        use rpdfium_page::function::{PdfFunction, TransferFunction};
        // Identity-like function: f(x) = x
        let func = PdfFunction::Type2 {
            domain: [0.0, 1.0],
            range: vec![],
            c0: vec![0.0],
            c1: vec![1.0],
            n: 1.0,
        };
        let tf = TransferFunction::Single(func);
        let mut color = RgbaColor {
            r: 0,
            g: 255,
            b: 1,
            a: 42,
        };
        apply_transfer(&mut color, &tf);
        // r=0 → f(0)=0 → 0: no underflow
        assert_eq!(color.r, 0);
        // g=255 → f(1)=1 → 255: no overflow
        assert_eq!(color.g, 255);
        // b=1 → f(1/255) ≈ 0.00392 → 0.00392*255 ≈ 1.0 → 1
        assert!((color.b as i32 - 1).abs() <= 1);
        // Alpha unchanged
        assert_eq!(color.a, 42);
    }

    // -----------------------------------------------------------------------
    // Rasterized glyph cache integration tests
    // -----------------------------------------------------------------------

    #[test]
    fn test_renderer_has_raster_cache() {
        let mut backend = MockBackend::new();
        let mut surface = backend.create_surface(100, 100, &RgbaColor::WHITE);
        let renderer = DisplayRenderer::new(&mut backend, &mut surface, Matrix::identity(), None);
        // The raster cache should be initialized and empty
        assert!(renderer.raster_cache.is_empty());
    }

    #[test]
    fn test_rasterize_glyph_alpha_simple_rect() {
        // A simple rectangle glyph outline
        let ops = vec![
            PathOp::MoveTo { x: 0.0, y: 0.0 },
            PathOp::LineTo { x: 100.0, y: 0.0 },
            PathOp::LineTo { x: 100.0, y: 100.0 },
            PathOp::LineTo { x: 0.0, y: 100.0 },
            PathOp::Close,
        ];
        let result = super::rasterize_glyph_alpha(&ops, 0.1, 10, 256);
        assert!(result.is_some());
        let glyph = result.unwrap();
        assert!(glyph.width > 0);
        assert!(glyph.height > 0);
        assert_eq!(glyph.alpha.len(), (glyph.width * glyph.height) as usize);
        // Some pixels should be non-zero (the fill)
        assert!(glyph.alpha.iter().any(|&a| a > 0));
    }

    #[test]
    fn test_rasterize_glyph_alpha_empty_ops() {
        let result = super::rasterize_glyph_alpha(&[], 1.0, 12, 256);
        assert!(result.is_none());
    }

    #[test]
    fn test_rasterize_glyph_alpha_zero_dim() {
        let ops = vec![
            PathOp::MoveTo { x: 0.0, y: 0.0 },
            PathOp::LineTo { x: 10.0, y: 10.0 },
        ];
        let result = super::rasterize_glyph_alpha(&ops, 1.0, 12, 0);
        assert!(result.is_none());
    }

    // -----------------------------------------------------------------------
    // ExplicitMask with a real decoder
    // -----------------------------------------------------------------------

    /// A mock ImageDecoder that returns a fixed grayscale mask image.
    struct MockImageDecoder {
        /// The mask image returned when any object is decoded.
        mask_data: Vec<u8>,
        mask_width: u32,
        mask_height: u32,
    }

    impl crate::image::ImageDecoder for MockImageDecoder {
        fn decode_image(
            &self,
            _image_ref: &rpdfium_graphics::ImageRef,
            _matrix: &Matrix,
        ) -> Result<crate::image::DecodedImage, crate::error::RenderError> {
            Ok(crate::image::DecodedImage {
                width: self.mask_width,
                height: self.mask_height,
                data: self.mask_data.clone(),
                format: crate::image::DecodedImageFormat::Gray8,
            })
        }

        fn decode_inline_image(
            &self,
            _properties: &std::collections::HashMap<rpdfium_core::Name, rpdfium_parser::Operand>,
            _data: &[u8],
            _matrix: &Matrix,
        ) -> Result<crate::image::DecodedImage, crate::error::RenderError> {
            Err(crate::error::RenderError::ImageDecode(
                "not supported".to_string(),
            ))
        }
    }

    #[test]
    fn test_apply_explicit_mask_with_decoder_applies_alpha() {
        use crate::image::{DecodedImage, DecodedImageFormat};
        use rpdfium_page::display::ImageMask;

        // 2x2 RGB image (all white)
        let img = DecodedImage {
            width: 2,
            height: 2,
            data: vec![
                255, 255, 255, // pixel (0,0)
                255, 255, 255, // pixel (1,0)
                255, 255, 255, // pixel (0,1)
                255, 255, 255, // pixel (1,1)
            ],
            format: DecodedImageFormat::Rgb24,
        };

        // Mask: pixel (0,0)=0 (transparent), (1,0)=128 (semi), (0,1)=255 (opaque), (1,1)=0
        let decoder = MockImageDecoder {
            mask_data: vec![0, 128, 255, 0],
            mask_width: 2,
            mask_height: 2,
        };

        let mask = ImageMask::ExplicitMask {
            mask_object_id: rpdfium_core::ObjectId::new(99, 0),
        };

        let result = apply_image_mask(img, Some(&mask), None, Some(&decoder));

        assert_eq!(result.format, DecodedImageFormat::Rgba32);
        assert_eq!(result.width, 2);
        assert_eq!(result.height, 2);
        // 4 pixels * 4 bytes = 16 bytes
        assert_eq!(result.data.len(), 16);

        // pixel (0,0): alpha = 0 (mask=0 → transparent)
        assert_eq!(result.data[3], 0);
        // pixel (1,0): alpha = 128 (mask=128 → semi-transparent)
        assert_eq!(result.data[7], 128);
        // pixel (0,1): alpha = 255 (mask=255 → fully opaque)
        assert_eq!(result.data[11], 255);
        // pixel (1,1): alpha = 0 (mask=0 → transparent)
        assert_eq!(result.data[15], 0);
    }

    #[test]
    fn test_apply_explicit_mask_with_decoder_scales_to_image_size() {
        use crate::image::{DecodedImage, DecodedImageFormat};
        use rpdfium_page::display::ImageMask;

        // 4x4 gray image
        let img = DecodedImage {
            width: 4,
            height: 4,
            data: vec![200u8; 16],
            format: DecodedImageFormat::Gray8,
        };

        // 2x2 mask (will be scaled to 4x4 via nearest-neighbor)
        // Top-left=255, top-right=0, bottom-left=0, bottom-right=255
        let decoder = MockImageDecoder {
            mask_data: vec![255, 0, 0, 255],
            mask_width: 2,
            mask_height: 2,
        };

        let mask = ImageMask::ExplicitMask {
            mask_object_id: rpdfium_core::ObjectId::new(100, 0),
        };

        let result = apply_image_mask(img, Some(&mask), None, Some(&decoder));

        assert_eq!(result.format, DecodedImageFormat::Rgba32);
        // 4x4 pixels, each 4 bytes
        assert_eq!(result.data.len(), 64);

        // Top-left quadrant (pixels 0,0 and 1,0 on row 0) should have mask=255
        assert_eq!(result.data[3], 255); // pixel (0,0)
        assert_eq!(result.data[7], 255); // pixel (1,0)
        // Top-right quadrant (pixels 2,0 and 3,0 on row 0) should have mask=0
        assert_eq!(result.data[11], 0); // pixel (2,0)
        assert_eq!(result.data[15], 0); // pixel (3,0)
    }

    // -----------------------------------------------------------------------
    // SMask backdrop color tests
    // -----------------------------------------------------------------------

    #[test]
    fn test_smask_backdrop_color_converts_to_rgba() {
        use rpdfium_page::display::{SoftMask, SoftMaskSubtype};

        // Test the backdrop color conversion logic directly.
        // With backdrop [1.0, 1.0, 1.0] (white), the surface should start white.
        let sm = SoftMask {
            subtype: SoftMaskSubtype::Luminosity,
            group: DisplayTree {
                root: DisplayNode::Group {
                    blend_mode: BlendMode::Normal,
                    clip: None,
                    opacity: 1.0,
                    isolated: true,
                    knockout: false,
                    soft_mask: None,
                    children: vec![],
                },
            },
            backdrop_color: Some(vec![1.0, 1.0, 1.0]),
            transfer_function: None,
        };

        // Use MockBackend which returns zeroed pixels (100x100).
        // With a white backdrop for luminosity, all pixels should report
        // full luminosity (white backdrop → lum ≈ 255).
        let mut backend = MockBackend::new();
        let surface = backend.create_surface(100, 100, &RgbaColor::WHITE);
        let result = render_soft_mask_alpha(&mut backend, &surface, &sm, Matrix::identity(), None);

        // render_soft_mask_alpha should succeed
        assert!(result.is_some());
        let (alpha, w, h) = result.unwrap();
        assert_eq!(w, 100);
        assert_eq!(h, 100);
        assert_eq!(alpha.len(), 10_000);
        // MockBackend.surface_pixels returns all zeros, so with luminosity
        // on a zero pixel surface, alpha should all be 0.
        // The point of the test is to verify the code runs without error
        // when backdrop_color is Some.
    }

    #[test]
    fn test_smask_no_backdrop_uses_transparent() {
        use rpdfium_page::display::{SoftMask, SoftMaskSubtype};

        let sm = SoftMask {
            subtype: SoftMaskSubtype::Alpha,
            group: DisplayTree {
                root: DisplayNode::Group {
                    blend_mode: BlendMode::Normal,
                    clip: None,
                    opacity: 1.0,
                    isolated: true,
                    knockout: false,
                    soft_mask: None,
                    children: vec![],
                },
            },
            backdrop_color: None,
            transfer_function: None,
        };

        let mut backend = MockBackend::new();
        let surface = backend.create_surface(100, 100, &RgbaColor::WHITE);
        let result = render_soft_mask_alpha(&mut backend, &surface, &sm, Matrix::identity(), None);

        assert!(result.is_some());
        let (alpha, w, h) = result.unwrap();
        assert_eq!(w, 100);
        assert_eq!(h, 100);
        // All alpha should be 0 since surface_pixels returns zeros
        assert!(alpha.iter().all(|&a| a == 0));
    }

    #[test]
    fn test_smask_backdrop_single_component_grayscale() {
        use rpdfium_page::display::{SoftMask, SoftMaskSubtype};

        // Single-component backdrop [0.5] → should replicate to R=G=B
        let sm = SoftMask {
            subtype: SoftMaskSubtype::Alpha,
            group: DisplayTree {
                root: DisplayNode::Group {
                    blend_mode: BlendMode::Normal,
                    clip: None,
                    opacity: 1.0,
                    isolated: true,
                    knockout: false,
                    soft_mask: None,
                    children: vec![],
                },
            },
            backdrop_color: Some(vec![0.5]),
            transfer_function: None,
        };

        let mut backend = MockBackend::new();
        let surface = backend.create_surface(10, 10, &RgbaColor::WHITE);
        let result = render_soft_mask_alpha(&mut backend, &surface, &sm, Matrix::identity(), None);

        assert!(result.is_some());
    }
}