chrome-devtools-frontend 1.0.1664619 → 1.0.1666631

package/.agents/skills/devtools-testing-guidance/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: devtools-testing-guidance
+description: Guidance on selecting the appropriate test suite (Unit, API, or E2E tests) when writing new tests in Chrome DevTools. MUST be used when writing new tests.
+---
+
+# Testing Guidance
+
+This guide outlines when and how to select the appropriate test suite when writing new tests in Chrome DevTools.
+
+> [!NOTE]
+> This skill provides guidance on **which** test suite to choose when writing tests. To learn **how** to run tests, build targets, or execute linters, refer to the `devtools-verification` skill.
+
+## Choosing a Test Suite
+
+### 1. Unit Tests
+
+**Default choice:** The vast majority of tests in DevTools should be unit tests.
+
+Use unit tests for isolated testing of individual functions, classes, models, helpers, and UI components.
+
+- **Utilities & Framework:**
+  - Use `TestUniverse` (and foundation test helpers) for easy, isolated setup of required dependencies and models.
+  - For testing UI widgets, use stubbed view functions and screenshot assertions rather than spinning up heavy DOM/browser infrastructure.
+- **Location:** Co-located next to their implementation files (e.g. `TimelinePanel.ts` and `TimelinePanel.test.ts`).
+- **BUILD.gn**: test file should be added to `devtools_ui_module("unittests")` or `devtools_foundation_module("foundation_unittests")` target in the corresponding `BUILD.gn` file.
+
+---
+
+### 2. API Tests
+
+Use API tests for integration tests that verify business logic requiring more complex setups or extensive CDP (Chrome DevTools Protocol) traffic, without needing the full DevTools frontend UI.
+
+- **When to use:**
+  - Evaluating JavaScript expressions in the target page (e.g. via `Runtime.evaluate`).
+  - Complex source map setups and symbolization.
+  - Multi-context or target setups (workers, iframes, OOPIFs).
+  - Tests that require extensive CDP mock setup.
+  - Verifying the "foundational layer" of DevTools models against a real browser/web page.
+- **Location:** Defined in `front_end/` with `.test.api.ts` extension (e.g. `Universe.test.api.ts`).
+- **BUILD.gn**: test file should be added to `devtools_api_test_module("api_tests")` target in the corresponding `BUILD.gn` file.
+
+---
+
+### 3. End-to-End (E2E) Tests
+
+Use E2E tests to verify real end-to-end user stories and user journeys.
+
+- **When to use:**
+  - Verifying full user journeys across DevTools panels and drawers.
+  - Complex UI behaviors that require extensive user interaction setup and benefit from a complete DevTools frontend page connected to an inspected target page over CDP.
+- **Location:** Defined in `test/e2e/` (e.g. `test/e2e/console/console-log.test.ts`).
+- **BUILD.gn**: test file should be added to `ts_e2e_library(ts_e2e_library)` target in the corresponding `BUILD.gn` file. And `node_ts_library` in `test/e2e/BUILD.gn` for its dependencies.

package/.agents/skills/devtools-ux-writing-refactor/SKILL.md

@@ -52,7 +52,7 @@ Locate all TypeScript files in the target folder that define `const UIStrings =
    * *Check sibling references:* If you change a setting name or label (for example, changing “Preserve log” to “Keep log”), search sibling files in the folder for explanatory text or status strings that reference the old name in quotes (for example, “console.clear() was prevented due to ‘Preserve log’”), and update them to match.
 2. **Cut unnecessary words:** Eliminate politeness (`please`, `sorry`), filler (`very`, `strongly`, `there is` or `there are`), and marketing fluff (`seamless`, `awesome`, `fast`, `quick`).
 3. **Contractions:** Use contractions (`don’t`, `can’t`, `isn’t`, `won’t`) instead of formal spellings (`do not`, `cannot`, `is not`, `will not`).
-4. **Curly apostrophes, quotation marks, and ellipses:** Use curly apostrophes (`’`) in user-facing `UIStrings` values for contractions and possessives, and quotation marks (`“ ”`) for improved readability. Use the ellipsis character (`…`) instead of three periods (`...`). Use prime (`′`) and double prime (`″`) symbols as needed for measurements like length or coordinates.
+4. **Curly apostrophes, quotation marks, and ellipses:** Use curly apostrophes (`’`) in user-facing `UIStrings` values for contractions and possessives. Double quotes should be straight (`"`) to avoid usability issues when users want to copy string literals, though consider not using double quotes at all where not necessary. Note that using both double quotes and backticks (for example, `"`Permissions-Policy`"`) is valid and useful when a fixed term needs to be visually enclosed in quotes in the UI, as backticks are used for localization locking and are often not rendered visually. Use the ellipsis character (`…`) instead of three periods (`...`). Use prime (`′`) and double prime (`″`) symbols as needed for measurements like length or coordinates.
 5. **Sentence case and capitalization:** Use sentence case for headings, labels, and UI element names. Capitalize only the first word, proper nouns, product names (`Chrome DevTools`), and web APIs (`Background Fetch API`).
    * Don’t capitalize feature names (for example, `conditional breakpoint` or `command menu`).
    * Capitalize panel names and UX elements that are named after panels (for example, `Show Application`, `Toggle Console`, `Console sidebar`, or `Styles`).

