chrome-devtools-frontend 1.0.1717196 → 1.0.1721762

package/.agents/rules/ui-and-widgets/ui-await-update-complete-post-render.md

@@ -0,0 +1,30 @@
+---
+name: devtools/ui-and-widgets/ui-await-update-complete-post-render
+rubric: correctness
+severity: blocking
+---
+
+**Rule.** Await this.updateComplete before executing post-render DOM measurements, focus changes, or scroll adjustments
+- **Look for**: `this.requestUpdate()` followed synchronously by `.focus()`, `.getBoundingClientRect()`, `.scrollIntoView()`, or child widget measurement without `await this.updateComplete`.
+- **Do not flag**: State updates that do not interact with rendered DOM nodes after scheduling the update.
+
+**Why.** Because `this.requestUpdate()` schedules rendering asynchronously in a microtask, querying DOM geometry, focusing newly rendered controls, or anchoring popovers immediately after `requestUpdate()` operates on stale pre-render DOM state.
+
+## Examples
+
+Bad:
+
+```ts
+this.#isEditing = true;
+this.requestUpdate();
+this.#focusEditorInput();
+```
+
+Good:
+
+```ts
+this.#isEditing = true;
+this.requestUpdate();
+await this.updateComplete;
+this.#focusEditorInput();
+```

package/.agents/rules/ui-and-widgets/ui-css-scoping-and-flex-layout.md

@@ -0,0 +1,27 @@
+---
+name: devtools/ui-and-widgets/ui-css-scoping-and-flex-layout
+rubric: readability
+severity: nit
+---
+
+**Rule.** Scope light-DOM stylesheets and align elements using flexbox or grid rather than competing margin and position offsets
+- **Look for**: Unscoped generic selectors in light-DOM `.css` files (or `:host` inside `@scope` blocks instead of `:scope`), or CSS rules combining `vertical-align`, negative `margin-top`, and pixel offsets to center icons and buttons.
+- **Do not flag**: Shadow DOM component stylesheets where `:host` scoping is native.
+
+**Why.** Unscoped class or tag selectors in light-DOM widget stylesheets leak across the DevTools document, while combining `vertical-align`, negative margins, and `position: relative` offsets creates brittle layouts that break under font scaling or zoom.
+
+## Examples
+
+Bad:
+
+```ts
+@scope to (devtools-widget > *) {
+  :host { display: block; }
+  .action-icon {
+    vertical-align: middle;
+    margin-top: -2px;
+    position: relative;
+    bottom: 1px;
+  }
+}
+```

package/.agents/rules/ui-and-widgets/ui-declarative-child-widget-composition.md

@@ -0,0 +1,29 @@
+---
+name: devtools/ui-and-widgets/ui-declarative-child-widget-composition
+rubric: design
+severity: should_fix
+---
+
+**Rule.** Compose child UI.Widget instances declaratively in Lit templates using the widget() directive instead of imperative show() calls
+- **Look for**: `new ChildWidget()` followed by `.show(...)` or `.appendChild(child.element)` inside Lit view functions or migrated `performUpdate()` methods instead of `<devtools-widget ${widget(ChildWidget, {...})}></devtools-widget>` (or `${widget(ChildWidget, {...})}`).
+- **Do not flag**: Top-level legacy split widgets or tabbed panes that have not migrated to Lit views.
+
+**Why.** Imperatively instantiating child widgets and calling `child.show(container)` inside presenters or views bypasses Lit reconciliation, complicates lifecycle management, and recreates widgets unnecessarily across renders.
+
+## Examples
+
+Bad:
+
+```ts
+const child = new DetailsWidget();
+child.data = input.data;
+child.show(target.querySelector('.container')!);
+```
+
+Good:
+
+```ts
+Lit.render(html`
+  <devtools-widget ${UI.Widget.widget(DetailsWidget, {data: input.data})}></devtools-widget>
+`, target);
+```

package/.agents/rules/ui-and-widgets/ui-lit-declarative-templates-and-directives.md

