chrome-devtools-frontend 1.0.1717709 → 1.0.1721762

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

@@ -0,0 +1,67 @@
+---
+name: review-tests
+description: >-
+  Reviews Chrome DevTools frontend changes in target directories (\.test\.ts$, ^test/, ^front_end/testing/),
+  strictly reflecting review standards, architectural invariants, and security boundaries
+  derived from historical code reviews.
+---
+
+# Chrome DevTools frontend reviewer skill: tests
+
+This skill provides review guidance for Chrome DevTools frontend changes matching the target directories (\.test\.ts$, ^test/, ^front_end/testing/). It focuses specifically on code review verification for test changes, complementing authoring guidance in `devtools-testing-guidance` and integrating with the general review checklist in `code-review`. Every rule below recurred in at least 5 CLs from 2 distinct reviewers in historical reviews; cite the rule id in findings.
+
+## Path group `tests` (9 rules)
+
+### `TEST_SHARED_FIXTURE_AND_HELPER_REUSE`: Reuse canonical front_end/testing helpers and beforeEach setup without mutating cached shared fixtures
+- **Severity**: WARNING
+- **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.
+- **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.
+
+### `TEST_MODULAR_HOOKS_AND_TEST_UNIVERSE`: Use lightweight modular setup hooks and TestUniverse instead of heavyweight describeWithEnvironment wrappers
+- **Severity**: WARNING
+- **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`.
+- **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.
+
+### `TEST_DETERMINISTIC_ASYNC_SYNCHRONIZATION`: Synchronize asynchronous test assertions using lifecycle promises, expectCall, or raf instead of arbitrary setTimeout delays
+- **Severity**: ERROR
+- **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()`.
+- **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()`.
+
+### `TEST_STRICT_ASSERTIONS_AND_LITERAL_EXPECTATIONS`: Use strict Chai and Sinon assertions against literal expected values rather than assert.isNotNull on undefined-unions or conditional guards
+- **Severity**: ERROR
+- **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.
+- **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`).
+
+### `TEST_VIEW_AND_PRESENTER_ISOLATION`: Test presenters via createViewFunctionStub and test pure view functions directly without piercing internal DOM structures
+- **Severity**: WARNING
+- **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.
+- **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.
+
+### `TEST_PUBLIC_API_AND_ENCAPSULATION`: Exercise classes through public APIs and constructor-injected dependencies rather than accessing private members or stubbing unused singletons
+- **Severity**: WARNING
+- **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.
+- **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.
+
+### `TEST_SINGLE_RESPONSIBILITY_AND_CONCISENESS`: Keep each it() block focused on a single behavior and prune duplicate or obsolete tests when features change
+- **Severity**: WARNING
+- **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.
+- **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.
+
+### `TEST_TYPE_SAFE_MOCKS_AND_EVENTS`: Construct typed stubs and real DOM or event instances instead of casting fake objects with as unknown as
+- **Severity**: WARNING
+- **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.
+- **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.
+
+### `TEST_CLEANUP_MUTATED_GLOBALS_AND_WIDGETS`: Restore mutated global properties and detach manually instantiated widgets or singletons in afterEach or finally blocks
+- **Severity**: WARNING
+- **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`.
+- **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.

package/.agents/skills/review-ui-widgets/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: review-ui-widgets
+description: >-
+  Reviews Chrome DevTools frontend changes in path group ui-and-widgets (^front_end/(ui|panels)/.*\.(ts|css)$),
+  strictly reflecting review standards, architectural invariants, and security boundaries
+  derived from historical code reviews.
+---
+
+# Chrome DevTools frontend reviewer skill: ui-and-widgets
+
+This skill provides review guidance for Chrome DevTools frontend changes matching the `ui-and-widgets` path group (^front_end/(ui|panels)/.*\.(ts|css)$). It focuses specifically on code review verification for UI and widget changes, complementing authoring guidance in `ui-widgets` and [`docs/ui_engineering.md`](../../../docs/ui_engineering.md), and integrating with the general review checklist in `code-review`. Every rule below recurred in at least 5 CLs from 2 distinct reviewers in historical reviews; cite the rule id in findings.
+
+## Path group `ui-and-widgets` (17 rules)
+
+### `UI_MODERN_COMPONENT_AND_ENCAPSULATION_STANDARDS`: Use modern DevTools UI primitives (`devtools-button`, `devtools-data-grid`, `devtools-icon`), #private fields, and module entrypoint imports
+- **Severity**: WARNING
+- **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.
+- **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`).
+
+### `UI_TYPE_SAFETY_AND_EXHAUSTIVENESS`: Model multi-state UI workflows with discriminated unions, Platform.assertNever exhaustiveness checks, and strict domain types
+- **Severity**: WARNING
+- **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.
+- **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.
+
+### `UI_PURE_VIEW_AND_PRESENTER_SEPARATION`: Keep UI.Widget view functions pure and stateless by computing presentation data in presenters, passing decoupled ViewInput data structures, and preserving helper topology
+- **Severity**: WARNING
+- **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. Additionally, deleting existing standalone/module-level DOM helper functions or async class update helpers and inlining them into `performUpdate()` or `DEFAULT_VIEW` during Lit migrations unnecessarily flattens the abstraction topology and inflates diffs.
+- **Look for**: `DEFAULT_VIEW` or view helper functions calling `Common.Settings.Settings.instance()`, `SDK.*`, `Host.*`, mutating `input.*` arrays in place, accepting raw `SDK`/`Protocol` domain objects instead of decoupled presentation interfaces on `ViewInput`, or Lit migrations that delete existing standalone/class DOM helper functions and inline their logic into `performUpdate()` or `DEFAULT_VIEW` instead of converting them in place to return `LitTemplate` (or `Promise<LitTemplate|null>`).
+- **Do not flag**: Legacy `UI.Widget` subclasses that have not yet migrated to a `DEFAULT_VIEW` function.
+
+### `UI_LIT_DECLARATIVE_TEMPLATES_AND_DIRECTIVES`: Use Lit.nothing, repeat with keys, classMap/styleMap, and ifDefined in declarative templates while preserving modular helper functions
+- **Severity**: WARNING
+- **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. Conversely, collapsing existing standalone DOM helper functions (e.g., `linkifyIcon`, `maybeCreateLinkToElementsPanel`) or class rendering helpers into a single monolithic `DEFAULT_VIEW` template harms readability and reviewability compared to converting those helpers in place to return `LitTemplate`.
+- **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, multiple `Lit.render()` calls mutating the same container, or Lit migrations that flatten/inline existing DOM helper functions and class helper methods instead of preserving them in their original locations returning `LitTemplate`.
+- **Do not flag**: Static arrays of primitive labels where item identity never reorders.
+
+### `UI_WIDGET_DOM_AND_LISTENER_LIFECYCLE`: Attach listeners to external models and managers in wasShown and detach them symmetrically in willHide
+- **Severity**: ERROR
+- **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.
+- **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.
+
+### `UI_ACCESSIBILITY_AND_SEMANTIC_HTML`: Use native semantic HTML controls with accurate ARIA attributes, keyboard handlers, and !event.isComposing guards
+- **Severity**: WARNING
+- **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.
+- **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.
+
+### `UI_PERFORMANCE_AND_FLAMECHART_RENDERING`: Precompute expensive metrics outside render loops, use Set/Map for O(1) lookups, and debounce high-frequency UI updates
+- **Severity**: WARNING
+- **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.
+- **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).
+
+### `UI_LOCALIZATION_AND_UISTRINGS_HYGIENE`: Define user-facing strings in sentence-case UIStrings using complete sentences and i18nTemplate for embedded elements, and prune unused entries
+- **Severity**: WARNING
+- **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.
+- **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(...)`.
+
+### `UI_REACTIVE_WIDGET_UPDATE_LIFECYCLE`: Schedule widget re-renders asynchronously via this.requestUpdate() and guard property setters with equality checks
+- **Severity**: WARNING
+- **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()`.
+- **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.
+
+### `UI_VISUAL_LOGGING_INSTRUMENTATION`: Instrument interactive UI elements and containers with kebab-case VisualLogging contexts registered in KnownContextValues
+- **Severity**: WARNING
+- **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.
+- **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.
+
+### `UI_CSS_SCOPING_AND_FLEX_LAYOUT`: Scope light-DOM stylesheets and align elements using flexbox or grid rather than competing margin and position offsets
+- **Severity**: INFO
+- **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.
+- **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.
+
+### `UI_VIEW_OUTPUT_AND_CALLBACK_CONTRACTS`: Encapsulate imperative DOM actions in ViewOutput callbacks and pass user actions via semantic ViewInput callbacks instead of raw DOM references
+- **Severity**: WARNING
+- **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)`.
+- **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`.
+
+### `UI_PANEL_AND_META_REGISTRATION`: Follow DevTools panel directory conventions and register settings and views in the appropriate *-meta.ts scope
+- **Severity**: WARNING
+- **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`.
+- **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.
+
+### `UI_WEAK_DOM_REFERENCES_AND_OBSERVER_CLEANUP`: Store DOM node metadata in WeakMap or WeakRef collections and clean up observers when elements detach
+- **Severity**: WARNING
+- **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.
+- **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.
+
+### `UI_SECURITY_AND_OUTPUT_SANITIZATION`: Sanitize untrusted strings, URLs, CSS selectors, and Markdown exports before rendering or exporting
+- **Severity**: ERROR
+- **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.
+- **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.
+
+### `UI_DECLARATIVE_CHILD_WIDGET_COMPOSITION`: Compose child UI.Widget instances declaratively in Lit templates using the two-argument widget(ChildWidget, {...}) directive instead of imperative show() calls or single-argument factory callbacks
+- **Severity**: WARNING
+- **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. Similarly, single-argument factory callbacks `widget(element => ...)` only run on initial creation and fail to propagate updated properties on subsequent re-renders; strongly prefer the two-argument `widget(ChildWidget, {...})` form (converting `setFoo()` methods on the child widget into `set foo()` setters if needed).
+- **Look for**: `new ChildWidget()` followed by `.show(...)` or `.appendChild(child.element)` inside Lit view functions or migrated `performUpdate()` methods, or `widget(element => ...)` factory callbacks configuring child widget properties imperatively 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.
+
+### `UI_AWAIT_UPDATE_COMPLETE_POST_RENDER`: Await this.updateComplete before executing post-render DOM measurements, focus changes, or scroll adjustments
+- **Severity**: ERROR
+- **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.
+- **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.

package/.agents/skills/ui-eng-vision-local-lit-renderer/SKILL.md

@@ -18,6 +18,11 @@ existing element containers.
 
     *   Maintain the existing class hierarchy, helper class boundaries, and
         logical groups.
+    *   Preserve existing standalone/module-level DOM helper functions (e.g.,
+        `linkifyIcon`, `maybeCreateLinkToElementsPanel`) and class helper
+        methods in their original locations, converting DOM-returning helpers in
+        place to return `LitTemplate` (or `Promise<LitTemplate|null>`) rather
+        than deleting and inlining them into `performUpdate()` or `DEFAULT_VIEW`.
     *   Do not aggressively "flatten" classes or collapse helper abstractions
         into the main view just to coerce a single master template. Pass 2
         should only change the *implementation details* of rendering (imperative
@@ -119,9 +124,20 @@ existing element containers.
     *   The Gerrit Code Review UI cannot identify moved blocks of unchanged code.
     *   If blocks of code need to be reordered, create a "prefactoring" change that first extracts the code that needs to be reordered into a named helper functions and pause the migration, waiting user confirmation.
 
-12. **Embedding Pre-Existing `UI.Widget` Instances via `UI.Widget.WrapperWidget`**:
-
-    *   Use `${widget(UI.Widget.WrapperWidget, {widget: input.childWidget})}` when
+12. **Composing Child `UI.Widget`s & Pre-Existing Instances**:
+
+    *   **Strongly Prefer Two-Argument `widget(ChildWidgetClass, {params})`**:
+        When instantiating child widgets in a Lit template, strongly prefer the
+        two-argument form `widget(ChildWidgetClass, {propA: input.a, propB: input.b})`
+        over the single-argument factory `widget(element => new ChildWidgetClass(element))`.
+        The two-argument form automatically propagates updated parameters and
+        schedules `requestUpdate()` on re-renders, whereas a factory callback only
+        runs once on initial creation. If the child widget currently uses
+        `setFoo()` methods instead of setters, convert them into `set foo()`
+        setters on the child widget so you can use the two-argument `widget()`
+        directive.
+    *   **Pre-Existing Widget Instances (`UI.Widget.WrapperWidget`)**: Use
+        `${widget(UI.Widget.WrapperWidget, {widget: input.childWidget})}` when
         embedding widgets owned by `UI.ViewManager`
         (`TabbedViewLocation.tabbedPane()`, `StackLocation.widget()`) or when
         conditionally moving a shared widget instance between containers

package/.agents/skills/ui-eng-vision-widget-promoter/SKILL.md

@@ -73,6 +73,7 @@ clean `UI.Widget` classes that use native update rendering delegates.
         html`<devtools-widget ${widget(MyWidgetClass, {params})}></devtools-widget>`
         ```
 
