tessera_ui/component_tree/

node.rs

use std::{
    collections::HashMap,
    num::NonZeroUsize,
    ops::{Add, AddAssign, Deref},
    sync::Arc,
};

use indextree::NodeId;
use smallvec::SmallVec;
use tracing::debug;
use winit::window::CursorIcon;

use crate::{
    ClipRegion, Px,
    accessibility::{AccessibilityActionHandler, AccessibilityNode, StoredSemantics},
    cursor::{CursorEventContent, PointerChange},
    focus::{
        FocusDirection, FocusRegistration, FocusRequester, FocusRevealRequest, FocusState,
        FocusTraversalPolicy,
    },
    layout::{
        ChildMeasure, DefaultLayoutNode, LayoutInput, LayoutModifierDyn, LayoutModifierHandle,
        LayoutResult, NoopDrawModifier, PlacementResult, PlacementScope,
    },
    modifier::{
        DrawModifierNode, LayoutModifierChild, LayoutModifierInput, LayoutModifierNode, Modifier,
    },
    prop::CallbackWith,
    px::{PxPosition, PxRect, PxSize},
    render_graph::RenderFragment,
    runtime::{
        RuntimePhase, push_current_component_instance_key,
        push_current_node_with_instance_logic_id, push_measured_node_instance_key, push_phase,
    },
    time::Instant,
};

use super::{
    DrawLayoutBounds, LayoutContext, LayoutSnapshotEntry, NodeDrawLayout,
    constraint::{Constraint, ParentConstraint},
    nearest_replay_boundary_instance_key,
    node_map::DenseNodeMap,
};

#[cfg(feature = "profiling")]
use crate::profiler::{Phase as ProfilerPhase, ScopeGuard as ProfilerScopeGuard};

/// A ComponentNode is a node in the component tree.
/// It represents all information about a component.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub(crate) enum NodeRole {
    Composition,
    Layout,
}

pub(crate) struct ComponentNode {
    /// Component function's name, for debugging purposes.
    pub(crate) fn_name: &'static str,
    /// Whether this tree node represents a composition boundary or an explicit
    /// layout node.
    pub(crate) role: NodeRole,
    pub(super) layout_children: Option<LayoutChildren>,
    pub(super) layout_children_dirty: bool,
    pub(crate) sibling_index: Option<NonZeroUsize>,
    #[cfg(feature = "profiling")]
    pub(crate) subtree_len: usize,
    pub(crate) children_scale: f32,
    /// Stable logic identifier of this concrete component instance.
    pub(crate) instance_logic_id: u64,
    /// Stable instance identifier for this node in the current frame.
    pub(crate) instance_key: u64,
    pub(crate) interaction: Option<Box<NodeInteraction>>,
    pub(crate) layout_coordinate_space: bool,
    /// Node-local modifier chain attached during build.
    pub(crate) modifier: Modifier,
    /// The unified layout node applied at the innermost layer.
    pub(crate) layout_node: Box<dyn LayoutModifierDyn>,
    pub(crate) layout_input_policy: LayoutModifierHandle,
    /// Draw modifier node used to record draw and compute commands.
    pub(crate) draw_node: Box<dyn DrawModifierNode>,
    pub(crate) replay_boundary: bool,
    /// Whether props are equal to the previous frame snapshot.
    pub(crate) props_unchanged_from_previous: bool,
}

impl ComponentNode {
    pub(crate) fn new(fn_name: &'static str, role: NodeRole) -> Self {
        Self {
            fn_name,
            role,
            layout_children: None,
            layout_children_dirty: true,
            sibling_index: None,
            #[cfg(feature = "profiling")]
            subtree_len: 1,
            children_scale: 1.0,
            instance_logic_id: 0,
            instance_key: 0,
            interaction: None,
            layout_coordinate_space: false,
            modifier: Modifier::default(),
            layout_node: Box::new(DefaultLayoutNode),
            layout_input_policy: LayoutModifierHandle::default(),
            draw_node: Box::new(NoopDrawModifier),
            replay_boundary: false,
            props_unchanged_from_previous: false,
        }
    }

    pub(crate) fn interaction(&self) -> &NodeInteraction {
        static EMPTY: NodeInteraction = NodeInteraction::EMPTY;
        self.interaction.as_deref().unwrap_or(&EMPTY)
    }

    pub(crate) fn layout_policy(&self) -> &dyn LayoutModifierDyn {
        self.layout_input_policy.as_policy()
    }

    pub(crate) fn interaction_mut(&mut self) -> &mut NodeInteraction {
        self.interaction
            .get_or_insert_with(|| Box::new(NodeInteraction::EMPTY))
    }
}

pub(crate) struct NodeInteraction {
    /// Pointer input handlers for capture stage (root to leaf).
    pub(crate) pointer_preview_handlers: Vec<Box<PointerInputHandlerFn>>,
    /// Pointer input handlers for bubble stage (leaf to root).
    pub(crate) pointer_handlers: Vec<Box<PointerInputHandlerFn>>,
    /// Pointer input handlers for final stage (root to leaf).
    pub(crate) pointer_final_handlers: Vec<Box<PointerInputHandlerFn>>,
    /// Keyboard input handlers for preview stage (root to leaf).
    pub(crate) keyboard_preview_handlers: Vec<Box<KeyboardInputHandlerFn>>,
    /// Keyboard input handlers for bubble stage (leaf to root).
    pub(crate) keyboard_handlers: Vec<Box<KeyboardInputHandlerFn>>,
    /// IME input handlers for preview stage (root to leaf).
    pub(crate) ime_preview_handlers: Vec<Box<ImeInputHandlerFn>>,
    /// IME input handlers for bubble stage (leaf to root).
    pub(crate) ime_handlers: Vec<Box<ImeInputHandlerFn>>,
    /// Optional focus requester bound to this component node.
    pub(crate) focus_requester_binding: Option<FocusRequester>,
    /// Optional focus registration attached to this component node.
    pub(crate) focus_registration: Option<FocusRegistration>,
    /// Optional fallback target used when a focus scope restores focus.
    pub(crate) focus_restorer_fallback: Option<FocusRequester>,
    /// Optional traversal policy used when directional navigation starts inside
    /// this focus group or scope.
    pub(crate) focus_traversal_policy: Option<FocusTraversalPolicy>,
    /// Optional callback invoked when the node's focus state changes.
    pub(crate) focus_changed_handler: Option<FocusChangedHandler>,
    /// Optional callback invoked when the node participates in a focus event.
    pub(crate) focus_event_handler: Option<FocusEventHandler>,
    /// Optional callback used to expand virtualized content for focus search.
    pub(crate) focus_beyond_bounds_handler: Option<FocusBeyondBoundsHandler>,
    /// Optional callback used to reveal the focused rectangle inside a
    /// container.
    pub(crate) focus_reveal_handler: Option<FocusRevealHandler>,
    /// Callbacks notified when this node's window rectangle changes.
    pub(crate) globally_positioned_handlers: Vec<GloballyPositionedHandler>,
}

