cvcGL wasm: the WebAssembly app contract (state shim, FrameYield, cvcgl_wasm_app, glsync)

.github/workflows/ci.yml

@@ -154,6 +154,58 @@ jobs:
           echo "$out"
           exit 1
 
+  # ─────────────── cvcGL browser-side JS (state shim, glsync, serve.py) ───────────────
+  #
+  # webgl_state_shadow.js (the --pre-js cvcgl_wasm_app links into every cvcGL wasm app), the
+  # glsync census and serve.py's flags are plain JS / Python, tested under node against mock
+  # WebGL contexts -- no browser and no wasm build. Only when those files changed: the node
+  # comes from the cvcpkg emsdk bundle (hermetic, no apt), which is a big download.
+  cvcgl-wasm-js:
+    name: cvcGL wasm JS tests
+    runs-on: ubuntu-24.04
+    concurrency:
+      group: ci-${{ github.ref }}-cvcgl-wasm-js
+      cancel-in-progress: true
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Did the browser-side files change?
+        id: paths
+        shell: bash
+        run: |
+          set -euo pipefail
+          if [ "${{ github.event_name }}" = "pull_request" ]; then
+            base="${{ github.event.pull_request.base.sha }}"
+          else
+            base="${{ github.event.before }}"
+          fi
+          run=true
+          if [ -n "$base" ] && [ "$base" != "0000000000000000000000000000000000000000" ] \
+             && git cat-file -e "${base}^{commit}" 2>/dev/null; then
+            if ! git diff --name-only "$base" HEAD -- src/cvcGL/wasm \
+                   src/cvcGL/test/webgl_state_shadow_test.js src/cvcGL/examples/wasm/serve.py \
+                   .github/workflows/ci.yml | grep -q .; then
+              run=false
+            fi
+          fi
+          echo "run=$run" >> "$GITHUB_OUTPUT"
+          echo "browser-side files changed: $run"
+
+      - name: Provision node from the cvcpkg emsdk bundle
+        if: steps.paths.outputs.run == 'true'
+        run: |
+          curl -fsSL https://cvcpkg.org/install.sh | sh
+          export PATH="$HOME/.local/bin:$PATH"
+          cvcpkg install emsdk --platform linux --prefix "$RUNNER_TEMP/emsdk" \
+            --config release --link shared --no-fallback-to-source
+          echo "CVC_EMSDK_DIR=$RUNNER_TEMP/emsdk" >> "$GITHUB_ENV"
+
+      - name: Run the JS tests
+        if: steps.paths.outputs.run == 'true'
+        run: src/cvcGL/wasm/run-js-tests.sh
+
   # ──────────────────────────── Linux packaging ────────────────────────────
   #
   # Mirrors release.yml's linux job exactly, but injects -<sha> into

.github/workflows/publish-cvcgl-wasm.yml

@@ -72,6 +72,10 @@ jobs:
             || { echo "::error::emsdk bundle has no emsdk_env.sh at $EMSDK_DIR"; exit 1; }
           echo "CVC_EMSDK_DIR=$EMSDK_DIR" >> "$GITHUB_ENV"
 
+      - name: cvcGL browser-side JS tests (state shim, glsync, serve.py)
+        # The shim ships in the bundle built below; test it first, with the emsdk's own node.
+        run: src/cvcGL/wasm/run-js-tests.sh
+
       - name: Install the wasm-mt dep closure
         # The same list + flags the nightly installs; libcvc/cvcGL link these. sdl3 backs the
         # cvcGL input/peripheral seam (CVC_ENABLE_SDL): with it in $WASM_DEPS, cvcGL's
@@ -117,6 +121,20 @@ jobs:
           grep -q "find_dependency(SDL3" "$INST/lib/cmake/cvcGL/cvcGLConfig.cmake" \
             || { echo "::error::cvcGL wasm did NOT link SDL3 (find_package(SDL3) failed under emcmake despite sdl3 in \$WASM_DEPS) — the input seam fell back to the VTK interactor"; exit 1; }
           echo "cvcGL wasm: SDL3 input seam ENABLED (find_dependency(SDL3) present)"
