feat(animation): let a spring be given a duration, and report when it settles

A spring's duration used to be an emergent consequence of `damping`,
`stiffness` and `mass`. An author who wanted "this spring, finishing in
0.8s" had to guess at three coupled numbers, and nothing exposed the instant
a given spring actually comes to rest — the one figure you need to time the
rest of a scene against it.

`SpringConfig` now takes an optional `duration` and `rest_threshold`. When
`duration` is set, time is rescaled linearly so the settle point lands
exactly there. The spring's shape is preserved by construction — the solver
is called with a scaled `t`, not with altered physics — and a test asserts
it: sampled at matching fractions of each one's own settle time, the natural
and pinned curves agree to 1e-9, with identical oscillation counts and
overshoot amplitudes. Without that test nothing would distinguish a real
remap from a crude shortening that flattens the spring.

The settle search handles the regimes that break naive implementations: an
overdamped spring never reaches its target exactly, which is what
`rest_threshold` is for; a very lightly damped one can take arbitrarily
long, so the search is bounded and the bound is tested rather than left to
spin.

`rustmotion info` now reports each spring's rest time, so a scene can be
timed against it instead of by trial and error, and `validate` rejects a
non-positive `duration` or a negative `rest_threshold` alongside the checks
PR #158 already added.

Author: LeadcodeDev

crates/rustmotion-cli/src/commands/info.rs

@@ -1,6 +1,9 @@
+use rustmotion::components::{ChildComponent, Component};
+use rustmotion::engine::animator::spring_rest_time;
+use rustmotion::engine::render::deserialize_children;
 use rustmotion::error::Result;
 use rustmotion::loader::load_input;
-use rustmotion::schema;
+use rustmotion::schema::{self, AnimationEffect, ResolvedScenario, SpringConfig};
 use std::path::PathBuf;
 
 pub fn cmd_info(input: &PathBuf) -> Result<()> {
@@ -55,5 +58,195 @@ pub fn cmd_info(input: &PathBuf) -> Result<()> {
         }
     }
 
+    let springs = collect_springs(&scenario);
+    if !springs.is_empty() {
+        println!("Springs:");
+        for report in &springs {
+            println!("  {}", report.describe());
+        }
+    }
+
     Ok(())
 }
