azul_core/

styled_dom.rs

//! `StyledDom` - the result of applying CSS styles to a DOM tree.
//!
//! This module contains [`StyledDom`], which is produced by combining a [`Dom`]
//! with a [`Css`] stylesheet via [`StyledDom::create`]. It stores the flattened
//! node hierarchy, per-node styled states, cascade information, and the CSS
//! property cache. Restyle operations (`restyle_nodes_hover`, etc.) allow
//! incremental updates when pseudo-class states change at runtime.
//!
//! `StyledDom` is the primary input to the layout engine.

use alloc::{boxed::Box, collections::btree_map::BTreeMap, string::String, vec::Vec};
use core::{
    fmt,
    hash::{Hash, Hasher},
};

use azul_css::{
    css::Css,
    props::{
        basic::{StyleFontFamily, StyleFontFamilyVec, StyleFontSize},
        property::{
            BoxDecorationBreakValue, BreakInsideValue, CaretAnimationDurationValue,
            CaretColorValue, ColumnCountValue, ColumnFillValue, ColumnRuleColorValue,
            ColumnRuleStyleValue, ColumnRuleWidthValue, ColumnSpanValue, ColumnWidthValue,
            ContentValue, CounterIncrementValue, CounterResetValue, CssProperty, CssPropertyType,
            FlowFromValue, FlowIntoValue, LayoutAlignContentValue, LayoutAlignItemsValue,
            LayoutAlignSelfValue, LayoutBorderBottomWidthValue, LayoutBorderLeftWidthValue,
            LayoutBorderRightWidthValue, LayoutBorderTopWidthValue, LayoutBoxSizingValue,
            LayoutClearValue, LayoutColumnGapValue, LayoutDisplayValue, LayoutFlexBasisValue,
            LayoutFlexDirectionValue, LayoutFlexGrowValue, LayoutFlexShrinkValue,
            LayoutFlexWrapValue, LayoutFloatValue, LayoutGapValue, LayoutGridAutoColumnsValue,
            LayoutGridAutoFlowValue, LayoutGridAutoRowsValue, LayoutGridColumnValue,
            LayoutGridRowValue, LayoutGridTemplateColumnsValue, LayoutGridTemplateRowsValue,
            LayoutHeightValue, LayoutInsetBottomValue, LayoutJustifyContentValue,
            LayoutJustifyItemsValue, LayoutJustifySelfValue, LayoutLeftValue,
            LayoutMarginBottomValue, LayoutMarginLeftValue, LayoutMarginRightValue,
            LayoutMarginTopValue, LayoutMaxHeightValue, LayoutMaxWidthValue, LayoutMinHeightValue,
            LayoutMinWidthValue, LayoutOverflowValue, LayoutPaddingBottomValue,
            LayoutPaddingLeftValue, LayoutPaddingRightValue, LayoutPaddingTopValue,
            LayoutPositionValue, LayoutRightValue, LayoutRowGapValue, LayoutScrollbarWidthValue,
            LayoutTextJustifyValue, LayoutTopValue, LayoutWidthValue, LayoutWritingModeValue,
            LayoutZIndexValue, OrphansValue, PageBreakValue, RelayoutScope,
            SelectionBackgroundColorValue, SelectionColorValue, ShapeImageThresholdValue,
            ShapeMarginValue, ShapeOutsideValue, StringSetValue, StyleBackfaceVisibilityValue,
            StyleBackgroundContentVecValue, StyleBackgroundPositionVecValue,
            StyleBackgroundRepeatVecValue, StyleBackgroundSizeVecValue,
            StyleBorderBottomColorValue, StyleBorderBottomLeftRadiusValue,
            StyleBorderBottomRightRadiusValue, StyleBorderBottomStyleValue,
            StyleBorderLeftColorValue, StyleBorderLeftStyleValue, StyleBorderRightColorValue,
            StyleBorderRightStyleValue, StyleBorderTopColorValue, StyleBorderTopLeftRadiusValue,
            StyleBorderTopRightRadiusValue, StyleBorderTopStyleValue, StyleBoxShadowValue,
            StyleCursorValue, StyleDirectionValue, StyleFilterVecValue, StyleFontFamilyVecValue,
            StyleFontSizeValue, StyleFontValue, StyleHyphensValue, StyleLetterSpacingValue,
            StyleLineHeightValue, StyleMixBlendModeValue, StyleOpacityValue,
            StylePerspectiveOriginValue, StyleScrollbarColorValue, StyleTabSizeValue,
            StyleTextAlignValue, StyleTextColorValue, StyleTransformOriginValue,
            StyleTransformVecValue, StyleVisibilityValue, StyleWhiteSpaceValue,
            StyleWordSpacingValue, WidowsValue,
        },
        style::StyleTextColor,
    },
    AzString,
};

use crate::{
    callbacks::Update,
    dom::{Dom, DomId, NodeData, NodeDataVec, OptionTabIndex, TabIndex, TagId},
    events::{RelayoutNodes, RestyleNodes},
    id::{
        Node, NodeDataContainer, NodeDataContainerRef, NodeDataContainerRefMut, NodeHierarchy,
        NodeId,
    },
    menu::Menu,
    prop_cache::{CssPropertyCache, CssPropertyCachePtr},
    refany::RefAny,
    resources::{Au, ImageCache, ImageRef, ImmediateFontId, RendererResources},
    style::{
        construct_html_cascade_tree, matches_html_element, rule_ends_with, CascadeInfo,
        CascadeInfoVec,
    },
    FastBTreeSet, OrderedMap,
};

#[repr(C)]
#[derive(Debug, Clone, PartialEq, Hash, PartialOrd, Eq, Ord)]
pub struct ChangedCssProperty {
    pub previous_state: StyledNodeState,
    pub previous_prop: CssProperty,
    pub current_state: StyledNodeState,
    pub current_prop: CssProperty,
}

impl_option!(
    ChangedCssProperty,
    OptionChangedCssProperty,
    copy = false,
    [Debug, Clone, PartialEq, Hash, PartialOrd, Eq, Ord]
);

impl_vec!(
    ChangedCssProperty,
    ChangedCssPropertyVec,
    ChangedCssPropertyVecDestructor,
    ChangedCssPropertyVecDestructorType,
    ChangedCssPropertyVecSlice,
    OptionChangedCssProperty
);
impl_vec_debug!(ChangedCssProperty, ChangedCssPropertyVec);
impl_vec_partialord!(ChangedCssProperty, ChangedCssPropertyVec);
impl_vec_clone!(
    ChangedCssProperty,
    ChangedCssPropertyVec,
    ChangedCssPropertyVecDestructor
);
impl_vec_partialeq!(ChangedCssProperty, ChangedCssPropertyVec);

/// Focus state change for restyle operations
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct FocusChange {
    /// Node that lost focus (if any)
    pub lost_focus: Option<NodeId>,
    /// Node that gained focus (if any)
    pub gained_focus: Option<NodeId>,
}

/// Hover state change for restyle operations
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct HoverChange {
    /// Nodes that the mouse left
    pub left_nodes: Vec<NodeId>,
    /// Nodes that the mouse entered
    pub entered_nodes: Vec<NodeId>,
}

/// Active (mouse down) state change for restyle operations
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ActiveChange {
    /// Nodes that were deactivated (mouse up)
    pub deactivated: Vec<NodeId>,
    /// Nodes that were activated (mouse down)
    pub activated: Vec<NodeId>,
}

/// Result of a restyle operation, indicating what needs to be updated
#[derive(Debug, Clone, Default)]
pub struct RestyleResult {
    /// Nodes whose CSS properties changed, with details of the changes
    pub changed_nodes: RestyleNodes,
    /// Whether layout needs to be recalculated (layout properties changed)
    pub needs_layout: bool,
    /// Whether display list needs regeneration (visual properties changed)
    pub needs_display_list: bool,
    /// Whether only GPU-level properties changed (opacity, transform)
    /// If true and `needs_display_list` is false, we can update via GPU without display list rebuild
    pub gpu_only_changes: bool,
    /// The highest `RelayoutScope` seen across all property changes.
    ///
    /// This enables the IFC incremental layout optimization (Phase 2):
    /// - `None`      -> repaint only, zero layout work
    /// - `IfcOnly`   -> only the affected IFC needs re-shaping/repositioning
    /// - `SizingOnly`-> this node's size changed, parent repositions siblings
    /// - `Full`      -> full subtree relayout
    ///
    /// When `max_relayout_scope <= IfcOnly`, the layout engine can skip
    /// full `calculate_layout_for_subtree` and use the IFC fast path instead.
    pub max_relayout_scope: RelayoutScope,
}

impl RestyleResult {
    /// Returns true if any changes occurred
    #[must_use]
    pub fn has_changes(&self) -> bool {
        !self.changed_nodes.is_empty()
    }

    /// Merge another `RestyleResult` into this one
    pub fn merge(&mut self, other: Self) {
        for (node_id, changes) in other.changed_nodes {
            self.changed_nodes
                .entry(node_id)
                .or_default()
                .extend(changes);
        }
        self.needs_layout = self.needs_layout || other.needs_layout;
        self.needs_display_list = self.needs_display_list || other.needs_display_list;
        self.gpu_only_changes = self.gpu_only_changes && other.gpu_only_changes;
        // Keep the highest (most expensive) scope
        if other.max_relayout_scope > self.max_relayout_scope {
            self.max_relayout_scope = other.max_relayout_scope;
        }
    }
}

/// NOTE: multiple states can be active at the same time
///
/// Tracks all CSS pseudo-class states for a node.
/// Each flag is independent - a node can be both :hover and :focus simultaneously.
#[repr(C)]
#[derive(Clone, Copy, PartialEq, Hash, PartialOrd, Eq, Ord, Default)]
pub struct StyledNodeState {
    /// Element is being hovered (:hover)
    pub hover: bool,
    /// Element is active/being clicked (:active)
    pub active: bool,
    /// Element has focus (:focus)
    pub focused: bool,
    /// Element is disabled (:disabled)
    pub disabled: bool,
    /// Element is checked/selected (:checked)
    pub checked: bool,
    /// Element or descendant has focus (:focus-within)
    pub focus_within: bool,
    /// Link has been visited (:visited)
    pub visited: bool,
    /// Window is not focused (:backdrop) - GTK compatibility
    pub backdrop: bool,
    /// Element is currently being dragged (:dragging)
    pub dragging: bool,
    /// A dragged element is over this drop target (:drag-over)
    pub drag_over: bool,
    /// The PROMPT of an empty editable is being styled (`::placeholder`).
    ///
    /// A pseudo-ELEMENT rather than a state of the node: it is never set on
    /// a real node during the cascade. The engine turns it on for the single
    /// resolve that produces the prompt's own style, so `::placeholder`
    /// rules travel the same bucketing/inheritance/lookup path as `:hover`
    /// and `:focus` instead of needing storage of their own.
    pub placeholder: bool,
    /// A NON-primary pointer seat focuses this node (`:seat-focus`,
    /// 9b-ii-a-i-d-iii-a). Independent of `focused`, which is the primary's.
    pub seat_focused: bool,
}

impl fmt::Debug for StyledNodeState {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        let mut v = Vec::new();
        if self.hover {
            v.push("hover");
        }
        if self.active {
            v.push("active");
        }
        if self.focused {
            v.push("focused");
        }
        if self.disabled {
            v.push("disabled");
        }
        if self.checked {
            v.push("checked");
        }
        if self.seat_focused {
            v.push("seat_focused");
        }
        if self.focus_within {
            v.push("focus_within");
        }
        if self.visited {
            v.push("visited");
        }
        if self.backdrop {
            v.push("backdrop");
        }
        if self.dragging {
            v.push("dragging");
        }
        if self.drag_over {
            v.push("drag_over");
        }
        if v.is_empty() {
            v.push("normal");
        }
        write!(f, "{v:?}")
    }
}

impl StyledNodeState {
    /// Creates a new state with all states set to false (normal state).
    #[must_use]
    pub const fn new() -> Self {
        Self {
            hover: false,
            active: false,
            focused: false,
            disabled: false,
            checked: false,
            focus_within: false,
            visited: false,
            backdrop: false,
            dragging: false,
            drag_over: false,
            placeholder: false,
            seat_focused: false,
        }
    }

    /// Check if a specific pseudo-state is active
    #[must_use]
    pub const fn has_state(&self, state_type: u8) -> bool {
        match state_type {
            0 => true, // Normal is always active
            1 => self.hover,
            2 => self.active,
            3 => self.focused,
            4 => self.disabled,
            5 => self.checked,
            6 => self.focus_within,
            7 => self.visited,
            8 => self.backdrop,
            9 => self.dragging,
            10 => self.drag_over,
            11 => self.seat_focused,
            _ => false,
        }
    }

    /// Returns true if no special state is active (just normal)
    #[must_use]
    pub const fn is_normal(&self) -> bool {
        !self.hover
            && !self.active
            && !self.focused
            && !self.disabled
            && !self.checked
            && !self.focus_within
            && !self.visited
            && !self.backdrop
            && !self.dragging
            && !self.drag_over
            // The `::placeholder` pseudo-ELEMENT is NOT the normal state:
            // leaving it out here sent the prompt's resolve down the
            // compact-cache fast path, which is keyed for the normal state,
            // so a `::placeholder` rule silently never applied.
            && !self.placeholder
            && !self.seat_focused
    }

    /// Create from `PseudoStateFlags`
    #[must_use]
    pub const fn from_pseudo_state_flags(
        flags: &azul_css::dynamic_selector::PseudoStateFlags,
    ) -> Self {
        Self {
            hover: flags.hover,
            active: flags.active,
            focused: flags.focused,
            disabled: flags.disabled,
            checked: flags.checked,
            focus_within: flags.focus_within,
            visited: flags.visited,
            backdrop: flags.backdrop,
            dragging: flags.dragging,
            drag_over: flags.drag_over,
            placeholder: flags.placeholder,
            seat_focused: flags.seat_focused,
        }
    }
}

/// A styled Dom node
// Per-DOM-node hot type passed by reference throughout the layout/style
// pipeline; kept non-Copy on purpose so it isn't silently bulk-copied and to
// avoid trivially_copy_pass_by_ref churn across the many &StyledNode callers.
#[allow(missing_copy_implementations)]
#[repr(C)]
#[derive(Debug, Default, Clone, PartialEq, Eq, PartialOrd)]
pub struct StyledNode {
    /// Current state of this styled node (used later for caching the style / layout)
    pub styled_node_state: StyledNodeState,
}

impl_option!(
    StyledNode,
    OptionStyledNode,
    copy = false,
    [Debug, Clone, PartialEq, Eq, PartialOrd]
);

impl_vec!(
    StyledNode,
    StyledNodeVec,
    StyledNodeVecDestructor,
    StyledNodeVecDestructorType,
    StyledNodeVecSlice,
    OptionStyledNode
);
impl_vec_mut!(StyledNode, StyledNodeVec);
impl_vec_debug!(StyledNode, StyledNodeVec);
impl_vec_partialord!(StyledNode, StyledNodeVec);
impl_vec_clone!(StyledNode, StyledNodeVec, StyledNodeVecDestructor);
impl_vec_partialeq!(StyledNode, StyledNodeVec);

