From 7e2b4e8f86d53d877b5fd8300094e6cf0f012bb2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Lo=C3=AFc=20Sharma?=
 <737941+loic-sharma@users.noreply.github.com>
Date: Tue, 4 Mar 2025 11:20:28 -0800
Subject: [PATCH] [Web] Improve onboarding docs (#164246)

---
 docs/tool/README.md                     |  2 +-
 engine/src/flutter/lib/web_ui/README.md | 48 +++++++++++++++++++++----
 2 files changed, 42 insertions(+), 8 deletions(-)

diff --git a/docs/tool/README.md b/docs/tool/README.md
index c8804a4d2e3..87e9952764c 100644
--- a/docs/tool/README.md
+++ b/docs/tool/README.md
@@ -187,7 +187,7 @@ with. A typical example would be:
 ```yaml
 dependency_overrides:
   sky_engine:
-    path: /path/to/flutter/engine/out/host_debug/gen/dart-pkg/sky_engine
+    path: /path/to/flutter/engine/src/out/host_debug/gen/dart-pkg/sky_engine
 ```
 
 Replace `host_debug` with the actual build that you want to use (similar to `--local-engine`, but typically
diff --git a/engine/src/flutter/lib/web_ui/README.md b/engine/src/flutter/lib/web_ui/README.md
index e05830879d7..5248177cbf4 100644
--- a/engine/src/flutter/lib/web_ui/README.md
+++ b/engine/src/flutter/lib/web_ui/README.md
@@ -8,8 +8,8 @@ If you are setting up a workspace for the first time, start by following the
 instructions at [Setting up the Engine development environment][1]. In addition,
 it is useful to add the following to your `PATH` environment variable:
 
-- `ENGINE_ROOT/src/flutter/lib/web_ui/dev`, so you can run the `felt` command
-  from anywhere.
+- `FLUTTER_ROOT/engine/src/flutter/lib/web_ui/dev`, so you can run the `felt`
+  command from anywhere.
 - `FLUTTER_ROOT/bin`, so you can run `dart` and `flutter` commands from
   anywhere.
 
@@ -135,7 +135,7 @@ tests locally. To make changes effective on LUCI follow instructions in
 
 ### Rolling browsers
 
-When running tests on LUCI using Chrome, LUCI uses the version of Chrome for 
+When running tests on LUCI using Chrome, LUCI uses the version of Chrome for
 Testing fetched from CIPD.
 
 Since the engine code and infra recipes do not live in the same repository
@@ -178,7 +178,7 @@ The available versions of Chrome for Testing available can be found [here](https
   instructions (this step requires sufficient privileges; contact
   #hackers-infra-🌡 on [Flutter's Discord server](https://github.com/flutter/flutter/wiki/Chat)).
 - Edit `dev/package_lock.yaml` and update the following values under `chrome`:
-  - Set `version` to the full four part version number of the build of Chrome 
+  - Set `version` to the full four part version number of the build of Chrome
     for Testing you want to roll (for example, `118.0.5993.70`)
 - Run `dart dev/package_roller.dart` and make sure it completes successfully.
   The script uploads the specified versions of Chromium (and Chromedriver) to the
@@ -250,6 +250,38 @@ Instead, we update this file manually once in a while.
 `canvaskit_lock.yaml` locks the version of CanvasKit for tests and production
 use.
 
+### Debugging the Web Engine
+
+Build the Flutter Web engine locally:
+
+```
+felt build
+```
+
+Run a Flutter app in debug mode using your locally built Web Engine artifacts:
+
+* **Option 1**: Launch a Chrome window from the command line.
+   ```
+   flutter run --local-web-sdk=wasm_release --debug -d chrome
+   ```
+   Exiting `flutter run` will close the app's Chrome window.
+* **Option 2**: Launch a web server on port `8080`:
+  ```
+  flutter run --local-web-sdk=wasm_release --debug -d web-server --web-port 8080
+  ```
+  To see your Flutter app, navigate your browser to http://localhost:8080.
+  
+  This option is useful if you want to keep your browser window when you
+  you restart `flutter run`, or, if you need to debug using browsers that
+  aren't supported by `flutter run`, such as Firefox and Safari.
+
+You can use [Chrome DevTools][7] to debug the Flutter Web engine.
+To open Chrome DevTools, right click and press **Inspect** on the Chrome window.
+Navigate to the [**Sources** tab][8].
+The Flutter Web engine's sources are in `localhost:<port>` > `lib` > `_engine` >
+`engine`. You can set breakpoints in Dart source files and use the Chrome
+debugger to inspect variables' values.
+
 ## Building CanvasKit
 
 To build CanvasKit locally, you must first set up your gclient config to
@@ -303,12 +335,14 @@ Once you know the version for the Emscripten SDK, change the line in
 
 
 
-[1]: https://github.com/flutter/flutter/wiki/Setting-up-the-Engine-development-environment
-[2]: https://github.com/flutter/flutter/blob/main/lib/web_ui/test/README
-[3]: https://github.com/flutter/engine/blob/main/lib/web_ui/dev/package_lock.yaml
+[1]: https://github.com/flutter/flutter/blob/main/engine/src/flutter/docs/contributing/Setting-up-the-Engine-development-environment.md
+[2]: https://github.com/flutter/flutter/blob/main/engine/src/flutter/lib/web_ui/test/README.md
+[3]: https://github.com/flutter/flutter/blob/main/engine/src/flutter/lib/web_ui/dev/package_lock.yaml
 [4]: https://chrome-infra-packages.appspot.com/p/flutter_internal
 [5]: https://cs.opensource.google/flutter/recipes/+/master:recipes/engine/web_engine.py
 [6]: https://chromium.googlesource.com/chromium/src.git/+/main/docs/cipd_and_3pp.md#What-is-CIPD
+[7]: https://developer.chrome.com/docs/devtools
+[8]: https://developer.chrome.com/docs/devtools/sources
 
 ## Unicode properties