/**
* CDP Inspector — Chrome DevTools Protocol integration for deep CSS inspection
*
* Manages a persistent CDP session per active page for:
* - Full CSS rule cascade inspection (matched rules, computed styles, inline styles)
* - Box model measurement
* - Live CSS modification via CSS.setStyleTexts
* - Modification history with undo/reset
*
* Session lifecycle:
* Create on first inspect call → reuse across inspections → detach on
* navigation/tab switch/shutdown → re-create transparently on next call
*/
import type { Page } from 'playwright';
// ─── Types ──────────────────────────────────────────────────────
export interface InspectorResult {
selector: string;
tagName: string;
id: string | null;
classes: string[];
attributes: Record<string, string>;
boxModel: {
content: { x: number; y: number; width: number; height: number };
padding: { top: number; right: number; bottom: number; left: number };
border: { top: number; right: number; bottom: number; left: number };
margin: { top: number; right: number; bottom: number; left: number };
};
computedStyles: Record<string, string>;
matchedRules: Array<{
selector: string;
properties: Array<{ name: string; value: string; important: boolean; overridden: boolean }>;
source: string;
sourceLine: number;
sourceColumn: number;
specificity: { a: number; b: number; c: number };
media?: string;
userAgent: boolean;
styleSheetId?: string;
range?: object;
}>;
inlineStyles: Record<string, string>;
pseudoElements: Array<{
pseudo: string;
rules: Array<{ selector: string; properties: string }>;
}>;
}
export interface StyleModification {
selector: string;
property: string;
oldValue: string;
newValue: string;
source: string;
sourceLine: number;
timestamp: number;
method: 'setStyleTexts' | 'inline';
}
// ─── Constants ──────────────────────────────────────────────────
/** ~55 key CSS properties for computed style output */
const KEY_CSS_PROPERTIES = [
'display', 'position', 'top', 'right', 'bottom', 'left',
'float', 'clear', 'z-index', 'overflow', 'overflow-x', 'overflow-y',
'width', 'height', 'min-width', 'max-width', 'min-height', 'max-height',
'margin-top', 'margin-right', 'margin-bottom', 'margin-left',
'padding-top', 'padding-right', 'padding-bottom', 'padding-left',
'border-top-width', 'border-right-width', 'border-bottom-width', 'border-left-width',
'border-style', 'border-color',
'font-family', 'font-size', 'font-weight', 'line-height',
'color', 'background-color', 'background-image', 'opacity',
'box-shadow', 'border-radius', 'transform', 'transition',
'flex-direction', 'flex-wrap', 'justify-content', 'align-items', 'gap',
'grid-template-columns', 'grid-template-rows',
'text-align', 'text-decoration', 'visibility', 'cursor', 'pointer-events',
];
const KEY_CSS_SET = new Set(KEY_CSS_PROPERTIES);
// ─── Session Management ─────────────────────────────────────────
/** Map of Page → CDP session. Sessions are reused per page. */
const cdpSessions = new WeakMap<Page, any>();
/** Track which pages have initialized DOM+CSS domains */
const initializedPages = new WeakSet<Page>();
/**
* Get or create a CDP session for the given page.
* Enables DOM + CSS domains on first use.
*/
async function getOrCreateSession(page: Page): Promise<any> {
let session = cdpSessions.get(page);
if (session) {
// Verify session is still alive
try {
await session.send('DOM.getDocument', { depth: 0 });
return session;
} catch {
// Session is stale — recreate
cdpSessions.delete(page);
initializedPages.delete(page);
}
}
session = await page.context().newCDPSession(page);
cdpSessions.set(page, session);
// Enable DOM and CSS domains
await session.send('DOM.enable');
await session.send('CSS.enable');
initializedPages.add(page);
// Auto-detach on navigation
page.once('framenavigated', () => {
try {
session.detach().catch(() => {});
} catch {}
cdpSessions.delete(page);
initializedPages.delete(page);
});
return session;
}
// ─── Modification History ───────────────────────────────────────
const modificationHistory: StyleModification[] = [];
// ─── Specificity Calculation ────────────────────────────────────
/**
* Parse a CSS selector and compute its specificity as {a, b, c}.
* a = ID selectors, b = class/attr/pseudo-class, c = type/pseudo-element
*/
function computeSpecificity(selector: string): { a: number; b: number; c: number } {
let a = 0, b = 0, c = 0;
// Remove :not() wrapper but count its contents
let cleaned = selector;
// Count IDs: #foo
const ids = cleaned.match(/#[a-zA-Z_-][\w-]*/g);
if (ids) a += ids.length;
// Count classes: .foo, attribute selectors: [attr], pseudo-classes: :hover (not ::)
const classes = cleaned.match(/\.[a-zA-Z_-][\w-]*/g);
if (classes) b += classes.length;
const attrs = cleaned.match(/\[[^\]]+\]/g);
if (attrs) b += attrs.length;
const pseudoClasses = cleaned.match(/(?<!:):[a-zA-Z][\w-]*/g);
if (pseudoClasses) b += pseudoClasses.length;
// Count type selectors: div, span (not * universal)
const types = cleaned.match(/(?:^|[\s+~>])([a-zA-Z][\w-]*)/g);
if (types) c += types.length;
// Count pseudo-elements: ::before, ::after
const pseudoElements = cleaned.match(/::[a-zA-Z][\w-]*/g);
if (pseudoElements) c += pseudoElements.length;
return { a, b, c };
}
/**
* Compare specificities: returns negative if s1 < s2, positive if s1 > s2, 0 if equal.
*/
function compareSpecificity(
s1: { a: number; b: number; c: number },
s2: { a: number; b: number; c: number }
): number {
if (s1.a !== s2.a) return s1.a - s2.a;
if (s1.b !== s2.b) return s1.b - s2.b;
return s1.c - s2.c;
}
// ─── Core Functions ─────────────────────────────────────────────
/**
* Inspect an element via CDP, returning full CSS cascade data.
*/
export async function inspectElement(
page: Page,
selector: string,
options?: { includeUA?: boolean }
): Promise<InspectorResult> {
const session = await getOrCreateSession(page);
// Get document root
const { root } = await session.send('DOM.getDocument', { depth: 0 });
// Query for the element
let nodeId: number;
try {
const result = await session.send('DOM.querySelector', {
nodeId: root.nodeId,
selector,
});
nodeId = result.nodeId;
if (!nodeId) throw new Error(`Element not found: ${selector}`);
} catch (err: any) {
throw new Error(`Element not found: ${selector} — ${err.message}`);
}
// Get element attributes
const { node } = await session.send('DOM.describeNode', { nodeId, depth: 0 });
const tagName = (node.localName || node.nodeName || '').toLowerCase();
const attrPairs = node.attributes || [];
const attributes: Record<string, string> = {};
for (let i = 0; i < attrPairs.length; i += 2) {
attributes[attrPairs[i]] = attrPairs[i + 1];
}
const id = attributes.id || null;
const classes = attributes.class ? attributes.class.split(/\s+/).filter(Boolean) : [];
// Get box model
let boxModel = {
content: { x: 0, y: 0, width: 0, height: 0 },
padding: { top: 0, right: 0, bottom: 0, left: 0 },
border: { top: 0, right: 0, bottom: 0, left: 0 },
margin: { top: 0, right: 0, bottom: 0, left: 0 },
};
try {
const boxData = await session.send('DOM.getBoxModel', { nodeId });
const model = boxData.model;
// Content quad: [x1,y1, x2,y2, x3,y3, x4,y4]
const content = model.content;
const padding = model.padding;
const border = model.border;
const margin = model.margin;
const contentX = content[0];
const contentY = content[1];
const contentWidth = content[2] - content[0];
const contentHeight = content[5] - content[1];
boxModel = {
content: { x: contentX, y: contentY, width: contentWidth, height: contentHeight },
padding: {
top: content[1] - padding[1],
right: padding[2] - content[2],
bottom: padding[5] - content[5],
left: content[0] - padding[0],
},
border: {
top: padding[1] - border[1],
right: border[2] - padding[2],
bottom: border[5] - padding[5],
left: padding[0] - border[0],
},
margin: {
top: border[1] - margin[1],
right: margin[2] - border[2],
bottom: margin[5] - border[5],
left: border[0] - margin[0],
},
};
} catch {
// Element may not have a box model (e.g., display:none)
}
// Get matched styles
const matchedData = await session.send('CSS.getMatchedStylesForNode', { nodeId });
// Get computed styles
const computedData = await session.send('CSS.getComputedStyleForNode', { nodeId });
const computedStyles: Record<string, string> = {};
for (const entry of computedData.computedStyle) {
if (KEY_CSS_SET.has(entry.name)) {
computedStyles[entry.name] = entry.value;
}
}
// Get inline styles
const inlineData = await session.send('CSS.getInlineStylesForNode', { nodeId });
const inlineStyles: Record<string, string> = {};
if (inlineData.inlineStyle?.cssProperties) {
for (const prop of inlineData.inlineStyle.cssProperties) {
if (prop.name && prop.value && !prop.disabled) {
inlineStyles[prop.name] = prop.value;
}
}
}
// Process matched rules
const matchedRules: InspectorResult['matchedRules'] = [];
// Track all property values to mark overridden ones
const seenProperties = new Map<string, number>(); // property → index of highest-specificity rule
if (matchedData.matchedCSSRules) {
for (const match of matchedData.matchedCSSRules) {
const rule = match.rule;
const isUA = rule.origin === 'user-agent';
if (isUA && !options?.includeUA) continue;
// Get the matching selector text
let selectorText = '';
if (rule.selectorList?.selectors) {
// Use the specific matching selector
const matchingIdx = match.matchingSelectors?.[0] ?? 0;
selectorText = rule.selectorList.selectors[matchingIdx]?.text || rule.selectorList.text || '';
}
// Get source info
let source = 'inline';
let sourceLine = 0;
let sourceColumn = 0;
let styleSheetId: string | undefined;
let range: object | undefined;
if (rule.styleSheetId) {
styleSheetId = rule.styleSheetId;
try {
// Try to resolve stylesheet URL
source = rule.origin === 'regular' ? (rule.styleSheetId || 'stylesheet') : rule.origin;
} catch {}
}
if (rule.style?.range) {
range = rule.style.range;
sourceLine = rule.style.range.startLine || 0;
sourceColumn = rule.style.range.startColumn || 0;
}
// Try to get a friendly source name from stylesheet
if (styleSheetId) {
try {
// Stylesheet URL might be embedded in the rule data
// CDP provides sourceURL in some cases
if (rule.style?.cssText) {
// Parse source from the styleSheetId metadata
}
} catch {}
}
// Get media query if present
let media: string | undefined;
if (match.rule?.media) {
const mediaList = match.rule.media;
if (Array.isArray(mediaList) && mediaList.length > 0) {
media = mediaList.map((m: any) => m.text).filter(Boolean).join(', ');
}
}
const specificity = computeSpecificity(selectorText);
// Process CSS properties
const properties: Array<{ name: string; value: string; important: boolean; overridden: boolean }> = [];
if (rule.style?.cssProperties) {
for (const prop of rule.style.cssProperties) {
if (!prop.name || prop.disabled) continue;
// Skip internal/vendor properties unless they are in our key set
if (prop.name.startsWith('-') && !KEY_CSS_SET.has(prop.name)) continue;
properties.push({
name: prop.name,
value: prop.value || '',
important: prop.important || (prop.value?.includes('!important') ?? false),
overridden: false, // will be set later
});
}
}
matchedRules.push({
selector: selectorText,
properties,
source,
sourceLine,
sourceColumn,
specificity,
media,
userAgent: isUA,
styleSheetId,
range,
});
}
}
// Sort by specificity (highest first — these win)
matchedRules.sort((a, b) => -compareSpecificity(a.specificity, b.specificity));
// Mark overridden properties: the first rule in the sorted list (highest specificity) wins
for (let i = 0; i < matchedRules.length; i++) {
for (const prop of matchedRules[i].properties) {
const key = prop.name;
if (!seenProperties.has(key)) {
seenProperties.set(key, i);
} else {
// This property was already declared by a higher-specificity rule
// Unless this one is !important and the earlier one isn't
const earlierIdx = seenProperties.get(key)!;
const earlierRule = matchedRules[earlierIdx];
const earlierProp = earlierRule.properties.find(p => p.name === key);
if (prop.important && earlierProp && !earlierProp.important) {
// This !important overrides the earlier non-important
if (earlierProp) earlierProp.overridden = true;
seenProperties.set(key, i);
} else {
prop.overridden = true;
}
}
}
}
// Process pseudo-elements
const pseudoElements: InspectorResult['pseudoElements'] = [];
if (matchedData.pseudoElements) {
for (const pseudo of matchedData.pseudoElements) {
const pseudoType = pseudo.pseudoType || 'unknown';
const rules: Array<{ selector: string; properties: string }> = [];
if (pseudo.matches) {
for (const match of pseudo.matches) {
const rule = match.rule;
const sel = rule.selectorList?.text || '';
const props = (rule.style?.cssProperties || [])
.filter((p: any) => p.name && !p.disabled)
.map((p: any) => `${p.name}: ${p.value}`)
.join('; ');
if (props) {
rules.push({ selector: sel, properties: props });
}
}
}
if (rules.length > 0) {
pseudoElements.push({ pseudo: `::${pseudoType}`, rules });
}
}
}
// Resolve stylesheet URLs for better source info
for (const rule of matchedRules) {
if (rule.styleSheetId && rule.source !== 'inline') {
try {
const sheetMeta = await session.send('CSS.getStyleSheetText', { styleSheetId: rule.styleSheetId }).catch(() => null);
// Try to get the stylesheet header for URL info
// The styleSheetId itself is opaque, but we can try to get source URL
} catch {}
}
}
return {
selector,
tagName,
id,
classes,
attributes,
boxModel,
computedStyles,
matchedRules,
inlineStyles,
pseudoElements,
};
}
/**
* Modify a CSS property on an element.
* Uses CSS.setStyleTexts in headed mode, falls back to inline style in headless.
*/
export async function modifyStyle(
page: Page,
selector: string,
property: string,
value: string
): Promise<StyleModification> {
// Validate CSS property name
if (!/^[a-zA-Z-]+$/.test(property)) {
throw new Error(`Invalid CSS property name: ${property}. Only letters and hyphens allowed.`);
}
let oldValue = '';
let source = 'inline';
let sourceLine = 0;
let method: 'setStyleTexts' | 'inline' = 'inline';
try {
// Try CDP approach first
const session = await getOrCreateSession(page);
const result = await inspectElement(page, selector);
oldValue = result.computedStyles[property] || '';
// Find the most-specific matching rule that has this property
let targetRule: InspectorResult['matchedRules'][0] | null = null;
for (const rule of result.matchedRules) {
if (rule.userAgent) continue;
const hasProp = rule.properties.some(p => p.name === property);
if (hasProp && rule.styleSheetId && rule.range) {
targetRule = rule;
break;
}
}
if (targetRule?.styleSheetId && targetRule.range) {
// Modify via CSS.setStyleTexts
const range = targetRule.range as any;
// Get current style text
const styleText = await session.send('CSS.getStyleSheetText', {
styleSheetId: targetRule.styleSheetId,
});
// Build new style text by replacing the property value
const currentProps = targetRule.properties;
const newPropsText = currentProps
.map(p => {
if (p.name === property) {
return `${p.name}: ${value}`;
}
return `${p.name}: ${p.value}`;
})
.join('; ');
try {
await session.send('CSS.setStyleTexts', {
edits: [{
styleSheetId: targetRule.styleSheetId,
range,
text: newPropsText,
}],
});
method = 'setStyleTexts';
source = `${targetRule.source}:${targetRule.sourceLine}`;
sourceLine = targetRule.sourceLine;
} catch {
// Fall back to inline
}
}
if (method === 'inline') {
// Fallback: modify via inline style
await page.evaluate(
([sel, prop, val]) => {
const el = document.querySelector(sel);
if (!el) throw new Error(`Element not found: ${sel}`);
(el as HTMLElement).style.setProperty(prop, val);
},
[selector, property, value]
);
}
} catch (err: any) {
// Full fallback: use page.evaluate for headless
await page.evaluate(
([sel, prop, val]) => {
const el = document.querySelector(sel);
if (!el) throw new Error(`Element not found: ${sel}`);
(el as HTMLElement).style.setProperty(prop, val);
},
[selector, property, value]
);
}
const modification: StyleModification = {
selector,
property,
oldValue,
newValue: value,
source,
sourceLine,
timestamp: Date.now(),
method,
};
modificationHistory.push(modification);
return modification;
}
/**
* Undo a modification by index (or last if no index given).
*/
export async function undoModification(page: Page, index?: number): Promise<void> {
const idx = index ?? modificationHistory.length - 1;
if (idx < 0 || idx >= modificationHistory.length) {
throw new Error(`No modification at index ${idx}. History has ${modificationHistory.length} entries.`);
}
const mod = modificationHistory[idx];
if (mod.method === 'setStyleTexts') {
// Try to restore via CDP
try {
await modifyStyle(page, mod.selector, mod.property, mod.oldValue);
// Remove the undo modification from history (it's a restore, not a new mod)
modificationHistory.pop();
} catch {
// Fall back to inline restore
await page.evaluate(
([sel, prop, val]) => {
const el = document.querySelector(sel);
if (!el) return;
if (val) {
(el as HTMLElement).style.setProperty(prop, val);
} else {
(el as HTMLElement).style.removeProperty(prop);
}
},
[mod.selector, mod.property, mod.oldValue]
);
}
} else {
// Inline modification — restore or remove
await page.evaluate(
([sel, prop, val]) => {
const el = document.querySelector(sel);
if (!el) return;
if (val) {
(el as HTMLElement).style.setProperty(prop, val);
} else {
(el as HTMLElement).style.removeProperty(prop);
}
},
[mod.selector, mod.property, mod.oldValue]
);
}
modificationHistory.splice(idx, 1);
}
/**
* Get the full modification history.
*/
export function getModificationHistory(): StyleModification[] {
return [...modificationHistory];
}
/**
* Reset all modifications, restoring original values.
*/
export async function resetModifications(page: Page): Promise<void> {
// Restore in reverse order
for (let i = modificationHistory.length - 1; i >= 0; i--) {
const mod = modificationHistory[i];
try {
await page.evaluate(
([sel, prop, val]) => {
const el = document.querySelector(sel);
if (!el) return;
if (val) {
(el as HTMLElement).style.setProperty(prop, val);
} else {
(el as HTMLElement).style.removeProperty(prop);
}
},
[mod.selector, mod.property, mod.oldValue]
);
} catch {
// Best effort
}
}
modificationHistory.length = 0;
}
/**
* Format an InspectorResult for CLI text output.
*/
export function formatInspectorResult(
result: InspectorResult,
options?: { includeUA?: boolean }
): string {
const lines: string[] = [];
// Element header
const classStr = result.classes.length > 0 ? ` class="${result.classes.join(' ')}"` : '';
const idStr = result.id ? ` id="${result.id}"` : '';
lines.push(`Element: <${result.tagName}${idStr}${classStr}>`);
lines.push(`Selector: ${result.selector}`);
const w = Math.round(result.boxModel.content.width + result.boxModel.padding.left + result.boxModel.padding.right);
const h = Math.round(result.boxModel.content.height + result.boxModel.padding.top + result.boxModel.padding.bottom);
lines.push(`Dimensions: ${w} x ${h}`);
lines.push('');
// Box model
lines.push('Box Model:');
const bm = result.boxModel;
lines.push(` margin: ${Math.round(bm.margin.top)}px ${Math.round(bm.margin.right)}px ${Math.round(bm.margin.bottom)}px ${Math.round(bm.margin.left)}px`);
lines.push(` padding: ${Math.round(bm.padding.top)}px ${Math.round(bm.padding.right)}px ${Math.round(bm.padding.bottom)}px ${Math.round(bm.padding.left)}px`);
lines.push(` border: ${Math.round(bm.border.top)}px ${Math.round(bm.border.right)}px ${Math.round(bm.border.bottom)}px ${Math.round(bm.border.left)}px`);
lines.push(` content: ${Math.round(bm.content.width)} x ${Math.round(bm.content.height)}`);
lines.push('');
// Matched rules
const displayRules = options?.includeUA
? result.matchedRules
: result.matchedRules.filter(r => !r.userAgent);
lines.push(`Matched Rules (${displayRules.length}):`);
if (displayRules.length === 0) {
lines.push(' (none)');
} else {
for (const rule of displayRules) {
const propsStr = rule.properties
.filter(p => !p.overridden)
.map(p => `${p.name}: ${p.value}${p.important ? ' !important' : ''}`)
.join('; ');
if (!propsStr) continue;
const spec = `[${rule.specificity.a},${rule.specificity.b},${rule.specificity.c}]`;
lines.push(` ${rule.selector} { ${propsStr} }`);
lines.push(` -> ${rule.source}:${rule.sourceLine} ${spec}${rule.media ? ` @media ${rule.media}` : ''}`);
}
}
lines.push('');
// Inline styles
lines.push('Inline Styles:');
const inlineEntries = Object.entries(result.inlineStyles);
if (inlineEntries.length === 0) {
lines.push(' (none)');
} else {
const inlineStr = inlineEntries.map(([k, v]) => `${k}: ${v}`).join('; ');
lines.push(` ${inlineStr}`);
}
lines.push('');
// Computed styles (key properties, compact format)
lines.push('Computed (key):');
const cs = result.computedStyles;
const computedPairs: string[] = [];
for (const prop of KEY_CSS_PROPERTIES) {
if (cs[prop] !== undefined) {
computedPairs.push(`${prop}: ${cs[prop]}`);
}
}
// Group into lines of ~3 properties each
for (let i = 0; i < computedPairs.length; i += 3) {
const chunk = computedPairs.slice(i, i + 3);
lines.push(` ${chunk.join(' | ')}`);
}
// Pseudo-elements
if (result.pseudoElements.length > 0) {
lines.push('');
lines.push('Pseudo-elements:');
for (const pseudo of result.pseudoElements) {
for (const rule of pseudo.rules) {
lines.push(` ${pseudo.pseudo} ${rule.selector} { ${rule.properties} }`);
}
}
}
return lines.join('\n');
}
/**
* Detach CDP session for a page (or all pages).
*/
export function detachSession(page?: Page): void {
if (page) {
const session = cdpSessions.get(page);
if (session) {
try { session.detach().catch(() => {}); } catch {}
cdpSessions.delete(page);
initializedPages.delete(page);
}
}
// Note: WeakMap doesn't support iteration, so we can't detach all.
// Callers with specific pages should call this per-page.
}