chrome-devtools-frontend 1.0.1579812 → 1.0.1581708

package/agents/prompts/creating-a-model.md

@@ -0,0 +1,51 @@
+# Creating or Migrating a Model in DevTools
+
+This guide outlines the standard procedure for creating a new model or migrating an existing one to `front_end/models/`.
+
+## 0. Preparation (Before you start)
+*   **Baseline:** Run existing tests for the code you are moving to ensure they pass *before* you touch anything.
+    *   `npm run test -- front_end/<old_location>`
+*   **Impact Analysis:** Search for usages of the class/file to understand the scope of refactoring.
+    *   `grep -r "ClassName" front_end/`
+
+## 1. File Structure
+*   **Location:** `front_end/models/<model_name>/` (must be lowercase).
+*   **Entrypoint:** Create a barrel file `front_end/models/<model_name>/<model_name>.ts` that exports the model's public API.
+*   **Implementation:** The actual logic goes in `<ClassName>.ts`.
+*   **Tests:** Unit tests go in `<ClassName>.test.ts` alongside the implementation.
+
+## 2. Build Configuration (`BUILD.gn`)
+Every model requires a `BUILD.gn` file in its directory with three specific targets:
+
+1.  **`devtools_module("<model_name>")`**: Lists implementation source files (`sources`) and dependencies (`deps`).
+    *   **Crucial:** Do NOT include the barrel file (`<model_name>.ts`) in `sources`.
+2.  **`devtools_entrypoint("bundle")`**: Defines the barrel file (`entrypoint = "<model_name>.ts"`).
+    *   **Crucial:** Must depend on the module target: `deps = [ ":<model_name>" ]`.
+3.  **`ts_library("unittests")`**: Lists test files and test-only dependencies.
+    *   **Crucial:** Must depend on the bundle: `deps = [ ":bundle" ]`.
+
+## 3. Global Registration (Crucial)
+The build system does not auto-detect new modules. You must manually register them in **`config/gni/devtools_grd_files.gni`**:
+
+*   **Bundled (Release) Build:** Add the new barrel file path (e.g., `front_end/models/<model_name>/<model_name>.js`) to the `grd_files_bundled_sources` list.
+*   **Unbundled (Debug) Build:** Add all other implementation files (e.g., `front_end/models/<model_name>/<ClassName>.js`) to the `grd_files_unbundled_sources` list.
+*   **Test Runner:** Add the new model's unittest target (e.g., `models/<model_name>:unittests`) to the `deps` list in **`front_end/BUILD.gn`**.
+
+## 4. Refactoring Imports & Exports
+*   **Consumers:** Update all files importing the model to use the new entrypoint:
+    `import * as ModelName from '../../models/<model_name>/<model_name>.js';`
+*   **Old Barrel File (Migration only):** If moving a file, **remove** its export from the original directory's barrel file (e.g., `front_end/panels/elements/elements.ts`).
+*   **Internal Imports:** Files *within* the model directory must import each other via relative paths (e.g., `./OtherClass.js`), **never** via the model's own barrel file.
+
+## 5. Verification Checklist
+1.  **Build:** `autoninja -C out/Default` (Ensures BUILD.gn and GRD files are correct).
+2.  **Lint:** `npm run lint` (Checks style and formatting).
+3.  **Test:**
+    *   `npm run test -- front_end/models/<model_name>` (New tests).
+    *   `npm run test -- front_end/<old_location>` (Regression check for previous owner).
+
+## Common Pitfalls
+*   **Circular Dependencies:** Occur when internal files import from the directory's own barrel file.
+*   **Missing Tests:** Failing to add the target to `front_end/BUILD.gn` means tests exist but never run.
+*   **Legacy Exports:** Forgetting to remove the class from the old location's `files` or `exports` allows old patterns to persist.
+*   **Build Errors:** Including the barrel file in `devtools_module` sources causes duplicate definition errors.

package/agents/prompts/merging-devtools-module.md

