//! Pure scroll state management — the single source of truth for scroll offsets.

//!

//! # Architecture

//!

//! `ScrollManager` is the exclusive owner of all scroll state. Other modules

//! interact with scrolling only through its public API:

//!

//! - **Platform shell** (macos/events.rs, etc.): Calls `record_scroll_from_hit_test()`

//!   to queue trackpad/mouse wheel input for the physics timer.

//! - **Scroll physics timer** (`scroll_timer.rs)`: Consumes inputs via `ScrollInputQueue`,

//!   applies physics, and pushes `CallbackChange::ScrollTo` for each updated node.

//! - **Event processing** (`event_v2.rs)`: Processes `ScrollTo` changes, sets scroll

//!   positions, and checks `VirtualView` re-invocation transparently.

//! - **Drag autoscroll** (`shell2/common/event.rs`): while a text-selection

//!   drag is held past a container's edge, a 60Hz timer pushes

//!   `CallbackChange::ScrollTo`. It does NOT go through the gesture manager —

//!   an earlier `AutoScrollDirection` design did, and was documented here

//!   long after it stopped being constructed anywhere.

//! - **Render loop**: Calls `tick()` every frame to advance easing animations.

//! - **`WebRender` sync** (`wr_translate2.rs)`: Reads offsets via

//!   `get_scroll_states_for_dom()` to synchronize scroll frames.

//! - **Layout** (cache.rs): Registers scroll nodes via

//!   `register_or_update_scroll_node()` after layout completes.

//!

//! # Scroll Flow

//!

//! ```text

//! Platform Event Handler

//!   → record_scroll_from_hit_test() → ScrollInputQueue

//!   → starts SCROLL_MOMENTUM_TIMER_ID if not running

//!

//! Timer fires (every ~16ms):

//!   → queue.take_all() → physics integration

//!   → push_change(CallbackChange::ScrollTo)

//!

//! ScrollTo processing (event_v2.rs):

//!   → scroll_manager.set_scroll_position()

//!   → virtual_view_manager.check_reinvoke() (transparent VirtualView support)

//!   → repaint

//! ```

//!

//! This module provides:

//! - Smooth scroll animations with easing

//! - Event source classification for scroll events

//! - Scrollbar geometry and hit-testing

//! - Virtual scroll bounds for `VirtualView` nodes

use alloc::collections::BTreeMap;

#[cfg(feature = "std")]

use alloc::vec::Vec;

use azul_core::{

    dom::{DomId, NodeId, ScrollbarOrientation},

    events::EasingFunction,

    geom::{LogicalPosition, LogicalRect, LogicalSize},

    hit_test::ScrollPosition,

    styled_dom::NodeHierarchyItemId,

    task::{Duration, Instant},

};

#[cfg(feature = "std")]

use std::sync::{Arc, Mutex};

use crate::managers::hover::InputPointId;

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

use crate::solver3::scrollbar::compute_scrollbar_geometry_with_button_size;

/// Minimum change in scroll offset (in logical pixels) to consider the position

/// "actually moved" and mark the scroll state dirty.

const SCROLL_CHANGE_EPSILON: f32 = 0.01;

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

// Scroll Input Types (for timer-based physics architecture)

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

/// Classifies the source of a scroll input event.

///

/// This determines how the scroll physics timer processes the input:

/// - `TrackpadContinuous`: The OS already applies momentum — set position directly

/// - `WheelDiscrete`: Mouse wheel clicks — apply as impulse with momentum decay

/// - `Programmatic`: API-driven scroll — apply with optional easing animation

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

pub enum ScrollInputSource {

    /// Continuous trackpad gesture (macOS precise scrolling).

    /// Position is set directly — the OS handles momentum/physics.

    TrackpadContinuous,

    /// Trackpad gesture ended (fingers lifted off trackpad).

    /// Triggers spring-back if the scroll position is past the bounds

    /// (rubber-banding overshoot). The OS sends this when

    /// `NSEventPhaseEnded` or momentumPhaseEnded is detected.

    TrackpadEnd,

    /// Discrete mouse wheel steps (Windows/Linux mouse wheel).

    /// Applied as velocity impulse with momentum decay.

    WheelDiscrete,

    /// Programmatic scroll (scrollTo API, keyboard Page Up/Down).

