//! DOM tree to CSS style tree cascading.

//!

//! Implements CSS selector matching (`matches_html_element`) and cascade-info

//! construction (`construct_html_cascade_tree`). Used by `styled_dom` and

//! `prop_cache` to resolve which CSS rules apply to each DOM node.

use alloc::vec::Vec;

use azul_css::css::{

    AttributeMatchOp, CssAttributeSelector, CssContentGroup, CssNthChildSelector,

    CssNthChildSelector::{Number, Even, Odd, Pattern}, CssPath, CssPathPseudoSelector, CssPathSelector,

};

use crate::{

    dom::NodeData,

    id::{NodeDataContainer, NodeDataContainerRef, NodeHierarchyRef, NodeId},

    styled_dom::NodeHierarchyItem,

};

/// Has all the necessary information about the style CSS path

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

#[repr(C)]

pub struct CascadeInfo {

    pub index_in_parent: u32,

    pub is_last_child: bool,

}

impl_option!(

    CascadeInfo,

    OptionCascadeInfo,

    [Debug, Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash]

);

impl_vec!(CascadeInfo, CascadeInfoVec, CascadeInfoVecDestructor, CascadeInfoVecDestructorType, CascadeInfoVecSlice, OptionCascadeInfo);

impl_vec_mut!(CascadeInfo, CascadeInfoVec);

impl_vec_debug!(CascadeInfo, CascadeInfoVec);

impl_vec_partialord!(CascadeInfo, CascadeInfoVec);

impl_vec_clone!(CascadeInfo, CascadeInfoVec, CascadeInfoVecDestructor);

impl_vec_partialeq!(CascadeInfo, CascadeInfoVec);

impl CascadeInfoVec {

}

/// Returns if the style CSS path matches the DOM node (i.e. if the DOM node should be styled by

/// that element)

#[allow(clippy::needless_pass_by_value)] // owned azul value taken by value (public API / ownership-transfer convention)

    use self::CssGroupSplitReason::{DirectChildren, Children, AdjacentSibling, GeneralSibling};

    // Skip anonymous nodes - they are not part of the original DOM tree

    // and should not participate in CSS selector matching

    // Collect all selector groups (processed right-to-left from the CSS path).

    // The rightmost group must match the target node directly.

    // groups[0] is ALWAYS the subject (rightmost) group, so it is the "last content

    // group" that an interactive pseudo (:hover/:focus/:active) attaches to — regardless

    // of how many ancestor groups precede it. The old `groups.len() == 1` disabled

    // :hover on the subject of every multi-group selector (e.g. `body > div:hover`).

    // Navigate from the target node upward/sideways through the DOM,

    // matching each remaining selector group with its combinator.

        // The combinator comes from the PREVIOUS group's reason

            DirectChildren => {

                // Parent must match directly (child combinator `>`)

                }

            }

            Children => {

                // Search up ancestor chain for a match (descendant combinator ` `)

                    ) {

                }

            }

            AdjacentSibling => {

                // Immediate previous sibling must match (adjacent sibling `+`)

                }

            }

            GeneralSibling => {

                // Search previous siblings for a match (general sibling `~`)

                    ) {

                }

            }

        }

    }

/// Find the first non-anonymous parent of a node.

    }

/// Find the first previous sibling of a node that the `+`/`~` combinators can target:

/// an element, skipping anonymous boxes AND non-element (text) nodes.

///

/// CSS sibling combinators operate on ELEMENTS (Selectors L4 §15.2), so an intervening

/// text node must not block `.a + .b` from reaching the preceding element. Skipping only

/// anonymous boxes left text siblings in the way.

    }

/// A CSS group is a group of css selectors in a path that specify the rule that a

/// certain node has to match, i.e. "div.main.foo" has to match three requirements:

///

/// - the node has to be of type div

/// - the node has to have the class "main"

/// - the node has to have the class "foo"

///

/// If any of these requirements are not met, the CSS block is discarded.

///

/// The `CssGroupIterator` splits the CSS path into semantic blocks, i.e.:

///

/// `"body > .foo.main > #baz"` will be split into `["body", ".foo.main", "#baz"]`

#[derive(Debug)]

pub struct CssGroupIterator<'a> {

    pub css_path: &'a [CssPathSelector],

    current_idx: usize,

    last_reason: CssGroupSplitReason,

}

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

pub enum CssGroupSplitReason {

    /// ".foo .main" - match any children

    Children,

    /// ".foo > .main" - match only direct children

    DirectChildren,

    /// ".foo + .main" - match adjacent sibling (immediately preceding)

    AdjacentSibling,

    /// ".foo ~ .main" - match general sibling (any preceding sibling)