+
+/// Where a `SpringConfig` was found, and the settle time computed for it —
+/// the "measure du repos" issue #167 lot E asks `rustmotion info` to
+/// surface, so an author can size the enclosing animation's `duration`
+/// around a spring instead of guessing (see `SpringConfig::duration`'s doc
+/// comment for why the two are not automatically kept in sync).
+#[derive(Debug)]
+struct SpringReport {
+    label: String,
+    rest_seconds: f64,
+    duration_was_set: bool,
+}
+
+impl SpringReport {
+    fn describe(&self) -> String {
+        if self.duration_was_set {
+            format!(
+                "{}: settles at {:.3}s (spring.duration set explicitly)",
+                self.label, self.rest_seconds
+            )
+        } else {
+            format!(
+                "{}: settles at {:.3}s (natural — no spring.duration set; \
+                 pin the enclosing animation's duration to at least this to \
+                 avoid cutting the spring short)",
+                self.label, self.rest_seconds
+            )
+        }
+    }
+}
+
+fn collect_springs(scenario: &ResolvedScenario) -> Vec<SpringReport> {
+    let mut out = Vec::new();
+    for (vi, view) in scenario.views.iter().enumerate() {
+        for (si, scene) in view.scenes.iter().enumerate() {
+            let children = deserialize_children(scene);
+            let path = format!("view {} / scene {}", vi + 1, si + 1);
+            collect_springs_in_children(&children, &path, &mut out);
+        }
+    }
+    out
+}
+
+fn collect_springs_in_children(
+    children: &[ChildComponent],
+    path: &str,
+    out: &mut Vec<SpringReport>,
+) {
+    for (i, child) in children.iter().enumerate() {
+        let p = format!("{path} / layer {}", i + 1);
+        if let Some(anim) = child.component.as_animatable() {
+            for effect in anim.animation_effects() {
+                if let Some((_, timing)) = effect.as_preset() {
+                    if let Some(spring) = &timing.spring {
+                        out.push(spring_report(&p, spring));
+                    }
+                }
+                if let AnimationEffect::Keyframes(k) = effect {
+                    for kf_anim in &k.keyframes {
+                        if let Some(spring) = &kf_anim.spring {
+                            out.push(spring_report(&p, spring));
+                        }
+                    }
+                }
+            }
+        }
+        match &child.component {
+            Component::Card(c) => collect_springs_in_children(&c.children, &p, out),
+            Component::Flex(c) => collect_springs_in_children(&c.children, &p, out),
+            Component::Grid(c) => collect_springs_in_children(&c.children, &p, out),
+            Component::Positioned(c) => collect_springs_in_children(&c.children, &p, out),
+            Component::Container(c) => collect_springs_in_children(&c.children, &p, out),
+            _ => {}
+        }
+    }
+}
+
+fn spring_report(label: &str, spring: &SpringConfig) -> SpringReport {
+    SpringReport {
+        label: label.to_string(),
+        rest_seconds: spring_rest_time(spring),
+        duration_was_set: spring.duration.is_some(),
+    }
+}
+
+#[cfg(test)]
+mod spring_report_tests {
+    //! Issue #167 lot E: `rustmotion info` must surface the settle time of
+    //! every spring it finds, recursing into containers the same way
+    //! `validate_schema::validate_children` already does.
+    use super::*;
+    use rustmotion::components::ChildComponent;
+
+    #[test]
+    fn finds_a_spring_on_a_top_level_preset() {
+        let child: ChildComponent = serde_json::from_value(serde_json::json!({
+            "type": "text",
+            "content": "hi",
+            "style": {
+                "animation": [{ "name": "bounce_in", "duration": 0.6, "spring": { "damping": 12, "stiffness": 100, "mass": 1 } }]
+            }
+        }))
+        .unwrap();
+        let mut out = Vec::new();
+        collect_springs_in_children(&[child], "test", &mut out);
+        assert_eq!(
+            out.len(),
+            1,
+            "expected exactly one spring report: {:?}",
+            out.iter().map(|r| &r.label).collect::<Vec<_>>()
+        );
+        assert!(out[0].rest_seconds > 0.0);
+        assert!(!out[0].duration_was_set);
+    }
+
+    #[test]
+    fn finds_a_spring_nested_inside_a_card() {
+        let child: ChildComponent = serde_json::from_value(serde_json::json!({
+            "type": "card",
+            "children": [{
+                "type": "text",
+                "content": "hi",
+                "style": {
+                    "animation": [{ "name": "fade_in_up", "duration": 0.6, "spring": { "damping": 15, "stiffness": 100, "mass": 1 } }]
+                }
+            }]
+        }))
+        .unwrap();
+        let mut out = Vec::new();
+        collect_springs_in_children(&[child], "test", &mut out);
+        assert_eq!(
+            out.len(),
+            1,
+            "spring nested inside a card must be found: {out:?}"
+        );
+        assert!(
+            out[0].label.contains("layer 1"),
+            "expected the nested layer to be labelled: {}",
+            out[0].label
+        );
+    }
+
+    #[test]
+    fn reports_the_pinned_duration_when_spring_duration_is_set() {
+        let child: ChildComponent = serde_json::from_value(serde_json::json!({
+            "type": "text",
+            "content": "hi",
+            "style": {
+                "animation": [{
+                    "name": "bounce_in",
+                    "duration": 0.6,
+                    "spring": { "damping": 6, "stiffness": 120, "mass": 1, "duration": 0.8 }
+                }]
+            }
+        }))
+        .unwrap();
+        let mut out = Vec::new();
+        collect_springs_in_children(&[child], "test", &mut out);
+        assert_eq!(out.len(), 1);
+        assert!(out[0].duration_was_set);
+        assert!(
+            (out[0].rest_seconds - 0.8).abs() < 1e-9,
+            "spring.duration must be reported verbatim as the settle time, got {}",
+            out[0].rest_seconds
+        );
+    }
+
+    #[test]
+    fn no_springs_produces_an_empty_report() {
+        let child: ChildComponent = serde_json::from_value(serde_json::json!({
+            "type": "text",
+            "content": "hi",
+            "style": {
+                "animation": [{ "name": "fade_in_up", "duration": 0.6 }]
+            }
+        }))
+        .unwrap();
+        let mut out = Vec::new();
+        collect_springs_in_children(&[child], "test", &mut out);
+        assert!(out.is_empty(), "unexpected spring reports: {out:?}");
+    }
+}

crates/rustmotion-cli/src/commands/validate_schema.rs

