//! Generates a renderer-agnostic display list from a laid-out tree.

//!

//! This module is the bridge between the layout solver and the compositor/renderer.

//! Key types:

//! - [`DisplayList`] — flat, paint-order-sorted list of drawing commands

//! - [`DisplayListItem`] — a single drawing primitive or state-management command

//! - [`DisplayListBuilder`] — internal builder that accumulates items during generation

//!

//! Entry points:

//! - [`generate_display_list`] — converts a laid-out [`LayoutTree`] into a [`DisplayList`]

//! - [`paginate_display_list_with_slicer_and_breaks`] — slices a display list into pages

//!

//! Coordinates are in **absolute window-logical pixels** ([`WindowLogicalRect`]).

//! `HiDPI` scaling and scroll-offset conversion happen in the compositor.

use crate::solver3::layout_tree::LayoutNodeId;

use std::{collections::{BTreeMap, HashMap}, sync::Arc};

use azul_core::{

    dom::{DomId, FormattingContext, NodeId, NodeType, ScrollbarOrientation},

    geom::{LogicalPosition, LogicalRect, LogicalSize},

    gpu::GpuValueCache,

    hit_test::{CursorType, ScrollPosition, TAG_TYPE_CURSOR, TAG_TYPE_DOM_NODE},

    resources::{

        IdNamespace, ImageRef, OpacityKey, RendererResources, TransformKey,

    },

    transform::ComputedTransform3D,

    selection::{Selection, SelectionRange, TextSelection},

    styled_dom::StyledDom,

    ui_solver::GlyphInstance,

};

use azul_css::{

    css::CssPropertyValue,

    codegen::format::GetHash,

    props::{

        basic::{ColorU, FontRef, PixelValue},

        layout::{LayoutDisplay, LayoutOverflow, LayoutPosition},

        property::{CssProperty, CssPropertyType},

        style::{

            background::{ConicGradient, ExtendMode, LinearGradient, RadialGradient},

            border_radius::StyleBorderRadius,

            box_shadow::{BoxShadowClipMode, StyleBoxShadow},

            filter::{StyleFilter, StyleFilterVec},

            BorderStyle, LayoutBorderBottomWidth, LayoutBorderLeftWidth, LayoutBorderRightWidth,

            LayoutBorderTopWidth, StyleBorderBottomColor, StyleBorderBottomStyle,

            StyleBorderLeftColor, StyleBorderLeftStyle, StyleBorderRightColor,

            StyleBorderRightStyle, StyleBorderTopColor, StyleBorderTopStyle,

        },

    },

    LayoutDebugMessage,

};

#[cfg(feature = "text_layout")]

use crate::text3;

#[cfg(feature = "text_layout")]

use crate::text3::cache::{InlineShape, PositionedItem};

use crate::{

    debug_info,

    font_traits::{

        FontHash, FontLoaderTrait, ImageSource, InlineContent, ParsedFontTrait, ShapedItem,

        UnifiedLayout,

    },

    solver3::{

        getters::{

            get_background_color, get_background_contents, get_border_info, get_border_radius,

            get_break_after, get_break_before, get_caret_style,

            get_overflow_clip_margin_property, get_overflow_x, get_overflow_y,

            get_scrollbar_gutter_property, get_scrollbar_info_from_layout, get_scrollbar_style, get_selection_style,

            get_style_border_radius, get_visibility, get_z_index, is_forced_page_break, BorderInfo, CaretStyle,

            ComputedScrollbarStyle, SelectionStyle,

        },

        layout_tree::{LayoutNode, LayoutNodeHot, LayoutNodeWarm, LayoutTree},

        positioning::get_position_type,

        scrollbar::{ScrollbarRequirements, compute_scrollbar_geometry_with_button_size},

        LayoutContext, LayoutError, Result,

    },

};

const APPROX_ASCENT_RATIO: f32 = 0.8;

const APPROX_UNDERLINE_THICKNESS_RATIO: f32 = 0.08;

const APPROX_UNDERLINE_OFFSET_RATIO: f32 = 0.12;

const APPROX_STRIKETHROUGH_OFFSET_RATIO: f32 = 0.3;

const APPROX_OVERLINE_OFFSET_RATIO: f32 = 0.85;

const APPROX_ELLIPSIS_WIDTH_RATIO: f32 = 0.6;

const DEFAULT_A4_WIDTH_PT: f32 = 595.0;