@@ -0,0 +1,33 @@
+---
+name: devtools/ui-and-widgets/ui-lit-declarative-templates-and-directives
+rubric: design
+severity: should_fix
+---
+
+**Rule.** Use Lit.nothing, repeat with keys, classMap/styleMap, and ifDefined in single-pass declarative templates instead of imperative DOM mutations
+- **Look for**: Ternary branches returning `''` or `undefined` in `html` templates instead of `Lit.nothing`, unkeyed `.map()` on dynamic stateful lists instead of `repeat()`, `ifDefined` omissions on optional attributes, or multiple `Lit.render()` calls mutating the same container.
+- **Do not flag**: Static arrays of primitive labels where item identity never reorders.
+
+**Why.** Mutating DOM elements via `appendChild`, `classList.toggle`, or `innerHTML` alongside Lit templates, or returning `''`/`null` instead of `Lit.nothing` in conditional branches, corrupts Lit's part tracking and creates unnecessary text nodes or wrapper `<div>`s.
+
+## Examples
+
+Bad:
+
+```ts
+html`
+  <div class="item ${isActive ? 'active' : ''}" title=${ maybeTitle || '' }>
+    ${showIcon ? html`<devtools-icon name="info"></devtools-icon>` : ''}
+  </div>
+`
+```
+
+Good:
+
+```ts
+html`
+  <div class=${classMap({item: true, active: isActive})} title=${ifDefined(maybeTitle)}>
+    ${showIcon ? html`<devtools-icon name="info"></devtools-icon>` : Lit.nothing}
+  </div>
+`
+```

package/.agents/rules/ui-and-widgets/ui-localization-and-uistrings-hygiene.md

@@ -0,0 +1,36 @@
+---
+name: devtools/ui-and-widgets/ui-localization-and-uistrings-hygiene
+rubric: design
+severity: should_fix
+---
+
+**Rule.** Define user-facing strings in sentence-case UIStrings using complete sentences and i18nTemplate for embedded elements, and prune unused entries
+- **Look for**: String concatenation around `i18nString(...)`, HTML/DOM elements interpolated without `i18nTemplate`, Title Case labels in `UIStrings`, unlocalized English literals in templates, or unused keys in `UIStrings`.
+- **Do not flag**: Technical protocol identifiers, MIME types, or strings in `UIStringsNotTranslate` / `i18n.i18n.lockedString(...)`.
+
+**Why.** Concatenating translated fragments breaks word order in non-English locales, title-Cased strings violate Chromium UX standards, translating English-only experimental strings wastes localization quota, and unused `UIStrings` entries bloat locale bundles.
+
+## Examples
+
+Bad:
+
+```ts
+const UIStrings = {
+  learnMoreAbout: 'Learn More About ', // Title case + fragmented sentence
+  unusedKey: 'Old label',
+} as const;
+html`${i18nString(UIStrings.learnMoreAbout)}<x-link href=${url}>CORS</x-link>`
+```
+
+Good:
+
+```ts
+const UIStrings = {
+  /**
+   * @description Link text explaining CORS errors.
+   * @example {CORS} PH1
+   */
+  learnMoreAbout: 'Learn more about {PH1}',
+} as const;
+html`${i18nTemplate(UIStrings.learnMoreAbout, {PH1: html`<x-link href=${url}>CORS</x-link>`})}`
+```

package/.agents/rules/ui-and-widgets/ui-modern-component-and-encapsulation-standards.md

