feat(wasm,3d-viewer): run upstream multi-threaded CPU raytracer

Bumps the kicad submodule to the threading revert (the 3D-viewer raytracer's
WASM single-threaded #ifdef fallbacks + the bs_thread_pool inline shim are gone;
those four files are now byte-identical to upstream KiCad).

Links wasm/shims/nanosleep_yield.c into every app (mirrors the gl_ffp_stub
pattern): the now-upstream raw-thread raytracer joins via a main-thread
sleep_for busy-wait, and this shim makes that nanosleep Asyncify-yield to the JS
event loop instead of deadlocking on on-demand pthread-Worker creation. Its
EM_ASYNC_JS yield is already covered by env.__asyncjs__* in asyncify-imports.txt.
This is what lets upstream's multi-threaded code run on WASM under native-EH.

Also documents isolated-worktree + submodule-branch creation in the README.

Result: ~11x faster 3D raytrace (21.3s -> 1.9s, 16 threads), pixel-correct
render, full kicad e2e green (63 passed / 0 failed).

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

README.md

@@ -92,6 +92,44 @@ Output: `output/pcbnew.js`, `output/pcbnew.wasm`
 
 See [docs/build.md](docs/build.md) for detailed build documentation.
 
+#### Creating an isolated worktree (with submodule branches)
+
+For an experiment or feature you can work in a disposable git worktree so the
+main checkout stays pristine. This repo has four submodules
+(`kicad`, `wxwidgets`, `binaryen`, `web/pcbjam-shared`); a new worktree starts
+with them empty, so initialize and branch each one:
+
+```bash
+# 1. Create the worktree on a new branch (off main), at a sibling path
+git worktree add -b experiment/my-thing ../kicad-wasm-my-thing main
+
+# 2. Check out the submodules INSIDE the worktree (working trees only;
+#    git objects are shared with the main checkout)
+cd ../kicad-wasm-my-thing
+git submodule update --init kicad wxwidgets binaryen web/pcbjam-shared
+
+# 3. Create a matching branch in each submodule (they start at detached HEAD)
+git checkout -b experiment/my-thing                 # root already on it via -b above
+for sm in kicad wxwidgets binaryen web/pcbjam-shared; do
+  git -C "$sm" checkout -b experiment/my-thing
+done
+```
+
+Then build from inside the worktree. Use an **isolated** Docker project — do NOT
+set `COMPOSE_PROJECT_NAME` to another branch's project (e.g. `kicad-wasm-main`),
+which can collide with other workflows; `docker/build.sh` auto-derives an isolated
+project name from the worktree branch. The first build provisions deps
+(wxWidgets + OCC) from scratch. To keep the machine responsive / bound wasm-opt
+RAM, cap parallelism and skip the slow release optimization:
+
+```bash
+KICAD_DOCKER_CPUS=4 BINARYEN_CORES=4 BINARYEN_OPT_LEVEL=-O1 \
+  ./docker/build.sh pcbnew -j 4
+```
+
+Tear down afterward with `git worktree remove ../kicad-wasm-my-thing` (and
+`docker compose -p <project> down -v` to drop the isolated volumes).
+
 #### Fresh worktree provisioning
 
 Some test artifacts are gitignored and are NOT produced by the build pipeline,

kicad

@@ -1 +1 @@
-Subproject commit 032540ab77542551e42104d83eae0cb3b457f43e
+Subproject commit 4f42d0b328e8021858cabd1bd5c9cefdf10dbe3c

scripts/kicad/build-kicad-target.sh

@@ -425,6 +425,15 @@ if [ "${BUILD_3D_VIEWER}" = "ON" ]; then
     GL3D_LINK_FLAGS="${STUBS_BUILD}/gl_ffp_stub.o"
 fi
 
