pcbjam/docs/wasm-exceptions-experiment.md

Experiment: native wasm exceptions (-fwasm-exceptions) to shrink the asyncify/-O2 critical path

Status: PARKED (2026-06-11). Compiles and links end-to-end, but blocked by an LLVM codegen bug in emscripten 4.0.2 — see "The blocker" below. The code changes were tried locally and then dropped; the full patch is preserved in the appendix of this doc, together with everything needed to resume.

Correction 2026-06-22 — see docs/features/wasm-exceptions/06-spike-plan.md. This experiment switched to -sWASM_LEGACY_EXCEPTIONS=0 (exnref) to dodge the legacy-encoding parse failure — but that is a dead end: Binaryen's Asyncify cannot instrument try_table/exnref in any released version (incl. v130), so an exnref build would die at the --asyncify step even after the br_table bug is fixed. Resume with =1 (legacy), not =0. The legacy parse failure is almost certainly an em-4.0.2 LLVM-codegen artifact; the fix is the emsdk/LLVM bump, not the encoding switch.

Why this matters

After the 3.3x CI win (see ci-build-slowness-findings.md), the critical path of the full build is pcbnew's host-side wasm-opt chain: asyncify ~5 min + -O2 ~52 min (self-built Binaryen v130 on the Hetzner ccx53). That -O2 time is a direct function of how big the asyncified module is — and the module is big because of how exceptions work.

Emscripten's default JS-based exception handling routes every potentially-throwing call that appears inside a try/catch through a JavaScript invoke_* trampoline. Asyncify must treat every JS round-trip as a potential suspension point, so in an exception-heavy codebase (KiCad + OpenCASCADE + wxWidgets) it ends up instrumenting nearly every function: pcbnew is 338 MB pre--O2.

Native wasm exceptions (-fwasm-exceptions) keep throw/catch entirely inside wasm:

• no invoke_* trampolines, no dynCall machinery (verified gone in the experiment),
• asyncify's instrumentation set collapses to the genuinely-suspending call graph,
• raw linked pcbnew.wasm measured at 92 MB (vs 338 MB) before any wasm-opt pass.

Expected payoff: a several-fold reduction in the asyncify + -O2 wall time on the critical path, plus smaller shipped binaries.

Browser support is not a concern: Chrome 95+, Firefox 100+, Safari 15.2+.

What it takes (no KiCad C++ changes)

Pure compile/link-flag change. The one hard rule: every C++ object in the link must agree on the EH model — deps (boost, anything with setjmp like cairo), wxWidgets, and all KiCad targets. The working flag set, threaded through every compile AND link:

-fwasm-exceptions -sSUPPORT_LONGJMP=wasm -sWASM_LEGACY_EXCEPTIONS=0

The appendix below contains the full plumbing as a patch, gated behind KICAD_WASM_EH=1 (default 0 = byte-identical to today): scripts/common/env.sh, scripts/deps/build-boost.sh, scripts/deps/build-cairo.sh, scripts/build-wxuniversal-wasm.sh, scripts/kicad/build-kicad-target.sh, and docker/build.sh (env passthrough into the container). Save the appendix diff to a file and git apply it to restore.

Why each flag, and the failures that taught us (in order hit)

