Add "prefersDebugSession" + rename capabilities flag (#7949)

packages/devtools_app/lib/src/service/editor/editor_client.dart

@@ -46,6 +46,7 @@ abstract class EditorClient {
     String? page,
     bool? forceExternal,
     bool? requiresDebugSession,
+    bool? prefersDebugSession,
   });
 
   /// Requests the editor enables a new platform (for example by running

packages/devtools_app/lib/src/standalone_ui/api/impl/dart_tooling_api.dart

@@ -212,12 +212,14 @@ class PostMessageEditorClient implements EditorClient {
     String? page,
     bool? forceExternal,
     bool? requiresDebugSession,
+    bool? prefersDebugSession,
   }) async {
     await _api.openDevToolsPage(
       debugSessionId,
       page: page,
       forceExternal: forceExternal,
       requiresDebugSession: requiresDebugSession,
+      prefersDebugSession: prefersDebugSession,
     );
   }
 

packages/devtools_app/lib/src/standalone_ui/api/impl/vs_code_api.dart

@@ -95,6 +95,7 @@ final class VsCodeApiImpl implements VsCodeApi {
     String? page,
     bool? forceExternal,
     bool? requiresDebugSession,
+    bool? prefersDebugSession,
   }) {
     return sendRequest(
       VsCodeApi.jsonOpenDevToolsPageMethod,
@@ -103,6 +104,7 @@ final class VsCodeApiImpl implements VsCodeApi {
         VsCodeApi.jsonPageParameter: page,
         VsCodeApi.jsonForceExternalParameter: forceExternal,
         VsCodeApi.jsonRequiresDebugSessionParameter: requiresDebugSession,
+        VsCodeApi.jsonPrefersDebugSessionParameter: prefersDebugSession,
       },
     );
   }
@@ -215,8 +217,9 @@ class VsCodeCapabilitiesImpl implements VsCodeCapabilities {
       _raw?[VsCodeCapabilities.openDevToolsExternallyField] == true;
 
   @override
-  bool get openDevToolsWithRequiresDebugSessionFlag =>
-      _raw?[VsCodeCapabilities.openDevToolsWithRequiresDebugSessionFlagField] ==
+  bool get openDevToolsWithOptionalDebugSessionFlags =>
+      _raw?[
+          VsCodeCapabilities.openDevToolsWithOptionalDebugSessionFlagsField] ==
       true;
 
   @override

packages/devtools_app/lib/src/standalone_ui/api/vs_code_api.dart

@@ -57,16 +57,21 @@ abstract interface class VsCodeApi {
   /// external browser window.
   ///
   /// If [debugSessionId] is `null` the [requiresDebugSession] flag will
-  /// determine whether the editor will select (or ask the user to select) a
-  /// debug session for the page. If [requiresDebugSession] is `null` (or if
-  /// the `openDevToolsWithRequiresDebugSessionFlag` capability is `false`) then
+  /// indicate whether the editor must select (or ask the user) for a debug
+  /// session. If [requiresDebugSession] is `false` but [prefersDebugSession] is
+  /// `true`, then the editor should use or prompt for a debug session if one
+  /// is available, but otherwise launch without a debug session.
+  ///
+  /// If [requiresDebugSession] is `null` (or if the
+  /// `openDevToolsWithOptionalDebugSessionFlags` capability is `false`) then
   /// the editor will try to make this decision automatically (which may be
   /// inaccurate for pages it does not know about, like extensions).
   Future<void> openDevToolsPage(
     String? debugSessionId, {
     String? page,
     bool? forceExternal,
     bool? requiresDebugSession,
+    bool? prefersDebugSession,
   });
 
   /// Sends a Hot Reload request to the debug session with ID [debugSessionId].
@@ -96,6 +101,7 @@ abstract interface class VsCodeApi {
   static const jsonDebugSessionIdParameter = 'debugSessionId';
   static const jsonPlatformTypeParameter = 'platformType';
   static const jsonRequiresDebugSessionParameter = 'requiresDebugSession';
+  static const jsonPrefersDebugSessionParameter = 'prefersDebugSession';
 }
 
 /// This class defines a device event sent by the Dart/Flutter extensions in VS
@@ -163,9 +169,10 @@ abstract interface class VsCodeCapabilities {
   bool get openDevToolsExternally;
 
   /// Whether the `openDevToolsPage` method can be called with the
-  /// `requiresDebugSession` flag to indicate whether the editor should select/
-  /// prompt for a debug session if one was not provided.
-  bool get openDevToolsWithRequiresDebugSessionFlag;
+  /// `requiresDebugSession` and `prefersDebugSession` flags to indicate
+  /// whether the editor should select/prompt for a debug session if one was not
+  /// provided.
+  bool get openDevToolsWithOptionalDebugSessionFlags;
 
   /// Whether the `hotReload` method is available call to hot reload a specific
   /// debug session.
@@ -178,8 +185,8 @@ abstract interface class VsCodeCapabilities {
   static const jsonSelectDeviceField = 'selectDevice';
   static const openDevToolsPageField = 'openDevToolsPage';
   static const openDevToolsExternallyField = 'openDevToolsExternally';
-  static const openDevToolsWithRequiresDebugSessionFlagField =
-      'openDevToolsWithRequiresDebugSessionFlag';
+  static const openDevToolsWithOptionalDebugSessionFlagsField =
+      'openDevToolsWithOptionalDebugSessionFlags';
   static const hotReloadField = 'hotReload';
   static const hotRestartField = 'hotRestart';
 }

packages/devtools_app/test/test_infra/scenes/standalone_ui/editor_service/editor_server.dart

@@ -39,6 +39,7 @@ abstract class EditorServer {
     String? page,
     bool forceExternal,
     bool requiresDebugSession,
+    bool prefersDebugSession,
   ) {}
 
   /// Overridden by subclasses to provide an implementation of the

packages/devtools_app/test/test_infra/scenes/standalone_ui/editor_service/fake_editor.dart

@@ -116,6 +116,7 @@ mixin FakeEditor on EditorServer {
     String? page,
     bool forceExternal,
     bool requiresDebugSession,
+    bool prefersDebugSession,
   ) {}
 }