chrome-devtools-frontend 1.0.1717196 → 1.0.1721762

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.

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
@@ -34,14 +39,18 @@ existing element containers.
         that method. **Do not** introduce Widget lifecycle methods
         (`performUpdate`) on classes that do not inherit them.
 
-3.  **Import Modern Templating**:
+3.  **Import Modern Templating (Named Imports Only)**:
 
-    *   Import the `Lit` rendering system inside the view module:
+    *   Always use named imports from `../../ui/lit/lit.js`:
 
         ```typescript
-        import {html, render, nothing} from '../../ui/lit/lit.js';
+        import {html, nothing, render, Directives, type LitTemplate} from '../../ui/lit/lit.js';
         ```
 
+    *   **NEVER** use namespace imports like `import * as Lit` or reference
+        `Lit.nothing` / `Lit.render`. Named imports enable better tree-shaking and
+        maintain consistent codebase style.
+
 4.  **Modern Component Mapping**:
     *   **MANDATORY**: You **MUST** read and load [ui_engineering.md](../../../docs/ui_engineering.md) first to understand specific component mappings (e.g., Toolbar vs `devtools-toolbar`). Do not assume standard Lit defaults.
     *   If unsure, also consult the [automatic migration code](../../../scripts/eslint_rules/lib/no-imperative-dom-api.ts)
@@ -115,13 +124,64 @@ 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. **Micro-Commit Strategy**:
+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
+        (`{widget: shouldShow ? this.#sharedWidget : null}`).
+    *   `WrapperWidget` automatically handles showing and detaching the inner
+        widget and forwards calculateConstraints without requiring custom wrapper
+        classes.
+
+13. **Declarative `<devtools-split-view>` Guidelines**:
+
+    *   **CSS Sizing**: Ensure `<devtools-split-view>` has `flex: auto; height: 100%;`
+        in CSS so it fills available container space and doesn't collapse to 0x0.
+    *   **Reuse Existing Settings for `showMode`**: When binding `show=${...}`
+        declaratively on `<devtools-split-view name="...">`, reuse the existing
+        `SplitWidget` setting (`{vertical?: {size, showMode}, horizontal?: {size, showMode}}`)
+        for `showMode` rather than creating new boolean settings (which loses user
+        preferences and requires `KnownContextValues.ts` updates).
+    *   **Keep Environment Overrides in Templates**: Keep environment overrides
+        (like `!input.isTraceApp`) in the `DEFAULT_VIEW` template (e.g.,
+        `show=${!input.isTraceApp && input.isSidebarOpen ? 'both' : 'main'}`)
+        rather than baking them into the presenter's setting state.
+    *   **Clean Up Resizers**: Do not leave unused `resizer-widget` classes in
+        templates; `<devtools-split-view>` manages its own built-in splitter
+        unless custom elements are explicitly registered with `installResizer`.
+
+14. **Declarative Long-Press Action Buttons (`bindToAction`)**:
+
+    *   Legacy `UI.Toolbar.Toolbar.createLongPressActionButton(action, [subButtons])`
+        maps declaratively to nesting option `<devtools-button>` elements directly
+        inside `<devtools-button ${bindToAction('action-id')}>...</devtools-button>`.
+
+15. **Audit Removed `UIStrings`**:
+
+    *   If a `UIStrings` entry becomes unused during template migration, verify
+        that a conditional UI branch (such as a dynamically shown checkbox, button,
+        or tooltip) wasn't accidentally dropped before deleting the string.
+
+16. **Micro-Commit Strategy**:
 
     *   Do not attempt to convert every helper method and UI component in a single monolithic commit. Break the template extraction into **small, self-contained micro-commits** (e.g., migrating one helper method, toolbar button, or list item render at a time).
     *   Verify with build and run tests after each micro-commit to guarantee zero regressions and 100% visual parity before moving to the next compartment.
     *   Provide the exact list of files and commit message when presenting progress so the change history remains atomic and easy to review.
 
