fix(LayoutAnimations): serialize config updates with pullTransaction

[bartlomiejbloniarz]

Before this change, configureAnimationBatch could update animation configuration while pullTransaction was already making animation decisions. Different parts of one pull could observe different configs. A retargeted animation could also use a different config from the one that started it.

Now updates collect in pendingConfigUpdates_. lockAndFlushConfigUpdates applies the full batch once at the start of pullTransaction and keeps the config stable for the rest of that pull. This gives every pull one config boundary and one consistent set of animation rules.

Caveat

animationsMutex_ is shared by all surfaces. If two surfaces call pullTransaction at the same time, one surface can wait while the other completes its config-dependent work. This can make multi-surface setups slower.

This does not change the result of either pull. Each pull uses one stable config state and captures its configs before releasing configLock. Most mobile apps use one Fabric surface, so this contention should be uncommon. We can separate config state by surface later if needed.

Threading analysis

This is how it breaks:

Here are the drawings for the new flow. Didn't want to spam the description:
AI analysis

Test Plan

• Run the config-spam stress screen below with Legacy and Experimental layout animations.
• Verify that repeated config changes do not cause frame jumps or incorrect final layouts.

ConfigSpamExample.tsx — paste into apps/common-app/src/apps/reanimated/examples/EmptyExample.tsx and open the Empty example.

import React, { useEffect, useState } from 'react';
import {
  Pressable,
  SafeAreaView,
  StyleSheet,
  Text,
  TouchableOpacity,
  View,
} from 'react-native';
import Animated, {
  FadeIn,
  FadeOut,
  LayoutAnimationConfig,
  LinearTransition,
  SequencedTransition,
} from 'react-native-reanimated';

const ITEMS = ['Item 1', 'Item 2', 'Item 3', 'Item 4', 'Item 5'];

const TRANSITIONS = [
  LinearTransition.duration(200),
  LinearTransition.duration(600),
  SequencedTransition.duration(400),
  undefined,
] as const;

const SPAM_INTERVAL_MS = 60;

export default function ConfigSpamExample() {
  const [items, setItems] = useState(ITEMS);
  const [spamming, setSpamming] = useState(false);
  const [tick, setTick] = useState(0);

  useEffect(() => {
    if (!spamming) {
      return;
    }
    const id = setInterval(() => setTick((prev) => prev + 1), SPAM_INTERVAL_MS);
    return () => clearInterval(id);
  }, [spamming]);

  const addItem = () => {
    let i = 1;
    while (items.includes(`Item ${i}`)) {
      i++;
    }
    setItems([...items, `Item ${i}`]);
  };

  const reorderItems = () => {
    setItems((prevItems) => [...prevItems].sort(() => Math.random() - 0.5));
  };

  const resetOrder = () => {
    setItems((prevItems) =>
      [...prevItems].sort(
        (left, right) =>
          parseInt(left.match(/\d+$/)![0], 10) -
          parseInt(right.match(/\d+$/)![0], 10)
      )
    );
  };

  return (
    <LayoutAnimationConfig skipEntering>
      <SafeAreaView style={styles.container}>
        <View style={styles.menu}>
          <Text style={styles.infoText}>Press an item to remove it</Text>
          <TouchableOpacity onPress={() => setSpamming((prev) => !prev)}>
            <Text style={styles.buttonText}>
              {spamming ? 'Stop configs' : 'Spam configs'}
            </Text>
          </TouchableOpacity>
          <View style={styles.row}>
            <TouchableOpacity onPress={addItem}>
              <Text style={styles.buttonText}>Add item</Text>
            </TouchableOpacity>
            <TouchableOpacity onPress={reorderItems}>
              <Text style={styles.buttonText}>Reorder</Text>
            </TouchableOpacity>
            <TouchableOpacity onPress={resetOrder}>
              <Text style={styles.buttonText}>Reset order</Text>
            </TouchableOpacity>
          </View>
        </View>

        <View style={styles.list}>
          {items.map((item) => (
            <Animated.View
              key={item}
              layout={TRANSITIONS[tick % TRANSITIONS.length]}
              entering={tick % 2 === 0 ? FadeIn : undefined}
              exiting={tick % 2 === 0 ? FadeOut : undefined}>
              <Pressable
                onPress={() =>
                  setItems((prevItems) =>
                    prevItems.filter((other) => other !== item)
                  )
                }
                style={styles.listItem}>
                <Text style={styles.itemText}>{item}</Text>
              </Pressable>
            </Animated.View>
          ))}
        </View>
      </SafeAreaView>
    </LayoutAnimationConfig>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
  },
  row: {
    flexDirection: 'row',
    gap: 16,
    alignItems: 'center',
  },
  list: {
    padding: 16,
    gap: 16,
  },
  listItem: {
    padding: 20,
    backgroundColor: '#b58df1',
  },
  itemText: {
    color: 'white',
    fontSize: 22,
  },
  menu: {
    padding: 16,
    alignItems: 'center',
    justifyContent: 'center',
    gap: 8,
  },
  infoText: {
    color: '#222534',
    fontSize: 18,
  },
  buttonText: {
    fontSize: 18,
    fontWeight: 'bold',
    color: '#b58df1',
  },
});

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 976e0af1-ebd2-4f55-aa50-bf45a31e43ce

