feat(wasm-eh): migrate the WASM build to native wasm exceptions (+ 3D viewer default-on)

Replace the legacy Emscripten JS-exceptions model with native wasm-EH (legacy
encoding) across the whole build, keeping Asyncify coroutines working via a
from-source Binaryen --hoist-cpp-catches pre-pass. Net result: native-EH is the
only build mode, the 3D viewer is on by default, and pcbnew shrinks substantially.

Highlights:
- Binaryen submodule everywhere + --hoist-cpp-catches integration in apply-asyncify;
  post-link Asyncify covers every app wasm (not just standalone test wasm).
- Build deps (incl. OpenCASCADE without OCC_CONVERT_SIGNALS) and all KiCad apps
  with -fwasm-exceptions; emscripten_sleep added to the post-link asyncify-imports.
- libcontext fiber entry wired under native exceptions; while-loop main loop +
  currData shim injected into all wx apps.
- Native-EH collab apply fixed: DEBUG-define the embind TU + match all out-of-CMake
  C++ TUs' ABI flags to the core, fixing the vtable-layout skew / mis-dispatch.
- 3D viewer enabled by default (real raytracer linked, not the stub).
- Retire the EH-spike scaffolding; flip the asyncify-races ablation pins to
  shim-redundancy pins (native-EH stays clean with the legacy shims ablated).
- Fix the asyncify-races quiescence check to not require Asyncify.currData==0:
  under the native-EH per-frame-yield top loop the main stack is asyncify-suspended
  every frame, so currData legitimately churns (a freed-but-not-yet-nulled buffer,
  not a leak). Refresh the pcbnew toolbar screenshot baseline for the new kicad.
