chrome-devtools-frontend 1.0.1717709 → 1.0.1721762

package/.agents/rules/models-and-core/core-ai-agent-context-and-prompt-discipline.md

@@ -0,0 +1,29 @@
+---
+name: devtools/models-and-core/core-ai-agent-context-and-prompt-discipline
+rubric: design
+severity: should_fix
+---
+
+**Rule.** Keep AI agent prompts, tool schemas, and data formatters deterministic, token-efficient, and decoupled from UI and locale state
+- **Look for**: Localized `i18nString` calls or verbose boilerplate prose inside AI data formatters, unsorted flag/property lists in prompt serializers, AI tools missing permission policy declarations, or monolithic trace models passed to response widgets.
+- **Do not flag**: User-facing UI labels rendered in the AI assistance panel chrome rather than sent to the LLM.
+
+**Why.** AI agent data formatters (`models/ai_assistance/data_formatters/`) must produce deterministic, unlocalized, concise text representations decoupled from UI widgets and trace insight models, while tools must declare explicit permission policies and flatten verbose CDP types.
+
+## Examples
+
+Bad:
+
+```ts
+export function formatInsightForPrompt(insight: Insight): string {
+  return `Here is a detailed explanation: ${i18nString(UIStrings.localizedSummary)}`;
+}
+```
+
+Good:
+
+```ts
+export function formatInsightForPrompt(insight: Insight): string {
+  return `metric=${insight.metricValue}ms, savings=${insight.estimatedSavings}ms`;
+}
+```

package/.agents/rules/models-and-core/core-cdp-and-extension-error-handling.md

@@ -0,0 +1,34 @@
+---
+name: devtools/models-and-core/core-cdp-and-extension-error-handling
+rubric: correctness
+severity: blocking
+---
+
+**Rule.** Handle CDP ProtocolResponseWithError and ContentDataOrError explicitly, release RemoteObject handles in finally blocks, and return Promises
+- **Look for**: `try { await ...invoke_*() }` or `try { await request.requestContentData() }` blocks, `Runtime.evaluate` calls creating `RemoteObject`s without `release()` in `finally`, callback-taking SDK methods instead of `Promise`, or `reject(rawObject)` in `ExtensionAPI.ts`.
+- **Do not flag**: `try/catch` blocks that wrap subsequent throwing operations like `JSON.parse()`. Properties marked required (non-optional) in generated `front_end/generated/protocol.ts` CDP types (do not ask for redundant runtime null/undefined checks on them), or `node.shadowRoots()[0]` accesses (elements have at most one shadow root; the array return type is a legacy Shadow DOM v0 artifact).
+
+**Why.** CDP agent calls and `requestContentData()` resolve to error-bearing response objects (`getError()`, `ContentData.isError()`) rather than throwing, so wrapping them in `try/catch` is misleading. Furthermore, temporary `RemoteObject` handles must be released in `finally` blocks, and extension APIs must reject with sanitized `Error` instances.
+
+## Examples
+
+Bad:
+
+```ts
+try {
+  const content = await request.requestContentData();
+  process(content.text);
+} catch (err) {
+  console.error(err);
+}
+```
+
+Good:
+
+```ts
+const contentData = await request.requestContentData();
+if (TextUtils.ContentData.ContentData.isError(contentData)) {
+  return {error: contentData.error};
+}
+process(contentData.text);
+```

package/.agents/rules/models-and-core/core-gn-build-and-module-layering.md