package/.agents/skills/migrate-chromium-test/SKILL.md

@@ -1,59 +1,59 @@
 ---
 name: migrate-chromium-test
-description: Use when migrating Chromium layout tests to DevTools unit tests
+description: Use when migrating Chromium layout tests to DevTools unit tests or API tests.
 ---
 
 ## Workflow
 
-1.  **Identify the Test to Move**:
+### 1. Identify the Test to Move
 
 - You should have already received the issue ID, the test title, and the exact local paths of the downloaded legacy test file (`.js`) and its expectation file (`-expected.txt`) in your initial prompt.
 - Refer to these local copies as you write the new modern test.
 
-2.  **Identify the Target Location**:
+### 2. Determine Target Location & Test Suite Type
 
-- Find the file being tested in `front_end/`.
-- Place the new test file next to the file being tested, following the naming convention `[FileName].test.ts`.
-- Example: If testing `ui/legacy/components/data_grid/DataGrid.ts`, the test should be `ui/legacy/components/data_grid/DataGrid.test.ts`.
+Investigate what files are being tested, start location should be `front_end/`.Consult the `devtools-testing-guidance` skill to select the appropriate test suite.
 
-3.  **Convert the Test Content**:
+### 3. Convert the Test Content
 
-- Rewrite the test from the legacy `TestRunner` style to the modern Mocha/Chai style used in DevTools.
-- Use `describeWithEnvironment` or `describe` as appropriate.
-- Replace `TestRunner.addResult` and expectation comparisons with standard assertions (`assert.strictEqual`, `assert.isTrue`, etc.).
-- If the test requires rendering, use `renderElementIntoDOM` to attach elements to a test container.
-- If testing legacy components that require internal tokens or have private methods, try to use public APIs or events instead. If impossible, consider using structural typing workarounds or updating the component to be more testable.
-- If tests require a repetitive setup extract it into a test helper function at the top of the file.
-- Code comments must be full sentences ending with a period, except when the entire comment is a URL.
-- Do not include comments of the form `// Replaces web test: http/tests/devtools/persistence/automapping-absolute-paths.js`. Since we plan to remove migrated web tests, these are not useful references.
-- **Important** If the test imports only `TestRunner` and no other TestRunner helper or DevTools code. The test should be move to the inspector-protocol test, and the issue should be closed as "Won't Fix (Infeasible)" and add the issue to the hotlist with ID 8691563.
+- **Testing Style:** Rewrite legacy `TestRunner` calls into modern Mocha (`describe`, `it`) and Chai assertions (`assert.strictEqual`, `assert.isTrue`, `assert.deepEqual`, `assert.isNotNull`, `assert.instanceOf`).
+- **Import Conventions:** Strictly follow the `devtools-imports` skill:
+  - Import cross-module code via module entrypoints (e.g., `import * as Module from '../module/module.js'`).
+  - Always use `import * as` for cross-module imports.
+  - TypeScript imports in DevTools **must** use `.js` file extensions (e.g., `./data_grid.js`).
+- **Environment & Setup Selection:**
+  - **Foundation / Non-UI Tests:** Follow the `foundation-test-migration` skill. Use `TestUniverse` and setup hooks (`setupLocaleHooks()`, `setupSettingsHooks()`, `setupRuntimeHooks()`) instead of DOM-heavy singletons or `describeWithEnvironment`. Use `universe.createTarget()` and `MockCDPConnection` for CDP mocking.
+  - **UI & Widget Tests:** Follow the `devtools-ui-widgets` skill. Use `renderElementIntoDOM` from `front_end/testing/DOMHelpers.js` for mounting elements, or `createViewFunctionStub` and `view.nextInput` from `front_end/testing/ViewFunctionHelpers.js` for testing MVP widgets.
+- **Code Comments:**
+  - Must be full sentences ending with a period (except when the entire comment is a URL).
+  - Do **not** include comments like `// Replaces web test: http/tests/devtools/...`. Since migrated web tests are deleted, these references become stale.
+- **Accessing Private Members & Events:** Avoid calling private methods or accessing internal tokens. Test public APIs or trigger behavior by dispatching standard DOM/SDK events instead.
 