const DEFAULT_SHADOW_FONT_SIZE_PX: f32 = 16.0;

/// Border widths for all four sides.

///

/// Each field is optional to allow partial border specifications.

/// Used in [`DisplayListItem::Border`] to specify per-side border widths.

#[derive(Debug, Clone, Copy)]

pub struct StyleBorderWidths {

    /// Top border width (CSS `border-top-width`)

    pub top: Option<CssPropertyValue<LayoutBorderTopWidth>>,

    /// Right border width (CSS `border-right-width`)

    pub right: Option<CssPropertyValue<LayoutBorderRightWidth>>,

    /// Bottom border width (CSS `border-bottom-width`)

    pub bottom: Option<CssPropertyValue<LayoutBorderBottomWidth>>,

    /// Left border width (CSS `border-left-width`)

    pub left: Option<CssPropertyValue<LayoutBorderLeftWidth>>,

}

/// Border colors for all four sides.

///

/// Each field is optional to allow partial border specifications.

/// Used in [`DisplayListItem::Border`] to specify per-side border colors.

#[derive(Debug, Clone, Copy)]

pub struct StyleBorderColors {

    /// Top border color (CSS `border-top-color`)

    pub top: Option<CssPropertyValue<StyleBorderTopColor>>,

    /// Right border color (CSS `border-right-color`)

    pub right: Option<CssPropertyValue<StyleBorderRightColor>>,

    /// Bottom border color (CSS `border-bottom-color`)

    pub bottom: Option<CssPropertyValue<StyleBorderBottomColor>>,

    /// Left border color (CSS `border-left-color`)

    pub left: Option<CssPropertyValue<StyleBorderLeftColor>>,

}

/// Border styles for all four sides.

///

/// Each field is optional to allow partial border specifications.

/// Used in [`DisplayListItem::Border`] to specify per-side border styles

/// (solid, dashed, dotted, none, etc.).

#[derive(Debug, Clone, Copy)]

pub struct StyleBorderStyles {

    /// Top border style (CSS `border-top-style`)

    pub top: Option<CssPropertyValue<StyleBorderTopStyle>>,

    /// Right border style (CSS `border-right-style`)

    pub right: Option<CssPropertyValue<StyleBorderRightStyle>>,

    /// Bottom border style (CSS `border-bottom-style`)

    pub bottom: Option<CssPropertyValue<StyleBorderBottomStyle>>,

    /// Left border style (CSS `border-left-style`)

    pub left: Option<CssPropertyValue<StyleBorderLeftStyle>>,

}

/// A rectangle in border-box coordinates (includes padding and border).

/// This is what layout calculates and stores in `used_size` and absolute positions.

#[derive(Debug, Clone, Copy, PartialEq, Eq)]

pub struct BorderBoxRect(pub LogicalRect);

/// A `LogicalRect` known to be in **absolute window coordinates** (as output

/// by the layout engine).

///

/// All spatial bounds stored in [`DisplayListItem`] use

/// this type so that the compositor is *forced* to convert them to

/// frame-relative coordinates before passing them to `WebRender`.

///

/// ## Coordinate-space contract

///

/// * **Layout engine** produces `WindowLogicalRect` values.

/// * **Compositor** converts via `resolve_rect()` → `WebRender` `LayoutRect`.

/// * Passing a `WindowLogicalRect` directly to a `WebRender` push function is a

///   **type error** (it wraps `LogicalRect`, not `LayoutRect`).

///

/// See `doc/SCROLL_COORDINATE_ARCHITECTURE.md` for background.

#[derive(Debug, Copy, Clone, Default, PartialEq, PartialOrd, Eq, Ord, Hash)]

pub struct WindowLogicalRect(pub LogicalRect);

/// Anything at or below this is the unassigned-position sentinel, not geometry.

///

/// The sentinel is exactly `f32::MIN`; the threshold is deliberately a little

/// looser so a sentinel that has been through one offset addition (which barely

/// moves a value of that magnitude) is still recognised.

const UNASSIGNED_POSITION_LIMIT: f32 = f32::MIN / 2.0;

impl WindowLogicalRect {

    #[inline]

    #[inline]

    /// Access the inner `LogicalRect` (still in window space – the caller is

    /// responsible for applying any offset conversion).

    #[inline]

    #[inline]

    // Convenience accessors

}

