stet_render/

skia_device.rs

// stet - A PostScript Interpreter
// Copyright (c) 2026 Scott Bowman
// SPDX-License-Identifier: Apache-2.0 OR MIT

//! tiny-skia implementation of the `OutputDevice` trait.

use std::collections::{HashMap, HashSet};
use std::hash::{Hash, Hasher};
use std::sync::{Arc, Mutex};

#[cfg(feature = "parallel")]
use rayon::prelude::*;
use stet_tiny_skia::{
    BlendMode, Color, FillRule as SkiaFillRule, LineCap as SkiaLineCap, LineJoin as SkiaLineJoin,
    Mask, Paint, PathBuilder, Pixmap, Stroke, StrokeDash, Transform,
};

use stet_core::device::OutputDevice;
use stet_fonts::geometry::{Matrix, PathSegment, PsPath};
use stet_graphics::color::{DeviceColor, FillRule, LineCap, LineJoin};
use stet_graphics::device::{
    AxialShadingParams, ClipParams, FillParams, ImageColorSpace, ImageParams, MeshShadingParams,
    PageSinkFactory, PatchShadingParams, RadialShadingParams, ShadingColorSpace, ShadingVertex,
    StrokeParams, TintLookupTable,
};
use stet_graphics::icc::IccCache;
use stet_graphics::layer_set::LayerSet;

/// Axis-aligned rectangle in device pixel coordinates.
#[derive(Clone, Copy)]
struct ClipRect {
    x0: u32,
    y0: u32, // top-left (inclusive)
    x1: u32,
    y1: u32, // bottom-right (exclusive)
}

impl ClipRect {
    /// Intersect two rectangles. Result may be empty.
    fn intersect(&self, other: &ClipRect) -> ClipRect {
        ClipRect {
            x0: self.x0.max(other.x0),
            y0: self.y0.max(other.y0),
            x1: self.x1.min(other.x1),
            y1: self.y1.min(other.y1),
        }
    }

    fn is_empty(&self) -> bool {
        self.x0 >= self.x1 || self.y0 >= self.y1
    }

    /// True if this rect covers the entire page.
    fn is_full_page(&self, w: u32, h: u32) -> bool {
        self.x0 == 0 && self.y0 == 0 && self.x1 == w && self.y1 == h
    }

    /// Create a mask with 255 inside the rect, 0 outside.
    fn make_mask(self, w: u32, h: u32) -> Option<Mask> {
        if self.is_empty() {
            return None;
        }
        let mut mask = Mask::new(w, h)?;
        let data = mask.data_mut();
        let stride = w as usize;
        for y in self.y0..self.y1 {
            let row_start = y as usize * stride + self.x0 as usize;
            let row_end = y as usize * stride + self.x1 as usize;
            data[row_start..row_end].fill(255);
        }
        Some(mask)
    }
}

/// Clip region: either a simple rectangle (fast) or a full rasterized mask.
enum ClipRegion {
    Rect(ClipRect),
    Mask(Mask),
}

/// tiny-skia based raster device.
pub struct SkiaDevice {
    pixmap: Pixmap,
    /// Page dimensions in device pixels. Stored separately so we can shrink
    /// the pixmap during banded rendering without losing page size info.
    page_w: u32,
    page_h: u32,
    /// Device resolution in DPI (for hairline width decisions).
    dpi: f64,
    clip_region: Option<ClipRegion>,
    /// Cache of rasterized clip masks keyed by path hash.
    /// Only paths seen more than once are cached (cache-on-second-sight).
    clip_mask_cache: HashMap<u64, Mask>,
    clip_mask_seen: HashSet<u64>,
    /// Recycled mask buffer to avoid repeated alloc/dealloc of large masks.
    spare_mask: Option<Mask>,
    /// Receiver for background render result (pipelined multi-page rendering).
    /// Uses rayon::spawn + oneshot channel to avoid OS thread spawn overhead.
    pending_render: Option<std::sync::mpsc::Receiver<Result<(), String>>>,
    /// Factory for creating page sinks (PNG, viewer, etc.).
    sink_factory: Box<dyn PageSinkFactory>,
    /// Raw bytes of the system CMYK ICC profile (for building render-thread IccCaches).
    system_cmyk_bytes: Option<std::sync::Arc<Vec<u8>>>,
    /// Transient IccCache used during non-banded replay_to_device rendering.
    render_icc_cache: Option<IccCache>,
    /// Disable anti-aliasing for all fill/stroke operations (matches GhostScript).
    no_aa: bool,
    /// Route `replay_and_show` through the viewport code path instead of the
    /// banded full-page path. Used by `--device viewport-png` to audit the
    /// viewport pipeline against the banded PNG baselines — same display list,
    /// different culling/epoch logic, same expected output.
    use_viewport_path: bool,
    /// OCG visibility overrides applied to every render that consults
    /// the layer system. Defaults to empty (every layer falls back to
    /// its `default_visible`); a consumer building a layer panel can
    /// install an explicit set via `set_layer_set`.
    layer_set: LayerSet,
}

impl SkiaDevice {
    /// Create a new device with the given page dimensions and default PNG output.
    ///
    /// Defers the full-page pixmap allocation — only a 1×1 placeholder is
    /// created here. The full pixmap is allocated lazily in `replay_and_show`
    /// only when the non-banded rendering path is needed.
    pub fn new(width: u32, height: u32) -> Self {
        Self::with_sink_factory(width, height, Box::new(crate::PngSinkFactory))
    }

    /// Create a new device with a custom page sink factory.
    pub fn with_sink_factory(
        width: u32,
        height: u32,
        sink_factory: Box<dyn PageSinkFactory>,
    ) -> Self {
        // Only the lower bound is enforced here, and deliberately so.
        //
        // These dimensions are `page_points * dpi / 72`, and the two factors
        // have different provenance: the points come from the file and are
        // untrusted, but the DPI is the caller's explicit request. Capping the
        // product punishes the caller for the file's exaggeration — a 1200 dpi
        // prepress proof of a large-format page is a legitimate gigapixel
        // render, and refusing it is worse than the attack it prevents. The
        // page size is bounded upstream, in points, where the untrusted value
        // actually enters (see `MAX_PAGE_SIZE_POINTS`).
        //
        // Zero, on the other hand, is never meaningful: `Pixmap::new` returns
        // `None` for a zero dimension and the call below used to `.expect()`
        // on it, so `<< /PageSize [-1 -1] >> setpagedevice` panicked the
        // renderer outright.
        let width = width.max(1);
        let height = height.max(1);
        // Estimate DPI from page height (assumes ~792pt US Letter as reference).
        // Close enough for hairline width threshold decisions.
        let dpi = height as f64 * 72.0 / 792.0;

        // Start with a tiny placeholder. The full-page pixmap is allocated
        // lazily only when the non-banded path is used (small pages / low DPI).
        // For banded rendering, band-sized pixmaps are created in replay_and_show.
        let pixmap = Pixmap::new(1, 1).expect("Failed to create placeholder pixmap");
        Self {
            pixmap,
            page_w: width,
            page_h: height,
            dpi,
            clip_region: None,
            clip_mask_cache: HashMap::new(),
            clip_mask_seen: HashSet::new(),
            spare_mask: None,
            pending_render: None,
            sink_factory,
            system_cmyk_bytes: None,
            render_icc_cache: None,
            no_aa: false,
            use_viewport_path: false,
            layer_set: LayerSet::new(),
        }
    }

    /// Route rendering through the viewport pipeline. Used by the visual
    /// test runner's `--device viewport-png` mode.
    pub fn set_use_viewport_path(&mut self, on: bool) {
        self.use_viewport_path = on;
    }

    /// Replace the device's OCG visibility overrides.
    ///
    /// The empty default has every layer fall back to its
    /// `default_visible` baked into the display list. Callers building
    /// a layer panel hand in a populated [`LayerSet`] each render
    /// pass.
    pub fn set_layer_set(&mut self, layer_set: LayerSet) {
        self.layer_set = layer_set;
    }

    /// Read-only view of the device's current OCG visibility overrides.
    pub fn layer_set(&self) -> &LayerSet {
        &self.layer_set
    }

    /// Ensure `self.pixmap` is allocated at full page dimensions.
    /// Called before non-banded rendering which operates on the full pixmap.
    fn ensure_full_pixmap(&mut self) {
        if self.pixmap.width() != self.page_w || self.pixmap.height() != self.page_h {
            // Dimensions are clamped at construction, so this only fails when
            // the allocation itself does — a page large enough to exhaust
            // memory. Keep the existing pixmap and carry on: the page renders
            // wrong, which is what a page that size was always going to do,
            // rather than taking the process down.
            let Some(pixmap) = Pixmap::new(self.page_w, self.page_h) else {
                eprintln!(
                    "Warning: could not allocate a {}x{} page pixmap; \
                     rendering into the existing {}x{} buffer instead",
                    self.page_w,
                    self.page_h,
                    self.pixmap.width(),
                    self.pixmap.height()
                );
                return;
            };
            self.pixmap = pixmap;
            self.pixmap.fill(Color::WHITE);
        }
    }

    /// Get the underlying pixmap (for testing).
    pub fn pixmap(&self) -> &Pixmap {
        &self.pixmap
    }

    /// Set the system CMYK ICC profile bytes for ICC-aware rendering.
    pub fn set_system_cmyk_bytes(&mut self, bytes: std::sync::Arc<Vec<u8>>) {
        self.system_cmyk_bytes = Some(bytes);
    }

    /// Disable anti-aliasing for all fill/stroke operations.
    pub fn set_no_aa(&mut self, no_aa: bool) {
        self.no_aa = no_aa;
    }
}

/// Convert a PostScript `Matrix` to tiny-skia `Transform` (f32).
fn to_transform(m: &Matrix) -> Transform {
    Transform::from_row(
        m.a as f32,
        m.b as f32,
        m.c as f32,
        m.d as f32,
        m.tx as f32,
        m.ty as f32,
    )
}

/// Convert a `DeviceColor` to tiny-skia `Paint`.
fn to_paint(color: &DeviceColor) -> Paint<'static> {
    to_paint_alpha(color, 1.0, 0, false)
}

/// Convert a `DeviceColor` to tiny-skia `Paint` with the given opacity and blend mode.
fn to_paint_alpha(color: &DeviceColor, alpha: f64, blend_mode: u8, no_aa: bool) -> Paint<'static> {
    let mut paint = Paint::default();
    let a = (alpha * 255.0).round().clamp(0.0, 255.0) as u8;
    paint.set_color_rgba8(
        (color.r * 255.0).round().clamp(0.0, 255.0) as u8,
        (color.g * 255.0).round().clamp(0.0, 255.0) as u8,
        (color.b * 255.0).round().clamp(0.0, 255.0) as u8,
        a,
    );
    paint.anti_alias = !no_aa;
    paint.blend_mode = u8_to_blend_mode(blend_mode);
    paint
}

/// Map a blend mode byte (0–15) to the corresponding tiny-skia `BlendMode`.
fn u8_to_blend_mode(mode: u8) -> BlendMode {
    match mode {
        1 => BlendMode::Multiply,
        2 => BlendMode::Screen,
        3 => BlendMode::Overlay,
        4 => BlendMode::Darken,
        5 => BlendMode::Lighten,
        6 => BlendMode::ColorDodge,
        7 => BlendMode::ColorBurn,
        8 => BlendMode::HardLight,
        9 => BlendMode::SoftLight,
        10 => BlendMode::Difference,
        11 => BlendMode::Exclusion,
        12 => BlendMode::Hue,
        13 => BlendMode::Saturation,
        14 => BlendMode::Color,
        15 => BlendMode::Luminosity,
        _ => BlendMode::SourceOver,
    }
}

/// Convert a `PsPath` to tiny-skia `Path`.
/// Maximum coordinate magnitude for path rasterization.
/// Coordinates beyond this cause integer overflow in the scanline rasterizer.
/// 1e6 is well beyond any real page (e.g. 612×792 pt at 600 DPI = ~5100×6600 px)
/// but safely within f32 precision and fixed-point limits.
const MAX_PATH_COORD: f32 = 1e6;

fn build_skia_path(path: &PsPath) -> Option<stet_tiny_skia::Path> {
    let mut pb = PathBuilder::new();

    for seg in &path.segments {
        match seg {
            PathSegment::MoveTo(x, y) => {
                pb.move_to(*x as f32, *y as f32);
            }
            PathSegment::LineTo(x, y) => {
                pb.line_to(*x as f32, *y as f32);
            }
            PathSegment::CurveTo {
                x1,
                y1,
                x2,
                y2,
                x3,
                y3,
            } => {
                pb.cubic_to(
                    *x1 as f32, *y1 as f32, *x2 as f32, *y2 as f32, *x3 as f32, *y3 as f32,
                );
            }
            PathSegment::ClosePath => {
                pb.close();
            }
        }
    }

    let result = pb.finish()?;

    // Reject paths with extreme coordinates that would overflow the scanline
    // rasterizer's integer math. This handles corrupted PDF content streams
    // with garbled coordinates.
    let b = result.bounds();
    if b.left().abs() > MAX_PATH_COORD
        || b.top().abs() > MAX_PATH_COORD
        || b.right().abs() > MAX_PATH_COORD
        || b.bottom().abs() > MAX_PATH_COORD
    {
        return None;
    }

    Some(result)
}

/// Detect degenerate fill paths that have zero extent in one dimension.
///
/// PDFs commonly draw table grid lines as zero-width or zero-height filled
/// rectangles (e.g., `8 0 1031 0 re f`). Since these have no area, the
/// fill rasterizer produces zero pixels. This function detects such paths
/// so they can be rendered as hairline strokes instead.
///
/// The check is performed in the path's own coordinate space (pre-transform)
/// using a very tight epsilon, so only paths with *exactly* zero extent in
/// one dimension are detected. Paths containing curves are never degenerate
/// — only MoveTo/LineTo/ClosePath segments qualify.
fn is_degenerate_fill(path: &PsPath) -> bool {
    let mut x_min = f64::INFINITY;
    let mut x_max = f64::NEG_INFINITY;
    let mut y_min = f64::INFINITY;
    let mut y_max = f64::NEG_INFINITY;

    for seg in &path.segments {
        let (x, y) = match seg {
            PathSegment::MoveTo(x, y) | PathSegment::LineTo(x, y) => (*x, *y),
            // Paths with curves are real shapes, not degenerate lines
            PathSegment::CurveTo { .. } => return false,
            PathSegment::ClosePath => continue,
        };
        x_min = x_min.min(x);
        x_max = x_max.max(x);
        y_min = y_min.min(y);
        y_max = y_max.max(y);
    }

    if x_min > x_max {
        return false; // empty path
    }

    let w = x_max - x_min;
    let h = y_max - y_min;

    // Degenerate if one dimension is exactly zero (within f64 epsilon)
    // while the other has real extent. This catches `re` rects with
    // zero width or height but not legitimate small shapes.
    let eps = 1e-6;
    (w < eps && h > eps) || (h < eps && w > eps)
}

/// Convert a tiny-skia Path back to a PsPath.
/// Used for overprint stroke handling where we convert a stroked outline to a fill.

/// Convert PostScript FillRule to tiny-skia FillRule.
fn to_fill_rule(rule: &FillRule) -> SkiaFillRule {
    match rule {
        FillRule::NonZeroWinding => SkiaFillRule::Winding,
        FillRule::EvenOdd => SkiaFillRule::EvenOdd,
        _ => SkiaFillRule::Winding,
    }
}

/// Convert PostScript LineCap to tiny-skia LineCap.
fn to_line_cap(cap: LineCap) -> SkiaLineCap {
    match cap {
        LineCap::Butt => SkiaLineCap::Butt,
        LineCap::Round => SkiaLineCap::Round,
        LineCap::Square => SkiaLineCap::Square,
        _ => SkiaLineCap::Butt,
    }
}

/// Convert PostScript LineJoin to tiny-skia LineJoin.
fn to_line_join(join: LineJoin) -> SkiaLineJoin {
    match join {
        LineJoin::Miter => SkiaLineJoin::Miter,
        LineJoin::Round => SkiaLineJoin::Round,
        LineJoin::Bevel => SkiaLineJoin::Bevel,
        _ => SkiaLineJoin::Miter,
    }
}

/// Detect if a path is an axis-aligned rectangle. Returns pixel-coordinate ClipRect if so.
/// Handles both CW and CCW winding, with optional trailing ClosePath.
fn detect_rect(path: &PsPath, page_w: u32, page_h: u32) -> Option<ClipRect> {
    let segs = &path.segments;
    // Expect: MoveTo + 3 LineTo + ClosePath (5 segments)
    // or MoveTo + 3 LineTo + LineTo(back to start) + ClosePath (6 segments)
    // or MoveTo + 3 LineTo (4 segments, implicitly closed)
    let (move_to, lines, _has_close) = match segs.len() {
        5 => {
            // MoveTo + 3 LineTo + ClosePath
            if !matches!(segs[4], PathSegment::ClosePath) {
                return None;
            }
            (&segs[0], &segs[1..4], true)
        }
        6 => {
            // MoveTo + 4 LineTo + ClosePath (4th LineTo returns to start)
            if !matches!(segs[5], PathSegment::ClosePath) {
                return None;
            }
            (&segs[0], &segs[1..5], true)
        }
        4 => {
            // MoveTo + 3 LineTo (no explicit close)
            (&segs[0], &segs[1..4], false)
        }
        _ => return None,
    };

    let PathSegment::MoveTo(mx, my) = move_to else {
        return None;
    };

    // Collect all corner points
    let mut pts = vec![(*mx, *my)];
    for seg in lines {
        match seg {
            PathSegment::LineTo(x, y) => pts.push((*x, *y)),
            _ => return None,
        }
    }

    // If 5 points (4 LineTos), last must return to start
    if pts.len() == 5 {
        let (fx, fy) = pts[0];
        let (lx, ly) = pts[4];
        if (fx - lx).abs() > 0.01 || (fy - ly).abs() > 0.01 {
            return None;
        }
        pts.truncate(4);
    }

    // Check axis-aligned: each edge must be horizontal or vertical
    for i in 0..4 {
        let (x1, y1) = pts[i];
        let (x2, y2) = pts[(i + 1) % 4];
        let dx = (x2 - x1).abs();
        let dy = (y2 - y1).abs();
        if dx > 0.01 && dy > 0.01 {
            return None; // diagonal edge
        }
    }

    // Compute bounding box
    let min_x = pts.iter().map(|p| p.0).fold(f64::INFINITY, f64::min);
    let min_y = pts.iter().map(|p| p.1).fold(f64::INFINITY, f64::min);
    let max_x = pts.iter().map(|p| p.0).fold(f64::NEG_INFINITY, f64::max);
    let max_y = pts.iter().map(|p| p.1).fold(f64::NEG_INFINITY, f64::max);

    // Convert to pixel coords: floor for top-left, ceil for bottom-right, clamp to page
    let x0 = (min_x.floor().max(0.0) as u32).min(page_w);
    let y0 = (min_y.floor().max(0.0) as u32).min(page_h);
    let x1 = (max_x.ceil().max(0.0) as u32).min(page_w);
    let y1 = (max_y.ceil().max(0.0) as u32).min(page_h);

    Some(ClipRect { x0, y0, x1, y1 })
}

/// Zero out mask pixels outside the given rectangle bounds.
fn intersect_mask_with_rect(mask: &mut Mask, rect: &ClipRect, w: u32, h: u32) {
    let data = mask.data_mut();
    let stride = w as usize;

    // Zero rows above rect
    if rect.y0 > 0 {
        let end = (rect.y0 as usize * stride).min(data.len());
        data[..end].fill(0);
    }

    // Zero rows below rect
    if rect.y1 < h {
        let start = (rect.y1 as usize * stride).min(data.len());
        data[start..].fill(0);
    }

    // Zero left and right margins within rect rows
    for y in rect.y0..rect.y1.min(h) {
        let row_start = y as usize * stride;
        // Left margin
        if rect.x0 > 0 {
            let end = row_start + rect.x0 as usize;
            data[row_start..end].fill(0);
        }
        // Right margin
        if rect.x1 < w {
            let start = row_start + rect.x1 as usize;
            let end = row_start + stride;
            data[start..end].fill(0);
        }
    }
}

/// Resolve a ClipRegion to an Option<&Mask> for paint operations.
/// Returns `None` if the clip is empty (caller should skip painting).
/// Returns `Some(None)` if no mask is needed (full page or no clip).
/// Returns `Some(Some(&Mask))` if a mask should be applied.
fn resolve_clip_mask<'a>(
    clip_region: &'a Option<ClipRegion>,
    temp_mask: &'a mut Option<Mask>,
    w: u32,
    h: u32,
) -> Option<Option<&'a Mask>> {
    match clip_region {
        None => Some(None),
        Some(ClipRegion::Mask(m)) => Some(Some(m)),
        Some(ClipRegion::Rect(rect)) => {
            if rect.is_empty() {
                return None; // empty clip → skip painting
            }
            if rect.is_full_page(w, h) {
                return Some(None); // full page → no mask needed
            }
            *temp_mask = rect.make_mask(w, h);
            Some(temp_mask.as_ref())
        }
    }
}

/// Hash a PsPath's segments for clip mask caching. Uses bit-exact f64 comparison
/// since paths are already in device space.
fn hash_clip_path(path: &PsPath, fill_rule: &FillRule) -> u64 {
    let mut hasher = std::collections::hash_map::DefaultHasher::new();
    std::mem::discriminant(fill_rule).hash(&mut hasher);
    for seg in &path.segments {
        match seg {
            PathSegment::MoveTo(x, y) => {
                0u8.hash(&mut hasher);
                x.to_bits().hash(&mut hasher);
                y.to_bits().hash(&mut hasher);
            }
            PathSegment::LineTo(x, y) => {
                1u8.hash(&mut hasher);
                x.to_bits().hash(&mut hasher);
                y.to_bits().hash(&mut hasher);
            }
            PathSegment::CurveTo {
                x1,
                y1,
                x2,
                y2,
                x3,
                y3,
            } => {
                2u8.hash(&mut hasher);
                x1.to_bits().hash(&mut hasher);
                y1.to_bits().hash(&mut hasher);
                x2.to_bits().hash(&mut hasher);
                y2.to_bits().hash(&mut hasher);
                x3.to_bits().hash(&mut hasher);
                y3.to_bits().hash(&mut hasher);
            }
            PathSegment::ClosePath => {
                3u8.hash(&mut hasher);
            }
        }
    }
    hasher.finish()
}

/// Pixel-multiply two masks: dst[i] = dst[i] * src[i] / 255.
fn intersect_masks(dst: &mut Mask, src: &Mask) {
    let dst_data = dst.data_mut();
    let src_data = src.data();
    for (d, s) in dst_data.iter_mut().zip(src_data.iter()) {
        *d = ((*d as u16 * *s as u16 + 127) / 255) as u8;
    }
}

// ---- Banded rendering support ----

use stet_graphics::display_list::{DisplayElement, DisplayList};

/// Band-local clip state, rebuilt for each band.
struct BandState {
    clip_region: Option<ClipRegion>,
    spare_mask: Option<Mask>,
    /// Per-band cache (cleared each band since masks are band-sized).
    clip_mask_cache: HashMap<u64, Mask>,
    /// Persists across bands for cache-on-second-sight.
    clip_mask_seen: HashSet<u64>,
    /// Pool of recycled masks to avoid alloc/dealloc (mmap/munmap) per band.
    mask_pool: Vec<Mask>,
    /// Per-pixel CMYK tracking buffer for overprint simulation.
    /// Only allocated when the display list contains overprint elements.
    /// Layout: [C, M, Y, K] as f32 per pixel, band_w * band_h * 4 entries.
    cmyk_buffer: Option<Vec<f32>>,
    /// Per-pixel snapshot of pixmap RGBA *before* the first overprint paint
    /// touched that pixel in this band. Subsequent overprint paints at the
    /// same pixel blend their result against this snapshot instead of the
    /// current (already-overprinted) pixmap, so AA edges of stacked overprints
    /// do not leak earlier colour through later paints.
    /// Lazily allocated on first overprint paint. 4 bytes per pixel.
    op_bg_snapshot: Option<Vec<u8>>,
    /// Parallel to `op_bg_snapshot`: 1 byte per pixel, non-zero iff the
    /// snapshot for that pixel has been captured. Reset to zero over the
    /// paint bbox on non-overprint writes so a later non-overprint fill
    /// establishes a fresh backdrop for subsequent overprints.
    op_touched: Option<Vec<u8>>,
    /// Per-pixel marker for "this pixel's pixmap colour includes spot-
    /// colorant contribution not reflected in `cmyk_buffer`". Set by
    /// DeviceN/Separation paints that include at least one spot colorant
    /// (i.e. `process_cmyk != native_cmyk`). Consulted by CMYK overprint
    /// rendering so the no-op-delta skip only fires on pixels where
    /// preserving the pixmap actually preserves spot colour — other pixels
    /// still go through the ICC(new_cmyk) replace path.
    spot_mask: Option<Vec<u8>>,
}

/// Maximum masks to keep in the recycling pool. Enough to avoid alloc churn
/// without accumulating unbounded memory across bands.
const MAX_POOL_MASKS: usize = 8;

impl BandState {
    /// Recycle all cached masks into the pool, clearing the cache for the next band.
    #[allow(dead_code)]
    fn recycle_cache(&mut self) {
        for (_, mask) in self.clip_mask_cache.drain() {
            if self.mask_pool.len() < MAX_POOL_MASKS {
                self.mask_pool.push(mask);
            }
            // else: drop mask, returning memory to OS
        }
    }

    /// Return a mask to the pool if under capacity, otherwise drop it.
    fn recycle_mask(&mut self, mask: Mask) {
        if self.mask_pool.len() < MAX_POOL_MASKS {
            self.mask_pool.push(mask);
        }
    }

    /// Get a recycled mask or allocate a new one.
    fn take_mask(&mut self, w: u32, h: u32) -> Mask {
        self.spare_mask
            .take()
            .or_else(|| self.mask_pool.pop())
            .unwrap_or_else(|| Mask::new(w, h).expect("Failed to create mask"))
    }

    /// Take (or lazily allocate) the overprint background snapshot and
    /// touched-flag buffers. Caller must pass them back via
    /// `restore_op_buffers`. Layout: snapshot is 4 bytes/pixel (RGBA),
    /// touched is 1 byte/pixel.
    fn take_op_buffers(&mut self, w: u32, h: u32) -> (Vec<u8>, Vec<u8>) {
        let n = w as usize * h as usize;
        let bg = self
            .op_bg_snapshot
            .take()
            .unwrap_or_else(|| vec![0u8; n * 4]);
        let touched = self.op_touched.take().unwrap_or_else(|| vec![0u8; n]);
        (bg, touched)
    }

    /// Put the overprint buffers back after an overprint render pass.
    fn restore_op_buffers(&mut self, bg: Vec<u8>, touched: Vec<u8>) {
        self.op_bg_snapshot = Some(bg);
        self.op_touched = Some(touched);
    }

    /// Take (or lazily allocate) the spot-contribution mask (1 byte/pixel).
    fn take_spot_mask(&mut self, w: u32, h: u32) -> Vec<u8> {
        let n = w as usize * h as usize;
        self.spot_mask.take().unwrap_or_else(|| vec![0u8; n])
    }

    /// Put the spot-contribution mask back after a paint.
    fn restore_spot_mask(&mut self, mask: Vec<u8>) {
        self.spot_mask = Some(mask);
    }

    /// Clear the overprint touched flag for pixels in the given bbox. Called
    /// by non-overprint paints so a subsequent overprint at those pixels
    /// captures a fresh backdrop snapshot instead of reusing a stale one.
    #[allow(dead_code)]
    fn invalidate_op_snapshot(
        &mut self,
        bbox_x0: usize,
        bbox_y0: usize,
        bbox_x1: usize,
        bbox_y1: usize,
        stride: usize,
    ) {
        if let Some(touched) = self.op_touched.as_mut() {
            for y in bbox_y0..bbox_y1 {
                let row = y * stride;
                for x in bbox_x0..bbox_x1 {
                    touched[row + x] = 0;
                }
            }
        }
    }
}

/// Unified rendering context that parameterizes both band and viewport rendering.
///
/// Band rendering is viewport rendering with `scale_x = scale_y = 1.0`.
/// `viewport_transform(t, vp_x, vp_y, 1.0, 1.0)` == `offset_transform_xy(t, vp_x, vp_y)`.
struct RenderContext<'a> {
    /// Viewport/band origin X in device space.
    vp_x: f32,
    /// Viewport/band origin Y in device space.
    vp_y: f32,
    /// Horizontal scale (1.0 for band rendering, zoom for viewport).
    scale_x: f32,
    /// Vertical scale (1.0 for band rendering, zoom for viewport).
    scale_y: f32,
    /// Output pixmap width in pixels.
    out_w: u32,
    /// Output pixmap height in pixels.
    out_h: u32,
    /// Effective DPI at output scale.
    effective_dpi: f64,
    /// ICC color profile cache (for CMYK conversions).
    icc: Option<&'a IccCache>,
    /// Pre-converted image data cache (for viewport rendering).
    image_cache: Option<&'a ImageCache>,
    /// Pre-converted and prescaled images (for banded rendering).
    preprocessed: Option<&'a [Option<PreprocessedImage>]>,
    /// Element index in parent display list (for image cache lookup).
    elem_idx: usize,
    /// Disable anti-aliasing for all fill/stroke operations.
    no_aa: bool,
    /// When true, CMYK(0,0,0,0) pixels in images produce alpha=0 (OPM=1).
    opm_zero_transparent: bool,
    /// Knockout group painter rendering pass override. The knockout group
    /// renders each Group painter twice — once for the blended-color result
    /// (`ColorPass`), once for the painter's coverage mask (`CoveragePass`).
    /// Both passes need to override `render_group`'s usual decisions:
    ///   * `ColorPass` expands the per-pixel CMYK composite-back gate to all
    ///     non-Normal blend modes so painters with separable blends like
    ///     Screen / ColorDodge / Overlay / SoftLight blend in DeviceCMYK
    ///     (matching the spec for `/CS DeviceCMYK` knockout groups) instead
    ///     of in tiny-skia's sRGB blend.
    ///   * `CoveragePass` disables the CMYK composite-back (its
    ///     "source==backdrop" guard would discard white-CMYK painters
    ///     against the transparent coverage backdrop) and forces the
    ///     painter's alpha to 1.0 with Normal blend so the coverage offscreen
    ///     captures the painter's *shape* even when the original alpha was 0
    ///     (Opacity 0% test) or its blend mode would erase the source.
    knockout_painter_pass: KnockoutPainterPass,
    /// True when the immediately enclosing transparency group was isolated.
    /// GWG 16.2's nested CMYK painter pattern (Painter B → Sub A/B) only
    /// requires CMYK math at the inner non-isolated layer when Painter B
    /// itself is isolated; for non-isolated parents (the 907 p28 financial
    /// chart pattern) the existing sRGB compositing path produces the right
    /// result and the new CMYK math would over-darken anti-aliased gray
    /// strokes.
    parent_group_isolated: bool,
    /// True when rendering an alpha-extraction pass for a non-isolated group
    /// with non-Normal blend mode.  Nested groups must render as isolated
    /// (no backdrop preload, no two-pass) so the alpha channel reflects
    /// pure element coverage rather than backdrop-blended results.
    alpha_extraction_pass: bool,
    /// OCG visibility overrides. Empty (every layer at its
    /// `default_visible`) when the caller didn't supply one.
    layer_set: &'a LayerSet,
}

/// Override mode applied to `render_group` while the knockout group renders
/// one of its painters; see [`RenderContext::knockout_painter_pass`].
#[derive(Clone, Copy, PartialEq, Eq)]
enum KnockoutPainterPass {
    /// Default rendering — no knockout overrides.
    None,
    /// Pass 1 (color): widen `plan_cmyk_compose` to any non-Normal blend mode.
    ColorPass,
    /// Pass 2 (coverage): disable CMYK composite-back, force full alpha and
    /// Normal blend so the coverage offscreen captures the painter's shape.
    CoveragePass,
}

impl RenderContext<'_> {
    /// Apply viewport transform to a PostScript matrix.
    fn transform(&self, m: &Matrix) -> Transform {
        viewport_transform(
            to_transform(m),
            self.vp_x,
            self.vp_y,
            self.scale_x,
            self.scale_y,
        )
    }
}

/// Y-axis bounding box in device pixels.
struct YBBox {
    y_min: f64,
    y_max: f64,
}

/// A group of display list elements between consecutive InitClip boundaries.
/// Each epoch starts with an InitClip (except possibly the first) and contains
/// all elements up to the next InitClip. Epochs whose paint elements don't
/// overlap a band can be skipped entirely.
struct ClipEpoch {
    /// Index of the first element in this epoch (the InitClip, or 0).
    start_idx: usize,
    /// One past the last element in this epoch.
    end_idx: usize,
    /// Y bounding box of all paint elements (Fill/Stroke/Image) in this epoch.
    /// None if the epoch has no paint elements (pure clip setup).
    paint_bbox: Option<YBBox>,
    /// True if this epoch contains an ErasePage element (must process for all bands).
    has_erase_page: bool,
}

/// Choose band height so that band pixmap + 2 clip masks fit in ~2 MB (L2 cache).
/// Returns `page_h` when banding is not worthwhile (≤2 bands).
fn select_band_height(w: u32, h: u32) -> u32 {
    if w == 0 || h == 0 {
        return h;
    }
    // Per-row cost: w*4 (RGBA) + w*1 (clip mask) + w*1 (spare mask) = w*6
    let per_row = w as u64 * 6;
    let budget = 2 * 1024 * 1024u64; // 2 MB (L2)
    let max_rows = budget / per_row;

    // Floor to power of 2, clamp to [16, h]
    let band = if max_rows >= h as u64 {
        h
    } else {
        let mut p = 1u32;
        while (p as u64) * 2 <= max_rows {
            p *= 2;
        }
        // Minimum 128 rows per band. At very high DPI the L2 budget yields
        // tiny bands (16 rows at 2400 DPI = 1650 bands) where display list
        // replay overhead dominates. 128-row minimum balances L3 cache fit
        // (~15 MB working set at 2400 DPI) against per-band overhead (207 bands).
        // Benchmarked: 16→31.3s, 64→22.5s, 128→21.8s, 256→22.1s.
        p.clamp(128, h)
    };

    // Skip banding if ≤2 bands
    if h.div_ceil(band) <= 2 {
        return h;
    }
    band
}

/// True if this display list contains any `Clip`/`InitClip` op, recursively
/// descending into `OcgGroup` / `Group` / `SoftMasked` children. When an
/// `OcgGroup` wraps clip ops, Y-bbox culling would skip the whole group for
/// bands its paint content doesn't overlap, but the clip state changes inside
/// must still be applied — otherwise subsequent top-level elements inherit a
/// stale clip. Use this to force such `OcgGroup`s to always be processed.
fn contains_clip_op(list: &DisplayList) -> bool {
    list.elements().iter().any(|e| match e {
        DisplayElement::Clip { .. } | DisplayElement::InitClip => true,
        DisplayElement::OcgGroup { elements, .. } => contains_clip_op(elements),
        DisplayElement::Group { elements, .. } => contains_clip_op(elements),
        DisplayElement::SoftMasked { content, .. } => contains_clip_op(content),
        _ => false,
    })
}

/// Compute conservative Y bounding boxes for display list elements.
/// Returns `None` for elements that must always be processed (Clip, InitClip, ErasePage).
///
/// All returned Y values are in **device space** (pixel coordinates) so they can be
/// compared directly against band boundaries.
fn precompute_bboxes(list: &DisplayList, dpi: f64) -> Vec<Option<YBBox>> {
    list.elements()
        .iter()
        .map(|elem| match elem {
            DisplayElement::Fill { path, params } => fill_device_y_bbox(path, &params.ctm),
            DisplayElement::Stroke { path, params } => stroke_device_y_bbox(path, params, dpi),
            DisplayElement::Image { params, .. } => image_y_bbox(params),
            DisplayElement::AxialShading { params } => {
                shading_y_bbox_from_bbox(&params.bbox, &params.ctm)
            }
            DisplayElement::RadialShading { params } => {
                shading_y_bbox_from_bbox(&params.bbox, &params.ctm)
            }
            DisplayElement::MeshShading { params } => {
                shading_y_bbox_from_bbox(&params.bbox, &params.ctm)
            }
            DisplayElement::PatchShading { params } => {
                shading_y_bbox_from_bbox(&params.bbox, &params.ctm)
            }
            DisplayElement::PatternFill { params } => pattern_fill_y_bbox(params),
            DisplayElement::Group { params, .. } => Some(YBBox {
                y_min: params.bbox[1],
                y_max: params.bbox[3],
            }),
            DisplayElement::SoftMasked { params, .. } => Some(YBBox {
                y_min: params.bbox[1],
                y_max: params.bbox[3],
            }),
            DisplayElement::OcgGroup {
                elements,
                visibility,
            } => {
                // Hidden groups without clip ops contribute nothing — cull.
                // (Hidden + has clip ops is handled below: we return paint
                // bounds so the epoch has correct extent, and the band loop
                // skips per-element culling for OcgGroups so the clip ops
                // always execute.)
                if !visibility.default_visible() && !contains_clip_op(elements) {
                    return None;
                }
                let child_bboxes = precompute_bboxes(elements, dpi);
                let mut y_min = f64::INFINITY;
                let mut y_max = f64::NEG_INFINITY;
                for cb in child_bboxes.into_iter().flatten() {
                    y_min = y_min.min(cb.y_min);
                    y_max = y_max.max(cb.y_max);
                }
                if y_min <= y_max {
                    Some(YBBox { y_min, y_max })
                } else {
                    None
                }
            }
            _ => None, // Clip, InitClip, ErasePage: always process
        })
        .collect()
}

/// Compute device-space Y bounding box for a shading element.
/// Uses the BBox if present, otherwise returns a full-page sentinel
/// (y_min=0, y_max=very large) so the element is never culled.
fn shading_y_bbox_from_bbox(bbox: &Option<[f64; 4]>, ctm: &Matrix) -> Option<YBBox> {
    if let Some(bbox) = bbox {
        let corners = [
            (bbox[0], bbox[1]),
            (bbox[2], bbox[1]),
            (bbox[0], bbox[3]),
            (bbox[2], bbox[3]),
        ];
        let mut y_min = f64::INFINITY;
        let mut y_max = f64::NEG_INFINITY;
        for (x, y) in &corners {
            let (_, dy) = ctm.transform_point(*x, *y);
            y_min = y_min.min(dy);
            y_max = y_max.max(dy);
        }
        Some(YBBox { y_min, y_max })
    } else {
        // No BBox — shading covers unbounded area; return sentinel so it's
        // never culled by band processing.
        Some(YBBox {
            y_min: 0.0,
            y_max: 1e9,
        })
    }
}

/// Compute device-space Y bounding box for a stroke element.
///
/// Isotropic strokes have paths already in device space (Identity CTM), so
/// `path_y_bbox` gives device-space bounds directly. Anisotropic strokes have
/// paths in user space with the full CTM — we must transform the bounding box
/// through the CTM to get device-space bounds.
fn stroke_device_y_bbox(path: &PsPath, params: &StrokeParams, dpi: f64) -> Option<YBBox> {
    let m = &params.ctm;
    let is_identity =
        m.a == 1.0 && m.b == 0.0 && m.c == 0.0 && m.d == 1.0 && m.tx == 0.0 && m.ty == 0.0;

    // Use effective line width: actual width or hairline minimum, whichever is larger
    let effective_lw = params.line_width.max(hairline_min_width(&params.ctm, dpi));

    if is_identity {
        // Path in device space — just read Y coords and expand for stroke width.
        return path_y_bbox(path).map(|mut bbox| {
            let expand = effective_lw * params.miter_limit * 0.5;
            bbox.y_min -= expand;
            bbox.y_max += expand;
            bbox
        });
    }

    // Anisotropic: path in user space. Compute full XY bbox, transform corners
    // through CTM to get device-space Y range.
    let (mut x_min, mut x_max) = (f64::INFINITY, f64::NEG_INFINITY);
    let (mut y_min, mut y_max) = (f64::INFINITY, f64::NEG_INFINITY);
    for seg in &path.segments {
        match seg {
            PathSegment::MoveTo(x, y) | PathSegment::LineTo(x, y) => {
                x_min = x_min.min(*x);
                x_max = x_max.max(*x);
                y_min = y_min.min(*y);
                y_max = y_max.max(*y);
            }
            PathSegment::CurveTo {
                x1,
                y1,
                x2,
                y2,
                x3,
                y3,
            } => {
                x_min = x_min.min(*x1).min(*x2).min(*x3);
                x_max = x_max.max(*x1).max(*x2).max(*x3);
                y_min = y_min.min(*y1).min(*y2).min(*y3);
                y_max = y_max.max(*y1).max(*y2).max(*y3);
            }
            PathSegment::ClosePath => {}
        }
    }
    if x_min > x_max {
        return None;
    }

    // Transform all 4 corners of user-space bbox to device space
    let corners = [
        (x_min, y_min),
        (x_max, y_min),
        (x_min, y_max),
        (x_max, y_max),
    ];
    let mut dev_y_min = f64::INFINITY;
    let mut dev_y_max = f64::NEG_INFINITY;
    for (x, y) in &corners {
        let dy = m.b * x + m.d * y + m.ty;
        dev_y_min = dev_y_min.min(dy);
        dev_y_max = dev_y_max.max(dy);
    }

    // Expand for stroke width + miter in device-space units.
    // ||[c,d]|| converts user-space line_width to device-space Y expansion.
    let col_y_len = (m.c * m.c + m.d * m.d).sqrt().max(1.0);
    let expand = effective_lw * col_y_len * params.miter_limit * 0.5;
    dev_y_min -= expand;
    dev_y_max += expand;

    Some(YBBox {
        y_min: dev_y_min,
        y_max: dev_y_max,
    })
}

/// Compute device-space Y bounds for a Fill element, accounting for CTM.
/// Mirrors `stroke_device_y_bbox` but without stroke-width expansion.
/// Paths may be stored either in device space (identity CTM, content streams)
/// or user space (non-identity CTM, synthesized annotation appearances).
fn fill_device_y_bbox(path: &PsPath, ctm: &Matrix) -> Option<YBBox> {
    let is_identity = ctm.a == 1.0
        && ctm.b == 0.0
        && ctm.c == 0.0
        && ctm.d == 1.0
        && ctm.tx == 0.0
        && ctm.ty == 0.0;
    if is_identity {
        return path_y_bbox(path);
    }
    let bbox = path_full_bbox(path)?;
    let corners = [
        (bbox.x_min, bbox.y_min),
        (bbox.x_max, bbox.y_min),
        (bbox.x_min, bbox.y_max),
        (bbox.x_max, bbox.y_max),
    ];
    let mut dev_y_min = f64::INFINITY;
    let mut dev_y_max = f64::NEG_INFINITY;
    for (x, y) in &corners {
        let dy = ctm.b * x + ctm.d * y + ctm.ty;
        dev_y_min = dev_y_min.min(dy);
        dev_y_max = dev_y_max.max(dy);
    }
    Some(YBBox {
        y_min: dev_y_min,
        y_max: dev_y_max,
    })
}

/// Compute Y bounds from path segments (conservative: uses control points for curves).
fn path_y_bbox(path: &PsPath) -> Option<YBBox> {
    let mut y_min = f64::INFINITY;
    let mut y_max = f64::NEG_INFINITY;
    for seg in &path.segments {
        match seg {
            PathSegment::MoveTo(_, y) | PathSegment::LineTo(_, y) => {
                y_min = y_min.min(*y);
                y_max = y_max.max(*y);
            }
            PathSegment::CurveTo { y1, y2, y3, .. } => {
                y_min = y_min.min(*y1).min(*y2).min(*y3);
                y_max = y_max.max(*y1).max(*y2).max(*y3);
            }
            PathSegment::ClosePath => {}
        }
    }
    if y_min <= y_max {
        Some(YBBox { y_min, y_max })
    } else {
        None
    }
}

/// Compute Y bounds for an image element from its transform.
fn image_y_bbox(params: &ImageParams) -> Option<YBBox> {
    let image_inv = params.image_matrix.invert()?;
    let combined = params.ctm.concat(&image_inv);
    let corners = [
        (0.0, 0.0),
        (params.width as f64, 0.0),
        (params.width as f64, params.height as f64),
        (0.0, params.height as f64),
    ];
    let mut y_min = f64::INFINITY;
    let mut y_max = f64::NEG_INFINITY;
    for (x, y) in &corners {
        let (_, dy) = combined.transform_point(*x, *y);
        y_min = y_min.min(dy);
        y_max = y_max.max(dy);
    }
    Some(YBBox { y_min, y_max })
}

/// Pre-populate clip_mask_seen with hashes of clip paths that appear ≥2 times.
/// This lets the first band immediately cache repeated clip paths.
fn precompute_clip_seen(list: &DisplayList) -> HashSet<u64> {
    let mut counts: HashMap<u64, u32> = HashMap::new();
    for elem in list.elements() {
        if let DisplayElement::Clip { path, params } = elem {
            let hash = hash_clip_path(path, &params.fill_rule);
            *counts.entry(hash).or_insert(0) += 1;
        }
    }
    counts
        .into_iter()
        .filter(|(_, c)| *c > 1)
        .map(|(h, _)| h)
        .collect()
}

/// Build clip epochs — groups of elements between InitClip boundaries.
/// Each epoch's paint_bbox is the union of Y ranges for all paint elements in it.
fn build_clip_epochs(list: &DisplayList, bboxes: &[Option<YBBox>]) -> Vec<ClipEpoch> {
    let elements = list.elements();
    let mut epochs = Vec::new();
    let mut epoch_start = 0;
    let mut y_min = f64::INFINITY;
    let mut y_max = f64::NEG_INFINITY;
    let mut has_erase = false;

    for (i, element) in elements.iter().enumerate() {
        // InitClip starts a new epoch (close the previous one first)
        if matches!(element, DisplayElement::InitClip) && i > epoch_start {
            epochs.push(ClipEpoch {
                start_idx: epoch_start,
                end_idx: i,
                paint_bbox: if y_min <= y_max {
                    Some(YBBox { y_min, y_max })
                } else {
                    None
                },
                has_erase_page: has_erase,
            });
            epoch_start = i;
            y_min = f64::INFINITY;
            y_max = f64::NEG_INFINITY;
            has_erase = false;
        }
        if matches!(element, DisplayElement::ErasePage) {
            has_erase = true;
        }
        if let Some(ref bbox) = bboxes[i] {
            y_min = y_min.min(bbox.y_min);
            y_max = y_max.max(bbox.y_max);
        }
    }
    // Final epoch
    if epoch_start < elements.len() {
        epochs.push(ClipEpoch {
            start_idx: epoch_start,
            end_idx: elements.len(),
            paint_bbox: if y_min <= y_max {
                Some(YBBox { y_min, y_max })
            } else {
                None
            },
            has_erase_page: has_erase,
        });
    }
    epochs
}

/// Apply a device-space Y offset to a tiny-skia Transform.
/// The original transform maps from path space to full-page device space;
/// we subtract `y_offset` from `ty` so band rows [y_start, y_start+band_h)
/// map to pixmap rows [0, band_h).
/// Composite premultiplied-alpha RGBA pixels onto a white background.
/// After this, all pixels are fully opaque (alpha=255).
fn composite_onto_white(data: &mut [u8]) {
    for pixel in data.chunks_exact_mut(4) {
        let a = pixel[3] as u16;
        if a == 255 {
            continue; // fully opaque — no compositing needed
        }
        let inv_a = 255 - a;
        pixel[0] = (pixel[0] as u16 + inv_a).min(255) as u8;
        pixel[1] = (pixel[1] as u16 + inv_a).min(255) as u8;
        pixel[2] = (pixel[2] as u16 + inv_a).min(255) as u8;
        pixel[3] = 255;
    }
}

/// Extract the contribution of a non-isolated transparency group and composite
/// it onto the parent using the group's blend mode and alpha.
///
/// Composite a (possibly cropped) non-isolated group offscreen onto the parent pixmap.
///
/// Like `extract_and_composite_contribution`, but the offscreen and backdrop
/// are crop-sized (only covering the group's bounding box region), positioned
/// at `(crop_x, crop_y)` in the parent's coordinate system.
fn composite_non_isolated_group_cropped(
    target: &mut Pixmap,
    source: &Pixmap,
    backdrop: &[u8],
    params: &stet_graphics::display_list::GroupParams,
    clip_mask: Option<&stet_tiny_skia::Mask>,
    crop_x: i32,
    crop_y: i32,
) {
    let cw = source.width();
    let ch = source.height();

    // Build a contribution pixmap: pixels that changed vs backdrop
    let Some(mut contribution) = Pixmap::new(cw, ch) else {
        return;
    };
    let src_data = source.data();
    let contrib_data = contribution.data_mut();

    for (i, chunk) in contrib_data.chunks_exact_mut(4).enumerate() {
        let off = i * 4;
        if src_data[off] != backdrop[off]
            || src_data[off + 1] != backdrop[off + 1]
            || src_data[off + 2] != backdrop[off + 2]
            || src_data[off + 3] != backdrop[off + 3]
        {
            chunk.copy_from_slice(&src_data[off..off + 4]);
        }
    }

    let paint = stet_tiny_skia::PixmapPaint {
        opacity: params.alpha as f32,
        blend_mode: u8_to_blend_mode(params.blend_mode),
        quality: stet_tiny_skia::FilterQuality::Nearest,
    };
    target.draw_pixmap(
        crop_x,
        crop_y,
        contribution.as_ref(),
        &paint,
        Transform::identity(),
        clip_mask,
    );
}

/// Non-isolated group composite-back using the proper source-extraction
/// formula (ISO 32000-1 §11.4.8).
///
/// `source` was rendered against the `backdrop`; `isolated` was rendered
/// against transparent.  The isolated render's alpha channel gives the
/// group's shape, which lets us extract the source color:
///
///   C_g_premul = R - B · (1 - α_g)      (premultiplied source color)
///   α_g        = isolated alpha channel
///
/// The extracted contribution is then composited onto `target` with the
/// group's blend mode and opacity.
fn composite_non_isolated_extracted(
    target: &mut Pixmap,
    source: &Pixmap,
    isolated: &Pixmap,
    backdrop: &[u8],
    params: &stet_graphics::display_list::GroupParams,
    clip_mask: Option<&stet_tiny_skia::Mask>,
    crop_x: i32,
    crop_y: i32,
) {
    let cw = source.width();
    let ch = source.height();

    let Some(mut contribution) = Pixmap::new(cw, ch) else {
        return;
    };
    let src_data = source.data();
    let iso_data = isolated.data();
    let contrib_data = contribution.data_mut();

    for i in 0..(cw as usize * ch as usize) {
        let off = i * 4;
        let alpha_g = iso_data[off + 3];
        if alpha_g == 0 {
            continue; // no group contribution at this pixel
        }

        // Extract premultiplied source: C_g_premul = R - B · (1 - α_g/255)
        let inv_alpha = 255 - alpha_g as i32;
        for c in 0..3 {
            let r = src_data[off + c] as i32;
            let b = backdrop[off + c] as i32;
            let raw = r - (b * inv_alpha + 127) / 255;
            contrib_data[off + c] = raw.clamp(0, 255) as u8;
        }
        contrib_data[off + 3] = alpha_g;
    }

    let paint = stet_tiny_skia::PixmapPaint {
        opacity: params.alpha as f32,
        blend_mode: u8_to_blend_mode(params.blend_mode),
        quality: stet_tiny_skia::FilterQuality::Nearest,
    };
    target.draw_pixmap(
        crop_x,
        crop_y,
        contribution.as_ref(),
        &paint,
        Transform::identity(),
        clip_mask,
    );
}

/// Apply a combined offset + scale to a tiny-skia Transform for viewport rendering.
/// Maps device-space coordinates into viewport-local pixel coordinates:
///   output_x = (device_x - vp_x) * scale_x
///   output_y = (device_y - vp_y) * scale_y
fn viewport_transform(t: Transform, vp_x: f32, vp_y: f32, scale_x: f32, scale_y: f32) -> Transform {
    // Post-compose: first apply `t` (path→device), then translate(-vp_x,-vp_y), then scale
    Transform::from_row(
        t.sx * scale_x,
        t.ky * scale_y,
        t.kx * scale_x,
        t.sy * scale_y,
        (t.tx - vp_x) * scale_x,
        (t.ty - vp_y) * scale_y,
    )
}

/// Fast area-average box filter resample for downscaling.
///
/// Each output pixel averages all source pixels that fall within its footprint.
/// Two-pass separable (horizontal then vertical) for O(src) total work regardless
/// of scale ratio. Produces quality equivalent to Lanczos3 for downscaling at a
/// fraction of the cost.
fn box_resample(src: &[u8], sw: u32, sh: u32, dw: u32, dh: u32) -> Vec<u8> {
    if dw == 0 || dh == 0 {
        return Vec::new();
    }
    let (sw, sh, dw, dh) = (sw as usize, sh as usize, dw as usize, dh as usize);

    // Pass 1: horizontal (sw → dw) with fractional edge weights.
    // Each output pixel covers [left_f, right_f] in source space. Edge source
    // pixels get proportional weight; interior pixels get weight 1.0.
    let ratio_x = sw as f32 / dw as f32;
    let mut tmp = vec![0.0f32; dw * sh * 4];
    let tmp_stride = dw * 4;

    for y in 0..sh {
        let row_off = y * sw * 4;
        let dst_row = y * tmp_stride;
        for dx in 0..dw {
            let left_f = dx as f32 * ratio_x;
            let right_f = (dx + 1) as f32 * ratio_x;
            let left = (left_f as usize).min(sw - 1);
            let right = (right_f.ceil() as usize).min(sw);
            let inv_area = 1.0 / (right_f - left_f);
            let (mut r, mut g, mut b, mut a) = (0.0f32, 0.0, 0.0, 0.0);
            for sx in left..right {
                // Weight: fraction of this source pixel covered by the output pixel
                let pixel_left = sx as f32;
                let pixel_right = (sx + 1) as f32;
                let w = pixel_right.min(right_f) - pixel_left.max(left_f);
                let i = row_off + sx * 4;
                r += src[i] as f32 * w;
                g += src[i + 1] as f32 * w;
                b += src[i + 2] as f32 * w;
                a += src[i + 3] as f32 * w;
            }
            let di = dst_row + dx * 4;
            tmp[di] = r * inv_area;
            tmp[di + 1] = g * inv_area;
            tmp[di + 2] = b * inv_area;
            tmp[di + 3] = a * inv_area;
        }
    }

    // Pass 2: vertical (sh → dh) with fractional edge weights, row-major order.
    let ratio_y = sh as f32 / dh as f32;
    let mut out = vec![0u8; dw * dh * 4];
    let out_stride = dw * 4;

    for dy in 0..dh {
        let top_f = dy as f32 * ratio_y;
        let bottom_f = (dy + 1) as f32 * ratio_y;
        let top = (top_f as usize).min(sh - 1);
        let bottom = (bottom_f.ceil() as usize).min(sh);
        let inv_area = 1.0 / (bottom_f - top_f);

        // Pre-compute row weights
        let n_rows = bottom - top;
        let mut row_weights_buf: [(usize, f32); 8] = [(0, 0.0); 8];
        let row_weights_vec: Vec<(usize, f32)>;
        let row_weights: &[(usize, f32)] = if n_rows <= 8 {
            for (i, sy) in (top..bottom).enumerate() {
                let pixel_top = sy as f32;
                let pixel_bottom = (sy + 1) as f32;
                let w = pixel_bottom.min(bottom_f) - pixel_top.max(top_f);
                row_weights_buf[i] = (sy, w);
            }
            &row_weights_buf[..n_rows]
        } else {
            row_weights_vec = (top..bottom)
                .map(|sy| {
                    let pixel_top = sy as f32;
                    let pixel_bottom = (sy + 1) as f32;
                    let w = pixel_bottom.min(bottom_f) - pixel_top.max(top_f);
                    (sy, w)
                })
                .collect();
            &row_weights_vec
        };

        let dst_row = dy * out_stride;
        for dx in 0..dw {
            let col = dx * 4;
            let (mut r, mut g, mut b, mut a) = (0.0f32, 0.0, 0.0, 0.0);
            for &(sy, w) in row_weights {
                let i = sy * tmp_stride + col;
                r += tmp[i] * w;
                g += tmp[i + 1] * w;
                b += tmp[i + 2] * w;
                a += tmp[i + 3] * w;
            }
            let di = dst_row + col;
            out[di] = (r * inv_area + 0.5).clamp(0.0, 255.0) as u8;
            out[di + 1] = (g * inv_area + 0.5).clamp(0.0, 255.0) as u8;
            out[di + 2] = (b * inv_area + 0.5).clamp(0.0, 255.0) as u8;
            out[di + 3] = (a * inv_area + 0.5).clamp(0.0, 255.0) as u8;
        }
    }

    out
}

/// Bicubic (Catmull-Rom) resample for upscaling — two-pass separable.
///
/// Pass 1: horizontal resample (sw → dw) at f32 precision.
/// Pass 2: vertical resample (sh → dh) and quantize to u8.
///
/// Separable approach: O(dw×sh + dw×dh) × 4 taps instead of O(dw×dh) × 16 taps.
fn bicubic_resample(src: &[u8], sw: u32, sh: u32, dw: u32, dh: u32) -> Vec<u8> {
    if dw == 0 || dh == 0 {
        return Vec::new();
    }

    let (sw, sh, dw, dh) = (sw as usize, sh as usize, dw as usize, dh as usize);
    let ratio_x = sw as f32 / dw as f32;
    let ratio_y = sh as f32 / dh as f32;

    // Pass 1: horizontal (sw → dw), keep sh rows, store as f32.
    let mut tmp = vec![0.0f32; dw * sh * 4];
    for y in 0..sh {
        let src_row = y * sw * 4;
        let dst_row = y * dw * 4;
        for dx in 0..dw {
            let sx = (dx as f32 + 0.5) * ratio_x - 0.5;
            let sx_floor = sx.floor() as i32;
            let fx = sx - sx_floor as f32;
            let w0 = catmull_rom(fx + 1.0);
            let w1 = catmull_rom(fx);
            let w2 = catmull_rom(1.0 - fx);
            let w3 = catmull_rom(2.0 - fx);
            let (mut r, mut g, mut b, mut a) = (0.0f32, 0.0, 0.0, 0.0);
            for (k, w) in [
                (sx_floor - 1, w0),
                (sx_floor, w1),
                (sx_floor + 1, w2),
                (sx_floor + 2, w3),
            ] {
                let px = k.clamp(0, sw as i32 - 1) as usize;
                let i = src_row + px * 4;
                r += src[i] as f32 * w;
                g += src[i + 1] as f32 * w;
                b += src[i + 2] as f32 * w;
                a += src[i + 3] as f32 * w;
            }
            let di = dst_row + dx * 4;
            tmp[di] = r;
            tmp[di + 1] = g;
            tmp[di + 2] = b;
            tmp[di + 3] = a;
        }
    }

    // Pass 2: vertical (sh → dh) on the dw-wide tmp, quantize to u8.
    // Row-major order for cache-friendly access.
    let mut out = vec![0u8; dw * dh * 4];
    let tmp_stride = dw * 4;
    let out_stride = dw * 4;
    for dy in 0..dh {
        let sy = (dy as f32 + 0.5) * ratio_y - 0.5;
        let sy_floor = sy.floor() as i32;
        let fy = sy - sy_floor as f32;
        let w0 = catmull_rom(fy + 1.0);
        let w1 = catmull_rom(fy);
        let w2 = catmull_rom(1.0 - fy);
        let w3 = catmull_rom(2.0 - fy);
        let py0 = (sy_floor - 1).clamp(0, sh as i32 - 1) as usize * tmp_stride;
        let py1 = sy_floor.clamp(0, sh as i32 - 1) as usize * tmp_stride;
        let py2 = (sy_floor + 1).clamp(0, sh as i32 - 1) as usize * tmp_stride;
        let py3 = (sy_floor + 2).clamp(0, sh as i32 - 1) as usize * tmp_stride;
        let dst_row = dy * out_stride;
        for dx in 0..dw {
            let col = dx * 4;
            let r = tmp[py0 + col] * w0
                + tmp[py1 + col] * w1
                + tmp[py2 + col] * w2
                + tmp[py3 + col] * w3;
            let g = tmp[py0 + col + 1] * w0
                + tmp[py1 + col + 1] * w1
                + tmp[py2 + col + 1] * w2
                + tmp[py3 + col + 1] * w3;
            let b = tmp[py0 + col + 2] * w0
                + tmp[py1 + col + 2] * w1
                + tmp[py2 + col + 2] * w2
                + tmp[py3 + col + 2] * w3;
            let a = tmp[py0 + col + 3] * w0
                + tmp[py1 + col + 3] * w1
                + tmp[py2 + col + 3] * w2
                + tmp[py3 + col + 3] * w3;
            let di = dst_row + col;
            out[di] = r.round().clamp(0.0, 255.0) as u8;
            out[di + 1] = g.round().clamp(0.0, 255.0) as u8;
            out[di + 2] = b.round().clamp(0.0, 255.0) as u8;
            out[di + 3] = a.round().clamp(0.0, 255.0) as u8;
        }
    }

    out
}

/// Catmull-Rom spline weight (a = -0.5).
#[inline]
fn catmull_rom(t: f32) -> f32 {
    let t = t.abs();
    if t < 1.0 {
        (1.5 * t - 2.5) * t * t + 1.0
    } else if t < 2.0 {
        ((-0.5 * t + 2.5) * t - 4.0) * t + 2.0
    } else {
        0.0
    }
}

/// Pre-downsample an image when the transform indicates significant downscaling.
///
/// tiny-skia's bilinear filter only samples a 2×2 neighborhood — it has no mipmap
/// support, so large downscale ratios cause severe aliasing (e.g., 300 DPI bitmap
/// fonts rendered at screen resolution).
///
/// For axis-aligned transforms: box-filter resample to the exact target dimensions.
///
/// Build an `IccCache` from ICC profiles found in a display list.
///
/// Registers all unique ICCBased profiles and optionally the system CMYK
/// profile. When `proofing_enabled` is true, ICCBased profiles registered
/// while scanning the display list are color-managed *through* the system
/// CMYK (the PDF's OutputIntent), so a render-thread cache built from the
/// effective OutputIntent matches the bake-time cache that produced the
/// display list. PostScript callers should pass `false` (no
/// PDF/X OutputIntent semantics).
pub fn build_icc_cache_for_list(
    list: &DisplayList,
    system_cmyk_bytes: Option<&std::sync::Arc<Vec<u8>>>,
    proofing_enabled: bool,
) -> IccCache {
    let mut cache = IccCache::new();
    let mut seen = HashSet::new();

    // Register system CMYK profile first. Proofing must stay off here: the
    // OutputIntent itself converts directly to sRGB, not through itself.
    if let Some(cmyk_bytes) = system_cmyk_bytes
        && let Some(hash) = cache.register_profile(cmyk_bytes)
    {
        seen.insert(hash);
        // Set the default CMYK hash so convert_image_8bit works for DeviceCMYK
        cache.set_default_cmyk_hash(hash);
        // Pre-warm the sRGB→CMYK reverse transform so band renderers, which
        // only hold an `&IccCache`, can use `convert_rgb_to_cmyk_readonly`
        // when populating the parallel CMYK buffer for non-CMYK painters.
        cache.prepare_reverse_cmyk();
        // Pre-build the per-intent Lab → OI CMYK samplers so Lab fills can
        // populate `native_cmyk` from `&IccCache` (mirrors the PNG path's
        // `apply_output_intent_as_default_cmyk`). Required for GWG 22.1.
        cache.prepare_lab_to_oi_cmyk();
    }

    // Enable proofing AFTER the OutputIntent itself is registered so the
    // chain logic in `register_profile` sees `default_cmyk_hash` set when
    // subsequent ICCBased profiles arrive — those get chained through the
    // OutputIntent.
    cache.set_proofing_enabled(proofing_enabled);

    // Scan display list for ICCBased images and shadings (recursing into Groups)
    fn scan_elements(
        elements: &[DisplayElement],
        seen: &mut HashSet<stet_graphics::icc::ProfileHash>,
        cache: &mut IccCache,
    ) {
        for element in elements {
            // Recurse into groups
            if let DisplayElement::Group { elements: sub, .. } = element {
                scan_elements(sub.elements(), seen, cache);
            }
            if let DisplayElement::SoftMasked { content, mask, .. } = element {
                scan_elements(content.elements(), seen, cache);
                scan_elements(mask.elements(), seen, cache);
            }
            if let DisplayElement::OcgGroup { elements: sub, .. } = element {
                scan_elements(sub.elements(), seen, cache);
            }
            // Shading color spaces
            let shading_cs = match element {
                DisplayElement::AxialShading { params } => Some(&params.color_space),
                DisplayElement::RadialShading { params } => Some(&params.color_space),
                DisplayElement::MeshShading { params } => Some(&params.color_space),
                DisplayElement::PatchShading { params } => Some(&params.color_space),
                _ => None,
            };
            if let Some(stet_graphics::device::ShadingColorSpace::ICCBased {
                n,
                profile_hash,
                profile_data,
            }) = shading_cs
            {
                if seen.insert(*profile_hash) {
                    cache.register_profile_with_n(profile_data, Some(*n));
                }
            }
            // Image color spaces
            if let DisplayElement::Image { params, .. } = element {
                match &params.color_space {
                    ImageColorSpace::ICCBased {
                        n,
                        profile_hash,
                        profile_data,
                    } if seen.insert(*profile_hash) => {
                        cache.register_profile_with_n(profile_data, Some(*n));
                    }
                    ImageColorSpace::Indexed { base, .. }
                        if matches!(base.as_ref(), ImageColorSpace::ICCBased { .. }) =>
                    {
                        if let ImageColorSpace::ICCBased {
                            n,
                            profile_hash,
                            profile_data,
                        } = base.as_ref()
                        {
                            if seen.insert(*profile_hash) {
                                cache.register_profile_with_n(profile_data, Some(*n));
                            }
                        }
                    }
                    _ => {}
                }
            }
        }
    }
    scan_elements(list.elements(), &mut seen, &mut cache);

    cache
}

/// Register ICC profiles from shading elements in a display list.
///
/// Recursively scans Groups and SoftMasks for ICCBased shading color spaces
/// and registers their profiles in the cache.
fn register_shading_icc_profiles(list: &DisplayList, cache: &mut IccCache) {
    fn register_image_iccs(
        cs: &ImageColorSpace,
        seen: &mut HashSet<stet_graphics::icc::ProfileHash>,
        cache: &mut IccCache,
    ) {
        match cs {
            ImageColorSpace::ICCBased {
                n,
                profile_hash,
                profile_data,
            } => {
                if seen.insert(*profile_hash) {
                    cache.register_profile_with_n(profile_data, Some(*n));
                }
            }
            ImageColorSpace::Indexed { base, .. } => register_image_iccs(base, seen, cache),
            ImageColorSpace::Separation { alt_space, .. }
            | ImageColorSpace::DeviceN { alt_space, .. } => {
                register_image_iccs(alt_space, seen, cache)
            }
            _ => {}
        }
    }
    fn scan(
        elements: &[DisplayElement],
        seen: &mut HashSet<stet_graphics::icc::ProfileHash>,
        cache: &mut IccCache,
    ) {
        for element in elements {
            if let DisplayElement::Group { elements: sub, .. } = element {
                scan(sub.elements(), seen, cache);
            }
            if let DisplayElement::SoftMasked { content, mask, .. } = element {
                scan(content.elements(), seen, cache);
                scan(mask.elements(), seen, cache);
            }
            if let DisplayElement::OcgGroup { elements: sub, .. } = element {
                scan(sub.elements(), seen, cache);
            }
            let shading_cs = match element {
                DisplayElement::AxialShading { params } => Some(&params.color_space),
                DisplayElement::RadialShading { params } => Some(&params.color_space),
                DisplayElement::MeshShading { params } => Some(&params.color_space),
                DisplayElement::PatchShading { params } => Some(&params.color_space),
                _ => None,
            };
            if let Some(stet_graphics::device::ShadingColorSpace::ICCBased {
                n,
                profile_hash,
                profile_data,
            }) = shading_cs
                && seen.insert(*profile_hash)
            {
                cache.register_profile_with_n(profile_data, Some(*n));
            }
            if let DisplayElement::Image { params, .. } = element {
                register_image_iccs(&params.color_space, seen, cache);
            }
        }
    }
    let mut seen = HashSet::new();
    scan(list.elements(), &mut seen, cache);
}

/// Convert raw image samples to RGBA for rasterization.
///
/// Handles all `ImageColorSpace` variants, producing width×height×4 RGBA bytes.
fn samples_to_rgba(
    data: &[u8],
    params: &ImageParams,
    icc: Option<&IccCache>,
    opm_zero_transparent: bool,
) -> Vec<u8> {
    let w = params.width as usize;
    let h = params.height as usize;
    let npixels = w * h;
    let bpc = params.bits_per_component;
    match &params.color_space {
        ImageColorSpace::PreconvertedRGBA => {
            // Already RGBA — just return as-is
            data.to_vec()
        }
        ImageColorSpace::DeviceGray => {
            let mut rgba = vec![255u8; npixels * 4];
            if bpc == 16 {
                for i in 0..npixels {
                    let g = data.get(i * 2).copied().unwrap_or(0);
                    let pi = i * 4;
                    rgba[pi] = g;
                    rgba[pi + 1] = g;
                    rgba[pi + 2] = g;
                }
            } else {
                for i in 0..npixels {
                    let g = data.get(i).copied().unwrap_or(0);
                    let pi = i * 4;
                    rgba[pi] = g;
                    rgba[pi + 1] = g;
                    rgba[pi + 2] = g;
                }
            }
            rgba
        }
        ImageColorSpace::DeviceRGB => {
            let mut rgba = vec![255u8; npixels * 4];
            if bpc == 16 {
                // 16 BPC: 6 bytes per pixel (R_hi R_lo G_hi G_lo B_hi B_lo)
                // Take high byte of each 16-bit sample
                for i in 0..npixels {
                    let si = i * 6;
                    let pi = i * 4;
                    rgba[pi] = data.get(si).copied().unwrap_or(0);
                    rgba[pi + 1] = data.get(si + 2).copied().unwrap_or(0);
                    rgba[pi + 2] = data.get(si + 4).copied().unwrap_or(0);
                }
            } else {
                for i in 0..npixels {
                    let si = i * 3;
                    let pi = i * 4;
                    rgba[pi] = data.get(si).copied().unwrap_or(0);
                    rgba[pi + 1] = data.get(si + 1).copied().unwrap_or(0);
                    rgba[pi + 2] = data.get(si + 2).copied().unwrap_or(0);
                }
            }
            rgba
        }
        ImageColorSpace::DeviceCMYK => {
            // Try ICC-based CMYK→RGB conversion via system CMYK profile.
            // Convert as many complete pixels as the data allows; PLRM-fallback
            // for any remaining pixels with insufficient data.
            if let Some(cache) = icc
                && let Some(cmyk_hash) = cache.default_cmyk_hash()
            {
                let avail_pixels = data.len() / 4;
                let icc_pixels = avail_pixels.min(npixels);
                if icc_pixels > 0
                    && let Some(rgb) = cache.convert_image_8bit(cmyk_hash, data, icc_pixels)
                {
                    let mut rgba = vec![255u8; npixels * 4];
                    for i in 0..icc_pixels {
                        rgba[i * 4] = rgb[i * 3];
                        rgba[i * 4 + 1] = rgb[i * 3 + 1];
                        rgba[i * 4 + 2] = rgb[i * 3 + 2];
                        // OPM=1: CMYK(0,0,0,0) = no ink = transparent
                        if opm_zero_transparent {
                            let si = i * 4;
                            if data[si] == 0
                                && data[si + 1] == 0
                                && data[si + 2] == 0
                                && data[si + 3] == 0
                            {
                                rgba[i * 4 + 3] = 0;
                            }
                        }
                    }
                    // Remaining pixels (if data was short) stay white (0xFF)
                    return rgba;
                }
            }
            // Fallback: PLRM CMYK→RGB formula
            let mut rgba = vec![255u8; npixels * 4];
            for i in 0..npixels {
                let si = i * 4;
                let c = data.get(si).copied().unwrap_or(0) as f64 / 255.0;
                let m = data.get(si + 1).copied().unwrap_or(0) as f64 / 255.0;
                let y = data.get(si + 2).copied().unwrap_or(0) as f64 / 255.0;
                let k = data.get(si + 3).copied().unwrap_or(0) as f64 / 255.0;
                let r = (1.0 - c.min(1.0)) * (1.0 - k.min(1.0));
                let g = (1.0 - m.min(1.0)) * (1.0 - k.min(1.0));
                let b = (1.0 - y.min(1.0)) * (1.0 - k.min(1.0));
                let pi = i * 4;
                rgba[pi] = (r * 255.0).round().clamp(0.0, 255.0) as u8;
                rgba[pi + 1] = (g * 255.0).round().clamp(0.0, 255.0) as u8;
                rgba[pi + 2] = (b * 255.0).round().clamp(0.0, 255.0) as u8;
                // OPM=1: CMYK(0,0,0,0) = no ink = transparent
                if opm_zero_transparent
                    && data.get(si).copied().unwrap_or(0) == 0
                    && data.get(si + 1).copied().unwrap_or(0) == 0
                    && data.get(si + 2).copied().unwrap_or(0) == 0
                    && data.get(si + 3).copied().unwrap_or(0) == 0
                {
                    rgba[pi + 3] = 0;
                }
            }
            rgba
        }
        ImageColorSpace::ICCBased {
            n,
            profile_hash,
            profile_data,
        } => {
            // Try ICC-based conversion if cache is available. Routes through
            // the proofing chain (`chain_per_intent_8bit[intent]`) when the
            // chain has been populated for this intent — the proofing chain
            // is what `convert_color_with_intent` uses for vector paints,
            // so images need it too to match. Without this, an Adobe-RGB
            // image renders via the source profile's direct RGB→sRGB while
            // the surrounding CMYK paint goes through the OutputIntent
            // CMYK→sRGB; the two sRGB outputs diverge. GWG 17.2 calibrates
            // both so they match under correct CMS, and the test's "X"
            // appears whenever the image bypasses the OI roundtrip.
            let intent = stet_graphics::icc::intent_from_pdf_byte(params.rendering_intent);
            if let Some(cache) = icc
                && cache.has_profile(profile_hash)
                && let Some(rgb) =
                    cache.convert_image_8bit_with_intent(profile_hash, data, npixels, intent)
            {
                let mut rgba = vec![255u8; npixels * 4];
                for i in 0..npixels {
                    rgba[i * 4] = rgb[i * 3];
                    rgba[i * 4 + 1] = rgb[i * 3 + 1];
                    rgba[i * 4 + 2] = rgb[i * 3 + 2];
                    // OPM=1 on 4-component (CMYK) ICC profiles
                    if opm_zero_transparent && *n == 4 {
                        let si = i * *n as usize;
                        if si + 3 < data.len()
                            && data[si] == 0
                            && data[si + 1] == 0
                            && data[si + 2] == 0
                            && data[si + 3] == 0
                        {
                            rgba[i * 4 + 3] = 0;
                        }
                    }
                }
                return rgba;
            }
            // Fallback to device equivalent based on component count
            let _ = (profile_hash, profile_data);
            let fallback = match n {
                1 => ImageColorSpace::DeviceGray,
                4 => ImageColorSpace::DeviceCMYK,
                _ => ImageColorSpace::DeviceRGB,
            };
            let p = ImageParams {
                color_space: fallback,
                bits_per_component: 8,
                ..params.clone()
            };
            samples_to_rgba(data, &p, icc, opm_zero_transparent)
        }
        ImageColorSpace::Indexed {
            base,
            hival,
            lookup,
        } => {
            let base_ncomp = base.num_components() as usize;
            // Expand indexed samples to base color space, then convert
            let mut expanded = Vec::with_capacity(npixels * base_ncomp);
            for i in 0..npixels {
                let idx = data.get(i).copied().unwrap_or(0) as usize;
                let idx = idx.min(*hival as usize);
                let offset = idx * base_ncomp;
                for c in 0..base_ncomp {
                    expanded.push(lookup.get(offset + c).copied().unwrap_or(0));
                }
            }
            let p = ImageParams {
                color_space: *base.clone(),
                bits_per_component: 8,
                ..params.clone()
            };
            samples_to_rgba(&expanded, &p, icc, opm_zero_transparent)
        }
        ImageColorSpace::CIEBasedABC { params: cie_params } => {
            let mut rgba = vec![255u8; npixels * 4];
            for i in 0..npixels {
                let si = i * 3;
                let a = data.get(si).copied().unwrap_or(0) as f64 / 255.0;
                let b = data.get(si + 1).copied().unwrap_or(0) as f64 / 255.0;
                let c = data.get(si + 2).copied().unwrap_or(0) as f64 / 255.0;
                let color = DeviceColor::from_cie_abc(a, b, c, cie_params);
                let pi = i * 4;
                rgba[pi] = (color.r * 255.0).round().clamp(0.0, 255.0) as u8;
                rgba[pi + 1] = (color.g * 255.0).round().clamp(0.0, 255.0) as u8;
                rgba[pi + 2] = (color.b * 255.0).round().clamp(0.0, 255.0) as u8;
            }
            rgba
        }
        ImageColorSpace::CIEBasedA { params: cie_params } => {
            let mut rgba = vec![255u8; npixels * 4];
            for i in 0..npixels {
                let val = data.get(i).copied().unwrap_or(0) as f64 / 255.0;
                let color = DeviceColor::from_cie_a(val, cie_params);
                let pi = i * 4;
                rgba[pi] = (color.r * 255.0).round().clamp(0.0, 255.0) as u8;
                rgba[pi + 1] = (color.g * 255.0).round().clamp(0.0, 255.0) as u8;
                rgba[pi + 2] = (color.b * 255.0).round().clamp(0.0, 255.0) as u8;
            }
            rgba
        }
        ImageColorSpace::Lab { range, .. } => {
            let mut rgba = vec![255u8; npixels * 4];
            let a_span = range[1] - range[0];
            let b_span = range[3] - range[2];
            for i in 0..npixels {
                let si = i * 3;
                let l = data.get(si).copied().unwrap_or(0) as f64 / 255.0 * 100.0;
                let a = data.get(si + 1).copied().unwrap_or(0) as f64 / 255.0 * a_span + range[0];
                let b = data.get(si + 2).copied().unwrap_or(0) as f64 / 255.0 * b_span + range[2];
                let color = DeviceColor::from_lab(l, a, b, range);
                let pi = i * 4;
                rgba[pi] = (color.r * 255.0).round().clamp(0.0, 255.0) as u8;
                rgba[pi + 1] = (color.g * 255.0).round().clamp(0.0, 255.0) as u8;
                rgba[pi + 2] = (color.b * 255.0).round().clamp(0.0, 255.0) as u8;
            }
            rgba
        }
        ImageColorSpace::Separation {
            alt_space,
            tint_table,
            ..
        } => {
            // 1 byte per pixel → lookup in tint table → convert alt space to RGB
            // For CMYK alt space with ICC, build bulk CMYK data and convert via ICC
            if matches!(alt_space.as_ref(), ImageColorSpace::DeviceCMYK)
                && let Some(rgba) = tint_separation_via_icc(data, npixels, tint_table, icc)
            {
                return rgba;
            }
            let mut rgba = vec![255u8; npixels * 4];
            let no = tint_table.num_outputs as usize;
            let mut alt_comps = vec![0.0f32; no];
            for i in 0..npixels {
                let tint = data.get(i).copied().unwrap_or(0) as f32 / 255.0;
                tint_table.lookup_1d(tint, &mut alt_comps);
                let (r, g, b) = alt_comps_to_rgb(&alt_comps, alt_space);
                let pi = i * 4;
                rgba[pi] = r;
                rgba[pi + 1] = g;
                rgba[pi + 2] = b;
            }
            rgba
        }
        ImageColorSpace::DeviceN {
            alt_space,
            tint_table,
            ..
        } => {
            let ni = tint_table.num_inputs as usize;
            let no = tint_table.num_outputs as usize;
            // For CMYK alt space with ICC, build bulk CMYK data and convert via ICC
            if matches!(alt_space.as_ref(), ImageColorSpace::DeviceCMYK)
                && let Some(rgba) = tint_devicen_via_icc(data, npixels, ni, tint_table, icc)
            {
                return rgba;
            }
            let mut rgba = vec![255u8; npixels * 4];
            let mut inputs = vec![0.0f32; ni];
            let mut alt_comps = vec![0.0f32; no];
            for i in 0..npixels {
                let si = i * ni;
                for (c, inp) in inputs.iter_mut().enumerate() {
                    *inp = data.get(si + c).copied().unwrap_or(0) as f32 / 255.0;
                }
                tint_table.lookup_nd(&inputs, &mut alt_comps);
                let (r, g, b) = alt_comps_to_rgb(&alt_comps, alt_space);
                let pi = i * 4;
                rgba[pi] = r;
                rgba[pi + 1] = g;
                rgba[pi + 2] = b;
            }
            rgba
        }
        ImageColorSpace::Mask {
            color, polarity, ..
        } => {
            let mut rgba = vec![0u8; npixels * 4];
            let r = (color.r * 255.0).round().clamp(0.0, 255.0) as u8;
            let g = (color.g * 255.0).round().clamp(0.0, 255.0) as u8;
            let b = (color.b * 255.0).round().clamp(0.0, 255.0) as u8;
            let bytes_per_row = (w).div_ceil(8);
            for row in 0..h {
                for col in 0..w {
                    let byte_idx = row * bytes_per_row + col / 8;
                    let bit_offset = 7 - (col % 8);
                    let bit = if byte_idx < data.len() {
                        (data[byte_idx] >> bit_offset) & 1
                    } else {
                        0
                    };
                    let paint = if *polarity { bit == 1 } else { bit == 0 };
                    if paint {
                        let pi = (row * w + col) * 4;
                        rgba[pi] = r;
                        rgba[pi + 1] = g;
                        rgba[pi + 2] = b;
                        rgba[pi + 3] = 255;
                    }
                }
            }
            rgba
        }
        _ => vec![0u8; npixels * 4],
    }
}

/// Convert Separation (1-input) tint table output through ICC CMYK profile.
/// Builds 4-byte CMYK data from tint table, then bulk-converts via ICC 8-bit transform.
fn tint_separation_via_icc(
    data: &[u8],
    npixels: usize,
    tint_table: &TintLookupTable,
    icc: Option<&IccCache>,
) -> Option<Vec<u8>> {
    let cache = icc?;
    let cmyk_hash = cache.default_cmyk_hash()?;
    // Build CMYK byte buffer from tint table
    let mut cmyk_data = vec![0u8; npixels * 4];
    let mut alt_comps = [0.0f32; 4];
    for i in 0..npixels {
        let tint = data.get(i).copied().unwrap_or(0) as f32 / 255.0;
        tint_table.lookup_1d(tint, &mut alt_comps);
        let si = i * 4;
        cmyk_data[si] = (alt_comps[0].clamp(0.0, 1.0) * 255.0).round() as u8;
        cmyk_data[si + 1] = (alt_comps[1].clamp(0.0, 1.0) * 255.0).round() as u8;
        cmyk_data[si + 2] = (alt_comps[2].clamp(0.0, 1.0) * 255.0).round() as u8;
        cmyk_data[si + 3] = (alt_comps[3].clamp(0.0, 1.0) * 255.0).round() as u8;
    }
    let rgb = cache.convert_image_8bit(cmyk_hash, &cmyk_data, npixels)?;
    let mut rgba = vec![255u8; npixels * 4];
    for i in 0..npixels {
        rgba[i * 4] = rgb[i * 3];
        rgba[i * 4 + 1] = rgb[i * 3 + 1];
        rgba[i * 4 + 2] = rgb[i * 3 + 2];
    }
    Some(rgba)
}

/// Convert DeviceN (N-input) tint table output through ICC CMYK profile.
fn tint_devicen_via_icc(
    data: &[u8],
    npixels: usize,
    ni: usize,
    tint_table: &TintLookupTable,
    icc: Option<&IccCache>,
) -> Option<Vec<u8>> {
    let cache = icc?;
    let cmyk_hash = cache.default_cmyk_hash()?;
    let mut cmyk_data = vec![0u8; npixels * 4];
    let mut inputs = vec![0.0f32; ni];
    let mut alt_comps = [0.0f32; 4];
    for i in 0..npixels {
        let si = i * ni;
        for (c, inp) in inputs.iter_mut().enumerate() {
            *inp = data.get(si + c).copied().unwrap_or(0) as f32 / 255.0;
        }
        tint_table.lookup_nd(&inputs, &mut alt_comps);
        let di = i * 4;
        cmyk_data[di] = (alt_comps[0].clamp(0.0, 1.0) * 255.0).round() as u8;
        cmyk_data[di + 1] = (alt_comps[1].clamp(0.0, 1.0) * 255.0).round() as u8;
        cmyk_data[di + 2] = (alt_comps[2].clamp(0.0, 1.0) * 255.0).round() as u8;
        cmyk_data[di + 3] = (alt_comps[3].clamp(0.0, 1.0) * 255.0).round() as u8;
    }
    let rgb = cache.convert_image_8bit(cmyk_hash, &cmyk_data, npixels)?;
    let mut rgba = vec![255u8; npixels * 4];
    for i in 0..npixels {
        rgba[i * 4] = rgb[i * 3];
        rgba[i * 4 + 1] = rgb[i * 3 + 1];
        rgba[i * 4 + 2] = rgb[i * 3 + 2];
    }
    Some(rgba)
}

/// Convert alt-space f32 component values to RGB bytes.
fn alt_comps_to_rgb(comps: &[f32], alt_space: &ImageColorSpace) -> (u8, u8, u8) {
    match alt_space {
        ImageColorSpace::DeviceGray => {
            let g = (comps.first().copied().unwrap_or(0.0).clamp(0.0, 1.0) * 255.0).round() as u8;
            (g, g, g)
        }
        ImageColorSpace::DeviceRGB => {
            let r = (comps.first().copied().unwrap_or(0.0).clamp(0.0, 1.0) * 255.0).round() as u8;
            let g = (comps.get(1).copied().unwrap_or(0.0).clamp(0.0, 1.0) * 255.0).round() as u8;
            let b = (comps.get(2).copied().unwrap_or(0.0).clamp(0.0, 1.0) * 255.0).round() as u8;
            (r, g, b)
        }
        ImageColorSpace::DeviceCMYK => {
            let c = comps.first().copied().unwrap_or(0.0).clamp(0.0, 1.0);
            let m = comps.get(1).copied().unwrap_or(0.0).clamp(0.0, 1.0);
            let y = comps.get(2).copied().unwrap_or(0.0).clamp(0.0, 1.0);
            let k = comps.get(3).copied().unwrap_or(0.0).clamp(0.0, 1.0);
            let r = ((1.0 - (c + k).min(1.0)) * 255.0).round() as u8;
            let g = ((1.0 - (m + k).min(1.0)) * 255.0).round() as u8;
            let b = ((1.0 - (y + k).min(1.0)) * 255.0).round() as u8;
            (r, g, b)
        }
        _ => (0, 0, 0),
    }
}

/// Apply ImageType 4 mask color transparency to RGBA data.
fn apply_mask_color_rgba(rgba: &mut [u8], sample_data: &[u8], params: &ImageParams) {
    let mask_color = match &params.mask_color {
        Some(mc) => mc,
        None => return,
    };
    let ncomp = params.color_space.num_components() as usize;
    let npixels = params.width as usize * params.height as usize;
    let is_range = mask_color.len() == 2 * ncomp;

    for i in 0..npixels {
        let si = i * ncomp;
        let matched = if is_range {
            (0..ncomp).all(|c| {
                let sample = sample_data.get(si + c).copied().unwrap_or(0);
                let min_val = mask_color.get(c * 2).copied().unwrap_or(0);
                let max_val = mask_color.get(c * 2 + 1).copied().unwrap_or(0);
                sample >= min_val && sample <= max_val
            })
        } else {
            (0..ncomp).all(|c| {
                let sample = sample_data.get(si + c).copied().unwrap_or(0);
                let target = mask_color.get(c).copied().unwrap_or(0);
                sample == target
            })
        };
        if matched {
            let pi = i * 4;
            if pi + 3 < rgba.len() {
                rgba[pi] = 0;
                rgba[pi + 1] = 0;
                rgba[pi + 2] = 0;
                rgba[pi + 3] = 0;
            }
        }
    }
}

/// Choose filter quality for image drawing.
///
/// When `interpolate` is false, use Nearest for upscaling (crisp pixel edges)
/// and Bilinear only for downscaling (proper area averaging). When `interpolate`
/// is true, use Bilinear for any scaling.
fn image_filter_quality(transform: Transform, interpolate: bool) -> stet_tiny_skia::FilterQuality {
    let eff_sx = (transform.sx * transform.sx + transform.ky * transform.ky).sqrt();
    let eff_sy = (transform.kx * transform.kx + transform.sy * transform.sy).sqrt();
    let min_scale = eff_sx.min(eff_sy);
    // Near-exact 1:1: Nearest is pixel-perfect and faster
    if (eff_sx - 1.0).abs() < 0.01 && (eff_sy - 1.0).abs() < 0.01 {
        stet_tiny_skia::FilterQuality::Nearest
    } else if !interpolate && min_scale >= 0.95 {
        // Non-interpolated upscaling: nearest-neighbor for crisp pixel edges
        stet_tiny_skia::FilterQuality::Nearest
    } else {
        stet_tiny_skia::FilterQuality::Bilinear
    }
}

/// For rotated/sheared transforms: integer box-filter pre-downsample, leaving
/// the fractional remainder to tiny-skia's bilinear.
///
/// Returns `None` if no pre-scaling is needed.
fn prescale_image(
    rgba_data: &[u8],
    w: u32,
    h: u32,
    transform: Transform,
    interpolate: bool,
) -> Option<(Vec<u8>, u32, u32, Transform)> {
    // Compute effective scale factors from the 2×2 part of the transform.
    let scale_x = (transform.sx * transform.sx + transform.ky * transform.ky).sqrt();
    let scale_y = (transform.kx * transform.kx + transform.sy * transform.sy).sqrt();
    let min_scale = scale_x.min(scale_y);

    // Upscaling: only apply bicubic resampling when Interpolate is true.
    // Per PLRM/PDF spec, non-interpolated images should use nearest-neighbor
    // for upscaling (crisp pixel boundaries, no smoothing).
    if min_scale > 1.05 {
        if interpolate {
            let is_axis_aligned = transform.kx.abs() < 1e-4 && transform.ky.abs() < 1e-4;
            if is_axis_aligned && w >= 2 && h >= 2 {
                let dw = (w as f32 * transform.sx.abs()).round().max(1.0) as u32;
                let dh = (h as f32 * transform.sy.abs()).round().max(1.0) as u32;
                if dw > w || dh > h {
                    let resampled = bicubic_resample(rgba_data, w, h, dw, dh);
                    let new_sx = transform.sx * w as f32 / dw as f32;
                    let new_sy = transform.sy * h as f32 / dh as f32;
                    let adjusted = Transform::from_row(
                        new_sx,
                        transform.ky,
                        transform.kx,
                        new_sy,
                        transform.tx,
                        transform.ty,
                    );
                    return Some((resampled, dw, dh, adjusted));
                }
            }
        }
        return None;
    }

    // Near 1:1 — no prescaling needed.
    if min_scale >= 0.95 {
        return None;
    }

    // Axis-aligned: use area-average box filter to target dimensions.
    // Much faster than Lanczos3 and produces equally good results for downscaling.
    let is_axis_aligned = transform.kx.abs() < 1e-4 && transform.ky.abs() < 1e-4;
    if is_axis_aligned && w >= 2 && h >= 2 {
        let dw = (w as f32 * transform.sx.abs()).ceil().max(1.0) as u32;
        let dh = (h as f32 * transform.sy.abs()).ceil().max(1.0) as u32;
        if dw < w || dh < h {
            let resampled = box_resample(rgba_data, w, h, dw, dh);
            // Adjust transform so scale ≈ ±1 (sign preserved), same translation.
            let new_sx = transform.sx * w as f32 / dw as f32;
            let new_sy = transform.sy * h as f32 / dh as f32;
            let adjusted = Transform::from_row(
                new_sx,
                transform.ky,
                transform.kx,
                new_sy,
                transform.tx,
                transform.ty,
            );
            return Some((resampled, dw, dh, adjusted));
        }
    }

    // Fallback for rotated/sheared: integer box filter.
    let factor = (1.0 / min_scale) as u32;
    if factor < 2 || w < factor || h < factor {
        return None;
    }
    let nw = w / factor;
    let nh = h / factor;
    if nw == 0 || nh == 0 {
        return None;
    }
    let area = factor * factor;
    let half = area / 2;
    let stride = w as usize * 4;
    let mut out = vec![0u8; (nw * nh * 4) as usize];
    for dy in 0..nh {
        for dx in 0..nw {
            let (mut r, mut g, mut b, mut a) = (0u32, 0u32, 0u32, 0u32);
            let sy0 = (dy * factor) as usize;
            let sx0 = (dx * factor) as usize;
            for iy in 0..factor as usize {
                let row = (sy0 + iy) * stride + sx0 * 4;
                for ix in 0..factor as usize {
                    let i = row + ix * 4;
                    r += rgba_data[i] as u32;
                    g += rgba_data[i + 1] as u32;
                    b += rgba_data[i + 2] as u32;
                    a += rgba_data[i + 3] as u32;
                }
            }
            let di = (dy * nw + dx) as usize * 4;
            out[di] = ((r + half) / area) as u8;
            out[di + 1] = ((g + half) / area) as u8;
            out[di + 2] = ((b + half) / area) as u8;
            out[di + 3] = ((a + half) / area) as u8;
        }
    }
    let f = factor as f32;
    let adjusted = Transform::from_row(
        transform.sx * f,
        transform.ky * f,
        transform.kx * f,
        transform.sy * f,
        transform.tx,
        transform.ty,
    );
    Some((out, nw, nh, adjusted))
}

/// Translate a device-space ClipRect into band-local coordinates.
fn translate_clip_rect(rect: &ClipRect, y_start: u32, band_h: u32) -> ClipRect {
    ClipRect {
        x0: rect.x0,
        y0: rect.y0.saturating_sub(y_start).min(band_h),
        x1: rect.x1,
        y1: rect.y1.saturating_sub(y_start).min(band_h),
    }
}

/// Ensure an image transform maps to at least 1 device pixel in each dimension.
///
/// PDFs commonly draw rules and borders using tiny image masks (1×1 or 4×1 pixels)
/// scaled via the CTM to thin rectangles. At low DPI these can map to sub-pixel
/// device dimensions and vanish. This adjusts the transform's scale components
/// so the image covers at least 1 pixel in each direction.
fn enforce_min_image_size(transform: Transform, img_w: u32, img_h: u32) -> Transform {
    // Effective device-space dimensions
    let eff_w =
        ((transform.sx * img_w as f32).powi(2) + (transform.ky * img_w as f32).powi(2)).sqrt();
    let eff_h =
        ((transform.kx * img_h as f32).powi(2) + (transform.sy * img_h as f32).powi(2)).sqrt();

    if eff_w >= 1.0 && eff_h >= 1.0 {
        return transform;
    }

    // Only boost if the image is a thin rule (large aspect ratio).
    // Small images that are sub-pixel in both dimensions (e.g. tiny dots)
    // are left as-is — boosting them would create visible artifacts.
    let ratio = eff_w.max(eff_h) / eff_w.min(eff_h).max(0.001);
    if ratio < 3.0 {
        return transform;
    }

    let mut t = transform;
    if eff_w < 1.0 && eff_w > 0.001 {
        let boost = 1.0 / eff_w;
        t.sx *= boost;
        t.ky *= boost;
    }
    if eff_h < 1.0 && eff_h > 0.001 {
        let boost = 1.0 / eff_h;
        t.kx *= boost;
        t.sy *= boost;
    }
    t
}

/// Compute minimum line width for hairline strokes at a given DPI and CTM.
/// Returns the minimum width in user-space units that ensures at least
/// 0.5 device pixels at ≤150 DPI or 1.0 device pixel above 150 DPI.
fn hairline_min_width(ctm: &Matrix, dpi: f64) -> f64 {
    let (a, b, c, d) = (ctm.a, ctm.b, ctm.c, ctm.d);
    let sum_sq = a * a + b * b + c * c + d * d;
    let diff = ((a * a + b * b - c * c - d * d).powi(2) + 4.0 * (a * c + b * d).powi(2)).sqrt();
    let s_max = (0.5 * (sum_sq + diff)).max(0.0).sqrt();
    let min_px = if dpi <= 150.0 { 0.5 } else { 1.0 };
    if s_max > 1e-10 {
        min_px / s_max
    } else {
        min_px
    }
}

/// True when the paint's source CMYK is K-only (C=M=Y=0, any K).
/// Used to route OPM 0 DeviceCMYK paints that encode "K-only" — like
/// `0 0 0 0.5 k` — through the per-pixel overprint path, so the no-op delta
/// skip can preserve a spot-painted backdrop at pixels where K already equals
/// the source value.
fn is_k_only_src(color: &DeviceColor) -> bool {
    if let Some((c, m, y, _k)) = color.native_cmyk {
        c == 0.0 && m == 0.0 && y == 0.0
    } else {
        false
    }
}

/// Detect a DeviceGray paint that should be promoted to CMYK_K for overprint.
///
/// DeviceGray `g` sets `painted_channels = 0` and leaves `native_cmyk = None`,
/// so overprint dispatch can't see it as a K-ink paint. When overprint is
/// active we re-describe the paint as DeviceCMYK `(0, 0, 0, 1-g)` with
/// `painted_channels = CMYK_K`: it flows through the subset path, only the K
/// plate is touched, and the pixmap is updated multiplicatively so any
/// backdrop spot contribution survives.
fn needs_gray_promotion(
    overprint: bool,
    painted_channels: u8,
    is_device_cmyk: bool,
    color: &DeviceColor,
) -> Option<f64> {
    if !overprint
        || painted_channels != 0
        || is_device_cmyk
        || color.native_cmyk.is_some()
        || color.process_cmyk.is_some()
    {
        return None;
    }
    let r = color.r;
    if (r - color.g).abs() > f64::EPSILON || (r - color.b).abs() > f64::EPSILON {
        return None;
    }
    Some(r.clamp(0.0, 1.0))
}

/// Promote a gray `FillParams` to a DeviceCMYK K-only overprint description if
/// the paint qualifies (see [`needs_gray_promotion`]).
fn maybe_promote_gray_fill<'a>(
    params: &'a FillParams,
    buf: &'a mut Option<FillParams>,
) -> &'a FillParams {
    if let Some(gray) = needs_gray_promotion(
        params.overprint,
        params.painted_channels,
        params.is_device_cmyk,
        &params.color,
    ) {
        let mut promoted = params.clone();
        promoted.is_device_cmyk = true;
        promoted.painted_channels = stet_graphics::device::CMYK_K;
        promoted.color.native_cmyk = Some((0.0, 0.0, 0.0, 1.0 - gray));
        promoted.color.process_cmyk = Some((0.0, 0.0, 0.0, 1.0 - gray));
        *buf = Some(promoted);
        return buf.as_ref().unwrap();
    }
    params
}

/// Promote a gray `StrokeParams` to a DeviceCMYK K-only overprint description.
fn maybe_promote_gray_stroke<'a>(
    params: &'a StrokeParams,
    buf: &'a mut Option<StrokeParams>,
) -> &'a StrokeParams {
    if let Some(gray) = needs_gray_promotion(
        params.overprint,
        params.painted_channels,
        params.is_device_cmyk,
        &params.color,
    ) {
        let mut promoted = params.clone();
        promoted.is_device_cmyk = true;
        promoted.painted_channels = stet_graphics::device::CMYK_K;
        promoted.color.native_cmyk = Some((0.0, 0.0, 0.0, 1.0 - gray));
        promoted.color.process_cmyk = Some((0.0, 0.0, 0.0, 1.0 - gray));
        *buf = Some(promoted);
        return buf.as_ref().unwrap();
    }
    params
}

/// Build a stroke with minimum line-width enforcement (shared by trait impl and band rendering).
/// `dpi` is the device resolution, used to select the hairline minimum width:
/// at ≤150 DPI use 0.6 device pixels; above 150 DPI use 1.0 device pixel.
fn build_stroke(params: &StrokeParams, dpi: f64) -> Stroke {
    let min_lw = hairline_min_width(&params.ctm, dpi);
    let mut stroke = Stroke {
        width: (params.line_width as f32).max(min_lw as f32),
        line_cap: to_line_cap(params.line_cap),
        line_join: to_line_join(params.line_join),
        miter_limit: params.miter_limit as f32,
        ..Stroke::default()
    };
    if !params.dash_pattern.array.is_empty() {
        let mut dash_array: Vec<f32> = params
            .dash_pattern
            .array
            .iter()
            .map(|&v| v as f32)
            .collect();
        // PostScript allows odd-length dash arrays (implicitly doubled),
        // but tiny-skia requires even length. Double odd arrays to match PS semantics.
        if dash_array.len() % 2 == 1 {
            let clone = dash_array.clone();
            dash_array.extend_from_slice(&clone);
        }
        if let Some(dash) = StrokeDash::new(dash_array, params.dash_pattern.offset as f32) {
            stroke.dash = Some(dash);
        }
    }
    stroke
}

/// Apply stroke adjustment: snap axis-aligned path segments to device pixel
/// centers so thin strokes render with consistent weight.
///
/// For a stroke of width W in device pixels:
/// - Odd-integer width (1, 3, ...): snap to half-pixel (floor(x) + 0.5)
/// - Even-integer width or non-integer: snap to pixel edge (round(x))
/// - For hairlines (device width < 1.5): always snap to half-pixel
///
/// Only axis-aligned segments (horizontal/vertical lines) are snapped.
/// Diagonal/curved segments are left as-is since snapping would distort them.
///
/// Check whether a CTM indicates the path is already in device space (identity
/// or simple Y-flip/translation). Stroke adjustment snaps coordinates to pixel
/// boundaries, which only makes sense when path coordinates are device pixels.
/// PDF Form XObjects with large scale factors (e.g. [405, 0, 0, 283, ...]) would
/// cause catastrophic snapping if treated as device-space paths.
fn ctm_is_device_space(ctm: &Matrix) -> bool {
    (ctm.a.abs() - 1.0).abs() < 0.01
        && ctm.b.abs() < 0.01
        && ctm.c.abs() < 0.01
        && (ctm.d.abs() - 1.0).abs() < 0.01
}

/// Apply stroke adjustment for viewport rendering.
///
/// Path coordinates are in reference-DPI device space. The viewport transform
/// maps them to output pixels: out = (ref - vp_origin) * scale.
/// We snap in output pixel space then map back to reference space.
fn stroke_adjust_path_viewport(
    path: &PsPath,
    device_width: f64,
    scale_x: f64,
    scale_y: f64,
    vp_x: f64,
    vp_y: f64,
) -> PsPath {
    let use_half_pixel = device_width < 1.5 || (device_width.round() as i32) % 2 == 1;

    // Snap a reference-space coordinate to the output pixel grid, then map back
    let snap_x = |v: f64| -> f64 {
        let out = (v - vp_x) * scale_x;
        let snapped = if use_half_pixel {
            out.floor() + 0.5
        } else {
            out.round()
        };
        snapped / scale_x + vp_x
    };
    let snap_y = |v: f64| -> f64 {
        let out = (v - vp_y) * scale_y;
        let snapped = if use_half_pixel {
            out.floor() + 0.5
        } else {
            out.round()
        };
        snapped / scale_y + vp_y
    };

    let mut result = PsPath::new();
    let mut prev_x = 0.0_f64;
    let mut prev_y = 0.0_f64;

    for seg in &path.segments {
        match *seg {
            PathSegment::MoveTo(x, y) => {
                prev_x = x;
                prev_y = y;
                result.segments.push(PathSegment::MoveTo(x, y));
            }
            PathSegment::LineTo(x, y) => {
                let is_horizontal = (y - prev_y).abs() < 1e-6;
                let is_vertical = (x - prev_x).abs() < 1e-6;

                if is_horizontal {
                    let snapped_y = snap_y(y);
                    if let Some(PathSegment::MoveTo(_, ly) | PathSegment::LineTo(_, ly)) =
                        result.segments.last_mut()
                    {
                        *ly = snapped_y;
                    }
                    result.segments.push(PathSegment::LineTo(x, snapped_y));
                    prev_x = x;
                    prev_y = snapped_y;
                } else if is_vertical {
                    let snapped_x = snap_x(x);
                    if let Some(PathSegment::MoveTo(lx, _) | PathSegment::LineTo(lx, _)) =
                        result.segments.last_mut()
                    {
                        *lx = snapped_x;
                    }
                    result.segments.push(PathSegment::LineTo(snapped_x, y));
                    prev_x = snapped_x;
                    prev_y = y;
                } else {
                    result.segments.push(PathSegment::LineTo(x, y));
                    prev_x = x;
                    prev_y = y;
                }
            }
            PathSegment::CurveTo {
                x1,
                y1,
                x2,
                y2,
                x3,
                y3,
            } => {
                result.segments.push(PathSegment::CurveTo {
                    x1,
                    y1,
                    x2,
                    y2,
                    x3,
                    y3,
                });
                prev_x = x3;
                prev_y = y3;
            }
            PathSegment::ClosePath => {
                result.segments.push(PathSegment::ClosePath);
            }
        }
    }
    result
}

/// Process a single display list element into a pixmap using the given render context.
///
/// This unified function handles both band rendering (scale=1.0) and viewport
/// rendering (arbitrary scale). Band rendering is viewport rendering with
/// `scale_x = scale_y = 1.0`.
fn render_element(
    pixmap: &mut Pixmap,
    band_state: &mut BandState,
    element: &DisplayElement,
    ctx: &RenderContext<'_>,
) {
    match element {
        DisplayElement::Fill { path, params } => {
            // DeviceGray with overprint behaves as a K-only process paint —
            // promote it to DeviceCMYK (0, 0, 0, 1-gray) with painted_channels
            // set to CMYK_K so it flows through the overprint subset path,
            // preserving backdrop CMY plates and the spot-derived visual
            // instead of knocking the pixmap out with plain RGB gray.
            let mut promoted_fill: Option<FillParams> = None;
            let params = maybe_promote_gray_fill(params, &mut promoted_fill);
            // Use the overprint compositing path whenever the fill needs
            // per-channel CMYK rendering. Five cases trigger it:
            //   1. Subset painted_channels (Separation /Magenta, DeviceN, etc.)
            //      — only the named channels touch the buffer; the rest are
            //      preserved from the backdrop.
            //   2. DeviceCMYK + OPM 1 — zero-valued components don't paint, so
            //      a per-pixel filter is required.
            //   3. Custom spot (painted_channels=0, non-CMYK, with native_cmyk)
            //      under overprint — process plates must be preserved; the
            //      spot's alt-CMYK only contributes multiplicatively to RGB.
            //   4. DeviceCMYK + overprint (any OPM) with CMYK_ALL — the per-
            //      pixel path lets us recognise a "no-op" overprint (src CMYK
            //      == backdrop CMYK) and leave the pixmap untouched, which
            //      preserves any spot-derived colour already visible there.
            //   5. (Combinations of the above.)
            // Only fires for Normal blend; non-Normal blend modes handle zero
            // values through their blend math, not through overprint filtering.
            // Includes text glyphs: when overprint is meaningful (the test
            // suite's GWG 1.0 swatches f/a use Separation /Magenta + glyphs),
            // correctness wins over the slight AA difference vs tiny-skia.
            let painted = params.painted_channels;
            let subset_channels = painted != 0 && painted != stet_graphics::device::CMYK_ALL;
            let opm1_cmyk = params.is_device_cmyk && params.overprint_mode == 1;
            // Real Separation/DeviceN custom spots set `process_cmyk` (even pure
            // spots set it to `(0, 0, 0, 0)`); ICCBased RGB routed through the
            // proofing chain has `native_cmyk` populated but leaves
            // `process_cmyk == None`. Per PDF 1.7 §11.7.4.5 a non-process source
            // colour space (CalGray/CalRGB/Lab/ICCBased) must paint as if /OP
            // were false — gating on `process_cmyk.is_some()` keeps ICCBased RGB
            // out of the overprint path so GWG 13.3 (ICC RGB X over CMYK BG)
            // knocks out instead of preserving the backdrop's CMYK plates.
            let custom_spot = painted == 0
                && !params.is_device_cmyk
                && params.color.native_cmyk.is_some()
                && params.color.process_cmyk.is_some();
            // A "near-K-only" DeviceCMYK paint under OPM 0 — e.g. `0 0 0 0.5 k`
            // — matches the Black-component plate of a DeviceN [Black, spot]
            // backdrop exactly. Routing it through the per-pixel path lets the
            // no-op-delta skip preserve the spot-derived colour instead of
            // wiping it with plain grey (GWG 3.0 "50% K over spot").
            let is_k_only_cmyk =
                params.is_device_cmyk && params.overprint_mode == 0 && is_k_only_src(&params.color);
            let needs_overprint = params.overprint
                && band_state.cmyk_buffer.is_some()
                && params.blend_mode == 0
                && (subset_channels || opm1_cmyk || custom_spot || is_k_only_cmyk);

            if needs_overprint {
                let mut cmyk_buf = band_state.cmyk_buffer.take().unwrap();
                let (mut op_bg, mut op_touched) = band_state.take_op_buffers(ctx.out_w, ctx.out_h);
                let spot_mask = band_state.take_spot_mask(ctx.out_w, ctx.out_h);
                render_overprint_fill(
                    pixmap,
                    &mut cmyk_buf,
                    &mut op_bg,
                    &mut op_touched,
                    &spot_mask,
                    band_state,
                    path,
                    params,
                    ctx.vp_x,
                    ctx.vp_y,
                    ctx.scale_x,
                    ctx.scale_y,
                    ctx.out_w,
                    ctx.out_h,
                    ctx.icc,
                    ctx.no_aa,
                );
                band_state.cmyk_buffer = Some(cmyk_buf);
                band_state.restore_op_buffers(op_bg, op_touched);
                band_state.restore_spot_mask(spot_mask);
            } else {
                let Some(skia_path) = build_skia_path(path) else {
                    return;
                };
                let mut temp_mask = None;
                let Some(mask_ref) = resolve_clip_mask(
                    &band_state.clip_region,
                    &mut temp_mask,
                    ctx.out_w,
                    ctx.out_h,
                ) else {
                    return;
                };
                let paint =
                    to_paint_alpha(&params.color, params.alpha, params.blend_mode, ctx.no_aa);
                let transform = ctx.transform(&params.ctm);

                // Detect degenerate fill paths: rectangles/lines with zero extent
                // in one dimension. These are commonly used in PDFs to draw table
                // grid lines as zero-width or zero-height filled rectangles.
                // Since they have no area, fill_path produces nothing. Render them
                // as hairline strokes instead.
                if is_degenerate_fill(path) {
                    let stroke = Stroke {
                        width: 1.0,
                        ..Stroke::default()
                    };
                    pixmap.stroke_path(&skia_path, &paint, &stroke, transform, mask_ref);
                } else {
                    let fill_rule = to_fill_rule(&params.fill_rule);
                    pixmap.fill_path(&skia_path, &paint, fill_rule, transform, mask_ref);
                }

                // Update CMYK tracking buffer for non-overprint fills
                if band_state.cmyk_buffer.is_some() {
                    let mut cmyk_buf = band_state.cmyk_buffer.take().unwrap();
                    let mut spot_mask = band_state.take_spot_mask(ctx.out_w, ctx.out_h);
                    update_cmyk_buffer_for_fill(
                        &mut cmyk_buf,
                        &mut spot_mask,
                        path,
                        params,
                        ctx.vp_x,
                        ctx.vp_y,
                        ctx.scale_x,
                        ctx.scale_y,
                        ctx.out_w,
                        ctx.out_h,
                        &band_state.clip_region,
                        ctx.no_aa,
                        ctx.icc,
                    );
                    band_state.cmyk_buffer = Some(cmyk_buf);
                    band_state.restore_spot_mask(spot_mask);
                }
            }
        }
        DisplayElement::Stroke { path, params } => {
            let mut promoted_stroke: Option<StrokeParams> = None;
            let params = maybe_promote_gray_stroke(params, &mut promoted_stroke);
            let transform = ctx.transform(&params.ctm);
            // Build stroke using the composited transform so hairline width
            // calculations account for the actual output resolution.
            let vp_ctm = Matrix {
                a: transform.sx as f64,
                b: transform.ky as f64,
                c: transform.kx as f64,
                d: transform.sy as f64,
                tx: 0.0,
                ty: 0.0,
            };
            let vp_params = StrokeParams {
                ctm: vp_ctm,
                ..params.clone()
            };
            let stroke = build_stroke(&vp_params, ctx.effective_dpi);

            // Apply stroke adjustment — snap in output device space
            let adjusted;
            let draw_path = if params.stroke_adjust
                && stroke.width <= 2.0
                && ctm_is_device_space(&params.ctm)
            {
                adjusted = stroke_adjust_path_viewport(
                    path,
                    stroke.width as f64,
                    ctx.scale_x as f64,
                    ctx.scale_y as f64,
                    ctx.vp_x as f64,
                    ctx.vp_y as f64,
                );
                &adjusted
            } else {
                path
            };

            // Mirror the Fill gating: per-channel CMYK rendering kicks in for
            // subset painted_channels (Separation /Magenta, DeviceN, etc.), for
            // DeviceCMYK + OPM 1 (zero-valued source components don't paint),
            // or for a custom spot (painted=0, non-CMYK) under overprint — so
            // the spot applies multiplicatively to RGB without disturbing the
            // process plates. GWG 1.0 swatch a/b/f/g need this for the magenta
            // X stroke that overlays the same path the fill already drew.
            let painted = params.painted_channels;
            let subset_channels = painted != 0 && painted != stet_graphics::device::CMYK_ALL;
            let opm1_cmyk = params.is_device_cmyk && params.overprint_mode == 1;
            // Mirror the Fill custom-spot gate: ICCBased RGB (proofing-chain
            // `native_cmyk`, no `process_cmyk`) must not reach the overprint
            // path. PDF 1.7 §11.7.4.5: non-process source spaces paint as if
            // /OP were false.
            let custom_spot = painted == 0
                && !params.is_device_cmyk
                && params.color.native_cmyk.is_some()
                && params.color.process_cmyk.is_some();
            let is_k_only_cmyk =
                params.is_device_cmyk && params.overprint_mode == 0 && is_k_only_src(&params.color);
            let needs_overprint = params.overprint
                && band_state.cmyk_buffer.is_some()
                && params.blend_mode == 0
                && (subset_channels || opm1_cmyk || custom_spot || is_k_only_cmyk);

            let Some(skia_path) = build_skia_path(draw_path) else {
                return;
            };
            let mut temp_mask = None;
            let Some(mask_ref) = resolve_clip_mask(
                &band_state.clip_region,
                &mut temp_mask,
                ctx.out_w,
                ctx.out_h,
            ) else {
                return;
            };

            if needs_overprint {
                // Convert the stroke outline to a fill path and route it
                // through the same per-channel CMYK compositing logic the
                // fill path uses, so the post-overprint result lands in the
                // pixmap (not the raw source colour).
                let mut cmyk_buf = band_state.cmyk_buffer.take().unwrap();
                let (mut op_bg, mut op_touched) = band_state.take_op_buffers(ctx.out_w, ctx.out_h);
                let spot_mask = band_state.take_spot_mask(ctx.out_w, ctx.out_h);
                render_overprint_stroke(
                    pixmap,
                    &mut cmyk_buf,
                    &mut op_bg,
                    &mut op_touched,
                    &spot_mask,
                    band_state,
                    &skia_path,
                    &stroke,
                    transform,
                    params,
                    ctx.out_w,
                    ctx.out_h,
                    ctx.icc,
                    ctx.no_aa,
                );
                band_state.cmyk_buffer = Some(cmyk_buf);
                band_state.restore_op_buffers(op_bg, op_touched);
                band_state.restore_spot_mask(spot_mask);
            } else {
                let paint =
                    to_paint_alpha(&params.color, params.alpha, params.blend_mode, ctx.no_aa);
                pixmap.stroke_path(&skia_path, &paint, &stroke, transform, mask_ref);

                if band_state.cmyk_buffer.is_some() {
                    let mut cmyk_buf = band_state.cmyk_buffer.take().unwrap();
                    let mut spot_mask = band_state.take_spot_mask(ctx.out_w, ctx.out_h);
                    update_cmyk_buffer_for_stroke(
                        &mut cmyk_buf,
                        &mut spot_mask,
                        draw_path,
                        params,
                        &stroke,
                        transform,
                        ctx.out_w,
                        ctx.out_h,
                        &band_state.clip_region,
                        ctx.no_aa,
                        ctx.icc,
                    );
                    band_state.cmyk_buffer = Some(cmyk_buf);
                    band_state.restore_spot_mask(spot_mask);
                }
            }
        }
        DisplayElement::Clip { path, params } => {
            clip_path_unified(band_state, path, params, ctx);
        }
        DisplayElement::InitClip => {
            if let Some(ClipRegion::Mask(mask)) = band_state.clip_region.take() {
                band_state.recycle_mask(mask);
            }
            band_state.clip_region = None;
        }
        DisplayElement::ErasePage => {
            pixmap.fill(Color::TRANSPARENT);
            if let Some(ClipRegion::Mask(mask)) = band_state.clip_region.take() {
                band_state.recycle_mask(mask);
            }
            band_state.clip_region = None;
        }
        DisplayElement::Image {
            sample_data,
            params,
        } => {
            let iw = params.width;
            let ih = params.height;
            if iw == 0 || ih == 0 {
                return;
            }

            let needs_overprint = params.overprint
                && band_state.cmyk_buffer.is_some()
                && image_supports_overprint(&params.color_space);

            if needs_overprint {
                let mut cmyk_buf = band_state.cmyk_buffer.take().unwrap();
                let (mut op_bg, mut op_touched) = band_state.take_op_buffers(ctx.out_w, ctx.out_h);
                render_overprint_image(
                    pixmap,
                    &mut cmyk_buf,
                    &mut op_bg,
                    &mut op_touched,
                    band_state,
                    sample_data,
                    params,
                    ctx.vp_x,
                    ctx.vp_y,
                    ctx.scale_x,
                    ctx.scale_y,
                    ctx.out_w,
                    ctx.out_h,
                    ctx.icc,
                );
                band_state.cmyk_buffer = Some(cmyk_buf);
                band_state.restore_op_buffers(op_bg, op_touched);
            } else if let Some(pp) = ctx
                .preprocessed
                .and_then(|pp| pp.get(ctx.elem_idx))
                .and_then(|e| e.as_ref())
            {
                // Fast path: use pre-converted and prescaled image data.
                // Only the per-band translation differs; scale factors are cached.
                let Some(image_inv) = params.image_matrix.invert() else {
                    return;
                };
                let combined = params.ctm.concat(&image_inv);
                let raw_transform = ctx.transform(&combined);
                let transform = Transform::from_row(
                    pp.adj_sx,
                    pp.adj_ky,
                    pp.adj_kx,
                    pp.adj_sy,
                    raw_transform.tx,
                    raw_transform.ty,
                );

                let Some(img_pixmap) =
                    stet_tiny_skia::PixmapRef::from_bytes(&pp.data, pp.width, pp.height)
                else {
                    return;
                };
                #[allow(unused_assignments)]
                let mut temp_mask = None;
                let mask_ref = match &band_state.clip_region {
                    None => None,
                    Some(ClipRegion::Mask(m)) => Some(m as &Mask),
                    Some(ClipRegion::Rect(rect)) => {
                        if rect.is_empty() {
                            return;
                        } else if rect.is_full_page(ctx.out_w, ctx.out_h) {
                            None
                        } else {
                            temp_mask = rect.make_mask(ctx.out_w, ctx.out_h);
                            temp_mask.as_ref()
                        }
                    }
                };
                let img_paint = stet_tiny_skia::PixmapPaint {
                    quality: pp.quality,
                    opacity: params.alpha as f32,
                    blend_mode: u8_to_blend_mode(params.blend_mode),
                };
                pixmap.draw_pixmap(0, 0, img_pixmap, &img_paint, transform, mask_ref);

                // Update CMYK tracking buffer for non-overprint images on the
                // fast path. Reading from the post-draw pixmap means the same
                // helper handles native-CMYK and non-CMYK source images, even
                // though `pp.data` is prescaled and we no longer have a
                // matching native RGBA buffer.
                if let Some(ref mut cmyk_buf) = band_state.cmyk_buffer {
                    update_cmyk_buffer_for_image(
                        cmyk_buf,
                        sample_data,
                        pixmap.data(),
                        params,
                        ctx.vp_x,
                        ctx.vp_y,
                        ctx.scale_x,
                        ctx.scale_y,
                        ctx.out_w,
                        ctx.out_h,
                        &band_state.clip_region,
                        ctx.icc,
                    );
                }
            } else {
                // Use pre-converted RGBA from image cache when available
                let owned_rgba;
                let rgba_data: &[u8] = if let Some(cached) =
                    ctx.image_cache.and_then(|c| c.get(ctx.elem_idx))
                {
                    cached
                } else {
                    owned_rgba = {
                        let mut rgba =
                            samples_to_rgba(sample_data, params, ctx.icc, ctx.opm_zero_transparent);
                        if params.mask_color.is_some() {
                            apply_mask_color_rgba(&mut rgba, sample_data, params);
                        }
                        rgba
                    };
                    &owned_rgba
                };
                let expected = (iw * ih * 4) as usize;
                if rgba_data.len() < expected {
                    return;
                }
                let Some(image_inv) = params.image_matrix.invert() else {
                    return;
                };
                let combined = params.ctm.concat(&image_inv);
                let raw_transform = enforce_min_image_size(ctx.transform(&combined), iw, ih);

                // Pre-scale images that are being downscaled. Even non-interpolated
                // images need proper area averaging when shrinking — "no interpolation"
                // means don't smooth when *upscaling*, but downscaling without averaging
                // produces aliased garbage.
                let prescaled =
                    prescale_image(rgba_data, iw, ih, raw_transform, params.interpolate);
                let (img_data, img_w, img_h, transform) = match &prescaled {
                    Some((data, w, h, t)) => (data.as_slice(), *w, *h, *t),
                    None => (rgba_data, iw, ih, raw_transform),
                };

                let Some(img_pixmap) =
                    stet_tiny_skia::PixmapRef::from_bytes(img_data, img_w, img_h)
                else {
                    return;
                };
                #[allow(unused_assignments)]
                let mut temp_mask = None;
                let mask_ref = match &band_state.clip_region {
                    None => None,
                    Some(ClipRegion::Mask(m)) => Some(m as &Mask),
                    Some(ClipRegion::Rect(rect)) => {
                        if rect.is_empty() {
                            return;
                        } else if rect.is_full_page(ctx.out_w, ctx.out_h) {
                            None
                        } else {
                            temp_mask = rect.make_mask(ctx.out_w, ctx.out_h);
                            temp_mask.as_ref()
                        }
                    }
                };
                let img_paint = stet_tiny_skia::PixmapPaint {
                    quality: image_filter_quality(transform, params.interpolate),
                    opacity: params.alpha as f32,
                    blend_mode: u8_to_blend_mode(params.blend_mode),
                };
                pixmap.draw_pixmap(0, 0, img_pixmap, &img_paint, transform, mask_ref);

                // Update CMYK tracking buffer for non-overprint images. Sample
                // the now-composited pixmap so non-CMYK source images can be
                // reverse-converted to CMYK via the system profile.
                if let Some(ref mut cmyk_buf) = band_state.cmyk_buffer {
                    update_cmyk_buffer_for_image(
                        cmyk_buf,
                        sample_data,
                        pixmap.data(),
                        params,
                        ctx.vp_x,
                        ctx.vp_y,
                        ctx.scale_x,
                        ctx.scale_y,
                        ctx.out_w,
                        ctx.out_h,
                        &band_state.clip_region,
                        ctx.icc,
                    );
                }
            }
        }
        DisplayElement::AxialShading { params } => {
            let mut temp_mask = None;
            let Some(mask_ref) = resolve_clip_mask(
                &band_state.clip_region,
                &mut temp_mask,
                ctx.out_w,
                ctx.out_h,
            ) else {
                return;
            };
            render_axial_shading(
                pixmap,
                params,
                ctx.vp_x,
                ctx.vp_y,
                ctx.scale_x,
                ctx.scale_y,
                mask_ref,
                ctx.no_aa,
                band_state.cmyk_buffer.as_deref_mut(),
                ctx.icc,
            );
        }
        DisplayElement::RadialShading { params } => {
            let mut temp_mask = None;
            let Some(mask_ref) = resolve_clip_mask(
                &band_state.clip_region,
                &mut temp_mask,
                ctx.out_w,
                ctx.out_h,
            ) else {
                return;
            };
            render_radial_shading(
                pixmap,
                params,
                ctx.vp_x,
                ctx.vp_y,
                ctx.scale_x,
                ctx.scale_y,
                mask_ref,
                ctx.no_aa,
                band_state.cmyk_buffer.as_deref_mut(),
                ctx.icc,
            );
        }
        DisplayElement::MeshShading { params } => {
            let mut temp_mask = None;
            let Some(mask_ref) = resolve_clip_mask(
                &band_state.clip_region,
                &mut temp_mask,
                ctx.out_w,
                ctx.out_h,
            ) else {
                return;
            };
            render_mesh_shading(
                pixmap,
                params,
                ctx.vp_x,
                ctx.vp_y,
                ctx.scale_x,
                ctx.scale_y,
                mask_ref,
                band_state.cmyk_buffer.as_deref_mut(),
                ctx.icc,
            );
        }
        DisplayElement::PatchShading { params } => {
            let mut temp_mask = None;
            let Some(mask_ref) = resolve_clip_mask(
                &band_state.clip_region,
                &mut temp_mask,
                ctx.out_w,
                ctx.out_h,
            ) else {
                return;
            };
            render_patch_shading(
                pixmap,
                params,
                ctx.vp_x,
                ctx.vp_y,
                ctx.scale_x,
                ctx.scale_y,
                mask_ref,
                band_state.cmyk_buffer.as_deref_mut(),
                ctx.icc,
            );
        }
        DisplayElement::PatternFill { params } => {
            render_pattern_fill(pixmap, band_state, params, ctx);
        }
        DisplayElement::Group { elements, params } => {
            render_group(pixmap, band_state, elements, params, ctx);
        }
        DisplayElement::SoftMasked {
            mask,
            content,
            params,
            mask_cache,
        } => {
            render_soft_masked(pixmap, band_state, mask, content, params, mask_cache, ctx);
        }
        DisplayElement::Text { .. } => {} // PDF-only, ignored by rasterizer
        DisplayElement::OcgGroup {
            elements,
            visibility,
        } => {
            // Visible groups render every child. OFF-by-default groups still
            // apply Clip/InitClip so the band's clip state stays in sync —
            // otherwise a transient clip from the previous group would leak
            // into the next visible one. Paint ops are skipped; that's what
            // "hidden layer" means.
            let visible = ctx.layer_set.evaluate(visibility);
            for (idx, elem) in elements.elements().iter().enumerate() {
                if !visible
                    && !matches!(elem, DisplayElement::Clip { .. } | DisplayElement::InitClip)
                {
                    continue;
                }
                let elem_ctx = RenderContext {
                    elem_idx: idx,
                    ..*ctx
                };
                render_element(pixmap, band_state, elem, &elem_ctx);
            }
        }
        _ => {}
    }
}

/// Compute the cropped output-pixel region for a group's device-space bounding box.
///
/// Returns `(crop_x, crop_y, crop_w, crop_h)` in output pixels, or `None` if
/// the group is entirely outside the viewport or cropping isn't worthwhile.
fn compute_group_crop(bbox: &[f64; 4], ctx: &RenderContext<'_>) -> Option<(i32, i32, u32, u32)> {
    // Transform device-space bbox to output pixel coords
    let px_min = ((bbox[0] as f32 - ctx.vp_x) * ctx.scale_x).floor() as i32;
    let py_min = ((bbox[1] as f32 - ctx.vp_y) * ctx.scale_y).floor() as i32;
    let px_max = ((bbox[2] as f32 - ctx.vp_x) * ctx.scale_x).ceil() as i32;
    let py_max = ((bbox[3] as f32 - ctx.vp_y) * ctx.scale_y).ceil() as i32;

    // Clip to output bounds
    let x0 = px_min.max(0);
    let y0 = py_min.max(0);
    let x1 = px_max.min(ctx.out_w as i32);
    let y1 = py_max.min(ctx.out_h as i32);

    if x0 >= x1 || y0 >= y1 {
        return None;
    }

    let crop_w = (x1 - x0) as u32;
    let crop_h = (y1 - y0) as u32;

    // Only crop if it saves at least 25% of pixels
    let crop_pixels = crop_w as u64 * crop_h as u64;
    let full_pixels = ctx.out_w as u64 * ctx.out_h as u64;
    if crop_pixels * 4 >= full_pixels * 3 {
        return None;
    }

    Some((x0, y0, crop_w, crop_h))
}

/// Apply a separable PDF blend mode in DeviceCMYK using the spec's "effective"
/// inversion convention (PDF 1.7 §11.3.5.2): the inverse value `1−c` is used as
/// input to the RGB-style blend function, and the result is inverted back.
fn blend_cmyk_separable_channel(cb: f64, cs: f64, mode: u8) -> f64 {
    let cbi = 1.0 - cb;
    let csi = 1.0 - cs;
    let result_inv = match mode {
        1 => cbi * csi,             // Multiply
        2 => cbi + csi - cbi * csi, // Screen
        3 => {
            // Overlay(b, s) = HardLight(s, b)
            if cbi <= 0.5 {
                2.0 * cbi * csi
            } else {
                1.0 - 2.0 * (1.0 - cbi) * (1.0 - csi)
            }
        }
        4 => cbi.min(csi), // Darken
        5 => cbi.max(csi), // Lighten
        6 => {
            // ColorDodge
            if csi >= 1.0 {
                1.0
            } else {
                (cbi / (1.0 - csi)).min(1.0)
            }
        }
        7 => {
            // ColorBurn
            if csi <= 0.0 {
                0.0
            } else {
                1.0 - ((1.0 - cbi) / csi).min(1.0)
            }
        }
        8 => {
            // HardLight
            if csi <= 0.5 {
                2.0 * cbi * csi
            } else {
                1.0 - 2.0 * (1.0 - cbi) * (1.0 - csi)
            }
        }
        9 => {
            // SoftLight (Adobe formulation)
            let d = if cbi <= 0.25 {
                ((16.0 * cbi - 12.0) * cbi + 4.0) * cbi
            } else {
                cbi.sqrt()
            };
            if csi <= 0.5 {
                cbi - (1.0 - 2.0 * csi) * cbi * (1.0 - cbi)
            } else {
                cbi + (2.0 * csi - 1.0) * (d - cbi)
            }
        }
        10 => (cbi - csi).abs(),           // Difference
        11 => cbi + csi - 2.0 * cbi * csi, // Exclusion
        _ => csi,                          // Normal/fallback
    };
    1.0 - result_inv.clamp(0.0, 1.0)
}

/// Apply a non-separable HSL-style PDF blend mode (Hue, Saturation, Color,
/// Luminosity) in DeviceCMYK. Per the spec, the inverted CMY components are
/// treated as "effective RGB" and the standard non-separable formulas are
/// applied; the K channel is taken from the source (it acts as the source's
/// luminosity contribution for the purposes of the blend).
fn blend_cmyk_nonseparable(cb: [f64; 4], cs: [f64; 4], mode: u8) -> [f64; 4] {
    fn lum(c: [f64; 3]) -> f64 {
        0.3 * c[0] + 0.59 * c[1] + 0.11 * c[2]
    }
    fn clip_color(mut c: [f64; 3]) -> [f64; 3] {
        let l = lum(c);
        let n = c[0].min(c[1]).min(c[2]);
        let x = c[0].max(c[1]).max(c[2]);
        if n < 0.0 {
            for ci in c.iter_mut() {
                *ci = l + (*ci - l) * l / (l - n);
            }
        }
        if x > 1.0 {
            for ci in c.iter_mut() {
                *ci = l + (*ci - l) * (1.0 - l) / (x - l);
            }
        }
        c
    }
    fn set_lum(c: [f64; 3], l: f64) -> [f64; 3] {
        let d = l - lum(c);
        clip_color([c[0] + d, c[1] + d, c[2] + d])
    }
    fn sat(c: [f64; 3]) -> f64 {
        c[0].max(c[1]).max(c[2]) - c[0].min(c[1]).min(c[2])
    }
    fn set_sat(c: [f64; 3], s: f64) -> [f64; 3] {
        // Index components by rank: min, mid, max.
        let mut idx = [0usize, 1, 2];
        idx.sort_by(|a, b| {
            c[*a]
                .partial_cmp(&c[*b])
                .unwrap_or(std::cmp::Ordering::Equal)
        });
        let (i_min, i_mid, i_max) = (idx[0], idx[1], idx[2]);
        let mut out = c;
        if c[i_max] > c[i_min] {
            out[i_mid] = (c[i_mid] - c[i_min]) * s / (c[i_max] - c[i_min]);
            out[i_max] = s;
        } else {
            out[i_mid] = 0.0;
            out[i_max] = 0.0;
        }
        out[i_min] = 0.0;
        out
    }

    let cb_rgb = [1.0 - cb[0], 1.0 - cb[1], 1.0 - cb[2]];
    let cs_rgb = [1.0 - cs[0], 1.0 - cs[1], 1.0 - cs[2]];
    let result_rgb = match mode {
        12 => set_lum(set_sat(cs_rgb, sat(cb_rgb)), lum(cb_rgb)), // Hue
        13 => set_lum(set_sat(cb_rgb, sat(cs_rgb)), lum(cb_rgb)), // Saturation
        14 => set_lum(cs_rgb, lum(cb_rgb)),                       // Color
        15 => set_lum(cb_rgb, lum(cs_rgb)),                       // Luminosity
        _ => cs_rgb,
    };
    // Hue/Saturation/Color preserve the backdrop's luminosity, which in CMYK
    // is carried primarily by the K channel. Luminosity transfers the source's
    // luminosity, so it takes K from the source.
    let result_k = if mode == 15 { cs[3] } else { cb[3] };
    [
        (1.0 - result_rgb[0]).clamp(0.0, 1.0),
        (1.0 - result_rgb[1]).clamp(0.0, 1.0),
        (1.0 - result_rgb[2]).clamp(0.0, 1.0),
        result_k,
    ]
}

/// Render a transparency group into a pixmap.
/// Device-space axis-aligned bbox of a path, computed from its segment
/// endpoints and curve control points. Returned as (x0, y0, x1, y1) with
/// x0 ≤ x1, y0 ≤ y1. Returns `None` for an empty path.
fn ps_path_bbox(path: &PsPath) -> Option<(f64, f64, f64, f64)> {
    let mut it = path.segments.iter().filter_map(|seg| match *seg {
        PathSegment::MoveTo(x, y) | PathSegment::LineTo(x, y) => Some(vec![(x, y)]),
        PathSegment::CurveTo {
            x1,
            y1,
            x2,
            y2,
            x3,
            y3,
        } => Some(vec![(x1, y1), (x2, y2), (x3, y3)]),
        PathSegment::ClosePath => None,
    });
    let first = it.next()?.into_iter().next()?;
    let (mut x0, mut y0) = first;
    let (mut x1, mut y1) = first;
    for seg_points in std::iter::once(vec![first]).chain(it) {
        for (x, y) in seg_points {
            x0 = x0.min(x);
            y0 = y0.min(y);
            x1 = x1.max(x);
            y1 = y1.max(y);
        }
    }
    Some((x0, y0, x1, y1))
}

/// True when rectangle `inner` fits inside `outer` with `tolerance` slack
/// (positive tolerance = inner may protrude by up to `tolerance` units).
fn bbox_contains(outer: (f64, f64, f64, f64), inner: (f64, f64, f64, f64), tolerance: f64) -> bool {
    inner.0 >= outer.0 - tolerance
        && inner.1 >= outer.1 - tolerance
        && inner.2 <= outer.2 + tolerance
        && inner.3 <= outer.3 + tolerance
}

/// Detect the GWG "reference-under-test" authoring pattern: a parent Fill
/// that will be fully covered by the first Fill of a following isolated
/// transparency group. When detected, the parent's Fill can be skipped —
/// its AA edges otherwise bleed into the dest under the group's partial-
/// alpha source during composite-back, producing a visible outline where
/// Acrobat shows none (see GWG 16.2 Opacity(0%) analysis in
/// `project_icc_profile_stability.md`).
///
/// Returns indices in `elements` that should be skipped. Safety conditions:
///   1. Parent fill is fully opaque, Normal blend.
///   2. Next paint (ignoring Clip/InitClip) is an isolated, alpha-1,
///      Normal-blend Group whose first paint is a Fill with matching
///      path (within tolerance) and the same opacity/blend conditions.
///   3. The group's declared bbox fully contains the parent path's bbox
///      — i.e. the form's own BBox clip won't carve the fill away.
///   4. Every Clip element between the parent fill and the group, and
///      every Clip between the group's start and its first fill, has a
///      bbox that also fully contains the parent path — so no additional
///      clip can cut the group's first fill to a subset of the parent's
///      extent.
///   5. PDF's isolated transparency semantics guarantee that once the
///      first fill establishes alpha=1 at the parent-path pixels, later
///      Normal-blend paints can only add colour there; alpha can't
///      decrease. So nothing in the group's tail can re-expose backdrop,
///      even without auditing those elements explicitly.
fn compute_obscured_fill_skips(elements: &DisplayList) -> Vec<usize> {
    let mut skips = Vec::new();
    let els = elements.elements();
    for i in 0..els.len() {
        let DisplayElement::Fill {
            path: parent_path,
            params: parent_params,
        } = &els[i]
        else {
            continue;
        };
        if (parent_params.alpha - 1.0).abs() > 1e-6 || parent_params.blend_mode != 0 {
            continue;
        }
        let Some(parent_bbox) = ps_path_bbox(parent_path) else {
            continue;
        };
        // Walk forward past Clip/InitClip between parent fill and the
        // group. Each such clip must contain the parent's extent; any
        // other element type ends the scan.
        let mut j = i + 1;
        let mut clips_ok = true;
        while j < els.len() {
            match &els[j] {
                DisplayElement::InitClip => {}
                DisplayElement::Clip {
                    path: clip_path, ..
                } => match ps_path_bbox(clip_path) {
                    Some(cb) if bbox_contains(cb, parent_bbox, 0.5) => {}
                    _ => {
                        clips_ok = false;
                        break;
                    }
                },
                _ => break,
            }
            j += 1;
        }
        if !clips_ok {
            continue;
        }
        let Some(DisplayElement::Group {
            elements: group_elements,
            params: group_params,
        }) = els.get(j)
        else {
            continue;
        };
        if !group_params.isolated
            || (group_params.alpha - 1.0).abs() > 1e-6
            || group_params.blend_mode != 0
        {
            continue;
        }
        // The form's declared BBox acts as a clip inside the group; the
        // parent's fill must fit inside it or the group's output will be
        // carved away where we'd rely on coverage.
        let group_bbox = (
            group_params.bbox[0],
            group_params.bbox[1],
            group_params.bbox[2],
            group_params.bbox[3],
        );
        if !bbox_contains(group_bbox, parent_bbox, 0.5) {
            continue;
        }
        // Walk past Clip/InitClip inside the group to its first paint,
        // requiring each clip to contain the parent's extent.
        let inner_els = group_elements.elements();
        let mut k = 0;
        let mut inner_clips_ok = true;
        while k < inner_els.len() {
            match &inner_els[k] {
                DisplayElement::InitClip => {}
                DisplayElement::Clip {
                    path: clip_path, ..
                } => match ps_path_bbox(clip_path) {
                    Some(cb) if bbox_contains(cb, parent_bbox, 0.5) => {}
                    _ => {
                        inner_clips_ok = false;
                        break;
                    }
                },
                _ => break,
            }
            k += 1;
        }
        if !inner_clips_ok {
            continue;
        }
        let Some(DisplayElement::Fill {
            path: group_path,
            params: group_fill_params,
        }) = inner_els.get(k)
        else {
            continue;
        };
        if (group_fill_params.alpha - 1.0).abs() > 1e-6 || group_fill_params.blend_mode != 0 {
            continue;
        }
        if paths_approximately_equal(parent_path, group_path, 0.5) {
            skips.push(i);
        }
    }
    skips
}

/// True when two device-space paths have the same segment sequence and
/// matching endpoints within `tolerance` device pixels per coordinate.
/// Used by `compute_obscured_fill_skips` to recognise PDF-authored patterns
/// where the same logical X path is emitted twice with sub-unit rounding
/// differences (GWG test suite authoring style from InDesign CS6).
fn paths_approximately_equal(a: &PsPath, b: &PsPath, tolerance: f64) -> bool {
    if a.segments.len() != b.segments.len() {
        return false;
    }
    for (sa, sb) in a.segments.iter().zip(b.segments.iter()) {
        let close_pair = |(x1, y1): (f64, f64), (x2, y2): (f64, f64)| -> bool {
            (x1 - x2).abs() <= tolerance && (y1 - y2).abs() <= tolerance
        };
        match (sa, sb) {
            (PathSegment::MoveTo(x1, y1), PathSegment::MoveTo(x2, y2)) => {
                if !close_pair((*x1, *y1), (*x2, *y2)) {
                    return false;
                }
            }
            (PathSegment::LineTo(x1, y1), PathSegment::LineTo(x2, y2)) => {
                if !close_pair((*x1, *y1), (*x2, *y2)) {
                    return false;
                }
            }
            (
                PathSegment::CurveTo {
                    x1: ax1,
                    y1: ay1,
                    x2: ax2,
                    y2: ay2,
                    x3: ax3,
                    y3: ay3,
                },
                PathSegment::CurveTo {
                    x1: bx1,
                    y1: by1,
                    x2: bx2,
                    y2: by2,
                    x3: bx3,
                    y3: by3,
                },
            ) => {
                if !close_pair((*ax1, *ay1), (*bx1, *by1))
                    || !close_pair((*ax2, *ay2), (*bx2, *by2))
                    || !close_pair((*ax3, *ay3), (*bx3, *by3))
                {
                    return false;
                }
            }
            (PathSegment::ClosePath, PathSegment::ClosePath) => {}
            _ => return false,
        }
    }
    true
}

///
/// Creates an offscreen pixmap, renders the group's child elements into it,
/// then composites back onto the parent with the group's blend mode and alpha.
fn render_group(
    pixmap: &mut Pixmap,
    band_state: &mut BandState,
    elements: &DisplayList,
    params: &stet_graphics::display_list::GroupParams,
    ctx: &RenderContext<'_>,
) {
    if params.knockout {
        render_knockout_group(pixmap, band_state, elements, params, ctx);
        return;
    }

    let crop = compute_group_crop(&params.bbox, ctx);

    let (eff_w, eff_h, crop_x, crop_y, eff_vp_x, eff_vp_y) = match crop {
        Some((cx, cy, cw, ch)) => (
            cw,
            ch,
            cx,
            cy,
            ctx.vp_x + cx as f32 / ctx.scale_x,
            ctx.vp_y + cy as f32 / ctx.scale_y,
        ),
        None => (ctx.out_w, ctx.out_h, 0, 0, ctx.vp_x, ctx.vp_y),
    };

    let Some(mut offscreen) = Pixmap::new(eff_w, eff_h) else {
        return;
    };

    // Decide upfront whether the composite-back will run in CMYK. The CMYK
    // path needs the parent backdrop pre-loaded into the offscreen so that
    // per-element painting accumulates in the right starting state. The
    // sRGB contribution-extraction path renders against an empty offscreen
    // for non-Normal BMs to avoid anti-aliased clip artifacts at the BBox
    // edges (the diff-against-backdrop logic mishandles partially-blended
    // edge pixels otherwise).
    use stet_graphics::display_list::GroupColorSpace;

    // Allocate a CMYK buffer for the group when:
    //   - it tracks overprint, OR
    //   - the parent already has one (CMYK context inheritance), OR
    //   - this group itself or one of its descendants declares an explicit
    //     `/CS DeviceCMYK`, meaning compositing within it needs CMYK math.
    let needs_group_cmyk = has_overprint_elements(elements)
        || band_state.cmyk_buffer.is_some()
        || params.color_space == GroupColorSpace::DeviceCMYK
        || has_cmyk_group(elements);

    // Decide whether to run the per-pixel CMYK composite-back. The default
    // (gated) rule restricts it to the cases the prior rendering session
    // explicitly validated. The `STET_FORCE_CMYK_COMPOSITE_BACK=1` env var
    // bypasses both gates and switches to the principled rule that the rest
    // of this plan will adopt — useful for A/B-comparing the broader fix
    // before flipping the default in Step 9.
    let force_cmyk_compose =
        std::env::var_os("STET_FORCE_CMYK_COMPOSITE_BACK").as_deref() == Some("1".as_ref());
    // The knockout group's coverage pass disables CMYK composite-back so the
    // painter falls through to the simple sRGB draw_pixmap path. Without this,
    // a white-source painter (CMYK 0,0,0,0) would be skipped by the
    // composite-back's "source==backdrop" guard against the transparent
    // coverage backdrop, and pass 2 wouldn't capture the painter's coverage.
    //
    // The color pass widens the gate to all non-Normal blend modes so a
    // `/CS DeviceCMYK` knockout group's painters with separable blends like
    // Screen / ColorDodge / Overlay / SoftLight blend in CMYK math (matching
    // the spec) instead of in tiny-skia's sRGB blend.
    let plan_cmyk_compose = match ctx.knockout_painter_pass {
        KnockoutPainterPass::CoveragePass => false,
        KnockoutPainterPass::ColorPass => {
            !params.isolated
                && params.blend_mode != 0
                && needs_group_cmyk
                && band_state.cmyk_buffer.is_some()
                && group_content_is_native_cmyk(elements)
        }
        KnockoutPainterPass::None if force_cmyk_compose => {
            // Principled rule: non-isolated group with an inversion-sensitive
            // blend mode (Difference, Exclusion, Hue, Saturation, Color,
            // Luminosity) whose painters all supply native CMYK source colors.
            //
            // The blend-mode restriction is intentional: bm 10..=15 produce
            // visibly *wrong* results in sRGB (the GWG 16.0 transparency test
            // exists exactly to expose this), so CMYK math is unambiguously
            // correct there. The separable modes 1..=9 (Multiply, Screen, etc.)
            // are spec-defensible in either color space but look noticeably
            // different — most renderers blend them in sRGB, and PDFs authored
            // for that look "wrong" if we suddenly switch them to CMYK math.
            //
            // The painter-set restriction (no shadings, no non-CMYK content)
            // exists because the parallel CMYK buffer can only faithfully track
            // single-CMYK-value-per-pixel painters; gradients interpolate
            // differently in pixmap RGB vs buffer CMYK and the divergence makes
            // the composite-back read stale source values.
            !params.isolated
                && matches!(params.blend_mode, 10..=15)
                && needs_group_cmyk
                && band_state.cmyk_buffer.is_some()
                && group_content_is_native_cmyk(elements)
        }
        KnockoutPainterPass::None => {
            // Default rule: only the inversion-sensitive blend modes
            // (Difference, Exclusion, HSL non-separable) need CMYK math; the
            // separable modes 1..=9 are spec-defensible in either color space
            // and most sRGB-authored PDFs expect them to blend in sRGB.
            let inversion_sensitive = !params.isolated
                && matches!(params.blend_mode, 10..=15)
                && group_only_native_cmyk_fills(elements);
            // GWG 16.2 ("Transparency Basic Blend Modes — DeviceCMYK,
            // Isolated") nests non-isolated `/CS DeviceCMYK` painter sub-groups
            // inside an isolated `/CS DeviceCMYK` group, with the swatch's
            // blend mode applied at the inner Do. Per PDF spec §11.6.7 the
            // compositing for those inner groups must happen in DeviceCMYK,
            // not sRGB — otherwise their colored X-shape produces the wrong
            // color and fails to cover the painter-A black X. The explicit
            // `/CS DeviceCMYK` declaration plus the isolated parent are the
            // spec signal that the author wants CMYK-space compositing for
            // a fresh transparent backdrop. The `parent_group_isolated`
            // gate keeps the rule from firing for non-isolated parents like
            // 907 page 28's chart panels, where the existing sRGB
            // contribution-extraction path correctly preserves anti-aliased
            // gray strokes.
            //
            // GWG 16.1 ("Transparency Basic Blend Modes — ICCBasedRGB")
            // exercises the same DeviceCMYK page group but the parent is
            // *non-isolated*, so the `parent_group_isolated` gate refused
            // to fire and every separable blend swatch fell back to sRGB
            // blending (visible as the test's "X" markers). PDF/X
            // workflows already declare their target compositing space via
            // `/OutputIntents`, and the proofing chain in
            // `register_profile_with_n` flips `IccCache::proofing_enabled`
            // on once that's been honoured. Use that as the PDF/X-specific
            // signal for "blend in DeviceCMYK regardless of group
            // isolation"; non-proofing documents (907 p28 et al.) keep
            // the original `parent_group_isolated` requirement.
            let proofing_enabled = ctx.icc.is_some_and(|c| c.proofing_enabled());
            // Per PDF 1.7 §11.6.6, a transparency group with no `/CS` inherits
            // its color space from the enclosing group. When the parent has
            // already allocated a CMYK buffer (the only way `cmyk_buffer` is
            // `Some` on this band_state when we enter `render_group`), the
            // parent's effective compositing space is DeviceCMYK and an
            // `Inherited` child should join it. Without this, GWG 16.4 swatch
            // groups (no `/CS`) fell back to sRGB blending and the Multiply /
            // Color Burn blends produced visible X markers.
            let effective_cs_is_cmyk = params.color_space == GroupColorSpace::DeviceCMYK
                || (params.color_space == GroupColorSpace::Inherited
                    && band_state.cmyk_buffer.is_some());
            let cmyk_group_blend = !params.isolated
                && (ctx.parent_group_isolated || proofing_enabled)
                && params.blend_mode != 0
                && effective_cs_is_cmyk
                && needs_group_cmyk
                && band_state.cmyk_buffer.is_some()
                && group_content_is_native_cmyk(elements);
            inversion_sensitive || cmyk_group_blend
        }
    };
    // Non-isolated groups with non-Normal blend modes on the sRGB path
    // need a two-pass render: once against the backdrop (for correct
    // internal blending) and once against transparent (to extract the
    // group's shape/alpha for the proper source-contribution formula).
    let needs_alpha_extraction = !params.isolated
        && params.blend_mode != 0
        && !plan_cmyk_compose
        && !ctx.alpha_extraction_pass;
    let needs_backdrop_preload =
        !params.isolated && (params.blend_mode == 0 || plan_cmyk_compose || needs_alpha_extraction);
    let backdrop = if needs_backdrop_preload {
        let data = if crop.is_some() {
            copy_backdrop_crop(pixmap, crop_x, crop_y, eff_w, eff_h)
        } else {
            pixmap.data().to_vec()
        };
        offscreen.data_mut().copy_from_slice(&data);
        Some(data)
    } else {
        None
    };
    let group_cmyk = if needs_group_cmyk {
        let buf_size = eff_w as usize * eff_h as usize * 4;
        let mut buf = vec![0.0f32; buf_size];
        if let Some(ref parent_cmyk) = band_state.cmyk_buffer {
            let parent_stride = ctx.out_w as usize * 4;
            let group_stride = eff_w as usize * 4;
            for gy in 0..eff_h as usize {
                let py = crop_y as usize + gy;
                if py < ctx.out_h as usize {
                    let p_start = py * parent_stride + crop_x as usize * 4;
                    let g_start = gy * group_stride;
                    let copy_len = group_stride.min(parent_stride - crop_x as usize * 4);
                    buf[g_start..g_start + copy_len]
                        .copy_from_slice(&parent_cmyk[p_start..p_start + copy_len]);
                }
            }
        }
        Some(buf)
    } else {
        None
    };

    // Snapshot the pre-load CMYK so the composite-back can identify pixels
    // the group actually modified. Without a separate snapshot we'd have to
    // diff against the parent CMYK buffer, which would lose any in-place
    // updates to the parent across the group's lifetime.
    let backdrop_cmyk: Option<Vec<f32>> = if !params.isolated {
        group_cmyk.clone()
    } else {
        None
    };

    let mut group_band = BandState {
        clip_region: None,
        spare_mask: None,
        clip_mask_cache: HashMap::new(),
        clip_mask_seen: HashSet::new(),
        mask_pool: Vec::new(),
        cmyk_buffer: group_cmyk,
        op_bg_snapshot: None,
        op_touched: None,
        spot_mask: None,
    };

    let group_ctx = RenderContext {
        vp_x: eff_vp_x,
        vp_y: eff_vp_y,
        scale_x: ctx.scale_x,
        scale_y: ctx.scale_y,
        out_w: eff_w,
        out_h: eff_h,
        effective_dpi: ctx.effective_dpi,
        icc: ctx.icc,
        image_cache: None, // Group elements don't use parent image cache
        preprocessed: None,
        elem_idx: 0,
        no_aa: ctx.no_aa,
        opm_zero_transparent: ctx.opm_zero_transparent,
        knockout_painter_pass: ctx.knockout_painter_pass,
        // The children of this group see *this* group as their parent.
        parent_group_isolated: params.isolated,
        alpha_extraction_pass: ctx.alpha_extraction_pass,
        layer_set: ctx.layer_set,
    };

    let skip_indices = compute_obscured_fill_skips(elements);
    for (idx, elem) in elements.elements().iter().enumerate() {
        if skip_indices.contains(&idx) {
            continue;
        }
        let elem_ctx = RenderContext {
            elem_idx: idx,
            ..group_ctx
        };
        render_element(&mut offscreen, &mut group_band, elem, &elem_ctx);
    }

    // Second pass: render against transparent to extract the group's
    // shape/alpha.  Only needed for the sRGB two-pass composite-back
    // path (non-isolated, non-Normal blend, no CMYK compose).
    let alpha_offscreen = if needs_alpha_extraction {
        let mut iso = Pixmap::new(eff_w, eff_h);
        if let Some(ref mut iso_pm) = iso {
            let mut iso_band = BandState {
                clip_region: None,
                spare_mask: None,
                clip_mask_cache: HashMap::new(),
                clip_mask_seen: HashSet::new(),
                mask_pool: Vec::new(),
                cmyk_buffer: None,
                op_bg_snapshot: None,
                op_touched: None,
                spot_mask: None,
            };
            let iso_ctx = RenderContext {
                parent_group_isolated: true,
                alpha_extraction_pass: true,
                ..group_ctx
            };
            for (idx, elem) in elements.elements().iter().enumerate() {
                let elem_ctx = RenderContext {
                    elem_idx: idx,
                    ..iso_ctx
                };
                render_element(iso_pm, &mut iso_band, elem, &elem_ctx);
            }
        }
        iso
    } else {
        None
    };

    let mut temp_mask = None;
    let mask_ref = match resolve_clip_mask(
        &band_state.clip_region,
        &mut temp_mask,
        ctx.out_w,
        ctx.out_h,
    ) {
        None => return, // empty clip → nothing visible
        Some(m) => m,
    };

    // Coverage pass override: force opacity 1.0 + Normal blend so the
    // painter's shape reaches the coverage offscreen even when the
    // original alpha was 0 (Opacity 0% test) or the blend mode would
    // erase the source against the transparent coverage backdrop.
    let coverage_params;
    let effective_params: &stet_graphics::display_list::GroupParams =
        if ctx.knockout_painter_pass == KnockoutPainterPass::CoveragePass {
            coverage_params = stet_graphics::display_list::GroupParams {
                alpha: 1.0,
                blend_mode: 0,
                ..params.clone()
            };
            &coverage_params
        } else {
            params
        };

    let mut cmyk_compose_done = false;
    if let Some(backdrop) = &backdrop {
        // Non-isolated group. For the inversion-sensitive blend modes
        // (Difference, Exclusion) and the HSL non-separable modes (Hue,
        // Saturation, Color, Luminosity), tiny-skia's sRGB blend math gives
        // visibly wrong results for the GWG 16.0 transparency test, where
        // the source colors are chosen so that, in CMYK, the blend produces
        // the backdrop color exactly. Run the composite-back per pixel in
        // CMYK for those modes when the inner content is exclusively
        // native-CMYK fills (so the inner CMYK buffer faithfully represents
        // the source). The other separable modes (Multiply / Lighten /
        // Darken / etc.) and non-CMYK content stay on the existing sRGB
        // contribution-extraction path because their CMYK pipeline currently
        // depends on `interpolate_cmyk_from_stops`, which derives CMYK from
        // sRGB via the lossy `(1−r,1−g,1−b,0)` inverse for shadings/images
        // and would shift their colors. Lifting that restriction requires
        // computing exact CMYK from each shading/image's source color space
        // (e.g. running the DeviceN tint transform), which is a larger
        // change than this fix attempts.
        let inner_cmyk = group_band.cmyk_buffer.as_deref();
        let pre_cmyk = backdrop_cmyk.as_deref();
        if plan_cmyk_compose && let (Some(inner), Some(pre)) = (inner_cmyk, pre_cmyk) {
            composite_non_isolated_cmyk(
                pixmap,
                band_state.cmyk_buffer.as_deref_mut(),
                &offscreen,
                inner,
                pre,
                backdrop,
                effective_params,
                mask_ref,
                crop_x,
                crop_y,
                ctx.icc,
            );
            cmyk_compose_done = true;
        } else if let Some(ref alpha_os) = alpha_offscreen {
            composite_non_isolated_extracted(
                pixmap,
                &offscreen,
                alpha_os,
                backdrop,
                effective_params,
                mask_ref,
                crop_x,
                crop_y,
            );
        } else {
            composite_non_isolated_group_cropped(
                pixmap,
                &offscreen,
                backdrop,
                effective_params,
                mask_ref,
                crop_x,
                crop_y,
            );
        }
    } else {
        let paint = stet_tiny_skia::PixmapPaint {
            opacity: effective_params.alpha as f32,
            blend_mode: u8_to_blend_mode(effective_params.blend_mode),
            quality: stet_tiny_skia::FilterQuality::Nearest,
        };
        pixmap.draw_pixmap(
            crop_x,
            crop_y,
            offscreen.as_ref(),
            &paint,
            Transform::identity(),
            mask_ref,
        );
    }

    // Write group CMYK buffer back to parent. Skip when the CMYK composite-back
    // already wrote the blended values into the parent CMYK buffer — running
    // `copy_cmyk_buffer_to_parent` afterwards would overwrite those blended
    // values with the inner buffer's raw source colors, breaking subsequent
    // siblings that read the parent CMYK as their backdrop.
    if !cmyk_compose_done
        && let (Some(group_cmyk), Some(parent_cmyk)) =
            (&group_band.cmyk_buffer, &mut band_state.cmyk_buffer)
    {
        copy_cmyk_buffer_to_parent(
            parent_cmyk,
            group_cmyk,
            offscreen.data(),
            crop_x as usize,
            crop_y as usize,
            eff_w as usize,
            eff_h as usize,
            ctx.out_w as usize,
            ctx.out_h as usize,
        );
    }
}

/// CMYK-aware composite-back for a non-isolated transparency group.
///
/// For each pixel in the group's region:
///   1. If the inner CMYK buffer matches the snapshot taken when the group
///      started, the group painted nothing there → leave the parent unchanged.
///   2. Otherwise apply the group blend mode in DeviceCMYK using the spec's
///      effective inversion formulas (`blend_cmyk_separable_channel` or
///      `blend_cmyk_nonseparable`), convert the result to sRGB through the
///      ICC system CMYK profile so it sits seamlessly next to the rest of the
///      page, and write the result to both the parent pixmap and (when
///      present) the parent CMYK buffer.
#[allow(clippy::too_many_arguments)]
fn composite_non_isolated_cmyk(
    target: &mut Pixmap,
    parent_cmyk: Option<&mut [f32]>,
    source: &Pixmap,
    source_cmyk: &[f32],
    backdrop_cmyk: &[f32],
    backdrop_pixels: &[u8],
    params: &stet_graphics::display_list::GroupParams,
    clip_mask: Option<&stet_tiny_skia::Mask>,
    crop_x: i32,
    crop_y: i32,
    icc: Option<&IccCache>,
) {
    let cw = source.width() as usize;
    let ch = source.height() as usize;
    let target_w = target.width() as usize;
    let target_h = target.height() as usize;

    let opacity = params.alpha.clamp(0.0, 1.0);
    let blend_mode = params.blend_mode;
    let is_nonseparable = matches!(blend_mode, 12..=15);

    let target_data = target.data_mut();
    let target_stride = target_w * 4;
    let group_stride = cw * 4;

    let clip_data = clip_mask.map(|m| m.data());

    for gy in 0..ch {
        let ty = crop_y + gy as i32;
        if ty < 0 || ty as usize >= target_h {
            continue;
        }
        let ty = ty as usize;
        let group_row = gy * group_stride;
        let target_row = ty * target_stride;

        for gx in 0..cw {
            let tx = crop_x + gx as i32;
            if tx < 0 || tx as usize >= target_w {
                continue;
            }
            let tx = tx as usize;
            let gi = group_row + gx * 4;
            let ti = target_row + tx * 4;

            // Did the group actually paint this pixel?
            let bc = backdrop_cmyk[gi] as f64;
            let bm = backdrop_cmyk[gi + 1] as f64;
            let by_ = backdrop_cmyk[gi + 2] as f64;
            let bk = backdrop_cmyk[gi + 3] as f64;
            let sc = source_cmyk[gi] as f64;
            let sm = source_cmyk[gi + 1] as f64;
            let sy_ = source_cmyk[gi + 2] as f64;
            let sk = source_cmyk[gi + 3] as f64;
            if (sc - bc).abs() < 1.0 / 255.0
                && (sm - bm).abs() < 1.0 / 255.0
                && (sy_ - by_).abs() < 1.0 / 255.0
                && (sk - bk).abs() < 1.0 / 255.0
            {
                continue;
            }

            // Clip mask coverage in target coordinates.
            let cov = if let Some(cd) = clip_data {
                cd[ty * target_w + tx] as f64 / 255.0
            } else {
                1.0
            };
            if cov <= 0.0 {
                continue;
            }

            // Transparent-backdrop fast path: when the backdrop pixmap's alpha
            // is 0 the parent group hasn't painted this pixel, so PDF spec
            // §11.4.6 says the blended result reduces to α_s · source — the
            // blend formula must NOT be applied. Without this check, formulas
            // like ColorBurn / ColorDodge / Lighten / Screen produce visibly
            // wrong colors (yellow instead of orange-yellow, white instead of
            // the source) because an all-zero CMYK backdrop is identical to
            // opaque white in CMYK terms. Using the pixmap alpha as the
            // sentinel correctly distinguishes "truly nothing painted"
            // (alpha 0) from "white painted" (alpha 1, CMYK 0,0,0,0).
            //
            // For this branch we composite the source pixmap directly via
            // SourceOver (rather than converting source CMYK→sRGB) so the
            // source's per-pixel alpha — including anti-aliased edges and
            // partially-transparent paint like 907 page 28's gray rules —
            // is preserved. The CMYK→sRGB direct path used the un-modulated
            // painter color and the group opacity, which forced antialiased
            // gray strokes to opaque black.
            let backdrop_alpha = backdrop_pixels[gi + 3];
            let backdrop_transparent = backdrop_alpha == 0;

            let mix = cov * opacity;
            let dst_a = target_data[ti + 3] as f64 / 255.0;

            if backdrop_transparent {
                // SourceOver of the source pixmap (already correctly rendered
                // for transparent-backdrop semantics) modulated by the group's
                // mix factor. To ensure inner-group AA edges don't leave
                // sliver gaps where the outer parent pixmap had previously
                // drawn a near-identical path (GWG 16.2 directly-drawn black
                // X covered by Painter B's slightly-offset colored X), we
                // promote any non-zero source alpha to the painter's full
                // unpremultiplied source CMYK converted to sRGB. This
                // produces fully-opaque coverage at edge pixels matching
                // what the inner painter would render at the path interior,
                // so the inner group can fully knock out the outer's AA
                // edge when composited back to its parent.
                let src_data = source.data();
                let src_a_pm = src_data[gi + 3] as f64 / 255.0;
                if src_a_pm <= 0.0 {
                    continue;
                }
                // Convert source CMYK directly to sRGB. The CMYK at this
                // pixel was written by the inner painter at its full
                // un-modulated value (the cmyk_buf doesn't track AA), so
                // this is the pure painter color regardless of AA cov.
                let (full_r, full_g, full_b) = icc
                    .and_then(|i| i.convert_cmyk_readonly(sc, sm, sy_, sk))
                    .unwrap_or_else(|| cmyk_to_rgb_plrm(sc, sm, sy_, sk));
                let alpha_s = mix;
                let inv_sa = 1.0 - alpha_s;
                let dst_r_pm = target_data[ti] as f64 / 255.0;
                let dst_g_pm = target_data[ti + 1] as f64 / 255.0;
                let dst_b_pm = target_data[ti + 2] as f64 / 255.0;
                let out_r = full_r * alpha_s + dst_r_pm * inv_sa;
                let out_g = full_g * alpha_s + dst_g_pm * inv_sa;
                let out_b = full_b * alpha_s + dst_b_pm * inv_sa;
                let out_a = alpha_s + dst_a * inv_sa;
                target_data[ti] = (out_r * 255.0).round().clamp(0.0, 255.0) as u8;
                target_data[ti + 1] = (out_g * 255.0).round().clamp(0.0, 255.0) as u8;
                target_data[ti + 2] = (out_b * 255.0).round().clamp(0.0, 255.0) as u8;
                target_data[ti + 3] = (out_a * 255.0).round().clamp(0.0, 255.0) as u8;
                continue;
            }

            // Apply the group's blend mode in CMYK.
            let (rc, rm, ry, rk) = if is_nonseparable {
                let r = blend_cmyk_nonseparable([bc, bm, by_, bk], [sc, sm, sy_, sk], blend_mode);
                (r[0], r[1], r[2], r[3])
            } else {
                (
                    blend_cmyk_separable_channel(bc, sc, blend_mode),
                    blend_cmyk_separable_channel(bm, sm, blend_mode),
                    blend_cmyk_separable_channel(by_, sy_, blend_mode),
                    blend_cmyk_separable_channel(bk, sk, blend_mode),
                )
            };

            let (new_r, new_g, new_b) = icc
                .and_then(|i| i.convert_cmyk_readonly(rc, rm, ry, rk))
                .unwrap_or_else(|| cmyk_to_rgb_plrm(rc, rm, ry, rk));

            // tiny-skia stores premultiplied sRGB. Apply the PDF
            // §11.4.6 result formula in straight-color form. We force the
            // source alpha to 1 (subject to clip + group opacity) at any
            // pixel where the source CMYK was written by the inner painter
            // — the cmyk_buf flags coverage at the path's full extent, even
            // at AA edges. Using full alpha here ensures the inner group
            // fully covers the outer parent's previously-drawn content
            // when both reference near-identical paths (GWG 16.2 directly-
            // drawn outer X path covered by Painter B's slightly-offset
            // colored X path). Without this, the formula's partial-cover
            // mix produces a 1-pixel sliver of darker color where the two
            // paths' rasterizations diverge sub-pixel-wise.
            let alpha_s = mix;
            let alpha_b = dst_a;
            let out_a = alpha_s + alpha_b * (1.0 - alpha_s);
            if out_a <= 0.0 {
                continue;
            }
            let (dst_r, dst_g, dst_b) = if alpha_b > 0.0 {
                let inv_a = 1.0 / alpha_b;
                (
                    (target_data[ti] as f64 / 255.0) * inv_a,
                    (target_data[ti + 1] as f64 / 255.0) * inv_a,
                    (target_data[ti + 2] as f64 / 255.0) * inv_a,
                )
            } else {
                (0.0, 0.0, 0.0)
            };
            // Spec §11.4.6 result computation:
            //   C_o = (α_s·(1−α_b)·C_s + α_s·α_b·B(C_b,C_s) + (1−α_s)·α_b·C_b) / α_o
            // Here we already have B(C_b,C_s) computed in CMYK and converted
            // to sRGB as (new_r, new_g, new_b). The "C_s" term — the source
            // color un-blended — uses the same value because the spec says
            // when α_b = 0 the formula reduces to source-as-is, which the
            // (1−α_b) coefficient already handles.
            let coef_b = alpha_s * alpha_b;
            let coef_s = alpha_s * (1.0 - alpha_b);
            let coef_d = (1.0 - alpha_s) * alpha_b;
            let out_r = (coef_s * new_r + coef_b * new_r + coef_d * dst_r) / out_a;
            let out_g = (coef_s * new_g + coef_b * new_g + coef_d * dst_g) / out_a;
            let out_b = (coef_s * new_b + coef_b * new_b + coef_d * dst_b) / out_a;

            target_data[ti] = (out_r * out_a * 255.0).round().clamp(0.0, 255.0) as u8;
            target_data[ti + 1] = (out_g * out_a * 255.0).round().clamp(0.0, 255.0) as u8;
            target_data[ti + 2] = (out_b * out_a * 255.0).round().clamp(0.0, 255.0) as u8;
            target_data[ti + 3] = (out_a * 255.0).round().clamp(0.0, 255.0) as u8;
        }
    }

    // Write the blended CMYK back to the parent CMYK buffer so subsequent
    // sibling groups see consistent backdrop values. We re-walk the same
    // region — keeps the inner loop above tight (no double-borrow on the
    // parent buffer) and only touches pixels we actually modified.
    if let Some(parent_cmyk) = parent_cmyk {
        for gy in 0..ch {
            let ty = crop_y + gy as i32;
            if ty < 0 || ty as usize >= target_h {
                continue;
            }
            let ty = ty as usize;
            let group_row = gy * group_stride;
            let parent_row = ty * target_stride;

            for gx in 0..cw {
                let tx = crop_x + gx as i32;
                if tx < 0 || tx as usize >= target_w {
                    continue;
                }
                let tx = tx as usize;
                let gi = group_row + gx * 4;
                let pi = parent_row + tx * 4;

                let bc = backdrop_cmyk[gi] as f64;
                let bm = backdrop_cmyk[gi + 1] as f64;
                let by_ = backdrop_cmyk[gi + 2] as f64;
                let bk = backdrop_cmyk[gi + 3] as f64;
                let sc = source_cmyk[gi] as f64;
                let sm = source_cmyk[gi + 1] as f64;
                let sy_ = source_cmyk[gi + 2] as f64;
                let sk = source_cmyk[gi + 3] as f64;
                if (sc - bc).abs() < 1.0 / 255.0
                    && (sm - bm).abs() < 1.0 / 255.0
                    && (sy_ - by_).abs() < 1.0 / 255.0
                    && (sk - bk).abs() < 1.0 / 255.0
                {
                    continue;
                }

                // Same transparent-backdrop fast path as above: use source
                // as-is. We read the original backdrop alpha from the saved
                // backdrop_pixels slice, NOT the live target — the live
                // target's alpha was already updated by the first loop's
                // composite-back writes.
                let backdrop_transparent = backdrop_pixels[gi + 3] == 0;
                let (rc, rm, ry, rk) = if backdrop_transparent {
                    (sc, sm, sy_, sk)
                } else if is_nonseparable {
                    let r =
                        blend_cmyk_nonseparable([bc, bm, by_, bk], [sc, sm, sy_, sk], blend_mode);
                    (r[0], r[1], r[2], r[3])
                } else {
                    (
                        blend_cmyk_separable_channel(bc, sc, blend_mode),
                        blend_cmyk_separable_channel(bm, sm, blend_mode),
                        blend_cmyk_separable_channel(by_, sy_, blend_mode),
                        blend_cmyk_separable_channel(bk, sk, blend_mode),
                    )
                };
                parent_cmyk[pi] = rc as f32;
                parent_cmyk[pi + 1] = rm as f32;
                parent_cmyk[pi + 2] = ry as f32;
                parent_cmyk[pi + 3] = rk as f32;
            }
        }
    }
}

/// Render a knockout transparency group into a pixmap.
///
/// In a knockout group, each element composites against the group's initial
/// backdrop (not the accumulated result of previous elements).
fn render_knockout_group(
    pixmap: &mut Pixmap,
    band_state: &mut BandState,
    elements: &DisplayList,
    params: &stet_graphics::display_list::GroupParams,
    ctx: &RenderContext<'_>,
) {
    let crop = compute_group_crop(&params.bbox, ctx);

    let (eff_w, eff_h, crop_x, crop_y, eff_vp_x, eff_vp_y) = match crop {
        Some((cx, cy, cw, ch)) => (
            cw,
            ch,
            cx,
            cy,
            ctx.vp_x + cx as f32 / ctx.scale_x,
            ctx.vp_y + cy as f32 / ctx.scale_y,
        ),
        None => (ctx.out_w, ctx.out_h, 0, 0, ctx.vp_x, ctx.vp_y),
    };

    let Some(mut offscreen) = Pixmap::new(eff_w, eff_h) else {
        return;
    };

    let initial_backdrop = if !params.isolated {
        if crop.is_some() {
            copy_backdrop_crop(pixmap, crop_x, crop_y, eff_w, eff_h)
        } else {
            pixmap.data().to_vec()
        }
    } else {
        vec![0u8; (eff_w * eff_h * 4) as usize]
    };

    let Some(mut accumulated) = Pixmap::new(eff_w, eff_h) else {
        return;
    };
    accumulated.data_mut().copy_from_slice(&initial_backdrop);

    // Initial CMYK values for the knockout group
    let needs_cmyk = has_overprint_elements(elements) || band_state.cmyk_buffer.is_some();
    let initial_cmyk = if needs_cmyk {
        let buf_size = eff_w as usize * eff_h as usize * 4;
        let mut buf = vec![0.0f32; buf_size];
        if let Some(ref parent_cmyk) = band_state.cmyk_buffer {
            let parent_stride = ctx.out_w as usize * 4;
            let group_stride = eff_w as usize * 4;
            for gy in 0..eff_h as usize {
                let py = crop_y as usize + gy;
                if py < ctx.out_h as usize {
                    let p_start = py * parent_stride + crop_x as usize * 4;
                    let g_start = gy * group_stride;
                    let copy_len = group_stride.min(parent_stride - crop_x as usize * 4);
                    buf[g_start..g_start + copy_len]
                        .copy_from_slice(&parent_cmyk[p_start..p_start + copy_len]);
                }
            }
        }
        Some(buf)
    } else {
        None
    };

    let mut accumulated_cmyk = initial_cmyk.clone();

    // Disable anti-aliasing in knockout groups to prevent seam artifacts.
    // Each element composites independently against the backdrop, so adjacent
    // fills' AA edges don't mesh — both blend toward the backdrop color,
    // creating visible 1px white lines at shared boundaries.
    let group_ctx = RenderContext {
        vp_x: eff_vp_x,
        vp_y: eff_vp_y,
        scale_x: ctx.scale_x,
        scale_y: ctx.scale_y,
        out_w: eff_w,
        out_h: eff_h,
        effective_dpi: ctx.effective_dpi,
        icc: ctx.icc,
        image_cache: None,
        preprocessed: None,
        elem_idx: 0,
        no_aa: true,
        opm_zero_transparent: ctx.opm_zero_transparent,
        knockout_painter_pass: ctx.knockout_painter_pass,
        // Knockout groups composite each element against the initial backdrop;
        // children effectively see this group's "fresh" backdrop. Treat the
        // knockout group as isolated for the purposes of the inner CMYK rule.
        parent_group_isolated: true,
        alpha_extraction_pass: false,
        layer_set: ctx.layer_set,
    };

    // Persistent band state for clip tracking — clips must accumulate across
    // elements in the knockout group (each paint element still composites
    // against the initial backdrop, but it must respect the current clip).
    let mut ko_band = BandState {
        clip_region: None,
        spare_mask: None,
        clip_mask_cache: HashMap::new(),
        clip_mask_seen: HashSet::new(),
        mask_pool: Vec::new(),
        cmyk_buffer: None,
        op_bg_snapshot: None,
        op_touched: None,
        spot_mask: None,
    };

    // Coverage offscreen for two-pass painter rendering of nested transparency
    // groups. Reused (zeroed) across painters; allocated lazily on first need.
    let mut coverage_offscreen: Option<Pixmap> = None;

    for elem in elements.elements() {
        match elem {
            // State-only elements: update persistent clip, no knockout compositing
            DisplayElement::Clip { .. } | DisplayElement::InitClip => {
                render_element(&mut offscreen, &mut ko_band, elem, &group_ctx);
            }
            // Group painters need two-pass rendering. Knockout semantics
            // require each painter to overwrite previous siblings within its
            // coverage area, even when the painter's blend mode happens to
            // produce a result that equals the initial backdrop (e.g.
            // Darken(red, white)=red, SoftLight(red, black)=red,
            // Multiply(red, magenta)=red — which is exactly what GWG 16.1
            // tests). The single-pass change-against-backdrop check used for
            // simpler painter types would miss those pixels, and earlier
            // siblings' contributions would bleed through.
            DisplayElement::Group { .. } => {
                // Pass 1: render painter against initial_backdrop to compute
                // the blended-color result (the painter's contribution).
                // Use ColorPass mode so any non-Normal blend mode goes through
                // the per-pixel CMYK composite-back — required for separable
                // blends like Screen / ColorDodge / Overlay / SoftLight whose
                // sRGB result drifts away from the CMYK-math result.
                let pass1_ctx = RenderContext {
                    knockout_painter_pass: KnockoutPainterPass::ColorPass,
                    ..group_ctx
                };
                offscreen.data_mut().copy_from_slice(&initial_backdrop);
                ko_band.cmyk_buffer = initial_cmyk.clone();
                render_element(&mut offscreen, &mut ko_band, elem, &pass1_ctx);
                let pass1_cmyk = ko_band.cmyk_buffer.take();

                // Pass 2: render painter into a fresh transparent offscreen so
                // the alpha channel captures the painter's coverage, which the
                // result-color comparison cannot recover when the blend mode
                // outputs the backdrop color exactly.
                let cov = match coverage_offscreen.as_mut() {
                    Some(p) => {
                        p.data_mut().fill(0);
                        p
                    }
                    None => {
                        let Some(p) = Pixmap::new(eff_w, eff_h) else {
                            // Out of memory for coverage buffer — fall back
                            // to the change-detection path so the painter
                            // still appears (just without proper knockout).
                            replace_changed_pixels(
                                accumulated.data_mut(),
                                offscreen.data(),
                                &initial_backdrop,
                            );
                            if let (Some(p1), Some(acc)) = (&pass1_cmyk, &mut accumulated_cmyk) {
                                replace_changed_cmyk(acc, p1, offscreen.data(), &initial_backdrop);
                            }
                            continue;
                        };
                        coverage_offscreen = Some(p);
                        coverage_offscreen.as_mut().unwrap()
                    }
                };
                ko_band.cmyk_buffer = None;
                // Coverage pass: render through the simple sRGB path with
                // alpha forced to 1.0 and Normal blend so the painter's
                // shape reaches the coverage offscreen even for white-source
                // CMYK painters and zero-alpha painters (Opacity 0% test).
                let coverage_ctx = RenderContext {
                    knockout_painter_pass: KnockoutPainterPass::CoveragePass,
                    ..group_ctx
                };
                render_element(cov, &mut ko_band, elem, &coverage_ctx);

                // Use the coverage offscreen's alpha as a knockout mask: the
                // painter's contribution from pass 1 source-overs onto
                // accumulated weighted by the coverage alpha.
                replace_with_coverage_mask(accumulated.data_mut(), offscreen.data(), cov.data());

                if let (Some(p1_cmyk), Some(acc_cmyk)) = (&pass1_cmyk, &mut accumulated_cmyk) {
                    replace_cmyk_with_coverage_mask(acc_cmyk, p1_cmyk, cov.data());
                }
                ko_band.cmyk_buffer = None;
            }
            // Other paint elements: single-pass with change-against-backdrop.
            // Direct path/image/shading paints always change pixels they cover,
            // so the simpler detection works and avoids the second-pass cost.
            _ => {
                offscreen.data_mut().copy_from_slice(&initial_backdrop);

                ko_band.cmyk_buffer = initial_cmyk.clone();

                render_element(&mut offscreen, &mut ko_band, elem, &group_ctx);

                if let (Some(elem_cmyk), Some(acc_cmyk)) =
                    (&ko_band.cmyk_buffer, &mut accumulated_cmyk)
                {
                    replace_changed_cmyk(acc_cmyk, elem_cmyk, offscreen.data(), &initial_backdrop);
                }
                ko_band.cmyk_buffer = None;

                replace_changed_pixels(accumulated.data_mut(), offscreen.data(), &initial_backdrop);
            }
        }
    }

    let mut temp_mask = None;
    let mask_ref = resolve_clip_mask(
        &band_state.clip_region,
        &mut temp_mask,
        ctx.out_w,
        ctx.out_h,
    );
    let mask_ref = match mask_ref {
        None => return,
        Some(m) => m,
    };

    composite_non_isolated_group_cropped(
        pixmap,
        &accumulated,
        &initial_backdrop,
        params,
        mask_ref,
        crop_x,
        crop_y,
    );

    if let (Some(acc_cmyk), Some(parent_cmyk)) = (&accumulated_cmyk, &mut band_state.cmyk_buffer) {
        copy_cmyk_buffer_to_parent(
            parent_cmyk,
            acc_cmyk,
            accumulated.data(),
            crop_x as usize,
            crop_y as usize,
            eff_w as usize,
            eff_h as usize,
            ctx.out_w as usize,
            ctx.out_h as usize,
        );
    }
}
/// Source-over `source` onto `target` weighted by `coverage`'s alpha channel.
/// Used for the two-pass knockout group rendering: `coverage` is rendered
/// into a transparent offscreen so its alpha records the painter's coverage
/// regardless of whether the painter's blend mode produced backdrop-equal
/// pixels in the color pass. Both `source` and `target` are assumed fully
/// opaque pixmaps (alpha=255 everywhere) since the knockout offscreens are
/// pre-loaded with the opaque initial backdrop.
fn replace_with_coverage_mask(target: &mut [u8], source: &[u8], coverage: &[u8]) {
    for i in (0..target.len()).step_by(4) {
        let cov_a = coverage[i + 3];
        if cov_a == 0 {
            continue;
        }
        if cov_a == 255 {
            target[i..i + 4].copy_from_slice(&source[i..i + 4]);
            continue;
        }
        let a = cov_a as u32;
        let inv = 255 - a;
        for c in 0..4 {
            let s = source[i + c] as u32;
            let t = target[i + c] as u32;
            target[i + c] = ((s * a + t * inv + 127) / 255) as u8;
        }
    }
}

/// Source-over CMYK values from `source` onto `target` weighted by the
/// coverage offscreen's alpha channel. Companion to
/// `replace_with_coverage_mask` for the parallel CMYK buffer.
fn replace_cmyk_with_coverage_mask(target: &mut [f32], source: &[f32], coverage: &[u8]) {
    let pixel_count = target.len() / 4;
    for i in 0..pixel_count {
        let pi = i * 4;
        let cov_a = coverage[pi + 3];
        if cov_a == 0 {
            continue;
        }
        if cov_a == 255 {
            target[pi..pi + 4].copy_from_slice(&source[pi..pi + 4]);
            continue;
        }
        let a = cov_a as f32 / 255.0;
        let inv = 1.0 - a;
        for c in 0..4 {
            target[pi + c] = source[pi + c] * a + target[pi + c] * inv;
        }
    }
}

/// Replace pixels in `target` with pixels from `source` wherever `source`
/// differs from `backdrop`. Used for knockout group per-element compositing
/// where each element replaces (not blends with) previous elements.
fn replace_changed_pixels(target: &mut [u8], source: &[u8], backdrop: &[u8]) {
    for i in (0..target.len()).step_by(4) {
        if source[i] != backdrop[i]
            || source[i + 1] != backdrop[i + 1]
            || source[i + 2] != backdrop[i + 2]
            || source[i + 3] != backdrop[i + 3]
        {
            target[i..i + 4].copy_from_slice(&source[i..i + 4]);
        }
    }
}

/// Copy a group's CMYK buffer back to the parent's CMYK buffer after compositing.
/// Only copies values for pixels where the group offscreen has non-zero alpha,
/// indicating the group actually painted something at that position.
#[allow(clippy::too_many_arguments)]
fn copy_cmyk_buffer_to_parent(
    parent_cmyk: &mut [f32],
    group_cmyk: &[f32],
    group_pixels: &[u8],
    crop_x: usize,
    crop_y: usize,
    group_w: usize,
    group_h: usize,
    parent_w: usize,
    parent_h: usize,
) {
    let parent_stride = parent_w * 4;
    let group_stride = group_w * 4;
    for gy in 0..group_h {
        let py = crop_y + gy;
        if py >= parent_h {
            break;
        }
        for gx in 0..group_w {
            let px = crop_x + gx;
            if px >= parent_w {
                break;
            }
            // Only copy if the group pixel has non-zero alpha AND
            // the group's cmyk at that pixel is non-zero.
            // Zero cmyk means "not tracked by a CMYK fill in this group"
            // — writing it back would erase the parent's tracked values.
            let g_pixel_idx = (gy * group_w + gx) * 4;
            let g_cmyk_idx = gy * group_stride + gx * 4;
            if group_pixels[g_pixel_idx + 3] > 0
                && (group_cmyk[g_cmyk_idx] != 0.0
                    || group_cmyk[g_cmyk_idx + 1] != 0.0
                    || group_cmyk[g_cmyk_idx + 2] != 0.0
                    || group_cmyk[g_cmyk_idx + 3] != 0.0)
            {
                let p_cmyk_idx = py * parent_stride + px * 4;
                parent_cmyk[p_cmyk_idx..p_cmyk_idx + 4]
                    .copy_from_slice(&group_cmyk[g_cmyk_idx..g_cmyk_idx + 4]);
            }
        }
    }
}

/// Copy CMYK values for pixels that changed in a knockout element.
/// Used alongside replace_changed_pixels to keep CMYK in sync with RGB.
fn replace_changed_cmyk(
    target_cmyk: &mut [f32],
    source_cmyk: &[f32],
    source_pixels: &[u8],
    backdrop_pixels: &[u8],
) {
    let pixel_count = target_cmyk.len() / 4;
    for i in 0..pixel_count {
        let pi = i * 4;
        if source_pixels[pi] != backdrop_pixels[pi]
            || source_pixels[pi + 1] != backdrop_pixels[pi + 1]
            || source_pixels[pi + 2] != backdrop_pixels[pi + 2]
            || source_pixels[pi + 3] != backdrop_pixels[pi + 3]
        {
            target_cmyk[pi..pi + 4].copy_from_slice(&source_cmyk[pi..pi + 4]);
        }
    }
}

/// Render soft-masked content.
///
/// 1. Renders the mask display list to an offscreen pixmap.
/// 2. Extracts a grayscale mask (luminosity or alpha).
/// 3. Renders content into another offscreen pixmap.
/// 4. Multiplies content alpha by the mask values.
/// 5. Composites the masked content onto the parent.
#[allow(clippy::too_many_arguments)]
fn render_soft_masked(
    pixmap: &mut Pixmap,
    band_state: &mut BandState,
    mask_list: &DisplayList,
    content_list: &DisplayList,
    params: &stet_graphics::display_list::SoftMaskParams,
    mask_cache: &Arc<Mutex<Option<Option<stet_graphics::display_list::MaskRaster>>>>,
    ctx: &RenderContext<'_>,
) {
    // The SoftMask's display list elements are in absolute device space (page coords).
    // params.bbox is the SoftMasked element's compositing bounds, derived
    // from the form's /BBox transformed by the gs-time CTM. The mask raster
    // (built lazily by `rasterize_mask` and cached on the display-list
    // element) is anchored independently to the *actual* mask paint bounds,
    // which may differ from params.bbox when the form's internal `cm`
    // operators translated paint elements outside the form bbox.
    //
    // The cached-raster path can produce truncated output when the
    // SoftMasked is rendered inside an outer offscreen (a Group, an
    // outer SoftMasked, etc.) — the nested offscreen's coordinate
    // system clips the mask raster's right edge unexpectedly. Detect
    // "nested" via `ctx.vp_x != 0.0` (top-level banded rendering uses
    // vp_x = 0; nested rendering inherits the parent offscreen's vp).
    // For nested cases, fall back to the inline band-local mask
    // rendering that worked before Step 4 of cosmic-masking-bird.
    let use_inline_mask = ctx.vp_x != 0.0;
    let bbox = &params.bbox;
    let smask_px_x0 = ((bbox[0] as f32 - ctx.vp_x) * ctx.scale_x).floor() as i32;
    let smask_px_y0 = ((bbox[1] as f32 - ctx.vp_y) * ctx.scale_y).floor() as i32;
    let smask_px_x1 = ((bbox[2] as f32 - ctx.vp_x) * ctx.scale_x).ceil() as i32;
    let smask_px_y1 = ((bbox[3] as f32 - ctx.vp_y) * ctx.scale_y).ceil() as i32;

    // Clip to parent output bounds
    let crop_x = smask_px_x0.max(0);
    let crop_y = smask_px_y0.max(0);
    let crop_x1 = smask_px_x1.min(ctx.out_w as i32);
    let crop_y1 = smask_px_y1.min(ctx.out_h as i32);
    if crop_x >= crop_x1 || crop_y >= crop_y1 {
        return;
    }
    let eff_w = (crop_x1 - crop_x) as u32;
    let eff_h = (crop_y1 - crop_y) as u32;

    // Viewport for the content offscreen: derived from the SoftMask's bbox
    // position relative to the parent's viewport. The content offscreen
    // still uses params.bbox because params.bbox correctly bounds where
    // the content can paint.
    let eff_vp_x = ctx.vp_x + crop_x as f32 / ctx.scale_x;
    let eff_vp_y = ctx.vp_y + crop_y as f32 / ctx.scale_y;

    let sub_ctx = RenderContext {
        vp_x: eff_vp_x,
        vp_y: eff_vp_y,
        scale_x: ctx.scale_x,
        scale_y: ctx.scale_y,
        out_w: eff_w,
        out_h: eff_h,
        effective_dpi: ctx.effective_dpi,
        icc: ctx.icc,
        image_cache: None,
        preprocessed: None,
        elem_idx: 0,
        no_aa: ctx.no_aa,
        opm_zero_transparent: ctx.opm_zero_transparent,
        knockout_painter_pass: ctx.knockout_painter_pass,
        parent_group_isolated: ctx.parent_group_isolated,
        // Soft masks render into their own independent offscreen and must
        // not inherit the alpha extraction pass — their groups need normal
        // backdrop preloading regardless of the outer extraction context.
        alpha_extraction_pass: false,
        layer_set: ctx.layer_set,
    };

    // 1a. INLINE PATH: Mask form contains nested offscreens.
    // Render the mask form into a band-local offscreen sized to the
    // SoftMasked's bbox crop. This matches the pre-Step-4 behavior.
    let mut mask_values_inline: Vec<u8> = Vec::new();
    if use_inline_mask {
        let Some(mut mask_pixmap) = Pixmap::new(eff_w, eff_h) else {
            return;
        };
        let mut mask_band = BandState {
            clip_region: None,
            spare_mask: None,
            clip_mask_cache: HashMap::new(),
            clip_mask_seen: HashSet::new(),
            mask_pool: Vec::new(),
            cmyk_buffer: None,
            op_bg_snapshot: None,
            op_touched: None,
            spot_mask: None,
        };
        for (idx, elem) in mask_list.elements().iter().enumerate() {
            let elem_ctx = RenderContext {
                elem_idx: idx,
                ..sub_ctx
            };
            render_element(&mut mask_pixmap, &mut mask_band, elem, &elem_ctx);
        }
        if params.has_nested_mask_scope
            && params.subtype == stet_graphics::display_list::SoftMaskSubtype::Luminosity
        {
            let bc = params.backdrop_color.as_ref();
            let bd_r = bc.map_or(0u8, |c| (c[0].clamp(0.0, 1.0) * 255.0 + 0.5) as u8);
            let bd_g = bc.map_or(0u8, |c| (c[1].clamp(0.0, 1.0) * 255.0 + 0.5) as u8);
            let bd_b = bc.map_or(0u8, |c| (c[2].clamp(0.0, 1.0) * 255.0 + 0.5) as u8);
            for chunk in mask_pixmap.data_mut().chunks_exact_mut(4) {
                let a = chunk[3] as u16;
                if a == 255 {
                    continue;
                }
                let inv_a = 255 - a;
                chunk[0] = ((chunk[0] as u16 * 255 + bd_r as u16 * inv_a + 127) / 255) as u8;
                chunk[1] = ((chunk[1] as u16 * 255 + bd_g as u16 * inv_a + 127) / 255) as u8;
                chunk[2] = ((chunk[2] as u16 * 255 + bd_b as u16 * inv_a + 127) / 255) as u8;
                chunk[3] = 255;
            }
        }
        mask_values_inline = vec![0u8; (eff_w * eff_h) as usize];
        extract_soft_mask_values(mask_pixmap.data(), &mut mask_values_inline, params);
    }

    // 1b. CACHED RASTER PATH: simple masks (no nested offscreens).
    let raster_owned: Option<stet_graphics::display_list::MaskRaster> = if use_inline_mask {
        None
    } else {
        let mut guard = mask_cache.lock().unwrap();
        let needs_build = match guard.as_ref() {
            None => true,
            Some(None) => false, // memoized "no mask"
            Some(Some(r)) => {
                (r.scale_x - ctx.scale_x).abs() > 1e-4 || (r.scale_y - ctx.scale_y).abs() > 1e-4
            }
        };
        if needs_build {
            let built = rasterize_mask(
                mask_list,
                params,
                ctx.icc,
                ctx.no_aa,
                ctx.effective_dpi,
                ctx.scale_x,
                ctx.scale_y,
                ctx.layer_set,
            );
            *guard = Some(built);
        }
        guard.as_ref().and_then(|inner| inner.clone())
    };

    // Default mask value for content pixels that fall outside the mask
    // raster (e.g. backdrop region for a Luminosity mask with non-black
    // /BC, or always 0 for Alpha masks).
    let fallback_mask = out_of_bounds_mask_value(params) as i32;

    // 2. Render content into an offscreen, initialized with the parent's
    // backdrop so non-isolated groups with blend modes (e.g. Multiply) see
    // the correct background and produce the right composited result.
    let Some(mut content_pixmap) = Pixmap::new(eff_w, eff_h) else {
        return;
    };
    let backdrop = copy_backdrop_crop(pixmap, crop_x, crop_y, eff_w, eff_h);
    content_pixmap.data_mut().copy_from_slice(&backdrop);

    let content_cmyk = if has_overprint_elements(content_list) || band_state.cmyk_buffer.is_some() {
        let buf_size = eff_w as usize * eff_h as usize * 4;
        let mut buf = vec![0.0f32; buf_size];
        if let Some(ref parent_cmyk) = band_state.cmyk_buffer {
            let parent_stride = ctx.out_w as usize * 4;
            let group_stride = eff_w as usize * 4;
            for gy in 0..eff_h as usize {
                let py = crop_y as usize + gy;
                if py < ctx.out_h as usize {
                    let p_start = py * parent_stride + crop_x as usize * 4;
                    let g_start = gy * group_stride;
                    let copy_len = group_stride.min(parent_stride - crop_x as usize * 4);
                    buf[g_start..g_start + copy_len]
                        .copy_from_slice(&parent_cmyk[p_start..p_start + copy_len]);
                }
            }
        }
        Some(buf)
    } else {
        None
    };
    // Snapshot the pre-content CMYK state so the mask blend can run in CMYK
    // space. Without this, the downstream sRGB blend interpolates between
    // CMYK backdrop and source after each has been ICC-converted separately,
    // which shifts the midtones away from the CMYK-interpolated result the
    // source was authored against (pink cast vs warm peach on GWG 16.10
    // inner-glow in PDFX-ready_Output-Test_X4.pdf).
    let backdrop_cmyk: Option<Vec<f32>> = content_cmyk.clone();
    let mut content_band = BandState {
        clip_region: None,
        spare_mask: None,
        clip_mask_cache: HashMap::new(),
        clip_mask_seen: HashSet::new(),
        mask_pool: Vec::new(),
        cmyk_buffer: content_cmyk,
        op_bg_snapshot: None,
        op_touched: None,
        spot_mask: None,
    };
    for (idx, elem) in content_list.elements().iter().enumerate() {
        let elem_ctx = RenderContext {
            elem_idx: idx,
            ..sub_ctx
        };
        render_element(&mut content_pixmap, &mut content_band, elem, &elem_ctx);
    }

    // 3. Apply soft mask: compute per-pixel masked contribution and write
    // to parent. result[c] = parent[c] + m * (content_on_backdrop[c] - backdrop[c]) / 255
    //
    // Mask sampling: the mask raster is in page-pixel coordinates at the
    // current render scale, anchored at `(raster.origin_x, raster.origin_y)`.
    // The combine loop iterates over content pixel `(x, y)` band-local in
    // the content offscreen. To translate to a mask raster index:
    //
    //   page_x = vp_x_pixels + crop_x + x
    //   page_y = vp_y_pixels + crop_y + y
    //   mask_x = page_x - raster.origin_x
    //   mask_y = page_y - raster.origin_y
    //
    // where `vp_x_pixels = round(ctx.vp_x * ctx.scale_x)` is the page-pixel
    // offset of the band's top-left. For banded rendering this is exact
    // (vp = 0, scale = 1, so vp_x_pixels = 0). For viewport rendering with
    // a fractional `vp_x`, there is at most a 0.5-pixel sub-pixel offset
    // between the content render grid and the cached mask grid; this is
    // bounded and visually acceptable for nearest-neighbor sampling.
    let vp_x_pixels = (ctx.vp_x * ctx.scale_x).round() as i32;
    let vp_y_pixels = (ctx.vp_y * ctx.scale_y).round() as i32;

    let mut temp_mask = None;
    let clip_ref = resolve_clip_mask(
        &band_state.clip_region,
        &mut temp_mask,
        ctx.out_w,
        ctx.out_h,
    );
    let clip_ref = match clip_ref {
        None => return,
        Some(m) => m,
    };

    // Decide whether to interpolate the masked delta in CMYK (with ICC→sRGB
    // on the way out) instead of sRGB. The CMYK path matches Acrobat's
    // behaviour when the transparency group declares /CS DeviceCMYK and all
    // content is native CMYK — the blend color space is then CMYK, and
    // sRGB-space interpolation on ICC-converted endpoints loses the warm
    // midtone that M+Y mixing produces under a proper CMYK profile.
    //
    // Gate strictly: content_list must be a flat list of native-CMYK fills
    // or strokes with Normal blend and full opacity. Any nested Group,
    // SoftMasked, Image, or blend-mode-modulated paint means the parallel
    // cmyk_buffer can't be trusted to match the pixmap — running CMYK
    // interpolation against a mismatched CMYK snapshot produced wrong
    // colors on GWG 16.10 outer-glow C (Fm5 is a Screen-blend white rect
    // inside a Group; cmyk_buffer held raw white while pixmap held the
    // screen-blended light gray).
    let use_cmyk_blend = ctx.icc.is_some()
        && backdrop_cmyk.is_some()
        && content_band.cmyk_buffer.is_some()
        && content_list_is_simple_native_cmyk(content_list);

    let content_data = content_pixmap.data();
    let parent_data = pixmap.data_mut();
    let parent_stride = ctx.out_w as usize * 4;
    let content_stride = eff_w as usize * 4;

    for y in 0..eff_h as usize {
        let py = crop_y as usize + y;
        if py >= ctx.out_h as usize {
            break;
        }
        let ci_row = y * content_stride;
        let pi_row = py * parent_stride;
        let page_y = vp_y_pixels + crop_y + y as i32;

        for x in 0..eff_w as usize {
            let px = crop_x as usize + x;
            if px >= ctx.out_w as usize {
                break;
            }

            // Check clip mask (in parent coordinates)
            if let Some(clip) = clip_ref {
                if clip.data()[py * ctx.out_w as usize + px] == 0 {
                    continue;
                }
            }

            // Sample the mask: inline-rendered values for masks with
            // nested offscreens, cached raster for simple masks.
            let m = if use_inline_mask {
                mask_values_inline[y * eff_w as usize + x] as i32
            } else if let Some(ref raster) = raster_owned {
                let page_x = vp_x_pixels + crop_x + x as i32;
                let mx = page_x - raster.origin_x;
                let my = page_y - raster.origin_y;
                if mx >= 0 && (mx as u32) < raster.width && my >= 0 && (my as u32) < raster.height {
                    raster.data[my as usize * raster.width as usize + mx as usize] as i32
                } else {
                    fallback_mask
                }
            } else {
                fallback_mask
            };
            if m == 0 {
                continue;
            }

            let ci = ci_row + x * 4;
            let pi = pi_row + px * 4;

            // Per-pixel gate: CMYK interpolation is only safe when both
            // endpoints are faithfully tracked. ICC-convert both cmyk
            // snapshots and compare with the sRGB endpoints; only take
            // the CMYK path if BOTH agree within tolerance. The backdrop
            // check catches image/RGB paints upstream (tile_clamp_bug.pdf
            // photo background) where cmyk_buffer is an approximate
            // reverse-transform. The content check catches cases where
            // non-CMYK paints inside content leave the cmyk_buffer stale
            // relative to the sRGB content pixmap.
            let ci_cmyk = (y * eff_w as usize + x) * 4;
            let cmyk_path_ok = use_cmyk_blend && {
                let bc_cmyk = &backdrop_cmyk.as_ref().unwrap()[ci_cmyk..ci_cmyk + 4];
                let cc_cmyk = &content_band.cmyk_buffer.as_ref().unwrap()[ci_cmyk..ci_cmyk + 4];
                let icc_match = |cmyk: &[f32], rgb: &[u8]| -> bool {
                    let (r, g, b) = ctx
                        .icc
                        .and_then(|i| {
                            i.convert_cmyk_readonly(
                                cmyk[0] as f64,
                                cmyk[1] as f64,
                                cmyk[2] as f64,
                                cmyk[3] as f64,
                            )
                        })
                        .unwrap_or_else(|| {
                            cmyk_to_rgb_plrm(
                                cmyk[0] as f64,
                                cmyk[1] as f64,
                                cmyk[2] as f64,
                                cmyk[3] as f64,
                            )
                        });
                    let r = (r * 255.0).round() as i32;
                    let g = (g * 255.0).round() as i32;
                    let b = (b * 255.0).round() as i32;
                    (r - rgb[0] as i32).abs() <= 3
                        && (g - rgb[1] as i32).abs() <= 3
                        && (b - rgb[2] as i32).abs() <= 3
                };
                icc_match(bc_cmyk, &backdrop[ci..ci + 3])
                    && icc_match(cc_cmyk, &content_data[ci..ci + 3])
            };

            if cmyk_path_ok {
                // CMYK-space mask blend: result_cmyk = backdrop + m*(content - backdrop)
                let bc_cmyk = &backdrop_cmyk.as_ref().unwrap()[ci_cmyk..ci_cmyk + 4];
                let cc_cmyk = &content_band.cmyk_buffer.as_ref().unwrap()[ci_cmyk..ci_cmyk + 4];
                let mf = m as f64 / 255.0;
                let rc = bc_cmyk[0] as f64 + mf * (cc_cmyk[0] as f64 - bc_cmyk[0] as f64);
                let rm = bc_cmyk[1] as f64 + mf * (cc_cmyk[1] as f64 - bc_cmyk[1] as f64);
                let ry = bc_cmyk[2] as f64 + mf * (cc_cmyk[2] as f64 - bc_cmyk[2] as f64);
                let rk = bc_cmyk[3] as f64 + mf * (cc_cmyk[3] as f64 - bc_cmyk[3] as f64);
                let (fr, fg, fb) = ctx
                    .icc
                    .and_then(|i| i.convert_cmyk_readonly(rc, rm, ry, rk))
                    .unwrap_or_else(|| cmyk_to_rgb_plrm(rc, rm, ry, rk));
                parent_data[pi] = (fr * 255.0).round().clamp(0.0, 255.0) as u8;
                parent_data[pi + 1] = (fg * 255.0).round().clamp(0.0, 255.0) as u8;
                parent_data[pi + 2] = (fb * 255.0).round().clamp(0.0, 255.0) as u8;
                // Alpha channel: keep sRGB delta blend.
                let content_a = content_data[ci + 3] as i32;
                let backdrop_a = backdrop[ci + 3] as i32;
                let delta = content_a - backdrop_a;
                if delta != 0 {
                    let masked_delta = if delta > 0 {
                        (delta * m + 128) / 255
                    } else {
                        (delta * m - 128) / 255
                    };
                    let result = (parent_data[pi + 3] as i32 + masked_delta).clamp(0, 255);
                    parent_data[pi + 3] = result as u8;
                }
                // The parent's cmyk_buffer is deliberately NOT written here.
                // Writing back mask-blended CMYK would overwrite backdrop
                // tracking that downstream CMYK consumers (outer groups,
                // subsequent masks) depend on and cause them to render
                // nearby pixels as pure CMYK channels (e.g. the outer-glow
                // C regression: adjacent gray pixels ICC-resolved to a
                // black K silhouette). The sRGB pixmap carries the mask-
                // blended color; parent_cmyk stays untouched.
            } else {
                for c in 0..4 {
                    let content_val = content_data[ci + c] as i32;
                    let backdrop_val = backdrop[ci + c] as i32;
                    let delta = content_val - backdrop_val;
                    if delta != 0 {
                        let masked_delta = if delta > 0 {
                            (delta * m + 128) / 255
                        } else {
                            (delta * m - 128) / 255
                        };
                        let result = (parent_data[pi + c] as i32 + masked_delta).clamp(0, 255);
                        parent_data[pi + c] = result as u8;
                    }
                }
            }
        }
    }

    // Write content CMYK buffer back to parent. Skip when the CMYK blend
    // loop already updated band_state.cmyk_buffer with mask-blended values
    // — copying the unmodulated content CMYK here would overwrite them.
    if !use_cmyk_blend {
        if let (Some(content_cmyk), Some(parent_cmyk)) =
            (&content_band.cmyk_buffer, &mut band_state.cmyk_buffer)
        {
            copy_cmyk_buffer_to_parent(
                parent_cmyk,
                content_cmyk,
                content_pixmap.data(),
                crop_x as usize,
                crop_y as usize,
                eff_w as usize,
                eff_h as usize,
                ctx.out_w as usize,
                ctx.out_h as usize,
            );
        }
    }
}
/// Extract grayscale mask values from rendered RGBA pixels.
fn extract_soft_mask_values(
    rgba: &[u8],
    out: &mut [u8],
    params: &stet_graphics::display_list::SoftMaskParams,
) {
    use stet_graphics::display_list::SoftMaskSubtype;
    let pixel_count = out.len();

    match params.subtype {
        SoftMaskSubtype::Alpha => {
            for i in 0..pixel_count {
                let a = rgba[i * 4 + 3]; // alpha channel
                out[i] = if params.transfer_invert { 255 - a } else { a };
            }
        }
        SoftMaskSubtype::Luminosity => {
            // Backdrop luminosity for transparent pixels
            let backdrop_lum = if let Some(bc) = &params.backdrop_color {
                (0.2126 * bc[0] + 0.7152 * bc[1] + 0.0722 * bc[2]).clamp(0.0, 1.0)
            } else {
                0.0 // black backdrop
            };
            let backdrop_byte = (backdrop_lum * 255.0 + 0.5) as u8;

            #[allow(clippy::needless_range_loop)]
            for i in 0..pixel_count {
                let off = i * 4;
                let a = rgba[off + 3];
                let lum_byte = if a == 0 {
                    backdrop_byte
                } else if a < 255 {
                    // Composite premultiplied RGB onto backdrop before computing
                    // luminosity (PDF spec 11.6.5.3): premul_rgb + BC × (1 - α/255)
                    let af = a as f64;
                    let bd = backdrop_lum * 255.0;
                    let r = rgba[off] as f64 + bd * (255.0 - af) / 255.0;
                    let g = rgba[off + 1] as f64 + bd * (255.0 - af) / 255.0;
                    let b = rgba[off + 2] as f64 + bd * (255.0 - af) / 255.0;
                    let lum = 0.2126 * r + 0.7152 * g + 0.0722 * b;
                    (lum + 0.5).clamp(0.0, 255.0) as u8
                } else {
                    // Fully opaque: premultiplied == straight RGB
                    let lum = 0.2126 * rgba[off] as f64
                        + 0.7152 * rgba[off + 1] as f64
                        + 0.0722 * rgba[off + 2] as f64;
                    (lum + 0.5).clamp(0.0, 255.0) as u8
                };
                // Apply transfer function inversion: {1 exch sub} → 255 - value
                out[i] = if params.transfer_invert {
                    255 - lum_byte
                } else {
                    lum_byte
                };
            }
        }
    }
}

/// Compute the byte the mask sample loop should use for content pixels
/// that fall outside the rasterized mask raster.
///
/// For Luminosity masks, transparent pixels (no rendered mask paint)
/// composite onto the backdrop color, so the effective mask value is the
/// backdrop's luminosity. For Alpha masks, transparent = 0 = mask off.
/// Both subtypes apply the `/TR {1 exch sub}` transfer inversion.
fn out_of_bounds_mask_value(params: &stet_graphics::display_list::SoftMaskParams) -> u8 {
    use stet_graphics::display_list::SoftMaskSubtype;
    let raw = match params.subtype {
        SoftMaskSubtype::Alpha => 0u8,
        SoftMaskSubtype::Luminosity => {
            let lum = if let Some(bc) = &params.backdrop_color {
                (0.2126 * bc[0] + 0.7152 * bc[1] + 0.0722 * bc[2]).clamp(0.0, 1.0)
            } else {
                0.0
            };
            (lum * 255.0 + 0.5) as u8
        }
    };
    if params.transfer_invert {
        255 - raw
    } else {
        raw
    }
}

/// Maximum mask raster area in pixels.  A malformed PDF that asks for a
/// gigantic mask form would otherwise OOM. 64 megapixels = 64 MB for
/// grayscale or 256 MB for RGBA — generous but bounded.  Using an area
/// limit instead of a per-dimension limit correctly handles narrow-but-tall
/// pages (e.g. infographics that exceed 8192 pixels in height while being
/// only ~1000 pixels wide).
const MAX_MASK_RASTER_PIXELS: u64 = 64 * 1024 * 1024;

/// Rasterize a soft mask form's display list into a `MaskRaster`.
///
/// Walks the mask display list to compute its actual paint bounds (which
/// may differ from the SoftMasked element's `params.bbox` because the
/// form's internal `cm` operators may translate paint elements outside
/// the form's `/BBox`), allocates a pixmap that exactly covers those
/// bounds in device-space pixels, and renders the mask elements with the
/// viewport set to the bounds origin so each element rasterizes at
/// `(device_x - origin_x, device_y - origin_y)`.
///
/// Returns `None` when the mask paints nothing.
fn rasterize_mask(
    mask_list: &DisplayList,
    params: &stet_graphics::display_list::SoftMaskParams,
    icc: Option<&IccCache>,
    no_aa: bool,
    effective_dpi: f64,
    scale_x: f32,
    scale_y: f32,
    layer_set: &LayerSet,
) -> Option<stet_graphics::display_list::MaskRaster> {
    // 1. Find the actual paint bounds in device space, then cap them to
    // the parent gstate's clip path bbox if known. The cap is critical
    // for masks whose form contains an unbounded shading inside a
    // sentinel-sized internal clip — without it, the raster blows past
    // the size limit and produces no output. Pixels outside the parent
    // clip can never affect the final image, so the cap is safe.
    let mut bounds = compute_paint_bounds(mask_list, effective_dpi)?;
    if let Some(cap) = params.parent_clip_bbox {
        let cap_bbox = BBox2D {
            x_min: cap[0],
            y_min: cap[1],
            x_max: cap[2],
            y_max: cap[3],
        };
        bounds = intersect_bbox(&bounds, &cap_bbox)?;
    }

    // 2. Snap to integer device pixels at the current render scale, with a
    // 1-pixel pad on each side to avoid antialiasing edge clipping.
    let px_x_min = (bounds.x_min as f32 * scale_x).floor() as i32 - 1;
    let px_y_min = (bounds.y_min as f32 * scale_y).floor() as i32 - 1;
    let px_x_max = (bounds.x_max as f32 * scale_x).ceil() as i32 + 1;
    let px_y_max = (bounds.y_max as f32 * scale_y).ceil() as i32 + 1;
    if px_x_min >= px_x_max || px_y_min >= px_y_max {
        return None;
    }
    let raster_w = (px_x_max - px_x_min) as u32;
    let raster_h = (px_y_max - px_y_min) as u32;
    if raster_w == 0 || raster_h == 0 {
        return None;
    }
    if (raster_w as u64) * (raster_h as u64) > MAX_MASK_RASTER_PIXELS {
        return None;
    }

    // 3. Allocate the offscreen pixmap (transparent backdrop).
    let mut mask_pixmap = Pixmap::new(raster_w, raster_h)?;

    // 4. Build a RenderContext that maps device pixel `(dx, dy)` to
    // raster pixel `(dx - px_x_min, dy - px_y_min)`. The viewport is in
    // device-space units (not pixels), so divide by scale.
    let sub_ctx = RenderContext {
        vp_x: px_x_min as f32 / scale_x,
        vp_y: px_y_min as f32 / scale_y,
        scale_x,
        scale_y,
        out_w: raster_w,
        out_h: raster_h,
        effective_dpi,
        icc,
        image_cache: None,
        preprocessed: None,
        elem_idx: 0,
        no_aa,
        opm_zero_transparent: false,
        knockout_painter_pass: KnockoutPainterPass::None,
        parent_group_isolated: false,
        alpha_extraction_pass: false,
        layer_set,
    };

    // 5. Mask rendering doesn't participate in CMYK overprint compositing.
    let mut mask_band = BandState {
        clip_region: None,
        spare_mask: None,
        clip_mask_cache: HashMap::new(),
        clip_mask_seen: HashSet::new(),
        mask_pool: Vec::new(),
        cmyk_buffer: None,
        op_bg_snapshot: None,
        op_touched: None,
        spot_mask: None,
    };

    // 6. Render every element of the mask display list into the offscreen.
    for (idx, elem) in mask_list.elements().iter().enumerate() {
        let elem_ctx = RenderContext {
            elem_idx: idx,
            ..sub_ctx
        };
        render_element(&mut mask_pixmap, &mut mask_band, elem, &elem_ctx);
    }

    // 7. If the mask form contained nested gs-set SMask scopes, composite
    // the rendered mask onto the backdrop color before extracting
    // luminosity. Nested masks produce semi-transparent pixels where
    // alpha encodes the mask modulation; without compositing,
    // un-premultiplying would amplify the color and lose the modulation.
    // Only Luminosity: Alpha masks extract the alpha channel directly,
    // so forcing alpha=255 via compositing would destroy the mask info.
    if params.has_nested_mask_scope
        && params.subtype == stet_graphics::display_list::SoftMaskSubtype::Luminosity
    {
        let bc = params.backdrop_color.as_ref();
        let bd_r = bc.map_or(0u8, |c| (c[0].clamp(0.0, 1.0) * 255.0 + 0.5) as u8);
        let bd_g = bc.map_or(0u8, |c| (c[1].clamp(0.0, 1.0) * 255.0 + 0.5) as u8);
        let bd_b = bc.map_or(0u8, |c| (c[2].clamp(0.0, 1.0) * 255.0 + 0.5) as u8);
        for chunk in mask_pixmap.data_mut().chunks_exact_mut(4) {
            let a = chunk[3] as u16;
            if a == 255 {
                continue;
            }
            let inv_a = 255 - a;
            chunk[0] = ((chunk[0] as u16 * 255 + bd_r as u16 * inv_a + 127) / 255) as u8;
            chunk[1] = ((chunk[1] as u16 * 255 + bd_g as u16 * inv_a + 127) / 255) as u8;
            chunk[2] = ((chunk[2] as u16 * 255 + bd_b as u16 * inv_a + 127) / 255) as u8;
            chunk[3] = 255;
        }
    }

    // 8. Extract grayscale mask values into a flat single-channel buffer.
    let pixel_count = (raster_w * raster_h) as usize;
    let mut data = vec![0u8; pixel_count];
    extract_soft_mask_values(mask_pixmap.data(), &mut data, params);

    Some(stet_graphics::display_list::MaskRaster {
        data,
        width: raster_w,
        height: raster_h,
        origin_x: px_x_min,
        origin_y: px_y_min,
        scale_x,
        scale_y,
    })
}

/// Transform a display element's CTM through a matrix so that pattern-space
/// coordinates map to device space.  Recursively transforms children of
/// Group and SoftMasked elements, and adjusts their bboxes.
fn transform_element_ctm(elem: &DisplayElement, pm: &Matrix) -> DisplayElement {
    match elem {
        DisplayElement::Fill { path, params } => {
            let mut p = params.clone();
            p.ctm = pm.concat(&p.ctm);
            DisplayElement::Fill {
                path: path.clone(),
                params: p,
            }
        }
        DisplayElement::Stroke { path, params } => {
            let mut p = params.clone();
            p.ctm = pm.concat(&p.ctm);
            DisplayElement::Stroke {
                path: path.clone(),
                params: p,
            }
        }
        DisplayElement::Clip { path, params } => {
            let mut p = params.clone();
            p.ctm = pm.concat(&p.ctm);
            if let Some(ref mut sp) = p.stroke_params {
                sp.ctm = pm.concat(&sp.ctm);
            }
            DisplayElement::Clip {
                path: path.clone(),
                params: p,
            }
        }
        DisplayElement::Image {
            sample_data,
            params,
        } => {
            let mut p = params.clone();
            p.ctm = pm.concat(&p.ctm);
            DisplayElement::Image {
                sample_data: sample_data.clone(),
                params: p,
            }
        }
        DisplayElement::MeshShading { params } => {
            let mut p = params.clone();
            p.ctm = pm.concat(&p.ctm);
            DisplayElement::MeshShading { params: p }
        }
        DisplayElement::PatchShading { params } => {
            let mut p = params.clone();
            p.ctm = pm.concat(&p.ctm);
            DisplayElement::PatchShading { params: p }
        }
        DisplayElement::AxialShading { params } => {
            let mut p = params.clone();
            p.ctm = pm.concat(&p.ctm);
            DisplayElement::AxialShading { params: p }
        }
        DisplayElement::RadialShading { params } => {
            let mut p = params.clone();
            p.ctm = pm.concat(&p.ctm);
            DisplayElement::RadialShading { params: p }
        }
        DisplayElement::Group { elements, params } => {
            let mut t = DisplayList::new();
            for child in elements.elements() {
                t.push(transform_element_ctm(child, pm));
            }
            let mut p = params.clone();
            let corners = [
                pm.transform_point(p.bbox[0], p.bbox[1]),
                pm.transform_point(p.bbox[2], p.bbox[1]),
                pm.transform_point(p.bbox[0], p.bbox[3]),
                pm.transform_point(p.bbox[2], p.bbox[3]),
            ];
            p.bbox = [
                corners.iter().map(|c| c.0).fold(f64::INFINITY, f64::min),
                corners.iter().map(|c| c.1).fold(f64::INFINITY, f64::min),
                corners
                    .iter()
                    .map(|c| c.0)
                    .fold(f64::NEG_INFINITY, f64::max),
                corners
                    .iter()
                    .map(|c| c.1)
                    .fold(f64::NEG_INFINITY, f64::max),
            ];
            DisplayElement::Group {
                elements: t,
                params: p,
            }
        }
        DisplayElement::SoftMasked {
            mask,
            content,
            params,
            ..
        } => {
            let mut t_mask = DisplayList::new();
            for child in mask.elements() {
                t_mask.push(transform_element_ctm(child, pm));
            }
            let mut t_content = DisplayList::new();
            for child in content.elements() {
                t_content.push(transform_element_ctm(child, pm));
            }
            let mut p = params.clone();
            let corners = [
                pm.transform_point(p.bbox[0], p.bbox[1]),
                pm.transform_point(p.bbox[2], p.bbox[1]),
                pm.transform_point(p.bbox[0], p.bbox[3]),
                pm.transform_point(p.bbox[2], p.bbox[3]),
            ];
            p.bbox = [
                corners.iter().map(|c| c.0).fold(f64::INFINITY, f64::min),
                corners.iter().map(|c| c.1).fold(f64::INFINITY, f64::min),
                corners
                    .iter()
                    .map(|c| c.0)
                    .fold(f64::NEG_INFINITY, f64::max),
                corners
                    .iter()
                    .map(|c| c.1)
                    .fold(f64::NEG_INFINITY, f64::max),
            ];
            // parent_clip_bbox was captured in the original (pattern)
            // coordinate system. Transform it through pm to match the
            // device-space coords that mask/content elements were just
            // moved into; otherwise the renderer would intersect a
            // device-space mask bbox with a pattern-space clip and get
            // an empty raster.
            if let Some(pcb) = p.parent_clip_bbox {
                let pcb_corners = [
                    pm.transform_point(pcb[0], pcb[1]),
                    pm.transform_point(pcb[2], pcb[1]),
                    pm.transform_point(pcb[0], pcb[3]),
                    pm.transform_point(pcb[2], pcb[3]),
                ];
                p.parent_clip_bbox = Some([
                    pcb_corners
                        .iter()
                        .map(|c| c.0)
                        .fold(f64::INFINITY, f64::min),
                    pcb_corners
                        .iter()
                        .map(|c| c.1)
                        .fold(f64::INFINITY, f64::min),
                    pcb_corners
                        .iter()
                        .map(|c| c.0)
                        .fold(f64::NEG_INFINITY, f64::max),
                    pcb_corners
                        .iter()
                        .map(|c| c.1)
                        .fold(f64::NEG_INFINITY, f64::max),
                ]);
            }
            // The transformed element's coordinate system is different
            // from the original; the original cache (if any) is invalid.
            // Allocate a fresh cache cell.
            DisplayElement::SoftMasked {
                mask: t_mask,
                content: t_content,
                params: p,
                mask_cache: Arc::new(Mutex::new(None)),
            }
        }
        DisplayElement::PatternFill { params } => {
            let mut p = params.clone();
            p.pattern_matrix = pm.concat(&p.pattern_matrix);
            // Transform the fill path (device-space coordinates)
            p.path = transform_path_by_matrix(&p.path, pm);
            if let Some(ref mut sp) = p.stroke_params {
                sp.ctm = pm.concat(&sp.ctm);
            }
            DisplayElement::PatternFill { params: p }
        }
        DisplayElement::OcgGroup {
            elements,
            visibility,
        } => {
            let mut t = DisplayList::new();
            for child in elements.elements() {
                t.push(transform_element_ctm(child, pm));
            }
            DisplayElement::OcgGroup {
                elements: t,
                visibility: visibility.clone(),
            }
        }
        other => other.clone(),
    }
}

/// Transform all points in a path through a matrix.
fn transform_path_by_matrix(path: &PsPath, m: &Matrix) -> PsPath {
    use stet_fonts::geometry::PathSegment;
    let mut out = PsPath::new();
    for seg in &path.segments {
        out.segments.push(match *seg {
            PathSegment::MoveTo(x, y) => {
                let (nx, ny) = m.transform_point(x, y);
                PathSegment::MoveTo(nx, ny)
            }
            PathSegment::LineTo(x, y) => {
                let (nx, ny) = m.transform_point(x, y);
                PathSegment::LineTo(nx, ny)
            }
            PathSegment::CurveTo {
                x1,
                y1,
                x2,
                y2,
                x3,
                y3,
            } => {
                let (nx1, ny1) = m.transform_point(x1, y1);
                let (nx2, ny2) = m.transform_point(x2, y2);
                let (nx3, ny3) = m.transform_point(x3, y3);
                PathSegment::CurveTo {
                    x1: nx1,
                    y1: ny1,
                    x2: nx2,
                    y2: ny2,
                    x3: nx3,
                    y3: ny3,
                }
            }
            PathSegment::ClosePath => PathSegment::ClosePath,
        });
    }
    out
}

/// Render a tiled pattern fill.
/// Bilinear downscale of premultiplied RGBA image data.
///
/// Used to pre-scale pattern tile images when the device-space tile is smaller
/// than the image resolution, since tiny-skia's `draw_pixmap` doesn't handle
/// sub-1.0 scale transforms.
fn bilinear_prescale(src: &[u8], sw: u32, sh: u32, dw: u32, dh: u32) -> Vec<u8> {
    let mut dst = vec![0u8; (dw * dh * 4) as usize];
    for dy in 0..dh {
        let sy_f = (dy as f64 + 0.5) * sh as f64 / dh as f64 - 0.5;
        let sy0 = sy_f.floor().max(0.0) as u32;
        let sy1 = (sy0 + 1).min(sh - 1);
        let fy = (sy_f - sy0 as f64) as f32;
        let ify = 1.0 - fy;
        for dx in 0..dw {
            let sx_f = (dx as f64 + 0.5) * sw as f64 / dw as f64 - 0.5;
            let sx0 = sx_f.floor().max(0.0) as u32;
            let sx1 = (sx0 + 1).min(sw - 1);
            let fx = (sx_f - sx0 as f64) as f32;
            let ifx = 1.0 - fx;

            let i00 = (sy0 * sw + sx0) as usize * 4;
            let i10 = (sy0 * sw + sx1) as usize * 4;
            let i01 = (sy1 * sw + sx0) as usize * 4;
            let i11 = (sy1 * sw + sx1) as usize * 4;
            let di = (dy * dw + dx) as usize * 4;
            for c in 0..4 {
                dst[di + c] = (src[i00 + c] as f32 * ifx * ify
                    + src[i10 + c] as f32 * fx * ify
                    + src[i01 + c] as f32 * ifx * fy
                    + src[i11 + c] as f32 * fx * fy)
                    .round() as u8;
            }
        }
    }
    dst
}

fn render_pattern_fill(
    pixmap: &mut Pixmap,
    band_state: &mut BandState,
    params: &stet_graphics::device::PatternFillParams,
    ctx: &RenderContext<'_>,
) {
    let mut temp_mask = None;
    let Some(mask_ref) = resolve_clip_mask(
        &band_state.clip_region,
        &mut temp_mask,
        ctx.out_w,
        ctx.out_h,
    ) else {
        return;
    };

    let pm = &params.pattern_matrix;

    // Tile step vectors in device space (handles rotation/shear)
    let (step_ux, step_uy) = pm.transform_delta(params.xstep, 0.0);
    let (step_vx, step_vy) = pm.transform_delta(0.0, params.ystep);

    let step_u_len = (step_ux * step_ux + step_uy * step_uy).sqrt();
    let step_v_len = (step_vx * step_vx + step_vy * step_vy).sqrt();
    if step_u_len < 0.01 || step_v_len < 0.01 {
        return;
    }

    let origin_x = pm.tx;
    let origin_y = pm.ty;

    // Viewport bounds in device space
    let dev_vp_x = ctx.vp_x as f64;
    let dev_vp_y = ctx.vp_y as f64;
    let dev_vp_w = ctx.out_w as f64 / ctx.scale_x as f64;
    let dev_vp_h = ctx.out_h as f64 / ctx.scale_y as f64;

    let (mut min_x, mut min_y, mut max_x, mut max_y) = (f64::MAX, f64::MAX, f64::MIN, f64::MIN);
    for seg in &params.path.segments {
        let (x, y) = match seg {
            PathSegment::MoveTo(x, y) | PathSegment::LineTo(x, y) => (*x, *y),
            PathSegment::CurveTo { x3, y3, .. } => (*x3, *y3),
            PathSegment::ClosePath => continue,
        };
        min_x = min_x.min(x);
        min_y = min_y.min(y);
        max_x = max_x.max(x);
        max_y = max_y.max(y);
    }

    // For stroke patterns, the path extends beyond the centerline by half
    // the stroke width.  The path is in user space; transform the bbox
    // corners through the CTM to get device-space bounds.
    if let Some(ref sp) = params.stroke_params {
        // Transform user-space bbox corners through CTM to device space
        let ctm = &sp.ctm;
        let corners = [
            ctm.transform_point(min_x, min_y),
            ctm.transform_point(max_x, min_y),
            ctm.transform_point(min_x, max_y),
            ctm.transform_point(max_x, max_y),
        ];
        min_x = f64::MAX;
        min_y = f64::MAX;
        max_x = f64::MIN;
        max_y = f64::MIN;
        for (cx, cy) in &corners {
            min_x = min_x.min(*cx);
            min_y = min_y.min(*cy);
            max_x = max_x.max(*cx);
            max_y = max_y.max(*cy);
        }
        // Expand by half stroke width in device space
        let half_w = sp.line_width
            * 0.5
            * (ctm.a * ctm.a + ctm.b * ctm.b)
                .sqrt()
                .max((ctm.c * ctm.c + ctm.d * ctm.d).sqrt());
        min_x -= half_w;
        min_y -= half_w;
        max_x += half_w;
        max_y += half_w;
    }

    // Clamp to viewport bounds in device space
    min_x = min_x.max(dev_vp_x);
    min_y = min_y.max(dev_vp_y);
    max_x = max_x.min(dev_vp_x + dev_vp_w);
    max_y = max_y.min(dev_vp_y + dev_vp_h);
    if min_x >= max_x || min_y >= max_y {
        return;
    }

    let det = step_ux * step_vy - step_uy * step_vx;
    if det.abs() < 1e-10 {
        return;
    }
    let inv_det = 1.0 / det;

    let mut tu_min = f64::MAX;
    let mut tu_max = f64::MIN;
    let mut tv_min = f64::MAX;
    let mut tv_max = f64::MIN;
    for &(cx, cy) in &[
        (min_x, min_y),
        (max_x, min_y),
        (min_x, max_y),
        (max_x, max_y),
    ] {
        let dx = cx - origin_x;
        let dy = cy - origin_y;
        let tu = (dx * step_vy - dy * step_vx) * inv_det;
        let tv = (-dx * step_uy + dy * step_ux) * inv_det;
        tu_min = tu_min.min(tu);
        tu_max = tu_max.max(tu);
        tv_min = tv_min.min(tv);
        tv_max = tv_max.max(tv);
    }

    let tile_x_start = tu_min.floor() as i32 - 1;
    let tile_x_end = tu_max.ceil() as i32 + 1;
    let tile_y_start = tv_min.floor() as i32 - 1;
    let tile_y_end = tv_max.ceil() as i32 + 1;

    let tile_count = (tile_x_end - tile_x_start) as i64 * (tile_y_end - tile_y_start) as i64;
    if tile_count > 10000 {
        return;
    }

    let Some(mut tile_buf) = Pixmap::new(ctx.out_w, ctx.out_h) else {
        return;
    };

    let sx_f = ctx.scale_x as f64;
    let sy_f = ctx.scale_y as f64;

    if params.device_space_tile {
        // Device-space tile path: tile elements have CTMs in device space
        // (pattern matrix baked in). Use the full render_element pipeline
        // which handles all element types (clips, soft masks, shadings,
        // groups). For each tile position, shift the viewport origin by the
        // tile offset in device space.
        for tv in tile_y_start..tile_y_end {
            for tu in tile_x_start..tile_x_end {
                let offset_x = tu as f64 * step_ux + tv as f64 * step_vx;
                let offset_y = tu as f64 * step_uy + tv as f64 * step_vy;

                let tile_ctx = RenderContext {
                    vp_x: ctx.vp_x - offset_x as f32,
                    vp_y: ctx.vp_y - offset_y as f32,
                    scale_x: ctx.scale_x,
                    scale_y: ctx.scale_y,
                    out_w: ctx.out_w,
                    out_h: ctx.out_h,
                    effective_dpi: ctx.effective_dpi,
                    icc: ctx.icc,
                    image_cache: None,
                    preprocessed: None,
                    elem_idx: 0,
                    no_aa: ctx.no_aa,
                    opm_zero_transparent: params.overprint_mode == 1,
                    knockout_painter_pass: ctx.knockout_painter_pass,
                    parent_group_isolated: ctx.parent_group_isolated,
                    alpha_extraction_pass: ctx.alpha_extraction_pass,
                    layer_set: ctx.layer_set,
                };

                let mut tile_band = BandState {
                    clip_region: None,
                    spare_mask: None,
                    clip_mask_cache: HashMap::new(),
                    clip_mask_seen: HashSet::new(),
                    mask_pool: Vec::new(),
                    cmyk_buffer: None,
                    op_bg_snapshot: None,
                    op_touched: None,
                    spot_mask: None,
                };

                for (idx, elem) in params.tile.elements().iter().enumerate() {
                    let elem_ctx = RenderContext {
                        elem_idx: idx,
                        ..tile_ctx
                    };
                    render_element(&mut tile_buf, &mut tile_band, elem, &elem_ctx);
                }
            }
        }
    } else if params.tile.elements().iter().any(|e| {
        !matches!(
            e,
            DisplayElement::Fill { .. }
                | DisplayElement::Stroke { .. }
                | DisplayElement::Image { .. }
                | DisplayElement::Clip { .. }
                | DisplayElement::InitClip
        )
    }) {
        // Complex tile path: pre-render one tile into a small pixmap using
        // the full render_element pipeline (handles shadings, groups,
        // soft masks, etc.), then stamp copies at each tile position.
        let bbox = &params.bbox;
        let corners_dev = [
            pm.transform_point(bbox[0], bbox[1]),
            pm.transform_point(bbox[2], bbox[1]),
            pm.transform_point(bbox[0], bbox[3]),
            pm.transform_point(bbox[2], bbox[3]),
        ];
        let (mut td_x0, mut td_y0) = (f64::MAX, f64::MAX);
        let (mut td_x1, mut td_y1) = (f64::MIN, f64::MIN);
        for (x, y) in &corners_dev {
            td_x0 = td_x0.min(*x);
            td_y0 = td_y0.min(*y);
            td_x1 = td_x1.max(*x);
            td_y1 = td_y1.max(*y);
        }
        let tile_pw = ((td_x1 - td_x0) * sx_f).ceil().max(1.0) as u32;
        let tile_ph = ((td_y1 - td_y0) * sy_f).ceil().max(1.0) as u32;
        let tile_pw = tile_pw.min(8192);
        let tile_ph = tile_ph.min(8192);

        if let Some(mut one_tile) = Pixmap::new(tile_pw, tile_ph) {
            let tile_render_ctx = RenderContext {
                vp_x: td_x0 as f32,
                vp_y: td_y0 as f32,
                scale_x: ctx.scale_x,
                scale_y: ctx.scale_y,
                out_w: tile_pw,
                out_h: tile_ph,
                effective_dpi: ctx.effective_dpi,
                icc: ctx.icc,
                image_cache: None,
                preprocessed: None,
                elem_idx: 0,
                no_aa: ctx.no_aa,
                opm_zero_transparent: params.overprint_mode == 1,
                knockout_painter_pass: ctx.knockout_painter_pass,
                parent_group_isolated: ctx.parent_group_isolated,
                alpha_extraction_pass: ctx.alpha_extraction_pass,
                layer_set: ctx.layer_set,
            };
            let mut tile_bs = BandState {
                clip_region: None,
                spare_mask: None,
                clip_mask_cache: HashMap::new(),
                clip_mask_seen: HashSet::new(),
                mask_pool: Vec::new(),
                cmyk_buffer: None,
                op_bg_snapshot: None,
                op_touched: None,
                spot_mask: None,
            };
            for (idx, elem) in params.tile.elements().iter().enumerate() {
                let transformed = transform_element_ctm(elem, pm);
                let elem_ctx = RenderContext {
                    elem_idx: idx,
                    ..tile_render_ctx
                };
                render_element(&mut one_tile, &mut tile_bs, &transformed, &elem_ctx);
            }
            // Stamp pre-rendered tile at each position
            for tv in tile_y_start..tile_y_end {
                for tu in tile_x_start..tile_x_end {
                    let offset_x = tu as f64 * step_ux + tv as f64 * step_vx;
                    let offset_y = tu as f64 * step_uy + tv as f64 * step_vy;
                    let px = ((td_x0 + offset_x - dev_vp_x) * sx_f) as i32;
                    let py = ((td_y0 + offset_y - dev_vp_y) * sy_f) as i32;
                    let paint = stet_tiny_skia::PixmapPaint {
                        opacity: 1.0,
                        blend_mode: BlendMode::SourceOver,
                        quality: stet_tiny_skia::FilterQuality::Nearest,
                    };
                    tile_buf.draw_pixmap(
                        px,
                        py,
                        one_tile.as_ref(),
                        &paint,
                        Transform::identity(),
                        None,
                    );
                }
            }
        }
    } else {
        // Simple tile path: tile elements have identity CTMs.
        // Manually apply the pattern matrix + tile offset for each element.
        // Only handles Fill, Stroke, Image, and Clip.

        // Pre-process Image elements: convert to RGBA once and pre-scale if
        // the combined transform would require downscaling (scale < 1.0).
        // tiny-skia's draw_pixmap doesn't handle sub-1.0 scale transforms.
        struct PreprocessedImage {
            rgba: Vec<u8>,
            width: u32,
            height: u32,
            /// Transform from pixel coords to pattern space, possibly adjusted
            /// to account for pre-scaling.
            img_transform: Transform,
        }
        let tile_elements = params.tile.elements();
        let mut preprocessed: Vec<Option<PreprocessedImage>> =
            Vec::with_capacity(tile_elements.len());
        // Tile transform scale components (constant across all tiles)
        let tt_sx = (pm.a * sx_f) as f32;
        let tt_sy = (pm.d * sy_f) as f32;
        let tt_kx = (pm.c * sx_f) as f32;
        let tt_ky = (pm.b * sy_f) as f32;
        for elem in tile_elements {
            if let DisplayElement::Image {
                sample_data,
                params: ip,
            } = elem
            {
                let iw = ip.width;
                let ih = ip.height;
                if iw > 0 && ih > 0 {
                    let mut rgba =
                        samples_to_rgba(sample_data, ip, ctx.icc, ctx.opm_zero_transparent);
                    if ip.mask_color.is_some() {
                        apply_mask_color_rgba(&mut rgba, sample_data, ip);
                    }
                    let expected = (iw * ih * 4) as usize;
                    if rgba.len() >= expected {
                        if let Some(inv) = ip.image_matrix.invert() {
                            let combined_mat = ip.ctm.concat(&inv);
                            let t = to_transform(&combined_mat);
                            // Check effective scale: t maps image pixels → pattern space,
                            // tile_transform maps pattern space → device space.
                            let test = t.post_concat(Transform::from_row(
                                tt_sx, tt_ky, tt_kx, tt_sy, 0.0, 0.0,
                            ));
                            let eff_sx = (test.sx * test.sx + test.ky * test.ky).sqrt();
                            let eff_sy = (test.kx * test.kx + test.sy * test.sy).sqrt();
                            if eff_sx < 0.99 || eff_sy < 0.99 {
                                // Pre-scale image to avoid sub-1.0 draw_pixmap transform.
                                // Use floor so the scaled image is smaller than the
                                // device-space tile, ensuring the adjusted scale >= 1.0.
                                let tw = (iw as f32 * eff_sx).floor().max(1.0) as u32;
                                let th = (ih as f32 * eff_sy).floor().max(1.0) as u32;
                                let scaled = bilinear_prescale(&rgba, iw, ih, tw, th);
                                // Adjust transform: pre-multiply a scale that maps new
                                // pixel coords back to original pixel coords
                                let adj = Transform::from_scale(
                                    iw as f32 / tw as f32,
                                    ih as f32 / th as f32,
                                );
                                preprocessed.push(Some(PreprocessedImage {
                                    rgba: scaled,
                                    width: tw,
                                    height: th,
                                    img_transform: t.pre_concat(adj),
                                }));
                            } else {
                                preprocessed.push(Some(PreprocessedImage {
                                    rgba,
                                    width: iw,
                                    height: ih,
                                    img_transform: t,
                                }));
                            }
                        } else {
                            preprocessed.push(None);
                        }
                    } else {
                        preprocessed.push(None);
                    }
                } else {
                    preprocessed.push(None);
                }
                // Note: only Image elements push to preprocessed, so img_idx
                // in the tile loop correctly indexes this array.
            }
        }

        for tv in tile_y_start..tile_y_end {
            for tu in tile_x_start..tile_x_end {
                let pat_offset_x = tu as f64 * params.xstep;
                let pat_offset_y = tv as f64 * params.ystep;

                let tile_transform = Transform::from_row(
                    tt_sx,
                    tt_ky,
                    tt_kx,
                    tt_sy,
                    ((pm.a * pat_offset_x + pm.c * pat_offset_y + pm.tx - dev_vp_x) * sx_f) as f32,
                    ((pm.b * pat_offset_x + pm.d * pat_offset_y + pm.ty - dev_vp_y) * sy_f) as f32,
                );

                // Clip tile elements to BBox (PDF spec 8.7.4.2)
                let bbox_clip = {
                    let bb = &params.bbox;
                    let mut bp = stet_tiny_skia::PathBuilder::new();
                    bp.move_to(bb[0] as f32, bb[1] as f32);
                    bp.line_to(bb[2] as f32, bb[1] as f32);
                    bp.line_to(bb[2] as f32, bb[3] as f32);
                    bp.line_to(bb[0] as f32, bb[3] as f32);
                    bp.close();
                    bp.finish().and_then(|sp| {
                        let mut m = Mask::new(ctx.out_w, ctx.out_h)?;
                        m.fill_path(
                            &sp,
                            stet_tiny_skia::FillRule::Winding,
                            false,
                            tile_transform,
                        );
                        Some(m)
                    })
                };
                let mut tile_clip: Option<Mask> = bbox_clip;
                let mut img_idx = 0usize;
                for elem in tile_elements {
                    let clip_ref = tile_clip.as_ref();
                    match elem {
                        DisplayElement::Clip { path, params: cp } => {
                            if let Some(sp) = build_skia_path(path) {
                                let t = to_transform(&cp.ctm);
                                let combined = t.post_concat(tile_transform);
                                let mut mask = Mask::new(ctx.out_w, ctx.out_h).expect("mask");
                                mask.fill_path(&sp, to_fill_rule(&cp.fill_rule), false, combined);
                                if let Some(prev) = tile_clip.take() {
                                    intersect_masks(&mut mask, &prev);
                                }
                                tile_clip = Some(mask);
                            }
                        }
                        DisplayElement::InitClip => {
                            tile_clip = None;
                        }
                        DisplayElement::Fill { path, params: fp } => {
                            if let Some(sp) = build_skia_path(path) {
                                let mut paint = if params.paint_type == 1 {
                                    to_paint(&fp.color)
                                } else {
                                    to_paint(
                                        params
                                            .underlying_color
                                            .as_ref()
                                            .unwrap_or(&DeviceColor::black()),
                                    )
                                };
                                paint.anti_alias = false;
                                let t = to_transform(&fp.ctm);
                                let combined = t.post_concat(tile_transform);
                                let fr = to_fill_rule(&fp.fill_rule);
                                tile_buf.fill_path(&sp, &paint, fr, combined, clip_ref);
                            }
                        }
                        DisplayElement::Stroke { path, params: sp } => {
                            if let Some(skp) = build_skia_path(path) {
                                // Compose element CTM with pattern matrix so
                                // hairline_min_width sees the real device scale,
                                // not the tile's identity CTM.
                                let effective_ctm = pm.concat(&sp.ctm);
                                let mut sp_adj = sp.clone();
                                sp_adj.ctm = effective_ctm;
                                let stroke = build_stroke(&sp_adj, ctx.effective_dpi);
                                let paint = if params.paint_type == 1 {
                                    to_paint(&sp.color)
                                } else {
                                    to_paint(
                                        params
                                            .underlying_color
                                            .as_ref()
                                            .unwrap_or(&DeviceColor::black()),
                                    )
                                };
                                let t = to_transform(&sp.ctm);
                                let combined = t.post_concat(tile_transform);
                                tile_buf.stroke_path(&skp, &paint, &stroke, combined, clip_ref);
                            }
                        }
                        DisplayElement::Image { .. } => {
                            if let Some(ref pi) = preprocessed[img_idx] {
                                let combined = pi.img_transform.post_concat(tile_transform);
                                if let Some(img_ref) = stet_tiny_skia::PixmapRef::from_bytes(
                                    &pi.rgba, pi.width, pi.height,
                                ) {
                                    let paint = stet_tiny_skia::PixmapPaint {
                                        opacity: 1.0,
                                        blend_mode: BlendMode::SourceOver,
                                        quality: stet_tiny_skia::FilterQuality::Nearest,
                                    };
                                    tile_buf.draw_pixmap(0, 0, img_ref, &paint, combined, clip_ref);
                                }
                            }
                            img_idx += 1;
                        }
                        _ => {}
                    }
                }
            }
        }
    }

    // Composite tile_buf onto main pixmap through the fill/stroke path
    let Some(fill_skia_path) = build_skia_path(&params.path) else {
        return;
    };
    let fill_rule = to_fill_rule(&params.fill_rule);
    let mut fill_mask = Mask::new(ctx.out_w, ctx.out_h).expect("mask");
    let path_transform = viewport_transform(
        Transform::identity(),
        ctx.vp_x,
        ctx.vp_y,
        ctx.scale_x,
        ctx.scale_y,
    );
    if let Some(ref sp) = params.stroke_params {
        // Stroke pattern: expand the centerline path to a fill outline
        // using the stroke parameters (width, cap, join, miter, dash).
        // Apply dash pattern first (Path::stroke doesn't handle dashing).
        let stroke = build_stroke(sp, ctx.effective_dpi);
        let ctm_transform = to_transform(&sp.ctm);
        let combined = ctm_transform.post_concat(path_transform);
        let res_scale = stet_tiny_skia::PathStroker::compute_resolution_scale(&combined);
        let dashed;
        let stroke_path = if let Some(ref dash) = stroke.dash {
            dashed = fill_skia_path.dash(dash, res_scale);
            match dashed.as_ref() {
                Some(p) => p,
                None => &fill_skia_path,
            }
        } else {
            &fill_skia_path
        };
        if let Some(outline) = stroke_path.stroke(&stroke, res_scale) {
            fill_mask.fill_path(
                &outline,
                stet_tiny_skia::FillRule::Winding,
                !ctx.no_aa,
                combined,
            );
        }
    } else {
        fill_mask.fill_path(&fill_skia_path, fill_rule, !ctx.no_aa, path_transform);
    }

    if let Some(clip_mask) = mask_ref {
        intersect_masks(&mut fill_mask, clip_mask);
    }

    let img_paint = stet_tiny_skia::PixmapPaint::default();
    pixmap.draw_pixmap(
        0,
        0,
        tile_buf.as_ref(),
        &img_paint,
        Transform::identity(),
        Some(&fill_mask),
    );
}

/// Unified clip path handling for both band and viewport rendering.
///
/// For band rendering (scale=1.0), includes rect fast-path and Y-bbox early exit.
/// For viewport rendering (scale!=1.0), uses the general mask path.
fn clip_path_unified(
    band_state: &mut BandState,
    path: &PsPath,
    params: &ClipParams,
    ctx: &RenderContext<'_>,
) {
    let is_unit_scale = ctx.scale_x == 1.0 && ctx.scale_y == 1.0;

    // Band-mode optimizations (scale=1.0): Y-bbox early exit and rect fast-path
    if is_unit_scale {
        let y_start = ctx.vp_y as u32;
        let x_start = ctx.vp_x as u32;

        // Y-bbox early exit: if clip path doesn't overlap this band, set empty clip
        // (only valid when CTM is identity — path coords must be in device space).
        // Skip when stroke_params is present: the path is in user space and
        // needs the stroke CTM transform, so raw Y bounds are meaningless here.
        if x_start == 0
            && params.stroke_params.is_none()
            && params.ctm.a == 1.0
            && params.ctm.d == 1.0
            && params.ctm.tx == 0.0
            && params.ctm.ty == 0.0
            && let Some(bbox) = path_y_bbox(path)
            && (bbox.y_max <= y_start as f64 || bbox.y_min >= (y_start + ctx.out_h) as f64)
        {
            if let Some(ClipRegion::Mask(mask)) = band_state.clip_region.take() {
                band_state.recycle_mask(mask);
            }
            band_state.clip_region = Some(ClipRegion::Rect(ClipRect {
                x0: 0,
                y0: 0,
                x1: 0,
                y1: 0,
            }));
            return;
        }

        // Rect fast-path (only when x_start==0 and CTM is identity —
        // detect_rect uses raw path coords which are only in device space
        // when the CTM is identity)
        let ctm_is_identity = params.ctm.a == 1.0
            && params.ctm.b == 0.0
            && params.ctm.c == 0.0
            && params.ctm.d == 1.0
            && params.ctm.tx == 0.0
            && params.ctm.ty == 0.0;
        if x_start == 0
            && ctm_is_identity
            && params.stroke_params.is_none()
            && let Some(dev_rect) = detect_rect(path, ctx.out_w, u32::MAX)
        {
            let new_rect = translate_clip_rect(&dev_rect, y_start, ctx.out_h);
            match band_state.clip_region.take() {
                None => {
                    band_state.clip_region = Some(ClipRegion::Rect(new_rect));
                }
                Some(ClipRegion::Rect(existing)) => {
                    band_state.clip_region = Some(ClipRegion::Rect(existing.intersect(&new_rect)));
                }
                Some(ClipRegion::Mask(mut mask)) => {
                    intersect_mask_with_rect(&mut mask, &new_rect, ctx.out_w, ctx.out_h);
                    band_state.clip_region = Some(ClipRegion::Mask(mask));
                }
            }
            return;
        }
    }

    // General path: non-rectangular clip with cache + mask reuse
    let fill_rule = to_fill_rule(&params.fill_rule);
    let path_hash = hash_clip_path(path, &params.fill_rule);
    let prev_region = band_state.clip_region.take();

    let mut mask = band_state.take_mask(ctx.out_w, ctx.out_h);

    let path_mask = if let Some(cached) = band_state.clip_mask_cache.get(&path_hash) {
        mask.data_mut().copy_from_slice(cached.data());
        mask
    } else {
        let Some(skia_path) = build_skia_path(path) else {
            band_state.recycle_mask(mask);
            band_state.clip_region = prev_region;
            return;
        };
        mask.data_mut().fill(0);
        if let Some(ref sp) = params.stroke_params {
            // Stroke-based clip: expand centerline to stroke outline.
            // Apply dash pattern first (Path::stroke doesn't handle dashing).
            let stroke = build_stroke(sp, ctx.effective_dpi);
            let transform = ctx.transform(&sp.ctm);
            let res_scale = stet_tiny_skia::PathStroker::compute_resolution_scale(&transform);
            let dashed;
            let stroke_path = if let Some(ref dash) = stroke.dash {
                dashed = skia_path.dash(dash, res_scale);
                match dashed.as_ref() {
                    Some(p) => p,
                    None => &skia_path,
                }
            } else {
                &skia_path
            };
            if let Some(outline) = stroke_path.stroke(&stroke, res_scale) {
                mask.fill_path(
                    &outline,
                    stet_tiny_skia::FillRule::Winding,
                    false,
                    transform,
                );
            }
        } else {
            let transform = ctx.transform(&params.ctm);
            mask.fill_path(&skia_path, fill_rule, false, transform);
        }
        if !band_state.clip_mask_seen.insert(path_hash) {
            band_state.clip_mask_cache.insert(path_hash, mask.clone());
        }
        mask
    };

    match prev_region {
        None => {
            band_state.clip_region = Some(ClipRegion::Mask(path_mask));
        }
        Some(ClipRegion::Rect(rect)) => {
            if rect.is_empty() {
                band_state.recycle_mask(path_mask);
                // Intersection with empty clip is still empty — preserve empty state.
                // Without this, clip_region stays None (= no clip = paint everything).
                band_state.clip_region = Some(ClipRegion::Rect(rect));
            } else {
                let mut mask = path_mask;
                intersect_mask_with_rect(&mut mask, &rect, ctx.out_w, ctx.out_h);
                band_state.clip_region = Some(ClipRegion::Mask(mask));
            }
        }
        Some(ClipRegion::Mask(mut existing)) => {
            intersect_masks(&mut existing, &path_mask);
            band_state.recycle_mask(path_mask);
            band_state.clip_region = Some(ClipRegion::Mask(existing));
        }
    }
}
impl OutputDevice for SkiaDevice {
    fn fill_path(&mut self, path: &PsPath, params: &FillParams) {
        self.ensure_full_pixmap();
        let Some(skia_path) = build_skia_path(path) else {
            return;
        };
        let (w, h) = (self.pixmap.width(), self.pixmap.height());
        let mut temp_mask = None;
        let Some(mask_ref) = resolve_clip_mask(&self.clip_region, &mut temp_mask, w, h) else {
            return; // empty clip
        };

        let paint = to_paint_alpha(&params.color, params.alpha, params.blend_mode, self.no_aa);
        let transform = to_transform(&params.ctm);
        let fill_rule = to_fill_rule(&params.fill_rule);

        self.pixmap
            .fill_path(&skia_path, &paint, fill_rule, transform, mask_ref);
    }

    fn stroke_path(&mut self, path: &PsPath, params: &StrokeParams) {
        self.ensure_full_pixmap();
        let stroke = build_stroke(params, self.dpi);
        let adjusted;
        let draw_path =
            if params.stroke_adjust && stroke.width <= 2.0 && ctm_is_device_space(&params.ctm) {
                adjusted =
                    stroke_adjust_path_viewport(path, stroke.width as f64, 1.0, 1.0, 0.0, 0.0);
                &adjusted
            } else {
                path
            };
        let Some(skia_path) = build_skia_path(draw_path) else {
            return;
        };
        let paint = to_paint_alpha(&params.color, params.alpha, params.blend_mode, self.no_aa);
        let transform = to_transform(&params.ctm);

        let (w, h) = (self.pixmap.width(), self.pixmap.height());
        let mut temp_mask = None;
        let Some(mask_ref) = resolve_clip_mask(&self.clip_region, &mut temp_mask, w, h) else {
            return; // empty clip
        };

        self.pixmap
            .stroke_path(&skia_path, &paint, &stroke, transform, mask_ref);
    }

    fn clip_path(&mut self, path: &PsPath, params: &ClipParams) {
        self.ensure_full_pixmap();
        let (w, h) = (self.pixmap.width(), self.pixmap.height());

        // Fast path: detect axis-aligned rectangle
        if let Some(new_rect) = detect_rect(path, w, h) {
            match self.clip_region.take() {
                None => {
                    self.clip_region = Some(ClipRegion::Rect(new_rect));
                }
                Some(ClipRegion::Rect(existing)) => {
                    // O(1) rect-rect intersection
                    self.clip_region = Some(ClipRegion::Rect(existing.intersect(&new_rect)));
                }
                Some(ClipRegion::Mask(mut mask)) => {
                    // Zero mask pixels outside rect
                    intersect_mask_with_rect(&mut mask, &new_rect, w, h);
                    self.clip_region = Some(ClipRegion::Mask(mask));
                }
            }
            return;
        }

        // Slow path: non-rectangular clip with mask caching + allocation reuse.
        let fill_rule = to_fill_rule(&params.fill_rule);
        let path_hash = hash_clip_path(path, &params.fill_rule);
        let prev_region = self.clip_region.take();

        // Reuse a spare mask buffer if available (avoids alloc/dealloc per tile).
        macro_rules! take_spare {
            ($self:expr, $w:expr, $h:expr) => {
                $self
                    .spare_mask
                    .take()
                    .unwrap_or_else(|| Mask::new($w, $h).expect("Failed to create mask"))
            };
        }

        // Try cache first; rasterize only on miss
        let path_mask = if let Some(cached) = self.clip_mask_cache.get(&path_hash) {
            // Cache hit: copy cached data into reused buffer (memcpy, no alloc)
            let mut mask = take_spare!(self, w, h);
            mask.data_mut().copy_from_slice(cached.data());
            mask
        } else {
            let Some(skia_path) = build_skia_path(path) else {
                self.clip_region = prev_region;
                return;
            };
            let transform = to_transform(&params.ctm);
            let mut mask = take_spare!(self, w, h);
            mask.data_mut().fill(0); // zero before rasterizing (spare may have old data)
            mask.fill_path(&skia_path, fill_rule, false, transform);
            // Cache on second sight: first time just record, second time store
            if !self.clip_mask_seen.insert(path_hash) {
                // Seen before — cache it (this clone only happens once per unique path)
                self.clip_mask_cache.insert(path_hash, mask.clone());
            }
            mask
        };

        match prev_region {
            None => {
                self.clip_region = Some(ClipRegion::Mask(path_mask));
            }
            Some(ClipRegion::Rect(rect)) => {
                if rect.is_empty() {
                    self.spare_mask = Some(path_mask); // recycle
                } else {
                    let mut mask = path_mask;
                    intersect_mask_with_rect(&mut mask, &rect, w, h);
                    self.clip_region = Some(ClipRegion::Mask(mask));
                }
            }
            Some(ClipRegion::Mask(mut existing)) => {
                intersect_masks(&mut existing, &path_mask);
                self.spare_mask = Some(path_mask); // recycle the copy
                self.clip_region = Some(ClipRegion::Mask(existing));
            }
        }
    }

    fn init_clip(&mut self) {
        if let Some(ClipRegion::Mask(mask)) = self.clip_region.take() {
            self.spare_mask = Some(mask);
        }
        self.clip_region = None;
    }

    fn erase_page(&mut self) {
        // Only fill the full pixmap when it's actually allocated (non-banded path).
        // During banding, self.pixmap is a 1×1 placeholder — filling it is harmless.
        self.pixmap.fill(Color::WHITE);
        if let Some(ClipRegion::Mask(mask)) = self.clip_region.take() {
            self.spare_mask = Some(mask);
        }
        self.clip_region = None;
    }

    fn show_page(&mut self, output_path: &str) -> Result<(), String> {
        let w = self.pixmap.width();
        let h = self.pixmap.height();
        // Composite onto white background before output
        composite_onto_white(self.pixmap.data_mut());
        let mut sink = self.sink_factory.create_sink(output_path)?;
        sink.begin_page(w, h)?;
        sink.write_rows(self.pixmap.data(), h)?;
        sink.end_page()
    }

    fn draw_image(&mut self, sample_data: &[u8], params: &ImageParams) {
        self.ensure_full_pixmap();
        let w = params.width;
        let h = params.height;
        if w == 0 || h == 0 {
            return;
        }
        let mut rgba_data =
            samples_to_rgba(sample_data, params, self.render_icc_cache.as_ref(), false);
        if params.mask_color.is_some() {
            apply_mask_color_rgba(&mut rgba_data, sample_data, params);
        }
        let expected = (w * h * 4) as usize;
        if rgba_data.len() < expected {
            return;
        }

        let Some(image_inv) = params.image_matrix.invert() else {
            return;
        };
        let combined = params.ctm.concat(&image_inv);
        let raw_transform = enforce_min_image_size(to_transform(&combined), w, h);

        let prescaled = prescale_image(&rgba_data, w, h, raw_transform, params.interpolate);
        let (img_data, img_w, img_h, transform) = match &prescaled {
            Some((data, pw, ph, t)) => (data.as_slice(), *pw, *ph, *t),
            None => (rgba_data.as_slice(), w, h, raw_transform),
        };

        let Some(img_pixmap) = stet_tiny_skia::PixmapRef::from_bytes(img_data, img_w, img_h) else {
            return;
        };

        let (pw, ph) = (self.pixmap.width(), self.pixmap.height());
        let mut temp_mask = None;
        let Some(mask_ref) = resolve_clip_mask(&self.clip_region, &mut temp_mask, pw, ph) else {
            return;
        };

        let paint = stet_tiny_skia::PixmapPaint {
            quality: image_filter_quality(transform, params.interpolate),
            opacity: params.alpha as f32,
            blend_mode: u8_to_blend_mode(params.blend_mode),
        };
        self.pixmap
            .draw_pixmap(0, 0, img_pixmap, &paint, transform, mask_ref);
    }

    fn paint_axial_shading(&mut self, params: &AxialShadingParams) {
        self.ensure_full_pixmap();
        let (w, h) = (self.pixmap.width(), self.pixmap.height());
        let mut temp_mask = None;
        let Some(mask_ref) = resolve_clip_mask(&self.clip_region, &mut temp_mask, w, h) else {
            return;
        };
        render_axial_shading(
            &mut self.pixmap,
            params,
            0.0,
            0.0,
            1.0,
            1.0,
            mask_ref,
            self.no_aa,
            None,
            None,
        );
    }

    fn paint_radial_shading(&mut self, params: &RadialShadingParams) {
        self.ensure_full_pixmap();
        let (w, h) = (self.pixmap.width(), self.pixmap.height());
        let mut temp_mask = None;
        let Some(mask_ref) = resolve_clip_mask(&self.clip_region, &mut temp_mask, w, h) else {
            return;
        };
        render_radial_shading(
            &mut self.pixmap,
            params,
            0.0,
            0.0,
            1.0,
            1.0,
            mask_ref,
            self.no_aa,
            None,
            None,
        );
    }

    fn paint_mesh_shading(&mut self, params: &MeshShadingParams) {
        self.ensure_full_pixmap();
        let (w, h) = (self.pixmap.width(), self.pixmap.height());
        let mut temp_mask = None;
        let Some(mask_ref) = resolve_clip_mask(&self.clip_region, &mut temp_mask, w, h) else {
            return;
        };
        render_mesh_shading(
            &mut self.pixmap,
            params,
            0.0,
            0.0,
            1.0,
            1.0,
            mask_ref,
            None,
            None,
        );
    }

    fn paint_patch_shading(&mut self, params: &PatchShadingParams) {
        self.ensure_full_pixmap();
        let (w, h) = (self.pixmap.width(), self.pixmap.height());
        let mut temp_mask = None;
        let Some(mask_ref) = resolve_clip_mask(&self.clip_region, &mut temp_mask, w, h) else {
            return;
        };
        render_patch_shading(
            &mut self.pixmap,
            params,
            0.0,
            0.0,
            1.0,
            1.0,
            mask_ref,
            None,
            None,
        );
    }

    fn paint_pattern_fill(&mut self, params: &stet_graphics::device::PatternFillParams) {
        self.ensure_full_pixmap();
        let w = self.pixmap.width();
        let h = self.pixmap.height();
        let mut band_state = BandState {
            clip_region: self.clip_region.take(),
            spare_mask: self.spare_mask.take(),
            clip_mask_cache: HashMap::new(),
            clip_mask_seen: HashSet::new(),
            mask_pool: Vec::new(),
            cmyk_buffer: None,
            op_bg_snapshot: None,
            op_touched: None,
            spot_mask: None,
        };
        {
            let ctx = RenderContext {
                vp_x: 0.0,
                vp_y: 0.0,
                scale_x: 1.0,
                scale_y: 1.0,
                out_w: w,
                out_h: h,
                effective_dpi: self.dpi,
                icc: None,
                image_cache: None,
                preprocessed: None,
                elem_idx: 0,
                no_aa: self.no_aa,
                opm_zero_transparent: false,
                knockout_painter_pass: KnockoutPainterPass::None,
                parent_group_isolated: false,
                alpha_extraction_pass: false,
                layer_set: &self.layer_set,
            };
            render_pattern_fill(&mut self.pixmap, &mut band_state, params, &ctx);
        }
        self.clip_region = band_state.clip_region.take();
        if let Some(mask) = band_state.spare_mask.take() {
            self.spare_mask = Some(mask);
        }
    }

    fn page_size(&self) -> (u32, u32) {
        (self.page_w, self.page_h)
    }

    fn replay_and_show(&mut self, list: DisplayList, output_path: &str) -> Result<(), String> {
        // Wait for any previous background render to complete
        self.join_pending()?;

        let (page_w, page_h) = self.page_size();

        // Audit mode: re-render through the viewport pipeline so visual tests
        // can catch viewport-only bugs against the same baselines. Same
        // `render_element`, same display list — differs only in how culling
        // and epochs are computed.
        if self.use_viewport_path {
            let icc_cache = build_icc_cache_for_list(&list, self.system_cmyk_bytes.as_ref(), false);
            let rgba = render_to_rgba_viewport(
                &list,
                page_w,
                page_h,
                self.dpi,
                Some(&icc_cache),
                self.no_aa,
            );
            let mut sink = self.sink_factory.create_sink(output_path)?;
            sink.begin_page(page_w, page_h)?;
            sink.write_rows(&rgba, page_h)?;
            sink.end_page()?;
            return Ok(());
        }

        let band_h = select_band_height(page_w, page_h);

        // Build ICC cache for this page's display list
        let icc_cache = build_icc_cache_for_list(&list, self.system_cmyk_bytes.as_ref(), false);

        // If banding not worthwhile, render the full page as a single band.
        // This still uses render_element (same as banded path) so that Group
        // and SoftMasked elements get proper offscreen compositing.
        if band_h >= page_h {
            self.ensure_full_pixmap();
            let ctx = RenderContext {
                vp_x: 0.0,
                vp_y: 0.0,
                scale_x: 1.0,
                scale_y: 1.0,
                out_w: page_w,
                out_h: page_h,
                effective_dpi: self.dpi,
                icc: Some(&icc_cache),
                image_cache: None,
                preprocessed: None,
                elem_idx: 0,
                no_aa: self.no_aa,
                opm_zero_transparent: false,
                knockout_painter_pass: KnockoutPainterPass::None,
                parent_group_isolated: false,
                alpha_extraction_pass: false,
                layer_set: &self.layer_set,
            };
            let mut band_state = BandState {
                clip_region: None,
                spare_mask: None,
                clip_mask_cache: HashMap::new(),
                clip_mask_seen: HashSet::new(),
                mask_pool: Vec::new(),
                cmyk_buffer: None,
                op_bg_snapshot: None,
                op_touched: None,
                spot_mask: None,
            };
            for (idx, elem) in list.elements().iter().enumerate() {
                let elem_ctx = RenderContext {
                    elem_idx: idx,
                    ..ctx
                };
                render_element(&mut self.pixmap, &mut band_state, elem, &elem_ctx);
            }
            return self.show_page(output_path);
        }

        // Banded path: shrink self.pixmap to free memory — we use a
        // band-sized pixmap instead. This avoids holding a multi-GB
        // full-page buffer during rendering.
        if self.pixmap.width() > 1 {
            self.pixmap = Pixmap::new(1, 1).expect("Failed to create placeholder pixmap");
        }

        // Create the sink for this page before spawning background work
        let mut sink = self.sink_factory.create_sink(output_path)?;
        let dpi = self.dpi;
        let layer_set = self.layer_set.clone();

        #[cfg(feature = "parallel")]
        {
            // Spawn banded rendering on rayon's thread pool, overlapping with
            // interpretation of the next page. Using rayon::spawn avoids OS thread
            // creation overhead and keeps work on the warmed-up pool.
            let no_aa = self.no_aa;
            let (tx, rx) = std::sync::mpsc::sync_channel(1);
            rayon::spawn(move || {
                let result = render_banded_to_sink(
                    page_w, page_h, band_h, dpi, &list, &mut *sink, &icc_cache, no_aa, &layer_set,
                );
                let _ = tx.send(result);
            });
            self.pending_render = Some(rx);
        }
        #[cfg(not(feature = "parallel"))]
        {
            render_banded_to_sink(
                page_w, page_h, band_h, dpi, &list, &mut *sink, &icc_cache, self.no_aa, &layer_set,
            )?;
        }

        Ok(())
    }

    fn finish(&mut self) -> Result<(), String> {
        self.join_pending()
    }
}

impl Drop for SkiaDevice {
    fn drop(&mut self) {
        // Safety net: ensure background render completes before device is destroyed.
        if let Some(rx) = self.pending_render.take() {
            let _ = rx.recv();
        }
    }
}

impl SkiaDevice {
    /// Wait for the pending background render to complete, if any.
    fn join_pending(&mut self) -> Result<(), String> {
        if let Some(rx) = self.pending_render.take() {
            match rx.recv() {
                Ok(result) => result?,
                Err(_) => return Err("Background render task failed".to_string()),
            }
        }
        Ok(())
    }
}

/// Returns true if any descendant transparency group declares an explicit
/// `/CS DeviceCMYK`. The renderer uses this to decide whether to allocate a
/// parallel CMYK buffer for the band/page so that compositing inside CMYK
/// groups can read the exact backdrop CMYK rather than rounding-trip via sRGB.
fn has_cmyk_group(list: &DisplayList) -> bool {
    use stet_graphics::display_list::GroupColorSpace;
    for elem in list.elements() {
        match elem {
            DisplayElement::Group { elements, params } => {
                if params.color_space == GroupColorSpace::DeviceCMYK {
                    return true;
                }
                if has_cmyk_group(elements) {
                    return true;
                }
            }
            DisplayElement::SoftMasked { content, mask, .. } => {
                if has_cmyk_group(content) || has_cmyk_group(mask) {
                    return true;
                }
            }
            DisplayElement::OcgGroup { elements, .. } => {
                if has_cmyk_group(elements) {
                    return true;
                }
            }
            _ => {}
        }
    }
    false
}

/// Returns true if every visible element in `elements` is a `Fill` whose
/// color carries `native_cmyk`. Clip and `InitClip` ops are skipped (they
/// don't paint). Returns `false` for any other shape (shadings, images,
/// patterns, nested groups, etc.) where the inner CMYK buffer would be
/// derived from sRGB via the lossy `interpolate_cmyk_from_stops` /
/// `(1-r,1-g,1-b,0)` inverse rather than tracked from the source CMYK.
fn group_only_native_cmyk_fills(elements: &DisplayList) -> bool {
    let mut found_paint = false;
    for elem in elements.elements() {
        match elem {
            DisplayElement::InitClip => continue,
            DisplayElement::Clip { .. } => continue,
            DisplayElement::Fill { params, .. } => {
                if params.color.native_cmyk.is_none() {
                    return false;
                }
                found_paint = true;
            }
            DisplayElement::Stroke { params, .. } => {
                // Strokes write a single CMYK value per painted pixel just
                // like fills, so the parallel CMYK buffer stays in sync with
                // the pixmap. Including strokes here is required by GWG 16.1
                // painters whose X path is both filled and stroked with the
                // same registration color.
                if params.color.native_cmyk.is_none() {
                    return false;
                }
                found_paint = true;
            }
            _ => return false,
        }
    }
    found_paint
}

/// Stronger predicate: returns `true` when every paint operation in `elements`
/// supplies its color directly as CMYK with one CMYK value per painted pixel
/// — i.e. the parallel CMYK buffer is *guaranteed* to match the rendered
/// pixmap on a per-pixel basis. When this holds, the per-pixel CMYK
/// composite-back can run safely.
///
/// Importantly, this excludes **shadings** even when their declared color
/// space is DeviceCMYK. The pixmap rasterizer interpolates the per-stop
/// `.color` (RGB) linearly across the gradient via [`build_gradient_lut`],
/// while [`interpolate_cmyk_from_stops`] interpolates the per-stop CMYK
/// `raw_components` linearly. Because the system CMYK ICC profile is
/// non-linear, the two interpolation strategies produce different intermediate
/// colors at each gradient pixel — the buffer no longer represents what the
/// pixmap shows, and feeding that into the composite-back yields visibly
/// shifted colors. Until the per-pixel rasterizer is taught to interpolate
/// CMYK directly (or the buffer is filled by ICC-reversing the pixmap), keep
/// shadings on the existing sRGB compositing path.
///
/// Recurses into nested groups and soft masks. Returns `false` if the group
/// contains no paint operations at all (so the composite-back has no work).
fn group_content_is_native_cmyk(elements: &DisplayList) -> bool {
    let mut found_paint = false;
    for elem in elements.elements() {
        match elem {
            DisplayElement::InitClip => continue,
            DisplayElement::Clip { .. } => continue,
            DisplayElement::Text { .. } => continue,
            DisplayElement::ErasePage => continue,
            DisplayElement::Fill { params, .. } => {
                if params.color.native_cmyk.is_none() {
                    return false;
                }
                found_paint = true;
            }
            DisplayElement::Stroke { params, .. } => {
                if params.color.native_cmyk.is_none() {
                    return false;
                }
                found_paint = true;
            }
            DisplayElement::Image { params, .. } => {
                if !is_cmyk_color_space(&params.color_space) {
                    return false;
                }
                found_paint = true;
            }
            DisplayElement::AxialShading { .. }
            | DisplayElement::RadialShading { .. }
            | DisplayElement::MeshShading { .. }
            | DisplayElement::PatchShading { .. } => {
                // See doc comment above: shading interpolation strategies
                // diverge between pixmap and buffer.
                return false;
            }
            DisplayElement::PatternFill { .. } => {
                // Pattern tiles render through their own BandState with
                // `cmyk_buffer: None`, so the parallel CMYK buffer can't track
                // per-tile source CMYK. Treat patterns as non-CMYK content.
                return false;
            }
            DisplayElement::Group { elements: sub, .. } => {
                if !group_content_is_native_cmyk(sub) {
                    return false;
                }
                found_paint = true;
            }
            DisplayElement::SoftMasked { .. } => {
                // Soft masks apply a per-pixel alpha modulation that the
                // parallel CMYK buffer cannot represent: the buffer holds raw
                // source CMYK while the pixmap holds the soft-masked blend
                // (`backdrop * (1 − mask) + source * mask`). Running
                // `composite_non_isolated_cmyk` over a soft-masked region
                // would feed the unmodulated source CMYK into the blend
                // formula and produce the wrong result for any non-Normal
                // parent blend mode (5310.pdf phone highlight regression).
                // Fall back to the sRGB contribution-extraction path, which
                // handles soft masks correctly.
                return false;
            }
            DisplayElement::OcgGroup { elements: sub, .. } => {
                if !group_content_is_native_cmyk(sub) {
                    return false;
                }
                found_paint = true;
            }
            _ => return false,
        }
    }
    found_paint
}

/// True when `list` is a flat sequence of native-CMYK Fill/Stroke paints
/// with Normal blend and full opacity — i.e. the cmyk_buffer's content
/// faithfully represents what the pixmap shows. Used by `render_soft_masked`
/// to decide whether to interpolate the mask blend in CMYK (ICC→sRGB).
/// Rejects Group/SoftMasked/Image/Shading/Pattern and any blend-mode-modulated
/// paint because those would diverge from the parallel CMYK snapshot.
fn content_list_is_simple_native_cmyk(list: &DisplayList) -> bool {
    let mut found_paint = false;
    for elem in list.elements() {
        match elem {
            DisplayElement::InitClip
            | DisplayElement::Clip { .. }
            | DisplayElement::Text { .. }
            | DisplayElement::ErasePage => continue,
            DisplayElement::Fill { params, .. } => {
                if params.color.native_cmyk.is_none() {
                    return false;
                }
                if params.blend_mode != 0 || params.alpha != 1.0 {
                    return false;
                }
                found_paint = true;
            }
            DisplayElement::Stroke { params, .. } => {
                if params.color.native_cmyk.is_none() {
                    return false;
                }
                if params.blend_mode != 0 || params.alpha != 1.0 {
                    return false;
                }
                found_paint = true;
            }
            // Recurse into a transparency Group only when the group itself is
            // Normal-blend / full-opacity AND its contents are themselves
            // simple native CMYK. This lets gradient-feather-style content
            // (a Group wrapping a single CMYK fill, GWG 16.11) qualify for
            // CMYK-domain mask blending while the prior outer-glow C
            // regression (a Group wrapping a Screen-blend white rect, GWG
            // 16.10) still gets rejected on the inner blend_mode check.
            DisplayElement::Group { params, elements } => {
                if params.blend_mode != 0 || params.alpha != 1.0 {
                    return false;
                }
                if !content_list_is_simple_native_cmyk(elements) {
                    return false;
                }
                // A Group whose contents are all clip/text without paint
                // adds no paint of its own; don't flip `found_paint` here —
                // the recursive call already counted any inner paints.
                if elements.elements().iter().any(|e| {
                    matches!(
                        e,
                        DisplayElement::Fill { .. } | DisplayElement::Stroke { .. }
                    )
                }) {
                    found_paint = true;
                }
            }
            _ => return false,
        }
    }
    found_paint
}

/// Scan a display list for any overprint fill/stroke elements that need CMYK simulation.
fn has_overprint_elements(list: &DisplayList) -> bool {
    for elem in list.elements() {
        match elem {
            DisplayElement::Fill { params, .. } => {
                if params.overprint {
                    return true;
                }
            }
            DisplayElement::Stroke { params, .. } => {
                if params.overprint {
                    return true;
                }
            }
            DisplayElement::Image { params, .. } => {
                if params.overprint {
                    return true;
                }
            }
            DisplayElement::AxialShading { params } => {
                if params.overprint {
                    return true;
                }
            }
            DisplayElement::RadialShading { params } => {
                if params.overprint {
                    return true;
                }
            }
            DisplayElement::MeshShading { params } => {
                if params.overprint {
                    return true;
                }
            }
            DisplayElement::PatchShading { params } => {
                if params.overprint {
                    return true;
                }
            }
            DisplayElement::Group { elements, .. } => {
                if has_overprint_elements(elements) {
                    return true;
                }
            }
            DisplayElement::SoftMasked { content, mask, .. } => {
                if has_overprint_elements(content) || has_overprint_elements(mask) {
                    return true;
                }
            }
            DisplayElement::OcgGroup { elements, .. } => {
                if has_overprint_elements(elements) {
                    return true;
                }
            }
            _ => {}
        }
    }
    false
}

/// Render an overprint fill: rasterize path to coverage mask, then composite
/// at the CMYK level, converting the result to RGB for the pixmap.
#[allow(clippy::too_many_arguments)]
fn render_overprint_fill(
    pixmap: &mut Pixmap,
    cmyk_buf: &mut [f32],
    op_bg: &mut [u8],
    op_touched: &mut [u8],
    spot_mask: &[u8],
    band_state: &mut BandState,
    path: &PsPath,
    params: &FillParams,
    vp_x: f32,
    vp_y: f32,
    scale_x: f32,
    scale_y: f32,
    out_w: u32,
    out_h: u32,
    icc: Option<&IccCache>,
    no_aa: bool,
) {
    let Some(skia_path) = build_skia_path(path) else {
        return;
    };
    let fill_rule = to_fill_rule(&params.fill_rule);

    let mut coverage_mask = match Mask::new(out_w, out_h) {
        Some(m) => m,
        None => return,
    };
    let transform = viewport_transform(to_transform(&params.ctm), vp_x, vp_y, scale_x, scale_y);
    coverage_mask.fill_path(&skia_path, fill_rule, !no_aa, transform);

    // Compute path bbox for constrained iteration
    let (bbox_x0, bbox_y0, bbox_x1, bbox_y1) =
        path_device_bbox(&skia_path, transform, out_w, out_h);

    // Intersect with clip mask
    let clip_coverage: Option<&[u8]> = match &band_state.clip_region {
        None => None,
        Some(ClipRegion::Rect(r)) => {
            // Only zero coverage within the path bbox (not the full page)
            let data = coverage_mask.data_mut();
            let stride = out_w as usize;
            for y in bbox_y0..bbox_y1 {
                let row_start = y * stride;
                for x in bbox_x0..bbox_x1 {
                    let yu = y as u32;
                    let xu = x as u32;
                    if yu < r.y0 || yu >= r.y1 || xu < r.x0 || xu >= r.x1 {
                        data[row_start + x] = 0;
                    }
                }
            }
            None
        }
        Some(ClipRegion::Mask(clip_mask)) => Some(clip_mask.data()),
    };

    // Custom spot paints (Separation/DeviceN whose named colorants don't include
    // any process channel) go to a separation plate, not CMYK. In the composite
    // preview we layer the spot's alt-CMYK onto the pixmap via multiplicative
    // ink stacking and leave the cmyk_buffer untouched — otherwise a later OPM 1
    // overprint would see the spot's alt-CMYK as "backdrop" and knock it out.
    let is_custom_spot = params.painted_channels == 0 && !params.is_device_cmyk;

    // Source CMYK preference: for paints with a process colorant in the mix
    // (Separation /Black, DeviceN [Black, …]), prefer `process_cmyk` — it
    // carries the named-colorant tint at full f64 precision (e.g. `(0, 0, 0,
    // 0.5)` for 50% /Black), matching what `update_cmyk_buffer_for_fill` writes
    // into the process buffer. Without this, the X paint reads native (e.g.
    // 0.502 from an 8-bit-quantized sampled Function) while the BG wrote
    // process (0.500), the per-pixel delta clears the 1e-4 no-op skip
    // threshold, and the X over-paints the spot backdrop with plain ICC-grey
    // (GWG 3.0 swatches c/i, "50% sep. black over spot").
    //
    // Custom spots (no process colorant) keep reading `native_cmyk` — that's
    // the spot's visual alt-CMYK representation, while `process_cmyk` is
    // `(0, 0, 0, 0)` for pure spots (the process buffer should not record
    // their tint). Falling back to native here keeps spot-coloured text
    // visible (1307.pdf "Business of the Meeting" in PANTONE 7427 C).
    let (src_c, src_m, src_y, src_k) = if !is_custom_spot && let Some(c) = params.color.process_cmyk
    {
        c
    } else if let Some(c) = params.color.native_cmyk {
        c
    } else {
        let r = params.color.r;
        let g = params.color.g;
        let b = params.color.b;
        (1.0 - r, 1.0 - g, 1.0 - b, 0.0)
    };

    let mut channels = params.painted_channels;
    // Non-CMYK fills (painted_channels=0, e.g. Separation spot colors, RGB, Gray)
    // replace all color at each pixel — update all CMYK channels to keep buffer in sync.
    if channels == 0 {
        channels = stet_graphics::device::CMYK_ALL;
    }
    // OPM 1 per-pixel zero filtering only applies to DeviceCMYK, not DeviceN/Separation
    if params.overprint_mode == 1
        && channels == stet_graphics::device::CMYK_ALL
        && params.is_device_cmyk
    {
        channels = 0;
        if src_c != 0.0 {
            channels |= stet_graphics::device::CMYK_C;
        }
        if src_m != 0.0 {
            channels |= stet_graphics::device::CMYK_M;
        }
        if src_y != 0.0 {
            channels |= stet_graphics::device::CMYK_Y;
        }
        if src_k != 0.0 {
            channels |= stet_graphics::device::CMYK_K;
        }
        // PDF 1.7 §7.6.4.5: OPM 1 with /op true preserves zero-source
        // components — leave `channels = 0` for an all-zero CMYK source only
        // when the gstate signals "strict overprint": /OPM and /op|/OP were
        // set together in the same ExtGState dict (as Adobe Illustrator
        // emits) OR /OP and /op were paired in one dict (legacy old-style
        // overprint, e.g. GWG 12.0 White Overprint where /GS6 sets both).
        // When the current /op was set standalone and OPM was merely
        // inherited (e.g. 2495.pdf page 5 page-icon, where /R20 has only
        // /op and OPM=1 came from /R11), fall back to legacy knockout so
        // a `0 0 0 0 k` paint still acts as a white knockout.
        if channels == 0 && !params.opm_paired {
            channels = stet_graphics::device::CMYK_ALL;
        }
    }

    // Bulk tiny-skia fast path for the plain CMYK_ALL replace case. Skipped
    // only for K-only DeviceCMYK paints under OPM 0 (C=M=Y=0, any K) because
    // those match the Black plate of a DeviceN [Black, spot] backdrop and
    // need the per-pixel no-op-delta skip to preserve spot-derived colour —
    // the bulk fill_path here would otherwise wipe the spot. Other CMYK
    // overprints (teal, full-colour, etc.) stay on the fast path to avoid
    // AA drift vs the non-overprint rasteriser.
    let is_k_only_cmyk = params.is_device_cmyk
        && params.overprint_mode == 0
        && src_c == 0.0
        && src_m == 0.0
        && src_y == 0.0;
    if channels == stet_graphics::device::CMYK_ALL && !is_custom_spot && !is_k_only_cmyk {
        let cov_data = coverage_mask.data();
        let stride = out_w as usize;
        for y in bbox_y0..bbox_y1 {
            for x in bbox_x0..bbox_x1 {
                let mi = y * stride + x;
                let mut cov = cov_data[mi] as f32 / 255.0;
                if let Some(clip) = clip_coverage {
                    cov *= clip[mi] as f32 / 255.0;
                }
                if cov > 0.0 {
                    let ci = mi * 4;
                    cmyk_buf[ci] = src_c as f32;
                    cmyk_buf[ci + 1] = src_m as f32;
                    cmyk_buf[ci + 2] = src_y as f32;
                    cmyk_buf[ci + 3] = src_k as f32;
                }
            }
        }
        let mut temp_mask = None;
        let Some(mask_ref) =
            resolve_clip_mask(&band_state.clip_region, &mut temp_mask, out_w, out_h)
        else {
            return;
        };
        let paint = to_paint_alpha(&params.color, params.alpha, params.blend_mode, no_aa);
        pixmap.fill_path(&skia_path, &paint, fill_rule, transform, mask_ref);
        return;
    }

    let cov_data = coverage_mask.data();
    let stride = out_w as usize;
    let px_data = pixmap.data_mut();
    let px_stride = out_w as usize * 4;

    for y in bbox_y0..bbox_y1 {
        for x in bbox_x0..bbox_x1 {
            let mi = y * stride + x;
            let mut cov = cov_data[mi] as f32 / 255.0;
            if let Some(clip) = clip_coverage {
                cov *= clip[mi] as f32 / 255.0;
            }
            if cov <= 0.0 {
                continue;
            }

            let ci = mi * 4;
            let pi = y * px_stride + x * 4;
            // Snapshot-based AA blending: on the first overprint touch of a
            // pixel that already has a backdrop (alpha > 0), capture the
            // pre-paint pixmap RGBA. Subsequent overprints at the same pixel
            // blend against the snapshot rather than the current pixmap, so
            // AA edges of stacked OPM-1 overprints do not leak colour from
            // earlier paints into later ones.
            if op_touched[mi] == 0 && px_data[pi + 3] > 0 {
                op_bg[pi] = px_data[pi];
                op_bg[pi + 1] = px_data[pi + 1];
                op_bg[pi + 2] = px_data[pi + 2];
                op_bg[pi + 3] = px_data[pi + 3];
                op_touched[mi] = 1;
            }
            let cur_c = cmyk_buf[ci] as f64;
            let cur_m = cmyk_buf[ci + 1] as f64;
            let cur_y = cmyk_buf[ci + 2] as f64;
            let cur_k = cmyk_buf[ci + 3] as f64;
            // Switch to multiplicative ink-stacking when the pixmap carries a
            // contribution not reflected in cmyk_buffer: either this paint is
            // itself a custom spot (painted_channels=0, non-CMYK) or the
            // process-ink state is empty while the pixmap shows colour *and*
            // is actually opaque — that signals a spot (or RGB) paint landed
            // here and the "replace" CMYK→RGB model would erase the
            // contribution for the channels being overwritten. Fully
            // transparent pixels are stored as premultiplied (0,0,0,0), so we
            // must require alpha>0 before trusting the RGB — otherwise fresh
            // paper (alpha=0) looks like "black backdrop" and multiplicative
            // darkening would paint the fill pure black.
            let cur_is_clean = cur_c == 0.0 && cur_m == 0.0 && cur_y == 0.0 && cur_k == 0.0;
            let pixmap_has_colour = px_data[pi + 3] > 0
                && (px_data[pi] < 250 || px_data[pi + 1] < 250 || px_data[pi + 2] < 250);
            // Multiplicative ink-stacking only when the pixmap carries a real
            // backdrop: either this paint is a custom spot landing on an
            // already-coloured pixel, or the process-ink buffer is empty but
            // the pixmap shows colour (prior spot/RGB paint). On fresh paper
            // (alpha=0 → premultiplied (0,0,0,0)) multiplicative would darken
            // the fill to pure black, so those pixels fall through to the
            // replace path where the source RGB paints normally.
            let use_multiplicative = (is_custom_spot || cur_is_clean) && pixmap_has_colour;

            // Promoted DeviceGray on a non-spot backdrop: fall back to a
            // plain knockout that replaces all four CMYK plates. The
            // `maybe_promote_gray_fill` path describes the paint as a
            // K-only subset so spot-backed swatches can preserve the spot
            // plate (GWG 3.0 "50% gray over spot"), but on a plain CMYK
            // backdrop that would preserve the old CMY values and turn the
            // cross into the bg colour (GWG 3.0 "50% gray over CMYK" e/k).
            // Expanding to CMYK_ALL here restores the regular-fill result
            // at those pixels.
            //
            // Gate on `params.painted_channels == CMYK_K` so this only fires
            // for genuinely-promoted DeviceGray. A `0 0 0 0.5 k` DeviceCMYK
            // paint filtered to CMYK_K by OPM 1 has `params.painted_channels
            // = CMYK_ALL`, and must stay K-subset so its CMY=0 values do
            // not wipe a CMYK backdrop (GWG 3.0 "50% K over CMYK" j/d).
            let is_promoted_gray = params.painted_channels == stet_graphics::device::CMYK_K
                && channels == stet_graphics::device::CMYK_K
                && params.is_device_cmyk
                && src_c == 0.0
                && src_m == 0.0
                && src_y == 0.0;
            let effective_channels = if is_promoted_gray && spot_mask[mi] == 0 {
                stet_graphics::device::CMYK_ALL
            } else {
                channels
            };

            let new_c = if effective_channels & stet_graphics::device::CMYK_C != 0 {
                src_c
            } else {
                cur_c
            };
            let new_m = if effective_channels & stet_graphics::device::CMYK_M != 0 {
                src_m
            } else {
                cur_m
            };
            let new_y = if effective_channels & stet_graphics::device::CMYK_Y != 0 {
                src_y
            } else {
                cur_y
            };
            let new_k = if effective_channels & stet_graphics::device::CMYK_K != 0 {
                src_k
            } else {
                cur_k
            };

            // Custom spot paints live on a separation plate — skip the
            // cmyk_buffer write so a later OPM 1 overprint still sees the
            // original process-ink state as backdrop.
            if !is_custom_spot {
                cmyk_buf[ci] = new_c as f32;
                cmyk_buf[ci + 1] = new_m as f32;
                cmyk_buf[ci + 2] = new_y as f32;
                cmyk_buf[ci + 3] = new_k as f32;
            }

            // No-op overprint: the paint's effective CMYK equals the existing
            // process state, so no plate actually changes. Skip the pixmap
            // write entirely — otherwise ICC(new_cmyk) paints a plain process
            // composite that erases any spot-derived colour already visible
            // at this pixel (GWG 3.0 "50% K over spot" swatches where the
            // backdrop's Black component and the cross's K value match).
            //
            // Only fire when a DeviceN/Separation paint with spot colorants
            // actually landed on this pixel (spot_mask[mi] != 0). On plain
            // CMYK backdrops, ICC(cmyk_buf) == pixmap_rgb already, and
            // skipping vs replacing produces the same result — but making
            // the skip unconditional subtly drifts AA edges because prior
            // stroke/fill precision accumulates (regressed GWG 1.0/1.1).
            let delta = (new_c - cur_c)
                .abs()
                .max((new_m - cur_m).abs())
                .max((new_y - cur_y).abs())
                .max((new_k - cur_k).abs());
            if delta < 1e-4 && spot_mask[mi] != 0 && pixmap_has_colour && !is_custom_spot {
                continue;
            }

            let (r, g, b) =
                if is_promoted_gray && effective_channels == stet_graphics::device::CMYK_ALL {
                    // Promoted DeviceGray collapsing to a full replace — use the
                    // paint's RGB directly so the pixmap matches the colour a
                    // regular non-overprint gray fill would paint at the same
                    // pixel. Going through ICC(CMYK) here would produce a
                    // slightly different gray (e.g. 151 vs 127) and leave a
                    // darker outline where a subsequent non-promoted gray
                    // stroke overpaints on top of it.
                    //
                    // Checked before `use_multiplicative` because a white gray
                    // paint (`1 g`, native CMYK (0,0,0,0)) on a coloured RGB
                    // backdrop (e.g. the red `Reset Form` button in 682.pdf
                    // page 2) would otherwise hit the multiplicative branch
                    // with all-zero source CMYK, which leaves the backdrop
                    // unchanged — hiding the white label.
                    (params.color.r, params.color.g, params.color.b)
                } else if use_multiplicative {
                    // Multiplicative ink stacking: each painted channel attenuates
                    // the corresponding RGB component; preserved channels leave
                    // the pixmap's existing colour untouched. This keeps any spot
                    // contribution already in the pixmap visible under overprints
                    // whose zero-valued CMYK components should not erase it.
                    let bg_r = px_data[pi] as f64 / 255.0;
                    let bg_g = px_data[pi + 1] as f64 / 255.0;
                    let bg_b = px_data[pi + 2] as f64 / 255.0;
                    let over_r = if channels & stet_graphics::device::CMYK_C != 0 {
                        1.0 - src_c
                    } else {
                        1.0
                    };
                    let over_g = if channels & stet_graphics::device::CMYK_M != 0 {
                        1.0 - src_m
                    } else {
                        1.0
                    };
                    let over_b = if channels & stet_graphics::device::CMYK_Y != 0 {
                        1.0 - src_y
                    } else {
                        1.0
                    };
                    let k_fac = if channels & stet_graphics::device::CMYK_K != 0 {
                        1.0 - src_k
                    } else {
                        1.0
                    };
                    (
                        (bg_r * over_r * k_fac).clamp(0.0, 1.0),
                        (bg_g * over_g * k_fac).clamp(0.0, 1.0),
                        (bg_b * over_b * k_fac).clamp(0.0, 1.0),
                    )
                } else if let Some(icc_cache) = icc {
                    icc_cache
                        .convert_cmyk_readonly(new_c, new_m, new_y, new_k)
                        .unwrap_or_else(|| cmyk_to_rgb_plrm(new_c, new_m, new_y, new_k))
                } else {
                    cmyk_to_rgb_plrm(new_c, new_m, new_y, new_k)
                };

            let a = (cov * params.alpha as f32).min(1.0);
            // Blend backdrop: prefer the pre-overprint snapshot only when
            // this paint's colour is close to the snapshot — that signals
            // the paint effectively returns the pixel to its original
            // backdrop (e.g. the almost-white cross in GWG 4.1 cancelling
            // the red cross's M/Y contributions). In that case blending
            // against the snapshot keeps AA edges clean.
            //
            // When the paint introduces colour (e.g. a magenta stroke
            // following a magenta fill — both lay down ink that should
            // stack), fall through to the current pixmap so repeated
            // same-colour paints keep compounding at edges instead of
            // snapping back to bg.
            let (bk_r, bk_g, bk_b, bk_a) = if op_touched[mi] != 0 {
                let new_r = (r as f32 * 255.0).clamp(0.0, 255.0);
                let new_g = (g as f32 * 255.0).clamp(0.0, 255.0);
                let new_b = (b as f32 * 255.0).clamp(0.0, 255.0);
                let dr = (op_bg[pi] as f32 - new_r).abs();
                let dg = (op_bg[pi + 1] as f32 - new_g).abs();
                let db = (op_bg[pi + 2] as f32 - new_b).abs();
                if dr.max(dg).max(db) <= 4.0 {
                    (op_bg[pi], op_bg[pi + 1], op_bg[pi + 2], op_bg[pi + 3])
                } else {
                    (
                        px_data[pi],
                        px_data[pi + 1],
                        px_data[pi + 2],
                        px_data[pi + 3],
                    )
                }
            } else {
                (
                    px_data[pi],
                    px_data[pi + 1],
                    px_data[pi + 2],
                    px_data[pi + 3],
                )
            };
            let dst_a = bk_a as f32 / 255.0;
            let one_minus_a = 1.0 - a;
            let out_a = a + dst_a * one_minus_a;
            if out_a > 0.0 {
                // tiny-skia stores premultiplied RGBA. Use the standard
                // src-over formula in premul space: result_pre = src*a + dst_pre*(1-a).
                // The backdrop values are already premultiplied, so no
                // additional divide-by-out_a step is needed.
                px_data[pi] = ((r as f32 * a + (bk_r as f32 / 255.0) * one_minus_a) * 255.0)
                    .clamp(0.0, 255.0)
                    .round() as u8;
                px_data[pi + 1] = ((g as f32 * a + (bk_g as f32 / 255.0) * one_minus_a) * 255.0)
                    .clamp(0.0, 255.0)
                    .round() as u8;
                px_data[pi + 2] = ((b as f32 * a + (bk_b as f32 / 255.0) * one_minus_a) * 255.0)
                    .clamp(0.0, 255.0)
                    .round() as u8;
                px_data[pi + 3] = (out_a * 255.0).round() as u8;
            }
        }
    }
}
/// PLRM CMYK-to-RGB formula fallback.
fn cmyk_to_rgb_plrm(c: f64, m: f64, y: f64, k: f64) -> (f64, f64, f64) {
    (
        1.0 - (c + k).min(1.0),
        1.0 - (m + k).min(1.0),
        1.0 - (y + k).min(1.0),
    )
}

/// Update the CMYK buffer for a non-overprint fill (to track backdrop for future overprints).
#[allow(clippy::too_many_arguments)]
/// Compute the device-space bounding box of a tiny-skia path after transform,
/// clamped to `(0, 0, w, h)`. Returns `(x0, y0, x1, y1)` as pixel indices.
fn path_device_bbox(
    skia_path: &stet_tiny_skia::Path,
    transform: Transform,
    w: u32,
    h: u32,
) -> (usize, usize, usize, usize) {
    let b = skia_path.bounds();
    let mut corners = [
        stet_tiny_skia::Point {
            x: b.left(),
            y: b.top(),
        },
        stet_tiny_skia::Point {
            x: b.right(),
            y: b.top(),
        },
        stet_tiny_skia::Point {
            x: b.right(),
            y: b.bottom(),
        },
        stet_tiny_skia::Point {
            x: b.left(),
            y: b.bottom(),
        },
    ];
    transform.map_points(&mut corners);
    let min_x = corners.iter().map(|p| p.x).fold(f32::INFINITY, f32::min);
    let min_y = corners.iter().map(|p| p.y).fold(f32::INFINITY, f32::min);
    let max_x = corners
        .iter()
        .map(|p| p.x)
        .fold(f32::NEG_INFINITY, f32::max);
    let max_y = corners
        .iter()
        .map(|p| p.y)
        .fold(f32::NEG_INFINITY, f32::max);
    // Floor/ceil + clamp to output dimensions (with 1px margin for AA)
    let x0 = (min_x.floor() as i32 - 1).max(0) as usize;
    let y0 = (min_y.floor() as i32 - 1).max(0) as usize;
    let x1 = (max_x.ceil() as i32 + 1).clamp(0, w as i32) as usize;
    let y1 = (max_y.ceil() as i32 + 1).clamp(0, h as i32) as usize;
    (x0, y0, x1, y1)
}

fn update_cmyk_buffer_for_fill(
    cmyk_buf: &mut [f32],
    spot_mask: &mut [u8],
    path: &PsPath,
    params: &FillParams,
    vp_x: f32,
    vp_y: f32,
    scale_x: f32,
    scale_y: f32,
    out_w: u32,
    out_h: u32,
    clip_region: &Option<ClipRegion>,
    no_aa: bool,
    icc: Option<&IccCache>,
) {
    // Custom spot paints (Separation/DeviceN naming no process channel) go to
    // their own separation plate — the process CMYK buffer must be zeroed
    // under the paint (knockout) so a later overprint sees "no process ink"
    // and falls into the multiplicative-blend branch that preserves the
    // spot's visible contribution in the pixmap.
    //
    // The `process_cmyk.is_some()` guard distinguishes "Separation/DeviceN
    // custom spot" (where `process_cmyk` is `Some((0,0,0,0))` per
    // `separation_process_cmyk`) from "any other non-CMYK fill that
    // happens to satisfy `painted_channels == 0 && !is_device_cmyk`" —
    // notably DeviceRGB, DeviceGray, and ICCBased RGB. The latter need to
    // deposit their full process CMYK into the buffer (via `native_cmyk`
    // from the proofing chain or via the ICC reverse) so the
    // `cmyk_group_blend` composite-back in `composite_non_isolated_cmyk`
    // can blend them correctly. Without this guard, GWG 16.1's
    // ICCBased-RGB swatches landed `(0,0,0,0)` in the form's CMYK
    // buffer; every separable blend then composited the X mark against a
    // zero source CMYK, painting the X with the form's source pixmap
    // RGB unchanged and producing the test's "X visible" failure.
    let is_custom_spot = params.painted_channels == 0
        && !params.is_device_cmyk
        && params.color.process_cmyk.is_some();

    // A DeviceN/Separation paint leaves "spot contribution" on the pixmap
    // when its full alt-CMYK (`native_cmyk`) differs from the process-only
    // tint (`process_cmyk`) — the extra RGB in the pixmap comes from a spot
    // plate that `cmyk_buf` cannot reflect. Pure DeviceCMYK paints have
    // `process_cmyk == None` (fall back to native), so no spot contribution.
    //
    // A "real" custom spot paint (`is_custom_spot && native_cmyk.is_some()`)
    // also deposits spot RGB that `cmyk_buf` loses (it's zeroed by the
    // custom-spot branch). Exclude DeviceRGB / DeviceGray / ICCBased-RGB
    // paints — those also satisfy `is_custom_spot = painted==0 &&
    // !is_device_cmyk` but carry no spot-plate contribution, and flagging
    // them would gate later OPM-1 cancel skips on a signal that doesn't
    // actually mean anything.
    let has_spot_contrib = (is_custom_spot && params.color.native_cmyk.is_some())
        || matches!(
            (params.color.native_cmyk, params.color.process_cmyk),
            (Some(nat), Some(proc_))
                if (nat.0 - proc_.0).abs() > 1e-6
                    || (nat.1 - proc_.1).abs() > 1e-6
                    || (nat.2 - proc_.2).abs() > 1e-6
                    || (nat.3 - proc_.3).abs() > 1e-6
        );

    // Source CMYK preference: process-only CMYK (from Separation/DeviceN paints
    // so spot-colorant tint contributions stay out of the process buffer) >
    // native CMYK (full alt-CMYK tint, fine for pure DeviceCMYK paints) > ICC
    // reverse (sRGB→CMYK via the system CMYK profile) > PLRM (1−r, 1−g, 1−b, 0)
    // fallback. The ICC reverse keeps non-CMYK fills (RGB/Gray/Lab/etc.)
    // representable as accurate CMYK in the parallel buffer so the
    // non-isolated CMYK composite-back can blend them correctly.
    let (src_c, src_m, src_y, src_k) = if is_custom_spot {
        (0.0, 0.0, 0.0, 0.0)
    } else if let Some(c) = params.color.process_cmyk {
        c
    } else if let Some(c) = params.color.native_cmyk {
        c
    } else if let Some(cmyk) = icc.and_then(|i| {
        i.convert_rgb_to_cmyk_readonly(params.color.r, params.color.g, params.color.b)
    }) {
        (cmyk[0], cmyk[1], cmyk[2], cmyk[3])
    } else {
        (
            (1.0 - params.color.r).clamp(0.0, 1.0),
            (1.0 - params.color.g).clamp(0.0, 1.0),
            (1.0 - params.color.b).clamp(0.0, 1.0),
            0.0,
        )
    };
    let Some(skia_path) = build_skia_path(path) else {
        return;
    };

    let mut coverage_mask = match Mask::new(out_w, out_h) {
        Some(m) => m,
        None => return,
    };
    let transform = viewport_transform(to_transform(&params.ctm), vp_x, vp_y, scale_x, scale_y);
    let fill_rule = to_fill_rule(&params.fill_rule);
    coverage_mask.fill_path(&skia_path, fill_rule, !no_aa, transform);

    let cov_data = coverage_mask.data();
    let clip_data: Option<&[u8]> = match clip_region {
        Some(ClipRegion::Mask(m)) => Some(m.data()),
        _ => None,
    };

    // Constrain iteration to the path's device-space bounding box
    let (mut bx0, mut by0, mut bx1, mut by1) =
        path_device_bbox(&skia_path, transform, out_w, out_h);
    if let Some(ClipRegion::Rect(r)) = clip_region {
        bx0 = bx0.max(r.x0 as usize);
        by0 = by0.max(r.y0 as usize);
        bx1 = bx1.min(r.x1 as usize);
        by1 = by1.min(r.y1 as usize);
    }

    let stride = out_w as usize;
    for y in by0..by1 {
        for x in bx0..bx1 {
            let mi = y * stride + x;
            let mut cov = cov_data[mi] as f32 / 255.0;
            if let Some(clip) = clip_data {
                cov *= clip[mi] as f32 / 255.0;
            }
            if cov > 0.0 {
                let ci = mi * 4;
                cmyk_buf[ci] = src_c as f32;
                cmyk_buf[ci + 1] = src_m as f32;
                cmyk_buf[ci + 2] = src_y as f32;
                cmyk_buf[ci + 3] = src_k as f32;
                if has_spot_contrib {
                    spot_mask[mi] = 1;
                }
            }
        }
    }
}

/// Render an overprint stroke: convert the stroke outline to a fill path,
/// rasterize a coverage mask, then composite per-pixel in CMYK so the painted
/// channels of the stroke colour replace the matching backdrop channels and
/// the result lands in the pixmap as RGB. Mirrors `render_overprint_fill`.
#[allow(clippy::too_many_arguments)]
fn render_overprint_stroke(
    pixmap: &mut Pixmap,
    cmyk_buf: &mut [f32],
    op_bg: &mut [u8],
    op_touched: &mut [u8],
    spot_mask: &[u8],
    band_state: &mut BandState,
    skia_path: &stet_tiny_skia::Path,
    stroke: &Stroke,
    transform: Transform,
    params: &StrokeParams,
    out_w: u32,
    out_h: u32,
    icc: Option<&IccCache>,
    no_aa: bool,
) {
    // Convert stroke outline to fill path. Mirrors update_cmyk_buffer_for_stroke_overprint.
    let resolution_scale = (transform.sx * transform.sx + transform.sy * transform.sy)
        .sqrt()
        .max(1.0);
    let dashed_op;
    let stroke_src = if let Some(ref dash) = stroke.dash {
        dashed_op = skia_path.dash(dash, resolution_scale);
        match dashed_op.as_ref() {
            Some(p) => p,
            None => skia_path,
        }
    } else {
        skia_path
    };
    let Some(stroked_user) = stroke_src.stroke(stroke, resolution_scale) else {
        return;
    };
    let Some(stroked) = stroked_user.transform(transform) else {
        return;
    };

    let mut coverage_mask = match Mask::new(out_w, out_h) {
        Some(m) => m,
        None => return,
    };
    coverage_mask.fill_path(
        &stroked,
        SkiaFillRule::Winding,
        !no_aa,
        Transform::identity(),
    );

    let (bbox_x0, bbox_y0, bbox_x1, bbox_y1) =
        path_device_bbox(&stroked, Transform::identity(), out_w, out_h);

    // Intersect with clip mask (same logic as render_overprint_fill).
    let clip_coverage: Option<&[u8]> = match &band_state.clip_region {
        None => None,
        Some(ClipRegion::Rect(r)) => {
            let data = coverage_mask.data_mut();
            let stride = out_w as usize;
            for y in bbox_y0..bbox_y1 {
                let row_start = y * stride;
                for x in bbox_x0..bbox_x1 {
                    let yu = y as u32;
                    let xu = x as u32;
                    if yu < r.y0 || yu >= r.y1 || xu < r.x0 || xu >= r.x1 {
                        data[row_start + x] = 0;
                    }
                }
            }
            None
        }
        Some(ClipRegion::Mask(clip_mask)) => Some(clip_mask.data()),
    };

    // See render_overprint_fill for the rationale: a custom spot stroke must
    // preserve the process CMYK buffer and blend multiplicatively in RGB so
    // later OPM 1 overprints don't knock out the spot's visible colour.
    let is_custom_spot = params.painted_channels == 0 && !params.is_device_cmyk;

    // Source CMYK preference: for paints with a process colorant in the mix,
    // prefer `process_cmyk` so the no-op-delta skip in the per-pixel loop sees
    // the same exact value the BG paint wrote into `cmyk_buf`. Custom spots
    // keep reading `native_cmyk` (the spot's visual alt-CMYK; process_cmyk is
    // (0,0,0,0) for pure spots). See `render_overprint_fill` for the full
    // rationale (GWG 3.0 swatches c/i, 1307.pdf spot text).
    let (src_c, src_m, src_y, src_k) = if !is_custom_spot && let Some(c) = params.color.process_cmyk
    {
        c
    } else if let Some(c) = params.color.native_cmyk {
        c
    } else {
        let r = params.color.r;
        let g = params.color.g;
        let b = params.color.b;
        (1.0 - r, 1.0 - g, 1.0 - b, 0.0)
    };

    let mut channels = params.painted_channels;
    if channels == 0 {
        channels = stet_graphics::device::CMYK_ALL;
    }
    if params.overprint_mode == 1
        && channels == stet_graphics::device::CMYK_ALL
        && params.is_device_cmyk
    {
        channels = 0;
        if src_c != 0.0 {
            channels |= stet_graphics::device::CMYK_C;
        }
        if src_m != 0.0 {
            channels |= stet_graphics::device::CMYK_M;
        }
        if src_y != 0.0 {
            channels |= stet_graphics::device::CMYK_Y;
        }
        if src_k != 0.0 {
            channels |= stet_graphics::device::CMYK_K;
        }
        // See render_overprint_fill: an all-zero CMYK source preserves the
        // backdrop only when /OPM and /op|/OP were set together (paired) in
        // the same ExtGState. Inherited-OPM cases fall back to legacy
        // knockout.
        if channels == 0 && !params.opm_paired {
            channels = stet_graphics::device::CMYK_ALL;
        }
    }

    let is_k_only_cmyk = params.is_device_cmyk
        && params.overprint_mode == 0
        && src_c == 0.0
        && src_m == 0.0
        && src_y == 0.0;
    if channels == stet_graphics::device::CMYK_ALL && !is_custom_spot && !is_k_only_cmyk {
        // Full-channel replacement: write source CMYK to buffer for covered
        // pixels and let tiny-skia stroke the pixmap with the source colour.
        // Only K-only DeviceCMYK OPM 0 paints are routed to the per-pixel
        // path (see render_overprint_fill).
        let cov_data = coverage_mask.data();
        let stride = out_w as usize;
        for y in bbox_y0..bbox_y1 {
            for x in bbox_x0..bbox_x1 {
                let mi = y * stride + x;
                let mut cov = cov_data[mi] as f32 / 255.0;
                if let Some(clip) = clip_coverage {
                    cov *= clip[mi] as f32 / 255.0;
                }
                if cov > 0.0 {
                    let ci = mi * 4;
                    cmyk_buf[ci] = src_c as f32;
                    cmyk_buf[ci + 1] = src_m as f32;
                    cmyk_buf[ci + 2] = src_y as f32;
                    cmyk_buf[ci + 3] = src_k as f32;
                }
            }
        }
        let mut temp_mask = None;
        let Some(mask_ref) =
            resolve_clip_mask(&band_state.clip_region, &mut temp_mask, out_w, out_h)
        else {
            return;
        };
        let paint = to_paint_alpha(&params.color, params.alpha, params.blend_mode, no_aa);
        pixmap.stroke_path(skia_path, &paint, stroke, transform, mask_ref);
        return;
    }

    let cov_data = coverage_mask.data();
    let stride = out_w as usize;
    let px_data = pixmap.data_mut();
    let px_stride = out_w as usize * 4;

    for y in bbox_y0..bbox_y1 {
        for x in bbox_x0..bbox_x1 {
            let mi = y * stride + x;
            let mut cov = cov_data[mi] as f32 / 255.0;
            if let Some(clip) = clip_coverage {
                cov *= clip[mi] as f32 / 255.0;
            }
            if cov <= 0.0 {
                continue;
            }

            let ci = mi * 4;
            let pi = y * px_stride + x * 4;
            // Snapshot-based AA blending — see render_overprint_fill for the
            // rationale. Capture the pre-paint pixmap on first overprint touch
            // so stacked overprints at the same pixel blend against the
            // original backdrop rather than each other.
            if op_touched[mi] == 0 && px_data[pi + 3] > 0 {
                op_bg[pi] = px_data[pi];
                op_bg[pi + 1] = px_data[pi + 1];
                op_bg[pi + 2] = px_data[pi + 2];
                op_bg[pi + 3] = px_data[pi + 3];
                op_touched[mi] = 1;
            }
            let cur_c = cmyk_buf[ci] as f64;
            let cur_m = cmyk_buf[ci + 1] as f64;
            let cur_y = cmyk_buf[ci + 2] as f64;
            let cur_k = cmyk_buf[ci + 3] as f64;
            let cur_is_clean = cur_c == 0.0 && cur_m == 0.0 && cur_y == 0.0 && cur_k == 0.0;
            let pixmap_has_colour = px_data[pi + 3] > 0
                && (px_data[pi] < 250 || px_data[pi + 1] < 250 || px_data[pi + 2] < 250);
            // Multiplicative ink-stacking only when the pixmap carries a real
            // backdrop: either this paint is a custom spot landing on an
            // already-coloured pixel, or the process-ink buffer is empty but
            // the pixmap shows colour (prior spot/RGB paint). On fresh paper
            // (alpha=0 → premultiplied (0,0,0,0)) multiplicative would darken
            // the fill to pure black, so those pixels fall through to the
            // replace path where the source RGB paints normally.
            let use_multiplicative = (is_custom_spot || cur_is_clean) && pixmap_has_colour;

            // Promoted DeviceGray on non-spot backdrop: replace all channels
            // (see render_overprint_fill).
            let is_promoted_gray = params.painted_channels == stet_graphics::device::CMYK_K
                && channels == stet_graphics::device::CMYK_K
                && params.is_device_cmyk
                && src_c == 0.0
                && src_m == 0.0
                && src_y == 0.0;
            let effective_channels = if is_promoted_gray && spot_mask[mi] == 0 {
                stet_graphics::device::CMYK_ALL
            } else {
                channels
            };

            let new_c = if effective_channels & stet_graphics::device::CMYK_C != 0 {
                src_c
            } else {
                cur_c
            };
            let new_m = if effective_channels & stet_graphics::device::CMYK_M != 0 {
                src_m
            } else {
                cur_m
            };
            let new_y = if effective_channels & stet_graphics::device::CMYK_Y != 0 {
                src_y
            } else {
                cur_y
            };
            let new_k = if effective_channels & stet_graphics::device::CMYK_K != 0 {
                src_k
            } else {
                cur_k
            };

            if !is_custom_spot {
                cmyk_buf[ci] = new_c as f32;
                cmyk_buf[ci + 1] = new_m as f32;
                cmyk_buf[ci + 2] = new_y as f32;
                cmyk_buf[ci + 3] = new_k as f32;
            }

            // No-op overprint skip — see render_overprint_fill for rationale.
            let delta = (new_c - cur_c)
                .abs()
                .max((new_m - cur_m).abs())
                .max((new_y - cur_y).abs())
                .max((new_k - cur_k).abs());
            if delta < 1e-4 && spot_mask[mi] != 0 && pixmap_has_colour && !is_custom_spot {
                continue;
            }

            let (r, g, b) =
                if is_promoted_gray && effective_channels == stet_graphics::device::CMYK_ALL {
                    // Promoted DeviceGray collapsing to a full replace — see
                    // render_overprint_fill for the rationale (must run before
                    // the multiplicative branch so a `1 g` / `1 G` white paint
                    // doesn't get folded into the backdrop via zero-source
                    // multiplication).
                    (params.color.r, params.color.g, params.color.b)
                } else if use_multiplicative {
                    let bg_r = px_data[pi] as f64 / 255.0;
                    let bg_g = px_data[pi + 1] as f64 / 255.0;
                    let bg_b = px_data[pi + 2] as f64 / 255.0;
                    let over_r = if channels & stet_graphics::device::CMYK_C != 0 {
                        1.0 - src_c
                    } else {
                        1.0
                    };
                    let over_g = if channels & stet_graphics::device::CMYK_M != 0 {
                        1.0 - src_m
                    } else {
                        1.0
                    };
                    let over_b = if channels & stet_graphics::device::CMYK_Y != 0 {
                        1.0 - src_y
                    } else {
                        1.0
                    };
                    let k_fac = if channels & stet_graphics::device::CMYK_K != 0 {
                        1.0 - src_k
                    } else {
                        1.0
                    };
                    (
                        (bg_r * over_r * k_fac).clamp(0.0, 1.0),
                        (bg_g * over_g * k_fac).clamp(0.0, 1.0),
                        (bg_b * over_b * k_fac).clamp(0.0, 1.0),
                    )
                } else if let Some(icc_cache) = icc {
                    icc_cache
                        .convert_cmyk_readonly(new_c, new_m, new_y, new_k)
                        .unwrap_or_else(|| cmyk_to_rgb_plrm(new_c, new_m, new_y, new_k))
                } else {
                    cmyk_to_rgb_plrm(new_c, new_m, new_y, new_k)
                };

            let a = (cov * params.alpha as f32).min(1.0);
            // Blend backdrop: prefer snapshot only when this paint's colour
            // closely matches the snapshot — see render_overprint_fill for
            // the rationale (keeps aw-on-red-style cancel paints clean at
            // edges while preserving additive same-colour stacking).
            let (bk_r, bk_g, bk_b, bk_a) = if op_touched[mi] != 0 {
                let new_r = (r as f32 * 255.0).clamp(0.0, 255.0);
                let new_g = (g as f32 * 255.0).clamp(0.0, 255.0);
                let new_b = (b as f32 * 255.0).clamp(0.0, 255.0);
                let dr = (op_bg[pi] as f32 - new_r).abs();
                let dg = (op_bg[pi + 1] as f32 - new_g).abs();
                let db = (op_bg[pi + 2] as f32 - new_b).abs();
                if dr.max(dg).max(db) <= 4.0 {
                    (op_bg[pi], op_bg[pi + 1], op_bg[pi + 2], op_bg[pi + 3])
                } else {
                    (
                        px_data[pi],
                        px_data[pi + 1],
                        px_data[pi + 2],
                        px_data[pi + 3],
                    )
                }
            } else {
                (
                    px_data[pi],
                    px_data[pi + 1],
                    px_data[pi + 2],
                    px_data[pi + 3],
                )
            };
            let dst_a = bk_a as f32 / 255.0;
            let one_minus_a = 1.0 - a;
            let out_a = a + dst_a * one_minus_a;
            if out_a > 0.0 {
                // tiny-skia stores premultiplied RGBA (see render_overprint_fill).
                px_data[pi] = ((r as f32 * a + (bk_r as f32 / 255.0) * one_minus_a) * 255.0)
                    .clamp(0.0, 255.0)
                    .round() as u8;
                px_data[pi + 1] = ((g as f32 * a + (bk_g as f32 / 255.0) * one_minus_a) * 255.0)
                    .clamp(0.0, 255.0)
                    .round() as u8;
                px_data[pi + 2] = ((b as f32 * a + (bk_b as f32 / 255.0) * one_minus_a) * 255.0)
                    .clamp(0.0, 255.0)
                    .round() as u8;
                px_data[pi + 3] = (out_a * 255.0).round() as u8;
            }
        }
    }
}

/// Update the CMYK buffer for a non-overprint stroke. Mirrors
/// [`update_cmyk_buffer_for_fill`] but rasterizes a stroked outline path
/// instead of a filled one. Source-CMYK selection follows the same
/// native_cmyk → ICC reverse → PLRM cascade.
#[allow(clippy::too_many_arguments)]
fn update_cmyk_buffer_for_stroke(
    cmyk_buf: &mut [f32],
    spot_mask: &mut [u8],
    path: &PsPath,
    params: &StrokeParams,
    stroke: &Stroke,
    transform: Transform,
    out_w: u32,
    out_h: u32,
    clip_region: &Option<ClipRegion>,
    no_aa: bool,
    icc: Option<&IccCache>,
) {
    // Custom spot strokes knockout the process CMYK plates — zero the buffer
    // under the stroke so later overprints fall into the multiplicative-blend
    // branch (see update_cmyk_buffer_for_fill, including the
    // `process_cmyk.is_some()` carve-out that keeps DeviceRGB / ICCBased-RGB
    // strokes off this branch so their proofing-chain CMYK reaches the
    // buffer).
    let is_custom_spot = params.painted_channels == 0
        && !params.is_device_cmyk
        && params.color.process_cmyk.is_some();
    // See update_cmyk_buffer_for_fill for rationale.
    let has_spot_contrib = (is_custom_spot && params.color.native_cmyk.is_some())
        || matches!(
            (params.color.native_cmyk, params.color.process_cmyk),
            (Some(nat), Some(proc_))
                if (nat.0 - proc_.0).abs() > 1e-6
                    || (nat.1 - proc_.1).abs() > 1e-6
                    || (nat.2 - proc_.2).abs() > 1e-6
                    || (nat.3 - proc_.3).abs() > 1e-6
        );

    let (src_c, src_m, src_y, src_k) = if is_custom_spot {
        (0.0, 0.0, 0.0, 0.0)
    } else if let Some(c) = params.color.process_cmyk {
        c
    } else if let Some(c) = params.color.native_cmyk {
        c
    } else if let Some(cmyk) = icc.and_then(|i| {
        i.convert_rgb_to_cmyk_readonly(params.color.r, params.color.g, params.color.b)
    }) {
        (cmyk[0], cmyk[1], cmyk[2], cmyk[3])
    } else {
        (
            (1.0 - params.color.r).clamp(0.0, 1.0),
            (1.0 - params.color.g).clamp(0.0, 1.0),
            (1.0 - params.color.b).clamp(0.0, 1.0),
            0.0,
        )
    };

    let Some(skia_path) = build_skia_path(path) else {
        return;
    };

    // Convert the stroke outline into a fill path so we can rasterize it via
    // Mask::fill_path. Mirrors the dance in the overprint stroke branch:
    // dash → stroke-to-outline (in user space) → device transform.
    let resolution_scale = (transform.sx * transform.sx + transform.sy * transform.sy)
        .sqrt()
        .max(1.0);
    let dashed_op;
    let stroke_src = if let Some(ref dash) = stroke.dash {
        dashed_op = skia_path.dash(dash, resolution_scale);
        match dashed_op.as_ref() {
            Some(p) => p,
            None => &skia_path,
        }
    } else {
        &skia_path
    };
    let Some(stroked_user) = stroke_src.stroke(stroke, resolution_scale) else {
        return;
    };
    let Some(stroked) = stroked_user.transform(transform) else {
        return;
    };

    let mut coverage_mask = match Mask::new(out_w, out_h) {
        Some(m) => m,
        None => return,
    };
    coverage_mask.fill_path(
        &stroked,
        SkiaFillRule::Winding,
        !no_aa,
        Transform::identity(),
    );

    let cov_data = coverage_mask.data();
    let clip_data: Option<&[u8]> = match clip_region {
        Some(ClipRegion::Mask(m)) => Some(m.data()),
        _ => None,
    };

    let (mut bx0, mut by0, mut bx1, mut by1) =
        path_device_bbox(&stroked, Transform::identity(), out_w, out_h);
    if let Some(ClipRegion::Rect(r)) = clip_region {
        bx0 = bx0.max(r.x0 as usize);
        by0 = by0.max(r.y0 as usize);
        bx1 = bx1.min(r.x1 as usize);
        by1 = by1.min(r.y1 as usize);
    }

    let stride = out_w as usize;
    for y in by0..by1 {
        for x in bx0..bx1 {
            let mi = y * stride + x;
            let mut cov = cov_data[mi] as f32 / 255.0;
            if let Some(clip) = clip_data {
                cov *= clip[mi] as f32 / 255.0;
            }
            if cov > 0.0 {
                let ci = mi * 4;
                cmyk_buf[ci] = src_c as f32;
                cmyk_buf[ci + 1] = src_m as f32;
                cmyk_buf[ci + 2] = src_y as f32;
                cmyk_buf[ci + 3] = src_k as f32;
                if has_spot_contrib {
                    spot_mask[mi] = 1;
                }
            }
        }
    }
}

/// Render an overprint image with viewport params.
#[allow(clippy::too_many_arguments)]
fn render_overprint_image(
    pixmap: &mut Pixmap,
    cmyk_buf: &mut [f32],
    op_bg: &mut [u8],
    op_touched: &mut [u8],
    band_state: &mut BandState,
    sample_data: &[u8],
    params: &ImageParams,
    vp_x: f32,
    vp_y: f32,
    scale_x: f32,
    scale_y: f32,
    out_w: u32,
    out_h: u32,
    icc: Option<&IccCache>,
) {
    let iw = params.width as usize;
    let ih = params.height as usize;
    let Some(image_inv) = params.image_matrix.invert() else {
        return;
    };
    let combined = params.ctm.concat(&image_inv);
    let Some(inv_combined) = combined.invert() else {
        return;
    };

    let px_data = pixmap.data_mut();
    let stride = out_w as usize;
    let inv_sx = 1.0 / scale_x as f64;
    let inv_sy = 1.0 / scale_y as f64;

    let clip_data: Option<&[u8]> = match &band_state.clip_region {
        Some(ClipRegion::Mask(m)) => Some(m.data()),
        _ => None,
    };
    let clip_rect = match &band_state.clip_region {
        Some(ClipRegion::Rect(r)) => Some(*r),
        _ => None,
    };

    let mask_info = if let ImageColorSpace::Mask {
        color, polarity, ..
    } = &params.color_space
    {
        let (src_c, src_m, src_y, src_k) = color.native_cmyk.unwrap_or_else(|| {
            let r = color.r;
            let g = color.g;
            let b = color.b;
            (1.0 - r, 1.0 - g, 1.0 - b, 0.0)
        });
        Some((src_c, src_m, src_y, src_k, *polarity, iw.div_ceil(8)))
    } else {
        None
    };

    for by in 0..out_h as usize {
        for bx in 0..out_w as usize {
            if let Some(ref r) = clip_rect
                && ((by as u32) < r.y0
                    || (by as u32) >= r.y1
                    || (bx as u32) < r.x0
                    || (bx as u32) >= r.x1)
            {
                continue;
            }
            if let Some(clip) = clip_data {
                let ci_clip = by * stride + bx;
                if clip[ci_clip] == 0 {
                    let bh = out_h as usize;
                    let has_neighbor = (bx > 0 && clip[ci_clip - 1] != 0)
                        || (bx + 1 < stride && clip[ci_clip + 1] != 0)
                        || (by > 0 && clip[ci_clip - stride] != 0)
                        || (by + 1 < bh && clip[ci_clip + stride] != 0)
                        || (bx > 0 && by > 0 && clip[ci_clip - stride - 1] != 0)
                        || (bx + 1 < stride && by > 0 && clip[ci_clip - stride + 1] != 0)
                        || (bx > 0 && by + 1 < bh && clip[ci_clip + stride - 1] != 0)
                        || (bx + 1 < stride && by + 1 < bh && clip[ci_clip + stride + 1] != 0);
                    if !has_neighbor {
                        continue;
                    }
                }
            }

            // Map output pixel to device space, then to image space
            let dx = (bx as f64 + 0.5) * inv_sx + vp_x as f64;
            let dy = (by as f64 + 0.5) * inv_sy + vp_y as f64;
            let ix = inv_combined.a * dx + inv_combined.c * dy + inv_combined.tx;
            let iy = inv_combined.b * dx + inv_combined.d * dy + inv_combined.ty;

            let col = ix.floor() as i64;
            let row = iy.floor() as i64;
            if col < 0 || col >= iw as i64 || row < 0 || row >= ih as i64 {
                continue;
            }
            let col = col as usize;
            let row = row as usize;

            let (src_c, src_m, src_y, src_k) =
                if let Some((mc, mm, my, mk, polarity, bytes_per_row)) = mask_info {
                    let byte_idx = row * bytes_per_row + col / 8;
                    let bit_offset = 7 - (col % 8);
                    let bit = if byte_idx < sample_data.len() {
                        (sample_data[byte_idx] >> bit_offset) & 1
                    } else {
                        0
                    };
                    let paint = if polarity { bit == 1 } else { bit == 0 };
                    if !paint {
                        continue;
                    }
                    (mc, mm, my, mk)
                } else if let Some(cmyk) =
                    sample_pixel_cmyk(sample_data, &params.color_space, iw, row, col)
                {
                    cmyk
                } else {
                    continue;
                };

            let mi = by * stride + bx;
            let ci = mi * 4;
            let pi = mi * 4;

            // Spot-tint images (Separation / DeviceN with CMYK alt and at
            // least one non-process colorant): per PDF spec 11.7.4.5 the
            // image affects only the device colorants identified by its color
            // space.  In composite preview that means:
            //   * Where the CMYK buffer is empty (fresh paper or a custom
            //     spot painted earlier whose alt-CMYK we never tracked),
            //     paint the pixel directly from the image's tint output —
            //     the spot's full alt-CMYK contribution shows up, and a
            //     same-spot underlying paint (e.g. a /GWG-Green X under an
            //     image whose GWG-Green is zero) is knocked out because
            //     ICC(0,0,0,0) is white.
            //   * Where the CMYK buffer carries prior CMYK (a `1 0 1 0.5 k`
            //     ✓ underneath), REPLACE only the NAMED PROCESS plates with
            //     the image's tint output and PRESERVE the rest, then
            //     recompose the pixmap.  A duotone DeviceN [Black, Green]
            //     image's "no ink" pixel knocks the ✓'s K=0.5 down to 0 —
            //     lightening it to (C=1, M=0, Y=1, K=0) — while leaving its
            //     C=1, Y=1 untouched.
            if image_cs_has_spot_tint_transform(&params.color_space) {
                let cur_c = cmyk_buf[ci] as f64;
                let cur_m = cmyk_buf[ci + 1] as f64;
                let cur_y = cmyk_buf[ci + 2] as f64;
                let cur_k = cmyk_buf[ci + 3] as f64;
                let cur_is_zero = cur_c == 0.0 && cur_m == 0.0 && cur_y == 0.0 && cur_k == 0.0;
                let named = params.painted_channels;
                // OPM=1 zero-source preservation: when the image's tint
                // output for a named plate is zero, the underlying value is
                // preserved instead of replaced.  Without this, a duotone
                // DeviceN [Black, GWG-Green] image's "no ink" pixel
                // overwrote the K=0.5 of an underlying CMYK ✓ with 0,
                // rendering the checkmark too light versus Adobe Acrobat.
                let opm1 = params.overprint_mode == 1;
                let (new_c, new_m, new_y, new_k) = if cur_is_zero {
                    (src_c, src_m, src_y, src_k)
                } else {
                    let nc =
                        if named & stet_graphics::device::CMYK_C != 0 && !(opm1 && src_c == 0.0) {
                            src_c
                        } else {
                            cur_c
                        };
                    let nm =
                        if named & stet_graphics::device::CMYK_M != 0 && !(opm1 && src_m == 0.0) {
                            src_m
                        } else {
                            cur_m
                        };
                    let ny =
                        if named & stet_graphics::device::CMYK_Y != 0 && !(opm1 && src_y == 0.0) {
                            src_y
                        } else {
                            cur_y
                        };
                    let nk =
                        if named & stet_graphics::device::CMYK_K != 0 && !(opm1 && src_k == 0.0) {
                            src_k
                        } else {
                            cur_k
                        };
                    (nc, nm, ny, nk)
                };
                cmyk_buf[ci] = new_c as f32;
                cmyk_buf[ci + 1] = new_m as f32;
                cmyk_buf[ci + 2] = new_y as f32;
                cmyk_buf[ci + 3] = new_k as f32;
                // When the alt space is non-CMYK (e.g., DeviceN with Lab alt),
                // src_* came from named-colorant extraction and only describes
                // the named process plates — spot contributions are missing.
                // For fresh-paper pixels (cur_is_zero), reconstruct the visual
                // via the tint transform's alt → RGB output instead so the
                // spot's true colour shows through. Composite cells (cur not
                // zero) still go through CMYK → RGB on the plate-replaced
                // values so process plates from the underlay are honoured.
                let alt_is_non_cmyk = image_cs_alt_is_non_cmyk(&params.color_space);
                let (r, g, b) = if cur_is_zero
                    && alt_is_non_cmyk
                    && let Some(rgb) =
                        sample_pixel_visual_rgb(sample_data, &params.color_space, iw, row, col)
                {
                    rgb
                } else if let Some(icc_cache) = icc {
                    icc_cache
                        .convert_cmyk_readonly(new_c, new_m, new_y, new_k)
                        .unwrap_or_else(|| cmyk_to_rgb_plrm(new_c, new_m, new_y, new_k))
                } else {
                    cmyk_to_rgb_plrm(new_c, new_m, new_y, new_k)
                };
                if op_touched[mi] == 0 && px_data[pi + 3] > 0 {
                    op_bg[pi] = px_data[pi];
                    op_bg[pi + 1] = px_data[pi + 1];
                    op_bg[pi + 2] = px_data[pi + 2];
                    op_bg[pi + 3] = px_data[pi + 3];
                    op_touched[mi] = 1;
                }
                px_data[pi] = (r * 255.0).round() as u8;
                px_data[pi + 1] = (g * 255.0).round() as u8;
                px_data[pi + 2] = (b * 255.0).round() as u8;
                px_data[pi + 3] = 255;
                continue;
            }

            let mut channels = params.painted_channels;
            // Non-CMYK images (painted_channels=0, e.g. Separation/DeviceN spot colors)
            // replace all CMYK channels with the tinted equivalent.
            if channels == 0 {
                channels = stet_graphics::device::CMYK_ALL;
            }
            let is_direct_cmyk = matches!(
                &params.color_space,
                ImageColorSpace::DeviceCMYK
                    | ImageColorSpace::ICCBased { n: 4, .. }
                    | ImageColorSpace::Mask { .. }
            );
            // Custom spot image: process plates stay untouched and the per-pixel
            // sampled CMYK is the spot's alt-CMYK, which we layer multiplicatively
            // onto the pixmap. For image masks, the spot identity lives on the
            // fill color (recognise them via painted_channels=0 paired with a
            // native-CMYK fill color from the alt-space conversion). Indexed
            // images inherit the base space, so an Indexed /DeviceCMYK palette
            // is NOT a custom spot even when painted_channels=0. Plain DeviceCMYK
            // / ICCBased(4) images keep is_custom_spot=false so standard OPM 1
            // behaviour still applies.
            let is_custom_spot = params.painted_channels == 0
                && !is_cmyk_color_space(&params.color_space)
                && match &params.color_space {
                    ImageColorSpace::Mask { color, .. } => color.native_cmyk.is_some(),
                    _ => true,
                };
            if params.overprint_mode == 1
                && channels == stet_graphics::device::CMYK_ALL
                && is_direct_cmyk
            {
                channels = 0;
                if src_c != 0.0 {
                    channels |= stet_graphics::device::CMYK_C;
                }
                if src_m != 0.0 {
                    channels |= stet_graphics::device::CMYK_M;
                }
                if src_y != 0.0 {
                    channels |= stet_graphics::device::CMYK_Y;
                }
                if src_k != 0.0 {
                    channels |= stet_graphics::device::CMYK_K;
                }
            }

            let cur_c = cmyk_buf[ci] as f64;
            let cur_m = cmyk_buf[ci + 1] as f64;
            let cur_y = cmyk_buf[ci + 2] as f64;
            let cur_k = cmyk_buf[ci + 3] as f64;
            let cur_is_clean = cur_c == 0.0 && cur_m == 0.0 && cur_y == 0.0 && cur_k == 0.0;
            let pixmap_has_colour = px_data[pi + 3] > 0
                && (px_data[pi] < 250 || px_data[pi + 1] < 250 || px_data[pi + 2] < 250);
            // Multiplicative ink-stacking only when the pixmap carries a real
            // backdrop: either this paint is a custom spot landing on an
            // already-coloured pixel, or the process-ink buffer is empty but
            // the pixmap shows colour (prior spot/RGB paint). On fresh paper
            // (alpha=0 → premultiplied (0,0,0,0)) multiplicative would darken
            // the fill to pure black, so those pixels fall through to the
            // replace path where the source RGB paints normally.
            let use_multiplicative = (is_custom_spot || cur_is_clean) && pixmap_has_colour;

            let new_c = if channels & stet_graphics::device::CMYK_C != 0 {
                src_c
            } else {
                cur_c
            };
            let new_m = if channels & stet_graphics::device::CMYK_M != 0 {
                src_m
            } else {
                cur_m
            };
            let new_y = if channels & stet_graphics::device::CMYK_Y != 0 {
                src_y
            } else {
                cur_y
            };
            let new_k = if channels & stet_graphics::device::CMYK_K != 0 {
                src_k
            } else {
                cur_k
            };

            if !is_custom_spot {
                cmyk_buf[ci] = new_c as f32;
                cmyk_buf[ci + 1] = new_m as f32;
                cmyk_buf[ci + 2] = new_y as f32;
                cmyk_buf[ci + 3] = new_k as f32;
            }

            let (r, g, b) = if use_multiplicative {
                let bg_r = px_data[pi] as f64 / 255.0;
                let bg_g = px_data[pi + 1] as f64 / 255.0;
                let bg_b = px_data[pi + 2] as f64 / 255.0;
                let over_r = if channels & stet_graphics::device::CMYK_C != 0 {
                    1.0 - src_c
                } else {
                    1.0
                };
                let over_g = if channels & stet_graphics::device::CMYK_M != 0 {
                    1.0 - src_m
                } else {
                    1.0
                };
                let over_b = if channels & stet_graphics::device::CMYK_Y != 0 {
                    1.0 - src_y
                } else {
                    1.0
                };
                let k_fac = if channels & stet_graphics::device::CMYK_K != 0 {
                    1.0 - src_k
                } else {
                    1.0
                };
                (
                    (bg_r * over_r * k_fac).clamp(0.0, 1.0),
                    (bg_g * over_g * k_fac).clamp(0.0, 1.0),
                    (bg_b * over_b * k_fac).clamp(0.0, 1.0),
                )
            } else if let Some(icc_cache) = icc {
                icc_cache
                    .convert_cmyk_readonly(new_c, new_m, new_y, new_k)
                    .unwrap_or_else(|| cmyk_to_rgb_plrm(new_c, new_m, new_y, new_k))
            } else {
                cmyk_to_rgb_plrm(new_c, new_m, new_y, new_k)
            };

            // Snapshot the pre-paint pixmap so a later overprint fill/stroke
            // at this pixel can blend against it (see render_overprint_fill).
            if op_touched[mi] == 0 && px_data[pi + 3] > 0 {
                op_bg[pi] = px_data[pi];
                op_bg[pi + 1] = px_data[pi + 1];
                op_bg[pi + 2] = px_data[pi + 2];
                op_bg[pi + 3] = px_data[pi + 3];
                op_touched[mi] = 1;
            }

            px_data[pi] = (r * 255.0).round() as u8;
            px_data[pi + 1] = (g * 255.0).round() as u8;
            px_data[pi + 2] = (b * 255.0).round() as u8;
            px_data[pi + 3] = 255;
        }
    }
}

/// Update CMYK buffer for a non-overprint image.
///
/// For native-CMYK image color spaces (DeviceCMYK / ICCBased(4) / Separation
/// or DeviceN with CMYK alt), the source CMYK is sampled directly via
/// `sample_pixel_cmyk`. For non-CMYK source spaces (RGB/Gray/Lab/etc.), the
/// already-composited pixmap pixel is read and reverse-converted to CMYK via
/// the system CMYK ICC profile, falling back to the PLRM formula. This keeps
/// the parallel CMYK buffer faithful for any image painter inside a
/// CMYK-tracked context.
#[allow(clippy::too_many_arguments)]
fn update_cmyk_buffer_for_image(
    cmyk_buf: &mut [f32],
    sample_data: &[u8],
    pixmap_rgba: &[u8],
    params: &ImageParams,
    vp_x: f32,
    vp_y: f32,
    scale_x: f32,
    scale_y: f32,
    out_w: u32,
    out_h: u32,
    clip_region: &Option<ClipRegion>,
    icc: Option<&IccCache>,
) {
    let iw = params.width as usize;
    let ih = params.height as usize;
    let Some(image_inv) = params.image_matrix.invert() else {
        return;
    };
    let combined = params.ctm.concat(&image_inv);
    let Some(inv_combined) = combined.invert() else {
        return;
    };
    let stride = out_w as usize;
    let inv_sx = 1.0 / scale_x as f64;
    let inv_sy = 1.0 / scale_y as f64;

    let mask_info = if let ImageColorSpace::Mask {
        color, polarity, ..
    } = &params.color_space
    {
        let Some((c, m, y, k)) = color.native_cmyk else {
            return;
        };
        Some((
            c as f32,
            m as f32,
            y as f32,
            k as f32,
            *polarity,
            iw.div_ceil(8),
        ))
    } else {
        None
    };

    let clip_data: Option<&[u8]> = match clip_region {
        Some(ClipRegion::Mask(m)) => Some(m.data()),
        _ => None,
    };
    let clip_rect = match clip_region {
        Some(ClipRegion::Rect(r)) => Some(*r),
        _ => None,
    };

    for by in 0..out_h as usize {
        for bx in 0..out_w as usize {
            if let Some(ref r) = clip_rect
                && ((by as u32) < r.y0
                    || (by as u32) >= r.y1
                    || (bx as u32) < r.x0
                    || (bx as u32) >= r.x1)
            {
                continue;
            }
            if let Some(clip) = clip_data
                && clip[by * stride + bx] == 0
            {
                continue;
            }

            let dx = (bx as f64 + 0.5) * inv_sx + vp_x as f64;
            let dy = (by as f64 + 0.5) * inv_sy + vp_y as f64;
            let ix = inv_combined.a * dx + inv_combined.c * dy + inv_combined.tx;
            let iy = inv_combined.b * dx + inv_combined.d * dy + inv_combined.ty;

            let col = ix.floor() as i64;
            let row = iy.floor() as i64;
            if col < 0 || col >= iw as i64 || row < 0 || row >= ih as i64 {
                continue;
            }
            let col = col as usize;
            let row = row as usize;

            let ci = (by * stride + bx) * 4;
            if let Some((sc, sm, sy, sk, polarity, bytes_per_row)) = mask_info {
                let byte_idx = row * bytes_per_row + col / 8;
                let bit_offset = 7 - (col % 8);
                let bit = if byte_idx < sample_data.len() {
                    (sample_data[byte_idx] >> bit_offset) & 1
                } else {
                    0
                };
                let paint = if polarity { bit == 1 } else { bit == 0 };
                if paint {
                    cmyk_buf[ci] = sc;
                    cmyk_buf[ci + 1] = sm;
                    cmyk_buf[ci + 2] = sy;
                    cmyk_buf[ci + 3] = sk;
                }
            } else if let Some((sc, sm, sy, sk)) =
                sample_pixel_cmyk(sample_data, &params.color_space, iw, row, col)
            {
                cmyk_buf[ci] = sc as f32;
                cmyk_buf[ci + 1] = sm as f32;
                cmyk_buf[ci + 2] = sy as f32;
                cmyk_buf[ci + 3] = sk as f32;
            } else if ci + 3 < pixmap_rgba.len() && pixmap_rgba[ci + 3] > 0 {
                // Non-CMYK source space: reverse-convert the composited pixmap
                // pixel to CMYK via the system profile. Falls back to PLRM
                // (1 − r, 1 − g, 1 − b, 0) when no ICC reverse is available.
                let r = pixmap_rgba[ci] as f64 / 255.0;
                let g = pixmap_rgba[ci + 1] as f64 / 255.0;
                let b = pixmap_rgba[ci + 2] as f64 / 255.0;
                let cmyk =
                    if let Some(c) = icc.and_then(|i| i.convert_rgb_to_cmyk_readonly(r, g, b)) {
                        c
                    } else {
                        [
                            (1.0 - r).clamp(0.0, 1.0),
                            (1.0 - g).clamp(0.0, 1.0),
                            (1.0 - b).clamp(0.0, 1.0),
                            0.0,
                        ]
                    };
                cmyk_buf[ci] = cmyk[0] as f32;
                cmyk_buf[ci + 1] = cmyk[1] as f32;
                cmyk_buf[ci + 2] = cmyk[2] as f32;
                cmyk_buf[ci + 3] = cmyk[3] as f32;
            }
        }
    }
}
/// Check if an image color space can be rendered through the overprint path.
/// Image masks always work (they use the fill color's native CMYK).
/// Other color spaces must be CMYK-resolvable via `sample_pixel_cmyk`.
fn image_supports_overprint(cs: &ImageColorSpace) -> bool {
    use stet_graphics::device::cmyk_channel_for_name;
    match cs {
        ImageColorSpace::Mask { .. } => true,
        ImageColorSpace::DeviceCMYK | ImageColorSpace::ICCBased { n: 4, .. } => true,
        ImageColorSpace::Separation {
            alt_space, name, ..
        } => {
            matches!(
                alt_space.as_ref(),
                ImageColorSpace::DeviceCMYK | ImageColorSpace::ICCBased { n: 4, .. }
            ) || cmyk_channel_for_name(name) != 0
        }
        ImageColorSpace::DeviceN {
            alt_space, names, ..
        } => {
            matches!(
                alt_space.as_ref(),
                ImageColorSpace::DeviceCMYK | ImageColorSpace::ICCBased { n: 4, .. }
            ) || names.iter().any(|n| cmyk_channel_for_name(n) != 0)
        }
        ImageColorSpace::Indexed { base, .. } => image_supports_overprint(base),
        _ => false,
    }
}

/// Check if an image color space is CMYK-based (DeviceCMYK, ICCBased 4-component, or Indexed over CMYK).
fn is_cmyk_color_space(cs: &ImageColorSpace) -> bool {
    match cs {
        ImageColorSpace::DeviceCMYK => true,
        ImageColorSpace::ICCBased { n: 4, .. } => true,
        ImageColorSpace::Indexed { base, .. } => is_cmyk_color_space(base),
        _ => false,
    }
}

/// True when an image's color space is a Separation/DeviceN with at least
/// one non-process spot colorant. These images represent paint that affects
/// a virtual spot plate; the per-pixel CMYK produced by the tint transform
/// (when alt is CMYK) — or extracted directly from named process colorants
/// (when alt is non-CMYK) — must blend with the tracked CMYK buffer per
/// OPM=1: named process plates are replaced and unnamed plates are preserved.
fn image_cs_has_spot_tint_transform(cs: &ImageColorSpace) -> bool {
    use stet_graphics::device::cmyk_channel_for_name;
    let is_cmyk_alt = |alt: &ImageColorSpace| {
        matches!(
            alt,
            ImageColorSpace::DeviceCMYK | ImageColorSpace::ICCBased { n: 4, .. }
        )
    };
    match cs {
        ImageColorSpace::Separation {
            name, alt_space, ..
        } => cmyk_channel_for_name(name) == 0 && is_cmyk_alt(alt_space.as_ref()),
        ImageColorSpace::DeviceN {
            names, alt_space, ..
        } => {
            let has_spot = names.iter().any(|n| cmyk_channel_for_name(n) == 0);
            let has_process = names.iter().any(|n| cmyk_channel_for_name(n) != 0);
            has_spot && (is_cmyk_alt(alt_space.as_ref()) || has_process)
        }
        ImageColorSpace::Indexed { base, .. } => image_cs_has_spot_tint_transform(base),
        _ => false,
    }
}

/// True when the image's tint transform alt is non-CMYK (Lab/RGB/Gray/etc.).
/// In that case the per-pixel CMYK from `sample_pixel_cmyk` only carries the
/// named process colorants extracted directly — it doesn't capture spot
/// colorant contributions, so visual painting (when the buffer is fresh)
/// must come from `sample_pixel_visual_rgb` instead of CMYK→RGB conversion.
fn image_cs_alt_is_non_cmyk(cs: &ImageColorSpace) -> bool {
    let is_cmyk_alt = |alt: &ImageColorSpace| {
        matches!(
            alt,
            ImageColorSpace::DeviceCMYK | ImageColorSpace::ICCBased { n: 4, .. }
        )
    };
    match cs {
        ImageColorSpace::Separation { alt_space, .. }
        | ImageColorSpace::DeviceN { alt_space, .. } => !is_cmyk_alt(alt_space.as_ref()),
        ImageColorSpace::Indexed { base, .. } => image_cs_alt_is_non_cmyk(base),
        _ => false,
    }
}

/// Sample a pixel's visual RGB (0..1) via the tint-transform → alt-space →
/// RGB chain. Used by the spot-tint overprint path when the image's alt is
/// non-CMYK; for those images the named-colorant CMYK extraction loses the
/// spot contribution, but the tint table still produces the correct visual.
fn sample_pixel_visual_rgb(
    sample_data: &[u8],
    cs: &ImageColorSpace,
    iw: usize,
    row: usize,
    col: usize,
) -> Option<(f64, f64, f64)> {
    let to_f64 = |(r, g, b): (u8, u8, u8)| (r as f64 / 255.0, g as f64 / 255.0, b as f64 / 255.0);
    match cs {
        ImageColorSpace::Separation {
            alt_space,
            tint_table,
            ..
        } => {
            let si = row * iw + col;
            if si >= sample_data.len() {
                return None;
            }
            let tint = sample_data[si] as f32 / 255.0;
            let no = tint_table.num_outputs as usize;
            let mut comps = vec![0.0f32; no];
            tint_table.lookup_1d(tint, &mut comps);
            Some(to_f64(alt_comps_to_rgb(&comps, alt_space)))
        }
        ImageColorSpace::DeviceN {
            alt_space,
            tint_table,
            ..
        } => {
            let ni = tint_table.num_inputs as usize;
            let si = (row * iw + col) * ni;
            if si + ni > sample_data.len() {
                return None;
            }
            let mut inputs = vec![0.0f32; ni];
            for (c, inp) in inputs.iter_mut().enumerate() {
                *inp = sample_data[si + c] as f32 / 255.0;
            }
            let no = tint_table.num_outputs as usize;
            let mut comps = vec![0.0f32; no];
            tint_table.lookup_nd(&inputs, &mut comps);
            Some(to_f64(alt_comps_to_rgb(&comps, alt_space)))
        }
        ImageColorSpace::Indexed {
            base,
            hival,
            lookup,
        } => {
            let pi = row * iw + col;
            if pi >= sample_data.len() {
                return None;
            }
            let idx = (sample_data[pi] as usize).min(*hival as usize);
            let base_ncomp = base.num_components() as usize;
            let li = idx * base_ncomp;
            if li + base_ncomp > lookup.len() {
                return None;
            }
            match base.as_ref() {
                ImageColorSpace::Separation {
                    alt_space,
                    tint_table,
                    ..
                } => {
                    let tint = lookup[li] as f32 / 255.0;
                    let no = tint_table.num_outputs as usize;
                    let mut comps = vec![0.0f32; no];
                    tint_table.lookup_1d(tint, &mut comps);
                    Some(to_f64(alt_comps_to_rgb(&comps, alt_space)))
                }
                ImageColorSpace::DeviceN {
                    alt_space,
                    tint_table,
                    ..
                } => {
                    let ni = tint_table.num_inputs as usize;
                    let mut inputs = vec![0.0f32; ni];
                    for (c, inp) in inputs.iter_mut().enumerate() {
                        if c < base_ncomp {
                            *inp = lookup[li + c] as f32 / 255.0;
                        }
                    }
                    let no = tint_table.num_outputs as usize;
                    let mut comps = vec![0.0f32; no];
                    tint_table.lookup_nd(&inputs, &mut comps);
                    Some(to_f64(alt_comps_to_rgb(&comps, alt_space)))
                }
                _ => None,
            }
        }
        _ => None,
    }
}

/// Extract CMYK values from DeviceN colorant inputs by mapping each named
/// process colorant directly to its CMYK channel. Spot colorants and `/None`
/// don't contribute. Used when the DeviceN's alt is non-CMYK so the tint
/// transform can't produce CMYK; the named-colorant inputs are themselves the
/// per-pixel ink amounts for the named process plates.
fn devicen_named_cmyk(names: &[Vec<u8>], inputs: &[u8]) -> (f64, f64, f64, f64) {
    use stet_graphics::device::{CMYK_C, CMYK_K, CMYK_M, CMYK_Y, cmyk_channel_for_name};
    let mut c = 0.0;
    let mut m = 0.0;
    let mut y = 0.0;
    let mut k = 0.0;
    for (i, name) in names.iter().enumerate() {
        let bit = cmyk_channel_for_name(name);
        if bit == 0 {
            continue;
        }
        let v = inputs.get(i).copied().unwrap_or(0) as f64 / 255.0;
        if bit & CMYK_C != 0 {
            c = v;
        }
        if bit & CMYK_M != 0 {
            m = v;
        }
        if bit & CMYK_Y != 0 {
            y = v;
        }
        if bit & CMYK_K != 0 {
            k = v;
        }
    }
    (c, m, y, k)
}

/// Sample a single pixel's CMYK values from image data, handling DeviceCMYK,
/// ICCBased(4), Separation/DeviceN (CMYK alt via tint table, or non-CMYK alt
/// via named-colorant extraction), and Indexed color spaces. Returns None for
/// non-CMYK images.
fn sample_pixel_cmyk(
    sample_data: &[u8],
    cs: &ImageColorSpace,
    iw: usize,
    row: usize,
    col: usize,
) -> Option<(f64, f64, f64, f64)> {
    use stet_graphics::device::cmyk_channel_for_name;
    let is_cmyk_alt = |alt: &ImageColorSpace| {
        matches!(
            alt,
            ImageColorSpace::DeviceCMYK | ImageColorSpace::ICCBased { n: 4, .. }
        )
    };
    match cs {
        ImageColorSpace::DeviceCMYK | ImageColorSpace::ICCBased { n: 4, .. } => {
            let si = (row * iw + col) * 4;
            if si + 3 < sample_data.len() {
                Some((
                    sample_data[si] as f64 / 255.0,
                    sample_data[si + 1] as f64 / 255.0,
                    sample_data[si + 2] as f64 / 255.0,
                    sample_data[si + 3] as f64 / 255.0,
                ))
            } else {
                None
            }
        }
        ImageColorSpace::Separation {
            alt_space,
            tint_table,
            name,
        } => {
            let si = row * iw + col;
            if si >= sample_data.len() {
                return None;
            }
            let tint = sample_data[si] as f32 / 255.0;
            if is_cmyk_alt(alt_space.as_ref()) {
                let mut alt = [0.0f32; 4];
                tint_table.lookup_1d(tint, &mut alt);
                return Some((alt[0] as f64, alt[1] as f64, alt[2] as f64, alt[3] as f64));
            }
            // Non-CMYK alt: only a named process colorant is recoverable.
            let bit = cmyk_channel_for_name(name);
            if bit == 0 {
                return None;
            }
            let names = vec![name.clone()];
            let inputs = [(tint * 255.0).round() as u8];
            Some(devicen_named_cmyk(&names, &inputs))
        }
        ImageColorSpace::DeviceN {
            alt_space,
            tint_table,
            names,
        } => {
            let ni = tint_table.num_inputs as usize;
            let si = (row * iw + col) * ni;
            if si + ni > sample_data.len() {
                return None;
            }
            if is_cmyk_alt(alt_space.as_ref()) {
                let mut inputs = vec![0.0f32; ni];
                for (c, inp) in inputs.iter_mut().enumerate() {
                    *inp = sample_data[si + c] as f32 / 255.0;
                }
                let mut alt = [0.0f32; 4];
                tint_table.lookup_nd(&inputs, &mut alt);
                return Some((alt[0] as f64, alt[1] as f64, alt[2] as f64, alt[3] as f64));
            }
            // Non-CMYK alt: extract from named process colorants directly.
            if !names.iter().any(|n| cmyk_channel_for_name(n) != 0) {
                return None;
            }
            Some(devicen_named_cmyk(names, &sample_data[si..si + ni]))
        }
        ImageColorSpace::Indexed {
            base,
            hival,
            lookup,
        } => {
            let pi = row * iw + col;
            if pi >= sample_data.len() {
                return None;
            }
            let idx = sample_data[pi] as usize;
            let idx = idx.min(*hival as usize);
            let base_ncomp = base.num_components() as usize;
            let li = idx * base_ncomp;
            // For direct CMYK base (4 components): read CMYK from lookup table
            if is_cmyk_color_space(base) && base_ncomp == 4 && li + 3 < lookup.len() {
                return Some((
                    lookup[li] as f64 / 255.0,
                    lookup[li + 1] as f64 / 255.0,
                    lookup[li + 2] as f64 / 255.0,
                    lookup[li + 3] as f64 / 255.0,
                ));
            }
            // For Separation/DeviceN base: extract base components from lookup, then tint
            if li + base_ncomp <= lookup.len() {
                match base.as_ref() {
                    ImageColorSpace::Separation {
                        alt_space,
                        tint_table,
                        name,
                    } => {
                        let tint = lookup[li] as f32 / 255.0;
                        if is_cmyk_alt(alt_space.as_ref()) {
                            let mut alt = [0.0f32; 4];
                            tint_table.lookup_1d(tint, &mut alt);
                            return Some((
                                alt[0] as f64,
                                alt[1] as f64,
                                alt[2] as f64,
                                alt[3] as f64,
                            ));
                        }
                        // Non-CMYK alt: only named process colorants extractable.
                        let bit = cmyk_channel_for_name(name);
                        if bit == 0 {
                            return None;
                        }
                        let names = vec![name.clone()];
                        let inputs = [(tint * 255.0).round() as u8];
                        return Some(devicen_named_cmyk(&names, &inputs));
                    }
                    ImageColorSpace::DeviceN {
                        alt_space,
                        tint_table,
                        names,
                    } => {
                        let ni = tint_table.num_inputs as usize;
                        if is_cmyk_alt(alt_space.as_ref()) {
                            let mut inputs = vec![0.0f32; ni];
                            for (c, inp) in inputs.iter_mut().enumerate() {
                                if c < base_ncomp {
                                    *inp = lookup[li + c] as f32 / 255.0;
                                }
                            }
                            let mut alt = [0.0f32; 4];
                            tint_table.lookup_nd(&inputs, &mut alt);
                            return Some((
                                alt[0] as f64,
                                alt[1] as f64,
                                alt[2] as f64,
                                alt[3] as f64,
                            ));
                        }
                        // Non-CMYK alt: extract from named process colorants directly.
                        if !names.iter().any(|n| cmyk_channel_for_name(n) != 0) {
                            return None;
                        }
                        let take = ni.min(base_ncomp);
                        return Some(devicen_named_cmyk(names, &lookup[li..li + take]));
                    }
                    _ => {}
                }
            }
            None
        }
        _ => None,
    }
}
/// Banded rendering as a free function — runs on a background thread.
///
/// Renders the display list in horizontal bands and streams the output
/// to a `PageSink`. This function is self-contained: it creates its own
/// band pixmaps, clip state, and streams rows to the sink.
#[allow(clippy::too_many_arguments)]
fn render_banded_to_sink(
    page_w: u32,
    page_h: u32,
    band_h: u32,
    dpi: f64,
    list: &DisplayList,
    sink: &mut dyn stet_graphics::device::PageSink,
    icc_cache: &IccCache,
    no_aa: bool,
    layer_set: &LayerSet,
) -> Result<(), String> {
    // Precompute Y bounding boxes for culling
    let bboxes = precompute_bboxes(list, dpi);

    // Build clip epochs — groups of elements between InitClip boundaries.
    // Epochs whose paint elements don't overlap a band can be skipped entirely,
    // avoiding both the per-element iteration AND clip mask rasterization.
    let epochs = build_clip_epochs(list, &bboxes);

    // Pre-populate clip_mask_seen so repeated clip paths get cached from first band
    let clip_seen = precompute_clip_seen(list);

    // Allocate a CMYK buffer at the page level when CMYK math is needed:
    // overprint simulation, an explicit DeviceCMYK page-level transparency
    // group (PDF spec §11.6.7), or any descendant group that declares its own
    // DeviceCMYK transparency CS.
    use stet_graphics::display_list::GroupColorSpace;
    let needs_cmyk_buffer = has_overprint_elements(list)
        || list.page_group_color_space() == GroupColorSpace::DeviceCMYK
        || has_cmyk_group(list);

    // Pre-convert and prescale images once (instead of per-band)
    let preprocessed_images = preprocess_images_for_bands(list, Some(icc_cache));

    // Extra rows rendered above and below each band to provide anti-aliasing
    // context at band seams. Without this, tiny-skia clips geometry at the
    // pixmap edge, producing visible discontinuities in thin diagonal strokes.
    const BAND_OVERLAP: u32 = 6;

    let render_h = band_h + 2 * BAND_OVERLAP;

    // Initialize the sink for this page
    sink.begin_page(page_w, page_h)?;

    let num_bands = page_h.div_ceil(band_h);
    let elements = list.elements();
    let row_bytes = page_w as usize * 4;
    let icc_ref = Some(icc_cache);

    // Closure that renders a single band and returns its RGBA pixels.
    let render_band = |band_idx: u32| -> Vec<u8> {
        let y_start = band_idx * band_h;
        let actual_h = (page_h - y_start).min(band_h);

        let render_y_start = y_start.saturating_sub(BAND_OVERLAP);
        let render_y_end_f = ((y_start + actual_h + BAND_OVERLAP).min(page_h)) as f64;
        let band_offset = y_start - render_y_start;

        let mut band_pixmap = Pixmap::new(page_w, render_h).expect("Failed to create band pixmap");
        // Start transparent — white background composited after content rendering
        band_pixmap.as_mut().data_mut().fill(0x00);

        let cmyk_buf = if needs_cmyk_buffer {
            // CMYK buffer for the render region (including overlap)
            Some(vec![0.0f32; page_w as usize * render_h as usize * 4])
        } else {
            None
        };

        let mut band_state = BandState {
            clip_region: None,
            spare_mask: None,
            clip_mask_cache: HashMap::new(),
            clip_mask_seen: clip_seen.clone(),
            mask_pool: Vec::new(),
            cmyk_buffer: cmyk_buf,
            op_bg_snapshot: None,
            op_touched: None,
            spot_mask: None,
        };

        // Epoch-based replay
        for epoch in &epochs {
            if !epoch.has_erase_page {
                match epoch.paint_bbox {
                    Some(ref pb)
                        if pb.y_max <= render_y_start as f64 || pb.y_min >= render_y_end_f =>
                    {
                        continue;
                    }
                    None => continue,
                    _ => {}
                }
            }

            for i in epoch.start_idx..epoch.end_idx {
                // OcgGroups containing Clip/InitClip must always be
                // processed so their clip-state changes apply for every
                // band — per-element Y culling would strand clip mutations
                // inside a group whose paint content doesn't touch the
                // current band.
                let force_process = matches!(
                    &elements[i],
                    DisplayElement::OcgGroup { elements: inner, .. }
                        if contains_clip_op(inner)
                );
                if !force_process
                    && let Some(ref bbox) = bboxes[i]
                    && (bbox.y_max <= render_y_start as f64 || bbox.y_min >= render_y_end_f)
                {
                    continue;
                }
                let ctx = RenderContext {
                    vp_x: 0.0,
                    vp_y: render_y_start as f32,
                    scale_x: 1.0,
                    scale_y: 1.0,
                    out_w: page_w,
                    out_h: render_h,
                    effective_dpi: dpi,
                    icc: icc_ref,
                    image_cache: None,
                    preprocessed: Some(&preprocessed_images),
                    elem_idx: i,
                    no_aa,
                    opm_zero_transparent: false,
                    knockout_painter_pass: KnockoutPainterPass::None,
                    parent_group_isolated: false,
                    alpha_extraction_pass: false,
                    layer_set,
                };
                render_element(&mut band_pixmap, &mut band_state, &elements[i], &ctx);
            }
        }

        // Composite content onto white background (premultiplied alpha)
        composite_onto_white(band_pixmap.data_mut());

        // Extract only the actual band rows (skip overlap)
        let start_byte = band_offset as usize * row_bytes;
        let total_bytes = actual_h as usize * row_bytes;
        band_pixmap.data()[start_byte..start_byte + total_bytes].to_vec()
    };

    // Render bands in parallel (when available), write to sink in order.
    #[cfg(feature = "parallel")]
    {
        // Process in chunks of `chunk_size` bands to limit peak memory
        // (each rendered band is ~band_h * page_w * 4 bytes).
        // Cap at 8 threads — sequential sink writing bottleneck means
        // additional cores yield no speedup (benchmarked: 8→7.8s plateau).
        let chunk_size = rayon::current_num_threads().max(1);

        for chunk_start in (0..num_bands).step_by(chunk_size) {
            let chunk_end = (chunk_start + chunk_size as u32).min(num_bands);

            let rendered: Vec<Vec<u8>> = (chunk_start..chunk_end)
                .into_par_iter()
                .map(&render_band)
                .collect();

            for (i, band_data) in rendered.iter().enumerate() {
                let band_idx = chunk_start + i as u32;
                let y_start = band_idx * band_h;
                let actual_h = (page_h - y_start).min(band_h);
                sink.write_rows(band_data, actual_h)?;
            }
        }
    }
    #[cfg(not(feature = "parallel"))]
    {
        // Sequential single-threaded rendering
        for band_idx in 0..num_bands {
            let band_data = render_band(band_idx);
            let y_start = band_idx * band_h;
            let actual_h = (page_h - y_start).min(band_h);
            sink.write_rows(&band_data, actual_h)?;
        }
    }

    sink.end_page()
}

/// 2D bounding box in device pixels.
#[derive(Clone, Copy)]
struct BBox2D {
    x_min: f64,
    y_min: f64,
    x_max: f64,
    y_max: f64,
}

/// Compute full 2D bounding boxes for display list elements (for viewport culling).
fn precompute_full_bboxes(list: &DisplayList, dpi: f64) -> Vec<Option<BBox2D>> {
    list.elements()
        .iter()
        .map(|elem| match elem {
            DisplayElement::Fill { path, params } => fill_device_full_bbox(path, &params.ctm),
            DisplayElement::Stroke { path, params } => {
                path_full_bbox(path).map(|mut bbox| {
                    // Use effective line width: actual width or hairline minimum
                    let effective_lw = params.line_width.max(hairline_min_width(&params.ctm, dpi));
                    let expand = effective_lw * params.miter_limit * 0.5;
                    let m = &params.ctm;
                    let is_identity = m.a == 1.0
                        && m.b == 0.0
                        && m.c == 0.0
                        && m.d == 1.0
                        && m.tx == 0.0
                        && m.ty == 0.0;
                    if is_identity {
                        bbox.x_min -= expand;
                        bbox.x_max += expand;
                        bbox.y_min -= expand;
                        bbox.y_max += expand;
                    } else {
                        // Path is in user space — expand for stroke, then
                        // transform bbox corners through CTM to device space.
                        let col_x_len = (m.a * m.a + m.b * m.b).sqrt().max(1.0);
                        let col_y_len = (m.c * m.c + m.d * m.d).sqrt().max(1.0);
                        let expand_x = effective_lw * col_x_len * params.miter_limit * 0.5;
                        let expand_y = effective_lw * col_y_len * params.miter_limit * 0.5;
                        bbox.x_min -= expand_x;
                        bbox.x_max += expand_x;
                        bbox.y_min -= expand_y;
                        bbox.y_max += expand_y;
                        // Transform all 4 corners to device space
                        let corners = [
                            (
                                m.a * bbox.x_min + m.c * bbox.y_min + m.tx,
                                m.b * bbox.x_min + m.d * bbox.y_min + m.ty,
                            ),
                            (
                                m.a * bbox.x_max + m.c * bbox.y_min + m.tx,
                                m.b * bbox.x_max + m.d * bbox.y_min + m.ty,
                            ),
                            (
                                m.a * bbox.x_min + m.c * bbox.y_max + m.tx,
                                m.b * bbox.x_min + m.d * bbox.y_max + m.ty,
                            ),
                            (
                                m.a * bbox.x_max + m.c * bbox.y_max + m.tx,
                                m.b * bbox.x_max + m.d * bbox.y_max + m.ty,
                            ),
                        ];
                        bbox.x_min = corners.iter().map(|c| c.0).fold(f64::INFINITY, f64::min);
                        bbox.x_max = corners
                            .iter()
                            .map(|c| c.0)
                            .fold(f64::NEG_INFINITY, f64::max);
                        bbox.y_min = corners.iter().map(|c| c.1).fold(f64::INFINITY, f64::min);
                        bbox.y_max = corners
                            .iter()
                            .map(|c| c.1)
                            .fold(f64::NEG_INFINITY, f64::max);
                    }
                    bbox
                })
            }
            DisplayElement::Image { params, .. } => image_full_bbox(params),
            DisplayElement::AxialShading { params } => shading_full_bbox(&params.bbox, &params.ctm),
            DisplayElement::RadialShading { params } => {
                shading_full_bbox(&params.bbox, &params.ctm)
            }
            DisplayElement::MeshShading { params } => shading_full_bbox(&params.bbox, &params.ctm),
            DisplayElement::PatchShading { params } => shading_full_bbox(&params.bbox, &params.ctm),
            DisplayElement::PatternFill { params } => pattern_fill_full_bbox(params),
            DisplayElement::Group { params, .. } => Some(BBox2D {
                x_min: params.bbox[0],
                y_min: params.bbox[1],
                x_max: params.bbox[2],
                y_max: params.bbox[3],
            }),
            DisplayElement::SoftMasked { params, .. } => Some(BBox2D {
                x_min: params.bbox[0],
                y_min: params.bbox[1],
                x_max: params.bbox[2],
                y_max: params.bbox[3],
            }),
            DisplayElement::OcgGroup {
                elements,
                visibility,
            } => {
                // Hidden groups without clip ops contribute nothing. Hidden
                // + has clip ops is force-processed at the render-loop layer
                // (see the viewport render_region_prepared loop) so we still
                // return the paint bounds here for correct epoch bbox.
                if !visibility.default_visible() && !contains_clip_op(elements) {
                    return None;
                }
                let child_bboxes = precompute_full_bboxes(elements, dpi);
                let mut x_min = f64::INFINITY;
                let mut y_min = f64::INFINITY;
                let mut x_max = f64::NEG_INFINITY;
                let mut y_max = f64::NEG_INFINITY;
                for cb in child_bboxes.into_iter().flatten() {
                    x_min = x_min.min(cb.x_min);
                    y_min = y_min.min(cb.y_min);
                    x_max = x_max.max(cb.x_max);
                    y_max = y_max.max(cb.y_max);
                }
                if x_min <= x_max && y_min <= y_max {
                    Some(BBox2D {
                        x_min,
                        y_min,
                        x_max,
                        y_max,
                    })
                } else {
                    None
                }
            }
            _ => None, // Clip, InitClip, ErasePage: always process
        })
        .collect()
}

/// Compute the device-space bounding box of a Clip element's path.
///
/// Clip paths emitted by the PDF reader use `ctm = identity`, so the path
/// segments are already in device space. For Clips that come from other
/// sources (PostScript, the pattern transform path), the `ctm` field may
/// be non-identity and the path is in user space — transform the path's
/// bbox corners through the CTM in that case. Stroke-clips are expanded
/// by half the line width.
fn clip_path_bbox(path: &PsPath, params: &ClipParams) -> Option<BBox2D> {
    let mut bbox = path_full_bbox(path)?;
    let ctm = &params.ctm;
    let is_identity = ctm.a == 1.0
        && ctm.b == 0.0
        && ctm.c == 0.0
        && ctm.d == 1.0
        && ctm.tx == 0.0
        && ctm.ty == 0.0;
    if !is_identity {
        let corners = [
            ctm.transform_point(bbox.x_min, bbox.y_min),
            ctm.transform_point(bbox.x_max, bbox.y_min),
            ctm.transform_point(bbox.x_min, bbox.y_max),
            ctm.transform_point(bbox.x_max, bbox.y_max),
        ];
        bbox.x_min = corners.iter().map(|c| c.0).fold(f64::INFINITY, f64::min);
        bbox.x_max = corners
            .iter()
            .map(|c| c.0)
            .fold(f64::NEG_INFINITY, f64::max);
        bbox.y_min = corners.iter().map(|c| c.1).fold(f64::INFINITY, f64::min);
        bbox.y_max = corners
            .iter()
            .map(|c| c.1)
            .fold(f64::NEG_INFINITY, f64::max);
    }
    if let Some(sp) = &params.stroke_params {
        let scale = (ctm.a * ctm.a + ctm.b * ctm.b)
            .sqrt()
            .max((ctm.c * ctm.c + ctm.d * ctm.d).sqrt())
            .max(1.0);
        let expand = sp.line_width * 0.5 * scale;
        bbox.x_min -= expand;
        bbox.x_max += expand;
        bbox.y_min -= expand;
        bbox.y_max += expand;
    }
    Some(bbox)
}

/// Intersect two bboxes; returns `None` if they don't overlap.
fn intersect_bbox(a: &BBox2D, b: &BBox2D) -> Option<BBox2D> {
    let x_min = a.x_min.max(b.x_min);
    let y_min = a.y_min.max(b.y_min);
    let x_max = a.x_max.min(b.x_max);
    let y_max = a.y_max.min(b.y_max);
    if x_min < x_max && y_min < y_max {
        Some(BBox2D {
            x_min,
            y_min,
            x_max,
            y_max,
        })
    } else {
        None
    }
}

/// Compute the union of all paint elements' device-space bounds in
/// `list`, with awareness of the active clip stack.
///
/// Used by the soft-mask rasterization path: a SoftMasked element's
/// `params.bbox` is derived from the form's `/BBox` transformed by the
/// gs-time CTM, but the form's internal `cm` operators may translate
/// individual paint elements outside that bbox. The mask raster needs to
/// be sized against the actual paint bounds, not the form bbox.
///
/// **Why clip-awareness matters**: a mask form may contain a shading
/// without an explicit `/BBox`, in which case `precompute_full_bboxes`
/// returns a sentinel "infinite" bbox (`shading_full_bbox` falls back to
/// `0..1e9`) so band rendering doesn't cull it. If `compute_paint_bounds`
/// just unioned that, the result would exceed the mask raster size cap
/// and `rasterize_mask` would return `None`, making the entire SoftMasked
/// element invisible. Tracking the active clip stack lets us bound those
/// shadings to their effective paint area.
///
/// Returns `None` when the list contains no paintable elements or when
/// no element survives clip culling.
fn compute_paint_bounds(list: &DisplayList, _dpi: f64) -> Option<BBox2D> {
    // Active clip stack: each entry is the intersection so far. The
    // current clip is `clip_stack.last()`; an empty stack means
    // "unbounded" (no clip established yet, or just after InitClip).
    let mut clip_stack: Vec<BBox2D> = Vec::new();
    let mut union: Option<BBox2D> = None;

    let push_paint = |union: &mut Option<BBox2D>, clip_stack: &[BBox2D], bbox: BBox2D| {
        // Intersect against the active clip if any. If the clip is
        // tighter than the bbox, the visible region is the intersection;
        // if the bbox is fully clipped away, skip it.
        let visible = match clip_stack.last() {
            Some(clip) => match intersect_bbox(clip, &bbox) {
                Some(b) => b,
                None => return,
            },
            None => bbox,
        };
        *union = Some(match union.take() {
            None => visible,
            Some(u) => BBox2D {
                x_min: u.x_min.min(visible.x_min),
                y_min: u.y_min.min(visible.y_min),
                x_max: u.x_max.max(visible.x_max),
                y_max: u.y_max.max(visible.y_max),
            },
        });
    };

    for elem in list.elements() {
        match elem {
            DisplayElement::Clip { path, params } => {
                if let Some(cb) = clip_path_bbox(path, params) {
                    let new_top = match clip_stack.last() {
                        Some(prev) => match intersect_bbox(prev, &cb) {
                            Some(b) => b,
                            // Clip cleared the visible region; push an
                            // empty bbox so subsequent paints are
                            // clipped away.
                            None => BBox2D {
                                x_min: 0.0,
                                y_min: 0.0,
                                x_max: 0.0,
                                y_max: 0.0,
                            },
                        },
                        None => cb,
                    };
                    clip_stack.push(new_top);
                }
            }
            DisplayElement::InitClip | DisplayElement::ErasePage => {
                clip_stack.clear();
            }
            DisplayElement::Fill { path, .. } => {
                if let Some(b) = path_full_bbox(path) {
                    push_paint(&mut union, &clip_stack, b);
                }
            }
            DisplayElement::Stroke { path, params } => {
                if let Some(mut b) = path_full_bbox(path) {
                    let expand = params.line_width * params.miter_limit * 0.5;
                    b.x_min -= expand;
                    b.x_max += expand;
                    b.y_min -= expand;
                    b.y_max += expand;
                    push_paint(&mut union, &clip_stack, b);
                }
            }
            DisplayElement::Image { params, .. } => {
                if let Some(b) = image_full_bbox(params) {
                    push_paint(&mut union, &clip_stack, b);
                }
            }
            DisplayElement::AxialShading { params } => {
                let b = match &params.bbox {
                    Some(_) => shading_full_bbox(&params.bbox, &params.ctm),
                    None => clip_stack.last().copied(),
                };
                if let Some(b) = b {
                    push_paint(&mut union, &clip_stack, b);
                }
            }
            DisplayElement::RadialShading { params } => {
                let b = match &params.bbox {
                    Some(_) => shading_full_bbox(&params.bbox, &params.ctm),
                    None => clip_stack.last().copied(),
                };
                if let Some(b) = b {
                    push_paint(&mut union, &clip_stack, b);
                }
            }
            DisplayElement::MeshShading { params } => {
                let b = match &params.bbox {
                    Some(_) => shading_full_bbox(&params.bbox, &params.ctm),
                    None => clip_stack.last().copied(),
                };
                if let Some(b) = b {
                    push_paint(&mut union, &clip_stack, b);
                }
            }
            DisplayElement::PatchShading { params } => {
                let b = match &params.bbox {
                    Some(_) => shading_full_bbox(&params.bbox, &params.ctm),
                    None => clip_stack.last().copied(),
                };
                if let Some(b) = b {
                    push_paint(&mut union, &clip_stack, b);
                }
            }
            DisplayElement::PatternFill { params } => {
                if let Some(b) = pattern_fill_full_bbox(params) {
                    push_paint(&mut union, &clip_stack, b);
                }
            }
            DisplayElement::Group { params, .. } => {
                push_paint(
                    &mut union,
                    &clip_stack,
                    BBox2D {
                        x_min: params.bbox[0],
                        y_min: params.bbox[1],
                        x_max: params.bbox[2],
                        y_max: params.bbox[3],
                    },
                );
            }
            DisplayElement::SoftMasked { params, .. } => {
                push_paint(
                    &mut union,
                    &clip_stack,
                    BBox2D {
                        x_min: params.bbox[0],
                        y_min: params.bbox[1],
                        x_max: params.bbox[2],
                        y_max: params.bbox[3],
                    },
                );
            }
            DisplayElement::Text { .. } => {} // PDF-only, ignored by rasterizer
            DisplayElement::OcgGroup { .. } => {
                // OCG groups have no inherent bbox; their children's bounds
                // are unknown without recursion. Conservative: skip here —
                // if the mask form contains OCG layers, the parent bbox cap
                // provides a sufficient upper bound.
            }
            _ => {}
        }
    }
    union
}

/// Compute full 2D bounds from path segments.
/// Compute device-space 2D bounds for a Fill element, accounting for CTM.
/// Paths may be stored in device space (identity CTM) or user space
/// (non-identity CTM, e.g. synthesized annotation appearances).
fn fill_device_full_bbox(path: &PsPath, ctm: &Matrix) -> Option<BBox2D> {
    let bbox = path_full_bbox(path)?;
    let is_identity = ctm.a == 1.0
        && ctm.b == 0.0
        && ctm.c == 0.0
        && ctm.d == 1.0
        && ctm.tx == 0.0
        && ctm.ty == 0.0;
    if is_identity {
        return Some(bbox);
    }
    let corners = [
        (bbox.x_min, bbox.y_min),
        (bbox.x_max, bbox.y_min),
        (bbox.x_min, bbox.y_max),
        (bbox.x_max, bbox.y_max),
    ];
    let mut x_min = f64::INFINITY;
    let mut x_max = f64::NEG_INFINITY;
    let mut y_min = f64::INFINITY;
    let mut y_max = f64::NEG_INFINITY;
    for (x, y) in &corners {
        let dx = ctm.a * x + ctm.c * y + ctm.tx;
        let dy = ctm.b * x + ctm.d * y + ctm.ty;
        x_min = x_min.min(dx);
        x_max = x_max.max(dx);
        y_min = y_min.min(dy);
        y_max = y_max.max(dy);
    }
    Some(BBox2D {
        x_min,
        y_min,
        x_max,
        y_max,
    })
}

fn path_full_bbox(path: &PsPath) -> Option<BBox2D> {
    let mut x_min = f64::INFINITY;
    let mut x_max = f64::NEG_INFINITY;
    let mut y_min = f64::INFINITY;
    let mut y_max = f64::NEG_INFINITY;
    for seg in &path.segments {
        match seg {
            PathSegment::MoveTo(x, y) | PathSegment::LineTo(x, y) => {
                x_min = x_min.min(*x);
                x_max = x_max.max(*x);
                y_min = y_min.min(*y);
                y_max = y_max.max(*y);
            }
            PathSegment::CurveTo {
                x1,
                y1,
                x2,
                y2,
                x3,
                y3,
            } => {
                x_min = x_min.min(*x1).min(*x2).min(*x3);
                x_max = x_max.max(*x1).max(*x2).max(*x3);
                y_min = y_min.min(*y1).min(*y2).min(*y3);
                y_max = y_max.max(*y1).max(*y2).max(*y3);
            }
            PathSegment::ClosePath => {}
        }
    }
    if x_min <= x_max {
        Some(BBox2D {
            x_min,
            y_min,
            x_max,
            y_max,
        })
    } else {
        None
    }
}

/// Compute full 2D bounds for a PatternFill element.
/// For stroke patterns, the path is in user space and must be transformed
/// through the CTM to get device-space bounds, then expanded by half
/// the stroke width.
fn pattern_fill_full_bbox(params: &stet_graphics::device::PatternFillParams) -> Option<BBox2D> {
    if let Some(ref sp) = params.stroke_params {
        let bbox = path_full_bbox(&params.path)?;
        let ctm = &sp.ctm;
        let corners = [
            ctm.transform_point(bbox.x_min, bbox.y_min),
            ctm.transform_point(bbox.x_max, bbox.y_min),
            ctm.transform_point(bbox.x_min, bbox.y_max),
            ctm.transform_point(bbox.x_max, bbox.y_max),
        ];
        let mut dev_bbox = BBox2D {
            x_min: f64::INFINITY,
            y_min: f64::INFINITY,
            x_max: f64::NEG_INFINITY,
            y_max: f64::NEG_INFINITY,
        };
        for (x, y) in &corners {
            dev_bbox.x_min = dev_bbox.x_min.min(*x);
            dev_bbox.y_min = dev_bbox.y_min.min(*y);
            dev_bbox.x_max = dev_bbox.x_max.max(*x);
            dev_bbox.y_max = dev_bbox.y_max.max(*y);
        }
        let half_w = sp.line_width
            * 0.5
            * (ctm.a * ctm.a + ctm.b * ctm.b)
                .sqrt()
                .max((ctm.c * ctm.c + ctm.d * ctm.d).sqrt());
        dev_bbox.x_min -= half_w;
        dev_bbox.y_min -= half_w;
        dev_bbox.x_max += half_w;
        dev_bbox.y_max += half_w;
        Some(dev_bbox)
    } else {
        path_full_bbox(&params.path)
    }
}

/// Compute Y-axis bounds for a PatternFill element (banded rendering).
fn pattern_fill_y_bbox(params: &stet_graphics::device::PatternFillParams) -> Option<YBBox> {
    let bbox = pattern_fill_full_bbox(params)?;
    Some(YBBox {
        y_min: bbox.y_min,
        y_max: bbox.y_max,
    })
}

/// Compute full 2D bounds for an image from its transform.
fn image_full_bbox(params: &ImageParams) -> Option<BBox2D> {
    let m = &params.ctm;
    let im = &params.image_matrix;
    let im_inv = im.invert()?;
    let combined = m.concat(&im_inv);
    // Image occupies [0, width] × [0, height] in image space
    let w = params.width as f64;
    let h = params.height as f64;
    let corners = [
        combined.transform_point(0.0, 0.0),
        combined.transform_point(w, 0.0),
        combined.transform_point(0.0, h),
        combined.transform_point(w, h),
    ];
    let mut x_min = f64::INFINITY;
    let mut x_max = f64::NEG_INFINITY;
    let mut y_min = f64::INFINITY;
    let mut y_max = f64::NEG_INFINITY;
    for (x, y) in &corners {
        x_min = x_min.min(*x);
        x_max = x_max.max(*x);
        y_min = y_min.min(*y);
        y_max = y_max.max(*y);
    }
    Some(BBox2D {
        x_min,
        y_min,
        x_max,
        y_max,
    })
}

/// Compute full 2D bounds for a shading element from its BBox.
fn shading_full_bbox(bbox: &Option<[f64; 4]>, ctm: &Matrix) -> Option<BBox2D> {
    if let Some(bbox) = bbox {
        let corners = [
            ctm.transform_point(bbox[0], bbox[1]),
            ctm.transform_point(bbox[2], bbox[1]),
            ctm.transform_point(bbox[0], bbox[3]),
            ctm.transform_point(bbox[2], bbox[3]),
        ];
        let mut x_min = f64::INFINITY;
        let mut x_max = f64::NEG_INFINITY;
        let mut y_min = f64::INFINITY;
        let mut y_max = f64::NEG_INFINITY;
        for (x, y) in &corners {
            x_min = x_min.min(*x);
            x_max = x_max.max(*x);
            y_min = y_min.min(*y);
            y_max = y_max.max(*y);
        }
        Some(BBox2D {
            x_min,
            y_min,
            x_max,
            y_max,
        })
    } else {
        Some(BBox2D {
            x_min: 0.0,
            y_min: 0.0,
            x_max: 1e9,
            y_max: 1e9,
        })
    }
}

/// Build 2D clip epochs for viewport culling.
fn build_viewport_epochs(list: &DisplayList, bboxes: &[Option<BBox2D>]) -> Vec<ViewportEpoch> {
    let elements = list.elements();
    let mut epochs = Vec::new();
    let mut epoch_start = 0;
    let mut x_min = f64::INFINITY;
    let mut x_max = f64::NEG_INFINITY;
    let mut y_min = f64::INFINITY;
    let mut y_max = f64::NEG_INFINITY;
    let mut has_erase = false;

    for (i, element) in elements.iter().enumerate() {
        if matches!(element, DisplayElement::InitClip) && i > epoch_start {
            epochs.push(ViewportEpoch {
                start_idx: epoch_start,
                end_idx: i,
                paint_bbox: if x_min <= x_max {
                    Some(BBox2D {
                        x_min,
                        y_min,
                        x_max,
                        y_max,
                    })
                } else {
                    None
                },
                has_erase_page: has_erase,
            });
            epoch_start = i;
            x_min = f64::INFINITY;
            x_max = f64::NEG_INFINITY;
            y_min = f64::INFINITY;
            y_max = f64::NEG_INFINITY;
            has_erase = false;
        }
        if matches!(element, DisplayElement::ErasePage) {
            has_erase = true;
        }
        if let Some(ref bbox) = bboxes[i] {
            x_min = x_min.min(bbox.x_min);
            x_max = x_max.max(bbox.x_max);
            y_min = y_min.min(bbox.y_min);
            y_max = y_max.max(bbox.y_max);
        }
    }
    if epoch_start < elements.len() {
        epochs.push(ViewportEpoch {
            start_idx: epoch_start,
            end_idx: elements.len(),
            paint_bbox: if x_min <= x_max {
                Some(BBox2D {
                    x_min,
                    y_min,
                    x_max,
                    y_max,
                })
            } else {
                None
            },
            has_erase_page: has_erase,
        });
    }
    epochs
}

/// Clip epoch with full 2D bounding box for viewport culling.
struct ViewportEpoch {
    start_idx: usize,
    end_idx: usize,
    paint_bbox: Option<BBox2D>,
    has_erase_page: bool,
}

/// Pre-computed metadata for fast viewport rendering.
///
/// Compute once per display list via [`prepare_display_list()`],
/// reuse across all [`render_region_prepared()`] calls. This avoids
/// three expensive traversals (bboxes, epochs, clip_seen) on every pan.
pub struct PreparedDisplayList {
    bboxes: Vec<Option<BBox2D>>,
    epochs: Vec<ViewportEpoch>,
    clip_seen: HashSet<u64>,
}

/// Precompute display list metadata for fast viewport rendering.
///
/// Uses a conservative DPI (72.0) for hairline expansion in bounding boxes,
/// producing safe overestimates that work at any zoom level without recomputation.
pub fn prepare_display_list(list: &DisplayList) -> PreparedDisplayList {
    let bboxes = precompute_full_bboxes(list, 72.0);
    let epochs = build_viewport_epochs(list, &bboxes);
    let clip_seen = precompute_clip_seen(list);
    PreparedDisplayList {
        bboxes,
        epochs,
        clip_seen,
    }
}

/// Pre-converted and prescaled image for banded rendering.
///
/// Built once per page before the band loop so that expensive RGBA conversion
/// and box-filter prescaling run once instead of once-per-band.
struct PreprocessedImage {
    /// RGBA pixel data (prescaled if applicable).
    data: Vec<u8>,
    /// Dimensions after prescaling.
    width: u32,
    height: u32,
    /// Scale/rotation part of the adjusted transform.
    /// Per-band rendering reconstructs the full transform by combining these
    /// with the band-specific translation (tx, ty).
    adj_sx: f32,
    adj_ky: f32,
    adj_kx: f32,
    adj_sy: f32,
    /// Filter quality for draw_pixmap.
    quality: stet_tiny_skia::FilterQuality,
}

/// Pre-converted RGBA image data cache, indexed by display list element index.
///
/// Built once per page after display list capture. Reused across all viewport
/// renders so that ICC color conversion (especially CMYK→sRGB) is not repeated
/// on every pan/zoom.
pub struct ImageCache {
    /// RGBA data per element index. `None` for non-image elements.
    entries: Vec<Option<Vec<u8>>>,
}

impl ImageCache {
    /// Build cache by pre-converting all images in the display list.
    pub fn build(list: &DisplayList, icc: Option<&IccCache>) -> Self {
        let entries = list
            .elements()
            .iter()
            .map(|elem| {
                if let DisplayElement::Image {
                    sample_data,
                    params,
                } = elem
                {
                    if params.width == 0 || params.height == 0 {
                        return None;
                    }
                    let mut rgba = samples_to_rgba(sample_data, params, icc, false);
                    if params.mask_color.is_some() {
                        apply_mask_color_rgba(&mut rgba, sample_data, params);
                    }
                    Some(rgba)
                } else {
                    None
                }
            })
            .collect();
        Self { entries }
    }

    /// Get pre-converted RGBA for the element at the given index.
    pub fn get(&self, index: usize) -> Option<&[u8]> {
        self.entries.get(index).and_then(|e| e.as_deref())
    }
}

/// Build preprocessed image cache for banded rendering.
///
/// For each Image element, converts to RGBA and prescales once.
/// Banded rendering then only needs `draw_pixmap` per band.
fn preprocess_images_for_bands(
    list: &DisplayList,
    icc: Option<&IccCache>,
) -> Vec<Option<PreprocessedImage>> {
    list.elements()
        .iter()
        .map(|elem| {
            let DisplayElement::Image {
                sample_data,
                params,
            } = elem
            else {
                return None;
            };
            let iw = params.width;
            let ih = params.height;
            if iw == 0 || ih == 0 {
                return None;
            }
            // Skip overprint images — they use a separate rendering path
            if params.overprint {
                return None;
            }

            // Convert to RGBA
            let mut rgba = samples_to_rgba(sample_data, params, icc, false);
            if params.mask_color.is_some() {
                apply_mask_color_rgba(&mut rgba, sample_data, params);
            }

            // Compute the device-space transform (vp_y=0, scale=1.0)
            let image_inv = params.image_matrix.invert()?;
            let combined = params.ctm.concat(&image_inv);
            let base_transform = enforce_min_image_size(to_transform(&combined), iw, ih);

            // Prescale
            let (data, width, height, adj_t) =
                match prescale_image(&rgba, iw, ih, base_transform, params.interpolate) {
                    Some((d, w, h, t)) => {
                        drop(rgba); // free the full-size RGBA
                        (d, w, h, t)
                    }
                    None => (rgba, iw, ih, base_transform),
                };

            let quality = image_filter_quality(adj_t, params.interpolate);

            Some(PreprocessedImage {
                data,
                width,
                height,
                adj_sx: adj_t.sx,
                adj_ky: adj_t.ky,
                adj_kx: adj_t.kx,
                adj_sy: adj_t.sy,
                quality,
            })
        })
        .collect()
}

/// Render a rectangular viewport region using precomputed metadata.
///
/// Like [`render_region()`] but skips the three precomputation passes,
/// using the [`PreparedDisplayList`] instead. Significantly faster for
/// repeated renders of the same display list (e.g., panning at a fixed zoom).
#[allow(clippy::too_many_arguments)]
pub fn render_region_prepared(
    list: &DisplayList,
    prepared: &PreparedDisplayList,
    vp_x: f64,
    vp_y: f64,
    vp_w: f64,
    vp_h: f64,
    pixel_w: u32,
    pixel_h: u32,
    dpi: f64,
    icc: Option<&IccCache>,
    image_cache: Option<&ImageCache>,
    no_aa: bool,
) -> Vec<u8> {
    if pixel_w == 0 || pixel_h == 0 || vp_w <= 0.0 || vp_h <= 0.0 {
        return vec![0xFF; pixel_w as usize * pixel_h as usize * 4];
    }

    let layer_set = LayerSet::new();
    let scale_x = pixel_w as f64 / vp_w;
    let scale_y = pixel_h as f64 / vp_h;
    let effective_dpi = dpi * scale_x;

    // Allocate a pixmap with the same OVERLAP padding as the banded page
    // renderer. This is essential for matching the banded baseline: the page
    // pipeline always allocates `band_h + 2*BAND_OVERLAP` rows, even for a
    // single-band render. tiny-skia's `Mask::fill_path` chooses between
    // edge-clipped and unclipped rasterization based on whether the path
    // bounds fit within the mask, and the two paths produce subtly different
    // winding counts at some pixels. Without the OVERLAP padding here, the
    // viewport pipeline rasterizes clip paths into a tighter mask than the
    // banded pipeline does, producing 39 (and other counts) of edge-pixel
    // divergences on samples like 1915_1.pdf.
    const OVERLAP: u32 = 6;
    let render_h = pixel_h + 2 * OVERLAP;
    let mut pixmap = Pixmap::new(pixel_w, render_h).expect("Failed to create viewport pixmap");
    // Start transparent — white background composited after content rendering
    pixmap.fill(Color::TRANSPARENT);

    let cmyk_buf = if has_overprint_elements(list)
        || list.page_group_color_space() == stet_graphics::display_list::GroupColorSpace::DeviceCMYK
        || has_cmyk_group(list)
    {
        Some(vec![0.0f32; pixel_w as usize * render_h as usize * 4])
    } else {
        None
    };

    let mut state = BandState {
        clip_region: None,
        spare_mask: None,
        clip_mask_cache: HashMap::new(),
        clip_mask_seen: prepared.clip_seen.clone(),
        mask_pool: Vec::new(),
        cmyk_buffer: cmyk_buf,
        op_bg_snapshot: None,
        op_touched: None,
        spot_mask: None,
    };

    let elements = list.elements();
    let vp_x_f = vp_x as f32;
    let vp_y_f = vp_y as f32;
    let sx = scale_x as f32;
    let sy = scale_y as f32;
    let vp_x_max = vp_x + vp_w;
    let vp_y_max = vp_y + vp_h;

    for epoch in &prepared.epochs {
        if !epoch.has_erase_page {
            match epoch.paint_bbox {
                Some(ref pb)
                    if pb.x_max <= vp_x
                        || pb.x_min >= vp_x_max
                        || pb.y_max <= vp_y
                        || pb.y_min >= vp_y_max =>
                {
                    continue;
                }
                None => continue,
                _ => {}
            }
        }

        #[allow(clippy::needless_range_loop)]
        for i in epoch.start_idx..epoch.end_idx {
            // OcgGroups with Clip/InitClip must always be processed — see
            // the banded renderer for the rationale.
            let force_process = matches!(
                &elements[i],
                DisplayElement::OcgGroup { elements: inner, .. }
                    if contains_clip_op(inner)
            );
            if !force_process
                && let Some(ref bbox) = prepared.bboxes[i]
                && (bbox.x_max <= vp_x
                    || bbox.x_min >= vp_x_max
                    || bbox.y_max <= vp_y
                    || bbox.y_min >= vp_y_max)
            {
                continue;
            }
            let ctx = RenderContext {
                vp_x: vp_x_f,
                vp_y: vp_y_f,
                scale_x: sx,
                scale_y: sy,
                out_w: pixel_w,
                out_h: render_h,
                effective_dpi,
                icc,
                image_cache,
                preprocessed: None,
                elem_idx: i,
                no_aa,
                opm_zero_transparent: false,
                knockout_painter_pass: KnockoutPainterPass::None,
                parent_group_isolated: false,
                alpha_extraction_pass: false,
                layer_set: &layer_set,
            };
            render_element(&mut pixmap, &mut state, &elements[i], &ctx);
        }
    }

    // Composite onto white background
    composite_onto_white(pixmap.data_mut());
    // Extract only the requested pixel_h rows (skip the OVERLAP padding at the bottom).
    let row_bytes = pixel_w as usize * 4;
    let end = pixel_h as usize * row_bytes;
    pixmap.data()[..end].to_vec()
}

/// Compute the number of bands and band height for viewport banding.
///
/// Returns `(num_bands, band_height)` using the same L2-cache-budget logic
/// as the full-page banded renderer.
pub fn viewport_band_count(pixel_w: u32, pixel_h: u32) -> (u32, u32) {
    let band_h = select_band_height(pixel_w, pixel_h);
    let num_bands = if band_h >= pixel_h {
        1
    } else {
        pixel_h.div_ceil(band_h)
    };
    (num_bands, band_h)
}

/// Render a single horizontal band of a viewport region.
///
/// This is the per-band counterpart to [`render_region_prepared()`]. The caller
/// loops over `band_idx` in `0..num_bands`, collecting RGBA strips that tile
/// vertically to form the full viewport image.
///
/// Returns RGBA pixel data for `actual_h` rows (may be less than `band_h` for
/// the last band).
#[allow(clippy::too_many_arguments)]
pub fn render_region_single_band(
    list: &DisplayList,
    prepared: &PreparedDisplayList,
    vp_x: f64,
    vp_y: f64,
    vp_w: f64,
    vp_h: f64,
    pixel_w: u32,
    pixel_h: u32,
    band_idx: u32,
    band_h: u32,
    num_bands: u32,
    dpi: f64,
    icc: Option<&IccCache>,
    image_cache: Option<&ImageCache>,
    no_aa: bool,
) -> Vec<u8> {
    if pixel_w == 0 || pixel_h == 0 || vp_w <= 0.0 || vp_h <= 0.0 {
        let actual_h = if band_idx < num_bands - 1 {
            band_h
        } else {
            pixel_h - band_idx * band_h
        };
        return vec![0xFF; pixel_w as usize * actual_h as usize * 4];
    }

    let layer_set = LayerSet::new();
    let scale_x = pixel_w as f64 / vp_w;
    let scale_y = pixel_h as f64 / vp_h;
    let effective_dpi = dpi * scale_x;

    // Output Y range for this band
    let out_y_start = band_idx * band_h;
    let actual_h = if band_idx < num_bands - 1 {
        band_h
    } else {
        pixel_h - out_y_start
    };

    // Add overlap above/below for anti-aliasing at seams.
    //
    // The pixmap is always `band_h + 2*OVERLAP` rows — matching the page
    // renderer (`render_banded_to_sink`) — even at the bottom band, where
    // content rendering stops at `pixel_h`. Without this, the bottom band's
    // pixmap is shorter than the page renderer's, and tiny-skia's
    // `Mask::fill_path` rasterizes clip paths into a tighter mask, producing
    // edge-pixel divergences from the banded baseline (39 pixels on
    // 1915_1.pdf, etc.). The extra rows below `pixel_h` are unused for output
    // but ensure mask-size-independent rasterization.
    const OVERLAP: u32 = 6;
    let render_y_start = out_y_start.saturating_sub(OVERLAP);
    let render_y_end = (out_y_start + actual_h + OVERLAP).min(pixel_h);
    let render_h = band_h + 2 * OVERLAP;
    let overlap_top = out_y_start - render_y_start;

    // Source-space Y range for culling
    let src_y_min = vp_y + render_y_start as f64 / scale_y;
    let src_y_max = vp_y + render_y_end as f64 / scale_y;

    // Adjusted viewport offset for this band's pixmap
    let band_vp_y = vp_y + render_y_start as f64 / scale_y;

    let mut pixmap = Pixmap::new(pixel_w, render_h).expect("Failed to create band pixmap");
    pixmap.fill(Color::TRANSPARENT);

    let cmyk_buf = if has_overprint_elements(list)
        || list.page_group_color_space() == stet_graphics::display_list::GroupColorSpace::DeviceCMYK
        || has_cmyk_group(list)
    {
        Some(vec![0.0f32; pixel_w as usize * render_h as usize * 4])
    } else {
        None
    };

    let mut state = BandState {
        clip_region: None,
        spare_mask: None,
        clip_mask_cache: HashMap::new(),
        clip_mask_seen: prepared.clip_seen.clone(),
        mask_pool: Vec::new(),
        cmyk_buffer: cmyk_buf,
        op_bg_snapshot: None,
        op_touched: None,
        spot_mask: None,
    };

    let elements = list.elements();
    let vp_x_f = vp_x as f32;
    let band_vp_y_f = band_vp_y as f32;
    let sx = scale_x as f32;
    let sy = scale_y as f32;
    let vp_x_max = vp_x + vp_w;

    for epoch in &prepared.epochs {
        if !epoch.has_erase_page {
            match epoch.paint_bbox {
                Some(ref pb)
                    if pb.x_max <= vp_x
                        || pb.x_min >= vp_x_max
                        || pb.y_max <= src_y_min
                        || pb.y_min >= src_y_max =>
                {
                    continue;
                }
                None => continue,
                _ => {}
            }
        }

        #[allow(clippy::needless_range_loop)]
        for i in epoch.start_idx..epoch.end_idx {
            // OcgGroups containing Clip/InitClip must always be processed
            // regardless of this band's bbox — see the full-page banded
            // renderer for the rationale.
            let force_process = matches!(
                &elements[i],
                DisplayElement::OcgGroup { elements: inner, .. }
                    if contains_clip_op(inner)
            );
            if !force_process
                && let Some(ref bbox) = prepared.bboxes[i]
                && (bbox.x_max <= vp_x
                    || bbox.x_min >= vp_x_max
                    || bbox.y_max <= src_y_min
                    || bbox.y_min >= src_y_max)
            {
                continue;
            }
            let ctx = RenderContext {
                vp_x: vp_x_f,
                vp_y: band_vp_y_f,
                scale_x: sx,
                scale_y: sy,
                out_w: pixel_w,
                out_h: render_h,
                effective_dpi,
                icc,
                image_cache,
                preprocessed: None,
                elem_idx: i,
                no_aa,
                opm_zero_transparent: false,
                knockout_painter_pass: KnockoutPainterPass::None,
                parent_group_isolated: false,
                alpha_extraction_pass: false,
                layer_set: &layer_set,
            };
            render_element(&mut pixmap, &mut state, &elements[i], &ctx);
        }
    }

    // Composite onto white background
    composite_onto_white(pixmap.data_mut());

    // Extract only the non-overlap rows
    let row_bytes = pixel_w as usize * 4;
    let start = overlap_top as usize * row_bytes;
    let end = start + actual_h as usize * row_bytes;
    pixmap.data()[start..end].to_vec()
}

/// Render a viewport region using parallel banded rendering via rayon.
///
/// This is the WASM counterpart to the parallel path in `render_banded_to_sink`.
/// All bands are rendered in parallel using `par_iter`, then assembled into the
/// final RGBA buffer in order.
///
/// Requires the `parallel` feature (rayon). Falls back to sequential rendering
/// if `parallel` is not enabled.
#[allow(clippy::too_many_arguments)]
pub fn render_region_prepared_parallel(
    list: &DisplayList,
    prepared: &PreparedDisplayList,
    vp_x: f64,
    vp_y: f64,
    vp_w: f64,
    vp_h: f64,
    pixel_w: u32,
    pixel_h: u32,
    dpi: f64,
    icc: Option<&IccCache>,
    image_cache: Option<&ImageCache>,
    no_aa: bool,
) -> Vec<u8> {
    let (num_bands, band_h) = viewport_band_count(pixel_w, pixel_h);

    if num_bands <= 1 {
        // Single band — no parallelism needed
        return render_region_prepared(
            list,
            prepared,
            vp_x,
            vp_y,
            vp_w,
            vp_h,
            pixel_w,
            pixel_h,
            dpi,
            icc,
            image_cache,
            no_aa,
        );
    }

    let render_band = |band_idx: u32| -> Vec<u8> {
        render_region_single_band(
            list,
            prepared,
            vp_x,
            vp_y,
            vp_w,
            vp_h,
            pixel_w,
            pixel_h,
            band_idx,
            band_h,
            num_bands,
            dpi,
            icc,
            image_cache,
            no_aa,
        )
    };

    let row_bytes = pixel_w as usize * 4;
    let mut result = vec![0u8; pixel_w as usize * pixel_h as usize * 4];

    #[cfg(feature = "parallel")]
    {
        let chunk_size = rayon::current_num_threads().max(1);

        for chunk_start in (0..num_bands).step_by(chunk_size) {
            let chunk_end = (chunk_start + chunk_size as u32).min(num_bands);

            let rendered: Vec<Vec<u8>> = (chunk_start..chunk_end)
                .into_par_iter()
                .map(&render_band)
                .collect();

            for (i, band_data) in rendered.iter().enumerate() {
                let band_idx = chunk_start + i as u32;
                let y_start = (band_idx * band_h) as usize;
                let dest_start = y_start * row_bytes;
                let len = band_data.len();
                result[dest_start..dest_start + len].copy_from_slice(band_data);
            }
        }
    }
    #[cfg(not(feature = "parallel"))]
    {
        for band_idx in 0..num_bands {
            let band_data = render_band(band_idx);
            let y_start = (band_idx * band_h) as usize;
            let dest_start = y_start * row_bytes;
            let len = band_data.len();
            result[dest_start..dest_start + len].copy_from_slice(&band_data);
        }
    }

    result
}

/// Like [`render_region_prepared_parallel()`] but with an atomic progress counter.
///
/// The counter is incremented after each chunk of bands completes. The total
/// number of bands is returned alongside the counter via [`viewport_band_count()`].
#[allow(clippy::too_many_arguments)]
pub fn render_region_prepared_parallel_with_progress(
    list: &DisplayList,
    prepared: &PreparedDisplayList,
    vp_x: f64,
    vp_y: f64,
    vp_w: f64,
    vp_h: f64,
    pixel_w: u32,
    pixel_h: u32,
    dpi: f64,
    icc: Option<&IccCache>,
    image_cache: Option<&ImageCache>,
    no_aa: bool,
    progress: &std::sync::atomic::AtomicU32,
) -> Vec<u8> {
    let (num_bands, band_h) = viewport_band_count(pixel_w, pixel_h);

    if num_bands <= 1 {
        let result = render_region_prepared(
            list,
            prepared,
            vp_x,
            vp_y,
            vp_w,
            vp_h,
            pixel_w,
            pixel_h,
            dpi,
            icc,
            image_cache,
            no_aa,
        );
        progress.store(1, std::sync::atomic::Ordering::Relaxed);
        return result;
    }

    let render_band = |band_idx: u32| -> Vec<u8> {
        render_region_single_band(
            list,
            prepared,
            vp_x,
            vp_y,
            vp_w,
            vp_h,
            pixel_w,
            pixel_h,
            band_idx,
            band_h,
            num_bands,
            dpi,
            icc,
            image_cache,
            no_aa,
        )
    };

    let row_bytes = pixel_w as usize * 4;
    let mut result = vec![0u8; pixel_w as usize * pixel_h as usize * 4];

    #[cfg(feature = "parallel")]
    {
        let chunk_size = rayon::current_num_threads().max(1);

        for chunk_start in (0..num_bands).step_by(chunk_size) {
            let chunk_end = (chunk_start + chunk_size as u32).min(num_bands);

            let rendered: Vec<Vec<u8>> = (chunk_start..chunk_end)
                .into_par_iter()
                .map(&render_band)
                .collect();

            for (i, band_data) in rendered.iter().enumerate() {
                let band_idx = chunk_start + i as u32;
                let y_start = (band_idx * band_h) as usize;
                let dest_start = y_start * row_bytes;
                let len = band_data.len();
                result[dest_start..dest_start + len].copy_from_slice(band_data);
            }
            progress.store(chunk_end, std::sync::atomic::Ordering::Relaxed);
        }
    }
    #[cfg(not(feature = "parallel"))]
    {
        for band_idx in 0..num_bands {
            let band_data = render_band(band_idx);
            let y_start = (band_idx * band_h) as usize;
            let dest_start = y_start * row_bytes;
            let len = band_data.len();
            result[dest_start..dest_start + len].copy_from_slice(&band_data);
            progress.store(band_idx + 1, std::sync::atomic::Ordering::Relaxed);
        }
    }

    result
}

/// Like [`render_region_prepared_parallel()`] but checks a cancellation flag
/// between band chunks. Returns `None` if cancelled.
#[allow(clippy::too_many_arguments)]
pub fn render_region_prepared_parallel_cancellable(
    list: &DisplayList,
    prepared: &PreparedDisplayList,
    vp_x: f64,
    vp_y: f64,
    vp_w: f64,
    vp_h: f64,
    pixel_w: u32,
    pixel_h: u32,
    dpi: f64,
    icc: Option<&IccCache>,
    image_cache: Option<&ImageCache>,
    no_aa: bool,
    cancelled: &std::sync::atomic::AtomicBool,
) -> Option<Vec<u8>> {
    if cancelled.load(std::sync::atomic::Ordering::Relaxed) {
        return None;
    }

    let (num_bands, band_h) = viewport_band_count(pixel_w, pixel_h);

    if num_bands <= 1 {
        return Some(render_region_prepared(
            list,
            prepared,
            vp_x,
            vp_y,
            vp_w,
            vp_h,
            pixel_w,
            pixel_h,
            dpi,
            icc,
            image_cache,
            no_aa,
        ));
    }

    let render_band = |band_idx: u32| -> Vec<u8> {
        render_region_single_band(
            list,
            prepared,
            vp_x,
            vp_y,
            vp_w,
            vp_h,
            pixel_w,
            pixel_h,
            band_idx,
            band_h,
            num_bands,
            dpi,
            icc,
            image_cache,
            no_aa,
        )
    };

    let row_bytes = pixel_w as usize * 4;
    let mut result = vec![0u8; pixel_w as usize * pixel_h as usize * 4];

    #[cfg(feature = "parallel")]
    {
        let chunk_size = rayon::current_num_threads().max(1);

        for chunk_start in (0..num_bands).step_by(chunk_size) {
            if cancelled.load(std::sync::atomic::Ordering::Relaxed) {
                return None;
            }
            let chunk_end = (chunk_start + chunk_size as u32).min(num_bands);

            let rendered: Vec<Vec<u8>> = (chunk_start..chunk_end)
                .into_par_iter()
                .map(&render_band)
                .collect();

            for (i, band_data) in rendered.iter().enumerate() {
                let band_idx = chunk_start + i as u32;
                let y_start = (band_idx * band_h) as usize;
                let dest_start = y_start * row_bytes;
                let len = band_data.len();
                result[dest_start..dest_start + len].copy_from_slice(band_data);
            }
        }
    }
    #[cfg(not(feature = "parallel"))]
    {
        for band_idx in 0..num_bands {
            if cancelled.load(std::sync::atomic::Ordering::Relaxed) {
                return None;
            }
            let band_data = render_band(band_idx);
            let y_start = (band_idx * band_h) as usize;
            let dest_start = y_start * row_bytes;
            let len = band_data.len();
            result[dest_start..dest_start + len].copy_from_slice(&band_data);
        }
    }

    Some(result)
}

/// Render a full-page display list to RGBA pixels using the banded parallel renderer.
///
/// This is the preferred way to render a complete page — it uses rayon parallelism
/// (when the `parallel` feature is enabled) and L2-cache-friendly band sizing.
/// For sub-region / zoomed viewport rendering, use `render_region` instead.
///
/// Returns RGBA pixel data of size `pixel_w × pixel_h × 4`, composited onto white.
pub fn render_to_rgba(
    list: &DisplayList,
    pixel_w: u32,
    pixel_h: u32,
    dpi: f64,
    icc: Option<&IccCache>,
    no_aa: bool,
) -> Vec<u8> {
    render_to_rgba_with_layers(list, pixel_w, pixel_h, dpi, icc, no_aa, &LayerSet::new())
}

/// Like [`render_to_rgba`] but consults the supplied [`LayerSet`] when
/// evaluating each `OcgGroup`'s visibility.
///
/// Pass `&LayerSet::new()` (or use [`render_to_rgba`]) to fall back to
/// each OCG's `default_visible` baked from the document's default
/// configuration.
#[allow(clippy::too_many_arguments)]
pub fn render_to_rgba_with_layers(
    list: &DisplayList,
    pixel_w: u32,
    pixel_h: u32,
    dpi: f64,
    icc: Option<&IccCache>,
    no_aa: bool,
    layer_set: &LayerSet,
) -> Vec<u8> {
    if pixel_w == 0 || pixel_h == 0 {
        return vec![0xFF; pixel_w as usize * pixel_h as usize * 4];
    }

    let mut icc_cache = match icc {
        Some(c) => c.clone(),
        None => IccCache::new(),
    };
    // Register any ICC profiles from shadings in the display list
    // (the caller's cache only has image profiles)
    register_shading_icc_profiles(list, &mut icc_cache);

    let mut sink = MemorySink {
        data: Vec::new(),
        width: 0,
    };

    let band_h = select_band_height(pixel_w, pixel_h);
    if let Err(e) = render_banded_to_sink(
        pixel_w, pixel_h, band_h, dpi, list, &mut sink, &icc_cache, no_aa, layer_set,
    ) {
        eprintln!("render_to_rgba: banded render failed: {e}");
        return vec![0xFF; pixel_w as usize * pixel_h as usize * 4];
    }

    sink.data
}

/// Render a display list to RGBA using the **viewport** code path, with
/// the viewport set to the full page at 1:1 scale.
///
/// This exists to audit the viewport pipeline (`render_region_prepared_*`)
/// against the same baselines the banded PNG path uses. The two paths share
/// `render_element` and the same display list, so their output should be
/// pixel-identical on a correctly implemented display list. Differences
/// indicate a bug in one of the two culling / epoch / bbox pipelines.
///
/// The CLI exposes this as `--device viewport-png`; the visual test runner
/// uses it to double-cover each sample without maintaining a second
/// baseline.
pub fn render_to_rgba_viewport(
    list: &DisplayList,
    pixel_w: u32,
    pixel_h: u32,
    dpi: f64,
    icc: Option<&IccCache>,
    no_aa: bool,
) -> Vec<u8> {
    if pixel_w == 0 || pixel_h == 0 {
        return vec![0xFF; pixel_w as usize * pixel_h as usize * 4];
    }

    let mut icc_cache = match icc {
        Some(c) => c.clone(),
        None => IccCache::new(),
    };
    register_shading_icc_profiles(list, &mut icc_cache);

    let prepared = prepare_display_list(list);
    render_region_prepared_parallel(
        list,
        &prepared,
        0.0,
        0.0,
        pixel_w as f64,
        pixel_h as f64,
        pixel_w,
        pixel_h,
        dpi,
        Some(&icc_cache),
        None,
        no_aa,
    )
}

/// Debug helper: format both bbox precomputations side-by-side.
///
/// Returns one line per element describing its Y-only bbox (used by the
/// banded page pipeline) and its 2D bbox (used by the viewport pipeline).
/// Elements that disagree on presence, or whose 2D bbox's Y extent differs
/// from the Y-only bbox, are marked with `DIFF`.
fn debug_bbox_lines(list: &DisplayList, dpi: f64, depth: usize, out: &mut Vec<String>) {
    let y_bboxes = precompute_bboxes(list, dpi);
    let full_bboxes = precompute_full_bboxes(list, dpi);
    let elements = list.elements();
    let indent = "  ".repeat(depth);
    for (i, elem) in elements.iter().enumerate() {
        let kind = match elem {
            DisplayElement::Fill { .. } => "Fill",
            DisplayElement::Stroke { .. } => "Stroke",
            DisplayElement::Image { .. } => "Image",
            DisplayElement::AxialShading { .. } => "AxialShading",
            DisplayElement::RadialShading { .. } => "RadialShading",
            DisplayElement::MeshShading { .. } => "MeshShading",
            DisplayElement::PatchShading { .. } => "PatchShading",
            DisplayElement::PatternFill { .. } => "PatternFill",
            DisplayElement::Group { .. } => "Group",
            DisplayElement::SoftMasked { .. } => "SoftMasked",
            DisplayElement::OcgGroup { .. } => "OcgGroup",
            DisplayElement::Clip { .. } => "Clip",
            DisplayElement::InitClip => "InitClip",
            DisplayElement::ErasePage => "ErasePage",
            DisplayElement::Text { .. } => "Text",
            _ => "Unknown",
        };
        let yb = &y_bboxes[i];
        let fb = &full_bboxes[i];
        let mut diff = false;
        if yb.is_some() != fb.is_some() {
            diff = true;
        }
        if let (Some(yb), Some(fb)) = (yb, fb)
            && ((yb.y_min - fb.y_min).abs() > 1e-9 || (yb.y_max - fb.y_max).abs() > 1e-9)
        {
            diff = true;
        }
        let yb_s = match yb {
            Some(b) => format!("Y[{:8.3}..{:8.3}]", b.y_min, b.y_max),
            None => "Y[None]".to_string(),
        };
        let fb_s = match fb {
            Some(b) => format!(
                "2D[x {:8.3}..{:8.3} y {:8.3}..{:8.3}]",
                b.x_min, b.x_max, b.y_min, b.y_max
            ),
            None => "2D[None]".to_string(),
        };
        out.push(format!(
            "{}{:4} {:15} {:30} {:55} {}",
            indent,
            i,
            kind,
            yb_s,
            fb_s,
            if diff { "DIFF" } else { "" }
        ));
        if let DisplayElement::Stroke { path, params } = elem {
            let rp = path_full_bbox(path);
            let m = &params.ctm;
            out.push(format!(
                "{}        ctm=[{:.4} {:.4} {:.4} {:.4} {:.4} {:.4}] lw={:.4} miter={:.4} raw={}",
                indent,
                m.a,
                m.b,
                m.c,
                m.d,
                m.tx,
                m.ty,
                params.line_width,
                params.miter_limit,
                match rp {
                    Some(b) => format!(
                        "x[{:.3}..{:.3}] y[{:.3}..{:.3}]",
                        b.x_min, b.x_max, b.y_min, b.y_max
                    ),
                    None => "None".to_string(),
                }
            ));
        }
        if let DisplayElement::Clip { path, params } = elem {
            let rp = path_full_bbox(path);
            let m = &params.ctm;
            out.push(format!(
                "{}        clip ctm=[{:.4} {:.4} {:.4} {:.4} {:.4} {:.4}] rule={:?} raw={}",
                indent,
                m.a,
                m.b,
                m.c,
                m.d,
                m.tx,
                m.ty,
                params.fill_rule,
                match rp {
                    Some(b) => format!(
                        "x[{:.3}..{:.3}] y[{:.3}..{:.3}]",
                        b.x_min, b.x_max, b.y_min, b.y_max
                    ),
                    None => "None".to_string(),
                }
            ));
        }
        if let DisplayElement::PatchShading { params } = elem {
            out.push(format!(
                "{}        patch ctm=[{:.4} {:.4} {:.4} {:.4} {:.4} {:.4}] bbox={:?} patches={}",
                indent,
                params.ctm.a,
                params.ctm.b,
                params.ctm.c,
                params.ctm.d,
                params.ctm.tx,
                params.ctm.ty,
                params.bbox,
                params.patches.len()
            ));
            if !params.patches.is_empty() {
                let patch = &params.patches[0];
                // Compute device-space bbox of patch points
                let mut x_min = f64::INFINITY;
                let mut y_min = f64::INFINITY;
                let mut x_max = f64::NEG_INFINITY;
                let mut y_max = f64::NEG_INFINITY;
                for &(px, py) in &patch.points {
                    let (dx, dy) = params.ctm.transform_point(px, py);
                    x_min = x_min.min(dx);
                    y_min = y_min.min(dy);
                    x_max = x_max.max(dx);
                    y_max = y_max.max(dy);
                }
                out.push(format!(
                    "{}        patch[0] pts={} dev x[{:.3}..{:.3}] y[{:.3}..{:.3}]",
                    indent,
                    patch.points.len(),
                    x_min,
                    x_max,
                    y_min,
                    y_max
                ));
            }
        }
        if let DisplayElement::Group {
            elements: inner,
            params,
        } = elem
        {
            out.push(format!(
                "{}        group bbox={:?} iso={} ko={} alpha={} bm={} cs={:?}",
                indent,
                params.bbox,
                params.isolated,
                params.knockout,
                params.alpha,
                params.blend_mode,
                params.color_space
            ));
            debug_bbox_lines(inner, dpi, depth + 1, out);
        }
        if let DisplayElement::SoftMasked {
            content, params, ..
        } = elem
        {
            out.push(format!(
                "{}        softmasked bbox={:?}",
                indent, params.bbox
            ));
            debug_bbox_lines(content, dpi, depth + 1, out);
        }
        if let DisplayElement::OcgGroup {
            elements: inner,
            visibility,
        } = elem
        {
            out.push(format!(
                "{}        ocg default_visible={}",
                indent,
                visibility.default_visible()
            ));
            debug_bbox_lines(inner, dpi, depth + 1, out);
        }
    }
}

pub fn debug_bbox_comparison(list: &DisplayList, dpi: f64) -> Vec<String> {
    let mut out = Vec::new();
    debug_bbox_lines(list, dpi, 0, &mut out);
    out
}

/// In-memory page sink that collects RGBA rows into a Vec.
struct MemorySink {
    data: Vec<u8>,
    width: u32,
}

impl stet_graphics::device::PageSink for MemorySink {
    fn begin_page(&mut self, width: u32, height: u32) -> Result<(), String> {
        self.width = width;
        self.data.reserve(width as usize * height as usize * 4);
        Ok(())
    }

    fn write_rows(&mut self, rgba_rows: &[u8], _num_rows: u32) -> Result<(), String> {
        self.data.extend_from_slice(rgba_rows);
        Ok(())
    }

    fn end_page(&mut self) -> Result<(), String> {
        Ok(())
    }
}

/// Render a rectangular viewport region of a display list to RGBA pixels.
///
/// - `list`: The display list to render (in device-space coordinates at the reference DPI)
/// - `vp_x, vp_y, vp_w, vp_h`: Viewport rectangle in device-space pixels
/// - `pixel_w, pixel_h`: Output pixel dimensions
/// - `dpi`: Reference DPI (for hairline width decisions)
///
/// Returns RGBA pixel data of size `pixel_w × pixel_h × 4`.
#[allow(clippy::too_many_arguments)]
pub fn render_region(
    list: &DisplayList,
    vp_x: f64,
    vp_y: f64,
    vp_w: f64,
    vp_h: f64,
    pixel_w: u32,
    pixel_h: u32,
    dpi: f64,
    icc: Option<&IccCache>,
    image_cache: Option<&ImageCache>,
    no_aa: bool,
) -> Vec<u8> {
    if pixel_w == 0 || pixel_h == 0 || vp_w <= 0.0 || vp_h <= 0.0 {
        return vec![0xFF; pixel_w as usize * pixel_h as usize * 4];
    }

    let layer_set = LayerSet::new();
    let scale_x = pixel_w as f64 / vp_w;
    let scale_y = pixel_h as f64 / vp_h;
    // Effective DPI for hairline decisions — reference DPI scaled by zoom
    let effective_dpi = dpi * scale_x;

    let bboxes = precompute_full_bboxes(list, effective_dpi);
    let epochs = build_viewport_epochs(list, &bboxes);
    let clip_seen = precompute_clip_seen(list);

    // OVERLAP padding to match `render_banded_to_sink`. See the comment in
    // `render_region_prepared` for why this is required for tiny-skia
    // mask-rasterization parity with the page renderer.
    const OVERLAP: u32 = 6;
    let render_h = pixel_h + 2 * OVERLAP;

    let mut pixmap = Pixmap::new(pixel_w, render_h).expect("Failed to create viewport pixmap");
    pixmap.fill(Color::TRANSPARENT);

    let cmyk_buf = if has_overprint_elements(list)
        || list.page_group_color_space() == stet_graphics::display_list::GroupColorSpace::DeviceCMYK
        || has_cmyk_group(list)
    {
        Some(vec![0.0f32; pixel_w as usize * render_h as usize * 4])
    } else {
        None
    };

    let mut state = BandState {
        clip_region: None,
        spare_mask: None,
        clip_mask_cache: HashMap::new(),
        clip_mask_seen: clip_seen,
        mask_pool: Vec::new(),
        cmyk_buffer: cmyk_buf,
        op_bg_snapshot: None,
        op_touched: None,
        spot_mask: None,
    };

    let elements = list.elements();
    let vp_x_f = vp_x as f32;
    let vp_y_f = vp_y as f32;
    let sx = scale_x as f32;
    let sy = scale_y as f32;
    let vp_x_max = vp_x + vp_w;
    let vp_y_max = vp_y + vp_h;

    for epoch in &epochs {
        // Epoch-level culling
        if !epoch.has_erase_page {
            match epoch.paint_bbox {
                Some(ref pb)
                    if pb.x_max <= vp_x
                        || pb.x_min >= vp_x_max
                        || pb.y_max <= vp_y
                        || pb.y_min >= vp_y_max =>
                {
                    continue;
                }
                None => continue,
                _ => {}
            }
        }

        for i in epoch.start_idx..epoch.end_idx {
            // OcgGroups with Clip/InitClip must always be processed — see
            // render_region_prepared for the rationale.
            let force_process = matches!(
                &elements[i],
                DisplayElement::OcgGroup { elements: inner, .. }
                    if contains_clip_op(inner)
            );
            // Element-level culling
            if !force_process
                && let Some(ref bbox) = bboxes[i]
                && (bbox.x_max <= vp_x
                    || bbox.x_min >= vp_x_max
                    || bbox.y_max <= vp_y
                    || bbox.y_min >= vp_y_max)
            {
                continue;
            }
            let ctx = RenderContext {
                vp_x: vp_x_f,
                vp_y: vp_y_f,
                scale_x: sx,
                scale_y: sy,
                out_w: pixel_w,
                out_h: render_h,
                effective_dpi,
                icc,
                image_cache,
                preprocessed: None,
                elem_idx: i,
                no_aa,
                opm_zero_transparent: false,
                knockout_painter_pass: KnockoutPainterPass::None,
                parent_group_isolated: false,
                alpha_extraction_pass: false,
                layer_set: &layer_set,
            };
            render_element(&mut pixmap, &mut state, &elements[i], &ctx);
        }
    }

    composite_onto_white(pixmap.data_mut());
    // Extract only the requested pixel_h rows (skip OVERLAP padding).
    let row_bytes = pixel_w as usize * 4;
    let end = pixel_h as usize * row_bytes;
    pixmap.data()[..end].to_vec()
}
/// Copy a rectangular region from parent pixmap into a smaller crop pixmap.
fn copy_backdrop_crop(
    parent: &Pixmap,
    crop_x: i32,
    crop_y: i32,
    crop_w: u32,
    crop_h: u32,
) -> Vec<u8> {
    let pw = parent.width() as usize;
    let src = parent.data();
    let cw = crop_w as usize;
    let ch = crop_h as usize;
    let cx = crop_x as usize;
    let cy = crop_y as usize;
    let mut backdrop = vec![0u8; cw * ch * 4];
    for row in 0..ch {
        let src_off = ((cy + row) * pw + cx) * 4;
        let dst_off = row * cw * 4;
        backdrop[dst_off..dst_off + cw * 4].copy_from_slice(&src[src_off..src_off + cw * 4]);
    }
    backdrop
}
// ---- Shading rendering ----

/// Sutherland-Hodgman polygon clipping against a half-plane.
/// Keeps the side where `nx*(x-px) + ny*(y-py) >= 0`.
fn clip_polygon_halfplane(
    poly: &[(f32, f32)],
    nx: f32,
    ny: f32,
    px: f32,
    py: f32,
) -> Vec<(f32, f32)> {
    if poly.is_empty() {
        return vec![];
    }
    let dot = |x: f32, y: f32| nx * (x - px) + ny * (y - py);
    let mut out = Vec::with_capacity(poly.len() + 1);
    let n = poly.len();
    for i in 0..n {
        let (ax, ay) = poly[i];
        let (bx, by) = poly[(i + 1) % n];
        let da = dot(ax, ay);
        let db = dot(bx, by);
        if da >= 0.0 {
            out.push((ax, ay));
        }
        if (da >= 0.0) != (db >= 0.0) {
            // Edge crosses the clipping line — compute intersection
            let t = da / (da - db);
            out.push((ax + t * (bx - ax), ay + t * (by - ay)));
        }
    }
    out
}

/// Render an axial (linear) gradient shading.
#[allow(clippy::too_many_arguments)]
fn render_axial_shading(
    pixmap: &mut Pixmap,
    params: &AxialShadingParams,
    vp_x: f32,
    vp_y: f32,
    scale_x: f32,
    scale_y: f32,
    clip_mask: Option<&Mask>,
    no_aa: bool,
    cmyk_buf: Option<&mut [f32]>,
    icc: Option<&IccCache>,
) {
    let pw = pixmap.width();
    let ph = pixmap.height();
    if params.color_stops.is_empty() || pw == 0 || ph == 0 {
        return;
    }

    let (mut rx_min, mut ry_min, mut rx_max, mut ry_max) = if let Some(bbox) = &params.bbox {
        let corners = [
            params.ctm.transform_point(bbox[0], bbox[1]),
            params.ctm.transform_point(bbox[2], bbox[1]),
            params.ctm.transform_point(bbox[0], bbox[3]),
            params.ctm.transform_point(bbox[2], bbox[3]),
        ];
        let x_min = corners.iter().map(|c| c.0).fold(f64::INFINITY, f64::min);
        let y_min = corners.iter().map(|c| c.1).fold(f64::INFINITY, f64::min);
        let x_max = corners
            .iter()
            .map(|c| c.0)
            .fold(f64::NEG_INFINITY, f64::max);
        let y_max = corners
            .iter()
            .map(|c| c.1)
            .fold(f64::NEG_INFINITY, f64::max);
        (
            ((x_min as f32 - vp_x) * scale_x).max(0.0),
            ((y_min as f32 - vp_y) * scale_y).max(0.0),
            ((x_max as f32 - vp_x) * scale_x).min(pw as f32),
            ((y_max as f32 - vp_y) * scale_y).min(ph as f32),
        )
    } else {
        (0.0, 0.0, pw as f32, ph as f32)
    };

    if rx_max <= rx_min || ry_max <= ry_min {
        return;
    }

    // Transform endpoints to device space for perpendicular clipping
    let (dx0, dy0) = params.ctm.transform_point(params.x0, params.y0);
    let (dx1, dy1) = params.ctm.transform_point(params.x1, params.y1);

    // When extend is false on a side, clip the fill area along a line
    // perpendicular to the gradient axis through that endpoint. For diagonal
    // gradients this produces a diagonal cutoff (not axis-aligned).
    let needs_perpendicular_clip = (!params.extend_start || !params.extend_end) && {
        let axis_x = dx1 - dx0;
        let axis_y = dy1 - dy0;
        axis_x.abs() > 1e-6 && axis_y.abs() > 1e-6
    };

    // Detect rotated BBox: if CTM has rotation components (b or c non-zero),
    // the BBox is not axis-aligned in device space and needs proper polygon clipping.
    let bbox_is_rotated =
        params.bbox.is_some() && (params.ctm.b.abs() > 1e-10 || params.ctm.c.abs() > 1e-10);

    if needs_perpendicular_clip {
        // Diagonal gradient with non-extended side — fall back to tiny-skia
        // for Sutherland-Hodgman polygon clipping.
        let stops = build_gradient_stops(&params.color_stops);
        if stops.is_empty() {
            return;
        }
        let start = stet_tiny_skia::Point::from_xy(params.x0 as f32, params.y0 as f32);
        let end = stet_tiny_skia::Point::from_xy(params.x1 as f32, params.y1 as f32);
        let gradient_transform =
            viewport_transform(to_transform(&params.ctm), vp_x, vp_y, scale_x, scale_y);
        let Some(gradient) = stet_tiny_skia::LinearGradient::new(
            start,
            end,
            stops,
            stet_tiny_skia::SpreadMode::Pad,
            gradient_transform,
        ) else {
            return;
        };
        let paint = Paint {
            shader: gradient,
            anti_alias: !no_aa,
            ..Paint::default()
        };

        // Use rotated BBox polygon when CTM has rotation, otherwise axis-aligned rect
        let mut poly: Vec<(f32, f32)> = if bbox_is_rotated {
            let bbox = params.bbox.as_ref().unwrap();
            let corners = [
                params.ctm.transform_point(bbox[0], bbox[1]),
                params.ctm.transform_point(bbox[2], bbox[1]),
                params.ctm.transform_point(bbox[2], bbox[3]),
                params.ctm.transform_point(bbox[0], bbox[3]),
            ];
            corners
                .iter()
                .map(|(x, y)| ((*x as f32 - vp_x) * scale_x, (*y as f32 - vp_y) * scale_y))
                .collect()
        } else {
            vec![
                (rx_min, ry_min),
                (rx_max, ry_min),
                (rx_max, ry_max),
                (rx_min, ry_max),
            ]
        };
        let ax = (dx1 - dx0) as f32 * scale_x;
        let ay = (dy1 - dy0) as f32 * scale_y;
        if !params.extend_start {
            let px = (dx0 as f32 - vp_x) * scale_x;
            let py = (dy0 as f32 - vp_y) * scale_y;
            poly = clip_polygon_halfplane(&poly, ax, ay, px, py);
        }
        if !params.extend_end {
            let px = (dx1 as f32 - vp_x) * scale_x;
            let py = (dy1 as f32 - vp_y) * scale_y;
            poly = clip_polygon_halfplane(&poly, -ax, -ay, px, py);
        }
        if poly.len() >= 3 {
            let mut pb = PathBuilder::new();
            pb.move_to(poly[0].0, poly[0].1);
            for &(x, y) in &poly[1..] {
                pb.line_to(x, y);
            }
            pb.close();
            if let Some(path) = pb.finish() {
                pixmap.fill_path(
                    &path,
                    &paint,
                    SkiaFillRule::Winding,
                    Transform::identity(),
                    clip_mask,
                );
            }
        }
    } else {
        // Common case: axis-aligned or both sides extended — direct rasterization.
        // Clip fill rect to gradient extent when sides aren't extended.
        if !params.extend_start || !params.extend_end {
            let axis_x = dx1 - dx0;
            let axis_y = dy1 - dy0;
            let gx0 = (dx0 as f32 - vp_x) * scale_x;
            let gy0 = (dy0 as f32 - vp_y) * scale_y;
            let gx1 = (dx1 as f32 - vp_x) * scale_x;
            let gy1 = (dy1 as f32 - vp_y) * scale_y;

            if axis_x.abs() >= axis_y.abs() {
                if !params.extend_start {
                    if axis_x >= 0.0 {
                        rx_min = rx_min.max(gx0);
                    } else {
                        rx_max = rx_max.min(gx0);
                    }
                }
                if !params.extend_end {
                    if axis_x >= 0.0 {
                        rx_max = rx_max.min(gx1);
                    } else {
                        rx_min = rx_min.max(gx1);
                    }
                }
            } else {
                if !params.extend_start {
                    if axis_y >= 0.0 {
                        ry_min = ry_min.max(gy0);
                    } else {
                        ry_max = ry_max.min(gy0);
                    }
                }
                if !params.extend_end {
                    if axis_y >= 0.0 {
                        ry_max = ry_max.min(gy1);
                    } else {
                        ry_min = ry_min.max(gy1);
                    }
                }
            }
            if rx_max <= rx_min || ry_max <= ry_min {
                return;
            }
        }

        // Compute gradient axis in shading space.
        let ax = params.x1 - params.x0;
        let ay = params.y1 - params.y0;
        let axis_sq = ax * ax + ay * ay;
        if axis_sq < 1e-20 {
            return;
        }

        // Size the LUT to the gradient's pixel span so each entry covers ≤1 pixel.
        // This ensures nearest-neighbor lookup produces pixel-perfect sharp edges
        // at stitching function discontinuities without banding in smooth gradients.
        let pixel_dx = (dx1 - dx0) * scale_x as f64;
        let pixel_dy = (dy1 - dy0) * scale_y as f64;
        let pixel_axis_len = (pixel_dx * pixel_dx + pixel_dy * pixel_dy).sqrt();
        let lut_size = (pixel_axis_len as usize)
            .max(params.color_stops.len())
            .max(256)
            .min(16384);
        let lut = build_gradient_lut(&params.color_stops, lut_size);

        let Some(inv) = params.ctm.invert() else {
            return;
        };
        let inv_sx = 1.0 / scale_x as f64;
        let inv_sy = 1.0 / scale_y as f64;
        let dev_origin_x = vp_x as f64;
        let dev_origin_y = vp_y as f64;

        // Shading-space coords as linear function of pixel coords:
        //   sx = sx_base + dsx_dx * px + dsx_dy * py
        //   sy = sy_base + dsy_dx * px + dsy_dy * py
        let sx_base = inv.a * dev_origin_x + inv.c * dev_origin_y + inv.tx;
        let sy_base = inv.b * dev_origin_x + inv.d * dev_origin_y + inv.ty;
        let dsx_dx = inv.a * inv_sx;
        let dsx_dy = inv.c * inv_sy;
        let dsy_dx = inv.b * inv_sx;
        let dsy_dy = inv.d * inv_sy;

        // t = dot(P_shading - P0, axis) / dot(axis, axis)
        let inv_axis_sq = 1.0 / axis_sq;
        let t_origin = ((sx_base - params.x0) * ax + (sy_base - params.y0) * ay) * inv_axis_sq;
        let dt_dx = (dsx_dx * ax + dsy_dx * ay) * inv_axis_sq;
        let dt_dy = (dsx_dy * ax + dsy_dy * ay) * inv_axis_sq;

        // Per-pixel rotated BBox clipping: reuse inverse CTM to map each pixel
        // back to shading space and check against the original BBox.
        let bbox_pixel_clip = if bbox_is_rotated {
            let bbox = params.bbox.as_ref().unwrap();
            let (bx0, bx1) = (bbox[0].min(bbox[2]), bbox[0].max(bbox[2]));
            let (by0, by1) = (bbox[1].min(bbox[3]), bbox[1].max(bbox[3]));
            Some((
                dsx_dx, dsx_dy, sx_base, dsy_dx, dsy_dy, sy_base, bx0, by0, bx1, by1,
            ))
        } else {
            None
        };

        let ix_min = rx_min.floor() as u32;
        let ix_max = rx_max.ceil().min(pw as f32) as u32;
        let iy_min = ry_min.floor() as u32;
        let iy_max = ry_max.ceil().min(ph as f32) as u32;

        let stride = pw as usize * 4;
        let data = pixmap.data_mut();
        let mask_data = clip_mask.map(|m| m.data());
        let alpha = (params.alpha.clamp(0.0, 1.0) * 255.0 + 0.5) as u16;

        for py in iy_min..iy_max {
            let t_row = t_origin + dt_dy * py as f64;
            let row_offset = py as usize * stride;

            // Precompute row-base values for rotated BBox check
            let (ux_row, uy_row) =
                if let Some((_, dux_dy, ux_base, _, duy_dy, uy_base, ..)) = &bbox_pixel_clip {
                    (ux_base + dux_dy * py as f64, uy_base + duy_dy * py as f64)
                } else {
                    (0.0, 0.0)
                };

            for px in ix_min..ix_max {
                // Check clip mask
                if let Some(md) = mask_data {
                    if md[py as usize * pw as usize + px as usize] == 0 {
                        continue;
                    }
                }

                // Per-pixel rotated BBox clip
                if let Some((dux_dx, _, _, duy_dx, _, _, bx0, by0, bx1, by1)) = &bbox_pixel_clip {
                    let ux = ux_row + dux_dx * px as f64;
                    let uy = uy_row + duy_dx * px as f64;
                    if ux < *bx0 || ux > *bx1 || uy < *by0 || uy > *by1 {
                        continue;
                    }
                }

                let t = t_row + dt_dx * px as f64;
                let t_clamped = t.clamp(0.0, 1.0);
                let idx = (t_clamped * (lut_size - 1) as f64 + 0.5) as usize;
                let [r, g, b, _] = lut[idx.min(lut_size - 1)];

                let offset = row_offset + px as usize * 4;
                if alpha >= 255 {
                    data[offset] = r;
                    data[offset + 1] = g;
                    data[offset + 2] = b;
                    data[offset + 3] = 255;
                } else {
                    // Alpha blend: premultiply and composite over existing pixel
                    let a = alpha as u16;
                    let inv_a = 255 - a;
                    data[offset] = ((r as u16 * a + data[offset] as u16 * inv_a + 127) / 255) as u8;
                    data[offset + 1] =
                        ((g as u16 * a + data[offset + 1] as u16 * inv_a + 127) / 255) as u8;
                    data[offset + 2] =
                        ((b as u16 * a + data[offset + 2] as u16 * inv_a + 127) / 255) as u8;
                    data[offset + 3] = ((a + data[offset + 3] as u16 * inv_a / 255).min(255)) as u8;
                }
            }
        }
    }

    // Update CMYK tracking buffer for axial shading
    if let Some(buf) = cmyk_buf {
        let pw = pixmap.width();
        let inv_sx = 1.0 / scale_x as f64;
        let inv_sy = 1.0 / scale_y as f64;
        let axis_x = params.x1 - params.x0;
        let axis_y = params.y1 - params.y0;
        let axis_len_sq = axis_x * axis_x + axis_y * axis_y;
        let Some(inv_ctm) = params.ctm.invert() else {
            return;
        };

        let iy_min = ry_min.floor() as u32;
        let iy_max = ry_max.ceil().min(pixmap.height() as f32) as u32;
        let ix_min = rx_min.floor() as u32;
        let ix_max = rx_max.ceil().min(pw as f32) as u32;

        for py in iy_min..iy_max {
            let dev_y = py as f64 * inv_sy + vp_y as f64;
            for px in ix_min..ix_max {
                let dev_x = px as f64 * inv_sx + vp_x as f64;
                let (ux, uy) = inv_ctm.transform_point(dev_x, dev_y);
                let t = if axis_len_sq > 1e-10 {
                    ((ux - params.x0) * axis_x + (uy - params.y0) * axis_y) / axis_len_sq
                } else {
                    0.0
                };
                if t < 0.0 && !params.extend_start {
                    continue;
                }
                if t > 1.0 && !params.extend_end {
                    continue;
                }
                let clamped = t.clamp(0.0, 1.0);

                if let Some(mask) = clip_mask {
                    let mi = py as usize * pw as usize + px as usize;
                    if mask.data()[mi] == 0 {
                        continue;
                    }
                }

                let color = interpolate_color_stops(&params.color_stops, clamped);
                let cmyk = interpolate_cmyk_from_stops(
                    &params.color_stops,
                    &params.color_space,
                    clamped,
                    &color,
                    icc,
                );
                let ci = (py as usize * pw as usize + px as usize) * 4;
                if ci + 3 < buf.len() {
                    if params.spot_tint_blend && params.overprint {
                        // Per PDF spec 11.7.4.5 a Separation/DeviceN gradient
                        // only affects the device colorants identified by its
                        // color space: plates for NAMED PROCESS colorants are
                        // REPLACED with the gradient's CMYK value at this
                        // pixel, plates not tied to a named process colorant
                        // are PRESERVED.  The LUT-painted pixmap already
                        // carries the spot's full ICC-converted color, so:
                        //
                        // Gated on `overprint` because the LUT pass for
                        // non-overprint shadings carries the author-intended
                        // blend mode (e.g. 2265.pdf draws each circle wedge
                        // twice — Normal then Multiply — and the multiplied
                        // pixmap is the wedge's final color).  Recomposing
                        // here would overwrite the multiply-darkened result
                        // with a single ICC sample of the source CMYK.
                        //   * Where the CMYK buffer is empty (fresh paper),
                        //     leave the pixmap alone — re-running CMYK→RGB
                        //     here would round-trip through the system
                        //     profile and produce a perceptibly different
                        //     gradient curve (the snowman shading regression
                        //     guarded against in the original recompose
                        //     branch).  Just record the named-process
                        //     contribution to the buffer for later overprint
                        //     tracking.
                        //   * Where the CMYK buffer has prior values (a
                        //     CMYK fill underneath, e.g. a `1 0 1 0.5 k`
                        //     checkmark under the strip), the LUT-paint had
                        //     wiped that underlying paint from the pixmap.
                        //     Recompose the pixmap from the merged CMYK
                        //     (REPLACE named, preserve non-named) to restore
                        //     the checkmark with the gradient's named-plate
                        //     contribution layered on top.
                        let cur_c = buf[ci] as f64;
                        let cur_m = buf[ci + 1] as f64;
                        let cur_y = buf[ci + 2] as f64;
                        let cur_k = buf[ci + 3] as f64;
                        let cur_is_zero =
                            cur_c == 0.0 && cur_m == 0.0 && cur_y == 0.0 && cur_k == 0.0;
                        let named = params.painted_channels;
                        if cur_is_zero {
                            if named & stet_graphics::device::CMYK_C != 0 {
                                buf[ci] = cmyk.0 as f32;
                            }
                            if named & stet_graphics::device::CMYK_M != 0 {
                                buf[ci + 1] = cmyk.1 as f32;
                            }
                            if named & stet_graphics::device::CMYK_Y != 0 {
                                buf[ci + 2] = cmyk.2 as f32;
                            }
                            if named & stet_graphics::device::CMYK_K != 0 {
                                buf[ci + 3] = cmyk.3 as f32;
                            }
                        } else {
                            let new_c = if named & stet_graphics::device::CMYK_C != 0 {
                                cmyk.0
                            } else {
                                cur_c
                            };
                            let new_m = if named & stet_graphics::device::CMYK_M != 0 {
                                cmyk.1
                            } else {
                                cur_m
                            };
                            let new_y = if named & stet_graphics::device::CMYK_Y != 0 {
                                cmyk.2
                            } else {
                                cur_y
                            };
                            let new_k = if named & stet_graphics::device::CMYK_K != 0 {
                                cmyk.3
                            } else {
                                cur_k
                            };
                            buf[ci] = new_c as f32;
                            buf[ci + 1] = new_m as f32;
                            buf[ci + 2] = new_y as f32;
                            buf[ci + 3] = new_k as f32;
                            let (rv, gv, bv) = if let Some(icc_cache) = icc {
                                icc_cache
                                    .convert_cmyk_readonly(new_c, new_m, new_y, new_k)
                                    .unwrap_or_else(|| cmyk_to_rgb_plrm(new_c, new_m, new_y, new_k))
                            } else {
                                cmyk_to_rgb_plrm(new_c, new_m, new_y, new_k)
                            };
                            let stride = pixmap.data().len() / pixmap.height() as usize;
                            let offset = py as usize * stride + px as usize * 4;
                            let data = pixmap.data_mut();
                            data[offset] = (rv * 255.0).round().clamp(0.0, 255.0) as u8;
                            data[offset + 1] = (gv * 255.0).round().clamp(0.0, 255.0) as u8;
                            data[offset + 2] = (bv * 255.0).round().clamp(0.0, 255.0) as u8;
                        }
                    } else if params.overprint
                        && params.painted_channels != stet_graphics::device::CMYK_ALL
                    {
                        if params.painted_channels & stet_graphics::device::CMYK_C != 0 {
                            buf[ci] = cmyk.0 as f32;
                        }
                        if params.painted_channels & stet_graphics::device::CMYK_M != 0 {
                            buf[ci + 1] = cmyk.1 as f32;
                        }
                        if params.painted_channels & stet_graphics::device::CMYK_Y != 0 {
                            buf[ci + 2] = cmyk.2 as f32;
                        }
                        if params.painted_channels & stet_graphics::device::CMYK_K != 0 {
                            buf[ci + 3] = cmyk.3 as f32;
                        }
                        // Recomposite RGB from merged CMYK via ICC
                        let c = buf[ci] as f64;
                        let m = buf[ci + 1] as f64;
                        let y = buf[ci + 2] as f64;
                        let k = buf[ci + 3] as f64;
                        let (rv, gv, bv) = if let Some(icc_cache) = icc {
                            icc_cache
                                .convert_cmyk_readonly(c, m, y, k)
                                .unwrap_or_else(|| cmyk_to_rgb_plrm(c, m, y, k))
                        } else {
                            cmyk_to_rgb_plrm(c, m, y, k)
                        };
                        let stride = pixmap.data().len() / pixmap.height() as usize;
                        let offset = py as usize * stride + px as usize * 4;
                        let data = pixmap.data_mut();
                        data[offset] = (rv * 255.0).round().clamp(0.0, 255.0) as u8;
                        data[offset + 1] = (gv * 255.0).round().clamp(0.0, 255.0) as u8;
                        data[offset + 2] = (bv * 255.0).round().clamp(0.0, 255.0) as u8;
                    } else {
                        // Non-overprint axial shading: write the source CMYK
                        // to the buffer for any consumer that needs it (e.g.
                        // overprint sibling tracking) but leave the pixmap
                        // alone — `build_gradient_lut` already painted the
                        // pixel with linearly-interpolated source RGB, and
                        // round-tripping CMYK→RGB through the ICC profile
                        // produces a different gradient curve (linear in
                        // CMYK rather than linear in RGB) that diverges
                        // visibly from the LUT result. The CMYK buffer is
                        // only consumed by `composite_non_isolated_cmyk`,
                        // which excludes shading-containing groups via
                        // `group_content_is_native_cmyk`, so the
                        // buffer/pixmap mismatch never reaches a consumer
                        // that would notice. Reintroducing the round-trip
                        // here was the 3000_9 / 3000_10 snowman shading
                        // regression in the silly-weaving-bird plan.
                        buf[ci] = cmyk.0 as f32;
                        buf[ci + 1] = cmyk.1 as f32;
                        buf[ci + 2] = cmyk.2 as f32;
                        buf[ci + 3] = cmyk.3 as f32;
                    }
                }
            }
        }
    }
}

/// Render a radial gradient shading.
#[allow(clippy::too_many_arguments)]
fn render_radial_shading(
    pixmap: &mut Pixmap,
    params: &RadialShadingParams,
    vp_x: f32,
    vp_y: f32,
    scale_x: f32,
    scale_y: f32,
    clip_mask: Option<&Mask>,
    _no_aa: bool,
    mut cmyk_buf: Option<&mut [f32]>,
    icc: Option<&IccCache>,
) {
    let pw = pixmap.width();
    let ph = pixmap.height();
    if params.color_stops.is_empty() || pw == 0 || ph == 0 {
        return;
    }

    let Some(inv_ctm) = params.ctm.invert() else {
        return;
    };

    let (px_min, py_min, px_max, py_max) = if let Some(bbox) = &params.bbox {
        let corners = [
            params.ctm.transform_point(bbox[0], bbox[1]),
            params.ctm.transform_point(bbox[2], bbox[1]),
            params.ctm.transform_point(bbox[0], bbox[3]),
            params.ctm.transform_point(bbox[2], bbox[3]),
        ];
        let x_min = corners
            .iter()
            .map(|c| c.0 as f32)
            .fold(f32::INFINITY, f32::min);
        let y_min = corners
            .iter()
            .map(|c| c.1 as f32)
            .fold(f32::INFINITY, f32::min);
        let x_max = corners
            .iter()
            .map(|c| c.0 as f32)
            .fold(f32::NEG_INFINITY, f32::max);
        let y_max = corners
            .iter()
            .map(|c| c.1 as f32)
            .fold(f32::NEG_INFINITY, f32::max);
        (
            ((x_min - vp_x) * scale_x).max(0.0) as u32,
            ((y_min - vp_y) * scale_y).max(0.0) as u32,
            (((x_max - vp_x) * scale_x).ceil() as u32).min(pw),
            (((y_max - vp_y) * scale_y).ceil() as u32).min(ph),
        )
    } else {
        (0, 0, pw, ph)
    };

    let inv_sx = 1.0 / scale_x as f64;
    let inv_sy = 1.0 / scale_y as f64;

    // Rotated BBox: check per-pixel user-space containment
    let rotated_bbox = if let Some(bbox) = &params.bbox {
        if params.ctm.b.abs() > 1e-10 || params.ctm.c.abs() > 1e-10 {
            let (bx0, bx1) = (bbox[0].min(bbox[2]), bbox[0].max(bbox[2]));
            let (by0, by1) = (bbox[1].min(bbox[3]), bbox[1].max(bbox[3]));
            Some((bx0, by0, bx1, by1))
        } else {
            None
        }
    } else {
        None
    };

    let data = pixmap.data_mut();
    let stride = pw as usize * 4;

    for py in py_min..py_max {
        let dev_y = py as f64 * inv_sy + vp_y as f64;
        for px in px_min..px_max {
            let dev_x = px as f64 * inv_sx + vp_x as f64;
            let (ux, uy) = inv_ctm.transform_point(dev_x, dev_y);

            // Per-pixel rotated BBox clip
            if let Some((bx0, by0, bx1, by1)) = rotated_bbox {
                if ux < bx0 || ux > bx1 || uy < by0 || uy > by1 {
                    continue;
                }
            }

            let t = solve_radial_t(
                ux,
                uy,
                params.x0,
                params.y0,
                params.r0,
                params.x1,
                params.y1,
                params.r1,
                params.extend_start,
                params.extend_end,
            );
            if let Some(t) = t {
                let clamped = t.clamp(0.0, 1.0);
                let color = interpolate_color_stops(&params.color_stops, clamped);

                let clipped = clip_mask
                    .is_some_and(|mask| mask.data()[py as usize * pw as usize + px as usize] == 0);

                if clipped {
                    continue;
                }

                // Decide whether this pixel should use the multiplicative
                // ink-stacking blend to preserve a spot backdrop. We mirror
                // the rule in `render_overprint_fill`: overprint + subset
                // painted channels + buffer effectively empty at this pixel
                // means the pixmap carries a non-CMYK contribution (or the
                // pixel is fresh), so per-channel ink-stacking gives the
                // correct result whether the backdrop was spot-painted or
                // plain.
                let cmyk = interpolate_cmyk_from_stops(
                    &params.color_stops,
                    &params.color_space,
                    clamped,
                    &color,
                    icc,
                );
                let ci = (py as usize * pw as usize + px as usize) * 4;
                let buffer_clean = if let Some(ref buf) = cmyk_buf {
                    if ci + 3 < buf.len() {
                        buf[ci] == 0.0
                            && buf[ci + 1] == 0.0
                            && buf[ci + 2] == 0.0
                            && buf[ci + 3] == 0.0
                    } else {
                        false
                    }
                } else {
                    false
                };
                let offset_for_check = py as usize * stride + px as usize * 4;
                let pixmap_has_colour = data[offset_for_check + 3] > 0
                    && (data[offset_for_check] < 250
                        || data[offset_for_check + 1] < 250
                        || data[offset_for_check + 2] < 250);
                let use_multiplicative = params.overprint
                    && params.painted_channels != stet_graphics::device::CMYK_ALL
                    && buffer_clean
                    && pixmap_has_colour;

                // Write CMYK buffer at non-clipped pixels
                if let Some(ref mut buf) = cmyk_buf
                    && ci + 3 < buf.len()
                {
                    if params.overprint
                        && params.painted_channels != stet_graphics::device::CMYK_ALL
                    {
                        if params.painted_channels & stet_graphics::device::CMYK_C != 0 {
                            buf[ci] = cmyk.0 as f32;
                        }
                        if params.painted_channels & stet_graphics::device::CMYK_M != 0 {
                            buf[ci + 1] = cmyk.1 as f32;
                        }
                        if params.painted_channels & stet_graphics::device::CMYK_Y != 0 {
                            buf[ci + 2] = cmyk.2 as f32;
                        }
                        if params.painted_channels & stet_graphics::device::CMYK_K != 0 {
                            buf[ci + 3] = cmyk.3 as f32;
                        }
                    } else {
                        buf[ci] = cmyk.0 as f32;
                        buf[ci + 1] = cmyk.1 as f32;
                        buf[ci + 2] = cmyk.2 as f32;
                        buf[ci + 3] = cmyk.3 as f32;
                    }
                }

                let offset = py as usize * stride + px as usize * 4;
                if use_multiplicative {
                    // Ink-stack the per-stop CMYK onto the pixmap RGB. Only
                    // channels named by painted_channels contribute; others
                    // leave the pixmap untouched, so a spot-painted backdrop
                    // survives with just the named inks darkening it.
                    let bg_r = data[offset] as f64 / 255.0;
                    let bg_g = data[offset + 1] as f64 / 255.0;
                    let bg_b = data[offset + 2] as f64 / 255.0;
                    let over_r = if params.painted_channels & stet_graphics::device::CMYK_C != 0 {
                        1.0 - cmyk.0
                    } else {
                        1.0
                    };
                    let over_g = if params.painted_channels & stet_graphics::device::CMYK_M != 0 {
                        1.0 - cmyk.1
                    } else {
                        1.0
                    };
                    let over_b = if params.painted_channels & stet_graphics::device::CMYK_Y != 0 {
                        1.0 - cmyk.2
                    } else {
                        1.0
                    };
                    let k_fac = if params.painted_channels & stet_graphics::device::CMYK_K != 0 {
                        1.0 - cmyk.3
                    } else {
                        1.0
                    };
                    data[offset] = ((bg_r * over_r * k_fac).clamp(0.0, 1.0) * 255.0).round() as u8;
                    data[offset + 1] =
                        ((bg_g * over_g * k_fac).clamp(0.0, 1.0) * 255.0).round() as u8;
                    data[offset + 2] =
                        ((bg_b * over_b * k_fac).clamp(0.0, 1.0) * 255.0).round() as u8;
                    data[offset + 3] = 255;
                } else {
                    data[offset] = (color.r * 255.0).round().clamp(0.0, 255.0) as u8;
                    data[offset + 1] = (color.g * 255.0).round().clamp(0.0, 255.0) as u8;
                    data[offset + 2] = (color.b * 255.0).round().clamp(0.0, 255.0) as u8;
                    data[offset + 3] = 255;

                    // Recomposite RGB from the CMYK buffer via ICC only for
                    // overprint DeviceCMYK shadings on a CMYK-only backdrop,
                    // where the per-channel merge in the buffer means the
                    // displayed pixel must reflect the merged CMYK rather
                    // than the source's RGB. For non-overprint shadings the
                    // LUT-rendered pixmap (above) is already correct, and
                    // round-tripping CMYK→RGB through the ICC profile
                    // produces a different gradient curve (linear in CMYK
                    // rather than linear in RGB) — that drift was the
                    // 3000_9 / 3000_10 snowman shading regression. The CMYK
                    // buffer is only consumed by `composite_non_isolated_cmyk`,
                    // which excludes shading-containing groups via
                    // `group_content_is_native_cmyk`, so the buffer/pixmap
                    // mismatch never reaches a consumer that would notice.
                    if params.overprint
                        && params.painted_channels != stet_graphics::device::CMYK_ALL
                        && matches!(
                            params.color_space,
                            ShadingColorSpace::DeviceCMYK
                                | ShadingColorSpace::Separation { .. }
                                | ShadingColorSpace::DeviceN { .. }
                        )
                        && let Some(ref mut buf) = cmyk_buf
                        && ci + 3 < buf.len()
                        && let Some(icc_cache) = icc
                    {
                        let c = buf[ci] as f64;
                        let m = buf[ci + 1] as f64;
                        let y = buf[ci + 2] as f64;
                        let k = buf[ci + 3] as f64;
                        if let Some((r, g, b)) = icc_cache.convert_cmyk_readonly(c, m, y, k) {
                            data[offset] = (r * 255.0).round().clamp(0.0, 255.0) as u8;
                            data[offset + 1] = (g * 255.0).round().clamp(0.0, 255.0) as u8;
                            data[offset + 2] = (b * 255.0).round().clamp(0.0, 255.0) as u8;
                        }
                    }
                }
            }
        }
    }
}
/// Solve for the parameter t of a two-circle radial gradient at point (px, py).
///
/// Returns the largest root of the circle equation that falls within the valid
/// domain and has R(t) >= 0. The valid domain is [0,1], extended by extend flags.
#[allow(clippy::too_many_arguments)]
fn solve_radial_t(
    px: f64,
    py: f64,
    x0: f64,
    y0: f64,
    r0: f64,
    x1: f64,
    y1: f64,
    r1: f64,
    extend_start: bool,
    extend_end: bool,
) -> Option<f64> {
    // Parametric: C(t) = (1-t)*C0 + t*C1, R(t) = (1-t)*r0 + t*r1
    // Solve: (px - Cx(t))^2 + (py - Cy(t))^2 = R(t)^2
    let cdx = x1 - x0;
    let cdy = y1 - y0;
    let dr = r1 - r0;

    let a = cdx * cdx + cdy * cdy - dr * dr;
    let dpx = px - x0;
    let dpy = py - y0;
    let b = -2.0 * (dpx * cdx + dpy * cdy + r0 * dr);
    let c = dpx * dpx + dpy * dpy - r0 * r0;

    // Helper: check if a root is in the valid domain
    let in_domain = |t: f64| -> bool {
        (0.0..=1.0).contains(&t) || (t < 0.0 && extend_start) || (t > 1.0 && extend_end)
    };

    if a.abs() < 1e-10 {
        // Linear case
        if b.abs() < 1e-10 {
            return None;
        }
        let t = -c / b;
        let radius = r0 + t * dr;
        if radius >= 0.0 && in_domain(t) {
            return Some(t);
        }
        return None;
    }

    let discriminant = b * b - 4.0 * a * c;
    if discriminant < 0.0 {
        return None;
    }
    let sqrt_d = discriminant.sqrt();
    let t1 = (-b + sqrt_d) / (2.0 * a);
    let t2 = (-b - sqrt_d) / (2.0 * a);

    // Pick the largest root that is in the valid domain and has R(t) >= 0
    let mut best: Option<f64> = None;
    for t in [t1, t2] {
        let radius = r0 + t * dr;
        if radius >= 0.0 && in_domain(t) {
            best = Some(match best {
                Some(prev) => prev.max(t),
                None => t,
            });
        }
    }
    best
}

/// Render a Gouraud-shaded triangle mesh.
#[allow(clippy::too_many_arguments)]
fn render_mesh_shading(
    pixmap: &mut Pixmap,
    params: &MeshShadingParams,
    vp_x: f32,
    vp_y: f32,
    scale_x: f32,
    scale_y: f32,
    clip_mask: Option<&Mask>,
    mut cmyk_buf: Option<&mut [f32]>,
    icc: Option<&IccCache>,
) {
    let pw = pixmap.width() as usize;
    let ph = pixmap.height() as usize;
    if pw == 0 || ph == 0 {
        return;
    }
    let data = pixmap.data_mut();
    let stride = pw * 4;

    let lut = params.color_lut.as_deref();

    for tri in &params.triangles {
        let (dx0, dy0) = params.ctm.transform_point(tri.v0.x, tri.v0.y);
        let (dx1, dy1) = params.ctm.transform_point(tri.v1.x, tri.v1.y);
        let (dx2, dy2) = params.ctm.transform_point(tri.v2.x, tri.v2.y);

        let x0 = (dx0 as f32 - vp_x) * scale_x;
        let y0 = (dy0 as f32 - vp_y) * scale_y;
        let x1 = (dx1 as f32 - vp_x) * scale_x;
        let y1 = (dy1 as f32 - vp_y) * scale_y;
        let x2 = (dx2 as f32 - vp_x) * scale_x;
        let y2 = (dy2 as f32 - vp_y) * scale_y;

        let min_x = (x0.min(x1).min(x2).floor().max(0.0)) as usize;
        let max_x = (x0.max(x1).max(x2).ceil() as usize).min(pw);
        let min_y = (y0.min(y1).min(y2).floor().max(0.0)) as usize;
        let max_y = (y0.max(y1).max(y2).ceil() as usize).min(ph);

        if min_x >= max_x || min_y >= max_y {
            continue;
        }

        let x0 = x0 as f64;
        let y0 = y0 as f64;
        let x1 = x1 as f64;
        let y1 = y1 as f64;
        let x2 = x2 as f64;
        let y2 = y2 as f64;
        // Swap vertices 1 and 2 when the triangle has reversed winding
        // (from a CTM with negative determinant, e.g. X- or Y-flip).
        // This ensures barycentric coordinates stay positive for interior
        // points regardless of the CTM orientation.
        let denom = (y1 - y2) * (x0 - x2) + (x2 - x1) * (y0 - y2);
        if denom.abs() < 1e-10 {
            continue;
        }
        let (x1, y1, x2, y2) = if denom < 0.0 {
            (x2, y2, x1, y1)
        } else {
            (x1, y1, x2, y2)
        };
        let (v1_ref, v2_ref) = if denom < 0.0 {
            (&tri.v2, &tri.v1)
        } else {
            (&tri.v1, &tri.v2)
        };
        let denom = denom.abs();
        let inv_denom = 1.0 / denom;

        for py in min_y..max_y {
            for px in min_x..max_x {
                let pxf = px as f64 + 0.5;
                let pyf = py as f64 + 0.5;

                let w0 = ((y1 - y2) * (pxf - x2) + (x2 - x1) * (pyf - y2)) * inv_denom;
                let w1 = ((y2 - y0) * (pxf - x2) + (x0 - x2) * (pyf - y2)) * inv_denom;
                let w2 = 1.0 - w0 - w1;

                if w0 < 0.0 || w1 < 0.0 || w2 < 0.0 {
                    continue;
                }

                let clipped = clip_mask.is_some_and(|mask| mask.data()[py * pw + px] == 0);

                let w0c = w0.max(0.0);
                let w1c = w1.max(0.0);
                let w2c = w2.max(0.0);
                let wsum = w0c + w1c + w2c;
                let w0n = w0c / wsum;
                let w1n = w1c / wsum;
                let w2n = w2c / wsum;

                // Per-pixel color: either LUT lookup (for function-based meshes)
                // or direct Gouraud interpolation of vertex DeviceColors.
                let (r, g, b) = if let Some(lut) = lut {
                    // Interpolate raw function input values per-pixel
                    let raw = w0n * tri.v0.raw_components[0]
                        + w1n * v1_ref.raw_components[0]
                        + w2n * v2_ref.raw_components[0];
                    let raw = raw.clamp(0.0, 1.0);
                    // Linear interpolation in the LUT
                    let fi = raw * (lut.len() - 1) as f64;
                    let i0 = (fi as usize).min(lut.len().saturating_sub(2));
                    let frac = fi - i0 as f64;
                    let c0 = &lut[i0];
                    let c1 = &lut[i0 + 1];
                    (
                        c0.r + frac * (c1.r - c0.r),
                        c0.g + frac * (c1.g - c0.g),
                        c0.b + frac * (c1.b - c0.b),
                    )
                } else {
                    (
                        w0n * tri.v0.color.r + w1n * v1_ref.color.r + w2n * v2_ref.color.r,
                        w0n * tri.v0.color.g + w1n * v1_ref.color.g + w2n * v2_ref.color.g,
                        w0n * tri.v0.color.b + w1n * v1_ref.color.b + w2n * v2_ref.color.b,
                    )
                };

                // Write CMYK buffer
                if let Some(ref mut buf) = cmyk_buf {
                    let ci = (py * pw + px) * 4;
                    if ci + 3 < buf.len() {
                        let cmyk = interpolate_cmyk_from_vertices(
                            &tri.v0,
                            v1_ref,
                            v2_ref,
                            w0n,
                            w1n,
                            w2n,
                            &params.color_space,
                            r,
                            g,
                            b,
                            icc,
                        );
                        if params.overprint
                            && params.painted_channels != stet_graphics::device::CMYK_ALL
                        {
                            if !clipped {
                                if params.painted_channels & stet_graphics::device::CMYK_C != 0 {
                                    buf[ci] = cmyk.0 as f32;
                                }
                                if params.painted_channels & stet_graphics::device::CMYK_M != 0 {
                                    buf[ci + 1] = cmyk.1 as f32;
                                }
                                if params.painted_channels & stet_graphics::device::CMYK_Y != 0 {
                                    buf[ci + 2] = cmyk.2 as f32;
                                }
                                if params.painted_channels & stet_graphics::device::CMYK_K != 0 {
                                    buf[ci + 3] = cmyk.3 as f32;
                                }
                            }
                        } else {
                            buf[ci] = cmyk.0 as f32;
                            buf[ci + 1] = cmyk.1 as f32;
                            buf[ci + 2] = cmyk.2 as f32;
                            buf[ci + 3] = cmyk.3 as f32;
                        }
                    }
                }

                if clipped {
                    continue;
                }

                let offset = py * stride + px * 4;
                data[offset] = (r * 255.0).round().clamp(0.0, 255.0) as u8;
                data[offset + 1] = (g * 255.0).round().clamp(0.0, 255.0) as u8;
                data[offset + 2] = (b * 255.0).round().clamp(0.0, 255.0) as u8;
                data[offset + 3] = 255;
            }
        }
    }
}

/// Render a Coons/tensor-product patch mesh by subdividing into triangles.
#[allow(clippy::too_many_arguments)]
fn render_patch_shading(
    pixmap: &mut Pixmap,
    params: &PatchShadingParams,
    vp_x: f32,
    vp_y: f32,
    scale_x: f32,
    scale_y: f32,
    clip_mask: Option<&Mask>,
    cmyk_buf: Option<&mut [f32]>,
    icc: Option<&IccCache>,
) {
    let mut triangles = Vec::new();
    let scale = scale_x.max(scale_y) as f64;
    for patch in &params.patches {
        if patch.points.len() >= 12 {
            // Compute device-space extent to choose subdivision level
            let mut x_min = f64::INFINITY;
            let mut y_min = f64::INFINITY;
            let mut x_max = f64::NEG_INFINITY;
            let mut y_max = f64::NEG_INFINITY;
            for &(px, py) in &patch.points {
                let (dx, dy) = params.ctm.transform_point(px, py);
                x_min = x_min.min(dx);
                y_min = y_min.min(dy);
                x_max = x_max.max(dx);
                y_max = y_max.max(dy);
            }
            let extent = (x_max - x_min).max(y_max - y_min).abs() * scale;
            // Target ~2 device pixels per boundary segment
            let n = (extent / 2.0).ceil().clamp(8.0, 64.0) as usize;
            // Extract ICC profile hash for per-grid-point color conversion
            let icc_profile_hash = match &params.color_space {
                stet_graphics::device::ShadingColorSpace::ICCBased { profile_hash, .. } => {
                    Some(profile_hash)
                }
                _ => None,
            };
            subdivide_patch_to_triangles(patch, &mut triangles, n, icc_profile_hash, icc);
        }
    }
    if !triangles.is_empty() {
        let mesh_params = MeshShadingParams {
            triangles,
            ctm: params.ctm,
            bbox: params.bbox,
            color_space: params.color_space.clone(),
            overprint: params.overprint,
            overprint_mode: params.overprint_mode,
            painted_channels: params.painted_channels,
            color_lut: params.color_lut.clone(),
            alpha: params.alpha,
            blend_mode: params.blend_mode,
            alpha_is_shape: params.alpha_is_shape,
        };
        render_mesh_shading(
            pixmap,
            &mesh_params,
            vp_x,
            vp_y,
            scale_x,
            scale_y,
            clip_mask,
            cmyk_buf,
            icc,
        );
    }
}
/// Subdivide a Coons/tensor patch into triangles via grid subdivision.
/// Evaluates the patch at NxN points and triangulates the resulting grid.
/// When an ICC profile hash and cache are provided, interpolates colors in the
/// source ICC color space and converts per-grid-point for accurate rendering.
fn subdivide_patch_to_triangles(
    patch: &stet_graphics::device::ShadingPatch,
    triangles: &mut Vec<stet_graphics::device::ShadingTriangle>,
    n: usize,
    icc_profile_hash: Option<&stet_graphics::icc::ProfileHash>,
    icc_cache: Option<&IccCache>,
) {
    // Evaluate patch at grid points.
    // Use tensor-product evaluation when 16 control points are available (Type 7),
    // otherwise fall back to Coons blending (Type 6, 12 points).
    let mut grid: Vec<(f64, f64, DeviceColor, Vec<f64>)> = Vec::with_capacity((n + 1) * (n + 1));
    let use_tensor = patch.points.len() >= 16;
    let has_raw = !patch.raw_colors[0].is_empty();
    // Use per-grid-point ICC conversion when profile info is available
    let use_icc_interp = has_raw && icc_profile_hash.is_some() && icc_cache.is_some();

    for row in 0..=n {
        let v = row as f64 / n as f64;
        for col in 0..=n {
            let u = col as f64 / n as f64;
            let (x, y) = if use_tensor {
                eval_tensor_patch(patch, u, v)
            } else {
                eval_coons_patch(patch, u, v)
            };
            let raw = if has_raw {
                bilinear_raw(&patch.raw_colors, u, v)
            } else {
                vec![]
            };
            // When ICC profile is available, convert the interpolated raw
            // components at each grid point for accurate color rendering.
            // This interpolates in the source color space (e.g. ProPhoto RGB)
            // and converts per-grid-point, rather than interpolating pre-converted
            // sRGB values from only the 4 corners.
            let color = if use_icc_interp {
                if let Some((r, g, b)) = icc_cache
                    .unwrap()
                    .convert_color_readonly(icc_profile_hash.unwrap(), &raw)
                {
                    DeviceColor::from_rgb(r, g, b)
                } else {
                    bilinear_color(&patch.colors, u, v)
                }
            } else {
                bilinear_color(&patch.colors, u, v)
            };
            grid.push((x, y, color, raw));
        }
    }

    // Triangulate grid
    let cols = n + 1;
    for row in 0..n {
        for col in 0..n {
            let i00 = row * cols + col;
            let i10 = i00 + 1;
            let i01 = i00 + cols;
            let i11 = i01 + 1;

            let (x00, y00, c00, r00) = &grid[i00];
            let (x10, y10, c10, r10) = &grid[i10];
            let (x01, y01, c01, r01) = &grid[i01];
            let (x11, y11, c11, r11) = &grid[i11];

            use stet_graphics::device::ShadingVertex;
            triangles.push(stet_graphics::device::ShadingTriangle {
                v0: ShadingVertex {
                    x: *x00,
                    y: *y00,
                    color: c00.clone(),
                    raw_components: r00.clone(),
                },
                v1: ShadingVertex {
                    x: *x10,
                    y: *y10,
                    color: c10.clone(),
                    raw_components: r10.clone(),
                },
                v2: ShadingVertex {
                    x: *x01,
                    y: *y01,
                    color: c01.clone(),
                    raw_components: r01.clone(),
                },
            });
            triangles.push(stet_graphics::device::ShadingTriangle {
                v0: ShadingVertex {
                    x: *x10,
                    y: *y10,
                    color: c10.clone(),
                    raw_components: r10.clone(),
                },
                v1: ShadingVertex {
                    x: *x11,
                    y: *y11,
                    color: c11.clone(),
                    raw_components: r11.clone(),
                },
                v2: ShadingVertex {
                    x: *x01,
                    y: *y01,
                    color: c01.clone(),
                    raw_components: r01.clone(),
                },
            });
        }
    }
}

/// Evaluate a Coons patch at parameter (u, v).
/// The 12 control points define 4 cubic Bezier boundary curves.
fn eval_coons_patch(patch: &stet_graphics::device::ShadingPatch, u: f64, v: f64) -> (f64, f64) {
    let pts = &patch.points;
    if pts.len() < 12 {
        return (0.0, 0.0);
    }

    // Side 0 (bottom): pts[0..4], u goes 0→1
    // Side 1 (right): pts[3..7], v goes 0→1
    // Side 2 (top): pts[6..10], u goes 1→0 (reversed)
    // Side 3 (left): pts[9..12] + pts[0], v goes 1→0 (reversed)
    let c0 = eval_cubic_bezier(pts[0], pts[1], pts[2], pts[3], u);
    let c2 = eval_cubic_bezier(pts[6], pts[7], pts[8], pts[9], 1.0 - u);
    let d0 = eval_cubic_bezier(pts[0], pts[11], pts[10], pts[9], v);
    let d1 = eval_cubic_bezier(pts[3], pts[4], pts[5], pts[6], v);

    // Bilinear blending of corners
    let p00 = pts[0];
    let p10 = pts[3];
    let p01 = pts[9];
    let p11 = pts[6];
    let bx = (1.0 - u) * (1.0 - v) * p00.0
        + u * (1.0 - v) * p10.0
        + (1.0 - u) * v * p01.0
        + u * v * p11.0;
    let by = (1.0 - u) * (1.0 - v) * p00.1
        + u * (1.0 - v) * p10.1
        + (1.0 - u) * v * p01.1
        + u * v * p11.1;

    // Coons blending: S(u,v) = c(u,v) + d(u,v) - B(u,v)
    let x = (1.0 - v) * c0.0 + v * c2.0 + (1.0 - u) * d0.0 + u * d1.0 - bx;
    let y = (1.0 - v) * c0.1 + v * c2.1 + (1.0 - u) * d0.1 + u * d1.1 - by;

    (x, y)
}

/// Evaluate a Type 7 tensor-product patch at parameter (u, v).
///
/// Uses 16 control points arranged in a 4×4 grid, evaluated as a bicubic
/// Bernstein surface: S(u,v) = ΣΣ B_i(u) * B_j(v) * P_ij
///
/// PDF spec (ISO 32000, Table 85) data ordering for flag=0:
///   p₁₁ p₁₂ p₁₃ p₁₄  p₂₁ p₂₂ p₂₃ p₂₄  p₃₁ p₃₂ p₃₃ p₃₄  p₄₁ p₄₂ p₄₃ p₄₄
///
/// In the grid (Figure 86), column index = u direction, row index = v direction:
///   grid[v=0][u] = p₁₁, p₂₁, p₃₁, p₄₁  = pts[0], pts[4], pts[8],  pts[12]
///   grid[v=⅓][u] = p₁₂, p₂₂, p₃₂, p₄₂  = pts[1], pts[5], pts[9],  pts[13]
///   grid[v=⅔][u] = p₁₃, p₂₃, p₃₃, p₄₃  = pts[2], pts[6], pts[10], pts[14]
///   grid[v=1][u] = p₁₄, p₂₄, p₃₄, p₄₄  = pts[3], pts[7], pts[11], pts[15]
fn eval_tensor_patch(patch: &stet_graphics::device::ShadingPatch, u: f64, v: f64) -> (f64, f64) {
    let pts = &patch.points;

    // Map data indices to 4×4 grid [row][col].
    // pts[0..12] are boundary points around the perimeter (same as Type 6).
    // pts[12..16] are the 4 interior control points.
    let grid: [[usize; 4]; 4] = [[0, 1, 2, 3], [11, 12, 13, 4], [10, 15, 14, 5], [9, 8, 7, 6]];

    // Cubic Bernstein basis values
    let su = 1.0 - u;
    let bu = [su * su * su, 3.0 * su * su * u, 3.0 * su * u * u, u * u * u];
    let sv = 1.0 - v;
    let bv = [sv * sv * sv, 3.0 * sv * sv * v, 3.0 * sv * v * v, v * v * v];

    let mut x = 0.0;
    let mut y = 0.0;
    for j in 0..4 {
        for i in 0..4 {
            let w = bu[i] * bv[j];
            let p = pts[grid[j][i]];
            x += w * p.0;
            y += w * p.1;
        }
    }
    (x, y)
}

/// Evaluate a cubic Bezier curve at parameter t.
fn eval_cubic_bezier(
    p0: (f64, f64),
    p1: (f64, f64),
    p2: (f64, f64),
    p3: (f64, f64),
    t: f64,
) -> (f64, f64) {
    let s = 1.0 - t;
    let s2 = s * s;
    let t2 = t * t;
    let b0 = s2 * s;
    let b1 = 3.0 * s2 * t;
    let b2 = 3.0 * s * t2;
    let b3 = t2 * t;
    (
        b0 * p0.0 + b1 * p1.0 + b2 * p2.0 + b3 * p3.0,
        b0 * p0.1 + b1 * p1.1 + b2 * p2.1 + b3 * p3.1,
    )
}

/// Bilinear color interpolation across patch corners.
fn bilinear_color(colors: &[DeviceColor; 4], u: f64, v: f64) -> DeviceColor {
    let r = (1.0 - u) * (1.0 - v) * colors[0].r
        + u * (1.0 - v) * colors[1].r
        + (1.0 - u) * v * colors[3].r
        + u * v * colors[2].r;
    let g = (1.0 - u) * (1.0 - v) * colors[0].g
        + u * (1.0 - v) * colors[1].g
        + (1.0 - u) * v * colors[3].g
        + u * v * colors[2].g;
    let b = (1.0 - u) * (1.0 - v) * colors[0].b
        + u * (1.0 - v) * colors[1].b
        + (1.0 - u) * v * colors[3].b
        + u * v * colors[2].b;
    DeviceColor::from_rgb(r.clamp(0.0, 1.0), g.clamp(0.0, 1.0), b.clamp(0.0, 1.0))
}

/// Bilinear interpolation of raw color components across patch corners.
fn bilinear_raw(raw_colors: &[Vec<f64>; 4], u: f64, v: f64) -> Vec<f64> {
    let n = raw_colors[0].len();
    let mut result = vec![0.0; n];
    for i in 0..n {
        result[i] = (1.0 - u) * (1.0 - v) * raw_colors[0][i]
            + u * (1.0 - v) * raw_colors[1][i]
            + (1.0 - u) * v * raw_colors[3][i]
            + u * v * raw_colors[2][i];
    }
    result
}

/// Pre-rasterize color stops into a 256-entry RGBA lookup table.
///
/// Each entry is linearly interpolated from the color stops. Used by the
/// direct-rasterization axial shading path to replace per-pixel stop search
/// with a single array lookup.
fn build_gradient_lut(stops: &[stet_graphics::device::ColorStop], size: usize) -> Vec<[u8; 4]> {
    let size = size.max(2);
    let mut lut = vec![[0u8; 4]; size];
    if stops.is_empty() {
        return lut;
    }
    let mut si = 0usize; // current stop index
    let last = (size - 1) as f64;
    for i in 0..size {
        let t = i as f64 / last;
        // Advance stop index
        while si + 1 < stops.len() && stops[si + 1].position < t {
            si += 1;
        }
        let (r, g, b) = if si + 1 >= stops.len() {
            let c = &stops[stops.len() - 1].color;
            (c.r, c.g, c.b)
        } else if t <= stops[si].position {
            let c = &stops[si].color;
            (c.r, c.g, c.b)
        } else {
            let t0 = stops[si].position;
            let t1 = stops[si + 1].position;
            let frac = if (t1 - t0).abs() < 1e-10 {
                0.0
            } else {
                (t - t0) / (t1 - t0)
            };
            let c0 = &stops[si].color;
            let c1 = &stops[si + 1].color;
            (
                c0.r + frac * (c1.r - c0.r),
                c0.g + frac * (c1.g - c0.g),
                c0.b + frac * (c1.b - c0.b),
            )
        };
        lut[i] = [
            (r * 255.0).round().clamp(0.0, 255.0) as u8,
            (g * 255.0).round().clamp(0.0, 255.0) as u8,
            (b * 255.0).round().clamp(0.0, 255.0) as u8,
            255,
        ];
    }
    lut
}

/// Build tiny-skia gradient stops from color stops.
fn build_gradient_stops(
    stops: &[stet_graphics::device::ColorStop],
) -> Vec<stet_tiny_skia::GradientStop> {
    let mut result = Vec::with_capacity(stops.len());
    for stop in stops {
        let r = (stop.color.r * 255.0).round().clamp(0.0, 255.0) as u8;
        let g = (stop.color.g * 255.0).round().clamp(0.0, 255.0) as u8;
        let b = (stop.color.b * 255.0).round().clamp(0.0, 255.0) as u8;
        result.push(stet_tiny_skia::GradientStop::new(
            stop.position as f32,
            Color::from_rgba8(r, g, b, 255),
        ));
    }
    result
}

/// Interpolate between color stops at a given position (0.0..=1.0).
fn interpolate_color_stops(
    stops: &[stet_graphics::device::ColorStop],
    position: f64,
) -> DeviceColor {
    if stops.is_empty() {
        return DeviceColor::from_gray(0.0);
    }
    if stops.len() == 1 || position <= stops[0].position {
        return stops[0].color.clone();
    }
    if position >= stops.last().unwrap().position {
        return stops.last().unwrap().color.clone();
    }

    // Find the two stops bracketing this position
    for i in 1..stops.len() {
        if position <= stops[i].position {
            let t0 = stops[i - 1].position;
            let t1 = stops[i].position;
            let frac = if (t1 - t0).abs() < 1e-10 {
                0.0
            } else {
                (position - t0) / (t1 - t0)
            };
            let c0 = &stops[i - 1].color;
            let c1 = &stops[i].color;
            return DeviceColor::from_rgb(
                (c0.r + frac * (c1.r - c0.r)).clamp(0.0, 1.0),
                (c0.g + frac * (c1.g - c0.g)).clamp(0.0, 1.0),
                (c0.b + frac * (c1.b - c0.b)).clamp(0.0, 1.0),
            );
        }
    }

    stops.last().unwrap().color.clone()
}

/// Derive CMYK values from color stops at parameter t.
///
/// For DeviceCMYK shading color spaces the per-stop `raw_components` carry the
/// authoritative 4-channel CMYK values (already tint-transformed for
/// Separation/DeviceN with a CMYK alt) — those are interpolated directly.
///
/// For non-CMYK source color spaces (DeviceRGB, DeviceGray, CalRGB, CalGray,
/// ICCBased non-4) the interpolated sRGB color is round-tripped to CMYK via
/// the system CMYK ICC profile so the parallel CMYK buffer holds an accurate
/// representation. Falls back to PLRM `(1−r, 1−g, 1−b, 0)` when no system
/// profile is registered (e.g. `--no-icc`).
fn interpolate_cmyk_from_stops(
    stops: &[stet_graphics::device::ColorStop],
    cs: &ShadingColorSpace,
    t: f64,
    color: &DeviceColor,
    icc: Option<&IccCache>,
) -> (f64, f64, f64, f64) {
    let rgb_to_cmyk = |c: &DeviceColor| -> (f64, f64, f64, f64) {
        if let Some(cmyk) = icc.and_then(|i| i.convert_rgb_to_cmyk_readonly(c.r, c.g, c.b)) {
            (cmyk[0], cmyk[1], cmyk[2], cmyk[3])
        } else {
            (
                (1.0 - c.r).clamp(0.0, 1.0),
                (1.0 - c.g).clamp(0.0, 1.0),
                (1.0 - c.b).clamp(0.0, 1.0),
                0.0,
            )
        }
    };

    match cs {
        // Separation/DeviceN with a CMYK alternate carry tint-transformed CMYK
        // in `raw_components`, the same shape as DeviceCMYK — handle them on
        // the same path so spot-shading round-trips render identically.
        ShadingColorSpace::DeviceCMYK
        | ShadingColorSpace::Separation { .. }
        | ShadingColorSpace::DeviceN { .. } => {
            // Interpolate raw CMYK components from stops
            if stops.len() == 1 {
                let rc = &stops[0].raw_components;
                if rc.len() >= 4 {
                    return (rc[0], rc[1], rc[2], rc[3]);
                }
            }
            // Find surrounding stops and interpolate
            let mut lo = &stops[0];
            let mut hi = stops.last().unwrap();
            for i in 0..stops.len() - 1 {
                if stops[i + 1].position >= t {
                    lo = &stops[i];
                    hi = &stops[i + 1];
                    break;
                }
            }
            let span = hi.position - lo.position;
            let frac = if span > 1e-10 {
                (t - lo.position) / span
            } else {
                0.0
            };
            let frac = frac.clamp(0.0, 1.0);
            if lo.raw_components.len() >= 4 && hi.raw_components.len() >= 4 {
                (
                    lo.raw_components[0] + frac * (hi.raw_components[0] - lo.raw_components[0]),
                    lo.raw_components[1] + frac * (hi.raw_components[1] - lo.raw_components[1]),
                    lo.raw_components[2] + frac * (hi.raw_components[2] - lo.raw_components[2]),
                    lo.raw_components[3] + frac * (hi.raw_components[3] - lo.raw_components[3]),
                )
            } else {
                rgb_to_cmyk(color)
            }
        }
        _ => rgb_to_cmyk(color),
    }
}

/// Derive CMYK values from triangle mesh vertices using barycentric weights.
///
/// Mirrors [`interpolate_cmyk_from_stops`]: DeviceCMYK source spaces use the
/// per-vertex `raw_components`, non-CMYK spaces ICC-reverse the interpolated
/// sRGB color, and PLRM is the last-resort fallback.
#[allow(clippy::too_many_arguments)]
fn interpolate_cmyk_from_vertices(
    v0: &ShadingVertex,
    v1: &ShadingVertex,
    v2: &ShadingVertex,
    w0: f64,
    w1: f64,
    w2: f64,
    cs: &ShadingColorSpace,
    r: f64,
    g: f64,
    b: f64,
    icc: Option<&IccCache>,
) -> (f64, f64, f64, f64) {
    let rgb_to_cmyk = |r: f64, g: f64, b: f64| -> (f64, f64, f64, f64) {
        if let Some(cmyk) = icc.and_then(|i| i.convert_rgb_to_cmyk_readonly(r, g, b)) {
            (cmyk[0], cmyk[1], cmyk[2], cmyk[3])
        } else {
            (
                (1.0 - r).clamp(0.0, 1.0),
                (1.0 - g).clamp(0.0, 1.0),
                (1.0 - b).clamp(0.0, 1.0),
                0.0,
            )
        }
    };

    match cs {
        ShadingColorSpace::DeviceCMYK
        | ShadingColorSpace::Separation { .. }
        | ShadingColorSpace::DeviceN { .. } => {
            if v0.raw_components.len() >= 4
                && v1.raw_components.len() >= 4
                && v2.raw_components.len() >= 4
            {
                (
                    w0 * v0.raw_components[0]
                        + w1 * v1.raw_components[0]
                        + w2 * v2.raw_components[0],
                    w0 * v0.raw_components[1]
                        + w1 * v1.raw_components[1]
                        + w2 * v2.raw_components[1],
                    w0 * v0.raw_components[2]
                        + w1 * v1.raw_components[2]
                        + w2 * v2.raw_components[2],
                    w0 * v0.raw_components[3]
                        + w1 * v1.raw_components[3]
                        + w2 * v2.raw_components[3],
                )
            } else {
                rgb_to_cmyk(r, g, b)
            }
        }
        _ => rgb_to_cmyk(r, g, b),
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use stet_graphics::color::DashPattern;
    use stet_graphics::device::{BgUcrState, HalftoneState, TransferState};

    #[test]
    fn test_create_device() {
        let dev = SkiaDevice::new(100, 100);
        assert_eq!(dev.page_size(), (100, 100));
    }

    #[test]
    fn test_fill_rect() {
        let mut dev = SkiaDevice::new(100, 100);
        let mut path = PsPath::new();
        path.segments.push(PathSegment::MoveTo(10.0, 10.0));
        path.segments.push(PathSegment::LineTo(90.0, 10.0));
        path.segments.push(PathSegment::LineTo(90.0, 90.0));
        path.segments.push(PathSegment::LineTo(10.0, 90.0));
        path.segments.push(PathSegment::ClosePath);

        let params = FillParams {
            color: DeviceColor::from_rgb(1.0, 0.0, 0.0),
            fill_rule: FillRule::NonZeroWinding,
            ctm: Matrix::identity(),
            is_text_glyph: false,
            overprint: false,
            overprint_mode: 0,
            opm_paired: false,
            painted_channels: 0,
            is_device_cmyk: false,
            spot_color: None,
            icc_color: None,
            rendering_intent: 0,
            transfer: TransferState::default(),
            halftone: HalftoneState::default(),
            bg_ucr: BgUcrState::default(),
            alpha: 1.0,
            blend_mode: 0,
            alpha_is_shape: false,
        };
        dev.fill_path(&path, &params);

        // Check that pixel at center is red
        let pixel = dev.pixmap().pixel(50, 50).unwrap();
        assert_eq!(pixel.red(), 255);
        assert_eq!(pixel.green(), 0);
        assert_eq!(pixel.blue(), 0);
    }

    #[test]
    fn test_stroke_line() {
        let mut dev = SkiaDevice::new(100, 100);
        let mut path = PsPath::new();
        path.segments.push(PathSegment::MoveTo(10.0, 50.0));
        path.segments.push(PathSegment::LineTo(90.0, 50.0));

        let params = StrokeParams {
            color: DeviceColor::from_rgb(0.0, 0.0, 1.0),
            line_width: 4.0,
            line_cap: LineCap::Butt,
            line_join: LineJoin::Miter,
            miter_limit: 10.0,
            dash_pattern: DashPattern::solid(),
            ctm: Matrix::identity(),
            stroke_adjust: false,
            is_text_glyph: false,
            overprint: false,
            overprint_mode: 0,
            opm_paired: false,
            painted_channels: 0,
            is_device_cmyk: false,
            spot_color: None,
            icc_color: None,
            rendering_intent: 0,
            transfer: TransferState::default(),
            halftone: HalftoneState::default(),
            bg_ucr: BgUcrState::default(),
            alpha: 1.0,
            blend_mode: 0,
            alpha_is_shape: false,
        };
        dev.stroke_path(&path, &params);

        // Check that pixel on the line is blue
        let pixel = dev.pixmap().pixel(50, 50).unwrap();
        assert_eq!(pixel.blue(), 255);
    }

    #[test]
    fn test_clip() {
        let mut dev = SkiaDevice::new(100, 100);

        // Set clip to left half
        let mut clip_path = PsPath::new();
        clip_path.segments.push(PathSegment::MoveTo(0.0, 0.0));
        clip_path.segments.push(PathSegment::LineTo(50.0, 0.0));
        clip_path.segments.push(PathSegment::LineTo(50.0, 100.0));
        clip_path.segments.push(PathSegment::LineTo(0.0, 100.0));
        clip_path.segments.push(PathSegment::ClosePath);

        let clip_params = ClipParams {
            fill_rule: FillRule::NonZeroWinding,
            ctm: Matrix::identity(),
            stroke_params: None,
        };
        dev.clip_path(&clip_path, &clip_params);

        // Fill entire page with red
        let mut fill_path = PsPath::new();
        fill_path.segments.push(PathSegment::MoveTo(0.0, 0.0));
        fill_path.segments.push(PathSegment::LineTo(100.0, 0.0));
        fill_path.segments.push(PathSegment::LineTo(100.0, 100.0));
        fill_path.segments.push(PathSegment::LineTo(0.0, 100.0));
        fill_path.segments.push(PathSegment::ClosePath);

        let fill_params = FillParams {
            color: DeviceColor::from_rgb(1.0, 0.0, 0.0),
            fill_rule: FillRule::NonZeroWinding,
            ctm: Matrix::identity(),
            is_text_glyph: false,
            overprint: false,
            overprint_mode: 0,
            opm_paired: false,
            painted_channels: 0,
            is_device_cmyk: false,
            spot_color: None,
            icc_color: None,
            rendering_intent: 0,
            transfer: TransferState::default(),
            halftone: HalftoneState::default(),
            bg_ucr: BgUcrState::default(),
            alpha: 1.0,
            blend_mode: 0,
            alpha_is_shape: false,
        };
        dev.fill_path(&fill_path, &fill_params);

        // Left half should be red
        let left_pixel = dev.pixmap().pixel(25, 50).unwrap();
        assert_eq!(left_pixel.red(), 255);

        // Right half should still be white
        let right_pixel = dev.pixmap().pixel(75, 50).unwrap();
        assert_eq!(right_pixel.red(), 255);
        assert_eq!(right_pixel.green(), 255); // white
    }

    #[test]
    fn test_erase_page() {
        let mut dev = SkiaDevice::new(100, 100);
        // Fill with red
        let mut path = PsPath::new();
        path.segments.push(PathSegment::MoveTo(0.0, 0.0));
        path.segments.push(PathSegment::LineTo(100.0, 0.0));
        path.segments.push(PathSegment::LineTo(100.0, 100.0));
        path.segments.push(PathSegment::LineTo(0.0, 100.0));
        path.segments.push(PathSegment::ClosePath);
        let params = FillParams {
            color: DeviceColor::from_rgb(1.0, 0.0, 0.0),
            fill_rule: FillRule::NonZeroWinding,
            ctm: Matrix::identity(),
            is_text_glyph: false,
            overprint: false,
            overprint_mode: 0,
            opm_paired: false,
            painted_channels: 0,
            is_device_cmyk: false,
            spot_color: None,
            icc_color: None,
            rendering_intent: 0,
            transfer: TransferState::default(),
            halftone: HalftoneState::default(),
            bg_ucr: BgUcrState::default(),
            alpha: 1.0,
            blend_mode: 0,
            alpha_is_shape: false,
        };
        dev.fill_path(&path, &params);

        dev.erase_page();

        // Should be white again
        let pixel = dev.pixmap().pixel(50, 50).unwrap();
        assert_eq!(pixel.red(), 255);
        assert_eq!(pixel.green(), 255);
        assert_eq!(pixel.blue(), 255);
    }

    #[test]
    fn test_show_page() {
        let mut dev = SkiaDevice::new(10, 10);
        let path = std::env::temp_dir().join("stet_test_output.png");
        let path_str = path.to_string_lossy();
        let result = dev.show_page(&path_str);
        assert!(result.is_ok());
        assert!(path.exists());
        std::fs::remove_file(&path).ok();
    }

    #[test]
    fn test_transform() {
        let mut dev = SkiaDevice::new(200, 200);
        // Draw at origin with a translate transform
        let mut path = PsPath::new();
        path.segments.push(PathSegment::MoveTo(0.0, 0.0));
        path.segments.push(PathSegment::LineTo(10.0, 0.0));
        path.segments.push(PathSegment::LineTo(10.0, 10.0));
        path.segments.push(PathSegment::LineTo(0.0, 10.0));
        path.segments.push(PathSegment::ClosePath);

        let params = FillParams {
            color: DeviceColor::from_rgb(0.0, 1.0, 0.0),
            fill_rule: FillRule::NonZeroWinding,
            ctm: Matrix::translate(100.0, 100.0),
            is_text_glyph: false,
            overprint: false,
            overprint_mode: 0,
            opm_paired: false,
            painted_channels: 0,
            is_device_cmyk: false,
            spot_color: None,
            icc_color: None,
            rendering_intent: 0,
            transfer: TransferState::default(),
            halftone: HalftoneState::default(),
            bg_ucr: BgUcrState::default(),
            alpha: 1.0,
            blend_mode: 0,
            alpha_is_shape: false,
        };
        dev.fill_path(&path, &params);

        // Pixel at translated location should be green
        let pixel = dev.pixmap().pixel(105, 105).unwrap();
        assert_eq!(pixel.green(), 255);
        assert_eq!(pixel.red(), 0);
    }

    fn make_test_fill_at(x: f64, y: f64, w: f64, h: f64) -> DisplayElement {
        let mut path = PsPath::new();
        path.segments.push(PathSegment::MoveTo(x, y));
        path.segments.push(PathSegment::LineTo(x + w, y));
        path.segments.push(PathSegment::LineTo(x + w, y + h));
        path.segments.push(PathSegment::LineTo(x, y + h));
        path.segments.push(PathSegment::ClosePath);
        DisplayElement::Fill {
            path,
            params: FillParams {
                color: DeviceColor::from_rgb(0.0, 0.0, 0.0),
                fill_rule: FillRule::NonZeroWinding,
                ctm: Matrix::identity(),
                is_text_glyph: false,
                overprint: false,
                overprint_mode: 0,
                opm_paired: false,
                painted_channels: 0,
                is_device_cmyk: false,
                spot_color: None,
                icc_color: None,
                rendering_intent: 0,
                transfer: TransferState::default(),
                halftone: HalftoneState::default(),
                bg_ucr: BgUcrState::default(),
                alpha: 1.0,
                blend_mode: 0,
                alpha_is_shape: false,
            },
        }
    }

    #[test]
    fn test_compute_paint_bounds_two_fills() {
        let mut list = DisplayList::new();
        list.push(make_test_fill_at(10.0, 20.0, 30.0, 40.0)); // [10..40, 20..60]
        list.push(make_test_fill_at(100.0, 50.0, 50.0, 25.0)); // [100..150, 50..75]

        let bounds = compute_paint_bounds(&list, 72.0).expect("expected union bounds");
        assert!(
            (bounds.x_min - 10.0).abs() < 1e-9,
            "x_min was {}",
            bounds.x_min
        );
        assert!(
            (bounds.y_min - 20.0).abs() < 1e-9,
            "y_min was {}",
            bounds.y_min
        );
        assert!(
            (bounds.x_max - 150.0).abs() < 1e-9,
            "x_max was {}",
            bounds.x_max
        );
        assert!(
            (bounds.y_max - 75.0).abs() < 1e-9,
            "y_max was {}",
            bounds.y_max
        );
    }

    #[test]
    fn test_compute_paint_bounds_empty_list() {
        let list = DisplayList::new();
        assert!(compute_paint_bounds(&list, 72.0).is_none());
    }

    #[test]
    fn test_compute_paint_bounds_only_clip_returns_none() {
        let mut list = DisplayList::new();
        list.push(DisplayElement::InitClip);
        // Clip / InitClip / ErasePage are skipped (return None from
        // precompute_full_bboxes), so a list of only clip ops yields no bounds.
        assert!(compute_paint_bounds(&list, 72.0).is_none());
    }

    #[test]
    fn test_rasterize_mask_anchors_to_paint_bounds() {
        use stet_graphics::display_list::{SoftMaskParams, SoftMaskSubtype};

        // A 50×40 white fill at page coords (200, 300)..(250, 340).
        // Mask paint bounds in device units: x [200..250], y [300..340].
        let mut mask = DisplayList::new();
        let mut path = PsPath::new();
        path.segments.push(PathSegment::MoveTo(200.0, 300.0));
        path.segments.push(PathSegment::LineTo(250.0, 300.0));
        path.segments.push(PathSegment::LineTo(250.0, 340.0));
        path.segments.push(PathSegment::LineTo(200.0, 340.0));
        path.segments.push(PathSegment::ClosePath);
        mask.push(DisplayElement::Fill {
            path,
            params: FillParams {
                color: DeviceColor::from_rgb(1.0, 1.0, 1.0),
                fill_rule: FillRule::NonZeroWinding,
                ctm: Matrix::identity(),
                is_text_glyph: false,
                overprint: false,
                overprint_mode: 0,
                opm_paired: false,
                painted_channels: 0,
                is_device_cmyk: false,
                spot_color: None,
                icc_color: None,
                rendering_intent: 0,
                transfer: TransferState::default(),
                halftone: HalftoneState::default(),
                bg_ucr: BgUcrState::default(),
                alpha: 1.0,
                blend_mode: 0,
                alpha_is_shape: false,
            },
        });

        let params = SoftMaskParams {
            subtype: SoftMaskSubtype::Luminosity,
            // Form bbox; intentionally tighter than paint bounds — the
            // raster should follow paint bounds, not this.
            bbox: [0.0, 0.0, 100.0, 100.0],
            backdrop_color: None, // black backdrop → out-of-bounds value = 0
            transfer_invert: false,
            has_nested_mask_scope: false,
            parent_clip_bbox: None,
        };

        let raster = rasterize_mask(
            &mask,
            &params,
            None,
            false,
            72.0,
            1.0,
            1.0,
            &LayerSet::new(),
        )
        .expect("expected raster");

        // Origin must be at (or just before) the paint bounds, with the
        // 1-pixel AA pad.
        assert_eq!(raster.origin_x, 199);
        assert_eq!(raster.origin_y, 299);
        // Width / height = paint bounds + 2 pixels of pad (1 each side).
        assert_eq!(raster.width, 52);
        assert_eq!(raster.height, 42);
        assert_eq!(raster.scale_x, 1.0);
        assert_eq!(raster.scale_y, 1.0);

        // The raster should be non-zero somewhere inside the painted region.
        // Sample the center of the painted area: page (225, 320) → mask
        // index (225 - 199, 320 - 299) = (26, 21).
        let mx = 225 - raster.origin_x;
        let my = 320 - raster.origin_y;
        assert!(mx >= 0 && (mx as u32) < raster.width);
        assert!(my >= 0 && (my as u32) < raster.height);
        let center_value = raster.data[(my as usize) * raster.width as usize + mx as usize];
        assert_eq!(
            center_value, 255,
            "center of painted mask should be opaque white (lum=255)"
        );

        // A point outside the paint bounds (page (300, 320)) maps to mask
        // index (101, 21) which is outside the raster width — sampling
        // there should fall back to out_of_bounds_mask_value(params) = 0.
        let mx_out = 300 - raster.origin_x;
        let in_bounds = mx_out >= 0 && (mx_out as u32) < raster.width;
        assert!(!in_bounds, "page x=300 should be outside the mask raster");
        assert_eq!(
            out_of_bounds_mask_value(&params),
            0,
            "black backdrop → out-of-bounds = 0"
        );
    }

    #[test]
    fn test_band_local_to_mask_formula() {
        // Verify the band-local → page-pixel → mask-index arithmetic for
        // several band offsets. This is the highest-risk part of Step 4
        // because it bridges three coordinate systems:
        //
        //   band-local pixel (x, y)
        //     + (crop_x, crop_y)            → soft-mask offset within band
        //     + (vp_x_pixels, vp_y_pixels)  → page-pixel position
        //     - (origin_x, origin_y)        → mask raster index

        // Mask raster anchored at page-pixel (200, 300).
        let raster_origin_x = 200i32;
        let raster_origin_y = 300i32;

        // Helper that runs the formula from render_soft_masked.
        let sample = |vp_x_dev: f32,
                      vp_y_dev: f32,
                      scale: f32,
                      crop_x: i32,
                      crop_y: i32,
                      x: i32,
                      y: i32|
         -> (i32, i32) {
            let vp_x_pixels = (vp_x_dev * scale).round() as i32;
            let vp_y_pixels = (vp_y_dev * scale).round() as i32;
            let page_x = vp_x_pixels + crop_x + x;
            let page_y = vp_y_pixels + crop_y + y;
            let mx = page_x - raster_origin_x;
            let my = page_y - raster_origin_y;
            (mx, my)
        };

        // Case 1: band starts at page Y=0 (top band of page).
        // vp_y=0, scale=1. The soft-mask top-left page (220, 310) must
        // map to mask index (20, 10).
        // crop_x = floor((220 - 0) * 1) = 220, crop_y = floor((310 - 0) * 1) = 310
        let (mx, my) = sample(0.0, 0.0, 1.0, 220, 310, 0, 0);
        assert_eq!((mx, my), (20, 10), "top band: smask top-left");

        // 5 pixels into the smask region (band-local): page (225, 315)
        let (mx, my) = sample(0.0, 0.0, 1.0, 220, 310, 5, 5);
        assert_eq!((mx, my), (25, 15), "top band: 5px into smask");

        // Case 2: band starts at page Y=400. The smask region [310..340]
        // doesn't intersect this band — covered by the early-return path.
        // But test a band that DOES intersect the smask, e.g. starting at
        // Y=305. Then page-Y 310 is band-local Y=5.
        // vp_y_pixels = round(305 * 1) = 305
        // crop_y = floor((310 - 305) * 1) = 5  (band-local)
        // For content y=0 (band-local), page_y = 305 + 5 + 0 = 310 ✓
        let (mx, my) = sample(0.0, 305.0, 1.0, 220, 5, 0, 0);
        assert_eq!((mx, my), (20, 10), "mid band: smask top-left");

        // Case 3: viewport rendering at scale 2. vp_x=100.0, vp_y=150.0,
        // scale=2. Page pixel offset = (200, 300). The smask region
        // [220..270] in device units = [440..540] in page-pixels at scale 2.
        // But the mask raster was built at scale 1, so this is a
        // SCALE-MISMATCH case — the cache would invalidate and rebuild.
        // We're not testing the rebuild, just that the formula computes
        // the right page-pixel coords:
        //   vp_x_pixels = round(100 * 2) = 200
        //   smask in band: page (440..540), band-local (240..340)
        //   crop_x = max(0, floor((220 - 100) * 2)) = 240
        //   For x=0 (band-local), page_x = 200 + 240 + 0 = 440 ✓
        let vp_x_pixels = (100.0_f32 * 2.0).round() as i32;
        let crop_x = ((220.0_f32 - 100.0) * 2.0).floor() as i32;
        let page_x_for_x_zero = vp_x_pixels + crop_x;
        assert_eq!(page_x_for_x_zero, 440, "viewport scale-2: page-x at x=0");
    }

    // --- obscured-fill skip (§ GWG reference-under-test pattern) ---

    fn x_path() -> PsPath {
        let mut p = PsPath::new();
        p.segments.push(PathSegment::MoveTo(10.0, 10.0));
        p.segments.push(PathSegment::LineTo(20.0, 20.0));
        p.segments.push(PathSegment::LineTo(30.0, 10.0));
        p.segments.push(PathSegment::LineTo(20.0, 0.0));
        p.segments.push(PathSegment::ClosePath);
        p
    }

    fn x_path_perturbed() -> PsPath {
        // Same shape, sub-unit rounding — stand-in for GWG's 0.001-unit
        // coordinate drift between duplicated path emissions.
        let mut p = PsPath::new();
        p.segments.push(PathSegment::MoveTo(10.001, 10.0));
        p.segments.push(PathSegment::LineTo(20.0, 19.999));
        p.segments.push(PathSegment::LineTo(30.002, 10.001));
        p.segments.push(PathSegment::LineTo(19.999, 0.0));
        p.segments.push(PathSegment::ClosePath);
        p
    }

    fn fill(path: PsPath, alpha: f64, blend: u8) -> DisplayElement {
        DisplayElement::Fill {
            path,
            params: FillParams {
                color: DeviceColor::from_rgb(0.0, 0.0, 0.0),
                fill_rule: FillRule::NonZeroWinding,
                ctm: Matrix::identity(),
                is_text_glyph: false,
                overprint: false,
                overprint_mode: 0,
                opm_paired: false,
                painted_channels: 0,
                is_device_cmyk: false,
                spot_color: None,
                icc_color: None,
                rendering_intent: 0,
                transfer: TransferState::default(),
                halftone: HalftoneState::default(),
                bg_ucr: BgUcrState::default(),
                alpha,
                blend_mode: blend,
                alpha_is_shape: false,
            },
        }
    }

    fn rect_path(x0: f64, y0: f64, x1: f64, y1: f64) -> PsPath {
        let mut p = PsPath::new();
        p.segments.push(PathSegment::MoveTo(x0, y0));
        p.segments.push(PathSegment::LineTo(x1, y0));
        p.segments.push(PathSegment::LineTo(x1, y1));
        p.segments.push(PathSegment::LineTo(x0, y1));
        p.segments.push(PathSegment::ClosePath);
        p
    }

    fn clip_elem(path: PsPath) -> DisplayElement {
        DisplayElement::Clip {
            path,
            params: ClipParams {
                fill_rule: FillRule::NonZeroWinding,
                ctm: Matrix::identity(),
                stroke_params: None,
            },
        }
    }

    fn group_elem(
        inner: Vec<DisplayElement>,
        bbox: [f64; 4],
        isolated: bool,
        alpha: f64,
        blend: u8,
    ) -> DisplayElement {
        let mut dl = DisplayList::new();
        for e in inner {
            dl.push(e);
        }
        DisplayElement::Group {
            elements: dl,
            params: stet_graphics::display_list::GroupParams {
                bbox,
                isolated,
                knockout: false,
                blend_mode: blend,
                alpha,
                color_space: stet_graphics::display_list::GroupColorSpace::Inherited,
            },
        }
    }

    fn dl(elements: Vec<DisplayElement>) -> DisplayList {
        let mut d = DisplayList::new();
        for e in elements {
            d.push(e);
        }
        d
    }

    #[test]
    fn obscured_skip_fires_on_matching_fill_plus_iso_group() {
        // Classic GWG pattern: parent Fill, then a clip, then an isolated
        // alpha-1 Group whose first paint is a matching Fill.
        let parent = fill(x_path(), 1.0, 0);
        let inner = vec![fill(x_path_perturbed(), 1.0, 0)];
        let grp = group_elem(inner, [0.0, -5.0, 40.0, 30.0], true, 1.0, 0);
        let d = dl(vec![
            parent,
            clip_elem(rect_path(0.0, -5.0, 40.0, 30.0)),
            grp,
        ]);
        assert_eq!(compute_obscured_fill_skips(&d), vec![0]);
    }

    #[test]
    fn obscured_skip_does_not_fire_on_non_isolated_group() {
        let parent = fill(x_path(), 1.0, 0);
        let inner = vec![fill(x_path(), 1.0, 0)];
        let grp = group_elem(inner, [0.0, -5.0, 40.0, 30.0], false, 1.0, 0);
        let d = dl(vec![parent, grp]);
        assert!(compute_obscured_fill_skips(&d).is_empty());
    }

    #[test]
    fn obscured_skip_does_not_fire_on_partial_alpha_group() {
        let parent = fill(x_path(), 1.0, 0);
        let inner = vec![fill(x_path(), 1.0, 0)];
        let grp = group_elem(inner, [0.0, -5.0, 40.0, 30.0], true, 0.5, 0);
        let d = dl(vec![parent, grp]);
        assert!(compute_obscured_fill_skips(&d).is_empty());
    }

    #[test]
    fn obscured_skip_does_not_fire_on_non_normal_blend() {
        let parent = fill(x_path(), 1.0, 0);
        let inner = vec![fill(x_path(), 1.0, 0)];
        // blend_mode = 10 (Difference) on the group — composite-back
        // semantics differ from Normal, so skipping parent is unsafe.
        let grp = group_elem(inner, [0.0, -5.0, 40.0, 30.0], true, 1.0, 10);
        let d = dl(vec![parent, grp]);
        assert!(compute_obscured_fill_skips(&d).is_empty());
    }

    #[test]
    fn obscured_skip_does_not_fire_when_paths_differ() {
        let parent = fill(rect_path(0.0, 0.0, 5.0, 5.0), 1.0, 0);
        let inner = vec![fill(x_path(), 1.0, 0)];
        let grp = group_elem(inner, [0.0, -5.0, 40.0, 30.0], true, 1.0, 0);
        let d = dl(vec![parent, grp]);
        assert!(compute_obscured_fill_skips(&d).is_empty());
    }

    #[test]
    fn obscured_skip_does_not_fire_when_group_bbox_too_small() {
        // Parent fills a rectangle larger than the group's declared
        // bbox — the form's BBox would clip the inner fill to a subset
        // of the parent's extent, so the parent cannot be dropped.
        let big = rect_path(0.0, 0.0, 100.0, 100.0);
        let parent = fill(big.clone(), 1.0, 0);
        let inner = vec![fill(big, 1.0, 0)];
        // Group bbox only covers [0..10, 0..10], much smaller than parent.
        let grp = group_elem(inner, [0.0, 0.0, 10.0, 10.0], true, 1.0, 0);
        let d = dl(vec![parent, grp]);
        assert!(compute_obscured_fill_skips(&d).is_empty());
    }

    #[test]
    fn obscured_skip_does_not_fire_when_intervening_clip_too_small() {
        // A clip between the parent fill and the group is narrower than
        // the parent's extent — dropping the parent's fill would reveal
        // backdrop where the group couldn't paint.
        let parent = fill(x_path(), 1.0, 0);
        let narrow_clip = clip_elem(rect_path(12.0, 5.0, 18.0, 15.0));
        let inner = vec![fill(x_path(), 1.0, 0)];
        let grp = group_elem(inner, [0.0, -5.0, 40.0, 30.0], true, 1.0, 0);
        let d = dl(vec![parent, narrow_clip, grp]);
        assert!(compute_obscured_fill_skips(&d).is_empty());
    }

    #[test]
    fn obscured_skip_does_not_fire_when_inner_clip_too_small() {
        // Clip *inside* the group is narrower than the parent's extent.
        let parent = fill(x_path(), 1.0, 0);
        let inner = vec![
            clip_elem(rect_path(12.0, 5.0, 18.0, 15.0)),
            fill(x_path(), 1.0, 0),
        ];
        let grp = group_elem(inner, [0.0, -5.0, 40.0, 30.0], true, 1.0, 0);
        let d = dl(vec![parent, grp]);
        assert!(compute_obscured_fill_skips(&d).is_empty());
    }

    #[test]
    fn obscured_skip_fires_when_inner_clip_is_wider_than_parent_path() {
        // A clip inside the group that's larger than the parent's fill
        // doesn't threaten coverage; still safe to skip the parent.
        let parent = fill(x_path(), 1.0, 0);
        let inner = vec![
            clip_elem(rect_path(-10.0, -10.0, 40.0, 30.0)),
            fill(x_path_perturbed(), 1.0, 0),
        ];
        let grp = group_elem(inner, [0.0, -5.0, 40.0, 30.0], true, 1.0, 0);
        let d = dl(vec![parent, grp]);
        assert_eq!(compute_obscured_fill_skips(&d), vec![0]);
    }

    #[test]
    fn obscured_skip_does_not_fire_on_partial_alpha_parent() {
        // A parent fill at alpha < 1 might blend with backdrop; dropping
        // it changes the visual even when the group overpaints.
        let parent = fill(x_path(), 0.5, 0);
        let inner = vec![fill(x_path(), 1.0, 0)];
        let grp = group_elem(inner, [0.0, -5.0, 40.0, 30.0], true, 1.0, 0);
        let d = dl(vec![parent, grp]);
        assert!(compute_obscured_fill_skips(&d).is_empty());
    }
}