Defer animation start time in FrameAnimationDriver (#56929)

Summary:

## 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/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

packages/react-native/ReactCommon/react/renderer/animated/tests/AnimationDriverTests.cpp

@@ -42,19 +42,29 @@ TEST_F(AnimationDriverTests, framesAnimation) {
 
   const double startTimeInTick = 12345;
 
+  // Frame 1: deferred start outputs frame 0 and re-anchors timing
   runAnimationFrame(startTimeInTick);
   EXPECT_EQ(round(nodesManager_->getValue(valueNodeTag).value()), 0);
 
-  runAnimationFrame(startTimeInTick + SingleFrameIntervalMs * 2.5);
+  // Frame 2: re-anchor completes, timeDelta=0 → still frame 0
+  runAnimationFrame(startTimeInTick + SingleFrameIntervalMs);
+  EXPECT_EQ(round(nodesManager_->getValue(valueNodeTag).value()), 0);
+
+  // Subsequent frames are measured from the re-anchored start
+  runAnimationFrame(
+      startTimeInTick + SingleFrameIntervalMs + SingleFrameIntervalMs * 2.5);
   EXPECT_EQ(round(nodesManager_->getValue(valueNodeTag).value()), 65);
 
-  runAnimationFrame(startTimeInTick + SingleFrameIntervalMs * 3);
+  runAnimationFrame(
+      startTimeInTick + SingleFrameIntervalMs + SingleFrameIntervalMs * 3);
   EXPECT_EQ(round(nodesManager_->getValue(valueNodeTag).value()), 90);
 
-  runAnimationFrame(startTimeInTick + SingleFrameIntervalMs * 4);
+  runAnimationFrame(
+      startTimeInTick + SingleFrameIntervalMs + SingleFrameIntervalMs * 4);
   EXPECT_EQ(round(nodesManager_->getValue(valueNodeTag).value()), toValue);
 
-  runAnimationFrame(startTimeInTick + SingleFrameIntervalMs * 10);
+  runAnimationFrame(
+      startTimeInTick + SingleFrameIntervalMs + SingleFrameIntervalMs * 10);
   EXPECT_EQ(round(nodesManager_->getValue(valueNodeTag).value()), toValue);
 }
 
@@ -84,12 +94,14 @@ TEST_F(AnimationDriverTests, framesAnimationReconfigurationClearsFrames) {
 
   const double startTimeInTick = 12345;
 
-  // Run first frame
+  // Deferred start frame + re-anchor frame
   runAnimationFrame(startTimeInTick);
   EXPECT_EQ(round(nodesManager_->getValue(valueNodeTag).value()), 0);
+  runAnimationFrame(startTimeInTick + SingleFrameIntervalMs);
+  EXPECT_EQ(round(nodesManager_->getValue(valueNodeTag).value()), 0);
 
-  // Reconfigure the same animation (same animationId) with new frames
-  // This triggers updateConfig on the existing FrameAnimationDriver
+  // Reconfigure the same animation (same animationId) with new frames.
+  // This triggers updateConfig → onConfigChanged → deferredStart_ = true again.
   const auto frames2 = folly::dynamic::array(0.0f, 0.5f, 1.0f);
   const auto toValue2 = 200;
   nodesManager_->startAnimatingNode(
@@ -99,22 +111,222 @@ TEST_F(AnimationDriverTests, framesAnimationReconfigurationClearsFrames) {
           "toValue", toValue2),
       std::nullopt);
 
-  // Reset animation timing
   const double newStartTimeInTick = 20000;
 
-  // Run animation at halfway point (1 frame into 3-frame animation)
+  // Deferred start frame for reconfigured animation
   runAnimationFrame(newStartTimeInTick);
-  runAnimationFrame(newStartTimeInTick + SingleFrameIntervalMs * 1);
+  EXPECT_EQ(nodesManager_->getValue(valueNodeTag).value(), 0);
+
+  // Re-anchor frame
+  runAnimationFrame(newStartTimeInTick + SingleFrameIntervalMs);
+  EXPECT_EQ(nodesManager_->getValue(valueNodeTag).value(), 0);
 
   // At frame 1 of 3 frames (50% progress), value should be approximately:
   // startValue (0) + 0.5 * (toValue2 - startValue) = 0 + 0.5 * 200 = 100
   // If frames accumulated (5 + 3 = 8 frames), we'd be at wrong position
-  // Use ceil rounding so 100.00x becomes 100.01
-  EXPECT_EQ(round(nodesManager_->getValue(valueNodeTag).value()), 100.01);
+  runAnimationFrame(newStartTimeInTick + SingleFrameIntervalMs * 2);
+  EXPECT_NEAR(nodesManager_->getValue(valueNodeTag).value(), 100, 0.01);
 
   // Complete the animation
-  runAnimationFrame(newStartTimeInTick + SingleFrameIntervalMs * 2);
-  EXPECT_EQ(round(nodesManager_->getValue(valueNodeTag).value()), toValue2);
+  runAnimationFrame(newStartTimeInTick + SingleFrameIntervalMs * 3);
+  EXPECT_EQ(nodesManager_->getValue(valueNodeTag).value(), toValue2);
+}
+
+TEST_F(AnimationDriverTests, framesAnimationDeferredStartPreventsSkipping) {
+  // Deferred start outputs frame 0 on the first update and re-anchors
+  // startFrameTimeMs_ so the second update also sees timeDelta=0.
+  // Without the fix the second frame would already be at value 25.
+  initNodesManager();
+
+  auto rootTag = getNextRootViewTag();
+
+  auto valueNodeTag = ++rootTag;
+  nodesManager_->createAnimatedNode(
+      valueNodeTag,
+      folly::dynamic::object("type", "value")("value", 0)("offset", 0));
+
+  const auto animationId = 1;
+  const auto frames = folly::dynamic::array(0.0f, 0.25f, 0.5f, 0.75f, 1.0f);
+  const auto toValue = 100;
+  nodesManager_->startAnimatingNode(
+      animationId,
+      valueNodeTag,
+      folly::dynamic::object("type", "frames")("frames", frames)(
+          "toValue", toValue),
+      std::nullopt);
+
+  const double t = 12345;
+
+  // Frame 1: both with and without fix, timeDelta=0 → value=0
+  runAnimationFrame(t);
+  EXPECT_EQ(nodesManager_->getValue(valueNodeTag).value(), 0);
+
+  // Frame 2: WITHOUT fix timeDelta=SI → value≈25.
+  // WITH fix the deferred start re-anchored startFrameTimeMs_, so
+  // timeDelta=0 → value=0. This assertion fails without the fix.
+  runAnimationFrame(t + SingleFrameIntervalMs);
+  EXPECT_EQ(nodesManager_->getValue(valueNodeTag).value(), 0);
+
+  // Frame 3: now timeDelta=SI from the re-anchored start
+  runAnimationFrame(t + SingleFrameIntervalMs * 2);
+  EXPECT_NEAR(nodesManager_->getValue(valueNodeTag).value(), 25, 0.01);
+
+  // Frame 4
+  runAnimationFrame(t + SingleFrameIntervalMs * 3);
+  EXPECT_NEAR(nodesManager_->getValue(valueNodeTag).value(), 50, 0.01);
+
+  // Complete
+  runAnimationFrame(t + SingleFrameIntervalMs * 5);
+  EXPECT_EQ(nodesManager_->getValue(valueNodeTag).value(), toValue);
+}
+
+TEST_F(
+    AnimationDriverTests,
+    framesAnimationDoesNotStartBeforeEndOfEventLoopTick) {
+  // Validates that animations don't start before the end of the current event
+  // loop tick, even if the main thread progresses after they've been set up.
+  //
+  // Scenario: animation is started, but the UI thread is busy with
+  // layout/mount work for several frames (~200ms) before the view composites.
+  // Without deferred start, the animation would skip ahead to the 200ms mark.
+  // With deferred start, the animation re-anchors and starts cleanly from
+  // frame 0 regardless of how much wall-clock time elapsed.
+  initNodesManager();
+
+  auto rootTag = getNextRootViewTag();
+
+  auto valueNodeTag = ++rootTag;
+  nodesManager_->createAnimatedNode(
+      valueNodeTag,
+      folly::dynamic::object("type", "value")("value", 0)("offset", 0));
+
+  const auto animationId = 1;
+  const auto frames = folly::dynamic::array(0.0f, 0.25f, 0.5f, 0.75f, 1.0f);
+  const auto toValue = 100;
+  nodesManager_->startAnimatingNode(
+      animationId,
+      valueNodeTag,
+      folly::dynamic::object("type", "frames")("frames", frames)(
+          "toValue", toValue),
+      std::nullopt);
+
+  const double setupTime = 10000;
+
+  // First runAnimationFrame happens right after setup — this is the first
+  // Choreographer tick that processes the animation. The deferred start
+  // outputs frame 0 and resets the time anchor.
+  runAnimationFrame(setupTime);
+  EXPECT_EQ(nodesManager_->getValue(valueNodeTag).value(), 0);
+
+  // Main thread is now busy with heavy layout/mount work for ~200ms
+  // (about 12 frame intervals). The next Choreographer callback arrives
+  // much later. Without deferred start, timeDelta would be 200ms and
+  // the animation would skip to the 200ms mark. With it, re-anchoring
+  // ensures timeDelta=0.
+  const double afterBusyPeriod = setupTime + 200;
+  runAnimationFrame(afterBusyPeriod);
+  EXPECT_EQ(nodesManager_->getValue(valueNodeTag).value(), 0)
+      << "Animation should not have progressed during the busy period";
+
+  // From here, animation progresses normally frame by frame
+  runAnimationFrame(afterBusyPeriod + SingleFrameIntervalMs);
+  EXPECT_NEAR(nodesManager_->getValue(valueNodeTag).value(), 25, 0.01);
+
+  runAnimationFrame(afterBusyPeriod + SingleFrameIntervalMs * 2);
+  EXPECT_NEAR(nodesManager_->getValue(valueNodeTag).value(), 50, 0.01);
+
+  runAnimationFrame(afterBusyPeriod + SingleFrameIntervalMs * 3);
+  EXPECT_NEAR(nodesManager_->getValue(valueNodeTag).value(), 75, 0.01);
+
+  runAnimationFrame(afterBusyPeriod + SingleFrameIntervalMs * 4);
+  EXPECT_EQ(nodesManager_->getValue(valueNodeTag).value(), toValue);
+}
+
+TEST_F(
+    AnimationDriverTests,
+    framesAnimationDoesNotStartBeforeEndOfEventLoopTick_multipleFrameGap) {
+  // Same scenario but the first runAnimationFrame itself arrives late
+  // (500ms after animation was set up) — simulating the case where the
+  // entire event loop tick is blocked by heavy JS/native work and
+  // Choreographer catches up later.
+  initNodesManager();
+
+  auto rootTag = getNextRootViewTag();
+
+  auto valueNodeTag = ++rootTag;
+  nodesManager_->createAnimatedNode(
+      valueNodeTag,
+      folly::dynamic::object("type", "value")("value", 0)("offset", 0));
+
+  const auto animationId = 1;
+  const auto frames = folly::dynamic::array(0.0f, 0.25f, 0.5f, 0.75f, 1.0f);
+  const auto toValue = 100;
+  nodesManager_->startAnimatingNode(
+      animationId,
+      valueNodeTag,
+      folly::dynamic::object("type", "frames")("frames", frames)(
+          "toValue", toValue),
+      std::nullopt);
+
+  // Simulate: 500ms passes before the first animation frame runs.
+  // The animation must still start at value 0 — it should never
+  // retroactively apply elapsed time.
+  const double lateFirstFrame = 50000;
+  runAnimationFrame(lateFirstFrame);
+  EXPECT_EQ(nodesManager_->getValue(valueNodeTag).value(), 0)
+      << "Animation must not skip ahead even if first frame arrives late";
+
+  // Second frame shortly after — re-anchor means timeDelta=0 still
+  runAnimationFrame(lateFirstFrame + SingleFrameIntervalMs);
+  EXPECT_EQ(nodesManager_->getValue(valueNodeTag).value(), 0)
+      << "Re-anchored start means second frame also sees timeDelta=0";
+
+  // Normal progression from the re-anchored point
+  runAnimationFrame(lateFirstFrame + SingleFrameIntervalMs * 2);
+  EXPECT_NEAR(nodesManager_->getValue(valueNodeTag).value(), 25, 0.01);
+
+  runAnimationFrame(lateFirstFrame + SingleFrameIntervalMs * 4);
+  EXPECT_NEAR(nodesManager_->getValue(valueNodeTag).value(), 75, 0.01);
+
+  runAnimationFrame(lateFirstFrame + SingleFrameIntervalMs * 5);
+  EXPECT_EQ(nodesManager_->getValue(valueNodeTag).value(), toValue);
+}
+
+TEST_F(AnimationDriverTests, framesAnimationDeferredStartOptOut) {
+  // When deferredStart is false, the animation starts immediately without
+  // the extra re-anchor frame.
+  initNodesManager();
+
+  auto rootTag = getNextRootViewTag();
+
+  auto valueNodeTag = ++rootTag;
+  nodesManager_->createAnimatedNode(
+      valueNodeTag,
+      folly::dynamic::object("type", "value")("value", 0)("offset", 0));
+
+  const auto animationId = 1;
+  const auto frames = folly::dynamic::array(0.0f, 0.25f, 0.5f, 0.75f, 1.0f);
+  const auto toValue = 100;
+  nodesManager_->startAnimatingNode(
+      animationId,
+      valueNodeTag,
+      folly::dynamic::object("type", "frames")("frames", frames)(
+          "toValue", toValue)("deferredStart", false),
+      std::nullopt);
+
+  const double t = 12345;
+
+  // Frame 1: timeDelta=0, value=0 (no deferred start delay)
+  runAnimationFrame(t);
+  EXPECT_EQ(nodesManager_->getValue(valueNodeTag).value(), 0);
+
+  // Frame 2: timeDelta=SI, value≈25 (animation progresses immediately)
+  runAnimationFrame(t + SingleFrameIntervalMs);
+  EXPECT_NEAR(nodesManager_->getValue(valueNodeTag).value(), 25, 0.01);
+
+  // Complete
+  runAnimationFrame(t + SingleFrameIntervalMs * 4);
+  EXPECT_EQ(nodesManager_->getValue(valueNodeTag).value(), toValue);
 }
 
 } // namespace facebook::react