impl NodeInteraction {
    const EMPTY: Self = Self {
        pointer_preview_handlers: Vec::new(),
        pointer_handlers: Vec::new(),
        pointer_final_handlers: Vec::new(),
        keyboard_preview_handlers: Vec::new(),
        keyboard_handlers: Vec::new(),
        ime_preview_handlers: Vec::new(),
        ime_handlers: Vec::new(),
        focus_requester_binding: None,
        focus_registration: None,
        focus_restorer_fallback: None,
        focus_traversal_policy: None,
        focus_changed_handler: None,
        focus_event_handler: None,
        focus_beyond_bounds_handler: None,
        focus_reveal_handler: None,
        globally_positioned_handlers: Vec::new(),
    };

    pub(super) fn has_pointer_handlers(&self) -> bool {
        !self.pointer_preview_handlers.is_empty()
            || !self.pointer_handlers.is_empty()
            || !self.pointer_final_handlers.is_empty()
    }

    pub(super) fn observes_input_geometry(&self) -> bool {
        self.has_pointer_handlers()
            || !self.keyboard_preview_handlers.is_empty()
            || !self.keyboard_handlers.is_empty()
            || !self.ime_preview_handlers.is_empty()
            || !self.ime_handlers.is_empty()
            || self.focus_registration.is_some()
    }
}

#[derive(Clone)]
pub(super) struct InputTransforms {
    pub(super) parent: crate::LocalToWindow,
    positions: Arc<[PxPosition]>,
}

impl InputTransforms {
    pub(super) fn get(&self, index: usize) -> Option<crate::LocalToWindow> {
        self.positions
            .get(index)
            .map(|position| self.parent.with_local_origin(*position))
    }
}

/// Contains metadata of the component node.
pub(crate) struct ComponentNodeMetaData {
    pub(super) prepared_layout: Option<super::PreparedLayoutMetadata>,
    pub(super) clip_regions: Option<Box<ClipRegions>>,
    pub(super) geometry_initialized: bool,
    pub(super) observes_geometry: bool,
    pub(super) observes_size: bool,
    pub(super) paint_dirty: bool,
    accessibility_written: bool,
    /// The computed data (size) of the node.
    /// None if the node is not computed yet.
    pub computed_data: Option<ComputedData>,
    pub draw_layout: NodeDrawLayout,
    /// Whether the most recent visit reused this node's measured layout.
    pub layout_cache_hit: bool,
    /// Placement order among siblings within the parent layout result.
    pub placement_order: Option<u64>,
    /// The node's start position, relative to its parent.
    /// None if the node is not placed yet.
    pub rel_position: Option<PxPosition>,
    /// The node's start position, relative to the root window.
    /// Before placement modifiers are applied.
    /// This will be computed during drawing command's generation.
    /// None if the node is not drawn yet.
    pub base_abs_position: Option<PxPosition>,
    pub local_to_window: Option<crate::LocalToWindow>,
    pub(super) input_transforms: Option<Box<InputTransforms>>,
    pub event_clip_bounds: Option<crate::FloatRect>,
    /// The node's start position, relative to the root window.
    /// After placement modifiers are applied.
    /// This will be computed during drawing command's generation.
    /// None if the node is not drawn yet.
    pub abs_position: Option<PxPosition>,
    /// Render fragment associated with this node.
    ///
    /// Commands are collected during the record phase and merged into the frame
    /// graph during rendering.
    pub(crate) fragment: RenderFragment,
    /// Whether this node clips its children.
    pub clips_children: bool,
    pub(crate) has_shape_clipping: bool,
    /// Opacity multiplier applied to this node and its descendants.
    pub opacity: f32,
    /// Accessibility information for this node.
    pub accessibility: Option<StoredSemantics>,
    /// Handler for accessibility actions on this node.
    pub accessibility_action_handler: Option<AccessibilityActionHandler>,
}

#[derive(Default)]
pub(super) struct ClipRegions {
    local: Option<ClipRegion>,
    prepared: Option<ClipRegion>,
}

impl ComponentNodeMetaData {
    /// Creates a new `ComponentNodeMetaData` with default values.
    pub fn none() -> Self {
        Self {
            prepared_layout: None,
            clip_regions: None,
            geometry_initialized: false,
            observes_geometry: false,
            observes_size: false,
            paint_dirty: true,
            accessibility_written: false,
            computed_data: None,
            draw_layout: NodeDrawLayout::default(),
            layout_cache_hit: false,
            placement_order: None,
            rel_position: None,
            base_abs_position: None,
            local_to_window: None,
            input_transforms: None,
            event_clip_bounds: None,
            abs_position: None,
            fragment: RenderFragment::default(),
            clips_children: false,
            has_shape_clipping: false,
            opacity: 1.0,
            accessibility: None,
            accessibility_action_handler: None,
        }
    }

    pub(crate) fn set_accessibility(
        &mut self,
        node: Option<AccessibilityNode>,
        handler: Option<AccessibilityActionHandler>,
    ) {
        if let Some(node) = node {
            StoredSemantics::write(&mut self.accessibility, node);
        } else {
            self.accessibility = None;
        }
        self.accessibility_action_handler = handler;
        self.accessibility_written = true;
    }

    pub(super) fn begin_accessibility_rebuild(&mut self) {
        self.accessibility_written = false;
        self.accessibility_action_handler = None;
    }

    pub(super) fn finish_accessibility_rebuild(&mut self) {
        if !self.accessibility_written {
            self.accessibility = None;
        }
    }

    /// Returns a mutable render fragment for this node.
    pub fn fragment_mut(&mut self) -> &mut RenderFragment {
        &mut self.fragment
    }

    pub(crate) fn event_clip_rect(&self) -> Option<PxRect> {
        self.event_clip_bounds.map(crate::FloatRect::outward)
    }

    pub(super) fn set_input_transforms(
        &mut self,
        parent: crate::LocalToWindow,
        positions: Vec<PxPosition>,
    ) {
        if positions.is_empty() {
            self.input_transforms = None;
        } else if let Some(transforms) = &mut self.input_transforms {
            transforms.parent = parent;
            if transforms.positions.as_ref() != positions.as_slice() {
                transforms.positions = positions.into();
            }
        } else {
            self.input_transforms = Some(Box::new(InputTransforms {
                parent,
                positions: positions.into(),
            }));
        }
    }

    pub(crate) fn clip_region(&self) -> Option<&ClipRegion> {
        self.clip_regions.as_ref()?.local.as_ref()
    }

    pub(crate) fn set_clip_region(&mut self, region: Option<ClipRegion>) {
        if region.is_some() {
            self.clip_regions.get_or_insert_with(Box::default).local = region;
        } else if let Some(regions) = &mut self.clip_regions {
            regions.local = None;
        }
    }

    pub(super) fn prepared_clip_region(&self) -> Option<&ClipRegion> {
        self.clip_regions.as_ref()?.prepared.as_ref()
    }

    pub(super) fn set_prepared_clip_region(&mut self, region: Option<ClipRegion>) {
        if let Some(regions) = &mut self.clip_regions {
            if regions.prepared != region {
                regions.prepared = region;
            }
            if regions.local.is_none() && region.is_none() {
                self.clip_regions = None;
            }
        }
    }
}

impl Default for ComponentNodeMetaData {
    fn default() -> Self {
        Self::none()
    }
}

pub(crate) fn sibling_index(id: NodeId, tree: &ComponentNodeTree) -> usize {
    tree[id].get().sibling_index.map_or_else(
        || id.preceding_siblings(tree).skip(1).count(),
        |index| index.get() - 1,
    )
}

