orinium_browser/engine/layouter/builder/

mod.rs

//! Layout builder, which transforms a DOM tree into a UI layout.

use crate::engine::animation::{AnimationInputs, ElementAnimationState, parse as anim_parse};
use crate::engine::css::values::CssValue;

mod args;
#[macro_use]
mod munch;
#[macro_use]
mod parse_args;
mod anchor;
mod apply;
mod background;
mod color;
mod css_resolve;
mod layout_fix;
#[cfg(test)]
mod tests;

pub use anchor::{parse_anchor_spec, resolve_anchor_positioning};
pub use apply::{apply_declaration, blockify_out_of_flow_positioned};
pub use layout_fix::{
    constrain_auto_grid_track_items, correct_atomic_inline_spacing,
    correct_atomic_inline_spacing_with_info, is_block_layout_child, is_collapsible_whitespace_info,
    refresh_missing_text_layout_results,
};

#[allow(unused_imports)]
pub use background::{
    apply_background_shorthand_geometry, parse_background_position, parse_background_repeat,
    parse_background_shorthand, parse_background_size, parse_gradient,
};
pub use color::resolve_css_color;
pub use css_resolve::{
    CalcValue, extract_font_families, one_or_two_values, parse_grid_line, parse_grid_line_end,
    parse_grid_placement, parse_grid_template_areas, parse_grid_tracks, resolve_calc_value,
    resolve_css_len, resolve_css_len_auto, resolve_font_size_px,
};

use crate::{perf_scope, profile_log};

use crate::engine::bridge::audio::AudioSinkFactory;
use crate::engine::bridge::text::{self, GlyphCluster};
use crate::engine::css::{
    matcher::{ElementChain, ElementInfo},
    values::Unit,
};
use crate::engine::html::util::split_html_space;
use crate::engine::html::{HtmlNodeType, ScriptingMode};
use crate::engine::layouter::css_resolver::{
    DeclarationResolver, Properties, PseudoElement, resolve_inline_value,
};
use crate::engine::layouter::dom_snapshot::{DomSnapshot, NodeId};
use crate::engine::layouter::types::WhiteSpace;
use crate::engine::renderer_model::Image;
use crate::engine::svg::{SvgContent, collect_svg};
use crate::engine::tree::NodeRef;
use crate::engine::ui::custom_node::CustomNode;
use crate::engine::ui::custom_node_bridge::CustomNodeBridge;
use crate::engine::ui::registry::{ComponentRegistry, CustomNodeContext, DomWriteBack};

use std::borrow::Cow;
use std::collections::{HashMap, HashSet};
use std::sync::Arc;

#[allow(unused_imports)]
use ui_layout::{
    AlignContent, AlignItems, AutoSizeBehavior, BoxSizing, Clear as LayoutClear, Display,
    FlexDirection, FlexWrap, Float as LayoutFloat, GridPlacement, GridPlacementEnd, GridRepeat,
    GridTrack, InnerDisplay, ItemFragment, JustifyContent, JustifyItems, LayoutChild, LayoutNode,
    Length, LengthOrAuto, OuterDisplay, Position, Style,
};

use super::css_resolver::{
    MediaEnvironment, ResolvedStyles, RuleSet, resolve_inline_style, set_inline_custom_property,
};
use super::match_cache::SelectorMatchCache;
use super::text_layouter::TextFlowLayouter;
#[allow(unused_imports)]
use super::types::{
    Background, BackgroundDimension, BackgroundOffset, BackgroundPosition, BackgroundPositionAxis,
    BackgroundRepeat, BackgroundSize, BorderRadius, BorderStyle, Color, ColorScheme, ColorStop,
    ContainerRole, ContainerStyle, CornerRadius, CssClear, CssFloat, FontStyle, FontWeight,
    Gradient, GradientKind, InfoNode, InteractionState, LineHeight, NodeKind, Overflow,
    RadialShape, RadialSizeKind, TextAlign, TextDecoration, TextFlowStyle, TextStyle,
    TextTransform,
};

pub(crate) const DEFAULT_LINE_FACTOR: f32 = 1.2;

const GRID_LINE_TO_END: GridPlacementEnd = GridPlacementEnd::Line(usize::MAX);

pub(crate) fn element_info(html_node: &HtmlNodeType) -> Option<ElementInfo> {
    let HtmlNodeType::Element {
        tag_name,
        attributes,
        ..
    } = html_node
    else {
        return None;
    };
    Some(ElementInfo {
        tag_name: tag_name.as_str().into(),
        id: attributes
            .iter()
            .find(|attribute| attribute.name == "id")
            .map(|attribute| Arc::from(attribute.value.as_str())),
        classes: attributes
            .iter()
            .find(|attribute| attribute.name == "class")
            .map(|attribute| {
                split_html_space(&attribute.value)
                    .map(Arc::<str>::from)
                    .collect()
            })
            .unwrap_or_default(),
        attributes: attributes
            .iter()
            .map(|attribute| {
                (
                    Arc::<str>::from(attribute.name.as_str()),
                    Arc::<str>::from(attribute.value.as_str()),
                )
            })
            .collect(),
        element_index: 1,
        element_count: 1,
        type_index: 1,
        type_count: 1,
        previous_siblings: ElementChain::default(),
        // A lone node carries no tree context, so both are filled in by the
        // callers that hold a snapshot. `has_parent` is optimistic here because
        // the structural pseudo-classes only use it to reject a tree root,
        // which a snapshot-less caller never describes.
        has_parent: true,
        is_empty: false,
        lang: None,
        checked: false,
        hovered: false,
        active: false,
    })
}

/// Structural pseudo-classes need a *parent element*; a document or shadow
/// root above the tree root does not count, which is why the root element must
/// not satisfy `:first-child`.
pub(crate) fn is_element_node(snapshot: &DomSnapshot, id: NodeId) -> bool {
    matches!(snapshot.node(id).kind, HtmlNodeType::Element { .. })
}

/// Read an element's own `lang` attribute, if any.
pub(crate) fn own_lang(snapshot: &DomSnapshot, id: NodeId) -> Option<Arc<str>> {
    snapshot
        .node(id)
        .kind
        .get_attr("lang")
        .map(str::trim)
        .filter(|value| !value.is_empty())
        .map(Arc::<str>::from)
}

/// The Selectors 4 `:empty` test: no element children, and no text node whose
/// data is non-empty. Comments and processing instructions are ignored, as are
/// empty text nodes.
pub(crate) fn is_empty_element(snapshot: &DomSnapshot, id: NodeId) -> bool {
    snapshot
        .children(id)
        .iter()
        .all(|&child| match &snapshot.node(child).kind {
            HtmlNodeType::Text(text) => text.is_empty(),
            HtmlNodeType::Element { .. } => false,
            _ => true,
        })
}

pub(crate) fn element_sibling_infos(
    snapshot: &DomSnapshot,
    children: &[NodeId],
    parent_lang: Option<&str>,
    interaction: &InteractionState,
) -> Vec<Option<ElementInfo>> {
    let mut type_counts = HashMap::<Arc<str>, usize>::new();
    for &child in children {
        if let Some(tag_name) = snapshot.node(child).kind.tag_name() {
            *type_counts.entry(Arc::from(tag_name)).or_default() += 1;
        }
    }
    let element_count = type_counts.values().sum();

    let mut seen_types = HashMap::<Arc<str>, usize>::new();
    let mut previous_siblings = ElementChain::default();
    let mut element_index = 0;
    children
        .iter()
        .map(|&child| {
            let mut info = match element_info(&snapshot.node(child).kind) {
                Some(info) => info,
                None => return None,
            };
            element_index += 1;
            let seen = seen_types.entry(Arc::clone(&info.tag_name)).or_default();
            *seen += 1;
            info.element_index = element_index;
            info.element_count = element_count;
            info.type_index = *seen;
            info.type_count = type_counts[&info.tag_name];
            info.previous_siblings = previous_siblings.clone();
            info.is_empty = is_empty_element(snapshot, child);
            info.checked = snapshot.node(child).checked;
            // `:lang()` sees the element's own tag, or the one inherited from
            // the nearest ancestor that declares one.
            info.lang = own_lang(snapshot, child).or_else(|| parent_lang.map(Arc::<str>::from));
            info.hovered = interaction.hovered_path.contains(&child);
            info.active = interaction.active_path.contains(&child);

            let mut sibling = info.clone();
            sibling.previous_siblings = ElementChain::default();
            previous_siblings = previous_siblings.prepend(Some(sibling));
            Some(info)
        })
        .collect()
}

/// Inherited values from parent, passed down through the tree.
///
/// `text_style` carries all inherited text/line-height values.
/// `color_scheme` carries the element's used color scheme (resolved from the
/// `color-scheme` property and the system preference).
/// Add new fields here when additional deferred-resolution properties arise.
#[derive(Clone, Default)]
pub struct InheritedCss {
    /// Inherited CSS custom properties, shared copy-on-write: descendants that
    /// do not introduce new `--var` values reuse the parent's map via `Arc`
    /// instead of deep-cloning it per element.
    pub custom_props: Arc<Properties>,
    pub text_style: TextStyle,
    pub text_flow_style: TextFlowStyle,
    pub color_scheme: ColorScheme,
}

/// Convert a resolved `Length` to an absolute pixel value for `LineHeight::Px`.
pub(super) fn length_to_px(len: &Length, font_size: f32) -> f32 {
    match len {
        Length::Px(v) => *v,
        Length::Percent(v) => v * font_size / 100.0,
        Length::Add(a, b) => length_to_px(a, font_size) + length_to_px(b, font_size),
        Length::Sub(a, b) => length_to_px(a, font_size) - length_to_px(b, font_size),
        Length::Mul(a, f) => length_to_px(a, font_size) * f,
        Length::Div(a, f) => length_to_px(a, font_size) / f,
        _ => font_size * DEFAULT_LINE_FACTOR,
    }
}

struct StackFrame {
    dom: NodeId,
    /// The language tag in effect for this node, so that descendants inherit
    /// `:lang()` correctly.
    lang: Option<Arc<str>>,
    chain: ElementChain,
    child: Arc<InheritedCss>,
    kind: Option<NodeKind>,
    style: Option<Style>,
    parent_style: Style,
    parent_container_style: ContainerStyle,
    child_slots: Vec<ChildSlot>,
    element_children: Vec<NodeId>,
    /// Inherited CSS counter state: counter name -> current value. Cloned from
    /// the parent and updated with this element's `counter-reset` /
    /// `counter-increment` before being passed to children.
    counter_state: HashMap<String, i32>,
}

enum ChildSlot {
    Inline(LayoutChild, Box<InfoNode>),
    Element(usize),
}

/// Builds the layout and render trees for a parsed HTML document.
///
/// The argument set mirrors [`build_layout_and_info_with_images`]; the
/// document-facing entry point forwards to it with no images present.
#[allow(clippy::too_many_arguments)]
pub fn build_layout_and_info(
    dom: &NodeRef<HtmlNodeType>,
    resolved_styles: &ResolvedStyles,
    measurer: Arc<dyn text::TextMeasurer>,
    audio_sinks: Arc<dyn AudioSinkFactory>,
    parent: InheritedCss,
    chain: ElementChain,
    system_color_scheme: ColorScheme,
    scripting_mode: ScriptingMode,
    viewport: (f32, f32),
) -> (LayoutNode, InfoNode) {
    build_layout_and_info_with_images(
        dom,
        resolved_styles,
        measurer,
        audio_sinks,
        parent,
        chain,
        system_color_scheme,
        scripting_mode,
        viewport,
        &HashMap::new(),
    )
}

