0069. duolith dev emits source maps, and our own debug adapter puts breakpoints on page lines
- Status: Proposed
- Date: 2026-11-14
- Decided by: toolchain work package (WP15), pending Mik's approval
- Planning item: WP15 (toolchain), goal 4
Context
A breakpoint should go on a line of the .duo file, a stack trace should name that file, and a signal should show its value under the name the author wrote. The compiled module puts the script, the markup's expressions and the runtime calls into one JavaScript file, after two rewrites (signals to .value, then TypeScript stripped).
Decision
- Source maps first. In
duolith dev, every page, layout and component module ends with an inline source map (//# sourceMappingURL=data:...) whose one source is the page file (/pages/index.duo) with its text included. The map composes three layers: where each piece of the module came from in the page, the shifts the runtime rewrite made, and the positions TypeScript stripping printed (oxc's codegen).duolith buildemits none, so production output is unchanged. - **Our own debug adapter,
@duolith/debug-adapter.** It speaks the Debug Adapter Protocol to the editor and the Chrome DevTools Protocol to Chromium, over--remote-debugging-pipe(no WebSocket, so it runs on the Node an editor ships). A launch startsduolith devand the browser. Breakpoints are placed per module: the browser pauses before each script runs, the adapter places the breakpoints the script's page file needs (at the first JavaScript each line became), and lets it run; so a page navigated to later, or reloaded, has its breakpoints from its first line. - Signals by their written names. A variable or evaluated name whose value is a
StateCellorDerivedCellis shown as the value inside it, read from its private field, never through thevaluegetter, so looking at it never makes a paused reaction depend on it. - **VS Code gets the
duolithdebug type.** The extension runs the bundled adapter on VS Code's own Node; F5 without alaunch.jsondebugs the folder's app. Other editors run the same adapter executable. Using VS Code's JavaScript debugger ("type": "chrome") on the source maps still works and stays indocs/guide/debugging.md. - Tested over DAP: the adapter's test launches
examples/control-flow, sets a breakpoint by a.duoline, presses Add, and checks the stop, the frame's file and line, a signal's value, a step and a continue.
Alternatives considered
| Option | Why not |
|---|---|
| Only VS Code's JavaScript debugger on the source maps | Shows signals as cells, and is VS Code's alone; the adapter serves every DAP editor |
| Wrap js-debug | A large dependency we would have to ship and pin; our needs are a small part of it |
| Predict module addresses from file names and break by address | Routes rename files ([id] becomes @id); pausing before each script needs no naming rules |
Separate .map files | A second file per module for the dev server to keep in step; inline maps travel with the module |
| Source maps in production builds too | Larger downloads; can be a flag later |
Consequences
- Errors thrown in a page during
duolith devshow the page's line in the console. - Stepping into the runtime shows its modules as unmapped frames, dimmed.
- Emitters for other targets will need the same three layers to map their output, and a native target will need its own transport in the adapter.