+    *   **Strongly prefer the two-argument `widget(MyWidgetClass, {params})` form** over the single-argument factory callback `widget(element => new MyWidgetClass(element, ...))`. The single-argument factory only runs on initial creation and does not update properties on subsequent re-renders. If the child widget only exposes `setFoo(...)` methods, convert them into `set foo(...)` setters so they can be passed via the second argument of `widget()`.
     *   Inspect instantiator files (e.g., `ApplicationPanelSidebar.ts`) and
         decouple any direct accesses to `.element`.
 
@@ -81,7 +82,7 @@ clean `UI.Widget` classes that use native update rendering delegates.
 ## 2. Safety & Verification Rules
 
 *   **CRITICAL**: Never update screenshot goldens without explicit consent of the user. Most likely the failure points to an issue in the implementation or (less likely) the test itself. Look at the screenshot diffs to debug.
-*   **Minimal Code Movement**: When migrating, try to move code around as little as possible, in particular around the lit rendering helpers. This minimizes the git diff and improves reviewability.
+*   **Minimal Code Movement & Helper Topology**: When migrating, try to move code around as little as possible, in particular around the lit rendering helpers. Preserve existing standalone/module-level DOM helper functions (e.g., `linkifyIcon`, `maybeCreateLinkToElementsPanel`) and async class update helpers in their original locations, having DOM helpers return `LitTemplate` (or `Promise<LitTemplate|null>`) rather than deleting and inlining them into `performUpdate()` or `DEFAULT_VIEW`. This minimizes the git diff and improves reviewability.
 
 --------------------------------------------------------------------------------
 

