rust_widgets 2.9.2

// SPDX-FileCopyrightText: Copyright (c) 2026 Mike Li/Mikewolfli/Wei Li(mikewolfli@163.com)
// SPDX-License-Identifier: MIT

use super::animation_group::AnimationGroup;
use crate::compat::{Box, Duration, HashMap, Instant, String, Vec};
use crate::core::Color;
#[derive(Debug, Clone, Copy, PartialEq, Default)]
/// The timing curve applied to an animation's raw progress.
///
/// [`EasingFunction::apply`] maps a normalized input `t` in `0.0..=1.0` to an
/// eased output that is *usually* in the same range, but not always: [`Self::BackIn`],
/// [`Self::BackOut`], [`Self::ElasticIn`] and [`Self::ElasticOut`] deliberately
/// overshoot outside it, which is how the "pull back" and "spring past" effects
/// are produced. Input outside `0.0..=1.0` is clamped first.
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub enum EasingFunction {
    #[default]
    /// Constant speed: the output equals the input.
    Linear,
    /// Accelerates from rest; the output lags the input in the first half.
    EaseIn,
    /// Decelerates to rest; the output leads the input in the first half.
    EaseOut,
    /// Accelerates out of the start and decelerates into the end.
    EaseInOut,
    /// [`Self::BounceOut`] played backwards, so the motion collides at the end.
    BounceIn,
    /// Decelerates into the target with a series of diminishing bounces.
    BounceOut,
    /// [`Self::ElasticOut`] played backwards, so the motion snaps into the
    /// start with increasing oscillation.
    ElasticIn,
    /// Overshoots the target and oscillates back to it, like a stretched spring.
    ElasticOut,
    /// Starts by moving *away* from the target before accelerating toward it.
    /// Overshoots below `0.0`.
    BackIn,
    /// Overshoots past the target before settling back. Overshoots above `1.0`.
    BackOut,
    /// A cubic Bézier timing function defined by two control points, the same four-parameter
    /// form a stylesheet spells `cubic-bezier(x1, y1, x2, y2)`.
    ///
    /// # Why this exists next to the named curves
    ///
    /// The named variants are a fixed family: every one of them is a single formula, so a theme
    /// or a host could choose from ten shapes and nothing else. The two control points cover the
    /// whole custom-curve space with **one** variant, which is what the CSS timing-function
    /// syntax already standardised and what an imported design token set expresses. Adding a
    /// variant per named curve instead would grow the enum without adding reach.
    ///
    /// `x1` and `x2` are clamped to `0.0..=1.0` by [`EasingFunction::cubic_bezier`], because a
    /// control point outside that range would make the curve non-monotonic in time and the solver
    /// could not name a single output for an input. `y1` and `y2` are deliberately unbounded:
    /// values outside `0.0..=1.0` are how an overshooting curve is written.
    CubicBezier {
        /// X coordinate of the first control point, in `0.0..=1.0`.
        x1: f32,
        /// Y coordinate of the first control point, unclamped.
        y1: f32,
        /// X coordinate of the second control point, in `0.0..=1.0`.
        x2: f32,
        /// Y coordinate of the second control point, unclamped.
        y2: f32,
    },
}

impl EasingFunction {
    /// Builds a [`EasingFunction::CubicBezier`] with the control points' X coordinates clamped
    /// to the valid `0.0..=1.0` range.
    ///
    /// Use this rather than the variant directly when the four numbers come from untrusted
    /// input (a design token, a stylesheet): it is the constructor that enforces the one
    /// invariant the solver relies on.
    pub fn cubic_bezier(x1: f32, y1: f32, x2: f32, y2: f32) -> Self {
        Self::CubicBezier { x1: x1.clamp(0.0, 1.0), y1, x2: x2.clamp(0.0, 1.0), y2 }
    }

    /// Parses the CSS spelling `cubic-bezier(x1, y1, x2, y2)`.
    ///
    /// Returns `None` for any other text, so a caller can fall back to the named curves instead
    /// of silently treating unknown text as linear. Whitespace around the numbers is accepted,
    /// as the CSS grammar allows.
    pub fn parse_cubic_bezier(text: &str) -> Option<Self> {
        let inner = text.trim().strip_prefix("cubic-bezier(")?.strip_suffix(')')?;
        let mut values = [0.0f32; 4];
        let mut count = 0usize;
        for part in inner.split(',') {
            if count == values.len() {
                return None;
            }
            values[count] = part.trim().parse().ok()?;
            count += 1;
        }
        if count != values.len() {
            return None;
        }
        Some(Self::cubic_bezier(values[0], values[1], values[2], values[3]))
    }
}
impl EasingFunction {
    /// Maps normalized progress `t` through this curve.
    ///
    /// `t` is clamped to `0.0..=1.0` before evaluation, so every variant yields
    /// exactly `0.0` at `t <= 0.0` and exactly `1.0` at `t >= 1.0`. The result of
    /// an intermediate `t` may fall outside `0.0..=1.0` for the overshooting
    /// variants listed on [`EasingFunction`].
    pub fn apply(&self, t: f32) -> f32 {
        let t = t.clamp(0.0, 1.0);
        match self {
            Self::Linear => t,
            Self::EaseIn => t * t,
            Self::EaseOut => 1.0 - (1.0 - t) * (1.0 - t),
            Self::EaseInOut => {
                if t < 0.5 {
                    2.0 * t * t
                } else {
                    1.0 - (-2.0 * t + 2.0).powi(2) / 2.0
                }
            }
            Self::BounceIn => 1.0 - Self::BounceOut.apply(1.0 - t),
            Self::BounceOut => {
                if t < 1.0 / 2.75 {
                    7.5625 * t * t
                } else if t < 2.0 / 2.75 {
                    let t = t - 1.5 / 2.75;
                    7.5625 * t * t + 0.75
                } else if t < 2.5 / 2.75 {
                    let t = t - 2.25 / 2.75;
                    7.5625 * t * t + 0.9375
                } else {
                    let t = t - 2.625 / 2.75;
                    7.5625 * t * t + 0.984375
                }
            }
            Self::ElasticIn => {
                if t == 0.0 {
                    0.0
                } else if t == 1.0 {
                    1.0
                } else {
                    -(2.0_f32.powf(10.0 * (t - 1.0)))
                        * ((t - 1.1) * 5.0 * core::f32::consts::PI).sin()
                }
            }
            Self::ElasticOut => {
                if t == 0.0 {
                    0.0
                } else if t == 1.0 {
                    1.0
                } else {
                    2.0_f32.powf(-10.0 * t) * ((t - 0.1) * 5.0 * core::f32::consts::PI).sin() + 1.0
                }
            }
            Self::BackIn => {
                const C1: f32 = 1.70158;
                const C3: f32 = C1 + 1.0;
                C3 * t * t * t - C1 * t * t
            }
            Self::BackOut => {
                const C1: f32 = 1.70158;
                const C3: f32 = C1 + 1.0;
                1.0 + C3 * (t - 1.0).powi(3) + C1 * (t - 1.0).powi(2)
            }
            Self::CubicBezier { x1, y1, x2, y2 } => cubic_bezier_at(*x1, *y1, *x2, *y2, t),
        }
    }
}

/// Evaluates the Y of a cubic Bézier with `(0,0)` and `(1,1)` endpoints.
///
/// `x(u)` is monotonic when both X control points are in `0.0..=1.0`, which
/// [`EasingFunction::cubic_bezier`] guarantees. The solver therefore bisects `u` until
/// `x(u) == x` to within `1e-6`: 32 iterations always suffice for `f32` precision, and the
/// loop is bounded, so a caller cannot hang on a degenerate curve.
fn cubic_bezier_at(x1: f32, y1: f32, x2: f32, y2: f32, x: f32) -> f32 {
    if x <= 0.0 {
        return 0.0;
    }
    if x >= 1.0 {
        return 1.0;
    }
    let sample = |u: f32| {
        let one_minus = 1.0 - u;
        3.0 * one_minus * one_minus * u * x1 + 3.0 * one_minus * u * u * x2 + u * u * u
    };
    let (mut low, mut high) = (0.0f32, 1.0f32);
    let mut u = x;
    for _ in 0..32 {
        let sampled = sample(u);
        if (sampled - x).abs() <= 1e-6 {
            break;
        }
        if sampled < x {
            low = u;
        } else {
            high = u;
        }
        u = (low + high) * 0.5;
    }
    let one_minus = 1.0 - u;
    3.0 * one_minus * one_minus * u * y1 + 3.0 * one_minus * u * u * y2 + u * u * u
}
/// Which family of shapes a state transition follows.
///
/// [`Self::Easing`] is the historical path: the theme's [`EasingFunction`] applied to the
/// frame's share of the duration. [`Self::Spring`] runs the crate's physical spring instead,
/// which is what gives an interaction the settle macOS controls are known for. A driver stores
/// this value, so a caller can choose the shape per property without changing a theme.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub enum MotionCurve {
    /// Ease along the theme's `Motion::easing` curve. The default, so every existing theme and
    /// every existing driver keeps its exact output.
    #[default]
    Easing,
    /// Settle like a damped spring with the named preset.
    Spring(SpringPreset),
}

/// The spring characters the library ships.
///
/// The presets are damping **ratios**, not one-off stiffness numbers: `Settle` is critically
/// damped (no overshoot), `Snappy` overshoots slightly, and `Bouncy` overshoots visibly. The
/// stiffness is folded from the motion slot the driver is priced by, so a `Fast` spring
/// settles sooner than a `Slow` one while keeping the same character.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub enum SpringPreset {
    /// Critically damped: reaches the target without crossing it. The default.
    #[default]
    Settle,
    /// Slightly under-damped: a small overshoot that reads as responsiveness.
    Snappy,
    /// Under-damped: a visible overshoot and one or two diminishing rebounds.
    Bouncy,
}

impl SpringPreset {
    /// The damping ratio this preset names.
    pub const fn damping_ratio(self) -> f32 {
        match self {
            Self::Settle => 1.0,
            Self::Snappy => 0.85,
            Self::Bouncy => 0.7,
        }
    }

    /// The `(stiffness, damping)` pair for a spring that settles over `tempo`'s duration.
    ///
    /// For a unit mass, a damping ratio `zeta` and a natural frequency `omega`, the spring
    /// constant is `omega^2` and the damping coefficient is `2 * zeta * omega`. The envelope
    /// decays as `exp(-zeta * omega * t)`, so `omega = 4 / (zeta * duration)` places the
    /// four-time-constant point at the requested duration. The frequency is capped at 100 rad/s
    /// so the explicit integrator stays stable at the driver's maximum substep; a token shorter
    /// than that cap would describe a motion too fast to see anyway.
    pub fn parameters(self, tempo: TransitionTempo) -> (f32, f32) {
        let duration_secs = (tempo.duration_ms().max(1) as f32) / 1000.0;
        let ratio = self.damping_ratio();
        let omega = (4.0 / (ratio * duration_secs)).min(100.0);
        (omega * omega, 2.0 * ratio * omega)
    }
}
/// Which direction each iteration of a repeating animation runs in.
///
/// Only [`Self::Alternate`] and [`Self::AlternateReverse`] depend on the
/// iteration index; the other two play every iteration identically, so a
/// non-infinite animation with them simply restarts from the same end.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum AnimationDirection {
    #[default]
    /// Play forwards on every iteration: progress runs `0.0` to `1.0`.
    Normal,
    /// Play backwards on every iteration: progress runs `1.0` to `0.0`.
    Reverse,
    /// Alternate: forwards on even iterations, backwards on odd ones.
    Alternate,
    /// Alternate starting from backwards: backwards on even iterations,
    /// forwards on odd ones.
    AlternateReverse,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
/// What an animation's value is before it starts and after it finishes.
///
/// The `backwards` half is honoured by [`Animation::progress`], which holds the run's first
/// value during the configured delay when this mode asks for it. The `forwards` half describes
/// what a *consumer* should do with the finished value — the progress function saturates at
/// `1.0` either way, so whether that value is kept or dropped is the caller's decision, and
/// [`AnimationFillMode::fills_forwards`] is the question a caller asks to make it.
pub enum AnimationFillMode {
    #[default]
    /// Apply no value outside the active interval: before the delay the
    /// animation has no effect, and it is dropped once finished.
    None,
    /// Retain the final value after the animation finishes.
    Forwards,
    /// Apply the first value during the delay, before the animation starts.
    Backwards,
    /// Both [`Self::Backwards`] and [`Self::Forwards`].
    Both,
}

impl AnimationFillMode {
    /// Whether the animation holds its first value during its own delay.
    ///
    /// The single place this question is answered, so [`Animation::progress`] and any future
    /// consumer cannot disagree about what `Backwards` and `Both` mean.
    pub const fn fills_backwards(self) -> bool {
        matches!(self, Self::Backwards | Self::Both)
    }

