chrome-devtools-frontend 1.0.1665921 → 1.0.1666631

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

@@ -22,6 +22,7 @@ Use unit tests for isolated testing of individual functions, classes, models, he
   - 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.
 
 ---
 
@@ -33,8 +34,10 @@ Use API tests for integration tests that verify business logic requiring more co
   - 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.
 
 ---
 
@@ -46,3 +49,4 @@ Use E2E tests to verify real end-to-end user stories and user journeys.
   - 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/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,15 +43,14 @@ 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**:
 
     *   If the class contains multiple separate legacy container fields (e.g.,
@@ -124,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

@@ -76,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/front_end/core/host/AidaClient.ts

@@ -61,10 +61,33 @@ const AidaLanguageToMarkdown: Record<AidaInferenceLanguage, string> = {
   [AidaInferenceLanguage.UNKNOWN]: 'unknown',
 };
 
-export class AidaAbortError extends Error {}
-export class AidaBlockError extends Error {}
-export class AidaQuotaError extends Error {}
-export class AidaPayloadTooLargeError extends Error {}
+export abstract class AidaClientError extends Error {
+  override name = 'AidaClientError';
+}
+export class AidaUnknownError extends AidaClientError {
+  override name = 'AidaUnknownError';
+}
+export class AidaAbortError extends AidaClientError {
+  override name = 'AidaAbortError';
+}
+export class AidaBlockError extends AidaClientError {
+  override name = 'AidaBlockError';
+}
+export class AidaQuotaError extends AidaClientError {
+  override name = 'AidaQuotaError';
+}
+export class AidaPayloadTooLargeError extends AidaClientError {
+  override name = 'AidaPayloadTooLargeError';
+}
+export class AidaPermissionDeniedError extends AidaClientError {
+  override name = 'AidaPermissionDeniedError';
+}
+export class AidaTimeoutError extends AidaClientError {
+  override name = 'AidaTimeoutError';
+}
+export class AidaInvalidJsonResponseError extends AidaClientError {
+  override name = 'AidaInvalidJsonResponseError';
+}
 
 interface AiStream {
   write: (data: string) => Promise<void>;
@@ -185,40 +208,7 @@ export class AidaClient {
         },
         err => {
           debugLog('doConversation failed with error:', JSON.stringify(err));
-          if (err instanceof DispatchHttpRequestClient.DispatchHttpRequestError && err.response) {
-            const result = err.response;
-            if (result.statusCode === 429) {
-              stream.fail(new AidaQuotaError('Server responded: quota exceeded'));
-              return;
-            }
-            if (result.statusCode === 403) {
-              stream.fail(new Error('Server responded: permission denied'));
-              return;
-            }
-            if ('error' in result && result.error) {
-              if (isQuotaError(result.error, result.detail)) {
-                stream.fail(new AidaQuotaError(
-                    `Cannot send request: ${result.error}${result.detail ? ` ${result.detail}` : ''}`));
-                return;
-              }
-              if (isPayloadTooLargeError(result.error, result.detail)) {
-                stream.fail(new AidaPayloadTooLargeError(
-                    `Cannot send request: ${result.error}${result.detail ? ` ${result.detail}` : ''}`));
-                return;
-              }
-              stream.fail(new Error(`Cannot send request: ${result.error}${result.detail ? ` ${result.detail}` : ''}`));
-              return;
-            }
-            if ('netErrorName' in result && result.netErrorName === 'net::ERR_TIMED_OUT') {
-              stream.fail(new Error('doAidaConversation timed out'));
-              return;
-            }
-            if (result.statusCode !== 200) {
-              stream.fail(new Error(`Request failed: ${JSON.stringify(result)}`));
-              return;
-            }
-          }
-          stream.fail(err);
+          stream.fail(mapError(err));
         });
     await (yield* this.#handleResponseStream(stream));
   }
@@ -265,13 +255,7 @@ export class AidaClient {
             thoughtSignature: result.functionCallChunk.functionCall.thoughtSignature,
           });
         } else if ('error' in result) {
-          if (isQuotaError(result.error)) {
-            throw new AidaQuotaError(`Server responded: ${JSON.stringify(result)}`);
-          }
-          if (isPayloadTooLargeError(result.error)) {
-            throw new AidaPayloadTooLargeError(`Server responded: ${JSON.stringify(result)}`);
-          }
-          throw new Error(`Server responded: ${JSON.stringify(result)}`);
+          throw mapError(result.error);
         } else {
           throw new Error(`Unknown chunk result ${JSON.stringify(result)}`);
         }
