//! Scroll physics timer callback — the core of the timer-based scroll architecture.

//!

//! This module implements the scroll physics as a regular timer callback, using

//! the same transactional `push_change(CallbackChange::ScrollTo)` pattern as all

//! other state modifications. There is nothing special about the scroll timer —

//! it is a normal user-space timer that happens to be started by the framework.

//!

//! # Architecture

//!

//! ```text

//! Platform Event Handler

//!   → ScrollManager.record_scroll_input(ScrollInput)

//!   → starts SCROLL_MOMENTUM_TIMER if not running

//!

//! Timer fires (every timer_interval_ms from ScrollPhysics):

//!   1. queue.take_recent(100) — consume up to 100 most recent inputs

//!   2. For each input:

//!      - TrackpadContinuous → set offset directly (OS handles momentum)

//!      - WheelDiscrete → add impulse to velocity

//!      - Programmatic → set target position

//!   3. Integrate physics: velocity decay, clamping

//!   4. push_change(CallbackChange::ScrollTo) for each updated node

//!   5. Return continue_and_update() or terminate_unchanged()

//! ```

//!

//! # Key Design Decisions

//!

//! - **No mutable access to LayoutWindow needed**: Uses `CallbackChange::ScrollTo`

//!   (the same transactional pattern as all other callbacks).

//! - **Shared queue via Arc<Mutex>**: The `ScrollInputQueue` is cloned into the

//!   timer's `RefAny` data. Event handlers push, timer pops.

//! - **Platform-independent**: Works on macOS, Windows, Linux — anywhere timers work.

//! - **Self-terminating**: When all velocities are below threshold and no inputs

//!   pending, the timer returns `TerminateTimer::Terminate`.

use alloc::collections::BTreeMap;

use azul_core::{

    callbacks::{TimerCallbackReturn, Update},

    dom::DomId,

    geom::LogicalPosition,

    refany::RefAny,

    styled_dom::NodeHierarchyItemId,

    task::TerminateTimer,

};

use crate::{

    managers::scroll_state::{

        ScrollInput, ScrollInputDevice, ScrollInputQueue, ScrollInputSource, ScrollNodeInfo,

    },

    timer::TimerCallbackInfo,

};

use azul_css::props::style::scrollbar::{ScrollPhysics, OverflowScrolling, OverscrollBehavior};

/// Maximum number of scroll events processed per timer tick.

/// Older events beyond this limit are discarded to keep the physics

/// simulation bounded and testable.

const MAX_SCROLL_EVENTS_PER_TICK: usize = 100;

/// Assumed framerate for converting between per-frame and per-second quantities.

/// Used both in wheel impulse conversion and friction decay so the two stay coupled.

const ASSUMED_FPS: f32 = 60.0;

/// State stored in the timer's `RefAny` data.

///

/// Contains the shared input queue, per-node velocity state, and the global

/// scroll physics configuration from `SystemStyle`.

#[derive(Debug)]

pub struct ScrollPhysicsState {

    /// Shared input queue — same Arc as `ScrollManager.scroll_input_queue`

    pub input_queue: ScrollInputQueue,

    /// Per-node velocity tracking

    pub node_velocities: BTreeMap<(DomId, NodeId), NodeScrollPhysics>,

    /// Per-node "forced position" from programmatic scroll (hard-clamped)

    pub pending_positions: BTreeMap<(DomId, NodeId), LogicalPosition>,

    /// Per-node "forced position" from trackpad scroll (rubber-band clamped)

    pub pending_trackpad_positions: BTreeMap<(DomId, NodeId), LogicalPosition>,

    /// Absolute offsets that `AnimateTo` / wheel-glide inputs are seeking,

    /// per node, together with the DEVICE that asked for the seek (device

    /// picks the spring duration: physical wheel clicks get the short

    /// `wheel_animate_bounce_ms` glide, everything else

    /// `bounce_back_duration_ms`). The integration loop applies a

    /// critically-damped spring toward each and removes the entry on

    /// convergence (snap to the exact target).

    pub animate_targets: BTreeMap<(DomId, NodeId), (LogicalPosition, ScrollInputDevice)>,

    /// Global scroll physics configuration (from `SystemStyle`)

    pub scroll_physics: ScrollPhysics,

}

/// For convenience, re-export `NodeId`

use azul_core::id::NodeId;

/// Per-node scroll physics state

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

pub struct NodeScrollPhysics {

    /// Current velocity in pixels/second

    pub velocity: LogicalPosition,

    /// Whether this node is currently in a rubber-band overshoot state

    pub is_rubber_banding: bool,

}

impl ScrollPhysicsState {

    /// Create a new physics state with the shared input queue and global config

    /// Returns true if any node has non-zero velocity or there are pending inputs

}

/// The scroll physics timer callback.

///