+          # cvcgl_wasm_app(): the WebGL state shim and the CMake function that links it must ship,
+          # the config must say this cvcGL is -pthread (MIMALLOC AUTO follows it), and none of the
+          # three CMake files may name a path on this runner (the JS dir is computed from the
+          # installed config's own location).
+          test -f "$INST/share/cvcGL/wasm/webgl_state_shadow.js" \
+            || { echo "::error::cvcGL wasm bundle has no share/cvcGL/wasm/webgl_state_shadow.js"; exit 1; }
+          grep -q "function(cvcgl_wasm_app" "$INST/lib/cmake/cvcGL/cvcGLWasm.cmake" \
+            || { echo "::error::cvcGL wasm bundle has no cvcgl_wasm_app() (lib/cmake/cvcGL/cvcGLWasm.cmake)"; exit 1; }
+          grep -q "CVCGL_WASM_PTHREADS ON" "$INST/lib/cmake/cvcGL/cvcGLConfig.cmake" \
+            || { echo "::error::cvcGLConfig.cmake does not record the -pthread build (CVCGL_WASM_PTHREADS)"; exit 1; }
+          if grep -nF -e "$GITHUB_WORKSPACE" -e "$INST" "$INST"/lib/cmake/cvcGL/cvcGLConfig.cmake \
+               "$INST"/lib/cmake/cvcGL/cvcGLTargets.cmake "$INST"/lib/cmake/cvcGL/cvcGLWasm.cmake; then
+            echo "::error::cvcGL's installed CMake files name a path on this runner (not relocatable)"; exit 1
+          fi
 
       - name: Pack + publish libcvc + cvcgl wasm-mt
         env:
@@ -186,6 +204,9 @@ jobs:
           bash cvcpkg/recipes/cvcgl-examples/build-wasm.sh
           test -f "$EX_INST/share/cvcgl-examples/web/index.html" \
             || { echo "::error::cvcgl-examples wasm gallery missing web/index.html"; exit 1; }
+          # Every gallery demo is a cvcgl_wasm_app: the state shim is in its module JS.
+          grep -q __cvcGlShadow "$EX_INST/share/cvcgl-examples/web/nav_city_drive/nav_city_drive.js" \
+            || { echo "::error::nav_city_drive.js has no WebGL state shim (cvcgl_wasm_app not applied)"; exit 1; }
           echo "=== gallery web/ contents ==="; ls -la "$EX_INST/share/cvcgl-examples/web" | head -20
           cvcpkg pack cvcpkg/recipes/cvcgl-examples --from-prefix "$EX_INST" \
             --platform wasm-mt --config release --link static \

bindings/pycvc/pycvc_gl.i

@@ -1694,6 +1694,9 @@ def _typed_node(sg, name):
 %pythonappend cvc::gl::SceneRenderer::SceneRenderer %{
     if args: self._pycvc_scene = args[0]
 %}
