chrome-devtools-frontend 1.0.1733843 → 1.0.1736236

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (184) hide show
  1. package/.agents/rules/tests/test-view-and-presenter-isolation.md +4 -4
  2. package/.agents/rules/ui-and-widgets/ui-declarative-tree-and-prompt-patterns.md +61 -0
  3. package/.agents/rules/ui-and-widgets/ui-lit-declarative-templates-and-directives.md +11 -7
  4. package/.agents/rules/ui-and-widgets/ui-modern-component-and-encapsulation-standards.md +13 -4
  5. package/.agents/rules/ui-and-widgets/ui-pure-view-and-presenter-separation.md +31 -2
  6. package/.agents/rules/ui-and-widgets/ui-reactive-widget-update-lifecycle.md +23 -4
  7. package/.agents/rules/ui-and-widgets/ui-widget-dom-and-listener-lifecycle.md +34 -3
  8. package/.agents/skills/code-review/SKILL.md +27 -0
  9. package/.agents/skills/devtools-uistrings/SKILL.md +147 -0
  10. package/.agents/skills/ui-eng-vision-local-lit-renderer/SKILL.md +27 -1
  11. package/.agents/skills/ui-eng-vision-orchestrator/SKILL.md +100 -0
  12. package/.agents/skills/ui-eng-vision-test-scaffolder/SKILL.md +16 -0
  13. package/.agents/skills/ui-eng-vision-widget-promoter/SKILL.md +13 -2
  14. package/.agents/skills/ui-widgets/SKILL.md +25 -25
  15. package/DIR_METADATA +8 -1
  16. package/docs/cookbook/localization.md +1 -1
  17. package/docs/ui_engineering.md +24 -0
  18. package/eslint.config.mjs +0 -1
  19. package/front_end/application_tokens.css +1 -1
  20. package/front_end/core/host/AidaClient.ts +147 -202
  21. package/front_end/core/host/AidaClientTypes.ts +9 -0
  22. package/front_end/core/host/AidaErrors.ts +416 -0
  23. package/front_end/core/host/AidaGcaTranslation.ts +11 -0
  24. package/front_end/core/host/InspectorFrontendHostAPI.ts +9 -2
  25. package/front_end/core/host/UserMetrics.ts +25 -0
  26. package/front_end/core/host/UserMetricsEnums.ts +25 -0
  27. package/front_end/core/host/host.ts +3 -1
  28. package/front_end/core/i18n/collect-ui-strings.js +20 -0
  29. package/front_end/core/root/Runtime.ts +12 -0
  30. package/front_end/core/sdk/CPUThrottlingManager.ts +3 -0
  31. package/front_end/core/sdk/EnhancedTracesParser.ts +8 -4
  32. package/front_end/core/sdk/NetworkManager.ts +0 -6
  33. package/front_end/core/sdk/OverlayModel.ts +0 -6
  34. package/front_end/core/sdk/PreloadingModel.ts +30 -13
  35. package/front_end/core/sdk/PrivateVerificationTokensModel.ts +0 -18
  36. package/front_end/core/sdk/RehydratingConnection.ts +5 -2
  37. package/front_end/core/sdk/ResourceTreeModel.ts +0 -42
  38. package/front_end/core/sdk/ScreenCaptureModel.ts +0 -84
  39. package/front_end/core/sdk/ServiceWorkerCacheModel.ts +0 -15
  40. package/front_end/core/sdk/StorageBucketsModel.ts +0 -15
  41. package/front_end/devtools_compatibility.js +57 -2
  42. package/front_end/entrypoints/formatter_worker/ScopeParser.ts +4 -2
  43. package/front_end/entrypoints/inspector_main/RenderingOptions.ts +203 -127
  44. package/front_end/entrypoints/inspector_main/renderingOptions.css +5 -0
  45. package/front_end/entrypoints/node_app/app/NodeMain.ts +0 -9
  46. package/front_end/entrypoints/node_app/app/nodeConnectionsPanel.css +0 -22
  47. package/front_end/generated/InspectorBackendCommands.ts +1 -1
  48. package/front_end/generated/SupportedCSSProperties.ts +0 -136
  49. package/front_end/generated/protocol-proxy-api.d.ts +231 -231
  50. package/front_end/generated/protocol.ts +1 -0
  51. package/front_end/models/ai_assistance/AiAgent2.ts +4 -1
  52. package/front_end/models/ai_assistance/ChangeManager.ts +3 -1
  53. package/front_end/models/ai_assistance/DOMHelpers.ts +118 -3
  54. package/front_end/models/ai_assistance/ExtensionScope.ts +31 -24
  55. package/front_end/models/ai_assistance/agents/AiAgent.ts +6 -0
  56. package/front_end/models/ai_assistance/agents/PerformanceAgent.snapshot.txt +13 -13
  57. package/front_end/models/ai_assistance/agents/PerformanceAgent.ts +1 -1
  58. package/front_end/models/ai_assistance/ai_assistance.ts +2 -0
  59. package/front_end/models/ai_assistance/data_formatters/PerformanceInsightFormatter.snapshot.txt +18 -8
  60. package/front_end/models/ai_assistance/data_formatters/PerformanceInsightFormatter.ts +2 -2
  61. package/front_end/models/ai_assistance/data_formatters/PerformanceTraceFormatter.snapshot.txt +103 -81
  62. package/front_end/models/ai_assistance/data_formatters/PerformanceTraceFormatter.ts +15 -203
  63. package/front_end/models/ai_assistance/injected.ts +6 -1
  64. package/front_end/models/ai_assistance/skills/lighthouse.md +1 -1
  65. package/front_end/models/ai_assistance/skills/styling.md +8 -10
  66. package/front_end/models/ai_assistance/tools/GetTraceEventByKey.ts +1 -1
  67. package/front_end/models/ai_assistance/tools/SetElementStyles.ts +288 -0
  68. package/front_end/models/ai_assistance/tools/Tool.ts +1 -0
  69. package/front_end/models/ai_assistance/tools/ToolRegistry.ts +3 -0
  70. package/front_end/models/bindings/ResourceScriptMapping.ts +64 -16
  71. package/front_end/models/comment_manager/CD4ABridge.ts +12 -2
  72. package/front_end/models/comment_manager/CommentManager.ts +24 -4
  73. package/front_end/models/javascript_metadata/NativeFunctions.ts +41 -1
  74. package/front_end/models/project_settings/ProjectSettingsModel.ts +1 -1
  75. package/front_end/models/trace/handlers/FlowsHandler.ts +10 -0
  76. package/front_end/models/trace/handlers/SamplesHandler.ts +3 -2
  77. package/front_end/models/trace/handlers/ScriptsHandler.ts +25 -26
  78. package/front_end/models/trace/helpers/TreeHelpers.ts +4 -0
  79. package/front_end/models/trace/insights/DuplicatedJavaScript.ts +1 -2
  80. package/front_end/models/trace/types/TraceEvents.ts +21 -22
  81. package/front_end/panels/ai_assistance/components/ChatMessage.ts +9 -1
  82. package/front_end/panels/ai_assistance/components/chatInput.css +4 -4
  83. package/front_end/panels/animation/AnimationTimeline.ts +3 -3
  84. package/front_end/panels/animation/animationTimeline.css +6 -4
  85. package/front_end/panels/application/IndexedDBModel.ts +0 -15
  86. package/front_end/panels/application/appManifestView.css +2 -5
  87. package/front_end/panels/application/components/backForwardCacheView.css +1 -5
  88. package/front_end/panels/application/components/serviceWorkerRouterView.css +2 -2
  89. package/front_end/panels/application/preloading/components/PreloadingString.ts +7 -0
  90. package/front_end/panels/comments/CommentsPane.ts +12 -7
  91. package/front_end/panels/comments/commentsPane.css +16 -2
  92. package/front_end/panels/common/CommentsOverlayWidget.ts +16 -10
  93. package/front_end/panels/common/CommentsStatusBarPill.ts +12 -5
  94. package/front_end/panels/common/commentsOverlay.css +7 -1
  95. package/front_end/panels/common/commentsStatusBarPill.css +30 -0
  96. package/front_end/panels/console/consolePrompt.css +0 -12
  97. package/front_end/panels/console/consoleView.css +2 -2
  98. package/front_end/panels/developer_resources/developerResourcesView.css +4 -3
  99. package/front_end/panels/elements/DOMTreeWidget.ts +29 -9
  100. package/front_end/panels/elements/StylePropertyTreeElement.ts +2 -1
  101. package/front_end/panels/elements/components/CSSHintDetailsView.ts +12 -5
  102. package/front_end/panels/elements/components/cssVariableValueView.css +1 -1
  103. package/front_end/panels/elements/components/elementsBreadcrumbs.css +2 -2
  104. package/front_end/panels/elements/domTreeWidget.css +6 -1
  105. package/front_end/panels/elements/elementsPanel.css +0 -6
  106. package/front_end/panels/elements/layoutPane.css +1 -1
  107. package/front_end/panels/elements/metricsSidebarPane.css +1 -1
  108. package/front_end/panels/elements/platformFontsWidget.css +1 -1
  109. package/front_end/panels/elements/stylesSidebarPane.css +0 -10
  110. package/front_end/panels/emulation/deviceModeView.css +6 -7
  111. package/front_end/panels/explain/components/consoleInsight.css +4 -4
  112. package/front_end/panels/issues/issuesTree.css +1 -26
  113. package/front_end/panels/lighthouse/lighthouseStartView.css +2 -2
  114. package/front_end/panels/linear_memory_inspector/components/linearMemoryInspector.css +1 -1
  115. package/front_end/panels/media/TickingFlameChart.ts +20 -3
  116. package/front_end/panels/media/playerMessagesView.css +2 -2
  117. package/front_end/panels/mobile_throttling/ThrottlingSettingsTab.ts +24 -5
  118. package/front_end/panels/mobile_throttling/throttlingSettingsTab.css +1 -6
  119. package/front_end/panels/network/networkLogView.css +2 -2
  120. package/front_end/panels/network/networkTimingTable.css +1 -1
  121. package/front_end/panels/performance_monitor/performanceMonitor.css +0 -4
  122. package/front_end/panels/protocol_monitor/JSONEditor.css +1 -1
  123. package/front_end/panels/protocol_monitor/JSONEditor.ts +4 -2
  124. package/front_end/panels/recorder/recorderPanel.css +3 -3
  125. package/front_end/panels/recorder/recordingListView.css +1 -1
  126. package/front_end/panels/screencast/screencastView.css +1 -1
  127. package/front_end/panels/search/searchResultsPane.css +1 -1
  128. package/front_end/panels/security/SecurityModel.ts +0 -6
  129. package/front_end/panels/security/SecurityPanel.ts +120 -108
  130. package/front_end/panels/security/originView.css +1 -1
  131. package/front_end/panels/sensors/locationsSettingsTab.css +3 -3
  132. package/front_end/panels/settings/EditFileSystemView.ts +159 -104
  133. package/front_end/panels/settings/editFileSystemView.css +30 -4
  134. package/front_end/panels/settings/emulation/devicesSettingsTab.css +0 -52
  135. package/front_end/panels/settings/settingsScreen.css +0 -7
  136. package/front_end/panels/sources/CallStackSidebarPane.ts +339 -221
  137. package/front_end/panels/sources/NavigatorView.ts +95 -8
  138. package/front_end/panels/sources/ThreadsSidebarPane.ts +8 -4
  139. package/front_end/panels/sources/breakpointsView.css +1 -3
  140. package/front_end/panels/sources/callStackSidebarPane.css +4 -0
  141. package/front_end/panels/sources/components/HeadersView.ts +15 -2
  142. package/front_end/panels/sources/watchExpressionsSidebarPane.css +0 -1
  143. package/front_end/panels/timeline/CountersGraph.ts +0 -4
  144. package/front_end/panels/timeline/TimelineLoader.ts +16 -6
  145. package/front_end/panels/timeline/TimelinePanel.ts +20 -12
  146. package/front_end/panels/timeline/TimelineUIUtils.ts +1 -1
  147. package/front_end/panels/timeline/components/DetailsView.ts +2 -1
  148. package/front_end/panels/timeline/components/cwvMetrics.css +1 -1
  149. package/front_end/panels/timeline/components/metricCard.css +1 -1
  150. package/front_end/panels/timeline/components/sidebarAnnotationsTab.css +4 -4
  151. package/front_end/panels/timeline/timelineFlameChartView.css +1 -1
  152. package/front_end/panels/webauthn/WebauthnPane.ts +13 -14
  153. package/front_end/panels/webauthn/webauthnPane.css +1 -1
  154. package/front_end/third_party/chromium/README.chromium +1 -1
  155. package/front_end/ui/comments/CommentOverlayManager.ts +34 -18
  156. package/front_end/ui/components/icon_button/FileSourceIcon.ts +6 -0
  157. package/front_end/ui/components/input/textInput.css +1 -1
  158. package/front_end/ui/components/panel_introduction_steps/panelIntroductionSteps.css +6 -4
  159. package/front_end/ui/components/suggestion_input/suggestionInput.css +2 -2
  160. package/front_end/ui/components/text_editor/AiCodeGenerationTeaser.ts +14 -2
  161. package/front_end/ui/legacy/DockController.ts +17 -4
  162. package/front_end/ui/legacy/Treeoutline.ts +2 -2
  163. package/front_end/ui/legacy/UIUtils.ts +148 -10
  164. package/front_end/ui/legacy/components/inline_editor/bezierEditor.css +3 -2
  165. package/front_end/ui/legacy/components/perf_ui/chartViewport.css +2 -2
  166. package/front_end/ui/legacy/components/perf_ui/filmStripView.css +2 -2
  167. package/front_end/ui/legacy/components/perf_ui/pieChart.css +1 -1
  168. package/front_end/ui/legacy/components/quick_open/filteredListWidget.css +5 -4
  169. package/front_end/ui/legacy/components/source_frame/imageView.css +1 -1
  170. package/front_end/ui/legacy/components/utils/TargetDetachedDialog.ts +0 -3
  171. package/front_end/ui/legacy/components/utils/imagePreview.css +1 -1
  172. package/front_end/ui/legacy/inspectorCommon.css +1 -14
  173. package/front_end/ui/legacy/inspectorDrawerTabbedPane.css +3 -2
  174. package/front_end/ui/legacy/listWidget.css +0 -18
  175. package/front_end/ui/legacy/theme_support/ThemeSupport.ts +44 -9
  176. package/front_end/ui/lit/strip-whitespace.ts +1 -1
  177. package/front_end/ui/visual_logging/KnownContextValues.ts +1 -0
  178. package/package.json +3 -3
  179. package/front_end/generated/Deprecation.ts +0 -471
  180. package/front_end/panels/accessibility/axBreadcrumbs.css +0 -155
  181. package/front_end/panels/network/requestHeadersTree.css +0 -226
  182. package/front_end/panels/recorder/startView.css +0 -38
  183. package/front_end/panels/security/ipProtectionView.css +0 -141
  184. package/front_end/ui/legacy/components/inline_editor/animationNameSwatch.css +0 -27