@@ -0,0 +1,23 @@
+---
+name: devtools/models-and-core/core-gn-build-and-module-layering
+rubric: correctness
+severity: blocking
+---
+
+**Rule.** Enforce strict GN bundle visibility, declare complete deps/ts_deps, and never import UI or panel modules from foundation layers
+- **Look for**: Imports of `ui/` or `panels/` inside `core/` or `models/`, `visibility = [ "*" ]` on new panel `BUILD.gn` targets, direct internal file imports across module boundaries instead of `:bundle` namespace imports, or missing `foundation_unittests` entries.
+- **Do not flag**: Core utility libraries intentionally exposed to the entire codebase with `visibility = [ "*" ]`.
+
+**Why.** DevTools enforces a strict DAG where `core/` and `models/` (`foundation`) must never depend on `ui/` or `panels/`. In `BUILD.gn`, modules must depend on `:bundle` targets across directories, register new files in `devtools_grd_files.gni` and `foundation_unittests`, and restrict panel `visibility`.
+
+## Examples
+
+Bad:
+
+```ts
+devtools_entrypoint("bundle") {
+  entrypoint = "my_panel.ts"
+  deps = [ ":my_panel" ]
+  visibility = [ "*" ]
+}
+```

package/.agents/rules/models-and-core/core-runtime-neutrality-and-platform-utils.md

@@ -0,0 +1,28 @@
+---
+name: devtools/models-and-core/core-runtime-neutrality-and-platform-utils
+rubric: correctness
+severity: blocking
+---
+
+**Rule.** Maintain runtime neutrality in foundation modules using Platform.HostRuntime, globalThis, and centralized core/platform utilities
+- **Look for**: `navigator.userAgent`, `window.setTimeout`, `window.atob`, manual `new Promise(r => { resolve = r; })` deferreds instead of `Promise.withResolvers()`, or ad-hoc MIME/escaping regexes in `core/` and `models/`.
+- **Do not flag**: Browser-only UI components in `front_end/panels/` or `front_end/ui/`.
+
+**Why.** Foundation modules (`core/` and `models/`) run in both browser DevTools and headless Node.js/worker environments (such as trace analysis and MCP servers). Accessing `window`, `navigator.userAgent`, or `document` directly breaks non-browser runtimes, and duplicating MIME/string/deferred utilities causes subtle bugs.
+
+## Examples
+
+Bad:
+
+```ts
+const ua = navigator.userAgent;
+let resolve!: () => void;
+const promise = new Promise<void>(r => { resolve = r; });
+```
+
+Good:
+
+```ts
+const ua = Platform.HostRuntime.HOST_RUNTIME.getUserAgent();
+const {promise, resolve} = Promise.withResolvers<void>();
+```

package/.agents/rules/models-and-core/core-sdk-model-and-target-lifecycle.md

@@ -0,0 +1,35 @@
+---
+name: devtools/models-and-core/core-sdk-model-and-target-lifecycle
+rubric: correctness
+severity: blocking
+---
+
+**Rule.** Manage SDK model and sub-target state on scoped manager instances using O(1) indexed maps rather than module globals or linear scans
+- **Look for**: Module-level `const tracked = new Map/Set()` in `core/sdk/` or `models/bindings/`, linear DOM tree traversals for frame/node lookups instead of indexed `Map`s, or target listeners that ignore sub-target attachment/detachment.
+- **Do not flag**: Immutable module-level `Set` or `Map` lookup tables of constant string literals. Properties marked required (non-optional) in generated `front_end/generated/protocol.ts` CDP types (do not ask for redundant runtime null/undefined checks on them), or `node.shadowRoots()[0]` accesses (elements have at most one shadow root; the array return type is a legacy Shadow DOM v0 artifact).
+
+**Why.** Storing model tracking collections (`Set`/`Map`) at module scope leaks state across multiple `TestUniverse` instances and targets, while failing to track OOPIF/worker sub-targets or scanning DOM trees linearly for frame nodes causes bugs and $O(N)$ bottlenecks.
+
+## Examples
+
+Bad:
+
+```ts
+const trackedSourceCodes = new Set<Workspace.UISourceCode.UISourceCode>();
+export class NetworkProjectManager {
+  add(uiSourceCode: Workspace.UISourceCode.UISourceCode) {
+    trackedSourceCodes.add(uiSourceCode);
+  }
+}
+```
+
+Good:
+
+```ts
+export class NetworkProjectManager {
+  readonly #trackedSourceCodes = new Set<Workspace.UISourceCode.UISourceCode>();
+  add(uiSourceCode: Workspace.UISourceCode.UISourceCode): void {
+    this.#trackedSourceCodes.add(uiSourceCode);
+  }
+}
+```

