orinium_browser/engine/renderer_model/

box_model.rs

//! Generation of [`DrawCommand`]s from the layout tree (box models, borders,
//! backgrounds and text).

use ui_layout::{
    BoxModel, EdgeOption, InnerDisplay, LayoutChild, LayoutNode, OuterDisplay, Position, Rect,
};

use crate::engine::layouter::text_layouter::TextFlowLayouter;
use crate::engine::layouter::types::{
    Background, BackgroundDimension, BackgroundImage, BackgroundOffset, BackgroundPositionAxis,
    BackgroundRepeat, BackgroundSize, BorderRadius, ClipPath, Color, ContainerStyle, CornerRadius,
    InfoNode, NodeKind, TextDecoration, TextFlowStyle, TextStyle, Visibility,
};
use crate::engine::renderer_model::draw_command::{Brush, DrawCommand, FillRule, Paint};
use crate::engine::renderer_model::geom::AffineTransform;
use crate::engine::renderer_model::path::{
    Path, append_quarter_ellipse, clamp_radii, ellipse_path, offset_path, polygon_path, rect_path,
    rounded_rect_path,
};
use crate::engine::svg::emit_commands;
use crate::engine::ui::ContentSize;

/// Per-box-model push state for balanced pop generation.
#[derive(Default, Clone, Copy)]
struct BoxPushState {
    border: bool,
    /// Whether the element's CSS `transform` was pushed.
    transform: bool,
    clip_path: bool,
    overflow_clip: bool,
    content: bool,
    scroll: bool,
    /// The pushed clip-path resolves to an empty (zero-area) region, so nothing
    /// in the subtree is visible and its painting can be skipped entirely.
    cull: bool,
}

// --------------------------------
// Helpers
// --------------------------------

fn push_transform(cmd_buf: &mut Vec<DrawCommand>, dx: f32, dy: f32) -> bool {
    if dx != 0.0 || dy != 0.0 {
        cmd_buf.push(DrawCommand::PushTransform {
            transform: AffineTransform::translate(dx, dy),
        });
        true
    } else {
        false
    }
}

/// State of the nearest scrollport, used to resolve `position: sticky` offsets.
///
/// All coordinates are expressed in the current node's parent-content space
/// (the same space its `border_box` coordinates live in).
#[derive(Default, Clone, Copy)]
pub struct StickyViewport {
    /// Top-left corner of the scrollport's visible region, scroll offset already
    /// applied. The renderer's scroll transform is `translate(scroll_x,
    /// -scroll_y)`, so in the scrollport's content space this is
    /// `(padding.left - scroll_x, padding.top + scroll_y)`; the value is rebased
    /// into each descendant's content space.
    pub top_left: (f32, f32),
    /// Visible (padding-box) size of the nearest scrollport.
    pub size: (f32, f32),
}

/// Whether the node scrolls its own content and thus establishes a scrollport
/// for its subtree. The document root always does, because the UI layer scrolls
/// it directly without necessarily setting its scroll flags.
pub fn is_scrollport(kind: &NodeKind) -> bool {
    match kind {
        NodeKind::Container {
            scroll_x, scroll_y, ..
        }
        | NodeKind::Custom {
            scroll_x, scroll_y, ..
        }
        | NodeKind::Svg {
            scroll_x, scroll_y, ..
        } => *scroll_x || *scroll_y,
        _ => false,
    }
}

/// Compute the sticky translate for a box relative to its nearest scrollport.
///
/// `box_rect` is the sticky box's border box (its natural position, in
/// parent-content space) and `containing` is the parent content-box size — the
/// containing block the box may not leave. Per CSS-POSITION-3 §3.4 the box is
/// shifted inward just enough to keep each specified edge inside the
/// scrollport's "sticky view rectangle" (the visible region, whose top-left is
/// `viewport.top_left`), while staying within the containing block.
pub fn sticky_offset(
    edges: &EdgeOption,
    box_rect: &Rect,
    viewport: StickyViewport,
    containing: (f32, f32),
) -> (f32, f32) {
    let x = box_rect.x;
    let y = box_rect.y;
    let w = box_rect.width;
    let h = box_rect.height;

    let mut dy: f32 = 0.0;
    let port_top = viewport.top_left.1;
    let port_bottom = viewport.top_left.1 + viewport.size.1;
    if let Some(top) = edges.top {
        dy = dy.max((port_top + top) - y);
    }
    if let Some(bottom) = edges.bottom {
        // CSS-POSITION-3 §3.4: when the sticky view rectangle is shorter than
        // the box, the end-edge inset is ignored and the box sticks to its
        // start edge instead.
        let has_room = match edges.top {
            Some(top) => (port_bottom - bottom) - (port_top + top) >= h,
            None => true,
        };
        if has_room {
            dy = dy.min((port_bottom - bottom) - (y + h));
        }
    }
    // Containing-block constraint (parent content box). The bounds are
    // zero-clamped so an already-overflowing box is never forced to move
    // (matching Chromium/Firefox "clamp sticky offset bounds by zero").
    let dy_lo = (-y).min(0.0);
    let dy_hi = (containing.1 - y - h).max(0.0);
    dy = dy.max(dy_lo).min(dy_hi);

    let mut dx: f32 = 0.0;
    let port_left = viewport.top_left.0;
    let port_right = viewport.top_left.0 + viewport.size.0;
    if let Some(left) = edges.left {
        dx = dx.max((port_left + left) - x);
    }
    if let Some(right) = edges.right {
        let has_room = match edges.left {
            Some(left) => (port_right - right) - (port_left + left) >= w,
            None => true,
        };
        if has_room {
            dx = dx.min((port_right - right) - (x + w));
        }
    }
    let dx_lo = (-x).min(0.0);
    let dx_hi = (containing.0 - x - w).max(0.0);
    dx = dx.max(dx_lo).min(dx_hi);

    (dx, dy)
}

/// Resolve the four outer corner radii to pixels against the border box.
///
/// Horizontal components resolve against the box width, vertical components
/// against the box height (so `%` works per-axis per CSS).
fn resolve_outer_radii(radius: &BorderRadius, box_w: f32, box_h: f32) -> [(f32, f32); 4] {
    let resolve = |c: &CornerRadius| -> (f32, f32) {
        (
            c.x.resolve_with(Some(box_w), 0.0, 0.0)
                .unwrap_or(0.0)
                .max(0.0),
            c.y.resolve_with(Some(box_h), 0.0, 0.0)
                .unwrap_or(0.0)
                .max(0.0),
        )
    };
    [
        resolve(&radius.top_left),
        resolve(&radius.top_right),
        resolve(&radius.bottom_right),
        resolve(&radius.bottom_left),
    ]
}

/// Compute the inner (padding-box) corner radii: the outer radii reduced by
/// the two adjacent border widths, per CSS.
fn inner_radii(outer: [(f32, f32); 4], bl: f32, bt: f32, br: f32, bb: f32) -> [(f32, f32); 4] {
    [
        (outer[0].0 - bl, outer[0].1 - bt),
        (outer[1].0 - br, outer[1].1 - bt),
        (outer[2].0 - br, outer[2].1 - bb),
        (outer[3].0 - bl, outer[3].1 - bb),
    ]
    .map(|(x, y)| (x.max(0.0), y.max(0.0)))
}

/// Build the closed path of the top border edge, including the top-left and
/// top-right corner caps. Coordinates are relative to the border-box origin.
///
/// `outer`/`inner` are the four corner radii in CSS order; the inner arcs are
/// concentric with the outer arcs.
fn top_border_strip(
    w: f32,
    bl: f32,
    bt: f32,
    br: f32,
    outer: [(f32, f32); 4],
    inner: [(f32, f32); 4],
) -> Path {
    let (rtl_x, rtl_y) = outer[0];
    let (rtr_x, rtr_y) = outer[1];
    let (itl_x, itl_y) = inner[0];
    let (itr_x, itr_y) = inner[1];
    let mut path = Path::new();
    path.move_to(0.0, rtl_y);
    append_quarter_ellipse(
        &mut path,
        rtl_x,
        rtl_y,
        rtl_x,
        rtl_y,
        (0.0, rtl_y),
        (rtl_x, 0.0),
    );
    path.line_to(w - rtr_x, 0.0);
    append_quarter_ellipse(
        &mut path,
        w - rtr_x,
        rtr_y,
        rtr_x,
        rtr_y,
        (w - rtr_x, 0.0),
        (w, rtr_y),
    );
    // Draw the top edge line to the start of the inner top‑right corner.
    // Use the right border width (`br`) for the outer edge, then transition to the inner radius.
    path.line_to(w - br, rtr_y);
    // Inner top‑right corner: connect outer edge to inner edge.
    // The start point is at the outer edge (`w - br`, `rtr_y`),
    // and the end point aligns with the inner radius.
    append_quarter_ellipse(
        &mut path,
        w - rtr_x - br,
        rtr_y - bt,
        itr_x,
        itr_y,
        (w - br, rtr_y),
        (w - rtr_x - br, bt),
    );
    path.line_to(itl_x, bt);
    append_quarter_ellipse(
        &mut path,
        rtl_x - bl,
        rtl_y - bt,
        itl_x,
        itl_y,
        (itl_x, bt),
        (bl, rtl_y),
    );
    path.close();
    path
}

/// Build the closed path of the bottom border edge, including the bottom-left
/// and bottom-right corner caps.
fn bottom_border_strip(
    w: f32,
    h: f32,
    bl: f32,
    bb: f32,
    br: f32,
    outer: [(f32, f32); 4],
    inner: [(f32, f32); 4],
) -> Path {
    let (rbl_x, rbl_y) = outer[3];
    let (rbr_x, rbr_y) = outer[2];
    let (ibl_x, ibl_y) = inner[3];
    let (ibr_x, ibr_y) = inner[2];
    let mut path = Path::new();
    path.move_to(w, h - rbr_y);
    append_quarter_ellipse(
        &mut path,
        w - rbr_x,
        h - rbr_y,
        rbr_x,
        rbr_y,
        (w, h - rbr_y),
        (w - rbr_x, h),
    );
    path.line_to(rbl_x, h);
    append_quarter_ellipse(
        &mut path,
        rbl_x,
        h - rbl_y,
        rbl_x,
        rbl_y,
        (rbl_x, h),
        (0.0, h - rbl_y),
    );
    path.line_to(bl, h - rbl_y);
    append_quarter_ellipse(
        &mut path,
        rbl_x,
        h - rbl_y,
        ibl_x,
        ibl_y,
        (bl, h - rbl_y),
        (rbl_x, h - bb),
    );
    path.line_to(w - rbr_x, h - bb);
    append_quarter_ellipse(
        &mut path,
        w - rbr_x,
        h - rbr_y,
        ibr_x,
        ibr_y,
        (w - rbr_x, h - bb),
        (w - br, h - rbr_y),
    );
    path.close();
    path
}

/// Draw the four border edges inside the current coordinate system.
/// Coordinates are relative to the border-box origin when `ox`/`oy` are zero
/// (the transform case); otherwise they are added to place the border in
/// absolute space (the inline case, where no transform is pushed).
fn draw_border(
    cmd_buf: &mut Vec<DrawCommand>,
    border_box: &ui_layout::Rect,
    padding_box: &ui_layout::Rect,
    style: &ContainerStyle,
    ox: f32,
    oy: f32,
    opacity: f32,
) {
    let bw_top = (padding_box.y - border_box.y).max(0.0);
    let bw_bottom =
        (border_box.y + border_box.height - (padding_box.y + padding_box.height)).max(0.0);
    let bw_left = (padding_box.x - border_box.x).max(0.0);
    let bw_right = (border_box.x + border_box.width - (padding_box.x + padding_box.width)).max(0.0);

    let w = border_box.width;
    let h = border_box.height;
    let mut outer = resolve_outer_radii(&style.border_radius, w, h);
    outer = clamp_radii(outer, w, h);
    let mut inner = inner_radii(outer, bw_left, bw_top, bw_right, bw_bottom);
    inner = clamp_radii(
        inner,
        padding_box.width.max(0.0),
        padding_box.height.max(0.0),
    );

    let bc = &style.border_color;
    let bs = &style.border_style;
    let push_fill = |cmd_buf: &mut Vec<DrawCommand>, path: Path, color: Color| {
        cmd_buf.push(DrawCommand::Fill {
            path,
            rule: FillRule::NonZero,
            paint: Paint {
                brush: Brush::Solid(color),
                opacity,
            },
        });
    };

    let has_radius = outer.iter().any(|(rx, ry)| *rx > 0.0 || *ry > 0.0);
    if !has_radius {
        if bw_top > 0.0 && bs.top != crate::engine::layouter::types::BorderStyle::None {
            push_fill(cmd_buf, rect_path(ox, oy, w, bw_top), bc.top);
        }
        if bw_bottom > 0.0 && bs.bottom != crate::engine::layouter::types::BorderStyle::None {
            push_fill(
                cmd_buf,
                rect_path(ox, oy + h - bw_bottom, w, bw_bottom),
                bc.bottom,
            );
        }
        if bw_left > 0.0 && bs.left != crate::engine::layouter::types::BorderStyle::None {
            push_fill(
                cmd_buf,
                rect_path(ox, oy + bw_top, bw_left, h - bw_top - bw_bottom),
                bc.left,
            );
        }
        if bw_right > 0.0 && bs.right != crate::engine::layouter::types::BorderStyle::None {
            push_fill(
                cmd_buf,
                rect_path(
                    ox + w - bw_right,
                    oy + bw_top,
                    bw_right,
                    h - bw_top - bw_bottom,
                ),
                bc.right,
            );
        }
        return;
    }

    if bw_top > 0.0 && bs.top != crate::engine::layouter::types::BorderStyle::None {
        push_fill(
            cmd_buf,
            offset_path(
                &top_border_strip(w, bw_left, bw_top, bw_right, outer, inner),
                ox,
                oy,
            ),
            bc.top,
        );
    }
    if bw_bottom > 0.0 && bs.bottom != crate::engine::layouter::types::BorderStyle::None {
        push_fill(
            cmd_buf,
            offset_path(
                &bottom_border_strip(w, h, bw_left, bw_bottom, bw_right, outer, inner),
                ox,
                oy,
            ),
            bc.bottom,
        );
    }
    if bw_left > 0.0 && bs.left != crate::engine::layouter::types::BorderStyle::None {
        push_fill(
            cmd_buf,
            rect_path(ox, oy + outer[0].1, bw_left, h - outer[0].1 - outer[3].1),
            bc.left,
        );
    }
    if bw_right > 0.0 && bs.right != crate::engine::layouter::types::BorderStyle::None {
        push_fill(
            cmd_buf,
            rect_path(
                ox + w - bw_right,
                oy + outer[1].1,
                bw_right,
                h - outer[1].1 - outer[2].1,
            ),
            bc.right,
        );
    }
}

