chrome-devtools-frontend 1.0.1717709 → 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.
 
 ---

package/.agents/skills/review-models-core/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: review-models-core
+description: >-
+  Reviews Chrome DevTools frontend changes in path group models-and-core (^front_end/(core|models|entrypoints|generated)/, BUILD\.gn$, \.gni$),
+  strictly reflecting review standards, architectural invariants, and security boundaries
+  derived from historical code reviews.
+---
+
+# Chrome DevTools frontend reviewer skill: models-and-core
+
+This skill provides review guidance for Chrome DevTools frontend changes matching the `models-and-core` path group (^front_end/(core|models|entrypoints|generated)/, BUILD\.gn$, \.gni$). Every rule below recurred in at least 5 CLs from 2 distinct reviewers in historical reviews; cite the rule id in findings.
+
+## Path group `models-and-core` (10 rules)
+
+### `CORE_TRACE_ENGINE_HANDLER_INVARIANTS`: Normalize and precompute trace events in handler finalize passes using Types.Events.is* guards while keeping raw events immutable
+- **Severity**: ERROR
+- **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.
+- **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()`.
+
+### `CORE_SDK_MODEL_AND_TARGET_LIFECYCLE`: Manage SDK model and sub-target state on scoped manager instances using O(1) indexed maps rather than module globals or linear scans
+- **Severity**: ERROR
+- **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.
+- **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).
+
+### `CORE_GN_BUILD_AND_MODULE_LAYERING`: Enforce strict GN bundle visibility, declare complete deps/ts_deps, and never import UI or panel modules from foundation layers
+- **Severity**: ERROR
+- **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`.
+- **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 = [ "*" ]`.
+
+### `CORE_AI_AGENT_CONTEXT_AND_PROMPT_DISCIPLINE`: Keep AI agent prompts, tool schemas, and data formatters deterministic, token-efficient, and decoupled from UI and locale state
+- **Severity**: WARNING
+- **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.
+- **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.
+
+### `CORE_RUNTIME_NEUTRALITY_AND_PLATFORM_UTILS`: Maintain runtime neutrality in foundation modules using Platform.HostRuntime, globalThis, and centralized core/platform utilities
+- **Severity**: ERROR
+- **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.
+- **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/`.
+
+### `CORE_CDP_AND_EXTENSION_ERROR_HANDLING`: Handle CDP ProtocolResponseWithError and ContentDataOrError explicitly, release RemoteObject handles in finally blocks, and return Promises
+- **Severity**: ERROR
+- **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.
+- **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).
+
+### `CORE_SECURITY_ORIGIN_AND_CAPABILITY_GUARDS`: Enforce security origin validation, enterprise policy guards, and branded UrlString types in the model and host layers
+- **Severity**: ERROR
+- **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.
+- **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.
+
+### `CORE_SOURCEMAP_AND_WORKSPACE_MAPPING`: Handle source map parsing, inline script offset translation, and scope tree resolution fault-tolerantly
+- **Severity**: ERROR
+- **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.
+- **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`.
+
+### `CORE_SETTINGS_AND_STORAGE_MIGRATION`: Guard settings and storage migrations with try/catch, preserve user preferences across renames, and clean up obsolete flags
+- **Severity**: ERROR
+- **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.
+- **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.
+
+### `CORE_TRACE_INSIGHT_MODELS_AND_TIMING_TYPES`: Enforce branded timing types (Micro, Milli) in trace models and keep types.ts and insight models free of executable or presentation logic
+- **Severity**: ERROR
+- **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.
+- **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.