    GeneralSibling,

}

impl<'a> CssGroupIterator<'a> {

}

impl<'a> Iterator for CssGroupIterator<'a> {

    type Item = (CssContentGroup<'a>, CssGroupSplitReason);

        use self::CssPathSelector::{Children, DirectChildren, AdjacentSibling, GeneralSibling};

                Children => {

                }

                DirectChildren => {

                }

                AdjacentSibling => {

                }

                GeneralSibling => {

                }

            }

        }

        // NOTE: Order inside of a ContentGroup is not important

        // for matching elements, only important for testing

        #[cfg(test)]

            } else {

                // Last element of path

            }

        } else {

            // skip the "Children | DirectChildren" element itself

        }

}

            index_in_parent: 0,

            is_last_child: false,

        // Per CSS Selectors Level 4 §13: "Standalone text and other non-element

        // nodes are not counted when calculating the position of an element in

        // the list of children of its parent."

        //

        // We count only element siblings when computing index_in_parent.

            // Necessary for :last selectors — find last element sibling

            is_last_child: {

                }

            },

        };

        // Count only element children for index_in_parent

            // Find whether this is the last element child (skip trailing text nodes)

            } else {

                }

            };

        }

    }

/// Checks whether the last selector in `path` matches the given pseudo-selector `target`.

///

/// Known limitation: this only inspects the final selector in the path, so compound

/// selectors like `div:hover:first-child` may not be filtered correctly when `target`

/// is `None` — only the very last pseudo-selector is tested.

#[inline]

    // Helper to check if a pseudo-selector is "interactive" (requires user interaction state)

    // vs "structural" (based on DOM structure only)

            CssPathPseudoSelector::Hover

                | CssPathPseudoSelector::Active

                | CssPathPseudoSelector::Focus

                | CssPathPseudoSelector::Backdrop

                | CssPathPseudoSelector::Dragging

                | CssPathPseudoSelector::DragOver

        )

    };

            // Only reject interactive pseudo-selectors (hover, active, focus).

            // Structural pseudo-selectors (nth-child, first, last) should be allowed.

    )

/// Matches a single group of CSS selectors against a DOM node.

///

/// Returns true if all selectors in the group match the given node.

/// Combinator selectors (>, +, ~, space) should not appear in the group.

    // Inline-style detection for the `Global` arm: a bare-declaration

    // `with_css` rule is scoped to EXACTLY its owner node when the scope is

    // pushed (`push_front_scope_for` collapses the range to `[owner, owner]`

    // for INLINE-priority bare `*` wrappers). Such a rule is the author

    // addressing THIS node directly — it must style a text node too.

        )

/// Matches a single CSS selector against a DOM node.

    use self::CssPathSelector::{Global, Root, Type, Class, Id, PseudoSelector, Attribute, DirectChildren, Children, AdjacentSibling, GeneralSibling};

        // Per CSS, `*` matches ELEMENTS - never text nodes: letting a

        // stylesheet's universal selector hit text nodes made

        // `* { color: #666 }` overwrite the color a text child had just

        // inherited from its `p { color: red }` parent. The one exception is

        // a rule scoped to EXACTLY this node (`node_scoped_to_self`) — that

        // is a bare-declaration `with_css` ON the text node itself, i.e.

        // inline-style semantics: `create_text_do_not_use_without_block_level_wrapper("x").with_css("color: white")`

        // must apply. Subtree-scoped and unscoped `*` rules keep refusing

        // text nodes.

        // `Root(range)` (scope marker, #47): matches any node WITHIN the subtree

        // range `[start, end]`. The range is chosen when the scope is pushed

        // (`CssPath::push_front_scope`):

        //  - a bare-decl `with_css` rule (`* { … }`) is scoped node-only (`[start,

        //    start]`) → inline-style semantics: it applies to the OWNER only, so a

        //    non-root `background` can't leak to descendants/siblings (#47 leak fix).

        //  - a component rule with a real selector (`.menu-item`, from

        //    `add_component_css`) is scoped to the whole subtree (`[start, end]`) so

        //    its selector matches descendants of the owner (a menu container styling

        //    its `.menu-item` children). Compounded with the rest of the path,

        //    `[Root(range), Class(x)]` means "a node in range that also matches `.x`".

        // `:root` matches the document root element (NodeId::ZERO, the topmost

        // element). Handled here rather than in `match_pseudo_selector` because it

        // needs `node_id`. Equivalent to `html` but with pseudo-class specificity.

        }

    }

/// Matches an attribute selector (`[name]`, `[name="v"]`, `[name~="v"]`, ...) against a node.

///

/// Some attributes (notably `class`) are stored as multiple separate entries in