@@ -4,11 +4,11 @@ rubric: testing
4
4
  severity: should_fix
5
5
  ---
6
6
 
7
- **Rule.** Test presenters via createViewFunctionStub and test pure view functions directly without piercing internal DOM structures
8
- - **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.
9
- - **Do not flag**: Legacy widgets that have not yet separated their template rendering into a standalone `DEFAULT_VIEW` function. Pre-existing mounted widget tests in `*.test.ts` when migrating a widget to `DEFAULT_VIEW` (keep existing end-to-end presenter + `DEFAULT_VIEW` + child-widget wiring tests intact; `createViewFunctionStub` tests may be added for new presenter logic, not used to delete existing DOM wiring coverage).
7
+ **Rule.** Test presenters via createViewFunctionStub, encapsulate legacy DOM/tree inspection in test helpers, and test pure view functions directly without piercing internal DOM structures
8
+ - **Look for**: Presenter tests instantiating full DOM trees and querying shadow/child DOM selectors to simulate clicks when the widget accepts a `view` function, view tests instantiating full presenters just to test template markup, or pre-migration unit test suites added for a legacy widget (`UI.TreeOutline`, `DataGrid`, `UI.ListControl`, `UI.ListWidget`) that scatter direct internal structure queries (`.scriptsTree`, `.rootElement()`, internal shadow-DOM selectors) across individual `it()` blocks instead of isolating them in small local test helpers (`dumpTree()`, `findTreeItem()`, `activateRow()`), or that omit `assertScreenshot(...)` visual baselines when the underlying legacy widget implementation is scheduled to be replaced.
9
+ - **Do not flag**: Legacy widgets that have not yet separated their template rendering into a standalone `DEFAULT_VIEW` function. Pre-existing mounted widget tests in `*.test.ts` when migrating a widget to `DEFAULT_VIEW` (keep existing end-to-end presenter + `DEFAULT_VIEW` + child-widget wiring tests intact; `createViewFunctionStub` tests may be added for new presenter logic, not used to delete existing DOM wiring coverage). Isolated presenter unit tests using `createViewFunctionStub` do not require screenshot assertions.
10
10
 