/// Builds layout and render trees with decoded images keyed by their `src` value.
///
/// `viewport` supplies the viewport size used to evaluate `@media` queries while
/// resolving the style cascade (e.g. `@media (min-width: 768px)`).
#[allow(clippy::too_many_arguments)]
pub fn build_layout_and_info_with_images(
    dom: &NodeRef<HtmlNodeType>,
    resolved_styles: &ResolvedStyles,
    measurer: Arc<dyn text::TextMeasurer>,
    audio_sinks: Arc<dyn AudioSinkFactory>,
    parent: InheritedCss,
    chain: ElementChain,
    system_color_scheme: ColorScheme,
    scripting_mode: ScriptingMode,
    viewport: (f32, f32),
    images: &HashMap<String, Image>,
) -> (LayoutNode, InfoNode) {
    let (snapshot, _dom_refs) = DomSnapshot::from_tree(dom);
    let media_environment = MediaEnvironment::new(viewport, system_color_scheme);
    let rule_set = RuleSet::from_declarations(resolved_styles, &media_environment);
    let (layout, info, _) = build_layout_and_info_from_snapshot(
        &snapshot,
        snapshot.roots()[0],
        &rule_set,
        measurer,
        audio_sinks,
        parent,
        chain,
        system_color_scheme,
        scripting_mode,
        images,
        &HashMap::new(),
        None,
        None,
        &InteractionState::default(),
        &HashMap::new(),
        &HashMap::new(),
    );
    (layout, info)
}