/// `node_data.attributes()` rather than a single space-joined string. We collect

/// every matching value and treat the matcher as "any value satisfies the op",

/// so that `[class~="primary"]` matches a node with classes `foo primary bar`.

            }

            }

            // Operator with a missing value (parser should reject these — be defensive).

        }

    }

/// Matches a pseudo-selector (:first, :last, :nth-child, :hover, etc.) against a node.

        ),

        ),

        ),

        ),

        ),

        ),

            // :lang() is matched via DynamicSelector at runtime, not during CSS cascade

            // During cascade, we just check if this is the expected ending

            // If not specifically looking for :lang, it doesn't match structurally

        }

        // `:root` is matched in `match_single_selector` (it needs `node_id`), so it

        // never reaches here — return false defensively.

    }

/// Returns true if the node is the first child of its parent.

/// Returns true if the node is the last child of its parent.

/// Matches :nth-child(n), :nth-child(even), :nth-child(odd), or :nth-child(An+B) patterns.

    use azul_css::css::CssNthChildPattern;

    // nth-child is 1-indexed, index_in_parent is 0-indexed

        Pattern(CssNthChildPattern {

        }) => {

            } else {

            }

        }

    }

/// Matches interactive pseudo-selectors (:hover, :active, :focus).

/// These only apply if they appear in the last content group of the CSS path.

#[cfg(test)]

#[allow(clippy::pedantic, clippy::nursery, clippy::too_many_lines)]

mod autotest_generated {

    use azul_css::{

        css::{CssNthChildPattern, CssScopeRange, NodeTypeTag},

        OptionString,

    };

    use super::*;

    use crate::{

        dom::{AttributeNameValue, AttributeType, NodeType},

        id::Node,

    };

    // ---------------------------------------------------------------------

    // helpers

    // ---------------------------------------------------------------------

    fn node(

        parent: Option<usize>,

        prev: Option<usize>,

        next: Option<usize>,

        last_child: Option<usize>,

    ) -> Node {

        Node {

            parent: parent.map(NodeId::new),

            previous_sibling: prev.map(NodeId::new),

            next_sibling: next.map(NodeId::new),

            last_child: last_child.map(NodeId::new),

        }

    }

    fn items(nodes: &[Node]) -> Vec<NodeHierarchyItem> {

        nodes.iter().map(|n| NodeHierarchyItem::from(*n)).collect()

    }

    fn div_with(id: Option<&str>, class: Option<&str>) -> NodeData {

        let mut nd = NodeData::create_div();

        if let Some(i) = id {

            nd.add_id(i.into());

        }

        if let Some(c) = class {

            nd.add_class(c.into());

        }

        nd

    }

    fn node_with_attrs(attrs: Vec<AttributeType>) -> NodeData {

        let mut nd = NodeData::create_div();

        nd.set_attributes(attrs.into());

        nd

    }

    fn custom(name: &str, value: &str) -> AttributeType {

        AttributeType::Custom(AttributeNameValue {

            attr_name: name.into(),

            value: value.into(),

        })

    }

    fn attr_sel(name: &str, op: AttributeMatchOp, value: Option<&str>) -> CssAttributeSelector {

        CssAttributeSelector {

            name: name.into(),

            op,

            value: value.map_or(OptionString::None, |v| OptionString::Some(v.into())),

        }

    }

    fn info(index_in_parent: u32, is_last_child: bool) -> CascadeInfo {

        CascadeInfo {

            index_in_parent,

            is_last_child,

        }

    }

    /// The shared fixture DOM. Note node 2 is a **text node** sitting between

    /// two element siblings — the whole point is to exercise the "text nodes

    /// are not counted as element siblings" rule (CSS Selectors L4 §13).

    ///

    /// ```text

    /// 0 body

    /// ├── 1 div#first.a

    /// ├── 2 "hello"          (text)

    /// ├── 3 div.b

    /// │   └── 4 p.inner

    /// └── 5 div.c

    /// ```

    fn sample_hierarchy() -> Vec<Node> {

        vec![

            node(None, None, None, Some(5)),

            node(Some(0), None, Some(2), None),

            node(Some(0), Some(1), Some(3), None),

            node(Some(0), Some(2), Some(5), Some(4)),

            node(Some(3), None, None, None),

            node(Some(0), Some(3), None, None),

        ]

    }

    fn sample_node_data() -> Vec<NodeData> {

        let mut p = NodeData::create_node(NodeType::P);

        p.add_class("inner".into());

        vec![

            NodeData::create_body(),

            div_with(Some("first"), Some("a")),

            NodeData::create_text_do_not_use_without_block_level_wrapper("hello"),

            div_with(None, Some("b")),

            p,

            div_with(None, Some("c")),

        ]

    }