impl StyledNodeVec {
    /// Returns an immutable container reference for indexed access.
    #[must_use]
    pub fn as_container(&self) -> NodeDataContainerRef<'_, StyledNode> {
        NodeDataContainerRef {
            internal: self.as_ref(),
        }
    }
    /// Returns a mutable container reference for indexed access.
    pub fn as_container_mut(&mut self) -> NodeDataContainerRefMut<'_, StyledNode> {
        NodeDataContainerRefMut {
            internal: self.as_mut(),
        }
    }
}

#[test]
#[allow(clippy::used_underscore_binding)] // intentional `_`-prefix (FFI/api.json pub field, or cfg-gated binding); access is deliberate
fn test_css_styling_with_nested_divs() {
    let s = "
        html, body, p {
            margin: 0;
            padding: 0;
        }
        #div1 {
            border: solid black;
            height: 2in;
            position: absolute;
            top: 1in;
            width: 3in;
        }
        div div {
            background: blue;
            height: 1in;
            position: fixed;
            width: 1in;
        }
    ";

    let css = azul_css::parser2::new_from_str(s);
    let mut _styled_dom = Dom::create_body().with_children(
        vec![Dom::create_div()
            .with_ids_and_classes(vec![crate::dom::IdOrClass::Id("div1".to_string().into())].into())
            .with_children(vec![Dom::create_div()].into())]
        .into(),
    );
    _styled_dom.add_component_css(css.0);
}

/// Regression test for the calc.c "frame ≥2 loses all backgrounds" bug:
/// `recompute_inheritance_and_compact_cache()` must reproduce the
/// `hot_flags` that `create_from_compact_dom` produced on frame 1. If the
/// recompute path silently drops to the getters-only `build_compact_cache`
/// variant, `HOT_FLAG_HAS_BACKGROUND` is never written, the renderer's
/// `has_any_background()` negative fast-path returns false for every node,
/// and every painted background vanishes on the next layout pass.
#[test]
fn test_recompute_preserves_hot_flag_has_background() {
    use azul_css::compact_cache::HOT_FLAG_HAS_BACKGROUND;

    let css_str = "
        body { margin: 0; padding: 0; }
        .painted { background: red; width: 100px; height: 100px; }
    ";
    let css = azul_css::parser2::new_from_str(css_str).0;

    let mut dom = Dom::create_body()
        .with_children(vec![Dom::create_div().with_class("painted".to_string().into())].into());
    let mut styled = StyledDom::create(&mut dom, css);

    // Frame 1: find the painted node by walking its hot_flags.
    let any_bg_frame1 = {
        let cache = styled
            .css_property_cache
            .ptr
            .compact_cache
            .as_ref()
            .expect("compact_cache populated by create_from_compact_dom");
        (0..styled.node_hierarchy.as_ref().len())
            .any(|i| cache.tier2_cold[i].hot_flags & HOT_FLAG_HAS_BACKGROUND != 0)
    };
    assert!(
        any_bg_frame1,
        "frame 1: expected HOT_FLAG_HAS_BACKGROUND on the .painted node",
    );

    // Frame 2+: simulate regenerate_layout rebuilding the compact cache.
    // This is the path the calculator hit on every resize tick, and the
    // one that had silently regressed to the getter-only builder.
    styled.recompute_inheritance_and_compact_cache();

    let any_bg_frame2 = {
        let cache = styled
            .css_property_cache
            .ptr
            .compact_cache
            .as_ref()
            .expect("compact_cache rebuilt by recompute_inheritance_and_compact_cache");
        (0..styled.node_hierarchy.as_ref().len())
            .any(|i| cache.tier2_cold[i].hot_flags & HOT_FLAG_HAS_BACKGROUND != 0)
    };
    assert!(
        any_bg_frame2,
        "frame ≥2 after recompute_inheritance_and_compact_cache: \
         HOT_FLAG_HAS_BACKGROUND disappeared. The recompute path must \
         use build_compact_cache_with_inheritance (not plain \
         build_compact_cache) so apply_css_property_to_compact runs and \
         populates hot_flags for the renderer's negative fast-paths.",
    );
}

/// Calculated hash of a font-family
#[derive(Copy, Clone, Hash, PartialEq, Eq, Ord, PartialOrd)]
pub struct StyleFontFamilyHash(pub u64);

impl ::core::fmt::Debug for StyleFontFamilyHash {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "StyleFontFamilyHash({})", self.0)
    }
}

impl StyleFontFamilyHash {
    /// Computes a 64-bit hash of a font family for cache lookups.
    #[must_use]
    pub fn new(family: &StyleFontFamily) -> Self {
        use core::hash::Hasher;
        let mut hasher = crate::hash::DefaultHasher::new();
        family.hash(&mut hasher);
        Self(hasher.finish())
    }
}

/// Calculated hash of a font-family
#[derive(Copy, Clone, Hash, PartialEq, Eq, Ord, PartialOrd)]
pub struct StyleFontFamiliesHash(pub u64);

impl ::core::fmt::Debug for StyleFontFamiliesHash {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "StyleFontFamiliesHash({})", self.0)
    }
}

impl StyleFontFamiliesHash {
    /// Computes a 64-bit hash of multiple font families for cache lookups.
    #[must_use]
    pub fn new(families: &[StyleFontFamily]) -> Self {
        use core::hash::Hasher;
        let mut hasher = crate::hash::DefaultHasher::new();
        // Prefix with the length so that e.g. `[A, B]` and `[AB]` (or any two
        // family lists whose concatenated element hashes coincide) cannot
        // collide into the same cache key.
        families.len().hash(&mut hasher);
        for f in families {
            f.hash(&mut hasher);
        }
        Self(hasher.finish())
    }
}

/// FFI-safe representation of `Option<NodeId>` as a single `usize`.
///
/// # Encoding (1-based)
///
/// - `inner = 0` -> `None` (no node)
/// - `inner = n > 0` -> `Some(NodeId(n - 1))`
///
/// This type exists because C/C++ cannot use Rust's `Option` type.
/// Use [`NodeHierarchyItemId::into_crate_internal`] to decode and
/// [`NodeHierarchyItemId::from_crate_internal`] to encode.
///
/// # Difference from `NodeId`
///
/// - **`NodeId`**: A 0-based array index. `NodeId::new(0)` refers to the first node.
///   Use directly for array indexing: `nodes[node_id.index()]`.
///
/// - **`NodeHierarchyItemId`**: A 1-based encoded `Option<NodeId>`.
///   `inner = 0` means `None`, `inner = 1` means `Some(NodeId(0))`.
///   **Never use `inner` as an array index!** Always decode first.
///
/// # Warning
///
/// The `inner` field uses **1-based encoding**, not a direct index!
/// Never use `inner` directly as an array index - always decode first.
///
/// # Example
///
/// ```ignore
/// // Encoding: Option<NodeId> -> NodeHierarchyItemId
/// let opt = NodeHierarchyItemId::from_crate_internal(Some(NodeId::new(5)));
/// assert_eq!(opt.into_raw(), 6);  // 5 + 1 = 6
///
/// // Decoding: NodeHierarchyItemId -> Option<NodeId>
/// let decoded = opt.into_crate_internal();
/// assert_eq!(decoded, Some(NodeId::new(5)));
///
/// // None case
/// let none = NodeHierarchyItemId::NONE;
/// assert_eq!(none.into_raw(), 0);
/// assert_eq!(none.into_crate_internal(), None);
/// ```
#[derive(Copy, Clone, PartialEq, Eq, Ord, PartialOrd, Hash)]
#[repr(C)]
pub struct NodeHierarchyItemId {
    // Uses 1-based encoding: 0 = None, n > 0 = Some(NodeId(n-1))
    // Do NOT use directly as an array index!
    inner: usize,
}

impl fmt::Debug for NodeHierarchyItemId {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self.into_crate_internal() {
            Some(n) => write!(f, "Some(NodeId({n}))"),
            None => write!(f, "None"),
        }
    }
}

impl fmt::Display for NodeHierarchyItemId {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "{self:?}")
    }
}

impl NodeHierarchyItemId {
    /// Represents `None` (no node). Encoded as `inner = 0`.
    pub const NONE: Self = Self { inner: 0 };

    /// Creates an `NodeHierarchyItemId` from a raw 1-based encoded value.
    ///
    /// # Warning
    ///
    /// The value must use 1-based encoding (0 = None, n = NodeId(n-1)).
    /// Prefer using [`NodeHierarchyItemId::from_crate_internal`] instead.
    #[inline]
    #[must_use]
    pub const fn from_raw(value: usize) -> Self {
        Self { inner: value }
    }

    /// Returns the raw 1-based encoded value.
    ///
    /// # Warning
    ///
    /// The returned value uses 1-based encoding. Do NOT use as an array index!
    #[inline]
    #[must_use]
    pub const fn into_raw(&self) -> usize {
        self.inner
    }
}

impl_option!(
    NodeHierarchyItemId,
    OptionNodeHierarchyItemId,
    [Debug, Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash]
);

impl_vec!(
    NodeHierarchyItemId,
    NodeHierarchyItemIdVec,
    NodeHierarchyItemIdVecDestructor,
    NodeHierarchyItemIdVecDestructorType,
    NodeHierarchyItemIdVecSlice,
    OptionNodeHierarchyItemId
);
impl_vec_mut!(NodeHierarchyItemId, NodeHierarchyItemIdVec);
impl_vec_debug!(NodeHierarchyItemId, NodeHierarchyItemIdVec);
impl_vec_ord!(NodeHierarchyItemId, NodeHierarchyItemIdVec);
impl_vec_eq!(NodeHierarchyItemId, NodeHierarchyItemIdVec);
impl_vec_hash!(NodeHierarchyItemId, NodeHierarchyItemIdVec);
impl_vec_partialord!(NodeHierarchyItemId, NodeHierarchyItemIdVec);
impl_vec_clone!(
    NodeHierarchyItemId,
    NodeHierarchyItemIdVec,
    NodeHierarchyItemIdVecDestructor
);
impl_vec_partialeq!(NodeHierarchyItemId, NodeHierarchyItemIdVec);

impl NodeHierarchyItemId {
    /// Decodes to `Option<NodeId>` (0 = None, n > 0 = Some(NodeId(n-1))).
    #[inline]
    #[must_use]
    pub const fn into_crate_internal(&self) -> Option<NodeId> {
        NodeId::from_usize(self.inner)
    }

    /// Encodes from `Option<NodeId>` (None -> 0, Some(NodeId(n)) -> n+1).
    #[inline]
    #[must_use]
    pub const fn from_crate_internal(t: Option<NodeId>) -> Self {
        Self {
            inner: NodeId::into_raw(&t),
        }
    }
}

impl From<Option<NodeId>> for NodeHierarchyItemId {
    #[inline]
    fn from(opt: Option<NodeId>) -> Self {
        Self::from_crate_internal(opt)
    }
}

impl From<NodeHierarchyItemId> for Option<NodeId> {
    #[inline]
    fn from(id: NodeHierarchyItemId) -> Self {
        id.into_crate_internal()
    }
}

#[derive(Debug, Copy, Clone, PartialEq, Eq, Ord, PartialOrd, Hash)]
#[repr(C)]
pub struct NodeHierarchyItem {
    pub parent: usize,
    pub previous_sibling: usize,
    pub next_sibling: usize,
    pub last_child: usize,
}

impl_option!(
    NodeHierarchyItem,
    OptionNodeHierarchyItem,
    [Debug, Copy, Clone, PartialEq, Eq, Ord, PartialOrd, Hash]
);

/// Iterator over a DOM node's ancestor chain - see [`hierarchy_ancestors`].
#[derive(Debug)]
pub struct HierarchyAncestors<'a> {
    hierarchy: &'a [NodeHierarchyItem],
    cursor: Option<NodeId>,
    budget: usize,
}

impl Iterator for HierarchyAncestors<'_> {
    type Item = NodeId;

    fn next(&mut self) -> Option<Self::Item> {
        if self.budget == 0 {
            return None;
        }
        let nid = self.cursor?;
        self.budget -= 1;
        self.cursor = self
            .hierarchy
            .get(nid.index())
            .and_then(NodeHierarchyItem::parent_id);
        Some(nid)
    }
}

/// THE ancestor walk over a `NodeHierarchy` - the DOM-tree twin of
/// `LayoutTree::ancestor_chain`.
///
/// Yields `node` (only when `inclusivity` says so) followed by every parent up
/// to the root, nearest first. `inclusivity` is an argument rather than a
/// property of the function's name because that is exactly the distinction
/// `ScrollManager::find_scroll_parent` used to bury in a `nid != node_id`
/// guard, where no caller could see it.
///
/// The walk is bounded by `hierarchy.len()`: no acyclic path can be longer, so
/// a corrupt parent chain terminates instead of spinning.
#[inline]
pub fn hierarchy_ancestors(
    hierarchy: &[NodeHierarchyItem],
    node: NodeId,
    inclusivity: crate::spaces::Inclusivity,
) -> HierarchyAncestors<'_> {
    let cursor = if inclusivity.includes_self() {
        Some(node)
    } else {
        hierarchy
            .get(node.index())
            .and_then(NodeHierarchyItem::parent_id)
    };
    HierarchyAncestors {
        hierarchy,
        cursor,
        budget: hierarchy.len(),
    }
}

impl NodeHierarchyItem {
    /// Creates a zeroed hierarchy item (no parent, siblings, or children).
    #[must_use]
    pub const fn zeroed() -> Self {
        Self {
            parent: 0,
            previous_sibling: 0,
            next_sibling: 0,
            last_child: 0,
        }
    }
}

impl From<Node> for NodeHierarchyItem {
    fn from(node: Node) -> Self {
        Self {
            parent: NodeId::into_raw(&node.parent),
            previous_sibling: NodeId::into_raw(&node.previous_sibling),
            next_sibling: NodeId::into_raw(&node.next_sibling),
            last_child: NodeId::into_raw(&node.last_child),
        }
    }
}

impl NodeHierarchyItem {
    /// Returns the parent node ID, if any.
    #[must_use]
    pub const fn parent_id(&self) -> Option<NodeId> {
        NodeId::from_usize(self.parent)
    }
    /// Returns the previous sibling node ID, if any.
    #[must_use]
    pub const fn previous_sibling_id(&self) -> Option<NodeId> {
        NodeId::from_usize(self.previous_sibling)
    }
    /// Returns the next sibling node ID, if any.
    #[must_use]
    pub const fn next_sibling_id(&self) -> Option<NodeId> {
        NodeId::from_usize(self.next_sibling)
    }
    /// Returns the first child node ID (`current_node_id` + 1 if has children).
    #[must_use]
    pub fn first_child_id(&self, current_node_id: NodeId) -> Option<NodeId> {
        self.last_child_id().map(|_| current_node_id + 1)
    }
    /// Returns the last child node ID, if any.
    #[must_use]
    pub const fn last_child_id(&self) -> Option<NodeId> {
        NodeId::from_usize(self.last_child)
    }
}