/// This is a normal timer callback registered with `SCROLL_MOMENTUM_TIMER_ID`.

/// It consumes pending scroll inputs, applies physics, and pushes `ScrollTo` changes.

///

/// Uses the `ScrollPhysics` configuration from `SystemStyle` for friction,

/// velocity thresholds, wheel multiplier, and rubber-banding parameters.

/// Per-node `OverflowScrolling` and `OverscrollBehavior` CSS properties are

/// respected to decide whether each node gets rubber-banding.

///

/// `AZ_SCROLL_DEBUG=1` turns on a per-event / per-tick trace of the scroll

/// pipeline.

///

/// It exists because the jitter reported on X11 and Wayland — a wheel scroll

/// that smooths, then jumps back and forward, damping toward the middle — could

/// not be reproduced from the code alone. Six candidate causes were eliminated

/// (spring stiffness, `dt`, device classification, X11 double ingress, the shm

/// slot count, and Wayland's slot catch-up), and the remaining ones need to

/// know what the platform actually DELIVERED, not what we think it delivers.

///

/// Off by default and checked once: this sits on the 16 ms tick and on every

/// scroll event, so it must cost nothing when unset.

#[cfg(feature = "std")]

#[must_use]

    use std::sync::OnceLock;

    static ON: OnceLock<bool> = OnceLock::new();

#[cfg(not(feature = "std"))]

#[must_use]

pub const fn scroll_debug_enabled() -> bool {

    false

}

/// One line per scroll event as the PLATFORM delivered it, before any physics.

///

/// Call this from the platform ingress (x11 `handle_scroll_input`, wayland

/// `axis`), so a log tells us the raw delta, whether the backend called it

/// continuous, and which source/device it was classified as. That is the piece

/// no amount of reading the code can supply.

#[cfg(feature = "std")]

    );

#[cfg(not(feature = "std"))]

pub fn trace_scroll_input(_: &str, _: f32, _: f32, _: bool, _: &str, _: &str) {}

/// # C API

///

/// This function has `extern "C"` ABI so it can be used as a `TimerCallbackType`.

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

#[allow(clippy::cast_precision_loss)] // bounded graphics/coord/counter/fixed-point cast