    /// Runs `matches_html_element` against the sample fixture.

    fn matches(

        selectors: Vec<CssPathSelector>,

        node_index: usize,

        expected_path_ending: Option<CssPathPseudoSelector>,

    ) -> bool {

        let hierarchy = sample_hierarchy();

        let hier_items = items(&hierarchy);

        let data = sample_node_data();

        let hierarchy_ref = NodeHierarchyRef::from_slice(&hierarchy);

        let data_ref = NodeDataContainerRef::from_slice(&data);

        let depths = hierarchy_ref.get_parents_sorted_by_depth();

        let cascade = construct_html_cascade_tree(&hierarchy_ref, &depths, &data_ref);

        matches_html_element(

            &CssPath::new(selectors),

            NodeId::new(node_index),

            &NodeDataContainerRef::from_slice(&hier_items),

            &data_ref,

            &cascade.as_ref(),

            expected_path_ending,

        )

    }

    // ---------------------------------------------------------------------

    // CascadeInfoVec::as_container  (getter)

    // ---------------------------------------------------------------------

    #[test]

    fn cascade_info_vec_as_container_preserves_every_entry() {

        let v: CascadeInfoVec = vec![info(0, false), info(1, false), info(2, true)].into();

        let c = v.as_container();

        assert_eq!(c.len(), 3);

        assert!(!c.is_empty());

        assert_eq!(c[NodeId::new(0)], info(0, false));

        assert_eq!(c[NodeId::new(2)], info(2, true));

        // Out-of-range access must be a `None`, not a panic.

        assert_eq!(c.get(NodeId::new(3)), None);

        assert_eq!(c.get(NodeId::new(usize::MAX)), None);

    }

    #[test]

    fn cascade_info_vec_as_container_on_empty_vec_does_not_panic() {

        let v: CascadeInfoVec = Vec::new().into();

        let c = v.as_container();

        assert_eq!(c.len(), 0);

        assert!(c.is_empty());

        assert_eq!(c.get(NodeId::new(0)), None);

    }

    #[test]

    fn cascade_info_vec_as_container_survives_extreme_field_values() {

        let v: CascadeInfoVec = vec![info(u32::MAX, true)].into();

        let c = v.as_container();

        assert_eq!(c[NodeId::new(0)].index_in_parent, u32::MAX);

        assert!(c[NodeId::new(0)].is_last_child);

    }

    // ---------------------------------------------------------------------

    // CssGroupIterator

    // ---------------------------------------------------------------------

    #[test]

    fn css_group_iterator_new_records_the_path_and_yields_nothing_when_empty() {

        let empty: [CssPathSelector; 0] = [];

        let it = CssGroupIterator::new(&empty);

        assert!(it.css_path.is_empty());

        assert_eq!(CssGroupIterator::new(&empty).count(), 0);

    }

    #[test]

    fn css_group_iterator_new_keeps_the_slice_it_was_given() {

        let path = vec![

            CssPathSelector::Global,

            CssPathSelector::Children,

            CssPathSelector::Class("x".into()),

        ];

        let it = CssGroupIterator::new(&path);

        assert_eq!(it.css_path.len(), 3);

        assert_eq!(it.css_path, path.as_slice());

    }

    #[test]

    fn css_group_iterator_splits_right_to_left_with_the_left_hand_combinator() {

        // `body > .foo.main .baz`

        let path = vec![

            CssPathSelector::Type(NodeTypeTag::Body),

            CssPathSelector::DirectChildren,

            CssPathSelector::Class("foo".into()),

            CssPathSelector::Class("main".into()),

            CssPathSelector::Children,

            CssPathSelector::Class("baz".into()),

        ];

        let groups: Vec<_> = CssGroupIterator::new(&path).collect();

        assert_eq!(groups.len(), 3);

        // Group 0 is the RIGHTMOST group (the subject of the selector).

        assert_eq!(groups[0].0, vec![&path[5]]);

        assert_eq!(groups[0].1, CssGroupSplitReason::Children);

        assert_eq!(groups[1].0, vec![&path[2], &path[3]]);

        assert_eq!(groups[1].1, CssGroupSplitReason::DirectChildren);

        assert_eq!(groups[2].0, vec![&path[0]]);

        // NOTE: the leftmost group's `reason` is a carry-over from the previous

        // split (there is no combinator to its left). `matches_html_element`

        // never reads it — it uses `groups[i - 1].1` as the combinator for

        // group `i` — so we deliberately do not assert on it here.

    }

    #[test]

