npm - chrome-devtools-frontend - Versions diffs - 1.0.1522145 → 1.0.1524741 - Mend

chrome-devtools-frontend 1.0.1522145 → 1.0.1524741

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (348) hide show

package/AUTHORS CHANGED Viewed

@@ -33,6 +33,7 @@ Danny Eldridge <me@heardanieljames.com>
 Derek Li <the.derekli@gmail.com>
 Douglas Chiang <douglasdothnc@gmail.com>
 Dragonish <no.web.developer@outlook.com>
+Eden Wang <nedenwang@gmail.com>
 Edward Trist <edwardtrist@gmail.com>
 Ergün Erdoğmuş <erdogmusergun@gmail.com>
 Eric Rannaud <eric.rannaud@gmail.com>

package/docs/README.md CHANGED Viewed

@@ -60,6 +60,7 @@ below.**
 ### Policies
+*   [Chromium DevTools Console Policy](./policy/console-policy.md)
 *   [Chromium DevTools Slow-Close Policy](./policy/slow-close.md)
 *   [DevTools Page Zoom Accessibility Policy](./policy/gar-page-zoom-policy.md)

package/docs/policy/README.md CHANGED Viewed

@@ -3,5 +3,6 @@
 This folder contains the policies relevant to the development of the Chromium
 DevTools.
+1. [Chromium DevTools Console Policy](./console-policy.md)
 1. [Chromium DevTools Slow-Close Policy](./slow-close.md)
 2. [DevTools Page Zoom Accessibility Policy](./gar-page-zoom-policy.md)

package/docs/policy/console-policy.md ADDED Viewed

