chrome-devtools-frontend 1.0.1738725 → 1.0.1742811

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 (502) hide show
  1. package/.agents/rules/ui-and-widgets/ui-accessibility-and-semantic-html.md +1 -1
  2. package/.agents/rules/ui-and-widgets/ui-css-scoping-and-flex-layout.md +44 -7
  3. package/.agents/rules/ui-and-widgets/ui-lit-declarative-templates-and-directives.md +1 -1
  4. package/.agents/rules/ui-and-widgets/ui-view-output-and-callback-contracts.md +2 -2
  5. package/.agents/rules/ui-and-widgets/ui-widget-dom-and-listener-lifecycle.md +1 -1
  6. package/.agents/skills/code-review/SKILL.md +23 -6
  7. package/.agents/skills/devtools-verification/SKILL.md +2 -1
  8. package/.agents/skills/migrate-chromium-test/SKILL.md +1 -0
  9. package/.agents/skills/ui-eng-vision-local-lit-renderer/SKILL.md +27 -11
  10. package/.agents/skills/ui-eng-vision-orchestrator/SKILL.md +41 -23
  11. package/.agents/skills/ui-eng-vision-test-scaffolder/SKILL.md +12 -7
  12. package/.agents/skills/ui-eng-vision-widget-promoter/SKILL.md +3 -0
  13. package/.agents/skills/ui-widgets/SKILL.md +22 -7
  14. package/.agents/skills/version-control/SKILL.md +10 -1
  15. package/.agents/skills/visual-regression-audit/SKILL.md +88 -0
  16. package/.gitallowed +2 -1
  17. package/.stylelintignore +1 -0
  18. package/.stylelintrc.json +5 -1
  19. package/AUTHORS +1 -0
  20. package/DIR_METADATA +2 -1
  21. package/PRESUBMIT_test.py +143 -0
  22. package/config/owner/INFRA_OWNERS +0 -1
  23. package/docs/contributing/infrastructure.md +2 -2
  24. package/docs/ui_engineering.md +14 -4
  25. package/eslint.config.mjs +119 -9
  26. package/front_end/application_tokens.css +0 -65
  27. package/front_end/core/host/AidaClient.ts +1 -1
  28. package/front_end/core/host/AidaClientTypes.ts +2 -0
  29. package/front_end/core/host/AidaErrors.ts +3 -3
  30. package/front_end/core/host/AidaGcaTranslation.ts +39 -0
  31. package/front_end/core/host/GcaClient.ts +32 -20
  32. package/front_end/core/host/GcaTypes.ts +4 -2
  33. package/front_end/core/host/InspectorFrontendHostAPI.ts +2 -0
  34. package/front_end/core/i18n/DevToolsLocale.ts +0 -1
  35. package/front_end/core/sdk/DebuggerModel.ts +25 -13
  36. package/front_end/core/sdk/PreloadingModel.ts +2 -2
  37. package/front_end/core/sdk/RehydratingConnection.ts +59 -30
  38. package/front_end/core/sdk/SourceMap.ts +30 -3
  39. package/front_end/core/sdk/SourceMapRangeMappings.ts +57 -0
  40. package/front_end/core/sdk/StorageKeyManager.ts +0 -1
  41. package/front_end/core/sdk/Target.ts +6 -0
  42. package/front_end/core/sdk/TargetManager.ts +10 -4
  43. package/front_end/entrypoints/formatter_worker/JavaScriptFormatter.ts +5 -9
  44. package/front_end/entrypoints/heap_snapshot_worker/HeapSnapshot.ts +12 -2
  45. package/front_end/entrypoints/inspector_main/OutermostTargetSelector.ts +159 -52
  46. package/front_end/entrypoints/inspector_main/outermostTargetSelector.css +77 -25
  47. package/front_end/entrypoints/main/MainImpl.ts +32 -15
  48. package/front_end/models/ai_assistance/AiAgent2.ts +95 -46
  49. package/front_end/models/ai_assistance/AiConversation.ts +1 -1
  50. package/front_end/models/ai_assistance/agents/AiAgent.ts +9 -2
  51. package/front_end/models/ai_assistance/agents/ExecuteJavascript.ts +3 -2
  52. package/front_end/models/ai_assistance/agents/StylingAgent.snapshot.txt +1 -1
  53. package/front_end/models/ai_assistance/data_formatters/FileFormatter.ts +1 -1
  54. package/front_end/models/ai_assistance/data_formatters/PerformanceTraceFormatter.ts +5 -4
  55. package/front_end/models/ai_assistance/performance/AICallTree.ts +7 -9
  56. package/front_end/models/ai_assistance/performance/AIQueries.ts +4 -8
  57. package/front_end/models/ai_assistance/skills/SkillRegistry.ts +11 -1
  58. package/front_end/models/ai_assistance/skills/lighthouse.md +1 -0
  59. package/front_end/models/ai_assistance/skills/network.md +3 -4
  60. package/front_end/models/ai_assistance/skills/sources.md +1 -2
  61. package/front_end/models/ai_assistance/skills/styling.md +3 -4
  62. package/front_end/models/ai_assistance/tools/ExecuteJavaScript.ts +11 -3
  63. package/front_end/models/ai_assistance/tools/ListNetworkRequests.ts +84 -23
  64. package/front_end/models/ai_assistance/tools/ListSources.ts +41 -13
  65. package/front_end/models/badges/Badge.ts +0 -1
  66. package/front_end/models/bindings/ResourceMapping.ts +1 -1
  67. package/front_end/models/bindings/ResourceScriptMapping.ts +1 -1
  68. package/front_end/models/breakpoints/BreakpointManager.ts +2 -4
  69. package/front_end/models/breakpoints/RecurringPauseDetector.ts +140 -0
  70. package/front_end/models/breakpoints/breakpoints.ts +2 -1
  71. package/front_end/models/heap_snapshot/HeapSnapshotModel.ts +2 -2
  72. package/front_end/models/persistence/Automapping.ts +0 -1
  73. package/front_end/models/trace/Processor.ts +16 -7
  74. package/front_end/models/trace/README.md +17 -1
  75. package/front_end/models/trace/extras/ThirdParties.ts +4 -6
  76. package/front_end/models/trace/extras/TraceFilter.ts +16 -8
  77. package/front_end/models/trace/extras/TraceTree.ts +159 -125
  78. package/front_end/models/trace/handlers/ExtensionTraceDataHandler.ts +0 -5
  79. package/front_end/models/trace/handlers/MetaHandler.ts +3 -0
  80. package/front_end/models/trace/handlers/RendererHandler.ts +7 -6
  81. package/front_end/models/trace/handlers/SamplesHandler.ts +1 -1
  82. package/front_end/models/trace/handlers/types.ts +15 -0
  83. package/front_end/models/trace/helpers/Extensions.ts +1 -3
  84. package/front_end/models/trace/helpers/SamplesIntegrator.ts +155 -87
  85. package/front_end/models/trace/helpers/Trace.ts +19 -14
  86. package/front_end/models/trace/helpers/TreeHelpers.ts +38 -10
  87. package/front_end/models/trace/insights/SlowCSSSelector.ts +3 -3
  88. package/front_end/models/trace/lantern/metrics/LargestContentfulPaint.ts +19 -4
  89. package/front_end/models/trace/lantern/simulation/Simulator.ts +4 -1
  90. package/front_end/models/web_mcp/WebMCPModel.ts +19 -9
  91. package/front_end/panels/ai_assistance/AiAssistancePanel.ts +30 -3
  92. package/front_end/panels/ai_assistance/components/ChatMessage.ts +2 -4
  93. package/front_end/panels/ai_assistance/components/chatMessage.css +1 -22
  94. package/front_end/panels/ai_assistance/components/chatView.css +0 -180
  95. package/front_end/panels/ai_assistance/components/exploreWidget.css +1 -19
  96. package/front_end/panels/ai_assistance/components/optInChangeDialog.css +1 -1
  97. package/front_end/panels/ai_assistance/components/walkthroughView.css +0 -13
  98. package/front_end/panels/animation/AnimationGroupPreviewUI.ts +3 -2
  99. package/front_end/panels/animation/AnimationTimeline.ts +5 -3
  100. package/front_end/panels/animation/animationTimeline.css +10 -8
  101. package/front_end/panels/application/ApplicationPanelSidebar.ts +14 -11
  102. package/front_end/panels/application/ApplicationPanelTreeElement.ts +66 -3
  103. package/front_end/panels/application/ReportingApiView.ts +0 -1
  104. package/front_end/panels/application/SubAppsView.ts +0 -1
  105. package/front_end/panels/application/WebMCPTreeElement.ts +3 -6
  106. package/front_end/panels/application/WebMCPView.ts +30 -0
  107. package/front_end/panels/application/components/ReportsGrid.ts +0 -1
  108. package/front_end/panels/application/components/backForwardCacheView.css +1 -8
  109. package/front_end/panels/application/components/permissionsPolicySection.css +2 -2
  110. package/front_end/panels/application/components/protocolHandlersView.css +46 -39
  111. package/front_end/panels/application/components/trustTokensView.css +0 -4
  112. package/front_end/panels/application/cookieItemsView.css +0 -7
  113. package/front_end/panels/application/indexedDBViews.css +0 -6
  114. package/front_end/panels/application/preloading/components/PreloadingDetailsReportView.ts +0 -2
  115. package/front_end/panels/application/preloading/components/PreloadingString.ts +0 -1
  116. package/front_end/panels/application/preloading/components/UsedPreloadingView.ts +4 -5
  117. package/front_end/panels/application/preloading/components/preloadingGrid.css +0 -9
  118. package/front_end/panels/application/resourcesPanel.css +0 -48
  119. package/front_end/panels/application/serviceWorkerUpdateCycleView.css +2 -9
  120. package/front_end/panels/application/serviceWorkersView.css +5 -4
  121. package/front_end/panels/application/storageView.css +0 -5
  122. package/front_end/panels/application/webMCPView.css +17 -0
  123. package/front_end/panels/browser_debugger/ObjectEventListenersSidebarPane.ts +15 -20
  124. package/front_end/panels/changes/changesView.css +0 -5
  125. package/front_end/panels/common/ExtensionServer.ts +80 -10
  126. package/front_end/panels/console/ConsolePanel.ts +92 -18
  127. package/front_end/panels/console/consoleContextSelector.css +1 -8
  128. package/front_end/panels/console/consoleInsightTeaser.css +10 -17
  129. package/front_end/panels/console/consolePinPane.css +3 -1
  130. package/front_end/panels/console/consoleView.css +14 -18
  131. package/front_end/panels/coverage/coverageListView.css +0 -4
  132. package/front_end/panels/css_overview/cssOverviewCompletedView.css +0 -22
  133. package/front_end/panels/css_overview/cssOverviewStartView.css +0 -43
  134. package/front_end/panels/developer_resources/developerResourcesListView.css +0 -4
  135. package/front_end/panels/elements/ColorSwatchPopoverIcon.ts +52 -45
  136. package/front_end/panels/elements/LayoutPane.ts +1 -3
  137. package/front_end/panels/elements/PropertiesWidget.ts +26 -8
  138. package/front_end/panels/elements/PropertyRenderer.ts +45 -21
  139. package/front_end/panels/elements/StandaloneStylesContainer.ts +6 -7
  140. package/front_end/panels/elements/StyleEditorWidget.ts +110 -63
  141. package/front_end/panels/elements/StylePropertiesSection.ts +18 -14
  142. package/front_end/panels/elements/StylePropertyTreeElement.ts +556 -527
  143. package/front_end/panels/elements/StylesContainer.ts +5 -6
  144. package/front_end/panels/elements/StylesSidebarPane.ts +12 -15
  145. package/front_end/panels/elements/classesPaneWidget.css +3 -7
  146. package/front_end/panels/elements/components/CSSQuery.ts +6 -5
  147. package/front_end/panels/elements/components/CSSVariableValueView.ts +17 -4
  148. package/front_end/panels/elements/components/StylePropertyEditor.ts +178 -140
  149. package/front_end/panels/elements/components/cssQuery.css +1 -1
  150. package/front_end/panels/elements/components/stylePropertyEditor.css +60 -56
  151. package/front_end/panels/elements/layoutPane.css +2 -2
  152. package/front_end/panels/elements/metricsSidebarPane.css +7 -8
  153. package/front_end/panels/elements/platformFontsWidget.css +1 -1
  154. package/front_end/panels/elements/stylePropertiesTreeOutline.css +1 -12
  155. package/front_end/panels/elements/stylesSidebarPane.css +3 -5
  156. package/front_end/panels/emulation/deviceModeView.css +1 -1
  157. package/front_end/panels/event_listeners/EventListenersView.ts +9 -2
  158. package/front_end/panels/event_listeners/eventListenersView.css +1 -1
  159. package/front_end/panels/explain/components/consoleInsight.css +1 -7
  160. package/front_end/panels/issues/AffectedBlockedByResponseView.ts +88 -46
  161. package/front_end/panels/issues/AffectedHeavyAdView.ts +72 -43
  162. package/front_end/panels/issues/AffectedResourcesView.ts +81 -13
  163. package/front_end/panels/issues/GenericIssueDetailsView.ts +112 -32
  164. package/front_end/panels/issues/issues.ts +2 -0
  165. package/front_end/panels/issues/issuesTree.css +13 -43
  166. package/front_end/panels/layer_viewer/PaintProfilerView.ts +1 -1
  167. package/front_end/panels/layer_viewer/layerDetailsView.css +1 -1
  168. package/front_end/panels/layer_viewer/paintProfiler.css +4 -3
  169. package/front_end/panels/lighthouse/LighthouseReportSelector.ts +1 -6
  170. package/front_end/panels/lighthouse/lighthousePanel.css +0 -9
  171. package/front_end/panels/lighthouse/lighthouseStartView.css +5 -16
  172. package/front_end/panels/linear_memory_inspector/components/LinearMemoryValueInterpreter.ts +0 -1
  173. package/front_end/panels/linear_memory_inspector/components/linearMemoryHighlightChipList.css +2 -2
  174. package/front_end/panels/linear_memory_inspector/components/linearMemoryValueInterpreter.css +2 -2
  175. package/front_end/panels/linear_memory_inspector/components/linearMemoryViewer.css +2 -2
  176. package/front_end/panels/linear_memory_inspector/components/valueInterpreterSettings.css +1 -1
  177. package/front_end/panels/media/playerListView.css +1 -2
  178. package/front_end/panels/media/playerPropertiesView.css +1 -1
  179. package/front_end/panels/mobile_throttling/throttlingSettingsTab.css +4 -4
  180. package/front_end/panels/network/NetworkLogView.ts +603 -582
  181. package/front_end/panels/network/RequestCookiesView.ts +0 -1
  182. package/front_end/panels/network/RequestTimingView.ts +16 -2
  183. package/front_end/panels/network/networkConfigView.css +3 -4
  184. package/front_end/panels/network/networkLogView.css +363 -377
  185. package/front_end/panels/network/networkPanel.css +1 -7
  186. package/front_end/panels/network/networkTimingTable.css +12 -27
  187. package/front_end/panels/network/networkWaterfallColumn.css +1 -1
  188. package/front_end/panels/network/requestConditionsDrawer.css +0 -4
  189. package/front_end/panels/network/requestCookiesView.css +7 -1
  190. package/front_end/panels/network/requestPayloadTree.css +0 -4
  191. package/front_end/panels/profiler/HeapProfileView.ts +1 -3
  192. package/front_end/panels/profiler/HeapSnapshotView.ts +0 -7
  193. package/front_end/panels/profiler/profilesPanel.css +0 -11
  194. package/front_end/panels/recorder/ControlButton.ts +1 -1
  195. package/front_end/panels/recorder/RecorderPanel.ts +1 -1
  196. package/front_end/panels/recorder/RecordingView.ts +32 -11
  197. package/front_end/panels/recorder/StepView.ts +31 -5
  198. package/front_end/panels/recorder/TimelineSection.ts +22 -6
  199. package/front_end/panels/recorder/controlButton.css +2 -9
  200. package/front_end/panels/recorder/createRecordingView.css +1 -1
  201. package/front_end/panels/recorder/recorderPanel.css +0 -9
  202. package/front_end/panels/recorder/recordingListView.css +4 -4
  203. package/front_end/panels/recorder/recordingView.css +44 -52
  204. package/front_end/panels/recorder/replaySection.css +2 -0
  205. package/front_end/panels/recorder/stepEditor.css +4 -4
  206. package/front_end/panels/recorder/stepView.css +47 -21
  207. package/front_end/panels/recorder/timelineSection.css +63 -83
  208. package/front_end/panels/screencast/ScreencastApp.ts +0 -1
  209. package/front_end/panels/search/searchView.css +1 -1
  210. package/front_end/panels/security/mainView.css +1 -1
  211. package/front_end/panels/security/originView.css +2 -2
  212. package/front_end/panels/sensors/SensorsView.ts +273 -361
  213. package/front_end/panels/settings/BackendLinkingSettingsTab.ts +0 -1
  214. package/front_end/panels/settings/backendLinkingSettingsTab.css +7 -7
  215. package/front_end/panels/settings/components/syncSection.css +0 -1
  216. package/front_end/panels/settings/workspaceSettingsTab.css +0 -5
  217. package/front_end/panels/sources/CSSPlugin.ts +177 -98
  218. package/front_end/panels/sources/DebuggerPausedMessage.ts +100 -27
  219. package/front_end/panels/sources/NavigatorView.ts +926 -946
  220. package/front_end/panels/sources/SourcesPanel.ts +9 -2
  221. package/front_end/panels/sources/breakpointsView.css +6 -28
  222. package/front_end/panels/sources/components/HeadersView.css +2 -2
  223. package/front_end/panels/sources/debuggerPausedMessage.css +7 -0
  224. package/front_end/panels/sources/navigatorTree.css +7 -2
  225. package/front_end/panels/sources/sourcesNavigator.css +0 -9
  226. package/front_end/panels/sources/sourcesView.css +2 -1
  227. package/front_end/panels/sources/watchExpressionsSidebarPane.css +0 -10
  228. package/front_end/panels/timeline/CompatibilityTracksAppender.ts +3 -0
  229. package/front_end/panels/timeline/EventsTimelineTreeView.ts +18 -5
  230. package/front_end/panels/timeline/LayoutShiftsTrackAppender.ts +0 -10
  231. package/front_end/panels/timeline/ModificationsManager.ts +0 -1
  232. package/front_end/panels/timeline/ThreadAppender.ts +2 -6
  233. package/front_end/panels/timeline/TimelineController.ts +30 -26
  234. package/front_end/panels/timeline/TimelineDetailsView.ts +10 -9
  235. package/front_end/panels/timeline/TimelineFlameChartDataProvider.ts +4 -16
  236. package/front_end/panels/timeline/TimelineMiniMap.ts +132 -54
  237. package/front_end/panels/timeline/TimelinePanel.ts +2 -2
  238. package/front_end/panels/timeline/TimelineTreeView.ts +63 -50
  239. package/front_end/panels/timeline/TimelineUIUtils.ts +8 -10
  240. package/front_end/panels/timeline/components/DetailsView.ts +7 -14
  241. package/front_end/panels/timeline/components/LayoutShiftDetails.ts +0 -2
  242. package/front_end/panels/timeline/components/NetworkTrackWidget.ts +5 -1
  243. package/front_end/panels/timeline/components/fieldSettingsDialog.css +1 -6
  244. package/front_end/panels/timeline/components/insights/baseInsightComponent.css +0 -12
  245. package/front_end/panels/timeline/components/interactionBreakdown.css +1 -1
  246. package/front_end/panels/timeline/components/layoutShiftDetails.css +2 -9
  247. package/front_end/panels/timeline/components/liveMetricsView.css +0 -16
  248. package/front_end/panels/timeline/components/metricCard.css +1 -5
  249. package/front_end/panels/timeline/components/networkRequestDetails.css +3 -3
  250. package/front_end/panels/timeline/components/networkRequestTooltip.css +6 -4
  251. package/front_end/panels/timeline/components/networkTrackWidget.css +1 -1
  252. package/front_end/panels/timeline/components/sidebarAnnotationsTab.css +1 -1
  253. package/front_end/panels/timeline/components/sidebarInsightsTab.css +1 -1
  254. package/front_end/panels/timeline/docs/profile_calls.md +7 -9
  255. package/front_end/panels/timeline/timelineDetailsView.css +1 -12
  256. package/front_end/panels/timeline/timelineFlamechartPopover.css +0 -4
  257. package/front_end/panels/timeline/timelineMiniMap.css +1 -4
  258. package/front_end/panels/timeline/timelinePanel.css +0 -4
  259. package/front_end/panels/timeline/timelineStatusDialog.css +1 -1
  260. package/front_end/panels/timeline/timelineTreeView.css +0 -12
  261. package/front_end/panels/timeline/utils/EntryNodes.ts +1 -1
  262. package/front_end/panels/webauthn/webauthnPane.css +2 -8
  263. package/front_end/panels/whats_new/ReleaseNoteText.ts +1 -1
  264. package/front_end/third_party/axe-core/README.chromium +2 -3
  265. package/front_end/third_party/chromium/README.chromium +1 -1
  266. package/front_end/third_party/puppeteer/README.chromium +2 -2
  267. package/front_end/third_party/puppeteer/package/lib/es5-iife/puppeteer-core-browser.d.ts +328 -11
  268. package/front_end/third_party/puppeteer/package/lib/es5-iife/puppeteer-core-browser.js +907 -588
  269. package/front_end/third_party/puppeteer/package/lib/puppeteer/api/Browser.d.ts +119 -1
  270. package/front_end/third_party/puppeteer/package/lib/puppeteer/api/Browser.d.ts.map +1 -1
  271. package/front_end/third_party/puppeteer/package/lib/puppeteer/api/Browser.js.map +1 -1
  272. package/front_end/third_party/puppeteer/package/lib/puppeteer/api/BrowserContext.d.ts +120 -1
  273. package/front_end/third_party/puppeteer/package/lib/puppeteer/api/BrowserContext.d.ts.map +1 -1
  274. package/front_end/third_party/puppeteer/package/lib/puppeteer/api/BrowserContext.js.map +1 -1
  275. package/front_end/third_party/puppeteer/package/lib/puppeteer/api/HTTPRequest.d.ts +16 -1
  276. package/front_end/third_party/puppeteer/package/lib/puppeteer/api/HTTPRequest.d.ts.map +1 -1
  277. package/front_end/third_party/puppeteer/package/lib/puppeteer/api/HTTPRequest.js +5 -1
  278. package/front_end/third_party/puppeteer/package/lib/puppeteer/api/HTTPRequest.js.map +1 -1
  279. package/front_end/third_party/puppeteer/package/lib/puppeteer/api/HTTPResponse.d.ts +26 -0
  280. package/front_end/third_party/puppeteer/package/lib/puppeteer/api/HTTPResponse.d.ts.map +1 -1
  281. package/front_end/third_party/puppeteer/package/lib/puppeteer/api/HTTPResponse.js.map +1 -1
  282. package/front_end/third_party/puppeteer/package/lib/puppeteer/api/Page.d.ts +23 -3
  283. package/front_end/third_party/puppeteer/package/lib/puppeteer/api/Page.d.ts.map +1 -1
  284. package/front_end/third_party/puppeteer/package/lib/puppeteer/api/Page.js +21 -14
  285. package/front_end/third_party/puppeteer/package/lib/puppeteer/api/Page.js.map +1 -1
  286. package/front_end/third_party/puppeteer/package/lib/puppeteer/api/locators/locators.d.ts +5 -5
  287. package/front_end/third_party/puppeteer/package/lib/puppeteer/api/locators/locators.d.ts.map +1 -1
  288. package/front_end/third_party/puppeteer/package/lib/puppeteer/api/locators/locators.js +4 -4
  289. package/front_end/third_party/puppeteer/package/lib/puppeteer/api/locators/locators.js.map +1 -1
  290. package/front_end/third_party/puppeteer/package/lib/puppeteer/bidi/Browser.d.ts +6 -1
  291. package/front_end/third_party/puppeteer/package/lib/puppeteer/bidi/Browser.d.ts.map +1 -1
  292. package/front_end/third_party/puppeteer/package/lib/puppeteer/bidi/Browser.js +158 -67
  293. package/front_end/third_party/puppeteer/package/lib/puppeteer/bidi/Browser.js.map +1 -1
  294. package/front_end/third_party/puppeteer/package/lib/puppeteer/bidi/BrowserConnector.d.ts.map +1 -1
  295. package/front_end/third_party/puppeteer/package/lib/puppeteer/bidi/BrowserConnector.js +1 -0
  296. package/front_end/third_party/puppeteer/package/lib/puppeteer/bidi/BrowserConnector.js.map +1 -1
  297. package/front_end/third_party/puppeteer/package/lib/puppeteer/bidi/Connection.d.ts.map +1 -1
  298. package/front_end/third_party/puppeteer/package/lib/puppeteer/bidi/Connection.js +3 -1
  299. package/front_end/third_party/puppeteer/package/lib/puppeteer/bidi/Connection.js.map +1 -1
  300. package/front_end/third_party/puppeteer/package/lib/puppeteer/bidi/Frame.d.ts.map +1 -1
  301. package/front_end/third_party/puppeteer/package/lib/puppeteer/bidi/Frame.js +28 -5
  302. package/front_end/third_party/puppeteer/package/lib/puppeteer/bidi/Frame.js.map +1 -1
  303. package/front_end/third_party/puppeteer/package/lib/puppeteer/bidi/HTTPRequest.d.ts +4 -0
  304. package/front_end/third_party/puppeteer/package/lib/puppeteer/bidi/HTTPRequest.d.ts.map +1 -1
  305. package/front_end/third_party/puppeteer/package/lib/puppeteer/bidi/HTTPRequest.js +19 -11
  306. package/front_end/third_party/puppeteer/package/lib/puppeteer/bidi/HTTPRequest.js.map +1 -1
  307. package/front_end/third_party/puppeteer/package/lib/puppeteer/bidi/HTTPResponse.d.ts +2 -0
  308. package/front_end/third_party/puppeteer/package/lib/puppeteer/bidi/HTTPResponse.d.ts.map +1 -1
  309. package/front_end/third_party/puppeteer/package/lib/puppeteer/bidi/HTTPResponse.js +17 -5
  310. package/front_end/third_party/puppeteer/package/lib/puppeteer/bidi/HTTPResponse.js.map +1 -1
  311. package/front_end/third_party/puppeteer/package/lib/puppeteer/bidi/Input.d.ts.map +1 -1
  312. package/front_end/third_party/puppeteer/package/lib/puppeteer/bidi/Input.js +62 -4
  313. package/front_end/third_party/puppeteer/package/lib/puppeteer/bidi/Input.js.map +1 -1
  314. package/front_end/third_party/puppeteer/package/lib/puppeteer/bidi/NetworkEvents.d.ts +29 -0
  315. package/front_end/third_party/puppeteer/package/lib/puppeteer/bidi/NetworkEvents.d.ts.map +1 -0
  316. package/front_end/third_party/puppeteer/package/lib/puppeteer/bidi/NetworkEvents.js +60 -0
  317. package/front_end/third_party/puppeteer/package/lib/puppeteer/bidi/NetworkEvents.js.map +1 -0
  318. package/front_end/third_party/puppeteer/package/lib/puppeteer/bidi/Page.d.ts +9 -1
  319. package/front_end/third_party/puppeteer/package/lib/puppeteer/bidi/Page.d.ts.map +1 -1
  320. package/front_end/third_party/puppeteer/package/lib/puppeteer/bidi/Page.js +24 -9
  321. package/front_end/third_party/puppeteer/package/lib/puppeteer/bidi/Page.js.map +1 -1
  322. package/front_end/third_party/puppeteer/package/lib/puppeteer/bidi/Realm.d.ts.map +1 -1
  323. package/front_end/third_party/puppeteer/package/lib/puppeteer/bidi/Realm.js +16 -7
  324. package/front_end/third_party/puppeteer/package/lib/puppeteer/bidi/Realm.js.map +1 -1
  325. package/front_end/third_party/puppeteer/package/lib/puppeteer/bidi/core/Browser.d.ts +6 -0
  326. package/front_end/third_party/puppeteer/package/lib/puppeteer/bidi/core/Browser.d.ts.map +1 -1
  327. package/front_end/third_party/puppeteer/package/lib/puppeteer/bidi/core/Browser.js +37 -20
  328. package/front_end/third_party/puppeteer/package/lib/puppeteer/bidi/core/Browser.js.map +1 -1
  329. package/front_end/third_party/puppeteer/package/lib/puppeteer/bidi/core/BrowsingContext.d.ts +2 -0
  330. package/front_end/third_party/puppeteer/package/lib/puppeteer/bidi/core/BrowsingContext.d.ts.map +1 -1
  331. package/front_end/third_party/puppeteer/package/lib/puppeteer/bidi/core/BrowsingContext.js +10 -5
  332. package/front_end/third_party/puppeteer/package/lib/puppeteer/bidi/core/BrowsingContext.js.map +1 -1
  333. package/front_end/third_party/puppeteer/package/lib/puppeteer/bidi/core/Navigation.d.ts.map +1 -1
  334. package/front_end/third_party/puppeteer/package/lib/puppeteer/bidi/core/Navigation.js +18 -1
  335. package/front_end/third_party/puppeteer/package/lib/puppeteer/bidi/core/Navigation.js.map +1 -1
  336. package/front_end/third_party/puppeteer/package/lib/puppeteer/bidi/core/Request.d.ts.map +1 -1
  337. package/front_end/third_party/puppeteer/package/lib/puppeteer/bidi/core/Request.js +24 -5
  338. package/front_end/third_party/puppeteer/package/lib/puppeteer/bidi/core/Request.js.map +1 -1
  339. package/front_end/third_party/puppeteer/package/lib/puppeteer/cdp/Binding.d.ts.map +1 -1
  340. package/front_end/third_party/puppeteer/package/lib/puppeteer/cdp/Binding.js +6 -4
  341. package/front_end/third_party/puppeteer/package/lib/puppeteer/cdp/Binding.js.map +1 -1
  342. package/front_end/third_party/puppeteer/package/lib/puppeteer/cdp/ExtensionTransport.d.ts.map +1 -1
  343. package/front_end/third_party/puppeteer/package/lib/puppeteer/cdp/ExtensionTransport.js +30 -6
  344. package/front_end/third_party/puppeteer/package/lib/puppeteer/cdp/ExtensionTransport.js.map +1 -1
  345. package/front_end/third_party/puppeteer/package/lib/puppeteer/cdp/FrameManager.d.ts +2 -0
  346. package/front_end/third_party/puppeteer/package/lib/puppeteer/cdp/FrameManager.d.ts.map +1 -1
  347. package/front_end/third_party/puppeteer/package/lib/puppeteer/cdp/FrameManager.js +3 -0
  348. package/front_end/third_party/puppeteer/package/lib/puppeteer/cdp/FrameManager.js.map +1 -1
  349. package/front_end/third_party/puppeteer/package/lib/puppeteer/cdp/HTTPRequest.d.ts +5 -1
  350. package/front_end/third_party/puppeteer/package/lib/puppeteer/cdp/HTTPRequest.d.ts.map +1 -1
  351. package/front_end/third_party/puppeteer/package/lib/puppeteer/cdp/HTTPRequest.js +12 -2
  352. package/front_end/third_party/puppeteer/package/lib/puppeteer/cdp/HTTPRequest.js.map +1 -1
  353. package/front_end/third_party/puppeteer/package/lib/puppeteer/cdp/HTTPResponse.d.ts +3 -0
  354. package/front_end/third_party/puppeteer/package/lib/puppeteer/cdp/HTTPResponse.d.ts.map +1 -1
  355. package/front_end/third_party/puppeteer/package/lib/puppeteer/cdp/HTTPResponse.js +40 -0
  356. package/front_end/third_party/puppeteer/package/lib/puppeteer/cdp/HTTPResponse.js.map +1 -1
  357. package/front_end/third_party/puppeteer/package/lib/puppeteer/cdp/NetworkEventManager.d.ts +23 -1
  358. package/front_end/third_party/puppeteer/package/lib/puppeteer/cdp/NetworkEventManager.d.ts.map +1 -1
  359. package/front_end/third_party/puppeteer/package/lib/puppeteer/cdp/NetworkEventManager.js +37 -0
  360. package/front_end/third_party/puppeteer/package/lib/puppeteer/cdp/NetworkEventManager.js.map +1 -1
  361. package/front_end/third_party/puppeteer/package/lib/puppeteer/cdp/NetworkManager.d.ts +2 -0
  362. package/front_end/third_party/puppeteer/package/lib/puppeteer/cdp/NetworkManager.d.ts.map +1 -1
  363. package/front_end/third_party/puppeteer/package/lib/puppeteer/cdp/NetworkManager.js +74 -16
  364. package/front_end/third_party/puppeteer/package/lib/puppeteer/cdp/NetworkManager.js.map +1 -1
  365. package/front_end/third_party/puppeteer/package/lib/puppeteer/cdp/Page.d.ts +3 -2
  366. package/front_end/third_party/puppeteer/package/lib/puppeteer/cdp/Page.d.ts.map +1 -1
  367. package/front_end/third_party/puppeteer/package/lib/puppeteer/cdp/Page.js +34 -23
  368. package/front_end/third_party/puppeteer/package/lib/puppeteer/cdp/Page.js.map +1 -1
  369. package/front_end/third_party/puppeteer/package/lib/puppeteer/cdp/ResponseBodyStream.d.ts +10 -0
  370. package/front_end/third_party/puppeteer/package/lib/puppeteer/cdp/ResponseBodyStream.d.ts.map +1 -0
  371. package/front_end/third_party/puppeteer/package/lib/puppeteer/cdp/ResponseBodyStream.js +94 -0
  372. package/front_end/third_party/puppeteer/package/lib/puppeteer/cdp/ResponseBodyStream.js.map +1 -0
  373. package/front_end/third_party/puppeteer/package/lib/puppeteer/cdp/Target.d.ts +2 -2
  374. package/front_end/third_party/puppeteer/package/lib/puppeteer/cdp/Target.d.ts.map +1 -1
  375. package/front_end/third_party/puppeteer/package/lib/puppeteer/cdp/Target.js +29 -1
  376. package/front_end/third_party/puppeteer/package/lib/puppeteer/cdp/Target.js.map +1 -1
  377. package/front_end/third_party/puppeteer/package/lib/puppeteer/cdp/cdp.d.ts +1 -0
  378. package/front_end/third_party/puppeteer/package/lib/puppeteer/cdp/cdp.d.ts.map +1 -1
  379. package/front_end/third_party/puppeteer/package/lib/puppeteer/cdp/cdp.js +1 -0
  380. package/front_end/third_party/puppeteer/package/lib/puppeteer/cdp/cdp.js.map +1 -1
  381. package/front_end/third_party/puppeteer/package/lib/puppeteer/cdp/utils.d.ts.map +1 -1
  382. package/front_end/third_party/puppeteer/package/lib/puppeteer/cdp/utils.js +6 -5
  383. package/front_end/third_party/puppeteer/package/lib/puppeteer/cdp/utils.js.map +1 -1
  384. package/front_end/third_party/puppeteer/package/lib/puppeteer/common/ConsoleMessage.d.ts +4 -0
  385. package/front_end/third_party/puppeteer/package/lib/puppeteer/common/ConsoleMessage.d.ts.map +1 -1
  386. package/front_end/third_party/puppeteer/package/lib/puppeteer/common/ConsoleMessage.js.map +1 -1
  387. package/front_end/third_party/puppeteer/package/lib/puppeteer/common/EventEmitter.d.ts +4 -4
  388. package/front_end/third_party/puppeteer/package/lib/puppeteer/common/EventEmitter.d.ts.map +1 -1
  389. package/front_end/third_party/puppeteer/package/lib/puppeteer/common/EventEmitter.js +2 -2
  390. package/front_end/third_party/puppeteer/package/lib/puppeteer/common/EventEmitter.js.map +1 -1
  391. package/front_end/third_party/puppeteer/package/lib/puppeteer/common/util.d.ts.map +1 -1
  392. package/front_end/third_party/puppeteer/package/lib/puppeteer/common/util.js +34 -15
  393. package/front_end/third_party/puppeteer/package/lib/puppeteer/common/util.js.map +1 -1
  394. package/front_end/third_party/puppeteer/package/lib/puppeteer/node/BrowserLauncher.d.ts +3 -0
  395. package/front_end/third_party/puppeteer/package/lib/puppeteer/node/BrowserLauncher.d.ts.map +1 -1
  396. package/front_end/third_party/puppeteer/package/lib/puppeteer/node/BrowserLauncher.js +11 -7
  397. package/front_end/third_party/puppeteer/package/lib/puppeteer/node/BrowserLauncher.js.map +1 -1
  398. package/front_end/third_party/puppeteer/package/lib/puppeteer/node/ChromeLauncher.js +10 -7
  399. package/front_end/third_party/puppeteer/package/lib/puppeteer/node/ChromeLauncher.js.map +1 -1
  400. package/front_end/third_party/puppeteer/package/lib/puppeteer/revisions.d.ts +3 -3
  401. package/front_end/third_party/puppeteer/package/lib/puppeteer/revisions.js +3 -3
  402. package/front_end/third_party/puppeteer/package/lib/puppeteer/util/decorators.js.map +1 -1
  403. package/front_end/third_party/puppeteer/package/lib/puppeteer/util/version.d.ts +1 -1
  404. package/front_end/third_party/puppeteer/package/lib/puppeteer/util/version.js +1 -1
  405. package/front_end/third_party/puppeteer/package/lib/types.d.ts +328 -11
  406. package/front_end/third_party/puppeteer/package/package.json +10 -8
  407. package/front_end/third_party/puppeteer/package/src/api/Browser.ts +118 -0
  408. package/front_end/third_party/puppeteer/package/src/api/BrowserContext.ts +119 -0
  409. package/front_end/third_party/puppeteer/package/src/api/HTTPRequest.ts +25 -2
  410. package/front_end/third_party/puppeteer/package/src/api/HTTPResponse.ts +28 -0
  411. package/front_end/third_party/puppeteer/package/src/api/Page.ts +65 -38
  412. package/front_end/third_party/puppeteer/package/src/api/locators/locators.ts +27 -7
  413. package/front_end/third_party/puppeteer/package/src/bidi/Browser.ts +43 -7
  414. package/front_end/third_party/puppeteer/package/src/bidi/BrowserConnector.ts +1 -0
  415. package/front_end/third_party/puppeteer/package/src/bidi/Connection.ts +5 -1
  416. package/front_end/third_party/puppeteer/package/src/bidi/Frame.ts +38 -8
  417. package/front_end/third_party/puppeteer/package/src/bidi/HTTPRequest.ts +27 -12
  418. package/front_end/third_party/puppeteer/package/src/bidi/HTTPResponse.ts +19 -6
  419. package/front_end/third_party/puppeteer/package/src/bidi/Input.ts +72 -5
  420. package/front_end/third_party/puppeteer/package/src/bidi/NetworkEvents.ts +82 -0
  421. package/front_end/third_party/puppeteer/package/src/bidi/Page.ts +37 -13
  422. package/front_end/third_party/puppeteer/package/src/bidi/Realm.ts +26 -14
  423. package/front_end/third_party/puppeteer/package/src/bidi/core/Browser.ts +43 -22
  424. package/front_end/third_party/puppeteer/package/src/bidi/core/BrowsingContext.ts +13 -5
  425. package/front_end/third_party/puppeteer/package/src/bidi/core/Navigation.ts +21 -1
  426. package/front_end/third_party/puppeteer/package/src/bidi/core/Request.ts +27 -5
  427. package/front_end/third_party/puppeteer/package/src/cdp/Binding.ts +6 -4
  428. package/front_end/third_party/puppeteer/package/src/cdp/ExtensionTransport.ts +31 -6
  429. package/front_end/third_party/puppeteer/package/src/cdp/FrameManager.ts +5 -0
  430. package/front_end/third_party/puppeteer/package/src/cdp/HTTPRequest.ts +18 -1
  431. package/front_end/third_party/puppeteer/package/src/cdp/HTTPResponse.ts +48 -0
  432. package/front_end/third_party/puppeteer/package/src/cdp/NetworkEventManager.ts +58 -5
  433. package/front_end/third_party/puppeteer/package/src/cdp/NetworkManager.ts +94 -14
  434. package/front_end/third_party/puppeteer/package/src/cdp/Page.ts +50 -28
  435. package/front_end/third_party/puppeteer/package/src/cdp/ResponseBodyStream.ts +106 -0
  436. package/front_end/third_party/puppeteer/package/src/cdp/Target.ts +38 -3
  437. package/front_end/third_party/puppeteer/package/src/cdp/cdp.ts +1 -0
  438. package/front_end/third_party/puppeteer/package/src/cdp/utils.ts +6 -5
  439. package/front_end/third_party/puppeteer/package/src/common/ConsoleMessage.ts +5 -0
  440. package/front_end/third_party/puppeteer/package/src/common/EventEmitter.ts +17 -8
  441. package/front_end/third_party/puppeteer/package/src/common/util.ts +32 -15
  442. package/front_end/third_party/puppeteer/package/src/node/BrowserLauncher.ts +21 -13
  443. package/front_end/third_party/puppeteer/package/src/node/ChromeLauncher.ts +10 -10
  444. package/front_end/third_party/puppeteer/package/src/revisions.ts +3 -3
  445. package/front_end/third_party/puppeteer/package/src/util/decorators.ts +1 -1
  446. package/front_end/third_party/puppeteer/package/src/util/version.ts +1 -1
  447. package/front_end/third_party/puppeteer/puppeteer-tsconfig.json +2 -0
  448. package/front_end/ui/components/adorners/adorner.css +1 -1
  449. package/front_end/ui/components/buttons/button.css +0 -28
  450. package/front_end/ui/components/buttons/textButton.css +1 -45
  451. package/front_end/ui/components/diff_view/diffView.css +0 -2
  452. package/front_end/ui/components/input/checkbox.css +3 -3
  453. package/front_end/ui/components/issue_counter/issueLinkIcon.css +2 -2
  454. package/front_end/ui/components/menus/Menu.ts +14 -0
  455. package/front_end/ui/components/menus/menu.css +2 -14
  456. package/front_end/ui/components/menus/menuItem.css +0 -4
  457. package/front_end/ui/components/request_link_icon/requestLinkIcon.css +2 -2
  458. package/front_end/ui/components/survey_link/SurveyLink.ts +1 -1
  459. package/front_end/ui/components/survey_link/surveyLink.css +3 -3
  460. package/front_end/ui/components/switch/switch.css +3 -2
  461. package/front_end/ui/components/text_editor/theme.ts +1 -1
  462. package/front_end/ui/components/tooltips/Tooltip.ts +29 -0
  463. package/front_end/ui/components/tree_outline/treeOutline.css +1 -24
  464. package/front_end/ui/legacy/ContextMenu.ts +5 -5
  465. package/front_end/ui/legacy/SoftContextMenu.ts +24 -8
  466. package/front_end/ui/legacy/Toolbar.ts +1 -1
  467. package/front_end/ui/legacy/Treeoutline.ts +31 -78
  468. package/front_end/ui/legacy/UIUtils.ts +9 -17
  469. package/front_end/ui/legacy/checkboxTextLabel.css +2 -44
  470. package/front_end/ui/legacy/components/color_picker/Spectrum.ts +39 -27
  471. package/front_end/ui/legacy/components/color_picker/spectrum.css +2 -10
  472. package/front_end/ui/legacy/components/data_grid/dataGrid.css +2 -6
  473. package/front_end/ui/legacy/components/inline_editor/BezierEditor.ts +34 -26
  474. package/front_end/ui/legacy/components/inline_editor/SwatchPopoverHelper.ts +1 -0
  475. package/front_end/ui/legacy/components/inline_editor/cssShadowEditor.css +1 -1
  476. package/front_end/ui/legacy/components/inline_editor/swatchPopover.css +1 -1
  477. package/front_end/ui/legacy/components/object_ui/ObjectPropertiesSection.ts +83 -21
  478. package/front_end/ui/legacy/components/object_ui/objectPopover.css +0 -4
  479. package/front_end/ui/legacy/components/perf_ui/FlameChart.ts +41 -14
  480. package/front_end/ui/legacy/components/perf_ui/chartViewport.css +1 -9
  481. package/front_end/ui/legacy/components/perf_ui/filmStripView.css +1 -1
  482. package/front_end/ui/legacy/components/perf_ui/overviewGrid.css +2 -1
  483. package/front_end/ui/legacy/components/quick_open/filteredListWidget.css +0 -5
  484. package/front_end/ui/legacy/components/settings_ui/SettingsUI.ts +6 -3
  485. package/front_end/ui/legacy/components/source_frame/JSONView.ts +95 -1
  486. package/front_end/ui/legacy/components/source_frame/imageView.css +2 -2
  487. package/front_end/ui/legacy/filter.css +7 -3
  488. package/front_end/ui/legacy/inspectorCommon.css +7 -81
  489. package/front_end/ui/legacy/inspectorDrawerTabbedPane.css +1 -1
  490. package/front_end/ui/legacy/listWidget.css +2 -2
  491. package/front_end/ui/legacy/progressIndicator.css +1 -1
  492. package/front_end/ui/legacy/tabbedPane.css +6 -10
  493. package/front_end/ui/visual_logging/KnownContextValues.ts +2 -0
  494. package/front_end/ui/visual_logging/LoggingDriver.ts +4 -0
  495. package/front_end/ui/visual_logging/visual_logging.ts +1 -1
  496. package/inspector_overlay/common.ts +0 -3
  497. package/inspector_overlay/main.ts +1 -3
  498. package/inspector_overlay/tool_highlight.css +0 -7
  499. package/inspector_overlay/tool_highlight.ts +0 -1
  500. package/inspector_overlay/tool_source_order.css +0 -4
  501. package/package.json +1 -1
  502. package/front_end/generated/SupportedCSSProperties.ts +0 -9689