-4.  **Update BUILD.gn**:
+### 4. Update BUILD.gn Configuration
 
-- Add the new test file to the `sources` list of the `devtools_ui_module("unittests")` or `devtools_foundation_module("foundation_unittests")` target in the corresponding `BUILD.gn` file.
+Every newly created test file must be added to the appropriate target in its folder's `BUILD.gn`:
 
-5.  **Verify the Changes**:
+> [!IMPORTANT]
+> If you omit the test file from `BUILD.gn`, the test target will not be compiled by Ninja and will be skipped by test runners.
 
-- Use the `verification` skill to correctly build the project and run the new test.
-- Ensure the test passes.
+### 5. Verify the Changes
 
-6. **Evaluate Test Completeness and Utility**:
+Use the `devtools-verification` skill to build and verify your changes.
 
-- Critically review the newly created test to ensure it provides meaningful coverage. Cross-reference it with the original Chromium layout test to verify that all original behaviors, edge cases, and assertions have been fully migrated and are actively being tested.
-- If the newly added test does not test any logic from the component but just the getters from the mocked data explain to the user that this test does not add value and it's better to close it without adding the test. Provide a command without executing it to close the issue as "Fixed".
-- If the newly added test uses too extensive mocks of CDP objects and methods explain to the user that the test should be foundation e2e test instead of unit test and we won't migrate it. **CRITICAL**  upload a comment to the issue with your investigation and the reason why you won't submit a CL and close the issue as "Won't Fix (Infeasible)" and add the issue to the hotlist with ID 8687901.
+### 6. Evaluate Test Completeness and Utility
 
-7. **Upload the CL:**
+- Critically review the newly created test to ensure it provides meaningful coverage. Cross-reference it with the original Chromium layout test to verify that all original behaviors, edge cases, and assertions have been fully migrated.
+- If the newly added test does not test any logic from the component but only tests getters from mocked data, explain to the user that this test does not add value and it is better to close it without adding the test. Provide a command without executing it to close the issue as "Fixed".
 
-## Commit message & CL upload requirements
+### 7. Upload the CL
 
-When committing and uploading CLs, **STRICTLY** follow this format and constraints:
-
-1. **Title line**: `[test-migration] Migrate <short test name> test to unit test`
-2. **Body**: `This CL migrates the legacy layout test <long test name> to a unit test in <new test name>. <optional additional explanation>`
-2. **Body appendix**: `https://crsrc.org/c/third_party/blink/web_tests/<long test name>;drc=4d51e9cab50efd0f8029c45a486e199a1d519fd1`
-3. **Bug line**: `Fixed: <issue number>`
-4. **Formatting constraints**: Wrap all lines to a maximum of 72 characters per line.
+Follow the `version-control` skill when uploading CLs.
+Follow the following format and constraints:
+   - **Title line:** `[test-migration] Migrate <short test name> test to unit test`
+   - **Body:** `This CL migrates the legacy layout test <long test name> to a unit test in <new test name>. <optional additional explanation>`
+   - **Body appendix:** `https://crsrc.org/c/third_party/blink/web_tests/<long test name>;drc=4d51e9cab50efd0f8029c45a486e199a1d519fd1`
+   - **Bug line:** `Fixed: <issue number>`
+   - **Line Length Constraint:** Wrap all lines in the commit message to a maximum of 72 characters per line.
 
 Example commit message:
 
@@ -71,11 +71,14 @@ https://crsrc.org/c/third_party/blink/web_tests/http/tests/devtools/console/cons
 Fixed: <issue number>
 ```
 
-Use the `version-control` skill to upload the CL.
 
-## Example Conversion
+---
+
+## Conversion Examples
+
+### Example 1: UI Unit Test (`DataGrid.test.ts`)
 
-### Legacy Test (`datagrid-editable-longtext.js`)
+#### Legacy Test (`datagrid-editable-longtext.js`)
 
 ```javascript
 import {TestRunner} from 'test_runner';
@@ -90,31 +93,43 @@ import * as DataGrid from 'devtools/ui/legacy/components/data_grid/data_grid.js'
 })();
 ```
 
-### Converted Test (`DataGrid.test.ts`)
+#### Converted UI Test (`DataGrid.test.ts`)
 
 ```typescript