/// Builds layout and render trees from a [`DomSnapshot`].
///
/// `write_back_sender` (when set) is cloned per text input so value changes
/// are reported as `(node id, value)` on the channel instead of mutating the
/// DOM directly, which allows this function to run off the UI thread.
///
/// `system_color_scheme` seeds the root element's used color scheme and is
/// used to resolve `color-scheme: light dark` and `light-dark()` values.
///
/// `match_cache` (when set) memoizes selector match results across builds that
/// share the same DOM snapshot and rule set. The caller is responsible for
/// clearing it when either input changes.
#[allow(clippy::too_many_arguments)]
pub fn build_layout_and_info_from_snapshot(
    snapshot: &DomSnapshot,
    root: NodeId,
    rule_set: &RuleSet,
    measurer: Arc<dyn text::TextMeasurer>,
    audio_sinks: Arc<dyn AudioSinkFactory>,
    parent: InheritedCss,
    mut chain: ElementChain,
    system_color_scheme: ColorScheme,
    scripting_mode: ScriptingMode,
    images: &HashMap<String, Image>,
    audio: &HashMap<String, Arc<[u8]>>,
    write_back_sender: Option<DomWriteBack>,
    mut match_cache: Option<&mut SelectorMatchCache>,
    interaction: &InteractionState,
    existing_custom_nodes: &HashMap<u32, Arc<dyn CustomNode>>,
    animated_overrides: &HashMap<NodeId, HashMap<String, CssValue>>,
) -> (
    LayoutNode,
    InfoNode,
    crate::engine::animation::AnimationInputs,
) {
    perf_scope!(total);

    #[cfg(any(feature = "profile", debug_assertions))]
    let mut css_match_time = std::time::Duration::ZERO;
    #[cfg(any(feature = "profile", debug_assertions))]
    let mut apply_decl_time = std::time::Duration::ZERO;
    #[cfg(any(feature = "profile", debug_assertions))]
    let mut custom_node_time = std::time::Duration::ZERO;
    #[cfg(any(feature = "profile", debug_assertions))]
    let mut text_layout_time = std::time::Duration::ZERO;
    #[cfg(any(feature = "profile", debug_assertions))]
    let mut exit_phase_time = std::time::Duration::ZERO;
    #[cfg(any(feature = "profile", debug_assertions))]
    let mut sibling_info_time = std::time::Duration::ZERO;
    #[cfg(any(feature = "profile", debug_assertions))]
    let mut whitespace_keep_time = std::time::Duration::ZERO;
    #[cfg(any(feature = "profile", debug_assertions))]
    let mut enter_prep_time = std::time::Duration::ZERO;
    #[cfg(any(feature = "profile", debug_assertions))]
    let mut child_slot_build_time = std::time::Duration::ZERO;
    #[cfg(any(feature = "profile", debug_assertions))]
    let mut leaf_assemble_time = std::time::Duration::ZERO;
    #[cfg(any(feature = "profile", debug_assertions))]
    let mut push_children_time = std::time::Duration::ZERO;
    #[cfg(any(feature = "profile", debug_assertions))]
    let mut exit_setup_time = std::time::Duration::ZERO;
    #[cfg(any(feature = "profile", debug_assertions))]
    let mut exit_build_time = std::time::Duration::ZERO;
    #[cfg(any(feature = "profile", debug_assertions))]
    let mut node_count = 0u64;

    #[cfg(any(feature = "profile", debug_assertions))]
    let mut cand_stats = CandidateMetrics::default();

    let registry = ComponentRegistry::new();
    /*
     * Build the initial element chain for the root node.
     */
    if let Some(mut info) = element_info(&snapshot.node(root).kind) {
        // The snapshot root has no parent, so it must not satisfy
        // `:first-child` and friends.
        info.has_parent = false;
        info.is_empty = is_empty_element(snapshot, root);
        info.hovered = interaction.hovered_path.contains(&root);
        info.active = interaction.active_path.contains(&root);
        chain = chain.prepend(Some(info));
    }

    // ── Explicit post-order stack (index-based to avoid borrow conflicts) ──

    let mut stack: Vec<StackFrame> = Vec::new();
    stack.push(StackFrame {
        dom: root,
        lang: own_lang(snapshot, root),
        chain,
        child: Arc::new(parent),
        kind: None,
        style: None,
        parent_style: Style::default(),
        parent_container_style: ContainerStyle::default(),
        child_slots: Vec::new(),
        element_children: Vec::new(),
        counter_state: HashMap::new(),
    });

    let mut results: HashMap<NodeId, (LayoutNode, InfoNode)> = HashMap::new();
    let mut animation_inputs: AnimationInputs = HashMap::new();

    // We use an index instead of .last_mut() so that push/pop don't conflict
    // with the mutable reference to the current frame.
    while let Some(top_idx) = {
        if stack.is_empty() {
            None
        } else {
            Some(stack.len() - 1)
        }
    } {
        // Phase check must happen BEFORE borrowing stack[top_idx] mutably.
        let is_entered = stack[top_idx].kind.is_some();

        if !is_entered {
            // ── ENTER phase ──────────────────────────────────────────────
            // Read frame state we need before taking any mutable action.
            let chain_for_css = stack[top_idx].chain.clone();
            let child_css = Arc::clone(&stack[top_idx].child);

            let html_node = &snapshot.node(stack[top_idx].dom).kind;
            let node_id = stack[top_idx].dom;
            let mut text_style = child_css.text_style.clone();
            let mut text_flow_style = child_css.text_flow_style;
            let mut container_style = ContainerStyle::default();
            if let HtmlNodeType::Element { tag_name, .. } = html_node {
                container_style.tag = Some(tag_name.clone());
            }
            let mut style = Style::default();
            let mut overflow = Overflow::default();
            let parent_style = stack[top_idx].parent_style.clone();
            let parent_container_style = stack[top_idx].parent_container_style.clone();
            let parent_text_style = text_style.clone();
            let parent_text_flow_style = text_flow_style;

            // Inherit container visibility
            container_style.visibility = parent_container_style.visibility;

            // Collect CSS candidates.
            perf_scope!(css_match);
            let (candidates, custom_property_candidates, pseudo_candidates) =
                if let HtmlNodeType::Element { .. } = html_node {
                    let (candidates, custom_property_candidates, pseudo_candidates) =
                        collect_candidates(
                            rule_set,
                            &chain_for_css,
                            node_id,
                            match_cache.as_deref_mut(),
                            #[cfg(any(feature = "profile", debug_assertions))]
                            &mut cand_stats,
                        );
                    (
                        Some(candidates),
                        Some(custom_property_candidates),
                        pseudo_candidates,
                    )
                } else {
                    (None, None, HashMap::new())
                };
            #[cfg(any(feature = "profile", debug_assertions))]
            {
                css_match_time += css_match.elapsed();
            }

            perf_scope!(enter_prep);
            // Inherit custom properties by sharing the parent's map unless this
            // element introduces new `--var` values (copy-on-write applies
            // cascade-discovered custom properties lazily).
            let mut custom_properties = Arc::clone(&child_css.custom_props);
            if let Some(own) = custom_property_candidates
                && !own.is_empty()
            {
                Arc::make_mut(&mut custom_properties).extend(own);
            }

            // Resolve the used color scheme for this element. `light-dark()`
            // and system colors resolve against it, and it is inherited by
            // descendants that do not set `color-scheme` themselves.
            let used_color_scheme = {
                let declaration = candidates
                    .as_ref()
                    .and_then(|c| c.get("color-scheme"))
                    .and_then(|d| {
                        DeclarationResolver::resolve_var(
                            &d.value,
                            &custom_properties,
                            &mut HashSet::new(),
                        )
                    });
                resolve_used_color_scheme(
                    declaration.as_ref(),
                    child_css.color_scheme,
                    system_color_scheme,
                )
            };
            #[cfg(any(feature = "profile", debug_assertions))]
            {
                enter_prep_time += enter_prep.elapsed();
            }

            // Apply presentational HTML attribute sizing (width/height
            // attributes). Presentational hints have the lowest priority in the
            // CSS cascade, below author stylesheets and inline declarations, so
            // they are applied first and can be overridden by CSS.
            for attr in ["width", "height"] {
                if let Some(value) = html_node.get_attr(attr)
                    && let Some(mut value) = resolve_inline_value(value)
                {
                    if let CssValue::Number(v) = value {
                        value = CssValue::Length(v, Unit::Px);
                    }
                    apply_declaration(
                        attr,
                        &value,
                        &mut style,
                        &mut container_style,
                        &mut text_style,
                        &mut text_flow_style,
                        &parent_style,
                        &parent_container_style,
                        &parent_text_style,
                        &parent_text_flow_style,
                        &mut overflow,
                        used_color_scheme,
                    );
                }
            }

            // Apply CSS declarations.
            perf_scope!(apply_decl);
            let mut anim_effective: std::collections::HashMap<String, CssValue> =
                std::collections::HashMap::new();
            let mut anim_transition = anim_parse::TransitionInputs::default();
            let mut anim_animation = anim_parse::AnimationInputs::default();
            // Counter operations collected during declaration application.
            let mut counter_resets: Vec<(String, i32)> = Vec::new();
            let mut counter_increments: Vec<(String, i32)> = Vec::new();
            if let Some(candidates) = &candidates {
                // The candidates map dedupes per property name (cascade winner),
                // but a shorthand and its longhand (e.g. `padding` and
                // `padding-top`) are distinct keys. Iterating a HashMap applies
                // them in random order, so re-sort by source order to make the
                // cascade deterministic.
                let mut candidates: Vec<_> = candidates.values().collect();
                candidates.sort_by_key(|declaration| declaration.order);

                for declaration in candidates {
                    if declaration.name.starts_with("--") {
                        continue;
                    }
                    let Some(value) = DeclarationResolver::resolve_var(
                        &declaration.value,
                        &custom_properties,
                        &mut HashSet::new(),
                    ) else {
                        continue;
                    };

                    // Counter state mutations are tracked separately and
                    // applied after the cascade loop.
                    if declaration.name == "counter-reset" {
                        counter_resets = parse_counter_reset(&value);
                        continue;
                    }
                    if declaration.name == "counter-increment" {
                        counter_increments = parse_counter_increment(&value);
                        continue;
                    }

                    apply_declaration(
                        &declaration.name,
                        &value,
                        &mut style,
                        &mut container_style,
                        &mut text_style,
                        &mut text_flow_style,
                        &parent_style,
                        &parent_container_style,
                        &parent_text_style,
                        &parent_text_flow_style,
                        &mut overflow,
                        used_color_scheme,
                    );
                    collect_animation_decl(
                        &declaration.name,
                        &value,
                        &mut anim_effective,
                        &mut anim_transition,
                        &mut anim_animation,
                    );
                }
            }

            // Compute counter state: start from inherited state, apply resets
            // (set to specified value), then increments (add to value).
            let mut counter_state = stack[top_idx].counter_state.clone();
            for (name, val) in &counter_resets {
                counter_state.insert(name.clone(), *val);
            }
            for (name, amount) in &counter_increments {
                *counter_state.entry(name.clone()).or_insert(0) += amount;
            }
            // Persist updated counter state on the frame so children inherit it.
            stack[top_idx].counter_state = counter_state.clone();

            // Apply the element's inline `style` attribute. Inline styles are
            // author-origin declarations with the highest specificity, so they
            // override stylesheet rules — unless the stylesheet rule was
            // `!important`, which still wins over a non-`!important` inline
            // declaration.
            if let Some(style_attr) = html_node.get_attr("style") {
                let inline_declarations = resolve_inline_style(style_attr);
                for (name, value, important) in &inline_declarations {
                    if name.starts_with("--") {
                        let stylesheet_important = candidates
                            .as_ref()
                            .and_then(|c| c.get(name))
                            .is_some_and(|declaration| declaration.important);
                        if *important || !stylesheet_important {
                            set_inline_custom_property(
                                Arc::make_mut(&mut custom_properties),
                                name.clone(),
                                value.clone(),
                                *important,
                            );
                        }
                    }
                }
                for (name, value, important) in inline_declarations {
                    if name.starts_with("--") {
                        continue;
                    }
                    let stylesheet_important = candidates
                        .as_ref()
                        .and_then(|c| c.get(&name))
                        .is_some_and(|declaration| declaration.important);
                    if !important && stylesheet_important {
                        continue;
                    }
                    let Some(value) = DeclarationResolver::resolve_var(
                        &value,
                        &custom_properties,
                        &mut HashSet::new(),
                    ) else {
                        continue;
                    };
                    apply_declaration(
                        &name,
                        &value,
                        &mut style,
                        &mut container_style,
                        &mut text_style,
                        &mut text_flow_style,
                        &parent_style,
                        &parent_container_style,
                        &parent_text_style,
                        &parent_text_flow_style,
                        &mut overflow,
                        used_color_scheme,
                    );
                    collect_animation_decl(
                        &name,
                        &value,
                        &mut anim_effective,
                        &mut anim_transition,
                        &mut anim_animation,
                    );
                }
            }
            #[cfg(any(feature = "profile", debug_assertions))]
            {
                apply_decl_time += apply_decl.elapsed();
            }

            // Record animation inputs for this element (base values + resolved specs).
            if matches!(html_node, HtmlNodeType::Element { .. }) {
                let transitions = anim_parse::build_transition_specs(&anim_transition);
                let animations = anim_parse::build_animation_specs(&anim_animation);
                let has_animation = animations
                    .iter()
                    .any(|a| a.name != "none" && !a.name.is_empty());
                if !transitions.is_empty() || has_animation {
                    let mut base_values = std::collections::HashMap::new();
                    for key in [
                        "opacity",
                        "width",
                        "height",
                        "top",
                        "right",
                        "bottom",
                        "left",
                        "margin-top",
                        "margin-right",
                        "margin-bottom",
                        "margin-left",
                        "padding-top",
                        "padding-right",
                        "padding-bottom",
                        "padding-left",
                        "font-size",
                        "line-height",
                        "color",
                        "transform",
                        "background-color",
                        "border-top-color",
                        "border-right-color",
                        "border-bottom-color",
                        "border-left-color",
                    ] {
                        if let Some(v) = anim_effective.get(key) {
                            base_values.insert(key.to_string(), v.clone());
                        }
                    }

                    // Fallback/computed base values to improve transition detection.
                    base_values
                        .entry("opacity".to_string())
                        .or_insert(CssValue::Number(container_style.opacity));
                    base_values.entry("color".to_string()).or_insert_with(|| {
                        CssValue::Color(format!(
                            "{:02x}{:02x}{:02x}{:02x}",
                            text_style.color.0,
                            text_style.color.1,
                            text_style.color.2,
                            text_style.color.3
                        ))
                    });
                    base_values
                        .entry("transform".to_string())
                        .or_insert(CssValue::Keyword("none".into()));
                    if let Some(color) = container_style.background.color {
                        base_values
                            .entry("background-color".to_string())
                            .or_insert_with(|| {
                                CssValue::Color(format!(
                                    "{:02x}{:02x}{:02x}{:02x}",
                                    color.0, color.1, color.2, color.3
                                ))
                            });
                    }

                    animation_inputs.insert(
                        node_id,
                        ElementAnimationState {
                            transitions,
                            animations,
                            base_values,
                        },
                    );
                }
            }

            // Apply animated overrides (runtime overlay) on top of base/inline styles.
            if let Some(overrides) = animated_overrides.get(&stack[top_idx].dom) {
                for (name, value) in overrides {
                    let Some(value) = DeclarationResolver::resolve_var(
                        value,
                        &custom_properties,
                        &mut HashSet::new(),
                    ) else {
                        continue;
                    };
                    apply_declaration(
                        name,
                        &value,
                        &mut style,
                        &mut container_style,
                        &mut text_style,
                        &mut text_flow_style,
                        &parent_style,
                        &parent_container_style,
                        &parent_text_style,
                        &parent_text_flow_style,
                        &mut overflow,
                        used_color_scheme,
                    );
                }
            }

            for layer in &mut container_style.background.layers {
                if let Some(crate::engine::layouter::types::BackgroundImage::Image {
                    source,
                    image,
                }) = &mut layer.image
                {
                    *image = images.get(source).cloned();
                }
            }

            // `float` and `clear` only apply to in-flow boxes; out-of-flow
            // (absolutely positioned) boxes ignore both.
            if !style.position.kind.is_out_of_flow() {
                style.float = match container_style.css_float {
                    CssFloat::None => LayoutFloat::None,
                    CssFloat::Left => LayoutFloat::Left,
                    CssFloat::Right => LayoutFloat::Right,
                };
                style.clear = match container_style.css_clear {
                    CssClear::None => LayoutClear::None,
                    CssClear::Left => LayoutClear::Left,
                    CssClear::Right => LayoutClear::Right,
                    CssClear::Both => LayoutClear::Both,
                };

                if style.float != LayoutFloat::None {
                    style.size.auto_behavior = AutoSizeBehavior::ShrinkToFit;
                    if matches!(
                        style.display.inner(),
                        Some(InnerDisplay::Flow) | Some(InnerDisplay::FlowRoot)
                    ) {
                        style.display = Display::OutsideInner {
                            outer: OuterDisplay::Inline,
                            inner: InnerDisplay::FlowRoot,
                        };
                    }
                }
            }

            // Absolutely positioned boxes are blockified before layout. The
            // inner display type remains unchanged.
            blockify_out_of_flow_positioned(&mut style);

            // Resolve line-height.
            style.line_height = match text_flow_style.line_height {
                LineHeight::Number(factor) => Length::Px(text_flow_style.font_size * factor),
                LineHeight::Normal => Length::Px(text_flow_style.font_size * DEFAULT_LINE_FACTOR),
                LineHeight::Px(px) => Length::Px(px),
            };
            container_style.text_align = text_flow_style.text_align;

            // ── Replaced <iframe> box ──
            // An iframe renders its content document (grafted into the DOM as
            // its children) inside a fixed 300×150 viewport that clips overflow,
            // per the CSS default for the element. Width/height attributes or
            // CSS override these defaults when supplied.
            if html_node.tag_name() == Some("iframe") {
                overflow.x = true;
                overflow.y = true;
                if matches!(style.size.width, LengthOrAuto::Auto) {
                    style.size.width = LengthOrAuto::Length(Length::Px(300.0));
                }
                if matches!(style.size.height, LengthOrAuto::Auto) {
                    style.size.height = LengthOrAuto::Length(Length::Px(150.0));
                }
            }

            // ── Inline SVG ──
            // An `<svg>` is atomic: its vector content rides on the layout
            // node instead of being laid out as child boxes. Collect the
            // viewBox and its single-color `<path>` subtree up front.
            let svg_content = if html_node.tag_name() == Some("svg") {
                collect_svg(
                    snapshot,
                    stack[top_idx].dom,
                    used_color_scheme,
                    text_style.color,
                )
            } else {
                None
            };

            // Per CSS-SIZING the auto height of an atomic SVG with a definite
            // width and an intrinsic aspect ratio (its viewBox) is the width
            // divided by that ratio (used when only a width is specified,
            // e.g. `svg { width: 100px }` with no height).
            if let Some(SvgContent {
                view_box: (_, _, vbw, vbh),
                ..
            }) = svg_content.as_ref()
                && *vbw > 0.0
                && *vbh > 0.0
                && matches!(style.size.height, LengthOrAuto::Auto)
                && let Some(width) = style.size.width.clone().length()
                && let Length::Px(width_px) = width
                && width_px > 0.0
            {
                style.size.height = LengthOrAuto::Length(Length::Px(width_px * *vbh / *vbw));
            }

            // An `<svg>` has no layout children; capture this early so it can
            // survive the move of `svg_content` into the kind construction.
            let is_svg_element = svg_content.is_some();

            let child = Arc::new(InheritedCss {
                custom_props: custom_properties,
                text_style: text_style.clone(),
                text_flow_style,
                color_scheme: used_color_scheme,
            });

            if let HtmlNodeType::Text(_) = html_node {
                unreachable!();
            }

            // ── Custom / replaced element (leaf) ──
            if let Some(tag) = html_node.tag_name()
                && registry.tags().contains(&tag)
            {
                perf_scope!(custom_node);
                // Replaced elements (button/img/input) size by their intrinsic
                // content when auto-sized, not by filling the containing block.
                style.size.auto_behavior = AutoSizeBehavior::ShrinkToFit;
                let media_source = html_node.get_attr("src").map(str::to_string).or_else(|| {
                    snapshot
                        .children(stack[top_idx].dom)
                        .iter()
                        .find_map(|&child| {
                            let child = &snapshot.node(child).kind;
                            (child.tag_name() == Some("source"))
                                .then(|| child.get_attr("src").map(str::to_string))
                                .flatten()
                        })
                });
                let reused = existing_custom_nodes.get(&stack[top_idx].dom).cloned();
                if let Some(node) = &reused {
                    let checked = snapshot.node(stack[top_idx].dom).checked;
                    node.set_checked(checked);
                }
                let node = reused.unwrap_or_else(|| {
                    registry
                        .create(&CustomNodeContext {
                            tag,
                            media_source: media_source.as_deref(),
                            container_style: &container_style,
                            text_style: &text_style,
                            measurer: Arc::clone(&measurer),
                            audio_sinks: &*audio_sinks,
                            images,
                            audio,
                            get_attr: &|name| html_node.get_attr(name).map(str::to_string),
                            write_back: write_back_sender
                                .as_ref()
                                .map(|sender| (sender.clone(), stack[top_idx].dom)),
                            dom_snapshot: snapshot,
                            dom_id: stack[top_idx].dom,
                        })
                        .expect("registry must handle every tag it reports")
                });

                let bridge = CustomNodeBridge::new_content(Arc::clone(&node), &style);
                let container_opacity = container_style.opacity;
                let kind = NodeKind::Custom {
                    node,
                    scroll_x: overflow.x,
                    scroll_y: overflow.y,
                    scroll_offset_x: 0.0,
                    scroll_offset_y: 0.0,
                    style: container_style,
                    layout_style: style.clone(),
                    text_style: text_style.clone(),
                    text_flow_style,
                };

                // ::before / ::after generated content for custom/replaced
                // elements, mirroring the element path: the pseudo slots flow
                // inline around the element's intrinsic box.
                let mut layout_children: Vec<LayoutChild> = Vec::new();
                let mut info_children: Vec<InfoNode> = Vec::new();
                let add_pseudo_slot =
                    |pseudo: &Properties,
                     layout_children: &mut Vec<LayoutChild>,
                     info_children: &mut Vec<InfoNode>| {
                        let dom_node = &snapshot.node(stack[top_idx].dom);
                        let get_attr = |name: &str| dom_node.kind.get_attr(name).map(|s| s.to_string());
                        if let Some(ChildSlot::Inline(fragment, pseudo_info)) = build_pseudo_slot(
                            pseudo,
                            &child_css.custom_props,
                            &text_style,
                            text_flow_style,
                            used_color_scheme,
                            &*measurer,
                            images,
                            &get_attr,
                            &stack[top_idx].counter_state,
                        ) {
                            layout_children.push(fragment);
                            info_children.push(*pseudo_info);
                        }
                    };
                let hidden = style.display == Display::None;
                if !hidden && let Some(pseudo) = pseudo_candidates.get(&PseudoElement::Before) {
                    add_pseudo_slot(pseudo, &mut layout_children, &mut info_children);
                }
                layout_children.push((style.clone(), bridge).into());
                // The intrinsic box is drawn by the custom node itself, but it
                // still owns a layout slot; mirror it with an empty info entry
                // so the following pseudo slots line up with their siblings.
                info_children.push(InfoNode {
                    kind: NodeKind::Container {
                        scroll_x: false,
                        scroll_y: false,
                        scroll_offset_x: 0.0,
                        scroll_offset_y: 0.0,
                        style: ContainerStyle::default(),
                        role: ContainerRole::Normal,
                    },
                    children: Vec::new(),
                    dom_id: None,
                });
                if !hidden && let Some(pseudo) = pseudo_candidates.get(&PseudoElement::After) {
                    add_pseudo_slot(pseudo, &mut layout_children, &mut info_children);
                }

                let layout = LayoutNode::with_children(style.clone(), layout_children);
                let info = InfoNode {
                    kind,
                    children: info_children,
                    dom_id: Some(stack[top_idx].dom),
                };
                let ptr = stack[top_idx].dom;
                // Ensure animation inputs exist for custom/replaced elements.
                if let std::collections::hash_map::Entry::Vacant(e) = animation_inputs.entry(ptr) {
                    let transitions = anim_parse::build_transition_specs(&anim_transition);
                    let animations = anim_parse::build_animation_specs(&anim_animation);
                    let has_animation = animations
                        .iter()
                        .any(|a| a.name != "none" && !a.name.is_empty());
                    if !transitions.is_empty() || has_animation {
                        let mut base_values = std::collections::HashMap::new();
                        for key in [
                            "opacity",
                            "width",
                            "height",
                            "top",
                            "right",
                            "bottom",
                            "left",
                            "margin-top",
                            "margin-right",
                            "margin-bottom",
                            "margin-left",
                            "padding-top",
                            "padding-right",
                            "padding-bottom",
                            "padding-left",
                            "font-size",
                            "line-height",
                            "color",
                            "transform",
                            "background-color",
                            "border-top-color",
                            "border-right-color",
                            "border-bottom-color",
                            "border-left-color",
                        ] {
                            if let Some(v) = anim_effective.get(key) {
                                base_values.insert(key.to_string(), v.clone());
                            }
                        }
                        base_values
                            .entry("opacity".to_string())
                            .or_insert(CssValue::Number(container_opacity));
                        base_values.entry("color".to_string()).or_insert_with(|| {
                            CssValue::Color(format!(
                                "{:02x}{:02x}{:02x}{:02x}",
                                text_style.color.0,
                                text_style.color.1,
                                text_style.color.2,
                                text_style.color.3
                            ))
                        });
                        base_values
                            .entry("transform".to_string())
                            .or_insert(CssValue::Keyword("none".into()));
                        e.insert(ElementAnimationState {
                            transitions,
                            animations,
                            base_values,
                        });
                    }
                }
                results.insert(ptr, (layout, info));
                #[cfg(any(feature = "profile", debug_assertions))]
                {
                    custom_node_time += custom_node.elapsed();
                    node_count += 1;
                }
                stack.pop();
                continue;
            }

            // ── Element node ──
            let is_link = html_node.tag_name() == Some("a") && html_node.get_attr("href").is_some();

            let role = match html_node.tag_name() {
                Some("table") => ContainerRole::Table,
                Some("thead" | "tbody" | "tfoot") => ContainerRole::TableRowGroup,
                Some("tr") => ContainerRole::TableRow,
                Some("td" | "th") => ContainerRole::TableCell,
                Some("caption") => ContainerRole::TableCaption,
                _ if is_link => ContainerRole::Link {
                    href: html_node.get_attr("href").unwrap().to_string(),
                },
                _ => ContainerRole::Normal,
            };

            let kind = if let Some(SvgContent {
                view_box, shapes, ..
            }) = svg_content
            {
                NodeKind::Svg {
                    view_box,
                    shapes,
                    scroll_x: overflow.x,
                    scroll_y: overflow.y,
                    scroll_offset_x: 0.0,
                    scroll_offset_y: 0.0,
                    style: container_style,
                }
            } else {
                NodeKind::Container {
                    scroll_x: overflow.x,
                    scroll_y: overflow.y,
                    scroll_offset_x: 0.0,
                    scroll_offset_y: 0.0,
                    style: container_style,
                    role,
                }
            };

            // Table → flex overrides
            if let Some(tag) = html_node.tag_name() {
                match tag {
                    "table" | "tbody" | "thead" | "tfoot" => {
                        style.display = Display::OutsideInner {
                            outer: OuterDisplay::Block,
                            inner: InnerDisplay::Flex,
                        };
                        style.flex_direction = FlexDirection::Column;
                    }
                    "tr" => {
                        style.display = Display::OutsideInner {
                            outer: OuterDisplay::Block,
                            inner: InnerDisplay::Flex,
                        };
                        style.flex_direction = FlexDirection::Row;
                    }
                    _ => {}
                }
            }

            let mut child_slots: Vec<ChildSlot> = Vec::new();
            let mut element_kids: Vec<NodeId> = Vec::new();

            perf_scope!(child_slot_build);
            // `<svg>` is atomic: its markup (path/text/whitespace) never forms
            // layout boxes, so no children are slotted at all.
            if style.display != Display::None && !is_svg_element {
                // ── ::before generated content ──
                if let Some(pseudo) = pseudo_candidates.get(&PseudoElement::Before) {
                    let dom_node = &snapshot.node(stack[top_idx].dom);
                    let get_attr = |name: &str| dom_node.kind.get_attr(name).map(|s| s.to_string());
                    if let Some(slot) = build_pseudo_slot(
                        pseudo,
                        &child_css.custom_props,
                        &text_style,
                        text_flow_style,
                        used_color_scheme,
                        &*measurer,
                        images,
                        &get_attr,
                        &stack[top_idx].counter_state,
                    )
                    {
                        child_slots.push(slot);
                        #[cfg(any(feature = "profile", debug_assertions))]
                        {
                            node_count += 1;
                        }
                    }
                }
                let parent_tag_name = snapshot.node(stack[top_idx].dom).kind.tag_name();
                for &child in snapshot.children(stack[top_idx].dom) {
                    let child_node = &snapshot.node(child).kind;
                    if let HtmlNodeType::Text(t) = child_node {
                        let t = if parent_tag_name == Some("pre") {
                            let t = t.strip_prefix('\n').unwrap_or(t);
                            normalize_whitespace(t, text_flow_style.white_space)
                        } else if t.chars().all(is_css_newline)
                            && matches!(
                                text_flow_style.white_space,
                                WhiteSpace::Normal | WhiteSpace::Nowrap
                            )
                        {
                            continue;
                        } else {
                            normalize_whitespace(t, text_flow_style.white_space)
                        };

                        let t = match text_style.text_transform {
                            TextTransform::None => t.into_owned(),
                            TextTransform::Uppercase => t.to_ascii_uppercase(),
                            TextTransform::Lowercase => t.to_ascii_lowercase(),
                        };
                        perf_scope!(text_layout);
                        let (layouter, kind) =
                            create_text_node(t, text_style.clone(), text_flow_style, &*measurer);
                        #[cfg(any(feature = "profile", debug_assertions))]
                        {
                            text_layout_time += text_layout.elapsed();
                            node_count += 1;
                        }
                        let mut inline_style = style.clone();
                        inline_style.display = Display::OutsideInner {
                            outer: OuterDisplay::Inline,
                            inner: InnerDisplay::Flow,
                        };
                        child_slots.push(ChildSlot::Inline(
                            (inline_style, layouter).into(),
                            Box::new(InfoNode {
                                kind,
                                children: Vec::new(),
                                dom_id: Some(child),
                            }),
                        ));
                    } else if child_node.tag_name() == Some("br") {
                        child_slots.push(ChildSlot::Inline(
                            ItemFragment::LineBreak.into(),
                            Box::new(InfoNode {
                                kind: NodeKind::LineBreak,
                                children: Vec::new(),
                                dom_id: Some(child),
                            }),
                        ));
                    } else if child_node.tag_name() == Some("noscript")
                        && scripting_mode == ScriptingMode::Enabled
                    {
                        // Skip
                    } else if child_node.tag_name() == Some("template")
                        || matches!(child_node, HtmlNodeType::DocumentFragment)
                    {
                        // Skip: template contents are inert and never rendered.
                    } else {
                        child_slots.push(ChildSlot::Element(element_kids.len()));
                        element_kids.push(child);
                    }
                }

                // ── ::after generated content ──
                if let Some(pseudo) = pseudo_candidates.get(&PseudoElement::After) {
                    let dom_node = &snapshot.node(stack[top_idx].dom);
                    let get_attr = |name: &str| dom_node.kind.get_attr(name).map(|s| s.to_string());
                    if let Some(slot) = build_pseudo_slot(
                        pseudo,
                        &child_css.custom_props,
                        &text_style,
                        text_flow_style,
                        used_color_scheme,
                        &*measurer,
                        images,
                        &get_attr,
                        &stack[top_idx].counter_state,
                    )
                    {
                        child_slots.push(slot);
                        #[cfg(any(feature = "profile", debug_assertions))]
                        {
                            node_count += 1;
                        }
                    }
                }
            }
            #[cfg(any(feature = "profile", debug_assertions))]
            {
                child_slot_build_time += child_slot_build.elapsed();
            }

            if element_kids.is_empty() {
                // ── No element children → leaf, build immediately ──
                perf_scope!(leaf_assemble);
                perf_scope!(whitespace_keep);
                let keep = compute_whitespace_keep(&child_slots, &[]);
                #[cfg(any(feature = "profile", debug_assertions))]
                {
                    whitespace_keep_time += whitespace_keep.elapsed();
                }
                let (layout_children, info_children): (Vec<_>, Vec<_>) = child_slots
                    .into_iter()
                    .enumerate()
                    .filter_map(|(i, slot)| {
                        if !keep[i] {
                            return None;
                        }
                        match slot {
                            ChildSlot::Inline(layout, info) => Some((layout, *info)),
                            ChildSlot::Element(_) => None,
                        }
                    })
                    .unzip();
                let layout = LayoutNode::with_children(style.clone(), layout_children);
                let info = InfoNode {
                    kind,
                    children: info_children,
                    dom_id: Some(stack[top_idx].dom),
                };
                let ptr = stack[top_idx].dom;
                results.insert(ptr, (layout, info));
                #[cfg(any(feature = "profile", debug_assertions))]
                {
                    leaf_assemble_time += leaf_assemble.elapsed();
                    node_count += 1;
                }
                stack.pop();
            } else {
                // ── Has element children → save state, push children ──
                perf_scope!(push_children);
                let parent_chain = stack[top_idx].chain.clone();
                let parent_container = match &kind {
                    NodeKind::Container { style, .. } => style.clone(),
                    _ => ContainerStyle::default(),
                };
                stack[top_idx].kind = Some(kind);
                stack[top_idx].parent_style = style.clone();
                stack[top_idx].parent_container_style = parent_container;
                stack[top_idx].style = Some(style);
                stack[top_idx].child = child;
                stack[top_idx].child_slots = child_slots;
                stack[top_idx].element_children = element_kids;

                // Build child chains and push frames.
                // Clone element_kids before the immutable borrow below
                // so we don't hold &mut stack[] while pushing.
                let kids_for_push: Vec<_> = {
                    let f = &stack[top_idx];
                    f.element_children.clone()
                };
                let child_css = Arc::clone(&stack[top_idx].child);
                perf_scope!(sibling_info);
                let parent_lang = stack[top_idx]
                    .lang
                    .clone()
                    .or_else(|| own_lang(snapshot, stack[top_idx].dom));
                let mut kid_infos = element_sibling_infos(
                    snapshot,
                    &kids_for_push,
                    parent_lang.as_deref(),
                    interaction,
                );
                if !is_element_node(snapshot, stack[top_idx].dom) {
                    for info in kid_infos.iter_mut().flatten() {
                        info.has_parent = false;
                    }
                }
                #[cfg(any(feature = "profile", debug_assertions))]
                {
                    sibling_info_time += sibling_info.elapsed();
                }
                let parent_style_for_children = stack[top_idx].parent_style.clone();
                let parent_container_for_children = stack[top_idx].parent_container_style.clone();
                for (&kid, info) in kids_for_push.iter().zip(kid_infos).rev() {
                    let kid_lang = info.as_ref().and_then(|info| info.lang.clone());
                    stack.push(StackFrame {
                        dom: kid,
                        lang: kid_lang,
                        chain: parent_chain.prepend(info),
                        child: Arc::clone(&child_css),
                        kind: None,
                        style: None,
                        parent_style: parent_style_for_children.clone(),
                        parent_container_style: parent_container_for_children.clone(),
                        child_slots: Vec::new(),
                        element_children: Vec::new(),
                        counter_state: stack[top_idx].counter_state.clone(),
                    });
                }
                #[cfg(any(feature = "profile", debug_assertions))]
                {
                    push_children_time += push_children.elapsed();
                }
            }
        } else {
            // ── EXIT phase ────────────────────────────────────────────────
            // Take ownership of frame data for building results.
            perf_scope!(exit_phase);
            perf_scope!(exit_setup);

            let frame = stack.swap_remove(top_idx);

            let style = frame.style.as_ref().unwrap().clone();
            let kind = frame.kind.as_ref().unwrap().clone();

            // Collect element children results.
            let mut element_results: Vec<(LayoutChild, InfoNode)> = Vec::new();

            for &kid in &frame.element_children {
                if let Some((child_layout, child_info)) = results.remove(&kid) {
                    element_results.push((child_layout.into(), child_info));
                }
            }

            // Handle html→body background inheritance.
            let mut final_kind = kind;
            if snapshot.node(frame.dom).kind.tag_name() == Some("html") {
                let should_inherit = final_kind.is_container_with_transparent_bg();
                if should_inherit {
                    for (_, child_info) in &element_results {
                        if child_info
                            .dom_id
                            .and_then(|id| snapshot.node(id).kind.tag_name())
                            == Some("body")
                        {
                            let child_bg = child_info.kind.container_bg();
                            if let Some(bg) = child_bg
                                && let NodeKind::Container { ref mut style, .. } = final_kind
                            {
                                style.background = bg.clone();
                            }
                        }
                    }
                }
            }

            #[cfg(any(feature = "profile", debug_assertions))]
            {
                exit_setup_time += exit_setup.elapsed();
            }

            perf_scope!(exit_build);
            let mut element_results: Vec<_> = element_results.into_iter().map(Some).collect();

            // Whitespace-only text nodes between two block-level siblings, or adjacent
            // to a `<br>`, would otherwise create stray inline boxes and spurious line
            // boxes in block, flex, and grid containers. Drop them now that every
            // sibling's display is resolved.
            perf_scope!(whitespace_keep);
            let keep = compute_whitespace_keep(&frame.child_slots, &element_results);
            #[cfg(any(feature = "profile", debug_assertions))]
            {
                whitespace_keep_time += whitespace_keep.elapsed();
            }

            let mut all_layout: Vec<LayoutChild> = Vec::with_capacity(frame.child_slots.len());
            let mut all_info: Vec<InfoNode> = Vec::with_capacity(frame.child_slots.len());

            for (i, slot) in frame.child_slots.into_iter().enumerate() {
                if !keep[i] {
                    continue;
                }
                let (lc, ic) = match slot {
                    ChildSlot::Inline(layout, info) => (layout, *info),
                    ChildSlot::Element(index) => element_results[index]
                        .take()
                        .expect("element child result must exist"),
                };
                all_layout.push(lc);
                all_info.push(ic);
            }

            // Collapsible whitespace at a block boundary does not create an
            // anonymous line box. Keeping indentation-only DOM text here made
            // a block such as Scratch's `.page` start one default line-height
            // below the viewport.
            let keep: Vec<bool> = (0..all_layout.len())
                .map(|index| {
                    let white_space = match &all_info[index].kind {
                        NodeKind::Text { flow_style, .. } => flow_style.white_space,
                        _ => WhiteSpace::Normal,
                    };
                    let collapsible = is_collapsible_whitespace_info(&all_info[index], white_space);
                    let next_to_block = index == 0
                        || index + 1 == all_layout.len()
                        || index
                            .checked_sub(1)
                            .is_some_and(|previous| is_block_layout_child(&all_layout[previous]))
                        || all_layout.get(index + 1).is_some_and(is_block_layout_child);
                    !(collapsible && next_to_block)
                })
                .collect();
            all_layout = all_layout
                .into_iter()
                .zip(&keep)
                .filter_map(|(layout, keep)| keep.then_some(layout))
                .collect();
            all_info = all_info
                .into_iter()
                .zip(keep)
                .filter_map(|(info, keep)| keep.then_some(info))
                .collect();

            // Grid and flex items are blockified by CSS Display. Keeping an
            // inline direct child makes its text-flow coordinates remain in
            // the parent's inline space, so item placement cannot move the
            // text with its box.
            if matches!(
                style.display.inner(),
                Some(InnerDisplay::Grid | InnerDisplay::Flex)
            ) {
                if style.display.inner() == Some(InnerDisplay::Grid) {
                    let columns = explicit_grid_track_count(&style.grid_template_columns);
                    let rows = explicit_grid_track_count(&style.grid_template_rows);
                    for child in &mut all_layout {
                        if let LayoutChild::Node(child) = child {
                            resolve_named_grid_area(child, &style.grid_template_areas);
                            resolve_grid_end_line(&mut child.style.grid_column, columns);
                            resolve_grid_end_line(&mut child.style.grid_row, rows);
                        }
                    }
                }
                for child in &mut all_layout {
                    if let LayoutChild::Node(child) = child
                        && child.style.display.outer() == Some(OuterDisplay::Inline)
                        && !child.style.position.kind.is_out_of_flow()
                        && let Display::OutsideInner { inner, .. } = child.style.display
                    {
                        child.style.display = Display::OutsideInner {
                            outer: OuterDisplay::Block,
                            inner,
                        };
                    }
                }
            }

            let layout = LayoutNode::with_children(style, all_layout);
            let info = InfoNode {
                kind: final_kind,
                children: all_info,
                dom_id: Some(frame.dom),
            };
            let ptr = frame.dom;
            results.insert(ptr, (layout, info));
            #[cfg(any(feature = "profile", debug_assertions))]
            {
                exit_build_time += exit_build.elapsed();
                exit_phase_time += exit_phase.elapsed();
                node_count += 1;
            }
        }
    }

    profile_log!(
        target: "LayoutRun",
        log::Level::Info,
        "[LayoutMetrics] total: {:?} (nodes: {})",
        total.elapsed(),
        node_count,
    );
    profile_log!(
        target: "LayoutRun",
        log::Level::Info,
        "[LayoutMetrics] css_match: {:?} | apply_decl: {:?}",
        css_match_time,
        apply_decl_time,
    );
    profile_log!(
        target: "LayoutRun",
        log::Level::Info,
        "[LayoutCandidates] elements: {} | examined: {} | matched: {}",
        cand_stats.elements_checked,
        cand_stats.candidates_examined,
        cand_stats.selectors_matched,
    );
    profile_log!(
        target: "LayoutRun",
        log::Level::Info,
        "[LayoutCandidates] query_time: {:?} | sel_match_time: {:?} | insert_time: {:?}",
        cand_stats.query_candidates_time,
        cand_stats.selector_match_time,
        cand_stats.cascade_insert_time,
    );
    profile_log!(
        target: "LayoutRun",
        log::Level::Info,
        "[LayoutMetrics] custom_node: {:?} | text_layout: {:?} | exit_phase: {:?}",
        custom_node_time,
        text_layout_time,
        exit_phase_time,
    );
    profile_log!(
        target: "LayoutRun",
        log::Level::Info,
        "[LayoutMetrics] sibling_info: {:?} | whitespace_keep: {:?}",
        sibling_info_time,
        whitespace_keep_time,
    );
    profile_log!(
        target: "LayoutRun",
        log::Level::Info,
        "[LayoutMetrics] enter_prep: {:?} | child_slot_build: {:?} | leaf_assemble: {:?}",
        enter_prep_time,
        child_slot_build_time,
        leaf_assemble_time,
    );
    profile_log!(
        target: "LayoutRun",
        log::Level::Info,
        "[LayoutMetrics] push_children: {:?} | exit_setup: {:?} | exit_build: {:?}",
        push_children_time,
        exit_setup_time,
        exit_build_time,
    );
    profile_log!(
        target: "LayoutRun",
        log::Level::Info,
        "[LayoutMetrics] rest: {:?}",
        total.elapsed().saturating_sub(
            css_match_time
                + apply_decl_time
                + custom_node_time
                + enter_prep_time
                + child_slot_build_time
                + leaf_assemble_time
                + push_children_time
                + exit_setup_time
                + exit_build_time
        ),
    );

    let (layout, info_node) = results
        .remove(&root)
        .expect("root must have been processed");
    (layout, info_node, animation_inputs)
}