@@ -5,7 +5,7 @@ severity: should_fix
5
5
  ---
6
6
 
7
7
  **Rule.** Use native semantic HTML controls with accurate ARIA attributes, keyboard handlers, and !event.isComposing guards
8
- - **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.
8
+ - **Look for**: `@click` on `<div>`/`<span>` without button semantics, `<button>` nested inside `<button>`/`<x-link>`, icon-only `<devtools-button>` elements missing `.accessibleLabel=${...}` (setting `title` or HTML `aria-label` alone leaves the inner shadow `<button>` unnamed under `axe-core` because `<devtools-button>` sets `role="presentation"` on its host), `Enter` keydown handlers missing `!event.isComposing`, or `aria-describedby` pointing to interactive `<devtools-tooltip>` elements.
9
9
  - **Do not flag**: Delegating click listeners on container elements that handle bubbled events from child buttons. Rendering `<tr>` rows directly into `this.affectedResources` (`<table class="affected-resource-list">`) in `AffectedResourcesView` subclasses without a `<tbody>` wrapper (`AffectedResourcesView` creates the `<table>` container without a `<tbody>` and subclasses render `<tr>` rows directly into `this.affectedResources`).
10
10
 
11
11
  **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.
@@ -1,22 +1,36 @@
1
1
  ---
