chrome-devtools-frontend 1.0.1706026 → 1.0.1708524

package/.agents/skills/code-review/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: code-review
+description: Generic checklist for reviewing DevTools CLs (your own before upload, or someone else's on Gerrit). Covers test correctness (tautological/vacuous tests, cleanup, leaks), code clarity, CL hygiene, and points to the specialized skills to consult for imports, UI, testing, strings, models, and verification. Use when asked to review a CL, a diff, a patch, or to self-review before `git cl upload`.
+---
+
+# Code Review
+
+This checklist comes from recurring reviewer feedback on landed DevTools CLs.
+Use it for self-review before upload and for reviewing other people's CLs.
+
+## 1. Gather context
+
+- **Local change:** `git diff origin/main...HEAD` (or `git show HEAD` for a
+  single-commit branch). To learn about the branch and upload workflow, see the
+  `devtools-version-control` skill.
+- **Gerrit CL:** strip the leading `)]}'` line from each response to get JSON:
+  - Diff: `git cl diff` (for the current branch), or fetch the patch set.
+  - Inline comments:
+    `curl -s https://chromium-review.googlesource.com/changes/devtools%2Fdevtools-frontend~<CL_NUMBER>/comments | tail -n +2`
+  - Messages:
+    `.../changes/devtools%2Fdevtools-frontend~<CL_NUMBER>/messages`
+- Read the CL description first. Then check that the diff does what the
+  description says, and nothing else.
+
+## 2. Consult the specialized skills
+
+Load the skill that matches what the diff touches, and apply its rules:
+
+| If the diff touches… | Use skill |
+| :--- | :--- |
+| Any `import` statement, or a new cross-module dependency | `devtools-imports` |
+| `UI.Widget`, lit-html views, components, CSS | `devtools-ui-widgets` |
+| Migration of legacy imperative DOM to widgets or Lit | `ui-eng-vision-orchestrator` (and its sub-skills) |
+| New or changed tests: choosing unit, API, or E2E | `devtools-testing-guidance` |
+| Tests that use `describeWithEnvironment` or `describeWithMockConnection`, or foundation modules | `foundation-test-migration` |
+| Ported Chromium web tests (`web_tests/http/tests/devtools`) | `migrate-chromium-test` |
+| Flaky or disabled tests, or `it.skip` / `it.skipOnPlatforms` | `fix-tests` |
+| `UIStrings` / user-facing text | `devtools-ux-writing-refactor` |
+| Rendering user-controlled strings (URLs, names, console text) | `devtools-unicode-escaping` |
+| `front_end/models/*`, `BUILD.gn`, `devtools_grd_files.gni`, entrypoints | `devtools-model-management` |
+| Merging modules or consolidating `BUILD.gn` | `merging-devtools-module` |
+| `Settings` registrations and descriptors | `devtools-setting-migration` |
+| Stack traces, source maps, `DebuggerWorkspaceBinding` | `devtools-source-maps` |
+| Building, running tests, or lint | `devtools-verification` |
+
+## 3. Test correctness (the most common review feedback)
+
+- **Tautological tests:** A test must exercise real production code. If a
+  mock does the thing the test asserts (for example, a mocked `DOM.undo` that
+  calls `removeSection()` directly, followed by an assertion that the section
+  was removed), the test checks the mock and nothing else. Mock the *boundary*
+  instead (for example, have the CDP stub emit `CSSModel.Events.StyleSheetChanged`)
+  and let production code react to it.
+- **Vacuous tests:** Look for local promises or data that are never connected
+  to DevTools logic, or stubs (like `initialize`) that skip the code path under
+  test. These tests pass because nothing happens.
+- **Assertions that check the setup:** For example,
+  `assert.isNull(pane.node())` right after `pane.setNodeForTest(null)`. Each
+  assertion should verify the behavior that the test name describes.
+- **Test lives where it belongs:** A test in `Foo.test.ts` should exercise
+  `Foo`. Move logic-only tests to the model's test file (for example,
+  `CSSMatchedStyles.test.ts`). Otherwise, render the UI and assert on the DOM.
+- **Test covers the scenario it claims:** For example, an "iframe event
+  listeners" test must select a node *inside* the iframe. It is not enough
+  that it passes on `<body>` of the main frame.
+- **Right suite:** Ask whether an E2E test could be a unit test, or whether the
+  E2E coverage is intentional for a user story. See `devtools-testing-guidance`.
+- **E2E selectors match real UI:** Labels and `aria-label`s must match the
+  actual strings, for example "Show user agent shadow DOM" and not "User agent
+  shadow DOM". Check that the setting being toggled actually affects the
+  scenario.
+- **Fail fast:** Throw or assert when a required value is missing. Don't let
+  the test time out later.
+
+## 4. Test hygiene and cleanup
+
+- Pair every `beforeEach` singleton creation with a cleanup in `afterEach`
+  (for example, `CSSWorkspaceBinding.removeInstance()` or
+  `WorkspaceImpl.removeInstance()`) so that state does not leak between tests.
+- Restore fake timers in `try { … } finally { clock.restore(); }`, or use the
+  sandbox or cleanup that the test runner provides. Keep the scope of fake
+  timers small.
+- Don't stub the same method twice without calling `restore()` first. Sinon
+  throws `Attempted to wrap … which is already wrapped` when the object is the
+  same instance.
+- Remove guards that were copied from helpers for no reason (for example,
+  `if (!stub.called) …` in a test that stubs the method only once).
+
+## 5. Code clarity
+
+- Don't take detours to reach a value. If a module is imported, call
+  `TextUtils.TextRange.TextRange.fromObject(...)` directly instead of going
+  through `rule.style.range.constructor`.
+- Look for dead code, leftover debug code, commented-out blocks, and unrelated
+  formatting churn.
+- Check that the change stays in scope. Flag unrelated refactors that should be
+  split into a separate CL.
+- Check for lifecycle issues: event listeners and observers that are added
+  without being removed, and async work that continues after a widget is
+  detached.
+
+## 6. CL hygiene
+
+- The description explains *why*, including external dependencies (for
+  example, "V8 will stop emitting X; this must land first").
+- Include a `Bug:` or `Fixed:` trailer, or `Bug: None`. Keep lines under 72
+  characters.
+- For migrations and stacked series, list the legacy tests or files covered,
+  and number the series (for example, `(13/16)`).
+- Disabled tests reference a bug.
+- Presubmit, lint, and format pass. See `devtools-verification`.
+
+## 7. Writing review comments
+
+- Be specific: cite file and line, explain the concrete failure mode (such as
+  a leak, a hang, or "passes vacuously"), and suggest a fix. Include a code
+  snippet when it helps.
+- Separate blocking issues from nits and questions (for example, "Should we
+  move this to a unit test?").
+- When a reviewer's concern is not an actual bug, reply with the rationale.
+  Don't make a silent change.

package/front_end/core/sdk/DOMModel.ts

@@ -1139,7 +1139,7 @@ export class DOMNode extends Common.ObjectWrapper.ObjectWrapper<DOMNodeEventType
   }
 
   isCustomElement(): boolean {
-    if (this.nodeType() !== NodeType.ELEMENT_NODE || this.isXMLNode()) {
+    if (this.nodeType() !== NodeType.ELEMENT_NODE || this.isXMLNode() || Boolean(this.pseudoType())) {
       return false;
     }
     const localName = this.localName() || this.nodeName().toLowerCase();
@@ -1600,11 +1600,18 @@ export class DOMDocument extends DOMNode {
     this.#frameId = frameId ?? null;
 
     const resourceTreeModel = this.domModel().target().model(ResourceTreeModel);
-    const frame = this.#frameId ? resourceTreeModel?.frameForId(this.#frameId) : resourceTreeModel?.mainFrame;
-    // In production, DOMDocument should always resolve its security origin from an
-    // associated frame, but falls back to SecurityOrigin.create() as a last resort
-    // for test environments where no frame exists.
-    this.#securityOrigin = frame?.securityOrigin() ?? SecurityOrigin.create(this.#documentURL);
+    const frame = this.#frameId ? resourceTreeModel?.frameForId(this.#frameId) : null;
+    if (frame) {
+      this.#securityOrigin = frame.securityOrigin();
+    } else if (resourceTreeModel?.mainFrame) {
+      // If the target has an active frame tree, a DOMDocument without a matching
+      // frame is a detached document and must be isolated with an opaque origin.
+      this.#securityOrigin = SecurityOrigin.createUniqueOpaque();
+    } else {
+      // TODO(b/567434846): Migrate synthetic unit tests to attach frames so this
+      // fallback to parsing documentURL can be removed.
+      this.#securityOrigin = SecurityOrigin.create(this.#documentURL);
+    }
   }
 
   get documentURL(): Platform.DevToolsPath.UrlString {

package/front_end/core/sdk/NetworkRequest.ts

@@ -179,6 +179,7 @@ export class NetworkRequest extends Common.ObjectWrapper.ObjectWrapper<EventType
   #blockedReason: Protocol.Network.BlockedReason|undefined = undefined;
   #renderBlockingBehavior?: Protocol.Network.RenderBlockingBehavior;
   #initiatorSecurityOrigin?: SecurityOrigin;
+  #requestURLSecurityOrigin?: SecurityOrigin;
   #corsErrorStatus: Protocol.Network.CorsErrorStatus|undefined = undefined;
   statusCode = 0;
   statusText = '';
@@ -193,6 +194,7 @@ export class NetworkRequest extends Common.ObjectWrapper.ObjectWrapper<EventType
   #resourceType: Common.ResourceType.ResourceType = Common.ResourceType.resourceTypes.Other;
   #contentData: Promise<TextUtils.ContentData.ContentDataOrError>|null = null;
   #streamingContentData: Promise<TextUtils.StreamingContentData.StreamingContentDataOrError>|null = null;
+  #resolvedStreamingContentData: TextUtils.StreamingContentData.StreamingContentData|null = null;
   readonly #frames: WebSocketFrame[] = [];
   #responseHeaderValues: Record<string, string|undefined> = {};
   #responseHeadersText = '';
@@ -402,10 +404,17 @@ export class NetworkRequest extends Common.ObjectWrapper.ObjectWrapper<EventType
    * (`imported-har://${authority}`) to ensure recorded network traffic never collides with
    * live web origins.
    *
+   * The result is cached, so repeated calls return the same instance until the URL or the
+   * imported HAR flag changes. This keeps opaque origins (such as `data:` URLs) same-origin
+   * with themselves.
+   *
    * @see {@link initiatorSecurityOrigin} to obtain the origin of the document that initiated the request.
    */
   requestURLSecurityOrigin(): SecurityOrigin {
-    return this.#resolveSecurityOrigin(this.#url);
+    if (!this.#requestURLSecurityOrigin) {
+      this.#requestURLSecurityOrigin = this.#resolveSecurityOrigin(this.#url);
+    }
+    return this.#requestURLSecurityOrigin;
   }
 
   /**
@@ -422,6 +431,9 @@ export class NetworkRequest extends Common.ObjectWrapper.ObjectWrapper<EventType
    * For imported HAR files, the origin is mapped to an isolated virtual domain
    * (`imported-har://${authority}`) matching the imported initiating document.
    *
+   * The result is cached, so repeated calls return the same instance until the imported HAR
+   * flag changes. This keeps opaque origins same-origin with themselves.
+   *
    * @see {@link requestURLSecurityOrigin} to obtain the origin of the target resource URL being requested.
    */
   initiatorSecurityOrigin(): SecurityOrigin {
@@ -462,6 +474,7 @@ export class NetworkRequest extends Common.ObjectWrapper.ObjectWrapper<EventType
     this.#parsedQueryParameters = undefined;
     this.#name = undefined;
     this.#path = undefined;
+    this.#requestURLSecurityOrigin = undefined;
   }
 
   get documentURL(): Platform.DevToolsPath.UrlString {
@@ -1207,7 +1220,12 @@ export class NetworkRequest extends Common.ObjectWrapper.ObjectWrapper<EventType
   }
 
   setIsImportedHar(isImportedHar: boolean): void {
+    if (this.#isImportedHar === isImportedHar) {
+      return;
+    }
     this.#isImportedHar = isImportedHar;
+    this.#requestURLSecurityOrigin = undefined;
+    this.#initiatorSecurityOrigin = undefined;
   }
 
   setEarlyHintsHeaders(headers: NameValue[]): void {
@@ -1488,9 +1506,11 @@ export class NetworkRequest extends Common.ObjectWrapper.ObjectWrapper<EventType
       }
       // Note that this is save: "streamResponseBody()" always creates base64-based ContentData and
       // for "contentData()" we'll never call "addChunk".
-      return TextUtils.StreamingContentData.StreamingContentData.from(
+      const streamingContentData = TextUtils.StreamingContentData.StreamingContentData.from(
           contentData,
       );
+      this.#resolvedStreamingContentData = streamingContentData;
+      return streamingContentData;
     });
 
     return this.#streamingContentData;
@@ -1510,6 +1530,18 @@ export class NetworkRequest extends Common.ObjectWrapper.ObjectWrapper<EventType
       isRegex: boolean,
       ): Promise<TextUtils.ContentProvider.SearchMatch[]> {
     if (!this.#contentDataProvider) {
+      const cachedContentData = this.finished && !this.failed ?
+          (await this.#contentData ?? this.#resolvedStreamingContentData?.content()) :
+          undefined;
+      if (cachedContentData && !TextUtils.ContentData.ContentData.isError(cachedContentData) &&
+          cachedContentData.isTextContent) {
+        return TextUtils.TextUtils.performSearchInContentData(
+            cachedContentData,
+            query,
+            caseSensitive,
+            isRegex,
+        );
+      }
       return await NetworkManager.searchInRequest(
           this,
           query,
@@ -1940,11 +1972,15 @@ export class NetworkRequest extends Common.ObjectWrapper.ObjectWrapper<EventType
     }
     this.endTime = timestamp;
     if (data) {
-      void this.#streamingContentData?.then(contentData => {
-        if (!TextUtils.StreamingContentData.isError(contentData)) {
-          contentData.addChunk(data);
-        }
-      });
+      if (this.#resolvedStreamingContentData) {
+        this.#resolvedStreamingContentData.addChunk(data);
+      } else {
+        void this.#streamingContentData?.then(contentData => {
+          if (!TextUtils.StreamingContentData.isError(contentData)) {
+            contentData.addChunk(data);
+          }
+        });
+      }
     }
   }
 