    /// Applied with optional easing animation.

    Programmatic,

    /// Animated scroll toward an ABSOLUTE target offset (`delta` carries

    /// the target, not a delta): the physics timer seeks it with a

    /// critically-damped spring, so scroll-to-caret / scroll-to-page /

    /// find-result navigation glide instead of jumping, and a retarget

    /// mid-flight keeps the current velocity (no restart). Produced by

    /// `LayoutWindow::scroll_to_animated`.

    AnimateTo,

}

/// WHERE a scroll input physically came from - distinct from

/// [`ScrollInputSource`], which is the PROCESSING model. Different devices

/// deserve different curves (a wheel step animated with the trackpad's

/// long spring feels jarring), and accessibility drivers / test harnesses

/// need to identify themselves for correct treatment and diagnostics.

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

pub enum ScrollInputDevice {

    /// Discrete physical mouse wheel clicks.

    MouseWheel,

    /// Trackpad / precision touchpad gestures.

    Touchpad,

    /// Direct touchscreen panning.

    Touchscreen,

    /// Keyboard navigation (PageUp/PageDown/arrows/Home/End).

    Keyboard,

    /// Assistive technology (screen readers, switch access).

    Accessibility,

    /// An automated test driver (e2e harness, CI scenarios).

    TestDriver,

    /// API-driven (`scroll_to` / `scroll_to_animated` from app code).

    Programmatic,

    /// Origin unknown (legacy producers). Treated like `MouseWheel` for

    /// curve selection on discrete inputs.

    #[default]

    Unknown,

}

/// A single scroll input event to be processed by the physics timer.

///

/// Scroll inputs are recorded by the platform event handler and consumed

/// by the scroll physics timer callback. This decouples input recording

/// from physics simulation.

#[derive(Debug, Clone)]

pub struct ScrollInput {

    /// DOM containing the scrollable node

    pub dom_id: DomId,

    /// Target scroll node

    pub node_id: NodeId,

    /// Scroll delta (positive = scroll down/right)

    pub delta: LogicalPosition,

    /// When this input was recorded

    pub timestamp: Instant,

    /// How this input should be processed

    pub source: ScrollInputSource,

    /// Where this input physically came from (curve selection,

    /// accessibility, diagnostics).

    pub device: ScrollInputDevice,

}

/// Thread-safe queue for scroll inputs, shared between event handlers and timer callbacks.

///

/// Event handlers push inputs, the physics timer pops them. Protected by a Mutex

/// so that the timer callback (which only has `&CallbackInfo` / `*const LayoutWindow`)

/// can still consume pending inputs without needing `&mut`.

#[cfg(feature = "std")]

#[derive(Debug, Clone, Default)]

pub struct ScrollInputQueue {

    inner: Arc<Mutex<Vec<ScrollInput>>>,

}

#[cfg(feature = "std")]

impl ScrollInputQueue {

    /// Push a new scroll input (called from platform event handler)

    /// Take all pending inputs (called from timer callback)

        )

    /// Take at most `max_events` recent inputs, sorted by timestamp (newest last).

    /// Any older events beyond `max_events` are discarded.

    /// This prevents the physics timer from processing an unbounded backlog.

                    // Sort by timestamp ascending (oldest first), keep last N

        )

    /// Check if there are pending inputs without consuming them

}

// Scrollbar Component Types

/// Which component of a scrollbar was hit during hit-testing

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

pub enum ScrollbarComponent {

    /// The track (background) of the scrollbar

    Track,

    /// The draggable thumb (indicator of current scroll position)

    Thumb,

    /// Top/left button (scrolls by one page up/left)

    TopButton,

    /// Bottom/right button (scrolls by one page down/right)

    BottomButton,

}

/// Scrollbar geometry state (calculated per frame, used for hit-testing and rendering)

#[derive(Copy, Debug, Clone)]

pub struct ScrollbarState {

    /// Is this scrollbar visible? (content larger than container)

    pub visible: bool,

    /// Orientation

    pub orientation: ScrollbarOrientation,

    /// Base size (1:1 square, width = height). This is the unscaled size.

    pub base_size: f32,

    /// Scale transform to apply (calculated from container size)

    pub scale: LogicalPosition, // x = width scale, y = height scale

    /// Thumb position ratio (0.0 = top/left, 1.0 = bottom/right)