/// Draw the background inside the padding box (rounded when a border radius
/// is present).
/// Coordinates are relative to the border-box origin when `ox`/`oy` are zero;
/// otherwise they are added to place the background in absolute space.
fn draw_background(
    cmd_buf: &mut Vec<DrawCommand>,
    border_box: &ui_layout::Rect,
    padding_box: &ui_layout::Rect,
    style: &ContainerStyle,
    ox: f32,
    oy: f32,
    opacity: f32,
) {
    let x = padding_box.x - border_box.x + ox;
    let y = padding_box.y - border_box.y + oy;
    let bw_top = (padding_box.y - border_box.y).max(0.0);
    let bw_bottom =
        (border_box.y + border_box.height - (padding_box.y + padding_box.height)).max(0.0);
    let bw_left = (padding_box.x - border_box.x).max(0.0);
    let bw_right = (border_box.x + border_box.width - (padding_box.x + padding_box.width)).max(0.0);

    let mut outer = resolve_outer_radii(&style.border_radius, border_box.width, border_box.height);
    outer = clamp_radii(outer, border_box.width, border_box.height);
    let mut inner = inner_radii(outer, bw_left, bw_top, bw_right, bw_bottom);
    inner = clamp_radii(
        inner,
        padding_box.width.max(0.0),
        padding_box.height.max(0.0),
    );
    // Build the rounded background path
    let path = rounded_rect_path(
        x,
        y,
        padding_box.width,
        padding_box.height,
        inner[0],
        inner[1],
        inner[2],
        inner[3],
    );
    // CSS paints the background color beneath every image/gradient layer.
    if let Some(color) = style.background.color
        && color.3 > 0
    {
        cmd_buf.push(DrawCommand::Fill {
            path: path.clone(),
            rule: FillRule::NonZero,
            paint: Paint {
                brush: Brush::Solid(color),
                opacity,
            },
        });
    }

    // Image/gradient layers are stored bottom-to-top; paint top-to-bottom.
    // Each layer carries its own position/size/repeat geometry.
    for layer in style.background.layers.iter().rev() {
        let layer_repeat = layer.repeat;
        let layer_size = layer.size;
        let layer_position = layer.position;

        match &layer.image {
            Some(BackgroundImage::Gradient(g)) => {
                cmd_buf.push(DrawCommand::Fill {
                    path: path.clone(),
                    rule: FillRule::NonZero,
                    paint: Paint {
                        brush: Brush::Gradient(g.clone()),
                        opacity,
                    },
                });
            }
            Some(BackgroundImage::Image {
                source: _,
                image: Some(image),
            }) => {
                let (image_width, image_height) = resolve_background_image_size(
                    image.width() as f32,
                    image.height() as f32,
                    padding_box.width,
                    padding_box.height,
                    layer_size,
                );
                if image_width > 0.0 && image_height > 0.0 {
                    let image_x =
                        resolve_background_axis(padding_box.width, image_width, layer_position.x);
                    let image_y =
                        resolve_background_axis(padding_box.height, image_height, layer_position.y);
                    let repeat_x = matches!(
                        layer_repeat,
                        BackgroundRepeat::Repeat | BackgroundRepeat::RepeatX
                    );
                    let repeat_y = matches!(
                        layer_repeat,
                        BackgroundRepeat::Repeat | BackgroundRepeat::RepeatY
                    );
                    let xs = background_tile_positions(
                        image_x,
                        image_width,
                        padding_box.width,
                        repeat_x,
                    );
                    let ys = background_tile_positions(
                        image_y,
                        image_height,
                        padding_box.height,
                        repeat_y,
                    );
                    cmd_buf.push(DrawCommand::PushClip {
                        path: path.clone(),
                        rule: FillRule::NonZero,
                    });
                    for tile_y in ys {
                        for tile_x in &xs {
                            cmd_buf.push(DrawCommand::Fill {
                                path: rect_path(x + *tile_x, y + tile_y, image_width, image_height),
                                rule: FillRule::NonZero,
                                paint: Paint {
                                    brush: Brush::Image(image.clone()),
                                    opacity,
                                },
                            });
                        }
                    }
                    cmd_buf.push(DrawCommand::PopClip);
                }
            }
            Some(BackgroundImage::Image { image: None, .. }) => {}
            None => {}
        }
    }
}

fn resolve_background_dimension(dimension: BackgroundDimension, area: f32) -> Option<f32> {
    match dimension {
        BackgroundDimension::Auto => None,
        BackgroundDimension::Length(value) => Some(value.max(0.0)),
        BackgroundDimension::Percent(value) => Some((area * value).max(0.0)),
    }
}

fn resolve_background_image_size(
    intrinsic_width: f32,
    intrinsic_height: f32,
    area_width: f32,
    area_height: f32,
    size: BackgroundSize,
) -> (f32, f32) {
    if intrinsic_width <= 0.0 || intrinsic_height <= 0.0 {
        return (0.0, 0.0);
    }
    let ratio = intrinsic_width / intrinsic_height;
    match size {
        BackgroundSize::Auto => (intrinsic_width, intrinsic_height),
        BackgroundSize::Contain | BackgroundSize::Cover => {
            let width_scale = area_width / intrinsic_width;
            let height_scale = area_height / intrinsic_height;
            let scale = if matches!(size, BackgroundSize::Contain) {
                width_scale.min(height_scale)
            } else {
                width_scale.max(height_scale)
            };
            (intrinsic_width * scale, intrinsic_height * scale)
        }
        BackgroundSize::Explicit { width, height } => {
            let width = resolve_background_dimension(width, area_width);
            let height = resolve_background_dimension(height, area_height);
            match (width, height) {
                (Some(width), Some(height)) => (width, height),
                (Some(width), None) => (width, width / ratio),
                (None, Some(height)) => (height * ratio, height),
                (None, None) => (intrinsic_width, intrinsic_height),
            }
        }
    }
}

fn resolve_background_axis(area: f32, image: f32, position: BackgroundPositionAxis) -> f32 {
    let available = area - image;
    let length_offset = |offset| match offset {
        BackgroundOffset::Zero => 0.0,
        BackgroundOffset::Length(value) => value,
        BackgroundOffset::Percent(value) => area * value,
    };
    match position {
        BackgroundPositionAxis::Start(BackgroundOffset::Percent(value)) => available * value,
        BackgroundPositionAxis::Start(offset) => length_offset(offset),
        BackgroundPositionAxis::Center(offset) => available * 0.5 + length_offset(offset),
        BackgroundPositionAxis::End(offset) => available - length_offset(offset),
    }
}

fn background_tile_positions(base: f32, tile: f32, area: f32, repeat: bool) -> Vec<f32> {
    if !repeat || tile <= 0.0 {
        return vec![base];
    }
    let mut start = base;
    while start > 0.0 {
        start -= tile;
    }
    while start + tile <= 0.0 {
        start += tile;
    }
    let mut positions = Vec::new();
    let mut position = start;
    while position < area && positions.len() < 512 {
        positions.push(position);
        position += tile;
    }
    positions
}

/// Convert a [`ClipPath`] definition into a concrete [`Path`] resolved
/// against the element's border-box dimensions.
fn clip_path_to_path(clip: &ClipPath, w: f32, h: f32) -> Path {
    match clip {
        ClipPath::None => rect_path(0.0, 0.0, w, h),
        ClipPath::Circle {
            radius,
            center_x,
            center_y,
        } => {
            let cx = center_x * w;
            let cy = center_y * h;
            // `radius` is a fraction of farthest-side (max(w, h)) per CSS.
            let farthest = w.max(h);
            let r = (radius * farthest).min(farthest);
            ellipse_path(cx, cy, r, r)
        }
        ClipPath::Ellipse {
            rx,
            ry,
            center_x,
            center_y,
        } => {
            let cx = center_x * w;
            let cy = center_y * h;
            ellipse_path(cx, cy, rx * w, ry * h)
        }
        ClipPath::Inset {
            top,
            right,
            bottom,
            left,
        } => {
            let x = left * w;
            let y = top * h;
            let iw = (w - left * w - right * w).max(0.0);
            let ih = (h - top * h - bottom * h).max(0.0);
            rect_path(x, y, iw, ih)
        }
        ClipPath::Polygon { points } => {
            let verts: Vec<(f32, f32)> = points.iter().map(|(px, py)| (px * w, py * h)).collect();
            polygon_path(&verts)
        }
    }
}

/// Whether a [`ClipPath`] resolves to an empty shape against a box of the
/// given border-box size (so the element and every descendant are invisible).
fn clip_path_is_empty(clip: &ClipPath, w: f32, h: f32) -> bool {
    match clip {
        ClipPath::None => false,
        ClipPath::Circle { radius, .. } => *radius <= 0.0 || w <= 0.0 || h <= 0.0,
        ClipPath::Ellipse { rx, ry, .. } => *rx <= 0.0 || *ry <= 0.0 || w <= 0.0 || h <= 0.0,
        ClipPath::Inset {
            top,
            right,
            bottom,
            left,
        } => {
            (w - left * w - right * w).max(0.0) <= 0.0 || (h - top * h - bottom * h).max(0.0) <= 0.0
        }
        ClipPath::Polygon { points } => points.len() < 3,
    }
}

