[web] Warn users when picking a deprecated renderer. (flutter#55709)

Warn users when they pick a deprecated renderer for the web, and point them to the appropriate /go/ link.

## Issues

* Part of flutter#145954
* Fixes flutter#154879

[C++, Objective-C, Java style guides]: https://github.com/flutter/engine/blob/main/CONTRIBUTING.md#style

Author: ditman

lib/web_ui/lib/src/engine/configuration.dart

@@ -167,7 +167,7 @@ class FlutterConfiguration {
 
   /// Auto detect which rendering backend to use.
   ///
-  /// Using flutter tools option "--web-render=auto" or not specifying one
+  /// Using flutter tools option "--web-renderer=auto" or not specifying one
   /// would set the value to true. Otherwise, it would be false.
   static const bool flutterWebAutoDetect =
       bool.fromEnvironment('FLUTTER_WEB_AUTO_DETECT', defaultValue: true);
@@ -177,10 +177,10 @@ class FlutterConfiguration {
 
   /// Enable the Skia-based rendering backend.
   ///
-  /// Using flutter tools option "--web-render=canvaskit" would set the value to
+  /// Using flutter tools option "--web-renderer=canvaskit" would set the value to
   /// true.
   ///
-  /// Using flutter tools option "--web-render=html" would set the value to false.
+  /// Using flutter tools option "--web-renderer=html" would set the value to false.
   static const bool useSkia = bool.fromEnvironment('FLUTTER_WEB_USE_SKIA');
 
   // Runtime parameters.

lib/web_ui/lib/src/engine/renderer.dart

@@ -38,6 +38,19 @@ abstract class Renderer {
         useCanvasKit = FlutterConfiguration.useSkia;
       }
 
+      // Warn users in development that anything other than canvaskit is deprecated.
+      assert(() {
+        if (!useCanvasKit) {
+          // The user requested 'html' or 'auto' either in the command-line or JS.
+          final String requested =
+            configuration.requestedRendererType ??
+            (FlutterConfiguration.flutterWebAutoDetect ? 'auto' : 'html');
+          printWarning(
+            'The HTML Renderer is being deprecated. Stop using the "$requested" renderer mode.'
+            '\nSee: https://docs.flutter.dev/to/web-html-renderer-deprecation');
+        }
+        return true;
+      }());
       return useCanvasKit ? CanvasKitRenderer() : HtmlRenderer();
     }
   }

lib/web_ui/test/html/deprecation_test.dart

@@ -0,0 +1,36 @@
+// Copyright 2013 The Flutter Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+import 'package:test/bootstrap/browser.dart';
+import 'package:test/test.dart';
+import 'package:ui/src/engine.dart';
+
+void main() {
+  internalBootstrapBrowserTest(() => testMain);
+}
+
+void testMain() {
+  final List<String> warnings = <String>[];
+  late void Function(String) oldPrintWarning;
+
+  setUpAll(() async {
+    oldPrintWarning = printWarning;
+    printWarning = (String warning) {
+      warnings.add(warning);
+    };
+  });
+
+  tearDownAll(() {
+    printWarning = oldPrintWarning;
+  });
+
+  test('Emit a warning when the HTML Renderer was picked.', () {
+    final Renderer chosenRenderer = renderer;
+
+    expect(chosenRenderer, isA<HtmlRenderer>());
+    expect(warnings, contains(
+      contains('See: https://docs.flutter.dev/to/web-html-renderer-deprecation')
+    ));
+  });
+}