-13. **Wait for confirmation**:
+17. **Wait for confirmation**:
 
     *   Wait for an explicit confirmation from the user (or Parent Orchestrator Agent) before proceeding to the next step.
 
@@ -130,8 +190,12 @@ existing element containers.
 ## 🔍 Mental Audit (Internal Self-Correction)
 
 *Before reporting back or committing, re-read the instructions and verify:*
-1.  ❓ **Tag Parity**: Did I accidentally change any `span` to `div` (or vice versa)?
-2.  ❓ **Attribute Drop**: Did I drop any `aria-*`, `role`, or custom data attributes?
-3.  ❓ **Clang-Off Boundary**: Is the template wrapped in `// clang-format off`?
-4.  ❓ **Build**: Does the code compile and do visual tests pass with 0% diff?
+1.  ❓ **Named Imports**: Did I use named imports `{html, nothing, render}` from `ui/lit/lit.js` (and no `import * as Lit`)?
+2.  ❓ **Tag Parity**: Did I accidentally change any `span` to `div` (or vice versa)?
+3.  ❓ **Attribute Drop**: Did I drop any `aria-*`, `role`, or custom data attributes?
+4.  ❓ **Clang-Off Boundary**: Is the template wrapped in `// clang-format off`?
+5.  ❓ **Split Views**: Does `<devtools-split-view>` have `flex: auto; height: 100%;` CSS and reuse existing split settings?
+6.  ❓ **String Audit**: Did I verify that any removed `UIStrings` weren't from accidentally dropped UI branches?
+7.  ❓ **Build**: Does the code compile and do visual tests pass with 0% diff?
+
 

package/.agents/skills/ui-eng-vision-logic-consolidator/SKILL.md

@@ -76,7 +76,29 @@ consolidating them into private helper methods with explicit data contracts.
         that first extracts the code that needs to be reordered into named
         helper functions and pause the migration, waiting for user confirmation.
 
-6.  **Wait for confirmation**:
+6.  **No Write-Only State Fields in Prefactor CLs**:
+
+    *   Do not introduce `#state` fields in a logic-consolidation CL that are only
+        written to in that CL and only read in the *next* CL's `DEFAULT_VIEW`.
+    *   Either read them in the prefactor CL (e.g., inside an extracted imperative
+        `#render...` helper) or introduce them in the CL that actually adds
+        `DEFAULT_VIEW`.
+
+7.  **Extract Imperative `#renderSubtreeContent()` Helpers**:
+
+    *   For complex layouts, extracting an imperative `#renderFooContent()`
+        helper in Pass 1 (while keeping the outer container imperative) minimizes
+        the Pass 2/3 diff when converting `#renderFooContent()` to
+        `renderFooContent(input: ViewInput): LitTemplate`.
+
+8.  **Preserve Imperative Cleanup Calls**:
+
+    *   When consolidating DOM/widget references (e.g., replacing
+        `#tabbedLocationHeader` with `#debuggerSidebarTabbedLocation`), preserve
+        imperative cleanup calls like `splitWidget.uninstallResizer(...)` until the
+        imperative container itself is removed.
+
+9.  **Wait for confirmation**:
 
     *   Wait for an explicit confirmation from the user (or Parent Orchestrator Agent) before proceeding to the next step.
 
@@ -86,6 +108,8 @@ consolidating them into private helper methods with explicit data contracts.
 
 *Before reporting back or committing, re-read the instructions and verify:*
 1.  ❓ **Minimal Diffs**: Did I move code blocks around unnecessarily?
-2.  ❓ **State Completeness**: Are all imperative DOM updates now backed by state variables?
-3.  ❓ **Build**: Does the code still compile?
+2.  ❓ **State Completeness & Utility**: Are all state variables actually read in this CL, with no write-only placeholders?
+3.  ❓ **Cleanup Preserved**: Are resizer/listener uninstallation calls preserved during reference consolidation?
+4.  ❓ **Build**: Does the code still compile?
+
 

package/.agents/skills/ui-eng-vision-orchestrator/SKILL.md

