| name | cpp-wasm-engineer |
| description | Build, debug, and optimize C++ WebAssembly targets with Emscripten (browser/worker/node) and WASI runtimes. Use when handling C/C++ to WASM compilation, CMake/Make migration, JS interop, threading, filesystem persistence, size/performance tuning, raylib/SDL/web render loop issues, and hard runtime failures such as traps, undefined symbols, MIME/CORS misconfiguration, or memory/thread edge cases. |
C++ WASM Engineer
Drive C++-first WebAssembly delivery with deterministic diagnosis, minimal-risk build settings, and explicit runtime constraints.
Skill Routing
- Use this skill for C++/C, CMake, Make, Emscripten, WASI, raylib/SDL ports, and browser runtime debugging.
- Keep
discover-wasm as a gateway only; treat this skill as the implementation authority for C++.
- Route Rust smart-contract specific tasks to
multiversx-wasm-debug.
Core Workflow
- Classify target first.
Choose one:
browser, worker, node, wasi, or hybrid.
- Pin the toolchain and entrypoints.
Capture exact compiler, linker, and exported symbol list before edits.
- Build a minimal reproducible artifact.
Reduce to the smallest command or target that still fails.
- Resolve runtime contract mismatches.
Check environment assumptions: threads, filesystem, MIME, CORS, JS glue, and memory model.
- Verify with evidence.
Run target-specific smoke tests plus size and symbol checks before closing.
Target Decision Matrix
| Requirement | Prefer | Reason |
|---|
| DOM/WebGL/audio/canvas integration | Emscripten | Provides JS glue and browser APIs |
| Portable server/runtime execution without browser APIs | WASI | Lean runtime contract |
| Same core library in browser and backend | Hybrid (Emscripten + WASI) | Share core, split platform adapters |
| Existing desktop CMake app | Emscripten first | Lowest migration friction |
| Strict startup and binary-size budget | Either, benchmark both | Tradeoffs depend on JS glue + libc usage |
Hard Rules
- Keep all build flags explicit and version-controlled.
- Export only required symbols and runtime methods.
- Fail fast on undefined symbols while iterating.
- Keep debug and release presets separate; never blend flags ad hoc.
- Treat browser headers and hosting config as part of the build contract.
- Document every non-default flag with the symptom it solves.
- For interactive bug fixes, require executable e2e evidence (keyboard + control-click/tap + drag + audio) before closure.
- Record each encountered error with symptom/root-cause/fix/evidence in project error reports.
Load References On Demand
- Read
references/toolchain-build.md for CMake/Make/direct builds, export policy, and Emscripten vs WASI setup.
- Read
references/runtime-interop.md for JS bridge, event loop, async, filesystem, and pthread runtime constraints.
- Read
references/debugging-optimization.md for debug presets, sanitizers, wasm inspection, and size/perf tuning.
- Read
references/edge-cases.md for symptom-driven triage and high-frequency failure patterns.
- Read
references/source-index.md to trace official sources used by this skill.
Execution Templates
Template A: Migrate desktop CMake app to browser WASM
- Configure with
emcmake cmake.
- Build with
cmake --build.
- Replace blocking desktop loop with browser-compatible main loop.
- Declare exports and runtime methods explicitly.
- Validate in served HTTP context, not
file://.
Template B: Fix runtime trap quickly
- Rebuild with debug preset.
- Inspect wasm sections and symbols.
- Map trap to one of: memory, symbol export/import, threading, async boundary, or JS interop contract.
- Apply one fix at a time; retest after each.
- Re-run release preset and compare size/perf regression.
Template C: Prepare production artifact
- Switch to release preset and run wasm optimizer pass.
- Audit exports, assets, and filesystem usage.
- Verify hosting headers for threads and MIME.
- Run smoke tests in target browsers/runtimes.
- Record artifact size, startup time, and known constraints.
Done Criteria
- Build is reproducible with committed commands.
- Runtime behavior is validated in intended environment.
- Edge-case checks for threads, memory, and loader headers are complete.
- Debug/release presets are documented and separate.
- Remaining limitations are explicit.
