web_ui: avoid crash for showPerformanceOverlay; log 'not supported' once (flutter#173518)

Fixes flutter#172405

On Flutter Web, calling `MaterialApp(showPerformanceOverlay: true)`
reaches
`SceneBuilder.addPerformanceOverlay`, which previously threw
`UnimplementedError`
and crashed apps. This change makes the method a no-op on Web and logs a
one-time
warning:

  "showPerformanceOverlay is not supported on Flutter Web. Use DevTools
   Performance (Timeline) instead."

Rationale: Avoid crashes and guide developers to the supported tooling
on Web.

Testing:
- Relied on CI for web_ui builds and tests.
- (Manual reproduction before fix) Enabling `showPerformanceOverlay` on
Web produced
  UnimplementedError from `canvaskit/layer_scene_builder.dart`.

---------

Co-authored-by: Mouad Debbar <mdebbar@google.com>

Author: muradhossin

engine/src/flutter/lib/web_ui/lib/src/engine/layer/layer_scene_builder.dart

@@ -7,11 +7,15 @@ import 'dart:typed_data';
 import 'package:ui/ui.dart' as ui;
 
 import '../lazy_path.dart';
+import '../util.dart';
 import '../vector_math.dart';
 import 'layer.dart';
 import 'layer_painting.dart';
 import 'layer_tree.dart';
 
+// Warn about performance overlay on Web only once per page load.
+bool _webPerfOverlayWarned = false;
+
 class LayerScene implements ui.Scene {
   LayerScene(RootLayer rootLayer) : layerTree = LayerTree(rootLayer);
 
@@ -43,8 +47,14 @@ class LayerSceneBuilder implements ui.SceneBuilder {
 
   @override
   void addPerformanceOverlay(int enabledOptions, ui.Rect bounds) {
-    // We don't plan to implement this on the web.
-    throw UnimplementedError();
+    // Not implemented on Web. Avoid crashing; warn once to guide developers.
+    if (!_webPerfOverlayWarned) {
+      _webPerfOverlayWarned = true;
+      printWarning(
+        'showPerformanceOverlay is not supported on Flutter Web. '
+        'See: https://docs.flutter.dev/perf/web-performance',
+      );
+    }
   }
 
   @override

engine/src/flutter/lib/web_ui/test/ui/performance_overlay_test.dart

@@ -0,0 +1,43 @@
+// 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';
+import 'package:ui/ui.dart' as ui;
+
+void main() {
+  internalBootstrapBrowserTest(() => testMain);
+}
+
+void testMain() {
+  group('LayerSceneBuilder.addPerformanceOverlay', () {
+    final List<String> warnings = <String>[];
+    late void Function(String) oldPrintWarning;
+
+    setUpAll(() {
+      oldPrintWarning = printWarning;
+      printWarning = (String warning) {
+        warnings.add(warning);
+      };
+    });
+
+    tearDownAll(() {
+      printWarning = oldPrintWarning;
+    });
+
+    test('does not throw and warns only once per page load', () {
+      final sb1 = ui.SceneBuilder();
+      warnings.clear();
+      expect(() => sb1.addPerformanceOverlay(0, ui.Rect.zero), returnsNormally);
+      expect(warnings, hasLength(1));
+      expect(warnings.single, contains('showPerformanceOverlay is not supported on Flutter Web'));
+
+      final sb2 = ui.SceneBuilder();
+      warnings.clear();
+      expect(() => sb2.addPerformanceOverlay(0, ui.Rect.zero), returnsNormally);
+      expect(warnings, isEmpty, reason: 'Second call should not produce additional warnings.');
+    });
+  });
+}