@@ -0,0 +1,144 @@
+# Workflow: Merging a DevTools Submodule into its Parent
+
+This document outlines the process for merging a submodule (e.g., `panels/timeline/extensions`) into its parent module (e.g., `panels/timeline`) within the DevTools build system. The goal is to simplify the build configuration by consolidating `BUILD.gn` files while keeping the original source file directory structure.
+
+## Prerequisites
+
+You will need the following information:
+-   **Parent Module Path:** The path to the directory containing the primary module.
+-   **Child Module Path:** The path to the directory of the submodule to be merged.
+
+## Workflow Steps
+
+### 1. Analyze Build Configurations
+
+Read the contents of the `BUILD.gn` file from both the child module and the parent module. Identify the following from the child's `BUILD.gn`:
+-   The list of `sources` in the `devtools_module`.
+-   The list of `deps` (dependencies) in the `devtools_module`.
+-   The `entrypoint` for the `devtools_entrypoint("bundle")`.
+
+### 2. Modify the Parent `BUILD.gn`
+
+Edit the `BUILD.gn` file in the parent module's directory to incorporate the child module's configuration.
+
+1.  **Add Child's Sources:** Append the list of `sources` from the child's `devtools_module` to the parent's `sources` list. Remember to maintain the relative path from the parent's directory (e.g., `extensions/ExtensionUI.ts`).
+2.  **Merge Dependencies:** Add the `deps` from the child's `devtools_module` to the parent's `deps` list. Remove any duplicate entries.
+3.  **Remove Child Bundle Dependency:** Delete the dependency on the child's bundle from the parent's `deps` list (e.g., remove `./extensions:bundle`).
+
+### 3. Delete the Child `BUILD.gn`
+
+Once the parent `BUILD.gn` is updated and contains all the necessary information, the child's `BUILD.gn` is no longer needed. Delete it.
+
+```bash
+rm <child_module_path>/BUILD.gn
+```
+
+### 4. Update `devtools_grd_files.gni`
+
+The global `.gni` file that lists all resources needs to be updated to reflect that the child module is no longer a separate, bundled entrypoint.
+
+1.  **Locate and Read the File:** Open `config/gni/devtools_grd_files.gni`.
+2.  **Remove Bundled Source:** Find and remove the line for the child's bundled JavaScript file from the `grd_files_bundled_sources` list. This path usually corresponds to the child's `entrypoint`.
+3.  **Add Unbundled Sources:** Add the paths to all of the child's original TypeScript source files (`.ts`) to the `grd_files_unbundled_sources` list.
+
+---
+
+## Example: Merging `panels/timeline/extensions` into `panels/timeline`
+
+-   **Parent Module:** `panels/timeline`
+-   **Child Module:** `panels/timeline/extensions`
+
+### 1. `panels/timeline/BUILD.gn` Modification
+
+**Before:**
+```gni
+devtools_module("timeline") {
+  sources = [
+    ...
+    "UIDevtoolsUtils.ts",
+  ]
+
+  deps = [
+    ...
+    "./components:bundle",
+    "./extensions:bundle",
+    "./overlays:bundle",
+    ...
+  ]
+}
+```
+
+**After:**
+```gni
+devtools_module("timeline") {
+  sources = [
+    ...
+    "UIDevtoolsUtils.ts",
+    "extensions/ExtensionUI.ts", # Added from child
+  ]
+
+  deps = [
+    ...
+    "./components:bundle",
+    # "./extensions:bundle", # Removed
+    "./overlays:bundle",
+    ...
+    # Dependencies from extensions/BUILD.gn are merged here
+    "../../../ui/components/helpers:bundle",
+    "../../../ui/components/render_coordinator:bundle",
+    "../../../ui/legacy:bundle",
+  ]
+}
+```
+
+### 2. `panels/timeline/extensions/BUILD.gn` Deletion
+
+```bash
+rm front_end/panels/timeline/extensions/BUILD.gn
+```
+
+### 3. `config/gni/devtools_grd_files.gni` Modification
+
+**Before:**
+```gni
+grd_files_bundled_sources = [
+  ...
+  "front_end/panels/timeline/components/components.js",
+  "front_end/panels/timeline/extensions/extensions.js",
+  "front_end/panels/timeline/overlays/overlays.js",
+  ...
+]
+
+grd_files_unbundled_sources = [
+  ...
+  "front_end/panels/timeline/extensions/ExtensionUI.ts", # This might not have been present before
+  ...
+]
+```
+
+**After:**
+```gni
+grd_files_bundled_sources = [
+  ...
+  "front_end/panels/timeline/components/components.js",
+  # "front_end/panels/timeline/extensions/extensions.js", # Removed
+  "front_end/panels/timeline/overlays/overlays.js",
+  ...
+]
+
+grd_files_unbundled_sources = [
+  ...
+  "front_end/panels/timeline/extensions/extensions.ts", # Added
+  "front_end/panels/timeline/extensions/ExtensionUI.ts",   # Added
+  ...
+]
+```
+
+## Removing Barrel Files
+
+After merging modules, you may still have remaining barrel files (e.g. `index.ts` or `extensions.ts` that just re-export other files). These should be removed to simplify the module structure.
+
+Manually updating all imports that rely on these barrels can be tedious and error-prone. The tool [unbarrelify](https://github.com/webpro/unbarrelify) can automate this process. It analyzes your codebase and replaces imports from barrel files with direct imports from the source files.
+
+**Usage:**
+Follow the instructions in the [unbarrelify repository](https://github.com/webpro/unbarrelify) to install and run the tool on your project. This is highly recommended to complete the refactoring process efficiently.

package/agents/prompts/ui-widgets.md

@@ -0,0 +1,351 @@
+## UI Widget Framework Guide (MVP Architecture)
+
+Adhere strictly to the Model-View-Presenter (MVP) architecture.
+
+* **Models** (`front_end/models/`): Handle business logic and application state. MUST NOT have knowledge of the UI.
+* **Presenters (`Widget`)**: Orchestrate data flow, manage UI-specific state, and handle interactions.
+* **Views (`function`)**: Purely presentational. Stateless functions that receive data/callbacks and render using `lit-html`.
+
+**Refactoring Note:** When refactoring legacy widgets to this framework, the widget's class name MUST NOT be changed. If you're refactoring a UI piece that uses shadow root (e.g. custom HTMLElements) to a Widget, make sure to update its styles to wrap the rules with a `@scope to (devtools-widget > *)` rule.
+
+### Presenter (`Widget`) Rules
+
+* Location: Co-located in the same file as its View.
+* MUST extend a base `UI.Widget` class (e.g., `UI.Widget.Widget`). Note that `UI.Widget.Widget` is not an `HTMLElement` and must be appended via `.show()` or `<devtools-widget>`.
+* Constructor MUST assign the injected view function to a private `#view` field.
+* Constructor MUST call `super()`. If taking `element?: HTMLElement`, pass it to `super(element)`. `super(true)` is forbidden.
+* Styling MUST be handled within the View. `this.registerCSSFiles()` is forbidden.
+* Initial render MUST be triggered in `override wasShown(): void` by calling `this.requestUpdate()`.
+* MUST hold all UI state as private class fields (e.g., `#counter`).
+* To schedule a UI update, MUST call `this.requestUpdate()`. `performUpdate()` MUST NOT be called directly.
+
+### View (`function`) Rules
+
+* MUST be a pure function, typically named `DEFAULT_VIEW`, in the same file as the Presenter.
+* MUST use the signature: `(input: ViewInput, output: ViewOutput, target: HTMLElement)`.
+  * `input`: Data and event handlers from the Presenter.
+  * `output`: Callbacks for imperative actions (e.g., focus) provided to the Presenter. If unused, the `output` parameter should be typed as `undefined` in the view's signature, and `undefined` should be passed from the presenter.
+  * `target`: The HTML element to render into.
+* The `input` parameter MUST NOT be destructured. Always use `input.propertyName`.
+* Responsibility: Render a `lit-html` template into `target`.
+* MUST NOT hold state, fetch data, or perform business logic.
+
+#### Helper Functions in Views
+
+Complex views can be broken down using helper functions defined inside `DEFAULT_VIEW` to access `input` and `output`.
+
+```ts
+// clang-format off
+const DEFAULT_VIEW = (input: ViewInput, output: ViewOutput, target: HTMLElement): void => {
+  const renderHeader = (): Lit.LitTemplate => {
+    return html`<h1>${input.title}</h1>`;
+  };
+  // ...
+  render(html`
+    <div class="child-widget">
+      ${renderHeader()}
+    </div>
+  `, target);
+};
+// clang-format on
+```
+
+### Composition (`<devtools-widget>`)
+
+* To render a child widget, the parent's View MUST use `<devtools-widget>`.
+* Configuration is passed via the `.widgetConfig` property using `UI.Widget.widgetConfig()`.
+* Properties passed from a parent MUST be declared as public fields on the child presenter class.
+* The framework automatically updates these properties and calls `requestUpdate()` on the child when the parent re-renders.
+
+## Refactoring Legacy Components
+
+When migrating imperative components (extending `UI.VBox`, `UI.Panel`, or `HTMLElement`) to the MVP architecture:
+
+1.  **Analyze Rendering Logic:** Identify where DOM is created (constructor, `wasShown`, imperative methods). This logic moves to the `DEFAULT_VIEW`.
+2.  **Convert Base Class:**
+    *   Prefer extending `UI.Widget.Widget`.
+    *   **Special Case:** If the component *must* extend `UI.Panel.Panel` or `UI.Dialog.Dialog` (to retain specific functionality), you cannot use `requestUpdate()`. Instead, call `this.performUpdate()` directly on state changes.
+3.  **State Migration:** Move DOM-stored state to private class fields.
+4.  **Update Usage:** Replace `new MyComponent()` instantiations with declarative `<devtools-widget .widgetConfig=...>` in parent templates.
+5.  **Scoping Styles:** Ensure your CSS file uses the `@scope` block to prevent style leaks:
+    ```css
+    @scope to (devtools-widget > *) {
+      ...
+    }
+    ```
+
+## Key Implementation Details (Gotchas)
+
+### Styling Strategy
+DevTools widgets typically render into Light DOM (the default for `UI.Widget`). To ensure styles are scoped to the component and do not leak into child widgets, wrap your CSS in an `@scope` block:
+
+```css
+/* myWidget.css */
+@scope to (devtools-widget > *) {
+  .my-class { ... }
+}
+```
+
+Then, include the styles in your `DEFAULT_VIEW`:
+
+```ts
+import myWidgetStyles from './myWidget.css.js';
+// ...
+render(html`
+  <style>${myWidgetStyles}</style>
+  <div class="my-widget">...</div>
+`, target);
+```
+
+**Note:** The `{host: input}` option in `render()` is generally **not required** unless you are using specific Shadow DOM patterns that necessitate it. The `@scope` strategy is the preferred method for style isolation in DevTools widgets.
+
+### Legacy Interop & Refs
+*   **Raw Elements:** Use `Lit.Directives.ref` to obtain a reference to a raw `HTMLElement` if needed for imperative APIs (e.g., `splitWidget.installResizer(element)`).
+*   **Child Widgets:** Use `UI.Widget.widgetRef` to obtain the class instance of a child `<devtools-widget>` if you need to call methods on it directly (though declarative data flow is preferred).
+
+### Dependencies
+The `DEFAULT_VIEW` is typically a module-level function. Ensure all dependencies (enums, constants, other components) are imported at the top of the file so they are available in the function scope.
+
+## Step-by-Step Implementation Example
+
+### 1\. Create the Widget File and Styles
+
+Example: `front_end/panels/my_example/MyExampleWidget.ts`.
+
+```css
+/* front_end/panels/my_example/myExampleWidget.css */
+@scope to (devtools-widget > *) {
+  p {
+    color: blue;
+  }
+}
+```
+
+```ts
+// front_end/panels/my_example/MyExampleWidget.ts
+
+import * as Lit from '../../ui/lit/lit.js';
+import * as UI from '../../ui/legacy/legacy.js';
+
+import myExampleWidgetStyles from './myExampleWidget.css.js';
+
+const {html, render, ref} = Lit;
+
+// 1. Define Input data shape. (Assuming Child Widget configuration for completeness)
+export interface ViewInput {
+  title: string;
+  counter: number;
+  onButtonClick: () => void;
+}
+
+// 2. Define Output imperative API shape.
+export interface ViewOutput {
+  focusButton?: () => void;
+}
+
+// 3. Define the View function.
+// clang-format off
+const DEFAULT_VIEW = (input: ViewInput, output: ViewOutput, target: HTMLElement): void => {
+  render(html`
+    <style>${myExampleWidgetStyles}</style>
+    <div class="child-widget">
+      <h3>${input.title}</h3>
+      <p>Counter: ${input.counter}</p>
+      <button @click=${input.onButtonClick} ${ref(el => {
+        if (el) {
+          output.focusButton = () => el.focus();
+        }
+      })}>Increment</button>
+    </div>
+  `, target);
+};
+// clang-format on
+
+// 4. Type alias for the view.
+type View = typeof DEFAULT_VIEW;
+
+// 5. Define the Presenter.
+export class MyExampleWidget extends UI.Widget.Widget {
+  #counter: number = 0;
+
+  // Public field REQUIRED to receive data from a parent.
+  title: string = 'Default Title';
+
+  #view: View;
+  #viewOutput: ViewOutput = {};
+
+  constructor(element?: HTMLElement, view: View = DEFAULT_VIEW) {
+    super(element);
+    this.#view = view;
+  }
+
+  override wasShown(): void {
+    super.wasShown();
+    // Initial render trigger.
+    this.requestUpdate();
+  }
+
+  focus(): void {
+    this.#viewOutput.focusButton?.();
+  }
+
+  #handleButtonClick = (): void => {
+    this.#counter++;
+    this.requestUpdate();
+  }
+
+  override performUpdate(): void {
+    const viewInput = {
+      title: this.title,
+      counter: this.#counter,
+      onButtonClick: this.#handleButtonClick,
+    };
+    this.#view(viewInput, this.#viewOutput, this.contentElement);
+  }
+}
+```
+
+### 2\. Compose Widgets (Parent Widget)
+
+Example: `front_end/panels/parent/ParentWidget.ts`. Demonstrates passing state via `widgetConfig` and a view with no `output`.
+
+```ts
+// front_end/panels/parent/ParentWidget.ts
+
+import * as Lit from '../../ui/lit/lit.js';
+import * as UI from '../../ui/legacy/legacy.js';
+import {MyExampleWidget} from '../my_example/MyExampleWidget.ts';
+
+import parentWidgetStyles from './parentWidgetStyles.css';
+
+const {html, render} = Lit;
+const {widgetConfig} = UI.Widget;
+
+interface ViewInput {
+  title: string;
+  onTitleChange: () => void;
+}
+
+// Parent View
+// clang-format off
+const DEFAULT_VIEW = (input: ViewInput, output: undefined, target: HTMLElement): void => {
+  render(html`
+    <style>${parentWidgetStyles}</style>
+    <div class="parent-container">
+      <h1>Parent Widget</h1>
+      <button @click=${input.onTitleChange}>Change Child Title</button>
+
+      <!-- Pass properties to the child widget. -->
+      <devtools-widget .widgetConfig=${widgetConfig(MyExampleWidget, {title: input.title})}>
+      </devtools-widget>
+    </div>
+  `, target);
+};
+// clang-format on
+
+type View = typeof DEFAULT_VIEW;
+
+// Parent Presenter
+export class ParentWidget extends UI.Widget.Widget {
+  #childTitle: string = 'Initial Title';
+  #view: View;
+
+  constructor(element?: HTMLElement, view: View = DEFAULT_VIEW) {
+    super(element);
+    this.#view = view;
+  }
+
+  override wasShown(): void {
+    super.wasShown();
+    this.requestUpdate();
+  }
+
+  #handleChangeTitleClick = () => {
+    this.#childTitle = `Title set at ${new Date().toLocaleTimeString()}`;
+    this.requestUpdate();
+  }
+
+  override performUpdate(): void {
+    this.#view({
+      title: this.#childTitle,
+      onTitleChange: this.#handleChangeTitleClick,
+    }, undefined, this.contentElement);
+  }
+}
+```
+
+### 3\. Testing Widgets
+
+Testing focuses on the Presenter's logic. The View MUST be replaced by a stub using `createViewFunctionStub`.
+
+* **`describeWithEnvironment`**: Sets up the testing environment.
+* **`createViewFunctionStub`**: Stubs the view to capture `input` data.
+* **`renderElementIntoDOM`**: Attaches the widget to the DOM to trigger lifecycle methods (like `wasShown`).
+* **`view.nextInput`**: A promise that resolves with the next `input` when the widget re-renders.
+* **Simulating Events**: Invoke callbacks directly (e.g., `view.input.onButtonClick()`), do not interact with the DOM.
+
+```ts
+// front_end/panels/my_example/MyExampleWidget.test.ts
+
+import {
+  renderElementIntoDOM,
+} from '../../testing/DOMHelpers.js';
+import {describeWithEnvironment} from '../../testing/EnvironmentHelpers.js';
+import {createViewFunctionStub} from '../../testing/ViewFunctionHelpers.js';
+import * as UI from '../../ui/legacy/legacy.js';
+
+import * as MyExampleWidget from './MyExampleWidget.js';
+
+const {MyExampleWidget} = MyExampleWidget;
+
+describeWithEnvironment('MyExampleWidget', () => {
+  // Helper to set up the widget with a stubbed view.
+  async function createWidget() {
+    // 1. Stub the view function.
+    const view = createViewFunctionStub(MyExampleWidget);
+
+    // 2. Instantiate the widget, injecting the stub.
+    const widget = new MyExampleWidget(undefined, view);
+
+    // 3. Render the widget into the DOM (triggers `wasShown`).
+    widget.markAsRoot();
+    renderElementIntoDOM(widget);
+
+    // 4. Wait for the initial render.
+    await view.nextInput;
+
+    return {view, widget};
+  }
+
+  it('renders with initial state', async () => {
+    const {view} = await createWidget();
+    assert.strictEqual(view.input.counter, 0);
+  });
+
+  it('increments counter on button click', async () => {
+    const {view} = await createWidget();
+
+    // Simulate the click by invoking the callback.
+    view.input.onButtonClick();
+
+    // Wait for the re-render.
+    const finalInput = await view.nextInput;
+
+    assert.strictEqual(finalInput.counter, 1);
+  });
+
+  it('updates its title when a new one is passed in', async () => {
+    const {view, widget} = await createWidget();
+
+    widget.title = 'New Test Title';
+    widget.requestUpdate();
+
+    const finalInput = await view.nextInput;
+    assert.strictEqual(finalInput.title, 'New Test Title');
+  });
+});
+```
+
+## Improving this Guide
+
+This document is a living guide. If you find that the instructions are incomplete, lead to errors, or could be improved, please suggest updates. Your goal is to make this guide as helpful as possible for both human developers and your future AI counterparts.

package/agents/prompts/verification.md

@@ -17,7 +17,8 @@
 
 ## Linting
 
-- `npm run lint` will execute ESLint and StyleLint and report any violations that must be fixed.
+- `npm run lint` will execute ESLint and StyleLint. It will report any violations and automatically fix them where possible.
+- To run the linter on a specific file or directory, you can run `npm run lint -- <PATH>` where `PATH` is a path to a file or directory. This will also automatically fix violations where possible.
 
 ## Best practices
 

package/docs/contributing/README.md

@@ -6,12 +6,11 @@ This page assumes a working Chromium DevTools [checkout and build](../get_the_co
 
 1.   [Quick Start](#Quick-Start)
 2.   [IDE Setup](#IDE-Setup)
-3.   [Design Documents](./design.md)
-4.   [Contributing changes](./changes.md)
-5.   [Issues Guidelines](./issues.md)
-6.   [Settings, Experiments, and Features](./settings-experiments-features.md)
-7.   [Infrastructure](./infrastructure.md)
-8.   [Legal Stuff](#Legal-Stuff)
+3.   [Contributing changes](./changes.md)
+4.   [Issues Guidelines](./issues.md)
+5.   [Settings, Experiments, and Features](./settings-experiments-features.md)
+6.   [Infrastructure](./infrastructure.md)
+7.   [Legal Stuff](#Legal-Stuff)
 
 
 ## Quick Start

package/docs/contributing/changes.md

@@ -1,8 +1,7 @@
 # Contributing changes to Chromium DevTools
 
 See [Get the Code](../get_the_code.md) for details on how to checkout the code,
-and [Design Documents](design.md) for information regarding our design process.
-Also check out [Contributing to
+and check out [Contributing to
 Chromium](https://chromium.googlesource.com/chromium/src/+/main/docs/contributing.md)
 for general information how to contribute to any Chromium project (including
 its developer tools).

package/docs/feature-specs/elements-tree-edit-html.md

@@ -0,0 +1,14 @@
+# HTML Edit View in Elements Tree
+
+## Overview
+The HTML Edit View allows developers to freely edit the HTML of a DOM node directly in the Elements panel. When active, it replaces the standard tree item representation with a fully functional CodeMirror editor instance.
+
+## Requirements
+1. **Triggering**: Users can trigger the HTML edit view via keyboard shortcuts (`F2` on a selected node), or via the Context Menu ("Edit as HTML").
+2. **Editor UI**: When activated, the tree element's inline attributes, tags, and descendant nodes are hidden. A CodeMirror editor instance is shown in place of the node.
+3. **Behavior**:
+    - The editor is populated with the node's `outerHTML` (or relevant subset).
+    - It supports syntax highlighting, auto-completion of tags, and proper indentation.
+    - If the user clicks outside the editor or presses `Cmd+Enter` / `Ctrl+Enter`, the edit is committed.
+    - If the user presses `Escape`, the edit is aborted.
+4. **State Management**: Upon committing or aborting, the tree element restores its standard view, and any updated DOM state is reflected.

package/docs/feature-specs/elements-tree-node-title.md

@@ -0,0 +1,46 @@
+# Requirements Specification: Elements Panel Tree Node Title
+
+## 1. Overview
+The Elements panel represents the DOM tree as a collection of nodes. Each node's primary visual representation—its "title"—is a dynamic string of text, interactive links, and syntax-highlighted code. This specification documents the expected user-facing behaviors of the node title rendering across various DOM node types, ensuring a rich, interactive, and accurate representation of the document structure.
+
+## 2. Node Types and Rendering Rules
+
+### 2.1 Element Nodes (`Node.ELEMENT_NODE`)
+Element nodes are the most common nodes in the tree. Their rendering depends on their state:
+*   **Standard Tags**: Rendered as `<tagName attribute="value">` for opening tags and `</tagName>` for closing tags. The tag names are syntax-highlighted.
+*   **Pseudo-Elements**: Rendered as `::pseudo-element-name(identifier)`.
+*   **Inline Text Nodes**: If an element contains only a text node and no other children (e.g., `<div>Hello</div>`), it is rendered entirely on one line: `<tagName>Hello</tagName>`. The text content has its whitespace collapsed, and HTML entities are syntax-highlighted.
+*   **Collapsed Expandable Elements**: When an element with children is collapsed, the title renders the opening tag, a clickable expand button (`▶`), a visually hidden `…` (for accessibility and layout tests), and the closing tag, all on one line.
+
+### 2.2 Attributes
+Attributes within Element nodes have complex interactive behaviors:
+*   **Formatting**: Rendered natively as `name="value"`. If an attribute has no value, the `="value"` part is omitted unless explicitly forced.
+*   **HTML Entities**: Unicode sequences and entities within attribute values are syntax-highlighted.
+*   **Linkification (URLs)**: Values of `src` and `href` attributes, as well as complex `srcset` definitions in `<img>`, `<source>`, and `<image>` tags, are automatically detected. They are rendered as clickable links that open the resource or show an image preview popover on hover.
+*   **Linkification (DOM Relations)**: Attributes that establish DOM relationships (`popovertarget`, `interesttarget`, `commandfor`) are parsed. Their values are rendered as clickable links that, when clicked, reveal the target DOM node in the Elements panel. Tooltips will read: "Reveal Popover Target", "Reveal Interest Target", or "Reveal Command For Target" respectively.
+
+### 2.3 Text Nodes (`Node.TEXT_NODE`)
+*   **Standard Text**: Rendered surrounded by double quotes (`"text"`). HTML entities within the text are highlighted.
+*   **JavaScript inside `<script>`**: If the parent is a `<script>` tag, the text is treated as code. Quotes are omitted, whitespace is trimmed, and the content is passed through the JavaScript syntax highlighter.
+*   **CSS inside `<style>`**: If the parent is a `<style>` tag, the text is treated as code. Quotes are omitted, whitespace is trimmed, and the content is passed through the CSS syntax highlighter.
+
+### 2.4 Other Node Types
+*   **Comment Nodes (`Node.COMMENT_NODE`)**: Rendered exactly as `<!-- comment text -->`.
+*   **Doctype Nodes (`Node.DOCUMENT_TYPE_NODE`)**: Rendered in the format `<!DOCTYPE name PUBLIC "publicId" "systemId" [internalSubset]>`. Only the applicable parts of the doctype are displayed.
+*   **CDATA Sections (`Node.CDATA_SECTION_NODE`)**: Rendered as `<![CDATA[text]]>`.
+*   **Document Nodes (`Node.DOCUMENT_NODE`)**: Rendered as `#document (url)` where the URL is a clickable link.
+*   **Document Fragments (`Node.DOCUMENT_FRAGMENT_NODE`)**: Rendered as the fragment name, with whitespace collapsed (e.g., `#document-fragment`). Shadow roots also receive specific CSS classes to indent them appropriately (`shadow-root`, `shadow-root-deep`, etc.).
+
+## 3. Dynamic Highlighting and Interactions
+
+### 3.1 DOM Update Flash (Animations)
+When the DevTools backend reports a change to a node (via an `ElementUpdateRecord`), the specific portion of the title that changed must briefly flash with a purple highlight (`dom-update-highlight` CSS animation):
+*   If an attribute was added/modified, the attribute value flashes.
+*   If children were added/removed (and the element is not expanded), the tag name flashes.
+*   If text content changed, the text node itself flashes.
+
+### 3.2 Search Result Highlighting
+When a user executes a search within the Elements panel (Ctrl/Cmd + F), matches found within the text representation of the node title are highlighted with a distinct yellow background span. This highlight spans across Tag names, attributes, and text values.
+
+### 3.3 Adorners
+Specific semantic markers like `slot`, `grid`, `flex`, and `popover` markers are appended to the title but managed via a separate layout/adorner system, overlaying on the line.

package/docs/styleguide/ux/README.md

@@ -16,6 +16,6 @@ user interface.
 
 ## UI reviews
 If you make changes to DevTools UI, make sure to involve us **early**, i.e. already in the
-UI design stage. See also the [Chrome DevTools Design Review Guidelines](../../contributing/design.md#Review-Guidelines)
+UI design stage.
 
 Back to the [Chromium DevTools Documentation](../../README.md).