package/.agents/rules/models-and-core/core-security-origin-and-capability-guards.md

@@ -0,0 +1,33 @@
+---
+name: devtools/models-and-core/core-security-origin-and-capability-guards
+rubric: security
+severity: blocking
+---
+
+**Rule.** Enforce security origin validation, enterprise policy guards, and branded UrlString types in the model and host layers
+- **Look for**: Unbranded `string` URLs in model/agent interfaces instead of `Platform.DevToolsPath.UrlString`, security origin checks performed only in UI views, or resource lookup errors returned before permission checks in `ExtensionServer`.
+- **Do not flag**: Internal display-only label strings that are never used for resource resolution or security checks.
+
+**Why.** Security origin checks (SOP), workspace access boundaries, and enterprise/geo-restriction capability checks must be enforced in `core/` and `models/` using `SecurityOrigin`, `Common.ParsedURL`, and `Platform.DevToolsPath.UrlString` rather than relying on UI-layer checks or unvalidated source URLs.
+
+## Examples
+
+Bad:
+
+```ts
+export interface SourceFile {
+  url: string;
+}
+// Derive security origin from untrusted sourceMappingURL comment:
+const origin = Common.ParsedURL.ParsedURL.extractOrigin(script.sourceURL);
+```
+
+Good:
+
+```ts
+export interface SourceFile {
+  url: Platform.DevToolsPath.UrlString;
+}
+// Derive security origin from trusted execution context or frame metadata:
+const origin = script.executionContext()?.securityOrigin;
+```

package/.agents/rules/models-and-core/core-settings-and-storage-migration.md

@@ -0,0 +1,31 @@
+---
+name: devtools/models-and-core/core-settings-and-storage-migration
+rubric: correctness
+severity: blocking
+---
+
+**Rule.** Guard settings and storage migrations with try/catch, preserve user preferences across renames, and clean up obsolete flags
+- **Look for**: Unprotected `JSON.parse()` in `Settings.ts` or storage classes, setting key renames that discard previously stored user preferences, or experiment removals that leave orphaned `localStorage` keys behind.
+- **Do not flag**: In-memory parsing of static constant JSON fixtures.
+
+**Why.** Corrupted `localStorage` payloads or legacy setting schemas can throw during `JSON.parse` and break DevTools startup unless caught and reset. When migrating setting keys or storage formats, existing user selections must be migrated rather than overwritten.
+
+## Examples
+
+Bad:
+
+```ts
+const stored = JSON.parse(setting.get());
+setting.set(defaultConfig); // Overwrites user customization!
+```
+
+Good:
+
+```ts
+try {
+  const stored = JSON.parse(rawSettingValue);
+  migratedSetting.set({...defaultConfig, ...stored});
+} catch {
+  setting.remove();
+}
+```

package/.agents/rules/models-and-core/core-sourcemap-and-workspace-mapping.md

@@ -0,0 +1,28 @@
+---
+name: devtools/models-and-core/core-sourcemap-and-workspace-mapping
+rubric: correctness
+severity: blocking
+---
+
+**Rule.** Handle source map parsing, inline script offset translation, and scope tree resolution fault-tolerantly
+- **Look for**: `window.btoa` on source map strings containing UTF-8, raw script locations passed to source map lookups without `rawLocationToRelativeLocation`, or unguarded `encodeURIComponent` / `JSON.parse` on external source map payloads.
+- **Do not flag**: ASCII-only binary buffer encoding via `Common.Base64.encode`.
+
+**Why.** Real-world source maps and inline `<script>` tags frequently contain malformed fields, UTF-8 characters, or non-zero line/column offsets. Source map consumers must translate raw inline script locations to relative locations, use UTF-8-safe URI encoding (`encodeURIComponent` with `try/catch` instead of `btoa`), and guard scope stack traversals.
+
+## Examples
+
+Bad:
+
+```ts
+const dataUrl = `data:application/json;base64,${btoa(sourceMapJson)}`;
+const entry = sourceMap.findEntry(rawLocation.lineNumber, rawLocation.columnNumber);
+```
+
+Good:
+
+```ts
+const dataUrl = `data:application/json;charset=utf-8,${encodeURIComponent(sourceMapJson)}`;
+const rel = script.rawLocationToRelativeLocation(rawLocation);
+const entry = sourceMap.findEntry(rel.lineNumber, rel.columnNumber);
+```