package/.agents/skills/ui-widgets/SKILL.md

@@ -59,8 +59,10 @@ const DEFAULT_VIEW = (input: ViewInput, output: ViewOutput, target: HTMLElement)
 ### Composition
 
 * To render a child widget, the parent's View MUST use the lit-html directive `UI.Widget.widget`.
+* **Strongly prefer the two-argument `widget(WidgetClass, {params})` form** over the single-argument factory callback `widget(element => new WidgetClass(element, ...))`. The two-argument form automatically updates properties and calls `requestUpdate()` on subsequent renders, whereas a factory callback only runs once on initial instantiation.
+* If a child widget currently exposes imperative setter methods (e.g., `setStorageKey(key)` or `setStorageBucket(bucket)`) instead of public properties/setters, convert them into standard TypeScript setters (`set storageKey(key)`, `set storageBucket(bucket)`) on the child widget so it can be instantiated and updated declaratively via the two-argument `widget(WidgetClass, {params})` directive.
 * Configuration is passed via the parameters.
-* Properties passed from a parent MUST be declared as public fields on the child presenter class.
+* Properties passed from a parent MUST be declared as public fields or setters on the child presenter class.
 * The framework automatically updates these properties and calls `requestUpdate()` on the child when the parent re-renders.
 * **Pre-existing Widget Instances (`WrapperWidget`):** To render an existing `UI.Widget` instance (such as locations created by `UI.ViewManager`: `TabbedViewLocation.tabbedPane()`, `StackLocation.widget()`) declaratively without creating a custom wrapper class, use `${widget(UI.Widget.WrapperWidget, {widget: myWidgetInstance})}`. `WrapperWidget` automatically forwards constraints, handles attach/detach lifecycle, and supports dynamic widget replacement.
 