impl_vec!(
    NodeHierarchyItem,
    NodeHierarchyItemVec,
    NodeHierarchyItemVecDestructor,
    NodeHierarchyItemVecDestructorType,
    NodeHierarchyItemVecSlice,
    OptionNodeHierarchyItem
);
impl_vec_mut!(NodeHierarchyItem, NodeHierarchyItemVec);
impl_vec_debug!(AzNode, NodeHierarchyItemVec);
impl_vec_partialord!(AzNode, NodeHierarchyItemVec);
impl_vec_clone!(
    NodeHierarchyItem,
    NodeHierarchyItemVec,
    NodeHierarchyItemVecDestructor
);
impl_vec_partialeq!(AzNode, NodeHierarchyItemVec);

impl NodeHierarchyItemVec {
    /// Returns an immutable container reference for indexed access.
    #[must_use]
    pub fn as_container(&self) -> NodeDataContainerRef<'_, NodeHierarchyItem> {
        NodeDataContainerRef {
            internal: self.as_ref(),
        }
    }
    /// Returns a mutable container reference for indexed access.
    pub fn as_container_mut(&mut self) -> NodeDataContainerRefMut<'_, NodeHierarchyItem> {
        NodeDataContainerRefMut {
            internal: self.as_mut(),
        }
    }
}

impl NodeDataContainerRef<'_, NodeHierarchyItem> {
    /// Returns the number of descendant nodes under the given parent.
    #[inline]
    #[must_use]
    pub fn subtree_len(&self, parent_id: NodeId) -> usize {
        let self_item_index = parent_id.index();
        let next_item_index = self[parent_id]
            .next_sibling_id()
            .map_or_else(|| self.len(), |s| s.index());
        // saturating: a malformed FastDom can leave next_sibling <= parent,
        // which would underflow-panic the subtraction.
        next_item_index
            .saturating_sub(self_item_index)
            .saturating_sub(1)
    }
}

#[derive(Copy, Clone, PartialEq, Eq, Ord, PartialOrd, Hash)]
#[repr(C)]
pub struct ParentWithNodeDepth {
    pub depth: usize,
    pub node_id: NodeHierarchyItemId,
}

impl_option!(
    ParentWithNodeDepth,
    OptionParentWithNodeDepth,
    [Copy, Clone, PartialEq, Eq, Ord, PartialOrd, Hash]
);

impl fmt::Debug for ParentWithNodeDepth {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(
            f,
            "{{ depth: {}, node: {:?} }}",
            self.depth,
            self.node_id.into_crate_internal()
        )
    }
}

impl_vec!(
    ParentWithNodeDepth,
    ParentWithNodeDepthVec,
    ParentWithNodeDepthVecDestructor,
    ParentWithNodeDepthVecDestructorType,
    ParentWithNodeDepthVecSlice,
    OptionParentWithNodeDepth
);
impl_vec_mut!(ParentWithNodeDepth, ParentWithNodeDepthVec);
impl_vec_debug!(ParentWithNodeDepth, ParentWithNodeDepthVec);
impl_vec_partialord!(ParentWithNodeDepth, ParentWithNodeDepthVec);
impl_vec_clone!(
    ParentWithNodeDepth,
    ParentWithNodeDepthVec,
    ParentWithNodeDepthVecDestructor
);
impl_vec_partialeq!(ParentWithNodeDepth, ParentWithNodeDepthVec);

#[derive(Debug, Clone, Copy, PartialEq, Eq, Ord, PartialOrd)]
#[repr(C)]
pub struct TagIdToNodeIdMapping {
    // Hit-testing tag ID (not all nodes have a tag, only nodes that are hit-testable)
    pub tag_id: TagId,
    /// Node ID of the node that has a tag
    pub node_id: NodeHierarchyItemId,
    /// Whether this node has a tab-index field
    pub tab_index: OptionTabIndex,
}

impl_option!(
    TagIdToNodeIdMapping,
    OptionTagIdToNodeIdMapping,
    copy = false,
    [Debug, Clone, PartialEq, Eq, Ord, PartialOrd]
);

impl_vec!(
    TagIdToNodeIdMapping,
    TagIdToNodeIdMappingVec,
    TagIdToNodeIdMappingVecDestructor,
    TagIdToNodeIdMappingVecDestructorType,
    TagIdToNodeIdMappingVecSlice,
    OptionTagIdToNodeIdMapping
);
impl_vec_mut!(TagIdToNodeIdMapping, TagIdToNodeIdMappingVec);
impl_vec_debug!(TagIdToNodeIdMapping, TagIdToNodeIdMappingVec);
impl_vec_partialord!(TagIdToNodeIdMapping, TagIdToNodeIdMappingVec);
impl_vec_clone!(
    TagIdToNodeIdMapping,
    TagIdToNodeIdMappingVec,
    TagIdToNodeIdMappingVecDestructor
);
impl_vec_partialeq!(TagIdToNodeIdMapping, TagIdToNodeIdMappingVec);

#[derive(Debug, Clone, PartialEq, PartialOrd)]
#[repr(C)]
pub struct ContentGroup {
    /// The parent of the current node group, i.e. either the root node (0)
    /// or the last positioned node ()
    pub root: NodeHierarchyItemId,
    /// Node ids in order of drawing
    pub children: ContentGroupVec,
}

impl_option!(
    ContentGroup,
    OptionContentGroup,
    copy = false,
    [Debug, Clone, PartialEq, PartialOrd]
);

impl_vec!(
    ContentGroup,
    ContentGroupVec,
    ContentGroupVecDestructor,
    ContentGroupVecDestructorType,
    ContentGroupVecSlice,
    OptionContentGroup
);
impl_vec_mut!(ContentGroup, ContentGroupVec);
impl_vec_debug!(ContentGroup, ContentGroupVec);
impl_vec_partialord!(ContentGroup, ContentGroupVec);
impl_vec_clone!(ContentGroup, ContentGroupVec, ContentGroupVecDestructor);
impl_vec_partialeq!(ContentGroup, ContentGroupVec);

#[derive(Debug, PartialEq, Clone)]
#[repr(C)]
pub struct StyledDom {
    pub root: NodeHierarchyItemId,
    pub node_hierarchy: NodeHierarchyItemVec,
    pub node_data: NodeDataVec,
    pub styled_nodes: StyledNodeVec,
    pub cascade_info: CascadeInfoVec,
    pub nodes_with_window_callbacks: NodeHierarchyItemIdVec,
    pub nodes_with_datasets: NodeHierarchyItemIdVec,
    pub tag_ids_to_node_ids: TagIdToNodeIdMappingVec,
    pub non_leaf_nodes: ParentWithNodeDepthVec,
    pub css_property_cache: CssPropertyCachePtr,
    /// The ID of this DOM in the layout tree (for multi-DOM support with `VirtualViews`)
    pub dom_id: DomId,
}
impl_option!(
    StyledDom,
    OptionStyledDom,
    copy = false,
    [Debug, Clone, PartialEq]
);

impl Default for StyledDom {
    fn default() -> Self {
        let root_node: NodeHierarchyItem = Node::ROOT.into();
        let root_node_id: NodeHierarchyItemId =
            NodeHierarchyItemId::from_crate_internal(Some(NodeId::ZERO));
        Self {
            root: root_node_id,
            node_hierarchy: vec![root_node].into(),
            node_data: vec![NodeData::create_body()].into(),
            styled_nodes: vec![StyledNode::default()].into(),
            cascade_info: vec![CascadeInfo {
                index_in_parent: 0,
                is_last_child: true,
            }]
            .into(),
            tag_ids_to_node_ids: Vec::new().into(),
            non_leaf_nodes: vec![ParentWithNodeDepth {
                depth: 0,
                node_id: root_node_id,
            }]
            .into(),
            nodes_with_window_callbacks: Vec::new().into(),
            nodes_with_datasets: Vec::new().into(),
            css_property_cache: CssPropertyCachePtr::new(CssPropertyCache::empty(1)),
            dom_id: DomId::ROOT_ID,
        }
    }
}

/// Per-field heap-byte breakdown of a `StyledDom`.
#[derive(Debug, Clone, Copy, Default)]
pub struct StyledDomMemoryReport {
    pub node_count: usize,
    pub node_hierarchy_bytes: usize,
    pub node_data_bytes: usize,
    pub styled_nodes_bytes: usize,
    pub cascade_info_bytes: usize,
    pub tag_ids_bytes: usize,
    pub non_leaf_nodes_bytes: usize,
    pub callback_vecs_bytes: usize,
    pub css_property_cache: crate::prop_cache::CssPropertyCacheBreakdown,
}

impl StyledDomMemoryReport {
    #[must_use]
    pub const fn total_bytes(&self) -> usize {
        self.node_hierarchy_bytes
            + self.node_data_bytes
            + self.styled_nodes_bytes
            + self.cascade_info_bytes
            + self.tag_ids_bytes
            + self.non_leaf_nodes_bytes
            + self.callback_vecs_bytes
            + self.css_property_cache.total_bytes()
    }
}

/// `AZ_CASCADE_TRACE=1`: one line per cascade-invalidating decision.
///
/// The two questions this exists to answer are the ones that gate any further
/// work on `CssPropertyCache::css_props` (24.2 MB, the largest remaining line
/// item): how often is the compact cache REBUILT, and how often does the
/// dynamic selector context actually change?
///
/// `css_props` is written only by `restyle()` and is therefore fully
/// reproducible from `retained_author_css`, so it could be pruned of
/// compact-encoded Normal properties and re-derived on demand — but only if
/// rebuilds are RARE. `prune_compact_normal_props` currently refuses to prune
/// it, citing a per-frame rebuild; that claim is untested, and the e2e runner
/// does not exercise `set_dynamic_selector_context` at all, so it cannot be
/// tested there. Run a real app with this dial to settle it.
#[cfg(feature = "std")]
pub(crate) fn cascade_trace(msg: impl FnOnce() -> String) {
    use std::sync::atomic::{AtomicUsize, Ordering};
    use std::sync::OnceLock;
    static ON: OnceLock<bool> = OnceLock::new();
    static N: AtomicUsize = AtomicUsize::new(0);
    if *ON.get_or_init(|| std::env::var("AZ_CASCADE_TRACE").is_ok()) {
        eprintln!("[cascade #{}] {}", N.fetch_add(1, Ordering::Relaxed) + 1, msg());
    }
}

#[cfg(not(feature = "std"))]
pub(crate) fn cascade_trace(_: impl FnOnce() -> alloc::string::String) {}

impl StyledDom {
    /// Approximate heap bytes retained by this `StyledDom`, broken out by field.
    #[must_use]
    pub fn memory_report(&self) -> StyledDomMemoryReport {
        let n = self.node_data.len();
        StyledDomMemoryReport {
            node_count: n,
            node_hierarchy_bytes: size_of_val(self.node_hierarchy.as_ref()),
            node_data_bytes: {
                let base = n * size_of::<NodeData>();
                // NodeData contains inline Vecs (callbacks, css_props, datasets)
                // that have their own heap allocations. Approximate:
                let mut inner = 0usize;
                for nd in self.node_data.as_ref() {
                    inner += nd.get_callbacks().len() * 64; // rough per-callback
                                                            // Each rule = path + decls Vec + conditions Vec + priority byte.
                                                            // Approximate at 64 bytes per rule + the heap for declarations.
                    inner += nd.style.rules.as_ref().len() * 64;
                }
                base + inner
            },
            styled_nodes_bytes: n * size_of::<StyledNode>(),
            cascade_info_bytes: n * size_of::<CascadeInfo>(),
            tag_ids_bytes: size_of_val(self.tag_ids_to_node_ids.as_ref()),
            non_leaf_nodes_bytes: size_of_val(self.non_leaf_nodes.as_ref()),
            callback_vecs_bytes: self.nodes_with_window_callbacks.as_ref().len() * 8
                + self.nodes_with_datasets.as_ref().len() * 8,
            css_property_cache: self.css_property_cache.ptr.memory_breakdown(),
        }
    }

    /// Creates a new `StyledDom` by applying CSS styles to a DOM tree.
    ///
    /// NOTE: After calling this function, the DOM will be reset to an empty DOM.
    // This is for memory optimization, so that the DOM does not need to be cloned.
    //
    // The CSS will be left in-place, but will be re-ordered
    pub fn create(dom: &mut Dom, css: Css) -> Self {
        use core::mem;

        let mut swap_dom = Dom::create_body();
        mem::swap(dom, &mut swap_dom);

        // Silent-loss fix: this entry point used to DISCARD every
        // node-attached stylesheet (`Dom::with_css` / `add_component_css`) —
        // the string parsed, rode the Dom to here, and vanished in the
        // CompactDom conversion, while `create_from_dom` applied it. The
        // classic split-brain constructor: half the callers styled nothing
        // and nobody was told (a `width:260px; height:100px` box silently
        // laid out auto-sized). Collect + subtree-scope exactly like
        // `create_from_dom` (#47), APPENDED after the caller's stylesheet —
        // inline rules already carry `rule_priority::INLINE`, so the cascade
        // ranks them correctly regardless of order.
        swap_dom.fixup_children_estimated();
        let mut next_scope_id = 0usize;
        scope_inline_css(&mut swap_dom, &mut next_scope_id);
        let mut node_css: Vec<Css> = Vec::new();
        collect_css_from_dom(&swap_dom, &mut node_css);
        let css = if node_css.is_empty() {
            css
        } else {
            let mut combined_rules = css.rules.into_library_owned_vec();
            let mut combined_keyframes = css.keyframes.into_library_owned_vec();
            for c in node_css {
                combined_rules.extend(c.rules.into_library_owned_vec());
                combined_keyframes.extend(c.keyframes.into_library_owned_vec());
            }
            let mut merged = Css::new(combined_rules);
            merged.keyframes = combined_keyframes.into();
            merged
        };
        strip_css_from_dom(&mut swap_dom);

        let compact_dom: CompactDom = swap_dom.into();
        let node_hierarchy: NodeHierarchyItemVec = compact_dom
            .node_hierarchy
            .as_ref()
            .internal
            .iter()
            .map(|i| (*i).into())
            .collect::<Vec<NodeHierarchyItem>>()
            .into();

        Self::create_from_compact_dom(compact_dom, css, node_hierarchy)
    }

