//! Scroll-into-view implementation

//!

//! Provides W3C CSSOM View Module compliant scroll-into-view functionality.

//! This module contains the core primitive `scroll_rect_into_view` which all

//! higher-level scroll-into-view APIs build upon.

//!

//! # Architecture

//!

//! The core principle is that all scroll-into-view operations reduce to scrolling

//! a rectangle into the visible area of its scroll container ancestry:

//!

//! - `scroll_rect_into_view`: Core primitive - scroll any rect into view

//! - `scroll_node_into_view`: Scroll a DOM node's bounding rect into view

//! - `scroll_cursor_into_view`: Scroll a text cursor position into view

//!

//! # W3C Compliance

//!

//! This implementation follows the W3C CSSOM View Module specification:

//! - `ScrollLogicalPosition`: start, center, end, nearest

//! - `ScrollBehavior`: auto, instant, smooth

//! - Proper scroll ancestor chain traversal

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

use alloc::vec::Vec;

use azul_core::{

    dom::{DomId, DomNodeId, NodeId},

    geom::{LogicalPosition, LogicalRect, LogicalSize},

    task::{Duration, Instant},

};

use crate::{

    managers::scroll_state::ScrollManager,

    solver3::getters::{get_overflow_x, get_overflow_y},

    window::DomLayoutResult,

};

// Re-export types from core for public API

pub use azul_core::events::{ScrollIntoViewBehavior, ScrollIntoViewOptions, ScrollLogicalPosition};

/// Minimum scroll delta (in logical pixels) below which scrolling is skipped

const SCROLL_DELTA_THRESHOLD: f32 = 0.5;

/// Duration of smooth scroll animations in milliseconds

const SMOOTH_SCROLL_DURATION_MS: u64 = 300;

/// Calculated scroll adjustment for one scroll container

#[derive(Copy, Debug, Clone)]

pub struct ScrollAdjustment {

    /// The DOM containing the scroll container

    pub scroll_container_dom_id: DomId,

    /// The node ID of the scroll container within the DOM

    pub scroll_container_node_id: NodeId,

    /// The scroll delta to apply

    pub delta: LogicalPosition,

    /// The scroll behavior to use

    pub behavior: ScrollIntoViewBehavior,

}

/// Information about a scrollable ancestor

#[derive(Debug, Clone)]

struct ScrollableAncestor {

    dom_id: DomId,

    node_id: NodeId,

    /// What to ADD to the target rect to express it in this ancestor's dom.

    ///

    /// Zero within one dom, where everything already shares an absolute space.

    /// Non-zero once the walk has crossed out of a `VirtualView`'s nested dom,

    /// whose display list is 0-relative and composited at

    /// `host.origin + content_offset`.

    target_lift: LogicalPosition,

    /// The visible rect of the scroll container (content area)

    visible_rect: LogicalRect,

    /// Whether horizontal scroll is enabled

    scroll_x: bool,

    /// Whether vertical scroll is enabled

    scroll_y: bool,

}

/// Resolve a nested dom to the `VirtualView` that hosts it:

/// `(host's dom, host node, offset that converts nested geometry to the host's

/// space)`.

///

/// Passed in rather than reaching for `VirtualViewManager` so this module stays

/// independent of it — and so a test can hand in a fixture chain.

pub type NestedDomHop<'a> = &'a dyn Fn(DomId) -> Option<(DomId, NodeId, LogicalPosition)>;

// ============================================================================

// Core API: scroll_rect_into_view

// ============================================================================

/// Core function: scroll a rect into the visible area of its scroll containers

///

/// This is the ONLY scroll-into-view primitive. All higher-level APIs call this.

///

/// # Arguments

///

/// * `target_rect` - The rectangle to make visible (in absolute coordinates)

/// * `target_dom_id` - The DOM containing the target node

/// * `target_node_id` - The target node (used for finding scroll ancestors)

/// * `layout_results` - Layout data for all DOMs

/// * `scroll_manager` - Current scroll state

/// * `options` - How to scroll (alignment and animation)

/// * `now` - Current timestamp for animation

///

/// # Returns

///

/// A vector of scroll adjustments for each scroll container in the ancestry chain.

/// The adjustments are ordered from innermost (closest to target) to outermost.

// Instant is a ref-counted FFI clock handle threaded through the event loop by value;

