chrome-devtools-frontend 1.0.1520535 → 1.0.1521746

package/docs/checklist/README.md

@@ -1,4 +1,4 @@
-# Chromium DevTools support checklist (for Blink Intents)
+# Chromium DevTools support checklist (for [Blink Intents](https://developer.chrome.com/docs/web-platform/blink-intents))
 
 [goo.gle/devtools-checklist](https://goo.gle/devtools-checklist)
 
@@ -6,20 +6,28 @@
 
 Many new Web Platform Features (WPFs) can piggyback off of DevTools' general tooling for HTML, DOM, CSS, JavaScript,
 WebAssembly, Network, and other aspects — requiring only minimal or no changes to make DevTools behave as expected
-in light of the new WPF. This document refers to such cases as _basic tooling_.
+in light of the new WPF. This document refers to such cases as _basic support_.
 
 However, some WPFs might warrant larger changes, including brand-new DevTools features. This document refers to such
-cases as _extended tooling_.
+cases as _extended support_.
+
+**What is basic support?**
+Basic support ensures that a new WPF is introspectable and DevTools does not break or crash Chromium in its presence. In addition, developers should have a way of knowing if their web application uses this WPF correctly. Definitions and examples of basic support for common WPF categories can be found below.
+
+**What is extended support?**
+Extended support involves dedicated, custom tooling to reduce friction and ensure the adoption of a new Web Platform Feature. It is considered on a case-by-case basis, typically for WPFs that are particularly complex and/or expected to be very popular. Examples include a custom UI editor for a new CSS feature (e.g. the flexbox editor) or dedicated debugging support in the Network panel for a new protocol (e.g. WebSocket).
+
+Extended support is not a requirement for shipping a WPF. If you believe your feature requires extended support, please refer to the [guidelines for working with the DevTools team](../playbook.md) to start the discussion.
 
 It’s the WPF owner’s responsibility to ensure the tooling story is thought through, by answering the question:
 _"how would a web developer making use of your new WPF test and debug their code?"_
 
-- Basic tooling must be implemented before shipping a new WPF.
-- Extended functionality must be considered on a case-by-case basis, and could in some cases be allowed to launch after shipping the WPF.
+- Basic support must be implemented before shipping a new WPF.
+- Extended support must be considered on a case-by-case basis, and is not tightly bound to or blocking a WPF's shipping.
 
-This document captures examples of different kinds of WPFs, the tooling support they require, and how this can be achieved.
+The following sections capture examples of different kinds of WPFs, the tooling support they require, and how this can be achieved.
 
-*** note
+***
 **IMPORTANT:** Please take a look at the [DevTools UI feature checklist](./ui.md) prior
 to changing or extending the DevTools user interface (UI).
 ***
@@ -36,27 +44,35 @@ See the [Chromium DevTools support checklist for JavaScript language features](h
 See the [Chromium DevTools checklist for WebAssembly features](https://goo.gle/devtools-wasm-checklist).
 
 
-## New HTML elements
+## DOM, HTML, and Web APIs
+
+### New HTML elements
+
+> **Basic support requirement:** The new element is displayed in the DOM tree with the correct tag name and structure, and both the element and its attributes are editable.
+
+This is often automatically supported because the Elements panel directly reflects the browser's internal DOM representation; any element that the browser can parse and add to the DOM will therefore appear in the tree. Verify that inspecting the new element in the Elements tab looks alright and works as expected (typically, this requires no additional implementation effort).
 
-New HTML elements get basic tooling support through the DevTools Elements panel. Verify that inspecting the new element
-in the Elements tab looks alright and works as expected (typically, this requires no additional implementation effort).
+### New WebIDL/DOM interfaces and attributes
 
+> **Basic support requirement:** New interfaces, attributes, and methods are accessible as properties on their corresponding DOM objects in the Console and appear in autocomplete suggestions.
 
-## New WebIDL/DOM interfaces and attributes
+This is often automatically supported because the DevTools Console has access to the same JavaScript runtime as the page. Any property that is programmatically accessible on a DOM object will be discoverable by the Console's autocomplete mechanism.
 
-Verify that the new properties show up in the DevTools Console autocomplete functionality (typically, this requires no additional implementation effort).
-To enable argument hints for new or changed parameterized functions, run
+Verify that the new properties show up in the DevTools Console autocomplete functionality. To enable argument hints for new or changed parameterized functions, run
 ```bash
 devtools-frontend/src/scripts/deps/roll_deps.py
 ```
-to re-generate `devtools-frontend/src/front_end/models/javascript\_metadata/NativeFunctions.js` ([Example CL](http://crrev.com/c/3432787)).
+to re-generate `devtools-frontend/src/front_end/models/javascript\_metadata/NativeFunctions.js` ([Example CL](http://crrev.com/c/3432787)). For more details, see the [Chromium DevTools support checklist for JavaScript language features](https://goo.gle/v8-checklist).
 
 ![](./images/checklist-autocomplete-idl-attribute.png "Console autocompletion for IDL attributes")
 
+### New DOM events
 
-## New DOM events
+> **Basic support requirement:** The new DOM event is discoverable. This means it must (1) appear in the **Event Listeners** sidebar tab in the Elements panel when a listener for it is added to an element, and (2) be listed under an appropriate category in the **Event Listener Breakpoints** tab in the Sources panel.
 
-DevTools supports setting breakpoints on DOM events via the Sources tab → Event Listener Breakpoints. Make sure the new event is exposed under the relevant category.
+Displaying the event in the Elements panel's 'Event Listeners' tab is often automatically supported, as this tab reflects the runtime state of the element.
+
+However, adding the event to the 'Event Listener Breakpoints' tab is not automatic. The list of debuggable events is maintained in the DevTools frontend. Adding a new event requires modifying this list to make it visible in the UI under an "appropriate category" (a logical grouping like `Mouse` or `Keyboard`). If a suitable category doesn't exist, a new one should be created.
 
 ![](./images/checklist-event-listener-breakpoints.png "Event Listener Breakpoints")
 
@@ -65,28 +81,38 @@ Pointer: [`front_end/core/sdk/DOMDebuggerModel.ts`](https://source.chromium.org/
 
 ## CSS
 
-For CSS WPFs, basic tooling support involves the ability to view and edit styles via the DevTools Styles panel.
+For CSS WPFs, basic support involves the ability to view and edit styles via the DevTools Styles tab.
 This mostly works out of the box, but some minimal changes might be needed depending on the specifics.
 
 ### New CSS at-rules
 
+> **Basic support requirement:** The new at-rule and its contents are displayed in the Styles tab, correctly linked to the stylesheet, and editable.
+
 WPFs that introduce new CSS at-rules (i.e. `@foo (bar: baz) { … }`) must surface the new at-rules over the Chrome
-DevTools Protocol (CDP) so that DevTools can show them in the Styles panel.
+DevTools Protocol (CDP) so that DevTools can show them in the Styles tab. Interlinking the at-rule to the style rules that reference it (e.g., linking a `@property` definition to its usage) is considered extended support and is not a requirement for shipping.
 Please refer to [goo.gle/devtools-generic-at](https://goo.gle/devtools-generic-at) for instructions and examples on
 how to add DevTools support for a new at-rule.
 
 ### New CSS pseudo-classes
 
-WPFs that introduce a new CSS pseudo-class must surface the new pseudo-class in the Force element state UI within the Styles tab.
+> **Basic support requirement:** The new pseudo-class must be toggleable in the 'Force element state' UI. When the pseudo-class is active, the corresponding style rules must appear and be editable in the Styles tab, just like any other style rule.
+
+To add a new pseudo-class to the UI, you must add it to the list of states in the constructor of `ElementStatePaneWidget`.
 
 ![](./images/checklist-pseudo-classes.png "Pseudo classes in the Styles tab")
 
+Pointer: [`front_end/panels/elements/ElementStatePaneWidget.ts`](https://source.chromium.org/chromium/chromium/src/+/main:third_party/devtools-frontend/src/front_end/panels/elements/ElementStatePaneWidget.ts)
+
 Example for `:target`: [Chromium back-end CL](https://chromium-review.googlesource.com/c/chromium/src/+/2575668),
 [DevTools front-end CL](https://chromium-review.googlesource.com/c/devtools/devtools-frontend/+/2581544).
 
 ### New CSS properties or values
 
-To recognize new CSS properties/values in the DevTools Styles panel’s autocomplete functionality, roll
+> **Basic support requirement:** The new CSS property or value is recognized by the Styles tab, autocompletes correctly, and does not show up as an "Unknown Property".
+
+Any new CSS property that is applied to an element should also appear correctly in the **Computed** tab of the Elements panel, displaying its resolved value. This is generally automatic, as the Computed tab reflects the browser's computed style.
+
+To recognize new CSS properties/values in the DevTools Styles tab’s autocomplete functionality, roll
 [Chromium’s `css_properties.json5`](https://source.chromium.org/chromium/chromium/src/+/main:third\_party/blink/renderer/core/css/css_properties.json5;drc=be2c473625b9c28a4ff6735547cb0c1b6743f4ae) into the `devtools-frontend` repository by running
 ```bash
 devtools-frontend/src/scripts/deps/roll_deps.py
@@ -95,26 +121,53 @@ see this [example CL](https://chromium-review.googlesource.com/c/devtools/devtoo
 
 ![](./images/checklist-css-properties.png "CSS property value completion")
 
+Additionally, verify that the Styles tab tooltips showing the property's definition and baseline status are correct and up-to-date. Otherwise, let DevTools team know that this should be updated.
+
+### New CSS Functions and Value Indirection
+
+> **Basic support requirement:** The new function or value mechanism is correctly parsed and displayed in the Styles tab, showing the *authored* value (e.g., `var(--my-color)`). Hovering over the value should reveal its computed result in a tooltip. The function name should also be autocompleted.
+
+Support for new CSS functions and other forms of value indirection (like CSS custom properties via `var()`) is a mix of automatic and manual work. While the browser's backend handles parsing and computation, ensuring the DevTools UI provides features like autocomplete for new function names or value tracing in hover-to-resolve tooltips require frontend changes. Value tracing example can be found [here](https://chromium-review.googlesource.com/c/devtools/devtools-frontend/+/6269777).
+
+### New CSS pseudo-elements
+
+> **Basic support requirement:** If the new pseudo-element is tree-abiding, it is displayed in the DOM tree (usually as a child of its originating element) and can be selected to inspect and edit its styles in the Styles tab. If it participates in style cascade of its originating element, its participating style should show up in the originating element's Style tab sections as well (e.g. Pseudo ::before element section).
+
+Support for new pseudo-elements is not automatic. The browser's backend must be updated to expose the new pseudo-element over the Chrome DevTools Protocol (CDP). Additionally, the DevTools frontend must be updated to recognize and display these pseudo-elements in the Elements panel.
+
+Pointers: [InspectorDOMAgent's supported pesudos](https://source.chromium.org/chromium/chromium/src/+/main:third_party/blink/renderer/core/inspector/inspector_dom_agent.cc;l=122;drc=90e6a37b7c43154ea99d7cc7ff632ee181078fb2), [InspectorStyleResolver's list of supported pseudo-elements](https://source.chromium.org/chromium/chromium/src/+/main:third_party/blink/renderer/core/inspector/inspector_style_resolver.cc;l=57-71;drc=c182cb38dc164e2b83c75cdf8699b076dfe6bc5e), and [DevTools Frontend DOMModel updates example CL](https://chromium-review.googlesource.com/c/devtools/devtools-frontend/+/6195233).
+
 
 ## Network-related features
 
-Any WPFs that have the ability to initiate requests or otherwise involve the network stack must ensure such requests
-are captured in the DevTools Network tab.
+### New request types
+
+> **Basic support requirement:** Any request initiated by the feature must appear as a distinct row in the Network panel with the correct **Type** (e.g., 'fetch', 'image'). This includes, at a minimum, the URL, status, method, size, and timing. Crucially, the **Initiator** column must correctly identify the source of the request.
+
+Support for new request types is not automatic. It requires instrumenting the browser's network stack to send the right information to DevTools via the Chrome DevTools Protocol (CDP). The DevTools frontend may also need to be updated to correctly classify and display the new request type.
+
+Pointer: The `ResourceType` class in [`front_end/core/common/ResourceType.ts`](https://source.chromium.org/chromium/chromium/src/+/main:third_party/devtools-frontend/src/front_end/core/common/ResourceType.ts) is the source of truth for request types in the frontend.
+
+### New network protocols or data formats
+
+> **Basic support requirement:** The new protocol or data format is identifiable in the Network panel. For new protocols, individual frames or messages should be inspectable. For new data formats, the response should be displayed in a format that is at least debuggable.
+
+Note that this level of support often requires significant implementation in both the browser's backend and the DevTools frontend to correctly interpret and display the new protocol's data. Aim for correctness first, then consider improving UX in a follow-up.
 
-Some WPFs might warrant extended tooling, for example, [Trust Tokens](http://crbug.com/1126824) got their own tab in
-DevTools’ Network panel:
+---
+*Extended support might involve a dedicated panel for a new protocol, such as the one for WebSockets, [DirectSockets CL1](https://chromium-review.googlesource.com/c/devtools/devtools-frontend/+/6316791), [DirectSockets CL2](https://chromium-review.googlesource.com/c/devtools/devtools-frontend/+/6406321), or the custom tab for [Trust Tokens](http://crbug.com/1126824) shown below.*
 
 ![](./images/checklist-network-trust-tokens.png "Trust Tokens tab in the Network panel")
 
 
-## PWA features
+## Storage, Workers, and Background Services
 
 WPFs related to Web Application Manifest, service workers, background services, notifications, storage, caching are
 covered under the DevTools Application tab. Given the broad scope of features captured here, there is no generic
 guidance that applies, other than: review the existing DevTools functionality related to your WPF, and ensure the
 new WPF works well with it.
 
-Depending on the WPF specifics, extended tooling might be warranted. For example, [Trust Tokens](http://crbug.com/1126824)
+Depending on the WPF specifics, extended support might be warranted. For example, [Trust Tokens](http://crbug.com/1126824)
 shipped with a new subpanel under the Application tab:
 
 ![](./images/checklist-application-trust-tokens.png "Trust Tokens tab in the Application panel")
@@ -126,7 +179,7 @@ your Intent email.
 ## Warnings, deprecations, removals
 
 If your Blink Intent is about the deprecation/removal of a WPF, or an otherwise risky change from a Web compatibility
-standpoint, the basic tooling support requirement can be satisfied by integrating with DevTools’ Issues panel. See
+standpoint, the basic support requirement can be satisfied by integrating with DevTools’ Issues panel. See
 [how to pipe your messages into the Issues tab](https://docs.google.com/document/d/13zZBu6RG7D23FSWecSy3AHPEdFHJMkp732-uJ5CFbmc)
 for details.
 

package/front_end/core/host/InspectorFrontendHost.ts

@@ -401,6 +401,9 @@ export class InspectorFrontendHostStub implements InspectorFrontendHostAPI {
       devToolsFlexibleLayout: {
         verticalDrawerEnabled: true,
       },
+      devToolsStartingStyleDebugging: {
+        enabled: false,
+      },
     };
     if ('hostConfigForTesting' in globalThis) {
       const {hostConfigForTesting} = (globalThis as unknown as {hostConfigForTesting: Root.Runtime.HostConfig});

package/front_end/core/root/Runtime.ts

@@ -499,6 +499,10 @@ interface DevToolsFlexibleLayout {
   verticalDrawerEnabled: boolean;
 }
 
+interface DevToolsStartingStyleDebugging {
+  enabled: boolean;
+}
+
 /**
  * The host configuration that we expect from the DevTools back-end.
  *
@@ -544,6 +548,7 @@ export type HostConfig = Platform.TypeScriptUtilities.RecursivePartial<{
   devToolsGdpProfilesAvailability: GdpProfilesAvailability,
   devToolsLiveEdit: LiveEdit,
   devToolsFlexibleLayout: DevToolsFlexibleLayout,
+  devToolsStartingStyleDebugging: DevToolsStartingStyleDebugging,
 }>;
 
 /**

package/front_end/core/sdk/CSSModel.ts

@@ -462,6 +462,12 @@ export class CSSModel extends SDKModel<EventTypes> {
     return new InlineStyleResult(inlineStyle, attributesStyle);
   }
 
+  forceStartingStyle(node: DOMNode, forced: boolean): boolean {
+    void this.agent.invoke_forceStartingStyle({nodeId: node.id, forced});
+    this.dispatchEventToListeners(Events.StartingStylesStateForced, node);
+    return true;
+  }
+
   forcePseudoState(node: DOMNode, pseudoClass: string, enable: boolean): boolean {
     const forcedPseudoClasses = node.marker<string[]>(PseudoStateMarker) || [];
     const hasPseudoClass = forcedPseudoClasses.includes(pseudoClass);
@@ -938,6 +944,7 @@ export enum Events {
   ModelWasEnabled = 'ModelWasEnabled',
   ModelDisposed = 'ModelDisposed',
   PseudoStateForced = 'PseudoStateForced',
+  StartingStylesStateForced = 'StartingStylesStateForced',
   StyleSheetAdded = 'StyleSheetAdded',
   StyleSheetChanged = 'StyleSheetChanged',
   StyleSheetRemoved = 'StyleSheetRemoved',
@@ -966,6 +973,7 @@ export interface EventTypes {
   [Events.ModelWasEnabled]: void;
   [Events.ModelDisposed]: CSSModel;
   [Events.PseudoStateForced]: PseudoStateForcedEvent;
+  [Events.StartingStylesStateForced]: DOMNode;
   [Events.StyleSheetAdded]: CSSStyleSheetHeader;
   [Events.StyleSheetChanged]: StyleSheetChangedEvent;
   [Events.StyleSheetRemoved]: CSSStyleSheetHeader;

package/front_end/core/sdk/CSSRule.ts

@@ -11,6 +11,7 @@ import {CSSLayer} from './CSSLayer.js';
 import {CSSMedia} from './CSSMedia.js';
 import type {CSSModel, Edit} from './CSSModel.js';
 import {CSSScope} from './CSSScope.js';
+import {CSSStartingStyle} from './CSSStartingStyle.js';
 import {CSSStyleDeclaration, Type} from './CSSStyleDeclaration.js';
 import type {CSSStyleSheetHeader} from './CSSStyleSheetHeader.js';
 import {CSSSupports} from './CSSSupports.js';
@@ -108,6 +109,7 @@ export class CSSStyleRule extends CSSRule {
   scopes: CSSScope[];
   layers: CSSLayer[];
   ruleTypes: Protocol.CSS.CSSRuleType[];
+  startingStyles: CSSStartingStyle[];
   wasUsed: boolean;
   constructor(cssModel: CSSModel, payload: Protocol.CSS.CSSRule, wasUsed?: boolean) {
     super(cssModel, {origin: payload.origin, style: payload.style, header: styleSheetHeaderForRule(cssModel, payload)});
@@ -120,6 +122,8 @@ export class CSSStyleRule extends CSSRule {
     this.scopes = payload.scopes ? CSSScope.parseScopesPayload(cssModel, payload.scopes) : [];
     this.supports = payload.supports ? CSSSupports.parseSupportsPayload(cssModel, payload.supports) : [];
     this.layers = payload.layers ? CSSLayer.parseLayerPayload(cssModel, payload.layers) : [];
+    this.startingStyles =
+        payload.startingStyles ? CSSStartingStyle.parseStartingStylePayload(cssModel, payload.startingStyles) : [];
     this.ruleTypes = payload.ruleTypes || [];
     this.wasUsed = wasUsed || false;
   }

package/front_end/core/sdk/CSSStartingStyle.ts

@@ -0,0 +1,29 @@
+// Copyright 2025 The Chromium Authors
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+import type * as Protocol from '../../generated/protocol.js';
+import * as TextUtils from '../../models/text_utils/text_utils.js';
+
+import type {CSSModel} from './CSSModel.js';
+import {CSSQuery} from './CSSQuery.js';
+
+export class CSSStartingStyle extends CSSQuery {
+  static parseStartingStylePayload(cssModel: CSSModel, payload: Protocol.CSS.CSSStartingStyle[]): CSSStartingStyle[] {
+    return payload.map(p => new CSSStartingStyle(cssModel, p));
+  }
+
+  constructor(cssModel: CSSModel, payload: Protocol.CSS.CSSStartingStyle) {
+    super(cssModel);
+    this.reinitialize(payload);
+  }
+
+  reinitialize(payload: Protocol.CSS.CSSStartingStyle): void {
+    this.range = payload.range ? TextUtils.TextRange.TextRange.fromObject(payload.range) : null;
+    this.styleSheetId = payload.styleSheetId;
+  }
+
+  active(): boolean {
+    return true;
+  }
+}

package/front_end/core/sdk/DOMModel.ts

@@ -126,6 +126,7 @@ export class DOMNode {
   #xmlVersion!: string|undefined;
   #isSVGNode!: boolean;
   #isScrollable!: boolean;
+  #affectedByStartingStyles!: boolean;
   #creationStackTrace: Promise<Protocol.Runtime.StackTrace|null>|null = null;
   #pseudoElements = new Map<string, DOMNode[]>();
   #distributedNodes: DOMNodeShortcut[] = [];
@@ -194,6 +195,7 @@ export class DOMNode {
     this.#xmlVersion = payload.xmlVersion;
     this.#isSVGNode = Boolean(payload.isSVG);
     this.#isScrollable = Boolean(payload.isScrollable);
+    this.#affectedByStartingStyles = Boolean(payload.affectedByStartingStyles);
     this.#retainedNodes = retainedNodes;
 
     if (this.#retainedNodes?.has(this.backendNodeId())) {
@@ -296,6 +298,10 @@ export class DOMNode {
     return this.#isScrollable;
   }
 
+  affectedByStartingStyles(): boolean {
+    return this.#affectedByStartingStyles;
+  }
+
   isMediaNode(): boolean {
     return this.#nodeName === 'AUDIO' || this.#nodeName === 'VIDEO';
   }
@@ -349,6 +355,10 @@ export class DOMNode {
     this.#isScrollable = isScrollable;
   }
 
+  setAffectedByStartingStyles(affectedByStartingStyles: boolean): void {
+    this.#affectedByStartingStyles = affectedByStartingStyles;
+  }
+
   hasAttributes(): boolean {
     return this.#attributes.size > 0;
   }
@@ -1565,6 +1575,15 @@ export class DOMModel extends SDKModel<EventTypes> {
     this.dispatchEventToListeners(Events.ScrollableFlagUpdated, {node});
   }
 
+  affectedByStartingStylesFlagUpdated(nodeId: Protocol.DOM.NodeId, affectedByStartingStyles: boolean): void {
+    const node = this.nodeForId(nodeId);
+    if (!node || node.affectedByStartingStyles() === affectedByStartingStyles) {
+      return;
+    }
+    node.setAffectedByStartingStyles(affectedByStartingStyles);
+    this.dispatchEventToListeners(Events.AffectedByStartingStylesFlagUpdated, {node});
+  }
+
   topLayerElementsUpdated(): void {
     this.dispatchEventToListeners(Events.TopLayerElementsChanged);
   }
@@ -1751,6 +1770,7 @@ export enum Events {
   MarkersChanged = 'MarkersChanged',
   TopLayerElementsChanged = 'TopLayerElementsChanged',
   ScrollableFlagUpdated = 'ScrollableFlagUpdated',
+  AffectedByStartingStylesFlagUpdated = 'AffectedByStartingStylesFlagUpdated',
   /* eslint-enable @typescript-eslint/naming-convention */
 }
 
@@ -1767,6 +1787,7 @@ export interface EventTypes {
   [Events.MarkersChanged]: DOMNode;
   [Events.TopLayerElementsChanged]: void;
   [Events.ScrollableFlagUpdated]: {node: DOMNode};
+  [Events.AffectedByStartingStylesFlagUpdated]: {node: DOMNode};
 }
 
 class DOMDispatcher implements ProtocolProxyApi.DOMDispatcher {
@@ -1839,7 +1860,9 @@ class DOMDispatcher implements ProtocolProxyApi.DOMDispatcher {
     this.#domModel.scrollableFlagUpdated(nodeId, isScrollable);
   }
 
-  affectedByStartingStylesFlagUpdated(_: Protocol.DOM.AffectedByStartingStylesFlagUpdatedEvent): void {
+  affectedByStartingStylesFlagUpdated({nodeId, affectedByStartingStyles}:
+                                          Protocol.DOM.AffectedByStartingStylesFlagUpdatedEvent): void {
+    this.#domModel.affectedByStartingStylesFlagUpdated(nodeId, affectedByStartingStyles);
   }
 }