package/.agents/rules/models-and-core/core-trace-engine-handler-invariants.md

@@ -0,0 +1,32 @@
+---
+name: devtools/models-and-core/core-trace-engine-handler-invariants
+rubric: correctness
+severity: blocking
+---
+
+**Rule.** Normalize and precompute trace events in handler finalize passes using Types.Events.is* guards while keeping raw events immutable
+- **Look for**: In-place property mutation of raw trace events, repeated full-trace `.filter()` scans inside insight calculators instead of handler precomputation, or ad-hoc property checks instead of `Types.Events.is*` (or `Trace.Types.Events.is*`) type guards.
+- **Do not flag**: Constructing new synthetic trace event objects owned by the handler during `finalize()`.
+
+**Why.** Trace handlers (`front_end/models/trace/handlers/`) must normalize synthetic event fields, validate bounds, and group events once during `finalize()` so downstream insights and UI tracks do not repeatedly filter the raw trace array or mutate raw trace event objects.
+
+## Examples
+
+Bad:
+
+```ts
+export function generateInsight(events: readonly Types.Events.Event[]) {
+  for (const event of events) {
+    (event as any).args.normalized = true; // Mutates raw trace event!
+  }
+}
+```
+
+Good:
+
+```ts
+// In handler finalize(): precompute and store in handler state without mutating raw events
+if (Types.Events.isTraceEventNavigationStart(event)) {
+  navigations.push(createSyntheticNavigation(event));
+}
+```

package/.agents/rules/models-and-core/core-trace-insight-models-and-timing-types.md

@@ -0,0 +1,28 @@
+---
+name: devtools/models-and-core/core-trace-insight-models-and-timing-types
+rubric: correctness
+severity: blocking
+---
+
+**Rule.** Enforce branded timing types (Micro, Milli) in trace models and keep types.ts and insight models free of executable or presentation logic
+- **Look for**: Manual `/ 1000` or `* 1000` arithmetic on trace timestamps, executable functions placed in `models/trace/**/types.ts`, or CSS/DOM/AI markdown formatting inside `models/trace/insights/`.
+- **Do not flag**: Type guard functions (`is*`) in `Trace.Types.Events` that only perform type predicate checks.
+
+**Why.** Mixing microseconds and milliseconds causes 1000x calculation bugs across trace insights; branded types (`Types.Timing.Micro`, `Types.Timing.Milli`) and canonical conversion helpers (such as `Trace.Helpers.Timing.microToMilli` or `Platform.Timing.microSecondsToMilliSeconds`) prevent unit confusion. Placing executable functions in `types.ts` or UI/AI formatting in insight models violates trace architecture.
+
+## Examples
+
+Bad:
+
+```ts
+const durationMs = (event.ts + event.dur - startTs) / 1000;
+// Or in models/trace/insights/types.ts:
+export function computeSavings(insight: InsightModel): number { ... }
+```
+
+Good:
+
+```ts
+const durationMs = Trace.Helpers.Timing.microToMilli(
+    Types.Timing.Micro(event.ts + (event.dur ?? 0) - startTs));
+```

package/.agents/rules/tests/test-cleanup-mutated-globals-and-widgets.md