    fn css_group_iterator_yields_an_empty_group_for_a_trailing_combinator() {

        // Malformed path `.foo >` (a combinator with nothing to its right).

        let path = vec![

            CssPathSelector::Class("foo".into()),

            CssPathSelector::DirectChildren,

        ];

        let groups: Vec<_> = CssGroupIterator::new(&path).collect();

        assert_eq!(groups.len(), 2);

        assert!(

            groups[0].0.is_empty(),

            "the group to the right of the dangling combinator is empty"

        );

        assert_eq!(groups[0].1, CssGroupSplitReason::DirectChildren);

        assert_eq!(groups[1].0, vec![&path[0]]);

    }

    #[test]

    fn css_group_iterator_terminates_on_consecutive_combinators() {

        // `.a > ~ .b` — two combinators in a row (parser should never emit this,

        // but the iterator must not loop forever or drop selectors).

        let path = vec![

            CssPathSelector::Class("a".into()),

            CssPathSelector::Children,

            CssPathSelector::DirectChildren,

            CssPathSelector::Class("b".into()),

        ];

        let groups: Vec<_> = CssGroupIterator::new(&path).collect();

        assert_eq!(groups.len(), 3);

        assert_eq!(groups[0].0, vec![&path[3]]);

        assert!(groups[1].0.is_empty(), "the group between the two combinators is empty");

        assert_eq!(groups[2].0, vec![&path[0]]);

    }

    #[test]

    fn css_group_iterator_only_combinators_yields_only_empty_groups() {

        let path = vec![

            CssPathSelector::Children,

            CssPathSelector::DirectChildren,

            CssPathSelector::AdjacentSibling,

            CssPathSelector::GeneralSibling,

        ];

        let groups: Vec<_> = CssGroupIterator::new(&path).collect();

        // Four combinators, four splits, and the final `new_idx == 0 &&

        // current_path.is_empty()` branch ends the iteration.

        assert_eq!(groups.len(), 4);

        assert!(groups.iter().all(|(g, _)| g.is_empty()));

    }

    #[test]

    fn css_group_iterator_conserves_every_non_combinator_selector_on_a_huge_path() {

        // 10_000 selectors: `.c0 .c1 .c2 ...` — must terminate and must not

        // lose or duplicate a single selector.

        let mut path = Vec::new();

        for i in 0..5_000u32 {

            if i != 0 {

                path.push(CssPathSelector::Children);

            }

            path.push(CssPathSelector::Class(alloc::format!(".c{i}").into()));

        }

        let groups: Vec<_> = CssGroupIterator::new(&path).collect();

        assert_eq!(groups.len(), 5_000);

        let total: usize = groups.iter().map(|(g, _)| g.len()).sum();

        assert_eq!(

            total, 5_000,

            "every non-combinator selector must appear in exactly one group"

        );

        assert!(groups.iter().all(|(_, r)| *r == CssGroupSplitReason::Children));

    }

    // ---------------------------------------------------------------------

    // rule_ends_with

    // ---------------------------------------------------------------------

    #[test]

    fn rule_ends_with_empty_path_is_always_false() {

        let empty = CssPath::new(Vec::new());

        assert!(!rule_ends_with(&empty, None));

        assert!(!rule_ends_with(&empty, Some(CssPathPseudoSelector::Hover)));

        assert!(!rule_ends_with(

            &empty,

            Some(CssPathPseudoSelector::NthChild(CssNthChildSelector::Even))

        ));

    }

    #[test]

    fn rule_ends_with_none_rejects_interactive_pseudos_but_keeps_structural_ones() {

        let ends_with = |s: CssPathSelector| {

            rule_ends_with(&CssPath::new(vec![CssPathSelector::Class("a".into()), s]), None)

        };

        // Interactive => rejected for the "normal" (non-pseudo) pass.

        for p in [

            CssPathPseudoSelector::Hover,

            CssPathPseudoSelector::Active,

            CssPathPseudoSelector::Focus,

            CssPathPseudoSelector::Backdrop,

            CssPathPseudoSelector::Dragging,

            CssPathPseudoSelector::DragOver,

        ] {

            assert!(

                !ends_with(CssPathSelector::PseudoSelector(p.clone())),

                "interactive pseudo {p:?} must not end a `None` rule"

            );

        }

        // Structural => kept.

        assert!(ends_with(CssPathSelector::PseudoSelector(

            CssPathPseudoSelector::First

        )));

        assert!(ends_with(CssPathSelector::PseudoSelector(

            CssPathPseudoSelector::Last

        )));

        assert!(ends_with(CssPathSelector::PseudoSelector(

            CssPathPseudoSelector::NthChild(CssNthChildSelector::Odd)

        )));

        // Non-pseudo endings are always kept.

        assert!(ends_with(CssPathSelector::Global));

        assert!(ends_with(CssPathSelector::Class("b".into())));

        assert!(ends_with(CssPathSelector::Type(NodeTypeTag::Div)));

        assert!(ends_with(CssPathSelector::DirectChildren));

    }