    /// Whether the animation keeps its final value once it has finished.
    pub const fn fills_forwards(self) -> bool {
        matches!(self, Self::Forwards | Self::Both)
    }
}
#[derive(Debug, Clone)]
/// The timing and repetition parameters for one animation.
///
pub struct AnimationConfig {
    /// How long one iteration lasts. A zero duration is handled by the animators,
    /// which treat it as an instant jump rather than dividing by it.
    pub duration: Duration,
    /// How long to wait before the first iteration begins. Progress reads `0.0`
    /// for the whole delay.
    pub delay: Duration,
    /// The timing curve applied to each iteration's progress.
    pub easing: EasingFunction,
    /// Which direction iteration 0 runs in, and whether later iterations flip.
    pub direction: AnimationDirection,
    /// What value the animation leaves behind before and after its active interval.
    pub fill_mode: AnimationFillMode,
    /// How many iterations to run before the animation counts as complete.
    ///
    /// Ignored while `infinite` is set. [`AnimationConfig::new`] starts this at
    /// `1`, so an animation plays once by default.
    pub iteration_count: u32,
    /// Run forever: [`Animation::is_completed`] always returns `false` and
    /// `iteration_count` is not consulted.
    pub infinite: bool,
}
impl AnimationConfig {
    /// Creates a config running one forward, linear iteration over `duration`,
    /// with no delay, no fill and no repetition.
    pub fn new(duration: Duration) -> Self {
        Self {
            duration,
            delay: Duration::ZERO,
            easing: EasingFunction::Linear,
            direction: AnimationDirection::Normal,
            fill_mode: AnimationFillMode::None,
            iteration_count: 1,
            infinite: false,
        }
    }
    /// Returns a copy with the start delay set to `delay`.
    pub fn with_delay(mut self, delay: Duration) -> Self {
        self.delay = delay;
        self
    }
    /// Returns a copy using `easing` as the timing curve.
    pub fn with_easing(mut self, easing: EasingFunction) -> Self {
        self.easing = easing;
        self
    }
    /// Returns a copy running in `direction`.
    pub fn with_direction(mut self, direction: AnimationDirection) -> Self {
        self.direction = direction;
        self
    }
    /// Returns a copy with `fill_mode` applied.
    pub fn with_fill_mode(mut self, fill_mode: AnimationFillMode) -> Self {
        self.fill_mode = fill_mode;
        self
    }
    /// Returns a copy running `count` iterations, and clears the infinite flag.
    ///
    /// The reset matters because `infinite` otherwise wins: without it,
    /// `config.infinite().with_iterations(3)` would still never complete.
    pub fn with_iterations(mut self, count: u32) -> Self {
        self.iteration_count = count;
        self.infinite = false;
        self
    }
    /// Returns a copy that repeats forever, ignoring `iteration_count`.
    pub fn infinite(mut self) -> Self {
        self.infinite = true;
        self
    }
}
impl Default for AnimationConfig {
    /// A one-shot 300 ms linear animation with no delay — the conventional UI
    /// transition length.
    fn default() -> Self {
        Self::new(Duration::from_millis(300))
    }
}
/// A single animation instance: config plus the clock state needed to drive it.
///
/// The clock is advanced by explicit calls to [`Animation::update`] rather than a
/// timer, so how smooth the result looks depends on how often the host calls it.
/// Reading [`Animation::progress`] does not advance anything and is safe from
/// `&self`.
pub struct Animation {
    config: AnimationConfig,
    start_time: Option<Instant>,
    is_running: bool,
    is_paused: bool,
    /// Tracks when the animation was paused, used on resume to adjust start_time.
    pause_start_time: Option<Instant>,
    current_iteration: u32,
    on_complete_callback: Option<Box<dyn FnMut()>>,
    /// Progress frozen at the moment of pause, so progress() returns the
    /// correct value while the animation is paused.
    frozen_progress: Option<f32>,
    /// Virtual elapsed time accumulated by [`Animation::advance_by`].
    ///
    /// When this is non-zero the animation is **delta-driven**: `progress_inner` reads it instead of
    /// the clock, so a host supplying frame deltas gets reproducible pacing and a test can reach an
    /// animation's end state without sleeping. An animation never advanced by a delta leaves it at
    /// zero and stays clock-driven, so an existing caller's behaviour is unchanged.
    elapsed_override: Duration,
}
impl Animation {
    /// Creates a stopped animation in iteration `0` with no completion callback.
    pub fn new(config: AnimationConfig) -> Self {
        Self {
            config,
            start_time: None,
            is_running: false,
            is_paused: false,
            pause_start_time: None,
            current_iteration: 0,
            on_complete_callback: None,
            frozen_progress: None,
            elapsed_override: Duration::ZERO,
        }
    }
    /// Starts the animation from now, clearing any pause and resetting the
    /// iteration counter to `0`.
    pub fn start(&mut self) {
        self.start_time = Some(Instant::now());
        self.is_running = true;
        self.is_paused = false;
        self.current_iteration = 0;
    }
    /// Stops the animation and resets its clock, leaving it at iteration `0`.
    ///
    /// The completion callback fires here, even though the animation did not
    /// reach its end, and is consumed: a later [`Animation::start`] will not
    /// invoke it again until [`Animation::on_complete`] installs a new one.
    pub fn stop(&mut self) {
        self.is_running = false;
        self.start_time = None;
        self.current_iteration = 0;
        self.frozen_progress = None;
        if let Some(mut callback) = self.on_complete_callback.take() {
            callback();
        }
    }
    /// Freezes progress at its current value and records the pause instant.
    ///
    /// The animation is not advanced by [`Animation::update`] while paused, so
    /// progress holds at the frozen value until [`Animation::resume`].
    pub fn pause(&mut self) {
        self.frozen_progress = Some(self.compute_progress());
        self.is_paused = true;
        self.pause_start_time = Some(Instant::now());
    }
    /// Reports whether the animation is currently paused.
    ///
    /// A paused animation is still "started": [`Animation::is_running`] returns
    /// `false` while this does.
    pub fn is_paused(&self) -> bool {
        self.is_paused
    }
    /// Returns the animation to the state [`Animation::new`] left it in:
    /// stopped, unpaused, iteration `0`, no frozen progress.
    ///
    /// The completion callback is *not* cleared and does not fire.
    pub fn reset(&mut self) {
        self.is_running = false;
        self.is_paused = false;
        self.start_time = None;
        self.pause_start_time = None;
        self.current_iteration = 0;
        self.frozen_progress = None;
    }
    /// Sets the callback invoked once when the animation completes or is stopped.
    ///
    /// Setting a new callback replaces the old one. The callback is single-shot:
    /// it is taken and consumed the first time it fires.
    pub fn on_complete(&mut self, callback: Box<dyn FnMut()>) {
        self.on_complete_callback = Some(callback);
    }
    /// Un-pauses the animation and shifts its start instant forward by however
    /// long the pause lasted, so progress picks up where it stopped rather than
    /// jumping ahead.
    ///
    /// Calling this on an animation that is not paused is harmless; if the
    /// animation was never started there is no start instant to shift.
    pub fn resume(&mut self) {
        self.is_paused = false;
        self.frozen_progress = None;
        // Adjust start_time forward by the paused duration so the animation
        // resumes from where it stopped rather than jumping forward.
        if let Some(pause_start) = self.pause_start_time.take() {
            let paused_duration = pause_start.elapsed();
            if let Some(ref mut start) = self.start_time {
                *start += paused_duration;
            }
        }
    }
    /// Reports whether the animation is advancing: started and not paused.
    pub fn is_running(&self) -> bool {
        self.is_running && !self.is_paused
    }
    /// Reports whether every requested iteration has been played.
    ///
    /// Always `false` for an infinite animation. This is derived from the
    /// iteration counter, which only [`Animation::update`] advances, so an
    /// animation that was started but never updated still reads as incomplete.
    pub fn is_completed(&self) -> bool {
        if self.config.infinite {
            false
        } else {
            self.current_iteration >= self.config.iteration_count
        }
    }
    /// The animation's position in its current iteration, as an eased
    /// `0.0..=1.0` fraction (outside that range for an overshooting easing curve).
    ///
    /// Returns `0.0` while the animation is stopped or still in its delay, and
    /// returns the frozen value while paused. Within an iteration the raw
    /// progress wraps, so a multi-iteration run reports the fractional part of its
    /// current iteration, and a completed run holds at the value its direction ends on.
    ///
    /// # A finished animation holds at its directional end value
    ///
    /// `update` clears `is_running` when the last iteration elapses, so a *completed*
    /// one-shot used to fall into the "not running" branch and read `0.0` — a progress bar
    /// wired to this snapped back to empty at the moment it filled. The documented contract is
    /// that it reads its final value, so completion is answered before the running check, and
    /// the value depends on the direction the final iteration ran in (a `Reverse` run ends at
    /// `0.0`, not `1.0`).
    pub fn progress(&self) -> f32 {
        if self.is_paused {
            // Return the progress frozen at the moment pause() was called.
            return self.frozen_progress.unwrap_or(0.0);
        }
        if self.is_completed() {
            return self.completed_progress();
        }
        self.progress_inner()
    }

    /// The progress value a completed animation holds at, which is the end of its final
    /// iteration rather than a direction-blind `1.0`.
    ///
    /// `Alternate`/`AlternateReverse` flip every iteration, so the end depends on the parity of
    /// the last iteration (`iteration_count - 1`).
    fn completed_progress(&self) -> f32 {
        let last_iteration = self.config.iteration_count.saturating_sub(1);
        match self.config.direction {
            AnimationDirection::Normal => 1.0,
            AnimationDirection::Reverse => 0.0,
            AnimationDirection::Alternate => {
                if last_iteration.is_multiple_of(2) {
                    1.0
                } else {
                    0.0
                }
            }
            AnimationDirection::AlternateReverse => {
                if last_iteration.is_multiple_of(2) {
                    0.0
                } else {
                    1.0
                }
            }
        }
    }
    /// The shared body of [`progress`](Self::progress) and the pause-time capture.
    ///
    /// Completion is answered *before* this function runs (see [`progress`](Self::progress)), so
    /// the only case that reaches here is an animation mid-iteration. The within-iteration progress
    /// is therefore the fractional part of `raw`, for finite and infinite runs alike: a
    /// three-iteration animation at `1.5` durations is in its second iteration at `0.5`, not
    /// saturated at `1.0`. The `min(1.0)` this branch once applied was wrong exactly because it
    /// could only ever return `raw % 1.0` or `0.0` — the clamp never bound — and it made every
    /// iteration after the first read as a stuck end-point.
    fn progress_inner(&self) -> f32 {
        if !self.is_running {
            return 0.0;
        }
        // Delta-driven when a caller has advanced this animation explicitly; clock-driven
        // otherwise. One source or the other, never a mix — see `advance_by`.
        let elapsed = if self.elapsed_override > Duration::ZERO {
            self.elapsed_override
        } else {
            self.start_time.map(|t| t.elapsed()).unwrap_or_default()
        };
        // # `fill_mode` is read here, not merely carried
        //
        // The enum documents itself as "what an animation's value is before it starts and after
        // it finishes", and it used to say that no animator consulted it. Two of its four states
        // decide this function's answer, so carrying them without reading them made
        // `with_fill_mode(Backwards)` a no-op — a builder whose name states a behaviour the code
        // did not have (principle #37).
        //
        // * `Backwards`/`Both` — during the delay the animation holds its *first* value, which is
        //   progress `0.0` for a forward run. That is already what the branch below returns, so
        //   the distinction is only observable through `direction`: a `Reverse` run's first value
        //   is progress `1.0`, and filling backwards must not snap it to `0.0`.
        // * `None`/`Forwards` — nothing is applied before the delay, so progress reads `0.0`
        //   regardless of direction.
        if elapsed < self.config.delay {
            return if self.config.fill_mode.fills_backwards() {
                match self.config.direction {
                    AnimationDirection::Reverse | AnimationDirection::AlternateReverse => 1.0,
                    _ => 0.0,
                }
            } else {
                0.0
            };
        }
        let animation_elapsed = elapsed - self.config.delay;
        // Guard against division by zero when duration is ZERO (default).
        let duration_secs = self.config.duration.as_secs_f32().max(f32::EPSILON);
        let raw_progress = animation_elapsed.as_secs_f32() / duration_secs;
        // Within-iteration progress: `raw % 1.0` gives the fraction through the current
        // iteration for both finite and infinite runs. The end-of-sequence value is produced by
        // `completed_progress`, not by saturating here.
        let progress = raw_progress % 1.0;
        let eased_progress = self.config.easing.apply(progress);
        match self.config.direction {
            AnimationDirection::Normal => eased_progress,
            AnimationDirection::Reverse => 1.0 - eased_progress,
            AnimationDirection::Alternate => {
                if self.current_iteration.is_multiple_of(2) {
                    eased_progress
                } else {
                    1.0 - eased_progress
                }
            }
            AnimationDirection::AlternateReverse => {
                if self.current_iteration.is_multiple_of(2) {
                    1.0 - eased_progress
                } else {
                    eased_progress
                }
            }
        }
    }
    /// Advances the clock: recomputes the iteration counter and finishes the
    /// animation once its last iteration has elapsed.
    ///
    /// Does nothing while the animation is stopped or paused. Call it once per
    /// frame; the completion callback fires from here rather than from a timer.
    /// Unlike [`Animation::progress`], this path has no zero-duration guard.
    pub fn update(&mut self) {
        if !self.is_running || self.is_paused {
            // Paused animations keep their frozen progress and do
            // not advance their iteration count.
            return;
        }
        let elapsed = self.start_time.map(|t| t.elapsed()).unwrap_or_default();
        if elapsed > self.config.delay {
            let animation_elapsed = elapsed - self.config.delay;
            let raw_progress = animation_elapsed.as_secs_f32() / self.config.duration.as_secs_f32();
            if raw_progress >= 1.0 {
                self.current_iteration = raw_progress.floor() as u32;
                if !self.config.infinite && self.current_iteration >= self.config.iteration_count {
                    self.is_running = false;
                    if let Some(mut callback) = self.on_complete_callback.take() {
                        callback();
                    }
                }
            }
        }
    }
    /// Advances this animation by an explicit `delta`, ignoring the wall clock.
    ///
    /// # Why an animation needs its own delta-driven advance
    ///
    /// `update` derives elapsed time from `start_time`, so progress depends on real time passing
    /// between calls. That makes the engine unusable from a control whose host supplies a frame delta
    /// — the crate's own `tick(delta_ms)` convention — and it makes an animation unreproducible in a
    /// test without sleeping.
    ///
    /// This moves a **virtual** elapsed time forward instead: `elapsed_override` accumulates the
    /// deltas the caller supplies, and the progress computation reads it in preference to the clock.
    /// An animation is therefore driven by exactly one source or the other, never a mix, which is
    /// what keeps one config producing the same curve either way.
    ///
    /// The delay, the iteration count and the completion callback all behave as they do in `update`,
    /// because both paths read the same configuration and the same accumulated time.
    pub fn advance_by(&mut self, delta: Duration) {
        if !self.is_running || self.is_paused {
            // Same rule as `update`: a paused animation keeps its frozen progress and does not
            // advance its iteration count.
            return;
        }
        self.elapsed_override += delta;
        let elapsed = self.elapsed_override;
        if elapsed > self.config.delay {
            let animation_elapsed = elapsed - self.config.delay;
            let raw_progress = animation_elapsed.as_secs_f32() / self.config.duration.as_secs_f32();
            if raw_progress >= 1.0 {
                self.current_iteration = raw_progress.floor() as u32;
                if !self.config.infinite && self.current_iteration >= self.config.iteration_count {
                    self.is_running = false;
                    if let Some(mut callback) = self.on_complete_callback.take() {
                        callback();
                    }
                }
            }
        }
    }

    /// Borrows the configuration this animation runs with.
    pub fn config(&self) -> &AnimationConfig {
        &self.config
    }

    /// Compute the current progress without considering pause state.
    /// This is used to capture the progress value at the moment of pause.
    ///
    /// Shares [`progress_inner`](Self::progress_inner) with [`progress`](Self::progress):
    /// the two were duplicated bodies, which is how they came to disagree with the
    /// documented saturation contract in exactly the same way.
    fn compute_progress(&self) -> f32 {
        self.progress_inner()
    }
}
/// Animates between two colours, interpolating each RGBA channel independently.
pub struct ColorAnimation {
    animation: Animation,
    from_color: Color,
    to_color: Color,
}
impl ColorAnimation {
    /// Creates a stopped colour animation running from `from` to `to`.
    pub fn new(config: AnimationConfig, from: Color, to: Color) -> Self {
        Self { animation: Animation::new(config), from_color: from, to_color: to }
    }
    /// Starts the animation from now.
    pub fn start(&mut self) {
        self.animation.start();
    }
    /// Stops the animation, firing its completion callback if one was set.
    pub fn stop(&mut self) {
        self.animation.stop();
    }
    /// The colour at the animation's current progress.
    ///
    /// The blend is linear in the channels' 8-bit values, so it traverses the
    /// RGB cube rather than a perceptual colour space. Reads `from` when stopped,
    /// since progress is then `0.0`.
    pub fn current_color(&self) -> Color {
        let progress = self.animation.progress();
        Self::interpolate_color(self.from_color, self.to_color, progress)
    }
    /// Advances the animation. Call once per frame.
    pub fn update(&mut self) {
        self.animation.update();
    }
    /// Reports whether the animation is running and not paused.
    pub fn is_running(&self) -> bool {
        self.animation.is_running()
    }
    fn interpolate_color(from: Color, to: Color, t: f32) -> Color {
        // See `style::gradient::interpolate_color`: `Color::blend` rounds where this truncates, so
        // routing through it would change rendered pixels. Kept as the truncating form.
        let r = ((1.0 - t) * from.r as f32 + t * to.r as f32) as u8;
        let g = ((1.0 - t) * from.g as f32 + t * to.g as f32) as u8;
        let b = ((1.0 - t) * from.b as f32 + t * to.b as f32) as u8;
        let a = ((1.0 - t) * from.a as f32 + t * to.a as f32) as u8;
        Color::rgba(r, g, b, a)
    }
}
/// Animates a single `f32` between two values.
pub struct FloatAnimation {
    animation: Animation,
    from_value: f32,
    to_value: f32,
}
impl FloatAnimation {
    /// Creates a stopped float animation running from `from` to `to`.
    pub fn new(config: AnimationConfig, from: f32, to: f32) -> Self {
        Self { animation: Animation::new(config), from_value: from, to_value: to }
    }
    /// Starts the animation from now.
    pub fn start(&mut self) {
        self.animation.start();
    }
    /// Stops the animation, firing its completion callback if one was set.
    pub fn stop(&mut self) {
        self.animation.stop();
    }
    /// The interpolated value at the animation's current progress.
    ///
    /// Reads `from_value` when stopped, since progress is then `0.0`.
    pub fn current_value(&self) -> f32 {
        let progress = self.animation.progress();
        self.from_value + (self.to_value - self.from_value) * progress
    }
    /// Advances the animation. Call once per frame.
    pub fn update(&mut self) {
        self.animation.update();
    }
    /// Reports whether the animation is running and not paused.
    pub fn is_running(&self) -> bool {
        self.animation.is_running()
    }
}
/// Describes a single animated property on a target object.
#[derive(Debug, Clone)]
pub struct PropertyAnimation {
    /// Unique animation ID.
    pub id: AnimationId,
    /// Property name (e.g., "x", "y", "width", "opacity", "rotation").
    pub property: String,
    /// Starting value.
    pub from: f32,
    /// Ending value.
    pub to: f32,
    /// Current value (updated each frame).
    pub current: f32,
}

/// A unique identifier for an active animation managed by `AnimationDriver`.
pub type AnimationId = u64;

/// Callback invoked each frame with the current animation progress (0.0–1.0).
pub type AnimationTickCallback = Box<dyn FnMut(f32)>;

/// Callback invoked when an animation completes.
pub type AnimationCompleteCallback = Box<dyn FnMut()>;

/// A tracked active animation within the `AnimationDriver`.
struct ActiveAnimation {
    /// The core animation state machine.
    anim: Animation,
    /// Callback invoked every tick with the un-eased progress [0,1].
    tick: Option<AnimationTickCallback>,
    /// Callback invoked once when the animation finishes.
    on_complete: Option<AnimationCompleteCallback>,
    /// The last reported progress to avoid redundant callbacks.
    last_progress: f32,
}

impl ActiveAnimation {
    /// Forwards a caller-supplied delta to the wrapped animation.
    ///
    /// A forwarding method rather than reaching through `entry.anim.advance_by` at the call site,
    /// so the one place that knows what "advancing an active animation" means stays the one place.
    fn advance_by(&mut self, delta: Duration) {
        self.anim.advance_by(delta);
    }
}