#[derive(Clone)]
pub(crate) enum LayoutChildren {
    Empty,
    One(NodeId),
    Shared(Arc<[NodeId]>),
}

impl LayoutChildren {
    pub(super) fn new(children: &[NodeId]) -> Self {
        match children {
            [] => Self::Empty,
            [child] => Self::One(*child),
            _ => Self::Shared(children.into()),
        }
    }
}

impl AsRef<[NodeId]> for LayoutChildren {
    fn as_ref(&self) -> &[NodeId] {
        self
    }
}

impl Deref for LayoutChildren {
    type Target = [NodeId];

    fn deref(&self) -> &[NodeId] {
        match self {
            Self::Empty => &[],
            Self::One(child) => std::slice::from_ref(child),
            Self::Shared(children) => children,
        }
    }
}

pub(crate) fn direct_layout_children(node_id: NodeId, tree: &ComponentNodeTree) -> LayoutChildren {
    if let Some(children) = tree
        .get(node_id)
        .and_then(|node| node.get().layout_children.as_ref())
    {
        return children.clone();
    }
    fn collect(node_id: NodeId, tree: &ComponentNodeTree, output: &mut SmallVec<[NodeId; 4]>) {
        let Some(node_ref) = tree.get(node_id) else {
            return;
        };
        if node_ref.get().role == NodeRole::Layout {
            output.push(node_id);
            return;
        }

        for child_id in node_id.children(tree) {
            collect(child_id, tree, output);
        }
    }

    let mut children = SmallVec::new();
    for child_id in node_id.children(tree) {
        collect(child_id, tree, &mut children);
    }
    LayoutChildren::new(&children)
}

fn reset_frame_metadata(
    node_id: NodeId,
    component_node_metadatas: &mut ComponentNodeMetaDatas,
) -> Option<ComputedData> {
    component_node_metadatas.mark_paint_dirty(node_id);
    let metadata = component_node_metadatas.entry_or_default(node_id);
    metadata.draw_layout = NodeDrawLayout::default();
    metadata.layout_cache_hit = false;
    metadata.paint_dirty = true;
    metadata.computed_data.take()
}

/// A tree of component nodes, using `indextree::Arena` for storage.
pub(crate) type ComponentNodeTree = indextree::Arena<ComponentNode>;

/// Stores component metadata for a single UI tree.
#[derive(Default)]
pub(crate) struct ComponentNodeMetaDatas {
    nodes: DenseNodeMap<ComponentNodeMetaData>,
    #[cfg(feature = "profiling")]
    pub(super) profiling_dirty: rustc_hash::FxHashSet<NodeId>,
    pub(super) geometry_visits: u64,
    pub(super) geometry_dirty: rustc_hash::FxHashSet<NodeId>,
    pub(super) geometry_changed: rustc_hash::FxHashSet<NodeId>,
    pub(super) size_changed: rustc_hash::FxHashSet<NodeId>,
    pub(super) paint_changed: rustc_hash::FxHashSet<NodeId>,
    pub(super) placement_order_dirty: rustc_hash::FxHashSet<NodeId>,
    pub(crate) placement_order_changed: rustc_hash::FxHashSet<NodeId>,
    pub(super) paint_dirty_nodes: rustc_hash::FxHashSet<NodeId>,
}

impl ComponentNodeMetaDatas {
    pub(crate) fn new() -> Self {
        Self::default()
    }

    pub(crate) fn clear(&mut self) {
        self.nodes.clear();
        #[cfg(feature = "profiling")]
        self.profiling_dirty.clear();
        self.geometry_dirty.clear();
        self.geometry_changed.clear();
        self.size_changed.clear();
        self.paint_dirty_nodes.clear();
        self.paint_changed.clear();
        self.placement_order_dirty.clear();
        self.placement_order_changed.clear();
    }

    pub(crate) fn remove(&mut self, node_id: &NodeId) -> Option<ComponentNodeMetaData> {
        #[cfg(feature = "profiling")]
        self.profiling_dirty.remove(node_id);
        self.geometry_dirty.remove(node_id);
        self.geometry_changed.remove(node_id);
        self.size_changed.remove(node_id);
        self.paint_dirty_nodes.remove(node_id);
        self.paint_changed.remove(node_id);
        self.placement_order_dirty.remove(node_id);
        self.placement_order_changed.remove(node_id);
        self.nodes.remove(*node_id)
    }

    pub(crate) fn get(&self, node_id: &NodeId) -> Option<&ComponentNodeMetaData> {
        self.nodes.get(*node_id)
    }

    pub(crate) fn get_mut(&mut self, node_id: &NodeId) -> Option<&mut ComponentNodeMetaData> {
        self.nodes.get_mut(*node_id)
    }

    pub(crate) fn entry_or_default(&mut self, node_id: NodeId) -> &mut ComponentNodeMetaData {
        if let Some(previous) = self.nodes.id_at_slot(node_id) {
            if previous == node_id {
                return self.nodes.get_mut(node_id).expect("occupied node slot");
            }
            self.remove(&previous);
        }
        self.geometry_dirty.insert(node_id);
        self.paint_dirty_nodes.insert(node_id);
        self.nodes.insert(node_id, ComponentNodeMetaData::default())
    }

    pub(crate) fn mark_geometry_dirty(&mut self, node_id: NodeId) {
        self.geometry_dirty.insert(node_id);
    }

    pub(crate) fn mark_paint_dirty(&mut self, node_id: NodeId) {
        self.paint_dirty_nodes.insert(node_id);
        if let Some(metadata) = self.get_mut(&node_id) {
            metadata.paint_dirty = true;
        }
    }
}

/// Represents errors that can occur during node measurement.
#[derive(Debug, Clone, PartialEq)]
pub enum MeasurementError {
    /// Indicates that the specified node was not found in the component tree.
    NodeNotFoundInTree,
    /// Indicates that metadata for the specified node was not found (currently
    /// not a primary error source in measure_node).
    NodeNotFoundInMeta,
    /// Indicates that the layout policy for a node failed. Contains a string
    /// detailing the failure.
    MeasureFnFailed(String),
    /// Indicates that the measurement of a child node failed during a
    /// parent's layout calculation. Contains the `NodeId` of the child
    /// that failed.
    ChildMeasurementFailed(NodeId),
}

/// Pointer input dispatch pass.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum PointerEventPass {
    /// Dispatch from root to leaf before the main pointer pass.
    Initial,
    /// Main pointer dispatch from leaf to root.
    Main,
    /// Final pointer dispatch from root to leaf.
    Final,
}

/// Pointer-specific input handler.
pub type PointerInputHandlerFn = dyn Fn(PointerInput) + Send + Sync;
/// Keyboard-specific input handler.
pub type KeyboardInputHandlerFn = dyn Fn(KeyboardInput) + Send + Sync;
/// IME-specific input handler.
pub type ImeInputHandlerFn = dyn Fn(ImeInput) + Send + Sync;
/// Focus-changed callback attached to a component node.
pub type FocusChangedHandler = CallbackWith<FocusState>;
/// Focus-event callback attached to a component node.
pub type FocusEventHandler = CallbackWith<FocusState>;
/// Beyond-bounds focus callback attached to a virtualized container node.
pub type FocusBeyondBoundsHandler = CallbackWith<FocusDirection, bool>;
/// Reveal callback attached to a scrollable container node.
pub type FocusRevealHandler = CallbackWith<FocusRevealRequest, bool>;
/// Callback invoked after a layout's observed geometry changes.
#[derive(Clone, Copy, PartialEq)]
pub enum GloballyPositionedHandler {
    Pixels(CallbackWith<PxRect>),
    Precise(CallbackWith<crate::FloatRect>),
    Transform(CallbackWith<crate::LocalToWindow>),
    Coordinates(CallbackWith<crate::LayoutCoordinates>),
    /// Observes the window-space rectangle remaining after rectangular
    /// clipping.
    Visible(CallbackWith<Option<crate::FloatRect>>),
    /// Observes bounds in the closest declared layout coordinate space.
    InSpace(CallbackWith<crate::FloatRect>),
    /// Observes measured dimensions in local layout units.
    Size(CallbackWith<PxSize>),
}