    #[test]

    fn rule_ends_with_some_target_requires_an_exact_match_on_the_last_selector() {

        let hover = CssPath::new(vec![

            CssPathSelector::Class("a".into()),

            CssPathSelector::PseudoSelector(CssPathPseudoSelector::Hover),

        ]);

        assert!(rule_ends_with(&hover, Some(CssPathPseudoSelector::Hover)));

        assert!(!rule_ends_with(&hover, Some(CssPathPseudoSelector::Active)));

        assert!(!rule_ends_with(&hover, Some(CssPathPseudoSelector::Focus)));

        // A non-pseudo ending never matches a pseudo target.

        let plain = CssPath::new(vec![CssPathSelector::Class("a".into())]);

        assert!(!rule_ends_with(&plain, Some(CssPathPseudoSelector::Hover)));

        // Documented limitation: only the VERY LAST selector is inspected, so

        // `.a:hover:first` does not count as ending with `:hover`.

        let compound = CssPath::new(vec![

            CssPathSelector::Class("a".into()),

            CssPathSelector::PseudoSelector(CssPathPseudoSelector::Hover),

            CssPathSelector::PseudoSelector(CssPathPseudoSelector::First),

        ]);

        assert!(!rule_ends_with(&compound, Some(CssPathPseudoSelector::Hover)));

        assert!(rule_ends_with(&compound, Some(CssPathPseudoSelector::First)));

    }

    #[test]

    fn rule_ends_with_compares_nth_child_and_lang_payloads() {

        let nth = |s| {

            CssPath::new(vec![CssPathSelector::PseudoSelector(

                CssPathPseudoSelector::NthChild(s),

            )])

        };

        assert!(rule_ends_with(

            &nth(CssNthChildSelector::Number(3)),

            Some(CssPathPseudoSelector::NthChild(CssNthChildSelector::Number(3)))

        ));

        assert!(!rule_ends_with(

            &nth(CssNthChildSelector::Number(3)),

            Some(CssPathPseudoSelector::NthChild(CssNthChildSelector::Number(4)))

        ));

        assert!(!rule_ends_with(

            &nth(CssNthChildSelector::Even),

            Some(CssPathPseudoSelector::NthChild(CssNthChildSelector::Odd))

        ));

        // Unicode / boundary language tags must compare by value, not by prefix.

        let lang = |s: &str| {

            CssPath::new(vec![CssPathSelector::PseudoSelector(

                CssPathPseudoSelector::Lang(s.into()),

            )])

        };

        assert!(rule_ends_with(

            &lang("zh-Hant-🎉"),

            Some(CssPathPseudoSelector::Lang("zh-Hant-🎉".into()))

        ));

        assert!(!rule_ends_with(

            &lang("zh-Hant-🎉"),

            Some(CssPathPseudoSelector::Lang("zh".into()))

        ));

        assert!(!rule_ends_with(&lang(""), Some(CssPathPseudoSelector::Lang("de".into()))));

    }

    // ---------------------------------------------------------------------

    // match_first_child / match_last_child

    // ---------------------------------------------------------------------

    #[test]

    fn match_first_and_last_child_read_only_their_own_field() {

        assert!(match_first_child(info(0, false)));

        assert!(!match_first_child(info(1, true)));

        assert!(!match_first_child(info(u32::MAX, true)));

        assert!(match_last_child(info(0, true)));

        assert!(!match_last_child(info(0, false)));

        assert!(match_last_child(info(u32::MAX, true)));

    }

    // ---------------------------------------------------------------------

    // match_nth_child  (numeric: 1-indexing, saturation, div-by-zero, overflow)

    // ---------------------------------------------------------------------

    #[test]

    fn match_nth_child_is_one_indexed() {

        // index_in_parent 0 == :nth-child(1) == odd

        assert!(match_nth_child(info(0, false), &CssNthChildSelector::Number(1)));

        assert!(!match_nth_child(info(0, false), &CssNthChildSelector::Number(0)));

        assert!(match_nth_child(info(0, false), &CssNthChildSelector::Odd));

        assert!(!match_nth_child(info(0, false), &CssNthChildSelector::Even));

        assert!(match_nth_child(info(1, false), &CssNthChildSelector::Number(2)));

        assert!(match_nth_child(info(1, false), &CssNthChildSelector::Even));

        assert!(!match_nth_child(info(1, false), &CssNthChildSelector::Odd));

    }