    /// Creates a `StyledDom` from a `FastDom` (arena-based DOM).
    ///
    /// This skips the `convert_dom_into_compact_dom` tree->arena conversion
    /// entirely since `FastDom` already has flat `NodeHierarchyItemVec` and
    /// `NodeDataVec`. CSS is collected from `CssWithNodeIdVec`.
    #[must_use]
    pub fn create_from_fast_dom(fast_dom: crate::dom::FastDom) -> Self {
        use azul_css::css::Css;

        // 1. Merge CSS from CssWithNodeIdVec into a single Css, scoping each
        //    node-attached stylesheet to its owner's subtree (#47): push_front a
        //    Root([owner, owner+subtree_len]) selector so inline/XML css can't leak
        //    globally — the same scoping the recursive create_from_dom path applies
        //    via scope_inline_css. `node_id` is the owner's flat id (0 = root).
        let mut combined_rules: Vec<azul_css::css::CssRuleBlock> = Vec::new();
        let mut combined_keyframes: Vec<azul_css::css::Keyframes> = Vec::new();
        let css_entries = fast_dom.css.into_library_owned_vec();
        {
            let hierarchy = fast_dom.node_hierarchy.as_container();
            for mut css_with_id in css_entries {
                // Keyframes are name-global (no scoping): collect before the
                // rules are consumed. Later definitions win at resolve time.
                combined_keyframes.extend(
                    core::mem::take(&mut css_with_id.css.keyframes).into_library_owned_vec(),
                );
                let owner = css_with_id.node_id;
                let end = if owner < hierarchy.len() {
                    owner + hierarchy.subtree_len(NodeId::new(owner))
                } else {
                    owner
                };
                for mut rule in css_with_id.css.rules.into_library_owned_vec() {
                    // Bare-declaration wrappers (INLINE priority) stay
                    // node-only; a stylesheet's `* { ... }` (AUTHOR/UA
                    // priority) scopes to the whole subtree. See
                    // push_front_scope_for.
                    let node_only = rule.priority >= azul_css::css::rule_priority::INLINE;
                    rule.path.push_front_scope_for(owner, end, node_only);
                    combined_rules.push(rule);
                }
            }
        }
        let combined_css = if combined_rules.is_empty() && combined_keyframes.is_empty() {
            Css::empty()
        } else {
            let mut css = Css::new(combined_rules);
            css.keyframes = combined_keyframes.into();
            css
        };

        // 2. Convert NodeHierarchyItemVec → NodeHierarchy (Vec<Node>)
        //    for cascade tree computation
        let node_hierarchy_items = fast_dom.node_hierarchy;
        let nodes: Vec<Node> = node_hierarchy_items
            .as_ref()
            .iter()
            .map(|item| Node {
                parent: NodeId::from_usize(item.parent),
                previous_sibling: NodeId::from_usize(item.previous_sibling),
                next_sibling: NodeId::from_usize(item.next_sibling),
                last_child: NodeId::from_usize(item.last_child),
            })
            .collect();
        let node_hierarchy_internal = NodeHierarchy { internal: nodes };

        // 3. Build CompactDom from the flat arenas (no conversion needed)
        let node_data_vec = fast_dom.node_data.into_library_owned_vec();
        let compact_dom = CompactDom {
            node_hierarchy: node_hierarchy_internal,
            node_data: NodeDataContainer {
                internal: node_data_vec,
            },
            root: NodeId::ZERO,
        };

        // 4. Delegate to create() which handles cascade, UA CSS, etc.
        //    We need a mutable Dom to pass to create(), but we already have CompactDom.
        //    Instead, inline the cascade logic from create() with our CompactDom.
        Self::create_from_compact_dom(compact_dom, combined_css, node_hierarchy_items)
    }

    /// Internal: creates `StyledDom` from a `CompactDom` + CSS + pre-built hierarchy items.
    /// Shared by both the Slow path (create -> `convert_dom_into_compact_dom` -> this)
    /// and the Fast path (`create_from_fast_dom` -> this).
    #[allow(clippy::similar_names)] // domain-standard coordinate/control-point names
    #[allow(clippy::too_many_lines)] // large but cohesive: single-purpose parser/builder/dispatch (one branch per input variant)
    fn create_from_compact_dom(
        compact_dom: CompactDom,
        mut css: Css,
        node_hierarchy: NodeHierarchyItemVec,
    ) -> Self {
        use crate::dom::EventFilter;

        static CASCADE_BREAKDOWN: crate::sync::OnceLock<bool> = crate::sync::OnceLock::new();
        let cascade_dbg = *CASCADE_BREAKDOWN.get_or_init(crate::profile::memory_enabled);

        let node_count = compact_dom.len();

        let non_leaf_nodes = compact_dom
            .node_hierarchy
            .as_ref()
            .get_parents_sorted_by_depth();

        let mut styled_nodes = vec![
            StyledNode {
                styled_node_state: StyledNodeState::new()
            };
            node_count
        ];

        let mut css_property_cache = CssPropertyCache::empty(compact_dom.node_data.len());

        let html_tree = construct_html_cascade_tree(
            &compact_dom.node_hierarchy.as_ref(),
            &non_leaf_nodes[..],
            &compact_dom.node_data.as_ref(),
        );

        let non_leaf_nodes = non_leaf_nodes
            .iter()
            .map(|(depth, node_id)| ParentWithNodeDepth {
                depth: *depth,
                node_id: NodeHierarchyItemId::from_crate_internal(Some(*node_id)),
            })
            .collect::<Vec<_>>();

        let non_leaf_nodes: ParentWithNodeDepthVec = non_leaf_nodes.into();

        let _restyle_tag_ids = css_property_cache.restyle(
            &mut css,
            &compact_dom.node_data.as_ref(),
            &node_hierarchy,
            &non_leaf_nodes,
            &html_tree.as_ref(),
        );

        // Retain the author stylesheet on the cache (this used to `drop(css)` to
        // save ~500 KiB, but that made runtime-inserted nodes unstyleable: the
        // rules were gone, so nothing could ever re-run the cascade for them —
        // see e2e/bug-inserted-node-no-author-css.json).
        css_property_cache.retained_author_css = css;

        // Apply UA defaults + compute inherited values so consumers that
        // read `css_property_cache.computed_values` (the web/HTML
        // renderer in `dll/src/web/html_render.rs`) see resolved
        // properties. The compact cache below stores the same info in
        // a different layout for the desktop renderer; computed_values
        // is the "tall" form that the web renderer's CSS emitter
        // (`emit_css_from_cache`) walks per node.
        css_property_cache.apply_ua_css(compact_dom.node_data.as_ref().internal);
        css_property_cache.compute_inherited_values(
            node_hierarchy.as_container().internal,
            compact_dom.node_data.as_ref().internal,
        );

        let prev_font_hashes: Vec<u64> = css_property_cache
            .compact_cache
            .as_ref()
            .map(|c| c.prev_font_hashes.clone())
            .unwrap_or_default();
        let compact = css_property_cache.build_compact_cache_with_inheritance(
            compact_dom.node_data.as_ref().internal,
            node_hierarchy.as_container().internal,
            &prev_font_hashes,
        );
        css_property_cache.compact_cache = Some(compact);
        let pre_prune = if cascade_dbg {
            Some(css_property_cache.memory_breakdown())
        } else {
            None
        };
        css_property_cache.prune_compact_normal_props();
        if let Some(pre) = pre_prune {
            let post = css_property_cache.memory_breakdown();
            #[cfg(feature = "std")]
            eprintln!(
                "[PRUNE] css_props {} → {} KiB  cascaded {} → {} KiB  (saved {} KiB)",
                pre.css_props_bytes / 1024,
                post.css_props_bytes / 1024,
                pre.cascaded_props_bytes / 1024,
                post.cascaded_props_bytes / 1024,
                (pre.total_bytes().saturating_sub(post.total_bytes())) / 1024
            );
            #[cfg(not(feature = "std"))]
            let _ = post;
        }

        let tag_ids =
            css_property_cache.generate_tag_ids(&compact_dom.node_data.as_ref(), &node_hierarchy);

        if cascade_dbg {
            let bd = css_property_cache.memory_breakdown();
            #[cfg(feature = "std")]
            eprintln!("[CASCADE] {} nodes  cascaded_props={} KiB  css_props={} KiB  compact={} KiB  computed={} KiB  total={} KiB",
                node_count,
                bd.cascaded_props_bytes / 1024, bd.css_props_bytes / 1024,
                bd.compact_cache_bytes / 1024, bd.computed_values_bytes / 1024,
                bd.total_bytes() / 1024);
            #[cfg(not(feature = "std"))]
            let _ = bd;
        }

        // Collect callback/dataset nodes in a single pass (avoids 3 separate 50K scans).
        // For XHTML-parsed DOMs with no callbacks, this early-exits immediately.
        let has_any_callbacks = compact_dom
            .node_data
            .as_ref()
            .internal
            .iter()
            .any(|c| !c.get_callbacks().is_empty() || c.get_dataset().is_some());

        let (nodes_with_window_callbacks, nodes_with_datasets) = if has_any_callbacks {
            let mut win_cbs = Vec::new();
            let mut datasets = Vec::new();
            for (node_id, c) in compact_dom.node_data.as_ref().internal.iter().enumerate() {
                let cbs = c.get_callbacks();
                let has_dataset = c.get_dataset().is_some();
                if !cbs.is_empty() || has_dataset {
                    datasets.push(NodeHierarchyItemId::from_crate_internal(Some(NodeId::new(
                        node_id,
                    ))));
                }
                for cb in cbs {
                    if let EventFilter::Window(_) = cb.event {
                        win_cbs.push(NodeHierarchyItemId::from_crate_internal(Some(NodeId::new(
                            node_id,
                        ))));
                        break;
                    }
                }
            }
            (win_cbs, datasets)
        } else {
            (Vec::new(), Vec::new())
        };
        let mut styled_dom = Self {
            root: NodeHierarchyItemId::from_crate_internal(Some(compact_dom.root)),
            node_hierarchy,
            node_data: compact_dom.node_data.internal.into(),
            cascade_info: html_tree.internal.into(),
            styled_nodes: styled_nodes.into(),
            tag_ids_to_node_ids: tag_ids.into(),
            nodes_with_window_callbacks: nodes_with_window_callbacks.into(),
            nodes_with_datasets: nodes_with_datasets.into(),
            non_leaf_nodes,
            css_property_cache: CssPropertyCachePtr::new(css_property_cache),
            dom_id: DomId::ROOT_ID,
        };
        #[cfg(feature = "table_layout")]
        if let Err(_e) = crate::dom_table::generate_anonymous_table_elements(&mut styled_dom) {}

        styled_dom
    }

    /// Creates a `StyledDom` from a recursive Dom tree with deferred CSS.
    ///
    /// This is the Phase 7.2 entry point: the layout callback returns a recursive
    /// `Dom` with `css: Vec<Css>` on each node. This function:
    ///
    /// 1. Collects all CSS objects from the recursive tree
    /// 2. Flattens the Dom into contiguous arrays (`CompactDom`)
    /// 3. Merges all CSS objects and runs a single cascade pass
    /// 4. Runs `apply_ua_css` -> `compute_inherited_values` -> `build_compact_cache`
    /// 5. Generates anonymous table elements
    #[must_use]
    pub fn create_from_dom(mut dom: Dom) -> Self {
        use azul_css::css::Css;

        // #47: scope each node's inline css to its subtree BEFORE collecting, so a
        // non-root node's with_css cannot leak to the whole tree. Uses the same
        // pre-order ids the flatten (convert_dom_into_compact_dom) will assign;
        // needs estimated_total_children populated first.
        dom.fixup_children_estimated();
        let mut next_scope_id = 0usize;
        scope_inline_css(&mut dom, &mut next_scope_id);

        // 1. Collect all CSS objects from the recursive Dom tree (now scoped)
        let mut all_css = Vec::new();
        collect_css_from_dom(&dom, &mut all_css);

        // 2. Merge all CSS objects into one combined Css
        let mut combined_css = if all_css.is_empty() {
            Css::empty()
        } else {
            let mut combined_rules: Vec<azul_css::css::CssRuleBlock> = Vec::new();
            let mut combined_keyframes: Vec<azul_css::css::Keyframes> = Vec::new();
            for css in all_css {
                combined_rules.extend(css.rules.into_library_owned_vec());
                combined_keyframes.extend(css.keyframes.into_library_owned_vec());
            }
            let mut css = Css::new(combined_rules);
            css.keyframes = combined_keyframes.into();
            css
        };

        // 3. Strip CSS from all Dom nodes before flattening
        //    (CSS is already collected, don't need it in the flat tree)
        strip_css_from_dom(&mut dom);

        // 4. Use existing StyledDom::create to flatten + cascade
        Self::create(&mut dom, combined_css)
    }

    /// Appends another `StyledDom` as a child to the `self.root`
    /// without re-styling the DOM itself
    pub fn append_child(&mut self, other: Self) {
        let self_root_id = self.root.into_crate_internal().unwrap_or(NodeId::ZERO);
        let current_root_children_count = self_root_id
            .az_children(&self.node_hierarchy.as_container())
            .count();
        self.append_child_with_index(other, current_root_children_count);
        self.finalize_non_leaf_nodes();
    }

    /// Optimized version of `append_child` that takes the child index directly
    /// instead of counting existing children (O(1) instead of O(n))
    pub fn append_child_with_index(&mut self, mut other: Self, child_index: usize) {
        // shift all the node ids in other by self.len()
        let self_len = self.node_hierarchy.as_ref().len();
        let other_len = other.node_hierarchy.as_ref().len();
        let self_root_id = self.root.into_crate_internal().unwrap_or(NodeId::ZERO);
        let other_root_id = other.root.into_crate_internal().unwrap_or(NodeId::ZERO);

        // Use provided index instead of counting children
        other.cascade_info.as_mut()[other_root_id.index()].index_in_parent =
            u32::try_from(child_index).unwrap_or(u32::MAX);
        other.cascade_info.as_mut()[other_root_id.index()].is_last_child = true;

        self.cascade_info.append(&mut other.cascade_info);

        // adjust node hierarchy
        for other in other.node_hierarchy.as_mut().iter_mut() {
            if other.parent != 0 {
                other.parent += self_len;
            }
            if other.previous_sibling != 0 {
                other.previous_sibling += self_len;
            }
            if other.next_sibling != 0 {
                other.next_sibling += self_len;
            }
            if other.last_child != 0 {
                other.last_child += self_len;
            }
        }

        other.node_hierarchy.as_container_mut()[other_root_id].parent =
            NodeId::into_raw(&Some(self_root_id));
        let current_last_child = self.node_hierarchy.as_container()[self_root_id].last_child_id();
        other.node_hierarchy.as_container_mut()[other_root_id].previous_sibling =
            NodeId::into_raw(&current_last_child);
        if let Some(current_last) = current_last_child {
            if self.node_hierarchy.as_container_mut()[current_last]
                .next_sibling_id()
                .is_some()
            {
                self.node_hierarchy.as_container_mut()[current_last].next_sibling +=
                    other_root_id.index() + other_len;
            } else {
                self.node_hierarchy.as_container_mut()[current_last].next_sibling =
                    NodeId::into_raw(&Some(NodeId::new(self_len + other_root_id.index())));
            }
        }
        self.node_hierarchy.as_container_mut()[self_root_id].last_child =
            NodeId::into_raw(&Some(NodeId::new(self_len + other_root_id.index())));

        self.node_hierarchy.append(&mut other.node_hierarchy);
        self.node_data.append(&mut other.node_data);
        self.styled_nodes.append(&mut other.styled_nodes);
        self.get_css_property_cache_mut()
            .append(other.get_css_property_cache_mut());

        // Tag IDs are globally unique (AtomicUsize counter) and never collide,
        // so we only shift node_id (which changes when DOMs are merged).
        for tag_id_node_id in &mut other.tag_ids_to_node_ids {
            tag_id_node_id.node_id.inner += self_len;
        }

        self.tag_ids_to_node_ids
            .append(&mut other.tag_ids_to_node_ids);

        for nid in &mut other.nodes_with_window_callbacks {
            nid.inner += self_len;
        }
        self.nodes_with_window_callbacks
            .append(&mut other.nodes_with_window_callbacks);

        for nid in &mut other.nodes_with_datasets {
            nid.inner += self_len;
        }
        self.nodes_with_datasets
            .append(&mut other.nodes_with_datasets);

        // edge case: if the other StyledDom consists of only one node
        // then it is not a parent itself
        if other_len != 1 {
            for other_non_leaf_node in &mut other.non_leaf_nodes {
                other_non_leaf_node.node_id.inner += self_len;
                other_non_leaf_node.depth += 1;
            }
            self.non_leaf_nodes.append(&mut other.non_leaf_nodes);
            // NOTE: Sorting deferred - call finalize_non_leaf_nodes() after all appends
        }
    }

