Router replaces browser history entry if state changes (#83509)

packages/flutter/lib/src/services/system_navigator.dart

@@ -67,20 +67,34 @@ class SystemNavigator {
 
   /// Notifies the platform for a route information change.
   ///
-  /// On web, creates a new browser history entry and update URL with the route
-  /// information. Whether the history holds one entry or multiple entries is
-  /// determined by [selectSingleEntryHistory] and [selectMultiEntryHistory].
+  /// On web, this method behaves differently based on the single-entry or
+  /// multiple-entries history mode. Use the [selectSingleEntryHistory] and
+  /// [selectMultiEntryHistory] to toggle between modes.
   ///
-  /// Currently, this is ignored on other platforms.
+  /// For single-entry mode, this method replaces the current URL and state in
+  /// the current history entry. The flag `replace` is ignored.
+  ///
+  /// For multiple-entries mode, this method creates a new history entry on top
+  /// of the current entry if the `replace` is false, thus the user will
+  /// be on a new history entry as if the user has visited a new page, and the
+  /// browser back button brings the user back to the previous entry. If
+  /// `replace` is true, this method only updates the URL and the state in the
+  /// current history entry without pushing a new one.
+  ///
+  /// This method is ignored on other platforms.
+  ///
+  /// The `replace` flag defaults to false.
   static Future<void> routeInformationUpdated({
     required String location,
     Object? state,
+    bool replace = false,
   }) {
     return SystemChannels.navigation.invokeMethod<void>(
       'routeInformationUpdated',
       <String, dynamic>{
         'location': location,
         'state': state,
+        'replace': replace,
       },
     );
   }

packages/flutter/test/services/system_navigator_test.dart

@@ -43,11 +43,15 @@ void main() {
     ]);
 
     await verify(() => SystemNavigator.routeInformationUpdated(location: 'a'), <Object>[
-      isMethodCall('routeInformationUpdated', arguments: <String, dynamic>{ 'location': 'a', 'state': null }),
+      isMethodCall('routeInformationUpdated', arguments: <String, dynamic>{ 'location': 'a', 'state': null, 'replace': false }),
     ]);
 
     await verify(() => SystemNavigator.routeInformationUpdated(location: 'a', state: true), <Object>[
-      isMethodCall('routeInformationUpdated', arguments: <String, dynamic>{ 'location': 'a', 'state': true }),
+      isMethodCall('routeInformationUpdated', arguments: <String, dynamic>{ 'location': 'a', 'state': true, 'replace': false }),
+    ]);
+
+    await verify(() => SystemNavigator.routeInformationUpdated(location: 'a', state: true, replace: true), <Object>[
+      isMethodCall('routeInformationUpdated', arguments: <String, dynamic>{ 'location': 'a', 'state': true, 'replace': true }),
     ]);
 
     await verify(() => SystemNavigator.routeUpdated(routeName: 'a', previousRouteName: 'b'), <Object>[

packages/flutter/test/widgets/route_notification_messages_test.dart

@@ -69,6 +69,7 @@ void main() {
         arguments: <String, dynamic>{
           'location': '/',
           'state': null,
+          'replace': false,
         },
       ),
     ]);
@@ -86,6 +87,7 @@ void main() {
         arguments: <String, dynamic>{
           'location': '/A',
           'state': null,
+          'replace': false,
         },
       ),
     );
@@ -103,6 +105,7 @@ void main() {
         arguments: <String, dynamic>{
           'location': '/',
           'state': null,
+          'replace': false,
         },
       ),
     );
@@ -174,6 +177,7 @@ void main() {
         arguments: <String, dynamic>{
           'location': '/',
           'state': null,
+          'replace': false,
         },
       ),
     ]);
@@ -191,6 +195,7 @@ void main() {
         arguments: <String, dynamic>{
           'location': '/A',
           'state': null,
+          'replace': false,
         },
       ),
     );
@@ -208,6 +213,7 @@ void main() {
         arguments: <String, dynamic>{
           'location': '/B',
           'state': null,
+          'replace': false,
         },
       ),
     );
@@ -243,6 +249,7 @@ void main() {
         arguments: <String, dynamic>{
           'location': '/home',
           'state': null,
+          'replace': false,
         },
       ),
     ]);
@@ -294,6 +301,7 @@ void main() {
       isMethodCall('routeInformationUpdated', arguments: <String, dynamic>{
         'location': 'update',
         'state': 'state',
+        'replace': false,
       }),
     ]);
   });