chrome-devtools-frontend 1.0.1593959 → 1.0.1595925

package/docs/contributing/settings-experiments-features.md

@@ -103,18 +103,38 @@ Root.Runtime.experiments.registerHostExperiment({
 
 `requiresChromeRestart` should be set to `true` if the `base::Feature` is used for conditionally
 running code in the Chromium repository as well. If it only affects code paths in the DevTools
-repository, `requiresChromeRestart` can be set to `false`. This means that toggling the
+repository, `requiresChromeRestart` should be set to `false`. This means that toggling the
 experimental feature requires only reloading DevTools and not restarting Chrome.
 
 You may also pass in two additional arguments which can be used to link users to documentation and
-a way to provide feedback.
+to a place for providing feedback.
 
 You must also add the experiment to [UserMetrics.ts](https://crsrc.org/c/third_party/devtools-frontend/src/front_end/core/host/UserMetrics.ts;l=807).
 Add an entry to the `DevToolsExperiments` enum, incrementing the `MAX_VALUE` by 1 and assigning the
-un-incremented value to your experiment. There are gaps in the values assigned to experiments. This
-is explained by the fact that expired experiments are removed from the codebase.
+un-incremented value to your experiment (the gaps in the values assigned to experiments are caused
+by expired experiments which are no longer part of the codebase).
 
-#### Step 2: Add the experiment to enums.xml in the Chromium repository
+#### Step 2: Update UI bindings to allow toggling the experiment from the DevTools UI
+
+In the scenario of allowing users to toggle the experiment from the DevTools UI, when assembling
+the host config to be sent to DevTools, use the `GetFeatureStateForDevTools` helper to determine
+the enabled/disabled state of the experiment.
+
+```cxx
+response_dict.Set(
+  "devToolsNewFeature",
+  base::DictValue().Set(
+    "enabled",
+    GetFeatureStateForDevTools(
+      ::features::kDevToolsNewFeature,
+      enabled_by_flags,
+      disabled_by_flags
+    )
+  )
+);
+```
+
+#### Step 3: Add the experiment to enums.xml in the Chromium repository
 
 In Chromium, edit [tools/metrics/histograms/metadata/dev/enums.xml](https://crsrc.org/c/tools/metrics/histograms/metadata/dev/enums.xml;l=898).
 Find the enum titled `DevToolsExperiments`, and add a new entry. Make sure that the value matches the one from

package/front_end/core/common/README.md

@@ -31,3 +31,129 @@ Common.Settings.registerSettingExtension({
 
 A controller for the each setting is added to the 'preferences' tab if they are visible, that is, they have a `title` and a `category`.
 They can also be set with the command menu if they have `options` and a `category` (options’ names are added as commands).
+
+---
+
+# The DevTools Revealer System
+
+The `Revealer.ts` module provides a centralized system that allows different parts of the DevTools UI to "reveal" or display various types of objects without being tightly coupled to one another. It's a powerful decoupling mechanism that makes the codebase more modular, extensible, and performant.
+
+For example, if you click on a CSS file link in the **Console**, this system is responsible for telling the **Sources** panel to open and display that file, without the Console needing a direct reference to the Sources panel.
+
+## Core Concepts
+
+1.  **`Revealer<T>` Interface**: This is the fundamental contract. A "Revealer" is any object (typically a UI panel or view) that knows how to display a specific type of data (`T`). It must implement a single method: `reveal(revealable: T): Promise<void>`.
+
+2.  **"Revealable" Object**: This is any object you want to show to the user. It can be a source code file (`SDK.SourceCode.UISourceCode`), a network request (`SDK.NetworkRequest.NetworkRequest`), a DOM node (`SDK.DOMModel.DOMNode`), or any other custom data type.
+
+3.  **`RevealerRegistry`**: This is a singleton class that acts as a central directory. It holds a list of all available `Revealer`s and maps them to the data types they can handle.
+
+4.  **`RevealerRegistration<T>`**: This is a configuration object used to register a `Revealer` with the `RevealerRegistry`. It contains three key pieces of information:
+    *   `contextTypes`: A function that returns an array of classes (constructors) that the `Revealer` can handle.
+    *   `loadRevealer`: An asynchronous function that returns a promise, which resolves to an instance of the `Revealer`. This allows for the lazy-loading of UI panels, improving initial application performance.
+    *   `destination` (optional): A user-friendly, localized string that describes where the object will be revealed (e.g., "Network panel", "Elements panel"). This is used for UI text, such as in context menus ("Reveal in...").
+
+---
+
+## How to Create a New Revealer
+
+Here are the steps to implement a new revealer that can take the user to a specific place in the DevTools UI.
+
+### Step 1: Define the Object to be Revealed
+
+First, ensure you have a class or data type that you want to make "revealable."
+
+```ts
+// front_end/models/my_app/MyApp.ts
+export class MyDataObject {
+  id: string;
+  constructor(id: string) {
+    this.id = id;
+  }
+}
+```
+
+### Step 2: Implement the `Revealer` Interface in Your UI Panel
+
+The UI component that will display the object (e.g., your panel or widget) must implement the `Common.Revealer.Revealer<T>` interface for your specific data type.
+
+```ts
+// front_end/panels/my_panel/MyPanel.ts
+import * as Common from '../../core/common/common.js';
+import * as UI from '../../ui/legacy/legacy.js';
+import * as MyApp from '../../models/my_app/my_app.js';
+
+// 1. Implement the interface for your specific data type.
+export class MyPanel extends UI.Panel.Panel implements Common.Revealer.Revealer<MyApp.MyDataObject> {
+  // ... other panel implementation ...
+
+  // 2. This is the required method from the interface.
+  async reveal(dataObject: MyApp.MyDataObject): Promise<void> {
+    // This is where you put your panel's custom logic to show the object.
+
+    // First, ensure this panel is visible to the user.
+    await UI.ViewManager.ViewManager.instance().showView('my-panel-view-id');
+
+    // Now, highlight the specific item within your panel.
+    console.log(`Revealing data object with ID: ${dataObject.id}`);
+    // e.g., this.selectItemInUI(dataObject.id);
+  }
+}
+```
+
+### Step 3: Register Your Panel as a `Revealer`
+
+This is the most important step. You must tell the central `RevealerRegistry` that `MyPanel` knows how to handle `MyDataObject`. This registration is typically done in a module's `-meta.ts` or `-legacy.ts` configuration file, which is executed at startup.
+
+```ts
+// front_end/panels/my_panel/my_panel-meta.ts
+import * as Common from '../../core/common/common.js';
+import * as i18n from '../../core/i18n/i18n.js';
+
+const UIStrings = {
+  /**
+  * @description The name of the panel that reveals our custom data objects.
+  */
+  myPanel: 'My Awesome Panel',
+};
+const str_ = i18n.i18n.registerUIStrings('panels/my_panel/my_panel-meta.ts', UIStrings);
+const i18nLazyString = i18n.i18n.getLazilyComputedLocalizedString.bind(undefined, str_);
+
+Common.Revealer.registerRevealer({
+  // 1. Specify the data type(s) this revealer can handle.
+  contextTypes() {
+    // Use a dynamic import to avoid circular dependencies at module load time.
+    const {MyApp} = await import('../../models/my_app/my_app.js');
+    return [
+      MyApp.MyDataObject,
+    ];
+  },
+
+  // 2. Provide a function to load and return an instance of your panel.
+  //    This is what makes lazy loading possible.
+  async loadRevealer() {
+    const {MyPanel} = await import('./MyPanel.js');
+    // If your panel is a singleton, return its instance, otherwise create a new one.
+    return MyPanel.instance();
+  },
+
+  // 3. (Optional) Provide a user-facing destination name for context menus.
+  destination: i18nLazyString(UIStrings.myPanel),
+});
+```
+
+### Step 4: Trigger the Reveal from Anywhere
+
+Now that your revealer is registered, any other part of the DevTools codebase can ask to reveal an instance of `MyDataObject` without needing to know anything about `MyPanel`.
+
+```ts
+// In some other file, e.g., a context menu action.
+import * as Common from '../../core/common/common.js';
+import * as MyApp from '../../models/my_app/my_app.js';
+
+// Create an instance of the object you want to reveal.
+const myObject = new MyApp.MyDataObject('abc-123');
+
+// Call the global reveal function.
+await Common.Revealer.reveal(myObject);
+```

package/front_end/core/sdk/CSSModel.ts

@@ -575,6 +575,28 @@ export class CSSModel extends SDKModel<EventTypes> {
     }
   }
 
+  async setNavigationText(
+      styleSheetId: Protocol.DOM.StyleSheetId, range: TextUtils.TextRange.TextRange,
+      newNavigationText: string): Promise<boolean> {
+    Host.userMetrics.actionTaken(Host.UserMetrics.Action.StyleRuleEdited);
+
+    try {
+      await this.ensureOriginalStyleSheetText(styleSheetId);
+      const {navigation} = await this.agent.invoke_setNavigationText({styleSheetId, range, text: newNavigationText});
+
+      if (!navigation) {
+        return false;
+      }
+      this.#domModel.markUndoableState();
+      const edit = new Edit(styleSheetId, range, newNavigationText, navigation);
+      this.fireStyleSheetChanged(styleSheetId, edit);
+      return true;
+    } catch (e) {
+      console.error(e);
+      return false;
+    }
+  }
+
   async setScopeText(
       styleSheetId: Protocol.DOM.StyleSheetId, range: TextUtils.TextRange.TextRange,
       newScopeText: string): Promise<boolean> {

package/front_end/core/sdk/CSSNavigation.ts

@@ -0,0 +1,33 @@
+// Copyright 2026 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 CSSNavigation extends CSSQuery {
+  static parseNavigationPayload(cssModel: CSSModel, payload: Protocol.CSS.CSSNavigation[]): CSSNavigation[] {
+    return payload.map(navigation => new CSSNavigation(cssModel, navigation));
+  }
+
+  #active = true;
+
+  constructor(cssModel: CSSModel, payload: Protocol.CSS.CSSNavigation) {
+    super(cssModel);
+    this.reinitialize(payload);
+  }
+
+  reinitialize(payload: Protocol.CSS.CSSNavigation): void {
+    this.text = payload.text;
+    this.range = payload.range ? TextUtils.TextRange.TextRange.fromObject(payload.range) : null;
+    this.styleSheetId = payload.styleSheetId;
+    this.#active = payload.active ?? true;
+  }
+
+  active(): boolean {
+    return this.#active;
+  }
+}

package/front_end/core/sdk/CSSRule.ts

@@ -10,6 +10,7 @@ import {CSSContainerQuery} from './CSSContainerQuery.js';
 import {CSSLayer} from './CSSLayer.js';
 import {CSSMedia} from './CSSMedia.js';
 import type {CSSModel, Edit} from './CSSModel.js';
+import {CSSNavigation} from './CSSNavigation.js';
 import {CSSScope} from './CSSScope.js';
 import {CSSStartingStyle} from './CSSStartingStyle.js';
 import {CSSStyleDeclaration, Type} from './CSSStyleDeclaration.js';
@@ -113,6 +114,7 @@ export class CSSStyleRule extends CSSRule {
   layers: CSSLayer[];
   ruleTypes: Protocol.CSS.CSSRuleType[];
   startingStyles: CSSStartingStyle[];
+  navigations: CSSNavigation[];
   wasUsed: boolean;
   constructor(cssModel: CSSModel, payload: Protocol.CSS.CSSRule, wasUsed?: boolean) {
     super(cssModel, {
@@ -132,6 +134,7 @@ export class CSSStyleRule extends CSSRule {
     this.layers = payload.layers ? CSSLayer.parseLayerPayload(cssModel, payload.layers) : [];
     this.startingStyles =
         payload.startingStyles ? CSSStartingStyle.parseStartingStylePayload(cssModel, payload.startingStyles) : [];
+    this.navigations = payload.navigations ? CSSNavigation.parseNavigationPayload(cssModel, payload.navigations) : [];
     this.ruleTypes = payload.ruleTypes || [];
     this.wasUsed = wasUsed || false;
   }
@@ -224,6 +227,7 @@ export class CSSStyleRule extends CSSRule {
     this.containerQueries.forEach(cq => cq.rebase(edit));
     this.scopes.forEach(scope => scope.rebase(edit));
     this.supports.forEach(supports => supports.rebase(edit));
+    this.navigations.forEach(navigation => navigation.rebase(edit));
 
     super.rebase(edit);
   }
@@ -396,7 +400,7 @@ export interface CSSNestedStyleLeaf {
 
 export type CSSNestedStyleCondition = {
   children: CSSNestedStyle[],
-}&({media: CSSMedia}|{container: CSSContainerQuery}|{supports: CSSSupports});
+}&({media: CSSMedia}|{container: CSSContainerQuery}|{supports: CSSSupports}|{navigation: CSSNavigation});
 
 export type CSSNestedStyle = CSSNestedStyleLeaf|CSSNestedStyleCondition;
 
@@ -463,7 +467,13 @@ export class CSSFunctionRule extends CSSRule {
           supports: new CSSSupports(this.cssModelInternal, node.condition.supports),
         };
       }
-      console.error('A function rule condition must have a media, container, or supports');
+      if (node.condition.navigation) {
+        return {
+          children,
+          navigation: new CSSNavigation(this.cssModelInternal, node.condition.navigation),
+        };
+      }
+      console.error('A function rule condition must have a media, container, supports, or navigation');
       return;
     }
     console.error('A function rule node must have a style or condition');

package/front_end/core/sdk/sdk-meta.ts

@@ -43,13 +43,17 @@ const UIStrings = {
    */
   captureAsyncStackTraces: 'Capture async stack traces',
   /**
-   * @description Text of a setting that  turn on the measuring rulers when hover over a target
+   * @description Text of a setting that turn on the measuring rulers when hover over a target
+   */
+  rulersOnHover: 'Rulers on hover',
+  /**
+   * @description Text of an option that turn on the measuring rulers when hover over a target through the Command Menu
    */
   showRulersOnHover: 'Show rulers on hover',
   /**
    * @description Text of a setting that do turn off the measuring rulers when hover over a target
    */
-  doNotShowRulersOnHover: 'Do not show rulers on hover',
+  doNotShowRulersOnHover: 'Don\'t show rulers on hover',
   /**
    * @description Title of a setting that turns on grid area name labels
    */
@@ -99,19 +103,19 @@ const UIStrings = {
    */
   showLineNames: 'Show line names',
   /**
-   * @description Title of a setting under the Rendering category that can be invoked through the Command Menu
+   * @description Title of an option under the Rendering category that can be invoked through the Command Menu
    */
   showPaintFlashingRectangles: 'Show paint flashing rectangles',
   /**
-   * @description Title of a setting under the Rendering category that can be invoked through the Command Menu
+   * @description Title of an option under the Rendering category that can be invoked through the Command Menu
    */
   hidePaintFlashingRectangles: 'Hide paint flashing rectangles',
   /**
-   * @description Title of a setting under the Rendering category that can be invoked through the Command Menu
+   * @description Title of an option under the Rendering category that can be invoked through the Command Menu
    */
   showLayoutShiftRegions: 'Show layout shift regions',
   /**
-   * @description Title of a setting under the Rendering category that can be invoked through the Command Menu
+   * @description Title of an option under the Rendering category that can be invoked through the Command Menu
    */
   hideLayoutShiftRegions: 'Hide layout shift regions',
   /**
@@ -119,31 +123,31 @@ const UIStrings = {
    */
   highlightAdFrames: 'Highlight ad frames',
   /**
-   * @description Title of a setting under the Rendering category that can be invoked through the Command Menu
+   * @description Title of an option under the Rendering category that can be invoked through the Command Menu
    */
   doNotHighlightAdFrames: 'Do not highlight ad frames',
   /**
-   * @description Title of a setting under the Rendering category that can be invoked through the Command Menu
+   * @description Title of an option under the Rendering category that can be invoked through the Command Menu
    */
   showLayerBorders: 'Show layer borders',
   /**
-   * @description Title of a setting under the Rendering category that can be invoked through the Command Menu
+   * @description Title of an option under the Rendering category that can be invoked through the Command Menu
    */
   hideLayerBorders: 'Hide layer borders',
   /**
-   * @description Title of a setting under the Rendering category that can be invoked through the Command Menu
+   * @description Title of an option under the Rendering category that can be invoked through the Command Menu
    */
   showFramesPerSecondFpsMeter: 'Show frames per second (FPS) meter',
   /**
-   * @description Title of a setting under the Rendering category that can be invoked through the Command Menu
+   * @description Title of an option under the Rendering category that can be invoked through the Command Menu
    */
   hideFramesPerSecondFpsMeter: 'Hide frames per second (FPS) meter',
   /**
-   * @description Title of a setting under the Rendering category that can be invoked through the Command Menu
+   * @description Title of an option under the Rendering category that can be invoked through the Command Menu
    */
   showScrollPerformanceBottlenecks: 'Show scroll performance bottlenecks',
   /**
-   * @description Title of a setting under the Rendering category that can be invoked through the Command Menu
+   * @description Title of an option under the Rendering category that can be invoked through the Command Menu
    */
   hideScrollPerformanceBottlenecks: 'Hide scroll performance bottlenecks',
   /**
@@ -376,11 +380,11 @@ const UIStrings = {
    */
   javaScriptSourceMaps: 'JavaScript source maps',
   /**
-   * @description Title of a setting under the Sources category that can be invoked through the Command Menu
+   * @description Title of an option under the Sources category that can be invoked through the Command Menu
    */
   enableJavaScriptSourceMaps: 'Enable JavaScript source maps',
   /**
-   * @description Title of a setting under the Sources category that can be invoked through the Command Menu
+   * @description Title of an option under the Sources category that can be invoked through the Command Menu
    */
   disableJavaScriptSourceMaps: 'Disable JavaScript source maps',
   /**
@@ -388,11 +392,11 @@ const UIStrings = {
    */
   cssSourceMaps: 'CSS source maps',
   /**
-   * @description Title of a setting under the Sources category that can be invoked through the Command Menu
+   * @description Title of an option under the Sources category that can be invoked through the Command Menu
    */
   enableCssSourceMaps: 'Enable CSS source maps',
   /**
-   * @description Title of a setting under the Sources category that can be invoked through the Command Menu
+   * @description Title of an option under the Sources category that can be invoked through the Command Menu
    */
   disableCssSourceMaps: 'Disable CSS source maps',
   /**
@@ -501,7 +505,7 @@ Common.Settings.registerSettingExtension({
 Common.Settings.registerSettingExtension({
   category: Common.Settings.SettingCategory.ELEMENTS,
   storageType: Common.Settings.SettingStorageType.SYNCED,
-  title: i18nLazyString(UIStrings.showRulersOnHover),
+  title: i18nLazyString(UIStrings.rulersOnHover),
   settingName: 'show-metrics-rulers',
   settingType: Common.Settings.SettingType.BOOLEAN,
   options: [

package/front_end/core/sdk/sdk.ts

@@ -29,6 +29,7 @@ import * as CSSMatchedStyles from './CSSMatchedStyles.js';
 import * as CSSMedia from './CSSMedia.js';
 import * as CSSMetadata from './CSSMetadata.js';
 import * as CSSModel from './CSSModel.js';
+import * as CSSNavigation from './CSSNavigation.js';
 import * as CSSProperty from './CSSProperty.js';
 import * as CSSPropertyParser from './CSSPropertyParser.js';
 import * as CSSPropertyParserMatchers from './CSSPropertyParserMatchers.js';
@@ -111,6 +112,7 @@ export {
   CSSMedia,
   CSSMetadata,
   CSSModel,
+  CSSNavigation,
   CSSProperty,
   CSSPropertyParser,
   CSSPropertyParserMatchers,