    #[test]

    fn match_nth_child_number_matches_exactly_one_index() {

        for n in 1..64u32 {

            for idx in 0..64u32 {

                let matched = match_nth_child(info(idx, false), &CssNthChildSelector::Number(n));

                assert_eq!(matched, idx + 1 == n, "nth-child({n}) vs index {idx}");

            }

        }

        // `:nth-child(0)` can never match: the index is 1-based.

        for idx in 0..64u32 {

            assert!(!match_nth_child(info(idx, false), &CssNthChildSelector::Number(0)));

        }

    }

    #[test]

    fn match_nth_child_even_and_odd_partition_every_index() {

        for idx in 0..1_000u32 {

            let even = match_nth_child(info(idx, false), &CssNthChildSelector::Even);

            let odd = match_nth_child(info(idx, false), &CssNthChildSelector::Odd);

            assert_ne!(even, odd, "index {idx} must be exactly one of even/odd");

        }

    }

    #[test]

    fn match_nth_child_pattern_agrees_with_the_even_and_odd_shorthands() {

        // CSS: `even` == `2n`, `odd` == `2n+1`.

        for idx in 0..256u32 {

            let even_pat = CssNthChildSelector::Pattern(CssNthChildPattern {

                pattern_repeat: 2,

                offset: 0,

            });

            let odd_pat = CssNthChildSelector::Pattern(CssNthChildPattern {

                pattern_repeat: 2,

                offset: 1,

            });

            assert_eq!(

                match_nth_child(info(idx, false), &even_pat),

                match_nth_child(info(idx, false), &CssNthChildSelector::Even),

                "2n disagrees with `even` at index {idx}"

            );

            assert_eq!(

                match_nth_child(info(idx, false), &odd_pat),

                match_nth_child(info(idx, false), &CssNthChildSelector::Odd),

                "2n+1 disagrees with `odd` at index {idx}"

            );

        }

    }

    #[test]

    fn match_nth_child_zero_repeat_never_divides_by_zero() {

        // `0n+3` matches only the 3rd child; `0n+0` matches nothing (1-based).

        let only_third = CssNthChildSelector::Pattern(CssNthChildPattern {

            pattern_repeat: 0,

            offset: 3,

        });

        let never = CssNthChildSelector::Pattern(CssNthChildPattern {

            pattern_repeat: 0,

            offset: 0,

        });

        for idx in 0..32u32 {

            assert_eq!(match_nth_child(info(idx, false), &only_third), idx == 2);

            assert!(

                !match_nth_child(info(idx, false), &never),

                "0n+0 must never match (index is 1-based)"

            );

        }

    }

    #[test]

    fn match_nth_child_pattern_below_the_offset_does_not_underflow() {

        // `2n+5`: nothing below the 5th child may match, and the `index - offset`

        // subtraction must never be reached for those.

        let pat = CssNthChildSelector::Pattern(CssNthChildPattern {

            pattern_repeat: 2,

            offset: 5,

        });

        for idx in 0..4u32 {

            assert!(!match_nth_child(info(idx, false), &pat), "index {idx} < offset");

        }

        assert!(match_nth_child(info(4, false), &pat)); // 5th child

        assert!(!match_nth_child(info(5, false), &pat)); // 6th

        assert!(match_nth_child(info(6, false), &pat)); // 7th

    }

    #[test]

    fn match_nth_child_with_a_u32_max_offset_does_not_underflow() {

        let pat = CssNthChildSelector::Pattern(CssNthChildPattern {

            pattern_repeat: 1,

            offset: u32::MAX,

        });

        assert!(!match_nth_child(info(0, false), &pat));

        assert!(!match_nth_child(info(1_000, false), &pat));

        // index == u32::MAX (index_in_parent == u32::MAX - 1) is the largest

        // index that can be formed without overflowing the `+ 1`.

        assert!(match_nth_child(info(u32::MAX - 1, false), &pat));

    }

    /// BOUNDARY: `match_nth_child` computes `index_in_parent + 1` unchecked.

    /// `index_in_parent == u32::MAX` is reachable — `construct_html_cascade_tree`

    /// itself saturates to `u32::MAX` (`unwrap_or(u32::MAX)`), and `CascadeInfo`

    /// is a `#[repr(C)]` struct with public fields. Debug builds therefore panic

    /// on overflow, release builds wrap the index to 0. Assert that the wrap can

    /// never silently produce the *wrong* answer for even/odd/number.

    #[cfg(feature = "std")]

    #[test]