11
- **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.
11
+ **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. When scaffolding tests ahead of replacing legacy widgets like `TreeOutline` or `ListControl`, routing DOM inspection through small local test helpers ensures the subsequent component swap only updates the helper definitions rather than dozens of tests, and `assertScreenshot` tests ensure visual parity independent of internal widget DOM changes.
12
12
 
13
13
  ## Examples
14
14
 
@@ -0,0 +1,61 @@
1
+ ---
2
+ name: devtools/ui-and-widgets/ui-declarative-tree-and-prompt-patterns
3
+ rubric: design
4
+ severity: should_fix
5
+ ---
6
+
7
+ **Rule.** Use declarative <devtools-tree> and persistent <devtools-prompt ?editing> (wrapped in a child widget inside tree rows) without widening ui/legacy Treeoutline contracts
8
+ - **Look for**: Panel or widget migrations modifying `front_end/ui/legacy/Treeoutline.ts` (`TreeViewElement` or `TreeViewTreeElement`) to accommodate legacy `TreeOutline` patterns—such as exporting `TreeViewTreeElement`, overriding `title` or `titleAsText()`, adding custom `.leading-icons` or `.trailing-icons` cloning hooks, or renaming `getInternalTreeOutlineForTest()` or `flushPendingUpdatesForTesting()` into public APIs—or leaving public `TreeOutline` getters (such as `get scriptsTree()`) on migrated presenters instead of rendering icons, labels, tooltips, and trailing actions inline inside `<li role="treeitem">` within `<devtools-tree .template=${html`<ul role="tree">...</ul>`}>` (`import '../../ui/kit/kit.js'`) and driving state via `?selected`, `?open`, `@select`, and `@expand`; duplicating `class="tree-element-title"` on inner `<span>` elements inside `<li role="treeitem">` (`TreeViewTreeElement.titleElement` already has `.tree-element-title`, causing rules like `.is-ignore-listed .tree-element-title { opacity: 40% }` to compound), or rendering an empty trailing-icons container instead of `nothing` when a row has no trailing actions; imperatively swapping `<devtools-prompt>` or `UI.InplaceEditor.startEditing` elements in and out of the DOM, subclassing `TreeElement` just to host prompt titles, keeping `UI.UIUtils.markBeingEdited` or `isBeingEdited` DOM markers on fully declarative widgets instead of presenter editing state, or setting a duplicate `aria-label` on an inner `<devtools-prompt>` when the enclosing `<li role="treeitem" aria-label=...>` already provides the accessible name; rendering `<devtools-prompt ?editing=${...}>` directly inside a `<devtools-tree>` `<li role="treeitem">` template instead of hosting it inside a small child `UI.Widget` via `${widget(RowPromptWidget, {...})}` (`<devtools-tree>` clones `<template>` nodes into shadow DOM and `TreeViewTreeElement.refresh()` re-clones and refocuses the `<li>` on any light-DOM mutation, immediately blurring and cancelling the active prompt when `?editing` toggles); or custom elements inside `<devtools-tree>` rows whose state updates via JS properties (`.data`) without overriding `cloneNode(deep)` to copy that state and reflecting dynamic state via a DOM attribute (such as `data-badge=${...}`) so `<devtools-tree>`'s `MutationObserver` refreshes the shadow clone.
9
+ - **Do not flag**: Unit tests or `front_end/legacy_test_runner/**` helpers calling `getInternalTreeOutlineForTest()` or `flushPendingUpdatesForTesting()` on `<devtools-tree>` for test inspection or synchronization. Explicitly scoped intermediate CLs (`Bug: <id>`) in a multi-CL migration that introduce persistent `<devtools-prompt ?editing>` on plain `UI.TreeOutline.TreeElement` rows (temporarily retaining `UI.UIUtils.markBeingEdited`) ahead of replacing `TreeOutline` with `<devtools-tree>`.
10
+
11
+ **Why.** Preserving `<devtools-tree>`'s declarative contract (`?selected`, `?open`, `@select`, `@expand`) prevents leaking legacy imperative `TreeOutline` internals across module boundaries. Keeping `<devtools-prompt ?editing>` persistently mounted in the template avoids disruptive DOM swapping and focus loss, while isolating editable prompts inside a child `UI.Widget` within `<devtools-tree>` prevents `MutationObserver` light-DOM re-clones from refocusing the `<li>` and blurring the active input. Omitting redundant `aria-label`s on inner prompts preserves accessible tree names without duplicate screen-reader announcements.
12
+
13
+ ## Examples
14
+
15
+ Bad:
16
+
17
+ ```ts
18
+ // Exposing legacy TreeOutline getters and rendering prompt directly in tree row
19
+ export class MyTreeView extends UI.Widget.VBox {
20
+ get scriptsTree(): UI.TreeOutline.TreeOutline {
21
+ return this.#tree;
22
+ }
23
+ }
24
+
25
+ const DEFAULT_VIEW = (input: ViewInput, _output: undefined, target: HTMLElement): void => {
26
+ render(html`
27
+ <devtools-tree .template=${html`
28
+ <ul role="tree">
29
+ <li role="treeitem" aria-label=${input.label}>
30
+ <span class="tree-element-title">
31
+ <devtools-prompt
32
+ aria-label=${input.label}
33
+ value=${input.title}
34
+ ?editing=${input.isEditing}>
35
+ ${input.title}
36
+ </devtools-prompt>
37
+ </span>
38
+ </li>
39
+ </ul>
40
+ `}></devtools-tree>
41
+ `, target);
42
+ };
43
+ ```
44
+
45
+ Good:
46
+
47
+ ```ts
48
+ const {widget} = UI.Widget;
49
+
50
+ const DEFAULT_VIEW = (input: ViewInput, _output: undefined, target: HTMLElement): void => {
51
+ render(html`
52
+ <devtools-tree autofocus .template=${html`
53
+ <ul role="tree">
54
+ <li role="treeitem" ?selected=${input.isSelected} ?open=${input.isOpen} aria-label=${input.label}>
55
+ ${widget(RowPromptWidget, {title: input.title, isEditing: input.isEditing})}
56
+ </li>
57
+ </ul>
58
+ `}></devtools-tree>
59
+ `, target);
60
+ };
61
+ ```
@@ -4,20 +4,22 @@ rubric: design
4
4
  severity: should_fix
5
5
  ---
6
6
 
