Add a dev tools area with benchmark, memory-leak, streaming, parser, and visual-diff tools

[sophiedeziel]

Disclaimer

As this kind of toolset is what I always dreamed of (for this project), this is a POC that is 100% vibe-coded and probably mostly slop.

Code is cheap, the tools are still valuable.

Summary

This PR adds a devtools/ area for internal development tooling, served alongside the demo by the existing dev server but not deployed with it. It ships five tools aimed at the 3.0.0 release gates in #402, built on a small shared infrastructure layer (devtools/lib/) that handles version discovery on jsDelivr, per-version import maps (each release loads the three/lil-gui versions it was published against), sandboxed iframe runners, and a 2.x/3.x API compat shim.

Run npm run dev and open http://localhost:8080/devtools/. Every page has a light/dark toggle top right, persisted across pages and reloads (previews and captures stay dark in both themes so numbers and pixel diffs never depend on the page theme).

Debugger

Steps through a gcode file like a debugger. Click a row's gutter to set a breakpoint, then step forward or back one command at a time, continue to the next breakpoint, or use Run to first to jump past the slicer's metadata comment preamble (on Benchy it lands on command 1,149, the first M73 after PrusaSlicer's comments). The preview renders the toolpath live as you step, and a State panel shows the interpreter's State object (position, positionShift, tool, units, isHomed) with the keys that changed on the last step highlighted. Stepping back re-executes from the start, which stays fast: benchy's 163,474 commands re-execute in about 40 ms. The loaded file and breakpoints survive page reloads via localStorage, with corrupt stored values discarded safely. A collapsed Instantiation settings editor exposes the constructor options as editable JSON with live validation, curated presets, Reset to default, and persistence on every edit; applying rebuilds the session while keeping breakpoints and position, and a rejected settings object falls back to the last-known-good ones. The page is full width and the two columns are resizable by dragging the separator.

It doubles as a parser inspector: summary stats and a command-type histogram (both collapsed by default after loading), plus a filterable command list that virtual-scrolls through all of Benchy's 163k commands with no pagination. Full inspection targets 3.x builds since 2.x does not export the parser; older versions degrade to a friendly notice.

Two more findings came out of building it: constructing a preview without buildVolume throws in 3.x (the SceneManager constructor reads this.buildVolume.x unconditionally), and Mach3-style bare S900/F140 lines currently parse as gcodes s900/f140.

Benchmark

Compares two library versions head to head on one of the demo gcode files. Any published npm version can face any other, or the local dist/ build. Each version runs sequentially in a fresh sandboxed iframe, runs are interleaved A/B/A/B, and the table reports medians for parse time, geometry build and render time, time to first render, FPS while orbiting, peak JS heap, triangles, and draw calls. Results can be copied as CSV or as Markdown ready to paste into #402.

Memory-leak tester

Runs repeated create, load, render, dispose cycles against a fresh canvas each time to mimic a framework remount, then charts the JS heap per cycle along with the renderer.info geometry and texture counts read after dispose() — any nonzero residual means dispose leaked GPU resources. The verdict compares the median heap between the first and second half of the steady-state cycles, which stays calm through GC sawtooth and allocator plateau jumps instead of crying wolf on healthy builds. The local build currently passes with a flat heap and flat counters.

Streaming equivalence checker

Parses the same file twice in one version, once as a whole string and once as a ReadableStream chunked at a configurable size, then diffs the parser and job stats plus a rendered-triangle fingerprint. Small chunk sizes maximize the odds of splitting a command across a chunk boundary, which is exactly where streaming bugs live.

It caught a real bug on its first run: parser.lineCount was one higher on the whole-string path for every newline-terminated file (a phantom empty trailing line from split), and digging in revealed the streamed path also fabricated lines on chunks without newlines. Both sides are now fixed in src/ on this PR, the ingestion-equivalence suite asserts line and command counts across all four modes, and the checker reports all metrics green.

Visual diff

Renders the same file in two versions with a pinned camera and target, captures both canvases in the same frame (required on 3.x, which uses preserveDrawingBuffer: false), and pixel-diffs the captures with an adjustable threshold. Changed pixels light up magenta over a dimmed grayscale base. Local vs local diffs at exactly 0.00%, and 2.18.0 vs local on Benchy shows a real 9.09% difference in scene composition relative to the origin.

Also in this PR

The rollup UMD output was missing a global mapping for lil-gui, so rollup warned on every build and guessed lilGui, which is not the global that lil-gui's UMD build actually exposes (lil). One line in rollup.config.mjs fixes both the warning and the broken guess.

The CodeQL alerts raised on this PR are addressed: interpolated values in the benchmark and streaming-equivalence tables are HTML-escaped, and the debugger's postMessage dispatches guard message types with Object.hasOwn.

A debugger-screenshots skill (in .agents/) documents how to capture before/after PR proof shots from the Debugger with custom gcode, following the pattern PR #439 established.

A local multi-angle code review of the branch was applied before marking ready: benchmark and visual-diff runners now dispose their previews so a finished side cannot contaminate the other side's measurements, breakpoints survive re-loads, pre-load edits persist, the debugger parses once and steps with exact full renders via the new public executeCommands API, the default baseline tracks the newest published stable instead of hardcoded 2.x, presets pass their real colors through, theme variables fall back to dark without JS, and shared helpers/CSS were extracted into devtools/lib.

Related to #402.

Assisted by Claude Code - Fable 5

[github-actions]

Visit the preview URL for this PR (updated for commit 62a50b2):

https://gcode-preview--pr453-feature-benchmark-pa-uqxm5awh.web.app

_{(expires Wed, 07 Oct 2026 17:37:17 GMT)}

_{🔥 via Firebase Hosting GitHub Action 🌎}

_{Sign: 59bd114ae4847b32c2bba0b68620b9069a3e3531}

[remcoder]

in #524 I updated the benchmark page with a sweep mode, so it can run the benchmark against a number of builds.
might be a bit rough..