package/AUTHORS

@@ -35,6 +35,7 @@ Conner Turner <cturner@zyme.xyz>
 Daniel bellfield <dnlbellfield@gmail.com>
 Danny Eldridge <me@heardanieljames.com>
 Derek Li <the.derekli@gmail.com>
+DevTools AIRC Bot <devtools-airc-bot@mths-airc-433412.iam.gserviceaccount.com>
 Dmitry Kryaklin <dmkryak@gmail.com>
 Douglas Chiang <douglasdothnc@gmail.com>
 Dragonish <no.web.developer@outlook.com>
@@ -85,6 +86,7 @@ Muhammad Mahad <mahadtxt@gmail.com>
 Naoto Ono <onoto1998@gmail.com>
 Navoda Munasinha <navoda.munasinha@codimite.com>
 Nourhan Hasan <nourhan.m.hasan@gmail.com>
+Omar Ramadan <omar@blockcast.net>
 Paras Awasthi <awasthiparas6@gmail.com>
 Paul Fisher <paul@pfish.zone>
 Peng Zhou <zhoupeng.1996@bytedance.com>
@@ -111,6 +113,7 @@ Simon Siefke <simon.siefke@gmail.com>
 Stephen Tsoi-A-Sue <stsoiasue@gmail.com>
 Steve Harrison <steve@steveharrison.dev>
 Sunnylost <sunnylost@gmail.com>