@@ -76,6 +76,26 @@ principles.
     clean and focused on high-level orchestration, prefer delegating intense
     execution tasks (like running tests, debugging compilations, or processing
     independent classes in parallel) to specialized subagents.
+13. **Cross-Repo Runtime Coupling Check (`legacy_test_runner` & `blink/web_tests`)**:
+    Before converting TypeScript `private` fields/methods to ES `#private` or
+    removing widget properties (e.g., `.tabbedPane`, `.sidebarPaneStack`,
+    `.threadsSidebarPane`, `.searchInputElement`), search both
+    `front_end/legacy_test_runner/**/*.js` and Chromium's
+    `third_party/blink/web_tests/http/tests/devtools/**/*.js` (which run on
+    `dtf_linux_rel` CQ via `blink_web_tests` and reflectively access private
+    members in untyped JS). Keep accessed members as TypeScript `private` with a
+    `// Accessed in web_tests / legacy_test_runner` comment, or migrate the
+    web_tests first in a dedicated CL.
+14. **Strict CL Splitting Rules**:
+    *   **One Class Per CL for Hybrid Files**: When modernizing files containing
+        multiple classes, extract or migrate secondary classes (e.g.,
+        `QuickSourceView`) into their own dedicated CLs.
+    *   **Separate Infrastructure CLs**: Keep shared `ui/legacy` or component
+        infrastructure changes (e.g., `bindToAction`, `SplitWidget`,
+        `WrapperWidget`) in separate, preceding CLs. Always verify with
+        `cog_api.py diff` before uploading that no changes from later commits
+        leaked into earlier infrastructure CLs.
+
 
 
 --------------------------------------------------------------------------------
@@ -129,6 +149,8 @@ The plan you generate **MUST** follow this structure:
 ## 🛠️ Passes Checklist
 - [ ] **Pass 0: Baseline & Safety Scaffolding**
   - Assigned to: `ui-eng-vision-test-scaffolder`
+- [ ] **Pass 0.5: Privatize & Dead-Code Cleanup**
+  - Mechanical prefactor: convert TypeScript `private` to ES `#private` and remove dead code
 - [ ] **Pass 1: Logic Consolidation**
   - Assigned to: `ui-eng-vision-logic-consolidator`
 - [ ] **Pass 2: Lit-HTML Rendering**
@@ -149,10 +171,18 @@ The plan you generate **MUST** follow this structure:
         regressions.
     2.  Pay extra attention not to skip this step.
 
+### Privatize & Dead-Code Cleanup (Pass 0.5)
+
+*   **Trigger Condition**: Baseline tests green.
+*   **Actions**:
+    1.  Perform the **Cross-Repo Runtime Coupling Check** against `legacy_test_runner` and `blink_web_tests` first.
+    2.  Convert internal TypeScript `private` fields/methods to ES `#private` (except those reflectively accessed by web tests).
+    3.  Identify and remove unused dead code, redundant containers, or obsolete split widgets in a dedicated prefactor CL so mechanical renames don't clutter logic and view CLs.
+    4.  Verify that all tests and lints pass and stage this prefactor CL before proceeding to logic consolidation.
+
 ### Logic Consolidation
 
-*   **Trigger Condition**: Baseline tests green (or respective previous pass
-    staged).
+*   **Trigger Condition**: Pass 0.5 staged (or baseline tests green if 0.5 skipped).
 *   **Subskill to Import/Delegate**: `ui-eng-vision-logic-consolidator` (Delegate to a subagent to maintain focus)
 *   **Actions**:
     1.  Extract manual elements, constructor DOM configurations, and imperative

package/.agents/skills/ui-eng-vision-test-scaffolder/SKILL.md

@@ -65,20 +65,23 @@ logical regressions are introduced during modernization.
 
 Always detect the execution environment first to run tests successfully:
 
-### Scenario A: Google-Internal Cog/Cider Workspaces (PRIMARY PATH for Google Workspaces)
+### Scenario A: Google-Internal Cog Workspaces (PRIMARY PATH for Google Workspaces)
 
 *   **Detection**: Triggered if the workspace path starts with `/google/cog/` or
     `/google/src/`.