#[derive(Clone, Copy)]
pub(crate) struct GeometryObservation {
    pub rounded: PxRect,
    pub precise: crate::FloatRect,
    pub transform: crate::LocalToWindow,
    pub coordinates: crate::LayoutCoordinates,
    pub in_space: crate::FloatRect,
    pub visible: Option<crate::FloatRect>,
}

impl GloballyPositionedHandler {
    pub(crate) fn changed(self, previous: GeometryObservation, next: GeometryObservation) -> bool {
        match self {
            Self::Pixels(_) => previous.rounded != next.rounded,
            Self::Precise(_) => previous.precise != next.precise,
            Self::Transform(_) => previous.transform != next.transform,
            Self::Coordinates(_) => previous.coordinates != next.coordinates,
            Self::Visible(_) => previous.visible != next.visible,
            Self::InSpace(_) => previous.in_space != next.in_space,
            Self::Size(_) => previous.coordinates.local_size != next.coordinates.local_size,
        }
    }

    pub(crate) fn call(self, geometry: GeometryObservation) {
        match self {
            Self::Pixels(handler) => handler.call(geometry.rounded),
            Self::Precise(handler) => handler.call(geometry.precise),
            Self::Transform(handler) => handler.call(geometry.transform),
            Self::Coordinates(handler) => handler.call(geometry.coordinates),
            Self::Visible(handler) => handler.call(geometry.visible),
            Self::InSpace(handler) => handler.call(geometry.in_space),
            Self::Size(handler) => handler.call(geometry.coordinates.local_size),
        }
    }
}

/// Input for pointer handlers.
///
/// This type carries pointer event payload, local geometry, and event
/// consumption helpers. Side effects that are not pointer-specific should use
/// dedicated APIs such as semantics modifiers, hover cursor modifiers, window
/// action helpers, or the IME session bridge instead of a generic request bag.
pub struct PointerInput<'a> {
    /// Maps this handler's local geometry and displacement units into the
    /// window.
    pub local_to_window: crate::LocalToWindow,
    /// Current pointer dispatch pass.
    pub pass: PointerEventPass,
    /// The size of the component node, computed during the measure stage.
    pub computed_data: ComputedData,
    /// The position of the cursor, if available.
    /// Relative to the root position of the component.
    pub cursor_position_rel: Option<PxPosition>,
    /// Absolute cursor position in window coordinates.
    pub(crate) cursor_position_abs: &'a mut Option<PxPosition>,
    /// The current pointer sample, or an empty list during hover updates.
    pub pointer_changes: &'a mut Vec<PointerChange>,
    /// The current state of the keyboard modifiers at the time of the event.
    pub key_modifiers: winit::keyboard::ModifiersState,
    pub(crate) ime_request: &'a mut Option<ImeRequest>,
    pub(crate) request_window_drag: &'a mut Option<WindowDragRequest>,
}

impl PointerInput<'_> {
    /// Converts a displacement observed in window coordinates into local units.
    pub fn local_delta(&self, dx: f32, dy: f32) -> (f32, f32) {
        let delta = self
            .local_to_window
            .inverse_vector(PxPosition::from_f32_xy(dx, dy));
        (delta.x, delta.y)
    }

    /// Marks all current pointer changes as consumed.
    pub fn consume_pointer_changes(&mut self) {
        for change in self.pointer_changes.iter_mut() {
            if matches!(change.content, CursorEventContent::Scroll(_)) {
                continue;
            }
            change.consume();
        }
    }

    /// Returns whether any current pointer change is an unconsumed release.
    pub fn has_unconsumed_release(&self) -> bool {
        self.pointer_changes.iter().any(|change| {
            !change.is_consumed() && matches!(change.content, CursorEventContent::Released(_))
        })
    }

    /// Returns the absolute cursor position in window coordinates.
    pub fn cursor_position_abs(&self) -> Option<PxPosition> {
        *self.cursor_position_abs
    }

    /// Blocks pointer input to other components.
    ///
    /// Scroll events are never consumed, so the cursor is only hidden from
    /// ancestors when this dispatch carries non-scroll pointer changes.
    /// This keeps wheel events reaching ancestor scroll containers.
    pub fn block_cursor(&mut self) {
        let blocks_non_scroll = self.pointer_changes.iter().any(|change| {
            !change.is_consumed() && !matches!(change.content, CursorEventContent::Scroll(_))
        });
        if blocks_non_scroll {
            self.cursor_position_abs.take();
        }
        self.consume_pointer_changes();
    }

    /// Blocks pointer changes to other components.
    pub fn block_all(&mut self) {
        self.block_cursor();
    }

    /// Begins a system drag move for the current window.
    pub fn drag_window(&mut self) {
        *self.request_window_drag = Some(WindowDragRequest {
            #[cfg(target_os = "macos")]
            mouse_press: self.pointer_changes.iter().find_map(|change| {
                (change.pointer_id == crate::cursor::MOUSE_POINTER_ID
                    && matches!(
                        change.content,
                        CursorEventContent::Pressed(crate::cursor::PressKeyEventType::Left)
                    ))
                .then_some(change.timestamp)
            }),
        });
    }

    /// Returns the IME session bridge for the current frame.
    pub fn ime_session(&mut self) -> ImeSession<'_> {
        ImeSession {
            request: self.ime_request,
        }
    }
}

/// Input for keyboard handlers.
///
/// This type carries keyboard event payload and event consumption helpers.
/// IME updates, semantics, and other side effects are exposed through narrower
/// dedicated APIs rather than a general-purpose request sink.
pub struct KeyboardInput<'a> {
    /// The size of the component node, computed during the measure stage.
    pub computed_data: ComputedData,
    /// Keyboard events from the event loop, if any.
    pub keyboard_events: &'a mut Vec<crate::KeyboardEvent>,
    /// The current state of the keyboard modifiers at the time of the event.
    pub key_modifiers: winit::keyboard::ModifiersState,
    pub(crate) ime_request: &'a mut Option<ImeRequest>,
}

impl KeyboardInput<'_> {
    /// Blocks keyboard events to other components.
    pub fn block_keyboard(&mut self) {
        self.keyboard_events.clear();
    }

    /// Returns the IME session bridge for the current frame.
    pub fn ime_session(&mut self) -> ImeSession<'_> {
        ImeSession {
            request: self.ime_request,
        }
    }
}