fn collect_animation_decl(
    name: &str,
    value: &CssValue,
    effective: &mut std::collections::HashMap<String, CssValue>,
    transition: &mut anim_parse::TransitionInputs,
    animation: &mut anim_parse::AnimationInputs,
) {
    let lname = name.to_ascii_lowercase();
    match lname.as_str() {
        "transition-property" => transition.property = Some(value.clone()),
        "transition-duration" => transition.duration = Some(value.clone()),
        "transition-delay" => transition.delay = Some(value.clone()),
        "transition-timing-function" => transition.timing_function = Some(value.clone()),
        "transition" => {
            // MVP shorthand: per-comma group parse property, times, easing.
            let groups = split_css_comma_groups(value);
            let mut props: Vec<CssValue> = Vec::new();
            let mut durs: Vec<CssValue> = Vec::new();
            let mut delays: Vec<CssValue> = Vec::new();
            let mut easings: Vec<CssValue> = Vec::new();
            for group in groups {
                let mut prop: Option<CssValue> = None;
                let mut times: Vec<CssValue> = Vec::new();
                let mut easing: Option<CssValue> = None;
                for item in flatten_css_value_items(&group) {
                    if anim_parse::parse_time_ms(&item).is_some() {
                        if times.len() < 2 {
                            times.push(item);
                        }
                        continue;
                    }
                    if easing.is_none() && anim_parse::parse_easing(&item).is_some() {
                        easing = Some(item);
                        continue;
                    }
                    if prop.is_none()
                        && let CssValue::Keyword(_) | CssValue::String(_) = item
                    {
                        prop = Some(item);
                    }
                }
                props.push(prop.unwrap_or_else(|| CssValue::Keyword("all".into())));
                durs.push(
                    times
                        .first()
                        .cloned()
                        .unwrap_or(CssValue::Length(0.0, Unit::S)),
                );
                delays.push(
                    times
                        .get(1)
                        .cloned()
                        .unwrap_or(CssValue::Length(0.0, Unit::S)),
                );
                easings.push(easing.unwrap_or_else(|| CssValue::Keyword("ease".into())));
            }
            if !props.is_empty() {
                transition.property = Some(join_css_comma_groups(props));
                transition.duration = Some(join_css_comma_groups(durs));
                transition.delay = Some(join_css_comma_groups(delays));
                transition.timing_function = Some(join_css_comma_groups(easings));
            }
        }
        "animation-name" => animation.name = Some(value.clone()),
        "animation-duration" => animation.duration = Some(value.clone()),
        "animation-delay" => animation.delay = Some(value.clone()),
        "animation-timing-function" => animation.timing_function = Some(value.clone()),
        "animation-iteration-count" => animation.iteration_count = Some(value.clone()),
        "animation-direction" => animation.direction = Some(value.clone()),
        "animation-fill-mode" => animation.fill_mode = Some(value.clone()),
        "animation-play-state" => animation.play_state = Some(value.clone()),
        "animation" => {
            // MVP shorthand: parse common tokens per comma group.
            let groups = split_css_comma_groups(value);
            let mut names: Vec<CssValue> = Vec::new();
            let mut durs: Vec<CssValue> = Vec::new();
            let mut delays: Vec<CssValue> = Vec::new();
            let mut easings: Vec<CssValue> = Vec::new();
            let mut iters: Vec<CssValue> = Vec::new();
            let mut dirs: Vec<CssValue> = Vec::new();
            let mut fills: Vec<CssValue> = Vec::new();
            let mut states: Vec<CssValue> = Vec::new();
            for group in groups {
                let mut name: Option<CssValue> = None;
                let mut times: Vec<CssValue> = Vec::new();
                let mut easing: Option<CssValue> = None;
                let mut iter: Option<CssValue> = None;
                let mut dir: Option<CssValue> = None;
                let mut fill: Option<CssValue> = None;
                let mut state: Option<CssValue> = None;
                for item in flatten_css_value_items(&group) {
                    if anim_parse::parse_time_ms(&item).is_some() && times.len() < 2 {
                        times.push(item);
                        continue;
                    }
                    if easing.is_none() && anim_parse::parse_easing(&item).is_some() {
                        easing = Some(item);
                        continue;
                    }
                    if iter.is_none() && anim_parse::parse_iteration_count(&item).is_some() {
                        iter = Some(item);
                        continue;
                    }
                    if dir.is_none() && anim_parse::parse_direction(&item).is_some() {
                        dir = Some(item);
                        continue;
                    }
                    if fill.is_none() && anim_parse::parse_fill_mode(&item).is_some() {
                        fill = Some(item);
                        continue;
                    }
                    if state.is_none() && anim_parse::parse_play_state(&item).is_some() {
                        state = Some(item);
                        continue;
                    }
                    if name.is_none()
                        && let CssValue::Keyword(_) | CssValue::String(_) = item
                    {
                        name = Some(item);
                    }
                }
                names.push(name.unwrap_or_else(|| CssValue::Keyword("none".into())));
                durs.push(
                    times
                        .first()
                        .cloned()
                        .unwrap_or(CssValue::Length(0.0, Unit::S)),
                );
                delays.push(
                    times
                        .get(1)
                        .cloned()
                        .unwrap_or(CssValue::Length(0.0, Unit::S)),
                );
                easings.push(easing.unwrap_or_else(|| CssValue::Keyword("ease".into())));
                iters.push(iter.unwrap_or(CssValue::Number(1.0)));
                dirs.push(dir.unwrap_or_else(|| CssValue::Keyword("normal".into())));
                fills.push(fill.unwrap_or_else(|| CssValue::Keyword("none".into())));
                states.push(state.unwrap_or_else(|| CssValue::Keyword("running".into())));
            }
            if !names.is_empty() {
                animation.name = Some(join_css_comma_groups(names));
                animation.duration = Some(join_css_comma_groups(durs));
                animation.delay = Some(join_css_comma_groups(delays));
                animation.timing_function = Some(join_css_comma_groups(easings));
                animation.iteration_count = Some(join_css_comma_groups(iters));
                animation.direction = Some(join_css_comma_groups(dirs));
                animation.fill_mode = Some(join_css_comma_groups(fills));
                animation.play_state = Some(join_css_comma_groups(states));
            }
        }
        _ => {}
    }

    if matches!(
        lname.as_str(),
        "opacity"
            | "width"
            | "height"
            | "top"
            | "right"
            | "bottom"
            | "left"
            | "margin-top"
            | "margin-right"
            | "margin-bottom"
            | "margin-left"
            | "padding-top"
            | "padding-right"
            | "padding-bottom"
            | "padding-left"
            | "font-size"
            | "line-height"
            | "color"
            | "transform"
            | "background-color"
            | "border-top-color"
            | "border-right-color"
            | "border-bottom-color"
            | "border-left-color"
    ) {
        effective.insert(lname, value.clone());
    }
}