/// Global animation driver that manages and advances active animations.
///
/// Call `advance()` from your event loop or render loop to tick all animations.
/// Use `add()` to register a new animation with a progress callback.
///
/// # Reachability (issue §9 item #5)
///
/// This engine **is** on the production path, not only a standalone capability. Controls do not
/// call it directly; they own a `PropertyDriver` (or a
/// `Transition`), whose `tick` builds and advances an `AnimationDriver`
/// internally. `Button::tick`, `PieMenu::tick` and the other animated controls therefore reach this
/// code every frame, and the interpolation curve (not each control) is the single place that defines
/// how a styled value moves.
///
/// The group composers (`AnimationGroup`,
/// `ParallelAnimation`,
/// `SequentialAnimation`) remain a **retained public
/// capability** with no in-crate control consumer: they compose *named* timeline animations, which
/// the property-transition path does not need. That is a deliberate scope decision (rule #4: the
/// library maps a control to the platform's ability; it does not invent a timeline the host never
/// asked for), not an unfinished wiring. A host that wants timeline choreography drives them
/// directly from its own frame loop, exactly as their docs show.
pub struct AnimationDriver {
    animations: HashMap<AnimationId, ActiveAnimation>,
    property_animations: HashMap<AnimationId, PropertyAnimation>,
    next_id: AnimationId,
    /// Ids of the animations that were in flight when the current advance began.
    ///
    /// `advance`/`advance_by` have to capture this set **before** advancing, because an animation
    /// that finishes during the call clears `is_running` — filtering afterwards would drop the frame
    /// that carries its final value. Keeping the set on the driver is what removes the two or three
    /// `Vec` allocations each of those calls used to make per frame (REND-13).
    in_flight: Vec<AnimationId>,
    /// `(id, progress)` taken between advancing and firing the callbacks, for the same reason: a
    /// callback gets `&mut ActiveAnimation`, so the progress has to be read before it runs.
    snapshot: Vec<(AnimationId, f32)>,
}

impl AnimationDriver {
    /// Creates a new empty animation driver.
    pub fn new() -> Self {
        Self {
            animations: HashMap::new(),
            property_animations: HashMap::new(),
            next_id: 1,
            in_flight: Vec::new(),
            snapshot: Vec::new(),
        }
    }

    /// Advances every active animation by a caller-supplied delta instead of by the clock.
    ///
    /// # Why the engine needed this
    ///
    /// `advance` reads `Instant::now()`, which makes an animation's progress depend on how long the
    /// host took to call it. That is right for a real frame loop and wrong for everything else: a
    /// test cannot drive an animation to its end state without sleeping, a host that renders on
    /// demand cannot reproduce a frame, and the crate's own `tick(delta_ms) -> bool` convention
    /// (established by `floating_label`) has no way to feed an engine that only reads the clock.
    ///
    /// So the engine shipped complete and uncallable from any control. This is the entry point that
    /// makes it callable: progress moves by exactly `delta`, and the return value answers the same
    /// question `advance`'s does — how many animations are still running — so a control can report
    /// "another frame is needed" without a second bookkeeping field.
    ///
    /// Easing and iteration still come from each animation's own config, so a delta-driven advance
    /// follows the same curve as a clock-driven one; only the source of elapsed time differs.
    pub fn advance_by(&mut self, delta: Duration) -> usize {
        // The scratch buffers live on the driver, so the three `collect`s this used to do per frame
        // are three `clear`+`push` passes over buffers that keep their capacity.
        let Self { animations, property_animations, in_flight, snapshot, .. } = self;
        // Which animations were in flight *before* this advance. Recorded up front because an
        // animation that reaches its end during this call flips `is_running` to `false` inside
        // `advance_by`, and filtering the snapshot on `is_running` afterwards would therefore drop
        // exactly the frame that carries the final value: a caller watching a transition would see
        // it stop one step short of its target and never be told the last step. The set answers
        // "was this animating when the frame started", which is the question the snapshot needs.
        in_flight.clear();
        for (id, entry) in animations.iter_mut() {
            if entry.anim.is_running() {
                in_flight.push(*id);
                entry.advance_by(delta);
            }
        }

        // Snapshot progress without holding a mutable borrow, then fire the callbacks — the same
        // two-phase shape the buffers above serve: a callback may add or remove animations, which
        // cannot happen while the map is borrowed.
        snapshot.clear();
        for id in in_flight.iter() {
            if let Some(entry) = animations.get(id) {
                snapshot.push((*id, entry.anim.progress()));
            }
        }
        for &(id, progress) in snapshot.iter() {
            if let Some(entry) = animations.get_mut(&id) {
                if (progress - entry.last_progress).abs() > 0.001 || progress == 0.0_f32 {
                    if let Some(ref mut cb) = entry.tick {
                        cb(progress);
                    }
                    entry.last_progress = progress;
                }
            }
        }
        for &(id, progress) in snapshot.iter() {
            if let Some(prop_anim) = property_animations.get_mut(&id) {
                let range = prop_anim.to - prop_anim.from;
                prop_anim.current = prop_anim.from + range * progress;
            }
        }
        // Completed animations are removed and their completion callbacks fired, exactly as a
        // clock-driven advance does, so the two paths leave the driver in the same state. The
        // in-flight buffer is free again by now, so the removal list reuses it rather than
        // allocating a third `Vec`.
        in_flight.clear();
        for (id, entry) in animations.iter() {
            if entry.anim.is_completed() && !entry.anim.config().infinite {
                in_flight.push(*id);
            }
        }
        for id in in_flight.iter() {
            if let Some(mut entry) = animations.remove(id) {
                property_animations.remove(id);
                if let Some(mut cb) = entry.on_complete.take() {
                    cb();
                }
            }
        }
        animations.len()
    }

    /// Register a new animation and return its ID.
    /// The `tick` callback is called every frame with the eased progress \[0,1\].
    pub fn add<F>(&mut self, config: AnimationConfig, tick: F) -> AnimationId
    where
        F: FnMut(f32) + 'static,
    {
        let id = self.next_id;
        self.next_id += 1;
        let mut anim = Animation::new(config);
        anim.start();
        self.animations.insert(
            id,
            ActiveAnimation {
                anim,
                tick: Some(Box::new(tick)),
                on_complete: None,
                last_progress: -1.0,
            },
        );
        id
    }

    /// Register a float animation that interpolates between `from` and `to`.
    /// The `on_tick` callback receives the current interpolated value each frame.
    pub fn add_float<F>(
        &mut self,
        config: AnimationConfig,
        from: f32,
        to: f32,
        mut on_tick: F,
    ) -> AnimationId
    where
        F: FnMut(f32) + 'static,
    {
        let range = to - from;
        self.add(config, move |progress| {
            on_tick(from + range * progress);
        })
    }

    /// Register a color animation that interpolates between `from` and `to`.
    /// The `on_tick` callback receives the current interpolated color each frame.
    pub fn add_color<F>(
        &mut self,
        config: AnimationConfig,
        from: Color,
        to: Color,
        mut on_tick: F,
    ) -> AnimationId
    where
        F: FnMut(Color) + 'static,
    {
        self.add(config, move |progress| {
            // Truncating channel lerp, matching the other rendering paths (see
            // `style::gradient::interpolate_color` for why `Color::blend` is not used here).
            let r = ((1.0 - progress) * from.r as f32 + progress * to.r as f32) as u8;
            let g = ((1.0 - progress) * from.g as f32 + progress * to.g as f32) as u8;
            let b = ((1.0 - progress) * from.b as f32 + progress * to.b as f32) as u8;
            let a = ((1.0 - progress) * from.a as f32 + progress * to.a as f32) as u8;
            on_tick(Color::rgba(r, g, b, a));
        })
    }

    /// Advance all animations by one frame.
    /// Calls tick callbacks with updated progress and removes completed animations.
    /// Returns the number of still-active (running) animations.
    pub fn advance(&mut self) -> usize {
        let Self { animations, property_animations, in_flight, snapshot, .. } = self;
        // Phase 1: Advance internal animation state (iteration counting,
        // on_complete callbacks) by calling update() on every active animation.
        // This must happen before progress snapshots so is_completed() is accurate.
        //
        // The in-flight set is captured first for the same reason `advance_by` captures it: an
        // animation that finishes during this call clears `is_running`, so a snapshot filtered on
        // `is_running` afterwards would silently skip the frame that carries its final value.
        in_flight.clear();
        for (id, entry) in animations.iter_mut() {
            if entry.anim.is_running() {
                in_flight.push(*id);
                entry.anim.update();
            }
        }

        // Snapshot: collect progress without mutable borrows
        snapshot.clear();
        for id in in_flight.iter() {
            if let Some(entry) = animations.get(id) {
                snapshot.push((*id, entry.anim.progress()));
            }
        }
        // Fire tick callbacks with mutable access
        for &(id, progress) in snapshot.iter() {
            if let Some(entry) = animations.get_mut(&id) {
                if (progress - entry.last_progress).abs() > 0.001 || progress == 0.0_f32 {
                    if let Some(ref mut cb) = entry.tick {
                        cb(progress);
                    }
                    entry.last_progress = progress;
                }
            }
        }
        // Update PropertyAnimation.current values so callers reading
        // .current on a PropertyAnimation get the latest interpolated value.
        for &(id, progress) in snapshot.iter() {
            if let Some(prop_anim) = property_animations.get_mut(&id) {
                let range = prop_anim.to - prop_anim.from;
                prop_anim.current = prop_anim.from + range * progress;
            }
        }
        // Remove completed animations, reusing the in-flight buffer for the removal list.
        in_flight.clear();
        for (id, entry) in animations.iter() {
            if entry.anim.is_completed() && !entry.anim.config().infinite {
                in_flight.push(*id);
            }
        }
        for id in in_flight.iter() {
            if let Some(mut entry) = animations.remove(id) {
                property_animations.remove(id);
                if let Some(mut cb) = entry.on_complete.take() {
                    cb();
                }
            }
        }
        animations.len()
    }

    /// Remove and stop a specific animation.
    pub fn remove(&mut self, id: AnimationId) {
        self.animations.remove(&id);
        self.property_animations.remove(&id);
    }

    /// Remove all active animations.
    pub fn clear(&mut self) {
        self.animations.clear();
        self.property_animations.clear();
    }

    /// Returns the number of active (running) animations.
    pub fn len(&self) -> usize {
        self.animations.len()
    }

    /// Returns true if there are no active animations.
    pub fn is_empty(&self) -> bool {
        self.animations.is_empty()
    }

    /// Start animating a named property from `from` to `to` over `duration`.
    /// The `on_tick` callback receives the current value and progress (0.0–1.0).
    pub fn animate<F>(
        &mut self,
        property: impl Into<String>,
        from: f32,
        to: f32,
        duration: Duration,
        easing: EasingFunction,
        mut on_tick: F,
    ) -> AnimationId
    where
        F: FnMut(f32, f32) + 'static,
    {
        let prop: String = property.into();
        let config = AnimationConfig::new(duration).with_easing(easing);
        let range = to - from;
        let id = self.add(config, move |progress| {
            let value = from + range * progress;
            on_tick(value, progress);
        });
        // Store property metadata so callers can inspect active animations
        let current = from;
        self.property_animations
            .insert(id, PropertyAnimation { id, property: prop.clone(), from, to, current });
        id
    }

    /// Convenience: animate with linear easing.
    pub fn animate_linear<F>(
        &mut self,
        property: impl Into<String>,
        from: f32,
        to: f32,
        duration: Duration,
        on_tick: F,
    ) -> AnimationId
    where
        F: FnMut(f32, f32) + 'static,
    {
        self.animate(property, from, to, duration, EasingFunction::Linear, on_tick)
    }

    /// Convenience: animate with ease-in-out easing.
    pub fn animate_ease<F>(
        &mut self,
        property: impl Into<String>,
        from: f32,
        to: f32,
        duration: Duration,
        on_tick: F,
    ) -> AnimationId
    where
        F: FnMut(f32, f32) + 'static,
    {
        self.animate(property, from, to, duration, EasingFunction::EaseInOut, on_tick)
    }

    /// Returns the current progress of an animation, or `None` if not found.
    pub fn get_progress(&self, id: AnimationId) -> Option<f32> {
        self.animations.get(&id).map(|entry| entry.anim.progress())
    }

    /// Whether the animation `id` has finished, or is no longer present.
    ///
    /// This is the lifecycle question the group composers ([`ParallelAnimation`],
    /// [`SequentialAnimation`] and `AnimationGroup`) ask. It must not be derived from
    /// [`AnimationDriver::get_progress`]: a reverse or overshooting child legitimately reads a
    /// value other than `1.0` while running or finished, so comparing progress to `1.0` makes a
    /// reverse child look complete at its start and a multi-iteration child never complete. A
    /// missing id counts as done, matching the composers' documented "removed means complete".
    pub fn is_finished(&self, id: AnimationId) -> bool {
        self.animations.get(&id).map(|entry| entry.anim.is_completed()).unwrap_or(true)
    }

    /// Returns the `PropertyAnimation` metadata for a given animation ID, if any.
    ///
    /// Only animations created via [`animate`](AnimationDriver::animate) (or its
    /// convenience wrappers) will have a `PropertyAnimation` entry.
    pub fn get_property_animation(&self, id: AnimationId) -> Option<&PropertyAnimation> {
        self.property_animations.get(&id)
    }
}

crate::impl_default_via_new!(AnimationDriver);

/// A group of animations that run concurrently.
///
/// This is a grouping handle, not a scheduler: the child animations are still
/// owned and advanced by [`AnimationDriver`], and the group only remembers their
/// IDs so they can be waited on together. Removing a child from the driver
/// makes this group consider it complete, because a missing animation has no
/// progress to check.
pub struct ParallelAnimation {
    ids: Vec<AnimationId>,
}

impl ParallelAnimation {
    /// Creates a group with no children.
    pub fn new() -> Self {
        Self { ids: Vec::new() }
    }
}

crate::impl_default_via_new!(ParallelAnimation);

impl ParallelAnimation {
    /// Add a child animation (managed externally via AnimationDriver).
    pub fn add(&mut self, id: AnimationId) {
        self.ids.push(id);
    }

    /// Returns true if all child animations have completed.
    pub fn is_completed(&self, driver: &AnimationDriver) -> bool {
        self.ids.iter().all(|id| driver.is_finished(*id))
    }

    /// Returns the number of child animations.
    pub fn len(&self) -> usize {
        self.ids.len()
    }

    /// Reports whether the group has no children. A group with no children is
    /// also treated as completed by [`ParallelAnimation::is_completed`].
    pub fn is_empty(&self) -> bool {
        self.ids.is_empty()
    }
}

/// A group of animations that run sequentially (one after another).
///
/// Child configs are stored, not live animations: each one is started on the
/// driver only when the previous one reports full progress. That single-child
/// handoff is also the main limitation — a child whose [`AnimationConfig`] is
/// infinite would stall the sequence forever.
pub struct SequentialAnimation {
    animations: Vec<AnimationConfig>,
    current_index: usize,
    current_id: Option<AnimationId>,
}

impl SequentialAnimation {
    /// Creates a sequence with no steps, positioned before the first one.
    pub fn new() -> Self {
        Self { animations: Vec::new(), current_index: 0, current_id: None }
    }
}

crate::impl_default_via_new!(SequentialAnimation);

impl SequentialAnimation {
    /// Add an animation config to the sequence.
    pub fn add(&mut self, config: AnimationConfig) {
        self.animations.push(config);
    }

    /// Start or advance the sequence. Call this each frame.
    /// Returns true if the sequence is still running.
    pub fn advance<F>(&mut self, driver: &mut AnimationDriver, mut on_tick: F) -> bool
    where
        F: FnMut(usize, f32) + 'static,
    {
        if self.current_index >= self.animations.len() {
            return false; // All done
        }
        // Check if current animation is done or not started
        match self.current_id {
            None => {
                // Start next animation
                let config = self.animations[self.current_index].clone();
                let idx = self.current_index;
                let id = driver.add(config, move |p| {
                    on_tick(idx, p);
                });
                self.current_id = Some(id);
                true
            }
            Some(id) => {
                if driver.is_finished(id) {
                    // Current animation done, move to next
                    self.current_index += 1;
                    self.current_id = None;
                    if self.current_index < self.animations.len() {
                        let config = self.animations[self.current_index].clone();
                        let idx = self.current_index;
                        let id = driver.add(config, move |p| {
                            on_tick(idx, p);
                        });
                        self.current_id = Some(id);
                    }
                    self.current_index < self.animations.len()
                } else {
                    true // still running
                }
            }
        }
    }

    /// Resets the sequence to its first step, so the next
    /// [`SequentialAnimation::advance`] starts it over.
    ///
    /// Any animation the sequence already registered keeps running on the
    /// driver; the sequence simply forgets it and starts a fresh one.
    pub fn reset(&mut self) {
        self.current_index = 0;
        self.current_id = None;
    }

    /// Returns the number of animation configs in the sequence.
    pub fn len(&self) -> usize {
        self.animations.len()
    }

    /// Returns `true` if the sequence contains no animations.
    pub fn is_empty(&self) -> bool {
        self.animations.is_empty()
    }
}

// ═══════════════════════════════════════════════════════════════════════════
// BLUE11 R6.1: Keyframe Animation
// ═══════════════════════════════════════════════════════════════════════════

/// A single keyframe at a specific progress point.
#[derive(Debug, Clone)]
pub struct Keyframe {
    /// Normalized time [0.0, 1.0] for this keyframe.
    pub time: f32,
    /// Value at this keyframe.
    pub value: f32,
    /// Easing function to use when interpolating FROM this keyframe to the next.
    pub easing: EasingFunction,
}