/// Push all draw commands for a single box model, returning the pop state.
#[allow(clippy::too_many_arguments)]
fn push_box_model(
    cmd_buf: &mut Vec<DrawCommand>,
    box_model: &ui_layout::BoxModel,
    style: &crate::engine::layouter::types::ContainerStyle,
    scroll_offset_x: f32,
    scroll_offset_y: f32,
    is_inline: bool,
    clips_overflow: bool,
    draw_bg: bool,
    paint: bool,
    opacity: f32,
) -> BoxPushState {
    let border_box = box_model.border_box;
    let padding_box = box_model.padding_box;
    let content_box = box_model.content_box;

    let dx = content_box.x - border_box.x;
    let dy = content_box.y - border_box.y;

    // Inline containers lay their text out in the parent's coordinate space,
    // and every line span yields its own box model, so no transform may be
    // pushed here: otherwise the accumulated border/content offsets of all
    // line boxes would displace the inline content.
    let border = !is_inline && push_transform(cmd_buf, border_box.x, border_box.y);

    // Apply the element's CSS `transform` about the element's center
    // (CSS `transform-origin` defaults to `50% 50%`). The border translation
    // above moved the origin to the border-box top-left, so we sandwich the
    // transform with a translate to/from the center.
    let transform = !is_inline
        && style
            .transform
            .is_some_and(|t| t != AffineTransform::identity())
        && {
            let center_x = border_box.width / 2.0;
            let center_y = border_box.height / 2.0;
            let t = style.transform.expect("checked above");
            let centered = AffineTransform::translate(center_x, center_y)
                .then(&t)
                .then(&AffineTransform::translate(-center_x, -center_y));
            cmd_buf.push(DrawCommand::PushTransform {
                transform: centered,
            });
            true
        };

    // When no transform is pushed (inline), draw commands must use absolute
    // coordinates; otherwise they are already relative to the border-box
    // origin thanks to the transform above.
    let (ox, oy) = if is_inline {
        (border_box.x, border_box.y)
    } else {
        (0.0, 0.0)
    };

    // Push clip-path clip before drawing borders/backgrounds so the shape
    // clips the entire element (border-box per CSS spec).
    let clip_path_pushed = !is_inline
        && !matches!(style.clip_path, ClipPath::None)
        && border_box.width > 0.0
        && border_box.height > 0.0;

    // A zero-area clip-path (e.g. GitHub's `clip-path: rect(0 0 0 0)` on
    // `.sr-only` elements) hides the element and every descendant.
    let clip_culls = clip_path_pushed
        && clip_path_is_empty(&style.clip_path, border_box.width, border_box.height);

    // Culled subtrees draw nothing; drop the clip-path clip as well (the
    // zero-area rect is pure overhead).
    let clip_path_pushed = clip_path_pushed && !clip_culls;
    if clip_path_pushed {
        let path = clip_path_to_path(&style.clip_path, border_box.width, border_box.height);
        cmd_buf.push(DrawCommand::PushClip {
            path,
            rule: FillRule::NonZero,
        });
    }

    // A `visibility: hidden` element paints neither borders nor backgrounds,
    // but still establishes its transforms/clips so explicitly visible
    // descendants are positioned and clipped correctly.
    if paint && !clip_culls {
        draw_border(cmd_buf, &border_box, &padding_box, style, ox, oy, opacity);

        if draw_bg {
            draw_background(cmd_buf, &border_box, &padding_box, style, ox, oy, opacity);
        }
    }

    // Everything below is invisible when culling; drop the clip-path and
    // overflow clips (and their pops) instead of emitting empty regions.
    let overflow_clip = !clip_culls
        && !is_inline
        && clips_overflow
        && padding_box.width > 0.0
        && padding_box.height > 0.0;
    if overflow_clip {
        cmd_buf.push(DrawCommand::PushClip {
            path: rect_path(
                padding_box.x - border_box.x,
                padding_box.y - border_box.y,
                padding_box.width,
                padding_box.height,
            ),
            rule: FillRule::NonZero,
        });
    }

    let content = !is_inline && push_transform(cmd_buf, dx, dy);
    let scroll = !is_inline && push_transform(cmd_buf, -scroll_offset_x, -scroll_offset_y);

    BoxPushState {
        border,
        transform,
        clip_path: clip_path_pushed,
        overflow_clip,
        content,
        scroll,
        cull: clip_culls,
    }
}

/// Pop commands for a single box model (reverse order of pushes).
fn pop_box_model(cmd_buf: &mut Vec<DrawCommand>, state: BoxPushState) {
    if state.scroll {
        cmd_buf.push(DrawCommand::PopTransform);
    }
    if state.content {
        cmd_buf.push(DrawCommand::PopTransform);
    }
    if state.overflow_clip {
        cmd_buf.push(DrawCommand::PopClip);
    }
    if state.clip_path {
        cmd_buf.push(DrawCommand::PopClip);
    }
    if state.transform {
        cmd_buf.push(DrawCommand::PopTransform);
    }
    if state.border {
        cmd_buf.push(DrawCommand::PopTransform);
    }
}

/// Draw text spans for a single text node.
fn draw_text(
    cmd_buf: &mut Vec<DrawCommand>,
    style: &TextStyle,
    flow_style: TextFlowStyle,
    text_id: usize,
    offset: (f32, f32),
    opacity: f32,
) {
    if let Some(result) = TextFlowLayouter::get_result(text_id) {
        // Text is composited directly onto the page surface, so multiplying
        // the color alpha by `opacity` is equivalent to a real opacity layer.
        let mut style = style.clone();
        style.color.3 = (style.color.3 as f32 * opacity).round() as u8;
        for (i, line_text) in result.line_texts.iter().enumerate() {
            let span = &result.spans[i];
            let x = span.line_pos.0 + offset.0;
            let y = span.line_pos.1 + offset.1;

            cmd_buf.push(DrawCommand::DrawText {
                x,
                y,
                text: line_text.as_str().into(),
                style: style.clone(),
                flow_style,
            });

            let font_size = flow_style.font_size;
            let line_thickness = (font_size * 0.08).max(1.0);
            let line_y_adj = if line_text.is_empty() {
                y
            } else {
                y + font_size
            };
            let (line_y, draw) = match style.text_decoration {
                TextDecoration::None => (0.0, false),
                TextDecoration::Underline => (line_y_adj, true),
                TextDecoration::LineThrough => (y + font_size * 0.5, true),
                TextDecoration::Overline => (y, true),
            };

            if draw {
                cmd_buf.push(DrawCommand::Fill {
                    path: rect_path(
                        x,
                        line_y,
                        span.x_range.end - span.x_range.start,
                        line_thickness,
                    ),
                    rule: FillRule::NonZero,
                    paint: Paint {
                        brush: Brush::Solid(style.text_decoration_color.unwrap_or(style.color)),
                        opacity,
                    },
                });
            }
        }
    }
}

// --------------------------------
// Public entry point
// --------------------------------

/// Paints the canvas background (CSS Backgrounds 3 §2.11.1): the root
/// element's background is propagated to the canvas and covers the entire
/// viewport, even when the root box is shorter than the viewport. The info
/// root is the document node, so when it is transparent the background of its
/// first element child (html) is propagated instead. Only solid colors are
/// propagated; the element still paints gradient/image backgrounds on its own
/// box.
fn emit_canvas_background(cmd_buf: &mut Vec<DrawCommand>, info: &InfoNode, viewport: (f32, f32)) {
    /// Check if a background has any visible content (non-transparent color
    /// or any image/gradient layers).
    fn has_visible_background(bg: &Background) -> bool {
        bg.color.is_some_and(|c| c.3 > 0) || !bg.layers.is_empty()
    }

    /// Resolve the canvas background per CSS 2.1 §14.2 / CSS Backgrounds 3:
    /// if the root element (html) has no visible background, the canvas
    /// background is the first body child's background.
    fn resolve_canvas_background(info: &InfoNode) -> Option<&Background> {
        // Find the html element: first Container child with tag "html".
        let html = info.children.iter().find(|child| {
            if let NodeKind::Container { style, .. } = &child.kind {
                style.tag.as_deref() == Some("html")
            } else {
                false
            }
        });

        match html {
            Some(html_info) => {
                let html_bg = html_info.kind.container_bg();
                if html_bg.is_some_and(has_visible_background) {
                    html_bg
                } else {
                    // Fall back to the first body child's background.
                    html_info.children.iter().find_map(|child| {
                        if let NodeKind::Container { style, .. } = &child.kind {
                            (style.tag.as_deref() == Some("body"))
                                .then_some(child.kind.container_bg())
                                .flatten()
                        } else {
                            None
                        }
                    })
                }
            }
            None => {
                // No html element found; fall back to the first visible
                // background color in the tree (root, then children).
                let solid_color = |bg: Option<&Background>| match bg {
                    Some(bg) if bg.color.is_some_and(|c| c.3 > 0) => Some(bg.color.unwrap()),
                    _ => None,
                };
                let child_bg = || {
                    info.children
                        .iter()
                        .find_map(|child| solid_color(child.kind.container_bg()))
                };
                solid_color(info.kind.container_bg())
                    .or_else(child_bg)
                    .and_then(|_| {
                        // Return a reference to the first background with visible color.
                        info.kind
                            .container_bg()
                            .filter(|bg| has_visible_background(bg))
                            .or_else(|| {
                                info.children.iter().find_map(|child| {
                                    child
                                        .kind
                                        .container_bg()
                                        .filter(|bg| has_visible_background(bg))
                                })
                            })
                    })
            }
        }
    }

    let background = resolve_canvas_background(info);
    let Some(bg) = background else {
        // Fall back to the previous behavior: first solid color found in the
        // tree (root, then children).
        let solid_color = |bg: Option<&Background>| match bg {
            Some(bg) if bg.color.is_some_and(|c| c.3 > 0) => Some(bg.color.unwrap()),
            _ => None,
        };
        let child_bg = || {
            info.children
                .iter()
                .find_map(|child| solid_color(child.kind.container_bg()))
        };
        let background = solid_color(info.kind.container_bg()).or_else(child_bg);
        let Some(color) = background else {
            return;
        };
        cmd_buf.push(DrawCommand::Fill {
            path: rect_path(0.0, 0.0, viewport.0, viewport.1),
            rule: FillRule::NonZero,
            paint: Paint {
                brush: Brush::Solid(color),
                opacity: 1.0,
            },
        });
        return;
    };

    // Paint solid color first (bottom-most layer).
    if let Some(color) = bg.color.filter(|c| c.3 > 0) {
        cmd_buf.push(DrawCommand::Fill {
            path: rect_path(0.0, 0.0, viewport.0, viewport.1),
            rule: FillRule::NonZero,
            paint: Paint {
                brush: Brush::Solid(color),
                opacity: 1.0,
            },
        });
    }

    // Paint image/gradient layers bottom-to-top, each covering the viewport.
    for layer in bg.layers.iter().rev() {
        match &layer.image {
            Some(BackgroundImage::Gradient(g)) => {
                cmd_buf.push(DrawCommand::Fill {
                    path: rect_path(0.0, 0.0, viewport.0, viewport.1),
                    rule: FillRule::NonZero,
                    paint: Paint {
                        brush: Brush::Gradient(g.clone()),
                        opacity: 1.0,
                    },
                });
            }
            Some(BackgroundImage::Image {
                image: Some(image), ..
            }) => {
                cmd_buf.push(DrawCommand::Fill {
                    path: rect_path(0.0, 0.0, viewport.0, viewport.1),
                    rule: FillRule::NonZero,
                    paint: Paint {
                        brush: Brush::Image(image.clone()),
                        opacity: 1.0,
                    },
                });
            }
            Some(BackgroundImage::Image { image: None, .. }) => {}
            None => {}
        }
    }
}

/// LayoutNode + InfoNode → DrawCommand
///
/// `viewport` is the visible (window) size of the page area; it establishes the
/// root scrollport that page-level `position: sticky` boxes stick to.
pub fn generate_draw_commands(
    cmd_buf: &mut Vec<DrawCommand>,
    layout: &LayoutNode,
    info: &InfoNode,
    viewport: (f32, f32),
) {
    emit_canvas_background(cmd_buf, info, viewport);
    let (scroll_x, scroll_y) = info.kind.scroll_offsets();
    let root_viewport = StickyViewport {
        top_left: (-scroll_x, scroll_y),
        size: viewport,
    };
    let containing = layout
        .layout_box
        .iter()
        .next()
        .map_or((0.0, 0.0), |b| (b.content_box.width, b.content_box.height));
    let origin = layout
        .layout_box
        .iter()
        .next()
        .map_or((0.0, 0.0), |b| (b.content_box.x, b.content_box.y));
    let mut popups: Vec<(Vec<DrawCommand>, (f32, f32))> = Vec::new();
    generate_draw_commands_inner(
        cmd_buf,
        layout,
        info,
        (0.0, 0.0),
        root_viewport,
        containing,
        origin,
        origin,
        &mut popups,
        1.0,
        true,
    );
    // Top-layer popups render after every other box, outside all ancestor
    // clips and transforms.
    for (commands, (tx, ty)) in popups {
        if tx != 0.0 || ty != 0.0 {
            cmd_buf.push(DrawCommand::PushTransform {
                transform: AffineTransform::translate(tx, ty),
            });
        }
        cmd_buf.extend(commands);
        if tx != 0.0 || ty != 0.0 {
            cmd_buf.push(DrawCommand::PopTransform);
        }
    }
}

/// Content-box origin of a child layout node in page space, derived from the
/// parent's page-space origin. Children are laid out relative to the parent's
/// content box, so the child's origin is the parent's origin plus the child's
/// content-box offset.
fn child_origin(child: &LayoutNode, parent_origin: (f32, f32)) -> (f32, f32) {
    child.layout_box.iter().next().map_or(parent_origin, |b| {
        (
            parent_origin.0 + b.content_box.x,
            parent_origin.1 + b.content_box.y,
        )
    })
}

/// Page-space origin of the transform a child subtree will run under. A
/// block-level container child pushes its own content transform, so its active
/// origin is its own; an inline container child that shares the parent's line
/// space pushes no transform and inherits the enclosing block's active origin.
/// A flow-root inline child (inline-block / blockified float) shares the
/// parent's line space for Y (ui_layout bakes the line position into its box
/// models) but owns its own box space for X, so its children run under its own
/// origin on both axes.
/// Custom elements push a box transform of their own even when laid out inline,
/// so the caller passes `child_origin` directly for those.
fn child_transform_origin(
    child: &LayoutNode,
    parent_origin: (f32, f32),
    inherited: (f32, f32),
) -> (f32, f32) {
    if matches!(child.layout_box, ui_layout::LayoutBox::InlineBox(_)) {
        inherited
    } else {
        child_origin(child, parent_origin)
    }
}