@@ -0,0 +1,32 @@
+---
+name: devtools/ui-and-widgets/ui-modern-component-and-encapsulation-standards
+rubric: design
+severity: should_fix
+---
+
+**Rule.** Use modern DevTools UI primitives (`devtools-button`, `devtools-data-grid`, `devtools-icon`), #private fields, and module entrypoint imports
+- **Look for**: `UI.Fragment.build`, legacy `DataGridImpl`, `extends LitElement`, `private ` keyword instead of `#` in new UI classes, or `<devtools-*>` tags in Lit templates without importing the corresponding component module entrypoint (e.g. `import * as Buttons from '../../ui/components/buttons/buttons.js'`).
+- **Do not flag**: Overriding inherited `protected` lifecycle methods on framework base classes (e.g. extending `UI.Widget.Widget`).
+
+**Why.** Legacy `UI.Fragment`, `DataGridImpl`, `LitElement`, `new Icon()`, and TypeScript `private` fields are superseded by standard `<devtools-*>` custom elements (imported via module entrypoints such as `import * as Buttons from '../../ui/components/buttons/buttons.js'` so custom tags register at runtime) and ECMAScript `#private` fields.
+
+## Examples
+
+Bad:
+
+```ts
+import type * as Buttons from '../../ui/components/buttons/buttons.js';
+export class MyView extends UI.Widget.VBox {
+  private grid = new DataGrid.DataGrid.DataGridImpl({...});
+}
+```
+
+Good:
+
+```ts
+import * as Buttons from '../../ui/components/buttons/buttons.js';
+import * as DataGrid from '../../ui/legacy/components/data_grid/data_grid.js';
+export class MyView extends UI.Widget.VBox {
+  #items: Item[] = [];
+}
+```

package/.agents/rules/ui-and-widgets/ui-panel-and-meta-registration.md

@@ -0,0 +1,35 @@
+---
+name: devtools/ui-and-widgets/ui-panel-and-meta-registration
+rubric: design
+severity: should_fix
+---
+
+**Rule.** Follow DevTools panel directory conventions and register settings and views in the appropriate *-meta.ts scope
+- **Look for**: Panel-level `UI.Widget` views placed inside `panels/<panel>/components/`, internal state flags registered with user-facing titles in `*-meta.ts`, or `loadView` callbacks calling `.instance()` instead of using the passed `Universe` context.
+- **Do not flag**: Standalone reusable leaf components inside `components/` or genuine user-configurable preferences.
+
+**Why.** Panel-level `UI.Widget` views belong directly under `front_end/panels/<panel>/` (reserving `components/` for reusable leaf components), internal non-user-facing settings must use `SettingCategory.NONE` or model descriptors rather than appearing in Settings UI, and shared SDK settings belong in `sdk-meta.ts`.
+
+## Examples
+
+Bad:
+
+```ts
+Common.Settings.registerSettingExtension({
+  settingName: 'has-shown-internal-onboarding',
+  settingType: Common.Settings.SettingType.BOOLEAN,
+  defaultValue: false,
+  title: () => i18nString(UIStrings.onboardingShown),
+});
+```
+
+Good:
+
+```ts
+Common.Settings.registerSettingExtension({
+  category: Common.Settings.SettingCategory.NONE,
+  settingName: 'has-shown-internal-onboarding',
+  settingType: Common.Settings.SettingType.BOOLEAN,
+  defaultValue: false,
+});
+```

package/.agents/rules/ui-and-widgets/ui-performance-and-flamechart-rendering.md

@@ -0,0 +1,34 @@
+---
+name: devtools/ui-and-widgets/ui-performance-and-flamechart-rendering
+rubric: design
+severity: should_fix
+---
+
+**Rule.** Precompute expensive metrics outside render loops, use Set/Map for O(1) lookups, and debounce high-frequency UI updates
+- **Look for**: `.includes()` / `.find()` / `.sort()` inside canvas draw or event iteration loops, repeated `ResizeObserver` registrations on individual child items instead of the parent container, or un-debounced filter/mutation handlers.
+- **Do not flag**: One-time initialization passes over bounded small arrays (less than 20 items).
+
+**Why.** Performing linear `Array.includes`/`find` scans, sorting, or regex parsing inside FlameChart canvas draw loops, `ElementsTreeOutline` mutation callbacks, or Lit render passes causes frame drops and UI jank on large traces and DOM trees.
+
+## Examples
+
+Bad:
+
+```ts
+for (const entry of traceEntries) {
+  if (allowedTypesArray.includes(entry.name) && Root.Runtime.experiments.isEnabled('exp')) {
+    drawEntry(entry);
+  }
+}
+```
+
+Good:
+
+```ts
+const isExpEnabled = Root.Runtime.experiments.isEnabled('exp');
+for (const entry of traceEntries) {
+  if (isExpEnabled && ALLOWED_TYPES_SET.has(entry.name)) {
+    drawEntry(entry);
+  }
+}
+```