@@ -0,0 +1,40 @@
+---
+name: devtools/tests/test-cleanup-mutated-globals-and-widgets
+rubric: testing
+severity: should_fix
+---
+
+**Rule.** Restore mutated global properties and detach manually instantiated widgets or singletons in afterEach or finally blocks
+- **Look for**: Direct assignments to `window.*`, `globalThis.*`, `Object.prototype.*`, `localStorage.*`, or `panel.show(document.body)` in `.test.ts` files without a matching restoration or `detach()` in `afterEach` or `finally`.
+- **Do not flag**: Widgets mounted directly via `renderElementIntoDOM(widget)`, which detaches widgets automatically during global harness teardown.
+
+**Why.** While Sinon stubs are restored automatically, direct mutations to `window`, `globalThis`, prototypes, or `localStorage`, as well as widgets and panels instantiated with `.markAsRoot()` or `show()`, persist across tests and leak listeners unless explicitly cleaned up in `afterEach` or `try...finally`.
+
+## Examples
+
+Bad:
+
+```ts
+it('handles custom global state', () => {
+  (window as any).customFlag = true;
+  const panel = Panel.instance({forceNew: true});
+  panel.markAsRoot();
+  panel.show(document.body);
+  assert.isTrue(panel.isShowing());
+});
+```
+
+Good:
+
+```ts
+afterEach(() => {
+  delete (window as any).customFlag;
+  panel?.detach();
+});
+it('handles custom global state', () => {
+  (window as any).customFlag = true;
+  panel = Panel.instance({forceNew: true});
+  renderElementIntoDOM(panel);
+  assert.isTrue(panel.isShowing());
+});
+```

package/.agents/rules/tests/test-deterministic-async-synchronization.md

@@ -0,0 +1,30 @@
+---
+name: devtools/tests/test-deterministic-async-synchronization
+rubric: testing
+severity: blocking
+---
+
+**Rule.** Synchronize asynchronous test assertions using lifecycle promises, expectCall, or raf instead of arbitrary setTimeout delays
+- **Look for**: `new Promise(r => setTimeout(r, ...))` in `.test.ts` files, synchronous DOM assertions immediately after `requestUpdate()`, or redundant `clock.tick()` calls when no fake timers are pending.
+- **Do not flag**: Tests specifically verifying debounce/throttle timer expiration using `sinon.useFakeTimers()`.
+
+**Why.** Waiting on wall-clock `setTimeout` delays or arbitrary microtask ticks makes unit tests slow and flaky under CPU contention on CI bots. Tests should await explicit widget update promises (`await widget.updateComplete`), event promises (`target.once(...)`), stub invocation helpers (`expectCall(stub)`), or `raf()`.
+
+## Examples
+
+Bad:
+
+```ts
+widget.data = newData;
+await new Promise(resolve => setTimeout(resolve, 50));
+assert.isTrue(callbackStub.calledOnce);
+```
+
+Good:
+
+```ts
+const called = expectCall(callbackStub);
+widget.data = newData;
+await widget.updateComplete;
+await called;
+```

package/.agents/rules/tests/test-modular-hooks-and-test-universe.md

@@ -0,0 +1,38 @@
+---
+name: devtools/tests/test-modular-hooks-and-test-universe
+rubric: testing
+severity: should_fix
+---
+
+**Rule.** Use lightweight modular setup hooks and TestUniverse instead of heavyweight describeWithEnvironment wrappers
+- **Look for**: `describeWithEnvironment` in unit tests that only need locale, settings, or `TestUniverse`, or suites combining `new TestUniverse()` with `describeWithEnvironment`, or direct mutation of `Root.Runtime.hostConfig` instead of `updateHostConfig(...)`.
+- **Do not flag**: Integration-style panel tests that exercise legacy singleton classes not yet migrated to `Universe` dependency injection. Bot-only CLI flags, credentials, or standalone runner scripts under `test/conductor/` or `test/ai_evals/` that do not run inside the standard Mocha unit test harness.
+
+**Why.** Wrapping unit tests in `describeWithEnvironment` initializes all DevTools global singletons and settings, slowing down tests and hiding implicit global dependencies. Tests should use `TestUniverse` or granular hooks (`setupLocaleHooks()`, `setupSettingsHooks()`, `updateHostConfig()`) and never mix `TestUniverse` with `describeWithEnvironment`.
+
+## Examples
+
+Bad:
+
+```ts
+describeWithEnvironment('MyFormatter', () => {
+  it('formats localized text', () => {
+    const universe = new TestUniverse();
+    Object.assign(Root.Runtime.hostConfig, {devToolsFeature: {enabled: true}});
+    assert.strictEqual(format(), 'Expected');
+  });
+});
+```
+
+Good:
+
+```ts
+describe('MyFormatter', () => {
+  setupLocaleHooks();
+  it('formats localized text', () => {
+    updateHostConfig({devToolsFeature: {enabled: true}});
+    const universe = new TestUniverse();
+    assert.strictEqual(format(universe), 'Expected');
+  });
+});
+```