package/front_end/core/sdk/SourceMap.ts

@@ -12,7 +12,7 @@ import {scopeTreeForScript} from './ScopeTreeCache.js';
 import type {Script} from './Script.js';
 import {buildOriginalScopes, decodePastaRanges, type NamedFunctionRange} from './SourceMapFunctionRanges.js';
 import {decodeRangeMappings} from './SourceMapRangeMappings.js';
-import {scriptRelativePosition, SourceMapScopesInfo, type TranslatedFrame} from './SourceMapScopesInfo.js';
+import {type RawFrameTranslation, scriptRelativePosition, SourceMapScopesInfo} from './SourceMapScopesInfo.js';
 
 /**
  * Type of the base source map JSON object, which contains the sources and the mappings at the very least, plus
@@ -867,19 +867,10 @@ export class SourceMap {
     return this.#scopesInfo?.findOriginalFunctionScope(position) ?? null;
   }
 
-  isOutlinedFrame(generatedLine: number, generatedColumn: number): boolean {
+  /** See {@link SourceMapScopesInfo.translateRawFrame}. `null` if no scopes information is available. */
+  translateRawFrame(generatedLine: number, generatedColumn: number): RawFrameTranslation|null {
     this.#ensureSourceMapProcessed();
-    return this.#scopesInfo?.isOutlinedFrame(generatedLine, generatedColumn) ?? false;
-  }
-
-  hasInlinedFrames(generatedLine: number, generatedColumn: number): boolean {
-    this.#ensureSourceMapProcessed();
-    return this.#scopesInfo?.hasInlinedFrames(generatedLine, generatedColumn) ?? false;
-  }
-
-  translateCallSite(generatedLine: number, generatedColumn: number): TranslatedFrame[] {
-    this.#ensureSourceMapProcessed();
-    return this.#scopesInfo?.translateCallSite(generatedLine, generatedColumn) ?? [];
+    return this.#scopesInfo?.translateRawFrame(generatedLine, generatedColumn) ?? null;
   }
 }
 