@@ -378,6 +378,14 @@ fn check_color_str(s: &str, label: &str, path: &str, errors: &mut Vec<String>) {
 /// floors these defensively (belt and suspenders — see `spring_value`'s doc
 /// comment), but catching it here gives the author an actionable error
 /// instead of a silently broken render.
+///
+/// Issue #167 lot E adds `duration`/`rest_threshold`: a non-positive
+/// `duration` would make `spring_value`'s remap divide by zero or invert
+/// time (both silently ignored by the solver rather than rejected — see its
+/// `Some(duration) if duration > 0.0` guard), and a `rest_threshold` outside
+/// `(0.0, 1.0)` is either meaningless (<=0: never satisfied except in the
+/// limit) or vacuous (>=1.0: satisfied from t=0, before the spring has
+/// moved at all — the whole 0→1 travel is "close enough").
 fn check_spring_config(spring: &SpringConfig, path: &str, errors: &mut Vec<String>) {
     if spring.mass <= 0.0 {
         errors.push(format!(
@@ -400,6 +408,28 @@ fn check_spring_config(spring: &SpringConfig, path: &str, errors: &mut Vec<Strin
             spring.damping
         ));
     }
+    if let Some(duration) = spring.duration {
+        if duration <= 0.0 {
+            errors.push(format!(
+                "{path}: spring.duration must be > 0 when set (got {duration}) — a zero or \
+                 negative duration cannot be mapped to a settle time"
+            ));
+        }
+    }
+    if let Some(rest_threshold) = spring.rest_threshold {
+        if rest_threshold <= 0.0 {
+            errors.push(format!(
+                "{path}: spring.rest_threshold must be > 0 when set (got {rest_threshold}) — a \
+                 zero or negative threshold is never satisfied, so the spring would never be \
+                 considered at rest"
+            ));
+        } else if rest_threshold >= 1.0 {
+            errors.push(format!(
+                "{path}: spring.rest_threshold must be < 1.0 when set (got {rest_threshold}) — \
+                 a threshold this large is satisfied at t=0, before the spring has moved"
+            ));
+        }
+    }
 }
 
 /// The `time_scale` declared on a container component, if any.
@@ -716,6 +746,108 @@ mod style_warning_tests {
         assert!(errors.is_empty(), "unexpected errors: {errors:?}");
     }
 
+    // ---- issue #167 lot E: `spring.duration`/`spring.rest_threshold` ----
+
+    #[test]
+    fn zero_spring_duration_is_an_error() {
+        let child: ChildComponent = serde_json::from_value(serde_json::json!({
+            "type": "text",
+            "content": "hi",
+            "style": {
+                "animation": [{ "name": "fade_in_up", "duration": 0.6, "spring": { "damping": 15, "stiffness": 100, "mass": 1, "duration": 0.0 } }]
+            }
+        }))
+        .unwrap();
+        let mut errors = Vec::new();
+        let mut warnings = Vec::new();
+        validate_children(&[child], "test", 4.0, &mut errors, &mut warnings);
+        assert!(
+            errors
+                .iter()
+                .any(|e| e.contains("spring.duration") && e.contains("> 0")),
+            "missing spring.duration error: {errors:?}"
+        );
+    }
+
+    #[test]
+    fn negative_spring_duration_is_an_error() {
+        let child: ChildComponent = serde_json::from_value(serde_json::json!({
+            "type": "text",
+            "content": "hi",
+            "style": {
+                "animation": [{ "name": "bounce_in", "duration": 0.6, "spring": { "damping": 15, "stiffness": 100, "mass": 1, "duration": -0.5 } }]
+            }
+        }))
+        .unwrap();
+        let mut errors = Vec::new();
+        let mut warnings = Vec::new();
+        validate_children(&[child], "test", 4.0, &mut errors, &mut warnings);
+        assert!(
+            errors.iter().any(|e| e.contains("spring.duration")),
+            "missing spring.duration error: {errors:?}"
+        );
+    }
+
+    #[test]
+    fn zero_or_negative_rest_threshold_is_an_error() {
+        let child: ChildComponent = serde_json::from_value(serde_json::json!({
+            "type": "text",
+            "content": "hi",
+            "style": {
+                "animation": [{ "name": "fade_in_up", "duration": 0.6, "spring": { "damping": 15, "stiffness": 100, "mass": 1, "rest_threshold": -0.01 } }]
+            }
+        }))
+        .unwrap();
+        let mut errors = Vec::new();
+        let mut warnings = Vec::new();
+        validate_children(&[child], "test", 4.0, &mut errors, &mut warnings);
+        assert!(
+            errors.iter().any(|e| e.contains("spring.rest_threshold")),
+            "missing spring.rest_threshold error: {errors:?}"
+        );
+    }
+
+    #[test]
+    fn absurdly_large_rest_threshold_is_an_error() {
+        // >= 1.0 is satisfied at t=0, before the spring has moved at all —
+        // "at rest" from the first frame is not a meaningful measurement.
+        let child: ChildComponent = serde_json::from_value(serde_json::json!({
+            "type": "text",
+            "content": "hi",
+            "style": {
+                "animation": [{ "name": "fade_in_up", "duration": 0.6, "spring": { "damping": 15, "stiffness": 100, "mass": 1, "rest_threshold": 1.0 } }]
+            }
+        }))
+        .unwrap();
+        let mut errors = Vec::new();
+        let mut warnings = Vec::new();
+        validate_children(&[child], "test", 4.0, &mut errors, &mut warnings);
+        assert!(
+            errors.iter().any(|e| e.contains("spring.rest_threshold")),
+            "missing spring.rest_threshold error: {errors:?}"
+        );
+    }
+
+    #[test]
+    fn positive_spring_duration_and_rest_threshold_are_accepted() {
+        let child: ChildComponent = serde_json::from_value(serde_json::json!({
+            "type": "text",
+            "content": "hi",
+            "style": {
+                "animation": [{
+                    "name": "fade_in_up",
+                    "duration": 0.8,
+                    "spring": { "damping": 15, "stiffness": 100, "mass": 1, "duration": 0.8, "rest_threshold": 0.01 }
+                }]
+            }
+        }))
+        .unwrap();
+        let mut errors = Vec::new();
+        let mut warnings = Vec::new();
+        validate_children(&[child], "test", 4.0, &mut errors, &mut warnings);
+        assert!(errors.is_empty(), "unexpected errors: {errors:?}");
+    }
+
     #[test]
     fn positive_time_scale_is_accepted() {
         let child: ChildComponent = serde_json::from_value(serde_json::json!({