fn split_css_comma_groups(value: &CssValue) -> Vec<Vec<CssValue>> {
    match value {
        CssValue::List(items) => {
            let mut groups: Vec<Vec<CssValue>> = vec![Vec::new()];
            for item in items {
                if matches!(item, CssValue::Keyword(k) if k == ",") {
                    groups.push(Vec::new());
                } else {
                    groups.last_mut().unwrap().push(item.clone());
                }
            }
            if groups.is_empty() {
                vec![vec![]]
            } else {
                groups
            }
        }
        other => vec![vec![other.clone()]],
    }
}

fn flatten_css_value_items(items: &[CssValue]) -> Vec<CssValue> {
    let mut out = Vec::new();
    for item in items {
        match item {
            CssValue::List(inner) => out.extend(inner.clone()),
            _ => out.push(item.clone()),
        }
    }
    out
}

fn join_css_comma_groups(groups: Vec<CssValue>) -> CssValue {
    if groups.len() <= 1 {
        return groups
            .into_iter()
            .next()
            .unwrap_or(CssValue::Keyword("none".into()));
    }
    let mut out: Vec<CssValue> = Vec::new();
    for (i, g) in groups.into_iter().enumerate() {
        if i > 0 {
            out.push(CssValue::Keyword(",".into()));
        }
        out.push(g);
    }
    CssValue::List(out)
}

