chrome-devtools-frontend 1.0.1613625 → 1.0.1614363

package/AUTHORS

@@ -41,6 +41,7 @@ Emir D <emrd434@gmail.com>
 Ergün Erdoğmuş <erdogmusergun@gmail.com>
 Eric Rannaud <eric.rannaud@gmail.com>
 Faisal Salman <fyzlman@gmail.com>
+Fedor Indutny <indutny@signal.org>
 Feng Lu <lufengd3@gmail.com>
 Feng Yu <f3n67u@gmail.com>
 Gabriel Luong <gabriel.luong@gmail.com>

package/front_end/core/common/MapWithDefault.ts

@@ -8,7 +8,7 @@
  * TODO: Once the proposal is merged, just replace `MapWithDefault` with `Map` and remove it.
  **/
 export class MapWithDefault<K, V> extends Map<K, V> {
-  override getOrInsert(key: K, defaultValue: V): V {
+  getOrInsert(key: K, defaultValue: V): V {
     if (!this.has(key)) {
       this.set(key, defaultValue);
     }
@@ -16,7 +16,7 @@ export class MapWithDefault<K, V> extends Map<K, V> {
     return this.get(key) as V;
   }
 
-  override getOrInsertComputed(key: K, callbackFunction: (key: K) => V): V {
+  getOrInsertComputed(key: K, callbackFunction: (key: K) => V): V {
     if (!this.has(key)) {
       this.set(key, callbackFunction(key));
     }

package/front_end/core/common/Object.ts

@@ -119,34 +119,31 @@ export class ObjectWrapper<Events> implements EventTarget<Events> {
 export function eventMixin<Events, Base extends Platform.Constructor.Constructor<object>>(base: Base) {
   console.assert(base !== HTMLElement);
   return class EventHandling extends base implements EventTarget<Events> {
-    // Note that the weird name is due to TSC disallowing private/protected fields in
-    // anonmous exported classes. We use a `__` prefix to prevent clashes with `base`.
-    // eslint-disable-next-line @devtools/no-underscored-properties, @typescript-eslint/naming-convention
-    __events = new ObjectWrapper<Events>();
+    #events = new ObjectWrapper<Events>();
 
     addEventListener<T extends keyof Events>(
         eventType: T, listener: (arg0: EventTargetEvent<Events[T]>) => void,
         thisObject?: Object): EventDescriptor<Events, T> {
-      return this.__events.addEventListener(eventType, listener, thisObject);
+      return this.#events.addEventListener(eventType, listener, thisObject);
     }
 
     once<T extends keyof Events>(eventType: T): Promise<Events[T]> {
-      return this.__events.once(eventType);
+      return this.#events.once(eventType);
     }
 
     removeEventListener<T extends keyof Events>(
         eventType: T, listener: (arg0: EventTargetEvent<Events[T]>) => void, thisObject?: Object): void {
-      this.__events.removeEventListener(eventType, listener, thisObject);
+      this.#events.removeEventListener(eventType, listener, thisObject);
     }
 
     hasEventListeners(eventType: keyof Events): boolean {
-      return this.__events.hasEventListeners(eventType);
+      return this.#events.hasEventListeners(eventType);
     }
 
     dispatchEventToListeners<T extends keyof Events>(
         eventType: Platform.TypeScriptUtilities.NoUnion<T>,
         ...eventData: EventPayloadToRestParameters<Events, T>): void {
-      this.__events.dispatchEventToListeners(eventType, ...eventData);
+      this.#events.dispatchEventToListeners(eventType, ...eventData);
     }
   };
 }

package/front_end/core/common/VersionController.ts

@@ -17,7 +17,7 @@ export class VersionController {
   static readonly SYNCED_VERSION_SETTING_NAME = 'syncedInspectorVersion';
   static readonly LOCAL_VERSION_SETTING_NAME = 'localInspectorVersion';
 
-  static readonly CURRENT_VERSION = 43;
+  static readonly CURRENT_VERSION = 44;
 
   readonly #settings: Settings;
   readonly #globalVersionSetting: Setting<number>;
@@ -848,6 +848,22 @@ export class VersionController {
     }
   }
 
+  updateVersionFrom43To44(): void {
+    const apcaExperimentEnabled =
+        Root.Runtime.experiments.getValueFromStorage('apca' as Root.ExperimentNames.ExperimentName);
+    if (apcaExperimentEnabled !== undefined) {
+      if (this.#settings.syncedStorage.has('apca')) {
+        return;  // Already migrated
+      }
+      try {
+        const apcaSetting = this.#settings.moduleSetting('apca');
+        apcaSetting.set(apcaExperimentEnabled);
+      } catch {
+        // If the setting is not registered yet (e.g. in tests), skip.
+      }
+    }
+  }
+
   /*
    * Any new migration should be added before this comment.
    *

package/front_end/core/host/UserMetrics.ts

@@ -816,7 +816,6 @@ export enum DevtoolsExperiments {
   'protocol-monitor' = 13,
   'sampling-heap-profiler-timeline' = 17,
   'timeline-invalidation-tracking' = 26,
-  apca = 39,
   'font-editor' = 41,
   'instrumentation-breakpoints' = 61,
   'use-source-map-scopes' = 76,

package/front_end/core/root/ExperimentNames.ts

@@ -9,7 +9,6 @@ export enum ExperimentName {
   PROTOCOL_MONITOR = 'protocol-monitor',
   SAMPLING_HEAP_PROFILER_TIMELINE = 'sampling-heap-profiler-timeline',
   TIMELINE_INVALIDATION_TRACKING = 'timeline-invalidation-tracking',
-  APCA = 'apca',
   FONT_EDITOR = 'font-editor',
   INSTRUMENTATION_BREAKPOINTS = 'instrumentation-breakpoints',
   USE_SOURCE_MAP_SCOPES = 'use-source-map-scopes',

package/front_end/core/sdk/OverlayModel.ts

@@ -7,7 +7,6 @@ import type * as ProtocolProxyApi from '../../generated/protocol-proxy-api.js';
 import * as Protocol from '../../generated/protocol.js';
 import * as Common from '../common/common.js';
 import * as i18n from '../i18n/i18n.js';
-import * as Root from '../root/root.js';
 
 import type {CSSModel} from './CSSModel.js';
 import {DebuggerModel, Events as DebuggerModelEvents} from './DebuggerModel.js';
@@ -534,9 +533,8 @@ export class OverlayModel extends SDKModel<EventTypes> implements ProtocolProxyA
       gridHighlightConfig: {},
       flexContainerHighlightConfig: {},
       flexItemHighlightConfig: {},
-      contrastAlgorithm: Root.Runtime.experiments.isEnabled(Root.ExperimentNames.ExperimentName.APCA) ?
-          Protocol.Overlay.ContrastAlgorithm.Apca :
-          Protocol.Overlay.ContrastAlgorithm.Aa,
+      contrastAlgorithm: settings.moduleSetting('apca').get() ? Protocol.Overlay.ContrastAlgorithm.Apca :
+                                                                Protocol.Overlay.ContrastAlgorithm.Aa,
     };
 
     if (mode === 'all' || mode === 'content') {

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

@@ -403,6 +403,10 @@ const UIStrings = {
    * @description Title of a setting under the Console category in Settings
    */
   logXmlhttprequests: 'Log XMLHttpRequests',
+  /**
+   * @description Title of a setting under the Elements category in Settings.
+   */
+  apca: 'Advanced Perceptual Contrast Algorithm (APCA) replacing previous contrast ratio and AA/AAA guidelines',
 } as const;
 const str_ = i18n.i18n.registerUIStrings('core/sdk/sdk-meta.ts', UIStrings);
 const i18nLazyString = i18n.i18n.getLazilyComputedLocalizedString.bind(undefined, str_);
@@ -521,6 +525,15 @@ Common.Settings.registerSettingExtension({
   defaultValue: false,
 });
 
+Common.Settings.registerSettingExtension({
+  category: Common.Settings.SettingCategory.ELEMENTS,
+  storageType: Common.Settings.SettingStorageType.SYNCED,
+  title: i18nLazyString(UIStrings.apca),
+  settingName: 'apca',
+  settingType: Common.Settings.SettingType.BOOLEAN,
+  defaultValue: false,
+});
+
 Common.Settings.registerSettingExtension({
   category: Common.Settings.SettingCategory.GRID,
   storageType: Common.Settings.SettingStorageType.SYNCED,

package/front_end/entrypoints/device_mode_emulation_frame/device_mode_emulation_frame.ts

@@ -3,6 +3,10 @@
 // found in the LICENSE file.
 
 import '../../core/dom_extension/dom_extension.js';
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// @ts-ignore: tsc 6.0 does not support side-effect imports without a type definition.
+// We cannot use `@ts-expect-error` here because the import is correctly resolved
+// when bundling the application (which doesn't error) and only errors in unbundled builds.
 import '../../Images/Images.js';
 
 if (window.opener) {

package/front_end/entrypoints/greendev_floaty/FloatyEntrypoint.ts

@@ -368,7 +368,6 @@ async function init(): Promise<void> {
     safeRegisterExperiment(Root.ExperimentNames.ExperimentName.PROTOCOL_MONITOR, 'Protocol Monitor');
     safeRegisterExperiment(
         Root.ExperimentNames.ExperimentName.SAMPLING_HEAP_PROFILER_TIMELINE, 'Sampling heap profiler timeline');
-    safeRegisterExperiment(Root.ExperimentNames.ExperimentName.APCA, 'APCA');
 
     const hostUnsyncedStorage: Common.Settings.SettingsBackingStore = {
       register: (name: string) =>

package/front_end/entrypoints/greendev_floaty/greendev_floaty.ts

@@ -254,7 +254,6 @@ async function init(): Promise<void> {
     Root.Runtime.experiments.register(Root.ExperimentNames.ExperimentName.PROTOCOL_MONITOR, 'Protocol Monitor');
     Root.Runtime.experiments.register(
         Root.ExperimentNames.ExperimentName.SAMPLING_HEAP_PROFILER_TIMELINE, 'Sampling heap profiler timeline');
-    Root.Runtime.experiments.register(Root.ExperimentNames.ExperimentName.APCA, 'APCA');
 
     const WINDOW_LOCAL_STORAGE: Common.Settings.SettingsBackingStore = {
       register(_setting: string): void{},

package/front_end/entrypoints/main/MainImpl.ts

@@ -372,12 +372,6 @@ export class MainImpl {
     Root.Runtime.experiments.register(
         Root.ExperimentNames.ExperimentName.USE_SOURCE_MAP_SCOPES, 'Use scope information from source maps');
 
-    // Advanced Perceptual Contrast Algorithm.
-    Root.Runtime.experiments.register(
-        Root.ExperimentNames.ExperimentName.APCA,
-        'Advanced Perceptual Contrast Algorithm (APCA) replacing previous contrast ratio and AA/AAA guidelines',
-        'https://developer.chrome.com/blog/new-in-devtools-89/#apca');
-
     // Font Editor
     Root.Runtime.experiments.register(
         Root.ExperimentNames.ExperimentName.FONT_EDITOR, 'New font editor in the Styles tab',

package/front_end/entrypoints/shell/shell.ts

@@ -2,6 +2,10 @@
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// @ts-ignore: tsc 6.0 does not support side-effect imports without a type definition.
+// We cannot use `@ts-expect-error` here because the import is correctly resolved
+// when bundling the application (which doesn't error) and only errors in unbundled builds.
 import '../../Images/Images.js';
 import '../../core/dom_extension/dom_extension.js';
 import '../../panels/sources/sources-meta.js';

package/front_end/entrypoints/trace_app/trace_app.ts

@@ -6,6 +6,10 @@ import '../main/main-meta.js';
 import '../inspector_main/inspector_main-meta.js';
 import '../../core/sdk/sdk-meta.js';
 import '../../models/workspace/workspace-meta.js';
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// @ts-ignore: tsc 6.0 does not support side-effect imports without a type definition.
+// We cannot use `@ts-expect-error` here because the import is correctly resolved
+// when bundling the application (which doesn't error) and only errors in unbundled builds.
 import '../../Images/Images.js';
 import '../../models/logs/logs-meta.js';
 import '../../models/persistence/persistence-meta.js';

package/front_end/generated/InspectorBackendCommands.ts

@@ -1408,7 +1408,7 @@ inspectorBackend.registerCommand("Target.setDiscoverTargets", [{"name": "discove
 inspectorBackend.registerCommand("Target.setRemoteLocations", [{"name": "locations", "type": "array", "optional": false, "description": "List of remote locations.", "typeRef": "Target.RemoteLocation"}], [], "Enables target discovery for the specified locations, when `setDiscoverTargets` was set to `true`.");
 inspectorBackend.registerCommand("Target.getDevToolsTarget", [{"name": "targetId", "type": "string", "optional": false, "description": "Page or tab target ID.", "typeRef": "Target.TargetID"}], ["targetId"], "Gets the targetId of the DevTools page target opened for the given target (if any).");
 inspectorBackend.registerCommand("Target.openDevTools", [{"name": "targetId", "type": "string", "optional": false, "description": "This can be the page or tab target ID.", "typeRef": "Target.TargetID"}, {"name": "panelId", "type": "string", "optional": true, "description": "The id of the panel we want DevTools to open initially. Currently supported panels are elements, console, network, sources, resources and performance.", "typeRef": null}], ["targetId"], "Opens a DevTools window for the target.");
-inspectorBackend.registerType("Target.TargetInfo", [{"name": "targetId", "type": "string", "optional": false, "description": "", "typeRef": "Target.TargetID"}, {"name": "type", "type": "string", "optional": false, "description": "List of types: https://source.chromium.org/chromium/chromium/src/+/main:content/browser/devtools/devtools_agent_host_impl.cc?ss=chromium&q=f:devtools%20-f:out%20%22::kTypeTab%5B%5D%22", "typeRef": null}, {"name": "title", "type": "string", "optional": false, "description": "", "typeRef": null}, {"name": "url", "type": "string", "optional": false, "description": "", "typeRef": null}, {"name": "attached", "type": "boolean", "optional": false, "description": "Whether the target has an attached client.", "typeRef": null}, {"name": "openerId", "type": "string", "optional": true, "description": "Opener target Id", "typeRef": "Target.TargetID"}, {"name": "canAccessOpener", "type": "boolean", "optional": false, "description": "Whether the target has access to the originating window.", "typeRef": null}, {"name": "openerFrameId", "type": "string", "optional": true, "description": "Frame id of originating window (is only set if target has an opener).", "typeRef": "Page.FrameId"}, {"name": "parentFrameId", "type": "string", "optional": true, "description": "Id of the parent frame, only present for the \\\"iframe\\\" targets.", "typeRef": "Page.FrameId"}, {"name": "browserContextId", "type": "string", "optional": true, "description": "", "typeRef": "Browser.BrowserContextID"}, {"name": "subtype", "type": "string", "optional": true, "description": "Provides additional details for specific target types. For example, for the type of \\\"page\\\", this may be set to \\\"prerender\\\".", "typeRef": null}]);
+inspectorBackend.registerType("Target.TargetInfo", [{"name": "targetId", "type": "string", "optional": false, "description": "", "typeRef": "Target.TargetID"}, {"name": "type", "type": "string", "optional": false, "description": "List of types: https://source.chromium.org/chromium/chromium/src/+/main:content/browser/devtools/devtools_agent_host_impl.cc?ss=chromium&q=f:devtools%20-f:out%20%22::kTypeTab%5B%5D%22", "typeRef": null}, {"name": "title", "type": "string", "optional": false, "description": "", "typeRef": null}, {"name": "url", "type": "string", "optional": false, "description": "", "typeRef": null}, {"name": "attached", "type": "boolean", "optional": false, "description": "Whether the target has an attached client.", "typeRef": null}, {"name": "openerId", "type": "string", "optional": true, "description": "Opener target Id", "typeRef": "Target.TargetID"}, {"name": "canAccessOpener", "type": "boolean", "optional": false, "description": "Whether the target has access to the originating window.", "typeRef": null}, {"name": "openerFrameId", "type": "string", "optional": true, "description": "Frame id of originating window (is only set if target has an opener).", "typeRef": "Page.FrameId"}, {"name": "parentFrameId", "type": "string", "optional": true, "description": "Id of the parent frame, present for \\\"iframe\\\" and \\\"worker\\\" targets. For nested workers, this is the \\\"ancestor\\\" frame that created the first worker in the nested chain.", "typeRef": "Page.FrameId"}, {"name": "browserContextId", "type": "string", "optional": true, "description": "", "typeRef": "Browser.BrowserContextID"}, {"name": "subtype", "type": "string", "optional": true, "description": "Provides additional details for specific target types. For example, for the type of \\\"page\\\", this may be set to \\\"prerender\\\".", "typeRef": null}]);
 inspectorBackend.registerType("Target.FilterEntry", [{"name": "exclude", "type": "boolean", "optional": true, "description": "If set, causes exclusion of matching targets from the list.", "typeRef": null}, {"name": "type", "type": "string", "optional": true, "description": "If not present, matches any type.", "typeRef": null}]);
 inspectorBackend.registerType("Target.TargetFilter", [{"name": "TargetFilter", "type": "array", "optional": false, "description": "The entries in TargetFilter are matched sequentially against targets and the first entry that matches determines if the target is included or not, depending on the value of `exclude` field in the entry. If filter is not specified, the one assumed is [{type: \\\"browser\\\", exclude: true}, {type: \\\"tab\\\", exclude: true}, {}] (i.e. include everything but `browser` and `tab`).", "typeRef": "Target.FilterEntry"}]);
 inspectorBackend.registerType("Target.RemoteLocation", [{"name": "host", "type": "string", "optional": false, "description": "", "typeRef": null}, {"name": "port", "type": "number", "optional": false, "description": "", "typeRef": null}]);
@@ -1489,7 +1489,7 @@ inspectorBackend.registerType("WebAuthn.VirtualAuthenticatorOptions", [{"name":
 inspectorBackend.registerType("WebAuthn.Credential", [{"name": "credentialId", "type": "string", "optional": false, "description": "", "typeRef": null}, {"name": "isResidentCredential", "type": "boolean", "optional": false, "description": "", "typeRef": null}, {"name": "rpId", "type": "string", "optional": true, "description": "Relying Party ID the credential is scoped to. Must be set when adding a credential.", "typeRef": null}, {"name": "privateKey", "type": "string", "optional": false, "description": "The ECDSA P-256 private key in PKCS#8 format.", "typeRef": null}, {"name": "userHandle", "type": "string", "optional": true, "description": "An opaque byte sequence with a maximum size of 64 bytes mapping the credential to a specific user.", "typeRef": null}, {"name": "signCount", "type": "number", "optional": false, "description": "Signature counter. This is incremented by one for each successful assertion. See https://w3c.github.io/webauthn/#signature-counter", "typeRef": null}, {"name": "largeBlob", "type": "string", "optional": true, "description": "The large blob associated with the credential. See https://w3c.github.io/webauthn/#sctn-large-blob-extension", "typeRef": null}, {"name": "backupEligibility", "type": "boolean", "optional": true, "description": "Assertions returned by this credential will have the backup eligibility (BE) flag set to this value. Defaults to the authenticator's defaultBackupEligibility value.", "typeRef": null}, {"name": "backupState", "type": "boolean", "optional": true, "description": "Assertions returned by this credential will have the backup state (BS) flag set to this value. Defaults to the authenticator's defaultBackupState value.", "typeRef": null}, {"name": "userName", "type": "string", "optional": true, "description": "The credential's user.name property. Equivalent to empty if not set. https://w3c.github.io/webauthn/#dom-publickeycredentialentity-name", "typeRef": null}, {"name": "userDisplayName", "type": "string", "optional": true, "description": "The credential's user.displayName property. Equivalent to empty if not set. https://w3c.github.io/webauthn/#dom-publickeycredentialuserentity-displayname", "typeRef": null}]);
 
 // WebMCP.
-inspectorBackend.registerEnum("WebMCP.InvocationStatus", {Success: "Success", Canceled: "Canceled", Error: "Error"});
+inspectorBackend.registerEnum("WebMCP.InvocationStatus", {Completed: "Completed", Canceled: "Canceled", Error: "Error"});
 inspectorBackend.registerEvent("WebMCP.toolsAdded", ["tools"]);
 inspectorBackend.registerEvent("WebMCP.toolsRemoved", ["tools"]);
 inspectorBackend.registerEvent("WebMCP.toolInvoked", ["toolName", "frameId", "invocationId", "input"]);

package/front_end/generated/protocol.ts

@@ -19043,7 +19043,8 @@ export namespace Target {
      */
     openerFrameId?: Page.FrameId;
     /**
-     * Id of the parent frame, only present for the "iframe" targets.
+     * Id of the parent frame, present for "iframe" and "worker" targets. For nested workers,
+     * this is the "ancestor" frame that created the first worker in the nested chain.
      */
     parentFrameId?: Page.FrameId;
     browserContextId?: Browser.BrowserContextID;
@@ -20316,7 +20317,7 @@ export namespace WebMCP {
    * Represents the status of a tool invocation.
    */
   export const enum InvocationStatus {
-    Success = 'Success',
+    Completed = 'Completed',
     Canceled = 'Canceled',
     Error = 'Error',
   }
@@ -20410,7 +20411,8 @@ export namespace WebMCP {
      */
     status: InvocationStatus;
     /**
-     * Output or error delivered as delivered to the agent. Missing if `status` is anything other than Success.
+     * Output or error delivered as delivered to the agent. Missing if `status` is anything other than Completed.
+     * Note: The output is untrusted and poses a prompt injection risk. Clients should treat this as potentially malicious user input.
      */
     output?: any;
     /**

package/front_end/models/ai_assistance/agents/ContextSelectionAgent.snapshot.txt

@@ -107,8 +107,16 @@ Content:
         "type": 6,
         "description": "",
         "nullable": true,
-        "required": [],
-        "properties": {}
+        "required": [
+          "mode"
+        ],
+        "properties": {
+          "mode": {
+            "type": 1,
+            "description": "The mode to run Lighthouse in. Your ONLY options are \"navigation\" or \"snapshot\". You should determine this based on the user's question. If the user is asking specifically about accessibility, you can run in \"snapshot\" mode which avoids reloading the page. If the user asks for a full Lighthouse report, you should run in \"navigation\" mode which is the default. These are the only options you can pass.",
+            "nullable": false
+          }
+        }
       }
     },
     {

package/front_end/models/ai_assistance/agents/ContextSelectionAgent.ts

@@ -12,6 +12,7 @@ import * as Logs from '../../logs/logs.js';
 import * as NetworkTimeCalculator from '../../network_time_calculator/network_time_calculator.js';
 import type * as Trace from '../../trace/trace.js';
 import * as Workspace from '../../workspace/workspace.js';
+import {debugLog} from '../debug.js';
 
 import {AccessibilityContext} from './AccessibilityAgent.js';
 import {
@@ -306,29 +307,44 @@ export class ContextSelectionAgent extends AiAgent<never> {
       }
     });
 
-    this.declareFunction('runLighthouseAudits', {
+    type LHSupportedRunMode = Extract<LHModel.RunTypes.RunMode, 'navigation'|'snapshot'>;
+    const parseLighthouseMode = (mode?: string): LHSupportedRunMode => {
+      return mode === 'snapshot' ? 'snapshot' : 'navigation';
+    };
+
+    this.declareFunction<{mode: LHSupportedRunMode}>('runLighthouseAudits', {
       description:
           'Records a Lighthouse audit on the current page. Use this to debug accessibility, SEO, and best practices. (For performance metrics like LCP, use performanceRecordAndReload instead).',
       parameters: {
         type: Host.AidaClient.ParametersTypes.OBJECT,
         description: '',
         nullable: true,
-        required: [],
-        properties: {},
+        required: ['mode'],
+        properties: {
+          mode: {
+            type: Host.AidaClient.ParametersTypes.STRING,
+            description:
+                'The mode to run Lighthouse in. Your ONLY options are "navigation" or "snapshot". You should determine this based on the user\'s question. If the user is asking specifically about accessibility, you can run in "snapshot" mode which avoids reloading the page. If the user asks for a full Lighthouse report, you should run in "navigation" mode which is the default. These are the only options you can pass.',
+            nullable: false,
+          }
+        },
       },
-      displayInfoFromArgs: () => {
+      displayInfoFromArgs: args => {
+        const mode = parseLighthouseMode(args.mode);
         return {
           title: 'Auditing your page with Lighthouse',
-          action: 'runLighthouseAudits()',
+          action: `runLighthouseAudits(${mode})`,
         };
       },
-      handler: async () => {
+      handler: async params => {
         if (!this.#lighthouseRecording) {
           return {
             error: 'Lighthouse report is not available.',
           };
         }
-        const result = await this.#lighthouseRecording();
+        const mode = parseLighthouseMode(params.mode);
+        debugLog(`Recording with Lighthouse; runMode=${mode}`);
+        const result = await this.#lighthouseRecording({mode});
         if (!result) {
           return {error: 'Failed to generate Lighthouse report.'};
         }

package/front_end/models/ai_assistance/agents/PerformanceAgent.ts

@@ -49,6 +49,13 @@ const UIStringsNotTranslated = {
 } as const;
 const lockedString = i18n.i18n.lockedString;
 
+/**
+ * Labels used to identify specific periods or categories in the trace for getting main thread summary.
+ * Supports hardcoded phases, dynamic navigation IDs (`NAVIGATION_X`), and insight models.
+ */
+type MainThreadSectionLabel = 'nav-to-lcp'|'lcp-ttfb'|'lcp-render-delay'|'trace-bounds'|'NO_NAVIGATION'|
+                              `NAVIGATION_${string}`|keyof Trace.Insights.Types.InsightModels;
+
 /**
  * WARNING: preamble defined in code is only used when userTier is
  * TESTERS. Otherwise, a server-side preamble is used (see
@@ -102,7 +109,8 @@ You can also use this key with \`selectEventByKey\` to show the user a specific
 
 ## Step-by-step instructions for debugging performance issues
 
-Note: if the user asks a specific question about the trace (such as "What is my LCP?", or "How many requests were render-blocking?", directly answer their question and skip starting a performance investigation. Otherwise, your task is to collaborate with the user to discover and resolve real performance issues.
+Note: if the user asks a specific question about the trace (such as "What is my LCP?", or "How many requests were render-blocking?"), directly answer their question using available data. However, if the user asks a general question like "What performance issues exist?" or requests an investigation, you MUST NOT give a generic answer. You must treat it as a full performance investigation (Step 1) and call main thread functions to find specific issues. Generic advice like "reduce long tasks" without specific details is UNACCEPTABLE.
+
 
 ### Step 1: Determine a performance problem to investigate
 
@@ -138,11 +146,22 @@ Note: if the user asks a specific question about the trace (such as "What is my
 
 ## Guidelines
 
+- You must call \`getMainThreadTrackSummary\` (by specifying a time range) or \`getMainThreadTrackSummaryByLabel\` (with the relevant label) to investigate the main thread activity before giving the user a reply or suggesting solutions for any performance problem or insight. Call \`getMainThreadTrackSummary\` with specific bounds when you identify a specific time range of interest from the initial data. This applies even if you already have some information about that period from \`getInsightDetails\` or the initial trace summary.
+- Dig Deeper: Before replying, you should really dig into the main thread activity to uncover what the performance issues actually are. Use the initially provided main thread data as a reference to identify interesting tasks or time ranges, and then use those time bounds to call functions like \`getMainThreadTrackSummary\` to get more detailed data. Do not solely rely on the information from the initial data; ensure you identify the root cause before suggesting solutions.
+- No Shortcutting: Even if the initial facts contain specific line numbers or function names, you are not allowed to reply using only that information. You MUST call \`getMainThreadTrackSummary\` with the time bounds of the task to inspect its full context and children before describing it to the user.
+- Look for Aggregated Cost: Performance issues are not always caused by a single "Long Task". Many small, frequent events (like unthrottled \`mousemove\` or \`scroll\` handlers) can add up to significant main thread blockage. Use the Bottom-Up summary in \`getMainThreadTrackSummary\` to identify functions with high total time, even if they are not associated with a Long Task.
 - Use the provided functions to get detailed performance data. Prioritize functions that provide context relevant to the performance issue being investigated.
 - Before finalizing your advice, look over it and validate using any relevant functions. If something seems off, refine the advice before giving it to the user.
 - Base your analysis and advice solely on the data retrieved through the provided functions. Always use the provided functions to gather sufficient data when needed.
 - Use absolute microsecond timestamps for any function that requires a \`min\` and \`max\` bounds. These timestamps can be found in the trace summary or within the details of an insight.
 - Example: If the trace bounds are {min: 1000, max: 5000} and you want to investigate a specific interaction that happened between 2000 and 3000, you should call \`getMainThreadTrackSummary({min: 2000, max: 3000})\`.
+- Available labels for \`getMainThreadTrackSummaryByLabel\` include:
+  - \`trace-bounds\` (entire trace)
+  - \`nav-to-lcp\` (navigation to LCP)
+  - \`lcp-ttfb\` (LCP TTFB phase)
+  - \`lcp-render-delay\` (LCP render delay phase)
+  - Insight names: \`LCPBreakdown\`, \`CLSCulprits\`, \`RenderBlocking\`, \`NetworkDependencyTree\`, \`ImageDelivery\`, \`FontDisplay\`, \`ThirdParties\`, \`ForcedReflow\`, \`Cache\`, \`DOMSize\`
+  - Navigation IDs: \`NAVIGATION_0\`, \`NAVIGATION_1\`, etc.
 - Use \`getEventByKey\` to get data on a specific trace event. This is great for root-cause analysis or validating any assumptions.
 - Provide clear, actionable recommendations. Avoid technical jargon unless necessary, and explain any technical terms used.
 - If you see a generic task like "Task", "Evaluate script" or "(anonymous)" in the main thread activity, try to look at its children to see what actual functions are executed and refer to those. When referencing the main thread activity, be as specific as you can. Ensure you identify to the user relevant functions and which script they were defined in. Avoid referencing "Task", "Evaluate script" and "(anonymous)" nodes if possible and instead focus on their children.
@@ -777,6 +796,52 @@ export class PerformanceAgent extends AiAgent<AgentFocus> {
     this.#functionCallCacheForFocus.set(focus, cache);
   }
 
+  async #handleMainThreadTrackSummary(
+      bounds: Trace.Types.Timing.TraceWindowMicro,
+      focus: AgentFocus,
+      functionName: string,
+      cacheKey: string,
+      ): Promise<FunctionCallHandlerResult<{summary: string}>> {
+    const formatter = this.#formatter;
+    if (!formatter) {
+      throw new Error('missing formatter');
+    }
+    const summary = await formatter.formatMainThreadTrackSummary(bounds);
+    if (this.#isFunctionResponseTooLarge(summary)) {
+      return {
+        error:
+            `${functionName} response is too large. Try investigating using other functions, or a more narrow bounds`,
+      };
+    }
+
+    const byteCount = Platform.StringUtilities.countWtf8Bytes(summary);
+    Host.userMetrics.performanceAIMainThreadActivityResponseSize(byteCount);
+
+    this.#cacheFunctionResult(focus, cacheKey, summary);
+    const widgets: AiWidget[] = [];
+    widgets.push({
+      name: 'TIMELINE_RANGE_SUMMARY',
+      data: {
+        parsedTrace: focus.parsedTrace,
+        bounds,
+        track: 'main',
+      },
+    });
+
+    widgets.push({
+      name: 'BOTTOM_UP_TREE',
+      data: {
+        bounds,
+        parsedTrace: focus.parsedTrace,
+      },
+    });
+
+    return {
+      result: {summary},
+      widgets,
+    };
+  }
+
   #declareFunctions(context: PerformanceTraceContext): void {
     const focus = context.getItem();
     const {parsedTrace} = focus;
@@ -972,53 +1037,51 @@ export class PerformanceAgent extends AiAgent<AgentFocus> {
       handler: async args => {
         debugLog('Function call: getMainThreadTrackSummary');
 
-        if (!this.#formatter) {
-          throw new Error('missing formatter');
-        }
-
         const bounds = createBounds(args.min, args.max);
         if (!bounds) {
           return {error: 'invalid bounds'};
         }
 
-        const formatter = this.#formatter;
-        const summary = await formatter.formatMainThreadTrackSummary(bounds);
-        if (this.#isFunctionResponseTooLarge(summary)) {
-          return {
-            error:
-                'getMainThreadTrackSummary response is too large. Try investigating using other functions, or a more narrow bounds',
-          };
-        }
-
-        const byteCount = Platform.StringUtilities.countWtf8Bytes(summary);
-        Host.userMetrics.performanceAIMainThreadActivityResponseSize(byteCount);
-
         const key = `getMainThreadTrackSummary({min: ${bounds.min}, max: ${bounds.max}})`;
-        this.#cacheFunctionResult(focus, key, summary);
-        const widgets: AiWidget[] = [];
-        widgets.push({
-          name: 'TIMELINE_RANGE_SUMMARY',
-          data: {
-            parsedTrace,
-            bounds,
-            track: 'main',
-          },
-        });
+        return await this.#handleMainThreadTrackSummary(bounds, focus, 'getMainThreadTrackSummary', key);
+      },
 
-        widgets.push({
-          name: 'BOTTOM_UP_TREE',
-          data: {
-            bounds,
-            parsedTrace,
-          },
-        });
+    });
 
+    this.declareFunction<{label: MainThreadSectionLabel}, {summary: string}>('getMainThreadTrackSummaryByLabel', {
+      description:
+          'Returns a focused, detailed summary of the main thread for a predefined labeled period. Use this to get more relevant detail than the initial trace summary before diagnosing issues.',
+      parameters: {
+        type: Host.AidaClient.ParametersTypes.OBJECT,
+        description: '',
+        nullable: false,
+        properties: {
+          label: {
+            type: Host.AidaClient.ParametersTypes.STRING,
+            description:
+                'The label of the period to investigate (e.g., \'LCPBreakdown\', \'CLSCulprits\', \'nav-to-lcp\').',
+            nullable: false,
+          },
+        },
+        required: ['label']
+      },
+      displayInfoFromArgs: args => {
         return {
-          result: {summary},
-          widgets,
+          title: lockedString(UIStringsNotTranslated.mainThreadActivity),
+          action: `getMainThreadTrackSummaryByLabel('${args.label}')`
         };
       },
+      handler: async args => {
+        debugLog('Function call: getMainThreadTrackSummaryByLabel');
+
+        const bounds = this.#getBoundsForLabel(args.label, focus);
+        if (!bounds) {
+          return {error: `Invalid label: ${args.label}`};
+        }
 
+        const key = `getMainThreadTrackSummaryByLabel('${args.label}')`;
+        return await this.#handleMainThreadTrackSummary(bounds, focus, 'getMainThreadTrackSummaryByLabel', key);
+      },
     });
 
     this.declareFunction<
@@ -1362,6 +1425,68 @@ export class PerformanceAgent extends AiAgent<AgentFocus> {
     }
   }
 
+  #getBoundsForLabel(label: MainThreadSectionLabel, focus: AgentFocus): Trace.Types.Timing.TraceWindowMicro|null {
+    const {parsedTrace} = focus;
+    const insightSet = focus.primaryInsightSet;
+
+    if (label === 'nav-to-lcp') {
+      if (insightSet) {
+        const lcp = Trace.Insights.Common.getLCP(insightSet);
+        if (lcp) {
+          return Trace.Helpers.Timing.traceWindowFromMicroSeconds(
+              insightSet.bounds.min, lcp.event.ts as Trace.Types.Timing.Micro);
+        }
+      }
+      return null;
+    }
+
+    if (label === 'lcp-ttfb') {
+      if (insightSet) {
+        const subparts = insightSet.model.LCPBreakdown?.subparts;
+        if (subparts?.ttfb) {
+          return subparts.ttfb;
+        }
+      }
+      return null;
+    }
+
+    if (label === 'lcp-render-delay') {
+      if (insightSet) {
+        const subparts = insightSet.model.LCPBreakdown?.subparts;
+        if (subparts?.renderDelay) {
+          return subparts.renderDelay;
+        }
+      }
+      return null;
+    }
+
+    if (label === 'trace-bounds') {
+      return parsedTrace.data.Meta.traceBounds;
+    }
+
+    for (const is of parsedTrace.insights?.values() ?? []) {
+      if (is.id === label) {
+        return is.bounds;
+      }
+    }
+
+    if (insightSet) {
+      const model = insightSet.model[label as keyof Trace.Insights.Types.InsightModels];
+      if (model) {
+        return Trace.Insights.Common.insightBounds(model, insightSet.bounds);
+      }
+    }
+
+    for (const is of parsedTrace.insights?.values() ?? []) {
+      const model = is.model[label as keyof Trace.Insights.Types.InsightModels];
+      if (model) {
+        return Trace.Insights.Common.insightBounds(model, is.bounds);
+      }
+    }
+
+    return null;
+  }
+
   async addElementAnnotation(elementId: string, annotationMessage: string):
       Promise<FunctionCallHandlerResult<unknown>> {
     if (!Annotations.AnnotationRepository.annotationsEnabled()) {