backend-infra-engineer: Post v0.3.9-hotfix7 snapshot (build cleanup)

docs/internal/wasm/build-guide.md

@@ -0,0 +1,72 @@
+# WASM Build Guide
+
+This guide covers building the experimental WebAssembly version of YAZE.
+
+## Prerequisites
+
+1.  **Emscripten SDK (emsdk)**
+    *   Install from [emscripten.org](https://emscripten.org/docs/getting_started/downloads.html).
+    *   Activate the environment: `source path/to/emsdk/emsdk_env.sh`
+2.  **Ninja Build System**
+    *   `brew install ninja` (macOS) or `apt-get install ninja-build` (Linux).
+3.  **Python 3** (for serving locally).
+
+## Quick Build
+
+Use the helper script for a one-step build:
+
+```bash
+# Build Release version (default)
+./scripts/build-wasm.sh
+
+# Build Debug version (with assertions and source maps)
+./scripts/build-wasm.sh debug
+
+# Build with AI runtime enabled (experimental)
+./scripts/build-wasm.sh ai
+```
+
+The script handles:
+1.  CMake configuration using `emcmake`.
+2.  Compilation with `ninja`.
+3.  Packaging assets (`src/web` -> `dist/`).
+4.  Ensuring `coi-serviceworker.js` is placed correctly for SharedArrayBuffer support.
+
+## Serving Locally
+
+You **cannot** open `index.html` directly from the file system due to CORS and SharedArrayBuffer security requirements. You must serve it with specific headers.
+
+```bash
+# Use the helper script (Python based)
+./scripts/serve-wasm.sh [port]
+```
+
+Or manually:
+```bash
+cd build-wasm/dist
+python3 -m http.server 8080
+```
+*Note: The helper script sets the required `Cross-Origin-Opener-Policy` and `Cross-Origin-Embedder-Policy` headers.*
+
+## Architecture
+
+*   **Entry Point:** `src/main_wasm.cpp` (or `src/main.cpp` with `__EMSCRIPTEN__` blocks).
+*   **Shell:** `src/web/index.html` template (populated by CMake/Emscripten).
+*   **Threading:** Uses `SharedArrayBuffer` and `pthread` pool. Requires HTTPS or localhost.
+*   **Filesystem:** Uses Emscripten's `IDBFS` mounted at `/home/web_user`. Data persists in IndexedDB.
+
+## Troubleshooting
+
+### "SharedArrayBuffer is not defined"
+*   **Cause:** Missing security headers.
+*   **Fix:** Ensure you are serving with `COOP: same-origin` and `COEP: require-corp`.
+*   **Check:** Is `coi-serviceworker.js` loading? It polyfills these headers for GitHub Pages (which doesn't support them natively yet).
+
+### "Out of Memory" / "Asyncify" Crashes
+*   The build uses `ASYNCIFY` to support blocking calls (like `im_gui_loop`).
+*   If the stack overflows, check `ASYNCIFY_STACK_SIZE` in `CMakePresets.json`.
+*   Ensure infinite loops yield back to the browser event loop.
+
+### "ReferenceError: _idb_... is not defined"
+*   **Cause:** Missing JS library imports.
+*   **Fix:** Check `CMAKE_EXE_LINKER_FLAGS` in `CMakePresets.json`. It should include `-lidbfs.js`.