package/.agents/rules/tests/test-public-api-and-encapsulation.md

@@ -0,0 +1,30 @@
+---
+name: devtools/tests/test-public-api-and-encapsulation
+rubric: testing
+severity: should_fix
+---
+
+**Rule.** Exercise classes through public APIs and constructor-injected dependencies rather than accessing private members or stubbing unused singletons
+- **Look for**: `@ts-expect-error` or `(obj as any).privateMethod()` calls in `.test.ts` files, `sinon.stub(Class, 'instance')` alongside `new UnderTest(mockInstance)`, or `child.shadowRoot.querySelector(...)` inside parent component tests.
+- **Do not flag**: Intentional negative type tests documented with an explanatory `@ts-expect-error` comment.
+
+**Why.** Accessing `#private` or `private` methods via `(instance as any)` or `@ts-expect-error`, piercing child component shadow roots, or stubbing `Class.instance()` when dependencies are already passed via constructor couples tests to internal implementation details.
+
+## Examples
+
+Bad:
+
+```ts
+sinon.stub(Model, 'instance').returns(mockModel);
+const tool = new MyTool(mockModel);
+// @ts-expect-error testing private helper
+assert.isTrue(tool.validateInternal());
+```
+
+Good:
+
+```ts
+const tool = new MyTool(mockModel);
+const result = await tool.execute();
+assert.isTrue(result.isValid);
+```

package/.agents/rules/tests/test-shared-fixture-and-helper-reuse.md

@@ -0,0 +1,29 @@
+---
+name: devtools/tests/test-shared-fixture-and-helper-reuse
+rubric: testing
+severity: should_fix
+---
+
+**Rule.** Reuse canonical front_end/testing helpers and beforeEach setup without mutating cached shared fixtures
+- **Look for**: Custom inline network request or AIDA client mocks in `.test.ts` files, in-place mutation of `parsedTrace` objects returned by `TraceLoader`, or manual `div` container creation around `renderElementIntoDOM(widget)`.
+- **Do not flag**: Specialized test helpers inside `front_end/testing/` that define the canonical factory implementations themselves.
+
+**Why.** Duplicating mock factories (`createTarget`, `createNetworkRequest`, `mockAidaClient`, `cleanTextContent`) or mutating cached objects returned by `TraceLoader` causes cross-test state corruption and maintenance drift across the test suite.
+
+## Examples
+
+Bad:
+
+```ts
+const parsedTrace = await TraceLoader.traceEngine(this, 'web-dev.json.gz');
+(parsedTrace.Meta as any).mainFrameId = 'custom-id'; // Mutates shared cached trace!
+const container = document.createElement('div');
+widget.show(container);
+```
+
+Good:
+
+```ts
+const parsedTrace = await TraceLoader.traceEngine(this, 'web-dev.json.gz');
+renderElementIntoDOM(widget, {includeCommonStyles: true});
+```

package/.agents/rules/tests/test-single-responsibility-and-conciseness.md

