WebAssembly: Evolving the qtloader.js API

What is the benefit? Why is this valuable?

The target here is to make qtloader.js more effective and see if stepwise instantiation of the wqasm app could be done, resultiung in faster startup times.

What are common use cases?

Qtoader.js is used by default by all wasm apps and that functionality is needed by wasm apps to load, it is however optional and can be replaced with apps own implementation.

Technical information

qtloader.js

qtloader.js provides a JavaScript API for loading and managing Qt-based applications

App Structure

Qt for WebAssembly based applications are hosted in a web environment, and need some supporting code. This will typically consist of:

app.html
qtloader.js
app.js

Where app.js provides the emscripten runtime, qtloader.js provides Qt's API for loading applications, and app.html provides a minimal html structure for displaying an app.

API Design

There are currently no source compatibility guarantees for qtloader.js. While we want to provide a stable API it is realistic to plan for iterative development and API overhauls.

A key design tenet for qtloader.js is that the managed application is a web page component, i.e. it can live somewhere in the html hierarchy and does not attempt to own the entire page. (the default app.html file does make it use the entire viewport, but can/should be replaced as needed.)

API areas for qtloader.js:
 * Webassembly/WebGL support detection.
 * App lifecycle management
 * Canvas and Container element management
 * Command line and environment variable handling
 * shared/dynamic builds: plugin and .wasm side module management.
 * Additional run-time API where needed (e.g. canvasResized)

Misc notes and open questions:
 * Not using qtloader.js is also supported: we'll document what the Qt requirements are.
 * Some emscripten build options (set by Qt) changes what the emscripten run-time API looks like, qtloader.js abstracts over this.
 * Which JavaScript version should we target? E.g. an isWebAssemblySupported() API does not make sense if the browser can't parse the .js file.
 * The next version of qtloader.js should use Emscripten's Modularize[DONE (6.2)].

Application State and Lifecycle Management

Intuitively, the application has two main states:
 * loading (downloading/compiling/instantiating wasm)
 * running

However: the state transitions are not always clear, and there are additional (sub) states:
 * loading
 ** created (the qtloader.js object has been created)
 ** loading (actually downloading, etc.)
 * running: when does the transition to this state happen?
 ** WebAssembly.instantiate returns an instance (we can call its exported functions at this point)
 ** Emscripten has finished initializing its runtime, and has run C++ global constructors
 ** The QApplication object has been created (we can call qt functions at this point)
 ** The application has produced the first frame (we can hide the loading screen and make the canvas visible now)
 * Exited: the application can exit
 ** clean exit with exit code
 ** crash/abort/exception

Canvas and Container element

Reading

Client-side API Design Principles: [[https://w3ctag.github.io/design-principles]|https://w3ctag%5C.github%5C.io/design-principles%5C%5D%5C%5D]
 Writing Promise-Using Specifications: [[https://www.w3.org/2001/tag/doc/promises-guide]