    /// Call this after all `append_child_with_index` operations are complete
    /// to sort `non_leaf_nodes` by depth (required for correct rendering)
    pub fn finalize_non_leaf_nodes(&mut self) {
        self.non_leaf_nodes.sort_by(|a, b| a.depth.cmp(&b.depth));
    }

    /// Same as `append_child()`, but as a builder method
    #[must_use]
    pub fn with_child(mut self, other: Self) -> Self {
        self.append_child(other);
        self
    }

    /// Sets the context menu for the root node
    pub fn set_context_menu(&mut self, context_menu: Menu) {
        if let Some(root_id) = self.root.into_crate_internal() {
            self.node_data.as_container_mut()[root_id].set_context_menu(context_menu);
        }
    }

    /// Builder method for setting the context menu
    #[must_use]
    pub fn with_context_menu(mut self, context_menu: Menu) -> Self {
        self.set_context_menu(context_menu);
        self
    }

    /// Sets the menu bar for the root node
    pub fn set_menu_bar(&mut self, menu_bar: Menu) {
        if let Some(root_id) = self.root.into_crate_internal() {
            self.node_data.as_container_mut()[root_id].set_menu_bar(menu_bar);
        }
    }

    /// Builder method for setting the menu bar
    #[must_use]
    pub fn with_menu_bar(mut self, menu_bar: Menu) -> Self {
        self.set_menu_bar(menu_bar);
        self
    }

    /// Re-compute inherited CSS values and rebuild the compact layout cache.
    ///
    /// This MUST be called after `append_child()` merges multiple `StyledDom`s.
    /// `append_child()` concatenates the CSS property caches but does NOT
    /// re-run inheritance or rebuild the compact cache. This means:
    ///
    /// 1. **Broken inheritance**: Inherited properties (`color`, `font-size`,
    ///    `direction`) from the parent DOM do not flow into appended subtrees.
    /// 2. **Stale compact cache**: The child's tier 1/2/2b entries still reflect
    ///    the child's isolated cascade, not the composed tree.
    ///
    /// Calling this method after all `append_child()` calls fixes both issues
    /// by re-running a full depth-first inheritance pass and rebuilding the
    /// compact cache from scratch on the composed tree.
    pub fn recompute_inheritance_and_compact_cache(&mut self) {
        cascade_trace(|| "compact cache REBUILT from css_props".to_string());
        // Use the _with_inheritance variant: it does inheritance inline (via
        // parent-compact-field copy) AND populates hot_flags via
        // apply_css_property_to_compact.  The plain build_compact_cache would
        // leave HOT_FLAG_HAS_BACKGROUND / HAS_CLIP_PATH / extra_flags at 0,
        // causing renderer negative fast-paths to skip paint (regression
        // introduced by ff059052b).  No SIGABRT risk — _with_inheritance
        // never pushes to the flat cascaded_props storage.
        let prev_font_hashes: Vec<u64> = self
            .css_property_cache
            .downcast_mut()
            .compact_cache
            .as_ref()
            .map(|c| c.prev_font_hashes.clone())
            .unwrap_or_default();
        let compact = self
            .css_property_cache
            .downcast_mut()
            .build_compact_cache_with_inheritance(
                self.node_data.as_container().internal,
                self.node_hierarchy.as_container().internal,
                &prev_font_hashes,
            );
        self.css_property_cache.downcast_mut().compact_cache = Some(compact);
    }

    /// Re-applies CSS styles to the existing DOM structure.
    /// Grow retained author-CSS subtree scopes to cover a node just appended under
    /// `parent`. Mount/`with_css` rules carry a `Root([start, end])` scope
    /// (`push_front_scope`) that only matches nodes within a node's ORIGINAL subtree
    /// range, so a node appended afterwards falls outside every scope and
    /// `restyle_retained` cannot match it. Appending under `parent` (rightmost-spine
    /// only, so subtrees stay contiguous in the flat arena) grows `parent`'s and its
    /// ancestors' subtrees; bump the inclusive `end` of every scope that already
    /// covers `parent` out to the new node.
    #[allow(clippy::similar_names)] // new_node/parent and the p/n index locals read clearly in context
    pub fn extend_author_scopes_for_appended(&mut self, new_node: NodeId, parent: NodeId) {
        use azul_css::css::CssPathSelector;
        let p = parent.index();
        let n = new_node.index();
        let cache = self.css_property_cache.downcast_mut();
        for rule in cache.retained_author_css.rules.as_mut() {
            let mut sels = rule.path.selectors.as_ref().to_vec();
            let mut changed = false;
            for sel in &mut sels {
                if let CssPathSelector::Root(range) = sel {
                    if range.contains(p) && range.end < n {
                        range.end = n;
                        changed = true;
                    }
                }
            }
            if changed {
                rule.path.selectors = sels.into();
            }
        }
    }

    /// Re-run the author cascade from the stylesheet retained at creation /
    /// last `restyle` (`CssPropertyCache::retained_author_css`). Call after a
    /// structural DOM mutation (e.g. inserting a node) so new nodes receive
    /// author CSS; a no-op when no author stylesheet was ever attached.
    /// The PER-TICK override channel: write `user_overridden_properties`
    /// WITHOUT recomputing inheritance or the compact cache. Sound only when
    /// the caller supplies the pixels itself (the transition driver patches
    /// the display list with the interpolated value directly) - every other
    /// caller wants [`Self::restyle_user_property`]. At t=1 the override is
    /// removed and the (correctly cascaded) target shows through.
    pub fn set_user_property_override_fast(
        &mut self,
        node_id: &NodeId,
        new_properties: &[CssProperty],
    ) {
        let node_count = self.node_data.as_ref().len();
        if node_id.index() >= node_count {
            return;
        }
        let cache = self.get_css_property_cache_mut();
        if cache.user_overridden_properties.len() < node_count {
            cache
                .user_overridden_properties
                .resize(node_count, Vec::new());
        }
        for new_prop in new_properties {
            let prop_type = new_prop.get_type();
            let vec = &mut cache.user_overridden_properties[node_id.index()];
            if new_prop.is_initial() {
                if let Ok(idx) = vec.binary_search_by_key(&prop_type, |(k, _)| *k) {
                    vec.remove(idx);
                }
            } else {
                match vec.binary_search_by_key(&prop_type, |(k, _)| *k) {
                    Ok(idx) => vec[idx].1 = new_prop.clone(),
                    Err(idx) => vec.insert(idx, (prop_type, new_prop.clone())),
                }
            }
        }
    }

    pub fn restyle_retained(&mut self) {
        let css = self
            .css_property_cache
            .downcast_mut()
            .retained_author_css
            .clone();
        if css.is_empty() {
            return;
        }
        self.restyle(css);
    }

    pub fn restyle(&mut self, mut css: Css) {
        // NOTE: the tag_ids returned by `cache.restyle` here are generated from
        // the STALE `compact_cache` (display/overflow reads) and are intentionally
        // discarded — we regenerate them below AFTER the compact cache and
        // inheritance have been recomputed (audit styled_dom.rs:1404/1426).
        let _stale_tag_ids = self.css_property_cache.downcast_mut().restyle(
            &mut css,
            &self.node_data.as_container(),
            &self.node_hierarchy,
            &self.non_leaf_nodes,
            &self.cascade_info.as_container(),
        );

        // Keep the stylesheet for later structural restyles (inserted nodes).
        self.css_property_cache.downcast_mut().retained_author_css = css;

        // Apply UA CSS properties before computing inheritance
        self.css_property_cache
            .downcast_mut()
            .apply_ua_css(self.node_data.as_container().internal);

        // Compute inherited values after restyle and apply_ua_css (resolves em, %, etc.)
        self.css_property_cache
            .downcast_mut()
            .compute_inherited_values(
                self.node_hierarchy.as_container().internal,
                self.node_data.as_container().internal,
            );

        // The old compact_cache was built from the pre-restyle CSS. If we do not
        // rebuild it, layout-hot properties (display/overflow/background/clip,
        // resolved font sizes) keep their stale values and the restyle silently
        // no-ops for them. Drop it, rebuild via the _with_inheritance path (which
        // repopulates hot_flags), and invalidate the cached resolved font sizes.
        let prev_font_hashes: Vec<u64> = self
            .css_property_cache
            .downcast_mut()
            .compact_cache
            .as_ref()
            .map(|c| c.prev_font_hashes.clone())
            .unwrap_or_default();
        self.css_property_cache.downcast_mut().compact_cache = None;
        let compact = self
            .css_property_cache
            .downcast_mut()
            .build_compact_cache_with_inheritance(
                self.node_data.as_container().internal,
                self.node_hierarchy.as_container().internal,
                &prev_font_hashes,
            );
        self.css_property_cache.downcast_mut().compact_cache = Some(compact);
        self.css_property_cache
            .downcast_mut()
            .invalidate_resolved_font_sizes();

        // Regenerate tag_ids from the freshly rebuilt compact cache so the
        // hit-test map reflects the post-restyle display/overflow values.
        let new_tag_ids = self
            .css_property_cache
            .downcast_mut()
            .generate_tag_ids(&self.node_data.as_container(), &self.node_hierarchy);
        self.tag_ids_to_node_ids = new_tag_ids.into();
    }

    /// Returns the total number of nodes in this `StyledDom`.
    #[inline]
    #[must_use]
    pub const fn node_count(&self) -> usize {
        self.node_data.len()
    }

    /// Returns an immutable reference to the CSS property cache.
    #[inline]
    #[must_use]
    pub fn get_css_property_cache(&self) -> &CssPropertyCache {
        &self.css_property_cache.ptr
    }

    /// Returns a mutable reference to the CSS property cache.
    #[inline]
    pub fn get_css_property_cache_mut(&mut self) -> &mut CssPropertyCache {
        &mut self.css_property_cache.ptr
    }

    /// Returns the current state (hover, active, focus) of a styled node.
    #[inline]
    #[must_use]
    pub fn get_styled_node_state(&self, node_id: &NodeId) -> StyledNodeState {
        self.styled_nodes.as_container()[*node_id].styled_node_state
    }

    /// Updates hover state for nodes and returns changed CSS properties.
    #[must_use]
    pub fn restyle_nodes_hover(&mut self, nodes: &[NodeId], new_hover_state: bool) -> RestyleNodes {
        self.restyle_nodes_state(
            nodes,
            new_hover_state,
            |state, val| state.hover = val,
            azul_css::dynamic_selector::PseudoStateType::Hover,
        )
    }

    /// Updates active state for nodes and returns changed CSS properties.
    #[must_use]
    pub fn restyle_nodes_active(
        &mut self,
        nodes: &[NodeId],
        new_active_state: bool,
    ) -> RestyleNodes {
        self.restyle_nodes_state(
            nodes,
            new_active_state,
            |state, val| state.active = val,
            azul_css::dynamic_selector::PseudoStateType::Active,
        )
    }

    /// Updates focus state for nodes and returns changed CSS properties.
    #[must_use]
    pub fn restyle_nodes_focus(&mut self, nodes: &[NodeId], new_focus_state: bool) -> RestyleNodes {
        self.restyle_nodes_state(
            nodes,
            new_focus_state,
            |state, val| state.focused = val,
            azul_css::dynamic_selector::PseudoStateType::Focus,
        )
    }

    /// `:seat-focus` on/off for `nodes` (9b-ii-a-i-d-iii-a).
    pub fn restyle_nodes_seat_focus(&mut self, nodes: &[NodeId], on: bool) -> RestyleNodes {
        self.restyle_nodes_state(
            nodes,
            on,
            |state, val| state.seat_focused = val,
            azul_css::dynamic_selector::PseudoStateType::SeatFocus,
        )
    }

    /// A non-primary seat's focus moved: `lost` drops `:seat-focus`, `gained`
    /// takes it. Same result classification as `restyle_on_state_change`.
    pub fn restyle_on_seat_focus_change(
        &mut self,
        lost: Option<NodeId>,
        gained: Option<NodeId>,
    ) -> RestyleResult {
        let mut result = RestyleResult {
            gpu_only_changes: true,
            ..RestyleResult::default()
        };
        let mut process = |changes: RestyleNodes, result: &mut RestyleResult| {
            for (node_id, props) in changes {
                for change in &props {
                    let prop_type = change.current_prop.get_type();
                    let scope = prop_type.relayout_scope(true);
                    if scope > result.max_relayout_scope {
                        result.max_relayout_scope = scope;
                    }
                    if scope != RelayoutScope::None {
                        result.needs_layout = true;
                        result.gpu_only_changes = false;
                    }
                    if !prop_type.is_gpu_only_property() {
                        result.gpu_only_changes = false;
                    }
                    result.needs_display_list = true;
                }
                result.changed_nodes.entry(node_id).or_default().extend(props);
            }
        };
        if let Some(old) = lost {
            let changes = self.restyle_nodes_seat_focus(&[old], false);
            process(changes, &mut result);
        }
        if let Some(new) = gained {
            let changes = self.restyle_nodes_seat_focus(&[new], true);
            process(changes, &mut result);
        }
        result
    }

