modifying injector to always inject client and introduce runMainAtStart flag

Author: jyameo

dwds/CHANGELOG.md

@@ -1,5 +1,6 @@
-## 24.3.11-wip
+## 24.3.11
 
+- Changed DWDS to always inject the client and use `runMainAtStart` flag to control whether main() execution is deferred or runs immediately.
 - Added WebSocket-based hot reload support: `reloadSources` in `ChromeProxyService` and `DevHandler` now handle hot reload requests and responses over WebSockets.
 - Refactored the injected client to use a reusable function for handling hot reload requests and responses over WebSockets.
 

dwds/lib/dart_web_debug_service.dart

@@ -66,7 +66,7 @@ class Dwds {
     required Stream<BuildResult> buildResults,
     required ConnectionProvider chromeConnection,
     required ToolConfiguration toolConfiguration,
-    bool injectDebuggingSupportCode = true,
+    bool runMainAtStart = false,
   }) async {
     globalToolConfiguration = toolConfiguration;
     final debugSettings = toolConfiguration.debugSettings;
@@ -120,7 +120,7 @@ class Dwds {
 
     final injected = DwdsInjector(
       extensionUri: extensionUri,
-      injectDebuggingSupportCode: injectDebuggingSupportCode,
+      runMainAtStart: runMainAtStart,
     );
 
     final devHandler = DevHandler(

dwds/lib/src/handlers/injector.dart

@@ -30,25 +30,23 @@ const _clientScript = 'dwds/src/injected/client';
 /// to include the injected DWDS client, enabling debugging capabilities
 /// and source mapping when running in a browser environment.
 ///
-/// The `_injectDebuggingSupportCode` flag determines whether debugging-related
-/// functionality should be included:
-/// - When `true`, the DWDS client is injected, enabling debugging features.
-/// - When `false`, debugging support is disabled, meaning the application will
-///   run without debugging.
+/// The `_runMainAtStart` flag determines whether main() execution should be
+/// deferred or run immediately:
+/// - When `true`, main() is executed immediately when the app is loaded.
+/// - When `false`, main() execution is deferred, allowing for setup or
+///   debugging initialization before main() runs.
 ///
 /// This separation allows for scenarios where debugging is not needed or
 /// should be explicitly avoided.
 class DwdsInjector {
   final Future<String>? _extensionUri;
   final _devHandlerPaths = StreamController<String>();
   final _logger = Logger('DwdsInjector');
-  final bool _injectDebuggingSupportCode;
+  final bool _runMainAtStart;
 
-  DwdsInjector({
-    Future<String>? extensionUri,
-    bool injectDebuggingSupportCode = true,
-  }) : _extensionUri = extensionUri,
-       _injectDebuggingSupportCode = injectDebuggingSupportCode;
+  DwdsInjector({Future<String>? extensionUri, bool runMainAtStart = true})
+    : _extensionUri = extensionUri,
+      _runMainAtStart = runMainAtStart;
 
   /// Returns the embedded dev handler paths.
   ///
@@ -110,17 +108,15 @@ class DwdsInjector {
           await globalToolConfiguration.loadStrategy.trackEntrypoint(
             entrypoint,
           );
-          // If true, inject the debugging client and hoist the main function
-          // to enable debugging support.
-          if (_injectDebuggingSupportCode) {
-            body = await _injectClientAndHoistMain(
-              body,
-              appId,
-              devHandlerPath,
-              entrypoint,
-              await _extensionUri,
-            );
-          }
+          // Always inject the debugging client and hoist the main function.
+          body = await _injectClientAndHoistMain(
+            body,
+            appId,
+            devHandlerPath,
+            entrypoint,
+            await _extensionUri,
+            _runMainAtStart,
+          );
           body += await globalToolConfiguration.loadStrategy.bootstrapFor(
             entrypoint,
           );
@@ -156,6 +152,7 @@ Future<String> _injectClientAndHoistMain(
   String devHandlerPath,
   String entrypointPath,
   String? extensionUri,
+  bool runMainAtStart,
 ) async {
   final bodyLines = body.split('\n');
   final extensionIndex = bodyLines.indexWhere(
@@ -174,6 +171,7 @@ Future<String> _injectClientAndHoistMain(
     devHandlerPath,
     entrypointPath,
     extensionUri,
+    runMainAtStart,
   );
   result += '''
   // Injected by dwds for debugging support.
@@ -205,6 +203,7 @@ Future<String> _injectedClientSnippet(
   String devHandlerPath,
   String entrypointPath,
   String? extensionUri,
+  bool runMainAtStart,
 ) async {
   final loadStrategy = globalToolConfiguration.loadStrategy;
   final buildSettings = loadStrategy.buildSettings;
@@ -223,6 +222,7 @@ Future<String> _injectedClientSnippet(
       'window.\$dartEmitDebugEvents = ${debugSettings.emitDebugEvents};\n'
       'window.\$isInternalBuild = ${appMetadata.isInternalBuild};\n'
       'window.\$isFlutterApp = ${buildSettings.isFlutterApp};\n'
+      'window.\$runMainAtStart = $runMainAtStart;\n'
       '${loadStrategy is DdcLibraryBundleStrategy ? 'window.\$hotReloadSourcesPath = "${loadStrategy.hotReloadSourcesUri.toString()}";\n' : ''}'
       '${loadStrategy.loadClientSnippet(_clientScript)}';