impl From<LogicalRect> for WindowLogicalRect {

    #[inline]

}

impl From<WindowLogicalRect> for LogicalRect {

    #[inline]

}

/// Simple struct for passing element dimensions to border-radius calculation

#[derive(Debug, Clone, Copy)]

pub struct PhysicalSizeImport {

    pub width: f32,

    pub height: f32,

}

/// Complete drawing information for a scrollbar with all visual components.

///

/// This contains the resolved geometry and colors for all scrollbar parts:

/// - Track: The background area where the thumb slides

/// - Thumb: The draggable indicator showing current scroll position

/// - Buttons: Optional up/down or left/right arrow buttons

/// - Corner: The area where horizontal and vertical scrollbars meet

#[derive(Debug, Clone, PartialEq)]

pub struct ScrollbarDrawInfo {

    /// Overall bounds of the entire scrollbar (including track and buttons)

    pub bounds: WindowLogicalRect,

    /// Scrollbar orientation (horizontal or vertical)

    pub orientation: ScrollbarOrientation,

    // Track area (the background rail)

    /// Bounds of the track area

    pub track_bounds: WindowLogicalRect,

    /// Color of the track background

    pub track_color: ColorU,

    // Thumb (the draggable part)

    /// Bounds of the thumb

    pub thumb_bounds: WindowLogicalRect,

    /// Color of the thumb

    pub thumb_color: ColorU,

    /// Border radius for rounded thumb corners

    pub thumb_border_radius: BorderRadius,

    // Optional buttons (arrows at ends)

    /// Optional decrement button bounds (up/left arrow)

    pub button_decrement_bounds: Option<WindowLogicalRect>,

    /// Optional increment button bounds (down/right arrow)

    pub button_increment_bounds: Option<WindowLogicalRect>,

    /// Color for buttons

    pub button_color: ColorU,

    /// Optional opacity key for GPU-side fading animation.

    pub opacity_key: Option<OpacityKey>,

    /// Optional transform key for GPU-side scrollbar thumb positioning.

    /// When present, the compositor will wrap the thumb in a `PushReferenceFrame`

    /// with `PropertyBinding::Binding` so `WebRender` can animate the thumb position

    /// without rebuilding the display list.

    pub thumb_transform_key: Option<TransformKey>,

    /// Initial transform for the scrollbar thumb (current scroll position).

    /// This is the transform applied when the display list is first built.

    /// During GPU-only scroll, `synchronize_gpu_values` updates this dynamically.

    pub thumb_initial_transform: ComputedTransform3D,

    /// Optional hit-test ID for `WebRender` hit-testing.

    pub hit_id: Option<azul_core::hit_test::ScrollbarHitId>,

    /// Whether to clip scrollbar to container's border-radius

    pub clip_to_container_border: bool,

    /// Container's border-radius (for clipping)

    pub container_border_radius: BorderRadius,

    /// Scrollbar visibility mode — used by back-registration to choose initial opacity.

    /// `Always` → initial opacity 1.0; `WhenScrolling` → initial opacity 0.0.

    pub visibility: azul_css::props::style::scrollbar::ScrollbarVisibilityMode,

}

impl BorderBoxRect {

    /// Convert border-box to content-box by subtracting padding and border.

    /// Content-box is where inline layout and text actually render.

    /// Get the inner `LogicalRect`

}

/// A rectangle in content-box coordinates (excludes padding and border).

/// This is where text and inline content is positioned by the inline formatter.

#[derive(Debug, Clone, Copy, PartialEq, Eq)]

pub struct ContentBoxRect(pub LogicalRect);

impl ContentBoxRect {

    /// Get the inner `LogicalRect`

}

/// The final, renderer-agnostic output of the layout engine.

///

/// This is a flat list of drawing and state-management commands, already sorted

/// according to the CSS paint order. A renderer can consume this list directly.

/// A CSS-forced page break recorded while building the display list.

#[derive(Debug, Clone, Copy, PartialEq)]

pub struct ForcedBreak {

    /// Absolute document-space Y of the break.

    pub y: f32,

    /// The node whose `break-before`/`break-after` property forced it.

    /// `None` only for synthetic inputs (tests, hand-built lists).

    pub causing_node: Option<NodeId>,

}

#[derive(Debug, Default, Clone)]

pub struct DisplayList {

    pub items: Vec<DisplayListItem>,

    /// Optional mapping from item index to the DOM `NodeId` that generated it.

