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
- Never parse raw error stacks manually: Do not split on newlines or use
homebrew regex to parse stack traces. Use
DebuggerWorkspaceBindinghelpers to structurally parse and translate stack traces. - Dispose of subscriptions: Models like
SymbolizedErrorsubscribe to live locations. Always call.dispose()when the consumer (e.g., a widget or list) is destroyed to avoid memory leaks. - Prefer pre-built widgets: Instead of manually formatting or rendering
call frames, use
StackTracePreviewContentfor raw stacks, andSymbolizedErrorWidgetfor 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 aStackTrace.Events.UPDATEDevent when the original sources are fully resolved or update.Frame: Represents a single frame, which containsuiSourceCode,url, line/column info, untranslatedrawName, translatedname, and inline information.
B. SymbolizedError Model (front_end/models/bindings/SymbolizedError.ts)
A union type representing a fully symbolized error.
SymbolizedErrorObject: Contains errormessage,stackTrace(as aParsedErrorStackTrace), and an optionalcause(anotherSymbolizedError). Also holds compile/evalsyntaxErrorLocation.UnparsableError: Fallback when parsing fails.
3. Core APIs on DebuggerWorkspaceBinding
Location Translation
Translates raw coordinates into UI-friendly original source coordinates:
const uiLocation = await Bindings.DebuggerWorkspaceBinding.instance()
.rawLocationToUILocation(rawLocation);
StackTrace & Error Generation
- From Protocol Stack Trace (Runtime Domain):
const stack = await Bindings.DebuggerWorkspaceBinding.instance() .createStackTraceFromProtocolRuntime(protocolStackTrace, target); - From Debugger Pause details:
const stack = await Bindings.DebuggerWorkspaceBinding.instance() .createStackTraceFromDebuggerPaused(pausedDetails, target); - From a Raw Error Stack string:
const stack = await Bindings.DebuggerWorkspaceBinding.instance() .createStackTraceFromErrorStackLikeString(target, stackString, exceptionDetails); - From a Remote Error Object:
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.
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.
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
- Check for Memory Leaks: Verify
symbolizedError.dispose()is called on consumer widget cleanup. - Ignore-listing Support: Ensure widgets have
ignoreListManagerset. - WASM/Inline Support: Check that inline and WebAssembly frames map correctly via original source maps.