-*   **Why it is required**: Raw commands like `./dt test` or `autoninja` fail
-    because they lack Google cloudtop/virtualization wrapper configurations.
+*   **Execution Guide**: Follow [`devtools-verification`](../devtools-verification/SKILL.md).
 *   **Resolution Steps**:
 
-    1.  Do not run `./dt test` or standard `autoninja` directly.
-    2.  Leverage the Google-specific Cider testing script to compile and run
-        tests in the cloud workspace:
+    1.  Ensure `depot_tools` is at the front of your `PATH`:
 
         ```bash
-        python3 internal/infra/scripts/cider/init_workspace.py test /google/cog/cloud/username/workspace_name --test_filter=front_end/panels/application/IndexedDBViews.test.ts
+        export PATH="/path/to/depot_tools:$PATH"
+        ```
+
+    2.  Execute tests using `./dt test` directly from `chromium/third_party/devtools-frontend/src`:
+
+        ```bash
+        ./dt test front_end/panels/application/IndexedDBViews.test.ts
         ```
 
 ### Scenario B: Standard Chromium Environment (Fallback)
@@ -133,6 +136,33 @@ Always detect the execution environment first to run tests successfully:
     3.  If it's a layout shift, check if you replaced a block element with an inline element (e.g. `div` -> `span`).
     4.  If styles are missing, verify if the test wrapper needs `{includeCommonStyles: true}`.
 
+### Scenario E: Lightweight Test Hook Gotchas (`describe` vs `describeWithEnvironment`)
+
+*   Prefer `describe` with lightweight hooks (`setupLocaleHooks()`, `setupSettingsHooks()`) when full `describeWithEnvironment` is unnecessary.
+*   **Always reset singleton registries in `afterEach`**:
+    When registering actions, shortcuts, or context menus in tests, singleton registries MUST be reset in `afterEach`:
+
+    ```typescript
+    afterEach(() => {
+      UI.ActionRegistration.reset();
+      UI.ActionRegistry.ActionRegistry.reset();
+      UI.ShortcutRegistry.ShortcutRegistry.removeInstance();
+    });
+    ```
+
+    Without these resets, repeated runs (such as `--repeat=10` or CQ flake detection) will fail on iteration 2+ with `Duplicate action ID: '...'`.
+
+*   **GlassPane Container Setup**:
+    If testing UI that opens a `GlassPane` or long-press option menu (e.g. `bindToAction` with long-press buttons) in a test suite using `describe` without `describeWithEnvironment`, call:
+
+    ```typescript
+    beforeEach(() => {
+      UI.GlassPane.GlassPane.setContainer(document.body);
+    });
+    ```
+
+    Otherwise, menu rendering will fail because `GlassPane` lacks an attached container element.
+
 --------------------------------------------------------------------------------
 
 ## 🔍 Mental Audit (Internal Self-Correction)

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

@@ -28,11 +28,11 @@ clean `UI.Widget` classes that use native update rendering delegates.
 2.  **Upgrade View Delegates & Inject View**:
 
     *   Migrate the local Lit template strings into a formally exported default
-        view layout:
+        view layout (using named imports `import {html, render} from '../../ui/lit/lit.js';`):
 
         ```typescript
         export const DEFAULT_VIEW: View = (input, output, target) => {
-          Lit.render(html`...`, target);
+          render(html`...`, target);
         };
         ```
 
@@ -67,12 +67,13 @@ clean `UI.Widget` classes that use native update rendering delegates.
 
     *   Remove any `LegacyWrapper` bindings or custom wrappable custom elements.
     *   Replace old panel instantiations with standard `<devtools-widget>`
-        declarative entries:
+        declarative entries (using `const {widget} = UI.Widget;`):
 
         ```typescript
-        html`<devtools-widget .widgetConfig=${widgetConfig(MyWidgetClass, [params])}></devtools-widget>`
+        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.
 
 --------------------------------------------------------------------------------