feat: make createNamespace sync by moving it into VtkWASMLoader

- this allows one to first load a VTK.wasm binary, then create a namespace
 using said binary.
- see examples/js/simple-app/src/main.js for usage

Author: jspanchu

docs/guide/js/bundler.md

@@ -4,7 +4,7 @@ Modern web development rely on package manager to bring project dependencies. Th
 
 ## Project setup
 
-In the simple example we are going to use [Vite](https://vite.dev/) with Vanilla JavaScript. The full code is available for reference [here](https://github.com/Kitware/vtk-wasm/tree/main/examples/js/simple-app).
+In the simple example we are going to use [Vite](https://vite.dev/) with Vanilla JavaScript. The full code is available for reference [here](https://github.com/Kitware/vtk-wasm/tree/main/examples/js/simple-app). Please note that you should use a concrete version, or "latest" for the `@kitware/vtk-wasm` package. Here, it uses a relative path to the `vtk-wasm` project root, so that the in source documentation stays relevant.
 
 ::: code-group
 <<< ../../../examples/js/simple-app/package.json

examples/js/simple-app/package-lock.json

@@ -12,6 +12,6 @@
     "vite": "^6.3.5"
   },
   "dependencies": {
-    "@kitware/vtk-wasm": "latest"
+    "@kitware/vtk-wasm": "file:../../.."
   }
 }

examples/js/simple-app/package.json

@@ -1,8 +1,8 @@
 import "./style.css";
-import { createNamespace } from "@kitware/vtk-wasm/vtk";
+import { VtkWASMLoader } from "@kitware/vtk-wasm/vtk";
 import { buildWASMScene } from "./example";
 
-const VTK_WASM_TARBALL_URL = "https://gitlab.kitware.com/api/v4/projects/13/packages/generic/vtk-wasm32-emscripten/9.5.20251215/vtk-9.5.20251215-wasm32-emscripten.tar.gz";
-createNamespace(VTK_WASM_TARBALL_URL).then((vtk) => {
-  buildWASMScene(vtk, "#app > canvas", "This scene passes the VTK.wasm bundle from GitLab registry to createNamespace()");
-});
+const loader = new VtkWASMLoader();
+await loader.load("https://gitlab.kitware.com/api/v4/projects/13/packages/generic/vtk-wasm32-emscripten/9.5.20251215/vtk-9.5.20251215-wasm32-emscripten.tar.gz");
+let vtk = loader.createNamespace();
+buildWASMScene(vtk, "#app > canvas", "This scene passes the VTK.wasm bundle from GitLab registry to createNamespace()");

examples/js/simple-app/src/main.js

