//! 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.

//! - **Gesture manager** (gesture.rs): Tracks drag state and emits

//!   `AutoScrollDirection` — does NOT modify scroll offsets directly.

//! - **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

//! - ExternalScrollId mapping for WebRender integration

//! - 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::{ExternalScrollId, ScrollPosition},

    styled_dom::NodeHierarchyItemId,

    task::{Duration, Instant},

};

#[cfg(feature = "std")]

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

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

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)]

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,

}

/// 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,

}

/// 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)

        } else {

        }

    /// 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

        } else {

        }

    /// 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(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>,

    /// Maps (DomId, NodeId) to WebRender ExternalScrollId

    external_scroll_ids: BTreeMap<(DomId, NodeId), ExternalScrollId>,

    /// Counter for generating unique ExternalScrollId values

    next_external_scroll_id: u64,

    /// 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,

    /// 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,

}

/// 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

#[derive(Debug, Clone)]

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(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

    /// 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.

    /// 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.

    ///

    /// `scroll_ids` maps layout-tree node index → scroll_id. We need to

    /// convert our (DomId, NodeId) keys to scroll_ids.

            // Find the scroll_id for this node_id by searching scroll_ids

            // (scroll_ids maps layout_index → scroll_id, and node_id.index() == layout_index

            // for the root DOM)

        }

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

    // 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.

    ///

    /// 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")]

            }

        }

    /// 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

        }

    /// 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

        // 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.

    // ExternalScrollId Management

    /// Register a scroll node and get its ExternalScrollId for WebRender.

    /// If the node already has an ID, returns the existing one.

        use azul_core::hit_test::PipelineId;

        // Generate new ExternalScrollId (id, pipeline_id)

        // PipelineId = (PipelineSourceId: u32, u32)

        // Use dom_id.inner for PipelineSourceId, node_id.index() for second part

    /// Get the ExternalScrollId for a node (returns None if not registered)

    /// Iterate over all registered external scroll IDs

    // 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.

        // Collect vertical scrollbar states

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

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

                );

        // Collect horizontal scrollbar states

                );

        // Insert all states

    /// 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

        }

    /// Perform hit-testing for all scrollbars at the given global position.

    ///

    /// This iterates through all visible scrollbars in reverse z-order (top to bottom)

    /// and returns the first hit. Use this when you don't know which node to check.

    ///

    /// For better performance, use `hit_test_scrollbar()` when you already have

    /// a hit-tested node from WebRender.

        // Iterate in reverse order to hit top-most scrollbars first

        {

            // Check if position is inside scrollbar track

            // Calculate local position relative to track origin

            );

            // Determine which component was hit

        }

}

// AnimatedScrollState Implementation

impl AnimatedScrollState {

    // +spec:overflow:60f6a1 - scroll origin defaults to block-start inline-start corner (0,0)

    /// Create a new scroll state initialized at offset (0, 0).

    /// Clamp a scroll position to valid bounds (0 to max_scroll).

    ///

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

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

}

// Easing Functions

/// Apply an easing function to a normalized time value (0.0 to 1.0).

/// Used by ScrollAnimation::tick() for smooth scroll animations.

        EasingFunction::EaseInOut => {

            } else {

            }

        }

    }

// Legacy type alias

pub type ScrollStates = ScrollManager;

impl ScrollManager {

    /// Remap NodeIds after DOM reconciliation

    ///

    /// When the DOM is regenerated, NodeIds can change. This method updates all

    /// internal state to use the new NodeIds based on the provided mapping.

        // Only remap nodes that actually moved (old_id != new_id).

        // Nodes NOT in the map are stable (kept same NodeId) — don't touch them.

        // We cannot distinguish "not moved" from "removed" with just node_moves,

        // so we conservatively keep states that aren't in the map.

        // Remap states

        }

        // Remap external_scroll_ids

        }

        // Remap scrollbar_states

        }

}