chrome-devtools-frontend 1.0.1697595 → 1.0.1697998

package/.stylelintignore

@@ -1,4 +1,5 @@
 front_end/third_party
+extensions/cxx_debugging/third_party
 karma-coverage
 node_modules
 out
@@ -8,3 +9,4 @@ test/**/*.ts
 third_party
 front_end/ui/components/docs
 build
+buildtools

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 = 46;
+  static readonly CURRENT_VERSION = 47;
 
   readonly #settings: Settings;
   readonly #globalVersionSetting: Setting<number>;
@@ -897,6 +897,10 @@ export class VersionController {
     }
   }
 
+  updateVersionFrom46To47(): void {
+    this.#settings.syncedStorage.remove('network.backend-linking-rules');
+  }
+
   /*
    * Any new migration should be added before this comment.
    *

package/front_end/core/sdk/AnimationModel.ts

@@ -920,7 +920,15 @@ export class AnimationGroup {
   }
 
   seekTo(currentTime: number): void {
-    void this.#animationModel.agent.invoke_seekAnimations({animations: this.animationIds(), currentTime});
+    const animations = [];
+    const currentTimes = [];
+    for (const animation of this.#animations) {
+      // Seek from the end of the animation if it is reversed.
+      animations.push(animation.id());
+      currentTimes.push(animation.playbackRate() >= 0 ? currentTime :
+                                                        animation.endTime() - animation.startTime() - currentTime);
+    }
+    void this.#animationModel.agent.invoke_seekAnimations({animations, currentTimes});
   }
 
   paused(): boolean {

package/front_end/generated/InspectorBackendCommands.ts

@@ -62,7 +62,7 @@ inspectorBackend.registerCommand("Animation.getCurrentTime", [{"name": "id", "ty
 inspectorBackend.registerCommand("Animation.getPlaybackRate", [], ["playbackRate"], "Gets the playback rate of the document timeline.");
 inspectorBackend.registerCommand("Animation.releaseAnimations", [{"name": "animations", "type": "array", "optional": false, "description": "List of animation ids to seek.", "typeRef": "string"}], [], "Releases a set of animations to no longer be manipulated.");
 inspectorBackend.registerCommand("Animation.resolveAnimation", [{"name": "animationId", "type": "string", "optional": false, "description": "Animation id.", "typeRef": null}], ["remoteObject"], "Gets the remote object of the Animation.");
-inspectorBackend.registerCommand("Animation.seekAnimations", [{"name": "animations", "type": "array", "optional": false, "description": "List of animation ids to seek.", "typeRef": "string"}, {"name": "currentTime", "type": "number", "optional": false, "description": "Set the current time of each animation.", "typeRef": null}], [], "Seek a set of animations to a particular time within each animation.");
+inspectorBackend.registerCommand("Animation.seekAnimations", [{"name": "animations", "type": "array", "optional": false, "description": "List of animation ids to seek.", "typeRef": "string"}, {"name": "currentTime", "type": "number", "optional": true, "description": "Set each animation to the same time.", "typeRef": null}, {"name": "currentTimes", "type": "array", "optional": true, "description": "Set each animation to a different time. If set, should have the same length as animations. Exactly one of currentTime or currentTimes should be set.", "typeRef": "number"}], [], "Seek a set of animations to a particular time within each animation.");
 inspectorBackend.registerCommand("Animation.setPaused", [{"name": "animations", "type": "array", "optional": false, "description": "Animations to set the pause state of.", "typeRef": "string"}, {"name": "paused", "type": "boolean", "optional": false, "description": "Paused state to set to.", "typeRef": null}], [], "Sets the paused state of a set of animations.");
 inspectorBackend.registerCommand("Animation.setPlaybackRate", [{"name": "playbackRate", "type": "number", "optional": false, "description": "Playback rate for animations on page", "typeRef": null}], [], "Sets the playback rate of the document timeline.");
 inspectorBackend.registerCommand("Animation.setTiming", [{"name": "animationId", "type": "string", "optional": false, "description": "Animation id.", "typeRef": null}, {"name": "duration", "type": "number", "optional": false, "description": "Duration of the animation.", "typeRef": null}, {"name": "delay", "type": "number", "optional": false, "description": "Delay of the animation.", "typeRef": null}], [], "Sets the timing of an animation node.");

package/front_end/generated/protocol.ts

@@ -749,9 +749,15 @@ export namespace Animation {
      */
     animations: string[];
     /**
-     * Set the current time of each animation.
+     * Set each animation to the same time.
      */