    pub thumb_position_ratio: f32,

    /// Thumb size ratio (0.0 = invisible, 1.0 = entire track)

    pub thumb_size_ratio: f32,

    /// Position of the scrollbar in the container (for hit-testing)

    pub track_rect: LogicalRect,

    /// Button size (square: `button_size` × `button_size`)

    pub button_size: f32,

    /// Usable track length after subtracting buttons

    pub usable_track_length: f32,

    /// Thumb length in pixels

    pub thumb_length: f32,

    /// Thumb offset from start of usable track region

    pub thumb_offset: f32,

}

impl ScrollbarState {

    /// Determine which component was hit at the given local position (relative to `track_rect`

    /// origin). Uses the shared geometry values (`button_size`, `usable_track_length`, `thumb_length`,

    /// `thumb_offset`) for consistent hit-testing.

            ScrollbarOrientation::Vertical => {

                // Top button

                // Bottom button

                // Thumb region starts after top button

                } else {

                }

            }

            ScrollbarOrientation::Horizontal => {

                // Left button

                // Right button

                // Thumb region starts after left button

                } else {

                }

            }

        }

}

/// Result of a scrollbar hit-test

///

/// Contains information about which scrollbar component was hit

/// and the position relative to both the track and the window.

#[derive(Debug, Clone, Copy)]

pub struct ScrollbarHit {

    /// DOM containing the scrollable node

    pub dom_id: DomId,

    /// Node with the scrollbar

    pub node_id: NodeId,

    /// Whether this is a vertical or horizontal scrollbar

    pub orientation: ScrollbarOrientation,

    /// Which component was hit (track, thumb, buttons)

    pub component: ScrollbarComponent,

    /// Position relative to `track_rect` origin

    pub local_position: LogicalPosition,

    /// Original global window position

    pub global_position: LogicalPosition,

}

// Core Scroll Manager

/// Manages all scroll state and animations for a window

#[derive(Debug, Clone, Default)]

pub struct ScrollManager {

    /// Maps (`DomId`, `NodeId`) to their scroll state

    states: BTreeMap<(DomId, NodeId), AnimatedScrollState>,

    /// Scrollbar geometry states (calculated per frame)

    scrollbar_states: BTreeMap<(DomId, NodeId, ScrollbarOrientation), ScrollbarState>,

    /// Thread-safe queue for scroll inputs (shared with timer callbacks)

    #[cfg(feature = "std")]

    pub scroll_input_queue: ScrollInputQueue,

    /// Raw wheel/trackpad delta recorded *this input pass*, regardless of whether

    /// a scrollable node was under the cursor. The scroll input queue only carries

    /// deltas destined for scrollable containers (consumed by the physics timer);

    /// this field additionally lets `determine_all_events` synthesize a `Scroll`

    /// event aimed at the hovered node so non-scroll-container widgets (e.g. the

    /// map, which treats wheel = zoom) can react via a `HoverEventFilter::Scroll`

    /// callback + `CallbackInfo::get_scroll_delta`. Set in

    /// [`Self::record_scroll_from_hit_test`]; read during event determination and

    /// callback dispatch, then cleared at the end of the pass.

    pub pending_wheel_event: Option<LogicalPosition>,

    /// Set when a scroll position changes; cleared after the display list

    /// is regenerated.  Used by the CPU renderer path to detect when the

    /// display list must be rebuilt even though the DOM hasn't changed.

    scroll_dirty: bool,

    /// Scroll-direction preference, applied ONCE in [`Self::record_scroll_input`]

    /// (the single chokepoint every platform's wheel/axis event flows through).

    ///

    /// `false` (default) = traditional desktop wheel: a raw "scroll down" event

    /// increases the offset (content moves up). `true` = natural: inverted.

    /// Replaces the per-platform hardcoded `-delta` negations so the sign lives

    /// in one configurable place ([`Self::set_natural_scroll`]).

    ///

    /// CAVEAT: on macOS and on Linux touchpads via libinput the OS/driver ALREADY

    /// applies the user's natural-scroll preference before azul sees the delta, so

    /// this flag must stay at its default there (we preserve current behavior) and

    /// primarily controls mouse-wheel direction on platforms that don't pre-apply.

    natural_scroll: bool,

}