+// FrameYield: SceneRenderer / ViewportManager::setFrameYield take it. At namespace
+// scope, so it must be seen before either header (SWIG does not follow #include).
+%include "cvc/gl/FrameYield.h"
 %include "cvc/gl/SceneRenderer.h"
 
 %extend cvc::gl::SceneRenderer {

bindings/pycvc/wasm/link-host.sh

@@ -81,6 +81,13 @@ fi
 
 printf "Module.preRun=Module.preRun||[];Module.preRun.push(function(){ENV.PYTHONHOME='/py';%sENV.PYTHONDONTWRITEBYTECODE='1';});\n" "$VTK_PYPATH" > "$OUT/pre.js"
 
+# TODO(cvcGL wasm app contract, docs/CVCGL_WASM.md): this host is node-only today, so it links
+# neither of cvcGL's browser-side speedups. When it gets a browser page, that link must add
+#   --pre-js "$INST/share/cvcGL/wasm/webgl_state_shadow.js"   (the WebGL state shim), and
+#   -sMALLOC=mimalloc                                         (on a wasm-mt / -pthread build only)
+# -- what cvcgl_wasm_app() does for a CMake app. It links no -sASYNCIFY, so FrameYield and
+# -sASYNCIFY_IGNORE_INDIRECT do not apply until it does.
+
 "$EMCC" "$SRC/bindings/pycvc/wasm/pycvc_host.cpp" "$GEN" \
     -std=c++17 -O1 -DPYCVC_EMBED_NUMPY ${VTK_DEF[@]+"${VTK_DEF[@]}"} -I "$PYINC" \
     -Wl,--allow-multiple-definition \

cvcpkg/recipes/cvcgl-cuda/recipe.yaml

@@ -4,7 +4,8 @@ recipe:
   upstream_version: "3.4.0"
   # Reset to 1 for the 3.3.0 upstream version: cvc_revision counts
   # revisions OF an upstream version, so a version bump restarts it.
-  cvc_revision: 1
+  # Bumped 1 -> 3 (2 is #522's): ships share/cvcGL/ (the wasm state shim), as cvcgl 3.4.0+cvc.18.
+  cvc_revision: 3
   maintainer: "cvcpkg group"
   maintainer_email: "info@cvcpkg.org"
   maintainer_url: "https://cvcpkg.org"
@@ -74,6 +75,7 @@ package:
     - lib/libcvcGL*
     - lib/cmake/cvcGL/
     - include/cvc/gl/
+    - share/cvcGL/
   cmake_packages:
     - name: cvcGL
       targets:

cvcpkg/recipes/cvcgl-examples/build.sh

@@ -97,6 +97,12 @@ cmake --install "$CVC_BUILD_DIR" --component cvcgl-examples
 install -d "$CVC_INSTALL_DIR/share/cvcgl-examples"
 install -m 755 "$CVC_SOURCE_DIR/src/cvcGL/examples/wasm/serve.py" \
   "$CVC_INSTALL_DIR/share/cvcgl-examples/serve.py"
+# The Firefox WebGL sync census (a dev tool, off unless serve.py --glsync): serve.py finds it in
+# devtools/ next to itself. The launcher below does not pass --glsync, so pages are unchanged.
+install -d "$CVC_INSTALL_DIR/share/cvcgl-examples/devtools"
+install -m 644 "$CVC_SOURCE_DIR/src/cvcGL/wasm/devtools/glsync.js" \
+  "$CVC_SOURCE_DIR/src/cvcGL/wasm/devtools/GLSYNC.md" \
+  "$CVC_INSTALL_DIR/share/cvcgl-examples/devtools/"
 
 cat > "$CVC_INSTALL_DIR/bin/cvcgl-examples-web" <<'LAUNCHER'
 #!/usr/bin/env bash

cvcpkg/recipes/cvcgl-examples/recipe.yaml

@@ -17,7 +17,8 @@ recipe:
   # Bumped 2 -> 3: build-wasm.sh no longer forces state_exec OFF (the
   # CVC_STATE_EXEC option is gone; state_exec is always built), so the wasm
   # gallery carries the program lanes that Ariadne apps run on.
-  cvc_revision: 3
+  # Bumped 3 -> 17 (15 published, 16 is #522's): every wasm demo is a cvcgl_wasm_app; ships glsync.
+  cvc_revision: 17
   maintainer: "cvcpkg group"
   maintainer_email: "info@cvcpkg.org"
   maintainer_url: "https://cvcpkg.org"

cvcpkg/recipes/cvcgl/recipe.yaml

@@ -69,7 +69,8 @@ recipe:
   # _rect partial texture uploads, caster-aware shadow baking (setCastsShadow), and the cheaper
   # scene-bounds walk deferred under hidden chrome. ABI-stale: SceneGraph/GraphicsNode/
   # NullGraphicNode layouts changed, so the published +cvc.14 must not be mixed with this build.
-  cvc_revision: 15
+  # Bumped 15 -> 18 (16 published, 17 is #522's): cvcgl_wasm_app(), the WebGL state shim, FrameYield.
+  cvc_revision: 18
   maintainer: "cvcpkg group"
   maintainer_email: "info@cvcpkg.org"
   maintainer_url: "https://cvcpkg.org"
@@ -153,6 +154,10 @@ package:
     - lib/cvcGL*
     - lib/cmake/cvcGL/
     - include/cvc/gl/
+    # The browser-side half of cvcGL: webgl_state_shadow.js, which cvcgl_wasm_app() (from
+    # lib/cmake/cvcGL/cvcGLWasm.cmake) links into a wasm app as a --pre-js. Installed on every
+    # platform so the layout is uniform; only Emscripten consumers use it.
+    - share/cvcGL/
   cmake_packages:
     - name: cvcGL
       targets: