Repository navigation
Description
Goal
Reproduce a wasm crash in a sketch and confirm whether the stack trace shows up in Chrome DevTools' "Sources" panel with proper C++ source mapping via the /dwarfsource resolver shipped in #118 (issue #85).
TL;DR
The resolver is server-side ready, client-side broken. A wasm crash today produces a JS stack of raw wasm-function[N]:0xHHHH offsets with no C++ source mapping. Three concrete gaps prevent the legacy debugging experience from being restored, all on the producer/consumer side of the resolver — the resolver endpoints themselves work.
Reproduction
fastled --init Blink --no-interactive
# patch Blink.ino: add `static void crash() { *(volatile int*)0 = 42; }`
# and call crash() from loop()
fastled --just-compile --debug --no-interactive ./fastled/Blink
fastled --debug --no-interactive ./fastled/Blink # compile + serve + watch
curl http://127.0.0.1:<port>/debug/source-roots
curl -X POST http://127.0.0.1:<port>/dwarfsource \
-H 'Content-Type: application/json' \
-d '{"path":"sketchsource/Blink.ino"}'What works
GET /debug/source-rootsreturns four populated roots after a successful build:{"roots":[ {"prefix":"sketchsource","path":"…\\Temp\\crash-test\\fastled\\Blink"}, {"prefix":"fastledsource","path":"…\\.fastled\\cache\\fl\\repo\\src"}, {"prefix":"headers","path":"…\\.fastled\\cache\\fl\\repo\\src"}, {"prefix":"emsdk","path":"…\\toolchains\\emscripten\\win\\x86_64"} ]}POST /dwarfsourcewith a prefixed path (sketchsource/Blink.ino,fastledsource/FastLED.h) returns the file content (200 OK).POST /dwarfsourcewith..traversal returns 400 withinvalid path:.--just-compile --debugembeds DWARF:fastled.wasmis 897 KB for a minimal Blink (vs ~540 KB for--quick). 17 absolute source paths are visible in the wasm viastrings.
What doesn't work — three gaps
Gap 1 (high): DWARF embeds raw absolute paths, not the prefixed form
The .wasm's DWARF compilation-unit table embeds the raw Windows paths like:
C:/Users/niteris/.fastled/cache/fl/repo/src\fl/stl/flat_map.h
C:/Users/niteris/.fastled/cache/fl/repo/src\platforms/shared/coroutine_context.cpp.hpp
…
When a browser/extension asks /dwarfsource for those paths, the resolver returns 400 (invalid path:) because they don't start with any configured prefix:
POST /dwarfsource {"path":"C:/Users/niteris/.fastled/cache/fl/repo/src/fl/stl/flat_map.h"}
HTTP/1.1 400 {"error":"invalid path: C:/Users/niteris/.fastled/cache/fl/repo/src/fl/stl/flat_map.h"}
Root cause: crates/fastled-cli/src/wasm_build.rs does not pass -ffile-prefix-map=FROM=TO to emcc. FastLED's src/platforms/wasm/compiler/build_flags.toml declares the mapping under [dwarf]:
file_prefix_map_from = "/"
file_prefix_map_to = "sketchsource/"…but only the legacy Python compiler honoured that section. The Rust path reads [build_modes.debug] flags directly and never generates the -ffile-prefix-map argument.
Worse, on Windows even a correctly-generated -ffile-prefix-map=/=sketchsource/ would not match anything because compilation paths look like C:/Users/…, not /Users/…. The mapping config is Unix-centric.
Gap 2 (high): no client code calls /dwarfsource
grep of the bundled frontend assets in fastled_js/*.js:
grep -lE 'dwarfsource|sketchsource|fastledsource|/debug/source-roots' \
/tmp/crash-test/fastled/Blink/fastled_js/*.js
# (no output)Nothing in the shipped JS bundle ever posts to /dwarfsource or fetches /debug/source-roots. The endpoints are reachable but never invoked. Two consumer paths existed historically:
- A Chrome extension (removed in Remove Playwright browser flow and tighten Rust/Python boundary #86 / referenced in feat: restore browser stack tracing without Playwright or CRX downloads #85) that intercepted DWARF source-fetches in DevTools and translated them into
POST /dwarfsourcecalls. - A VSCode auto-debug extension (still installed by
install.rs'sAUTO_DEBUG_VSIX_URL), which targets VSCode's wasm debugger, not Chrome.
Neither one is the path a user takes when they hit a crash in the default fastled <sketch> Tauri viewer / browser.
Gap 3 (medium): /debug/source-roots leaks the \\?\ long-path prefix
The JSON above shows the paths as "\\\\?\\C:\\Users\\…". The Windows long-path prefix that we now strip from the build-side path consumers (via NormalizedPath) is still surfacing in the resolver's source-roots output, because debug_symbols::DebugSymbolConfig::source_roots() uses path.canonicalize() directly instead of going through NormalizedPath. Not a functional break for the resolver itself, but a regression risk if a future browser consumer compares root paths.
Gap 4 (low): --serve-dir cannot serve DWARF sources
--serve-dir skips the build, so the resolver handle is never populated. /debug/source-roots returns {"roots":[]} and any /dwarfsource POST returns 400 debug source resolver unavailable. If we want post-mortem debugging of a pre-built fastled_js/ directory, the resolver needs to be reconstructible from on-disk state (e.g. a dwarf-roots.json sidecar written at build time).
Current state of issue #85 acceptance criteria
| Criterion | Status |
|---|---|
| Failing sketch produces a readable mapped stack trace | ❌ JS stack of raw wasm-function[N]:0xHHHH offsets |
| No Playwright / Chrome Web Store CRX dependency | ✅ |
No hidden --internal-ensure-chrome-extension path |
✅ |
| Automated coverage that doesn't require Playwright | ✅ — 6 resolver unit tests + 4 server integration tests in #118 |
| Documented diagnostic path |
Next steps
In rough priority order:
- Plumb
-ffile-prefix-mapthrough the Rust build path.wasm_build.rs::get_sketch_compile_flagsshould read[dwarf]frombuild_flags.tomland append-ffile-prefix-map={file_prefix_map_from}={file_prefix_map_to}to the per-mode flags. Handle Windows by mapping the actual prefixes that emcc sees (<sketch_dir>/→sketchsource/,<fastled_dir>/src/→fastledsource/,<emsdk_root>/→dwarfsource/emsdk/). Verify withstrings fastled.wasm | grep sketchsourceafter a clean debug build. - Pick a client path and wire it. Options:
- Chrome devtools native + extension-free: leverage
-gsource-mapso the C++ frames resolve through the same source-map endpoint that JS frames already use. Implies dropping/dwarfsourceand the resolver in favour of source-map URLs. - Browser overlay: ship a tiny JS error handler in the frontend bundle that catches the wasm trap, walks the JS stack, posts each wasm frame to a new
/wasm/symbolicateendpoint, and renders the mapped frames in an HTML overlay. Bridge doesn't depend on a Chrome extension. - Restore the Chrome extension, but without the Web Store CRX download path (e.g. bundle the extension's unpacked source in the Tauri viewer and load it via
--load-extension).
- Chrome devtools native + extension-free: leverage
- Strip the
\\?\prefix fromsource_roots()output — foldNormalizedPathintoDebugSymbolConfig::source_roots(). - Persist a
dwarf-roots.jsonsidecar infastled_js/so--serve-dircan rehydrate the resolver from a pre-built directory. - Add an end-to-end smoke test that compiles a known-crashing sketch, starts the server, walks the wasm strings table for embedded source paths, posts each one to
/dwarfsource, and asserts every resolution succeeds. That makes Gap 1 a hard error in CI.
Evidence captured during this session
fastled --just-compile --debugon asetup()-crashing Blink →fastled.wasm897 KB with 17 rawC:/Users/…paths.GET /debug/source-rootsafter compile+serve → 4 prefixed roots populated, but the path strings carry\\?\.POST /dwarfsource {"path":"sketchsource/Blink.ino"}→ 200 with full Blink source.POST /dwarfsource {"path":"<raw embedded path>"}→ 400invalid path:.grepon bundled JS infastled_js/*.js→ no references todwarfsource/sketchsource//debug/source-roots.
Activity
feat(dwarf): bridge source maps to debug sources
feat(dwarf): bridge source maps to debug sources (#132)
zackees commentedon Jun 1, 2026
Fixed by the combined cross-repo work:
The four gaps from this issue are now covered:
fastled.wasm.mapuses source-map paths such as.../sketchsource/Blink.inoand.../fastledsource/...dwarf-roots.jsonis written intofastled_js/and--serve-dirrehydrates it/debug/source-rootsuses normalized paths instead of leaking Windows long-path prefixesFinal raw-CDP browser acceptance from #130 also passed: Chrome loaded
fastled.wasmwithsourceMapURL: fastled.wasm.map, and a breakpoint at the generated wasm location mapped fromBlink.ino:26paused in$issue_130_null_deref()with the C++ wasm stack intact.