package/.agents/rules/ui-and-widgets/ui-pure-view-and-presenter-separation.md

@@ -0,0 +1,31 @@
+---
+name: devtools/ui-and-widgets/ui-pure-view-and-presenter-separation
+rubric: design
+severity: should_fix
+---
+
+**Rule.** Keep UI.Widget view functions pure and stateless by computing presentation data in presenters and passing decoupled ViewInput data structures
+- **Look for**: `DEFAULT_VIEW` or view helper functions calling `Common.Settings.Settings.instance()`, `SDK.*`, `Host.*`, mutating `input.*` arrays in place, or accepting raw `SDK`/`Protocol` domain objects instead of decoupled presentation interfaces on `ViewInput`.
+- **Do not flag**: Legacy `UI.Widget` subclasses that have not yet migrated to a `DEFAULT_VIEW` function.
+
+**Why.** In DevTools' MVP architecture, `DEFAULT_VIEW` functions must be pure projections of `ViewInput` to Lit templates. Querying SDK models, reading global settings, mutating presenter state, or calling host/clipboard APIs inside the view couples rendering to global state and breaks isolated view testing.
+
+## Examples
+
+Bad:
+
+```ts
+export const DEFAULT_VIEW = (input: ViewInput, _output: ViewOutput, target: HTMLElement): void => {
+  const showAdvanced = Common.Settings.Settings.instance().moduleSetting('show-advanced').get();
+  const sorted = input.items.sort((a, b) => a.name.localeCompare(b.name));
+  Lit.render(html`...`, target);
+};
+```
+
+Good:
+
+```ts
+export const DEFAULT_VIEW = (input: ViewInput, _output: ViewOutput, target: HTMLElement): void => {
+  Lit.render(html`${input.sortedItems.map(item => html`<div>${item.name}</div>`)}`, target);
+};
+```

package/.agents/rules/ui-and-widgets/ui-reactive-widget-update-lifecycle.md

@@ -0,0 +1,34 @@
+---
+name: devtools/ui-and-widgets/ui-reactive-widget-update-lifecycle
+rubric: design
+severity: should_fix
+---
+
+**Rule.** Schedule widget re-renders asynchronously via this.requestUpdate() and guard property setters with equality checks
+- **Look for**: Widget property setters calling `this.performUpdate()` or `this.#view(...)` directly, or setters calling `this.requestUpdate()` without checking `if (this.#prop === value) return;`.
+- **Do not flag**: Internal test helpers or synchronous initialization paths explicitly documented as requiring immediate flush.
+
+**Why.** Calling `this.performUpdate()` or invoking `this.#view(...)` synchronously inside property setters causes redundant synchronous DOM renders when multiple properties change in the same tick. Setters should short-circuit if the value is unchanged and call `this.requestUpdate()`.
+
+## Examples
+
+Bad:
+
+```ts
+set items(items: Item[]) {
+  this.#items = items;
+  this.performUpdate();
+}
+```
+
+Good:
+
+```ts
+set items(items: Item[]) {
+  if (this.#items === items) {
+    return;
+  }
+  this.#items = items;
+  this.requestUpdate();
+}
+```

package/.agents/rules/ui-and-widgets/ui-security-and-output-sanitization.md

