chrome-devtools-frontend 1.0.1652307 → 1.0.1656291

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

@@ -0,0 +1,142 @@
+// 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 Host from '../../../core/host/host.js';
+import * as i18n from '../../../core/i18n/i18n.js';
+import * as SDK from '../../../core/sdk/sdk.js';
+import type * as Protocol from '../../../generated/protocol.js';
+import type {FunctionCallHandlerResult} from '../agents/AiAgent.js';
+import {DOMNodeContext} from '../contexts/DOMNodeContext.js';
+
+import {
+  type BaseToolCapability,
+  type OriginLockCapability,
+  type TargetCapability,
+  type Tool,
+  type ToolArgs,
+  ToolName,
+} from './Tool.js';
+
+/**
+ * Arguments for getting accessibility details of an element.
+ */
+export interface GetElementAccessibilityDetailsArgs extends ToolArgs {
+  /**
+   * The backend node ID of the element to inspect.
+   */
+  element: number;
+  explanation: string;
+}
+
+/**
+ * A tool that retrieves fine-grained accessibility properties (role, name, ARIA properties, focus state)
+ * for a resolved element backend node ID. It also returns a DOM snapshot of the element's subtree.
+ */
+export class GetElementAccessibilityDetailsTool implements
+    Tool<GetElementAccessibilityDetailsArgs, string, BaseToolCapability&TargetCapability&OriginLockCapability> {
+  readonly name = ToolName.GET_ELEMENT_ACCESSIBILITY_DETAILS;
+  readonly description =
+      'Get detailed accessibility information for an element on the inspected page by its backend node ID.';
+
+  readonly parameters: Host.AidaClient.FunctionObjectParam<keyof GetElementAccessibilityDetailsArgs> = {
+    type: Host.AidaClient.ParametersTypes.OBJECT,
+    description: 'Arguments for getting element accessibility details.',
+    nullable: false,
+    properties: {
+      explanation: {
+        type: Host.AidaClient.ParametersTypes.STRING,
+        description: 'Reason for requesting accessibility details.',
+        nullable: false,
+      },
+      element: {
+        type: Host.AidaClient.ParametersTypes.INTEGER,
+        description: 'The backend node ID of the element.',
+        nullable: false,
+      },
+    },
+    required: ['explanation', 'element'],
+  };
+
+  displayInfoFromArgs(params: GetElementAccessibilityDetailsArgs): {
+    title: string,
+    thought: string,
+    action: string,
+  } {
+    return {
+      title: 'Reading accessibility details',
+      thought: params.explanation,
+      action: `getElementAccessibilityDetails(${params.element})`,
+    };
+  }
+
+  /**
+   * Handles the request to retrieve accessibility details.
+   *
+   * Resolves the element backend node ID, validates its origin against the locked origin,
+   * requests the AX subtree via AccessibilityModel, and maps the relevant attributes.
+   */
+  async handler(
+      params: GetElementAccessibilityDetailsArgs,
+      context: BaseToolCapability&TargetCapability&OriginLockCapability,
+      ): Promise<FunctionCallHandlerResult<string>> {
+    const establishedOrigin = context.getEstablishedOrigin();
+    if (!establishedOrigin) {
+      return {error: 'Error: Origin lock is not established.'};
+    }
+
+    const target = context.getTarget();
+    if (!target) {
+      return {error: 'Error: Inspected target not found.'};
+    }
+
+    // Resolve the backend node ID to an SDK DOMNode. We use DeferredDOMNode
+    // because the backend node ID is the stable identifier received from external
+    // sources (like Lighthouse audits), and we need to fetch the local node object to query it.
+    const deferredNode = new SDK.DOMModel.DeferredDOMNode(target, params.element as Protocol.DOM.BackendNodeId);
+    const resolved = await deferredNode.resolvePromise();
+    if (!resolved) {
+      return {error: 'Error: Could not resolve element by ID.'};
+    }
+
+    const nodeContext = new DOMNodeContext(resolved);
+    // Security check: Ensure the element matches the active conversation's origin lock.
+    if (!nodeContext.isOriginAllowed(establishedOrigin)) {
+      return {error: 'Error: Node does not belong to the locked origin.'};
+    }
+
+    const axModel = target.model(SDK.AccessibilityModel.AccessibilityModel);
+    if (!axModel) {
+      return {error: 'Error: Accessibility model not found.'};
+    }
+
+    // Accessibility data is not loaded by default for all nodes to optimize performance.
+    // We must explicitly request and load the accessibility subtree for the resolved node before querying.
+    await axModel.requestAndLoadSubTreeToNode(resolved);
+    const axNode = axModel.axNodeForDOMNode(resolved);
+    if (!axNode) {
+      return {error: 'Error: AX node details not found.'};
+    }
+
+    const properties = {
+      role: axNode.role()?.value,
+      name: axNode.name()?.value,
+      properties: axNode.properties()?.map(p => ({name: p.name, value: p.value?.value})) ?? [],
+    };
+
+    // Take a snapshot of the resolved node's DOM structure. This is required
+    // by the DOM_TREE UI widget to render the element's local tree in the AI response panel.
+    const snapshot = await resolved.takeSnapshot();
+    return {
+      result: JSON.stringify(properties, null, 2),
+      widgets: [{
+        name: 'DOM_TREE',
+        data: {
+          root: snapshot,
+          title: i18n.i18n.lockedString('Element details'),
+          accessibleRevealLabel: i18n.i18n.lockedString('Reveal element'),
+        },
+      }],
+    };
+  }
+}

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