@@ -0,0 +1,37 @@
+---
+name: devtools/tests/test-single-responsibility-and-conciseness
+rubric: testing
+severity: should_fix
+---
+
+**Rule.** Keep each it() block focused on a single behavior and prune duplicate or obsolete tests when features change
+- **Look for**: `it('... and ...')` blocks testing multiple orthogonal interactions sequentially, nested `{ ... }` scope blocks inside a single `it()`, or identical test cases duplicated across `describe` blocks.
+- **Do not flag**: Multi-step stateful workflow tests where earlier steps are required preconditions to reach the state under test.
+
+**Why.** Combining multiple independent user interactions or feature scenarios into a single monolithic `it()` block obscures failure root causes, while leaving duplicate or orphaned tests behind increases suite runtime and maintenance burden.
+
+## Examples
+
+Bad:
+
+```ts
+it('toggles setting on/off and expands details card', async () => {
+  toggleSetting();
+  assert.isTrue(setting.get());
+  expandCard();
+  assert.isTrue(card.expanded);
+});
+```
+
+Good:
+
+```ts
+it('toggles setting on and off', () => {
+  toggleSetting();
+  assert.isTrue(setting.get());
+});
+it('expands details card when clicked', () => {
+  expandCard();
+  assert.isTrue(card.expanded);
+});
+```

package/.agents/rules/tests/test-strict-assertions-and-literal-expectations.md

@@ -0,0 +1,31 @@
+---
+name: devtools/tests/test-strict-assertions-and-literal-expectations
+rubric: testing
+severity: blocking
+---
+
+**Rule.** Use strict Chai and Sinon assertions against literal expected values rather than assert.isNotNull on undefined-unions or conditional guards
+- **Look for**: `assert.isNotNull(...)` on `container?.querySelector` / `Map.get` / `Array.find` / optional properties, `if (el) { assert... }` blocks, `assert.isTrue(spy.called)` instead of `sinon.assert.calledWith`, or assertions comparing output against production formatting helpers.
+- **Do not flag**: Variables whose static return type is strictly `T | null` (and never `undefined`).
+
+**Why.** Calling `assert.isNotNull(x)` on a value typed as `T | undefined` passes when `x` is `undefined`, silently skipping assertions. Similarly, wrapping assertions inside `if (el)` or computing expected values by calling the same production helper under test allows broken code to pass.
+
+## Examples
+
+Bad:
+
+```ts
+const item = list.find(x => x.id === 'a');
+assert.isNotNull(item);
+if (item) {
+  assert.strictEqual(item.label, formatLabel('a'));
+}
+```
+
+Good:
+
+```ts
+const item = list.find(x => x.id === 'a');
+assert.isOk(item);
+assert.strictEqual(item.label, 'Expected literal label');
+```

package/.agents/rules/tests/test-type-safe-mocks-and-events.md

@@ -0,0 +1,30 @@
+---
+name: devtools/tests/test-type-safe-mocks-and-events
+rubric: testing
+severity: should_fix
+---
+
+**Rule.** Construct typed stubs and real DOM or event instances instead of casting fake objects with as unknown as
+- **Look for**: `as unknown as` or `as any` casts on mock objects, fake DOM nodes, or synthetic events in `.test.ts` files, or untyped `querySelector(...) as HTMLElement` calls.
+- **Do not flag**: Tests explicitly verifying runtime handling of malformed untrusted payloads or narrow generic type parameters inside shared `front_end/testing/` helpers.
+
+**Why.** Casting partial object literals via `as unknown as T` or `as any` bypasses TypeScript compile-time checks, masks missing methods when interfaces evolve, and causes brittle runtime failures. Using `sinon.createStubInstance(Class)`, real DOM/Event constructors (`DataTransfer`, `ClipboardEvent`), or typed fixture helpers preserves type safety.
+
+## Examples
+
+Bad:
+
+```ts
+const fakeNode = {securityOrigin: () => 'https://example.com'} as unknown as SDK.DOMModel.DOMNode;
+const fakeEvent = {clipboardData: {getData: () => 'text'}} as unknown as ClipboardEvent;
+```
+
+Good:
+
+```ts
+const node = sinon.createStubInstance(SDK.DOMModel.DOMNode);
+node.securityOrigin.returns('https://example.com');
+const dataTransfer = new DataTransfer();
+dataTransfer.setData('text/plain', 'text');
+const event = new ClipboardEvent('paste', {clipboardData: dataTransfer});
+```

