Defer animation start time in FrameAnimationDriver (#56929)

Summary:
Pull Request resolved: #56929

## Changelog:

[Internal] [Fixed] - Defer animation start time in FrameAnimationDriver

**Problem**: In complex apps, if animation is started in commit phase (the case if animation starts in useLayoutEffect, or from ViewTransition event handlers), it'll skip initial frames — the user sees the animation snap to an intermediate position. This happens because `FrameAnimationDriver` anchors its start time on the first `runAnimationStep` call, but the UI thread may be busy with layout/mount work for several frames before the view actually composites. The elapsed wall-clock time advances, causing `frameIndex` to jump ahead.

**Why**: `startFrameTimeMs_` is set to the Choreographer frame time on the first tick. If the UI thread is blocked processing a heavy tree (many views mounting), subsequent ticks arrive much later — `timeDeltaMs` jumps and the animation skips to a mid-point.
- Every major framework solves this: Flutter uses lazy start (`_startTime ??= timeStamp` on first actual tick), Android native uses `CALLBACK_COMMIT` to adjust post-traversal, and CSS View Transitions spec defers start until post-composite.

**Fix**: On the very first `update()` call, output the starting value (frame 0) and reset `startFrameTimeMs_ = -1`. This causes the base class to re-anchor on the next `runAnimationStep`, so elapsed time is measured from the first frame that has actually been rendered — not from when `startAnimatingNode` was dispatched. The flag disables itself after one use, so all subsequent frames use pure elapsed-time with no behavioral change.

Differential Revision: D106007152

Author: zeyap

packages/react-native/Libraries/Animated/__tests__/Animated-itest.js

@@ -4,7 +4,7 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  *
- * @fantom_flags useSharedAnimatedBackend:*
+ * @fantom_flags useSharedAnimatedBackend:* animatedDeferStartOfTimingAnimations:*
  * @flow strict-local
  * @format
  */
@@ -21,6 +21,12 @@ import {Animated, View, useAnimatedValue} from 'react-native';
 import {allowStyleProp} from 'react-native/Libraries/Animated/NativeAnimatedAllowlist';
 import ReactNativeElement from 'react-native/src/private/webapis/dom/nodes/ReactNativeElement';
 
+// Deferred start outputs the initial value on the first animation frame and
+// re-anchors timing on the second. This delays animation progress by one
+// frame interval (~16ms at 60 fps).
+const DEFERRED_START_MS =
+  ReactNativeFeatureFlags.animatedDeferStartOfTimingAnimations() ? 16 : 0;
+
 test('moving box by 100 points', () => {
   let _translateX;
   const viewRef = createRef<HostInstance>();
@@ -60,7 +66,7 @@ test('moving box by 100 points', () => {
     }).start();
   });
 
-  Fantom.unstable_produceFramesForDuration(500);
+  Fantom.unstable_produceFramesForDuration(500 + DEFERRED_START_MS);
 
   // shadow tree is not synchronised yet, position X is still 0.
   expect(viewElement.getBoundingClientRect().x).toBe(0);
@@ -81,6 +87,84 @@ test('moving box by 100 points', () => {
   expect(viewElement.getBoundingClientRect().x).toBe(100);
 });
 
+test('animation does not start before the end of the current event loop tick', () => {
+  // Validates that even if the main thread progresses after animation setup,
+  // the animation does not begin timing until after the current event loop
+  // tick completes and the first frame is produced.
+  if (!ReactNativeFeatureFlags.animatedDeferStartOfTimingAnimations()) {
+    // Without the flag, the animation anchors on the first frame time
+    // which already gives correct behavior for same-tick setup.
+    // The deferred start flag adds the extra guarantee that even if
+    // additional time passes before the first composite, we don't skip.
+    return;
+  }
+
+  let _translateX;
+  const viewRef = createRef<HostInstance>();
+
+  function MyApp() {
+    const translateX = useAnimatedValue(0);
+    _translateX = translateX;
+    return (
+      <Animated.View
+        ref={viewRef}
+        style={[
+          {
+            width: 100,
+            height: 100,
+          },
+          {transform: [{translateX}]},
+        ]}
+      />
+    );
+  }
+
+  const root = Fantom.createRoot();
+
+  Fantom.runTask(() => {
+    root.render(<MyApp />);
+  });
+
+  const viewElement = ensureInstance(viewRef.current, ReactNativeElement);
+
+  // Start the animation inside a task (simulating commit phase / useLayoutEffect)
+  Fantom.runTask(() => {
+    Animated.timing(_translateX, {
+      toValue: 100,
+      duration: 1000,
+      useNativeDriver: true,
+    }).start();
+  });
+
+  // Produce exactly one frame (~16ms). With deferred start, this first frame
+  // outputs the initial value and re-anchors timing — the animation should
+  // NOT have progressed yet, even though wall-clock time has advanced.
+  Fantom.unstable_produceFramesForDuration(16);
+
+  const transformAfterFirstFrame =
+    // $FlowFixMe[incompatible-use]
+    Fantom.unstable_getDirectManipulationProps(viewElement).transform[0];
+
+  // The animation must still be at 0 after the first frame — it has not
+  // started timing yet because deferred start re-anchors on this frame.
+  expect(transformAfterFirstFrame.translateX).toBe(0);
+
+  // Now produce 500ms of additional frames. The animation timing starts
+  // from the re-anchored point, so we expect ~50% progress.
+  Fantom.unstable_produceFramesForDuration(500);
+
+  const transformAfterHalf =
+    // $FlowFixMe[incompatible-use]
+    Fantom.unstable_getDirectManipulationProps(viewElement).transform[0];
+
+  expect(transformAfterHalf.translateX).toBeCloseTo(50, 0);
+
+  // Complete the animation
+  Fantom.unstable_produceFramesForDuration(500);
+  Fantom.runWorkLoop();
+  expect(viewElement.getBoundingClientRect().x).toBe(100);
+});
+
 test('animation driven by onScroll event', () => {
   const scrollViewRef = createRef<HostInstance>();
   const viewRef = createRef<HostInstance>();
@@ -248,7 +332,7 @@ test('animated opacity', () => {
     }).start();
   });
 
-  Fantom.unstable_produceFramesForDuration(30);
+  Fantom.unstable_produceFramesForDuration(30 + DEFERRED_START_MS);
   expect(Fantom.unstable_getDirectManipulationProps(viewElement).opacity).toBe(
     0,
   );
@@ -559,7 +643,7 @@ test('animate layout props', () => {
     }).start();
   });
 