7
- **Rule.** Use Lit.nothing, repeat with keys, classMap/styleMap, and ifDefined in single-pass declarative templates instead of imperative DOM mutations
8
- - **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, `Lit.*` namespace calls instead of direct `{Directives, html, nothing, render}` imports from `ui/lit/lit.js`, `useShadowDom: true` in new or migrated `UI.Widget` constructors instead of `useShadowDom: 'pure'` (which makes `this.contentElement` the `ShadowRoot` directly without an extra inner `<div class="widget">` wrapper), `super(..., {classes: [...]})` / `super(..., {jslog: ...})` in `UI.Widget` constructors instead of passing `{container: {classes: [...], attributes: {jslog: ...}}}` as the third argument to every `render(template, target, {container: {classes: [...]}})` branch in the view function (with `useShadowDom: 'pure'` when shadow DOM is used), imperative `element.classList.add(...)`, `element.setAttribute(...)`, or `UI.ARIAUtils.*(element)` calls on a container element (`this.contentElement`, `this.element`, or a detached `HTMLDivElement`) that is rendered via `render(template, element)` instead of passing `{container: {classes: [...], attributes: {...}}}` as the third argument to `render(...)`, or `@SomeEvent` on `<devtools-widget>` when the child class does not use `eventMixin` on `UI.Widget` (no `dispatchDOMEvent`), when the listener is placed on an ancestor element (the `CustomEvent` does not bubble), or when the handler reads `event.data` instead of `event.detail`.
9
- - **Do not flag**: Static arrays of primitive labels where item identity never reorders. Omitting Lit's `live()` directive on `<devtools-checkbox>` (`UI.UIUtils.CheckboxLabel`) `.checked` bindings (`live()` breaks `CheckboxLabel`'s host `checked` attribute synchronization when toggled externally), listening to `ObjectWrapper` events via Lit `@SomeEvent=${handler}` bindings on a `<devtools-widget>` whose class uses `Common.ObjectWrapper.eventMixin` on `UI.Widget` (`eventMixin` dispatches `new CustomEvent(type, {detail: data})` on `widget.element`, and Lit preserves the case of `@SomeEvent` from the template string), or interpolating boolean values directly inside Lit text/`<td>` positions (Lit renders booleans as `'true'`/`'false'`). Newlines and indentation spaces between expressions and child elements in multi-line `html` templates (DevTools' custom `html` tag in `front_end/ui/lit/strip-whitespace.ts` strips `\n\s*` outside of `<...>` tags at runtime, so multi-line formatting does not introduce whitespace text nodes).
7
+ **Rule.** Use Lit.nothing, repeat with keys, classMap/styleMap, ?hidden, autofocus, and ifDefined in single-pass declarative templates instead of imperative DOM mutations
8
+ - **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, `Lit.*` namespace calls instead of direct `{Directives, html, nothing, render}` imports from `ui/lit/lit.js`, `useShadowDom: true` in new or migrated `UI.Widget` constructors instead of `useShadowDom: 'pure'` (which makes `this.contentElement` the `ShadowRoot` directly without an extra inner `<div class="widget">` wrapper), `super(..., {classes: [...]})` / `super(..., {jslog: ...})` in `UI.Widget` constructors instead of passing `{container: {classes: [...], attributes: {jslog: ...}}}` as the third argument to every `render(template, target, {container: {classes: [...]}})` branch in the view function (with `useShadowDom: 'pure'` when shadow DOM is used), imperative `element.classList.add(...)`, `element.setAttribute(...)`, or `UI.ARIAUtils.*(element)` calls on a container element (`this.contentElement`, `this.element`, or a detached `HTMLDivElement`) that is rendered via `render(template, element)` instead of passing `{container: {classes: [...], attributes: {...}}}` as the third argument to `render(...)`, combining a `.hidden` CSS class (`class="... hidden"`, `classMap({hidden: ...})`, or `classList.toggle('hidden', ...)`) with the HTML `?hidden` attribute, or toggling `.hidden` via `classMap` when `?hidden=${...}` suffices (prefer `?hidden=${...}` exclusively; `inspectorCommon.css` already provides `[hidden] { display: none !important; }`), overriding `focus(): void` on a `UI.Widget`, calling `this.setDefaultFocusedElement(...)` or `this.setDefaultFocusedChild(...)` imperatively, or plumbing a `ref(...)` focus callback through `ViewOutput` merely to focus a default child element or widget when declarative `autofocus` or `?autofocus=${...}` in `DEFAULT_VIEW` suffices (`UI.Widget.prototype.focus()` natively queries `[autofocus]` via `getDefaultFocusedElement()`; ensure at most one element has `autofocus` in any render state), or `@SomeEvent` on `<devtools-widget>` when the child class does not use `eventMixin` on `UI.Widget` (no `dispatchDOMEvent`), when the listener is placed on an ancestor element (the `CustomEvent` does not bubble), or when the handler reads `event.data` instead of `event.detail`.
9
+ - **Do not flag**: Static arrays of primitive labels where item identity never reorders. Omitting Lit's `live()` directive on `<devtools-checkbox>` (`UI.UIUtils.CheckboxLabel`) `.checked` bindings (`live()` breaks `CheckboxLabel`'s host `checked` attribute synchronization when toggled externally), listening to `ObjectWrapper` events via Lit `@SomeEvent=${handler}` bindings on a `<devtools-widget>` whose class uses `Common.ObjectWrapper.eventMixin` on `UI.Widget` (`eventMixin` dispatches `new CustomEvent(type, {detail: data})` on `widget.element`, and Lit preserves the case of `@SomeEvent` from the template string), interpolating boolean values directly inside Lit text/`<td>` positions (Lit renders booleans as `'true'`/`'false'`), `override focus()` methods that perform dynamic focus restoration beyond focusing a single `[autofocus]` target (such as restoring text editor selection/coordinates or delegating to legacy sub-views), or newlines and indentation spaces between expressions and child elements in multi-line `html` templates (DevTools' custom `html` tag in `front_end/ui/lit/strip-whitespace.ts` strips `\n\s*` outside of `<...>` tags at runtime, so multi-line formatting does not introduce whitespace text nodes).
10
10
 
11
- **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.
11
+ **Why.** Mutating DOM elements via `appendChild`, `classList.toggle`, or `innerHTML` alongside Lit templates, returning `''`/`null` instead of `Lit.nothing` in conditional branches, or combining `.hidden` classes with `?hidden` attributes corrupts part tracking and creates redundant style rules. Using declarative `autofocus` leverages `UI.Widget`'s built-in focus delegation without imperative wiring or manual `ref` plumbing through `ViewOutput`.
12
12
 
13
13
  ## Examples
14
14
 
15
15
  Bad:
16
16
 
17
17
  ```ts
18
+ // String-interpolated classes, empty string ternary fallback, .hidden class + ?hidden, and ref focus plumbing
18
19
  html`
19
- <div class="item ${isActive ? 'active' : ''}" title=${ maybeTitle || '' }>
20
+ <div class="item ${isActive ? 'active' : ''} ${classMap({hidden: !isVisible})}" ?hidden=${!isVisible} title=${maybeTitle || ''}>
20
21
  ${showIcon ? html`<devtools-icon name="info"></devtools-icon>` : ''}
22
+ <button ${ref(el => { if (el) output.focus = () => el.focus(); })}>Click</button>
21
23
  </div>
22
24
  `
23
25
  ```
@@ -25,9 +27,11 @@ html`
25
27
  Good:
26
28
 
27
29
  ```ts
30
+ // Using classMap, ifDefined, nothing sentinel, ?hidden attribute exclusively, and autofocus
28
31
  html`
29
- <div class=${classMap({item: true, active: isActive})} title=${ifDefined(maybeTitle)}>
30
- ${showIcon ? html`<devtools-icon name="info"></devtools-icon>` : Lit.nothing}
32
+ <div class=${classMap({item: true, active: isActive})} ?hidden=${!isVisible} title=${ifDefined(maybeTitle)}>
33
+ ${showIcon ? html`<devtools-icon name="info"></devtools-icon>` : nothing}
34
+ <button autofocus>Click</button>
31
35
  </div>
32
36
  `
33
37
  ```
@@ -4,11 +4,11 @@ rubric: design
4
4
  severity: should_fix
5
5
  ---
6
6
 
7
- **Rule.** Use modern DevTools UI primitives (`devtools-button`, `devtools-data-grid`, `devtools-icon`, `devtools-link`, `devtools-list`, `devtools-tabbed-pane`, `devtools-stack-pane`), #private fields, and module entrypoint imports
8
- - **Look for**: `UI.Fragment.build`, legacy `DataGridImpl`, `extends LitElement`, `Link.create(...)` or `UI.XLink.XLink.create(...)` inside Lit view functions (use `<devtools-link>` instead), `UI.ListWidget.ListWidget` / `UI.ListWidget.Delegate` in newly migrated views or passed via `ViewInput` to `WrapperWidget` with `DocumentFragment` item/editor adapters (prefer `<devtools-list>` with `<devtools-prompt>`, an inline editor row, or `UI.Dialog.Dialog`, or encapsulate `ListWidget` inside the view layer behind pure `ViewInput` data and callbacks), imperative `UI.TabbedPane.TabbedPane` or `StackLocation` passed via `ViewInput` instead of declarative `<devtools-tabbed-pane>` / `<devtools-stack-pane>` in the view, `private ` keyword instead of `#` in new UI classes, `<devtools-*>` tags in Lit templates without importing the corresponding component module entrypoint (e.g. `import * as Buttons from '../../ui/components/buttons/buttons.js'`), or formatting dates or timestamps with `toLocaleString()` inside sortable `<devtools-data-grid>` cells without a numeric/ISO sort value (sorts alphabetically instead of chronologically; use `toISOString()` or a numeric sort value).
9
- - **Do not flag**: Overriding inherited `protected` lifecycle methods on framework base classes (e.g. extending `UI.Widget.Widget`).
7
+ **Rule.** Use modern DevTools UI primitives (`devtools-button`, `devtools-data-grid`, `devtools-icon`, `devtools-link`, `devtools-list`, `devtools-prompt`, `devtools-stack-pane`, `devtools-tabbed-pane`, `devtools-tree`), #private fields, and module entrypoint imports
8
+ - **Look for**: `UI.Fragment.build`, legacy `DataGridImpl`, `extends LitElement`, `Link.create(...)` or `UI.XLink.XLink.create(...)` inside Lit view functions (use `<devtools-link>` instead), `UI.ListWidget.ListWidget` / `UI.ListWidget.Delegate` in newly migrated views or passed via `ViewInput` to `WrapperWidget` with `DocumentFragment` item/editor adapters (prefer `<devtools-list>` with `<devtools-prompt>`, an inline editor row, or `UI.Dialog.Dialog`, or encapsulate `ListWidget` inside the view layer behind pure `ViewInput` data and callbacks), legacy `UI.TreeOutline.TreeOutline` / `TreeOutlineInShadow`, `extends UI.TreeOutline.TreeElement` subclasses, `UI.ListControl.ListControl`, or `UI.InplaceEditor` in newly authored UI or in CLs claiming to complete a UI Eng Vision migration (`Fixed: <id>`) (noting that ESLint `@devtools/no-imperative-dom-api` does not flag `extends UI.TreeOutline.TreeElement` subclasses or `UI.ListControl`), migrated `UI.Widget` subclasses with `DEFAULT_VIEW` whose constructor omits `element?: HTMLElement` as its first parameter (`constructor(element?: HTMLElement, ..., view: View = DEFAULT_VIEW)` so the widget can be instantiated via `${widget(MyWidget, ...)}`), or omits `static override readonly INJECT` when requesting `Universe`-managed dependencies, imperative `UI.TabbedPane.TabbedPane` or `StackLocation` passed via `ViewInput` instead of declarative `<devtools-tabbed-pane>` / `<devtools-stack-pane>` in the view, `private ` keyword instead of `#` in new UI classes, `<devtools-*>` tags in Lit templates without importing the corresponding component module entrypoint (e.g. `import * as Buttons from '../../ui/components/buttons/buttons.js'`), or formatting dates or timestamps with `toLocaleString()` inside sortable `<devtools-data-grid>` cells without a numeric/ISO sort value (sorts alphabetically instead of chronologically; use `toISOString()` or a numeric sort value).
9
+ - **Do not flag**: Overriding inherited `protected` lifecycle methods on framework base classes (e.g. extending `UI.Widget.Widget`). Explicitly scoped intermediate CLs (`Bug: <id>`, not `Fixed: <id>`) in a multi-CL migration that refactor presenter/item state in place while deferring `<devtools-tree>` or `UI.ListControl` replacement to a follow-up CL.
10
10
 
11
- **Why.** Legacy `UI.Fragment`, `DataGridImpl`, `LitElement`, `new Icon()`, `Link.create()`, `UI.XLink.XLink.create()`, `UI.ListWidget.ListWidget`, imperative `UI.TabbedPane.TabbedPane` / `StackLocation`, 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. In particular, keeping `this.list = new UI.ListWidget.ListWidget(this)` and `implements UI.ListWidget.Delegate` on a migrated presenter (imperatively calling `this.list.clear()`, `this.list.appendItem()`, `this.list.addNewItem()`, using `DocumentFragment` adapters in `renderItem`/`beginEdit`, and passing `list` in `ViewInput` to `WrapperWidget`) leaks view widgets into presenter state; replace `ListWidget` + `ListWidget.Delegate` with `<devtools-list>` (or, if preserving legacy `ListWidget.Editor` screenshot goldens temporarily, move `ListWidget` and `ListWidget.Delegate` ownership into the view layer and pass only pure data and callbacks in `ViewInput`).
11
+ **Why.** Legacy `UI.Fragment`, `DataGridImpl`, `LitElement`, `new Icon()`, `Link.create()`, `UI.XLink.XLink.create()`, `UI.TreeOutline`, `UI.ListControl`, `UI.InplaceEditor`, `UI.ListWidget.ListWidget`, imperative `UI.TabbedPane.TabbedPane` / `StackLocation`, 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. Migrated widgets must expose the standard MVP constructor signature (`element?: HTMLElement, ..., view: View = DEFAULT_VIEW`) and declare `static override readonly INJECT` for dependency injection.
12
12
 
13
13
  ## Examples
14
14
 
@@ -18,6 +18,7 @@ Bad:
18
18
  import type * as Buttons from '../../ui/components/buttons/buttons.js';
19
19
  export class MyView extends UI.Widget.VBox {
20
20
  private grid = new DataGrid.DataGrid.DataGridImpl({...});
21
+ private tree = new UI.TreeOutline.TreeOutlineInShadow();
21
22
  }
22
23
  ```
23
24
 
@@ -26,7 +27,15 @@ Good:
26
27
  ```ts
27
28
  import * as Buttons from '../../ui/components/buttons/buttons.js';
28
29
  import * as DataGrid from '../../ui/legacy/components/data_grid/data_grid.js';
30
+ import '../../ui/kit/kit.js';
31
+
29
32
  export class MyView extends UI.Widget.VBox {
30
33
  #items: Item[] = [];
34
+ #view: View;
35
+
36
+ constructor(element?: HTMLElement, view: View = DEFAULT_VIEW) {
37
+ super(element);
38
+ this.#view = view;
39
+ }
31
40
  }
32
41
  ```
@@ -5,10 +5,10 @@ severity: should_fix
5
5
  ---
6
6
 
7
7
  **Rule.** Keep UI.Widget view functions pure and stateless by computing presentation data in presenters and passing decoupled ViewInput data structures
8
- - **Look for**: `DEFAULT_VIEW` or view helper functions calling `Common.Settings.Settings.instance()`, `UI.Context.Context.instance()`, `SDK.TargetManager.TargetManager.instance()`, `Host.*`, or mutating model or `input.*` state in place; `ViewInput` interfaces carrying pre-created DOM `Element`/`HTMLElement` nodes or `UI.Widget` instances (`ListWidget`, `TabbedPane`, `Linkifier` elements); presenters calling `DEFAULT_VIEW(...)` or auxiliary `*_VIEW(...)` constants directly instead of injecting `view: View = DEFAULT_VIEW` via the constructor (`this.#view(...)`) and exporting `ViewInput` and `View`; 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>`).
8
+ - **Look for**: `DEFAULT_VIEW` or view helper functions calling `Common.Settings.Settings.instance()`, `UI.Context.Context.instance()`, `SDK.TargetManager.TargetManager.instance()`, `Host.*`, or mutating model or `input.*` state in place; `ViewInput` interfaces carrying pre-created DOM `Element`/`HTMLElement` nodes or `UI.Widget` instances (`ListWidget`, `TabbedPane`, `Linkifier` elements); presenters calling `DEFAULT_VIEW(...)` or auxiliary `*_VIEW(...)` constants directly instead of injecting `view: View = DEFAULT_VIEW` via the constructor (`this.#view(...)`) and exporting `ViewInput` and `View`; one-time lazy model/workspace initialization guards (`if (!this.#initialized) { ... }`) inside `performUpdate()` (side-effecting initialization belongs in `wasShown()`, keeping `performUpdate()` a pure projection of presenter state into `this.#view(...)`); 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>`).
9
9
  - **Do not flag**: Legacy `UI.Widget` subclasses that have not yet migrated to a `DEFAULT_VIEW` function, or passing read-only `Protocol.*`, `SDK.*`, or `Models.*` objects in `ViewInput` when the view only reads properties/getters from them or forwards them to child widgets/linkifiers without mutating model state or calling side-effecting `SDK` methods.
10
10
 
11
- **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.
11
+ **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, performing one-time initialization inside `performUpdate()`, or calling host/clipboard APIs inside the view couples rendering to global state and breaks isolated view testing.
12
12
 
13
13
  ## Examples
14
14
 
@@ -29,3 +29,32 @@ export const DEFAULT_VIEW = (input: ViewInput, _output: ViewOutput, target: HTML
29
29
  Lit.render(html`${input.sortedItems.map(item => html`<div>${item.name}</div>`)}`, target);
30
30
  };
31
31
  ```
32
+
33
+ Bad:
34
+
35
+ ```ts
36
+ override performUpdate(): void {
37
+ if (!this.#initialized) {
38
+ this.#initialized = true;
39
+ this.#initializeFromWorkspace(); // Side-effecting initialization in performUpdate
40
+ }
41
+ this.#view(this.#viewInput, undefined, this.contentElement);
42
+ }
43
+ ```
44
+
45
+ Good:
46
+
47
+ ```ts
48
+ override wasShown(): void {
49
+ super.wasShown();
50
+ if (!this.#initialized) {
51
+ this.#initialized = true;
52
+ this.#initializeFromWorkspace();
53
+ }
54
+ this.requestUpdate();
55
+ }
56
+
57
+ override performUpdate(): void {
58
+ this.#view(this.#viewInput, undefined, this.contentElement);
59
+ }
60
+ ```
@@ -4,11 +4,11 @@ rubric: design
4
4
  severity: should_fix
5
5
  ---
6
6
 
7
- **Rule.** Schedule widget re-renders asynchronously via this.requestUpdate() and guard property setters with equality checks
8
- - **Look for**: Widget property setters calling `this.performUpdate()` or `this.#view(...)` directly, setters calling `this.requestUpdate()` without checking `if (this.#prop === value) return;`, monolithic `set data(...)` object setters on `UI.Widget` subclasses instead of individual property setters, or synchronous `this.performUpdate()` calls inside a `UI.Widget` `constructor()` (creates DOM and reads `UI.Context` before the widget is attached or visible; use `this.requestUpdate()` or `wasShown()` instead).
9
- - **Do not flag**: Internal test helpers or synchronous initialization paths explicitly documented as requiring immediate flush. Synchronous `this.performUpdate()` calls in a constructor when the constructor or methods callable before `wasShown()` depend on `ViewOutput`, `widgetRef`, or `ref` fields populated by the initial render.
7
+ **Rule.** Schedule widget re-renders asynchronously via this.requestUpdate(), avoid synchronous performUpdate() in presenter methods, and guard property setters with equality checks
8
+ - **Look for**: Widget property setters calling `this.performUpdate()` or `this.#view(...)` directly, setters calling `this.requestUpdate()` without checking `if (this.#prop === value) return;`, monolithic `set data(...)` object setters on `UI.Widget` subclasses instead of individual property setters, synchronous `this.performUpdate()` calls inside a `UI.Widget` `constructor()` (creates DOM and reads `UI.Context` before the widget is attached or visible; use `this.requestUpdate()` or `wasShown()` instead), synchronous `this.performUpdate()` calls in presenter methods, event handlers, selection/expansion/rename handlers, or helper nodes when scheduling an asynchronous `this.requestUpdate()` suffices (callers and tests should `await widget.updateComplete` when inspecting post-render DOM), custom `#renderView()` or `#render()` methods on `UI.Widget` subclasses that invoke `this.#view(...)` directly bypassing `override performUpdate()` and `this.requestUpdate()`, or view-layer refresh methods on presenter or presenter-node classes (such as `updateTrailingIcons()`, `updateIcon()`, `updateTreeElement()`) that push visual updates imperatively instead of mutating pure presenter state and calling `this.requestUpdate()` so `DEFAULT_VIEW` computes icons, badges, and tooltips declaratively.
9
+ - **Do not flag**: Internal test helpers, `legacy_test_runner` helpers, or synchronous initialization paths explicitly documented as requiring immediate flush. Synchronous `this.performUpdate()` calls in a constructor when the constructor or methods callable before `wasShown()` depend on `ViewOutput`, `widgetRef`, or `ref` fields populated by the initial render. `UI.Panel.Panel` or `UI.Dialog.Dialog` subclasses where `requestUpdate()` is unavailable and calling `performUpdate()` is required. Popover or tooltip widgets instantiated inside `setTimeout` or before element bounds measurement where synchronous DOM rendering is necessary before measuring dimensions.
10
10
 
11
- **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()`.
11
+ **Why.** Calling `this.performUpdate()` or invoking `this.#view(...)` synchronously inside property setters, presenter event handlers, or helper methods causes redundant synchronous DOM renders and layout thrashing when multiple pieces of state change in the same tick. Presenter methods and setters should mutate state, short-circuit if unchanged, and schedule re-rendering asynchronously via `this.requestUpdate()`. Presenter nodes must not retain imperative view-refresh methods; all visual representations should be derived declaratively in the view function.
12
12
 
13
13
  ## Examples
14
14
 
@@ -19,6 +19,17 @@ set items(items: Item[]) {
19
19
  this.#items = items;
20
20
  this.performUpdate();
21
21
  }
22
+
23
+ selectNode(node: MyNode): void {
24
+ this.#selectedNode = node;
25
+ this.performUpdate(); // Synchronous render in presenter method
26
+ }
27
+
28
+ updateTrailingIcons(): void {
29
+ // Imperative view-layer helper on presenter node
30
+ this.#trailingIcons = [renderIcon()];
31
+ this.performUpdate();
32
+ }
22
33
  ```
23
34
 
24
35
  Good:
@@ -31,4 +42,12 @@ set items(items: Item[]) {
31
42
  this.#items = items;
32
43
  this.requestUpdate();
33
44
  }
45
+
46
+ selectNode(node: MyNode): void {
47
+ if (this.#selectedNode === node) {
48
+ return;
49
+ }
50
+ this.#selectedNode = node;
51
+ this.requestUpdate();
52
+ }
34
53
  ```
@@ -4,11 +4,11 @@ rubric: correctness
4
4
  severity: blocking
5
5
  ---
6
6
 
7
- **Rule.** Attach listeners to external models and managers in wasShown and detach them symmetrically in willHide
8
- - **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, scheduled or asynchronous `performUpdate()` methods on `SDKModelObserver` widgets that access or re-register a model without checking that `this.#model` is still active after `modelRemoved()` has run, or calling `removeChildren()` on a DOM or `TreeOutline` container that hosts imperatively mounted `UI.Widget` children without first detaching them (`this.detachChildWidgets()` or `UI.Widget.Widget.get(el)?.detach()`).
7
+ **Rule.** Attach listeners to external models and managers in wasShown and detach them symmetrically in willHide without wiping populated UI state on re-show
8
+ - **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, `wasShown()` or subscription implementations that unconditionally `reset()` or wipe already-populated presenter UI state (such as expanded tree folders, selection, or filter state) when a hidden widget is shown again instead of initializing once and incrementally reconciling model/workspace/setting changes that occurred while hidden, scheduled or asynchronous `performUpdate()` methods on `SDKModelObserver` widgets that access or re-register a model without checking that `this.#model` is still active after `modelRemoved()` has run, or calling `removeChildren()` on a DOM or `TreeOutline` container that hosts imperatively mounted `UI.Widget` children without first detaching them (`this.detachChildWidgets()` or `UI.Widget.Widget.get(el)?.detach()`).
9
9
  - **Do not flag**: Listeners attached to the widget's own internal DOM elements (`this.contentElement`), which are garbage-collected together with the widget. Model or target listeners on background recording/overview widgets (such as `NetworkOverview`) that must continuously record events while the widget is hidden or collapsed (especially when rendering is already gated on `this.isShowing()`), or pre-existing constructor listeners untouched by a DOM-to-Lit view migration.
10
10
 
11
- **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.
11
+ **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. Conversely, unconditionally resetting presenter state on `wasShown()` destroys expanded tree nodes and user selections whenever the user switches away and back to the tab.
12
12
 
13
13
  ## Examples
14
14
 
@@ -36,3 +36,34 @@ override willHide(): void {
36
36
  SDK.DOMModel.DOMModel, SDK.DOMModel.Events.DocumentUpdated, this.#onUpdate, this);
37
37
  }
38
38
  ```
39
+
40
+ Bad:
41
+
42
+ ```ts
43
+ override wasShown(): void {
44
+ super.wasShown();
45
+ this.#reset(); // Destroys open folders and selection every time tab is shown!
46
+ this.#subscribe();
47
+ this.requestUpdate();
48
+ }
49
+ ```
50
+
51
+ Good:
52
+
53
+ ```ts
54
+ override wasShown(): void {
55
+ super.wasShown();
56
+ if (!this.#initialized) {
57
+ this.#initialized = true;
58
+ this.#populateInitialState();
59
+ } else {
60
+ this.#reconcileState(); // Incrementally updates changes that occurred while hidden
61
+ }
62
+ this.#subscribe();
63
+ this.requestUpdate();
64
+ }
65
+ override willHide(): void {
66
+ super.willHide();
67
+ this.#unsubscribe();
68
+ }
69
+ ```
@@ -42,6 +42,7 @@ Load the skill or `.agents/rules/` files that match what the diff touches, and a
42
42
  | Ported Chromium web tests (`web_tests/http/tests/devtools`) | `migrate-chromium-test` |
43
43
  | Flaky or disabled tests, or `it.skip` / `it.skipOnPlatforms` | `fix-tests` |
44
44
  | Rendering user-controlled strings (URLs, names, console text) | `devtools-unicode-escaping` |
45
+ | Adding or modifying `UIStrings` or `@description` / `@example` L10n comments | `devtools-uistrings` |
45
46
  | `front_end/models/*`, `BUILD.gn`, `devtools_grd_files.gni`, entrypoints | `devtools-model-management` |
46
47
  | Reviewing foundation, models, and build configs (`front_end/(core|models|entrypoints|generated)/**`, `BUILD.gn`, `*.gni`) | `.agents/rules/models-and-core/*.md` |
47
48
  | Merging modules or consolidating `BUILD.gn` | `merging-devtools-module` |
@@ -129,6 +130,13 @@ findings):
129
130
  scenario.
130
131
  - **Fail fast:** Throw or assert when a required value is missing. Don't let
131
132
  the test time out later.
133
+ - **Pre-migration tests for legacy widgets:** When reviewing tests added ahead of
134
+ replacing a legacy widget (`TreeOutline`, `DataGrid`, `ListControl`,
135
+ `ListWidget`), check that DOM/tree inspection is encapsulated in local test
136
+ helpers (`dumpTree()`, `findTreeItem()`, `activateRow()`) rather than
137
+ repeated across every `it()` block, and ask for `assertScreenshot(...)` golden
138
+ tests so visual regressions are caught independently of the legacy widget
139
+ implementation.
132
140
 
133
141
  ## 6. Test hygiene and cleanup
134
142
 
@@ -165,6 +173,25 @@ findings):
165
173
  characters.
166
174
  - For migrations and stacked series, list the legacy tests or files covered,
167
175
  and number the series (for example, `(13/16)`).
176
+ - **UI Eng Vision migration completeness & `Fixed:` vs `Bug:`**: Flag
177
+ `Fixed: <id>` on UI Eng Vision migration CLs when core violations remain in
178
+ the target file: legacy `UI.TreeOutline` or `extends UI.TreeOutline.TreeElement`
179
+ subclasses, `UI.ListControl`, `UI.ListWidget`, `UI.InplaceEditor`, non-MVP
180
+ constructors (missing `element?: HTMLElement` or injectable `view = DEFAULT_VIEW`),
181
+ missing `static override readonly INJECT` for Universe dependencies, custom
182
+ `#renderView()` helpers bypassing `override performUpdate()` +
183
+ `this.requestUpdate()`, constructor-bound model/setting listeners instead of
184
+ non-destructive `wasShown()`/`willHide()` subscriptions, synchronous
185
+ `this.performUpdate()` calls in presenter methods, or TypeScript `private`
186
+ fields not required by `legacy_test_runner`/`blink/web_tests`. Note
187
+ explicitly that a clean `@devtools/no-imperative-dom-api` lint pass does
188
+ **not** prove completeness because ESLint misses `TreeElement` subclasses and
189
+ `UI.ListControl`. Intermediate CLs in a multi-CL migration must use
190
+ `Bug: <id>`, reserving `Fixed: <id>` for the final CL.
191
+ - **Component contract preservation**: Flag feature or panel migrations that
192
+ widen `front_end/ui/legacy/` component contracts (such as exporting internal
193
+ classes or turning `*ForTest()` or `*ForTesting()` methods on `Treeoutline.ts`
194
+ into public APIs).
168
195
  - Disabled tests reference a bug.
169
196
  - Presubmit, lint, and format pass. See `devtools-verification`.
170
197
 
@@ -0,0 +1,147 @@
1
+ ---
2
+ name: devtools-uistrings
3
+ description: >-
4
+ Reviews added or modified UIStrings and localization (@description / @example)
5
+ comments in Chrome DevTools for UX writing style, inline backtick locking,
6
+ sentence case, UI glossary terminology, translator context, and sibling string
7
+ consistency beyond what ESLint and check-strings.js enforce. Use when a CL or
8
+ local diff adds or edits UIStrings or i18n calls in front_end/. Don't use for
9
+ syntax rules already enforced by l10n ESLint rules or for unlocalized locked
10
+ strings.
11
+ ---
12
+
13
+ # Reviewing DevTools `UIStrings` and Localization Comments
14
+
15
+ Apply these checks when a diff adds or modifies `const UIStrings = { ... }`
16
+ entries or their JSDoc comments in `front_end/`.
17
+
18
+ ## 1. Do Not Flag
19
+
20
+ - **Already enforced by ESLint (`scripts/eslint_rules/lib/l10n-*.ts`):** Do not
21
+ comment on curly apostrophes (`’`) vs. straight quotes (`"`) inside
22
+ `UIStrings` values, Unicode ellipses (`…`) vs. `...`, uppercase `URL`,
23
+ negative contractions (`don’t`, `can’t`, `isn’t`, etc.), single- vs.
24
+ multi-sentence trailing periods, whole-phrase backtick locking, or unused keys
25
+ in regular `*.ts` files.
26
+ - **Already enforced by `third_party/i18n/check-strings.js`:** Do not comment
27
+ on missing/empty `@description` tags, missing `@example` tags for `{PH1}`
28
+ placeholders, unclosed backticks, malformed Markdown links, or `\n` literals.
29
+ - **Exempt strings:** Do not flag `UIStringsNotTranslate`,
30
+ `i18n.i18n.lockedString(...)`, or pre-existing `UIStrings` entries that were
31
+ not modified (including verbatim moves during a refactor).
32
+ - **Non-issues:** Do not nitpick minor `@description` lead-in wording variations
33
+ that are equally clear to translators (e.g., `Tooltip text for…` vs. `Tooltip
34
+ for…`), and do not force synonym swaps where grammar or spec precision breaks
35
+ (e.g., `a suitable Cross-Origin Resource Policy` where `a fit …` is
36
+ ungrammatical, or RFC terms like `additional parameters`).
37
+
38
+ ## 2. Shared Capitalization & DevTools UI Terminology
39
+
40
+ Apply these rules consistently in both `UIStrings` values and `@description`
41
+ comments:
42
+
43
+ - **Sentence case:** Capitalize only the first word, proper nouns, product
44
+ names (`Chrome DevTools`), acronyms, backtick-locked spec terms (e.g.,
45
+ `` '`Trusted Type` violations' ``), and web platform APIs / worker types
46
+ (`Background Fetch API`, `Service Worker` / `Service Workers`, `Web Worker` /
47
+ `Web Workers`).
48
+ - **Panels vs. features/concepts:**
49
+ - Capitalize user-facing panel names (`Console`, `Network`, `Elements`,
50
+ `Sources`, `Performance`, `Memory`, `Application`, `Security`,
51
+ `Lighthouse`, `Recorder`, `Issues`). For multi-word panel or tab names,
52
+ capitalize only the first word (`Developer resources panel`, `Memory
53
+ inspector panel`, `Remote devices tab`). When paired with a noun, keep the
54
+ second word lowercase (`Console panel`, `Console sidebar`, `Memory panel`).
55
+ - Map internal folder or class names to user-facing panel names (`profiler` ->
56
+ `Memory panel`, `Timeline UIUtils` -> `Performance panel`,
57
+ `linear_memory_inspector` -> `Memory inspector panel`).
58
+ - Keep feature, view, tool, and concept names **lowercase** unless starting a
59
+ sentence (`conditional breakpoint`, `command menu`, `quick open`, `heap
60
+ profiler`, `heap snapshot view`, `allocation sampling`, `isolate selector`,
61
+ `summary view`, `console message`, `network log`).
62
+ - **UI glossary & platform terms:** Use `panel`, `tab`, `drawer`, `sidebar`,
63
+ `table` (or `datagrid`), `action bar`, and `status bar`; never call a tab,
64
+ sidebar, or section a `pane`. Prefer `JavaScript modules` over `ES modules`,
65
+ and write `top level` with a space when used as a noun (`The top level of
66
+ JavaScript modules`).
67
+
68
+ ## 3. User-Facing String Values
69
+
70
+ - **Prefer short, everyday synonyms (when grammatical and spec-accurate):**
71
+ - `preserve` -> `keep` | `additional` -> `more` | `prevent` -> `stop`
72
+ - `submit` -> `send` | `modification` -> `change` | `create` -> `add` |
73
+ `suitable` -> `fit`
74
+ - `receive` -> `get` in general prose (e.g., `get the reports`), **except**
75
+ keep `receive` / `received` for network or worker data/message reception
76
+ (e.g., `receive data while cached`, `received a message from a
77
+ SharedWorker`).
78
+ - **Cut filler, politeness & banned branding:** Remove `please`, `sorry`,
79
+ `very`, `strongly`, `there is` / `there are`, marketing adjectives
80
+ (`seamless`, `awesome`, `fast`, `quick`), and `"Powered by AI"` (use neutral
81
+ action labels such as `'Understand this message'`).
82
+ - **Inline backtick-locking (`\`...\``):** Wrap embedded technical tokens (CSS
83
+ properties, values, and media features like `` `print` ``, `` `screen` ``,
84
+ `` `prefers-color-scheme` ``; HTTP headers like `` `Alt-Svc` ``; HTML
85
+ attributes; and JS APIs like `` `console.clear()` ``) in backticks so
86
+ translators do not translate them. Keep spec capitalization inside backticks
87
+ while using sentence case outside (`` '`Trusted Type` violations' ``).
88
+ - **Articles, positive contractions, symbols & actionability:** Avoid fragile
89
+ `a` / `an` articles before `{PH1}` placeholders or initialisms (`HTTP`, `XHR`)
90
+ when shorter article-free phrasing works. Use natural positive contractions
91
+ not checked by ESLint (`it’s`, `you’re`, `we’re`, `that’s`, with curly `’`),
92
+ and use prime (`′`) and double prime (`″`) for measurements or coordinates.
93
+ State how to recover in error messages (e.g., `Shorten filename to 64
94
+ characters or less` instead of `Invalid filename`).
95
+
96
+ ## 4. Localization Comments (`@description` & `@example`)
97
+
98
+ - **Explain UI role and concrete sub-location, never repeat the string:**
99
+ Inspect where `UIStrings.<key>` is called and name the UI element type (button
100
+ label, tooltip, column header, checkbox label, context menu item,
101
+ `aria-label`, status text) and concrete panel/sub-view location instead of
102
+ echoing the message text. Keep specific sub-locations such as `in the summary
103
+ view of the Performance panel` rather than collapsing them to `in the
104
+ Performance panel`.
105
+ - **No internal code or protocol names:** Do not reference C++ identifiers, CDP
106
+ enum names, or class names in `@description` comments. Describe the
107
+ user-visible state instead.
108
+ - **Verify `@example` values against the call site:** Check what
109
+ `i18nString(UIStrings.<key>, {PH1: ...})` passes at runtime (especially
110
+ whether units like `%` or `ms` are already formatted inside `{PH1}` vs.
111
+ outside in the template, e.g., `@example {12.34%} PH2`) and use realistic
112
+ runtime values rather than type names like `{string}`. Do not ask for
113
+ `@example` tags on ICU plural count variables.
114
+ - **Comment formatting:** Use straight apostrophes (`'`) and straight quotes
115
+ (`"`) in code comments (even when `UIStrings` uses curly `’`), and end every
116
+ `@description` with a period (`.`).
117
+
118
+ ```ts
119
+ // Bad: repeats the string, uses internal/legacy names, unlocked token, vague example
120
+ /**
121
+ * @description Text for preserve log checkbox in Timeline UIUtils Pane
122
+ * @example {string} PH1
123
+ */
124
+ preserveLog: 'Please preserve additional print log entries in {PH1}',
125
+
126
+ // Good: role + sub-location, sentence case, locked token, realistic example
127
+ /**
128
+ * @description Checkbox label in the summary view of the Performance panel to
129
+ * keep log entries across page loads.
130
+ * @example {https://example.com} PH1
131
+ */
132
+ keepLog: 'Keep more `print` log entries for {PH1}',
133
+ ```
134
+
135
+ ## 5. Neighbor, Module & Linter-Gap Consistency
136
+
137
+ - **Adjacent `UIStrings` & `-meta.ts` alignment:** Compare added or edited
138
+ entries against neighboring entries in the same `UIStrings` block and
139
+ companion `-meta.ts` file so panel names, feature casing, inline backticks,
140
+ and separators (`or` vs. `/`) stay consistent across sibling strings.
141
+ - **Quoted label renames:** When a CL renames a setting or button label (e.g.,
142
+ `Preserve log` -> `Keep log`), check sibling files in the same module for
143
+ explanatory `UIStrings` that quote the old label (e.g., `` '`console.clear()`
144
+ was prevented due to \'Keep log\'' ``) and update them together.
145
+ - **Unused keys in linter-exempt files:** `l10n-no-unused-message` skips
146
+ `ModuleUIStrings.ts` and `models/trace/insights/*.ts`; flag orphaned keys
147
+ left behind in those files when their last caller is removed.
@@ -114,6 +114,33 @@ existing element containers.
114
114
  * **Accessibility Preservation**: Convert custom accessibility
115
115
  instrumentation (like `ARIAUtils.markAsAlert()`) to native ARIA
116
116
  attributes in the template (e.g., `role="alert"`, `aria-live="polite"`).
117
+ * **Visibility (`?hidden` Attribute Only)**: Use `?hidden=${...}`
118
+ exclusively to toggle visibility in templates. Never combine a `.hidden`
119
+ CSS class (`classMap({hidden: ...})` or `classList.toggle('hidden', ...)`)
120
+ with `?hidden` (`inspectorCommon.css` already defines
121
+ `[hidden] { display: none !important; }`).
122
+ * **Declarative Default Focus (`autofocus` / `?autofocus`)**: Prefer
123
+ marking the default focused element with `autofocus` or `?autofocus=${...}`
124
+ in the template instead of collecting elements via `ref(...)` and plumbing
125
+ focus callbacks through `ViewOutput`. `UI.Widget.prototype.focus()`
126
+ queries `[autofocus]` automatically via `getDefaultFocusedElement()`.
127
+ * **`<devtools-tree>` & Persistent `<devtools-prompt ?editing>` Patterns**:
128
+ When rendering `<devtools-tree .template=${html`<ul role="tree">...</ul>`}>`:
129
+ - Preserve `front_end/ui/legacy/Treeoutline.ts` contracts without
130
+ widening internal classes or exposing `TreeOutline` getters on the
131
+ presenter.
132
+ - Drive selection and expansion declaratively via `?selected`, `?open`,
133
+ `@select`, and `@expand`.
134
+ - Do not duplicate `aria-label` on inner prompts when the enclosing
135
+ `<li role="treeitem">` already labels the row, do not duplicate
136
+ `class="tree-element-title"` on inner spans (which compounds opacity
137
+ rules), and return `nothing` for trailing icons when none exist.
138
+ - Host editable `<devtools-prompt ?editing>` rows in a child `UI.Widget`
139
+ (`${widget(RowPromptWidget, {...})}`) so `<devtools-tree>`'s
140
+ `MutationObserver` does not re-clone the row and blur the active input.
141
+ - Ensure custom elements with state passed via JS properties (`.data`)
142
+ override `cloneNode(deep)` and reflect dynamic state via DOM
143
+ attributes so shadow clones stay updated.
117
144
 
118
145
  11. **Render Templates Syntax & Code Movement**:
119
146
 
@@ -238,4 +265,3 @@ existing element containers.
238
265
  5. ❓ **Split Views**: Does `<devtools-split-view>` have `flex: auto; height: 100%;` CSS and reuse existing split settings?
239
266
  6. ❓ **String Audit**: Did I verify that any removed `UIStrings` weren't from accidentally dropped UI branches?
240
267
  7. ❓ **Build**: Does the code compile and do visual tests pass with 0% diff?
241
-