Repository navigation
Description
Goal
Restore the end-to-end DWARF stack-trace debugging experience so that when a sketch crashes in the browser, the user sees their actual C++ .ino source line in DevTools, not raw wasm-function[N]:0xHHHH offsets.
The original work landed the server-side resolver scaffolding (#118, closes none of #85). This meta issue tracks every remaining piece across every repo that has to change for the experience to actually work for an end user.
Current state
- ✅
POST /dwarfsourceandGET /debug/source-rootsare wired up and tested (feat: restore DWARF source resolution + unblock end-to-end Windows compile #118). - ✅ The resolver auto-populates after each successful build with the right roots.
- ❌ The DWARF embedded in
.wasmuses raw absolute paths, not the prefixes the resolver expects (fix(dwarf): bridge from /dwarfsource resolver to actual browser stack traces #129, gap 1). - ❌ Nothing in the shipped JS bundle ever calls
/dwarfsource(fix(dwarf): bridge from /dwarfsource resolver to actual browser stack traces #129, gap 2). - ❌ Source-roots JSON leaks the Windows
\\?\long-path prefix (fix(dwarf): bridge from /dwarfsource resolver to actual browser stack traces #129, gap 3). - ❌
--serve-dircannot rehydrate the resolver from a pre-built directory (fix(dwarf): bridge from /dwarfsource resolver to actual browser stack traces #129, gap 4).
Net effect today: a real wasm crash in the Tauri viewer shows the JS stack only; C++ frames are unresolved.
Work breakdown
zackees/fastled-wasm (this repo)
- feat: restore browser stack tracing without Playwright or CRX downloads #85 — feat: restore browser stack tracing without Playwright or CRX downloads — the parent feature request. Stays open until the experience works end-to-end.
- fix(dwarf): bridge from /dwarfsource resolver to actual browser stack traces #129 — fix(dwarf): bridge from /dwarfsource resolver to actual browser stack traces — captures the current failure state and enumerates the four gaps below. Will split into smaller issues as work begins.
- build path: plumb
-ffile-prefix-map=…throughwasm_build.rs::get_sketch_compile_flags, reading the[dwarf]section ofbuild_flags.toml. Goal:strings fastled.wasm | grep sketchsource/Blink.inoafter a clean debug build. (Splits from fix(dwarf): bridge from /dwarfsource resolver to actual browser stack traces #129 gap 1.) - client bridge: pick one and ship it. Options (fix(dwarf): bridge from /dwarfsource resolver to actual browser stack traces #129 lists trade-offs):
- source-map–only path (drop
/dwarfsourceentirely, rely on-gsource-map); - bundled JS overlay that catches wasm traps and renders mapped frames via
/dwarfsource; - bundled (unpacked) Chrome extension that the Tauri viewer loads via
--load-extension.
- source-map–only path (drop
- fix(dwarf): bridge from /dwarfsource resolver to actual browser stack traces #129 gap 3: fold
NormalizedPathintoDebugSymbolConfig::source_roots()so the JSON response stops leaking the\\?\prefix. - fix(dwarf): bridge from /dwarfsource resolver to actual browser stack traces #129 gap 4: write
dwarf-roots.jsonintofastled_js/at build time so--serve-dircan rehydrate the resolver. - smoke test: walk the wasm strings table after a debug build, POST every embedded source path to
/dwarfsource, assert every resolution succeeds. Pins gap 1 closed for good. - VSIX URL:
crates/fastled-cli/src/install.rs:475referenceshttps://github.com/zackees/vscode-auto-debug/releases/latest/download/auto-debug.vsix, but the repo currently returns 404. Either restore the repo, retarget the URL, or remove the install path. (Likely a separate small issue.)
FastLED/FastLED (upstream library)
- Windows-aware
[dwarf]mapping inbuild_flags.toml. The current config is Unix-centric:On Windows, build paths look likefile_prefix_map_from = "/" file_prefix_map_to = "sketchsource/"
C:/Users/…(or\\?\C:\…after canonicalize), so a single-prefix mapping cannot capture both the sketch tree and the FastLED tree. Either:- expand the section to declare multiple
(from, to)pairs, one per logical root (sketch / FastLED src / emsdk); or - drop the config and let the build system synthesize prefix-maps from the actual on-disk roots it knows about.
- expand the section to declare multiple
- Frontend symbolicator (if we ship the JS-overlay path). A small JS module bundled into the WASM frontend that catches errors, walks the wasm stack, and renders mapped frames using
/dwarfsource. Likely lives next to the existing JS bundle undersrc/platforms/wasm/compiler/. - Confirm
.dwarfseparate-file output isn't expected.build_flags.tomldeclaresdwarf_filename = "fastled.wasm.dwarf"but no such file is produced today — emscripten embeds DWARF in the .wasm directly. Either drop the key or wire it up via-gseparate-dwarf=<path>if external DWARF is wanted.
Future Chrome-extension repo (only if the extension path is picked)
- Resurrect or replace the legacy Chrome extension that the original Playwright path used. Must not depend on the Chrome Web Store CRX download (per feat: restore browser stack tracing without Playwright or CRX downloads #85's acceptance criteria). Likely lives in its own repo so the Tauri viewer can vendor it as a submodule / fetched artifact.
Documentation
- Once the experience works, document the diagnostic path in
CLAUDE.md(or a newdocs/debugging.md) so future maintainers know how a sketch crash is supposed to surface in DevTools.
Definition of done
fastled --init Blink → add a null-deref crash → fastled <sketch> (compile + serve + viewer) → trigger the crash → Chrome DevTools' "Sources" panel highlights the offending .ino / .h line, with a JS-style stack listing each C++ frame mapped to its source file. No Playwright. No Chrome Web Store CRX. No manual extension install.
Refs
#85 #118 #129 — local-side state and the resolver scaffolding shipped in #118.
Activity
feat(dwarf): bridge source maps to debug sources
zackees commentedon Jun 1, 2026
Status update on the DWARF stack-trace path:
-ffile-prefix-mapgeneration forFastLED/src, forward-slash Meson source discovery, and cache invalidation for old native-separator source metadata.Local combined smoke using fastled-wasm#132 + FastLED#2675:
fastled --init Blink --no-interactivefastled --just-compile --debug --no-interactive --fastled-path <FastLED PR worktree> .\fastled\Blinkfastled_js/fastled.wasm.map,fastled.wasm, anddwarf-roots.jsonsketchsource/Blink.inoandfastledsource/...fastled.wasm.mapsrc\platforms/fastledsource\platformsbackslash source-path matches infastled.wasm.mapStill intentionally not closing this meta issue until the final browser DevTools null-deref acceptance path is verified after the PRs land.
feat(dwarf): bridge source maps to debug sources (#132)
zackees commentedon Jun 1, 2026
Implemented and verified end-to-end.
Merged PRs:
11cdf0fe907e8f594c15b92e52037ee26c3a5b9a27a168259ce79ab422cb7d0715fd329e80543181Final acceptance run, no Playwright / no CRX / no extension install:
mainrelease binarymasterBlink.ino:24issue_130_null_deref()Blink.ino:26*missing = 130;fastled --just-compile --debug --no-interactive --fastled-path C:\Users\niteris\dev\FastLED <temp>\Blinkfastled_jswith the native--serve-dirpath/debug/source-rootsrehydrated sketch/FastLED/emsdk roots fromdwarf-roots.jsonGET /dev/fastled/sketchsource/Blink.inoreturns the modified sketch sourcefastled.wasmloads withsourceMapURL: fastled.wasm.mapfastled.wasm.mapmaps generated wasmline 0, column 7344toBlink.ino:26http://127.0.0.1:<port>/fastled.wasm:0:7344pauses in the worker at$issue_130_null_deref()$issue_130_null_deref()->$loop()->$fl::fastled_loop_once()->$extern_loop()That satisfies this meta issue's definition of done: the browser has the wasm source map, the server can resolve the mapped
.inosource, and the debugger stops on the offending sketch frame/source location without Playwright or a Chrome extension.