/// A multi-keyframe animation that interpolates through a series of waypoints.
pub struct KeyframeAnimation {
    keyframes: Vec<Keyframe>,
    animation: Animation,
    config: AnimationConfig,
}

impl KeyframeAnimation {
    /// Create a new keyframe animation with the given keyframes and config.
    /// Keyframes should be sorted by time ascending.
    pub fn new(keyframes: Vec<Keyframe>, config: AnimationConfig) -> Self {
        Self { keyframes, config: config.clone(), animation: Animation::new(config) }
    }

    /// Start the animation.
    pub fn start(&mut self) {
        self.animation.start();
    }
    /// Stop the animation and reset progress.
    pub fn stop(&mut self) {
        self.animation.stop();
    }
    /// Pause the animation.
    pub fn pause(&mut self) {
        self.animation.pause();
    }
    /// Resume from pause.
    pub fn resume(&mut self) {
        self.animation.resume();
    }
    /// Returns a reference to the animation config.
    pub fn config(&self) -> &AnimationConfig {
        &self.config
    }

    /// Returns true if the animation is currently running.
    pub fn is_running(&self) -> bool {
        self.animation.is_running()
    }

    /// Evaluate the current interpolated value based on animation progress.
    pub fn current_value(&self) -> f32 {
        let progress = self.animation.progress();
        self.evaluate(progress)
    }

    /// Evaluate the animation at a given normalized progress [0.0, 1.0].
    pub fn evaluate(&self, progress: f32) -> f32 {
        if self.keyframes.is_empty() {
            return 0.0;
        }
        let progress = progress.clamp(0.0, 1.0);
        if progress <= self.keyframes[0].time {
            return self.keyframes[0].value;
        }
        if progress >= self.keyframes.last().unwrap().time {
            return self.keyframes.last().unwrap().value;
        }
        for i in 0..self.keyframes.len() - 1 {
            let kf_a = &self.keyframes[i];
            let kf_b = &self.keyframes[i + 1];
            if progress >= kf_a.time && progress <= kf_b.time {
                let segment_duration = kf_b.time - kf_a.time;
                if segment_duration == 0.0 {
                    return kf_b.value;
                }
                let local_t = (progress - kf_a.time) / segment_duration;
                let eased_t = kf_a.easing.apply(local_t);
                return kf_a.value + (kf_b.value - kf_a.value) * eased_t;
            }
        }
        self.keyframes.last().unwrap().value
    }

    /// Update animation state (call each frame).
    pub fn update(&mut self) {
        self.animation.update();
    }
    /// Returns true when the animation has completed.
    pub fn is_completed(&self) -> bool {
        self.animation.is_completed()
    }
}

// ═══════════════════════════════════════════════════════════════════════════
// BLUE11 R6.2: CSS-style Transition Animation
// ═══════════════════════════════════════════════════════════════════════════

/// A CSS-style transition rule mapping a property to an animation config.
#[derive(Debug, Clone)]
pub struct TransitionRule {
    /// Property name pattern.
    pub property: String,
    /// Animation configuration (duration, easing, delay).
    pub config: AnimationConfig,
}

impl TransitionRule {
    /// Creates a rule for `property` that transitions over `duration` with
    /// `easing`, with no delay.
    pub fn new(property: impl Into<String>, duration: Duration, easing: EasingFunction) -> Self {
        Self {
            property: property.into(),
            config: AnimationConfig::new(duration).with_easing(easing),
        }
    }
    /// Returns a copy that waits `delay` before starting each transition.
    pub fn with_delay(mut self, delay: Duration) -> Self {
        self.config = self.config.clone().with_delay(delay);
        self
    }
}

/// Manages CSS-style transitions for a set of properties.
/// When a property value changes, smoothly interpolates to the new value.
#[derive(Debug, Clone)]
pub struct TransitionManager {
    transitions: HashMap<String, ActiveTransition>,
    rules: HashMap<String, TransitionRule>,
}

#[derive(Debug, Clone)]
struct ActiveTransition {
    from: f32,
    to: f32,
    current: f32,
    elapsed: Duration,
    rule: TransitionRule,
    completed: bool,
}

impl TransitionManager {
    /// Create a new empty transition manager.
    pub fn new() -> Self {
        Self { transitions: HashMap::new(), rules: HashMap::new() }
    }
    /// Add a transition rule for a property.
    pub fn add_rule(&mut self, rule: TransitionRule) {
        self.rules.insert(rule.property.clone(), rule);
    }
    /// Remove a transition rule for a property.
    pub fn remove_rule(&mut self, property: &str) {
        self.rules.remove(property);
    }
    /// Check if a transition rule exists.
    pub fn has_rule(&self, property: &str) -> bool {
        self.rules.contains_key(property)
    }

    /// Begin a transition for a property from its old value to a new value.
    pub fn transition_to(&mut self, property: impl Into<String>, value: f32) {
        let prop = property.into();
        if let Some(rule) = self.rules.get(&prop) {
            let current = self.transitions.get(&prop).map(|t| t.current).unwrap_or(value);
            self.transitions.insert(
                prop,
                ActiveTransition {
                    from: current,
                    to: value,
                    current,
                    elapsed: Duration::ZERO,
                    rule: rule.clone(),
                    completed: false,
                },
            );
        }
    }

    /// Advance all active transitions by `dt`. Returns true if any still active.
    pub fn advance(&mut self, dt: Duration) -> bool {
        let mut any_active = false;
        for t in self.transitions.values_mut() {
            if t.completed {
                continue;
            }
            t.elapsed += dt;
            if t.elapsed >= t.rule.config.delay {
                let active_time = t.elapsed - t.rule.config.delay;
                let duration_s = t.rule.config.duration.as_secs_f32();
                let progress = if duration_s > 0.0 {
                    (active_time.as_secs_f32() / duration_s).clamp(0.0, 1.0)
                } else {
                    1.0
                };
                let eased = t.rule.config.easing.apply(progress);
                t.current = t.from + (t.to - t.from) * eased;
                if progress >= 1.0 {
                    t.current = t.to;
                    t.completed = true;
                } else {
                    any_active = true;
                }
            } else {
                any_active = true;
            }
        }
        self.transitions.retain(|_, t| !t.completed);
        any_active
    }
    /// Get the current value of a transitioning property.
    pub fn current_value(&self, property: &str) -> Option<f32> {
        self.transitions.get(property).map(|t| t.current)
    }
    /// The number of child animations currently mid-transition.
    pub fn len(&self) -> usize {
        self.transitions.len()
    }
    /// Reports whether no property is currently transitioning.
    pub fn is_empty(&self) -> bool {
        self.transitions.is_empty()
    }
    /// Drops every in-flight transition and their values, keeping the registered
    /// rules so later changes to the same properties still animate.
    pub fn clear(&mut self) {
        self.transitions.clear();
    }
}

crate::impl_default_via_new!(TransitionManager);

/// Physical spring animation (iOS-style spring physics).
pub struct SpringAnimation {
    animation: Animation,
    from_value: f32,
    to_value: f32,
    stiffness: f32,
    damping: f32,
    mass: f32,
    velocity: f32,
    current_value: f32,
}

impl SpringAnimation {
    /// Creates a stopped spring running from `from` to `to`.
    ///
    /// The defaults are stiffness `200.0`, damping `20.0` and mass `1.0`. The
    /// inner [`Animation`] is given a 1-second duration, but the spring's own
    /// integration decides when it settles, so that duration does not bound it.
    pub fn new(from: f32, to: f32) -> Self {
        Self {
            animation: Animation::new(AnimationConfig::new(Duration::from_secs(1))),
            from_value: from,
            to_value: to,
            stiffness: 200.0,
            damping: 20.0,
            mass: 1.0,
            velocity: 0.0,
            current_value: from,
        }
    }
    /// Returns a copy with the spring constant set to `s`: a higher value pulls
    /// the value toward the target harder, making the motion faster and bouncier.
    pub fn with_stiffness(mut self, s: f32) -> Self {
        self.stiffness = s;
        self
    }
    /// Returns a copy with the damping coefficient set to `d`: a higher value
    /// bleeds off velocity faster, reducing overshoot. `0.0` lets the spring
    /// oscillate indefinitely.
    pub fn with_damping(mut self, d: f32) -> Self {
        self.damping = d;
        self
    }
    /// Returns a copy with the moving mass set to `m`.
    ///
    /// Mass scales the acceleration (`a = F / m`), so a larger value slows every
    /// response. It must not be zero: the acceleration divides by it, so a zero
    /// mass yields a non-finite step.
    pub fn with_mass(mut self, m: f32) -> Self {
        self.mass = m;
        self
    }
    /// Returns a copy with the current velocity set to `v`, in units per second.
    ///
    /// Used by [`PropertyDriver`] when it hands a spring in flight to a fresh integrator: the
    /// driver keeps the velocity across ticks so an interrupted spring continues with the
    /// momentum it already had instead of restarting from rest.
    pub fn with_velocity(mut self, v: f32) -> Self {
        self.velocity = v;
        self
    }
    /// The current velocity, in units per second.
    pub fn velocity(&self) -> f32 {
        self.velocity
    }
    /// Starts the spring.
    ///
    /// The value is *not* reset to `from_value`; integration continues from
    /// wherever [`SpringAnimation::current_value`] currently stands.
    pub fn start(&mut self) {
        self.animation.start();
    }
    /// Stops the spring where it is, leaving the current value and velocity as
    /// they were.
    pub fn stop(&mut self) {
        self.animation.stop();
    }
    /// The value the spring was created from.
    ///
    /// This is informational: integration starts from `current_value`, so
    /// restarting a spring does not return it to `from_value`.
    pub fn from_value(&self) -> f32 {
        self.from_value
    }

    /// The value the spring has integrated to so far.
    pub fn current_value(&self) -> f32 {
        self.current_value
    }
    /// Reports whether the spring is running and not paused.
    pub fn is_running(&self) -> bool {
        self.animation.is_running()
    }

    /// Integrates the spring forward by one frame of `dt`.
    ///
    /// `dt` is clamped to at most 50 ms so a stalled or resumed application
    /// cannot take an oversized integration step. The spring is considered
    /// settled — and stops itself, snapping exactly onto `to_value` — once both
    /// the displacement and the velocity fall below `0.5`. This is a
    /// single-step Euler integration and is not unconditionally stable: a large
    /// `stiffness` combined with a small `mass` can diverge.
    pub fn update(&mut self, dt: Duration) {
        if !self.animation.is_running() {
            return;
        }
        let dt_secs = dt.as_secs_f32().min(0.05);
        // Spring physics: F = -kx - cv
        let displacement = self.current_value - self.to_value;
        let spring_force = -self.stiffness * displacement;
        let damping_force = -self.damping * self.velocity;
        let acceleration = (spring_force + damping_force) / self.mass;
        self.velocity += acceleration * dt_secs;
        self.current_value += self.velocity * dt_secs;
        // Check if settled
        if displacement.abs() < 0.5 && self.velocity.abs() < 0.5 {
            self.current_value = self.to_value;
            self.velocity = 0.0;
            self.animation.stop();
        }
    }
}

/// The half-period a text cursor spends in each of its two visible states.
///
/// Half a second is the tempo every platform's text field converged on, and it is what the
/// controls in this crate document. It is a named constant rather than a literal repeated at
/// each cursor so a future change of tempo moves them all together.
pub const CURSOR_BLINK_HALF_PERIOD_MS: u32 = 500;

/// The on/off state of a blinking text cursor, advanced by frame deltas.
///
/// # Why this is a type rather than a timer inside each control
///
/// Eight controls in this crate draw a caret, and each one used to draw a solid line while its
/// documentation claimed the cursor blinked. Giving every one of them its own `Instant`, its own
/// half-period literal and its own phase reset would be eight chances to disagree — and it is the
/// exact shape that produced the discrepancy: the comment described behaviour no code had.
///
/// So the state lives here, once, and a control owns a field of this type and forwards its
/// frame delta. The type is deliberately independent of any widget: it holds no `ObjectId`, no
/// geometry and no appearance, only "which half of the cycle are we in", so the same logic serves
/// a caret in a single-line field and one in a code editor.
///
/// # Why it is delta-driven
///
/// The convention every animated control in this crate follows is `tick(delta_ms) -> bool`, which
/// lets a host supply the frame delta instead of the control reading the wall clock. That keeps a
/// test able to reach a blink state without sleeping, and keeps a host that renders on demand in
/// control of the clock.
#[derive(Debug, Clone, Copy)]
pub struct CursorBlink {
    /// Milliseconds elapsed within the current half-period, in `0..half_period_ms`.
    elapsed_in_half: u32,
    /// Whether the cursor is drawn in the current half-period.
    visible: bool,
    /// Whether the cursor is animating at all. A blurred or read-only field holds a steady
    /// cursor and must not ask its host for frames.
    running: bool,
}

impl Default for CursorBlink {
    /// A cursor that is visible and not yet animating — the state of a field that has just been
    /// constructed but not focused.
    fn default() -> Self {
        Self { elapsed_in_half: 0, visible: true, running: false }
    }
}

impl CursorBlink {
    /// A cursor that is visible and not animating.
    pub fn new() -> Self {
        Self::default()
    }

    /// Starts blinking, showing the cursor.
    ///
    /// Called when a field gains focus. Restarting the phase on every focus is what makes the
    /// cursor immediately visible when a reader clicks into a field, rather than possibly appearing
    /// on the far side of an invisible half-period.
    pub fn start(&mut self) {
        self.elapsed_in_half = 0;
        self.visible = true;
        self.running = true;
    }

    /// Stops blinking and leaves the cursor visible.
    ///
    /// Called when a field loses focus. The cursor is left *visible* rather than hidden because a
    /// blurred field still shows where editing would resume; a hidden caret would read as a
    /// rendering failure.
    pub fn stop(&mut self) {
        self.elapsed_in_half = 0;
        self.visible = true;
        self.running = false;
    }

    /// Whether the cursor is currently drawn.
    pub fn is_visible(&self) -> bool {
        self.visible
    }

    /// Whether the cursor is animating.
    pub fn is_running(&self) -> bool {
        self.running
    }

    /// Advances the blink by `delta_ms` and reports whether another frame is needed.
    ///
    /// The same contract [`AnimationDriver::advance_by`] and `FloatingLabel::tick` follow: the
    /// return value answers "is there still work", so a host stops scheduling frames for a field
    /// whose cursor is not blinking. A `delta_ms` larger than one half-period is consumed
    /// half-period by half-period rather than snapping, so a stalled frame loop resumes at the
    /// correct phase instead of silently skipping a whole cycle's worth of flips.
    pub fn tick(&mut self, delta_ms: u32) -> bool {
        if !self.running {
            return false;
        }
        self.elapsed_in_half += delta_ms;
        while self.elapsed_in_half >= CURSOR_BLINK_HALF_PERIOD_MS {
            self.elapsed_in_half -= CURSOR_BLINK_HALF_PERIOD_MS;
            self.visible = !self.visible;
        }
        // A running cursor always owes the next frame: the blink is periodic, so the frame that
        // shows it is never the last one. Reporting `false` here would be the "settled" signal,
        // and a blink never settles.
        true
    }
}

/// Which of the theme's motion tokens prices a transition.
///
/// Named rather than passed as a bare `u32`, so the *choice of tempo* is a decision a control
/// states once, in one word, instead of reading a field out of the theme at its call site — and
/// so a control cannot accidentally price itself from an unrelated duration.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum TransitionTempo {
    /// The theme's `Motion::fast` — a direct reaction to the pointer.
    Fast,
    /// The theme's `Motion::normal` — a control's own state change. The default, and what
    /// Material's `kThemeChangeDuration` (200 ms) describes.
    #[default]
    Normal,
    /// The theme's `Motion::slow` — a larger movement, such as a toggle travelling.
    Slow,
}

impl TransitionTempo {
    /// The duration this tempo names in the active theme.
    ///
    /// Read through [`crate::style`] rather than `crate::theme` directly: `crate::theme`
    /// only exists in a build with a device profile, so naming it here made the module
    /// fail to compile under `mini`/`embedded`. The `style` layer is the profile-safe
    /// facade every other control already goes through.
    pub fn duration_ms(self) -> u32 {
        // The `Motion` token set, or the crate's own defaults when no theme is active.
        // `normal` (200 ms) is the value the old hardcoded call sites used, so a build
        // with no theme behaves exactly as before.
        let (fast, normal, slow) = crate::style::motion_tokens();
        match self {
            TransitionTempo::Fast => fast,
            TransitionTempo::Normal => normal,
            TransitionTempo::Slow => slow,
        }
    }
}