// ── Whitespace helpers ──────────────────────────────────────────────────────

fn is_css_whitespace(c: char) -> bool {
    matches!(c, ' ' | '\t' | '\n' | '\r' | '\x0c')
}

fn is_css_newline(c: char) -> bool {
    matches!(c, '\n' | '\r')
}

/// True when an inline child is a whitespace-only text node that renders as
/// nothing more than a collapsible space.
fn is_collapsible_whitespace_text(info: &InfoNode) -> bool {
    matches!(
        &info.kind,
        NodeKind::Text {
            text, flow_style, ..
        } if text.chars().all(is_css_whitespace)
            && matches!(
                flow_style.white_space,
                WhiteSpace::Normal | WhiteSpace::Nowrap
            )
    )
}

/// Classification of the nearest layout-participating sibling of a slot.
#[derive(PartialEq)]
enum Neighbour {
    /// No participating sibling (container edge) or only `display:none` boxes.
    None,
    /// A block-level element box.
    Block,
    /// A `<br>` line break.
    LineBreak,
    /// Any other inline content (text, inline element, replaced, …).
    Inline,
}

/// Inspects the nearest layout-participating sibling of `slot_index` in the
/// given `step` direction (`-1` = previous, `+1` = next).
///
/// Collapsible-whitespace-only text siblings are always skipped. `<br>`
/// siblings are skipped when `skip_line_break` is set, so the caller can tell
/// "adjacent to a `<br>`" apart from "the nearest block beyond a `<br>`".
fn neighbour(
    slots: &[ChildSlot],
    element_results: &[Option<(LayoutChild, InfoNode)>],
    slot_index: usize,
    step: isize,
    skip_line_break: bool,
) -> Neighbour {
    let mut idx = slot_index;

    loop {
        let Some(next) = (if step < 0 {
            idx.checked_sub(1)
        } else {
            idx.checked_add(1)
        }) else {
            return Neighbour::None;
        };
        if next >= slots.len() {
            return Neighbour::None;
        }
        idx = next;

        match &slots[idx] {
            ChildSlot::Element(element_index) => {
                let Some((child, _)) = element_results[*element_index].as_ref() else {
                    continue;
                };

                // display:none elements do not participate in layout.
                if matches!(
                    child,
                    LayoutChild::Node(node)
                        if node.style.display == Display::None
                ) {
                    continue;
                }

                return if matches!(
                    child,
                    LayoutChild::Node(node)
                        if node.style.display.outer() == Some(OuterDisplay::Block)
                ) {
                    Neighbour::Block
                } else {
                    Neighbour::Inline
                };
            }
            ChildSlot::Inline(_, info) => {
                if matches!(info.kind, NodeKind::LineBreak) {
                    if !skip_line_break {
                        return Neighbour::LineBreak;
                    }
                } else if !is_collapsible_whitespace_text(info) {
                    return Neighbour::Inline;
                }
            }
        }
    }
}

/// Per-child keep decision for whitespace-only text nodes.
///
/// A whitespace-only text node is dropped when it is adjacent on *either*
/// side to a block-level sibling or to a `<br>`; otherwise it would become a
/// stray inline box that creates a spurious line box in block containers.
fn compute_whitespace_keep(
    slots: &[ChildSlot],
    element_results: &[Option<(LayoutChild, InfoNode)>],
) -> Vec<bool> {
    (0..slots.len())
        .map(|i| match &slots[i] {
            ChildSlot::Inline(_, info) => {
                if !is_collapsible_whitespace_text(info) {
                    return true;
                }
                // Drop if either side is a block-level box or a `<br>` (a line
                // break starts a new line, so adjacent whitespace is spurious).
                let side_drops = |step: isize| {
                    neighbour(slots, element_results, i, step, true) == Neighbour::Block
                        || neighbour(slots, element_results, i, step, false) == Neighbour::LineBreak
                };
                !(side_drops(-1) || side_drops(1))
            }
            ChildSlot::Element(_) => true,
        })
        .collect()
}