    /// Used for pagination to look up CSS break properties.

    /// Not all items have a source node (e.g., synthesized decorations).

    pub node_mapping: Vec<Option<NodeId>>,

    /// Forced page breaks (from break-before/break-after: always), with the

    /// node whose break property caused each one. Y coordinates are absolute

    /// in the infinite canvas coordinate system; the slicer aligns page

    /// boundaries with these positions.

    pub forced_page_breaks: Vec<ForcedBreak>,

    /// Index ranges (start, end) of display list items that belong to fixed-position elements.

    /// In paged media, these items are replicated on every page (CSS Positioned Layout §2.1).

    pub fixed_position_item_ranges: Vec<(usize, usize)>,

    /// Per-item PROVEN uniform background (Text items only, None elsewhere).

    /// Parallel to `items` like `node_mapping`. Lives on the LIST rather

    /// than in the `Text` variant because printpdf (crates.io, immutable)

    /// pattern-matches the variant exhaustively — a new variant field is a

    /// downstream semver break; a new list field is not. See

    /// `compute_uniform_text_bg` for what "proven" means and the raster's

    /// pre-blended tile path for what it buys (~6 ms/repaint of per-pixel

    /// linear LCD compositing).

    pub uniform_text_bgs: Vec<Option<(ColorU, WindowLogicalRect)>>,

    /// Per-item (layout-tree index, emission phase) — the DL-PATCHING key.

    /// `node_mapping` attributes items to DOM ids, but patching substitutes

    /// per LAYOUT-NODE PAINT CALL: on a resize-skip pass the tree object and

    /// its indices are unchanged, so a node's cached items can replace a

    /// paint call — IF the run for the bg/border call can be told apart from

    /// the run for the content call and from items the SC walk itself pushes

    /// (scroll-frame hit areas, clips, scrollbars — those always re-emit

    /// fresh). Parallel to `items`, like `node_mapping`.

    pub layout_node_mapping: Vec<Option<(usize, EmitPhase)>>,

}

impl DisplayList {

    /// Approximate heap bytes retained by this display list — the

    /// item vec + parallel vecs + every item's owned heap. The memory

    /// report used to charge a FLAT 2 KiB for a cached display list;

    /// on a paginated document the `Text` items alone hold an offset

    /// COPY of every painted glyph (20 B each), which made the single

    /// biggest DL cost invisible ("a zero is not a measurement" — and

    /// so is a constant).

    ///

    /// Returns `(bytes, text_instances, item_count)` — the counters that

    /// explain the byte figure (glyph copies vs item slots), same pattern

    /// as the cluster counters on the tree report.

    #[must_use]

        use core::mem::size_of;

    /// Owned heap hanging off one item. EXHAUSTIVE on purpose — a new

    /// variant must fail this match so its heap gets classified rather

    /// than silently uncounted. `Arc`/`ImageRef` fields are CLONES of

    /// allocations owned (and counted) elsewhere → 0 here.

        use core::mem::size_of;

        use DisplayListItem as I;

            }

            }

            }

            }

            }

            // Arc / ImageRef clones — owned and counted elsewhere.

            // Flat payloads: everything lives inline in the enum variant,

            // already covered by `items.capacity() * size_of::<DisplayListItem>()`.

            I::Rect { .. }

            | I::SelectionRect { .. }

            | I::CursorRect { .. }

            | I::Border { .. }

            | I::Underline { .. }

            | I::Strikethrough { .. }

            | I::Overline { .. }

            | I::ScrollBar { .. }

            | I::VirtualView { .. }

            | I::VirtualViewPlaceholder { .. }

            | I::PushClip { .. }

            | I::PopClip

            | I::PopImageMaskClip

            | I::PushScrollFrame { .. }

            | I::PopScrollFrame

            | I::PushStackingContext { .. }

            | I::PopStackingContext

            | I::PushReferenceFrame { .. }

            | I::PopReferenceFrame

            | I::HitTestArea { .. }

            | I::BoxShadow { .. }

            | I::PopFilter

            | I::PopBackdropFilter

            | I::PushOpacity { .. }

            | I::PopOpacity

            | I::PushTextShadow { .. }

        }

}

/// Translate a display-list item's geometry by `delta` (DL patching:

/// same item content, moved node). Every variant the two paint fns can

/// emit is handled; variants outside `patchable_item` never reach this