package/.agents/rules/tests/test-view-and-presenter-isolation.md

@@ -0,0 +1,32 @@
+---
+name: devtools/tests/test-view-and-presenter-isolation
+rubric: testing
+severity: should_fix
+---
+
+**Rule.** Test presenters via createViewFunctionStub and test pure view functions directly without piercing internal DOM structures
+- **Look for**: Presenter tests instantiating full DOM trees and querying shadow/child DOM selectors to simulate clicks when the widget accepts a `view` function, or view tests instantiating full presenters just to test template markup.
+- **Do not flag**: Legacy widgets that have not yet separated their template rendering into a standalone `DEFAULT_VIEW` function.
+
+**Why.** In DevTools' MVP (`UI.Widget` + `DEFAULT_VIEW`) architecture, presenter tests should follow the view stubbing conventions documented in [`docs/ui_engineering.md`](../../../docs/ui_engineering.md) by stubbing the view function with `createViewFunctionStub(Presenter)` and asserting on `await view.nextInput`, while view rendering tests should invoke `DEFAULT_VIEW(input, output, target)` directly or use screenshot assertions.
+
+## Examples
+
+Bad:
+
+```ts
+const widget = new MyWidget();
+renderElementIntoDOM(widget);
+widget.contentElement.querySelector('devtools-button')!.click();
+assert.include(widget.contentElement.textContent, 'Updated');
+```
+
+Good:
+
+```ts
+const view = createViewFunctionStub(MyWidget);
+const widget = new MyWidget(undefined, view);
+widget.wasShown();
+view.input.onActionClick();
+assert.strictEqual((await view.nextInput).statusText, 'Updated');
+```

package/.agents/rules/ui-and-widgets/ui-accessibility-and-semantic-html.md

@@ -0,0 +1,32 @@
+---
+name: devtools/ui-and-widgets/ui-accessibility-and-semantic-html
+rubric: design
+severity: should_fix
+---
+
+**Rule.** Use native semantic HTML controls with accurate ARIA attributes, keyboard handlers, and !event.isComposing guards
+- **Look for**: `@click` on `<div>`/`<span>` without button semantics, `<button>` nested inside `<button>`/`<x-link>`, `Enter` keydown handlers missing `!event.isComposing`, or `aria-describedby` pointing to interactive `<devtools-tooltip>` elements.
+- **Do not flag**: Delegating click listeners on container elements that handle bubbled events from child buttons.
+
+**Why.** Clickable `<div>`/`<span>` elements and nested interactive controls (`<button>` inside `<a>` or `<button>`) break keyboard navigation and screen readers. Interactive elements require semantic tags (`<button>`, `<details>`/`<summary>`, `<thead>`/`<tbody>`), synchronized ARIA state (`aria-expanded`, `aria-details` for rich tooltips vs `aria-describedby` for plain text), and `!event.isComposing` checks on `Enter` keydown handlers.
+
+## Examples
+
+Bad:
+
+```ts
+html`
+  <div class="custom-btn" @click=${onSubmit}>Submit</div>
+  <textarea @keydown=${(e: KeyboardEvent) => e.key === 'Enter' && onSubmit()}></textarea>
+`
+```
+
+Good:
+
+```ts
+html`
+  <devtools-button @click=${onSubmit}>Submit</devtools-button>
+  <textarea aria-label=${i18nString(UIStrings.prompt)}
+    @keydown=${(e: KeyboardEvent) => e.key === 'Enter' && !e.isComposing && onSubmit()}></textarea>
+`
+```