+# Multi-threaded CPU raytracer (mainline threading restored): link the main-thread
+# nanosleep->Asyncify-yield shim so the raw-thread raytracer joins (sleep_for busy-wait)
+# yield to the JS event loop instead of deadlocking on-demand pthread-Worker creation.
+# Mirrors the gl_ffp_stub pattern (compile to .o, add to the link). Shim:
+# wasm/shims/nanosleep_yield.c; its EM_ASYNC_JS yield is covered by env.__asyncjs__* in
+# scripts/common/asyncify-imports.txt.
+emcc -c -pthread "${PROJECT_ROOT}/wasm/shims/nanosleep_yield.c" -o "${STUBS_BUILD}/nanosleep_yield.o"
+NANOSLEEP_YIELD_LINK="${STUBS_BUILD}/nanosleep_yield.o"
+
 emcmake cmake "${KICAD_DIR}" \
     ${CCACHE_OPTS} \
     ${SYM_CONVERTER_CMAKE_FLAG} \
@@ -435,7 +444,7 @@ emcmake cmake "${KICAD_DIR}" \
     -DCMAKE_POLICY_VERSION_MINIMUM=3.5 \
     -DCMAKE_CXX_FLAGS="${EXTRA_FLAGS} -Xclang -fno-pch-timestamp -pthread -sUSE_ZLIB=1 -DKICAD_USE_PLATFORM_WASM=1${DIAG_DEFINES} -I${SYSROOT}/include -I${STUBS_DIR} -include ${STUBS_DIR}/char_traits_uint16_workaround.h" \
     -DCMAKE_C_FLAGS="${EXTRA_FLAGS} -pthread -sUSE_ZLIB=1 -I${SYSROOT}/include -I${STUBS_DIR}" \
-    -DCMAKE_EXE_LINKER_FLAGS="${LINKER_DEBUG_FLAGS} -pthread -sUSE_ZLIB=1 -sASYNCIFY=1 -sDYNCALLS=1 -sASYNCIFY_STACK_SIZE=65536 -sUSE_PTHREADS=1 -sPTHREAD_POOL_SIZE='navigator.hardwareConcurrency' -sPTHREAD_POOL_SIZE_STRICT=0 -sALLOW_MEMORY_GROWTH=1 -sINITIAL_MEMORY=256MB -sMAXIMUM_MEMORY=4GB -sMAX_WEBGL_VERSION=2 ${GL3D_LINK_FLAGS} -sEXPORTED_RUNTIME_METHODS=['ccall','cwrap','UTF8ToString','stringToUTF8','lengthBytesUTF8','dynCall'] -sDEFAULT_LIBRARY_FUNCS_TO_INCLUDE=['\$dynCall'] --bind -L${SYSROOT}/lib ${STUBS_BUILD}/libgit2_stub.a ${STUBS_BUILD}/libcurl_stub.a${APP_STUB_LINK} ${STUBS_BUILD}/libnng_stub.a ${EMBIND_OBJ}" \
+    -DCMAKE_EXE_LINKER_FLAGS="${LINKER_DEBUG_FLAGS} -pthread -sUSE_ZLIB=1 -sASYNCIFY=1 -sDYNCALLS=1 -sASYNCIFY_STACK_SIZE=65536 -sUSE_PTHREADS=1 -sPTHREAD_POOL_SIZE='navigator.hardwareConcurrency' -sPTHREAD_POOL_SIZE_STRICT=0 -sALLOW_MEMORY_GROWTH=1 -sINITIAL_MEMORY=256MB -sMAXIMUM_MEMORY=4GB -sMAX_WEBGL_VERSION=2 ${GL3D_LINK_FLAGS} ${NANOSLEEP_YIELD_LINK} -sEXPORTED_RUNTIME_METHODS=['ccall','cwrap','UTF8ToString','stringToUTF8','lengthBytesUTF8','dynCall'] -sDEFAULT_LIBRARY_FUNCS_TO_INCLUDE=['\$dynCall'] --bind -L${SYSROOT}/lib ${STUBS_BUILD}/libgit2_stub.a ${STUBS_BUILD}/libcurl_stub.a${APP_STUB_LINK} ${STUBS_BUILD}/libnng_stub.a ${EMBIND_OBJ}" \
     -DCMAKE_PREFIX_PATH="${SYSROOT};${WX_BUILD}" \
     -DwxWidgets_CONFIG_EXECUTABLE="${WX_BUILD}/wx-config" \
     \