devtools-source-maps

# Utilizing Source Maps & Structured Stack Traces in DevTools This skill guides you on how to correctly map runtime coordinates to original source locations and render structured stack traces or symbolized errors in the DevTools frontend. --- ## 1. Primary Rules 1. **Never parse raw error stacks manually:** Do not split on newlines or use homebrew regex to parse stack traces. Use `DebuggerWorkspaceBinding` helpers to structurally parse and translate stack traces. 2. **Dispose of subscriptions:** Models like `SymbolizedError` subscribe to live locations. Always call `.dispose()` when the consumer (e.g., a widget or list) is destroyed to avoid memory leaks. 3. **Prefer pre-built widgets:** Instead of manually formatting or rendering call frames, use `StackTracePreviewContent` for raw stacks, and `SymbolizedErrorWidget` for complete errors. --- ## 2. Core Abstractions ### A. StackTrace Model (`front_end/models/stack_trace/`) A structured representation of a call stack (synchronous + asynchronous segments). * **`StackTrace`** / **`ParsedErrorStackTrace`** / **`DebuggableStackTrace`**: Dispatches a `StackTrace.Events.UPDATED` event when the original sources are fully resolved or update. * **`Frame`**: Represents a single frame, which contains `uiSourceCode`, `url`, line/column info, untranslated `rawName`, translated `name`, and inline information. ### B. SymbolizedError Model (`front_end/models/bindings/SymbolizedError.ts`) A union type representing a fully symbolized error. * **`SymbolizedErrorObject`**: Contains error `message`, `stackTrace` (as a `ParsedErrorStackTrace`), and an optional `cause` (another `SymbolizedError`). Also holds compile/eval `syntaxErrorLocation`. * **`UnparsableError`**: Fallback when parsing fails. --- ## 3. Core APIs on DebuggerWorkspaceBinding ### Location Translation Translates raw coordinates into UI-friendly original source coordinates: ```ts const uiLocation = await Bindings.DebuggerWorkspaceBinding.instance() .rawLocationToUILocation(rawLocation); ``` ### StackTrace & Error Generation * **From Protocol Stack Trace (Runtime Domain)**: ```ts const stack = await Bindings.DebuggerWorkspaceBinding.instance() .createStackTraceFromProtocolRuntime(protocolStackTrace, target); ``` * **From Debugger Pause details**: ```ts const stack = await Bindings.DebuggerWorkspaceBinding.instance() .createStackTraceFromDebuggerPaused(pausedDetails, target); ``` * **From a Raw Error Stack string**: ```ts const stack = await Bindings.DebuggerWorkspaceBinding.instance() .createStackTraceFromErrorStackLikeString(target, stackString, exceptionDetails); ``` * **From a Remote Error Object**: ```ts const symbolizedError = await Bindings.DebuggerWorkspaceBinding.instance() .createSymbolizedError(remoteObject, exceptionDetails); ``` --- ## 4. UI Widget Reference ### StackTracePreviewContent Renders a structured `StackTrace` inside Shadow DOM. Handles expandable UI and collapsing ignore-listed files. ```ts import * as Components from '../../ui/legacy/components/utils/utils.js'; import * as Workspace from '../../models/workspace/workspace.js'; const preview = new Components.JSPresentationUtils.StackTracePreviewContent(); preview.stackTrace = stackTrace; preview.options = { expandable: true, showColumnNumber: true, ignoreListManager: Workspace.IgnoreListManager.IgnoreListManager.instance(), }; this.contentElement.appendChild(preview.element); ``` ### SymbolizedErrorWidget Displays a complete `SymbolizedError` including recursive causal chains ("Caused by: ...") and syntax error locations. ```ts import * as Panels from '../../panels/panels.js'; import * as Workspace from '../../models/workspace/workspace.js'; const errorWidget = new Panels.Console.SymbolizedErrorWidget(); errorWidget.error = symbolizedError; errorWidget.ignoreListManager = Workspace.IgnoreListManager.IgnoreListManager .instance(); this.contentElement.appendChild(errorWidget.element); ``` --- ## 5. Verification Checklist 1. **Check for Memory Leaks:** Verify `symbolizedError.dispose()` is called on consumer widget cleanup. 2. **Ignore-listing Support:** Ensure widgets have `ignoreListManager` set. 3. **WASM/Inline Support:** Check that inline and WebAssembly frames map correctly via original source maps.