2
2
  name: devtools/ui-and-widgets/ui-css-scoping-and-flex-layout
3
3
  rubric: readability
4
- severity: nit
4
+ severity: should_fix
5
5
  ---
6
6
 
7
- **Rule.** Scope light-DOM stylesheets and align elements using flexbox or grid rather than competing margin and position offsets
8
- - **Look for**: Unscoped generic selectors in light-DOM `.css` files (or `:host` inside `@scope` blocks instead of `:scope`), redundant `@scope to (devtools-widget > *)` wrappers on shadow-DOM (`useShadowDom: 'pure'` or `useShadowDom: true`) widgets that have no child `<devtools-widget>` elements, CSS rules combining `vertical-align`, negative `margin-top`, and pixel offsets to center icons and buttons, or `this.registerRequiredCSS(...)` or `widget.registerRequiredCSS(...)` calls in widgets migrated to Lit view functions instead of rendering `<style>${styles}</style>` inside the view template.
9
- - **Do not flag**: Shadow DOM component stylesheets where `:host` scoping is native. `<style>${styles}</style>` interpolations of `*.css.js` default imports in Lit templates (generated `.css.js` files export plain CSS strings, not `CSSStyleSheet` objects, and `<style>${...}</style>` is the standard replacement for deprecated `registerRequiredCSS`).
7
+ **Rule.** Scope light-DOM stylesheets with `@scope to (devtools-widget > *)` and align elements using flexbox or grid rather than competing margin and position offsets
8
+ - **Look for**: Adding files to the `@devtools/no-unscoped-light-dom-styles` `burndown` list in `eslint.config.mjs`, leaving Light DOM stylesheets without top-level `@scope to (devtools-widget > *)` blocks, `:host` inside `@scope` (which is unconditionally forbidden by `plugin/check_scope_selectors`, even with `:scope` or `&`), ancestor selectors inside `@scope` without `:scope` or `&` that receive an implicit `:scope ` descendant prefix and never match (such as `:host-context()`, `:root`, `html`, `body`, `.theme-with-dark-background`, `.platform-*`, or `.overlay-scrollbar-enabled`), injecting redundant `inspectorCommonStyles` or `textButtonStyles` into Light DOM views, injecting other shared stylesheets into Light DOM without wrapping them inline as `<style>@scope to (devtools-widget > *) { ${styles} }</style>`, relying on `(devtools-widget > *)` to stop at imperatively attached `childWidget.show(container)` legacy children, redundant `@scope to (devtools-widget > *)` wrappers on shadow-DOM (`useShadowDom: 'pure'` or `useShadowDom: true`) widgets that have no child `<devtools-widget>` elements, CSS rules combining `vertical-align`, negative `margin-top`, and pixel offsets to center icons and buttons, or `this.registerRequiredCSS(...)` or `widget.registerRequiredCSS(...)` calls in widgets migrated to Lit view functions instead of rendering `<style>${styles}</style>` inside the view template.
9
+ - **Do not flag**: Shadow DOM component stylesheets where `:host` scoping is native. `<style>${styles}</style>` interpolations of `*.css.js` default imports in Lit templates (generated `.css.js` files export plain CSS strings, not `CSSStyleSheet` objects, and `<style>${...}</style>` is the standard replacement for deprecated `registerRequiredCSS`). Removing scoped files from the `@devtools/no-unscoped-light-dom-styles` `burndown` list.
10
10
 
