bindings/module_loader library

Lazy, self-contained loader for the minigpu Emscripten glue.

🔴 WHY THIS EXISTS — the glue is a classic (non-MODULARIZE) Emscripten build: its script declares a top-level var Module and keeps writing through that binding for the LIFE of the page (heap growth re-assigns Module["HEAP8"] etc.). Loaded as a plain <script>, that binding is globalThis.Module — a name ANY other classic Emscripten build on the page (miniav_web's audio wasm, for one) also claims. Two claimants and whichever loads second corrupts the first; on a page that never injects the glue at all, Module belongs to someone else entirely and every _mgpu* lookup dies as "func is not a function".

So this loader runs the glue INSIDE A FUNCTION SCOPE — a fixed wrapper in a blob-backed script, called with OUR private object — which turns every top-level var in the glue (Module, HEAP views, runtime state) into a function local. The glue's prelude (var Module = typeof Module != 'undefined' ? Module : {}) sees the parameter and adopts our object; exports land on it; the shared global Module is untouched. Loading uses the browser's script loader rather than eval/Function, so CSP needs blob: but not unsafe-eval. The initialized instance is then published as globalThis.MinigpuModule, which is the ONLY name the Dart bindings read.

Host pages that preload the glue the old way (minigpu_web.loader.js in index.html — gui_bench, minigpu_av, the view example) still work: their glue really does live at globalThis.Module, and _load ADOPTS it as MinigpuModule instead of loading twice (awaiting the loader's in-flight promise when that glue has not run yet).

Properties

isMinigpuModuleLoaded → bool

True once globalThis.MinigpuModule is available.

no setter

Functions

ensureMinigpuModuleLoaded() → Future<void>

Load (or adopt) the minigpu wasm module once. Safe to await repeatedly. Throws on fetch/instantiation failure — callers surface that as "no GPU on this platform" rather than a silent hang — and the next call tries again.

installWebGpuAdapterInfoShim() → void