    fn match_nth_child_at_u32_max_index_never_answers_wrongly() {

        // The true 1-based index here is 2^32, which is even.

        let even = std::panic::catch_unwind(|| {

            match_nth_child(info(u32::MAX, false), &CssNthChildSelector::Even)

        });

        let odd = std::panic::catch_unwind(|| {

            match_nth_child(info(u32::MAX, false), &CssNthChildSelector::Odd)

        });

        let one = std::panic::catch_unwind(|| {

            match_nth_child(info(u32::MAX, false), &CssNthChildSelector::Number(1))

        });

        // debug: the overflow check fires — loud failure, acceptable.

        // release: the index wraps to 0, which must still not flip an answer.

        if let Ok(v) = even {

            assert!(v, "2^32 is even");

        }

        if let Ok(v) = odd {

            assert!(!v, "2^32 is not odd");

        }

        if let Ok(v) = one {

            assert!(!v, "the 2^32-th child is not the 1st child");

        }

    }

    // ---------------------------------------------------------------------

    // match_interactive_pseudo / match_pseudo_selector

    // ---------------------------------------------------------------------

    #[test]

    fn match_interactive_pseudo_needs_both_the_last_group_and_the_expected_ending() {

        let hover = CssPathPseudoSelector::Hover;

        let active = CssPathPseudoSelector::Active;

        assert!(match_interactive_pseudo(&hover, Some(&hover), true));

        assert!(!match_interactive_pseudo(&hover, Some(&hover), false));

        assert!(!match_interactive_pseudo(&hover, Some(&active), true));

        assert!(!match_interactive_pseudo(&hover, None, true));

        assert!(!match_interactive_pseudo(&hover, None, false));

    }

    #[test]

    fn match_pseudo_selector_routes_every_interactive_pseudo_through_the_gate() {

        for p in [

            CssPathPseudoSelector::Hover,

            CssPathPseudoSelector::Active,

            CssPathPseudoSelector::Focus,

            CssPathPseudoSelector::Backdrop,

            CssPathPseudoSelector::Dragging,

            CssPathPseudoSelector::DragOver,

        ] {

            assert!(

                match_pseudo_selector(&p, info(0, false), Some(&p), true),

                "{p:?} must match when it is the expected ending of the last group"

            );

            assert!(

                !match_pseudo_selector(&p, info(0, false), Some(&p), false),

                "{p:?} must not match outside the last content group"

            );

            assert!(

                !match_pseudo_selector(&p, info(0, false), None, true),

                "{p:?} must not match when no pseudo state is expected"

            );

        }

    }

    #[test]

    fn match_pseudo_selector_structural_pseudos_ignore_the_expected_ending() {

        let hover = CssPathPseudoSelector::Hover;

        // :first / :last / :nth-child depend only on the CascadeInfo.

        for (expected, is_last) in [(None, true), (Some(&hover), false), (Some(&hover), true)] {

            assert!(match_pseudo_selector(

                &CssPathPseudoSelector::First,

                info(0, false),

                expected,

                is_last

            ));

            assert!(!match_pseudo_selector(

                &CssPathPseudoSelector::First,

                info(1, false),

                expected,

                is_last

            ));

            assert!(match_pseudo_selector(

                &CssPathPseudoSelector::Last,

                info(9, true),

                expected,

                is_last

            ));

            assert!(match_pseudo_selector(

                &CssPathPseudoSelector::NthChild(CssNthChildSelector::Number(10)),

                info(9, true),

                expected,

                is_last

            ));

        }

    }

    #[test]

    fn match_pseudo_selector_lang_only_matches_the_expected_lang() {

        let de = CssPathPseudoSelector::Lang("de".into());

        let en = CssPathPseudoSelector::Lang("en".into());

        assert!(match_pseudo_selector(&de, info(0, false), Some(&de), true));

        assert!(!match_pseudo_selector(&de, info(0, false), Some(&en), true));

        assert!(!match_pseudo_selector(&de, info(0, false), None, true));

        assert!(!match_pseudo_selector(

            &de,

            info(0, false),

            Some(&CssPathPseudoSelector::Hover),

            true

        ));

        // Unicode + empty language tags must not panic and must compare by value.

        let emoji = CssPathPseudoSelector::Lang("de-🎉".into());

        assert!(match_pseudo_selector(&emoji, info(0, false), Some(&emoji), true));

        assert!(!match_pseudo_selector(&emoji, info(0, false), Some(&de), true));

        let empty = CssPathPseudoSelector::Lang("".into());

        assert!(match_pseudo_selector(&empty, info(0, false), Some(&empty), true));

    }

    // ---------------------------------------------------------------------

    // match_attribute_selector

    // ---------------------------------------------------------------------

    #[test]

    fn match_attribute_selector_on_a_node_without_attributes_is_always_false() {

        let nd = NodeData::create_div();