Fix laggy spring animations at 240hz refresh rates

[mattgperry]

Summary

• Fix systematic velocity loss in useSpring/attachFollow at high refresh rates (240hz+)
• Add analytical velocity derivative to the spring generator, eliminating frame-rate-dependent finite-difference errors
• Use stable function reference for frame.postRender to deduplicate redundant callbacks from rapid input events

Problem

On 240hz displays, spring animations following a moving target (like useSpring tracking mouse position) appeared laggy and stuttered. The spring element fell ~22% behind compared to the same animation at 60hz.

Root cause: When the spring target changed, attachFollow stopped the animation and created a new one, using value.getVelocity() to preserve velocity. This finite-difference velocity estimate divides the frame-over-frame position change by the frame interval. At 240hz (~4ms frames), the spring barely moves per frame, so the measured velocity severely underestimates the true instantaneous velocity. This systematic velocity loss compounds every frame, causing the spring to progressively fall behind.

Fix

1. Analytical spring velocity (spring/index.ts): Added a velocity(t) method to the spring generator that returns the exact derivative of the spring equation at time t, rather than approximating via finite difference. This gives accurate velocity regardless of frame rate.

2. Generator velocity on JSAnimation (JSAnimation.ts): Added a generatorVelocity getter that reads the generator's analytical velocity when available, with finite-difference fallback for non-spring generators.

3. Accurate velocity in attachFollow (follow-value.ts): When retargeting a running spring, use activeAnimation.generatorVelocity instead of value.getVelocity(). This preserves exact spring momentum across target changes.

4. Callback deduplication (follow-value.ts): Extract the frame.postRender callback to a stable function reference so the frame loop's Set deduplicates multiple calls from rapid input events within a single frame.

Test plan

• New test follow-value-framerate.test.ts verifies 240hz and 60hz spring positions are within 15% of each other (was ~22% off before fix)
• All 18 existing spring-value tests pass
• All 101 JSAnimation + spring generator tests pass
• Full yarn test passes (400 motion-dom + 760 framer-motion tests)
• yarn build succeeds

Fixes #3265

🤖 Generated with Claude Code

[greptile-apps]

Greptile Summary

This PR successfully fixes a critical bug where spring animations at 240hz refresh rates appeared laggy and fell ~22% behind compared to 60hz. The root cause was systematic velocity loss due to finite-difference estimation when springs retargeted.

Key Changes

• Analytical spring velocity: Added exact velocity derivatives for all three spring types (underdamped, critically damped, overdamped) in the spring generator, providing frame-rate-independent velocity calculation
• JSAnimation velocity getter: New generatorVelocity property uses analytical velocity when available, with finite-difference fallback for non-spring generators
• Accurate velocity preservation: attachFollow now captures activeAnimation.generatorVelocity before stopping, preserving exact spring momentum across target changes instead of using the lossy value.getVelocity()
• Callback deduplication: Extracted stable function reference for frame.postRender to prevent redundant callbacks from rapid input events

Test Coverage

New test verifies 240hz and 60hz spring positions are within 15% (was ~22% off before fix). All existing spring and animation tests continue to pass.

Minor Issue

Test helper has a logic bug in delta calculation (line 11-12) but doesn't affect test validity since animations use timestamps directly.

Confidence Score: 5/5

• Safe to merge - mathematically sound fix with comprehensive test coverage
• The fix addresses a real performance issue with a mathematically correct solution. The analytical velocity derivatives are properly implemented for all spring damping cases, the integration is clean with proper fallbacks, and test coverage validates the fix. The minor test helper issue doesn't affect correctness.
• No files require special attention

Important Files Changed

Filename	Overview
packages/motion-dom/src/animation/generators/spring/index.ts	Added analytical velocity derivatives for underdamped, critically damped, and overdamped springs, eliminating frame-rate-dependent finite-difference errors
packages/motion-dom/src/animation/JSAnimation.ts	Added generatorVelocity getter that uses analytical velocity when available with finite-difference fallback for non-spring generators
packages/motion-dom/src/value/follow-value.ts	Uses activeAnimation.generatorVelocity instead of value.getVelocity() to preserve accurate velocity across retargets, and extracts stable callback reference for deduplication
packages/motion-dom/src/value/tests/follow-value-framerate.test.ts	New test verifying spring consistency across frame rates, but has a minor issue in processFrame delta calculation logic

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Target changes on MotionValue] --> B[attachFollow schedules animation]
    B --> C{currentValue == targetValue?}
    C -->|Yes| D[Stop animation, no work needed]
    C -->|No| E{activeAnimation exists?}
    E -->|Yes| F[Capture activeAnimation.generatorVelocity<br/>analytical derivative]
    E -->|No| G[Use value.getVelocity<br/>finite difference]
    F --> H[Stop old animation]
    G --> H
    H --> I[Create new JSAnimation<br/>with captured velocity]
    I --> J{Generator has velocity method?}
    J -->|Yes - Spring| K[Use analytical spring.velocity<br/>exact derivative at time t]
    J -->|No - Other| L[Use finite difference fallback<br/>sample at t and t-5ms]
    K --> M[Animation runs with<br/>preserved momentum]
    L --> M
    
    style F fill:#90EE90
    style K fill:#90EE90
    style G fill:#FFB6C1
    style L fill:#FFB6C1

Loading

_{Last reviewed commit: 90c0f87}

[greptile-apps]

frameData.timestamp is set before calculating frameData.delta, so delta will always be 0 and fall back to 1000/60. Capture the previous timestamp first:

Suggested change

	frameData.timestamp = timestamp
	frameData.delta = timestamp - (frameData.timestamp || 0) || 1000 / 60
	const previousTimestamp = frameData.timestamp
	frameData.timestamp = timestamp
	frameData.delta = timestamp - (previousTimestamp || 0) || 1000 / 60