/// Input for IME handlers.
///
/// This type carries IME event payload and event consumption helpers. IME
/// snapshot publication is performed through [`ImeSession`].
pub struct ImeInput<'a> {
    /// The size of the component node, computed during the measure stage.
    pub computed_data: ComputedData,
    /// IME events from the event loop, if any.
    pub ime_events: &'a mut Vec<winit::event::Ime>,
    pub(crate) ime_request: &'a mut Option<ImeRequest>,
}

impl ImeInput<'_> {
    /// Blocks IME events to other components.
    pub fn block_ime(&mut self) {
        self.ime_events.clear();
    }

    /// Returns the IME session bridge for the current frame.
    pub fn ime_session(&mut self) -> ImeSession<'_> {
        ImeSession {
            request: self.ime_request,
        }
    }
}

/// A collection of requests that components can make to the windowing system
/// for the current frame. This struct's lifecycle is confined to a single
/// `compute` pass.
#[derive(Default, Debug)]
pub(crate) struct WindowRequests {
    /// The cursor icon requested by a component. If multiple components request
    /// a cursor, the last one to make a request in a frame "wins", since
    /// it's executed later.
    pub cursor_icon: CursorIcon,
    /// An Input Method Editor (IME) request.
    /// If multiple components request IME, the one from the "newer" component
    /// (which is processed later in the state handling pass) will overwrite
    /// previous requests.
    pub ime_request: Option<ImeRequest>,
    pub request_window_drag: Option<WindowDragRequest>,
}

#[derive(Clone, Copy, Debug)]
pub(crate) struct WindowDragRequest {
    #[cfg(target_os = "macos")]
    pub mouse_press: Option<Instant>,
}

impl WindowRequests {
    pub(crate) fn settle(&mut self, mut next: Self) {
        next.request_window_drag = next.request_window_drag.or(self.request_window_drag);
        if let (Some(previous), Some(request)) = (&self.ime_request, &mut next.ime_request) {
            request.show_keyboard |=
                previous.show_keyboard && previous.client_id == request.client_id;
            if previous.client_id == request.client_id && previous.text_state == request.text_state
            {
                request.change_cause = previous.change_cause;
            }
        }
        *self = next;
    }
}

/// Publishes the focused editor's text, selection and input configuration.
pub struct ImeSession<'a> {
    request: &'a mut Option<ImeRequest>,
}

impl ImeSession<'_> {
    /// Publishes the IME snapshot for the current frame.
    pub fn update(&mut self, mut request: ImeRequest) {
        request.show_keyboard |= self
            .request
            .as_ref()
            .is_some_and(|request| request.show_keyboard);
        *self.request = Some(request);
    }

    /// Opens the software keyboard and publishes the current editor snapshot.
    pub fn show(&mut self, mut request: ImeRequest) {
        request.show_keyboard = true;
        self.update(request);
    }

    /// Clears the IME snapshot for the current frame.
    pub fn clear(&mut self) {
        *self.request = None;
    }
}

/// A request to the windowing system to open an Input Method Editor (IME).
/// This is typically used for text input components.
#[derive(Clone, Debug, PartialEq)]
pub struct ImeRequest {
    /// The size of the area where the IME is requested.
    pub size: PxSize,
    /// The position of the IME anchor relative to the requesting node.
    pub local_position: PxPosition,
    /// The complete text snapshot, including directional selection and composition.
    pub text_state: winit::event::ImeTextState,
    /// The input purpose and return-key action.
    pub options: winit::window::ImeOptions,
    pub(crate) change_cause: winit::event::ImeChangeCause,
    pub(crate) show_keyboard: bool,
    pub(crate) client_id: Option<crate::focus::FocusHandleId>,
    pub(crate) position: Option<PxPosition>,
}

impl ImeRequest {
    /// Creates a new IME request with the target input area size.
    pub fn new(size: PxSize) -> Self {
        Self {
            size,
            local_position: PxPosition::ZERO,
            text_state: winit::event::ImeTextState::default(),
            options: winit::window::ImeOptions::default(),
            change_cause: winit::event::ImeChangeCause::Other,
            show_keyboard: false,
            client_id: None,
            position: None,
        }
    }

    /// Sets the position of the IME anchor relative to the requesting node.
    pub fn with_local_position(mut self, local_position: PxPosition) -> Self {
        self.local_position = local_position;
        self
    }

    /// Sets the complete editable text snapshot using UTF-8 byte offsets.
    pub fn with_text_state(mut self, text_state: winit::event::ImeTextState) -> Self {
        self.text_state = text_state;
        self
    }

    /// Sets the input purpose and return-key action.
    pub fn with_options(mut self, options: winit::window::ImeOptions) -> Self {
        self.options = options;
        self
    }
}

fn apply_layout_placements(
    placements: &[(u64, PxPosition)],
    tree: &ComponentNodeTree,
    children: &[NodeId],
    component_node_metadatas: &mut ComponentNodeMetaDatas,
) {
    let positions: HashMap<_, _> = placements
        .iter()
        .enumerate()
        .map(|(order, (key, position))| (*key, (*position, order as u64)))
        .collect();
    for child_id in children {
        let placement = tree
            .get(*child_id)
            .and_then(|child| positions.get(&child.get().instance_key))
            .copied();
        if let Some((position, order)) = placement {
            place_node(*child_id, position, order, component_node_metadatas);
            continue;
        }
        let metadata = component_node_metadatas.entry_or_default(*child_id);
        let changed = metadata.rel_position.is_some();
        metadata.rel_position = None;
        metadata.placement_order = None;
        if changed {
            component_node_metadatas.mark_geometry_dirty(*child_id);
        }
    }
}

#[derive(Clone, Default)]
pub(super) struct CachedLayoutChildren(Option<Arc<CachedLayoutChildList>>);

struct CachedLayoutChildList {
    entries: Box<[(u64, ChildMeasure)]>,
    indices: HashMap<u64, usize>,
}

impl CachedLayoutChildren {
    fn new(entries: Vec<(u64, ChildMeasure)>) -> Self {
        if entries.is_empty() {
            return Self::default();
        }
        let indices = if entries.len() <= 4 {
            HashMap::default()
        } else {
            entries
                .iter()
                .enumerate()
                .map(|(index, &(key, _))| (key, index))
                .collect()
        };
        Self(Some(Arc::new(CachedLayoutChildList {
            entries: entries.into_boxed_slice(),
            indices,
        })))
    }

    fn entries(&self) -> &[(u64, ChildMeasure)] {
        self.0.as_deref().map_or(&[], |list| &list.entries)
    }

    fn index_of(&self, key: u64) -> Option<usize> {
        let list = self.0.as_ref()?;
        if list.indices.is_empty() {
            list.entries.iter().position(|&(entry, _)| entry == key)
        } else {
            list.indices.get(&key).copied()
        }
    }
}

fn share_placements(placements: &[(u64, PxPosition)]) -> Option<Arc<[(u64, PxPosition)]>> {
    (!placements.is_empty()).then(|| Arc::from(placements))
}

#[derive(Clone)]
struct MeasuredNodeLayout {
    size: ComputedData,
    placements: Vec<(u64, PxPosition)>,
    base_placements: Option<Arc<[(u64, PxPosition)]>>,
    measured_children: HashMap<NodeId, crate::layout::ChildMeasure>,
    intrinsic_dependencies: bool,
    draw_layout: NodeDrawLayout,
}

struct MeasureLayoutContext<'a, 'ctx> {
    tree: &'a ComponentNodeTree,
    children: &'a [NodeId],
    layout_ctx: Option<&'a LayoutContext<'ctx>>,
}