-import * as DataGrid from './data_grid.js';
 import {renderElementIntoDOM} from '../../../../testing/DOMHelpers.js';
 import {describeWithEnvironment} from '../../../../testing/EnvironmentHelpers.js';
+import * as DataGrid from './data_grid.js';
 
 describeWithEnvironment('DataGrid', () => {
   it('tests long text in datagrid', () => {
     // ... setup grid ...
-    // Use assertions instead of printing results.
+    const grid = new DataGrid.DataGrid.DataGridImpl({...});
+    renderElementIntoDOM(grid.element);
+
+    // Use Chai assertions instead of printing results.
     assert.strictEqual(keyElement.textContent.length, 1500);
   });
 });
 ```
 
+---
+
 ## Tips & Troubleshooting
 
-- **TypeScript Type Mismatches**: Legacy tests often use plain strings for properties that now require specific branded types like `LocalizedString`. You can often bypass this in tests by casting the object array `as DataGrid.DataGrid.ColumnDescriptor[]` or similar, or by using `i18n.i18n.lockedString` if appropriate.
-- **Accessing Private Methods**: Legacy tests frequently called private methods (e.g., `dataGrid.update()`). In TypeScript unit tests, you should avoid this. Look for public alternatives (e.g., `updateInstantly()`) or trigger the behavior by dispatching standard DOM events (e.g., `element.dispatchEvent(new Event('scroll'))` instead of calling `onScroll()`).
-- **Recursive Expansion Limits**: Methods like `TreeElement.expandRecursively()` have a default depth limit (e.g., 3) to prevent infinite loops. If your test requires expanding deeper trees, remember to pass a higher max depth argument: `expandRecursively(10)`.
-- **Mocking Objects**: When testing UI components that display objects (like `RemoteObject`), look for existing mock helpers in related test files (e.g., `createDeepRemoteObjectMock` in `ObjectPropertiesSection.test.ts`) instead of trying to create real SDK objects or complex mocks from scratch. Other helpers live inside `front_end/testing`.
-- **Ignoring Environment Failures**: In some environments, `npm run test` may exit with code 1 due to memory leaks (e.g., `WebFrame LEAKED`) or infrastructure issues (e.g., `gpkg` or `Corp Airlock` logs), even if the tests themselves passed. Always check the end of the test log for `TOTAL: X SUCCESS` to confirm if the test logic was successful.
-- **Rendering issue**: If you encounter an issue where checking values never gives correct information it may be due to async rendering. To resolve that you may trying using `raf()` from `front_end/testing/DOMHelpers.ts` to wait for the next rendering cycle.
+- **TypeScript Type Mismatches:** Legacy tests often use plain strings for properties that now require branded types like `LocalizedString`. You can bypass this in tests by casting (`as DataGrid.DataGrid.ColumnDescriptor[]`) or by using `i18n.i18n.lockedString` where appropriate.
+- **Accessing Private Methods:** Legacy tests frequently called private methods (e.g., `dataGrid.update()`). Look for public alternatives (e.g., `updateInstantly()`) or trigger the behavior by dispatching standard DOM/SDK events (e.g., `element.dispatchEvent(new Event('scroll'))`).
+- **Domain Test Helpers in `front_end/testing/`:** Check existing helper utilities before writing custom boilerplate:
+  - `DOMHelpers.ts`: `renderElementIntoDOM`, `dispatchAndAwait`.
+  - `ViewFunctionHelpers.ts`: `createViewFunctionStub`, `view.nextInput` (for MVP widget tests).
+  - `MockCDPConnection.ts`: Scoped protocol mocking.
+  - `SourceMapHelpers.ts`, `TraceHelpers.ts`, `ConsoleHelpers.ts`, `SettingsHelpers.ts` etc.
+- **Async Rendering:** If component values fail to update immediately during tests, wait for the next rendering frame using `raf()` from `front_end/testing/DOMHelpers.js`.
+- **Recursive Expansion Limits:** Methods like `TreeElement.expandRecursively()` have default depth limits (e.g. 3). Pass a higher max depth argument if your test requires deeper tree expansion: `expandRecursively(10)`.
+- **Mocking Complex Objects:** Look for existing mock helpers in related test files (e.g., `createDeepRemoteObjectMock` in `ObjectPropertiesSection.test.ts`) instead of instantiating real objects from scratch.
+- **Ignoring Infrastructure Log Warnings:** In some local environments, test runs may print leak messages (e.g., `WebFrame LEAKED`) or `Corp Airlock` warnings. Always inspect the summary line at the end of the test log for `TOTAL: X SUCCESS` to confirm if test logic passed.
+
+---
 
-## After finishing the migration
+## After Finishing the Migration
 
-If you encountered any novel issues, workarounds, or helpful tips during the migration that are not already documented, please report them to the user so they can be added to the skill documentation.
+If you encountered any novel issues, workarounds, or helpful tips during the migration that are not already documented, please inform the user so the skill documentation can be further updated.

package/.agents/skills/ui-eng-vision-local-lit-renderer/SKILL.md

@@ -43,10 +43,13 @@ existing element containers.
         ```
 
 4.  **Modern Component Mapping**:
-
-    *   Refer to [ui_engineering.md](../../../docs/ui_engineering.md) for
-        specific migration examples.
+    *   **MANDATORY**: You **MUST** read and load [ui_engineering.md](../../../docs/ui_engineering.md) first to understand specific component mappings (e.g., Toolbar vs `devtools-toolbar`). Do not assume standard Lit defaults.
     *   If unsure, also consult the [automatic migration code](../../../scripts/eslint_rules/lib/no-imperative-dom-api.ts)
+    *   **Prefer Component Built-Ins Over Legacy Boilerplate**: Before porting
+        legacy event handlers, comparators, or state variables, check if the
+        modern component handles them natively. Drop host-level workarounds in
+        favor of declarative component attributes.
+
 
 5.  **Local Modular Renders**:
 
@@ -70,6 +73,7 @@ existing element containers.
     *   Do not attempt to rewrite complex historical subsystems (like Linkifiers
         or specialized UI utilities) to be "pure Lit" during this pass.
     *   Capitalize on Lit's ability to interpolate standard `HTMLElement` or `Element` instances directly. Treat unmigrated utilities as "black boxes" that generate DOM, and embed their output in standard template expressions: `html`<div>${this.legacyElement}</div>``.
+    *   **CRITICAL:** Before treating any component as "unmigrated," you MUST follow steps in Section 4. You are only allowed to use this escape hatch if no declarative migration instructions exist.
 
 8.  **Handle Asynchronous DOM Updates**:
 
@@ -87,9 +91,10 @@ existing element containers.
         functions inside the class scope returning `LitTemplate`. This avoids
         monoliths, preserves readability, and reuses template cache strategies.
 
-10. **Visual Parity and Accessibility**:
+10. **Visual Parity, CSS Adaptation, and Accessibility**:
 
     *   **Zero-Tolerance Regression**: Screenshot tests are the ground truth for this phase. Any visual diff (above 0%) in the generated screenshots is unacceptable and must be resolved before proceeding.
+    *   **CSS Selector Migration**: When replacing legacy imperative components/widgets with modern web components (e.g., replacing legacy `DataGrid` with `<devtools-data-grid>`), inspect and update the associated `.css` file. Replace legacy class selectors (`.data-grid`) with tag selectors (`devtools-data-grid`).
     *   **Strict Tag/Class Parity**: Do not change tag types (e.g., `span` to
         `div`) or drop class names during template translation, as CSS may
         depend on them.
@@ -118,5 +123,15 @@ existing element containers.
 
 13. **Wait for confirmation**:
 
-    *   Wait for an explicit confirmation from the user before proceeding to the
-        next step.
+    *   Wait for an explicit confirmation from the user (or Parent Orchestrator Agent) before proceeding to the next step.
+
+--------------------------------------------------------------------------------
+
+## 🔍 Mental Audit (Internal Self-Correction)
+
+*Before reporting back or committing, re-read the instructions and verify:*
+1.  ❓ **Tag Parity**: Did I accidentally change any `span` to `div` (or vice versa)?
+2.  ❓ **Attribute Drop**: Did I drop any `aria-*`, `role`, or custom data attributes?
+3.  ❓ **Clang-Off Boundary**: Is the template wrapped in `// clang-format off`?
+4.  ❓ **Build**: Does the code compile and do visual tests pass with 0% diff?
+

package/.agents/skills/ui-eng-vision-logic-consolidator/SKILL.md

@@ -78,5 +78,14 @@ consolidating them into private helper methods with explicit data contracts.
 
 6.  **Wait for confirmation**:
 
-    *   Wait for an explicit confirmation from the user before proceeding to the
-        next step.
+    *   Wait for an explicit confirmation from the user (or Parent Orchestrator Agent) before proceeding to the next step.
+
+--------------------------------------------------------------------------------
+
+## 🔍 Mental Audit (Internal Self-Correction)
+
+*Before reporting back or committing, re-read the instructions and verify:*
+1.  ❓ **Minimal Diffs**: Did I move code blocks around unnecessarily?
+2.  ❓ **State Completeness**: Are all imperative DOM updates now backed by state variables?
+3.  ❓ **Build**: Does the code still compile?
+