+Sutthinon <mankhong.garden@gmail.com>
 Suyoung Jung <tdhitbtd@gmail.com>
 TaegeonKim <aksen5240@gmail.com>
 Thomas Stokes <git@tombl.dev>

package/DIR_METADATA

@@ -17,6 +17,26 @@ agentic_review: {
       ".agents/skills/devtools-ux-writing-refactor/SKILL.md"
     ]
   }
+  capability_groups: {
+    path_expression: [
+      "front_end/(core|models|entrypoints|generated)/.*\\.ts",
+      ".*BUILD\\.gn",
+      ".*\\.gni"
+    ]
+    path_expression_exclusion: [".*\\.test\\.ts"]
+    rules: [
+      ".agents/rules/models-and-core/core-trace-engine-handler-invariants.md",
+      ".agents/rules/models-and-core/core-sdk-model-and-target-lifecycle.md",
+      ".agents/rules/models-and-core/core-gn-build-and-module-layering.md",
+      ".agents/rules/models-and-core/core-ai-agent-context-and-prompt-discipline.md",
+      ".agents/rules/models-and-core/core-runtime-neutrality-and-platform-utils.md",
+      ".agents/rules/models-and-core/core-cdp-and-extension-error-handling.md",
+      ".agents/rules/models-and-core/core-security-origin-and-capability-guards.md",
+      ".agents/rules/models-and-core/core-sourcemap-and-workspace-mapping.md",
+      ".agents/rules/models-and-core/core-settings-and-storage-migration.md",
+      ".agents/rules/models-and-core/core-trace-insight-models-and-timing-types.md"
+    ]
+  }
   capability_groups: {
     path_expression: ["front_end/(panels|ui)/.*\\.(ts|css)"]
     path_expression_exclusion: [".*\\.test\\.ts"]
@@ -24,13 +44,43 @@ agentic_review: {
       ".agents/skills/ui-widgets/SKILL.md",
       ".agents/skills/ui-eng-vision-orchestrator/SKILL.md"
     ]
+    rules: [
+      ".agents/rules/ui-and-widgets/ui-modern-component-and-encapsulation-standards.md",
+      ".agents/rules/ui-and-widgets/ui-type-safety-and-exhaustiveness.md",
+      ".agents/rules/ui-and-widgets/ui-pure-view-and-presenter-separation.md",
+      ".agents/rules/ui-and-widgets/ui-lit-declarative-templates-and-directives.md",
+      ".agents/rules/ui-and-widgets/ui-widget-dom-and-listener-lifecycle.md",
+      ".agents/rules/ui-and-widgets/ui-accessibility-and-semantic-html.md",
+      ".agents/rules/ui-and-widgets/ui-performance-and-flamechart-rendering.md",
+      ".agents/rules/ui-and-widgets/ui-localization-and-uistrings-hygiene.md",
+      ".agents/rules/ui-and-widgets/ui-reactive-widget-update-lifecycle.md",
+      ".agents/rules/ui-and-widgets/ui-visual-logging-instrumentation.md",
+      ".agents/rules/ui-and-widgets/ui-css-scoping-and-flex-layout.md",
+      ".agents/rules/ui-and-widgets/ui-view-output-and-callback-contracts.md",
+      ".agents/rules/ui-and-widgets/ui-panel-and-meta-registration.md",
+      ".agents/rules/ui-and-widgets/ui-weak-dom-references-and-observer-cleanup.md",
+      ".agents/rules/ui-and-widgets/ui-security-and-output-sanitization.md",
+      ".agents/rules/ui-and-widgets/ui-declarative-child-widget-composition.md",
+      ".agents/rules/ui-and-widgets/ui-await-update-complete-post-render.md"
+    ]
   }
   capability_groups: {
-    path_expression: [".*\\.test\\.ts", "test/.*\\.ts"]
+    path_expression: [".*\\.test\\.ts", "test/.*\\.ts", "front_end/testing/.*\\.ts"]
     review_capability_skills: [
       ".agents/skills/devtools-testing-guidance/SKILL.md",
       ".agents/skills/foundation-test-migration/SKILL.md",
       ".agents/skills/fix-tests/SKILL.md"
     ]
+    rules: [
+      ".agents/rules/tests/test-shared-fixture-and-helper-reuse.md",
+      ".agents/rules/tests/test-modular-hooks-and-test-universe.md",
+      ".agents/rules/tests/test-deterministic-async-synchronization.md",
+      ".agents/rules/tests/test-strict-assertions-and-literal-expectations.md",
+      ".agents/rules/tests/test-view-and-presenter-isolation.md",
+      ".agents/rules/tests/test-public-api-and-encapsulation.md",
+      ".agents/rules/tests/test-single-responsibility-and-conciseness.md",
+      ".agents/rules/tests/test-type-safe-mocks-and-events.md",
+      ".agents/rules/tests/test-cleanup-mutated-globals-and-widgets.md"
+    ]
   }
 }