/// (`PatchState::build` forces their node into the re-emit set).

#[must_use]

    use DisplayListItem as I;

        }

        // No geometry of their own.

        // Anything else is untranslatable by contract (see patchable_item).

    }

/// Whether an item may appear in a PATCHED (copied+translated) run. The

/// build step forces nodes emitting anything else into the re-emit set —

/// scroll frames, clips, stacking contexts, virtual views, filters and

/// scrollbars all carry state beyond a rect and must re-emit fresh.

#[must_use]

    use DisplayListItem as I;

        I::Rect { .. }

            | I::SelectionRect { .. }

            | I::CursorRect { .. }

            | I::Border { .. }

            | I::TextLayout { .. }

            | I::Text { .. }

            | I::Underline { .. }

            | I::Strikethrough { .. }

            | I::Overline { .. }

            | I::Image { .. }

            | I::LinearGradient { .. }

            | I::RadialGradient { .. }

            | I::ConicGradient { .. }

            | I::BoxShadow { .. }

            | I::HitTestArea { .. }

            | I::PushTextShadow { .. }

            | I::PopTextShadow

    )

/// Runtime toggle for DL patching. 0 = uninitialized (resolve from

/// `AZ_NO_DL_PATCH` on first read), 1 = enabled, 2 = disabled. A runtime

/// atomic rather than a latched `OnceLock` so tests can A/B the patched and

/// full paths in one process (the golden-equality gate), and so a live

/// session can be flipped for diagnosis.

static DL_PATCHING: core::sync::atomic::AtomicU8 = core::sync::atomic::AtomicU8::new(0);

#[must_use]

    use core::sync::atomic::Ordering;

        _ => {

        }

    }

/// Force DL patching on/off (tests + live diagnosis; overrides the env).

    use core::sync::atomic::Ordering;

/// Which emission site produced a display-list item. See

/// [`DisplayList::layout_node_mapping`].

#[derive(Debug, Copy, Clone, PartialEq, Eq)]

pub enum EmitPhase {

    /// Pushed by the stacking-context walk itself (clips, scroll frames,

    /// scrollable hit areas, scrollbars) — never substituted from cache.

    ScWalk,

    /// Pushed by `paint_node_background_and_border`.

    BgBorder,

    /// Pushed by `paint_node_content`.

    Content,

}

impl DisplayList {

    /// THE display-list ↔ DOM identity invariant, checkable after every

    /// build or patch.

    ///

    /// `node_mapping` is how thirty-plus consumers (damage attribution,

    /// pagination break lookup, hit-testing, the coming display-list PATCHING)

    /// resolve an item back to the DOM. A stale or out-of-range id does not

    /// fail — it succeeds at describing the WRONG node, which is the silent

    /// corruption class `assert_dom_ids_are_in_range` documents on the tree

    /// side (a ribbon tab click once repainted rects of unrelated nodes; it

    /// was only caught because an index happened to trip a bounds check).

    /// This is the missing display-list-side counterpart, and the hard gate

    /// the DL-patching work patches AGAINST: every patch must leave this

    /// invariant intact.

    ///

    /// Checks: (1) `node_mapping` covers `items` 1:1; (2) every mapped id

    /// indexes into `styled_dom`; (3) every item's bounds, where it has any,

    /// is finite (a NaN origin poisons every damage union it touches).

    /// Deliberately NOT checked: bounds-within-node-rect — decorations

    /// (shadows, outlines, selection) legitimately paint outside their node.

    ///

    /// # Errors

    /// Returns a message naming the first offending item index.

                {

        }

    /// Patch text glyph data for a specific layout node without rebuilding

    /// the entire display list. Returns the damage rect covering all

    /// affected text items, or None if no matching items found.

    ///

    /// Used for `GlyphSwap` incremental relayout: glyphs changed but

    /// positions are identical, so only the glyph IDs need updating.

            if let DisplayListItem::Text {

                ..

                                // rect union (was crate::cpurender::union_rect, which

                                // is gated behind the `cpurender` feature; inlined here

                                // so display-list damage tracking works without it / on WASM)

        }

    /// Rewrite the `ImageRef` of every `Image` item generated by `node`

    /// without rebuilding the display list, returning the union of the

    /// patched bounds (None if the node produced no image items).

    ///

    /// The single caller is the content chokepoint

    /// (`LayoutWindow::apply_content_change`, paint tier): geometry is