@@ -0,0 +1,144 @@
+# Chromium DevTools Console Policy
+[goo.gle/devtools-console-policy](http://goo.gle/devtools-console-policy)
+([go/chrome-devtools:console-policy](http://go/chrome-devtools:console-policy))
+**TL;DR:** This policy outlines a strategy to keep the signal to noise ratio in
+the Console panel of Chromium DevTools high, by setting clear expectations for
+Chromium teams what kind of information is presented to web developers via the
+Console and how it is presented. Console spam, specifically from Chromium
+itself, is a known pain point for developers (e.g.
+[crbug/338403584](http://crbug.com/338403584)).
+## Background
+The [Console panel](https://developer.chrome.com/docs/devtools/console) in the
+Chromium Developer Tools is usually the first place where web developers check
+in case something is not working as expected, and ideally they would come across
+an error or warning message here that helps them to quickly resolve the issue at
+hand. The panel shows all the messages that are logged by the web application
+but also the browser (potentially on behalf of the web application, for example
+logging uncaught exceptions).
+In order for it to remain useful to web developers, the signal to noise ratio
+must be as high as possible, and it’s crucially important to keep in mind that
+the information shown is (a) relevant to what the developer is looking for right
+now and (b) actionable wrt. to the issue at hand. Putting it the other way
+around, while the developer is focused on investigating a concrete problem it
+doesn’t help to show a lot of messages around potential issues, suggested
+improvements, or things that went wrong without any useful breadcrumbs (prime
+examples here are error messages from somewhere deep in Blink which contain no
+stack traces and basically just repeat the information that is already present
+on a JavaScript exception throw at the same time).
+## Common problems
+### Useless anchor
+A common problem we’ve observed is console messages from Chromium without a
+meaningful and actionable stack trace. Consider the following example, where the
+location attached to the console message is the first line of the main document.
+The inexperienced web developer will probably be puzzled how come
+`<!doctype html>` activates fingerprinting protection on the current page.
+![](./images/console-policy1.png "Useless message anchors")
+### For your information
+From a Chromium team working on a specific feature, it might be totally
+reasonable to _”let the developer know what’s going on”_, because something
+could break. But from a user’s perspective, messages that basically only convey
+non-actionable information and aren’t relevant in the context of the problem
+that the developer is investigating are useless at best. Consider the following
+example:
+![](./images/console-policy2.png "Confusing FYI messages")
+The first warning message says that Fingerprinting protection is active, but
+doesn’t tell the developer whether that’s a problem or not, and what they can do
+about it. It’s highly confusing. The second warning message states that two
+third-party cookies were blocked, but also leaves the developer wondering if
+that’s something to be concerned about or caused any actual problem.
+Similar messages that fall into this bucket:
+* `Third-party cookie will be blocked. Learn more in the Issues tab`
+* `[Violation] 'setTimeout' handler took <N>ms`
+* `[Violation] Added non-passive event listener to a scroll-blocking <some> event. Consider marking event handler as 'passive' to make the page more responsive. See <URL>`
+* `Specifying 'overflow: visible' on img, video and canvas tags may cause them to produce visual content outside of the element bounds. See https://github.com/WICG/view-transitions/blob/main/debugging_overflow_on_images.md for details.`
+Logging a message to the Console panel just to tell the developer to open
+another panel or read some article is specifically annoying, and over time will
+result in training web developers on ignoring messages produced by Chromium
+itself.
+### Repetition
+Repeating the same message over and over again (independent of whether it’s
+actionable and meaningful) is another source of problems:
+![](./images/console-policy3.png "Repeated console messages")
+DevTools has a feature to group similar messages, which most users have enabled,
+so the pain they feel from a lot of repeated information is manageable. But that
+also gives rise to a new problem: Problems might be hidden through the grouping
+feature outside of the viewport, because the grouping somewhat breaks the
+chronological order.
+## Best practice
+Specifically for the purpose of being able to present developers with actionable
+information, coupled with traces of data that are relevant to the issue, we’ve
+introduced the [Issues panel], and as part of
+[crbug/40173406](http://crbug.com/40173406) and related bugs already migrated a
+few spammy console messages to issues.
+In general, reserve the use of `context->AddConsoleMessage(...)` and similar
+APIs for rare cases when the console message adds significant value, favor a
+well-worded and helpful issue over a console message, and specifically don’t
+spit out a console message when you are already raising an exception (exceptions
+can be coupled with issues internally to provide more actionable information).
+## Building empathy
+Many Chromies might not be able to immediately relate to the struggles of web
+developers, and might not have first hand experience with sifting through
+endless logs of useless information produced by frameworks, libraries, and
+eventually the browser. But imagine the following scenario: You are using `gdb`
+or `lldb` and instead of helping you diagnose the crash somewhere deep in your
+C++ code for Autofill in the browser process, it’s spamming you with pages of
+potential performance improvements in the renderer code for `<canvas>` elements.
+At best that would be very confusing, but more likely you’d be very frustrated
+with the tool after a while. This is exactly what happens if we spam web
+developers with potential performance issues.
+We have a [logging policy for Chromium] to prevent ourselves from being
+overwhelmed by log messages from other Chromium teams, for the same reason.
+## GTM strategy
+The most common cause for spammy console messages from Chromium is an
+insufficient Go-To-Market (GTM) strategy for features or (potentially breaking)
+changes when it comes to developer adoption. Oftentimes it’s unclear what
+exactly the expectations are and what are the critical user journeys that web
+developers go through. Spending a bit more time on this aspect and involving
+DevRel early on can help to shine light on the matter and avoid sprinkling log
+messages all over the place to _”raise awareness”_. Specifically consider:
+- The precise target audience for your information, because not all web
+  developers are equal at all times.
+- Under which exact circumstances that piece of information is required.
+- Is it a nice to have (e.g. _”X could be faster if you did Y”_ or _”using A
+  poses a potential security risk for your users”_) or a critically important
+  piece of information (e.g. _”X will stop working in the next release unless
+  you do Y”_).
+Feel free to reach out to [devtools-dev@chromium.org] with questions, and ping
+[dsv@chromium.org](mailto:dsv@chromium.org) (Chrome DevTools TL) or
+[hablich@chromium.org](mailto:hablich@chromium.org) (Chrome DevTools PM)
+directly (specifically in case of code reviews which add new problematic console
+messages).
+  [Issues panel]: https://developer.chrome.com/docs/devtools/issues
+  [logging policy for Chromium]: https://chromium.googlesource.com/chromium/src/+/main/styleguide/c++/c++.md#logging
+  [devtools-dev@chromium.org]: https://groups.google.com/a/chromium.org/g/devtools-dev

package/docs/policy/images/console-policy1.png ADDED Viewed

Binary file

package/docs/policy/images/console-policy2.png ADDED Viewed

Binary file

package/docs/policy/images/console-policy3.png ADDED Viewed

Binary file

package/docs/ui_engineering.md CHANGED Viewed

@@ -1223,3 +1223,101 @@ export const DEFAULT_VIEW = (input, _output, target) => {
     target, {host: input});
 };
 ```
+## Refactoring UI.Toolbar.Provider
+As part of the migration, sometimes classes need to be broken up into smaller pieces. Classes implementing
+`UI.Toolbar.Provider` logic are good examples of this, if they implement `View` logic in addition to their
+`UI.Toolbar.Provider` responsibilities. The View logic needs to be moved to a separate class.
+**Before:**
+```typescript
+export class NodeIndicator implements UI.Toolbar.Provider {
+  readonly #element: Element;
+  readonly #item: UI.Toolbar.ToolbarItem;
+  private constructor() {
+    // Creates `this.#element` and `this.#item` imperatively (e.g. using document.createElement/createChild).
+  }
+  static instance(opts: { forceNew: boolean|null, } = {forceNew: null}): NodeIndicator {
+    // Creates an instance of this class and returns it.
+  }
+  #update(input): void { /* Handles updates to `this.#element` and `this.#item`. */}
+  item(): UI.Toolbar.ToolbarItem|null {
+    return this.#item;
+  }
+}
+```
+**After:**
+```typescript
+export const DEFAULT_VIEW: View = (input, output, target) => {
+  // Implementation of the View using Lit.render() (omitted for brevity).
+};
+export class NodeIndicator extends UI.Widget.Widget {
+  readonly #view: View;
+  constructor(element?: HTMLElement, view = DEFAULT_VIEW) {
+    super(element, {useShadowDom: true});
+    this.#view = view;
+  }
+  override performUpdate(): void {
+    const input = {
+      // Whatever input the View needs.
+    };
+    this.#view(input, {}, this.contentElement);
+  }
+}
+let nodeIndicatorProviderInstance: NodeIndicatorProvider;
+export class NodeIndicatorProvider implements UI.Toolbar.Provider {
+  #toolbarItem: UI.Toolbar.ToolbarItem;
+  #widgetElement: UI.Widget.WidgetElement<NodeIndicator>;
+  private constructor() {
+    this.#widgetElement = document.createElement('devtools-widget') as UI.Widget.WidgetElement<NodeIndicator>;
+    this.#widgetElement.widgetConfig = UI.Widget.widgetConfig(NodeIndicator);
+    this.#toolbarItem = new UI.Toolbar.ToolbarItem(this.#widgetElement);
+    this.#toolbarItem.setVisible(false);
+  }
+  item(): UI.Toolbar.ToolbarItem|null {
+    return this.#toolbarItem;
+  }
+  static instance(opts: {forceNew: boolean|null} = {forceNew: null}): NodeIndicatorProvider {
+    const {forceNew} = opts;
+    if (!nodeIndicatorProviderInstance || forceNew) {
+      nodeIndicatorProviderInstance = new NodeIndicatorProvider();
+    }
+    return nodeIndicatorProviderInstance;
+  }
+}
+```
+## Highlighting text
+### (UI.UIUtils.highlightRangesWithStyleClass or Highlighting.HighlightManager)
+Use the `<devtools-highlight>` component to highlight text ranges within its
+container. The component takes two attributes: `ranges`, which is a
+space-separated list of `offset,length` pairs, and `current-range`, which is a
+single `offset,length` pair to highlight with a different color.
+The component will automatically sort and merge the ranges provided.
+```html
+<div style="position:relative">
+  <devtools-highlight ranges="10,2 1,3 2,3" current-range="5,3">
+    This is some text to highlight.
+  </devtools-highlight>
+</div>
+```
+In this example, the ranges `1,3` and `2,3` will be merged into `1,4`. The
+ranges `10,2` and the current range `5,3` will also be highlighted.

package/front_end/Tests.js CHANGED Viewed

@@ -1065,7 +1065,7 @@
         this.fail(text);
       }  // This will throw.
     }
-    // Neither PASS nor FAIL, so wait for more messages.
+    /** Neither PASS nor FAIL, so wait for more messages. **/
     function onConsoleMessage(event) {
       const text = event.data.messageText;
       if (text === 'PASS') {

package/front_end/core/common/Color.ts CHANGED Viewed

@@ -47,11 +47,13 @@ import {
   rgbToHwb,
 } from './ColorUtils.js';
-// <hue> is defined as a <number> or <angle>
-// and we hold this in degrees. However, after
-// the conversions, these degrees can result in
-// negative values. That's why we normalize the hue to be
-// between [0 - 360].
+/**
+ * <hue> is defined as a <number> or <angle>
+ * and we hold this in degrees. However, after
+ * the conversions, these degrees can result in
+ * negative values. That's why we normalize the hue to be
+ * between [0 - 360].
+ **/
 function normalizeHue(hue: number): number {
   // Even though it is highly unlikely, hue can be
   // very negative like -400. The initial modulo
@@ -60,9 +62,11 @@ function normalizeHue(hue: number): number {
   return ((hue % 360) + 360) % 360;
 }
-// Parses angle in the form of
-// `<angle>deg`, `<angle>turn`, `<angle>grad and `<angle>rad`
-// and returns the canonicalized `degree`.
+/**
+ * Parses angle in the form of
+ * `<angle>deg`, `<angle>turn`, `<angle>grad and `<angle>rad`
+ * and returns the canonicalized `degree`.
+ **/
 function parseAngle(angleText: string): number|null {
   const angle = angleText.replace(/(deg|g?rad|turn)$/, '');
   // @ts-expect-error: isNaN can accept strings
@@ -90,7 +94,7 @@ function parseAngle(angleText: string): number|null {
   return number;
 }
-// Returns the `Format` equivalent from the format text
+/** Returns the `Format` equivalent from the format text **/
 export function getFormat(formatText: string): Format|null {
   switch (formatText) {
     case Format.HEX:

package/front_end/core/common/ColorConverter.ts CHANGED Viewed

@@ -50,13 +50,15 @@ class Matrix3x3 {
   }
 }
-// A transfer function mapping encoded values to linear values,
-// represented by this 7-parameter piecewise function:
-//
-//   linear = sign(encoded) *  (c*|encoded| + f)       , 0 <= |encoded| < d
-//          = sign(encoded) * ((a*|encoded| + b)^g + e), d <= |encoded|
-//
-// (A simple gamma transfer function sets g to gamma and a to 1.)
+/**
+ * A transfer function mapping encoded values to linear values,
+ * represented by this 7-parameter piecewise function:
+ *
+ * linear = sign(encoded) *  (c*|encoded| + f)       , 0 <= |encoded| < d
+ * = sign(encoded) * ((a*|encoded| + b)^g + e), d <= |encoded|
+ *
+ * (A simple gamma transfer function sets g to gamma and a to 1.)
+ **/
 class TransferFunction {
   g: number;
   a: number;

package/front_end/core/common/Gzip.ts CHANGED Viewed

@@ -48,7 +48,7 @@ export async function compress(str: string): Promise<ArrayBuffer> {
   return buffer;
 }
-// Private coder/decoder
+/** Private coder/decoder **/
 function gzipCodec(buffer: Uint8Array<ArrayBufferLike>|ArrayBuffer, codecStream: CompressionStream|DecompressionStream):
     Promise<ArrayBuffer> {
   const {readable, writable} = new TransformStream();

package/front_end/core/common/MapWithDefault.ts CHANGED Viewed

@@ -2,9 +2,11 @@
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
-// Polyfill of https://github.com/tc39/proposal-upsert with a subclass.
-//
-// TODO: Once the proposal is merged, just replace `MapWithDefault` with `Map` and remove it.
+/**
+ * Polyfill of https://github.com/tc39/proposal-upsert with a subclass.
+ *
+ * TODO: Once the proposal is merged, just replace `MapWithDefault` with `Map` and remove it.
+ **/
 export class MapWithDefault<K, V> extends Map<K, V> {
   getOrInsert(key: K, defaultValue: V): V {
     if (!this.has(key)) {

package/front_end/core/common/ResourceType.ts CHANGED Viewed

@@ -145,10 +145,6 @@ const UIStrings = {
    * @description Name of a network initiator type
    */
   preflight: 'Preflight',
-  /**
-   * @description Name of a network initiator type
-   */
-  webbundle: 'WebBundle',
   /**
    * @description Name of a network initiator type for FedCM requests
    */
@@ -212,9 +208,6 @@ export class ResourceType {
     if (mimeType === 'application/wasm') {
       return resourceTypes.Wasm;
     }
-    if (mimeType === 'application/webbundle') {
-      return resourceTypes.WebBundle;
-    }
     return null;
   }
@@ -337,10 +330,6 @@ export class ResourceType {
     return this.#name.startsWith('sm-');
   }
-  isWebbundle(): boolean {
-    return this.#name === 'webbundle';
-  }
   toString(): string {
     return this.#name;
   }
@@ -427,7 +416,6 @@ export const resourceTypes = {
   SourceMapScript: new ResourceType('sm-script', i18nLazyString(UIStrings.script), resourceCategories.Script, true),
   SourceMapStyleSheet:
       new ResourceType('sm-stylesheet', i18nLazyString(UIStrings.stylesheet), resourceCategories.Stylesheet, true),
-  WebBundle: new ResourceType('webbundle', i18nLazyString(UIStrings.webbundle), resourceCategories.Other, false),
   FedCM: new ResourceType('fedcm', i18nLazyString(UIStrings.fedcm), resourceCategories.Other, false),
 } as const;

package/front_end/core/common/ReturnToPanel.ts CHANGED Viewed

@@ -2,10 +2,12 @@
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
-// Set instance of this class as flavor to mark what panel triggered the
-// 'elements.toggle-element-search' action if it was not the elements panel.
-// This will cause specified panel to be made visible instead of the elements
-// panel after the inspection is done.
+/**
+ * Set instance of this class as flavor to mark what panel triggered the
+ * 'elements.toggle-element-search' action if it was not the elements panel.
+ * This will cause specified panel to be made visible instead of the elements
+ * panel after the inspection is done.
+ **/
 export class ReturnToPanelFlavor {
   readonly viewId: string;

package/front_end/core/common/Trie.ts CHANGED Viewed

@@ -7,8 +7,10 @@
 // ElementTYpe<string> -> string
 type ElementType<T extends ArrayLike<unknown>> = T extends ArrayLike<infer E>? E : never;
-// Abstracts some generic operations that have different implementions depending
-// on whether we operate on strings or array of things.
+/**
+ * Abstracts some generic operations that have different implementations depending
+ * on whether we operate on strings or array of things.
+ **/
 interface TrieableTrait<T extends ArrayLike<ElementType<T>>> {
   empty(): T;
   append(base: T, appendage: ElementType<T>): T;

package/front_end/core/host/AidaClient.ts CHANGED Viewed

@@ -93,7 +93,7 @@ export interface FunctionDeclaration<T extends string|number|symbol = string> {
   parameters: FunctionObjectParam<T>;
 }
-// Raw media bytes.
+/** Raw media bytes. **/
 export interface MediaBlob {
   // The IANA standard MIME type of the source data.
   // Currently supported types are: image/png, image/jpeg.
@@ -113,7 +113,7 @@ export enum FunctionalityType {
   AGENTIC_CHAT = 5,
 }
-// See: cs/aida.proto (google3).
+/** See: cs/aida.proto (google3). **/
 export enum ClientFeature {
   // Unspecified client feature.
   CLIENT_FEATURE_UNSPECIFIED = 0,
@@ -150,7 +150,7 @@ export enum UserTier {
   PUBLIC = 3,
 }
-// Googlers: see the Aida `retrieval` proto; this type is based on that.
+/** Googlers: see the Aida `retrieval` proto; this type is based on that. **/
 export interface RequestFactMetadata {
   /**
    * A description of where the fact comes from.

package/front_end/core/host/GdpClient.ts CHANGED Viewed

@@ -84,11 +84,13 @@ class GdpError extends Error {
   }
 }
-// The `batchGet` awards endpoint returns badge names with an
-// obfuscated user ID (e.g., `profiles/12345/awards/badge-name`).
-// This function normalizes them to use `me` instead of the ID
-// (e.g., `profiles/me/awards/badge-path`) to match the format
-// used for client-side requests.
+/**
+ * The `batchGet` awards endpoint returns badge names with an
+ * obfuscated user ID (e.g., `profiles/12345/awards/badge-name`).
+ * This function normalizes them to use `me` instead of the ID
+ * (e.g., `profiles/me/awards/badge-path`) to match the format
+ * used for client-side requests.
+ **/
 function normalizeBadgeName(name: string): string {
   return name.replace(/profiles\/[^/]+\/awards\//, 'profiles/me/awards/');
 }

package/front_end/core/host/InspectorFrontendHostAPI.ts CHANGED Viewed

@@ -217,11 +217,13 @@ export interface FunctionCallEvent {
   context?: number;
 }
-// While `EventDescriptors` are used to dynamically dispatch host binding events,
-// the `EventTypes` "type map" is used for type-checking said events by TypeScript.
-// `EventTypes` is not used at runtime.
-// Please note that the "dispatch" side can't be type-checked as the dispatch is
-// done dynamically.
+/**
+ * While `EventDescriptors` are used to dynamically dispatch host binding events,
+ * the `EventTypes` "type map" is used for type-checking said events by TypeScript.
+ * `EventTypes` is not used at runtime.
+ * Please note that the "dispatch" side can't be type-checked as the dispatch is
+ * done dynamically.
+ **/
 export interface EventTypes {
   [Events.AppendedToURL]: Platform.DevToolsPath.RawPathString|Platform.DevToolsPath.UrlString;
   [Events.CanceledSaveURL]: Platform.DevToolsPath.UrlString;

package/front_end/core/host/Platform.ts CHANGED Viewed

@@ -35,9 +35,11 @@ export function isWin(): boolean {
   return _isWin;
 }
-// In Chrome Layout tests the imported 'Platform' object is not writable/
-// configurable, which prevents us from monkey-patching 'Platform''s methods.
-// We circumvent this by adding 'setPlatformForTests'.
+/**
+ * In Chrome Layout tests the imported 'Platform' object is not writable/
+ * configurable, which prevents us from monkey-patching 'Platform''s methods.
+ * We circumvent this by adding 'setPlatformForTests'.
+ **/
 export function setPlatformForTests(platform: string): void {
   _platform = platform;
   _isMac = undefined;

package/front_end/core/host/UserMetrics.ts CHANGED Viewed

@@ -321,9 +321,11 @@ export class UserMetrics {
  * 2. Do not update any 'MAX_VALUE' or any other value.
  */
-// Codes below are used to collect UMA histograms in the Chromium port.
-// Do not change the values below, additional actions are needed on the Chromium side
-// in order to add more codes.
+/**
+ * Codes below are used to collect UMA histograms in the Chromium port.
+ * Do not change the values below, additional actions are needed on the Chromium side
+ * in order to add more codes.
+ **/
 export enum Action {
   /* eslint-disable @typescript-eslint/naming-convention */
   WindowDocked = 1,
@@ -807,7 +809,7 @@ export enum DevtoolsExperiments {
   MAX_VALUE = 110,
 }
-// Update DevToolsIssuesPanelIssueExpanded from tools/metrics/histograms/enums.xml if new enum is added.
+/** Update DevToolsIssuesPanelIssueExpanded from tools/metrics/histograms/enums.xml if new enum is added. **/
 export enum IssueExpanded {
   /* eslint-disable @typescript-eslint/naming-convention */
   CrossOriginEmbedderPolicy = 0,

package/front_end/core/platform/ArrayUtilities.ts CHANGED Viewed

@@ -265,7 +265,7 @@ export function nearestIndexFromEnd<T>(arr: readonly T[], predicate: (arrayItem:
   return nearestIndex(arr, predicate, NearestSearchStart.END);
 }
-// Type guard for ensuring that `arr` does not contain null or undefined
+/** Type guard for ensuring that `arr` does not contain null or undefined **/
 export function arrayDoesNotContainNullOrUndefined<T>(arr: Array<T|null|undefined>): arr is T[] {
   return !arr.includes(null) && !arr.includes(undefined);
 }