@@ -105,7 +105,7 @@ export class GetStylesTool implements
         return {error: 'Error: Could not find the element with uid=' + uid};
       }
       const newContext = new DOMNodeContext(resolved);
-      if (establishedOrigin !== newContext.getOrigin()) {
+      if (!newContext.isOriginAllowed(establishedOrigin)) {
         return {error: 'Error: Node does not belong to the current origin.'};
       }
       const styles = await resolved.domModel().cssModel().getComputedStyle(resolved.id);

package/front_end/models/ai_assistance/tools/README.md

@@ -17,12 +17,30 @@ Instead of passing a monolithic "grab-bag" context object to all tool handlers,
 - `PageExecutionCapability`: For tools executing JavaScript code on the inspected page.
 - `StyleMutationCapability`: For tools managing and applying style mutations via a `ChangeManager`.
 - `TargetCapability`: For tools requiring access to the page's current SDK `Target`.
-- `OriginLockCapability`: For tools enforcing cross-origin security via origin locks. Tools that fetch resources or state from the inspected page (such as styling or source code) must use this capability to verify that the target resource matches the conversation's established origin. This prevents the LLM from executing tools against out-of-origin elements or documents.
+- `OriginLockCapability`: For tools enforcing cross-origin security via origin locks. Tools that fetch resources or state from the inspected page (such as styling or source code) must use this capability to verify that the target resource matches the conversation's established origin. This prevents the LLM from executing tools against out-of-origin elements or documents. Verification should be done by wrapping resolved resources in helper context classes (e.g., `DOMNodeContext`) and calling `isOriginAllowed(establishedOrigin)`.
 
 ### Unified Context
 
 The Agent (e.g., `AiAgent2`) builds the complete dependency union (`AllToolsCapabilities`) and fulfills all capabilities. When the handler is invoked, TypeScript validates that the provided context matches the intersection of capabilities requested by that tool.
 
+## Returning UI Widgets
+
+Tools can return rich UI components (widgets) to be rendered directly in the AI Assistance panel alongside text results. To do this, include the widget payload in the `widgets` field of the returned `FunctionCallHandlerResult`:
+
+```typescript
+return {
+  result: JSON.stringify(properties, null, 2),
+  widgets: [{
+    name: 'DOM_TREE',
+    data: {
+      root: snapshot,
+      title: i18n.i18n.lockedString('Element details'),
+      accessibleRevealLabel: i18n.i18n.lockedString('Reveal element'),
+    },
+  }],
+};
+```
+
 ## Authoring a New Tool
 
 To author a new tool:
@@ -35,6 +53,8 @@ To author a new tool:
 See concrete, production examples of capability-based tools in this directory:
 - [ExecuteJavaScript.ts](ExecuteJavaScript.ts): Demonstrates use of `PageExecutionCapability` and `StyleMutationCapability`.
 - [GetStyles.ts](GetStyles.ts): Demonstrates use of `TargetCapability` and `OriginLockCapability`.
+- [GetElementAccessibilityDetails.ts](GetElementAccessibilityDetails.ts): Demonstrates returning UI widgets (`DOM_TREE`) and origin checks with context wrappers.
+- [ResolveDevtoolsNodePath.ts](ResolveDevtoolsNodePath.ts): Demonstrates path resolution input validation and origin lock checks.
 
 ## ToolRegistry Lookup
 

package/front_end/models/ai_assistance/tools/{ResolveLighthousePath.ts → ResolveDevtoolsNodePath.ts}

@@ -17,11 +17,11 @@ import {
 } from './Tool.js';
 
 /**
- * Arguments for resolving a Lighthouse path to a backend node ID.
+ * Arguments for resolving a DevTools node path to a backend node ID.
  */
-export interface ResolveLighthousePathArgs extends ToolArgs {
+export interface ResolveDevtoolsNodePathArgs extends ToolArgs {
   /**
-   * A Lighthouse-style element path.
+   * A DevTools node path.
    * This is typically a comma-separated list of child indices and tag names
    * representing the path from the root to the target element (e.g., "1,HTML,1,BODY").
    */
@@ -30,19 +30,20 @@ export interface ResolveLighthousePathArgs extends ToolArgs {
 }
 
 /**
- * A tool that resolves a Lighthouse-style element path to a backend node ID.
+ * A tool that resolves a DevTools node path to a backend node ID.
  *
  * This is used by the AI assistant to identify specific DOM nodes referred to in
- * Lighthouse reports. It ensures the resolved node belongs to the locked origin.
+ * Lighthouse reports or other sources using node paths. It ensures the resolved node
+ * belongs to the locked origin.
  */
-export class ResolveLighthousePathTool implements
-    Tool<ResolveLighthousePathArgs, {backendNodeId: number}, BaseToolCapability&TargetCapability&OriginLockCapability> {
-  readonly name = ToolName.RESOLVE_LIGHTHOUSE_PATH;
-  readonly description = 'Resolves a Lighthouse path to a backend node ID.';
+export class ResolveDevtoolsNodePathTool implements Tool<ResolveDevtoolsNodePathArgs, {backendNodeId: number},
+                                                         BaseToolCapability&TargetCapability&OriginLockCapability> {
+  readonly name = ToolName.RESOLVE_DEVTOOLS_NODE_PATH;
+  readonly description = 'Resolves a DevTools node path to a backend node ID.';
 
-  readonly parameters: Host.AidaClient.FunctionObjectParam<keyof ResolveLighthousePathArgs> = {
+  readonly parameters: Host.AidaClient.FunctionObjectParam<keyof ResolveDevtoolsNodePathArgs> = {
     type: Host.AidaClient.ParametersTypes.OBJECT,
-    description: 'Arguments for resolving a Lighthouse path to a backend node ID.',
+    description: 'Arguments for resolving a DevTools node path to a backend node ID.',
     nullable: false,
     properties: {
       explanation: {
@@ -52,14 +53,14 @@ export class ResolveLighthousePathTool implements
       },
       path: {
         type: Host.AidaClient.ParametersTypes.STRING,
-        description: 'Lighthouse path string.',
+        description: 'DevTools node path string.',
         nullable: false,
       },
     },
     required: ['explanation', 'path'],
   };
 
-  displayInfoFromArgs(params: ResolveLighthousePathArgs): {
+  displayInfoFromArgs(params: ResolveDevtoolsNodePathArgs): {
     title: string,
     thought: string,
     action: string,
@@ -67,7 +68,7 @@ export class ResolveLighthousePathTool implements
     return {
       title: 'Resolving element path',
       thought: params.explanation,
-      action: `resolveLighthousePath('${params.path}')`,
+      action: `resolveDevtoolsNodePath('${params.path}')`,
     };
   }
 
@@ -79,7 +80,7 @@ export class ResolveLighthousePathTool implements
    * access to nodes from other origins.
    */
   async handler(
-      params: ResolveLighthousePathArgs,
+      params: ResolveDevtoolsNodePathArgs,
       context: BaseToolCapability&TargetCapability&OriginLockCapability,
       ): Promise<FunctionCallHandlerResult<{backendNodeId: number}>> {
     const establishedOrigin = context.getEstablishedOrigin();
@@ -95,11 +96,11 @@ export class ResolveLighthousePathTool implements
 
     let nodeId;
     try {
-      // Resolves the Lighthouse path (a representation of the path to a node)
+      // Resolves the DevTools node path (a representation of the path to a node)
       // and ensures the node is loaded into the frontend DOM model, returning its ID.
       nodeId = await domModel.pushNodeByPathToFrontend(params.path);
     } catch {
-      return {error: 'Error: Could not find node by path.'};
+      // pushNodeByPathToFrontend can fail or return undefined
     }
     if (!nodeId) {
       return {error: 'Error: Could not find node by path.'};

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

@@ -98,7 +98,8 @@ export const enum ToolName {
   LIST_NETWORK_REQUESTS = 'listNetworkRequests',
   GET_NETWORK_REQUEST_DETAILS = 'getNetworkRequestDetails',
   GET_LIGHTHOUSE_AUDITS = 'getLighthouseAudits',
-  RESOLVE_LIGHTHOUSE_PATH = 'resolveLighthousePath',
+  RESOLVE_DEVTOOLS_NODE_PATH = 'resolveDevtoolsNodePath',
+  GET_ELEMENT_ACCESSIBILITY_DETAILS = 'getElementAccessibilityDetails',
 }
 
 /**
@@ -125,6 +126,10 @@ export interface BaseTool {
 export interface Tool<Args extends ToolArgs = ToolArgs, ReturnType = unknown,
                                    ContextType extends BaseToolCapability = BaseToolCapability> extends BaseTool {
   readonly parameters: Host.AidaClient.FunctionObjectParam<keyof Args>;
+  /**
+   * Converts the tool arguments into user-friendly display information.
+   * This is used by the UI to show what the agent is doing (e.g., in the history/steps log).
+   */
   readonly displayInfoFromArgs?: (
       args: Args,
       ) => {

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

@@ -3,11 +3,12 @@
 // found in the LICENSE file.
 
 import {ExecuteJavaScriptTool} from './ExecuteJavaScript.js';
+import {GetElementAccessibilityDetailsTool} from './GetElementAccessibilityDetails.js';
 import {GetLighthouseAuditsTool} from './GetLighthouseAudits.js';
 import {GetNetworkRequestDetailsTool} from './GetNetworkRequestDetails.js';
 import {GetStylesTool} from './GetStyles.js';
 import {ListNetworkRequestsTool} from './ListNetworkRequests.js';
-import {ResolveLighthousePathTool} from './ResolveLighthousePath.js';
+import {ResolveDevtoolsNodePathTool} from './ResolveDevtoolsNodePath.js';
 import {type AllToolsCapabilities, type Tool, type ToolArgs, ToolName} from './Tool.js';
 
 /**
@@ -24,7 +25,8 @@ export const TOOLS = {
   [ToolName.LIST_NETWORK_REQUESTS]: new ListNetworkRequestsTool(),
   [ToolName.GET_NETWORK_REQUEST_DETAILS]: new GetNetworkRequestDetailsTool(),
   [ToolName.GET_LIGHTHOUSE_AUDITS]: new GetLighthouseAuditsTool(),
-  [ToolName.RESOLVE_LIGHTHOUSE_PATH]: new ResolveLighthousePathTool(),
+  [ToolName.RESOLVE_DEVTOOLS_NODE_PATH]: new ResolveDevtoolsNodePathTool(),
+  [ToolName.GET_ELEMENT_ACCESSIBILITY_DETAILS]: new GetElementAccessibilityDetailsTool(),
 };
 
 /**

package/front_end/models/autofill_manager/AutofillManager.ts

@@ -7,27 +7,18 @@ import * as Platform from '../../core/platform/platform.js';
 import * as SDK from '../../core/sdk/sdk.js';
 import type * as Protocol from '../../generated/protocol.js';
 
-let autofillManagerInstance: AutofillManager;
-
 export class AutofillManager extends Common.ObjectWrapper.ObjectWrapper<EventTypes> {
   #address = '';
   #filledFields: Protocol.Autofill.FilledField[] = [];
   #matches: Match[] = [];
   #autofillModel: SDK.AutofillModel.AutofillModel|null = null;
+  #frameManager: SDK.FrameManager.FrameManager;
 
-  private constructor() {
+  constructor(targetManager: SDK.TargetManager.TargetManager, frameManager: SDK.FrameManager.FrameManager) {
     super();
-    SDK.TargetManager.TargetManager.instance().addModelListener(
-        SDK.AutofillModel.AutofillModel, SDK.AutofillModel.Events.ADDRESS_FORM_FILLED, this.#addressFormFilled, this,
-        {scoped: true});
-  }
-
-  static instance(opts: {forceNew: boolean|null} = {forceNew: null}): AutofillManager {
-    const {forceNew} = opts;
-    if (!autofillManagerInstance || forceNew) {
-      autofillManagerInstance = new AutofillManager();
-    }
-    return autofillManagerInstance;
+    this.#frameManager = frameManager;
+    targetManager.addModelListener(SDK.AutofillModel.AutofillModel, SDK.AutofillModel.Events.ADDRESS_FORM_FILLED,
+                                   this.#addressFormFilled, this, {scoped: true});
   }
 
   async #addressFormFilled({data}: Common.EventTarget.EventTargetEvent<
@@ -56,7 +47,7 @@ export class AutofillManager extends Common.ObjectWrapper.ObjectWrapper<EventTyp
 
   highlightFilledField(filledField: Protocol.Autofill.FilledField): void {
     const backendNodeId = filledField.fieldId;
-    const target = SDK.FrameManager.FrameManager.instance().getFrame(filledField.frameId)?.resourceTreeModel().target();
+    const target = this.#frameManager.getFrame(filledField.frameId)?.resourceTreeModel().target();
     if (target) {
       const deferredNode = new SDK.DOMModel.DeferredDOMNode(target, backendNodeId);
       const domModel = target.model(SDK.DOMModel.DOMModel);

package/front_end/models/bindings/NetworkProject.ts

@@ -3,6 +3,7 @@
 // found in the LICENSE file.
 
 import * as Common from '../../core/common/common.js';
+import * as Root from '../../core/root/root.js';
 import * as SDK from '../../core/sdk/sdk.js';
 import type * as Protocol from '../../generated/protocol.js';
 import type * as Workspace from '../workspace/workspace.js';
@@ -13,21 +14,16 @@ const uiSourceCodeToAttributionMap = new WeakMap<Workspace.UISourceCode.UISource
                                                  }>>();
 const projectToTargetMap = new WeakMap<Workspace.Workspace.Project, SDK.Target.Target>();
 
-let networkProjectManagerInstance: NetworkProjectManager;
-
 export class NetworkProjectManager extends Common.ObjectWrapper.ObjectWrapper<EventTypes> {
-  private constructor() {
-    super();
-  }
 
   static instance({forceNew}: {
     forceNew: boolean,
   } = {forceNew: false}): NetworkProjectManager {
-    if (!networkProjectManagerInstance || forceNew) {
-      networkProjectManagerInstance = new NetworkProjectManager();
+    if (!Root.DevToolsContext.globalInstance().has(NetworkProjectManager) || forceNew) {
+      Root.DevToolsContext.globalInstance().set(NetworkProjectManager, new NetworkProjectManager());
     }
 
-    return networkProjectManagerInstance;
+    return Root.DevToolsContext.globalInstance().get(NetworkProjectManager);
   }
 }
 

package/front_end/models/breakpoints/BreakpointManager.ts

@@ -14,7 +14,6 @@ import * as SourceMapScopes from '../source_map_scopes/source_map_scopes.js';
 import type * as TextUtils from '../text_utils/text_utils.js';
 import * as Workspace from '../workspace/workspace.js';
 
-let breakpointManagerInstance: BreakpointManager;
 const INITIAL_RESTORE_BREAKPOINT_COUNT = 100;
 
 export class BreakpointManager extends Common.ObjectWrapper.ObjectWrapper<EventTypes> implements
@@ -35,10 +34,9 @@ export class BreakpointManager extends Common.ObjectWrapper.ObjectWrapper<EventT
   readonly #breakpointByStorageId = new Map<string, Breakpoint>();
   #updateBindingsCallbacks: Array<(uiSourceCode: Workspace.UISourceCode.UISourceCode) => Promise<void>> = [];
 
-  private constructor(
-      targetManager: SDK.TargetManager.TargetManager, workspace: Workspace.Workspace.WorkspaceImpl,
-      debuggerWorkspaceBinding: Bindings.DebuggerWorkspaceBinding.DebuggerWorkspaceBinding,
-      settings: Common.Settings.Settings, restoreInitialBreakpointCount?: number) {
+  constructor(targetManager: SDK.TargetManager.TargetManager, workspace: Workspace.Workspace.WorkspaceImpl,
+              debuggerWorkspaceBinding: Bindings.DebuggerWorkspaceBinding.DebuggerWorkspaceBinding,
+              settings: Common.Settings.Settings, restoreInitialBreakpointCount?: number) {
     super();
     this.#workspace = workspace;
     this.targetManager = targetManager;
@@ -85,18 +83,20 @@ export class BreakpointManager extends Common.ObjectWrapper.ObjectWrapper<EventT
   }): BreakpointManager {
     const {forceNew, targetManager, workspace, debuggerWorkspaceBinding, settings, restoreInitialBreakpointCount} =
         opts;
-    if (!breakpointManagerInstance || forceNew) {
+    if (!Root.DevToolsContext.globalInstance().has(BreakpointManager) || forceNew) {
       if (!targetManager || !workspace || !debuggerWorkspaceBinding || !settings) {
         throw new Error(
             `Unable to create settings: targetManager, workspace, debuggerWorkspaceBinding, and settings must be provided: ${
                 new Error().stack}`);
       }
 
-      breakpointManagerInstance = new BreakpointManager(
-          targetManager, workspace, debuggerWorkspaceBinding, settings, restoreInitialBreakpointCount);
+      Root.DevToolsContext.globalInstance().set(
+          BreakpointManager,
+          new BreakpointManager(targetManager, workspace, debuggerWorkspaceBinding, settings,
+                                restoreInitialBreakpointCount));
     }
 
-    return breakpointManagerInstance;
+    return Root.DevToolsContext.globalInstance().get(BreakpointManager);
   }
 
   modelAdded(debuggerModel: SDK.DebuggerModel.DebuggerModel): void {

package/front_end/models/emulation/DeviceModeModel.ts

@@ -200,6 +200,10 @@ export class DeviceModeModel extends Common.ObjectWrapper.ObjectWrapper<EventTyp
     }
   }
 
+  static removeInstance(): void {
+    deviceModeModelInstance = null;
+  }
+
   dispose(): void {
     SDK.TargetManager.TargetManager.instance().unobserveModels(SDK.EmulationModel.EmulationModel, this);
   }
@@ -573,6 +577,25 @@ export class DeviceModeModel extends Common.ObjectWrapper.ObjectWrapper<EventTyp
     return this.#mode.insets;
   }
 
+  private currentSafeAreaInsets(): Insets|null {
+    if (this.#type !== Type.Device || !this.#mode) {
+      return null;
+    }
+    return this.#mode.safeAreaInsets ?? null;
+  }
+
+  private applySafeAreaInsets(insets: Insets|null): void {
+    if (!this.#emulationModel) {
+      return;
+    }
+    if (insets) {
+      void this.#emulationModel.setSafeAreaInsets(
+          {top: insets.top, left: insets.left, bottom: insets.bottom, right: insets.right});
+    } else {
+      void this.#emulationModel.setSafeAreaInsets({});
+    }
+  }
+
   private getScreenOrientationType(): Protocol.Emulation.ScreenOrientationType {
     if (!this.#mode) {
       throw new Error('Mode required to get orientation type.');
@@ -649,6 +672,7 @@ export class DeviceModeModel extends Common.ObjectWrapper.ObjectWrapper<EventTyp
     if (overlayModel) {
       overlayModel.setShowViewportSizeOnResize(this.#type === Type.None);
     }
+    this.applySafeAreaInsets(this.currentSafeAreaInsets());
     this.dispatchEventToListeners(Events.UPDATED);
   }
 

package/front_end/models/emulation/EmulatedDevices.ts

@@ -103,6 +103,15 @@ export class EmulatedDevice {
             parseIntValue(json, 'bottom'));
       }
 
+      function parseCutoutShape(json: any): CutoutShape {
+        const shape = parseValue(json, 'shape', 'string');
+        if (shape !== CutoutShape.PILL && shape !== CutoutShape.NOTCH && shape !== CutoutShape.CIRCLE &&
+            shape !== CutoutShape.RECTANGLE) {
+          throw new Error('Emulated device mode has unsupported cutout shape: ' + shape);
+        }
+        return shape;
+      }
+
       function parseRGBA(json: any): SDK.OverlayModel.HighlightColor {
         const result = {} as SDK.OverlayModel.HighlightColor;
         result.r = parseIntValue(json, 'r');
@@ -257,6 +266,40 @@ export class EmulatedDevice {
           throw new Error('Emulated device mode \'' + mode.title + '\'has wrong mode insets');
         }
         mode.image = (parseValue(modes[i], 'image', 'string', null) as string);
+        const safeAreaInsets = parseValue(modes[i], 'safe-area-insets', 'object', null);
+        if (safeAreaInsets) {
+          mode.safeAreaInsets = parseInsets(safeAreaInsets);
+        }
+        const cutout = parseValue(modes[i], 'cutout', 'object', null);
+        if (cutout) {
+          const shape = parseCutoutShape(cutout);
+          const baseCutout = {
+            x: parseIntValue(cutout, 'x'),
+            y: parseIntValue(cutout, 'y'),
+            width: parseIntValue(cutout, 'width'),
+            height: parseIntValue(cutout, 'height'),
+          };
+          if (shape === CutoutShape.PILL) {
+            mode.cutout = {shape, ...baseCutout, borderRadius: parseIntValue(cutout, 'border-radius')};
+          } else if (shape === CutoutShape.NOTCH) {
+            mode.cutout = {
+              shape,
+              ...baseCutout,
+              upperRadius: parseIntValue(cutout, 'upper-radius'),
+              lowerRadius: parseIntValue(cutout, 'lower-radius'),
+            };
+          } else if (shape === CutoutShape.CIRCLE) {
+            mode.cutout = {
+              shape,
+              ...baseCutout,
+              cx: parseIntValue(cutout, 'cx'),
+              cy: parseIntValue(cutout, 'cy'),
+              radius: parseIntValue(cutout, 'radius'),
+            };
+          } else {
+            mode.cutout = {shape, ...baseCutout};
+          }
+        }
         result.modes.push(mode);
       }
       result.#showByDefault = (parseValue(json, 'show-by-default', 'boolean', undefined) as boolean);
@@ -359,6 +402,35 @@ export class EmulatedDevice {
         },
         image: this.modes[i].image || undefined,
       };
+      const safeAreaInsets = this.modes[i].safeAreaInsets;
+      if (safeAreaInsets) {
+        mode['safe-area-insets'] = {
+          left: safeAreaInsets.left,
+          top: safeAreaInsets.top,
+          right: safeAreaInsets.right,
+          bottom: safeAreaInsets.bottom,
+        };
+      }
+      const cutout = this.modes[i].cutout;
+      if (cutout) {
+        mode.cutout = {
+          shape: cutout.shape,
+          x: cutout.x,
+          y: cutout.y,
+          width: cutout.width,
+          height: cutout.height,
+        };
+        if (cutout.shape === CutoutShape.PILL) {
+          mode.cutout['border-radius'] = cutout.borderRadius;
+        } else if (cutout.shape === CutoutShape.NOTCH) {
+          mode.cutout['upper-radius'] = cutout.upperRadius;
+          mode.cutout['lower-radius'] = cutout.lowerRadius;
+        } else if (cutout.shape === CutoutShape.CIRCLE) {
+          mode.cutout.cx = cutout.cx;
+          mode.cutout.cy = cutout.cy;
+          mode.cutout.radius = cutout.radius;
+        }
+      }
       json['modes'].push(mode);
     }
 
@@ -637,7 +709,24 @@ export interface Mode {
   orientation: string;
   insets: Insets;
   image: string|null;
+  safeAreaInsets?: Insets;
+  cutout?: Cutout;
 }
+export const enum CutoutShape {
+  PILL = 'pill',
+  NOTCH = 'notch',
+  CIRCLE = 'circle',
+  RECTANGLE = 'rectangle',
+}
+export interface BaseCutout {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+export type Cutout = BaseCutout&({shape: CutoutShape.RECTANGLE}|{shape: CutoutShape.PILL, borderRadius: number}|
+                                 {shape: CutoutShape.NOTCH, upperRadius: number, lowerRadius: number}|
+                                 {shape: CutoutShape.CIRCLE, cx: number, cy: number, radius: number});
 export interface Orientation {
   width: number;
   height: number;
@@ -655,6 +744,25 @@ export interface JSONMode {
     top: number,
     bottom: number,
   };
+  'safe-area-insets'?: {
+    left: number,
+    right: number,
+    top: number,
+    bottom: number,
+  };
+  cutout?: {
+    shape: string,
+    x: number,
+    y: number,
+    width: number,
+    height: number,
+    'border-radius'?: number,
+    'upper-radius'?: number,
+    'lower-radius'?: number,
+    cx?: number,
+    cy?: number,
+    radius?: number,
+  };
 }
 
 // These props should quoted for the script to work properly