package/eslint.config.mjs

@@ -267,8 +267,7 @@ export default defineConfig([
         'error',
         {
           selector: 'ExportDefaultDeclaration',
-          message:
-            'Default exports are not allowed. Use named exports instead.',
+          message: 'Default exports are not allowed. Use named exports instead.',
         },
       ],
       /**
@@ -309,8 +308,8 @@ export default defineConfig([
         'error',
         {
           definedTags: [
-            'attribute', // @attribute is used by lit-analyzer (through web-component-analyzer)
-            'meaning', // @meaning is used by localization
+            'attribute',  // @attribute is used by lit-analyzer (through web-component-analyzer)
+            'meaning',    // @meaning is used by localization
           ],
         },
       ],
@@ -341,11 +340,11 @@ export default defineConfig([
       parserOptions: {
         allowAutomaticSingleRunInference: true,
         project: join(
-          import.meta.dirname,
-          'config',
-          'typescript',
-          'tsconfig.eslint.json',
-        ),
+            import.meta.dirname,
+            'config',
+            'typescript',
+            'tsconfig.eslint.json',
+            ),
       },
     },
 
@@ -588,12 +587,12 @@ export default defineConfig([
         {
           // Enforce that any import of models/trace/trace.js names the import Trace.
           modulePath: join(
-            import.meta.dirname,
-            'front_end',
-            'models',
-            'trace',
-            'trace.js',
-          ),
+              import.meta.dirname,
+              'front_end',
+              'models',
+              'trace',
+              'trace.js',
+              ),
           importName: 'Trace',
         },
       ],
@@ -668,6 +667,8 @@ export default defineConfig([
       ],
       '@devtools/static-custom-event-names': 'error',
       '@devtools/lit-no-attribute-quotes': 'error',
+      '@devtools/lit-no-non-latin1': 'error',
+      '@devtools/no-boolean-input-checked-attr': 'error',
       '@devtools/lit-template-result-or-nothing': 'error',
       '@devtools/inject-checkbox-styles': 'error',
       '@devtools/jslog-context-list': 'error',
@@ -792,6 +793,7 @@ export default defineConfig([
       '@devtools/prefer-url-string': 'error',
       '@devtools/trace-engine-test-timeouts': 'error',
       '@devtools/no-document-body-mutation': 'error',
+      '@devtools/no-manual-sinon-restore': 'error',
       // Don't update the KnownContext with test data.
       '@devtools/jslog-context-list': 'off',
       '@devtools/enforce-custom-element-definitions-location': 'off',
@@ -821,10 +823,16 @@ export default defineConfig([
   {
     name: 'Use private class members rule',
     files: [
+      'front_end/core/**/*.ts',
+      'front_end/models/**/*.ts',
       'front_end/panels/**/components/*.ts',
       'front_end/ui/components/**/*.ts',
       'front_end/entrypoints/**/*.ts',
     ],