11
- **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.
11
+ **Why.** Unscoped selectors in Light DOM stylesheets leak across the DevTools document, while `:host` is invalid in Light DOM and ancestor selectors inside `@scope` without `:scope` or `&` receive an implicit `:scope ` descendant prefix and never match. Combining `vertical-align`, negative margins, and `position: relative` offsets creates brittle layouts that break under font scaling or zoom.
12
12
 
13
13
  ## Examples
14
14
 
15
15
  Bad:
16
16
 
17
- ```ts
17
+ ```css
18
+ /* Unscoped Light DOM rules or dead selectors inside @scope */
19
+ .widget-container {
20
+ display: block;
21
+ }
22
+
18
23
  @scope to (devtools-widget > *) {
19
- :host { display: block; }
24
+ /* Dead selector: :host is Shadow DOM only and never matches in @scope */
25
+ :host {
26
+ display: flex;
27
+ }
28
+
29
+ /* Dead selector: receives implicit :scope descendant prefix, so ancestor theme never matches */
30
+ .theme-with-dark-background .item {
31
+ color: #fff;
32
+ }
33
+
20
34
  .action-icon {
21
35
  vertical-align: middle;
22
36
  margin-top: -2px;
@@ -25,3 +39,26 @@ Bad:
25
39
  }
26
40
  }