-  Fantom.unstable_produceFramesForDuration(10);
+  Fantom.unstable_produceFramesForDuration(10 + DEFERRED_START_MS);
 
   // TODO: this shouldn't be necessary since animation should be stopped after duration
   Fantom.runTask(() => {
@@ -712,7 +796,7 @@ test('Animated.sequence', () => {
     });
   });
 
-  Fantom.unstable_produceFramesForDuration(500);
+  Fantom.unstable_produceFramesForDuration(500 + DEFERRED_START_MS);
 
   expect(
     // $FlowFixMe[incompatible-use]

packages/react-native/Libraries/Animated/animations/TimingAnimation.js

@@ -15,6 +15,7 @@ import type AnimatedValue from '../nodes/AnimatedValue';
 import type AnimatedValueXY from '../nodes/AnimatedValueXY';
 import type {AnimationConfig, EndCallback} from './Animation';
 
+import * as ReactNativeFeatureFlags from '../../../src/private/featureflags/ReactNativeFeatureFlags';
 import AnimatedColor from '../nodes/AnimatedColor';
 import Animation from './Animation';
 
@@ -69,6 +70,7 @@ export default class TimingAnimation extends Animation {
   _animationFrame: ?AnimationFrameID;
   _timeout: ?TimeoutID;
   _platformConfig: ?PlatformConfig;
+  _deferredStart: boolean;
 
   constructor(config: TimingAnimationConfigSingle) {
     super(config);
@@ -78,6 +80,7 @@ export default class TimingAnimation extends Animation {
     this._duration = config.duration ?? 500;
     this._delay = config.delay ?? 0;
     this._platformConfig = config.platformConfig;
+    this._deferredStart = false;
   }
 
   __getNativeAnimationConfig(): Readonly<{
@@ -102,6 +105,7 @@ export default class TimingAnimation extends Animation {
       iterations: this.__iterations,
       platformConfig: this._platformConfig,
       debugID: this.__getDebugID(),
+      deferredStart: this._deferredStart,
     };
   }
 
@@ -116,6 +120,10 @@ export default class TimingAnimation extends Animation {
 
     this._fromValue = fromValue;
     this._onUpdate = onUpdate;
+    if (ReactNativeFeatureFlags.animatedDeferStartOfTimingAnimations()) {
+      this._deferredStart = animatedValue.__deferAnimationStart;
+      animatedValue.__deferAnimationStart = false;
+    }
 
     const start = () => {
       this._startTime = Date.now();

packages/react-native/Libraries/Animated/nodes/AnimatedValue.js

@@ -20,6 +20,7 @@ import type AnimatedNode from './AnimatedNode';
 import type {AnimatedNodeConfig} from './AnimatedNode';
 import type AnimatedTracking from './AnimatedTracking';
 
+import * as ReactNativeFeatureFlags from '../../../src/private/featureflags/ReactNativeFeatureFlags';
 import NativeAnimatedHelper from '../../../src/private/animated/NativeAnimatedHelper';
 import AnimatedInterpolation from './AnimatedInterpolation';
 import AnimatedWithChildren from './AnimatedWithChildren';
@@ -95,6 +96,7 @@ export default class AnimatedValue extends AnimatedWithChildren {
   _offset: number;
   _animation: ?Animation;
   _tracking: ?AnimatedTracking;
+  __deferAnimationStart: boolean;
 
   constructor(value: number, config?: ?AnimatedValueConfig) {
     super(config);
@@ -107,6 +109,8 @@ export default class AnimatedValue extends AnimatedWithChildren {
 
     this._startingValue = this._value = value;
     this._offset = 0;
+    this.__deferAnimationStart =
+      ReactNativeFeatureFlags.animatedDeferStartOfTimingAnimations();
     this._animation = null;
     if (config && config.useNativeDriver) {
       this.__makeNative();
@@ -327,6 +331,10 @@ export default class AnimatedValue extends AnimatedWithChildren {
       result => {
         this._animation = null;
         callback && callback(result);
+        if (this._animation == null) {
+          this.__deferAnimationStart =
+            ReactNativeFeatureFlags.animatedDeferStartOfTimingAnimations();
+        }
       },
       previousAnimation,
       this,

packages/react-native/ReactCommon/react/renderer/animated/drivers/FrameAnimationDriver.cpp

@@ -49,15 +49,34 @@ void FrameAnimationDriver::onConfigChanged() {
     frames_.push_back(frameValue);
   }
   toValue_ = config_["toValue"].asDouble();
+  auto deferIt = config_.find("deferredStart");
+  deferredStart_ = deferIt == config_.items().end() || deferIt->second.asBool();
 }
 
-bool FrameAnimationDriver::update(double timeDeltaMs, bool /*restarting*/) {
+bool FrameAnimationDriver::update(double timeDeltaMs, bool restarting) {
   if (auto node =
           manager_->getAnimatedNode<ValueAnimatedNode>(animatedValueTag_)) {
     if (!startValue_) {
       startValue_ = node->getRawValue();
     }
 
+    if (deferredStart_ && restarting) {
+      // On the very first update after start: output the starting value
+      // (frame 0) and defer the time anchor. The base class will re-anchor
+      // startFrameTimeMs_ on the next call, so elapsed time is measured
+      // from the first frame that has actually been rendered — not from
+      // when startAnimatingNode was dispatched.
+      //
+      // This prevents skipping initial frames when the UI thread is busy
+      // with layout/mount work between animation start and first composite.
+      node->setRawValue(
+          startValue_.value() + frames_[0] * (toValue_ - startValue_.value()));
+      markNodeUpdated(node->tag());
+      startFrameTimeMs_ = -1;
+      deferredStart_ = false;
+      return false;
+    }
+
     const auto startIndex =
         static_cast<size_t>(std::round(timeDeltaMs / SingleFrameIntervalMs));
     assert(startIndex >= 0);

packages/react-native/ReactCommon/react/renderer/animated/drivers/FrameAnimationDriver.h

@@ -35,6 +35,7 @@ class FrameAnimationDriver : public AnimationDriver {
   std::vector<double> frames_{};
   double toValue_{0};
   std::optional<double> startValue_{};
+  bool deferredStart_{true};
 };
 
 } // namespace facebook::react