1. -fwasm-exceptions alone fails immediately: harfbuzz (C, uses setjmp) dies with clang: error: invalid argument '-fwasm-exceptions' not allowed with '-enable-emscripten-sjlj'. JS-based setjmp/longjmp and wasm EH can't mix → add -sSUPPORT_LONGJMP=wasm to every compile.
2. Stale deps bite at link: pcbnew link failed with undefined symbol: emscripten_longjmp, traced via llvm-nm to libcairo.a (its png path uses setjmp/longjmp). The deps scripts skip-if-stamped, so flag changes do NOT trigger rebuilds — rm build-wasm/stamps/cairo.stamp (and any other C dep with sjlj) and rebuild. A full --clean deps build is the safe path.
3. wasm-emscripten-finalize / wasm-opt -all parse failure: [parse exception: popping from empty stack] on the linked module, with both the emsdk-bundled binaryen and official v130. emscripten 4.0.2 defaults WASM_LEGACY_EXCEPTIONS=true (the old, pre-standard exnref-less encoding) → add -sWASM_LEGACY_EXCEPTIONS=0 (it's a [compile+link] setting — must be on every compile too, full rebuild).

The blocker: LLVM codegen bug in emscripten 4.0.2

With all three flags and a fully clean rebuild, pcbnew compiles and links (92 MB module, no invoke_*/dynCall), but finalize still fails with the same parse exception — and this time Binaryen is not at fault. Validating the raw module with V8 itself (container node 22.16, node --experimental-wasm-exnref, WebAssembly.compile) gives the definitive error:

Compiling function #96546:"ShapeUpgrade_SplitSurface::Build(bool)" failed:
br_table: label arity inconsistent with previous arity 0 @+52067104

The clang/LLVM shipped in emscripten 4.0.2 emits an invalid br_table instruction (branch targets with mismatched stack arity) in OpenCASCADE code when compiling under wasm EH. The module is malformed at the source; no Binaryen version or flag can fix it. Latest Binaryen release is still v130, so there is no newer tarball to try either.

How to resume

1. Bump ARG EMSCRIPTEN_VERSION=4.0.2 in docker/Dockerfile — emsdk 5.0.7 (latest 5.x, conservative) or 6.0.0 — to pick up a newer LLVM with the br_table fix. Expect ~2.5–3h for image + full clean deps/wx/kicad rebuild locally.
2. git apply the patch from the appendix, then KICAD_WASM_EH=1 BINARYEN_VERSION=130 ./docker/build.sh pcbnew --build-deps -j 8 (use a separate COMPOSE_PROJECT_NAME to keep the main build volume intact).
3. If finalize + asyncify + -O2 succeed: measure the wasm-opt chain vs the current 5 min + 52 min, then a small Hetzner repro (never all for experiments), then full e2e.
4. e2e audit required even if green: asyncify cannot suspend from inside a catch block (binaryen issue #4470). Any KiCad path that calls a suspending function (file dialogs, sleeps, network) inside a catch handler will trap. Build once with -sASYNCIFY_ASSERTIONS / asyncify-asserts and exercise the e2e suite to flush these out before adopting.

Risk notes

• An emsdk bump changes the compiler for the whole project — it must be validated for the normal (JS-EH) build too, not just this experiment.
• JSPI (the long-term replacement for asyncify) was evaluated and is not viable yet: Firefox still flag-gates it.

Appendix: the full plumbing patch

Applies cleanly on top of a563746. Save the block below to a file and git apply it.

diff --git a/docker/build.sh b/docker/build.sh
index 268b03d..456f906 100755
--- a/docker/build.sh
+++ b/docker/build.sh
@@ -182,7 +182,8 @@ compile_app() {
     # -e EMSDK=/emsdk: `docker compose exec` bypasses the entrypoint that sources
     # 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 kicad-wasm-builder \
+    docker compose -f docker/docker-compose.yml exec -e EMSDK=/emsdk \
+        -e KICAD_WASM_EH="${KICAD_WASM_EH:-0}" kicad-wasm-builder \
         "/workspace/scripts/kicad/build-${app}.sh" "${ARGS[@]}"
 
     # Copy output to host-accessible directory.
diff --git a/scripts/build-wxuniversal-wasm.sh b/scripts/build-wxuniversal-wasm.sh
index 29b7f20..385b356 100755
--- a/scripts/build-wxuniversal-wasm.sh
+++ b/scripts/build-wxuniversal-wasm.sh
@@ -137,9 +137,16 @@ if [ $NEEDS_CONFIGURE -eq 1 ]; then
         echo "Building wxWidgets in RELEASE mode"
     fi
 
+    # EH model must match the rest of the build (see env.sh KICAD_WASM_EH).
+    if [ "${KICAD_WASM_EH:-0}" = "1" ]; then
+        WX_EH_FLAG="-fwasm-exceptions -sSUPPORT_LONGJMP=wasm -sWASM_LEGACY_EXCEPTIONS=0"
+    else
+        WX_EH_FLAG="-fexceptions"
+    fi
+
     # Include emscripten cache sysroot for zlib headers
-    export CFLAGS="-DZ_HAVE_UNISTD_H=1 -I$EM_CACHE_SYSROOT/include ${WX_DEBUG_FLAGS} -fexceptions -pthread -matomics -mbulk-memory"
-    export CXXFLAGS="-DZ_HAVE_UNISTD_H=1 -I$EM_CACHE_SYSROOT/include -I$PCRE2_INCLUDE ${WX_DEBUG_FLAGS} -fexceptions -pthread -matomics -mbulk-memory"
+    export CFLAGS="-DZ_HAVE_UNISTD_H=1 -I$EM_CACHE_SYSROOT/include ${WX_DEBUG_FLAGS} ${WX_EH_FLAG} -pthread -matomics -mbulk-memory"
+    export CXXFLAGS="-DZ_HAVE_UNISTD_H=1 -I$EM_CACHE_SYSROOT/include -I$PCRE2_INCLUDE ${WX_DEBUG_FLAGS} ${WX_EH_FLAG} -pthread -matomics -mbulk-memory"
     export LDFLAGS="-L$EM_CACHE_SYSROOT/lib/wasm32-emscripten"
 
     emconfigure "$WX_SOURCE/configure" \
diff --git a/scripts/common/env.sh b/scripts/common/env.sh
index 90fb61a..0445f99 100755
--- a/scripts/common/env.sh
+++ b/scripts/common/env.sh
@@ -82,7 +82,22 @@ else
     export DEBUG_LDFLAGS=""
 fi
 
-export DEBUG_BUILD BUILD_TYPE DEBUG_CFLAGS DEBUG_LDFLAGS
+# KICAD_WASM_EH=1 (EXPERIMENTAL): native WebAssembly exceptions instead of
+# emscripten's JS-based EH. JS-EH routes every potentially-throwing call inside
+# a try/catch through a JS invoke_* trampoline, which forces asyncify to
+# instrument nearly the whole exception-heavy codebase (pcbnew: 338 MB pre-O2).
+# Wasm EH (-fwasm-exceptions, Chrome 95+/Firefox 100+/Safari 15.2+) keeps
+# exceptions inside wasm — no invoke_*, far smaller asyncify set. ALL C++ must
+# agree on the EH model (deps + wx + kicad): this var feeds every compile.
+# Known limit: asyncify cannot suspend from inside a catch block (binaryen #4470).
+if [ "${KICAD_WASM_EH:-0}" = "1" ]; then
+    # -sSUPPORT_LONGJMP=wasm: setjmp/longjmp must use the same (wasm) machinery;
+    # without it emcc injects -enable-emscripten-sjlj, which clang rejects in
+    # combination with -fwasm-exceptions.
+    export DEBUG_CFLAGS="${DEBUG_CFLAGS} -fwasm-exceptions -sSUPPORT_LONGJMP=wasm -sWASM_LEGACY_EXCEPTIONS=0"
+fi
+
+export DEBUG_BUILD BUILD_TYPE DEBUG_CFLAGS DEBUG_LDFLAGS KICAD_WASM_EH
 
 # Parallel jobs (default to 1 for memory-constrained environments like Docker)
 # Can be overridden with -j N flag or by setting JOBS/PARALLEL_JOBS env vars
diff --git a/scripts/deps/build-boost.sh b/scripts/deps/build-boost.sh
index 8905e79..04da340 100755
--- a/scripts/deps/build-boost.sh
+++ b/scripts/deps/build-boost.sh
@@ -72,6 +72,11 @@ else
     BOOST_DEBUG_FLAGS="-O2"
 fi
 
+# EH model must match the rest of the build (see env.sh KICAD_WASM_EH).
+if [ "${KICAD_WASM_EH:-0}" = "1" ]; then
+    BOOST_DEBUG_FLAGS="${BOOST_DEBUG_FLAGS} -fwasm-exceptions -sSUPPORT_LONGJMP=wasm -sWASM_LEGACY_EXCEPTIONS=0"
+fi
+
 # Create user-config.jam for Emscripten
 cat > user-config.jam << EOF
 using clang : emscripten
diff --git a/scripts/deps/build-cairo.sh b/scripts/deps/build-cairo.sh
index 2580320..9d17e15 100755
--- a/scripts/deps/build-cairo.sh
+++ b/scripts/deps/build-cairo.sh
@@ -65,6 +65,13 @@ else
     MESON_DEBUG_FLAGS="'-O2'"
 fi
 
+# Cairo is C, but its png path uses setjmp/longjmp — the SJLJ machinery must
+# match the link (see env.sh KICAD_WASM_EH): without this, libcairo.a keeps
+# emscripten_longjmp references that are undefined under -sSUPPORT_LONGJMP=wasm.
+if [ "${KICAD_WASM_EH:-0}" = "1" ]; then
+    MESON_DEBUG_FLAGS="${MESON_DEBUG_FLAGS}, '-sSUPPORT_LONGJMP=wasm', '-sWASM_LEGACY_EXCEPTIONS=0'"
+fi
+
 # Cairo uses meson
 cat > cross-file.txt << EOF
 [binaries]
diff --git a/scripts/kicad/build-kicad-target.sh b/scripts/kicad/build-kicad-target.sh
index 6ace02b..0dc10f2 100755
--- a/scripts/kicad/build-kicad-target.sh
+++ b/scripts/kicad/build-kicad-target.sh
@@ -193,25 +193,34 @@ log_info "Building KiCad ${APP_NAME} ${KICAD_VERSION} for WASM..."
 
 # Step 5: Set build type
 # Use environment DEBUG_BUILD if set, otherwise check local --debug flag
-# -fexceptions is required because wxWidgets is built with exceptions enabled
+# Exceptions are required because wxWidgets is built with exceptions enabled.
+# EH model: JS-based (-fexceptions, default) or native wasm EH
+# (-fwasm-exceptions, KICAD_WASM_EH=1 — see env.sh). Must match deps + wx.
 # -matomics -mbulk-memory are required for shared memory (pthreads)
 # NOTE: We use -O1 for debug builds because -O0 produces WASM with too many
 # locals for V8/Chrome to compile (error: "local count too large").
 # -O1 keeps debug info but optimizes enough to stay under V8's limits.
+if [ "${KICAD_WASM_EH:-0}" = "1" ]; then
+    EH_FLAG="-fwasm-exceptions -sSUPPORT_LONGJMP=wasm -sWASM_LEGACY_EXCEPTIONS=0"
+    log_info "Using native WebAssembly exceptions (-fwasm-exceptions)"
+else
+    EH_FLAG="-fexceptions"
+fi
+
 if [ "${DEBUG_BUILD:-0}" = "1" ] || [ $DEBUG -eq 1 ]; then
     BUILD_TYPE="Debug"
-    EXTRA_FLAGS="-g -O1 -fexceptions -matomics -mbulk-memory"
+    EXTRA_FLAGS="-g -O1 ${EH_FLAG} -matomics -mbulk-memory"
     # -gseparate-dwarf puts debug info in a separate .debug.wasm file
     # This keeps the main WASM small (~200MB) while preserving full debug info
     # DevTools loads the debug file on-demand when debugging
-    LINKER_DEBUG_FLAGS="-O1 -g -gseparate-dwarf -fexceptions"
+    LINKER_DEBUG_FLAGS="-O1 -g -gseparate-dwarf ${EH_FLAG}"
     log_info "Building KiCad in DEBUG mode (separate DWARF for smaller main binary)"
 else
     BUILD_TYPE="Release"
-    EXTRA_FLAGS="-O2 -fexceptions -matomics -mbulk-memory"
+    EXTRA_FLAGS="-O2 ${EH_FLAG} -matomics -mbulk-memory"
     # -O0 at link time skips wasm-opt (which can OOM on large WASM files)
     # Compilation is still -O2 for optimized code, but we skip post-link wasm-opt
-    LINKER_DEBUG_FLAGS="-O0 -fexceptions"
+    LINKER_DEBUG_FLAGS="-O0 ${EH_FLAG}"
     log_info "Building KiCad in RELEASE mode (skipping wasm-opt due to memory limits)"
 fi