    /// Generic restyle method parameterized by the state field and pseudo-state type.
    fn restyle_nodes_state(
        &mut self,
        nodes: &[NodeId],
        new_state_value: bool,
        set_state: impl Fn(&mut StyledNodeState, bool),
        pseudo_state_type: azul_css::dynamic_selector::PseudoStateType,
    ) -> RestyleNodes {
        // Drop any stale NodeIds that no longer index into this DOM (e.g. left
        // over from a previous, larger tree). Indexing styled_nodes / node_data
        // with an out-of-range id would panic. Filtering here keeps the
        // downstream zip with `old_node_states` aligned.
        let node_count = self.node_count();
        let nodes: Vec<NodeId> = nodes
            .iter()
            .copied()
            .filter(|nid| nid.index() < node_count)
            .collect();

        // save the old node state
        let old_node_states = nodes
            .iter()
            .map(|nid| self.styled_nodes.as_container()[*nid].styled_node_state)
            .collect::<Vec<_>>();

        for nid in &nodes {
            set_state(
                &mut self.styled_nodes.as_container_mut()[*nid].styled_node_state,
                new_state_value,
            );
        }

        let css_property_cache = self.get_css_property_cache();
        let styled_nodes = self.styled_nodes.as_container();
        let node_data = self.node_data.as_container();

        // scan all properties that could have changed because of addition / removal
        let v = nodes
            .iter()
            .zip(old_node_states.iter())
            .filter_map(|(node_id, old_node_state)| {
                let mut keys_normal: Vec<_> = CssPropertyCache::prop_types_for_state(
                    css_property_cache.css_props.get_slice(node_id.index()),
                    pseudo_state_type,
                ).collect();
                let mut keys_inherited: Vec<_> = CssPropertyCache::prop_types_for_state(
                    css_property_cache.cascaded_props.get_slice(node_id.index()),
                    pseudo_state_type,
                ).collect();
                let keys_inline: Vec<CssPropertyType> = {
                    use azul_css::dynamic_selector::DynamicSelector;
                    node_data[*node_id]
                        .style
                        .iter_inline_properties()
                        .filter_map(|(prop, conds)| {
                            let matches = conds.as_slice().iter().any(|c| {
                                matches!(c, DynamicSelector::PseudoState(pst) if *pst == pseudo_state_type)
                            });
                            if matches {
                                Some(prop.get_type())
                            } else {
                                None
                            }
                        })
                        .collect()
                };
                let mut keys_inline_ref: Vec<_> = keys_inline.iter().collect();

                keys_normal.append(&mut keys_inherited);
                keys_normal.append(&mut keys_inline_ref);

                let node_properties_that_could_have_changed = keys_normal;

                if node_properties_that_could_have_changed.is_empty() {
                    return None;
                }

                let new_node_state = &styled_nodes[*node_id].styled_node_state;
                let node_data = &node_data[*node_id];

                let changes = node_properties_that_could_have_changed
                    .into_iter()
                    .filter_map(|prop| {
                        // calculate both the old and the new state
                        let old = css_property_cache.get_property_slow(
                            node_data,
                            node_id,
                            old_node_state,
                            prop,
                        );
                        let new = css_property_cache.get_property_slow(
                            node_data,
                            node_id,
                            new_node_state,
                            prop,
                        );
                        if old == new {
                            None
                        } else {
                            Some(ChangedCssProperty {
                                previous_state: *old_node_state,
                                previous_prop: old.map_or_else(|| CssProperty::auto(*prop), Clone::clone),
                                current_state: *new_node_state,
                                current_prop: new.map_or_else(|| CssProperty::auto(*prop), Clone::clone),
                            })
                        }
                    })
                    .collect::<Vec<_>>();

                if changes.is_empty() {
                    None
                } else {
                    Some((*node_id, changes))
                }
            })
            .collect::<Vec<_>>();

        v.into_iter().collect()
    }

    /// Unified entry point for all CSS restyle operations.
    ///
    /// This function synchronizes the `StyledNodeState` with runtime state
    /// and computes which CSS properties have changed. It determines whether
    /// layout, display list, or GPU-only updates are needed.
    ///
    /// # Arguments
    /// * `focus_changes` - Nodes gaining/losing focus
    /// * `hover_changes` - Nodes gaining/losing hover
    /// * `active_changes` - Nodes gaining/losing active (mouse down)
    ///
    /// # Returns
    /// * `RestyleResult` containing changed nodes and what needs updating
    #[must_use]
    pub fn restyle_on_state_change(
        &mut self,
        focus_changes: Option<FocusChange>,
        hover_changes: Option<HoverChange>,
        active_changes: Option<ActiveChange>,
    ) -> RestyleResult {
        // Start with GPU-only assumption; refined below as changes are analyzed.
        let mut result = RestyleResult {
            gpu_only_changes: true,
            ..RestyleResult::default()
        };

        // Helper closure to merge changes and analyze property categories
        let mut process_changes = |changes: RestyleNodes| {
            for (node_id, props) in changes {
                for change in &props {
                    let prop_type = change.current_prop.get_type();

                    // Use the granular RelayoutScope instead of the binary
                    // can_trigger_relayout(). We pass node_is_ifc_member = true
                    // conservatively: this means font/text property changes will
                    // produce IfcOnly (rather than None). Phase 2c can refine
                    // this by checking whether the node actually participates
                    // in an IFC.
                    let scope = prop_type.relayout_scope(/* node_is_ifc_member */ true);

                    // Track the highest scope seen
                    if scope > result.max_relayout_scope {
                        result.max_relayout_scope = scope;
                    }

                    // Any scope above None triggers layout
                    if scope != RelayoutScope::None {
                        result.needs_layout = true;
                        result.gpu_only_changes = false;
                    }

                    // Check if this is a GPU-only property
                    if !prop_type.is_gpu_only_property() {
                        result.gpu_only_changes = false;
                    }

                    // Any visual change needs display list update (unless GPU-only)
                    result.needs_display_list = true;
                }

                result
                    .changed_nodes
                    .entry(node_id)
                    .or_default()
                    .extend(props);
            }
        };

        // 1. Process focus changes
        if let Some(focus) = focus_changes {
            if let Some(old) = focus.lost_focus {
                let changes = self.restyle_nodes_focus(&[old], false);
                process_changes(changes);
            }
            if let Some(new) = focus.gained_focus {
                let changes = self.restyle_nodes_focus(&[new], true);
                process_changes(changes);
            }
        }

        // 2. Process hover changes
        if let Some(hover) = hover_changes {
            if !hover.left_nodes.is_empty() {
                let changes = self.restyle_nodes_hover(&hover.left_nodes, false);
                process_changes(changes);
            }
            if !hover.entered_nodes.is_empty() {
                let changes = self.restyle_nodes_hover(&hover.entered_nodes, true);
                process_changes(changes);
            }
        }

        // 3. Process active changes
        if let Some(active) = active_changes {
            if !active.deactivated.is_empty() {
                let changes = self.restyle_nodes_active(&active.deactivated, false);
                process_changes(changes);
            }
            if !active.activated.is_empty() {
                let changes = self.restyle_nodes_active(&active.activated, true);
                process_changes(changes);
            }
        }

        // If no changes, reset display_list flag
        if result.changed_nodes.is_empty() {
            result.needs_display_list = false;
            result.gpu_only_changes = false;
        }

        // If layout is needed, display list is also needed
        if result.needs_layout {
            result.needs_display_list = true;
            result.gpu_only_changes = false;
        }

        result
    }

    /// Overrides CSS properties for a single node from user code (typically a
    /// callback). Writes into `CssPropertyCache::user_overridden_properties`,
    /// which `get_property_slow` / `get_property_fast` / `get_computed_value`
    /// consult at higher priority than the static CSS cascade - making this
    /// the fast path for animating a handful of properties per frame.
    ///
    /// Passing `CssProperty::Initial` for a property removes any override for
    /// that type, restoring the cascaded value. Returns the set of
    /// `ChangedCssProperty` entries the caller can feed into the incremental
    /// restyle pipeline.
    #[must_use]
    pub fn restyle_user_property(
        &mut self,
        node_id: &NodeId,
        new_properties: &[CssProperty],
    ) -> RestyleNodes {
        let mut map = BTreeMap::default();

        if new_properties.is_empty() {
            return map;
        }

        let node_count = self.node_data.as_ref().len();
        if node_id.index() >= node_count {
            return map;
        }

        let node_data = self.node_data.as_container();
        let node_data = &node_data[*node_id];

        let node_states = &self.styled_nodes.as_container();
        let old_node_state = &node_states[*node_id].styled_node_state;

        let changes: Vec<ChangedCssProperty> = {
            let css_property_cache = self.get_css_property_cache();

            new_properties
                .iter()
                .filter_map(|new_prop| {
                    let old_prop = css_property_cache.get_property_slow(
                        node_data,
                        node_id,
                        old_node_state,
                        &new_prop.get_type(),
                    );

                    let old_prop = old_prop
                        .map_or_else(|| CssProperty::auto(new_prop.get_type()), Clone::clone);

                    if old_prop == *new_prop {
                        None
                    } else {
                        Some(ChangedCssProperty {
                            previous_state: *old_node_state,
                            previous_prop: old_prop,
                            // overriding a user property does not change the state
                            current_state: *old_node_state,
                            current_prop: new_prop.clone(),
                        })
                    }
                })
                .collect()
        };

        let css_property_cache_mut = self.get_css_property_cache_mut();

        // user_overridden_properties is built lazily (empty after StyledDom
        // construction). Grow to cover this node_id before indexing so the
        // override path works on any DOM, not just ones that already have
        // overrides from a prior mutation.
        if css_property_cache_mut.user_overridden_properties.len() < node_count {
            css_property_cache_mut
                .user_overridden_properties
                .resize(node_count, Vec::new());
        }

        for new_prop in new_properties {
            let prop_type = new_prop.get_type();
            let vec = &mut css_property_cache_mut.user_overridden_properties[node_id.index()];
            if new_prop.is_initial() {
                // CssProperty::Initial = remove overridden property
                if let Ok(idx) = vec.binary_search_by_key(&prop_type, |(k, _)| *k) {
                    vec.remove(idx);
                }
            } else {
                match vec.binary_search_by_key(&prop_type, |(k, _)| *k) {
                    Ok(idx) => vec[idx].1 = new_prop.clone(),
                    Err(idx) => vec.insert(idx, (prop_type, new_prop.clone())),
                }
            }
        }

        // The compact cache is a precomputed per-node array that the layout
        // getters read on their FAST PATH (`get_display`, `get_width`, ...)
        // BEFORE consulting `user_overridden_properties`. An override that
        // changes geometry would therefore be written, reported as changed,
        // and then ignored by layout — which is why a runtime
        // `display: none -> flex` patch (combobox list, popover, ribbon
        // gallery panel) left the node at zero size and invisible.
        //
        // REBUILD the cache rather than merely dropping it. The builder's
        // per-node walk applies `user_overridden_properties` as its last
        // step, so the rebuilt cache reflects the patch — and every consumer
        // that treats the compact cache as the source of truth keeps
        // working. Leaving it `None` until "the next full cascade" was a
        // trap: the font phase derives its requirements (font-stack
        // signature, font chains, the GC keep-set) from this cache, so the
        // very relayout that applies the patch resolved an EMPTY font world
        // — the chain cache was replaced with nothing and the patched-in
        // subtree's text laid out at zero size (the gallery panel opened as
        // an 18px blank strip). Overrides are user-interaction-rate, so the
        // rebuild is not a per-frame cost; the animation channel
        // (colour/opacity/transform) keeps the fast path untouched.
        // INHERITED paint props need the recompute too: a `color` override on
        // a container is READ by its text children through the precomputed
        // inheritance tables, so skipping the recompute left descendants at
        // the stale colour — a colour transition on a DIV animated nothing
        // visible (found by the css_anim_perf_transition damage law). The
        // per-tick animation channel avoids this whole fn via
        // `set_user_property_override_fast` + display-list patching.
        if new_properties
            .iter()
            .any(|p| p.get_type().can_trigger_relayout() || p.get_type().is_inheritable())
        {
            self.recompute_inheritance_and_compact_cache();
            self.get_css_property_cache_mut()
                .invalidate_resolved_font_sizes();
        }

        if !changes.is_empty() {
            map.insert(*node_id, changes);
        }

        map
    }

    /// Provide (or update) the window's `DynamicSelectorContext` - viewport
    /// size, theme, OS, media type - for this DOM's cascade.
    ///
    /// Inline conditional properties (`CssPropertyWithConditions` with
    /// viewport/@media/theme/OS selectors) evaluate against this context in
    /// BOTH production readers: `get_property_slow` (per lookup) and the
    /// compact-cache builder (at build time). A freshly created `StyledDom`
    /// has NO context - non-pseudo conditions do not apply until a window
    /// adopts the DOM and calls this, which the layout funnel
    /// (`LayoutWindow::layout_and_generate_display_list`) does before every
    /// pass.
    ///
    /// When the context actually changed AND the compact cache says some
    /// node's resting style depends on it (`has_dynamic_conditions`), the
    /// compact cache is rebuilt and hit-test tags are regenerated (a
    /// condition can flip `display`, which decides which nodes carry tags).
    /// For the common condition-free DOM a context change costs one bool
    /// read.
    pub fn set_dynamic_selector_context(
        &mut self,
        context: azul_css::dynamic_selector::DynamicSelectorContext,
    ) {
        {
            let cache = self.get_css_property_cache_mut();
            let same = cache.dynamic_context.as_deref() == Some(&context);
            cascade_trace(|| format!("dynamic context offered, unchanged={same}"));
            if same {
                return;
            }
            cache.dynamic_context = Some(Box::new(context));
        }
        // Author-css @-rule conditions are baked at CASCADE time (restyle
        // drops non-matching rule blocks), so a context change must re-run
        // the author cascade — rebuilding the compact cache alone would
        // keep the stale rule selection. Only DOMs whose stylesheet
        // actually has conditional rules pay this. `env()` values are baked
        // the same way (resolved against the context's safe-area insets),
        // so a stylesheet using them counts as conditional too.
        let author_conditional = self
            .get_css_property_cache()
            .retained_author_css
            .rules
            .as_ref()
            .iter()
            .any(azul_css::css::CssRuleBlock::depends_on_dynamic_context);
        if author_conditional {
            self.restyle_retained();
        }
        let needs_rebuild = self
            .get_css_property_cache()
            .compact_cache
            .as_ref()
            .is_none_or(|cc| cc.has_dynamic_conditions);
        if needs_rebuild {
            self.recompute_inheritance_and_compact_cache();
            self.get_css_property_cache_mut()
                .invalidate_resolved_font_sizes();
            let new_tag_ids = self
                .css_property_cache
                .downcast_mut()
                .generate_tag_ids(&self.node_data.as_container(), &self.node_hierarchy);
            self.tag_ids_to_node_ids = new_tag_ids.into();
        }
    }

    /// The viewport-size thresholds (widths, heights, logical px) at which
    /// any conditional styling in this DOM can flip: the author
    /// stylesheet's `@media (min-/max-width/height)` bounds plus every
    /// inline conditional property's `ViewportWidth`/`ViewportHeight`
    /// bounds (harvested by the compact-cache builder). Sorted, deduped.
    ///
    /// `None` when the compact cache has not been built yet (no styling
    /// pass) - callers should treat that as "unknown" and fall back to a
    /// conservative policy. The engine's resize decision uses this instead
    /// of the old hardcoded `CSS_BREAKPOINTS` guess list, which failed both
    /// ways: a widget breakpoint like the ribbon's 720px was not on it (so
    /// shrinking onto the mobile layout never regenerated), and its eight
    /// guessed thresholds fired ~66ms full regenerations on every drag
    /// across 640/768/1024/...
    #[must_use]
    pub fn viewport_breakpoints(&self) -> Option<(Vec<f32>, Vec<f32>)> {
        let cache = self.get_css_property_cache();
        let cc = cache.compact_cache.as_ref()?;
        let (mut w, mut h) = cache.retained_author_css.viewport_breakpoints();
        w.extend(cc.inline_viewport_w.iter().copied().map(f32::from_bits));
        h.extend(cc.inline_viewport_h.iter().copied().map(f32::from_bits));
        w.sort_by_key(|v| v.to_bits());
        w.dedup_by_key(|v| v.to_bits());
        h.sort_by_key(|v| v.to_bits());
        h.dedup_by_key(|v| v.to_bits());
        Some((w, h))
    }