/// The complete scroll state for a single node (with animation support)

#[derive(Debug, Clone)]

pub struct AnimatedScrollState {

    /// Current scroll offset (live, may be animating)

    pub current_offset: LogicalPosition,

    /// Ongoing smooth scroll animation, if any

    pub animation: Option<ScrollAnimation>,

    /// Last time scroll activity occurred (for fading scrollbars)

    pub last_activity: Instant,

    /// Bounds of the scrollable container

    pub container_rect: LogicalRect,

    /// Bounds of the total content (for calculating scroll limits)

    pub content_rect: LogicalRect,

    /// Virtual scroll size from `VirtualView` callback (if this node hosts a `VirtualView`).

    /// When set, clamp logic uses this instead of `content_rect` for max scroll bounds.

    pub virtual_scroll_size: Option<LogicalSize>,

    /// Virtual scroll offset from `VirtualView` callback

    pub virtual_scroll_offset: Option<LogicalPosition>,

    /// Per-node overscroll behavior for X axis (from CSS `overscroll-behavior-x`)

    pub overscroll_behavior_x: azul_css::props::style::scrollbar::OverscrollBehavior,

    /// Per-node overscroll behavior for Y axis (from CSS `overscroll-behavior-y`)

    pub overscroll_behavior_y: azul_css::props::style::scrollbar::OverscrollBehavior,

    /// Per-node overflow scrolling mode (from CSS `-azul-overflow-scrolling`)

    pub overflow_scrolling: azul_css::props::style::scrollbar::OverflowScrolling,

    /// CSS-resolved scrollbar thickness (from `scrollbar-width` property).

    /// Used for rendering and hit-testing. Defaults to 16.0 if not set.

    pub scrollbar_thickness: f32,

    /// Visual rendering width in CSS pixels (e.g. 8.0 for thin overlay).

    /// Non-zero even for overlay scrollbars. Falls back to `scrollbar_thickness` if 0.

    pub visual_width_px: f32,

    /// Whether this node also needs a horizontal scrollbar (affects vertical geometry)

    pub has_horizontal_scrollbar: bool,

    /// Whether this node also needs a vertical scrollbar (affects horizontal geometry)

    pub has_vertical_scrollbar: bool,

}

/// Details of an in-progress smooth scroll animation.

///

/// `pub` because `ScrollState::animation` is already a `pub` field holding it —

/// a private type behind a public field is only an error at the point somebody

/// outside this module reads it, which is why this compiled until the E2E

/// manager fingerprints needed to ask "is a scroll animation in flight?".

#[derive(Debug, Clone)]

pub struct ScrollAnimation {

    /// When the animation started

    start_time: Instant,

    /// Total duration of the animation

    duration: Duration,

    /// Scroll offset at animation start

    start_offset: LogicalPosition,

    /// Target scroll offset at animation end

    target_offset: LogicalPosition,

    /// Easing function for interpolation

    easing: EasingFunction,

}

/// Read-only snapshot of a scroll node's state, returned by `CallbackInfo` queries.

///

/// Provides all the information a timer callback needs to compute scroll physics

/// without requiring mutable access to the `ScrollManager`.

#[derive(Copy, Debug, Clone)]

pub struct ScrollNodeInfo {

    /// Current scroll offset

    pub current_offset: LogicalPosition,

    /// Container (viewport) bounds

    pub container_rect: LogicalRect,

    /// Content bounds (total scrollable area)

    pub content_rect: LogicalRect,

    /// Maximum scroll in X direction

    pub max_scroll_x: f32,

    /// Maximum scroll in Y direction

    pub max_scroll_y: f32,

    /// Per-node overscroll behavior for X axis

    pub overscroll_behavior_x: azul_css::props::style::scrollbar::OverscrollBehavior,

    /// Per-node overscroll behavior for Y axis

    pub overscroll_behavior_y: azul_css::props::style::scrollbar::OverscrollBehavior,

    /// Per-node overflow scrolling mode (auto vs touch)

    pub overflow_scrolling: azul_css::props::style::scrollbar::OverflowScrolling,

}

/// Result of a scroll tick, indicating what actions are needed

#[derive(Debug, Default)]

pub struct ScrollTickResult {

    /// If true, a repaint is needed (scroll offset changed)

    pub needs_repaint: bool,