📥 Commits

Reviewing files that changed from the base of the PR and between e073386 and f140fbf.

📒 Files selected for processing (1)

• packages/react-native-reanimated/CHANGELOG.md

Included review availability: Your plan provides up to 10 included reviews per hour; 6 remain after this review.

---

📝 Walkthrough

Walkthrough

The PR queues layout-animation configuration updates behind mutexes and passes serialized configurations through legacy and experimental proxies. It adds retargeting, surface-state cleanup, reparenting, animation cancellation, and final-frame reconciliation. It refactors transaction processing and registry-based proxy construction. The common app adds configuration and cleanup-ordering examples, enables the iOS modal example, and updates the changelog.

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly identifies the main change: serializing LayoutAnimations configuration updates with pullTransaction.
Description check	✅ Passed	The description directly explains the configuration race, the batching and locking changes, the performance caveat, and the planned stress test.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

🧹 Nitpick comments (1)

packages/react-native-reanimated/Common/cpp/reanimated/LayoutAnimations/LayoutAnimationsProxyCommon.cpp (1)

470-486: 🎯 Functional Correctness | 🔵 Trivial | 💤 Low value

Bruce thinks the two update mutations for one tag are the real smoking gun here.

On non-Android the opacity branch pushes Update(currentView → restoredView). The reconciliation branch then pushes Update(currentView → finalView). The second mutation uses the stale currentView as its old view, and its new view finalView discards the opacity that the first mutation just applied. The final props are still correct because finalView carries React's committed opacity, so this is a redundancy rather than a defect. Merge both effects into one mutation to keep the emitted pair consistent.

♻️ Proposed consolidation

     auto &animation = completedAnimation.animation;
+    auto restoredView = animation.finalView;
     if (!completedAnimation.shouldRemove && animation.opacity) {
 `#ifdef` ANDROID
       opacityRestorations.push_back(OpacityRestoration{
           .shadowView = animation.finalView,
           .opacity = *animation.opacity,
       });
 `#else`
-      auto restoredView = cloneViewWithOpacity(animation.currentView, *animation.opacity, propsParserContext);
-      mutations.push_back(ShadowViewMutation::UpdateMutation(animation.currentView, restoredView, animation.parentTag));
+      restoredView = cloneViewWithOpacity(animation.finalView, *animation.opacity, propsParserContext);
+      mutations.push_back(ShadowViewMutation::UpdateMutation(animation.currentView, restoredView, animation.parentTag));
 `#endif`
     }
-    if (!completedAnimation.shouldRemove && needsFinalFrameReconciliation(animation.type) &&
-        animation.currentView.layoutMetrics != animation.finalView.layoutMetrics) {
-      mutations.push_back(
-          ShadowViewMutation::UpdateMutation(animation.currentView, animation.finalView, animation.parentTag));
-    }

The exact shape depends on whether the opacity restore must precede the frame reconciliation, so adjust as needed.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: f071c793-ce1c-40bb-add5-880f2e0a17f1

📥 Commits

Reviewing files that changed from the base of the PR and between 5cc9135 and 98ae530.

📒 Files selected for processing (4)

• packages/react-native-reanimated/Common/cpp/reanimated/LayoutAnimations/LayoutAnimationsProxyCommon.cpp
• packages/react-native-reanimated/Common/cpp/reanimated/LayoutAnimations/LayoutAnimationsProxyCommon.h
• packages/react-native-reanimated/Common/cpp/reanimated/LayoutAnimations/LayoutAnimationsProxy_Experimental.cpp
• packages/react-native-reanimated/Common/cpp/reanimated/LayoutAnimations/LayoutAnimationsProxy_Experimental.h

Included review availability: Your plan provides up to 10 included reviews per hour; 5 remain after this review.

[bartlomiejbloniarz]

@coderabbitai review

[coderabbitai]

⚠️ Action not completed

Review rate limited.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[bartlomiejbloniarz]

@coderabbitai review

[coderabbitai]

⚠️ Action not completed

Review rate limited.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[bartlomiejbloniarz]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.