package/.agents/skills/ui-eng-vision-orchestrator/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: ui-eng-vision-orchestrator
 description: High-level orchestrator for managing multi-pass migration of Chrome DevTools legacy components to the modern UI engineering vision (UI.Widget & Lit-html).
-allowed-tools: code_search open_urls search_changelists data_analysis import_skill close_skill
+allowed-tools: code_search open_urls search_changelists data_analysis import_skill close_skill invoke_subagent send_message
 ---
 
 # UI Engineering Vision Orchestrator: Meta-Skill Instructions
@@ -14,6 +14,16 @@ small, testable, and highly reviewable.
 Refer to [ui_engineering.md](../../../docs/ui_engineering.md) for general
 principles.
 
+--------------------------------------------------------------------------------
+
+## 🛑 Critical Constraints & Forbidden Actions
+
+1.  **NEVER Break the Build**: Code must compile and tests must pass at all steps. If you change a class API or method signature, you **MUST** update its usage in the same CL to maintain stability.
+2.  **Strict Intermediate Stability**: Do not leave the code in a broken state between passes.
+3.  **No Beautification of Adjacent Code**: Do NOT fix unrelated typos, formatting issues, or lint warnings in code you aren't actively migrating.
+4.  **No Monolithic Refactors**: Do NOT batch Lit conversion and Widget Promotion in the same pass. Keep CLs small and focused.
+
+
 --------------------------------------------------------------------------------
 
 ## 1. Migration Philosophy & Plan-Validate-Execute Pattern
@@ -48,8 +58,8 @@ principles.
     converting imperative DOM to Lit-html) with base class refactoring in the
     same diff.
 8.  **Strict Intermediate Stability**: The code must compile and work correctly,
-    and all tests must pass after each step. We should not split the class API
-    update from its usage update.
+    and all tests must pass after each step. You **MUST** update usages if you
+    change APIs.
 9.  **Establish Comprehensive Guardrails First**: Ensure both **logic tests**
     (verifying presenter interactions and state updates) and **screenshot
     tests** (verifying layout/styling) exist before rewriting code. If coverage
@@ -62,6 +72,11 @@ principles.
     roughly 300 lines of code. If a step is predicted to be too complex, break
     it down into smaller substeps. The agent must stop and report back after
     each step or substep to allow verification.
+12. **Context Hygiene via Subagents**: To keep the main conversation context
+    clean and focused on high-level orchestration, prefer delegating intense
+    execution tasks (like running tests, debugging compilations, or processing
+    independent classes in parallel) to specialized subagents.
+
 
 --------------------------------------------------------------------------------
 
@@ -96,16 +111,38 @@ principles.
             DOM construction. Converting the layout to declarative Lit templates
             first (using temporary inline or local state) makes it much easier
             to isolate and group the remaining state updates afterward.
-    5.  Generate a `migration_plan.md` reflecting this ordering and outlining
-        the target steps.
+    5.  Generate a `migration_plan.md` using the **Structured Plan Template** below.
     6.  Halt execution and print the formatted plan in Markdown to the chat.
         Wait for user approval.
 
+### 📝 Structured Plan Template
+The plan you generate **MUST** follow this structure:
+
+```markdown
+# Migration Plan: [FileName.ts]
+
+## 📊 Current State
+- **Hybrid File**: [Yes/No]
+- **Classes Found**: [ClassA, ClassB]
+- **Strategy Selection**: [Option A (Logic First) | Option B (Tech First)]
+
+## 🛠️ Passes Checklist
+- [ ] **Pass 0: Baseline & Safety Scaffolding**
+  - Assigned to: `ui-eng-vision-test-scaffolder`
+- [ ] **Pass 1: Logic Consolidation**
+  - Assigned to: `ui-eng-vision-logic-consolidator`
+- [ ] **Pass 2: Lit-HTML Rendering**
+  - Assigned to: `ui-eng-vision-local-lit-renderer`
+- [ ] **Pass 3: Widget Promotion**
+  - Assigned to: `ui-eng-vision-widget-promoter`
+```
+
+
 ### Baseline & Safety Scaffolding
 
 *   **Trigger Condition**: User explicitly says "I accept the plan" or
     equivalent.