    /// unchanged, only the content identity moves — the backend display-list

    /// diff sees the `ImageRef` id change and damages exactly these bounds.

    /// Patch PAINT COLOURS in place for a node's SUBTREE — the per-tick fast

    /// path of a paint-only `animation` transition. Items attributed (via

    /// `node_mapping`) to a node id in `range` whose colour equals `from`

    /// take `to`; the from-match is what implements inheritance without a

    /// cascade pass (a descendant with its OWN explicit colour differs from

    /// `from` and is untouched). Returns the damage union, `None` when

    /// nothing matched (the caller falls back to a full rebuild).

            };

                DisplayListItem::Text {

            }

        }

            if let DisplayListItem::Image {

                ..

            {

        }

    /// Compute a damage rect from the difference between old and new text

    /// layout results, starting from a given line index.

    #[allow(clippy::similar_names)] // domain-standard coordinate/geometry/short-lived names

            }

    /// Generates a JSON representation of the display list for debugging.

    /// This includes clip chain analysis showing how clips are stacked.

    #[allow(clippy::too_many_lines)] // large but cohesive: single-purpose layout/render/parse routine (one branch per case)

        use std::fmt::Write;

                DisplayListItem::PushClip {

                DisplayListItem::PushScrollFrame {

                DisplayListItem::Rect {

            }

        }

        )

}

/// A command in the display list. Can be either a drawing primitive or a

/// state-management instruction for the renderer's graphics context.

#[derive(Debug, Clone)]

pub enum DisplayListItem {

    // Drawing Primitives

    /// A filled rectangle with optional rounded corners.

    /// Used for backgrounds, colored boxes, and other solid fills.

    Rect {

        /// The rectangle bounds in absolute window coordinates

        bounds: WindowLogicalRect,

        /// The fill color (RGBA)

        color: ColorU,

        /// Corner radii for rounded rectangles

        border_radius: BorderRadius,

    },

    /// A selection highlight rectangle (e.g., for text selection).

    /// Rendered behind text to show selected regions.

    SelectionRect {

        /// The rectangle bounds in absolute window coordinates

        bounds: WindowLogicalRect,

        /// Corner radii for rounded selection

        border_radius: BorderRadius,

        /// The selection highlight color (typically semi-transparent)

        color: ColorU,

    },

    /// A text cursor (caret) rectangle.

    /// Typically a thin vertical line indicating text insertion point.

    CursorRect {

        /// The cursor bounds (usually narrow width)

        bounds: WindowLogicalRect,

        /// The cursor color

        color: ColorU,

    },

    /// A CSS border with per-side widths, colors, and styles.

    /// Supports different styles per side (solid, dashed, dotted, etc.).

    Border {

        /// The border-box bounds

        bounds: WindowLogicalRect,

        /// Border widths for each side

        widths: StyleBorderWidths,

        /// Border colors for each side

        colors: StyleBorderColors,

        /// Border styles for each side (solid, dashed, etc.)

        styles: StyleBorderStyles,

        /// Corner radii for rounded borders

        border_radius: StyleBorderRadius,

    },

    /// Text layout with full metadata (for PDF, accessibility, etc.)

    /// This is pushed BEFORE the individual Text items and contains

    /// the original text, glyph-to-unicode mapping, and positioning info

    TextLayout {

        layout: Arc<dyn std::any::Any + Send + Sync>, // Type-erased UnifiedLayout

        bounds: WindowLogicalRect,

        font_hash: FontHash,

        font_size_px: f32,

        color: ColorU,

    },

    /// Text rendered with individual glyph positioning (for simple renderers)

    Text {

        glyphs: Vec<GlyphInstance>,

        font_hash: FontHash,

        font_size_px: f32,

        color: ColorU,

        clip_rect: WindowLogicalRect,

        /// Layout node index that produced this text run.

        /// Enables patching glyphs without full display list regeneration.

        source_node_index: Option<usize>,

    },

    /// Underline decoration for text (CSS text-decoration: underline)

    Underline {

        bounds: WindowLogicalRect,

        color: ColorU,

        thickness: f32,

    },

    /// Strikethrough decoration for text (CSS text-decoration: line-through)

    Strikethrough {

        bounds: WindowLogicalRect,

        color: ColorU,

        thickness: f32,

    },

    /// Overline decoration for text (CSS text-decoration: overline)