/// A single control's state transition, advanced by frame deltas.
///
/// # Why this is a type rather than a few fields in each control
///
/// Dozens of controls animate one thing: how far they are between their resting appearance and
/// their interactive one. Each one that reimplements the interpolation also reimplements the same
/// decisions — what `tick`'s return value means, which of the theme's motion tokens prices it,
/// and how the engine's callback ownership works — and a control that gets any of them wrong
/// fails quietly. Two shapes of that failure were already present in the crate: `Button` carried
/// the interpolation inline (including the `Rc<Cell<_>>` dance the engine's callback ownership
/// requires), and `FloatingLabel` had re-derived it as an **exponential approach** that never
/// actually arrived and could not be re-priced by a theme.
///
/// # The contract
///
/// [`Transition::tick`] follows `tick(delta_ms) -> bool`: it returns `true` while there is still
/// movement and `false` once the value has settled, so a host can stop scheduling frames. The
/// duration is read from the theme *per tick*, so a theme switch re-prices a transition already
/// in flight instead of stranding it at the old tempo.
///
/// # Why the target is supplied every tick
///
/// A press that arrives mid-hover **re-aims the same progress** rather than restarting from zero.
/// That is what makes a quick press-and-release read as one movement instead of two fades. The
/// caller states the target from its own state on each call, so a change that arrived without a
/// `tick` in between is picked up rather than missed.
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct Transition {
    /// Where the value is now, in `0.0..=1.0`.
    progress: f32,
    /// Which motion token prices the transition.
    tempo: TransitionTempo,
}

impl Default for Transition {
    /// At rest: a freshly constructed control must not fade *out* on its first frame, which is
    /// what starting at the interactive end of the range would do.
    fn default() -> Self {
        Self { progress: 0.0, tempo: TransitionTempo::Normal }
    }
}

impl Transition {
    /// A transition at rest, priced by the theme's `normal` tempo.
    pub fn new() -> Self {
        Self::default()
    }

    /// A transition at rest with an explicit tempo.
    pub fn with_tempo(tempo: TransitionTempo) -> Self {
        Self { progress: 0.0, tempo }
    }

    /// Where the value is now, in `0.0..=1.0`.
    pub fn progress(&self) -> f32 {
        self.progress
    }

    /// Moves the value to `progress`, snapping it and stopping any motion.
    ///
    /// Used when a control is reset or disabled: the caller wants a definite appearance, not a
    /// fade toward it.
    pub fn reset_to(&mut self, progress: f32) {
        self.progress = progress.clamp(0.0, 1.0);
    }

    /// Advances toward `target` by `delta_ms` and reports whether another frame is needed.
    ///
    /// # The interpolation is the engine's, not this type's
    ///
    /// The crate already owns an easing engine ([`AnimationDriver`]). This type drives it with
    /// `advance_by`, so a transition follows the same curve as every other animation in the crate,
    /// and the easing function stays a theme decision rather than something each control chooses.
    ///
    /// The driver owns its callbacks, so the value it produces comes back through a shared cell
    /// rather than an assignment to a captured local: `move |v| observed = v` would move the
    /// local into the closure and leave the caller reading the pre-move value, which is how a
    /// transition silently never advances.
    ///
    /// # Why the step is paced from the tempo instead of coming from the engine
    ///
    /// The engine's easing is applied to the *progress of a whole run*, and this type rebuilds the
    /// driver on every call — so handing it the frame delta would hand it an animation that is
    /// priced at `delta_ms` and asked to advance by `delta_ms`. That run is at 100% in one step,
    /// the easing is evaluated at `1.0`, and the value therefore arrives at the target on the
    /// **first** frame. The theme's easing could not soften anything, because there was no
    /// progress left for it to shape: with the crate's default `EaseOut`, a `Normal`-paced
    /// transition moved 0 -> 1 on one 120 ms frame and a `Slow` one reached 0.4. Every hover,
    /// press and toggle in the library was a cut, which is the one thing these transitions exist
    /// to remove.
    ///
    /// So the fraction stepped is computed here, from the tempo and `delta_ms` — the same
    /// `delta / duration` the engine would derive, applied directly to the value. The easing
    /// curve is the crate's motion curve, so a transition and the driver it mirrors agree.
    pub fn tick(&mut self, target: f32, delta_ms: u32) -> bool {
        let target = target.clamp(0.0, 1.0);
        if (self.progress - target).abs() < f32::EPSILON {
            return false;
        }
        let duration_ms = self.tempo.duration_ms().max(1);
        // The share of the whole transition one frame is worth. Clamped to 1.0 because a frame
        // longer than the transition (a stalled host, a debugger breakpoint) must finish it, not
        // overshoot; a `f32::EPSILON` floor keeps a zero-duration token from dividing by zero.
        let step = (delta_ms as f32 / duration_ms as f32).clamp(f32::EPSILON, 1.0);

        let from = self.progress;
        // The interpolation is this frame's share of the remaining travel, eased by the crate's
        // motion curve. An `AnimationDriver` used to be constructed here, advanced by 1 ms, and
        // dropped on every call: its answer was never read, yet it cost a `HashMap`, an
        // `Rc<Cell>` and a boxed callback per animating control per frame.
        let curve = crate::style::motion_easing();
        let next = from + (target - from) * curve.apply(step);
        // # "Still moving" is asked of the *value*, and the tolerance is one step
        //
        // The step applied above is a geometric approach, so its answer says nothing about whether
        // this transition is done. Two facts make the value the right place
        // to ask. **Reaching the target is what draws the animation's last frame**, so "needs
        // another frame" is exactly "has not reached it" — and once it has, the first arm above
        // returns `false` for every later call, so the snap does not re-trigger. And because the
        // remainder shrinks by `(1 - step)` each frame, the approach is geometric: with this test
        // the travel settles in about `ln(tolerance) / ln(1 - step)` frames (about 44 at a 16 ms
        // step against a 200 ms duration), in both real time and frame count. An animation whose
        // target is inside the tolerance is **snapped** rather than approached —
        // `target * (1 - tolerance)` is well under a pixel for every position a control has, so
        // the difference is invisible and the old rule would have left a visible one for the rest
        // of the frame loop's life.
        //
        // # Why the snap is published before it is decided
        //
        // `self.progress` is assigned `target` on the settle frame, so a caller that advances this
        // transition and then reads the value sees the animation's **end state on the frame it
        // ends** rather than one step short of it. The earlier shape wrote the eased value and
        // returned `false`, which meant the final value was only visible to a caller who ticked a
        // transition that was already finished — the frame that drew the ending showed nearly it.
        let tolerance = step.clamp(f32::EPSILON, 1.0);
        if (next - target).abs() <= tolerance {
            self.progress = target;
            return false;
        }
        self.progress = next;
        true
    }
}

/// A **named** motion token, for the one property a control drives itself.
///
/// # Why a second name for [`TransitionTempo`]
///
/// `TransitionTempo` is the same three tokens, and [`MotionSlot`] deliberately does not
/// replace it: the former is what a `Transition` is *configured by* at construction, while
/// this is what a [`PropertyDriver`] is *created with* and what BLUE24 §2.4's gate reads.
/// Keeping the two spellings would be the "two enums, one meaning" mistake principle #54
/// forbids -- so this is a **type alias**, not a copy: a reader sees one token set, and a
/// new variant added to `TransitionTempo` cannot silently fail to reach a driver.
pub type MotionSlot = TransitionTempo;

/// One numeric property moving between two values, advanced once per frame.
///
/// # Why this is not [`AnimationDriver`]
///
/// `AnimationDriver` is **registry-shaped**: a caller registers a named animation and the
/// driver advances it by id. That shape has the failure BLUE23 §3.3 already documented --
/// "registered and never unregistered" -- and a control cannot answer "am I moving?"
/// from a registry it does not own.
///
/// What the crate needs is **self-describing**: the control *is* the animation's owner, and
/// `is_moving()` is its answer about itself. So this type is `Transition`'s sibling, with
/// the one thing `Transition` left to its callers made explicit: **the target is stored**.
///
/// # Why storing the target removes a field from every control
///
/// `Transition::tick(target, delta)` takes the target *every call*, so a control that wants
/// to answer `is_animating()` between frames has to cache it... which is exactly the second
/// private field (`interaction_target: f32`) that `Button` and `ToggleButton` each carry.
/// Two controls, two copies of the same three lines, and the copies had to agree with
/// `widget_state()` on their own. Here the target is part of the value, so `set_target` is
/// the only writer and `is_moving` reads the same fact the interpolation does -- the
/// duplicated field goes away because there is nothing left for it to cache.
///
/// # Why there is no generic `T`
///
/// The properties that need driving are **scalar progress** (0..=1: a button's hover fill,
/// a toggle's travel) and **pixel offset** (a thumb position), and both interpolate as
/// `f32`. An `Interpolate` trait would add a `where` clause at every call site to express
/// what one `f32` already expresses (principle #28). A future *colour* interpolation should
/// be a new named method, not a type parameter.
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct PropertyDriver {
    /// Where the value is now.
    current: f32,
    /// Where it is heading. Kept here so `is_moving` and `set_target` agree by construction.
    target: f32,
    /// Which motion token prices the move.
    tempo: MotionSlot,
    /// Which shape the move follows.
    curve: MotionCurve,
    /// Velocity carried across spring ticks, in normalised units per second.
    ///
    /// Only the spring path writes it. It is stored on the driver rather than in a
    /// [`SpringAnimation`] because the driver must stay `Copy`, and because the integrator is
    /// rebuilt every tick from this state — the physics is the engine's, the memory of it is
    /// the driver's.
    spring_velocity: f32,
}

impl Default for PropertyDriver {
    /// At the **resting** end, priced normally.
    ///
    /// This is the crate's one answer to "what is the first value", and it is the safe one:
    /// starting at the target end would make a freshly built control animate *away* from its
    /// own state on the first frame it is drawn (the defect `button.rs` records in prose and
    /// `PieMenu` still exhibited -- BLUE24 §2.4 gate B exists to pin it here instead).
    fn default() -> Self {
        Self {
            current: 0.0,
            target: 0.0,
            tempo: MotionSlot::Normal,
            curve: MotionCurve::Easing,
            spring_velocity: 0.0,
        }
    }
}

impl PropertyDriver {
    /// A driver resting at `value`, priced by `tempo`.
    ///
    /// The target starts equal to `value`, so a driver built at a non-zero value is **still**,
    /// not "about to travel to zero". A control that wants the value to move calls
    /// [`set_target`](Self::set_target).
    pub fn at(value: f32, tempo: MotionSlot) -> Self {
        Self {
            current: value,
            target: value,
            tempo,
            curve: MotionCurve::Easing,
            spring_velocity: 0.0,
        }
    }

    /// A driver resting at `value`, priced by `tempo`, following `curve`.
    ///
    /// The curve is a driver property rather than a theme read so a control can opt one
    /// property into a spring (a switch's thumb, a sheet's reveal) while the rest of the window
    /// keeps the theme's easing. [`MotionCurve::Easing`] reproduces [`Self::at`] exactly.
    pub fn with_curve(value: f32, tempo: MotionSlot, curve: MotionCurve) -> Self {
        Self { curve, ..Self::at(value, tempo) }
    }

    /// Replaces the curve without touching the current value or target.
    ///
    /// Switching to or from a spring discards the accumulated spring velocity: a curve is a
    /// statement about the shape of the **remaining** movement, and carrying momentum from a
    /// different shape would make the new curve overshoot for a reason the caller did not ask
    /// for. Re-aiming with [`Self::set_target`] is the way to interrupt a spring while keeping
    /// its momentum.
    pub fn set_curve(&mut self, curve: MotionCurve) {
        self.curve = curve;
        self.spring_velocity = 0.0;
    }

    /// The curve this driver follows.
    pub fn curve(&self) -> MotionCurve {
        self.curve
    }

    /// The value the driver is currently interpolating, which is the same `f32` the
    /// interpolation moves -- not a separate cache.
    pub fn value(&self) -> f32 {
        self.current
    }

    /// Aim the driver at `target`.
    ///
    /// # Same value does not restart
    ///
    /// Setting the target the driver is already at (or already heading to) is a no-op, so a
    /// state change that is re-reported every frame -- which is what a `widget_state()`
    /// derived target does -- cannot reset the progress and make the movement stutter. That is
    /// the "interrupt re-aims rather than restarts" property `Transition` already had, kept
    /// here by simply not touching `current`.
    pub fn set_target(&mut self, target: f32) {
        self.target = target;
    }

    /// The value the driver is heading toward.
    pub fn target(&self) -> f32 {
        self.target
    }

    /// Advance by `delta_ms` toward the target; `true` while there is still movement.
    ///
    /// [`MotionCurve::Easing`] delegates to [`Transition`], so there is one place that knows
    /// the curve, the pacing and the snap tolerance. [`MotionCurve::Spring`] delegates to the
    /// crate's [`SpringAnimation`] integrator, with the preset's damping ratio and a stiffness
    /// folded from the driver's tempo. Both paths store their result back into `current`, so
    /// [`Self::is_moving`] reads one fact regardless of which curve produced it.
    pub fn tick(&mut self, delta_ms: u32) -> bool {
        if (self.current - self.target).abs() <= f32::EPSILON {
            self.spring_velocity = 0.0;
            return false;
        }
        // Reduced motion reaches the target on this frame rather than skipping the animation:
        // the value is *reached*, so every caller sees the same end state it would after the
        // full transition. This is the same rule `motion_tokens` applies by collapsing the
        // duration to zero, stated once here as well because a driver can carry an explicit
        // curve the token set does not price.
        if crate::style::environment::environment().prefers_reduced_motion() {
            let target = self.target;
            self.jump_to(target);
            return false;
        }
        match self.curve {
            MotionCurve::Easing => {
                let mut transition = Transition::with_tempo(self.tempo);
                transition.reset_to(self.current);
                let moving = transition.tick(self.target, delta_ms);
                self.current = transition.progress();
                self.spring_velocity = 0.0;
                moving
            }
            MotionCurve::Spring(preset) => self.tick_spring(preset, delta_ms),
        }
    }

    /// One spring step, using the crate's [`SpringAnimation`] integrator.
    ///
    /// The integrator's own settle tolerance is half a unit, which is an enormous distance on a
    /// `0..=1` property. The values are therefore scaled to a thousand units, where that
    /// tolerance is a twentieth of a percent — small enough to be invisible and large enough
    /// that floating-point noise cannot keep a settled spring running. The frame delta is split
    /// into short substeps because the integration is explicit Euler: at 8 ms the fastest
    /// preset stays well inside the stability bound, while a single stalled 100 ms frame would
    /// not.
    fn tick_spring(&mut self, preset: SpringPreset, delta_ms: u32) -> bool {
        const VALUE_SCALE: f32 = 1_000.0;
        const MAX_SUBSTEP_MS: u32 = 8;

        // A zero-duration token means "reach the target now" everywhere else in the crate; a
        // spring asked to settle in zero time has no finite stiffness, so it takes the same
        // one-frame path.
        if self.tempo.duration_ms() == 0 {
            let target = self.target;
            self.jump_to(target);
            return false;
        }

        let (stiffness, damping) = preset.parameters(self.tempo);
        let mut spring =
            SpringAnimation::new(self.current * VALUE_SCALE, self.target * VALUE_SCALE)
                .with_stiffness(stiffness)
                .with_damping(damping)
                .with_velocity(self.spring_velocity * VALUE_SCALE);
        spring.start();

        let mut remaining = delta_ms;
        loop {
            let step = remaining.min(MAX_SUBSTEP_MS);
            spring.update(Duration::from_millis(step as u64));
            remaining = remaining.saturating_sub(step);
            if !spring.is_running() || remaining == 0 {
                break;
            }
        }

        self.current = spring.current_value() / VALUE_SCALE;
        self.spring_velocity = spring.velocity() / VALUE_SCALE;
        if spring.is_running() {
            true
        } else {
            self.current = self.target;
            self.spring_velocity = 0.0;
            false
        }
    }

    /// Whether the driver is between two values -- **answers only, never advances**.
    ///
    /// This is the query `Widget::is_animating` needs: a frame loop asks every control
    /// whether it owes frames without advancing any of them, so that the advance happens
    /// exactly once and in one place (BLUE24 §1.2).
    pub fn is_moving(&self) -> bool {
        (self.current - self.target).abs() > f32::EPSILON
    }

    /// Jump to `value` and stop, so the next [`tick`](Self::tick) does not move it.
    ///
    /// Both ends are set, because a driver that jumped its position but kept pointing at the
    /// old target would immediately animate away from where it was just placed -- which is
    /// what a control disabling itself or being reset actually wants to avoid.
    pub fn jump_to(&mut self, value: f32) {
        self.current = value;
        self.target = value;
        self.spring_velocity = 0.0;
    }
}

// ────────────────────────────────────────────
// Frame clock
// ────────────────────────────────────────────

/// The longest delta a frame clock will report.
///
/// A host that slept (a laptop lid, a suspended process) comes back with a timestamp gap of
/// seconds. Advancing an animation by that whole gap makes it jump straight past its end, so a
/// frame is capped at a quarter second: long enough that a genuinely slow frame is followed at
/// its real pace, short enough that a resume cannot skip an animation's visible half.
pub const MAX_FRAME_DELTA_MS: u32 = 250;

/// What one frame did, so a host can decide whether to schedule another.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct FrameStep {
    /// Milliseconds advanced on this frame. Zero on the first frame (there is no previous
    /// timestamp to measure from) and when the timestamp did not move.
    pub delta_ms: u32,
    /// How many animations are still running after the step.
    pub active: usize,
    /// A monotonic counter of frames this clock has seen, starting at 1 for the first frame.
    pub frame_index: u64,
    /// How many named groups finished during this step and were removed.
    pub groups_completed: usize,
}