@@ -364,14 +348,18 @@ export class AidaClient {
     }
 
     if (this.#gcaClient.enabled()) {
-      return await this.#gcaClient.completeCode(request);
+      try {
+        return await this.#gcaClient.completeCode(request);
+      } catch (err) {
+        throw mapError(err);
+      }
     }
     const {promise, resolve} = Promise.withResolvers<AidaCodeCompleteResult>();
     InspectorFrontendHostInstance.aidaCodeComplete(JSON.stringify(request), resolve);
     const completeCodeResult = await promise;
 
     if (completeCodeResult.error) {
-      throw new Error(`Cannot send request: ${completeCodeResult.error} ${completeCodeResult.detail || ''}`);
+      throw mapError(completeCodeResult.error, completeCodeResult.detail);
     }
     const response = completeCodeResult.response;
     if (!response?.length) {
@@ -420,18 +408,25 @@ export class AidaClient {
 
     if (this.#gcaClient.enabled()) {
       // Inline and remove the else clause after migration
-      return await this.#gcaClient.generateCode(request, options);
-    }
-    const response = await DispatchHttpRequestClient.makeHttpRequest<GenerateCodeResponse>(
-        {
-          service: SERVICE_NAME,
-          path: '/v1/aida:generateCode',
-          method: 'POST',
-          body: JSON.stringify(request),
-        },
-        options);
+      try {
+        return await this.#gcaClient.generateCode(request, options);
+      } catch (err) {
+        throw mapError(err);
+      }
+    }
+    try {
+      const response = await DispatchHttpRequestClient.makeHttpRequest<GenerateCodeResponse>({
+        service: SERVICE_NAME,
+        path: '/v1/aida:generateCode',
+        method: 'POST',
+        body: JSON.stringify(request),
+      },
+                                                                                             options);
 
-    return response;
+      return response;
+    } catch (err) {
+      throw mapError(err);
+    }
   }
 }
 
@@ -527,10 +522,64 @@ export interface EventTypes {
   [Events.AIDA_AVAILABILITY_CHANGED]: void;
 }
 
-function isQuotaError(...inputs: Array<string|undefined>): boolean {
+export function isQuotaError(...inputs: Array<string|undefined>): boolean {
   return inputs.some(input => input?.toLowerCase().includes('quota'));
 }
 
-function isPayloadTooLargeError(...inputs: Array<string|undefined>): boolean {
+export function isPayloadTooLargeError(...inputs: Array<string|undefined>): boolean {
   return inputs.some(input => input?.toLowerCase().includes('payload size exceeds the limit'));
 }
+
+/**
+ * Maps AIDA-specific errors, DispatchHttpRequestErrors, strings, and generic
+ * Errors to dedicated AidaClientError subclasses.
+ */
+export function mapError(err: unknown, detail?: string): AidaClientError {
+  if (err instanceof AidaClientError) {
+    return err;
+  }
+
+  if (err instanceof DispatchHttpRequestClient.DispatchHttpRequestError) {
+    if (err.type === DispatchHttpRequestClient.ErrorType.ABORT) {
+      return new AidaAbortError();
+    }
+    const response = err.response;
+    if (response) {
+      if (response.statusCode === 429) {
+        return new AidaQuotaError('Server responded: quota exceeded');
+      }
+      if (response.statusCode === 403) {
+        return new AidaPermissionDeniedError('Server responded: permission denied');
+      }
+      if ('netErrorName' in response && response.netErrorName === 'net::ERR_TIMED_OUT') {
+        return new AidaTimeoutError('AIDA request timed out');
+      }
+      if ('error' in response && response.error) {
+        return mapError(response.error, response.detail);
+      }
+      // The dispatcher throws HTTP_RESPONSE_UNAVAILABLE with status code 200
+      // when it successfully receives the HTTP response but fails to parse its JSON body.
+      if (response.statusCode === 200 && err.type === DispatchHttpRequestClient.ErrorType.HTTP_RESPONSE_UNAVAILABLE) {
+        return new AidaInvalidJsonResponseError('Server responded with invalid JSON', {cause: err});
+      }
+      if (response.statusCode !== 200) {
+        return new AidaUnknownError(`Request failed: ${JSON.stringify(response)}`);
+      }
+    }
+  }
+
+  if (typeof err === 'string') {
+    if (isQuotaError(err, detail)) {
+      return new AidaQuotaError(`Cannot send request: ${err}${detail ? ` ${detail}` : ''}`);
+    }
+    if (isPayloadTooLargeError(err, detail)) {
+      return new AidaPayloadTooLargeError(`Cannot send request: ${err}${detail ? ` ${detail}` : ''}`);
+    }
+    return new AidaUnknownError(`Cannot send request: ${err}${detail ? ` ${detail}` : ''}`);
+  }
+
+  if (err instanceof Error) {
+    return new AidaUnknownError(err.message, {cause: err});
+  }
+  return new AidaUnknownError(String(err));
+}