    Overline {

        bounds: WindowLogicalRect,

        color: ColorU,

        thickness: f32,

    },

    Image {

        bounds: WindowLogicalRect,

        image: ImageRef,

        border_radius: BorderRadius,

    },

    /// A dedicated primitive for a scrollbar with optional GPU-animated opacity.

    /// This is a simple single-color scrollbar used for basic rendering.

    ScrollBar {

        bounds: WindowLogicalRect,

        color: ColorU,

        orientation: ScrollbarOrientation,

        /// Optional opacity key for GPU-side fading animation.

        /// If present, the renderer will use this key to look up dynamic opacity.

        /// If None, the alpha channel of `color` is used directly.

        opacity_key: Option<OpacityKey>,

        /// Optional hit-test ID for `WebRender` hit-testing.

        /// If present, allows event handlers to identify which scrollbar component was clicked.

        hit_id: Option<azul_core::hit_test::ScrollbarHitId>,

    },

    /// A fully styled scrollbar with separate track, thumb, and optional buttons.

    /// Used when CSS scrollbar properties are specified.

    ScrollBarStyled {

        /// Complete drawing information for all scrollbar components

        info: Box<ScrollbarDrawInfo>,

    },

    /// An embedded `VirtualView` that references a child DOM with its own display list.

    /// The renderer will look up the child display list by `child_dom_id` and

    /// render it within the bounds. The `VirtualView` viewport is rendered in parent

    /// coordinate space (NOT inside a scroll frame) so it stays stationary.

    /// Scroll offset is communicated to the `VirtualView` callback, not via `WebRender`.

    VirtualView {

        /// The `DomId` of the child DOM (similar to webrender's `pipeline_id`)

        child_dom_id: DomId,

        /// The bounds where the `VirtualView` should be rendered

        bounds: WindowLogicalRect,

        /// The clip rect for the `VirtualView` content

        clip_rect: WindowLogicalRect,

        /// How far to shift the child content inside `bounds`, in logical px:

        /// `materialized_window_origin - current_scroll_offset`.

        ///

        /// This is what makes a `VirtualView` SCROLL rather than merely

        /// re-materialize. It is deliberately derived from the materialized

        /// window's origin and the live scroll offset ONLY — never from the

        /// virtual document size — so refining the document estimate (as

        /// background pagination lands) resizes the scrollbar and moves

        /// nothing on screen.

        content_offset: LogicalPosition,

    },

    /// Placeholder emitted during display list generation for `VirtualView` nodes.

    /// `window.rs` replaces this with a real `VirtualView` item after invoking

    /// the `VirtualView` callback. This avoids the need for post-hoc scroll frame

    /// scanning — `window.rs` simply finds the placeholder by `node_id`.

    ///

    /// Unlike regular scrollable nodes, `VirtualView` nodes do NOT get a

    /// PushScrollFrame/PopScrollFrame pair. Scroll state is managed by

    /// `ScrollManager` and passed to the `VirtualView` callback as `scroll_offset`.

    VirtualViewPlaceholder {

        /// The DOM `NodeId` of the `VirtualView` element in the parent DOM

        node_id: NodeId,

        /// The layout bounds of the `VirtualView` container

        bounds: WindowLogicalRect,

        /// The clip rect (same as bounds initially, may be adjusted)

        clip_rect: WindowLogicalRect,

    },

    // --- State-Management Commands ---

    /// Pushes a new clipping rectangle onto the renderer's clip stack.

    /// All subsequent primitives will be clipped by this rect until a `PopClip`.

    PushClip {

        bounds: WindowLogicalRect,

        border_radius: BorderRadius,

    },

    /// Pops the current clip from the renderer's clip stack.

    PopClip,

    /// Pushes an image-based clip mask onto the renderer's clip stack.

    /// The mask image should be R8 format: white (255) = visible, black (0) = clipped.

    /// All subsequent primitives will be masked until `PopImageMaskClip`.

    PushImageMaskClip {

        /// The bounds of the element being clipped

        bounds: WindowLogicalRect,

        /// The mask image (R8 format)

        mask_image: ImageRef,

        /// The rect within which the mask is applied

        mask_rect: WindowLogicalRect,

    },

    /// Pops the current image mask clip from the renderer's clip stack.

    PopImageMaskClip,

    /// Defines a scrollable area. This is a specialized clip that also