impl FrameStep {
    /// Whether any animation still needs frames.
    pub fn is_running(self) -> bool {
        self.active > 0
    }
}

/// A frame-driven clock: one [`AnimationDriver`] plus the named [`AnimationGroup`]s that ride on
/// it, advanced by the host's animation-frame callbacks rather than by wall-clock reads.
///
/// # Why one clock rather than a driver per control
///
/// A driver advanced by `advance()` reads `Instant::now()` per animation, so two controls that
/// were started on the same frame can land on different elapsed times depending on when their
/// own `advance` ran. The clock measures **one** delta per frame and hands that exact value to
/// every animation, which is what makes a coordinated transition (a sheet and its scrim, a row
/// and its disclosure arrow) move in step. It also gives a group one place to advance, which is
/// the consumer `AnimationGroup` documented
/// itself as lacking.
///
/// The first frame reports a zero delta: a clock cannot know how long the frame *before* the
/// first one took, and inventing a nominal 16 ms would make an animation's first tick depend on
/// a guess.
#[derive(Default)]
pub struct AnimationClock {
    driver: AnimationDriver,
    groups: Vec<AnimationGroup>,
    last_timestamp_ms: Option<u64>,
    frame_index: u64,
}

impl AnimationClock {
    /// Creates an empty clock with no animations and no groups.
    pub fn new() -> Self {
        Self::default()
    }

    /// Replaces the clock's driver, for a host that owns an already-populated one.
    pub fn with_driver(driver: AnimationDriver) -> Self {
        Self { driver, ..Self::default() }
    }

    /// The driver every animation in this clock lives in.
    pub fn driver(&self) -> &AnimationDriver {
        &self.driver
    }

    /// Mutable access to the driver, for adding or removing animations.
    pub fn driver_mut(&mut self) -> &mut AnimationDriver {
        &mut self.driver
    }

    /// Takes ownership of `group` and returns its index, which is stable until the group
    /// completes and is removed.
    pub fn add_group(&mut self, group: AnimationGroup) -> usize {
        self.groups.push(group);
        self.groups.len() - 1
    }

    /// The group at `index`, or `None` once it has completed and been removed.
    pub fn group(&self, index: usize) -> Option<&AnimationGroup> {
        self.groups.get(index)
    }

    /// How many groups are still running.
    pub fn group_count(&self) -> usize {
        self.groups.len()
    }

    /// How many frames this clock has advanced.
    pub fn frame_index(&self) -> u64 {
        self.frame_index
    }

    /// Whether anything the clock owns still needs frames.
    pub fn is_running(&self) -> bool {
        !self.driver.is_empty() || !self.groups.is_empty()
    }

    /// Advances by an explicit delta, for a host that measures frames itself.
    pub fn advance_delta(&mut self, delta_ms: u32) -> FrameStep {
        self.frame_index = self.frame_index.wrapping_add(1);
        let delta_ms = delta_ms.min(MAX_FRAME_DELTA_MS);
        let active = if delta_ms == 0 {
            self.driver.len()
        } else {
            self.driver.advance_by(Duration::from_millis(u64::from(delta_ms)))
        };
        // A group that has just become complete is removed, so `is_running` describes work left
        // rather than every group ever registered.
        let mut completed = 0usize;
        let driver = &mut self.driver;
        self.groups.retain_mut(|group| {
            group.advance(driver);
            let done = group.is_completed(driver);
            if done {
                completed += 1;
            }
            !done
        });
        FrameStep { delta_ms, active, frame_index: self.frame_index, groups_completed: completed }
    }

    /// Advances to a frame timestamp in milliseconds, measuring the delta from the previous
    /// frame. The first frame has no previous timestamp and therefore advances by zero.
    pub fn advance_frame(&mut self, timestamp_ms: u64) -> FrameStep {
        let delta_ms = match self.last_timestamp_ms {
            Some(previous) => {
                u32::try_from(timestamp_ms.saturating_sub(previous)).unwrap_or(u32::MAX)
            }
            None => 0,
        };
        self.last_timestamp_ms = Some(timestamp_ms);
        self.advance_delta(delta_ms)
    }
}

thread_local! {
    /// The process's default clock for hosts that have no reason to own one.
    ///
    /// Thread-local because an [`AnimationDriver`](crate::style::animation::AnimationDriver) holds
    /// `FnMut` callbacks that may capture UI-thread state; the clock therefore belongs to the
    /// thread that owns the controls, exactly as the widget registry does. A host that installs
    /// [`crate::event::EventLoop::drive_default_animation_clock`] reaches this instance from the
    /// loop thread, which is the same thread in every supported profile.
    static DEFAULT_CLOCK: core::cell::RefCell<Option<AnimationClock>> =
        const { core::cell::RefCell::new(None) };
}

/// Runs `f` against the thread's default clock, creating it on first use.
///
/// The closure gets the clock itself, so a control can add its animation without a handle to a
/// shared object. Nested calls panic on the `RefCell` borrow, matching the crate's other scoped
/// thread-local accessors: a callback invoked from inside the closure must not re-enter it.
pub fn with_default_animation_clock<R>(f: impl FnOnce(&mut AnimationClock) -> R) -> R {
    DEFAULT_CLOCK.with(|cell| {
        let mut slot = cell.borrow_mut();
        let clock = slot.get_or_insert_with(AnimationClock::new);
        f(clock)
    })
}

/// Drops the thread's default clock and every animation in it.
///
/// This is the teardown half of [`with_default_animation_clock`]: a host that replaces its scene
/// calls it so the previous scene's callbacks are not retained.
pub fn reset_default_animation_clock() {
    DEFAULT_CLOCK.with(|cell| {
        *cell.borrow_mut() = None;
    });
}

/// Advances the thread's default clock by an explicit frame delta.
///
/// This is the function an event loop's frame driver calls; see
/// [`crate::event::EventLoop::drive_default_animation_clock`]. It creates the clock if no
/// animation has been added yet, so installing the driver costs nothing until something animates.
pub fn advance_default_animation_clock(delta_ms: u32) -> FrameStep {
    with_default_animation_clock(|clock| clock.advance_delta(delta_ms))
}

#[cfg(test)]
mod property_driver_tests {
    use super::{MotionCurve, MotionSlot, PropertyDriver, SpringPreset, Transition};
    use crate::style::environment::{
        install_environment, uninstall_environment, DefaultEnvironment, EnvironmentProvider,
    };
    use crate::style::MotionPreference;
    use alloc::boxed::Box;

    /// The default is the resting end, and it is asserted rather than inferred.
    ///
    /// # The defect this pins
    ///
    /// BLUE24 §2.4 gate B: a control constructed at the **target** end of its own animation is
    /// born already finished. Three consequences, none of which reports an error -- it fades
    /// *out* on the first frame, `show_at`/`set_checked` have nothing left to animate, and
    /// `is_moving()` is `false`, so the frame loop never schedules the reveal.
    ///
    /// `PieMenu` shipped exactly that (`animation_progress: 1.0` at construction, and no reader
    /// of the field at all), while `button.rs` carried the lesson in prose. The crate's single
    /// default is the place to make the rule structural once, so the gate can check the type
    /// instead of every construction site.
    #[test]
    fn the_default_starts_at_the_resting_end() {
        let driver = PropertyDriver::default();
        assert_eq!(driver.value(), 0.0, "the first value must be the resting end");
        assert!(!driver.is_moving(), "and a fresh driver is not travelling anywhere");
    }

    /// `at` starts still: the target equals the value, so nothing moves until aimed.
    ///
    /// The distinction matters because `at` is how a control states a non-zero rest position
    /// (a menu that opens to a half-extended ring, a phase that starts mid-sweep). If `at`
    /// injected a target, every such control would drift toward an end it never asked for.
    #[test]
    fn at_starts_still_at_the_given_value() {
        let driver = PropertyDriver::at(0.25, MotionSlot::Slow);
        assert_eq!(driver.value(), 0.25);
        assert_eq!(driver.target(), 0.25, "at must not invent a destination");
        assert!(!driver.is_moving());
    }

    /// A driver crosses in many frames, arrives exactly, and then stops asking for frames.
    ///
    /// The same contract every control's `tick` advertises, asserted once at the type so the
    /// controls can rely on it rather than each re-deriving it: `true` while moving, then the
    /// **end value on the settle frame**, then `false` forever after.
    #[test]
    fn a_driver_settles_exactly_and_then_reports_no_more_frames() {
        let mut driver = PropertyDriver::at(0.0, MotionSlot::Normal);
        driver.set_target(1.0);
        assert!(driver.is_moving(), "a new target makes it moving at once, before any tick");

        let mut frames = 0;
        while driver.tick(16) {
            frames += 1;
            assert!(frames < 500, "the transition must terminate rather than tick forever");
        }
        assert!(frames > 1, "a transition must take more than one frame, or it is a cut: {frames}");
        assert_eq!(driver.value(), 1.0, "the settle frame lands exactly on the target");
        assert!(!driver.is_moving());
        assert!(!driver.tick(16), "and it stays settled");
    }

    /// Setting the target it is already at does not restart the movement.
    ///
    /// This is what lets a control re-assert its target every frame (which is how a
    /// `widget_state()`-derived target works) without the motion stuttering: `set_target`
    /// only stores the destination and never rewinds `current`, so a repeated aim at the same
    /// place is invisible.
    #[test]
    fn re_aiming_at_the_same_target_does_not_restart() {
        let mut driver = PropertyDriver::at(0.0, MotionSlot::Normal);
        driver.set_target(1.0);
        let _ = driver.tick(16);
        let partway = driver.value();
        assert!(partway > 0.0 && partway < 1.0, "the fixture must be mid-flight: {partway}");

        driver.set_target(1.0);
        assert_eq!(driver.value(), partway, "re-aiming at the same place must not rewind it");
        let _ = driver.tick(16);
        assert!(driver.value() > partway, "and the next step must continue forward");
    }

    /// `jump_to` lands and stops, so the next tick does not animate away from it.
    ///
    /// It sets both ends for exactly that reason: a driver whose position jumped but whose
    /// target stayed behind would immediately travel back to the stale aim, which is the
    /// opposite of what "place this value here, now" means.
    #[test]
    fn jump_to_lands_and_stops() {
        let mut driver = PropertyDriver::at(0.0, MotionSlot::Normal);
        driver.set_target(1.0);
        let _ = driver.tick(16);

        driver.jump_to(0.5);
        assert_eq!(driver.value(), 0.5);
        assert!(!driver.is_moving(), "a jump is not a movement");
        assert!(!driver.tick(16), "and nothing is left to animate");
        assert_eq!(driver.value(), 0.5, "so the value stays where it was placed");
    }

    /// `PropertyDriver` is the production consumer that puts `AnimationDriver` on the widget path.
    ///
    /// # Why this pins issue §9 item #5
    ///
    /// The item asked whether the animation engine reaches a real production path. It does: every
    /// animated control owns a `PropertyDriver`, whose `tick` builds and advances an
    /// [`AnimationDriver`] internally. This asserts that the two are genuinely joined \u2014 a
    /// `PropertyDriver` aimed at a new target reports the engine's eased value (strictly between the
    /// endpoints mid-flight, and the driver's `is_moving` is true only while the engine still has a
    /// frame to run) rather than a straight linear ramp this type computed itself.
    #[test]
    fn the_property_driver_drives_the_animation_engine() {
        // # Why a single `16 ms` step, and a comparison against the linear share
        //
        // The driver applies the crate's easing engine to the frame's share of the duration, so one
        // short step moves **more** than the raw `delta / duration` fraction would under `EaseOut`
        // (the default). A driver that recomputed a linear `current += delta/duration` ramp would land
        // exactly on that fraction. This is the join between `PropertyDriver` and the engine made
        // observable: the value cannot be a straight line.
        let tempo = MotionSlot::Normal;
        let duration = tempo.duration_ms().max(1);
        let delta = 16u32.min(duration / 4).max(1);

        let mut driver = PropertyDriver::at(0.0, tempo);
        driver.set_target(1.0);
        let moving = driver.tick(delta);
        let stepped = driver.value();

        assert!(moving, "a partial step must leave the driver owing more frames");
        assert!(
            stepped > 0.0 && stepped < 1.0,
            "one short step must land strictly inside the endpoints, got {stepped}"
        );
        let linear_share = delta as f32 / duration as f32;
        let eased_share = crate::style::motion_easing().apply(linear_share);
        assert!(
            (stepped - eased_share).abs() < 1e-4,
            "the driver must read the engine's easing of the frame share: \
             driver={stepped} eased={eased_share} linear={linear_share}"
        );
        // A non-linear easing must not coincide with the linear share; if the curve is Linear this
        // half is vacuously true, which is correct.
        if (eased_share - linear_share).abs() > 1e-4 {
            assert!(
                (stepped - linear_share).abs() > 1e-4,
                "a non-linear easing must not reproduce the linear frame share"
            );
        }

        // The engine still governs the endpoint: the driver settles exactly, and stops asking.
        let mut settling = PropertyDriver::at(0.0, tempo);
        settling.set_target(1.0);
        while settling.tick(16) {}
        assert_eq!(settling.value(), 1.0, "the engine's end value is reached exactly");
        assert!(!settling.is_moving());
    }

    /// The default curve is `Easing`, and that path produces exactly what `Transition` produces.
    ///
    /// This is the regression guard for the whole token extension: a driver built without a
    /// curve must not move by one bit differently from the transition it has always mirrored.
    #[test]
    fn the_default_curve_is_easing_and_matches_the_transition_path() {
        let _guard = crate::style::theme_test_guard();
        let previous = install_environment(Box::new(DefaultEnvironment));

        assert_eq!(PropertyDriver::default().curve(), MotionCurve::Easing);
        let tempo = MotionSlot::Normal;
        let mut driver = PropertyDriver::at(0.0, tempo);
        driver.set_target(1.0);
        let mut transition = Transition::with_tempo(tempo);
        transition.reset_to(0.0);

        for step in 0..6 {
            let driver_moving = driver.tick(16);
            let transition_moving = transition.tick(1.0, 16);
            assert_eq!(
                driver.value(),
                transition.progress(),
                "step {step}: the easing path must be the transition's path bit for bit"
            );
            assert_eq!(driver_moving, transition_moving, "step {step}: the frame demand agrees");
        }

        match previous {
            Some(previous) => {
                install_environment(previous);
            }
            None => {
                uninstall_environment();
            }
        }
    }

    /// Every spring preset reaches the target, and stops asking for frames when it does.
    #[test]
    fn every_spring_preset_settles_on_the_target() {
        let _guard = crate::style::theme_test_guard();
        let previous = install_environment(Box::new(DefaultEnvironment));

        for preset in [SpringPreset::Settle, SpringPreset::Snappy, SpringPreset::Bouncy] {
            let mut driver =
                PropertyDriver::with_curve(0.0, MotionSlot::Normal, MotionCurve::Spring(preset));
            driver.set_target(1.0);
            let mut frames = 0;
            while driver.tick(16) {
                frames += 1;
                assert!(frames < 1000, "{preset:?} must settle rather than tick forever");
            }
            assert_eq!(driver.value(), 1.0, "{preset:?} must land exactly on the target");
            assert!(!driver.is_moving(), "{preset:?} reports that it is at rest");
        }

        match previous {
            Some(previous) => {
                install_environment(previous);
            }
            None => {
                uninstall_environment();
            }
        }
    }

    /// `set_curve` after construction changes the shape of the remaining movement and keeps the
    /// value it had already reached.
    #[test]
    fn set_curve_after_construction_changes_the_path() {
        let _guard = crate::style::theme_test_guard();
        let previous = install_environment(Box::new(DefaultEnvironment));

        let mut driver = PropertyDriver::at(0.0, MotionSlot::Normal);
        driver.set_target(1.0);
        let _ = driver.tick(16);
        let partway = driver.value();
        assert!(partway > 0.0 && partway < 1.0, "the fixture must be mid-flight: {partway}");

        driver.set_curve(MotionCurve::Spring(SpringPreset::Snappy));
        assert_eq!(driver.curve(), MotionCurve::Spring(SpringPreset::Snappy));
        assert_eq!(driver.value(), partway, "changing the curve must not move the value");

        assert!(driver.tick(16), "the spring continues toward the same target");
        assert!(driver.value() > partway, "and moves forward: {}", driver.value());
        while driver.tick(16) {}
        assert_eq!(driver.value(), 1.0, "the spring settles on the stored target");

        match previous {
            Some(previous) => {
                install_environment(previous);
            }
            None => {
                uninstall_environment();
            }
        }
    }