-    currentTime: number;
+    currentTime?: number;
+    /**
+     * Set each animation to a different time. If set, should have the same
+     * length as animations. Exactly one of currentTime or currentTimes should
+     * be set.
+     */
+    currentTimes?: number[];
   }
 
   export interface SetPausedRequest {

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

@@ -20,6 +20,7 @@ import {StorageContext} from '../contexts/StorageContext.js';
 import {formatBytesToKb, seconds} from '../data_formatters/UnitFormatters.js';
 import {debugLog} from '../debug.js';
 import {StorageItem} from '../StorageItem.js';
+import {isOriginAllowedByLock} from '../tools/Tool.js';
 
 import {
   type AgentOptions,
@@ -587,4 +588,29 @@ export class ContextSelectionAgent extends AiAgent<never> {
 
     return [...uiSourceCodes.values()];
   }
+
+  /**
+   * Resolves a workspace source file by its ID, ensuring that the file's security
+   * origin is authorized by the conversation's established origin lock.
+   *
+   * Fails closed by returning `undefined` if the established origin is missing or opaque,
+   * if the file ID is invalid, or if the file origin does not match the lock.
+   */
+  static getSourceById(
+      id: number,
+      establishedOrigin?: SDK.SecurityOrigin.SecurityOrigin,
+      // eslint-disable-next-line @devtools/no-instance-of-migrated-singletons
+      workspace: Workspace.Workspace.WorkspaceImpl = Workspace.Workspace.WorkspaceImpl.instance(),
+      ): Workspace.UISourceCode.UISourceCode|undefined {
+    if (!establishedOrigin || !Number.isInteger(id) || id <= 0) {
+      return undefined;
+    }
+    return ContextSelectionAgent.getUISourceCodes(workspace).find(file => {
+      if (ContextSelectionAgent.uiSourceCodeId.get(file) !== id) {
+        return false;
+      }
+      return isOriginAllowedByLock({status: 'ESTABLISHED_ORIGIN', origin: establishedOrigin},
+                                   FileContext.originForUISourceCode(file));
+    });
+  }
 }

package/front_end/models/ai_assistance/ai_assistance.ts

@@ -46,18 +46,18 @@ import * as ExecuteJavaScript from './tools/ExecuteJavaScript.js';
 import * as GetCookieValues from './tools/GetCookieValues.js';
 import * as GetDetailedCallTree from './tools/GetDetailedCallTree.js';
 import * as GetElementAccessibilityDetails from './tools/GetElementAccessibilityDetails.js';
-import * as GetFunctionCode from './tools/GetFunctionCode.js';
 import * as GetInsightDetails from './tools/GetInsightDetails.js';
 import * as GetLighthouseAudits from './tools/GetLighthouseAudits.js';
 import * as GetNetworkRequestDetails from './tools/GetNetworkRequestDetails.js';
-import * as GetResourceContent from './tools/GetResourceContent.js';
 import * as GetSourceContent from './tools/GetSourceContent.js';
 import * as GetStorageBreakdown from './tools/GetStorageBreakdown.js';
 import * as GetStorageValues from './tools/GetStorageValues.js';
 import * as GetStyles from './tools/GetStyles.js';
 import * as GetTraceEventByKey from './tools/GetTraceEventByKey.js';
+import * as GetTraceFunctionCode from './tools/GetTraceFunctionCode.js';
 import * as GetTraceMainThreadSummary from './tools/GetTraceMainThreadSummary.js';
 import * as GetTraceNetworkSummary from './tools/GetTraceNetworkSummary.js';
+import * as GetTraceResourceContent from './tools/GetTraceResourceContent.js';
 import * as ListCookies from './tools/ListCookies.js';
 import * as ListNetworkRequests from './tools/ListNetworkRequests.js';
 import * as ListPageOrigins from './tools/ListPageOrigins.js';
@@ -99,18 +99,18 @@ export {
   GetCookieValues,
   GetDetailedCallTree,
   GetElementAccessibilityDetails,
-  GetFunctionCode,
   GetInsightDetails,
   GetLighthouseAudits,
   GetNetworkRequestDetails,
-  GetResourceContent,
   GetSourceContent,
   GetStorageBreakdown,
   GetStorageValues,
   GetStyles,
   GetTraceEventByKey,
+  GetTraceFunctionCode,
   GetTraceMainThreadSummary,
   GetTraceNetworkSummary,
+  GetTraceResourceContent,
   Injected,
   LighthouseFormatter,
   ListCookies,

package/front_end/models/ai_assistance/skills/performance.md

@@ -8,8 +8,8 @@ allowed-tools:
   - getTraceMainThreadSummary
   - getTraceNetworkSummary
   - getDetailedCallTree
-  - getFunctionCode
-  - getResourceContent
+  - getTraceFunctionCode
+  - getTraceResourceContent
   - getInsightDetails
 ---
 You are an expert web performance assistant integrated into Chrome DevTools.
@@ -29,7 +29,8 @@ Your goal is to provide actionable advice about web page performance by analyzin
 3. **Call Tree, Event & Source Inspection**:
    - Use `getDetailedCallTree` to retrieve bottom-up execution trees for expensive main thread tasks.
    - Use `getTraceEventByKey` to inspect timing and payload data for individual events.
-   - Use `getFunctionCode` or `getResourceContent` to inspect the source code and identify root causes.
+   - Use `getTraceFunctionCode` to inspect a specific function identified in the call tree, including line-by-line CPU profile execution costs.
+   - Use `getTraceResourceContent` to inspect the full text of a script or resource captured within the trace by URL.
 
 4. **UI Selection & Trace Recording**:
    - Use `selectTraceEventByKey` to reveal and select an event in the Performance Flamechart if requested.

package/front_end/models/ai_assistance/tools/{GetFunctionCode.ts → GetTraceFunctionCode.ts}

@@ -21,54 +21,67 @@ const UIStringsNotTranslate = {
 
 const lockedString = i18n.i18n.lockedString;
 
-export interface GetFunctionCodeArgs extends ToolArgs {
+/**
+ * Arguments for {@link GetTraceFunctionCodeTool}.
+ */
+export interface GetTraceFunctionCodeArgs extends ToolArgs {
+  /** The URL of the script containing the function recorded in the performance trace. */
   scriptUrl: string;
+  /** The line number where the function is defined (0-based, as reported in the call tree). */
   line: number;
+  /** The column number where the function is defined (0-based, as reported in the call tree). */
   column: number;
 }
 
-export class GetFunctionCodeTool implements
-    DataTool<GetFunctionCodeArgs, string, BaseToolCapability&PerformanceTraceCapability> {
-  readonly name: ToolName = ToolName.GET_FUNCTION_CODE;
+/**
+ * Retrieves function code and line-by-line CPU profile execution costs from the performance trace.
+ *
+ * Preconditions:
+ * - Requires an active, freshly recorded trace session (fails on imported traces).
+ * - Requires resource access via the performance trace context.
+ */
+export class GetTraceFunctionCodeTool implements
+    DataTool<GetTraceFunctionCodeArgs, string, BaseToolCapability&PerformanceTraceCapability> {
+  readonly name: ToolName = ToolName.GET_TRACE_FUNCTION_CODE;
   readonly description: string =
-      'Retrieves the code for a function defined at the given location. The result is annotated with the runtime performance of each line of code.';
+      'Retrieves the code for a function recorded in the performance trace at the specified location, annotated with line-by-line CPU runtime profiling execution costs. Do not call this tool unless a performance trace recording is actively loaded.';
 
-  readonly parameters: Host.AidaClient.FunctionObjectParam<keyof GetFunctionCodeArgs> = {
+  readonly parameters: Host.AidaClient.FunctionObjectParam<keyof GetTraceFunctionCodeArgs> = {
     type: Host.AidaClient.ParametersTypes.OBJECT,
-    description: 'Arguments for looking up function code.',
+    description: 'Arguments for looking up function code from the performance trace profile.',
     nullable: false,
     properties: {
       scriptUrl: {
         type: Host.AidaClient.ParametersTypes.STRING,
-        description: 'The url of the function.',
+        description: 'The URL of the script containing the function recorded in the performance trace.',
         nullable: false,
       },
       line: {
         type: Host.AidaClient.ParametersTypes.INTEGER,
-        description: 'The line number where the function is defined.',
+        description: 'The line number where the function is defined (0-based, as reported in the call tree).',
         nullable: false,
       },
       column: {
         type: Host.AidaClient.ParametersTypes.INTEGER,
-        description: 'The column number where the function is defined.',
+        description: 'The column number where the function is defined (0-based, as reported in the call tree).',
         nullable: false,
       },
     },
     required: ['scriptUrl', 'line', 'column'],
   };
 
-  displayInfoFromArgs(params: GetFunctionCodeArgs): {
+  displayInfoFromArgs(params: GetTraceFunctionCodeArgs): {
     title: string,
     action: string,
   } {
     return {
       title: lockedString(UIStringsNotTranslate.lookingUpFunctionCode),
-      action: `getFunctionCode('${params.scriptUrl}', ${params.line}, ${params.column})`,
+      action: `getTraceFunctionCode('${params.scriptUrl}', ${params.line}, ${params.column})`,
     };
   }
 
   async handler(
-      params: GetFunctionCodeArgs,
+      params: GetTraceFunctionCodeArgs,
       capabilities: BaseToolCapability&PerformanceTraceCapability,
       ): Promise<DataHandlerResult<string>> {
     const performanceTraceContext = capabilities.getPerformanceTraceContext();

package/front_end/models/ai_assistance/tools/{GetResourceContent.ts → GetTraceResourceContent.ts}

@@ -25,42 +25,57 @@ const UIStringsNotTranslate = {
 
 const lockedString = i18n.i18n.lockedString;
 
-export interface GetResourceContentArgs extends ToolArgs {
+/**
+ * Arguments for {@link GetTraceResourceContentTool}.
+ */
+export interface GetTraceResourceContentArgs extends ToolArgs {
+  /** The URL of the resource captured in the performance trace to retrieve. */
   url: string;
 }
 
-export class GetResourceContentTool implements DataTool<
-    GetResourceContentArgs, {content: string}, BaseToolCapability&TargetCapability&PerformanceTraceCapability> {
-  readonly name: ToolName = ToolName.GET_RESOURCE_CONTENT;
+/**
+ * Retrieves text content for a resource or script captured in the performance trace.
+ *
+ * Precedence:
+ * 1. Checks trace metadata (`parsedTrace.data.Scripts`) for scripts captured during recording.
+ * 2. Falls back to querying the live page target's `ResourceTreeModel`.
+ *
+ * Preconditions:
+ * - Requires an active, freshly recorded trace session (fails on imported traces).
+ * - Fails if resource is binary/non-text, cross-origin, or a `file://` URL.
+ */
+export class GetTraceResourceContentTool implements DataTool<
+    GetTraceResourceContentArgs, {content: string}, BaseToolCapability&TargetCapability&PerformanceTraceCapability> {
+  readonly name: ToolName = ToolName.GET_TRACE_RESOURCE_CONTENT;
   readonly description: string =
-      'Retrieves the content of the resource with the given url. Only use this for text resource types.';
+      'Retrieves the text content of a script or resource captured within the recorded performance trace by URL. Only use this for text resource types. Do not call this tool on imported traces or for general workspace files (use listSources and getSourceContent instead).';
 
-  readonly parameters: Host.AidaClient.FunctionObjectParam<keyof GetResourceContentArgs> = {
+  readonly parameters: Host.AidaClient.FunctionObjectParam<keyof GetTraceResourceContentArgs> = {
     type: Host.AidaClient.ParametersTypes.OBJECT,
-    description: 'Arguments for looking up resource content.',
+    description: 'Arguments for looking up resource content from the performance trace.',
     nullable: false,
     properties: {
       url: {
         type: Host.AidaClient.ParametersTypes.STRING,
-        description: 'The url for the resource.',
+        description: 'The URL of the resource captured in the performance trace to retrieve.',
         nullable: false,
       },
     },
     required: ['url'],
   };
 
-  displayInfoFromArgs(params: GetResourceContentArgs): {
+  displayInfoFromArgs(params: GetTraceResourceContentArgs): {
     title: string,
     action: string,
   } {
     return {
       title: lockedString(UIStringsNotTranslate.lookingAtResourceContent),
-      action: `getResourceContent('${params.url}')`,
+      action: `getTraceResourceContent('${params.url}')`,
     };
   }
 
   async handler(
-      params: GetResourceContentArgs,
+      params: GetTraceResourceContentArgs,
       capabilities: BaseToolCapability&TargetCapability&PerformanceTraceCapability,
       ): Promise<DataHandlerResult<{content: string}>> {
     const performanceTraceContext = capabilities.getPerformanceTraceContext();
@@ -72,6 +87,10 @@ export class GetResourceContentTool implements DataTool<
       return {error: 'Cannot use this tool on an imported file.'};
     }
 
+    if (!params.url) {
+      return {error: 'Missing arg: url'};
+    }
+
     if (!performanceTraceContext.canAccessResource(params.url)) {
       return {error: 'Resource not found'};
     }
@@ -82,6 +101,7 @@ export class GetResourceContentTool implements DataTool<
     let content: string;
 
     const url = params.url as Platform.DevToolsPath.UrlString;
+    // Check trace metadata for scripts captured during recording before falling back to live page resources.
     const script = parsedTrace.data.Scripts?.scripts.find(script => script.url === params.url);
     if (script?.content !== undefined) {
       content = script.content;

package/front_end/models/ai_assistance/tools/Tool.ts

@@ -258,8 +258,8 @@ export const enum ToolName {
   GET_TRACE_NETWORK_SUMMARY = 'getTraceNetworkSummary',
   RUN_LIGHTHOUSE = 'runLighthouse',
   GET_DETAILED_CALL_TREE = 'getDetailedCallTree',
-  GET_FUNCTION_CODE = 'getFunctionCode',
-  GET_RESOURCE_CONTENT = 'getResourceContent',
+  GET_TRACE_FUNCTION_CODE = 'getTraceFunctionCode',
+  GET_TRACE_RESOURCE_CONTENT = 'getTraceResourceContent',
   GET_INSIGHT_DETAILS = 'getInsightDetails',
   GET_STORAGE_BREAKDOWN = 'getStorageBreakdown',
 }

package/front_end/models/ai_assistance/tools/ToolRegistry.ts

@@ -6,18 +6,18 @@ import {ExecuteJavaScriptTool} from './ExecuteJavaScript.js';
 import {GetCookieValuesTool} from './GetCookieValues.js';
 import {GetDetailedCallTreeTool} from './GetDetailedCallTree.js';
 import {GetElementAccessibilityDetailsTool} from './GetElementAccessibilityDetails.js';
-import {GetFunctionCodeTool} from './GetFunctionCode.js';
 import {GetInsightDetailsTool} from './GetInsightDetails.js';
 import {GetLighthouseAuditsTool} from './GetLighthouseAudits.js';
 import {GetNetworkRequestDetailsTool} from './GetNetworkRequestDetails.js';
-import {GetResourceContentTool} from './GetResourceContent.js';
 import {GetSourceContentTool} from './GetSourceContent.js';
 import {GetStorageBreakdownTool} from './GetStorageBreakdown.js';
 import {GetStorageValuesTool} from './GetStorageValues.js';
 import {GetStylesTool} from './GetStyles.js';
 import {GetTraceEventByKeyTool} from './GetTraceEventByKey.js';
+import {GetTraceFunctionCodeTool} from './GetTraceFunctionCode.js';
 import {GetTraceMainThreadSummaryTool} from './GetTraceMainThreadSummary.js';
 import {GetTraceNetworkSummaryTool} from './GetTraceNetworkSummary.js';
+import {GetTraceResourceContentTool} from './GetTraceResourceContent.js';
 import {ListCookiesTool} from './ListCookies.js';
 import {ListNetworkRequestsTool} from './ListNetworkRequests.js';
 import {ListPageOriginsTool} from './ListPageOrigins.js';
@@ -51,8 +51,8 @@ export interface BaseToolsRegistryMap {
   [ToolName.GET_TRACE_NETWORK_SUMMARY]: GetTraceNetworkSummaryTool;
   [ToolName.RUN_LIGHTHOUSE]: RunLighthouseTool;
   [ToolName.GET_DETAILED_CALL_TREE]: GetDetailedCallTreeTool;
-  [ToolName.GET_FUNCTION_CODE]: GetFunctionCodeTool;
-  [ToolName.GET_RESOURCE_CONTENT]: GetResourceContentTool;
+  [ToolName.GET_TRACE_FUNCTION_CODE]: GetTraceFunctionCodeTool;
+  [ToolName.GET_TRACE_RESOURCE_CONTENT]: GetTraceResourceContentTool;
   [ToolName.GET_INSIGHT_DETAILS]: GetInsightDetailsTool;
   [ToolName.GET_STORAGE_BREAKDOWN]: GetStorageBreakdownTool;
 }
@@ -86,8 +86,8 @@ export const TOOLS: BaseToolsRegistryMap = {
   [ToolName.GET_TRACE_NETWORK_SUMMARY]: new GetTraceNetworkSummaryTool(),
   [ToolName.RUN_LIGHTHOUSE]: new RunLighthouseTool(),
   [ToolName.GET_DETAILED_CALL_TREE]: new GetDetailedCallTreeTool(),
-  [ToolName.GET_FUNCTION_CODE]: new GetFunctionCodeTool(),
-  [ToolName.GET_RESOURCE_CONTENT]: new GetResourceContentTool(),
+  [ToolName.GET_TRACE_FUNCTION_CODE]: new GetTraceFunctionCodeTool(),
+  [ToolName.GET_TRACE_RESOURCE_CONTENT]: new GetTraceResourceContentTool(),
   [ToolName.GET_INSIGHT_DETAILS]: new GetInsightDetailsTool(),
   [ToolName.GET_STORAGE_BREAKDOWN]: new GetStorageBreakdownTool(),
 };

package/front_end/models/elements/DOMChanges.ts

@@ -0,0 +1,238 @@
+// 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 * as Platform from '../../core/platform/platform.js';
+import type * as SDK from '../../core/sdk/sdk.js';
+import type * as ChangeTracker from '../change_tracker/change_tracker.js';
+import type * as CommentManager from '../comment_manager/comment_manager.js';
+
+type Tracker = ChangeTracker.ChangeTracker.ChangeTracker|undefined;
+
+/**
+ * Maximum number of characters of page controlled data (tag names, attribute names and values,
+ * text node values and HTML) that a change description embeds. The inspected page fully controls
+ * these strings and `Changed HTML from ... to ...` in particular can otherwise hold on to the
+ * entire subtree of an element.
+ */
+export const MAX_VALUE_LENGTH = 100;
+
+/** Shortens page controlled data so that both its start and its end stay recognizable. */
+function trimValue(value: string): string {
+  return Platform.StringUtilities.trimMiddle(value, MAX_VALUE_LENGTH);
+}
+
+function buildAnchor(node: SDK.DOMModel.DOMNode,
+                     selector = 'element'): CommentManager.CommentManager.CommentAnchorSignature {
+  return {
+    vePath: 'Panel: elements > Tree: elements > TreeItem',
+    textSignature: selector,
+    node: {
+      backendNodeId: node.backendNodeId(),
+      targetId: node.domModel().target().id(),
+    },
+  };
+}
+
+/**
+ * Parses a raw attribute string (e.g. 'class="btn"', 'data-id=123', or 'disabled')
+ * into its attribute name and unquoted value for single-attribute inline edits.
+ */
+function parseAttributeText(text: string): {name: string, value: string} {
+  const trimmed = text.trim();
+  const eqIdx = trimmed.indexOf('=');
+  if (eqIdx === -1) {
+    return {name: trimmed, value: ''};
+  }
+  const name = trimmed.slice(0, eqIdx).trim();
+  let value = trimmed.slice(eqIdx + 1).trim();
+  if (value.length >= 2 &&
+      ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith('\'') && value.endsWith('\'')))) {
+    value = value.slice(1, -1);
+  }
+  return {name, value};
+}
+
+function describeAddAttribute(attributeName: string, value?: string): string {
+  if (value !== undefined && value !== '') {
+    return `Added attribute ${trimValue(attributeName)}="${trimValue(value)}"`;
+  }
+  return `Added attribute "${trimValue(attributeName)}"`;
+}
+
+function describeRemoveAttribute(attributeName: string): string {
+  return `Removed attribute "${trimValue(attributeName)}"`;
+}
+
+/**
+ * Describes a modification of an existing attribute, which covers renaming the attribute, changing
+ * its value, or both at once. `oldValue` is `undefined` if the previous value is unknown.
+ */
+function describeAttributeChange(
+    oldAttributeName: string,
+    oldValue: string|undefined,
+    newAttributeName: string,
+    newValue: string,
+    ): string {
+  if (oldAttributeName !== newAttributeName) {
+    if (oldValue !== undefined && oldValue !== newValue) {
+      return `Renamed attribute "${trimValue(oldAttributeName)}"="${trimValue(oldValue)}" to "${
+          trimValue(newAttributeName)}"="${trimValue(newValue)}"`;
+    }
+    return `Renamed attribute "${trimValue(oldAttributeName)}" to "${trimValue(newAttributeName)}"`;
+  }
+  if (oldValue !== undefined) {
+    return `Changed attribute "${trimValue(newAttributeName)}" from "${trimValue(oldValue)}" to "${
+        trimValue(newValue)}"`;
+  }
+  return `Changed attribute "${trimValue(newAttributeName)}" to "${trimValue(newValue)}"`;
+}
+
+export interface AttributeEdit {
+  /** Name of the edited attribute, or an empty string when a new attribute is added. */
+  attributeName: string;
+  /** Raw attribute text before the edit, if there was any. */
+  oldText: string|null;
+  /** Raw attribute text the user committed. Empty when the attribute is removed. */
+  newText: string;
+}
+
+function describeAttributeEdit({attributeName, oldText, newText}: AttributeEdit): string {
+  const parsedNew = parseAttributeText(newText);
+  const parsedOld = oldText !== null ? parseAttributeText(oldText) : undefined;
+
+  if (!newText.trim()) {
+    return describeRemoveAttribute(attributeName.trim());
+  }
+  if (!attributeName.trim()) {
+    return describeAddAttribute(parsedNew.name, parsedNew.value);
+  }
+  return describeAttributeChange(
+      attributeName.trim(),
+      parsedOld?.value,
+      parsedNew.name || attributeName.trim(),
+      parsedNew.value,
+  );
+}
+
+/**
+ * These strings are for the consumption by AI agents, they don't need to be translated.
+ */
+function describeTagNameEdit(oldTagName: string, newTagName: string): string {
+  return `Renamed tag from <${trimValue(oldTagName)}> to <${trimValue(newTagName)}>`;
+}
+
+function describeTextNodeEdit(oldText: string, newText: string): string {
+  return `Changed text from "${trimValue(oldText)}" to "${trimValue(newText)}"`;
+}
+
+function describeNodeRemoval(tagName: string): string {
+  return `Removed node <${trimValue(tagName)}>`;
+}
+
+function describeHTMLEdit(oldValue?: string, newValue?: string): string {
+  if (oldValue !== undefined && newValue !== undefined) {
+    return `Changed HTML from "${trimValue(oldValue)}" to "${trimValue(newValue)}"`;
+  }
+  if (newValue !== undefined) {
+    return `Changed HTML to "${trimValue(newValue)}"`;
+  }
+  return 'Edited HTML';
+}
+
+function describeVisibilityToggle(tagName: string, hidden: boolean): string {
+  return hidden ? `Hid element <${trimValue(tagName)}>` : `Unhid element <${trimValue(tagName)}>`;
+}
+
+function describeNodeDuplication(tagName: string): string {
+  return `Duplicated node <${trimValue(tagName)}>`;
+}
+
+function describeNodeMove(tagName: string, directionUp: boolean): string {
+  return `Moved node <${trimValue(tagName)}> ${directionUp ? 'up' : 'down'}`;
+}
+
+function describeNodeDrop(tagName: string): string {
+  return `Moved node <${trimValue(tagName)}> via drag and drop`;
+}
+
+function describeNodePaste(tagName: string, isCut: boolean): string {
+  return isCut ? `Pasted (moved) node <${trimValue(tagName)}>` : `Pasted node <${trimValue(tagName)}>`;
+}
+
+export function trackAttributeEdit(tracker: Tracker, node: SDK.DOMModel.DOMNode, selector: string|undefined,
+                                   edit: AttributeEdit): void {
+  if (!tracker?.isTracking) {
+    return;
+  }
+  tracker.trackChange(describeAttributeEdit(edit), buildAnchor(node, selector));
+}
+
+export function trackTagNameEdit(tracker: Tracker, node: SDK.DOMModel.DOMNode, selector: string|undefined,
+                                 oldTagName: string, newTagName: string): void {
+  if (!tracker?.isTracking) {
+    return;
+  }
+  tracker.trackChange(describeTagNameEdit(oldTagName, newTagName), buildAnchor(node, selector));
+}
+
+export function trackTextNodeEdit(tracker: Tracker, node: SDK.DOMModel.DOMNode, selector: string|undefined,
+                                  oldText: string, newText: string): void {
+  if (!tracker?.isTracking) {
+    return;
+  }
+  tracker.trackChange(describeTextNodeEdit(oldText, newText), buildAnchor(node, selector));
+}
+
+export function trackNodeRemoval(tracker: Tracker, node: SDK.DOMModel.DOMNode, selector: string|undefined): void {
+  if (!tracker?.isTracking) {
+    return;
+  }
+  tracker.trackChange(describeNodeRemoval(node.nodeName().toLowerCase()), buildAnchor(node, selector));
+}
+
+export function trackHTMLEdit(tracker: Tracker, node: SDK.DOMModel.DOMNode, selector: string|undefined,
+                              oldValue: string, newValue: string): void {
+  if (!tracker?.isTracking) {
+    return;
+  }
+  tracker.trackChange(describeHTMLEdit(oldValue, newValue), buildAnchor(node, selector));
+}
+
+export function trackVisibilityToggle(tracker: Tracker, node: SDK.DOMModel.DOMNode, selector: string|undefined,
+                                      hidden: boolean): void {
+  if (!tracker?.isTracking) {
+    return;
+  }
+  tracker.trackChange(describeVisibilityToggle(node.nodeName().toLowerCase(), hidden), buildAnchor(node, selector));
+}
+
+export function trackNodeDuplication(tracker: Tracker, node: SDK.DOMModel.DOMNode, selector: string|undefined): void {
+  if (!tracker?.isTracking) {
+    return;
+  }
+  tracker.trackChange(describeNodeDuplication(node.nodeName().toLowerCase()), buildAnchor(node, selector));
+}
+
+export function trackNodeMove(tracker: Tracker, node: SDK.DOMModel.DOMNode, selector: string|undefined,
+                              directionUp: boolean): void {
+  if (!tracker?.isTracking) {
+    return;
+  }
+  tracker.trackChange(describeNodeMove(node.nodeName().toLowerCase(), directionUp), buildAnchor(node, selector));
+}
+
+export function trackNodeDrop(tracker: Tracker, node: SDK.DOMModel.DOMNode, selector: string|undefined): void {
+  if (!tracker?.isTracking) {
+    return;
+  }
+  tracker.trackChange(describeNodeDrop(node.nodeName().toLowerCase()), buildAnchor(node, selector));
+}
+
+export function trackNodePaste(tracker: Tracker, node: SDK.DOMModel.DOMNode, selector: string|undefined,
+                               isCut: boolean): void {
+  if (!tracker?.isTracking) {
+    return;
+  }
+  tracker.trackChange(describeNodePaste(node.nodeName().toLowerCase(), isCut), buildAnchor(node, selector));
+}

package/front_end/models/elements/elements.ts

@@ -2,8 +2,10 @@
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
+import * as DOMChanges from './DOMChanges.js';
 import * as ElementUpdateRecord from './ElementUpdateRecord.js';
 
 export {
+  DOMChanges,
   ElementUpdateRecord,
 };