    /// Nodes whose scroll position was updated this tick

    pub updated_nodes: Vec<(DomId, NodeId)>,

}

// ScrollManager Implementation

impl ScrollManager {

    /// Creates a new empty `ScrollManager`

        // Power-user / test override. Platform shells should call

        // `set_natural_scroll` from the OS preference; this env var wins so the

        // direction can be flipped without a rebuild and so tests are hermetic.

        #[cfg(feature = "std")]

    /// Set the scroll-direction preference. `true` = natural (content follows the

    /// gesture / inverted from the traditional wheel). Platform shells call this

    /// from the detected OS preference. See the `natural_scroll` field docs for the

    /// macOS/libinput pre-application caveat.

    /// Current scroll-direction preference (`true` = natural/inverted).

    /// The sign applied to a raw input delta to get the offset delta:

    /// `-1.0` traditional (default), `+1.0` natural. Centralises what used to be a

    /// hardcoded `-delta` at every platform call site.

    #[inline]

        } else {

        }

    /// Sizes of the internal maps — used by `AZ_E2E_TEST` to watch for

    /// unbounded growth across resize/tick iterations.

    /// Returns `true` if any scroll position changed since the last

    /// `clear_scroll_dirty()` call.

    /// Every `(DomId, NodeId)` this manager currently keys scroll state on.

    ///

    /// The E2E `assert_manager_invariants` op needs the KEY SET, not just the

    /// count `debug_counts()` reports: a key naming a node that no longer exists

    /// in `layout_results` is a dangling index (invariant X10), and a key set is

    /// the only way to see it from outside.

    #[must_use]

    /// Every `(DomId, NodeId)` whose `AnimatedScrollState` currently carries an

    /// easing animation. `has_active_animations()` is exactly

    /// `!animating_keys().is_empty()`; E2E invariant X2 asserts that identity.

    #[must_use]

    /// Clear the dirty flag after the display list has been regenerated.

    /// Build a map from `scroll_id` (`LocalScrollId`) to current scroll offset.

    ///

    /// Used by the CPU renderer to look up scroll positions at render time

    /// without embedding them in the display list.

    ///

    /// Takes `DomLayoutResult::scroll_id_to_node_id` — the SAME table the

    /// `WebRender` path resolves through (`wr_translate2::scroll_all_nodes`) —

    /// because it is keyed the way this manager is keyed: by DOM `NodeId`.

    ///

    /// It used to take the sibling table `scroll_ids` (layout-tree index →

    /// `scroll_id`) and index it with `node_id.index()`, i.e. it assumed the

    /// layout tree and the DOM share an index space. They do not: anonymous

    /// boxes and box splits are inserted during layout-tree construction, so

    /// any scroll container with a text sibling ahead of it sits at a

    /// different index. The lookup then missed, the container never appeared

    /// in this map, the compositor resolved its layer offset as `(0.0, 0.0)`

    /// and the content stayed frozen — while the scrollbar thumb, driven by

    /// the `(DomId, NodeId)`-keyed GPU value cache, kept tracking the wheel.

        }

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

    // Input Recording API (timer-based architecture)

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

    /// Records a scroll input event into the shared queue.

    ///

    /// This is the primary entry point for platform event handlers. Instead of

    /// directly modifying scroll positions, the input is queued for the scroll

    /// physics timer to process. This decouples input from physics simulation.

    ///

    /// The scroll-direction sign ([`Self::scroll_sign`]) is applied HERE — the

    /// single chokepoint every wheel/axis event flows through — so platform shells

    /// pass the RAW delta and no longer hardcode `-delta` at each call site.

    ///

    /// Returns `true` if the physics timer should be started (i.e., there are

    /// now pending inputs and no timer is running yet).

    #[cfg(feature = "std")]

    /// High-level entry point for platform event handlers: performs hit-test lookup

    /// and queues the input for the physics timer, instead of directly modifying offsets.

    ///

    /// Returns `Some((dom_id, node_id, should_start_timer))` if a scrollable node was found.

    /// The caller should start `SCROLL_MOMENTUM_TIMER_ID` when `should_start_timer` is true.

    #[cfg(feature = "std")]

        // Record the raw wheel delta for this pass unconditionally — even when the

        // cursor isn't over a scroll container — so a `Scroll` event can be aimed

        // at the hovered node (wheel-as-zoom widgets like the map rely on this).

        // MWA-B2: nested scroll containers — innermost-first with boundary

        // handoff. The previous ascending iteration always picked the

        // OUTERMOST scrollable ancestor (BTreeMap keys ascend; ancestors

        // have lower arena NodeIds), so wheeling over a list inside a

        // scrollable page scrolled the page instead of the list. We now

        // walk innermost-first and give the event to the first candidate

        // that can still move in the delta's direction (the web's default

        // overscroll handoff); when every candidate is pinned, the

        // innermost scrollable wins so the gesture still targets the node

        // under the pointer.

        );

    /// MWA-B2: choose the scroll node a wheel/trackpad event should drive.

    ///

    /// `candidates` must be ordered innermost-first; `eff_x`/`eff_y` are the

    /// direction-normalized deltas (post `scroll_sign()`: positive = offset

    /// grows = view moves toward content's down/right). The first candidate

    /// with remaining travel in a moved direction wins; if every candidate

    /// is pinned, the innermost scrollable is returned so the gesture still

    /// anchors under the pointer (matches CSS default overscroll behavior).

    {

        }

    /// MWA-B10: the a11y tree's scroll surface for a node — current offset

    /// plus max travel per axis, or `None` when the node isn't scrollable.

    /// Screen readers use this (with the ScrollUp/Down/... actions) to

    /// drive the same inbound handler mouse users exercise.

    /// `true` when the node still has travel in the direction of the

    /// normalized delta on at least one moved axis — the boundary-handoff

    /// test for [`select_scroll_target`](Self::select_scroll_target).

        const EPS: f32 = 0.5;

        };

        } else {

        };

        } else {

        };

    /// Get a clone of the scroll input queue (for sharing with timer callbacks).

    ///

    /// The timer callback stores this in its `RefAny` data and calls `take_all()`

    /// each tick to consume pending inputs.

    #[cfg(feature = "std")]

    /// Advances scroll animations by one tick, returns repaint info

    #[allow(clippy::suboptimal_flops)] // mul_add not guaranteed faster/available without target +fma; keep explicit a*b+c

    // Instant is a ref-counted FFI clock handle; called by every dll backend's event loop by value.

    #[allow(clippy::needless_pass_by_value)]

        }

    /// Returns `true` if any scroll node has an active easing animation.

    ///

    /// Used by GPU render paths to skip rendering when the UI is completely

    /// static (no scroll animations, no layout changes).

    /// Finds the closest scroll-container ancestor for a given node.

    ///

    /// Walks up the node hierarchy to find a node that is registered as a

    /// scrollable node in this `ScrollManager`. Returns `None` if no scrollable

    /// ancestor is found.

        }

    /// Check if a node is scrollable (has overflow:scroll/auto and overflowing content)

    ///

    /// Uses `virtual_scroll_size` (when set) instead of `content_rect` for the

    /// overflow check, so `VirtualView` nodes with large virtual content are correctly

    /// identified as scrollable even when only a small subset is rendered.

    // +spec:overflow:4000a6 - scroll position as offset from scroll origin within scrollport

    /// Sets scroll position immediately (no animation), clamped to valid bounds.

    /// Sets scroll position immediately without clamping.

    ///

    /// Used by the scroll physics timer which does its own rubber-band clamping.

    /// Allows the offset to go outside [0, `max_scroll`] for overscroll/rubber-banding.

    /// Scrolls by a delta amount with animation

    /// Scrolls to an absolute position with animation

    ///

    /// If duration is zero, the position is set immediately without animation.

        // For zero duration, set position immediately

        };

    /// Updates the container and content bounds for a scrollable node

    /// Updates virtual scroll bounds for a `VirtualView` node.

    ///

    /// Called after `VirtualView` callback returns to propagate the virtual content size

    /// to the `ScrollManager`. Clamp logic then uses `virtual_scroll_size` (when set)

    /// instead of `content_rect` for max scroll bounds.

    ///

    /// If no scroll state exists yet for this node (because `register_or_update_scroll_node`

    /// hasn't been called yet), this creates a default state so the virtual size is preserved.

            // AzInstant (System on std, safe Tick on no-clock targets) — not the

            // WASM-panicking std::time::Instant::now(). (A refinement would thread

            // the window's get_system_time_fn callback through for hookability.)

        // Re-clamp with new virtual bounds

    /// Returns the current scroll offset for a node

    /// Returns the timestamp of last scroll activity for a node

    /// Returns the internal scroll state for a node

    /// Returns a read-only snapshot of a scroll node's state.

    ///

    /// This is the preferred way for timer callbacks to query scroll state,

    /// since they only have `&CallbackInfo` (read-only access).

    ///

    /// When `virtual_scroll_size` is set (for `VirtualView` nodes), the max scroll

    /// bounds are computed from the virtual size instead of `content_rect`.

    /// Returns all scroll positions for nodes in a specific DOM

    ///

    /// # `ScrollPosition` coordinate convention (MIXED — read before consuming)

    ///

    /// The two rects of the emitted [`ScrollPosition`] do NOT live in the same

    /// space, and a consumer that subtracts one origin from the other gets

    /// garbage:

    ///

    /// - `parent_rect` — the container's border box in **absolute window

    ///   coordinates** (`calculated_positions[node]`, see

    ///   `shell2::common::layout::register_scroll_nodes`). Only `size` is

    ///   meaningful to most consumers; the origin exists for `scroll_into_view`.

    /// - `children_rect.origin` — the **scroll offset itself**, i.e.

    ///   `current_offset`: the distance already scrolled, measured from the

    ///   scroll origin, clamped to `[0, content − container]`. It is NOT the

    ///   absolute position of the scrolled content, and it is NOT relative to

    ///   `parent_rect.origin`. Content is painted at `position − offset`

    ///   (`cpurender::raster`), so a positive value means "scrolled down/right".

    /// - `children_rect.size` — the scrollable content size (the `VirtualView`

    ///   virtual size when one was reported, else the laid-out content size).

    ///

    /// `content_rect.origin` is never carried out of here because it is always

    /// zero in the state (`register_or_update_scroll_node` builds it that way,

    /// and `clamp` reads only its size) — the absolute-content-rect reading of

    /// `children_rect` is not even representable.

    ///

    /// The round trip is the identity: `LayoutWindow::set_scroll_position`

    /// feeds `children_rect.origin` straight back into `set_scroll_position`.

        // M12.7: iterating an EMPTY hashbrown map (RawIterRange) mis-lifts to

        // wasm and loops forever (same class as the font-id / GPU-cache loops).

        // For the headless web path `states` is empty; guard it (len-based, no

        // iteration). Desktop unchanged.

                // Use virtual_scroll_size (from VirtualView callback) when available,

                // otherwise fall back to content_rect.size from layout.

    /// Registers or updates a scrollable node with its container and content sizes.

    /// This should be called after layout for each node that has overflow:scroll or overflow:auto

    /// with overflowing content.

    ///

    /// If the node already exists, updates container/content rects without changing scroll offset.

    /// If the node is new, initializes with zero scroll offset.

    // Scrollbar State Management

    /// Calculate scrollbar states for all visible scrollbars.

    /// This should be called once per frame after layout is complete.

    /// Uses the shared `compute_scrollbar_geometry()` for consistent geometry.

        // Uses virtual_scroll_size (when set) for the overflow check and thumb ratio,

        // so VirtualView nodes with large virtual content show correct scrollbar geometry.

                        ScrollbarOrientation::Vertical => (

                        ),

                        ScrollbarOrientation::Horizontal => (

                        ),

                    };

                    );

        }

    /// Calculate scrollbar state using the shared `compute_scrollbar_geometry()`.

        } else {

        };

        };

        };

        // Overlay scrollbars (thickness == 0 from layout) have no arrow buttons

        );

        // Build ScrollbarState from the shared geometry

            ScrollbarOrientation::Vertical => {

            }

            ScrollbarOrientation::Horizontal => {

            }

        };

    /// Get scrollbar state for hit-testing

    /// Iterate over all visible scrollbar states

    // Scrollbar Hit-Testing

    /// Hit-test scrollbars for a specific node at the given position.

    /// Returns Some if the position is inside a scrollbar for this node.

        // Check both vertical and horizontal scrollbars for this node

        ] {

            };

            // Check if position is inside scrollbar track using LogicalRect::contains

            // Calculate local position relative to track origin

            );

            // Determine which component was hit

        }