- CI: drop the obsolete binaryen_version input/env (the build uses the binaryen
  submodule fork's wasm-opt, not a version download); key the wasm-output cache on
  the binaryen submodule SHA instead.

Bumps the wxwidgets + binaryen submodules to their squashed feature commits.

Validated green: all 7 apps native-EH (real 3D in pcbnew); KiCad e2e 63/63
Firefox + Chromium (3D viewer renders); wx 336; coroutine 34/34 both engines;
asyncify 7/7 both engines.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

docker/Dockerfile

@@ -25,10 +25,13 @@ RUN apt-get update && apt-get install -y \
     unzip \
     && rm -rf /var/lib/apt/lists/*
 
-# Install emsdk from source (same approach as scripts/setup-emsdk.sh)
-# EMSCRIPTEN_VERSION must match scripts/common/versions.sh
-ARG EMSCRIPTEN_VERSION=4.0.2
-RUN git clone https://github.com/emscripten-core/emsdk.git /emsdk \
+# Install emsdk from source (same approach as scripts/setup-emsdk.sh). The version is the SINGLE
+# source of truth in scripts/common/versions.sh, passed in as a build arg by docker/build.sh (via the
+# compose build.args). Do NOT hardcode it here — fail fast if the arg is missing so a stale image can
+# never silently use the wrong toolchain.
+ARG EMSCRIPTEN_VERSION
+RUN test -n "${EMSCRIPTEN_VERSION}" || { echo "EMSCRIPTEN_VERSION build-arg required (scripts/common/versions.sh)"; exit 1; }; \
+    git clone https://github.com/emscripten-core/emsdk.git /emsdk \
     && cd /emsdk \
     && ./emsdk install ${EMSCRIPTEN_VERSION} \
     && ./emsdk activate ${EMSCRIPTEN_VERSION}

docker/build.sh

@@ -22,7 +22,7 @@
 #
 # The build is split into two phases:
 # 1. Docker: Compile KiCad to WASM (without asyncify)
-# 2. Host: dyncall shims + finalize + asyncify + -O2 (Binaryen via get-wasm-opt.sh)
+# 2. Host: dyncall shims + finalize + asyncify + -O2 (Binaryen submodule via build-wasm-opt.sh)
 #
 # KICAD_PIPELINE=1 (multi-app builds only): run phase 2 of each app in the
 # background while the next app compiles in the container. wasm-opt is
@@ -49,6 +49,11 @@ source "$(dirname "$0")/../scripts/common/logging.sh"
 # Build-progress markers (parsed by scripts/build-monitor.sh).
 source "$(dirname "$0")/../scripts/common/stages.sh"
 
+# Pinned toolchain version (single source of truth). Exported so the compose build.args can pass it
+# into the Docker image's emsdk install — bumping the toolchain is then a one-line edit in versions.sh.
+source "$(dirname "$0")/../scripts/common/versions.sh"
+export EMSCRIPTEN_VERSION
+
 set -e
 
 # Emit a completion/failure marker no matter how the build ends, so the monitor
@@ -120,7 +125,7 @@ echo "Building app: ${APP_NAME}"
 #   --postprocess-only   — only the host post-process (dyncall + finalize +
 #                          asyncify + wasm-opt -O$BINARYEN_OPT_LEVEL) on the
 #                          existing output/ base wasm; NO container needed
-#                          (get-wasm-opt.sh self-provisions Binaryen).
+#                          (build-wasm-opt.sh self-provisions the Binaryen submodule).
 # Extracted here so they are NOT forwarded to the inner build-<app>.sh scripts.
 PHASE="both"
 _FILTERED=()
@@ -143,8 +148,9 @@ fi
 # which is pure host work on the already-built base wasm in output/.
 if [[ "$PHASE" != "postprocess" ]]; then
 
-# Start container if not running
-docker compose -f docker/docker-compose.yml up -d
+# Start container if not running. --build so the image is rebuilt when the pinned EMSCRIPTEN_VERSION
+# (build-arg from versions.sh) changes; Docker layer-caches it to a near no-op when unchanged.
+docker compose -f docker/docker-compose.yml up -d --build
 
 # Sync source code to container volume (fixes macOS Docker VirtioFS issues)
 # Use --checksum to only transfer files with different CONTENT, not timestamps.
@@ -217,7 +223,7 @@ compile_app() {
     # emsdk_env.sh, so the build shell would lack emcc/embuilder on PATH. Setting
     # EMSDK lets scripts/common/env.sh source /emsdk/emsdk_env.sh and activate the toolchain.
     docker compose -f docker/docker-compose.yml exec -e EMSDK=/emsdk \
-        -e BUILD_3D_VIEWER="${BUILD_3D_VIEWER:-OFF}" \
+        -e BUILD_3D_VIEWER="${BUILD_3D_VIEWER:-ON}" \
         kicad-wasm-builder \
         "/workspace/scripts/kicad/build-${app}.sh" "${ARGS[@]}"
 
@@ -266,6 +272,8 @@ postprocess_app() {
 
     # Apply asyncify transformation on host. The converter is a synchronous node
     # CLI built with ASYNCIFY=0, so asyncify is unnecessary and would be wrong.
+    # apply-asyncify always runs the --hoist-cpp-catches pass FIRST (native wasm-EH is the only build
+    # mode) so Asyncify can suspend from inside C++ catch arms, then asyncify + removelist + -O2.
     if [ "$app" != "sym_convert" ]; then
         kw_stage asyncify
         ./scripts/common/apply-asyncify.sh "${out_dir}/${app}.wasm" "${out_dir}/${app}.wasm"
@@ -349,7 +357,7 @@ elif [[ "$PHASE" == "postprocess" ]]; then
     # wasm (no container). Parallelize across apps when pipelining.
     if [[ "${KICAD_PIPELINE:-0}" == "1" ]] && [ "$TOTAL_APPS" -gt 1 ]; then
         mkdir -p "$PIPELINE_LOG_DIR"
-        ./scripts/common/get-wasm-opt.sh >/dev/null  # pre-warm Binaryen once
+        ./scripts/binaryen-hoist-pass/build-wasm-opt.sh >/dev/null  # pre-warm Binaryen (submodule) once
         _install_pipeline_trap
         for app in "${APPS[@]}"; do
             pipeline_postprocess "$app"
@@ -364,9 +372,9 @@ elif [[ "${KICAD_PIPELINE:-0}" == "1" ]] && [ "$TOTAL_APPS" -gt 1 ]; then
     # both, pipelined: overlap app[i+1]'s container compile with app[i]'s host
     # post-process (KICAD_PIPELINE=1).
     mkdir -p "$PIPELINE_LOG_DIR"
-    # Pre-warm the Binaryen download once — two concurrent postprocesses racing
-    # the first download would collide on the extract/mv.
-    ./scripts/common/get-wasm-opt.sh >/dev/null
+    # Pre-build the Binaryen submodule once — two concurrent postprocesses racing
+    # the first from-source build would collide.
+    ./scripts/binaryen-hoist-pass/build-wasm-opt.sh >/dev/null
     _install_pipeline_trap
     idx=1
     for app in "${APPS[@]}"; do

docker/docker-compose.yml

@@ -3,6 +3,11 @@ services:
     build:
       context: ..
       dockerfile: docker/Dockerfile
+      args:
+        # Single source of truth: scripts/common/versions.sh, exported into the env by the scripts
+        # that drive compose (docker/build.sh, docker/shell.sh). No default -> the Dockerfile fails
+        # fast if it's unset, so the image can't be built against the wrong toolchain.
+        EMSCRIPTEN_VERSION: ${EMSCRIPTEN_VERSION:?source scripts/common/versions.sh before docker compose}
     # Container name is auto-generated with project prefix (set in build.sh)
 
     # Resource limits. Defaults are sized for a dev Mac (Docker Desktop VM).

docker/shell.sh

@@ -4,6 +4,10 @@ set -e
 
 cd "$(dirname "$0")/.."
 
+# Pinned toolchain version (single source of truth) -> compose build.args needs it in the env.
+source "$(dirname "$0")/../scripts/common/versions.sh"
+export EMSCRIPTEN_VERSION
+
 # Start container if not running
 docker compose -f docker/docker-compose.yml up -d