27
41
  ```
42
+
43
+ Good:
44
+
45
+ ```css
46
+ /* Properly scoped Light DOM stylesheet */
47
+ @scope to (devtools-widget > *) {
48
+ :scope {
49
+ display: flex;
50
+ align-items: center;
51
+ }
52
+
53
+ .item {
54
+ /* Use theme-aware design tokens instead of ancestor theme selectors */
55
+ color: var(--sys-color-on-surface);
56
+ }
57
+
58
+ .action-icon {
59
+ display: inline-flex;
60
+ align-items: center;
61
+ justify-content: center;
62
+ }
63
+ }
64
+ ```
@@ -5,7 +5,7 @@ severity: should_fix
5
5
  ---
6
6
 
7
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`.
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, mutating `element.autofocus` / `setAttribute('autofocus', ...)` / `toggleAttribute('autofocus', ...)` imperatively in TypeScript or `ref(...)` callbacks, 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
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
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`.
@@ -5,8 +5,8 @@ severity: should_fix
5
5
  ---
6
6
 
7
7
  **Rule.** Encapsulate imperative DOM actions in ViewOutput callbacks and pass user actions via semantic ViewInput callbacks instead of raw DOM references
8
- - **Look for**: `ViewOutput` interfaces containing `HTMLElement` or `Element` properties, `ViewInput` callbacks typed as `(event: Event) => void` instead of semantic domain values, or view functions with no outputs that type `output` as `object` or `{}` instead of `undefined` (and view calls such as `this.#view(...)` in `performUpdate()` passing `{}` instead of `undefined`, or dangling `type ViewOutput = undefined` aliases).
9
- - **Do not flag**: Third-party editor hosts, `<canvas>` (`HTMLCanvasElement`) and canvas sizing/resizer containers, or elements returned by existing public cross-widget APIs (such as `UI.ListDelegate.createElementForItem` or `ConsolePrompt.belowEditorElement`).
8
+ - **Look for**: `ViewOutput` interfaces containing `HTMLElement` or `Element` properties, `ViewInput` callbacks typed as `(event: Event) => void` instead of semantic domain values, imperative item/cell DOM factories (`UI.ListDelegate.createElementForItem` on `UI.SoftDropDown`, `DataGridNode.createCell`) retained in migrated views instead of passing pure data-only item arrays in `ViewInput` and looping declaratively inside `<devtools-menu>`, `<devtools-list>`, `<devtools-data-grid>`, or `<devtools-tree>`, or view functions with no outputs that type `output` as `object` or `{}` instead of `undefined` (and view calls such as `this.#view(...)` in `performUpdate()` passing `{}` instead of `undefined`, or dangling `type ViewOutput = undefined` aliases).
9
+ - **Do not flag**: Third-party editor hosts, `<canvas>` (`HTMLCanvasElement`) and canvas sizing/resizer containers, or elements returned by unmigrated external APIs (such as `ConsolePrompt.belowEditorElement`).
10
10
 
11
11
  **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)`.
12
12
 
@@ -5,7 +5,7 @@ severity: blocking
5
5
  ---
6
6
 
7
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()`).
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, `UI.Widget` subclasses wrapping `this.element` in `new UI.Toolbar.ToolbarItem(this.element)` that call `toolbarItem.setVisible(false)` before attachment without re-applying `toolbarItem.setVisible(...)` in `show()` / `wasShown()` (`Widget.#showWidget` unconditionally strips `'hidden'` from `this.element` on mount), 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
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.
@@ -33,7 +33,7 @@ Load the skill or `.agents/rules/` files that match what the diff touches, and a
33
33
  | If the diff touches… | Load skill or rules |
34
34
  | :--- | :--- |
35
35
  | Any `import` statement, or a new cross-module dependency | `devtools-imports` |
36
- | `UI.Widget`, lit-html views, components, CSS | `ui-widgets` |
36
+ | `UI.Widget`, lit-html views, components, CSS, or UI layout changes | `ui-widgets`, `visual-regression-audit` |
37
37
  | Reviewing UI and widgets (`front_end/(panels|ui)/**/*.{ts,css}`) | `.agents/rules/ui-and-widgets/*.md` |
38
38
  | Migration of legacy imperative DOM to widgets or Lit | `ui-eng-vision-orchestrator` (and its sub-skills) |
39
39
  | New or changed tests: choosing unit, API, or E2E | `devtools-testing-guidance` |
@@ -157,8 +157,14 @@ findings):
157
157
  - Don't take detours to reach a value. If a module is imported, call
158
158
  `TextUtils.TextRange.TextRange.fromObject(...)` directly instead of going
159
159
  through `rule.style.range.constructor`.
160
- - Look for dead code, leftover debug code, commented-out blocks, and unrelated
161
- formatting churn.
160
+ - Look for dead code, leftover debug code, commented-out blocks, pure-whitespace
161
+ diff hunks in non-CSS files, and unrelated formatting churn.
162
+ - **Live-code & abstraction checks in UI migrations**: Flag `DEFAULT_VIEW` or
163
+ `*_VIEW` functions that have zero production callers in the CL (unused views
164
+ staged for a later CL), stateless single-row/item child `UI.Widget` subclasses
165
+ where a `LitTemplate` helper in the parent view suffices, and call sites that
166
+ inline non-trivial shared helpers (such as `UI.UIUtils.maybeCreateNewBadge`)
167
+ instead of converting the shared helper to return `LitTemplate`.
162
168
  - Check that the change stays in scope. Flag unrelated refactors that should be
163
169
  split into a separate CL.
164
170
  - Check for lifecycle issues: event listeners and observers that are added
@@ -170,9 +176,20 @@ findings):
170
176
  - The description explains *why*, including external dependencies (for
171
177
  example, "V8 will stop emitting X; this must land first").
172
178
  - Include a `Bug:` or `Fixed:` trailer, or `Bug: None`. Keep lines under 72
173
- characters.
174
- - For migrations and stacked series, list the legacy tests or files covered,
175
- and number the series (for example, `(13/16)`).
179
+ characters, and keep diffs at or under `350` changed lines (`insertions + deletions`)
180
+ where practical.
181
+ - **Descriptive subject lines & live vertical splits**: The first line (`<= 72`
182
+ chars) must describe *what the CL changes functionally*, never which step or
183
+ pass of a migration it is (no `Pass 1:`, `(2/6)`, or `Step 3 of migration` in
184
+ the subject; place stack context in the body if needed). Flag split CLs that
185
+ defer unit tests to a follow-up test-only CL or defer dead-code removal to a
186
+ cleanup-only tail CL.
187
+ - **Never add Piper `KEY=VALUE` tags:** Flag any column-0 lines matching
188
+ `TAG=`, `CONV=`, `BUG=`, `FIXED=`, or `MARKDOWN=true`. DevTools commit
189
+ descriptions must use standard Git trailers (`Bug:`, `Fixed:`) only; Piper
190
+ tags break Git trailer parsing and are rejected by `PRESUBMIT.py`. Agent
191
+ conversations should be linked out of band via
192
+ `git config --global cl.upload-conversation-id true`.
176
193
  - **UI Eng Vision migration completeness & `Fixed:` vs `Bug:`**: Flag
177
194
  `Fixed: <id>` on UI Eng Vision migration CLs when core violations remain in
178
195
  the target file: legacy `UI.TreeOutline` or `extends UI.TreeOutline.TreeElement`
