Skip to content

Chrome DevTools for coding agents

feat: add css formatter class (#2707)

Samiya Caurf0b5fa4bde0a
diff --git a/src/formatters/CssFormatter.ts b/src/formatters/CssFormatter.ts
new file mode 100644
index 00000000..0c86a476
--- /dev/null
+++ b/src/formatters/CssFormatter.ts
@@ -0,0 +1,285 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {DevTools} from '../third_party/index.js';
+import type {MatchedStyles} from '../tools/ToolDefinition.js';
+
+export interface CssFormatterOptions {
+ uid: string;
+}
+
+/**
+ * Status of a CSS property in the cascade:
+ * - `active`: Winning declaration for this property name (printed without prefix tag).
+ * - `overloaded`: Overridden by a more specific or later CSS rule (`[overloaded]`).
+ * - `invalid`: Property name or value failed CSS parsing (`[invalid]`).
+ * - `disabled`: Commented out or programmatically disabled (`[disabled]`).
+ */
+export type CssPropertyStatus =
+ 'active' | 'overloaded' | 'invalid' | 'disabled';
+
+export interface StructuredCssProperty {
+ name: string;
+ value: string;
+ status: CssPropertyStatus;
+ important?: boolean;
+}
+
+export interface NodeStyleRule {
+ type: 'inline' | 'attributes' | 'transition';
+ selector: string;
+ properties: StructuredCssProperty[];
+}
+
+export interface AnimationRule {
+ type: 'animation';
+ name?: string;
+ selector: string;
+ properties: StructuredCssProperty[];
+}
+
+export type CascadeRule = NodeStyleRule | AnimationRule;
+
+export interface StructuredCssStyles {
+ element: {
+ uid: string;
+ selector: string;
+ };
+ rules: CascadeRule[];
+}
+
+const PROPERTY_STATE_MAP: Record<string, CssPropertyStatus> = {
+ [DevTools.CSSMatchedStyles.PropertyState.ACTIVE]: 'active',
+ [DevTools.CSSMatchedStyles.PropertyState.OVERLOADED]: 'overloaded',
+};
+
+class IndentedWriter {
+ readonly #lines: string[] = [];
+ #indent = 0;
+
+ constructor(baseIndent = 0) {
+ this.#indent = baseIndent;
+ }
+
+ indent(): void {
+ this.#indent += 2;
+ }
+
+ dedent(): void {
+ this.#indent = Math.max(0, this.#indent - 2);
+ }
+
+ writeLine(text: string): void {
+ this.#lines.push(' '.repeat(this.#indent) + text);
+ }
+
+ writeEmptyLine(): void {
+ this.#lines.push('');
+ }
+
+ writeComment(comment: string): void {
+ this.writeLine(`/* ${comment} */`);
+ }
+
+ lines(): string[] {
+ return this.#lines;
+ }
+}
+
+/**
+ * Formats a CSS property into standard CSS syntax with optional status tags.
+ *
+ * Status prefix convention:
+ * - 'active': Clean output without tags (e.g. `color: red;`).
+ * - 'overloaded' | 'invalid' | 'disabled': Tagged prefix (e.g. `[overloaded] color: blue;`).
+ */
+function formatPropertyLine(prop: StructuredCssProperty): string {
+ const stateStr = prop.status === 'active' ? '' : `[${prop.status}] `;
+ const imp =
+ prop.important && !/\s*!\s*important$/i.test(prop.value)
+ ? ' !important'
+ : '';
+ return `${stateStr}${prop.name}: ${prop.value}${imp};`;
+}
+
+function getCascadeRuleHeader(rule: CascadeRule): string {
+ let selector: string;
+ switch (rule.type) {
+ case 'inline':
+ case 'transition':
+ case 'animation':
+ case 'attributes':
+ selector = rule.selector;
+ break;
+ }
+ const source = 'source' in rule ? rule.source : undefined;
+ return source ? `${selector} (${source})` : selector;
+}
+
+function appendRule(writer: IndentedWriter, rule: CascadeRule): void {
+ const header = getCascadeRuleHeader(rule);
+ writer.writeLine(`${header} {`);
+ writer.indent();
+ for (const prop of rule.properties) {
+ writer.writeLine(formatPropertyLine(prop));
+ }
+ writer.dedent();
+ writer.writeLine('}');
+}
+
+function appendCssSectionsToString(
+ writer: IndentedWriter,
+ styles: StructuredCssStyles,
+): void {
+ for (const rule of styles.rules) {
+ writer.writeEmptyLine();
+ appendRule(writer, rule);
+ }
+}
+
+export class CssFormatter {
+ static #getStyleProperties(
+ style: DevTools.CSSStyleDeclaration.CSSStyleDeclaration,
+ ): DevTools.CSSProperty.CSSProperty[] {
+ return style.leadingProperties?.() ?? style.allProperties();
+ }
+
+ /**
+ * Aggregates all cascading rules impacting the target node.
+ */
+ static collectRules(matchedStyles: MatchedStyles): CascadeRule[] {
+ const rules: CascadeRule[] = [];
+ CssFormatter.#collectNodeStyles(rules, matchedStyles);
+ return rules;
+ }
+
+ static #collectNodeStyles(
+ rules: CascadeRule[],
+ matchedStyles: MatchedStyles,
+ ): void {
+ for (const style of matchedStyles.nodeStyles?.() ?? []) {
+ const properties = CssFormatter.#getStyleProperties(style);
+ if (!properties.length) {
+ continue;
+ }
+
+ if (style.type === DevTools.CSSStyleDeclaration.Type.Transition) {
+ rules.push({
+ type: 'transition',
+ selector: 'transitions style',
+ properties: CssFormatter.#formatProperties(properties, matchedStyles),
+ });
+ } else if (style.type === DevTools.CSSStyleDeclaration.Type.Animation) {
+ const animName = style.animationName();
+ rules.push({
+ type: 'animation',
+ ...(animName ? {name: animName} : {}),
+ selector: animName ? `${animName} animation` : 'animation style',
+ properties: CssFormatter.#formatProperties(properties, matchedStyles),
+ });
+ } else if (style.type === DevTools.CSSStyleDeclaration.Type.Attributes) {
+ const node = matchedStyles.nodeForStyle(style);
+ const tag = node ? node.nodeNameInCorrectCase() : '';
+ rules.push({
+ type: 'attributes',
+ selector: tag ? `${tag}[attributes style]` : '[attributes style]',
+ properties: CssFormatter.#formatProperties(properties, matchedStyles),
+ });
+ } else if (style.type === DevTools.CSSStyleDeclaration.Type.Inline) {
+ rules.push({
+ type: 'inline',
+ selector: 'element.style',
+ properties: CssFormatter.#formatProperties(properties, matchedStyles),
+ });
+ }
+ }
+ }
+
+ static #formatProperties(
+ props: DevTools.CSSProperty.CSSProperty[],
+ matchedStyles: MatchedStyles,
+ ): StructuredCssProperty[] {
+ return props.map(p =>
+ CssFormatter.#formatStructuredProperty(p, matchedStyles),
+ );
+ }
+
+ static #formatStructuredProperty(
+ prop: DevTools.CSSProperty.CSSProperty,
+ matchedStyles: MatchedStyles,
+ ): StructuredCssProperty {
+ let status: CssPropertyStatus = 'active';
+ if (prop.parsedOk === false) {
+ status = 'invalid';
+ } else if (prop.disabled) {
+ status = 'disabled';
+ } else {
+ const state = matchedStyles.propertyState?.(prop);
+ if (state) {
+ status = PROPERTY_STATE_MAP[state] ?? 'active';
+ }
+ }
+
+ let value = prop.value;
+ const isImportant = Boolean(prop.important);
+ if (isImportant) {
+ value = value.replace(/\s*!\s*important$/i, '').trimEnd();
+ }
+
+ return {
+ name: prop.name,
+ value,
+ status,
+ ...(isImportant ? {important: true} : {}),
+ };
+ }
+
+ readonly #matchedStyles: MatchedStyles;
+ readonly #options: CssFormatterOptions;
+ readonly #cascadeRules: readonly CascadeRule[];
+
+ constructor(
+ matchedStyles: MatchedStyles,
+ options: CssFormatterOptions,
+ cascadeRules?: readonly CascadeRule[],
+ ) {
+ this.#matchedStyles = matchedStyles;
+ this.#options = options;
+ this.#cascadeRules =
+ cascadeRules ?? CssFormatter.collectRules(matchedStyles);
+ }
+
+ get rules(): readonly CascadeRule[] {
+ return this.#cascadeRules;
+ }
+
+ toString(): string {
+ const json = this.toJSON();
+ const lines: string[] = [
+ `Styles for ${json.element.selector} (uid: "${json.element.uid}"):`,
+ ];
+
+ if (this.#cascadeRules.length === 0) {
+ lines.push('', ' (no styles)');
+ return lines.join('\n');
+ }
+
+ const writer = new IndentedWriter(2);
+ appendCssSectionsToString(writer, json);
+ lines.push(...writer.lines());
+ return lines.join('\n');
+ }
+
+ toJSON(): StructuredCssStyles {
+ return {
+ element: {
+ uid: this.#options.uid,
+ selector: this.#matchedStyles.node?.()?.simpleSelector() ?? '',
+ },
+ rules: [...this.#cascadeRules],
+ };
+ }
+}
diff --git a/src/tools/ToolDefinition.ts b/src/tools/ToolDefinition.ts
index 8b08f898..3bed3f94 100644
--- a/src/tools/ToolDefinition.ts
+++ b/src/tools/ToolDefinition.ts
@@ -322,6 +322,8 @@ export type Context = Readonly<{
): Promise<DevTools.HeapSnapshotModel.HeapSnapshotModel.ItemsRange>;
}>;
+export type MatchedStyles = DevTools.CSSMatchedStyles.CSSMatchedStyles;
+
/**
* Only add methods used by tools/*.
*/
diff --git a/tests/formatters/CssFormatter.test.js.snapshot b/tests/formatters/CssFormatter.test.js.snapshot
new file mode 100644
index 00000000..2da21fb1
--- /dev/null
+++ b/tests/formatters/CssFormatter.test.js.snapshot
@@ -0,0 +1,113 @@
+exports[`CssFormatter > formats element label with id, class, and uid and no styles toJSON 1`] = `
+{
+ "element": {
+ "uid": "1_1",
+ "selector": "div#main"
+ },
+ "rules": []
+}
+`;
+
+exports[`CssFormatter > formats element label with id, class, and uid and no styles toString 1`] = `
+Styles for div#main (uid: "1_1"):
+
+ (no styles)
+`;
+
+exports[`CssFormatter > formats inline styles with active and overloaded properties toJSON 1`] = `
+{
+ "element": {
+ "uid": "1_2",
+ "selector": "button"
+ },
+ "rules": [
+ {
+ "type": "inline",
+ "selector": "element.style",
+ "properties": [
+ {
+ "name": "color",
+ "value": "red",
+ "status": "overloaded"
+ },
+ {
+ "name": "font-size",
+ "value": "14px",
+ "status": "active",
+ "important": true
+ }
+ ]
+ }
+ ]
+}
+`;
+
+exports[`CssFormatter > formats inline styles with active and overloaded properties toString 1`] = `
+Styles for button (uid: "1_2"):
+
+ element.style {
+ [overloaded] color: red;
+ font-size: 14px !important;
+ }
+`;
+
+exports[`CssFormatter > formats transition, animation, and attributes styles toJSON 1`] = `
+{
+ "element": {
+ "uid": "table-1",
+ "selector": "table#data"
+ },
+ "rules": [
+ {
+ "type": "transition",
+ "selector": "transitions style",
+ "properties": [
+ {
+ "name": "opacity",
+ "value": "1",
+ "status": "active"
+ }
+ ]
+ },
+ {
+ "type": "animation",
+ "name": "pulse",
+ "selector": "pulse animation",
+ "properties": [
+ {
+ "name": "transform",
+ "value": "scale(1.2)",
+ "status": "active"
+ }
+ ]
+ },
+ {
+ "type": "attributes",
+ "selector": "table[attributes style]",
+ "properties": [
+ {
+ "name": "border",
+ "value": "1px",
+ "status": "active"
+ }
+ ]
+ }
+ ]
+}
+`;
+
+exports[`CssFormatter > formats transition, animation, and attributes styles toString 1`] = `
+Styles for table#data (uid: "table-1"):
+
+ transitions style {
+ opacity: 1;
+ }
+
+ pulse animation {
+ transform: scale(1.2);
+ }
+
+ table[attributes style] {
+ border: 1px;
+ }
+`;
diff --git a/tests/formatters/CssFormatter.test.ts b/tests/formatters/CssFormatter.test.ts
new file mode 100644
index 00000000..b59f86a0
--- /dev/null
+++ b/tests/formatters/CssFormatter.test.ts
@@ -0,0 +1,90 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {afterEach, describe, it} from 'node:test';
+import sinon from 'sinon';
+
+import {CssFormatter} from '../../src/formatters/CssFormatter.js';
+import {DevTools} from '../../src/third_party/index.js';
+import {
+ createMockCSSInlineStyle,
+ createMockCSSMatchedStyles,
+ createMockCSSProperty,
+ createMockCSSStyleDeclaration,
+ createMockDOMNode,
+} from '../mocks.js';
+
+describe('CssFormatter', () => {
+ afterEach(() => {
+ sinon.restore();
+ });
+
+ function formatterTest(
+ label: string,
+ setup: (t: it.TestContext) => CssFormatter | Promise<CssFormatter>,
+ ) {
+ it(label + ' toString', async t => {
+ const formatter = await setup(t);
+ t.assert.snapshot(formatter.toString());
+ });
+ it(label + ' toJSON', async t => {
+ const formatter = await setup(t);
+ t.assert.snapshot(JSON.stringify(formatter.toJSON(), null, 2));
+ });
+ }
+
+ formatterTest(
+ 'formats element label with id, class, and uid and no styles',
+ () => {
+ const matchedStyles = createMockCSSMatchedStyles({node: 'div#main'});
+ return new CssFormatter(matchedStyles, {uid: '1_1'});
+ },
+ );
+
+ formatterTest(
+ 'formats inline styles with active and overloaded properties',
+ () => {
+ const prop1 = createMockCSSProperty('color', 'red');
+ const prop2 = createMockCSSProperty('font-size', '14px', {
+ important: true,
+ });
+
+ const matchedStyles = createMockCSSMatchedStyles({
+ nodeStyles: [createMockCSSInlineStyle([prop1, prop2])],
+ propertyStates: new Map([[prop1, 'Overloaded']]),
+ });
+
+ return new CssFormatter(matchedStyles, {uid: '1_2'});
+ },
+ );
+
+ formatterTest('formats transition, animation, and attributes styles', () => {
+ const transitionStyle = createMockCSSStyleDeclaration(
+ [createMockCSSProperty('opacity', '1')],
+ {type: DevTools.CSSStyleDeclaration.Type.Transition},
+ );
+ const animationStyle = createMockCSSStyleDeclaration(
+ [createMockCSSProperty('transform', 'scale(1.2)')],
+ {
+ type: DevTools.CSSStyleDeclaration.Type.Animation,
+ animationName: 'pulse',
+ },
+ );
+ const tableNode = createMockDOMNode({selector: 'table#data'});
+ const attributesStyle = createMockCSSStyleDeclaration(
+ [createMockCSSProperty('border', '1px')],
+ {type: DevTools.CSSStyleDeclaration.Type.Attributes},
+ );
+
+ const matchedStyles = createMockCSSMatchedStyles({
+ node: tableNode,
+ nodeStyles: [transitionStyle, animationStyle, attributesStyle],
+ nodeForStyleMap: new Map([[attributesStyle, tableNode]]),
+ });
+
+ return new CssFormatter(matchedStyles, {uid: 'table-1'});
+ });
+});
diff --git a/tests/mocks.ts b/tests/mocks.ts
index e34ce93f..0af6432f 100644
--- a/tests/mocks.ts
+++ b/tests/mocks.ts
@@ -28,7 +28,7 @@ import sinon from 'sinon';
import {McpContext} from '../src/McpContext.js';
import {McpPage} from '../src/McpPage.js';
import {McpResponse} from '../src/McpResponse.js';
-import {CdpPage} from '../src/third_party/index.js';
+import {CdpPage, DevTools} from '../src/third_party/index.js';
import type {Page} from '../src/third_party/index.js';
export type MockMcpPage = sinon.SinonStubbedInstance<McpPage> & {
@@ -36,6 +36,13 @@ export type MockMcpPage = sinon.SinonStubbedInstance<McpPage> & {
};
export type MockMcpContext = sinon.SinonStubbedInstance<McpContext>;
export type MockMcpResponse = sinon.SinonStubbedInstance<McpResponse>;
+export type MockDOMNode = sinon.SinonStubbedInstance<DevTools.DOMModel.DOMNode>;
+export type MockCSSProperty =
+ sinon.SinonStubbedInstance<DevTools.CSSProperty.CSSProperty>;
+export type MockCSSStyleDeclaration =
+ sinon.SinonStubbedInstance<DevTools.CSSStyleDeclaration.CSSStyleDeclaration>;
+export type MockCSSMatchedStyles =
+ sinon.SinonStubbedInstance<DevTools.CSSMatchedStyles.CSSMatchedStyles>;
/**
* A minimal event emitter used to back mocked `on`/`off`/`emit` methods on
@@ -135,3 +142,133 @@ export function createHandlerMocks(): {
const response = createMockMcpResponse();
return {page, context, response};
}
+
+function isBackendNodeId(
+ id: unknown,
+): id is DevTools.Protocol.DOM.BackendNodeId {
+ return typeof id === 'number';
+}
+
+export interface MockDOMNodeOptions {
+ selector?: string;
+ backendNodeId?: number;
+}
+
+export function createMockDOMNode(
+ options: MockDOMNodeOptions = {},
+): MockDOMNode {
+ const node = sinon.createStubInstance(DevTools.DOMModel.DOMNode);
+ const selector = options.selector ?? 'button';
+ const backendNodeId = options.backendNodeId ?? 1;
+ if (isBackendNodeId(backendNodeId)) {
+ node.backendNodeId.returns(backendNodeId);
+ }
+ node.simpleSelector.returns(selector);
+ node.nodeNameInCorrectCase.returns(selector.split(/[#.]/)[0] || selector);
+ return node;
+}
+
+export interface MockCSSPropertyOptions {
+ important?: boolean;
+ parsedOk?: boolean;
+ disabled?: boolean;
+}
+
+export function createMockCSSProperty(
+ name: string,
+ value: string,
+ options: MockCSSPropertyOptions = {},
+): MockCSSProperty {
+ const prop = sinon.createStubInstance(DevTools.CSSProperty.CSSProperty);
+ prop.name = name;
+ prop.value = value;
+ prop.important = options.important ?? false;
+ prop.parsedOk = options.parsedOk ?? true;
+ prop.disabled = options.disabled ?? false;
+ return prop;
+}
+
+export interface MockCSSStyleDeclarationOptions {
+ rule?: DevTools.CSSRule.CSSRule | null;
+ type?: DevTools.CSSStyleDeclaration.Type;
+ animationName?: string;
+ range?: {
+ startLine: number;
+ startColumn: number;
+ endLine: number;
+ endColumn: number;
+ };
+}
+
+export function createMockCSSStyleDeclaration(
+ properties: DevTools.CSSProperty.CSSProperty[],
+ options: MockCSSStyleDeclarationOptions = {},
+): MockCSSStyleDeclaration {
+ const style = sinon.createStubInstance(
+ DevTools.CSSStyleDeclaration.CSSStyleDeclaration,
+ );
+ style.type = options.type ?? DevTools.CSSStyleDeclaration.Type.Regular;
+ style.allProperties.returns(properties);
+ style.leadingProperties.returns(properties);
+ style.parentRule = options.rule ?? null;
+ style.animationName.returns(options.animationName ?? '');
+ if (options.range) {
+ Object.assign(style, {range: options.range});
+ }
+ return style;
+}
+
+export function createMockCSSInlineStyle(
+ properties: DevTools.CSSProperty.CSSProperty[],
+): MockCSSStyleDeclaration {
+ return createMockCSSStyleDeclaration(properties, {
+ type: DevTools.CSSStyleDeclaration.Type.Inline,
+ });
+}
+
+export interface MockCSSMatchedStylesParams {
+ node?: string | DevTools.DOMModel.DOMNode;
+ nodeStyles?: DevTools.CSSStyleDeclaration.CSSStyleDeclaration[];
+ parentNode?: string | DevTools.DOMModel.DOMNode;
+ nodeForStyleMap?: Map<
+ DevTools.CSSStyleDeclaration.CSSStyleDeclaration,
+ DevTools.DOMModel.DOMNode
+ >;
+ propertyStates?: Map<DevTools.CSSProperty.CSSProperty, string>;
+ matchingSelectorsMap?: Map<unknown, number[]>;
+}
+
+export function createMockCSSMatchedStyles(
+ params: MockCSSMatchedStylesParams = {},
+): MockCSSMatchedStyles {
+ const mockNode =
+ typeof params.node === 'string'
+ ? createMockDOMNode({selector: params.node})
+ : (params.node ?? createMockDOMNode());
+ const nodeStyles = params.nodeStyles ?? [];
+
+ const defaultParentNode =
+ typeof params.parentNode === 'string'
+ ? createMockDOMNode({selector: params.parentNode})
+ : params.parentNode;
+ const nodeForStyleMap = params.nodeForStyleMap ?? new Map();
+
+ const propertyStates = params.propertyStates ?? new Map();
+
+ const mock = sinon.createStubInstance(
+ DevTools.CSSMatchedStyles.CSSMatchedStyles,
+ );
+ mock.node.returns(mockNode);
+ mock.nodeStyles.returns(nodeStyles);
+
+ mock.nodeForStyle.callsFake(
+ style => nodeForStyleMap.get(style) ?? defaultParentNode ?? null,
+ );
+
+ mock.propertyState.callsFake(prop => propertyStates.get(prop) ?? 'Active');
+ mock.getMatchingSelectors.callsFake(
+ rule => params.matchingSelectorsMap?.get(rule) ?? [],
+ );
+
+ return mock;
+}