// ── Grid layout helpers ─────────────────────────────────────────────────────

fn explicit_grid_track_count(tracks: &[GridTrack]) -> usize {
    tracks
        .iter()
        .map(|track| match track {
            GridTrack::Repeat(GridRepeat::Count(count), pattern) => {
                count.saturating_mul(explicit_grid_track_count(pattern))
            }
            GridTrack::Repeat(GridRepeat::AutoFit | GridRepeat::AutoFill, _) => 0,
            _ => 1,
        })
        .sum()
}

fn resolve_grid_end_line(placement: &mut GridPlacement, track_count: usize) {
    if !matches!(placement.end, GRID_LINE_TO_END) || track_count == 0 {
        return;
    }

    placement.end = GridPlacementEnd::Line(track_count + 1);
}

fn resolve_named_grid_area(node: &mut LayoutNode, areas: &[Vec<String>]) {
    let Some(name) = node.style.grid_area.as_deref() else {
        return;
    };
    let mut min_column = usize::MAX;
    let mut max_column = 0;
    let mut min_row = usize::MAX;
    let mut max_row = 0;
    for (row, names) in areas.iter().enumerate() {
        for (column, area) in names.iter().enumerate() {
            if area == name {
                min_column = min_column.min(column);
                max_column = max_column.max(column);
                min_row = min_row.min(row);
                max_row = max_row.max(row);
            }
        }
    }
    if min_column == usize::MAX {
        return;
    }
    node.style.grid_column = GridPlacement {
        start: Some(min_column + 1),
        end: GridPlacementEnd::Line(max_column + 2),
    };
    node.style.grid_row = GridPlacement {
        start: Some(min_row + 1),
        end: GridPlacementEnd::Line(max_row + 2),
    };
    node.style.grid_area = None;
}

// ── Text normalization ──────────────────────────────────────────────────────

/// Normalizes segment breaks and collapsible whitespace according to the
/// element's `white-space`.
///
/// Returns [`Cow::Borrowed`] when `text` is already in normalized form, which
/// is the common case for the many short text nodes whose content has no
/// segment breaks, repeated spaces or leading/trailing whitespace. Only the
/// text that actually needs rewriting is copied.
pub fn normalize_whitespace(text: &str, white_space: WhiteSpace) -> Cow<'_, str> {
    // `pre`-like modes only rewrite segment breaks (`\r\n`, `\r`, `\x0c` are
    // all replaced by `\n`); every other rune is preserved verbatim.
    let is_pre_like = matches!(
        white_space,
        WhiteSpace::Pre | WhiteSpace::PreWrap | WhiteSpace::BreakSpaces
    );
    let has_segment_break = text.as_bytes().iter().any(|&b| b == b'\r' || b == b'\x0c');

    if is_pre_like {
        if !has_segment_break {
            return Cow::Borrowed(text);
        }
        // Only segment breaks change; avoid the throwaway second `replace`.
        let mut result = String::with_capacity(text.len());
        let mut chars = text.chars().peekable();
        while let Some(c) = chars.next() {
            match c {
                '\r' => {
                    if chars.peek() == Some(&'\n') {
                        chars.next();
                    }
                    result.push('\n');
                }
                '\x0c' => result.push('\n'),
                _ => result.push(c),
            }
        }
        return Cow::Owned(result);
    }

    // `Normal`, `Nowrap` and `PreLine` all collapse runs of CSS whitespace:
    // every whitespace rune is mapped to a single `' '`. The text therefore
    // only needs rewriting when a segment break is present, when a whitespace
    // rune other than `' '` appears (tab, newline, …), or when two whitespace
    // runes are adjacent (the second would be dropped).
    let needs_rewrite = has_segment_break || {
        let mut prev_was_space = false;
        let mut rewrite = false;
        for c in text.chars() {
            let is_space = is_css_whitespace(c);
            if is_space && (prev_was_space || c != ' ') {
                rewrite = true;
                break;
            }
            prev_was_space = is_space;
        }
        rewrite
    };

    if !needs_rewrite {
        return Cow::Borrowed(text);
    }

    let text = text.replace("\r\n", "\n");
    let text = text.replace(['\r', '\x0c'], "\n");

    let mut result = String::new();
    let mut prev_was_space = false;

    for c in text.chars() {
        match white_space {
            WhiteSpace::Normal | WhiteSpace::Nowrap => {
                if is_css_whitespace(c) {
                    if !prev_was_space {
                        result.push(' ');
                    }
                    prev_was_space = true;
                } else {
                    result.push(c);
                    prev_was_space = false;
                }
            }

            WhiteSpace::Pre | WhiteSpace::PreWrap | WhiteSpace::BreakSpaces => {
                result.push(c);
                prev_was_space = false;
            }

            WhiteSpace::PreLine => {
                if c == '\n' {
                    result.push('\n');
                    prev_was_space = false;
                } else if is_css_whitespace(c) {
                    if !prev_was_space {
                        result.push(' ');
                    }
                    prev_was_space = true;
                } else {
                    result.push(c);
                    prev_was_space = false;
                }
            }
        }
    }

    Cow::Owned(result)
}

/// Measure text and create a [`TextFlowLayouter`] + [`NodeKind::Text`].
///
/// Falls back to unshaped measurement when shaped measurement fails.
fn create_text_node(
    text: String,
    text_style: TextStyle,
    text_flow_style: TextFlowStyle,
    measurer: &dyn text::TextMeasurer,
) -> (TextFlowLayouter, NodeKind) {
    perf_scope!(measure);
    let request = text::TextMeasureRequest {
        text: text.clone(),
        attribute: text::TextAttribute {
            style: text_style.clone(),
            flow_style: text_flow_style,
        },
    };
    let clusters = measurer.measure_shaped(&request).unwrap_or_else(|_| {
        measurer
            .measure(&request)
            .map(|ms| {
                let mut offset = 0usize;
                ms.into_iter()
                    .map(|f| {
                        // find this fragment's byte offset in the original text
                        let pos = text[offset..]
                            .find(&f.text)
                            .map(|p| offset + p)
                            .unwrap_or(offset);
                        offset = pos + f.text.len();
                        GlyphCluster {
                            byte_offset: pos,
                            width: f.width,
                            break_allowed: true,
                        }
                    })
                    .collect()
            })
            .unwrap_or_default()
    });
    profile_log!(
        target: "Layouter",
        log::Level::Info,
        "measure_shaped: text={:?} len={} took={:?}",
        crate::profile::text_preview(&text),
        text.len(),
        measure.elapsed(),
    );

    let layouter = TextFlowLayouter::new(text.clone(), text_flow_style, clusters);
    let kind = NodeKind::Text {
        text,
        style: text_style,
        flow_style: text_flow_style,
        text_id: layouter.id,
    };
    (layouter, kind)
}

/// Builds the generated-content box for a `::before`/`::after` rule block.
///
/// The pseudo-element box is an inline flow-root styled by the cascaded
/// declarations. `content` supplies generated text (`none` or an empty string
/// produces no box unless the pseudo has a background/border/dimensions, which
/// pure-CSS icons such as the Google logo rely on). Returns `None` when the
/// pseudo generates nothing to render.
#[allow(clippy::too_many_arguments)]
fn build_pseudo_slot(
    declarations: &Properties,
    custom_properties: &Properties,
    inherited_text_style: &TextStyle,
    inherited_text_flow_style: TextFlowStyle,
    color_scheme: ColorScheme,
    measurer: &dyn text::TextMeasurer,
    images: &HashMap<String, Image>,
    get_attr: &dyn Fn(&str) -> Option<String>,
    counter_state: &HashMap<String, i32>,
) -> Option<ChildSlot> {
    let mut style = Style::default();
    let mut container_style = ContainerStyle::default();
    let mut text_style = inherited_text_style.clone();
    let mut text_flow_style = inherited_text_flow_style;
    let mut overflow = Overflow::default();

    // The cascade map is already ordered per-property; re-sort by source order
    // so shorthand/longhand interactions apply deterministically.
    let mut cascade: Vec<_> = declarations.values().collect();
    cascade.sort_by_key(|declaration| declaration.order);

    let mut content: Option<CssValue> = None;
    for declaration in cascade {
        if declaration.name.starts_with("--") {
            continue;
        }
        if declaration.name == "content" {
            content = Some(declaration.value.clone());
            continue;
        }
        let Some(value) = DeclarationResolver::resolve_var(
            &declaration.value,
            custom_properties,
            &mut HashSet::new(),
        ) else {
            continue;
        };
        apply_declaration(
            &declaration.name,
            &value,
            &mut style,
            &mut container_style,
            &mut text_style,
            &mut text_flow_style,
            &Style::default(),
            &ContainerStyle::default(),
            inherited_text_style,
            &inherited_text_flow_style,
            &mut overflow,
            color_scheme,
        );
    }

    // Generated content: resolve `content` value to text, or `none`/`normal`/omitted.
    let content_text = match &content {
        None => String::new(),
        Some(CssValue::Keyword(k))
            if k.eq_ignore_ascii_case("none") || k.eq_ignore_ascii_case("normal") =>
        {
            String::new()
        }
        Some(CssValue::Keyword(k)) => match k.to_ascii_lowercase().as_str() {
            "open-quote" => "\"".to_string(),
            "close-quote" => "\"".to_string(),
            "no-open-quote" | "no-close-quote" => String::new(),
            _ => String::new(),
        },
        Some(CssValue::String(s)) => s.clone(),
        Some(CssValue::Function(fn_name, args)) => {
            resolve_content_function(fn_name, args, get_attr, counter_state)
        }
        Some(CssValue::List(items)) => {
            // `content: "a" attr(data-label) "b"` concatenates strings and
            // resolved function values.
            let mut joined = String::new();
            for item in items {
                match item {
                    CssValue::String(s) => joined.push_str(s.as_str()),
                    CssValue::Keyword(k) => match k.to_ascii_lowercase().as_str() {
                        "open-quote" => joined.push_str("\""),
                        "close-quote" => joined.push_str("\""),
                        "no-open-quote" | "no-close-quote" => {}
                        _ => {}
                    },
                    CssValue::Function(fn_name, args) => {
                        let resolved =
                            resolve_content_function(fn_name, args, get_attr, counter_state);
                        if !resolved.is_empty() {
                            joined.push_str(&resolved);
                        }
                    }
                    _ => {}
                }
            }
            joined
        }
        Some(_) => String::new(),
    };

    // `content: url(...)` renders the image as a background layer on the
    // pseudo-element, so it paints even when there is no text content.
    if let Some(CssValue::Function(fn_name, args)) = &content
        && fn_name.eq_ignore_ascii_case("url")
    {
        for arg_group in args.iter().flatten() {
            if let CssValue::String(source) = arg_group {
                container_style.background.layers.push(
                    crate::engine::layouter::types::BackgroundLayer {
                        image: Some(
                            crate::engine::layouter::types::BackgroundImage::Image {
                                source: source.clone(),
                                image: None,
                            },
                        ),
                        position: Default::default(),
                        size: Default::default(),
                        repeat: Default::default(),
                    },
                );
                break;
            }
        }
    }

    let has_styling = container_style.background.color.is_some_and(|c| c.3 > 0)
        || container_style
            .background
            .layers
            .iter()
            .any(|layer| layer.image.is_some())
        || matches!(
            (&style.size.width, &style.size.height),
            (LengthOrAuto::Length(l), _) | (_, LengthOrAuto::Length(l))
                if !matches!(l, Length::Px(0.0))
        )
        || [
            &style.spacing.padding_top,
            &style.spacing.padding_right,
            &style.spacing.padding_bottom,
            &style.spacing.padding_left,
            &style.spacing.border_top,
            &style.spacing.border_right,
            &style.spacing.border_bottom,
            &style.spacing.border_left,
        ]
        .iter()
        .any(|p| !matches!(p, Length::Px(0.0)));

    if content_text.is_empty() && !has_styling {
        return None;
    }

    // Resolve line-height from the pseudo's own text-flow style.
    style.line_height = match text_flow_style.line_height {
        LineHeight::Number(factor) => Length::Px(text_flow_style.font_size * factor),
        LineHeight::Normal => Length::Px(text_flow_style.font_size * DEFAULT_LINE_FACTOR),
        LineHeight::Px(px) => Length::Px(px),
    };

    // Attach the decoded background image, mirroring element handling.
    for layer in &mut container_style.background.layers {
        if let Some(crate::engine::layouter::types::BackgroundImage::Image { source, image }) =
            &mut layer.image
        {
            *image = images.get(source).cloned();
        }
    }

    // The generated box is an inline-level flow root (inline-block): it sits
    // on the originating element's line and shrink-wraps its content.
    style.display = Display::OutsideInner {
        outer: OuterDisplay::Inline,
        inner: InnerDisplay::FlowRoot,
    };

    let mut inline_style = style.clone();
    let mut slot_children: Vec<LayoutChild> = Vec::new();
    let mut slot_info: Vec<InfoNode> = Vec::new();

    if !content_text.is_empty() {
        let content_text = normalize_whitespace(&content_text, text_flow_style.white_space);
        let content_text = match text_style.text_transform {
            TextTransform::None => content_text.into_owned(),
            TextTransform::Uppercase => content_text.to_ascii_uppercase(),
            TextTransform::Lowercase => content_text.to_ascii_lowercase(),
        };
        let (layouter, kind) =
            create_text_node(content_text, text_style.clone(), text_flow_style, measurer);
        inline_style.display = Display::OutsideInner {
            outer: OuterDisplay::Inline,
            inner: InnerDisplay::Flow,
        };
        slot_children.push((inline_style, layouter).into());
        slot_info.push(InfoNode {
            kind,
            children: Vec::new(),
            dom_id: None,
        });
    }

    let layout = LayoutNode::with_children(style, slot_children);
    let info = InfoNode {
        kind: NodeKind::Container {
            scroll_x: overflow.x,
            scroll_y: overflow.y,
            scroll_offset_x: 0.0,
            scroll_offset_y: 0.0,
            style: container_style,
            role: ContainerRole::Normal,
        },
        children: slot_info,
        dom_id: None,
    };
    Some(ChildSlot::Inline(layout.into(), Box::new(info)))
}