/// Recursive draw-command generation.
///
/// `accumulated_scroll` is the sum of the scroll offsets of every scrollable
/// ancestor, expressed in content space (`(x, y)`), i.e. the displacement the
/// current subtree inherits from ancestor scrolling. A `position: fixed` box
/// is positioned relative to the viewport, so the inherited displacement is
/// cancelled by pushing the inverse transform before its own box models and
/// resetting the accumulated scroll for its descendants.
///
/// `viewport` is the nearest scrollport as seen from this node's parent-content
/// space (used to resolve `position: sticky`), `containing` is this node's
/// parent content-box size (the containing block sticky boxes must stay in),
/// `origin` is this node's content-box origin in page space (unscrolled), and
/// `is_root` marks the document root, which always establishes the page
/// scrollport.
///
/// Open popups owned by custom nodes are collected (with the page-space
/// translation of their content-box origin) instead of being drawn inline, so
/// the caller can emit them above all page content.
#[allow(clippy::too_many_arguments)]
fn generate_draw_commands_inner(
    cmd_buf: &mut Vec<DrawCommand>,
    layout: &LayoutNode,
    info: &InfoNode,
    accumulated_scroll: (f32, f32),
    viewport: StickyViewport,
    containing: (f32, f32),
    origin: (f32, f32),
    transform_origin: (f32, f32),
    popups: &mut Vec<(Vec<DrawCommand>, (f32, f32))>,
    opacity: f32,
    is_root: bool,
) {
    // CSS `visibility` semantics: a hidden element paints nothing of its own
    // (box, borders, backgrounds, text) but still participates in layout, and
    // descendants with an explicit `visibility: visible` computed style DO
    // paint (computed visibility is already resolved per node by the style
    // builder, so a hidden ancestor does not force hidden descendants here).
    // Therefore the subtree must still be traversed; only this node's own
    // painting is suppressed.
    let self_hidden = matches!(
        &info.kind,
        NodeKind::Container { style, .. }
            | NodeKind::Custom { style, .. }
            | NodeKind::Svg { style, .. }
            if matches!(style.visibility, Visibility::Hidden | Visibility::Collapse)
    );

    // CSS `opacity` multiplies down the tree: an element with `opacity: 0.5`
    // renders itself and every descendant at half strength. `opacity` is the
    // product of all ancestors' opacities; `effective_opacity` folds this
    // node's own opacity in for its box, borders, backgrounds, text and SVG
    // content, and is passed to children as their inherited multiplier.
    let effective_opacity = {
        let own = match &info.kind {
            NodeKind::Container { style, .. }
            | NodeKind::Custom { style, .. }
            | NodeKind::Svg { style, .. } => style.opacity,
            _ => 1.0,
        };
        opacity * own
    };

    let mut box_states: Vec<BoxPushState> = Vec::new();

    let is_fixed = layout.style.position.kind == Position::Fixed;
    let is_sticky = layout.style.position.kind == Position::Sticky;
    let is_inline = matches!(layout.layout_box, ui_layout::LayoutBox::InlineBox(_));

    // Inline containers that establish their own inline formatting context
    // (display: inline-block, or a blockified float) nest their descendants in
    // their own content coordinate space. ui_layout lays those descendants out
    // relative to this box's content box on the X axis, but on the Y axis it
    // bakes this box's own line position into them (an inline box shares the
    // parent's line space). The content can therefore be translated by the
    // box's X offset only; Y is already carried by the styled coordinates and
    // must not be offset again. Plain inline boxes never translate.
    let establishes_inline_box_space = is_inline
        && layout.style.display.outer() == Some(OuterDisplay::Inline)
        && layout.style.display.inner() == Some(InnerDisplay::FlowRoot);

    let flow_root_inline_dx = if establishes_inline_box_space {
        origin.0 - transform_origin.0
    } else {
        0.0
    };

    // Cancel the inherited scroll displacement for fixed-position boxes.
    let cancel_scroll = is_fixed && (accumulated_scroll.0 != 0.0 || accumulated_scroll.1 != 0.0);
    if cancel_scroll {
        cmd_buf.push(DrawCommand::PushTransform {
            transform: AffineTransform::translate(-accumulated_scroll.0, accumulated_scroll.1),
        });
    }

    // Shift sticky boxes so each specified inset stays within the visible area
    // of the nearest scrollport. Fixed boxes are positioned relative to the
    // viewport, so sticky offsets never apply to them.
    let sticky_pushed = if is_sticky && !is_fixed {
        match layout.layout_box.iter().next() {
            Some(bm) => {
                let (dx, dy) = bm
                    .sticky_edges
                    .map(|edges| sticky_offset(&edges, &bm.border_box, viewport, containing))
                    .unwrap_or((0.0, 0.0));
                push_transform(cmd_buf, dx, dy)
            }
            None => false,
        }
    } else {
        false
    };

    match &info.kind {
        NodeKind::Text { .. } | NodeKind::LineBreak => unreachable!(),

        NodeKind::Container {
            scroll_x,
            scroll_y,
            scroll_offset_x,
            scroll_offset_y,
            style,
            ..
        } => {
            for box_model in &layout.layout_box {
                box_states.push(push_box_model(
                    cmd_buf,
                    &box_model,
                    style,
                    *scroll_offset_x,
                    *scroll_offset_y,
                    is_inline,
                    *scroll_x || *scroll_y,
                    true,
                    !self_hidden,
                    effective_opacity,
                ));
            }
        }

        // An inline SVG paints its viewBox-space subpaths into the content
        // box right after the box is established, à la `emit_canvas_background`.
        NodeKind::Svg {
            view_box,
            shapes,
            scroll_x,
            scroll_y,
            scroll_offset_x,
            scroll_offset_y,
            style,
            ..
        } => {
            for box_model in &layout.layout_box {
                box_states.push(push_box_model(
                    cmd_buf,
                    &box_model,
                    style,
                    *scroll_offset_x,
                    *scroll_offset_y,
                    is_inline,
                    *scroll_x || *scroll_y,
                    true,
                    !self_hidden,
                    effective_opacity,
                ));
            }

            // The vector content belongs to the element itself (like its borders
            // and background), so a hidden node paints nothing.
            if !self_hidden && let Some(bm) = layout.layout_box.iter().next() {
                emit_commands(
                    cmd_buf,
                    (
                        bm.content_box.x,
                        bm.content_box.y,
                        bm.content_box.width,
                        bm.content_box.height,
                    ),
                    is_inline,
                    *view_box,
                    shapes,
                    effective_opacity,
                );
            }
        }

        NodeKind::Custom {
            scroll_x,
            scroll_y,
            scroll_offset_x,
            scroll_offset_y,
            style,
            layout_style,
            node,
            text_style,
            text_flow_style,
            ..
        } => 'custom: {
            for box_model in &layout.layout_box {
                box_states.push(push_box_model(
                    cmd_buf,
                    &box_model,
                    style,
                    *scroll_offset_x,
                    *scroll_offset_y,
                    false,
                    *scroll_x || *scroll_y,
                    true,
                    !self_hidden,
                    effective_opacity,
                ));
            }

            // `display: none` / `display: contents` custom elements have no
            // laid-out box (`LayoutBox::None`); render nothing rather than
            // falling back to the component's intrinsic size.
            let base_box = match &layout.layout_box {
                ui_layout::LayoutBox::BlockBox(bm) => Some(bm.clone()),
                ui_layout::LayoutBox::InlineBox(ib) => Some(ib.box_model.clone()),
                _ => None,
            };
            let Some(size) = base_box.as_ref().map(|bm| ContentSize {
                width: bm.content_box.width,
                height: bm.content_box.height,
            }) else {
                break 'custom;
            };
            let culled = box_states.iter().any(|s| s.cull);
            if !self_hidden && !culled {
                node.draw_sized(cmd_buf, text_style, text_flow_style, layout_style, size);
            }
            // Collect open popups so they render above every other box,
            // outside all ancestor clips and transforms.
            if let Some(popup) = node.popup(text_style, text_flow_style) {
                let own_scroll = info.kind.scroll_offsets();
                // Fixed boxes are positioned relative to the viewport, so the
                // inherited scroll displacement does not move their popup.
                let inherited_scroll = if is_fixed {
                    (0.0, 0.0)
                } else {
                    accumulated_scroll
                };
                let (mut tx, mut ty) = (
                    origin.0 - inherited_scroll.0 - own_scroll.0,
                    origin.1 - inherited_scroll.1 - own_scroll.1,
                );
                // Sticky boxes shift their whole subtree (and thus their
                // popup) by the sticky offset.
                if is_sticky
                    && !is_fixed
                    && let Some(bm) = layout.layout_box.iter().next()
                    && let Some(edges) = bm.sticky_edges
                {
                    let (dx, dy) = sticky_offset(&edges, &bm.border_box, viewport, containing);
                    tx += dx;
                    ty += dy;
                }
                popups.push((popup.commands, (tx, ty)));
            }
        }
    }

    // A zero-area clip-path anywhere in this node's box stack hides the whole
    // subtree: skip painting it (transforms/clips stay balanced).
    let subtree_culled = box_states.iter().any(|s| s.cull);

    // Scroll offsets of this node itself; they scroll the node's own content.
    let own_scroll = info.kind.scroll_offsets();
    // A fixed box resets the inherited displacement (already cancelled above),
    // so its descendants only inherit its own scroll offset.
    let child_scroll = if is_fixed {
        own_scroll
    } else {
        (
            accumulated_scroll.0 + own_scroll.0,
            accumulated_scroll.1 + own_scroll.1,
        )
    };

    // Sticky viewport state for this node's subtree, rebased into each child's
    // parent-content space. A node that scrolls its own content (or the root,
    // which the UI layer scrolls directly) becomes the scrollport for its
    // descendants; otherwise the inherited visible region is shifted by the
    // node's content-box offset.
    let child_viewport = if is_root || is_scrollport(&info.kind) {
        let bm = layout.layout_box.iter().next();
        let (scroll_x, scroll_y) = own_scroll;
        StickyViewport {
            top_left: bm.as_ref().map_or((0.0, 0.0), |b| {
                (
                    b.padding_box.x - b.content_box.x - scroll_x,
                    b.padding_box.y - b.content_box.y + scroll_y,
                )
            }),
            size: if is_root {
                viewport.size
            } else {
                bm.map_or(viewport.size, |b| {
                    (b.padding_box.width, b.padding_box.height)
                })
            },
        }
    } else {
        let bm = layout.layout_box.iter().next();
        StickyViewport {
            top_left: bm.map_or(viewport.top_left, |b| {
                (
                    viewport.top_left.0 - b.content_box.x,
                    viewport.top_left.1 - b.content_box.y,
                )
            }),
            size: viewport.size,
        }
    };
    let child_containing = layout
        .layout_box
        .iter()
        .next()
        .map_or(containing, |b| (b.content_box.width, b.content_box.height));

    // A flow-root inline box (inline-block / blockified float) translates its
    // content by its own X offset within the active transform space; the Y
    // bake from ui_layout's line-space layout is left untouched.
    let flow_root_inline_pushed =
        flow_root_inline_dx != 0.0 && push_transform(cmd_buf, flow_root_inline_dx, 0.0);

    let mut layout_iter = layout.children.iter();
    let mut positive_stacking_children: Vec<(i32, usize, Vec<DrawCommand>)> = Vec::new();

    for (child_order, child_info) in info.children.iter().enumerate() {
        match &child_info.kind {
            NodeKind::Text {
                text_id,
                style,
                flow_style,
                ..
            } => {
                // Text belongs to its parent box, so a hidden parent hides it.
                if !self_hidden && !subtree_culled {
                    // Content is always drawn relative to the established box
                    // space: block and flow-root inline frames push their own
                    // transform, and plain inline text lives in the nearest
                    // enclosing block's line space.
                    draw_text(
                        cmd_buf,
                        style,
                        *flow_style,
                        *text_id,
                        (0.0, 0.0),
                        effective_opacity,
                    );
                }
                layout_iter.next();
            }
            NodeKind::LineBreak => {
                layout_iter.next();
            }
            NodeKind::Container { .. } | NodeKind::Svg { .. } => {
                if subtree_culled {
                    layout_iter.next();
                    continue;
                }
                if let Some(LayoutChild::Node(node)) = layout_iter.next() {
                    let child_origin = child_origin(node, origin);
                    // A plain inline frame pushes no transform of its own, so
                    // its box children inherit the enclosing block's active
                    // origin; a flow-root inline (or block) frame establishes
                    // its own box space, so inlines it contains are relative
                    // to its own content origin.
                    let inherited = if establishes_inline_box_space {
                        origin
                    } else {
                        transform_origin
                    };
                    let child_transform_origin = child_transform_origin(node, origin, inherited);
                    let z_index = child_info.kind.z_index();
                    if z_index > 0 {
                        let mut child_commands = Vec::new();
                        generate_draw_commands_inner(
                            &mut child_commands,
                            node,
                            child_info,
                            child_scroll,
                            child_viewport,
                            child_containing,
                            child_origin,
                            child_transform_origin,
                            popups,
                            effective_opacity,
                            false,
                        );
                        positive_stacking_children.push((z_index, child_order, child_commands));
                    } else {
                        generate_draw_commands_inner(
                            cmd_buf,
                            node,
                            child_info,
                            child_scroll,
                            child_viewport,
                            child_containing,
                            child_origin,
                            child_transform_origin,
                            popups,
                            effective_opacity,
                            false,
                        );
                    }
                }
            }
            NodeKind::Custom {
                node,
                text_style,
                text_flow_style,
                style,
                layout_style,
                ..
            } => {
                if subtree_culled {
                    layout_iter.next();
                    continue;
                }
                match layout_iter.next() {
                    // Block custom element: recurse into the child layout node.
                    Some(LayoutChild::Node(node_layout)) => {
                        let child_origin = child_origin(node_layout, origin);
                        // Custom elements always push a box transform of their
                        // own, even when laid out as inline boxes.
                        generate_draw_commands_inner(
                            cmd_buf,
                            node_layout,
                            child_info,
                            child_scroll,
                            child_viewport,
                            child_containing,
                            child_origin,
                            child_origin,
                            popups,
                            effective_opacity,
                            false,
                        );
                    }
                    // Inline custom element: consume the Object and draw it
                    // from the layout result stored on the tree child.
                    Some(LayoutChild::Custom(custom_child)) => {
                        if let Some(result) = custom_child.result() {
                            let bm = &result.box_model;
                            let rect = BoxModel {
                                sticky_edges: bm.sticky_edges,
                                border_box: bm.border_box,
                                padding_box: bm.padding_box,
                                content_box: bm.content_box,
                                children_box: bm.children_box,
                            };
                            let size = layout
                                .layout_box
                                .iter()
                                .next()
                                .map(|box_model| ContentSize {
                                    width: box_model.content_box.width,
                                    height: box_model.content_box.height,
                                })
                                .unwrap_or(ContentSize {
                                    width: rect.content_box.width,
                                    height: rect.content_box.height,
                                });
                            // The parent custom element owns CSS box painting;
                            // this bridge box only positions its intrinsic content.
                            let state = push_box_model(
                                cmd_buf,
                                &rect,
                                style,
                                0.0,
                                0.0,
                                false,
                                false,
                                false,
                                false,
                                effective_opacity,
                            );
                            node.draw_sized(
                                cmd_buf,
                                text_style,
                                text_flow_style,
                                layout_style,
                                size,
                            );
                            pop_box_model(cmd_buf, state);
                        }
                    }
                    _ => {}
                }
            }
        }
    }

    positive_stacking_children.sort_by_key(|(z_index, child_order, _)| (*z_index, *child_order));
    for (_, _, commands) in positive_stacking_children {
        cmd_buf.extend(commands);
    }

    if matches!(
        info.kind,
        NodeKind::Container { .. } | NodeKind::Custom { .. } | NodeKind::Svg { .. }
    ) {
        for state in box_states.iter().rev() {
            pop_box_model(cmd_buf, *state);
        }
    }

    if sticky_pushed {
        cmd_buf.push(DrawCommand::PopTransform);
    }

    if cancel_scroll {
        cmd_buf.push(DrawCommand::PopTransform);
    }

    if flow_root_inline_pushed {
        cmd_buf.push(DrawCommand::PopTransform);
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::engine::layouter::types::{BackgroundLayer, ContainerRole};
    use crate::engine::renderer_model::geom::AffineTransform;
    use crate::engine::ui::custom_node::{CustomNode, Popup};
    use std::sync::Arc;
    use ui_layout::Style;

    fn count_balanced(commands: &[DrawCommand]) -> bool {
        let mut transform_depth = 0usize;
        let mut clip_depth = 0usize;
        for cmd in commands {
            match cmd {
                DrawCommand::PushTransform { .. } => transform_depth += 1,
                DrawCommand::PopTransform => transform_depth -= 1,
                DrawCommand::PushClip { .. } => clip_depth += 1,
                DrawCommand::PopClip => clip_depth -= 1,
                _ => {}
            }
        }
        transform_depth == 0 && clip_depth == 0
    }

    #[test]
    fn test_push_pop_transform_balanced() {
        let mut buf = Vec::new();
        assert!(push_transform(&mut buf, 5.0, 5.0));
        assert!(matches!(buf.pop(), Some(DrawCommand::PushTransform { .. })));
        assert!(!push_transform(&mut buf, 0.0, 0.0));
    }

    #[test]
    fn test_radii_resolution_and_clamp() {
        let outer = resolve_outer_radii(&BorderRadius::default(), 100.0, 50.0);
        assert_eq!(outer, [(0.0, 0.0); 4]);
    }

    #[test]
    fn scratch_background_image_geometry_is_resolved() {
        let (width, height) = resolve_background_image_size(
            1200.0,
            600.0,
            800.0,
            400.0,
            BackgroundSize::Explicit {
                width: BackgroundDimension::Length(624.0),
                height: BackgroundDimension::Length(325.0),
            },
        );
        assert_eq!((width, height), (624.0, 325.0));
        assert_eq!(
            resolve_background_axis(
                800.0,
                width,
                BackgroundPositionAxis::End(BackgroundOffset::Zero),
            ),
            176.0
        );
        assert_eq!(
            resolve_background_axis(
                400.0,
                height,
                BackgroundPositionAxis::Center(BackgroundOffset::Zero),
            ),
            37.5
        );
    }

    #[test]
    fn background_contain_and_cover_preserve_aspect_ratio() {
        assert_eq!(
            resolve_background_image_size(200.0, 100.0, 300.0, 300.0, BackgroundSize::Contain,),
            (300.0, 150.0)
        );
        assert_eq!(
            resolve_background_image_size(200.0, 100.0, 300.0, 300.0, BackgroundSize::Cover),
            (600.0, 300.0)
        );
    }

    #[test]
    fn background_color_is_painted_below_gradient_layers() {
        use crate::engine::layouter::types::{Gradient, GradientKind, GradientSpread};

        let gradient = Gradient {
            kind: GradientKind::Linear { angle: 0.0 },
            stops: Vec::new(),
            spread: GradientSpread::Pad,
        };
        let style = ContainerStyle {
            background: Background {
                color: Some(Color(255, 0, 0, 255)),
                layers: vec![BackgroundLayer {
                    image: Some(crate::engine::layouter::types::BackgroundImage::Gradient(
                        gradient,
                    )),
                    position: Default::default(),
                    size: Default::default(),
                    repeat: Default::default(),
                }],
            },
            ..ContainerStyle::default()
        };
        let rect = ui_rect(0.0, 0.0, 100.0, 50.0);
        let mut cmd_buf = Vec::new();
        draw_background(&mut cmd_buf, &rect, &rect, &style, 0.0, 0.0, 1.0);

        let mut brushes = cmd_buf.iter().filter_map(|cmd| match cmd {
            DrawCommand::Fill { paint, .. } => Some(paint.brush.clone()),
            _ => None,
        });
        assert!(matches!(
            brushes.next(),
            Some(Brush::Solid(Color(255, 0, 0, 255)))
        ));
        assert!(matches!(brushes.next(), Some(Brush::Gradient(_))));
    }

    #[test]
    fn background_geometry_uses_the_original_layer_index() {
        use crate::engine::renderer_model::draw_command::Image;
        use crate::engine::renderer_model::path::PathCommand;

        let path_size = |path: &Path| {
            let mut max = (0.0f32, 0.0f32);
            for command in &path.commands {
                match command {
                    PathCommand::MoveTo { x, y } | PathCommand::LineTo { x, y } => {
                        max.0 = max.0.max(*x);
                        max.1 = max.1.max(*y);
                    }
                    _ => {}
                }
            }
            max
        };

        let top = Image::from_rgba(1, 1, vec![0, 0, 0, 0]).expect("top image");
        let bottom = Image::from_rgba(2, 1, vec![0; 8]).expect("bottom image");
        let top_id = top.id();
        let bottom_id = bottom.id();
        let style = ContainerStyle {
            background: Background {
                color: None,
                layers: vec![
                    BackgroundLayer {
                        image: Some(crate::engine::layouter::types::BackgroundImage::Image {
                            source: "top".into(),
                            image: Some(top),
                        }),
                        position: Default::default(),
                        size: BackgroundSize::Explicit {
                            width: BackgroundDimension::Length(10.0),
                            height: BackgroundDimension::Length(10.0),
                        },
                        repeat: BackgroundRepeat::NoRepeat,
                    },
                    BackgroundLayer {
                        image: Some(crate::engine::layouter::types::BackgroundImage::Image {
                            source: "bottom".into(),
                            image: Some(bottom),
                        }),
                        position: Default::default(),
                        size: BackgroundSize::Explicit {
                            width: BackgroundDimension::Length(20.0),
                            height: BackgroundDimension::Length(20.0),
                        },
                        repeat: BackgroundRepeat::NoRepeat,
                    },
                ],
            },
            ..ContainerStyle::default()
        };
        let rect = ui_rect(0.0, 0.0, 100.0, 100.0);
        let mut cmd_buf = Vec::new();
        draw_background(&mut cmd_buf, &rect, &rect, &style, 0.0, 0.0, 1.0);

        let fills: Vec<(u64, (f32, f32))> = cmd_buf
            .iter()
            .filter_map(|cmd| match cmd {
                DrawCommand::Fill {
                    path,
                    paint:
                        Paint {
                            brush: Brush::Image(image),
                            ..
                        },
                    ..
                } => Some((image.id(), path_size(path))),
                _ => None,
            })
            .collect();
        assert_eq!(
            fills,
            vec![(bottom_id, (20.0, 20.0)), (top_id, (10.0, 10.0))]
        );
    }

    fn ui_rect(x: f32, y: f32, w: f32, h: f32) -> ui_layout::Rect {
        ui_layout::Rect {
            x,
            y,
            width: w,
            height: h,
        }
    }

    #[derive(Debug)]
    struct DrawingNode;

    impl CustomNode for DrawingNode {
        fn draw_sized(
            &self,
            cmd_buf: &mut Vec<DrawCommand>,
            _text_style: &TextStyle,
            _text_flow_style: &TextFlowStyle,
            _style: &Style,
            size: ContentSize,
        ) {
            cmd_buf.push(DrawCommand::Fill {
                path: rect_path(0.0, 0.0, size.width, size.height),
                rule: FillRule::NonZero,
                paint: Paint {
                    brush: Brush::Solid(Color(255, 0, 0, 255)),
                    opacity: 1.0,
                },
            });
        }

        fn intrinsic_size(&self) -> ContentSize {
            ContentSize {
                width: 10.0,
                height: 10.0,
            }
        }
    }

    #[test]
    fn inline_custom_content_uses_its_flow_root_position_once() {
        let mut root = LayoutNode::new(Style::default());
        root.layout_box = ui_layout::LayoutBox::BlockBox(ui_layout::BoxModel {
            sticky_edges: None,
            border_box: ui_rect(0.0, 0.0, 200.0, 200.0),
            padding_box: ui_rect(0.0, 0.0, 200.0, 200.0),
            content_box: ui_rect(0.0, 0.0, 200.0, 200.0),
            children_box: ui_rect(0.0, 0.0, 200.0, 200.0),
        });

        let inline_style = Style {
            display: ui_layout::Display::parse("inline-block").unwrap(),
            ..Style::default()
        };
        let mut custom = LayoutNode::new(inline_style.clone());
        custom.layout_box = ui_layout::LayoutBox::InlineBox(ui_layout::InlineBox {
            box_model: ui_layout::BoxModel {
                sticky_edges: None,
                border_box: ui_rect(3.0, 10.0, 20.0, 20.0),
                padding_box: ui_rect(4.0, 11.0, 18.0, 18.0),
                content_box: ui_rect(8.0, 15.0, 10.0, 10.0),
                children_box: ui_rect(8.0, 15.0, 10.0, 10.0),
            },
            line_spans: vec![ui_layout::LineSpan {
                x_range: 0.0..10.0,
                line_pos: (3.0, 10.0),
                line_index: 0,
            }],
        });
        root.children = vec![LayoutChild::Node(Box::new(custom))];

        let root_info = mk_info_node(
            NodeKind::Container {
                scroll_x: false,
                scroll_y: false,
                scroll_offset_x: 0.0,
                scroll_offset_y: 0.0,
                style: ContainerStyle::default(),
                role: ContainerRole::Normal,
            },
            vec![mk_info_node(
                NodeKind::Custom {
                    node: Arc::new(DrawingNode),
                    scroll_x: false,
                    scroll_y: false,
                    scroll_offset_x: 0.0,
                    scroll_offset_y: 0.0,
                    style: ContainerStyle::default(),
                    layout_style: inline_style,
                    text_style: TextStyle::default(),
                    text_flow_style: TextFlowStyle::default(),
                },
                Vec::new(),
            )],
        );

        let mut commands = Vec::new();
        generate_draw_commands(&mut commands, &root, &root_info, (200.0, 200.0));
        assert!(count_balanced(&commands));

        let mut translations = Vec::new();
        for command in commands {
            match command {
                DrawCommand::PushTransform { transform } => {
                    translations.push(transform.apply(0.0, 0.0));
                }
                DrawCommand::Fill { paint, .. } => {
                    if !matches!(paint.brush, Brush::Solid(Color(255, 0, 0, 255))) {
                        translations.clear();
                        continue;
                    }
                    assert_eq!(translations, [(3.0, 10.0), (5.0, 5.0)]);
                    assert_eq!(
                        translations
                            .iter()
                            .fold((0.0, 0.0), |(x, y), (dx, dy)| { (x + dx, y + dy) }),
                        (8.0, 15.0)
                    );
                    return;
                }
                _ => {}
            }
        }
        panic!("custom content fill was not emitted");
    }

    #[test]
    fn test_single_box_model_is_balanced() {
        let box_model = ui_layout::BoxModel {
            sticky_edges: None,
            border_box: ui_rect(10.0, 20.0, 120.0, 60.0),
            padding_box: ui_rect(12.0, 22.0, 116.0, 56.0),
            content_box: ui_rect(12.0, 22.0, 116.0, 56.0),
            children_box: ui_rect(12.0, 22.0, 116.0, 56.0),
        };
        let style = ContainerStyle::default();
        let mut buf = Vec::new();
        let state = push_box_model(
            &mut buf, &box_model, &style, 0.0, 0.0, false, true, true, true, 1.0,
        );
        // Scroll/content transforms are no-ops here (zero offsets); border
        // transform + clip + content are pushed while the box is open.
        assert!(buf.len() >= 2);
        // Opening pushes are not yet balanced: a clip and transforms are pending.
        assert!(!count_balanced(&buf));
        pop_box_model(&mut buf, state);
        assert!(count_balanced(&buf));
    }

    #[test]
    fn transform_origin_is_element_center() {
        let box_model = ui_layout::BoxModel {
            sticky_edges: None,
            border_box: ui_rect(10.0, 20.0, 100.0, 50.0),
            padding_box: ui_rect(12.0, 22.0, 96.0, 46.0),
            content_box: ui_rect(12.0, 22.0, 96.0, 46.0),
            children_box: ui_rect(12.0, 22.0, 96.0, 46.0),
        };
        let style = ContainerStyle {
            transform: Some(AffineTransform::rotate(std::f32::consts::FRAC_PI_2)),
            ..Default::default()
        };
        let mut buf = Vec::new();
        let state = push_box_model(
            &mut buf, &box_model, &style, 0.0, 0.0, false, true, true, true, 1.0,
        );
        pop_box_model(&mut buf, state);

        // Commands: [border translate(10,20), centered transform, content translate(..)].
        let transforms: Vec<&AffineTransform> = buf
            .iter()
            .filter_map(|cmd| match cmd {
                DrawCommand::PushTransform { transform } => Some(transform),
                _ => None,
            })
            .collect();
        assert!(transforms.len() >= 2);
        let centered = transforms[1];

        // Expected: translate(50, 25) * rotate(90deg) * translate(-50, -25).
        let expected = AffineTransform::translate(50.0, 25.0)
            .then(&AffineTransform::rotate(std::f32::consts::FRAC_PI_2))
            .then(&AffineTransform::translate(-50.0, -25.0));
        assert!((centered.m11 - expected.m11).abs() < 1e-5);
        assert!((centered.m12 - expected.m12).abs() < 1e-5);
        assert!((centered.m21 - expected.m21).abs() < 1e-5);
        assert!((centered.m22 - expected.m22).abs() < 1e-5);
        assert!((centered.dx - expected.dx).abs() < 1e-5);
        assert!((centered.dy - expected.dy).abs() < 1e-5);

        // The element's center (local (50, 25)) must stay fixed under rotation.
        let (cx, cy) = centered.apply(50.0, 25.0);
        assert!((cx - 50.0).abs() < 1e-5, "center x = {cx}");
        assert!((cy - 25.0).abs() < 1e-5, "center y = {cy}");
    }

    #[test]
    fn visible_overflow_does_not_clip_block_contents() {
        let box_model = ui_layout::BoxModel {
            sticky_edges: None,
            border_box: ui_rect(0.0, 0.0, 100.0, 50.0),
            padding_box: ui_rect(0.0, 0.0, 100.0, 50.0),
            content_box: ui_rect(0.0, 0.0, 100.0, 50.0),
            children_box: ui_rect(0.0, 0.0, 120.0, 60.0),
        };
        let mut commands = Vec::new();
        let state = push_box_model(
            &mut commands,
            &box_model,
            &ContainerStyle::default(),
            0.0,
            0.0,
            false,
            false,
            true,
            true,
            1.0,
        );
        assert!(
            !commands
                .iter()
                .any(|command| matches!(command, DrawCommand::PushClip { .. }))
        );
        pop_box_model(&mut commands, state);
        assert!(count_balanced(&commands));
    }

    #[test]
    fn test_nested_box_models_balanced() {
        let mk_box = |x: f32, y: f32, w: f32, h: f32| ui_layout::BoxModel {
            sticky_edges: None,
            border_box: ui_rect(x, y, w, h),
            padding_box: ui_rect(x + 2.0, y + 2.0, w - 4.0, h - 4.0),
            content_box: ui_rect(x + 2.0, y + 2.0, w - 4.0, h - 4.0),
            children_box: ui_rect(x + 2.0, y + 2.0, w - 4.0, h - 4.0),
        };
        let style = ContainerStyle::default();
        let mut buf = Vec::new();
        let outer = push_box_model(
            &mut buf,
            &mk_box(0.0, 0.0, 100.0, 100.0),
            &style,
            3.0,
            4.0,
            false,
            true,
            true,
            true,
            1.0,
        );
        let inner = push_box_model(
            &mut buf,
            &mk_box(10.0, 10.0, 50.0, 50.0),
            &style,
            0.0,
            0.0,
            false,
            true,
            true,
            true,
            1.0,
        );
        // Sanity: inner push generated commands (border + background + clip).
        assert!(!buf.is_empty());
        pop_box_model(&mut buf, inner);
        pop_box_model(&mut buf, outer);
        assert!(count_balanced(&buf));
    }

    #[test]
    fn test_affine_transform_reexport() {
        let t = AffineTransform::translate(1.0, 2.0);
        assert_eq!(t.apply(0.0, 0.0), (1.0, 2.0));
    }

    /// Build an InfoNode subtree matching `generate_draw_commands`' expectation:
    /// `kind` (with `style`), `children` (each with `kind`).
    fn mk_info_node(kind: NodeKind, children: Vec<InfoNode>) -> InfoNode {
        InfoNode {
            kind,
            children,
            dom_id: None,
        }
    }

    fn hidden_container_info(children: Vec<InfoNode>) -> InfoNode {
        let style = ContainerStyle {
            visibility: Visibility::Hidden,
            ..ContainerStyle::default()
        };
        mk_info_node(
            NodeKind::Container {
                scroll_x: false,
                scroll_y: false,
                scroll_offset_x: 0.0,
                scroll_offset_y: 0.0,
                style,
                role: ContainerRole::Normal,
            },
            children,
        )
    }

    fn visible_container_info(children: Vec<InfoNode>) -> InfoNode {
        let style = ContainerStyle {
            background: Background {
                color: Some(Color(255, 0, 0, 255)),
                layers: Vec::new(),
            },
            ..ContainerStyle::default()
        };
        mk_info_node(
            NodeKind::Container {
                scroll_x: false,
                scroll_y: false,
                scroll_offset_x: 0.0,
                scroll_offset_y: 0.0,
                style,
                role: ContainerRole::Normal,
            },
            children,
        )
    }

    /// A `visibility: hidden` ancestor must NOT prune explicitly visible
    /// descendants: the hidden box paints nothing itself, but its visible
    /// children still emit draw commands (CSS `visibility` is per-element,
    /// unlike `display: none`). This is what Reddit's FOUC-guard CSS relies
    /// on (`:not(:defined) { visibility: hidden }` plus explicit
    /// `visibility: visible` on descendants).
    #[test]
    fn hidden_ancestor_does_not_prune_visible_descendants() {
        let ui_rect = |x: f32, y: f32, w: f32, h: f32| ui_layout::Rect {
            x,
            y,
            width: w,
            height: h,
        };
        let mk_box = |x: f32, y: f32, w: f32, h: f32| ui_layout::BoxModel {
            sticky_edges: None,
            border_box: ui_rect(x, y, w, h),
            padding_box: ui_rect(x, y, w, h),
            content_box: ui_rect(x, y, w, h),
            children_box: ui_rect(x, y, w, h),
        };

        // hidden ancestor (with a background) → visible child (with a background)
        let mut hidden_root = LayoutNode::new(Style::default());
        hidden_root.layout_box = ui_layout::LayoutBox::BlockBox(mk_box(0.0, 0.0, 100.0, 100.0));
        let mut visible_child = LayoutNode::new(Style::default());
        visible_child.layout_box = ui_layout::LayoutBox::BlockBox(mk_box(0.0, 0.0, 50.0, 50.0));
        hidden_root.children = vec![LayoutChild::Node(Box::new(visible_child))];

        let hidden_info = hidden_container_info(vec![visible_container_info(Vec::new())]);

        let mut commands = Vec::new();
        generate_draw_commands(&mut commands, &hidden_root, &hidden_info, (100.0, 100.0));

        // The visible descendant still generates commands.
        assert!(
            !commands.is_empty(),
            "visible descendants of a hidden ancestor must still draw"
        );
        assert!(count_balanced(&commands));
    }

    /// A fully hidden subtree (every node computed hidden) paints nothing:
    /// no backgrounds, borders, or text.
    #[test]
    fn fully_hidden_subtree_paints_nothing() {
        let ui_rect = |x: f32, y: f32, w: f32, h: f32| ui_layout::Rect {
            x,
            y,
            width: w,
            height: h,
        };
        let mk_box = |x: f32, y: f32, w: f32, h: f32| ui_layout::BoxModel {
            sticky_edges: None,
            border_box: ui_rect(x, y, w, h),
            padding_box: ui_rect(x, y, w, h),
            content_box: ui_rect(x, y, w, h),
            children_box: ui_rect(x, y, w, h),
        };

        let mut hidden_root = LayoutNode::new(Style::default());
        hidden_root.layout_box = ui_layout::LayoutBox::BlockBox(mk_box(0.0, 0.0, 100.0, 100.0));
        let mut hidden_child = LayoutNode::new(Style::default());
        hidden_child.layout_box = ui_layout::LayoutBox::BlockBox(mk_box(0.0, 0.0, 50.0, 50.0));
        hidden_root.children = vec![LayoutChild::Node(Box::new(hidden_child))];

        let hidden_info = hidden_container_info(vec![hidden_container_info(Vec::new())]);

        let mut commands = Vec::new();
        generate_draw_commands(&mut commands, &hidden_root, &hidden_info, (100.0, 100.0));

        assert!(
            commands.is_empty(),
            "a fully hidden subtree must not paint, got {commands:?}"
        );
    }

    /// Collect the sequence of scroll-related transforms in `commands` as
    /// `(translate_x, translate_y)` tuples, in order.
    fn scroll_translates(commands: &[DrawCommand]) -> Vec<(f32, f32)> {
        let mut tx: Vec<f32> = Vec::new();
        let mut ty: Vec<f32> = Vec::new();
        let mut out = Vec::new();
        for cmd in commands {
            match cmd {
                DrawCommand::PushTransform { transform } => {
                    tx.push(transform.apply(0.0, 0.0).0);
                    ty.push(transform.apply(0.0, 0.0).1);
                    out.push((transform.apply(0.0, 0.0).0, transform.apply(0.0, 0.0).1));
                }
                DrawCommand::PopTransform => {
                    if let (Some(x), Some(y)) = (tx.pop(), ty.pop()) {
                        out.push((-x, -y));
                    }
                }
                _ => {}
            }
        }
        out
    }

    #[test]
    fn fixed_node_cancels_inherited_scroll_offset() {
        let ui_rect = |x: f32, y: f32, w: f32, h: f32| ui_layout::Rect {
            x,
            y,
            width: w,
            height: h,
        };
        let mk_box = |x: f32, y: f32, w: f32, h: f32| ui_layout::BoxModel {
            sticky_edges: None,
            border_box: ui_rect(x, y, w, h),
            padding_box: ui_rect(x, y, w, h),
            content_box: ui_rect(x, y, w, h),
            children_box: ui_rect(x, y, w, h),
        };

        // A scrollable ancestor (scrolled by 50px) containing a fixed child.
        let scroller_style = Style::default();
        let mut scroller = LayoutNode::new(scroller_style);
        scroller.layout_box = ui_layout::LayoutBox::BlockBox(mk_box(0.0, 0.0, 100.0, 100.0));

        let mut fixed_style = Style::default();
        fixed_style.position.kind = Position::Fixed;
        let fixed = LayoutNode::new(fixed_style);
        scroller.children = vec![LayoutChild::Node(Box::new(fixed))];

        let scroller_info = mk_info_node(
            NodeKind::Container {
                scroll_x: true,
                scroll_y: true,
                scroll_offset_x: 0.0,
                scroll_offset_y: 50.0,
                style: ContainerStyle::default(),
                role: ContainerRole::Normal,
            },
            vec![mk_info_node(
                NodeKind::Container {
                    scroll_x: false,
                    scroll_y: false,
                    scroll_offset_x: 0.0,
                    scroll_offset_y: 0.0,
                    style: ContainerStyle::default(),
                    role: ContainerRole::Normal,
                },
                Vec::new(),
            )],
        );

        let mut commands = Vec::new();
        generate_draw_commands(&mut commands, &scroller, &scroller_info, (100.0, 100.0));
        assert!(count_balanced(&commands));

        // The fixed child must push a transform cancelling the ancestor's
        // 50px scroll: `(-0, +50)` cancels the inherited `(0, -50)`.
        let translates = scroll_translates(&commands);
        assert!(
            translates.contains(&(0.0, 50.0)),
            "expected a scroll-cancelling transform, got {translates:?}"
        );
    }

    #[test]
    fn positive_z_index_child_paints_after_later_normal_sibling() {
        let box_model = |x: f32| ui_layout::BoxModel {
            sticky_edges: None,
            border_box: ui_rect(x, 0.0, 50.0, 50.0),
            padding_box: ui_rect(x, 0.0, 50.0, 50.0),
            content_box: ui_rect(x, 0.0, 50.0, 50.0),
            children_box: ui_rect(x, 0.0, 50.0, 50.0),
        };
        let mut root = LayoutNode::new(Style::default());
        root.layout_box = ui_layout::LayoutBox::BlockBox(box_model(0.0));
        let mut front = LayoutNode::new(Style::default());
        front.layout_box = ui_layout::LayoutBox::BlockBox(box_model(0.0));
        let mut normal = LayoutNode::new(Style::default());
        normal.layout_box = ui_layout::LayoutBox::BlockBox(box_model(0.0));
        root.children = vec![
            LayoutChild::Node(Box::new(front)),
            LayoutChild::Node(Box::new(normal)),
        ];

        let child_info = |color, z_index| {
            mk_info_node(
                NodeKind::Container {
                    scroll_x: false,
                    scroll_y: false,
                    scroll_offset_x: 0.0,
                    scroll_offset_y: 0.0,
                    style: ContainerStyle {
                        background: Background {
                            color: Some(color),
                            layers: Vec::new(),
                        },
                        z_index,
                        ..ContainerStyle::default()
                    },
                    role: ContainerRole::Normal,
                },
                Vec::new(),
            )
        };
        let root_info = mk_info_node(
            NodeKind::Container {
                scroll_x: false,
                scroll_y: false,
                scroll_offset_x: 0.0,
                scroll_offset_y: 0.0,
                style: ContainerStyle::default(),
                role: ContainerRole::Normal,
            },
            vec![
                child_info(Color(255, 0, 0, 255), Some(10)),
                child_info(Color(0, 0, 255, 255), None),
            ],
        );

        let mut commands = Vec::new();
        generate_draw_commands(&mut commands, &root, &root_info, (100.0, 100.0));
        let colors: Vec<_> = commands
            .iter()
            .filter_map(|command| match command {
                DrawCommand::Fill {
                    paint:
                        Paint {
                            brush: Brush::Solid(color),
                            ..
                        },
                    ..
                } => Some(*color),
                _ => None,
            })
            .collect();
        assert_eq!(
            colors,
            vec![
                Color(255, 0, 0, 255),
                Color(0, 0, 255, 255),
                Color(255, 0, 0, 255)
            ]
        );
        assert!(count_balanced(&commands));
    }

    fn sticky_viewport(scroll: (f32, f32)) -> StickyViewport {
        StickyViewport {
            top_left: (-scroll.0, scroll.1),
            size: (800.0, 500.0),
        }
    }

    fn sticky_edges(top: Option<f32>, bottom: Option<f32>) -> EdgeOption {
        EdgeOption {
            left: None,
            top,
            right: None,
            bottom,
        }
    }

    #[test]
    fn test_sticky_offset_top_sticks_to_viewport_top() {
        // Natural y=600, viewport scrolled 600px: the box's top edge is pinned
        // at the viewport top + 10.
        let (dx, dy) = sticky_offset(
            &sticky_edges(Some(10.0), None),
            &ui_rect(0.0, 600.0, 100.0, 50.0),
            sticky_viewport((0.0, 600.0)),
            (800.0, 2000.0),
        );
        assert_eq!((dx, dy), (0.0, 10.0));
    }

    #[test]
    fn test_sticky_offset_bottom_pushes_up() {
        // Natural bottom (1000) is below the viewport bottom minus the inset
        // (490): the box is pulled up by 510.
        let (dx, dy) = sticky_offset(
            &sticky_edges(None, Some(10.0)),
            &ui_rect(0.0, 900.0, 100.0, 100.0),
            sticky_viewport((0.0, 0.0)),
            (800.0, 2000.0),
        );
        assert_eq!((dx, dy), (0.0, -510.0));
    }

    #[test]
    fn test_sticky_offset_no_movement_when_in_view() {
        let (dx, dy) = sticky_offset(
            &sticky_edges(Some(10.0), None),
            &ui_rect(0.0, 50.0, 100.0, 50.0),
            sticky_viewport((0.0, 0.0)),
            (800.0, 2000.0),
        );
        assert_eq!((dx, dy), (0.0, 0.0));
    }

    #[test]
    fn test_sticky_offset_containing_block_hi_clamp() {
        // A box taller than the visible area near the container end must not
        // be pushed past the containing block bottom (natural bottom is
        // already at 1300, the container end).
        let (dx, dy) = sticky_offset(
            &sticky_edges(Some(10.0), None),
            &ui_rect(0.0, 900.0, 100.0, 400.0),
            sticky_viewport((0.0, 900.0)),
            (800.0, 1300.0),
        );
        assert_eq!((dx, dy), (0.0, 0.0));
    }

    #[test]
    fn test_sticky_offset_inset_fit_ignores_end_edge_without_room() {
        // Both insets set but the sticky view rectangle is shorter than the
        // box: the bottom inset is ignored, the box sticks to its top edge.
        let (dx, dy) = sticky_offset(
            &sticky_edges(Some(10.0), Some(10.0)),
            &ui_rect(0.0, 100.0, 100.0, 500.0),
            sticky_viewport((0.0, 0.0)),
            (800.0, 2000.0),
        );
        assert_eq!((dx, dy), (0.0, 0.0));
    }

    #[test]
    fn test_sticky_offset_horizontal_right_pushes_left() {
        // Box spans [850, 950], off-screen right of the 800-wide viewport; a
        // right inset of 10 pulls it left so its right edge sits at 790.
        let edges = EdgeOption {
            left: None,
            top: None,
            right: Some(10.0),
            bottom: None,
        };
        let (dx, dy) = sticky_offset(
            &edges,
            &ui_rect(850.0, 0.0, 100.0, 50.0),
            sticky_viewport((0.0, 0.0)),
            (2000.0, 2000.0),
        );
        assert_eq!((dx, dy), (-160.0, 0.0));
    }

    #[test]
    fn sticky_node_pushes_sticky_offset_transform() {
        // Root acts as the page scrollport (scrolled 600px). A sticky child at
        // natural y=600 with top:10 must push a translate(0, 10).
        let ui_rect = |x: f32, y: f32, w: f32, h: f32| ui_layout::Rect {
            x,
            y,
            width: w,
            height: h,
        };
        let mk_box = |x: f32, y: f32, w: f32, h: f32| ui_layout::BoxModel {
            sticky_edges: None,
            border_box: ui_rect(x, y, w, h),
            padding_box: ui_rect(x, y, w, h),
            content_box: ui_rect(x, y, w, h),
            children_box: ui_rect(x, y, w, h),
        };

        let root_style = Style::default();
        let mut root = LayoutNode::new(root_style);
        root.layout_box = ui_layout::LayoutBox::BlockBox(mk_box(0.0, 0.0, 800.0, 2000.0));

        let mut sticky_style = Style::default();
        sticky_style.position.kind = Position::Sticky;
        let mut sticky = LayoutNode::new(sticky_style);
        let mut sticky_bm = mk_box(0.0, 600.0, 800.0, 100.0);
        sticky_bm.sticky_edges = Some(sticky_edges(Some(10.0), None));
        sticky.layout_box = ui_layout::LayoutBox::BlockBox(sticky_bm);
        root.children = vec![LayoutChild::Node(Box::new(sticky))];

        let root_info = mk_info_node(
            NodeKind::Container {
                scroll_x: false,
                scroll_y: false,
                scroll_offset_x: 0.0,
                scroll_offset_y: 600.0,
                style: ContainerStyle::default(),
                role: ContainerRole::Normal,
            },
            vec![mk_info_node(
                NodeKind::Container {
                    scroll_x: false,
                    scroll_y: false,
                    scroll_offset_x: 0.0,
                    scroll_offset_y: 0.0,
                    style: ContainerStyle::default(),
                    role: ContainerRole::Normal,
                },
                Vec::new(),
            )],
        );

        let mut commands = Vec::new();
        generate_draw_commands(&mut commands, &root, &root_info, (800.0, 500.0));
        assert!(count_balanced(&commands));

        let translates = scroll_translates(&commands);
        assert!(
            translates.contains(&(0.0, 10.0)),
            "expected a sticky top offset, got {translates:?}"
        );
    }

    #[test]
    fn sticky_node_bottom_pushes_up() {
        // Same setup but bottom:10, unscrolled, natural y=900: pulled up by 510.
        let ui_rect = |x: f32, y: f32, w: f32, h: f32| ui_layout::Rect {
            x,
            y,
            width: w,
            height: h,
        };
        let mk_box = |x: f32, y: f32, w: f32, h: f32| ui_layout::BoxModel {
            sticky_edges: None,
            border_box: ui_rect(x, y, w, h),
            padding_box: ui_rect(x, y, w, h),
            content_box: ui_rect(x, y, w, h),
            children_box: ui_rect(x, y, w, h),
        };

        let root_style = Style::default();
        let mut root = LayoutNode::new(root_style);
        root.layout_box = ui_layout::LayoutBox::BlockBox(mk_box(0.0, 0.0, 800.0, 2000.0));

        let mut sticky_style = Style::default();
        sticky_style.position.kind = Position::Sticky;
        let mut sticky = LayoutNode::new(sticky_style);
        let mut sticky_bm = mk_box(0.0, 900.0, 800.0, 100.0);
        sticky_bm.sticky_edges = Some(sticky_edges(None, Some(10.0)));
        sticky.layout_box = ui_layout::LayoutBox::BlockBox(sticky_bm);
        root.children = vec![LayoutChild::Node(Box::new(sticky))];

        let root_info = mk_info_node(
            NodeKind::Container {
                scroll_x: false,
                scroll_y: false,
                scroll_offset_x: 0.0,
                scroll_offset_y: 0.0,
                style: ContainerStyle::default(),
                role: ContainerRole::Normal,
            },
            vec![mk_info_node(
                NodeKind::Container {
                    scroll_x: false,
                    scroll_y: false,
                    scroll_offset_x: 0.0,
                    scroll_offset_y: 0.0,
                    style: ContainerStyle::default(),
                    role: ContainerRole::Normal,
                },
                Vec::new(),
            )],
        );

        let mut commands = Vec::new();
        generate_draw_commands(&mut commands, &root, &root_info, (800.0, 500.0));
        assert!(count_balanced(&commands));

        let translates = scroll_translates(&commands);
        assert!(
            translates.contains(&(0.0, -510.0)),
            "expected a sticky bottom offset, got {translates:?}"
        );
    }

    /// A custom node that reports an open popup with a single fill command.
    #[derive(Debug)]
    struct PopupNode {
        open: bool,
        box_height: f32,
        popup_height: f32,
    }

    impl CustomNode for PopupNode {
        fn draw_sized(
            &self,
            _cmd_buf: &mut Vec<DrawCommand>,
            _text_style: &TextStyle,
            _text_flow_style: &TextFlowStyle,
            _style: &Style,
            _size: ContentSize,
        ) {
        }

        fn intrinsic_size(&self) -> ContentSize {
            ContentSize {
                width: 120.0,
                height: self.box_height,
            }
        }

        fn popup(
            &self,
            _text_style: &TextStyle,
            _text_flow_style: &TextFlowStyle,
        ) -> Option<Popup> {
            self.open.then(|| Popup {
                rect: crate::engine::renderer_model::Rect {
                    x: 0.0,
                    y: self.box_height,
                    width: 120.0,
                    height: self.popup_height,
                },
                commands: vec![DrawCommand::Fill {
                    path: rect_path(0.0, self.box_height, 120.0, self.popup_height),
                    rule: FillRule::NonZero,
                    paint: Paint {
                        brush: Brush::Solid(Color(255, 0, 0, 255)),
                        opacity: 1.0,
                    },
                }],
            })
        }
    }

    #[test]
    fn popup_is_emitted_as_top_layer_at_node_position() {
        // A select-like node with an open popup nested inside a scrollable
        // container: node content origin (10+5, 20+0) = (15, 20), inherited
        // scroll offset 50 → popup translate (15, 20-50) = (15, -30).
        let node: Arc<dyn CustomNode> = Arc::new(PopupNode {
            open: true,
            box_height: 28.0,
            popup_height: 84.0,
        });

        let mk_box = |x: f32, y: f32, w: f32, h: f32| ui_layout::BoxModel {
            sticky_edges: None,
            border_box: ui_rect(x, y, w, h),
            padding_box: ui_rect(x, y, w, h),
            content_box: ui_rect(x, y, w, h),
            children_box: ui_rect(x, y, w, h),
        };

        let mut root = LayoutNode::new(Style::default());
        root.layout_box = ui_layout::LayoutBox::BlockBox(mk_box(0.0, 0.0, 200.0, 200.0));

        let mut scroller = LayoutNode::new(Style::default());
        scroller.layout_box = ui_layout::LayoutBox::BlockBox(mk_box(10.0, 20.0, 160.0, 100.0));

        let mut custom = LayoutNode::new(Style::default());
        custom.layout_box = ui_layout::LayoutBox::BlockBox(mk_box(5.0, 0.0, 120.0, 28.0));
        scroller.children = vec![LayoutChild::Node(Box::new(custom))];
        root.children = vec![LayoutChild::Node(Box::new(scroller))];

        let root_info = mk_info_node(
            NodeKind::Container {
                scroll_x: false,
                scroll_y: false,
                scroll_offset_x: 0.0,
                scroll_offset_y: 0.0,
                style: ContainerStyle::default(),
                role: ContainerRole::Normal,
            },
            vec![mk_info_node(
                NodeKind::Container {
                    scroll_x: false,
                    scroll_y: true,
                    scroll_offset_x: 0.0,
                    scroll_offset_y: 50.0,
                    style: ContainerStyle::default(),
                    role: ContainerRole::Normal,
                },
                vec![mk_info_node(
                    NodeKind::Custom {
                        node,
                        scroll_x: false,
                        scroll_y: false,
                        scroll_offset_x: 0.0,
                        scroll_offset_y: 0.0,
                        style: ContainerStyle::default(),
                        layout_style: Style::default(),
                        text_style: TextStyle::default(),
                        text_flow_style: TextFlowStyle::default(),
                    },
                    Vec::new(),
                )],
            )],
        );

        let mut commands = Vec::new();
        generate_draw_commands(&mut commands, &root, &root_info, (200.0, 200.0));
        assert!(count_balanced(&commands));

        // The default styles paint nothing, so the only fill in the buffer is
        // the popup, emitted after every clip/transform.
        let fills = commands
            .iter()
            .filter(|cmd| matches!(cmd, DrawCommand::Fill { .. }))
            .count();
        assert_eq!(fills, 1, "popup must be the only painted box");

        match &commands[commands.len() - 3..] {
            [
                DrawCommand::PushTransform { transform },
                DrawCommand::Fill { .. },
                DrawCommand::PopTransform,
            ] => {
                assert_eq!(transform.apply(0.0, 0.0), (15.0, -30.0));
            }
            _ => panic!("expected trailing popup PushTransform/Fill/PopTransform"),
        }
    }

    #[test]
    fn closed_popup_is_not_emitted() {
        let node: Arc<dyn CustomNode> = Arc::new(PopupNode {
            open: false,
            box_height: 28.0,
            popup_height: 84.0,
        });

        let mk_box = |x: f32, y: f32, w: f32, h: f32| ui_layout::BoxModel {
            sticky_edges: None,
            border_box: ui_rect(x, y, w, h),
            padding_box: ui_rect(x, y, w, h),
            content_box: ui_rect(x, y, w, h),
            children_box: ui_rect(x, y, w, h),
        };

        let mut root = LayoutNode::new(Style::default());
        root.layout_box = ui_layout::LayoutBox::BlockBox(mk_box(0.0, 0.0, 200.0, 200.0));
        let mut custom = LayoutNode::new(Style::default());
        custom.layout_box = ui_layout::LayoutBox::BlockBox(mk_box(0.0, 0.0, 120.0, 28.0));
        root.children = vec![LayoutChild::Node(Box::new(custom))];

        let root_info = mk_info_node(
            NodeKind::Container {
                scroll_x: false,
                scroll_y: false,
                scroll_offset_x: 0.0,
                scroll_offset_y: 0.0,
                style: ContainerStyle::default(),
                role: ContainerRole::Normal,
            },
            vec![mk_info_node(
                NodeKind::Custom {
                    node,
                    scroll_x: false,
                    scroll_y: false,
                    scroll_offset_x: 0.0,
                    scroll_offset_y: 0.0,
                    style: ContainerStyle::default(),
                    layout_style: Style::default(),
                    text_style: TextStyle::default(),
                    text_flow_style: TextFlowStyle::default(),
                },
                Vec::new(),
            )],
        );

        let mut commands = Vec::new();
        generate_draw_commands(&mut commands, &root, &root_info, (200.0, 200.0));
        assert!(count_balanced(&commands));
        assert_eq!(
            commands
                .iter()
                .filter(|cmd| matches!(cmd, DrawCommand::Fill { .. }))
                .count(),
            0
        );
    }

    #[test]
    fn canvas_background_inherits_from_body_when_html_has_none() {
        // html has no background, body has red → canvas paints red.
        let body_info = mk_info_node(
            NodeKind::Container {
                scroll_x: false,
                scroll_y: false,
                scroll_offset_x: 0.0,
                scroll_offset_y: 0.0,
                style: ContainerStyle {
                    background: Background {
                        color: Some(Color(255, 0, 0, 255)),
                        layers: Vec::new(),
                    },
                    tag: Some("body".to_string()),
                    ..ContainerStyle::default()
                },
                role: ContainerRole::Normal,
            },
            Vec::new(),
        );
        let html_info = mk_info_node(
            NodeKind::Container {
                scroll_x: false,
                scroll_y: false,
                scroll_offset_x: 0.0,
                scroll_offset_y: 0.0,
                style: ContainerStyle {
                    background: Background::default(),
                    tag: Some("html".to_string()),
                    ..ContainerStyle::default()
                },
                role: ContainerRole::Normal,
            },
            vec![body_info],
        );
        let root_info = mk_info_node(
            NodeKind::Container {
                scroll_x: false,
                scroll_y: false,
                scroll_offset_x: 0.0,
                scroll_offset_y: 0.0,
                style: ContainerStyle::default(),
                role: ContainerRole::Normal,
            },
            vec![html_info],
        );

        let mut commands = Vec::new();
        generate_draw_commands(
            &mut commands,
            &LayoutNode::new(Style::default()),
            &root_info,
            (100.0, 100.0),
        );

        let fills: Vec<_> = commands
            .iter()
            .filter_map(|cmd| match cmd {
                DrawCommand::Fill {
                    paint:
                        Paint {
                            brush: Brush::Solid(color),
                            ..
                        },
                    ..
                } => Some(*color),
                _ => None,
            })
            .collect();

        // Canvas paints body's red, then html paints (none), then body paints red again.
        assert!(
            fills.contains(&Color(255, 0, 0, 255)),
            "canvas should paint body's red background, got {fills:?}"
        );
    }

    #[test]
    fn canvas_background_uses_html_when_both_specified() {
        // html has green, body has red → canvas paints html's green (html wins).
        let body_info = mk_info_node(
            NodeKind::Container {
                scroll_x: false,
                scroll_y: false,
                scroll_offset_x: 0.0,
                scroll_offset_y: 0.0,
                style: ContainerStyle {
                    background: Background {
                        color: Some(Color(255, 0, 0, 255)),
                        layers: Vec::new(),
                    },
                    tag: Some("body".to_string()),
                    ..ContainerStyle::default()
                },
                role: ContainerRole::Normal,
            },
            Vec::new(),
        );
        let html_info = mk_info_node(
            NodeKind::Container {
                scroll_x: false,
                scroll_y: false,
                scroll_offset_x: 0.0,
                scroll_offset_y: 0.0,
                style: ContainerStyle {
                    background: Background {
                        color: Some(Color(0, 255, 0, 255)),
                        layers: Vec::new(),
                    },
                    tag: Some("html".to_string()),
                    ..ContainerStyle::default()
                },
                role: ContainerRole::Normal,
            },
            vec![body_info],
        );
        let root_info = mk_info_node(
            NodeKind::Container {
                scroll_x: false,
                scroll_y: false,
                scroll_offset_x: 0.0,
                scroll_offset_y: 0.0,
                style: ContainerStyle::default(),
                role: ContainerRole::Normal,
            },
            vec![html_info],
        );

        let mut commands = Vec::new();
        generate_draw_commands(
            &mut commands,
            &LayoutNode::new(Style::default()),
            &root_info,
            (100.0, 100.0),
        );

        let fills: Vec<_> = commands
            .iter()
            .filter_map(|cmd| match cmd {
                DrawCommand::Fill {
                    paint:
                        Paint {
                            brush: Brush::Solid(color),
                            ..
                        },
                    ..
                } => Some(*color),
                _ => None,
            })
            .collect();

        assert!(
            fills.contains(&Color(0, 255, 0, 255)),
            "canvas should paint html's green background, got {fills:?}"
        );
        assert!(
            fills[0] == Color(0, 255, 0, 255),
            "first canvas fill should be html's green background"
        );
    }

    #[test]
    fn canvas_background_transparent_when_neither_html_nor_body_has_background() {
        let body_info = mk_info_node(
            NodeKind::Container {
                scroll_x: false,
                scroll_y: false,
                scroll_offset_x: 0.0,
                scroll_offset_y: 0.0,
                style: ContainerStyle {
                    tag: Some("body".to_string()),
                    ..ContainerStyle::default()
                },
                role: ContainerRole::Normal,
            },
            Vec::new(),
        );
        let html_info = mk_info_node(
            NodeKind::Container {
                scroll_x: false,
                scroll_y: false,
                scroll_offset_x: 0.0,
                scroll_offset_y: 0.0,
                style: ContainerStyle {
                    tag: Some("html".to_string()),
                    ..ContainerStyle::default()
                },
                role: ContainerRole::Normal,
            },
            vec![body_info],
        );
        let root_info = mk_info_node(
            NodeKind::Container {
                scroll_x: false,
                scroll_y: false,
                scroll_offset_x: 0.0,
                scroll_offset_y: 0.0,
                style: ContainerStyle::default(),
                role: ContainerRole::Normal,
            },
            vec![html_info],
        );

        let mut commands = Vec::new();
        generate_draw_commands(
            &mut commands,
            &LayoutNode::new(Style::default()),
            &root_info,
            (100.0, 100.0),
        );

        let fill_count = commands
            .iter()
            .filter(|cmd| matches!(cmd, DrawCommand::Fill { .. }))
            .count();
        assert_eq!(
            fill_count, 0,
            "no canvas background fill when neither html nor body has background"
        );
    }

    #[test]
    fn canvas_background_inherits_body_gradient_when_html_has_none() {
        use crate::engine::layouter::types::{Gradient, GradientKind, GradientSpread};

        let gradient = Gradient {
            kind: GradientKind::Linear { angle: 0.0 },
            stops: Vec::new(),
            spread: GradientSpread::Pad,
        };
        let body_info = mk_info_node(
            NodeKind::Container {
                scroll_x: false,
                scroll_y: false,
                scroll_offset_x: 0.0,
                scroll_offset_y: 0.0,
                style: ContainerStyle {
                    background: Background {
                        color: None,
                        layers: vec![crate::engine::layouter::types::BackgroundLayer {
                            image: Some(crate::engine::layouter::types::BackgroundImage::Gradient(
                                gradient,
                            )),
                            position: Default::default(),
                            size: Default::default(),
                            repeat: Default::default(),
                        }],
                    },
                    tag: Some("body".to_string()),
                    ..ContainerStyle::default()
                },
                role: ContainerRole::Normal,
            },
            Vec::new(),
        );
        let html_info = mk_info_node(
            NodeKind::Container {
                scroll_x: false,
                scroll_y: false,
                scroll_offset_x: 0.0,
                scroll_offset_y: 0.0,
                style: ContainerStyle {
                    background: Background::default(),
                    tag: Some("html".to_string()),
                    ..ContainerStyle::default()
                },
                role: ContainerRole::Normal,
            },
            vec![body_info],
        );
        let root_info = mk_info_node(
            NodeKind::Container {
                scroll_x: false,
                scroll_y: false,
                scroll_offset_x: 0.0,
                scroll_offset_y: 0.0,
                style: ContainerStyle::default(),
                role: ContainerRole::Normal,
            },
            vec![html_info],
        );

        let mut commands = Vec::new();
        generate_draw_commands(
            &mut commands,
            &LayoutNode::new(Style::default()),
            &root_info,
            (100.0, 100.0),
        );

        let gradient_count = commands
            .iter()
            .filter(|cmd| {
                matches!(
                    cmd,
                    DrawCommand::Fill {
                        paint: Paint {
                            brush: Brush::Gradient(_),
                            ..
                        },
                        ..
                    }
                )
            })
            .count();

        assert!(
            gradient_count > 0,
            "canvas should paint body's gradient layer"
        );
    }
}