    /// Migrate runtime CSS overrides (`user_overridden_properties`) from a
    /// previous generation's property cache onto this DOM, following the
    /// reconciliation node matches.
    ///
    /// State follows node identity across a `RefreshDom` rebuild - exactly
    /// like datasets (`diff::transfer_states`), scroll offsets and text
    /// cursors already do. Without this, every runtime patch
    /// (`set_css_property`) silently reverted on the next app-driven DOM
    /// rebuild: the ribbon's collapsed band and an open combobox/gallery
    /// panel "un-toggled" whenever any callback returned `RefreshDom` (the
    /// ribbon's own tab-click does), because the fresh cascade knows nothing
    /// of the old override layer.
    ///
    /// Rebuilds the compact cache when anything migrated, so the layout fast
    /// path sees the carried-over values immediately.
    pub fn migrate_user_overrides_from(
        &mut self,
        old_cache: &CssPropertyCache,
        node_moves: &[crate::diff::NodeMove],
    ) {
        let node_count = self.node_data.as_ref().len();
        let mut migrated_any = false;
        for m in node_moves {
            let Some(old_vec) = old_cache
                .user_overridden_properties
                .get(m.old_node_id.index())
                .filter(|v| !v.is_empty())
            else {
                continue;
            };
            let new_idx = m.new_node_id.index();
            if new_idx >= node_count {
                continue;
            }
            let old_vec = old_vec.clone();
            let cache = self.get_css_property_cache_mut();
            if cache.user_overridden_properties.len() < node_count {
                cache
                    .user_overridden_properties
                    .resize(node_count, Vec::new());
            }
            cache.user_overridden_properties[new_idx] = old_vec;
            migrated_any = true;
        }
        if migrated_any {
            self.recompute_inheritance_and_compact_cache();
            self.get_css_property_cache_mut()
                .invalidate_resolved_font_sizes();
        }
    }

    /// Reconstruct a plain [`Dom`](crate::dom::Dom) from a subtree of this
    /// styled DOM by cloning each node's [`NodeData`](crate::dom::NodeData)
    /// (ids/classes, inline CSS, callbacks, dataset - `RefAny`/`ImageRef`
    /// fields are refcounted handles, so nothing heavy is copied).
    ///
    /// `root`: the subtree root, or `None` for the DOM's root node.
    ///
    /// The returned `Dom` CARRIES THE STYLESHEETS: the cascade retains the
    /// author CSS (`CssPropertyCache::retained_author_css`), and it is
    /// re-attached to the returned root's `css` field - re-styling the
    /// reconstruction reproduces the on-screen cascade. For a NON-root
    /// subtree this is an approximation: selectors that depended on
    /// ancestors OUTSIDE the subtree (descendant combinators through cut-off
    /// parents, `:nth-child` against removed siblings) may match differently
    /// in the new document. When exact pixel parity matters, hand the whole
    /// `StyledDom` clone to the consumer instead (e.g.
    /// `Pdf::from_styled_dom_with_resources`), which skips re-cascading
    /// entirely.
    #[must_use]
    pub fn reconstruct_dom_subtree(&self, root: Option<NodeId>) -> Dom {
        use crate::dom::NodeData;

        let hierarchy = self.node_hierarchy.as_container();
        let node_data = self.node_data.as_container();
        let root_id = root.unwrap_or(NodeId::ZERO);

        let make_dom = |id: NodeId| -> Dom {
            Dom {
                root: node_data
                    .get(id)
                    .cloned()
                    .unwrap_or_else(NodeData::create_div),
                children: Vec::new().into(),
                css: Vec::new().into(),
                estimated_total_children: 0,
            }
        };

        // Iterative post-order: a node is folded into its parent via
        // `add_child` (which maintains `estimated_total_children`) once all
        // of its own children are assembled, so arbitrary depth cannot
        // overflow the stack.
        let mut result_stack: Vec<Dom> = vec![make_dom(root_id)];
        let mut visit_stack: Vec<(NodeId, Option<NodeId>)> = vec![(
            root_id,
            hierarchy
                .get(root_id)
                .and_then(|n| n.first_child_id(root_id)),
        )];

        while let Some((node, next_child)) = visit_stack.pop() {
            if let Some(child) = next_child {
                // Come back to `node` for the sibling AFTER `child`,
                // then descend into `child`.
                let sibling = hierarchy
                    .get(child)
                    .and_then(NodeHierarchyItem::next_sibling_id);
                visit_stack.push((node, sibling));
                result_stack.push(make_dom(child));
                visit_stack.push((
                    child,
                    hierarchy.get(child).and_then(|c| c.first_child_id(child)),
                ));
            } else {
                let Some(finished) = result_stack.pop() else {
                    break;
                };
                if let Some(parent) = result_stack.last_mut() {
                    parent.add_child(finished);
                } else {
                    let mut finished = finished;
                    let author_css = self.get_css_property_cache().retained_author_css.clone();
                    if !author_css.is_empty() {
                        finished.css = vec![author_css].into();
                    }
                    return finished;
                }
            }
        }

        // Unreachable for a well-formed hierarchy; degrade to an empty div.
        Dom::create_div()
    }

    /// Returns a HTML-formatted version of the DOM for easier debugging.
    ///
    /// For example, a DOM with a parent div containing a child div would return:
    ///
    /// ```xml,no_run,ignore
    /// <div id="hello">
    ///      <div id="test" />
    /// </div>
    /// ```
    #[must_use]
    pub fn get_html_string(&self, custom_head: &str, custom_body: &str, test_mode: bool) -> String {
        let css_property_cache = self.get_css_property_cache();

        let mut output = String::new();

        // After which nodes should a close tag be printed?
        let mut should_print_close_tag_after_node: BTreeMap<NodeId, Vec<(NodeId, usize)>> =
            BTreeMap::new();

        let should_print_close_tag_debug = self
            .non_leaf_nodes
            .iter()
            .filter_map(|p| {
                let parent_node_id = p.node_id.into_crate_internal()?;
                let mut total_last_child = None;
                recursive_get_last_child(
                    parent_node_id,
                    self.node_hierarchy.as_ref(),
                    &mut total_last_child,
                );
                let total_last_child = total_last_child?;
                Some((parent_node_id, (total_last_child, p.depth)))
            })
            .collect::<BTreeMap<_, _>>();

        for (parent_id, (last_child, parent_depth)) in should_print_close_tag_debug {
            should_print_close_tag_after_node
                .entry(last_child)
                .or_default()
                .push((parent_id, parent_depth));
        }

        let mut all_node_depths = self
            .non_leaf_nodes
            .iter()
            .filter_map(|p| {
                let parent_node_id = p.node_id.into_crate_internal()?;
                Some((parent_node_id, p.depth))
            })
            .collect::<BTreeMap<_, _>>();

        for (parent_node_id, parent_depth) in self
            .non_leaf_nodes
            .iter()
            .filter_map(|p| Some((p.node_id.into_crate_internal()?, p.depth)))
        {
            for child_id in parent_node_id.az_children(&self.node_hierarchy.as_container()) {
                all_node_depths.insert(child_id, parent_depth + 1);
            }
        }

        for node_id in self.node_hierarchy.as_container().linear_iter() {
            // A single-node DOM (or any node not reached as a non-leaf parent or
            // one of their children, e.g. a lone root) has no entry here; treat
            // its depth as 0 instead of panic-indexing the map.
            let depth = all_node_depths.get(&node_id).copied().unwrap_or(0);

            let node_data = &self.node_data.as_container()[node_id];
            let node_state = &self.styled_nodes.as_container()[node_id].styled_node_state;
            let tabs = String::from("    ").repeat(depth);

            output.push_str("\r\n");
            output.push_str(&tabs);
            output.push_str(&node_data.debug_print_start(css_property_cache, &node_id, node_state));

            if let Some(content) = node_data.get_node_type().format().as_ref() {
                output.push_str(content);
            }

            let node_has_children = self.node_hierarchy.as_container()[node_id]
                .first_child_id(node_id)
                .is_some();
            if !node_has_children {
                let node_data = &self.node_data.as_container()[node_id];
                output.push_str(&node_data.debug_print_end());
            }

            if let Some(close_tag_vec) = should_print_close_tag_after_node.get(&node_id) {
                let mut close_tag_vec = close_tag_vec.clone();
                close_tag_vec.sort_by(|a, b| b.1.cmp(&a.1)); // sort by depth descending
                for (close_tag_parent_id, close_tag_depth) in close_tag_vec {
                    let node_data = &self.node_data.as_container()[close_tag_parent_id];
                    let tabs = String::from("    ").repeat(close_tag_depth);
                    output.push_str("\r\n");
                    output.push_str(&tabs);
                    output.push_str(&node_data.debug_print_end());
                }
            }
        }

        if test_mode {
            output
        } else {
            format!(
                "
                <html>
                    <head>
                    <style>* {{ margin:0px; padding:0px; }}</style>
                    {custom_head}
                    </head>
                {output}
                {custom_body}
                </html>
            "
            )
        }
    }

    /// Returns nodes grouped by their rendering order (respects z-index and position).
    #[must_use]
    pub fn get_rects_in_rendering_order(&self) -> ContentGroup {
        Self::determine_rendering_order(
            self.non_leaf_nodes.as_ref(),
            &self.node_hierarchy.as_container(),
            &self.styled_nodes.as_container(),
            &self.node_data.as_container(),
            self.get_css_property_cache(),
        )
    }

    /// Returns the rendering order of the items (the rendering
    /// order doesn't have to be the original order)
    fn determine_rendering_order(
        non_leaf_nodes: &[ParentWithNodeDepth],
        node_hierarchy: &NodeDataContainerRef<'_, NodeHierarchyItem>,
        styled_nodes: &NodeDataContainerRef<'_, StyledNode>,
        node_data_container: &NodeDataContainerRef<'_, NodeData>,
        css_property_cache: &CssPropertyCache,
    ) -> ContentGroup {
        let children_sorted = non_leaf_nodes
            .iter()
            .filter_map(|parent| {
                Some((
                    parent.node_id,
                    sort_children_by_position(
                        parent.node_id.into_crate_internal()?,
                        node_hierarchy,
                        styled_nodes,
                        node_data_container,
                        css_property_cache,
                    ),
                ))
            })
            .collect::<Vec<_>>();

        let children_sorted: BTreeMap<NodeHierarchyItemId, Vec<NodeHierarchyItemId>> =
            children_sorted.into_iter().collect();

        let mut root_content_group = ContentGroup {
            root: NodeHierarchyItemId::from_crate_internal(Some(NodeId::ZERO)),
            children: Vec::new().into(),
        };

        fill_content_group_children(&mut root_content_group, &children_sorted);

        root_content_group
    }

    /// Replaces this `StyledDom` with default and returns the old value.
    #[must_use]
    pub fn swap_with_default(&mut self) -> Self {
        let mut new = Self::default();
        core::mem::swap(self, &mut new);
        new
    }
}

/// Same as `Dom`, but arena-based for more efficient memory layout and faster traversal.
#[derive(Debug, PartialEq, PartialOrd, Eq)]
pub struct CompactDom {
    /// The arena containing the hierarchical relationships (parent, child, sibling) of all nodes.
    pub node_hierarchy: NodeHierarchy,
    /// The arena containing the actual data (`NodeData`) for each node.
    pub node_data: NodeDataContainer<NodeData>,
    /// The ID of the root node of the DOM tree.
    pub root: NodeId,
}

impl CompactDom {
    /// Returns the number of nodes in this DOM.
    #[inline]
    #[must_use]
    pub fn len(&self) -> usize {
        self.node_hierarchy.as_ref().len()
    }

    /// Returns `true` if this DOM has no nodes.
    #[inline]
    #[must_use]
    pub fn is_empty(&self) -> bool {
        self.node_hierarchy.as_ref().is_empty()
    }
}

impl From<Dom> for CompactDom {
    fn from(dom: Dom) -> Self {
        convert_dom_into_compact_dom(dom)
    }
}

/// Converts a tree-based Dom into an arena-based `CompactDom` for efficient traversal.
#[must_use]
pub fn convert_dom_into_compact_dom(mut dom: Dom) -> CompactDom {
    // note: somehow convert this into a non-recursive form later on!
    fn convert_dom_into_compact_dom_internal(
        dom: &mut Dom,
        node_hierarchy: &mut [Node],
        node_data: &mut Vec<NodeData>,
        parent_node_id: NodeId,
        node: Node,
        cur_node_id: &mut usize,
    ) {
        // - parent [0]
        //    - child [1]
        //    - child [2]
        //        - child of child 2 [2]
        //        - child of child 2 [4]
        //    - child [5]
        //    - child [6]
        //        - child of child 4 [7]

        // Write node into the arena here!
        node_hierarchy[parent_node_id.index()] = node;

        // MOVE the node's inline `style` AND its `extra` (NodeDataExt) box instead of relying on
        // copy_special's `self.style.clone()` / `self.extra.clone()`. Both derived Clones lower to
        // indirect-jump jump tables that remill mis-lifts on the web backend: CssProperty's clone
        // comes back with discriminant 0 (drops simple inline CSS) and for COMPLEX values (AzButton's
        // gradient; the NodeDataExt attributes Vec) the mis-lifted clone reads/writes wrong-sized data,
        // which clobbers the adjacent `style` temporary → "memory access out of bounds" later in the
        // cascade (StyledDom::create → restyle's inheritance loop reads the corrupted style). 2026-06-02:
        // copy_special_moving_complex mem::takes BOTH style+extra before copy_special, so copy_special
        // clones an EMPTY style + None extra (no broken clone runs) and restores them after. (Extra was
        // added after the AzButton ids/classes node — which lazily allocates NodeDataExt — OOB'd even
        // with the style-only take.) The Dom is consumed here, so the move is correct.
        let copy = dom.root.copy_special_moving_complex();

        node_data[parent_node_id.index()] = copy;

        *cur_node_id += 1;

        let mut previous_sibling_id = None;
        let children_len = dom.children.len();
        for (child_index, child_dom) in dom.children.as_mut().iter_mut().enumerate() {
            let child_node_id = NodeId::new(*cur_node_id);
            let is_last_child = (child_index + 1) == children_len;
            let child_dom_is_empty = child_dom.children.is_empty();
            let child_node = Node {
                parent: Some(parent_node_id),
                previous_sibling: previous_sibling_id,
                next_sibling: if is_last_child {
                    None
                } else {
                    Some(child_node_id + child_dom.estimated_total_children + 1)
                },
                last_child: if child_dom_is_empty {
                    None
                } else {
                    Some(child_node_id + child_dom.estimated_total_children)
                },
            };
            previous_sibling_id = Some(child_node_id);
            // recurse BEFORE adding the next child
            convert_dom_into_compact_dom_internal(
                child_dom,
                node_hierarchy,
                node_data,
                child_node_id,
                child_node,
                cur_node_id,
            );
        }

        // AUTHORITATIVE last_child. The per-child `last_child` set at construction used
        // `child_node_id + estimated_total_children`, which is the last node of the
        // whole SUBTREE (its deepest descendant), NOT the last DIRECT child — wrong
        // whenever that last child has children of its own. It corrupted `last_child_id()`
        // and, through it, append_child (which spliced onto the wrong node). The loop
        // above already tracked `previous_sibling_id`, which now holds the real last
        // direct child (None if there were none), so overwrite with it. This runs for
        // every node including the root, so it also corrects the root's own computation.
        node_hierarchy[parent_node_id.index()].last_child = previous_sibling_id;
    }

    // Pre-allocate all nodes (+ 1 root node)
    let sum_nodes = dom.fixup_children_estimated();

    let mut node_hierarchy = vec![Node::ROOT; sum_nodes + 1];
    let mut node_data = vec![NodeData::create_div(); sum_nodes + 1];
    let mut cur_node_id = 0;

    let root_node_id = NodeId::ZERO;
    let root_node = Node {
        parent: None,
        previous_sibling: None,
        next_sibling: None,
        last_child: if dom.children.is_empty() {
            None
        } else {
            Some(root_node_id + dom.estimated_total_children)
        },
    };

    convert_dom_into_compact_dom_internal(
        &mut dom,
        &mut node_hierarchy,
        &mut node_data,
        root_node_id,
        root_node,
        &mut cur_node_id,
    );

    CompactDom {
        node_hierarchy: NodeHierarchy {
            internal: node_hierarchy,
        },
        node_data: NodeDataContainer {
            internal: node_data,
        },
        root: root_node_id,
    }
}