@@ -1,6 +1,7 @@
 export default {
   base: "./",
   build: {
+    target: 'esnext',
     outDir: "../../../docs/public/demo/simple-app",
     emptyOutDir: true,
   },

examples/js/simple-app/vite.config.js

@@ -13,14 +13,9 @@ import { createInstantiatorProxy } from "./core/proxy";
  * @returns the vtk namespace for creating VTK objects.
  */
 export async function createNamespace(url, config = {}, wasmBaseName = "vtk") {
-  const vtkProxyCache = new WeakMap();
-  const idToRef = new Map();
-
   const loader = new VtkWASMLoader();
   await loader.load(url || "loaded-module", config, wasmBaseName);
-  const wasm = loader.createStandaloneSession();
-
-  return createInstantiatorProxy(wasm, vtkProxyCache, idToRef);
+  return loader.createNamespace();
 }
 
 /**
@@ -33,18 +28,20 @@ export async function createNamespace(url, config = {}, wasmBaseName = "vtk") {
  *  - data-config="{ rendering: 'webgl|webgpu', exec: 'sync|async' }" json config for
  *    WASM module configuration.
  */
-const { promise, resolve, reject } = createFuture();
-const script = document.querySelector("#vtk-wasm");
-if (script) {
-  const url = script.dataset.url || ".";
-  const config = JSON.parse(script.dataset.config || "{}");
-  window.vtkReady = promise;
-  createNamespace(url, config)
-    .then((vtk) => {
-      window.vtk = vtk;
-      resolve(vtk);
-    })
-    .catch(reject);
-} else {
-  reject("Automatic VTK namespace initialization is disabled because no <script id=\"vtk-wasm\"> tag was found. See https://kitware.github.io/vtk-wasm/guide/js/plain.html#defer-wasm-loading-with-annotation'");
+if (typeof window !== "undefined") {
+  const script = document.querySelector("#vtk-wasm");
+  if (script) {
+    const { promise, resolve, reject } = createFuture();
+    const url = script.dataset.url || ".";
+    const config = JSON.parse(script.dataset.config || "{}");
+    window.vtkReady = promise;
+    createNamespace(url, config)
+      .then((vtk) => {
+        window.vtk = vtk;
+        resolve(vtk);
+      })
+      .catch(reject);
+  }
 }
+
+export { VtkWASMLoader } from "./wasmLoader";

src/standalone.js

@@ -6,6 +6,7 @@ import { createRemoteSession } from "./core/sessionFactory";
 import { createFuture } from "./core/future";
 import { createBlobURL, disposeBlobURL } from "./core/blobURL";
 import { convertToObj, convertToStr } from "./core/stateDecorators";
+import { createInstantiatorProxy } from "./core/proxy";
 
 /**
  * VtkWASMLoader type definition
@@ -60,12 +61,12 @@ export class VtkWASMLoader {
       this.#pendingLoad = promise;
 
       // wait for wasm script to load if any (first priority)
-      if (!window.createVTKWASM) {
+      if (typeof window !== 'undefined' && !globalThis.createVTKWASM) {
         await loadWebAssemblyModuleFromExistingScript(wasmBaseName);
       }
 
       let wasmFile = null;
-      if (!window.createVTKWASM) {
+      if (typeof window !== 'undefined' && !globalThis.createVTKWASM) {
         if (isGzipBundle(wasmBaseURL)) {
           let gzipArrayBuffer;
           let javaScriptBlobURL = null;
@@ -101,8 +102,8 @@ export class VtkWASMLoader {
             if (scriptURL !== null) {
               await loadWebAssemblyModuleFromScript(scriptURL);
             }
-            // if window.createVTKWASM is still not defined, try legacy loader
-            if (!window.createVTKWASM) {
+            // if globalThis.createVTKWASM is still not defined, try legacy loader
+            if (!globalThis.createVTKWASM) {
               const legacyScriptURL = await createScriptURL(wasmBaseURL, null, null, true);
               await loadWebAssemblyModuleFromScript(legacyScriptURL);
             }
@@ -115,9 +116,9 @@ export class VtkWASMLoader {
       }
 
       // Load WASM
-      if (window.createVTKWASM) {
+      if (globalThis.createVTKWASM) {
         try {
-          this.#wasmInstance = await window.createVTKWASM(createEmscriptenConfig(this.#config, wasmFile));
+          this.#wasmInstance = await globalThis.createVTKWASM(createEmscriptenConfig(this.#config, wasmFile));
         } catch (e) {
           reject(e);
           this.#pendingLoad = null;
@@ -126,7 +127,7 @@ export class VtkWASMLoader {
         this.#loaded = true;
         resolve();
         this.#pendingLoad = null;
-      } else if (window.createVTKWasmSceneManager) {
+      } else if (globalThis.createVTKWasmSceneManager) {
         // Legacy API
         this.#wasmInstance = null;
         this.#loaded = true;
@@ -153,6 +154,13 @@ export class VtkWASMLoader {
     }
   }
 
+  createNamespace() {
+    const vtkProxyCache = new WeakMap();
+    const idToRef = new Map();
+    const wasm = this.createStandaloneSession();
+    return createInstantiatorProxy(wasm, vtkProxyCache, idToRef);
+  }
+
   /**
    * Create a new remote session and return it regardless of WASM version.
    *