-*   **Subskill to Import**: `ui-eng-vision-test-scaffolder`
+*   **Subskill to Import/Delegate**: `ui-eng-vision-test-scaffolder` (Delegate to a subagent to encapsulate verbose test logs)
 *   **Actions**:
     1.  Verify existing test coverage. Propose and add missing **logic tests**
         for interactions and **screenshot tests** for visual validation to avoid
@@ -116,7 +153,7 @@ principles.
 
 *   **Trigger Condition**: Baseline tests green (or respective previous pass
     staged).
-*   **Subskill to Import**: `ui-eng-vision-logic-consolidator`
+*   **Subskill to Import/Delegate**: `ui-eng-vision-logic-consolidator` (Delegate to a subagent to maintain focus)
 *   **Actions**:
     1.  Extract manual elements, constructor DOM configurations, and imperative
         updates into private update helper methods with structured
@@ -125,7 +162,7 @@ principles.
 ### Local Lit-HTML Rendering (Technology Migration)
 
 *   **Trigger Condition**: Previous pass staged.
-*   **Subskill to Import**: `ui-eng-vision-local-lit-renderer`
+*   **Subskill to Import/Delegate**: `ui-eng-vision-local-lit-renderer` (Delegate to a subagent for isolated template generation)
 *   **Actions**:
     1.  Migrate imperative elements to declarative templates (using component
         mapping rules defined inside the subskill) and render them locally
@@ -135,7 +172,7 @@ principles.
 
 *   **Trigger Condition**: Both local template rendering and logic consolidation
     staged.
-*   **Subskill to Import**: `ui-eng-vision-widget-promoter`
+*   **Subskill to Import/Delegate**: `ui-eng-vision-widget-promoter` (Delegate to a subagent for final architectural cleanup)
 *   **Actions**:
     1.  Promote view classes to modern `UI.Widget` classes, hook up
         `performUpdate()` delegates, export the default view layout, and clean

package/.agents/skills/ui-eng-vision-test-scaffolder/SKILL.md

@@ -57,7 +57,7 @@ logical regressions are introduced during modernization.
 
 4.  **Wait for confirmation**:
 
-    *   Wait for an explicit confirmation from the user before proceeding to the next step.
+    *   Wait for an explicit confirmation from the user (or Parent Orchestrator Agent) before proceeding to the next step.
 
 --------------------------------------------------------------------------------
 
@@ -123,3 +123,22 @@ Always detect the execution environment first to run tests successfully:
         ```bash
         npm run build
         ```
+
+### Scenario D: Screenshot Test Fails (Visual Diffs > 0%)
+
+*   **Symptom**: The test runs but fails with a percentage difference in visual regression.
+*   **Resolution Steps**:
+    1.  Do **NOT** ask the user to accept the new screenshot yet.
+    2.  Inspect the failure log to see if it is a **layout shift** or a **missing style**.
+    3.  If it's a layout shift, check if you replaced a block element with an inline element (e.g. `div` -> `span`).
+    4.  If styles are missing, verify if the test wrapper needs `{includeCommonStyles: true}`.
+
+--------------------------------------------------------------------------------
+
+## 🔍 Mental Audit (Internal Self-Correction)
+
+*Before reporting back or committing, re-read the instructions and verify:*
+1.  ❓ **Coverage**: Did I cover all classes in the file, or only the main one?
+2.  ❓ **Stability**: Can the tests run repeatedly without flakiness?
+3.  ❓ **Integrations**: Did I verify that the component mounts correctly?
+

package/.agents/skills/ui-eng-vision-widget-promoter/SKILL.md

@@ -14,6 +14,8 @@ clean `UI.Widget` classes that use native update rendering delegates.
 
 ## 1. Widget Promotion Guidelines
 