    /// Reduced motion reaches the target on the first tick and asks for no more frames.
    #[test]
    fn reduced_motion_lands_on_the_target_in_one_frame() {
        struct Reduced;
        impl EnvironmentProvider for Reduced {
            fn motion_preference(&self) -> MotionPreference {
                MotionPreference::ReduceMotion
            }
        }

        let previous = install_environment(Box::new(Reduced));
        let mut driver = PropertyDriver::with_curve(
            0.0,
            MotionSlot::Normal,
            MotionCurve::Spring(SpringPreset::Bouncy),
        );
        driver.set_target(0.75);

        assert!(!driver.tick(16), "a reduced-motion tick completes the move");
        assert_eq!(driver.value(), 0.75, "the end state is reached, not skipped");
        assert!(!driver.is_moving());

        match previous {
            Some(previous) => {
                install_environment(previous);
            }
            None => {
                uninstall_environment();
            }
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::compat::MiniToString;

    /// A transition takes many frames to cross, not one.
    ///
    /// # The defect this pins
    ///
    /// [`Transition::tick`] rebuilds its [`AnimationDriver`] on every call, so the driver's notion of
    /// "how far through am I" is resettable — and the version that handed it the frame delta as its
    /// duration described a run that is 100% complete in one step. The easing was then sampled at
    /// `1.0` (where every curve returns 1.0 by construction, since a curve must map 1 to 1) and the
    /// value **arrived at its target on the first frame**. The theme's `EaseOut` could not soften
    /// anything because there was no progress left to shape, so every hover, press and toggle in the
    /// library was a cut — the one thing the transition exists to remove.
    ///
    /// The assertion is deliberately about the *shape of the sequence* rather than about any frame
    /// count: "more than one step, every step forward, never past the target". A curve is applied to
    /// each step, so individual steps are not evenly sized and a fixed expectation would be a
    /// statement about the curve rather than about the pacing.
    ///
    /// The settle frame's value is recorded **after** the loop rather than only inside it: the frame
    /// that reports `false` is the frame that lands on the target, so a caller that stops at the
    /// first `false` and never re-reads would see the animation end one step short. The final
    /// `assert_eq!` is what pins that — the previous shape of this type wrote the eased value and
    /// returned `false`, leaving the end state reachable only by a second, redundant `tick`.
    #[test]
    fn a_transition_takes_many_frames_and_never_overshoots() {
        for tempo in [TransitionTempo::Fast, TransitionTempo::Normal, TransitionTempo::Slow] {
            let mut transition = Transition::with_tempo(tempo);
            let mut seen = vec![transition.progress()];
            let mut steps = 0;
            // 200 frames at 16 ms is 3.2 s, past every tempo the theme ships.
            while transition.tick(1.0, 16) {
                steps += 1;
                seen.push(transition.progress());
                assert!(steps < 200, "{tempo:?} must settle, not run forever: {seen:?}");
                assert!(
                    seen[seen.len() - 2] < seen[seen.len() - 1],
                    "{tempo:?} must move forward on every frame: {seen:?}"
                );
                assert!(
                    seen[seen.len() - 1] <= 1.0,
                    "{tempo:?} must never pass its target: {seen:?}"
                );
            }
            // The frame that reported "done" landed on the target; its value is what it published.
            seen.push(transition.progress());
            assert!(steps > 1, "{tempo:?} must take more than one frame, not arrive at once");
            assert!(
                seen.iter().any(|p| *p > 0.0 && *p < 1.0),
                "{tempo:?} must be seen mid-flight: {seen:?}"
            );
            assert_eq!(
                seen.last().copied(),
                Some(1.0),
                "{tempo:?} must land exactly on its target: {seen:?}"
            );
            assert!(
                seen.windows(2).all(|pair| pair[0] <= pair[1]),
                "{tempo:?} must never move backwards: {seen:?}"
            );
        }
    }

    /// A step at least as long as the transition finishes it in that frame.
    ///
    /// The other side of the same rule: a host that hands over a delta longer than the whole tempo —
    /// a stalled frame, a breakpoint, a first frame after a resize — must see the transition
    /// complete, not advance a fraction of it and then need a second frame to finish. This is what
    /// the `step` clamp to `1.0` is for.
    #[test]
    fn a_frame_longer_than_the_transition_finishes_it() {
        for tempo in [TransitionTempo::Fast, TransitionTempo::Normal, TransitionTempo::Slow] {
            let mut transition = Transition::with_tempo(tempo);
            assert!(
                !transition.tick(1.0, tempo.duration_ms() * 4),
                "{tempo:?} must be done after a frame longer than its own duration"
            );
            assert_eq!(transition.progress(), 1.0, "{tempo:?} must land on the target exactly");
        }
    }

    /// A transition already at its target owes nothing, whatever the tempo.
    #[test]
    fn a_transition_at_its_target_owes_no_frames() {
        let mut transition = Transition::default();
        assert!(!transition.tick(0.0, 16), "0.0 is where it starts, so it is already there");
        transition.reset_to(1.0);
        assert!(!transition.tick(1.0, 16), "and 1.0 needs no approach");
        assert_eq!(transition.progress(), 1.0, "with no drift from the repeated calls");
    }

    #[test]
    fn test_easing_functions() {
        assert_eq!(EasingFunction::Linear.apply(0.5), 0.5);
        assert!(EasingFunction::EaseIn.apply(0.5) < 0.5);
        assert!(EasingFunction::EaseOut.apply(0.5) > 0.5);
    }
    #[test]
    fn test_animation_config() {
        let config = AnimationConfig::new(Duration::from_millis(500))
            .with_delay(Duration::from_millis(100))
            .with_easing(EasingFunction::EaseInOut)
            .with_iterations(3);
        assert_eq!(config.duration, Duration::from_millis(500));
        assert_eq!(config.delay, Duration::from_millis(100));
        assert_eq!(config.iteration_count, 3);
    }
    #[test]
    fn test_color_animation() {
        let config = AnimationConfig::new(Duration::from_millis(100));
        let mut animation = ColorAnimation::new(config, Color::RED, Color::BLUE);
        animation.start();
        let color = animation.current_color();
        // Animation just started: should be RED or transitioning (r≥127, b≤127)
        assert!(color.r >= 127);
    }
    #[test]
    fn test_float_animation() {
        let config = AnimationConfig::new(Duration::from_millis(100));
        let mut animation = FloatAnimation::new(config, 0.0, 100.0);
        animation.start();
        let value = animation.current_value();
        assert!((0.0..=100.0).contains(&value));
    }
    #[test]
    fn animation_driver_add_and_advance() {
        let mut driver = AnimationDriver::new();
        let config = AnimationConfig::new(Duration::from_millis(100));
        let id = driver.add(config, |_| {});
        assert!(!driver.is_empty());
        driver.advance();
        driver.remove(id);
        assert!(driver.is_empty());
    }
    #[test]
    fn animation_driver_add_float() {
        let mut driver = AnimationDriver::new();
        let config = AnimationConfig::new(Duration::from_millis(100));
        let _id = driver.add_float(config, 10.0, 20.0, |_| {});
        driver.advance();
    }
    #[test]
    fn animation_driver_add_color() {
        let mut driver = AnimationDriver::new();
        let config = AnimationConfig::new(Duration::from_millis(100));
        let _id = driver.add_color(config, Color::RED, Color::BLUE, |_| {});
        driver.advance();
    }
    #[test]
    fn animation_driver_clear() {
        let mut driver = AnimationDriver::new();
        let c1 = AnimationConfig::new(Duration::from_millis(100));
        let c2 = AnimationConfig::new(Duration::from_millis(100));
        driver.add(c1, |_| {});
        driver.add(c2, |_| {});
        assert_eq!(driver.len(), 2);
        driver.clear();
        assert_eq!(driver.len(), 0);
    }
    #[test]
    fn animation_driver_is_empty() {
        let mut driver = AnimationDriver::new();
        assert!(driver.is_empty());
        let config = AnimationConfig::new(Duration::from_millis(100));
        driver.add(config, |_| {});
        assert!(!driver.is_empty());
        driver.clear();
        assert!(driver.is_empty());
    }
    #[test]
    fn animation_driver_default() {
        let driver: AnimationDriver = Default::default();
        assert!(driver.is_empty());
    }
    #[test]
    fn animation_driver_animate_named_property() {
        let mut driver = AnimationDriver::new();
        let id = driver.animate(
            "opacity",
            0.0,
            1.0,
            Duration::from_millis(100),
            EasingFunction::Linear,
            |_, _| {},
        );
        assert!(!driver.is_empty());
        // Verify that PropertyAnimation was wired up
        let prop_anim = driver.get_property_animation(id);
        assert!(prop_anim.is_some());
        let pa = prop_anim.unwrap();
        assert_eq!(pa.property, "opacity");
        assert!((pa.from - 0.0).abs() < 1e-6);
        assert!((pa.to - 1.0).abs() < 1e-6);
        driver.advance();
    }

    /// Property metadata must not outlive the animation it describes.
    ///
    /// `property_animations` was insert-only: every `animate()` call left a `PropertyAnimation`
    /// behind after completion and after `clear()`, so a host that animates per interaction leaked
    /// one entry (with a `String`) per call and `get_property_animation` kept returning stale data.
    #[test]
    fn property_metadata_is_dropped_with_the_animation() {
        let mut driver = AnimationDriver::new();
        let id = driver.animate(
            "opacity",
            0.0,
            1.0,
            Duration::from_millis(10),
            EasingFunction::Linear,
            |_, _| {},
        );
        assert!(driver.get_property_animation(id).is_some());

        driver.advance_by(Duration::from_millis(50));
        assert!(driver.is_empty(), "the run is complete");
        assert!(
            driver.get_property_animation(id).is_none(),
            "the metadata must be removed with the animation"
        );

        // `clear` must drop the metadata too.
        let id = driver.animate(
            "x",
            0.0,
            10.0,
            Duration::from_secs(10),
            EasingFunction::Linear,
            |_, _| {},
        );
        driver.clear();
        assert!(driver.get_property_animation(id).is_none());
    }

    #[test]
    fn animation_driver_animate_linear() {
        let mut driver = AnimationDriver::new();
        let _id = driver.animate_linear("x", 10.0, 100.0, Duration::from_millis(100), |_, _| {});
        driver.advance();
    }
    #[test]
    fn animation_driver_animate_ease() {
        let mut driver = AnimationDriver::new();
        let _id = driver.animate_ease("width", 50.0, 200.0, Duration::from_millis(100), |_, _| {});
        driver.advance();
    }
    #[test]
    fn property_animation_struct_accessors() {
        let pa = PropertyAnimation {
            id: 42,
            property: "x".to_string(),
            from: 0.0,
            to: 100.0,
            current: 50.0,
        };
        assert_eq!(pa.id, 42);
        assert_eq!(pa.property, "x");
        assert!((pa.current - 50.0).abs() < 1e-6);
    }
    #[test]
    fn animation_driver_get_progress() {
        let mut driver = AnimationDriver::new();
        let id = driver.animate_linear("y", 0.0, 100.0, Duration::from_millis(100), move |_, _| {});
        // Initially should return Some(0.0) since animation just started
        let prog = driver.get_progress(id);
        assert!(prog.is_some());
    }
    #[test]
    fn parallel_animation_group() {
        let mut driver = AnimationDriver::new();
        let mut group = ParallelAnimation::new();
        let id1 = driver.animate_linear("a", 0.0, 1.0, Duration::from_millis(100), |_, _| {});
        let id2 = driver.animate_linear("b", 0.0, 1.0, Duration::from_millis(100), |_, _| {});
        group.add(id1);
        group.add(id2);
        assert_eq!(group.len(), 2);
        assert!(!group.is_completed(&driver));
        driver.advance();
    }
    #[test]
    fn sequential_animation_group() {
        let mut driver = AnimationDriver::new();
        let mut seq = SequentialAnimation::new();
        seq.add(AnimationConfig::new(Duration::from_millis(10)));
        seq.add(AnimationConfig::new(Duration::from_millis(10)));
        // Start the sequence
        let running = seq.advance(&mut driver, |_, _| {});
        assert!(running);
        driver.advance();
    }

    /// All easing functions should clamp to 0.0 for t < 0 and 1.0 for t > 1.
    #[test]
    fn test_easing_functions_clamp_range() {
        let variants = [
            EasingFunction::Linear,
            EasingFunction::EaseIn,
            EasingFunction::EaseOut,
            EasingFunction::EaseInOut,
            EasingFunction::BounceIn,
            EasingFunction::BounceOut,
            EasingFunction::ElasticIn,
            EasingFunction::ElasticOut,
            EasingFunction::BackIn,
            EasingFunction::BackOut,
        ];
        for variant in &variants {
            let below = variant.apply(-0.5);
            assert!(
                (below - 0.0).abs() < 1e-6,
                "{:?}.apply(-0.5) expected 0.0, got {}",
                variant,
                below
            );
            let above = variant.apply(1.5);
            assert!(
                (above - 1.0).abs() < 1e-6,
                "{:?}.apply(1.5) expected 1.0, got {}",
                variant,
                above
            );
        }
    }

    #[test]
    fn test_animation_driver_empty_advance() {
        let mut driver = AnimationDriver::new();
        // Advance on an empty driver should return 0 (no active animations).
        assert_eq!(driver.advance(), 0);
    }

    /// A cursor blinks on the documented half-period and only while it is running.
    ///
    /// The defect this pins is not arithmetic — it is that the feature did not exist while three
    /// doc comments said it did. The assertions are therefore about observable state transitions:
    /// a stopped cursor is visible and owes no frames, a started one flips exactly at the
    /// half-period, and a delayed frame resumes at the right phase instead of skipping a flip.
    #[test]
    fn a_cursor_blinks_on_its_half_period_and_stops_when_told() {
        let mut blink = CursorBlink::new();

        // Blurred: visible, and it must not ask the host for frames.
        assert!(blink.is_visible());
        assert!(!blink.is_running());
        assert!(!blink.tick(10_000), "a stopped cursor owes no frame, however large the delta");
        assert!(blink.is_visible(), "a stopped cursor stays visible");

        // Focused: it flips on the boundary and holds the phase in between.
        blink.start();
        assert!(blink.is_visible());
        assert!(blink.tick(CURSOR_BLINK_HALF_PERIOD_MS - 1), "still running");
        assert!(blink.is_visible(), "one millisecond short of the boundary is not yet a flip");
        assert!(blink.tick(1), "still running");
        assert!(!blink.is_visible(), "the boundary is where it flips");
        assert!(blink.tick(CURSOR_BLINK_HALF_PERIOD_MS), "still running");
        assert!(blink.is_visible(), "and it flips back");

        // A long frame must consume the elapsed time half-period by half-period rather than
        // snapping to one flip, or a stalled host would come back out of phase.
        let mut delayed = CursorBlink::new();
        delayed.start();
        // Visible at 0. One half-period flips it to hidden...
        delayed.tick(CURSOR_BLINK_HALF_PERIOD_MS);
        assert!(!delayed.is_visible());
        // ...and three further half-periods in a single frame flip it three more times, ending
        // visible. Snapping to a single flip would leave it hidden, so this distinguishes the two.
        delayed.tick(CURSOR_BLINK_HALF_PERIOD_MS * 3);
        assert!(delayed.is_visible(), "three flips from hidden lands on visible");

        // Blurring returns it to the steady, visible state.
        blink.stop();
        assert!(blink.is_visible());
        assert!(!blink.tick(CURSOR_BLINK_HALF_PERIOD_MS * 10), "a stopped cursor owes no frame");
        assert!(blink.is_visible());
    }

    // ── Transition (the shared state-transition primitive) ──

    #[test]
    fn a_transition_starts_at_rest_heading_nowhere() {
        // Starting at the interactive end would make every control fade *out* on its first
        // frame, and would make a snapshot taken without ticking show a moved control.
        let transition = Transition::new();
        assert_eq!(transition.progress(), 0.0);
    }

    #[test]
    fn a_transition_lands_exactly_on_its_target_and_then_settles() {
        // The whole point of the `bool` return: a host must be able to stop scheduling frames.
        // A transition that approached its target asymptotically would return `true` forever,
        // which is precisely the defect `FloatingLabel` had before it used this type.
        let mut transition = Transition::new();
        assert!(transition.tick(1.0, 30), "one short frame is not enough to arrive");
        assert!(!transition.tick(1.0, 10_000), "a long frame must finish it");
        assert_eq!(transition.progress(), 1.0, "and must land exactly on the target");
        assert!(!transition.tick(1.0, 16), "a settled transition owes no frame");
    }

    #[test]
    fn a_transition_re_aims_rather_than_restarting() {
        // A press arriving mid-hover must continue from where the value *is*, which is what
        // makes a quick press-and-release read as one movement instead of two.
        let mut transition = Transition::new();
        transition.tick(1.0, 50);
        let partway = transition.progress();
        assert!(partway > 0.0 && partway < 1.0, "expected mid-flight, got {partway}");
        transition.tick(0.0, 16);
        assert!(
            transition.progress() < partway,
            "retracting must continue from {partway}, not jump"
        );
    }

    #[test]
    fn a_transition_never_leaves_the_unit_range() {
        // Targets come from caller state, so the clamp is the type's own guarantee rather
        // than something each caller must remember.
        let mut transition = Transition::new();
        transition.tick(5.0, 10_000);
        assert!(transition.progress() <= 1.0);
        transition.tick(-5.0, 10_000);
        assert!(transition.progress() >= 0.0);
    }

    #[test]
    fn resetting_a_transition_snaps_rather_than_fading() {
        let mut transition = Transition::new();
        transition.reset_to(1.0);
        assert_eq!(transition.progress(), 1.0);
        assert!(!transition.tick(1.0, 16), "an already-at-target transition owes no frame");
        // Out-of-range input is clamped, not stored.
        transition.reset_to(9.0);
        assert_eq!(transition.progress(), 1.0);
    }

    #[test]
    fn each_tempo_names_its_own_motion_token() {
        // The three tempos must be distinct facts, or the enum would be decoration.
        // Reading the values back through the crate's own defaults keeps this test
        // compiling in a profile with no theme module.
        let fast = TransitionTempo::Fast.duration_ms();
        let normal = TransitionTempo::Normal.duration_ms();
        let slow = TransitionTempo::Slow.duration_ms();
        assert!(fast < normal, "a pointer reaction is quicker than a state change");
        assert!(normal < slow, "a state change is quicker than a large movement");
    }

    /// An animation that completes on a frame still reports that frame's final value.
    ///
    /// The driver used to snapshot progress from animations that were *still* running once the
    /// advance had finished. A one-shot animation clears `is_running` the moment it reaches its
    /// end, so the very frame that carried the value `to` was filtered out of the snapshot: the
    /// tick callback never fired for it, and a caller watching a transition saw it stop one step
    /// short of its target forever. `add_float` is used because it is the API a control reaches
    /// for, and it makes the arithmetic visible — the callback receives `from + (to - from) * p`,
    /// so a missing final callback is an observable value rather than an absent event.
    #[test]
    fn a_completing_animation_still_delivers_its_final_value() {
        use core::cell::RefCell;
        use std::rc::Rc;

        let seen = Rc::new(RefCell::new(Vec::<f32>::new()));
        let sink = Rc::clone(&seen);

        let mut driver = AnimationDriver::new();
        driver.add_float(
            AnimationConfig::new(Duration::from_millis(200)),
            0.0,
            1.0,
            move |value| sink.borrow_mut().push(value),
        );

        // One advance that overshoots the whole duration: the animation begins and ends here.
        assert_eq!(
            driver.advance_by(Duration::from_millis(1000)),
            0,
            "it finished, so nothing runs"
        );
        assert_eq!(
            seen.borrow().last().copied(),
            Some(1.0),
            "the completing frame must deliver the end value, not the last running value"
        );

        // And the same through the clock-driven path, which carried the identical defect.
        let seen_clock = Rc::new(RefCell::new(Vec::<f32>::new()));
        let sink_clock = Rc::clone(&seen_clock);
        let mut clock_driver = AnimationDriver::new();
        clock_driver.add_float(
            // Zero duration: the animation is already past its end on the first `advance`.
            AnimationConfig::new(Duration::ZERO),
            0.0,
            4.0,
            move |value| sink_clock.borrow_mut().push(value),
        );
        std::thread::sleep(Duration::from_millis(5));
        clock_driver.advance();
        assert_eq!(
            seen_clock.borrow().last().copied(),
            Some(4.0),
            "the clock-driven advance must deliver the end value on the completing frame too"
        );
    }

    #[test]
    fn test_parallel_empty_is_completed() {
        let driver = AnimationDriver::new();
        let group = ParallelAnimation::new();
        // An empty parallel group should be considered completed.
        assert!(group.is_completed(&driver));
    }

    #[test]
    fn test_sequential_empty_stops_immediately() {
        let mut driver = AnimationDriver::new();
        let mut seq = SequentialAnimation::new();
        // An empty sequence should return false from advance() immediately.
        assert!(!seq.advance(&mut driver, |_, _| {}));
        assert!(!seq.advance(&mut driver, |_, _| {}));
    }
    /// A finite multi-iteration animation reports the within-iteration progress, not `1.0`
    /// for every iteration after the first.
    ///
    /// This pins the S-21 defect through the public, delta-driven API so the result is
    /// reproducible without a wall clock.
    #[test]
    fn multi_iteration_progress_is_within_the_current_iteration() {
        use core::time::Duration;
        let mut animation =
            Animation::new(AnimationConfig::new(Duration::from_millis(100)).with_iterations(3));
        animation.start();
        animation.advance_by(Duration::from_millis(150));
        assert!(!animation.is_completed(), "1.5 of 3 iterations is still running");
        assert_eq!(
            animation.progress(),
            0.5,
            "the second iteration reads 0.5, not the stuck end-point 1.0"
        );
    }

    /// A completed animation holds the end value its direction points at, not a direction-blind
    /// `1.0`.
    #[test]
    fn a_completed_animation_reads_its_directional_end_value() {
        use core::time::Duration;
        let complete = |direction: AnimationDirection, iterations: u32| -> f32 {
            let mut animation = Animation::new(
                AnimationConfig::new(Duration::from_millis(1))
                    .with_direction(direction)
                    .with_iterations(iterations),
            );
            animation.start();
            animation.advance_by(Duration::from_millis(10_000));
            assert!(animation.is_completed(), "the animation has run every iteration");
            animation.progress()
        };

        assert_eq!(complete(AnimationDirection::Normal, 1), 1.0);
        assert_eq!(complete(AnimationDirection::Reverse, 1), 0.0, "Reverse runs 1.0 to 0.0");
        assert_eq!(complete(AnimationDirection::Alternate, 1), 1.0);
        assert_eq!(complete(AnimationDirection::Alternate, 2), 0.0, "odd last iteration runs back");
        assert_eq!(complete(AnimationDirection::Alternate, 3), 1.0);
        assert_eq!(complete(AnimationDirection::AlternateReverse, 1), 0.0);
        assert_eq!(complete(AnimationDirection::AlternateReverse, 2), 1.0);
        assert_eq!(complete(AnimationDirection::AlternateReverse, 3), 0.0);
    }

    /// A group composer must use lifecycle completion, not `progress >= 1.0`, so a reverse child
    /// is not mistaken for done at its start and a multi-iteration child is waited on.
    #[test]
    fn a_reverse_child_is_not_completed_by_its_starting_progress() {
        use core::time::Duration;
        let mut driver = AnimationDriver::new();
        let mut group = ParallelAnimation::new();
        let id = driver.add(
            AnimationConfig::new(Duration::from_millis(100))
                .with_direction(AnimationDirection::Reverse),
            |_| {},
        );
        group.add(id);
        assert!(!group.is_completed(&driver), "a reverse child starts at 1.0 but is not finished");
    }

    /// A multi-iteration child keeps its group alive until every iteration has run.
    #[test]
    fn a_parallel_group_waits_for_multi_iteration_children() {
        use core::time::Duration;
        let mut driver = AnimationDriver::new();
        let mut group = ParallelAnimation::new();
        let id =
            driver.add(AnimationConfig::new(Duration::from_millis(100)).with_iterations(3), |_| {});
        group.add(id);

        driver.advance_by(Duration::from_millis(150));
        assert!(!group.is_completed(&driver), "a 3-iteration child at 1.5 iterations is not done");

        driver.advance_by(Duration::from_millis(10_000));
        assert!(group.is_completed(&driver), "after all iterations the child is done");
    }

    /// A finite animation that has fully elapsed reports completion and full progress.
    ///
    /// The end-to-end check of the contract above, through the public API.
    #[test]
    fn a_finished_finite_animation_reads_full_progress() {
        use core::time::Duration;
        let mut animation = Animation::new(AnimationConfig {
            duration: Duration::from_millis(1),
            iteration_count: 1,
            infinite: false,
            ..AnimationConfig::default()
        });
        animation.start();
        std::thread::sleep(Duration::from_millis(5));
        animation.update();
        assert!(animation.is_completed(), "a one-iteration animation must complete");
        assert_eq!(
            animation.progress(),
            1.0,
            "a completed finite animation must read 1.0, not wrap back to 0.0"
        );
    }

    /// `fill_mode` decides what the value is **during the delay**.
    ///
    /// The enum, the config field and `with_fill_mode` all existed, and no animator read any of
    /// them — so `with_fill_mode(AnimationFillMode::Backwards)` was a builder whose name stated a
    /// behaviour the code did not have (principle #37). It is observable exactly here: a forward
    /// run's first value is progress `0.0`, which the old code happened to return anyway, but a
    /// `Reverse` run's first value is `1.0`, and filling backwards must hold that rather than
    /// snapping to zero.
    #[test]
    fn fill_mode_decides_the_value_during_the_delay() {
        use core::time::Duration;
        let during_delay = |fill: AnimationFillMode, direction: AnimationDirection| -> f32 {
            let mut animation = Animation::new(AnimationConfig {
                duration: Duration::from_millis(10),
                delay: Duration::from_secs(30),
                direction,
                fill_mode: fill,
                ..AnimationConfig::default()
            });
            animation.start();
            // Well inside the 30 s delay, so the answer comes from the delay branch alone.
            animation.progress()
        };

        // A forward run starts at 0.0 whether or not it fills backwards.
        assert_eq!(during_delay(AnimationFillMode::None, AnimationDirection::Normal), 0.0);
        assert_eq!(during_delay(AnimationFillMode::Forwards, AnimationDirection::Normal), 0.0);
        assert_eq!(during_delay(AnimationFillMode::Backwards, AnimationDirection::Normal), 0.0);

        // A reversed run's first value is 1.0, and only a backwards fill holds it there.
        assert_eq!(
            during_delay(AnimationFillMode::Backwards, AnimationDirection::Reverse),
            1.0,
            "a backwards fill holds the run's first value during the delay"
        );
        assert_eq!(
            during_delay(AnimationFillMode::Both, AnimationDirection::Reverse),
            1.0,
            "`Both` includes the backwards half"
        );
        assert_eq!(
            during_delay(AnimationFillMode::None, AnimationDirection::Reverse),
            0.0,
            "without a backwards fill nothing is applied before the animation starts"
        );
        assert_eq!(
            during_delay(AnimationFillMode::Forwards, AnimationDirection::Reverse),
            0.0,
            "`Forwards` says nothing about the delay, so it must not fill backwards"
        );

        // The two predicates are the single statement of each half.
        assert!(AnimationFillMode::Both.fills_backwards());
        assert!(AnimationFillMode::Both.fills_forwards());
        assert!(!AnimationFillMode::Forwards.fills_backwards());
        assert!(!AnimationFillMode::Backwards.fills_forwards());
        assert!(!AnimationFillMode::None.fills_backwards());
        assert!(!AnimationFillMode::None.fills_forwards());
    }
}

#[cfg(test)]
mod cubic_bezier_tests {
    use super::*;

    /// The endpoints are exact: every curve starts at 0 and ends at 1, which is what makes a
    /// transition arrive at its declared target instead of near it.
    #[test]
    fn the_curve_hits_both_endpoints() {
        let curve = EasingFunction::cubic_bezier(0.25, 0.1, 0.25, 1.0);
        assert_eq!(curve.apply(0.0), 0.0);
        assert_eq!(curve.apply(1.0), 1.0);
        assert_eq!(curve.apply(-3.0), 0.0, "input is clamped, not extrapolated");
        assert_eq!(curve.apply(4.0), 1.0);
    }

    /// `cubic-bezier(0.25, 0.1, 0.25, 1)` is CSS's `ease`, so it must reproduce the shape the
    /// named curve describes: ahead of linear at the midpoint.
    #[test]
    fn css_ease_matches_the_named_shape() {
        let curve = EasingFunction::cubic_bezier(0.25, 0.1, 0.25, 1.0);
        let midway = curve.apply(0.5);
        assert!((0.7..0.85).contains(&midway), "ease leads linear at 0.5, got {midway}");
        assert!(curve.apply(0.25) < curve.apply(0.5));
        assert!(curve.apply(0.5) < curve.apply(0.75));
    }

    /// The parser accepts the stylesheet spelling and refuses everything else rather than
    /// guessing — an unparsed curve must be a caller's decision, not a silent linear fallback.
    #[test]
    fn the_css_spelling_parses_and_other_text_does_not() {
        assert_eq!(
            EasingFunction::parse_cubic_bezier(" cubic-bezier( 0.42, 0.0, 0.58, 1.0 ) "),
            Some(EasingFunction::cubic_bezier(0.42, 0.0, 0.58, 1.0))
        );
        assert_eq!(EasingFunction::parse_cubic_bezier("ease-in"), None);
        assert_eq!(EasingFunction::parse_cubic_bezier("cubic-bezier(0.1, 0.2, 0.3)"), None);
        assert_eq!(EasingFunction::parse_cubic_bezier("cubic-bezier(0.1, 0.2, nope, 1)"), None);
    }

    /// X control points are clamped into the solvable range; Y is not, because overshoot is
    /// expressed by a Y outside `0..=1`.
    #[test]
    fn only_the_x_coordinates_are_clamped() {
        // X control points outside `0..=1` would make the curve non-monotonic in time, so the
        // constructor clamps them. Y is unbounded because overshoot is how a spring-like curve
        // is written.
        let curve = EasingFunction::cubic_bezier(-1.0, 3.0, 2.0, 3.0);
        assert_eq!(curve, EasingFunction::CubicBezier { x1: 0.0, y1: 3.0, x2: 1.0, y2: 3.0 });
        assert!(curve.apply(0.5) > 1.0, "an overshooting Y reaches above the target");
    }
}

#[cfg(test)]
mod animation_clock_tests {
    use super::*;
    use crate::compat::Rc;
    use crate::style::animation_group::AnimationGroup;
    use core::cell::RefCell;
    use core::time::Duration;

    /// The clock measures one delta per timestamp, and the first frame has no delta to measure.
    #[test]
    fn the_first_frame_is_a_zero_delta_and_later_frames_measure_the_gap() {
        let mut clock = AnimationClock::new();
        assert_eq!(clock.advance_frame(1_000).delta_ms, 0, "no previous frame to measure from");
        let second = clock.advance_frame(1_016);
        assert_eq!(second.delta_ms, 16);
        assert_eq!(second.frame_index, 2);
        // A timestamp that did not move (or went backwards) cannot advance time.
        assert_eq!(clock.advance_frame(1_016).delta_ms, 0);
        assert_eq!(clock.advance_frame(900).delta_ms, 0);
    }

    /// A resume after a long stall is capped, so an animation cannot skip its visible half.
    #[test]
    fn a_stalled_frame_is_capped() {
        let mut clock = AnimationClock::new();
        clock.advance_frame(0);
        assert_eq!(clock.advance_frame(60_000).delta_ms, MAX_FRAME_DELTA_MS);
    }

    /// The clock advances its driver by exactly the measured delta, so a host's frame pacing
    /// (not wall-clock time) decides how far an animation has travelled.
    #[test]
    fn the_driver_advances_by_the_measured_delta() {
        let mut clock = AnimationClock::new();
        let progress = Rc::new(RefCell::new(0.0f32));
        let seen = Rc::clone(&progress);
        clock.driver_mut().add(AnimationConfig::new(Duration::from_millis(200)), move |value| {
            *seen.borrow_mut() = value
        });
        clock.advance_frame(0);
        // Two 50 ms frames carry a 200 ms linear animation a quarter of the way in *time* but a
        // half in progress only after the second's 100 ms total: assert the total, not a guess.
        clock.advance_frame(50);
        clock.advance_frame(100);
        let reached = *progress.borrow();
        assert!(
            (reached - 0.5).abs() < 0.01,
            "100 of 200 ms should be half the progress, got {reached}"
        );
        let finished = clock.advance_frame(300);
        assert_eq!(finished.active, 0, "the animation completed and was removed");
        assert!(!clock.is_running());
    }

    /// A named group is a consumer of the clock: its sequential half runs and the group is
    /// removed once complete, which is the wiring the group documented itself as lacking.
    #[test]
    fn a_group_runs_to_completion_and_leaves_the_clock() {
        let mut clock = AnimationClock::new();
        let mut group = AnimationGroup::new("sequential");
        group.add_sequential(AnimationConfig::new(Duration::from_millis(50)));
        group.add_sequential(AnimationConfig::new(Duration::from_millis(50)));
        clock.add_group(group);
        assert_eq!(clock.group_count(), 1);

        let mut completed = 0usize;
        let mut now = 0u64;
        for _ in 0..10 {
            now += 16;
            completed += clock.advance_frame(now).groups_completed;
        }
        assert_eq!(completed, 1, "the group must be reported complete exactly once");
        assert_eq!(clock.group_count(), 0, "and removed rather than retained");
        assert!(!clock.is_running());
    }

    /// The thread-local default clock is the instance a loop frame driver reaches.
    #[test]
    fn the_default_clock_is_thread_local_and_advances_by_delta() {
        reset_default_animation_clock();
        with_default_animation_clock(|clock| {
            clock.driver_mut().add(AnimationConfig::new(Duration::from_millis(40)), |_| {});
        });
        let step = advance_default_animation_clock(20);
        assert_eq!(step.delta_ms, 20);
        assert_eq!(step.active, 1);
        assert!(with_default_animation_clock(|clock| clock.is_running()));
        reset_default_animation_clock();
        assert!(!with_default_animation_clock(|clock| clock.is_running()));
    }
}