+    ignores: [
+      'front_end/core/**/*.test.ts',
+      'front_end/models/**/*.test.ts',
+    ],
 
     rules: {
       '@devtools/prefer-private-class-members': 'error',
@@ -833,6 +841,29 @@ export default defineConfig([
   {
     name: 'Ignore private class members rule',
     files: [
+      'front_end/core/common/**/*.ts',
+      'front_end/core/host/**/*.ts',
+      'front_end/core/platform/**/*.ts',
+      'front_end/core/protocol_client/**/*.ts',
+      'front_end/core/sdk/**/*.ts',
+      'front_end/core/text_utils/**/*.ts',
+      'front_end/models/bindings/**/*.ts',
+      'front_end/models/breakpoints/**/*.ts',
+      'front_end/models/computed_style/**/*.ts',
+      'front_end/models/cpu_profile/**/*.ts',
+      'front_end/models/elements/**/*.ts',
+      'front_end/models/emulation/**/*.ts',
+      'front_end/models/extensions/**/*.ts',
+      'front_end/models/formatter/**/*.ts',
+      'front_end/models/har/**/*.ts',
+      'front_end/models/javascript_metadata/**/*.ts',
+      'front_end/models/logs/**/*.ts',
+      'front_end/models/persistence/**/*.ts',
+      'front_end/models/source_map_scopes/**/*.ts',
+      'front_end/models/trace/**/*.ts',
+      'front_end/models/trace_source_maps_resolver/**/*.ts',
+      'front_end/models/workspace/**/*.ts',
+      'front_end/models/workspace_diff/**/*.ts',
       'front_end/panels/recorder/**/*.ts',
       'front_end/ui/components/suggestion_input/*.ts',
     ],
@@ -899,12 +930,12 @@ export default defineConfig([
           bannedImportPaths: [
             {
               bannedPath: join(
-                import.meta.dirname,
-                'front_end',
-                'core',
-                'sdk',
-                'sdk.js',
-              ),
+                  import.meta.dirname,
+                  'front_end',
+                  'core',
+                  'sdk',
+                  'sdk.js',
+                  ),
               allowTypeImports: true,
             },
           ],
@@ -963,4 +994,15 @@ export default defineConfig([
       'no-restricted-syntax': 'off',
     },
   },
+  {
+    name: 'Mocha test harness setup files',
+    files: [
+      'front_end/testing/test_setup.ts',
+      'test/unit/mocha-hooks.ts',
+    ],
+    rules: {
+      // Global Mocha test harness restores Sinon stubs and timers after each test.
+      '@devtools/no-manual-sinon-restore': 'off',
+    },
+  },
 ]);

package/front_end/core/platform/api/HostRuntime.ts

@@ -36,6 +36,7 @@ export interface HostRuntime {
   getCacheStorage(): CacheStorageLike|undefined;
   getDevicePixelRatio(): number;
   saveScreenshot(options: ScreenshotOptions): Promise<void>;
+  copyScreenshot(options: ScreenshotOptions): Promise<void>;
   revokeLastScreenshotUrl(): void;
   loadTextFile(url: URL): Promise<string>;
   evaluateCSS(dataValue: string|null, customExpr: string): string|null;

package/front_end/core/platform/browser/HostRuntime.ts

@@ -130,6 +130,15 @@ async function saveScreenshot(options: Api.HostRuntime.ScreenshotOptions): Promi
   link.click();
 }
 
+async function copyScreenshot(options: Api.HostRuntime.ScreenshotOptions): Promise<void> {
+  const response = await fetch('data:image/png;base64,' + options.base64Png);
+  const blob = await response.blob();
+
+  await navigator.clipboard.write([
+    new ClipboardItem({'image/png': blob}),
+  ]);
+}
+
 let cssEvaluationElement: HTMLElement|null = null;
 
 export const HOST_RUNTIME: Api.HostRuntime.HostRuntime = {
@@ -155,6 +164,7 @@ export const HOST_RUNTIME: Api.HostRuntime.HostRuntime = {
     return window.devicePixelRatio;
   },
   saveScreenshot,
+  copyScreenshot,
   revokeLastScreenshotUrl,
   async loadTextFile(url: URL): Promise<string> {
     const response = await fetch(url);

package/front_end/core/platform/node/HostRuntime.ts

@@ -137,6 +137,7 @@ export const HOST_RUNTIME: Api.HostRuntime.HostRuntime = {
     return 1;
   },
   async saveScreenshot(_options: Api.HostRuntime.ScreenshotOptions): Promise<void>{},
+  async copyScreenshot(_options: Api.HostRuntime.ScreenshotOptions): Promise<void>{},
   revokeLastScreenshotUrl(): void{},
   async loadTextFile(url: URL): Promise<string> {
     return await Fs.promises.readFile(Url.fileURLToPath(url), 'utf-8');