[ Widget Preview ] Improve IDE integration support (#176114)

This change adds support for two DTD Editor service RPCs and makes
functionality that's dependent on the availability of the Editor service
reactive to the service availability changing.

The newly added `getActiveLocation` Editor RPC now allows for us to
properly determine which source file is selected at startup, removing
the need for special casing around initializing the filtered preview
set.

The `navigateToCode` Editor RPC is now supported, and URIs in stack
traces can now be clicked to navigate to the source location in the IDE.

Both filtering previews by selected file and stack frame navigation
links are only enabled when the Editor service is available.

Fixes flutter/flutter#176113

Author: bkonyi

packages/flutter_tools/lib/src/commands/widget_preview.dart

@@ -254,6 +254,7 @@ final class WidgetPreviewStartCommand extends WidgetPreviewSubCommandBase with C
     shutdownHooks: shutdownHooks,
     onHotRestartPreviewerRequest: onHotRestartRequest,
     dtdLauncher: DtdLauncher(logger: logger, artifacts: artifacts, processManager: processManager),
+    project: rootProject.widgetPreviewScaffoldProject,
   );
 
   /// The currently running instance of the widget preview scaffold.

packages/flutter_tools/lib/src/widget_preview/dtd_services.dart

@@ -6,6 +6,7 @@ import 'dart:async';
 
 import 'package:dtd/dtd.dart';
 import 'package:json_rpc_2/json_rpc_2.dart';
+import 'package:package_config/package_config_types.dart';
 import 'package:process/process.dart';
 
 import '../artifacts.dart';
@@ -15,6 +16,8 @@ import '../base/logger.dart';
 import '../base/platform.dart';
 import '../base/process.dart';
 import '../convert.dart';
+import '../dart/package_map.dart';
+import '../project.dart';
 
 typedef DtdService = (String, DTDServiceCallback);
 
