docs: update section about DISABLE_COMMIT_PAUSING_MECHANISM feature flag (#9117)

## Summary

This PR updates the docs about feature flags with our current
recommendations.

## Test plan

Author: tomekzaw

docs/docs-reanimated/docs/guides/feature-flags.md

@@ -37,95 +37,48 @@ Feature flags available in `react-native-worklets` are listed [on this page](htt
 
 When enabled, this feature flag is supposed to eliminate jittering of animated components like sticky header while scrolling. This feature flag is safe to enable only if `preventShadowTreeCommitExhaustion` feature flag from `react-native` (available since React Native 0.81) is also enabled – see instructions below. In all other cases it can lead to unresponsiveness of the app due to the starvation of React commits. For more details, see [PR #7852](https://github.com/software-mansion/react-native-reanimated/pull/7852).
 
-In React Native 0.81, `preventShadowTreeCommitExhaustion` feature flag can be enabled by setting experimental release level. If you're using Expo, you can enable it using [`expo-build-properties`](https://docs.expo.dev/versions/latest/sdk/build-properties/):
+:::note
+We no longer recommend setting experimental React Native release level because it also enables other unrelated flags, for instance `fixTextClippingAndroid15useBoundsForWidth`, which supposedly causes incorrect text clipping on Android 15. Instead, you should enable only the `preventShadowTreeCommitExhaustion` feature flag according to the instructions below.
+:::
 
-```json
-{
-  "expo": {
-    // ...
-    "plugins": [
-      // ...
-      // highlight-start
-      [
-        "expo-build-properties",
-        {
-          "android": {
-            "reactNativeReleaseLevel": "experimental"
-          },
-          "ios": {
-            "reactNativeReleaseLevel": "experimental"
-          }
-        }
-      ]
-      // highlight-end
-    ]
-  }
-}
-```
+Here's how you can enable `preventShadowTreeCommitExhaustion` feature flag from React Native.
 
-It will add the following lines in `gradle.properties` (Android) and `Info.plist` (iOS):
+First, please apply the following change in `ReactNativeFeatureFlagsDefaults.h`:
 
-```gradle
-reactNativeReleaseLevel=experimental
+```diff
+   bool preventShadowTreeCommitExhaustion() override {
+-    return false;
++    return true;
+   }
 ```
 
-```
-<key>ReactNativeReleaseLevel</key>
-<string>experimental</string>
-```
+It is recommended to make a patch after applying this change to make it persistent using tools like [patch-package](https://www.npmjs.com/package/patch-package), [yarn patch](https://yarnpkg.com/cli/patch) or [pnpm patch](https://pnpm.io/cli/patch).
 
-If you're not using Expo, in order to enable experimental release level on Android, you need to add the following lines in `MainApplication.kt` of your app:
-
-```kt
-package com.helloworld
-
-import android.app.Application
-import com.facebook.react.PackageList
-import com.facebook.react.ReactApplication
-import com.facebook.react.ReactHost
-import com.facebook.react.ReactNativeApplicationEntryPoint.loadReactNative
-import com.facebook.react.ReactNativeHost
-import com.facebook.react.ReactPackage
-// highlight-next-line
-import com.facebook.react.defaults.DefaultNewArchitectureEntryPoint
-import com.facebook.react.defaults.DefaultReactHost.getDefaultReactHost
-import com.facebook.react.defaults.DefaultReactNativeHost
-// highlight-next-line
-import com.facebook.react.common.ReleaseLevel
-
-class MainApplication : Application(), ReactApplication {
-  // ...
+You also need to build React Native from source in order for this change to take effect.
 
-  override fun onCreate() {
-    super.onCreate()
-    // highlight-next-line
-    DefaultNewArchitectureEntryPoint.releaseLevel = ReleaseLevel.EXPERIMENTAL
-    loadReactNative(this)
-  }
+For Android, please add the following lines in `android/settings.gradle` according to the instructions [here](https://reactnative.dev/contributing/how-to-build-from-source#update-your-project-to-build-from-source):
+
+```gradle
+includeBuild('../node_modules/react-native') {
+    dependencySubstitution {
+        substitute(module("com.facebook.react:react-android")).using(project(":packages:react-native:ReactAndroid"))
+        substitute(module("com.facebook.react:react-native")).using(project(":packages:react-native:ReactAndroid"))
+        substitute(module("com.facebook.react:hermes-android")).using(project(":packages:react-native:ReactAndroid:hermes-engine"))
+        substitute(module("com.facebook.react:hermes-engine")).using(project(":packages:react-native:ReactAndroid:hermes-engine"))
+    }
 }
 ```
 
-For iOS, you need edit the following line in `AppDelegate.swift` of your app:
-
-```swift
-@main
-class AppDelegate: UIResponder, UIApplicationDelegate {
-  // ...
-
-  func application(
-    _ application: UIApplication,
-    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil
-  ) -> Bool {
-    let delegate = ReactNativeDelegate()
-    // highlight-next-line
-    let factory = RCTReactNativeFactory(delegate: delegate, releaseLevel: RCTReleaseLevel.Experimental)
-    delegate.dependencyProvider = RCTAppDependencyProvider()
+For iOS, add the following lines in `ios/Podfile` according to the instructions [here](https://reactnative.dev/blog/2026/02/11/react-native-0.84#precompiled-binaries-on-ios-by-default).
 
-    // ...
-  }
-}
+```rb
+ENV['RCT_USE_PREBUILT_RNCORE'] = '0'
 ```
 
+:::tip
+Flickering/jittering while scrolling will be ultimately fixed by branching mechanism which was introduced in [this PR to React Native](https://github.com/facebook/react-native/pull/54835). Currently it's under testing and should be out in some future release of React Native.
+:::
+
 ### `ANDROID_SYNCHRONOUSLY_UPDATE_UI_PROPS`
 
 When enabled, non-layout styles will be applied using the `synchronouslyUpdateViewOnUIThread` method (which doesn't involve layout recalculation) instead of than `ShadowTree::commit` method (which requires layout recalculation). In an artificial benchmark, it can lead to up to 4x increase of frames per second. Even though we don't expect such high speedups in the production apps, there should be a visible improvements in the smoothness of some animations. However, there are some unwanted side effects that one needs to take into account and properly compensate for:

docs/docs-reanimated/docs/guides/performance.md

@@ -20,7 +20,7 @@ Please note that downgrading your Expo SDK version or using an older release of
 
 **Problem:** When scrolling a `FlatList` or `ScrollView`, you might notice flickering or jittering of animated components (e.g. sticky header) implemented using `useAnimatedScrollHandler` hook.
 
-**Solution:** You need to upgrade to React Native 0.81 (or newer), set experimental release level in order to enable `preventShadowTreeCommitExhaustion` feature flag and enable [`DISABLE_COMMIT_PAUSING_MECHANISM`](/docs/guides/feature-flags#disable_commit_pausing_mechanism) static feature flag as described [here](/docs/guides/feature-flags#disable_commit_pausing_mechanism).
+**Solution:** You need to upgrade to React Native 0.81 (or newer), enable `preventShadowTreeCommitExhaustion` React Native feature flag and enable [`DISABLE_COMMIT_PAUSING_MECHANISM`](/docs/guides/feature-flags#disable_commit_pausing_mechanism) static feature flag. For more details, click [here](/docs/guides/feature-flags#disable_commit_pausing_mechanism).
 
 ### ⚠️ Lower FPS while scrolling