@@ -0,0 +1,28 @@
+---
+name: devtools/ui-and-widgets/ui-security-and-output-sanitization
+rubric: security
+severity: blocking
+---
+
+**Rule.** Sanitize untrusted strings, URLs, CSS selectors, and Markdown exports before rendering or exporting
+- **Look for**: Raw string interpolation in `querySelector('[attr="' + val + '"]')` without `CSS.escape`, `href` attribute bindings with unvalidated `javascript:` URLs, Markdown table cell serialization without escaping `|*_<>\`, or raw HTML snippet generation without HTML escaping.
+- **Do not flag**: Standard Lit `html` text bindings (`${text}`), which escape HTML entities automatically.
+
+**Why.** Interpolating untrusted network URLs, DOM attributes, or user strings into raw HTML snippets, `CSS.escape`-free attribute selectors, Markdown table exports, or `href` attributes without protocol validation risks injection, XSS, broken layout formatting, or text spoofing.
+
+## Examples
+
+Bad:
+
+```ts
+const el = root.querySelector(`[data-key="${dynamicKey}"]`);
+const markdownRow = `| ${cell.name} | ${cell.value} |`;
+```
+
+Good:
+
+```ts
+const el = root.querySelector(`[data-key="${CSS.escape(dynamicKey)}"]`);
+const escapeMd = (s: string) => s.replace(/[*_|<>]/g, '\\$&');
+const markdownRow = `| ${escapeMd(cell.name)} | ${escapeMd(cell.value)} |`;
+```

package/.agents/rules/ui-and-widgets/ui-type-safety-and-exhaustiveness.md

@@ -0,0 +1,37 @@
+---
+name: devtools/ui-and-widgets/ui-type-safety-and-exhaustiveness
+rubric: design
+severity: should_fix
+---
+
+**Rule.** Model multi-state UI workflows with discriminated unions, Platform.assertNever exhaustiveness checks, and strict domain types
+- **Look for**: `switch` statements over union/enum types missing `Platform.assertNever(x)` in `default:`, `any` or `declare` field modifiers in UI classes, or multiple boolean flags (`isLoading`, `isError`, `isEmpty`) representing mutually exclusive states.
+- **Do not flag**: Switch statements that intentionally handle only a small subset of a large external protocol enum.
+
+**Why.** Representing mutually exclusive UI states with loose optional boolean flags or `any` types permits impossible states and silently misses new enum variants. Discriminated unions paired with `Platform.assertNever` in `default:` branches enforce compile-time exhaustiveness.
+
+## Examples
+
+Bad:
+
+```ts
+switch (state.type) {
+  case StateType.LOADING:
+    return renderLoading();
+  case StateType.LOADED:
+    return renderData(state.data);
+}
+```
+
+Good:
+
+```ts
+switch (state.type) {
+  case StateType.LOADING:
+    return renderLoading();
+  case StateType.LOADED:
+    return renderData(state.data);
+  default:
+    Platform.assertNever(state, `Unhandled state: ${JSON.stringify(state)}`);
+}
+```

package/.agents/rules/ui-and-widgets/ui-view-output-and-callback-contracts.md

@@ -0,0 +1,35 @@
+---
+name: devtools/ui-and-widgets/ui-view-output-and-callback-contracts
+rubric: design
+severity: should_fix
+---
+
+**Rule.** Encapsulate imperative DOM actions in ViewOutput callbacks and pass user actions via semantic ViewInput callbacks instead of raw DOM references
+- **Look for**: `ViewOutput` interfaces containing `HTMLElement` or `Element` properties, or `ViewInput` callbacks typed as `(event: Event) => void` instead of semantic domain values.
+- **Do not flag**: Third-party editor or canvas host containers that require a raw mount `HTMLElement`.
+
+**Why.** Exposing raw `HTMLElement` references on `ViewOutput` or passing raw `MouseEvent`/`KeyboardEvent` objects to presenter callbacks leaks DOM details into presenters. Views should populate narrow functional closures on `ViewOutput` (e.g. `output.focusInput = () => ...`) and unpack event values before calling `input.onSelect(value)`.
+
+## Examples
+
+Bad:
+
+```ts
+export interface ViewOutput {
+  inputElement?: HTMLInputElement;
+}
+export interface ViewInput {
+  onInputChange: (event: Event) => void;
+}
+```
+
+Good:
+
+```ts
+export interface ViewOutput {
+  focusInput?: () => void;
+}
+export interface ViewInput {
+  onFilterChanged: (newFilterText: string) => void;
+}
+```

package/.agents/rules/ui-and-widgets/ui-visual-logging-instrumentation.md

@@ -0,0 +1,29 @@
+---
+name: devtools/ui-and-widgets/ui-visual-logging-instrumentation
+rubric: design
+severity: should_fix
+---
+
+**Rule.** Instrument interactive UI elements and containers with kebab-case VisualLogging contexts registered in KnownContextValues
+- **Look for**: Interactive elements (`<button>`, `<devtools-button>`, `<input>`, menus, drawers) missing `jslog` or `jslogContext`, non-kebab-case context names, or new context values missing from `KnownContextValues.ts`.
+- **Do not flag**: Purely decorative icons or internal wrapper `<div>`s that represent neither a distinct visual section nor an interactive control.
+
+**Why.** DevTools relies on Visual Elements (`jslog`) telemetry to measure feature usage. Omitting `jslog` on new buttons/toggles/menus, using localized or camelCase context strings, adding redundant panel prefixes inside already-logged containers, or dropping `jslog` during Lit refactors breaks analytics.
+
+## Examples
+
+Bad:
+
+```ts
+html`<button @click=${input.onToggle}>${input.label}</button>`
+// Or using localized string as context:
+jslog=${VisualLogging.action(i18nString(UIStrings.clearAll)).track({click: true})}
+```
+
+Good:
+
+```ts
+html`<devtools-button
+  .jslogContext=${'clear-all'}
+  @click=${input.onClear}>${i18nString(UIStrings.clearAll)}</devtools-button>`
+```

package/.agents/rules/ui-and-widgets/ui-weak-dom-references-and-observer-cleanup.md

@@ -0,0 +1,29 @@
+---
+name: devtools/ui-and-widgets/ui-weak-dom-references-and-observer-cleanup
+rubric: design
+severity: should_fix
+---
+
+**Rule.** Store DOM node metadata in WeakMap or WeakRef collections and clean up observers when elements detach
+- **Look for**: Strong `Map<Element, ...>` / `Set<Element>` collections holding DOM/model associations, `WeakMap` values retaining strong references back to their DOM keys, `ResizeObserver`/`IntersectionObserver` without `.unobserve()`/`.disconnect()` on teardown, or `ref(el => ...)` callbacks that do not handle `el === undefined`.
+- **Do not flag**: Module-level `WeakMap<Element, ...>` globals whose values do not strongly reference the key, or short-lived local maps created and discarded within a single synchronous function call.
+
+**Why.** Retaining DOM `Element` or `SDK.Target` references in strong `Map`/`Set` collections (or in `WeakMap` values that hold strong references back to their keys) prevents detached DOM trees from being garbage-collected, while leaving `ResizeObserver`, `MutationObserver`, or `Lit.Directives.ref` callbacks active after unmount leaks memory.
+
+## Examples
+
+Bad:
+
+```ts
+const elementState = new Map<HTMLElement, State>();
+// Or in Lit template:
+html`<div ${ref(el => { this.#el = el as HTMLElement; })}></div>`
+```
+
+Good:
+
+```ts
+readonly #elementState = new WeakMap<HTMLElement, State>();
+// In Lit template, handle undefined when element detaches:
+html`<div ${ref(el => { this.#el = el instanceof HTMLElement ? el : undefined; })}></div>`
+```

package/.agents/rules/ui-and-widgets/ui-widget-dom-and-listener-lifecycle.md

@@ -0,0 +1,38 @@
+---
+name: devtools/ui-and-widgets/ui-widget-dom-and-listener-lifecycle
+rubric: correctness
+severity: blocking
+---
+
+**Rule.** Attach listeners to external models and managers in wasShown and detach them symmetrically in willHide
+- **Look for**: `addEventListener`, `addModelListener`, or `addChangeListener` on singletons, models, or settings inside `UI.Widget` constructors or `wasShown()` without a matching `remove*` call in `willHide()` using the same function reference.
+- **Do not flag**: Listeners attached to the widget's own internal DOM elements (`this.contentElement`), which are garbage-collected together with the widget.
+
+**Why.** Subscribing to long-lived SDK `TargetManager`, `Settings`, or model events in a widget's constructor without unsubscribing in `willHide()` (or `onDetach()` / `onunbind()`) causes hidden panels to process background updates and leaks detached widget instances.
+
+## Examples
+
+Bad:
+
+```ts
+constructor() {
+  super();
+  SDK.TargetManager.TargetManager.instance().addModelListener(
+      SDK.DOMModel.DOMModel, SDK.DOMModel.Events.DocumentUpdated, this.#onUpdate, this);
+}
+```
+
+Good:
+
+```ts
+override wasShown(): void {
+  super.wasShown();
+  SDK.TargetManager.TargetManager.instance().addModelListener(
+      SDK.DOMModel.DOMModel, SDK.DOMModel.Events.DocumentUpdated, this.#onUpdate, this);
+}
+override willHide(): void {
+  super.willHide();
+  SDK.TargetManager.TargetManager.instance().removeModelListener(
+      SDK.DOMModel.DOMModel, SDK.DOMModel.Events.DocumentUpdated, this.#onUpdate, this);
+}
+```

package/.agents/skills/code-review/SKILL.md

@@ -34,14 +34,17 @@ Load the skill that matches what the diff touches, and apply its rules:
 | :--- | :--- |
 | Any `import` statement, or a new cross-module dependency | `devtools-imports` |
 | `UI.Widget`, lit-html views, components, CSS | `ui-widgets` |
+| Reviewing UI and widgets (`front_end/(panels|ui)/**/*.{ts,css}`) | `review-ui-widgets` |
 | Migration of legacy imperative DOM to widgets or Lit | `ui-eng-vision-orchestrator` (and its sub-skills) |
 | New or changed tests: choosing unit, API, or E2E | `devtools-testing-guidance` |
+| Reviewing tests (`*.test.ts`, `test/**`, `front_end/testing/**`) | `review-tests` |
 | Tests that use `describeWithEnvironment` or `describeWithMockConnection`, or foundation modules | `foundation-test-migration` |
 | Ported Chromium web tests (`web_tests/http/tests/devtools`) | `migrate-chromium-test` |
 | Flaky or disabled tests, or `it.skip` / `it.skipOnPlatforms` | `fix-tests` |
 | `UIStrings` / user-facing text | `devtools-ux-writing-refactor` |
 | Rendering user-controlled strings (URLs, names, console text) | `devtools-unicode-escaping` |
 | `front_end/models/*`, `BUILD.gn`, `devtools_grd_files.gni`, entrypoints | `devtools-model-management` |
+| Reviewing foundation, models, and build configs (`front_end/(core|models|entrypoints|generated)/**`, `BUILD.gn`, `*.gni`) | `review-models-core` |
 | Merging modules or consolidating `BUILD.gn` | `merging-devtools-module` |
 | `Settings` registrations and descriptors | `devtools-setting-migration` |
 | Stack traces, source maps, `DebuggerWorkspaceBinding` | `devtools-source-maps` |

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`).
+- **Test functions:** import `describe`, `it`, `beforeEach`, etc. from `mocha` (e.g. `import {describe, it} from 'mocha';`). They are not available as globals.
 - **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.
 
 ---
@@ -37,7 +38,8 @@ Use API tests for integration tests that verify business logic requiring more co
   - 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.
+- **Test functions:** import `describe`, `it` and `setup` from `test/api/mocha-interface.ts`. They are not available as globals.
+- **BUILD.gn**: test file should be added to `devtools_api_test_module("api_tests")` target in the corresponding `BUILD.gn` file, which needs `test/api` in its `ts_deps`.
 
 ---
 
@@ -49,4 +51,5 @@ 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.
+- **Test functions:** import `describe`, `it` and `setup` from `test/e2e/conductor/mocha-interface.ts` (e.g. `import {describe, it} from '../conductor/mocha-interface.js';`). They are not available as globals.
+- **BUILD.gn**: test file should be added to the `node_ts_library` target in the corresponding `BUILD.gn` file, which needs `"../conductor:implementation"` in its `ts_deps`. And `node_ts_library` in `test/e2e/BUILD.gn` for its dependencies.