@@ -25,6 +28,7 @@ class WidgetPreviewDtdServices {
     required this.shutdownHooks,
     required this.dtdLauncher,
     required this.onHotRestartPreviewerRequest,
+    required this.project,
   }) {
     shutdownHooks.addShutdownHook(() async {
       await _dtd?.close();
@@ -40,9 +44,14 @@ class WidgetPreviewDtdServices {
   static const kWidgetPreviewService = 'widget-preview';
   static const kIsWindows = 'isWindows';
   static const kHotRestartPreviewer = 'hotRestartPreviewer';
+  static const kResolveUri = 'resolveUri';
 
   /// The list of DTD service methods registered by the tool.
-  late final services = <DtdService>[(kHotRestartPreviewer, _hotRestart), (kIsWindows, _isWindows)];
+  late final services = <DtdService>[
+    (kHotRestartPreviewer, _hotRestart),
+    (kIsWindows, _isWindows),
+    (kResolveUri, _resolveUri),
+  ];
 
   // END KEEP SYNCED
 
@@ -54,6 +63,11 @@ class WidgetPreviewDtdServices {
   /// scaffold.
   final VoidCallback onHotRestartPreviewerRequest;
 
+  /// The widget_preview_scaffold project.
+  final FlutterProject project;
+
+  PackageConfig? _packageConfig;
+
   DartToolingDaemon? _dtd;
 
   /// The [Uri] pointing to the currently connected DTD instance.
@@ -95,6 +109,12 @@ class WidgetPreviewDtdServices {
   Future<Map<String, Object?>> _isWindows(Parameters _) async {
     return BoolResponse(const LocalPlatform().isWindows).toJson();
   }
+
+  Future<Map<String, Object?>> _resolveUri(Parameters params) async {
+    _packageConfig ??= await loadPackageConfigWithLogging(project.packageConfig, logger: logger);
+    final Uri? result = _packageConfig!.resolve(Uri.parse(params.asMap['uri'] as String));
+    return StringResponse(result.toString()).toJson();
+  }
 }
 
 /// Manages the lifecycle of a Dart Tooling Daemon (DTD) instance.

packages/flutter_tools/lib/src/widget_preview/preview_pubspec_builder.dart

@@ -40,6 +40,7 @@ class PreviewPubspecBuilder {
   ///   - flutter_lints, which is referenced by the analysis_options.yaml generated by the 'app'
   ///     template.
   ///   - google_fonts, which is used for the Roboto Mono font.
+  ///   - json_rpc_2, which is used to handle errors thrown by package:dtd
   ///   - path, which is used to normalize and compare paths.
   ///   - stack_trace, which is used to generate terse stack traces for displaying errors thrown
   ///     by widgets being previewed.
@@ -48,6 +49,7 @@ class PreviewPubspecBuilder {
     'dtd',
     'flutter_lints',
     'google_fonts',
+    'json_rpc_2',
     'path',
     'stack_trace',
     'url_launcher',

packages/flutter_tools/templates/template_manifest.json

@@ -344,6 +344,7 @@
     "templates/widget_preview_scaffold/lib/src/widget_preview_rendering.dart.tmpl",
     "templates/widget_preview_scaffold/lib/src/widget_preview_scaffold_controller.dart.tmpl",
     "templates/widget_preview_scaffold/lib/src/controls.dart.tmpl",
+    "templates/widget_preview_scaffold/lib/src/dtd/utils.dart.tmpl",
     "templates/widget_preview_scaffold/lib/src/dtd/dtd_services.dart.tmpl",
     "templates/widget_preview_scaffold/lib/src/dtd/editor_service.dart.tmpl",
     "templates/widget_preview_scaffold/lib/src/generated_preview.dart.tmpl",

packages/flutter_tools/templates/widget_preview_scaffold/lib/src/controls.dart.tmpl

@@ -153,25 +153,38 @@ class LayoutTypeSelector extends StatelessWidget {
 
 /// A toggle button that enables / disables filtering previews by the currently
 /// selected source file.
+///
+/// This control is hidden if the DTD Editor service isn't available.
 class FilterBySelectedFileToggle extends StatelessWidget {
   const FilterBySelectedFileToggle({super.key, required this.controller});
 
+  @visibleForTesting
+  static const kTooltip = 'Filter previews by selected file';
+
   final WidgetPreviewScaffoldController controller;
 
   @override
   Widget build(BuildContext context) {
-    return _ControlDecorator(
-      child: ValueListenableBuilder(
-        valueListenable: controller.filterBySelectedFileListenable,
-        builder: (context, value, child) {
-          return IconButton(
-            onPressed: controller.toggleFilterBySelectedFile,
-            icon: Icon(Icons.file_open),
-            color: value ? Colors.blue : Colors.black,
-            tooltip: 'Filter previews by selected file',
-          );
-        },
-      ),
+    return ValueListenableBuilder(
+      valueListenable: controller.editorServiceAvailable,
+      builder: (context, editorServiceAvailable, child) {
+        if (!editorServiceAvailable) {
+          return Container();
+        }
+        return _ControlDecorator(
+          child: ValueListenableBuilder(
+            valueListenable: controller.filterBySelectedFileListenable,
+            builder: (context, value, child) {
+              return IconButton(
+                onPressed: controller.toggleFilterBySelectedFile,
+                icon: Icon(Icons.file_open),
+                color: value ? Colors.blue : Colors.black,
+                tooltip: kTooltip,
+              );
+            },
+          ),
+        );
+      },
     );
   }
 }

packages/flutter_tools/templates/widget_preview_scaffold/lib/src/dtd/dtd_services.dart.tmpl

@@ -5,6 +5,7 @@
 import 'dart:async';
 
 import 'package:dtd/dtd.dart';
+import 'package:widget_preview_scaffold/src/dtd/utils.dart';
 import 'editor_service.dart';
 
 /// Provides services, streams, and RPC invocations to interact with Flutter developer tooling.
@@ -17,9 +18,10 @@ class WidgetPreviewScaffoldDtdServices with DtdEditorService {
   //
   // START KEEP SYNCED
 
-  static const kWidgetPreviewService = 'widget-preview';
+  static const String kWidgetPreviewService = 'widget-preview';
   static const kIsWindows = 'isWindows';
-  static const kHotRestartPreviewer = 'hotRestartPreviewer';
+  static const String kHotRestartPreviewer = 'hotRestartPreviewer';
+  static const String kResolveUri = 'resolveUri';
 
   // END KEEP SYNCED
 
@@ -50,21 +52,35 @@ class WidgetPreviewScaffoldDtdServices with DtdEditorService {
     await dtd.close();
   }
 
-  Future<DTDResponse> _call(
+  Future<DTDResponse?> _call(
     String methodName, {
     Map<String, Object?>? params,
-  }) => dtd.call(kWidgetPreviewService, methodName, params: params);
+  }) => dtd.safeCall(kWidgetPreviewService, methodName, params: params);
 
   /// Returns `true` if the operating system is Windows.
   late final bool isWindows;
 
   Future<void> _determineIfWindows() async {
-    isWindows = ((await _call(kIsWindows)) as BoolResponse).value!;
+    isWindows = (BoolResponse.fromDTDResponse(
+      (await _call(kIsWindows))!,
+    )).value!;
   }
 
   /// Trigger a hot restart of the widget preview scaffold.
   Future<void> hotRestartPreviewer() => _call(kHotRestartPreviewer);
 
+  /// Resolves a package:// URI to a file:// URI using the package_config.
+  ///
+  /// Returns null if [uri] can not be resolved.
+  Future<Uri?> resolveUri(Uri uri) async {
+    final response = await _call(kResolveUri, params: {'uri': uri.toString()});
+    if (response == null) {
+      return null;
+    }
+    final result = StringResponse.fromDTDResponse(response).value;
+    return result == null ? null : Uri.parse(result);
+  }
+
   @override
   late final DartToolingDaemon dtd;
 }

packages/flutter_tools/templates/widget_preview_scaffold/lib/src/dtd/editor_service.dart.tmpl

@@ -2,9 +2,12 @@
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
+import 'dart:async';
+
 import 'package:dtd/dtd.dart';
 import 'package:flutter/foundation.dart';
 import 'package:widget_preview_scaffold/src/dtd/dtd_services.dart';
+import 'package:widget_preview_scaffold/src/dtd/utils.dart';
 
 /// Provides support for interacting with the Editor DTD service registered by IDE plugins.
 mixin DtdEditorService {
@@ -13,6 +16,27 @@ mixin DtdEditorService {
   /// The name of the Editor service.
   static const String kEditorService = 'Editor';
 
+  /// The name of the Editor's getActiveLocation method.
+  static const String kGetActiveLocation = 'getActiveLocation';
+
+  /// The name of the Editor's navigateToCode method.
+  static const String kNavigateToCode = 'navigateToCode';
+
+  /// The name of the DTD Service stream.
+  static const String kServiceStream = 'Service';
+
+  /// The kind of the event sent over the [kServiceStream] stream when a new
+  /// service method is registered.
+  static const kServiceRegistered = 'ServiceRegistered';
+
+  /// The kind of the event sent over the [kServiceStream] stream when a
+  /// service method is unregistered.
+  static const kServiceUnregistered = 'ServiceUnregistered';
+
+  /// Whether or not the Editor service is available.
+  ValueListenable<bool> get editorServiceAvailable => _editorServiceAvailable;
+  static final _editorServiceAvailable = ValueNotifier<bool>(false);
+
   /// The currently selected source file in the IDE.
   ValueListenable<TextDocument?> get selectedSourceFile => _selectedSourceFile;
   static final _selectedSourceFile = ValueNotifier<TextDocument?>(null);
@@ -41,14 +65,61 @@ mixin DtdEditorService {
           ).textDocument;
       }
     });
-    await dtd.streamListen(kEditorService);
+    await dtd.safeStreamListen(kEditorService);
+
+    dtd.onEvent(kServiceStream).listen((data) async {
+      switch (data) {
+        case DTDEvent(
+          kind: kServiceRegistered,
+          data: {
+            DtdParameters.service: kEditorService,
+            DtdParameters.method: kGetActiveLocation,
+          },
+        ):
+          // Manually retrieve the currently selected source file.
+          unawaited(_updateSelectedSourceFile());
+          _editorServiceAvailable.value = true;
+        case DTDEvent(
+          kind: kServiceRegistered,
+          data: {DtdParameters.service: kEditorService},
+        ):
+          _editorServiceAvailable.value = true;
+        case DTDEvent(
+          kind: kServiceUnregistered,
+          data: {DtdParameters.service: kEditorService},
+        ):
+          _editorServiceAvailable.value = false;
+      }
+    });
+    await dtd.safeStreamListen(kServiceStream);
   }
 
   @mustCallSuper
   void dispose() {
     _selectedSourceFile.dispose();
+    _editorServiceAvailable.dispose();
     _editorTheme.dispose();
   }
+
+  Future<void> _updateSelectedSourceFile() async {
+    final response = await dtd.safeCall(kEditorService, kGetActiveLocation);
+    if (response != null) {
+      _selectedSourceFile.value = ActiveLocation.fromJson(
+        response.result,
+      ).textDocument;
+    }
+  }
+
+  /// Tells the editor to navigate to a given code [location].
+  ///
+  /// Only locations with `file://` URIs are valid.
+  Future<void> navigateToCode(CodeLocation location) async {
+    await dtd.safeCall(
+      kEditorService,
+      kNavigateToCode,
+      params: location.toJson(),
+    );
+  }
 }
 
 // TODO(bkonyi): much of the following code is copied from the DevTools codebase. We should publish
@@ -123,13 +194,24 @@ class ThemeChangedEvent extends EditorEvent {
 }
 
 /// An event sent by an editor when the current cursor position/s change.
-class ActiveLocationChangedEvent extends EditorEvent {
-  ActiveLocationChangedEvent({
-    required this.selections,
-    required this.textDocument,
-  });
+class ActiveLocationChangedEvent extends ActiveLocation implements EditorEvent {
+  ActiveLocationChangedEvent({required ActiveLocation activeLocation})
+    : super(
+        selections: activeLocation.selections,
+        textDocument: activeLocation.textDocument,
+      );
 
   ActiveLocationChangedEvent.fromJson(Map<String, Object?> map)
+    : this(activeLocation: ActiveLocation.fromJson(map));
+
+  @override
+  EditorEventKind get kind => EditorEventKind.activeLocationChanged;
+}
+
+class ActiveLocation {
+  ActiveLocation({required this.selections, required this.textDocument});
+
+  ActiveLocation.fromJson(Map<String, Object?> map)
     : this(
         textDocument: map.containsKey(Field.textDocument)
             ? TextDocument.fromJson(
@@ -145,9 +227,6 @@ class ActiveLocationChangedEvent extends EditorEvent {
   final List<EditorSelection> selections;
   final TextDocument? textDocument;
 
-  @override
-  EditorEventKind get kind => EditorEventKind.activeLocationChanged;
-
   Map<String, Object?> toJson() => {
     Field.selections: selections,
     Field.textDocument: textDocument,
@@ -269,13 +348,39 @@ class CursorPosition {
   int get hashCode => Object.hash(character, line);
 }
 
+/// Parameters for the `navigateToCode` request.
+class CodeLocation {
+  const CodeLocation({required this.uri, this.line, this.column});
+
+  /// The URI of the location to navigate to. Only `file://` URIs are supported
+  /// unless the service registration's `capabilities` indicate other schemes
+  /// are supported.
+  ///
+  /// Editors should return error code 144 if a caller passes a URI with an
+  /// unsupported scheme.
+  final String uri;
+
+  /// Optional 1-based line number to navigate to.
+  final int? line;
+
+  /// Optional 1-based column number to navigate to.
+  final int? column;
+
+  Map<String, Object?> toJson() => {
+    Field.uri: uri,
+    Field.line: ?line,
+    Field.column: ?column,
+  };
+}
+
 /// Constants for all fields used in JSON maps to avoid literal strings that
 /// may have typos sprinkled throughout the API classes.
 abstract class Field {
   static const active = 'active';
   static const anchor = 'anchor';
   static const backgroundColor = 'backgroundColor';
   static const character = 'character';
+  static const column = 'column';
   static const end = 'end';
   static const fontSize = 'fontSize';
   static const foregroundColor = 'foregroundColor';