This PR changes the initialization of a flutter web app to use the ui.webOnlyWarmupEngine API introduced here:

• [web] webOnlyWarmupEngine + js-interop APIs engine#32017

in order to yield full control to the programmer over the initialization of a Flutter Web app.

• Fixes: [web] Let developers control the bootstrap of a Flutter Web application #99773
• Supersedes: [wip] Flutter JS Bootstrap RFC #95379

Currently, Flutter Web apps start as soon as possible, and take over the whole screen. With this change, the startup of an App can be split in three stages (four, if we count the cleanup stage too):

• Injecting the main.dart.js and (optionally) the serviceworker
• Initializing the engine
• Running the flutter app
• Cleaning the app (currently not implemented)

To achieve this, some JS-interop and Promise-wrangling is needed. The new workflow is as follows:

• The user injects flutter.js in their index.html, and once that script is loaded, calls _flutter.loader.loadMainDartJs
• flutter.js injects main.dart.js, and sets up a _flutter.loader.didLoadMainDartJs callback. (This callback must be in a hardcoded location, so Flutter loaded from a script knows where to call)

  • If the callback is not present (old index.html, not using flutter.js):

    • The engine immediately initializes the app, as it used to do earlier. This ensures backwards compatibility.

  • If the callback is present:

    • The engine calls it with an EngineInitializer object that can be used by the programmer.
      • This resolves the promise returned by loadMainDartJs in step 1.
    • From this moment on, the loading of the application is a sequence of Promise-based objects that let the user walk through the three (four) stages described above:

    loadMainDartJs -> EngineInitializer.initializeEngine -> AppRunner.runApp -> AppCleaner.cleanApp (optional)
    

Demo

The new API above allows users to write their own (informative) splash screens, for example:

• https://dit-bootstrap-tests.web.app (red circles should turn green as the app loads. The button only becomes enabled once the app is ready to start. The app only starts when the button is pressed).

Backwards compatibility

This is currently backwards compatible with old versions of index.html. If the flutter init script calls ui.webOnlyWarmUpEngine, it checks if the flutter loader callback is setup or not.

Testing

• Unit tests added to assert the existence and contents of the new flutter.js file.
• Minor updates to existing unit tests that were asserting the contents of the old wrapper script (auto-generated)
• general.shard of tests passes.

Waiting to update this branch with the latest from the engine, to detect potential failures in integration tests between the engine and the framework, even though the engine change should be fully backwards-compatible.

Manual testing

Clone this PR into your flutter/engine fork, and build it.

Clone this PR into your flutter/flutter fork, and ensure that your flutter binary is the one coming from your Github checkout.

With the new version of flutter on your box, you'll be able to create a new app normally by using flutter create. That should come with the new flutter.js and index.html templates.

In order for the flutter_tool to rebuild, you'll need to delete its cache; you can do it with:

rm [YOUR_FLUTTER_CLONE]/bin/cache/flutter_tools.*

Once the engine and the tools are rebuilt, you can just do something similar to:

flutter clean && flutter run --local-engine=host_debug_unopt -d chrome --web-port 7357