@@ -19,10 +19,11 @@ Run the scripts from the root `package.json` (`test`, `lint`, `build`, `start`,
19
19
 
20
20
  - Check for build issues by running `autoninja -C out/Default`.
21
21
 
22
- ## Linting
22
+ ## Linting & Diff-Range Formatting
23
23
 
24
24
  - `./dt lint` will execute ESLint and StyleLint. It will report any violations and automatically fix them where possible.
25
25
  - To run the linter on a specific file or directory, you can run `./dt lint <PATH>` where `PATH` is a path to a file or directory. This will also automatically fix violations where possible.
26
+ - **Format changed line ranges only**: Format only modified line ranges (`git clang-format` or `clang-format --lines=<start>:<end>`) instead of running whole-file `clang-format`, which introduces unrelated whitespace churn in untouched code. Before uploading, verify `git diff` vs `git diff -w` has zero pure-whitespace hunks in non-CSS files.
26
27
 
27
28
  ## Fetching Tryjob Results, Failure Logs, & Screenshot Goldens
28
29
 
@@ -54,6 +54,7 @@ Follow the following format and constraints:
54
54
  - **Body appendix:** `https://crsrc.org/c/third_party/blink/web_tests/<long test name>;drc=4d51e9cab50efd0f8029c45a486e199a1d519fd1`
55
55
  - **Bug line:** `Fixed: <issue number>`
56
56
  - **Line Length Constraint:** Wrap all lines in the commit message to a maximum of 72 characters per line.
57
+ - **No Piper tags:** Never add Piper `KEY=VALUE` tags (such as `TAG=agy` or `CONV=...`); use Git trailers only (`PRESUBMIT.py` rejects Piper tags).
57
58
 
58
59
  Example commit message:
59
60
 
@@ -23,6 +23,12 @@ existing element containers.
23
23
  methods in their original locations, converting DOM-returning helpers in
24
24
  place to return `LitTemplate` (or `Promise<LitTemplate|null>`) rather
25
25
  than deleting and inlining them into `performUpdate()` or `DEFAULT_VIEW`.
26
+ * **Update Low-Fanout Shared Helpers Instead of Inlining**: When migrating a
27
+ caller of a shared cross-module DOM helper (such as
28
+ `UI.UIUtils.maybeCreateNewBadge`) that encapsulates non-trivial markup or
29
+ visual logging across a small set of callers, convert the shared helper
30
+ to return `LitTemplate` and update its callers in a standalone
31
+ prerequisite CL instead of inlining its markup at each call site.
26
32
  * Do not aggressively "flatten" classes or collapse helper abstractions
27
33
  into the main view just to coerce a single master template. Pass 2
28
34
  should only change the *implementation details* of rendering (imperative
@@ -54,10 +60,8 @@ existing element containers.
54
60
  4. **Modern Component Mapping**:
55
61
  * **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.
56
62
  * If unsure, also consult the [automatic migration code](../../../scripts/eslint_rules/lib/no-imperative-dom-api.ts)
57
- * **Prefer Component Built-Ins Over Legacy Boilerplate**: Before porting
58
- legacy event handlers, comparators, or state variables, check if the
59
- modern component handles them natively. Drop host-level workarounds in
60
- favor of declarative component attributes.
63
+ * **Replace Imperative Item & Cell Factories with Data Loops**: Do not leave `UI.ListDelegate.createElementForItem` (`UI.SoftDropDown`), `DataGridNode.createCell` (`DataGridImpl`), or `UI.TreeOutline` item builders in place. Pass a pure data-only items array in `ViewInput` and map over it declaratively inside `<button>` + `<devtools-menu>`, `<devtools-list>`, `<devtools-data-grid>`, or `<devtools-tree>`.
64
+ * **Prefer HTML-Native Attributes Over `ref(...)` Wiring Setters**: Before using `ref(...)` to wire two elements together or configure a shared DevTools UI primitive imperatively (e.g. menu anchor/origin), check whether the primitive supports or should gain an HTML-native ID/attribute API in a standalone prerequisite CL. Drop host-level workarounds in favor of declarative component attributes.
61
65
 
62
66
 
63
67
  5. **Local Modular Renders**:
@@ -107,10 +111,14 @@ existing element containers.
107
111
  * **Strict Tag/Class Parity**: Do not change tag types (e.g., `span` to
108
112
  `div`) or drop class names during template translation, as CSS may
109
113
  depend on them.
110
- * **Explicit Component Variants**: Modern Custom Element (e.g.
114
+ * **Explicit Component Variants & Accessible Labels**: Modern Custom Element (e.g.
111
115
  `<devtools-button>`) defaults may not match legacy appearance.
112
116
  Explicitly bind `.data=${{variant: Buttons.Button.Variant.OUTLINED}}`
113
- (or appropriate variant) rather than relying on defaults.
117
+ (or `.variant=${...}`) rather than relying on defaults. On icon-only
118
+ `<devtools-button>` elements, always bind `.accessibleLabel=${label}`
119
+ (setting `title` or HTML `aria-label` alone leaves the inner shadow
120
+ `<button>` unnamed under `axe-core` because `<devtools-button>` sets
121
+ `role="presentation"` on its host).
114
122
  * **Accessibility Preservation**: Convert custom accessibility
115
123
  instrumentation (like `ARIAUtils.markAsAlert()`) to native ARIA
116
124
  attributes in the template (e.g., `role="alert"`, `aria-live="polite"`).
@@ -119,11 +127,13 @@ existing element containers.
119
127
  CSS class (`classMap({hidden: ...})` or `classList.toggle('hidden', ...)`)
120
128
  with `?hidden` (`inspectorCommon.css` already defines
121
129
  `[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()`.
130
+ * **Declarative Default Focus (`autofocus` / `?autofocus`)**: Mark the
131
+ default focused element with `autofocus` or `?autofocus=${...}` directly
132
+ in the Lit template instead of collecting elements via `ref(...)`,
133
+ plumbing focus callbacks through `ViewOutput`, or mutating
134
+ `element.autofocus` / `setAttribute('autofocus', ...)` imperatively in
135
+ TypeScript. `UI.Widget.prototype.focus()` queries `[autofocus]`
136
+ automatically via `getDefaultFocusedElement()`.
127
137
  * **`<devtools-tree>` & Persistent `<devtools-prompt ?editing>` Patterns**:
128
138
  When rendering `<devtools-tree .template=${html`<ul role="tree">...</ul>`}>`:
129
139
  - Preserve `front_end/ui/legacy/Treeoutline.ts` contracts without
@@ -141,6 +151,11 @@ existing element containers.
141
151
  - Ensure custom elements with state passed via JS properties (`.data`)
142
152
  override `cloneNode(deep)` and reflect dynamic state via DOM
143
153
  attributes so shadow clones stay updated.
154
+ * **Light DOM CSS Encapsulation (`@scope`)**:
155
+ - Verify stylesheets satisfy `@devtools/no-unscoped-light-dom-styles`. Never add files to the `burndown` list in `eslint.config.mjs`; remove the entry from `burndown` once scoped.
156
+ - Obey `plugin/check_scope_selectors`: never use `:host` inside `@scope` (it is unconditionally forbidden, even with `:scope` or `&`), use `:scope` to style the root container, and use theme-aware design tokens (`--sys-color-*` / `--app-color-*`) instead of ancestor classes like `.theme-with-dark-background` or `:host-context(...)` (which receive an implicit `:scope ` prefix and never match without `:scope` or `&`).
157
+ - Remove redundant `inspectorCommonStyles` or `textButtonStyles` imports from Light DOM views (`installComponentRootStyles()` already provides them). For other shared stylesheets, wrap inline as `<style>@scope to (devtools-widget > *) { ${styles} }</style>`.
158
+ - Beware that the `(devtools-widget > *)` lower boundary stops cascading into declarative `<devtools-widget>` children (`${widget(...)}`), but does **not** stop at imperatively attached `childWidget.show(container)` legacy children.
144
159
 
145
160
  11. **Render Templates Syntax & Code Movement**:
146
161
 
@@ -265,3 +280,4 @@ existing element containers.
265
280
  5. ❓ **Split Views**: Does `<devtools-split-view>` have `flex: auto; height: 100%;` CSS and reuse existing split settings?
266
281
  6. ❓ **String Audit**: Did I verify that any removed `UIStrings` weren't from accidentally dropped UI branches?
267
282
  7. ❓ **Build**: Does the code compile and do visual tests pass with 0% diff?
283
+ 8. ❓ **CSS @scope Encapsulation**: Are Light DOM styles wrapped in `@scope to (devtools-widget > *)` with `:scope` instead of `:host`, theme-aware `--sys-color-*` tokens instead of theme classes, redundant common styles removed, and no entries added to the ESLint burndown list?
@@ -39,44 +39,50 @@ principles.
39
39
  file matches older patterns or generic examples. Always perform a structure
40
40
  analysis of the active file first and adapt the plan to the actual, current
41
41
  code.
42
- 4. **Hybrid Files/Multiple Classes**: Files may contain multiple classes in
42
+ 4. **Reusable vs. Single-Use Web Components Gate**:
43
+ * **Reusable UI primitives** (`front_end/ui/components/**`, `front_end/ui/kit/**` — shared buttons, menus, dialogs, links, badges, or trees reused across panels) must remain custom elements (`HTMLElement`). Do **not** migrate them to `UI.Widget` or `DEFAULT_VIEW`.
44
+ * **Single-use custom elements** (`extends HTMLElement` or `LitElement` under `front_end/panels/**/components/` used solely for encapsulation in one feature or panel) **should** migrate to `UI.Widget` + `DEFAULT_VIEW` + `@scope to (devtools-widget > *)`.
45
+ 5. **Hybrid Files/Multiple Classes**: Files may contain multiple classes in
43
46
  different states of modernization (e.g., one partially migrated class and
44
47
  one fully legacy class). If the file being migrated contains several
45
48
  classes, the migration needs to be done separately for each class, starting
46
49
  with the leaves and going up the dependency chain. Propose modifications
47
50
  only for classes with actual violations.
48
- 5. **Coupling Analysis**: Always check the integration files (e.g., sidebar
51
+ 6. **Coupling Analysis**: Always check the integration files (e.g., sidebar
49
52
  files, parent panel files) where the target class is instantiated to see if
50
53
  there are any direct `.element` or `.contentElement` couplings. If found,
51
54
  include the decoupling of these references in the plan.
52
- 6. **Neighboring Component Reference**: Inspect neighboring modernized files of
55
+ 7. **Neighboring Component Reference**: Inspect neighboring modernized files of
53
56
  the same archetype (e.g., `DOMStorageItemsView.ts` or
54
57
  `KeyValueStorageItemsView.ts` for storage-like components) to find proven
55
58
  patterns for toolbar and data-grid configurations.
56
- 7. **The Narrow Bridge Principle**: Keep code modifications tightly scoped to a
59
+ 8. **The Narrow Bridge Principle**: Keep code modifications tightly scoped to a
57
60
  single responsibility per CL. Do not combine technology migrations (e.g.,
58
61
  converting imperative DOM to Lit-html) with base class refactoring in the
59
62
  same diff.
60
- 8. **Strict Intermediate Stability**: The code must compile and work correctly,
63
+ 9. **Strict Intermediate Stability**: The code must compile and work correctly,
61
64
  and all tests must pass after each step. You **MUST** update usages if you
62
65
  change APIs.
63
- 9. **Establish Comprehensive Guardrails First**: Ensure both **logic tests**
66
+ 10. **Establish Comprehensive Guardrails First**: Ensure both **logic tests**
64
67
  (verifying presenter interactions and state updates) and **screenshot
65
68
  tests** (verifying layout/styling) exist before rewriting code. If coverage
66
69
  is missing, scaffold it first.
67
- 10. **Pre-flight Clarification**: Before starting, verify if the task is
70
+ 11. **Pre-flight Clarification**: Before starting, verify if the task is
68
71
  underspecified or ambiguous. If so, point this out and ask for
69
72
  clarifications before proceeding.
70
- 11. **Step Sizing & Complexity Assessment**: Assess the complexity of each step
71
- beforehand. Aim for intermediate steps that involve changing or adding
72
- roughly 300 lines of code. If a step is predicted to be too complex, break
73
- it down into smaller substeps. The agent must stop and report back after
74
- each step or substep to allow verification.
75
- 12. **Context Hygiene via Subagents**: To keep the main conversation context
73
+ 12. **Step Sizing (`<= 350` Lines) & 100% Live-Code Rule**: Keep every CL at or
74
+ under **`350` changed lines (`insertions + deletions`)**. Every CL must
75
+ execute 100% of its new view and presenter code in production, remove the
76
+ imperative code it replaces, and include unit tests covering that behavior in
77
+ the **same CL**. Never create a CL that adds an unused `DEFAULT_VIEW` or
78
+ `*_VIEW` export, defers unit tests to a follow-up test-only CL, or defers
79
+ imperative dead-code removal to a cleanup-only tail CL. The agent must stop
80
+ and report back after each step or substep to allow verification.
81
+ 13. **Context Hygiene via Subagents**: To keep the main conversation context
76
82
  clean and focused on high-level orchestration, prefer delegating intense
77
83
  execution tasks (like running tests, debugging compilations, or processing
78
84
  independent classes in parallel) to specialized subagents.
79
- 13. **Cross-Repo Runtime Coupling Check (`legacy_test_runner` & `blink/web_tests`)**:
85
+ 14. **Cross-Repo Runtime Coupling Check (`legacy_test_runner` & `blink/web_tests`)**:
80
86
  Before converting TypeScript `private` fields/methods to ES `#private` or
81
87
  removing widget properties (e.g., `.tabbedPane`, `.sidebarPaneStack`,
82
88
  `.threadsSidebarPane`, `.searchInputElement`), search both
@@ -86,15 +92,17 @@ principles.
86
92
  members in untyped JS). Keep accessed members as TypeScript `private` with a
87
93
  `// Accessed in web_tests / legacy_test_runner` comment, or migrate the
88
94
  web_tests first in a dedicated CL.
89
- 14. **Strict CL Splitting Rules**:
90
- * **One Class Per CL for Hybrid Files**: When modernizing files containing
91
- multiple classes, extract or migrate secondary classes (e.g.,
92
- `QuickSourceView`) into their own dedicated CLs.
93
- * **Separate Infrastructure CLs**: Keep shared `ui/legacy` or component
94
- infrastructure changes (e.g., `bindToAction`, `SplitWidget`,
95
- `WrapperWidget`) in separate, preceding CLs. Always verify with
96
- `cog_api.py diff` before uploading that no changes from later commits
97
- leaked into earlier infrastructure CLs.
95
+ 15. **Strict CL Splitting Rules**:
96
+ * **Live Split Patterns (`<= 350` Lines)**: When a migration exceeds 350 lines, split using one of three live-code patterns: (a) **one live class or low-fanout shared helper per CL** (leaf-to-root, wired to callers and tested immediately), (b) **2-pass `Local Lit in performUpdate()` -> `UI.Widget + DEFAULT_VIEW promotion`** (Pass 1 renders Lit templates live in `performUpdate()`, removes imperative DOM, and tests behavior; Pass 2 promotes to `DEFAULT_VIEW` and `createViewFunctionStub` tests), or (c) **vertical UI compartment slices** (migrating one toolbar, settings pane, split pane, or formatter batch end-to-end per CL).
97
+ * **Separate Infrastructure & Shared-Helper CLs**: Keep shared `ui/legacy`, `ui/kit`, or `UI.UIUtils` changes (e.g., converting a low-fanout helper like `UI.UIUtils.maybeCreateNewBadge` to return `LitTemplate` across its callers, or adding an HTML-native ID/attribute API to `<devtools-menu>`) in separate, preceding CLs rather than inlining helper internals or adding `ref(...)` workarounds at call sites. Always verify with `cog_api.py diff` before uploading that no changes from later commits leaked into earlier infrastructure CLs.
98
+ * **CL Descriptions & Bug Trailers Across Stacks**: Carry the target Buganizer issue ID across every CL in a split stack (`Bug: <id>` on intermediate CLs, `Fixed: <id>` only on the final complete CL). Write descriptive `<= 72`-character subject lines stating what each CL changes functionally, without pass or step numbers (`Pass 1:`, `(2/6)`) in the subject line.
99
+ * **Standalone CSS `@scope` CLs**: Migrating a Light DOM widget includes
100
+ ensuring its stylesheet is wrapped in `@scope to (devtools-widget > *)`
101
+ (removing the file from the `@devtools/no-unscoped-light-dom-styles`
102
+ `burndown` list in `eslint.config.mjs` once scoped). Always land this
103
+ in a small, standalone CSS CL separate from logic, template, or
104
+ widget-promotion CLs for bisectability, with screenshot baselines
105
+ established beforehand.
98
106
 
99
107
 
100
108
 
@@ -151,6 +159,8 @@ The plan you generate **MUST** follow this structure:
151
159
  - Assigned to: `ui-eng-vision-test-scaffolder`
152
160
  - [ ] **Pass 0.5: Privatize & Dead-Code Cleanup**
153
161
  - Mechanical prefactor: convert TypeScript `private` to ES `#private` and remove dead code
162
+ - [ ] **Pass 0.75: Light DOM CSS @scope Wrapping (Standalone CL)**
163
+ - Ensure stylesheet is wrapped in `@scope to (devtools-widget > *)` and remove entry from the `@devtools/no-unscoped-light-dom-styles` burndown list in `eslint.config.mjs`
154
164
  - [ ] **Pass 1: Logic Consolidation**
155
165
  - Assigned to: `ui-eng-vision-logic-consolidator`
156
166
  - [ ] **Pass 2: Lit-HTML Rendering**
@@ -180,6 +190,14 @@ The plan you generate **MUST** follow this structure:
180
190
  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.
181
191
  4. Verify that all tests and lints pass and stage this prefactor CL before proceeding to logic consolidation.
182
192
 
193
+ ### Light DOM CSS @scope Wrapping (Pass 0.75 / Standalone CSS CL)
194
+
195
+ * **Trigger Condition**: Baseline tests green (screenshot baselines established).
196
+ * **Actions**:
197
+ 1. Wrap the Light DOM widget's stylesheet in `@scope to (devtools-widget > *)`.
198
+ 2. Remove the file from the `@devtools/no-unscoped-light-dom-styles` `burndown` list in `eslint.config.mjs`.
199
+ 3. Verify zero visual regressions against screenshot goldens and land this in a small, standalone CL separate from logic, template, and widget-promotion CLs for bisectability.
200
+
183
201
  ### Logic Consolidation
184
202
 
185
203
  * **Trigger Condition**: Pass 0.5 staged (or baseline tests green if 0.5 skipped).
@@ -42,16 +42,18 @@ logical regressions are introduced during modernization.
42
42
  adding the styles itself. If the test pass, keep the version without
43
43
  `{includeCommonStyles: true}`. Otherwise, bring it back.
44
44
  * Screenshot tests are unittests that render either the full widget (if not migrated to the MVP architecture) or its view function (if already in MVP shape).
45
- * When testing view-separated components, prefer testing the View function (e.g., `DEFAULT_VIEW`) directly by passing mock state and callbacks.
46
- * Use `assertScreenshot` to capture and verify the visual output.
45
+ * Ship unit tests in the **same CL** as the production code they cover; never defer tests to a follow-up test-only CL.
46
+ * Test presenter logic via `createViewFunctionStub` and rely on `assertScreenshot` / E2E tests for template layout (per `docs/ui_engineering.md`). When adding targeted unit tests for view rendering, name the suite `describe('view', ...)` (never `describe('... DEFAULT_VIEW', ...)`), and avoid verbose synthetic `DEFAULT_VIEW` DOM assertion suites that duplicate presenter assertions.
47
47
  * Example structure:
48
48
 
49
49
  ```typescript
50
- it('renders the view', async () => {
51
- const target = document.createElement('div');
52
- renderElementIntoDOM(target, {includeCommonStyles: true});
53
- MyComponent.DEFAULT_VIEW(mockViewInput, undefined, target);
54
- await assertScreenshot('my_component/base.png');
50
+ describe('view', () => {
51
+ it('renders the base state', async () => {
52
+ const target = document.createElement('div');
53
+ renderElementIntoDOM(target, {includeCommonStyles: true});
54
+ MyComponent.DEFAULT_VIEW(mockViewInput, undefined, target);
55
+ await assertScreenshot('my_component/base.png');
56
+ });
55
57
  });
56
58
  ```
57
59
 
@@ -179,6 +181,9 @@ Always detect the execution environment first to run tests successfully:
179
181
 
180
182
  Otherwise, menu rendering will fail because `GlassPane` lacks an attached container element.
181
183
 
184
+ * **Drain `RenderCoordinator` in `afterEach` for Nested Dialog Components**:
185
+ When a mounted panel or widget instantiates components that chain 3+ nested `ScheduledRender` passes (such as `<devtools-shortcut-dialog>` or `<devtools-perf-export-trace-options>` -> `ButtonDialog` -> `Dialog`), call `await RenderCoordinator.done()` after `detach()` in `afterEach`. Synchronous `0ms` tests otherwise exceed `checkForPendingActivity`'s retry budget under `--repeat=10` CQ flake detection.
186
+
182
187
  --------------------------------------------------------------------------------
183
188
 
184
189
  ## 🔍 Mental Audit (Internal Self-Correction)
@@ -85,7 +85,9 @@ clean `UI.Widget` classes that use native update rendering delegates.
85
85
  * Trigger initial renders and external subscriptions in `wasShown()`, detaching them symmetrically in `willHide()`. Reconcile state incrementally rather than wiping populated presenter state via `reset()` on every re-show.
86
86
  * Use `this.requestUpdate()` across all presenter methods and setters; avoid synchronous `this.performUpdate()` calls or custom `#renderView()` methods.
87
87
  * Use declarative `autofocus` for default focus targets rather than imperative `focus()` overrides or `ViewOutput` focus closures.
88
+ * **`UI.Toolbar.Provider` Visibility Sync**: When promoting a `UI.Toolbar.Provider` to `UI.Widget` with `new UI.Toolbar.ToolbarItem(this.element)`, remember that `Widget.#showWidget()` strips `'hidden'` from `this.element` on mount. Re-apply `this.#toolbarItem.setVisible(...)` in `override show(...)` and `override wasShown()`, and test mounting into a `<devtools-toolbar>` while initially hidden.
88
89
  * Verify that no legacy `UI.TreeOutline`, `extends UI.TreeOutline.TreeElement` subclasses, `UI.ListControl`, `UI.ListWidget`, or `UI.InplaceEditor` remain before marking `Fixed: <id>`. If any remain, use `Bug: <id>`.
90
+ * Verify that Light DOM stylesheets satisfy `@devtools/no-unscoped-light-dom-styles` (removed from the `eslint.config.mjs` `burndown` list) and pass `plugin/check_scope_selectors` (`:scope` instead of `:host`, theme-aware tokens instead of ancestor theme/platform classes) before marking `Fixed: <id>`.
89
91
 
90
92
  --------------------------------------------------------------------------------
91
93
 
@@ -105,3 +107,4 @@ clean `UI.Widget` classes that use native update rendering delegates.
105
107
  4. ❓ **Lifecycle & Reactivity**: Does presenter code call `this.requestUpdate()` asynchronously (no synchronous `performUpdate()`), with non-destructive `wasShown()`/`willHide()` subscriptions?
106
108
  5. ❓ **No Legacy Controls**: Are all `TreeOutline`/`TreeElement` subclasses, `ListControl`, and `InplaceEditor` instances eliminated before using `Fixed: <id>`?
107
109
  6. ❓ **Build**: Does the code compile and do tests pass?
110
+ 7. ❓ **CSS @scope Completeness**: Does the Light DOM widget satisfy `@devtools/no-unscoped-light-dom-styles` (removed from the `eslint.config.mjs` burndown list) and `plugin/check_scope_selectors` (`:scope` instead of `:host`, theme-aware tokens) before marking `Fixed: <id>`?
@@ -11,7 +11,7 @@ Adhere strictly to the Model-View-Presenter (MVP) architecture.
11
11
  * **Presenters (`Widget`)**: Orchestrate data flow, manage UI-specific state, and handle interactions.
12
12
  * **Views (`function`)**: Purely presentational. Stateless functions that receive data/callbacks and render using `lit-html`.
13
13
 
14
- **Refactoring Note:** When refactoring legacy widgets to this framework, the widget's class name MUST NOT be changed. If you're refactoring a UI piece that uses shadow root (e.g. custom HTMLElements) to a Widget, make sure to update its styles to wrap the rules with a `@scope to (devtools-widget > *)` rule.
14
+ **Refactoring Note:** When refactoring legacy widgets to this framework, the widget's class name MUST NOT be changed. Truly reusable UI primitives (`front_end/ui/components/**`, `front_end/ui/kit/**`) stay custom elements (`HTMLElement`) and should not be migrated to `DEFAULT_VIEW` or `UI.Widget`, whereas single-use custom elements under `front_end/panels/**/components/` used solely for encapsulation in one feature should migrate to `UI.Widget` with `@scope to (devtools-widget > *)` styles.
15
15
 
16
16
  ### Presenter (`Widget`) Rules
17
17
 
@@ -37,9 +37,9 @@ Adhere strictly to the Model-View-Presenter (MVP) architecture.
37
37
  * **Template Formatting & Whitespace:** The custom `html` tag from `ui/lit/lit.js` (`front_end/ui/lit/strip-whitespace.ts`) automatically strips `\n\s*` outside of `<...>` tags at runtime, so multi-line formatting between text interpolations and inline elements (`<span>`, etc.) does not introduce whitespace text nodes.
38
38
  * MUST NOT hold state, fetch data, or perform business logic.
39
39
 
40
- #### Helper Functions in Views
40
+ #### Helper Functions in Views vs. Child Widgets
41
41
 
42
- Complex views can be broken down using helper functions defined inside `DEFAULT_VIEW` to access `input` and `output`.
42
+ Complex views and repeated item rows should be broken down using pure helper functions returning `LitTemplate` inside `DEFAULT_VIEW` (iterating over pure data arrays on `input`), rather than extracting stateless single-row or single-item child `UI.Widget` subclasses. Only extract a child `UI.Widget` when the sub-component owns independent lifecycle (`wasShown`/`willHide`), external subscriptions, or an isolated DOM mutation boundary (such as editable `<devtools-prompt>` rows inside `<devtools-tree>`).
43
43
 
44
44
  ```ts
45
45
  // clang-format off
@@ -83,7 +83,7 @@ When migrating imperative components (extending `UI.VBox`, `UI.Panel`, or `HTMLE
83
83
  * **Special Case:** If the component *must* extend `UI.Panel.Panel` or `UI.Dialog.Dialog` (to retain specific functionality), you cannot use `requestUpdate()`. Instead, call `this.performUpdate()` directly on state changes.
84
84
  3. **State Migration:** Move DOM-stored state to private class fields.
85
85
  4. **Update Usage:** Replace `new MyComponent()` instantiations with declarative `widget(MyComponent, {params})` in parent templates.
86
- 5. **Scoping Styles:** Ensure your CSS file uses the `@scope` block to prevent style leaks:
86
+ 5. **Scoping Styles:** Ensure your CSS file uses an `@scope to (devtools-widget > *)` block to prevent style leaks. Land `@scope` CSS wrapping in its own small, standalone CL separate from widget migration CLs so visual regressions are easy to bisect:
87
87
  ```css
88
88
  @scope to (devtools-widget > *) {
89
89
  ...
@@ -98,6 +98,9 @@ DevTools widgets typically render into Light DOM (the default for `UI.Widget`).
98
98
  ```css
99
99
  /* myWidget.css */
100
100
  @scope to (devtools-widget > *) {
101
+ :scope {
102
+ display: flex;
103
+ }
101
104
  .my-class { ... }
102
105
  }
103
106
  ```
@@ -113,10 +116,21 @@ render(html`
113
116
  `, target);
114
117
  ```
115
118
 
119
+ **Automated Lint Enforcement:**
120
+ - `@devtools/no-unscoped-light-dom-styles` (ESLint): checks stylesheets injected by Light DOM widgets (`<style>${styles}</style>`, `this.registerRequiredCSS()`, `appendStyle()`) and requires all rules to sit inside a top-level `@scope` block. Never add new files to the self-cleaning `burndown` list in `eslint.config.mjs`; remove migrated files from the list once scoped.
121
+ - `plugin/check_scope_selectors` (stylelint): unconditionally forbids `:host` inside `@scope` (even with `:scope` or `&`), and flags ancestor selectors that receive an implicit `:scope ` descendant combinator and cannot match without `:scope` or `&` (`:host-context()`, `:root`, `html`, `body`, `.theme-with-dark-background`, `.platform-*`, `.overlay-scrollbar-enabled`).
122
+
123
+ **Key `@scope` Gotchas & Rules:**
124
+ * **`:scope` instead of `:host`**: `:host` is Shadow DOM-only and never matches inside `@scope`. Style the widget's root container element with `:scope`.
125
+ * **Theme-aware tokens instead of theme or platform classes**: Because un-anchored selectors inside `@scope` receive an implicit `:scope ` prefix, selectors like `.theme-with-dark-background .foo` or `:host-context(...)` look inside the widget for the ancestor class and never match. Use theme-aware design tokens (`--sys-color-*` / `--app-color-*`) instead.
126
+ * **Shared stylesheets**: Do not inject `inspectorCommonStyles` or `textButtonStyles` into Light DOM views (`installComponentRootStyles()` already injects them globally into the document and shadow roots). Wrap other shared stylesheets inline as `<style>@scope to (devtools-widget > *) { ${styles} }</style>` so Shadow DOM consumers stay unaffected.
127
+ * **Lower boundary and imperative child widgets**: The `(devtools-widget > *)` lower boundary stops cascading into declarative `<devtools-widget>` children (`${widget(...)}`), but it does **not** stop at legacy imperatively attached `<div class="widget">` children (`childWidget.show(container)`).
128
+ * **Small, Standalone CLs**: Always land `@scope` CSS wrapping in a dedicated, standalone CL separate from logic, template, or widget-promotion CLs so visual regressions are easy to bisect.
129
+
116
130
  **Note:** The `{host: input}` option in `render()` is generally **not required** unless you are using specific Shadow DOM patterns that necessitate it. The `@scope` strategy is the preferred method for style isolation in DevTools widgets.
117
131
 
118
132
  ### Legacy Interop & Refs
119
- * **Raw Elements:** Use `Directives.ref` (from `ui/lit/lit.js`) to obtain a reference to a raw `HTMLElement` if needed for imperative APIs (e.g., `splitWidget.installResizer(element)`).
133
+ * **Raw Elements:** Use `Directives.ref` (from `ui/lit/lit.js`) to obtain a reference to a raw `HTMLElement` only when strictly required for legacy imperative APIs (e.g., `splitWidget.installResizer(element)`). When a shared DevTools UI primitive (`ui/kit`, `ui/components`, `ui/legacy`) would force callers to use `ref(...)` + imperative setters just to link elements together (such as a `<devtools-menu>` trigger anchor), extend the shared primitive with an HTML-native ID/attribute API in a standalone prerequisite CL rather than adding `ref(...)` boilerplate at call sites.
120
134
  * **Child Widgets:** Use `UI.Widget.widgetRef` to obtain the class instance of a child widget inside the view function if you need to call imperative methods on it. **Do NOT store child widget instances on `ViewOutput` as a final result** (doing so is only acceptable temporarily in intermediate migration CLs). Instead, either supply all needed configuration declaratively through setters/inputs on the child widget, or if imperative calls are strictly necessary, expose narrow action functions on `ViewOutput` (e.g., `output.doLayout = () => splitWidget.doLayout()`, `output.revealPosition = pos => childWidget.revealPosition(pos)`). Do not keep `get*ForTest()` methods that return child widget instances via `ViewOutput`; tests should query rendered `<devtools-widget>` elements via `.getWidget()` or assert on `ViewInput` via `createViewFunctionStub`.
121
135
 
122
136
  ### Visibility (`?hidden` Attribute Only)
@@ -125,9 +139,10 @@ Toggle element visibility declaratively using the HTML `?hidden` attribute:
125
139
  html`<div ?hidden=${!input.isVisible}>...</div>`
126
140
  ```
127
141
  Never combine a `.hidden` CSS class (`classMap({hidden: ...})` or `classList.toggle('hidden', ...)`) with `?hidden` (`inspectorCommon.css` already defines `[hidden] { display: none !important; }`).
142
+ * **`UI.Toolbar.Provider` Widgets (`new ToolbarItem(this.element)`):** `Widget.#showWidget()` unconditionally removes `'hidden'` from `this.element` when `Toolbar.appendToolbarItem` (or `show()`) mounts the widget. Any `UI.Widget` wrapping `this.element` in `UI.Toolbar.ToolbarItem` that can start hidden must re-apply `this.#toolbarItem.setVisible(...)` in `override show(...)` and `override wasShown()`, with a unit test mounting the widget into a `<devtools-toolbar>` while initially hidden.
128
143
 
129
144
  ### Declarative Default Focus (`autofocus` / `?autofocus`)
130
- `UI.Widget.prototype.focus()` natively queries `[autofocus]` via `getDefaultFocusedElement()` across both plain HTML elements (e.g. `<devtools-tree autofocus>`) and child widgets. Mark the default focus target with `autofocus` or `?autofocus=${...}` (ensuring at most one element has `autofocus` in any render state) instead of overriding `focus()`, calling `this.setDefaultFocusedElement(...)`, or plumbing focus closures through `ViewOutput`.
145
+ `UI.Widget.prototype.focus()` natively queries `[autofocus]` via `getDefaultFocusedElement()` across both plain HTML elements (e.g. `<devtools-tree autofocus>`) and child widgets. Mark the default focus target with `autofocus` or `?autofocus=${...}` directly in the Lit template (ensuring at most one element has `autofocus` in any render state) instead of overriding `focus()`, calling `this.setDefaultFocusedElement(...)`, plumbing focus closures through `ViewOutput`, or mutating `element.autofocus` / `setAttribute('autofocus', ...)` / `toggleAttribute('autofocus', ...)` imperatively in TypeScript or `ref(...)` callbacks.
131
146
 
132
147
  ### `<devtools-tree>` & Editable `<devtools-prompt ?editing>` Rows
133
148
  * Keep `<devtools-tree>` (`ui/kit/kit.js`) contracts intact without widening `front_end/ui/legacy/Treeoutline.ts` (`TreeViewElement`/`TreeViewTreeElement`). Drive selection and expansion purely via `?selected`, `?open`, `@select`, and `@expand`.
@@ -313,7 +328,7 @@ export class ParentWidget extends UI.Widget.Widget {
313
328
 
314
329
  ### 3\. Testing Widgets
315
330
 
316
- Testing focuses on the Presenter's logic. The View MUST be replaced by a stub using `createViewFunctionStub`.
331
+ Ship unit tests in the **same CL** as the presenter/view change (never defer tests to a follow-up test-only CL). Testing focuses on the Presenter's logic using `createViewFunctionStub`, while template layout is covered by `assertScreenshot` / E2E tests (per `docs/ui_engineering.md`). When adding targeted unit tests for view rendering, name the suite `describe('view', ...)` (never `describe('... DEFAULT_VIEW', ...)`), and avoid 80–150 line synthetic `DEFAULT_VIEW` DOM assertion suites that duplicate presenter tests.
317
332
 
318
333
  * **`describeWithEnvironment`**: Sets up the testing environment.
319
334
  * **`createViewFunctionStub`**: Stubs the view to capture `input` data.