fn measure_base_layout(
    policy: &dyn LayoutModifierDyn,
    layout_ctx: &MeasureLayoutContext<'_, '_>,
    metadatas: &mut ComponentNodeMetaDatas,
    constraint: &Constraint,
) -> Result<MeasuredNodeLayout, MeasurementError> {
    let mut input = LayoutInput::new(
        layout_ctx.tree,
        ParentConstraint::new(constraint),
        layout_ctx.children,
        layout_ctx.layout_ctx,
    );
    let layout_result = {
        let mut scope = input.measure_scope(metadatas);
        policy.measure_dyn(&mut scope)?
    };
    Ok(MeasuredNodeLayout {
        size: layout_result.size,
        base_placements: share_placements(&layout_result.placements),
        placements: layout_result.placements,
        intrinsic_dependencies: input.has_intrinsic_dependencies(),
        measured_children: input.take_measured_children(),
        draw_layout: NodeDrawLayout {
            layers: None,
            base_constraint: *constraint,
            base_size: layout_result.size,
        },
    })
}

fn measure_with_layout_modifiers(
    modifiers: &[Arc<dyn LayoutModifierNode>],
    layout_ctx: &MeasureLayoutContext<'_, '_>,
    constraint: &Constraint,
    base: &mut dyn FnMut(&Constraint) -> Result<MeasuredNodeLayout, MeasurementError>,
) -> Result<MeasuredNodeLayout, MeasurementError> {
    if modifiers.is_empty() {
        return base(constraint);
    }

    struct ModifierChildRunner<'a, 'b> {
        next: &'b mut dyn FnMut(&Constraint) -> Result<MeasuredNodeLayout, MeasurementError>,
        last: Option<MeasuredNodeLayout>,
        placements: Vec<(u64, PxPosition)>,
        position: Option<PxPosition>,
        _marker: std::marker::PhantomData<&'a ()>,
    }

    impl LayoutModifierChild for ModifierChildRunner<'_, '_> {
        fn measure(&mut self, constraint: &Constraint) -> Result<ComputedData, MeasurementError> {
            let measured = (self.next)(constraint)?;
            let size = measured.size;
            self.last = Some(measured);
            self.placements.clear();
            self.position = None;
            Ok(size)
        }

        fn place(&mut self, position: PxPosition) {
            self.position = Some(position);
            let measured = self
                .last
                .as_ref()
                .expect("layout modifier child must be measured before placement");
            for (instance_key, child_position) in &measured.placements {
                self.placements
                    .push((*instance_key, position + *child_position));
            }
        }
    }

    let head = &modifiers[0];
    let tail = &modifiers[1..];
    let mut next = |next_constraint: &Constraint| {
        measure_with_layout_modifiers(tail, layout_ctx, next_constraint, base)
    };
    let mut input = LayoutInput::new(
        layout_ctx.tree,
        ParentConstraint::new(constraint),
        layout_ctx.children,
        layout_ctx.layout_ctx,
    );
    let modifier_input = LayoutModifierInput {
        layout_input: &input,
    };
    let mut child = ModifierChildRunner {
        next: &mut next,
        last: None,
        placements: Vec::new(),
        position: None,
        _marker: std::marker::PhantomData,
    };
    let size = head.measure_content(&modifier_input, &mut child)?.size;
    if let Some(measured) = child.last.as_ref() {
        input.extend_measured_children(measured.measured_children.clone());
    }
    let mut draw_layout = child
        .last
        .as_ref()
        .map(|measured| measured.draw_layout.clone())
        .unwrap_or_default();
    let bounds = child
        .position
        .zip(child.last.as_ref())
        .map(|(position, measured)| DrawLayoutBounds {
            position,
            size: measured.size,
        });
    let mut layers = draw_layout.layers.as_deref().unwrap_or_default().to_vec();
    for layer in &mut layers {
        *layer = layer.zip(child.position).map(|(mut layer, position)| {
            layer.position = layer.position + position;
            layer
        });
    }
    layers.insert(0, bounds);
    draw_layout.layers = Some(layers.into());
    Ok(MeasuredNodeLayout {
        size,
        placements: child.placements,
        base_placements: child
            .last
            .as_ref()
            .and_then(|measured| measured.base_placements.clone()),
        intrinsic_dependencies: input.has_intrinsic_dependencies()
            || child
                .last
                .as_ref()
                .is_some_and(|measured| measured.intrinsic_dependencies),
        measured_children: input.take_measured_children(),
        draw_layout,
    })
}

fn relayout_base_layout(
    policy: &dyn LayoutModifierDyn,
    modifiers: &[Arc<dyn LayoutModifierNode>],
    layout_ctx: &MeasureLayoutContext<'_, '_>,
    entry: &LayoutSnapshotEntry,
    parent_constraint: &Constraint,
    update_placements: bool,
) -> Option<MeasuredNodeLayout> {
    let _phase = push_phase(RuntimePhase::Place);
    let children = layout_ctx.children;
    if entry.children.entries().len() != children.len() {
        return None;
    }

    let child_sizes: HashMap<NodeId, ComputedData> = children
        .iter()
        .copied()
        .zip(
            entry
                .children
                .entries()
                .iter()
                .map(|(_, measure)| measure.size),
        )
        .collect();
    let scope = PlacementScope::new(
        layout_ctx.tree,
        ParentConstraint::new(&entry.draw_layout.base_constraint),
        children,
        &child_sizes,
        entry.draw_layout.base_size,
    );
    let placements = if update_placements {
        policy
            .place_children_dyn(&scope, &PlacementResult::new())?
            .into_placements()
    } else {
        entry
            .base_placements
            .as_deref()
            .unwrap_or_default()
            .to_vec()
    };
    let measured_children = children
        .iter()
        .copied()
        .zip(entry.children.entries().iter().map(|&(_, measure)| measure))
        .collect();
    let base_layout = MeasuredNodeLayout {
        size: entry.draw_layout.base_size,
        base_placements: share_placements(&placements),
        placements,
        measured_children,
        intrinsic_dependencies: entry.intrinsic_dependencies,
        draw_layout: NodeDrawLayout {
            layers: None,
            base_constraint: entry.draw_layout.base_constraint,
            base_size: entry.draw_layout.base_size,
        },
    };
    // Replay only the wrappers so their content bounds stay synchronized with
    // placement changes without measuring the policy or its child subtree.
    let mut base = |constraint: &Constraint| {
        if *constraint != entry.draw_layout.base_constraint {
            return Err(MeasurementError::MeasureFnFailed(
                "cached content constraints changed".into(),
            ));
        }
        Ok(base_layout.clone())
    };
    let measured =
        measure_with_layout_modifiers(modifiers, layout_ctx, parent_constraint, &mut base).ok()?;
    (measured.size == entry.layout_result.size).then_some(measured)
}