+*   **Widget Framework Rules**: Follow the rules defined in [`devtools-ui-widgets`](../ui-widgets/SKILL.md).
+
 1.  **Change Class Inheritance**:
 
     *   Rewrite class declarations to extend `UI.Widget` (or specialized
@@ -74,3 +76,12 @@ clean `UI.Widget` classes that use native update rendering delegates.
 *   **Minimal Code Movement**: When migrating, try to move code around as little as possible, in particular around the lit rendering helpers. This minimizes the git diff and improves reviewability.
 
 --------------------------------------------------------------------------------
+
+## 🔍 Mental Audit (Internal Self-Correction)
+
+*Before reporting back or committing, re-read the instructions and verify:*
+1.  ❓ **Decoupling**: Did I remove all direct `.element` or `.contentElement` couplings from instantiator files?
+2.  ❓ **Inheritance**: Does the class now cleanly inherit from `UI.Widget` or its variants?
+3.  ❓ **Injectability**: Is the view injectable in the constructor?
+4.  ❓ **Build**: Does the code compile and do tests pass?
+

package/eslint.config.mjs

@@ -103,6 +103,7 @@ export default defineConfig([
       '@stylistic/semi': 'error',
       '@stylistic/no-extra-semi': 'error',
       '@stylistic/comma-style': ['error', 'last'],
+      '@stylistic/comma-dangle': ['error', 'always-multiline'],
       '@stylistic/wrap-iife': ['error', 'inside'],
 
       '@stylistic/spaced-comment': [
@@ -719,6 +720,13 @@ export default defineConfig([
       'no-console': 'off',
     },
   },
+  {
+    name: 'API test files',
+    files: ['**/*.test.api.ts'],
+    rules: {
+      '@devtools/no-api-test-unit-helpers': 'error',
+    },
+  },
   {
     name: 'TypeScript test files',
     files: [

package/front_end/Images/rollup.config.mjs

@@ -30,7 +30,7 @@ export default {
               return data;
             }
             return null;
-          }
+          },
         }),
       ],
 };

package/front_end/Tests.js

@@ -850,7 +850,7 @@
           'LenVOavSot+3i9DAgBkcRcAtjOj4LaR0VknFBbVPFd5uRHg5h6h+u/N5GJG7' +
           '9G+dwfCMNYxdAfvDbbnvRG15RjF+Cv6pgsH/76tuIMRQyV+dTZsXjAzlAcmg' +
           'QWpzU/qlULRuJQ/7TBj0/VLZjmmx6BEP3ojY+x1J96relc8geMJgEtslQIxq' +
-          '/H5COEBkEveegeGTLg=='
+          '/H5COEBkEveegeGTLg==',
     ]);
   };
 
@@ -901,22 +901,21 @@
     step1();
 
     function step1() {
-      testPreset(
-          MobileThrottling.networkPresets[3],
-          [
-            'offline event: online = false', 'connection change event: type = none; downlinkMax = 0; effectiveType = 4g'
-          ],
-          step2);
+      testPreset(MobileThrottling.networkPresets[3],
+                 [
+                   'offline event: online = false',
+                   'connection change event: type = none; downlinkMax = 0; effectiveType = 4g',
+                 ],
+                 step2);
     }
 
     function step2() {
-      testPreset(
-          MobileThrottling.networkPresets[2],
-          [
-            'online event: online = true',
-            'connection change event: type = cellular; downlinkMax = 0.3814697265625; effectiveType = 2g'
-          ],
-          step3);
+      testPreset(MobileThrottling.networkPresets[2],
+                 [
+                   'online event: online = true',
+                   'connection change event: type = cellular; downlinkMax = 0.3814697265625; effectiveType = 2g',
+                 ],
+                 step3);
     }
 
     function step3() {
@@ -1311,14 +1310,14 @@
     await SDK.TargetManager.TargetManager.instance().primaryPageTarget()?.runtimeAgent().invoke_evaluate({
       expression: `fetch("/set-cookie?devtools-test-cookie=Bar",
                          {credentials: 'include'})`,
-      awaitPromise: true
+      awaitPromise: true,
     });
     await testCase(baseURL + 'echoheader?Cookie', undefined, 200, ['cache-control'], 'devtools-test-cookie=Bar');
 
     await SDK.TargetManager.TargetManager.instance().primaryPageTarget()?.runtimeAgent().invoke_evaluate({
       expression: `fetch("/set-cookie?devtools-test-cookie=same-site-cookie;SameSite=Lax",
                          {credentials: 'include'})`,
-      awaitPromise: true
+      awaitPromise: true,
     });
     await testCase(
         baseURL + 'echoheader?Cookie', undefined, 200, ['cache-control'], 'devtools-test-cookie=same-site-cookie');

package/front_end/core/common/Gzip.ts

@@ -78,7 +78,7 @@ async function gzipCodec(
     start(controller) {
       controller.enqueue(buffer instanceof ArrayBuffer ? new Uint8Array(buffer) : buffer);
       controller.close();
-    }
+    },
   });
   const codecReadable = readable.pipeThrough(codecStream);
   // A response is a convenient way to get an ArrayBuffer from a ReadableStream.
@@ -104,7 +104,7 @@ export function createMonitoredStream(stream: ReadableStream, onProgress: (bytes
       bytesRead += chunk.byteLength;
       onProgress(bytesRead);
       controller.enqueue(chunk);
-    }
+    },
   });
 
   return stream.pipeThrough(progressTransformer);