/// #47: scope every node's inline css to its own subtree. Walks the tree in the
/// SAME pre-order `convert_dom_into_compact_dom` uses to assign flat `NodeIds`, so the
/// `[flat_id, flat_id + estimated_total_children]` range pushed onto each rule (via
/// `CssPath::push_front_scope`) matches the ids the cascade will later see. After
/// this, a node's `with_css`/`set_css` rules can only match nodes inside its subtree;
/// they can no longer leak to the whole tree. `fixup_children_estimated()` must
/// have run first so `estimated_total_children` is populated/exact.
fn scope_inline_css(dom: &mut Dom, next_id: &mut usize) {
    let start = *next_id;
    let end = start + dom.estimated_total_children;
    for css in dom.css.as_mut().iter_mut() {
        for rule in css.rules.as_mut().iter_mut() {
            // Bare-decl wrappers (INLINE priority, from set_css/with_css
            // selector-less declarations) are scoped node-only so a non-root
            // background can't leak to descendants (#47). A stylesheet's
            // `* { ... }` (AUTHOR/UA priority) scopes to the SUBTREE - the
            // classic `* { margin: 0 }` reset must reach every element of the
            // mounted document, not just the mount root.
            let node_only = rule.priority >= azul_css::css::rule_priority::INLINE;
            rule.path.push_front_scope_for(start, end, node_only);
        }
    }
    *next_id += 1;
    for child in dom.children.as_mut().iter_mut() {
        scope_inline_css(child, next_id);
    }
}

/// Recursively collect all CSS objects from a Dom tree (depth-first).
/// Inner (deeper) CSS objects come first, outer (shallower) CSS objects come last.
/// This means outer CSS has higher cascade priority when applied in order.
fn collect_css_from_dom(dom: &Dom, out: &mut Vec<Css>) {
    // First, recurse into children (inner CSS = lower priority)
    for child in &dom.children {
        collect_css_from_dom(child, out);
    }
    // Then, add this node's CSS objects (outer CSS = higher priority)
    for css in &dom.css {
        out.push(css.clone());
    }
}

/// Recursively strip CSS from all Dom nodes (sets css to empty vec).
/// Called after collecting CSS so the `CompactDom` doesn't carry CSS data.
fn strip_css_from_dom(dom: &mut Dom) {
    dom.css = Vec::new().into();
    for child in dom.children.as_mut().iter_mut() {
        strip_css_from_dom(child);
    }
}

fn fill_content_group_children(
    group: &mut ContentGroup,
    children_sorted: &BTreeMap<NodeHierarchyItemId, Vec<NodeHierarchyItemId>>,
) {
    if let Some(c) = children_sorted.get(&group.root) {
        // returns None for leaf nodes
        group.children = c
            .iter()
            .map(|child| ContentGroup {
                root: *child,
                children: Vec::new().into(),
            })
            .collect::<Vec<ContentGroup>>()
            .into();

        for c in group.children.as_mut() {
            fill_content_group_children(c, children_sorted);
        }
    }
}

fn sort_children_by_position(
    parent: NodeId,
    node_hierarchy: &NodeDataContainerRef<'_, NodeHierarchyItem>,
    rectangles: &NodeDataContainerRef<'_, StyledNode>,
    node_data_container: &NodeDataContainerRef<'_, NodeData>,
    css_property_cache: &CssPropertyCache,
) -> Vec<NodeHierarchyItemId> {
    use azul_css::props::layout::LayoutPosition::Absolute;

    let children_positions = parent
        .az_children(node_hierarchy)
        .map(|nid| {
            let position = css_property_cache
                .get_position(
                    &node_data_container[nid],
                    &nid,
                    &rectangles[nid].styled_node_state,
                )
                .and_then(|p| (*p).get_property_or_default())
                .unwrap_or_default();
            let id = NodeHierarchyItemId::from_crate_internal(Some(nid));
            (id, position)
        })
        .collect::<Vec<_>>();

    let mut not_absolute_children = children_positions
        .iter()
        .filter_map(|(node_id, position)| {
            if *position == Absolute {
                None
            } else {
                Some(*node_id)
            }
        })
        .collect::<Vec<_>>();

    let mut absolute_children = children_positions
        .iter()
        .filter_map(|(node_id, position)| {
            if *position == Absolute {
                Some(*node_id)
            } else {
                None
            }
        })
        .collect::<Vec<_>>();

    // Append the position:absolute children after the regular children
    not_absolute_children.append(&mut absolute_children);
    not_absolute_children
}

// calls get_last_child() recursively until the last child of the last child of the ... has been
// found
fn recursive_get_last_child(
    node_id: NodeId,
    node_hierarchy: &[NodeHierarchyItem],
    target: &mut Option<NodeId>,
) {
    match node_hierarchy[node_id.index()].last_child_id() {
        None => (),
        Some(s) => {
            *target = Some(s);
            recursive_get_last_child(s, node_hierarchy, target);
        }
    }
}

// ============================================================================
// DOM TRAVERSAL FOR MULTI-NODE SELECTION
// ============================================================================

/// Determine if `node_a` comes before `node_b` in document order.
///
/// Document order is defined as pre-order depth-first traversal order.
/// This is equivalent to the order nodes appear in HTML source.
///
/// ## Algorithm
/// 1. Find the path from root to each node
/// 2. Find the Lowest Common Ancestor (LCA)
/// 3. At the divergence point, the child that appears first in sibling order comes first
#[must_use]
pub fn is_before_in_document_order(
    hierarchy: &NodeHierarchyItemVec,
    node_a: NodeId,
    node_b: NodeId,
) -> bool {
    if node_a == node_b {
        return false;
    }

    let hierarchy = hierarchy.as_container();

    // Get paths from root to each node (stored as root-first order)
    let path_a = get_path_to_root(&hierarchy, node_a);
    let path_b = get_path_to_root(&hierarchy, node_b);

    // Find divergence point (last common ancestor)
    let min_len = path_a.len().min(path_b.len());

    for i in 0..min_len {
        if path_a[i] != path_b[i] {
            // Found divergence - check which sibling comes first
            let child_towards_a = path_a[i];
            let child_towards_b = path_b[i];

            // A smaller NodeId index means it was created earlier in DOM construction,
            // which means it comes first in document order for siblings
            return child_towards_a.index() < child_towards_b.index();
        }
    }

    // One path is a prefix of the other - the shorter path (ancestor) comes first
    path_a.len() < path_b.len()
}

/// Get the path from root to a node, returned in root-first order.
fn get_path_to_root(
    hierarchy: &NodeDataContainerRef<'_, NodeHierarchyItem>,
    node: NodeId,
) -> Vec<NodeId> {
    let mut path = Vec::new();
    let mut current = Some(node);

    while let Some(node_id) = current {
        path.push(node_id);
        current = hierarchy
            .get(node_id)
            .and_then(NodeHierarchyItem::parent_id);
    }

    // Reverse to get root-first order
    path.reverse();
    path
}

/// Collect all nodes between start and end (inclusive) in document order.
///
/// This performs a pre-order depth-first traversal starting from the root,
/// collecting nodes once we've seen `start` and stopping at `end`.
///
/// ## Parameters
/// * `hierarchy` - The node hierarchy
/// * `start_node` - First node in document order
/// * `end_node` - Last node in document order
///
/// ## Returns
/// Vector of `NodeIds` in document order, from start to end (inclusive)
#[must_use]
pub fn collect_nodes_in_document_order(
    hierarchy: &NodeHierarchyItemVec,
    start_node: NodeId,
    end_node: NodeId,
) -> Vec<NodeId> {
    if start_node == end_node {
        return vec![start_node];
    }

    let hierarchy_container = hierarchy.as_container();
    let hierarchy_slice = hierarchy.as_ref();

    let mut result = Vec::new();
    let mut in_range = false;

    // Pre-order DFS using a stack
    // We need to traverse in document order, which is pre-order DFS
    let mut stack: Vec<NodeId> = vec![NodeId::ZERO]; // Start from root

    while let Some(current) = stack.pop() {
        // Check if we've entered the range
        if current == start_node {
            in_range = true;
        }

        // Collect if in range
        if in_range {
            result.push(current);
        }

        // Check if we've exited the range
        if current == end_node {
            break;
        }

        // Push children in reverse order so they pop in correct order
        // (first child should be processed first)
        if let Some(item) = hierarchy_container.get(current) {
            // Get first child
            if let Some(first_child) = item.first_child_id(current) {
                // Collect all children by following next_sibling
                let mut children = Vec::new();
                let mut child = Some(first_child);
                while let Some(child_id) = child {
                    children.push(child_id);
                    child = hierarchy_container
                        .get(child_id)
                        .and_then(NodeHierarchyItem::next_sibling_id);
                }
                // Push in reverse order for correct DFS order
                for child_id in children.into_iter().rev() {
                    stack.push(child_id);
                }
            }
        }
    }

    result
}

/// Check if two `StyledDom`s are structurally equivalent for layout purposes.
///
/// Returns `true` if the DOMs have the same structure, node types, classes,
/// IDs, inline styles, and callback event registrations - meaning the
/// layout output would be identical.
///
/// Image callback nodes are compared by function pointer and `RefAny` type ID
/// rather than heap pointer, since each `layout()` call creates new `ImageRef`
/// allocations even when the callback is the same.
///
/// This is used to short-circuit the expensive layout pipeline when the DOM
/// hasn't actually changed (e.g., an animation timer fires but only the GL
/// texture content changed, not the DOM structure).
#[must_use]
pub fn is_layout_equivalent(old: &StyledDom, new: &StyledDom) -> bool {
    use crate::dom::NodeType;
    use crate::resources::DecodedImage;

    // Quick check: node count must match
    let old_nodes = old.node_data.as_ref();
    let new_nodes = new.node_data.as_ref();
    if old_nodes.len() != new_nodes.len() {
        return false;
    }

    // Check hierarchy (parent/child/sibling structure)
    let old_hier = old.node_hierarchy.as_ref();
    let new_hier = new.node_hierarchy.as_ref();
    if old_hier.len() != new_hier.len() {
        return false;
    }
    if old_hier != new_hier {
        return false;
    }

    // Per-node comparison
    for (old_node, new_node) in old_nodes.iter().zip(new_nodes.iter()) {
        // Compare node type discriminant
        if core::mem::discriminant(&old_node.node_type)
            != core::mem::discriminant(&new_node.node_type)
        {
            return false;
        }

        // Compare node type content (with special handling for image callbacks)
        match (&old_node.node_type, &new_node.node_type) {
            (NodeType::Image(old_img), NodeType::Image(new_img)) => {
                match (old_img.get_data(), new_img.get_data()) {
                    (DecodedImage::Callback(old_cb), DecodedImage::Callback(new_cb)) => {
                        // Compare callback function pointer (stable across frames)
                        if old_cb.callback.cb != new_cb.callback.cb {
                            return false;
                        }
                        // Compare RefAny type ID (not instance pointer)
                        if old_cb.refany.get_type_id() != new_cb.refany.get_type_id() {
                            return false;
                        }
                    }
                    _ => {
                        // Raw images / GL textures: compare by pointer identity
                        if old_img != new_img {
                            return false;
                        }
                    }
                }
            }
            _ => {
                if old_node.node_type != new_node.node_type {
                    return false;
                }
            }
        }

        // Compare IDs and classes (now stored in attributes as AttributeType::Id/Class)
        {
            use crate::dom::AttributeType;
            let old_ids_classes: Vec<_> = old_node
                .attributes()
                .as_ref()
                .iter()
                .filter(|a| matches!(a, AttributeType::Id(_) | AttributeType::Class(_)))
                .collect();
            let new_ids_classes: Vec<_> = new_node
                .attributes()
                .as_ref()
                .iter()
                .filter(|a| matches!(a, AttributeType::Id(_) | AttributeType::Class(_)))
                .collect();
            if old_ids_classes != new_ids_classes {
                return false;
            }
        }

        // Compare inline CSS (direct layout input)
        if old_node.style != new_node.style {
            return false;
        }

        // Compare callback event types (affects hit-test tags)
        // We compare only event types, not function pointers or data
        let old_cbs = old_node.callbacks.as_ref();
        let new_cbs = new_node.callbacks.as_ref();
        if old_cbs.len() != new_cbs.len() {
            return false;
        }
        for (old_cb, new_cb) in old_cbs.iter().zip(new_cbs.iter()) {
            if old_cb.event != new_cb.event {
                return false;
            }
        }

        // Compare attributes (some affect layout, e.g. colspan)
        if old_node.attributes().as_ref() != new_node.attributes().as_ref() {
            return false;
        }
    }

    // Compare styled node states (hover/focus/active flags affect CSS resolution)
    let old_styled = old.styled_nodes.as_ref();
    let new_styled = new.styled_nodes.as_ref();
    if old_styled.len() != new_styled.len() {
        return false;
    }
    if old_styled != new_styled {
        return false;
    }

    true
}

#[cfg(test)]
#[path = "styled_dom_test.rs"]
mod styled_dom_test;