fn save_measured_snapshot(
    instance_key: u64,
    constraint: &Constraint,
    layout: &MeasureLayoutContext<'_, '_>,
    previous: Option<&LayoutSnapshotEntry>,
    measured: MeasuredNodeLayout,
) {
    let Some(layout_ctx) = layout.layout_ctx else {
        return;
    };
    let consumed_insets = layout_ctx.consumed_insets.get();
    let child_measurements = layout.children.iter().map(|id| {
        let measurement = measured.measured_children.get(id)?;
        measurement
            .consistent
            .then(|| (layout.tree[*id].get().instance_key, *measurement))
    });
    let unchanged = previous.is_some_and(|previous| {
        previous.constraint_key == *constraint
            && previous.consumed_insets == consumed_insets
            && previous.layout_result.size == measured.size
            && previous.layout_result.placements == measured.placements
            && previous.base_placements == measured.base_placements
            && previous.intrinsic_dependencies == measured.intrinsic_dependencies
            && previous.draw_layout == measured.draw_layout
            && child_measurements
                .clone()
                .eq(previous.children.entries().iter().copied().map(Some))
    });
    if unchanged {
        layout_ctx.acknowledge_deferred_invalidation(instance_key);
    } else if let Some(children) = child_measurements.collect::<Option<Vec<_>>>() {
        layout_ctx.insert_snapshot(
            instance_key,
            LayoutSnapshotEntry {
                constraint_key: *constraint,
                consumed_insets,
                children: CachedLayoutChildren::new(children),
                layout_result: LayoutResult {
                    size: measured.size,
                    placements: measured.placements,
                },
                base_placements: measured.base_placements,
                intrinsic_dependencies: measured.intrinsic_dependencies,
                draw_layout: measured.draw_layout,
            },
        );
        layout_ctx.inc_cache_store_count();
    } else {
        layout_ctx.remove_snapshot(instance_key);
        layout_ctx.inc_cache_drop_non_cacheable_count();
    }
}

/// Measures a single node recursively, returning its size or an error.
pub(crate) fn measure_node(
    node_id: NodeId,
    parent_constraint: &Constraint,
    tree: &ComponentNodeTree,
    component_node_metadatas: &mut ComponentNodeMetaDatas,
    layout_ctx: Option<&LayoutContext<'_>>,
) -> Result<ComputedData, MeasurementError> {
    let node_data_ref = tree
        .get(node_id)
        .ok_or(MeasurementError::NodeNotFoundInTree)?;
    let node_data = node_data_ref.get();
    #[cfg(feature = "profiling")]
    let mut profiler_guard = Some(ProfilerScopeGuard::new(
        ProfilerPhase::Measure,
        Some(node_id),
        node_data_ref.parent(),
        Some(node_data.fn_name),
    ));

    #[cfg(feature = "profiling")]
    if !layout_ctx.is_some_and(|context| context.intrinsic) {
        component_node_metadatas.profiling_dirty.insert(node_id);
    }
    let children = direct_layout_children(node_id, tree);
    let timer = Instant::now();

    debug!(
        "Measuring node {} with {} children, parent constraint: {:?}",
        node_data.fn_name,
        children.len(),
        parent_constraint
    );

    let prepare_measurement = || {
        let node = push_current_node_with_instance_logic_id(
            node_id,
            node_data.instance_logic_id,
            node_data.fn_name,
        );
        let instance = push_current_component_instance_key(nearest_replay_boundary_instance_key(
            node_id, tree,
        ));
        let measured = push_measured_node_instance_key(
            layout_ctx
                .and_then(|context| context.state_reader_instance_key)
                .unwrap_or(node_data.instance_key),
        );
        let phase = push_phase(RuntimePhase::Measure);
        (
            (phase, measured, instance, node),
            node_data.modifier.layout_modifiers(),
        )
    };
    let mut measurement = None;
    let layout_node = &node_data.layout_node;
    let snapshot = layout_ctx.and_then(|context| context.snapshot(node_data.instance_key));
    if let Some(layout_ctx) = layout_ctx {
        layout_ctx.inc_measure_node_calls();
        if let Some(entry) = snapshot.as_deref() {
            let path = layout_ctx.dirty_paths.and_then(|paths| paths.get(&node_id));
            let deferred = layout_ctx.deferred_invalidation(node_data.instance_key);
            let same_constraint = entry.constraint_key == *parent_constraint;
            let node_self_measure_dirty = entry.consumed_insets != layout_ctx.consumed_insets.get()
                || path.is_some_and(|path| path.measure)
                || deferred.as_ref().is_some_and(|pending| pending.measure);
            let node_self_placement_dirty = path.is_some_and(|path| path.placement)
                || deferred.as_ref().is_some_and(|pending| pending.placement);
            let node_effective_dirty = path.is_some()
                || deferred
                    .as_ref()
                    .is_some_and(|pending| !pending.children.is_empty());
            let cached_children = entry.children.entries();
            let can_try_reuse = !node_self_measure_dirty
                && (!node_effective_dirty || !entry.intrinsic_dependencies)
                && cached_children.len() == children.len();
            if can_try_reuse {
                if same_constraint
                    && !node_self_placement_dirty
                    && !node_effective_dirty
                    && component_node_metadatas
                        .get(&node_id)
                        .is_some_and(|metadata| {
                            metadata.computed_data == Some(entry.layout_result.size)
                        })
                {
                    component_node_metadatas
                        .entry_or_default(node_id)
                        .layout_cache_hit = true;
                    layout_ctx.inc_cache_hit_direct();
                    return Ok(entry.layout_result.size);
                }
                let dirty_children = path
                    .map(|path| path.children.as_slice())
                    .into_iter()
                    .flatten()
                    .filter_map(|&id| {
                        layout_ctx.inc_dirty_child_checked();
                        let index = entry.children.index_of(tree[id].get().instance_key)?;
                        Some((index, id))
                    })
                    .chain(
                        deferred
                            .iter()
                            .flat_map(|pending| pending.children.iter())
                            .filter_map(|key| {
                                let index = entry.children.index_of(*key)?;
                                let &id = children.get(index)?;
                                if tree[id].get().instance_key != *key
                                    || layout_ctx
                                        .dirty_paths
                                        .is_some_and(|paths| paths.contains_key(&id))
                                {
                                    return None;
                                }
                                layout_ctx.inc_dirty_child_checked();
                                Some((index, id))
                            }),
                    );

                let mut child_size_changed = false;
                for (index, child_id) in dirty_children {
                    let (_, previous) = cached_children[index];
                    let size = layout_ctx.with_consumed_insets(previous.consumed_insets, || {
                        measure_node(
                            child_id,
                            &previous.constraint,
                            tree,
                            component_node_metadatas,
                            Some(layout_ctx),
                        )
                    })?;
                    if size != previous.size {
                        child_size_changed = true;
                        break;
                    }
                }
                if child_size_changed {
                    layout_ctx.inc_cache_miss_child_size();
                } else {
                    if same_constraint
                        && !node_self_placement_dirty
                        && component_node_metadatas
                            .get(&node_id)
                            .is_some_and(|metadata| {
                                metadata.computed_data == Some(entry.layout_result.size)
                            })
                    {
                        component_node_metadatas
                            .entry_or_default(node_id)
                            .layout_cache_hit = true;
                        layout_ctx.acknowledge_deferred_invalidation(node_data.instance_key);
                        layout_ctx.inc_cache_hit_boundary();
                        return Ok(entry.layout_result.size);
                    }
                    let cached_result = &entry.layout_result;
                    let needs_relayout = node_self_placement_dirty || !same_constraint;
                    let relayout = if needs_relayout {
                        let (_, layout_modifiers) =
                            measurement.get_or_insert_with(&prepare_measurement);
                        crate::runtime::clear_phase_state_reads(
                            node_data.instance_key,
                            crate::runtime::ReadPhase::Place,
                        );
                        relayout_base_layout(
                            layout_node.as_ref(),
                            layout_modifiers,
                            &MeasureLayoutContext {
                                tree,
                                children: &children,
                                layout_ctx: Some(layout_ctx),
                            },
                            entry,
                            parent_constraint,
                            node_self_placement_dirty,
                        )
                    } else {
                        None
                    };
                    if needs_relayout && relayout.is_none() {
                        if node_self_placement_dirty {
                            layout_ctx.inc_cache_miss_dirty_self();
                        }
                    } else {
                        let (placements, draw_layout, base_placements) = relayout
                            .map(|measured| {
                                (
                                    measured.placements,
                                    measured.draw_layout,
                                    measured.base_placements,
                                )
                            })
                            .unwrap_or_else(|| {
                                (
                                    cached_result.placements.clone(),
                                    entry.draw_layout.clone(),
                                    entry.base_placements.clone(),
                                )
                            });
                        apply_layout_placements(
                            &placements,
                            tree,
                            &children,
                            component_node_metadatas,
                        );
                        if component_node_metadatas
                            .get(&node_id)
                            .is_some_and(|metadata| metadata.draw_layout != draw_layout)
                        {
                            component_node_metadatas.mark_paint_dirty(node_id);
                        }
                        if let Some(metadata) = component_node_metadatas.get_mut(&node_id) {
                            metadata.computed_data = Some(cached_result.size);
                            metadata.paint_dirty |= metadata.draw_layout != draw_layout;
                            metadata.draw_layout = draw_layout.clone();
                            metadata.layout_cache_hit = true;
                        }
                        if needs_relayout
                            && (!same_constraint
                                || placements != cached_result.placements
                                || draw_layout != entry.draw_layout
                                || base_placements != entry.base_placements)
                        {
                            layout_ctx.insert_snapshot(
                                node_data.instance_key,
                                LayoutSnapshotEntry {
                                    constraint_key: *parent_constraint,
                                    consumed_insets: layout_ctx.consumed_insets.get(),
                                    children: entry.children.clone(),
                                    layout_result: LayoutResult {
                                        size: cached_result.size,
                                        placements,
                                    },
                                    base_placements,
                                    intrinsic_dependencies: entry.intrinsic_dependencies,
                                    draw_layout,
                                },
                            );
                            layout_ctx.inc_cache_store_count();
                        }
                        layout_ctx.acknowledge_deferred_invalidation(node_data.instance_key);
                        layout_ctx.inc_cache_hit_boundary();
                        return Ok(cached_result.size);
                    }
                }
            }
            if !same_constraint {
                layout_ctx.inc_cache_miss_constraint();
            } else if node_self_measure_dirty || node_self_placement_dirty {
                layout_ctx.inc_cache_miss_dirty_self();
            } else if node_effective_dirty {
                layout_ctx.inc_cache_miss_child_size();
            } else {
                layout_ctx.inc_cache_miss_no_entry();
            }
        } else {
            layout_ctx.inc_cache_miss_no_entry();
        }
    }

    let (_, layout_modifiers) = measurement.get_or_insert_with(prepare_measurement);
    if !layout_ctx.is_some_and(|context| context.intrinsic) {
        crate::runtime::clear_phase_state_reads(
            node_data.instance_key,
            crate::runtime::ReadPhase::Measure,
        );
        crate::runtime::clear_phase_state_reads(
            node_data.instance_key,
            crate::runtime::ReadPhase::Place,
        );
    }
    let previous_size = reset_frame_metadata(node_id, component_node_metadatas);
    let measure_layout_ctx = MeasureLayoutContext {
        tree,
        children: &children,
        layout_ctx,
    };
    let measured = measure_with_layout_modifiers(
        layout_modifiers,
        &measure_layout_ctx,
        parent_constraint,
        &mut |constraint| {
            measure_base_layout(
                layout_node.as_ref(),
                &measure_layout_ctx,
                component_node_metadatas,
                constraint,
            )
        },
    )
    .inspect_err(|_| component_node_metadatas.mark_geometry_dirty(node_id))?;
    let size = measured.size;
    apply_layout_placements(
        &measured.placements,
        tree,
        &children,
        component_node_metadatas,
    );

    if previous_size != Some(size) {
        component_node_metadatas.mark_geometry_dirty(node_id);
    }
    let metadata = component_node_metadatas.entry_or_default(node_id);
    metadata.computed_data = Some(size);
    metadata.draw_layout = measured.draw_layout.clone();

    #[cfg(feature = "profiling")]
    if let Some(guard) = &mut profiler_guard {
        guard.set_computed_size(size.width.0, size.height.0);
    }

    save_measured_snapshot(
        node_data.instance_key,
        parent_constraint,
        &measure_layout_ctx,
        snapshot.as_deref(),
        measured,
    );

    debug!(
        "Measured node {} in {:?} with size {:?}",
        node_data.fn_name,
        timer.elapsed(),
        size
    );

    #[cfg(feature = "profiling")]
    if let Some(guard) = &mut profiler_guard {
        guard.set_computed_size(size.width.0, size.height.0);
    }

    Ok(size)
}