// &-converting would cascade through the loop call chain.

#[allow(clippy::needless_pass_by_value)]

    // Find scrollable ancestors from target to root

    );

    // Transform target_rect relative to each scroll container and calculate deltas

        // Express the target in THIS ancestor's dom before comparing. Zero

        // within one dom; non-zero once the walk has left a nested one.

        // Calculate the scroll delta based on options

        );

        // Only add adjustment if there's actual scrolling to do

    }

// ============================================================================

// Higher-Level APIs

// ============================================================================

/// Scroll a DOM node's bounding rect into view

///

/// This is a convenience wrapper around `scroll_rect_into_view` that

/// automatically gets the node's bounding rect from layout results.

    // Get node's bounding rect from layout

    };

    };

    // Call the core rect-based API

    )

/// Scroll a text cursor position into view

///

/// Transforms the cursor's visual rect (in node-local coordinates) to absolute

/// coordinates before scrolling.

    // Get node's position to transform cursor_rect to absolute coordinates

    };

    // Transform cursor rect to absolute coordinates

    };

    // Call the core rect-based API

    )

// ============================================================================

// Helper Functions

// ============================================================================

/// Find all scrollable ancestors from a node to the root

///

/// Returns ancestors ordered from innermost (closest to target) to outermost (root).

    // What to add to the target rect to express it in `current_dom`.

    'walk: loop {

        };

        // In the target's OWN dom start above it: scrolling a container into

        // its own scrollport is not a thing. After a crossing, start AT the

        // host — the VirtualView clips the nested content, so it is a genuine

        // scroll ancestor of everything inside it.

        } else {

        };

        }

        // Reached this dom's root. A nested dom is a WINDOW inside a

        // VirtualView, so its scroll ancestry continues in the host's dom —

        // stopping here meant a caret inside a virtualized view could never be

        // revealed through the containers that actually clip it.

        }

    }

/// How many `VirtualView` boundaries [`find_scrollable_ancestors`] will cross.

/// Nesting is shallow; the bound only stops a cycle.

const NESTED_DOM_CROSSING_LIMIT: usize = 32;

/// Check if a node is scrollable and return its scroll info

    );

    );

    // Programmatic scrolling reaches EVERY scroll container - including

    // overflow:hidden, whose user scrolling is disabled but which css

    // overflow-3 §3.1 keeps programmatically scrollable (scrollIntoView

    // through a hidden clipper is the canonical carousel/tab-panel case).

    // If neither axis is scrollable, skip this node

    // Check if the scroll manager has scroll state for this node

    // (which means it actually has overflowing content)

    // Check if content actually overflows (use virtual_scroll_size when set, e.g. for VirtualView)

    // Get the visible rect (container rect minus current scroll offset)

    Some(ScrollableAncestor {

        // Filled in by the walk, which is what knows how many VirtualView

        // boundaries were crossed to reach this ancestor.

    })

/// Calculate the scroll delta needed to bring target into view within container

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

    LogicalPosition {

            )

        } else {

        },

            )

        } else {

        },

    }

/// Calculate scroll delta for a single axis

        ScrollLogicalPosition::Start => {

            // Align target start with container start

        }

        ScrollLogicalPosition::End => {

            // Align target end with container end

        }

        ScrollLogicalPosition::Center => {

            // Center target in container

        }

        ScrollLogicalPosition::Nearest => {

            // Minimum scroll to make target fully visible

                // Target is above/left of visible area - scroll up/left

                // Target is below/right of visible area

                    // Target fits, align end with container end

                } else {

                    // Target doesn't fit, align start with container start

                }

            } else {

                // Target is already fully visible

            }

        }

    }

/// Resolve scroll behavior based on options and CSS properties

// +spec:containing-block:03528c - scroll-behavior on root element applies to viewport

        ScrollIntoViewBehavior::Auto => {

            // TODO: Check CSS scroll-behavior property on the scroll container

            // For now, default to instant

        }

    }

/// Apply a scroll adjustment to the scroll manager

    use azul_core::events::EasingFunction;

    use azul_core::task::SystemTimeDiff;

    }

/// Get a node's bounding rect from layout results

    // Get position

    // Get size

#[cfg(test)]

mod autotest_generated {

    /// The fixtures here are single-dom: there is no `VirtualView` boundary to

    /// cross, so the walk stops at the root exactly as it always did.

