feat(wasm): add browser QEMU build

HANDOFF.md

@@ -12,10 +12,11 @@ touching QEMU internals. Pairs with `ROADMAP.md` (the plan) — this is the
 - One `xteink` QEMU machine selects `variant=x3|x4` at launch. **Unmodified
   canonical firmware** detects X3 through I²C fingerprints and boots the home
   screen; X4 detects through all-NAK probes and reaches a blank SSD1677 stub.
-- All Phase-1 device models live in **one patch**:
-  `qemu/patches/0001-xteink-machine.patch`, applied onto exact espressif/qemu
-  commit `40edccac415693c5130f91c01d84176ae6008566`.
-- Next: compile to WASM (qemu-wasm) → static browser UI. Full X4 rendering waits.
+- Phase-1 device models live in `qemu/patches/0001-xteink-machine.patch`;
+  `0002-qemu-wasm.patch` ports qemu-wasm's host backend onto the same pinned
+  Espressif QEMU commit `40edccac415693c5130f91c01d84176ae6008566`.
+- `make qemu-wasm` produces a smoke-tested ES module, WASM binary, and pthread
+  worker under `dist/wasm/`. Next: static browser UI. Full X4 rendering waits.
 
 ---
 
@@ -207,8 +208,8 @@ ADC ladders on GPIO1 & GPIO2; power button GPIO3; UC8253 @ 16 MHz.
 
 ## 8. Reproducibility model
 
-- **Durable = the patch** (`qemu/patches/0001-xteink-machine.patch`), verified
-  against exact QEMU commit `40edccac415693c5130f91c01d84176ae6008566` (tag
+- **Durable = the patches**: apply `0001-xteink-machine.patch`, then
+  `0002-qemu-wasm.patch` for the browser build. Both target exact QEMU commit `40edccac415693c5130f91c01d84176ae6008566` (tag
   `esp-develop-9.2.2-20260417`). When editing `_scratch/qemu-src`, regenerate:
   ```sh
   cd <qemu-src> && git add -N <new files> && git diff --binary > <repo>/qemu/patches/0001-xteink-machine.patch
@@ -253,15 +254,27 @@ ADC ladders on GPIO1 & GPIO2; power button GPIO3; UC8253 @ 16 MHz.
 
 ---
 
-## 10. Next steps (in priority order)
+## 10. WASM build and next steps
 
-1. **Compile to WASM**: combine this pinned Espressif fork with
-   `ktock/qemu-wasm`'s WASM TCG/TCI backend + Emscripten. De-risk by building an
-   unpatched esp32c3 target under qemu-wasm first, then apply our patch.
-2. **Static browser front-end**: display surface → canvas; physical buttons →
+- `make qemu-wasm` uses Podman or Docker and the pinned Emscripten 3.1.50 image
+  in `qemu/wasm/Dockerfile`. It builds only `riscv32-softmmu` with the xteink
+  device graph; unrelated boards, networking, audio, virtfs, tools, and docs are
+  disabled. Outputs go to `dist/wasm/`.
+- qemu-wasm commit `0ef7b4e2814b231705d8371dd7997f5b72e70baf` is based on
+  QEMU 8.2; `0002-qemu-wasm.patch` is the resolved port to Espressif QEMU 9.2.
+  `-sEMULATE_FUNCTION_POINTER_CASTS=1` is required for QEMU's QOM callbacks.
+- The WASM dependency image omits libgcrypt. AES/RSA/DS/XTS devices are therefore
+  not instantiated; their MMIO falls through to the existing zero-return stub.
+  Canonical firmware boot still needs browser-level validation; add cross-built
+  libgcrypt only if firmware proves it uses those accelerators.
+- Emscripten pthreads require cross-origin isolation (COOP/COEP) in the browser.
+
+Next:
+
+1. **Static browser front-end**: display surface → canvas; physical buttons →
    ADC/GPIO controls; uploaded flash; SD block backend; `variant=x3|x4` chosen
    before boot. Must run fully from static assets (airgapped).
-3. **Full X4 rendering later**: SSD1677 is 800×480 controller / 480×800 portrait,
+2. **Full X4 rendering later**: SSD1677 is 800×480 controller / 480×800 portrait,
    BUSY active-high. Implement its RAM/window/update commands when needed.
 
 ---
@@ -271,7 +284,9 @@ ADC ladders on GPIO1 & GPIO2; power button GPIO3; UC8253 @ 16 MHz.
 | What | Where |
 |------|-------|
 | Emulator repo | `/home/evanreichard/Development/git/personal/xteink-web-emulator` |
-| The patch | `qemu/patches/0001-xteink-machine.patch` |
+| Native/WASM patches | `qemu/patches/0001-xteink-machine.patch`, `0002-qemu-wasm.patch` |
+| WASM environment | `qemu/wasm/Dockerfile` |
+| WASM build | `scripts/build-qemu-wasm.sh` → `dist/wasm/` |
 | QEMU source (ephemeral) | `_scratch/qemu-src` (via `make qemu`) |
 | Canonical firmware | `https://github.com/crosspoint-reader/crosspoint-reader` |
 | Tested firmware checkout | `/tmp/crosspoint-reader-main` @ `556b8ae` (unmodified) |