/// Places a node at the specified relative position within its parent.
pub(crate) fn place_node(
    node: indextree::NodeId,
    rel_position: PxPosition,
    placement_order: u64,
    component_node_metadatas: &mut ComponentNodeMetaDatas,
) {
    let metadata = component_node_metadatas.entry_or_default(node);
    let changed = metadata.rel_position != Some(rel_position);
    let order_changed = metadata.placement_order != Some(placement_order);
    metadata.rel_position = Some(rel_position);
    metadata.placement_order = Some(placement_order);
    if order_changed {
        component_node_metadatas.placement_order_dirty.insert(node);
        component_node_metadatas.mark_geometry_dirty(node);
    }
    if changed {
        component_node_metadatas.mark_geometry_dirty(node);
    }
}

/// Layout information computed at the measure stage, representing the size of a
/// node.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct ComputedData {
    /// The resolved width of the node in physical pixels.
    pub width: Px,
    /// The resolved height of the node in physical pixels.
    pub height: Px,
}

impl Add for ComputedData {
    type Output = Self;
    fn add(self, rhs: Self) -> Self::Output {
        Self {
            width: self.width + rhs.width,
            height: self.height + rhs.height,
        }
    }
}

impl AddAssign for ComputedData {
    fn add_assign(&mut self, rhs: Self) {
        *self = *self + rhs;
    }
}

impl ComputedData {
    /// Zero-sized layout data.
    pub const ZERO: Self = Self {
        width: Px(0),
        height: Px(0),
    };

    /// Calculates the minimum size guaranteed by a constraint interval.
    pub fn min_from_constraint(constraint: &Constraint) -> Self {
        let width = constraint.width.min;
        let height = constraint.height.min;
        Self { width, height }
    }

    /// Returns the component-wise minimum of two computed sizes.
    pub fn min(self, rhs: Self) -> Self {
        Self {
            width: self.width.min(rhs.width),
            height: self.height.min(rhs.height),
        }
    }

    /// Returns the component-wise maximum of two computed sizes.
    pub fn max(self, rhs: Self) -> Self {
        Self {
            width: self.width.max(rhs.width),
            height: self.height.max(rhs.height),
        }
    }
}