    fn no_hop(_: DomId) -> Option<(DomId, NodeId, LogicalPosition)> {

        None

    }

    use alloc::collections::BTreeMap;

    use std::collections::HashMap;

    use azul_core::{

        dom::{Dom, FormattingContext, IdOrClass},

        styled_dom::{NodeHierarchyItemId, StyledDom},

    };

    use super::*;

    use crate::solver3::{

        display_list::DisplayList,

        geometry::PackedBoxProps,

        layout_tree::{LayoutNodeHot, LayoutTree},

    };

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

    // Fixtures

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

    /// Flat node indices of [`chain_dom`]. The fixture is a *linear* chain, so

    /// these indices hold under any tree-flattening order.

    const OUTER: usize = 1;

    const INNER: usize = 2;

    const TARGET: usize = 3;

    /// A node index far past the end of the fixture DOM.

    const OUT_OF_RANGE: usize = 9999;

    const SCROLL_CSS: &str = ".outer { overflow-x: scroll; overflow-y: scroll; } .inner { \

                              overflow-x: scroll; overflow-y: scroll; }";

    const X_ONLY_CSS: &str = ".inner { overflow-x: scroll; }";

    const NO_CSS: &str = "";

    fn dom_id(inner: usize) -> DomId {

        DomId { inner }

    }

    fn nid(index: usize) -> NodeId {

        NodeId::new(index)

    }

    fn dnid(dom: usize, index: usize) -> DomNodeId {

        DomNodeId {

            dom: dom_id(dom),

            node: NodeHierarchyItemId::from_crate_internal(Some(nid(index))),

        }

    }

    /// A `DomNodeId` whose node slot is the "no node" sentinel.

    fn null_dnid(dom: usize) -> DomNodeId {

        DomNodeId {

            dom: dom_id(dom),

            node: NodeHierarchyItemId::NONE,

        }

    }

    fn pos(x: f32, y: f32) -> LogicalPosition {

        LogicalPosition::new(x, y)

    }

    fn size(width: f32, height: f32) -> LogicalSize {

        LogicalSize::new(width, height)

    }

    fn rect(x: f32, y: f32, width: f32, height: f32) -> LogicalRect {

        LogicalRect::new(pos(x, y), size(width, height))

    }

    fn close(a: f32, b: f32) -> bool {

        (a - b).abs() < 1e-3

    }

    fn now() -> Instant {

        Instant::now()

    }

    fn opts(

        block: ScrollLogicalPosition,

        inline_axis: ScrollLogicalPosition,

        behavior: ScrollIntoViewBehavior,

    ) -> ScrollIntoViewOptions {

        ScrollIntoViewOptions {

            block,

            inline_axis,

            behavior,

        }

    }

    fn div_with_class(class: &str) -> Dom {

        Dom::create_div().with_ids_and_classes(vec![IdOrClass::Class(class.into())].into())

    }

    /// `body(0) > .outer(1) > .inner(2) > .target(3)` — a strictly linear chain,

    /// styled through a real class stylesheet (not `Dom::with_css`, whose scoped

    /// `*` rule would also match the descendants and blur which node is styled).

    fn chain_dom(css_str: &str) -> StyledDom {

        let mut dom = Dom::create_body().with_child(

            div_with_class("outer")

                .with_child(div_with_class("inner").with_child(div_with_class("target"))),

        );

        let (css, _warnings) = azul_css::parser2::new_from_str(css_str);

        StyledDom::create(&mut dom, css)

    }

    fn empty_layout_tree() -> LayoutTree {

        LayoutTree {

            nodes: Vec::new(),

            warm: Vec::new(),

            cold: Vec::new(),

            root: 0,

            dom_to_layout: BTreeMap::new(),

            children_arena: Vec::new(),

            children_offsets: Vec::new(),

            subtree_needs_intrinsic: Vec::new(),

        }

    }

    /// A `DomLayoutResult` with an *empty* layout tree. Everything except

    /// `get_node_rect` reads only `styled_dom`, so no real layout is needed.

    fn layout_result(styled_dom: StyledDom) -> DomLayoutResult {

        DomLayoutResult {

            styled_dom,

            layout_tree: empty_layout_tree(),

            calculated_positions: Vec::new(),

            viewport: LogicalRect::zero(),

            display_list: std::sync::Arc::new(DisplayList::default()),

            scroll_ids: HashMap::new(),

            scroll_id_to_node_id: HashMap::new(),

        }

    }

    /// One layout box per entry, in order: DOM node `n` maps to layout index `i`,

    /// laid out at `p` with used size `s`.

    fn layout_result_with_boxes(

        styled_dom: StyledDom,

        boxes: &[(usize, LogicalPosition, Option<LogicalSize>)],

    ) -> DomLayoutResult {

        let mut lr = layout_result(styled_dom);

        for (layout_index, (node_index, position, used_size)) in boxes.iter().enumerate() {

            lr.layout_tree

                .dom_to_layout

                .insert(nid(*node_index), vec![LayoutNodeId::new(layout_index)]);

            lr.layout_tree.nodes.push(LayoutNodeHot {

                box_props: PackedBoxProps::default(),

                dom_node_id: Some(nid(*node_index)),

                used_size: *used_size,

                formatting_context: FormattingContext::Block {

                    establishes_new_context: false,

                },

                parent: None,

            });

            lr.calculated_positions.push(*position);

        }

        lr

    }

    fn window(lr: DomLayoutResult) -> BTreeMap<DomId, DomLayoutResult> {

        let mut map = BTreeMap::new();

        map.insert(dom_id(0), lr);

        map

    }

    fn register(sm: &mut ScrollManager, node: usize, container: LogicalRect, content: LogicalSize) {

        sm.register_or_update_scroll_node(

            dom_id(0),

            nid(node),

            container,

            content,

            now(),

            16.0,

            8.0,

            false,

            false,

        );

    }

    /// `.inner` (node 2) is a 100×100 scroll container at the origin holding

    /// 100×1000 of content: vertical overflow only, max scroll y = 900.

    /// `.outer` (node 1) is styled scrollable but never registered with the scroll

    /// manager, so it is *not* a live scroll container.

    fn inner_only() -> (BTreeMap<DomId, DomLayoutResult>, ScrollManager) {

        let layout_results = window(layout_result(chain_dom(SCROLL_CSS)));

        let mut sm = ScrollManager::new();

        register(

            &mut sm,

            INNER,

            rect(0.0, 0.0, 100.0, 100.0),

            size(100.0, 1000.0),

        );

        (layout_results, sm)

    }

    // ==================================================================

    // calculate_axis_delta — numeric: zero / min_max / negative / nan_inf

    // ==================================================================

    #[test]

    fn axis_delta_all_zero_inputs_are_zero_for_every_position() {

        for position in [

            ScrollLogicalPosition::Start,

            ScrollLogicalPosition::Center,

            ScrollLogicalPosition::End,

            ScrollLogicalPosition::Nearest,

        ] {

            let delta = calculate_axis_delta(0.0, 0.0, 0.0, 0.0, position);

            assert!(close(delta, 0.0), "{position:?} on all-zero input");

        }

    }

    #[test]

    fn axis_delta_start_aligns_target_start_with_container_start() {

        assert!(close(

            calculate_axis_delta(100.0, 50.0, 20.0, 30.0, ScrollLogicalPosition::Start),

            80.0

        ));

    }

    #[test]

    fn axis_delta_end_aligns_target_end_with_container_end() {

        // target 100..150, container 0..30 => 150 - 30

        assert!(close(

            calculate_axis_delta(100.0, 50.0, 0.0, 30.0, ScrollLogicalPosition::End),

            120.0

        ));

    }

    #[test]

    fn axis_delta_center_aligns_midpoints() {

        // target center 120, container center 50

        assert!(close(

            calculate_axis_delta(100.0, 40.0, 0.0, 100.0, ScrollLogicalPosition::Center),

            70.0

        ));

    }

    #[test]

    fn axis_delta_center_of_zero_sized_target_is_offset_of_container_center() {

        assert!(close(

            calculate_axis_delta(0.0, 0.0, 0.0, 100.0, ScrollLogicalPosition::Center),

            -50.0

        ));

    }

    #[test]

    fn axis_delta_nearest_leaves_fully_visible_target_alone() {

        // target 10..30 inside container 0..100

        assert!(close(

            calculate_axis_delta(10.0, 20.0, 0.0, 100.0, ScrollLogicalPosition::Nearest),

            0.0

        ));

    }

    #[test]

    fn axis_delta_nearest_scrolls_back_for_target_before_container() {

        assert!(close(

            calculate_axis_delta(-40.0, 20.0, 0.0, 100.0, ScrollLogicalPosition::Nearest),

            -40.0

        ));

    }

    #[test]

    fn axis_delta_nearest_aligns_end_when_target_fits() {

        // target 150..170 (size 20) below container 0..100 => end-align

        assert!(close(

            calculate_axis_delta(150.0, 20.0, 0.0, 100.0, ScrollLogicalPosition::Nearest),

            70.0

        ));

    }

    #[test]

    fn axis_delta_nearest_aligns_start_when_target_does_not_fit() {

        // target 150..450 (size 300) is bigger than the 100px container => start-align

        assert!(close(

            calculate_axis_delta(150.0, 300.0, 0.0, 100.0, ScrollLogicalPosition::Nearest),

            150.0

        ));

    }

    #[test]

    fn axis_delta_handles_negative_coordinates_deterministically() {

        // container -100..-50, target -200..-190

        assert!(close(

            calculate_axis_delta(-200.0, 10.0, -100.0, 50.0, ScrollLogicalPosition::Start),

            -100.0

        ));

        assert!(close(

            calculate_axis_delta(-200.0, 10.0, -100.0, 50.0, ScrollLogicalPosition::End),

            -140.0

        ));

        assert!(close(

            calculate_axis_delta(-200.0, 10.0, -100.0, 50.0, ScrollLogicalPosition::Nearest),

            -100.0

        ));

    }

    #[test]

    fn axis_delta_nearest_never_scrolls_the_wrong_way() {

        let (container_start, container_size) = (100.0f32, 50.0f32);

        for target_start in [-1000.0f32, 0.0, 99.0, 100.0, 120.0, 149.0, 150.0, 1000.0] {

            for target_size in [0.0f32, 10.0, 50.0, 60.0] {

                let delta = calculate_axis_delta(

                    target_start,

                    target_size,

                    container_start,

                    container_size,

                    ScrollLogicalPosition::Nearest,

                );

                let start_align = target_start - container_start;

                let end_align = (target_start + target_size) - (container_start + container_size);

                let fully_visible = target_start >= container_start

                    && (target_start + target_size) <= (container_start + container_size);

                // The delta is always one of {0, start-align, end-align} — never an

                // arbitrary value, and never an overshoot past both alignments.

                assert!(

                    close(delta, 0.0) || close(delta, start_align) || close(delta, end_align),

                    "delta {delta} for target {target_start}+{target_size}"

                );

                if fully_visible {

                    assert!(

                        close(delta, 0.0),

                        "visible target {target_start}+{target_size} must not scroll"

                    );

                }

                if target_start < container_start {

                    // Target starts before the viewport: only ever scroll backwards.

                    assert!(delta <= 0.0, "delta {delta} scrolled the wrong way");

                }

            }

        }

    }

    #[test]

    fn axis_delta_nan_target_start_does_not_panic() {

        // Start/End/Center are pure arithmetic: NaN propagates (a defined f32 result).

        for position in [

            ScrollLogicalPosition::Start,

            ScrollLogicalPosition::End,

            ScrollLogicalPosition::Center,

        ] {

            let delta = calculate_axis_delta(f32::NAN, 10.0, 0.0, 100.0, position);

            assert!(delta.is_nan(), "{position:?} should propagate NaN, got {delta}");

        }

    }

    #[test]

    fn axis_delta_nan_target_start_is_zero_for_nearest() {

        // Every NaN comparison is false, so `Nearest` falls through to the

        // "already fully visible" branch and returns exactly 0.0 — the safe

        // choice (no scroll) rather than a NaN leaking into the scroll offset.

        let delta = calculate_axis_delta(f32::NAN, 10.0, 0.0, 100.0, ScrollLogicalPosition::Nearest);

        assert_eq!(delta, 0.0);

    }

    #[test]

    fn axis_delta_nan_container_does_not_panic() {

        for position in [

            ScrollLogicalPosition::Start,

            ScrollLogicalPosition::End,

            ScrollLogicalPosition::Center,

            ScrollLogicalPosition::Nearest,

        ] {

            let delta = calculate_axis_delta(0.0, 10.0, f32::NAN, f32::NAN, position);

            assert!(

                delta.is_nan() || delta == 0.0,

                "{position:?} gave {delta} for a NaN container"

            );

        }

    }

    #[test]

    fn axis_delta_infinite_target_start_saturates_to_infinity() {

        let delta =

            calculate_axis_delta(f32::INFINITY, 10.0, 0.0, 100.0, ScrollLogicalPosition::Start);

        assert!(delta.is_infinite() && delta.is_sign_positive());

        let delta = calculate_axis_delta(

            f32::NEG_INFINITY,

            10.0,

            0.0,

            100.0,

            ScrollLogicalPosition::Start,

        );

        assert!(delta.is_infinite() && delta.is_sign_negative());

    }

    #[test]

    fn axis_delta_infinity_minus_infinity_is_nan_not_a_panic() {

        let delta = calculate_axis_delta(

            f32::INFINITY,

            10.0,

            f32::INFINITY,

            100.0,

            ScrollLogicalPosition::Start,

        );

        assert!(delta.is_nan());

    }

    #[test]

    fn axis_delta_infinite_sizes_do_not_panic() {

        for position in [

            ScrollLogicalPosition::Start,

            ScrollLogicalPosition::End,

            ScrollLogicalPosition::Center,

            ScrollLogicalPosition::Nearest,

        ] {

            let delta = calculate_axis_delta(0.0, f32::INFINITY, 0.0, f32::INFINITY, position);

            assert!(

                delta.is_nan() || delta.is_infinite() || delta.is_finite(),

                "{position:?} produced a non-f32 value"

            );

        }

    }

    #[test]

    fn axis_delta_f32_max_overflow_saturates_instead_of_panicking() {

        // target_start + target_size overflows f32 => +inf (IEEE saturation, no panic)

        let delta =

            calculate_axis_delta(f32::MAX, f32::MAX, 0.0, 100.0, ScrollLogicalPosition::End);

        assert!(delta.is_infinite() && delta.is_sign_positive());

        // Nearest sees target_end == +inf > container_end, and the (infinite)

        // target does not fit, so it start-aligns to a finite f32::MAX.

        let delta =

            calculate_axis_delta(f32::MAX, f32::MAX, 0.0, 100.0, ScrollLogicalPosition::Nearest);

        assert_eq!(delta, f32::MAX);

    }

    #[test]

    fn axis_delta_f32_min_does_not_panic() {

        for position in [

            ScrollLogicalPosition::Start,

            ScrollLogicalPosition::End,

            ScrollLogicalPosition::Center,

            ScrollLogicalPosition::Nearest,

        ] {

            let delta = calculate_axis_delta(f32::MIN, 1.0, f32::MAX, 1.0, position);

            assert!(!delta.is_nan(), "{position:?} produced NaN from finite input");

        }

    }

    // ==================================================================

    // calculate_scroll_delta — numeric

    // ==================================================================

    #[test]

    fn scroll_delta_zero_rects_are_zero() {

        let delta = calculate_scroll_delta(

            LogicalRect::zero(),

            LogicalRect::zero(),

            ScrollLogicalPosition::Nearest,

            ScrollLogicalPosition::Nearest,

            true,

            true,

        );

        assert_eq!((delta.x, delta.y), (0.0, 0.0));

    }

    #[test]

    fn scroll_delta_disabled_axes_are_exactly_zero_even_for_nan_and_infinite_rects() {

        let poison = LogicalRect::new(

            pos(f32::NAN, f32::INFINITY),

            size(f32::NAN, f32::NEG_INFINITY),

        );

        let delta = calculate_scroll_delta(

            poison,

            poison,

            ScrollLogicalPosition::Start,

            ScrollLogicalPosition::Start,

            false,

            false,

        );

        // Disabled axes short-circuit to 0.0 before any arithmetic runs, so no

        // NaN can reach the scroll offset.

        assert_eq!((delta.x, delta.y), (0.0, 0.0));

        assert!(delta.x.is_finite() && delta.y.is_finite());

    }

    #[test]

    fn scroll_delta_does_not_swap_the_axes() {

        // x must use `inline` + width, y must use `block` + height.

        let delta = calculate_scroll_delta(

            rect(10.0, 200.0, 5.0, 5.0),

            rect(0.0, 0.0, 100.0, 50.0),

            ScrollLogicalPosition::Start, // block  -> y

            ScrollLogicalPosition::End,   // inline -> x

            true,

            true,

        );

        assert!(close(delta.x, -85.0), "x used the wrong axis/position: {}", delta.x);

        assert!(close(delta.y, 200.0), "y used the wrong axis/position: {}", delta.y);

    }

    #[test]

    fn scroll_delta_only_enabled_axis_moves() {

        let target = rect(500.0, 500.0, 10.0, 10.0);

        let container = rect(0.0, 0.0, 100.0, 100.0);

        let x_only = calculate_scroll_delta(

            target,

            container,

            ScrollLogicalPosition::Start,

            ScrollLogicalPosition::Start,

            true,

            false,

        );

        assert!(close(x_only.x, 500.0));

        assert_eq!(x_only.y, 0.0);

        let y_only = calculate_scroll_delta(

            target,

            container,

            ScrollLogicalPosition::Start,

            ScrollLogicalPosition::Start,

            false,

            true,

        );

        assert_eq!(y_only.x, 0.0);

        assert!(close(y_only.y, 500.0));

    }

    // ==================================================================

    // resolve_scroll_behavior — predicate / invariant

    // ==================================================================

    #[test]

    fn resolve_behavior_maps_auto_to_instant_and_passes_the_rest_through() {

        let empty: BTreeMap<DomId, DomLayoutResult> = BTreeMap::new();

        assert_eq!(

            resolve_scroll_behavior(

                ScrollIntoViewBehavior::Auto,

                dom_id(0),

                nid(TARGET),

                &empty

            ),

            ScrollIntoViewBehavior::Instant

        );

        assert_eq!(

            resolve_scroll_behavior(

                ScrollIntoViewBehavior::Instant,

                dom_id(0),

                nid(TARGET),

                &empty

            ),

            ScrollIntoViewBehavior::Instant

        );

        assert_eq!(

            resolve_scroll_behavior(

                ScrollIntoViewBehavior::Smooth,

                dom_id(OUT_OF_RANGE),

                nid(OUT_OF_RANGE),

                &empty

            ),

            ScrollIntoViewBehavior::Smooth

        );

    }

    #[test]

    fn resolve_behavior_is_idempotent() {

        let empty: BTreeMap<DomId, DomLayoutResult> = BTreeMap::new();

        for behavior in [

            ScrollIntoViewBehavior::Auto,

            ScrollIntoViewBehavior::Instant,

            ScrollIntoViewBehavior::Smooth,

        ] {

            let once = resolve_scroll_behavior(behavior, dom_id(0), nid(0), &empty);

            let twice = resolve_scroll_behavior(once, dom_id(0), nid(0), &empty);

            assert_eq!(once, twice, "resolving {behavior:?} twice changed the result");

        }

    }

    // ==================================================================

    // apply_scroll_adjustment — numeric: zero / min_max / negative / overflow

    // ==================================================================

    /// 100×100 container, 500×500 content => max scroll (400, 400).

    fn registered_manager() -> ScrollManager {

        let mut sm = ScrollManager::new();

        register(

            &mut sm,

            INNER,

            rect(0.0, 0.0, 100.0, 100.0),

            size(500.0, 500.0),

        );

        sm

    }

    #[test]

    fn apply_zero_delta_leaves_the_offset_at_zero() {

        let mut sm = registered_manager();

        apply_scroll_adjustment(

            &mut sm,

            dom_id(0),

            nid(INNER),

            pos(0.0, 0.0),

            ScrollIntoViewBehavior::Instant,

            now(),

        );

        let offset = sm.get_current_offset(dom_id(0), nid(INNER)).unwrap();

        assert_eq!((offset.x, offset.y), (0.0, 0.0));

    }

    #[test]

    fn apply_on_an_unregistered_node_creates_a_zero_bounded_state() {

        // No bounds are known for the node, so max scroll is 0 and the delta is

        // clamped away entirely — it must not panic or store an unbounded offset.

        let mut sm = ScrollManager::new();

        apply_scroll_adjustment(

            &mut sm,

            dom_id(0),

            nid(OUT_OF_RANGE),

            pos(1234.0, 5678.0),

            ScrollIntoViewBehavior::Instant,

            now(),

        );

        let offset = sm.get_current_offset(dom_id(0), nid(OUT_OF_RANGE)).unwrap();

        assert_eq!((offset.x, offset.y), (0.0, 0.0));

    }

    #[test]

    fn apply_instant_delta_moves_the_offset() {

        let mut sm = registered_manager();

        apply_scroll_adjustment(

            &mut sm,

            dom_id(0),

            nid(INNER),

            pos(50.0, 60.0),

            ScrollIntoViewBehavior::Instant,

            now(),

        );

        let offset = sm.get_current_offset(dom_id(0), nid(INNER)).unwrap();

        assert!(close(offset.x, 50.0) && close(offset.y, 60.0));

        assert!(!sm.has_active_animations());

    }

    #[test]

    fn apply_negative_delta_clamps_to_zero() {

        let mut sm = registered_manager();

        apply_scroll_adjustment(

            &mut sm,

            dom_id(0),

            nid(INNER),

            pos(-1000.0, -1000.0),

            ScrollIntoViewBehavior::Instant,

            now(),

        );

        let offset = sm.get_current_offset(dom_id(0), nid(INNER)).unwrap();

        assert_eq!((offset.x, offset.y), (0.0, 0.0));

    }

    #[test]

    fn apply_f32_max_delta_clamps_to_max_scroll() {

        let mut sm = registered_manager();

        apply_scroll_adjustment(

            &mut sm,

            dom_id(0),

            nid(INNER),

            pos(f32::MAX, f32::MAX),

            ScrollIntoViewBehavior::Instant,

            now(),

        );

        let offset = sm.get_current_offset(dom_id(0), nid(INNER)).unwrap();

        assert!(close(offset.x, 400.0) && close(offset.y, 400.0), "{offset:?}");

    }

    #[test]

    fn apply_infinite_delta_clamps_to_the_scroll_bounds() {

        let mut sm = registered_manager();

        apply_scroll_adjustment(

            &mut sm,

            dom_id(0),

            nid(INNER),

            pos(f32::INFINITY, f32::NEG_INFINITY),

            ScrollIntoViewBehavior::Instant,

            now(),

        );

        let offset = sm.get_current_offset(dom_id(0), nid(INNER)).unwrap();

        assert!(offset.x.is_finite() && offset.y.is_finite(), "{offset:?}");

        assert!(close(offset.x, 400.0) && close(offset.y, 0.0), "{offset:?}");

    }

    #[test]

    fn apply_nan_delta_cannot_poison_the_scroll_offset() {

        let mut sm = registered_manager();

        apply_scroll_adjustment(

            &mut sm,

            dom_id(0),

            nid(INNER),

            pos(f32::NAN, f32::NAN),

            ScrollIntoViewBehavior::Instant,

            now(),

        );

        let offset = sm.get_current_offset(dom_id(0), nid(INNER)).unwrap();

        // f32::max(NaN, 0.0) == 0.0, so the clamp scrubs the NaN.

        assert!(offset.x.is_finite() && offset.y.is_finite(), "{offset:?}");

        assert_eq!((offset.x, offset.y), (0.0, 0.0));

    }

    #[test]

    fn apply_auto_behaves_like_instant() {

        let mut sm = registered_manager();

        apply_scroll_adjustment(

            &mut sm,

            dom_id(0),

            nid(INNER),

            pos(25.0, 25.0),

            ScrollIntoViewBehavior::Auto,

            now(),

        );

        let offset = sm.get_current_offset(dom_id(0), nid(INNER)).unwrap();

        assert!(close(offset.x, 25.0) && close(offset.y, 25.0));

        assert!(!sm.has_active_animations());

    }

    #[test]

    fn apply_smooth_animates_instead_of_jumping() {

        let mut sm = registered_manager();

        apply_scroll_adjustment(

            &mut sm,

            dom_id(0),

            nid(INNER),

            pos(50.0, 50.0),

            ScrollIntoViewBehavior::Smooth,

            now(),

        );

        let offset = sm.get_current_offset(dom_id(0), nid(INNER)).unwrap();

        assert_eq!((offset.x, offset.y), (0.0, 0.0), "smooth must not jump");

        assert!(sm.has_active_animations(), "smooth must arm an animation");

    }

    #[test]

    fn apply_deltas_accumulate_onto_the_current_offset() {

        let mut sm = registered_manager();

        for _ in 0..3 {

            apply_scroll_adjustment(

                &mut sm,

                dom_id(0),

                nid(INNER),

                pos(100.0, 100.0),