Sync fork with chromium/7827

Author: huntie

.agents/OWNERS

@@ -0,0 +1 @@
+file://config/owner/COMMON_OWNERS

.agents/README.md

@@ -0,0 +1,13 @@
+# .agents
+
+This directory contains workspace-specific agent expertise and skills.
+
+## Skills
+
+Workspace skills are located in `.agents/skills/`. These represent on-demand expertise that the AI agent can activate to complete specialized tasks.
+
+To use a skill, the agent will autonomously identify it based on its description and pull in the instructions using the `activate_skill` tool.
+
+## Contributing
+
+Contributions to existing skills or adding new ones are encouraged via CLs.

.agents/skills/creating-a-model/SKILL.md

@@ -0,0 +1,57 @@
+```
+---
+name: devtools-model-management
+description: Guidelines for creating, migrating, and registering models in front_end/models/. Covers BUILD.gn, devtools_grd_files.gni, and entrypoints.
+---
+
+# 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.

.agents/skills/devtools-imports/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: devtools-imports
+description: Conventions for importing code in Devtools to avoid build errors. Covers cross-module imports, internal imports, and the "import * as" requirement.
+---
+
+# Imports
+
+This codebase follows a special convention for importing code that must be followed to avoid build errors.
+
+In DevTools each folder of code is considered a *module*:
+
+- `front_end/models/trace` is the *trace module*.
+- `front_end/panels/timeline` is the *timeline module*.
+
+Within each module there are multiple TypeScript files. *The file that is named the same as the folder name is called the entrypoint*.
+
+- `front_end/models/trace/trace.ts` is the *trace module's entrypoint*
+- `front_end/models/trace/ModelImpl.ts` is part of the implementation of the trace module.
+
+## Importing from another module
+
+When you want to reuse code from other modules, *you must import that module via its entrypoint*. Imagine we are in `front_end/panels/timeline/TimelinePanel.ts`. This import is GOOD:
+
+```ts
+import * as Trace from '../models/trace/trace.js'; // import the entrypoint
+```
+
+This import is BAD because we import a file that is NOT the entrypoint:
+
+```ts
+import * as ModelImpl from '../models/trace/ModelImpl.js' // NEVER ALLOWED
+```
+
+Additionally, you **must import using the `import * as` syntax**.
+
+```ts
+import {ModelImpl, X, Y} from '../models/trace/trace.js'; // BAD
+```
+
+```ts
+import * as Trace from '../models/trace/trace.js'; // GOOD
+```
+
+## Importing from within the same module
+
+If you are within the same module, it is OK to import from files directly rather than go via the entrypoint. You can also import specifically what you need.
+
+For example, if you are editing `front_end/models/trace/ModelImpl.ts` this would be acceptable:
+
+```ts
+import {Foo} from './Foo.js'; // allowed because Foo.ts is in the same directory.
+```

.agents/skills/foundation-test-migration/SKILL.md

@@ -0,0 +1,171 @@
+---
+name: foundation-test-migration
+description: Migrating unit tests to foundation unit tests using TestUniverse and devtools_foundation_module. Use when moving tests away from DOM-heavy helpers like describeWithEnvironment or describeWithMockConnection.
+---
+
+# Foundation Test Migration
+
+This skill provides guidance on migrating DevTools unit tests to the "foundation" pattern, which is lighter, avoids global singletons, and is compatible with both Node and Browser runtimes (Isomorphic).
+
+## Core Concepts
+
+### devtools_foundation_module (BUILD.gn)
+Use this template for modules that should be platform-agnostic.
+- **Enforcement**: It type-checks the code against both Browser and Node APIs.
+- **Constraint**: Avoid direct DOM access (like `FileReader` or layout metrics) or heavy DevTools dependencies. Use `Universe` to access services.
+
+### TestUniverse
+`TestUniverse` is the preferred way to setup a DevTools-like environment for tests without global singletons.
+- **Lazy**: Dependencies (targetManager, settings, workspace, etc.) are only created when accessed via getters.
+- **Scoped**: Does not install instances as globals (avoids `Common.Settings.Settings.instance()`).
+- **Explicit**: Uses `DevToolsContext` to manage dependencies.
+
+## Migration Guide
+
+### 1. Replace Heavy Helpers
+Avoid `describeWithEnvironment` or `describeWithMockConnection`.
+
+Instead, use standard `describe` and initialize environment hooks at the top-level `describe` block. **Crucial:** Without `setupRuntimeHooks`, tests creating SDK models will crash due to uninitialized experiments (e.g. `capture-node-creation-stacks`).
+
+```ts
+import {setupLocaleHooks} from '../../testing/LocaleHelpers.js';
+import {setupSettingsHooks} from '../../testing/SettingsHelpers.js';
+import {setupRuntimeHooks} from '../../testing/RuntimeHelpers.js';
+import {TestUniverse} from '../../testing/TestUniverse.js';
+
+describe('MyComponent', () => {
+  setupLocaleHooks();
+  setupSettingsHooks();
+  setupRuntimeHooks();
+
+  let universe: TestUniverse;
+
+  beforeEach(() => {
+    universe = new TestUniverse();
+  });
+});
+```
+
+### 2. Access Dependencies via Universe
+Instead of using `SDK.TargetManager.TargetManager.instance()`, use `universe.targetManager`. Use `universe.createTarget()` instead of the global `createTarget`.
+
+```ts
+// OLD
+const target = createTarget();
+const targetManager = SDK.TargetManager.TargetManager.instance();
+
+// NEW
+const target = universe.createTarget({url: urlString`http://example.com/`});
+const targetManager = universe.targetManager;
+```
+
+#### Mocking CDP Traffic
+If the test used `describeWithMockConnection` and global `setMockConnectionResponseHandler` to stub CDP traffic, you can migrate this by passing a `MockCDPConnection` to `universe.createTarget()`. This allows stubbing out CDP traffic scoped to a specific target tree rather than globally.
+
+```ts
+import {MockCDPConnection} from '../../testing/MockCDPConnection.js';
+
+const cdpConnection = new MockCDPConnection([
+  {
+    method: 'Network.getResponseBody',
+    response: () => ({body: 'mocked body', base64Encoded: false}),
+  }
+]);
+
+const target = universe.createTarget({connection: cdpConnection});
+```
+
+> [!TIP]
+> **Legacy Target URLs**: `EnvironmentHelpers.createTarget()` defaults to `http://example.com/`. `TestUniverse.createTarget()` defaults to `about:blank`. If your test asserts against specific URLs, remember to pass the URL explicitly.
+
+### 3. Dealing with Legacy Singletons & Helpers
+
+For large integration tests, you may encounter code that strictly calls `SomeModule.instance()` or uses complex legacy helpers (like `createWorkspaceProject`).
+
+**Do not use `setUpEnvironment()`** as it will create disconnected singletons. Instead, wire the singletons to your `TestUniverse` and stub the globals to bridge legacy helpers:
+
+```ts
+beforeEach(async () => {
+  universe = new TestUniverse();
+  const {targetManager, workspace, settings} = universe;
+
+  // 1. Stub globals so legacy helpers use TestUniverse components
+  sinon.stub(Workspace.Workspace.WorkspaceImpl, 'instance').returns(workspace);
+  sinon.stub(SDK.TargetManager.TargetManager, 'instance').returns(targetManager);
+  sinon.stub(Common.Settings.Settings, 'instance').returns(settings);
+
+  // 2. Initialize interdependent singletons in the correct order
+  SDK.NetworkManager.MultitargetNetworkManager.instance({forceNew: true, targetManager});
+
+  // 3. Now safe to use legacy helpers that rely on the above instances
+  await createWorkspaceProject(urlString`file:///path/to/overrides`, [...]);
+});
+```
+
+## Pitfalls & Troubleshooting
+
+### Strict Equality in Protocol Responses (`assert.deepEqual`)
+Protocol requests/responses dynamically generated by Chrome (like Network conditions) can vary slightly (e.g., adding `connectionType`, `urlPattern`).
+- **Problem**: `assert.deepEqual(rules, [{...}])` will flake if unrequested fields are present.
+- **Solution**: Use `sinon.spy()` for handlers and assert with `sinon.assert.calledOnceWithMatch`:
+
+```ts
+const emulateSpy = sinon.spy();
+connection.setHandler('Network.emulateNetworkConditionsByRule', request => {
+  emulateSpy(request);
+  return {result: {ruleIds: []}};
+});
+
+// Matches only the fields you care about, ignoring extra protocol fields
+sinon.assert.calledOnceWithMatch(emulateSpy, {
+  offline: false,
+  matchedNetworkConditions: [sinon.match({ downloadThroughput: 1000 })],
+});
+```
+
+### DOM Globals (`ReferenceError: FileReader is not defined`)
+Foundation tests run in Node.js where `window`, `FileReader`, and certain DOM string encodings don't exist.
+- **Fix**: Use isomorphic equivalents (e.g. `btoa()`, `Uint8Array`).
+- **Fix**: Abstract the APIs that are different between Node.js and Browser via `front_end/core/platform/api/HostRuntime.ts`.
+
+### Initialization Order Lockups
+If a test times out (5000ms exceeded), it is usually an unhandled promise caused by a missing singleton. Double-check the constructor of the failing manager to see which `instance()` it listens to, and ensure that dependent singleton was created *first*.
+
+## BUILD.gn Changes
+
+When a module and its tests are ready, update `BUILD.gn`:
+
+1.  Change `devtools_module` to `devtools_foundation_module` for both the module and its unittests.
+2.  Ensure the tests are grouped under a `foundation_unittests` target in the parent `BUILD.gn`.
+
+```gn
+# front_end/my_module/BUILD.gn
+
+devtools_foundation_module("my_module") {
+  sources = [ "MyModule.ts" ]
+  deps = [ "../../core/common:bundle" ]
+}
+
+devtools_foundation_module("unittests") {
+  testonly = true
+  sources = [ "MyModule.test.ts" ]
+  deps = [
+    ":my_module",
+    "../../testing",
+  ]
+}
+```
+
+## Verification
+
+Foundation tests must pass in both Node.js and Browser runtimes.
+
+### Run in Node.js
+```bash
+npm test -- front_end/core/sdk/NetworkManager.test.ts --node-unit-tests
+```
+
+### Run in Browser
+```bash
+npm test -- front_end/core/sdk/NetworkManager.test.ts
+```