#[allow(clippy::too_many_lines, clippy::cognitive_complexity)] // large but cohesive: single-purpose layout/render/parse routine (one branch per case)

    // Downcast the RefAny to our physics state

    };

    // Extract physics config values

    // Sanitize: `.max(0.0)` turns a NaN or negative max_velocity (a plain repr(C)

    // field with no validation, reachable from a bad SystemStyle) into 0.0, so the

    // `velocity.clamp(-max_velocity, max_velocity)` below never hits f32::clamp's

    // `min > max` panic — which in this extern "C" callback would ABORT the process.

    // 1. Take at most MAX_SCROLL_EVENTS_PER_TICK recent inputs from the shared queue

            ScrollInputSource::TrackpadContinuous => {

                // Trackpad: OS handles momentum. Apply delta directly as position change.

                //

                // ACCUMULATE onto whatever this tick already staged for the

                // node, falling back to the committed offset. `current_offset`

                // does NOT move while this callback runs — the ScrollTo changes

                // are applied after it returns — so basing every event of the

                // batch on it and then `insert`ing meant N events in one tick

                // collapsed to the LAST delta. A 120 Hz trackpad against the

                // 16 ms tick routinely queues two events, i.e. half the gesture

                // was silently dropped, which is what "scrolling fights itself"

                // feels like from the outside.

                // Kill any existing velocity for this node (trackpad overrides momentum)

            }

            ScrollInputSource::WheelDiscrete => {

                // Input provenance decides the math. A PHYSICAL wheel click

                // glides toward an accumulating ABSOLUTE target (short

                // critically-damped spring, hard stop on arrival) — running

                // discrete clicks through the velocity+friction model gave

                // them the trackpad's floaty momentum tail, which feels

                // jarring on a ratcheting wheel. Consecutive clicks extend

                // the target (glide keeps going), they don't stack impulses.

                // Touchpads that surface wheel-style events (Windows

                // precision-touchpad fallback, X11 smooth scrolling) and

                // test drivers keep the velocity model: their deltas are

                // fine-grained and the momentum tail is correct for them.

                    ScrollInputDevice::MouseWheel | ScrollInputDevice::Unknown

                ) {

                    {

                        // Clamp into the scrollable range: a wheel click at

                        // the boundary must not build up an off-range target

                        // (chaining to the parent scroller happens at

                        // hit-test time in the ScrollManager, per click).

                        // Ensure the seek loop visits this node; keep any

                        // in-flight velocity so a retarget stays continuous.

            }

            ScrollInputSource::Programmatic => {

                // Programmatic: Set position directly. Accumulates within the

                // tick for the same reason as TrackpadContinuous above.

            }

            ScrollInputSource::AnimateTo => {

                // `delta` carries the ABSOLUTE target. Clamp into the node's

                // scrollable range; keep any existing velocity so a retarget

                // mid-flight stays continuous (the spring redirects it).

            }

            ScrollInputSource::TrackpadEnd => {

                // Trackpad gesture ended (fingers lifted).

                // If the scroll position is past the bounds (rubber-banding overshoot),

                // start a spring-back animation to snap back to the boundary.

                // Peek (do NOT remove) the position this tick has staged for

                // the node. It used to read `pending_positions`, the

                // PROGRAMMATIC map, which a trackpad gesture never writes — so

                // the overshoot decision was made from the stale, pre-tick

                // offset and the spring-back fought the finger's last delta.

                // Peeking rather than removing leaves step 3 to apply the

                // rubber-band clamp, which is the write that must win.

                        // Preserve the overshot position for the spring-back animation.

                        // Must use unclamped so the overshot position is NOT clamped to bounds.

                        //

                        // Skipped when step 3 is already going to write this

                        // node from a staged position: that write is the

                        // rubber-band-clamped one and must be the only one, or

                        // the node gets two conflicting offsets in one tick.

            }

        }

    }

    // 2. Integrate velocity physics for wheel-based momentum

    // Residual momentum from nodes that hit their boundary this tick, to be

    // transferred up the scroll chain after the iteration (can't mutate

    // node_velocities mid-loop).

    // AnimateTo targets, read-only during the iteration (the map itself is

    // mutated after the loop via `converged_targets`).

    // Nodes the finger moved THIS tick. Both writers below end in a

    // `scroll_to_unclamped` for the same node and the velocity one is applied

    // last, so without this the spring silently overwrote the gesture's delta

    // with a position integrated from the STALE pre-tick offset — the direct

    // "physics fighting the actual scroll" the user reported. The finger wins

    // while it is down; the spring resumes next tick from the committed offset.

        // Get current scroll info for clamping and per-node CSS config

        };

        // Target-seeking spring (scroll_to_animated): a critically-damped

        // pull toward the absolute target — the same F = -k*x - c*v the

        // rubber-band uses, with x measured from the TARGET instead of the

        // boundary. Close enough + slow enough snaps EXACTLY onto the

        // target and retires it (no asymptotic crawl).

            {

            // Provenance picks the curve: wheel clicks want a short snappy

            // glide, programmatic/other seeks the platform bounce duration.

                ScrollInputDevice::MouseWheel | ScrollInputDevice::Unknown => {

                }

            };

        // Determine if this node allows rubber-banding

        // Calculate current overshoot amounts

        // If we're in a rubber-band overshoot, apply critically-damped spring force.

        // F = -k*x - c*v  where c = 2*sqrt(k) for critical damping (no oscillation).

        // Skip if velocity is negligible and not rubber-banding or seeking

        {

        // Apply velocity to position

        // The whole jitter question in one line: what this tick READ, what the

        // writers wanted, and what it is about to COMMIT. If the offset a tick

        // reads is not the offset the previous tick wrote, the spring is

        // integrating from a stale base — and that is the oscillation.

        #[cfg(feature = "std")]

                dom_id, node_id,

                info.current_offset.x, info.current_offset.y,

                node_physics.velocity.x, node_physics.velocity.y,

                displacement.x, displacement.y,

                raw_new_x, raw_new_y,

                info.max_scroll_x, info.max_scroll_y,

            );

        // Clamp with or without rubber-banding

            // Allow overshoot with diminishing returns (elasticity)

        } else {

        };

        } else {

        };

        // Apply exponential friction decay

        // At edges without rubber-banding: hand the remaining momentum to a

        // scrollable ancestor, then kill this node's velocity (MWA-C-scroll:

        // a fling that exhausts the inner container mid-momentum continues

        // on the outer one, mirroring the input-time boundary handoff in

        // select_scroll_target). overscroll-behavior contain/none on this

        // node stops the chain, matching CSS scroll-chaining semantics.

        // Check if rubber-banding spring-back is almost complete

        // Snap to zero if below threshold after decay

    }

    // Clean up nodes with zero velocity and not rubber-banding

    // MWA-C-scroll: transfer residual momentum up the scroll chain — walk the

    // scroll-parent chain to the nearest ancestor that can still consume in

    // the fling's direction and seed it with the leftover velocity (picked up

    // by the integration loop on the next tick; is_active() keeps the timer

    // alive because the entry lands in node_velocities).

    // Retire converged AnimateTo targets (snapped exactly this tick).

            };

            };

            // This ancestor is itself exhausted in the fling's direction —

            // respect ITS overscroll-behavior before chaining past it.

        }

    }

    // 3. Push ScrollTo changes for all updated positions

    // Apply programmatic position changes (hard-clamped to bounds)

    }

    // Apply trackpad position changes (rubber-band clamped for elastic overshoot)

    // Uses scroll_to_unclamped because the physics timer does its own rubber-band clamping.

                LogicalPosition {

                    } else {

                    },

                    } else {

                    },

                }

    }

    // Apply velocity-based position changes (uses unclamped: physics already handles rubber-band clamping)

    // 4. Decide whether to continue or terminate

    } else {

        // No more velocity, no pending inputs → terminate the timer

    }

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