/// Resolves a `content()` function value to a string.
///
/// Supported functions:
/// - `attr(attr-name)` — the element's attribute value, or empty if absent.
/// - `counter(counter-name)` / `counter(counter-name, style)` — current counter value.
/// - `counters(counter-name, separator)` — current counter value (simple impl).
/// - `url(...)` — image source; handled separately as a replaced element.
fn resolve_content_function(
    fn_name: &str,
    args: &[Vec<CssValue>],
    get_attr: &dyn Fn(&str) -> Option<String>,
    counter_state: &HashMap<String, i32>,
) -> String {
    let flat: Vec<&CssValue> = args.iter().flatten().collect();

    match fn_name {
        "attr" => {
            if let Some(CssValue::String(attr_name)) = flat.first() {
                get_attr(attr_name).unwrap_or_default()
            } else if let Some(CssValue::Keyword(attr_name)) = flat.first() {
                get_attr(attr_name).unwrap_or_default()
            } else {
                String::new()
            }
        }
        "counter" => {
            if let Some(CssValue::Keyword(name)) = flat.first() {
                counter_state
                    .get(name.as_str())
                    .map(|v| v.to_string())
                    .unwrap_or_else(|| "0".to_string())
            } else {
                "0".to_string()
            }
        }
        "counters" => {
            if let Some(CssValue::Keyword(name)) = flat.first() {
                counter_state
                    .get(name.as_str())
                    .map(|v| v.to_string())
                    .unwrap_or_else(|| "0".to_string())
            } else {
                "0".to_string()
            }
        }
        "url" => {
            String::new()
        }
        _ => String::new(),
    }
}

/// Parse `counter-reset` value into a list of (name, value) pairs.
///
/// Examples:
/// - `counter-reset: section` → [("section", 0)]
/// - `counter-reset: section 5` → [("section", 5)]
/// - `counter-reset: section 5 subsection 0` → [("section", 5), ("subsection", 0)]
/// - `counter-reset: none` → []
fn parse_counter_reset(value: &CssValue) -> Vec<(String, i32)> {
    match value {
        CssValue::Keyword(k) if k.eq_ignore_ascii_case("none") => Vec::new(),
        CssValue::List(items) => {
            let mut result = Vec::new();
            let mut iter = items.iter();
            while let Some(name_val) = iter.next() {
                let name = match name_val {
                    CssValue::Keyword(k) => k.to_string(),
                    _ => continue,
                };
                let val = match iter.next() {
                    Some(CssValue::Number(n)) => *n as i32,
                    _ => 0,
                };
                result.push((name, val));
            }
            result
        }
        CssValue::Keyword(k) => {
            if k.eq_ignore_ascii_case("none") {
                Vec::new()
            } else {
                vec![(k.to_string(), 0)]
            }
        }
        _ => Vec::new(),
    }
}

/// Parse `counter-increment` value into a list of (name, amount) pairs.
///
/// Examples:
/// - `counter-increment: section` → [("section", 1)]
/// - `counter-increment: section 2` → [("section", 2)]
/// - `counter-increment: section 2 subsection -1` → [("section", 2), ("subsection", -1)]
fn parse_counter_increment(value: &CssValue) -> Vec<(String, i32)> {
    match value {
        CssValue::Keyword(k) if k.eq_ignore_ascii_case("none") => Vec::new(),
        CssValue::List(items) => {
            let mut result = Vec::new();
            let mut iter = items.iter();
            while let Some(name_val) = iter.next() {
                let name = match name_val {
                    CssValue::Keyword(k) => k.to_string(),
                    _ => continue,
                };
                let val = match iter.next() {
                    Some(CssValue::Number(n)) => *n as i32,
                    _ => 1,
                };
                result.push((name, val));
            }
            result
        }
        CssValue::Keyword(k) => {
            if k.eq_ignore_ascii_case("none") {
                Vec::new()
            } else {
                vec![(k.to_string(), 1)]
            }
        }
        _ => Vec::new(),
    }
}

// ── Color scheme resolution ─────────────────────────────────────────────────

/// How an element's `color-scheme` property constrains its used color scheme.
enum ColorSchemePref {
    /// `normal` or unset: fall back to the inherited (or system) scheme.
    Normal,
    Light,
    Dark,
    /// Both `light` and `dark` listed: follow the system preference.
    Both,
}

/// Parses the winning `color-scheme` declaration into a preference.
fn color_scheme_pref(value: Option<&CssValue>) -> ColorSchemePref {
    let Some(value) = value else {
        return ColorSchemePref::Normal;
    };
    let mut light = false;
    let mut dark = false;
    let mut has = false;
    let mut push = |keyword: &str| {
        has = true;
        match keyword {
            "light" => light = true,
            "dark" => dark = true,
            // `only`, `normal`, unknown keywords are ignored here.
            _ => {}
        }
    };
    match value {
        CssValue::Keyword(k) => push(k),
        CssValue::List(items) => {
            for item in items {
                if let CssValue::Keyword(k) = item {
                    push(k);
                }
            }
        }
        _ => {}
    }
    if !has {
        ColorSchemePref::Normal
    } else if light && dark {
        ColorSchemePref::Both
    } else if light {
        ColorSchemePref::Light
    } else if dark {
        ColorSchemePref::Dark
    } else {
        ColorSchemePref::Normal
    }
}

/// Computes the used color scheme of an element from its `color-scheme`
/// declaration, the inherited scheme, and the system preference.
fn resolve_used_color_scheme(
    declaration: Option<&CssValue>,
    inherited: ColorScheme,
    system: ColorScheme,
) -> ColorScheme {
    match color_scheme_pref(declaration) {
        ColorSchemePref::Normal => inherited,
        ColorSchemePref::Light => ColorScheme::Light,
        ColorSchemePref::Dark => ColorScheme::Dark,
        ColorSchemePref::Both => system,
    }
}

// ── CSS candidate collection ────────────────────────────────────────────────

/// Aggregated CSS candidate-matching statistics for a single layout build.
#[cfg(any(feature = "profile", debug_assertions))]
#[derive(Default)]
struct CandidateMetrics {
    elements_checked: u64,
    candidates_examined: u64,
    selectors_matched: u64,
    query_candidates_time: std::time::Duration,
    selector_match_time: std::time::Duration,
    cascade_insert_time: std::time::Duration,
}

fn collect_candidates(
    rule_set: &RuleSet,
    chain: &ElementChain,
    node_id: NodeId,
    mut match_cache: Option<&mut SelectorMatchCache>,
    #[cfg(any(feature = "profile", debug_assertions))] stats: &mut CandidateMetrics,
) -> (Properties, Properties, HashMap<PseudoElement, Properties>) {
    let mut properties = HashMap::new();
    let mut custom_properties = HashMap::new();
    let mut pseudo_properties: HashMap<PseudoElement, Properties> = HashMap::new();

    let element = match chain.first() {
        Some(el) => el,
        None => return (properties, custom_properties, pseudo_properties),
    };

    #[cfg(any(feature = "profile", debug_assertions))]
    {
        stats.elements_checked += 1;
    }

    // The candidate iterator is lazy; under profiling it is materialized so
    // query time is measured separately from selector matching.
    perf_scope!(query);
    #[cfg(any(feature = "profile", debug_assertions))]
    let candidates_iter: Vec<_> = rule_set.query_candidates(element).collect();
    #[cfg(not(any(feature = "profile", debug_assertions)))]
    let candidates_iter = rule_set.query_candidates(element);
    #[cfg(any(feature = "profile", debug_assertions))]
    {
        stats.query_candidates_time += query.elapsed();
    }

    for group in candidates_iter {
        #[cfg(any(feature = "profile", debug_assertions))]
        {
            stats.candidates_examined += 1;
        }

        // Declarations sharing an identical selector are grouped, so the
        // (comparatively expensive) selector walk happens once per group.
        perf_scope!(sel_match);
        let matches_sel = match match_cache.as_deref_mut() {
            Some(cache) => {
                cache.get_or_insert(&group.selector, node_id, || group.selector.matches(chain))
            }
            None => group.selector.matches(chain),
        };
        #[cfg(any(feature = "profile", debug_assertions))]
        {
            stats.selector_match_time += sel_match.elapsed();
            if matches_sel {
                stats.selectors_matched += 1;
            }
        }
        if !matches_sel {
            continue;
        }

        for &decl_idx in &group.decls {
            let decl = &rule_set.declarations()[decl_idx];

            let target: &mut Properties = if decl.pseudo != PseudoElement::None {
                pseudo_properties.entry(decl.pseudo).or_default()
            } else if decl.name.starts_with("--") {
                &mut custom_properties
            } else {
                &mut properties
            };

            perf_scope!(cascade);
            let should_replace = match target.get(&decl.name) {
                Some(current) => decl.outranks(current),
                None => true,
            };

            if should_replace {
                target.insert(decl.name.clone(), decl.clone());
            }

            #[cfg(any(feature = "profile", debug_assertions))]
            {
                stats.cascade_insert_time += cascade.elapsed();
            }
        }
    }

    (properties, custom_properties, pseudo_properties)
}