package/front_end/core/sdk/SourceMapScopesInfo.ts

@@ -16,13 +16,16 @@ export class SourceMapScopesInfo {
   readonly #sourceMap: SourceMap;
   readonly #originalScopes: Array<ScopesCodec.OriginalScope[]|null>;
   readonly #generatedRanges: ScopesCodec.GeneratedRange[];
+  /** Whether the scope information was derived from the AST and mappings (see {@link createFromAst}). */
+  readonly #isFromAst: boolean;
 
   #cachedVariablesAndBindingsPresent: boolean|null = null;
 
-  constructor(sourceMap: SourceMap, scopeInfo: ScopesCodec.ScopeInfo) {
+  constructor(sourceMap: SourceMap, scopeInfo: ScopesCodec.ScopeInfo, {isFromAst = false}: {isFromAst?: boolean} = {}) {
     this.#sourceMap = sourceMap;
     this.#originalScopes = scopeInfo.scopes;
     this.#generatedRanges = scopeInfo.ranges;
+    this.#isFromAst = isFromAst;
   }
 
   /**
@@ -114,7 +117,8 @@ export class SourceMapScopesInfo {
       }
     }
 
-    return new SourceMapScopesInfo(sourceMap, {scopes: scopesBySourceUrl, ranges: rootRange ? [rootRange] : []});
+    return new SourceMapScopesInfo(sourceMap, {scopes: scopesBySourceUrl, ranges: rootRange ? [rootRange] : []},
+                                   {isFromAst: true});
 
     /**
      * Finds the correct place in the tree to insert the new scope.
@@ -219,39 +223,17 @@ export class SourceMapScopesInfo {
     }
   }
 
-  /**
-   * @returns true, iff the function surrounding the provided position is marked as "hidden".
-   */
-  isOutlinedFrame(generatedLine: number, generatedColumn: number): boolean {
-    const rangeChain = this.#findGeneratedRangeChain(generatedLine, generatedColumn);
-    return this.#isOutlinedFrame(rangeChain);
-  }
-
-  #isOutlinedFrame(rangeChain: ScopesCodec.GeneratedRange[]): boolean {
-    for (let i = rangeChain.length - 1; i >= 0; --i) {
-      if (rangeChain[i].isStackFrame) {
-        return rangeChain[i].isHidden;
-      }
+  #generatedFrameKind(rangeChain: ScopesCodec.GeneratedRange[]): GeneratedFrameKind {
+    const functionRange = rangeChain.findLast(range => range.isStackFrame);
+    if (!functionRange) {
+      // Top-level code.
+      return GeneratedFrameKind.VISIBLE;
     }
-    return false;
-  }
-
-  /**
-   * @returns true, iff the range surrounding the provided position contains multiple
-   * inlined original functions.
-   */
-  hasInlinedFrames(generatedLine: number, generatedColumn: number): boolean {
-    const rangeChain = this.#findGeneratedRangeChain(generatedLine, generatedColumn);
-    for (let i = rangeChain.length - 1; i >= 0; --i) {
-      if (rangeChain[i].isStackFrame) {
-        // We stop looking for inlined original functions once we reach the current frame.
-        return false;
-      }
-      if (rangeChain[i].callSite) {
-        return true;
-      }
+    if (!functionRange.originalScope) {
+      // For scope information derived from the AST, we merely failed to map the function.
+      return this.#isFromAst ? GeneratedFrameKind.VISIBLE : GeneratedFrameKind.HIDDEN;
     }
-    return false;
+    return functionRange.isHidden ? GeneratedFrameKind.OUTLINED : GeneratedFrameKind.VISIBLE;
   }
 
   /**
@@ -419,54 +401,53 @@ export class SourceMapScopesInfo {
   /**
    * Returns the authored function scope of the function containing the provided generated position.
    */
-  findOriginalFunctionScope({line, column}: ScopesCodec.Position):
+  findOriginalFunctionScope(position: ScopesCodec.Position):
       {scope: ScopesCodec.OriginalScope, url?: Platform.DevToolsPath.UrlString}|null {
+    const rangeChain = this.#findGeneratedRangeChain(position.line, position.column);
+    const functionScope =
+        this.#findFunctionScopeInOriginalScopeChain(this.#innerMostOriginalScope(rangeChain, position));
+    return functionScope ? {scope: functionScope, url: this.#sourceURLOfScope(functionScope)} : null;
+  }
+
+  /**
+   * Returns the inner-most original scope containing the generated `position`. `rangeChain` must be the generated
+   * range chain of `position`.
+   */
+  #innerMostOriginalScope(rangeChain: ScopesCodec.GeneratedRange[],
+                          position: ScopesCodec.Position): ScopesCodec.OriginalScope|undefined {
     // There are 2 approaches:
     //   1) Find the inner-most generated range containing the provided generated position
-    //      and use it's OriginalScope (then walk it outwards until we hit a function).
+    //      and use its OriginalScope.
     //   2) Use the mappings to turn the generated position into an original position.
     //      Then find the inner-most original scope containing that original position.
-    //      Then walk it outwards until we hit a function.
     //
     // Both approaches should yield the same result (assuming the mappings are spec compliant
     // w.r.t. generated ranges). But in the case of "pasta" scopes and extension provided
     // scope info, we only have the OriginalScope parts and mappings without GeneratedRanges.
-
-    let originalInnerMostScope: ScopesCodec.OriginalScope|undefined;
-
     if (this.#generatedRanges.length > 0) {
-      const rangeChain = this.#findGeneratedRangeChain(line, column);
-      originalInnerMostScope = rangeChain.at(-1)?.originalScope;
-    } else {
-      // No GeneratedRanges. Try to use mappings.
-      const entry = this.#sourceMap.findEntry(line, column);
-      if (entry?.sourceIndex === undefined) {
-        return null;
-      }
-      originalInnerMostScope =
-          this.#findOriginalScopeChain(
-                  {sourceIndex: entry.sourceIndex, line: entry.sourceLineNumber, column: entry.sourceColumnNumber})
-              .at(-1);
+      return rangeChain.at(-1)?.originalScope;
     }
 
-    if (!originalInnerMostScope) {
-      return null;
-    }
-
-    const functionScope = this.#findFunctionScopeInOriginalScopeChain(originalInnerMostScope);
-    if (!functionScope) {
-      return null;
+    // No GeneratedRanges. Try to use mappings.
+    const entry = this.#sourceMap.findEntry(position.line, position.column);
+    if (entry?.sourceIndex === undefined) {
+      return undefined;
     }
+    return this
+        .#findOriginalScopeChain(
+            {sourceIndex: entry.sourceIndex, line: entry.sourceLineNumber, column: entry.sourceColumnNumber})
+        .at(-1);
+  }
 
+  /** @returns the URL of the original source that `scope` belongs to. */
+  #sourceURLOfScope(scope: ScopesCodec.OriginalScope): Platform.DevToolsPath.UrlString|undefined {
     // Find the root scope for some given original source, to get the source url.
-    let rootScope: ScopesCodec.OriginalScope = functionScope;
+    let rootScope: ScopesCodec.OriginalScope = scope;
     while (rootScope.parent) {
       rootScope = rootScope.parent;
     }
     const sourceIndex = this.#originalScopes.findIndex(scopes => scopes?.includes(rootScope));
-    const url = sourceIndex !== -1 ? this.#sourceMap.sourceURLForSourceIndex(sourceIndex) : undefined;
-
-    return functionScope ? {scope: functionScope, url} : null;
+    return sourceIndex !== -1 ? this.#sourceMap.sourceURLForSourceIndex(sourceIndex) : undefined;
   }
 
   /**
@@ -513,33 +494,54 @@ export class SourceMapScopesInfo {
   }
 
   /**
-   * Returns one or more original stack frames for this single "raw frame" or call-site.
-   *
-   * @returns An empty array if no mapping at the call-site was found, or the resulting frames
-   * in top-to-bottom order in case of inlining.
-   * @throws If this range is marked "hidden". Outlining needs to be handled externally as
-   * outlined function segments in stack traces can span across bundles.
+   * Translates a single "raw frame" or call-site, including outlined functions. It's the caller's responsibility to
+   * merge outlined frames with their caller(s) (see {@link GeneratedFrameKind}).
    */
-  translateCallSite(generatedLine: number, generatedColumn: number): TranslatedFrame[] {
+  translateRawFrame(generatedLine: number, generatedColumn: number): RawFrameTranslation {
     const rangeChain = this.#findGeneratedRangeChain(generatedLine, generatedColumn);
-    if (this.#isOutlinedFrame(rangeChain)) {
-      throw new Error('SourceMapScopesInfo is unable to translate an outlined function by itself');
+    const kind = this.#generatedFrameKind(rangeChain);
+    if (kind === GeneratedFrameKind.HIDDEN) {
+      return {kind, frames: []};
     }
+    const frame = this.#translateTopFrame(generatedLine, generatedColumn, rangeChain);
+    return {kind, frames: frame ? [frame, ...this.#translateInlinedCallers(rangeChain)] : []};
+  }
+
+  /**
+   * The top-most frame is translated the same, regardless of whether we have inlined functions: The name is the
+   * original function surrounding the generated position, and the location is the mapped generated position.
+   *
+   * If the generated position has no mapping, the generated ranges may still tell which authored function (or
+   * which file, for top-level code) the position belongs to. The frame then has no position.
+   */
+  #translateTopFrame(generatedLine: number, generatedColumn: number,
+                     rangeChain: ScopesCodec.GeneratedRange[]): TranslatedFrame|null {
+    const position = {line: generatedLine, column: generatedColumn};
+    const innerMostScope = this.#innerMostOriginalScope(rangeChain, position);
+    const functionScope = this.#findFunctionScopeInOriginalScopeChain(innerMostScope);
+    const name = functionScope ? (functionScope.name ?? '') : undefined;
 
     const mapping = this.#sourceMap.findEntry(generatedLine, generatedColumn);
-    if (mapping?.sourceIndex === undefined) {
-      return [];
+    if (mapping?.sourceIndex !== undefined) {
+      return {
+        line: mapping.sourceLineNumber,
+        column: mapping.sourceColumnNumber,
+        name,
+        url: mapping.sourceURL,
+        functionStart: functionScope?.start,
+      };
     }
+    if (!innerMostScope) {
+      return null;
+    }
+    return {name, url: this.#sourceURLOfScope(functionScope ?? innerMostScope), functionStart: functionScope?.start};
+  }
 
-    // The top-most frame is translated the same even if we have inlined functions.
-    const result: TranslatedFrame[] = [{
-      line: mapping.sourceLineNumber,
-      column: mapping.sourceColumnNumber,
-      name: this.findOriginalFunctionName({line: generatedLine, column: generatedColumn}) ?? undefined,
-      url: mapping.sourceURL,
-    }];
-
-    // Walk the range chain inside out until we find a generated function and for each inlined function add a frame.
+  /**
+   * Walk the range chain inside out until we find a generated function and for each inlined function add a frame.
+   */
+  #translateInlinedCallers(rangeChain: ScopesCodec.GeneratedRange[]): TranslatedFrame[] {
+    const result: TranslatedFrame[] = [];
     for (let i = rangeChain.length - 1; i >= 0 && !rangeChain[i].isStackFrame; --i) {
       const range = rangeChain[i];
       if (!range.callSite) {
@@ -547,11 +549,13 @@ export class SourceMapScopesInfo {
       }
 
       const originalScopeChain = this.#findOriginalScopeChain(range.callSite);
+      const functionScope = this.#findFunctionScopeInOriginalScopeChain(originalScopeChain.at(-1));
       result.push({
         line: range.callSite.line,
         column: range.callSite.column,
-        name: this.#findFunctionNameInOriginalScopeChain(originalScopeChain.at(-1)) ?? undefined,
+        name: functionScope ? (functionScope.name ?? '') : undefined,
         url: this.#sourceMap.sourceURLForSourceIndex(range.callSite.sourceIndex),
+        functionStart: functionScope?.start,
       });
     }
 
@@ -559,17 +563,61 @@ export class SourceMapScopesInfo {
   }
 }
 
+/**
+ * Describes how the generated function surrounding a generated position shows up in stack traces.
+ *
+ * Compilers tend to introduce functions (and calls to them) that don't exist in the authored code. The scopes
+ * proposal distinguishes two cases:
+ *
+ *   1) The generated function contains authored code, e.g. a block scope that was turned into a function. The
+ *      generated range is marked "hidden", but links to the original scope via its definition. We can pause
+ *      in such a function, but the frame is merged with its caller(s) in stack traces: The outlined code
+ *      logically belongs to the (authored) function that transitively calls it.
+ *
+ *   2) The generated function doesn't represent any authored code, e.g. a compiler helper. The generated range
+ *      has no definition. The scopes spec is being updated to say that such a range can be ignored in stack
+ *      traces, so we drop these frames.
+ */
+export const enum GeneratedFrameKind {
+  /** A regular (possibly with inlined functions) generated function, or top-level code. */
+  VISIBLE = 'VISIBLE',
+  /** A generated function marked as "hidden" that has a definition (case 1). */
+  OUTLINED = 'OUTLINED',
+  /** A generated function without a definition (case 2). */
+  HIDDEN = 'HIDDEN',
+}
+
+/** See {@link SourceMapScopesInfo.translateRawFrame}. */
+export interface RawFrameTranslation {
+  kind: GeneratedFrameKind;
+  /**
+   * [top, ...inlinedCallers] in top-to-bottom order. Empty for {@link GeneratedFrameKind.HIDDEN} frames, or if
+   * neither the mappings nor the generated ranges know anything about the generated position.
+   *
+   * For {@link GeneratedFrameKind.OUTLINED} frames, the top frame is named after the authored function the outlined
+   * code belongs to.
+   */
+  frames: TranslatedFrame[];
+}
+
 /**
  * Represents a stack frame in original terms. It closely aligns with StackTrace.StackTrace.Frame,
  * but since we can't import that type here we mirror it here somewhat.
  *
- * Equivalent to Pick<StackTrace.StackTrace.Frame, 'line'|'column'|'name'|'url'>.
+ * Equivalent to Pick<StackTrace.StackTrace.Frame, 'line'|'column'|'name'|'url'>, except that the position is
+ * optional.
  */
 export interface TranslatedFrame {
-  line: number;
-  column: number;
+  /**
+   * `line` and `column` are undefined iff the generated position has no mapping. The frame then only identifies
+   * the authored function: `name`, `functionStart` and the `url` of the function's source.
+   */
+  line?: number;
+  column?: number;
   name?: string;
   url?: Platform.DevToolsPath.UrlString;
+  /** Start of the original function scope containing this frame's position. Undefined for top-level code. */
+  functionStart?: ScopesCodec.Position;
 }
 
 export function findExpression(range: ScopesCodec.GeneratedRange|undefined, index: number, line = 0,

package/front_end/core/text_utils/ContentData.ts

@@ -19,6 +19,23 @@ const objectUrlRegistry = new FinalizationRegistry<string>(url => {
  */
 const MAX_BLOB_SIZE_BYTES = 10 * 1024 * 1024;
 
+/**
+ * Returns `charset` if `TextDecoder` supports it, and 'utf-8' otherwise.
+ * The charset usually comes straight from a `Content-Type` header, and
+ * `TextDecoder` has no non-throwing way to check a label.
+ */
+function supportedCharsetOrUtf8(charset: string|undefined): string {
+  if (!charset) {
+    return 'utf-8';
+  }
+  try {
+    new TextDecoder(charset);
+    return charset;
+  } catch {
+    return 'utf-8';
+  }
+}
+
 /**
  * This class is a small wrapper around either raw binary or text data.
  * As the binary data can actually contain textual data, we also store the
@@ -44,7 +61,7 @@ export class ContentData {
   #imagePreviewUrl?: string;
 
   constructor(data: string, isBase64: boolean, mimeType: string, charset?: string) {
-    this.charset = charset || 'utf-8';
+    this.charset = supportedCharsetOrUtf8(charset);
     if (isBase64) {
       this.#contentAsBase64 = data;
     } else {