// Rubber-banding Helper Functions

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

/// Determines if a node allows rubber-banding on a given axis based on:

/// 1. Whether the axis actually has overflow (`max_scroll` > 0)

/// 2. Per-node `overflow_scrolling` CSS property (-azul-overflow-scrolling)

/// 3. Per-node `overscroll_behavior` CSS property (overscroll-behavior-x/y)

/// 4. Global `overscroll_elasticity` from `ScrollPhysics`

/// Calculate how far a position has overshot the valid scroll range.

/// Returns positive for overshoot past max, negative for overshoot past min, 0 if in range.

    } else {

    }

/// Rubber-band clamping: allows overshoot up to `max_overscroll`, with

/// diminishing returns (elasticity) so it feels "springy".

///

/// The further you overshoot, the harder it becomes to scroll further.

    } else {

    };

    // Diminishing returns: as overshoot increases, actual displacement decreases

    // Formula: actual = max_overscroll * (1 - e^(-elasticity * overshoot / max_overscroll))

    } else {

    };

    } else {

    }

/// Convert `deceleration_rate` (0.0 - 1.0) to a friction constant for exponential decay.

/// Higher `deceleration_rate` = less friction (slower deceleration).

    // deceleration_rate ~0.95 (fast) → friction ~0.05

    // deceleration_rate ~0.998 (iOS-like) → friction ~0.002

/// Calculate spring constant from bounce-back duration.

/// Higher k = faster spring back. Approximate: k ≈ (2π / duration)²

#[allow(clippy::cast_precision_loss)] // bounded graphics/coord/counter/fixed-point cast

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

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

// Generated adversarial tests

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

#[cfg(all(test, feature = "std"))]

#[allow(

    clippy::float_cmp,

    clippy::cast_precision_loss,

    clippy::too_many_lines,

    clippy::unreadable_literal

)]

mod autotest_generated {

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

    use azul_core::{

        dom::{DomNodeId, OptionDomNodeId},

        geom::{LogicalRect, LogicalSize, OptionLogicalPosition},

        gl::OptionGlContextPtr,

        hit_test::ScrollPosition,

        refany::OptionRefAny,

        resources::RendererResources,

        task::Instant,

        window::{MonitorVec, RawWindowHandle},

    };

    use azul_css::system::SystemStyle;

    use rust_fontconfig::FcFontCache;

    use super::*;

    #[cfg(feature = "icu")]

    use crate::icu::IcuLocalizerHandle;

    use crate::{

        callbacks::{CallbackChange, CallbackInfo, CallbackInfoRefData, ExternalSystemCallbacks},

        window::LayoutWindow,

        window_state::FullWindowState,

    };

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

    // Harness

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

    /// A live callback environment: an otherwise-empty `LayoutWindow` (optionally

    /// carrying registered scroll nodes) plus the shared change log that

    /// `scroll_to` / `scroll_to_unclamped` push into. `tick()` runs one full

    /// timer callback against it, so the physics loop can be driven repeatedly.

    struct Env<'a> {

        ref_data: &'a CallbackInfoRefData<'a>,