    /// establishes a new coordinate system for its children, which can be offset.

    PushScrollFrame {

        /// The clip rect in the parent's coordinate space.

        clip_bounds: WindowLogicalRect,

        /// The total size of the scrollable content.

        content_size: LogicalSize,

        /// An ID for the renderer to track this scrollable area between frames.

        scroll_id: LocalScrollId,

    },

    /// Pops the current scroll frame.

    PopScrollFrame,

    /// Pushes a new stacking context for proper z-index layering.

    /// All subsequent primitives until `PopStackingContext` will be in this stacking context.

    PushStackingContext {

        /// The z-index for this stacking context (for debugging/validation)

        z_index: i32,

        /// The bounds of the stacking context root element

        bounds: WindowLogicalRect,

    },

    /// Pops the current stacking context.

    PopStackingContext,

    /// Pushes a reference frame with a GPU-accelerated transform.

    /// Used for CSS transforms and drag visual offsets.

    /// Creates a new spatial coordinate system for all children.

    PushReferenceFrame {

        /// The transform key for GPU-animated property binding

        transform_key: TransformKey,

        /// The initial transform value (identity for drag, computed for CSS transform)

        initial_transform: ComputedTransform3D,

        /// The bounds of the reference frame (origin = transform origin)

        bounds: WindowLogicalRect,

    },

    /// Pops the current reference frame.

    PopReferenceFrame,

    /// Defines a region for hit-testing.

    HitTestArea {

        bounds: WindowLogicalRect,

        tag: DisplayListTagId, // This would be a renderer-agnostic ID type

    },

    // --- Gradient Primitives ---

    /// A linear gradient fill.

    LinearGradient {

        bounds: WindowLogicalRect,

        gradient: LinearGradient,

        border_radius: BorderRadius,

    },

    /// A radial gradient fill.

    RadialGradient {

        bounds: WindowLogicalRect,

        gradient: RadialGradient,

        border_radius: BorderRadius,

    },

    /// A conic (angular) gradient fill.

    ConicGradient {

        bounds: WindowLogicalRect,

        gradient: ConicGradient,

        border_radius: BorderRadius,

    },

    // --- Shadow Effects ---

    /// A box shadow (either outset or inset).

    BoxShadow {

        bounds: WindowLogicalRect,

        shadow: StyleBoxShadow,

        border_radius: BorderRadius,

    },

    // --- Filter Effects ---

    /// Push a filter effect that applies to subsequent content.

    PushFilter {

        bounds: WindowLogicalRect,

        filters: Vec<StyleFilter>,

    },

    /// Pop a previously pushed filter.

    PopFilter,

    /// Push a backdrop filter (applies to content behind the element).

    PushBackdropFilter {

        bounds: WindowLogicalRect,

        filters: Vec<StyleFilter>,

    },

    /// Pop a previously pushed backdrop filter.

    PopBackdropFilter,

    /// Push an opacity layer.

    PushOpacity {

        bounds: WindowLogicalRect,

        /// The BAKED (CSS) opacity — the value at display-list build time.

        opacity: f32,

        /// GPU binding for ANIMATED opacity (enter/exit fades, diff-driven

        /// animation). Same contract as `PushReferenceFrame.transform_key`:

        /// the display list carries the KEY, the per-tick value lives in the

        /// `GpuValueCache` animation channel, so the cached list serves every

        /// tick while the fade advances. `None` for plain CSS opacity.

        opacity_key: Option<OpacityKey>,

    },

    /// Pop an opacity layer.

    PopOpacity,

    /// Push a text shadow that applies to subsequent text content.

    PushTextShadow {

        shadow: StyleBoxShadow,

    },

    /// Pop all text shadows.

    PopTextShadow,

}

/// Intersect `a` with `b`; if they do not overlap, fall back to `b`.

///

/// Used to clamp a computed ink extent to its clip rect. The fallback is

/// deliberately the CLIP and not an empty rect: a non-overlapping result

/// means the extent was computed wrongly, and in that case damaging too

/// much is recoverable while damaging nothing leaves stale pixels.

    } else {

    }

impl DisplayListItem {

    /// Compare two display list items for visual equality (same appearance when rendered).

    /// Used by damage computation to detect content changes within the same bounds.

    /// Conservative: returns `false` (assumes different) for complex types like Arc<dyn Any>.

    // Exact float equality is intentional: this is frame-to-frame damage detection,