        changes: &'a Arc<Mutex<Vec<CallbackChange>>>,

    }

    impl Env<'_> {

        /// Run one `scroll_physics_timer_callback` tick against this environment.

        fn tick(&mut self, data: &RefAny) -> TimerCallbackReturn {

            let info = CallbackInfo::new(

                self.ref_data,

                self.changes,

                DomNodeId {

                    dom: DomId::ROOT_ID,

                    node: NodeHierarchyItemId::NONE,

                },

                OptionLogicalPosition::None,

                OptionLogicalPosition::None,

            );

            let timer_info =

                TimerCallbackInfo::create(info, OptionDomNodeId::None, Instant::now(), 0, false);

            scroll_physics_timer_callback(data.clone(), timer_info)

        }

        /// Drain the `CallbackChange`s pushed so far.

        fn take_changes(&self) -> Vec<CallbackChange> {

            self.changes

                .lock()

                .map(|mut c| core::mem::take(&mut *c))

                .unwrap_or_default()

        }

        /// Drain the change log, asserting every entry is a `ScrollTo`, and

        /// return `(node index, position, unclamped)` for each.

        fn take_scroll_tos(&self) -> Vec<(usize, LogicalPosition, bool)> {

            self.take_changes()

                .iter()

                .map(|change| {

                    let CallbackChange::ScrollTo {

                        node_id,

                        position,

                        unclamped,

                        ..

                    } = change

                    else {

                        panic!("expected only ScrollTo changes, got {change:?}");

                    };

                    let idx = node_id

                        .into_crate_internal()

                        .expect("ScrollTo must name a concrete node")

                        .index();

                    (idx, *position, *unclamped)

                })

                .collect()

        }

    }

    /// Builds a callback environment. `setup` may register scroll nodes on the

    /// `LayoutWindow` before it is frozen behind the shared reference.

    fn with_env<R>(setup: impl FnOnce(&mut LayoutWindow), f: impl FnOnce(&mut Env<'_>) -> R) -> R {

        let mut layout_window =

            LayoutWindow::new(FcFontCache::default()).expect("LayoutWindow::new failed");

        setup(&mut layout_window);

        let renderer_resources = RendererResources::default();

        let previous_window_state: Option<FullWindowState> = None;

        let current_window_state = FullWindowState::default();

        let gl_context = OptionGlContextPtr::None;

        let scroll_states: BTreeMap<DomId, BTreeMap<NodeHierarchyItemId, ScrollPosition>> =

            BTreeMap::new();

        let window_handle = RawWindowHandle::Unsupported;

        let system_callbacks = ExternalSystemCallbacks::rust_internal();

        let ref_data = CallbackInfoRefData {

            layout_window: &layout_window,

            renderer_resources: &renderer_resources,

            previous_window_state: &previous_window_state,

            current_window_state: &current_window_state,

            gl_context: &gl_context,

            current_scroll_manager: &scroll_states,

            current_window_handle: &window_handle,

            system_callbacks: &system_callbacks,

            system_style: Arc::new(SystemStyle::default()),

            monitors: Arc::new(Mutex::new(MonitorVec::from_const_slice(&[]))),

            #[cfg(feature = "icu")]

            icu_localizer: IcuLocalizerHandle::default(),

            ctx: OptionRefAny::None,

        };

        let changes: Arc<Mutex<Vec<CallbackChange>>> = Arc::new(Mutex::new(Vec::new()));

        let mut env = Env {

            ref_data: &ref_data,

            changes: &changes,

        };

        f(&mut env)

    }

    /// Registers node `idx` of the root DOM as a scrollable node with a

    /// `container_w x container_h` viewport over `content_w x content_h` content

    /// (so `max_scroll_x = content_w - container_w`, clamped at 0).

    fn register_node(

        window: &mut LayoutWindow,

        idx: usize,

        container: (f32, f32),

        content: (f32, f32),

    ) {

        window.scroll_manager.register_or_update_scroll_node(

            DomId::ROOT_ID,

            NodeId::new(idx),

            LogicalRect::new(

                LogicalPosition::zero(),

                LogicalSize::new(container.0, container.1),

            ),

            LogicalSize::new(content.0, content.1),

            Instant::now(),

            0.0,

            0.0,

            false,

            false,

        );

    }

    /// A scroll input for node `idx` of the root DOM (device = TestDriver,

    /// which keeps the legacy velocity model on WheelDiscrete).

    fn input(idx: usize, delta: (f32, f32), source: ScrollInputSource) -> ScrollInput {

        input_dev(idx, delta, source, ScrollInputDevice::TestDriver)

    }

    /// A scroll input with an explicit device provenance.

    fn input_dev(

        idx: usize,

        delta: (f32, f32),

        source: ScrollInputSource,

        device: ScrollInputDevice,

    ) -> ScrollInput {

        ScrollInput {

            dom_id: DomId::ROOT_ID,

            node_id: NodeId::new(idx),

            delta: LogicalPosition::new(delta.0, delta.1),

            timestamp: Instant::now(),

            source,

            device,

        }

    }

    /// A `ScrollPhysicsState` wrapped in a `RefAny`, plus the queue that feeds it.

    fn state_with(physics: ScrollPhysics) -> (RefAny, ScrollInputQueue) {

        let queue = ScrollInputQueue::new();

        let state = ScrollPhysicsState::new(queue.clone(), physics);

        (RefAny::new(state), queue)

    }

    fn key(idx: usize) -> (DomId, NodeId) {

        (DomId::ROOT_ID, NodeId::new(idx))

    }

    /// Reads the physics state back out of the `RefAny` after a tick.

    fn with_state<R>(data: &mut RefAny, f: impl FnOnce(&ScrollPhysicsState) -> R) -> R {

        let state = data

            .downcast_ref::<ScrollPhysicsState>()

            .expect("RefAny must still hold a ScrollPhysicsState");

        f(&state)

    }

    /// A `ScrollPhysics` whose every float field is `NaN` and every integer field

    /// is degenerate — except `max_velocity`, which must stay non-NaN and

    /// non-negative or `f32::clamp` panics (see the `known_hazard` tests below).

    fn nan_physics() -> ScrollPhysics {

        ScrollPhysics {

            smooth_scroll_duration_ms: 0,

            deceleration_rate: f32::NAN,

            min_velocity_threshold: f32::NAN,

            max_velocity: 0.0,

            wheel_multiplier: f32::NAN,

            invert_direction: false,

            overscroll_elasticity: f32::NAN,

            max_overscroll_distance: f32::NAN,

            bounce_back_duration_ms: 0,

            timer_interval_ms: 0,

            wheel_animate_bounce_ms: 0,

        }

    }

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

    // calculate_overshoot — numeric

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

    #[test]

    fn calculate_overshoot_returns_zero_inside_the_range_and_on_both_boundaries() {

        assert_eq!(calculate_overshoot(0.0, 0.0, 100.0), 0.0);

        assert_eq!(calculate_overshoot(100.0, 0.0, 100.0), 0.0);

        assert_eq!(calculate_overshoot(50.0, 0.0, 100.0), 0.0);

        // Degenerate range (min == max): only that single point is in range.

        assert_eq!(calculate_overshoot(0.0, 0.0, 0.0), 0.0);

        // -0.0 is neither < 0.0 nor > 0.0, so it counts as in-range.

        assert_eq!(calculate_overshoot(-0.0, 0.0, 100.0), 0.0);

    }

    #[test]

    fn calculate_overshoot_is_signed_by_which_boundary_was_crossed() {

        assert_eq!(calculate_overshoot(-10.0, 0.0, 100.0), -10.0);

        assert_eq!(calculate_overshoot(110.0, 0.0, 100.0), 10.0);

        // Negative range: overshoot is still measured relative to the boundary.

        assert_eq!(calculate_overshoot(-30.0, -20.0, -10.0), -10.0);

        assert_eq!(calculate_overshoot(0.0, -20.0, -10.0), 10.0);

    }

    #[test]

    fn calculate_overshoot_nan_position_reports_no_overshoot() {

        // Both `NaN < min` and `NaN > max` are false, so the in-range branch wins

        // and a NaN position is reported as "not overshooting" rather than

        // propagating NaN into the spring force.

        let out = calculate_overshoot(f32::NAN, 0.0, 100.0);

        assert!(!out.is_nan(), "NaN must not leak out of calculate_overshoot");

        assert_eq!(out, 0.0);

        // A NaN bound, however, does make every position look "in range".

        assert_eq!(calculate_overshoot(1e9, 0.0, f32::NAN), 0.0);

        assert_eq!(calculate_overshoot(-1e9, f32::NAN, 100.0), 0.0);

    }

    #[test]

    fn calculate_overshoot_infinite_position_saturates_without_panicking() {

        assert_eq!(calculate_overshoot(f32::INFINITY, 0.0, 100.0), f32::INFINITY);

        assert_eq!(

            calculate_overshoot(f32::NEG_INFINITY, 0.0, 100.0),

            f32::NEG_INFINITY

        );

        // inf - inf would be NaN; the boundary check keeps us in-range instead.

        assert_eq!(

            calculate_overshoot(f32::INFINITY, f32::NEG_INFINITY, f32::INFINITY),

            0.0

        );

    }

    #[test]

    fn calculate_overshoot_extreme_finite_range_overflows_to_infinity_not_a_panic() {

        // f32::MAX - f32::MIN is not representable -> +inf. Defined, no panic.

        let out = calculate_overshoot(f32::MAX, f32::MIN, f32::MIN);

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

        let out = calculate_overshoot(f32::MIN, f32::MAX, f32::MAX);

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

    }

    #[test]

    fn calculate_overshoot_inverted_range_is_deterministic() {

        // min > max: the `pos < min` branch is checked first, so everything below

        // `min` reads as a negative overshoot. No panic, no assertion inside.

        assert_eq!(calculate_overshoot(5.0, 10.0, 0.0), -5.0);

        assert_eq!(calculate_overshoot(20.0, 10.0, 0.0), 20.0);

    }

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

    // rubber_band_clamp — numeric

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

    #[test]

    fn rubber_band_clamp_is_the_identity_inside_the_range() {

        assert_eq!(rubber_band_clamp(0.0, 0.0, 100.0, 50.0, 0.5), 0.0);

        assert_eq!(rubber_band_clamp(50.0, 0.0, 100.0, 50.0, 0.5), 50.0);

        assert_eq!(rubber_band_clamp(100.0, 0.0, 100.0, 50.0, 0.5), 100.0);

    }

    #[test]

    fn rubber_band_clamp_with_zero_max_overscroll_hard_clamps_to_the_boundary() {

        assert_eq!(rubber_band_clamp(1000.0, 0.0, 100.0, 0.0, 0.5), 100.0);

        assert_eq!(rubber_band_clamp(-1000.0, 0.0, 100.0, 0.0, 0.5), 0.0);

        // A negative max_overscroll takes the same `else` branch (no bounce).

        assert_eq!(rubber_band_clamp(1000.0, 0.0, 100.0, -50.0, 0.5), 100.0);

        assert_eq!(rubber_band_clamp(-1000.0, 0.0, 100.0, -50.0, 0.5), 0.0);

    }

    #[test]

    fn rubber_band_clamp_with_zero_elasticity_pins_to_the_boundary() {

        // 1 - e^0 == 0, so no overshoot displacement at all.

        assert_eq!(rubber_band_clamp(1000.0, 0.0, 100.0, 120.0, 0.0), 100.0);

        assert_eq!(rubber_band_clamp(-1000.0, 0.0, 100.0, 120.0, 0.0), 0.0);

    }

    #[test]

    fn rubber_band_clamp_never_exceeds_max_overscroll_even_for_absurd_input() {

        let (min, max, max_over, elast) = (0.0, 100.0, 120.0, 0.5);

        for raw in [101.0_f32, 500.0, 1e6, 1e30, f32::MAX, f32::INFINITY] {

            let out = rubber_band_clamp(raw, min, max, max_over, elast);

            assert!(out.is_finite(), "raw={raw} produced {out}");

            assert!(

                out >= max && out <= max + max_over,

                "raw={raw} escaped the overscroll band: {out}"

            );

        }

        for raw in [-1.0_f32, -500.0, -1e6, -1e30, f32::MIN, f32::NEG_INFINITY] {

            let out = rubber_band_clamp(raw, min, max, max_over, elast);

            assert!(out.is_finite(), "raw={raw} produced {out}");

            assert!(

                out <= min && out >= min - max_over,

                "raw={raw} escaped the overscroll band: {out}"

            );

        }

        // The band is approached asymptotically: an infinite pull lands exactly on it.

        assert_eq!(

            rubber_band_clamp(f32::INFINITY, min, max, max_over, elast),

            max + max_over

        );

        assert_eq!(

            rubber_band_clamp(f32::NEG_INFINITY, min, max, max_over, elast),

            min - max_over

        );

    }

    #[test]

    fn rubber_band_clamp_has_diminishing_returns_and_stays_monotonic() {

        let (min, max, max_over, elast) = (0.0, 100.0, 100.0, 0.5);

        let mut previous = max;

        for raw in [110.0_f32, 120.0, 200.0, 400.0, 800.0] {

            let out = rubber_band_clamp(raw, min, max, max_over, elast);

            // Monotonically increasing...

            assert!(out > previous, "not monotonic at raw={raw}: {out} <= {previous}");

            // ...but always giving back less than the raw pull (springy resistance).

            assert!(

                out < raw,

                "raw={raw} was not resisted at all (got {out})"

            );

            previous = out;

        }

    }

    #[test]

    fn rubber_band_clamp_nan_inputs_are_defined_and_do_not_panic() {

        // NaN fails both in-range comparisons, falls into the `raw_pos >= max`

        // branch, and NaN propagates to the result. The caller

        // (`scroll_to_unclamped` -> change processor) sanitises it later.

        assert!(rubber_band_clamp(f32::NAN, 0.0, 100.0, 120.0, 0.5).is_nan());

        // A NaN elasticity / max_overscroll must not panic either.

        assert!(rubber_band_clamp(500.0, 0.0, 100.0, 120.0, f32::NAN).is_nan());

        // NaN max_overscroll is not > 0.0, so the no-bounce branch pins the boundary.

        assert_eq!(rubber_band_clamp(500.0, 0.0, 100.0, f32::NAN, 0.5), 100.0);

    }

    #[test]

    fn rubber_band_clamp_negative_elasticity_stays_non_nan() {

        // A negative elasticity inverts the exponential (e^+x): the "resistance"

        // becomes an amplification. It is nonsense physically, but it must not

        // panic and must not produce NaN.

        for raw in [110.0_f32, 1e6, f32::MAX] {

            let out = rubber_band_clamp(raw, 0.0, 100.0, 100.0, -1.0);

            assert!(!out.is_nan(), "raw={raw} produced NaN");

        }

        // Small overshoot with negative elasticity: still finite and defined.

        let out = rubber_band_clamp(110.0, 0.0, 100.0, 100.0, -1.0);

        assert!(out.is_finite());

        assert!(out < 100.0, "negative elasticity flips the sign: {out}");

    }

    #[test]

    fn rubber_band_clamp_degenerate_range_still_returns_a_boundary() {

        // min == max: everything except that point overshoots.

        assert_eq!(rubber_band_clamp(0.0, 0.0, 0.0, 100.0, 0.5), 0.0);

        let out = rubber_band_clamp(10.0, 0.0, 0.0, 100.0, 0.5);

        assert!(out > 0.0 && out <= 100.0, "{out}");

        let out = rubber_band_clamp(-10.0, 0.0, 0.0, 100.0, 0.5);

        assert!((-100.0..0.0).contains(&out), "{out}");

    }

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

    // friction_from_deceleration — numeric

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

    #[test]

    fn friction_from_deceleration_matches_the_documented_values() {

        assert!((friction_from_deceleration(0.95) - 0.05).abs() < 1e-6);

        assert!((friction_from_deceleration(0.998) - 0.002).abs() < 1e-6);

        assert!((friction_from_deceleration(0.0) - 1.0).abs() < 1e-6);

    }

    #[test]

    fn friction_from_deceleration_clamps_both_ends_and_never_returns_zero() {

        // Anything >= 0.999 collapses onto the 0.001 friction floor: a

        // deceleration_rate of exactly 1.0 ("never stops") must NOT produce a

        // zero friction, or momentum would run forever.

        assert_eq!(friction_from_deceleration(1.0), 0.001);

        assert_eq!(friction_from_deceleration(0.999), 0.001);

        assert_eq!(friction_from_deceleration(f32::MAX), 0.001);

        assert_eq!(friction_from_deceleration(f32::INFINITY), 0.001);

        // Anything <= 0.0 saturates to full friction.

        assert_eq!(friction_from_deceleration(-0.0), 1.0);

        assert_eq!(friction_from_deceleration(-5.0), 1.0);

        assert_eq!(friction_from_deceleration(f32::MIN), 1.0);

        assert_eq!(friction_from_deceleration(f32::NEG_INFINITY), 1.0);

    }

    #[test]

    fn friction_from_deceleration_nan_falls_back_to_the_floor() {

        // f32::clamp(NaN) == NaN, but `NaN.max(0.001)` == 0.001 (f32::max ignores

        // NaN), so the friction floor rescues the whole physics integration.

        let out = friction_from_deceleration(f32::NAN);

        assert!(!out.is_nan(), "NaN deceleration must not poison friction");

        assert_eq!(out, 0.001);

    }

    #[test]

    fn friction_from_deceleration_always_yields_a_usable_decay_factor() {

        let dt = 16.0 / 1000.0;

        for rate in [

            0.0_f32,

            0.5,

            0.9,

            0.95,

            0.996,

            0.998,

            0.999,

            1.0,

            -1.0,

            f32::NAN,

            f32::INFINITY,

            f32::NEG_INFINITY,

            f32::MAX,

            f32::MIN,

            f32::MIN_POSITIVE,

        ] {

            let friction = friction_from_deceleration(rate);

            assert!(friction.is_finite(), "rate={rate} -> {friction}");

            assert!(

                (0.001..=1.0).contains(&friction),

                "rate={rate} -> friction {friction} outside [0.001, 1.0]"

            );

            // This is exactly how the callback uses it: exp(-friction*dt*60).

            let decay = (-friction * dt * ASSUMED_FPS).exp();

            assert!(decay.is_finite() && decay > 0.0 && decay < 1.0, "rate={rate} -> decay {decay}");

        }

    }

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

    // spring_constant_from_bounce_duration — numeric

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

    #[test]

    fn spring_constant_clamps_short_durations_to_50ms() {

        let floor = spring_constant_from_bounce_duration(50);

        assert_eq!(spring_constant_from_bounce_duration(0), floor);

        assert_eq!(spring_constant_from_bounce_duration(1), floor);

        assert_eq!(spring_constant_from_bounce_duration(49), floor);

        // (2*pi / 0.05)^2 ~= 15791.4

        assert!((floor - 15791.37).abs() < 1.0, "{floor}");

    }

    #[test]

    fn spring_constant_decreases_monotonically_with_duration() {

        let mut previous = f32::INFINITY;

        for ms in [50_u32, 100, 200, 300, 400, 500, 1000, 10_000] {

            let k = spring_constant_from_bounce_duration(ms);

            assert!(k.is_finite() && k > 0.0, "ms={ms} -> {k}");

            assert!(k < previous, "ms={ms}: {k} did not decrease below {previous}");

            previous = k;

        }

    }

    #[test]

    fn spring_constant_stays_finite_and_positive_at_u32_max() {

        // duration_ms = u32::MAX -> ~4295 seconds -> a vanishingly small k.

        // It must stay > 0 so that `2 * k.sqrt()` (the damping term) is not NaN.

        let k = spring_constant_from_bounce_duration(u32::MAX);

        assert!(k.is_finite(), "{k}");

        assert!(k > 0.0, "{k}");

        assert!(k < 1e-6, "{k}");

    }

    #[test]

    fn spring_constant_damping_term_is_always_finite() {

        // The callback computes `2.0 * spring_k.sqrt()`; a negative or NaN k